@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/keepers/kit/streamLog.js

@@ -0,0 +1,697 @@
+import { chmodSync, closeSync, fstatSync, fsync, fsyncSync, ftruncateSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import path from 'node:path';
+export const SEGMENT_BYTES = 8 * 1024 * 1024;
+export const SOFT_QUOTA_BYTES = 256 * 1024 * 1024;
+export const FSYNC_INTERVAL_MS = 100;
+export const FSYNC_BYTES = 64 * 1024;
+export const IMMEDIATE_KINDS = ['spawn', 'exit', 'checkpoint', 'commit'];
+const INDEX_STRIDE = 64;
+const CHUNK_BYTES = 1024 * 1024;
+const SUBSCRIBE_BATCH = 256;
+const SEGMENT_NAME = /^seg-(\d+)\.log$/;
+const CHECKPOINT_NAME = /^checkpoint-(\d+)\.json$/;
+const META_FILE = 'meta.json';
+const KEPT_CHECKPOINTS = 2;
+export class StreamCorruptError extends Error {
+    constructor(message) { super(message); this.name = 'StreamCorruptError'; }
+}
+const openStreams = new Set();
+function fsyncDirectory(dir) {
+    let fd;
+    try {
+        fd = openSync(dir, 'r');
+        fsyncSync(fd);
+    }
+    catch { /* best effort: some filesystems cannot fsync a directory */ }
+    finally {
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* ignore */ }
+    }
+}
+function writeAll(fd, data) {
+    let written = 0;
+    while (written < data.length)
+        written += writeSync(fd, data, written, data.length - written);
+}
+/** Atomically replaces `file` (tmp + fsync + rename + directory fsync), mode 0600. */
+function atomicWrite(file, content) {
+    const temp = `${file}.tmp`;
+    const fd = openSync(temp, 'w', 0o600);
+    try {
+        writeAll(fd, Buffer.from(content));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temp, file);
+    fsyncDirectory(path.dirname(file));
+}
+/**
+ * Calls `onLine(line, pos)` for every complete (newline-terminated) line in `[start, end)` of `fd`; `line` is only valid
+ * during the call. Stops when it returns false. Returns the position just after the last complete line seen.
+ */
+function scanLines(fd, start, end, onLine) {
+    const chunk = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, Math.max(1, end - start)));
+    let pos = start; // file position of chunk[0]
+    let lineStart = start;
+    let carry = [];
+    while (pos < end) {
+        const n = readSync(fd, chunk, 0, Math.min(chunk.length, end - pos), pos);
+        if (n <= 0)
+            break;
+        const view = chunk.subarray(0, n);
+        let from = 0;
+        for (;;) {
+            const nl = view.indexOf(10, from);
+            if (nl < 0)
+                break;
+            let line;
+            if (carry.length > 0) {
+                carry.push(chunk.subarray(from, nl));
+                line = Buffer.concat(carry);
+                carry = [];
+            }
+            else
+                line = chunk.subarray(from, nl);
+            if (onLine(line, lineStart) === false)
+                return lineStart;
+            lineStart = pos + nl + 1;
+            from = nl + 1;
+        }
+        if (from < n)
+            carry.push(Buffer.from(chunk.subarray(from, n)));
+        pos += n;
+    }
+    return lineStart;
+}
+function parseRecord(line) {
+    try {
+        const value = JSON.parse(line.toString('utf8'));
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const r = value;
+            if (Number.isSafeInteger(r.o) && typeof r.k === 'string' && typeof r.t === 'number')
+                return r;
+        }
+    }
+    catch { /* torn or garbage */ }
+    return undefined;
+}
+export class StreamLog {
+    /** Bytes dropped from the newest segment's end when the log was opened (a torn tail); 0 for a clean open. */
+    repairedBytes;
+    dir;
+    segmentBytes;
+    softQuota;
+    fsyncIntervalMs;
+    fsyncBytes;
+    immediate;
+    now;
+    syncFile;
+    onError;
+    segments = [];
+    active;
+    nextOffset = 0;
+    committedOffset = -1;
+    tail;
+    checkpointSeq = 0;
+    checkpointOffset = -1;
+    totalBytes = 0;
+    /** Bytes ever appended / bytes known durable (by a completed fsync). The difference is what a crash could still lose. */
+    appendedBytes = 0;
+    syncedBytes = 0;
+    syncTimer;
+    syncCount = 0;
+    syncErrors = 0;
+    lastSyncError;
+    /** The one background fsync (batched appends never fsync on the event loop); `again` = more bytes arrived meanwhile. */
+    inflight;
+    closed = false;
+    notifyPending = false;
+    watchers = new Set();
+    static open(options) { return new StreamLog(options); }
+    constructor(options) {
+        this.dir = path.resolve(options.dir);
+        this.segmentBytes = options.segmentBytes ?? SEGMENT_BYTES;
+        this.softQuota = options.softQuotaBytes ?? SOFT_QUOTA_BYTES;
+        this.fsyncIntervalMs = options.fsyncIntervalMs ?? FSYNC_INTERVAL_MS;
+        this.fsyncBytes = options.fsyncBytes ?? FSYNC_BYTES;
+        this.immediate = new Set(options.immediateKinds ?? IMMEDIATE_KINDS);
+        this.now = options.now ?? Date.now;
+        this.onError = options.onError;
+        this.syncFile = options.syncFile ?? fsyncSync;
+        if (options.baseOffset !== undefined && (!Number.isSafeInteger(options.baseOffset) || options.baseOffset < 0))
+            throw new RangeError(`Invalid baseOffset ${options.baseOffset}`);
+        if (openStreams.has(this.dir))
+            throw new Error(`Stream log already open in this process: ${this.dir}`);
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        chmodSync(this.dir, 0o700);
+        openStreams.add(this.dir);
+        let repaired = 0;
+        try {
+            repaired = this.recover(options.baseOffset);
+            if (repaired > 0)
+                this.append({ k: 'discontinuity', reason: 'torn-tail', droppedBytes: repaired }, { sync: true });
+        }
+        catch (error) {
+            // Release everything: the directory stays openable and no descriptor leaks.
+            this.closed = true;
+            this.closeActive();
+            if (this.syncTimer)
+                clearTimeout(this.syncTimer);
+            openStreams.delete(this.dir);
+            throw error;
+        }
+        this.repairedBytes = repaired;
+    }
+    // ---- recovery ----------------------------------------------------------------------------------------------
+    recover(baseOffset) {
+        const names = readdirSync(this.dir);
+        if (baseOffset !== undefined && baseOffset > 0 && !names.some((n) => SEGMENT_NAME.test(n) || n === META_FILE)) {
+            // A fresh log continuing another one's offsets: the watermark is durable before anything is appended.
+            atomicWrite(path.join(this.dir, META_FILE), JSON.stringify({ v: 1, committed: baseOffset - 1, t: this.now() }));
+            names.push(META_FILE);
+        }
+        for (const name of names)
+            if (name.endsWith('.tmp'))
+                try {
+                    unlinkSync(path.join(this.dir, name));
+                }
+                catch { /* ignore */ }
+        const firsts = names.map((n) => SEGMENT_NAME.exec(n)).filter((m) => !!m).map((m) => Number(m[1])).sort((a, b) => a - b);
+        for (let i = 0; i < firsts.length; i++) {
+            const file = path.join(this.dir, `seg-${firsts[i]}.log`);
+            const bytes = fstatSizeOf(file);
+            const count = i + 1 < firsts.length ? firsts[i + 1] - firsts[i] : 0; // the newest is counted by the repair scan
+            this.segments.push({ first: firsts[i], file, bytes, count, idx: [], indexed: false });
+        }
+        let meta = {};
+        try {
+            meta = JSON.parse(readFileSync(path.join(this.dir, META_FILE), 'utf8'));
+        }
+        catch { /* absent or unreadable: derived below */ }
+        this.committedOffset = Number.isSafeInteger(meta.committed) ? meta.committed : -1;
+        this.tail = meta.tail;
+        let repaired = 0;
+        const newest = this.segments[this.segments.length - 1];
+        if (newest)
+            repaired = this.repairNewest(newest);
+        // Everything before the oldest retained segment was committed, even if meta.json cannot say so.
+        const firstRetained = this.segments[0]?.first;
+        if (firstRetained !== undefined)
+            this.committedOffset = Math.max(this.committedOffset, firstRetained - 1);
+        this.nextOffset = newest ? newest.first + newest.count : 0;
+        this.nextOffset = Math.max(this.nextOffset, this.committedOffset + 1);
+        this.totalBytes = this.segments.reduce((sum, s) => sum + s.bytes, 0);
+        // A crash between writing meta.json and deleting the covered segments: finish the deletion.
+        this.deleteCommittedSegments();
+        // Resume appending to the newest segment if any remains (reopen it for append).
+        const last = this.segments[this.segments.length - 1];
+        if (last && last.first + last.count === this.nextOffset) {
+            const fd = openSync(last.file, 'a', 0o600);
+            this.active = { seg: last, fd };
+        }
+        const checkpoints = this.checkpointFiles();
+        if (checkpoints.length > 0)
+            this.checkpointSeq = checkpoints[checkpoints.length - 1].seq;
+        this.checkpointOffset = this.latestCheckpoint()?.offset ?? -1;
+        return repaired;
+    }
+    /** Scans the newest segment: counts and indexes its records and truncates anything after the last intact one. */
+    repairNewest(seg) {
+        const fd = openSync(seg.file, 'r+', 0o600);
+        try {
+            let expected = seg.first;
+            let good = 0;
+            const idx = [];
+            const size = fstatSync(fd).size;
+            scanLines(fd, 0, size, (line, pos) => {
+                const record = parseRecord(line);
+                if (!record || record.o !== expected)
+                    return false;
+                if ((expected - seg.first) % INDEX_STRIDE === 0)
+                    idx.push(pos);
+                expected++;
+                good = pos + line.length + 1;
+                return true;
+            });
+            let dropped = 0;
+            if (good < size) {
+                dropped = size - good;
+                ftruncateSync(fd, good);
+                fsyncSync(fd);
+            }
+            seg.bytes = good;
+            seg.count = expected - seg.first;
+            seg.idx = idx;
+            seg.indexed = true;
+            return dropped;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    deleteCommittedSegments() {
+        let removed = false;
+        while (this.segments.length > 0) {
+            const seg = this.segments[0];
+            if (seg.first + seg.count - 1 > this.committedOffset)
+                break;
+            if (this.active?.seg === seg) {
+                this.retireFd(this.active.fd);
+                this.active = undefined;
+            }
+            try {
+                unlinkSync(seg.file);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            this.totalBytes -= seg.bytes;
+            this.segments.shift();
+            removed = true;
+        }
+        if (removed)
+            fsyncDirectory(this.dir);
+    }
+    // ---- append ------------------------------------------------------------------------------------------------
+    /**
+     * Appends one record (stamping `o` and `t`) and returns it.
+     *
+     * Durability: ordinary records are fsynced in the background (at most one fsync in flight; started when 64 KiB are
+     * unsynced or 100 ms after the first unsynced append) and never block the caller. Records of an immediate kind
+     * (spawn/exit/checkpoint/commit by default) or appended with `sync: true` are fsynced synchronously before returning.
+     * Once the line is written the append has succeeded: if that synchronous fsync then fails, the record IS in the log
+     * (a retry would duplicate it), so the error is reported through `onError` and `stats().syncErrors`/`lastSyncError`
+     * instead of being thrown, and the record stays counted as unsynced. Only a failure to write the line itself throws.
+     */
+    append(input, options = {}) {
+        this.assertOpen();
+        if (typeof input.k !== 'string' || input.k === '')
+            throw new TypeError('A stream record needs a non-empty kind `k`');
+        if ('o' in input || 't' in input)
+            throw new TypeError('`o` and `t` are stamped by the stream log');
+        const { k, ...rest } = input;
+        const record = { o: this.nextOffset, t: this.now(), k, ...rest };
+        const line = Buffer.from(`${JSON.stringify(record)}\n`);
+        let target = this.active;
+        if (target && target.seg.bytes > 0 && target.seg.bytes + line.length > this.segmentBytes) {
+            this.sealActive();
+            target = undefined;
+        }
+        if (!target)
+            target = this.startSegment(record.o);
+        try {
+            writeAll(target.fd, line);
+        }
+        catch (error) {
+            try {
+                ftruncateSync(target.fd, target.seg.bytes);
+            }
+            catch { /* the next open repairs it */ }
+            throw error;
+        }
+        const seg = target.seg;
+        if (seg.count % INDEX_STRIDE === 0)
+            seg.idx.push(seg.bytes);
+        seg.bytes += line.length;
+        seg.count++;
+        this.totalBytes += line.length;
+        this.nextOffset++;
+        this.appendedBytes += line.length;
+        this.scheduleNotify();
+        if (options.sync || this.immediate.has(k)) {
+            try {
+                this.sync();
+            }
+            catch (error) {
+                this.reportSyncError(error);
+            }
+        }
+        else if (this.appendedBytes - this.syncedBytes >= this.fsyncBytes)
+            this.startBackgroundSync();
+        else if (!this.syncTimer && !this.inflight) {
+            this.syncTimer = setTimeout(() => { this.syncTimer = undefined; this.startBackgroundSync(); }, this.fsyncIntervalMs);
+            this.syncTimer.unref();
+        }
+        return record;
+    }
+    reportSyncError(error) {
+        this.syncErrors++;
+        this.lastSyncError = error instanceof Error ? error : new Error(String(error));
+        this.onError?.(this.lastSyncError);
+    }
+    /** Starts the single background fsync of the active segment, or asks the running one to go again when it finishes. */
+    startBackgroundSync() {
+        if (this.closed || !this.active)
+            return;
+        if (this.inflight) {
+            this.inflight.again = true;
+            return;
+        }
+        if (this.appendedBytes === this.syncedBytes)
+            return;
+        const flight = { fd: this.active.fd, covers: this.appendedBytes, again: false, closeAfter: false };
+        this.inflight = flight;
+        fsync(flight.fd, (error) => {
+            this.inflight = undefined;
+            if (flight.closeAfter) {
+                try {
+                    closeSync(flight.fd);
+                }
+                catch { /* ignore */ }
+            }
+            if (error) {
+                if (!flight.closeAfter)
+                    this.reportSyncError(error);
+                return;
+            }
+            this.syncCount++;
+            this.syncedBytes = Math.max(this.syncedBytes, flight.covers);
+            if (this.closed)
+                return;
+            if (flight.again || this.appendedBytes - this.syncedBytes >= this.fsyncBytes)
+                this.startBackgroundSync();
+            else if (this.appendedBytes > this.syncedBytes && !this.syncTimer) {
+                this.syncTimer = setTimeout(() => { this.syncTimer = undefined; this.startBackgroundSync(); }, this.fsyncIntervalMs);
+                this.syncTimer.unref();
+            }
+        });
+    }
+    /** Closes `fd`, or hands it to the in-flight fsync to close when that completes (never close under a running fsync). */
+    retireFd(fd) {
+        if (this.inflight?.fd === fd) {
+            this.inflight.closeAfter = true;
+            return;
+        }
+        try {
+            closeSync(fd);
+        }
+        catch { /* ignore */ }
+    }
+    /** Appends an explicit `discontinuity` record: the caller (or the keeper) knows data before this point may be missing. */
+    markDiscontinuity(reason, fields = {}) {
+        return this.append({ ...fields, k: 'discontinuity', reason }, { sync: true });
+    }
+    /** Synchronously fsyncs everything appended so far (throws if the fsync fails). */
+    sync() {
+        if (this.syncTimer) {
+            clearTimeout(this.syncTimer);
+            this.syncTimer = undefined;
+        }
+        if (this.active && this.appendedBytes > this.syncedBytes) {
+            const covers = this.appendedBytes;
+            this.syncFile(this.active.fd);
+            this.syncCount++;
+            this.syncedBytes = Math.max(this.syncedBytes, covers);
+        }
+    }
+    startSegment(first) {
+        const file = path.join(this.dir, `seg-${first}.log`);
+        const fd = openSync(file, 'a', 0o600);
+        const seg = { first, file, bytes: 0, count: 0, idx: [], indexed: true };
+        this.segments.push(seg);
+        this.active = { seg, fd };
+        fsyncDirectory(this.dir);
+        return this.active;
+    }
+    sealActive() {
+        if (!this.active)
+            return;
+        this.sync();
+        this.retireFd(this.active.fd);
+        this.active = undefined;
+    }
+    // ---- read / subscribe --------------------------------------------------------------------------------------
+    /**
+     * Up to `limit` records with `o >= from`, in order. If `from` was already truncated away the result starts at the first
+     * retained record (the caller can tell from `records[0].o`; use `readFrom` or `subscribe`'s `onTruncated` to be told).
+     */
+    read(from, limit, options = {}) { return this.readFrom(from, limit, options).records; }
+    /** Like `read`, plus `first` (first retained offset) and `truncated` (true when `from < first`: requested records are gone). */
+    readFrom(from, limit, options = {}) {
+        this.assertOpen();
+        const maxBytes = options.maxBytes ?? Number.POSITIVE_INFINITY;
+        let bytes = 0;
+        const first = this.segments[0]?.first ?? this.nextOffset;
+        const truncated = from < first;
+        const out = [];
+        if (!(limit > 0) || this.segments.length === 0)
+            return { records: out, first, truncated };
+        from = Math.max(from, first);
+        if (from >= this.nextOffset)
+            return { records: out, first, truncated };
+        let si = this.segments.length - 1;
+        while (si > 0 && this.segments[si].first > from)
+            si--;
+        let full = false;
+        for (; si < this.segments.length && out.length < limit && !full; si++) {
+            const seg = this.segments[si];
+            if (seg.count === 0)
+                continue;
+            this.ensureIndexed(seg);
+            const rel = Math.max(0, from - seg.first);
+            const slot = Math.floor(rel / INDEX_STRIDE);
+            let skip = rel - slot * INDEX_STRIDE;
+            let expected = seg.first + slot * INDEX_STRIDE;
+            const fd = openSync(seg.file, 'r');
+            try {
+                scanLines(fd, seg.idx[slot], seg.bytes, (line) => {
+                    if (skip > 0) {
+                        skip--;
+                        expected++;
+                        return true;
+                    }
+                    if (out.length > 0 && bytes + line.length + 1 > maxBytes) {
+                        full = true;
+                        return false;
+                    }
+                    const record = parseRecord(line);
+                    if (!record || record.o !== expected)
+                        throw new StreamCorruptError(`Corrupt record at offset ${expected} in ${seg.file}`);
+                    expected++;
+                    out.push(record);
+                    bytes += line.length + 1;
+                    return out.length < limit;
+                });
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        return { records: out, first, truncated };
+    }
+    ensureIndexed(seg) {
+        if (seg.indexed)
+            return;
+        const fd = openSync(seg.file, 'r');
+        try {
+            let n = 0;
+            const idx = [];
+            scanLines(fd, 0, seg.bytes, (_line, pos) => { if (n % INDEX_STRIDE === 0)
+                idx.push(pos); n++; });
+            if (n !== seg.count)
+                throw new StreamCorruptError(`Segment ${seg.file} holds ${n} records, expected ${seg.count}`);
+            seg.idx = idx;
+            seg.indexed = true;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /**
+     * Pushes records with `o >= from` to `on`, in batches, now and whenever more are appended. Returns the unsubscribe.
+     * Delivery is asynchronous (never from inside `append`). A throwing `on` ends that subscription and goes to `onError`.
+     * If `from` is below the first retained record, delivery starts at that record and `onTruncated({from, first})` is
+     * called once before the first batch, so the loss of the committed range is observable.
+     */
+    subscribe(from, on, options = {}) {
+        let next = from;
+        let live = true;
+        let reported = false;
+        const pump = () => {
+            if (!live || this.closed)
+                return;
+            try {
+                for (;;) {
+                    const { records: batch, first, truncated } = this.readFrom(next, SUBSCRIBE_BATCH);
+                    if (truncated && !reported) {
+                        reported = true;
+                        options.onTruncated?.({ from: next, first });
+                    }
+                    if (batch.length === 0)
+                        return;
+                    next = batch[batch.length - 1].o + 1;
+                    on(batch);
+                    if (!live)
+                        return;
+                }
+            }
+            catch (error) {
+                live = false;
+                unwatch();
+                this.onError?.(error);
+            }
+        };
+        const unwatch = this.watch(pump);
+        this.scheduleNotify(pump);
+        return () => { live = false; unwatch(); };
+    }
+    /** Calls `notify` (asynchronously, coalesced) after appends. Returns the unwatch. */
+    watch(notify) {
+        this.watchers.add(notify);
+        return () => { this.watchers.delete(notify); };
+    }
+    /** The adapter the kit server streams from (`keeper.subscribe`, credit counted in records). */
+    asEventSource(options = {}) {
+        return {
+            read: (from, limit, perRead) => {
+                const caps = [options.maxBytes, perRead?.maxBytes].filter((cap) => cap !== undefined);
+                const result = this.readFrom(from, limit, { maxBytes: caps.length > 0 ? Math.min(...caps) : undefined });
+                if (result.truncated)
+                    options.onTruncated?.({ from, first: result.first });
+                return result.records;
+            },
+            watch: (notify) => this.watch(notify),
+        };
+    }
+    scheduleNotify(only) {
+        if (only) {
+            queueMicrotask(() => { if (!this.closed)
+                only(); });
+            return;
+        }
+        if (this.notifyPending || this.watchers.size === 0)
+            return;
+        this.notifyPending = true;
+        queueMicrotask(() => {
+            this.notifyPending = false;
+            if (this.closed)
+                return;
+            for (const watcher of [...this.watchers]) {
+                try {
+                    watcher();
+                }
+                catch (error) {
+                    this.onError?.(error);
+                }
+            }
+        });
+    }
+    // ---- commit / checkpoint -----------------------------------------------------------------------------------
+    /**
+     * Marks records through `through` (inclusive) as committed and deletes the segments that hold nothing else — whole
+     * segments only, files are never rewritten. `tail` is the caller's opaque watermark; it is persisted atomically with
+     * the truncation and stays readable (`state().committedTail`) after the records are gone. Omitting `tail` keeps the
+     * previous one. A `through` at or below the current watermark changes nothing (but a given `tail` is still stored).
+     */
+    commit(through, tail) {
+        this.assertOpen();
+        if (!Number.isSafeInteger(through) || through < -1)
+            throw new RangeError(`Invalid commit offset ${through}`);
+        if (through > this.nextOffset - 1)
+            throw new RangeError(`Commit offset ${through} is beyond the head ${this.nextOffset - 1}`);
+        const advance = through > this.committedOffset;
+        if (!advance && tail === undefined)
+            return;
+        this.sync(); // the watermark must never point at records that are not durable
+        const committed = advance ? through : this.committedOffset;
+        const newTail = tail === undefined ? this.tail : tail;
+        atomicWrite(path.join(this.dir, META_FILE), JSON.stringify({ v: 1, committed, tail: newTail, t: this.now() }));
+        this.committedOffset = committed;
+        this.tail = newTail;
+        if (advance)
+            this.deleteCommittedSegments();
+    }
+    /** Atomically stores a checkpoint slot (tmp + rename, fsynced), keeping the latest two. `blob` is opaque. */
+    writeCheckpoint(offset, blob) {
+        this.assertOpen();
+        if (!Number.isSafeInteger(offset) || offset < -1)
+            throw new RangeError(`Invalid checkpoint offset ${offset}`);
+        const data = typeof blob === 'string' ? Buffer.from(blob, 'utf8') : Buffer.from(blob);
+        this.sync(); // a durable checkpoint must never point beyond records that could still be lost
+        const seq = this.checkpointSeq + 1;
+        const t = this.now();
+        atomicWrite(path.join(this.dir, `checkpoint-${String(seq).padStart(12, '0')}.json`), JSON.stringify({ v: 1, seq, offset, t, blob: data.toString('base64') }));
+        this.checkpointSeq = seq;
+        this.checkpointOffset = offset;
+        const files = this.checkpointFiles();
+        for (const old of files.slice(0, Math.max(0, files.length - KEPT_CHECKPOINTS)))
+            try {
+                unlinkSync(old.file);
+            }
+            catch { /* ignore */ }
+        return { seq, offset, t, blob: data };
+    }
+    /** The newest readable checkpoint (falls back to the previous slot when the newest cannot be parsed). */
+    latestCheckpoint() {
+        const files = this.checkpointFiles();
+        for (let i = files.length - 1; i >= 0; i--) {
+            try {
+                const value = JSON.parse(readFileSync(files[i].file, 'utf8'));
+                if (Number.isSafeInteger(value.seq) && Number.isSafeInteger(value.offset) && typeof value.t === 'number' && typeof value.blob === 'string') {
+                    return { seq: value.seq, offset: value.offset, t: value.t, blob: Buffer.from(value.blob, 'base64') };
+                }
+            }
+            catch { /* try the older slot */ }
+        }
+        return undefined;
+    }
+    checkpointFiles() {
+        return readdirSync(this.dir).map((n) => CHECKPOINT_NAME.exec(n)).filter((m) => !!m)
+            .map((m) => ({ seq: Number(m[1]), file: path.join(this.dir, m[0]) })).sort((a, b) => a.seq - b.seq);
+    }
+    // ---- state / lifecycle -------------------------------------------------------------------------------------
+    state() {
+        return {
+            head: this.nextOffset - 1,
+            committed: this.committedOffset,
+            committedTail: this.tail,
+            overQuota: this.totalBytes > this.softQuota,
+            checkpointOffset: this.checkpointOffset,
+            first: this.segments[0]?.first ?? this.nextOffset,
+            next: this.nextOffset,
+            bytes: this.totalBytes,
+            segments: this.segments.length,
+        };
+    }
+    /** Counters for tests and diagnostics. */
+    stats() {
+        return { fsyncs: this.syncCount, unsyncedBytes: this.appendedBytes - this.syncedBytes, syncErrors: this.syncErrors, lastSyncError: this.lastSyncError };
+    }
+    /** Flushes, closes the files and releases the directory. Idempotent. */
+    close() {
+        if (this.closed)
+            return;
+        try {
+            this.sync();
+        }
+        finally {
+            this.closed = true;
+            this.closeActive();
+            this.watchers.clear();
+            openStreams.delete(this.dir);
+        }
+    }
+    closeActive() {
+        if (this.active) {
+            this.retireFd(this.active.fd);
+            this.active = undefined;
+        }
+    }
+    assertOpen() { if (this.closed)
+        throw new Error('Stream log is closed'); }
+}
+function fstatSizeOf(file) {
+    const fd = openSync(file, 'r');
+    try {
+        return fstatSync(fd).size;
+    }
+    finally {
+        closeSync(fd);
+    }
+}