@nanobpm/urban 0.88.1 → 0.90.0

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

@@ -97,6 +97,18 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("searchIncidents");
       return { items: [] };
     },
+    async searchVariables() {
+      calls.push("searchVariables");
+      return { items: [] };
+    },
+    async searchJobs() {
+      calls.push("searchJobs");
+      return { items: [] };
+    },
+    async getProcessDefinitionXml() {
+      calls.push("getProcessDefinitionXml");
+      return "";
+    },
     async resolveIncident(input) {
       calls.push("resolveIncident");
       return { ...input };
@@ -303,6 +315,72 @@ test("searchUserTasks surfaces the resolved form linkage", async () => {
   ]);
 });
 
+test("searchUserTasks normalizes the process-instance key selectors and drops blank ones", async () => {
+  // Guards the selector-normalization defect class: a padded selector (`" 42 "`) must reach the
+  // engine trimmed (so it matches the normalized keys the adapter surfaces), a blank/whitespace-only
+  // selector must be *dropped* (not forwarded as a present filter that silently matches nothing),
+  // and unrelated selectors must pass through untouched — mirroring `searchProcessInstances`.
+  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({
+    processInstanceKey: " 42 ", // padded → trimmed to "42"
+    parentProcessInstanceKey: "   ", // whitespace-only → dropped
+    rootProcessInstanceKey: "", // blank → dropped
+    assignee: "alice", // unrelated selector passes through unchanged
+  });
+  const filter = input?.filter ?? {};
+  assert.equal(filter.processInstanceKey, "42", "padded key selector is trimmed");
+  assert.equal("parentProcessInstanceKey" in filter, false, "whitespace-only parent selector is dropped");
+  assert.equal("rootProcessInstanceKey" in filter, false, "blank root selector is dropped");
+  assert.equal(filter.assignee, "alice", "unrelated selectors pass through unchanged");
+});
+
+test("searchUserTasks surfaces the process-instance linkage keys and drops blank ones", async () => {
+  // Guards the linkage-output defect class: the three linkage keys the engine reports on a task
+  // (processInstanceKey/parentProcessInstanceKey/rootProcessInstanceKey) must be surfaced on the
+  // returned `UserTaskSummary`, normalized through the same presence rule — a padded value trimmed,
+  // a blank/whitespace-only value omitted rather than surfaced as an empty string.
+  const client = fakeSdkClient({
+    searchUserTasks: async () => ({
+      items: [
+        {
+          userTaskKey: 1,
+          elementId: "a",
+          processInstanceKey: 10,
+          parentProcessInstanceKey: 20,
+          rootProcessInstanceKey: 30,
+        },
+        {
+          userTaskKey: 2,
+          elementId: "b",
+          processInstanceKey: " 11 ", // padded → trimmed
+          parentProcessInstanceKey: "  ", // whitespace-only → omitted
+          rootProcessInstanceKey: "", // blank → omitted
+        },
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const tasks = await engine.searchUserTasks();
+  assert.deepEqual(tasks, [
+    {
+      userTaskKey: "1",
+      elementId: "a",
+      variables: undefined,
+      processInstanceKey: "10",
+      parentProcessInstanceKey: "20",
+      rootProcessInstanceKey: "30",
+    },
+    { userTaskKey: "2", elementId: "b", variables: undefined, processInstanceKey: "11" },
+  ]);
+});
+
 test("getForm resolves by formKey and parses the serialized schema", async () => {
   let seen: unknown;
   const schema = { type: "default", schemaVersion: 18, components: [{ type: "textfield", key: "name" }] };
@@ -474,6 +552,64 @@ test("searchProcessInstances skips keyless and unrecognized-state rows", async (
   assert.deepEqual(out, [{ processInstanceKey: "10", state: "COMPLETED" }]);
 });
 
+test("searchProcessInstances normalizes the parent/root key selectors and drops blank ones", async () => {
+  // Guards the request-mapping defect class for the reduced path's parent/root selectors: a padded
+  // selector must be trimmed, a blank/whitespace-only selector must be dropped rather than sent as
+  // an empty filter that matches nothing — mirroring `searchUserTasks` (No Drift Surfaces).
+  let seenInput: { filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input) => {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchProcessInstances({
+    parentProcessInstanceKey: " 42 ", // padded → trimmed to "42"
+    rootProcessInstanceKey: "   ", // whitespace-only → dropped
+  });
+  const filter = seenInput?.filter ?? {};
+  assert.equal(filter.parentProcessInstanceKey, "42", "padded parent selector is trimmed");
+  assert.equal("rootProcessInstanceKey" in filter, false, "whitespace-only root selector is dropped");
+  // A selector-only search carries no key `$in` and no page cap.
+  assert.deepEqual(seenInput, { filter: { parentProcessInstanceKey: "42" } });
+});
+
+test("searchProcessInstances surfaces the parent/root linkage keys and drops blank ones", async () => {
+  // Guards the linkage-output defect class: the parent/root keys the engine reports on an instance
+  // must be surfaced on the returned `ProcessInstanceSnapshot`, normalized through the same presence
+  // rule — a padded value trimmed, a blank/whitespace-only value omitted rather than an empty string.
+  const client = fakeSdkClient({
+    searchProcessInstances: async () => ({
+      items: [
+        {
+          processInstanceKey: 10,
+          state: "ACTIVE",
+          parentProcessInstanceKey: 20,
+          rootProcessInstanceKey: 30,
+        },
+        {
+          processInstanceKey: " 11 ", // padded → trimmed
+          state: "COMPLETED",
+          parentProcessInstanceKey: "  ", // whitespace-only → omitted
+          rootProcessInstanceKey: "", // blank → omitted
+        },
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchProcessInstances();
+  assert.deepEqual(out, [
+    {
+      processInstanceKey: "10",
+      state: "ACTIVE",
+      parentProcessInstanceKey: "20",
+      rootProcessInstanceKey: "30",
+    },
+    { processInstanceKey: "11", state: "COMPLETED" },
+  ]);
+});
+
 test("normalizeProcessInstanceState maps the terminal set and rejects others", () => {
   assert.equal(normalizeProcessInstanceState("ACTIVE"), "ACTIVE");
   assert.equal(normalizeProcessInstanceState("completed"), "COMPLETED");

package/src/runtime/engine/nanosdk.ts

@@ -24,12 +24,16 @@ import type {
   IncidentFilter,
   IncidentState,
   IncidentSummary,
+  JobFilter,
   JobHandler,
+  JobSummary,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
   UserTaskState,
   UserTaskSummary,
   UserTaskFilter,
+  VariableFilter,
+  VariableSummary,
   WorkerSubscription,
 } from "../core/host.ts";
 import { assertDeployedWaitStateType, isBpmnError } from "../core/host.ts";
@@ -360,6 +364,99 @@ export function mapIncidentRow(
   };
 }
 
+/** Map one engine variable row onto a {@link VariableSummary}, or `undefined` when the row is
+ *  malformed (missing the `variableKey`, owning `processInstanceKey`, or `name` — the identity a
+ *  caller needs). `value` is the engine's serialized JSON value (a string); a non-string value is
+ *  JSON-encoded so the field is always a string a caller can `JSON.parse`. `scopeKey` falls back to
+ *  the process-instance key for a process-level variable that omits it. `isTruncated` is the
+ *  engine's large-value-clipped flag, defaulting to `false`. The single source of truth
+ *  `searchVariables` extracts through. */
+export function mapVariableRow(
+  row: Record<string, unknown>,
+  log: Log,
+): VariableSummary | undefined {
+  const variableKey = presentEngineKey(row.variableKey);
+  if (variableKey === undefined) {
+    log("warn", "skipping variable with no variableKey in engine response");
+    return undefined;
+  }
+  const processInstanceKey = presentEngineKey(row.processInstanceKey);
+  if (processInstanceKey === undefined) {
+    log("warn", "skipping variable with no processInstanceKey in engine response", {
+      variableKey,
+    });
+    return undefined;
+  }
+  const name = presentText(row.name);
+  if (name === undefined) {
+    log("warn", "skipping variable with no name in engine response", { variableKey });
+    return undefined;
+  }
+  // A process-level variable is scoped to the process instance itself; the engine may omit
+  // `scopeKey` for it, so fall back to the process-instance key rather than dropping the row.
+  const scopeKey = presentEngineKey(row.scopeKey) ?? processInstanceKey;
+  // The engine serializes `value` as a JSON string. Keep a string as-is; encode any other type
+  // (an object/array/number a permissive engine might inline) so the field is always a string the
+  // caller can `JSON.parse`.
+  const value = typeof row.value === "string" ? row.value : JSON.stringify(row.value ?? null);
+  return {
+    variableKey,
+    name,
+    value,
+    scopeKey,
+    processInstanceKey,
+    isTruncated: row.isTruncated === true,
+  };
+}
+
+/** Map one engine job row onto a {@link JobSummary}, or `undefined` when the row is malformed
+ *  (missing the `jobKey`, `type`, or owning `processInstanceKey`). `worker`/`retries`/`elementId`/
+ *  `deadline` are best-effort diagnostics: present when the engine reports them, omitted otherwise
+ *  — an unset `worker` is the "queued, not leased" signal, so it must be absent rather than `""`.
+ *  `state` is passed through as a bare string (the engine's job-state enum is broad). The single
+ *  source of truth `searchJobs` extracts through. */
+export function mapJobRow(
+  row: Record<string, unknown>,
+  log: Log,
+): JobSummary | undefined {
+  const jobKey = presentEngineKey(row.jobKey);
+  if (jobKey === undefined) {
+    log("warn", "skipping job with no jobKey in engine response");
+    return undefined;
+  }
+  const type = presentText(row.type);
+  if (type === undefined) {
+    log("warn", "skipping job with no type in engine response", { jobKey });
+    return undefined;
+  }
+  const processInstanceKey = presentEngineKey(row.processInstanceKey);
+  if (processInstanceKey === undefined) {
+    log("warn", "skipping job with no processInstanceKey in engine response", { jobKey });
+    return undefined;
+  }
+  const state = presentText(row.state);
+  if (state === undefined) {
+    log("warn", "skipping job with no state in engine response", { jobKey });
+    return undefined;
+  }
+  const worker = presentText(row.worker);
+  const retries = typeof row.retries === "number" && Number.isFinite(row.retries)
+    ? row.retries
+    : undefined;
+  const elementId = presentText(row.elementId);
+  const deadline = presentText(row.deadline);
+  return {
+    jobKey,
+    type,
+    state,
+    processInstanceKey,
+    ...(worker ? { worker } : {}),
+    ...(retries !== undefined ? { retries } : {}),
+    ...(elementId ? { elementId } : {}),
+    ...(deadline ? { deadline } : {}),
+  };
+}
+
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -463,6 +560,21 @@ export interface NanoSdkClient {
     consistency?: unknown,
     options?: unknown,
   ): Promise<Record<string, unknown>>;
+  searchVariables(
+    input: { filter?: Record<string, unknown>; page?: Record<string, unknown> },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  searchJobs(
+    input: { filter?: Record<string, unknown>; page?: Record<string, unknown> },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  getProcessDefinitionXml(
+    input: { processDefinitionKey: string },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<unknown>;
   resolveIncident(
     input: { incidentKey: string },
     options?: unknown,
@@ -565,8 +677,19 @@ export class SdkEngineClient implements EngineClient {
   }): Promise<UserTaskSummary[]> {
     // User tasks are an eventually consistent read; ask for zero-wait consistency so
     // the search reflects what is currently visible without blocking.
+    // Normalize the process-instance key selectors through the shared presence rule so a
+    // blank/whitespace-only selector is *dropped* rather than forwarded as a present filter that
+    // silently matches nothing, and a padded key (`" 123 "`) matches the normalized keys we
+    // surface — mirroring `WasmEngineClient` (which normalizes via `presentKey`) and
+    // `searchProcessInstances` below (No Drift Surfaces).
+    const f: Record<string, unknown> = { ...(filter ?? {}) };
+    for (const sel of ["processInstanceKey", "parentProcessInstanceKey", "rootProcessInstanceKey"] as const) {
+      const normalized = presentEngineKey(filter?.[sel]);
+      if (normalized) f[sel] = normalized;
+      else delete f[sel];
+    }
     const body = await this.client.searchUserTasks(
-      { filter: { ...(filter ?? {}) } },
+      { filter: f },
       { consistency: { waitUpToMs: 0 } },
     );
     const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
@@ -579,10 +702,16 @@ export class SdkEngineClient implements EngineClient {
       // 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;
       // no `resolveFormKeyByFormId` resolver is passed because the gateway already resolved it.
+      const processInstanceKey = presentEngineKey(it.processInstanceKey);
+      const parentProcessInstanceKey = presentEngineKey(it.parentProcessInstanceKey);
+      const rootProcessInstanceKey = presentEngineKey(it.rootProcessInstanceKey);
       return [{
         userTaskKey: String(userTaskKey),
         elementId: typeof it.elementId === "string" ? it.elementId : undefined,
         variables: isRecord(it.variables) ? it.variables : undefined,
+        ...(processInstanceKey ? { processInstanceKey } : {}),
+        ...(parentProcessInstanceKey ? { parentProcessInstanceKey } : {}),
+        ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
         ...pickFormLinkage(it),
       }];
     });
@@ -651,11 +780,26 @@ export class SdkEngineClient implements EngineClient {
   async searchProcessInstances(filter?: {
     processInstanceKeys?: string[];
     state?: ProcessInstanceState;
+    parentProcessInstanceKey?: string;
+    rootProcessInstanceKey?: string;
   }): Promise<ProcessInstanceSnapshot[]> {
     const f: Record<string, unknown> = {};
     if (filter?.state) f.state = filter.state;
-    const keys = filter?.processInstanceKeys?.filter((k) => k != null && k !== "");
+    // Normalize each requested key through the shared presence rule (drop blank/whitespace-only
+    // entries, trim padded ones like `" 123 "`) so the `$in` filter carries only present keys that
+    // match the normalized keys we surface — mirroring `WasmEngineClient` and the selector
+    // handling above (No Drift Surfaces).
+    const keys = filter?.processInstanceKeys
+      ?.map((k) => presentEngineKey(k))
+      .filter((k): k is string => k !== undefined);
     if (keys && keys.length > 0) f.processInstanceKey = { $in: keys };
+    // Parent/root selectors let the reduced path query a subject's native descendants
+    // server-side. Normalize each through the shared presence rule so a blank selector is
+    // dropped rather than sent as an empty filter that would match nothing.
+    const parentProcessInstanceKey = presentEngineKey(filter?.parentProcessInstanceKey);
+    if (parentProcessInstanceKey) f.parentProcessInstanceKey = parentProcessInstanceKey;
+    const rootProcessInstanceKey = presentEngineKey(filter?.rootProcessInstanceKey);
+    if (rootProcessInstanceKey) f.rootProcessInstanceKey = rootProcessInstanceKey;
     // 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
@@ -667,20 +811,33 @@ export class SdkEngineClient implements EngineClient {
     );
     const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
     return items.flatMap((it) => {
-      const key = it.processInstanceKey;
-      if (key == null || key === "") {
+      // Normalize the surfaced primary key through the shared presence rule (trim padded,
+      // drop blank/whitespace-only) so it matches the normalized parent/root linkage keys
+      // and the `searchUserTasks` mapping — the surfaced process-instance key must not drift
+      // between the two reduced-path searches (No Drift Surfaces).
+      const processInstanceKey = presentEngineKey(it.processInstanceKey);
+      if (!processInstanceKey) {
         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),
+          processInstanceKey,
           state: String(it.state),
         });
         return [];
       }
-      return [{ processInstanceKey: String(key), state }];
+      const processDefinitionKey = presentEngineKey(it.processDefinitionKey);
+      const parentProcessInstanceKey = presentEngineKey(it.parentProcessInstanceKey);
+      const rootProcessInstanceKey = presentEngineKey(it.rootProcessInstanceKey);
+      return [{
+        processInstanceKey,
+        state,
+        ...(processDefinitionKey ? { processDefinitionKey } : {}),
+        ...(parentProcessInstanceKey ? { parentProcessInstanceKey } : {}),
+        ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
+      }];
     });
   }
 
@@ -784,6 +941,82 @@ export class SdkEngineClient implements EngineClient {
     });
   }
 
+  async searchVariables(filter?: VariableFilter): Promise<VariableSummary[]> {
+    // Same shape as `searchIncidents`: build the engine filter from the transport-agnostic
+    // selectors, read at zero-wait consistency (a variable search is eventually consistent), and
+    // map each row through the single `mapVariableRow` gate, dropping malformed rows.
+    const f: Record<string, unknown> = {};
+    const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
+    if (processInstanceKey) f.processInstanceKey = processInstanceKey;
+    const scopeKey = presentEngineKey(filter?.scopeKey);
+    if (scopeKey) f.scopeKey = scopeKey;
+    const name = filter?.name?.trim();
+    if (name) f.name = name;
+    const body = await this.client.searchVariables(
+      { filter: f },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+    return items.flatMap((it) => {
+      const mapped = mapVariableRow(it, this.log);
+      return mapped ? [mapped] : [];
+    });
+  }
+
+  async searchJobs(filter?: JobFilter): Promise<JobSummary[]> {
+    // Same shape as `searchIncidents`: build the engine filter from the transport-agnostic
+    // selectors, read at zero-wait consistency (a job search is eventually consistent), and map
+    // each row through the single `mapJobRow` gate, dropping malformed rows.
+    const f: Record<string, unknown> = {};
+    const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
+    if (processInstanceKey) f.processInstanceKey = processInstanceKey;
+    const state = filter?.state?.trim();
+    if (state) f.state = state;
+    const type = filter?.type?.trim();
+    if (type) f.type = type;
+    const elementId = filter?.elementId?.trim();
+    if (elementId) f.elementId = elementId;
+    const worker = filter?.worker?.trim();
+    if (worker) f.worker = worker;
+    const body = await this.client.searchJobs(
+      { filter: f },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+    return items.flatMap((it) => {
+      const mapped = mapJobRow(it, this.log);
+      return mapped ? [mapped] : [];
+    });
+  }
+
+  async getProcessDefinitionXml(
+    processDefinitionKey: string,
+  ): Promise<string | null> {
+    // A blank key can never address a definition — short-circuit to null rather than issue a
+    // `GET /v2/process-definitions//xml` with an empty segment. Normalize a padded-but-valid key so
+    // `" 5 "` addresses the same definition, mirroring `getElementInstance`.
+    const key = presentEngineKey(processDefinitionKey);
+    if (key === undefined) return null;
+    let xml: unknown;
+    try {
+      xml = await this.client.getProcessDefinitionXml(
+        { processDefinitionKey: key },
+        { consistency: { waitUpToMs: 0 } },
+      );
+    } catch (err) {
+      // A 404 (no such definition) is an expected "not found", not a fault — mirror `getForm`/
+      // `getElementInstance`, which treat a failed fetch as absence (null) rather than propagating.
+      this.log("warn", "getProcessDefinitionXml: engine fetch failed", {
+        processDefinitionKey: key,
+        err: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+    // The endpoint returns the raw BPMN XML as a string (204 → empty). Treat a blank/absent body
+    // as "no XML" (null) so a caller distinguishes "have it" from "don't".
+    return typeof xml === "string" && xml.trim() !== "" ? xml : null;
+  }
+
   async resolveIncident(input: { incidentKey: string }): Promise<void> {
     await this.client.resolveIncident({
       incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),

package/src/runtime/index.ts

@@ -100,13 +100,17 @@ export type {
   EngineIncidentState,
   IncidentFilter,
   IncidentSummary,
+  JobFilter,
   JobHandler,
+  JobSummary,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
   SqliteDb,
   UserTaskState,
   UserTaskSummary,
   UserTaskFilter,
+  VariableFilter,
+  VariableSummary,
   WatchHandle,
   WorkerSubscription,
 } from "./core/host.ts";