@minnowdb/core 0.7.0 → 0.7.1

package/dist/storage/toolkit/extents.js

@@ -1,538 +1,462 @@
 import { readFully, writeFully } from "./sync-file.js";
 import { crc32 } from "../../block-format/index.js";
-/** Opaque O(1) rollback point for bytes not yet published by a WAL frame. */
-export class ExtentBatchMark {
-    tailExtentId;
-    nextExtentId;
-    tailOffset;
-    /** @internal Original counters are captured lazily only for extents the batch touches. */
-    _liveBytesBefore = new Map();
-    constructor(tailExtentId, nextExtentId, tailOffset) {
-        this.tailExtentId = tailExtentId;
-        this.nextExtentId = nextExtentId;
-        this.tailOffset = tailOffset;
-    }
+class ExtentBatchMark {
+  tailExtentId;
+  nextExtentId;
+  tailOffset;
+  _liveBytesBefore = /* @__PURE__ */ new Map();
+  constructor(tailExtentId, nextExtentId, tailOffset) {
+    this.tailExtentId = tailExtentId;
+    this.nextExtentId = nextExtentId;
+    this.tailOffset = tailOffset;
+  }
 }
 const SEAL_BYTES = 8 * 1024 * 1024;
 const READ_HANDLE_CACHE = 12;
-export class ExtentPool {
-    #tree;
-    #checksum;
-    #tailId;
-    #nextId;
-    #tailOffset;
-    #tailHandle;
-    #tailDirty = false;
-    #liveBytes = new Map();
-    /** Sealed-extent read handles, LRU by insertion order. The tail is never in here. */
-    #readHandles = new Map();
-    #openingReadHandles = new Map();
-    #deletingExtents = new Set();
-    #activeBatch;
-    #closed = false;
-    constructor(tree, meta, tailHandle, checksum) {
-        this.#tree = tree;
-        this.#checksum = checksum;
-        this.#tailId = meta.tailId;
-        this.#nextId = meta.nextId;
-        this.#tailOffset = meta.tailOffset;
-        this.#tailHandle = tailHandle;
-    }
-    /** Opens (or creates) the tail extent. `meta` comes from the checkpoint, if any. */
-    static async open(tree, meta, options = {}) {
-        if (meta !== undefined)
-            assertValidExtentMeta(meta);
-        const tailId = meta?.tailExtentId ?? 0;
-        const nextId = meta?.nextExtentId ?? 1;
-        const tailHandle = await tree.openHandle(extentPath(tailId), { create: true });
-        const pool = new ExtentPool(tree, { tailId, nextId, tailOffset: meta?.tailOffset ?? 0 }, tailHandle, options._checksumForTests ?? crc32);
-        for (const [id, bytes] of meta?.liveBytes ?? [])
-            pool.#liveBytes.set(id, bytes);
-        if (tailHandle.getSize() < pool.#tailOffset) {
-            pool.close();
-            throw new Error(`OPFS tail extent ${String(tailId)} is shorter than its checkpointed offset: ` +
-                `${String(tailHandle.getSize())} < ${String(pool.#tailOffset)}`);
-        }
-        return pool;
-    }
-    /** Captures the exact append/accounting state before an unpublished multi-payload batch. */
-    markBatch() {
-        if (this.#activeBatch !== undefined)
-            throw new Error("An extent append batch is already active");
-        const mark = new ExtentBatchMark(this.#tailId, this.#nextId, this.#tailOffset);
-        this.#activeBatch = mark;
-        return mark;
-    }
-    /** Publishes a successful batch; constant-time and allocation-free. */
-    commitBatch(mark) {
-        if (this.#activeBatch !== mark)
-            throw new Error("Extent batch mark is not active");
-        this.#activeBatch = undefined;
-    }
-    /**
-     * Rolls back every append and accounting mutation since `mark`. This is deliberately an
-     * async slow path; successful appends retain the allocation-free hot path.
-     */
-    async rollbackBatch(mark) {
-        if (this.#activeBatch !== mark)
-            throw new Error("Extent batch mark is not active");
-        if (mark.nextExtentId > this.#nextId) {
-            throw new Error("Cannot roll an extent pool forward to a future batch mark");
-        }
-        this.#tailHandle.close();
-        // Every id allocated after the mark is unpublished by definition. Delete it before
-        // restoring the former tail so repeated refused batches cannot accumulate sealed files.
-        for (let id = mark.nextExtentId; id < this.#nextId; id += 1) {
-            await this.#closeCachedReadHandle(id);
-            await this.#tree.deleteFile(extentPath(id));
-        }
-        await this.#closeCachedReadHandle(mark.tailExtentId);
-        this.#tailHandle = await this.#tree.openHandle(extentPath(mark.tailExtentId), { create: true });
-        this.#tailHandle.truncate(mark.tailOffset);
-        this.#tailId = mark.tailExtentId;
-        this.#nextId = mark.nextExtentId;
-        this.#tailOffset = mark.tailOffset;
-        this.#tailDirty = false;
-        for (const [id, bytes] of mark._liveBytesBefore) {
-            if (bytes === undefined)
-                this.#liveBytes.delete(id);
-            else
-                this.#liveBytes.set(id, bytes);
-        }
-        this.#activeBatch = undefined;
-    }
-    async #closeCachedReadHandle(id) {
-        const opening = this.#openingReadHandles.get(id);
-        if (opening !== undefined)
-            await opening.promise.catch(() => undefined);
-        const cached = this.#readHandles.get(id);
-        if (cached !== undefined && cached.readers > 0) {
-            await new Promise((resolve) => cached.drained.push(resolve));
-        }
-        this.#readHandles.get(id)?.handle.close();
-        this.#readHandles.delete(id);
-    }
-    /** Removes an unpublished physical suffix left by a crash before its WAL publication. */
-    truncateTailToPublishedOffset() {
-        const size = this.#tailHandle.getSize();
-        if (size < this.#tailOffset) {
-            throw new Error(`OPFS tail extent ${String(this.#tailId)} is shorter than its published offset: ` +
-                `${String(size)} < ${String(this.#tailOffset)}`);
-        }
-        if (size > this.#tailOffset)
-            this.#tailHandle.truncate(this.#tailOffset);
-    }
-    /**
-     * Replay hook: a WAL entry recorded this placement after the checkpoint was taken. Advances
-     * the tail position and live-byte accounting to match what the writer had done.
-     */
-    restorePlacement(placement) {
-        assertValidPlacement(placement);
-        const liveBytes = safeExtentSum(this.#liveBytes.get(placement.extent) ?? 0, placement.length, "Extent live bytes");
-        this.#liveBytes.set(placement.extent, liveBytes);
-        if (placement.extent === this.#tailId) {
-            this.#tailOffset = Math.max(this.#tailOffset, safeExtentSum(placement.offset, placement.length, "Extent tail offset"));
-        }
-        if (placement.extent >= this.#nextId) {
-            // The writer sealed past the checkpointed tail; adopt its numbering.
-            this.#nextId = safeExtentSuccessor(placement.extent, "Extent ID");
-        }
-    }
-    /** Replay hook: the tail recorded by placements may belong to a newer extent than ours. */
-    async adoptTail(extentId, offset) {
-        assertValidExtentCoordinate(extentId, "Extent ID");
-        assertValidExtentCoordinate(offset, "Extent tail offset");
-        const nextId = safeExtentSuccessor(extentId, "Extent ID");
-        if (extentId === this.#tailId) {
-            this.#tailOffset = Math.max(this.#tailOffset, offset);
-            return;
-        }
-        this.#tailHandle.close();
-        // Recovery validation may have opened the newer extent through the read cache before it
-        // was known to be the tail. Release that shared-read role before taking the tail lock.
-        this.#readHandles.get(extentId)?.handle.close();
-        this.#readHandles.delete(extentId);
-        this.#tailHandle = await this.#tree.openHandle(extentPath(extentId), { create: true });
-        this.#tailId = extentId;
-        this.#tailOffset = offset;
-        this.#nextId = Math.max(this.#nextId, nextId);
-    }
-    get tailExtentId() {
-        return this.#tailId;
-    }
-    /** Appends synchronously; seals and rolls the tail first when it is full (the async part). */
-    async append(bytes, flush) {
-        const initialEnd = safeExtentSum(this.#tailOffset, bytes.byteLength, "Extent tail offset");
-        if (this.#tailOffset > 0 && initialEnd > SEAL_BYTES) {
-            await this.#seal();
-        }
-        const nextOffset = safeExtentSum(this.#tailOffset, bytes.byteLength, "Extent tail offset");
-        const nextLiveBytes = safeExtentSum(this.#liveBytes.get(this.#tailId) ?? 0, bytes.byteLength, "Extent live bytes");
-        const placement = {
-            extent: this.#tailId,
-            offset: this.#tailOffset,
-            length: bytes.byteLength,
-            checksum: this.#checksum(bytes),
-        };
-        writeFully(this.#tailHandle, bytes, placement.offset, `appending extent ${String(placement.extent)}`);
-        this.#tailDirty = true;
-        if (flush)
-            this.flush();
-        this.#tailOffset = nextOffset;
-        this.#rememberLiveBytes(this.#tailId);
-        this.#liveBytes.set(this.#tailId, nextLiveBytes);
-        return placement;
-    }
-    async #seal() {
-        const nextId = safeExtentSuccessor(this.#nextId, "Extent ID");
-        // Relaxed durability batches flushes instead of flushing every append. Sealing is the last
-        // chance to make this immutable extent durable before its held handle is released.
-        this.flush();
-        this.#tailHandle.close();
-        // The now-sealed extent may still be read; it re-opens on demand through the cache.
-        this.#tailId = this.#nextId;
-        this.#nextId = nextId;
-        this.#tailOffset = 0;
-        this.#tailHandle = await this.#tree.openHandle(extentPath(this.#tailId), { create: true });
-    }
-    async read(placement) {
-        assertValidPlacement(placement);
-        if (placement.extent === this.#tailId)
-            return this.#readFromHandle(placement, this.#tailHandle);
-        const acquired = this.#acquireReadHandle(placement.extent);
-        const handle = isHandlePromise(acquired) ? await acquired : acquired;
-        try {
-            return this.#readFromHandle(placement, handle);
-        }
-        finally {
-            this.#releaseReadHandle(placement.extent);
-        }
-    }
-    /** Reads and verifies one complete opaque payload with exactly one checksum scan. */
-    async readVerified(placement) {
-        const bytes = await this.read(placement);
-        if (this.#checksum(bytes) !== placement.checksum) {
-            throw new Error(`Extent placement checksum mismatch: ${String(placement.extent)}:` +
-                `${String(placement.offset)}+${String(placement.length)}`);
-        }
-        return bytes;
-    }
-    /** True when the complete placement currently exists; used to bound crash replay. */
-    async contains(placement) {
-        if (!validPlacement(placement))
-            return false;
-        try {
-            if (placement.extent === this.#tailId) {
-                return placement.offset + placement.length <= this.#tailHandle.getSize();
-            }
-            const acquired = this.#acquireReadHandle(placement.extent);
-            const handle = isHandlePromise(acquired) ? await acquired : acquired;
-            try {
-                return placement.offset + placement.length <= handle.getSize();
-            }
-            finally {
-                this.#releaseReadHandle(placement.extent);
-            }
-        }
-        catch (error) {
-            if (error instanceof DOMException && error.name === "NotFoundError")
-                return false;
-            throw error;
-        }
-    }
-    /**
-     * Returns the sealed extent with the most dead space once less than half its physical bytes
-     * remain live. Relocating that extent keeps sealed-file bytes below twice live payload bytes;
-     * the append tail contributes only one bounded extent beyond that ratio.
-     */
-    async fragmentedExtentId() {
-        let candidate;
-        for (const [id, liveBytes] of this.#liveBytes) {
-            if (id === this.#tailId || liveBytes === 0)
-                continue;
-            const acquired = this.#acquireReadHandle(id);
-            const handle = isHandlePromise(acquired) ? await acquired : acquired;
-            let size;
-            try {
-                size = handle.getSize();
-            }
-            finally {
-                this.#releaseReadHandle(id);
-            }
-            if (size === 0 || liveBytes * 2 >= size)
-                continue;
-            const wasteRatio = (size - liveBytes) / size;
-            if (candidate === undefined || wasteRatio > candidate.wasteRatio) {
-                candidate = { id, wasteRatio };
-            }
-        }
-        return candidate?.id;
-    }
-    /** Actual bytes of every checkpoint-known extent, including the held tail handle. */
-    async physicalByteLengths() {
-        const sizes = new Map();
-        const ids = new Set([...this.#liveBytes.keys(), this.#tailId]);
-        for (const id of ids) {
-            if (id === this.#tailId) {
-                sizes.set(id, this.#tailHandle.getSize());
-                continue;
-            }
-            const acquired = this.#acquireReadHandle(id);
-            const handle = isHandlePromise(acquired) ? await acquired : acquired;
-            try {
-                sizes.set(id, handle.getSize());
-            }
-            finally {
-                this.#releaseReadHandle(id);
-            }
-        }
-        return sizes;
-    }
-    /** Cached hits return the handle directly: no promise allocation or extra await on reads. */
-    #acquireReadHandle(extent) {
-        if (this.#closed)
-            throw new Error("This extent pool is closed");
-        if (this.#deletingExtents.has(extent)) {
-            throw new Error(`Extent ${String(extent)} is being deleted`);
-        }
-        const cached = this.#readHandles.get(extent);
-        if (cached !== undefined) {
-            // Refresh recency.
-            this.#readHandles.delete(extent);
-            this.#readHandles.set(extent, cached);
-            cached.readers += 1;
-            return cached.handle;
-        }
-        const opening = this.#openingReadHandles.get(extent);
-        if (opening !== undefined) {
-            opening.reservations += 1;
-            return opening.promise;
-        }
-        const pending = { reservations: 1 };
-        pending.promise = this.#tree.openHandle(extentPath(extent), { create: false }).then((handle) => {
-            this.#openingReadHandles.delete(extent);
-            // An open already in flight owns reader reservations. A deletion that starts later
-            // blocks new acquisitions and awaits this promise plus those readers; rejecting the
-            // earlier reservations here would let relocation invalidate a selected placement.
-            if (this.#closed) {
-                handle.close();
-                throw new Error(`Extent ${String(extent)} became unavailable while opening`);
-            }
-            this.#readHandles.set(extent, {
-                handle,
-                readers: pending.reservations,
-                drained: [],
-            });
-            this.#evictReadHandles();
-            return handle;
-        }, (error) => {
-            this.#openingReadHandles.delete(extent);
-            throw error;
-        });
-        this.#openingReadHandles.set(extent, pending);
-        return pending.promise;
-    }
-    #releaseReadHandle(extent) {
-        const cached = this.#readHandles.get(extent);
-        if (cached === undefined)
-            return;
-        cached.readers -= 1;
-        if (cached.readers < 0)
-            throw new Error(`Extent ${String(extent)} read lease underflow`);
-        if (cached.readers === 0) {
-            for (const resolve of cached.drained.splice(0))
-                resolve();
-            this.#evictReadHandles();
-        }
-    }
-    #evictReadHandles() {
-        while (this.#readHandles.size > READ_HANDLE_CACHE) {
-            const idle = [...this.#readHandles].find(([, cached]) => cached.readers === 0);
-            if (idle === undefined)
-                return;
-            const [extent, cached] = idle;
-            cached.handle.close();
-            this.#readHandles.delete(extent);
-        }
-    }
-    #readFromHandle(placement, handle) {
-        const end = placement.offset + placement.length;
-        const size = handle.getSize();
-        if (end > size) {
-            throw new Error(`Extent placement exceeds its file: ${String(placement.extent)}:` +
-                `${String(placement.offset)}+${String(placement.length)} > ${String(size)}`);
-        }
-        const bytes = new Uint8Array(placement.length);
-        readFully(handle, bytes, placement.offset, `reading extent ${String(placement.extent)} placement`);
-        return bytes;
-    }
-    /** Live-byte accounting for reclaimed payloads; reports extents now safe to delete. */
-    release(placements) {
-        const decrements = new Map();
-        const ranges = new Map();
-        for (const placement of placements) {
-            assertValidPlacement(placement);
-            decrements.set(placement.extent, (decrements.get(placement.extent) ?? 0) + placement.length);
-            if (placement.length > 0) {
-                const extentRanges = ranges.get(placement.extent) ?? [];
-                extentRanges.push({ start: placement.offset, end: placement.offset + placement.length });
-                ranges.set(placement.extent, extentRanges);
-            }
-        }
-        for (const [id, extentRanges] of ranges) {
-            extentRanges.sort((left, right) => left.start - right.start || left.end - right.end);
-            for (let index = 1; index < extentRanges.length; index += 1) {
-                const previous = extentRanges[index - 1];
-                const current = extentRanges[index];
-                if (previous !== undefined && current !== undefined && current.start < previous.end) {
-                    throw new Error(`Extent ${String(id)} release contains overlapping or duplicate placements: ` +
-                        `${String(previous.start)}..${String(previous.end)} and ` +
-                        `${String(current.start)}..${String(current.end)}`);
-                }
-            }
-        }
-        // Validate the entire batch before mutating one counter. Underflow is an invariant
-        // violation, never evidence that an extent is empty and safe to delete.
-        for (const [id, decrement] of decrements) {
-            const live = this.#liveBytes.get(id);
-            if (live === undefined || decrement > live) {
-                throw new Error(`Extent ${String(id)} live-byte accounting underflow: release ${String(decrement)} ` +
-                    `from ${live === undefined ? "an unknown extent" : String(live)}`);
-            }
-        }
-        for (const [id, decrement] of decrements) {
-            this.#rememberLiveBytes(id);
-            this.#liveBytes.set(id, (this.#liveBytes.get(id) ?? 0) - decrement);
-        }
-        const deletable = [];
-        for (const [id, bytes] of this.#liveBytes) {
-            if (bytes === 0 && id !== this.#tailId)
-                deletable.push(id);
-        }
-        return deletable;
-    }
-    /** Removes a drained extent's file and forgets it. Idempotent. */
-    async deleteExtent(id) {
-        if (this.#activeBatch !== undefined) {
-            throw new Error("Cannot delete an extent while an unpublished batch is active");
-        }
-        if (id === this.#tailId)
-            return;
-        this.#deletingExtents.add(id);
-        try {
-            const opening = this.#openingReadHandles.get(id);
-            if (opening !== undefined)
-                await opening.promise.catch(() => undefined);
-            const cached = this.#readHandles.get(id);
-            if (cached !== undefined && cached.readers > 0) {
-                await new Promise((resolve) => cached.drained.push(resolve));
-            }
-            this.#readHandles.get(id)?.handle.close();
-            this.#readHandles.delete(id);
-            await this.#tree.deleteFile(extentPath(id));
-            // Preserve the zero-live entry when the physical delete is refused. The caller can then
-            // retry it and account the cleanup debt instead of silently orphaning an untracked file.
-            this.#liveBytes.delete(id);
-        }
-        finally {
-            this.#deletingExtents.delete(id);
-        }
-    }
-    meta() {
-        return {
-            nextExtentId: this.#nextId,
-            tailExtentId: this.#tailId,
-            tailOffset: this.#tailOffset,
-            liveBytes: [...this.#liveBytes.entries()],
-        };
-    }
-    flush() {
-        if (!this.#tailDirty)
-            return;
-        this.#tailHandle.flush();
-        this.#tailDirty = false;
-    }
-    close() {
-        this.#closed = true;
-        this.#tailHandle.close();
-        for (const { handle } of this.#readHandles.values())
-            handle.close();
-        this.#readHandles.clear();
-    }
-    #rememberLiveBytes(id) {
-        const batch = this.#activeBatch;
-        if (batch === undefined || batch._liveBytesBefore.has(id))
-            return;
-        batch._liveBytesBefore.set(id, this.#liveBytes.get(id));
-    }
+class ExtentPool {
+  #tree;
+  #checksum;
+  #tailId;
+  #nextId;
+  #tailOffset;
+  #tailHandle;
+  #tailDirty = false;
+  #liveBytes = /* @__PURE__ */ new Map();
+  #readHandles = /* @__PURE__ */ new Map();
+  #openingReadHandles = /* @__PURE__ */ new Map();
+  #deletingExtents = /* @__PURE__ */ new Set();
+  #activeBatch;
+  #closed = false;
+  constructor(tree, meta, tailHandle, checksum) {
+    this.#tree = tree;
+    this.#checksum = checksum;
+    this.#tailId = meta.tailId;
+    this.#nextId = meta.nextId;
+    this.#tailOffset = meta.tailOffset;
+    this.#tailHandle = tailHandle;
+  }
+  static async open(tree, meta, options = {}) {
+    if (meta !== void 0)
+      assertValidExtentMeta(meta);
+    const tailId = meta?.tailExtentId ?? 0;
+    const nextId = meta?.nextExtentId ?? 1;
+    const tailHandle = await tree.openHandle(extentPath(tailId), { create: true });
+    const pool = new ExtentPool(tree, { tailId, nextId, tailOffset: meta?.tailOffset ?? 0 }, tailHandle, options._checksumForTests ?? crc32);
+    for (const [id, bytes] of meta?.liveBytes ?? [])
+      pool.#liveBytes.set(id, bytes);
+    if (tailHandle.getSize() < pool.#tailOffset) {
+      pool.close();
+      throw new Error(`OPFS tail extent ${String(tailId)} is shorter than its checkpointed offset: ${String(tailHandle.getSize())} < ${String(pool.#tailOffset)}`);
+    }
+    return pool;
+  }
+  markBatch() {
+    if (this.#activeBatch !== void 0)
+      throw new Error("An extent append batch is already active");
+    const mark = new ExtentBatchMark(this.#tailId, this.#nextId, this.#tailOffset);
+    this.#activeBatch = mark;
+    return mark;
+  }
+  commitBatch(mark) {
+    if (this.#activeBatch !== mark)
+      throw new Error("Extent batch mark is not active");
+    this.#activeBatch = void 0;
+  }
+  async rollbackBatch(mark) {
+    if (this.#activeBatch !== mark)
+      throw new Error("Extent batch mark is not active");
+    if (mark.nextExtentId > this.#nextId) {
+      throw new Error("Cannot roll an extent pool forward to a future batch mark");
+    }
+    this.#tailHandle.close();
+    for (let id = mark.nextExtentId; id < this.#nextId; id += 1) {
+      await this.#closeCachedReadHandle(id);
+      await this.#tree.deleteFile(extentPath(id));
+    }
+    await this.#closeCachedReadHandle(mark.tailExtentId);
+    this.#tailHandle = await this.#tree.openHandle(extentPath(mark.tailExtentId), { create: true });
+    this.#tailHandle.truncate(mark.tailOffset);
+    this.#tailId = mark.tailExtentId;
+    this.#nextId = mark.nextExtentId;
+    this.#tailOffset = mark.tailOffset;
+    this.#tailDirty = false;
+    for (const [id, bytes] of mark._liveBytesBefore) {
+      if (bytes === void 0)
+        this.#liveBytes.delete(id);
+      else
+        this.#liveBytes.set(id, bytes);
+    }
+    this.#activeBatch = void 0;
+  }
+  async #closeCachedReadHandle(id) {
+    const opening = this.#openingReadHandles.get(id);
+    if (opening !== void 0)
+      await opening.promise.catch(() => void 0);
+    const cached = this.#readHandles.get(id);
+    if (cached !== void 0 && cached.readers > 0) {
+      await new Promise((resolve) => cached.drained.push(resolve));
+    }
+    this.#readHandles.get(id)?.handle.close();
+    this.#readHandles.delete(id);
+  }
+  truncateTailToPublishedOffset() {
+    const size = this.#tailHandle.getSize();
+    if (size < this.#tailOffset) {
+      throw new Error(`OPFS tail extent ${String(this.#tailId)} is shorter than its published offset: ${String(size)} < ${String(this.#tailOffset)}`);
+    }
+    if (size > this.#tailOffset)
+      this.#tailHandle.truncate(this.#tailOffset);
+  }
+  restorePlacement(placement) {
+    assertValidPlacement(placement);
+    const liveBytes = safeExtentSum(this.#liveBytes.get(placement.extent) ?? 0, placement.length, "Extent live bytes");
+    this.#liveBytes.set(placement.extent, liveBytes);
+    if (placement.extent === this.#tailId) {
+      this.#tailOffset = Math.max(this.#tailOffset, safeExtentSum(placement.offset, placement.length, "Extent tail offset"));
+    }
+    if (placement.extent >= this.#nextId) {
+      this.#nextId = safeExtentSuccessor(placement.extent, "Extent ID");
+    }
+  }
+  async adoptTail(extentId, offset) {
+    assertValidExtentCoordinate(extentId, "Extent ID");
+    assertValidExtentCoordinate(offset, "Extent tail offset");
+    const nextId = safeExtentSuccessor(extentId, "Extent ID");
+    if (extentId === this.#tailId) {
+      this.#tailOffset = Math.max(this.#tailOffset, offset);
+      return;
+    }
+    this.#tailHandle.close();
+    this.#readHandles.get(extentId)?.handle.close();
+    this.#readHandles.delete(extentId);
+    this.#tailHandle = await this.#tree.openHandle(extentPath(extentId), { create: true });
+    this.#tailId = extentId;
+    this.#tailOffset = offset;
+    this.#nextId = Math.max(this.#nextId, nextId);
+  }
+  get tailExtentId() {
+    return this.#tailId;
+  }
+  async append(bytes, flush) {
+    const initialEnd = safeExtentSum(this.#tailOffset, bytes.byteLength, "Extent tail offset");
+    if (this.#tailOffset > 0 && initialEnd > SEAL_BYTES) {
+      await this.#seal();
+    }
+    const nextOffset = safeExtentSum(this.#tailOffset, bytes.byteLength, "Extent tail offset");
+    const nextLiveBytes = safeExtentSum(this.#liveBytes.get(this.#tailId) ?? 0, bytes.byteLength, "Extent live bytes");
+    const placement = {
+      extent: this.#tailId,
+      offset: this.#tailOffset,
+      length: bytes.byteLength,
+      checksum: this.#checksum(bytes)
+    };
+    writeFully(this.#tailHandle, bytes, placement.offset, `appending extent ${String(placement.extent)}`);
+    this.#tailDirty = true;
+    if (flush)
+      this.flush();
+    this.#tailOffset = nextOffset;
+    this.#rememberLiveBytes(this.#tailId);
+    this.#liveBytes.set(this.#tailId, nextLiveBytes);
+    return placement;
+  }
+  async #seal() {
+    const nextId = safeExtentSuccessor(this.#nextId, "Extent ID");
+    this.flush();
+    this.#tailHandle.close();
+    this.#tailId = this.#nextId;
+    this.#nextId = nextId;
+    this.#tailOffset = 0;
+    this.#tailHandle = await this.#tree.openHandle(extentPath(this.#tailId), { create: true });
+  }
+  async read(placement) {
+    assertValidPlacement(placement);
+    if (placement.extent === this.#tailId)
+      return this.#readFromHandle(placement, this.#tailHandle);
+    const acquired = this.#acquireReadHandle(placement.extent);
+    const handle = isHandlePromise(acquired) ? await acquired : acquired;
+    try {
+      return this.#readFromHandle(placement, handle);
+    } finally {
+      this.#releaseReadHandle(placement.extent);
+    }
+  }
+  async readVerified(placement) {
+    const bytes = await this.read(placement);
+    if (this.#checksum(bytes) !== placement.checksum) {
+      throw new Error(`Extent placement checksum mismatch: ${String(placement.extent)}:${String(placement.offset)}+${String(placement.length)}`);
+    }
+    return bytes;
+  }
+  async contains(placement) {
+    if (!validPlacement(placement))
+      return false;
+    try {
+      if (placement.extent === this.#tailId) {
+        return placement.offset + placement.length <= this.#tailHandle.getSize();
+      }
+      const acquired = this.#acquireReadHandle(placement.extent);
+      const handle = isHandlePromise(acquired) ? await acquired : acquired;
+      try {
+        return placement.offset + placement.length <= handle.getSize();
+      } finally {
+        this.#releaseReadHandle(placement.extent);
+      }
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "NotFoundError")
+        return false;
+      throw error;
+    }
+  }
+  async fragmentedExtentId() {
+    let candidate;
+    for (const [id, liveBytes] of this.#liveBytes) {
+      if (id === this.#tailId || liveBytes === 0)
+        continue;
+      const acquired = this.#acquireReadHandle(id);
+      const handle = isHandlePromise(acquired) ? await acquired : acquired;
+      let size;
+      try {
+        size = handle.getSize();
+      } finally {
+        this.#releaseReadHandle(id);
+      }
+      if (size === 0 || liveBytes * 2 >= size)
+        continue;
+      const wasteRatio = (size - liveBytes) / size;
+      if (candidate === void 0 || wasteRatio > candidate.wasteRatio) {
+        candidate = { id, wasteRatio };
+      }
+    }
+    return candidate?.id;
+  }
+  async physicalByteLengths() {
+    const sizes = /* @__PURE__ */ new Map();
+    const ids = /* @__PURE__ */ new Set([...this.#liveBytes.keys(), this.#tailId]);
+    for (const id of ids) {
+      if (id === this.#tailId) {
+        sizes.set(id, this.#tailHandle.getSize());
+        continue;
+      }
+      const acquired = this.#acquireReadHandle(id);
+      const handle = isHandlePromise(acquired) ? await acquired : acquired;
+      try {
+        sizes.set(id, handle.getSize());
+      } finally {
+        this.#releaseReadHandle(id);
+      }
+    }
+    return sizes;
+  }
+  #acquireReadHandle(extent) {
+    if (this.#closed)
+      throw new Error("This extent pool is closed");
+    if (this.#deletingExtents.has(extent)) {
+      throw new Error(`Extent ${String(extent)} is being deleted`);
+    }
+    const cached = this.#readHandles.get(extent);
+    if (cached !== void 0) {
+      this.#readHandles.delete(extent);
+      this.#readHandles.set(extent, cached);
+      cached.readers += 1;
+      return cached.handle;
+    }
+    const opening = this.#openingReadHandles.get(extent);
+    if (opening !== void 0) {
+      opening.reservations += 1;
+      return opening.promise;
+    }
+    const pending = { reservations: 1 };
+    pending.promise = this.#tree.openHandle(extentPath(extent), { create: false }).then((handle) => {
+      this.#openingReadHandles.delete(extent);
+      if (this.#closed) {
+        handle.close();
+        throw new Error(`Extent ${String(extent)} became unavailable while opening`);
+      }
+      this.#readHandles.set(extent, {
+        handle,
+        readers: pending.reservations,
+        drained: []
+      });
+      this.#evictReadHandles();
+      return handle;
+    }, (error) => {
+      this.#openingReadHandles.delete(extent);
+      throw error;
+    });
+    this.#openingReadHandles.set(extent, pending);
+    return pending.promise;
+  }
+  #releaseReadHandle(extent) {
+    const cached = this.#readHandles.get(extent);
+    if (cached === void 0)
+      return;
+    cached.readers -= 1;
+    if (cached.readers < 0)
+      throw new Error(`Extent ${String(extent)} read lease underflow`);
+    if (cached.readers === 0) {
+      for (const resolve of cached.drained.splice(0))
+        resolve();
+      this.#evictReadHandles();
+    }
+  }
+  #evictReadHandles() {
+    while (this.#readHandles.size > READ_HANDLE_CACHE) {
+      const idle = [...this.#readHandles].find(([, cached2]) => cached2.readers === 0);
+      if (idle === void 0)
+        return;
+      const [extent, cached] = idle;
+      cached.handle.close();
+      this.#readHandles.delete(extent);
+    }
+  }
+  #readFromHandle(placement, handle) {
+    const end = placement.offset + placement.length;
+    const size = handle.getSize();
+    if (end > size) {
+      throw new Error(`Extent placement exceeds its file: ${String(placement.extent)}:${String(placement.offset)}+${String(placement.length)} > ${String(size)}`);
+    }
+    const bytes = new Uint8Array(placement.length);
+    readFully(handle, bytes, placement.offset, `reading extent ${String(placement.extent)} placement`);
+    return bytes;
+  }
+  release(placements) {
+    const decrements = /* @__PURE__ */ new Map();
+    const ranges = /* @__PURE__ */ new Map();
+    for (const placement of placements) {
+      assertValidPlacement(placement);
+      decrements.set(placement.extent, (decrements.get(placement.extent) ?? 0) + placement.length);
+      if (placement.length > 0) {
+        const extentRanges = ranges.get(placement.extent) ?? [];
+        extentRanges.push({ start: placement.offset, end: placement.offset + placement.length });
+        ranges.set(placement.extent, extentRanges);
+      }
+    }
+    for (const [id, extentRanges] of ranges) {
+      extentRanges.sort((left, right) => left.start - right.start || left.end - right.end);
+      for (let index = 1; index < extentRanges.length; index += 1) {
+        const previous = extentRanges[index - 1];
+        const current = extentRanges[index];
+        if (previous !== void 0 && current !== void 0 && current.start < previous.end) {
+          throw new Error(`Extent ${String(id)} release contains overlapping or duplicate placements: ${String(previous.start)}..${String(previous.end)} and ${String(current.start)}..${String(current.end)}`);
+        }
+      }
+    }
+    for (const [id, decrement] of decrements) {
+      const live = this.#liveBytes.get(id);
+      if (live === void 0 || decrement > live) {
+        throw new Error(`Extent ${String(id)} live-byte accounting underflow: release ${String(decrement)} from ${live === void 0 ? "an unknown extent" : String(live)}`);
+      }
+    }
+    for (const [id, decrement] of decrements) {
+      this.#rememberLiveBytes(id);
+      this.#liveBytes.set(id, (this.#liveBytes.get(id) ?? 0) - decrement);
+    }
+    const deletable = [];
+    for (const [id, bytes] of this.#liveBytes) {
+      if (bytes === 0 && id !== this.#tailId)
+        deletable.push(id);
+    }
+    return deletable;
+  }
+  async deleteExtent(id) {
+    if (this.#activeBatch !== void 0) {
+      throw new Error("Cannot delete an extent while an unpublished batch is active");
+    }
+    if (id === this.#tailId)
+      return;
+    this.#deletingExtents.add(id);
+    try {
+      const opening = this.#openingReadHandles.get(id);
+      if (opening !== void 0)
+        await opening.promise.catch(() => void 0);
+      const cached = this.#readHandles.get(id);
+      if (cached !== void 0 && cached.readers > 0) {
+        await new Promise((resolve) => cached.drained.push(resolve));
+      }
+      this.#readHandles.get(id)?.handle.close();
+      this.#readHandles.delete(id);
+      await this.#tree.deleteFile(extentPath(id));
+      this.#liveBytes.delete(id);
+    } finally {
+      this.#deletingExtents.delete(id);
+    }
+  }
+  meta() {
+    return {
+      nextExtentId: this.#nextId,
+      tailExtentId: this.#tailId,
+      tailOffset: this.#tailOffset,
+      liveBytes: [...this.#liveBytes.entries()]
+    };
+  }
+  flush() {
+    if (!this.#tailDirty)
+      return;
+    this.#tailHandle.flush();
+    this.#tailDirty = false;
+  }
+  close() {
+    this.#closed = true;
+    this.#tailHandle.close();
+    for (const { handle } of this.#readHandles.values())
+      handle.close();
+    this.#readHandles.clear();
+  }
+  #rememberLiveBytes(id) {
+    const batch = this.#activeBatch;
+    if (batch === void 0 || batch._liveBytesBefore.has(id))
+      return;
+    batch._liveBytesBefore.set(id, this.#liveBytes.get(id));
+  }
 }
-export function extentPath(id) {
-    return ["extents", String(id).padStart(6, "0")];
+function extentPath(id) {
+  return ["extents", String(id).padStart(6, "0")];
 }
-export function validPlacement(placement) {
-    return (Number.isSafeInteger(placement.extent) &&
-        placement.extent >= 0 &&
-        placement.extent < Number.MAX_SAFE_INTEGER &&
-        Number.isSafeInteger(placement.offset) &&
-        placement.offset >= 0 &&
-        Number.isSafeInteger(placement.length) &&
-        placement.length >= 0 &&
-        Number.isSafeInteger(placement.checksum) &&
-        placement.checksum >= 0 &&
-        placement.checksum <= 0xffff_ffff &&
-        placement.offset + placement.length <= Number.MAX_SAFE_INTEGER);
+function validPlacement(placement) {
+  return Number.isSafeInteger(placement.extent) && placement.extent >= 0 && placement.extent < Number.MAX_SAFE_INTEGER && Number.isSafeInteger(placement.offset) && placement.offset >= 0 && Number.isSafeInteger(placement.length) && placement.length >= 0 && Number.isSafeInteger(placement.checksum) && placement.checksum >= 0 && placement.checksum <= 4294967295 && placement.offset + placement.length <= Number.MAX_SAFE_INTEGER;
 }
-export function assertValidPlacement(placement) {
-    if (!validPlacement(placement)) {
-        throw new TypeError(`Invalid extent placement: ${String(placement.extent)}:${String(placement.offset)}+` +
-            `${String(placement.length)} checksum ${String(placement.checksum)}`);
-    }
+function assertValidPlacement(placement) {
+  if (!validPlacement(placement)) {
+    throw new TypeError(`Invalid extent placement: ${String(placement.extent)}:${String(placement.offset)}+${String(placement.length)} checksum ${String(placement.checksum)}`);
+  }
 }
-export function assertValidExtentMeta(meta) {
-    if (!Number.isSafeInteger(meta.nextExtentId) ||
-        meta.nextExtentId < 1 ||
-        !Number.isSafeInteger(meta.tailExtentId) ||
-        meta.tailExtentId < 0 ||
-        meta.tailExtentId >= meta.nextExtentId ||
-        !Number.isSafeInteger(meta.tailOffset) ||
-        meta.tailOffset < 0 ||
-        !Array.isArray(meta.liveBytes)) {
-        throw new TypeError("Invalid OPFS extent checkpoint metadata");
-    }
-    const ids = new Set();
-    for (const entry of meta.liveBytes) {
-        const [id, bytes] = entry;
-        if (!Number.isSafeInteger(id) ||
-            id < 0 ||
-            id >= meta.nextExtentId ||
-            ids.has(id) ||
-            !Number.isSafeInteger(bytes) ||
-            bytes < 0) {
-            throw new TypeError(`Invalid OPFS extent live-byte entry: ${String(id)} => ${String(bytes)}`);
-        }
-        ids.add(id);
-    }
+function assertValidExtentMeta(meta) {
+  if (!Number.isSafeInteger(meta.nextExtentId) || meta.nextExtentId < 1 || !Number.isSafeInteger(meta.tailExtentId) || meta.tailExtentId < 0 || meta.tailExtentId >= meta.nextExtentId || !Number.isSafeInteger(meta.tailOffset) || meta.tailOffset < 0 || !Array.isArray(meta.liveBytes)) {
+    throw new TypeError("Invalid OPFS extent checkpoint metadata");
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const entry of meta.liveBytes) {
+    const [id, bytes] = entry;
+    if (!Number.isSafeInteger(id) || id < 0 || id >= meta.nextExtentId || ids.has(id) || !Number.isSafeInteger(bytes) || bytes < 0) {
+      throw new TypeError(`Invalid OPFS extent live-byte entry: ${String(id)} => ${String(bytes)}`);
+    }
+    ids.add(id);
+  }
 }
 function isHandlePromise(value) {
-    return typeof value.then === "function";
+  return typeof value.then === "function";
 }
 function assertValidExtentCoordinate(value, label) {
-    if (!Number.isSafeInteger(value) || value < 0)
-        throw new RangeError(`${label} is out of range`);
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new RangeError(`${label} is out of range`);
 }
 function safeExtentSuccessor(value, label) {
-    if (!Number.isSafeInteger(value) || value < 0 || value >= Number.MAX_SAFE_INTEGER) {
-        throw new RangeError(`${label} cannot exceed the safe integer range`);
-    }
-    return value + 1;
+  if (!Number.isSafeInteger(value) || value < 0 || value >= Number.MAX_SAFE_INTEGER) {
+    throw new RangeError(`${label} cannot exceed the safe integer range`);
+  }
+  return value + 1;
 }
 function safeExtentSum(left, right, label) {
-    if (!Number.isSafeInteger(left) ||
-        left < 0 ||
-        !Number.isSafeInteger(right) ||
-        right < 0 ||
-        left > Number.MAX_SAFE_INTEGER - right) {
-        throw new RangeError(`${label} cannot exceed the safe integer range`);
-    }
-    return left + right;
+  if (!Number.isSafeInteger(left) || left < 0 || !Number.isSafeInteger(right) || right < 0 || left > Number.MAX_SAFE_INTEGER - right) {
+    throw new RangeError(`${label} cannot exceed the safe integer range`);
+  }
+  return left + right;
 }
+export {
+  ExtentBatchMark,
+  ExtentPool,
+  assertValidExtentMeta,
+  assertValidPlacement,
+  extentPath,
+  validPlacement
+};