@ggui-ai/protocol-conformance 0.6.3 → 0.8.0

package/README.md

@@ -1,22 +1,25 @@
 # @ggui-ai/protocol-conformance
 
-Conformance test kit for the ggui protocol. Ships a JSON fixture catalog + a runner that drives each fixture against a live implementation over WebSocket and reports scorecard-style pass / fail / skip output.
+Conformance test kit for the ggui protocol. Ships JSON case catalogs + runners that drive them against a live implementation — the behavioral fixtures over WebSocket, the `resources/read` cases over the MCP binding — and report scorecard-style pass / fail / skip output.
 
 This kit is the protocol's conformance surface: it lets a third-party MCP builder prove their implementation is protocol-conformant without reimplementing the test harness.
 
 ## Grading mechanisms
 
-The kit grades protocol obligations through **three mechanisms**, each matched to where the obligation is observable:
+The kit grades protocol obligations through **four mechanisms**, each matched to where the obligation is observable:
 
 1. **Path-A WS fixtures** — wire-observable behaviors graded from frames the runner collects over the live channel (acks, error frames, canonical `data` deliveries).
 2. **Pure-function catalogs** — deterministic validation obligations (the SPEC §7.7.2 gadget obligations) graded against a caller-supplied function; no host, render, or transport.
 3. **Session-state host read-back** — stateful obligations with no wire response (e.g. `host_context_observed` persisting onto `GguiSession.hostContext`): the runner dispatches the C→S frame, waits out the observation window, then reads the GguiSession field back through `ConformanceHost.readSessionField()` and deep-equals it against the fixture's `expected`. No host (or a host without the method, or a read that throws) → the fixture SKIPS with the reason — a host that cannot read state cannot grade it, and the kit never converts that gap into a pass.
+4. **MCP-binding scenario driver** — request/response obligations on the MCP surface, where the deployment shape is part of what is under test. The `resources/read` catalog is the first: a case declares a server shape, a caller identity and a seed set, the adopter's driver brings a server up that way, and the kit reads locators against it and grades the raw JSON-RPC frames. A driver that cannot express a scenario throws, and the case SKIPS — never passes.
 
-A fourth surface — the **Path-B browser-host driver** for DOM-level claims (`bootstrap-failure`, `props-update`) — is honestly absent: it is not yet packaged, and those fixtures skip wherever the kit runs (see below).
+A fifth surface — the **Path-B browser-host driver** for DOM-level claims (`bootstrap-failure`, `props-update`) — is honestly absent: it is not yet packaged, and those fixtures skip wherever the kit runs (see below).
 
 ## Transport
 
-**v1.0 is WebSocket-only.** The canonical ggui transport is WS (see SPEC §12 Transport Bindings). `TransportConfig` is shaped as an extensibly-closed union so later transports (stdio MCP, HTTP long-poll) can be added post-v1.1 without breaking the public API.
+**The behavioral fixture catalog is WebSocket-only.** The canonical ggui live-channel transport is WS (see SPEC §12 Transport Bindings). `TransportConfig` is shaped as an extensibly-closed union so later live-channel transports (HTTP long-poll) can be added without breaking the public API.
+
+The MCP surface is graded separately, by catalog rather than by transport config — see `resource-read-conformance` below. Its cases are deliberately NOT registered in `fixturesByContract`: everything in that map is driven over a WebSocket, so an MCP case there would be a permanent skip on every WS run, which is the false gate the kit's exact skip-set pinning exists to prevent. `resources/read` is the only MCP method bound today; `tools/call` has no driver yet.
 
 ## Path-A vs Path-B matchability
 
@@ -42,17 +45,18 @@ The Path-B driver is not yet packaged — no browser-host harness ships with the
 
 The partition is intentional: Path-A FAILs are vendor-neutrality bugs the server owns; Path-B SKIPs are not fails — they are claims a different driver is responsible for.
 
-One declared grading gap on the action loop: `action-ack` proves the append half of the consume-buffer contract; the retrieval half (the agent draining the buffer via `ggui_consume`) is an MCP tool call a WS-only runner cannot drive. Grading it needs an MCP-binding driver — a future kit surface, not a weaker WS assertion.
+One declared grading gap on the action loop: `action-ack` proves the append half of the consume-buffer contract; the retrieval half (the agent draining the buffer via `ggui_consume`) is an MCP **tool call**, which a WS runner cannot drive. The resource-read catalog below does not close it — that driver binds `resources/read`, and `tools/call` is a different method with a different seam. Grading it needs a tool-call driver, not a weaker WS assertion.
 
 ## Pure-function conformance catalogs
 
 The behavioral fixture catalog above asserts what an implementation _does_ over the wire. Some protocol obligations aren't transport-observable at all — they are deterministic _validation functions_: given an input, accept or reject it. SPEC §7.7.2's gadget obligations are exactly this. Modeling them as WebSocket fixtures would mean faking wire frames the protocol never emits; instead the kit ships **pure-function catalogs** — accept/reject cases graded against a caller-supplied function, with no host, render, or transport.
 
