@optimystic/db-p2p-storage-fs 1.14.0 → 1.16.0

package/dist/src/file-batch-backend.js

@@ -0,0 +1,400 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { NODE_KV_NAMESPACES } from '@optimystic/db-p2p';
+import { createLogger } from './logger.js';
+import { FileWriteLog, assertFileWriteLogOptions, fileStoreIdentity, readFileIfExists } from './file-write-log.js';
+const log = createLogger('storage:file');
+// Built on first use rather than at module load, like every other `TextDecoder` in library source
+// (see NO_MODULE_SCOPE_TEXT_DECODER in eslint.config.js). Harmless on Node; kept uniform so the lint
+// rule needs no per-package exemption.
+let decoderInstance;
+const decoder = () => decoderInstance ??= new TextDecoder();
+// Colons are illegal in Windows filenames; encode them so action ids like
+// `tx:<hash>` and `stamp:<hash>` round-trip safely on all platforms.
+function encodeActionIdForFilename(actionId) {
+    return actionId.replace(/:/g, '%3A');
+}
+function decodeFilenameToActionId(filename) {
+    return filename.replace(/%3A/g, ':');
+}
+// A torn write leaves valid-prefix JSON cut off mid-token — JSON.parse throws
+// SyntaxError. Used as the "corrupt content → treat as missing" guard so a
+// crash-truncated file reads as absent (letting recover() make progress) instead
+// of surfacing a parse error forever. Only the JSON-valued stores use this; the
+// revisions store holds a bare ActionId string (not JSON) and is never guarded.
+// NOTE: every guarded read parses the JSON here (validate, discard) and the kernel's
+// decodeJson parses the same bytes AGAIN to build the value — 2× parse per get. The
+// guard is intrinsic to the backend's "corrupt→missing" contract (the kernel can't
+// express it), so it can't simply be dropped. Fine at current read volumes; if a read
+// path ever shows up hot, parse once and thread the parsed value through the backend.
+function isParseableJson(bytes) {
+    try {
+        JSON.parse(decoder().decode(bytes));
+        return true;
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return false;
+        throw err;
+    }
+}
+const ACTION_SCOPED_DIRS = {
+    pending: 'pend',
+    transactions: 'actions',
+    materialized: 'blocks',
+};
+const METADATA_FILE = 'meta.json';
+const REVISIONS_DIR = 'revs';
+const PROOFS_DIR = 'proofs';
+/**
+ * The directories a block keeps its own records in, skipped when the block listing walks below a
+ * block directory (a block's directory can hold another block's: `.../Ledger/index/LedgerLatest`
+ * sits inside `.../Ledger/`).
+ * NOTE: a block id that extends another block's id with one of these segments (`x/revs`,
+ * `x/blocks/y`) lands inside block `x`'s own store directory — on write `x/revs` shares it outright,
+ * and the listing never yields either id. A limit of the raw-id layout; if such ids ever occur,
+ * encode block-id segments in the layout.
+ */
+const BLOCK_STORE_DIRS = new Set([...Object.values(ACTION_SCOPED_DIRS), REVISIONS_DIR, PROOFS_DIR]);
+/**
+ * The node's KV namespaces, which `FileKVStore` writes at the root when it shares this base path.
+ * Skipped by the listing so a KV key whose last segment is `meta` (stored as `meta.json`) is not
+ * read as a block, and so a startup scan does not walk `executed/`. A block id starting with one of
+ * these words already collides with the KV store on write (see `FileKVStore.keyToPath`).
+ */
+const ROOT_KV_NAMESPACES = new Set(NODE_KV_NAMESPACES);
+/**
+ * Filesystem {@link BatchBackend}: the six logical block-storage stores mapped to six paths under
+ * `basePath/<blockId>/` (`{meta.json,revs/,pend/,actions/,proofs/,blocks/}`), every batch committed
+ * through the directory's {@link FileWriteLog}. The directory tree is a deliberate,
+ * human-inspectable layout — it is NOT flattened into encoded-filename KV keys.
+ *
+ * `KvRawStorage` owns all JSON serialization, so this backend reads raw `Uint8Array` bytes and
+ * never does `JSON.stringify/parse` on values. What is fs-specific lives here: the path per
+ * {@link StoreKey}, the corrupt-content-as-missing read guard, colon-encoded action-id filenames
+ * with the legacy raw-colon read fallback and win32 guards, and the directory listings.
+ *
+ * Every operation opens the shared log first — on the first one: take the lock, replay, then
+ * serve — so no read ever sees a tree the log has not been replayed into. The log is acquired on
+ * that first operation rather than in the constructor, so an instance that is constructed and
+ * never used (one `withReadCache` dedupes away) holds no handle and no lock.
+ */
+export class FileBatchBackend {
+    options;
+    /** A committed batch's record is synced to the log by the deadline its commit allowed, or before the commit resolves; replay rebuilds the tree from it. */
+    durability = 'power-loss';
+    basePath;
+    identity;
+    log;
+    /** `options` are the directory log's checkpoint settings, applied when this is the first store to open it. */
+    constructor(basePath, options = {}) {
+        this.options = options;
+        assertFileWriteLogOptions(options);
+        this.basePath = path.resolve(basePath);
+        this.identity = fileStoreIdentity(basePath);
+    }
+    storeIdentity() {
+        return this.identity;
+    }
+    // --- reads ---
+    async get(key) {
+        await this.open();
+        switch (key.store) {
+            case 'metadata':
+                return this.readBytesIfExists(this.metadataPath(key.blockId), true);
+            // The revisions store value is a bare ActionId string (kernel `encodeActionId`, NOT JSON),
+            // so it is read WITHOUT the JSON guard — any bytes are a valid string and `decodeActionId`
+            // never throws.
+            // NOTE: because there is no guard here, a *torn* revision file reads back as a wrong
+            // (truncated) ActionId rather than as missing — unlike the JSON stores, which torn-read as
+            // undefined. A tree file can only be torn by a crash during its write, and that write's log
+            // record is durable before the write starts, so the next open's replay rewrites it whole.
+            // Only a file written by a build before the log can stay torn, and recover() re-derives
+            // revisions from the actions store anyway. If revisions ever move outside the log, add a
+            // checksum/length guard here.
+            case 'revisions':
+                return this.readBytesIfExists(this.revisionPath(key.blockId, key.rev), false);
+            // Keyed by (blockId, rev) like the revisions store, but JSON-valued like the action stores —
+            // so it takes the corrupt-content-as-missing guard the revisions store does not, and the
+            // filename carries no colon to encode. Deliberately no delete: a proof lives and dies with
+            // its revision record (see RawStoreDriver.getProof).
+            case 'proofs':
+                return this.readBytesIfExists(this.proofPath(key.blockId, key.rev), true);
+            case 'pending':
+            case 'transactions':
+            case 'materialized':
+                return this.readActionScopedBytes(this.actionScopedPath(key.store, key.blockId, key.actionId), this.actionScopedPath(key.store, key.blockId, key.actionId, false));
+        }
+    }
+    async rangeRevisions(blockId, lo, hi) {
+        await this.open();
+        // The fs backend has no cursor: walk the bounded [lo, hi] range rev-by-rev, reading each
+        // present rev. The range is caller-bounded, so this avoids listing an unbounded revs/ directory.
+        const results = [];
+        for (let rev = lo; rev <= hi; rev++) {
+            const value = await this.readBytesIfExists(this.revisionPath(blockId, rev), false);
+            if (value !== undefined) {
+                results.push([rev, value]);
+            }
+        }
+        return results;
+    }
+    async listPendingActionIds(blockId) {
+        await this.open();
+        const pendingPath = path.join(this.blockPath(blockId), ACTION_SCOPED_DIRS.pending);
+        // Only a genuinely-absent directory (ENOENT) maps to "no pendings". Any other error
+        // (EACCES, EIO, ENOTDIR, ...) must surface — swallowing it here would make listPendingActionIds
+        // silently report an empty directory, so pend's conflict detection would be skipped. Mirrors
+        // directoryByteSize's ENOENT-vs-other discrimination.
+        const files = await fs.readdir(pendingPath).catch((err) => {
+            if (err?.code === 'ENOENT')
+                return [];
+            log('listPendingActionIds readdir failed for %s - %o', blockId, err);
+            throw err;
+        });
+        const ids = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            const actionId = decodeFilenameToActionId(file.slice(0, -5));
+            // Accept every realistic action id: legacy UUIDs (`[0-9a-f-]`), consensus
+            // tx:/stamp: ids (base64url-encoded SHA-256, alphabet `[A-Za-z0-9_-]` — see
+            // db-core hashString, NOT lowercase hex), AND the bare-alphanumeric ids the
+            // cross-backend conformance suite uses (`a1`, `b1`, ...). This is deliberately
+            // broad-but-not-total: an id is any `[A-Za-z0-9_-]` string, optionally prefixed
+            // with `tx:`/`stamp:`. It is NOT a total accept — a file whose decoded name
+            // carries other punctuation (a dot, a space) is genuine junk in pend/ and is
+            // logged-and-skipped rather than surfaced as a phantom pending. The memory/db
+            // reference drivers key on the raw id and never see a filesystem name, so this
+            // filter is fs-only; it must not drop an id those backends would list, hence the
+            // widened class (an earlier hex-only class silently dropped real consensus ids —
+            // see `optimystic-filestorage-colon-actionid-windows`).
+            if (!/^(?:tx:|stamp:)?[A-Za-z0-9_-]+$/.test(actionId)) {
+                // Leave a breadcrumb rather than silently dropping: the .json + decode guard
+                // already excludes the `*.tmp` orphans an older build's atomic writer could leave, so
+                // anything reaching here is an unexpected filename a maintainer should see.
+                log('listPendingActionIds skipping unrecognized action-id file %s for %s', file, blockId);
+                continue;
+            }
+            ids.push(actionId);
+        }
+        return ids;
+    }
+    async *listBlockIds() {
+        await this.open();
+        // A block id is used raw as a relative path (see blockPath), so an id containing `/` lives in
+        // nested directories: `default/app/Ledger` is `basePath/default/app/Ledger/meta.json`. So the
+        // listing walks the whole tree and yields every directory holding a meta.json, its path
+        // relative to basePath rebuilt with `/` (never path.sep, so a win32 host yields the id it was
+        // given). Intermediate directories (`default/`, `default/app/`) hold no meta.json: descended,
+        // not listed. Files are never descended, so `write-ahead.log` and `store.lock` at the root
+        // are skipped by that alone.
+        //
+        // Gating on meta.json — existence (fs.access), not parse — enumerates exactly the population
+        // the metadata-keyed backends (sqlite/leveldb/indexeddb) get for free: every block with ANY
+        // durable metadata. That INCLUDES a pend-only block on the node path, because
+        // `BlockStorage.savePendingTransaction` seeds metadata first; a pend straight through this
+        // backend creates `<blockId>/pend/` without meta.json and is not listed. Do not "improve" this
+        // into a committed-revision filter: parsing every meta.json would turn a cheap sweep into a
+        // per-block read at startup (see the `listBlockIds` contract in i-raw-storage.ts). A
+        // torn/corrupt meta.json still counts as a key, exactly as a corrupt value would elsewhere.
+        //
+        // ENOENT (basePath not created yet, or a directory without meta.json) maps to "not there".
+        // Any OTHER readdir/access error surfaces: swallowing it would make the startup seed falsely
+        // report an empty store and under-protect data already on disk.
+        // NOTE: one readdir + one meta.json access per directory on the walk, yielded as it goes; if a
+        // store ever grows to millions of block directories and this becomes a startup-latency
+        // problem, page each listing (e.g. opendir cursor) — fine at current scale.
+        yield* this.walkBlockDirectories([]);
+    }
+    async *walkBlockDirectories(segments) {
+        const dir = path.join(this.basePath, ...segments);
+        const isBlock = segments.length > 0 && await this.hasMetadataFile(dir);
+        if (isBlock)
+            yield segments.join('/');
+        for (const name of await this.childDirectoryNames(dir)) {
+            if (isBlock && BLOCK_STORE_DIRS.has(name))
+                continue;
+            if (segments.length === 0 && ROOT_KV_NAMESPACES.has(name))
+                continue;
+            yield* this.walkBlockDirectories([...segments, name]);
+        }
+    }
+    async childDirectoryNames(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true })
+            .catch((err) => {
+            if (err?.code === 'ENOENT')
+                return [];
+            log('listBlockIds readdir failed for %s - %o', dir, err);
+            throw err;
+        });
+        return entries.filter(entry => entry.isDirectory()).map(entry => entry.name);
+    }
+    hasMetadataFile(dir) {
+        return fs.access(path.join(dir, METADATA_FILE))
+            .then(() => true)
+            .catch((err) => {
+            if (err?.code === 'ENOENT')
+                return false;
+            log('listBlockIds access failed for %s - %o', dir, err);
+            throw err;
+        });
+    }
+    /** The tree's bytes, the write-ahead log and the lock included: all of it is what the store occupies. */
+    async approximateBytesUsed() {
+        await this.open();
+        return this.directoryByteSize(this.basePath);
+    }
+    // --- the one write ---
+    /** One log record, synced within `syncWithinMs` (see `FileWriteLog.commit`); the `durable` returned is the log's. */
+    commit(entries, options) {
+        return this.shared().commit(entries.flatMap(entry => this.toLogEntries(entry)), options);
+    }
+    /** Hasten the log's sync. A backend that never committed holds no log, and so has nothing to hasten. */
+    sync() {
+        return this.log?.sync() ?? Promise.resolve();
+    }
+    async close() {
+        const shared = this.log;
+        this.log = undefined;
+        await shared?.release();
+    }
+    // --- the log ---
+    shared() {
+        return this.log ??= FileWriteLog.acquire(this.basePath, this.options);
+    }
+    open() {
+        return this.shared().open();
+    }
+    /**
+     * A put is one entry at the key's canonical path. A delete of an action-scoped record is that
+     * path's entry plus, off win32 and when the id carries a colon, the pre-encode raw-colon sibling's,
+     * so a deleted item cannot resurface through the read fallback in readActionScopedBytes — in the
+     * log, so a replay removes the sibling too.
+     *
+     * NOTE: that sibling entry names a path with a colon, which only a POSIX build writes; a log
+     * carrying one and moved unreplayed to a win32 machine replays it as an unlink of an NTFS
+     * stream path, where anything but ENOENT fails the open. A store is not moved across platforms
+     * mid-log today; if it ever is, have the replay skip a delete it cannot spell on this platform.
+     */
+    toLogEntries(entry) {
+        const relative = this.relativePath(entry.key);
+        if (entry.value !== undefined)
+            return [{ kind: 'put', path: relative, value: entry.value }];
+        const entries = [{ kind: 'delete', path: relative }];
+        const { key } = entry;
+        if (key.store === 'pending' || key.store === 'materialized') {
+            const raw = this.relativeActionScopedPath(key.store, key.blockId, key.actionId, false);
+            if (process.platform !== 'win32' && raw !== relative)
+                entries.push({ kind: 'delete', path: raw });
+        }
+        return entries;
+    }
+    // --- paths: relative with forward slashes for the log, absolute for reads ---
+    relativePath(key) {
+        switch (key.store) {
+            case 'metadata':
+                return `${key.blockId}/${METADATA_FILE}`;
+            case 'revisions':
+                return `${key.blockId}/${REVISIONS_DIR}/${key.rev}.json`;
+            case 'proofs':
+                return `${key.blockId}/${PROOFS_DIR}/${key.rev}.json`;
+            case 'pending':
+            case 'transactions':
+            case 'materialized':
+                return this.relativeActionScopedPath(key.store, key.blockId, key.actionId);
+        }
+    }
+    // `encoded` controls colon handling: writes and canonical reads use the percent-encoded filename
+    // (encoded = true); the legacy raw-colon fallback (see readActionScopedBytes) passes
+    // encoded = false to reach pre-encode POSIX files like `actions/tx:<hash>.json`.
+    relativeActionScopedPath(store, blockId, actionId, encoded = true) {
+        const filename = encoded ? encodeActionIdForFilename(actionId) : actionId;
+        return `${blockId}/${ACTION_SCOPED_DIRS[store]}/${filename}.json`;
+    }
+    blockPath(blockId) {
+        return path.join(this.basePath, blockId);
+    }
+    metadataPath(blockId) {
+        return path.join(this.blockPath(blockId), METADATA_FILE);
+    }
+    revisionPath(blockId, rev) {
+        return path.join(this.blockPath(blockId), REVISIONS_DIR, `${rev}.json`);
+    }
+    proofPath(blockId, rev) {
+        return path.join(this.blockPath(blockId), PROOFS_DIR, `${rev}.json`);
+    }
+    actionScopedPath(store, blockId, actionId, encoded = true) {
+        return path.join(this.basePath, this.relativeActionScopedPath(store, blockId, actionId, encoded));
+    }
+    // --- reads with the fs guards ---
+    // Reads an action-id-keyed file (JSON-valued) by its canonical (percent-encoded)
+    // path, falling back on a miss to the legacy raw-colon path written by pre-encode
+    // nodes (e.g. POSIX files literally named `actions/tx:<hash>.json`).
+    //
+    // Tradeoff: this reads legacy files in place and never renames them, so a
+    // store upgraded from a pre-encode node keeps mixed naming on disk. That is
+    // acceptable pre-1.0; a future migration sweep can normalize if desired. We
+    // deliberately do NOT migrate-on-read here — reads stay side-effect-free.
+    //
+    // win32 guard: a raw-colon path is not a benign miss on Windows — the colon
+    // is parsed as an NTFS alternate-data-stream separator and a read there can
+    // throw a non-ENOENT error rather than cleanly missing. Raw-colon files
+    // cannot have been written on win32 anyway, so we skip the fallback there
+    // (losing nothing) and swallow ALL fallback errors elsewhere, guaranteeing
+    // the fallback never surfaces a new throw to callers.
+    async readActionScopedBytes(encodedPath, rawPath) {
+        const hit = await this.readBytesIfExists(encodedPath, true);
+        if (hit !== undefined)
+            return hit;
+        if (process.platform === 'win32' || rawPath === encodedPath)
+            return undefined;
+        return fs.readFile(rawPath)
+            .then(bytes => (isParseableJson(bytes) ? bytes : undefined))
+            .catch(() => undefined);
+    }
+    // Reads a file's raw bytes. ENOENT → undefined. When `jsonGuard` is set, a
+    // present-but-corrupt file (JSON.parse fails — a torn write of a build before the log, or a
+    // crash mid-write that the next open's replay has not yet rewritten) is treated as "missing" so
+    // recover() and normal reads make progress instead of rethrowing forever. A real I/O error
+    // (permissions, EIO, EISDIR, ...) still throws — it must not be masked.
+    async readBytesIfExists(filePath, jsonGuard) {
+        const bytes = await readFileIfExists(filePath);
+        if (bytes === undefined)
+            return undefined;
+        if (jsonGuard && !isParseableJson(bytes)) {
+            log('readBytesIfExists: corrupt JSON at %s, treating as missing', filePath);
+            return undefined;
+        }
+        return bytes;
+    }
+    async directoryByteSize(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true })
+            .catch((err) => {
+            if (err?.code === 'ENOENT')
+                return [];
+            log('directoryByteSize readdir failed for %s - %o', dir, err);
+            return [];
+        });
+        let total = 0;
+        for (const entry of entries) {
+            const entryPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                total += await this.directoryByteSize(entryPath);
+            }
+            else if (entry.isFile()) {
+                const size = await fs.stat(entryPath)
+                    .then(st => st.size)
+                    .catch((err) => {
+                    if (err?.code === 'ENOENT')
+                        return 0;
+                    log('directoryByteSize stat failed for %s - %o', entryPath, err);
+                    return 0;
+                });
+                total += size;
+            }
+        }
+        return total;
+    }
+}
+//# sourceMappingURL=file-batch-backend.js.map

