@nanobpm/agentic 0.1.0

package/src/relay/scheduler.ts

@@ -0,0 +1,208 @@
+/**
+ * The three-lane QoS scheduler — S5's outbound egress for one consumer socket.
+ *
+ * The channel carries three lanes in STRICT priority: control/facts >
+ * interactive > bulk (invariant #5). The relay data plane is high-volume `bulk`
+ * traffic; heartbeats, blackboard writes and relay control acks ride control /
+ * interactive. The load-bearing guarantee: a bulk-output storm must NEVER
+ * head-of-line-block a control or interactive frame.
+ *
+ * Two mechanisms enforce it:
+ *
+ *  1. **Strict lane priority.** {@link QosScheduler.flush} drains all control,
+ *     then all interactive, then bulk. Control/interactive are never gated, so a
+ *     queued heartbeat is emitted ahead of any bulk backlog. Cross-lane order is
+ *     DERIVED from S0's {@link compareFrameOrder} (asserted in the tests).
+ *
+ *  2. **Credit-based backpressure on the bulk lane.** A slow consumer grants
+ *     credit for how many bulk frames it can accept; the scheduler emits bulk
+ *     only while credit remains. With zero credit, bulk buffers (bounded — see
+ *     `bulkCapacity`) while control/interactive still flow freely. The buffered
+ *     bulk tail is safe to shed because the {@link ReplayRing} retains it for a
+ *     later resume-from-offset.
+ */
+import { compareFrameOrder, lanePriority } from "../protocol/index.ts";
+import type { Frame } from "../protocol/index.ts";
+import { addSafeInt, isNonNegInt, isPosInt } from "./validate.ts";
+
+export interface QosSchedulerOptions {
+  /** Where drained frames are emitted (typically the connection's `send`). */
+  readonly sink: (frame: Frame) => void;
+  /** Initial bulk credit. Default 0 — bulk stays buffered until credit is granted. */
+  readonly credit?: number;
+  /**
+   * Maximum buffered bulk frames before overflow sheds the oldest. Default 1024.
+   * Shedding is safe: the replay ring retains evicted chunks for resume. Control
+   * and interactive frames are never shed.
+   */
+  readonly bulkCapacity?: number;
+}
+
+const DEFAULT_BULK_CAPACITY = 1024;
+
+export class QosScheduler {
+  readonly #sink: (frame: Frame) => void;
+  readonly #bulkCapacity: number;
+  readonly #control: Frame[] = [];
+  readonly #interactive: Frame[] = [];
+  // The bulk lane is a fixed-size circular buffer: both overflow shedding and
+  // credit-gated draining advance a head index in O(1)/O(k) rather than
+  // Array.shift() (O(n) per frame). Under the sustained "bulk storm" this
+  // scheduler exists to absorb, shift() would degrade to O(n²). Same eviction
+  // discipline as ReplayRing: overwrite the oldest slot, advance the head.
+  readonly #bulk: (Frame | undefined)[] = [];
+  #bulkHead = 0;
+  #bulkCount = 0;
+  #credit: number;
+  #shed = 0;
+
+  constructor(options: QosSchedulerOptions) {
+    if (options.credit !== undefined && !isNonNegInt(options.credit)) {
+      throw new RangeError(`QosScheduler credit must be a non-negative integer, got ${options.credit}`);
+    }
+    const bulkCapacity = options.bulkCapacity ?? DEFAULT_BULK_CAPACITY;
+    if (!isPosInt(bulkCapacity)) {
+      throw new RangeError(`QosScheduler bulkCapacity must be a positive integer, got ${bulkCapacity}`);
+    }
+    this.#sink = options.sink;
+    this.#credit = options.credit ?? 0;
+    this.#bulkCapacity = bulkCapacity;
+    this.#bulk.length = bulkCapacity;
+  }
+
+  /** Remaining bulk credit. */
+  get credit(): number {
+    return this.#credit;
+  }
+
+  /** Frames buffered but not yet emitted (across all lanes). */
+  get pending(): number {
+    return this.#control.length + this.#interactive.length + this.#bulkCount;
+  }
+
+  /** Bulk frames buffered awaiting credit. */
+  get pendingBulk(): number {
+    return this.#bulkCount;
+  }
+
+  /** How many bulk frames have been shed on overflow over this scheduler's life. */
+  get shed(): number {
+    return this.#shed;
+  }
+
+  /**
+   * Buffer a frame on its lane and drain what is now eligible. Control and
+   * interactive frames drain immediately (never credit-gated); a bulk frame
+   * drains only if credit is available, otherwise it waits (or sheds the oldest
+   * bulk frame if the bulk buffer is full).
+   */
+  enqueue(frame: Frame): void {
+    switch (frame.lane) {
+      case "control":
+        this.#control.push(frame);
+        break;
+      case "interactive":
+        this.#interactive.push(frame);
+        break;
+      case "bulk":
+        this.#pushBulk(frame);
+        break;
+    }
+    this.flush();
+  }
+
+  /** Grant `n` more bulk credits, then drain any bulk frames that credit now allows. */
+  grantCredit(n: number): void {
+    if (!isNonNegInt(n)) {
+      throw new RangeError(`grantCredit requires a non-negative integer, got ${n}`);
+    }
+    this.#credit = addSafeInt(this.#credit, n, "QosScheduler credit");
+    this.flush();
+  }
+
+  /**
+   * Drain eligible frames to the sink in strict lane priority: all control, then
+   * all interactive, then bulk up to the available credit. Control/interactive
+   * are never head-of-line-blocked by bulk backlog or exhausted credit.
+   */
+  flush(): void {
+    // Remove eligible frames up-front, then emit. Removing before the sink call
+    // preserves "remove before sink" semantics (a re-entrant flush() from within
+    // sink() cannot re-emit an already-taken frame) and keeps the drain O(k) in
+    // the number of frames actually emitted, not O(n²): repeated Array.shift()
+    // is O(n) per element and degrades on a large bulk burst — exactly the storm
+    // this scheduler exists to absorb.
+    //
+    // Guard each splice with a length check: enqueue() calls flush() on every
+    // frame, so in the bulk-storm / zero-credit case the control and interactive
+    // lanes are usually empty. splice(0) on an empty array still allocates a new
+    // (empty) array, so skipping it keeps the empty-lane hot path allocation-free.
+    if (this.#control.length > 0) {
+      for (const frame of this.#control.splice(0)) {
+        this.#sink(frame);
+      }
+    }
+    if (this.#interactive.length > 0) {
+      for (const frame of this.#interactive.splice(0)) {
+        this.#sink(frame);
+      }
+    }
+    // Drain the bulk lane one frame at a time rather than removing the whole
+    // credit-worth up-front. Removing the frame (and spending its credit) only
+    // as it is emitted keeps "remove before sink" — a re-entrant flush() from
+    // within sink() still cannot re-emit an in-flight frame — while making the
+    // drain robust to a throwing sink: if #sink() throws mid-drain, the un-taken
+    // tail stays buffered in the ring and its credit is untouched, so a transient
+    // send failure sheds at most the one frame it was called with instead of
+    // silently dropping the rest of the backlog and burning their credit.
+    while (this.#credit > 0 && this.#bulkCount > 0) {
+      const bulkFrame = this.#shiftBulk();
+      if (bulkFrame === undefined) {
+        continue;
+      }
+      this.#credit -= 1;
+      this.#sink(bulkFrame);
+    }
+  }
+
+  /** Discard every buffered frame (e.g. on subscriber teardown). */
+  clear(): void {
+    this.#control.length = 0;
+    this.#interactive.length = 0;
+    this.#bulk.fill(undefined);
+    this.#bulkHead = 0;
+    this.#bulkCount = 0;
+  }
+
+  /**
+   * Append a bulk frame to the circular buffer, shedding the oldest buffered
+   * bulk frame first when already at capacity (safe: the ReplayRing retains it
+   * for resume). All O(1) — no Array.shift().
+   */
+  #pushBulk(frame: Frame): void {
+    if (this.#bulkCount === this.#bulkCapacity) {
+      this.#bulk[this.#bulkHead] = undefined;
+      this.#bulkHead = (this.#bulkHead + 1) % this.#bulkCapacity;
+      this.#bulkCount -= 1;
+      this.#shed += 1;
+    }
+    this.#bulk[(this.#bulkHead + this.#bulkCount) % this.#bulkCapacity] = frame;
+    this.#bulkCount += 1;
+  }
+
+  /** Remove and return the oldest bulk frame from the circular buffer (O(1)). */
+  #shiftBulk(): Frame | undefined {
+    const frame = this.#bulk[this.#bulkHead];
+    this.#bulk[this.#bulkHead] = undefined;
+    this.#bulkHead = (this.#bulkHead + 1) % this.#bulkCapacity;
+    this.#bulkCount -= 1;
+    return frame;
+  }
+}
+
+/**
+ * Re-exported from S0 so callers reason about lane ordering from one source
+ * rather than re-deriving priority. The scheduler's drain order (with unlimited
+ * credit) is asserted equal to a stable sort by {@link compareFrameOrder}.
+ */
+export { compareFrameOrder, lanePriority };

