Make Modern pagination collision-safe and pin the wire

Review found the paginator asserting a precondition that holds for one of
its four callers. Only Tool.Name is unique -- ResolveToolConflicts keys a
map -- while resources, resource templates and prompts are plain-appended
across backends under "no conflict resolution for these yet". With a bare
"resume strictly above lastKey" scan, a key shared at a page boundary made
the scan skip every copy, so an item appeared on no page at all. Two honest
backends both exposing file:///README.md was enough. A 1100-item corpus
delivered 1097.

The cursor now carries how many items sharing the last key were already
sent, so a page can resume inside a run of equal keys. Items sharing a key
are interchangeable for that purpose, which keeps the walk correct without
a secondary sort key the generic signature cannot see. The comment claiming
uniqueness is corrected rather than merged: it now states which callers can
collide and that the paginator does not rely on uniqueness.

The test corpus was the reason this shipped. Every case drew from a helper
minting strictly unique keys, so the one precondition the code called
load-bearing was the only thing untested. Collisions must also be placed by
SORTED position -- a distinctively named duplicate key sorts away from the
boundary and tests nothing, which a first attempt at the fixture did.

Cap an inbound cursor before decoding it. A well-formed 6MB cursor decoded
successfully at ~295ms of CPU on a verb that is not rate-limited, and a
legitimate cursor is tens of bytes.

Skip the capability fan-out in subscriptions/listen when nothing could be
honored. core.Discover is un-rate-limited and, while no push capability is
advertised, its result cannot change the answer -- so N no-op listens cost N
fan-outs, now worse since list verbs page. Probing the ceiling first makes
that O(1). This renders the fan-out error path unreachable, so its test is
removed rather than left asserting a branch the code cannot enter.

Assert the SSE framing. Replacing the blank-line event terminator with a
single newline previously left the whole suite green -- including against a
real client -- while a conformant parser would dispatch neither frame, so
the ack-then-result contract was unverifiable. The helper now parses
strictly, and the method name, acknowledgement name, subscriptionId key and
jsonrpc field are asserted as literals; mutating any of them was silent.

Add the negative capability test. The design rests on the advertisement
honoring nothing, which was enforced by no test at all -- only by a runtime
WARN that fires in production after the offending line ships. Now asserted
across all sixteen presence combinations.

Use http.ResponseController rather than a Flusher assertion: every
ResponseWriter wrapper in the chain defines Flush unconditionally, so the
assertion only established that a wrapper was present. Correct the comment
that claimed otherwise, and the one claiming headers were committed on all
four failure paths when three precede WriteHeader.

Log the honored set by count, not by client-supplied URIs.

Update docs/arch: subscriptions/listen is no longer unimplemented,
serverStreamRegistry is the seam for delivery rather than for the handler,
and both the pagination behaviour and the tools-only uniqueness property
are now recorded.

Refs #5959, #6033, #5743

Author: JAORMX

docs/arch/03-transport-architecture.md

@@ -677,20 +677,31 @@ path for server->client messages.
   send-on-closed-channel panic if a concurrent broadcast/dispatch races
   eviction/shutdown.
 
