@nanobpm/urban 0.87.0 → 0.88.0

package/src/openapi/mcp-parity.fixture.yaml

@@ -19,6 +19,11 @@
 #                                          self-contained (no `$ref`, explicit
 #                                          `type`) — an MCP client cannot resolve
 #                                          `#/components/...` outside this document.
+#   - an INLINE object-body op (POST)    → its request body declares `type: object`
+#                                          inline, exercising the faithful object-body
+#                                          transport path (object arg → door receives
+#                                          an object; a pre-encoded JSON string is
+#                                          parsed, not double-encoded).
 #
 # Edit this fixture ONLY together with a reviewed `npm run gen:mcp-tools`.
 openapi: 3.1.0
@@ -93,3 +98,25 @@ paths:
       responses:
         "200":
           description: ok
+  /widgets/bulk:
+    post:
+      operationId: bulkCreateWidgets
+      summary: "Bulk create widgets (mutating — inline `type: object` request body, object-arg round-trip case)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - items
+              properties:
+                items:
+                  type: array
+                  items:
+                    type: string
+                dryRun:
+                  type: boolean
+      responses:
+        "201":
+          description: created

package/src/openapi/mcp-tools.snapshot.json

@@ -64,5 +64,36 @@
       "type": "object",
       "properties": {}
     }
+  },
+  {
+    "operationId": "bulkCreateWidgets",
+    "method": "post",
+    "mutating": true,
+    "excluded": false,
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "body": {
+          "type": "object",
+          "required": [
+            "items"
+          ],
+          "properties": {
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "dryRun": {
+              "type": "boolean"
+            }
+          }
+        }
+      },
+      "required": [
+        "body"
+      ]
+    }
   }
 ]

package/src/runtime/core/modules/mcp.test.ts

@@ -356,6 +356,130 @@ test("a $ref-bodied tool projects a self-contained body schema (no $ref, explici
   assert.ok(!JSON.stringify(schema).includes("$ref"), "projected body schema must not leak a $ref");
 });
 
