From df3f761e84ee736252de7a2a07c242728583a647 Mon Sep 17 00:00:00 2001
From: Ayla Croft <aylacroft@proton.me>
Date: Tue, 20 Oct 2026 04:26:03 -0400
Subject: [PATCH] Freeze readiness: nothing a shared contract may still move is
 frozen at 1.0.0

1.0.0 freezes this package's own call surface. This makes everything a
protocol revision, a shared encoding or a system beside this one may
still extend either open to growth or versioned, so 1.0.0 does not lock
it. Each change was red before its fix.

- Wire bytes. Every JSON value the transports write has its object keys
  in sorted order at every depth, through one internal writer
  (BeamMCP.JSON.encode!/2, not public). A refusal walks a client's
  arguments in sorted order too. Before, maps of more than 32 keys were
  written in hash order: one tools/list with a 40-property schema hashed
  e6d4e13e... on OTP 28.5.0.8 and 09fd2985... on OTP 29.1. Now both give
  40d948fc..., pinned on every leg.
- Request context (BREAKING, the host contract). Dispatch's third
  argument is the host's dispatch_opts plus a reserved :mcp key: the
  request's params._meta as sent, the client's capabilities and the
  revision the request is served under. One request's _meta never
  reaches the next. new/1 and the HTTP transport's init refuse a host's
  own :mcp.
- The resource_template node kind (BREAKING, the exported bytes). A
  resource template is a node of the declared connectome, identified by
  its uri template. Before, it was enumerated as unreadable. The
  canonical bytes move to schema_version 4 because their node vocabulary
  grew. The envelope's shape is unchanged, and bytes at 3 still verify:
  0.6.0 to 0.10.1's goldens are kept and checked under the new code.
- docs/api-stability.md, "What may grow, and how": a growth table marks
  every named atom-union type and struct field OPEN or CLOSED (all eight
  are OPEN), held by a census over the compiled types. The section also
  covers versioned encodings, the :mcp key, stable wire bytes, and
  callbacks added only as optional. BeamMCP.JSON.decode/1 leaves every
  error reason but its two named ones unspecified.
- Will-not-implement entry 13: no listChanged or subscribe is advertised
  while subscriptions/listen is not served; both are answered -32601, and
  404 over HTTP. Entry 12 now draws its line at input_required rather
  than "only complete".

Measured locally: the full gate on OTP 28.1.1 with Elixir 1.18.4 prints
"Gate OK"; the wire hashes agree on OTP 28.5.0.8 and 29.1. OTP 27 has
not been run locally; this pull request's CI is that measurement.

