@nanobpm/nano-workforce 0.140.0 → 0.142.0

package/app/agentic/element-instance.ts

@@ -0,0 +1,97 @@
+// nano-workforce — resolve an agent job's ENGINE ELEMENT-INSTANCE KEY from its jobKey (#544).
+//
+// The durable correlation store (`./correlation-store.ts`) has historically keyed an agent session's
+// engine context on the STATIC BPMN `element_id`. That id is ambiguous across a looping / retried
+// activity: every re-activation of the same task id is a DISTINCT element instance sharing one id, so
+// a transcript keyed on `element_id` alone cannot say WHICH occupancy produced it. #544 keys on the
+// engine's per-occupancy handle instead — the `elementInstanceKey` — which is exactly what Nano
+// Explorer addresses runtime position by and what Camunda keys its agent model on.
+//
+// The engine does not offer a `getJob(jobKey)` lookup, but it DOES surface every parked element
+// instance via the element-instance wait-state read (`POST /v2/element-instances/wait-states/search`,
+// bound onto the `@nanobpm/urban` EngineClient by nano-ide#473). A service task awaiting a worker is a
+// `JOB` park, and that park carries BOTH its `jobKey` AND its owning `elementInstanceKey`. So the join
+// is: list the live JOB parks, find the one whose `jobKey` matches the agent job, and read off its
+// `elementInstanceKey`. Because a park is keyed to a specific element instance, this is unambiguous
+// even when many iterations of the same static element are (or have been) live — each iteration is a
+// separate park with a separate jobKey (see the looping/retried-job test).
+//
+// Invariant fit (ADR 0056): this is an ADVISORY, READ-ONLY engine query — it observes the engine's
+// read model to enrich a visibility record. It NEVER activates/completes a job, publishes a message,
+// or gates a BPMN sequence flow; the Camunda-8 job protocol (worker⇄engine) is untouched. It is
+// deliberately expressed against a narrow reader shape (not the whole EngineClient) so the callers
+// that drive it stay structurally decoupled from the engine.
+import type { ElementInstanceWaitState, ElementInstanceWaitStateFilter } from "@nanobpm/urban";
+
+/**
+ * The narrow slice of the engine read model this resolver needs: the element-instance wait-state
+ * search. `@nanobpm/urban`'s `EngineClient` satisfies it structurally; a test supplies a fake.
+ */
+export interface ElementInstanceWaitStateReader {
+  searchElementInstanceWaitStates(
+    filter?: ElementInstanceWaitStateFilter,
+  ): Promise<readonly ElementInstanceWaitState[]>;
+}
+
+/** Optional scoping for {@link resolveElementInstanceKey} (a performance narrowing, never required). */
+export interface ResolveElementInstanceOptions {
+  /**
+   * The owning process instance, when the caller already knows it. Passed to the engine as a search
+   * filter so the read is scoped to one process instance rather than every live JOB park. It is a pure
+   * OPTIMISATION: the `jobKey` is the match key and is engine-unique, so an unscoped search resolves
+   * the same element instance — just over a larger candidate set.
+   */
+  readonly processInstanceKey?: string;
+}
+
+/**
+ * Resolve the `elementInstanceKey` the agent job identified by `jobKey` occupies, by matching the
+ * job against the engine's live `JOB` wait-state parks. Returns `undefined` when the job is not (or no
+ * longer) parked — e.g. it already completed and released its park, or the jobKey is empty — which the
+ * advisory callers treat as "not resolved", never an error.
+ *
+ * The resolution keys on `jobKey`, NOT `elementId`: that is the whole point of #544. A retried /
+ * looping activity has many parks sharing one `elementId` but each with its own `jobKey` and its own
+ * `elementInstanceKey`, so matching on `jobKey` returns the correct per-occupancy instance.
+ */
+export async function resolveElementInstanceKey(
+  reader: ElementInstanceWaitStateReader,
+  jobKey: string,
+  options: ResolveElementInstanceOptions = {},
+): Promise<string | undefined> {
+  if (jobKey === "") return undefined;
+  const filter: ElementInstanceWaitStateFilter = { waitStateType: "JOB" };
+  if (options.processInstanceKey !== undefined && options.processInstanceKey !== "") {
+    filter.processInstanceKey = options.processInstanceKey;
+  }
+  const parks = await reader.searchElementInstanceWaitStates(filter);
+  for (const park of parks) {
+    // Narrow to the JOB variant (the discriminant guards `jobKey`); a non-JOB park never carries the
+    // jobKey field even if the engine ignored the filter. Match on the engine-unique jobKey.
+    if (park.waitStateType === "JOB" && park.jobKey === jobKey) {
+      return park.elementInstanceKey;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The narrow, advisory element-instance resolution seam the relay slice fires at link time (#544):
+ * given an agent `jobKey` (and its owning `processInstanceKey` when known), resolve the engine
+ * element-instance key it occupies, or `undefined` when it is not resolvable. A function shape — NOT
+ * an `EngineClient` — so the agentic families depend on a capability, not the engine itself; the
+ * composition root ({@link file://main.ts}) closes it over the real engine, a test over a fake.
+ */
+export type ElementInstanceResolver = (
+  jobKey: string,
+  processInstanceKey?: string,
+) => Promise<string | undefined>;
+
+/**
+ * Build an {@link ElementInstanceResolver} bound to an engine wait-state reader — the closure the
+ * composition root threads into the agentic channel so the relay slice can resolve an agent job's
+ * element instance without holding an engine reference of its own.
+ */
+export function makeElementInstanceResolver(reader: ElementInstanceWaitStateReader): ElementInstanceResolver {
+  return (jobKey, processInstanceKey) => resolveElementInstanceKey(reader, jobKey, { processInstanceKey });
+}

package/app/agentic/families/relay.family.test.ts

@@ -134,6 +134,12 @@ function mkService(registry: ConnectionRegistry, db: SqliteDb | undefined): {
   return { service, hub };
 }
 
+/** Flush the microtask/macrotask queue so a fire-and-forget promise chain (the async #544 element-
+ * instance resolution) settles before the test asserts on its effects. */
+function tick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
 /** Build a service with the H6 correlation write-side wired (a real registry + a connection→instance map). */
 function mkCorrelatedService(
   registry: ConnectionRegistry,
@@ -143,6 +149,7 @@ function mkCorrelatedService(
   extra: {
     attributionForInstance?: (instance: string) => { identity?: string; host?: string } | undefined;
     correlationStore?: AgenticCorrelationStore;
+    resolveElementInstance?: (jobKey: string, processInstanceKey?: string) => Promise<string | undefined>;
     now?: () => string;
   } = {},
 ): { service: RelayTranscriptService; hub: CapturingHub } {
@@ -156,6 +163,7 @@ function mkCorrelatedService(
     instanceForConnection: (id) => byConnection.get(id),
     attributionForInstance: extra.attributionForInstance,
     correlationStore: extra.correlationStore,
+    resolveElementInstance: extra.resolveElementInstance,
     now: extra.now,
   });
   return { service, hub };
@@ -452,6 +460,88 @@ test("H6 durable attribution: completing/superseding a job persists the worker's
   service.teardown();
 });
 
+test("#544 element-instance enrichment: link-time resolution keys the completed session on the element instance", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const db = memoryDb();
+  const store = new AgenticCorrelationStore(db);
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // The engine resolves job k1's live JOB park to element instance ei-1 (resolution wins the race,
+  // i.e. it returns while the job is still live — the common case for a long-lived agent job).
+  const resolveElementInstance = (jobKey: string) =>
+    Promise.resolve(jobKey === "k1" ? "ei-1" : undefined);
+  const { service, hub } = mkCorrelatedService(registry, db, correlation, byConnection, {
+    correlationStore: store,
+    resolveElementInstance,
+    now: () => "2024-01-02T03:04:05.000Z",
+  });
+  const p = connect("prod", registry);
+
+  // First produce links the job and fires the (async) element-instance resolution.
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  await tick();
+  // The live correlation context is enriched while the job runs.
+  assertEquals(correlation.resolve("k1")?.elementInstanceKey, "ei-1", "the live context carries the element instance");
+
+  // Superseding with a new job completes k1 → its attribution persists WITH the element-instance key.
+  hub.handler?.(produce(jobStream("k2"), 1, "job-2 line"), p.conn);
+  const durable = store.get("k1");
+  assertEquals(durable?.elementInstanceKey, "ei-1", "the completed session is keyed on the element instance");
+  service.teardown();
+});
+
+test("#544 element-instance enrichment: a resolution that lands AFTER completion backfills the durable row", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const db = memoryDb();
+  const store = new AgenticCorrelationStore(db);
+  const byConnection = new Map([["prod", "worker-A"]]);
+  // A deferred resolution the test releases MANUALLY, to force the race where the element-instance
+  // key arrives only after the job already completed and released its live correlation.
+  let release: (key: string | undefined) => void = () => {};
+  const pending = new Promise<string | undefined>((resolve) => {
+    release = resolve;
+  });
+  const { service, hub } = mkCorrelatedService(registry, db, correlation, byConnection, {
+    correlationStore: store,
+    resolveElementInstance: () => pending,
+  });
+  const p = connect("prod", registry);
+
+  // Link job k1 (fires the still-pending resolution), then supersede it → k1 completes and persists
+  // its attribution BEFORE the element instance is known.
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  hub.handler?.(produce(jobStream("k2"), 1, "job-2 line"), p.conn);
+  assertEquals(store.get("k1")?.elementInstanceKey, undefined, "persisted before the element instance resolved");
+  assertEquals(correlation.resolve("k1"), undefined, "k1's live correlation was already released");
+
+  // The resolution finally lands — it backfills the durable row directly (the live context is gone).
+  release("ei-late");
+  await tick();
+  assertEquals(store.get("k1")?.elementInstanceKey, "ei-late", "the durable row is backfilled after the fact");
+  service.teardown();
+});
+
+test("#544 element-instance enrichment: an unresolved job (never parked) leaves the session un-keyed, not erroring", async () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const db = memoryDb();
+  const store = new AgenticCorrelationStore(db);
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, db, correlation, byConnection, {
+    correlationStore: store,
+    resolveElementInstance: () => Promise.resolve(undefined),
+  });
+  const p = connect("prod", registry);
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  await tick();
+  hub.handler?.(produce(jobStream("k2"), 1, "job-2 line"), p.conn);
+  const durable = store.get("k1");
+  assert(durable !== undefined, "the session is still attributed");
+  assertEquals(durable?.elementInstanceKey, undefined, "no element-instance key when the job was not resolvable");
+  service.teardown();
+});
+
 /**
  * A {@link CorrelationLink} wrapper that delegates to a real registry but can be flipped to throw on
  * `link()`/`releaseJob()`, exercising the advisory-resilience contract: `#link`/`#unlink` are

package/app/agentic/families/relay.family.ts

@@ -35,6 +35,7 @@ import {
 import type { Logger } from "@nanobpm/urban";
 import { currentCorrelation, type JobContext, type JobCorrelation, jobKeyOfStream } from "../correlation.ts";
 import { AgenticCorrelationStore } from "../correlation-store.ts";
+import type { ElementInstanceResolver } from "../element-instance.ts";
 import type { AgenticContext, AgenticFamily } from "../registry.ts";
 import { currentPresenceRegistry } from "./presence.family.ts";
 
@@ -105,6 +106,13 @@ interface StreamState {
    * instance's prior job stream.
    */
   instance?: string;
+  /**
+   * The engine element-instance key this `job:<jobKey>` stream's job occupies (#544), once the
+   * asynchronous link-time resolution ({@link RelayTranscriptService.#resolveElementInstance}) lands.
+   * Stashed on the stream so job completion can persist it even if the live correlation was already
+   * enriched-and-released, and so a resolution that returns after completion can still be recognised.
+   */
+  elementInstanceKey?: string;
 }
 
 /**
@@ -115,6 +123,12 @@ interface StreamState {
 export interface CorrelationLink {
   link(instance: string, jobKey: string, context?: JobContext): void;
   releaseJob(jobKey: string): void;
+  /**
+   * Enrich a still-linked job's context with the engine element-instance key it occupies (#544),
+   * resolved asynchronously after the link. Optional so the minimal double in tests need not implement
+   * it; the real {@link CorrelationRegistry} does. A no-op once the job is released.
+   */
+  attachElementInstance?(jobKey: string, elementInstanceKey: string): void;
   /**
    * The (still-live) engine context for a jobKey, when the write-side exposes it. Optional so the
    * minimal double in tests need not implement it; the real {@link CorrelationRegistry} does, and the
@@ -178,6 +192,15 @@ export interface RelayTranscriptServiceOptions {
    * no durable attribution). Injectable so a test can supply an in-memory store.
    */
   readonly correlationStore?: AgenticCorrelationStore;
+  /**
+   * Resolve the engine element-instance key a `job:<jobKey>` stream's job occupies (#544). Called
+   * fire-and-forget on the first `produce` (while the job's JOB park is still live), and its result
+   * enriches the live correlation context / durable attribution so a captured session is keyed on the
+   * element INSTANCE (unambiguous across a looping / retried job), not just the static element id.
+   * Advisory and READ-ONLY — never awaited in a frame handler, never gates a flow. {@link createRelayFamily}
+   * wires it to the channel's {@link AgenticContext.resolveElementInstance}; omitted → no enrichment.
+   */
+  readonly resolveElementInstance?: ElementInstanceResolver;
   /** "Now" as an ISO-8601 instant, injectable for deterministic completion timestamps. */
   readonly now?: () => string;
 }
