@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

package/src/retrieval/knowledge-index/quantize.ts

@@ -0,0 +1,78 @@
+/**
+ * quantize.ts — int8 codes with one symmetric per-index scale.
+ *
+ * Graph traversal compares int8 codes with integer dot products. A sum of
+ * int8×int8 products stays far inside 2^53, so it is exact in a JS number and
+ * bit-identical on every platform — the float noise between a CPU and a WebGPU
+ * embedding only matters where a component sits on a rounding boundary.
+ *
+ * The scale is fitted once (at the index's first compaction) and then fixed, so a
+ * code never changes meaning while the index lives.
+ */
+
+/** Largest code magnitude; symmetric, so -128 is never produced. */
+export const CODE_MAX = 127;
+
+/** How far from unit norm a vector may be and still be taken as already normalised. */
+const UNIT_TOLERANCE = 1e-3;
+
+/**
+ * A unit-norm Float32 copy of `v`. Every embedder behind the port already emits
+ * L2-normalised vectors; those (|‖v‖² − 1| ≤ 1e-3) are copied as-is, so a
+ * last-bit difference between two hosts' embeddings is not amplified by a
+ * renormalisation. Anything else is normalised; a zero vector stays zero.
+ */
+export function toUnit(v: ArrayLike<number>): Float32Array {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) sum += v[i]! * v[i]!;
+    const out = Float32Array.from(v);
+    if (sum === 0 || Math.abs(sum - 1) <= UNIT_TOLERANCE) return out;
+    const norm = Math.sqrt(sum);
+    for (let i = 0; i < out.length; i++) out[i] = out[i]! / norm;
+    return out;
+}
+
+/**
+ * The symmetric scale for a set of (normalised) vectors: CODE_MAX over the largest
+ * component magnitude, rounded UP to 1/64 first so a little float noise in the
+ * maximum does not move the scale.
+ */
+export function fitScale(vectors: Iterable<ArrayLike<number>>): number {
+    let maxAbs = 0;
+    for (const v of vectors) {
+        for (let i = 0; i < v.length; i++) {
+            const a = Math.abs(v[i]!);
+            if (a > maxAbs) maxAbs = a;
+        }
+    }
+    const bound = Math.max(1, Math.ceil(maxAbs * 64)) / 64;
+    return CODE_MAX / bound;
+}
+
+/** int8 codes of `v` at `scale`, clamped to ±CODE_MAX. */
+export function quantize(v: ArrayLike<number>, scale: number): Int8Array {
+    const out = new Int8Array(v.length);
+    for (let i = 0; i < v.length; i++) {
+        const q = Math.round(v[i]! * scale);
+        out[i] = q > CODE_MAX ? CODE_MAX : q < -CODE_MAX ? -CODE_MAX : q;
+    }
+    return out;
+}
+
+/** Exact integer dot product of two code vectors. */
+export function dotInt8(a: Int8Array, b: Int8Array): number {
+    const n = Math.min(a.length, b.length);
+    let dot = 0;
+    for (let i = 0; i < n; i++) dot += a[i]! * b[i]!;
+    return dot;
+}
+
+/**
+ * Cosine of two code vectors: an exact integer dot over exact integer norms, then
+ * IEEE `sqrt` and division — both correctly rounded, so the result is the same
+ * everywhere. 0 when either is a zero vector.
+ */
+export function cosineInt8(a: Int8Array, b: Int8Array): number {
+    const denom = Math.sqrt(dotInt8(a, a)) * Math.sqrt(dotInt8(b, b));
+    return denom === 0 ? 0 : dotInt8(a, b) / denom;
+}

package/src/retrieval/knowledge-index/serialize.ts

