@nanobpm/urban 0.95.0 → 0.96.0

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

@@ -216,14 +216,33 @@ export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
  * never surface in the `taskInbox` as if it were actionable.
  */
 export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
-/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
-export interface ProcessInstanceSnapshot {
-    readonly processInstanceKey: string;
-    readonly state: ProcessInstanceState;
+/**
+ * Which deployed process definition an instance runs — shared by the instance a
+ * {@link EngineClient.createInstance} starts and the {@link ProcessInstanceSnapshot} a
+ * {@link EngineClient.searchProcessInstances} reports, so the two describe the same instance
+ * identically. Each field is absent when the engine omits it (or reports it blank/malformed).
+ */
+export interface ProcessDefinitionIdentity {
     /** 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. */
+     *  `processDefinitionKey` → deployed XML path, no repo checkout). Unique per deployed version. */
     readonly processDefinitionKey?: string;
+    /** The BPMN process id (`<bpmn:process id>`) — stable across versions; the selector
+     *  {@link EngineClient.searchProcessInstances} accepts as `processDefinitionId`. */
+    readonly processDefinitionId?: string;
+    /** The deployed version of `processDefinitionId` this instance runs (1-based). */
+    readonly processDefinitionVersion?: number;
+}
+/** The instance {@link EngineClient.createInstance} started: its key, the exact deployed
+ *  definition version it runs, and — when `awaitCompletion` was requested — its final variables. */
+export interface CreatedProcessInstance extends ProcessDefinitionIdentity {
+    readonly processInstanceKey: string;
+    readonly variables?: Record<string, unknown>;
+}
+/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
+export interface ProcessInstanceSnapshot extends ProcessDefinitionIdentity {
+    readonly processInstanceKey: string;
+    readonly state: ProcessInstanceState;
     /** 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
@@ -664,15 +683,14 @@ export interface EngineClient {
     }[]): Promise<{
         deployed: number;
     }>;
-    /** Start a process instance. */
+    /** Start a process instance of the latest deployed version of `processDefinitionId`. Returns
+     *  the new instance's key plus the {@link ProcessDefinitionIdentity} (key, id, version) of the
+     *  definition it actually runs. */
     createInstance(input: {
         processDefinitionId: string;
         variables?: Record<string, unknown>;
         awaitCompletion?: boolean;
-    }): Promise<{
-        processInstanceKey: string;
-        variables?: Record<string, unknown>;
-    }>;
+    }): Promise<CreatedProcessInstance>;
     /** Cancel a running process instance (the pages surface's row-cancel action). */
     cancelInstance(input: {
         processInstanceKey: string;
@@ -725,7 +743,8 @@ export interface EngineClient {
     /** Complete a user task. */
     completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
     /**
-     * Search process instances by key and/or lifecycle state. The instance-tracking
+     * Search process instances by key, BPMN process id (`processDefinitionId`, any version),
+     * and/or lifecycle state. The instance-tracking
      * reconciler uses this to detect a tracked instance reaching a terminal state
      * (`TERMINATED`/`COMPLETED`) even though no completion worker ran for it — the
      * read-model row it backs would otherwise stay "active" forever. An eventually
@@ -735,6 +754,9 @@ export interface EngineClient {
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
+        /** Select only instances of this BPMN process id (every deployed version). A blank or
+         *  whitespace-only value is treated as absent (no filter). */
+        processDefinitionId?: string;
         /** Select only instances whose *immediate* parent is this process instance — the reduced-path
          *  query for "the native children spawned by this subject". */
         parentProcessInstanceKey?: string;

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

@@ -428,11 +428,12 @@ function buildDebugTools(app) {
     return [
         {
             name: `${DEBUG_PREFIX}search_process_instances`,
-            description: "Engine truth: search process instances by key and/or lifecycle state.",
+            description: "Engine truth: search process instances by key, BPMN process id (processDefinitionId, any version), and/or lifecycle state.",
             inputSchema: {
                 type: "object",
                 properties: {
                     processInstanceKeys: { type: "array", items: OPTIONAL_STRING },
+                    processDefinitionId: OPTIONAL_STRING,
                     state: { type: "string", enum: ["ACTIVE", "COMPLETED", "TERMINATED"] },
                 },
             },
@@ -444,6 +445,9 @@ function buildDebugTools(app) {
                 const state = readProcessInstanceState(args, "state");
                 if (state)
                     filter.state = state;
+                const processDefinitionId = readPresentString(args, "processDefinitionId");
+                if (processDefinitionId)
+                    filter.processDefinitionId = processDefinitionId;
                 return app.engine.searchProcessInstances(filter);
             },
         },

package/dist/runtime/core/process-identity.d.ts

@@ -0,0 +1,21 @@
+import type { ProcessDefinitionIdentity } from "./host.ts";
+export type { ProcessDefinitionIdentity };
+/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
+ *  whitespace-only string). Coerces a *finite* 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, nor a non-finite number into `"NaN"`/`"Infinity"`. The blank check trims,
+ *  matching the read-path blank-key guards, so a `"   "` key can never leak into a result. */
+export declare function presentEngineKey(value: unknown): string | undefined;
+/** A present string-only identifier (e.g. a BPMN process id) under the shared trim rule; a
+ *  non-string is absent and never `String(...)`-coerced. */
+export declare function presentString(value: unknown): string | undefined;
+/** The {@link ProcessDefinitionIdentity} an engine row (a create response or a process-instance
+ *  search row) reports — the single mapping both `createInstance` and `searchProcessInstances` use,
+ *  so a created instance and its later snapshot describe the same definition identically. Each field
+ *  passes the shared presence rule; a version that is not a positive integer number is omitted
+ *  (never coerced). */
+export declare function pickProcessDefinitionIdentity(row: {
+    processDefinitionKey?: unknown;
+    processDefinitionId?: unknown;
+    processDefinitionVersion?: unknown;
+}): ProcessDefinitionIdentity;

package/dist/runtime/core/process-identity.js

@@ -0,0 +1,56 @@
+// The single, transport-agnostic normalizer for a {@link ProcessDefinitionIdentity}. Both engine
+// adapters — the live SDK/REST adapter (`engine/nanosdk.ts`, `SdkEngineClient`) and the in-process
+// WASM test adapter (`@nanobpm/urban-testkit`, `WasmEngineClient`) — report which deployed
+// definition an instance runs on *both* `createInstance` and `searchProcessInstances`. Each used to
+// carry its own hand-mirrored `pickProcessDefinitionIdentity` (plus a re-declared identity type), so
+// the two could silently diverge the moment identity validation changed — exactly the drift class
+// the shared form-contract normalizer exists to kill (`./form-contract.ts`, issue #252). Centralizing
+// the mapper (and reusing the canonical {@link ProcessDefinitionIdentity}) here removes that surface:
+// a created instance and its later snapshot describe the same definition identically wherever this
+// normalizer runs, because they run the *same* code.
+//
+// Ownership today: only the SDK adapter runs this implementation. `WasmEngineClient` still defines
+// and calls its own behaviourally identical copy (`urban-testkit/src/wasm-engine.ts`) — a deliberate,
+// temporary fork: this module is introduced by the same change, so it exists in no published urban
+// release, and a value import would force the testkit's peer floor up to an urban version that does
+// not yet exist (AGENTS.md: depend on an unreleased sibling only after it is published). Follow-up
+// #585 switches the WASM adapter to this canonical import once the urban release carrying it is
+// published; until then the testkit's own identity cases pin its copy to this normalizer's behaviour.
+/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
+ *  whitespace-only string). Coerces a *finite* 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, nor a non-finite number into `"NaN"`/`"Infinity"`. The blank check trims,
+ *  matching the read-path blank-key guards, so a `"   "` key can never leak into a result. */
+export 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 present string-only identifier (e.g. a BPMN process id) under the shared trim rule; a
+ *  non-string is absent and never `String(...)`-coerced. */
+export function presentString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/** The {@link ProcessDefinitionIdentity} an engine row (a create response or a process-instance
+ *  search row) reports — the single mapping both `createInstance` and `searchProcessInstances` use,
+ *  so a created instance and its later snapshot describe the same definition identically. Each field
+ *  passes the shared presence rule; a version that is not a positive integer number is omitted
+ *  (never coerced). */
+export function pickProcessDefinitionIdentity(row) {
+    const processDefinitionKey = presentEngineKey(row.processDefinitionKey);
+    const processDefinitionId = presentString(row.processDefinitionId);
+    const version = row.processDefinitionVersion;
+    const processDefinitionVersion = typeof version === "number" && Number.isInteger(version) && version > 0 ? version : undefined;
+    return {
+        ...(processDefinitionKey ? { processDefinitionKey } : {}),
+        ...(processDefinitionId ? { processDefinitionId } : {}),
+        ...(processDefinitionVersion !== undefined ? { processDefinitionVersion } : {}),
+    };
+}

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

@@ -1,4 +1,4 @@
-import type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceSummary, 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 { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobFilter, JobHandler, JobSummary, CreatedProcessInstance, 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. */
@@ -233,10 +233,7 @@ export declare class SdkEngineClient implements EngineClient {
         processDefinitionId: string;
         variables?: Record<string, unknown>;
         awaitCompletion?: boolean;
-    }): Promise<{
-        processInstanceKey: string;
-        variables?: Record<string, unknown>;
-    }>;
+    }): Promise<CreatedProcessInstance>;
     cancelInstance(input: {
         processInstanceKey: string;
     }): Promise<void>;
@@ -260,6 +257,7 @@ export declare class SdkEngineClient implements EngineClient {
     searchProcessInstances(filter?: {
         processInstanceKeys?: string[];
         state?: ProcessInstanceState;
+        processDefinitionId?: string;
         parentProcessInstanceKey?: string;
         rootProcessInstanceKey?: string;
     }): Promise<ProcessInstanceSnapshot[]>;

package/dist/runtime/engine/nanosdk.js

@@ -19,6 +19,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { assertDeployedWaitStateType, isBpmnError } from "../core/host.js";
+import { pickProcessDefinitionIdentity, presentEngineKey, presentString, } from "../core/process-identity.js";
 import { buildFormSchema, parseFormSchema, pickFormLinkage, resolveFormIdentifier, } from "../core/form-contract.js";
 import { isRecord } from "../core/guards.js";
 import { applyAmbientLineage } from "../core/lineage.js";
@@ -111,20 +112,11 @@ export function normalizeIncidentState(raw) {
             return "UNKNOWN";
     }
 }
-/** 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;
-}
+// Engine-key / process-definition-identity normalization now lives in the shared, adapter-agnostic
+// `../core/process-identity.ts` (imported above), so this adapter's `createInstance` and
+// `searchProcessInstances` run the *same* mapping — see that module's header for the drift class
+// this removes. The WASM test adapter keeps a mirrored local copy until #585 (that module header's
+// "Ownership today" note), so the shared mapping is not yet a cross-adapter guarantee.
 /** The non-empty, trimmed string form of a *required* engine key, or throws when the value is
  *  absent/blank (including a whitespace-only string). A mutating seam operation addresses a
  *  single entity by key, so a blank key is a caller bug that must fail fast with an actionable
@@ -632,6 +624,7 @@ export class SdkEngineClient {
         const variables = isRecord(body.variables) ? body.variables : undefined;
         return {
             processInstanceKey: requireProcessInstanceKey(key),
+            ...pickProcessDefinitionIdentity(body),
             variables,
         };
     }
@@ -749,6 +742,10 @@ export class SdkEngineClient {
         const f = {};
         if (filter?.state)
             f.state = filter.state;
+        // A blank BPMN process-id selector is absent, not an empty filter that matches nothing.
+        const processDefinitionId = presentString(filter?.processDefinitionId);
+        if (processDefinitionId)
+            f.processDefinitionId = processDefinitionId;
         // 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
@@ -792,13 +789,12 @@ export class SdkEngineClient {
                 });
                 return [];
             }
-            const processDefinitionKey = presentEngineKey(it.processDefinitionKey);
             const parentProcessInstanceKey = presentEngineKey(it.parentProcessInstanceKey);
             const rootProcessInstanceKey = presentEngineKey(it.rootProcessInstanceKey);
             return [{
                     processInstanceKey,
                     state,
-                    ...(processDefinitionKey ? { processDefinitionKey } : {}),
+                    ...pickProcessDefinitionIdentity(it),
                     ...(parentProcessInstanceKey ? { parentProcessInstanceKey } : {}),
                     ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
                 }];

package/dist/runtime/index.d.ts

@@ -8,9 +8,10 @@ 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, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceMetrics, AgentInstanceSummary, 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 type { EngineClient, AgentHistoryFilter, AgentHistoryRecord, AgentInstanceFilter, AgentInstanceMetrics, AgentInstanceSummary, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, JobFilter, JobHandler, JobSummary, CreatedProcessInstance, ProcessDefinitionIdentity, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { TranscriptContentBlock, TranscriptContentType, TranscriptToolCall, TranscriptTurnMetrics, TranscriptTurnRole, } from "@nanobpm/agentic/transcript";
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
+export { pickProcessDefinitionIdentity, presentEngineKey, presentString, } from "./core/process-identity.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";
 export type { Logger, LogLevel, LogFields, LogSink } from "./core/logger.ts";

package/dist/runtime/index.js

@@ -12,6 +12,11 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 // both engine adapters (SDK/REST + WASM test double) call, so their form-identifier,
 // form-schema, and user-task form-linkage handling cannot drift.
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.js";
+// The adapter-agnostic process-definition-identity normalizer (the single mapping both
+// `createInstance` and `searchProcessInstances` use), owned today by the live SDK adapter; the WASM
+// test adapter keeps a mirrored local copy until #585, so cross-adapter drift-freedom is not yet
+// claimed. `ProcessDefinitionIdentity` itself is re-exported from `./core/host.ts`.
+export { pickProcessDefinitionIdentity, presentEngineKey, presentString, } from "./core/process-identity.js";
 // Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
 // so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).
 export { createLogger } from "./core/logger.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.95.0",
+	"version": "0.96.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",
@@ -106,7 +106,7 @@
 		"@nanobpm/agentic": "^0.15.0",
 		"@nanobpm/nano-app-schema": "^0.11.0",
 		"@nanobpm/nano-sdk": "^1.2.5",
-		"@nanobpm/workflow": "^0.14.0",
+		"@nanobpm/workflow": "^0.15.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
 		"create-urban-app": "^0.15.2",
 		"yaml": "^2.9.0"

package/src/runtime/core/host.ts

@@ -257,14 +257,35 @@ export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
  */
 export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
 
-/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
-export interface ProcessInstanceSnapshot {
-  readonly processInstanceKey: string;
-  readonly state: ProcessInstanceState;
+/**
+ * Which deployed process definition an instance runs — shared by the instance a
+ * {@link EngineClient.createInstance} starts and the {@link ProcessInstanceSnapshot} a
+ * {@link EngineClient.searchProcessInstances} reports, so the two describe the same instance
+ * identically. Each field is absent when the engine omits it (or reports it blank/malformed).
+ */
+export interface ProcessDefinitionIdentity {
   /** 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. */
+   *  `processDefinitionKey` → deployed XML path, no repo checkout). Unique per deployed version. */
   readonly processDefinitionKey?: string;
+  /** The BPMN process id (`<bpmn:process id>`) — stable across versions; the selector
+   *  {@link EngineClient.searchProcessInstances} accepts as `processDefinitionId`. */
+  readonly processDefinitionId?: string;
+  /** The deployed version of `processDefinitionId` this instance runs (1-based). */
+  readonly processDefinitionVersion?: number;
+}
+
+/** The instance {@link EngineClient.createInstance} started: its key, the exact deployed
+ *  definition version it runs, and — when `awaitCompletion` was requested — its final variables. */
+export interface CreatedProcessInstance extends ProcessDefinitionIdentity {
+  readonly processInstanceKey: string;
+  readonly variables?: Record<string, unknown>;
+}
+
+/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
+export interface ProcessInstanceSnapshot extends ProcessDefinitionIdentity {
+  readonly processInstanceKey: string;
+  readonly state: ProcessInstanceState;
   /** 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
@@ -741,12 +762,14 @@ export interface EngineClient {
   deployResources(
     resources: { name: string; content: string; contentType: string }[],
   ): Promise<{ deployed: number }>;
-  /** Start a process instance. */
+  /** Start a process instance of the latest deployed version of `processDefinitionId`. Returns
+   *  the new instance's key plus the {@link ProcessDefinitionIdentity} (key, id, version) of the
+   *  definition it actually runs. */
   createInstance(input: {
     processDefinitionId: string;
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
-  }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }>;
+  }): Promise<CreatedProcessInstance>;
   /** Cancel a running process instance (the pages surface's row-cancel action). */
   cancelInstance(input: { processInstanceKey: string }): Promise<void>;
   /** Publish a message for correlation. */