-Each catalog ships its cases as raw JSON so a non-TypeScript implementer can grade their own implementation, and each runner takes the implementation as a callback — the kit never hard-binds a concrete one. Three catalogs ship today:
+Each catalog ships its cases as raw JSON so a non-TypeScript implementer can grade their own implementation, and each runner takes the implementation as a callback — the kit never hard-binds a concrete one. Four catalogs ship today:
 
 - **`@ggui-ai/protocol-conformance/schema-conformance`** — which `DataContract.clientCapabilities` payloads a conformant parser MUST accept / reject (the gadget wire shape).
 - **`@ggui-ai/protocol-conformance/registration-conformance`** — which `(contract, appGadgets, appPublicEnv)` triples the push-time gadget gate stack MUST accept / reject, and with which precise SPEC §7.9 reject code (`gadget_not_registered` / `gadget_package_mismatch` / `gadget_public_env_missing` / `duplicate_gadget_hook`).
 - **`@ggui-ai/protocol-conformance/resolution-conformance`** — which bundle + style URLs the server MUST compute for a gadget descriptor's transport fields (`bundleHost` precedence, default host, loopback `http` scheme).
+- **`@ggui-ai/protocol-conformance/binding-conformance`** — which MCP tool-binding set a manifest resolves to (a declared `mcpTools` list wins entirely; blueprints without it derive bare tool-name entries from contract tool names) and which artifacts the registry `tool=` / `server=` search filters MUST match (SPEC §7.7.4.1).
 
 ```ts
 import { runSchemaConformance } from "@ggui-ai/protocol-conformance/schema-conformance";
@@ -72,29 +76,66 @@ if (schema.failed.length + gate.failed.length + urls.failed.length > 0) {
 }
 ```
 
-The `schema-conformance` meta-test binds its catalog to the live `@ggui-ai/protocol` `clientCapabilitiesSpecSchema` — a drift-catch if the wire schema diverges from the §7.7.2 obligations the catalog freezes. The `registration-conformance` and `resolution-conformance` meta-tests verify catalog coherence against faithful in-test implementations (the kit stays vendor-neutral — it does not depend on a server implementation); grading the _shipping_ gate / resolver is an implementation-side test that drives the corresponding runner.
+The `schema-conformance` meta-test binds its catalog to the live `@ggui-ai/protocol` `clientCapabilitiesSpecSchema` — a drift-catch if the wire schema diverges from the §7.7.2 obligations the catalog freezes. The `registration-conformance`, `resolution-conformance`, and `binding-conformance` meta-tests verify catalog coherence against faithful in-test implementations (the kit stays vendor-neutral — it does not depend on a server implementation); grading the _shipping_ gate / resolver is an implementation-side test that drives the corresponding runner.
+
+## Resource-read conformance — the MCP binding
+
+A read of a render locator (`ui://ggui/render/{sessionId}` or `ui://ggui/render/{sessionId}/{blueprintKey}`) has exactly **two exits**: a result whose contents declare a delivery channel — a live mount — or one typed JSON-RPC error. There is no third outcome, and in particular no successful result carrying a shell that can never paint anything.
+
+That is what makes the read host-checkable. A host that gets `contents` back can mount them without inspecting anything; a host that gets an error routes on `error.data.code` — "come back never" versus "come back with a fresh render" — without parsing prose.
+
+```ts
+import { runResourceReadConformance } from "@ggui-ai/protocol-conformance/resource-read-conformance";
+
+const result = await runResourceReadConformance(async (scenario) => {
+  // Bring YOUR server up in `scenario.server`'s shape, as
+  // `scenario.caller`, with `scenario.seeds` applied.
+  const server = await bootMyServer(scenario);
+  return {
+    // Keys your registry assigned to `registered-blueprint` seeds.
+    registeredKeys: server.registeredKeys,
+    // MUST resolve. A protocol failure is `{kind: 'error'}` carrying
+    // the RAW frame — an MCP client's reconstructed error rewrites
+    // `message`, and the disclosure obligation is graded on bytes.
+    read: (uri) => server.readResource(uri),
+    dispose: () => server.close(),
+  };
+});
+
+if (result.failed.length > 0 || result.passed.length === 0) process.exit(1);
+```
+
+Throwing from the driver means "I cannot express this scenario" and the case **skips** with that reason — never passes. Throwing from `read` is a **fail**, because the read is the thing under test.
+
+The catalog grades all four failure classes (`NOT_FOUND` on `-32002`; `BLUEPRINT_UNRESOLVABLE` / `NOT_SUPPORTED` / `NOT_MOUNTABLE` on `-32006`), the mount half on both a live row and a re-minted one, and the disclosure obligation: a read refused for lack of entitlement and a read of a locator that never existed must be **byte-identical**, on a server that keeps durable records, on one that keeps none, on the two half-wired shapes in between, and on one whose blueprint registry matches the probed key.
+
+It deliberately does **not** grade: the order in which a substrate-less server answers (`NOT_SUPPORTED` describes the deployment, so answering it immediately is correct); `detail` wording on any code; the `NOT_FOUND` message literal (its _constancy_ is what is normative); internal-error message text; the number a URI naming no locator receives (that belongs to the transport binding — only the negative is graded, that it must not be one of the four); and the shell's markup (success is graded on the projected render meta, never on DOM shape).
 
 ## Conformance status
 
 What is actually graded against shipping code today, and what is still awaiting a driver. This is an inventory, not a roadmap — a mechanism is listed as proven only if a test in the repo drives it against the real implementation on every push.
 