package/src/relay/validate.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { addSafeInt, isNonNegInt, isPosInt } from "./validate.ts";
+
+// Defect-class guard: relay integers are accumulated/decremented and round-trip
+// through JSON, so a value beyond Number.MAX_SAFE_INTEGER would silently lose
+// precision. The canonical guards must reject unsafe integers, not merely
+// non-integers — this is the single rule every validation site derives from.
+const UNSAFE = Number.MAX_SAFE_INTEGER + 1;
+
+test("isNonNegInt accepts non-negative safe integers", () => {
+  for (const v of [0, 1, 2, 100, Number.MAX_SAFE_INTEGER]) {
+    assert.equal(isNonNegInt(v), true, `${v} should be a non-negative safe integer`);
+  }
+});
+
+test("isNonNegInt rejects unsafe, negative, fractional, and non-number values", () => {
+  for (const v of [UNSAFE, -1, -UNSAFE, 1.5, Number.NaN, Number.POSITIVE_INFINITY, "1", null, undefined, {}]) {
+    assert.equal(isNonNegInt(v), false, `${String(v)} should be rejected`);
+  }
+});
+
+test("isPosInt accepts positive safe integers only", () => {
+  for (const v of [1, 2, 100, Number.MAX_SAFE_INTEGER]) {
+    assert.equal(isPosInt(v), true, `${v} should be a positive safe integer`);
+  }
+  for (const v of [0, UNSAFE, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, "1", null, undefined]) {
+    assert.equal(isPosInt(v), false, `${String(v)} should be rejected`);
+  }
+});
+
+test("addSafeInt sums non-negative safe integers", () => {
+  assert.equal(addSafeInt(0, 1, "x"), 1);
+  assert.equal(addSafeInt(5, 7, "x"), 12);
+  assert.equal(addSafeInt(Number.MAX_SAFE_INTEGER - 1, 1, "x"), Number.MAX_SAFE_INTEGER);
+});
+
+test("addSafeInt fails fast when accumulation would leave the safe-integer range", () => {
+  // Both operands are individually safe, but their sum is not — a value that
+  // would silently lose precision under further arithmetic/JSON round-trips.
+  assert.throws(() => addSafeInt(Number.MAX_SAFE_INTEGER, 1, "credit"), RangeError);
+  assert.throws(() => addSafeInt(Number.MAX_SAFE_INTEGER - 1, 2, "offset"), RangeError);
+});

