@seanhogg/builderforce-memory 2026.9.34 → 2026.10.2

package/dist/storage/idbAdapter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * storage/idbAdapter.ts – Durable browser/IndexedDB implementation of the
+ * storage port.
+ *
+ * Two properties the legacy MemoryStore write helpers did NOT have (M02):
+ *   1. `transact()` resolves only on `tx.oncomplete` — the durable commit point —
+ *      and rejects on `tx.onabort`. Request-level `onsuccess` is used internally
+ *      to chain operations, never to signal durability.
+ *   2. One `transact()` call is one unit of work spanning facts, tombstones,
+ *      journal and meta, so a fact and its sync journal entry commit together.
+ *
+ * Schema (database version 3):
+ *   - 'facts'      keyPath 'id'    — StoredFactRecord (scoped composite id)
+ *       index 'byKey' on 'key'           — key lookup without a scan
+ *       index 'byTag' on 'tags' multiEntry — tag lookup without a scan
+ *   - 'tombstones' keyPath 'id'    — TombstoneRecord
+ *   - 'journal'    keyPath 'opId'  — JournalEntry (the sync journal)
+ *   - 'meta'       keyPath 'key'   — MetaCounters (durable seq / revision / opSeq)
+ *   - 'weights'    (out-of-line)   — legacy weight blob store, retained
+ *
+ * Version 3 adds the key and tag indexes only. Existing fact records, including
+ * their timestamps and TTLs, are not rewritten.
+ *
+ * Version-1 databases (facts keyed by the raw key, no journal) are migrated in
+ * the upgrade transaction: records are copied to the new 'id'-keyed store with
+ * the unbound scope, their seq preserved, revision 1, and no pending sync state.
+ *
+ * Cross-context consistency (M05): when BroadcastChannel is available the
+ * adapter publishes a change note after every committed write and delivers
+ * foreign notes to subscribers, so sibling tabs/windows invalidate their caches
+ * instead of serving stale recalls. The channel opens lazily — on the first
+ * publish, or once the database is open for a subscriber — and is `unref()`ed
+ * where supported (Node), so a store that is never closed cannot keep the
+ * process alive.
+ */
+import { type ConsistencyNote, type FactStoragePort, type MetaCounters, type StorageStoreName, type StorageTransaction } from './types.js';
+declare const FACTS_STORE = "facts";
+declare const TOMBSTONES_STORE = "tombstones";
+declare const JOURNAL_STORE = "journal";
+declare const META_STORE = "meta";
+declare const WEIGHTS_STORE = "weights";
+declare const DB_VERSION = 3;
+declare const ALL_STORES: StorageStoreName[];
+export interface IdbStorageAdapterOptions {
+    /** IDBFactory override (tests, non-standard hosts). NOT a durability shim. */
+    idbFactory?: IDBFactory;
+    /** Identity of this context for cross-context notes. Default: random. */
+    contextId?: string;
+    /** BroadcastChannel override (tests). Default: global, when present. */
+    channelFactory?: (name: string) => BroadcastChannelLike | undefined;
+}
+/** Minimal BroadcastChannel surface (Node's worker_threads channel satisfies it too). */
+export interface BroadcastChannelLike {
+    postMessage(message: unknown): void;
+    close(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    /** Node only: stop this channel from keeping the event loop alive. */
+    unref?(): void;
+}
+export declare class IdbStorageAdapter implements FactStoragePort {
+    private readonly _dbName;
+    readonly kind: "indexedDB";
+    private readonly _idb;
+    private readonly _contextId;
+    private readonly _channelFactory;
+    private _db;
+    private _channel;
+    private _channelFailed;
+    private readonly _listeners;
+    constructor(_dbName: string, opts?: IdbStorageAdapterOptions);
+    /** Identity of this context, stamped onto change notes and opIds. */
+    get contextId(): string;
+    private _open;
+    /**
+     * One unit of work: runs `fn` inside a single IndexedDB transaction and
+     * resolves ONLY on `tx.oncomplete`. If `fn` throws, the transaction is
+     * aborted so no partial writes survive; if the browser aborts the
+     * transaction (quota, corruption, crash mid-commit) the promise rejects.
+     */
+    transact<T>(stores: StorageStoreName[], mode: 'readonly' | 'readwrite', fn: (tx: StorageTransaction) => Promise<T> | T): Promise<T>;
+    publish(note: ConsistencyNote): void;
+    /**
+     * Registers `listener` for foreign change notes. The channel itself opens
+     * when the database does (or on the first publish), not here: subscribing
+     * from a constructor must not open a global channel.
+     */
+    subscribe(listener: (note: ConsistencyNote) => void): () => void;
+    private _ensureChannel;
+    close(): void;
+}
+export { ALL_STORES, FACTS_STORE, TOMBSTONES_STORE, JOURNAL_STORE, META_STORE, WEIGHTS_STORE, DB_VERSION };
+export type { MetaCounters };
+//# sourceMappingURL=idbAdapter.d.ts.map

package/dist/storage/idbAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idbAdapter.d.ts","sourceRoot":"","sources":["../../src/storage/idbAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAKH,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EAE1B,MAAM,YAAY,CAAC;AAEpB,QAAA,MAAM,WAAW,UAAe,CAAC;AACjC,QAAA,MAAM,gBAAgB,eAAe,CAAC;AACtC,QAAA,MAAM,aAAa,YAAe,CAAC;AACnC,QAAA,MAAM,UAAU,SAAe,CAAC;AAChC,QAAA,MAAM,aAAa,YAAe,CAAC;AACnC,QAAA,MAAM,UAAU,IAAU,CAAC;AAE3B,QAAA,MAAM,UAAU,EAAE,gBAAgB,EAA+D,CAAC;AAElG,MAAM,WAAW,wBAAwB;IACrC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,oBAAoB,GAAG,SAAS,CAAC;CACvE;AAED,yFAAyF;AACzF,MAAM,WAAW,oBAAoB;IACjC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;IACd,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACvD,sEAAsE;IACtE,KAAK,CAAC,IAAI,IAAI,CAAC;CAClB;AA4CD,qBAAa,iBAAkB,YAAW,eAAe;IAYjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX5B,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAErC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmE;IACnG,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8C;gBAGpD,OAAO,EAAE,MAAM,EAChC,IAAI,GAAE,wBAA6B;IAOvC,qEAAqE;IACrE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,OAAO,CAAC,KAAK;IAoCb;;;;;OAKG;IACG,QAAQ,CAAC,CAAC,EACZ,MAAM,EAAE,gBAAgB,EAAE,EAC1B,IAAI,EAAE,UAAU,GAAG,WAAW,EAC9B,EAAE,EAAE,CAAC,EAAE,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC/C,OAAO,CAAC,CAAC,CAAC;IAmDb,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAUpC;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAMhE,OAAO,CAAC,cAAc;IAqBtB,KAAK,IAAI,IAAI;CAMhB;AAmFD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AAC3G,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/storage/idbAdapter.js

@@ -0,0 +1,311 @@
+/**
+ * storage/idbAdapter.ts – Durable browser/IndexedDB implementation of the
+ * storage port.
+ *
+ * Two properties the legacy MemoryStore write helpers did NOT have (M02):
+ *   1. `transact()` resolves only on `tx.oncomplete` — the durable commit point —
+ *      and rejects on `tx.onabort`. Request-level `onsuccess` is used internally
+ *      to chain operations, never to signal durability.
+ *   2. One `transact()` call is one unit of work spanning facts, tombstones,
+ *      journal and meta, so a fact and its sync journal entry commit together.
+ *
+ * Schema (database version 3):
+ *   - 'facts'      keyPath 'id'    — StoredFactRecord (scoped composite id)
+ *       index 'byKey' on 'key'           — key lookup without a scan
+ *       index 'byTag' on 'tags' multiEntry — tag lookup without a scan
+ *   - 'tombstones' keyPath 'id'    — TombstoneRecord
+ *   - 'journal'    keyPath 'opId'  — JournalEntry (the sync journal)
+ *   - 'meta'       keyPath 'key'   — MetaCounters (durable seq / revision / opSeq)
+ *   - 'weights'    (out-of-line)   — legacy weight blob store, retained
+ *
+ * Version 3 adds the key and tag indexes only. Existing fact records, including
+ * their timestamps and TTLs, are not rewritten.
+ *
+ * Version-1 databases (facts keyed by the raw key, no journal) are migrated in
+ * the upgrade transaction: records are copied to the new 'id'-keyed store with
+ * the unbound scope, their seq preserved, revision 1, and no pending sync state.
+ *
+ * Cross-context consistency (M05): when BroadcastChannel is available the
+ * adapter publishes a change note after every committed write and delivers
+ * foreign notes to subscribers, so sibling tabs/windows invalidate their caches
+ * instead of serving stale recalls. The channel opens lazily — on the first
+ * publish, or once the database is open for a subscriber — and is `unref()`ed
+ * where supported (Node), so a store that is never closed cannot keep the
+ * process alive.
+ */
+import { FACT_KEY_INDEX, FACT_TAG_INDEX, MemoryStorageError, scopedRecordId, } from './types.js';
+const FACTS_STORE = 'facts';
+const TOMBSTONES_STORE = 'tombstones';
+const JOURNAL_STORE = 'journal';
+const META_STORE = 'meta';
+const WEIGHTS_STORE = 'weights';
+const DB_VERSION = 3;
+const ALL_STORES = [FACTS_STORE, TOMBSTONES_STORE, JOURNAL_STORE, META_STORE];
+function reqToPromise(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error('IndexedDB request failed'));
+    });
+}
+class IdbStorageTransaction {
+    _tx;
+    constructor(_tx) {
+        this._tx = _tx;
+    }
+    async get(store, id) {
+        return reqToPromise(this._tx.objectStore(store).get(id));
+    }
+    async getAll(store) {
+        return reqToPromise(this._tx.objectStore(store).getAll());
+    }
+    async put(store, value) {
+        await reqToPromise(this._tx.objectStore(store).put(value));
+    }
+    async delete(store, id) {
+        await reqToPromise(this._tx.objectStore(store).delete(id));
+    }
+    async getByIndex(store, indexName, query) {
+        const objectStore = this._tx.objectStore(store);
+        // Legacy databases opened before the index existed fall through to a scan.
+        if (!objectStore.indexNames.contains(indexName))
+            return undefined;
+        return reqToPromise(objectStore.index(indexName).getAll(query));
+    }
+}
+export class IdbStorageAdapter {
+    _dbName;
+    kind = 'indexedDB';
+    _idb;
+    _contextId;
+    _channelFactory;
+    _db = null;
+    _channel = null;
+    _channelFailed = false;
+    _listeners = new Set();
+    constructor(_dbName, opts = {}) {
+        this._dbName = _dbName;
+        this._idb = opts.idbFactory;
+        this._contextId = opts.contextId ?? `ctx-${Math.random().toString(36).slice(2)}-${Date.now().toString(36)}`;
+        this._channelFactory = opts.channelFactory;
+    }
+    /** Identity of this context, stamped onto change notes and opIds. */
+    get contextId() {
+        return this._contextId;
+    }
+    _open() {
+        if (this._db)
+            return Promise.resolve(this._db);
+        return new Promise((resolve, reject) => {
+            const factory = this._idb ?? (typeof indexedDB !== 'undefined' ? indexedDB : undefined);
+            if (!factory) {
+                reject(new MemoryStorageError('STORAGE_UNAVAILABLE', 'IndexedDB is not available in this environment. For durable Node.js storage use NodeFileStorageAdapter; fake-indexeddb is a test double, not durable storage.'));
+                return;
+            }
+            const req = factory.open(this._dbName, DB_VERSION);
+            req.onupgradeneeded = (e) => {
+                const db = e.target.result;
+                const tx = e.target.transaction;
+                migrateSchema(db, tx, e.oldVersion);
+            };
+            req.onsuccess = () => {
+                this._db = req.result;
+                // Subscribers registered before the first open start listening now.
+                if (this._listeners.size > 0)
+                    this._ensureChannel();
+                resolve(req.result);
+            };
+            /* istanbul ignore next -- IDB open onerror fires only on storage faults; not reproducible with fake-indexeddb */
+            req.onerror = () => reject(new MemoryStorageError('STORAGE_UNAVAILABLE', `Failed to open IndexedDB "${this._dbName}": ${req.error?.message ?? 'unknown'}`, req.error));
+        });
+    }
+    /**
+     * One unit of work: runs `fn` inside a single IndexedDB transaction and
+     * resolves ONLY on `tx.oncomplete`. If `fn` throws, the transaction is
+     * aborted so no partial writes survive; if the browser aborts the
+     * transaction (quota, corruption, crash mid-commit) the promise rejects.
+     */
+    async transact(stores, mode, fn) {
+        const db = await this._open();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(err instanceof MemoryStorageError ? err : new MemoryStorageError('STORAGE_ABORTED', `Transaction aborted on "${this._dbName}": ${err instanceof Error ? err.message : String(err)}`, err));
+            };
+            let tx;
+            try {
+                tx = db.transaction(stores, mode);
+            }
+            catch (err) {
+                fail(err);
+                return;
+            }
+            let result;
+            tx.oncomplete = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(result);
+            };
+            /* istanbul ignore next -- abort fires only on storage faults or explicit abort; fault path not reproducible with fake-indexeddb */
+            tx.onabort = () => fail(tx.error ?? new Error('transaction aborted'));
+            /* istanbul ignore next -- request errors surface through the per-request rejections and the abort handler */
+            tx.onerror = () => { };
+            const stx = new IdbStorageTransaction(tx);
+            Promise.resolve()
+                .then(() => fn(stx))
+                .then((r) => { result = r; })
+                .catch((err) => {
+                // The unit of work failed — abort so facts/journal/tombstones
+                // never commit partially (M02), then surface the ORIGINAL error.
+                try {
+                    tx.abort();
+                }
+                catch { /* already finished */ }
+                if (!settled) {
+                    settled = true;
+                    reject(err);
+                }
+            });
+        });
+    }
+    // ── Cross-context consistency seam (M05) ──────────────────────────────────
+    publish(note) {
+        const channel = this._ensureChannel();
+        if (!channel)
+            return;
+        try {
+            channel.postMessage(note);
+        }
+        catch {
+            // A dead channel must never fail a committed write.
+        }
+    }
+    /**
+     * Registers `listener` for foreign change notes. The channel itself opens
+     * when the database does (or on the first publish), not here: subscribing
+     * from a constructor must not open a global channel.
+     */
+    subscribe(listener) {
+        this._listeners.add(listener);
+        if (this._db)
+            this._ensureChannel();
+        return () => this._listeners.delete(listener);
+    }
+    _ensureChannel() {
+        if (this._channel || this._channelFailed)
+            return this._channel;
+        try {
+            const factory = this._channelFactory ?? defaultChannelFactory;
+            const channel = factory(`bf-memory:${this._dbName}`);
+            if (channel) {
+                channel.onmessage = (e) => {
+                    const note = e.data;
+                    if (!note || note.kind !== 'facts-changed')
+                        return;
+                    if (note.origin === this._contextId)
+                        return; // our own write
+                    for (const l of this._listeners)
+                        l(note);
+                };
+                channel.unref?.();
+                this._channel = channel;
+            }
+        }
+        catch {
+            this._channelFailed = true;
+        }
+        return this._channel;
+    }
+    close() {
+        this._channel?.close();
+        this._channel = null;
+        this._db?.close();
+        this._db = null;
+    }
+}
+function defaultChannelFactory(name) {
+    if (typeof BroadcastChannel === 'undefined')
+        return undefined;
+    return new BroadcastChannel(name);
+}
+// ── Schema migration ──────────────────────────────────────────────────────────
+function ensureFactIndexes(store) {
+    if (!store.indexNames.contains(FACT_KEY_INDEX)) {
+        store.createIndex(FACT_KEY_INDEX, 'key', { unique: false });
+    }
+    if (!store.indexNames.contains(FACT_TAG_INDEX)) {
+        // One index row per tag, so recallByTag is a lookup rather than a scan.
+        store.createIndex(FACT_TAG_INDEX, 'tags', { unique: false, multiEntry: true });
+    }
+}
+function migrateSchema(db, tx, oldVersion) {
+    if (oldVersion < 1) {
+        // Fresh database.
+        const facts = db.createObjectStore(FACTS_STORE, { keyPath: 'id' });
+        ensureFactIndexes(facts);
+        db.createObjectStore(WEIGHTS_STORE);
+    }
+    else if (oldVersion < 2 && db.objectStoreNames.contains(FACTS_STORE)) {
+        // v1 → v2: facts were keyed by the raw key; move them onto the scoped
+        // record shape in the unbound partition. Copy out, drop, recreate, refill —
+        // all inside the upgrade transaction, so a crash here rolls everything back.
+        const legacy = [];
+        const cursorReq = tx.objectStore(FACTS_STORE).openCursor();
+        cursorReq.onsuccess = () => {
+            const cursor = cursorReq.result;
+            if (cursor) {
+                legacy.push(cursor.value);
+                cursor.continue();
+            }
+            else {
+                db.deleteObjectStore(FACTS_STORE);
+                const store = db.createObjectStore(FACTS_STORE, { keyPath: 'id' });
+                ensureFactIndexes(store);
+                for (const e of legacy) {
+                    const record = {
+                        id: scopedRecordId(undefined, e.key),
+                        key: e.key,
+                        scope: {},
+                        content: e.content,
+                        timestamp: e.timestamp,
+                        seq: e.seq ?? 0,
+                        revision: 1,
+                        opId: 'migrated:v1',
+                        ttlMs: e.ttlMs,
+                        type: e.type,
+                        tags: e.tags,
+                        importance: e.importance,
+                        pendingSync: false,
+                    };
+                    store.put(record);
+                }
+            }
+        };
+    }
+    else if (!db.objectStoreNames.contains(FACTS_STORE)) {
+        const facts = db.createObjectStore(FACTS_STORE, { keyPath: 'id' });
+        ensureFactIndexes(facts);
+    }
+    else if (oldVersion < 3) {
+        // v2 → v3: add key/tag indexes. Do not rewrite records — timestamps,
+        // TTLs, tags and content already on disk must survive the upgrade.
+        ensureFactIndexes(tx.objectStore(FACTS_STORE));
+    }
+    if (!db.objectStoreNames.contains(WEIGHTS_STORE)) {
+        db.createObjectStore(WEIGHTS_STORE);
+    }
+    if (!db.objectStoreNames.contains(TOMBSTONES_STORE)) {
+        db.createObjectStore(TOMBSTONES_STORE, { keyPath: 'id' });
+    }
+    if (!db.objectStoreNames.contains(JOURNAL_STORE)) {
+        db.createObjectStore(JOURNAL_STORE, { keyPath: 'opId' });
+    }
+    if (!db.objectStoreNames.contains(META_STORE)) {
+        db.createObjectStore(META_STORE, { keyPath: 'key' });
+    }
+}
+export { ALL_STORES, FACTS_STORE, TOMBSTONES_STORE, JOURNAL_STORE, META_STORE, WEIGHTS_STORE, DB_VERSION };
+//# sourceMappingURL=idbAdapter.js.map

