@minnowdb/core 0.1.0 → 0.2.0

package/dist/storage/opfs/leader.js

@@ -0,0 +1,1104 @@
+import { collectFtsCandidates, } from "../types.js";
+import { RecordCore, validateBeginTransactionInput, validateId, validateTempRunPage, validateTempRunPageIdentity, } from "../toolkit/record-core.js";
+import { encodeSegment, decodeSegment } from "./files.js";
+import { decodeChunk, decodeSyncCheckpoint, encodeChunk, encodeSyncCheckpoint, } from "../toolkit/wire.js";
+import { WalWriter, replayWalFrames } from "../toolkit/wal.js";
+import { ExtentPool } from "../toolkit/extents.js";
+/** Checkpoint when the WAL passes either bound; both trade replay time against pause time. */
+const CHECKPOINT_WAL_BYTES = 4 * 1024 * 1024;
+const CHECKPOINT_ENTRIES = 1024;
+/** Decoded full-text base chunks kept in memory; least recently loaded goes first. */
+const FTS_CHUNK_CACHE_SIZE = 64;
+/**
+ * The leader: the one instance holding the database's write-ahead log handle, and with it
+ * every other handle — checkpoint slots, the tail extent, a small cache of sealed extents.
+ *
+ * Because the handles are held, every operation's storage cost is a synchronous write or read
+ * measured in microseconds, and because leadership is exclusive by the browser's own file
+ * lock, the leader's in-memory `RecordCore` is always provably current — there are no
+ * freshness probes anywhere. An operation is: validate and mutate the core (synchronously),
+ * append one checksummed WAL frame (synchronously), acknowledge. The only awaits sit before
+ * that critical section (extent appends that may seal, temp-file IO), so no observer ever
+ * sees state mid-mutation.
+ *
+ * Checkpointing is also synchronous — dump, write to the older of two fixed slots, flush,
+ * reset the WAL — which is what makes a single WAL file safe: the flush precedes the reset,
+ * and a crash mid-checkpoint corrupts only the slot being written while the other slot plus
+ * the un-reset WAL still reconstruct everything.
+ */
+export class OpfsLeader {
+    #tree;
+    #strict;
+    #core;
+    #blockIndex = new Map();
+    #ftsBases = new Map();
+    #ftsChunkCache = new Map();
+    #extents;
+    #wal;
+    /** The pool exists from the moment recovery succeeds; before that, nothing may touch it. */
+    get #pool() {
+        const pool = this.#extents;
+        if (pool === undefined)
+            throw new Error("The OPFS leader has not recovered yet");
+        return pool;
+    }
+    #walHandle;
+    #slots;
+    /** The slot holding the newest checkpoint; the next checkpoint writes to the other. */
+    #newestSlot = 0;
+    #seq = 0;
+    #entriesSinceCheckpoint = 0;
+    #permissivePhysical = false;
+    #poisoned = false;
+    #closed = false;
+    #chain = Promise.resolve();
+    #checkpointEntries;
+    #lastCheckpointBytes = 0;
+    #checkpointScheduled = false;
+    constructor(tree, strict, walHandle, slots, checkpointEntries) {
+        this.#checkpointEntries = checkpointEntries ?? CHECKPOINT_ENTRIES;
+        this.#tree = tree;
+        this.#strict = strict;
+        this.#walHandle = walHandle;
+        this.#slots = slots;
+        this.#wal = new WalWriter(walHandle, 0);
+        this.#core = new RecordCore({
+            hasBlock: (id) => this.#permissivePhysical || this.#blockIndex.has(id),
+            blockByteLength: (id) => this.#blockIndex.get(id)?.length ?? (this.#permissivePhysical ? 0 : undefined),
+        });
+    }
+    /** Builds a leader from held handles: newest valid checkpoint slot plus the WAL tail. */
+    static async recover(tree, strict, handles, checkpointEntries) {
+        const leader = new OpfsLeader(tree, strict, handles.wal, [handles.slotA, handles.slotB], checkpointEntries);
+        try {
+            await leader.#loadFromDisk();
+        }
+        catch (error) {
+            // A failed recovery must release every handle it acquired, or the browser's file lock
+            // outlives the attempt and no connection can ever lead this database again.
+            leader.crash();
+            throw error;
+        }
+        return leader;
+    }
+    async #loadFromDisk() {
+        const states = this.#slots.map((slot) => {
+            const size = slot.getSize();
+            const bytes = new Uint8Array(size);
+            slot.read(bytes, { at: 0 });
+            return decodeSyncCheckpoint(bytes);
+        });
+        let checkpoint;
+        this.#newestSlot = 0;
+        states.forEach((state, index) => {
+            if (state !== undefined && (checkpoint === undefined || state.lastSeq > checkpoint.lastSeq)) {
+                checkpoint = state;
+                this.#newestSlot = index;
+            }
+        });
+        this.#blockIndex.clear();
+        this.#ftsBases.clear();
+        this.#ftsChunkCache.clear();
+        this.#extents?.close();
+        this.#extents = await ExtentPool.open(this.#tree, checkpoint?.extents);
+        if (checkpoint === undefined) {
+            this.#core.load(EMPTY_CORE_STATE());
+            this.#seq = 0;
+        }
+        else {
+            this.#core.load(checkpoint.core);
+            for (const [id, placement] of checkpoint.blockIndex)
+                this.#blockIndex.set(id, placement);
+            for (const [key, pointer] of checkpoint.ftsBases)
+                this.#ftsBases.set(key, pointer);
+            this.#seq = checkpoint.lastSeq;
+        }
+        const newest = this.#slots[this.#newestSlot];
+        this.#lastCheckpointBytes = newest === undefined ? 0 : newest.getSize();
+        const { payloads, endOffset } = replayWalFrames(this.#walHandle);
+        let applied = 0;
+        let tailExtent = -1;
+        let tailEnd = 0;
+        for (const payload of payloads) {
+            const entry = payload;
+            if (entry.seq <= this.#seq)
+                continue; // Covered by the checkpoint; reset had not run yet.
+            applied += 1;
+            this.#applyReplayed(entry);
+            for (const placement of placementsOf(entry)) {
+                this.#pool.restorePlacement(placement);
+                if (placement.extent > tailExtent ||
+                    (placement.extent === tailExtent && placement.offset + placement.length > tailEnd)) {
+                    tailExtent = placement.extent;
+                    tailEnd = placement.offset + placement.length;
+                }
+            }
+            this.#seq = entry.seq;
+        }
+        if (tailExtent > this.#pool.tailExtentId) {
+            await this.#pool.adoptTail(tailExtent, tailEnd);
+        }
+        this.#wal = new WalWriter(this.#walHandle, endOffset);
+        this.#entriesSinceCheckpoint = applied;
+        this.#poisoned = false;
+        // Extents fully drained before the crash but never deleted: finish the job.
+        for (const id of this.#pool.release([]))
+            await this.#pool.deleteExtent(id);
+    }
+    // ---------------------------------------------------------------------------------------
+    // The logged-operation spine.
+    // ---------------------------------------------------------------------------------------
+    #run(work) {
+        const result = this.#chain.then(async () => {
+            if (this.#closed)
+                throw new Error("This OPFS store connection is closed");
+            if (this.#poisoned)
+                await this.#loadFromDisk();
+            return work();
+        });
+        this.#chain = result.catch(() => undefined);
+        return result;
+    }
+    /**
+     * Reads answer from memory without the queue — but never from a poisoned instance, whose
+     * memory ran ahead of a write the disk refused. The fast path is one boolean check; the
+     * poisoned path rides the queue, which reloads from the held handles first.
+     */
+    async #healthy() {
+        if (!this.#poisoned)
+            return;
+        await this.#run(() => undefined);
+    }
+    /**
+     * The critical section: apply to the core and append the frame in one synchronous run.
+     * A validation throw leaves the core untouched (validate-then-mutate bodies); a WAL write
+     * failure after mutation poisons the leader, which reloads from its own handles before the
+     * next operation, and the original error — quota, most importantly — escapes unwrapped.
+     */
+    #logged(body) {
+        const result = this.#applyBody(body);
+        this.#appendFrame(body);
+        return result;
+    }
+    #appendFrame(body) {
+        try {
+            this.#seq += 1;
+            this.#wal.append({ seq: this.#seq, ...body }, this.#strict);
+            this.#entriesSinceCheckpoint += 1;
+        }
+        catch (error) {
+            this.#poisoned = true;
+            throw error;
+        }
+        // The checkpoint runs as its own queued step: the operation that trips the threshold is
+        // already durable and should not absorb the pause — or a checkpoint failure. A failed
+        // checkpoint (quota, most plausibly) leaves the WAL covering everything and retries on a
+        // later trigger; the operations themselves stay correct throughout.
+        if (this.#checkpointDue() && !this.#checkpointScheduled) {
+            this.#checkpointScheduled = true;
+            void this.#run(() => {
+                this.#checkpointScheduled = false;
+                if (this.#checkpointDue())
+                    this.checkpointNow();
+            }).catch(() => undefined);
+        }
+    }
+    /**
+     * Due when the WAL outgrows the larger of the floor and the previous checkpoint's own size —
+     * so checkpointing amortizes to O(bytes written) instead of re-serializing the whole state
+     * every fixed interval during a bulk load — or when the frame count alone would make a
+     * replay slow.
+     */
+    #checkpointDue() {
+        return (this.#wal.byteLength >= Math.max(CHECKPOINT_WAL_BYTES, this.#lastCheckpointBytes) ||
+            this.#entriesSinceCheckpoint >= this.#checkpointEntries);
+    }
+    #applyBody(body) {
+        switch (body.op) {
+            case "addBlocks": {
+                for (const { id, placement } of body.placements)
+                    this.#blockIndex.set(id, placement);
+                return undefined;
+            }
+            case "removeBlock": {
+                const placement = this.#blockIndex.get(body.id);
+                this.#blockIndex.delete(body.id);
+                if (placement !== undefined)
+                    this.#pool.release([placement]);
+                return undefined;
+            }
+            case "relocatePayloads": {
+                // Validate the complete move before changing an index: a stale relocation must leave
+                // both indexes and live-byte accounting untouched.
+                for (const move of body.blocks) {
+                    if (!samePlacement(this.#blockIndex.get(move.id), move.from)) {
+                        throw new Error(`OPFS block moved before relocation: ${move.id}`);
+                    }
+                }
+                for (const move of body.ftsChunks) {
+                    if (!samePlacement(this.#ftsBases.get(move.key)?.chunks[move.ordinal], move.from)) {
+                        throw new Error(`OPFS full-text chunk moved before relocation: ${move.key}`);
+                    }
+                }
+                for (const move of body.blocks)
+                    this.#blockIndex.set(move.id, move.placement);
+                for (const move of body.ftsChunks) {
+                    const pointer = this.#ftsBases.get(move.key);
+                    if (pointer === undefined)
+                        throw new Error(`OPFS full-text base is missing: ${move.key}`);
+                    pointer.chunks[move.ordinal] = move.placement;
+                    this.#dropFtsChunkCache(move.key);
+                }
+                this.#pool.release([
+                    ...body.blocks.map((move) => move.from),
+                    ...body.ftsChunks.map((move) => move.from),
+                ]);
+                return undefined;
+            }
+            case "addTable":
+                return this.#core.addTable(body.record);
+            case "updateTable":
+                return this.#core.updateTable(body.id, body.expectedRevision, body.update);
+            case "removeTable": {
+                this.#core.removeTable(body.id, body.expectedRevision);
+                const owned = `${body.id}/`;
+                for (const [key, pointer] of [...this.#ftsBases]) {
+                    if (!key.startsWith(owned))
+                        continue;
+                    this.#ftsBases.delete(key);
+                    this.#dropFtsChunkCache(key);
+                    this.#pool.release(pointer.chunks);
+                }
+                return undefined;
+            }
+            case "addSegment":
+                return this.#core.addSegment(body.record);
+            case "removeSegment":
+                return this.#core.removeSegment(body.id);
+            case "reserveRowIds":
+                return this.#core.reserveRowIds(body.tableId, body.count);
+            case "reserveAutoIncrement":
+                return this.#core.reserveAutoIncrement(body.tableId, body.columnId, body.count, body.atLeast);
+            case "publishManifest":
+                return this.#core.publishManifest(body.input);
+            case "beginTransaction":
+                return this.#core.beginTransaction(body.input);
+            case "createTransaction":
+                return this.#core.createTransaction(body.record);
+            case "updateTransaction":
+                return this.#core.updateTransaction(body.id, body.expectedRevision, body.update);
+            case "stageTransactionArtifacts": {
+                for (const { id, placement } of body.blocks)
+                    this.#blockIndex.set(id, placement);
+                return this.#core.stageTransactionArtifacts({
+                    transactionId: body.transactionId,
+                    expectedRevision: body.expectedRevision,
+                    blocks: body.blocks.map(({ id }) => ({ id, bytes: EMPTY_BYTES })),
+                    segments: body.segments,
+                    updatedAt: body.updatedAt,
+                }, { blocksPrevalidated: true });
+            }
+            case "commitTransaction":
+                return this.#core.commitTransaction(body.input);
+            case "writeTransaction": {
+                // The core counts this step's own blocks as present, so the index is set only once the
+                // whole write has been accepted — a refusal leaves no stray placements behind.
+                const summary = this.#core.writeTransaction({ ...body.input, blocks: body.blocks.map(({ id }) => ({ id, bytes: EMPTY_BYTES })) }, { blocksPrevalidated: true });
+                for (const { id, placement } of body.blocks)
+                    this.#blockIndex.set(id, placement);
+                return summary;
+            }
+            case "createLease":
+                return this.#core.createLease(body.record);
+            case "renewLease":
+                return this.#core.renewLease(body.id, body.expectedRevision, body.expiresAt);
+            case "moveLease":
+                return this.#core.moveLease(body.id, body.expectedRevision, body.manifestVersion, body.expiresAt);
+            case "removeLeaseIfExpired":
+                return this.#core.removeLeaseIfExpired(body.id, body.expectedRevision, body.expiresAtCutoff);
+            case "removeLease":
+                return this.#core.removeLease(body.id);
+            case "createCompactionJob":
+                return this.#core.createCompactionJob(body.record);
+            case "updateCompactionJob":
+                return this.#core.updateCompactionJob(body.id, body.expectedRevision, body.update);
+            case "cancelCompactionJob":
+                return this.#core.cancelCompactionJob(body.id, body.expectedRevision, body.cancelledAt);
+            case "removeCompactionJob":
+                return this.#core.removeCompactionJob(body.id);
+            case "createGarbageCollectionJob":
+                return this.#core.createGarbageCollectionJob(body.input);
+            case "garbageCollectionStep": {
+                this.#core.applyGarbageCollectionEffect(body.effect);
+                this.#releaseReclaimedBlocks(body.effect.reclaimedBlockIds);
+                return undefined;
+            }
+            case "removeGarbageCollectionJob":
+                return this.#core.removeGarbageCollectionJob(body.id);
+            case "removePrunedManifestRecords":
+                return this.#core.removePrunedManifestRecords().length;
+            case "createTempOwner":
+                return this.#core.createTempOwner(body.record);
+            case "renewTempOwner":
+                return this.#core.renewTempOwner(body.ownerId, body.expectedRevision, body.expiresAt);
+            case "removeTempOwnerIfExpired":
+                return this.#core.removeTempOwnerIfExpired(body.ownerId, body.expiresAtCutoff);
+            case "removeTempOwner":
+                return this.#core.removeTempOwner(body.ownerId);
+            case "writeFtsBase": {
+                const key = `${body.tableId}/${body.columnId}`;
+                const previous = this.#ftsBases.get(key);
+                if (previous !== undefined) {
+                    this.#pool.release(previous.chunks);
+                    this.#dropFtsChunkCache(key);
+                }
+                this.#ftsBases.set(key, structuredClone(body.pointer));
+                this.#core.pruneFtsDeltas(body.tableId, body.columnId, body.pointer.coversVersion);
+                return undefined;
+            }
+            case "importSnapshot": {
+                if (this.#core.getCurrentManifestVersion() !== null || this.#core.listTables().length > 0) {
+                    throw new Error("This store already holds a database");
+                }
+                for (const { id, placement } of body.blockPlacements)
+                    this.#blockIndex.set(id, placement);
+                this.#core.loadSnapshotRecords({ ...body.records, blocks: undefined }, body.blockPlacements.map(({ id }) => id));
+                return undefined;
+            }
+        }
+    }
+    #applyReplayed(entry) {
+        this.#permissivePhysical = true;
+        try {
+            const { seq: _seq, ...body } = entry;
+            void _seq;
+            this.#applyBody(body);
+        }
+        finally {
+            this.#permissivePhysical = false;
+        }
+    }
+    #releaseReclaimedBlocks(ids) {
+        const placements = [];
+        for (const id of ids) {
+            const placement = this.#blockIndex.get(id);
+            if (placement !== undefined)
+                placements.push(placement);
+            this.#blockIndex.delete(id);
+        }
+        this.#pool.release(placements);
+    }
+    /** Fully synchronous: dump, write the older slot, flush it, then and only then reset. */
+    checkpointNow() {
+        const state = {
+            lastSeq: this.#seq,
+            core: this.#core.dump(),
+            blockIndex: [...this.#blockIndex.entries()],
+            ftsBases: [...this.#ftsBases.entries()],
+            extents: this.#pool.meta(),
+        };
+        const bytes = encodeSyncCheckpoint(state);
+        const slotIndex = this.#newestSlot === 0 ? 1 : 0;
+        const slot = this.#slots[slotIndex];
+        slot.truncate(0);
+        slot.write(bytes, { at: 0 });
+        slot.flush();
+        this.#newestSlot = slotIndex;
+        this.#wal.reset();
+        this.#entriesSinceCheckpoint = 0;
+        this.#lastCheckpointBytes = bytes.byteLength;
+    }
+    async #deleteDrainedExtents() {
+        for (const id of this.#pool.release([])) {
+            await this.#pool.deleteExtent(id);
+        }
+    }
+    /** Re-packs every sealed extent below 50% occupancy; each source file is at most 8 MiB. */
+    async #compactFragmentedExtents() {
+        for (;;) {
+            const extent = await this.#pool.fragmentedExtentId();
+            if (extent === undefined)
+                return;
+            const blockSources = [...this.#blockIndex.entries()]
+                .filter(([, placement]) => placement.extent === extent)
+                .map(([id, from]) => ({ id, from }));
+            const ftsSources = [...this.#ftsBases.entries()].flatMap(([key, pointer]) => pointer.chunks.flatMap((from, ordinal) => from.extent === extent ? [{ key, ordinal, from }] : []));
+            if (blockSources.length === 0 && ftsSources.length === 0) {
+                throw new Error(`OPFS extent ${String(extent)} has live bytes but no indexed payload`);
+            }
+            const blocks = [];
+            const ftsChunks = [];
+            const appended = [];
+            try {
+                for (const source of blockSources) {
+                    const placement = await this.#pool.append(await this.#pool.read(source.from), this.#strict);
+                    appended.push(placement);
+                    blocks.push({ ...source, placement });
+                }
+                for (const source of ftsSources) {
+                    const placement = await this.#pool.append(await this.#pool.read(source.from), this.#strict);
+                    appended.push(placement);
+                    ftsChunks.push({ ...source, placement });
+                }
+                this.#logged({ op: "relocatePayloads", blocks, ftsChunks });
+            }
+            catch (error) {
+                this.#pool.release(appended);
+                throw error;
+            }
+            await this.#deleteDrainedExtents();
+        }
+    }
+    // ---------------------------------------------------------------------------------------
+    // Blocks.
+    // ---------------------------------------------------------------------------------------
+    async addBlock(id, bytes) {
+        return this.addBlocks([{ id, bytes }]);
+    }
+    async addBlocks(blocks) {
+        return this.#run(async () => {
+            const ids = new Set();
+            for (const block of blocks) {
+                validateId(block.id);
+                if (ids.has(block.id) || this.#blockIndex.has(block.id)) {
+                    throw new Error(`Block already exists: ${block.id}`);
+                }
+                ids.add(block.id);
+            }
+            const placements = [];
+            try {
+                for (const block of blocks) {
+                    placements.push({
+                        id: block.id,
+                        placement: await this.#pool.append(block.bytes, this.#strict),
+                    });
+                }
+            }
+            catch (error) {
+                // Nothing was recorded; the written bytes are dead space. Undo the accounting.
+                this.#pool.release(placements.map(({ placement }) => placement));
+                throw error;
+            }
+            this.#logged({ op: "addBlocks", placements });
+        });
+    }
+    async getBlock(id) {
+        await this.#healthy();
+        const placement = this.#blockIndex.get(id);
+        if (placement === undefined)
+            return undefined;
+        return this.#pool.read(placement);
+    }
+    async getBlocks(ids) {
+        return Promise.all(ids.map((id) => this.getBlock(id)));
+    }
+    async removeBlock(id) {
+        await this.#run(async () => {
+            if (!this.#blockIndex.has(id))
+                return;
+            this.#logged({ op: "removeBlock", id });
+            await this.#deleteDrainedExtents();
+            await this.#compactFragmentedExtents();
+        });
+    }
+    async listBlockIds() {
+        await this.#healthy();
+        return [...this.#blockIndex.keys()].sort();
+    }
+    // ---------------------------------------------------------------------------------------
+    // Temp spill pages: instance-local files, never logged, never proxied.
+    // ---------------------------------------------------------------------------------------
+    async putTempRunPage(page) {
+        validateTempRunPage(page);
+        await this.#tree.writeFile(tempPagePath(page.ownerId, page.runId, page.pageIndex), page.bytes);
+    }
+    async getTempRunPage(ownerId, runId, pageIndex) {
+        validateTempRunPageIdentity(ownerId, runId, pageIndex);
+        return this.#tree.readFile(tempPagePath(ownerId, runId, pageIndex));
+    }
+    async removeTempRun(ownerId, runId) {
+        validateTempRunPageIdentity(ownerId, runId, 0);
+        await this.#tree.deleteTree(["temp", encodeSegment(ownerId), encodeSegment(runId)]);
+    }
+    async removeTempOwner(ownerId) {
+        validateId(ownerId);
+        await this.#run(() => this.#logged({ op: "removeTempOwner", ownerId }));
+        await this.#tree.deleteTree(["temp", encodeSegment(ownerId)]);
+    }
+    async createTempOwner(record) {
+        await this.#run(() => this.#logged({ op: "createTempOwner", record }));
+    }
+    async getTempOwner(ownerId) {
+        await this.#healthy();
+        return this.#core.getTempOwner(ownerId);
+    }
+    async renewTempOwner(ownerId, expectedRevision, expiresAt) {
+        return this.#run(() => this.#logged({
+            op: "renewTempOwner",
+            ownerId,
+            expectedRevision,
+            expiresAt,
+        }));
+    }
+    async removeTempOwnerIfExpired(ownerId, expiresAtCutoff) {
+        const removed = await this.#run(() => this.#logged({ op: "removeTempOwnerIfExpired", ownerId, expiresAtCutoff }));
+        if (removed)
+            await this.#tree.deleteTree(["temp", encodeSegment(ownerId)]);
+        return removed;
+    }
+    async listTempOwnerIdsPage(afterOwnerId, limit) {
+        await this.#healthy();
+        const names = await this.#tree.listNames(["temp"]);
+        return this.#core.listTempOwnerIdsPage(afterOwnerId, limit, names.map(decodeSegment));
+    }
+    // ---------------------------------------------------------------------------------------
+    // Record reads: the leader's memory is always current; no probes, no refreshes.
+    // ---------------------------------------------------------------------------------------
+    async getTable(id) {
+        await this.#healthy();
+        return this.#core.getTable(id);
+    }
+    async getTableByName(name) {
+        await this.#healthy();
+        return this.#core.getTableByName(name);
+    }
+    async listTables() {
+        await this.#healthy();
+        return this.#core.listTables();
+    }
+    async getSegment(id) {
+        await this.#healthy();
+        return this.#core.getSegment(id);
+    }
+    async listSegments(tableId) {
+        await this.#healthy();
+        return this.#core.listSegments(tableId);
+    }
+    async getExistingUniqueKeys(tableId, keyTokens) {
+        await this.#healthy();
+        return this.#core.getExistingUniqueKeys(tableId, keyTokens);
+    }
+    async getCurrentManifestVersion() {
+        await this.#healthy();
+        return this.#core.getCurrentManifestVersion();
+    }
+    async getCatalogProbe() {
+        await this.#healthy();
+        return this.#core.getCatalogProbe();
+    }
+    async getQueryCatalogState(tableNames) {
+        await this.#healthy();
+        return this.#core.getQueryCatalogState(tableNames);
+    }
+    async getCurrentManifest() {
+        await this.#healthy();
+        return this.#core.getCurrentManifest();
+    }
+    async getManifest(version) {
+        await this.#healthy();
+        return this.#core.getManifest(version);
+    }
+    async listManifests() {
+        await this.#healthy();
+        return this.#core.listManifests();
+    }
+    async listManifestPage(afterVersion, limit) {
+        await this.#healthy();
+        return this.#core.listManifestPage(afterVersion, limit);
+    }
+    async getTransaction(id) {
+        await this.#healthy();
+        return this.#core.getTransaction(id);
+    }
+    async getTransactions(ids) {
+        await this.#healthy();
+        return this.#core.getTransactions(ids);
+    }
+    async listTransactions() {
+        await this.#healthy();
+        return this.#core.listTransactions();
+    }
+    async listTransactionPage(afterId, limit) {
+        await this.#healthy();
+        return this.#core.listTransactionPage(afterId, limit);
+    }
+    async getLease(id) {
+        await this.#healthy();
+        return this.#core.getLease(id);
+    }
+    async listLeases() {
+        await this.#healthy();
+        return this.#core.listLeases();
+    }
+    async getCompactionJob(id) {
+        await this.#healthy();
+        return this.#core.getCompactionJob(id);
+    }
+    async listCompactionJobs(tableId) {
+        await this.#healthy();
+        return this.#core.listCompactionJobs(tableId);
+    }
+    async listCompactionJobPage(afterId, limit) {
+        await this.#healthy();
+        return this.#core.listCompactionJobPage(afterId, limit);
+    }
+    async getGarbageCollectionJob(id) {
+        await this.#healthy();
+        return this.#core.getGarbageCollectionJob(id);
+    }
+    async listGarbageCollectionJobs() {
+        await this.#healthy();
+        return this.#core.listGarbageCollectionJobs();
+    }
+    // ---------------------------------------------------------------------------------------
+    // Logged record mutations.
+    // ---------------------------------------------------------------------------------------
+    async addTable(record) {
+        await this.#run(() => this.#logged({ op: "addTable", record }));
+    }
+    async updateTable(id, expectedRevision, update) {
+        return this.#run(() => this.#logged({ op: "updateTable", id, expectedRevision, update }));
+    }
+    async removeTable(id, expectedRevision) {
+        await this.#run(async () => {
+            this.#logged({ op: "removeTable", id, expectedRevision });
+            await this.#deleteDrainedExtents();
+            await this.#compactFragmentedExtents();
+        });
+    }
+    async addSegment(record) {
+        await this.#run(() => this.#logged({ op: "addSegment", record }));
+    }
+    async removeSegment(id) {
+        await this.#run(() => this.#logged({ op: "removeSegment", id }));
+    }
+    async reserveRowIds(tableId, count) {
+        return this.#run(() => this.#logged({ op: "reserveRowIds", tableId, count }));
+    }
+    async reserveAutoIncrement(tableId, columnId, count, atLeast) {
+        return this.#run(() => this.#logged({
+            op: "reserveAutoIncrement",
+            tableId,
+            columnId,
+            count,
+            ...(atLeast === undefined ? {} : { atLeast }),
+        }));
+    }
+    async publishManifest(input) {
+        // Resolve the optional timestamp before logging: replays must be deterministic.
+        const resolved = {
+            ...input,
+            createdAt: input.createdAt ?? new Date().toISOString(),
+        };
+        return this.#run(() => this.#logged({ op: "publishManifest", input: resolved }));
+    }
+    async beginTransaction(input) {
+        validateBeginTransactionInput(input);
+        return this.#run(() => this.#logged({ op: "beginTransaction", input }));
+    }
+    async createTransaction(record) {
+        await this.#run(() => this.#logged({ op: "createTransaction", record }));
+    }
+    async updateTransaction(id, expectedRevision, update) {
+        return this.#run(() => this.#logged({
+            op: "updateTransaction",
+            id,
+            expectedRevision,
+            update,
+        }));
+    }
+    async stageTransactionArtifacts(input) {
+        return this.#run(async () => {
+            const ids = new Set();
+            for (const block of input.blocks) {
+                validateId(block.id);
+                if (ids.has(block.id) || this.#blockIndex.has(block.id)) {
+                    throw new Error(`Block already exists: ${block.id}`);
+                }
+                ids.add(block.id);
+            }
+            const blocks = [];
+            try {
+                for (const block of input.blocks) {
+                    blocks.push({
+                        id: block.id,
+                        placement: await this.#pool.append(block.bytes, this.#strict),
+                    });
+                }
+                return this.#logged({
+                    op: "stageTransactionArtifacts",
+                    transactionId: input.transactionId,
+                    expectedRevision: input.expectedRevision,
+                    blocks,
+                    segments: [...input.segments],
+                    updatedAt: input.updatedAt,
+                });
+            }
+            catch (error) {
+                this.#pool.release(blocks.map(({ placement }) => placement));
+                throw error;
+            }
+        });
+    }
+    async commitTransaction(input) {
+        return this.#run(() => this.#logged({ op: "commitTransaction", input }));
+    }
+    async writeTransaction(input) {
+        return this.#run(async () => {
+            const ids = new Set();
+            for (const block of input.blocks) {
+                validateId(block.id);
+                if (ids.has(block.id) || this.#blockIndex.has(block.id)) {
+                    throw new Error(`Block already exists: ${block.id}`);
+                }
+                ids.add(block.id);
+            }
+            const { blocks: bytes, ...rest } = input;
+            const blocks = [];
+            try {
+                for (const block of bytes) {
+                    blocks.push({
+                        id: block.id,
+                        placement: await this.#pool.append(block.bytes, this.#strict),
+                    });
+                }
+                return this.#logged({
+                    op: "writeTransaction",
+                    input: { ...rest, segments: [...input.segments] },
+                    blocks,
+                });
+            }
+            catch (error) {
+                // Nothing was recorded; the written bytes are dead space. Undo the accounting.
+                this.#pool.release(blocks.map(({ placement }) => placement));
+                throw error;
+            }
+        });
+    }
+    async createLease(record) {
+        await this.#run(() => this.#logged({ op: "createLease", record }));
+    }
+    async renewLease(id, expectedRevision, expiresAt) {
+        return this.#run(() => this.#logged({ op: "renewLease", id, expectedRevision, expiresAt }));
+    }
+    async moveLease(id, expectedRevision, manifestVersion, expiresAt) {
+        return this.#run(() => this.#logged({
+            op: "moveLease",
+            id,
+            expectedRevision,
+            manifestVersion,
+            expiresAt,
+        }));
+    }
+    async removeLeaseIfExpired(id, expectedRevision, expiresAtCutoff) {
+        return this.#run(() => this.#logged({
+            op: "removeLeaseIfExpired",
+            id,
+            expectedRevision,
+            expiresAtCutoff,
+        }));
+    }
+    async removeLease(id) {
+        await this.#run(() => this.#logged({ op: "removeLease", id }));
+    }
+    async createCompactionJob(record) {
+        await this.#run(() => this.#logged({ op: "createCompactionJob", record }));
+    }
+    async updateCompactionJob(id, expectedRevision, update) {
+        return this.#run(() => this.#logged({
+            op: "updateCompactionJob",
+            id,
+            expectedRevision,
+            update,
+        }));
+    }
+    async cancelCompactionJob(id, expectedRevision, cancelledAt) {
+        return this.#run(() => this.#logged({
+            op: "cancelCompactionJob",
+            id,
+            expectedRevision,
+            cancelledAt,
+        }));
+    }
+    async removeCompactionJob(id) {
+        await this.#run(() => this.#logged({ op: "removeCompactionJob", id }));
+    }
+    async createGarbageCollectionJob(input) {
+        return this.#run(() => this.#logged({ op: "createGarbageCollectionJob", input }));
+    }
+    async runGarbageCollectionStep(input) {
+        return this.#run(async () => {
+            // Computed against provably-current state, logged as the resolved effect so replay
+            // needs no knowledge of physical placement.
+            const step = this.#core.runGarbageCollectionStep(input);
+            this.#releaseReclaimedBlocks(step.reclaimedBlockIds);
+            this.#appendFrame({
+                op: "garbageCollectionStep",
+                effect: {
+                    job: step.job,
+                    prunedManifestVersions: [...step.prunedManifestVersions],
+                    reclaimedSegmentIds: [...step.reclaimedSegmentIds],
+                    reclaimedBlockIds: [...step.reclaimedBlockIds],
+                    reclaimedTransactionIds: [...step.reclaimedTransactionIds],
+                    updatedAt: input.updatedAt,
+                },
+            });
+            await this.#deleteDrainedExtents();
+            if (step.job.state === "completed")
+                await this.#compactFragmentedExtents();
+            return step;
+        });
+    }
+    async removeGarbageCollectionJob(id) {
+        await this.#run(() => this.#logged({ op: "removeGarbageCollectionJob", id }));
+    }
+    async removePrunedManifestRecords() {
+        return this.#run(() => this.#logged({ op: "removePrunedManifestRecords" }));
+    }
+    // ---------------------------------------------------------------------------------------
+    // Full-text bases: immutable chunks in extents plus a logged pointer.
+    // ---------------------------------------------------------------------------------------
+    async writeFtsBase(tableId, columnId, input) {
+        await this.#run(async () => {
+            const chunks = [];
+            try {
+                for (const chunk of input.chunks) {
+                    chunks.push(await this.#pool.append(encodeFtsChunk(chunk), this.#strict));
+                }
+            }
+            catch (error) {
+                this.#pool.release(chunks);
+                throw error;
+            }
+            const pointer = {
+                coversVersion: input.coversVersion,
+                totalTokens: input.totalTokens,
+                chunks,
+                chunkBounds: input.chunks.map((chunk) => ({
+                    first: chunk[0]?.term ?? "",
+                    last: chunk[chunk.length - 1]?.term ?? "",
+                })),
+            };
+            this.#logged({ op: "writeFtsBase", tableId, columnId, pointer });
+            await this.#deleteDrainedExtents();
+            await this.#compactFragmentedExtents();
+        });
+    }
+    async readFtsCandidates(tableId, columnId, terms, upToVersion) {
+        await this.#healthy();
+        const key = `${tableId}/${columnId}`;
+        const pointer = this.#ftsBases.get(key);
+        const coversVersion = pointer?.coversVersion ?? -1;
+        const deltas = this.#core.readFtsDeltas(tableId, columnId, coversVersion, upToVersion);
+        const baseChunks = pointer === undefined
+            ? []
+            : await Promise.all(selectFtsChunks(pointer.chunkBounds, terms).map((ordinal) => this.#loadFtsChunk(key, pointer, ordinal)));
+        return {
+            ...collectFtsCandidates([...baseChunks, ...deltas.chunkLists], terms),
+            deltaChunkCount: deltas.deltaChunkCount,
+            totalTokens: (pointer?.totalTokens ?? 0) + deltas.deltaTokens,
+            coversVersion,
+        };
+    }
+    async #loadFtsChunk(key, pointer, ordinal) {
+        const placement = pointer.chunks[ordinal];
+        if (placement === undefined)
+            return [];
+        const cacheKey = `${key}/${String(placement.extent)}/${String(placement.offset)}`;
+        const cached = this.#ftsChunkCache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const chunk = decodeFtsChunk(await this.#pool.read(placement));
+        this.#ftsChunkCache.set(cacheKey, chunk);
+        if (this.#ftsChunkCache.size > FTS_CHUNK_CACHE_SIZE) {
+            const [oldest] = this.#ftsChunkCache.keys();
+            if (oldest !== undefined)
+                this.#ftsChunkCache.delete(oldest);
+        }
+        return chunk;
+    }
+    #dropFtsChunkCache(keyPrefix) {
+        for (const key of [...this.#ftsChunkCache.keys()]) {
+            if (key.startsWith(`${keyPrefix}/`))
+                this.#ftsChunkCache.delete(key);
+        }
+    }
+    // ---------------------------------------------------------------------------------------
+    // Snapshots, sizing, lifecycle.
+    // ---------------------------------------------------------------------------------------
+    /**
+     * Consistent by construction: the export runs as one queue operation, so no commit or
+     * garbage collection interleaves with it. Full-text bases export as rebuilds.
+     */
+    async exportSnapshot() {
+        return this.#run(async () => {
+            const { records, blockIds } = this.#core.exportSnapshotRecords();
+            const blocks = [];
+            for (const id of blockIds) {
+                const placement = this.#blockIndex.get(id);
+                if (placement === undefined)
+                    throw new Error(`Manifest references missing block: ${id}`);
+                blocks.push({ id, bytes: await this.#pool.read(placement) });
+            }
+            return { ...records, blocks };
+        });
+    }
+    async importSnapshot(snapshot, options = {}) {
+        const totalBytes = snapshot.blocks.reduce((total, block) => total + block.bytes.byteLength, 0);
+        options.onProgress?.({ phase: "blocks", writtenBytes: 0, totalBytes });
+        await this.#run(async () => {
+            if (this.#core.getCurrentManifestVersion() !== null || this.#core.listTables().length > 0) {
+                throw new Error("This store already holds a database");
+            }
+            let writtenBytes = 0;
+            const blockPlacements = [];
+            try {
+                for (const block of snapshot.blocks) {
+                    blockPlacements.push({
+                        id: block.id,
+                        placement: await this.#pool.append(block.bytes, this.#strict),
+                    });
+                    writtenBytes += block.bytes.byteLength;
+                    options.onProgress?.({ phase: "blocks", writtenBytes, totalBytes });
+                }
+            }
+            catch (error) {
+                this.#pool.release(blockPlacements.map(({ placement }) => placement));
+                throw error;
+            }
+            this.#logged({
+                op: "importSnapshot",
+                // Full-text bases restore as rebuilds; the index is an accelerator, not truth.
+                records: {
+                    version: snapshot.version,
+                    createdAt: snapshot.createdAt,
+                    tables: snapshot.tables.map((table) => ({
+                        ...structuredClone(table),
+                        fts: [],
+                        record: invalidateFtsColumns(structuredClone(table.record)),
+                    })),
+                    segments: structuredClone(snapshot.segments),
+                    transactions: structuredClone(snapshot.transactions),
+                },
+                blockPlacements,
+            });
+        });
+        options.onProgress?.({ phase: "done", writtenBytes: totalBytes, totalBytes });
+    }
+    /** Live payload bytes plus the control files — what this database logically occupies. */
+    async getLogicalStorageBytes() {
+        let total = this.#wal.byteLength;
+        const slot = this.#slots[this.#newestSlot];
+        if (slot !== undefined)
+            total += slot.getSize();
+        for (const [, bytes] of this.#pool.meta().liveBytes)
+            total += bytes;
+        for (const { size } of await this.#tree.walkFiles(["temp"]))
+            total += size;
+        return total;
+    }
+    /** Graceful: flush, checkpoint (so the next leader's takeover is instant), release. */
+    async shutdown() {
+        await this.#run(() => {
+            this.checkpointNow();
+            this.#closed = true;
+        }).catch(() => {
+            // Shutting down a poisoned leader still releases its handles below.
+            this.#closed = true;
+        });
+        this.#walHandle.close();
+        for (const slot of this.#slots)
+            slot.close();
+        this.#extents?.close();
+    }
+    /** Test-only: what tab death does — locks release, nothing is flushed or checkpointed. */
+    crash() {
+        this.#closed = true;
+        this.#walHandle.close();
+        for (const slot of this.#slots)
+            slot.close();
+        this.#extents?.close();
+    }
+}
+const EMPTY_BYTES = new Uint8Array(0);
+function EMPTY_CORE_STATE() {
+    return {
+        currentVersion: null,
+        catalogEpoch: 0,
+        manifests: [],
+        transactions: [],
+        tables: [],
+        segments: [],
+        leases: [],
+        compactionJobs: [],
+        garbageCollectionJobs: [],
+        nextRowIds: [],
+        nextAutoIncrement: [],
+        ftsBases: [],
+        ftsDeltas: [],
+        uniqueKeys: [],
+        tempOwners: [],
+    };
+}
+function tempPagePath(ownerId, runId, pageIndex) {
+    return ["temp", encodeSegment(ownerId), encodeSegment(runId), String(pageIndex)];
+}
+function placementsOf(entry) {
+    switch (entry.op) {
+        case "addBlocks":
+            return entry.placements.map(({ placement }) => placement);
+        case "stageTransactionArtifacts":
+        case "writeTransaction":
+            return entry.blocks.map(({ placement }) => placement);
+        case "writeFtsBase":
+            return entry.pointer.chunks;
+        case "importSnapshot":
+            return entry.blockPlacements.map(({ placement }) => placement);
+        case "relocatePayloads":
+            return [
+                ...entry.blocks.map(({ placement }) => placement),
+                ...entry.ftsChunks.map(({ placement }) => placement),
+            ];
+        default:
+            return [];
+    }
+}
+function samePlacement(left, right) {
+    return (left?.extent === right.extent && left.offset === right.offset && left.length === right.length);
+}
+function encodeFtsChunk(chunk) {
+    return encodeChunk(chunk);
+}
+function decodeFtsChunk(bytes) {
+    const chunk = decodeChunk(bytes);
+    if (chunk === undefined)
+        throw new Error("Full-text base chunk is unreadable");
+    return chunk;
+}
+/** The ordinals of base chunks whose term range can contain any of the query's terms. */
+function selectFtsChunks(chunkBounds, terms) {
+    const ordinals = [];
+    for (const [ordinal, bounds] of chunkBounds.entries()) {
+        const needed = terms.some(({ term, prefix }) => {
+            if (bounds.last < term)
+                return false;
+            if (prefix) {
+                return bounds.first <= `${term}￿` || bounds.first.startsWith(term);
+            }
+            return bounds.first <= term;
+        });
+        if (needed)
+            ordinals.push(ordinal);
+    }
+    return ordinals;
+}
+function invalidateFtsColumns(record) {
+    if (record.ftsColumns === undefined)
+        return record;
+    const ftsColumns = Object.fromEntries(Object.entries(record.ftsColumns).map(([columnId, state]) => [
+        columnId,
+        { ...state, state: "invalid" },
+    ]));
+    return { ...record, ftsColumns };
+}
+//# sourceMappingURL=leader.js.map