Signed-off-by: Ayla Croft <aylacroft@proton.me>
---
 CHANGELOG.md                                  |  69 +++++++
 README.md                                     |  11 +-
 docs/api-stability.md                         |  66 +++++-
 docs/connectome-canonical.md                  |  39 ++--
 docs/connectome.md                            |  12 +-
 docs/threat-model.md                          |   6 +-
 docs/will-not-implement.md                    |   7 +-
 lib/beam_mcp/connectome/declared.ex           |  27 ++-
 lib/beam_mcp/connectome/graph.ex              |   5 +-
 lib/beam_mcp/connectome/node.ex               |  17 +-
 lib/beam_mcp/cursor.ex                        |   2 +-
 lib/beam_mcp/json.ex                          |  43 +++-
 lib/beam_mcp/schema.ex                        |  19 +-
 lib/beam_mcp/server.ex                        |  88 +++++++-
 lib/beam_mcp/transport/http.ex                |  24 ++-
 lib/beam_mcp/transport/stdio.ex               |   4 +-
 livebooks/connectome.livemd                   |   2 +-
 livebooks/exports/fx.declared.json            |   2 +-
 livebooks/exports/fx.diff.json                |   2 +-
 livebooks/exports/fx.observed.json            |   2 +-
 livebooks/exports/fx.observed.sidecar.json    |   2 +-
 test/beam_mcp/boundary/no_mrtr_test.exs       |  26 ++-
 test/beam_mcp/boundary/package_reach_test.exs |   7 +-
 test/beam_mcp/connectome/canonical_test.exs   |  43 +++-
 test/beam_mcp/connectome/declared_test.exs    |  19 +-
 test/beam_mcp/connectome/graph_test.exs       |  11 +-
 test/beam_mcp/connectome/node_test.exs        |   3 +-
 test/beam_mcp/connectome/observed_test.exs    |   3 +-
 test/beam_mcp/connectome_vocabulary_test.exs  |  12 +-
 test/beam_mcp/growth_table_test.exs           |  99 +++++++++
 test/beam_mcp/readme_claims_test.exs          |  49 +++++
 test/beam_mcp/request_context_test.exs        | 195 ++++++++++++++++++
 test/beam_mcp/server_test.exs                 |   3 +-
 test/beam_mcp/threat_model_test.exs           |   8 +-
 test/beam_mcp/unserved_subscription_test.exs  | 103 +++++++++
 test/beam_mcp/wire_bytes_test.exs             | 146 +++++++++++++
 test/beam_mcp/wire_recording_test.exs         |   3 +-
 test/fixtures/connectome/golden.json          |   2 +-
 test/fixtures/connectome/golden.sha256        |   2 +-
 test/fixtures/connectome/golden.sha384        |   2 +-
 test/fixtures/connectome/golden.sha512        |   2 +-
 test/fixtures/connectome/golden.sidecar.json  |   2 +-
 test/fixtures/connectome/golden.v3.json       |   1 +
 .../connectome/golden.v3.json.license         |   2 +
 test/fixtures/connectome/golden.v3.sha256     |   1 +
 .../connectome/golden.v3.sha256.license       |   2 +
 46 files changed, 1072 insertions(+), 123 deletions(-)
 create mode 100644 test/beam_mcp/growth_table_test.exs
 create mode 100644 test/beam_mcp/request_context_test.exs
 create mode 100644 test/beam_mcp/unserved_subscription_test.exs
 create mode 100644 test/beam_mcp/wire_bytes_test.exs
 create mode 100644 test/fixtures/connectome/golden.v3.json
 create mode 100644 test/fixtures/connectome/golden.v3.json.license
 create mode 100644 test/fixtures/connectome/golden.v3.sha256
 create mode 100644 test/fixtures/connectome/golden.v3.sha256.license

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b46cbfb2..0c7df3fb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,75 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+### Changed (BREAKING, the host contract): the request's context reaches dispatch under `:mcp`
+
+- The host's dispatch function receives, in its third argument, its own `dispatch_opts`
+  followed by one reserved key, `:mcp`: a map of the request's `params._meta` as the client
+  sent it (string keys, `%{}` when it sent none), the client's capabilities (the request's own
+  in `_meta`, else what `initialize` declared; `nil` when there are none, or when they are not
+  an object), and the protocol revision the request is served under (the one its `_meta` names,
+  else `2025-11-25`). It is the client's word: authorise on the transport's hooks, not on it. Before, the core stripped `params._meta` before
+  `tools/call` was matched and kept no client capabilities, so a host could not see a trace id
+  or a capability the client declared. Fields added later join this map at a minor.
+  `BeamMCP.Server.new/1` refuses `dispatch_opts` carrying `:mcp`, and so does
+  `BeamMCP.Transport.HTTP` at init.
+  **How to tell whether you are affected:** your `dispatch_opts` has a key named `:mcp` (rename it); or your dispatch
+  function checks its third argument as a whole: matches it exactly (`fn _, _, [secret: s] ->`),
+  compares it (`opts == []`), or validates it against a closed key list (`Keyword.validate!/2`,
+  `NimbleOptions.validate!/2`, which now raise on `:mcp`): match or fetch the keys you read
+  (`Keyword.fetch!(opts, :secret)`); or you log or forward the whole of it, which now carries
+  the client's `_meta`: drop `:mcp` first (`Keyword.delete(opts, :mcp)`).
+
+### Changed (BREAKING, the exported bytes): `schema_version` 4 and the `resource_template` node kind
+
+- A resource template is a node of the declared connectome, of the new kind
+  `:resource_template`, identified by its uri template (`srv/resource_template/<template>`), in
+  a key space of its own. Before, every template a catalog offered was enumerated as an
+  unreadable catalog entry and had no node. The canonical bytes move to `schema_version` `4`
+  because their node vocabulary grew; the envelope's shape is unchanged, so a graph with no
+  template differs from its `3` bytes in the version alone, and bytes at `3` stay verifiable
+  by the same rule (`docs/connectome-canonical.md`, *Versions*).
+  **How to tell whether you are affected:** you verify or store the canonical bytes and pin `schema_version` `3`, or you
+  match a node's kind exhaustively (accept `4`, and `resource_template`); or you build a graph
+  with a literal `schema_version: 3` (`BeamMCP.Connectome.Graph.new/1` now refuses it, as it refused `2` in
+  0.6.0: pass `BeamMCP.Connectome.Graph.schema_version()`); or your catalog offers resource
+  templates and you read the bound's `unreadable_catalog_entries` (now empty) or track the
+  diff record's `declared_nodes` and `nodes_in_both` over time: both count one more per
+  template, while the diff record's own `schema_version` stays `3`, because its bytes carry
+  node ids and never a node's kind.
+
+### Changed: the wire's bytes are the same on every OTP release
+
+- Every JSON value the transports write has its object keys in sorted order at every depth,
+  the tool result written as text inside `content` included, and a refusal names the first
+  offending property, and lists unknown ones, in sorted order. A struct is written by its own
+  `Jason.Encoder`, as before; no struct reaches the wire from this package today. A map of more than 32 keys
+  iterates in hash order, and that order differs between OTP releases: one `tools/list` whose
+  schema had 40 properties was measured hashing differently on OTP 28.5.0.8 and OTP 29.1.
+  The content is unchanged; a client that compares decoded JSON sees nothing, and one that
+  hashes or caches the bytes now sees one answer per content.
+
+### Added: what may grow, and how (`docs/api-stability.md`)
+
+- A growth table marks every union of atoms in a public type OPEN (it may gain a value at a
+  minor, so code keeps a catch-all) or CLOSED; every one is OPEN today, and so is every value
+  set not in the table, error reasons included. It is held by a census over the compiled
+  types. The page also states that encodings a shared contract governs are versioned, not
+  frozen; that the request context grows inside `:mcp`; that the wire's bytes are stable in
+  1.x; and that a callback joins a behaviour only as optional.
+- `BeamMCP.JSON.decode/1` promises its two named error reasons and leaves every other reason
+  unspecified (it is the decoder's); its spec says `term()` where it said `struct()`.
+
+### Changed: the will-not-implement page gains entry 13, and entry 12 draws its line at `input_required`
+
+- Entry 13: the package never advertises a change notification it does not deliver: every
+  `listChanged` and `subscribe` flag is `false` while `subscriptions/listen` is not served,
+  and `subscriptions/listen` and `resources/subscribe` are answered `-32601` (`404` over HTTP).
+  Nothing a client sees changes; the rule is written down and held by a test.
+- Entry 12 now says the package never writes an `input_required` result, where it said the one
+  result type written is `complete`, so that another result type the specification defines
+  can be added without crossing the boundary.
+
 ### Changed: a request the HTTP adapter rejects is the adapter's to answer
 
 - An exception raised inside a call this transport makes into the adapter (reading the
diff --git a/README.md b/README.md
index 361d824c..36941dcb 100644
--- a/README.md
+++ b/README.md
@@ -152,6 +152,11 @@ does not advertise.
 @type dispatch :: (atom(), map(), keyword() -> {:ok, term()} | {:error, term()})
 ```
 
+The third argument is the host's own `dispatch_opts` plus one reserved key, `:mcp`: the
+request's context, `%{meta: ..., client_capabilities: ..., protocol_version: ...}`, where
+`meta` is the request's `params._meta` exactly as the client sent it. Fields added later join
+that map, so match the keys you read.
+
 ## Running it
 
 ```elixir
@@ -197,7 +202,7 @@ A `BeamMCP.ToolSpec` that omits `input_schema` is a tool with no arguments: it a
 empty object, so `tools/call` refuses nothing and dispatch is handed `%{}` whatever the client
 sent.
 
-Dispatch receives the declared properties only: a property outside `properties` is held to
+Dispatch's arguments are the declared properties only: a property outside `properties` is held to
 `additionalProperties` (refused when it is `false`, checked when it is a schema) and is not
 passed on.
 
@@ -577,7 +582,7 @@ cryptographic posture, and what a FIPS-mode host needs from it, are
 - **Declared**: `BeamMCP.Connectome.Declared.build/1` reads what *can* happen: the catalog,
   the call edges of the modules in scope from their beams (OTP's `:xref`), and a grouping of
   modules by OTP application. Beside the graph it returns a completeness bound: every dynamic
-  dispatch site, callee outside the scope and unreadable entry, enumerated rather than guessed.
+  dispatch site and callee outside the scope, enumerated rather than guessed.
 - **Observed**: `BeamMCP.Connectome.Observed` reads what *did* happen: a `:telemetry` span on
   the one dispatch site and a host-started ETS collector, plus an optional, off-by-default,
   guarded tracer for module-level edges (`BeamMCP.Connectome.Tracer`). Edge identity only:
@@ -662,7 +667,7 @@ there. A small surface can look unfinished from the outside; this one is a commo
 that says which it is. The list is derived, not typed: the thesis sentence at the top of this
 README, the census test that no line under `lib/` writes a sign other than `:unset`, and a
 test that no line under `lib/` names a receipt, an approval, a risk tier or egress. The full
-boundary (twelve entries, each with the test that enforces it by path and by name) is
+boundary (thirteen entries, each with the test that enforces it by path and by name) is
 [`docs/will-not-implement.md`](docs/will-not-implement.md), held to the tests in both
 directions by a census of its own; a request to cross it is answered by pointing there. What
 the package defends against on the wire, and what it hands to the server or the host, is
diff --git a/docs/api-stability.md b/docs/api-stability.md
index 0a7a5c03..6774b464 100644
--- a/docs/api-stability.md
+++ b/docs/api-stability.md
@@ -70,7 +70,7 @@ and metadata (`docs/connectome-observed.md`); and the tracer's exit reasons, doc
 fields of the public structs and the shapes behind the `@type`s and `@spec`s. A field renamed
 or a return shape changed leaves `Module kind name/arity` untouched, so the census does not see
 it; such a change is a break like any other and is a reviewer's line and a CHANGELOG entry,
-not a census failure. **Not promised anywhere:** the shape of `inspect/1` output, the text of
+not a census failure, unless it is growth that *What may grow, and how*, below, allows. **Not promised anywhere:** the shape of `inspect/1` output, the text of
 log lines and error messages, the names of the tracer's processes and trace session, and the
 layout of the observed collector's ETS rows beyond the `row/0` type
 `BeamMCP.Connectome.Observed` documents.
@@ -96,6 +96,70 @@ and deprecates; a patch fixes. `1.0.0` follows once the public API and the state
 have each survived a full minor release unchanged (the README's condition, and the only one
 stated); `UPGRADING.md` carries what a `0.x` consumer must do to reach it.
 
+## What may grow, and how
+
+1.0.0 freezes this package's own call surface. It does not freeze a value set that the
+protocol, a shared contract (the canonical bytes, the signature schemes, the digest names) or a
+system built beside this one may still extend. Five rules say how each kind of thing grows.
+
+**Value sets: open by default.** Every named type, and every public struct field, whose
+definition is a union of atoms is listed below, OPEN or CLOSED. An OPEN set may gain a value at a minor release: code that matches on it keeps
+a catch-all clause, and a value it does not know is not an error. A CLOSED set changes only at
+a major. Every value set not in the table, an atom nested in a list, a tuple or an error reason
+included, is OPEN. Every error reason a function returns is OPEN in particular, and
+`BeamMCP.JSON.decode/1` promises the two reasons it names (`{:nesting, depth, max}`,
+`{:duplicate_key, key}`) and nothing about any other: which decoder produced it, and in which
+shape, is unspecified. The table is held by `test/beam_mcp/growth_table_test.exs` "every atom
+union in a public type has exactly one row, with its atoms and OPEN or CLOSED", which reads the
+compiled types, so a union that grows, shrinks or appears without its row fails.
+
+| Type | Values | Growth |
+| -- | -- | -- |
+| `t:BeamMCP.Connectome.Node.kind/0` | `:server` `:tool` `:resource` `:resource_template` `:prompt` `:process` `:module` | OPEN |
+| `t:BeamMCP.Connectome.Node.level/0` | `:mfa` `:module` `:boundary` `:server` | OPEN |
+| `t:BeamMCP.Connectome.Edge.kind/0` | `:invoke` `:read` `:message` `:supervise` | OPEN |
+| `t:BeamMCP.Connectome.Edge.provenance/0` | `:declared` `:observed` | OPEN |
+| `t:BeamMCP.Connectome.Edge.sign/0` | `:allow` `:deny` `:hold` `:ungoverned` `:unset` | OPEN |
+| `t:BeamMCP.Connectome.Canonical.algorithm/0` | `:sha256` `:sha384` `:sha512` | OPEN |
+| `t:BeamMCP.Connectome.Canonical.scheme/0` | `:ed25519` `:ecdsa_p384_sha384` `:mldsa87` | OPEN |
+| `t:BeamMCP.ToolSpec.t/0` field `mode` | `:read_only` `:proposal` | OPEN |
+
+None is CLOSED today. A set is CLOSED only when it is this package's alone and a consumer's
+exhaustive match on it is the point; the column exists so that such a set can say so.
+
+**Encodings: versioned, not frozen.** An encoding a shared contract governs carries its
+`schema_version` inside the bytes. It changes only as a new version at a minor, and bytes at an
+older version are never rewritten and keep verifying by their own version's rule. The canonical
+connectome bytes are the first: `4` since the node vocabulary gained `resource_template`, with
+the bytes `0.6.0` to `0.10.1` wrote at `3` kept as goldens and verified under the code that
+writes `4` (`test/beam_mcp/connectome/canonical_test.exs` "versioned, not frozen: bytes at 3
+still verify under the code that writes 4"; `docs/connectome-canonical.md`, *Versions*). In
+`0.x` such a version is a documented break, like every break. From `1.0.0` it is the one change
+a minor may make to bytes a consumer pins: the alternative is freezing a contract other systems
+share. It ships with a CHANGELOG heading naming the new version and a "how to tell" sentence;
+the old version's bytes keep verifying; and code that builds the structure passes the version
+the package exports (`BeamMCP.Connectome.Graph.schema_version/0`), never a literal, which a
+new version refuses.
+
+**Request context: one reserved key.** What a request carries beyond its arguments reaches the
+host's dispatch under the `:mcp` key of its third argument (the request's `params._meta`, the
+client's capabilities, the revision served; `BeamMCP.Server` `t:dispatch/0`). A later field,
+the next protocol addition that rides in `_meta`, joins that map at a minor, never as a new
+function or a new argument; a host matches the keys it reads.
+
+**Wire bytes: stable in 1.x.** Every JSON value the transports write has its object keys in
+sorted order at every depth (a struct is written by its own `Jason.Encoder`), and a refusal
+walks a client's arguments in sorted order too, so a response's bytes are a function of its
+content and not of the OTP release's map iteration order (`test/beam_mcp/wire_bytes_test.exs` pins one sha256 per
+response on every CI leg). Field values are the protocol's; a field the protocol adds is an
+addition to the bytes, not a break.
+
+**Behaviours: callbacks are added optional.** A callback joins `BeamMCP.Catalog` or
+`BeamMCP.Server` at a minor only under `@optional_callbacks`, never as required: a module
+written against the earlier behaviour keeps compiling without a warning. `BeamMCP.Signer` is the
+one exception by design: its single callback is a boundary (will-not-implement entry 3), held
+exactly by `test/beam_mcp/boundary/no_signature_test.exs`, and it does not grow.
+
 ## Deprecation: three steps, three minors
 
 A public entry that is going to leave goes in three steps, each on the record:
diff --git a/docs/connectome-canonical.md b/docs/connectome-canonical.md
index 00b76c62..ce5d2da1 100644
--- a/docs/connectome-canonical.md
+++ b/docs/connectome-canonical.md
@@ -22,7 +22,7 @@ The bytes are UTF-8 JSON with no insignificant whitespace, written under these r
 1. **The top level is an object with exactly four members, in this fixed order:**
    `"schema_version"`, then `"algorithm"`, then `"nodes"`, then `"edges"`. This is the one
    place the order is fixed rather than sorted, so the version is the first thing a reader
-   meets and the digest the second. The schema version is the integer `3` (see *Versions*
+   meets and the digest the second. The schema version is the integer `4` (see *Versions*
    below). The algorithm is one of the three strings `"sha256"`, `"sha384"`, `"sha512"`
    (the name under which the digest is known to `:crypto`, lowercase, no hyphen), and it is
    what rule 9 hashes the bytes with. **The nodes and edges members do not depend on the
@@ -108,10 +108,10 @@ A server `"s"` with one tool `"t"` (labelled `mode: :read_only`) and the one dec
 from the server to the tool. Its canonical bytes under the default algorithm, on one line:
 
 ```json-canonical
-{"schema_version":3,"algorithm":"sha256","nodes":[{"id":"s/server","kind":"server","labels":{},"level":"server"},{"id":"s/tool/t","kind":"tool","labels":{"mode":"read_only"},"level":"server"}],"edges":[{"from":"s/server","kind":"invoke","provenance":"declared","sign":"unset","to":"s/tool/t"}]}
+{"schema_version":4,"algorithm":"sha256","nodes":[{"id":"s/server","kind":"server","labels":{},"level":"server"},{"id":"s/tool/t","kind":"tool","labels":{"mode":"read_only"},"level":"server"}],"edges":[{"from":"s/server","kind":"invoke","provenance":"declared","sign":"unset","to":"s/tool/t"}]}
 ```
 
-sha256: `a401cd47f0f0410d17248538eb8a3ef00018f6a31bf6fb6a7b9b0ba3377f570e`
+sha256: `b27e00414811cf71a818af1ee6f4be7d779432c34e052477614ec2a2431a320a`
 
 Reproduce it without the package: paste the line above into a file with no trailing newline
 and run `sha256sum` over it, or `printf '%s' '<the line>' | sha256sum`.
@@ -120,15 +120,15 @@ The same graph under SHA-384 is a different envelope (one member differs) and so
 different hash, over the bytes that name it:
 
 ```json-canonical-sha384
-{"schema_version":3,"algorithm":"sha384","nodes":[{"id":"s/server","kind":"server","labels":{},"level":"server"},{"id":"s/tool/t","kind":"tool","labels":{"mode":"read_only"},"level":"server"}],"edges":[{"from":"s/server","kind":"invoke","provenance":"declared","sign":"unset","to":"s/tool/t"}]}
+{"schema_version":4,"algorithm":"sha384","nodes":[{"id":"s/server","kind":"server","labels":{},"level":"server"},{"id":"s/tool/t","kind":"tool","labels":{"mode":"read_only"},"level":"server"}],"edges":[{"from":"s/server","kind":"invoke","provenance":"declared","sign":"unset","to":"s/tool/t"}]}
 ```
 
-sha384: `f5b9b2f4fe21a4bfe88721d804f4f82d167f73f7dd59b1a64ae0196f4cf78f05a6b9a3efa6d02e7362469796dbba53dd`
+sha384: `0055fe763dfad9c2aea0de1ebb233da8a62ae592134a5c6376fa37ceae4ca612024b3eb1ce08db29b4f5fe37f234ee15`
 
 (`sha384sum` over that line.) Under SHA-512 the member reads `"algorithm":"sha512"` and the
 rest of the line is byte-identical:
 
-sha512: `26cacb025eeaeabb0c441a293882ab81ec2436b80559618fd700dc494f9a5d2e2c6d46cee69a68cbdc84746aa9d64a4a11da027df7b0bc733ba1091031ee2e78`
+sha512: `1095ab691c82759659e20d9850b27244f9b50ccaf0e87df3dd8f42573e3ce4d354937189a19ec264607a1b82d90273e40ba1daa53db6d93af35d1c6fc20d73b8`
 
 A blind reader reproduces all three from this page alone: rule 1 fixes the four members and
 their order, rule 9 the digest by the member's value, and the line is the same in every
@@ -148,6 +148,13 @@ at an edge and found nothing governing it had no `ungoverned` to write, so its h
 was `unknown` too, and the bytes do not say which case a given `unknown` was. A reader must
 not narrow a version-1 `unknown` to `unset`; it is "one of the two, unrecorded which".
 
+**`4`** (the release after 0.10.1): the node kind `resource_template` joins the vocabulary, a
+resource template named by its uri template in a key space of its own; the envelope's shape is
+`3`'s, unchanged, so the only byte that differs for a graph with no template is the version
+itself. That is the rule this page keeps for every shared encoding: it grows by a new version
+at a minor, and bytes at an older version stay what they were and verify by their own
+version's rule (`docs/api-stability.md`, *Versioned, not frozen*).
+
 **What a verifier holding bytes at `1` or `2` does**: 0.4.0 and 0.5.0 bytes exist in the
 world, and their hashes stay verifiable forever under their own version: those bytes name no
 algorithm, and **at `1` and `2` the digest is SHA-256**, by this rule and by no member of the
@@ -155,26 +162,28 @@ bytes; the verifier hashes the bytes it holds, unchanged, with SHA-256, and comp
 not add an `"algorithm"` member, rewrite the version, or re-encode: a `2` envelope with a
 member inserted is different bytes with a different hash, not a migration. At `3` the
 verifier reads the member and hashes with what it names; a `3` envelope without the member,
-or a `1` or `2` envelope with one, is a malformed record and is refused. So the whole
-verifier is: read `schema_version`; below `3`, SHA-256; at `3`, the named digest; anything
-else, refuse. Published 0.4.0 and 0.5.0 hashes verify under that rule exactly as they did the
+or a `1` or `2` envelope with one, is a malformed record and is refused. At `4` the rule is
+`3`'s. So the whole verifier is: read `schema_version`; below `3`, SHA-256; at `3` or `4`,
+the named digest; anything else, refuse. Published 0.4.0 and 0.5.0 hashes verify under that rule exactly as they did the
 day they were written.
 
 What the version tells the verifier beyond the digest is how to *read* the sign field: at
-`1`, `unknown` is a valid sign and `ungoverned` is not; at `2` and `3`, `unset` and
+`1`, `unknown` is a valid sign and `ungoverned` is not; at `2`, `3` and `4`, `unset` and
 `ungoverned` are valid and `unknown` is not. A reader that resolves the vocabulary by the
 version it finds first (as Avro resolves a writer's schema against a reader's) needs no other
 signal. A sign outside the vocabulary of the version the bytes name is a malformed record:
 the hash still verifies (it is over the bytes), and the record is refused, never corrected:
-the rule the package applies to itself in `BeamMCP.Connectome.Graph.new/1`. The package itself
-writes `3` and only `3`, and `BeamMCP.Connectome.Graph.new/1` refuses a graph carrying any
+the rule the package applies to itself in `BeamMCP.Connectome.Graph.new/1`. The same holds for
+node kinds: `resource_template` is valid at `4` and not below it. The package itself
+writes `4` and only `4`, and `BeamMCP.Connectome.Graph.new/1` refuses a graph carrying any
 other version rather than translating it: bytes are not re-imported here, only produced and
-hashed. `test/fixtures/connectome/golden.v2.json` and `golden.v2.sha256` are 0.5.0's goldens
-kept as they were, and a test verifies them the way this section says.
+hashed. `test/fixtures/connectome/golden.v2.json` and `golden.v2.sha256` are 0.5.0's goldens,
+and `golden.v3.json` and `golden.v3.sha256` the goldens 0.6.0 to 0.10.1 wrote, kept as they
+were, and a test verifies them the way this section says.
 
 ## The sidecar
 
-Weights are written separately as `{"schema_version":3,"weights":[…]}` (the graph's version, no algorithm member, since the sidecar is never hashed), one object per edge
+Weights are written separately as `{"schema_version":4,"weights":[…]}` (the graph's version, no algorithm member, since the sidecar is never hashed), one object per edge
 that carries a weight, each with `"from"`, `"kind"`, `"provenance"`, `"to"`, `"weight"` in
 that order, the array sorted as in rule 3, the same string rules. An integer weight is an
 integer; a float weight is written in the shortest form that round-trips
diff --git a/docs/connectome.md b/docs/connectome.md
index 38918c2d..091e8225 100644
--- a/docs/connectome.md
+++ b/docs/connectome.md
@@ -28,8 +28,8 @@ is claimed.
 
 - A **connectome** is the graph itself: nodes and edges, each edge carrying a kind, a sign and a
   provenance.
-- The **declared connectome** is built from what is declared: the catalog's tools, resources and
-  prompts, the static call graph between the host's modules, and the host's boundary declarations.
+- The **declared connectome** is built from what is declared: the catalog's tools, resources,
+  resource templates and prompts, the static call graph between the host's modules, and the host's boundary declarations.
   It says what *can* happen.
 - The **observed connectome** is built from what ran: telemetry on the dispatch path and, when the
   host opts in, a guarded tracer. It records edge identity only, never arguments, results or
@@ -50,7 +50,8 @@ is claimed.
 | -- | -- |
 | `:server` | the MCP server: the thing whose catalog is advertised |
 | `:tool` | a tool the catalog names; labelled with its `command_class` and `mode` |
-| `:resource` | a resource the catalog names |
+| `:resource` | a resource the catalog names, identified by its uri |
+| `:resource_template` | a resource template the catalog names, identified by its uri template (a key space of its own: a template and a resource never share an id); in the vocabulary from `schema_version` `4` |
 | `:prompt` | a prompt the catalog names |
 | `:process` | a BEAM process: a GenServer, a task, a supervisor |
 | `:module` | a BEAM module, at the module level, or a module–function–arity at the finest level |
@@ -94,7 +95,7 @@ edge, where that verdict never reached this package, gets `:unset` on that edge,
 that read `:unset` as "no policy spoke" would be wrong about the world. That is why the value is
 named for the slot's state and not for the world's. (Until 0.5.0 the value was `:unknown`,
 glossed "no policy has spoken"; the rename is the correction, and the bytes carry
-`schema_version` `2` or later from here (`3` today), so a reader knows which vocabulary applies:
+`schema_version` `2` or later from here (`4` today), so a reader knows which vocabulary applies:
 [`docs/connectome-canonical.md`](connectome-canonical.md).)
 
 There is no `:not_applicable` and no `:indeterminate`: nothing in the package can produce them,
@@ -133,7 +134,7 @@ the part within it.
 | identity | node |
 | -- | -- |
 | `{:server, server}` | the server itself |
-| `{:tool, server, name}` · `{:resource, server, name}` · `{:prompt, server, name}` · `{:process, server, name}` | a catalog part or a process, named within the server |
+| `{:tool, server, name}` · `{:resource, server, uri}` · `{:resource_template, server, uri_template}` · `{:prompt, server, name}` · `{:process, server, name}` | a catalog part or a process, named within the server |
 | `{:module, server, module}` | a module, at the `:module` level |
 | `{:module, server, {module, function, arity}}` | one function, at the `:mfa` level |
 | `{:boundary, server, source, name}` | a group of modules, at the `:boundary` level, with the source of the grouping named |
@@ -168,6 +169,7 @@ the canonical form, not by the id.
 | `{:server, "srv"}` | `srv/server` |
 | `{:tool, "srv", "écho"}` | `srv/tool/écho` |
 | `{:resource, "srv", "r://a"}` | `srv/resource/r:%2F%2Fa` |
+| `{:resource_template, "srv", "r://t/{x}"}` | `srv/resource_template/r:%2F%2Ft%2F{x}` |
 | `{:prompt, "a/b", "p%"}` | `a%2Fb/prompt/p%25` |
 | `{:process, "srv", :worker}` | `srv/process/worker` |
 | `{:module, "srv", Foo.Bar}` | `srv/module/Foo.Bar` |
diff --git a/docs/threat-model.md b/docs/threat-model.md
index c12223c3..2e28e777 100644
--- a/docs/threat-model.md
+++ b/docs/threat-model.md
@@ -91,7 +91,11 @@ tool, and the client that chose to feed its result to a model, own that vector b
 the tool then does (the effect in the world, the privilege it uses) is the host's, and the
 connectome exists to make that inspectable (which effects a catalog can reach, and which paths
 cross a gate), not to decide it. The sign an edge carries is a consumer's; this package writes
-only `:unset` and never treats any sign as suppression.
+only `:unset` and never treats any sign as suppression. With the call, dispatch receives the request's
+context under `:mcp`: the request's `params._meta` as the client sent it and the capabilities
+the client declares. Both are the client's word, unvalidated beyond their JSON shape: a host
+authorises on its own evidence (the transport's `authorize` and `authorize_body` hooks), never
+on a tenant, a role or a capability read from `meta`.
 
 **Authority.** The verdict on an edge, the key that would sign a finding, the decision that
 acts on one: absent by decision (`docs/will-not-implement.md`, entries 1–4). A threat model for
diff --git a/docs/will-not-implement.md b/docs/will-not-implement.md
index 6c6115fa..3f8329de 100644
--- a/docs/will-not-implement.md
+++ b/docs/will-not-implement.md
@@ -10,7 +10,7 @@ entry below is something `beam_mcp` will never do, with the reason in a line and
 enforces it, by path and by name. **The tests are the proof; this page is the contract.** A
 request to cross one of these lines is a request for a different package: the *host* (the
 application that embeds this package, supplies its catalog and dispatch function, and owns
-every decision about them) for entries 1, 4, 7, 11 and 12; a *signer* (a module behind the
+every decision about them) for entries 1, 4, 7, 11, 12 and 13; a *signer* (a module behind the
 one callback `BeamMCP.Signer` names; the reference one is in the separate package
 `beam_mcp_signer`, Ed25519 through OTP's `:crypto`, the key under `opts[:private_key]`)
 for entries 2 and 3; a
@@ -114,13 +114,14 @@ The core itself is unchanged by the seam: entry 12's two tests hold as they stoo
 | 3 | **make a signature of its own.** No signing or MAC primitive is called under `lib/`, and no key is held. The one `sign/2` defined there is `BeamMCP.Signer.None`, a no-op answering `{:error, :no_signer}`; the one call of a signer is `BeamMCP.Connectome.Canonical.signature/3`, which hands the canonical bytes to a host-supplied module implementing `BeamMCP.Signer` (exactly one callback, `sign(canonical_bytes, opts)`, two arguments with those names), and places what comes back beside them. The key and the primitive are in the separate package `beam_mcp_signer` (Ed25519 through OTP's `:crypto`, the key under `opts[:private_key]`), which a host attaches; this package does not depend on it. | Signing bytes publishes nothing about who decides what; a richer callback would, so the census pins the shape and any widening is a visible act. The `sign` field an edge carries is the host's verdict slot (entry 1), a value and not an act. | `test/beam_mcp/boundary/no_signature_test.exs` "no line under lib/ calls a signing or MAC primitive" "exactly one `def sign` under lib/: the no-op, spelled as pinned, in its own file" "the behaviour has exactly one callback, sign/2, with the pinned argument names and return" "exactly one call of a signer under lib/: signature/3's, over encode/2's bytes"; `test/beam_mcp/boundary/package_reach_test.exs` "the modules the package calls are exactly the listed ones" |
 | 4 | **decide authority.** It writes no verdict (entry 1: the sign slot is only ever `:unset`) and names no receipt (a signed record that a call happened), no approval (a decision that a call may proceed), no risk tier (a ranking of calls by consequence), no egress and no mask (the withholding or rewriting of what leaves the system): any word containing *receipt*, *approv*, *egress*, *tier* or *mask* (a "frontier" in prose would trip it, loudly, and be read). | Every one of these is a decision about the host's tools, and the package holds none of them; the moment it held one, its topology could be mistaken for a verdict. The words "verdict" and "authority" are not barred: under `lib/` they name the host's slot in the edge's docs and the diff's own class, *dead authority*. They are terms the package defines, not acts it performs. The acts are barred in the spellings code uses as well as prose. | `test/beam_mcp/boundary/no_authority_test.exs` "no line under lib/ names a receipt, an approval, a risk tier, egress or a mask, in any spelling"; `test/beam_mcp/connectome/census_test.exs` "no code line under lib/ writes or names a sign other than :unset"; `test/beam_mcp/readme_claims_test.exs` "deliberately out: no line under lib/ names a receipt, an approval, a risk tier or egress" |
 | 5 | **put a payload byte into the observed graph.** Edge identity only: never an argument, a result, a header, an error message or a stack frame's contents. | A wiring diagram that carries payloads is a log, and a log of tool calls is the most sensitive artefact a host produces. The observed graph is safe to export because it cannot contain what was said. | `test/beam_mcp/connectome/observed_test.exs` "a marker in a nested argument map and in a uri argument is absent from rows, bytes, sidecar and latency" "a marker in the error a dispatch returns is absent" "a marker in an exception a dispatch raises is absent, and the edge was still recorded" "the :stop event itself carries no argument, result or header bytes" "dispatch_opts never enter: a secret handed to every dispatch is in no row, byte or summary" "request headers carrying the marker reach neither the events nor the rows" "a throw and an exit from the dispatch are exceptions of their kind, with marker-free frames; a crafted error_info is dropped from the frames"; `test/beam_mcp/connectome/tracer_test.exs` "a registered name is identity: a secret in a name is published in the bytes, the message beside it is not"; `test/beam_mcp/connectome/diff_test.exs` "an observed graph the collector built from a call carrying a marker diffs to bytes with no marker"; `test/beam_mcp/readme_claims_test.exs` "the observed graph carries edge identity only, never a payload byte" |
-| 6 | **claim an MCP capability the specification does not define.** No topology or reachability capability on the wire; `connectome://` is the package's own URI scheme, not a claimed capability. | Capabilities are negotiated with clients that read the specification, not this README. An invented key is a promise no client can act on. The advertised keys are held to `ServerCapabilities` as each revision's schema defines it: a copy of the two key sets taken from the schema files on 2026-09-15 and cited in the test (`tasks` in 2025-11-25; `extensions` in 2026-07-28). The entry bars keys the specification does not define, at the top level and one level under each capability whose sub-keys the schema names (`tools`: `listChanged`, the only capability advertised today; `resources`, `prompts` and `tasks` are held the day they are advertised; `completions`, `logging`, `experimental` and `extensions` are open objects and nothing is read under them; a third level is not read); a key it does define and this package does not implement is a different question, answered by the README. | `test/beam_mcp/boundary/no_invented_capability_test.exs` "server/discover advertises only keys the 2026-07-28 schema defines" "the initialize result advertises only keys the 2025-11-25 schema defines" "no line under lib/ names a topology or reachability capability on the wire" |
+| 6 | **claim an MCP capability the specification does not define.** No topology or reachability capability on the wire; `connectome://` is the package's own URI scheme, not a claimed capability. | Capabilities are negotiated with clients that read the specification, not this README. An invented key is a promise no client can act on. The advertised keys are held to `ServerCapabilities` as each revision's schema defines it: a copy of the two key sets taken from the schema files on 2026-09-15 and cited in the test (`tasks` in 2025-11-25; `extensions` in 2026-07-28). The entry bars keys the specification does not define, at the top level and one level under each capability whose sub-keys the schema names (`tools`: `listChanged`; `resources`: `listChanged` and `subscribe`; `prompts`: `listChanged`, the three advertised today, every flag `false` (entry 13); `tasks` is held the day it is advertised; `completions`, `logging`, `experimental` and `extensions` are open objects and nothing is read under them; a third level is not read); a key it does define and this package does not implement is a different question, answered by the README. | `test/beam_mcp/boundary/no_invented_capability_test.exs` "server/discover advertises only keys the 2026-07-28 schema defines" "the initialize result advertises only keys the 2025-11-25 schema defines" "no line under lib/ names a topology or reachability capability on the wire" |
 | 7 | **issue or honour a session identifier.** Over HTTP no response carries `Mcp-Session-Id`, a request carrying one gets the same status and body as one that does not (held on four methods, including an unknown one), and no line under `lib/` reads or writes one; the name is barred in every delimiter and casing (`mcp-session-id`, `McpSessionId`, `session_id`), with one allowance: the hyphenated header name written directly after the words "no `", the transport's own denial. | Every request stands alone; the 2026-07-28 transport removed sessions. Refusing unestablished callers on a transport where that matters is the host's job, stated in the README. | `test/beam_mcp/boundary/no_session_test.exs` "no response carries an mcp-session-id header, and a request carrying one is answered as if it did not" "no code line under lib/ reads or writes a session identifier" |
 | 8 | **carry OAuth.** No authorization flow, discovery document, token endpoint or bearer handling under `lib/`: the `authorization` header is not even read there; it reaches the host's hook untouched. The transport offers `:authorize` and `:authorize_body` hooks and performs no cryptography. | Verifying is the host's work; making it possible is the transport's. A package that performs no cryptography (entries 2 and 3) cannot honestly offer an OAuth server. | `test/beam_mcp/boundary/no_oauth_no_client_test.exs` "no OAuth under lib/" |
 | 9 | **be a client.** No module under `lib/` names itself a client, opens an outbound connection, or sends an `initialize` request. The artefact holds the outbound half whatever the spelling: none of `gen_tcp`, `ssl`, `socket`, `gen_udp`, `ssh`, `httpc`, `inets`, `os`, `peer`, `net_kernel`, `rpc`, `Port`, `File` or any HTTP client is among the modules the package calls, and of `:erlang` only `spawn/1` (the local one) is; the text census names the same by word. A message to a process registered on another node (`send/2`, `GenServer.call/2` to a `{name, node}`) is the one outbound act the compiled form cannot tell from a local one; every `initialize` under `lib/` is a clause head that receives one, or the list of methods the modern era removed. | A server that also calls out has two threat models, and a page like this one for each; this package keeps one. | `test/beam_mcp/boundary/no_oauth_no_client_test.exs` "no client under lib/: no client module, no outbound connection, initialize only ever received"; `test/beam_mcp/boundary/package_reach_test.exs` "the modules the package calls are exactly the listed ones" |
 | 10 | **enumerate all paths or match motifs in the connectome.** `all_paths` is refused by name, always; it is not capped; its one definition under `lib/` is the refusal, and no function under `lib/` carries *motif*, *isomorph*, *subgraph*, *path* or *walk* in its name, except the bare names `path` and `walk` (reach's own witness builder and dominator pass), allowed by name alone, in any module and at any arity. | The number of paths is exponential in the graph; a cap would be a promise to answer "some of them", which is worse than no answer. Motif matching is refused for the same reason. The reachability questions the package does answer are on the reach page. | `test/beam_mcp/connectome/reach_test.exs` "all-paths enumeration is refused by name, not attempted"; `test/beam_mcp/boundary/no_path_enumeration_test.exs` "the only definition of all_paths under lib/ is the refusal, and no motif matcher is defined" |
 | 11 | **hold a tool, a domain, or a concrete catalog.** No module under `lib/` implements `BeamMCP.Catalog` (by `@behaviour`, or by defining or delegating `capabilities/0`, which is all the package asks of a catalog) and nothing under `lib/` builds a `%BeamMCP.ToolSpec{}`, in any spelling: in the compiled form of every module under `lib/`, the atom `BeamMCP.ToolSpec` occurs only inside a map *pattern*: a literal, an alias, a `struct/2`, a `Map.put` of `__struct__`, a map update of `__struct__`, a map *key*, a `%__MODULE__{}` in its own module or a variable bound to the module all leave the atom somewhere else, and the compiler-generated sites are not skipped but pinned (the struct's own `__struct__/0,1` and Catalog's callback info, exactly), so an `unquote` of a hand-built syntax tree marked generated is one site too many. What this does not see is a tool derived from a tool the package was handed: a matched struct updated field by field carries no atom of its own; nothing under `lib/` does that today, and it is a reviewer's line. The struct is defined there, matched there, and never constructed there. The catalog is reached through three callees, `capabilities/0` at five sites, `read_resource/1` at one and `get_prompt/2` at one: in the compiled form every call through a module known only at runtime, with parentheses, is one of those seven; the one read is reached only after the catalog's own `capabilities/0` has listed the uri or a template that matches it, and the one render only after it has listed the prompt and the tools validator has passed the arguments (a call through a function *value* is a closure, the host's dispatch and hooks or the package's own, and not a module call); and the one spelling the compiled form cannot tell from a field access (`m.capabilities` without parentheses, a deprecated form) is held by the list of every name the package reaches by dot syntax, pinned exactly: its own fields, `conn.method`, and a rescued exception's `__struct__` (names, not module–name pairs: a runtime module whose export shares a field's name, `m.nodes` with `m = :erlang`, is inside the list). The catalog and the dispatch are injected by the host. | The README's opening sentence: the package holds no tools, no domain, and no policy; a commodity protocol layer with nothing of its own to protect or to sell. | `test/beam_mcp/boundary/no_catalog_test.exs` "no module under lib/ implements BeamMCP.Catalog" "no line under lib/ constructs a tool" "the catalog is called through three callees: capabilities/0 at five sites, read_resource/1 at one, get_prompt/2 at one" "every name the package reaches by dot syntax is on its pinned list" |
-| 12 | **run a multi-round-trip request.** The `2026-07-28` revision lets a server answer `tools/call`, `resources/read` or `prompts/get` with an `InputRequiredResult` and finish on a later request carrying `inputResponses` and a `requestState` of the server's own. This package answers every request completely or refuses it: the one `resultType` written under `lib/` is `"complete"`, at one site, and neither continuation parameter is read anywhere: a request carrying them is served as if it carried neither, since nothing here ever asked for input. | An input-required round trip is a conversation with state between two messages (what was asked, what came back, what the server had decided so far), and this core has no process and no state of its own by design: one message in, one response out. The `requestState` the revision offers as the server's opaque continuation would carry the server's own decision state for a client to hand back, unlike the pagination cursor, which names a position any client may name by other means and carries no decision. A host that wants the round trip owns exactly the state it needs to run it, above this core. Named by the owner as the one item of the `2026-07-28` surface nobody had placed; placed here, out, so nobody later improves it in by accident. | `test/beam_mcp/boundary/no_mrtr_test.exs` "the only resultType written under lib/ is complete, at one site" "no line under lib/ reads inputResponses or requestState, and none names InputRequiredResult"; `test/beam_mcp/mrtr_wire_test.exs` "on the core, at both eras, the answer with the continuation parameters is the bare answer" "through the HTTP transport the answer with the continuation parameters is the bare answer" |
+| 12 | **run a multi-round-trip request.** The `2026-07-28` revision lets a server answer `tools/call`, `resources/read` or `prompts/get` with an `InputRequiredResult` and finish on a later request carrying `inputResponses` and a `requestState` of the server's own. This package answers every request completely or refuses it: it never writes an `input_required` result (every `resultType` written under `lib/` is a literal, and none is `"input_required"`), and neither continuation parameter is read anywhere: a request carrying them is served as if it carried neither, since nothing here ever asked for input. | An input-required round trip is a conversation with state between two messages (what was asked, what came back, what the server had decided so far), and this core has no process and no state of its own by design: one message in, one response out. The `requestState` the revision offers as the server's opaque continuation would carry the server's own decision state for a client to hand back, unlike the pagination cursor, which names a position any client may name by other means and carries no decision. A host that wants the round trip owns exactly the state it needs to run it, above this core. Named by the owner as the one item of the `2026-07-28` surface nobody had placed; placed here, out, so nobody later improves it in by accident. | `test/beam_mcp/boundary/no_mrtr_test.exs` "every resultType written under lib/ is a literal, and none is input_required" "no line under lib/ reads inputResponses or requestState, and none names InputRequiredResult"; `test/beam_mcp/mrtr_wire_test.exs` "on the core, at both eras, the answer with the continuation parameters is the bare answer" "through the HTTP transport the answer with the continuation parameters is the bare answer" |
+| 13 | **advertise a change notification it does not deliver.** No `listChanged` (tools, resources, prompts) and no `subscribe` (resources) is advertised `true` while the method that delivers it, `subscriptions/listen`, is not served; in 1.x it is not, so every flag is `false` on both revisions, and `subscriptions/listen` and the legacy `resources/subscribe` are answered method-not-found: -32601, and 404 over HTTP. | `2026-07-28` replaced `resources/subscribe` with `subscriptions/listen`, a long-lived stream (SEP-2575), and every change notification is delivered on it. The HTTP transport is stateless by contract and stdio answers one message at a time, so this core holds no stream; a flag advertised without the stream is a promise no client can collect. A server advertising neither feature is conformant ("Servers may advertise either feature independently, together or neither"), and the conformance suite skips the subscription checks for one. A host that needs notifications serves the stream above this core, where the connection state lives; serving it here later is an addition, and turns this entry over with it. | `test/beam_mcp/unserved_subscription_test.exs` "no listChanged or subscribe is advertised true while subscriptions/listen is not served" "subscriptions/listen and resources/subscribe are answered -32601 on the core, and 404 over HTTP" |
 
 ## What a census does not prove
 
diff --git a/lib/beam_mcp/connectome/declared.ex b/lib/beam_mcp/connectome/declared.ex
index 5b3556cc..4b94cb97 100644
--- a/lib/beam_mcp/connectome/declared.ex
+++ b/lib/beam_mcp/connectome/declared.ex
@@ -9,7 +9,7 @@ defmodule BeamMCP.Connectome.Declared do
   Three sources, each optional but the scope:
 
   * **the catalog** -- `c:BeamMCP.Catalog.capabilities/0` of the module given as `catalog:`; one node per tool,
-    resource and prompt, a `:invoke` edge from the server to each tool, and a `:invoke` edge
+    resource, resource template and prompt, a `:invoke` edge from the server to each tool, and a `:invoke` edge
     from a tool to the module the host names for it in `tool_modules:`;
   * **the compiled code** -- call edges read from the beams of the modules in scope with OTP's
     `:xref`. A module whose only use is at a macro's expansion site produces no edge, because
@@ -32,7 +32,9 @@ defmodule BeamMCP.Connectome.Declared do
   every field an enumerated, sorted list and never a count: dynamic-dispatch sites (the calls
   `:xref` cannot resolve, by caller), sites the host vouched for in `dynamic_allowlist:`, callees
   outside the scope, modules with no beam on the code path, modules whose beam carries no debug
-  information, catalog entries no reader can name, tools with no implementing module, modules
+  information, catalog entries no reader can name (none, for a catalog `BeamMCP.Catalog`
+  accepts: it holds every resource, template and prompt to a name, so the field is kept and
+  empty since templates became nodes), tools with no implementing module, modules
   that could not be grouped at the `:boundary` level and the calls into or out of them. Nothing
   the compiled code shows is dropped silently; what it cannot show is stated below.
 
@@ -295,24 +297,35 @@ defmodule BeamMCP.Connectome.Declared do
       for n <- tool_nodes,
           do: Edge.new!(from: server_id, to: n.id, kind: :invoke, provenance: :declared)
 
+    # A template is named by its uri template, as the specification identifies it, and is a
+    # kind of its own: a resource's uri and a template's uri_template are two key spaces.
+    {templates, resources} =
+      Enum.split_with(Map.get(caps, :resources, []), &match?(%BeamMCP.ResourceTemplateSpec{}, &1))
+
     {resource_nodes, bad_resources} =
-      named(Map.get(caps, :resources, []), :resources, [:uri, "uri"], server, :resource)
+      named(resources, :resources, [:uri, "uri"], server, :resource)
+
+    {template_nodes, bad_templates} =
+      named(templates, :resources, [:uri_template], server, :resource_template)
 
     {prompt_nodes, bad_prompts} =
       named(Map.get(caps, :prompts, []), :prompts, [:name, "name"], server, :prompt)
 
     {:ok,
      %{
-       nodes: tool_nodes ++ resource_nodes ++ prompt_nodes,
+       nodes: tool_nodes ++ resource_nodes ++ template_nodes ++ prompt_nodes,
        edges: tool_edges,
-       unreadable: Enum.sort(bad_resources ++ bad_prompts),
+       unreadable: Enum.sort(bad_resources ++ bad_templates ++ bad_prompts),
        tools: Enum.map(tools, & &1.name),
        sources: [:catalog]
      }}
   end
 
-  # A resource or prompt entry is readable when it carries a name under one of the keys a
-  # reader can look for. Anything else is enumerated as unreadable, never dropped.
+  # A resource, template or prompt entry is readable when it carries a name under one of the
+  # keys a reader can look for. Anything else is enumerated as unreadable, never dropped:
+  # unreachable for a catalog `Catalog.validate/1` admits (every entry is a named struct, and
+  # with templates as nodes the suite passes with this branch raising), kept as the guard if
+  # that admission ever widens.
   defp named(entries, field, keys, server, kind) do
     Enum.reduce(entries, {[], []}, fn entry, {nodes, bad} ->
       # The map test comes first and on its own: `is_map(e) and find(...)` short-circuits to
diff --git a/lib/beam_mcp/connectome/graph.ex b/lib/beam_mcp/connectome/graph.ex
index 24c50fb8..76a07dc3 100644
--- a/lib/beam_mcp/connectome/graph.ex
+++ b/lib/beam_mcp/connectome/graph.ex
@@ -27,7 +27,10 @@ defmodule BeamMCP.Connectome.Graph do
   # bytes at 1 and bytes at 2 read their signs against different vocabularies. 3 since the
   # release after: the canonical envelope names its algorithm as a fourth top-level member,
   # and bytes at 1 and 2, which name none, are SHA-256 by the page's rule for those versions.
-  @schema_version 3
+  # 4 since the release after 0.10.1: the node vocabulary gained `resource_template`, so bytes
+  # at 3 and bytes at 4 read their node kinds against different vocabularies; the envelope's
+  # shape is 3's. Growth is a new version, never an edit of an old one (docs/api-stability.md).
+  @schema_version 4
   @keys [:nodes, :edges, :schema_version]
   @required [:nodes, :edges, :schema_version]
 
diff --git a/lib/beam_mcp/connectome/node.ex b/lib/beam_mcp/connectome/node.ex
index c7981692..18d86684 100644
--- a/lib/beam_mcp/connectome/node.ex
+++ b/lib/beam_mcp/connectome/node.ex
@@ -16,12 +16,13 @@ defmodule BeamMCP.Connectome.Node do
   an insertion order, so two builds of the same system produce the same ids and a diff can
   line them up. `id/1` is the one function that derives it, and the only place in the package
   that does -- a second scheme is how two graphs stop agreeing about what a node is. The
-  server component is the identity the host supplies for its server; a tool, resource, prompt
-  or process is named within it; a module is named by its module, or at the finest level by
-  module, function and arity.
+  server component is the identity the host supplies for its server; a tool, resource,
+  resource template, prompt or process is named within it (a template by its uri template, in
+  a key space of its own); a module is named by its module, or at the finest level by module,
+  function and arity.
   """
 
-  @kinds [:server, :tool, :resource, :prompt, :process, :module]
+  @kinds [:server, :tool, :resource, :resource_template, :prompt, :process, :module]
   @levels [:mfa, :module, :boundary, :server]
   @keys [:kind, :level, :identity, :labels]
   @required [:kind, :level, :identity]
@@ -30,7 +31,8 @@ defmodule BeamMCP.Connectome.Node do
   defstruct [:id, :kind, :level, labels: %{}]
 
   @typedoc "What kind of part the node is."
-  @type kind :: :server | :tool | :resource | :prompt | :process | :module
+  @type kind ::
+          :server | :tool | :resource | :resource_template | :prompt | :process | :module
 
   @typedoc "The granularity the node was built at; coarsest last."
   @type level :: :mfa | :module | :boundary | :server
@@ -41,7 +43,7 @@ defmodule BeamMCP.Connectome.Node do
   """
   @type identity ::
           {:server, server :: String.t()}
-          | {:tool | :resource | :prompt | :process, server :: String.t(),
+          | {:tool | :resource | :resource_template | :prompt | :process, server :: String.t(),
              name :: atom() | String.t()}
           | {:module, server :: String.t(), module()}
           | {:module, server :: String.t(), {module(), atom(), arity()}}
@@ -126,7 +128,8 @@ defmodule BeamMCP.Connectome.Node do
   defp id_parts({:server, server}) when is_binary(server), do: [server, "server"]
 
   defp id_parts({kind, server, name})
-       when kind in [:tool, :resource, :prompt, :process] and is_binary(server) and
+       when kind in [:tool, :resource, :resource_template, :prompt, :process] and
+              is_binary(server) and
               (is_atom(name) or is_binary(name)),
        do: [server, Atom.to_string(kind), to_string(name)]
 
diff --git a/lib/beam_mcp/cursor.ex b/lib/beam_mcp/cursor.ex
index 46b4db1d..5c1f993f 100644
--- a/lib/beam_mcp/cursor.ex
+++ b/lib/beam_mcp/cursor.ex
@@ -43,7 +43,7 @@ defmodule BeamMCP.Cursor do
   @spec encode(kind(), key()) :: String.t()
   def encode(kind, key) when is_atom(kind) and is_binary(key) do
     %{"v" => @version, "k" => Atom.to_string(kind), "a" => key}
-    |> Jason.encode!()
+    |> BeamMCP.JSON.encode!()
     |> Base.url_encode64(padding: false)
   end
 
diff --git a/lib/beam_mcp/json.ex b/lib/beam_mcp/json.ex
index 930cf842..a3e144bc 100644
--- a/lib/beam_mcp/json.ex
+++ b/lib/beam_mcp/json.ex
@@ -4,7 +4,7 @@
 defmodule BeamMCP.JSON do
   @moduledoc """
   The one place the wire's JSON is read, on every transport, with the nesting bound in front
-  of the decoder.
+  of the decoder; and the one place it is written, with every map's keys in sorted order.
 
   The size cap a transport puts on a body (1 MiB on both) bounds how deep a body can nest --
   half its bytes, one level per bracket -- but not what decoding it costs: a 1 MiB body nested
@@ -18,8 +18,9 @@ defmodule BeamMCP.JSON do
   string is text -- and refuses a body whose nesting passes `max_depth/0` with
   `{:error, {:nesting, depth, max}}`, building nothing. The walk is O(bytes) and allocates
   nothing but its counters; what it costs a well-formed request is measured in
-  `docs/threat-model.md`. A body it admits is handed to Jason unchanged, so every other
-  answer -- a parse error, a non-object -- is the decoder's, as before.
+  `docs/threat-model.md`. A body it admits is handed to the decoder unchanged, so every other
+  answer -- a parse error, a non-object -- is the decoder's, as before, and its shape is not
+  promised (see `decode/1`).
 
   ## The number
 
@@ -42,7 +43,9 @@ defmodule BeamMCP.JSON do
   Decodes a JSON body after bounding its nesting and refusing a repeated key.
   `{:error, {:nesting, depth, max}}` names the first depth past the bound, before a byte is
   decoded; `{:error, {:duplicate_key, key}}` names the first key an object repeats, at any
-  depth; every other error is Jason's.
+  depth. Those two reasons are promised; every other reason (a parse error) is unspecified:
+  it is the decoder's, today Jason's, and the decoder may change (OTP's `:json` was measured
+  2.3 to 2.6 times faster on bodies near the 1 MiB cap), so match `{:error, _}` for it.
 
   Repeated keys are refused rather than resolved because two parsers resolve them two ways:
   Jason keeps the first, most others the last. A hop in front of this server that routes on
@@ -59,7 +62,7 @@ defmodule BeamMCP.JSON do
   @spec decode(binary()) ::
           {:ok, term()}
           | {:error,
-             {:nesting, pos_integer(), pos_integer()} | {:duplicate_key, String.t()} | struct()}
+             {:nesting, pos_integer(), pos_integer()} | {:duplicate_key, String.t()} | term()}
   def decode(body) when is_binary(body) do
     with :ok <- bound(nesting(body, 0, @max_depth)),
          {:ok, ordered} <- Jason.decode(body, objects: :ordered_objects) do
@@ -67,6 +70,36 @@ defmodule BeamMCP.JSON do
     end
   end
 
+  # The one writer for bytes this package puts on the wire, on every transport: every map, at
+  # every depth, written with its keys in sorted order (by the text JSON carries for the key;
+  # Erlang term order breaks a tie between an atom key and a string key that read the same).
+  # A map of more than 32 keys iterates in hash order and that order is not promised across
+  # OTP releases: one `tools/list` with a 40-property schema was measured hashing differently
+  # on OTP 28.5.0.8 and 29.1 (test/beam_mcp/wire_bytes_test.exs pins one hash). A struct is
+  # its own `Jason.Encoder`'s, left as it is.
+  @doc false
+  @spec encode!(term(), keyword()) :: String.t()
+  def encode!(term, opts \\ []), do: Jason.encode!(sorted(term), opts)
+
+  defp sorted(%{__struct__: _} = struct), do: struct
+
+  defp sorted(%{} = map) do
+    pairs =
+      map
+      |> Enum.map(fn {key, value} -> {key, sorted(value)} end)
+      |> Enum.sort_by(fn {key, _} -> {key_text(key), key} end)
+
+    %Jason.OrderedObject{values: pairs}
+  end
+
+  defp sorted(list) when is_list(list), do: Enum.map(list, &sorted/1)
+  defp sorted(other), do: other
+
+  # The text Jason writes for a key: an atom by its name (`nil` is "nil", where to_string/1
+  # gives ""), anything else by String.Chars, as Jason does.
+  defp key_text(key) when is_atom(key), do: Atom.to_string(key)
+  defp key_text(key), do: to_string(key)
+
   @doc "The type of a decoded value that is not an object, for a refusal that names it."
   @spec type_of(term()) :: String.t()
   def type_of(v) when is_list(v), do: "an array"
diff --git a/lib/beam_mcp/schema.ex b/lib/beam_mcp/schema.ex
index 0eb5f617..8d38a45b 100644
--- a/lib/beam_mcp/schema.ex
+++ b/lib/beam_mcp/schema.ex
@@ -95,8 +95,9 @@ defmodule BeamMCP.Schema do
   @spec check_schema(term()) :: result()
   def check_schema(schema), do: check_schema(schema, "the schema")
 
+  # Sorted, as `check_properties/3` is: the first defect named is part of a -32603's text.
   defp check_schema(schema, where) when is_map(schema) and not is_struct(schema) do
-    Enum.reduce_while(schema, :ok, fn {key, value}, :ok ->
+    Enum.reduce_while(Enum.sort(schema), :ok, fn {key, value}, :ok ->
       continue_or_halt(check_keyword(key, value, where))
     end)
   end
@@ -131,7 +132,7 @@ defmodule BeamMCP.Schema do
   # so the property would be advertised and never checked.
   defp check_keyword("properties", properties, where)
        when is_map(properties) and not is_struct(properties) do
-    Enum.reduce_while(properties, :ok, fn
+    Enum.reduce_while(Enum.sort(properties), :ok, fn
       {name, sub}, :ok when is_binary(name) ->
         continue_or_halt(check_schema(sub, "#{where}, property #{name}"))
 
@@ -269,8 +270,11 @@ defmodule BeamMCP.Schema do
     end
   end
 
+  # Keys are visited in sorted order, never the map's: a map of more than 32 keys iterates in
+  # hash order, which differs between OTP releases, and the refusal (which property it names
+  # first, the order it lists unknown ones in) is bytes on the wire.
   defp check_additional(object, properties, schema, path) do
-    extra = object |> Map.keys() |> Enum.reject(&Map.has_key?(properties, &1))
+    extra = object |> Map.keys() |> Enum.sort() |> Enum.reject(&Map.has_key?(properties, &1))
 
     case Map.get(schema, "additionalProperties", true) do
       false when extra != [] ->
@@ -287,9 +291,12 @@ defmodule BeamMCP.Schema do
   end
 
   defp check_properties(object, properties, path) do
-    Enum.reduce_while(object, :ok, fn {key, value}, :ok ->
+    object
+    |> Map.keys()
+    |> Enum.sort()
+    |> Enum.reduce_while(:ok, fn key, :ok ->
       case Map.fetch(properties, key) do
-        {:ok, sub} -> continue_or_halt(check(value, sub, path ++ [key]))
+        {:ok, sub} -> continue_or_halt(check(Map.fetch!(object, key), sub, path ++ [key]))
         :error -> {:cont, :ok}
       end
     end)
@@ -429,7 +436,7 @@ defmodule BeamMCP.Schema do
   # Schema values rendered for a message, whatever JSON they are: a string as itself, anything
   # else as its JSON text (a map or a list in an enum has no to_string/1).
   defp display(value) when is_binary(value), do: value
-  defp display(value), do: Jason.encode!(value)
+  defp display(value), do: BeamMCP.JSON.encode!(value)
 
   defp plural([_]), do: "y"
   defp plural(_), do: "ies"
diff --git a/lib/beam_mcp/server.ex b/lib/beam_mcp/server.ex
index fedfec1d..dc8df567 100644
--- a/lib/beam_mcp/server.ex
+++ b/lib/beam_mcp/server.ex
@@ -108,12 +108,33 @@ defmodule BeamMCP.Server do
   The dispatch contract. A host supplies a function of this shape; the server calls it and
   never inspects what it does. Any three-arity function returning an ok-or-error tuple
   satisfies it, whatever sits behind it.
+
+  The arguments are the tool's name, its validated arguments (atom keys), and the host's own
+  `dispatch_opts` with one key added, `:mcp`, reserved for the request's context:
+
+      %{
+        meta: map(),                       # the request's params._meta as sent, or %{}
+        client_capabilities: map() | nil,  # the client's declared capabilities, if any
+        protocol_version: String.t()       # the revision the request is served under
+      }
+
+  `meta` keeps string keys, as the client sent them. A request that names its revision in
+  `params._meta` is served under that revision, and the capabilities are the ones it carries
+  there (`2026-07-28` requires them); a request with no `_meta` is served under `2025-11-25`,
+  whatever `initialize` negotiated, and its capabilities are the ones `initialize` declared.
+  A capabilities value that is not an object is `nil`. Everything in this map is the client's
+  word, unverified: authorise on the host's own evidence (the transport's `authorize` hook),
+  never on `meta`. Later fields join this map at a minor release, so a host matches the keys it
+  reads and keeps no exhaustive pattern on it. The key is reserved: `new/1` refuses
+  `dispatch_opts` carrying `:mcp`.
   """
   @type dispatch :: (atom(), map(), keyword() -> {:ok, term()} | {:error, term()})
 
   @type state :: %{
           dispatch: (atom(), map(), keyword() -> {:ok, term()} | {:error, term()}),
           dispatch_opts: keyword(),
+          client: nil | %{capabilities: map() | nil},
+          request: nil | %{meta: map(), protocol_version: String.t()},
           initialized?: boolean(),
           server_name: String.t(),
           shutdown?: boolean(),
@@ -168,7 +189,8 @@ defmodule BeamMCP.Server do
   @options [
     catalog: "a module implementing the BeamMCP.Catalog behaviour",
     dispatch: "a function of three arguments, or absent",
-    dispatch_opts: "a keyword list",
+    dispatch_opts:
+      "a keyword list without the key :mcp (reserved: the request's context arrives under it)",
     server_name: "a string",
     supported_versions:
       "a non-empty list of the revisions this package implements, in the order to advertise them",
@@ -185,7 +207,10 @@ defmodule BeamMCP.Server do
 
   defp valid?(:catalog, value), do: is_atom(value)
   defp valid?(:dispatch, value), do: is_nil(value) or is_function(value, 3)
-  defp valid?(:dispatch_opts, value), do: Keyword.keyword?(value)
+
+  defp valid?(:dispatch_opts, value),
+    do: Keyword.keyword?(value) and not Keyword.has_key?(value, :mcp)
+
   defp valid?(:server_name, value), do: is_binary(value)
 
   defp valid?(:supported_versions, value),
@@ -206,6 +231,11 @@ defmodule BeamMCP.Server do
     %{
       dispatch: Keyword.get(opts, :dispatch),
       dispatch_opts: Keyword.get(opts, :dispatch_opts, []),
+      # What a 2025-11-25 session's initialize declared, and the one request being served:
+      # both read only to hand dispatch its `:mcp` context. `request` is set for one message
+      # and cleared after it, so a stdio state never carries one request's _meta into the next.
+      client: nil,
+      request: nil,
       initialized?: false,
       server_name: Keyword.get(opts, :server_name, @default_server_name),
       shutdown?: false,
@@ -313,7 +343,14 @@ defmodule BeamMCP.Server do
           "serverInfo" => %{"name" => state.server_name, "version" => @server_version}
         })
 
-      {%{state | initialized?: true}, response}
+      capabilities =
+        case message do
+          %{"params" => %{"capabilities" => %{} = caps}} -> caps
+          _ -> nil
+        end
+
+      client = %{capabilities: capabilities}
+      {%{state | initialized?: true, client: client}, response}
     else
       {state, unsupported_version(state, id, requested)}
     end
@@ -362,7 +399,7 @@ defmodule BeamMCP.Server do
             {state, error(id, -32_601, "Method not found: ping")}
 
           true ->
-            {next, response} = handle_message(state, bare)
+            {next, response} = serve_request(state, bare, meta, version)
             # `next`, not `state`: modernise/2 reads only server_name today, which nothing
             # mutates, so this is currently indistinguishable -- and would stop being so the
             # moment any handler changed a field modernise/2 reads.
@@ -372,7 +409,7 @@ defmodule BeamMCP.Server do
       @legacy_version ->
         # 2025-11-25 semantics: ping exists, and the result carries neither resultType nor
         # serverInfo _meta, both of which 2026-07-28 introduced.
-        handle_message(state, bare)
+        serve_request(state, bare, meta, version)
 
       _other ->
         {state, unsupported_version(state, id, version)}
@@ -821,7 +858,7 @@ defmodule BeamMCP.Server do
     encoded = to_json_value(payload)
 
     %{
-      "content" => [%{"type" => "text", "text" => Jason.encode!(encoded, pretty: true)}],
+      "content" => [%{"type" => "text", "text" => BeamMCP.JSON.encode!(encoded, pretty: true)}],
       "structuredContent" => encoded,
       "isError" => false
     }
@@ -846,6 +883,7 @@ defmodule BeamMCP.Server do
   defp error_text(reason) when is_map(reason) do
     reason
     |> to_json_value()
+    |> Enum.sort_by(fn {key, _} -> {to_string(key), key} end)
     |> Enum.map_join(", ", fn {key, value} -> "#{key}: #{stringify(value)}" end)
   end
 
@@ -853,7 +891,7 @@ defmodule BeamMCP.Server do
 
   defp stringify(value) when is_binary(value), do: value
   defp stringify(value) when is_number(value), do: to_string(value)
-  defp stringify(value), do: Jason.encode!(value)
+  defp stringify(value), do: BeamMCP.JSON.encode!(value)
 
   # One lookup governs both paths: a tool is callable exactly when the injected catalog names
   # it, and the spec it returns carries the schema that will be enforced. Both this and the
@@ -865,6 +903,40 @@ defmodule BeamMCP.Server do
   # host's `capabilities/0` is safe -- unlike `Transport.HTTP.init/1`, which under Plug's
   # default init_mode is the host's COMPILE time. Same pattern as `:authorize`: a host that
   # mis-wires this learns when it starts, not from a BadMapError in a request path.
+  # One message served with its request's _meta in hand, for dispatch's `:mcp` context only,
+  # and cleared on the way out (`request: nil`), whatever the handler did with the state.
+  defp serve_request(state, bare, meta, version) do
+    # Map.put, not `%{state | ...}`: a state built by hand, or held from before this field
+    # existed, has no `:request` key, and the update syntax would raise on it.
+    {next, response} =
+      handle_message(Map.put(state, :request, %{meta: meta, protocol_version: version}), bare)
+
+    {Map.put(next, :request, nil), response}
+  end
+
+  # The context dispatch receives under `:mcp`: the request's own when it carried _meta
+  # (2026-07-28 requires it, with the capabilities inside), else the session's (initialize).
+  # A request without _meta is served under 2025-11-25 semantics whatever initialize
+  # negotiated (it never reaches the versioned clause), so that is the revision it is told.
+  defp request_context(%{request: %{meta: meta, protocol_version: version}} = state) do
+    caps = Map.get(meta, @capabilities_meta_key, session_capabilities(state))
+    %{meta: meta, client_capabilities: object_or_nil(caps), protocol_version: version}
+  end
+
+  defp request_context(state) do
+    %{
+      meta: %{},
+      client_capabilities: session_capabilities(state),
+      protocol_version: @legacy_version
+    }
+  end
+
+  defp session_capabilities(%{client: %{capabilities: caps}}), do: caps
+  defp session_capabilities(_state), do: nil
+
+  defp object_or_nil(%{} = map) when not is_struct(map), do: map
+  defp object_or_nil(_), do: nil
+
   defp validate_options!(opts) do
     unless Keyword.keyword?(opts) do
       raise ArgumentError, "BeamMCP.Server.new/1 takes a keyword list, got: #{inspect(opts)}"
@@ -960,7 +1032,7 @@ defmodule BeamMCP.Server do
     )
 
     try do
-      result = state.dispatch.(tool, args, state.dispatch_opts)
+      result = state.dispatch.(tool, args, state.dispatch_opts ++ [mcp: request_context(state)])
       stop = System.monotonic_time()
 
       :telemetry.execute(
diff --git a/lib/beam_mcp/transport/http.ex b/lib/beam_mcp/transport/http.ex
index 8f03c9eb..579ff78b 100644
--- a/lib/beam_mcp/transport/http.ex
+++ b/lib/beam_mcp/transport/http.ex
@@ -344,6 +344,8 @@ if Code.ensure_loaded?(Plug) do
         """
       end
 
+      validate_dispatch_opts!(Keyword.get(opts, :dispatch_opts))
+
       read_timeout =
         validate_read_timeout!(Keyword.get(opts, :read_timeout, @read_timeout_default))
 
@@ -368,6 +370,19 @@ if Code.ensure_loaded?(Plug) do
       }
     end
 
+    # The core refuses a reserved `:mcp` in `dispatch_opts` at `new/1`, which this transport
+    # calls per request; refused here too, structurally, so a host learns it at startup and
+    # not as a fault on every call. Any other shape is the core's to judge, as before.
+    defp validate_dispatch_opts!([_ | _] = dispatch_opts) do
+      if Keyword.keyword?(dispatch_opts) and Keyword.has_key?(dispatch_opts, :mcp) do
+        raise ArgumentError,
+              "BeamMCP.Transport.HTTP: :dispatch_opts must not carry :mcp, the key the " <>
+                "request's context arrives under"
+      end
+    end
+
+    defp validate_dispatch_opts!(_), do: :ok
+
     # THE ADAPTER'S OWN EXCEPTIONS GO BACK TO THE ADAPTER, AS THEMSELVES.
     #
     # Whose exception it is decides whose answer it is, and an exception raised inside a call
@@ -1700,7 +1715,7 @@ if Code.ensure_loaded?(Plug) do
     defp answer(%{"method" => method} = message, _opts) when method in @removed_in_modern do
       case message["id"] do
         nil -> {202, nil}
-        id -> {404, Jason.encode!(error(id, -32_601, "#{@method_not_found} #{method}"))}
+        id -> {404, BeamMCP.JSON.encode!(error(id, -32_601, "#{@method_not_found} #{method}"))}
       end
     end
 
@@ -1729,10 +1744,10 @@ if Code.ensure_loaded?(Plug) do
           # The coupling to the core's wording is deliberate and pinned: a test asserts
           # `Server.handle_message/2` still prefixes this case with @method_not_found, so a
           # reword fails that test instead of silently turning every 404 back into a 200.
-          {404, Jason.encode!(response)}
+          {404, BeamMCP.JSON.encode!(response)}
 
         {_state, response} ->
-          {200, Jason.encode!(response)}
+          {200, BeamMCP.JSON.encode!(response)}
       end
     end
 
@@ -1741,7 +1756,8 @@ if Code.ensure_loaded?(Plug) do
 
     # The encode stays OUTSIDE the adapter boundary: a payload this package cannot encode is
     # its own (or the host's) fault and is answered as one; only the send is the adapter's.
-    defp send_json(conn, status, payload), do: send_encoded(conn, status, Jason.encode!(payload))
+    defp send_json(conn, status, payload),
+      do: send_encoded(conn, status, BeamMCP.JSON.encode!(payload))
 
     defp send_encoded(conn, status, encoded) do
       conn = put_resp_content_type(conn, "application/json")
diff --git a/lib/beam_mcp/transport/stdio.ex b/lib/beam_mcp/transport/stdio.ex
index 1961512a..3c10434d 100644
--- a/lib/beam_mcp/transport/stdio.ex
+++ b/lib/beam_mcp/transport/stdio.ex
@@ -335,13 +335,13 @@ defmodule BeamMCP.Transport.Stdio do
   defp write_message(message) do
     line =
       try do
-        Jason.encode!(message)
+        BeamMCP.JSON.encode!(message)
       rescue
         e ->
           # The exception's name, not its message: the encoder's message quotes the bytes it
           # refused, and those are the host's.
           report("a response could not be encoded as JSON (#{inspect(e.__struct__)})")
-          Jason.encode!(error(Map.get(message, "id"), -32_603, "Internal error"))
+          BeamMCP.JSON.encode!(error(Map.get(message, "id"), -32_603, "Internal error"))
       end
 
     IO.binwrite(:stdio, [line, "\n"])
diff --git a/livebooks/connectome.livemd b/livebooks/connectome.livemd
index d309ca9e..97e5f70c 100644
--- a/livebooks/connectome.livemd
+++ b/livebooks/connectome.livemd
@@ -28,7 +28,7 @@ each is held by a test to what the package produces from its fixtures today. To
 your own system, point the next cell at your own exports.
 
 The fixture is small on purpose: a server `fx` declaring two tools, one resource, one
-prompt and six modules, and a run of the collector in which the *running* catalog carried
+resource template, one prompt and six modules, and a run of the collector in which the *running* catalog carried
 a third tool the declaration never mentioned.
 
 ```elixir
diff --git a/livebooks/exports/fx.declared.json b/livebooks/exports/fx.declared.json
index 7adcdc97..266ec18c 100644
--- a/livebooks/exports/fx.declared.json
+++ b/livebooks/exports/fx.declared.json
@@ -1 +1 @@
-{"schema_version":3,"algorithm":"sha256","nodes":[{"id":"fx/module/BeamMCP.Fixture.Declared.Alpha","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Beta","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Catalog","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Dyn","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Gamma","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.MacroOnly","kind":"module","labels":{},"level":"module"},{"id":"fx/prompt/greet","kind":"prompt","labels":{},"level":"server"},{"id":"fx/resource/r:%2F%2Fa","kind":"resource","labels":{},"level":"server"},{"id":"fx/server","kind":"server","labels":{},"level":"server"},{"id":"fx/tool/echo","kind":"tool","labels":{"command_class":"observe","mode":"read_only"},"level":"server"},{"id":"fx/tool/write","kind":"tool","labels":{"command_class":"mutate","mode":"proposal"},"level":"server"}],"edges":[{"from":"fx/module/BeamMCP.Fixture.Declared.Alpha","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/module/BeamMCP.Fixture.Declared.Beta"},{"from":"fx/server","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/tool/echo"},{"from":"fx/server","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/tool/write"},{"from":"fx/tool/echo","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/module/BeamMCP.Fixture.Declared.Alpha"}]}
\ No newline at end of file
+{"schema_version":4,"algorithm":"sha256","nodes":[{"id":"fx/module/BeamMCP.Fixture.Declared.Alpha","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Beta","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Catalog","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Dyn","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.Gamma","kind":"module","labels":{},"level":"module"},{"id":"fx/module/BeamMCP.Fixture.Declared.MacroOnly","kind":"module","labels":{},"level":"module"},{"id":"fx/prompt/greet","kind":"prompt","labels":{},"level":"server"},{"id":"fx/resource/r:%2F%2Fa","kind":"resource","labels":{},"level":"server"},{"id":"fx/resource_template/r:%2F%2Ft%2F{x}","kind":"resource_template","labels":{},"level":"server"},{"id":"fx/server","kind":"server","labels":{},"level":"server"},{"id":"fx/tool/echo","kind":"tool","labels":{"command_class":"observe","mode":"read_only"},"level":"server"},{"id":"fx/tool/write","kind":"tool","labels":{"command_class":"mutate","mode":"proposal"},"level":"server"}],"edges":[{"from":"fx/module/BeamMCP.Fixture.Declared.Alpha","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/module/BeamMCP.Fixture.Declared.Beta"},{"from":"fx/server","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/tool/echo"},{"from":"fx/server","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/tool/write"},{"from":"fx/tool/echo","kind":"invoke","provenance":"declared","sign":"unset","to":"fx/module/BeamMCP.Fixture.Declared.Alpha"}]}
\ No newline at end of file
diff --git a/livebooks/exports/fx.diff.json b/livebooks/exports/fx.diff.json
index 9439bff5..0493ad32 100644
--- a/livebooks/exports/fx.diff.json
+++ b/livebooks/exports/fx.diff.json
@@ -1 +1 @@
-{"algorithm":"sha256","classes":{"changed_sign":[],"declared_and_observed":[{"from":"fx/server","kind":"invoke","to":"fx/tool/echo"},{"from":"fx/server","kind":"invoke","to":"fx/tool/write"}],"declared_never_observed":[{"from":"fx/module/BeamMCP.Fixture.Declared.Alpha","kind":"invoke","to":"fx/module/BeamMCP.Fixture.Declared.Beta"},{"from":"fx/tool/echo","kind":"invoke","to":"fx/module/BeamMCP.Fixture.Declared.Alpha"}],"observed_but_undeclared":[{"from":"fx/server","kind":"invoke","to":"fx/tool/probe"}]},"coverage":{"declared_and_observed":2,"declared_edges":4,"declared_endpoint_covered":2,"declared_nodes":11,"declared_sign_only":0,"nodes_in_both":3,"observed_edges":3,"observed_endpoint_declared":2,"observed_nodes":4,"observed_sign_only":0},"schema_version":3,"window":{"ended_at":"2026-09-14T01:00:00Z","started_at":"2026-09-14T00:00:00Z"}}
\ No newline at end of file
+{"algorithm":"sha256","classes":{"changed_sign":[],"declared_and_observed":[{"from":"fx/server","kind":"invoke","to":"fx/tool/echo"},{"from":"fx/server","kind":"invoke","to":"fx/tool/write"}],"declared_never_observed":[{"from":"fx/module/BeamMCP.Fixture.Declared.Alpha","kind":"invoke","to":"fx/module/BeamMCP.Fixture.Declared.Beta"},{"from":"fx/tool/echo","kind":"invoke","to":"fx/module/BeamMCP.Fixture.Declared.Alpha"}],"observed_but_undeclared":[{"from":"fx/server","kind":"invoke","to":"fx/tool/probe"}]},"coverage":{"declared_and_observed":2,"declared_edges":4,"declared_endpoint_covered":2,"declared_nodes":12,"declared_sign_only":0,"nodes_in_both":3,"observed_edges":3,"observed_endpoint_declared":2,"observed_nodes":4,"observed_sign_only":0},"schema_version":3,"window":{"ended_at":"2026-09-14T01:00:00Z","started_at":"2026-09-14T00:00:00Z"}}
\ No newline at end of file
diff --git a/livebooks/exports/fx.observed.json b/livebooks/exports/fx.observed.json
index da15c4fa..b1da9772 100644
--- a/livebooks/exports/fx.observed.json
+++ b/livebooks/exports/fx.observed.json
@@ -1 +1 @@
-{"schema_version":3,"algorithm":"sha256","nodes":[{"id":"fx/server","kind":"server","labels":{},"level":"server"},{"id":"fx/tool/echo","kind":"tool","labels":{},"level":"server"},{"id":"fx/tool/probe","kind":"tool","labels":{},"level":"server"},{"id":"fx/tool/write","kind":"tool","labels":{},"level":"server"}],"edges":[{"from":"fx/server","kind":"invoke","provenance":"observed","sign":"unset","to":"fx/tool/echo"},{"from":"fx/server","kind":"invoke","provenance":"observed","sign":"unset","to":"fx/tool/probe"},{"from":"fx/server","kind":"invoke","provenance":"observed","sign":"unset","to":"fx/tool/write"}]}
\ No newline at end of file
+{"schema_version":4,"algorithm":"sha256","nodes":[{"id":"fx/server","kind":"server","labels":{},"level":"server"},{"id":"fx/tool/echo","kind":"tool","labels":{},"level":"server"},{"id":"fx/tool/probe","kind":"tool","labels":{},"level":"server"},{"id":"fx/tool/write","kind":"tool","labels":{},"level":"server"}],"edges":[{"from":"fx/server","kind":"invoke","provenance":"observed","sign":"unset","to":"fx/tool/echo"},{"from":"fx/server","kind":"invoke","provenance":"observed","sign":"unset","to":"fx/tool/probe"},{"from":"fx/server","kind":"invoke","provenance":"observed","sign":"unset","to":"fx/tool/write"}]}
\ No newline at end of file
diff --git a/livebooks/exports/fx.observed.sidecar.json b/livebooks/exports/fx.observed.sidecar.json
index 4e03fd2d..9c449949 100644
--- a/livebooks/exports/fx.observed.sidecar.json
+++ b/livebooks/exports/fx.observed.sidecar.json
@@ -1 +1 @@
-{"schema_version":3,"weights":[{"from":"fx/server","kind":"invoke","provenance":"observed","to":"fx/tool/echo","weight":3},{"from":"fx/server","kind":"invoke","provenance":"observed","to":"fx/tool/probe","weight":1},{"from":"fx/server","kind":"invoke","provenance":"observed","to":"fx/tool/write","weight":1}]}
\ No newline at end of file
+{"schema_version":4,"weights":[{"from":"fx/server","kind":"invoke","provenance":"observed","to":"fx/tool/echo","weight":3},{"from":"fx/server","kind":"invoke","provenance":"observed","to":"fx/tool/probe","weight":1},{"from":"fx/server","kind":"invoke","provenance":"observed","to":"fx/tool/write","weight":1}]}
\ No newline at end of file
diff --git a/test/beam_mcp/boundary/no_mrtr_test.exs b/test/beam_mcp/boundary/no_mrtr_test.exs
index c1c2c046..bc9ed714 100644
--- a/test/beam_mcp/boundary/no_mrtr_test.exs
+++ b/test/beam_mcp/boundary/no_mrtr_test.exs
@@ -5,19 +5,27 @@ defmodule BeamMCP.Boundary.NoMrtrTest do
   # boundary: runs no multi-round-trip request
   # 2026-07-28 lets a server answer `tools/call`, `resources/read` and `prompts/get` with an
   # `InputRequiredResult` and continue on a later request carrying `inputResponses` and
-  # `requestState`. This package answers every request completely or refuses it: the one
-  # `resultType` written under `lib/` is `"complete"`, at one site, and neither continuation
-  # parameter is read anywhere -- a request carrying them is served as if it carried neither,
-  # because the package never asked for input. Stated on the will-not-implement page with its
-  # reason; this census is what holds it.
+  # `requestState`. This package answers every request completely or refuses it: no
+  # `resultType` written under `lib/` is `"input_required"` (each is a literal, so the census
+  # can read it), and neither continuation parameter is read anywhere -- a request carrying
+  # them is served as if it carried neither, because the package never asked for input. The
+  # line is drawn at `input_required`, not at "only `complete`", so that another result type
+  # the specification defines (the Tasks extension's `"task"`, SEP-2663) can be added without
+  # crossing it. Stated on the will-not-implement page with its reason; this census holds it.
   use ExUnit.Case, async: true
   alias BeamMCP.Boundary
 
-  test "the only resultType written under lib/ is complete, at one site" do
+  test "every resultType written under lib/ is a literal, and none is input_required" do
     hits = Boundary.hits(~r/"resultType"/)
-    assert length(hits) == 1, "resultType sites under lib/:\n  " <> Boundary.format(hits)
-    assert [{_, _, line}] = hits
-    assert line =~ ~s("resultType", "complete")
+    assert hits != [], "no resultType site under lib/: the census reads nothing"
+
+    for {_, _, line} = hit <- hits do
+      assert [_, value] = Regex.run(~r/"resultType",\s*"([a-z_]+)"/, line),
+             "a resultType that is not a literal, which this census cannot read:\n  " <>
+               Boundary.format([hit])
+
+      refute value == "input_required", "an input_required result:\n  " <> Boundary.format([hit])
+    end
   end
 
   # The one place the names appear under lib/ is the sentence in BeamMCP.Server's moduledoc
diff --git a/test/beam_mcp/boundary/package_reach_test.exs b/test/beam_mcp/boundary/package_reach_test.exs
index c6409836..5c66e581 100644
--- a/test/beam_mcp/boundary/package_reach_test.exs
+++ b/test/beam_mcp/boundary/package_reach_test.exs
@@ -70,7 +70,8 @@ defmodule BeamMCP.Boundary.PackageReachTest do
   # tag (`:error_logger`), a tuple tag in the canonical encoder (`:array`), `:json` -- a local
   # function name that OTP 28 turned into a module's name, the collision this census is loud
   # about -- and `Jason.OrderedObject`, the struct the decoder hands back for ordered objects,
-  # matched by `BeamMCP.JSON` to read each object's keys once and never called, and
+  # matched by `BeamMCP.JSON` to read each object's keys once, and built by its writer to put
+  # each map's keys in sorted order; never called, and
   # `:standard_error`, the registered name of the VM's standard-error device, which the stdio
   # transport writes its reports to (standard output is the protocol's). Exact for the
   # OTP the gate runs; an older OTP without `json` reads one fewer.
@@ -180,7 +181,9 @@ defmodule BeamMCP.Boundary.PackageReachTest do
     ],
     :atomics => [get: 2, new: 2, put: 3],
     :telemetry => [attach_many: 4, detach: 1, execute: 3],
-    Jason => [decode: 2, encode!: 1, encode!: 2],
+    # One writer: BeamMCP.JSON.encode!/2 hands Jason sorted maps, so the wire's bytes do not
+    # depend on a map's hash order (test/beam_mcp/wire_bytes_test.exs).
+    Jason => [decode: 2, encode!: 2],
     Logger => [__do_log__: 4, __should_log__: 2],
     Process => [delete: 1, info: 2, put: 2, whereis: 1],
     GenServer => [format_report: 1, start: 3, start_link: 3, stop: 3],
diff --git a/test/beam_mcp/connectome/canonical_test.exs b/test/beam_mcp/connectome/canonical_test.exs
index e6a07d6b..3f296049 100644
--- a/test/beam_mcp/connectome/canonical_test.exs
+++ b/test/beam_mcp/connectome/canonical_test.exs
@@ -144,7 +144,7 @@ defmodule BeamMCP.Connectome.CanonicalTest do
 
       assert String.starts_with?(
                bytes,
-               ~s({"schema_version":3,"algorithm":"sha256","nodes":[{"id":")
+               ~s({"schema_version":4,"algorithm":"sha256","nodes":[{"id":")
              )
 
       assert bytes == File.read!(Path.join(@fixtures, "golden.json"))
@@ -170,7 +170,7 @@ defmodule BeamMCP.Connectome.CanonicalTest do
       decoded = Jason.decode!(Canonical.encode!(golden_graph()))
 
       words =
-        ~w(server tool resource prompt process module mfa boundary invoke read message supervise allow deny hold unknown declared observed)
+        ~w(server tool resource resource_template prompt process module mfa boundary invoke read message supervise allow deny hold unknown declared observed)
 
       for node <- decoded["nodes"], {key, value} <- node, is_binary(value), value in words do
         assert key in ["kind", "level"], "#{value} under #{key}"
@@ -615,14 +615,14 @@ defmodule BeamMCP.Connectome.CanonicalTest do
     test "the envelope names its algorithm right after the version, and the default is sha256" do
       g = golden_graph()
       {:ok, bytes} = Canonical.encode(g)
-      assert String.starts_with?(bytes, ~s({"schema_version":3,"algorithm":"sha256","nodes":[))
+      assert String.starts_with?(bytes, ~s({"schema_version":4,"algorithm":"sha256","nodes":[))
       assert Canonical.encode!(g, algorithm: :sha256) == bytes
     end
 
     test "an envelope tagged sha384 round-trips: the bytes name it and the hash is SHA-384 over them" do
       g = golden_graph()
       {:ok, bytes} = Canonical.encode(g, algorithm: :sha384)
-      assert String.starts_with?(bytes, ~s({"schema_version":3,"algorithm":"sha384","nodes":[))
+      assert String.starts_with?(bytes, ~s({"schema_version":4,"algorithm":"sha384","nodes":[))
       assert {:ok, hash} = Canonical.hash(g, algorithm: :sha384)
       assert hash == :crypto.hash(:sha384, bytes)
       assert byte_size(hash) == 48
@@ -738,15 +738,15 @@ defmodule BeamMCP.Connectome.CanonicalTest do
       assert verifier_algorithm(v2) == :sha256
       assert Base.encode16(:crypto.hash(verifier_algorithm(v2), v2), case: :lower) == v2_hex
 
-      v3 = File.read!(Path.join(@fixtures, "golden.json"))
+      v3 = File.read!(Path.join(@fixtures, "golden.v3.json"))
       assert verifier_algorithm(v3) == :sha256
 
       assert Base.encode16(:crypto.hash(:sha256, v3), case: :lower) ==
-               String.trim(File.read!(Path.join(@fixtures, "golden.sha256")))
+               String.trim(File.read!(Path.join(@fixtures, "golden.v3.sha256")))
 
       assert verifier_algorithm(Canonical.encode!(golden_graph(), algorithm: :sha384)) == :sha384
       # And what the page calls malformed, the verifier refuses: a 2 with a member, a 3
-      # without one, a 4, an unknown name.
+      # without one, a 5, an unknown name.
       with_member = ~s({"schema_version":2,"algorithm":"sha256",)
 
       assert verifier_algorithm(String.replace(v2, ~s({"schema_version":2,), with_member)) ==
@@ -755,7 +755,7 @@ defmodule BeamMCP.Connectome.CanonicalTest do
       assert verifier_algorithm(String.replace(v3, ~s("algorithm":"sha256",), "")) == :malformed
 
       assert verifier_algorithm(
-               String.replace(v3, ~s("schema_version":3), ~s("schema_version":4))
+               String.replace(v3, ~s("schema_version":3), ~s("schema_version":5))
              ) == :malformed
 
       assert verifier_algorithm(String.replace(v3, "sha256", "sha3-256")) == :malformed
@@ -765,6 +765,29 @@ defmodule BeamMCP.Connectome.CanonicalTest do
                Graph.new(nodes: [], edges: [], schema_version: 2)
     end
 
+    test "versioned, not frozen: bytes at 3 still verify under the code that writes 4" do
+      # 0.6.0 to 0.10.1 wrote 3; this package writes 4 since the node vocabulary grew
+      # (`resource_template`). A new version is how a shared encoding grows: the old bytes are
+      # kept, unchanged, and verify by their own version's rule, which for 3 and 4 is the same
+      # (the named digest). Nothing reads 3's bytes as 4's or rewrites them.
+      v3 = File.read!(Path.join(@fixtures, "golden.v3.json"))
+      v4 = File.read!(Path.join(@fixtures, "golden.json"))
+      assert String.starts_with?(v3, ~s({"schema_version":3,"algorithm":"sha256",))
+      assert String.starts_with?(v4, ~s({"schema_version":4,"algorithm":"sha256",))
+
+      for {bytes, hex} <- [{v3, "golden.v3.sha256"}, {v4, "golden.sha256"}] do
+        assert verifier_algorithm(bytes) == :sha256
+
+        assert Base.encode16(:crypto.hash(verifier_algorithm(bytes), bytes), case: :lower) ==
+                 String.trim(File.read!(Path.join(@fixtures, hex)))
+      end
+
+      # The two differ in the version alone: the golden graph carries no template, and the
+      # envelope's shape did not move.
+      assert String.replace(v3, ~s("schema_version":3), ~s("schema_version":4)) == v4
+      assert Canonical.encode!(golden_graph()) == v4
+    end
+
     test "a weight change alters the sidecar and not the hash" do
       g = golden_graph()
       [e | rest] = Enum.filter(g.edges, &(&1.weight != nil))
@@ -1056,13 +1079,13 @@ defmodule BeamMCP.Connectome.CanonicalTest do
   # What the migration note tells a verifier to do, in a dozen lines, on the page's terms:
   # the members are in a fixed order, so the version and the algorithm are read from the
   # prefix, not from a decoded map; below 3 the digest is SHA-256 and a member is malformed;
-  # at 3 the member is the second and names one of the three; above 3 is refused.
+  # at 3 and 4 the member is the second and names one of the three; above 4 is refused.
   defp verifier_algorithm(bytes) do
     prefix = ~r/^\{"schema_version":(\d+),(?:"algorithm":"(sha256|sha384|sha512)",)?"nodes":/
 
     case Regex.run(prefix, bytes) do
       [_, v] when v in ["1", "2"] -> :sha256
-      [_, "3", name] -> String.to_existing_atom(name)
+      [_, v, name] when v in ["3", "4"] -> String.to_existing_atom(name)
       _ -> :malformed
     end
   end
diff --git a/test/beam_mcp/connectome/declared_test.exs b/test/beam_mcp/connectome/declared_test.exs
index ea22770d..d1d6db98 100644
--- a/test/beam_mcp/connectome/declared_test.exs
+++ b/test/beam_mcp/connectome/declared_test.exs
@@ -37,6 +37,7 @@ defmodule BeamMCP.Connectome.DeclaredTest do
           Node.id({:tool, @server, :echo}),
           Node.id({:tool, @server, :write}),
           Node.id({:resource, @server, "r://a"}),
+          Node.id({:resource_template, @server, "r://t/{x}"}),
           Node.id({:prompt, @server, "greet"})
         ] ++ Enum.map(@modules, &Node.id({:module, @server, &1}))
 
@@ -121,16 +122,18 @@ defmodule BeamMCP.Connectome.DeclaredTest do
       assert Enum.map(bound.allowlisted_calls, &elem(&1, 0)) == [{Fx.Dyn, :fun, 2}]
     end
 
-    test "a catalog entry no reader can name is enumerated, and has no node" do
+    test "a resource template is a node of its own kind, named by its uri template; nothing is unreadable" do
       {:ok, %{graph: g, bound: bound}} = build()
 
-      # A resource template has no uri, so this builder cannot name it: enumerated, no node.
-      # (Every other entry is a struct the catalog contract holds to a name, so a template is
-      # the one unreadable entry a valid catalog can carry.)
-      assert bound.unreadable_catalog_entries == [
-               {:resources, %BeamMCP.ResourceTemplateSpec{uri_template: "r://t/{x}", name: "t"}}
-             ]
-
+      # The specification identifies a template by its `uriTemplate`, as it identifies a
+      # resource by its `uri`: two key spaces (a resource and a template are two lists on the
+      # wire), so a template is its own kind and never collides with a resource whose uri is
+      # the same string. Until this kind existed, the fixture's template was the one entry a
+      # valid catalog could carry that the builder enumerated as unreadable (G-056).
+      assert bound.unreadable_catalog_entries == []
+      assert [template] = Enum.filter(g.nodes, &(&1.kind == :resource_template))
+      assert template.id == Node.id({:resource_template, @server, "r://t/{x}"})
+      assert template.level == :server
       assert length(Enum.filter(g.nodes, &(&1.kind == :resource))) == 1
     end
 
diff --git a/test/beam_mcp/connectome/graph_test.exs b/test/beam_mcp/connectome/graph_test.exs
index 8dbe9512..8448e70d 100644
--- a/test/beam_mcp/connectome/graph_test.exs
+++ b/test/beam_mcp/connectome/graph_test.exs
@@ -72,8 +72,11 @@ defmodule BeamMCP.Connectome.GraphTest do
       refute page =~ ~r/schema_version: \d/
     end
 
-    test "the version is 3, and the two the package wrote before are refused rather than translated" do
-      assert Graph.schema_version() == 3
+    test "the version is 4, and the three the package wrote before are refused rather than translated" do
+      assert Graph.schema_version() == 4
+
+      assert {:error, {:invalid, :schema_version, 3}} =
+               Graph.new(nodes: [], edges: [], schema_version: 3)
 
       assert {:error, {:invalid, :schema_version, 2}} =
                Graph.new(nodes: [], edges: [], schema_version: 2)
@@ -263,8 +266,8 @@ defmodule BeamMCP.Connectome.GraphTest do
       %Graph{} = g = Graph.new!(nodes: nodes, edges: edges, schema_version: @version)
       assert Graph.check(g) == :ok
 
-      assert Graph.check(%Graph{g | schema_version: 4}) ==
-               {:error, {:invalid, :schema_version, 4}}
+      assert Graph.check(%Graph{g | schema_version: 5}) ==
+               {:error, {:invalid, :schema_version, 5}}
 
       assert Graph.check(%Graph{g | nodes: :none}) == {:error, {:invalid, :nodes, :none}}
       assert Graph.check(%Graph{g | edges: [1]}) == {:error, {:invalid, :edges, [1]}}
diff --git a/test/beam_mcp/connectome/node_test.exs b/test/beam_mcp/connectome/node_test.exs
index b09fe161..93d3526c 100644
--- a/test/beam_mcp/connectome/node_test.exs
+++ b/test/beam_mcp/connectome/node_test.exs
@@ -27,7 +27,8 @@ defmodule BeamMCP.Connectome.NodeTest do
       # level of every :tool node to :server survived them all. The field is what the caller
       # said, whatever the kind; :module and :server are members of both families and the
       # struct must never derive one field from the other.
-      for kind <- [:tool, :resource, :prompt, :process], level <- [:mfa, :module, :boundary] do
+      for kind <- [:tool, :resource, :resource_template, :prompt, :process],
+          level <- [:mfa, :module, :boundary] do
         assert {:ok, %Node{kind: ^kind, level: ^level}} =
                  Node.new(kind: kind, level: level, identity: {kind, "srv", :x})
       end
diff --git a/test/beam_mcp/connectome/observed_test.exs b/test/beam_mcp/connectome/observed_test.exs
index 3893723f..9588bf15 100644
--- a/test/beam_mcp/connectome/observed_test.exs
+++ b/test/beam_mcp/connectome/observed_test.exs
@@ -605,7 +605,8 @@ defmodule BeamMCP.Connectome.ObservedTest do
         )
 
       assert {_, %{"result" => _}} = call(state, :echo, %{"k" => "plain"})
-      assert_receive {:opts, [secret: @marker]}
+      # The host's own options, as given, then the reserved request context.
+      assert_receive {:opts, [{:secret, @marker}, {:mcp, %{}}]}
       assert_marker_absent(name)
     end
 
diff --git a/test/beam_mcp/connectome_vocabulary_test.exs b/test/beam_mcp/connectome_vocabulary_test.exs
index 3ee955cf..8e54b184 100644
--- a/test/beam_mcp/connectome_vocabulary_test.exs
+++ b/test/beam_mcp/connectome_vocabulary_test.exs
@@ -15,10 +15,12 @@ defmodule BeamMCP.ConnectomeVocabularyTest do
      this file red, and a term added here without the document being updated does the same.
   3. Every atom in a `@type` union under `lib/beam_mcp/connectome/` is defined in the document.
      Derived by reading the tree, not listed: the population is every `.ex` file under that
-     directory, and the atoms are the alternatives of every `@type` there. Empty today, which is
-     the point -- the first `@type sign :: :allow | ...` a later slice writes is policed by a
-     test that already runs, and a fifth edge kind or a new sign cannot arrive without a
-     sentence in the public vocabulary.
+     directory, and the atoms are the alternatives of every `@type` there. It was empty when
+     this anchor was written, which was the point: the first `@type sign :: :allow | ...` a
+     later slice wrote was policed by a test that already ran, so an edge kind, a node kind or
+     a sign cannot arrive without a sentence in the public vocabulary. Whether such a set may
+     grow at a minor is a different question, answered on `docs/api-stability.md` and held by
+     `test/beam_mcp/growth_table_test.exs` over the compiled types.
 
   The limit, stated: anchor 3 reads `@type` unions only, and only their BARE-ATOM alternatives
   (`:: :a | :b`), checking for a definition row anywhere in the document rather than under a
@@ -49,7 +51,7 @@ defmodule BeamMCP.ConnectomeVocabularyTest do
   # the node-kind row for `:module` survived -- the level row satisfied it (mutation Md5). The
   # heading is the family, and a row outside it does not define the term in it.
   @families [
-    {"Node kinds", [:server, :tool, :resource, :prompt, :process, :module]},
+    {"Node kinds", [:server, :tool, :resource, :resource_template, :prompt, :process, :module]},
     {"Edge kinds", [:invoke, :read, :message, :supervise]},
     {"Sign", [:allow, :deny, :hold, :ungoverned, :unset]},
     {"Level", [:mfa, :module, :boundary, :server]},
diff --git a/test/beam_mcp/growth_table_test.exs b/test/beam_mcp/growth_table_test.exs
new file mode 100644
index 00000000..65e1b1db
--- /dev/null
+++ b/test/beam_mcp/growth_table_test.exs
@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+
+defmodule BeamMCP.GrowthTableTest do
+  @moduledoc """
+  Every value set a public type spells out as a union of atoms says, on
+  `docs/api-stability.md`, whether it may grow at a minor (OPEN) or only at a major (CLOSED).
+
+  The population is read from the compiled types (`Code.Typespec.fetch_types/1` over every
+  module compiled from `lib/`, the public-API census's population), never from a list: a named
+  `@type` whose whole definition is a union of literal atoms, and a public struct's field
+  typed as one. Each needs exactly one row, with exactly the atoms the type has, so a union
+  that grows, shrinks or appears without its row is a failure, and so is a row whose type is
+  gone. Unions nested deeper (inside a list, a tuple, an error reason) are not rows: the page's
+  default covers them, and the default is OPEN.
+  """
+  use ExUnit.Case, async: true
+
+  @page "docs/api-stability.md"
+
+  # {"Module.name/arity", nil | field, [atoms]} for every union the compiled types carry:
+  # `@type` and `@opaque`, with parameters or without (`@typep` is not public).
+  defp population do
+    for m <- BeamMCP.PublicAPI.modules(),
+        {:ok, types} <- [Code.Typespec.fetch_types(m)],
+        {kind, {name, ast, args}} <- types,
+        kind in [:type, :opaque],
+        entry <- unions("#{inspect(m)}.#{name}/#{length(args)}", ast),
+        do: entry
+  end
+
+  defp unions(type, ast) do
+    case atoms(ast) do
+      [_, _ | _] = atoms -> [{type, nil, atoms}]
+      _ -> fields(type, ast)
+    end
+  end
+
+  # A struct's type: `%{__struct__: M, field => type, ...}`; a field whose type is a union of
+  # literal atoms is a row of its own.
+  defp fields(type, {:type, _, :map, pairs}) when is_list(pairs) do
+    struct? = Enum.any?(pairs, &match?({:type, _, _, [{:atom, _, :__struct__}, _]}, &1))
+
+    for {:type, _, _, [{:atom, _, field}, field_type]} <- pairs,
+        struct?,
+        field != :__struct__,
+        [_, _ | _] = atoms <- [atoms(field_type)],
+        do: {type, Atom.to_string(field), atoms}
+  end
+
+  defp fields(_type, _ast), do: []
+
+  defp atoms({:type, _, :union, members}) do
+    if Enum.all?(members, &match?({:atom, _, _}, &1)),
+      do: Enum.sort(for({:atom, _, a} <- members, do: a)),
+      else: nil
+  end
+
+  defp atoms(_), do: nil
+
+  # | `t:Mod.name/0` | `:a` `:b` | OPEN |   or   | `t:Mod.name/0` field `f` | ... | CLOSED |
+  defp rows do
+    ~r/^\| `t:([A-Za-z0-9_.]+\/\d+)`(?: field `([a-z_]+)`)? \| ((?:`:[a-z0-9_]+` ?)+) \| (OPEN|CLOSED) \|/m
+    |> Regex.scan(File.read!(@page), capture: :all_but_first)
+    |> Enum.map(fn [type, field, values, growth] ->
+      atoms =
+        ~r/`:([a-z0-9_]+)`/
+        |> Regex.scan(values, capture: :all_but_first)
+        |> List.flatten()
+        |> Enum.map(&String.to_atom/1)
+        |> Enum.sort()
+
+      {{type, if(field == "", do: nil, else: field)}, {atoms, growth}}
+    end)
+  end
+
+  test "every atom union in a public type has exactly one row, with its atoms and OPEN or CLOSED" do
+    pop = population()
+    rows = rows()
+    assert pop != [], "the census read no union: its reader is broken, not the tree clean"
+
+    keys = Enum.map(rows, &elem(&1, 0))
+    assert keys == Enum.uniq(keys), "a type has two rows on #{@page}"
+    table = Map.new(rows)
+
+    for {type, field, atoms} <- pop do
+      label = if field, do: "#{type} field `#{field}`", else: type
+
+      assert {row_atoms, _growth} = Map.get(table, {type, field}),
+             "#{label} (#{inspect(atoms)}) has no row in #{@page}'s growth table"
+
+      assert row_atoms == atoms,
+             "#{label}: the row says #{inspect(row_atoms)}, the compiled type #{inspect(atoms)}"
+    end
+
+    stale = Map.keys(table) -- Enum.map(pop, fn {t, f, _} -> {t, f} end)
+    assert stale == [], "rows for types that are not atom unions any more: #{inspect(stale)}"
+  end
+end
diff --git a/test/beam_mcp/readme_claims_test.exs b/test/beam_mcp/readme_claims_test.exs
index 958ad39c..ca04d841 100644
--- a/test/beam_mcp/readme_claims_test.exs
+++ b/test/beam_mcp/readme_claims_test.exs
@@ -993,4 +993,53 @@ defmodule BeamMCP.ReadmeClaimsTest do
 
     HTTP.call(conn, HTTP.init(opts))
   end
+
+  describe "the dispatch callback's third argument" do
+    defmodule ContextCatalog do
+      @moduledoc false
+      def capabilities do
+        %{
+          tools: [
+            %BeamMCP.ToolSpec{
+              name: :probe,
+              command_class: :observe,
+              mode: :read_only,
+              description: "Reports its third argument."
+            }
+          ],
+          resources: [],
+          prompts: []
+        }
+      end
+    end
+
+    test "is the host's dispatch_opts plus :mcp, whose meta is params._meta as sent" do
+      assert readme() |> String.replace(~r/\s+/u, " ") =~
+               "The third argument is the host's own `dispatch_opts` plus one reserved key, `:mcp`"
+
+      parent = self()
+
+      state =
+        BeamMCP.Server.new(
+          catalog: ContextCatalog,
+          dispatch: fn _, _, opts -> send(parent, {:opts, opts}) && {:ok, %{}} end,
+          dispatch_opts: [mine: 1]
+        )
+
+      meta = %{
+        "io.modelcontextprotocol/protocolVersion" => "2026-07-28",
+        "io.modelcontextprotocol/clientCapabilities" => %{},
+        "com.example/x" => 1
+      }
+
+      BeamMCP.Server.handle_message(state, %{
+        "jsonrpc" => "2.0",
+        "id" => 1,
+        "method" => "tools/call",
+        "params" => %{"name" => "probe", "arguments" => %{}, "_meta" => meta}
+      })
+
+      assert_receive {:opts, [mine: 1, mcp: %{meta: ^meta, protocol_version: "2026-07-28"}]}
+    end
+  end
 end
diff --git a/test/beam_mcp/request_context_test.exs b/test/beam_mcp/request_context_test.exs
new file mode 100644
index 00000000..d484fb93
--- /dev/null
+++ b/test/beam_mcp/request_context_test.exs
@@ -0,0 +1,195 @@
+# SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+
+defmodule BeamMCP.RequestContextTest do
+  @moduledoc """
+  The request's context reaches the host's dispatch under the reserved `:mcp` key of its third
+  argument: the request's `params._meta` as the client sent it, the client's capabilities and
+  the protocol revision the request is served under.
+
+  Before, the third argument was the host's static `dispatch_opts` and nothing else: the core
+  stripped `params._meta` before `tools/call` was matched, and kept no client capabilities, so
+  a host that needed a trace id, a progress token or a capability the client declared could
+  not see it, and the next protocol addition that rides in `_meta` would have needed a new
+  function. One reserved key carries all of it, and later fields join that map.
+  """
+  use ExUnit.Case, async: true
+
+  alias BeamMCP.Server
+  alias BeamMCP.Transport.HTTP
+
+  @modern "2026-07-28"
+  @legacy "2025-11-25"
+  @vkey "io.modelcontextprotocol/protocolVersion"
+  @ckey "io.modelcontextprotocol/clientCapabilities"
+
+  defmodule Catalog do
+    @moduledoc false
+    def capabilities do
+      %{
+        tools: [
+          %BeamMCP.ToolSpec{
+            name: :probe,
+            command_class: :observe,
+            mode: :read_only,
+            description: "Reports what dispatch was handed."
+          }
+        ],
+        resources: [],
+        prompts: []
+      }
+    end
+  end
+
+  defp server(extra \\ []) do
+    parent = self()
+
+    Server.new(
+      [
+        catalog: Catalog,
+        dispatch: fn _tool, _args, opts ->
+          send(parent, {:dispatched, opts})
+          {:ok, %{}}
+        end,
+        dispatch_opts: [host: :own]
+      ] ++ extra
+    )
+  end
+
+  defp call(state, id, meta) do
+    params = %{"name" => "probe", "arguments" => %{}}
+    params = if meta, do: Map.put(params, "_meta", meta), else: params
+
+    Server.handle_message(state, %{
+      "jsonrpc" => "2.0",
+      "id" => id,
+      "method" => "tools/call",
+      "params" => params
+    })
+  end
+
+  test "a modern request's _meta, capabilities and revision reach dispatch under :mcp" do
+    caps = %{"elicitation" => %{}}
+    meta = %{@vkey => @modern, @ckey => caps, "com.example/trace" => "t-1"}
+
+    {_state, response} = call(server(), 1, meta)
+    assert %{"result" => _} = response
+    assert_receive {:dispatched, opts}
+
+    assert opts[:host] == :own
+    assert opts[:mcp] == %{meta: meta, client_capabilities: caps, protocol_version: @modern}
+  end
+
+  test "one request's _meta never reaches the next request's dispatch" do
+    {state, _} =
+      call(server(), 1, %{@vkey => @modern, @ckey => %{}, "com.example/trace" => "t-1"})
+
+    assert_receive {:dispatched, _}
+
+    # A request with no _meta at all is the one a leak would reach: nothing of its own to
+    # overwrite the last request's.
+    {_state, _} = call(state, 2, nil)
+    assert_receive {:dispatched, opts}
+    assert opts[:mcp].meta == %{}
+  end
+
+  test "a legacy session's capabilities and revision come from initialize; a request without _meta has %{}" do
+    caps = %{"roots" => %{"listChanged" => true}}
+
+    {state, _} =
+      Server.handle_message(server(), %{
+        "jsonrpc" => "2.0",
+        "id" => 0,
+        "method" => "initialize",
+        "params" => %{"protocolVersion" => @legacy, "capabilities" => caps}
+      })
+
+    {_state, _} = call(state, 1, nil)
+    assert_receive {:dispatched, opts}
+    assert opts[:mcp] == %{meta: %{}, client_capabilities: caps, protocol_version: @legacy}
+  end
+
+  test "a request without _meta is told the revision it is served under, whatever initialize negotiated" do
+    # initialize may name 2026-07-28, but a request without _meta never reaches the versioned
+    # clause: it is answered legacy-shaped (no resultType), so 2025-11-25 is its revision.
+    {state, _} =
+      Server.handle_message(server(), %{
+        "jsonrpc" => "2.0",
+        "id" => 0,
+        "method" => "initialize",
+        "params" => %{"protocolVersion" => @modern, "capabilities" => %{}}
+      })
+
+    {_state, response} = call(state, 1, nil)
+    refute Map.has_key?(response["result"], "resultType")
+    assert_receive {:dispatched, opts}
+    assert opts[:mcp].protocol_version == @legacy
+  end
+
+  test "a capabilities value that is not an object reaches dispatch as nil" do
+    {_state, _} = call(server(), 1, %{@vkey => @modern, @ckey => "x"})
+    assert_receive {:dispatched, opts}
+    assert opts[:mcp].client_capabilities == nil
+  end
+
+  test "a state without the request field (built by hand, or held from before it existed) is served" do
+    state = Map.delete(server(), :request)
+    {_state, response} = call(state, 1, %{@vkey => @modern, @ckey => %{}})
+    assert %{"result" => _} = response
+  end
+
+  test "over HTTP, where every request builds a fresh state, the context arrives the same way" do
+    parent = self()
+    meta = %{@vkey => @modern, @ckey => %{"sampling" => %{}}, "com.example/trace" => "t-9"}
+
+    opts =
+      HTTP.init(
+        catalog: Catalog,
+        dispatch: fn _t, _a, o ->
+          send(parent, {:dispatched, o})
+          {:ok, %{}}
+        end,
+        authorize: fn _conn -> :ok end,
+        allowed_origins: :any
+      )
+
+    body = %{
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => "tools/call",
+      "params" => %{"name" => "probe", "arguments" => %{}, "_meta" => meta}
+    }
+
+    conn =
+      Plug.Test.conn(:post, "/mcp", Jason.encode!(body))
+      |> Plug.Conn.put_req_header("content-type", "application/json")
+      |> Plug.Conn.put_req_header("mcp-protocol-version", @modern)
+      |> Plug.Conn.put_req_header("mcp-method", "tools/call")
+      |> Plug.Conn.put_req_header("mcp-name", "probe")
+      |> HTTP.call(opts)
+
+    assert conn.status == 200
+    assert_receive {:dispatched, o}
+
+    assert o[:mcp] == %{
+             meta: meta,
+             client_capabilities: %{"sampling" => %{}},
+             protocol_version: @modern
+           }
+  end
+
+  test "a host's own :mcp key is refused by new/1, and by the HTTP transport at init: the key is reserved" do
+    assert_raise ArgumentError, ~r/:dispatch_opts.*:mcp/s, fn ->
+      Server.new(catalog: Catalog, dispatch_opts: [mcp: :mine])
+    end
+
+    assert_raise ArgumentError, ~r/:dispatch_opts.*:mcp/s, fn ->
+      HTTP.init(
+        catalog: Catalog,
+        authorize: fn _ -> :ok end,
+        allowed_origins: :any,
+        dispatch_opts: [mcp: :mine]
+      )
+    end
+  end
+end
diff --git a/test/beam_mcp/server_test.exs b/test/beam_mcp/server_test.exs
index 15f36727..3d4e7350 100644
--- a/test/beam_mcp/server_test.exs
+++ b/test/beam_mcp/server_test.exs
@@ -161,7 +161,8 @@ defmodule BeamMCP.ServerTest do
         }
       })
 
-    assert_receive {:dispatch, :propose_action, args, []}
+    # The host passed no dispatch_opts: the third argument is only the reserved request context.
+    assert_receive {:dispatch, :propose_action, args, [mcp: %{meta: %{}}]}
     assert args[:case_id] == "case-7"
     # The package normalises the KEY and passes the VALUE through. Turning "contain" into an
     # atom is domain knowledge and belongs to the host's dispatch, not to a generic server.
diff --git a/test/beam_mcp/threat_model_test.exs b/test/beam_mcp/threat_model_test.exs
index d2daa931..3363672a 100644
--- a/test/beam_mcp/threat_model_test.exs
+++ b/test/beam_mcp/threat_model_test.exs
@@ -138,10 +138,14 @@ defmodule BeamMCP.ThreatModelTest do
       escaped = ~s({"k":"a\\"#{String.duplicate("[", max * 3)}"})
       assert {:ok, %{"k" => _}} = BeamMCP.JSON.decode(escaped)
       # A backslash before a bracket inside a string, as JSON allows only for a few escapes:
-      # Jason refuses it, and that is Jason's answer, not a nesting refusal.
-      assert {:error, %Jason.DecodeError{}} =
+      # the decoder refuses it, and that is the decoder's answer, not a nesting refusal (its
+      # shape is unspecified, so only what it is not is asserted).
+      assert {:error, reason} =
                BeamMCP.JSON.decode(~s({"k":"\\[#{String.duplicate("[", max * 3)}"}))
 
+      refute match?({:nesting, _, _}, reason)
+      refute match?({:duplicate_key, _}, reason)
+
       # Many siblings at depth two: the closing bracket counts back down.
       siblings = "[" <> Enum.map_join(1..(max * 3), ",", fn _ -> "[]" end) <> "]"
       assert {:ok, list} = BeamMCP.JSON.decode(siblings)
diff --git a/test/beam_mcp/unserved_subscription_test.exs b/test/beam_mcp/unserved_subscription_test.exs
new file mode 100644
index 00000000..b36f16a2
--- /dev/null
+++ b/test/beam_mcp/unserved_subscription_test.exs
@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+
+defmodule BeamMCP.UnservedSubscriptionTest do
+  # boundary: advertises no change notification it does not deliver
+  # 2026-07-28 replaced `resources/subscribe` with `subscriptions/listen`, a long-lived stream
+  # (SEP-2575): `listChanged` on tools, resources or prompts, and `subscribe` on resources, are
+  # promises a client can only collect on that stream. This package does not serve it in 1.x
+  # (the HTTP transport is stateless by contract; stdio answers one message at a time), so it
+  # advertises every one of those flags `false`, and a request for the stream, or for the
+  # legacy subscribe, is answered method-not-found: -32601, and 404 over HTTP. A server that
+  # advertises neither is conformant (resources.mdx: "Servers may advertise either feature
+  # independently, together or neither"). The rule this holds: no flag is advertised `true`
+  # while the method that delivers it is not served. Stated on the will-not-implement page,
+  # entry 13; implementing the stream later is an addition, and turns this census over with it.
+  use ExUnit.Case, async: true
+
+  alias BeamMCP.Server
+  alias BeamMCP.Transport.HTTP
+
+  @modern "2026-07-28"
+  @legacy "2025-11-25"
+  @meta %{
+    "io.modelcontextprotocol/protocolVersion" => @modern,
+    "io.modelcontextprotocol/clientCapabilities" => %{}
+  }
+
+  defmodule Catalog do
+    @moduledoc false
+    def capabilities, do: %{tools: [], resources: [], prompts: []}
+  end
+
+  defp core(message), do: elem(Server.handle_message(Server.new(catalog: Catalog), message), 1)
+
+  defp request(method, params \\ %{}),
+    do: %{"jsonrpc" => "2.0", "id" => 1, "method" => method, "params" => params}
+
+  # The change-notification flags a capabilities map advertises, as {capability, flag, value}.
+  defp flags(capabilities) do
+    for {cap, %{} = sub} <- capabilities,
+        {flag, value} <- sub,
+        flag in ["listChanged", "subscribe"],
+        do: {cap, flag, value}
+  end
+
+  defp served?(method, params) do
+    case core(request(method, params)) do
+      %{"error" => %{"code" => -32_601}} -> false
+      _ -> true
+    end
+  end
+
+  test "no listChanged or subscribe is advertised true while subscriptions/listen is not served" do
+    modern = core(request("server/discover", %{"_meta" => @meta}))["result"]["capabilities"]
+
+    legacy =
+      core(request("initialize", %{"protocolVersion" => @legacy, "capabilities" => %{}}))[
+        "result"
+      ]["capabilities"]
+
+    listen = %{"_meta" => @meta, "filter" => %{"resourcesListChanged" => true}}
+    refute served?("subscriptions/listen", listen)
+
+    # Every flag the two eras advertise is present and false: the population is what the
+    # server wrote, so a capability gaining a flag is read here the day it is advertised.
+    for caps <- [modern, legacy] do
+      advertised = flags(caps)
+      assert advertised != []
+      assert Enum.all?(advertised, fn {_, _, value} -> value == false end), inspect(advertised)
+    end
+  end
+
+  test "subscriptions/listen and resources/subscribe are answered -32601 on the core, and 404 over HTTP" do
+    for {method, params} <- [
+          {"subscriptions/listen", %{"_meta" => @meta, "filter" => %{}}},
+          {"resources/subscribe", %{"_meta" => @meta, "uri" => "r://a"}},
+          {"resources/subscribe", %{"uri" => "r://a"}}
+        ] do
+      assert %{"error" => %{"code" => -32_601}} = core(request(method, params)), method
+    end
+
+    opts =
+      HTTP.init(
+        catalog: Catalog,
+        authorize: fn _ -> :ok end,
+        allowed_origins: :any
+      )
+
+    for method <- ["subscriptions/listen", "resources/subscribe"] do
+      body = Jason.encode!(request(method, %{"_meta" => @meta}))
+
+      conn =
+        Plug.Test.conn(:post, "/mcp", body)
+        |> Plug.Conn.put_req_header("content-type", "application/json")
+        |> Plug.Conn.put_req_header("mcp-protocol-version", @modern)
+        |> Plug.Conn.put_req_header("mcp-method", method)
+        |> HTTP.call(opts)
+
+      assert conn.status == 404, method
+      assert %{"error" => %{"code" => -32_601}} = Jason.decode!(conn.resp_body)
+    end
+  end
+end
diff --git a/test/beam_mcp/wire_bytes_test.exs b/test/beam_mcp/wire_bytes_test.exs
new file mode 100644
index 00000000..45eb20d6
--- /dev/null
+++ b/test/beam_mcp/wire_bytes_test.exs
@@ -0,0 +1,146 @@
+# SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+
+defmodule BeamMCP.WireBytesTest do
+  @moduledoc """
+  The bytes this package writes are the same on every OTP release it runs on.
+
+  A map of more than 32 keys iterates in hash order, and that order is not promised across OTP
+  releases: before the sorted encoding, one `tools/list` whose schema had 40 properties hashed
+  differently on OTP 28.5.0.8 and OTP 29.1 (the slice record quotes both). A client that
+  hashes, caches or signs a response would see a different answer from the same server. So
+  every map is written with its keys in sorted order, and this file pins one sha256 per
+  response, the same on every leg of CI.
+
+  The responses carry the package's version (`serverInfo` in the result's `_meta`), so a
+  release bump changes both hashes, on every leg alike. The rule then: re-pin both from one
+  leg in the release's own commit, and confirm the other legs agree in its CI run. A hash that
+  moves on one leg and not another is this file's failure, never a re-pin.
+  """
+  use ExUnit.Case, async: true
+  import Plug.Conn
+  import Plug.Test
+
+  alias BeamMCP.Transport.HTTP
+
+  @modern "2026-07-28"
+  @vkey "io.modelcontextprotocol/protocolVersion"
+
+  # Forty properties, so the schema map and its `properties` map are both past 32 keys.
+  @properties Map.new(1..40, fn i ->
+                {"p#{String.pad_leading(Integer.to_string(i), 2, "0")}",
+                 %{"type" => "string", "description" => "property #{i}"}}
+              end)
+
+  defmodule Catalog do
+    @moduledoc false
+    @behaviour BeamMCP.Catalog
+
+    @impl true
+    def capabilities do
+      %{
+        tools: [
+          %BeamMCP.ToolSpec{
+            name: :wide,
+            command_class: :observe,
+            mode: :read_only,
+            description: "A tool with a wide schema.",
+            input_schema: %{
+              "type" => "object",
+              "properties" =>
+                Map.new(1..40, fn i ->
+                  {"p#{String.pad_leading(Integer.to_string(i), 2, "0")}",
+                   %{"type" => "string", "description" => "property #{i}"}}
+                end),
+              "additionalProperties" => false
+            }
+          }
+        ],
+        resources: [],
+        prompts: []
+      }
+    end
+  end
+
+  defp opts do
+    HTTP.init(
+      catalog: Catalog,
+      # A result of 40 keys: the tool's structured result is written as text, too.
+      dispatch: fn _name, _args, _opts -> {:ok, Map.new(1..40, &{"k#{&1}", &1})} end,
+      authorize: fn _conn -> :ok end,
+      allowed_origins: :any
+    )
+  end
+
+  defp post(method, params, headers) do
+    body = %{
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => method,
+      "params" =>
+        Map.put(params, "_meta", %{
+          @vkey => @modern,
+          "io.modelcontextprotocol/clientCapabilities" => %{}
+        })
+    }
+
+    conn =
+      :post
+      |> conn("/mcp", Jason.encode!(body))
+      |> put_req_header("content-type", "application/json")
+      |> put_req_header("mcp-protocol-version", @modern)
+      |> put_req_header("mcp-method", method)
+
+    conn = Enum.reduce(headers, conn, fn {k, v}, c -> put_req_header(c, k, v) end)
+    HTTP.call(conn, opts())
+  end
+
+  defp sha256(conn) do
+    assert conn.status == 200
+    :crypto.hash(:sha256, conn.resp_body) |> Base.encode16(case: :lower)
+  end
+
+  test "tools/list with a 40-property schema is the same bytes on every OTP release" do
+    assert sha256(post("tools/list", %{}, [])) ==
+             "40d948fc723e22ad7b81a12c484403e22c80effd39dd212b148ff7a64a4abbf1"
+  end
+
+  test "a tools/call whose result has 40 keys is the same bytes on every OTP release" do
+    args = Map.new(@properties, fn {k, _} -> {k, "x"} end)
+    conn = post("tools/call", %{"name" => "wide", "arguments" => args}, [{"mcp-name", "wide"}])
+
+    assert sha256(conn) ==
+             "0bc14b84b3506daf845f3ebcd28e93d3370633f3e2c6113c58dced61de1b9c7f"
+  end
+
+  # A refusal is bytes on the wire too: which property it names, and in which order it lists
+  # unknown ones, must not depend on the order the client's map iterates in.
+  test "a refusal over a 40-key argument map names the first property in sorted order" do
+    bad = Map.new(@properties, fn {k, _} -> {k, 1} end)
+    conn = post("tools/call", %{"name" => "wide", "arguments" => bad}, [{"mcp-name", "wide"}])
+    [%{"text" => text}] = Jason.decode!(conn.resp_body)["result"]["content"]
+    assert text =~ "p01", text
+    refute Enum.any?(2..40, &(text =~ "p#{String.pad_leading(Integer.to_string(&1), 2, "0")}"))
+
+    extra = Map.new(1..40, &{"q#{String.pad_leading(Integer.to_string(&1), 2, "0")}", "x"})
+    conn = post("tools/call", %{"name" => "wide", "arguments" => extra}, [{"mcp-name", "wide"}])
+    [%{"text" => text}] = Jason.decode!(conn.resp_body)["result"]["content"]
+    listed = Regex.scan(~r/q\d\d/, text) |> List.flatten()
+    assert listed == Enum.sort(Map.keys(extra)), text
+  end
+
+  test "every map is written with its keys in sorted order, at every depth, the pretty text too" do
+    # Atom and string keys sort by the string JSON carries; a struct is its own encoder's.
+    term = %{"b" => 1, :a => %{"z" => [%{"y" => 1, "x" => 2}], "m" => nil}, "c" => true}
+    assert BeamMCP.JSON.encode!(term) == ~s({"a":{"m":null,"z":[{"x":2,"y":1}]},"b":1,"c":true})
+    # A key sorts by the text written for it: `nil` is written "nil", not "".
+    assert BeamMCP.JSON.encode!(%{nil => 1, "a" => 2, "o" => 3}) == ~s({"a":2,"nil":1,"o":3})
+
+    wide = Map.new(1..40, &{"k#{String.pad_leading(Integer.to_string(&1), 2, "0")}", &1})
+
+    keys =
+      Regex.scan(~r/"(k\d\d)"/, BeamMCP.JSON.encode!(wide, pretty: true), capture: :all_but_first)
+
+    assert List.flatten(keys) == Enum.sort(Map.keys(wide))
+  end
+end
diff --git a/test/beam_mcp/wire_recording_test.exs b/test/beam_mcp/wire_recording_test.exs
index e31872d4..8f8abdb3 100644
--- a/test/beam_mcp/wire_recording_test.exs
+++ b/test/beam_mcp/wire_recording_test.exs
@@ -9,7 +9,8 @@ defmodule BeamMCP.WireRecordingTest do
   that the same catalog still answers exactly that, and that the catalog with the surface's
   entries added answers exactly that plus the entries -- nothing else on the wire moved, and
   `server/discover` is identical (as decoded JSON: the recording holds the decoded responses,
-  and the encoder is deterministic): no capability was claimed for a graph.
+  and the encoder writes every map's keys in sorted order, so equal decoded JSON is equal bytes:
+  `test/beam_mcp/wire_bytes_test.exs`): no capability was claimed for a graph.
 
   The recording pins the package version the results carry, so a release bump fails both
   tests; the rule then is to re-record with the recorder on the fixture catalog WITHOUT the
diff --git a/test/fixtures/connectome/golden.json b/test/fixtures/connectome/golden.json
index e56a8e8f..af0b9725 100644
--- a/test/fixtures/connectome/golden.json
+++ b/test/fixtures/connectome/golden.json
@@ -1 +1 @@
-{"schema_version":3,"algorithm":"sha256","nodes":[{"id":"srv/boundary/application/beam_mcp","kind":"module","labels":{},"level":"boundary"},{"id":"srv/module/Enum","kind":"module","labels":{},"level":"module"},{"id":"srv/resource/r:%2F%2Fa","kind":"resource","labels":{},"level":"server"},{"id":"srv/server","kind":"server","labels":{},"level":"server"},{"id":"srv/tool/écho","kind":"tool","labels":{"command_class":"observe","mode":"read_only","nested":{"n":2,"ok":true},"title":"café"},"level":"server"}],"edges":[{"from":"srv/module/Enum","kind":"message","provenance":"observed","sign":"unset","to":"srv/boundary/application/beam_mcp"},{"from":"srv/server","kind":"invoke","provenance":"declared","sign":"unset","to":"srv/tool/écho"},{"from":"srv/tool/écho","kind":"invoke","provenance":"declared","sign":"unset","to":"srv/module/Enum"},{"from":"srv/tool/écho","kind":"read","provenance":"observed","sign":"unset","to":"srv/resource/r:%2F%2Fa"}]}
\ No newline at end of file
+{"schema_version":4,"algorithm":"sha256","nodes":[{"id":"srv/boundary/application/beam_mcp","kind":"module","labels":{},"level":"boundary"},{"id":"srv/module/Enum","kind":"module","labels":{},"level":"module"},{"id":"srv/resource/r:%2F%2Fa","kind":"resource","labels":{},"level":"server"},{"id":"srv/server","kind":"server","labels":{},"level":"server"},{"id":"srv/tool/écho","kind":"tool","labels":{"command_class":"observe","mode":"read_only","nested":{"n":2,"ok":true},"title":"café"},"level":"server"}],"edges":[{"from":"srv/module/Enum","kind":"message","provenance":"observed","sign":"unset","to":"srv/boundary/application/beam_mcp"},{"from":"srv/server","kind":"invoke","provenance":"declared","sign":"unset","to":"srv/tool/écho"},{"from":"srv/tool/écho","kind":"invoke","provenance":"declared","sign":"unset","to":"srv/module/Enum"},{"from":"srv/tool/écho","kind":"read","provenance":"observed","sign":"unset","to":"srv/resource/r:%2F%2Fa"}]}
\ No newline at end of file
diff --git a/test/fixtures/connectome/golden.sha256 b/test/fixtures/connectome/golden.sha256
index 6d1315ce..40895015 100644
--- a/test/fixtures/connectome/golden.sha256
+++ b/test/fixtures/connectome/golden.sha256
@@ -1 +1 @@
-e442feaaccd752ddfe3a907a88bcfb19c1d31f4be3fc20a3125ba7b85584caf7
+9ebab284ce675dcfd56e76989cf0d48b1e7ab98e74c76fd48a99fa4db33cd900
diff --git a/test/fixtures/connectome/golden.sha384 b/test/fixtures/connectome/golden.sha384
index 80153869..18380879 100644
--- a/test/fixtures/connectome/golden.sha384
+++ b/test/fixtures/connectome/golden.sha384
@@ -1 +1 @@
-24d90e232e23d85ced6c9e92e34d7b202ed01fbacf4fec2032951214327970e5b5904dd04d27a79ae17b7c124c213685
+ba7350edeed3876fdc8f739d4b29423476f14f174459c65ab13be31b24ea64a4b54460a88f86ad5b74e61bfb65653093
diff --git a/test/fixtures/connectome/golden.sha512 b/test/fixtures/connectome/golden.sha512
index 2c9cdb64..0cb114a5 100644
--- a/test/fixtures/connectome/golden.sha512
+++ b/test/fixtures/connectome/golden.sha512
@@ -1 +1 @@
-21637ad9bbfb72132e751e2f4ead2e9a902d42dedba664c8f199527dd05304158116d0499b02b8441c028e8cf60de7783c398ffdcb97115b9c7a2ba90f495fe4
+8d483db1831148bb3ccc34c9d5d89881aa5b5c97c5fff3c88d90c6f6074a9209ba6b3900a868bd15228faa0fa740262dddbc10f97a1ee4134b4cb05857ff0638
diff --git a/test/fixtures/connectome/golden.sidecar.json b/test/fixtures/connectome/golden.sidecar.json
index 2c364ad8..be6e7a1a 100644
--- a/test/fixtures/connectome/golden.sidecar.json
+++ b/test/fixtures/connectome/golden.sidecar.json
@@ -1 +1 @@
-{"schema_version":3,"weights":[{"from":"srv/module/Enum","kind":"message","provenance":"observed","to":"srv/boundary/application/beam_mcp","weight":1},{"from":"srv/tool/écho","kind":"read","provenance":"observed","to":"srv/resource/r:%2F%2Fa","weight":3}]}
\ No newline at end of file
+{"schema_version":4,"weights":[{"from":"srv/module/Enum","kind":"message","provenance":"observed","to":"srv/boundary/application/beam_mcp","weight":1},{"from":"srv/tool/écho","kind":"read","provenance":"observed","to":"srv/resource/r:%2F%2Fa","weight":3}]}
\ No newline at end of file
diff --git a/test/fixtures/connectome/golden.v3.json b/test/fixtures/connectome/golden.v3.json
new file mode 100644
index 00000000..e56a8e8f
--- /dev/null
+++ b/test/fixtures/connectome/golden.v3.json
@@ -0,0 +1 @@
+{"schema_version":3,"algorithm":"sha256","nodes":[{"id":"srv/boundary/application/beam_mcp","kind":"module","labels":{},"level":"boundary"},{"id":"srv/module/Enum","kind":"module","labels":{},"level":"module"},{"id":"srv/resource/r:%2F%2Fa","kind":"resource","labels":{},"level":"server"},{"id":"srv/server","kind":"server","labels":{},"level":"server"},{"id":"srv/tool/écho","kind":"tool","labels":{"command_class":"observe","mode":"read_only","nested":{"n":2,"ok":true},"title":"café"},"level":"server"}],"edges":[{"from":"srv/module/Enum","kind":"message","provenance":"observed","sign":"unset","to":"srv/boundary/application/beam_mcp"},{"from":"srv/server","kind":"invoke","provenance":"declared","sign":"unset","to":"srv/tool/écho"},{"from":"srv/tool/écho","kind":"invoke","provenance":"declared","sign":"unset","to":"srv/module/Enum"},{"from":"srv/tool/écho","kind":"read","provenance":"observed","sign":"unset","to":"srv/resource/r:%2F%2Fa"}]}
\ No newline at end of file
diff --git a/test/fixtures/connectome/golden.v3.json.license b/test/fixtures/connectome/golden.v3.json.license
new file mode 100644
index 00000000..f1cc2499
--- /dev/null
+++ b/test/fixtures/connectome/golden.v3.json.license
@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC
+SPDX-License-Identifier: Apache-2.0
diff --git a/test/fixtures/connectome/golden.v3.sha256 b/test/fixtures/connectome/golden.v3.sha256
new file mode 100644
index 00000000..6d1315ce
--- /dev/null
+++ b/test/fixtures/connectome/golden.v3.sha256
@@ -0,0 +1 @@
+e442feaaccd752ddfe3a907a88bcfb19c1d31f4be3fc20a3125ba7b85584caf7
diff --git a/test/fixtures/connectome/golden.v3.sha256.license b/test/fixtures/connectome/golden.v3.sha256.license
new file mode 100644
index 00000000..f1cc2499
--- /dev/null
+++ b/test/fixtures/connectome/golden.v3.sha256.license
@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2026 Sudo Apt Holdings LLC
+SPDX-License-Identifier: Apache-2.0