@poe-platform/safe-fs 0.1.807 → 0.1.809

package/dist/safe-fs/fs/s3/filesystem.d.ts

@@ -53,7 +53,7 @@ export declare class S3FileSystem implements FileSystem {
         truncate: boolean;
         atomicRenameNoReplace: false;
         rename: boolean;
-        streamingAppend: boolean;
+        streamingAppend: false;
         randomAccessWrite: false;
         readOnly: boolean;
         symlinks: false;
@@ -109,6 +109,7 @@ export declare class S3FileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     mkdir(input: string, options?: MkdirOptions): Promise<void>;
     readdir(input: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    iterateDirectory(input: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     private tree;
     rmdir(input: string, options?: FsOptions): Promise<void>;
     rm(input: string, options?: RemoveOptions): Promise<void>;

package/dist/safe-fs/fs/s3/filesystem.js

@@ -152,8 +152,8 @@ export class S3FileSystem {
             atomicRenameNoReplace: false,
             rename: this.allowRename && options.transport.capabilities?.conditionalDelete === true
                 && (options.transport.capabilities?.conditionalCopy === true || options.transport.capabilities?.conditionalPut === true),
-            streamingAppend: options.transport.capabilities?.streamingWrite === true
-                && options.transport.capabilities?.conditionalPut === true && typeof options.transport.putObjectStream === "function",
+            // Conditional append currently collects the old and incoming bodies.
+            streamingAppend: false,
             randomAccessWrite: false,
             readOnly: options.readOnly ?? false,
             symlinks: false, hardlinks: false, permissions: false,
@@ -341,25 +341,33 @@ export class S3FileSystem {
         if (key.endsWith("/") && object.Size !== 0)
             fail("ENOTSUP", "listObjectsV2", path, "nonempty slash-suffixed objects cannot be treated as directories");
     }
-    async *pages(prefix, path, options, delimiter, maxKeys = this.pageSize) {
-        const tokens = new Set();
-        let token;
-        let entries = 0;
+    async *pages(prefix, path, options, delimiter, maxKeys = this.pageSize, rememberTokens = true) {
+        // Buffered callers preserve exact repeated-token rejection. Lazy traversal
+        // detects continuation cycles without retaining the whole token history.
+        const tokens = rememberTokens ? new Set() : undefined;
+        let token, checkpoint;
+        let entries = 0, pageCount = 0, span = 0, power = 1;
         do {
             const page = await this.page(prefix, path, options, delimiter, token, maxKeys);
             entries += (page.Contents?.length ?? 0) + (page.CommonPrefixes?.length ?? 0);
-            if (entries > this.maxListEntries || tokens.size >= this.maxListEntries)
+            if (entries > this.maxListEntries || ++pageCount > this.maxListEntries)
                 fail("EFBIG", "listObjectsV2", path, "listing exceeds maxListEntries");
+            const truncated = page.IsTruncated, next = page.NextContinuationToken;
             yield page;
-            if (!page.IsTruncated)
+            if (!truncated)
                 return;
-            token = page.NextContinuationToken;
-            if (typeof token !== "string" || !token || tokens.has(token))
+            if (typeof next !== "string" || !next || next === token || next === checkpoint || tokens?.has(next))
                 fail("EIO", "listObjectsV2", path, "missing or repeated continuation token");
-            tokens.add(token);
+            if (++span === power) {
+                checkpoint = next;
+                span = 0;
+                power = Math.min(Number.MAX_SAFE_INTEGER, power * 2);
+            }
+            tokens?.add(next);
+            token = next;
         } while (true);
     }
-    async inspect(path, options) {
+    async inspect(path, options, rememberTokens = true) {
         if (path === "/") {
             const listing = await this.page(this.prefix, path, options, undefined, undefined, 1);
             const marker = this.prefix && listing.Contents?.some(object => object.Key === this.prefix)
@@ -375,7 +383,7 @@ export class S3FileSystem {
         const directoryKey = this.directoryKey(path);
         let directory = false;
         let hasMarker = false;
-        for await (const children of this.pages(directoryKey, path, options, undefined, 1)) {
+        for await (const children of this.pages(directoryKey, path, options, undefined, 1, rememberTokens)) {
             if ((children.Contents?.length ?? 0) > 0) {
                 directory = true;
                 hasMarker = children.Contents.some(object => object.Key === directoryKey);
@@ -393,7 +401,7 @@ export class S3FileSystem {
             return { stat: this.makeStat("directory", marker), ...(marker ? { metadata: marker } : {}) };
         return undefined;
     }
-    async lookup(path, options) {
+    async lookup(path, options, rememberTokens = true) {
         const ancestors = [];
         for (let parent = posix.dirname(path); path !== "/"; parent = posix.dirname(parent)) {
             ancestors.unshift(parent);
@@ -403,13 +411,13 @@ export class S3FileSystem {
         for (const parent of ancestors) {
             if (parent === "/" && this.prefix === "")
                 continue;
-            const ancestor = await this.inspect(parent, options);
+            const ancestor = await this.inspect(parent, options, rememberTokens);
             if (!ancestor)
                 fail("ENOENT", "stat", parent);
             if (ancestor.stat.type !== "directory")
                 fail("ENOTDIR", "stat", parent);
         }
-        return this.inspect(path, options);
+        return this.inspect(path, options, rememberTokens);
     }
     requireDirectorySuffix(input, info) {
         if (input.endsWith("/") && info?.stat.type === "file")
@@ -596,6 +604,37 @@ export class S3FileSystem {
         }
         return [...entries.values()].sort((left, right) => compareKeys(left.name, right.name));
     }
+    async *iterateDirectory(input, options = {}) {
+        const path = this.path(input);
+        const directory = await this.lookup(path, options, false);
+        if (!directory)
+            fail("ENOENT", "iterateDirectory", path);
+        if (directory.stat.type !== "directory")
+            fail("ENOTDIR", "iterateDirectory", path);
+        const prefix = this.directoryKey(path);
+        for await (const page of this.pages(prefix, path, options, "/", this.pageSize, false)) {
+            // Snapshot one bounded service page before yielding to caller code.
+            if ((page.Contents?.length ?? 0) + (page.CommonPrefixes?.length ?? 0) > this.pageSize)
+                fail("EIO", "iterateDirectory", path, "transport exceeded requested page size");
+            const entries = [];
+            for (const item of page.Contents ?? [])
+                if (item.Key !== prefix)
+                    entries.push({ name: item.Key.slice(prefix.length), type: "file" });
+            for (const item of page.CommonPrefixes ?? [])
+                entries.push({ name: item.Prefix.slice(prefix.length, -1), type: "directory" });
+            for (const entry of entries) {
+                this.checkAbort(options, "iterateDirectory", path);
+                if (!entry.name || entry.name.includes("/"))
+                    fail("EIO", "iterateDirectory", path, "invalid direct child in delimited listing");
+                // Revalidation preserves file/prefix collision detection across pages
+                // and follows the backend's live namespace without retaining all names.
+                const child = await this.lookup(path === "/" ? `/${entry.name}` : `${path}/${entry.name}`, options, false);
+                this.checkAbort(options, "iterateDirectory", path);
+                if (child)
+                    yield { name: entry.name, type: child.stat.type };
+            }
+        }
+    }
     async tree(path, options) {
         const objects = new Map();
         for await (const page of this.pages(this.directoryKey(path), path, options)) {

package/dist/safe-fs/fs/scoped.js

@@ -21,7 +21,7 @@ const operations = new Set([
     "prepareDirectoryAncestry", "prepareStagingResolution", "publishStagedFileSet",
     "publishFileConditional", "removeEntryConditional", "removeTreeConditional", "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory",
     "confineExtraction", "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
-    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir",
+    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir", "iterateDirectory",
     "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "unlink", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
 ]);
@@ -188,7 +188,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
             close: (options = {}) => closing ??= Promise.resolve().then(() => descriptor.close(options)),
         };
     };
-    const wrapStream = (source, options) => {
+    const wrapStream = (source, options, chargeNext = false) => {
         const budgetFrames = getScopedTransportBudget();
         return {
             [Symbol.asyncIterator]() {
@@ -203,6 +203,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             await closing;
                             return { done: true, value: undefined };
                         }
+                        if (chargeNext)
+                            admit(options);
                         const result = await withScopedTransportBudget(budgetFrames, operation);
                         assertOpen(options);
                         if (closing) {
@@ -341,6 +343,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             if (property === "publishStagedFile") {
                                 const publishOptions = (options ?? {});
                                 await requireOwnedMutation(original, args[1], "atomicFileStaging", publishOptions, publishOptions.destination === null);
+                                if (publishOptions.preserveIdentity)
+                                    await requireOwnedMutation(original, args[1], "atomicStagedFileMutation", publishOptions);
                                 const query = options.destination === null ? { ...options, create: true } : options;
                                 const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(args[1], query) ?? original.capabilities);
                                 assertReady();
@@ -430,7 +434,11 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             });
                         return Reflect.apply(method, original, args);
                     })();
+                if (property === "iterateDirectory")
+                    args[1] = { ...args[1], signal: combineSignal(args[1]?.signal) };
                 const result = Reflect.apply(method, original, args);
+                if (property === "iterateDirectory")
+                    return wrapStream(result, args[1], true);
                 return property === "readStream" ? wrapStream(result, args[1]) : result;
             };
             const dispatch = (...args) => {
@@ -438,7 +446,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                     return executeDispatch(args);
                 if (operations.has(property)) {
                     const optionIndex = ["compareEntry", "createStagedFile", "utimes"].includes(String(property)) ? 3
-                        : ["writeFile", "appendFile", "writeStream", "rename", "copyFile", "link", "symlink", "access", "chmod", "truncate", "resizeFile", "publishFileConditional", "writeFileConditional", "publishStagedFile"].includes(String(property)) ? 2 : 1;
+                        : ["writeFile", "appendFile", "writeStream", "rename", "copyFile", "link", "symlink", "access", "chmod", "truncate", "resizeFile", "publishFileConditional", "writeFileConditional", "publishStagedFile", "publishStagedFileSet"].includes(String(property)) ? 2 : 1;
                     args[optionIndex] = scopeTransportOptions((args[optionIndex] ?? {}), admit, credit);
                 }
                 return runScopedTransportBudget(admit, () => executeDispatch(args), credit);
@@ -451,7 +459,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                     try {
                         const declared = ownedMutationCapabilities(original, await original.capabilitiesFor?.(path, { ...controls, stagingResolution: true }) ?? original.capabilities);
                         controls.signal?.throwIfAborted();
-                        if (declared.synchronousStagingResolution !== true)
+                        if (declared.synchronousStagingResolution !== true || controls.followFinalSymlink === true && declared.synchronousFollowedStagingResolution !== true)
                             throw new FsError("ENOTSUP", { path });
                         const resolution = snapshotStagingResolution(await Reflect.apply(method, original, [path, controls]));
                         controls.signal?.throwIfAborted();
@@ -528,7 +536,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                                     ? async (...args) => ownedMutationCapabilities(original, retainedResizeCapabilities(original, await dispatch(...args)))
                                     : property === "openReadFile"
                                         ? async (...args) => wrapHandle(await dispatch(...args))
-                                        : operations.has(property) && property !== "canonicalizeMissingTarget" && property !== "readStream"
+                                        : operations.has(property) && property !== "canonicalizeMissingTarget" && property !== "readStream" && property !== "iterateDirectory"
                                             ? (...args) => {
                                                 try {
                                                     const res = dispatch(...args);

package/dist/safe-fs/index.d.ts

@@ -23,3 +23,4 @@ export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createNodeFileSystemAdapterRegistry } from "./config.node.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";

package/dist/safe-fs/index.js

@@ -19,3 +19,4 @@ export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createNodeFileSystemAdapterRegistry } from "./config.node.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";

package/dist/safe-fs/runtime-core.d.ts

@@ -25,3 +25,4 @@ export declare function tryWriteMemoryFileSync(fs: FileSystem, path: string, dat
 export declare function tryMkdirMemorySync(fs: FileSystem, path: string, recursive: boolean, mode: number, signal?: AbortSignal, dirPrefixHint?: string): boolean;
 export declare function tryRmRfMemorySync(fs: FileSystem, path: string, signal?: AbortSignal): boolean;
 export declare function tryWriteMemoryFileInDirSync(fs: FileSystem, dirPrefix: string, name: string, data: Uint8Array, append: boolean, mode: number, signal?: AbortSignal): boolean;
+export { readFileStream } from "./fs/read-file-stream.js";

package/dist/safe-fs/runtime-core.js

@@ -55,3 +55,4 @@ export function tryRmRfMemorySync(fs, path, signal) {
 export function tryWriteMemoryFileInDirSync(fs, dirPrefix, name, data, append, mode, signal) {
     return Boolean((fs && _getMemHooks()?.byProto?.get(Object.getPrototypeOf(fs))?.tryWriteMemoryFileInDirSync)?.(fs, dirPrefix, name, data, append, mode, signal));
 }
+export { readFileStream } from "./fs/read-file-stream.js";

package/dist/safe-fs/storage.d.ts

@@ -0,0 +1,57 @@
+import type { FileSystem } from "./contracts/filesystem.js";
+export interface PagedStorageContext {
+    readonly fs: FileSystem;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly signal: AbortSignal;
+}
+/** A bounded page cache backed only by the caller filesystem. The default is
+ * one MiB; callers own close() on every outcome. Memory filesystems still retain
+ * spilled data in RAM, so large workloads require an external backing provider. */
+export declare class PagedStorage {
+    private readonly context;
+    private readonly maxPages;
+    private readonly pages;
+    private readonly controller;
+    private readonly signal;
+    private descriptor;
+    private parent;
+    private initial;
+    private path;
+    private diskLength;
+    private unlinked;
+    private end;
+    private active;
+    private closing;
+    constructor(context: PagedStorageContext, maxPages?: number);
+    allocate(length: number): number;
+    private operation;
+    private spill;
+    private flush;
+    private page;
+    write(position: number, bytes: Uint8Array): Promise<void>;
+    append(bytes: Uint8Array): Promise<number>;
+    read(position: number, length: number): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+/** Fixed-depth radix index: both dense and sparse 64-bit keys use bounded RAM. */
+export declare class IntegerTable {
+    private readonly storage;
+    private readonly maxEntries;
+    private root;
+    private revision;
+    private readonly branches;
+    private readonly cache;
+    constructor(storage: Pick<PagedStorage, "allocate" | "read" | "write">, maxEntries?: number);
+    private retain;
+    get(key: bigint): Promise<bigint | undefined>;
+    set(key: bigint, value: bigint): Promise<void>;
+    /** Ordered replay with a fixed 16-level radix stack (at most 2 KiB of
+     * owned node bytes) and 128 output records. Batches avoid alternating sparse
+     * index reads with consumer writes on every record. Mutation is not permitted. */
+    entries(start?: bigint, end?: bigint): AsyncGenerator<readonly [bigint, bigint]>;
+    /** Hot radix paths must not evict dirty leaf pages in a one-page backend. */
+    private branch;
+    private lookup;
+    private persist;
+}

package/dist/safe-fs/storage.js

@@ -0,0 +1,364 @@
+import { FsError, isFsError } from "./contracts/errors.js";
+const pageBytes = 16 * 1024;
+let serial = 0;
+/** A bounded page cache backed only by the caller filesystem. The default is
+ * one MiB; callers own close() on every outcome. Memory filesystems still retain
+ * spilled data in RAM, so large workloads require an external backing provider. */
+export class PagedStorage {
+    context;
+    maxPages;
+    pages = new Map();
+    controller = new AbortController();
+    signal;
+    descriptor;
+    parent;
+    initial;
+    path;
+    diskLength = 0;
+    unlinked = false;
+    end = 8; // Zero is the absent-pointer sentinel.
+    active = Promise.resolve();
+    closing;
+    constructor(context, maxPages = 64) {
+        this.context = context;
+        this.maxPages = maxPages;
+        if (!Number.isSafeInteger(maxPages) || maxPages < 1)
+            throw new RangeError("Invalid storage page cache size");
+        this.signal = AbortSignal.any([context.signal, this.controller.signal]);
+    }
+    allocate(length) {
+        this.signal.throwIfAborted();
+        if (!Number.isSafeInteger(length) || length < 0 || length > Number.MAX_SAFE_INTEGER - this.end)
+            throw new FsError("EFBIG");
+        const offset = this.end;
+        this.end += length;
+        return offset;
+    }
+    operation(action) {
+        this.signal.throwIfAborted();
+        const work = this.active.then(() => {
+            this.signal.throwIfAborted();
+            return action();
+        });
+        this.active = work.then(() => undefined, () => undefined);
+        return work;
+    }
+    async spill() {
+        const { fs, cwd, env } = this.context;
+        if (!fs.open || !fs.removeFileConditional)
+            throw new FsError("ENOTSUP", { message: "spill storage requires retained read/write handles and conditional removal" });
+        const selected = env.TMPDIR || cwd;
+        const directory = selected.startsWith("/") ? selected : `${cwd}/${selected}`;
+        this.parent = await fs.stat(directory, { signal: this.signal });
+        this.signal.throwIfAborted();
+        if (this.parent.type !== "directory")
+            throw new FsError("ENOTDIR", { path: directory });
+        for (let attempt = 0; attempt < 128; attempt++) {
+            const path = `${directory.endsWith("/") ? directory : directory + "/"}.storage-${++serial}`;
+            try {
+                this.descriptor = await fs.open(path, { access: "readwrite", creation: "exclusive", mode: 0o600, signal: this.signal });
+                this.path = path;
+                break;
+            }
+            catch (error) {
+                this.signal.throwIfAborted();
+                if (!isFsError(error) || error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        if (!this.descriptor)
+            throw new FsError("EEXIST", { path: directory });
+        // Retain the acquisition receipt even if cancellation wins immediately after open.
+        this.initial = await this.descriptor.stat();
+        this.signal.throwIfAborted();
+        if (!this.descriptor.capabilities.positionedRead || !this.descriptor.capabilities.positionedWrite)
+            throw new FsError("ENOTSUP");
+        // Detach the name before storing input. A later output or random-source path
+        // cannot alias our scratch file; the retained descriptor owns its lifetime.
+        await fs.removeFileConditional(this.path, { parent: this.parent, expected: this.initial, signal: this.signal });
+        this.unlinked = true;
+        for (const [number, page] of this.pages)
+            await this.flush(number, page);
+    }
+    async flush(number, page) {
+        if (!page.dirty)
+            return;
+        let offset = 0;
+        while (offset < pageBytes) {
+            this.signal.throwIfAborted();
+            const count = await this.descriptor.write(page.bytes.subarray(offset), number * pageBytes + offset, { signal: this.signal });
+            this.signal.throwIfAborted();
+            if (!Number.isSafeInteger(count) || count <= 0 || count > pageBytes - offset)
+                throw new FsError("EIO");
+            offset += count;
+        }
+        this.diskLength = Math.max(this.diskLength, (number + 1) * pageBytes);
+        page.dirty = false;
+    }
+    async page(number) {
+        this.signal.throwIfAborted();
+        const cached = this.pages.get(number);
+        if (cached) {
+            this.pages.delete(number);
+            this.pages.set(number, cached);
+            return cached;
+        }
+        let reusable;
+        if (this.pages.size === this.maxPages) {
+            if (!this.descriptor)
+                await this.spill();
+            const [oldNumber, oldPage] = this.pages.entries().next().value;
+            await this.flush(oldNumber, oldPage);
+            this.pages.delete(oldNumber);
+            reusable = oldPage;
+        }
+        // Flush owns the bytes until its awaited write completes. Reuse only then;
+        // zero new/unwritten ranges so the previous page cannot leak into them.
+        const page = reusable ?? { bytes: new Uint8Array(pageBytes), dirty: false };
+        if (reusable)
+            page.bytes.fill(0);
+        if (number * pageBytes < this.diskLength) {
+            let offset = 0;
+            while (offset < pageBytes) {
+                const count = await this.descriptor.read(page.bytes.subarray(offset), number * pageBytes + offset, { signal: this.signal });
+                this.signal.throwIfAborted();
+                if (!Number.isSafeInteger(count) || count <= 0 || count > pageBytes - offset)
+                    throw new FsError("EIO");
+                offset += count;
+            }
+        }
+        this.pages.set(number, page);
+        return page;
+    }
+    write(position, bytes) {
+        if (!Number.isSafeInteger(position) || position < 8 || position + bytes.length > this.end)
+            throw new RangeError("Invalid paged storage range");
+        return this.operation(async () => {
+            for (let offset = 0; offset < bytes.length;) {
+                const target = position + offset;
+                const page = await this.page(Math.floor(target / pageBytes));
+                const count = Math.min(bytes.length - offset, pageBytes - target % pageBytes);
+                page.bytes.set(bytes.subarray(offset, offset + count), target % pageBytes);
+                page.dirty = true;
+                offset += count;
+            }
+        });
+    }
+    async append(bytes) {
+        const position = this.allocate(bytes.length);
+        await this.write(position, bytes);
+        return position;
+    }
+    read(position, length) {
+        if (!Number.isSafeInteger(position) || position < 8 || !Number.isSafeInteger(length) || length < 0 || length > pageBytes || position + length > this.end)
+            throw new RangeError("Invalid paged storage range");
+        return this.operation(async () => {
+            const bytes = new Uint8Array(length);
+            for (let offset = 0; offset < length;) {
+                const source = position + offset;
+                const page = await this.page(Math.floor(source / pageBytes));
+                const count = Math.min(length - offset, pageBytes - source % pageBytes);
+                bytes.set(page.bytes.subarray(source % pageBytes, source % pageBytes + count), offset);
+                offset += count;
+            }
+            return bytes;
+        });
+    }
+    close() {
+        this.controller.abort(new FsError("ECANCELED"));
+        return this.closing ??= (async () => {
+            await this.active.catch(() => { });
+            this.pages.clear();
+            const descriptor = this.descriptor;
+            if (!descriptor)
+                return;
+            const cancellation = new FsError("ECANCELED");
+            try {
+                if (!this.unlinked) {
+                    const expected = this.initial ?? await descriptor.stat();
+                    await this.context.fs.removeFileConditional(this.path, { parent: this.parent, expected }).catch(error => {
+                        if (!isFsError(error) || error.code !== "ENOENT")
+                            throw error;
+                    });
+                }
+            }
+            finally {
+                // Conditional descriptors must discard their private staged writes, not
+                // publish the scratch data when the command retires its handle.
+                await descriptor.close({ signal: AbortSignal.abort(cancellation) }).catch(error => {
+                    if (error !== cancellation)
+                        throw error;
+                });
+            }
+        })();
+    }
+}
+/** Fixed-depth radix index: both dense and sparse 64-bit keys use bounded RAM. */
+export class IntegerTable {
+    storage;
+    maxEntries;
+    root = 0;
+    revision = 0;
+    branches = new Map();
+    cache = new Map();
+    constructor(storage, maxEntries = 4096) {
+        this.storage = storage;
+        this.maxEntries = maxEntries;
+        if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
+            throw new RangeError("Invalid integer table cache size");
+    }
+    async retain(key, value, dirty) {
+        if (this.cache.size === this.maxEntries && !this.cache.has(key)) {
+            const [oldKey, old] = this.cache.entries().next().value;
+            // Flush the bounded dirty window together, before the caller touches other
+            // stored data. One dirty leaf per insertion otherwise thrashes a page cache.
+            if (old.dirty)
+                for (const [key, entry] of this.cache)
+                    if (entry.dirty) {
+                        await this.persist(key, entry.value);
+                        entry.dirty = false;
+                    }
+            this.cache.delete(oldKey);
+        }
+        this.cache.delete(key);
+        this.cache.set(key, { value, dirty });
+    }
+    async get(key) {
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.cache.delete(key);
+            this.cache.set(key, cached);
+            return cached.value;
+        }
+        const value = await this.lookup(key);
+        if (value !== undefined)
+            await this.retain(key, value, false);
+        return value;
+    }
+    async set(key, value) {
+        if (key < 0n || key > 0xffffffffffffffffn || value < 0n || value >= 0xffffffffffffffffn)
+            throw new RangeError("Invalid storage integer table value");
+        this.revision++;
+        await this.retain(key, value, true);
+    }
+    /** Ordered replay with a fixed 16-level radix stack (at most 2 KiB of
+     * owned node bytes) and 128 output records. Batches avoid alternating sparse
+     * index reads with consumer writes on every record. Mutation is not permitted. */
+    async *entries(start = 0n, end = 0x10000000000000000n) {
+        if (start < 0n || start > end || end > 0x10000000000000000n)
+            throw new RangeError("Invalid integer table range");
+        if (start === end)
+            return;
+        const revision = this.revision;
+        const check = () => { if (revision !== this.revision)
+            throw new Error("Integer table changed during iteration"); };
+        for (const [key, entry] of this.cache)
+            if (entry.dirty) {
+                check();
+                await this.persist(key, entry.value);
+                check();
+                entry.dirty = false;
+            }
+        const storage = this.storage;
+        async function* visit(position, shift, prefix) {
+            check();
+            if (!position)
+                return;
+            const bytes = new Uint8Array(await storage.read(position, 128));
+            check();
+            if (bytes.length !== 128)
+                throw new RangeError("Truncated integer table node");
+            const node = new DataView(bytes.buffer);
+            for (let slot = 0; slot < 16; slot++) {
+                check();
+                const value = node.getBigUint64(slot * 8, true);
+                if (!value)
+                    continue;
+                const key = prefix | BigInt(slot) << shift;
+                if (key >= end || key + (1n << shift) <= start)
+                    continue;
+                if (shift === 0n)
+                    yield [key, value - 1n];
+                else
+                    yield* visit(Number(value), shift - 4n, key);
+            }
+        }
+        const batch = [];
+        for await (const entry of visit(this.root, 60n, 0n)) {
+            batch.push(entry);
+            if (batch.length === 128) {
+                for (const entry of batch) {
+                    check();
+                    yield entry;
+                }
+                batch.length = 0;
+            }
+        }
+        for (const entry of batch) {
+            check();
+            yield entry;
+        }
+        check();
+    }
+    /** Hot radix paths must not evict dirty leaf pages in a one-page backend. */
+    branch(key, shift, position) {
+        const prefix = key >> shift | 1n << (64n - shift);
+        const value = position ?? this.branches.get(prefix);
+        if (value !== undefined) {
+            this.branches.delete(prefix);
+            this.branches.set(prefix, value);
+            if (this.branches.size > 128)
+                this.branches.delete(this.branches.keys().next().value);
+        }
+        return value;
+    }
+    async lookup(key) {
+        let node = this.root;
+        for (let shift = 60n; shift >= 0n; shift -= 4n) {
+            if (!node)
+                return undefined;
+            const cached = shift === 0n ? undefined : this.branch(key, shift);
+            if (cached !== undefined) {
+                node = cached;
+                continue;
+            }
+            const slot = node + Number((key >> shift) & 15n) * 8;
+            const bytes = await this.storage.read(slot, 8);
+            const value = new DataView(bytes.buffer, bytes.byteOffset, 8).getBigUint64(0, true);
+            if (shift === 0n)
+                return value === 0n ? undefined : value - 1n;
+            node = Number(value);
+            if (node)
+                this.branch(key, shift, node);
+        }
+        return undefined;
+    }
+    async persist(key, value) {
+        if (!this.root)
+            this.root = this.storage.allocate(128);
+        let node = this.root;
+        for (let shift = 60n; shift >= 0n; shift -= 4n) {
+            const cached = shift === 0n ? undefined : this.branch(key, shift);
+            if (cached !== undefined) {
+                node = cached;
+                continue;
+            }
+            const slot = node + Number((key >> shift) & 15n) * 8;
+            const bytes = await this.storage.read(slot, 8);
+            const view = new DataView(bytes.buffer, bytes.byteOffset, 8);
+            if (shift === 0n) {
+                view.setBigUint64(0, value + 1n, true);
+                await this.storage.write(slot, bytes);
+                return;
+            }
+            let child = Number(view.getBigUint64(0, true));
+            if (!child) {
+                child = this.storage.allocate(128);
+                view.setBigUint64(0, BigInt(child), true);
+                await this.storage.write(slot, bytes);
+            }
+            node = child;
+            this.branch(key, shift, child);
+        }
+    }
+}