@nylorun/runtime 0.12.0-beta → 0.14.0-beta

package/dist/streams/relay/core.js

@@ -0,0 +1,366 @@
+/**
+ * The stream relay (Durable Streams §7): feeds S2 from the record, exactly once and in order
+ * per session.
+ *
+ * - **Input.** Committed transactions from a `ChangeSource`, in commit order. The source
+ *   keeps each one until it is acknowledged, so a crash replays what S2 may not have.
+ * - **Pumps.** Each session has a queue and one pump. The pump appends the contiguous rows
+ *   at the front of the queue as one batch to `sessions/<id>` in the row's basin generation,
+ *   with `matchSeq` = the first row's `seq`:
+ *   - `ok`: the rows are done;
+ *   - tail past the batch: S2 already has those rows (a replay); they are done;
+ *   - tail before the batch: S2 is missing rows (a lost stream, or rows the source never
+ *     delivered); they are read from the record and put in front;
+ *   - an error: the rows' generation is checked against the Tenant's (a reset or Tenant
+ *     deletion makes them obsolete: done), the basin is ensured, and the batch is retried
+ *     with backoff (50 ms to 2 s). The pump is per session, so order is kept.
+ * - **Acknowledgement.** A transaction is acknowledged once all its rows are done, in commit
+ *   order, never past one that is not.
+ * - **Reconciliation.** When the source starts fresh (a new or lost slot), every session's S2
+ *   tail is compared with its log head and the difference is re-sent from the record.
+ *   `matchSeq` makes overlap with the live input harmless.
+ *
+ * The relay never writes the record and never deletes from S2.
+ */
+import { basinOf } from "../basin.js";
+import { sessionStream } from "../types.js";
+const RETRY_MIN_MS = 50;
+const RETRY_MAX_MS = 2000;
+const HEADS_PAGE = 500;
+export function createStreamRelay(options) {
+    const { source, record, streams } = options;
+    const log = options.log ?? (() => { });
+    const maxRecords = options.maxBatchRecords ?? 500;
+    const maxBytes = options.maxBatchBytes ?? 768 * 1024;
+    const concurrency = options.reconcileConcurrency ?? 8;
+    /** Committed transactions not yet fully in S2, in commit order. */
+    const txs = [];
+    const sessions = new Map();
+    let confirmed = null;
+    let active = false;
+    let stopped = false;
+    let reconciliations = 0;
+    let lastError = null;
+    let idleWaiters = [];
+    /** Woken when queued rows settle or the activation ends (`reconcile` waits on its rows). */
+    let progressWaiters = [];
+    /** Moves on with every activation and every loss of the source. */
+    let activation = 0;
+    const stopping = new AbortController();
+    const keyOf = (tenantId, sessionId) => `${tenantId}\u0000${sessionId}`;
+    function queueOf(tenantId, sessionId) {
+        const key = keyOf(tenantId, sessionId);
+        let queue = sessions.get(key);
+        if (!queue)
+            sessions.set(key, (queue = { tenantId, sessionId, rows: [], running: false }));
+        return queue;
+    }
+    function queued(row, tx) {
+        const body = JSON.stringify(row.body) ?? "null";
+        return { ...row, seq: Number(row.seq), tx, bytes: Buffer.byteLength(body) };
+    }
+    function onTx(committed) {
+        if (stopped)
+            return;
+        const tx = { endLsn: committed.endLsn, remaining: committed.rows.length };
+        txs.push(tx);
+        // Queue every row before pumping, so a transaction's rows go out in as few batches as fit.
+        const touched = new Set();
+        for (const row of committed.rows) {
+            const queue = queueOf(row.tenantId, row.sessionId);
+            queue.rows.push(queued(row, tx));
+            touched.add(queue);
+        }
+        for (const queue of touched)
+            pumpSoon(queue);
+        advance();
+    }
+    function pumpSoon(queue) {
+        if (!queue.running)
+            void pump(queue);
+    }
+    function done(row) {
+        row.tx.remaining -= 1;
+    }
+    /** The contiguous rows at the front of the queue, within the batch limits. */
+    function takeBatch(rows) {
+        const batch = [rows[0]];
+        let bytes = rows[0].bytes;
+        for (let i = 1; i < rows.length && batch.length < maxRecords; i += 1) {
+            const row = rows[i];
+            const previous = batch[batch.length - 1];
+            if (row.seq !== previous.seq + 1 || row.generation !== previous.generation)
+                break;
+            if (bytes + row.bytes > maxBytes)
+                break;
+            bytes += row.bytes;
+            batch.push(row);
+        }
+        return batch;
+    }
+    async function pump(queue) {
+        queue.running = true;
+        let delay = RETRY_MIN_MS;
+        try {
+            while (queue.rows.length > 0 && !stopped) {
+                // Duplicates (a replay overlapping a refill) and stale rows sort out here.
+                queue.rows.sort((a, b) => a.generation - b.generation || a.seq - b.seq);
+                const batch = takeBatch(queue.rows);
+                const first = batch[0];
+                const basin = basinOf(first.tenantId, first.generation);
+                try {
+                    const result = await streams.append(basin, sessionStream(first.sessionId), batch.map((row) => row.body), { matchSeq: first.seq });
+                    if (result.status === "ok") {
+                        settle(queue, (row) => batch.includes(row));
+                    }
+                    else if (result.tail > first.seq) {
+                        // A replay: S2 already has every row below its tail.
+                        settle(queue, (row) => row.generation === first.generation && row.seq < result.tail);
+                    }
+                    else {
+                        // S2 is behind the record: re-send the gap first.
+                        await refill(queue, first.generation, result.tail, first.seq);
+                    }
+                    delay = RETRY_MIN_MS;
+                    lastError = null;
+                }
+                catch (error) {
+                    if (stopped)
+                        return;
+                    lastError = messageOf(error);
+                    if (await obsolete(first)) {
+                        settle(queue, (row) => row.generation <= first.generation);
+                        continue;
+                    }
+                    log("stream relay append failed; retrying", {
+                        tenantId: first.tenantId,
+                        sessionId: first.sessionId,
+                        seq: first.seq,
+                        retryInMs: delay,
+                        message: lastError,
+                    });
+                    // The basin may be missing (S2 lost it, or it was never created).
+                    await streams.ensureTenant(basin).catch(() => undefined);
+                    await sleep(delay, stopping.signal);
+                    delay = Math.min(delay * 2, RETRY_MAX_MS);
+                }
+            }
+        }
+        finally {
+            queue.running = false;
+            if (queue.rows.length === 0)
+                sessions.delete(keyOf(queue.tenantId, queue.sessionId));
+            else if (!stopped)
+                pumpSoon(queue);
+            advance();
+        }
+    }
+    /** Marks the queue's rows matching `match` done and drops them. */
+    function settle(queue, match) {
+        const keep = [];
+        for (const row of queue.rows) {
+            if (match(row))
+                done(row);
+            else
+                keep.push(row);
+        }
+        queue.rows = keep;
+        progressed();
+    }
+    function progressed() {
+        const waiters = progressWaiters;
+        progressWaiters = [];
+        for (const wake of waiters)
+            wake();
+    }
+    /** The rows' generation is no longer the Tenant's (a reset), or the Tenant is gone. */
+    async function obsolete(row) {
+        try {
+            const current = await record.generation(row.tenantId);
+            return current === undefined || current > row.generation;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Puts record rows `[from, to)` in front of the queue (not part of the ack order). Returns
+     * their pending count, which reaches 0 once they are all in S2.
+     */
+    async function refill(queue, generation, from, to) {
+        const rows = await record.readRange(queue.tenantId, queue.sessionId, from, to);
+        const own = rows.filter((row) => row.generation === generation);
+        if (own.length < to - from) {
+            // The record no longer has them (a reset deleted the session): nothing to re-send.
+            if (await obsolete({ ...queue, seq: from, generation, body: null })) {
+                settle(queue, (row) => row.generation <= generation);
+                return undefined;
+            }
+            throw new Error(`The record is missing rows ${from}..${to - 1} of session ${queue.sessionId}`);
+        }
+        const tx = { endLsn: undefined, remaining: own.length };
+        log("stream relay refilling a session from the record", {
+            tenantId: queue.tenantId,
+            sessionId: queue.sessionId,
+            from,
+            to,
+        });
+        queue.rows.unshift(...own.map((row) => queued(row, tx)));
+        return tx;
+    }
+    /** Acknowledges the newest transaction whose rows, and all before it, are in S2. */
+    function advance() {
+        let lsn;
+        while (txs.length > 0 && txs[0].remaining <= 0)
+            lsn = txs.shift().endLsn ?? lsn;
+        if (lsn)
+            acknowledge(lsn);
+        if (txs.length === 0 && sessions.size === 0) {
+            const waiters = idleWaiters;
+            idleWaiters = [];
+            for (const wake of waiters)
+                wake();
+        }
+    }
+    function acknowledge(lsn) {
+        confirmed = lsn;
+        source.acknowledge(lsn);
+    }
+    /**
+     * Re-sends, for every session, what the record has beyond its S2 tail, and resolves true
+     * once all of it is in S2. False when activation `of` ended first (the source was lost, so
+     * the queued rows were dropped) or the relay stopped: the slot must stay unreconciled.
+     */
+    async function reconcile(of) {
+        reconciliations += 1;
+        const started = Date.now();
+        const current = () => !stopped && activation === of;
+        let sessionsChecked = 0;
+        let resent = 0;
+        const refilled = [];
+        let after;
+        for (;;) {
+            if (!current())
+                return false;
+            const page = await record.heads(after, HEADS_PAGE);
+            if (page.length === 0)
+                break;
+            let next = 0;
+            await Promise.all(Array.from({ length: Math.min(concurrency, page.length) }, async () => {
+                while (next < page.length && current()) {
+                    const head = page[next++];
+                    sessionsChecked += 1;
+                    const tx = await reconcileOne(head);
+                    if (tx) {
+                        refilled.push(tx);
+                        resent += tx.remaining;
+                    }
+                }
+            }));
+            const last = page[page.length - 1];
+            after = { tenantId: last.tenantId, sessionId: last.sessionId };
+        }
+        // Queued is not delivered: wait until S2 has every re-sent row.
+        while (current() && refilled.some((tx) => tx.remaining > 0))
+            await new Promise((resolve) => progressWaiters.push(resolve));
+        if (!current())
+            return false;
+        log("stream relay reconciled the record with S2", {
+            sessions: sessionsChecked,
+            resent,
+            durationMs: Date.now() - started,
+        });
+        return true;
+    }
+    async function reconcileOne(head) {
+        const current = await record.generation(head.tenantId);
+        if (current === undefined || current !== head.generation)
+            return undefined;
+        const basin = basinOf(head.tenantId, head.generation);
+        await streams.ensureTenant(basin);
+        const tail = await streams.tail(basin, sessionStream(head.sessionId));
+        if (tail >= head.head)
+            return undefined;
+        const queue = queueOf(head.tenantId, head.sessionId);
+        const tx = await refill(queue, head.generation, tail, head.head);
+        pumpSoon(queue);
+        return tx;
+    }
+    return {
+        start() {
+            source.start({
+                onActive({ fresh }) {
+                    active = true;
+                    const of = (activation += 1);
+                    log("stream relay active", { fresh });
+                    if (fresh)
+                        void reconcile(of)
+                            .then((complete) => (complete ? source.reconciled() : undefined))
+                            .catch((error) => {
+                            lastError = messageOf(error);
+                            log("stream relay reconciliation failed", { message: lastError });
+                        });
+                },
+                onTx,
+                onKeepalive(lsn) {
+                    // Caught up: let the source move past WAL that holds none of our rows.
+                    if (txs.length === 0) {
+                        confirmed = lsn;
+                        return lsn;
+                    }
+                    return undefined;
+                },
+                onInactive(error) {
+                    active = false;
+                    activation += 1;
+                    // The source replays everything not acknowledged; what is queued is dropped.
+                    txs.length = 0;
+                    for (const queue of sessions.values())
+                        queue.rows = [];
+                    progressed();
+                    if (error) {
+                        lastError = messageOf(error);
+                        log("stream relay lost its source; retrying", { message: lastError });
+                    }
+                },
+            });
+        },
+        async stop() {
+            stopped = true;
+            stopping.abort();
+            progressed();
+            await source.stop();
+            const waiters = idleWaiters;
+            idleWaiters = [];
+            for (const wake of waiters)
+                wake();
+        },
+        status: () => ({
+            active,
+            pendingTxs: txs.length,
+            pendingRows: [...sessions.values()].reduce((n, queue) => n + queue.rows.length, 0),
+            confirmed,
+            reconciliations,
+            lastError,
+        }),
+        idle() {
+            if (txs.length === 0 && sessions.size === 0)
+                return Promise.resolve();
+            return new Promise((resolve) => idleWaiters.push(resolve));
+        },
+    };
+}
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}

package/dist/streams/relay/memory.d.ts

@@ -0,0 +1,69 @@
+/**
+ * An in-memory record with a change source that behaves like a logical replication slot:
+ * committed transactions are kept until acknowledged and replayed to the next reader, one
+ * reader holds the slot at a time, and a dropped slot starts fresh. For unit tests and the
+ * in-memory Session Store. Not durable.
+ */
+import type { ChangeHandlers, ChangeSource, CommittedTx, LogHead, RecordReader, RecordRow } from "./types.js";
+export declare class MemoryRecord implements RecordReader {
+    /** `tenantId\0sessionId` → rows by seq. */
+    private readonly rows;
+    private readonly generations;
+    /** Committed transactions since the slot's confirmed position. */
+    private retained;
+    private lsn;
+    private slot;
+    private reader;
+    /** Commits rows as one transaction (the record is written by the Session Store). */
+    commit(rows: readonly RecordRow[]): void;
+    /** Sets a Tenant's basin generation (a reset moves it on). */
+    setGeneration(tenantId: string, generation: number): void;
+    /** Deletes a Tenant's rows, or one session's, as a reset or deletion does. */
+    deleteRows(tenantId: string, sessionId?: string): void;
+    /** Forgets a Tenant (deletion). */
+    deleteTenant(tenantId: string): void;
+    /** Drops the slot, as `max_slot_wal_keep_size` or an operator would. */
+    dropSlot(): void;
+    /** Ends the reader's connection but keeps the slot, as a network failure would. */
+    disconnect(): void;
+    /** A change source over this record; one at a time holds the slot. */
+    source(): ChangeSource;
+    readRange(tenantId: string, sessionId: string, from: number, to: number): Promise<RecordRow[]>;
+    heads(after: {
+        tenantId: string;
+        sessionId: string;
+    } | undefined, limit: number): Promise<LogHead[]>;
+    generation(tenantId: string): Promise<number | undefined>;
+    /** @internal */
+    attach(reader: MemoryChangeSource): {
+        fresh: boolean;
+        replay: CommittedTx[];
+    } | undefined;
+    /** @internal */
+    detach(reader: MemoryChangeSource): void;
+    /** @internal */
+    reconciled(): void;
+    /** @internal */
+    confirm(lsn: string): void;
+    /** The slot's confirmed position (tests). */
+    confirmed(): number | undefined;
+}
+declare class MemoryChangeSource implements ChangeSource {
+    private readonly record;
+    private handlers;
+    private timer;
+    private active;
+    private stopped;
+    constructor(record: MemoryRecord);
+    start(handlers: ChangeHandlers): void;
+    acknowledge(lsn: string): void;
+    reconciled(): Promise<void>;
+    stop(): Promise<void>;
+    /** @internal */
+    deliver(tx: CommittedTx): void;
+    /** @internal */
+    lost(error: Error): void;
+    private tryAttach;
+    private retry;
+}
+export {};

package/dist/streams/relay/memory.js

@@ -0,0 +1,176 @@
+export class MemoryRecord {
+    /** `tenantId\0sessionId` → rows by seq. */
+    rows = new Map();
+    generations = new Map();
+    /** Committed transactions since the slot's confirmed position. */
+    retained = [];
+    lsn = 0;
+    slot;
+    reader;
+    /** Commits rows as one transaction (the record is written by the Session Store). */
+    commit(rows) {
+        if (rows.length === 0)
+            return;
+        for (const row of rows) {
+            const key = keyOf(row.tenantId, row.sessionId);
+            let list = this.rows.get(key);
+            if (!list)
+                this.rows.set(key, (list = []));
+            list[row.seq] = structuredClone(row);
+            if (!this.generations.has(row.tenantId))
+                this.generations.set(row.tenantId, row.generation);
+        }
+        this.lsn += 1;
+        const tx = { endLsn: lsnText(this.lsn), rows: rows.map((row) => structuredClone(row)) };
+        // A slot keeps what was committed after it was created.
+        if (this.slot)
+            this.retained.push({ lsn: this.lsn, tx });
+        this.reader?.deliver(tx);
+    }
+    /** Sets a Tenant's basin generation (a reset moves it on). */
+    setGeneration(tenantId, generation) {
+        this.generations.set(tenantId, generation);
+    }
+    /** Deletes a Tenant's rows, or one session's, as a reset or deletion does. */
+    deleteRows(tenantId, sessionId) {
+        for (const key of [...this.rows.keys()])
+            if (sessionId === undefined ? key.startsWith(`${tenantId}\u0000`) : key === keyOf(tenantId, sessionId))
+                this.rows.delete(key);
+    }
+    /** Forgets a Tenant (deletion). */
+    deleteTenant(tenantId) {
+        this.deleteRows(tenantId);
+        this.generations.delete(tenantId);
+    }
+    /** Drops the slot, as `max_slot_wal_keep_size` or an operator would. */
+    dropSlot() {
+        this.slot = undefined;
+        this.retained = [];
+        this.reader?.lost(new Error("replication slot dropped"));
+    }
+    /** Ends the reader's connection but keeps the slot, as a network failure would. */
+    disconnect() {
+        this.reader?.lost(new Error("replication connection lost"));
+    }
+    /** A change source over this record; one at a time holds the slot. */
+    source() {
+        return new MemoryChangeSource(this);
+    }
+    async readRange(tenantId, sessionId, from, to) {
+        const list = this.rows.get(keyOf(tenantId, sessionId)) ?? [];
+        return list.slice(from, to).filter(Boolean).map((row) => structuredClone(row));
+    }
+    async heads(after, limit) {
+        const heads = [];
+        for (const [key, list] of [...this.rows].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+            const [tenantId, sessionId] = key.split("\u0000");
+            if (after && key <= keyOf(after.tenantId, after.sessionId))
+                continue;
+            const last = list[list.length - 1];
+            if (!last)
+                continue;
+            heads.push({ tenantId, sessionId, generation: last.generation, head: list.length });
+            if (heads.length >= limit)
+                break;
+        }
+        return heads;
+    }
+    async generation(tenantId) {
+        return this.generations.get(tenantId);
+    }
+    /** @internal */
+    attach(reader) {
+        if (this.reader && this.reader !== reader)
+            return undefined;
+        this.reader = reader;
+        if (!this.slot)
+            this.slot = { confirmed: this.lsn, reconcilePending: true };
+        return {
+            fresh: this.slot.reconcilePending,
+            replay: this.retained.map((entry) => entry.tx),
+        };
+    }
+    /** @internal */
+    detach(reader) {
+        if (this.reader === reader)
+            this.reader = undefined;
+    }
+    /** @internal */
+    reconciled() {
+        if (this.slot)
+            this.slot.reconcilePending = false;
+    }
+    /** @internal */
+    confirm(lsn) {
+        const position = Number(lsn.split("/")[1] ?? lsn);
+        if (!this.slot || position <= this.slot.confirmed)
+            return;
+        this.slot.confirmed = position;
+        this.retained = this.retained.filter((entry) => entry.lsn > position);
+    }
+    /** The slot's confirmed position (tests). */
+    confirmed() {
+        return this.slot?.confirmed;
+    }
+}
+class MemoryChangeSource {
+    record;
+    handlers;
+    timer;
+    active = false;
+    stopped = false;
+    constructor(record) {
+        this.record = record;
+    }
+    start(handlers) {
+        this.handlers = handlers;
+        this.tryAttach();
+    }
+    acknowledge(lsn) {
+        if (this.active)
+            this.record.confirm(lsn);
+    }
+    async reconciled() {
+        this.record.reconciled();
+    }
+    async stop() {
+        this.stopped = true;
+        clearTimeout(this.timer);
+        this.record.detach(this);
+        this.active = false;
+    }
+    /** @internal */
+    deliver(tx) {
+        if (this.active)
+            this.handlers?.onTx(tx);
+    }
+    /** @internal */
+    lost(error) {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.record.detach(this);
+        this.handlers?.onInactive(error);
+        this.retry();
+    }
+    tryAttach() {
+        if (this.stopped)
+            return;
+        const attached = this.record.attach(this);
+        if (!attached)
+            return this.retry();
+        this.active = true;
+        this.handlers.onActive({ fresh: attached.fresh });
+        for (const tx of attached.replay)
+            this.handlers.onTx(tx);
+    }
+    retry() {
+        if (this.stopped)
+            return;
+        this.timer = setTimeout(() => this.tryAttach(), 20);
+        this.timer.unref?.();
+    }
+}
+const keyOf = (tenantId, sessionId) => `${tenantId}\u0000${sessionId}`;
+/** A Postgres-looking LSN, so positions read the same in logs. */
+const lsnText = (n) => `0/${n}`;

package/dist/streams/relay/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Contracts of the stream relay (Durable Streams §7): what it reads committed events from,
+ * and how it reads the record back to refill and reconcile. Postgres implements both with
+ * logical replication (`adapters/replication/pgoutput.ts`) and the record tables
+ * (`store/postgres/record.ts`); `streams/relay/memory.ts` is the in-memory pair.
+ */
+/** One committed row of the record: a session event and the basin generation it goes to. */
+export interface RecordRow {
+    tenantId: string;
+    sessionId: string;
+    seq: number;
+    generation: number;
+    /** The event, as stored. */
+    body: unknown;
+}
+/** One committed transaction's record rows, in commit order. */
+export interface CommittedTx {
+    /** Where the source resumes after this transaction once it is acknowledged. */
+    readonly endLsn: string;
+    readonly rows: readonly RecordRow[];
+}
+export interface ChangeHandlers {
+    /**
+     * This process now reads the source (the slot is ours). `fresh` while the source has no
+     * history to replay for rows committed before it existed (a new or lost slot): the record
+     * must be reconciled with S2, then `reconciled()` called.
+     */
+    onActive(state: {
+        fresh: boolean;
+    }): void;
+    /** A committed transaction, in commit order. Replayed after a restart until acknowledged. */
+    onTx(tx: CommittedTx): void;
+    /**
+     * The source asks how far it may move on: return the position to acknowledge (the
+     * server's `lsn` when nothing is pending), or undefined to acknowledge nothing new.
+     */
+    onKeepalive(lsn: string): string | undefined;
+    /** This process stopped reading the source (connection lost); it tries again. */
+    onInactive(error?: unknown): void;
+}
+/**
+ * Committed record rows in commit order, kept by the source until acknowledged: a
+ * transaction not acknowledged before a crash is delivered again.
+ */
+export interface ChangeSource {
+    /** Starts reading; keeps trying (another process may hold the source) until `stop`. */
+    start(handlers: ChangeHandlers): void;
+    /** Everything up to `lsn` is delivered; the source may forget it. */
+    acknowledge(lsn: string): void;
+    /**
+     * The relay reconciled the record after a fresh start. Until this is called, every process
+     * that becomes active is told `fresh` again (the reconciliation may have been cut short).
+     */
+    reconciled(): Promise<void>;
+    stop(): Promise<void>;
+    /** How far the source is behind, in bytes, when known. */
+    lag?(): Promise<number | undefined>;
+}
+/** A session's log head: the next `seq` to allocate. */
+export interface LogHead {
+    tenantId: string;
+    sessionId: string;
+    generation: number;
+    head: number;
+}
+/** Reads the record back (refill and reconciliation). */
+export interface RecordReader {
+    /** Rows `[from, to)` of a session, in `seq` order. */
+    readRange(tenantId: string, sessionId: string, from: number, to: number): Promise<RecordRow[]>;
+    /** Log heads with `head > 0`, in (Tenant, session) order, after `after`, at most `limit`. */
+    heads(after: {
+        tenantId: string;
+        sessionId: string;
+    } | undefined, limit: number): Promise<LogHead[]>;
+    /** The Tenant's current basin generation; undefined when the Tenant is gone. */
+    generation(tenantId: string): Promise<number | undefined>;
+}

package/dist/streams/relay/types.js

@@ -0,0 +1,7 @@
+/**
+ * Contracts of the stream relay (Durable Streams §7): what it reads committed events from,
+ * and how it reads the record back to refill and reconcile. Postgres implements both with
+ * logical replication (`adapters/replication/pgoutput.ts`) and the record tables
+ * (`store/postgres/record.ts`); `streams/relay/memory.ts` is the in-memory pair.
+ */
+export {};