@nanobpm/urban 0.85.0 → 0.86.1

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.85.0",
+	"version": "0.86.1",
 	"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",
@@ -93,6 +93,8 @@
 		"typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.browser.json",
 		"gen:runtime": "node scripts/gen-runtime.mjs",
 		"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",
 		"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/mcp-parity.fixture.yaml

@@ -0,0 +1,49 @@
+# Parity-guard fixture (ADR 0067 Slice 3) — NOT an app spec.
+#
+# This is the input to the spec↔tool parity guard (`scripts/gen-mcp-tools.ts`).
+# It exercises every branch of the MCP tool projection with a stable, minimal
+# document so `check:mcp` fails loudly the moment the walker's projection changes
+# without a matching, reviewed regeneration of `mcp-tools.snapshot.json`:
+#
+#   - a READ operation (GET)            → projected, non-mutating
+#   - a MUTATING operation (POST)       → projected, mutating (guarded at runtime)
+#   - an `x-mcp`-EXCLUDED operation      → present in the doc but withheld from the
+#                                          agent-facing tool surface (the security-
+#                                          relevant opt-out, `x-mcp: false`)
+#
+# Edit this fixture ONLY together with a reviewed `npm run gen:mcp-tools`.
+openapi: 3.1.0
+info:
+  title: mcp-parity-fixture
+  version: 0.0.0
+components:
+  securitySchemes:
+    appSecret:
+      type: apiKey
+      in: header
+      name: X-Nano-Key
+      x-nano-secret-env: NANO_WEBHOOK_KEY
+paths:
+  /widgets:
+    get:
+      operationId: listWidgets
+      summary: List widgets (read — projected, unguarded on loopback).
+      responses:
+        "200":
+          description: ok
+    post:
+      operationId: createWidget
+      summary: Create a widget (mutating — projected, guarded).
+      security:
+        - appSecret: []
+      responses:
+        "201":
+          description: created
+  /internal/reindex:
+    post:
+      operationId: reindexWidgets
+      summary: Operator-only reindex (withheld from the MCP tool surface).
+      x-mcp: false
+      responses:
+        "202":
+          description: accepted

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

@@ -0,0 +1,20 @@
+[
+  {
+    "operationId": "reindexWidgets",
+    "method": "post",
+    "mutating": true,
+    "excluded": true
+  },
+  {
+    "operationId": "listWidgets",
+    "method": "get",
+    "mutating": false,
+    "excluded": false
+  },
+  {
+    "operationId": "createWidget",
+    "method": "post",
+    "mutating": true,
+    "excluded": false
+  }
+]

package/src/openapi/spec.test.ts