@@ -794,7 +817,8 @@ export interface EngineClient {
   /** Complete a user task. */
   completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
   /**
-   * Search process instances by key and/or lifecycle state. The instance-tracking
+   * Search process instances by key, BPMN process id (`processDefinitionId`, any version),
+   * and/or lifecycle state. The instance-tracking
    * reconciler uses this to detect a tracked instance reaching a terminal state
    * (`TERMINATED`/`COMPLETED`) even though no completion worker ran for it — the
    * read-model row it backs would otherwise stay "active" forever. An eventually
@@ -804,6 +828,9 @@ export interface EngineClient {
   searchProcessInstances(filter?: {
     processInstanceKeys?: string[];
     state?: ProcessInstanceState;
+    /** Select only instances of this BPMN process id (every deployed version). A blank or
+     *  whitespace-only value is treated as absent (no filter). */
+    processDefinitionId?: string;
     /** Select only instances whose *immediate* parent is this process instance — the reduced-path
      *  query for "the native children spawned by this subject". */
     parentProcessInstanceKey?: string;

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

@@ -617,6 +617,30 @@ test("the framework debug tools appear and return engine truth", async () => {
   assert.deepEqual(JSON.parse(text), [snapshot]);
 });
 
+test("urban_debug_search_process_instances forwards a processDefinitionId selector", async () => {
+  const seen: unknown[] = [];
+  const engine = fakeEngine({
+    searchProcessInstances: async (filter) => {
+      seen.push(filter);
+      return [];
+    },
+  });
+  const { router } = buildHarness({ engine });
+  const session = await connect(router);
+  const list = await rpc(router, session, "tools/list", {});
+  const tools = list.result?.tools;
+  assert.ok(Array.isArray(tools));
+  const tool = tools.find((t) => Reflect.get(t, "name") === "urban_debug_search_process_instances");
+  const props = Reflect.get(Reflect.get(tool ?? {}, "inputSchema") ?? {}, "properties");
+  assert.ok(props && typeof props === "object" && "processDefinitionId" in props);
+
+  await rpc(router, session, "tools/call", {
+    name: "urban_debug_search_process_instances",
+    arguments: { processDefinitionId: "order", state: "ACTIVE" },
+  });
+  assert.deepEqual(seen, [{ state: "ACTIVE", processDefinitionId: "order" }]);
+});
+
 test("urban_debug_search_variables / search_jobs / get_process_definition_xml are read tools returning engine truth", async () => {
   const variable = {
     variableKey: "v-1",

package/src/runtime/core/modules/mcp.ts

@@ -70,6 +70,7 @@ import type {
   HttpResponse,
   IncidentFilter,
   JobFilter,
+  EngineClient,
   ProcessInstanceState,
   SqliteDb,
   UserTaskFilter,
@@ -544,20 +545,24 @@ function buildDebugTools(app: AppApi): DebugTool[] {
   return [
     {
       name: `${DEBUG_PREFIX}search_process_instances`,
-      description: "Engine truth: search process instances by key and/or lifecycle state.",
+      description:
+        "Engine truth: search process instances by key, BPMN process id (processDefinitionId, any version), and/or lifecycle state.",
       inputSchema: {
         type: "object",
         properties: {
           processInstanceKeys: { type: "array", items: OPTIONAL_STRING },
+          processDefinitionId: OPTIONAL_STRING,
           state: { type: "string", enum: ["ACTIVE", "COMPLETED", "TERMINATED"] },
         },
       },
       run: (args) => {
-        const filter: { processInstanceKeys?: string[]; state?: ProcessInstanceState } = {};
+        const filter: NonNullable<Parameters<EngineClient["searchProcessInstances"]>[0]> = {};
         const keys = readStringArray(args, "processInstanceKeys");
         if (keys) filter.processInstanceKeys = keys;
         const state = readProcessInstanceState(args, "state");
         if (state) filter.state = state;
+        const processDefinitionId = readPresentString(args, "processDefinitionId");
+        if (processDefinitionId) filter.processDefinitionId = processDefinitionId;
         return app.engine.searchProcessInstances(filter);
       },
     },

package/src/runtime/core/process-identity.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  pickProcessDefinitionIdentity,
+  presentEngineKey,
+  presentString,
+} from "./process-identity.ts";
+
+// The canonical, adapter-agnostic process-definition-identity normalizer. These cases pin the
+// class the shared helper exists to keep consistent (No Drift Surfaces): a padded/numeric key is
+// normalized, a blank/whitespace/non-string/non-finite value is *absent* and never coerced, and a
+// version is kept only when a positive integer number. Scope today: only the SDK adapter
+// (`engine/nanosdk.ts`) routes through this mapping; the WASM test adapter
+// (`@nanobpm/urban-testkit`) runs a deliberately mirrored local copy until #585, pinned to this
+// behaviour by its own identity cases (`wasm-engine.test.ts`).
+
+test("presentEngineKey coerces a finite numeric key, trims a string, and drops blank/non-finite/non-string", () => {
+  assert.equal(presentEngineKey(7), "7");
+  assert.equal(presentEngineKey(" order "), "order");
+  assert.equal(presentEngineKey("   "), undefined);
+  assert.equal(presentEngineKey(""), undefined);
+  assert.equal(presentEngineKey(Number.NaN), undefined);
+  assert.equal(presentEngineKey(Number.POSITIVE_INFINITY), undefined);
+  assert.equal(presentEngineKey({}), undefined);
+  assert.equal(presentEngineKey(null), undefined);
+  assert.equal(presentEngineKey(undefined), undefined);
+});
+
+test("presentString keeps a trimmed non-empty string and drops blank/non-string (never coerces)", () => {
+  assert.equal(presentString(" human "), "human");
+  assert.equal(presentString("   "), undefined);
+  assert.equal(presentString(""), undefined);
+  // A number id is absent — never String(...)-coerced into a garbage id.
+  assert.equal(presentString(5), undefined);
+  assert.equal(presentString({}), undefined);
+  assert.equal(presentString(undefined), undefined);
+});
+
+test("pickProcessDefinitionIdentity normalizes present fields and omits blank/malformed ones", () => {
+  assert.deepEqual(
+    pickProcessDefinitionIdentity({
+      processDefinitionKey: 7,
+      processDefinitionId: " order ",
+      processDefinitionVersion: 2,
+    }),
+    { processDefinitionKey: "7", processDefinitionId: "order", processDefinitionVersion: 2 },
+  );
+});
+
+test("pickProcessDefinitionIdentity drops a blank key, a non-string id, and a stringly version", () => {
+  assert.deepEqual(
+    pickProcessDefinitionIdentity({
+      processDefinitionKey: "  ",
+      processDefinitionId: 5,
+      processDefinitionVersion: "2",
+    }),
+    {},
+  );
+});
+
+test("pickProcessDefinitionIdentity keeps a version only when a positive integer number", () => {
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: 1.5 }), {});
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: 0 }), {});
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: -1 }), {});
+  assert.deepEqual(pickProcessDefinitionIdentity({ processDefinitionVersion: 3 }), {
+    processDefinitionVersion: 3,
+  });
+});
+
+test("pickProcessDefinitionIdentity on an empty row returns an empty identity (fully absent)", () => {
+  assert.deepEqual(pickProcessDefinitionIdentity({}), {});
+});

