@nanobpm/urban 0.28.0 → 0.29.0

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

@@ -0,0 +1,181 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import { makeGateway } from "./gateway.ts";
+import {
+  ensureProvenanceTable,
+  makeProvenanceRecorder,
+  WRITE_PROVENANCE_TABLE,
+} from "./datasource.ts";
+import {
+  __resetExecStoreForTests,
+  currentJobContext,
+  installExecStore,
+  runInJobContext,
+  type JobExecContext,
+} from "../execContext.ts";
+import type { HostContext, SqliteDb } from "../host.ts";
+
+interface Note {
+  id: number;
+  body: string;
+}
+
+interface ProvRow {
+  source: string;
+  table_name: string;
+  pk_value: string;
+  instance_key: string | null;
+  element_id: string | null;
+  job_type: string | null;
+  op: string;
+  at: string;
+}
+
+async function withSource(
+  fn: (host: HostContext, db: SqliteDb) => Promise<void>,
+): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-prov-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  db.exec("CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL)");
+  try {
+    await fn(host, db);
+  } finally {
+    db.close();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function provRows(db: SqliteDb): ProvRow[] {
+  return db.all<ProvRow>(`SELECT * FROM ${WRITE_PROVENANCE_TABLE} ORDER BY seq`);
+}
+
+test("insert inside a job context records a provenance row linking row → instance/element", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    const notes = src.table<Note>("notes");
+
+    let id: number | bigint = 0;
+    await runInJobContext(
+      { instanceKey: "inst-1", elementId: "Task_persist", jobType: "notes.write" },
+      async () => {
+        id = await notes.insert({ body: "hello" });
+      },
+    );
+
+    const rows = provRows(db);
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].source, "main");
+    assert.equal(rows[0].table_name, "notes");
+    assert.equal(rows[0].pk_value, String(id));
+    assert.equal(rows[0].instance_key, "inst-1");
+    assert.equal(rows[0].element_id, "Task_persist");
+    assert.equal(rows[0].job_type, "notes.write");
+    assert.equal(rows[0].op, "insert");
+    assert.ok(rows[0].at.length > 0);
+  });
+});
+
+test("insert outside any job context records no provenance (graceful degradation)", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    await src.table<Note>("notes").insert({ body: "no ctx" });
+    assert.equal(provRows(db).length, 0);
+  });
+});
+
+test("a job context without an instance key records no provenance", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    await runInJobContext({ jobType: "notes.write" }, async () => {
+      await src.table<Note>("notes").insert({ body: "no instance" });
+    });
+    assert.equal(provRows(db).length, 0);
+  });
+});
+
+test("a provenance-write failure never breaks the app insert", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    // Deliberately do NOT create the provenance table, so the recorder's own INSERT throws.
+    const src = makeGateway(db, makeProvenanceRecorder(host, db, "main"));
+    let id: number | bigint = 0;
+    await runInJobContext({ instanceKey: "inst-9" }, async () => {
+      id = await src.table<Note>("notes").insert({ body: "resilient" });
+    });
+    // The app row is written despite provenance capture failing.
+    assert.equal((await src.table<Note>("notes").get(id))?.body, "resilient");
+  });
+});
+
+test("the recorder does not record writes to urban/engine-internal tables", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    ensureProvenanceTable(db);
+    const recorder = makeProvenanceRecorder(host, db, "main");
+    runInJobContext({ instanceKey: "inst-1" }, () => {
+      recorder("_urban_migrations", 1);
+      recorder(WRITE_PROVENANCE_TABLE, 2);
+      recorder("_nano_events", 3);
+      recorder("sqlite_sequence", 4);
+    });
+    assert.equal(provRows(db).length, 0);
+  });
+});
+
+test("with no store installed, capture is a transparent no-op", async () => {
+  __resetExecStoreForTests();
+  // No installExecStore call: runInJobContext must pass through and currentJobContext be undefined.
+  let ran = false;
+  const out = runInJobContext({ instanceKey: "x" }, () => {
+    ran = true;
+    assert.equal(currentJobContext(), undefined);
+    return 42;
+  });
+  assert.equal(ran, true);
+  assert.equal(out, 42);
+});
+
+test("installExecStore is idempotent — the first install wins", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    void db;
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    // A second install with a factory that would throw must be ignored (never invoked).
+    installExecStore(() => {
+      throw new Error("second install must not run");
+    });
+    runInJobContext({ instanceKey: "inst-2" }, () => {
+      assert.equal(currentJobContext()?.instanceKey, "inst-2");
+    });
+  });
+});
+
+test("installExecStore can install after an incapable host returns no store", async () => {
+  __resetExecStoreForTests();
+  await withSource(async (host, db) => {
+    void db;
+    installExecStore(() => undefined);
+    assert.equal(currentJobContext(), undefined);
+
+    installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+    runInJobContext({ instanceKey: "inst-3" }, () => {
+      assert.equal(currentJobContext()?.instanceKey, "inst-3");
+    });
+  });
+});

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

