@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

package/dist/retrieval/knowledge-index/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The knowledge index — a deterministic, LEANN-style index over knowledge-graph
+ * cards (design: Builderforce.ai/docs/design/deterministic-knowledge-index.md).
+ *
+ * Exact → lexical → dense cascade; int8 codes with integer traversal; a
+ * high-degree-preserving pruned graph stored as CSR; float vectors recomputed
+ * only for the candidates being reranked. Every result is a pure function of
+ * `(digest(), query, opts)`.
+ *
+ * Runs in a Worker, the browser and Node: no Node-only API anywhere.
+ */
+import type { EmbedderPort, IndexParams, KnowledgeIndex } from './types.js';
+export interface KnowledgeIndexStorage {
+    nodes: number;
+    codeBytes: number;
+    graphBytes: number;
+    /** What the same nodes would take as float32 vectors. */
+    float32Bytes: number;
+}
+/** The concrete index type: the contract plus diagnostics. */
+export type DeterministicKnowledgeIndexType = KnowledgeIndex & {
+    denseCandidates(q: string, n: number): Promise<string[]>;
+    storage(): KnowledgeIndexStorage;
+};
+export declare function createKnowledgeIndex(opts?: {
+    embedder?: EmbedderPort;
+    params?: Partial<IndexParams>;
+}): DeterministicKnowledgeIndexType;
+/**
+ * Loads a serialized index. With no embedder, or one of another fingerprint, the
+ * dense tier is absent until `compact()` re-embeds every card under the new one.
+ */
+export declare function loadKnowledgeIndex(bytes: Uint8Array, embedder?: EmbedderPort): DeterministicKnowledgeIndexType;
+export type { EmbedderPort, GraphNeighbours, IndexDoc, IndexHit, IndexParams, IndexTier, KnowledgeIndex, SimilarPair } from './types.js';
+export { DEFAULT_INDEX_PARAMS } from './state.js';
+export { codeTokenize } from './tokenize.js';
+export { hashDocText } from './digest.js';
+export { sha256, sha256Hex, Sha256 } from './sha256.js';
+export { EXPAND_HOP_DECAY } from './expand.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAuC,WAAW,EAAa,cAAc,EAAe,MAAM,YAAY,CAAC;AAoHzI,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,MAAM,+BAA+B,GAAG,cAAc,GAAG;IAC3D,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,OAAO,IAAI,qBAAqB,CAAC;CACpC,CAAC;AAEF,wBAAgB,oBAAoB,CAChC,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;CAAO,GACtE,+BAA+B,CAEjC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,+BAA+B,CAE9G;AAED,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzI,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/retrieval/knowledge-index/index.js

