@seanhogg/builderforce-memory 2026.9.34 → 2026.10.2

package/dist/errors/SSMError.d.ts

@@ -5,7 +5,7 @@
  * Runtime-level failures (bridge, distillation, memory) throw SSMError.
  * Both carry a typed `code` discriminant for programmatic handling.
  */
-export type SSMErrorCode = 'RUNTIME_DESTROYED' | 'BRIDGE_REQUEST_FAILED' | 'BRIDGE_RESPONSE_INVALID' | 'MEMORY_UNAVAILABLE' | 'DISTILL_FAILED' | 'UNKNOWN';
+export type SSMErrorCode = 'RUNTIME_DESTROYED' | 'BRIDGE_REQUEST_FAILED' | 'BRIDGE_RESPONSE_INVALID' | 'MEMORY_UNAVAILABLE' | 'MEMORY_CONFLICT' | 'DISTILL_FAILED' | 'UNKNOWN';
 export declare class SSMError extends Error {
     readonly code: SSMErrorCode;
     readonly cause?: unknown | undefined;

package/dist/errors/SSMError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SSMError.d.ts","sourceRoot":"","sources":["../../src/errors/SSMError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAClB,mBAAmB,GACnB,uBAAuB,GACvB,yBAAyB,GACzB,oBAAoB,GACpB,gBAAgB,GAChB,SAAS,CAAC;AAEhB,qBAAa,QAAS,SAAQ,KAAK;aAEX,IAAI,EAAE,YAAY;aAElB,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,YAAY,EAClC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKtC"}
+{"version":3,"file":"SSMError.d.ts","sourceRoot":"","sources":["../../src/errors/SSMError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAClB,mBAAmB,GACnB,uBAAuB,GACvB,yBAAyB,GACzB,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,SAAS,CAAC;AAEhB,qBAAa,QAAS,SAAQ,KAAK;aAEX,IAAI,EAAE,YAAY;aAElB,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,YAAY,EAClC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKtC"}

package/dist/errors/SSMError.js.map

@@ -1 +1 @@
-{"version":3,"file":"SSMError.js","sourceRoot":"","sources":["../../src/errors/SSMError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAEX;IAEA;IAHpB,YACoB,IAAkB,EAClC,OAAe,EACC,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAc;QAElB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IAC3B,CAAC;CACJ"}
+{"version":3,"file":"SSMError.js","sourceRoot":"","sources":["../../src/errors/SSMError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAEX;IAEA;IAHpB,YACoB,IAAkB,EAClC,OAAe,EACC,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAc;QAElB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IAC3B,CAAC;CACJ"}

package/dist/handoff/index.d.ts

@@ -2,11 +2,11 @@
  * Model hand-off packing — the `@seanhogg/builderforce-memory/handoff` subpath (PRD 34 §3.3).
  *
  * When a conversation moves to another model (a local one with a small window, say),
- * {@link packHandoff} fits the transcript into that model's budget: the system message(s)
- * stay, the latest user directive stays verbatim, tool calls are never split from their
- * results, the verbatim tail takes what the budget allows, and the dropped middle becomes
- * ONE assistant note (summary → memory recall → elision marker, with a one-line hand-off
- * note when the models differ).
+ * {@link packHandoff} fits the transcript into that model's budget: the leading system
+ * message(s) stay first, the latest user directive stays verbatim, tool calls are never
+ * split from their results, the verbatim tail takes what the budget allows, and the
+ * dropped middle becomes ONE note (summary → memory recall → elision marker, with a
+ * one-line hand-off note when the models differ) whose role keeps turns alternating.
  *
  * Pure: no WebGPU, no IndexedDB, no `node:*` — runs in a Cloudflare Worker, a browser
  * page and Node alike.

package/dist/handoff/index.js

@@ -2,11 +2,11 @@
  * Model hand-off packing — the `@seanhogg/builderforce-memory/handoff` subpath (PRD 34 §3.3).
  *
  * When a conversation moves to another model (a local one with a small window, say),
- * {@link packHandoff} fits the transcript into that model's budget: the system message(s)
- * stay, the latest user directive stays verbatim, tool calls are never split from their
- * results, the verbatim tail takes what the budget allows, and the dropped middle becomes
- * ONE assistant note (summary → memory recall → elision marker, with a one-line hand-off
- * note when the models differ).
+ * {@link packHandoff} fits the transcript into that model's budget: the leading system
+ * message(s) stay first, the latest user directive stays verbatim, tool calls are never
+ * split from their results, the verbatim tail takes what the budget allows, and the
+ * dropped middle becomes ONE note (summary → memory recall → elision marker, with a
+ * one-line hand-off note when the models differ) whose role keeps turns alternating.
  *
  * Pure: no WebGPU, no IndexedDB, no `node:*` — runs in a Cloudflare Worker, a browser
  * page and Node alike.

package/dist/handoff/note.d.ts

@@ -1,5 +1,5 @@
 /**
- * The ONE assistant note that stands in for the dropped middle of a handed-off
+ * The ONE note that stands in for the dropped middle of a handed-off
  * transcript: an optional one-line hand-off note, then the first body source that
  * succeeds — the `summarize` result, else the `recall` memory block for the latest
  * directive, else an elision marker. A failing, timing-out or empty source falls through

package/dist/handoff/note.js

@@ -1,5 +1,5 @@
 /**
- * The ONE assistant note that stands in for the dropped middle of a handed-off
+ * The ONE note that stands in for the dropped middle of a handed-off
  * transcript: an optional one-line hand-off note, then the first body source that
  * succeeds — the `summarize` result, else the `recall` memory block for the latest
  * directive, else an elision marker. A failing, timing-out or empty source falls through

package/dist/handoff/pack.d.ts

@@ -4,13 +4,22 @@
  * Shape of the result, mirroring Builderforce's `assembleCompacted`
  * (brain-embedded/src/workingTranscript.ts):
  *
- *   system message(s) · ONE assistant note for the dropped middle · the latest user
+ *   leading system message(s) · ONE note for the dropped middle · the latest user
  *   directive re-injected verbatim (only when it fell in the middle) · the verbatim tail
  *
+ * Only the LEADING run of system messages is the fixed prefix. A system message later in
+ * the conversation stays where it was: in the tail when the tail reaches it, else in the
+ * dropped middle — never hoisted to the front, where it would read as if it governed the
+ * whole conversation.
+ *
+ * The note's role keeps turns alternating: it is an `assistant` note when a user turn (the
+ * re-injected directive, or a tail that starts with one) follows it, and a `user` note
+ * when an assistant turn follows or nothing does — never two assistant turns in a row.
+ *
  * The tail is the longest run of whole units (see `segments.ts`) from the end that fits
- * what is left after the system message(s), the directive and room for an elision marker.
- * Whatever room the tail leaves is the note's: summary, else recall, else the marker.
- * The result never exceeds the budget unless the system message(s) + directive alone do.
+ * what is left after the prefix, the directive and room for an elision marker. Whatever
+ * room the tail leaves is the note's: summary, else recall, else the marker. The result
+ * never exceeds the budget unless the prefix + directive alone do.
  */
 import type { HandoffPack, HandoffPackInput } from './types.js';
 export declare function packHandoff(input: HandoffPackInput): Promise<HandoffPack>;

package/dist/handoff/pack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/handoff/pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAkB,WAAW,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AA6DhG,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAqD/E"}
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/handoff/pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAkB,WAAW,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AAyEhG,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuD/E"}

package/dist/handoff/pack.js

@@ -4,17 +4,37 @@
  * Shape of the result, mirroring Builderforce's `assembleCompacted`
  * (brain-embedded/src/workingTranscript.ts):
  *
- *   system message(s) · ONE assistant note for the dropped middle · the latest user
+ *   leading system message(s) · ONE note for the dropped middle · the latest user
  *   directive re-injected verbatim (only when it fell in the middle) · the verbatim tail
  *
+ * Only the LEADING run of system messages is the fixed prefix. A system message later in
+ * the conversation stays where it was: in the tail when the tail reaches it, else in the
+ * dropped middle — never hoisted to the front, where it would read as if it governed the
+ * whole conversation.
+ *
+ * The note's role keeps turns alternating: it is an `assistant` note when a user turn (the
+ * re-injected directive, or a tail that starts with one) follows it, and a `user` note
+ * when an assistant turn follows or nothing does — never two assistant turns in a row.
+ *
  * The tail is the longest run of whole units (see `segments.ts`) from the end that fits
- * what is left after the system message(s), the directive and room for an elision marker.
- * Whatever room the tail leaves is the note's: summary, else recall, else the marker.
- * The result never exceeds the budget unless the system message(s) + directive alone do.
+ * what is left after the prefix, the directive and room for an elision marker. Whatever
+ * room the tail leaves is the note's: summary, else recall, else the marker. The result
+ * never exceeds the budget unless the prefix + directive alone do.
  */
 import { defaultEstimateTokens, handoffBudget, messageTokens, tokensOf } from './budget.js';
 import { buildNote, composeNote, elisionMarker, handoffLine, noteTokens } from './note.js';
 import { segmentTranscript } from './segments.js';
+/** Length of the leading run of `system` messages. */
+function leadingSystemCount(all) {
+    let n = 0;
+    while (n < all.length && all[n].role === 'system')
+        n += 1;
+    return n;
+}
+/** The note's role: `user` before an assistant turn (or at the end), else `assistant`. */
+function noteRole(next) {
+    return next === undefined || next.role === 'assistant' ? 'user' : 'assistant';
+}
 /** Index of the last `user` message, or -1. */
 function latestDirectiveIndex(convo) {
     for (let i = convo.length - 1; i >= 0; i--)
@@ -64,8 +84,9 @@ export async function packHandoff(input) {
     // Under budget: hand the transcript over untouched.
     if (tokensOf(all, estimate) <= budget)
         return result(all.slice(), 0, estimate);
-    const system = all.filter((m) => m.role === 'system');
-    const convo = all.filter((m) => m.role !== 'system');
+    const prefixLen = leadingSystemCount(all);
+    const system = all.slice(0, prefixLen);
+    const convo = all.slice(prefixLen);
     const systemTokens = tokensOf(system, estimate);
     const directiveIdx = latestDirectiveIndex(convo);
     const directive = directiveIdx >= 0 ? convo[directiveIdx] : undefined;
@@ -96,12 +117,12 @@ export async function packHandoff(input) {
             timeoutMs: input.timeoutMs,
         })
         : null;
+    const after = reinject && directive ? [directive] : [];
+    after.push(...convo.slice(tail.start));
     const messages = [...system];
     if (note)
-        messages.push({ role: 'assistant', content: note.text });
-    if (reinject && directive)
-        messages.push(directive);
-    messages.push(...convo.slice(tail.start));
+        messages.push({ role: noteRole(after[0]), content: note.text });
+    messages.push(...after);
     return result(messages, droppedMsgs.length, estimate, {
         summarized: note?.summarized ?? false,
         recalled: note?.recalled ?? false,

package/dist/handoff/pack.js.map

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

package/dist/memory/MemoryStore.d.ts

@@ -1,149 +1,104 @@
 /**
  * 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 { type HybridRetrieveOptions } from '../retrieval/index.js';
-export type FactType = 'text' | 'json' | 'number' | 'boolean';
-export interface MemoryEntry {
-    key: string;
-    content: string;
-    timestamp: number;
-    /**
-     * Monotonic write sequence, used only to break `timestamp` ties so that
-     * ordering stays deterministic when several entries are written within the
-     * same millisecond (Date.now() resolution). Higher = written later.
-     * Optional for backward compatibility with entries persisted/imported
-     * before this field existed (those sort as seq 0).
-     */
-    seq?: number;
-    /** Optional time-to-live in milliseconds. */
-    ttlMs?: number;
-    /** Semantic type of the stored value. Default: 'text'. */
-    type?: FactType;
-    /** Tags for grouping and filtering. */
-    tags?: string[];
-    /** Importance weight in the range 0–1. Default: 0.5. */
-    importance?: number;
-}
-/**
- * Which ranker produced a recall ordering. Matches the vocabulary the gateway's
- * Evermind recall/validate surfaces already report, so a host can render one chip
- * ("Semantic recall" / "Lexical recall (fallback)") regardless of which layer
- * answered.
- */
-export type RecallMethod = 'embedding' | 'lexical';
-/** A recalled entry with its relevance score (higher = closer). */
-export interface ScoredMemory {
-    entry: MemoryEntry;
-    score: number;
-}
-/** A ranked recall: the hits plus the ranker that ordered them. */
-export interface RankedRecall {
-    hits: ScoredMemory[];
-    method: RecallMethod;
-}
-export interface RememberOptions {
-    /** Override the store-level defaultTtlMs for this entry. */
-    ttlMs?: number;
-    type?: FactType;
-    tags?: string[];
-    importance?: number;
-}
-export interface MemoryStoreOptions {
-    /** IndexedDB database name. Default: 'ssmjs'. */
-    dbName?: string;
-    /** Key used for weight storage within the 'weights' object store. Default: 'ssmjs-weights'. */
-    weightsKey?: string;
-    /**
-     * IDBFactory to use instead of the global `indexedDB`.
-     * Use this in Node.js environments with fake-indexeddb:
-     *   import { IDBFactory } from 'fake-indexeddb';
-     *   const idbFactory = new IDBFactory();
-     */
-    idbFactory?: IDBFactory;
-    /**
-     * Default TTL applied to new entries when no per-entry ttlMs is provided.
-     * Entries with an expired TTL are filtered from recallAll() and related methods.
-     */
-    defaultTtlMs?: number;
+import type { HybridRetrieveOptions } from '../retrieval/index.js';
+import { IdbStorageAdapter } from '../storage/idbAdapter.js';
+import { ScopedFactRepository } from '../storage/ScopedFactRepository.js';
+import { MemoryStorageError, type ConsistencyNote, type FactProvenance, type FactStoragePort, type MemoryScope, type StoredFactRecord, type TombstoneRecord, type JournalEntry } from '../storage/types.js';
+import type { MemoryEntry, MemoryStoreOptions, RankedRecall, RememberOptions, SaveLoadRuntime, ScoredMemory, SSMRuntimeRef } from './types.js';
+export type { FactType, MemoryEntry, MemoryStoreOptions, RankedRecall, RecallMethod, RememberOptions, ScoredMemory, } from './types.js';
+export declare class MemoryStore {
+    private readonly _weightsKey;
+    private readonly _defaultTtl;
+    private readonly _maxEntries;
+    private readonly _scope;
+    /** The unit-of-work layer every durable operation flows through. */
+    readonly repository: ScopedFactRepository;
+    private readonly _storage;
+    /** Cross-context subscription, opened on the first operation (see `_ready`). */
+    private _unsubscribe;
+    private _subscribed;
+    private readonly _sweeper;
+    /** Ranking + its embedding / dense-index caches (EVM-1, EVM-1b, EVM-8). */
+    private readonly _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).
+     */
+    private _foreignRevision;
+    constructor(opts?: MemoryStoreOptions);
     /**
-     * Fact count at/above which semantic recall switches from an exact O(N)
-     * cosine scan to an O(log N) HNSW ANN index. Default 256 — small stores stay
-     * exact (simpler + faster), large stores stay fast. (EVM-1)
+     * 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.
      */
-    annThreshold?: number;
+    private _ready;
+    /** The scope partition this store is bound to (never widened implicitly). */
+    get scope(): MemoryScope;
+    /** The durable storage backend kind in use ('indexedDB' | 'node-file'). */
+    get storageKind(): FactStoragePort['kind'];
     /**
-     * Hard cap on stored facts. When set, each write evicts the lowest-value
-     * entries (expired first, then lowest importance, then oldest) so the store
-     * stays bounded. Unset = unbounded (legacy). (EVM-7)
+     * 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.
      */
-    maxEntries?: number;
+    get foreignRevision(): number;
+    private _onForeignChange;
     /**
-     * Max content→embedding vectors held in the LRU recall cache. Default 2000.
-     * (EVM-8 — bounded LRU instead of clear-on-overflow.)
+     * 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.
      */
-    embedCacheMax?: number;
-}
-interface SaveLoadRuntime {
-    save(opts?: {
-        storage: 'indexedDB';
-        key: string;
-    }): Promise<void>;
-    load(opts?: {
-        key: string;
-    }): Promise<boolean>;
-}
-type SSMRuntimeRef = any;
-export declare class MemoryStore {
-    private readonly _dbName;
-    private readonly _weightsKey;
-    private readonly _idb;
-    private readonly _defaultTtl;
-    private readonly _annThreshold;
-    private readonly _maxEntries;
-    private readonly _embedCacheMax;
-    private _db;
-    private _sweepTimer;
-    /** Content → L2-normalised embedding cache, used by recallSimilar. */
-    private readonly _embedCache;
-    /** Runtime whose embeddings populate `_embedCache`; a change invalidates it. */
-    private _embedRuntime;
-    private readonly _denseVectors;
-    private _denseIndex;
-    /** Signature of the fact set the current index was built from. */
-    private _denseSig;
-    /** Identity of the runtime whose embeddings populated the vectors. */
-    private _denseRuntime;
-    constructor(opts?: MemoryStoreOptions);
-    private _open;
-    private _isExpired;
-    /** Stores or overwrites a fact. */
     remember(key: string, content: string, opts?: RememberOptions): Promise<void>;
     /**
-     * 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.
      */
-    private _enforceCap;
+    rememberCas(key: string, content: string, expectedRevision: number | null, opts?: RememberOptions): Promise<MemoryEntry>;
+    /** Fetches an entry WITH its durable revision, for CAS-based reconciliation. */
+    recallVersioned(key: string): Promise<MemoryEntry | undefined>;
     /**
-     * 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: number): void;
     /** Stops the background TTL sweeper started by {@link startTtlSweeper}. */
     stopTtlSweeper(): void;
     /**
-     * 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.
      */
     recall(key: string): Promise<MemoryEntry | undefined>;
-    /** Returns all non-expired stored facts, newest first. */
+    /** Returns all non-expired stored facts in this store's scope, newest first. */
     recallAll(): Promise<MemoryEntry[]>;
     /**
      * Returns the N most recently updated non-expired facts.
@@ -152,19 +107,15 @@ export declare class MemoryStore {
     recallRecent(n: number): Promise<MemoryEntry[]>;
     /**
      * 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.
      */
     recallByTag(tag: string): Promise<MemoryEntry[]>;
     /**
-     * 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}.
      */
     recallSimilar(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<MemoryEntry[]>;
     /**
@@ -173,80 +124,67 @@ export declare class MemoryStore {
      * so callers can rank/threshold by TRUE similarity instead of list position.
      * {@link recallSimilar} is the score-dropping convenience wrapper over this.
      */
-    recallSimilarScored(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<Array<{
-        entry: MemoryEntry;
-        score: number;
-    }>>;
+    recallSimilarScored(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<ScoredMemory[]>;
     /**
-     * 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.
      */
     recallHybrid(query: string, topK: number, runtime?: SSMRuntimeRef, opts?: HybridRetrieveOptions): Promise<MemoryEntry[]>;
     /**
-     * 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.
      */
     recallRanked(query: string, topK: number, runtime?: SSMRuntimeRef, opts?: HybridRetrieveOptions): Promise<RankedRecall>;
     /**
-     * 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.
-     */
-    private _embedWithCache;
-    /**
-     * 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).
-     */
-    private _syncDense;
-    /**
-     * 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.
      */
     purgeExpired(): Promise<number>;
-    /** 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).
+     */
     forget(key: string): Promise<void>;
-    /** Deletes all facts. Does not affect saved weights. */
+    /** Deletes all facts in this store's scope. Does not affect saved weights. */
     clear(): Promise<void>;
+    /** Operations not yet acknowledged by sync — the pending knowledge set. */
+    pendingOps(): Promise<JournalEntry[]>;
+    /** Delete tombstones in this store's scope (or all scopes when omitted). */
+    tombstones(scope?: MemoryScope): Promise<TombstoneRecord[]>;
+    /**
+     * 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).
+     */
+    markSynced(opIds: string[]): Promise<void>;
+    /** The current durable store generation. */
+    revision(): Promise<number>;
+    /** Releases cross-context subscriptions and the underlying connection. */
+    close(): void;
     /**
      * 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).
      */
     exportAll(): Promise<MemoryEntry[]>;
     /**
-     * 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.
      */
-    importAll(entries: MemoryEntry[], strategy: 'merge' | 'overwrite'): Promise<void>;
-    /** Writes a raw MemoryEntry directly (preserves original timestamp / metadata). */
-    private _putRaw;
+    importAll(entries: MemoryEntry[], strategy: 'merge' | 'overwrite', importedFrom?: string): Promise<void>;
     /**
      * 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.
      */
     saveWeights(runtime: SaveLoadRuntime): Promise<void>;
@@ -256,5 +194,6 @@ export declare class MemoryStore {
      */
     loadWeights(runtime: SaveLoadRuntime): Promise<boolean>;
 }
-export {};
+export { IdbStorageAdapter, ScopedFactRepository, MemoryStorageError, };
+export type { ConsistencyNote, FactProvenance, FactStoragePort, JournalEntry, MemoryScope, StoredFactRecord, TombstoneRecord, };
 //# sourceMappingURL=MemoryStore.d.ts.map

package/dist/memory/MemoryStore.d.ts.map

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