package/dist/storage/idbAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idbAdapter.js","sourceRoot":"","sources":["../../src/storage/idbAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACH,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,cAAc,GAOjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,GAAQ,OAAO,CAAC;AACjC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AACtC,MAAM,aAAa,GAAM,SAAS,CAAC;AACnC,MAAM,UAAU,GAAS,MAAM,CAAC;AAChC,MAAM,aAAa,GAAM,SAAS,CAAC;AACnC,MAAM,UAAU,GAAS,CAAC,CAAC;AAE3B,MAAM,UAAU,GAAuB,CAAC,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;AA+BlG,SAAS,YAAY,CAAI,GAAkB;IACvC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,GAAG,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,GAAG,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,qBAAqB;IACM;IAA7B,YAA6B,GAAmB;QAAnB,QAAG,GAAH,GAAG,CAAgB;IAAG,CAAC;IAEpD,KAAK,CAAC,GAAG,CAAI,KAAuB,EAAE,EAAU;QAC5C,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAA8B,CAAC,CAAC;IAC1F,CAAC;IACD,KAAK,CAAC,MAAM,CAAI,KAAuB;QACnC,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,MAAM,EAAqB,CAAC,CAAC;IACjF,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,KAAuB,EAAE,KAAc;QAC7C,MAAM,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,KAAuB,EAAE,EAAU;QAC5C,MAAM,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,UAAU,CAAI,KAAuB,EAAE,SAAiB,EAAE,KAAa;QACzE,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAChD,2EAA2E;QAC3E,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAClE,OAAO,YAAY,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAoB,CAAC,CAAC;IACvF,CAAC;CACJ;AAED,MAAM,OAAO,iBAAiB;IAYL;IAXZ,IAAI,GAAG,WAAoB,CAAC;IAEpB,IAAI,CAAyB;IAC7B,UAAU,CAAS;IACnB,eAAe,CAAmE;IAC3F,GAAG,GAAuB,IAAI,CAAC;IAC/B,QAAQ,GAAgC,IAAI,CAAC;IAC7C,cAAc,GAAG,KAAK,CAAC;IACd,UAAU,GAAG,IAAI,GAAG,EAAmC,CAAC;IAEzE,YACqB,OAAe,EAChC,OAAiC,EAAE;QADlB,YAAO,GAAP,OAAO,CAAQ;QAGhC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAC5G,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC;IAC/C,CAAC;IAED,qEAAqE;IACrE,IAAI,SAAS;QACT,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAEO,KAAK;QACT,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAE/C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACxF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACX,MAAM,CAAC,IAAI,kBAAkB,CACzB,qBAAqB,EACrB,+JAA+J,CAClK,CAAC,CAAC;gBACH,OAAO;YACX,CAAC;YAED,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAEnD,GAAG,CAAC,eAAe,GAAG,CAAC,CAAC,EAAE,EAAE;gBACxB,MAAM,EAAE,GAAI,CAAC,CAAC,MAA2B,CAAC,MAAM,CAAC;gBACjD,MAAM,EAAE,GAAI,CAAC,CAAC,MAA2B,CAAC,WAAY,CAAC;gBACvD,aAAa,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;YACxC,CAAC,CAAC;YAEF,GAAG,CAAC,SAAS,GAAG,GAAG,EAAE;gBACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;gBACtB,oEAAoE;gBACpE,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC;oBAAE,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC,CAAC;YACF,iHAAiH;YACjH,GAAG,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAC7C,qBAAqB,EACrB,6BAA6B,IAAI,CAAC,OAAO,MAAM,GAAG,CAAC,KAAK,EAAE,OAAO,IAAI,SAAS,EAAE,EAChF,GAAG,CAAC,KAAK,CACZ,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CACV,MAA0B,EAC1B,IAA8B,EAC9B,EAA8C;QAE9C,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACtC,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,IAAI,GAAG,CAAC,GAAY,EAAE,EAAE;gBAC1B,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM,CAAC,GAAG,YAAY,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,kBAAkB,CACnE,iBAAiB,EACjB,2BAA2B,IAAI,CAAC,OAAO,MAAM,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAC/F,GAAG,CACN,CAAC,CAAC;YACP,CAAC,CAAC;YAEF,IAAI,EAAkB,CAAC;YACvB,IAAI,CAAC;gBACD,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACtC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,IAAI,CAAC,GAAG,CAAC,CAAC;gBACV,OAAO;YACX,CAAC;YAED,IAAI,MAAS,CAAC;YACd,EAAE,CAAC,UAAU,GAAG,GAAG,EAAE;gBACjB,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC,CAAC;YACF,mIAAmI;YACnI,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC;YACtE,6GAA6G;YAC7G,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE,GAAgD,CAAC,CAAC;YAEpE,MAAM,GAAG,GAAG,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;YAC1C,OAAO,CAAC,OAAO,EAAE;iBACZ,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;iBACnB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;iBAC5B,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACpB,8DAA8D;gBAC9D,iEAAiE;gBACjE,IAAI,CAAC;oBAAC,EAAE,CAAC,KAAK,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC;gBACpD,IAAI,CAAC,OAAO,EAAE,CAAC;oBACX,OAAO,GAAG,IAAI,CAAC;oBACf,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChB,CAAC;YACL,CAAC,CAAC,CAAC;QACX,CAAC,CAAC,CAAC;IACP,CAAC;IAED,6EAA6E;IAE7E,OAAO,CAAC,IAAqB;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACtC,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC;YACD,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACL,oDAAoD;QACxD,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,QAAyC;QAC/C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,cAAc,EAAE,CAAC;QACpC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAEO,cAAc;QAClB,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;QAC/D,IAAI,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,IAAI,qBAAqB,CAAC;YAC9D,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;YACrD,IAAI,OAAO,EAAE,CAAC;gBACV,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,EAAE;oBACtB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAuB,CAAC;oBACvC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe;wBAAE,OAAO;oBACnD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU;wBAAE,OAAO,CAAC,gBAAgB;oBAC7D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU;wBAAE,CAAC,CAAC,IAAI,CAAC,CAAC;gBAC7C,CAAC,CAAC;gBACF,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;gBAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;YAC5B,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACL,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED,KAAK;QACD,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;IACpB,CAAC;CACJ;AAED,SAAS,qBAAqB,CAAC,IAAY;IACvC,IAAI,OAAO,gBAAgB,KAAK,WAAW;QAAE,OAAO,SAAS,CAAC;IAC9D,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAoC,CAAC;AACzE,CAAC;AAED,iFAAiF;AAEjF,SAAS,iBAAiB,CAAC,KAAqB;IAC5C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7C,KAAK,CAAC,WAAW,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7C,wEAAwE;QACxE,KAAK,CAAC,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IACnF,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,EAAe,EAAE,EAAkB,EAAE,UAAkB;IAC1E,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACjB,kBAAkB;QAClB,MAAM,KAAK,GAAG,EAAE,CAAC,iBAAiB,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACzB,EAAE,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;SAAM,IAAI,UAAU,GAAG,CAAC,IAAI,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACrE,sEAAsE;QACtE,4EAA4E;QAC5E,6EAA6E;QAC7E,MAAM,MAAM,GAAuB,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,UAAU,EAAE,CAAC;QAC3D,SAAS,CAAC,SAAS,GAAG,GAAG,EAAE;YACvB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;YAChC,IAAI,MAAM,EAAE,CAAC;gBACT,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAyB,CAAC,CAAC;gBAC9C,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACJ,EAAE,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;gBAClC,MAAM,KAAK,GAAG,EAAE,CAAC,iBAAiB,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnE,iBAAiB,CAAC,KAAK,CAAC,CAAC;gBACzB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;oBACrB,MAAM,MAAM,GAAqB;wBAC7B,EAAE,EAAY,cAAc,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC;wBAC9C,GAAG,EAAW,CAAC,CAAC,GAAG;wBACnB,KAAK,EAAS,EAAE;wBAChB,OAAO,EAAO,CAAC,CAAC,OAAO;wBACvB,SAAS,EAAK,CAAC,CAAC,SAAS;wBACzB,GAAG,EAAW,CAAC,CAAC,GAAG,IAAI,CAAC;wBACxB,QAAQ,EAAM,CAAC;wBACf,IAAI,EAAU,aAAa;wBAC3B,KAAK,EAAS,CAAC,CAAC,KAAK;wBACrB,IAAI,EAAU,CAAC,CAAC,IAAI;wBACpB,IAAI,EAAU,CAAC,CAAC,IAAI;wBACpB,UAAU,EAAI,CAAC,CAAC,UAAU;wBAC1B,WAAW,EAAG,KAAK;qBACtB,CAAC;oBACF,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACtB,CAAC;YACL,CAAC;QACL,CAAC,CAAC;IACN,CAAC;SAAM,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,EAAE,CAAC,iBAAiB,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;SAAM,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACxB,qEAAqE;QACrE,mEAAmE;QACnE,iBAAiB,CAAC,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/C,EAAE,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAClD,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/C,EAAE,CAAC,iBAAiB,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,EAAE,CAAC,iBAAiB,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;AACL,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC"}

