@nanobpm/urban 0.88.1 → 0.90.0

package/dist/runtime/core/host.d.ts

@@ -198,6 +198,22 @@ export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
 export interface ProcessInstanceSnapshot {
     readonly processInstanceKey: string;
     readonly state: ProcessInstanceState;
+    /** The key of the deployed process definition this instance runs — the handle a caller feeds to
+     *  {@link EngineClient.getProcessDefinitionXml} to fetch the deployed BPMN (the instance →
+     *  `processDefinitionKey` → deployed XML path, no repo checkout). Absent when the engine omits it. */
+    readonly processDefinitionKey?: string;
+    /** The key of this instance's *immediate* parent process instance — the caller that instantiated
+     *  it as a native child (a `<bpmn:callActivity>`). `undefined` for a top-level (root) instance,
+     *  and absent when the engine omits it (same optional/engine-provided convention as
+     *  `processDefinitionKey`). Lets a reduced-capability read path map a native child back to the
+     *  subject that spawned it without a raw-REST channel. */
+    readonly parentProcessInstanceKey?: string;
+    /** The key of this instance's *root* process instance — the top-level ancestor of the
+     *  call-activity hierarchy this instance belongs to (equal to `processInstanceKey` for a
+     *  top-level instance). `undefined`/absent when the engine omits it (only present for hierarchies
+     *  created on an engine version that reports it). Lets a reduced-capability read path correlate a
+     *  deep native descendant straight back to its root subject. */
+    readonly rootProcessInstanceKey?: string;
 }
 /**
  * A single open user task as {@link EngineClient.searchUserTasks} reports it. Carries the
@@ -215,6 +231,24 @@ export interface UserTaskSummary {
     readonly formKey?: string;
     /** An external form reference (a form linked outside the deployment), if any. */
     readonly externalFormReference?: string;