-Every test below is a plain `*.test.ts` inside a package's `src/`, so it runs in that package's ordinary vitest suite. The ggui repo's per-push CI runs `turbo run test` across all non-e2e packages, so **all five rows below are gated on every push** — the kit needs no dedicated workflow, and adopters wiring it into their own CI need nothing more than their existing unit-test task.
+Every test below is a plain `*.test.ts` inside a package's `src/`, so it runs in that package's ordinary vitest suite. The ggui repo's per-push CI runs `turbo run test` across all non-e2e packages, so **all eight rows below are gated on every push** — the kit needs no dedicated workflow, and adopters wiring it into their own CI need nothing more than their existing unit-test task.
 
-| Obligation                          | Graded against                                                                             | Driver                                                                                   |
-| ----------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| Gadget wire schema (§7.7.2)         | the shipping `@ggui-ai/protocol` `clientCapabilitiesSpecSchema`                            | this kit's own `src/schema-conformance/schema-conformance.test.ts`                       |
-| Registration gate (§7.7.3, §7.9)    | the shipping gate trio in `@ggui-ai/mcp-server-handlers`                                   | `mcp-server-handlers/src/renders/assert-gadgets.conformance.test.ts`                     |
-| Bundle-URL resolution (§7.7.2)      | the shipping `resolveGadgetUrls` in `@ggui-ai/mcp-server-handlers`                         | `mcp-server-handlers/src/renders/resolve-gadget-urls.conformance.test.ts`                |
-| Path-A WS fixtures — first-party    | the real `@ggui-ai/mcp-server` GguiSession channel, booted in-process on an ephemeral port | `mcp-server/src/ggui-session-channel.conformance.test.ts` — **8 pass / 4 skip / 0 fail** |
-| Path-A WS fixtures — vendor-neutral | `@ggui-ai/protocol-reference-server`                                                       | `protocol-reference-server/src/conformance.test.ts` — **9 pass / 3 skip / 0 fail**       |
+| Obligation                                                              | Graded against                                                                             | Driver                                                                                               |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Gadget wire schema (§7.7.2)                                             | the shipping `@ggui-ai/protocol` `clientCapabilitiesSpecSchema`                            | this kit's own `src/schema-conformance/schema-conformance.test.ts`                                   |
+| Registration gate (§7.7.3, §7.9)                                        | the shipping gate trio in `@ggui-ai/mcp-server-handlers`                                   | `mcp-server-handlers/src/renders/assert-gadgets.conformance.test.ts`                                 |
+| Bundle-URL resolution (§7.7.2)                                          | the shipping `resolveGadgetUrls` in `@ggui-ai/mcp-server-handlers`                         | `mcp-server-handlers/src/renders/resolve-gadget-urls.conformance.test.ts`                            |
+| Path-A WS fixtures — first-party                                        | the real `@ggui-ai/mcp-server` GguiSession channel, booted in-process on an ephemeral port | `mcp-server/src/ggui-session-channel.conformance.test.ts` — **8 pass / 4 skip / 0 fail**             |
+| Path-A WS fixtures — vendor-neutral                                     | `@ggui-ai/protocol-reference-server`                                                       | `protocol-reference-server/src/conformance.test.ts` — **9 pass / 3 skip / 0 fail**                   |
+| `resources/read` typed failures + mount invariant                       | the shipping `registerGguiRenderResourceTemplate` in `@ggui-ai/mcp-server`                 | `mcp-server/src/mcp-apps-outbound.resource-read.conformance.test.ts` — **12 pass / 0 skip / 0 fail** |
+| Tool-binding resolution — declared wins, contract derivation (§7.7.4.1) | the shipping `resolveMcpToolBindings` in `@ggui-ai/artifact-manifest`                      | `artifact-manifest/src/mcp-tool-bindings.conformance.test.ts`                                        |
+| Tool-binding search filters — `tool=` / `server=` semantics (§7.7.4.1)  | the shipping `matchesMcpToolFilters` in `@ggui-ai/registry-core`                           | `registry-core/src/mcp-tool-filters.conformance.test.ts`                                             |
 