package/dist/src/file-batch-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-batch-backend.js","sourceRoot":"","sources":["../../src/file-batch-backend.ts"],"names":[],"mappings":"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"}

package/dist/src/file-kv-store.d.ts

@@ -1,13 +1,47 @@
-import type { IKVStore } from '@optimystic/db-p2p';
-/** Filesystem-backed IKVStore. Keys may contain `/` separators which become subdirectories. */
+import { type FlushOptions, type IKVStore, type WriteGroupOptions } from '@optimystic/db-p2p';
+import { type FileWriteLogOptions } from './file-write-log.js';
+/** The write group's `idleFlushMs` and the log's checkpoint settings; `setTimer` (test-only) arms both. */
+export type FileKVStoreOptions = WriteGroupOptions & FileWriteLogOptions;
+/**
+ * Filesystem-backed {@link IKVStore}: each key is the file `<basePath>/<key>.json`, a `/` in the key
+ * a subdirectory. Writes go through a {@link WriteGroup} over the directory's {@link FileWriteLog} —
+ * the same log a `FileRawStorage` over the same directory holds, so the two share one log, one
+ * lock and one checkpoint. A `set` or `delete` resolves into memory, served from there to `get` and
+ * `list`; `flush()` appends everything written since the last flush to the log as one record, synced
+ * before the flush resolves or within the window the flush allows (`FileWriteLog.commit`). A write
+ * no flush reaches is flushed by the group's idle timer.
+ *
+ * The constructor is synchronous and holds nothing: the log is acquired, the lock taken and the log
+ * replayed on the first operation. `close()` flushes what is still held and releases this store's
+ * reference to the log.
+ */
 export declare class FileKVStore implements IKVStore {
     private readonly basePath;
-    constructor(basePath: string);
+    private readonly options;
+    private readonly group;
+    private log;
+    constructor(basePath: string, options?: FileKVStoreOptions);
     get(key: string): Promise<string | undefined>;
     set(key: string, value: string): Promise<void>;
     delete(key: string): Promise<void>;
+    /**
+     * Every key under `prefix`, which names a directory: it ends in `/`, as every prefix the node
+     * lists by does. The tree's keys, plus those written and not yet flushed, less those deleted and
+     * not yet flushed.
+     */
     list(prefix: string): Promise<string[]>;
+    /** Make every write resolved before this call durable, at once or within `options.withinMs`: one log record, synced by then. The contract is `RawStoreDriver.flush`'s. */
+    flush(options?: FlushOptions): Promise<void>;
+    /** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
+    whenDurable(): Promise<void>;
+    /** Flush what is still held, then release this store's reference to the directory's log. */
+    close(): Promise<void>;
+    private commit;
+    private shared;
+    private open;
     private listRecursive;
+    /** The key's file relative to the store's directory, forward slashes, as the log records it. */
+    private keyToRelative;
     private keyToPath;
 }
 //# sourceMappingURL=file-kv-store.d.ts.map

