@nanobpm/urban 0.27.0 → 0.29.0

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);

package/src/runtime/engine/nanosdk.ts

@@ -15,6 +15,8 @@ import type {
   EngineClient,
   EngineJob,
   JobHandler,
+  ProcessInstanceSnapshot,
+  ProcessInstanceState,
   WorkerSubscription,
 } from "../core/host.ts";
 import { isBpmnError } from "../core/host.ts";
@@ -30,6 +32,26 @@ export function requireProcessInstanceKey(key: string | number | null | undefine
   return String(key);
 }
 
+/** Map the engine's process-instance `state` onto the transport-agnostic
+ *  {@link ProcessInstanceState} union, or `undefined` for an unrecognized value
+ *  (which the caller skips rather than mis-reconciling). Case-insensitive so a
+ *  future casing tweak on the engine side doesn't silently drop instances. */
+export function normalizeProcessInstanceState(
+  raw: unknown,
+): ProcessInstanceState | undefined {
+  if (typeof raw !== "string") return undefined;
+  switch (raw.toUpperCase()) {
+    case "ACTIVE":
+      return "ACTIVE";
+    case "COMPLETED":
+      return "COMPLETED";
+    case "TERMINATED":
+      return "TERMINATED";
+    default:
+      return undefined;
+  }
+}
+
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -103,6 +125,11 @@ export interface NanoSdkClient {
     input: { userTaskKey: string; variables?: Record<string, unknown> },
     options?: unknown,
   ): Promise<unknown>;
+  searchProcessInstances(
+    input: { filter?: Record<string, unknown>; page?: Record<string, unknown> },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
   createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
   /** Stop every worker created on this client. Used on teardown to also drain a
    * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
@@ -213,6 +240,42 @@ export class SdkEngineClient implements EngineClient {
     await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
   }
 
+  async searchProcessInstances(filter?: {
+    processInstanceKeys?: string[];
+    state?: ProcessInstanceState;
+  }): Promise<ProcessInstanceSnapshot[]> {
+    const f: Record<string, unknown> = {};
+    if (filter?.state) f.state = filter.state;
+    const keys = filter?.processInstanceKeys?.filter((k) => k != null && k !== "");
+    if (keys && keys.length > 0) f.processInstanceKey = { $in: keys };
+    // A process-instance search is an eventually consistent read; ask for zero-wait
+    // consistency so it reflects what is currently visible without blocking. Cap the page
+    // to the number of keys asked for (each key matches at most one instance), so a bounded
+    // reconcile query never silently truncates on the API's default page size.
+    const page = keys && keys.length > 0 ? { limit: keys.length } : undefined;
+    const body = await this.client.searchProcessInstances(
+      { filter: f, ...(page ? { page } : {}) },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+    return items.flatMap((it) => {
+      const key = it.processInstanceKey;
+      if (key == null || key === "") {
+        this.log("warn", "skipping process instance with no key in engine response");
+        return [];
+      }
+      const state = normalizeProcessInstanceState(it.state);
+      if (!state) {
+        this.log("warn", "skipping process instance with unrecognized state", {
+          processInstanceKey: String(key),
+          state: String(it.state),
+        });
+        return [];
+      }
+      return [{ processInstanceKey: String(key), state }];
+    });
+  }
+
   async registerWorker(
     jobType: string,
     handler: JobHandler,