package/src/relay/validate.ts

@@ -0,0 +1,44 @@
+/**
+ * Canonical safe-integer validators for the relay package.
+ *
+ * Every integer the relay handles — replay offsets, ring/bulk capacities,
+ * credit budgets, incarnation generations, and untrusted inbound protocol
+ * fields (`from`, `credit`, `incarnation`) — is accumulated, decremented,
+ * compared, or round-tripped through JSON. A value beyond
+ * `Number.MAX_SAFE_INTEGER` cannot survive that arithmetic or JSON round-trip
+ * without silent precision loss, which would corrupt offset/credit semantics.
+ * `Number.isSafeInteger` (not `Number.isInteger`) is therefore the single
+ * correct predicate. Deriving every integer check from these two guards keeps
+ * that rule in one place instead of scattering `Number.isInteger(x) || x < 0`
+ * across the package, where one site could drift from the rest.
+ */
+
+/** A non-negative safe integer: `0, 1, … Number.MAX_SAFE_INTEGER`. */
+export function isNonNegInt(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** A positive safe integer: `1, 2, … Number.MAX_SAFE_INTEGER`. */
+export function isPosInt(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+
+/**
+ * Add a delta to a running counter, failing fast if the sum would leave the
+ * safe-integer range. Validating each individual input with the guards above is
+ * necessary but not sufficient: relay counters (bulk credit, replay offsets)
+ * accumulate across many operations, so repeated additions of individually-safe
+ * values can still push the running total past `Number.MAX_SAFE_INTEGER`, where
+ * it silently loses precision and corrupts credit/offset semantics. Every
+ * counter that accumulates derives its overflow check from here rather than
+ * re-implementing the boundary. `label` names the counter for the error.
+ */
+export function addSafeInt(current: number, delta: number, label: string): number {
+  const sum = current + delta;
+  if (!Number.isSafeInteger(sum)) {
+    throw new RangeError(
+      `${label} overflowed the safe-integer range (${current} + ${delta} exceeds Number.MAX_SAFE_INTEGER)`,
+    );
+  }
+  return sum;
+}

package/src/transcript/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @nanobpm/agentic-transcript — the transcript store for the Nano agentic
+ * protocol (ADR 0056, slice S6).
+ *
+ * Retention-by-lifecycle over the app DataLayer/SQLite ({@link TranscriptStore}):
+ * an ephemeral run flushes the S5 relay ring to a durable, readable transcript on
+ * job completion; a long-lived stream retains its chunks so a reconnecting
+ * consumer can resume-from-offset (reattach). It builds on the S5 relay's
+ * resume-from-offset semantics (`@nanobpm/agentic-relay`) and stores through the
+ * app DataLayer only — nothing rides the Camunda-8 engine or its transport.
+ *
+ * The new DB schema ships as the forward-only, additive migration
+ * `db/migrations/002_agentic_transcript.sql`, mirrored by {@link TRANSCRIPT_SCHEMA_SQL}
+ * and kept in lockstep by a drift-guard test.
+ */
+export { TranscriptStore, TranscriptCorruptionError, TranscriptLifecycleError, systemClock } from "./store.ts";
+export type {
+  Clock,
+  SqliteDb,
+  TranscriptChunk,
+  TranscriptLifecycle,
+  TranscriptRing,
+  TranscriptSlice,
+  TranscriptStatus,
+  TranscriptStoreOptions,
+  TranscriptStream,
+} from "./store.ts";
+
+export {
+  TRANSCRIPT_CHUNK_TABLE,
+  TRANSCRIPT_SCHEMA_SQL,
+  TRANSCRIPT_STREAM_TABLE,
+} from "./schema.ts";

package/src/transcript/integration.test.ts

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, test } from "node:test";
+// Import the real S5 relay ring from source so this package's tests need no
+// prebuilt relay dist. The store flushes exactly this resume-from-offset source.
+import { ReplayRing } from "../relay/index.ts";
+import { TranscriptStore } from "./store.ts";
+import { openTestDb, type TestDb } from "./test-db.ts";
+
+let db: TestDb;
+afterEach(() => db.close());
+beforeEach(() => {
+  db = openTestDb();
+});
+
+test("acceptance: an ephemeral run flushes the S5 ring to a durable, readable transcript on completion", () => {
+  const store = new TranscriptStore(db);
+  store.ensureSchema();
+
+  // A short ephemeral run produces terminal output into an S5 replay ring.
+  const ring = new ReplayRing({ capacity: 1024 });
+  const produced = ["$ npm test\n", "ok 1 - boots\n", "ok 2 - flushes\n", "# pass 2\n"];
+  for (const line of produced) ring.append(line);
+
+  // On job completion the ring is flushed to a durable transcript.
+  const flushed = store.flush("run-42", ring, "ephemeral");
+  assert.equal(flushed, produced.length);
+
+  const meta = store.get("run-42");
+  assert.equal(meta?.lifecycle, "ephemeral");
+  assert.equal(meta?.status, "completed", "an ephemeral flush completes the transcript");
+  assert.equal(meta?.nextOffset, ring.nextOffset);
+
+  // The transcript is durable and readable: full, in order, reconstructable.
+  assert.deepEqual(
+    store.read("run-42").map((c) => c.chunk),
+    produced,
+  );
+  // Durability across a fresh store handle over the same DB (no in-memory state).
+  const reopened = new TranscriptStore(db);
+  assert.deepEqual(
+    reopened.read("run-42").map((c) => c.chunk).join(""),
+    produced.join(""),
+  );
+});
+
+test("acceptance: a long-lived stream reattaches from offset across a consumer reconnect", () => {
+  const store = new TranscriptStore(db);
+  store.ensureSchema();
+
+  const ring = new ReplayRing({ capacity: 1024 });
+  const emit = (chunk: string) => {
+    const entry = ring.append(chunk);
+    // Long-lived: persist incrementally as the live stream advances.
+    store.record("session-1", [{ offset: entry.offset, chunk: entry.chunk }], "long-lived");
+  };
+
+  emit("line-0\n");
+  emit("line-1\n");
+  emit("line-2\n");
+
+  // A consumer that saw through offset 1 reconnects and reattaches from offset 2.
+  const resume = store.since("session-1", 2);
+  assert.equal(resume.gap, false);
+  assert.deepEqual(
+    resume.entries.map((e) => e.chunk),
+    ["line-2\n"],
+  );
+  assert.equal(resume.nextOffset, 3);
+
+  // The stream keeps advancing after the reattach; a from-0 reattach still works.
+  emit("line-3\n");
+  const full = store.since("session-1", 0);
+  assert.equal(full.gap, false);
+  assert.deepEqual(
+    full.entries.map((e) => e.offset),
+    [0, 1, 2, 3],
+  );
+  assert.equal(full.nextOffset, 4);
+});
+
+test("flush advances nextOffset to the ring's high-water mark even when early chunks were evicted", () => {
+  const store = new TranscriptStore(db);
+  store.ensureSchema();
+
+  // A small ring evicts its head: 5 produced, capacity 3 → only offsets 2,3,4 retained.
+  const ring = new ReplayRing({ capacity: 3 });
+  for (let i = 0; i < 5; i++) ring.append(`chunk-${i}`);
+  assert.equal(ring.nextOffset, 5);
+  assert.equal(ring.firstOffset, 2);
+
+  const flushed = store.flush("run-evict", ring, "ephemeral");
+  assert.equal(flushed, 3);
+
+  const meta = store.get("run-evict");
+  // The durable window is exactly what the ring still retained…
+  assert.equal(meta?.firstOffset, 2);
+  // …but nextOffset reflects everything ever produced, so reattach gap accounting
+  // downstream stays correct.
+  assert.equal(meta?.nextOffset, 5);
+
+  // A reattach from an evicted offset reports a gap (retention lost those chunks).
+  const slice = store.since("run-evict", 0);
+  assert.equal(slice.gap, true);
+  assert.deepEqual(
+    slice.entries.map((e) => e.offset),
+    [2, 3, 4],
+  );
+});

package/src/transcript/schema.test.ts

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import {
+  TRANSCRIPT_CHUNK_TABLE,
+  TRANSCRIPT_SCHEMA_SQL,
+  TRANSCRIPT_STREAM_TABLE,
+} from "./schema.ts";
+import { TranscriptStore } from "./store.ts";
+import { openTestDb } from "./test-db.ts";
+
+/**
+ * Normalise SQL for a drift comparison: drop `-- …` line comments, collapse all
+ * runs of whitespace to a single space, and trim. Two DDL scripts that create the
+ * same objects with the same columns normalise identically regardless of
+ * comments/indentation.
+ */
+function normaliseSql(sql: string): string {
+  return sql
+    .split("\n")
+    .map((line) => line.replace(/--.*$/, ""))
+    .join("\n")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const migrationPath = fileURLToPath(
+  new URL("../../../../db/migrations/002_agentic_transcript.sql", import.meta.url),
+);
+
+test("the boot migration and TranscriptStore's DDL do not drift", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(TRANSCRIPT_SCHEMA_SQL),
+    "db/migrations/002_agentic_transcript.sql must match TRANSCRIPT_SCHEMA_SQL — update both together",
+  );
+});
+
+test("the boot migration is forward-only and additive (IF NOT EXISTS, no drops/alters)", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_transcript_stream/);
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_transcript_chunk/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+});
+
+test("the migration takes prefix 002, after S2's 001 and before S7", () => {
+  // Numbering is a shared epic surface (see migration header). Guard the prefix so
+  // a rebase that renumbers is caught here rather than at merge time.
+  const stream = new URL("../../../../db/migrations/002_agentic_transcript.sql", import.meta.url).pathname;
+  assert.match(stream, /\/002_agentic_transcript\.sql$/);
+});
+
+test("ensureSchema creates both transcript tables idempotently", () => {
+  const db = openTestDb();
+  const store = new TranscriptStore(db);
+  store.ensureSchema();
+  store.ensureSchema();
+  const tables = db
+    .all<{ name: string }>(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN (?, ?) ORDER BY name",
+      [TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_STREAM_TABLE],
+    )
+    .map((r) => r.name);
+  assert.deepEqual(tables, [TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_STREAM_TABLE]);
+  db.close();
+});