-**Forward-compatibility note**: the 2026-07-28 (Modern) MCP revision (see
-`mcp.MCPVersionModern` and `pkg/mcp/revision.go`) introduces
-`subscriptions/listen`, a POST method whose response stream stays open for
-server-pushed subscription events. `serverStreamRegistry` is a reasonable
-decoupled fan-out seam to build a future Modern handler for this method on top
-of, but it is **not** a drop-in reuse. Per the 2026-07-28 spec, real adaptation is
-required: `subscriptions/listen` is a long-lived POST, not a GET; Modern has no
-sessions, so streams must be keyed per-subscription-id rather than per session
-ID; delivery requires per-notification-type AND per-URI opt-in filtering, not
-blanket fan-out; an initial `notifications/subscriptions/acknowledged` must be
-sent; and deliveries must be tagged with `io.modelcontextprotocol/subscriptionId`.
-`dispatcher_streams.go` is intentionally kept transport-agnostic (no HTTP
-types) so that this adaptation, when it happens, does not also require
-rewriting the underlying fan-out primitives.
+**Relationship to Modern `subscriptions/listen`**: the 2026-07-28 (Modern)
+revision (see `mcp.MCPVersionModern` and `pkg/mcp/revision.go`) replaces the
+standalone GET with `subscriptions/listen`, a POST method whose response stream
+stays open for server-pushed subscription events.
+
+vMCP now **serves** that method on its client edge
+(`pkg/vmcp/server/modern_subscriptions.go`), and deliberately does **not** use
+`serverStreamRegistry`. The reason is that the handler honors no subscriptions:
+the honored set is intersected against the capabilities `server/discover`
+advertises, every push flag there is false, so the acknowledged set is always
+empty and the stream terminates immediately. With nothing to fan out, wiring in a
+fan-out registry from another package would add an abstraction with zero
+consumers. What the handler does implement is the wire contract — a long-lived
+POST rather than a GET, keyed per-subscription-id (the listen request's own
+JSON-RPC id) rather than per session ID since Modern has no sessions, an initial
+`notifications/subscriptions/acknowledged`, and
+`io.modelcontextprotocol/subscriptionId` tagging.
+
+`serverStreamRegistry` remains the sensible seam for the piece still missing:
+actual **delivery** of notifications on a Modern listen stream (#5743). That work
+needs per-notification-type AND per-URI opt-in filtering rather than blanket
+fan-out, and per `schema/draft/schema.ts` must tag *every* notification with the
+subscription id, not just the acknowledgement. `dispatcher_streams.go` is
+therefore still intentionally kept transport-agnostic (no HTTP types), so that
+when delivery lands it does not also require rewriting the fan-out primitives.
 
 ## Error Handling
 

docs/arch/10-virtual-mcp-architecture.md

@@ -136,6 +136,19 @@ When backends expose tools with the same name, vMCP resolves the conflict using
 | **priority** | First backend in priority order wins, others hidden |
 | **manual** | Explicit mapping for each conflict |
 
+**Conflict resolution covers tools only.** Resources, resource templates, and
+prompts are concatenated across backends with no de-duplication
+(`default_aggregator.go`, "no conflict resolution for these yet"), so
+`Resource.URI`, `ResourceTemplate.URITemplate` and `Prompt.Name` can each repeat
+in the aggregated view — two backends both exposing `file:///README.md` is
+enough. Only `Tool.Name` is unique, because tool resolution keys a map.
+
+Anything that treats one of those fields as an identity must account for that.
+The Modern list paginator does: its cursor names a position within a run of equal
+keys rather than assuming keys are distinct, because a plain "resume after this
+key" scan silently dropped an item whenever a duplicate landed on a page boundary
+(see [Client-facing list pagination](#client-facing-list-pagination)).
+
 ### Tool Filtering
 
 Beyond conflict resolution, vMCP can filter which tools are exposed through allow/deny lists, renaming, and description overrides.
@@ -300,14 +313,53 @@ Beyond tools, vMCP aggregates and serves the full complement of MCP capabilities
 | Resource templates (`resources/templates/list`) | Yes | Templated reads route through the same `ReadResource` path; the router matches an expanded URI against the aggregated templates, and an exact template-string key routes to its backend; covered by the same `notifications/resources/list_changed` propagation as resources (MCP 2025-11-25 has no separate wire method for template changes) |
 | Prompts (`prompts/list`, `prompts/get`) | Yes | Served per-session; a backend's asynchronous `notifications/prompts/list_changed` propagates ADDITIONS (not removals) to already-registered sessions — see below |
 | Completions (`completion/complete`) | Yes | A `ref/prompt` routes via the prompts table; a `ref/resource` carries the URI-template string per the spec and routes via the resource-templates table (exact template-string key, with exact-resource and template-expansion fallbacks). Unroutable refs return an empty result (lenient completion); admission denial returns an error |
-| Resource subscriptions (`resources/subscribe`, `resources/unsubscribe`) | Ack-level only | vMCP accepts and records the subscription (after session-binding and resource-admission checks) but does **not** yet forward backend `notifications/resources/updated` — see the limitation below |
+| Resource subscriptions (`resources/subscribe`, `resources/unsubscribe`) | Ack-level only | Legacy edge. vMCP accepts and records the subscription (after session-binding and resource-admission checks) but does **not** yet forward backend `notifications/resources/updated` — see the limitation below |
+| Subscriptions (`subscriptions/listen`) | Ack-level only | Modern (2026-07-28) edge, the revision's only server→client push channel. Answered with an SSE stream carrying the mandatory `notifications/subscriptions/acknowledged` and then a terminating result, both tagged `io.modelcontextprotocol/subscriptionId` and keyed by the listen request's JSON-RPC id (Modern has no sessions). The honored set is intersected against the advertised capabilities, all of whose push flags are false, so it is always **empty** and the stream closes immediately rather than idling. Serving it is what lets a go-sdk v1.7 client complete `Connect` at all — see below |
+
+The four Modern list verbs (`tools/list`, `resources/list`, `resources/templates/list`, `prompts/list`) **paginate**, emitting `nextCursor` while items remain and capping a page at 1000 items to match the page size the SDK applies on the Legacy path. See [Client-facing list pagination](#client-facing-list-pagination).
 
 The completion handler is a single global handler installed via `WithCompletionHandler`, so it recovers the session from the SDK request context rather than a per-session closure. Setting it makes the shim auto-advertise the `completions` capability at initialize.
 
 ### Subscription limitation (ack-level)
 
 vMCP advertises `resources.subscribe: true` and answers `resources/subscribe` / `resources/unsubscribe` at **ack level**: the request is accepted (enforcing session binding and validating the URI is an advertised, admitted resource), and go-sdk records the subscription. vMCP does **not** currently propagate backend `notifications/resources/updated` to the subscribed client — doing so requires persistent per-session backend connections, which is out of scope. Clients that subscribe will receive a success ack but no update stream yet.
 
+### Client-facing list pagination
+
+On the Legacy edge the SDK's session-scoped feature store splits list results into
+pages. `dispatchModern` bypasses the SDK, so the Modern edge paginates itself
+(`pkg/vmcp/server/modern_pagination.go`).
+
+Modern has no sessions, so a cursor may not denote server-held iteration state.
+The draft pagination page makes cursors **opaque to clients** ("MUST treat cursors
+as opaque tokens"), which is precisely what allows the server to encode position
+*into* the token instead of remembering it. So the cursor is self-describing:
+base64url over a small JSON payload naming the list kind, the last key delivered,
+and how many items sharing that key have already been sent.
+
+Three properties worth knowing:
+
+- **Ordering.** Keyset paging needs a deterministic total order, and the
+  aggregator's fan-out order is not stable between calls, so Modern list results
+  are sorted by the item's key (`Tool.Name`, `Resource.URI`,
+  `ResourceTemplate.URITemplate`, `Prompt.Name`). Legacy ordering is unchanged.
+- **Duplicate keys are tolerated, not assumed away.** Only tool names are unique
+  (see [Conflict Resolution](#conflict-resolution)); resource URIs, template
+  strings and prompt names can repeat. The cursor therefore resumes *within* a run
+  of equal keys, because a plain "resume after this key" scan skipped every copy
+  and permanently dropped items whose key collided at a page boundary.
+- **End of results omits `nextCursor` entirely.** The draft states that "an empty
+  string is a valid cursor and thus MUST NOT be treated as the end of results", so
+  emitting `""` would make a conformant client re-request and loop on page one.
+
+The cursor encodes a position in the **aggregated** ordering and never names a
+backend, so adding or removing a backend cannot invalidate one. This is unrelated
+to the aggregator's *upstream* cursor-following (#5851), which is vMCP acting as a
+client walking a backend's pages.
+
+An invalid cursor — malformed, over-length, or minted for a different list verb —
+is rejected with `-32602`, per the draft's error-handling rule.
+
 ### Tools/resources/prompts list_changed propagation (#5748, #5969)
 
 Unlike the per-call backend client (`pkg/vmcp/client`), the **persistent**
@@ -338,8 +390,17 @@ above for how that revision is resolved and cached. This is correct, not a gap i
 `initialize` and `Mcp-Session-Id`, so there is no Legacy-shaped persistent
 connection to hold and no standalone GET stream a Modern backend could push
 on. Modern's own server-push mechanism is `subscriptions/listen` (see
-[Transport Architecture](03-transport-architecture.md)), which vMCP does not
-implement yet — so `list_changed` propagation is currently Legacy-only.
+[Transport Architecture](03-transport-architecture.md)). vMCP **serves** that
+method on its client edge (`pkg/vmcp/server/modern_subscriptions.go`), but only
+at acknowledgement level: it computes the honored subscription set by
+intersecting the client's request against the capabilities `server/discover`
+advertises, and since every push-related flag there is deliberately false
+(`newModernCapabilities`), the honored set is always empty and no notification is
+ever pushed. So `list_changed` **delivery** remains Legacy-only, on both edges —
+what the Modern client edge gained is a conformant, explicitly-empty answer
+instead of a `-32601` that tore the client's connection down. Real Modern
+delivery is tracked in #5743 and requires vMCP to start advertising a push
+capability first.
 
 The sink is built once per session, at registration (`pkg/vmcp/server`'s
 `buildListChangedSink`), closing over the SDK `ClientSession`, the session ID,

pkg/vmcp/server/modern_dispatch_test.go

@@ -38,6 +38,13 @@ type modernFakeCore struct {
 
 	discoverCaps core.DiscoverCapabilities
 	discoverErr  error
+	// discoverCalls counts Discover invocations, so a test can assert the
+	// subscriptions/listen pre-check skipped the backend fan-out entirely (the
+	// response is identical either way, so only the count is observable).
+	discoverCalls int
+	// discoverIdentity records the identity Discover was called with, so
+	// per-identity filtering of a computed set can be pinned rather than assumed.
+	discoverIdentity *auth.Identity
 
 	checkToolErr, checkResourceErr, checkPromptErr error
 	callToolErr, readResourceErr, getPromptErr     error
@@ -73,7 +80,9 @@ func (f *modernFakeCore) ListPrompts(context.Context, *auth.Identity) ([]vmcp.Pr
 	return f.prompts, nil
 }
 
-func (f *modernFakeCore) Discover(context.Context, *auth.Identity) (core.DiscoverCapabilities, error) {
+func (f *modernFakeCore) Discover(_ context.Context, identity *auth.Identity) (core.DiscoverCapabilities, error) {
+	f.discoverCalls++
+	f.discoverIdentity = identity
 	return f.discoverCaps, f.discoverErr
 }
 

pkg/vmcp/server/modern_envelope.go

@@ -233,21 +233,10 @@ type modernDiscoverResult struct {
 	Meta              modernMeta             `json:"_meta"`
 }
 
-// newModernDiscover builds the server/discover wire result. hasTools/
-// hasResources/hasPrompts are the caller's len(core.List*(ctx, identity))>0
-// admission-filtered presence checks -- this function only shapes them into
-// the wire capability flags, so a discover response reflects exclusively
-// what this identity may reach, same as the four list results. hasTemplates
-// folds into the "resources" capability: the wire protocol has no separate
-// resource-templates capability flag.
-//
-// Completions is set unconditionally, unlike the three identity-filtered
-// flags above: completion/complete has no per-identity admission of its own
-// (core.Complete authorizes the underlying prompt/resource ref at dispatch,
-// not the completions feature itself), and this dispatcher serves it for
-// every caller once Modern dispatch is enabled at all -- matching how the
-// Legacy/SDK path always wires server.WithCompletionHandler regardless of
-// identity (serve.go).
+// newModernDiscover builds the server/discover wire result. The capability
+// flags themselves are shaped by newModernCapabilities below -- see its doc
+// comment for what each flag means and why the push-related ones are false.
+// This function only assembles the envelope around them.
 //
 // SupportedVersions enumerates every protocol version this vMCP endpoint
 // actually serves, not just Modern: mcpparser.MCPVersionModern (this
@@ -269,8 +258,22 @@ func newModernDiscover(
 }
 
 // newModernCapabilities shapes the four admission-filtered presence checks into
-// the wire capability flags. It is the SINGLE source of truth for what this
-// dispatcher advertises: server/discover publishes it verbatim (above), and
+// the wire capability flags.
+//
+// hasTools/hasResources/hasTemplates/hasPrompts are the caller's
+// len(core.List*(ctx, identity))>0 checks, so an advertisement reflects
+// exclusively what this identity may reach, same as the four list results.
+// hasTemplates folds into the "resources" capability: the wire protocol has no
+// separate resource-templates flag.
+//
+// Completions is set unconditionally, unlike the identity-filtered flags:
+// completion/complete has no per-identity admission of its own (core.Complete
+// authorizes the underlying prompt/resource ref at dispatch, not the completions
+// feature itself), and this dispatcher serves it for every caller -- matching how
+// the Legacy/SDK path always wires server.WithCompletionHandler regardless of
+// identity (serve.go).
+//
+// It is the SINGLE source of truth for what this dispatcher advertises: server/discover publishes it verbatim (above), and
 // subscriptions/listen intersects a client's requested notification set against
 // it (honoredSubscriptions, modern_subscriptions.go). Keeping one builder is
 // what makes those two answers impossible to drift apart -- a client can never
@@ -318,8 +321,12 @@ func newModernCapabilities(hasTools, hasResources, hasTemplates, hasPrompts bool
 
 // newModernToolsList builds the tools/list wire result from the core's
 // admission-filtered domain tools.
+// nextCursor is LAST on purpose: it sits among same-typed string parameters, and
+// when it was in the middle a transposition with serverName compiled silently and
+// put a server name in the cursor field. Keep new string params appended, not
+// inserted.
 func newModernToolsList(
-	tools []vmcp.Tool, nextCursor, serverName, serverVersion string,
+	tools []vmcp.Tool, serverName, serverVersion, nextCursor string,
 ) (modernToolsListResult, error) {
 	wireTools := make([]mcp.Tool, 0, len(tools))
 	for _, t := range tools {
@@ -341,7 +348,7 @@ func newModernToolsList(
 // newModernResourcesList builds the resources/list wire result from the
 // core's admission-filtered domain resources.
 func newModernResourcesList(
-	resources []vmcp.Resource, nextCursor, serverName, serverVersion string,
+	resources []vmcp.Resource, serverName, serverVersion, nextCursor string,
 ) modernResourcesListResult {
 	wireResources := make([]mcp.Resource, 0, len(resources))
 	for _, r := range resources {
@@ -359,7 +366,7 @@ func newModernResourcesList(
 // newModernResourceTemplatesList builds the resources/templates/list wire
 // result from the core's admission-filtered domain resource templates.
 func newModernResourceTemplatesList(
-	templates []vmcp.ResourceTemplate, nextCursor, serverName, serverVersion string,
+	templates []vmcp.ResourceTemplate, serverName, serverVersion, nextCursor string,
 ) modernResourceTemplatesListResult {
 	wireTemplates := make([]mcp.ResourceTemplate, 0, len(templates))
 	for _, t := range templates {
@@ -377,7 +384,7 @@ func newModernResourceTemplatesList(
 // newModernPromptsList builds the prompts/list wire result from the core's
 // admission-filtered domain prompts.
 func newModernPromptsList(
-	prompts []vmcp.Prompt, nextCursor, serverName, serverVersion string,
+	prompts []vmcp.Prompt, serverName, serverVersion, nextCursor string,
 ) modernPromptsListResult {
 	wirePrompts := make([]mcp.Prompt, 0, len(prompts))
 	for _, p := range prompts {

pkg/vmcp/server/modern_envelope_test.go

@@ -43,7 +43,7 @@ func TestModernEnvelopeCommonFields(t *testing.T) {
 					Name:        "greet",
 					Description: "say hi",
 					InputSchema: map[string]any{"type": "object"},
-				}}, "", testServerName, testServerVersion)
+				}}, testServerName, testServerVersion, "")
 				require.NoError(t, err)
 				return result
 			},
@@ -54,7 +54,7 @@ func TestModernEnvelopeCommonFields(t *testing.T) {
 			build: func(*testing.T) any {
 				return newModernResourcesList([]vmcp.Resource{
 					{Name: "info", URI: "embedded:info", MimeType: "text/plain"},
-				}, "", testServerName, testServerVersion)
+				}, testServerName, testServerVersion, "")
 			},
 			wantCacheable: true,
 		},
@@ -63,7 +63,7 @@ func TestModernEnvelopeCommonFields(t *testing.T) {
 			build: func(*testing.T) any {
 				return newModernResourceTemplatesList([]vmcp.ResourceTemplate{
 					{Name: "logs", URITemplate: "file:///logs/{date}.txt"},
-				}, "", testServerName, testServerVersion)
+				}, testServerName, testServerVersion, "")
 			},
 			wantCacheable: true,
 		},
@@ -72,7 +72,7 @@ func TestModernEnvelopeCommonFields(t *testing.T) {
 			build: func(*testing.T) any {
 				return newModernPromptsList([]vmcp.Prompt{
 					{Name: "code_review", Arguments: []vmcp.PromptArgument{{Name: "Code", Required: true}}},
-				}, "", testServerName, testServerVersion)
+				}, testServerName, testServerVersion, "")
 			},
 			wantCacheable: true,
 		},
@@ -328,27 +328,27 @@ func TestModernEnvelopeEmptyCollections(t *testing.T) {
 			field: "tools",
 			build: func(t *testing.T) any {
 				t.Helper()
-				result, err := newModernToolsList(nil, "", testServerName, testServerVersion)
+				result, err := newModernToolsList(nil, testServerName, testServerVersion, "")
 				require.NoError(t, err)
 				return result
 			},
 		},
 		{
 			name:  "resources/list",
 			field: "resources",
-			build: func(*testing.T) any { return newModernResourcesList(nil, "", testServerName, testServerVersion) },
+			build: func(*testing.T) any { return newModernResourcesList(nil, testServerName, testServerVersion, "") },
 		},
 		{
 			name:  "resources/templates/list",
 			field: "resourceTemplates",
 			build: func(*testing.T) any {
-				return newModernResourceTemplatesList(nil, "", testServerName, testServerVersion)
+				return newModernResourceTemplatesList(nil, testServerName, testServerVersion, "")
 			},
 		},
 		{
 			name:  "prompts/list",
 			field: "prompts",
-			build: func(*testing.T) any { return newModernPromptsList(nil, "", testServerName, testServerVersion) },
+			build: func(*testing.T) any { return newModernPromptsList(nil, testServerName, testServerVersion, "") },
 		},
 		{
 			name:  "tools/call content",