@nanobpm/urban 0.86.0 → 0.87.0

package/src/runtime/core/host.ts

@@ -296,10 +296,19 @@ 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"
@@ -309,6 +318,59 @@ export type WaitStateType =
   | "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 const DEPLOYED_WAIT_STATE_TYPES: readonly WaitStateType[] = ["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 {
+  readonly waitStateType: string;
+  readonly supported: readonly WaitStateType[];
+  constructor(waitStateType: string) {
+    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?: WaitStateType): void {
+  if (waitStateType !== undefined && !DEPLOYED_WAIT_STATE_TYPES.includes(waitStateType)) {
+    throw new UnsupportedWaitStateTypeError(waitStateType);
+  }
+}
+
 /**
  * A single parked (waiting) element instance as
  * {@link EngineClient.searchElementInstanceWaitStates} reports it. Every variant carries the
@@ -352,6 +414,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;
@@ -512,11 +578,19 @@ export interface EngineClient {
   ): 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,

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

@@ -327,6 +327,35 @@ test("a projected tool's input schema matches the spec's params", async () => {
   });
 });
 
+test("a $ref-bodied tool projects a self-contained body schema (no $ref, explicit type)", async () => {
+  // createInvoice's requestBody is `{ $ref: "#/components/schemas/Invoice" }` — a bare $ref with no
+  // inline `type`. An MCP client cannot resolve `#/components/...` outside the document, so the
+  // projected tool schema MUST inline the concrete Invoice shape (ADR 0067). Regression guard for the
+  // leak that shipped an opaque `#/components/...` pointer into `inputSchema.properties.body`.
+  const { router } = buildHarness();
+  const session = await connect(router);
+  const list = await rpc(router, session, "tools/list", {});
+  const tools = list.result?.tools;
+  assert.ok(Array.isArray(tools));
+  const createInvoice = tools.find((t) => Reflect.get(t, "name") === "createInvoice");
+  assert.ok(createInvoice, "createInvoice must be present in tools/list before checking its schema");
+  const schema = Reflect.get(createInvoice, "inputSchema");
+  assert.deepEqual(schema, {
+    type: "object",
+    properties: {
+      body: {
+        type: "object",
+        properties: { id: { type: "string" }, amount: { type: "integer", minimum: 1 } },
+        required: ["id", "amount"],
+        additionalProperties: false,
+      },
+    },
+    required: ["body"],
+  });
+  // Self-containment holds structurally: the serialized schema carries no `$ref` token at all.
+  assert.ok(!JSON.stringify(schema).includes("$ref"), "projected body schema must not leak a $ref");
+});
+
 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

@@ -55,6 +55,7 @@ import {
   parseSpec,
   type SecurityDecision,
   sharedSecretSchemeName,
+  toolInputSchema,
 } from "../../../openapi/spec.ts";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage } from "../guards.ts";
@@ -250,26 +251,10 @@ function isMutatingOperation(op: OperationInfo): boolean {
   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: OperationInfo): Record<string, unknown> {
-  const properties: Record<string, unknown> = {};
-  const required: string[] = [];
-  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: Record<string, unknown> = { 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. */

package/src/runtime/engine/nanosdk.test.ts

@@ -13,6 +13,11 @@ import {
   type NanoSdkJobWorkerConfig,
 } from "./nanosdk.ts";
 import { BpmnError } from "../core/host.ts";
+import {
+  assertDeployedWaitStateType,
+  DEPLOYED_WAIT_STATE_TYPES,
+  UnsupportedWaitStateTypeError,
+} from "../core/host.ts";
 import { __resetExecStoreForTests, installExecStore, runInJobContext } from "../core/execContext.ts";
 import { readLineage } from "../core/lineage.ts";
 import { createNodeHost } from "../adapters/node.ts";
@@ -498,6 +503,27 @@ test("normalizeWaitStateType maps the wait-state kinds (case-insensitive) and re
   assert.equal(normalizeWaitStateType(3), undefined);
 });
 
