@seanhogg/builderforce-memory 2026.9.34 → 2026.10.2

package/src/storage/nodeFileAdapter.ts

@@ -0,0 +1,331 @@
+/**
+ * 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 { FileLock, type FileLockOptions } from './fileLock.js';
+import { FileTransaction, emptyDocument, type NodeFileDocument } from './fileTransaction.js';
+import {
+    MemoryStorageError,
+    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;
+}
+
+/** Load a module without a static specifier, so bundlers skip Node builtins. */
+function dynamicImport(m: string): Promise<unknown> {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+    return new Function('m', 'return import(m)')(m) as Promise<unknown>;
+}
+
+export class NodeFileStorageAdapter implements FactStoragePort {
+    readonly kind = 'node-file' as const;
+
+    private readonly _fs: NodeFs;
+    private readonly _path: NodePath;
+    private readonly _contextId: string;
+    private _doc: NodeFileDocument;
+    private _stamp: { mtimeMs: number; size: number } | null = null;
+    /** Transaction queue tail — all transacts serialize through this. */
+    private _queue: Promise<unknown> = Promise.resolve();
+    private _watchTimer: ReturnType<typeof setInterval> | null = null;
+    private readonly _listeners = new Set<(note: ConsistencyNote) => void>();
+    private readonly _watchIntervalMs: number;
+    private readonly _lock: FileLock;
+
+    private constructor(
+        private readonly _filePath: string,
+        fs: NodeFs,
+        path: NodePath,
+        opts: NodeFileStorageAdapterOptions,
+    ) {
+        this._fs = fs;
+        this._path = path;
+        this._contextId = opts.contextId ?? `node-${Math.random().toString(36).slice(2)}-${Date.now().toString(36)}`;
+        this._watchIntervalMs = opts.watchIntervalMs ?? 1000;
+        this._lock = new FileLock(fs, `${_filePath}.lock`, opts.lock);
+        this._doc = this._loadFromDisk();
+    }
+
+    /**
+     * 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 async open(filePath: string, opts: NodeFileStorageAdapterOptions = {}): Promise<NodeFileStorageAdapter> {
+        const fs = (opts.fs ?? (await dynamicImport('node:fs'))) as NodeFs;
+        const path = (opts.path ?? (await dynamicImport('node:path'))) as NodePath;
+        return new NodeFileStorageAdapter(filePath, fs, path, opts);
+    }
+
+    /** Identity of this context, stamped onto change notes and opIds. */
+    get contextId(): string {
+        return this._contextId;
+    }
+
+    /** The durable file backing this adapter. */
+    get filePath(): string {
+        return this._filePath;
+    }
+
+    // ── Boot / crash recovery ─────────────────────────────────────────────────
+
+    /**
+     * 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(): NodeFileDocument {
+        const fs = this._fs;
+        const dir = this._path.dirname(this._filePath);
+        if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+        const parsed = this._readDocument(this._filePath);
+        if (parsed) return parsed;
+
+        if (fs.existsSync(this._filePath)) {
+            const tmp = this._readDocument(`${this._filePath}.tmp`);
+            if (tmp) return tmp;
+            try {
+                fs.copyFileSync(this._filePath, `${this._filePath}.corrupt`);
+                fs.unlinkSync(this._filePath);
+            } catch { /* best-effort forensics */ }
+        }
+        return emptyDocument();
+    }
+
+    private _readDocument(path: string): NodeFileDocument | null {
+        const fs = this._fs;
+        if (!fs.existsSync(path)) return null;
+        let raw: unknown;
+        try {
+            raw = JSON.parse(fs.readFileSync(path, 'utf8'));
+        } catch {
+            return null;
+        }
+        if (!raw || typeof raw !== 'object') return null;
+        const doc = raw as Partial<NodeFileDocument>;
+        if (doc.formatVersion !== 1 || !Array.isArray(doc.facts)) return null;
+        const full: NodeFileDocument = {
+            formatVersion: 1,
+            facts: doc.facts,
+            tombstones: Array.isArray(doc.tombstones) ? doc.tombstones : [],
+            journal: Array.isArray(doc.journal) ? doc.journal : [],
+            meta: doc.meta?.key === 'counters'
+                ? doc.meta
+                : { key: 'counters', seq: 0, revision: 0, opSeq: 0 },
+        };
+        try {
+            const st = fs.statSync(path);
+            this._stamp = { mtimeMs: st.mtimeMs, size: st.size };
+        } catch { /* stamp stays null; next write re-checks */ }
+        return full;
+    }
+
+    /** Re-reads the document when another process rewrote the file. */
+    private _refreshIfChanged(): void {
+        const fs = this._fs;
+        if (!fs.existsSync(this._filePath)) {
+            // Deleted underneath us: an empty document is the truth now.
+            if (this._stamp) {
+                this._stamp = null;
+                this._doc = emptyDocument();
+            }
+            return;
+        }
+        let st: { mtimeMs: number; size: number };
+        try {
+            st = fs.statSync(this._filePath);
+        } catch {
+            return;
+        }
+        if (this._stamp && st.mtimeMs === this._stamp.mtimeMs && st.size === this._stamp.size) return;
+        const doc = this._readDocument(this._filePath);
+        if (doc) this._doc = doc;
+    }
+
+    /**
+     * 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(): void {
+        const fs = this._fs;
+        const text = JSON.stringify(this._doc);
+        const tmp = `${this._filePath}.tmp`;
+        const fd = fs.openSync(tmp, 'w');
+        try {
+            fs.writeFileSync(fd, text);
+            fs.fsyncSync(fd);
+        } finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, this._filePath);
+        try {
+            const st = fs.statSync(this._filePath);
+            this._stamp = { mtimeMs: st.mtimeMs, size: st.size };
+        } catch { /* re-stamped on next change check */ }
+    }
+
+    // ── Port ──────────────────────────────────────────────────────────────────
+
+    /**
+     * 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> {
+        const run = this._queue.then((): Promise<T> => mode === 'readwrite'
+            ? this._lock.run(() => this._readWrite(fn))
+            : Promise.resolve(fn(new FileTransaction(this._doc))));
+        // Keep the queue alive across rejections.
+        this._queue = run.catch(() => undefined);
+        return run;
+    }
+
+    private async _readWrite<T>(fn: (tx: StorageTransaction) => Promise<T> | T): Promise<T> {
+        this._refreshIfChanged();
+        const snapshot = JSON.stringify(this._doc);
+        let result: T;
+        try {
+            result = await fn(new FileTransaction(this._doc));
+        } catch (err) {
+            // A unit of work that threw leaves nothing behind, in memory either.
+            this._doc = JSON.parse(snapshot) as NodeFileDocument;
+            throw err;
+        }
+        try {
+            this._persist();
+        } catch (err) {
+            // Roll back: the caller must not observe a committed-looking state
+            // that never reached disk.
+            this._doc = JSON.parse(snapshot) as NodeFileDocument;
+            throw new MemoryStorageError(
+                'STORAGE_ABORTED',
+                `Failed to durably persist "${this._filePath}": ${err instanceof Error ? err.message : String(err)}`,
+                err,
+            );
+        }
+        return result;
+    }
+
+    // ── Cross-process consistency seam (M05) ──────────────────────────────────
+
+    publish(note: ConsistencyNote): void {
+        // Co-process subscribers get the note synchronously (subscribers filter
+        // their own origin); foreign processes learn via the watcher.
+        for (const l of this._listeners) l(note);
+    }
+
+    subscribe(listener: (note: ConsistencyNote) => void): () => void {
+        this._listeners.add(listener);
+        if (this._watchIntervalMs > 0 && !this._watchTimer) {
+            let lastRevision = this._doc.meta.revision;
+            const timer = setInterval(() => {
+                const before = this._doc.meta.revision;
+                this._refreshIfChanged();
+                if (this._doc.meta.revision !== before && this._doc.meta.revision !== lastRevision) {
+                    lastRevision = this._doc.meta.revision;
+                    const note: ConsistencyNote = {
+                        kind: 'facts-changed',
+                        revision: this._doc.meta.revision,
+                        origin: 'foreign',
+                    };
+                    for (const l of this._listeners) l(note);
+                } else {
+                    lastRevision = this._doc.meta.revision;
+                }
+            }, this._watchIntervalMs);
+            const maybeUnref = timer as unknown as { unref?: () => void };
+            if (typeof maybeUnref.unref === 'function') maybeUnref.unref();
+            this._watchTimer = timer;
+        }
+        return () => {
+            this._listeners.delete(listener);
+            if (this._listeners.size === 0 && this._watchTimer) {
+                clearInterval(this._watchTimer);
+                this._watchTimer = null;
+            }
+        };
+    }
+
+    close(): void {
+        if (this._watchTimer) {
+            clearInterval(this._watchTimer);
+            this._watchTimer = null;
+        }
+    }
+}

package/src/storage/syncJournal.ts

@@ -0,0 +1,47 @@
+/**
+ * storage/syncJournal.ts – The sync-acknowledgement half of the journal (M04/M06).
+ *
+ * The journal holds only operations still owed to a sync target: entries are
+ * written unsynced (and only when sync is enabled — see `factMutations.journal`)
+ * and are DELETED once acknowledged, so the journal stays bounded by the
+ * outstanding work instead of growing with every write ever made.
+ */
+
+import type { FactStoragePort, JournalEntry, StoredFactRecord, TombstoneRecord } from './types.js';
+
+/** Journal entries not yet acknowledged by sync — the pending operation set. */
+export async function pendingOps(storage: FactStoragePort): Promise<JournalEntry[]> {
+    return storage.transact(['journal'], 'readonly', async (tx) => {
+        const all = await tx.getAll<JournalEntry>('journal');
+        return all.filter((j) => !j.synced);
+    });
+}
+
+/**
+ * Acknowledges synced operations: their journal entries are pruned, and the
+ * facts/tombstones they produced clear `pendingSync`, making cap eviction
+ * eligible again. Rows already marked synced (written by older versions,
+ * which journaled every write even without sync) are pruned too.
+ */
+export async function markSynced(storage: FactStoragePort, opIds: string[]): Promise<void> {
+    if (opIds.length === 0) return;
+    const acked = new Set(opIds);
+    await storage.transact(['journal', 'facts', 'tombstones'], 'readwrite', async (tx) => {
+        const journal = await tx.getAll<JournalEntry>('journal');
+        for (const entry of journal) {
+            if (entry.synced || acked.has(entry.opId)) await tx.delete('journal', entry.opId);
+        }
+        const facts = await tx.getAll<StoredFactRecord>('facts');
+        for (const record of facts) {
+            if (acked.has(record.opId) && record.pendingSync) {
+                await tx.put('facts', { ...record, pendingSync: false });
+            }
+        }
+        const tombstones = await tx.getAll<TombstoneRecord>('tombstones');
+        for (const tomb of tombstones) {
+            if (acked.has(tomb.opId) && tomb.pendingSync) {
+                await tx.put('tombstones', { ...tomb, pendingSync: false });
+            }
+        }
+    });
+}