@@ -0,0 +1,31 @@
+// The injectable timer + clock seam shared by every background loop in urban (cron
+// triggers, the instance-tracking reconciler). Keeping one definition here — rather
+// than a copy per module — means a test's fake scheduler drives them all the same
+// way, and the "clamp a far-future delay to setTimeout's 32-bit range" rule has a
+// single home.
+
+/** Injectable timer + clock seam so background scheduling is deterministic under test. */
+export interface SchedulerDeps {
+  setTimer: (fn: () => void, delayMs: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  /** Current wall-clock time in ms since epoch. */
+  now: () => number;
+}
+
+/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+function isTimerHandle(handle: unknown): handle is ReturnType<typeof setTimeout> {
+  return typeof handle === "number" || (typeof handle === "object" && handle !== null);
+}
+
+/** Default (live) scheduler seam, backed by the global timer functions. */
+export function defaultScheduler(): SchedulerDeps {
+  return {
+    setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimer: (h) => {
+      if (isTimerHandle(h)) globalThis.clearTimeout(h);
+    },
+    now: () => Date.now(),
+  };
+}

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

@@ -29,6 +29,7 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     publishMessage: async () => {},
     searchUserTasks: async () => [],
     completeUserTask: async () => {},
+    searchProcessInstances: async () => [],
     registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
     close: async () => {},
   };