@@ -5,6 +5,7 @@ import {
   evaluateSecurity,
   isObjectSchema,
   isSafeOperationId,
+  isMutatingMethod,
   type OpenApiDoc,
   type OpenApiSchema,
   operationsWithoutId,
@@ -13,6 +14,8 @@ import {
   resolveSchema,
   responseSchemaForStatus,
   sharedRequestBodySchemas,
+  sharedSecretSchemeName,
+  sharedSecretSchemeNames,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -436,6 +439,18 @@ test("isSafeOperationId rejects path separators and traversal; collectOperations
   assert.deepEqual(operationsWithUnsafeId(evil), ["GET /x (../../etc/passwd)"]);
 });
 
+test("isMutatingMethod: the HTTP safe verbs (get/head/options) are read-only, everything else mutates", () => {
+  // OPTIONS is a CORS/preflight metadata probe — a safe, non-mutating verb (RFC 9110 §9.2.1). It must
+  // NOT be flagged mutating, or an `options` operation is wrongly marked destructive in tools/list and
+  // captured as a "mutating" fact by the spec↔tool parity snapshot.
+  for (const safe of ["get", "head", "options"] as const) {
+    assert.equal(isMutatingMethod(safe), false, `${safe} must be treated as read-only`);
+  }
+  for (const mutating of ["put", "post", "delete", "patch"] as const) {
+    assert.equal(isMutatingMethod(mutating), true, `${mutating} must be treated as mutating`);
+  }
+});
+
 test("object validation uses own-property checks (prototype keys don't satisfy required or bypass additionalProperties)", () => {
   // A prototype key must NOT satisfy `required` (own-property semantics).
   const req = { type: "object", properties: { toString: { type: "string" } }, required: ["toString"] };
@@ -633,6 +648,83 @@ test("evaluateSecurity: alternative requirements are OR (any one satisfied autho
   assert.equal(evaluateSecurity(doc, op, noHeader, noQuery, env).status, 401);
 });
 
+test("sharedSecretSchemeName: exactly one apiKey header scheme with x-nano-secret-env is the guard", () => {
+  assert.equal(sharedSecretSchemeName(secured), "webhookKey");
+  assert.deepEqual(sharedSecretSchemeNames(secured), ["webhookKey"]);
+});
+
+test("sharedSecretSchemeName: no candidate scheme → undefined (mutations stay closed)", () => {
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: { securitySchemes: { oauth: { type: "oauth2" } } },
+    paths: {},
+  };
+  assert.equal(sharedSecretSchemeName(doc), undefined);
+  assert.deepEqual(sharedSecretSchemeNames(doc), []);
+});
+
+test("sharedSecretSchemeName: MULTIPLE candidate schemes are an explicit misconfiguration, not a silent first-wins", () => {
+  // Two apiKey header schemes both carry x-nano-secret-env: which one guards mutations would
+  // otherwise depend on object iteration (authoring) order — surface it loudly instead.
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      securitySchemes: {
+        primary: { type: "apiKey", in: "header", name: "X-A", "x-nano-secret-env": "A_KEY" },
+        secondary: { type: "apiKey", in: "header", name: "X-B", "x-nano-secret-env": "B_KEY" },
+      },
+    },
+    paths: {},
+  };
+  // The full candidate list is exposed (source of truth) …
+  assert.deepEqual(sharedSecretSchemeNames(doc), ["primary", "secondary"]);
+  // … and the selector refuses to pick one silently.
+  assert.throws(
+    () => sharedSecretSchemeName(doc),
+    /multiple shared-secret schemes.*primary, secondary/s,
+  );
+});
+
+test("sharedSecretSchemeNames: a declared-but-EMPTY x-nano-secret-env is still a candidate (→ 500 downstream, not a silent 401)", () => {
+  // An empty `x-nano-secret-env` is a misconfiguration, not "no scheme": a truthiness test would
+  // drop it so the guard reports a misleading "no shared-secret scheme" (401). A structural presence
+  // check keeps it selected so `evaluateSecurity` surfaces it as a 500, mirroring how it treats an
+  // empty env-var pointer.
+  const doc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      securitySchemes: {
+        webhookKey: { type: "apiKey", in: "header", name: "X-Key", "x-nano-secret-env": "" },
+      },
+    },
+    paths: {},
+  };
+  assert.deepEqual(sharedSecretSchemeNames(doc), ["webhookKey"]);
+  assert.equal(sharedSecretSchemeName(doc), "webhookKey");
+});
+
+test("sharedSecretSchemeNames: a malformed (null) scheme entry is skipped, not a bare TypeError", () => {
+  // A mistakenly empty scheme (`webhookKey:` with no body) parses as `null` in YAML. Dereferencing
+  // it (`scheme.type`) would throw a bare TypeError; a non-object scheme is not a valid apiKey
+  // shared-secret candidate, so it is skipped and the real candidate is still selected. Built via
+  // JSON.parse so the runtime-invalid `null` scheme reaches the function (types forbid it).
+  const doc: OpenApiDoc = parseSpec(
+    JSON.stringify({
+      openapi: "3.0.0",
+      components: {
+        securitySchemes: {
+          brokenEmpty: null,
+          webhookKey: { type: "apiKey", in: "header", name: "X-Key", "x-nano-secret-env": "KEY" },
+        },
+      },
+      paths: {},
+    }),
+  );
+  assert.deepEqual(sharedSecretSchemeNames(doc), ["webhookKey"]);
+  assert.equal(sharedSecretSchemeName(doc), "webhookKey");
+});
+
+
 test("responseSchemaForStatus: a documented-but-bodyless status suppresses the default fallback", () => {
   const ops = collectOperations({
     openapi: "3.1.0",

package/src/openapi/spec.ts

@@ -187,6 +187,11 @@ export interface OperationInfo {
    *  else the document-level default, else `[]`). An empty list means the operation is open. */
   security: OpenApiSecurityRequirement[];
   eject: boolean;
+  /** Whether the operation opts OUT of MCP tool projection via the `x-mcp` extension (ADR 0067).
+   *  Defaults to `false` — an operation IS exposed as a tool unless it explicitly excludes itself.
+   *  Security-relevant: this is the single authoring switch that keeps an operator-only door (e.g.
+   *  a human-gated dispatch) out of the agent-facing tool surface. See {@link isMcpExcluded}. */
+  mcpExcluded: boolean;
   summary?: string;
 }
 
@@ -307,6 +312,7 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
         responseSchemas: collectResponseSchemas(responses),
         security,
         eject: opRaw["x-urban-eject"] === true,
+        mcpExcluded: isMcpExcluded(opRaw["x-mcp"]),
         summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
       });
     }
