@nanobpm/urban 0.89.0 → 0.90.0

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

@@ -202,6 +202,18 @@ export interface ProcessInstanceSnapshot {
      *  {@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
@@ -219,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,
@@ -230,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
@@ -582,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

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

@@ -236,6 +236,8 @@ 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[]>;

package/dist/runtime/engine/nanosdk.js

@@ -465,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;
@@ -476,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),
                 }];
         });
@@ -545,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
@@ -556,24 +590,32 @@ 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 [];
             }
             const processDefinitionKey = presentEngineKey(it.processDefinitionKey);
+            const parentProcessInstanceKey = presentEngineKey(it.parentProcessInstanceKey);
+            const rootProcessInstanceKey = presentEngineKey(it.rootProcessInstanceKey);
             return [{
-                    processInstanceKey: String(key),
+                    processInstanceKey,
                     state,
                     ...(processDefinitionKey ? { processDefinitionKey } : {}),
+                    ...(parentProcessInstanceKey ? { parentProcessInstanceKey } : {}),
+                    ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
                 }];
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.89.0",
+	"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",

package/src/runtime/core/host.ts

@@ -233,6 +233,18 @@ export interface ProcessInstanceSnapshot {
    *  {@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;
 }
 
 /**
@@ -251,6 +263,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;
 }
 
 /**
@@ -263,6 +293,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;
 }
 
 /**
@@ -636,6 +674,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

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

@@ -315,6 +315,72 @@ test("searchUserTasks surfaces the resolved form linkage", async () => {
   ]);
 });
 
+test("searchUserTasks normalizes the process-instance key selectors and drops blank ones", async () => {
+  // Guards the selector-normalization defect class: a padded selector (`" 42 "`) must reach the
+  // engine trimmed (so it matches the normalized keys the adapter surfaces), a blank/whitespace-only
+  // selector must be *dropped* (not forwarded as a present filter that silently matches nothing),
+  // and unrelated selectors must pass through untouched — mirroring `searchProcessInstances`.
+  let input: { filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    searchUserTasks: async (i) => {
+      input = i;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchUserTasks({
+    processInstanceKey: " 42 ", // padded → trimmed to "42"
+    parentProcessInstanceKey: "   ", // whitespace-only → dropped
+    rootProcessInstanceKey: "", // blank → dropped
+    assignee: "alice", // unrelated selector passes through unchanged
+  });
+  const filter = input?.filter ?? {};
+  assert.equal(filter.processInstanceKey, "42", "padded key selector is trimmed");
+  assert.equal("parentProcessInstanceKey" in filter, false, "whitespace-only parent selector is dropped");
+  assert.equal("rootProcessInstanceKey" in filter, false, "blank root selector is dropped");
+  assert.equal(filter.assignee, "alice", "unrelated selectors pass through unchanged");
+});
+
+test("searchUserTasks surfaces the process-instance linkage keys and drops blank ones", async () => {
+  // Guards the linkage-output defect class: the three linkage keys the engine reports on a task
+  // (processInstanceKey/parentProcessInstanceKey/rootProcessInstanceKey) must be surfaced on the
+  // returned `UserTaskSummary`, normalized through the same presence rule — a padded value trimmed,
+  // a blank/whitespace-only value omitted rather than surfaced as an empty string.
+  const client = fakeSdkClient({
+    searchUserTasks: async () => ({
+      items: [
+        {
+          userTaskKey: 1,
+          elementId: "a",
+          processInstanceKey: 10,
+          parentProcessInstanceKey: 20,
+          rootProcessInstanceKey: 30,
+        },
+        {
+          userTaskKey: 2,
+          elementId: "b",
+          processInstanceKey: " 11 ", // padded → trimmed
+          parentProcessInstanceKey: "  ", // whitespace-only → omitted
+          rootProcessInstanceKey: "", // blank → omitted
+        },
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const tasks = await engine.searchUserTasks();
+  assert.deepEqual(tasks, [
+    {
+      userTaskKey: "1",
+      elementId: "a",
+      variables: undefined,
+      processInstanceKey: "10",
+      parentProcessInstanceKey: "20",
+      rootProcessInstanceKey: "30",
+    },
+    { userTaskKey: "2", elementId: "b", variables: undefined, processInstanceKey: "11" },
+  ]);
+});
+
 test("getForm resolves by formKey and parses the serialized schema", async () => {
   let seen: unknown;
   const schema = { type: "default", schemaVersion: 18, components: [{ type: "textfield", key: "name" }] };
@@ -486,6 +552,64 @@ test("searchProcessInstances skips keyless and unrecognized-state rows", async (
   assert.deepEqual(out, [{ processInstanceKey: "10", state: "COMPLETED" }]);
 });
 
+test("searchProcessInstances normalizes the parent/root key selectors and drops blank ones", async () => {
+  // Guards the request-mapping defect class for the reduced path's parent/root selectors: a padded
+  // selector must be trimmed, a blank/whitespace-only selector must be dropped rather than sent as
+  // an empty filter that matches nothing — mirroring `searchUserTasks` (No Drift Surfaces).
+  let seenInput: { filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    searchProcessInstances: async (input) => {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.searchProcessInstances({
+    parentProcessInstanceKey: " 42 ", // padded → trimmed to "42"
+    rootProcessInstanceKey: "   ", // whitespace-only → dropped
+  });
+  const filter = seenInput?.filter ?? {};
+  assert.equal(filter.parentProcessInstanceKey, "42", "padded parent selector is trimmed");
+  assert.equal("rootProcessInstanceKey" in filter, false, "whitespace-only root selector is dropped");
+  // A selector-only search carries no key `$in` and no page cap.
+  assert.deepEqual(seenInput, { filter: { parentProcessInstanceKey: "42" } });
+});
+
+test("searchProcessInstances surfaces the parent/root linkage keys and drops blank ones", async () => {
+  // Guards the linkage-output defect class: the parent/root keys the engine reports on an instance
+  // must be surfaced on the returned `ProcessInstanceSnapshot`, normalized through the same presence
+  // rule — a padded value trimmed, a blank/whitespace-only value omitted rather than an empty string.
+  const client = fakeSdkClient({
+    searchProcessInstances: async () => ({
+      items: [
+        {
+          processInstanceKey: 10,
+          state: "ACTIVE",
+          parentProcessInstanceKey: 20,
+          rootProcessInstanceKey: 30,
+        },
+        {
+          processInstanceKey: " 11 ", // padded → trimmed
+          state: "COMPLETED",
+          parentProcessInstanceKey: "  ", // whitespace-only → omitted
+          rootProcessInstanceKey: "", // blank → omitted
+        },
+      ],
+    }),
+  });
+  const engine = new SdkEngineClient(client);
+  const out = await engine.searchProcessInstances();
+  assert.deepEqual(out, [
+    {
+      processInstanceKey: "10",
+      state: "ACTIVE",
+      parentProcessInstanceKey: "20",
+      rootProcessInstanceKey: "30",
+    },
+    { processInstanceKey: "11", state: "COMPLETED" },
+  ]);
+});
+
 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

@@ -677,8 +677,19 @@ export class SdkEngineClient implements EngineClient {
   }): Promise<UserTaskSummary[]> {
     // User tasks are an eventually consistent read; ask for zero-wait consistency so
     // the search reflects what is currently visible without blocking.
+    // 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: Record<string, unknown> = { ...(filter ?? {}) };
+    for (const sel of ["processInstanceKey", "parentProcessInstanceKey", "rootProcessInstanceKey"] as const) {
+      const normalized = presentEngineKey(filter?.[sel]);
+      if (normalized) f[sel] = normalized;
+      else delete f[sel];
+    }
     const body = await this.client.searchUserTasks(
-      { filter: { ...(filter ?? {}) } },
+      { filter: f },
       { consistency: { waitUpToMs: 0 } },
     );
     const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
@@ -691,10 +702,16 @@ export class SdkEngineClient implements EngineClient {
       // 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),
       }];
     });
@@ -763,11 +780,26 @@ export class SdkEngineClient implements EngineClient {
   async searchProcessInstances(filter?: {
     processInstanceKeys?: string[];
     state?: ProcessInstanceState;
+    parentProcessInstanceKey?: string;
+    rootProcessInstanceKey?: string;
   }): Promise<ProcessInstanceSnapshot[]> {
     const f: Record<string, unknown> = {};
     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 is string => 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
@@ -779,24 +811,32 @@ export class SdkEngineClient implements EngineClient {
     );
     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 [];
       }
       const processDefinitionKey = presentEngineKey(it.processDefinitionKey);
+      const parentProcessInstanceKey = presentEngineKey(it.parentProcessInstanceKey);
+      const rootProcessInstanceKey = presentEngineKey(it.rootProcessInstanceKey);
       return [{
-        processInstanceKey: String(key),
+        processInstanceKey,
         state,
         ...(processDefinitionKey ? { processDefinitionKey } : {}),
+        ...(parentProcessInstanceKey ? { parentProcessInstanceKey } : {}),
+        ...(rootProcessInstanceKey ? { rootProcessInstanceKey } : {}),
       }];
     });
   }