@@ -0,0 +1,124 @@
+/**
+ * serialize.ts — the versioned binary form of an index state.
+ *
+ * Layout (little-endian, via `bytes.ts`):
+ *   magic "BFKI" · u32 version
+ *   fingerprint · dims · scale · params
+ *   docs (id order): id · text · hash · keys · optional pending float vector
+ *   u8 compacted? → node ids · node hashes · hubs · code-present flags · codes · graph
+ *
+ * Texts travel with the index because the lexical tier, the recompute path and a
+ * re-embed under a new fingerprint all need them. Loading rebuilds the derived
+ * structures (key map, BM25 postings) and gives back the same digest.
+ */
+
+import { compareIds } from '../order.js';
+import type { IndexParams } from './types.js';
+import { createState, indexKeys, type Compacted, type DocEntry, type IndexState } from './state.js';
+import type { CsrLayer } from './csr.js';
+import { ByteReader, ByteWriter } from './bytes.js';
+import { writeGraph, writeParams } from './digest.js';
+
+const MAGIC = [0x42, 0x46, 0x4b, 0x49]; // "BFKI"
+export const SERIALIZE_VERSION = 1;
+
+export function serializeState(state: IndexState): Uint8Array {
+    const w = new ByteWriter();
+    w.raw(Uint8Array.from(MAGIC)).u32(SERIALIZE_VERSION);
+    w.str(state.fingerprint).u32(state.dims).f64(state.scale);
+    writeParams(w, state.params);
+
+    const ids = [...state.docs.keys()].sort(compareIds);
+    w.u32(ids.length);
+    for (const id of ids) {
+        const doc = state.docs.get(id)!;
+        w.str(doc.id).str(doc.text).str(doc.hash).u32(doc.keys.length);
+        for (const key of doc.keys) w.str(key);
+        w.u8(doc.vec ? 1 : 0);
+        if (doc.vec) w.f32s(doc.vec);
+    }
+
+    const c = state.compacted;
+    w.u8(c ? 1 : 0);
+    if (c) {
+        w.u32(c.ids.length);
+        for (let i = 0; i < c.ids.length; i++) w.str(c.ids[i]!).str(c.hashes[i]!);
+        w.bytes(c.hubs);
+        w.bytes(Uint8Array.from(c.codes, (code) => (code ? 1 : 0)));
+        for (const code of c.codes) if (code) w.bytes(code);
+        writeGraph(w, c.graph);
+    }
+    return w.finish();
+}
+
+function readParams(r: ByteReader): IndexParams {
+    return {
+        m: r.u32(),
+        efConstruction: r.u32(),
+        efSearch: r.u32(),
+        hubShare: r.f64(),
+        rerankFactor: r.u32(),
+        lean: r.u8() === 1,
+        rrfK: r.u32(),
+    };
+}
+
+export function deserializeState(bytes: Uint8Array): IndexState {
+    const r = new ByteReader(bytes);
+    const magic = r.raw(4);
+    if (MAGIC.some((b, i) => magic[i] !== b)) throw new Error('knowledge-index: not a serialized index');
+    const version = r.u32();
+    if (version !== SERIALIZE_VERSION) throw new Error(`knowledge-index: unsupported version ${version}`);
+
+    const fingerprint = r.str();
+    const dims = r.u32();
+    const scale = r.f64();
+    const state = createState(readParams(r));
+    Object.assign(state, { fingerprint, dims, scale });
+
+    const docCount = r.u32();
+    for (let i = 0; i < docCount; i++) {
+        const doc: DocEntry = { id: r.str(), text: r.str(), hash: r.str(), keys: [] };
+        const keyCount = r.u32();
+        for (let k = 0; k < keyCount; k++) doc.keys.push(r.str());
+        if (r.u8() === 1) doc.vec = r.f32s();
+        state.docs.set(doc.id, doc);
+        indexKeys(state, doc, true);
+        state.lexical.set(doc.id, doc.text);
+    }
+
+    if (r.u8() === 1) {
+        const n = r.u32();
+        const ids: string[] = [];
+        const hashes: string[] = [];
+        for (let i = 0; i < n; i++) {
+            ids.push(r.str());
+            hashes.push(r.str());
+        }
+        const hubs = r.bytes();
+        const present = r.bytes();
+        const codes: Compacted['codes'] = Array.from(present, (p) => {
+            if (p !== 1) return undefined;
+            const raw = r.bytes();
+            return new Int8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+        });
+        const entry = r.i32();
+        const layerCount = r.u32();
+        const layers: CsrLayer[] = [];
+        for (let l = 0; l < layerCount; l++) {
+            const nodes = r.u32s();
+            const offsets = r.u32s();
+            const neighbours = r.u32s();
+            layers.push(l === 0 ? { offsets, neighbours } : { nodes, offsets, neighbours });
+        }
+        state.compacted = {
+            ids,
+            hashes,
+            codes,
+            hubs,
+            graph: { entry, layers },
+            nodeOf: new Map(ids.map((id, i) => [id, i])),
+        };
+    }
+    return state;
+}