package/src/storage/types.ts

@@ -0,0 +1,262 @@
+/**
+ * storage/types.ts – Narrow storage/transaction ports for durable memory.
+ *
+ * This module is the seam the offline-memory scope (M01–M05) requires:
+ *   - MemoryStore no longer owns IndexedDB directly; it speaks to a
+ *     {@link FactStoragePort} with REAL transaction semantics (a write resolves
+ *     only after the transaction commits, and rejects on abort — M02).
+ *   - Facts carry explicit scope partitions (account/tenant/project/repository/
+ *     chat — or the explicit unbound scope for personal, never-connected
+ *     memory), durable revisions, operation identity and provenance (M03/M04).
+ *   - Deletes write tombstones, and every mutation appends to a sync journal in
+ *     the SAME transaction as the fact change, so a crash can never acknowledge
+ *     a fact whose journal entry was lost (M02/M04).
+ *
+ * Two durable adapters implement the port:
+ *   - `IdbStorageAdapter`       (browser / VSIX webview — IndexedDB)
+ *   - `NodeFileStorageAdapter`  (VSIX extension host / MCP — atomic JSON file)
+ * An in-memory IndexedDB shim (fake-indexeddb) is a TEST double, never a
+ * durability claim.
+ */
+
+import { SSMError, type SSMErrorCode } from '../errors/SSMError.js';
+
+/** Explicit ownership partition for a fact. All fields optional; absent = unbound. */
+export interface MemoryScope {
+    account?: string;
+    tenant?: string;
+    project?: string;
+    repository?: string;
+    chat?: string;
+}
+
+/** The explicit "no account, never connected" partition — NOT the absence of a scope. */
+export const UNBOUND_SCOPE: MemoryScope = Object.freeze({});
+
+const SCOPE_FIELDS = ['account', 'tenant', 'project', 'repository', 'chat'] as const;
+
+/**
+ * Canonical partition string for a scope. The unbound scope partitions to the
+ * empty string, so legacy records (written before scopes existed) land in the
+ * unbound partition and stay readable. Two scopes that differ in any field are
+ * different partitions — callers can never widen a recall by omitting a field
+ * unless they genuinely target the unbound partition.
+ */
+export function scopePartitionKey(scope: MemoryScope | undefined): string {
+    if (!scope) return '';
+    const parts: string[] = [];
+    for (const f of SCOPE_FIELDS) {
+        const v = scope[f];
+        if (v != null && v !== '') parts.push(`${f}=${encodeURIComponent(v)}`);
+    }
+    return parts.join('|');
+}
+
+/**
+ * Physical record id for a (scope, key) pair. Unbound-scope ids are the bare
+ * key — byte-identical to pre-scope records, so existing databases migrate
+ * without rewriting keys.
+ */
+export function scopedRecordId(scope: MemoryScope | undefined, key: string): string {
+    const partition = scopePartitionKey(scope);
+    return partition === '' ? key : `${partition}::${key}`;
+}
+
+/** Where a fact came from. Survives export/import so source time is never rewritten. */
+export interface FactProvenance {
+    /** Origin surface/agent, e.g. 'vscode', 'mcp', 'web', 'cognition'. */
+    source?: string;
+    /** Snapshot/store this record was imported from. */
+    importedFrom?: string;
+    /** The timestamp the source store recorded; preserved across import (M06). */
+    originalTimestamp?: number;
+}
+
+export type StorageStoreName = 'facts' | 'tombstones' | 'journal' | 'meta';
+
+/**
+ * Secondary index on {@link StoredFactRecord.key}. Key lookup uses this (or the
+ * primary key) — never a full scan — when the adapter has built it.
+ */
+export const FACT_KEY_INDEX = 'byKey';
+
+/**
+ * Secondary multi-entry index on {@link StoredFactRecord.tags}. Tag lookup uses
+ * this when present and falls back to a scan only when the index is missing.
+ */
+export const FACT_TAG_INDEX = 'byTag';
+
+/**
+ * The durable fact record. Extends the legacy MemoryEntry shape with identity,
+ * revision and sync state. `pendingSync` is only ever true when the owning
+ * store was created with sync enabled — without a sync target there is nothing
+ * to be pending FOR, and eviction must behave exactly as before (M06).
+ */
+export interface StoredFactRecord {
+    /** Physical primary key: {@link scopedRecordId}. */
+    id: string;
+    /** Caller-facing key within the scope. */
+    key: string;
+    /** Ownership partition. */
+    scope: MemoryScope;
+    content: string;
+    /** Wall-clock write time (source time; preserved by import). */
+    timestamp: number;
+    /** Durable monotonic tiebreaker for same-millisecond writes. */
+    seq: number;
+    /** Durable revision: the store generation that last wrote this record. */
+    revision: number;
+    /** Durable identity of the operation that produced this record. */
+    opId: string;
+    ttlMs?: number;
+    type?: 'text' | 'json' | 'number' | 'boolean';
+    tags?: string[];
+    importance?: number;
+    provenance?: FactProvenance;
+    /** True until a sync acknowledgement clears it; such facts are NEVER evicted by caps. */
+    pendingSync: boolean;
+}
+
+/** A durable deletion marker. Deletes propagate through sync; tombstones prevent resurrection. */
+export interface TombstoneRecord {
+    id: string;
+    key: string;
+    scope: MemoryScope;
+    deletedAt: number;
+    /** Store generation of the delete; always greater than the fact's last revision. */
+    revision: number;
+    opId: string;
+    pendingSync: boolean;
+}
+
+export type JournalOpKind = 'remember' | 'forget';
+
+/** One durable operation in the sync journal — written atomically with its fact change. */
+export interface JournalEntry {
+    opId: string;
+    kind: JournalOpKind;
+    id: string;
+    key: string;
+    scope: MemoryScope;
+    /** Store generation after this op committed. */
+    revision: number;
+    /** The revision the writer based its write on (CAS); undefined = blind write. */
+    baseRevision?: number;
+    timestamp: number;
+    synced: boolean;
+}
+
+/** Counters kept durably in the meta store. */
+export interface MetaCounters {
+    key: 'counters';
+    /** Durable write sequence (replaces the process-local `_writeSeq`). */
+    seq: number;
+    /** Durable store generation, bumped by every committed write transaction. */
+    revision: number;
+    /** Durable operation counter; opIds are `${contextId}:${opSeq}`. */
+    opSeq: number;
+}
+
+/**
+ * The minimal surface a transaction offers. Adapters MUST keep the underlying
+ * transaction alive across the awaited operations (request-chained awaits only)
+ * and MUST NOT resolve {@link FactStoragePort.transact} before commit.
+ */
+export interface StorageTransaction {
+    get<T>(store: StorageStoreName, id: string): Promise<T | undefined>;
+    getAll<T>(store: StorageStoreName): Promise<T[]>;
+    put(store: StorageStoreName, value: unknown): Promise<void>;
+    delete(store: StorageStoreName, id: string): Promise<void>;
+    /**
+     * Lookup via a named index. `undefined` means this store has no such index
+     * (legacy schema, or an adapter that has not built it) — the caller MUST
+     * fall back to a primary-key get or a scan. An empty array means the index
+     * exists and matched nothing; do not scan in that case.
+     */
+    getByIndex?<T>(store: StorageStoreName, indexName: string, query: string): Promise<T[] | undefined>;
+}
+
+/** A change notice for cross-context invalidation (M05). */
+export interface ConsistencyNote {
+    kind: 'facts-changed';
+    /** Scope partition that changed; undefined = whole database. */
+    scope?: MemoryScope;
+    /** Durable generation after the change. */
+    revision: number;
+    /** Identity of the committing context; a context ignores its own notes. */
+    origin: string;
+}
+
+/**
+ * The narrow durable-storage port. One transaction = one unit of work:
+ * fact mutation + provenance + tombstone/event + journal commit together or
+ * not at all.
+ */
+export interface FactStoragePort {
+    /** Which durable backend this is (for honest capability reporting). */
+    readonly kind: 'indexedDB' | 'node-file';
+    /**
+     * Runs `fn` inside one real transaction over the named stores. Resolves with
+     * `fn`'s result ONLY after the transaction has committed durably; rejects if
+     * the transaction aborts, `fn` throws, or the persist fails. A rejected
+     * transact leaves NO partial writes behind.
+     */
+    transact<T>(
+        stores: StorageStoreName[],
+        mode: 'readonly' | 'readwrite',
+        fn: (tx: StorageTransaction) => Promise<T> | T,
+    ): Promise<T>;
+    /**
+     * Publishes a change notice to other contexts sharing this storage, when the
+     * adapter supports cross-context notification. Optional.
+     */
+    publish?(note: ConsistencyNote): void;
+    /**
+     * Subscribes to change notices from OTHER contexts (tabs, extension windows,
+     * MCP processes) sharing this storage. Returns an unsubscribe function.
+     * Optional: an adapter without it simply offers no cross-context seam.
+     */
+    subscribe?(listener: (note: ConsistencyNote) => void): () => void;
+    close?(): void | Promise<void>;
+}
+
+/** Detailed error codes surfaced by the storage layer (`MemoryStorageError.storageCode`). */
+export type StorageErrorCode =
+    /** The durable backend is unavailable or faulted. */
+    | 'STORAGE_UNAVAILABLE'
+    /** A compare-and-set write found a newer revision than its base. */
+    | 'STORAGE_CONFLICT'
+    /** A transaction aborted; no partial writes were committed. */
+    | 'STORAGE_ABORTED';
+
+/**
+ * The public {@link SSMError} code for each storage code. Callers that predate
+ * the storage layer branch on `code === 'MEMORY_UNAVAILABLE'` (what MemoryStore
+ * always rejected with when IndexedDB was missing or faulted), so unavailable
+ * and aborted storage keep that code; a CAS conflict is the new `MEMORY_CONFLICT`.
+ */
+const PUBLIC_CODE: Record<StorageErrorCode, SSMErrorCode> = {
+    STORAGE_UNAVAILABLE: 'MEMORY_UNAVAILABLE',
+    STORAGE_ABORTED    : 'MEMORY_UNAVAILABLE',
+    STORAGE_CONFLICT   : 'MEMORY_CONFLICT',
+};
+
+/**
+ * A storage-layer failure. It IS an {@link SSMError} whose `code` is the public
+ * contract (`MEMORY_UNAVAILABLE` / `MEMORY_CONFLICT`); `storageCode` keeps the
+ * detailed storage code for callers that need it.
+ */
+export class MemoryStorageError extends SSMError {
+    readonly storageCode: StorageErrorCode;
+
+    constructor(storageCode: StorageErrorCode, message: string, cause?: unknown) {
+        super(PUBLIC_CODE[storageCode], message, cause);
+        this.storageCode = storageCode;
+        this.name = 'MemoryStorageError';
+    }
+}
+
+/** Type guard for conflict errors so callers can reconcile instead of blindly retrying. */
+export function isStorageConflict(err: unknown): err is MemoryStorageError {
+    return err instanceof MemoryStorageError && err.storageCode === 'STORAGE_CONFLICT';
+}