@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

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

@@ -0,0 +1,111 @@
+/**
+ * cascade.ts — the knowledge index's search: cheapest tier first.
+ *
+ *   1. exact    — the folded `keys` map; a hit scores 1.0, and when the exact hits
+ *                 fill `k` nothing else runs;
+ *   2. lexical  — BM25 over card text with the code-aware tokenizer;
+ *   3. dense    — int8 graph search for `k × rerankFactor` candidates (plus the
+ *                 cards not yet compacted), then a float rerank over vectors
+ *                 recomputed through the hash-keyed LRU;
+ *   4. fuse     — RRF over the lexical and dense lists; exact hits stay on top at
+ *                 1.0; everything in {@link compareHits} order.
+ *
+ * Dense runs only with an embedder of the stored fingerprint — otherwise the tier
+ * is absent, never silently replaced.
+ */
+import { reciprocalRankFusion } from '../fusion.js';
+import { compareDenseHits, compareHits } from '../order.js';
+import { cosineSimilarity } from '../../similarity/index.js';
+import { availableTiers, graphNode } from './state.js';
+import { dotInt8, quantize } from './quantize.js';
+import { searchGraph } from './traverse.js';
+import { foldKey } from './tokenize.js';
+/** Exact-tier ids for `q`, ascending. */
+function exactIds(state, q) {
+    const ids = state.keys.get(foldKey(q));
+    return ids ? [...ids].sort() : [];
+}
+/**
+ * Dense candidates before the float rerank: the best `n` live graph nodes by
+ * integer dot product, plus the best `n` cards not yet in the graph. Ids, unordered
+ * between the two sources (the rerank orders them).
+ */
+export async function denseCandidates(ctx, qv, n) {
+    const { state, cache } = ctx;
+    const out = new Set();
+    const c = state.compacted;
+    if (c && state.scale > 0) {
+        const qc = quantize(qv, state.scale);
+        const recomputed = new Map();
+        const codeOf = (node) => c.codes[node] ?? recomputed.get(node);
+        const found = await searchGraph(c.graph, {
+            score: (node) => {
+                const code = codeOf(node);
+                return code ? dotInt8(qc, code) : -Infinity;
+            },
+            ensure: cache && state.params.lean ? (nodes) => {
+                const live = nodes.filter((node) => !codeOf(node) && graphNode(state, c.ids[node]) === node);
+                if (live.length === 0)
+                    return undefined;
+                return cache.vectors(live.map((node) => state.docs.get(c.ids[node]))).then((vecs) => {
+                    live.forEach((node, i) => recomputed.set(node, quantize(vecs[i], state.scale)));
+                });
+            } : undefined,
+        }, Math.max(state.params.efSearch, n));
+        for (const hit of found) {
+            if (out.size >= n)
+                break;
+            if (hit.score !== -Infinity && graphNode(state, c.ids[hit.node]) === hit.node)
+                out.add(c.ids[hit.node]);
+        }
+    }
+    const pending = [];
+    for (const doc of state.docs.values()) {
+        if (doc.vec && graphNode(state, doc.id) < 0)
+            pending.push({ id: doc.id, score: cosineSimilarity(qv, doc.vec) });
+    }
+    for (const hit of pending.sort(compareDenseHits).slice(0, n))
+        out.add(hit.id);
+    return [...out];
+}
+/** The dense tier: candidates, then float recompute + rerank, best first. */
+async function denseRank(ctx, q, n) {
+    const cache = ctx.cache;
+    const qv = await cache.query(q);
+    const ids = await denseCandidates(ctx, qv, n);
+    const docs = ids.map((id) => ctx.state.docs.get(id));
+    const needVec = docs.filter((d) => !d.vec);
+    const fresh = await cache.vectors(needVec);
+    const vecOf = new Map(needVec.map((d, i) => [d, fresh[i]]));
+    return docs
+        .map((d) => ({ id: d.id, score: cosineSimilarity(qv, d.vec ?? vecOf.get(d)) }))
+        .sort(compareDenseHits)
+        .slice(0, n);
+}
+/** Runs the cascade. A pure function of the state (its digest), `q` and `opts`. */
+export async function cascadeSearch(ctx, q, opts = {}) {
+    const { state } = ctx;
+    const k = Math.max(0, opts.k ?? 10);
+    if (k === 0 || state.docs.size === 0)
+        return [];
+    const available = availableTiers(state, ctx.embedder);
+    const run = new Set((opts.tiers ?? available).filter((t) => available.includes(t)));
+    const exact = run.has('exact')
+        ? exactIds(state, q).map((id) => ({ id, score: 1, tier: 'exact' }))
+        : [];
+    if (exact.length >= k)
+        return exact.slice(0, k);
+    const exactSet = new Set(exact.map((h) => h.id));
+    const n = Math.max(k, k * state.params.rerankFactor);
+    const lexical = run.has('lexical')
+        ? state.lexical.search(q, n + exact.length).filter((h) => !exactSet.has(h.id)).map((h) => h.id)
+        : [];
+    const dense = run.has('dense')
+        ? (await denseRank(ctx, q, n + exact.length)).filter((h) => !exactSet.has(h.id)).map((h) => h.id)
+        : [];
+    const lexicalSet = new Set(lexical);
+    const fused = reciprocalRankFusion([{ ids: lexical }, { ids: dense }].filter((l) => l.ids.length > 0), state.params.rrfK)
+        .map((h) => ({ id: h.id, score: h.score, tier: lexicalSet.has(h.id) ? 'lexical' : 'dense' }));
+    return [...exact, ...fused].sort(compareHits).slice(0, k);
+}
+//# sourceMappingURL=cascade.js.map

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * compact.ts — the canonical rebuild.
+ *
+ * Every live card, in id order, is coded (an unchanged node keeps its code; a new
+ * or changed card is quantized from its float vector) and the graph is rebuilt
+ * from those codes. Since levels come from id hashes, inserts are id-ordered and
+ * every tie breaks on id, the same card set and fingerprint give the same bytes
+ * whatever order the upserts arrived in.
+ *
+ * The int8 scale is fitted at the first compaction and fixed after it. An embedder
+ * whose fingerprint differs from the stored one is never mixed in: compaction
+ * drops every stored vector and code and re-embeds all cards under it.
+ */
+import type { EmbedderPort } from './types.js';
+import { type IndexState } from './state.js';
+import type { EmbeddingCache } from './embeddings.js';
+export declare function compactState(state: IndexState, embedder: EmbedderPort | undefined, cache: EmbeddingCache | undefined): Promise<void>;
+//# sourceMappingURL=compact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/compact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAA4B,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAUtD,wBAAsB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,GAAG,SAAS,EAAE,KAAK,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAwC1I"}

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