package/src/retrieval/knowledge-index/sha256.ts

@@ -0,0 +1,122 @@
+/**
+ * sha256.ts — a synchronous, pure-TypeScript SHA-256 (FIPS 180-4).
+ *
+ * The knowledge index names its state with a digest that must be identical on
+ * every host. WebCrypto is async and `node:crypto` is Node-only, so this is the
+ * one portable, synchronous hasher in the package: it runs in a Worker, a browser
+ * and Node, and it is incremental so a large state is hashed without first
+ * concatenating it.
+ */
+
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const encoder = new TextEncoder();
+
+/** Incremental SHA-256: `update(...)` any number of times, then `digest()` once. */
+export class Sha256 {
+    private readonly _h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    private readonly _block = new Uint8Array(64);
+    private readonly _w = new Uint32Array(64);
+    private _blockLen = 0;
+    private _bytes = 0;
+    private _done = false;
+
+    /** Feeds bytes, or a string as UTF-8. */
+    update(data: Uint8Array | string): this {
+        if (this._done) throw new Error('Sha256: update after digest');
+        const bytes = typeof data === 'string' ? encoder.encode(data) : data;
+        this._bytes += bytes.length;
+        let i = 0;
+        while (i < bytes.length) {
+            const take = Math.min(64 - this._blockLen, bytes.length - i);
+            this._block.set(bytes.subarray(i, i + take), this._blockLen);
+            this._blockLen += take;
+            i += take;
+            if (this._blockLen === 64) {
+                this._compress();
+                this._blockLen = 0;
+            }
+        }
+        return this;
+    }
+
+    /** The 32-byte digest. The hasher is finished afterwards. */
+    digest(): Uint8Array {
+        if (this._done) throw new Error('Sha256: digest called twice');
+        const bitsHi = Math.floor(this._bytes / 0x20000000);
+        const bitsLo = (this._bytes * 8) >>> 0;
+        this.update(new Uint8Array([0x80]));
+        while (this._blockLen !== 56) this.update(new Uint8Array(1));
+        const len = new Uint8Array(8);
+        const view = new DataView(len.buffer);
+        view.setUint32(0, bitsHi);
+        view.setUint32(4, bitsLo);
+        this.update(len);
+        this._done = true;
+        const out = new Uint8Array(32);
+        const outView = new DataView(out.buffer);
+        for (let j = 0; j < 8; j++) outView.setUint32(j * 4, this._h[j]!);
+        return out;
+    }
+
+    /** The digest as lowercase hex. */
+    hex(): string {
+        return toHex(this.digest());
+    }
+
+    private _compress(): void {
+        const w = this._w;
+        const b = this._block;
+        for (let t = 0; t < 16; t++) {
+            w[t] = ((b[t * 4]! << 24) | (b[t * 4 + 1]! << 16) | (b[t * 4 + 2]! << 8) | b[t * 4 + 3]!) >>> 0;
+        }
+        for (let t = 16; t < 64; t++) {
+            const x = w[t - 15]!;
+            const y = w[t - 2]!;
+            const s0 = ((x >>> 7) | (x << 25)) ^ ((x >>> 18) | (x << 14)) ^ (x >>> 3);
+            const s1 = ((y >>> 17) | (y << 15)) ^ ((y >>> 19) | (y << 13)) ^ (y >>> 10);
+            w[t] = (w[t - 16]! + s0 + w[t - 7]! + s1) >>> 0;
+        }
+        const h = this._h;
+        let a = h[0]!, bb = h[1]!, c = h[2]!, d = h[3]!, e = h[4]!, f = h[5]!, g = h[6]!, hh = h[7]!;
+        for (let t = 0; t < 64; t++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + S1 + ch + K[t]! + w[t]!) >>> 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & bb) ^ (a & c) ^ (bb & c);
+            const t2 = (S0 + maj) >>> 0;
+            hh = g; g = f; f = e; e = (d + t1) >>> 0;
+            d = c; c = bb; bb = a; a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0]! + a) >>> 0; h[1] = (h[1]! + bb) >>> 0; h[2] = (h[2]! + c) >>> 0; h[3] = (h[3]! + d) >>> 0;
+        h[4] = (h[4]! + e) >>> 0; h[5] = (h[5]! + f) >>> 0; h[6] = (h[6]! + g) >>> 0; h[7] = (h[7]! + hh) >>> 0;
+    }
+}
+
+function toHex(bytes: Uint8Array): string {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++) s += bytes[i]!.toString(16).padStart(2, '0');
+    return s;
+}
+
+/** SHA-256 of a string (UTF-8) or bytes. */
+export function sha256(data: Uint8Array | string): Uint8Array {
+    return new Sha256().update(data).digest();
+}
+
+/** SHA-256 hex of a string (UTF-8) or bytes. */
+export function sha256Hex(data: Uint8Array | string): string {
+    return new Sha256().update(data).hex();
+}