+    /** The key of the process instance this task belongs to. Absent when the engine omits it (same
+     *  optional/engine-provided convention as `processDefinitionKey`). For a task owned by a native
+     *  child instance, this is the child's own key — the handle a reduced-capability read path feeds
+     *  to {@link EngineClient.searchProcessInstances} to resolve the child's parent/root linkage. */
+    readonly processInstanceKey?: string;
+    /** The key of the *immediate* parent process instance of this task's owning instance — the caller
+     *  that spawned it as a native child. Absent when the engine's user-task read model omits it (as
+     *  it does today: the engine surfaces the parent linkage on {@link ProcessInstanceSnapshot}, so a
+     *  caller resolves it via `processInstanceKey` → `searchProcessInstances`). Declared here for
+     *  parity with the process-instance snapshot and to flow through automatically if the read model
+     *  starts carrying it. */
+    readonly parentProcessInstanceKey?: string;
+    /** The key of the *root* process instance of this task's owning instance — the top-level ancestor
+     *  of the call-activity hierarchy the task lives in. Absent when the engine omits it. Lets a
+     *  reduced-capability read path (`pollUserTasks` and other reconcile/affordance surfaces)
+     *  correlate a native-child (e.g. human-escalation grandchild) task straight back to its root
+     *  subject through the typed seam, with no raw-REST fallback. */
+    readonly rootProcessInstanceKey?: string;
 }
 /**
  * The lifecycle-state-agnostic selectors for a user-task search: which process instance,
@@ -226,6 +260,14 @@ export interface UserTaskFilter {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
+    /** Select only tasks whose owning instance has this *immediate* parent process instance. Honored
+     *  server-side by the live gateway where the read model supports it; the in-process testkit
+     *  applies it client-side against the row's parent linkage (absent today on the user-task read
+     *  model, so it matches nothing until the engine surfaces it there). */
+    parentProcessInstanceKey?: string;
+    /** Select only tasks whose owning instance belongs to this *root* process-instance hierarchy — the
+     *  selector a reduced-capability path uses to fetch every open task under one root subject. */
+    rootProcessInstanceKey?: string;
 }
 /**
  * An element instance's lifecycle state, as the engine reports it on a
@@ -425,6 +467,72 @@ export interface FormSchema {
     readonly version?: number;
     readonly schema: Record<string, unknown>;
 }
+/**
+ * Selectors for a variable search: which process instance and/or scope to match, optionally
+ * narrowed to a single variable `name`. Used by {@link EngineClient.searchVariables}. An
+ * eventually consistent (zero-wait) read; an unset selector matches every variable in scope.
+ */
+export interface VariableFilter {
+    processInstanceKey?: string;
+    scopeKey?: string;
+    name?: string;
+}
+/**
+ * A single process variable as {@link EngineClient.searchVariables} reports it — the read
+ * counterpart to the write-only {@link EngineClient.setVariables}. Mirrors the engine's v2
+ * `/variables/search` row: the variable's own `variableKey`, its `name`, its serialized JSON
+ * `value` (a string — an object/array value arrives JSON-encoded, so a caller `JSON.parse`s it),
+ * the `scopeKey` it is directly defined in (a process-instance key for a process-level variable,
+ * an element-instance key for a local one) and the owning `processInstanceKey`. `isTruncated` is
+ * `true` when the engine clipped a large `value` for the read model — the caller then knows the
+ * `value` is a preview, not the whole payload. This is the only way to read a parked token's
+ * business payload (`prKey`, `round`, an escalation `question`/`answer`, `resolution`,
+ * `directive`); the ADR 0065 projections carry lifecycle/position, not the payload.
+ */
+export interface VariableSummary {
+    readonly variableKey: string;
+    readonly name: string;
+    readonly value: string;
+    readonly scopeKey: string;
+    readonly processInstanceKey: string;
+    readonly isTruncated: boolean;
+}
+/**
+ * Selectors for a job search: which process instance, lifecycle `state`, job `type`, `elementId`,
+ * and/or leasing `worker` to match. Used by {@link EngineClient.searchJobs}. `state` is kept a
+ * transport-agnostic bare string (the engine's job-state enum is broad and forward-looking — e.g.
+ * `CREATED`/`COMPLETED`/`FAILED`/`TIMED_OUT`), so a new engine state flows through without having
+ * to be enumerated here. An eventually consistent (zero-wait) read; an unset selector matches
+ * every job.
+ */
+export interface JobFilter {
+    processInstanceKey?: string;
+    state?: string;
+    type?: string;
+    elementId?: string;
+    worker?: string;
+}
+/**
+ * A single job as {@link EngineClient.searchJobs} reports it — mirrors the engine's v2
+ * `/jobs/search` row. Carries the `jobKey` a caller passes to
+ * {@link EngineClient.updateJobRetries} (the only source of a `jobKey` for a job NOT already
+ * behind a `jobNoRetries` incident, which {@link searchIncidents} surfaces), the job `type` and
+ * lifecycle `state` (a bare string — see {@link JobFilter}), the owning `processInstanceKey`, and
+ * the best-effort diagnostics `worker`/`retries`/`elementId`/`deadline`. The `worker` field is the
+ * "is it actually stuck" signal: a `CREATED` job WITH a `worker` set has been leased by an agent,
+ * while one with NONE set is merely queued — so `worker` is omitted (absent) when unset. `retries`,
+ * `elementId`, and `deadline` are likewise present when the engine reports them, omitted otherwise.
+ */
+export interface JobSummary {
+    readonly jobKey: string;
+    readonly type: string;
+    readonly state: string;
+    readonly processInstanceKey: string;
+    readonly worker?: string;
+    readonly retries?: number;
+    readonly elementId?: string;
+    readonly deadline?: string;
+}
 /**
  * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
@@ -512,6 +620,12 @@ export interface EngineClient {
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
+        /** Select only instances whose *immediate* parent is this process instance — the reduced-path
+         *  query for "the native children spawned by this subject". */
+        parentProcessInstanceKey?: string;
+        /** Select only instances belonging to this *root* process-instance hierarchy — "every instance
+         *  under this root subject", the deep-descendant correlation query. */
+        rootProcessInstanceKey?: string;
     }): Promise<ProcessInstanceSnapshot[]>;
     /**
      * Search element instances ("tokens") by process instance, element, and/or lifecycle state
@@ -560,6 +674,40 @@ export interface EngineClient {
      * they answer "how far has this instance progressed", this answers "why is it stuck".
      */
     searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    /**
+     * Search process variables by owning process instance and/or scope, optionally narrowed to a
+     * single `name` (`POST /v2/variables/search`). The read counterpart to the write-only
+     * {@link setVariables}: it is the only way to see a parked token's business payload (`prKey`,
+     * `round`, an escalation `question`/`answer`, `resolution`, `directive`) — the ADR 0065
+     * projections carry lifecycle/position, not the payload. An eventually consistent (zero-wait)
+     * read; each {@link VariableSummary} carries the variable's serialized JSON `value` (a string)
+     * and an `isTruncated` flag set when the engine clipped a large value for the read model.
+     */
+    searchVariables(filter?: VariableFilter): Promise<VariableSummary[]>;
+    /**
+     * Search jobs by owning process instance, lifecycle `state`, job `type`, `elementId`, and/or
+     * leasing `worker` (`POST /v2/jobs/search`). This is the "is it actually stuck" read: a
+     * `CREATED` job WITH a `worker` set has been leased by an agent, while one with NONE set is
+     * merely queued. It is also the on-tool source of a `jobKey` for {@link updateJobRetries} when
+     * the job is NOT behind an incident — {@link searchIncidents} only surfaces a `jobKey` for a
+     * job that already faulted (a `jobNoRetries` incident), so retrying an un-incidented job would
+     * otherwise be impossible without a direct engine-API call. An eventually consistent (zero-wait)
+     * read; each {@link JobSummary} carries the `jobKey` plus best-effort `worker`/`retries`/
+     * `elementId`/`deadline` diagnostics.
+     */
+    searchJobs(filter?: JobFilter): Promise<JobSummary[]>;
+    /**
+     * Fetch the deployed BPMN XML of a process definition by its `processDefinitionKey`
+     * (`GET /v2/process-definitions/{processDefinitionKey}/xml`), or `null` when the key is blank,
+     * unknown (a 404), or the definition carries no XML. This is the *deployed* model — the routing
+     * source of truth, including its FEEL gateway conditions — so an agent can reason about WHY an
+     * instance routed where it did without checking out `resources/processes/*.bpmn` from the app
+     * repo. An instance already carries its `processDefinitionKey` (via {@link searchProcessInstances}),
+     * so the path is instance → `processDefinitionKey` → deployed XML. A read is treated as absence
+     * (`null`) rather than propagating (mirroring {@link getForm}/{@link getElementInstance}), so a
+     * caller distinguishes "have it" from "don't" without a try/catch. A zero-wait read.
+     */
+    getProcessDefinitionXml(processDefinitionKey: string): Promise<string | null>;
     /**
      * Resolve an open incident by key (`POST /v2/incidents/{incidentKey}/resolution`), unblocking
      * the parked token: a job incident returns the job to the activatable pool (so it must have
@@ -614,4 +762,4 @@ export interface EngineClient {
  * and `getForm` before it) that a purely structural `implements EngineClient` check no
  * longer catches once the fake is published/compiled against an older `@nanobpm/urban`.
  */