@@ -0,0 +1,134 @@
+/**
+ * The knowledge index — a deterministic, LEANN-style index over knowledge-graph
+ * cards (design: Builderforce.ai/docs/design/deterministic-knowledge-index.md).
+ *
+ * Exact → lexical → dense cascade; int8 codes with integer traversal; a
+ * high-degree-preserving pruned graph stored as CSR; float vectors recomputed
+ * only for the candidates being reranked. Every result is a pure function of
+ * `(digest(), query, opts)`.
+ *
+ * Runs in a Worker, the browser and Node: no Node-only API anywhere.
+ */
+import { availableTiers, canonicalKeys, createState, denseReady, graphNode, indexKeys } from './state.js';
+import { EmbeddingCache } from './embeddings.js';
+import { cascadeSearch, denseCandidates } from './cascade.js';
+import { compactState } from './compact.js';
+import { expandHits } from './expand.js';
+import { similarPairs } from './pairs.js';
+import { hashDocText, stateDigest } from './digest.js';
+import { deserializeState, serializeState } from './serialize.js';
+class DeterministicKnowledgeIndex {
+    _state;
+    _embedder;
+    _cache;
+    _digest = null;
+    constructor(_state, _embedder) {
+        this._state = _state;
+        this._embedder = _embedder;
+        this._cache = _embedder ? new EmbeddingCache(_embedder) : undefined;
+    }
+    get _ctx() {
+        return { state: this._state, embedder: this._embedder, cache: this._cache };
+    }
+    async upsert(docs) {
+        const s = this._state;
+        const changed = [];
+        for (const d of docs) {
+            const entry = { id: d.id, text: d.text, keys: canonicalKeys(d.keys), hash: d.hash ?? hashDocText(d.text) };
+            const prev = s.docs.get(d.id);
+            if (prev)
+                indexKeys(s, prev, false);
+            if (prev && prev.hash === entry.hash) {
+                prev.keys = entry.keys;
+                indexKeys(s, prev, true);
+                continue;
+            }
+            s.docs.set(entry.id, entry);
+            indexKeys(s, entry, true);
+            s.lexical.set(entry.id, entry.text);
+            changed.push(entry);
+        }
+        this._digest = null;
+        if (!denseReady(s, this._embedder) || !this._cache)
+            return;
+        // Only the cards that are live and not already coded in the graph need a vector.
+        const toEmbed = changed.filter((e) => s.docs.get(e.id) === e && graphNode(s, e.id) < 0);
+        const vecs = await this._cache.vectors(toEmbed);
+        toEmbed.forEach((e, i) => { e.vec = vecs[i]; });
+    }
+    remove(ids) {
+        const s = this._state;
+        for (const id of ids) {
+            const doc = s.docs.get(id);
+            if (!doc)
+                continue;
+            indexKeys(s, doc, false);
+            s.lexical.delete(id);
+            s.docs.delete(id);
+        }
+        this._digest = null;
+    }
+    search(q, opts) {
+        return cascadeSearch(this._ctx, q, opts);
+    }
+    expand(hits, graph, opts) {
+        return expandHits(hits, graph, opts);
+    }
+    similarPairs(opts) {
+        return similarPairs(this._state, opts);
+    }
+    async compact() {
+        await compactState(this._state, this._embedder, this._cache);
+        this._digest = null;
+    }
+    digest() {
+        return (this._digest ??= stateDigest(this._state));
+    }
+    tiers() {
+        return availableTiers(this._state, this._embedder);
+    }
+    size() {
+        return this._state.docs.size;
+    }
+    serialize() {
+        return serializeState(this._state);
+    }
+    /**
+     * Diagnostics: the dense candidate ids for `q` before the float rerank (the
+     * integer graph walk plus not-yet-compacted cards). Empty without the dense tier.
+     */
+    async denseCandidates(q, n) {
+        if (!denseReady(this._state, this._embedder) || !this._cache)
+            return [];
+        return denseCandidates(this._ctx, await this._cache.query(q), n);
+    }
+    /** Diagnostics: stored bytes of the int8 codes and the CSR graph, against float32. */
+    storage() {
+        const c = this._state.compacted;
+        if (!c)
+            return { nodes: 0, codeBytes: 0, graphBytes: 0, float32Bytes: 0 };
+        let codeBytes = 0;
+        for (const code of c.codes)
+            codeBytes += code?.byteLength ?? 0;
+        let graphBytes = 0;
+        for (const l of c.graph.layers)
+            graphBytes += (l.nodes?.byteLength ?? 0) + l.offsets.byteLength + l.neighbours.byteLength;
+        return { nodes: c.ids.length, codeBytes, graphBytes, float32Bytes: c.ids.length * this._state.dims * 4 };
+    }
+}
+export function createKnowledgeIndex(opts = {}) {
+    return new DeterministicKnowledgeIndex(createState(opts.params, opts.embedder), opts.embedder);
+}
+/**
+ * Loads a serialized index. With no embedder, or one of another fingerprint, the
+ * dense tier is absent until `compact()` re-embeds every card under the new one.
+ */
+export function loadKnowledgeIndex(bytes, embedder) {
+    return new DeterministicKnowledgeIndex(deserializeState(bytes), embedder);
+}
+export { DEFAULT_INDEX_PARAMS } from './state.js';
+export { codeTokenize } from './tokenize.js';
+export { hashDocText } from './digest.js';
+export { sha256, sha256Hex, Sha256 } from './sha256.js';
+export { EXPAND_HOP_DECAY } from './expand.js';
+//# sourceMappingURL=index.js.map