-Both WS drivers pin their pass set _and_ their skip set as exact sets. A fixture silently degrading to a skip fails the build, and so does a skipped fixture that quietly starts passing — a skip set that can grow unnoticed is a false gate, and re-pinning it is meant to be a deliberate act.
+Both WS drivers pin their pass set _and_ their skip set as exact sets, and the resource-read driver pins its skip set as exactly empty. A fixture silently degrading to a skip fails the build, and so does a skipped fixture that quietly starts passing — a skip set that can grow unnoticed is a false gate, and re-pinning it is meant to be a deliberate act.
 
 **Awaiting a driver:**
 
-- **Path-B browser-host fixtures** — `bootstrap-bundle-fetch-failed`, `bootstrap-meta-missing` (both need MCP-Apps-host fault injection) and `props-update-roundtrip` (assertion is on rendered DOM). No browser-host adapter ships with the kit, so these skip on every driver above. Honestly absent, not silently passing.
+- **Path-B browser-host fixtures** — `bootstrap-bundle-fetch-failed`, `bootstrap-meta-missing` (both need MCP-Apps-host fault injection) and `props-update-roundtrip` (assertion is on rendered DOM). No browser-host adapter ships with the kit, so these skip on every WS driver above. Honestly absent, not silently passing.
 - **`version-mismatch` on the first-party server** — needs a `server-version-override` seam the channel deliberately does not expose; adding a production seam with no production caller purely to drive a fixture was rejected. It passes on the reference server, which has a per-render override.
-- **The `ggui_consume` retrieval half of the action loop** — `action-ack-sequence` proves the append half; draining the buffer is an MCP tool call a WS-only runner cannot drive. Needs an MCP-binding driver, a future kit surface.
+- **The `ggui_consume` retrieval half of the action loop, and `stream-delivery-roundtrip`** — both are `tools/call` obligations (`ggui_consume`, `ggui_emit`). The resource-read driver binds `resources/read` only, so neither is closed by it; both await a tool-call driver.
+- **`resources/read` on a second implementation** — the catalog is vendor-neutral by construction (the kit imports no server; the adopter supplies the driver), but it is graded against one implementation today. A second binding is what would ground the vendor-neutrality claim empirically, the way `protocol-reference-server` does for the WS catalog.
 
 ## Public API
 

package/dist/binding-conformance/cases/bind-blueprint-no-contract-none.json

@@ -0,0 +1,6 @@
+{
+    "name": "bind-blueprint-no-contract-none",
+    "description": "A blueprint manifest with no `mcpTools` and no contract. Nothing declares and nothing derives — the artifact has no bindings and is simply not findable by tool. Accept with no binding set.",
+    "entry": { "kind": "blueprint" },
+    "expect": { "outcome": "accept" }
+}

package/dist/binding-conformance/cases/bind-contract-without-tool-names-none.json

@@ -0,0 +1,18 @@
+{
+    "name": "bind-contract-without-tool-names-none",
+    "description": "A blueprint manifest whose contract carries NO tool lineage anywhere derivation reads — props without `sourceTool`, stream channels without `source`. Derivation runs and finds the empty union: no bindings, same as having no contract at all.",
+    "entry": {
+        "kind": "blueprint",
+        "contract": {
+            "propsSpec": {
+                "properties": {
+                    "note": { "schema": { "description": "free-text note" } }
+                }
+            },
+            "streamSpec": {
+                "ticks": { "schema": { "description": "local timer ticks" } }
+            }
+        }
+    },
+    "expect": { "outcome": "accept" }
+}

package/dist/binding-conformance/cases/bind-declared-gadget.json

