@nanobpm/nano-workforce 0.139.4 → 0.141.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 };
@@ -292,6 +300,37 @@ test("retention: a disconnected producer auto-completes its ephemeral stream on
   service.teardown();
 });
 
+test("#486 live fallback: an uncompleted stream's ring is served pre-flush, then yields to the durable store", () => {
+  const registry = new ConnectionRegistry();
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({
+    hub,
+    registry,
+    db: memoryDb(),
+    log: noopLog(),
+    now: () => "2026-03-04T05:06:07.000Z",
+  });
+  const p = connect("prod", registry);
+  for (let i = 0; i < 3; i++) hub.handler?.(produce(jobStream("Lk1"), 1, `r${i}`), p.conn);
+
+  // The job has completed and emitted its transcriptUrl, but this multiplexing worker is still live so
+  // no disconnect/supersede flushed the ring — the durable store still 404s (#486). The live fallback
+  // exposes the captured ring + its opened-at instant so the read path can serve it immediately.
+  assertEquals(service.transcriptOf(jobStream("Lk1")), undefined, "not yet flushed while the worker is live");
+  const live = service.liveFallback(jobStream("Lk1"));
+  assert(live !== undefined, "a live, unflushed stream has a serveable ring");
+  assertEquals(live.createdAt, "2026-03-04T05:06:07.000Z", "createdAt is the stream's opened-at instant");
+  assertEquals(live.ring.since(0).entries.length, 3, "the whole captured window is available");
+  assertEquals(live.ring.nextOffset, 3);
+
+  // Once the stream completes (flushed to durable), the durable store is the source of truth and the
+  // live fallback steps aside so a completed transcript is never double-sourced.
+  service.completeStream(jobStream("Lk1"));
+  assertEquals(service.transcriptOf(jobStream("Lk1"))?.status, "completed");
+  assertEquals(service.liveFallback(jobStream("Lk1")), undefined, "a completed stream no longer falls back to the ring");
+  service.teardown();
+});
+
 test("H6 correlation write-side: a produce on job:<k> links instance→[k]; stream completion releases it", () => {
   const registry = new ConnectionRegistry();
   const correlation = new CorrelationRegistry();
@@ -421,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";
 
@@ -90,6 +91,14 @@ interface StreamState {
    * instance is not yet resolvable (a register/produce race), so a later `produce` frame retries.
    */
   linked: boolean;
+  /**
+   * When this stream's in-memory state was first opened, ISO-8601 (stamped from the service clock).
+   * The durable transcript row carries its own `created_at` (stamped at flush/`open`), but a
+   * still-live ephemeral stream has no durable row yet (#486): its ring holds the captured bytes but
+   * the store 404s until a producer disconnect / supersede flushes it. This is the authoritative
+   * "when opened" for {@link RelayTranscriptService.liveFallback} to serve the pre-flush ring.
+   */
+  createdAt: string;
   /**
    * The worker instance a `job:<jobKey>` stream was linked under (H6). Recorded so a stream's release
    * (completion / disconnect) can tidy the {@link RelayTranscriptService.#jobStreamByInstance}
@@ -97,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;
 }
 
 /**
@@ -107,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
@@ -170,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;
 }
@@ -218,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;
 
@@ -227,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
@@ -440,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.
@@ -451,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;
@@ -497,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,
@@ -508,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", {
@@ -536,10 +624,30 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * The still-live relay ring for a stream, for the read path to serve BEFORE a durable flush (#486).
+   *
+   * A multiplexing worker relays every job over one long-lived connection, one job at a time, so an
+   * ephemeral job stream is only flushed to the durable store when the worker disconnects or a NEW
+   * job supersedes it — NOT when the job itself completes. In the window between "job completed
+   * (`transcriptUrl` emitted)" and that flush, {@link TranscriptStore.get} returns undefined and the
+   * transcript endpoint would 404 the freshly-emitted URL. This exposes the live ring (+ its opened-at
+   * instant) so {@link readTranscriptFrom} can serve the captured bytes directly, making the URL
+   * readable the moment it is emitted. Returns undefined when there is no live ring, or once the
+   * stream has been completed (the durable store is then the source of truth).
+   */
+  liveFallback(stream: string): { ring: TranscriptRing; createdAt: string } | undefined {
+    const ring = this.relay.ring(stream);
+    if (ring === undefined) return undefined;
+    const state = this.#streams.get(stream);
+    if (state?.completed) return undefined;
+    return { ring, createdAt: state?.createdAt ?? this.#now() };
+  }
+
   #stateFor(stream: string): StreamState {
     let state = this.#streams.get(stream);
     if (state === undefined) {
-      state = { lifecycle: "ephemeral", completed: false, linked: false };
+      state = { lifecycle: "ephemeral", completed: false, linked: false, createdAt: this.#now() };
       this.#streams.set(stream, state);
     }
     return state;
@@ -590,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

@@ -6,10 +6,11 @@
 // interaction with a missing/invalid createdAt — where a hand-built store lets us fix exact timestamps.
 import { test } from "node:test";
 import { DatabaseSync } from "node:sqlite";
-import type { SqliteDb, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+import type { SqliteDb, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import { assert, assertEquals } from "#test-assert";
 import { AgenticCorrelationStore } from "./correlation-store.ts";
-import { correlationFieldsFor, listTranscripts } from "./transcript-read.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. */
 function fakeStore(metas: TranscriptStream[]): TranscriptStore {
@@ -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());
@@ -122,3 +149,96 @@ test("listTranscripts: the instance filter returns only sessions the durable sto
   );
   assert(out.every((t) => t.instance === "worker-A"), "each row is attributed to worker-A");
 });
+
+// --- #486: the still-live-ring read fallback that makes a freshly-emitted transcriptUrl readable ---
+//
+// A multiplexing worker relays every job over one long-lived connection and only flushes a job's ring
+// to the durable store when it disconnects or a NEW job supersedes it — NOT when the job completes. In
+// the window between "job completed (transcriptUrl emitted)" and that flush, the durable store has no
+// row, so the transcript endpoint must serve the live ring or it would 404 the URL it just emitted.
+
+/** A minimal live ring double satisfying {@link TranscriptRing}: the whole retained window from `from`. */
+function fakeRing(entries: { offset: number; chunk: string }[]): TranscriptRing {
+  const nextOffset = entries.length === 0 ? 0 : entries[entries.length - 1].offset + 1;
+  return {
+    since: (from: number) => ({ entries: entries.filter((e) => e.offset >= from) }),
+    nextOffset,
+  };
+}
+
+/** A store double whose `get` returns a seeded row (or undefined), with the matching `since` window. */
+function getStore(row: TranscriptStream | undefined, entries: { offset: number; chunk: string }[] = []): TranscriptStore {
+  return {
+    get: (_stream: string) => row,
+    since: (_stream: string, from: number) => ({
+      entries: entries.filter((e) => e.offset >= from),
+      gap: false,
+      nextOffset: row?.nextOffset ?? 0,
+    }),
+  } as unknown as TranscriptStore;
+}
+
+test("readTranscriptFrom: falls back to the live ring when the durable store has no row (#486)", () => {
+  const ring = fakeRing([
+    { offset: 0, chunk: "hello " },
+    { offset: 1, chunk: "world" },
+  ]);
+  const out = readTranscriptFrom("job:live1", 0, getStore(undefined), undefined, undefined, {
+    ring,
+    createdAt: mid,
+  });
+  assert(out !== undefined, "a live-but-unflushed stream is readable, not a 404");
+  assertEquals(out.status, "open", "an unflushed live stream reads as open");
+  assertEquals(out.lifecycle, "ephemeral");
+  assertEquals(out.createdAt, mid);
+  assertEquals(out.nextOffset, 2);
+  assertEquals(out.chunkCount, 2);
+  assertEquals(
+    out.entries.map((e) => e.chunk).join(""),
+    "hello world",
+    "the captured bytes are served straight from the ring",
+  );
+  assertEquals(out.jobKey, "live1", "the jobKey is still decoded from the stream id");
+});
+
+test("readTranscriptFrom: the live-ring fallback honours the resume-from offset", () => {
+  const ring = fakeRing([
+    { offset: 0, chunk: "a" },
+    { offset: 1, chunk: "b" },
+    { offset: 2, chunk: "c" },
+  ]);
+  const out = readTranscriptFrom("job:live2", 2, getStore(undefined), undefined, undefined, { ring, createdAt: mid });
+  assert(out !== undefined);
+  assertEquals(out.from, 2);
+  assertEquals(
+    out.entries.map((e) => e.chunk).join(""),
+    "c",
+    "only chunks at/after the requested offset are replayed",
+  );
+});
+
+test("readTranscriptFrom: prefers the durable store once the ring has been flushed", () => {
+  const row: TranscriptStream = {
+    stream: "job:flushed",
+    lifecycle: "ephemeral",
+    status: "completed",
+    createdAt: early,
+    completedAt: late,
+    nextOffset: 1,
+  };
+  const store = getStore(row, [{ offset: 0, chunk: "durable" }]);
+  // A live ring is ALSO provided, but the flushed durable row wins (it is the source of truth once flushed).
+  const out = readTranscriptFrom("job:flushed", 0, store, undefined, undefined, {
+    ring: fakeRing([{ offset: 0, chunk: "stale-ring" }]),
+    createdAt: mid,
+  });
+  assert(out !== undefined);
+  assertEquals(out.status, "completed", "the flushed durable row is served, not the live ring");
+  assertEquals(out.completedAt, late);
+  assertEquals(out.entries.map((e) => e.chunk).join(""), "durable");
+});
+
+test("readTranscriptFrom: returns undefined when neither the store nor a live ring has the stream", () => {
+  const out = readTranscriptFrom("job:gone", 0, getStore(undefined), undefined, undefined, undefined);
+  assertEquals(out, undefined);
+});