@nanobpm/urban 0.87.0 → 0.88.0

package/dist/runtime/core/modules/mcp.d.ts

@@ -1,3 +1,4 @@
+import { type OpenApiDoc, type OpenApiSchema, type OperationInfo } from "../../../openapi/spec.ts";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { HttpRequest } from "../host.ts";
 import { type Route } from "../router.ts";
@@ -64,6 +65,33 @@ export declare function readHeader(headers: Record<string, string | string[] | u
  *  required is enough to have missing (or whitespace-only) calls rejected rather than silently
  *  substituted with an empty string. */
 export declare function missingRequiredArgs(inputSchema: Record<string, unknown>, args: Record<string, unknown>): string[];
+/** 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 declare function effectiveRequestBodySchema(op: OperationInfo, doc: OpenApiDoc | undefined): OpenApiSchema | undefined;
+/** 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 declare function structuredBodyKind(schema: OpenApiSchema | undefined): "object" | "array" | 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 declare function normalizeBodyArg(op: OperationInfo, args: Record<string, unknown>, doc: OpenApiDoc | undefined): {
+    ok: true;
+    args: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Mount the runtime-served MCP surface at `/app/mcp` (ADR 0067). Returns a single `*`-method route
  * (mounted unconditionally, like `/app/agent`); the handler bridges the host request/response seam

package/dist/runtime/core/modules/mcp.js

@@ -34,7 +34,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, isInitializeRequest, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { GENERATED_DIR } from "../../../toolkit/artifact.js";
 import { SYSTEM_BRIEF_JSON } from "../../../toolkit/derivers/system-brief.js";
-import { collectOperations, evaluateSecurity, isMutatingMethod, parseSpec, sharedSecretSchemeName, toolInputSchema, } from "../../../openapi/spec.js";
+import { collectOperations, evaluateSecurity, isMutatingMethod, isObjectSchema, parseSpec, resolveSchema, schemaHasType, sharedSecretSchemeName, toolInputSchema, } from "../../../openapi/spec.js";
 import { errorMessage } from "../guards.js";
 import { presentFormIdentifier } from "../host.js";
 import { resolveBindMode } from "../manifest.js";
@@ -257,6 +257,10 @@ export function missingRequiredArgs(inputSchema, args) {
  *  read-only) app operation is then guarded exactly as its HTTP route is — the app operation tools
  *  inherit the OpenAPI `security` contract rather than a bespoke MCP gate (ADR 0067 §4). */
 function toHttpRequest(op, args, forwardHeaders) {
+    // `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)
         : "";
@@ -277,6 +281,69 @@ function toHttpRequest(op, args, forwardHeaders) {
         text: () => Promise.resolve(bodyText),
     };
 }
+/** 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, doc) {
+    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) {
+    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, args, doc) {
+    const body = args.body;
+    const kind = structuredBodyKind(effectiveRequestBodySchema(op, doc));
+    if (body === undefined || kind === undefined || typeof body !== "string") {
+        return { ok: true, args };
+    }
+    let parsed;
+    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, isError = false) {
@@ -716,10 +783,17 @@ export function mountMcp(ctx, app, apiRoutes) {
             // empty-string substitution — the calling agent sees exactly which required params it omitted.
             return textResult({ error: `validation failed: missing required path parameter(s): ${missing.join(", ")}` }, 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/dist/runtime/mcp-conformance.d.ts

@@ -0,0 +1,49 @@
+import { type OpenApiDoc, type OperationInfo } from "../openapi/spec.ts";
+/** 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 declare const CONSUMER_SPECS: ConsumerSpec[];
+/** 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;
+};
+/** 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 declare function findSpecConformanceViolations(label: string, doc: OpenApiDoc, normalizeBody?: BodyNormalizer): string[];
+/** Parse a vendored consumer spec from disk into an {@link OpenApiDoc}. */
+export declare function loadConsumerSpec(spec: ConsumerSpec): OpenApiDoc;
+/** 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 declare function runConsumerConformance(specs?: readonly ConsumerSpec[]): SpecConformanceResult[];

package/dist/runtime/mcp-conformance.js

@@ -0,0 +1,132 @@
+// 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, parseSpec, toolInputSchema, } from "../openapi/spec.js";
+import { effectiveRequestBodySchema, normalizeBodyArg, structuredBodyKind } from "./core/modules/mcp.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SPECS_DIR = resolve(HERE, "../openapi/consumer-specs");
+/** 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 = [
+    {
+        label: "nano-workforce",
+        repo: "nanobpm/nano-workforce",
+        ref: "2018020a290c2f416e703e3584b27f92ccf27753",
+        file: resolve(SPECS_DIR, "nano-workforce.openapi.yaml"),
+    },
+];
+function describe(e) {
+    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, kind) {
+    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, op, kind, doc, normalizeBody) {
+    const violations = [];
+    const sample = 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, doc, normalizeBody = normalizeBodyArg) {
+    let ops;
+    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 = [];
+    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;
+        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) {
+    return parseSpec(readFileSync(spec.file, "utf8"));
+}
+/** 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 = CONSUMER_SPECS) {
+    return specs.map((spec) => {
+        let doc;
+        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) };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.87.0",
+	"version": "0.88.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -95,6 +95,7 @@
 		"check:runtime": "node scripts/gen-runtime.mjs --check",
 		"gen:mcp-tools": "node --experimental-strip-types scripts/gen-mcp-tools.ts",
 		"check:mcp": "node --experimental-strip-types scripts/gen-mcp-tools.ts --check",
+		"check:mcp-conformance": "node --experimental-strip-types scripts/check-mcp-conformance.ts",
 		"test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",
 		"test:conformance": "node --test --experimental-strip-types \"src/context/conformance/**/*.conformance.ts\"",
 		"check:pii": "node --experimental-strip-types scripts/check-pii.ts",

package/src/openapi/consumer-specs/README.md

@@ -0,0 +1,51 @@
+# Vendored consumer OpenAPI specs (MCP projection conformance corpus)
+
+These are **real** hosted-app `openapi.yaml` documents, vendored and **pinned to a
+specific commit**, that the MCP projection is held to by
+`npm run check:mcp-conformance -w packages/urban` (wired into CI). Unlike the minimal
+synthetic `mcp-parity.fixture.yaml`, these are the actual specs consumer apps ship —
+so a projection change (or a spec change) that would advertise a broken tool to an
+MCP client fails the build here, on the surface where the `$ref`-body defect
+(nanobpm/nano-ide#501) originally surfaced.
+
+For every projected (non-`x-mcp`-excluded) tool the guard asserts the properties
+P0 (nanobpm/nano-ide#502) and P1 (nanobpm/nano-ide#503) established:
+
+- **Self-contained input schema** — no unresolved `$ref` and an explicit `type` on
+  `body` (a client cannot resolve `#/components/...` outside the source document).
+- **Faithful object-body transport** — an object/array body round-trips: an object
+  argument reaches the door as an object, and a pre-encoded JSON-string body is
+  parsed once (never double-encoded).
+
+The guard needs **no running instance** — it projects the vendored file directly.
+
+## Corpus
+
+| Spec | Source repo | Pinned ref |
+| --- | --- | --- |
+| `nano-workforce.openapi.yaml` | [`nanobpm/nano-workforce`](https://github.com/nanobpm/nano-workforce) | `2018020a290c2f416e703e3584b27f92ccf27753` |
+
+The pin is the single source of truth in code: `CONSUMER_SPECS` in
+`../../runtime/mcp-conformance.ts` (`ref` field) records the same commit. Keep the
+table above in sync with that `ref` when refreshing a pin. `mcp-conformance.test.ts`
+asserts each `ref` is a full 40-hex commit SHA (so a mutable branch/tag pin cannot
+make the guard non-deterministic); it does not verify the table ↔ code ↔ vendored
+bytes provenance, so update both together by hand.
+
+## Refreshing a pinned spec
+
+Vendoring is deliberate — the check must be deterministic and offline. To bump a pin,
+re-fetch the file at a new commit and update the `ref` in `CONSUMER_SPECS` (and the
+table above) in the **same** commit, then re-run the guard:
+
+```sh
+REF=<new-commit-sha>
+gh api "repos/nanobpm/nano-workforce/contents/openapi.yaml?ref=$REF" \
+  --jq '.content' | base64 -d \
+  > packages/urban/src/openapi/consumer-specs/nano-workforce.openapi.yaml
+# update CONSUMER_SPECS[].ref to $REF, then:
+npm run check:mcp-conformance -w packages/urban
+```
+
+If a refreshed spec would project a broken tool the guard fails — then either the
+projection (`openapi/spec.ts`) or the offending consumer spec is fixed deliberately.