@nanobpm/nano-workforce 0.127.0 → 0.129.0

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

@@ -33,7 +33,8 @@ import {
   type TranscriptStream,
 } from "@nanobpm/agentic/transcript";
 import type { Logger } from "@nanobpm/urban";
-import { currentCorrelation, type JobContext, jobKeyOfStream } from "../correlation.ts";
+import { currentCorrelation, type JobContext, type JobCorrelation, jobKeyOfStream } from "../correlation.ts";
+import { AgenticCorrelationStore } from "../correlation-store.ts";
 import type { AgenticContext, AgenticFamily } from "../registry.ts";
 import { currentPresenceRegistry } from "./presence.family.ts";
 
@@ -89,6 +90,13 @@ interface StreamState {
    * instance is not yet resolvable (a register/produce race), so a later `produce` frame retries.
    */
   linked: boolean;
+  /**
+   * 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}
+   * supersede index, and so the "one job at a time per worker" supersede rule can identify the
+   * instance's prior job stream.
+   */
+  instance?: string;
 }
 
 /**
@@ -99,6 +107,19 @@ interface StreamState {
 export interface CorrelationLink {
   link(instance: string, jobKey: string, context?: JobContext): void;
   releaseJob(jobKey: 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
+   * relay slice reads it at completion to persist a job's process-instance / plan context durably
+   * before the correlation is released (#485).
+   */
+  resolve?(jobKey: string): JobCorrelation | undefined;
+}
+
+/** A worker's durable identity attributes, resolved from the presence registry at completion time. */
+export interface WorkerAttribution {
+  readonly identity?: string;
+  readonly host?: string;
 }
 
 export interface RelayTranscriptServiceOptions {
@@ -137,6 +158,20 @@ export interface RelayTranscriptServiceOptions {
    * ({@link currentPresenceRegistry}). A resolver returning undefined → no linking (advisory).
    */
   readonly instanceForConnection?: (connectionId: string) => string | undefined;
+  /**
+   * Resolve a producing worker instance's durable identity attributes (identity / host) — read at
+   * job-completion time and persisted with the attribution so a PAST session stays attributable to a
+   * worker after it exits (#485). {@link createRelayFamily} wires it to the presence registry; omitted
+   * → attribution is recorded with instance only (still attributable), never an error.
+   */
+  readonly attributionForInstance?: (instance: string) => WorkerAttribution | undefined;
+  /**
+   * The durable worker-attribution store (#485). Omitted → constructed from {@link db} (absent db →
+   * no durable attribution). Injectable so a test can supply an in-memory store.
+   */
+  readonly correlationStore?: AgenticCorrelationStore;
+  /** "Now" as an ISO-8601 instant, injectable for deterministic completion timestamps. */
+  readonly now?: () => string;
 }
 
 /** The minimal per-connection surface the relay handler receives from the hub (a {@link RelayHub} `RelayConnection`). */
@@ -158,19 +193,41 @@ export class RelayTranscriptService {
   /** The transcript store, or `undefined` when no DataLayer is mounted (relay still works, unpersisted). */
   readonly store: TranscriptStore | undefined;
 
+  /** The durable worker-attribution store (#485), or `undefined` when unpersisted. Exposed so the read path can attribute released jobs. */
+  get correlationStore(): AgenticCorrelationStore | undefined {
+    return this.#correlationStore;
+  }
+
   readonly #registry: ConnectionRegistry;
   readonly #log: Logger;
   readonly #streams = new Map<string, StreamState>();
+  /**
+   * The `job:<jobKey>` relay stream each worker instance is CURRENTLY relaying (H6, #149). A worker
+   * relays every job it runs over one long-lived channel connection, one job at a time
+   * (`../correlation.ts`), so that connection never disconnects between jobs — the disconnect-driven
+   * `#reconcile` release never fires. This index lets a NEW job's first `produce` supersede the
+   * worker's PRIOR job (complete its stream → flush transcript + release correlation), so a supply
+   * row shows only the current job instead of accumulating every job the connection ever ran.
+   */
+  readonly #jobStreamByInstance = new Map<string, string>();
   /** The correlation write-side accessor (H6, #149) — resolved per call so a late family mount wins. */
   readonly #correlation: () => CorrelationLink | undefined;
   /** The connection → producing-instance resolver (H6, #149). */
   readonly #instanceForConnection: (connectionId: string) => string | undefined;
+  /** Resolve a worker instance's durable identity attributes for attribution (#485). */
+  readonly #attributionForInstance: (instance: string) => WorkerAttribution | undefined;
+  /** The durable worker-attribution store, or undefined when unpersisted (#485). */
+  readonly #correlationStore: AgenticCorrelationStore | undefined;
+  /** "Now" as an ISO-8601 instant (injectable for deterministic tests). */
+  readonly #now: () => string;
 
   constructor(options: RelayTranscriptServiceOptions) {
     this.#registry = options.registry;
     this.#log = options.log;
     this.#correlation = options.correlation ?? currentCorrelation;
     this.#instanceForConnection = options.instanceForConnection ?? (() => undefined);
+    this.#attributionForInstance = options.attributionForInstance ?? (() => undefined);
+    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
     // running the relay unpersisted rather than tearing down the whole agentic channel.
@@ -188,6 +245,21 @@ export class RelayTranscriptService {
     }
     this.store = store;
 
+    // The durable worker-attribution store (#485) — advisory, same failure posture as the transcript
+    // store: an unbuildable store falls back to no durable attribution, never a mount failure.
+    let correlationStore = options.correlationStore;
+    if (correlationStore === undefined && options.db) {
+      try {
+        correlationStore = new AgenticCorrelationStore(options.db);
+      } catch (err) {
+        this.#log.warn("agentic correlation store unavailable — past sessions unattributed", {
+          err: String(err),
+        });
+        correlationStore = undefined;
+      }
+    }
+    this.#correlationStore = correlationStore;
+
     this.relay = new RelayHub({
       ...options.relay,
       onFenced: (stream, incarnation, current) => {
@@ -357,8 +429,17 @@ export class RelayTranscriptService {
     const correlation = this.#correlation();
     if (!correlation) return;
     try {
+      // One job at a time per worker (`../correlation.ts`): the worker relaying a NEW job's terminal
+      // over its live connection PROVES its prior job finished. Supersede it — complete the prior
+      // stream (flush transcript → durable past session, release its correlation) BEFORE linking the
+      // new one — so the worker's supply row never accumulates jobs the disconnect-driven release
+      // would otherwise strand behind a connection that stays open across jobs.
+      const priorStream = this.#jobStreamByInstance.get(instance);
+      if (priorStream !== undefined && priorStream !== stream) this.completeStream(priorStream);
       correlation.link(instance, jobKey);
       state.linked = true;
+      state.instance = instance;
+      this.#jobStreamByInstance.set(instance, stream);
     } 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.
@@ -376,8 +457,17 @@ export class RelayTranscriptService {
     const jobKey = jobKeyOfStream(stream);
     if (jobKey === undefined) return;
     try {
+      // Persist the completed job's durable worker attribution + (best-effort) engine context BEFORE
+      // releasing the live correlation, so a PAST session stays attributable to a worker after it
+      // exits (#485) — the in-memory registry is about to forget it. Advisory, best-effort.
+      this.#persistAttribution(stream, jobKey, state);
       this.#correlation()?.releaseJob(jobKey);
       state.linked = false;
+      // Tidy the supersede index so it never points a released instance at a completed stream and
+      // stays bounded across the worker's lifetime.
+      if (state.instance !== undefined && this.#jobStreamByInstance.get(state.instance) === stream) {
+        this.#jobStreamByInstance.delete(state.instance);
+      }
     } catch (err) {
       // Advisory — never throws into the frame handler. Swallow a throwing injectable correlation and
       // leave `state.linked` true so the flag honestly records that the release did NOT happen (rather
@@ -393,6 +483,41 @@ export class RelayTranscriptService {
     }
   }
 
+  /**
+   * Record a completed job's durable attribution (#485): which worker ran it (instance + presence
+   * identity/host) and its still-live engine context (process instance / plan), keyed by jobKey, so
+   * the transcript read path can attribute the PAST session after the live correlation is released
+   * and after a restart. Advisory — a persistence fault is logged, never thrown into the frame
+   * handler, and never blocks the correlation release.
+   */
+  #persistAttribution(stream: string, jobKey: string, state: StreamState): void {
+    const store = this.#correlationStore;
+    const instance = state.instance;
+    if (store === undefined || instance === undefined || instance === "") return;
+    try {
+      const attribution = this.#attributionForInstance(instance) ?? {};
+      const context = this.#correlation()?.resolve?.(jobKey);
+      store.record({
+        jobKey,
+        stream,
+        instance,
+        completedAt: this.#now(),
+        ...(attribution.identity !== undefined ? { identity: attribution.identity } : {}),
+        ...(attribution.host !== undefined ? { host: attribution.host } : {}),
+        ...(context?.processInstanceKey !== undefined ? { processInstanceKey: context.processInstanceKey } : {}),
+        ...(context?.bpmnProcessId !== undefined ? { bpmnProcessId: context.bpmnProcessId } : {}),
+        ...(context?.elementId !== undefined ? { elementId: context.elementId } : {}),
+        ...(context?.planKey !== undefined ? { planKey: context.planKey } : {}),
+      });
+    } catch (err) {
+      this.#log.warn("agentic correlation attribution persist failed — past session left unattributed", {
+        stream,
+        jobKey,
+        err: String(err),
+      });
+    }
+  }
+
   /**
    * Flush + complete every ephemeral stream whose producer connection is no longer live (the S1
    * registry dropped it on close or liveness timeout), and release its job correlation (H6, #149).
@@ -460,6 +585,10 @@ export function createRelayFamily(options: {
         // are read per call, so this works regardless of family mount order (relay may mount before
         // presence/correlation). Absent registries → no linking, still advisory-correct.
         instanceForConnection: (connectionId) => currentPresenceRegistry()?.instanceForConnection(connectionId),
+        // #485: resolve a completed job's worker attribution (presence identity/host) from the live
+        // presence registry, read per call for the same mount-order independence. Absent → attribution
+        // records instance only.
+        attributionForInstance: (instance) => currentPresenceRegistry()?.attributionOf(instance),
         correlation: currentCorrelation,
       });
       setCurrentRelayTranscriptService(service);

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

@@ -5,9 +5,11 @@
 // time-window semantics directly on listTranscripts() — inclusive boundaries, ordering, and the
 // interaction with a missing/invalid createdAt — where a hand-built store lets us fix exact timestamps.
 import { test } from "node:test";
-import type { TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
-import { assertEquals } from "#test-assert";
-import { listTranscripts } from "./transcript-read.ts";
+import { DatabaseSync } from "node:sqlite";
+import type { SqliteDb, 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";
 
 /** A read-only TranscriptStore double: list() returns the seeded metas; read() has no retained chunks. */
 function fakeStore(metas: TranscriptStream[]): TranscriptStore {
@@ -70,3 +72,53 @@ test("listTranscripts: a session with an unparseable createdAt is retained regar
   const out = listTranscripts(store, undefined, { since: late });
   assertEquals(new Set(out.map((t) => t.stream)), new Set(["job:bad"]));
 });
+
+function memoryStore(): SqliteDb {
+  const raw = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => raw.exec(sql),
+    run: (sql, params = []) => raw.prepare(sql).run(...params),
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []): T[] =>
+      raw.prepare(sql).all(...params) as T[],
+  };
+}
+
+test("durable fallback: a released (past) job is attributed from the durable store when the live registry is empty", () => {
+  // The exact past-session case: the live correlation registry no longer holds the job (undefined here),
+  // so worker attribution + context must come from the durable store recorded at completion.
+  const durable = new AgenticCorrelationStore(memoryStore());
+  durable.record({
+    jobKey: "k1",
+    stream: "job:k1",
+    instance: "worker-A",
+    identity: "gpu-box-7",
+    host: "us-east-1a",
+    processInstanceKey: "pi-9",
+    planKey: "acme/repo#42",
+    completedAt: mid,
+  });
+
+  const fields = correlationFieldsFor("job:k1", undefined, durable);
+  assertEquals(fields.jobKey, "k1");
+  assertEquals(fields.instance, "worker-A");
+  assertEquals(fields.identity, "gpu-box-7");
+  assertEquals(fields.host, "us-east-1a");
+  assertEquals(fields.processInstanceKey, "pi-9");
+  assertEquals(fields.planKey, "acme/repo#42");
+});
+
+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());
+  durable.record({ jobKey: "k1", stream: "job:k1", instance: "worker-A", completedAt: early });
+  durable.record({ jobKey: "k2", stream: "job:k2", instance: "worker-B", completedAt: mid });
+  durable.record({ jobKey: "k3", stream: "job:k3", instance: "worker-A", completedAt: late });
+
+  const out = listTranscripts(store, undefined, { instance: "worker-A" }, durable);
+  assertEquals(
+    out.map((t) => t.stream),
+    ["job:k3", "job:k1"],
+    "only worker-A's sessions, newest-first",
+  );
+  assert(out.every((t) => t.instance === "worker-A"), "each row is attributed to worker-A");
+});