package/dist/retrieval/knowledge-index/index.js.map

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

package/dist/retrieval/knowledge-index/lexical.d.ts

@@ -0,0 +1,26 @@
+/**
+ * lexical.ts — the knowledge index's BM25 tier, as an incremental inverted index.
+ *
+ * `bm25Search` rebuilds its term table per call, which is right for a bounded
+ * candidate set and wrong for 50k cards queried on every prompt. This keeps the
+ * postings across upserts and scores with the SAME Okapi core (`bm25Idf`,
+ * `bm25LengthNorm`, `bm25TermScore`) — the formula is not restated here.
+ */
+export interface LexicalHit {
+    id: string;
+    score: number;
+}
+export declare class LexicalIndex {
+    /** term → (doc id → term frequency). */
+    private readonly _postings;
+    /** doc id → its distinct terms and token count. */
+    private readonly _docs;
+    private _totalLen;
+    get size(): number;
+    /** Indexes (or re-indexes) one document. */
+    set(id: string, text: string): void;
+    delete(id: string): void;
+    /** BM25 hits for `query`, best first ({@link compareHits}), at most `limit`. */
+    search(query: string, limit: number): LexicalHit[];
+}
+//# sourceMappingURL=lexical.d.ts.map

package/dist/retrieval/knowledge-index/lexical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/lexical.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,YAAY;IACrB,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IACpE,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuD;IAC7E,OAAO,CAAC,SAAS,CAAK;IAEtB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,4CAA4C;IAC5C,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAcnC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAYxB,gFAAgF;IAChF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE;CAoBrD"}

package/dist/retrieval/knowledge-index/lexical.js

@@ -0,0 +1,76 @@
+/**
+ * lexical.ts — the knowledge index's BM25 tier, as an incremental inverted index.
+ *
+ * `bm25Search` rebuilds its term table per call, which is right for a bounded
+ * candidate set and wrong for 50k cards queried on every prompt. This keeps the
+ * postings across upserts and scores with the SAME Okapi core (`bm25Idf`,
+ * `bm25LengthNorm`, `bm25TermScore`) — the formula is not restated here.
+ */
+import { bm25Idf, bm25LengthNorm, bm25TermScore } from '../bm25.js';
+import { compareHits } from '../order.js';
+import { codeTokenize } from './tokenize.js';
+export class LexicalIndex {
+    /** term → (doc id → term frequency). */
+    _postings = new Map();
+    /** doc id → its distinct terms and token count. */
+    _docs = new Map();
+    _totalLen = 0;
+    get size() {
+        return this._docs.size;
+    }
+    /** Indexes (or re-indexes) one document. */
+    set(id, text) {
+        this.delete(id);
+        const tokens = codeTokenize(text);
+        const tf = new Map();
+        for (const t of tokens)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        for (const [term, f] of tf) {
+            let posting = this._postings.get(term);
+            if (!posting)
+                this._postings.set(term, (posting = new Map()));
+            posting.set(id, f);
+        }
+        this._docs.set(id, { terms: [...tf.keys()], len: tokens.length });
+        this._totalLen += tokens.length;
+    }
+    delete(id) {
+        const doc = this._docs.get(id);
+        if (!doc)
+            return;
+        for (const term of doc.terms) {
+            const posting = this._postings.get(term);
+            posting?.delete(id);
+            if (posting && posting.size === 0)
+                this._postings.delete(term);
+        }
+        this._totalLen -= doc.len;
+        this._docs.delete(id);
+    }
+    /** BM25 hits for `query`, best first ({@link compareHits}), at most `limit`. */
+    search(query, limit) {
+        const n = this._docs.size;
+        if (n === 0 || limit <= 0)
+            return [];
+        const terms = [...new Set(codeTokenize(query))].sort();
+        const avgdl = this._totalLen / n || 1;
+        const scores = new Map();
+        // Terms in sorted order, so each doc's sum is accumulated in the same order everywhere.
+        for (const term of terms) {
+            const posting = this._postings.get(term);
+            if (!posting)
+                continue;
+            const idf = bm25Idf(n, posting.size);
+            for (const [id, f] of posting) {
+                const norm = bm25LengthNorm(this._docs.get(id).len, avgdl);
+                scores.set(id, (scores.get(id) ?? 0) + bm25TermScore(f, idf, norm));
+            }
+        }
+        const hits = [];
+        for (const [id, score] of scores)
+            if (score > 0)
+                hits.push({ id, score });
+        return hits.sort(compareHits).slice(0, limit);
+    }
+}
+//# sourceMappingURL=lexical.js.map

