@seanhogg/builderforce-memory 2026.6.31 → 2026.6.35

package/src/distillation/DistillationEngine.ts

@@ -53,6 +53,22 @@ export interface DistillOptions {
     qualityGate? : QualityGate;
 }
 
+/**
+ * Catastrophic-forgetting guard (EVM-5). Online WSLA adapts a narrow set of
+ * weights toward the newest exemplar, which can erode previously-learned
+ * knowledge. A rehearsal (experience-replay) buffer mitigates this: each adapt
+ * also trains on a sample of past exemplars, so old knowledge is continually
+ * reinforced instead of overwritten.
+ */
+export interface RehearsalOptions {
+    /** Ring-buffer capacity of past exemplars. 0 disables rehearsal. Default 0. */
+    bufferSize?: number;
+    /** How many past exemplars to mix into each adapt pass. Default 2. */
+    sampleK?: number;
+    /** Deterministic sampling seed. Default 1. */
+    seed?: number;
+}
+
 export interface DistillResult {
     /** The input prompt that was distilled. */
     input        : string;
@@ -64,6 +80,8 @@ export interface DistillResult {
     skipped?     : boolean;
     /** Reason adaptation was skipped, if applicable. */
     skipReason?  : string;
+    /** Number of past exemplars rehearsed alongside this one (EVM-5). */
+    rehearsed?   : number;
 }
 
 export interface DistillBatchResult {
@@ -94,14 +112,56 @@ export class DistillationEngine {
     private readonly _bridge   : TransformerBridge;
     private readonly _log      : DistillationLog[] = [];
 
+    // ── Rehearsal buffer (EVM-5 catastrophic-forgetting guard) ─────────────────
+    private readonly _rehearsalSize : number;
+    private readonly _rehearsalK    : number;
+    private readonly _rehearsal     : Array<{ input: string; teacherOutput: string }> = [];
+    private _rehearsalState         : number;
+
     /**
      * @param runtime The SSMRuntime whose SSM will be trained as the student.
      * @param bridge  The transformer bridge acting as teacher.
      *                A bridge must be provided — distillation requires one.
+     * @param rehearsal Optional experience-replay config (EVM-5). When
+     *                `bufferSize > 0`, each adapt also trains on a sample of past
+     *                exemplars to guard against catastrophic forgetting.
      */
-    constructor(runtime: SSMRuntime, bridge: TransformerBridge) {
+    constructor(runtime: SSMRuntime, bridge: TransformerBridge, rehearsal: RehearsalOptions = {}) {
         this._runtime = runtime;
         this._bridge  = bridge;
+        this._rehearsalSize = Math.max(0, rehearsal.bufferSize ?? 0);
+        this._rehearsalK    = Math.max(0, rehearsal.sampleK ?? 2);
+        this._rehearsalState = (rehearsal.seed ?? 1) >>> 0 || 1;
+    }
+
+    /** Current number of exemplars held in the rehearsal buffer (EVM-5). */
+    getRehearsalBufferSize(): number {
+        return this._rehearsal.length;
+    }
+
+    /** Deterministic [0,1) draw for reproducible rehearsal sampling. */
+    private _rand(): number {
+        this._rehearsalState = (Math.imul(1664525, this._rehearsalState) + 1013904223) >>> 0;
+        return this._rehearsalState / 0x1_0000_0000;
+    }
+
+    /** Sample up to `_rehearsalK` distinct past exemplars (reservoir-free, by index). */
+    private _sampleRehearsal(): Array<{ input: string; teacherOutput: string }> {
+        if (this._rehearsalSize === 0 || this._rehearsal.length === 0 || this._rehearsalK === 0) return [];
+        const k = Math.min(this._rehearsalK, this._rehearsal.length);
+        const idxs = this._rehearsal.map((_, i) => i);
+        // Partial Fisher–Yates to pick k distinct indices deterministically.
+        for (let i = 0; i < k; i++) {
+            const j = i + Math.floor(this._rand() * (idxs.length - i));
+            const tmp = idxs[i]!; idxs[i] = idxs[j]!; idxs[j] = tmp;
+        }
+        return idxs.slice(0, k).map((i) => this._rehearsal[i]!);
+    }
+
+    private _pushRehearsal(input: string, teacherOutput: string): void {
+        if (this._rehearsalSize === 0) return;
+        this._rehearsal.push({ input, teacherOutput });
+        if (this._rehearsal.length > this._rehearsalSize) this._rehearsal.shift();
     }
 
     /**
@@ -182,9 +242,13 @@ export class DistillationEngine {
             }
         }
 
-        // Train the SSM on the teacher's output.
-        // Prepend the input so the model learns the (prompt → response) mapping.
-        const trainingText = `${input}\n${teacherOutput}`;
+        // Train the SSM on the teacher's output, prepending the input so the model
+        // learns the (prompt → response) mapping. EVM-5: interleave a sample of
+        // past exemplars (experience replay) so this adapt reinforces prior
+        // knowledge instead of overwriting it (catastrophic-forgetting guard).
+        const rehearsed = this._sampleRehearsal();
+        const pairs = [...rehearsed, { input, teacherOutput }].map((p) => `${p.input}\n${p.teacherOutput}`);
+        const trainingText = pairs.join('\n\n');
 
         let adaptResult: AdaptResult;
         try {
@@ -197,6 +261,9 @@ export class DistillationEngine {
             );
         }
 
+        // Record the new exemplar for future rehearsal.
+        this._pushRehearsal(input, teacherOutput);
+
         this._appendLog({
             input,
             teacherOutputLength: teacherOutput.length,
@@ -205,7 +272,7 @@ export class DistillationEngine {
             epochs     : adaptResult.epochCount,
         });
 
-        return { input, teacherOutput, adaptResult, skipped: false };
+        return { input, teacherOutput, adaptResult, skipped: false, rehearsed: rehearsed.length };
     }
 
     /**

package/src/distillation/index.ts

@@ -1,2 +1,2 @@
 export { DistillationEngine } from './DistillationEngine.js';
-export type { DistillOptions, DistillResult, DistillBatchResult, DistillationLog, QualityGate } from './DistillationEngine.js';
+export type { DistillOptions, DistillResult, DistillBatchResult, DistillationLog, QualityGate, RehearsalOptions } from './DistillationEngine.js';

package/src/index.ts

@@ -169,7 +169,16 @@ export type {
 } from './memory/MemoryStore.js';
 
 // ── Cognition (Evermind — Write-Through Cognition) ────────────────────────────
-export { EvermindCognition, workspacePresenceGatherer } from './cognition/index.js';
+export {
+    EvermindCognition,
+    workspacePresenceGatherer,
+    canonicalizeSubjectKey,
+    normalizeSubjectKey,
+    buildAliasTable,
+    sanitizeRecalledFact,
+    buildRecallContext,
+    trustScore,
+} from './cognition/index.js';
 export type {
     EvermindCognitionOptions,
     WorkspacePresenceRule,
@@ -180,6 +189,9 @@ export type {
     EvidenceGatherer,
     EvidenceResult,
     Verdict,
+    AliasTable,
+    RecalledFact,
+    FactProvenance,
 } from './cognition/index.js';
 
 // ── Diagnostics (execution-output runner) ──────────────────────────────────────
@@ -218,6 +230,10 @@ export type {
     RunWorkflowOptions,
 } from './workflow/index.js';
 
+// ── Publish (ship an engine model export to HF / local folder) ──────────────────
+export { publishToHuggingFace, writeExportToDir } from './publish/index.js';
+export type { HuggingFaceTarget, PublishOutcome, HubClient, FsLike } from './publish/index.js';
+
 // ── Distillation ──────────────────────────────────────────────────────────────
 export { DistillationEngine } from './distillation/DistillationEngine.js';
 export type {
@@ -226,6 +242,7 @@ export type {
     DistillBatchResult,
     DistillationLog,
     QualityGate,
+    RehearsalOptions,
 } from './distillation/DistillationEngine.js';
 
 // ── Agent ─────────────────────────────────────────────────────────────────────

package/src/memory/MemoryStore.ts

@@ -9,8 +9,8 @@
  */
 
 import { SSMError } from '../errors/SSMError.js';
-import { tokenize, jaccardSimilarity, cosineSimilarity } from '../similarity/index.js';
-import { hybridRetrieve, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
+import { tokenize, jaccardSimilarity } from '../similarity/index.js';
+import { hybridRetrieve, denseSearch, HnswIndex, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
 
 export type FactType = 'text' | 'json' | 'number' | 'boolean';
 
@@ -61,6 +61,23 @@ export interface MemoryStoreOptions {
      * Entries with an expired TTL are filtered from recallAll() and related methods.
      */
     defaultTtlMs? : number;
+    /**
+     * 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)
+     */
+    annThreshold? : number;
+    /**
+     * 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)
+     */
+    maxEntries?   : number;
+    /**
+     * Max content→embedding vectors held in the LRU recall cache. Default 2000.
+     * (EVM-8 — bounded LRU instead of clear-on-overflow.)
+     */
+    embedCacheMax?: number;
 }
 
 const FACTS_STORE   = 'facts';
@@ -84,7 +101,7 @@ interface SaveLoadRuntime {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type SSMRuntimeRef = any;
 
-/** Max number of cached content→embedding vectors retained in memory. */
+/** Max content→embedding vectors retained (LRU-evicted past this). (EVM-8) */
 const EMBED_CACHE_MAX = 2000;
 
 export class MemoryStore {
@@ -92,15 +109,36 @@ export class MemoryStore {
     private readonly _weightsKey : string;
     private readonly _idb        : IDBFactory | undefined;
     private readonly _defaultTtl : number | undefined;
+    private readonly _annThreshold : number;
+    private readonly _maxEntries : number | undefined;
+    private readonly _embedCacheMax : number;
     private _db: IDBDatabase | null = null;
+    private _sweepTimer: ReturnType<typeof setInterval> | null = null;
     /** Content → L2-normalised embedding cache, used by recallSimilar. */
     private readonly _embedCache = new Map<string, Float32Array>();
+    /** Runtime whose embeddings populate `_embedCache`; a change invalidates it. */
+    private _embedRuntime: unknown = 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.
+    private readonly _denseVectors = new Map<string, Float32Array>();
+    private _denseIndex: HnswIndex | null = null;
+    /** Signature of the fact set the current index was built from. */
+    private _denseSig = '';
+    /** Identity of the runtime whose embeddings populated the vectors. */
+    private _denseRuntime: unknown = null;
 
     constructor(opts: MemoryStoreOptions = {}) {
         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 ──────────────────────────────────────────────────────
@@ -167,7 +205,65 @@ export class MemoryStore {
         };
 
         const tx = db.transaction(FACTS_STORE, 'readwrite');
-        return requestToPromise(tx.objectStore(FACTS_STORE).put(entry), `Failed to store fact "${key}"`, () => undefined);
+        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();
+    }
+
+    /**
+     * 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)
+     */
+    private async _enforceCap(): Promise<void> {
+        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() as IDBRequest<MemoryEntry[]>,
+            '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: MemoryEntry): [number, number, number, number] =>
+            [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;
+        });
+        const victims = sorted.slice(0, all.length - this._maxEntries);
+        await Promise.all(victims.map((e) => this.forget(e.key)));
+    }
+
+    /**
+     * Starts a background timer that periodically hard-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)
+     */
+    startTtlSweeper(intervalMs: number): void {
+        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 as unknown as { unref?: () => void };
+        /* istanbul ignore else -- unref exists in Node; absent in the browser */
+        if (typeof maybeUnref.unref === 'function') {
+            maybeUnref.unref();
+        }
+        this._sweepTimer = timer;
+    }
+
+    /** Stops the background TTL sweeper started by {@link startTtlSweeper}. */
+    stopTtlSweeper(): void {
+        if (this._sweepTimer) {
+            clearInterval(this._sweepTimer);
+            this._sweepTimer = null;
+        }
     }
 
     /**
@@ -239,16 +335,16 @@ export class MemoryStore {
         if (runtime != null && typeof runtime.embed === 'function') {
             const queryVec = await this._embedWithCache(runtime, query);
             if (queryVec) {
-                const scored: { entry: MemoryEntry; score: number }[] = [];
-                let embeddedAll = true;
-                for (const entry of all) {
-                    const entryVec = await this._embedWithCache(runtime, entry.content);
-                    if (!entryVec) { embeddedAll = false; break; }
-                    scored.push({ entry, score: cosineSimilarity(queryVec, entryVec) });
-                }
-                if (embeddedAll) {
-                    scored.sort((a, b) => b.score - a.score);
-                    return scored.slice(0, topK).map(s => s.entry);
+                // 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 => synced.byKey.get(h.id)).filter((e): e is MemoryEntry => !!e);
                 }
             }
             // Any failure falls through to the Jaccard path below.
@@ -296,7 +392,7 @@ export class MemoryStore {
             candidates.push({ id: entry.key, text: entry.content, vector });
         }
 
-        const hits = hybridRetrieve({ text: query, vector: queryVec }, candidates, { topK, ...opts });
+        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.map(h => byKey.get(h.id)).filter((e): e is MemoryEntry => !!e);
     }
@@ -307,13 +403,29 @@ export class MemoryStore {
      * unavailable so callers can fall back to lexical similarity.
      */
     private async _embedWithCache(runtime: SSMRuntimeRef, text: string): Promise<Float32Array | null> {
+        // 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) return cached;
+        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) {
-                // Bound cache growth — simplest eviction is a full clear.
-                if (this._embedCache.size >= EMBED_CACHE_MAX) this._embedCache.clear();
+                // 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;
             }
@@ -323,6 +435,68 @@ export class MemoryStore {
         return null;
     }
 
+    /**
+     * 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 async _syncDense(
+        runtime: SSMRuntimeRef,
+        all: MemoryEntry[],
+    ): Promise<{ byKey: Map<string, MemoryEntry>; items: Array<{ id: string; vector: Float32Array }>; index: HnswIndex | null } | null> {
+        if (runtime !== this._denseRuntime) {
+            this._denseVectors.clear();
+            this._denseIndex = null;
+            this._denseSig = '';
+            this._denseRuntime = runtime;
+        }
+
+        const vkeyOf = (e: MemoryEntry): string => `${e.key}@${e.seq ?? 0}`;
+        const currentVkeys = new Set<string>();
+        let sig = `${all.length}`;
+        for (const e of all) { const k = vkeyOf(e); currentVkeys.add(k); sig += '|' + k; }
+
+        const byKey = new Map<string, MemoryEntry>();
+        const items: Array<{ id: string; vector: Float32Array }> = [];
+        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.
      * @returns The number of entries deleted.
@@ -356,6 +530,11 @@ export class MemoryStore {
     /** Deletes all facts. Does not affect saved weights. */
     async clear(): Promise<void> {
         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);

package/src/publish/huggingface.ts

@@ -0,0 +1,139 @@
+/**
+ * publish/huggingface.ts — push an exported Evermind model to the Hugging Face Hub.
+ *
+ * The runtime stays zero-dependency: the actual Hub I/O is delegated to an
+ * injectable {@link HubClient}. In production it is dynamically imported from the
+ * optional `@huggingface/hub` package (which handles LFS for the binary weight
+ * files correctly); tests inject a fake. There is also a credential-free path —
+ * {@link writeExportToDir} — that writes the repo to a local folder you push with
+ * `git` / `huggingface-cli upload`.
+ *
+ * The export itself (turning a trained model into the file set) lives in the
+ * engine's `export/` module; this module is only the *transport*.
+ */
+
+import type { ExportResult, ExportFile } from "@seanhogg/builderforce-memory-engine";
+
+/** Where/how to publish. `repoId` is "owner/name" (e.g. "builderforce/Evermind"). */
+export interface HuggingFaceTarget {
+  repoId: string;
+  /** A write-scoped HF access token (hf_…). */
+  token: string;
+  /** Create the repo private. Default false (public). */
+  private?: boolean;
+  /** Commit title. Default "Publish <repoId>". */
+  commitTitle?: string;
+  /** Target branch. Default "main". */
+  branch?: string;
+}
+
+export interface PublishOutcome {
+  repoId: string;
+  url: string;
+  files: string[];
+}
+
+/** The slice of `@huggingface/hub` we use — injectable for testing. */
+export interface HubClient {
+  createRepo(args: {
+    repo: { type: "model"; name: string };
+    accessToken: string;
+    private?: boolean;
+  }): Promise<unknown>;
+  uploadFiles(args: {
+    repo: { type: "model"; name: string };
+    accessToken: string;
+    branch?: string;
+    commitTitle?: string;
+    files: { path: string; content: Blob }[];
+  }): Promise<unknown>;
+}
+
+/** Turn an emitted file into a Blob (binary or text) for upload. */
+function toBlob(file: ExportFile): Blob {
+  const part = (typeof file.data === "string" ? file.data : file.data) as unknown as BlobPart;
+  return new Blob([part], { type: file.contentType });
+}
+
+async function loadHub(): Promise<HubClient> {
+  try {
+    // Optional peer dep — only required when actually uploading. A variable
+    // specifier keeps it out of the static module graph (no build-time dep).
+    const spec = "@huggingface/hub";
+    const mod = (await import(spec)) as unknown as HubClient;
+    if (typeof mod.createRepo !== "function" || typeof mod.uploadFiles !== "function") {
+      throw new Error("module shape unexpected");
+    }
+    return mod;
+  } catch {
+    throw new Error(
+      "publishToHuggingFace needs the optional '@huggingface/hub' package " +
+        "(npm i @huggingface/hub) — or use writeExportToDir() + `huggingface-cli upload`.",
+    );
+  }
+}
+
+/**
+ * Publish an export to the Hub: create the repo (idempotent) then upload every
+ * file. Pass `deps.hub` to inject a client; otherwise `@huggingface/hub` is
+ * loaded dynamically. Requires a write-scoped token (the credential-gated step).
+ */
+export async function publishToHuggingFace(
+  result: ExportResult,
+  target: HuggingFaceTarget,
+  deps: { hub?: HubClient } = {},
+): Promise<PublishOutcome> {
+  if (!target.repoId.includes("/")) {
+    throw new Error(`publishToHuggingFace: repoId must be "owner/name" (got "${target.repoId}")`);
+  }
+  if (!target.token) throw new Error("publishToHuggingFace: a write-scoped HF token is required");
+
+  const hub = deps.hub ?? (await loadHub());
+  const repo = { type: "model" as const, name: target.repoId };
+
+  try {
+    await hub.createRepo({ repo, accessToken: target.token, private: target.private ?? false });
+  } catch (e) {
+    // Re-creating an existing repo is fine; only rethrow unexpected failures.
+    const msg = e instanceof Error ? e.message : String(e);
+    if (!/exist|409|conflict/i.test(msg)) throw e;
+  }
+
+  const files = result.files.map((f) => ({ path: f.path, content: toBlob(f) }));
+  await hub.uploadFiles({
+    repo,
+    accessToken: target.token,
+    branch: target.branch ?? "main",
+    commitTitle: target.commitTitle ?? `Publish ${target.repoId}`,
+    files,
+  });
+
+  return { repoId: target.repoId, url: `https://huggingface.co/${target.repoId}`, files: files.map((f) => f.path) };
+}
+
+/** A minimal fs surface (Node `fs/promises`) — injectable for testing. */
+export interface FsLike {
+  mkdir(path: string, opts: { recursive: boolean }): Promise<unknown>;
+  writeFile(path: string, data: Uint8Array | string): Promise<void>;
+}
+
+/**
+ * Credential-free publish: write the export to a local directory (a ready-to-push
+ * HF repo folder). Returns the relative paths written. Inject `fs` in tests;
+ * otherwise Node's `fs/promises` is used.
+ */
+export async function writeExportToDir(result: ExportResult, dir: string, fs?: FsLike): Promise<string[]> {
+  const spec = "node:fs/promises";
+  const realFs = fs ?? ((await import(spec)) as unknown as FsLike);
+  const sep = dir.endsWith("/") || dir.endsWith("\\") ? "" : "/";
+  await realFs.mkdir(dir, { recursive: true });
+  const written: string[] = [];
+  for (const f of result.files) {
+    const full = `${dir}${sep}${f.path}`;
+    const slash = Math.max(full.lastIndexOf("/"), full.lastIndexOf("\\"));
+    if (slash > dir.length) await realFs.mkdir(full.slice(0, slash), { recursive: true });
+    await realFs.writeFile(full, f.data);
+    written.push(f.path);
+  }
+  return written;
+}

package/src/publish/index.ts

@@ -0,0 +1,7 @@
+/**
+ * publish/ — transport for published Evermind exports (the engine builds the
+ * files; this ships them). Hugging Face Hub upload + local-folder writer.
+ */
+
+export { publishToHuggingFace, writeExportToDir } from "./huggingface.js";
+export type { HuggingFaceTarget, PublishOutcome, HubClient, FsLike } from "./huggingface.js";

package/src/retrieval/HybridRetriever.ts

@@ -14,9 +14,9 @@
  * candidate vectors → BM25-only; no overlap → dense-only.
  */
 
-import { cosineSimilarity } from '../similarity/index.js';
 import { bm25Search, type Bm25Options } from './bm25.js';
 import { reciprocalRankFusion, maximalMarginalRelevance, type MmrCandidate } from './fusion.js';
+import { denseSearch } from './hnsw.js';
 
 export interface RetrievalCandidate {
     id: string;
@@ -46,6 +46,11 @@ export interface HybridRetrieveOptions {
     mmrLambda?: number;
     /** BM25 tuning. */
     bm25?: Bm25Options;
+    /**
+     * Candidate count at/above which the dense pass uses an HNSW ANN index
+     * instead of an exact cosine scan (O(log N) vs O(N)). Default 256.
+     */
+    annThreshold?: number;
 }
 
 export interface HybridHit {
@@ -70,14 +75,16 @@ export function hybridRetrieve(
 
     const byId = new Map(candidates.map(c => [c.id, c]));
 
-    // ── Dense ranking (cosine) ────────────────────────────────────────────────
+    // ── Dense ranking (cosine, ANN-accelerated above the threshold) ────────────
     let denseIds: string[] = [];
     if (query.vector) {
-        denseIds = candidates
-            .filter(c => c.vector && c.vector.length > 0)
-            .map(c => ({ id: c.id, score: cosineSimilarity(query.vector!, c.vector!) }))
-            .sort((a, b) => b.score - a.score)
-            .map(h => h.id);
+        const vectored = candidates
+            .filter((c): c is RetrievalCandidate & { vector: Float32Array } => !!c.vector && c.vector.length > 0)
+            .map(c => ({ id: c.id, vector: c.vector }));
+        // Rank the full vectored set (k = all) so fusion sees the complete dense
+        // ordering; denseSearch uses an exact scan under the threshold and HNSW
+        // above it, so behaviour is identical for small stores.
+        denseIds = denseSearch(query.vector, vectored, vectored.length, opts.annThreshold ?? 256).map(h => h.id);
     }
 
     // ── Sparse ranking (BM25) ─────────────────────────────────────────────────