@@ -226,6 +249,8 @@ export class RelayTranscriptService {
   readonly #attributionForInstance: (instance: string) => WorkerAttribution | undefined;
   /** The durable worker-attribution store, or undefined when unpersisted (#485). */
   readonly #correlationStore: AgenticCorrelationStore | undefined;
+  /** Resolve the engine element-instance key a job occupies (#544), or undefined when not wired. */
+  readonly #resolveElementInstance: ElementInstanceResolver | undefined;
   /** "Now" as an ISO-8601 instant (injectable for deterministic tests). */
   readonly #now: () => string;
 
@@ -235,6 +260,7 @@ export class RelayTranscriptService {
     this.#correlation = options.correlation ?? currentCorrelation;
     this.#instanceForConnection = options.instanceForConnection ?? (() => undefined);
     this.#attributionForInstance = options.attributionForInstance ?? (() => undefined);
+    this.#resolveElementInstance = options.resolveElementInstance;
     this.#now = options.now ?? (() => new Date().toISOString());
     // Persistence is advisory: a store that can't be constructed or whose schema can't be applied
     // (locked/permission-denied/unavailable SQLite) must NOT fail the family mount — fall back to
@@ -448,6 +474,10 @@ export class RelayTranscriptService {
       state.linked = true;
       state.instance = instance;
       this.#jobStreamByInstance.set(instance, stream);
+      // #544: resolve the element INSTANCE this job occupies while its JOB park is still live (the
+      // park is gone once the job completes, so this must fire at link time, not completion time).
+      // Advisory and asynchronous — fire-and-forget so it never blocks the synchronous frame handler.
+      this.#enrichElementInstance(stream, jobKey, state);
     } catch (err) {
       // Advisory — never throws into the frame handler. Swallow a throwing injectable correlation and
       // leave the stream UNLINKED so a later `produce` retries the link.
@@ -459,6 +489,51 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * #544: asynchronously resolve the engine element-instance key this job occupies and record it, from
+   * the first `produce` while the JOB park is still live. Fire-and-forget: it is invoked from the
+   * synchronous frame handler but never awaited, and every failure is swallowed (advisory). On success
+   * it enriches BOTH the live correlation context (so a still-running job's reads see it) AND stashes
+   * it on the stream state (so completion persists it); it ALSO backfills the durable row directly, to
+   * cover the race where resolution returns AFTER the job completed and released its live correlation.
+   */
+  #enrichElementInstance(stream: string, jobKey: string, state: StreamState): void {
+    const resolve = this.#resolveElementInstance;
+    if (resolve === undefined) return;
+    const processInstanceKey = this.#correlation()?.resolve?.(jobKey)?.processInstanceKey;
+    // Self-contained advisory: a synchronous throw (a misbehaving resolver) is swallowed here rather
+    // than surfacing in `#link`'s catch as a misleading "link failed", and the async rejection path is
+    // handled by `.catch`. Either way this never throws into the synchronous frame handler.
+    let pending: Promise<string | undefined>;
+    try {
+      pending = resolve(jobKey, processInstanceKey);
+    } catch (err) {
+      this.#log.warn("agentic relay element-instance resolution failed — session left un-keyed", {
+        stream,
+        jobKey,
+        err: String(err),
+      });
+      return;
+    }
+    void pending
+      .then((elementInstanceKey) => {
+        if (elementInstanceKey === undefined || elementInstanceKey === "") return;
+        state.elementInstanceKey = elementInstanceKey;
+        // Enrich the live context if still linked (a no-op once released), and backfill the durable
+        // row if it was already persisted (a no-op before completion) — the two are complementary, so
+        // exactly one lands depending on whether resolution beat completion.
+        this.#correlation()?.attachElementInstance?.(jobKey, elementInstanceKey);
+        this.#correlationStore?.setElementInstanceKey(jobKey, elementInstanceKey);
+      })
+      .catch((err: unknown) => {
+        this.#log.warn("agentic relay element-instance resolution failed — session left un-keyed", {
+          stream,
+          jobKey,
+          err: String(err),
+        });
+      });
+  }
+
   /** H6 write-side (#149): release a `job:<jobKey>` stream's correlation on completion / disconnect. */
   #unlink(stream: string, state: StreamState): void {
     if (!state.linked) return;