package/dist/retrieval/knowledge-index/lexical.js.map

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

package/dist/retrieval/knowledge-index/pairs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * pairs.ts — near-duplicate pairs over the int8 codes (the Duplication lens,
+ * review-time entity resolution, contradiction candidates).
+ *
+ * Near-duplicates are each other's nearest neighbours, so the candidate pairs are
+ * the compacted graph's edges on every layer rather than all n² pairs. Similarity
+ * is {@link cosineInt8} (exact integers, correctly-rounded sqrt/division). The
+ * order is total: similarity (quantized 1e-4) descending, then `a`, then `b`, and
+ * `a < b` by id in every pair.
+ *
+ * Cards not yet compacted, and lean-mode nodes whose codes were dropped, are not
+ * paired until the next compaction (the call is synchronous; it never embeds).
+ */
+import type { SimilarPair } from './types.js';
+import { type IndexState } from './state.js';
+export interface SimilarPairsOptions {
+    minSimilarity: number;
+    maxPairs: number;
+    idPrefix?: string;
+}
+export declare function similarPairs(state: IndexState, opts: SimilarPairsOptions): SimilarPair[];
+//# sourceMappingURL=pairs.d.ts.map

package/dist/retrieval/knowledge-index/pairs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairs.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/pairs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAIxD,MAAM,WAAW,mBAAmB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,mBAAmB,GAAG,WAAW,EAAE,CA8BxF"}

package/dist/retrieval/knowledge-index/pairs.js

