@nanobpm/agentic 0.1.0

package/dist/relay/ring.d.ts

@@ -0,0 +1,49 @@
+/** A single retained chunk and the offset it was assigned. */
+export interface ReplayEntry {
+    readonly offset: number;
+    readonly chunk: string;
+}
+export interface ReplayRingOptions {
+    /** Maximum number of retained chunks. Must be a positive integer. */
+    readonly capacity: number;
+}
+/** The result of a {@link ReplayRing.since} query. */
+export interface ReplaySlice {
+    /** The retained entries with `offset >= from`, in offset order. */
+    readonly entries: readonly ReplayEntry[];
+    /**
+     * `true` when `from` predates the oldest retained offset: some chunks the
+     * consumer asked for were already evicted, so the replay is not gap-free. The
+     * consumer should treat the returned tail as a best-effort resume, not a
+     * continuous stream from `from`.
+     */
+    readonly gap: boolean;
+}
+export declare class ReplayRing {
+    #private;
+    readonly capacity: number;
+    constructor(options: ReplayRingOptions);
+    /** Number of chunks currently retained. */
+    get size(): number;
+    /** The offset the next {@link append} will assign (also the total ever appended). */
+    get nextOffset(): number;
+    /** The oldest retained offset, or `undefined` when nothing is retained. */
+    get firstOffset(): number | undefined;
+    /**
+     * Append a chunk, assigning it the next offset. When the ring is at capacity
+     * the oldest retained chunk is evicted first (the offset counter still
+     * advances, so offsets stay monotonic and gap-free across eviction).
+     */
+    append(chunk: string): ReplayEntry;
+    /**
+     * Return the retained tail from offset `from` (inclusive), for resume. `from`
+     * is clamped to what is retained:
+     *  - `from <= firstOffset` → the whole retained window; `gap` is `true` when
+     *    `from` is strictly before the oldest retained offset (evicted chunks).
+     *  - `firstOffset < from <= nextOffset` → the exact suffix from `from`; no gap.
+     *  - `from > nextOffset` → empty (the consumer is ahead of the stream); no gap.
+     */
+    since(from: number): ReplaySlice;
+    /** Drop every retained chunk. The offset counter is NOT reset (offsets stay monotonic). */
+    clear(): void;
+}

package/dist/relay/ring.js

@@ -0,0 +1,105 @@
+/**
+ * The bounded replay ring — S5's resume-from-offset store for one relay stream.
+ *
+ * A live terminal stream is an append-only sequence of chunks. Each appended
+ * chunk is assigned a monotonic, gap-free `offset` (starting at 0). The ring
+ * retains only the most recent `capacity` chunks: older chunks are evicted so a
+ * long-running stream cannot grow unbounded.
+ *
+ * Resume-from-offset (the load-bearing property): when a consumer reconnects it
+ * asks for everything from the next offset it still needs. {@link ReplayRing.since}
+ * returns exactly the retained tail from that offset, and flags a `gap` when the
+ * requested offset predates what is still retained (i.e. the consumer was
+ * disconnected long enough that some chunks were evicted before it could resume).
+ * The stream itself survives the reconnect — the ring is the durable-enough
+ * window that makes resume possible.
+ */
+import { addSafeInt, isNonNegInt, isPosInt } from "./validate.js";
+export class ReplayRing {
+    capacity;
+    // Fixed-size circular buffer: eviction overwrites the oldest slot and advances
+    // the head in O(1), instead of Array.shift() (O(n) on every append once the
+    // ring is at steady-state capacity — a hotspot for high-throughput streams).
+    #buffer = [];
+    #head = 0;
+    #count = 0;
+    #nextOffset = 0;
+    constructor(options) {
+        if (!isPosInt(options.capacity)) {
+            throw new RangeError(`ReplayRing capacity must be a positive integer, got ${options.capacity}`);
+        }
+        this.capacity = options.capacity;
+        this.#buffer.length = options.capacity;
+    }
+    /** Number of chunks currently retained. */
+    get size() {
+        return this.#count;
+    }
+    /** The offset the next {@link append} will assign (also the total ever appended). */
+    get nextOffset() {
+        return this.#nextOffset;
+    }
+    /** The oldest retained offset, or `undefined` when nothing is retained. */
+    get firstOffset() {
+        return this.#count === 0 ? undefined : this.#buffer[this.#head]?.offset;
+    }
+    /**
+     * Append a chunk, assigning it the next offset. When the ring is at capacity
+     * the oldest retained chunk is evicted first (the offset counter still
+     * advances, so offsets stay monotonic and gap-free across eviction).
+     */
+    append(chunk) {
+        // Fail fast before mutating any state: compute the next offset first so an
+        // overflow throws atomically (the ring is left untouched) rather than after
+        // a partial append. Offsets accumulate forever, so guard the running total.
+        const offset = this.#nextOffset;
+        const nextOffset = addSafeInt(offset, 1, "ReplayRing offset");
+        const entry = { offset, chunk };
+        if (this.#count < this.capacity) {
+            this.#buffer[(this.#head + this.#count) % this.capacity] = entry;
+            this.#count += 1;
+        }
+        else {
+            // At capacity: overwrite the oldest slot and advance the head — O(1).
+            this.#buffer[this.#head] = entry;
+            this.#head = (this.#head + 1) % this.capacity;
+        }
+        this.#nextOffset = nextOffset;
+        return entry;
+    }
+    /**
+     * Return the retained tail from offset `from` (inclusive), for resume. `from`
+     * is clamped to what is retained:
+     *  - `from <= firstOffset` → the whole retained window; `gap` is `true` when
+     *    `from` is strictly before the oldest retained offset (evicted chunks).
+     *  - `firstOffset < from <= nextOffset` → the exact suffix from `from`; no gap.
+     *  - `from > nextOffset` → empty (the consumer is ahead of the stream); no gap.
+     */
+    since(from) {
+        if (!isNonNegInt(from)) {
+            throw new RangeError(`since(from) requires a non-negative integer, got ${from}`);
+        }
+        const first = this.firstOffset;
+        if (first === undefined || from >= this.#nextOffset) {
+            // Nothing retained, or the consumer already has everything.
+            return { entries: [], gap: first !== undefined && from < first };
+        }
+        const gap = from < first;
+        const startOffset = gap ? first : from;
+        const startIndex = startOffset - first;
+        const entries = [];
+        for (let i = startIndex; i < this.#count; i += 1) {
+            const entry = this.#buffer[(this.#head + i) % this.capacity];
+            if (entry !== undefined) {
+                entries.push(entry);
+            }
+        }
+        return { entries, gap };
+    }
+    /** Drop every retained chunk. The offset counter is NOT reset (offsets stay monotonic). */
+    clear() {
+        this.#buffer.fill(undefined);
+        this.#head = 0;
+        this.#count = 0;
+    }
+}

