@rindle/api-server 0.7.12 → 0.8.0

package/dist/streams.js

@@ -0,0 +1,1047 @@
+// LM stream checkpointing — the two-plane response path (designs/LM-STREAM-CHECKPOINT-DESIGN.md).
+//
+// A model response arrives as hundreds of tiny deltas per second. Every one wants to be on a screen
+// immediately; none wants to be a durable write. So the response runs on TWO planes sharing ONE
+// monotone coordinate (`seq`, in UTF-16 code units of the response text):
+//
+//   - the LIVE plane (this module): process-local, volatile, every delta, straight to subscribers;
+//   - the DURABLE plane: the app's own tables, advanced at coarse boundaries — N chars, T ms, an
+//     explicit `flush()`, and always at close.
+//
+// The contract both planes stand on (§0):
+//
+//   S (splice)  durableText(f) ++ concat(frames delivered from f) == producedText, for every join
+//               offset f and every join time.
+//   P (prefix)  durableText is always a PREFIX of producedText, and durableSeq is monotone.
+//
+// P is what makes S mechanical — two prefixes of one string merge by taking the longer (see
+// {@link spliceStreamText}). Everything else here is bookkeeping in service of those two.
+//
+// TWO THINGS THIS DELIBERATELY IS NOT (both were wrong in the first cut of this module):
+//
+//   1. Checkpoints are SYSTEM WRITES, not mutation envelopes. `lmid` is client-authored and exists
+//      to release a client's optimistic rebase point; a server-authored checkpoint has no
+//      prediction to release, and CDC → IVM fanout needs no envelope at all. Checkpoints therefore
+//      go through `outsideSql` with no clientID/mid — the same rule the realtime lifecycle writes
+//      follow ("a system write must never advance an lmid").
+//   2. A checkpoint INSERTS A CHUNK ROW; it never appends to a growing column. A normalized `edit`
+//      carries BOTH the old and the new full row, so advancing a `body` column would re-stream the
+//      whole message twice per checkpoint — O(n²) wire to deliver n characters. One row per chunk
+//      makes each checkpoint a single `add` carrying only its own slice.
+//
+// Durability is never overclaimed (§0, the RINDLE-REALTIME §8.1 "ack honesty" rule): a `chunk` frame
+// says only "produced", a `durable` frame says "committed", an `end` frame says "sealed". Losing
+// this plane entirely costs latency and the un-checkpointed tail — never consistency: a client with
+// no live stream still sees the message grow through IVM at checkpoint granularity, which is why
+// `absent`/`stale` are ordinary answers rather than errors.
+// Type-only (erased at runtime) — no import cycle with ./index.ts.
+import { STREAM_STATUS_STREAMING, frameResumePoint } from "@rindle/client";
+// ------------------------------------------------------------------------------- the wire
+//
+// The frame shapes and the two pure reassembly functions live in `@rindle/client` — BOTH tiers need
+// them, and a browser must never pull this package to read a stream. Re-exported here so the
+// server-side import path is unchanged.
+export { STREAM_STATUS_STREAMING, assembleDurableText, frameResumePoint, spliceStreamText, } from "@rindle/client";
+// ------------------------------------------------------------------------------- defaults
+const DEFAULT_CHECKPOINT_CHARS = 512;
+const DEFAULT_CHECKPOINT_INTERVAL_MS = 750;
+const DEFAULT_CHECKPOINT_RETRIES = 3;
+const DEFAULT_RETAIN_CHARS = 64 * 1024;
+const DEFAULT_LINGER_MS = 30_000;
+const DEFAULT_MAX_QUEUED_FRAMES = 1024;
+/** Retry backoff base — 50ms, 100ms, 200ms, … A checkpoint failure is usually a blip at the write
+ *  authority; the text is safe in the buffer meanwhile, so there is nothing to rush. */
+const RETRY_BACKOFF_MS = 50;
+/** A SCHEDULING timer — the checkpoint cadence, the linger window, the SSE keep-alive. It never
+ *  holds the process open: none of them is work in flight, and a stream plane must not keep a CLI
+ *  alive. `unref` is Node-only — Workers' `setTimeout` has no such method, hence the guard. */
+function timer(fn, ms) {
+    const t = setTimeout(fn, ms);
+    t.unref?.();
+    return t;
+}
+/** The retry backoff, and deliberately NOT unref'd: a checkpoint mid-retry IS work in flight, and a
+ *  process that exits during it drops text the caller is still awaiting. */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function errText(err) {
+    return String(err?.message ?? err);
+}
+/** A per-plane stand-in for {@link RindleStreamOptions.hostId} when only the open CAS — not
+ *  subscribe routing — needs a token. */
+function randomOpenToken() {
+    const c = globalThis.crypto;
+    return c?.randomUUID?.() ?? `open-${Math.random().toString(36).slice(2)}`;
+}
+export function resolveStreamColumns(columns) {
+    return {
+        key: columns?.key ?? "id",
+        body: columns?.body ?? "body",
+        status: columns?.status ?? "status",
+        seq: columns?.seq ?? "seq",
+        ...(columns?.cancel !== undefined ? { cancel: columns.cancel } : {}),
+        ...(columns?.error !== undefined ? { error: columns.error } : {}),
+        ...(columns?.host !== undefined ? { host: columns.host } : {}),
+        chunkKey: columns?.chunkKey ?? "id",
+        chunkStream: columns?.chunkStream ?? "streamId",
+        chunkSeq: columns?.chunkSeq ?? "seq",
+        chunkText: columns?.chunkText ?? "text",
+    };
+}
+/** Quote an identifier for both dialects (`"x"` is standard in SQLite and Postgres alike). An
+ *  embedded quote is refused rather than escaped: a mapping is app configuration, and a name that
+ *  needs escaping is a mistake worth failing loudly on. */
+function q(identifier) {
+    if (identifier.includes('"'))
+        throw new TypeError(`invalid stream column/table name: ${JSON.stringify(identifier)}`);
+    return `"${identifier}"`;
+}
+/** The chunk row's deterministic id: a replayed checkpoint collides with itself and is absorbed by
+ *  `ON CONFLICT DO NOTHING` — idempotency without an envelope or a dedup ledger (§3.3). */
+export function streamChunkId(streamId, seq) {
+    return `${streamId}:${seq}`;
+}
+/**
+ * The chunk table's DDL, for the app's migration. The app owns the message table (this only states
+ * the three columns the plane needs on it); the chunk table is entirely protocol-shaped, so it is
+ * generated rather than hand-written.
+ */
+export function streamChunkTableDdl(tables, dialect) {
+    const c = resolveStreamColumns(tables.columns);
+    const text = dialect.name === "postgres" ? "text" : "TEXT";
+    const int = dialect.name === "postgres" ? "bigint" : "INTEGER";
+    return [
+        `CREATE TABLE IF NOT EXISTS ${q(tables.chunks)} (` +
+            `${q(c.chunkKey)} ${text} PRIMARY KEY, ` +
+            `${q(c.chunkStream)} ${text} NOT NULL, ` +
+            `${q(c.chunkSeq)} ${int} NOT NULL, ` +
+            `${q(c.chunkText)} ${text} NOT NULL)`,
+        // The read path is always "this message's chunks, in order" — and compaction deletes by stream.
+        `CREATE INDEX IF NOT EXISTS ${q(`${tables.chunks}_stream_seq`)} ` +
+            `ON ${q(tables.chunks)} (${q(c.chunkStream)}, ${q(c.chunkSeq)})`,
+    ];
+}
+/** The plane's SQL, one place, both dialects. */
+class MappedTableSql {
+    tables;
+    cols;
+    dialect;
+    constructor(tables, dialect) {
+        this.tables = tables;
+        this.cols = resolveStreamColumns(tables.columns);
+        this.dialect = dialect;
+    }
+    p(i) {
+        return this.dialect.placeholder(i);
+    }
+    /** The open probe: the row must exist and be empty. A generation is never a resume — regenerating
+     *  is a NEW message id — so an already-advanced row is a bug worth refusing loudly. */
+    probeOpen() {
+        const { key, seq, status } = this.cols;
+        return `SELECT ${q(seq)} AS seq, ${q(status)} AS status FROM ${q(this.tables.message)} WHERE ${q(key)} = ${this.p(1)}`;
+    }
+    /** The open write. With a `host` column mapped this is the CAS half of the single-flight guard:
+     *  set the status AND this producer's token only if no producer holds the row, verified by the
+     *  read-back in {@link probeHost}. Without one it is the plain flip the probe already vetted. */
+    markStreaming(streamId, hostToken) {
+        const { key, status, host } = this.cols;
+        if (host !== undefined) {
+            return {
+                sql: `UPDATE ${q(this.tables.message)} SET ${q(status)} = ${this.p(1)}, ${q(host)} = ${this.p(2)} ` +
+                    `WHERE ${q(key)} = ${this.p(3)} AND ${q(status)} <> ${this.p(4)}`,
+                params: [STREAM_STATUS_STREAMING, hostToken, streamId, STREAM_STATUS_STREAMING],
+            };
+        }
+        return {
+            sql: `UPDATE ${q(this.tables.message)} SET ${q(status)} = ${this.p(1)} WHERE ${q(key)} = ${this.p(2)}`,
+            params: [STREAM_STATUS_STREAMING, streamId],
+        };
+    }
+    /** The read-back half of the open CAS, or `undefined` when no `host` column is mapped. */
+    probeHost() {
+        const { host, key } = this.cols;
+        if (host === undefined)
+            return undefined;
+        return `SELECT ${q(host)} AS host FROM ${q(this.tables.message)} WHERE ${q(key)} = ${this.p(1)}`;
+    }
+    /** ONE transaction: insert the slice, then CAS the message's durable length. BOTH statements are
+     *  gated on the same `seq = :from` predicate: the CAS refuses to apply twice or out of order, and
+     *  the guarded insert makes a STALE RE-COVER a no-op — after a committed-but-ack-lost append, the
+     *  next slice's `from` lags the row, and an unguarded insert would land an OVERLAPPING chunk row
+     *  (a different deterministic id, so `ON CONFLICT` alone cannot absorb it) and corrupt the
+     *  assembled text until compaction. The `ON CONFLICT` clause stays as the belt under that
+     *  guard's braces. Which case actually happened is decided by the read-back ({@link probeState}),
+     *  never assumed (§3.2/§3.3). */
+    append(streamId, from, seq, text) {
+        const c = this.cols;
+        return [
+            {
+                sql: `INSERT INTO ${q(this.tables.chunks)} ` +
+                    `(${q(c.chunkKey)}, ${q(c.chunkStream)}, ${q(c.chunkSeq)}, ${q(c.chunkText)}) ` +
+                    `SELECT ${this.p(1)}, ${this.p(2)}, ${this.p(3)}, ${this.p(4)} ` +
+                    `WHERE EXISTS (SELECT 1 FROM ${q(this.tables.message)} ` +
+                    `WHERE ${q(c.key)} = ${this.p(5)} AND ${q(c.seq)} = ${this.p(6)}) ` +
+                    `ON CONFLICT DO NOTHING`,
+                params: [streamChunkId(streamId, seq), streamId, seq, text, streamId, from],
+            },
+            {
+                sql: `UPDATE ${q(this.tables.message)} SET ${q(c.seq)} = ${this.p(1)} ` +
+                    `WHERE ${q(c.key)} = ${this.p(2)} AND ${q(c.seq)} = ${this.p(3)}`,
+                params: [seq, streamId, from],
+            },
+        ];
+    }
+    /** Compaction (§3.4): write the whole body, seal the status, drop every chunk — atomically. Also
+     *  the repair path: whatever the chunks did or did not capture, the body ends up correct. */
+    compact(streamId, body, status, error) {
+        const c = this.cols;
+        const sets = [`${q(c.body)} = ${this.p(1)}`, `${q(c.seq)} = ${this.p(2)}`, `${q(c.status)} = ${this.p(3)}`];
+        const params = [body, body.length, status];
+        if (c.error !== undefined) {
+            sets.push(`${q(c.error)} = ${this.p(params.length + 1)}`);
+            params.push(error ?? null);
+        }
+        params.push(streamId);
+        return [
+            {
+                sql: `UPDATE ${q(this.tables.message)} SET ${sets.join(", ")} WHERE ${q(c.key)} = ${this.p(params.length)}`,
+                params,
+            },
+            {
+                sql: `DELETE FROM ${q(this.tables.chunks)} WHERE ${q(c.chunkStream)} = ${this.p(1)}`,
+                params: [streamId],
+            },
+        ];
+    }
+    get hasCancel() {
+        return this.cols.cancel !== undefined;
+    }
+    /** The post-append read-back: the row's authoritative length — what CONFIRMS an append applied
+     *  (and absorbs a committed-but-ack-lost one) — plus the cancel flag when mapped (§6). */
+    probeState() {
+        const { cancel, key, seq } = this.cols;
+        const picked = cancel === undefined ? `${q(seq)} AS seq` : `${q(seq)} AS seq, ${q(cancel)} AS cancel`;
+        return `SELECT ${picked} FROM ${q(this.tables.message)} WHERE ${q(key)} = ${this.p(1)}`;
+    }
+}
+// ------------------------------------------------------------------------------- subscribers
+/** One attached reader. Frames queue; a reader that stops draining is bounded and then DROPPED with
+ *  `stale` rather than allowed to pin the producer's memory — it resolves that by rejoining. */
+class Subscriber {
+    queue = [];
+    waiter;
+    done = false;
+    cap;
+    onDetach;
+    constructor(cap, onDetach) {
+        this.cap = cap;
+        this.onDetach = onDetach;
+    }
+    /** @returns false when the queue overflowed (caller drops this subscriber). */
+    offer(frame) {
+        if (this.done)
+            return true;
+        if (this.waiter) {
+            const w = this.waiter;
+            this.waiter = undefined;
+            w({ value: frame, done: false });
+            return true;
+        }
+        if (this.queue.length >= this.cap)
+            return false;
+        this.queue.push(frame);
+        return true;
+    }
+    /** Deliver a terminal frame (bypassing the cap — it is the last one) and end the iterator. */
+    finish(frame) {
+        if (this.done)
+            return;
+        if (this.waiter) {
+            const w = this.waiter;
+            this.waiter = undefined;
+            this.done = true;
+            w({ value: frame, done: false });
+            return;
+        }
+        this.queue.push(frame);
+        this.done = true;
+    }
+    close() {
+        this.done = true;
+        this.queue.length = 0;
+        if (this.waiter) {
+            const w = this.waiter;
+            this.waiter = undefined;
+            w({ value: undefined, done: true });
+        }
+        this.onDetach(this);
+    }
+    frames() {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        const queued = self.queue.shift();
+                        if (queued !== undefined)
+                            return Promise.resolve({ value: queued, done: false });
+                        if (self.done) {
+                            self.onDetach(self);
+                            return Promise.resolve({ value: undefined, done: true });
+                        }
+                        return new Promise((resolve) => {
+                            self.waiter = resolve;
+                        });
+                    },
+                    return() {
+                        self.close();
+                        return Promise.resolve({ value: undefined, done: true });
+                    },
+                };
+            },
+        };
+    }
+}
+class LiveStream {
+    /** Retained text; `buf[0]` sits at offset {@link bufFrom}. */
+    buf = "";
+    bufFrom = 0;
+    seq = 0;
+    durableSeq = 0;
+    ended = false;
+    cancelled = false;
+    streamId;
+    user;
+    meta;
+    plane;
+    subs = new Set();
+    sealing;
+    draining = false;
+    forced = false;
+    /** The last drain round left a slice uncommitted: wait out the interval instead of re-attempting
+     *  immediately, so a down store costs a retry cadence and not a hot loop. */
+    stalled = false;
+    tick = null;
+    waiters = [];
+    sealed;
+    sealError;
+    constructor(streamId, user, meta, plane) {
+        this.streamId = streamId;
+        this.user = user;
+        this.meta = meta;
+        this.plane = plane;
+    }
+    // ---- producer side
+    push(text) {
+        if (this.sealing || this.ended)
+            throw new Error(`stream ${this.streamId} is closed`);
+        if (text.length === 0)
+            return;
+        const from = this.seq;
+        this.buf += text;
+        this.seq += text.length;
+        this.fanout({ type: "chunk", from, seq: this.seq, text });
+        if (this.seq - this.durableSeq >= this.plane.chars)
+            this.kick(true);
+        else
+            this.arm();
+    }
+    flush() {
+        const at = this.seq;
+        if (this.durableSeq >= at)
+            return Promise.resolve(this.durableSeq);
+        // After a failed seal the shortfall is PERMANENT (the stream ended; nothing will retry it), so a
+        // late flush rejects honestly instead of quietly re-running the seal.
+        if (this.ended) {
+            return Promise.reject(new Error(`stream ${this.streamId} ended with only ${this.durableSeq} of ${this.seq} characters durable`));
+        }
+        const p = new Promise((resolve, reject) => {
+            this.waiters.push({ at, resolve, reject });
+        });
+        this.kick(true);
+        return p;
+    }
+    /** Seal the stream. Resolves once the terminal checkpoint has committed; rejects if it could not
+     *  (the stream still ENDS — subscribers always get their `end` frame — the caller just learns the
+     *  store is short of what was produced). */
+    seal(status, error) {
+        // Already sealed: hand back the SAME settled promise (already marked handled below), so a second
+        // `close()`/`fail()` can neither re-seal nor mint a stray rejection.
+        if (this.ended)
+            return this.sealed?.promise ?? Promise.resolve();
+        if (!this.sealing) {
+            this.sealing = { status, error };
+            let resolve;
+            let reject;
+            const promise = new Promise((res, rej) => {
+                resolve = res;
+                reject = rej;
+            });
+            // A `fail()` nobody awaited must not become an unhandled rejection at process level. This
+            // marks the promise handled WITHOUT consuming it — a caller that does await still sees the
+            // rejection, because `await` attaches its own handler to the same promise.
+            promise.catch(() => { });
+            this.sealed = { resolve, reject, promise };
+            this.disarm();
+            this.kick(true);
+        }
+        return this.sealed.promise;
+    }
+    // ---- checkpoint driving
+    arm() {
+        if (this.tick || this.seq === this.durableSeq)
+            return;
+        this.tick = timer(() => {
+            this.tick = null;
+            this.kick(true);
+        }, this.plane.intervalMs);
+    }
+    disarm() {
+        if (this.tick)
+            clearTimeout(this.tick);
+        this.tick = null;
+    }
+    kick(force) {
+        if (force)
+            this.forced = true;
+        if (this.draining)
+            return;
+        this.draining = true;
+        void this.drain();
+    }
+    async drain() {
+        this.stalled = false;
+        try {
+            for (;;) {
+                // Sealing goes STRAIGHT to the seal: it writes the whole body (§3.4), so committing the
+                // outstanding tail as one more chunk first would be pure waste — and the seal repairs any
+                // earlier checkpoint that failed, which a tail commit could not.
+                if (this.sealing) {
+                    await this.commitSeal();
+                    break;
+                }
+                const behind = this.seq - this.durableSeq;
+                if (behind > 0 && (this.forced || behind >= this.plane.chars)) {
+                    // Consume the force BEFORE the round, not after: a `flush()` that lands while this round
+                    // is already in flight re-sets it and gets a round of its OWN — clearing it afterwards
+                    // would swallow that request and leave the flush to the interval cadence.
+                    this.forced = false;
+                    this.disarm();
+                    const failure = await this.commitTail();
+                    if (failure) {
+                        this.stalled = true;
+                        // A seal requested WHILE this checkpoint was in flight outranks the retry cadence: the
+                        // seal writes the whole body anyway, so it both supersedes and repairs the failed slice.
+                        // Backing off here instead would make `close()` wait out `intervalMs` for nothing. An
+                        // explicit re-force during the failed round likewise earns one immediate re-attempt —
+                        // someone is waiting on it — while an unforced failure stalls to the cadence.
+                        if (!this.sealing && !this.forced)
+                            break;
+                    }
+                    continue;
+                }
+                this.forced = false;
+                break;
+            }
+        }
+        finally {
+            this.draining = false;
+            if (!this.ended) {
+                // A pending seal ALWAYS proceeds at once — including out of a stall (see the loop above);
+                // otherwise a stall waits out the interval, and deltas that landed mid-commit may already
+                // meet the threshold and deserve an immediate round.
+                if (this.sealing)
+                    this.kick(false);
+                else if (this.stalled)
+                    this.arm();
+                else if (this.seq - this.durableSeq >= this.plane.chars)
+                    this.kick(false);
+                else
+                    this.arm();
+            }
+        }
+    }
+    /** @returns the failure, or `undefined` when the slice committed. */
+    async commitTail() {
+        const from = this.durableSeq;
+        const to = this.seq;
+        const text = this.buf.slice(from - this.bufFrom, to - this.bufFrom);
+        let out;
+        try {
+            out = await this.plane.commit({ kind: "append", streamId: this.streamId, from, seq: to, text });
+        }
+        catch (err) {
+            // The store may hold MORE than we believe — an append that committed while its ack was lost,
+            // somewhere in the retry chain. The read-back is the truth, and adopting it is what keeps the
+            // NEXT slice contiguous instead of overlapping (§3.3).
+            const truth = await this.plane.probeDurableSeq(this.streamId);
+            if (truth !== undefined && truth > this.durableSeq)
+                this.advanceDurable(truth);
+            this.plane.reportCheckpointError(err, { streamId: this.streamId, from, seq: to });
+            // Waiters that asked for THIS prefix learn it did not land; later waiters keep waiting for a
+            // later attempt. A durability failure is never silent.
+            this.rejectWaiters(to, err);
+            return { err };
+        }
+        if (out?.cancelRequested)
+            this.cancelled = true;
+        // `durableSeq` advances to what the store CONFIRMED — the mapped path reads it back, a `commit`
+        // callback may report it — never to a plane-side assumption. A confirmation short of `to` means
+        // this slice's `from` was stale (a prior ack loss the read-back could not see at the time): the
+        // guarded statements made it a no-op, and the next round re-covers from the confirmed offset.
+        const confirmed = out?.seq ?? to;
+        if (confirmed > this.durableSeq)
+            this.advanceDurable(confirmed);
+        if (confirmed < to) {
+            const err = new Error(`stream ${this.streamId}: the store confirmed ${confirmed} of ${to} — re-covering from there`);
+            this.plane.reportCheckpointError(err, { streamId: this.streamId, from, seq: to });
+            this.rejectWaiters(to, err);
+            return { err };
+        }
+        return undefined;
+    }
+    /** The one place durable progress is recorded: position, `durable` frame, buffer trim, waiters. */
+    advanceDurable(seq) {
+        this.durableSeq = seq;
+        this.fanout({ type: "durable", seq });
+        this.trim();
+        this.resolveWaiters();
+    }
+    async commitSeal() {
+        const seal = this.sealing;
+        const from = this.durableSeq;
+        try {
+            await this.plane.commit({
+                kind: "close",
+                streamId: this.streamId,
+                from,
+                seq: this.seq,
+                // A trimmed buffer (only reachable in `commit`-callback mode, where the app opted into
+                // trimming) cannot supply the whole body: `bodyFrom` says where the retained text starts,
+                // so the app can still append exactly the outstanding tail (`body.slice(from - bodyFrom)`).
+                body: this.buf,
+                bodyFrom: this.bufFrom,
+                status: seal.status,
+                ...(seal.error !== undefined ? { error: seal.error } : {}),
+            });
+            this.durableSeq = this.seq;
+        }
+        catch (err) {
+            this.sealError = err;
+            this.plane.reportCheckpointError(err, { streamId: this.streamId, from, seq: this.seq });
+        }
+        this.ended = true;
+        this.disarm();
+        this.rejectWaiters(Number.POSITIVE_INFINITY, new Error(`stream ${this.streamId} ended with only ${this.durableSeq} of ${this.seq} characters durable`));
+        this.resolveWaiters();
+        const frame = {
+            type: "end",
+            seq: this.durableSeq,
+            status: seal.status,
+            ...(seal.error !== undefined ? { error: seal.error } : {}),
+        };
+        for (const sub of [...this.subs])
+            sub.finish(frame);
+        this.plane.retire(this.streamId);
+        if (this.sealError)
+            this.sealed?.reject(this.sealError);
+        else
+            this.sealed?.resolve();
+    }
+    /** Keep everything at or above `durableSeq`, plus a slack window below it so a client whose IVM
+     *  view lags one checkpoint can still join without a `stale` round trip (§4). A `retainChars` of
+     *  `Infinity` (the mapped-table default — compaction needs the whole text) never trims. */
+    trim() {
+        if (!Number.isFinite(this.plane.retainChars))
+            return;
+        const floor = Math.max(0, this.durableSeq - this.plane.retainChars);
+        if (floor <= this.bufFrom)
+            return;
+        this.buf = this.buf.slice(floor - this.bufFrom);
+        this.bufFrom = floor;
+    }
+    resolveWaiters() {
+        if (this.waiters.length === 0)
+            return;
+        const still = [];
+        for (const w of this.waiters) {
+            if (w.at <= this.durableSeq)
+                w.resolve(this.durableSeq);
+            else
+                still.push(w);
+        }
+        this.waiters = still;
+    }
+    rejectWaiters(upTo, err) {
+        if (this.waiters.length === 0)
+            return;
+        const still = [];
+        for (const w of this.waiters) {
+            if (w.at <= upTo && w.at > this.durableSeq)
+                w.reject(err);
+            else
+                still.push(w);
+        }
+        this.waiters = still;
+    }
+    // ---- subscriber side
+    fanout(frame) {
+        for (const sub of [...this.subs]) {
+            if (!sub.offer(frame)) {
+                // Bounded, then dropped: a reader that stopped draining costs itself a rejoin, never the
+                // producer's memory.
+                sub.finish({ type: "stale", floorSeq: this.bufFrom, durableSeq: this.durableSeq });
+                this.subs.delete(sub);
+            }
+        }
+    }
+    /** Attach a reader at `from`. Runs in ONE synchronous block — snapshot, replay, register — so no
+     *  delta can slip between the replay and the live tail (the gap-free half of contract S). */
+    subscribe(from) {
+        const sub = new Subscriber(this.plane.maxQueuedFrames, (s) => this.subs.delete(s));
+        // Floored as well as clamped: a fractional `from` (a hand-built subscribe input) would otherwise
+        // produce a replay chunk whose `text.length !== seq - from`, breaking the frame invariant.
+        const at = Math.min(Math.max(Math.floor(from), 0), this.seq);
+        if (at < this.bufFrom) {
+            sub.finish({ type: "stale", floorSeq: this.bufFrom, durableSeq: this.durableSeq });
+            return this.wrap(sub);
+        }
+        sub.offer({ type: "open", streamId: this.streamId, from: at, seq: this.seq, durableSeq: this.durableSeq, ended: this.ended });
+        if (this.seq > at) {
+            sub.offer({ type: "chunk", from: at, seq: this.seq, text: this.buf.slice(at - this.bufFrom) });
+        }
+        if (this.durableSeq > at)
+            sub.offer({ type: "durable", seq: this.durableSeq });
+        if (this.ended) {
+            const seal = this.sealing ?? { status: "interrupted" };
+            sub.finish({
+                type: "end",
+                seq: this.durableSeq,
+                status: seal.status,
+                ...(seal.error !== undefined ? { error: seal.error } : {}),
+            });
+            return this.wrap(sub);
+        }
+        this.subs.add(sub);
+        return this.wrap(sub);
+    }
+    wrap(sub) {
+        return { streamId: this.streamId, frames: sub.frames(), close: () => sub.close() };
+    }
+    /** Drop every reader without sealing (process teardown — `drainStreams` seals first). */
+    detachAll() {
+        for (const sub of [...this.subs])
+            sub.close();
+        this.subs.clear();
+        this.disarm();
+    }
+}
+export class StreamPlane {
+    chars;
+    intervalMs;
+    retries;
+    retainChars;
+    lingerMs;
+    maxQueuedFrames;
+    live = new Map();
+    opts;
+    sink;
+    mapped;
+    tables;
+    /** The open CAS token (§5.1): `hostId`, or a random per-plane stand-in when only the CAS — not
+     *  routing — needs it. */
+    openToken;
+    constructor(opts, sink) {
+        this.opts = opts;
+        this.sink = sink;
+        this.chars = opts.policy?.chars ?? DEFAULT_CHECKPOINT_CHARS;
+        this.intervalMs = opts.policy?.intervalMs ?? DEFAULT_CHECKPOINT_INTERVAL_MS;
+        this.retries = opts.policy?.retries ?? DEFAULT_CHECKPOINT_RETRIES;
+        this.lingerMs = opts.lingerMs ?? DEFAULT_LINGER_MS;
+        this.maxQueuedFrames = opts.maxQueuedFrames ?? DEFAULT_MAX_QUEUED_FRAMES;
+        this.openToken = opts.hostId ?? randomOpenToken();
+        if ("tables" in opts.checkpoint) {
+            if (!sink)
+                throw new TypeError("streams.checkpoint.tables needs a SQL-capable mutation backend");
+            this.tables = opts.checkpoint.tables;
+            this.mapped = new MappedTableSql(opts.checkpoint.tables, sink.dialect);
+            // Options this mode cannot honour are refused loudly (the room-profile rule), never ignored.
+            if (opts.retainChars !== undefined) {
+                throw new TypeError("streams.retainChars is `commit`-mode only — mapped tables retain the whole text for compaction (§3.4)");
+            }
+            if (opts.hostId !== undefined && resolveStreamColumns(opts.checkpoint.tables.columns).host === undefined) {
+                throw new TypeError("streams.hostId does nothing in tables mode until columns.host names where to persist it");
+            }
+            // Compaction writes the WHOLE body at close, so the buffer is retained in full. `retainChars`
+            // is honoured only where the app owns persistence and may not need the tail.
+            this.retainChars = Number.POSITIVE_INFINITY;
+        }
+        else {
+            this.retainChars = opts.retainChars ?? DEFAULT_RETAIN_CHARS;
+        }
+    }
+    /** Open a stream on an EXISTING message row (§5): the app's own mutator wrote it, alongside the
+     *  user's prompt, so the pointer is already durable and every client's query already shows the
+     *  message. This verifies it and flips it to `streaming`. */
+    async open(input) {
+        if (this.live.has(input.streamId)) {
+            throw new Error(`stream ${input.streamId} is already open on this host`);
+        }
+        const stream = new LiveStream(input.streamId, input.user, input.meta, this);
+        this.live.set(input.streamId, stream);
+        try {
+            if (this.mapped)
+                await this.assertOpenable(input.streamId);
+            await this.commit({
+                kind: "open",
+                streamId: input.streamId,
+                meta: input.meta ?? null,
+                ...(this.opts.hostId !== undefined ? { hostId: this.opts.hostId } : {}),
+                startedAt: Date.now(),
+            });
+        }
+        catch (err) {
+            this.live.delete(input.streamId);
+            throw err;
+        }
+        return {
+            streamId: stream.streamId,
+            get seq() {
+                return stream.seq;
+            },
+            get durableSeq() {
+                return stream.durableSeq;
+            },
+            get cancelled() {
+                return stream.cancelled;
+            },
+            push: (text) => stream.push(text),
+            flush: () => stream.flush(),
+            pump: async (deltas) => {
+                // `for await` closes the iterator on `break`, which is what aborts the SDK's underlying
+                // request — the whole point of honouring cancellation here rather than in the caller.
+                for await (const d of deltas) {
+                    stream.push(d);
+                    if (stream.cancelled)
+                        break;
+                }
+            },
+            close: () => stream.seal(stream.cancelled ? "cancelled" : "complete"),
+            fail: (error) => stream.seal("error", errText(error)),
+        };
+    }
+    /**
+     * The read-only precondition on the app's message row, checked ONCE per `open` (§5.1). Read-only on
+     * purpose: it is a decision about the app's data, so re-deciding it per write attempt would let a
+     * lost ack turn a success into a refusal.
+     *
+     * The `streaming` check is the **single-flight guard**, and it lives at the ROW rather than in this
+     * process's map because the thing it defends against is distributed: the kick that starts a
+     * generation is an at-least-once effect (a retried mutation envelope re-runs its post-commit code,
+     * §10.5), so a second kick can land on another instance, where the in-memory map is empty. Two
+     * producers on one `streamId` would interleave: both CAS the same length, one stalls, and whichever
+     * closes last overwrites the body with ITS buffer. Cheap to refuse; expensive to debug.
+     *
+     * This probe alone is check-then-act — it and the open write are separate round trips, so two
+     * SIMULTANEOUS kicks can both pass it. Mapping a `host` column closes that window: the open write
+     * turns conditional and {@link verifyOpenWinner}'s read-back names the winner.
+     */
+    async assertOpenable(streamId) {
+        const cols = resolveStreamColumns(this.tables.columns);
+        const rows = await this.sink.sql.query(this.mapped.probeOpen(), [streamId]);
+        const row = rows[0];
+        if (!row) {
+            throw new StreamOpenRefused(`stream ${streamId}: no row in "${this.tables.message}" — the app's own mutator must write the message ` +
+                `(with its chatId/role/…) BEFORE opening the stream on it`);
+        }
+        // A NULL length is refused as loudly as an advanced one, and for a subtler reason: it is the CAS
+        // column, and `WHERE seq = 0` can never match NULL. A nullable column would let every chunk
+        // insert land while its length CAS silently matched nothing — the one failure mode this plane
+        // cannot detect (`batch` reports no row count) and one compaction would paper over (§5.1).
+        if (typeof row.seq !== "number") {
+            throw new StreamOpenRefused(`stream ${streamId}: "${this.tables.message}"."${cols.seq}" is ${row.seq === null ? "NULL" : typeof row.seq} — ` +
+                `the length column must be NOT NULL DEFAULT 0 (it is compare-and-swapped on every checkpoint, and no ` +
+                `comparison matches NULL)`);
+        }
+        if (row.seq !== 0) {
+            throw new StreamOpenRefused(`stream ${streamId}: the message row already holds ${row.seq} characters — a regeneration is a NEW message ` +
+                `id, never a resume of an advanced row`);
+        }
+        if (row.status === STREAM_STATUS_STREAMING) {
+            throw new StreamOpenRefused(`stream ${streamId}: "${cols.status}" is already "${STREAM_STATUS_STREAMING}" — another producer holds this ` +
+                `stream. Two producers on one stream interleave their checkpoints; if the first one's host died, the ` +
+                `sweeper marking it "interrupted" is what releases the row (§7)`);
+        }
+    }
+    async subscribe(input) {
+        const stream = this.live.get(input.streamId);
+        const from = input.from ?? 0;
+        // Authorize BEFORE existence is consulted: a denial must not double as an existence oracle.
+        const verdict = await this.opts.authorize({
+            user: input.user,
+            streamId: input.streamId,
+            from,
+            meta: stream === undefined ? undefined : stream.meta,
+            request: input.request,
+        });
+        if (verdict === false)
+            throw new StreamForbidden(input.streamId);
+        if (!stream)
+            return oneFrame(input.streamId, { type: "absent" });
+        return stream.subscribe(from);
+    }
+    /** Seal every live stream `interrupted`. In mapped-table mode the seal IS the compaction, so a
+     *  graceful drain loses nothing PRODUCED; the status still says the response was cut short rather
+     *  than claiming completion (§5). Wire it to SIGTERM. */
+    async drainStreams() {
+        await Promise.allSettled([...this.live.values()].map((s) => s.seal("interrupted")));
+    }
+    /** Teardown: drop readers and timers WITHOUT a durable write (that is `drainStreams`). */
+    closeSync() {
+        for (const s of this.live.values())
+            s.detachAll();
+        this.live.clear();
+    }
+    /** A sealed stream stays joinable for the linger window, so a subscribe that races the last token
+     *  still gets `end` (and the tail it missed) rather than a bare `absent`. */
+    retire(streamId) {
+        timer(() => {
+            const entry = this.live.get(streamId);
+            if (entry?.ended) {
+                this.live.delete(streamId);
+                entry.detachAll();
+            }
+        }, this.lingerMs);
+    }
+    reportCheckpointError(err, info) {
+        // Reporting runs INSIDE the drain loop, so a throwing hook would take the loop down with it and
+        // wedge the stream — the one failure mode a diagnostic must never cause.
+        try {
+            if (this.opts.onCheckpointError)
+                this.opts.onCheckpointError(err, info);
+            else
+                console.error(`[rindle api-server] stream ${info.streamId}: checkpoint ${info.from}→${info.seq} failed:`, err);
+        }
+        catch (hookErr) {
+            console.error(`[rindle api-server] stream ${info.streamId}: onCheckpointError itself threw:`, hookErr);
+        }
+    }
+    /** Drive ONE checkpoint, retrying on failure. Every statement it emits is idempotent under replay
+     *  — the chunk insert dedups on its deterministic id, the length CAS refuses to apply twice, the
+     *  compaction is a whole-row overwrite — so "retry until it sticks" needs no dedup ledger and no
+     *  `lmid` (§3.3). */
+    async commit(input) {
+        let lastErr;
+        for (let attempt = 0; attempt <= this.retries; attempt++) {
+            if (attempt > 0)
+                await delay(RETRY_BACKOFF_MS * 2 ** (attempt - 1));
+            try {
+                return await this.commitOnce(input);
+            }
+            catch (err) {
+                if (err instanceof StreamOpenRefused)
+                    throw err; // a settled verdict, not a blip
+                lastErr = err;
+            }
+        }
+        throw lastErr;
+    }
+    async commitOnce(input) {
+        const target = this.opts.checkpoint;
+        if ("commit" in target)
+            return (await target.commit(input)) ?? undefined;
+        const sql = this.sink.sql;
+        const mapped = this.mapped;
+        switch (input.kind) {
+            case "open": {
+                // The PRECONDITION is checked once, in `assertOpenable`, before this write — never here.
+                // Re-reading it per attempt would make a lost ack on the write below refuse its own success
+                // (the row would already say `streaming`).
+                await sql.batch([mapped.markStreaming(input.streamId, this.openToken)]);
+                await this.verifyOpenWinner(input.streamId);
+                return undefined;
+            }
+            case "append": {
+                try {
+                    await sql.batch(mapped.append(input.streamId, input.from, input.seq, input.text));
+                }
+                catch (err) {
+                    // The batch may have COMMITTED with its ack lost. The read-back is the truth: a row at
+                    // (or past) this slice's end means it landed, and the throw was only the reply.
+                    const truth = await this.readAppendState(input.streamId).catch(() => undefined);
+                    if (truth === undefined || truth.seq < input.seq)
+                        throw err;
+                    return truth;
+                }
+                // The read-back CONFIRMS the append (the guarded statements report no row count). If it
+                // throws, the retry is safe: a replay of an applied slice no-ops on the guard and confirms
+                // on its own read-back.
+                return await this.readAppendState(input.streamId);
+            }
+            case "close": {
+                await sql.batch(mapped.compact(input.streamId, input.body, input.status, input.error));
+                return undefined;
+            }
+        }
+    }
+    /** The read-back half of the open CAS, run only when a `host` column is mapped. The probe in
+     *  `assertOpenable` and the open write are separate round trips, so bare check-then-act leaves a
+     *  window where two simultaneous kicks both pass the probe; the conditional `markStreaming`
+     *  matches nothing when a rival got there first, and whichever token the row now holds names the
+     *  winner — a true CAS with no row counts needed. A replayed open (lost ack) reads back its OWN
+     *  token and proceeds. */
+    async verifyOpenWinner(streamId) {
+        const probe = this.mapped.probeHost();
+        if (probe === undefined)
+            return;
+        const rows = await this.sink.sql.query(probe, [streamId]);
+        if (rows[0]?.host !== this.openToken) {
+            throw new StreamOpenRefused(`stream ${streamId}: another producer won the open race (the row's host is ` +
+                `${JSON.stringify(rows[0]?.host ?? null)}) — two producers on one stream interleave their checkpoints, ` +
+                `so the loser stands down`);
+        }
+    }
+    /** The post-append read-back (§3.2): the row's authoritative length — which both CONFIRMS an
+     *  append (the guarded batch reports no row count) and absorbs a committed-but-ack-lost one —
+     *  plus the reader's cancel flag when mapped (§6), riding the same indexed point read. This read
+     *  is LOAD-BEARING: a failure here fails the append attempt (retried, then stalled), because
+     *  claiming durability the store did not confirm is the one dishonesty this plane refuses. */
+    async readAppendState(streamId) {
+        const rows = await this.sink.sql.query(this.mapped.probeState(), [
+            streamId,
+        ]);
+        const row = rows[0];
+        if (row === undefined || typeof row.seq !== "number") {
+            throw new Error(`stream ${streamId}: the read-back found no usable message row`);
+        }
+        return { seq: row.seq, ...(this.mapped.hasCancel ? { cancelRequested: Boolean(row.cancel) } : {}) };
+    }
+    /** The store's word on how much is durable — for resynchronizing after a FAILED append, where a
+     *  lost ack may have left the store ahead of the plane. `undefined` in `commit` mode (no readable
+     *  authority) or when the read itself fails (the next attempt retries the resync too). */
+    async probeDurableSeq(streamId) {
+        if (!this.mapped)
+            return undefined;
+        try {
+            return (await this.readAppendState(streamId)).seq;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** The open probe's verdict: the message row is missing or already advanced. Not retried — it is a
+ *  settled statement about the app's data, and retrying re-asks a question already answered. */
+export class StreamOpenRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StreamOpenRefused";
+    }
+}
+/** Refused by {@link RindleStreamOptions.authorize}. Distinct from the api-server's own
+ *  `RindleApiError` so this module stays importable without the server (no cycle); the server
+ *  translates it to a 403 at the handler seam. */
+export class StreamForbidden extends Error {
+    streamId;
+    constructor(streamId) {
+        super(`stream ${streamId}: forbidden`);
+        this.name = "StreamForbidden";
+        this.streamId = streamId;
+    }
+}
+function oneFrame(streamId, frame) {
+    let taken = false;
+    return {
+        streamId,
+        frames: {
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        if (taken)
+                            return Promise.resolve({ value: undefined, done: true });
+                        taken = true;
+                        return Promise.resolve({ value: frame, done: false });
+                    },
+                };
+            },
+        },
+        close: () => {
+            taken = true;
+        },
+    };
+}
+// ------------------------------------------------------------------------------- SSE transport
+/** Headers for the SSE response. `x-accel-buffering` is the nginx-family opt-out — without it a
+ *  buffering proxy holds the tokens and hands the user a paragraph at a time. */
+export const STREAM_SSE_HEADERS = {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-cache, no-transform",
+    connection: "keep-alive",
+    "x-accel-buffering": "no",
+};
+/** Pull a subscribe request out of a fetch-style GET: `?streamId=…&from=…`, with `Last-Event-ID`
+ *  winning over an explicit `from` (a reconnecting `EventSource` knows better than its own URL —
+ *  the URL is the ORIGINAL join point, the header is where it actually got to). */
+export function streamRequestFromHttp(req) {
+    const url = new URL(req.url);
+    const streamId = url.searchParams.get("streamId") ?? "";
+    const lastEventId = req.headers.get("last-event-id");
+    const raw = lastEventId ?? url.searchParams.get("from") ?? "0";
+    const from = Number.parseInt(raw, 10);
+    return { streamId, from: Number.isFinite(from) && from > 0 ? from : 0 };
+}
+/**
+ * Encode a subscription as an SSE body. Each positional frame carries `id: <seq>`, so a browser
+ * `EventSource` that drops the connection resumes at exactly the right offset with no application
+ * code — its own `Last-Event-ID` header is the `from` of the next subscribe ({@link
+ * streamRequestFromHttp}).
+ *
+ * The reader must close the `EventSource` on the `end` frame: `EventSource` reconnects on ANY close,
+ * including a clean one.
+ */
+export function streamFramesToSse(sub, opts) {
+    const encoder = new TextEncoder();
+    const keepAliveMs = opts?.keepAliveMs ?? 15_000;
+    let ping = null;
+    let cancelled = false;
+    let iter;
+    // PULL-based on purpose: a frame is taken from the subscription only when the consumer has
+    // demand, so a slow HTTP client backs frames up in the SUBSCRIBER's bounded queue — where
+    // `maxQueuedFrames` drops it with `stale` (§4) — instead of unboundedly in this stream's own.
+    return new ReadableStream({
+        start(controller) {
+            iter = sub.frames[Symbol.asyncIterator]();
+            const beat = () => {
+                if (cancelled)
+                    return;
+                // A comment line: keeps intermediaries from reaping an idle connection, costs 8 bytes.
+                controller.enqueue(encoder.encode(": ping\n\n"));
+                ping = timer(beat, keepAliveMs);
+            };
+            ping = timer(beat, keepAliveMs);
+        },
+        async pull(controller) {
+            const next = await iter.next();
+            if (cancelled)
+                return;
+            if (next.done) {
+                if (ping)
+                    clearTimeout(ping);
+                sub.close();
+                controller.close();
+                return;
+            }
+            const id = frameResumePoint(next.value);
+            const head = id === undefined ? "" : `id: ${id}\n`;
+            controller.enqueue(encoder.encode(`${head}data: ${JSON.stringify(next.value)}\n\n`));
+        },
+        cancel() {
+            cancelled = true;
+            if (ping)
+                clearTimeout(ping);
+            sub.close();
+        },
+    });
+}
+//# sourceMappingURL=streams.js.map