@@ -0,0 +1,64 @@
+/**
+ * compact.ts — the canonical rebuild.
+ *
+ * Every live card, in id order, is coded (an unchanged node keeps its code; a new
+ * or changed card is quantized from its float vector) and the graph is rebuilt
+ * from those codes. Since levels come from id hashes, inserts are id-ordered and
+ * every tie breaks on id, the same card set and fingerprint give the same bytes
+ * whatever order the upserts arrived in.
+ *
+ * The int8 scale is fitted at the first compaction and fixed after it. An embedder
+ * whose fingerprint differs from the stored one is never mixed in: compaction
+ * drops every stored vector and code and re-embeds all cards under it.
+ */
+import { compareIds } from '../order.js';
+import { graphNode } from './state.js';
+import { fitScale, quantize } from './quantize.js';
+import { buildGraph } from './csr.js';
+/** Float vectors for the docs that have neither a reusable code nor a pending vector. */
+async function vectorsFor(cache, docs) {
+    const vecs = await cache.vectors(docs);
+    return new Map(docs.map((d, i) => [d.id, vecs[i]]));
+}
+export async function compactState(state, embedder, cache) {
+    // Nothing to code with: exact and lexical need no compaction, and a stored
+    // graph of another fingerprint is kept for an embedder that matches it.
+    if (!embedder || !cache)
+        return;
+    if (embedder.fingerprint !== state.fingerprint || embedder.dims !== state.dims) {
+        state.fingerprint = embedder.fingerprint;
+        state.dims = embedder.dims;
+        state.scale = 0;
+        state.compacted = null;
+        for (const doc of state.docs.values())
+            doc.vec = undefined;
+    }
+    const ids = [...state.docs.keys()].sort(compareIds);
+    const docs = ids.map((id) => state.docs.get(id));
+    if (docs.length === 0) {
+        state.compacted = null;
+        return;
+    }
+    const old = state.compacted;
+    const reused = docs.map((d) => {
+        const node = graphNode(state, d.id);
+        return node >= 0 && state.scale > 0 ? old.codes[node] : undefined;
+    });
+    const missing = await vectorsFor(cache, docs.filter((d, i) => !reused[i] && !d.vec));
+    const floatOf = (d) => d.vec ?? missing.get(d.id);
+    if (state.scale === 0)
+        state.scale = fitScale(docs.map(floatOf));
+    const codes = docs.map((d, i) => reused[i] ?? quantize(floatOf(d), state.scale));
+    const { graph, hubs } = buildGraph(ids, codes, state.params);
+    state.compacted = {
+        ids,
+        hashes: docs.map((d) => d.hash),
+        codes: state.params.lean ? codes.map((code, i) => (hubs[i] ? code : undefined)) : codes,
+        hubs,
+        graph,
+        nodeOf: new Map(ids.map((id, i) => [id, i])),
+    };
+    for (const doc of docs)
+        doc.vec = undefined;
+}
+//# sourceMappingURL=compact.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * csr.ts — the knowledge index's graph, stored as CSR (compressed sparse rows).
+ *
+ * The graph is built by the package's HNSW over int8 codes (canonical, id-ordered
+ * inserts, hash-derived levels), its base layer is pruned (`prune.ts`), and every
+ * layer is flattened into a `Uint32Array` of offsets plus a `Uint32Array` of
+ * neighbours: no per-node arrays, a fixed byte layout to serialize and hash.
+ *
+ * Layer 0 holds every node and is indexed by node directly. An upper layer holds
+ * only the nodes that reach it, listed ascending in `nodes`.
+ */
+import type { IndexParams } from './types.js';
+export interface CsrLayer {
+    /** Upper layers: the node indices present, ascending. Absent on layer 0 (every node). */
+    nodes?: Uint32Array;
+    /** Row `r`'s neighbours are `neighbours[offsets[r] .. offsets[r + 1])`. */
+    offsets: Uint32Array;
+    neighbours: Uint32Array;
+}
+export interface CsrGraph {
+    /** Entry node for search; -1 for an empty graph. */
+    entry: number;
+    /** layers[0] is the base layer; layers.length - 1 is the top layer. */
+    layers: CsrLayer[];
+}
+export declare const EMPTY_GRAPH: CsrGraph;
+/** Flattens per-row neighbour lists into one CSR layer. */
+export declare function toCsrLayer(rows: ReadonlyArray<readonly number[]>, nodes?: Uint32Array): CsrLayer;
+/** Neighbours of `node` on `layer` (empty when the node is not on it). */
+export declare function neighboursOf(layer: CsrLayer, node: number): Uint32Array;
+/**
+ * Builds the pruned CSR graph over `codes`, whose order is the id order of `ids`
+ * (already sorted and unique). Distances are cosine over the int8 codes, which is
+ * exact integer arithmetic plus correctly-rounded sqrt/division — so the same codes
+ * give the same graph on every platform.
+ */
+export declare function buildGraph(ids: readonly string[], codes: readonly Int8Array[], params: IndexParams): {
+    graph: CsrGraph;
+    hubs: Uint8Array;
+};
+//# sourceMappingURL=csr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csr.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/csr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,MAAM,WAAW,QAAQ;IACrB,yFAAyF;IACzF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,2EAA2E;IAC3E,OAAO,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACrB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,EAAE,QAAQ,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,WAAW,EAAE,QAA+D,CAAC;AAE1F,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,CAUhG;AAiBD,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAIvE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACtB,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,MAAM,EAAE,WAAW,GACpB;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAsBvC"}

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

