@nanobpm/urban 0.49.0 → 0.50.0

package/dist/runtime/core/form-contract.d.ts

@@ -0,0 +1,58 @@
+import { presentFormIdentifier } from "./host.ts";
+import type { FormSchema } from "./host.ts";
+export { presentFormIdentifier };
+/**
+ * Resolve which identifier addresses a form for {@link EngineClient.getForm}, applying the
+ * contract's shared presence + preference rule: prefer a present `formKey`, else fall back
+ * to a present `formId`; an empty/whitespace-only value is *absent* (via
+ * {@link presentFormIdentifier}), so a blank `?formKey=` falls through to a valid `formId`
+ * instead of short-circuiting to null. Returns `null` when neither identifier is present.
+ *
+ * `kind` distinguishes a resolved deploy key (`"key"`) from an authored form id (`"id"`),
+ * which a key-addressed store (the WASM adapter) must itself resolve to a deploy key; a
+ * key/id-agnostic backend (the REST gateway) can ignore `kind` and address by `value`.
+ */
+export declare function resolveFormIdentifier(input: {
+    formKey?: string;
+    formId?: string;
+}): {
+    kind: "key" | "id";
+    value: string;
+} | null;
+/**
+ * Parse a deployed form-js schema into the object the surface renders. The engine
+ * serializes it as a JSON string, so parse it; tolerate an already-parsed object (an
+ * in-memory/embedded engine). Returns `null` for anything that is neither a JSON object
+ * string nor an object (which the caller treats as "no such form").
+ */
+export declare function parseFormSchema(raw: unknown): Record<string, unknown> | null;
+/**
+ * Assemble the {@link FormSchema} result with the contract's presence guards: a blank or
+ * whitespace-only `formKey`/`formId`, or a non-numeric `version`, is omitted rather than
+ * surfaced as an empty/garbage value. Identifiers are trimmed (the shared presence rule), so
+ * a padded `formKey` never leaks whitespace; `formKey` is stringified (the REST body may carry
+ * it as a number).
+ */
+export declare function buildFormSchema(parts: {
+    schema: Record<string, unknown>;
+    formKey?: unknown;
+    formId?: unknown;
+    version?: unknown;
+}): FormSchema;
+/**
+ * Select a user task's form linkage from a raw engine record for
+ * {@link EngineClient.searchUserTasks}, applying the contract's non-empty rule (a blank
+ * `formKey`/`externalFormReference` is absent). The engine resolves a
+ * `<zeebe:formDefinition formId="X" />` linkage to the latest deployed form's key at task
+ * creation, so a resolved `formKey` (not a form id) is the linkage a task reports.
+ *
+ * A key-addressed engine that does *not* itself resolve that linkage (the WASM adapter)
+ * can pass `resolveFormKeyByFormId` to map an authored `formId` on the task to the deploy
+ * key; a backend that already resolved it (the REST gateway) omits the resolver, and the
+ * authored-id path is simply not taken. A blank or whitespace-only `formKey`/`formId`/
+ * `externalFormReference` is treated as absent (the shared trimming presence rule).
+ */
+export declare function pickFormLinkage(raw: Record<string, unknown>, resolveFormKeyByFormId?: (formId: string) => string | undefined): {
+    formKey?: string;
+    externalFormReference?: string;
+};

package/dist/runtime/core/form-contract.js

