@seanhogg/builderforce-memory 2026.6.31 → 2026.6.34

package/dist/publish/huggingface.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 } 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>;
+}
+/**
+ * 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 declare function publishToHuggingFace(result: ExportResult, target: HuggingFaceTarget, deps?: {
+    hub?: HubClient;
+}): Promise<PublishOutcome>;
+/** 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 declare function writeExportToDir(result: ExportResult, dir: string, fs?: FsLike): Promise<string[]>;
+//# sourceMappingURL=huggingface.d.ts.map

package/dist/publish/huggingface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"huggingface.d.ts","sourceRoot":"","sources":["../../src/publish/huggingface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,sCAAsC,CAAC;AAErF,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,IAAI,EAAE;QACf,IAAI,EAAE;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QACtC,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB,WAAW,CAAC,IAAI,EAAE;QAChB,IAAI,EAAE;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QACtC,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,IAAI,CAAA;SAAE,EAAE,CAAC;KAC1C,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AA0BD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,iBAAiB,EACzB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,SAAS,CAAA;CAAO,GAC7B,OAAO,CAAC,cAAc,CAAC,CA2BzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAcxG"}

package/dist/publish/huggingface.js

@@ -0,0 +1,88 @@
+/**
+ * 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*.
+ */
+/** Turn an emitted file into a Blob (binary or text) for upload. */
+function toBlob(file) {
+    const part = (typeof file.data === "string" ? file.data : file.data);
+    return new Blob([part], { type: file.contentType });
+}
+async function loadHub() {
+    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));
+        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, target, deps = {}) {
+    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", 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) };
+}
+/**
+ * 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, dir, fs) {
+    const spec = "node:fs/promises";
+    const realFs = fs ?? (await import(spec));
+    const sep = dir.endsWith("/") || dir.endsWith("\\") ? "" : "/";
+    await realFs.mkdir(dir, { recursive: true });
+    const written = [];
+    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;
+}
+//# sourceMappingURL=huggingface.js.map

package/dist/publish/huggingface.js.map

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

package/dist/publish/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/publish/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/publish/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/publish/index.js

@@ -0,0 +1,6 @@
+/**
+ * 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";
+//# sourceMappingURL=index.js.map

package/dist/publish/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/publish/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/retrieval/HybridRetriever.d.ts

@@ -40,6 +40,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 {
     id: string;

package/dist/retrieval/HybridRetriever.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HybridRetriever.d.ts","sourceRoot":"","sources":["../../src/retrieval/HybridRetriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAGzD,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,MAAM,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IAClC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,IAAI,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,kBAAkB,EAAE,EAChC,IAAI,GAAE,qBAA0B,GACjC,SAAS,EAAE,CAuDb"}
+{"version":3,"file":"HybridRetriever.d.ts","sourceRoot":"","sources":["../../src/retrieval/HybridRetriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAIzD,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,MAAM,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IAClC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,kBAAkB,EAAE,EAChC,IAAI,GAAE,qBAA0B,GACjC,SAAS,EAAE,CAyDb"}

package/dist/retrieval/HybridRetriever.js

@@ -13,9 +13,9 @@
  * query (text + optional vector). It degrades gracefully: no query vector / no
  * candidate vectors → BM25-only; no overlap → dense-only.
  */