-export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "searchIncidents", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];
+export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "searchIncidents", "searchVariables", "searchJobs", "getProcessDefinitionXml", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];

package/dist/runtime/core/host.js

@@ -118,6 +118,9 @@ export const ENGINE_CLIENT_METHODS = [
     "searchElementInstanceWaitStates",
     "getElementInstance",
     "searchIncidents",
+    "searchVariables",
+    "searchJobs",
+    "getProcessDefinitionXml",
     "resolveIncident",
     "updateJobRetries",
     "setVariables",

package/dist/runtime/core/modules/mcp.js

@@ -536,6 +536,74 @@ function buildDebugTools(app) {
                 return app.engine.searchIncidents(filter);
             },
         },
+        {
+            name: `${DEBUG_PREFIX}search_variables`,
+            description: "Engine truth: search process variables by process instance and/or scope, optionally by name — the read counterpart to set_variables. Reads only, eventually consistent. This is the only way to see a parked token's business payload (prKey, round, an escalation question/answer, resolution, directive); the projections carry lifecycle/position, not the payload. Each result carries the variableKey/name/serialized-JSON value/scopeKey/processInstanceKey/isTruncated.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    processInstanceKey: OPTIONAL_STRING,
+                    scopeKey: OPTIONAL_STRING,
+                    name: OPTIONAL_STRING,
+                },
+            },
+            run: (args) => {
+                const filter = {};
+                const pik = readPresentString(args, "processInstanceKey");
+                if (pik)
+                    filter.processInstanceKey = pik;
+                const scopeKey = readPresentString(args, "scopeKey");
+                if (scopeKey)
+                    filter.scopeKey = scopeKey;
+                const name = readPresentString(args, "name");
+                if (name)
+                    filter.name = name;
+                return app.engine.searchVariables(filter);
+            },
+        },
+        {
+            name: `${DEBUG_PREFIX}search_jobs`,
+            description: "Engine truth: search jobs by process instance, state, and/or type/elementId/worker. Reads only, eventually consistent. The 'is it actually stuck?' test: a CREATED job WITH a worker set has been leased by an agent, one with NONE set is merely queued. This is also the on-tool source of a jobKey for retry_job (the only other source is a jobNoRetries incident via search_incidents). Each result carries jobKey/type/state/processInstanceKey and the best-effort worker/retries/elementId/deadline.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    processInstanceKey: OPTIONAL_STRING,
+                    state: OPTIONAL_STRING,
+                    type: OPTIONAL_STRING,
+                    elementId: OPTIONAL_STRING,
+                    worker: OPTIONAL_STRING,
+                },
+            },
+            run: (args) => {
+                const filter = {};
+                const pik = readPresentString(args, "processInstanceKey");
+                if (pik)
+                    filter.processInstanceKey = pik;
+                const state = readPresentString(args, "state");
+                if (state)
+                    filter.state = state;
+                const type = readPresentString(args, "type");
+                if (type)
+                    filter.type = type;
+                const elementId = readPresentString(args, "elementId");
+                if (elementId)
+                    filter.elementId = elementId;
+                const worker = readPresentString(args, "worker");
+                if (worker)
+                    filter.worker = worker;
+                return app.engine.searchJobs(filter);
+            },
+        },
+        {
+            name: `${DEBUG_PREFIX}get_process_definition_xml`,
+            description: "Engine truth: return the deployed BPMN XML of a process definition by key (the routing source of truth, with its FEEL gateway conditions) — reason about WHY an instance routed where it did without a repo checkout. Reads only; null when the key is unknown. An instance carries its processDefinitionKey via search_process_instances, so the path is instance → processDefinitionKey → deployed XML; pair with get_element_instance to locate the parked element.",
+            inputSchema: {
+                type: "object",
+                properties: { processDefinitionKey: OPTIONAL_STRING },
+                required: ["processDefinitionKey"],
+            },
+            run: (args) => app.engine.getProcessDefinitionXml(requireString(args, "processDefinitionKey")),
+        },
         {
             name: `${DEBUG_PREFIX}cancel_instance`,
             description: "MUTATING: cancel a running process instance. Requires the shared-secret guard.",

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

@@ -1,4 +1,4 @@
-import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, 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. */
@@ -40,6 +40,21 @@ export declare function mapElementInstanceWaitStateRow(row: Record<string, unkno
  *  `errorMessage` are best-effort diagnostics: present when the engine reports them, omitted
  *  otherwise. The single source of truth `searchIncidents` extracts through. */
 export declare function mapIncidentRow(row: Record<string, unknown>, log: Log): IncidentSummary | undefined;
+/** 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 declare function mapVariableRow(row: Record<string, unknown>, log: Log): VariableSummary | undefined;
+/** 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 declare function mapJobRow(row: Record<string, unknown>, log: Log): JobSummary | 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 {
@@ -135,6 +150,17 @@ export interface NanoSdkClient {
         filter?: Record<string, unknown>;
         page?: Record<string, unknown>;
     }, 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): Promise<unknown>;
@@ -210,11 +236,16 @@ export declare class SdkEngineClient implements EngineClient {
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
+        parentProcessInstanceKey?: string;
+        rootProcessInstanceKey?: string;
     }): Promise<ProcessInstanceSnapshot[]>;
     searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
     searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
     getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
     searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    searchVariables(filter?: VariableFilter): Promise<VariableSummary[]>;
+    searchJobs(filter?: JobFilter): Promise<JobSummary[]>;
+    getProcessDefinitionXml(processDefinitionKey: string): Promise<string | null>;
     resolveIncident(input: {
         incidentKey: string;
     }): Promise<void>;

package/dist/runtime/engine/nanosdk.js

@@ -320,6 +320,91 @@ export function mapIncidentRow(row, log) {
         state: normalizeIncidentState(row.state),
     };
 }
+/** 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, log) {
+    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, log) {
+    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 } : {}),
+    };
+}
 /**
  * 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
@@ -380,7 +465,20 @@ export class SdkEngineClient {
     async searchUserTasks(filter) {
         // User tasks are an eventually consistent read; ask for zero-wait consistency so
         // the search reflects what is currently visible without blocking.
-        const body = await this.client.searchUserTasks({ filter: { ...(filter ?? {}) } }, { consistency: { waitUpToMs: 0 } });
+        // 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 = { ...(filter ?? {}) };
+        for (const sel of ["processInstanceKey", "parentProcessInstanceKey", "rootProcessInstanceKey"]) {
+            const normalized = presentEngineKey(filter?.[sel]);
+            if (normalized)
+                f[sel] = normalized;
+            else
+                delete f[sel];
+        }
+        const body = await this.client.searchUserTasks({ filter: f }, { consistency: { waitUpToMs: 0 } });
         const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
         return items.flatMap((it) => {
             const userTaskKey = it.userTaskKey ?? it.key;
@@ -391,10 +489,16 @@ export class SdkEngineClient {
             // 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),
                 }];
         });
@@ -460,9 +564,24 @@ export class SdkEngineClient {
         const f = {};
         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 !== 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
@@ -471,20 +590,33 @@ export class SdkEngineClient {
         const body = await this.client.searchProcessInstances({ filter: f, ...(page ? { page } : {}) }, { consistency: { waitUpToMs: 0 } });
         const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
         return items.flatMap((it) => {
-            const key = it.processInstanceKey;
-            if (key == null || key === "") {
+            // 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 } : {}),
+                }];
         });
     }
     async searchElementInstances(filter) {
@@ -575,6 +707,78 @@ export class SdkEngineClient {
             return mapped ? [mapped] : [];
         });
     }
+    async searchVariables(filter) {
+        // 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 = {};
+        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) {
+        // 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 = {};
+        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) {
+        // 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;
+        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) {
         await this.client.resolveIncident({
             incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),

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, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, 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, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, 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.88.1",
+	"version": "0.90.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",