@nanobpm/urban 0.91.0 → 0.92.0

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/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.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

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