@@ -0,0 +1,76 @@
+/**
+ * csr.ts — the knowledge index's graph, stored as CSR (compressed sparse rows).
+ *
+ * The graph is built by the package's HNSW over int8 codes (canonical, id-ordered
+ * inserts, hash-derived levels), its base layer is pruned (`prune.ts`), and every
+ * layer is flattened into a `Uint32Array` of offsets plus a `Uint32Array` of
+ * neighbours: no per-node arrays, a fixed byte layout to serialize and hash.
+ *
+ * Layer 0 holds every node and is indexed by node directly. An upper layer holds
+ * only the nodes that reach it, listed ascending in `nodes`.
+ */
+import { HnswIndex } from '../hnsw.js';
+import { pruneBaseLayer } from './prune.js';
+import { cosineInt8 } from './quantize.js';
+export const EMPTY_GRAPH = Object.freeze({ entry: -1, layers: [] });
+/** Flattens per-row neighbour lists into one CSR layer. */
+export function toCsrLayer(rows, nodes) {
+    const offsets = new Uint32Array(rows.length + 1);
+    let total = 0;
+    rows.forEach((row, r) => {
+        total += row.length;
+        offsets[r + 1] = total;
+    });
+    const neighbours = new Uint32Array(total);
+    rows.forEach((row, r) => neighbours.set(row, offsets[r]));
+    return nodes ? { nodes, offsets, neighbours } : { offsets, neighbours };
+}
+/** The row of `node` in `layer`, or -1 when the node is not on it. */
+function rowOf(layer, node) {
+    if (!layer.nodes)
+        return node < layer.offsets.length - 1 ? node : -1;
+    let lo = 0;
+    let hi = layer.nodes.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >>> 1;
+        const v = layer.nodes[mid];
+        if (v === node)
+            return mid;
+        if (v < node)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return -1;
+}
+/** Neighbours of `node` on `layer` (empty when the node is not on it). */
+export function neighboursOf(layer, node) {
+    const r = rowOf(layer, node);
+    if (r < 0)
+        return layer.neighbours.subarray(0, 0);
+    return layer.neighbours.subarray(layer.offsets[r], layer.offsets[r + 1]);
+}
+/**
+ * Builds the pruned CSR graph over `codes`, whose order is the id order of `ids`
+ * (already sorted and unique). Distances are cosine over the int8 codes, which is
+ * exact integer arithmetic plus correctly-rounded sqrt/division — so the same codes
+ * give the same graph on every platform.
+ */
+export function buildGraph(ids, codes, params) {
+    if (ids.length === 0)
+        return { graph: EMPTY_GRAPH, hubs: new Uint8Array(0) };
+    const hnsw = HnswIndex.canonicalBuild(ids.map((id, i) => ({ id, vector: codes[i] })), { M: params.m, efConstruction: params.efConstruction, efSearch: params.efSearch });
+    const view = hnsw.graph();
+    const { rows, hubs } = pruneBaseLayer(view.neighbours.map((layers) => layers[0] ?? []), params.m, params.hubShare, (a, b) => cosineInt8(codes[a], codes[b]));
+    const layers = [toCsrLayer(rows)];
+    for (let l = 1; l <= view.maxLayer; l++) {
+        const present = [];
+        view.neighbours.forEach((layersOfNode, node) => {
+            if (layersOfNode.length > l)
+                present.push(node);
+        });
+        layers.push(toCsrLayer(present.map((node) => view.neighbours[node][l]), Uint32Array.from(present)));
+    }
+    return { graph: { entry: view.entry, layers }, hubs };
+}
+//# sourceMappingURL=csr.js.map

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * digest.ts — the name of an index state.
+ *
+ * sha-256 over the canonical encoding of everything a result depends on: the
+ * fingerprint, dims, params and int8 scale; every live card's (id, hash, keys) in
+ * id order; and the compacted snapshot (node ids and hashes, hubs, the CSR graph).
+ * Every search result is a pure function of `(digest, query, opts)`, which is what
+ * lets a logged digest replay a disputed answer.
+ */
+import type { IndexParams } from './types.js';
+import type { IndexState } from './state.js';
+import type { CsrGraph } from './csr.js';
+import { ByteWriter } from './bytes.js';
+/** The default content hash of a card's text. */
+export declare function hashDocText(text: string): string;
+/** Params in a fixed field order, for the digest and the serialized header. */
+export declare function writeParams(w: ByteWriter, p: IndexParams): void;
+/** The graph's layers: entry, then per layer its node list, offsets and neighbours. */
+export declare function writeGraph(w: ByteWriter, g: CsrGraph): void;
+export declare function stateDigest(state: IndexState): string;
+//# sourceMappingURL=digest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,GAAG,IAAI,CAE/D;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAG3D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAoBrD"}

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