package/src/retrieval/knowledge-index/state.ts

@@ -0,0 +1,108 @@
+/**
+ * state.ts — the knowledge index's in-memory state, shared by the cascade,
+ * compaction, digest and serializer. Everything a result depends on lives here,
+ * so `digest()` can name it and `serialize()` can carry it.
+ */
+
+import type { EmbedderPort, IndexParams, IndexTier } from './types.js';
+import type { CsrGraph } from './csr.js';
+import { LexicalIndex } from './lexical.js';
+import { foldKey } from './tokenize.js';
+
+export const DEFAULT_INDEX_PARAMS: Readonly<IndexParams> = Object.freeze({
+    m: 16,
+    efConstruction: 200,
+    efSearch: 64,
+    hubShare: 0.02,
+    rerankFactor: 4,
+    lean: false,
+    rrfK: 60,
+});
+
+/** One live card. `vec` is its unit float embedding while it is not yet in the graph. */
+export interface DocEntry {
+    id: string;
+    text: string;
+    /** Case-folded, de-duplicated, sorted. */
+    keys: string[];
+    hash: string;
+    vec?: Float32Array;
+}
+
+/** The canonical, id-ordered snapshot written by `compact()`. Node index = rank of its id. */
+export interface Compacted {
+    ids: string[];
+    /** The doc hash each node was coded from; a node whose doc changed is stale. */
+    hashes: string[];
+    /** int8 codes by node; `undefined` where lean mode dropped a non-hub's code. */
+    codes: Array<Int8Array | undefined>;
+    /** 1 for a hub (top `hubShare` by in-degree). */
+    hubs: Uint8Array;
+    graph: CsrGraph;
+    nodeOf: Map<string, number>;
+}
+
+export interface IndexState {
+    params: IndexParams;
+    /** Fingerprint of every stored vector and code; '' when none was ever embedded. */
+    fingerprint: string;
+    dims: number;
+    /** The int8 scale, fixed at the first compaction; 0 until then. */
+    scale: number;
+    docs: Map<string, DocEntry>;
+    /** Folded key → ids. */
+    keys: Map<string, Set<string>>;
+    lexical: LexicalIndex;
+    compacted: Compacted | null;
+}
+
+export function createState(params: Partial<IndexParams> | undefined, embedder?: EmbedderPort): IndexState {
+    return {
+        params: { ...DEFAULT_INDEX_PARAMS, ...params },
+        fingerprint: embedder?.fingerprint ?? '',
+        dims: embedder?.dims ?? 0,
+        scale: 0,
+        docs: new Map(),
+        keys: new Map(),
+        lexical: new LexicalIndex(),
+        compacted: null,
+    };
+}
+
+/** Folded, unique, sorted keys. */
+export function canonicalKeys(keys: readonly string[] | undefined): string[] {
+    return [...new Set((keys ?? []).map(foldKey).filter(Boolean))].sort();
+}
+
+/** Adds (`on`) or removes a doc's keys from the exact-match map. */
+export function indexKeys(state: IndexState, doc: DocEntry, on: boolean): void {
+    for (const key of doc.keys) {
+        let ids = state.keys.get(key);
+        if (on) {
+            if (!ids) state.keys.set(key, (ids = new Set()));
+            ids.add(doc.id);
+        } else if (ids) {
+            ids.delete(doc.id);
+            if (ids.size === 0) state.keys.delete(key);
+        }
+    }
+}
+
+/** The node index of `id` when its doc is live in the graph at the coded hash, else -1. */
+export function graphNode(state: IndexState, id: string): number {
+    const c = state.compacted;
+    if (!c) return -1;
+    const node = c.nodeOf.get(id);
+    if (node === undefined) return -1;
+    return state.docs.get(id)?.hash === c.hashes[node] ? node : -1;
+}
+
+/** Whether `embedder` may produce vectors comparable with the stored ones. */
+export function denseReady(state: IndexState, embedder: EmbedderPort | undefined): embedder is EmbedderPort {
+    return !!embedder && embedder.fingerprint === state.fingerprint && embedder.dims === state.dims;
+}
+
+/** The tiers a search can run right now. */
+export function availableTiers(state: IndexState, embedder: EmbedderPort | undefined): IndexTier[] {
+    return denseReady(state, embedder) ? ['exact', 'lexical', 'dense'] : ['exact', 'lexical'];
+}