package/src/transcript/schema.ts

@@ -0,0 +1,51 @@
+/**
+ * The canonical transcript-store schema.
+ *
+ * The DDL here is the single source of truth the {@link TranscriptStore} applies
+ * through {@link TranscriptStore.ensureSchema}. The very same statements are
+ * mirrored in the app-boot migration `db/migrations/002_agentic_transcript.sql`
+ * (applied by the DataLayer migration runner). To keep those two application
+ * paths from drifting, `schema.test.ts` normalises both and asserts they are
+ * statement-for-statement identical — divergence is a red test, not a silent
+ * production/boot mismatch.
+ *
+ * Two tables back the store:
+ *  - `agentic_transcript_stream` — one row per relay stream: its retention
+ *    lifecycle (`ephemeral` vs `long-lived`), its status (`open`/`completed`),
+ *    and the offset window (`first_offset` … `next_offset`) currently retained.
+ *  - `agentic_transcript_chunk` — the durable chunks, keyed `(stream, chunk_offset)`
+ *    so a flush/append is idempotent and reattach can slice from any offset.
+ *
+ * `chunk_offset` (not `offset`) is deliberate: `OFFSET` is a SQLite keyword, so
+ * the column is named to avoid quoting it in every statement.
+ */
+
+/** The per-stream metadata table name. */
+export const TRANSCRIPT_STREAM_TABLE = "agentic_transcript_stream";
+
+/** The durable per-chunk table name. */
+export const TRANSCRIPT_CHUNK_TABLE = "agentic_transcript_chunk";
+
+/**
+ * The canonical transcript-store DDL. Forward-only and additive; every column
+ * added here must also be added to the boot migration (the drift guard enforces
+ * it). Chunks are immutable once written — retention drops whole windows/streams,
+ * it never rewrites a chunk.
+ */
+export const TRANSCRIPT_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${TRANSCRIPT_STREAM_TABLE} (
+  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 ${TRANSCRIPT_CHUNK_TABLE} (
+  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_${TRANSCRIPT_STREAM_TABLE}_retention ON ${TRANSCRIPT_STREAM_TABLE} (lifecycle, status, completed_at);`;