@nanobpm/urban 0.91.0 → 0.92.1

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

@@ -314,16 +314,20 @@ export interface ElementInstanceSummary {
  * {@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.
+ * against a live engine alike. The floor now covers `JOB | MESSAGE | USER_TASK`
+ * (Magikcraft/nano-bpm#1042 shipped `USER_TASK` parks); `TIMER`/`SIGNAL`/`CONDITION` remain
+ * the follow-on. 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.
+ * {@link WaitStateType} union. The gateway's read model started as a snapshot of the Zeebe
+ * contract taken 2026-06-09 that recognized only `JOB | MESSAGE`; Magikcraft/nano-bpm#1042
+ * has since shipped `USER_TASK` parks (added on user-task CREATED, removed on
+ * COMPLETED/CANCELED, with the park identity under `details.taskKey`), moving the floor up to
+ * `JOB | MESSAGE | USER_TASK`. `TIMER`/`SIGNAL`/`CONDITION` are still rejected with HTTP 422
+ * (the 8.10 follow-on tracked in Magikcraft/nano-bpm#1042).
  *
  * 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},
@@ -645,14 +649,14 @@ export interface EngineClient {
      * (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.
+     * **Deployed floor.** The currently deployed nanobpmn gateway implements
+     * `JOB | MESSAGE | USER_TASK` ({@link DEPLOYED_WAIT_STATE_TYPES}); a `USER_TASK` park can be
+     * read here (or through {@link searchUserTasks}). A `waitStateType` filter outside the floor
+     * (`TIMER`/`SIGNAL`/`CONDITION`) 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

@@ -45,10 +45,12 @@ export function presentFormIdentifier(value) {
 /**
  * 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.
+ * {@link WaitStateType} union. The gateway's read model started as a snapshot of the Zeebe
+ * contract taken 2026-06-09 that recognized only `JOB | MESSAGE`; Magikcraft/nano-bpm#1042
+ * has since shipped `USER_TASK` parks (added on user-task CREATED, removed on
+ * COMPLETED/CANCELED, with the park identity under `details.taskKey`), moving the floor up to
+ * `JOB | MESSAGE | USER_TASK`. `TIMER`/`SIGNAL`/`CONDITION` are still rejected with HTTP 422
+ * (the 8.10 follow-on tracked in Magikcraft/nano-bpm#1042).
  *
  * 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},
@@ -57,7 +59,7 @@ export function presentFormIdentifier(value) {
  * 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"];
+export const DEPLOYED_WAIT_STATE_TYPES = ["JOB", "MESSAGE", "USER_TASK"];
 /**
  * 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

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

@@ -41,7 +41,6 @@ import { resolveBindMode } from "../manifest.js";
 import { json, makeRouter } from "../router.js";
 import { API_BASE, readApiBinding } from "./api.js";
 import { resolveAppPath } from "./datasource.js";
-import { InstanceStateStore } from "./instance-state-store.js";
 import { OpenUserTasksStore } from "./open-user-tasks-store.js";
 /** The mount path of the MCP endpoint — a sibling of `/app/api` / `/app/agent`, mounted
  *  unconditionally so an MCP client always has a stable address to connect to. */
@@ -682,18 +681,19 @@ function buildDebugTools(app) {
         },
         {
             name: `${DEBUG_PREFIX}instance_state`,
-            description: "Projection (urban_instance_state, ADR 0065): the canonical engine-lifecycle state for an instance.",
+            description: "Engine truth: the live lifecycle state of a process instance (ACTIVE/COMPLETED/TERMINATED) via searchProcessInstances, plus `waitingOnHuman` from its open user tasks. `null` means the engine has no such instance (not merely 'not yet terminal').",
             inputSchema: {
                 type: "object",
                 properties: { processInstanceKey: OPTIONAL_STRING },
                 required: ["processInstanceKey"],
             },
-            run: (args) => {
+            run: async (args) => {
                 const key = requireString(args, "processInstanceKey");
-                const db = projectionDb();
-                if (!db)
-                    return Promise.resolve(null);
-                return Promise.resolve(new InstanceStateStore(db).getState(key) ?? null);
+                const [snapshot] = await app.engine.searchProcessInstances({ processInstanceKeys: [key] });
+                if (!snapshot)
+                    return null;
+                const openTasks = await app.engine.openUserTasks({ processInstanceKey: key });
+                return { processInstanceKey: key, state: snapshot.state, waitingOnHuman: openTasks.length > 0 };
             },
         },
         {

package/dist/runtime/engine/nanosdk.js

@@ -640,9 +640,10 @@ export class SdkEngineClient {
     }
     async searchElementInstanceWaitStates(filter) {
         // 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).
+        // A `waitStateType` selector outside the deployed floor (`JOB | MESSAGE | USER_TASK`) 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`

package/package.json

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

@@ -350,7 +350,9 @@ export interface ElementInstanceSummary {
  * {@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.
+ * against a live engine alike. The floor now covers `JOB | MESSAGE | USER_TASK`
+ * (Magikcraft/nano-bpm#1042 shipped `USER_TASK` parks); `TIMER`/`SIGNAL`/`CONDITION` remain
+ * the follow-on. Ref: Magikcraft/nano-bpm#1042.
  */
 export type WaitStateType =
   | "JOB"
@@ -363,10 +365,12 @@ export type WaitStateType =
 /**
  * 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.
+ * {@link WaitStateType} union. The gateway's read model started as a snapshot of the Zeebe
+ * contract taken 2026-06-09 that recognized only `JOB | MESSAGE`; Magikcraft/nano-bpm#1042
+ * has since shipped `USER_TASK` parks (added on user-task CREATED, removed on
+ * COMPLETED/CANCELED, with the park identity under `details.taskKey`), moving the floor up to
+ * `JOB | MESSAGE | USER_TASK`. `TIMER`/`SIGNAL`/`CONDITION` are still rejected with HTTP 422
+ * (the 8.10 follow-on tracked in Magikcraft/nano-bpm#1042).
  *
  * 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},
@@ -375,7 +379,7 @@ export type WaitStateType =
  * 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"];
+export const DEPLOYED_WAIT_STATE_TYPES: readonly WaitStateType[] = ["JOB", "MESSAGE", "USER_TASK"];
 
 /**
  * Thrown when a wait-state search is asked to filter on a {@link WaitStateType} the deployed
@@ -701,14 +705,14 @@ export interface EngineClient {
    * (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.
+   * **Deployed floor.** The currently deployed nanobpmn gateway implements
+   * `JOB | MESSAGE | USER_TASK` ({@link DEPLOYED_WAIT_STATE_TYPES}); a `USER_TASK` park can be
+   * read here (or through {@link searchUserTasks}). A `waitStateType` filter outside the floor
+   * (`TIMER`/`SIGNAL`/`CONDITION`) 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

@@ -29,7 +29,6 @@ import { makeRouter } from "../router.ts";
 import { mountApi } from "./api.ts";
 import { makeGateway } from "./gateway.ts";
 import { DataLayer, type ProvisionedSource } from "./datasource.ts";
-import { InstanceStateStore } from "./instance-state-store.ts";
 import { OpenUserTasksStore } from "./open-user-tasks-store.ts";
 import { evictExcessSessions, isLoopbackRequest, missingRequiredArgs, mountMcp, newSessionId, readHeader, readMcpConfig } from "./mcp.ts";
 import { collectMcpToolProjection, diffMcpToolProjection, parseSpec } from "../../../openapi/spec.ts";
@@ -769,13 +768,11 @@ test("the reserved-namespace drop warns once, not on every tools/list and tools/
   assert.equal(drops.length, 1, "the reserved-namespace drop must warn exactly once across many requests");
 });
 
-test("the projection debug tools read the ADR 0065 canonical stores", async () => {
+test("urban_debug_open_user_tasks reads the ADR 0065 canonical projection", async () => {
   const dir = await mkdtemp(join(tmpdir(), "urban-mcp-proj-"));
   const host = createNodeHost({ cwd: dir, log: () => {} });
   const db: SqliteDb = host.openSqlite(join(dir, "test.db"));
   try {
-    new InstanceStateStore(db, { clock: { now: () => 0 } }).ensureSchema();
-    new InstanceStateStore(db, { clock: { now: () => 0 } }).recordState("pi-7", "ACTIVE");
     const openStore = new OpenUserTasksStore(db, { clock: { now: () => 0 } });
     openStore.ensureSchema();
     openStore.recordOpenTask("pi-7", { userTaskKey: "ut-1", elementId: "Task_A" });
@@ -792,13 +789,6 @@ test("the projection debug tools read the ADR 0065 canonical stores", async () =
     const { router } = buildHarness({ data });
     const session = await connect(router);
 
-    const stateCall = await rpc(router, session, "tools/call", {
-      name: "urban_debug_instance_state",
-      arguments: { processInstanceKey: "pi-7" },
-    });
-    const state = JSON.parse(toolContentText(stateCall.result));
-    assert.equal(Reflect.get(state, "state"), "ACTIVE");
-
     const tasksCall = await rpc(router, session, "tools/call", {
       name: "urban_debug_open_user_tasks",
       arguments: { processInstanceKey: "pi-7" },
@@ -812,6 +802,66 @@ test("the projection debug tools read the ADR 0065 canonical stores", async () =
   }
 });
 
+test("urban_debug_instance_state returns engine truth for a live (ACTIVE) instance", async () => {
+  const snapshot: ProcessInstanceSnapshot = { processInstanceKey: "pi-7", state: "ACTIVE" };
+  const engine = fakeEngine({
+    searchProcessInstances: async (filter) => {
+      assert.deepEqual(filter?.processInstanceKeys, ["pi-7"]);
+      return [snapshot];
+    },
+    openUserTasks: async () => [],
+  });
+  const { router } = buildHarness({ engine });
+  const session = await connect(router);
+
+  const call = await rpc(router, session, "tools/call", {
+    name: "urban_debug_instance_state",
+    arguments: { processInstanceKey: "pi-7" },
+  });
+  const state = JSON.parse(toolContentText(call.result));
+  assert.deepEqual(state, { processInstanceKey: "pi-7", state: "ACTIVE", waitingOnHuman: false });
+});
+
+test("urban_debug_instance_state reports waitingOnHuman from open user tasks", async () => {
+  const snapshot: ProcessInstanceSnapshot = { processInstanceKey: "pi-7", state: "ACTIVE" };
+  const engine = fakeEngine({
+    searchProcessInstances: async () => [snapshot],
+    openUserTasks: async (filter) => {
+      assert.equal(filter?.processInstanceKey, "pi-7");
+      return [{ userTaskKey: "ut-1", processInstanceKey: "pi-7" }];
+    },
+  });
+  const { router } = buildHarness({ engine });
+  const session = await connect(router);
+
+  const call = await rpc(router, session, "tools/call", {
+    name: "urban_debug_instance_state",
+    arguments: { processInstanceKey: "pi-7" },
+  });
+  const state = JSON.parse(toolContentText(call.result));
+  assert.deepEqual(state, { processInstanceKey: "pi-7", state: "ACTIVE", waitingOnHuman: true });
+});
+
+test("urban_debug_instance_state returns null when the engine has no such instance", async () => {
+  let openUserTasksCalled = false;
+  const engine = fakeEngine({
+    searchProcessInstances: async () => [],
+    openUserTasks: async () => {
+      openUserTasksCalled = true;
+      return [];
+    },
+  });
+  const { router } = buildHarness({ engine });
+  const session = await connect(router);
+
+  const call = await rpc(router, session, "tools/call", {
+    name: "urban_debug_instance_state",
+    arguments: { processInstanceKey: "nope" },
+  });
+  assert.equal(toolContentText(call.result), "null");
+  assert.equal(openUserTasksCalled, false, "must not probe user tasks for an instance the engine doesn't know");
+});
+
 // ---- mutation guard (Slice 3) -----------------------------------------------------------------
 
 // A repeated credential header must read the SAME under the MCP guard as under OpenAPI route

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

@@ -82,7 +82,6 @@ import { resolveBindMode } from "../manifest.ts";
 import { json, makeRouter, type Route } from "../router.ts";
 import { API_BASE, readApiBinding } from "./api.ts";
 import { resolveAppPath } from "./datasource.ts";
-import { InstanceStateStore } from "./instance-state-store.ts";
 import { OpenUserTasksStore } from "./open-user-tasks-store.ts";
 
 /** The mount path of the MCP endpoint — a sibling of `/app/api` / `/app/agent`, mounted
@@ -785,17 +784,19 @@ function buildDebugTools(app: AppApi): DebugTool[] {
     },
     {
       name: `${DEBUG_PREFIX}instance_state`,
-      description: "Projection (urban_instance_state, ADR 0065): the canonical engine-lifecycle state for an instance.",
+      description:
+        "Engine truth: the live lifecycle state of a process instance (ACTIVE/COMPLETED/TERMINATED) via searchProcessInstances, plus `waitingOnHuman` from its open user tasks. `null` means the engine has no such instance (not merely 'not yet terminal').",
       inputSchema: {
         type: "object",
         properties: { processInstanceKey: OPTIONAL_STRING },
         required: ["processInstanceKey"],
       },
-      run: (args) => {
+      run: async (args) => {
         const key = requireString(args, "processInstanceKey");
-        const db = projectionDb();
-        if (!db) return Promise.resolve(null);
-        return Promise.resolve(new InstanceStateStore(db).getState(key) ?? null);
+        const [snapshot] = await app.engine.searchProcessInstances({ processInstanceKeys: [key] });
+        if (!snapshot) return null;
+        const openTasks = await app.engine.openUserTasks({ processInstanceKey: key });
+        return { processInstanceKey: key, state: snapshot.state, waitingOnHuman: openTasks.length > 0 };
       },
     },
     {

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

@@ -640,14 +640,16 @@ test("normalizeWaitStateType maps the wait-state kinds (case-insensitive) and re
 });
 
 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"]);
+  // The deployed floor is exactly JOB|MESSAGE|USER_TASK — the single source of truth both
+  // adapters gate on (USER_TASK shipped in Magikcraft/nano-bpm#1042).
+  assert.deepEqual([...DEPLOYED_WAIT_STATE_TYPES], ["JOB", "MESSAGE", "USER_TASK"]);
   // 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.doesNotThrow(() => assertDeployedWaitStateType("USER_TASK"));
+  // Every canonical type still outside the floor is rejected with a typed, descriptive error.
+  for (const waitStateType of ["TIMER", "SIGNAL", "CONDITION"] as const) {
     assert.throws(
       () => assertDeployedWaitStateType(waitStateType),
       (err: unknown) => {
@@ -843,11 +845,56 @@ test("searchElementInstanceWaitStates forwards a waitStateType selector and read
   ]);
 });
 
+test("searchElementInstanceWaitStates maps a USER_TASK park, unwrapping details.taskKey → userTaskKey (mock SDK client, not a live gateway)", async () => {
+  // MOCK-ONLY LEG: this exercises the SDK adapter's row mapping against a `fakeSdkClient`, not
+  // a live gateway — the canonical parity assertion against a real engine lives in the
+  // adapter-agnostic `runEngineClientContract` USER_TASK leg (contract.ts), run against the
+  // live `SdkEngineClient` in the integration lane. Here we only pin the shape the engine's
+  // wait-state read model returns for a USER_TASK park (Magikcraft/nano-bpm#1042): the park's
+  // `taskKey` under `details` unwraps to the seam's `userTaskKey`.
+  let seenInput: unknown;
+  const client = fakeSdkClient({
+    searchElementInstanceWaitStates: async (input) => {
+      seenInput = input;
+      return {
+        items: [
+          {
+            elementInstanceKey: 7,
+            processInstanceKey: 3,
+            elementId: "review",
+            type: "USER_TASK",
+            details: { waitStateType: "USER_TASK", taskKey: 90 },
+          },
+          {
+            elementInstanceKey: 8,
+            processInstanceKey: 3,
+            elementId: "review2",
+            details: { waitStateType: "USER_TASK" },
+          }, // USER_TASK with no taskKey → dropped (missing required identity)
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchElementInstanceWaitStates({ processInstanceKey: "3", waitStateType: "USER_TASK" });
+  assert.deepEqual(seenInput, { filter: { processInstanceKey: "3", waitStateType: "USER_TASK" } });
+  assert.deepEqual(out, [
+    {
+      elementInstanceKey: "7",
+      processInstanceKey: "3",
+      elementId: "review",
+      elementType: "USER_TASK",
+      waitStateType: "USER_TASK",
+      userTaskKey: "90",
+    },
+  ]);
+});
+
 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).
+  // The deployed gateway's read model implements JOB|MESSAGE|USER_TASK and 422s any other
+  // filter value. The SDK adapter must fail fast client-side (not issue the call), so an app
+  // authoring `waitStateType: "TIMER"` cannot ship green then blow up at runtime (issues
+  // nanobpm/nano-ide#497, #498).
   let called = false;
   const client = fakeSdkClient({
     searchElementInstanceWaitStates: async () => {
@@ -856,7 +903,7 @@ test("searchElementInstanceWaitStates rejects a waitStateType outside the deploy
     },
   });
   const engine = new SdkEngineClient(client);
-  for (const waitStateType of ["USER_TASK", "TIMER", "SIGNAL", "CONDITION"] as const) {
+  for (const waitStateType of ["TIMER", "SIGNAL", "CONDITION"] as const) {
     await assert.rejects(
       engine.searchElementInstanceWaitStates({ waitStateType }),
       (err: unknown) => {
@@ -868,8 +915,9 @@ test("searchElementInstanceWaitStates rejects a waitStateType outside the deploy
     );
   }
   assert.equal(called, false, "the gateway must not be called for an out-of-floor filter");
-  // An in-floor filter still reaches the gateway.
+  // Every in-floor filter still reaches the gateway.
   await engine.searchElementInstanceWaitStates({ waitStateType: "JOB" });
+  await engine.searchElementInstanceWaitStates({ waitStateType: "USER_TASK" });
   assert.equal(called, true);
 });
 

package/src/runtime/engine/nanosdk.ts

@@ -867,9 +867,10 @@ export class SdkEngineClient implements EngineClient {
     filter?: ElementInstanceWaitStateFilter,
   ): Promise<ElementInstanceWaitState[]> {
     // 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).
+    // A `waitStateType` selector outside the deployed floor (`JOB | MESSAGE | USER_TASK`) 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`