package/src/retrieval/knowledge-index/tokenize.ts

@@ -0,0 +1,41 @@
+/**
+ * tokenize.ts — the code-aware tokenizer the knowledge index's lexical tier uses.
+ *
+ * Cards name things the way code does: `retryPolicy.ts`, `stripe_webhook`,
+ * `api/src/billing/invoice.ts`. The package's plain `tokenize` keeps
+ * `retrypolicy` whole, so "retry policy" never matches it. This splits paths on
+ * separators, then each word on snake_case and camelCase boundaries, and emits
+ * the parts AND the whole compound — an exact identifier still scores higher.
+ *
+ * Lowercasing is `toLowerCase` (locale-free), so the tokens are the same on every
+ * host. Pure and zero-dependency.
+ */
+
+/** camelCase / PascalCase / acronym boundaries: `parseHTTPResponse` → parse, HTTP, Response. */
+function splitCamel(word: string): string[] {
+    return word
+        .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, '$1 $2')
+        .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, '$1 $2')
+        .split(' ');
+}
+
+/**
+ * Splits `text` into lowercase terms: every word (a run of letters, digits and `_`)
+ * yields its snake/camel parts, plus the whole word when it has more than one part.
+ */
+export function codeTokenize(text: string): string[] {
+    const out: string[] = [];
+    for (const word of text.split(/[^\p{L}\p{N}_]+/u)) {
+        if (!word) continue;
+        const parts = word.split('_').flatMap(splitCamel).filter(Boolean).map((p) => p.toLowerCase());
+        if (parts.length === 0) continue;
+        out.push(...parts);
+        if (parts.length > 1) out.push(word.toLowerCase());
+    }
+    return out;
+}
+
+/** Case-folds an exact-match key or query the same way on insert and on lookup. */
+export function foldKey(key: string): string {
+    return key.trim().toLowerCase();
+}

