@nanobpm/urban 0.86.0 → 0.86.1

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/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.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",

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/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 {