@@ -0,0 +1,50 @@
+/**
+ * digest.ts — the name of an index state.
+ *
+ * sha-256 over the canonical encoding of everything a result depends on: the
+ * fingerprint, dims, params and int8 scale; every live card's (id, hash, keys) in
+ * id order; and the compacted snapshot (node ids and hashes, hubs, the CSR graph).
+ * Every search result is a pure function of `(digest, query, opts)`, which is what
+ * lets a logged digest replay a disputed answer.
+ */
+import { compareIds } from '../order.js';
+import { ByteWriter } from './bytes.js';
+import { sha256Hex } from './sha256.js';
+/** The default content hash of a card's text. */
+export function hashDocText(text) {
+    return sha256Hex(text);
+}
+/** Params in a fixed field order, for the digest and the serialized header. */
+export function writeParams(w, p) {
+    w.u32(p.m).u32(p.efConstruction).u32(p.efSearch).f64(p.hubShare).u32(p.rerankFactor).u8(p.lean ? 1 : 0).u32(p.rrfK);
+}
+/** The graph's layers: entry, then per layer its node list, offsets and neighbours. */
+export function writeGraph(w, g) {
+    w.i32(g.entry).u32(g.layers.length);
+    for (const layer of g.layers)
+        w.u32s(layer.nodes ?? []).u32s(layer.offsets).u32s(layer.neighbours);
+}
+export function stateDigest(state) {
+    const w = new ByteWriter();
+    w.str('bf-knowledge-index/digest/1').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(id).str(doc.hash).u32(doc.keys.length);
+        for (const key of doc.keys)
+            w.str(key);
+    }
+    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);
+        writeGraph(w, c.graph);
+    }
+    return sha256Hex(w.finish());
+}
+//# sourceMappingURL=digest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,iDAAiD;AACjD,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,CAAa,EAAE,CAAc;IACrD,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACxH,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,CAAa,EAAE,CAAW;IACjD,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,MAAM;QAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;AACvG,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAiB;IACzC,MAAM,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC;IAC3B,CAAC,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7F,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpD,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;QAChC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI;YAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC;IAC1B,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChB,IAAI,CAAC,EAAE,CAAC;QACJ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC;QAC1E,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAChB,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,SAAS,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACjC,CAAC"}

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

