@nanobpm/nano-workforce 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.53.0](https://github.com/nanobpm/nano-workforce/compare/v0.52.0...v0.53.0) (2026-08-13)
+
+
+### Features
+
+* relay ring + transcript store agentic family (H3) ([#162](https://github.com/nanobpm/nano-workforce/issues/162)) ([f629526](https://github.com/nanobpm/nano-workforce/commit/f62952698fa3cfb3321e60fdce61fdb1f13ca9d6)), closes [#142](https://github.com/nanobpm/nano-workforce/issues/142) [#143](https://github.com/nanobpm/nano-workforce/issues/143) [#146](https://github.com/nanobpm/nano-workforce/issues/146) [#streams](https://github.com/nanobpm/nano-workforce/issues/streams)
+
 # [0.52.0](https://github.com/nanobpm/nano-workforce/compare/v0.51.0...v0.52.0) (2026-08-13)
 
 

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

@@ -0,0 +1,402 @@
+// Unit tests for the H3 relay ring + transcript store family (ADR 0056, #146).
+//
+// Exercises the acceptance surface of the mounted family through {@link RelayTranscriptService}:
+//   - ring resume: a late/reconnecting consumer replays from an offset with no loss or duplication;
+//   - lane priority: a bulk-output storm never head-of-line-blocks a control-lane frame;
+//   - retention-by-lifecycle: an ephemeral stream's transcript is persisted on completion (and swept
+//     after retention); a long-lived stream is checkpointed and stays reattachable, never auto-completed;
+//   - disconnect-driven completion: an ephemeral stream flushes when its producer connection drops.
+// Plus a drift guard proving `db/migrations/024_agentic_transcript.sql` mirrors the package's canonical
+// transcript DDL byte-for-byte.
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { ConnectionRegistry } from "@nanobpm/agentic/channel";
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
+import { type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
+import { assert, assertEquals } from "#test-assert";
+import { noopLog } from "../../../test/log.ts";
+import {
+  createRelayFamily,
+  family as relayFamily,
+  RELAY_FAMILY_NAME,
+  RelayTranscriptService,
+} from "./relay.family.ts";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** An in-memory {@link SqliteDb} over `node:sqlite`, matching the store's exec/run/all surface. */
+function memoryDb(): 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[],
+  };
+}
+
+/** An in-memory {@link SqliteDb} whose exec/run/all can be flipped to throw, to exercise advisory resilience. */
+function flakyDb(): { db: SqliteDb; fail: (on: boolean) => void } {
+  const raw = new DatabaseSync(":memory:");
+  let failing = false;
+  const guard = <T>(fn: () => T): T => {
+    if (failing) throw new Error("sqlite unavailable");
+    return fn();
+  };
+  return {
+    db: {
+      exec: (sql) => guard(() => raw.exec(sql)),
+      run: (sql, params = []) => guard(() => raw.prepare(sql).run(...params)),
+      all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []): T[] =>
+        guard(() => raw.prepare(sql).all(...params) as T[]),
+    },
+    fail: (on: boolean) => {
+      failing = on;
+    },
+  };
+}
+
+/** A hub double that just captures the family handler so the test can drive frames directly. */
+interface CapturingHub {
+  handler?: (frame: Frame, conn: RelayConn) => void;
+  registerFamilyHandler(family: string, handler: (frame: Frame, conn: RelayConn) => void): void;
+}
+
+interface RelayConn {
+  readonly id: string;
+  readonly registry: { has(id: string): boolean };
+  send(frame: Frame): void;
+}
+
+function capturingHub(): CapturingHub {
+  return {
+    registerFamilyHandler(_family, handler) {
+      this.handler = handler;
+    },
+  };
+}
+
+/** A live fake connection registered in `registry`, collecting frames the hub sends back to it. */
+function connect(id: string, registry: ConnectionRegistry): { conn: RelayConn; sent: Frame[] } {
+  registry.add(id, `identity:${id}`);
+  const sent: Frame[] = [];
+  return { conn: { id, registry, send: (f) => sent.push(f) }, sent };
+}
+
+const produce = (stream: string, incarnation: number, chunk: string): Frame => ({
+  lane: "bulk",
+  family: RELAY_FAMILY,
+  seq: 0,
+  payload: { op: "produce", stream, incarnation, chunk },
+});
+const subscribe = (stream: string, from: number, credit: number): Frame => ({
+  lane: "control",
+  family: RELAY_FAMILY,
+  seq: 0,
+  payload: { op: "subscribe", stream, from, credit },
+});
+const grant = (credit: number): Frame => ({
+  lane: "control",
+  family: RELAY_FAMILY,
+  seq: 0,
+  payload: { op: "credit", credit },
+});
+
+/** Read the `op` marker off a delivered frame payload without an unsafe cast. */
+function payloadOp(frame: Frame): unknown {
+  const p = frame.payload;
+  return p && typeof p === "object" && Object.hasOwn(p, "op")
+    ? Object.getOwnPropertyDescriptor(p, "op")?.value
+    : undefined;
+}
+function payloadField(frame: Frame, key: string): unknown {
+  const p = frame.payload;
+  return p && typeof p === "object" && Object.hasOwn(p, key)
+    ? Object.getOwnPropertyDescriptor(p, key)?.value
+    : undefined;
+}
+
+function mkService(registry: ConnectionRegistry, db: SqliteDb | undefined): {
+  service: RelayTranscriptService;
+  hub: CapturingHub;
+} {
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({ hub, registry, db, log: noopLog() });
+  return { service, hub };
+}
+
+test("the family exports a valid AgenticFamily named 'relay'", () => {
+  assertEquals(relayFamily.name, RELAY_FAMILY_NAME);
+  assertEquals(relayFamily.name, "relay");
+  assertEquals(typeof relayFamily.mount, "function");
+  assertEquals(typeof relayFamily.teardown, "function");
+  // createRelayFamily builds an independent instance with the same contract.
+  const another = createRelayFamily();
+  assertEquals(another.name, "relay");
+});
+
+test("ring resume: a late consumer replays from an offset with no loss or duplication", () => {
+  const registry = new ConnectionRegistry();
+  const { service, hub } = mkService(registry, memoryDb());
+  const p = connect("prod", registry);
+  for (let i = 0; i < 5; i++) hub.handler?.(produce("s", 1, `c${i}`), p.conn);
+
+  // A late consumer resumes from offset 2 with ample credit → gets exactly offsets 2,3,4 in order.
+  const late = connect("late", registry);
+  hub.handler?.(subscribe("s", 2, 100), late.conn);
+
+  const acks = late.sent.filter((f) => payloadOp(f) === "subscribed");
+  assertEquals(acks.length, 1);
+  assertEquals(payloadField(acks[0], "gap"), false);
+  assertEquals(payloadField(acks[0], "nextOffset"), 5);
+
+  const data = late.sent.filter((f) => payloadOp(f) === undefined); // data frames carry {stream,offset,chunk}
+  assertEquals(
+    data.map((f) => payloadField(f, "offset")),
+    [2, 3, 4],
+  );
+  assertEquals(
+    data.map((f) => payloadField(f, "chunk")),
+    ["c2", "c3", "c4"],
+  );
+
+  // A reconnect from 0 gets the whole retained window — still gap-free, no duplication.
+  const full = connect("full", registry);
+  hub.handler?.(subscribe("s", 0, 100), full.conn);
+  const fullData = full.sent.filter((f) => payloadOp(f) === undefined);
+  assertEquals(
+    fullData.map((f) => payloadField(f, "offset")),
+    [0, 1, 2, 3, 4],
+  );
+  service.teardown();
+});
+
+test("lane priority: a bulk storm never head-of-line-blocks a control frame", () => {
+  const registry = new ConnectionRegistry();
+  const { service, hub } = mkService(registry, memoryDb());
+  const p = connect("prod", registry);
+
+  // Consumer subscribes to stream A with ZERO bulk credit: it gets the control ack but no bulk.
+  const c = connect("cons", registry);
+  hub.handler?.(subscribe("A", 0, 0), c.conn);
+  assertEquals(c.sent.filter((f) => payloadOp(f) === "subscribed").length, 1);
+
+  // A bulk-output storm on A: every produce enqueues a bulk data frame, all credit-gated (buffered).
+  for (let i = 0; i < 200; i++) hub.handler?.(produce("A", 1, `x${i}`), p.conn);
+  const bulkBefore = c.sent.filter((f) => payloadOp(f) === undefined).length;
+  assertEquals(bulkBefore, 0, "bulk must stay buffered with zero credit — never force-flushed");
+
+  // A control-lane heartbeat (a second subscribe) MUST get through despite the buffered bulk backlog.
+  hub.handler?.(subscribe("B", 0, 0), c.conn);
+  assertEquals(
+    c.sent.filter((f) => payloadOp(f) === "subscribed").length,
+    2,
+    "control ack delivered ahead of the bulk backlog — control is never starved",
+  );
+  assertEquals(c.sent.filter((f) => payloadOp(f) === undefined).length, 0);
+
+  // Granting credit now releases the buffered bulk — nothing was lost, order preserved.
+  hub.handler?.(grant(300), c.conn);
+  const released = c.sent.filter((f) => payloadOp(f) === undefined);
+  assertEquals(released.length, 200);
+  assertEquals(payloadField(released[0], "chunk"), "x0");
+  assertEquals(payloadField(released[199], "chunk"), "x199");
+  service.teardown();
+});
+
+test("retention: an ephemeral stream's transcript is persisted on completion, then swept", () => {
+  const registry = new ConnectionRegistry();
+  const db = memoryDb();
+  const clock = { t: 1_000_000 };
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({
+    hub,
+    registry,
+    db,
+    log: noopLog(),
+    transcript: { ephemeralRetentionMs: 1000, clock: { now: () => clock.t } },
+  });
+  const p = connect("prod", registry);
+  for (let i = 0; i < 3; i++) hub.handler?.(produce("job-1", 1, `l${i}`), p.conn);
+
+  const flushed = service.completeStream("job-1");
+  assertEquals(flushed, 3);
+  const meta = service.transcriptOf("job-1");
+  assertEquals(meta?.lifecycle, "ephemeral");
+  assertEquals(meta?.status, "completed");
+  assertEquals(service.reattach("job-1", 0)?.entries.length, 3);
+
+  // Before the retention window elapses the sweep keeps it; after, it retires the transcript.
+  clock.t += 500;
+  assertEquals(service.sweep(), []);
+  clock.t += 1000;
+  assertEquals(service.sweep(), ["job-1"]);
+  assertEquals(service.transcriptOf("job-1"), undefined);
+  assert(!service.streams().includes("job-1"), "sweep forgets retired stream state — map stays bounded");
+  service.teardown();
+});
+
+test("retention: a disconnected producer auto-completes its ephemeral stream on the next frame", () => {
+  const registry = new ConnectionRegistry();
+  const db = memoryDb();
+  const { service, hub } = mkService(registry, db);
+  const p = connect("prod", registry);
+  for (let i = 0; i < 2; i++) hub.handler?.(produce("job-2", 1, `m${i}`), p.conn);
+  assertEquals(service.transcriptOf("job-2"), undefined, "not yet flushed while producer is live");
+
+  // Producer drops (S1 registry removed it on close/timeout). A subsequent inbound frame from any
+  // live connection reconciles the dead producer and flushes+completes its ephemeral stream.
+  registry.remove("prod");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn); // any frame drives #reconcile
+
+  const meta = service.transcriptOf("job-2");
+  assertEquals(meta?.status, "completed");
+  assertEquals(service.reattach("job-2", 0)?.entries.length, 2);
+  service.teardown();
+});
+
+test("retention: a long-lived stream is checkpointed + reattachable and never auto-completed", () => {
+  const registry = new ConnectionRegistry();
+  const db = memoryDb();
+  const { service, hub } = mkService(registry, db);
+  service.declareLifecycle("ctrl", "long-lived");
+  const p = connect("prod", registry);
+  for (let i = 0; i < 4; i++) hub.handler?.(produce("ctrl", 1, `k${i}`), p.conn);
+
+  const n = service.checkpointStream("ctrl");
+  assertEquals(n, 4);
+  assertEquals(service.transcriptOf("ctrl")?.status, "open");
+  assertEquals(service.reattach("ctrl", 2)?.entries.map((e) => e.chunk), ["k2", "k3"]);
+
+  // Producer drop must NOT complete a long-lived stream — it stays open for reattach.
+  registry.remove("prod");
+  const other = connect("cons", registry);
+  hub.handler?.(grant(0), other.conn);
+  assertEquals(service.transcriptOf("ctrl")?.status, "open");
+
+  // The retention sweep never time-retires an open long-lived stream.
+  assertEquals(service.sweep(2_000_000_000_000), []);
+  assertEquals(service.transcriptOf("ctrl")?.status, "open");
+  service.teardown();
+});
+
+test("teardown flushes still-open ephemeral streams so nothing in-flight is lost", () => {
+  const registry = new ConnectionRegistry();
+  const db = memoryDb();
+  const { service, hub } = mkService(registry, db);
+  const p = connect("prod", registry);
+  hub.handler?.(produce("open-job", 1, "z0"), p.conn);
+  assertEquals(service.transcriptOf("open-job"), undefined);
+
+  service.teardown();
+  assertEquals(service.transcriptOf("open-job")?.status, "completed");
+});
+
+test("advisory mode: with no DataLayer the relay still replays; persistence is a no-op", () => {
+  const registry = new ConnectionRegistry();
+  const { service, hub } = mkService(registry, undefined);
+  const p = connect("prod", registry);
+  for (let i = 0; i < 3; i++) hub.handler?.(produce("s", 1, `n${i}`), p.conn);
+
+  const c = connect("cons", registry);
+  hub.handler?.(subscribe("s", 0, 100), c.conn);
+  const data = c.sent.filter((f) => payloadOp(f) === undefined);
+  assertEquals(data.length, 3, "relay replay works without a store — advisory-correct");
+
+  assertEquals(service.completeStream("s"), 0);
+  assertEquals(service.reattach("s", 0), undefined);
+  assertEquals(service.sweep(), []);
+  service.teardown();
+});
+
+test("incarnation fencing: a stale producer cannot overwrite a newer incarnation's stream", () => {
+  const registry = new ConnectionRegistry();
+  const { service, hub } = mkService(registry, memoryDb());
+  const p = connect("prod", registry);
+  hub.handler?.(produce("s", 2, "new-a"), p.conn); // incarnation 2 establishes the mark
+  hub.handler?.(produce("s", 1, "stale"), p.conn); // incarnation 1 is fenced (dropped)
+  hub.handler?.(produce("s", 2, "new-b"), p.conn);
+
+  const c = connect("cons", registry);
+  hub.handler?.(subscribe("s", 0, 100), c.conn);
+  const chunks = c.sent.filter((f) => payloadOp(f) === undefined).map((f) => payloadField(f, "chunk"));
+  assertEquals(chunks, ["new-a", "new-b"], "the stale incarnation's chunk never entered the ring");
+  service.teardown();
+});
+
+test("advisory mode: a store that fails to initialize falls back to unpersisted — mount never throws", () => {
+  const registry = new ConnectionRegistry();
+  const { db, fail } = flakyDb();
+  fail(true); // schema application throws during construction
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({ hub, registry, db, log: noopLog() });
+  assertEquals(service.store, undefined, "store setup failure falls back to unpersisted, not a thrown mount");
+
+  // The relay still replays — advisory-correct even with no store.
+  const p = connect("prod", registry);
+  for (let i = 0; i < 3; i++) hub.handler?.(produce("s", 1, `n${i}`), p.conn);
+  const c = connect("cons", registry);
+  hub.handler?.(subscribe("s", 0, 100), c.conn);
+  assertEquals(c.sent.filter((f) => payloadOp(f) === undefined).length, 3);
+  assertEquals(service.completeStream("s"), 0);
+  service.teardown();
+});
+
+test("advisory resilience: a flush failure leaves the ephemeral stream uncompleted and never bubbles", () => {
+  const registry = new ConnectionRegistry();
+  const { db, fail } = flakyDb();
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({ hub, registry, db, log: noopLog() });
+  const p = connect("prod", registry);
+  for (let i = 0; i < 2; i++) hub.handler?.(produce("job", 1, `c${i}`), p.conn);
+
+  fail(true);
+  assertEquals(service.completeStream("job"), 0, "flush failure is swallowed and returns 0");
+
+  // Left uncompleted: once the store recovers, a later completion flushes the whole window.
+  fail(false);
+  assertEquals(service.completeStream("job"), 2);
+  assertEquals(service.transcriptOf("job")?.status, "completed");
+  service.teardown();
+});
+
+test("advisory resilience: a checkpoint flush failure keeps the long-lived stream open and returns 0", () => {
+  const registry = new ConnectionRegistry();
+  const { db, fail } = flakyDb();
+  const hub = capturingHub();
+  const service = new RelayTranscriptService({ hub, registry, db, log: noopLog() });
+  service.declareLifecycle("ctrl", "long-lived");
+  const p = connect("prod", registry);
+  for (let i = 0; i < 3; i++) hub.handler?.(produce("ctrl", 1, `k${i}`), p.conn);
+
+  fail(true);
+  assertEquals(service.checkpointStream("ctrl"), 0, "checkpoint failure is swallowed and returns 0");
+
+  fail(false);
+  assertEquals(service.checkpointStream("ctrl"), 3);
+  assertEquals(service.transcriptOf("ctrl")?.status, "open");
+  service.teardown();
+});
+
+test("drift guard: migration 024 mirrors the canonical transcript DDL byte-for-byte", async () => {
+  const migrationPath = join(HERE, "..", "..", "..", "db", "migrations", "024_agentic_transcript.sql");
+  const raw = await readFile(migrationPath, "utf8");
+  // Strip `-- …` comment lines; the DDL is the remaining statements.
+  const ddl = raw
+    .split("\n")
+    .filter((line) => !line.trimStart().startsWith("--"))
+    .join("\n");
+  const normalise = (s: string) => s.trim().replace(/\s+/g, " ");
+  assertEquals(
+    normalise(ddl),
+    normalise(TRANSCRIPT_SCHEMA_SQL),
+    "024_agentic_transcript.sql drifted from @nanobpm/agentic/transcript TRANSCRIPT_SCHEMA_SQL",
+  );
+  assert(ddl.includes("agentic_transcript_stream"));
+  assert(ddl.includes("agentic_transcript_chunk"));
+});

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