@@ -42,6 +43,7 @@ const fakeEngine: EngineClient = {
   publishMessage: async () => {},
   searchUserTasks: async () => [],
   completeUserTask: async () => {},
+  searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -30,6 +30,7 @@ class MiniEngine implements EngineClient {
   }
   async searchUserTasks(): Promise<[]> { return []; }
   async completeUserTask(): Promise<void> {}
+  async searchProcessInstances(): Promise<[]> { return []; }
   async registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -9,18 +9,14 @@ import type { HttpRequest } from "../host.ts";
 import { json, normalizeRoutePath, type Route } from "../router.ts";
 import type { Trigger } from "../manifest.ts";
 import { nextCronFire, parseCron } from "./cron.ts";
+import { defaultScheduler, MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
+
+export type { SchedulerDeps };
 
 export interface TriggersHandle extends Mounted {
   routes: Route[];
 }
 
-/** Injectable timer + clock seam so cron scheduling is deterministic under test. */
-export interface SchedulerDeps {
-  setTimer: (fn: () => void, delayMs: number) => unknown;
-  clearTimer: (handle: unknown) => void;
-  /** Current wall-clock time in ms since epoch. */
-  now: () => number;
-}
 
 type Scope = { body: unknown; headers: Record<string, string>; query: Record<string, string> };
 
@@ -149,24 +145,6 @@ export async function runTriggerAction(
 
 const emptyScope: Scope = { body: {}, headers: {}, query: {} };
 
-/** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-
-/** Default (live) scheduler seam, backed by the global timer functions. */
-function defaultScheduler(): SchedulerDeps {
-  return {
-    setTimer: (fn, ms) => globalThis.setTimeout(fn, ms),
-    clearTimer: (h) => {
-      if (isTimerHandle(h)) globalThis.clearTimeout(h);
-    },
-    now: () => Date.now(),
-  };
-}
-
-function isTimerHandle(handle: unknown): handle is ReturnType<typeof setTimeout> {
-  return typeof handle === "number" || (typeof handle === "object" && handle !== null);
-}
-
 /** Mount webhook + cron triggers. Webhooks contribute HTTP routes; cron triggers arm
  *  background timers that fire their action on schedule. `stop()` clears every timer. */
 export function mountTriggers(

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

@@ -15,6 +15,7 @@ class MiniEngine implements EngineClient {
   async publishMessage(): Promise<void> {}
   async searchUserTasks(): Promise<[]> { return []; }
   async completeUserTask(): Promise<void> {}
+  async searchProcessInstances(): Promise<[]> { return []; }
   async close(): Promise<void> {}
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);

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

@@ -7,6 +7,7 @@ import { isRecord } from "../guards.ts";
 import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import { workerJobType, type Worker } from "../manifest.ts";
 import { type DecisionEvaluator, type LlmRuntime, runLlmJob } from "./llm.ts";
+import { runInJobContext } from "../execContext.ts";
 
 /** The subset of the engine SDK the LLM decision-rails need: evaluate a DMN decision,
  *  whose `output` comes back as a JSON string (the orchestration-cluster contract). */
@@ -142,7 +143,11 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
         env: (n) => app.env(n),
         evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
       };
-      const wrapped: JobHandler = (job) => runLlmJob(job.variables, binding, rt);
+      const wrapped: JobHandler = (job) =>
+        runInJobContext(
+          { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
+          () => runLlmJob(job.variables, binding, rt),
+        );
       const sub = await ctx.engine.registerWorker(jobType, wrapped, {
         workerName: `${ctx.manifest.id}:${jobType}`,
       });
@@ -159,7 +164,11 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
           `(expected handlers["${jobType}"], a named export, or a default function)`,
       );
     }
-    const wrapped: JobHandler = (job) => handler(job, app);
+    const wrapped: JobHandler = (job) =>
+      runInJobContext(
+        { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
+        () => handler(job, app),
+      );
     const sub = await ctx.engine.registerWorker(jobType, wrapped, {
       workerName: `${ctx.manifest.id}:${jobType}`,
     });

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

@@ -42,6 +42,9 @@ class FakeEngine implements EngineClient {
   async completeUserTask(key: string, variables?: Record<string, unknown>) {
     this.completedTasks.push({ key, variables });
   }
+  async searchProcessInstances() {
+    return [];
+  }
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);
     return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };

package/src/runtime/core/runtime.ts

@@ -12,10 +12,12 @@ import { makeRouter, type Route } from "./router.ts";
 import { deployModels } from "./modules/deploy.ts";
 import type { TemplateSource } from "./modules/templates.ts";
 import { provisionData, DataLayer } from "./modules/datasource.ts";
+import { installExecStore, type JobExecContext } from "./execContext.ts";
 import { mountWorkers } from "./modules/workers.ts";
 import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
 import { mountTriggers } from "./modules/triggers.ts";
+import { mountInstanceTracking } from "./modules/instance-tracking.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
 
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -52,6 +54,9 @@ export interface MountFlags {
   surfaces?: boolean;
   triggers?: boolean;
   security?: boolean;
+  /** The `instanceTracking` reconciler poll loop. Shares no HTTP surface; safe to disable
+   *  in hosts that only render surfaces (e.g. the console preview). */
+  instanceTracking?: boolean;
 }
 
 export interface CreateUrbanAppOptions {
@@ -104,9 +109,15 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     surfaces: opts.mount?.surfaces ?? true,
     triggers: opts.mount?.triggers ?? true,
     security: opts.mount?.security ?? true,
+    instanceTracking: opts.mount?.instanceTracking ?? true,
   };
   const ctx = { manifest, host, engine, root, templates: opts.templates };
 
+  // Install the ambient job-execution store once per process (idempotent) so worker dispatch can
+  // stamp write-provenance onto DataLayer inserts. Absent-safe: a host without `createAsyncStore`
+  // leaves provenance capture disabled.
+  installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+
   let data: DataLayer | undefined;
   let security: SecurityPolicy | undefined;
   let server: HttpServer | undefined;
@@ -204,6 +215,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           mounted.push(t);
           describe.triggers = t.describe?.();
         }
+        if (flags.instanceTracking && (manifest.instanceTracking?.length ?? 0) > 0) {
+          const it = mountInstanceTracking(ctx, api);
+          mounted.push(it);
+          describe.instanceTracking = it.describe?.();
+        }
         if (security) describe.security = security.describe();
         if (data) describe.data = data.describe();
 

package/src/runtime/core/validate.test.ts

@@ -111,3 +111,99 @@ test("validateManifest throws ManifestValidationError with issues", () => {
     return true;
   });
 });