@@ -0,0 +1,32 @@
+/**
+ * embeddings.ts — the index's recompute path: card text → unit float vector,
+ * through a bounded LRU keyed by the card's content hash.
+ *
+ * LEANN's point is that most vectors need not be stored: the dense tier
+ * recomputes float vectors only for the handful of candidates it reranks, and
+ * lean mode recomputes the codes it dropped. Keying by hash means an unchanged
+ * card is never re-embedded while it stays warm, and a changed one never serves
+ * a stale vector.
+ */
+import type { EmbedderPort } from './types.js';
+/** Default number of vectors held. */
+export declare const EMBEDDING_CACHE_MAX = 8192;
+/** Texts per `embed` call. */
+export declare const EMBED_BATCH = 256;
+export interface Embeddable {
+    hash: string;
+    text: string;
+}
+export declare class EmbeddingCache {
+    private readonly _embedder;
+    private readonly _max;
+    private readonly _lru;
+    constructor(_embedder: EmbedderPort, _max?: number);
+    /** Unit vectors for `items`, in order. Misses are embedded in batches of {@link EMBED_BATCH}. */
+    vectors(items: readonly Embeddable[]): Promise<Float32Array[]>;
+    /** A query (not a card) vector: not cached, the query space is unbounded. */
+    query(text: string): Promise<Float32Array>;
+    private _touch;
+    private _put;
+}
+//# sourceMappingURL=embeddings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,sCAAsC;AACtC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,8BAA8B;AAC9B,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,cAAc;IAInB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;gBAGnC,SAAS,EAAE,YAAY,EACvB,IAAI,GAAE,MAA4B;IAGvD,iGAAiG;IAC3F,OAAO,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA2BpE,6EAA6E;IACvE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAMhD,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,IAAI;CAQf"}

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