@@ -0,0 +1,331 @@
+// nano-workforce — the relay ring + transcript store agentic family (ADR 0056, H3 / #146).
+//
+// This is a sibling slice of the agentic-visibility epic (#142). It plugs into the H0 (#143)
+// family-registration SEAM (`../registry.ts`) as ONE NEW FILE and NOTHING ELSE — it never edits
+// `main.ts`, `drainAndExit`, or any shared boot line. The auto-discovery loader (`../loader.ts`)
+// finds it by the `*.family.ts` suffix and the seam mounts + tears it down.
+//
+// It composes two published primitives — it re-implements NEITHER:
+//   - `@nanobpm/agentic/relay`      — the bounded replay ring, three-lane QoS scheduler
+//     (control > interactive > bulk), resume-from-offset, and incarnation/generation fencing,
+//     all inside {@link RelayHub}. We mount it on the hub's `registerFamilyHandler` seam.
+//   - `@nanobpm/agentic/transcript` — {@link TranscriptStore}, retention-by-lifecycle over the app's
+//     SQLite DataLayer. Ephemeral streams flush the ring to a durable transcript on job completion;
+//     long-lived streams retain chunks so a reconnecting consumer resumes-from-offset (reattach).
+//
+// Its DB schema ships as the reserved forward-only additive migration
+// `db/migrations/024_agentic_transcript.sql` (H0 pre-allocated prefix 024 for H3), a byte-for-byte
+// mirror of the package's canonical `TRANSCRIPT_SCHEMA_SQL`, drift-guarded by this slice's test.
+//
+// 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 preserved (the
+// relay/transcript never hard-lock or gate a BPMN sequence flow).
+import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
+import {
+  type SqliteDb,
+  type TranscriptLifecycle,
+  type TranscriptRing,
+  type TranscriptSlice,
+  TranscriptStore,
+  type TranscriptStoreOptions,
+  type TranscriptStream,
+} from "@nanobpm/agentic/transcript";
+import type { Logger } from "@nanobpm/urban";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/** The stable family name this slice registers under the seam (distinct from the wire family key). */
+export const RELAY_FAMILY_NAME = "relay";
+
+/** Read a property off an unknown value without an unsafe `as` cast (mirrors the loader's helper). */
+function readProp(value: unknown, key: string): unknown {
+  if (!value || typeof value !== "object") return undefined;
+  return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+
+/**
+ * A resume-from-offset source with no retained chunks — used to flush/complete a stream that a
+ * producer opened logically but never wrote to, so its transcript is still stamped `completed`
+ * rather than left dangling `open`.
+ */
+const EMPTY_SOURCE: TranscriptRing = { since: () => ({ entries: [] }), nextOffset: 0 };
+
+/** Per-stream bookkeeping the service keeps to drive lifecycle-aware persistence. */
+interface StreamState {
+  /** Retention lifecycle: `ephemeral` (flush+complete on job end) vs `long-lived` (reattach). */
+  lifecycle: TranscriptLifecycle;
+  /** The connection id of the most recent producer, for disconnect-driven completion. */
+  producer?: string;
+  /** Set once an ephemeral stream has been flushed & completed (so it is not re-completed). */
+  completed: boolean;
+}
+
+export interface RelayTranscriptServiceOptions {
+  /** The app-tier hub; the service claims the `relay` family key via its registration seam. */
+  readonly hub: {
+    registerFamilyHandler(family: string, handler: (frame: Frame, conn: RelayConnectionCtx) => void): void;
+  };
+  /** The shared connection registry — its `has(id)` is the liveness source of truth. */
+  readonly registry: ConnectionRegistry;
+  /** The raw SQLite handle (the app DataLayer's `source().db`); absent → transcripts disabled. */
+  readonly db: SqliteDb | undefined;
+  /** A structured logger for lifecycle lines. */
+  readonly log: Logger;
+  /** Options forwarded to the underlying {@link RelayHub} (ring/bulk capacity, default credit). */
+  readonly relay?: RelayHubOptions;
+  /** Options forwarded to the {@link TranscriptStore} (retention window, injectable clock). */
+  readonly transcript?: TranscriptStoreOptions;
+  /**
+   * Apply the transcript DDL from the store on mount (idempotent `CREATE ... IF NOT EXISTS`).
+   * Default `true`: the boot migration is the canonical path, but this makes the service usable
+   * against a bare source too (and is harmless when the migration already ran).
+   */
+  readonly ensureSchema?: boolean;
+}
+
+/** The minimal per-connection surface the relay handler receives from the hub (a {@link RelayHub} `RelayConnection`). */
+interface RelayConnectionCtx {
+  readonly id: string;
+  readonly registry: { has(id: string): boolean };
+  send(frame: Frame): void;
+}
+
+/**
+ * Composes the S5 relay ({@link RelayHub}) with the S6 transcript store ({@link TranscriptStore})
+ * and wires retention-by-lifecycle. It owns NO ring/scheduler/store logic of its own — it observes
+ * `produce` ownership so an ephemeral stream is flushed & completed when its producer disconnects,
+ * and exposes the completion/checkpoint/reattach/sweep surface H6 (#149) and the app drive.
+ */
+export class RelayTranscriptService {
+  /** The mounted relay hub (ring + QoS scheduler + incarnation fence). Exposed for inspection/tests. */
+  readonly relay: RelayHub;
+  /** The transcript store, or `undefined` when no DataLayer is mounted (relay still works, unpersisted). */
+  readonly store: TranscriptStore | undefined;
+
+  readonly #registry: ConnectionRegistry;
+  readonly #log: Logger;
+  readonly #streams = new Map<string, StreamState>();
+
+  constructor(options: RelayTranscriptServiceOptions) {
+    this.#registry = options.registry;
+    this.#log = options.log;
+    // 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.
+    let store: TranscriptStore | undefined;
+    if (options.db) {
+      try {
+        store = new TranscriptStore(options.db, options.transcript);
+        if (options.ensureSchema !== false) store.ensureSchema();
+      } catch (err) {
+        this.#log.warn("agentic transcript store unavailable — relay runs unpersisted", {
+          err: String(err),
+        });
+        store = undefined;
+      }
+    }
+    this.store = store;
+
+    this.relay = new RelayHub({
+      ...options.relay,
+      onFenced: (stream, incarnation, current) => {
+        this.#log.warn("agentic relay fenced a stale producer", { stream, incarnation, current });
+        options.relay?.onFenced?.(stream, incarnation, current);
+      },
+      onError: (err, connectionId) => {
+        this.#log.warn("agentic relay message error", { connectionId, err: String(err) });
+        options.relay?.onError?.(err, connectionId);
+      },
+    });
+
+    // Register the `relay` family ourselves (rather than via `registerRelayFamily`) so we can observe
+    // `produce` ownership before delegating to the hub — the hub's own routing still derives purely
+    // from this single registration, and a second `relay` registration is rejected by the seam.
+    options.hub.registerFamilyHandler(RELAY_FAMILY, (frame, conn) => this.#onFrame(frame, conn));
+  }
+
+  /** The tracked stream names (those a producer opened or that were declared). */
+  streams(): string[] {
+    return [...this.#streams.keys()];
+  }
+
+  /**
+   * Declare a stream's retention lifecycle before (or independently of) its first `produce`. The
+   * durable store records lifecycle write-once (first call wins there); in memory the latest call
+   * wins until the stream completes, which is how {@link checkpointStream} upgrades an as-yet
+   * ephemeral stream to `long-lived`. No-op once the stream has already been completed.
+   */
+  declareLifecycle(stream: string, lifecycle: TranscriptLifecycle): void {
+    const state = this.#stateFor(stream);
+    if (!state.completed) state.lifecycle = lifecycle;
+  }
+
+  /**
+   * Complete a stream on job end: flush the relay ring (its whole retained window) to the durable
+   * transcript under the stream's lifecycle. For an `ephemeral` stream this stamps `completed_at`
+   * (so {@link reattach} then serves the durable transcript and {@link sweep} may later retire it);
+   * for a `long-lived` stream it is a snapshot checkpoint that leaves the stream `open`. Idempotent:
+   * re-completing already-persisted offsets is a no-op. Returns the number of newly-persisted chunks.
+   */
+  completeStream(stream: string): number {
+    if (!this.store) return 0;
+    const state = this.#stateFor(stream);
+    const source = this.relay.ring(stream) ?? EMPTY_SOURCE;
+    let flushed: number;
+    try {
+      flushed = this.store.flush(stream, source, state.lifecycle);
+    } catch (err) {
+      // Persistence is advisory: a flush failure must not bubble into the hub's frame handler and
+      // take down unrelated streams. Log and leave the stream uncompleted so a later pass retries.
+      this.#log.warn("agentic relay stream flush failed — leaving stream uncompleted", {
+        stream,
+        lifecycle: state.lifecycle,
+        err: String(err),
+      });
+      return 0;
+    }
+    if (state.lifecycle === "ephemeral") state.completed = true;
+    // Drop producer ownership so a later reconcile does not re-flush a completed stream.
+    state.producer = undefined;
+    this.#log.info("agentic relay stream flushed", {
+      stream,
+      lifecycle: state.lifecycle,
+      flushed,
+      completed: state.completed,
+    });
+    return flushed;
+  }
+
+  /**
+   * Snapshot a long-lived stream's ring into the durable transcript without completing it — the
+   * checkpoint path a growing stream uses so a reconnecting consumer can {@link reattach} past the
+   * ring's resume window. Returns the number of newly-persisted chunks.
+   */
+  checkpointStream(stream: string): number {
+    if (!this.store) return 0;
+    this.declareLifecycle(stream, "long-lived");
+    const source = this.relay.ring(stream) ?? EMPTY_SOURCE;
+    try {
+      return this.store.flush(stream, source, "long-lived");
+    } catch (err) {
+      // Advisory: a checkpoint failure keeps the relay usable — return 0, the stream stays open.
+      this.#log.warn("agentic relay checkpoint flush failed", { stream, err: String(err) });
+      return 0;
+    }
+  }
+
+  /**
+   * Reattach a consumer from offset `from` (inclusive) against the durable transcript — mirrors the
+   * relay ring's `since` contract exactly, so a late/reconnecting consumer resumes identically
+   * whether from the live ring or the persisted transcript. Returns `undefined` with no store.
+   */
+  reattach(stream: string, from: number): TranscriptSlice | undefined {
+    return this.store?.since(stream, from);
+  }
+
+  /** Retention sweep: retire completed-ephemeral transcripts past the retention window. */
+  sweep(now?: number): string[] {
+    const retired = this.store?.sweep(now) ?? [];
+    // Forget the in-memory state of every retired stream so `#streams` stays bounded (and
+    // `#reconcile`'s scan stays cheap) even after many ephemeral streams complete and age out.
+    for (const stream of retired) this.#streams.delete(stream);
+    return retired;
+  }
+
+  /** A stream's persisted transcript metadata, if any (lifecycle/status/offset window). */
+  transcriptOf(stream: string): TranscriptStream | undefined {
+    return this.store?.get(stream);
+  }
+
+  /**
+   * Complete every still-open ephemeral stream (e.g. on shutdown) so no in-flight terminal is lost,
+   * then forget all tracking. Long-lived streams are left for reattach and are not force-completed.
+   */
+  teardown(): void {
+    for (const [stream, state] of this.#streams) {
+      if (state.lifecycle === "ephemeral" && !state.completed) this.completeStream(stream);
+    }
+    this.#streams.clear();
+  }
+
+  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, then delegate. */
+  #onFrame(frame: Frame, conn: RelayConnectionCtx): void {
+    this.#reconcile();
+    this.#observe(frame, conn);
+    this.relay.handle(frame, conn);
+  }
+
+  /** Record `produce` ownership so a producer disconnect can drive ephemeral completion. */
+  #observe(frame: Frame, conn: RelayConnectionCtx): void {
+    if (readProp(frame.payload, "op") !== "produce") return;
+    const stream = readProp(frame.payload, "stream");
+    if (typeof stream !== "string" || stream === "") return;
+    this.#stateFor(stream).producer = conn.id;
+  }
+
+  /**
+   * Flush + complete every ephemeral stream whose producer connection is no longer live (the S1
+   * registry dropped it on close or liveness timeout). Lazy, like the relay hub's own dead-subscriber
+   * prune: it runs on each inbound frame, and shutdown covers the quiescent tail via {@link teardown}.
+   */
+  #reconcile(): void {
+    for (const [stream, state] of this.#streams) {
+      if (state.completed || state.lifecycle !== "ephemeral") continue;
+      if (state.producer !== undefined && !this.#registry.has(state.producer)) {
+        this.completeStream(stream);
+      }
+    }
+  }
+
+  #stateFor(stream: string): StreamState {
+    let state = this.#streams.get(stream);
+    if (state === undefined) {
+      state = { lifecycle: "ephemeral", completed: false };
+      this.#streams.set(stream, state);
+    }
+    return state;
+  }
+}
+
+/**
+ * Build the H3 relay family. Copy-of-the-seam pattern: it constructs the {@link RelayTranscriptService}
+ * in `mount` (threading the seam's hub/registry/DataLayer/log) and tears it down in `teardown`. The
+ * created service is exposed to `onMounted` so a driver (H6 correlation, tests) can reach the
+ * completion/reattach surface without re-mounting anything.
+ */
+export function createRelayFamily(options: {
+  readonly relay?: RelayHubOptions;
+  readonly transcript?: TranscriptStoreOptions;
+  readonly ensureSchema?: boolean;
+  /** Called with the live service once mounted, so a driver can drive completion/reattach. */
+  readonly onMounted?: (service: RelayTranscriptService) => void;
+} = {}): AgenticFamily {
+  let service: RelayTranscriptService | undefined;
+  return {
+    name: RELAY_FAMILY_NAME,
+    mount(ctx: AgenticContext): void {
+      service = new RelayTranscriptService({
+        hub: ctx.hub,
+        registry: ctx.registry,
+        // The app's SQLite handle: the same store the advisory blackboard uses. Absent → relay runs
+        // unpersisted (still advisory-correct), rather than failing the whole channel boot.
+        db: ctx.data ? ctx.data.source().db : undefined,
+        log: ctx.log,
+        relay: options.relay,
+        transcript: options.transcript,
+        ensureSchema: options.ensureSchema,
+      });
+      options.onMounted?.(service);
+    },
+    teardown(): void {
+      service?.teardown();
+      service = undefined;
+    },
+  };
+}
+
+/** The discovered family instance (the loader picks up this `family` export). */
+export const family: AgenticFamily = createRelayFamily();
+
+export default family;