package/app/agentic/transcript-read.ts

@@ -17,6 +17,7 @@
 import type { TranscriptChunk, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
 import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
+import type { AgenticCorrelationStore } from "./correlation-store.ts";
 import { utf8ByteLength } from "./transcript-events.ts";
 
 /** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
@@ -26,21 +27,34 @@ export function byteLengthOf(chunks: readonly TranscriptChunk[]): number {
   return total;
 }
 
-/** The correlation fields (jobKey + engine context) a stream id resolves to, best-effort. */
+/** The correlation fields (jobKey + engine context + worker attribution) a stream id resolves to, best-effort. */
 interface CorrelationFields {
   jobKey?: string;
   processInstanceKey?: string;
   bpmnProcessId?: string;
   elementId?: string;
   planKey?: string;
+  /** The worker instance that ran the job (durable — survives release / restart). */
+  instance?: string;
+  /** The worker's durable identity, when recorded. */
+  identity?: string;
+  /** The worker's host, when recorded. */
+  host?: string;
 }
 
 /**
- * Resolve a stream id to its correlation fields: the jobKey is always decoded from a `job:<jobKey>`
- * stream id; the engine context (process instance / plan) is added only when the correlation registry
- * still holds the (live) job. Non-job streams yield an empty object.
+ * Resolve a stream id to its correlation fields. The jobKey is always decoded from a `job:<jobKey>`
+ * stream id. Engine context (process instance / plan) + worker attribution (instance / identity /
+ * host) come from the LIVE registry while the job is still linked, and fall back to the DURABLE store
+ * (`AgenticCorrelationStore`) once the job has completed and its live correlation was released — so a
+ * PAST session stays attributable to its worker after the worker exits or the process restarts.
+ * Non-job streams yield an empty object.
  */
-export function correlationFieldsFor(stream: string, correlation: CorrelationRegistry | undefined): CorrelationFields {
+export function correlationFieldsFor(
+  stream: string,
+  correlation: CorrelationRegistry | undefined,
+  durable?: AgenticCorrelationStore | undefined,
+): CorrelationFields {
   const jobKey = jobKeyOfStream(stream);
   if (jobKey === undefined) return {};
   const fields: CorrelationFields = { jobKey };
@@ -51,6 +65,20 @@ export function correlationFieldsFor(stream: string, correlation: CorrelationReg
     if (context.elementId !== undefined) fields.elementId = context.elementId;
     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
+  // worker-attribution field the in-memory registry never carried). Live values take precedence.
+  const row = durable?.get(jobKey);
+  if (row) {
+    if (fields.processInstanceKey === undefined && row.processInstanceKey !== undefined) {
+      fields.processInstanceKey = row.processInstanceKey;
+    }
+    if (fields.bpmnProcessId === undefined && row.bpmnProcessId !== undefined) fields.bpmnProcessId = row.bpmnProcessId;
+    if (fields.elementId === undefined && row.elementId !== undefined) fields.elementId = row.elementId;
+    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;
+    if (row.host !== undefined) fields.host = row.host;
+  }
   return fields;
 }
 
@@ -59,6 +87,7 @@ export function toTranscript(
   meta: TranscriptStream,
   store: TranscriptStore,
   correlation: CorrelationRegistry | undefined,
+  durable?: AgenticCorrelationStore | undefined,
 ): AgenticTranscript {
   const chunks = store.read(meta.stream);
   const out: AgenticTranscript = {
@@ -72,12 +101,15 @@ export function toTranscript(
   };
   if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
   if (meta.firstOffset !== undefined) out.firstOffset = meta.firstOffset;
-  const fields = correlationFieldsFor(meta.stream, correlation);
+  const fields = correlationFieldsFor(meta.stream, correlation, durable);
   if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
   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.planKey !== undefined) out.planKey = fields.planKey;
+  if (fields.instance !== undefined) out.instance = fields.instance;
+  if (fields.identity !== undefined) out.identity = fields.identity;
+  if (fields.host !== undefined) out.host = fields.host;
   return out;
 }
 
@@ -86,6 +118,8 @@ export interface TranscriptFilter {
   readonly jobKey?: string;
   readonly processInstanceKey?: string;
   readonly planKey?: string;
+  /** The worker instance that ran the session (durable attribution) — powers the worker-history view. */
+  readonly instance?: string;
   /** ISO-8601 lower bound (inclusive) on the session's createdAt. */
   readonly since?: string;
   /** ISO-8601 upper bound (inclusive) on the session's createdAt. */
@@ -95,22 +129,24 @@ export interface TranscriptFilter {
 /**
  * List every captured session projected to the wire shape, sorted newest-first by createdAt (then by
  * stream for a stable tie-break), after applying the (advisory) filters. jobKey / process-instance /
- * plan filters match the correlation-enriched fields; since/until bound createdAt.
+ * plan / instance filters match the correlation-enriched fields; since/until bound createdAt.
  */
 export function listTranscripts(
   store: TranscriptStore,
   correlation: CorrelationRegistry | undefined,
   filter: TranscriptFilter = {},
+  durable?: AgenticCorrelationStore | undefined,
 ): AgenticTranscript[] {
   const sinceMs = filter.since !== undefined ? Date.parse(filter.since) : undefined;
   const untilMs = filter.until !== undefined ? Date.parse(filter.until) : undefined;
   const rows = store
     .list()
-    .map((meta) => toTranscript(meta, store, correlation))
+    .map((meta) => toTranscript(meta, store, correlation, durable))
     .filter((t) => {
       if (filter.jobKey !== undefined && t.jobKey !== filter.jobKey) return false;
       if (filter.processInstanceKey !== undefined && t.processInstanceKey !== filter.processInstanceKey) 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);
       if (sinceMs !== undefined && Number.isFinite(createdMs) && createdMs < sinceMs) return false;
       if (untilMs !== undefined && Number.isFinite(createdMs) && createdMs > untilMs) return false;
@@ -134,6 +170,7 @@ export function readTranscriptFrom(
   from: number,
   store: TranscriptStore,
   correlation: CorrelationRegistry | undefined,
+  durable?: AgenticCorrelationStore | undefined,
 ): AgenticTranscriptData | undefined {
   const meta = store.get(stream);
   if (meta === undefined) return undefined;
@@ -152,11 +189,14 @@ export function readTranscriptFrom(
     entries,
   };
   if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
-  const fields = correlationFieldsFor(meta.stream, correlation);
+  const fields = correlationFieldsFor(meta.stream, correlation, durable);
   if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
   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.planKey !== undefined) out.planKey = fields.planKey;
+  if (fields.instance !== undefined) out.instance = fields.instance;
+  if (fields.identity !== undefined) out.identity = fields.identity;
+  if (fields.host !== undefined) out.host = fields.host;
   return out;
 }

package/app/conformance.test.ts

@@ -3,6 +3,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
 import { memBlackboardSource } from "../test/blackboardDb.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import { appendEntry } from "./blackboard.ts";
 import {
   acknowledgeConformance,
@@ -45,7 +46,7 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
       },
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk), source: memBlackboardSource().source } as any as DataLayer;
+  const data = { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)), source: memBlackboardSource().source } as any as DataLayer;
   return { data, stores };
 }
 

package/app/conformance.ts

@@ -17,6 +17,7 @@
 import type { DataLayer } from "@nanobpm/urban";
 import { type BlackboardEntry, isUniqueViolation, readBlackboard } from "./blackboard.ts";
 import { TERMINAL_STATUSES } from "./delivery.ts";
+import { derivedTrackingTable } from "./instanceTracking.ts";
 import { planTasks } from "./plan.ts";
 
 const now = () => new Date().toISOString();
@@ -45,15 +46,20 @@ interface PlanRow extends Record<string, unknown> {
 
 const plansTbl = (data: DataLayer) => data.table<PlanRow>("plans", "plan_key");
 const prsTbl = (data: DataLayer) =>
-  data.table<{ pr_key: string; status: string }>("pull_requests", "pr_key");
+  derivedTrackingTable<{ pr_key: string; derived_status: string }>(
+    data,
+    "pull_requests",
+    "pr_key",
+  );
 
 /** A slice's PR "landed" iff it exists and reached a non-abandoned terminal status. The single
  * predicate both {@link gatherConformance} and {@link hasDeliveredImplementationForPlan} apply, so
- * the full digest and the cheap trigger check can't disagree about what counts as landed. */
+ * the full digest and the cheap trigger check can't disagree about what counts as landed. Reads the
+ * ADR-0065 derived edge so an out-of-band-terminated PR is correctly excluded from "landed". */
 async function isLanded(data: DataLayer, prKey: string | null | undefined): Promise<boolean> {
   if (!prKey) return false;
   const pr = await prsTbl(data).get(prKey);
-  return !!pr && LANDED_PR_STATUSES.has(pr.status);
+  return !!pr && LANDED_PR_STATUSES.has(pr.derived_status);
 }
 const conformanceTbl = (data: DataLayer) =>
   data.table<{ plan_key: string } & Record<string, unknown>>("plan_conformance", "plan_key");

package/app/featureDelivery.test.ts

@@ -6,6 +6,7 @@
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import { deriveFeatureDelivery } from "./feature.ts";
 import { pollFeatureDelivery } from "./service.ts";
 
@@ -34,7 +35,7 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
       },
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  const data = { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)) } as any as DataLayer;
   return { data, stores };
 }
 