@@ -0,0 +1,78 @@
+/**
+ * embeddings.ts — the index's recompute path: card text → unit float vector,
+ * through a bounded LRU keyed by the card's content hash.
+ *
+ * LEANN's point is that most vectors need not be stored: the dense tier
+ * recomputes float vectors only for the handful of candidates it reranks, and
+ * lean mode recomputes the codes it dropped. Keying by hash means an unchanged
+ * card is never re-embedded while it stays warm, and a changed one never serves
+ * a stale vector.
+ */
+import { toUnit } from './quantize.js';
+/** Default number of vectors held. */
+export const EMBEDDING_CACHE_MAX = 8192;
+/** Texts per `embed` call. */
+export const EMBED_BATCH = 256;
+export class EmbeddingCache {
+    _embedder;
+    _max;
+    _lru = new Map();
+    constructor(_embedder, _max = EMBEDDING_CACHE_MAX) {
+        this._embedder = _embedder;
+        this._max = _max;
+    }
+    /** Unit vectors for `items`, in order. Misses are embedded in batches of {@link EMBED_BATCH}. */
+    async vectors(items) {
+        const out = items.map((it) => this._touch(it.hash));
+        const missing = [];
+        const seen = new Map();
+        items.forEach((it, i) => {
+            if (out[i] || seen.has(it.hash))
+                return;
+            seen.set(it.hash, missing.length);
+            missing.push(i);
+        });
+        if (missing.length > 0) {
+            const raw = [];
+            for (let start = 0; start < missing.length; start += EMBED_BATCH) {
+                const batch = missing.slice(start, start + EMBED_BATCH).map((i) => items[i].text);
+                raw.push(...(await this._embedder.embed(batch)));
+            }
+            missing.forEach((i, j) => {
+                const vec = raw[j];
+                if (!vec)
+                    throw new Error('knowledge-index: embedder returned fewer vectors than texts');
+                this._put(items[i].hash, toUnit(vec));
+            });
+            items.forEach((it, i) => {
+                if (!out[i])
+                    out[i] = this._touch(it.hash) ?? toUnit(raw[seen.get(it.hash)]);
+            });
+        }
+        return out;
+    }
+    /** A query (not a card) vector: not cached, the query space is unbounded. */
+    async query(text) {
+        const [vec] = await this._embedder.embed([text]);
+        if (!vec)
+            throw new Error('knowledge-index: embedder returned no vector for the query');
+        return toUnit(vec);
+    }
+    _touch(hash) {
+        const hit = this._lru.get(hash);
+        if (hit) {
+            this._lru.delete(hash);
+            this._lru.set(hash, hit);
+        }
+        return hit;
+    }
+    _put(hash, vec) {
+        this._lru.delete(hash);
+        this._lru.set(hash, vec);
+        while (this._lru.size > this._max) {
+            const oldest = this._lru.keys().next().value;
+            this._lru.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=embeddings.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,sCAAsC;AACtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACxC,8BAA8B;AAC9B,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAO/B,MAAM,OAAO,cAAc;IAIF;IACA;IAJJ,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;IAExD,YACqB,SAAuB,EACvB,OAAe,mBAAmB;QADlC,cAAS,GAAT,SAAS,CAAc;QACvB,SAAI,GAAJ,IAAI,CAA8B;IACpD,CAAC;IAEJ,iGAAiG;IACjG,KAAK,CAAC,OAAO,CAAC,KAA4B;QACtC,MAAM,GAAG,GAAoC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QACrF,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;YACpB,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC;gBAAE,OAAO;YACxC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,GAAG,GAAmB,EAAE,CAAC;YAC/B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,WAAW,EAAE,CAAC;gBAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,CAAC;gBACnF,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACrD,CAAC;YACD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBACrB,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;gBACnB,IAAI,CAAC,GAAG;oBAAE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;gBACzF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;gBACpB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;oBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAE,CAAE,CAAC,CAAC;YACnF,CAAC,CAAC,CAAC;QACP,CAAC;QACD,OAAO,GAAqB,CAAC;IACjC,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,KAAK,CAAC,IAAY;QACpB,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QACxF,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;IAEO,MAAM,CAAC,IAAY;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,GAAG,EAAE,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAEO,IAAI,CAAC,IAAY,EAAE,GAAiB;QACxC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAe,CAAC;YACvD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;IACL,CAAC;CACJ"}

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

@@ -0,0 +1,19 @@
+/**
+ * expand.ts — recall expansion over the knowledge graph's edges.
+ *
+ * A hit alone is an isolated fact; its neighbours make it knowledge (a claim's
+ * source section, the claims contradicting it, the entity it is about). Each hop
+ * scores `parent score × edge weight × 0.5`; a node reached more than one way keeps
+ * its best score; the original hits keep theirs. The result is re-ordered by
+ * {@link compareHits}, so it is deterministic whatever order the graph lists
+ * neighbours in.
+ */
+import type { GraphNeighbours, IndexHit } from './types.js';
+/** The per-hop decay. */
+export declare const EXPAND_HOP_DECAY = 0.5;
+export interface ExpandOptions {
+    hops?: 1 | 2;
+    edgeKinds?: string[];
+}
+export declare function expandHits(hits: readonly IndexHit[], graph: GraphNeighbours, opts?: ExpandOptions): IndexHit[];
+//# sourceMappingURL=expand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/expand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5D,yBAAyB;AACzB,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC1B,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,GAAE,aAAkB,GAAG,QAAQ,EAAE,CAgClH"}

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

@@ -0,0 +1,49 @@
+/**
+ * expand.ts — recall expansion over the knowledge graph's edges.
+ *
+ * A hit alone is an isolated fact; its neighbours make it knowledge (a claim's
+ * source section, the claims contradicting it, the entity it is about). Each hop
+ * scores `parent score × edge weight × 0.5`; a node reached more than one way keeps
+ * its best score; the original hits keep theirs. The result is re-ordered by
+ * {@link compareHits}, so it is deterministic whatever order the graph lists
+ * neighbours in.
+ */
+import { compareHits } from '../order.js';
+/** The per-hop decay. */
+export const EXPAND_HOP_DECAY = 0.5;
+export function expandHits(hits, graph, opts = {}) {
+    const hops = opts.hops ?? 1;
+    const best = new Map();
+    for (const hit of [...hits].sort(compareHits)) {
+        const prev = best.get(hit.id);
+        if (!prev || hit.score > prev.score)
+            best.set(hit.id, { ...hit });
+    }
+    const original = new Set(best.keys());
+    let frontier = [...best.values()];
+    for (let hop = 0; hop < hops; hop++) {
+        const reached = new Map();
+        // Parents in total order, and a strict `>` to replace: equal-score ties keep
+        // the first parent in that order, independent of the graph's listing order.
+        for (const parent of frontier.sort(compareHits)) {
+            for (const edge of graph.neighbours(parent.id, opts.edgeKinds)) {
+                if (original.has(edge.id))
+                    continue;
+                const score = parent.score * edge.weight * EXPAND_HOP_DECAY;
+                const prev = reached.get(edge.id);
+                if (!prev || score > prev.score)
+                    reached.set(edge.id, { id: edge.id, score, tier: parent.tier });
+            }
+        }
+        frontier = [];
+        for (const [id, hit] of reached) {
+            const prev = best.get(id);
+            if (!prev || hit.score > prev.score) {
+                best.set(id, hit);
+                frontier.push(hit);
+            }
+        }
+    }
+    return [...best.values()].sort(compareHits);
+}
+//# sourceMappingURL=expand.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expand.js","sourceRoot":"","sources":["../../../src/retrieval/knowledge-index/expand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,yBAAyB;AACzB,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAOpC,MAAM,UAAU,UAAU,CAAC,IAAyB,EAAE,KAAsB,EAAE,OAAsB,EAAE;IAClG,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAEtC,IAAI,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC5C,6EAA6E;QAC7E,4EAA4E;QAC5E,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC7D,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBAAE,SAAS;gBACpC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,gBAAgB,CAAC;gBAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAClC,IAAI,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACrG,CAAC;QACL,CAAC;QACD,QAAQ,GAAG,EAAE,CAAC;QACd,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1B,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;gBAClC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBAClB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC"}