package/dist/relay/scheduler.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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";
+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;
+}
+export declare class QosScheduler {
+    #private;
+    constructor(options: QosSchedulerOptions);
+    /** Remaining bulk credit. */
+    get credit(): number;
+    /** Frames buffered but not yet emitted (across all lanes). */
+    get pending(): number;
+    /** Bulk frames buffered awaiting credit. */
+    get pendingBulk(): number;
+    /** How many bulk frames have been shed on overflow over this scheduler's life. */
+    get shed(): number;
+    /**
+     * 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;
+    /** Grant `n` more bulk credits, then drain any bulk frames that credit now allows. */
+    grantCredit(n: number): void;
+    /**
+     * 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;
+    /** Discard every buffered frame (e.g. on subscriber teardown). */
+    clear(): void;
+}
+/**
+ * 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/dist/relay/scheduler.js

@@ -0,0 +1,180 @@
+/**
+ * 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.js";
+import { addSafeInt, isNonNegInt, isPosInt } from "./validate.js";
+const DEFAULT_BULK_CAPACITY = 1024;
+export class QosScheduler {
+    #sink;
+    #bulkCapacity;
+    #control = [];
+    #interactive = [];
+    // 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.
+    #bulk = [];
+    #bulkHead = 0;
+    #bulkCount = 0;
+    #credit;
+    #shed = 0;
+    constructor(options) {
+        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() {
+        return this.#credit;
+    }
+    /** Frames buffered but not yet emitted (across all lanes). */
+    get pending() {
+        return this.#control.length + this.#interactive.length + this.#bulkCount;
+    }
+    /** Bulk frames buffered awaiting credit. */
+    get pendingBulk() {
+        return this.#bulkCount;
+    }
+    /** How many bulk frames have been shed on overflow over this scheduler's life. */
+    get shed() {
+        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) {
+        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) {
+        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() {
+        // 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() {
+        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) {
+        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() {
+        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/dist/relay/validate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare function isNonNegInt(value: unknown): value is number;
+/** A positive safe integer: `1, 2, … Number.MAX_SAFE_INTEGER`. */
+export declare function isPosInt(value: unknown): value is number;
+/**
+ * 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 declare function addSafeInt(current: number, delta: number, label: string): number;

package/dist/relay/validate.js

@@ -0,0 +1,39 @@
+/**
+ * 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) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** A positive safe integer: `1, 2, … Number.MAX_SAFE_INTEGER`. */
+export function isPosInt(value) {
+    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, delta, label) {
+    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/dist/transcript/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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/dist/transcript/index.js

@@ -0,0 +1,17 @@
+/**
+ * @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.js";
+export { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE, } from "./schema.js";

package/dist/transcript/schema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare const TRANSCRIPT_STREAM_TABLE = "agentic_transcript_stream";
+/** The durable per-chunk table name. */
+export declare 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 declare const TRANSCRIPT_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS agentic_transcript_stream (\n  stream        TEXT PRIMARY KEY,\n  lifecycle     TEXT NOT NULL,\n  status        TEXT NOT NULL DEFAULT 'open',\n  created_at    TEXT NOT NULL,\n  completed_at  TEXT,\n  first_offset  INTEGER,\n  next_offset   INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS agentic_transcript_chunk (\n  stream        TEXT NOT NULL,\n  chunk_offset  INTEGER NOT NULL,\n  chunk         TEXT NOT NULL,\n  appended_at   TEXT NOT NULL,\n  PRIMARY KEY (stream, chunk_offset)\n);\nCREATE INDEX IF NOT EXISTS idx_agentic_transcript_stream_retention ON agentic_transcript_stream (lifecycle, status, completed_at);";

package/dist/transcript/schema.js

@@ -0,0 +1,48 @@
+/**
+ * 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);`;