@nanobpm/urban 0.82.1 → 0.83.0

package/src/runtime/core/host.ts

@@ -261,6 +261,104 @@ export interface UserTaskFilter {
   candidateGroup?: string;
 }
 
+/**
+ * An element instance's lifecycle state, as the engine reports it on a
+ * `/v2/element-instances/search` result. Mirrors the engine's `ElementInstanceStateEnum`:
+ * `ACTIVE` (a token is currently *at* this element), `COMPLETED` (the token has left it), or
+ * `TERMINATED` (the element was interrupted). Structurally the same state set as
+ * {@link ProcessInstanceState} (one active state plus the `COMPLETED`/`TERMINATED` terminals),
+ * but a distinct concept — element instances are the tokens *within* a process instance — so it
+ * is kept as its own type rather than aliased.
+ */
+export type ElementInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
+
+/**
+ * A single element instance ("token") as {@link EngineClient.searchElementInstances} and
+ * {@link EngineClient.getElementInstance} report it — the finest-grained "how far has this
+ * process instance progressed" signal, below the process-instance lifecycle
+ * ({@link ProcessInstanceSnapshot}) and independent of whether the element is a user task
+ * ({@link UserTaskSummary}). It surfaces active *non-user-task* elements (a service task, a
+ * gateway, a catch event) a user-task search cannot see — "the furthest element reached".
+ * Carries the element instance's own key, its identity (`elementId`, its BPMN `elementType`
+ * when the engine reports it), the owning process instance, and its lifecycle `state`.
+ */
+export interface ElementInstanceSummary {
+  readonly elementInstanceKey: string;
+  readonly processInstanceKey: string;
+  readonly elementId: string;
+  /** The BPMN element type (e.g. `"SERVICE_TASK"`, `"USER_TASK"`,
+   *  `"INTERMEDIATE_CATCH_EVENT"`), when the engine reports it. Kept transport-agnostic (a
+   *  bare string) so a new BPMN element type on the engine flows through without having to be
+   *  enumerated here. Absent when the adapter's read model does not carry it. */
+  readonly elementType?: string;
+  readonly state: ElementInstanceState;
+}
+
+/**
+ * The kind of wait an element instance is parked in, as a
+ * `/v2/element-instances/wait-states/search` result reports it. Unlike a user-task search,
+ * this surfaces *every* park — a `JOB` (a service task awaiting a worker), a `MESSAGE`
+ * (an event awaiting correlation), a `TIMER`, a `SIGNAL`, a `CONDITION`, as well as a
+ * `USER_TASK` — so a consumer can read "what is this instance blocked on" beyond user tasks.
+ */
+export type WaitStateType =
+  | "JOB"
+  | "MESSAGE"
+  | "USER_TASK"
+  | "TIMER"
+  | "SIGNAL"
+  | "CONDITION";
+
+/**
+ * A single parked (waiting) element instance as
+ * {@link EngineClient.searchElementInstanceWaitStates} reports it. Every variant carries the
+ * element instance's identity; the `waitStateType` discriminates the park-specific fields — a
+ * `JOB` carries the `jobType`/`jobKey` it is parked on, a `MESSAGE` the awaited
+ * `messageName`/`correlationKey`, a `USER_TASK` the `userTaskKey`, a `SIGNAL` the
+ * `signalName` — so a caller narrows on `waitStateType` to reach them type-safely rather than
+ * probing a flat optional-field bag.
+ */
+export type ElementInstanceWaitState =
+  & {
+    readonly elementInstanceKey: string;
+    readonly processInstanceKey: string;
+    readonly elementId: string;
+    readonly elementType?: string;
+  }
+  & (
+    | { readonly waitStateType: "JOB"; readonly jobType: string; readonly jobKey?: string }
+    | {
+      readonly waitStateType: "MESSAGE";
+      readonly messageName: string;
+      readonly correlationKey?: string;
+    }
+    | { readonly waitStateType: "USER_TASK"; readonly userTaskKey: string }
+    | { readonly waitStateType: "TIMER" }
+    | { readonly waitStateType: "SIGNAL"; readonly signalName: string }
+    | { readonly waitStateType: "CONDITION" }
+  );
+
+/**
+ * Selectors for an element-instance search: which process instance, element, and/or lifecycle
+ * state to match. Used by {@link EngineClient.searchElementInstances}.
+ */
+export interface ElementInstanceFilter {
+  processInstanceKey?: string;
+  elementId?: string;
+  state?: ElementInstanceState;
+}
+
+/**
+ * Selectors for an element-instance *wait-state* search: which process instance, element,
+ * and/or kind of wait to match. Used by {@link EngineClient.searchElementInstanceWaitStates}.
+ * There is deliberately no lifecycle-`state` selector — a wait state is always an active park.
+ */
+export interface ElementInstanceWaitStateFilter {
+  processInstanceKey?: string;
+  elementId?: string;
+  waitStateType?: WaitStateType;
+}
+
 /**
  * A deployed form's form-js schema plus its identifying metadata, as
  * {@link EngineClient.getForm} returns it. `schema` is the parsed form-js document
@@ -350,6 +448,41 @@ export interface EngineClient {
     processInstanceKeys?: string[];
     state?: ProcessInstanceState;
   }): Promise<ProcessInstanceSnapshot[]>;
+  /**
+   * Search element instances ("tokens") by process instance, element, and/or lifecycle state
+   * (`POST /v2/element-instances/search`). Where {@link searchProcessInstances} answers "is
+   * this instance still running" and {@link searchUserTasks} answers "what user tasks are
+   * open", this answers "what element has a token reached" — including the active
+   * *non-user-task* elements (a service task, a gateway, a catch event) that a user-task
+   * search cannot see, i.e. "the furthest element reached". An eventually consistent
+   * (zero-wait) read; each {@link ElementInstanceSummary} carries the element instance's key,
+   * its `elementId`/`elementType`, the owning process instance, and its `state`.
+   */
+  searchElementInstances(
+    filter?: ElementInstanceFilter,
+  ): Promise<ElementInstanceSummary[]>;
+  /**
+   * Search the *wait states* of element instances
+   * (`POST /v2/element-instances/wait-states/search`) — every park, not only user tasks. A
+   * `JOB` park (a service task awaiting a worker), a `MESSAGE` park (an event awaiting
+   * correlation), a `TIMER`/`SIGNAL`/`CONDITION`, plus `USER_TASK`. A zero-wait read; each
+   * result is discriminated by `waitStateType` (see {@link ElementInstanceWaitState}), so a
+   * consumer can read the job/message parks a {@link searchUserTasks} cannot surface.
+   */
+  searchElementInstanceWaitStates(
+    filter?: ElementInstanceWaitStateFilter,
+  ): Promise<ElementInstanceWaitState[]>;
+  /**
+   * Fetch a single element instance by its key (`GET /v2/element-instances/{elementInstanceKey}`),
+   * or `null` when it cannot be resolved — the key is blank, no such element instance exists
+   * (a 404), or the fetch otherwise fails. A read is treated as absence rather than propagating
+   * (mirroring {@link getForm}), so a caller distinguishes "have it" from "don't" without a
+   * try/catch. A zero-wait read returning the same {@link ElementInstanceSummary} shape as
+   * {@link searchElementInstances}.
+   */
+  getElementInstance(
+    elementInstanceKey: string,
+  ): Promise<ElementInstanceSummary | null>;
   /** Register a push worker for a job type. Draining is handled by the adapter. */
   registerWorker(
     jobType: string,
@@ -384,6 +517,9 @@ export const ENGINE_CLIENT_METHODS = [
   "getForm",
   "completeUserTask",
   "searchProcessInstances",
+  "searchElementInstances",
+  "searchElementInstanceWaitStates",
+  "getElementInstance",
   "registerWorker",
   "close",
 ] as const satisfies readonly (keyof EngineClient)[];

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

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

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

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

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

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

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

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

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

@@ -21,6 +21,9 @@ 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 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,9 @@ const noEngine: EngineClient = {
   getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
+  searchElementInstances: async () => [],
+  searchElementInstanceWaitStates: async () => [],
+  getElementInstance: async () => null,
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -90,6 +90,9 @@ function fakeEngine(
     searchUserTasks: notUsed("searchUserTasks"),
     getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
+    searchElementInstances: notUsed("searchElementInstances"),
+    searchElementInstanceWaitStates: notUsed("searchElementInstanceWaitStates"),
+    getElementInstance: notUsed("getElementInstance"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
   };

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

@@ -48,6 +48,9 @@ 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 registerWorker(jobType) { return { jobType, unsubscribe: async () => {} }; },
     async close() {},
   };

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

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

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

@@ -35,6 +35,9 @@ 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 registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -32,6 +32,9 @@ 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 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,15 @@ class NoopEngine implements EngineClient {
   async searchProcessInstances() {
     return [];
   }
+  async searchElementInstances() {
+    return [];
+  }
+  async searchElementInstanceWaitStates() {
+    return [];
+  }
+  async getElementInstance() {
+    return null;
+  }
   async registerWorker(jobType: string): Promise<WorkerSubscription> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -53,6 +53,15 @@ class FakeEngine implements EngineClient {
   async searchProcessInstances() {
     return [];
   }
+  async searchElementInstances() {
+    return [];
+  }
+  async searchElementInstanceWaitStates() {
+    return [];
+  }
+  async getElementInstance() {
+    return null;
+  }
   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,18 @@ 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 completeUserTask() {
       calls.push("completeUserTask");
       return {};
@@ -448,6 +462,273 @@ 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("registerWorker creates a worker the SDK auto-starts, and dispatches + completes", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);