+
+test("a well-formed instanceTracking binding has no issues", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        statusField: "status",
+        activeStatuses: ["planning"],
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.deepEqual(issues, []);
+});
+
+test("an instanceTracking binding missing table/keyField/onTerminated.set is flagged", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [{ onTerminated: { set: {} } }],
+  });
+  assert.ok(issues.some((i) => i.path === "instanceTracking[0].table"));
+  assert.ok(issues.some((i) => i.path === "instanceTracking[0].keyField"));
+  assert.ok(issues.some((i) => i.path === "instanceTracking[0].onTerminated.set"));
+});
+
+test("instanceTracking activeStatuses without statusField is flagged", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        activeStatuses: ["planning"],
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.ok(issues.some((i) => i.path === "instanceTracking[0].activeStatuses"));
+});
+
+test("instanceTracking activeStatuses with an empty-string statusField is flagged (silently polls every row otherwise)", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        statusField: "",
+        activeStatuses: ["planning"],
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.ok(issues.some((i) => i.path === "instanceTracking[0].activeStatuses"));
+});
+
+test("instanceTracking pollMs that is non-positive/NaN/non-number is flagged (would hot-loop the poll timer)", () => {
+  for (const badPollMs of [0, -1, Number.NaN, Number.POSITIVE_INFINITY, "5000"]) {
+    const issues = collectManifestIssues({
+      ...valid,
+      instanceTracking: [
+        {
+          table: "plans",
+          keyField: "process_key",
+          statusField: "status",
+          activeStatuses: ["planning"],
+          onTerminated: { set: { status: "abandoned" } },
+          pollMs: badPollMs,
+        },
+      ],
+    });
+    assert.ok(
+      issues.some((i) => i.path === "instanceTracking[0].pollMs"),
+      `expected pollMs=${String(badPollMs)} to be flagged`,
+    );
+  }
+});
+
+test("instanceTracking with a valid positive pollMs has no pollMs issue", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        statusField: "status",
+        activeStatuses: ["planning"],
+        onTerminated: { set: { status: "abandoned" } },
+        pollMs: 5000,
+      },
+    ],
+  });
+  assert.deepEqual(issues, []);
+});

package/src/runtime/core/validate.ts

@@ -150,6 +150,45 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
     });
   }
 
+  // instanceTracking: each binding must name the table + key column it tracks and a
+  // non-empty `onTerminated.set` patch — a reconciler with nothing to write is inert
+  // and almost certainly a mistake. `activeStatuses` without `statusField` is incoherent
+  // (no column to read the statuses from), so the runtime would silently poll every row.
+  const tracking = Array.isArray(obj.instanceTracking) ? obj.instanceTracking : undefined;
+  if (tracking) {
+    tracking.forEach((t, i) => {
+      const b = isRecord(t) ? t : undefined;
+      if (typeof b?.table !== "string" || b.table.length === 0) {
+        issues.push({ path: `instanceTracking[${i}].table`, message: "missing table" });
+      }
+      if (typeof b?.keyField !== "string" || b.keyField.length === 0) {
+        issues.push({ path: `instanceTracking[${i}].keyField`, message: "missing keyField" });
+      }
+      const onTerminated = isRecord(b?.onTerminated) ? b.onTerminated : undefined;
+      const set = isRecord(onTerminated?.set) ? onTerminated.set : undefined;
+      if (!set || Object.keys(set).length === 0) {
+        issues.push({
+          path: `instanceTracking[${i}].onTerminated.set`,
+          message: "missing onTerminated.set patch (a non-empty column → value map)",
+        });
+      }
+      if (Array.isArray(b?.activeStatuses) && (typeof b?.statusField !== "string" || b.statusField.length === 0)) {
+        issues.push({
+          path: `instanceTracking[${i}].activeStatuses`,
+          message: "activeStatuses requires statusField",
+        });
+      }
+      // `pollMs`, when set, schedules a self-rescheduling timer; a non-number/NaN/non-positive
+      // value would become a 0-delay hot loop at runtime, so reject it at author time.
+      if (b?.pollMs !== undefined && (typeof b.pollMs !== "number" || !Number.isFinite(b.pollMs) || b.pollMs <= 0)) {
+        issues.push({
+          path: `instanceTracking[${i}].pollMs`,
+          message: "pollMs must be a finite positive number of milliseconds",
+        });
+      }
+    });
+  }
+
   return issues;
 }
 

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