package/db/migrations/024_agentic_transcript.sql

@@ -0,0 +1,43 @@
+-- Agentic visibility plane (ADR 0056, epic #142) — H3 relay transcript store (#146).
+--
+-- The relay family (app/agentic/families/relay.family.ts) mounts @nanobpm/agentic/relay (a bounded
+-- replay ring + three-lane QoS scheduler + incarnation fence) on the app-tier agentic channel and
+-- persists terminal transcripts through @nanobpm/agentic/transcript with retention-by-lifecycle:
+--
+--   • ephemeral streams  → the relay ring is flushed to a durable transcript on job completion
+--                          (and the stream marked `completed`, then retired by a retention sweep);
+--   • long-lived streams → chunks are retained/checkpointed so a reconnecting consumer can resume
+--                          from any offset (reattach), bounded by a rolling offset window.
+--
+-- This DDL is the forward-only, additive boot migration the DataLayer runner applies from
+-- nano.app.json (`data.sources.app.migrations`). It is a byte-for-byte mirror of the package's
+-- canonical `TRANSCRIPT_SCHEMA_SQL` (@nanobpm/agentic/transcript `schema.ts`), which the store also
+-- applies via `ensureSchema()`. The two application paths are kept from drifting by the drift-guard
+-- test `app/agentic/families/relay.family.test.ts` — divergence is a red test, not a silent boot vs.
+-- store mismatch. Additive only (CREATE ... IF NOT EXISTS): it adds no column to an existing table
+-- and drops nothing, so it is safe to apply forward over any earlier schema.
+--
+-- H0 (#143) pre-allocated this exact prefix (024) for H3 so no two sibling slices independently grab
+-- "the next" number (H1=023_agentic_presence, H4=025_agentic_blackboard). `chunk_offset` (not
+-- `offset`) is deliberate: OFFSET is a SQLite keyword, so the column avoids quoting in every query.
+--
+-- 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 preserved (the
+-- transcript never hard-locks or gates a BPMN sequence flow).
+CREATE TABLE IF NOT EXISTS agentic_transcript_stream (
+  stream        TEXT PRIMARY KEY,
+  lifecycle     TEXT NOT NULL,
+  status        TEXT NOT NULL DEFAULT 'open',
+  created_at    TEXT NOT NULL,
+  completed_at  TEXT,
+  first_offset  INTEGER,
+  next_offset   INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS agentic_transcript_chunk (
+  stream        TEXT NOT NULL,
+  chunk_offset  INTEGER NOT NULL,
+  chunk         TEXT NOT NULL,
+  appended_at   TEXT NOT NULL,
+  PRIMARY KEY (stream, chunk_offset)
+);
+CREATE INDEX IF NOT EXISTS idx_agentic_transcript_stream_retention ON agentic_transcript_stream (lifecycle, status, completed_at);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",