package/app/instanceTracking.ts

@@ -0,0 +1,97 @@
+// nano-workforce — the app's single accessor for the `instanceTracking` derived read models
+// (ADR 0065, the writer→source inversion adopted with `@nanobpm/urban@0.81.0`).
+//
+// Since ADR 0065 the `instanceTracking` reconciler is a SOURCE, not a writer: on each poll it feeds
+// engine truth into urban's canonical projections (`urban_instance_state`, `urban_open_user_tasks`)
+// and NO LONGER writes the terminal (`onTerminated.set`) / wait-on-human (`onWaitingHuman.set`)
+// edges onto the app's base row. Those edges are now DERIVED — recomputed on every read — by an
+// auto-provisioned managed VIEW `<table>__tracking` whose `derived_status` column is
+// `CASE WHEN terminated THEN <onTerminated value> WHEN waiting-human THEN <onWaitingHuman value>
+// ELSE base.<statusField> END`. So the base `statusField` keeps only the worker-owned transient
+// status, and any reader that used to rely on the reconciler having written the terminal status
+// onto the base row must read `derived_status` off the VIEW instead.
+//
+// This module is the ONE place that:
+//   - parses the `instanceTracking` bindings from `nano.app.json` (the single source of truth), and
+//   - resolves each binding's derived VIEW name + `derived_status` column via urban's OWN target
+//     resolver (`instanceTrackingReadModelTarget`), so the app can never drift from the framework's
+//     view naming.
+//
+// Writers are unchanged: a service-task worker that owns a terminal outcome (`converged`, `merged`,
+// `done`, …) still writes it to the base `data.table(<table>)`. Only readers that classify on the
+// RECONCILER-derived edge (terminated → abandoned/failed/reviewed, or waiting-human →
+// awaiting_operator) route through the derived VIEW here.
+
+import { readFileSync } from "node:fs";
+import {
+  type AppManifest,
+  type DataLayer,
+  type InstanceTracking,
+  instanceTrackingReadModelTarget,
+  type Table,
+} from "@nanobpm/urban";
+
+/** The app manifest, parsed exactly ONCE at module load, typed by urban's own `AppManifest` so the
+ *  binding shape can never drift from the framework's schema. */
+const APP_MANIFEST: AppManifest = JSON.parse(
+  readFileSync(new URL("../nano.app.json", import.meta.url), "utf8"),
+);
+
+/** The app manifest's `instanceTracking` bindings — the single source of truth for the derived
+ *  read-model registry. */
+const INSTANCE_TRACKING_BINDINGS: readonly InstanceTracking[] = APP_MANIFEST.instanceTracking ?? [];
+
+/** The single `instanceTracking` binding for a base table, or throw if the manifest has none. */
+export function trackingBindingFor(table: string): InstanceTracking {
+  const binding = INSTANCE_TRACKING_BINDINGS.find((b) => b.table === table);
+  if (!binding) {
+    throw new Error(`nano.app.json: no instanceTracking binding for table "${table}"`);
+  }
+  return binding;
+}
+
+/** A tracked table's parked-and-active statuses, from the single source of truth
+ *  (`instanceTracking.<table>.activeStatuses` in nano.app.json), so an app-side scan can never drift
+ *  from the reconciler's notion of "in-flight". Throws if the binding is missing/empty. */
+export function activeStatusesFor(table: string): readonly string[] {
+  const binding = trackingBindingFor(table);
+  if (!binding.activeStatuses?.length) {
+    throw new Error(
+      `nano.app.json: instanceTracking[table="${table}"].activeStatuses is missing or empty`,
+    );
+  }
+  return binding.activeStatuses;
+}
+
+/** The managed derived read-model VIEW name + effective-status column for a base table, resolved by
+ *  urban's OWN target resolver so the app never drifts from the framework's `<table>__tracking` /
+ *  `derived_status` naming (ADR 0065). */
+export function trackingTargetFor(table: string): { view: string; statusColumn: string } {
+  return instanceTrackingReadModelTarget(trackingBindingFor(table));
+}
+
+/** The base table a derived tracking VIEW projects, or undefined when `view` is not a tracking view.
+ * The inverse of {@link trackingTargetFor}, resolved off the same binding registry so it can't drift
+ * from the framework's view naming. */
+export function baseTableForTrackingView(view: string): string | undefined {
+  return INSTANCE_TRACKING_BINDINGS.find((b) => trackingTargetFor(b.table).view === view)?.table;
+}
+
+/** The base `statusField` a binding's derived edge falls through to when no terminal/wait edge
+ * applies (the VIEW's `ELSE base.<statusField>` branch). Defaults to `"status"`, mirroring urban. */
+export function baseStatusFieldFor(table: string): string {
+  return trackingBindingFor(table).statusField ?? "status";
+}
+
+/** A read-only typed gateway over a tracked table's derived VIEW (`<table>__tracking`). The VIEW
+ *  re-exports `base.*` plus the derived `derived_status` column, so a row carries BOTH the base
+ *  transient `<statusField>` and the effective (ADR-0065-derived) `derived_status`. Read
+ *  `derived_status` to classify on the terminal / wait-on-human edge; urban forbids writing a VIEW,
+ *  so use `data.table(<table>)` for writes. `T` should include `derived_status: string`. */
+export function derivedTrackingTable<T extends object>(
+  data: DataLayer,
+  table: string,
+  pk: string,
+): Table<T> {
+  return data.table<T>(trackingTargetFor(table).view, pk);
+}

package/app/lineage.test.ts

@@ -6,6 +6,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import {
   deriveLineage,
   type LineagePr,
@@ -176,7 +177,7 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
       },
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  const data = { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)) } as any as DataLayer;
   return { data, stores };
 }