@@ -2,6 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
   createNanoSdkEngineClient,
+  normalizeProcessInstanceState,
   requireProcessInstanceKey,
   SdkEngineClient,
   type NanoSdkActivatedJob,
@@ -66,6 +67,10 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("searchUserTasks");
       return { items: [] };
     },
+    async searchProcessInstances() {
+      calls.push("searchProcessInstances");
+      return { items: [] };
+    },
     async completeUserTask() {
       calls.push("completeUserTask");
       return {};
@@ -202,6 +207,74 @@ test("completeUserTask routes through the SDK", async () => {
   assert.deepEqual(seen, { userTaskKey: "utk", variables: { done: true } });
 });
 
+test("searchProcessInstances filters by keys ($in) + state with a matching page cap", async () => {
+  let seenInput: unknown;
+  let seenConsistency: unknown;
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input, c) => {
+      seenInput = input;
+      seenConsistency = c;
+      return {
+        items: [
+          { processInstanceKey: 7, state: "TERMINATED" },
+          { processInstanceKey: "8", state: "ACTIVE" },
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchProcessInstances({
+    processInstanceKeys: ["7", "8", ""], // empty key dropped from the $in
+    state: "TERMINATED",
+  });
+  assert.deepEqual(seenInput, {
+    filter: { state: "TERMINATED", processInstanceKey: { $in: ["7", "8"] } },
+    page: { limit: 2 },
+  });
+  assert.deepEqual(seenConsistency, { consistency: { waitUpToMs: 0 } });
+  assert.deepEqual(out, [
+    { processInstanceKey: "7", state: "TERMINATED" },
+    { processInstanceKey: "8", state: "ACTIVE" },
+  ]);
+});
+
+test("searchProcessInstances with no keys sends no key filter and no page cap", async () => {
+  let seenInput: unknown;
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input) => {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchProcessInstances();
+  assert.deepEqual(seenInput, { filter: {} });
+});
+
+test("searchProcessInstances skips keyless and unrecognized-state rows", async () => {
+  const client = fakeSdkClient({
+    searchProcessInstances: async () => ({
+      items: [
+        { processInstanceKey: "", state: "TERMINATED" }, // keyless → skipped
+        { processInstanceKey: 9, state: "SUSPENDED" }, // unknown state → skipped
+        { processInstanceKey: 10, state: "completed" }, // case-insensitive → mapped
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchProcessInstances();
+  assert.deepEqual(out, [{ processInstanceKey: "10", state: "COMPLETED" }]);
+});
+
+test("normalizeProcessInstanceState maps the terminal set and rejects others", () => {
+  assert.equal(normalizeProcessInstanceState("ACTIVE"), "ACTIVE");
+  assert.equal(normalizeProcessInstanceState("completed"), "COMPLETED");
+  assert.equal(normalizeProcessInstanceState("Terminated"), "TERMINATED");
+  assert.equal(normalizeProcessInstanceState("SUSPENDED"), undefined);
+  assert.equal(normalizeProcessInstanceState(42), undefined);
+  assert.equal(normalizeProcessInstanceState(undefined), undefined);
+});
+
 test("registerWorker creates a worker the SDK auto-starts, and dispatches + completes", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);