@seanhogg/builderforce-memory 2026.9.34 → 2026.10.1

package/dist/memory/MemoryStore.js

@@ -1,184 +1,173 @@
 /**
  * MemoryStore – persistent key-value fact store and weight checkpoint helper.
  *
- * Uses IndexedDB with a dedicated 'ssmjs' database containing two object stores:
- *   - 'facts'   : MemoryEntry records keyed by the fact key string
- *   - 'weights' : a single ArrayBuffer keyed by `weightsKey`
+ * Persistence is delegated to a narrow {@link FactStoragePort} (M01) fronted by
+ * a {@link ScopedFactRepository} unit-of-work layer (M02–M06):
+ *   - Browser default: IndexedDB via {@link IdbStorageAdapter}; every write
+ *     resolves only after the transaction commits (M02).
+ *   - Node.js: pass `storage: await NodeFileStorageAdapter.open(path)` for real
+ *     durable storage. fake-indexeddb via `idbFactory` remains supported for
+ *     TESTS, but is never durable and is not presented as such.
+ *   - Facts live in an explicit {@link MemoryScope} partition (default: the
+ *     unbound, never-connected scope) with durable revisions, operation
+ *     identity, provenance and — when `sync: true` — a journaled tombstone
+ *     trail that caps/TTL will not sacrifice (M03/M04/M06).
+ *
+ * Recall ranking and its derived embedding/index caches live in
+ * {@link SemanticRecall}; the public shapes in `./types.ts`.
  *
  * Weight save/load is delegated to the SSMRuntime passed to saveWeights/loadWeights.
  */
