@nanobpm/urban 0.82.1 → 0.84.0

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

@@ -33,6 +33,13 @@ const engine: EngineClient = {
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
+  searchElementInstances: async () => [],
+  searchElementInstanceWaitStates: async () => [],
+  getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -18,6 +18,13 @@ const fakeEngine: EngineClient = {
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
+  searchElementInstances: async () => [],
+  searchElementInstanceWaitStates: async () => [],
+  getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -31,6 +31,13 @@ const engine: EngineClient = {
   openUserTasks: async () => [],
   getForm: async () => null,
   searchProcessInstances: async () => [],
+  searchElementInstances: async () => [],
+  searchElementInstanceWaitStates: async () => [],
+  getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   completeUserTask: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},

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

@@ -85,6 +85,13 @@ function cancelEngine(opts: {
     openUserTasks: notUsed("openUserTasks"),
     getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
+    searchElementInstances: notUsed("searchElementInstances"),
+    searchElementInstanceWaitStates: notUsed("searchElementInstanceWaitStates"),
+    getElementInstance: notUsed("getElementInstance"),
+    searchIncidents: notUsed("searchIncidents"),
+    resolveIncident: notUsed("resolveIncident"),
+    updateJobRetries: notUsed("updateJobRetries"),
+    setVariables: notUsed("setVariables"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
   };

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

@@ -21,6 +21,13 @@ class MiniEngine implements EngineClient {
   async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
+  async searchElementInstances(): Promise<[]> { return []; }
+  async searchElementInstanceWaitStates(): Promise<[]> { return []; }
+  async getElementInstance(): Promise<null> { return null; }
+  async searchIncidents(): Promise<never[]> { return []; }
+  async resolveIncident(): Promise<void> {}
+  async updateJobRetries(): Promise<void> {}
+  async setVariables(): Promise<void> {}
   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/modules/datasource.migrations.test.ts

@@ -20,6 +20,13 @@ const noEngine: EngineClient = {
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
+  searchElementInstances: async () => [],
+  searchElementInstanceWaitStates: async () => [],
+  getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -90,6 +90,13 @@ function fakeEngine(
     searchUserTasks: notUsed("searchUserTasks"),
     getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
+    searchElementInstances: notUsed("searchElementInstances"),
+    searchElementInstanceWaitStates: notUsed("searchElementInstanceWaitStates"),
+    getElementInstance: notUsed("getElementInstance"),
+    searchIncidents: notUsed("searchIncidents"),
+    resolveIncident: notUsed("resolveIncident"),
+    updateJobRetries: notUsed("updateJobRetries"),
+    setVariables: notUsed("setVariables"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
   };

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

@@ -48,6 +48,13 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
     async getForm() { return null; },
     async completeUserTask() {},
     async searchProcessInstances() { return []; },
+    async searchElementInstances() { return []; },
+    async searchElementInstanceWaitStates() { return []; },
+    async getElementInstance() { return null; },
+    async searchIncidents() { return []; },
+    async resolveIncident() {},
+    async updateJobRetries() {},
+    async setVariables() {},
     async registerWorker(jobType) { return { jobType, unsubscribe: async () => {} }; },
     async close() {},
   };

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

@@ -34,6 +34,13 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     getForm: async () => null,
     completeUserTask: async () => {},
     searchProcessInstances: async () => [],
+    searchElementInstances: async () => [],
+    searchElementInstanceWaitStates: async () => [],
+    getElementInstance: async () => null,
+    searchIncidents: async () => [],
+    resolveIncident: async () => {},
+    updateJobRetries: async () => {},
+    setVariables: async () => {},
     registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
     close: async () => {},
   };
@@ -50,6 +57,13 @@ const fakeEngine: EngineClient = {
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
+  searchElementInstances: async () => [],
+  searchElementInstanceWaitStates: async () => [],
+  getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -35,6 +35,13 @@ class MiniEngine implements EngineClient {
   async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
+  async searchElementInstances(): Promise<[]> { return []; }
+  async searchElementInstanceWaitStates(): Promise<[]> { return []; }
+  async getElementInstance(): Promise<null> { return null; }
+  async searchIncidents(): Promise<never[]> { return []; }
+  async resolveIncident(): Promise<void> {}
+  async updateJobRetries(): Promise<void> {}
+  async setVariables(): Promise<void> {}
   async registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -32,6 +32,13 @@ class MiniEngine implements EngineClient {
   async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
+  async searchElementInstances(): Promise<[]> { return []; }
+  async searchElementInstanceWaitStates(): Promise<[]> { return []; }
+  async getElementInstance(): Promise<null> { return null; }
+  async searchIncidents(): Promise<never[]> { return []; }
+  async resolveIncident(): Promise<void> {}
+  async updateJobRetries(): Promise<void> {}
+  async setVariables(): Promise<void> {}
   async close(): Promise<void> {}
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);

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

@@ -32,6 +32,21 @@ class NoopEngine implements EngineClient {
   async searchProcessInstances() {
     return [];
   }
+  async searchElementInstances() {
+    return [];
+  }
+  async searchElementInstanceWaitStates() {
+    return [];
+  }
+  async getElementInstance() {
+    return null;
+  }
+  async searchIncidents() {
+    return [];
+  }
+  async resolveIncident() {}
+  async updateJobRetries() {}
+  async setVariables() {}
   async registerWorker(jobType: string): Promise<WorkerSubscription> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -53,6 +53,21 @@ class FakeEngine implements EngineClient {
   async searchProcessInstances() {
     return [];
   }
+  async searchElementInstances() {
+    return [];
+  }
+  async searchElementInstanceWaitStates() {
+    return [];
+  }
+  async getElementInstance() {
+    return null;
+  }
+  async searchIncidents() {
+    return [];
+  }
+  async resolveIncident() {}
+  async updateJobRetries() {}
+  async setVariables() {}
   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/engine/nanosdk.test.ts

@@ -3,6 +3,8 @@ import assert from "node:assert/strict";
 import {
   createNanoSdkEngineClient,
   normalizeProcessInstanceState,
+  normalizeElementInstanceState,
+  normalizeWaitStateType,
   requireProcessInstanceKey,
   SdkEngineClient,
   type NanoSdkActivatedJob,
@@ -74,6 +76,34 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("searchProcessInstances");
       return { items: [] };
     },
+    async searchElementInstances() {
+      calls.push("searchElementInstances");
+      return { items: [] };
+    },
+    async searchElementInstanceWaitStates() {
+      calls.push("searchElementInstanceWaitStates");
+      return { items: [] };
+    },
+    async getElementInstance() {
+      calls.push("getElementInstance");
+      return {};
+    },
+    async searchIncidents() {
+      calls.push("searchIncidents");
+      return { items: [] };
+    },
+    async resolveIncident(input) {
+      calls.push("resolveIncident");
+      return { ...input };
+    },
+    async updateJob(input) {
+      calls.push("updateJob");
+      return { ...input };
+    },
+    async createElementInstanceVariables(input) {
+      calls.push("createElementInstanceVariables");
+      return { ...input };
+    },
     async completeUserTask() {
       calls.push("completeUserTask");
       return {};
@@ -448,6 +478,360 @@ test("normalizeProcessInstanceState maps the terminal set and rejects others", (
   assert.equal(normalizeProcessInstanceState(undefined), undefined);
 });
 
+test("normalizeElementInstanceState maps the recognized states (case-insensitive) and rejects others", () => {
+  assert.equal(normalizeElementInstanceState("ACTIVE"), "ACTIVE");
+  assert.equal(normalizeElementInstanceState("completed"), "COMPLETED");
+  assert.equal(normalizeElementInstanceState("Terminated"), "TERMINATED");
+  assert.equal(normalizeElementInstanceState("SKIPPED"), undefined);
+  assert.equal(normalizeElementInstanceState(7), undefined);
+  assert.equal(normalizeElementInstanceState(undefined), undefined);
+});
+
+test("normalizeWaitStateType maps the wait-state kinds (case-insensitive) and rejects others", () => {
+  assert.equal(normalizeWaitStateType("JOB"), "JOB");
+  assert.equal(normalizeWaitStateType("message"), "MESSAGE");
+  assert.equal(normalizeWaitStateType("User_Task"), "USER_TASK");
+  assert.equal(normalizeWaitStateType("TIMER"), "TIMER");
+  assert.equal(normalizeWaitStateType("signal"), "SIGNAL");
+  assert.equal(normalizeWaitStateType("CONDITION"), "CONDITION");
+  assert.equal(normalizeWaitStateType("ESCALATION"), undefined);
+  assert.equal(normalizeWaitStateType(3), undefined);
+});
+
+test("searchElementInstances passes zero-wait consistency, maps rows, and forwards selectors", async () => {
+  let seenInput: unknown;
+  let seenConsistency: unknown;
+  const client = fakeSdkClient({
+    searchElementInstances: async (input, c) => {
+      seenInput = input;
+      seenConsistency = c;
+      return {
+        items: [
+          {
+            elementInstanceKey: 5,
+            processInstanceKey: 3,
+            elementId: "task",
+            type: "SERVICE_TASK",
+            state: "active",
+          },
+          // elementType may arrive as `elementType` on a plain REST body.
+          {
+            elementInstanceKey: "6",
+            processInstanceKey: "3",
+            elementId: "gw",
+            elementType: "PARALLEL_GATEWAY",
+            state: "COMPLETED",
+          },
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchElementInstances({
+    processInstanceKey: "3",
+    elementId: "task",
+    state: "ACTIVE",
+  });
+  assert.deepEqual(seenInput, {
+    filter: { processInstanceKey: "3", elementId: "task", state: "ACTIVE" },
+  });
+  assert.deepEqual(seenConsistency, { consistency: { waitUpToMs: 0 } });
+  assert.deepEqual(out, [
+    {
+      elementInstanceKey: "5",
+      processInstanceKey: "3",
+      elementId: "task",
+      elementType: "SERVICE_TASK",
+      state: "ACTIVE",
+    },
+    {
+      elementInstanceKey: "6",
+      processInstanceKey: "3",
+      elementId: "gw",
+      elementType: "PARALLEL_GATEWAY",
+      state: "COMPLETED",
+    },
+  ]);
+});
+
+test("searchElementInstances with no filter sends an empty filter", async () => {
+  let seenInput: unknown;
+  const client = fakeSdkClient({
+    searchElementInstances: async (input) => {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchElementInstances();
+  assert.deepEqual(seenInput, { filter: {} });
+});
+
+test("searchElementInstances skips malformed rows (missing key/elementId/state)", async () => {
+  const client = fakeSdkClient({
+    searchElementInstances: async () => ({
+      items: [
+        { elementInstanceKey: "", processInstanceKey: "3", elementId: "a", state: "ACTIVE" }, // keyless
+        { elementInstanceKey: "   ", processInstanceKey: "3", elementId: "a", state: "ACTIVE" }, // whitespace key
+        { elementInstanceKey: "5", processInstanceKey: "", elementId: "a", state: "ACTIVE" }, // no PI key
+        { elementInstanceKey: "6", processInstanceKey: "3", elementId: "", state: "ACTIVE" }, // no elementId
+        { elementInstanceKey: "9", processInstanceKey: "3", elementId: "  ", state: "ACTIVE" }, // whitespace elementId
+        { elementInstanceKey: "7", processInstanceKey: "3", elementId: "a", state: "SKIPPED" }, // bad state
+        { elementInstanceKey: "8", processInstanceKey: "3", elementId: "ok", state: "ACTIVE" }, // kept
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchElementInstances();
+  assert.deepEqual(out, [
+    { elementInstanceKey: "8", processInstanceKey: "3", elementId: "ok", state: "ACTIVE" },
+  ]);
+});
+
+test("searchElementInstanceWaitStates maps JOB/MESSAGE parks and unwraps SDK `details`", async () => {
+  let seenInput: unknown;
+  let seenConsistency: unknown;
+  const client = fakeSdkClient({
+    searchElementInstanceWaitStates: async (input, c) => {
+      seenInput = input;
+      seenConsistency = c;
+      return {
+        items: [
+          {
+            elementInstanceKey: 5,
+            processInstanceKey: 3,
+            elementId: "svc",
+            type: "SERVICE_TASK",
+            details: { waitStateType: "JOB", jobType: "work", jobKey: 6 },
+          },
+          {
+            elementInstanceKey: 8,
+            processInstanceKey: 3,
+            elementId: "catch",
+            details: { waitStateType: "MESSAGE", messageName: "Go", correlationKey: "K1" },
+          },
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchElementInstanceWaitStates({ processInstanceKey: "3" });
+  assert.deepEqual(seenInput, { filter: { processInstanceKey: "3" } });
+  assert.deepEqual(seenConsistency, { consistency: { waitUpToMs: 0 } });
+  assert.deepEqual(out, [
+    {
+      elementInstanceKey: "5",
+      processInstanceKey: "3",
+      elementId: "svc",
+      elementType: "SERVICE_TASK",
+      waitStateType: "JOB",
+      jobType: "work",
+      jobKey: "6",
+    },
+    {
+      elementInstanceKey: "8",
+      processInstanceKey: "3",
+      elementId: "catch",
+      waitStateType: "MESSAGE",
+      messageName: "Go",
+      correlationKey: "K1",
+    },
+  ]);
+});
+
+test("searchElementInstanceWaitStates forwards a waitStateType selector and reads inlined details", async () => {
+  let seenInput: unknown;
+  const client = fakeSdkClient({
+    searchElementInstanceWaitStates: async (input) => {
+      seenInput = input;
+      // A plain REST body may inline the park fields rather than nesting them under `details`.
+      return {
+        items: [
+          {
+            elementInstanceKey: "9",
+            processInstanceKey: "3",
+            elementId: "ut",
+            waitStateType: "USER_TASK",
+            taskKey: "42",
+          },
+          {
+            elementInstanceKey: "11",
+            processInstanceKey: "3",
+            elementId: "ut2",
+            waitStateType: "USER_TASK",
+          }, // USER_TASK with no taskKey/userTaskKey → dropped (invalid identity)
+          { elementInstanceKey: "10", processInstanceKey: "3", elementId: "?" }, // no waitStateType → dropped
+        ],
+      };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchElementInstanceWaitStates({ waitStateType: "USER_TASK" });
+  assert.deepEqual(seenInput, { filter: { waitStateType: "USER_TASK" } });
+  assert.deepEqual(out, [
+    {
+      elementInstanceKey: "9",
+      processInstanceKey: "3",
+      elementId: "ut",
+      waitStateType: "USER_TASK",
+      userTaskKey: "42",
+    },
+  ]);
+});
+
+test("searchElementInstanceWaitStates drops parks missing their required discriminator field", async () => {
+  const client = fakeSdkClient({
+    searchElementInstanceWaitStates: async () => ({
+      items: [
+        { elementInstanceKey: "5", processInstanceKey: "3", elementId: "j", waitStateType: "JOB" }, // no jobType
+        { elementInstanceKey: "6", processInstanceKey: "3", elementId: "m", waitStateType: "MESSAGE" }, // no messageName
+        { elementInstanceKey: "7", processInstanceKey: "3", elementId: "s", waitStateType: "SIGNAL" }, // no signalName
+        {
+          elementInstanceKey: "8",
+          processInstanceKey: "3",
+          elementId: "j2",
+          waitStateType: "JOB",
+          jobType: "   ",
+        }, // blank jobType → dropped
+        {
+          elementInstanceKey: "9",
+          processInstanceKey: "3",
+          elementId: "t",
+          waitStateType: "TIMER",
+        }, // TIMER has no required field → kept
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchElementInstanceWaitStates();
+  assert.deepEqual(out, [
+    { elementInstanceKey: "9", processInstanceKey: "3", elementId: "t", waitStateType: "TIMER" },
+  ]);
+});
+
+test("getElementInstance returns a mapped summary, and null for a blank key or a 404", async () => {
+  const client = fakeSdkClient({
+    getElementInstance: async (input) => {
+      if (input.elementInstanceKey === "5") {
+        return {
+          elementInstanceKey: 5,
+          processInstanceKey: 3,
+          elementId: "task",
+          type: "SERVICE_TASK",
+          state: "ACTIVE",
+        };
+      }
+      throw new Error("404 not found");
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  assert.deepEqual(await engine.getElementInstance("5"), {
+    elementInstanceKey: "5",
+    processInstanceKey: "3",
+    elementId: "task",
+    elementType: "SERVICE_TASK",
+    state: "ACTIVE",
+  });
+  // A padded-but-valid key is normalized before the fetch, so it addresses the same instance.
+  assert.deepEqual(await engine.getElementInstance("  5  "), {
+    elementInstanceKey: "5",
+    processInstanceKey: "3",
+    elementId: "task",
+    elementType: "SERVICE_TASK",
+    state: "ACTIVE",
+  });
+  // A blank key short-circuits without hitting the engine; a 404 is treated as absence.
+  assert.equal(await engine.getElementInstance("   "), null);
+  assert.equal(await engine.getElementInstance("missing"), null);
+});
+
+test("searchIncidents normalizes the processInstanceKey selector (trims, drops blank)", async () => {
+  let seenInput: { filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    async searchIncidents(input) {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  // A padded key is trimmed before it reaches the engine filter.
+  await engine.searchIncidents({ processInstanceKey: "  7  " });
+  assert.deepEqual(seenInput?.filter, { processInstanceKey: "7" });
+
+  // A whitespace-only key is treated as absent, not forwarded as a garbage filter segment.
+  await engine.searchIncidents({ processInstanceKey: "   " });
+  assert.deepEqual(seenInput?.filter, {});
+
+  // The state selector still passes through untouched.
+  await engine.searchIncidents({ state: "ACTIVE" });
+  assert.deepEqual(seenInput?.filter, { state: "ACTIVE" });
+});
+
+test("resolveIncident normalizes the incidentKey and rejects a blank one", async () => {
+  let seen: { incidentKey: string } | undefined;
+  const client = fakeSdkClient({
+    async resolveIncident(input) {
+      seen = input;
+      return { ...input };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  await engine.resolveIncident({ incidentKey: "  inc-1  " });
+  assert.deepEqual(seen, { incidentKey: "inc-1" });
+
+  await assert.rejects(
+    engine.resolveIncident({ incidentKey: "   " }),
+    /incidentKey must be a non-empty key/,
+  );
+});
+
+test("setVariables normalizes the scopeKey and rejects a blank one", async () => {
+  let seen: Record<string, unknown> | undefined;
+  const client = fakeSdkClient({
+    async createElementInstanceVariables(input) {
+      seen = input;
+      return { ...input };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  await engine.setVariables({ scopeKey: "  ei-9  ", variables: { fixed: true } });
+  assert.deepEqual(seen, { elementInstanceKey: "ei-9", variables: { fixed: true } });
+
+  await assert.rejects(
+    engine.setVariables({ scopeKey: "  ", variables: { fixed: true } }),
+    /scopeKey must be a non-empty key/,
+  );
+});
+
+test("updateJobRetries normalizes the jobKey and rejects a blank key or an invalid retry count", async () => {
+  let seen: { jobKey: string; changeset: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    async updateJob(input) {
+      seen = input;
+      return { ...input };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  await engine.updateJobRetries({ jobKey: "  j-1  ", retries: 3 });
+  assert.deepEqual(seen, { jobKey: "j-1", changeset: { retries: 3 } });
+
+  await assert.rejects(
+    engine.updateJobRetries({ jobKey: "   ", retries: 3 }),
+    /jobKey must be a non-empty key/,
+  );
+  for (const retries of [-1, 1.5, Number.NaN]) {
+    await assert.rejects(
+      engine.updateJobRetries({ jobKey: "j-1", retries }),
+      /retries must be a non-negative integer/,
+      `retries=${retries} must be rejected`,
+    );
+  }
+});
+
 test("registerWorker creates a worker the SDK auto-starts, and dispatches + completes", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);