package/src/retrieval/knowledge-index/traverse.ts

@@ -0,0 +1,95 @@
+/**
+ * traverse.ts — HNSW search over the CSR graph with integer scores.
+ *
+ * Greedy descent through the upper layers, then a bounded best-first beam on the
+ * base layer. Scores are int8 dot products (exact integers), and equal scores
+ * break on node index (= id order), so the candidates are bit-identical on every
+ * platform for the same codes and query code.
+ *
+ * Lean mode stores no code for most nodes; `ensure` is called with the nodes about
+ * to be scored so the caller can recompute their codes first. It is awaited only
+ * when it returns a promise, so the non-lean walk never yields.
+ */
+
+import { neighboursOf, type CsrGraph } from './csr.js';
+
+export interface GraphScorer {
+    /** The node's score against the query; higher is nearer. */
+    score(node: number): number;
+    /** Make codes available for `nodes` before they are scored (lean mode). */
+    ensure?(nodes: number[]): Promise<void> | undefined;
+}
+
+export interface GraphCandidate {
+    node: number;
+    score: number;
+}
+
+/** Higher score first, then lower node index. */
+function before(a: GraphCandidate, b: GraphCandidate): boolean {
+    return a.score > b.score || (a.score === b.score && a.node < b.node);
+}
+
+/** Inserts `c` into `list`, kept in {@link before} order. */
+function insertOrdered(list: GraphCandidate[], c: GraphCandidate): void {
+    let lo = 0;
+    let hi = list.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (before(list[mid]!, c)) lo = mid + 1;
+        else hi = mid;
+    }
+    list.splice(lo, 0, c);
+}
+
+/** The scorer's `ensure`, or `undefined` when there is nothing to wait for. */
+function ensure(scorer: GraphScorer, nodes: number[]): Promise<void> | undefined {
+    if (!scorer.ensure || nodes.length === 0) return undefined;
+    return scorer.ensure(nodes);
+}
+
+/** The best `ef` nodes for the query, in {@link before} order. */
+export async function searchGraph(graph: CsrGraph, scorer: GraphScorer, ef: number): Promise<GraphCandidate[]> {
+    if (graph.entry < 0 || graph.layers.length === 0 || ef <= 0) return [];
+    { const p = ensure(scorer, [graph.entry]); if (p) await p; }
+    let ep: GraphCandidate = { node: graph.entry, score: scorer.score(graph.entry) };
+
+    for (let l = graph.layers.length - 1; l > 0; l--) {
+        let improved = true;
+        while (improved) {
+            improved = false;
+            const nbs = Array.from(neighboursOf(graph.layers[l]!, ep.node));
+            const p = ensure(scorer, nbs);
+            if (p) await p;
+            for (const node of nbs) {
+                const c = { node, score: scorer.score(node) };
+                if (before(c, ep)) {
+                    ep = c;
+                    improved = true;
+                }
+            }
+        }
+    }
+
+    const base = graph.layers[0]!;
+    const visited = new Set<number>([ep.node]);
+    const frontier: GraphCandidate[] = [ep];
+    const results: GraphCandidate[] = [ep];
+    while (frontier.length > 0) {
+        const cur = frontier.shift()!;
+        if (results.length >= ef && before(results[results.length - 1]!, cur)) break;
+        const fresh = Array.from(neighboursOf(base, cur.node)).filter((node) => !visited.has(node));
+        for (const node of fresh) visited.add(node);
+        const p = ensure(scorer, fresh);
+        if (p) await p;
+        for (const node of fresh) {
+            const c = { node, score: scorer.score(node) };
+            if (results.length < ef || before(c, results[results.length - 1]!)) {
+                insertOrdered(frontier, c);
+                insertOrdered(results, c);
+                if (results.length > ef) results.pop();
+            }
+        }
+    }
+    return results;
+}

