@nanobpm/agentic 0.1.0

package/dist/transcript/store.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The minimal synchronous SQLite handle the store needs — structurally the same
+ * surface the Urban runtime's DataLayer exposes (`host.openSqlite`). Kept local
+ * so the store depends on a shape, not on the runtime package. (Identical to the
+ * S2 presence store's `SqliteDb`.)
+ */
+export interface SqliteDb {
+    /** Execute one or more statements with no result (DDL, migrations). */
+    exec(sql: string): void;
+    /** Run a parameterised statement, returning the changed-row count. */
+    run(sql: string, params?: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** Run a parameterised query, returning all rows as plain objects. */
+    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+}
+/** A monotonic wall clock, injectable for deterministic tests. */
+export interface Clock {
+    now(): number;
+}
+/** The default clock: `Date.now()`. */
+export declare const systemClock: Clock;
+/**
+ * A stream's retention lifecycle. `ephemeral` transcripts are flushed once on job
+ * completion and retained until a retention sweep; `long-lived` transcripts grow
+ * incrementally and are bounded by a rolling offset window.
+ */
+export type TranscriptLifecycle = "ephemeral" | "long-lived";
+/** A stream's transcript status. */
+export type TranscriptStatus = "open" | "completed";
+/** A single durable transcript chunk and the offset it was assigned. */
+export interface TranscriptChunk {
+    readonly offset: number;
+    readonly chunk: string;
+}
+/** Per-stream transcript metadata. */
+export interface TranscriptStream {
+    readonly stream: string;
+    readonly lifecycle: TranscriptLifecycle;
+    readonly status: TranscriptStatus;
+    /** When the stream was first opened, ISO-8601. */
+    readonly createdAt: string;
+    /** When an ephemeral run was flushed & completed, ISO-8601 (undefined while open). */
+    readonly completedAt?: string;
+    /** The oldest retained offset, or undefined when the transcript is empty. */
+    readonly firstOffset?: number;
+    /** One past the highest offset ever recorded (the resume high-water mark). */
+    readonly nextOffset: number;
+}
+/**
+ * The result of a {@link TranscriptStore.since} reattach query — the same shape
+ * the S5 {@link ReplayRing.since} returns, now served from durable storage.
+ */
+export interface TranscriptSlice {
+    /** The retained chunks with `offset >= from`, in offset order. */
+    readonly entries: readonly TranscriptChunk[];
+    /**
+     * `true` when `from` predates the oldest retained offset: chunks the consumer
+     * asked for were already dropped by retention (rolling window / expiry), so the
+     * replay is a best-effort resume, not gap-free from `from`.
+     */
+    readonly gap: boolean;
+    /** One past the highest recorded offset (where the live stream continues). */
+    readonly nextOffset: number;
+}
+/**
+ * The minimal resume-from-offset source a {@link TranscriptStore.flush} reads.
+ * The S5 {@link ReplayRing} satisfies this structurally (`since(0).entries` is the
+ * whole retained window; `nextOffset` is its high-water mark), so the store can
+ * flush a real relay ring without a compile dependency on the relay package.
+ */
+export interface TranscriptRing {
+    since(from: number): {
+        readonly entries: readonly TranscriptChunk[];
+    };
+    readonly nextOffset: number;
+}
+export interface TranscriptStoreOptions {
+    /**
+     * How long a *completed ephemeral* transcript is retained after its
+     * `completed_at` before {@link TranscriptStore.sweep} may drop it, in ms.
+     * Default 86_400_000 (24h). Long-lived streams are never time-swept.
+     */
+    ephemeralRetentionMs?: number;
+    /** Injectable clock for deterministic tests. Default {@link systemClock}. */
+    clock?: Clock;
+}
+/**
+ * Raised when a transcript row read back from storage holds a value outside its
+ * domain (e.g. an unknown `lifecycle`/`status`), signalling schema corruption or a
+ * bad manual write. Fail fast rather than silently coercing to a default, which
+ * would mask the corruption and skew retention decisions.
+ */
+export declare class TranscriptCorruptionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when an operation targets a lifecycle it does not apply to (e.g.
+ * completing a `long-lived` stream, which by definition never completes).
+ */
+export declare class TranscriptLifecycleError extends Error {
+    readonly stream: string;
+    constructor(stream: string, message: string);
+}
+export declare class TranscriptStore {
+    #private;
+    constructor(db: SqliteDb, options?: TranscriptStoreOptions);
+    /** The completed-ephemeral retention window in ms. */
+    get ephemeralRetentionMs(): number;
+    /**
+     * Apply the canonical transcript DDL (idempotent). Callers that let the app
+     * DataLayer migration runner apply `db/migrations/002_agentic_transcript.sql`
+     * do not need this — but it is provided so the store is usable against a bare
+     * source too. The DDL is identical to the migration (drift-guarded).
+     */
+    ensureSchema(): void;
+    /**
+     * Open (or fetch) a stream's transcript with the given lifecycle. Idempotent:
+     * a first call stamps `created_at` and the lifecycle; later calls return the
+     * existing row unchanged (lifecycle is first-wins and never mutates). Returns
+     * the stored metadata row.
+     */
+    open(stream: string, lifecycle: TranscriptLifecycle): TranscriptStream;
+    /**
+     * Record chunks into a stream's durable transcript, idempotently. Each chunk is
+     * keyed `(stream, offset)`, so re-recording an already-stored offset (a retry, a
+     * re-flush, an overlapping reattach) is a no-op — never a duplicate. Auto-opens
+     * the stream with `lifecycle` (default `long-lived`) if it is not open yet; if the
+     * stream already exists under a different lifecycle this throws a
+     * {@link TranscriptLifecycleError} before writing anything (lifecycle is
+     * first-wins), so a mismatched flush cannot leave a partial write.
+     * The batch is atomic: if any entry has an invalid offset (or a write fails)
+     * partway through, the whole call rolls back — it records every chunk or none.
+     * Returns the number of newly-persisted chunks.
+     *
+     * This is the incremental path a long-lived stream uses; {@link flush} builds on
+     * it for the ephemeral completion path.
+     */
+    record(stream: string, entries: Iterable<TranscriptChunk>, lifecycle?: TranscriptLifecycle): number;
+    /**
+     * Flush a resume-from-offset source (an S5 {@link ReplayRing}) into a stream's
+     * durable transcript. Persists the source's entire retained window
+     * (`source.since(0)`) idempotently and advances the stream's high-water mark to
+     * `source.nextOffset` (so the recorded `nextOffset` reflects everything ever
+     * produced, even chunks the ring already evicted). Returns the number of
+     * newly-persisted chunks.
+     *
+     * For an `ephemeral` stream this is the job-completion flush: it also marks the
+     * transcript `completed` (stamping `completed_at`), after which {@link read}
+     * yields 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`.
+     */
+    flush(stream: string, source: TranscriptRing, lifecycle: TranscriptLifecycle): number;
+    /**
+     * Reattach a consumer from offset `from` (inclusive). Returns the retained
+     * chunks with `offset >= from`, the live `nextOffset`, and a `gap` flag when
+     * `from` predates the oldest retained offset (retention dropped chunks the
+     * consumer wanted). Mirrors the S5 {@link ReplayRing.since} contract exactly,
+     * so a reattach behaves identically whether it resumes from the live ring or
+     * the durable transcript.
+     */
+    since(stream: string, from: number): TranscriptSlice;
+    /** Read a stream's whole durable transcript in offset order. */
+    read(stream: string): TranscriptChunk[];
+    /**
+     * Apply a rolling retention window to a long-lived stream: drop every chunk with
+     * `offset < before`. A subsequent {@link since} from an offset older than
+     * `before` reports a `gap`. Returns the number of chunks dropped. Refuses to
+     * truncate an `ephemeral` transcript (those are retained whole until swept) with
+     * a {@link TranscriptLifecycleError}.
+     */
+    truncateBefore(stream: string, before: number): number;
+    /**
+     * Retention sweep for completed ephemeral transcripts: drop every stream whose
+     * `status = 'completed'` and whose `completed_at` is older than the retention
+     * window, along with its chunks. Long-lived streams are never time-swept (they
+     * are bounded by {@link truncateBefore} instead). Returns the removed stream ids.
+     *
+     * The selection and all deletes run inside a single SAVEPOINT (#atomic) so the
+     * sweep is all-or-nothing: if any delete throws mid-sweep the whole batch rolls
+     * back, so the DB is never left partially swept and the returned list always
+     * matches what was actually deleted.
+     */
+    sweep(now?: number): string[];
+    /** Look up a single stream's transcript metadata. */
+    get(stream: string): TranscriptStream | undefined;
+    /** Every stream's metadata, ordered by first open then stream id. */
+    list(): TranscriptStream[];
+    /** Number of tracked streams. */
+    count(): number;
+}

package/dist/transcript/store.js

@@ -0,0 +1,347 @@
+/**
+ * The transcript store — S6's retention-by-lifecycle durable layer over the app
+ * DataLayer.
+ *
+ * The S5 relay ({@link https://npmjs.com/package/@nanobpm/agentic-relay | ReplayRing})
+ * keeps a *bounded* in-memory resume window per live stream. S6 layers a *durable*
+ * transcript on top, with retention differentiated by the stream's lifecycle:
+ *
+ *  - **ephemeral** — a short run (e.g. one job). Its ring is flushed to a durable
+ *    transcript on job completion ({@link TranscriptStore.flush}); the completed
+ *    transcript is readable ({@link TranscriptStore.read}) and ages out only on an
+ *    explicit retention sweep ({@link TranscriptStore.sweep}) — never while a
+ *    consumer might still fetch it.
+ *  - **long-lived** — a durable stream that outlives any single ring. Chunks are
+ *    recorded incrementally ({@link TranscriptStore.record}); a reconnecting
+ *    consumer reattaches from an offset ({@link TranscriptStore.since}); a rolling
+ *    retention window is applied by {@link TranscriptStore.truncateBefore}, after
+ *    which a reattach before the truncation point reports a `gap` (exactly the S5
+ *    ring's resume-from-offset contract, now over durable storage).
+ *
+ * The store speaks only the tiny synchronous SQLite subset the runtime exposes
+ * ({@link SqliteDb}), so it works against any app DataLayer source without pulling
+ * in the whole runtime.
+ */
+import { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE } from "./schema.js";
+/** The default clock: `Date.now()`. */
+export const systemClock = { now: () => Date.now() };
+const DEFAULT_EPHEMERAL_RETENTION_MS = 86_400_000;
+function isNonNegInt(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * A recordable offset must be a non-negative safe integer that still leaves room
+ * for its successor: `#refreshWindow` derives `next_offset = maxOffset + 1`, so an
+ * offset of `Number.MAX_SAFE_INTEGER` would make `next_offset` a non-safe integer
+ * and break the resume contract (`since()` rejects non-safe integers). Cap one
+ * below the safe-integer ceiling.
+ */
+function isRecordableOffset(value) {
+    return isNonNegInt(value) && value < Number.MAX_SAFE_INTEGER;
+}
+function toLifecycle(value) {
+    if (value === "ephemeral" || value === "long-lived")
+        return value;
+    throw new TranscriptCorruptionError(`invalid transcript lifecycle in DB: ${JSON.stringify(value)}`);
+}
+function toStatus(value) {
+    if (value === "open" || value === "completed")
+        return value;
+    throw new TranscriptCorruptionError(`invalid transcript status in DB: ${JSON.stringify(value)}`);
+}
+function toStream(row) {
+    const out = {
+        stream: row.stream,
+        lifecycle: toLifecycle(row.lifecycle),
+        status: toStatus(row.status),
+        createdAt: row.created_at,
+        nextOffset: row.next_offset,
+    };
+    if (row.completed_at !== null)
+        out.completedAt = row.completed_at;
+    if (row.first_offset !== null)
+        out.firstOffset = row.first_offset;
+    return out;
+}
+/**
+ * Raised when a transcript row read back from storage holds a value outside its
+ * domain (e.g. an unknown `lifecycle`/`status`), signalling schema corruption or a
+ * bad manual write. Fail fast rather than silently coercing to a default, which
+ * would mask the corruption and skew retention decisions.
+ */
+export class TranscriptCorruptionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TranscriptCorruptionError";
+    }
+}
+/**
+ * Raised when an operation targets a lifecycle it does not apply to (e.g.
+ * completing a `long-lived` stream, which by definition never completes).
+ */
+export class TranscriptLifecycleError extends Error {
+    stream;
+    constructor(stream, message) {
+        super(message);
+        this.name = "TranscriptLifecycleError";
+        this.stream = stream;
+    }
+}
+export class TranscriptStore {
+    #db;
+    #ephemeralRetentionMs;
+    #clock;
+    constructor(db, options = {}) {
+        const retentionMs = options.ephemeralRetentionMs ?? DEFAULT_EPHEMERAL_RETENTION_MS;
+        if (!(typeof retentionMs === "number" && Number.isFinite(retentionMs) && retentionMs >= 0)) {
+            throw new RangeError(`ephemeralRetentionMs must be a finite non-negative number, got ${retentionMs}`);
+        }
+        this.#db = db;
+        this.#ephemeralRetentionMs = retentionMs;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** The completed-ephemeral retention window in ms. */
+    get ephemeralRetentionMs() {
+        return this.#ephemeralRetentionMs;
+    }
+    /**
+     * Apply the canonical transcript DDL (idempotent). Callers that let the app
+     * DataLayer migration runner apply `db/migrations/002_agentic_transcript.sql`
+     * do not need this — but it is provided so the store is usable against a bare
+     * source too. The DDL is identical to the migration (drift-guarded).
+     */
+    ensureSchema() {
+        this.#db.exec(TRANSCRIPT_SCHEMA_SQL);
+    }
+    /**
+     * Open (or fetch) a stream's transcript with the given lifecycle. Idempotent:
+     * a first call stamps `created_at` and the lifecycle; later calls return the
+     * existing row unchanged (lifecycle is first-wins and never mutates). Returns
+     * the stored metadata row.
+     */
+    open(stream, lifecycle) {
+        this.#db.run(`INSERT INTO ${TRANSCRIPT_STREAM_TABLE} (stream, lifecycle, status, created_at, next_offset)
+       VALUES (?, ?, 'open', ?, 0)
+       ON CONFLICT(stream) DO NOTHING`, [stream, lifecycle, new Date(this.#clock.now()).toISOString()]);
+        const row = this.get(stream);
+        if (row === undefined) {
+            throw new Error(`transcript stream row vanished immediately after open: ${stream}`);
+        }
+        return row;
+    }
+    /**
+     * Record chunks into a stream's durable transcript, idempotently. Each chunk is
+     * keyed `(stream, offset)`, so re-recording an already-stored offset (a retry, a
+     * re-flush, an overlapping reattach) is a no-op — never a duplicate. Auto-opens
+     * the stream with `lifecycle` (default `long-lived`) if it is not open yet; if the
+     * stream already exists under a different lifecycle this throws a
+     * {@link TranscriptLifecycleError} before writing anything (lifecycle is
+     * first-wins), so a mismatched flush cannot leave a partial write.
+     * The batch is atomic: if any entry has an invalid offset (or a write fails)
+     * partway through, the whole call rolls back — it records every chunk or none.
+     * Returns the number of newly-persisted chunks.
+     *
+     * This is the incremental path a long-lived stream uses; {@link flush} builds on
+     * it for the ephemeral completion path.
+     */
+    record(stream, entries, lifecycle = "long-lived") {
+        const meta = this.open(stream, lifecycle);
+        if (meta.lifecycle !== lifecycle) {
+            throw new TranscriptLifecycleError(stream, `refusing to record into "${stream}" with lifecycle=${lifecycle}; the stream is ${meta.lifecycle} (lifecycle is first-wins)`);
+        }
+        const at = new Date(this.#clock.now()).toISOString();
+        // Make the batch write + window refresh all-or-nothing. If a later entry is
+        // invalid (or any write throws) partway through, the SAVEPOINT rolls back so
+        // record() never leaves partially-persisted chunks or stale first/next-offset
+        // metadata — it either records the whole batch or nothing.
+        return this.#atomic(() => {
+            let written = 0;
+            for (const entry of entries) {
+                if (!isRecordableOffset(entry.offset)) {
+                    throw new RangeError(`transcript offset must be a non-negative safe integer below Number.MAX_SAFE_INTEGER, got ${entry.offset}`);
+                }
+                const { changes } = this.#db.run(`INSERT INTO ${TRANSCRIPT_CHUNK_TABLE} (stream, chunk_offset, chunk, appended_at)
+           VALUES (?, ?, ?, ?)
+           ON CONFLICT(stream, chunk_offset) DO NOTHING`, [stream, entry.offset, entry.chunk, at]);
+                written += changes;
+            }
+            this.#refreshWindow(stream);
+            return written;
+        });
+    }
+    /**
+     * Flush a resume-from-offset source (an S5 {@link ReplayRing}) into a stream's
+     * durable transcript. Persists the source's entire retained window
+     * (`source.since(0)`) idempotently and advances the stream's high-water mark to
+     * `source.nextOffset` (so the recorded `nextOffset` reflects everything ever
+     * produced, even chunks the ring already evicted). Returns the number of
+     * newly-persisted chunks.
+     *
+     * For an `ephemeral` stream this is the job-completion flush: it also marks the
+     * transcript `completed` (stamping `completed_at`), after which {@link read}
+     * yields 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`.
+     */
+    flush(stream, source, lifecycle) {
+        const written = this.record(stream, source.since(0).entries, lifecycle);
+        // Advance the high-water mark to the source's nextOffset. The ring may have
+        // evicted early chunks, so its nextOffset can exceed maxStoredOffset+1; the
+        // recorded next_offset must reflect the true stream length for a later
+        // reattach's gap accounting to be correct.
+        if (isNonNegInt(source.nextOffset)) {
+            this.#raiseNextOffset(stream, source.nextOffset);
+        }
+        if (lifecycle === "ephemeral") {
+            this.#complete(stream);
+        }
+        return written;
+    }
+    /**
+     * Reattach a consumer from offset `from` (inclusive). Returns the retained
+     * chunks with `offset >= from`, the live `nextOffset`, and a `gap` flag when
+     * `from` predates the oldest retained offset (retention dropped chunks the
+     * consumer wanted). Mirrors the S5 {@link ReplayRing.since} contract exactly,
+     * so a reattach behaves identically whether it resumes from the live ring or
+     * the durable transcript.
+     */
+    since(stream, from) {
+        if (!isNonNegInt(from)) {
+            throw new RangeError(`since(from) requires a non-negative safe integer, got ${from}`);
+        }
+        const meta = this.get(stream);
+        if (meta === undefined) {
+            return { entries: [], gap: false, nextOffset: 0 };
+        }
+        const entries = this.#db
+            .all(`SELECT chunk_offset, chunk FROM ${TRANSCRIPT_CHUNK_TABLE}
+         WHERE stream = ? AND chunk_offset >= ? ORDER BY chunk_offset`, [stream, from])
+            .map((r) => ({ offset: r.chunk_offset, chunk: r.chunk }));
+        // A gap means the consumer asked for an offset older than anything retained.
+        // Only meaningful while chunks remain: with an empty (fully-swept or freshly
+        // opened) transcript there is nothing to have "lost", so gap is false.
+        const gap = meta.firstOffset !== undefined && from < meta.firstOffset;
+        return { entries, gap, nextOffset: meta.nextOffset };
+    }
+    /** Read a stream's whole durable transcript in offset order. */
+    read(stream) {
+        return this.#db
+            .all(`SELECT chunk_offset, chunk FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ? ORDER BY chunk_offset`, [stream])
+            .map((r) => ({ offset: r.chunk_offset, chunk: r.chunk }));
+    }
+    /**
+     * Apply a rolling retention window to a long-lived stream: drop every chunk with
+     * `offset < before`. A subsequent {@link since} from an offset older than
+     * `before` reports a `gap`. Returns the number of chunks dropped. Refuses to
+     * truncate an `ephemeral` transcript (those are retained whole until swept) with
+     * a {@link TranscriptLifecycleError}.
+     */
+    truncateBefore(stream, before) {
+        if (!isNonNegInt(before)) {
+            throw new RangeError(`truncateBefore(before) requires a non-negative safe integer, got ${before}`);
+        }
+        const meta = this.get(stream);
+        if (meta === undefined)
+            return 0;
+        if (meta.lifecycle === "ephemeral") {
+            throw new TranscriptLifecycleError(stream, `refusing to truncate ephemeral transcript "${stream}"; ephemeral runs are retained whole until sweep()`);
+        }
+        const { changes } = this.#db.run(`DELETE FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ? AND chunk_offset < ?`, [stream, before]);
+        if (changes > 0)
+            this.#refreshWindow(stream);
+        return changes;
+    }
+    /**
+     * Retention sweep for completed ephemeral transcripts: drop every stream whose
+     * `status = 'completed'` and whose `completed_at` is older than the retention
+     * window, along with its chunks. Long-lived streams are never time-swept (they
+     * are bounded by {@link truncateBefore} instead). Returns the removed stream ids.
+     *
+     * The selection and all deletes run inside a single SAVEPOINT (#atomic) so the
+     * sweep is all-or-nothing: if any delete throws mid-sweep the whole batch rolls
+     * back, so the DB is never left partially swept and the returned list always
+     * matches what was actually deleted.
+     */
+    sweep(now = this.#clock.now()) {
+        const cutoffIso = new Date(now - this.#ephemeralRetentionMs).toISOString();
+        return this.#atomic(() => {
+            const removed = this.#db
+                .all(`SELECT stream FROM ${TRANSCRIPT_STREAM_TABLE}
+           WHERE lifecycle = 'ephemeral' AND status = 'completed'
+             AND completed_at IS NOT NULL AND completed_at < ?`, [cutoffIso])
+                .map((r) => r.stream);
+            for (const stream of removed) {
+                this.#db.run(`DELETE FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ?`, [stream]);
+                this.#db.run(`DELETE FROM ${TRANSCRIPT_STREAM_TABLE} WHERE stream = ?`, [stream]);
+            }
+            return removed;
+        });
+    }
+    /** Look up a single stream's transcript metadata. */
+    get(stream) {
+        const rows = this.#db.all(`SELECT * FROM ${TRANSCRIPT_STREAM_TABLE} WHERE stream = ?`, [stream]);
+        const row = rows[0];
+        return row === undefined ? undefined : toStream(row);
+    }
+    /** Every stream's metadata, ordered by first open then stream id. */
+    list() {
+        return this.#db
+            .all(`SELECT * FROM ${TRANSCRIPT_STREAM_TABLE} ORDER BY created_at, stream`)
+            .map(toStream);
+    }
+    /** Number of tracked streams. */
+    count() {
+        const rows = this.#db.all(`SELECT COUNT(*) AS n FROM ${TRANSCRIPT_STREAM_TABLE}`);
+        return rows[0]?.n ?? 0;
+    }
+    /** Mark an ephemeral stream completed (idempotent), stamping `completed_at`. */
+    #complete(stream) {
+        const meta = this.get(stream);
+        if (meta === undefined)
+            return;
+        if (meta.lifecycle !== "ephemeral") {
+            throw new TranscriptLifecycleError(stream, `refusing to complete non-ephemeral transcript "${stream}" (lifecycle=${meta.lifecycle})`);
+        }
+        if (meta.status === "completed")
+            return;
+        this.#db.run(`UPDATE ${TRANSCRIPT_STREAM_TABLE} SET status = 'completed', completed_at = ? WHERE stream = ?`, [new Date(this.#clock.now()).toISOString(), stream]);
+    }
+    /**
+     * Recompute a stream's retained offset window (`first_offset`, and `next_offset`
+     * raised to `max(chunk_offset)+1`) from the chunks actually stored. `next_offset`
+     * is monotonic — it is never lowered below its recorded high-water mark, so a
+     * truncation that drops the tail (there is none — truncation drops the head) or
+     * a re-record cannot rewind the resume point.
+     */
+    #refreshWindow(stream) {
+        const agg = this.#db.all(`SELECT MIN(chunk_offset) AS mn, MAX(chunk_offset) AS mx FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ?`, [stream])[0];
+        const minOffset = agg?.mn ?? null;
+        const maxOffset = agg?.mx ?? null;
+        const candidateNext = maxOffset === null ? 0 : maxOffset + 1;
+        this.#db.run(`UPDATE ${TRANSCRIPT_STREAM_TABLE}
+       SET first_offset = ?, next_offset = MAX(next_offset, ?)
+       WHERE stream = ?`, [minOffset, candidateNext, stream]);
+    }
+    /** Raise a stream's `next_offset` high-water mark (never lowers it). */
+    #raiseNextOffset(stream, nextOffset) {
+        this.#db.run(`UPDATE ${TRANSCRIPT_STREAM_TABLE} SET next_offset = MAX(next_offset, ?) WHERE stream = ?`, [nextOffset, stream]);
+    }
+    /**
+     * Run `body` inside a SQLite SAVEPOINT so its writes are atomic: on any throw
+     * the savepoint is rolled back (nothing it wrote persists) and the error is
+     * re-raised; on success it is released. SAVEPOINTs nest, so this is safe
+     * whether or not an outer transaction is already open.
+     */
+    #atomic(body) {
+        this.#db.exec("SAVEPOINT nano_atomic");
+        try {
+            const result = body();
+            this.#db.exec("RELEASE SAVEPOINT nano_atomic");
+            return result;
+        }
+        catch (err) {
+            this.#db.exec("ROLLBACK TO SAVEPOINT nano_atomic");
+            this.#db.exec("RELEASE SAVEPOINT nano_atomic");
+            throw err;
+        }
+    }
+}

package/dist/transcript/test-db.d.ts

@@ -0,0 +1,5 @@
+import type { SqliteDb } from "./store.ts";
+export interface TestDb extends SqliteDb {
+    close(): void;
+}
+export declare function openTestDb(): TestDb;

package/dist/transcript/test-db.js

@@ -0,0 +1,41 @@
+/**
+ * Test-only helper: a {@link SqliteDb} backed by an in-memory `node:sqlite`
+ * database, mirroring the Node host adapter's `wrapNodeSqlite` (and the identical
+ * helper in @nanobpm/agentic-presence). Kept out of the published build (see
+ * `tsconfig.build.json` exclude) — it exists solely so the store tests exercise
+ * the store against a real SQLite engine, not a mock.
+ */
+import { DatabaseSync } from "node:sqlite";
+function toParams(params) {
+    return params.map((p) => {
+        if (p === null)
+            return null;
+        if (typeof p === "string" || typeof p === "number" || typeof p === "bigint" || p instanceof Uint8Array) {
+            return p;
+        }
+        if (typeof p === "boolean")
+            return p ? 1 : 0;
+        // Mirror wrapNodeSqlite's `sqliteParams`: unsupported types (including
+        // `undefined`) throw rather than coerce, so a test can never pass on a
+        // parameter production would reject.
+        throw new TypeError(`unsupported SQLite parameter type: ${typeof p}`);
+    });
+}
+export function openTestDb() {
+    const db = new DatabaseSync(":memory:");
+    return {
+        exec: (sql) => db.exec(sql),
+        run: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            const r = stmt.run(...toParams(params));
+            return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+        },
+        all: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            // Mirror wrapNodeSqlite exactly: return the driver's row objects directly.
+            // biome-ignore lint/plugin: Node sqlite returns untyped row objects; SqliteDb.all<T> is the host adapter boundary.
+            return stmt.all(...toParams(params));
+        },
+        close: () => db.close(),
+    };
+}

package/dist/vocab/core-vocab.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The opinionated core vocabulary.
+ *
+ * Ships working out of the box (S0 invariant 6): the standard agentic SDLC
+ * networks — `planning.*`, `qa.*`, `implementation.*`, `ci.*` — plus the bare
+ * `decide` role, each gated by an enrolment `requires` predicate and sized with
+ * seats. Authors EXTEND this in the SAME schema (see {@link mergeVocab}); there
+ * is no second schema for extensions.
+ *
+ * Seats & diversity: review roles carry two named seats `#red` / `#blue` with
+ * `seatsDistinctFamily: true` so the diversity SLO (S3) fails RED when both
+ * reviewers are the same family. Non-review roles leave `seatsDistinctFamily`
+ * off (warn-default): a same-family collision there is AMBER, not RED.
+ *
+ * Capability is NEVER in the token — `requires` is the registry gate, evaluated
+ * over the declared enrolment capability (cognition/weight/family/host).
+ */
+import type { VocabDocument } from "../protocol/index.ts";
+/** The current core-vocabulary artifact version. */
+export declare const CORE_VOCAB_VERSION = 1;
+/**
+ * The frozen core vocabulary document. Deep-frozen so a consumer cannot mutate
+ * the shared artifact; author extensions go through {@link mergeVocab}, which
+ * returns a fresh document.
+ */
+export declare const CORE_VOCAB: VocabDocument;