@@ -0,0 +1,108 @@
+// The shared, transport-agnostic normalization glue for the form + user-task parts of
+// the {@link EngineClient} contract. Both engine adapters — the live SDK/REST adapter
+// (`engine/nanosdk.ts`, `SdkEngineClient`) and the in-process WASM test adapter
+// (`@nanobpm/urban-testkit`, `WasmEngineClient`) — reproduce the same API-layer
+// conveniences (form storage + `formId`→`formKey` resolution, form-schema parsing,
+// user-task form linkage) on top of their own transport. Historically each adapter
+// hand-mirrored these rules (with literal `// Mirror … exactly` comments), and that
+// copy-paste drifted — e.g. a local `presentFormIdentifier` copy that trimmed for the
+// emptiness check but returned the *untrimmed* value. Centralizing the rules here so
+// both adapters call the *same* code removes that drift class (issue #252).
+import { presentFormIdentifier } from "./host.js";
+import { isRecord } from "./guards.js";
+export { presentFormIdentifier };
+/**
+ * Presence-check a possibly-numeric identifier under the shared trim rule. The REST body may
+ * carry a `formKey` as a number, so coerce it to a string; an empty or whitespace-only string
+ * is *absent* (via {@link presentFormIdentifier}, which also trims). Any other type is absent.
+ * This is the same trimming presence rule {@link resolveFormIdentifier} applies, so a blank
+ * key can never be surfaced as an empty/whitespace value — the drift-bug class #252 targets.
+ */
+function presentKey(v) {
+    if (typeof v === "number")
+        return presentFormIdentifier(String(v));
+    if (typeof v === "string")
+        return presentFormIdentifier(v);
+    return undefined;
+}
+/**
+ * Resolve which identifier addresses a form for {@link EngineClient.getForm}, applying the
+ * contract's shared presence + preference rule: prefer a present `formKey`, else fall back
+ * to a present `formId`; an empty/whitespace-only value is *absent* (via
+ * {@link presentFormIdentifier}), so a blank `?formKey=` falls through to a valid `formId`
+ * instead of short-circuiting to null. Returns `null` when neither identifier is present.
+ *
+ * `kind` distinguishes a resolved deploy key (`"key"`) from an authored form id (`"id"`),
+ * which a key-addressed store (the WASM adapter) must itself resolve to a deploy key; a
+ * key/id-agnostic backend (the REST gateway) can ignore `kind` and address by `value`.
+ */
+export function resolveFormIdentifier(input) {
+    const key = presentFormIdentifier(input.formKey);
+    if (key != null)
+        return { kind: "key", value: key };
+    const id = presentFormIdentifier(input.formId);
+    if (id != null)
+        return { kind: "id", value: id };
+    return null;
+}
+/**
+ * Parse a deployed form-js schema into the object the surface renders. The engine
+ * serializes it as a JSON string, so parse it; tolerate an already-parsed object (an
+ * in-memory/embedded engine). Returns `null` for anything that is neither a JSON object
+ * string nor an object (which the caller treats as "no such form").
+ */
+export function parseFormSchema(raw) {
+    if (isRecord(raw))
+        return raw;
+    if (typeof raw !== "string")
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Assemble the {@link FormSchema} result with the contract's presence guards: a blank or
+ * whitespace-only `formKey`/`formId`, or a non-numeric `version`, is omitted rather than
+ * surfaced as an empty/garbage value. Identifiers are trimmed (the shared presence rule), so
+ * a padded `formKey` never leaks whitespace; `formKey` is stringified (the REST body may carry
+ * it as a number).
+ */
+export function buildFormSchema(parts) {
+    const formKey = presentKey(parts.formKey);
+    const formId = typeof parts.formId === "string" ? presentFormIdentifier(parts.formId) : undefined;
+    return {
+        schema: parts.schema,
+        ...(formKey != null ? { formKey } : {}),
+        ...(formId != null ? { formId } : {}),
+        ...(typeof parts.version === "number" ? { version: parts.version } : {}),
+    };
+}
+/**
+ * Select a user task's form linkage from a raw engine record for
+ * {@link EngineClient.searchUserTasks}, applying the contract's non-empty rule (a blank
+ * `formKey`/`externalFormReference` is absent). The engine resolves a
+ * `<zeebe:formDefinition formId="X" />` linkage to the latest deployed form's key at task
+ * creation, so a resolved `formKey` (not a form id) is the linkage a task reports.
+ *
+ * A key-addressed engine that does *not* itself resolve that linkage (the WASM adapter)
+ * can pass `resolveFormKeyByFormId` to map an authored `formId` on the task to the deploy
+ * key; a backend that already resolved it (the REST gateway) omits the resolver, and the
+ * authored-id path is simply not taken. A blank or whitespace-only `formKey`/`formId`/
+ * `externalFormReference` is treated as absent (the shared trimming presence rule).
+ */
+export function pickFormLinkage(raw, resolveFormKeyByFormId) {
+    const directKey = presentKey(raw.formKey);
+    const authoredId = typeof raw.formId === "string" ? presentFormIdentifier(raw.formId) : undefined;
+    const formKey = directKey ?? (authoredId && resolveFormKeyByFormId ? resolveFormKeyByFormId(authoredId) : undefined);
+    const externalFormReference = typeof raw.externalFormReference === "string"
+        ? presentFormIdentifier(raw.externalFormReference)
+        : undefined;
+    return {
+        ...(formKey ? { formKey } : {}),
+        ...(externalFormReference ? { externalFormReference } : {}),
+    };
+}

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

@@ -187,6 +187,13 @@ export interface WorkerSubscription {
  * element-instance state set (which adds SKIPPED/CANCELED/FAILED for tokens).
  */
 export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
+/**
+ * A user task's lifecycle state, as the engine reports it on a `/v2/user-tasks/search`
+ * result. `CREATED` is the only *open* (answerable) state — a task in any other state has
+ * already been answered (`COMPLETED`), withdrawn (`CANCELED`), or errored (`FAILED`) and must
+ * never surface in the `taskInbox` as if it were actionable.
+ */
+export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
 /** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
 export interface ProcessInstanceSnapshot {
     readonly processInstanceKey: string;
@@ -253,12 +260,16 @@ export interface EngineClient {
         correlationKey?: string;
         variables?: Record<string, unknown>;
     }): Promise<void>;
-    /** Search open user tasks (optionally by process instance). Each result carries the
-     *  task's resolved form linkage (`formKey`/`externalFormReference`) when present. */
+    /** Search user tasks (optionally by process instance, assignee, or candidate group).
+     *  By default this is unfiltered by lifecycle state and may return tasks in any state
+     *  (e.g. completed/canceled); pass `state: "CREATED"` to constrain the search to open
+     *  (answerable) tasks. Each result carries the task's resolved form linkage
+     *  (`formKey`/`externalFormReference`) when present. */
     searchUserTasks(filter?: {
         processInstanceKey?: string;
         assignee?: string;
         candidateGroup?: string;
+        state?: UserTaskState;
     }): Promise<UserTaskSummary[]>;
     /**
      * Fetch a deployed form's form-js schema for the `taskInbox` surface. Resolve by

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

@@ -201,7 +201,14 @@ export function mountSurfaces(ctx, app) {
             source: "surface:taskInbox",
             handler: async (req) => {
                 const pik = req.query.get("processInstanceKey") ?? undefined;
-                const tasks = await app.engine.searchUserTasks(pik ? { processInstanceKey: pik } : undefined);
+                // Constrain the inbox to open (answerable) tasks. Without a state filter the engine
+                // returns tasks in every state (CREATED/COMPLETED/CANCELED/...), so already-answered
+                // or withdrawn tasks would surface as if actionable — completing one then fails with
+                // "User task ... is not active". See nanobpm/nano-ide#248.
+                const tasks = await app.engine.searchUserTasks({
+                    state: "CREATED",
+                    ...(pik ? { processInstanceKey: pik } : {}),
+                });
                 return json(tasks);
             },
         });

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskSummary, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -140,6 +140,7 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKey?: string;
         assignee?: string;
         candidateGroup?: string;
+        state?: UserTaskState;
     }): Promise<UserTaskSummary[]>;
     getForm(input: {
         formKey?: string;

package/dist/runtime/engine/nanosdk.js

@@ -18,7 +18,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { isBpmnError, presentFormIdentifier } from "../core/host.js";
+import { isBpmnError } from "../core/host.js";
+import { buildFormSchema, parseFormSchema, pickFormLinkage, resolveFormIdentifier, } from "../core/form-contract.js";
 import { isRecord } from "../core/guards.js";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -110,17 +111,13 @@ export class SdkEngineClient {
                 return [];
             }
             // The engine resolves a `formId="X"` linkage to the latest deployed form's key at
-            // task creation, so `formKey` (not a form id) is the linkage it reports on the task.
-            const formKey = it.formKey != null && it.formKey !== "" ? String(it.formKey) : undefined;
-            const externalFormReference = typeof it.externalFormReference === "string" && it.externalFormReference !== ""
-                ? it.externalFormReference
-                : undefined;
+            // task creation, so `formKey` (not a form id) is the linkage it reports on the task;
+            // no `resolveFormKeyByFormId` resolver is passed because the gateway already resolved it.
             return [{
                     userTaskKey: String(userTaskKey),
                     elementId: typeof it.elementId === "string" ? it.elementId : undefined,
                     variables: isRecord(it.variables) ? it.variables : undefined,
-                    ...(formKey ? { formKey } : {}),
-                    ...(externalFormReference ? { externalFormReference } : {}),
+                    ...pickFormLinkage(it),
                 }];
         });
     }
@@ -132,13 +129,15 @@ export class SdkEngineClient {
         // form or 404s (→ null) when there is no such form.
         //
         // This is the single gate that resolves which identifier addresses the form: an
-        // empty/whitespace identifier is treated as *absent* (via `presentFormIdentifier`, the
-        // shared presence rule) so a blank `formKey` (e.g. a `?formKey=` query param) falls
+        // empty/whitespace identifier is treated as *absent* (via the shared presence rule in
+        // `resolveFormIdentifier`) so a blank `formKey` (e.g. a `?formKey=` query param) falls
         // through to a valid `formId` instead of being taken as a present-but-unresolvable key
-        // that short-circuits to null.
-        const key = presentFormIdentifier(input.formKey) ?? presentFormIdentifier(input.formId);
-        if (key == null)
+        // that short-circuits to null. The REST gateway addresses a form by `value` regardless
+        // of whether it is a deploy key or an authored id, so `kind` is not consulted here.
+        const resolved = resolveFormIdentifier(input);
+        if (resolved == null)
             return null;
+        const key = resolved.value;
         let body;
         try {
             body = await this.client.getFormByKey({ formKey: key }, { consistency: { waitUpToMs: 0 } });
@@ -154,31 +153,21 @@ export class SdkEngineClient {
         }
         if (!isRecord(body))
             return null;
-        const rawSchema = body.schema;
         // The engine serializes the form-js schema as a JSON string; parse it to the object
         // the surface renders. Tolerate an already-parsed object (an in-memory/embedded engine).
-        let schema;
-        if (typeof rawSchema === "string") {
-            try {
-                const parsed = JSON.parse(rawSchema);
-                if (isRecord(parsed))
-                    schema = parsed;
-            }
-            catch {
+        const schema = parseFormSchema(body.schema);
+        if (!schema) {
+            if (typeof body.schema === "string") {
                 this.log("warn", "getForm: form schema is not valid JSON", { key, formKey: input.formKey, formId: input.formId });
             }
-        }
-        else if (isRecord(rawSchema)) {
-            schema = rawSchema;
-        }
-        if (!schema)
             return null;
-        return {
+        }
+        return buildFormSchema({
             schema,
-            ...(body.formKey != null && body.formKey !== "" ? { formKey: String(body.formKey) } : {}),
-            ...(typeof body.formId === "string" && body.formId !== "" ? { formId: body.formId } : {}),
-            ...(typeof body.version === "number" ? { version: body.version } : {}),
-        };
+            formKey: body.formKey,
+            formId: body.formId,
+            version: body.version,
+        });
     }
     async completeUserTask(userTaskKey, variables) {
         await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });

package/dist/runtime/index.d.ts

@@ -4,7 +4,8 @@ export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, p
 export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
+export type { EngineClient, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, WatchHandle, WorkerSubscription, } from "./core/host.ts";
+export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";
 export type { Logger, LogLevel, LogFields, LogSink } from "./core/logger.ts";

package/dist/runtime/index.js

@@ -5,6 +5,10 @@ export { createUrbanApp } from "./core/runtime.js";
 export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.js";
 // Validation
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
+// Shared form/user-task contract normalization (issue #252): the single source of truth
+// both engine adapters (SDK/REST + WASM test double) call, so their form-identifier,
+// form-schema, and user-task form-linkage handling cannot drift.
+export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.js";
 // Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
 // so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).
 export { createLogger } from "./core/logger.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.49.0",
+	"version": "0.50.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/form-contract.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  buildFormSchema,
+  parseFormSchema,
+  pickFormLinkage,
+  resolveFormIdentifier,
+} from "./form-contract.ts";
+
+test("resolveFormIdentifier prefers a present formKey over a formId", () => {
+  assert.deepEqual(resolveFormIdentifier({ formKey: "42", formId: "myForm" }), {
+    kind: "key",
+    value: "42",
+  });
+});
+
+test("resolveFormIdentifier falls back to formId when formKey is absent/blank/whitespace", () => {
+  assert.deepEqual(resolveFormIdentifier({ formId: "myForm" }), { kind: "id", value: "myForm" });
+  for (const formKey of ["", "   "]) {
+    assert.deepEqual(
+      resolveFormIdentifier({ formKey, formId: "myForm" }),
+      { kind: "id", value: "myForm" },
+      `formKey=${JSON.stringify(formKey)} must fall through to formId`,
+    );
+  }
+});
+
+test("resolveFormIdentifier trims the resolved value and returns null when neither is present", () => {
+  assert.deepEqual(resolveFormIdentifier({ formKey: "  42  " }), { kind: "key", value: "42" });
+  assert.equal(resolveFormIdentifier({}), null);
+  assert.equal(resolveFormIdentifier({ formKey: "  ", formId: "" }), null);
+});
+
+test("parseFormSchema parses a JSON-object string, passes an object through, and rejects the rest", () => {
+  assert.deepEqual(parseFormSchema('{"a":1}'), { a: 1 });
+  const obj = { a: 1 };
+  assert.equal(parseFormSchema(obj), obj);
+  assert.equal(parseFormSchema("not json"), null);
+  assert.equal(parseFormSchema("[1,2]"), null, "a JSON array is not a form schema object");
+  assert.equal(parseFormSchema(42), null);
+  assert.equal(parseFormSchema(null), null);
+});
+
+test("buildFormSchema applies presence guards and stringifies a numeric formKey", () => {
+  const schema = { components: [] };
+  assert.deepEqual(buildFormSchema({ schema, formKey: 42, formId: "myForm", version: 3 }), {
+    schema,
+    formKey: "42",
+    formId: "myForm",
+    version: 3,
+  });
+  // Blank/garbage parts are omitted rather than surfaced as empty values.
+  assert.deepEqual(buildFormSchema({ schema, formKey: "", formId: "", version: "3" }), { schema });
+  assert.deepEqual(buildFormSchema({ schema }), { schema });
+});
+
+test("buildFormSchema trims padded identifiers and drops whitespace-only ones (the #252 drift bug)", () => {
+  const schema = { components: [] };
+  // Whitespace-only key/id are absent, not surfaced as " ".
+  assert.deepEqual(buildFormSchema({ schema, formKey: "   ", formId: "  " }), { schema });
+  // A padded key/id is trimmed to its space-free value, not surfaced with the padding.
+  assert.deepEqual(buildFormSchema({ schema, formKey: "  42  ", formId: "  myForm  " }), {
+    schema,
+    formKey: "42",
+    formId: "myForm",
+  });
+});
+
+test("pickFormLinkage prefers a direct formKey and carries an externalFormReference", () => {
+  assert.deepEqual(
+    pickFormLinkage({ formKey: 42, externalFormReference: "https://x/form" }),
+    { formKey: "42", externalFormReference: "https://x/form" },
+  );
+  // Blank linkage fields are treated as absent.
+  assert.deepEqual(pickFormLinkage({ formKey: "", externalFormReference: "" }), {});
+});
+
+test("pickFormLinkage trims padded linkage fields and drops whitespace-only ones", () => {
+  // Whitespace-only key/id/ref are absent, not surfaced with whitespace.
+  assert.deepEqual(
+    pickFormLinkage({ formKey: "   ", externalFormReference: "  " }),
+    {},
+  );
+  // A padded key/ref is trimmed; a padded authored id is trimmed before the resolver sees it.
+  assert.deepEqual(
+    pickFormLinkage({ formKey: "  7  ", externalFormReference: "  https://x/form  " }),
+    { formKey: "7", externalFormReference: "https://x/form" },
+  );
+  assert.deepEqual(
+    pickFormLinkage({ formId: "  myForm  " }, (id) => (id === "myForm" ? "form-7" : undefined)),
+    { formKey: "form-7" },
+    "the authored formId is trimmed before the key resolver is called",
+  );
+});
+
+test("pickFormLinkage resolves an authored formId to a deploy key only via the callback", () => {
+  const raw = { formId: "myForm" };
+  // No resolver (the gateway path): an authored id is not turned into a key.
+  assert.deepEqual(pickFormLinkage(raw), {});
+  // With a resolver (the WASM/key-addressed path): the id maps to the latest deploy key.
+  assert.deepEqual(
+    pickFormLinkage(raw, (id) => (id === "myForm" ? "form-7" : undefined)),
+    { formKey: "form-7" },
+  );
+});

package/src/runtime/core/form-contract.ts

@@ -0,0 +1,121 @@
+// The shared, transport-agnostic normalization glue for the form + user-task parts of
+// the {@link EngineClient} contract. Both engine adapters — the live SDK/REST adapter
+// (`engine/nanosdk.ts`, `SdkEngineClient`) and the in-process WASM test adapter
+// (`@nanobpm/urban-testkit`, `WasmEngineClient`) — reproduce the same API-layer
+// conveniences (form storage + `formId`→`formKey` resolution, form-schema parsing,
+// user-task form linkage) on top of their own transport. Historically each adapter
+// hand-mirrored these rules (with literal `// Mirror … exactly` comments), and that
+// copy-paste drifted — e.g. a local `presentFormIdentifier` copy that trimmed for the
+// emptiness check but returned the *untrimmed* value. Centralizing the rules here so
+// both adapters call the *same* code removes that drift class (issue #252).
+
+import { presentFormIdentifier } from "./host.ts";
+import type { FormSchema } from "./host.ts";
+import { isRecord } from "./guards.ts";
+
+export { presentFormIdentifier };
+
+/**
+ * Presence-check a possibly-numeric identifier under the shared trim rule. The REST body may
+ * carry a `formKey` as a number, so coerce it to a string; an empty or whitespace-only string
+ * is *absent* (via {@link presentFormIdentifier}, which also trims). Any other type is absent.
+ * This is the same trimming presence rule {@link resolveFormIdentifier} applies, so a blank
+ * key can never be surfaced as an empty/whitespace value — the drift-bug class #252 targets.
+ */
+function presentKey(v: unknown): string | undefined {
+  if (typeof v === "number") return presentFormIdentifier(String(v));
+  if (typeof v === "string") return presentFormIdentifier(v);
+  return undefined;
+}
+
+/**
+ * Resolve which identifier addresses a form for {@link EngineClient.getForm}, applying the
+ * contract's shared presence + preference rule: prefer a present `formKey`, else fall back
+ * to a present `formId`; an empty/whitespace-only value is *absent* (via
+ * {@link presentFormIdentifier}), so a blank `?formKey=` falls through to a valid `formId`
+ * instead of short-circuiting to null. Returns `null` when neither identifier is present.
+ *
+ * `kind` distinguishes a resolved deploy key (`"key"`) from an authored form id (`"id"`),
+ * which a key-addressed store (the WASM adapter) must itself resolve to a deploy key; a
+ * key/id-agnostic backend (the REST gateway) can ignore `kind` and address by `value`.
+ */
+export function resolveFormIdentifier(
+  input: { formKey?: string; formId?: string },
+): { kind: "key" | "id"; value: string } | null {
+  const key = presentFormIdentifier(input.formKey);
+  if (key != null) return { kind: "key", value: key };
+  const id = presentFormIdentifier(input.formId);
+  if (id != null) return { kind: "id", value: id };
+  return null;
+}
+
+/**
+ * Parse a deployed form-js schema into the object the surface renders. The engine
+ * serializes it as a JSON string, so parse it; tolerate an already-parsed object (an
+ * in-memory/embedded engine). Returns `null` for anything that is neither a JSON object
+ * string nor an object (which the caller treats as "no such form").
+ */
+export function parseFormSchema(raw: unknown): Record<string, unknown> | null {
+  if (isRecord(raw)) return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assemble the {@link FormSchema} result with the contract's presence guards: a blank or
+ * whitespace-only `formKey`/`formId`, or a non-numeric `version`, is omitted rather than
+ * surfaced as an empty/garbage value. Identifiers are trimmed (the shared presence rule), so
+ * a padded `formKey` never leaks whitespace; `formKey` is stringified (the REST body may carry
+ * it as a number).
+ */
+export function buildFormSchema(parts: {
+  schema: Record<string, unknown>;
+  formKey?: unknown;
+  formId?: unknown;
+  version?: unknown;
+}): FormSchema {
+  const formKey = presentKey(parts.formKey);
+  const formId = typeof parts.formId === "string" ? presentFormIdentifier(parts.formId) : undefined;
+  return {
+    schema: parts.schema,
+    ...(formKey != null ? { formKey } : {}),
+    ...(formId != null ? { formId } : {}),
+    ...(typeof parts.version === "number" ? { version: parts.version } : {}),
+  };
+}
+
+/**
+ * Select a user task's form linkage from a raw engine record for
+ * {@link EngineClient.searchUserTasks}, applying the contract's non-empty rule (a blank
+ * `formKey`/`externalFormReference` is absent). The engine resolves a
+ * `<zeebe:formDefinition formId="X" />` linkage to the latest deployed form's key at task
+ * creation, so a resolved `formKey` (not a form id) is the linkage a task reports.
+ *
+ * A key-addressed engine that does *not* itself resolve that linkage (the WASM adapter)
+ * can pass `resolveFormKeyByFormId` to map an authored `formId` on the task to the deploy
+ * key; a backend that already resolved it (the REST gateway) omits the resolver, and the
+ * authored-id path is simply not taken. A blank or whitespace-only `formKey`/`formId`/
+ * `externalFormReference` is treated as absent (the shared trimming presence rule).
+ */
+export function pickFormLinkage(
+  raw: Record<string, unknown>,
+  resolveFormKeyByFormId?: (formId: string) => string | undefined,
+): { formKey?: string; externalFormReference?: string } {
+  const directKey = presentKey(raw.formKey);
+  const authoredId = typeof raw.formId === "string" ? presentFormIdentifier(raw.formId) : undefined;
+  const formKey =
+    directKey ?? (authoredId && resolveFormKeyByFormId ? resolveFormKeyByFormId(authoredId) : undefined);
+  const externalFormReference =
+    typeof raw.externalFormReference === "string"
+      ? presentFormIdentifier(raw.externalFormReference)
+      : undefined;
+  return {
+    ...(formKey ? { formKey } : {}),
+    ...(externalFormReference ? { externalFormReference } : {}),
+  };
+}

package/src/runtime/core/host.ts

@@ -217,6 +217,14 @@ export interface WorkerSubscription {
  */
 export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
 
+/**
+ * A user task's lifecycle state, as the engine reports it on a `/v2/user-tasks/search`
+ * result. `CREATED` is the only *open* (answerable) state — a task in any other state has
+ * already been answered (`COMPLETED`), withdrawn (`CANCELED`), or errored (`FAILED`) and must
+ * never surface in the `taskInbox` as if it were actionable.
+ */
+export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
+
 /** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
 export interface ProcessInstanceSnapshot {
   readonly processInstanceKey: string;
@@ -277,12 +285,16 @@ export interface EngineClient {
     correlationKey?: string;
     variables?: Record<string, unknown>;
   }): Promise<void>;
-  /** Search open user tasks (optionally by process instance). Each result carries the
-   *  task's resolved form linkage (`formKey`/`externalFormReference`) when present. */
+  /** Search user tasks (optionally by process instance, assignee, or candidate group).
+   *  By default this is unfiltered by lifecycle state and may return tasks in any state
+   *  (e.g. completed/canceled); pass `state: "CREATED"` to constrain the search to open
+   *  (answerable) tasks. Each result carries the task's resolved form linkage
+   *  (`formKey`/`externalFormReference`) when present. */
   searchUserTasks(filter?: {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
+    state?: UserTaskState;
   }): Promise<UserTaskSummary[]>;
   /**
    * Fetch a deployed form's form-js schema for the `taskInbox` surface. Resolve by

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

@@ -171,12 +171,28 @@ test("/api/tasks surfaces the resolved form linkage", async () => {
   };
   const { tasks } = inboxRoutes(engine);
   const res = await call(tasks, { query: "processInstanceKey=pi-9" });
-  assert.deepEqual(seenFilter, { processInstanceKey: "pi-9" });
+  assert.deepEqual(seenFilter, { state: "CREATED", processInstanceKey: "pi-9" });
   const parsed = JSON.parse(String(res.body));
   assert.equal(parsed[0].formKey, "form-123");
   assert.equal(parsed[1].formKey, undefined);
 });
 
+test("/api/tasks constrains the search to open (CREATED) tasks", async () => {
+  let seenFilter: unknown;
+  const engine: EngineClient = {
+    ...fakeEngine,
+    searchUserTasks: async (filter) => {
+      seenFilter = filter;
+      return [];
+    },
+  };
+  const { tasks } = inboxRoutes(engine);
+  await call(tasks);
+  // No processInstanceKey supplied, but the inbox must still pin state=CREATED so that
+  // already-answered/canceled tasks never surface as answerable (nanobpm/nano-ide#248).
+  assert.deepEqual(seenFilter, { state: "CREATED" });
+});
+
 test("/api/form resolves a linked form's schema", async () => {
   let seen: unknown;
   const schema = { type: "default", schemaVersion: 18, components: [{ type: "textfield", key: "name", label: "Name" }] };

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

@@ -215,7 +215,14 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
       source: "surface:taskInbox",
       handler: async (req) => {
         const pik = req.query.get("processInstanceKey") ?? undefined;
-        const tasks = await app.engine.searchUserTasks(pik ? { processInstanceKey: pik } : undefined);
+        // Constrain the inbox to open (answerable) tasks. Without a state filter the engine
+        // returns tasks in every state (CREATED/COMPLETED/CANCELED/...), so already-answered
+        // or withdrawn tasks would surface as if actionable — completing one then fails with
+        // "User task ... is not active". See nanobpm/nano-ide#248.
+        const tasks = await app.engine.searchUserTasks({
+          state: "CREATED",
+          ...(pik ? { processInstanceKey: pik } : {}),
+        });
         return json(tasks);
       },
     });

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

@@ -177,8 +177,10 @@ test("publishMessage defaults correlationKey/variables", async () => {
 
 test("searchUserTasks passes zero-wait consistency and maps items", async () => {
   let consistency: unknown;
+  let input: { filter?: Record<string, unknown> } | undefined;
   const client = fakeSdkClient({
-    searchUserTasks: async (_input, c) => {
+    searchUserTasks: async (i, c) => {
+      input = i;
       consistency = c;
       return {
         items: [
@@ -192,12 +194,34 @@ test("searchUserTasks passes zero-wait consistency and maps items", async () =>
   const engine = new SdkEngineClient(client);
   const tasks = await engine.searchUserTasks({ processInstanceKey: "pi" });
   assert.deepEqual(consistency, { consistency: { waitUpToMs: 0 } });
+  // The adapter forwards the caller's filter verbatim and no longer injects a lifecycle
+  // state (#252): the search is unfiltered by state unless the caller opts in, so the
+  // taskInbox surface — not the adapter — owns the open-only (CREATED) policy. Assert
+  // individual fields so the check is independent of key insertion order.
+  assert.equal(input?.filter?.state, undefined, "no state is injected when the caller passes none");
+  assert.equal(input?.filter?.processInstanceKey, "pi");
   assert.deepEqual(tasks, [
     { userTaskKey: "7", elementId: "task_a", variables: { x: 1 } },
     { userTaskKey: "8", elementId: undefined, variables: undefined },
   ]);
 });
 
+test("searchUserTasks forwards a caller-provided lifecycle state filter", async () => {
+  let input: { filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    searchUserTasks: async (i) => {
+      input = i;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchUserTasks({ state: "CREATED", processInstanceKey: "pi" });
+  // The caller's `state` reaches the engine unchanged — the adapter neither drops nor
+  // overrides it (the taskInbox surface passes `state: "CREATED"` to constrain the inbox).
+  assert.equal(input?.filter?.state, "CREATED");
+  assert.equal(input?.filter?.processInstanceKey, "pi");
+});
+
 test("searchUserTasks surfaces the resolved form linkage", async () => {
   const client = fakeSdkClient({
     searchUserTasks: async () => ({

package/src/runtime/engine/nanosdk.ts

@@ -18,10 +18,17 @@ import type {
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
+  UserTaskState,
   UserTaskSummary,
   WorkerSubscription,
 } from "../core/host.ts";
-import { isBpmnError, presentFormIdentifier } from "../core/host.ts";
+import { isBpmnError } from "../core/host.ts";
+import {
+  buildFormSchema,
+  parseFormSchema,
+  pickFormLinkage,
+  resolveFormIdentifier,
+} from "../core/form-contract.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 import { isRecord } from "../core/guards.ts";
 
@@ -221,6 +228,7 @@ export class SdkEngineClient implements EngineClient {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
+    state?: UserTaskState;
   }): Promise<UserTaskSummary[]> {
     // User tasks are an eventually consistent read; ask for zero-wait consistency so
     // the search reflects what is currently visible without blocking.
@@ -236,19 +244,13 @@ export class SdkEngineClient implements EngineClient {
         return [];
       }
       // The engine resolves a `formId="X"` linkage to the latest deployed form's key at
-      // task creation, so `formKey` (not a form id) is the linkage it reports on the task.
-      const formKey =
-        it.formKey != null && it.formKey !== "" ? String(it.formKey) : undefined;
-      const externalFormReference =
-        typeof it.externalFormReference === "string" && it.externalFormReference !== ""
-          ? it.externalFormReference
-          : undefined;
+      // task creation, so `formKey` (not a form id) is the linkage it reports on the task;
+      // no `resolveFormKeyByFormId` resolver is passed because the gateway already resolved it.
       return [{
         userTaskKey: String(userTaskKey),
         elementId: typeof it.elementId === "string" ? it.elementId : undefined,
         variables: isRecord(it.variables) ? it.variables : undefined,
-        ...(formKey ? { formKey } : {}),
-        ...(externalFormReference ? { externalFormReference } : {}),
+        ...pickFormLinkage(it),
       }];
     });
   }
@@ -261,12 +263,14 @@ export class SdkEngineClient implements EngineClient {
     // form or 404s (→ null) when there is no such form.
     //
     // This is the single gate that resolves which identifier addresses the form: an
-    // empty/whitespace identifier is treated as *absent* (via `presentFormIdentifier`, the
-    // shared presence rule) so a blank `formKey` (e.g. a `?formKey=` query param) falls
+    // empty/whitespace identifier is treated as *absent* (via the shared presence rule in
+    // `resolveFormIdentifier`) so a blank `formKey` (e.g. a `?formKey=` query param) falls
     // through to a valid `formId` instead of being taken as a present-but-unresolvable key
-    // that short-circuits to null.
-    const key = presentFormIdentifier(input.formKey) ?? presentFormIdentifier(input.formId);
-    if (key == null) return null;
+    // that short-circuits to null. The REST gateway addresses a form by `value` regardless
+    // of whether it is a deploy key or an authored id, so `kind` is not consulted here.
+    const resolved = resolveFormIdentifier(input);
+    if (resolved == null) return null;
+    const key = resolved.value;
     let body: Record<string, unknown>;
     try {
       body = await this.client.getFormByKey(
@@ -283,27 +287,21 @@ export class SdkEngineClient implements EngineClient {
       return null;
     }
     if (!isRecord(body)) return null;
-    const rawSchema = body.schema;
     // The engine serializes the form-js schema as a JSON string; parse it to the object
     // the surface renders. Tolerate an already-parsed object (an in-memory/embedded engine).
-    let schema: Record<string, unknown> | undefined;
-    if (typeof rawSchema === "string") {
-      try {
-        const parsed: unknown = JSON.parse(rawSchema);
-        if (isRecord(parsed)) schema = parsed;
-      } catch {
+    const schema = parseFormSchema(body.schema);
+    if (!schema) {
+      if (typeof body.schema === "string") {
         this.log("warn", "getForm: form schema is not valid JSON", { key, formKey: input.formKey, formId: input.formId });
       }
-    } else if (isRecord(rawSchema)) {
-      schema = rawSchema;
+      return null;
     }
-    if (!schema) return null;
-    return {
+    return buildFormSchema({
       schema,
-      ...(body.formKey != null && body.formKey !== "" ? { formKey: String(body.formKey) } : {}),
-      ...(typeof body.formId === "string" && body.formId !== "" ? { formId: body.formId } : {}),
-      ...(typeof body.version === "number" ? { version: body.version } : {}),
-    };
+      formKey: body.formKey,
+      formId: body.formId,
+      version: body.version,
+    });
   }
 
   async completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void> {

package/src/runtime/index.ts

@@ -52,16 +52,31 @@ export type { ValidationIssue } from "./core/validate.ts";
 export type {
   EngineClient,
   EngineJob,
+  FormSchema,
   HostContext,
   HttpHandler,
   HttpRequest,
   HttpResponse,
   HttpServer,
   JobHandler,
+  ProcessInstanceSnapshot,
+  ProcessInstanceState,
   SqliteDb,
+  UserTaskState,
+  UserTaskSummary,
   WatchHandle,
   WorkerSubscription,
 } from "./core/host.ts";
+// Shared form/user-task contract normalization (issue #252): the single source of truth
+// both engine adapters (SDK/REST + WASM test double) call, so their form-identifier,
+// form-schema, and user-task form-linkage handling cannot drift.
+export {
+  buildFormSchema,
+  parseFormSchema,
+  pickFormLinkage,
+  presentFormIdentifier,
+  resolveFormIdentifier,
+} from "./core/form-contract.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 // Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
 // so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).