-import { SSMError } from '../errors/SSMError.js';
-import { tokenize, jaccardSimilarity } from '../similarity/index.js';
-import { hybridRetrieve, denseSearch, HnswIndex } from '../retrieval/index.js';
-const FACTS_STORE = 'facts';
-const WEIGHTS_STORE = 'weights';
-const DB_VERSION = 1;
-/**
- * Process-wide monotonic counter stamped onto each remembered entry. Strictly
- * increasing per write regardless of store instance, so it reliably breaks
- * `timestamp` ties (same-millisecond writes) in newest-first ordering.
- */
-let _writeSeq = 0;
+import { IdbStorageAdapter } from '../storage/idbAdapter.js';
+import { ScopedFactRepository } from '../storage/ScopedFactRepository.js';
+import { MemoryStorageError, } from '../storage/types.js';
+import { SemanticRecall } from './SemanticRecall.js';
+import { isExpired, liveEntries, rememberInput, toEntry, toImportRecord } from './records.js';
+import { TtlSweeper } from './ttlSweeper.js';
 /** Max content→embedding vectors retained (LRU-evicted past this). (EVM-8) */
 const EMBED_CACHE_MAX = 2000;
 export class MemoryStore {
-    _dbName;
     _weightsKey;
-    _idb;
     _defaultTtl;
-    _annThreshold;
     _maxEntries;
-    _embedCacheMax;
-    _db = null;
-    _sweepTimer = null;
-    /** Content → L2-normalised embedding cache, used by recallSimilar. */
-    _embedCache = new Map();
-    /** Runtime whose embeddings populate `_embedCache`; a change invalidates it. */
-    _embedRuntime = null;
-    // ── Persistent dense index (EVM-1b) ────────────────────────────────────────
-    // Fact embeddings keyed by `${key}@${seq}` so an EDIT (seq bump) is a new key
-    // and an unchanged fact is never re-embedded. The HNSW index is derived from
-    // these vectors and reused across recalls until the fact set changes — so
-    // steady-state recall is O(1) query-embed + O(log N) search, not O(N) embed.
-    _denseVectors = new Map();
-    _denseIndex = null;
-    /** Signature of the fact set the current index was built from. */
-    _denseSig = '';
-    /** Identity of the runtime whose embeddings populated the vectors. */
-    _denseRuntime = null;
+    _scope;
+    /** The unit-of-work layer every durable operation flows through. */
+    repository;
+    _storage;
+    /** Cross-context subscription, opened on the first operation (see `_ready`). */
+    _unsubscribe;
+    _subscribed = false;
+    _sweeper = new TtlSweeper();
+    /** Ranking + its embedding / dense-index caches (EVM-1, EVM-1b, EVM-8). */
+    _recall;
+    /**
+     * Last store generation observed from a FOREIGN context (another tab,
+     * window or process). Monotonic, in-memory only; lets readers notice
+     * cross-context writes without a storage round-trip per recall (M05).
+     */
+    _foreignRevision = 0;
     constructor(opts = {}) {
-        this._dbName = opts.dbName ?? 'ssmjs';
         this._weightsKey = opts.weightsKey ?? 'ssmjs-weights';
-        this._idb = opts.idbFactory;
         this._defaultTtl = opts.defaultTtlMs;
-        this._annThreshold = opts.annThreshold ?? 256;
         this._maxEntries = opts.maxEntries;
-        this._embedCacheMax = opts.embedCacheMax ?? EMBED_CACHE_MAX;
-    }
-    // ── Internal DB open ──────────────────────────────────────────────────────
-    _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 SSMError('MEMORY_UNAVAILABLE', 'IndexedDB is not available in this environment. Pass an idbFactory option (e.g. from fake-indexeddb) for Node.js support.'));
-                return;
-            }
-            const req = factory.open(this._dbName, DB_VERSION);
-            req.onupgradeneeded = (e) => {
-                const db = e.target.result;
-                if (!db.objectStoreNames.contains(FACTS_STORE)) {
-                    db.createObjectStore(FACTS_STORE, { keyPath: 'key' });
-                }
-                if (!db.objectStoreNames.contains(WEIGHTS_STORE)) {
-                    db.createObjectStore(WEIGHTS_STORE);
-                }
-            };
-            req.onsuccess = () => {
-                this._db = req.result;
-                resolve(req.result);
-            };
-            /* istanbul ignore next -- IDB open onerror fires only on storage faults; not reproducible with fake-indexeddb */
-            req.onerror = () => reject(new SSMError('MEMORY_UNAVAILABLE', `Failed to open IndexedDB "${this._dbName}": ${req.error?.message ?? 'unknown'}`, req.error));
+        this._recall = new SemanticRecall({
+            annThreshold: opts.annThreshold ?? 256,
+            embedCacheMax: opts.embedCacheMax ?? EMBED_CACHE_MAX,
+            // Opt-in floor: 0 keeps recall returning its best hits, as it always did.
+            minRelevance: opts.minRelevance ?? 0,
+        });
+        this._scope = opts.scope ? { ...opts.scope } : {};
+        this._storage = opts.storage ?? new IdbStorageAdapter(opts.dbName ?? 'ssmjs', {
+            idbFactory: opts.idbFactory,
+            contextId: opts.contextId,
         });
+        this.repository = new ScopedFactRepository(this._storage, {
+            syncEnabled: opts.sync ?? false,
+            contextId: opts.contextId,
+        });
+    }
+    /**
+     * Cross-context invalidation (M05): a sibling tab/window/process that
+     * commits against the same storage invalidates this instance's derived
+     * caches. Subscribed lazily on the first operation: before it there are no
+     * caches to invalidate, and an eager subscription opened a global
+     * BroadcastChannel in the constructor that kept Node processes alive.
+     */
+    _ready() {
+        if (this._subscribed)
+            return;
+        this._subscribed = true;
+        this._unsubscribe = this.repository.subscribe((note) => this._onForeignChange(note));
+    }
+    /** The scope partition this store is bound to (never widened implicitly). */
+    get scope() {
+        return { ...this._scope };
+    }
+    /** The durable storage backend kind in use ('indexedDB' | 'node-file'). */
+    get storageKind() {
+        return this._storage.kind;
     }