@@ -0,0 +1,13 @@
+{
+    "name": "bind-declared-gadget",
+    "description": "A gadget manifest declaring `mcpTools` explicitly. The resolver MUST surface the declared list verbatim, marked `declared`. The list legally mixes a server-qualified entry with a bare (server-agnostic) entry for the same tool name — only exact-duplicate `(server, tool)` pairs are invalid, and a bare entry is a distinct pair from any server-qualified one.",
+    "entry": {
+        "kind": "gadget",
+        "mcpTools": [{ "server": "acme-crm", "tool": "list_invoices" }, { "tool": "list_invoices" }]
+    },
+    "expect": {
+        "outcome": "accept",
+        "source": "declared",
+        "bindings": [{ "server": "acme-crm", "tool": "list_invoices" }, { "tool": "list_invoices" }]
+    }
+}

package/dist/binding-conformance/cases/bind-declared-wins-over-contract.json

@@ -0,0 +1,23 @@
+{
+    "name": "bind-declared-wins-over-contract",
+    "description": "A blueprint manifest with BOTH a declared `mcpTools` list AND a contract whose prop lineage names a different tool. Declared wins entirely: derivation MUST NOT run and MUST NOT merge — the result carries only the declared entries, marked `declared`.",
+    "entry": {
+        "kind": "blueprint",
+        "mcpTools": [{ "server": "acme-crm", "tool": "list_invoices" }],
+        "contract": {
+            "propsSpec": {
+                "properties": {
+                    "forecast": {
+                        "schema": { "description": "hourly forecast rows" },
+                        "sourceTool": "get_forecast"
+                    }
+                }
+            }
+        }
+    },
+    "expect": {
+        "outcome": "accept",
+        "source": "declared",
+        "bindings": [{ "server": "acme-crm", "tool": "list_invoices" }]
+    }
+}

package/dist/binding-conformance/cases/bind-derived-caps-at-sixteen.json

@@ -0,0 +1,54 @@
+{
+    "name": "bind-derived-caps-at-sixteen",
+    "description": "Derivation caps at the same 16-entry bound a declared `mcpTools` list is schema-capped at, keeping the survivors in first-appearance order (props before stream, each in declaration order) and dropping anything past the 16th distinct tool name. This composes the existing envelope — it is not new policy.",
+    "entry": {
+        "kind": "blueprint",
+        "contract": {
+            "propsSpec": {
+                "properties": {
+                    "p01": { "schema": { "description": "p01" }, "sourceTool": "tool_01" },
+                    "p02": { "schema": { "description": "p02" }, "sourceTool": "tool_02" },
+                    "p03": { "schema": { "description": "p03" }, "sourceTool": "tool_03" },
+                    "p04": { "schema": { "description": "p04" }, "sourceTool": "tool_04" },
+                    "p05": { "schema": { "description": "p05" }, "sourceTool": "tool_05" },
+                    "p06": { "schema": { "description": "p06" }, "sourceTool": "tool_06" },
+                    "p07": { "schema": { "description": "p07" }, "sourceTool": "tool_07" },
+                    "p08": { "schema": { "description": "p08" }, "sourceTool": "tool_08" },
+                    "p09": { "schema": { "description": "p09" }, "sourceTool": "tool_09" },
+                    "p10": { "schema": { "description": "p10" }, "sourceTool": "tool_10" }
+                }
+            },
+            "streamSpec": {
+                "s11": { "schema": { "description": "s11" }, "source": { "tool": "tool_11" } },
+                "s12": { "schema": { "description": "s12" }, "source": { "tool": "tool_12" } },
+                "s13": { "schema": { "description": "s13" }, "source": { "tool": "tool_13" } },
+                "s14": { "schema": { "description": "s14" }, "source": { "tool": "tool_14" } },
+                "s15": { "schema": { "description": "s15" }, "source": { "tool": "tool_15" } },
+                "s16": { "schema": { "description": "s16" }, "source": { "tool": "tool_16" } },
+                "s17": { "schema": { "description": "s17" }, "source": { "tool": "tool_17" } }
+            }
+        }
+    },
+    "expect": {
+        "outcome": "accept",
+        "source": "derived",
+        "bindings": [
+            { "tool": "tool_01" },
+            { "tool": "tool_02" },
+            { "tool": "tool_03" },
+            { "tool": "tool_04" },
+            { "tool": "tool_05" },
+            { "tool": "tool_06" },
+            { "tool": "tool_07" },
+            { "tool": "tool_08" },
+            { "tool": "tool_09" },
+            { "tool": "tool_10" },
+            { "tool": "tool_11" },
+            { "tool": "tool_12" },
+            { "tool": "tool_13" },
+            { "tool": "tool_14" },
+            { "tool": "tool_15" },
+            { "tool": "tool_16" }
+        ]
+    }
+}

package/dist/binding-conformance/cases/bind-derived-props-and-stream.json