@@ -314,6 +320,161 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
   return out;
 }
 
+/**
+ * Read the `x-mcp` operation extension (ADR 0067 — MCP tool projection). An operation is EXPOSED as
+ * an MCP tool by default; it is excluded only when it says so explicitly, so a spec author opts a
+ * door OUT rather than every operation having to opt in. Recognised exclusion forms:
+ *   - `x-mcp: false`            — a terse boolean opt-out;
+ *   - `x-mcp: { exclude: true }` — the object form (room for future keys, e.g. per-tool metadata).
+ * Any other value (including `x-mcp: true` / `{ exclude: false }` / absent) leaves the operation
+ * exposed — fail-open to the documented default. This is a SECURITY-RELEVANT authoring rule: it is
+ * the one switch that keeps an operator-only operation out of the agent-facing tool surface, so it
+ * is enforced from the same single walker the runtime and the parity guard both read (no second
+ * source of truth to drift, ADR 0053).
+ */
+export function isMcpExcluded(ext: unknown): boolean {
+  if (ext === false) return true;
+  return isRecord(ext) && ext.exclude === true;
+}
+
+/** The HTTP methods MCP treats as read-only (safe, non-mutating). These are exactly the HTTP "safe"
+ *  verbs (RFC 9110 §9.2.1) that {@link HTTP_METHODS} can express: GET/HEAD, plus OPTIONS (a
+ *  CORS/preflight metadata probe that never mutates). Every other method an operation can declare is
+ *  a mutation whose tool is guarded (ADR 0067 Slice 3). */
+const READ_ONLY_METHODS: readonly HttpMethodLower[] = ["get", "head", "options"];
+
+/** 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 function isMutatingMethod(method: HttpMethodLower): boolean {
+  return !READ_ONLY_METHODS.includes(method);
+}
+
+/** 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). */
+export interface McpToolProjection {
+  operationId: string;
+  method: HttpMethodLower;
+  mutating: boolean;
+  excluded: boolean;
+}
+
+/**
+ * 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.
+ */
+export function collectMcpToolProjection(doc: OpenApiDoc): McpToolProjection[] {
+  return collectOperations(doc).map((op) => ({
+    operationId: op.operationId,
+    method: op.method,
+    mutating: isMutatingMethod(op.method),
+    excluded: op.mcpExcluded,
+  }));
+}
+
+/**
+ * Compare a previously-captured MCP-tool projection (the committed snapshot) against the projection
+ * freshly computed from the spec, returning a human-readable line for every skew — an operation the
+ * spec now projects that the snapshot lacks, one the snapshot still lists that the spec no longer
+ * projects, or one whose method / mutating / excluded facts changed. An empty array means the spec
+ * and the projected tool list are in parity. This is the pure core of the `check:mcp` CI drift gate
+ * (ADR 0067) — the same "generated derived artifact + fail-on-drift" pattern the repo already uses
+ * for `check:runtime` — and is unit-tested by feeding it an injected skew.
+ */
+export function diffMcpToolProjection(
+  snapshot: McpToolProjection[],
+  current: McpToolProjection[],
+): string[] {
+  const drift: string[] = [];
+  const byId = (list: McpToolProjection[]): Map<string, McpToolProjection> =>
+    new Map(list.map((p) => [p.operationId, p]));
+  const snapshotById = byId(snapshot);
+  const currentById = byId(current);
+  for (const [id, cur] of currentById) {
+    const snap = snapshotById.get(id);
+    if (!snap) {
+      drift.push(`+ ${id}: spec projects a tool the snapshot is missing (regenerate the snapshot)`);
+      continue;
+    }
+    if (snap.method !== cur.method || snap.mutating !== cur.mutating || snap.excluded !== cur.excluded) {
+      drift.push(
+        `~ ${id}: projection changed — snapshot {method:${snap.method}, mutating:${snap.mutating}, ` +
+          `excluded:${snap.excluded}} vs spec {method:${cur.method}, mutating:${cur.mutating}, ` +
+          `excluded:${cur.excluded}}`,
+      );
+    }
+  }
+  for (const id of snapshotById.keys()) {
+    if (!currentById.has(id)) {
+      drift.push(`- ${id}: snapshot lists a tool the spec no longer projects (regenerate the snapshot)`);
+    }
+  }
+  return drift;
+}
+
+/**
+ * Every app shared-secret security scheme (ADR 0067/0059): the `apiKey` schemes in
+ * `components.securitySchemes` presented in a request HEADER and pointing at an env var via
+ * `x-nano-secret-env` (declared, even if empty — an empty pointer is a misconfiguration surfaced as
+ * 500 downstream, not "no scheme"), in document (authoring) order. Single source of truth for both the guard
+ * selector (`sharedSecretSchemeName`) and its ambiguity check — a mutating MCP tool REUSES the
+ * app's existing shared secret (the same one a `webhook` trigger or a guarded operation already
+ * uses) instead of minting an MCP-specific synonym.
+ */
+export function sharedSecretSchemeNames(doc: OpenApiDoc): string[] {
+  const schemes = doc.components?.securitySchemes ?? {};
+  const names: string[] = [];
+  for (const [name, scheme] of Object.entries(schemes)) {
+    // A malformed scheme value (e.g. `webhookKey:` with no body parses as `null` in YAML, or a
+    // primitive) is not a valid apiKey shared-secret candidate — skip it rather than dereference it
+    // and throw a bare TypeError. This mirrors `evaluateSecurity`, which never treats a non-object
+    // scheme as a valid credential (a referenced null/primitive scheme surfaces there as a 500), so
+    // there is no silent security hole: mutations fail closed and a genuine misconfig is caught at
+    // request time by the enforcement path.
+    if (!isRecord(scheme)) continue;
+    // Structural presence check (`typeof … === "string"`), NOT truthiness: a declared-but-EMPTY
+    // `x-nano-secret-env` is a misconfiguration, not "no scheme". Selecting it here lets
+    // `evaluateSecurity` surface it as a 500 (missing env-var pointer) — the same way it treats an
+    // empty pointer — instead of silently dropping the scheme so the guard reports a misleading 401.
+    if (
+      scheme.type === "apiKey" &&
+      (scheme.in ?? "header") === "header" &&
+      typeof scheme["x-nano-secret-env"] === "string"
+    ) {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * The name of the app's single shared-secret security scheme (ADR 0067/0059) — the credential the
+ * framework MUTATING MCP tools require. `undefined` when the app declares no such scheme, in which
+ * case the mutating tools stay closed unless an explicit runtime opt-in is set.
+ *
+ * THROWS when the spec declares MORE THAN ONE candidate: which scheme becomes "the" MCP mutation
+ * guard would otherwise depend on `securitySchemes` object iteration (authoring) order, silently
+ * guarding with an unintended secret (or rejecting a different, valid shared-secret header). That is
+ * an incoherent spec, surfaced loudly — the caller maps it to a 500 misconfiguration — rather than
+ * resolved by an invisible "first wins" rule. Derived from `sharedSecretSchemeNames` (no drift).
+ */
+export function sharedSecretSchemeName(doc: OpenApiDoc): string | undefined {
+  const names = sharedSecretSchemeNames(doc);
+  if (names.length > 1) {
+    throw new Error(
+      `OpenAPI spec declares multiple shared-secret schemes (apiKey header with x-nano-secret-env): ` +
+        `${names.join(", ")}. Exactly one may serve as the MCP mutation guard — remove the extras so ` +
+        "the guard scheme is unambiguous.",
+    );
+  }
+  return names[0];
+}
+
 /**
  * Throw if the document declares the same `operationId` on more than one operation. An operationId
  * must be unique across the whole OpenAPI document (it names the delegate module `<dir>/<operationId>`

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,