@@ -0,0 +1,51 @@
+/**
+ * pairs.ts — near-duplicate pairs over the int8 codes (the Duplication lens,
+ * review-time entity resolution, contradiction candidates).
+ *
+ * Near-duplicates are each other's nearest neighbours, so the candidate pairs are
+ * the compacted graph's edges on every layer rather than all n² pairs. Similarity
+ * is {@link cosineInt8} (exact integers, correctly-rounded sqrt/division). The
+ * order is total: similarity (quantized 1e-4) descending, then `a`, then `b`, and
+ * `a < b` by id in every pair.
+ *
+ * Cards not yet compacted, and lean-mode nodes whose codes were dropped, are not
+ * paired until the next compaction (the call is synchronous; it never embeds).
+ */
+import { compareIds, quantizeScore, DENSE_SCORE_QUANTUM } from '../order.js';
+import { graphNode } from './state.js';
+import { neighboursOf } from './csr.js';
+import { cosineInt8 } from './quantize.js';
+export function similarPairs(state, opts) {
+    const c = state.compacted;
+    if (!c || opts.maxPairs <= 0)
+        return [];
+    const prefix = opts.idPrefix ?? '';
+    const usable = (node) => !!c.codes[node] && c.ids[node].startsWith(prefix) && graphNode(state, c.ids[node]) === node;
+    const seen = new Set();
+    const pairs = [];
+    for (let a = 0; a < c.ids.length; a++) {
+        if (!usable(a))
+            continue;
+        for (const layer of c.graph.layers) {
+            for (const b of neighboursOf(layer, a)) {
+                if (b === a || !usable(b))
+                    continue;
+                const lo = Math.min(a, b);
+                const hi = Math.max(a, b);
+                const key = `${lo}:${hi}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const similarity = cosineInt8(c.codes[lo], c.codes[hi]);
+                if (similarity >= opts.minSimilarity) {
+                    pairs.push({ a: c.ids[lo], b: c.ids[hi], similarity, q: quantizeScore(similarity, DENSE_SCORE_QUANTUM) });
+                }
+            }
+        }
+    }
+    return pairs
+        .sort((x, y) => (y.q - x.q) || compareIds(x.a, y.a) || compareIds(x.b, y.b))
+        .slice(0, opts.maxPairs)
+        .map(({ a, b, similarity }) => ({ a, b, similarity }));
+}
+//# sourceMappingURL=pairs.js.map

package/dist/retrieval/knowledge-index/pairs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairs.js","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/pairs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,SAAS,EAAmB,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAQ3C,MAAM,UAAU,YAAY,CAAC,KAAiB,EAAE,IAAyB;IACrE,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;IAC1B,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAC5B,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,KAAK,IAAI,CAAC;IAElG,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,KAAK,GAAuC,EAAE,CAAC;IACrD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,SAAS;QACzB,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACjC,KAAK,MAAM,CAAC,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;gBACrC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;oBAAE,SAAS;gBACpC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC1B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC1B,MAAM,GAAG,GAAG,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;gBAC1B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAE,CAAC,CAAC;gBAC1D,IAAI,UAAU,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAE,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAE,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,CAAC,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,CAAC;gBAChH,CAAC;YACL,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,KAAK;SACP,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3E,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC;SACvB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/retrieval/knowledge-index/prune.d.ts

@@ -0,0 +1,21 @@
+/**
+ * prune.ts — high-degree-preserving pruning of the base layer (the LEANN storage
+ * technique).
+ *
+ * Most of a graph index's bytes are base-layer edges. Searches route through the
+ * few well-connected hubs, so those keep their full degree and every other node
+ * keeps half: the top `hubShare` of nodes by in-degree keep `m` edges, the rest
+ * `m / 2`. Upper layers are tiny and stay unpruned.
+ *
+ * Every choice is a total order (in-degree, then node index; similarity, then
+ * node index — and node index is id order), so pruning is deterministic.
+ */
+/**
+ * Prunes base-layer rows. `similarity(a, b)` scores two nodes (higher = nearer).
+ * Each kept row is ordered nearest first.
+ */
+export declare function pruneBaseLayer(rows: ReadonlyArray<readonly number[]>, m: number, hubShare: number, similarity: (a: number, b: number) => number): {
+    rows: number[][];
+    hubs: Uint8Array;
+};
+//# sourceMappingURL=prune.d.ts.map

package/dist/retrieval/knowledge-index/prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;GAGG;AACH,wBAAgB,cAAc,CAC1B,IAAI,EAAE,aAAa,CAAC,SAAS,MAAM,EAAE,CAAC,EACtC,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,GAC7C;IAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAuBxC"}

package/dist/retrieval/knowledge-index/prune.js

@@ -0,0 +1,43 @@
+/**
+ * prune.ts — high-degree-preserving pruning of the base layer (the LEANN storage
+ * technique).
+ *
+ * Most of a graph index's bytes are base-layer edges. Searches route through the
+ * few well-connected hubs, so those keep their full degree and every other node
+ * keeps half: the top `hubShare` of nodes by in-degree keep `m` edges, the rest
+ * `m / 2`. Upper layers are tiny and stay unpruned.
+ *
+ * Every choice is a total order (in-degree, then node index; similarity, then
+ * node index — and node index is id order), so pruning is deterministic.
+ */
+import { compareScoreThenId, DENSE_SCORE_QUANTUM } from '../order.js';
+/**
+ * Prunes base-layer rows. `similarity(a, b)` scores two nodes (higher = nearer).
+ * Each kept row is ordered nearest first.
+ */
+export function pruneBaseLayer(rows, m, hubShare, similarity) {
+    const n = rows.length;
+    const inDegree = new Uint32Array(n);
+    for (const row of rows)
+        for (const to of row)
+            inDegree[to] += 1;
+    const hubs = new Uint8Array(n);
+    const hubCount = n === 0 ? 0 : Math.min(n, Math.max(1, Math.ceil(n * Math.max(0, hubShare))));
+    const byDegree = Array.from({ length: n }, (_, i) => i)
+        .sort((a, b) => inDegree[b] - inDegree[a] || a - b);
+    for (let i = 0; i < hubCount; i++)
+        hubs[byDegree[i]] = 1;
+    const full = Math.max(1, m);
+    const half = Math.max(1, Math.floor(m / 2));
+    const pruned = rows.map((row, node) => {
+        const keep = hubs[node] ? full : half;
+        return [...new Set(row)]
+            .filter((to) => to !== node)
+            .map((to) => ({ to, score: similarity(node, to) }))
+            .sort((a, b) => compareScoreThenId(a.score, a.to, b.score, b.to, DENSE_SCORE_QUANTUM))
+            .slice(0, keep)
+            .map((e) => e.to);
+    });
+    return { rows: pruned, hubs };
+}
+//# sourceMappingURL=prune.js.map

package/dist/retrieval/knowledge-index/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.js","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEtE;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC1B,IAAsC,EACtC,CAAS,EACT,QAAgB,EAChB,UAA4C;IAE5C,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,MAAM,QAAQ,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAEhE,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAE,GAAG,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,CAAC;IAE1D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACtC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;aACnB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;aAC3B,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;aAClD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,mBAAmB,CAAC,CAAC;aACrF,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;aACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC"}

package/dist/retrieval/knowledge-index/quantize.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare const CODE_MAX = 127;
+/**
+ * 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 declare function toUnit(v: ArrayLike<number>): Float32Array;
+/**
+ * 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 declare function fitScale(vectors: Iterable<ArrayLike<number>>): number;
+/** int8 codes of `v` at `scale`, clamped to ±CODE_MAX. */
+export declare function quantize(v: ArrayLike<number>, scale: number): Int8Array;
+/** Exact integer dot product of two code vectors. */
+export declare function dotInt8(a: Int8Array, b: Int8Array): number;
+/**
+ * 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 declare function cosineInt8(a: Int8Array, b: Int8Array): number;
+//# sourceMappingURL=quantize.d.ts.map

package/dist/retrieval/knowledge-index/quantize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quantize.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/quantize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oEAAoE;AACpE,eAAO,MAAM,QAAQ,MAAM,CAAC;AAK5B;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,YAAY,CAQzD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAUrE;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAOvE;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAK1D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAG7D"}

package/dist/retrieval/knowledge-index/quantize.js

@@ -0,0 +1,77 @@
+/**
+ * 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) {
+    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) {
+    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, scale) {
+    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, b) {
+    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, b) {
+    const denom = Math.sqrt(dotInt8(a, a)) * Math.sqrt(dotInt8(b, b));
+    return denom === 0 ? 0 : dotInt8(a, b) / denom;
+}
+//# sourceMappingURL=quantize.js.map

package/dist/retrieval/knowledge-index/quantize.js.map

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

package/dist/retrieval/knowledge-index/serialize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { type IndexState } from './state.js';
+export declare const SERIALIZE_VERSION = 1;
+export declare function serializeState(state: IndexState): Uint8Array;
+export declare function deserializeState(bytes: Uint8Array): IndexState;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/retrieval/knowledge-index/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAyD,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAMpG,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CA2B5D;AAcD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CA0D9D"}