@@ -0,0 +1,36 @@
+{
+    "name": "bind-derived-props-and-stream",
+    "description": "A blueprint manifest with no `mcpTools` and a contract carrying tool lineage in both places derivation reads: `propsSpec.properties[*].sourceTool` and `streamSpec[*].source.tool`. The resolver MUST derive bare `{tool}` entries (contracts carry no server identity), marked `derived`, in first-appearance order: props entries in declaration order, then stream channels in declaration order.",
+    "entry": {
+        "kind": "blueprint",
+        "contract": {
+            "propsSpec": {
+                "properties": {
+                    "invoices": {
+                        "schema": { "description": "invoice rows" },
+                        "sourceTool": "list_invoices"
+                    },
+                    "customer": {
+                        "schema": { "description": "customer record" },
+                        "sourceTool": "get_customer"
+                    }
+                }
+            },
+            "streamSpec": {
+                "invoiceEvents": {
+                    "schema": { "description": "invoice change events" },
+                    "source": { "tool": "watch_invoices" }
+                }
+            }
+        }
+    },
+    "expect": {
+        "outcome": "accept",
+        "source": "derived",
+        "bindings": [
+            { "tool": "list_invoices" },
+            { "tool": "get_customer" },
+            { "tool": "watch_invoices" }
+        ]
+    }
+}

package/dist/binding-conformance/cases/bind-derived-skips-invalid-names.json

@@ -0,0 +1,40 @@
+{
+    "name": "bind-derived-skips-invalid-names",
+    "description": "Contract lineage tool names are agent/tool-authored data, not author declarations, so derivation stays inside the same charset envelope a declared `mcpTools` list is validated against by filtering invalid names silently rather than rejecting the manifest. An empty-string `sourceTool`, a charset-invalid `sourceTool` (embedded space), and a charset-invalid stream `source.tool` (embedded slash) MUST all be skipped; only names matching the binding charset survive derivation, in first-appearance order.",
+    "entry": {
+        "kind": "blueprint",
+        "contract": {
+            "propsSpec": {
+                "properties": {
+                    "empty": {
+                        "schema": { "description": "prop with empty lineage" },
+                        "sourceTool": ""
+                    },
+                    "invalidChars": {
+                        "schema": { "description": "prop with charset-invalid lineage" },
+                        "sourceTool": "has space"
+                    },
+                    "customer": {
+                        "schema": { "description": "customer record" },
+                        "sourceTool": "get_customer"
+                    }
+                }
+            },
+            "streamSpec": {
+                "badChannel": {
+                    "schema": { "description": "channel with charset-invalid lineage" },
+                    "source": { "tool": "bad/tool" }
+                },
+                "invoiceEvents": {
+                    "schema": { "description": "invoice change events" },
+                    "source": { "tool": "watch_invoices" }
+                }
+            }
+        }
+    },
+    "expect": {
+        "outcome": "accept",
+        "source": "derived",
+        "bindings": [{ "tool": "get_customer" }, { "tool": "watch_invoices" }]
+    }
+}

package/dist/binding-conformance/cases/bind-derived-union-dedupes.json

@@ -0,0 +1,38 @@
+{
+    "name": "bind-derived-union-dedupes",
+    "description": "Derivation is a set union: the same tool name appearing on two props AND as a stream-channel source MUST collapse to one bare entry at its first appearance. Props without `sourceTool` and channels without `source` contribute nothing.",
+    "entry": {
+        "kind": "blueprint",
+        "contract": {
+            "propsSpec": {
+                "properties": {
+                    "openInvoices": {
+                        "schema": { "description": "open invoice rows" },
+                        "sourceTool": "list_invoices"
+                    },
+                    "paidInvoices": {
+                        "schema": { "description": "paid invoice rows" },
+                        "sourceTool": "list_invoices"
+                    },
+                    "title": {
+                        "schema": { "description": "screen title" }
+                    }
+                }
+            },
+            "streamSpec": {
+                "refresh": {
+                    "schema": { "description": "refreshed invoice rows" },
+                    "source": { "tool": "list_invoices" }
+                },
+                "ticker": {
+                    "schema": { "description": "sourceless local ticks" }
+                }
+            }
+        }
+    },
+    "expect": {
+        "outcome": "accept",
+        "source": "derived",
+        "bindings": [{ "tool": "list_invoices" }]
+    }
+}

package/dist/binding-conformance/cases/bind-gadget-undeclared-none.json

@@ -0,0 +1,6 @@
+{
+    "name": "bind-gadget-undeclared-none",
+    "description": "A gadget manifest without `mcpTools`. Gadgets have no contract to derive from — derivation is a blueprint-only fallback — so an undeclared gadget has no bindings.",
+    "entry": { "kind": "gadget" },
+    "expect": { "outcome": "accept" }
+}

