@nanobpm/urban 0.86.0 → 0.87.0

package/dist/openapi/spec.d.ts

@@ -53,6 +53,11 @@ export interface OpenApiParameter {
     in: "path" | "query" | "header" | "cookie";
     required?: boolean;
     schema?: OpenApiSchema;
+    /** The parameter's schema with every local component `$ref` inlined (via {@link resolveSchemaDeep}),
+     *  so a consumer that cannot resolve `#/components/...` — e.g. an MCP client reading the projected
+     *  tool `inputSchema` — sees a self-contained schema. Absent when the parameter declares no schema.
+     *  The raw {@link schema} is retained for the type deriver, which maps a `$ref` to its named type. */
+    resolvedSchema?: OpenApiSchema;
 }
 export interface OpenApiMediaType {
     schema?: OpenApiSchema;
@@ -119,6 +124,16 @@ export interface OperationInfo {
     path: string;
     parameters: OpenApiParameter[];
     requestBodySchema?: OpenApiSchema;
+    /** The request-body schema with every local component `$ref` deeply inlined (via
+     *  {@link resolveSchemaDeep}), so it is self-contained: no `$ref`, and an explicit `type` where the
+     *  referenced component declared one. This is what the MCP tool projection copies into a tool's
+     *  `inputSchema.properties.body` — an MCP client cannot resolve `#/components/...` outside the
+     *  original document, so the projected schema must carry the concrete shape. The raw
+     *  {@link requestBodySchema} is retained alongside it for the type deriver (which maps a `$ref` to
+     *  its named TypeScript type) and for `sharedRequestBodySchemas` (which fingerprints shared refs).
+     *  Absent exactly when {@link requestBodySchema} is absent. Downstream slices (ADR 0067) read the
+     *  resolved body `type` from here rather than re-resolving a possibly-`$ref` raw schema. */
+    requestBodySchemaResolved?: OpenApiSchema;
     requestBodyRequired: boolean;
     /** Every documented JSON response, keyed by status code ("200","400",…,"default"), in a stable
      *  order. The type layer unions these into the operation's response type; the runtime validates a
@@ -144,6 +159,20 @@ export declare function parseSpec(text: string): OpenApiDoc;
 export declare function refName(ref: string): string | undefined;
 /** Follow local component `$ref`s to the concrete schema (guarding cycles). Non-local refs → undefined. */
 export declare function resolveSchema(doc: OpenApiDoc, schema: OpenApiSchema | undefined): OpenApiSchema | undefined;
+/** Deeply inline every local component `$ref` in a schema, returning a self-contained schema with no
+ *  `$ref` anywhere in its tree (top-level chain plus nested `properties`/`items`/
+ *  `additionalProperties`/`allOf`/`oneOf`/`anyOf`). This is the resolver the MCP tool projection uses
+ *  so a tool's `inputSchema` carries the concrete shape rather than an opaque `#/components/...`
+ *  pointer an MCP client cannot follow (ADR 0067). It reuses the same local-ref semantics as
+ *  {@link resolveSchema}, extended to recurse into subschemas.
+ *
+ *  Cycles and unresolvable refs FAIL LOUDLY rather than leak a `$ref`:
+ *   - a `$ref` that reappears on its own resolution path (an irreducible cycle — a schema that
+ *     cannot be finitely inlined) throws;
+ *   - a `$ref` that is non-local or dangles (no matching `#/components/schemas/*`) throws.
+ *  `seenRefs` tracks refs on the CURRENT path only, so a component referenced twice in sibling
+ *  branches (a diamond) inlines fine — only genuine self-reference is rejected. */
+export declare function resolveSchemaDeep(doc: OpenApiDoc, schema: OpenApiSchema | undefined, seenRefs?: ReadonlySet<string>): OpenApiSchema | undefined;
 /** Walk the document's paths and return every operation that carries an operationId, in a stable
  *  (path, method) order. Operations without an operationId are skipped here; the runtime mount logs
  *  them at `warn` and skips them too — this keeps the pure collector total. */
@@ -164,15 +193,44 @@ export declare function isMcpExcluded(ext: unknown): boolean;
 /** Whether an operation's HTTP method mutates state — anything other than a safe read verb. Drives
  *  the MCP read/mutate split: read tools are unguarded on loopback, mutating tools are gated. */
 export declare function isMutatingMethod(method: HttpMethodLower): boolean;
-/** One operation's MCP-tool projection facts: its id, HTTP method, whether it mutates, and whether
- *  `x-mcp` excludes it from projection. This is the shared unit the runtime MCP surface AND the CI
- *  spec↔tool parity guard both read — a single derivation of "which operations become tools", never
- *  a second walker (ADR 0053). */
+/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
+ *  path/query parameters and its request-body schema. It is the SINGLE derivation both the runtime
+ *  MCP surface (`tools/list`) and the CI parity guard read, so a tool's advertised input schema and
+ *  the HTTP validation it dispatches to can never drift (ADR 0053/0067).
+ *
+ *  Every property schema is taken from the operation's resolved (`$ref`-free) metadata — the
+ *  parameters' `resolvedSchema` and the body's `requestBodySchemaResolved`, both produced by
+ *  {@link resolveSchemaDeep} in {@link collectOperations} — so the emitted schema is self-contained:
+ *  an MCP client, which cannot follow a `#/components/...` pointer outside the original document,
+ *  sees the concrete shape (and an explicit `type` on the body). */
+export declare function toolInputSchema(op: OperationInfo): Record<string, unknown>;
+/** Walk a JSON value (a projected tool schema) and return a pointer for every `$ref` still present.
+ *  Empty means the schema is self-contained — no `#/components/...` an MCP client cannot resolve. The
+ *  path is a dotted trail to each leak (e.g. `properties.body.properties.foo`). Pure/total. */
+export declare function findSchemaRefLeaks(value: unknown, path?: string): string[];
+/** Self-containment violations in one projected tool's `inputSchema`: any surviving `$ref` (an
+ *  MCP client cannot resolve `#/components/...`), and — when the tool has a `body` property — a
+ *  `body` that carries no explicit `type` (so the client cannot tell it is an object/array and
+ *  mis-encodes the argument). Empty means the schema is a usable, self-contained input contract.
+ *  This is the pure assertion the `check:mcp` guard runs over every projected tool (ADR 0067). */
+export declare function findToolSchemaViolations(operationId: string, inputSchema: Record<string, unknown>): string[];
+/** Every self-containment violation across all projected (non-excluded) tools for a document — the
+ *  aggregate the `check:mcp` guard fails on. Excluded operations are skipped: they are withheld from
+ *  the live tool surface, so their schema is never advertised to a client. */
+export declare function findAllToolSchemaViolations(doc: OpenApiDoc): string[];
+/** One operation's MCP-tool projection facts: its id, HTTP method, whether it mutates, whether
+ *  `x-mcp` excludes it from projection, and its self-contained input schema. This is the shared unit
+ *  the runtime MCP surface AND the CI spec↔tool parity guard both read — a single derivation of
+ *  "which operations become tools and what each accepts", never a second walker (ADR 0053). */
 export interface McpToolProjection {
     operationId: string;
     method: HttpMethodLower;
     mutating: boolean;
     excluded: boolean;
+    /** The tool's `inputSchema` as advertised to an MCP client (absent for an excluded op, which is
+     *  never advertised). Captured in the snapshot so a projection change — including a body `$ref`
+     *  that stops being resolved — is caught by `check:mcp` drift, not discovered by a client. */
+    inputSchema?: Record<string, unknown>;
 }
 /**
  * Project every operationId-bearing operation to its MCP-tool facts, in the stable
@@ -180,7 +238,7 @@ export interface McpToolProjection {
  * `excluded: true`) rather than dropped, so the parity guard can positively assert that an
  * `x-mcp`-excluded door is present-but-withheld — the runtime drops them when it builds the live
  * tool list. Derived entirely from {@link collectOperations}, so it can never diverge from what
- * `mountApi` routes.
+ * `mountApi` routes. A non-excluded op also carries its self-contained {@link toolInputSchema}.
  */
 export declare function collectMcpToolProjection(doc: OpenApiDoc): McpToolProjection[];
 /**

package/dist/openapi/spec.js

@@ -115,6 +115,54 @@ export function resolveSchema(doc, schema) {
     }
     return current;
 }
+/** Deeply inline every local component `$ref` in a schema, returning a self-contained schema with no
+ *  `$ref` anywhere in its tree (top-level chain plus nested `properties`/`items`/
+ *  `additionalProperties`/`allOf`/`oneOf`/`anyOf`). This is the resolver the MCP tool projection uses
+ *  so a tool's `inputSchema` carries the concrete shape rather than an opaque `#/components/...`
+ *  pointer an MCP client cannot follow (ADR 0067). It reuses the same local-ref semantics as
+ *  {@link resolveSchema}, extended to recurse into subschemas.
+ *
+ *  Cycles and unresolvable refs FAIL LOUDLY rather than leak a `$ref`:
+ *   - a `$ref` that reappears on its own resolution path (an irreducible cycle — a schema that
+ *     cannot be finitely inlined) throws;
+ *   - a `$ref` that is non-local or dangles (no matching `#/components/schemas/*`) throws.
+ *  `seenRefs` tracks refs on the CURRENT path only, so a component referenced twice in sibling
+ *  branches (a diamond) inlines fine — only genuine self-reference is rejected. */
+export function resolveSchemaDeep(doc, schema, seenRefs = new Set()) {
+    if (!schema)
+        return undefined;
+    let current = schema;
+    let seen = seenRefs;
+    while (current.$ref) {
+        const ref = current.$ref;
+        if (seen.has(ref)) {
+            throw new Error(`OpenAPI schema $ref cycle: ${[...seen, ref].join(" -> ")} cannot be inlined into a self-contained schema`);
+        }
+        const name = refName(ref);
+        const next = name ? doc.components?.schemas?.[name] : undefined;
+        if (!next) {
+            throw new Error(`OpenAPI schema $ref "${ref}" does not resolve to a local component — a self-contained schema cannot contain an unresolvable $ref`);
+        }
+        seen = new Set(seen).add(ref);
+        current = next;
+    }
+    const out = { ...current };
+    delete out.$ref;
+    if (current.properties) {
+        out.properties = Object.fromEntries(Object.entries(current.properties).map(([k, v]) => [k, resolveSchemaDeep(doc, v, seen) ?? {}]));
+    }
+    if (current.items)
+        out.items = resolveSchemaDeep(doc, current.items, seen);
+    if (current.additionalProperties && typeof current.additionalProperties === "object") {
+        out.additionalProperties = resolveSchemaDeep(doc, current.additionalProperties, seen);
+    }
+    for (const key of ["allOf", "oneOf", "anyOf"]) {
+        const arr = current[key];
+        if (arr)
+            out[key] = arr.map((s) => resolveSchemaDeep(doc, s, seen) ?? {});
+    }
+    return out;
+}
 function firstJsonSchema(content) {
     if (!content)
         return undefined;
@@ -151,10 +199,29 @@ export function collectOperations(doc) {
             const operationId = typeof opRaw.operationId === "string" ? opRaw.operationId : undefined;
             if (!operationId || !isSafeOperationId(operationId))
                 continue;
+            // Resolve exclusion BEFORE any deep `$ref` inlining. An `x-mcp`-excluded operation is never
+            // advertised as a tool, so its schema is never projected or self-containment-guarded; doing
+            // its (throwing) deep resolution eagerly would let a dangling/cyclic `$ref` on an EXCLUDED
+            // door crash projection/guards for the whole document — even though that door is withheld.
+            // Excluded ops therefore carry no `resolvedSchema`/`requestBodySchemaResolved` (unused).
+            const mcpExcluded = isMcpExcluded(opRaw["x-mcp"]);
             const opParams = Array.isArray(opRaw.parameters) ? opRaw.parameters : [];
-            const parameters = normalizeParameters([...pathParams, ...opParams]);
+            const parameters = normalizeParameters([...pathParams, ...opParams]).map((p) => ({
+                ...p,
+                // Inline any local component `$ref` so the projected MCP tool schema is self-contained. The
+                // raw `p.schema` is kept for the type deriver; the tool projection reads `resolvedSchema`.
+                resolvedSchema: mcpExcluded ? undefined : resolveSchemaDeep(doc, p.schema),
+            }));
             const requestBody = isRecord(opRaw.requestBody) ? opRaw.requestBody : undefined;
             const requestBodySchema = firstJsonSchema(isRecord(requestBody?.content) ? requestBody.content : undefined);
+            // Deeply inline component `$ref`s so downstream consumers (the MCP tool projection, ADR 0067)
+            // get a self-contained, explicitly-typed body schema — never an opaque `#/components/...`
+            // pointer. Raw `requestBodySchema` is retained (deriver + shared-ref fingerprinting). A cyclic
+            // or unresolvable body ref fails loudly here rather than leaking a `$ref` — but only for a
+            // projected (non-excluded) op; an excluded op skips this throwing work (see above).
+            const requestBodySchemaResolved = mcpExcluded
+                ? undefined
+                : resolveSchemaDeep(doc, requestBodySchema);
             const responses = isRecord(opRaw.responses) ? opRaw.responses : {};
             // Effective security: an operation's own `security` (even an explicit `[]`, which opts out of
             // a document-level default) wins; otherwise inherit the document-level default; otherwise open.
@@ -168,11 +235,12 @@ export function collectOperations(doc) {
                 path,
                 parameters,
                 requestBodySchema,
+                requestBodySchemaResolved,
                 requestBodyRequired: requestBody?.required === true,
                 responseSchemas: collectResponseSchemas(responses),
                 security,
                 eject: opRaw["x-urban-eject"] === true,
-                mcpExcluded: isMcpExcluded(opRaw["x-mcp"]),
+                mcpExcluded,
                 summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
             });
         }
@@ -206,13 +274,107 @@ const READ_ONLY_METHODS = ["get", "head", "options"];
 export function isMutatingMethod(method) {
     return !READ_ONLY_METHODS.includes(method);
 }
+/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
+ *  path/query parameters and its request-body schema. It is the SINGLE derivation both the runtime
+ *  MCP surface (`tools/list`) and the CI parity guard read, so a tool's advertised input schema and
+ *  the HTTP validation it dispatches to can never drift (ADR 0053/0067).
+ *
+ *  Every property schema is taken from the operation's resolved (`$ref`-free) metadata — the
+ *  parameters' `resolvedSchema` and the body's `requestBodySchemaResolved`, both produced by
+ *  {@link resolveSchemaDeep} in {@link collectOperations} — so the emitted schema is self-contained:
+ *  an MCP client, which cannot follow a `#/components/...` pointer outside the original document,
+ *  sees the concrete shape (and an explicit `type` on the body). */
+export function toolInputSchema(op) {
+    const properties = {};
+    const required = [];
+    for (const p of op.parameters) {
+        if (p.in === "path" || p.in === "query") {
+            properties[p.name] = p.resolvedSchema ?? p.schema ?? {};
+            if (p.required)
+                required.push(p.name);
+        }
+    }
+    const body = op.requestBodySchemaResolved;
+    if (body) {
+        properties.body = body;
+        if (op.requestBodyRequired)
+            required.push("body");
+    }
+    const schema = { type: "object", properties };
+    if (required.length > 0)
+        schema.required = required;
+    return schema;
+}
+/** Walk a JSON value (a projected tool schema) and return a pointer for every `$ref` still present.
+ *  Empty means the schema is self-contained — no `#/components/...` an MCP client cannot resolve. The
+ *  path is a dotted trail to each leak (e.g. `properties.body.properties.foo`). Pure/total. */
+export function findSchemaRefLeaks(value, path = "") {
+    const leaks = [];
+    const visit = (v, p) => {
+        if (Array.isArray(v)) {
+            v.forEach((item, i) => visit(item, `${p}[${i}]`));
+            return;
+        }
+        if (v && typeof v === "object") {
+            for (const [k, child] of Object.entries(v)) {
+                // A JSON-Schema `$ref` is a *string* pointer; only that form is an unresolvable leak. A
+                // property literally named `$ref` with a non-string value is an ordinary schema key, so
+                // recurse into it (real leaks can still hide nested beneath such a property).
+                if (k === "$ref" && typeof child === "string")
+                    leaks.push(p || "<root>");
+                else
+                    visit(child, p ? `${p}.${k}` : k);
+            }
+        }
+    };
+    visit(value, path);
+    return leaks;
+}
+/** Whether a (record-typed) schema declares an explicit JSON-Schema `type` — a non-empty string or a
+ *  non-empty array of types. Operates on a raw record (not a typed {@link OpenApiSchema}) so it can
+ *  vet a projected tool schema's `body` property without an unchecked cast. */
+function hasExplicitType(schema) {
+    const t = schema.type;
+    if (typeof t === "string")
+        return t.length > 0;
+    return Array.isArray(t) && t.length > 0;
+}
+/** Self-containment violations in one projected tool's `inputSchema`: any surviving `$ref` (an
+ *  MCP client cannot resolve `#/components/...`), and — when the tool has a `body` property — a
+ *  `body` that carries no explicit `type` (so the client cannot tell it is an object/array and
+ *  mis-encodes the argument). Empty means the schema is a usable, self-contained input contract.
+ *  This is the pure assertion the `check:mcp` guard runs over every projected tool (ADR 0067). */
+export function findToolSchemaViolations(operationId, inputSchema) {
+    const violations = [];
+    for (const leak of findSchemaRefLeaks(inputSchema)) {
+        violations.push(`${operationId}: inputSchema leaks an unresolved $ref at ${leak}`);
+    }
+    const properties = isRecord(inputSchema.properties) ? inputSchema.properties : undefined;
+    const body = properties && isRecord(properties.body) ? properties.body : undefined;
+    if (body && !hasExplicitType(body)) {
+        violations.push(`${operationId}: inputSchema.properties.body has no explicit \`type\``);
+    }
+    return violations;
+}
+/** Every self-containment violation across all projected (non-excluded) tools for a document — the
+ *  aggregate the `check:mcp` guard fails on. Excluded operations are skipped: they are withheld from
+ *  the live tool surface, so their schema is never advertised to a client. */
+export function findAllToolSchemaViolations(doc) {
+    const violations = [];
+    for (const op of collectOperations(doc)) {
+        if (op.mcpExcluded)
+            continue;
+        violations.push(...findToolSchemaViolations(op.operationId, toolInputSchema(op)));
+    }
+    return violations;
+}
 /**
  * Project every operationId-bearing operation to its MCP-tool facts, in the stable
  * `collectOperations` (path, method) order. Excluded operations are RETAINED here (flagged
  * `excluded: true`) rather than dropped, so the parity guard can positively assert that an
  * `x-mcp`-excluded door is present-but-withheld — the runtime drops them when it builds the live
  * tool list. Derived entirely from {@link collectOperations}, so it can never diverge from what
- * `mountApi` routes.
+ * `mountApi` routes. A non-excluded op also carries its self-contained {@link toolInputSchema}.
  */
 export function collectMcpToolProjection(doc) {
     return collectOperations(doc).map((op) => ({
@@ -220,6 +382,7 @@ export function collectMcpToolProjection(doc) {
         method: op.method,
         mutating: isMutatingMethod(op.method),
         excluded: op.mcpExcluded,
+        ...(op.mcpExcluded ? {} : { inputSchema: toolInputSchema(op) }),
     }));
 }
 /**
@@ -247,6 +410,12 @@ export function diffMcpToolProjection(snapshot, current) {
                 `excluded:${snap.excluded}} vs spec {method:${cur.method}, mutating:${cur.mutating}, ` +
                 `excluded:${cur.excluded}}`);
         }
+        if (JSON.stringify(snap.inputSchema ?? null) !== JSON.stringify(cur.inputSchema ?? null)) {
+            // Emit a concise, constant-size line rather than inlining both full `inputSchema` payloads:
+            // for a non-trivial schema that would explode CI logs and bury the signal. The committed
+            // snapshot's own diff carries the exact field-level detail; this line just names the drift.
+            drift.push(`~ ${id}: inputSchema changed (regenerate the snapshot to see the field-level diff)`);
+        }
     }
     for (const id of snapshotById.keys()) {
         if (!currentById.has(id)) {

package/dist/runtime/core/host.d.ts

@@ -260,12 +260,58 @@ export interface ElementInstanceSummary {
 }
 /**
  * The kind of wait an element instance is parked in, as a
- * `/v2/element-instances/wait-states/search` result reports it. Unlike a user-task search,
- * this surfaces *every* park — a `JOB` (a service task awaiting a worker), a `MESSAGE`
- * (an event awaiting correlation), a `TIMER`, a `SIGNAL`, a `CONDITION`, as well as a
- * `USER_TASK` — so a consumer can read "what is this instance blocked on" beyond user tasks.
+ * `/v2/element-instances/wait-states/search` result reports it. This is the *canonical*
+ * six-type contract (Zeebe's, as of 2026): a `JOB` (a service task awaiting a worker), a
+ * `MESSAGE` (an event awaiting correlation), a `TIMER`, a `SIGNAL`, a `CONDITION`, as well
+ * as a `USER_TASK`.
+ *
+ * **Not every deployed engine implements the whole union.** It is forward-looking on
+ * purpose (the response mapper and {@link normalizeWaitStateType} tolerate all six so a
+ * newer engine's rows map cleanly), but the *currently deployed* nanobpmn gateway's
+ * read-model floor is narrower — see {@link DEPLOYED_WAIT_STATE_TYPES}. A
+ * {@link ElementInstanceWaitStateFilter} whose `waitStateType` falls outside that floor is
+ * rejected (the gateway answers HTTP 422); {@link assertDeployedWaitStateType} enforces the
+ * same floor client-side so the divergence surfaces as a clear error offline, in tests, and
+ * against a live engine alike. Ref: Magikcraft/nano-bpm#1042.
  */
 export type WaitStateType = "JOB" | "MESSAGE" | "USER_TASK" | "TIMER" | "SIGNAL" | "CONDITION";
+/**
+ * The `waitStateType` values the *currently deployed* nanobpmn gateway's wait-state read
+ * model actually implements — the **deployed floor**, a strict subset of the canonical
+ * {@link WaitStateType} union. The gateway's read model is a snapshot of the Zeebe contract
+ * taken 2026-06-09 (the same day Zeebe extended it with `USER_TASK`, then `TIMER`/`SIGNAL`/
+ * `CONDITION`), so it recognizes only `JOB | MESSAGE` and rejects any other filter value
+ * with HTTP 422.
+ *
+ * This constant is the **single source of truth** for that floor: the SDK-backed and
+ * WASM-backed {@link EngineClient} adapters both gate through {@link assertDeployedWaitStateType},
+ * and the WASM emulation synthesizes only these park kinds — so a test cannot pass against
+ * the emulation while a real gateway would 422 (No Drift Surfaces). Widen it (adding a leg
+ * backed by the real gateway) only once the engine actually serves the richer type — the
+ * tracking gap is Magikcraft/nano-bpm#1042.
+ */
+export declare const DEPLOYED_WAIT_STATE_TYPES: readonly WaitStateType[];
+/**
+ * Thrown when a wait-state search is asked to filter on a {@link WaitStateType} the deployed
+ * gateway's read model does not implement (outside {@link DEPLOYED_WAIT_STATE_TYPES}). It
+ * fails fast client-side with a clear, offline-detectable error rather than letting the call
+ * reach the gateway and surface as an opaque HTTP 422 "did not match any variant of untagged
+ * enum WaitStateTypeFilterProperty". Ref: Magikcraft/nano-bpm#1042.
+ */
+export declare class UnsupportedWaitStateTypeError extends Error {
+    readonly waitStateType: string;
+    readonly supported: readonly WaitStateType[];
+    constructor(waitStateType: string);
+}
+/**
+ * Assert a wait-state filter's `waitStateType` is within the deployed floor
+ * ({@link DEPLOYED_WAIT_STATE_TYPES}), throwing {@link UnsupportedWaitStateTypeError}
+ * otherwise. An absent selector is always allowed (the search is unfiltered by type). Both
+ * {@link EngineClient} adapters call this before issuing a wait-state search, so the floor is
+ * enforced identically whether the query runs against a live gateway or the in-process
+ * emulation. No-ops for an in-floor type.
+ */
+export declare function assertDeployedWaitStateType(waitStateType?: WaitStateType): void;
 /**
  * A single parked (waiting) element instance as
  * {@link EngineClient.searchElementInstanceWaitStates} reports it. Every variant carries the
@@ -312,6 +358,10 @@ export interface ElementInstanceFilter {
  * Selectors for an element-instance *wait-state* search: which process instance, element,
  * and/or kind of wait to match. Used by {@link EngineClient.searchElementInstanceWaitStates}.
  * There is deliberately no lifecycle-`state` selector — a wait state is always an active park.
+ *
+ * A `waitStateType` selector must fall within the deployed floor
+ * ({@link DEPLOYED_WAIT_STATE_TYPES}); a value outside it is rejected with
+ * {@link UnsupportedWaitStateTypeError} (the live gateway answers HTTP 422).
  */
 export interface ElementInstanceWaitStateFilter {
     processInstanceKey?: string;
@@ -476,11 +526,19 @@ export interface EngineClient {
     searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
     /**
      * Search the *wait states* of element instances
-     * (`POST /v2/element-instances/wait-states/search`) — every park, not only user tasks. A
-     * `JOB` park (a service task awaiting a worker), a `MESSAGE` park (an event awaiting
-     * correlation), a `TIMER`/`SIGNAL`/`CONDITION`, plus `USER_TASK`. A zero-wait read; each
-     * result is discriminated by `waitStateType` (see {@link ElementInstanceWaitState}), so a
-     * consumer can read the job/message parks a {@link searchUserTasks} cannot surface.
+     * (`POST /v2/element-instances/wait-states/search`) — the parks the deployed engine's
+     * read model serves. A zero-wait read; each result is discriminated by `waitStateType`
+     * (see {@link ElementInstanceWaitState}), so a consumer can read the job/message parks a
+     * {@link searchUserTasks} cannot surface.
+     *
+     * **Deployed floor.** The currently deployed nanobpmn gateway implements only
+     * `JOB | MESSAGE` ({@link DEPLOYED_WAIT_STATE_TYPES}) — a `USER_TASK` park is read via
+     * {@link searchUserTasks}, not here. A `waitStateType` filter outside the floor is rejected
+     * with {@link UnsupportedWaitStateTypeError} (the live gateway answers HTTP 422); an
+     * unfiltered search returns only in-floor parks. The `waitStateType` union is
+     * forward-looking (richer engines may serve more), but this adapter contract pins the
+     * floor so a query cannot pass in emulation while a real engine rejects it. Ref:
+     * Magikcraft/nano-bpm#1042.
      */
     searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
     /**

package/dist/runtime/core/host.js

@@ -42,6 +42,54 @@ export function presentFormIdentifier(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
+/**
+ * The `waitStateType` values the *currently deployed* nanobpmn gateway's wait-state read
+ * model actually implements — the **deployed floor**, a strict subset of the canonical
+ * {@link WaitStateType} union. The gateway's read model is a snapshot of the Zeebe contract
+ * taken 2026-06-09 (the same day Zeebe extended it with `USER_TASK`, then `TIMER`/`SIGNAL`/
+ * `CONDITION`), so it recognizes only `JOB | MESSAGE` and rejects any other filter value
+ * with HTTP 422.
+ *
+ * This constant is the **single source of truth** for that floor: the SDK-backed and
+ * WASM-backed {@link EngineClient} adapters both gate through {@link assertDeployedWaitStateType},
+ * and the WASM emulation synthesizes only these park kinds — so a test cannot pass against
+ * the emulation while a real gateway would 422 (No Drift Surfaces). Widen it (adding a leg
+ * backed by the real gateway) only once the engine actually serves the richer type — the
+ * tracking gap is Magikcraft/nano-bpm#1042.
+ */
+export const DEPLOYED_WAIT_STATE_TYPES = ["JOB", "MESSAGE"];
+/**
+ * Thrown when a wait-state search is asked to filter on a {@link WaitStateType} the deployed
+ * gateway's read model does not implement (outside {@link DEPLOYED_WAIT_STATE_TYPES}). It
+ * fails fast client-side with a clear, offline-detectable error rather than letting the call
+ * reach the gateway and surface as an opaque HTTP 422 "did not match any variant of untagged
+ * enum WaitStateTypeFilterProperty". Ref: Magikcraft/nano-bpm#1042.
+ */
+export class UnsupportedWaitStateTypeError extends Error {
+    waitStateType;
+    supported;
+    constructor(waitStateType) {
+        super(`unsupported waitStateType "${waitStateType}": the deployed nanobpmn gateway's ` +
+            `wait-state read model implements only ${DEPLOYED_WAIT_STATE_TYPES.join(" | ")} and ` +
+            `rejects any other value with HTTP 422. Ref: Magikcraft/nano-bpm#1042.`);
+        this.name = "UnsupportedWaitStateTypeError";
+        this.waitStateType = waitStateType;
+        this.supported = DEPLOYED_WAIT_STATE_TYPES;
+    }
+}
+/**
+ * Assert a wait-state filter's `waitStateType` is within the deployed floor
+ * ({@link DEPLOYED_WAIT_STATE_TYPES}), throwing {@link UnsupportedWaitStateTypeError}
+ * otherwise. An absent selector is always allowed (the search is unfiltered by type). Both
+ * {@link EngineClient} adapters call this before issuing a wait-state search, so the floor is
+ * enforced identically whether the query runs against a live gateway or the in-process
+ * emulation. No-ops for an in-floor type.
+ */
+export function assertDeployedWaitStateType(waitStateType) {
+    if (waitStateType !== undefined && !DEPLOYED_WAIT_STATE_TYPES.includes(waitStateType)) {
+        throw new UnsupportedWaitStateTypeError(waitStateType);
+    }
+}
 /**
  * The names of every method on {@link EngineClient} — the single *runtime* source of
  * truth for the interface's surface. It is compile-time-pinned to `keyof EngineClient`

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, } from "../../../openapi/spec.js";
+import { collectOperations, evaluateSecurity, isMutatingMethod, parseSpec, sharedSecretSchemeName, toolInputSchema, } from "../../../openapi/spec.js";
 import { errorMessage } from "../guards.js";
 import { presentFormIdentifier } from "../host.js";
 import { resolveBindMode } from "../manifest.js";
@@ -173,29 +173,10 @@ export function readHeader(headers, name) {
 function isMutatingOperation(op) {
     return isMutatingMethod(op.method);
 }
-/** A JSON Schema (OpenAPI object subset) describing a tool's input, derived from an operation's
- *  path/query parameters and its request-body schema. Keeping the property schemas verbatim from the
- *  spec means the tool input schema and the HTTP validation share one source of truth. */
-function toolInputSchema(op) {
-    const properties = {};
-    const required = [];
-    for (const p of op.parameters) {
-        if (p.in === "path" || p.in === "query") {
-            properties[p.name] = p.schema ?? {};
-            if (p.required)
-                required.push(p.name);
-        }
-    }
-    if (op.requestBodySchema) {
-        properties.body = op.requestBodySchema;
-        if (op.requestBodyRequired)
-            required.push("body");
-    }
-    const schema = { type: "object", properties };
-    if (required.length > 0)
-        schema.required = required;
-    return schema;
-}
+/** A JSON Schema (OpenAPI object subset) describing a tool's input is derived once, in
+ *  `openapi/spec.ts`'s {@link toolInputSchema}, from an operation's resolved (`$ref`-free) parameter
+ *  and request-body metadata — so the tool input schema the runtime advertises and the schema the CI
+ *  parity guard pins are the SAME derivation (one source of truth, ADR 0053/0067). */
 /** Substitute an operation's `{param}` path-template segments with the supplied arguments, building
  *  the request path under the shared `/app/api` base so dispatch hits the exact `mountApi` route. */
 function fillPath(op, args) {

package/dist/runtime/engine/nanosdk.js

@@ -18,7 +18,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { isBpmnError } from "../core/host.js";
+import { assertDeployedWaitStateType, isBpmnError } from "../core/host.js";
 import { buildFormSchema, parseFormSchema, pickFormLinkage, resolveFormIdentifier, } from "../core/form-contract.js";
 import { isRecord } from "../core/guards.js";
 import { applyAmbientLineage } from "../core/lineage.js";
@@ -507,10 +507,14 @@ export class SdkEngineClient {
         });
     }
     async searchElementInstanceWaitStates(filter) {
-        // The wait-states search surfaces *every* park (job/message/timer/signal/condition/user
-        // task), not just user tasks. Same zero-wait read + per-row mapping-gate shape as
-        // `searchElementInstances`; the SDK nests park-specific fields under `details`, which
-        // `mapElementInstanceWaitStateRow` unwraps.
+        // The wait-states search surfaces the parks the deployed engine's read model serves.
+        // A `waitStateType` selector outside the deployed floor (`JOB | MESSAGE`) is rejected by
+        // the gateway with HTTP 422; fail fast client-side with a clear error instead, so the
+        // divergence is caught offline and identically to the WASM adapter (No Drift Surfaces).
+        assertDeployedWaitStateType(filter?.waitStateType);
+        // Same zero-wait read + per-row mapping-gate shape as `searchElementInstances`; the SDK
+        // nests park-specific fields under `details`, which `mapElementInstanceWaitStateRow`
+        // unwraps.
         const f = {};
         if (filter?.processInstanceKey)
             f.processInstanceKey = filter.processInstanceKey;

package/dist/runtime/index.d.ts

@@ -15,6 +15,7 @@ export { createLogger } from "./core/logger.ts";
 export type { Logger, LogLevel, LogFields, LogSink } from "./core/logger.ts";
 export { BpmnError, isBpmnError } from "./core/host.ts";
 export { ENGINE_CLIENT_METHODS } from "./core/host.ts";
+export { assertDeployedWaitStateType, DEPLOYED_WAIT_STATE_TYPES, UnsupportedWaitStateTypeError, } from "./core/host.ts";
 export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.ts";
 export type { ConnectorsHandle } from "./core/modules/connectors.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";

package/dist/runtime/index.js

@@ -22,6 +22,10 @@ export { BpmnError, isBpmnError } from "./core/host.js";
 // double / adapter iterates it to prove at runtime that it implements the full interface,
 // catching the "fake lags the SDK" seam-lag class categorically.
 export { ENGINE_CLIENT_METHODS } from "./core/host.js";
+// Deployed wait-state floor (issue nanobpm/nano-ide#497): the `waitStateType` values the
+// deployed gateway actually serves, plus the shared guard both EngineClient adapters use so
+// a filter outside the floor fails identically in emulation and against a live engine.
+export { assertDeployedWaitStateType, DEPLOYED_WAIT_STATE_TYPES, UnsupportedWaitStateTypeError, } from "./core/host.js";
 // Connector packs (ADR 0050, in-process port)
 export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.js";
 // Data layer

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.86.0",
+	"version": "0.87.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",