package/dist/storage/nodeFileAdapter.d.ts

@@ -0,0 +1,127 @@
+/**
+ * storage/nodeFileAdapter.ts – Durable Node.js implementation of the storage
+ * port, backed by a single atomically-replaced JSON document.
+ *
+ * This is the VSIX extension-host / MCP adapter the offline-memory scope (M01)
+ * requires: real durable storage on Node WITHOUT an in-memory IndexedDB shim.
+ * fake-indexeddb evaporates with the process; this adapter fsyncs a temp file
+ * and atomically renames it over the database file, so a crash mid-write leaves
+ * either the old or the new document — never a torn one.
+ *
+ * Transaction semantics (M02/M05):
+ *   - All transactions are serialized through one promise queue, so concurrent
+ *     writers in this process interleave at transaction granularity.
+ *   - A read-write transaction holds an exclusive `<file>.lock` (see
+ *     `fileLock.ts`: atomic create, stale-lock reclamation by PID liveness,
+ *     bounded wait) across refresh + mutate + persist, so two processes can
+ *     never both build on the same stale document and lose a write.
+ *   - Under that lock, the file is re-read when another process changed it
+ *     (mtime/size freshness), so cross-process writers build on each other's
+ *     commits instead of blindly overwriting.
+ *   - If the persist fails, the in-memory document is rolled back to the
+ *     pre-transaction snapshot and the transaction rejects — no partial commits.
+ *
+ * Cross-process consistency: a polling watcher (default 1s, injectable)
+ * republishes foreign changes to subscribers, the Node analogue of the IDB
+ * adapter's BroadcastChannel.
+ *
+ * Node builtins are loaded indirectly (via a non-static import) so a browser
+ * bundle of this package never statically pulls in `node:fs`.
+ */
+import { type FileLockOptions } from './fileLock.js';
+import { type ConsistencyNote, type FactStoragePort, type StorageStoreName, type StorageTransaction } from './types.js';
+export type { NodeFileDocument } from './fileTransaction.js';
+export interface NodeFileStorageAdapterOptions {
+    /** Identity of this context for cross-context notes. Default: random. */
+    contextId?: string;
+    /**
+     * Poll interval (ms) for foreign-change notification. 0 disables the
+     * watcher. Default: 1000. Freshness is also checked synchronously before
+     * every write transaction regardless of this interval.
+     */
+    watchIntervalMs?: number;
+    /** Injectable fs (tests, sandboxed hosts). Default: node:fs. */
+    fs?: NodeFs;
+    /** Injectable path helpers. Default: node:path. */
+    path?: NodePath;
+    /** Cross-process write lock tuning (timeout, liveness probe). */
+    lock?: FileLockOptions;
+}
+/** The subset of node:fs this adapter uses. */
+export interface NodeFs {
+    existsSync(path: string): boolean;
+    readFileSync(path: string, encoding: 'utf8'): string;
+    statSync(path: string): {
+        mtimeMs: number;
+        size: number;
+    };
+    mkdirSync(path: string, opts: {
+        recursive: boolean;
+    }): void;
+    openSync(path: string, flags: string): number;
+    writeFileSync(fd: number, data: string): void;
+    fsyncSync(fd: number): void;
+    closeSync(fd: number): void;
+    renameSync(from: string, to: string): void;
+    unlinkSync(path: string): void;
+    copyFileSync(from: string, to: string): void;
+}
+export interface NodePath {
+    dirname(p: string): string;
+}
+export declare class NodeFileStorageAdapter implements FactStoragePort {
+    private readonly _filePath;
+    readonly kind: "node-file";
+    private readonly _fs;
+    private readonly _path;
+    private readonly _contextId;
+    private _doc;
+    private _stamp;
+    /** Transaction queue tail — all transacts serialize through this. */
+    private _queue;
+    private _watchTimer;
+    private readonly _listeners;
+    private readonly _watchIntervalMs;
+    private readonly _lock;
+    private constructor();
+    /**
+     * Opens (creating if necessary) the durable file at `filePath`. Async only
+     * because Node builtins load indirectly; the document itself is read
+     * synchronously before this resolves.
+     */
+    static open(filePath: string, opts?: NodeFileStorageAdapterOptions): Promise<NodeFileStorageAdapter>;
+    /** Identity of this context, stamped onto change notes and opIds. */
+    get contextId(): string;
+    /** The durable file backing this adapter. */
+    get filePath(): string;
+    /**
+     * Reads the document from disk. Recovery order on a corrupt main file
+     * (killed mid-rename is impossible, but a torn fsync on exotic filesystems
+     * is not): try `<file>.tmp` (the last fully-fsynced candidate), then give up
+     * with the corrupt file preserved at `<file>.corrupt` for forensics rather
+     * than silently starting empty.
+     */
+    private _loadFromDisk;
+    private _readDocument;
+    /** Re-reads the document when another process rewrote the file. */
+    private _refreshIfChanged;
+    /**
+     * Atomic durable write: fsync the full document to `<file>.tmp`, then rename
+     * over the live file. A crash leaves the old file intact; the tmp file is
+     * the recovery source on next boot.
+     */
+    private _persist;
+    /**
+     * Serialized unit of work. Read-write transactions take the cross-process
+     * lock, refresh from disk (so we build on other processes' commits), run
+     * `fn` against the live document, then persist atomically before
+     * releasing. Any failure rolls the in-memory document back to the
+     * pre-transaction snapshot — no partial commits, in memory or on disk.
+     */
+    transact<T>(_stores: StorageStoreName[], mode: 'readonly' | 'readwrite', fn: (tx: StorageTransaction) => Promise<T> | T): Promise<T>;
+    private _readWrite;
+    publish(note: ConsistencyNote): void;
+    subscribe(listener: (note: ConsistencyNote) => void): () => void;
+    close(): void;
+}
+//# sourceMappingURL=nodeFileAdapter.d.ts.map

package/dist/storage/nodeFileAdapter.d.ts.map

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