package/dist/binding-conformance/cases/bind-reject-charset.json

@@ -0,0 +1,9 @@
+{
+    "name": "bind-reject-charset",
+    "description": "A binding whose `tool` carries characters outside the allowed charset `[A-Za-z0-9_.-]` (here: a space and `!`). The manifest MUST be rejected with the manifest-validation code.",
+    "entry": {
+        "kind": "gadget",
+        "mcpTools": [{ "tool": "list invoices!" }]
+    },
+    "expect": { "outcome": "reject", "code": "manifest_invalid" }
+}

package/dist/binding-conformance/cases/bind-reject-duplicate-pair.json

@@ -0,0 +1,12 @@
+{
+    "name": "bind-reject-duplicate-pair",
+    "description": "Two entries with the exact same `(server, tool)` pair. Exact duplicates are rejected at schema level with the manifest-validation code — deduplication is the publisher's job, not the registry's.",
+    "entry": {
+        "kind": "blueprint",
+        "mcpTools": [
+            { "server": "acme-crm", "tool": "list_invoices" },
+            { "server": "acme-crm", "tool": "list_invoices" }
+        ]
+    },
+    "expect": { "outcome": "reject", "code": "manifest_invalid" }
+}

package/dist/binding-conformance/cases/bind-reject-empty-list.json

@@ -0,0 +1,9 @@
+{
+    "name": "bind-reject-empty-list",
+    "description": "An empty `mcpTools` list. Present-but-empty is invalid — a publisher opting into tool bindings must name at least one; omitting the field entirely is the way to declare none.",
+    "entry": {
+        "kind": "gadget",
+        "mcpTools": []
+    },
+    "expect": { "outcome": "reject", "code": "manifest_invalid" }
+}

package/dist/binding-conformance/cases/bind-reject-overlong-name.json

@@ -0,0 +1,13 @@
+{
+    "name": "bind-reject-overlong-name",
+    "description": "A binding whose `tool` is 129 characters — one past the 128-character bound. The manifest MUST be rejected with the manifest-validation code.",
+    "entry": {
+        "kind": "gadget",
+        "mcpTools": [
+            {
+                "tool": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+            }
+        ]
+    },
+    "expect": { "outcome": "reject", "code": "manifest_invalid" }
+}

package/dist/binding-conformance/cases/bind-reject-server-charset.json

@@ -0,0 +1,9 @@
+{
+    "name": "bind-reject-server-charset",
+    "description": "A binding whose `server` violates the shared charset (here: a `/`). `server` and `tool` share one name rule. The manifest MUST be rejected with the manifest-validation code.",
+    "entry": {
+        "kind": "blueprint",
+        "mcpTools": [{ "server": "acme/crm", "tool": "list_invoices" }]
+    },
+    "expect": { "outcome": "reject", "code": "manifest_invalid" }
+}

package/dist/binding-conformance/cases/bind-reject-too-many-entries.json

@@ -0,0 +1,27 @@
+{
+    "name": "bind-reject-too-many-entries",
+    "description": "Seventeen binding entries — one past the 16-entry cap. The manifest MUST be rejected with the manifest-validation code.",
+    "entry": {
+        "kind": "blueprint",
+        "mcpTools": [
+            { "tool": "tool_01" },
+            { "tool": "tool_02" },
+            { "tool": "tool_03" },
+            { "tool": "tool_04" },
+            { "tool": "tool_05" },
+            { "tool": "tool_06" },
+            { "tool": "tool_07" },
+            { "tool": "tool_08" },
+            { "tool": "tool_09" },
+            { "tool": "tool_10" },
+            { "tool": "tool_11" },
+            { "tool": "tool_12" },
+            { "tool": "tool_13" },
+            { "tool": "tool_14" },
+            { "tool": "tool_15" },
+            { "tool": "tool_16" },
+            { "tool": "tool_17" }
+        ]
+    },
+    "expect": { "outcome": "reject", "code": "manifest_invalid" }
+}

package/dist/binding-conformance/cases/filter-case-sensitive-server.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-case-sensitive-server",
+    "description": "Server matching is case-sensitive exact — `acme-crm` does not match an entry declaring `Acme-CRM`, even with an exact tool match on the same entry.",
+    "bindings": [{ "server": "Acme-CRM", "tool": "list_invoices" }],
+    "filters": { "server": "acme-crm", "tool": "list_invoices" },
+    "expect": false
+}

package/dist/binding-conformance/cases/filter-case-sensitive-tool.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-case-sensitive-tool",
+    "description": "Tool matching is case-sensitive exact — MCP tool names are case-sensitive, so `list_invoices` does not match an entry bound to `List_Invoices`.",
+    "bindings": [{ "tool": "List_Invoices" }],
+    "filters": { "tool": "list_invoices" },
+    "expect": false
+}