-import { cosineSimilarity } from '../similarity/index.js';
 import { bm25Search } from './bm25.js';
 import { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+import { denseSearch } from './hnsw.js';
 /**
  * Runs the full hybrid pipeline over `candidates` and returns the top-K hits.
  * Pure given its inputs (embeddings are supplied by the caller) so it is directly
@@ -26,14 +26,16 @@ export function hybridRetrieve(query, candidates, opts = {}) {
     if (candidates.length === 0)
         return [];
     const byId = new Map(candidates.map(c => [c.id, c]));
-    // ── Dense ranking (cosine) ────────────────────────────────────────────────
+    // ── Dense ranking (cosine, ANN-accelerated above the threshold) ────────────
     let denseIds = [];
     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.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) ─────────────────────────────────────────────────
     const sparseIds = bm25Search(query.text, candidates, opts.bm25).map(h => h.id);

package/dist/retrieval/HybridRetriever.js.map

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

package/dist/retrieval/hnsw.d.ts

@@ -0,0 +1,71 @@
+/**
+ * hnsw.ts — a pure-TypeScript HNSW approximate-nearest-neighbour index.
+ *
+ * Recall over the fact store was an O(N) cosine scan per query, so the
+ * "lifetime of always-current knowledge" thesis hit a wall around ~10⁴ facts.
+ * HNSW (Hierarchical Navigable Small World) gives O(log N) expected query time
+ * with high recall, and this implementation is dependency-free so it keeps the
+ * engine/runtime zero-dep promise. For small sets an exact scan is both simpler
+ * and faster, so callers use {@link denseSearch} which switches to HNSW only
+ * above a threshold.
+ *
+ * Distance is cosine similarity (higher = closer); the graph stores `1 - cos`
+ * as the metric so "nearer" is "smaller". Construction is deterministic given a
+ * seed, so builds (and tests) reproduce exactly.
+ */
+export interface HnswOptions {
+    /** Max neighbours per node on layers > 0. Default 16. */
+    M?: number;
+    /** Candidate-list size during construction. Default 200. */
+    efConstruction?: number;
+    /** Default candidate-list size during search. Default 50. */
+    efSearch?: number;
+    /** Deterministic seed for layer assignment. Default 0x5eed. */
+    seed?: number;
+}
+export interface SearchHit {
+    id: string;
+    /** Cosine similarity to the query (higher = closer). */
+    score: number;
+}
+export declare class HnswIndex {
+    private readonly _M;
+    private readonly _Mmax0;
+    private readonly _efC;
+    private readonly _efS;
+    private readonly _mL;
+    private readonly _rng;
+    private readonly _nodes;
+    private readonly _idToIdx;
+    private _entry;
+    private _maxLayer;
+    constructor(opts?: HnswOptions);
+    get size(): number;
+    has(id: string): boolean;
+    private _dist;
+    private _randomLayer;
+    /** Insert a vector. Ids are unique — re-adding a known id is ignored. */
+    add(id: string, vector: Float32Array): void;
+    /** Top-k nearest by cosine similarity (descending). */
+    search(query: Float32Array, k: number, ef?: number): SearchHit[];
+    clear(): void;
+    /** Greedy hill-climb to the single closest node to `q` on layer `lc`. */
+    private _greedyClosest;
+    /**
+     * ef-search on a single layer: returns candidates sorted nearest-first.
+     * A bounded best-first expansion (the standard HNSW layer search).
+     */
+    private _searchLayer;
+    /** Keep only the `Mmax` closest neighbours of `node` on layer `lc`. */
+    private _prune;
+}
+/**
+ * Dense KNN with an exact-scan fast path: below `threshold` candidates a linear
+ * cosine scan is simpler and faster; at/above it, build an HNSW index and query
+ * it. Returned hits are cosine-similarity descending. Pure given its inputs.
+ */
+export declare function denseSearch(query: Float32Array, items: Array<{
+    id: string;
+    vector: Float32Array;
+}>, k: number, threshold?: number, hnsw?: HnswOptions): SearchHit[];
+//# sourceMappingURL=hnsw.d.ts.map

package/dist/retrieval/hnsw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw.d.ts","sourceRoot":"","sources":["../../src/retrieval/hnsw.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,WAAW;IACxB,yDAAyD;IACzD,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACjB;AAkBD,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,SAAS,CAAM;gBAEX,IAAI,GAAE,WAAgB;IASlC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,YAAY;IAIpB,yEAAyE;IACzE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IA0C3C,uDAAuD;IACvD,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,SAAY,GAAG,SAAS,EAAE;IAUnE,KAAK,IAAI,IAAI;IASb,yEAAyE;IACzE,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAoCpB,uEAAuE;IACvE,OAAO,CAAC,MAAM;CAKjB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACvB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC,EAClD,CAAC,EAAE,MAAM,EACT,SAAS,SAAM,EACf,IAAI,CAAC,EAAE,WAAW,GACnB,SAAS,EAAE,CAWb"}

package/dist/retrieval/hnsw.js

@@ -0,0 +1,201 @@
+/**
+ * hnsw.ts — a pure-TypeScript HNSW approximate-nearest-neighbour index.
+ *
+ * Recall over the fact store was an O(N) cosine scan per query, so the
+ * "lifetime of always-current knowledge" thesis hit a wall around ~10⁴ facts.
+ * HNSW (Hierarchical Navigable Small World) gives O(log N) expected query time
+ * with high recall, and this implementation is dependency-free so it keeps the
+ * engine/runtime zero-dep promise. For small sets an exact scan is both simpler
+ * and faster, so callers use {@link denseSearch} which switches to HNSW only
+ * above a threshold.
+ *
+ * Distance is cosine similarity (higher = closer); the graph stores `1 - cos`
+ * as the metric so "nearer" is "smaller". Construction is deterministic given a
+ * seed, so builds (and tests) reproduce exactly.
+ */
+import { cosineSimilarity } from '../similarity/index.js';
+/** A small deterministic LCG → float in [0,1). Mirrors the engine's SeededRng. */
+function makeRng(seed) {
+    let s = (seed >>> 0) || 1;
+    return () => {
+        s = (Math.imul(1664525, s) + 1013904223) >>> 0;
+        return s / 0x1_0000_0000;
+    };
+}
+export class HnswIndex {
+    _M;
+    _Mmax0;
+    _efC;
+    _efS;
+    _mL;
+    _rng;
+    _nodes = [];
+    _idToIdx = new Map();
+    _entry = -1; // index of the entry-point node
+    _maxLayer = -1;
+    constructor(opts = {}) {
+        this._M = Math.max(2, opts.M ?? 16);
+        this._Mmax0 = this._M * 2;
+        this._efC = Math.max(this._M, opts.efConstruction ?? 200);
+        this._efS = Math.max(1, opts.efSearch ?? 50);
+        this._mL = 1 / Math.log(this._M);
+        this._rng = makeRng(opts.seed ?? 0x5eed);
+    }
+    get size() {
+        return this._nodes.length;
+    }
+    has(id) {
+        return this._idToIdx.has(id);
+    }
+    _dist(a, b) {
+        return 1 - cosineSimilarity(a, b);
+    }
+    _randomLayer() {
+        return Math.floor(-Math.log(Math.max(this._rng(), 1e-12)) * this._mL);
+    }
+    /** Insert a vector. Ids are unique — re-adding a known id is ignored. */
+    add(id, vector) {
+        if (this._idToIdx.has(id))
+            return;
+        const layer = this._randomLayer();
+        const node = { id, vector, neighbours: Array.from({ length: layer + 1 }, () => []) };
+        const idx = this._nodes.length;
+        this._nodes.push(node);
+        this._idToIdx.set(id, idx);
+        if (this._entry === -1) {
+            this._entry = idx;
+            this._maxLayer = layer;
+            return;
+        }
+        // Descend from the top to just above the new node's top layer.
+        let ep = this._entry;
+        for (let lc = this._maxLayer; lc > layer; lc--) {
+            ep = this._greedyClosest(vector, ep, lc);
+        }
+        // From the node's top layer down to 0: find neighbours and link.
+        for (let lc = Math.min(layer, this._maxLayer); lc >= 0; lc--) {
+            const candidates = this._searchLayer(vector, ep, this._efC, lc);
+            const Mmax = lc === 0 ? this._Mmax0 : this._M;
+            const selected = candidates.slice(0, this._M).map((c) => c.idx);
+            node.neighbours[lc] = selected.slice();
+            // Add reverse links, pruning each neighbour back to Mmax.
+            for (const nIdx of selected) {
+                const nb = this._nodes[nIdx];
+                const list = nb.neighbours[lc] ?? (nb.neighbours[lc] = []);
+                list.push(idx);
+                if (list.length > Mmax)
+                    this._prune(nb, lc, Mmax);
+            }
+            ep = candidates[0]?.idx ?? ep;
+        }
+        if (layer > this._maxLayer) {
+            this._maxLayer = layer;
+            this._entry = idx;
+        }
+    }
+    /** Top-k nearest by cosine similarity (descending). */
+    search(query, k, ef = this._efS) {
+        if (this._entry === -1 || k <= 0)
+            return [];
+        let ep = this._entry;
+        for (let lc = this._maxLayer; lc > 0; lc--) {
+            ep = this._greedyClosest(query, ep, lc);
+        }
+        const found = this._searchLayer(query, ep, Math.max(ef, k), 0);
+        return found.slice(0, k).map((c) => ({ id: this._nodes[c.idx].id, score: 1 - c.dist }));
+    }
+    clear() {
+        this._nodes.length = 0;
+        this._idToIdx.clear();
+        this._entry = -1;
+        this._maxLayer = -1;
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    /** Greedy hill-climb to the single closest node to `q` on layer `lc`. */
+    _greedyClosest(q, start, lc) {
+        let best = start;
+        let bestDist = this._dist(q, this._nodes[best].vector);
+        let improved = true;
+        while (improved) {
+            improved = false;
+            for (const nIdx of this._nodes[best].neighbours[lc] ?? []) {
+                const d = this._dist(q, this._nodes[nIdx].vector);
+                if (d < bestDist) {
+                    bestDist = d;
+                    best = nIdx;
+                    improved = true;
+                }
+            }
+        }
+        return best;
+    }
+    /**
+     * ef-search on a single layer: returns candidates sorted nearest-first.
+     * A bounded best-first expansion (the standard HNSW layer search).
+     */
+    _searchLayer(q, entry, ef, lc) {
+        const visited = new Set([entry]);
+        const entryDist = this._dist(q, this._nodes[entry].vector);
+        // `candidates` is a min-heap-ish frontier; `results` keeps the best ef.
+        const candidates = [{ idx: entry, dist: entryDist }];
+        const results = [{ idx: entry, dist: entryDist }];
+        while (candidates.length > 0) {
+            // Pop nearest candidate.
+            let ci = 0;
+            for (let i = 1; i < candidates.length; i++)
+                if (candidates[i].dist < candidates[ci].dist)
+                    ci = i;
+            const cur = candidates.splice(ci, 1)[0];
+            // Farthest in results.
+            const worst = results.reduce((m, r) => (r.dist > m.dist ? r : m), results[0]);
+            if (cur.dist > worst.dist && results.length >= ef)
+                break;
+            for (const nIdx of this._nodes[cur.idx].neighbours[lc] ?? []) {
+                if (visited.has(nIdx))
+                    continue;
+                visited.add(nIdx);
+                const d = this._dist(q, this._nodes[nIdx].vector);
+                const farthest = results.reduce((m, r) => (r.dist > m.dist ? r : m), results[0]);
+                if (results.length < ef || d < farthest.dist) {
+                    candidates.push({ idx: nIdx, dist: d });
+                    results.push({ idx: nIdx, dist: d });
+                    if (results.length > ef) {
+                        // Drop the current farthest.
+                        let wi = 0;
+                        for (let i = 1; i < results.length; i++)
+                            if (results[i].dist > results[wi].dist)
+                                wi = i;
+                        results.splice(wi, 1);
+                    }
+                }
+            }
+        }
+        return results.sort((a, b) => a.dist - b.dist);
+    }
+    /** Keep only the `Mmax` closest neighbours of `node` on layer `lc`. */
+    _prune(node, lc, Mmax) {
+        const list = node.neighbours[lc];
+        list.sort((a, b) => this._dist(node.vector, this._nodes[a].vector) - this._dist(node.vector, this._nodes[b].vector));
+        node.neighbours[lc] = list.slice(0, Mmax);
+    }
+}
+/**
+ * Dense KNN with an exact-scan fast path: below `threshold` candidates a linear
+ * cosine scan is simpler and faster; at/above it, build an HNSW index and query
+ * it. Returned hits are cosine-similarity descending. Pure given its inputs.
+ */
+export function denseSearch(query, items, k, threshold = 256, hnsw) {
+    if (items.length === 0 || k <= 0)
+        return [];
+    if (items.length < threshold) {
+        return items
+            .map((it) => ({ id: it.id, score: cosineSimilarity(query, it.vector) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k);
+    }
+    const index = new HnswIndex(hnsw);
+    for (const it of items)
+        index.add(it.id, it.vector);
+    return index.search(query, k);
+}
+//# sourceMappingURL=hnsw.js.map

package/dist/retrieval/hnsw.js.map

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

package/dist/retrieval/index.d.ts

@@ -13,4 +13,6 @@ export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
 export type { RankedList, FusedHit, MmrCandidate } from './fusion.js';
 export { hybridRetrieve } from './HybridRetriever.js';
 export type { RetrievalCandidate, HybridQuery, HybridRetrieveOptions, HybridHit, } from './HybridRetriever.js';
+export { HnswIndex, denseSearch } from './hnsw.js';
+export type { HnswOptions, SearchHit } from './hnsw.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/retrieval/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/retrieval/index.js

@@ -9,4 +9,5 @@ export { chunkText } from './chunk.js';
 export { bm25Search } from './bm25.js';
 export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
 export { hybridRetrieve } from './HybridRetriever.js';
+export { HnswIndex, denseSearch } from './hnsw.js';
 //# sourceMappingURL=index.js.map

package/dist/retrieval/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/workflow/steps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../src/workflow/steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAgChF,UAAU,UAAU;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAyQpD,CAAC"}
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../src/workflow/steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgBH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAyChF,UAAU,UAAU;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAyVpD,CAAC"}