package/src/retrieval/knowledge-index/types.ts

@@ -0,0 +1,78 @@
+/**
+ * The knowledge index contract — a deterministic, LEANN-style index over knowledge-graph
+ * cards (design: Builderforce.ai/docs/design/deterministic-knowledge-index.md).
+ *
+ * Every result is a pure function of `(digest, query, opts)`: one total order
+ * (`compareHits`), an insertion-order-free graph, integer (int8) traversal similarity.
+ */
+
+/** One card. `id` is stable (a knowledge-graph NodeRef); `hash` defaults to a hash of `text`. */
+export interface IndexDoc {
+    id: string;
+    text: string;
+    /** Exact-match keys (path, basename, symbol, heading slug, entity name) — case-folded on insert. */
+    keys?: string[];
+    hash?: string;
+}
+
+/** The embedder seam. Vectors from two fingerprints are never compared. */
+export interface EmbedderPort {
+    /** model id + version + dims. */
+    fingerprint: string;
+    dims: number;
+    embed(texts: string[]): Promise<Float32Array[]>;
+}
+
+export type IndexTier = 'exact' | 'lexical' | 'dense';
+
+export interface IndexHit {
+    id: string;
+    score: number;
+    tier: IndexTier;
+}
+
+/** Neighbours of a node, supplied by the knowledge graph for recall expansion. */
+export interface GraphNeighbours {
+    neighbours(id: string, edgeKinds?: readonly string[]): ReadonlyArray<{ id: string; kind: string; weight: number }>;
+}
+
+export interface IndexParams {
+    /** HNSW max neighbours for hubs (non-hubs keep m/2 after pruning). Default 16. */
+    m: number;
+    efConstruction: number;
+    efSearch: number;
+    /** Share of nodes (by in-degree) that keep full degree. Default 0.02. */
+    hubShare: number;
+    /** Dense candidates = k * rerankFactor, recomputed in float and reranked. Default 4. */
+    rerankFactor: number;
+    /** Drop int8 codes of non-hub nodes and recompute on the search path. Default false. */
+    lean: boolean;
+    /** RRF constant. Default 60. */
+    rrfK: number;
+}
+
+export interface SimilarPair {
+    a: string;
+    b: string;
+    similarity: number;
+}
+
+export interface KnowledgeIndex {
+    /** Inserts or replaces; skips docs whose hash is unchanged. */
+    upsert(docs: IndexDoc[]): Promise<void>;
+    remove(ids: string[]): void;
+    /** Cascade: exact → lexical → dense (when an embedder of the stored fingerprint is present) → RRF → compareHits. */
+    search(q: string, opts?: { k?: number; tiers?: IndexTier[] }): Promise<IndexHit[]>;
+    /** Adds graph neighbours (score × weight × 0.5 per hop), re-ordered by compareHits. */
+    expand(hits: IndexHit[], graph: GraphNeighbours, opts?: { hops?: 1 | 2; edgeKinds?: string[] }): IndexHit[];
+    /** Deterministic near-duplicate pairs over int8 codes; `idPrefix` filters (e.g. `src:`). */
+    similarPairs(opts: { minSimilarity: number; maxPairs: number; idPrefix?: string }): SimilarPair[];
+    /** Canonical rebuild (ids sorted) — the same doc set + fingerprint ⇒ the same bytes. */
+    compact(): Promise<void>;
+    /** sha-256 hex over the canonical state. */
+    digest(): string;
+    /** Tiers available right now (dense only with a matching embedder). */
+    tiers(): IndexTier[];
+    size(): number;
+    serialize(): Uint8Array;
+}