package/dist/binding-conformance/cases/filter-none-passes-bound.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-none-passes-bound",
+    "description": "No tool/server filters at all: the predicate passes every artifact — the binding dimensions only constrain when asked, preserving AND-composition with unrelated search filters.",
+    "bindings": [{ "server": "acme-crm", "tool": "list_invoices" }],
+    "filters": {},
+    "expect": true
+}

package/dist/binding-conformance/cases/filter-none-passes-unbound.json

@@ -0,0 +1,6 @@
+{
+    "name": "filter-none-passes-unbound",
+    "description": "No filters, and the artifact has no bindings at all: still passes — artifacts without bindings stay findable by every non-tool search dimension.",
+    "filters": {},
+    "expect": true
+}

package/dist/binding-conformance/cases/filter-pair-bare-never-matches.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-pair-bare-never-matches",
+    "description": "A bare entry never satisfies a pair query even when the tool name matches — the server dimension requires an explicit server declaration.",
+    "bindings": [{ "tool": "list_invoices" }],
+    "filters": { "server": "acme-crm", "tool": "list_invoices" },
+    "expect": false
+}

package/dist/binding-conformance/cases/filter-pair-exact.json

@@ -0,0 +1,10 @@
+{
+    "name": "filter-pair-exact",
+    "description": "`tool=` + `server=` together match only an entry carrying exactly that `(server, tool)` pair.",
+    "bindings": [
+        { "server": "acme-crm", "tool": "list_invoices" },
+        { "server": "other-crm", "tool": "export_csv" }
+    ],
+    "filters": { "server": "acme-crm", "tool": "list_invoices" },
+    "expect": true
+}

package/dist/binding-conformance/cases/filter-pair-not-cross-entry.json

@@ -0,0 +1,10 @@
+{
+    "name": "filter-pair-not-cross-entry",
+    "description": "The pair filter is per-entry, not per-list: one entry matching the server and a DIFFERENT entry matching the tool is NOT a match — both dimensions must land on the same entry.",
+    "bindings": [
+        { "server": "acme-crm", "tool": "create_invoice" },
+        { "server": "other-crm", "tool": "list_invoices" }
+    ],
+    "filters": { "server": "acme-crm", "tool": "list_invoices" },
+    "expect": false
+}

package/dist/binding-conformance/cases/filter-server-excludes-bare.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-server-excludes-bare",
+    "description": "`server=` alone NEVER matches a bare entry — a server-agnostic binding declares no server, so it cannot satisfy a server query.",
+    "bindings": [{ "tool": "list_invoices" }],
+    "filters": { "server": "acme-crm" },
+    "expect": false
+}

package/dist/binding-conformance/cases/filter-server-match.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-server-match",
+    "description": "`server=` alone matches any entry that explicitly declares that server, whatever its tool.",
+    "bindings": [{ "server": "acme-crm", "tool": "list_invoices" }],
+    "filters": { "server": "acme-crm" },
+    "expect": true
+}

package/dist/binding-conformance/cases/filter-tool-cross-server.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-tool-cross-server",
+    "description": "`tool=` alone matches any entry carrying that tool name regardless of which server qualifies it — a server-qualified entry satisfies a bare tool query.",
+    "bindings": [{ "server": "acme-crm", "tool": "list_invoices" }, { "tool": "export_csv" }],
+    "filters": { "tool": "list_invoices" },
+    "expect": true
+}

package/dist/binding-conformance/cases/filter-tool-excludes-unbound.json

@@ -0,0 +1,6 @@
+{
+    "name": "filter-tool-excludes-unbound",
+    "description": "`tool=` with an artifact that has no bindings matches nothing — unbound artifacts are invisible to tool-dimension queries.",
+    "filters": { "tool": "list_invoices" },
+    "expect": false
+}

package/dist/binding-conformance/cases/filter-tool-matches-bare-entry.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-tool-matches-bare-entry",
+    "description": "`tool=` alone also matches a bare (server-agnostic) entry — the tool dimension ignores server identity entirely.",
+    "bindings": [{ "tool": "list_invoices" }],
+    "filters": { "tool": "list_invoices" },
+    "expect": true
+}

package/dist/binding-conformance/cases/filter-tool-no-match.json

@@ -0,0 +1,7 @@
+{
+    "name": "filter-tool-no-match",
+    "description": "`tool=` alone with no entry carrying that tool name matches nothing.",
+    "bindings": [{ "server": "acme-crm", "tool": "create_invoice" }],
+    "filters": { "tool": "list_invoices" },
+    "expect": false
+}