-    // ── TTL helpers ───────────────────────────────────────────────────────────
-    _isExpired(entry) {
-        if (entry.ttlMs == null)
-            return false;
-        return Date.now() > entry.timestamp + entry.ttlMs;
+    /**
+     * Best-effort in-memory token that changes when another context writes to
+     * this store's database. Readers (e.g. EvermindCognition's recall cache)
+     * can fold it into their cache key so cross-context writes invalidate
+     * without a storage hit per recall.
+     */
+    get foreignRevision() {
+        return this._foreignRevision;
+    }
+    _onForeignChange(note) {
+        if (note.revision <= this._foreignRevision)
+            return;
+        this._foreignRevision = note.revision;
+        // Derived caches describe a fact set another context just changed.
+        this._recall.invalidate();
     }
     // ── Semantic facts ────────────────────────────────────────────────────────
-    /** Stores or overwrites a fact. */
+    /**
+     * Stores or overwrites a fact. Resolves only after the underlying
+     * transaction commits durably (M02); the fact, its provenance and its sync
+     * journal entry commit atomically.
+     */
     async remember(key, content, opts) {
-        const db = await this._open();
-        const entry = {
-            key,
-            content,
-            timestamp: Date.now(),
-            seq: ++_writeSeq,
-            ttlMs: opts?.ttlMs ?? this._defaultTtl,
-            type: opts?.type,
-            tags: opts?.tags,
-            importance: opts?.importance,
-        };
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        await requestToPromise(tx.objectStore(FACTS_STORE).put(entry), `Failed to store fact "${key}"`, () => undefined);
-        // EVM-7: keep the store bounded — evict lowest-value entries past the cap.
-        if (this._maxEntries != null)
-            await this._enforceCap();
+        this._ready();
+        await this.repository.remember(this._scope, key, rememberInput(content, opts, this._defaultTtl));
+        // EVM-7: keep the store bounded — evict lowest-value SYNCED entries past
+        // the cap; unsynced knowledge is never sacrificed to a cache cap (M06).
+        if (this._maxEntries != null) {
+            await this.repository.evictForCap(this._scope, this._maxEntries, isExpired);
+        }
     }
     /**
-     * Evicts the lowest-value entries until at most `maxEntries` remain. Eviction
-     * priority (removed first): expired → lowest importance → oldest. No-op when
-     * no cap is set or the store is under it. (EVM-7)
+     * Compare-and-set write (M04/M05): commits only if the record's current
+     * revision equals `expectedRevision` (`null` asserts the key is absent).
+     * Throws a MemoryStorageError otherwise (`code` 'MEMORY_CONFLICT',
+     * `storageCode` 'STORAGE_CONFLICT'; see `isStorageConflict`) — callers reconcile
+     * (re-read, re-evaluate evidence) instead of blindly overwriting a
+     * concurrent writer. Returns the committed entry.
      */
-    async _enforceCap() {
-        if (this._maxEntries == null)
-            return;
-        const db = await this._open();
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        const all = await requestToPromise(tx.objectStore(FACTS_STORE).getAll(), 'Failed to scan facts for cap', (r) => r);
-        if (all.length <= this._maxEntries)
-            return;
-        // Ascending sort = worst first: expired (0) before live (1), then lower
-        // importance, then older timestamp, then lower write sequence.
-        const rank = (e) => [this._isExpired(e) ? 0 : 1, e.importance ?? 0.5, e.timestamp, e.seq ?? 0];
-        const sorted = [...all].sort((a, b) => {
-            const ra = rank(a), rb = rank(b);
-            for (let i = 0; i < ra.length; i++) {
-                if (ra[i] !== rb[i])
-                    return ra[i] - rb[i];
-            }
-            return 0;
+    async rememberCas(key, content, expectedRevision, opts) {
+        this._ready();
+        const { record } = await this.repository.remember(this._scope, key, {
+            ...rememberInput(content, opts, this._defaultTtl),
+            expectedRevision,
         });
-        const victims = sorted.slice(0, all.length - this._maxEntries);
-        await Promise.all(victims.map((e) => this.forget(e.key)));
+        return toEntry(record);
+    }
+    /** Fetches an entry WITH its durable revision, for CAS-based reconciliation. */
+    async recallVersioned(key) {
+        return this.recall(key);
     }
     /**
-     * Starts a background timer that periodically hard-deletes expired entries —
+     * Starts a background timer that periodically deletes expired entries —
      * TTL is otherwise only evaluated lazily on read, so an idle store would keep
      * dead entries forever. Idempotent; pair with {@link stopTtlSweeper}. (EVM-7)
+     *
+     * With sync enabled each expiry is a scoped deletion (tombstone + journal),
+     * not a silent drop (M06).
      */
     startTtlSweeper(intervalMs) {
-        if (this._sweepTimer)
-            return;
-        const timer = setInterval(() => { void this.purgeExpired(); }, intervalMs);
-        // Don't keep a Node process alive just for the sweeper.
-        const maybeUnref = timer;
-        /* istanbul ignore else -- unref exists in Node; absent in the browser */
-        if (typeof maybeUnref.unref === 'function') {
-            maybeUnref.unref();
-        }
-        this._sweepTimer = timer;
+        this._sweeper.start(intervalMs, () => this.purgeExpired());
     }
     /** Stops the background TTL sweeper started by {@link startTtlSweeper}. */
     stopTtlSweeper() {
-        if (this._sweepTimer) {
-            clearInterval(this._sweepTimer);
-            this._sweepTimer = null;
-        }
+        this._sweeper.stop();
     }
     /**
-     * Retrieves a fact by key.
+     * Retrieves a fact by key from this store's scope partition.
      * Returns `undefined` if the key does not exist or the entry has expired.
      */
     async recall(key) {
-        const db = await this._open();
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        return requestToPromise(tx.objectStore(FACTS_STORE).get(key), `Failed to recall fact "${key}"`, (entry) => (entry && this._isExpired(entry) ? undefined : entry));
+        this._ready();
+        const record = await this.repository.get(this._scope, key);
+        if (!record || isExpired(record))
+            return undefined;
+        return toEntry(record);
     }
-    /** Returns all non-expired stored facts, newest first. */
+    /** Returns all non-expired stored facts in this store's scope, newest first. */
     async recallAll() {
-        const db = await this._open();
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        return requestToPromise(tx.objectStore(FACTS_STORE).getAll(), 'Failed to recall all facts', (entries) => entries
-            .filter(e => !this._isExpired(e))
-            // Newest first; break same-millisecond ties by write sequence so
-            // ordering is deterministic (IndexedDB getAll() returns key order,
-            // which would otherwise surface same-ms writes oldest-first).
-            .sort((a, b) => b.timestamp - a.timestamp || (b.seq ?? 0) - (a.seq ?? 0)));
+        this._ready();
+        return liveEntries(await this.repository.getAll(this._scope));
     }
     /**
      * Returns the N most recently updated non-expired facts.
@@ -190,22 +179,18 @@ export class MemoryStore {
     }
     /**
      * Returns all non-expired entries that contain the given tag.
+     * Looks the tag up on the facts `byTag` index when the storage adapter has
+     * one; a full scan is used only when that index is missing.
      */
     async recallByTag(tag) {
-        const all = await this.recallAll();
-        return all.filter(e => e.tags?.includes(tag) ?? false);
+        this._ready();
+        return liveEntries(await this.repository.getByTag(this._scope, tag));
     }
     /**
-     * Finds the top-K semantically similar entries to `query`.
-     *
-     * When `runtime` exposes an `embed()` method (the SSMRuntime does), similarity
-     * is computed as cosine distance between SSM hidden-state embeddings — i.e. the
-     * memory layer uses the very model it is attached to, and recall quality
-     * improves automatically as that model is adapted/distilled. Embeddings are
-     * cached per content string to avoid recomputing across calls.
-     *
-     * If no embedding-capable runtime is provided, or embedding fails for any
-     * reason, it transparently falls back to Jaccard word-overlap similarity.
+     * Finds the top-K semantically similar entries to `query`: cosine over the
+     * attached SSM runtime's embeddings (so recall improves as that model is
+     * adapted), or Jaccard word overlap when no runtime can embed. See
+     * {@link SemanticRecall}.
      */
     async recallSimilar(query, topK, runtime) {
         return (await this.recallSimilarScored(query, topK, runtime)).map(s => s.entry);
@@ -217,263 +202,106 @@ export class MemoryStore {
      * {@link recallSimilar} is the score-dropping convenience wrapper over this.
      */
     async recallSimilarScored(query, topK, runtime) {
-        const all = await this.recallAll();
-        if (all.length === 0)
-            return [];
-        // ── Preferred path: SSM-embedding cosine similarity ───────────────────
-        if (runtime != null && typeof runtime.embed === 'function') {
-            const queryVec = await this._embedWithCache(runtime, query);
-            if (queryVec) {
-                // EVM-1b: sync the persistent vector store + index (embeds only the
-                // delta), then query it — no per-call re-embed of every fact.
-                const synced = await this._syncDense(runtime, all);
-                if (synced) {
-                    const hits = synced.index
-                        // EVM-1: above the threshold, query the persistent HNSW (O(log N)).
-                        ? synced.index.search(queryVec, topK)
-                        // Below it, an exact scan over the (already-embedded) vectors.
-                        : denseSearch(queryVec, synced.items, topK, this._annThreshold);
-                    return hits
-                        .map(h => { const entry = synced.byKey.get(h.id); return entry ? { entry, score: h.score } : null; })
-                        .filter((e) => !!e);
-                }
-            }
-            // Any failure falls through to the Jaccard path below.
-        }
-        // ── Fallback: Jaccard word-overlap similarity ─────────────────────────
-        const queryTokens = new Set(tokenize(query));
-        const scored = all.map(entry => {
-            const entryTokens = new Set(tokenize(entry.content));
-            const score = jaccardSimilarity(queryTokens, entryTokens);
-            return { entry, score };
-        });
-        scored.sort((a, b) => b.score - a.score);
-        return scored.slice(0, topK);
+        return this._recall.similar(await this.recallAll(), query, topK, runtime);
     }
     /**
-     * Hybrid recall: fuses dense (SSM-embedding cosine) and sparse (BM25 lexical)
-     * rankings via Reciprocal Rank Fusion, then applies an MMR diversity rerank.
-     *
-     * This is the production RAG retrieval path — it catches both semantic matches
-     * (embeddings) and exact-token matches (BM25 — identifiers, codes, rare names)
-     * that cosine-only `recallSimilar` misses, and avoids returning near-duplicate
-     * facts. Degrades to BM25-only when no embedding-capable runtime is available,
-     * so it is always strictly at least as good as the lexical fallback.
+     * Hybrid recall: dense (SSM-embedding cosine) and sparse (BM25) rankings
+     * fused by Reciprocal Rank Fusion, then an MMR diversity rerank — catches
+     * exact-token matches cosine misses, and degrades to BM25 alone without a
+     * runtime. The production RAG path.
      */
     async recallHybrid(query, topK, runtime, opts) {
         return (await this.recallRanked(query, topK, runtime, opts)).hits.map(h => h.entry);
     }
     /**
-     * The hybrid retrieval path with its evidence attached: each hit's fused score,
-     * plus WHICH ranker produced the ordering.
-     *
-     * {@link recallHybrid} is the convenience wrapper that throws both away, so
-     * there is exactly one implementation of the blend — and it is the shared
-     * `hybridRetrieve` → `reciprocalRankFusion` primitive, never a second hand-
-     * rolled mix of cosine and word overlap.
-     *
-     * `method` is honest rather than aspirational: `'embedding'` means the query
-     * really did embed and the dense ranking really did participate in the fusion;
-     * `'lexical'` means no model was available (or embedding failed) and the
-     * ordering is BM25 alone. Callers surface it so a user can tell semantic
-     * recall from the fallback instead of guessing.
+     * {@link recallHybrid} with its evidence: each hit's fused score, and WHICH
+     * ranker produced the ordering — `'embedding'` only when the query and the
+     * candidates really embedded, `'lexical'` when the ordering is BM25 alone.
+     * One blend implementation: the shared `hybridRetrieve` primitive.
      */
     async recallRanked(query, topK, runtime, opts) {
-        const all = await this.recallAll();
-        if (all.length === 0)
-            return { hits: [], method: 'lexical' };
-        // Embed candidates + query where a runtime is available; null vectors are
-        // fine — hybridRetrieve degrades that candidate to BM25-only.
-        const canEmbed = runtime != null && typeof runtime.embed === 'function';
-        const queryVec = canEmbed ? (await this._embedWithCache(runtime, query)) ?? undefined : undefined;
-        const candidates = [];
-        for (const entry of all) {
-            const vector = queryVec ? (await this._embedWithCache(runtime, entry.content)) ?? undefined : undefined;
-            candidates.push({ id: entry.key, text: entry.content, vector });
-        }
-        // The dense ranking only exists when the query embedded AND at least one
-        // candidate did — anything less is a lexical ordering wearing a label.
-        const dense = !!queryVec && candidates.some(c => !!c.vector);
-        const hits = hybridRetrieve({ text: query, vector: queryVec }, candidates, { topK, annThreshold: this._annThreshold, ...opts });
-        const byKey = new Map(all.map(e => [e.key, e]));
-        return {
-            hits: hits
-                .map(h => { const entry = byKey.get(h.id); return entry ? { entry, score: h.score } : null; })
-                .filter((h) => !!h),
-            method: dense ? 'embedding' : 'lexical',
-        };
-    }
-    /**
-     * Returns a cached embedding for `text`, computing it via `runtime.embed()`
-     * on a cache miss. Returns `null` (never throws) when embedding is
-     * unavailable so callers can fall back to lexical similarity.
-     */
-    async _embedWithCache(runtime, text) {
-        // Embeddings are model-specific: if the runtime instance changed, the cached
-        // vectors are from a different model and must be dropped. (EVM-1b)
-        if (runtime !== this._embedRuntime) {
-            this._embedCache.clear();
-            this._embedRuntime = runtime;
-        }
-        const cached = this._embedCache.get(text);
-        if (cached) {
-            // LRU touch: re-insert so this entry becomes most-recently-used. (EVM-8)
-            this._embedCache.delete(text);
-            this._embedCache.set(text, cached);
-            return cached;
-        }
-        try {
-            const vec = await runtime.embed(text);
-            if (vec instanceof Float32Array && vec.length > 0) {
-                // EVM-8: bound cache growth by evicting the LEAST-recently-used entry
-                // (Map keeps insertion order; the first key is the LRU), instead of
-                // dumping the whole cache on every overflow.
-                if (this._embedCache.size >= this._embedCacheMax) {
-                    const lru = this._embedCache.keys().next().value;
-                    if (lru !== undefined)
-                        this._embedCache.delete(lru);
-                }
-                this._embedCache.set(text, vec);
-                return vec;
-            }
-        }
-        catch {
-            // Embedding unavailable (no GPU, destroyed runtime, etc.) — signal fallback.
-        }
-        return null;
+        return this._recall.ranked(await this.recallAll(), query, topK, runtime, opts);
     }
     /**
-     * Synchronise the persistent dense vector store + HNSW index to `all` (EVM-1b).
-     * Embeds ONLY new/changed facts (keyed by `key@seq`), prunes removed ones, and
-     * rebuilds the index only when the fact set actually changed — so a read-heavy
-     * workload reuses both the embeddings and the index across recalls. Returns
-     * `null` (caller falls back to lexical) if any embedding is unavailable, or
-     * resets everything when the runtime identity changes (embeddings are
-     * model-specific).
-     */
-    async _syncDense(runtime, all) {
-        if (runtime !== this._denseRuntime) {
-            this._denseVectors.clear();
-            this._denseIndex = null;
-            this._denseSig = '';
-            this._denseRuntime = runtime;
-        }
-        const vkeyOf = (e) => `${e.key}@${e.seq ?? 0}`;
-        const currentVkeys = new Set();
-        let sig = `${all.length}`;
-        for (const e of all) {
-            const k = vkeyOf(e);
-            currentVkeys.add(k);
-            sig += '|' + k;
-        }
-        const byKey = new Map();
-        const items = [];
-        for (const entry of all) {
-            const vk = vkeyOf(entry);
-            let vec = this._denseVectors.get(vk);
-            if (!vec) {
-                const v = await this._embedWithCache(runtime, entry.content);
-                if (!v)
-                    return null; // embedding failed → lexical fallback
-                vec = v;
-                this._denseVectors.set(vk, vec);
-            }
-            items.push({ id: entry.key, vector: vec });
-            byKey.set(entry.key, entry);
-        }
-        // Drop vectors for facts that are gone or were edited (stale vkeys).
-        if (this._denseVectors.size > currentVkeys.size) {
-            for (const k of this._denseVectors.keys()) {
-                if (!currentVkeys.has(k))
-                    this._denseVectors.delete(k);
-            }
-        }
-        // Maintain the ANN index only above the threshold; (re)build it only when
-        // the fact set changed (no embedding involved — purely in-memory).
-        if (all.length >= this._annThreshold) {
-            if (sig !== this._denseSig || this._denseIndex === null) {
-                const index = new HnswIndex();
-                for (const it of items)
-                    index.add(it.id, it.vector);
-                this._denseIndex = index;
-            }
-        }
-        else {
-            this._denseIndex = null;
-        }
-        this._denseSig = sig;
-        return { byKey, items, index: this._denseIndex };
-    }
-    /**
-     * Hard-deletes all entries whose TTL has expired.
+     * Deletes all entries whose TTL has expired. With sync enabled each expiry
+     * commits a tombstone + journal entry in the same transaction, so expiries
+     * propagate instead of resurrecting from a replica (M06).
      * @returns The number of entries deleted.
      */
     async purgeExpired() {
-        const db = await this._open();
-        // Load all raw entries (including expired ones) to check each
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        const all = await requestToPromise(tx.objectStore(FACTS_STORE).getAll(), 'Failed to scan facts for purge', (r) => r);
-        const expired = all.filter(e => this._isExpired(e));
-        if (expired.length === 0)
-            return 0;
-        await Promise.all(expired.map(e => this.forget(e.key)));
-        return expired.length;
+        this._ready();
+        return this.repository.purgeExpired(this._scope, isExpired);
     }
-    /** Deletes a single fact. No-op if key does not exist. */
+    /**
+     * Deletes a single fact. No-op if key does not exist. With sync enabled the
+     * delete is a durable tombstone + journal entry committed atomically (M04).
+     */
     async forget(key) {
-        const db = await this._open();
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        return requestToPromise(tx.objectStore(FACTS_STORE).delete(key), `Failed to forget fact "${key}"`, () => undefined);
+        this._ready();
+        await this.repository.forget(this._scope, key);
     }
-    /** Deletes all facts. Does not affect saved weights. */
+    /** Deletes all facts in this store's scope. Does not affect saved weights. */
     async clear() {
-        const db = await this._open();
         // Drop the persistent dense index/vectors too (EVM-1b) — they describe a
         // fact set that no longer exists.
-        this._denseVectors.clear();
-        this._denseIndex = null;
-        this._denseSig = '';
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        return requestToPromise(tx.objectStore(FACTS_STORE).clear(), 'Failed to clear facts', () => undefined);
+        this._ready();
+        this._recall.resetDense();
+        await this.repository.clear(this._scope);
+    }
+    // ── Sync protocol surface (M04) ───────────────────────────────────────────
+    /** Operations not yet acknowledged by sync — the pending knowledge set. */
+    async pendingOps() {
+        return this.repository.pendingOps();
+    }
+    /** Delete tombstones in this store's scope (or all scopes when omitted). */
+    async tombstones(scope) {
+        return this.repository.tombstones(scope);
+    }
+    /**
+     * Acknowledges that the given operations reached the sync target. Their
+     * facts/tombstones stop being `pendingSync`, so retention may touch them
+     * again. Retention NEVER touches unacknowledged knowledge (M06).
+     */
+    async markSynced(opIds) {
+        await this.repository.markSynced(opIds);
+    }
+    /** The current durable store generation. */
+    async revision() {
+        return this.repository.revision();
+    }
+    /** Releases cross-context subscriptions and the underlying connection. */
+    close() {
+        this.stopTtlSweeper();
+        this._unsubscribe?.();
+        this._unsubscribe = undefined;
+        this._storage.close?.();
     }
     // ── Cross-session memory merge ────────────────────────────────────────────
     /**
      * Returns all non-expired facts as a plain array for export.
-     * Suitable for serialisation and import into another MemoryStore instance.
+     * Scope, revision and provenance travel with each entry (M03).
      */
     async exportAll() {
         return this.recallAll();
     }
     /**
-     * Imports entries from an external array.
+     * Imports entries from an external array INTO this store's scope partition.
+     * Source timestamps, sequences, tags, importance, TTL and provenance are
+     * preserved — import never rewrites source time (M06).
      *
      * - `'merge'`     : only writes an entry if no existing entry with the same
      *                   key exists, or if the incoming entry has a newer timestamp.
      * - `'overwrite'` : writes all entries unconditionally.
      */
-    async importAll(entries, strategy) {
-        for (const entry of entries) {
-            if (strategy === 'overwrite') {
-                await this._putRaw(entry);
-            }
-            else {
-                const existing = await this.recall(entry.key);
-                if (existing == null || entry.timestamp > existing.timestamp) {
-                    await this._putRaw(entry);
-                }
-            }
-        }
-    }
-    /** Writes a raw MemoryEntry directly (preserves original timestamp / metadata). */
-    async _putRaw(entry) {
-        const db = await this._open();
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        return requestToPromise(tx.objectStore(FACTS_STORE).put(entry), `Failed to import fact "${entry.key}"`, () => undefined);
+    async importAll(entries, strategy, importedFrom) {
+        this._ready();
+        const records = entries.map((e) => toImportRecord(e, this._scope));
+        await this.repository.importRecords(this._scope, records, strategy, importedFrom);
     }
     // ── Weight persistence ────────────────────────────────────────────────────
     /**
      * Saves SSM weights via `runtime.save()`.
-     * The weights are stored under `weightsKey` in this store's IndexedDB,
+     * The weights are stored under `weightsKey` in the session's IndexedDB,
      * separate from MambaSession's own key.
      */
     async saveWeights(runtime) {
@@ -487,22 +315,6 @@ export class MemoryStore {
         return runtime.load({ key: this._weightsKey });
     }
 }
-// ── IndexedDB helper ──────────────────────────────────────────────────────────
-/**
- * Wires an IDBRequest to a promise: resolves with `map(result)` on success,
- * rejects with a normalised MEMORY_UNAVAILABLE error on failure. Extracted so
- * the success/error wiring lives in one place instead of being duplicated across
- * every store method.
- *
- * The onerror branch fires only on IndexedDB storage faults (quota exceeded,
- * disk failure, corruption), which the in-memory fake-indexeddb used in tests
- * cannot reproduce — hence the istanbul ignore on that single line.
- */
-function requestToPromise(req, failMsg, map) {
-    return new Promise((resolve, reject) => {
-        req.onsuccess = () => resolve(map(req.result));
-        /* istanbul ignore next -- IDB storage-fault path; not reproducible with fake-indexeddb */
-        req.onerror = () => reject(new SSMError('MEMORY_UNAVAILABLE', `${failMsg}: ${req.error?.message ?? 'unknown'}`, req.error ?? undefined));
-    });
-}
+// Re-export the storage seam so consumers reach it through the store's module.
+export { IdbStorageAdapter, ScopedFactRepository, MemoryStorageError, };
 //# sourceMappingURL=MemoryStore.js.map