@seanhogg/builderforce-memory 2026.9.33 → 2026.10.1

package/src/storage/fileLock.ts

@@ -0,0 +1,162 @@
+/**
+ * storage/fileLock.ts – Cross-process exclusive lock for the node-file adapter.
+ *
+ * Two MCP / extension-host processes sharing one memory file each ran
+ * refresh → mutate → tmp+rename with nothing between them, so the later rename
+ * silently dropped the other's commit. A read-write transaction now holds an
+ * exclusive lock file for its whole refresh + mutate + persist:
+ *
+ *   - Acquire = `open(<file>.lock, 'wx')` (atomic create-if-absent), then write
+ *     our PID into it.
+ *   - A lock whose recorded PID is no longer alive is STALE and is reclaimed.
+ *     Staleness is decided by PID liveness, never by age: a slow but live
+ *     writer (a large fsync) must not have its lock stolen.
+ *   - Waiting is bounded: past `timeoutMs` the transaction rejects with
+ *     STORAGE_UNAVAILABLE naming the holder, instead of hanging forever.
+ */
+
+import { MemoryStorageError } from './types.js';
+
+/** The subset of node:fs the lock needs. */
+export interface LockFs {
+    openSync(path: string, flags: string): number;
+    writeFileSync(fd: number, data: string): void;
+    closeSync(fd: number): void;
+    readFileSync(path: string, encoding: 'utf8'): string;
+    unlinkSync(path: string): void;
+}
+
+export interface FileLockOptions {
+    /** Give up waiting after this long (ms). Default 10 000. */
+    timeoutMs?: number;
+    /** Poll interval while the lock is held by a live process (ms). Default 20. */
+    retryMs?: number;
+    /** This process's PID. Default: `process.pid`. */
+    pid?: number;
+    /** PID liveness probe. Default: `process.kill(pid, 0)`. */
+    isAlive?: (pid: number) => boolean;
+    /** Injectable sleep (tests). */
+    sleep?: (ms: number) => Promise<void>;
+}
+
+interface NodeProcessLike {
+    pid: number;
+    kill(pid: number, signal: number): void;
+}
+
+function nodeProcess(): NodeProcessLike | undefined {
+    return (globalThis as { process?: NodeProcessLike }).process;
+}
+
+function errorCode(err: unknown): string | undefined {
+    return (err as { code?: string } | null)?.code;
+}
+
+/** `kill(pid, 0)`: ESRCH = gone; EPERM = alive under another user. */
+export function defaultIsAlive(pid: number): boolean {
+    const proc = nodeProcess();
+    if (!proc) return true;
+    try {
+        proc.kill(pid, 0);
+        return true;
+    } catch (err) {
+        return errorCode(err) === 'EPERM';
+    }
+}
+
+function readHolder(fs: LockFs, lockPath: string): number | undefined {
+    let text: string;
+    try {
+        text = fs.readFileSync(lockPath, 'utf8');
+    } catch (err) {
+        // Released between our failed create and this read: retry the create.
+        if (errorCode(err) === 'ENOENT') return undefined;
+        throw err;
+    }
+    const pid = Number.parseInt(text.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+export class FileLock {
+    private readonly _timeoutMs: number;
+    private readonly _retryMs: number;
+    private readonly _pid: number;
+    private readonly _isAlive: (pid: number) => boolean;
+    private readonly _sleep: (ms: number) => Promise<void>;
+
+    constructor(private readonly _fs: LockFs, readonly lockPath: string, opts: FileLockOptions = {}) {
+        this._timeoutMs = opts.timeoutMs ?? 10_000;
+        this._retryMs = opts.retryMs ?? 20;
+        this._pid = opts.pid ?? nodeProcess()?.pid ?? 0;
+        this._isAlive = opts.isAlive ?? defaultIsAlive;
+        this._sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+
+    /** Runs `fn` while holding the lock; always releases it. */
+    async run<T>(fn: () => Promise<T> | T): Promise<T> {
+        await this._acquire();
+        try {
+            return await fn();
+        } finally {
+            this._release();
+        }
+    }
+
+    private _tryCreate(): boolean {
+        let fd: number;
+        try {
+            fd = this._fs.openSync(this.lockPath, 'wx');
+        } catch (err) {
+            if (errorCode(err) === 'EEXIST') return false;
+            throw new MemoryStorageError('STORAGE_UNAVAILABLE', `Cannot create lock "${this.lockPath}": ${String(err)}`, err);
+        }
+        try {
+            this._fs.writeFileSync(fd, String(this._pid));
+        } finally {
+            this._fs.closeSync(fd);
+        }
+        return true;
+    }
+
+    private async _acquire(): Promise<void> {
+        const deadline = Date.now() + this._timeoutMs;
+        let holder: number | undefined;
+        for (;;) {
+            if (this._tryCreate()) return;
+            holder = readHolder(this._fs, this.lockPath);
+            if (holder !== undefined && holder !== this._pid && !this._isAlive(holder)) {
+                this._reclaim(holder);
+                continue;
+            }
+            // A live holder, or a lock whose PID is not written yet: wait.
+            if (Date.now() >= deadline) {
+                throw new MemoryStorageError(
+                    'STORAGE_UNAVAILABLE',
+                    `Timed out after ${this._timeoutMs}ms waiting for "${this.lockPath}" (held by pid ${holder ?? 'unknown'}).`,
+                );
+            }
+            await this._sleep(this._retryMs);
+        }
+    }
+
+    /** Removes a dead holder's lock — only if it still names that holder. */
+    private _reclaim(deadPid: number): void {
+        if (readHolder(this._fs, this.lockPath) !== deadPid) return;
+        try {
+            this._fs.unlinkSync(this.lockPath);
+        } catch (err) {
+            // Another waiter reclaimed it first; the next create decides.
+            if (errorCode(err) !== 'ENOENT') throw err;
+        }
+    }
+
+    private _release(): void {
+        try {
+            this._fs.unlinkSync(this.lockPath);
+        } catch (err) {
+            if (errorCode(err) !== 'ENOENT') {
+                throw new MemoryStorageError('STORAGE_UNAVAILABLE', `Cannot release lock "${this.lockPath}": ${String(err)}`, err);
+            }
+        }
+    }
+}

package/src/storage/fileTransaction.ts

@@ -0,0 +1,116 @@
+/**
+ * storage/fileTransaction.ts – The {@link StorageTransaction} the node-file
+ * adapter hands to a unit of work: direct reads/writes on the in-memory
+ * document, plus lazily rebuilt key/tag indexes over its facts.
+ */
+
+import {
+    FACT_KEY_INDEX,
+    FACT_TAG_INDEX,
+    type JournalEntry,
+    type MetaCounters,
+    type StorageStoreName,
+    type StorageTransaction,
+    type StoredFactRecord,
+    type TombstoneRecord,
+} from './types.js';
+
+/** The on-disk document shape. Versioned so future migrations are explicit. */
+export interface NodeFileDocument {
+    formatVersion: 1;
+    facts: StoredFactRecord[];
+    tombstones: TombstoneRecord[];
+    journal: JournalEntry[];
+    meta: MetaCounters;
+}
+
+export function emptyDocument(): NodeFileDocument {
+    return {
+        formatVersion: 1,
+        facts: [],
+        tombstones: [],
+        journal: [],
+        meta: { key: 'counters', seq: 0, revision: 0, opSeq: 0 },
+    };
+}
+
+export class FileTransaction implements StorageTransaction {
+    /** Lazy key/tag indexes over the in-memory document. Rebuilt after mutations. */
+    private _indexDirty = true;
+    private readonly _byKey = new Map<string, StoredFactRecord[]>();
+    private readonly _byTag = new Map<string, StoredFactRecord[]>();
+
+    constructor(private readonly _doc: NodeFileDocument) {}
+
+    private _table(store: StorageStoreName): Array<{ id?: string; opId?: string; key?: string }> {
+        return this._doc[store] as unknown as Array<{ id?: string; opId?: string; key?: string }>;
+    }
+
+    /** The id field of a table store (`meta` is the singleton and never reaches here). */
+    private _idField(store: Exclude<StorageStoreName, 'meta'>): 'id' | 'opId' {
+        return store === 'journal' ? 'opId' : 'id';
+    }
+
+    // `meta` is ONE counters record on disk (`doc.meta`), not an array: the other stores
+    // are tables keyed by their id field, `meta` is a singleton keyed 'counters'.
+    async get<T>(store: StorageStoreName, id: string): Promise<T | undefined> {
+        if (store === 'meta') return (this._doc.meta?.key === id ? this._doc.meta : undefined) as T | undefined;
+        const f = this._idField(store);
+        return this._table(store).find((r) => r[f] === id) as T | undefined;
+    }
+    async getAll<T>(store: StorageStoreName): Promise<T[]> {
+        if (store === 'meta') return (this._doc.meta ? [this._doc.meta] : []) as unknown as T[];
+        return this._table(store).slice() as unknown as T[];
+    }
+    async put(store: StorageStoreName, value: unknown): Promise<void> {
+        if (store === 'meta') {
+            this._doc.meta = value as MetaCounters;
+            return;
+        }
+        const f = this._idField(store);
+        const table = this._table(store);
+        const id = (value as Record<string, string>)[f]!;
+        const idx = table.findIndex((r) => r[f] === id);
+        if (idx >= 0) table[idx] = value as never;
+        else table.push(value as never);
+        if (store === 'facts') this._indexDirty = true;
+    }
+    async delete(store: StorageStoreName, id: string): Promise<void> {
+        if (store === 'meta') {
+            if (this._doc.meta?.key === id) this._doc.meta = emptyDocument().meta;
+            return;
+        }
+        const f = this._idField(store);
+        const table = this._table(store);
+        const idx = table.findIndex((r) => r[f] === id);
+        if (idx >= 0) table.splice(idx, 1);
+        if (store === 'facts') this._indexDirty = true;
+    }
+
+    async getByIndex<T>(store: StorageStoreName, indexName: string, query: string): Promise<T[] | undefined> {
+        if (store !== 'facts') return undefined;
+        if (indexName !== FACT_KEY_INDEX && indexName !== FACT_TAG_INDEX) return undefined;
+        this._ensureFactIndexes();
+        const hits = indexName === FACT_KEY_INDEX
+            ? this._byKey.get(query)
+            : this._byTag.get(query);
+        return (hits ?? []).slice() as T[];
+    }
+
+    private _ensureFactIndexes(): void {
+        if (!this._indexDirty) return;
+        this._byKey.clear();
+        this._byTag.clear();
+        for (const fact of this._doc.facts) {
+            const keyHits = this._byKey.get(fact.key);
+            if (keyHits) keyHits.push(fact);
+            else this._byKey.set(fact.key, [fact]);
+            for (const tag of fact.tags ?? []) {
+                const tagHits = this._byTag.get(tag);
+                if (tagHits) tagHits.push(fact);
+                else this._byTag.set(tag, [fact]);
+            }
+        }
+        this._indexDirty = false;
+    }
+}

package/src/storage/idbAdapter.ts

@@ -0,0 +1,373 @@
+/**
+ * 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,
+    type ConsistencyNote,
+    type FactStoragePort,
+    type MetaCounters,
+    type StorageStoreName,
+    type StorageTransaction,
+    type StoredFactRecord,
+} 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: StorageStoreName[] = [FACTS_STORE, TOMBSTONES_STORE, JOURNAL_STORE, META_STORE];
+
+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;
+}
+
+interface LegacyFactRecord {
+    key: string;
+    content: string;
+    timestamp: number;
+    seq?: number;
+    ttlMs?: number;
+    type?: StoredFactRecord['type'];
+    tags?: string[];
+    importance?: number;
+}
+
+function reqToPromise<R>(req: IDBRequest<R>): Promise<R> {
+    return new Promise<R>((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error('IndexedDB request failed'));
+    });
+}
+
+class IdbStorageTransaction implements StorageTransaction {
+    constructor(private readonly _tx: IDBTransaction) {}
+
+    async get<T>(store: StorageStoreName, id: string): Promise<T | undefined> {
+        return reqToPromise(this._tx.objectStore(store).get(id) as IDBRequest<T | undefined>);
+    }
+    async getAll<T>(store: StorageStoreName): Promise<T[]> {
+        return reqToPromise(this._tx.objectStore(store).getAll() as IDBRequest<T[]>);
+    }
+    async put(store: StorageStoreName, value: unknown): Promise<void> {
+        await reqToPromise(this._tx.objectStore(store).put(value));
+    }
+    async delete(store: StorageStoreName, id: string): Promise<void> {
+        await reqToPromise(this._tx.objectStore(store).delete(id));
+    }
+
+    async getByIndex<T>(store: StorageStoreName, indexName: string, query: string): Promise<T[] | undefined> {
+        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) as IDBRequest<T[]>);
+    }
+}
+
+export class IdbStorageAdapter implements FactStoragePort {
+    readonly kind = 'indexedDB' as const;
+
+    private readonly _idb: IDBFactory | undefined;
+    private readonly _contextId: string;
+    private readonly _channelFactory: ((name: string) => BroadcastChannelLike | undefined) | undefined;
+    private _db: IDBDatabase | null = null;
+    private _channel: BroadcastChannelLike | null = null;
+    private _channelFailed = false;
+    private readonly _listeners = new Set<(note: ConsistencyNote) => void>();
+
+    constructor(
+        private readonly _dbName: string,
+        opts: IdbStorageAdapterOptions = {},
+    ) {
+        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(): string {
+        return this._contextId;
+    }
+
+    private _open(): Promise<IDBDatabase> {
+        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 as IDBOpenDBRequest).result;
+                const tx = (e.target as IDBOpenDBRequest).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<T>(
+        stores: StorageStoreName[],
+        mode: 'readonly' | 'readwrite',
+        fn: (tx: StorageTransaction) => Promise<T> | T,
+    ): Promise<T> {
+        const db = await this._open();
+        return new Promise<T>((resolve, reject) => {
+            let settled = false;
+            const fail = (err: unknown) => {
+                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: IDBTransaction;
+            try {
+                tx = db.transaction(stores, mode);
+            } catch (err) {
+                fail(err);
+                return;
+            }
+
+            let result: T;
+            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 = () => { /* handled via request promises + onabort */ };
+
+            const stx = new IdbStorageTransaction(tx);
+            Promise.resolve()
+                .then(() => fn(stx))
+                .then((r) => { result = r; })
+                .catch((err: unknown) => {
+                    // 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: ConsistencyNote): void {
+        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: (note: ConsistencyNote) => void): () => void {
+        this._listeners.add(listener);
+        if (this._db) this._ensureChannel();
+        return () => this._listeners.delete(listener);
+    }
+
+    private _ensureChannel(): BroadcastChannelLike | null {
+        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 as ConsistencyNote;
+                    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(): void {
+        this._channel?.close();
+        this._channel = null;
+        this._db?.close();
+        this._db = null;
+    }
+}
+
+function defaultChannelFactory(name: string): BroadcastChannelLike | undefined {
+    if (typeof BroadcastChannel === 'undefined') return undefined;
+    return new BroadcastChannel(name) as unknown as BroadcastChannelLike;
+}
+
+// ── Schema migration ──────────────────────────────────────────────────────────
+
+function ensureFactIndexes(store: IDBObjectStore): void {
+    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: IDBDatabase, tx: IDBTransaction, oldVersion: number): void {
+    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: LegacyFactRecord[] = [];
+        const cursorReq = tx.objectStore(FACTS_STORE).openCursor();
+        cursorReq.onsuccess = () => {
+            const cursor = cursorReq.result;
+            if (cursor) {
+                legacy.push(cursor.value as LegacyFactRecord);
+                cursor.continue();
+            } else {
+                db.deleteObjectStore(FACTS_STORE);
+                const store = db.createObjectStore(FACTS_STORE, { keyPath: 'id' });
+                ensureFactIndexes(store);
+                for (const e of legacy) {
+                    const record: StoredFactRecord = {
+                        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 };
+export type { MetaCounters };