+test("an object body reaches the door as an object; a pre-encoded JSON-string body is parsed, not double-encoded; a malformed string body is a clear error", async () => {
+  // `createInvoice`'s requestBody is `{ $ref: "#/components/schemas/Invoice" }` — an object body
+  // whose concrete `type` is only visible after the projection resolver inlines the component. The
+  // transport must classify it as an object body FROM THE RESOLVED SCHEMA (not the raw `$ref`) so the
+  // string-parse path triggers for exactly this motivating shape, not merely an inline-`type` body.
+  let seenBody: unknown = "unset";
+  const { router } = buildHarness({
+    modules: {
+      "/app/operations/createInvoice": {
+        default: (input: { body: unknown }) => {
+          seenBody = input.body;
+          return { body: { ok: true } };
+        },
+      },
+    },
+  });
+  const session = await connect(router);
+
+  // 1. A genuine object argument reaches the door (the reused delegate) AS AN OBJECT.
+  const objCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: { id: "7", amount: 3 } },
+  });
+  assert.notEqual(objCall.result?.isError, true, `object body call must succeed: ${toolContentText(objCall.result)}`);
+  assert.deepEqual(seenBody, { id: "7", amount: 3 }, "an object body argument must reach the door as an object");
+
+  // 2. A PRE-ENCODED JSON-string body is accepted and parsed — NOT double-encoded into a quoted
+  //    string the door would reject with "expected object, got string".
+  seenBody = "unset";
+  const strCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: JSON.stringify({ id: "9", amount: 5 }) },
+  });
+  assert.notEqual(strCall.result?.isError, true, `pre-encoded string body must be accepted: ${toolContentText(strCall.result)}`);
+  assert.deepEqual(seenBody, { id: "9", amount: 5 }, "a pre-encoded JSON-string body must be parsed to an object at the door");
+
+  // 3. A malformed string body is a CLEAR tool error naming the expected shape — never a silent 4xx
+  //    from a forwarded double-encoded body, and the delegate must not run.
+  seenBody = "unset";
+  const badCall = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: "{not valid json" },
+  });
+  assert.equal(badCall.result?.isError, true, "a malformed string body must return an isError result");
+  assert.match(toolContentText(badCall.result), /object/i, "the error must name the expected object shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a malformed string body");
+
+  // 4. A string that parses to the WRONG shape (a scalar) is likewise a clear error, not a
+  //    double-encoded forward — the object body path fails loudly on a non-object.
+  seenBody = "unset";
+  const wrongShape = await rpc(router, session, "tools/call", {
+    name: "createInvoice",
+    arguments: { body: "42" },
+  });
+  assert.equal(wrongShape.result?.isError, true, "a string parsing to a scalar must return an isError result");
+  assert.match(toolContentText(wrongShape.result), /object/i, "the error must name the expected object shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a wrong-shape string body");
+});
+
+test("an array body reaches the door as an array; a pre-encoded JSON-string array body is parsed, not double-encoded; a wrong-shape string is a clear error", async () => {
+  // Mirror of the object-body transport test for the ARRAY branch: `structuredBodyKind` can return
+  // "array" and `normalizeBodyArg` has an `Array.isArray(parsed)` path, so a regression in array
+  // handling must be caught here. `createBatch`'s requestBody declares a `type: array` body — the
+  // transport must classify it as an array body and parse a pre-encoded JSON-string array once so it
+  // round-trips as an array rather than being double-encoded into a quoted string the door rejects.
+  const arraySpec = JSON.stringify({
+    openapi: "3.0.0",
+    paths: {
+      "/batch": {
+        post: {
+          operationId: "createBatch",
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { type: "array", items: { type: "string" } } } },
+          },
+          responses: { "201": {} },
+        },
+      },
+    },
+  });
+  let seenBody: unknown = "unset";
+  const { router } = buildHarness({
+    spec: arraySpec,
+    modules: {
+      "/app/operations/createBatch": {
+        default: (input: { body: unknown }) => {
+          seenBody = input.body;
+          return { body: { ok: true } };
+        },
+      },
+    },
+  });
+  const session = await connect(router);
+
+  // 1. A genuine array argument reaches the door (the reused delegate) AS AN ARRAY.
+  const arrCall = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: ["a", "b"] },
+  });
+  assert.notEqual(arrCall.result?.isError, true, `array body call must succeed: ${toolContentText(arrCall.result)}`);
+  assert.deepEqual(seenBody, ["a", "b"], "an array body argument must reach the door as an array");
+
+  // 2. A PRE-ENCODED JSON-string array body is accepted and parsed — NOT double-encoded into a quoted
+  //    string the door would reject with "expected array, got string".
+  seenBody = "unset";
+  const strCall = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: JSON.stringify(["a", "b"]) },
+  });
+  assert.notEqual(strCall.result?.isError, true, `pre-encoded string array body must be accepted: ${toolContentText(strCall.result)}`);
+  assert.deepEqual(seenBody, ["a", "b"], "a pre-encoded JSON-string array body must be parsed to an array at the door");
+
+  // 3. A string that parses to the WRONG shape (an object) is a clear error naming the expected
+  //    array shape, not a double-encoded forward — and the delegate must not run.
+  seenBody = "unset";
+  const wrongShape = await rpc(router, session, "tools/call", {
+    name: "createBatch",
+    arguments: { body: JSON.stringify({ not: "an array" }) },
+  });
+  assert.equal(wrongShape.result?.isError, true, "a string parsing to an object must return an isError result");
+  assert.match(toolContentText(wrongShape.result), /array/i, "the error must name the expected array shape");
+  assert.equal(seenBody, "unset", "the door delegate must not run for a wrong-shape string array body");
+});
+
 test("a tool call routes through the SAME mountApi delegate as the HTTP call", async () => {
   let seenParams: Record<string, unknown> | undefined;
   const { router, imported } = buildHarness({

package/src/runtime/core/modules/mcp.ts

@@ -50,9 +50,13 @@ import {
   collectOperations,
   evaluateSecurity,
   isMutatingMethod,
+  isObjectSchema,
   type OpenApiDoc,
+  type OpenApiSchema,
   type OperationInfo,
   parseSpec,
+  resolveSchema,
+  schemaHasType,
   type SecurityDecision,
   sharedSecretSchemeName,
   toolInputSchema,
@@ -336,6 +340,10 @@ function toHttpRequest(
   args: Record<string, unknown>,
   forwardHeaders: Record<string, string | string[] | undefined>,
 ): HttpRequest {
+  // `args.body` is expected to already be the structured value the operation declares — a
+  // pre-encoded JSON-string body is normalized upstream by `normalizeBodyArg` (called in
+  // `dispatchOperationTool`) so `JSON.stringify` here serializes an object/array ONCE rather than
+  // double-encoding a quoted string the door would reject (ADR 0067).
   const bodyText = op.requestBodySchema !== undefined && args.body !== undefined
     ? JSON.stringify(args.body)
     : "";
@@ -354,6 +362,76 @@ function toHttpRequest(
   };
 }
 
+/** The operation's effective request-body schema for classifying a tool-call `body`: P0's resolved,
+ *  `$ref`-free schema ({@link OperationInfo.requestBodySchemaResolved}, produced by
+ *  `collectOperations`). As defence in depth, if that metadata is somehow still a bare `$ref` (it
+ *  should never be after resolution), re-resolve it via {@link resolveSchema} against `doc` so the
+ *  classification below never keys off an opaque `#/components/...` pointer. */
+export function effectiveRequestBodySchema(
+  op: OperationInfo,
+  doc: OpenApiDoc | undefined,
+): OpenApiSchema | undefined {
+  const schema = op.requestBodySchemaResolved ?? op.requestBodySchema;
+  if (schema?.$ref) return doc ? resolveSchema(doc, schema) : undefined;
+  return schema;
+}
+
+/** Whether the operation declares a STRUCTURED (object/array) request body — the shapes the app door
+ *  expects as a JSON object/array rather than a bare scalar. Classified from the RESOLVED schema so a
+ *  `$ref`-bodied op (e.g. `previewDeliveryGraph`, whose object `type` is only visible after P0's
+ *  resolution) is recognized, not merely an inline-`type` object body. */
+export function structuredBodyKind(schema: OpenApiSchema | undefined): "object" | "array" | undefined {
+  if (!schema) return undefined;
+  if (isObjectSchema(schema)) return "object";
+  if (schemaHasType(schema, "array")) return "array";
+  return undefined;
+}
+
+/** Normalize a tool-call `body` argument for FAITHFUL transport (ADR 0067). A client that saw an
+ *  opaque input schema — or that coerces non-primitive args — may send `body` as a pre-encoded JSON
+ *  *string* instead of the object/array the operation declares. Left as-is, `toHttpRequest`'s
+ *  `JSON.stringify` would DOUBLE-encode it into a quoted string and the door would reject it with
+ *  "expected object, got string". So when the op declares an object/array body and `body` arrives as
+ *  a string, parse it once so it round-trips as the structured value. A genuine object/array argument
+ *  passes through untouched (still serialized by the transport). A string that does not parse to the
+ *  declared shape is a CLEAR tool error naming the expected shape — never a silently double-encoded
+ *  (and 4xx-rejected) request. */
+export function normalizeBodyArg(
+  op: OperationInfo,
+  args: Record<string, unknown>,
+  doc: OpenApiDoc | undefined,
+): { ok: true; args: Record<string, unknown> } | { ok: false; error: string } {
+  const body = args.body;
+  const kind = structuredBodyKind(effectiveRequestBodySchema(op, doc));
+  if (body === undefined || kind === undefined || typeof body !== "string") {
+    return { ok: true, args };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return {
+      ok: false,
+      error:
+        `validation failed: the "body" argument was sent as a string but this operation expects a JSON ${kind}; the string is not valid JSON`,
+    };
+  }
+  const parsedKind = Array.isArray(parsed)
+    ? "array"
+    : parsed !== null && typeof parsed === "object"
+      ? "object"
+      : undefined;
+  if (parsedKind !== kind) {
+    const got = parsedKind ?? (parsed === null ? "null" : typeof parsed);
+    return {
+      ok: false,
+      error:
+        `validation failed: the "body" argument was sent as a string but this operation expects a JSON ${kind}; it parsed to a ${got}`,
+    };
+  }
+  return { ok: true, args: { ...args, body: parsed } };
+}
+
 /** Wrap a value as an MCP tool text result. A JSON payload is stringified; `isError` flags a
  *  non-2xx dispatch so the client sees the failure (carrying the delegate's own error body). */
 function textResult(value: unknown, isError = false): {
@@ -838,10 +916,16 @@ export function mountMcp(ctx: RuntimeContext, app: AppApi, apiRoutes: Route[]):
         true,
       );
     }
+    // Faithful body transport (ADR 0067): a client may send an object/array `body` pre-encoded as a
+    // JSON string. Normalize it to the structured value from the operation's RESOLVED body schema so
+    // it is not double-encoded by `toHttpRequest`; a string that cannot parse to the declared shape
+    // is a clear tool error rather than a silent 4xx from a double-encoded body.
+    const normalized = normalizeBodyArg(op, args, (await loadSpecDoc()).doc);
+    if (!normalized.ok) return textResult({ error: normalized.error }, true);
     // Forward the MCP connection's headers so the reused router enforces the operation's own
     // OpenAPI `security` (a mutating — or secured read — app op is guarded exactly as its HTTP
     // route). A `401`/`403`/`500` from that enforcement flows back as an error tool result.
-    const res = await apiRouter(toHttpRequest(op, args, headers));
+    const res = await apiRouter(toHttpRequest(op, normalized.args, headers));
     const status = res.status ?? 200;
     return textResult(res.body ?? "", status >= 400);
   };

package/src/runtime/mcp-conformance.test.ts

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { collectOperations, parseSpec } from "../openapi/spec.ts";
+import {
+  type BodyNormalizer,
+  CONSUMER_SPECS,
+  findSpecConformanceViolations,
+  loadConsumerSpec,
+  runConsumerConformance,
+} from "./mcp-conformance.ts";
+import { normalizeBodyArg, structuredBodyKind, effectiveRequestBodySchema } from "./core/modules/mcp.ts";
+
+// The whole corpus conforms: every projected tool in every vendored real consumer spec is
+// self-contained (P0 #502) and every object-body op round-trips through the real transport (P1 #503).
+test("consumer conformance corpus projects only conformant MCP tools", () => {
+  const results = runConsumerConformance();
+  assert.ok(results.length > 0, "expected at least one vendored consumer spec");
+  for (const { label, violations } of results) {
+    assert.deepEqual(violations, [], `${label} should project conformant tools, got:\n${violations.join("\n")}`);
+  }
+});
+
+// Guard against a VACUOUS pass: the vendored spec must actually contain the shape the projection
+// previously broke on — projected, non-excluded, structured-body operations — or the round-trip
+// property below never runs and the guard proves nothing.
+test("nano-workforce spec actually exercises the structured-body projection path", () => {
+  const spec = CONSUMER_SPECS.find((s) => s.label === "nano-workforce");
+  assert.ok(spec, "nano-workforce must be in the corpus");
+  const doc = loadConsumerSpec(spec);
+  const structured = collectOperations(doc).filter(
+    (op) => !op.mcpExcluded && structuredBodyKind(effectiveRequestBodySchema(op, doc)) !== undefined,
+  );
+  assert.ok(
+    structured.length > 0,
+    "expected nano-workforce to project at least one non-excluded object/array-body tool",
+  );
+});
+
+// The pinned ref recorded in code is the single source of truth; keep it a 40-hex commit SHA so a
+// refresh cannot land a mutable ref (branch/tag) that would make the guard non-deterministic.
+test("every consumer spec is pinned to a concrete commit SHA", () => {
+  for (const spec of CONSUMER_SPECS) {
+    assert.match(spec.ref, /^[0-9a-f]{40}$/, `${spec.label} ref must be a full commit SHA, got ${spec.ref}`);
+  }
+});
+
+// Negative — REINTRODUCED DOUBLE-ENCODING: a transport that leaves a pre-encoded string body a
+// string (the pre-P1 #503 behaviour) must make the conformance guard FAIL on the real spec.
+test("a reintroduced double-encoding path fails conformance", () => {
+  const spec = CONSUMER_SPECS.find((s) => s.label === "nano-workforce");
+  assert.ok(spec);
+  const doc = loadConsumerSpec(spec);
+
+  const doubleEncoding: BodyNormalizer = (_op, args) => ({ ok: true, args }); // never parses a string body
+
+  const violations = findSpecConformanceViolations(spec.label, doc, doubleEncoding);
+  assert.ok(violations.length > 0, "double-encoding transport must be caught");
+  assert.ok(
+    violations.some((v) => v.includes("double-encoding path was reintroduced")),
+    `expected a double-encoding violation, got:\n${violations.join("\n")}`,
+  );
+});
+
+// Positive control: with the REAL transport the same spec conforms — so the negative test above is
+// detecting the injected regression, not a pre-existing failure.
+test("the real transport conforms on the same spec", () => {
+  const spec = CONSUMER_SPECS.find((s) => s.label === "nano-workforce");
+  assert.ok(spec);
+  const doc = loadConsumerSpec(spec);
+  assert.deepEqual(findSpecConformanceViolations(spec.label, doc, normalizeBodyArg), []);
+});
+
+// Negative — REINTRODUCED $ref LEAK: a body whose `$ref` cannot be made self-contained (dangling
+// component) must fail the guard rather than leak an opaque `#/components/...` pointer to a client.
+test("an unresolvable $ref body fails conformance", () => {
+  const doc = parseSpec(`
+openapi: 3.0.0
+info: { title: leak, version: "1" }
+paths:
+  /widgets:
+    post:
+      operationId: createWidget
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/DoesNotExist" }
+      responses:
+        "200": { description: ok }
+components:
+  schemas: {}
+`);
+  const violations = findSpecConformanceViolations("leak-fixture", doc);
+  assert.ok(violations.length > 0, "an unresolvable $ref body must be caught");
+  assert.ok(
+    violations.some((v) => v.includes("projection failed")),
+    `expected a projection-failure violation, got:\n${violations.join("\n")}`,
+  );
+});
+
+// Negative — a `body` that projects WITHOUT an explicit `type` (P0's other property) is caught: a
+// client cannot tell it is an object/array and mis-encodes the argument.
+test("a body schema without an explicit type fails conformance", () => {
+  const doc = parseSpec(`
+openapi: 3.0.0
+info: { title: untyped, version: "1" }
+paths:
+  /widgets:
+    post:
+      operationId: createWidget
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              properties:
+                name: { type: string }
+      responses:
+        "200": { description: ok }
+`);
+  const violations = findSpecConformanceViolations("untyped-fixture", doc);
+  assert.ok(
+    violations.some((v) => v.includes("no explicit `type`")),
+    `expected an explicit-type violation, got:\n${violations.join("\n")}`,
+  );
+});

package/src/runtime/mcp-conformance.ts

@@ -0,0 +1,199 @@
+// Real-spec MCP projection conformance guard (ADR 0067 · epic nanobpm/nano-ide#501, P2 #504).
+//
+// WHY THIS EXISTS
+// The `check:mcp` parity guard exercises the projection's branches on a MINIMAL SYNTHETIC document
+// (`mcp-parity.fixture.yaml`). That is exactly why the `$ref`-body defect shipped: the fixture never
+// contained a `$ref`-bodied operation, while a real consumer app's `openapi.yaml` (nano-workforce,
+// ADR 0067's first consumer) does. This guard closes that gap — it projects the projection over
+// VENDORED, pinned, REAL consumer specs and asserts, for every projected (non-`x-mcp`-excluded)
+// tool, the two properties the fix established:
+//
+//   - P0 (#502) — the tool's `inputSchema` is SELF-CONTAINED: no unresolved `$ref` (a client cannot
+//     follow `#/components/...` outside the source document) and an explicit `type` on `body`.
+//   - P1 (#503) — an object/array body ROUND-TRIPS through the real transport: an object argument
+//     reaches the door as an object, and a pre-encoded JSON-string body is parsed once, never
+//     double-encoded into a quoted string the door would reject.
+//
+// It reuses the EXACT projection + transport code both properties landed in (`toolInputSchema` /
+// `findToolSchemaViolations` from `openapi/spec.ts`, and `normalizeBodyArg` from `mcp.ts`) rather
+// than reimplementing a second, driftable copy (ADR 0053) — so a regression in either surface is
+// caught here over a real spec, not discovered by a client. It needs NO running instance: the
+// vendored file is projected directly.
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  collectOperations,
+  findToolSchemaViolations,
+  type OpenApiDoc,
+  type OperationInfo,
+  parseSpec,
+  toolInputSchema,
+} from "../openapi/spec.ts";
+import { effectiveRequestBodySchema, normalizeBodyArg, structuredBodyKind } from "./core/modules/mcp.ts";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SPECS_DIR = resolve(HERE, "../openapi/consumer-specs");
+
+/** A vendored, pinned consumer OpenAPI spec the MCP projection is held to. Pinned to a specific
+ *  commit so the guard is deterministic and offline (no live-instance dependency). The `ref` here is
+ *  the single in-code source of truth for the pin — `mcp-conformance.test.ts` asserts it is a full
+ *  40-hex commit SHA (so a mutable branch/tag ref can't make the guard non-deterministic), and
+ *  `consumer-specs/README.md` documents the same commit. The test does not verify that `ref` matches
+ *  the vendored bytes' provenance, so keep code, README, and bytes in sync when refreshing a pin. */
+export interface ConsumerSpec {
+  /** Short label used in violation messages, e.g. "nano-workforce". */
+  label: string;
+  /** Source repository the spec was vendored from, `owner/repo`. */
+  repo: string;
+  /** The commit SHA the vendored file is pinned to. */
+  ref: string;
+  /** Absolute path to the vendored `openapi.yaml`. */
+  file: string;
+}
+
+/** The conformance corpus: real hosted-app specs, pinned. nano-workforce first (ADR 0067's first
+ *  consumer, where the `$ref`-body mismatch surfaced). Add further consumer specs here as they
+ *  adopt the projection. */
+export const CONSUMER_SPECS: ConsumerSpec[] = [
+  {
+    label: "nano-workforce",
+    repo: "nanobpm/nano-workforce",
+    ref: "2018020a290c2f416e703e3584b27f92ccf27753",
+    file: resolve(SPECS_DIR, "nano-workforce.openapi.yaml"),
+  },
+];
+
+/** The transport normalizer the round-trip property is checked against — the real
+ *  {@link normalizeBodyArg} in production, injectable so a test can prove a REINTRODUCED
+ *  double-encoding path (a normalizer that leaves a pre-encoded string body a string) fails the
+ *  guard. */
+export type BodyNormalizer = (
+  op: OperationInfo,
+  args: Record<string, unknown>,
+  doc: OpenApiDoc | undefined,
+) => { ok: true; args: Record<string, unknown> } | { ok: false; error: string };
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** Whether a value is the structured JSON shape the operation declares — an object for an `"object"`
+ *  body, an array for an `"array"` body. Used to assert a body reaches the door as the right shape
+ *  (not a JSON string, not a scalar). */
+function isKind(value: unknown, kind: "object" | "array"): boolean {
+  if (kind === "array") return Array.isArray(value);
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** The transport round-trip property (P1) for one structured-body operation, checked against the
+ *  real {@link normalizeBodyArg}. A representative empty instance of the declared shape must reach
+ *  the door as that shape both when the client sends it as a value AND when the client sends it
+ *  pre-encoded as a JSON string — the latter is what catches a reintroduced double-encoding path. */
+function checkBodyRoundTrip(
+  label: string,
+  op: OperationInfo,
+  kind: "object" | "array",
+  doc: OpenApiDoc,
+  normalizeBody: BodyNormalizer,
+): string[] {
+  const violations: string[] = [];
+  const sample: unknown = kind === "array" ? [] : {};
+
+  // (1) An object/array argument passes through the transport as that structured value.
+  const asValue = normalizeBody(op, { body: sample }, doc);
+  if (!asValue.ok) {
+    violations.push(`${label}: ${op.operationId}: object-body argument rejected by transport: ${asValue.error}`);
+  } else if (!isKind(asValue.args.body, kind)) {
+    violations.push(
+      `${label}: ${op.operationId}: object-body argument did not reach the door as a JSON ${kind}`,
+    );
+  }
+
+  // (2) A pre-encoded JSON string round-trips to the structured value — NOT a double-encoded string.
+  const asString = normalizeBody(op, { body: JSON.stringify(sample) }, doc);
+  if (!asString.ok) {
+    violations.push(
+      `${label}: ${op.operationId}: pre-encoded JSON-string body rejected by transport: ${asString.error}`,
+    );
+  } else if (!isKind(asString.args.body, kind)) {
+    violations.push(
+      `${label}: ${op.operationId}: pre-encoded JSON-string body did not round-trip to a JSON ${kind} ` +
+        "(a double-encoding path was reintroduced)",
+    );
+  }
+
+  return violations;
+}
+
+/** Every conformance violation the projection would advertise for one spec document. Empty means
+ *  every projected tool is self-contained (P0) and every object/array body round-trips faithfully
+ *  through the real transport (P1). `normalizeBody` is injectable for negative tests; production uses
+ *  the real {@link normalizeBodyArg}. */
+export function findSpecConformanceViolations(
+  label: string,
+  doc: OpenApiDoc,
+  normalizeBody: BodyNormalizer = normalizeBodyArg,
+): string[] {
+  let ops: OperationInfo[];
+  try {
+    // `collectOperations` deep-resolves each projected op's `$ref`s and throws loudly on a cyclic or
+    // unresolvable ref — a spec that cannot project a self-contained schema fails HERE.
+    ops = collectOperations(doc);
+  } catch (e) {
+    return [`${label}: projection failed (unresolvable or cyclic $ref?): ${describe(e)}`];
+  }
+
+  const violations: string[] = [];
+  for (const op of ops) {
+    if (op.mcpExcluded) continue;
+
+    // P0: the projected input schema must be self-contained (no `$ref`, `body` explicitly typed).
+    let inputSchema: Record<string, unknown>;
+    try {
+      inputSchema = toolInputSchema(op);
+    } catch (e) {
+      violations.push(`${label}: ${op.operationId}: input schema could not be resolved: ${describe(e)}`);
+      continue;
+    }
+    for (const v of findToolSchemaViolations(op.operationId, inputSchema)) {
+      violations.push(`${label}: ${v}`);
+    }
+
+    // P1: an object/array body must round-trip through the real transport.
+    const kind = structuredBodyKind(effectiveRequestBodySchema(op, doc));
+    if (kind) {
+      violations.push(...checkBodyRoundTrip(label, op, kind, doc, normalizeBody));
+    }
+  }
+  return violations;
+}
+
+/** Parse a vendored consumer spec from disk into an {@link OpenApiDoc}. */
+export function loadConsumerSpec(spec: ConsumerSpec): OpenApiDoc {
+  return parseSpec(readFileSync(spec.file, "utf8"));
+}
+
+/** One consumer spec's conformance outcome — its label and every violation (empty when it conforms).
+ *  A spec whose FILE cannot be read/parsed surfaces as a single violation rather than throwing, so
+ *  the guard reports it uniformly. */
+export interface SpecConformanceResult {
+  label: string;
+  violations: string[];
+}
+
+/** Run the conformance guard over the whole {@link CONSUMER_SPECS} corpus (or an injected set). Each
+ *  spec is loaded and projected independently so one broken spec does not mask the others. */
+export function runConsumerConformance(specs: readonly ConsumerSpec[] = CONSUMER_SPECS): SpecConformanceResult[] {
+  return specs.map((spec) => {
+    let doc: OpenApiDoc;
+    try {
+      doc = loadConsumerSpec(spec);
+    } catch (e) {
+      return { label: spec.label, violations: [`${spec.label}: cannot load ${spec.file}: ${describe(e)}`] };
+    }
+    return { label: spec.label, violations: findSpecConformanceViolations(spec.label, doc) };
+  });
+}