package/dist/src/file-kv-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-kv-store.d.ts","sourceRoot":"","sources":["../../src/file-kv-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnD,+FAA+F;AAC/F,qBAAa,WAAY,YAAW,QAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAEvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAS7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAS/B,aAAa;IAkB3B,OAAO,CAAC,SAAS;CAUjB"}
+{"version":3,"file":"file-kv-store.d.ts","sourceRoot":"","sources":["../../src/file-kv-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmC,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAgD,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC7K,OAAO,EAA6D,KAAK,mBAAmB,EAAsB,MAAM,qBAAqB,CAAC;AAE9I,2GAA2G;AAC3G,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAQzE;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,YAAW,QAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,GAAG,CAA2B;gBAE1B,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAWxD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQ7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;;OAIG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAc7C,0KAA0K;IAC1K,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,uIAAuI;IACvI,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,4FAA4F;IACtF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,IAAI;YAIE,aAAa;IAiB3B,gGAAgG;IAChG,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,SAAS;CAWjB"}

package/dist/src/file-kv-store.js

@@ -1,41 +1,103 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
-import { atomicWriteFile } from './atomic-write.js';
-/** Filesystem-backed IKVStore. Keys may contain `/` separators which become subdirectories. */
+import { WriteGroup } from '@optimystic/db-p2p';
+import { FileWriteLog, assertFileWriteLogOptions, readFileIfExists } from './file-write-log.js';
+const encoder = new TextEncoder();
+// Built on first use rather than at module load, like every other `TextDecoder` in library source
+// (see NO_MODULE_SCOPE_TEXT_DECODER in eslint.config.js).
+let decoderInstance;
+const decoder = () => decoderInstance ??= new TextDecoder();
+/**
+ * Filesystem-backed {@link IKVStore}: each key is the file `<basePath>/<key>.json`, a `/` in the key
+ * a subdirectory. Writes go through a {@link WriteGroup} over the directory's {@link FileWriteLog} —
+ * the same log a `FileRawStorage` over the same directory holds, so the two share one log, one
+ * lock and one checkpoint. A `set` or `delete` resolves into memory, served from there to `get` and
+ * `list`; `flush()` appends everything written since the last flush to the log as one record, synced
+ * before the flush resolves or within the window the flush allows (`FileWriteLog.commit`). A write
+ * no flush reaches is flushed by the group's idle timer.
+ *
+ * The constructor is synchronous and holds nothing: the log is acquired, the lock taken and the log
+ * replayed on the first operation. `close()` flushes what is still held and releases this store's
+ * reference to the log.
+ */
 export class FileKVStore {
     basePath;
-    constructor(basePath) {
-        this.basePath = basePath;
+    options;
+    group;
+    log;
+    constructor(basePath, options = {}) {
+        assertFileWriteLogOptions(options);
+        this.basePath = path.resolve(basePath);
+        this.options = options;
+        this.group = new WriteGroup(key => key, {
+            commit: (entries, commitOptions) => this.commit(entries, commitOptions),
+            // A store that never committed holds no log, and so has nothing to hasten.
+            sync: () => this.log?.sync() ?? Promise.resolve(),
+        }, options);
     }
     async get(key) {
-        try {
-            return await fs.readFile(this.keyToPath(key), 'utf-8');
-        }
-        catch (err) {
-            if (err?.code === 'ENOENT')
-                return undefined;
-            throw err;
-        }
+        const held = this.group.lookup(key);
+        if (held !== undefined)
+            return held === null ? undefined : decoder().decode(held);
+        await this.open();
+        const bytes = await readFileIfExists(this.keyToPath(key));
+        return bytes === undefined ? undefined : decoder().decode(bytes);
     }
     async set(key, value) {
-        await atomicWriteFile(this.keyToPath(key), value);
+        this.group.put(key, encoder.encode(value));
     }
     async delete(key) {
+        this.group.delete(key);
+    }
+    /**
+     * Every key under `prefix`, which names a directory: it ends in `/`, as every prefix the node
+     * lists by does. The tree's keys, plus those written and not yet flushed, less those deleted and
+     * not yet flushed.
+     */
+    async list(prefix) {
+        // Taken before awaiting the tree: a commit resolving meanwhile drops entries from the overlay
+        // that the listing below may have been taken without.
+        const held = [...this.group.entries()].filter(([key]) => key.startsWith(prefix));
+        await this.open();
+        const keys = new Set();
+        await this.listRecursive(path.join(this.basePath, ...prefix.split('/').filter(Boolean)), prefix, keys);
+        for (const [key, value] of held) {
+            if (value === null)
+                keys.delete(key);
+            else
+                keys.add(key);
+        }
+        return [...keys];
+    }
+    /** Make every write resolved before this call durable, at once or within `options.withinMs`: one log record, synced by then. The contract is `RawStoreDriver.flush`'s. */
+    flush(options) {
+        return this.group.flush(options);
+    }
+    /** Resolves once every write covered by a flush that resolved before this call is durable; `RawStoreDriver.whenDurable`'s contract. */
+    whenDurable() {
+        return this.group.whenDurable();
+    }
+    /** Flush what is still held, then release this store's reference to the directory's log. */
+    async close() {
         try {
-            await fs.unlink(this.keyToPath(key));
+            await this.group.close();
         }
-        catch (err) {
-            if (err?.code !== 'ENOENT')
-                throw err;
+        finally {
+            const shared = this.log;
+            this.log = undefined;
+            await shared?.release();
         }
     }
-    async list(prefix) {
-        // prefix like "coordinator/" → scan basePath/coordinator/ directory
-        const parts = prefix.split('/').filter(Boolean);
-        const dirPath = path.join(this.basePath, ...parts);
-        const results = [];
-        await this.listRecursive(dirPath, prefix, results);
-        return results;
+    commit(entries, options) {
+        return this.shared().commit(entries.map(({ key, value }) => value === undefined
+            ? { kind: 'delete', path: this.keyToRelative(key) }
+            : { kind: 'put', path: this.keyToRelative(key), value }), options);
+    }
+    shared() {
+        return this.log ??= FileWriteLog.acquire(this.basePath, this.options);
+    }
+    open() {
+        return this.shared().open();
     }
     async listRecursive(dirPath, prefix, results) {
         let entries;
@@ -49,22 +111,26 @@ export class FileKVStore {
         }
         for (const entry of entries) {
             if (entry.isDirectory()) {
-                const subPrefix = prefix + entry.name + '/';
-                await this.listRecursive(path.join(dirPath, entry.name), subPrefix, results);
+                await this.listRecursive(path.join(dirPath, entry.name), prefix + entry.name + '/', results);
             }
             else if (entry.isFile() && entry.name.endsWith('.json')) {
-                results.push(prefix + entry.name.slice(0, -5));
+                results.add(prefix + entry.name.slice(0, -5));
             }
         }
     }
+    /** The key's file relative to the store's directory, forward slashes, as the log records it. */
+    keyToRelative(key) {
+        return `${key}.json`;
+    }
     keyToPath(key) {
-        // NOTE: `/`-separated keys become nested dirs, so a key's first segment shares
-        // the top-level namespace with FileRawStorage's <blockId>/ dirs. Safe today
-        // because block ids are content hashes; if a KV key's first segment could ever
-        // equal a block id, give the two stores separate basePaths (see README Usage).
-        // FileRawStorage.listBlockIds also yields only root directories holding a meta.json, so a
-        // KV directory such as the under-replication ledger's `under-replicated/` is never
-        // enumerated as a block. Its bytes do count toward FileRawStorage.getApproximateBytesUsed.
+        // NOTE: `/`-separated keys become nested dirs, so a key's first segment shares the top-level
+        // namespace with FileRawStorage's <blockId>/ dirs. Safe while no block id's first segment
+        // (a block id containing `/` nests too) equals a key's first segment — the node's keys all start with a fixed word (`under-replicated`,
+        // `coordinator`, `participant`, `executed`) — and if one ever could, give the two stores
+        // separate basePaths (see README Usage). FileRawStorage.listBlockIds walks the tree but skips
+        // these root namespaces (db-p2p's NODE_KV_NAMESPACES — a new namespace must be added there),
+        // so a KV key whose last segment is `meta` is never enumerated as a block. Their bytes do
+        // count toward FileRawStorage.getApproximateBytesUsed.
         return path.join(this.basePath, ...key.split('/')) + '.json';
     }
 }