feat: NAMS Phase 10a -- SearchMessagesAsync + payload edge-case live tests

Adds INamsClient.SearchMessagesAsync (confirmed live: POST /v1/conversations/{id}/search),
standalone -- deliberately not wired into the already-shipped RecallAsync pipeline.

Adds 4 payload edge-case live tests, each verified against real live behavior before writing
assertions: empty content (a genuine NAMS API inconsistency -- the bulk endpoint accepts what the
single-message endpoint rejects), large messages (50K chars accepted at write time; round-trip
tested at 5K to stay within our own recall character budget rather than measuring our own
truncation logic), multi-message single turn, and code-like content with special characters.

Author: joslat

docs/reviews/NAMS_Phase10a_SearchMessagesAndPayloadTests_PlanningAndImplementationPlan.md

@@ -0,0 +1,57 @@
+# NAMS Phase 10a — SearchMessagesAsync + Payload Edge-Case Tests — Planning and Implementation Plan
+
+**Prepared:** 2026-07-17
+**Branch:** `nams/phase10a-search-messages-and-payload-tests`
+**Purpose:** First increment of the follow-up Phase 10 work (10a-10d + a TCK Platinum research task), per the
+user's explicitly requested order: smallest/cleanest items first.
+
+## 1. `INamsClient.SearchMessagesAsync`
+
+Confirmed live: `POST /v1/conversations/{id}/search` with `{query, limit}`, returning
+`{messages: [...], searchType}` in exactly the existing `NamsMessage` shape (score/tokenCount present,
+conversationId absent -- matching the `recentMessages` context shape, not the bulk-add response shape).
+Phase 2 originally dropped this (`SearchMessagesAsync`) for lack of confirmation; added now, standalone.
+
+**Deliberately NOT wired into `INamsRecallService.RecallAsync`** -- that's Phase 4-6's already-shipped, live-
+tested, unit-tested behavior. Changing what automatic recall does is a separate decision from adding a new
+client capability, and isn't part of this increment's scope. A future MCP `nams_search_messages` tool (a
+natural Phase 8 follow-up, per the plan's own `search_messages` span name already anticipated in Phase 9) is
+also explicitly deferred, not built here.
+
+## 2. Payload edge-case live tests
+
+Added to `NamsLiveConnectivityTests.cs`. Live-verified each edge case's REAL behavior before writing the
+test's assertions, rather than assuming what "should" happen:
+
+- **Empty content** -- verified live that this is a genuine **NAMS API inconsistency**: the single-message
+  endpoint (`POST /v1/conversations/{id}/messages`) rejects empty content with 400, but the bulk endpoint
+  (`POST /v1/conversations/{id}/messages/bulk`) -- the *only* one `PersistTurnAsync` ever calls -- accepts it
+  and returns a real message ID. The test asserts the actual (accepted) behavior, not the wrong assumption
+  that empty content fails uniformly.
+- **Large message** -- verified live that NAMS's write path accepts at least 50,000 characters. For the
+  round-trip half of the test, deliberately used 5,000 characters (comfortably under
+  `NamsRecallOptions.MaxTotalCharacters`'s 8,000 default) after discovering the first version of this test
+  failed for an unrelated reason: a single item larger than the entire recall character budget is silently
+  excluded by `NamsRecallService`'s own `ApplyCharacterBudget` (correct, pre-existing, separately-tested
+  behavior) -- the test was accidentally measuring our own truncation logic, not NAMS's payload handling.
+- **Multi-message single turn** -- 2 user + 2 assistant messages in one `PersistTurnAsync` call; asserts all
+  4 come back with IDs from the one bulk request.
+- **Code-like content with special characters** (braces, quotes, escaped newlines, backticks) -- the plan's
+  "non-text" payload category, interpreted as structured/code-like text (there's no binary/attachment
+  concept anywhere in `NamsMessageToPersist`, so "non-text" can't mean literal binary).
+
+## 3. Verification
+
+- `dotnet build AgentMemory.slnx -c Release` -- 0 warnings, 0 errors.
+- `dotnet test tests/AgentMemory.Tests.Unit` -- full suite green, +1 new unit test (`SearchMessagesAsync`
+  client test) plus 5 test-fake updates (every `INamsClient` implementer needed the new method).
+- `dotnet test tests/AgentMemory.Tests.Integration --filter "...NamsLiveConnectivityTests"` -- **11/11 live**
+  (7 previous + 4 new), ~7s total, against the real NAMS SaaS.
+
+## 4. Definition of done
+
+- [x] `SearchMessagesAsync` added to `INamsClient`/`Neo4jNamsClientAdapter`, instrumented (Phase 9 metrics,
+      operation name `search_messages` matching the plan's own span-name anticipation), unit tested.
+- [x] 4 payload edge-case live tests added, each verified against real live behavior first.
+- [x] Full unit + live suites green.
+- [ ] Self-reviewed, PR opened, CI green, merged to `main`.

src/AgentMemory.Nams/Client/INamsClient.cs

@@ -43,4 +43,15 @@ Task<IReadOnlyList<NamsEntity>> SearchEntitiesAsync(
     /// health probe.
     /// </summary>
     Task<IReadOnlyList<NamsEntity>> ListEntitiesAsync(int limit, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Searches a conversation's own message history (<c>POST /v1/conversations/{id}/search</c>) --
+    /// confirmed live as part of the Phase 10 scenario-matrix expansion. Phase 2's original design dropped
+    /// this (as <c>SearchMessagesAsync</c>) for lack of confirmation at the time; it's added now, standalone,
+    /// deliberately NOT wired into <c>INamsRecallService.RecallAsync</c>'s already-shipped, tested Phase 4-6
+    /// behavior -- that would be a real behavior change to the automatic recall pipeline, a separate decision
+    /// from adding the client capability itself.
+    /// </summary>
+    Task<IReadOnlyList<NamsMessage>> SearchMessagesAsync(
+        string conversationId, string query, int limit, CancellationToken cancellationToken);
 }

src/AgentMemory.Nams/Client/Neo4jNamsClientAdapter.cs

@@ -97,6 +97,21 @@ public async Task<IReadOnlyList<NamsEntity>> ListEntitiesAsync(int limit, Cancel
         return response.Entities;
     }
 
+    public async Task<IReadOnlyList<NamsMessage>> SearchMessagesAsync(
+        string conversationId, string query, int limit, CancellationToken cancellationToken)
+    {
+        // A POST verb, but a pure read-only query with no server-side side effects -- same idempotent-for-
+        // retry-purposes treatment as SearchEntitiesAsync above.
+        var path = $"conversations/{Uri.EscapeDataString(conversationId)}/search";
+        var response = await InvokeAsync(
+            "search_messages",
+            () => BuildJsonRequest(HttpMethod.Post, path, new SearchMessagesRequestBody(query, limit)),
+            isIdempotent: true,
+            DeserializeAsync<SearchMessagesResponseBody>,
+            cancellationToken).ConfigureAwait(false);
+        return response.Messages;
+    }
+
     private async Task<T> InvokeAsync<T>(
         string operationName,
         Func<HttpRequestMessage> requestFactory,
@@ -184,4 +199,12 @@ private sealed record SearchEntitiesResponseBody(
 
     private sealed record ListEntitiesResponseBody(
         [property: JsonPropertyName("entities")] IReadOnlyList<NamsEntity> Entities);
+
+    private sealed record SearchMessagesRequestBody(
+        [property: JsonPropertyName("query")] string Query,
+        [property: JsonPropertyName("limit")] int Limit);
+
+    private sealed record SearchMessagesResponseBody(
+        [property: JsonPropertyName("messages")] IReadOnlyList<NamsMessage> Messages,
+        [property: JsonPropertyName("searchType")] string? SearchType);
 }

tests/AgentMemory.Tests.Integration/Nams/NamsLiveConnectivityTests.cs

@@ -218,6 +218,115 @@ await persistence.PersistTurnAsync(
         found.Should().BeTrue("Unicode/emoji content should round-trip through NAMS byte-for-byte in the recent-messages tier");
     }
 
+    // ── Phase 10: payload edge cases (empty / max size / multi-message / non-text-like) ─────────────
+
+    [LiveNamsFact]
+    public async Task PersistTurnAsync_EmptyContent_BulkEndpointAcceptsIt()
+    {
+        var services = _fixture.Services!;
+        var resolver = services.GetRequiredService<INamsConversationResolver>();
+        var persistence = services.GetRequiredService<INamsPersistenceService>();
+        var conversation = await resolver.ResolveAsync(UniqueIdentity(), CancellationToken.None);
+
+        // Genuine NAMS API inconsistency, confirmed live: the single-message endpoint
+        // (POST /v1/conversations/{id}/messages) rejects empty content with 400, but the bulk endpoint
+        // (POST /v1/conversations/{id}/messages/bulk) -- the ONLY one PersistTurnAsync ever calls --
+        // accepts it and returns a real message ID. Documenting actual behavior, not the (wrong) assumption
+        // that empty content fails uniformly across both NAMS endpoints.
+        var result = await persistence.PersistTurnAsync(
+            conversation.NamsConversationId, userMessages: [new NamsMessageToPersist("")], assistantMessages: [], CancellationToken.None);
+
+        result.Outcome.Should().Be(NamsPersistenceOutcome.Persisted);
+        result.PersistedMessageIds.Should().ContainSingle();
+    }
+
+    [LiveNamsFact]
+    public async Task PersistTurnAsync_LargeMessage_PersistsSuccessfully_AndEventuallyRoundTripsWithinTheDefaultRecallBudget()
+    {
+        var services = _fixture.Services!;
+        var resolver = services.GetRequiredService<INamsConversationResolver>();
+        var persistence = services.GetRequiredService<INamsPersistenceService>();
+        var recall = services.GetRequiredService<INamsRecallService>();
+        var conversation = await resolver.ResolveAsync(UniqueIdentity(), CancellationToken.None);
+
+        // Confirmed live: NAMS's write path accepts at least 50,000 characters in one message (separately
+        // verified, not asserted here to keep this test's own runtime reasonable). For the round-trip half
+        // of this test, deliberately use a size comfortably under NamsRecallOptions.MaxTotalCharacters'
+        // default (8,000) -- a single item larger than the whole budget is silently excluded by
+        // NamsRecallService's own ApplyCharacterBudget (correct, existing, separately-tested behavior), which
+        // would make this test measure our own truncation logic instead of NAMS's payload handling.
+        var marker = $"large-payload-{Guid.NewGuid():N} ";
+        var largeContent = marker + new string('x', 5_000);
+        var persistResult = await persistence.PersistTurnAsync(
+            conversation.NamsConversationId, userMessages: [new NamsMessageToPersist(largeContent)], assistantMessages: [], CancellationToken.None);
+
+        persistResult.Outcome.Should().Be(NamsPersistenceOutcome.Persisted);
+
+        var found = await PollUntilAsync(
+            async () =>
+            {
+                var recalled = await recall.RecallAsync(conversation.NamsConversationId, marker, CancellationToken.None);
+                return recalled.Items.Any(i =>
+                    i.Category == NamsRecallCategory.RecentMessage && i.Content.Contains(marker, StringComparison.Ordinal));
+            },
+            timeout: TimeSpan.FromSeconds(30));
+
+        found.Should().BeTrue("a 5,000-character message (within the default recall budget) should round-trip through NAMS");
+    }
+
+    [LiveNamsFact]
+    public async Task PersistTurnAsync_MultipleMessagesInOneTurn_PersistsAllInOrder()
+    {
+        var services = _fixture.Services!;
+        var resolver = services.GetRequiredService<INamsConversationResolver>();
+        var persistence = services.GetRequiredService<INamsPersistenceService>();
+        var conversation = await resolver.ResolveAsync(UniqueIdentity(), CancellationToken.None);
+
+        var id = Guid.NewGuid().ToString("N");
+        var result = await persistence.PersistTurnAsync(
+            conversation.NamsConversationId,
+            userMessages: [new NamsMessageToPersist($"user-1-{id}"), new NamsMessageToPersist($"user-2-{id}")],
+            assistantMessages: [new NamsMessageToPersist($"assistant-1-{id}"), new NamsMessageToPersist($"assistant-2-{id}")],
+            CancellationToken.None);
+
+        result.Outcome.Should().Be(NamsPersistenceOutcome.Persisted);
+        result.PersistedMessageIds.Should().HaveCount(4, "all 4 messages in the turn should be persisted in one bulk call");
+    }
+
+    [LiveNamsFact]
+    public async Task PersistTurnAsync_CodeLikeContentWithSpecialCharacters_EventuallyRoundTrips()
+    {
+        var services = _fixture.Services!;
+        var resolver = services.GetRequiredService<INamsConversationResolver>();
+        var persistence = services.GetRequiredService<INamsPersistenceService>();
+        var recall = services.GetRequiredService<INamsRecallService>();
+        var conversation = await resolver.ResolveAsync(UniqueIdentity(), CancellationToken.None);
+
+        // "Non-text" per the plan's payload matrix, interpreted as structured/code-like text content --
+        // NamsMessageToPersist.Content is a string; NAMS has no binary/attachment concept to test against.
+        var marker = Guid.NewGuid().ToString("N");
+        var codeContent = $$"""
+            marker: {{marker}}
+            ```csharp
+            var x = new Dictionary<string, string> { ["a"] = "b\n\tc" };
+            Console.WriteLine($"{x["a"]}");
+            ```
+            """;
+        await persistence.PersistTurnAsync(
+            conversation.NamsConversationId, userMessages: [new NamsMessageToPersist(codeContent)], assistantMessages: [], CancellationToken.None);
+
+        var found = await PollUntilAsync(
+            async () =>
+            {
+                var recalled = await recall.RecallAsync(conversation.NamsConversationId, marker, CancellationToken.None);
+                return recalled.Items.Any(i =>
+                    i.Category == NamsRecallCategory.RecentMessage && i.Content.Contains(marker, StringComparison.Ordinal));
+            },
+            timeout: TimeSpan.FromSeconds(30));
+
+        found.Should().BeTrue("code-like content with braces/quotes/newlines should round-trip through NAMS");
+    }
+
     private static NamsConversationIdentity UniqueIdentity([CallerMemberName] string testName = "") => new()
     {
         ApplicationId = "agent-memory-dotnet-live-tests",

tests/AgentMemory.Tests.Unit/Nams/NamsConversationResolverTests.cs

@@ -44,6 +44,10 @@ public Task<IReadOnlyList<NamsEntity>> SearchEntitiesAsync(
             string query, string? type, int limit, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
 
+        public Task<IReadOnlyList<NamsMessage>> SearchMessagesAsync(
+            string conversationId, string query, int limit, CancellationToken cancellationToken) =>
+            throw new NotSupportedException();
+
         public Task<IReadOnlyList<NamsEntity>> ListEntitiesAsync(int limit, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
     }

tests/AgentMemory.Tests.Unit/Nams/NamsHealthCheckTests.cs

@@ -33,6 +33,10 @@ public Task<IReadOnlyList<NamsEntity>> ListEntitiesAsync(int limit, Cancellation
             cancellationToken.ThrowIfCancellationRequested();
             return (OnListEntities ?? ((_, _) => Task.FromResult<IReadOnlyList<NamsEntity>>([])))(limit, cancellationToken);
         }
+
+        public Task<IReadOnlyList<NamsMessage>> SearchMessagesAsync(
+            string conversationId, string query, int limit, CancellationToken cancellationToken) =>
+            throw new NotSupportedException();
     }
 
     private static NamsOptions ValidOptions() => new() { Endpoint = new Uri("https://nams.test/v1/"), ApiKey = "nams_key" };

tests/AgentMemory.Tests.Unit/Nams/NamsObservabilityTests.cs

@@ -256,6 +256,10 @@ public Task<IReadOnlyList<NamsEntity>> SearchEntitiesAsync(
             string query, string? type, int limit, CancellationToken cancellationToken) =>
             Task.FromResult<IReadOnlyList<NamsEntity>>([]);
 
+        public Task<IReadOnlyList<NamsMessage>> SearchMessagesAsync(
+            string conversationId, string query, int limit, CancellationToken cancellationToken) =>
+            throw new NotSupportedException();
+
         public Task<IReadOnlyList<NamsEntity>> ListEntitiesAsync(int limit, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
     }

tests/AgentMemory.Tests.Unit/Nams/NamsPersistenceServiceTests.cs

@@ -36,6 +36,10 @@ public Task<IReadOnlyList<NamsEntity>> SearchEntitiesAsync(
             string query, string? type, int limit, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
 
+        public Task<IReadOnlyList<NamsMessage>> SearchMessagesAsync(
+            string conversationId, string query, int limit, CancellationToken cancellationToken) =>
+            throw new NotSupportedException();
+
         public Task<IReadOnlyList<NamsEntity>> ListEntitiesAsync(int limit, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
     }

tests/AgentMemory.Tests.Unit/Nams/NamsRecallServiceTests.cs

@@ -38,6 +38,10 @@ public Task<IReadOnlyList<NamsEntity>> SearchEntitiesAsync(
             return (OnSearchEntities ?? ((_, _, _) => Task.FromResult<IReadOnlyList<NamsEntity>>([])))(query, limit, cancellationToken);
         }
 
+        public Task<IReadOnlyList<NamsMessage>> SearchMessagesAsync(
+            string conversationId, string query, int limit, CancellationToken cancellationToken) =>
+            throw new NotSupportedException();
+
         public Task<IReadOnlyList<NamsEntity>> ListEntitiesAsync(int limit, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
     }

tests/AgentMemory.Tests.Unit/Nams/Neo4jNamsClientAdapterTests.cs

@@ -135,6 +135,25 @@ public async Task SearchEntitiesAsync_Success_UsesRetryDespitePostVerb()
         fake.Requests.Should().HaveCount(2); // search is a read despite the POST verb -- retries like other reads
     }
 
+    [Fact]
+    public async Task SearchMessagesAsync_Success_UsesRetryDespitePostVerb()
+    {
+        var fake = new FakeHttpMessageHandler(
+            () => new HttpResponseMessage(HttpStatusCode.ServiceUnavailable),
+            () => Json(HttpStatusCode.OK, """
+                {"messages":[{"id":"m1","content":"the quick brown fox","role":"user","score":0.8,"tokenCount":4}],"searchType":"vector"}
+                """));
+        var adapter = CreateAdapter(fake);
+
+        var messages = await adapter.SearchMessagesAsync("conv-1", "quick brown fox", 5, CancellationToken.None);
+
+        messages.Single().Content.Should().Be("the quick brown fox");
+        messages.Single().Score.Should().Be(0.8);
+        fake.Requests.Should().HaveCount(2); // search is a read despite the POST verb -- retries like other reads
+        var requestBody = await fake.Requests[1].Content!.ReadAsStringAsync();
+        requestBody.Should().Contain("\"query\":\"quick brown fox\"").And.Contain("\"limit\":5");
+    }
+
     [Fact]
     public async Task ListEntitiesAsync_Success_DeserializesEntities_NoQueryInRequest()
     {