+test("assertDeployedWaitStateType: allows the floor and an absent selector, rejects the rest", () => {
+  // The deployed floor is exactly JOB|MESSAGE — the single source of truth both adapters gate on.
+  assert.deepEqual([...DEPLOYED_WAIT_STATE_TYPES], ["JOB", "MESSAGE"]);
+  // In-floor and absent selectors are no-ops (no throw).
+  assert.doesNotThrow(() => assertDeployedWaitStateType(undefined));
+  assert.doesNotThrow(() => assertDeployedWaitStateType("JOB"));
+  assert.doesNotThrow(() => assertDeployedWaitStateType("MESSAGE"));
+  // Every canonical type outside the floor is rejected with a typed, descriptive error.
+  for (const waitStateType of ["USER_TASK", "TIMER", "SIGNAL", "CONDITION"] as const) {
+    assert.throws(
+      () => assertDeployedWaitStateType(waitStateType),
+      (err: unknown) => {
+        assert.ok(err instanceof UnsupportedWaitStateTypeError);
+        assert.equal(err.waitStateType, waitStateType);
+        assert.match(err.message, /HTTP 422/);
+        return true;
+      },
+    );
+  }
+});
+
 test("searchElementInstances passes zero-wait consistency, maps rows, and forwards selectors", async () => {
   let seenInput: unknown;
   let seenConsistency: unknown;
@@ -650,35 +676,67 @@ test("searchElementInstanceWaitStates forwards a waitStateType selector and read
           {
             elementInstanceKey: "9",
             processInstanceKey: "3",
-            elementId: "ut",
-            waitStateType: "USER_TASK",
-            taskKey: "42",
+            elementId: "catch",
+            waitStateType: "MESSAGE",
+            messageName: "Go",
+            correlationKey: "K1",
           },
           {
             elementInstanceKey: "11",
             processInstanceKey: "3",
-            elementId: "ut2",
-            waitStateType: "USER_TASK",
-          }, // USER_TASK with no taskKey/userTaskKey → dropped (invalid identity)
+            elementId: "catch2",
+            waitStateType: "MESSAGE",
+          }, // MESSAGE with no messageName → dropped (invalid identity)
           { elementInstanceKey: "10", processInstanceKey: "3", elementId: "?" }, // no waitStateType → dropped
         ],
       };
     },
   });
   const engine = new SdkEngineClient(client);
-  const out = await engine.searchElementInstanceWaitStates({ waitStateType: "USER_TASK" });
-  assert.deepEqual(seenInput, { filter: { waitStateType: "USER_TASK" } });
+  const out = await engine.searchElementInstanceWaitStates({ waitStateType: "MESSAGE" });
+  assert.deepEqual(seenInput, { filter: { waitStateType: "MESSAGE" } });
   assert.deepEqual(out, [
     {
       elementInstanceKey: "9",
       processInstanceKey: "3",
-      elementId: "ut",
-      waitStateType: "USER_TASK",
-      userTaskKey: "42",
+      elementId: "catch",
+      waitStateType: "MESSAGE",
+      messageName: "Go",
+      correlationKey: "K1",
     },
   ]);
 });
 
+test("searchElementInstanceWaitStates rejects a waitStateType outside the deployed floor without calling the gateway", async () => {
+  // The deployed gateway's read model implements only JOB|MESSAGE and 422s any other filter
+  // value. The SDK adapter must fail fast client-side (not issue the call), so an app authoring
+  // `waitStateType: "USER_TASK"` cannot ship green then blow up at runtime (issue
+  // nanobpm/nano-ide#497).
+  let called = false;
+  const client = fakeSdkClient({
+    searchElementInstanceWaitStates: async () => {
+      called = true;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  for (const waitStateType of ["USER_TASK", "TIMER", "SIGNAL", "CONDITION"] as const) {
+    await assert.rejects(
+      engine.searchElementInstanceWaitStates({ waitStateType }),
+      (err: unknown) => {
+        assert.ok(err instanceof Error);
+        assert.match(err.message, /unsupported waitStateType/);
+        assert.match(err.message, new RegExp(waitStateType));
+        return true;
+      },
+    );
+  }
+  assert.equal(called, false, "the gateway must not be called for an out-of-floor filter");
+  // An in-floor filter still reaches the gateway.
+  await engine.searchElementInstanceWaitStates({ waitStateType: "JOB" });
+  assert.equal(called, true);
+});
+
 test("searchElementInstanceWaitStates drops parks missing their required discriminator field", async () => {
   const client = fakeSdkClient({
     searchElementInstanceWaitStates: async () => ({

package/src/runtime/engine/nanosdk.ts

@@ -32,7 +32,7 @@ import type {
   UserTaskFilter,
   WorkerSubscription,
 } from "../core/host.ts";
-import { isBpmnError } from "../core/host.ts";
+import { assertDeployedWaitStateType, isBpmnError } from "../core/host.ts";
 import {
   buildFormSchema,
   parseFormSchema,
@@ -709,10 +709,14 @@ export class SdkEngineClient implements EngineClient {
   async searchElementInstanceWaitStates(
     filter?: ElementInstanceWaitStateFilter,
   ): Promise<ElementInstanceWaitState[]> {
-    // 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: Record<string, unknown> = {};
     if (filter?.processInstanceKey) f.processInstanceKey = filter.processInstanceKey;
     if (filter?.elementId) f.elementId = filter.elementId;

package/src/runtime/index.ts

@@ -133,6 +133,14 @@ export { BpmnError, isBpmnError } from "./core/host.ts";
 // 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.ts";
+// 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.ts";
 
 // Connector packs (ADR 0050, in-process port)
 export {