@nanobpm/urban 0.82.0 → 0.83.0

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -8,6 +8,27 @@ export declare function requireProcessInstanceKey(key: string | number | null |
  *  (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 declare function normalizeProcessInstanceState(raw: unknown): ProcessInstanceState | undefined;
+/** Map the engine's element-instance `state` onto the transport-agnostic
+ *  {@link ElementInstanceState} union, or `undefined` for an unrecognized value (which the
+ *  caller skips rather than surfacing a malformed row). Case-insensitive so a future casing
+ *  tweak on the engine side doesn't silently drop element instances. Kept separate from
+ *  {@link normalizeProcessInstanceState} — the two model distinct engine enums that only
+ *  coincide today — so element and process state can diverge without a hidden coupling. */
+export declare function normalizeElementInstanceState(raw: unknown): ElementInstanceState | undefined;
+/** Map the engine's wait-state `waitStateType` onto the transport-agnostic
+ *  {@link WaitStateType} union, or `undefined` for an unrecognized value. Case-insensitive
+ *  so a casing tweak doesn't silently drop parks. */
+export declare function normalizeWaitStateType(raw: unknown): WaitStateType | undefined;
+/** Map one engine element-instance row onto an {@link ElementInstanceSummary}, or `undefined`
+ *  when the row is malformed (missing key/elementId/process instance, or an unrecognized
+ *  state). The single source of truth both `searchElementInstances` and `getElementInstance`
+ *  extract through, so the two cannot drift. */
+export declare function mapElementInstanceRow(row: Record<string, unknown>, log: Log): ElementInstanceSummary | undefined;
+/** Map one engine wait-state row onto an {@link ElementInstanceWaitState}, or `undefined`
+ *  when the row is malformed (missing identity, or an unrecognized `waitStateType`). The
+ *  Camunda SDK nests the park-specific fields under `details`; a plain REST body may inline
+ *  them — read `details` first, then fall back to the row itself, so both wire shapes map. */
+export declare function mapElementInstanceWaitStateRow(row: Record<string, unknown>, log: Log): ElementInstanceWaitState | 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 {
@@ -88,6 +109,17 @@ export interface NanoSdkClient {
         filter?: Record<string, unknown>;
         page?: Record<string, unknown>;
     }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchElementInstances(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchElementInstanceWaitStates(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    getElementInstance(input: {
+        elementInstanceKey: string;
+    }, 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
@@ -152,6 +184,9 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
     }): Promise<ProcessInstanceSnapshot[]>;
+    searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
+    searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
+    getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
         maxParallelJobs?: number;

package/dist/runtime/engine/nanosdk.js

@@ -48,6 +48,211 @@ export function normalizeProcessInstanceState(raw) {
             return undefined;
     }
 }
+/** Map the engine's element-instance `state` onto the transport-agnostic
+ *  {@link ElementInstanceState} union, or `undefined` for an unrecognized value (which the
+ *  caller skips rather than surfacing a malformed row). Case-insensitive so a future casing
+ *  tweak on the engine side doesn't silently drop element instances. Kept separate from
+ *  {@link normalizeProcessInstanceState} — the two model distinct engine enums that only
+ *  coincide today — so element and process state can diverge without a hidden coupling. */
+export function normalizeElementInstanceState(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    switch (raw.toUpperCase()) {
+        case "ACTIVE":
+            return "ACTIVE";
+        case "COMPLETED":
+            return "COMPLETED";
+        case "TERMINATED":
+            return "TERMINATED";
+        default:
+            return undefined;
+    }
+}
+/** Map the engine's wait-state `waitStateType` onto the transport-agnostic
+ *  {@link WaitStateType} union, or `undefined` for an unrecognized value. Case-insensitive
+ *  so a casing tweak doesn't silently drop parks. */
+export function normalizeWaitStateType(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    switch (raw.toUpperCase()) {
+        case "JOB":
+            return "JOB";
+        case "MESSAGE":
+            return "MESSAGE";
+        case "USER_TASK":
+            return "USER_TASK";
+        case "TIMER":
+            return "TIMER";
+        case "SIGNAL":
+            return "SIGNAL";
+        case "CONDITION":
+            return "CONDITION";
+        default:
+            return undefined;
+    }
+}
+/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
+ *  whitespace-only string). Coerces a numeric key to a string (the engine may serialize a key
+ *  either way) but never `String(...)`-coerces an arbitrary object into a garbage
+ *  `"[object Object]"` id. The blank check trims, matching `getElementInstance`'s blank-key
+ *  guard and the form-key presence helpers, so a `"   "` key can never leak into a result. */
+function presentEngineKey(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? String(value) : undefined;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** A required text field (a wait-state discriminator's `jobType`/`messageName`/`signalName`),
+ *  or `undefined` when absent or blank — the caller skips the row rather than emitting a typed
+ *  wait state carrying an empty required string. Returns the trimmed value, matching the
+ *  presence rule used for keys, so surrounding whitespace can never leak into a result. */
+function presentText(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** The element type carried on an element-instance/wait-state row. The Camunda SDK DTO calls
+ *  it `type`; a plain REST/Rust-engine body may call it `elementType`. Accept either. */
+function pickElementType(row) {
+    return presentText(row.elementType) ?? presentText(row.type);
+}
+/** Map one engine element-instance row onto an {@link ElementInstanceSummary}, or `undefined`
+ *  when the row is malformed (missing key/elementId/process instance, or an unrecognized
+ *  state). The single source of truth both `searchElementInstances` and `getElementInstance`
+ *  extract through, so the two cannot drift. */
+export function mapElementInstanceRow(row, log) {
+    const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
+    if (elementInstanceKey === undefined) {
+        log("warn", "skipping element instance with no key in engine response");
+        return undefined;
+    }
+    const processInstanceKey = presentEngineKey(row.processInstanceKey);
+    if (processInstanceKey === undefined) {
+        log("warn", "skipping element instance with no processInstanceKey in engine response", {
+            elementInstanceKey,
+        });
+        return undefined;
+    }
+    const elementId = typeof row.elementId === "string" && row.elementId.trim() !== ""
+        ? row.elementId.trim()
+        : undefined;
+    if (elementId === undefined) {
+        log("warn", "skipping element instance with no elementId in engine response", {
+            elementInstanceKey,
+        });
+        return undefined;
+    }
+    const state = normalizeElementInstanceState(row.state);
+    if (state === undefined) {
+        log("warn", "skipping element instance with unrecognized state", {
+            elementInstanceKey,
+            state: String(row.state),
+        });
+        return undefined;
+    }
+    const elementType = pickElementType(row);
+    return {
+        elementInstanceKey,
+        processInstanceKey,
+        elementId,
+        ...(elementType ? { elementType } : {}),
+        state,
+    };
+}
+/** Map one engine wait-state row onto an {@link ElementInstanceWaitState}, or `undefined`
+ *  when the row is malformed (missing identity, or an unrecognized `waitStateType`). The
+ *  Camunda SDK nests the park-specific fields under `details`; a plain REST body may inline
+ *  them — read `details` first, then fall back to the row itself, so both wire shapes map. */
+export function mapElementInstanceWaitStateRow(row, log) {
+    const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
+    const processInstanceKey = presentEngineKey(row.processInstanceKey);
+    const elementId = typeof row.elementId === "string" && row.elementId.trim() !== ""
+        ? row.elementId.trim()
+        : undefined;
+    if (elementInstanceKey === undefined || processInstanceKey === undefined || elementId === undefined) {
+        log("warn", "skipping element-instance wait state with incomplete identity in engine response");
+        return undefined;
+    }
+    const details = isRecord(row.details) ? row.details : row;
+    const waitStateType = normalizeWaitStateType(details.waitStateType ?? row.waitStateType);
+    if (waitStateType === undefined) {
+        log("warn", "skipping element-instance wait state with unrecognized waitStateType", {
+            elementInstanceKey,
+            waitStateType: String(details.waitStateType ?? row.waitStateType),
+        });
+        return undefined;
+    }
+    const elementType = pickElementType(row);
+    const base = {
+        elementInstanceKey,
+        processInstanceKey,
+        elementId,
+        ...(elementType ? { elementType } : {}),
+    };
+    switch (waitStateType) {
+        case "JOB": {
+            // `jobType` is the required discriminator of a JOB park; without it the row is malformed.
+            const jobType = presentText(details.jobType);
+            if (jobType === undefined) {
+                log("warn", "skipping JOB wait state with no jobType in engine response", {
+                    elementInstanceKey,
+                });
+                return undefined;
+            }
+            const jobKey = presentEngineKey(details.jobKey);
+            return { ...base, waitStateType, jobType, ...(jobKey ? { jobKey } : {}) };
+        }
+        case "MESSAGE": {
+            // `messageName` is the required discriminator of a MESSAGE park.
+            const messageName = presentText(details.messageName);
+            if (messageName === undefined) {
+                log("warn", "skipping MESSAGE wait state with no messageName in engine response", {
+                    elementInstanceKey,
+                });
+                return undefined;
+            }
+            const correlationKey = presentText(details.correlationKey);
+            return {
+                ...base,
+                waitStateType,
+                messageName,
+                ...(correlationKey ? { correlationKey } : {}),
+            };
+        }
+        case "USER_TASK": {
+            // `userTaskKey` is the required identity of a USER_TASK park; without it the row is
+            // malformed. Skip it (like the missing-identity guards above) rather than emit a typed
+            // wait state carrying an empty key that would break a downstream join.
+            const userTaskKey = presentEngineKey(details.taskKey ?? details.userTaskKey);
+            if (userTaskKey === undefined) {
+                log("warn", "skipping USER_TASK wait state with no userTaskKey in engine response", {
+                    elementInstanceKey,
+                });
+                return undefined;
+            }
+            return { ...base, waitStateType, userTaskKey };
+        }
+        case "SIGNAL": {
+            // `signalName` is the required discriminator of a SIGNAL park.
+            const signalName = presentText(details.signalName);
+            if (signalName === undefined) {
+                log("warn", "skipping SIGNAL wait state with no signalName in engine response", {
+                    elementInstanceKey,
+                });
+                return undefined;
+            }
+            return { ...base, waitStateType, signalName };
+        }
+        case "TIMER":
+            return { ...base, waitStateType };
+        case "CONDITION":
+            return { ...base, waitStateType };
+    }
+}
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
  * message, and user-task calls map one-to-one onto the SDK's client methods; workers
@@ -215,6 +420,70 @@ export class SdkEngineClient {
             return [{ processInstanceKey: String(key), state }];
         });
     }
+    async searchElementInstances(filter) {
+        // Mirror `searchProcessInstances`: build the engine filter from the transport-agnostic
+        // selectors, read at zero-wait consistency (an element-instance search is eventually
+        // consistent), and map each row through the single `mapElementInstanceRow` gate — which
+        // also `searchElementInstances`/`getElementInstance` share — dropping malformed rows.
+        const f = {};
+        if (filter?.processInstanceKey)
+            f.processInstanceKey = filter.processInstanceKey;
+        if (filter?.elementId)
+            f.elementId = filter.elementId;
+        if (filter?.state)
+            f.state = filter.state;
+        const body = await this.client.searchElementInstances({ filter: f }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const mapped = mapElementInstanceRow(it, this.log);
+            return mapped ? [mapped] : [];
+        });
+    }
+    async searchElementInstanceWaitStates(filter) {
+        // The wait-states search surfaces *every* park (job/message/timer/signal/condition/user
+        // task), not just user tasks. Same zero-wait read + per-row mapping-gate shape as
+        // `searchElementInstances`; the SDK nests park-specific fields under `details`, which
+        // `mapElementInstanceWaitStateRow` unwraps.
+        const f = {};
+        if (filter?.processInstanceKey)
+            f.processInstanceKey = filter.processInstanceKey;
+        if (filter?.elementId)
+            f.elementId = filter.elementId;
+        if (filter?.waitStateType)
+            f.waitStateType = filter.waitStateType;
+        const body = await this.client.searchElementInstanceWaitStates({ filter: f }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const mapped = mapElementInstanceWaitStateRow(it, this.log);
+            return mapped ? [mapped] : [];
+        });
+    }
+    async getElementInstance(elementInstanceKey) {
+        // A blank key can never address an element instance — short-circuit to null rather than
+        // issue a `GET /element-instances/` with an empty segment. Normalize the key up front (as
+        // `getForm` resolves a normalized identifier before fetching) so a padded-but-valid key
+        // like `" 5 "` addresses the same element instance rather than 404ing on the raw segment.
+        if (typeof elementInstanceKey !== "string" || elementInstanceKey.trim() === "") {
+            return null;
+        }
+        const key = elementInstanceKey.trim();
+        let body;
+        try {
+            body = await this.client.getElementInstance({ elementInstanceKey: key }, { consistency: { waitUpToMs: 0 } });
+        }
+        catch (err) {
+            // A 404 (no such element instance) is an expected "not found", not a fault — mirror
+            // `getForm`, which treats a failed fetch as absence (null) rather than propagating.
+            this.log("warn", "getElementInstance: engine fetch failed", {
+                elementInstanceKey: key,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+        if (!isRecord(body))
+            return null;
+        return mapElementInstanceRow(body, this.log) ?? null;
+    }
     async registerWorker(jobType, handler, options) {
         const worker = this.client.createJobWorker({
             jobType,

package/dist/runtime/index.d.ts

@@ -8,7 +8,7 @@ export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, p
 export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-export type { EngineClient, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, WatchHandle, WorkerSubscription, } from "./core/host.ts";
+export type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.82.0",
+	"version": "0.83.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/browser/runtime.browser.js

@@ -2769,7 +2769,11 @@ function renderAppView(node) {
   });
 
   const section = el("section", { class: "pc-appview" + (fill ? " pc-appview-fill" : "") });
-  if (title) section.append(el("div", { class: "pc-appview-title" }, title));
+  // The title is an <h2> (the tag EVERY card renderer uses and makeCollapsible lifts into the
+  // collapse header), not a <div>: a collapsible appView's title must be lifted out of the body,
+  // otherwise it double-renders (header label + leftover in-body title). The .pc-appview-title CSS
+  // is class-based, so a non-collapsible appView renders identically.
+  if (title) section.append(el("h2", { class: "pc-appview-title" }, title));
   section.append(frame);
   return section;
 }

package/src/runtime/browser/runtime.browser.test.ts

@@ -157,14 +157,29 @@ test("#416: renderAppView mounts a base-relative iframe honoring embed/title/fil
   assert.equal(frame.getAttribute("title"), "Agent networks");
   assert.equal(frame.className, "pc-appview-frame");
 
-  // The title also renders as a visible label above the frame.
+  // The title also renders as a visible label above the frame — as an <h2> (see below).
   const label = section.children.find(
     (c): c is FakeElement => c instanceof FakeElement && c.className === "pc-appview-title",
   );
   assert.ok(label, "the title renders as a label");
+  assert.equal(label.tagName, "H2", "the appView title must be an <h2> so makeCollapsible lifts it (no duplicate title when collapsible)");
   assert.equal(label.textContent, "Agent networks");
 });
 
+test("#471: the appView title is an <h2> so a collapsible appView doesn't double-render it", (t) => {
+  // makeCollapsible lifts a card's title out of the body into the collapse header by finding the
+  // renderer's <h2> (card.querySelector('h2')). Every card renderer emits an <h2>; renderAppView
+  // used to emit a <div class=pc-appview-title>, so the lift missed it and a collapsible appView
+  // showed its title twice (header label + leftover in-body div). Pin the tag so that can't regress.
+  t.after(installFakeDom());
+  const section = asFake(renderAppView({ type: "appView", props: { title: "Staged proposals", embed: "./e.html" } }));
+  const label = section.children.find(
+    (c): c is FakeElement => c instanceof FakeElement && c.className === "pc-appview-title",
+  );
+  assert.ok(label, "the appView renders a title label");
+  assert.equal(label.tagName, "H2", "renderAppView must emit its title as the <h2> makeCollapsible lifts");
+});
+
 test("#416: renderAppView rebases a root-absolute embed onto the mount root", (t) => {
   t.after(installFakeDom());
   // A root-absolute "/embed.html" would escape the console proxy prefix and hit the

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"),
   };