package/src/runtime/core/process-identity.ts

@@ -0,0 +1,66 @@
+// The single, transport-agnostic normalizer for a {@link ProcessDefinitionIdentity}. Both engine
+// adapters — the live SDK/REST adapter (`engine/nanosdk.ts`, `SdkEngineClient`) and the in-process
+// WASM test adapter (`@nanobpm/urban-testkit`, `WasmEngineClient`) — report which deployed
+// definition an instance runs on *both* `createInstance` and `searchProcessInstances`. Each used to
+// carry its own hand-mirrored `pickProcessDefinitionIdentity` (plus a re-declared identity type), so
+// the two could silently diverge the moment identity validation changed — exactly the drift class
+// the shared form-contract normalizer exists to kill (`./form-contract.ts`, issue #252). Centralizing
+// the mapper (and reusing the canonical {@link ProcessDefinitionIdentity}) here removes that surface:
+// a created instance and its later snapshot describe the same definition identically wherever this
+// normalizer runs, because they run the *same* code.
+//
+// Ownership today: only the SDK adapter runs this implementation. `WasmEngineClient` still defines
+// and calls its own behaviourally identical copy (`urban-testkit/src/wasm-engine.ts`) — a deliberate,
+// temporary fork: this module is introduced by the same change, so it exists in no published urban
+// release, and a value import would force the testkit's peer floor up to an urban version that does
+// not yet exist (AGENTS.md: depend on an unreleased sibling only after it is published). Follow-up
+// #585 switches the WASM adapter to this canonical import once the urban release carrying it is
+// published; until then the testkit's own identity cases pin its copy to this normalizer's behaviour.
+
+import type { ProcessDefinitionIdentity } from "./host.ts";
+
+export type { ProcessDefinitionIdentity };
+
+/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
+ *  whitespace-only string). Coerces a *finite* 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, nor a non-finite number into `"NaN"`/`"Infinity"`. The blank check trims,
+ *  matching the read-path blank-key guards, so a `"   "` key can never leak into a result. */
+export function presentEngineKey(value: unknown): string | undefined {
+  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 present string-only identifier (e.g. a BPMN process id) under the shared trim rule; a
+ *  non-string is absent and never `String(...)`-coerced. */
+export function presentString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** The {@link ProcessDefinitionIdentity} an engine row (a create response or a process-instance
+ *  search row) reports — the single mapping both `createInstance` and `searchProcessInstances` use,
+ *  so a created instance and its later snapshot describe the same definition identically. Each field
+ *  passes the shared presence rule; a version that is not a positive integer number is omitted
+ *  (never coerced). */
+export function pickProcessDefinitionIdentity(row: {
+  processDefinitionKey?: unknown;
+  processDefinitionId?: unknown;
+  processDefinitionVersion?: unknown;
+}): ProcessDefinitionIdentity {
+  const processDefinitionKey = presentEngineKey(row.processDefinitionKey);
+  const processDefinitionId = presentString(row.processDefinitionId);
+  const version = row.processDefinitionVersion;
+  const processDefinitionVersion =
+    typeof version === "number" && Number.isInteger(version) && version > 0 ? version : undefined;
+  return {
+    ...(processDefinitionKey ? { processDefinitionKey } : {}),
+    ...(processDefinitionId ? { processDefinitionId } : {}),
+    ...(processDefinitionVersion !== undefined ? { processDefinitionVersion } : {}),
+  };
+}

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

@@ -200,6 +200,43 @@ test("createInstance routes through the SDK and coerces the key", async () => {
   assert.ok(client.calls.includes("createProcessInstance"));
 });
 
+test("createInstance returns the started definition's identity (key, id, version)", async () => {
+  // The create response names exactly which deployed definition version the instance runs; the
+  // seam must surface it (normalized through the same presence rule as the search snapshot) so a
+  // caller need not race an eventually consistent search to learn it.
+  const client = fakeSdkClient({
+    createProcessInstance: async () => ({
+      processInstanceKey: 99,
+      processDefinitionKey: 2251799813685249,
+      processDefinitionId: " order ",
+      processDefinitionVersion: 3,
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const res = await engine.createInstance({ processDefinitionId: "order" });
+  assert.deepEqual(res, {
+    processInstanceKey: "99",
+    processDefinitionKey: "2251799813685249",
+    processDefinitionId: "order",
+    processDefinitionVersion: 3,
+    variables: undefined,
+  });
+});
+
+test("createInstance omits definition identity fields the engine leaves blank or malformed", async () => {
+  const client = fakeSdkClient({
+    createProcessInstance: async () => ({
+      processInstanceKey: "99",
+      processDefinitionKey: "  ",
+      processDefinitionId: "",
+      processDefinitionVersion: "3", // not a number → omitted, never coerced
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const res = await engine.createInstance({ processDefinitionId: "order" });
+  assert.deepEqual(res, { processInstanceKey: "99", variables: undefined });
+});
+
 test("createInstance throws when the SDK response omits the instance key", async () => {
   const client = fakeSdkClient({
     createProcessInstance: async () => ({ variables: { ok: true } }),
@@ -622,6 +659,51 @@ test("searchProcessInstances surfaces the parent/root linkage keys and drops bla
   ]);
 });
 
+test("searchProcessInstances forwards a processDefinitionId selector (trimmed, blank dropped)", async () => {
+  const seen: unknown[] = [];
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input) => {
+      seen.push(input);
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchProcessInstances({ processDefinitionId: " order ", state: "ACTIVE" });
+  await engine.searchProcessInstances({ processDefinitionId: "   " });
+  assert.deepEqual(seen, [
+    { filter: { state: "ACTIVE", processDefinitionId: "order" } },
+    { filter: {} },
+  ]);
+});
+
+test("searchProcessInstances surfaces each instance's definition identity", async () => {
+  const client = fakeSdkClient({
+    searchProcessInstances: async () => ({
+      items: [
+        {
+          processInstanceKey: 10,
+          state: "ACTIVE",
+          processDefinitionKey: 5,
+          processDefinitionId: "order",
+          processDefinitionVersion: 2,
+        },
+        { processInstanceKey: 11, state: "ACTIVE", processDefinitionId: " ", processDefinitionVersion: null },
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  assert.deepEqual(await engine.searchProcessInstances(), [
+    {
+      processInstanceKey: "10",
+      state: "ACTIVE",
+      processDefinitionKey: "5",
+      processDefinitionId: "order",
+      processDefinitionVersion: 2,
+    },
+    { processInstanceKey: "11", state: "ACTIVE" },
+  ]);
+});
+
 test("normalizeProcessInstanceState maps the terminal set and rejects others", () => {
   assert.equal(normalizeProcessInstanceState("ACTIVE"), "ACTIVE");
   assert.equal(normalizeProcessInstanceState("completed"), "COMPLETED");

package/src/runtime/engine/nanosdk.ts

@@ -32,6 +32,7 @@ import type {
   JobFilter,
   JobHandler,
   JobSummary,
+  CreatedProcessInstance,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
   UserTaskState,
@@ -49,6 +50,11 @@ import type {
   TranscriptTurnRole,
 } from "@nanobpm/agentic/transcript";
 import { assertDeployedWaitStateType, isBpmnError } from "../core/host.ts";
+import {
+  pickProcessDefinitionIdentity,
+  presentEngineKey,
+  presentString,
+} from "../core/process-identity.ts";
 import {
   buildFormSchema,
   parseFormSchema,
@@ -153,19 +159,11 @@ export function normalizeIncidentState(raw: unknown): IncidentState {
   }
 }
 
-/** 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: unknown): string | undefined {
-  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;
-}
+// Engine-key / process-definition-identity normalization now lives in the shared, adapter-agnostic
+// `../core/process-identity.ts` (imported above), so this adapter's `createInstance` and
+// `searchProcessInstances` run the *same* mapping — see that module's header for the drift class
+// this removes. The WASM test adapter keeps a mirrored local copy until #585 (that module header's
+// "Ownership today" note), so the shared mapping is not yet a cross-adapter guarantee.
 
 /** The non-empty, trimmed string form of a *required* engine key, or throws when the value is
  *  absent/blank (including a whitespace-only string). A mutating seam operation addresses a
@@ -858,7 +856,7 @@ export class SdkEngineClient implements EngineClient {
     processDefinitionId: string;
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
-  }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }> {
+  }): Promise<CreatedProcessInstance> {
     // Auto-thread the `_urban.lineage` envelope (issue #254): a handler that spawns an
     // instance propagates its `rootRequestKey` and stamps `causedByInstanceKey`; a genuine
     // top-level request mints a fresh root. An explicit caller-supplied envelope wins.
@@ -873,6 +871,7 @@ export class SdkEngineClient implements EngineClient {
     const variables = isRecord(body.variables) ? body.variables : undefined;
     return {
       processInstanceKey: requireProcessInstanceKey(key),
+      ...pickProcessDefinitionIdentity(body),
       variables,
     };
   }
@@ -1003,11 +1002,15 @@ export class SdkEngineClient implements EngineClient {
   async searchProcessInstances(filter?: {
     processInstanceKeys?: string[];
     state?: ProcessInstanceState;
+    processDefinitionId?: string;
     parentProcessInstanceKey?: string;
     rootProcessInstanceKey?: string;
   }): Promise<ProcessInstanceSnapshot[]> {
     const f: Record<string, unknown> = {};
     if (filter?.state) f.state = filter.state;
+    // A blank BPMN process-id selector is absent, not an empty filter that matches nothing.
+    const processDefinitionId = presentString(filter?.processDefinitionId);
+    if (processDefinitionId) f.processDefinitionId = processDefinitionId;
     // 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
@@ -1051,13 +1054,12 @@ export class SdkEngineClient implements EngineClient {
         });
         return [];
       }
-      const processDefinitionKey = presentEngineKey(it.processDefinitionKey);
       const parentProcessInstanceKey = presentEngineKey(it.parentProcessInstanceKey);
       const rootProcessInstanceKey = presentEngineKey(it.rootProcessInstanceKey);
       return [{
         processInstanceKey,
         state,
-        ...(processDefinitionKey ? { processDefinitionKey } : {}),
+        ...pickProcessDefinitionIdentity(it),
         ...(parentProcessInstanceKey ? { parentProcessInstanceKey } : {}),
         ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
       }];

package/src/runtime/index.ts

@@ -108,6 +108,8 @@ export type {
   JobFilter,
   JobHandler,
   JobSummary,
+  CreatedProcessInstance,
+  ProcessDefinitionIdentity,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
   SqliteDb,
@@ -140,6 +142,15 @@ export {
   presentFormIdentifier,
   resolveFormIdentifier,
 } from "./core/form-contract.ts";
+// The adapter-agnostic process-definition-identity normalizer (the single mapping both
+// `createInstance` and `searchProcessInstances` use), owned today by the live SDK adapter; the WASM
+// test adapter keeps a mirrored local copy until #585, so cross-adapter drift-freedom is not yet
+// claimed. `ProcessDefinitionIdentity` itself is re-exported from `./core/host.ts`.
+export {
+  pickProcessDefinitionIdentity,
+  presentEngineKey,
+  presentString,
+} from "./core/process-identity.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 // Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
 // so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).