@@ -505,6 +580,10 @@ export class RelayTranscriptService {
     try {
       const attribution = this.#attributionForInstance(instance) ?? {};
       const context = this.#correlation()?.resolve?.(jobKey);
+      // #544: prefer the live context's element-instance key; fall back to the stream state (the
+      // resolution may have landed after the context was released, or the context write-side may not
+      // carry it). Either source is the same resolved value.
+      const elementInstanceKey = context?.elementInstanceKey ?? state.elementInstanceKey;
       store.record({
         jobKey,
         stream,
@@ -516,6 +595,7 @@ export class RelayTranscriptService {
         ...(context?.bpmnProcessId !== undefined ? { bpmnProcessId: context.bpmnProcessId } : {}),
         ...(context?.elementId !== undefined ? { elementId: context.elementId } : {}),
         ...(context?.planKey !== undefined ? { planKey: context.planKey } : {}),
+        ...(elementInstanceKey !== undefined ? { elementInstanceKey } : {}),
       });
     } catch (err) {
       this.#log.warn("agentic correlation attribution persist failed — past session left unattributed", {
@@ -618,6 +698,10 @@ export function createRelayFamily(options: {
         // records instance only.
         attributionForInstance: (instance) => currentPresenceRegistry()?.attributionOf(instance),
         correlation: currentCorrelation,
+        // #544: the advisory element-instance resolver the composition root closed over the engine.
+        // Absent (engine-less host, or a test that mounts without it) → sessions are keyed on the
+        // static element id only, exactly as before this slice.
+        resolveElementInstance: ctx.resolveElementInstance,
       });
       setCurrentRelayTranscriptService(service);
 

package/app/agentic/registry.ts

@@ -23,11 +23,16 @@
 //   - `db/migrations/024_agentic_transcript.sql` → H3 (#146)
 //   - `db/migrations/025_agentic_blackboard.sql` → H4 (#147), only if it needs a schema change
 //
-// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
-// is untouched — the agentic channel is the only new conversation; advisory semantics are preserved
-// (a family NEVER hard-locks or gates a BPMN sequence flow).
+// Invariants (ADR 0056): app-tier only — a family NEVER participates in or gates the Camunda-8 job
+// protocol (worker⇄engine): it does not activate/complete jobs, publish messages, or gate a BPMN
+// sequence flow; the agentic channel is the only new conversation, and its semantics are advisory. An
+// ADVISORY, READ-ONLY query against the engine's read model (e.g. resolving the element instance a job
+// occupies, #544) is permitted — it observes state to enrich a visibility record, never drives it — and
+// is offered to families as the narrow {@link AgenticContext.resolveElementInstance} seam so a family
+// depends on a capability, not the engine handle.
 import type { AgenticHub, ConnectionRegistry, WebSocketChannelTransport } from "@nanobpm/agentic/channel";
 import type { DataLayer, Logger } from "@nanobpm/urban";
+import type { ElementInstanceResolver } from "./element-instance.ts";
 
 /**
  * The reusable handle the seam threads to every family module at mount time. A sibling family uses
@@ -43,6 +48,15 @@ export interface AgenticContext {
   readonly transport: WebSocketChannelTransport;
   /** The app's SQLite data layer — the same store the advisory blackboard uses (may be absent). */
   readonly data: DataLayer | undefined;
+  /**
+   * An ADVISORY, READ-ONLY element-instance resolver (#544), when the composition root supplies one.
+   * A family may call it to enrich a visibility record with the engine element-instance key a job
+   * occupies. It is a narrow function shape (not an engine handle) closed over the engine's element-
+   * instance wait-state read — so a family can query the engine's READ MODEL for advisory enrichment
+   * WITHOUT participating in or gating the Camunda-8 job protocol (the invariant above forbids the
+   * latter, not the former). Absent when no engine is wired (tests, engine-less hosts).
+   */
+  readonly resolveElementInstance?: ElementInstanceResolver;
   /** A structured logger for boot/shutdown lifecycle lines. */
   readonly log: Logger;
 }

package/app/agentic/transcript-read.test.ts

@@ -9,6 +9,7 @@ import { DatabaseSync } from "node:sqlite";
 import type { SqliteDb, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
 import { AgenticCorrelationStore } from "./correlation-store.ts";
+import { CorrelationRegistry } from "./correlation.ts";
 import { correlationFieldsFor, listTranscripts, readTranscriptFrom } from "./transcript-read.ts";
 
 /** A read-only TranscriptStore double: list() returns the seeded metas; read() has no retained chunks. */
@@ -107,6 +108,32 @@ test("durable fallback: a released (past) job is attributed from the durable sto
   assertEquals(fields.planKey, "acme/repo#42");
 });
 
+test("#544: the durable element-instance key surfaces on the read projection and its filter", () => {
+  const durable = new AgenticCorrelationStore(memoryStore());
+  // Two iterations of the SAME static element (`agent`) — distinct element instances, distinct jobKeys.
+  durable.record({ jobKey: "k1", stream: "job:k1", instance: "worker-A", elementId: "agent", elementInstanceKey: "ei-1", completedAt: early });
+  durable.record({ jobKey: "k2", stream: "job:k2", instance: "worker-A", elementId: "agent", elementInstanceKey: "ei-2", completedAt: late });
+
+  // The key surfaces on the correlation fields (durable fallback, live registry empty).
+  assertEquals(correlationFieldsFor("job:k1", undefined, durable).elementInstanceKey, "ei-1");
+
+  const store = fakeStore([meta("job:k1", early), meta("job:k2", late)]);
+  // The elementInstanceKey filter resolves a session to ONE occupancy, where the elementId cannot.
+  const out = listTranscripts(store, undefined, { elementInstanceKey: "ei-2" }, durable);
+  assertEquals(out.map((t) => t.stream), ["job:k2"], "only the ei-2 occupancy matches");
+  assertEquals(out[0].elementInstanceKey, "ei-2", "the projection carries the element-instance key");
+});
+
+test("#544: the live correlation's element-instance key takes precedence over the durable row on read", () => {
+  const registry = new CorrelationRegistry();
+  registry.link("worker-A", "k1", { elementId: "agent" });
+  registry.attachElementInstance("k1", "ei-live");
+  const durable = new AgenticCorrelationStore(memoryStore());
+  durable.record({ jobKey: "k1", stream: "job:k1", instance: "worker-A", elementInstanceKey: "ei-old", completedAt: mid });
+
+  assertEquals(correlationFieldsFor("job:k1", registry, durable).elementInstanceKey, "ei-live");
+});
+
 test("listTranscripts: the instance filter returns only sessions the durable store attributes to that worker", () => {
   const store = fakeStore([meta("job:k1", early), meta("job:k2", mid), meta("job:k3", late)]);
   const durable = new AgenticCorrelationStore(memoryStore());

package/app/agentic/transcript-read.ts

@@ -33,6 +33,8 @@ interface CorrelationFields {
   processInstanceKey?: string;
   bpmnProcessId?: string;
   elementId?: string;
+  /** The engine element-instance key the job's token occupied (#544) — per-occupancy, unlike elementId. */
+  elementInstanceKey?: string;
   planKey?: string;
   /** The worker instance that ran the job (durable — survives release / restart). */
   instance?: string;
@@ -63,6 +65,7 @@ export function correlationFieldsFor(
     if (context.processInstanceKey !== undefined) fields.processInstanceKey = context.processInstanceKey;
     if (context.bpmnProcessId !== undefined) fields.bpmnProcessId = context.bpmnProcessId;
     if (context.elementId !== undefined) fields.elementId = context.elementId;
+    if (context.elementInstanceKey !== undefined) fields.elementInstanceKey = context.elementInstanceKey;
     if (context.planKey !== undefined) fields.planKey = context.planKey;
   }
   // Durable fallback: fill any field the live registry did not supply (a released past session, or a
@@ -74,6 +77,9 @@ export function correlationFieldsFor(
     }
     if (fields.bpmnProcessId === undefined && row.bpmnProcessId !== undefined) fields.bpmnProcessId = row.bpmnProcessId;
     if (fields.elementId === undefined && row.elementId !== undefined) fields.elementId = row.elementId;
+    if (fields.elementInstanceKey === undefined && row.elementInstanceKey !== undefined) {
+      fields.elementInstanceKey = row.elementInstanceKey;
+    }
     if (fields.planKey === undefined && row.planKey !== undefined) fields.planKey = row.planKey;
     if (row.instance !== undefined) fields.instance = row.instance;
     if (row.identity !== undefined) fields.identity = row.identity;
@@ -106,6 +112,7 @@ export function toTranscript(
   if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
   if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
   if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.elementInstanceKey !== undefined) out.elementInstanceKey = fields.elementInstanceKey;
   if (fields.planKey !== undefined) out.planKey = fields.planKey;
   if (fields.instance !== undefined) out.instance = fields.instance;
   if (fields.identity !== undefined) out.identity = fields.identity;
@@ -117,6 +124,8 @@ export function toTranscript(
 export interface TranscriptFilter {
   readonly jobKey?: string;
   readonly processInstanceKey?: string;
+  /** The engine element-instance key (#544) — resolves a session to one occupancy of a looping activity. */
+  readonly elementInstanceKey?: string;
   readonly planKey?: string;
   /** The worker instance that ran the session (durable attribution) — powers the worker-history view. */
   readonly instance?: string;
@@ -145,6 +154,7 @@ export function listTranscripts(
     .filter((t) => {
       if (filter.jobKey !== undefined && t.jobKey !== filter.jobKey) return false;
       if (filter.processInstanceKey !== undefined && t.processInstanceKey !== filter.processInstanceKey) return false;
+      if (filter.elementInstanceKey !== undefined && t.elementInstanceKey !== filter.elementInstanceKey) return false;
       if (filter.planKey !== undefined && t.planKey !== filter.planKey) return false;
       if (filter.instance !== undefined && t.instance !== filter.instance) return false;
       const createdMs = Date.parse(t.createdAt);
@@ -225,6 +235,7 @@ export function readTranscriptFrom(
   if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
   if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
   if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.elementInstanceKey !== undefined) out.elementInstanceKey = fields.elementInstanceKey;
   if (fields.planKey !== undefined) out.planKey = fields.planKey;
   if (fields.instance !== undefined) out.instance = fields.instance;
   if (fields.identity !== undefined) out.identity = fields.identity;

package/app/convergeTargets.ts

@@ -0,0 +1,30 @@
+// The converge-enrollment connector-target vocabulary (ADR 0005, issue #500) — the SINGLE, dependency-
+// free source of truth for the `converge` / `converge-merge` literals and their derived semantics.
+// Extracted from `deliveryConnector.ts` so the pure, import-free semantic validator (`deliveryGraph.ts`)
+// can share the exact same predicate WITHOUT pulling in the connector module's urban/data-layer deps —
+// a converge/wait node's late-binding validation (issue #548) must agree with the worker's dispatch
+// branch on what "a converge target" is, and this module is what keeps them from drifting.
+
+/** The review-only converge target: enrolls a PR into the shared convergence loop and STOPS at
+ * `converged` (never hands it to the merge loop). */
+export const CONVERGE_TARGET = "converge";
+
+/** The converge-AND-merge target: enrolls a PR into the shared convergence loop and drives the merge
+ * loop too (the canonical `agent → connector[converge-merge] → wait[pr, merged]` land shape). */
+export const CONVERGE_MERGE_TARGET = "converge-merge";
+
+/** Is `target` one of the converge-enrollment targets (`converge` / `converge-merge`)? The single
+ * predicate the connector worker branches on to route a dispatch into `submitPr`, and the validator
+ * branches on to require a bound/literal PR (issue #548). */
+export function isConvergeTarget(target: string): boolean {
+  return target === CONVERGE_TARGET || target === CONVERGE_MERGE_TARGET;
+}
+
+/** The DEFAULT `convergeOnly` for a converge target: `converge` is review-only (`true` — stop at
+ * `converged`), `converge-merge` drives the merge loop too (`false`). Maps directly onto `submitPr`'s
+ * `convergeOnly` argument. An author may still override it per-dispatch via the connector payload's
+ * `convergeOnly`. Only ever consulted behind `isConvergeTarget`, so a non-converge target's `false`
+ * is unreachable. */
+export function convergeOnlyForTarget(target: string): boolean {
+  return target === CONVERGE_TARGET;
+}

package/app/deliveryConnector.ts

@@ -39,26 +39,14 @@ export const OUTCOME_DELIVERED = "delivered";
  * convergence AND the merge loop; `converge` stops at `converged` (converge-only). This is the "real
  * target dispatch" ADR 0005 deferred as a later slice for the connector I/O surface: a `converge`/
  * `converge-merge` connector IS the "automated, side-effecting outbound action" a connector is
- * defined to be. Named constants so the worker's dispatch branch and the docs/preview can never drift
- * on the literal. */
-export const CONVERGE_TARGET = "converge";
-export const CONVERGE_MERGE_TARGET = "converge-merge";
-
-/** Is `target` one of the converge-enrollment targets (`converge` / `converge-merge`)? The single
- * predicate the worker branches on to route a dispatch into `submitPr` instead of the forward-declared
- * stub. */
-export function isConvergeTarget(target: string): boolean {
-  return target === CONVERGE_TARGET || target === CONVERGE_MERGE_TARGET;
-}
-
-/** The DEFAULT `convergeOnly` for a converge target: `converge` is review-only (`true` — stop at
- * `converged`), `converge-merge` drives the merge loop too (`false`). Maps directly onto `submitPr`'s
- * `convergeOnly` argument (mirroring how `converge-feature` inverts `autoMerge`). An author may still
- * override it per-dispatch via the connector payload's `convergeOnly`. Only ever consulted behind
- * `isConvergeTarget`, so a non-converge target's `false` is unreachable. */
-export function convergeOnlyForTarget(target: string): boolean {
-  return target === CONVERGE_TARGET;
-}
+ * defined to be. The converge-target vocabulary lives in the dependency-free {@link ./convergeTargets.ts}
+ * so the pure validator can share it; re-exported here for the worker's existing import surface. */
+export {
+  CONVERGE_MERGE_TARGET,
+  CONVERGE_TARGET,
+  convergeOnlyForTarget,
+  isConvergeTarget,
+} from "./convergeTargets.ts";
 
 /** One durable dispatch-claim row — the at-most-once ledger entry a connector writes before it acts. */
 export interface DeliveryConnectorDispatchRow extends Record<string, unknown> {
@@ -82,6 +70,29 @@ export interface BoundFact {
   value: unknown;
 }
 
+/** Resolve a converge connector's effective target PR (issue #548), late-binding it from an upstream
+ * `agent` node's emitted `pr` fact so the canonical `agent → connector[converge-merge] → wait` shape
+ * needs NO hardcoded literal. Precedence, given the author-supplied `payload.pr` and the threaded
+ * `boundFacts`:
+ *   • an explicit fact REFERENCE — a `payload.pr` string that exactly matches a threaded fact's
+ *     `<from>.<name>` — resolves to that fact's value (an `owner/repo#N` PR ref emitted upstream);
+ *   • an explicit LITERAL — any other `payload.pr` string — is returned as-is (a real `owner/repo#N`
+ *     is never `<node>.<fact>`-shaped, so it can't collide with a reference), and `parsePr` validates it;
+ *   • OMITTED (`payload.pr` absent) — binds the single incoming fact named `pr` (the canonical emit),
+ *     else the single incoming bound fact when there is exactly one, else stays undefined so
+ *     {@link readConvergeInput} raises its "requires payload.pr" error (fail closed).
+ * Pure + total (no PR parsing here — the caller validates), so it is unit-testable without the engine. */
+export function resolveConvergePr(payloadPr: unknown, boundFacts: readonly BoundFact[]): unknown {
+  if (typeof payloadPr === "string" && payloadPr.trim() !== "") {
+    const ref = boundFacts.find((b) => `${b.from}.${b.name}` === payloadPr.trim());
+    return ref ? ref.value : payloadPr;
+  }
+  const named = boundFacts.filter((b) => b.name === "pr");
+  if (named.length === 1) return named[0].value;
+  if (named.length === 0 && boundFacts.length === 1) return boundFacts[0].value;
+  return payloadPr;
+}
+
 /** The effective dedupe key for a connector dispatch: the author-supplied `connector.dedupeKey` when
  * present, else a graph-derived `<processInstanceKey>:<elementId>` — both STABLE across a re-activation
  * of the same node instance (the engine re-delivers the same job with the same identity), so an