@juspay/neurolink 10.3.0 → 10.4.0

package/dist/knowledge/defaults.js

@@ -0,0 +1,29 @@
+/**
+ * Central default constants for the knowledge-grounding engine. Kept as
+ * runtime values (not type aliases) so they live outside src/lib/types/.
+ * Every number here is a starting value meant to be tuned through evaluation.
+ */
+/** Field weights for the lexical scorer: title/alias matches outrank body. */
+export const DEFAULT_FIELD_WEIGHTS = {
+    title: 5,
+    aliases: 5,
+    keywords: 3,
+    summary: 3,
+    body: 1,
+};
+/** How many scored candidates enter relationship expansion / assembly. */
+export const DEFAULT_CANDIDATE_LIMIT = 24;
+/** How many primary entries survive into the assembled context. */
+export const DEFAULT_RESULT_LIMIT = 8;
+/** Cap on relationship-expanded entries added after primary retrieval. */
+export const DEFAULT_RELATION_LIMIT = 4;
+/** Additive boost for an exact entry-id / configuration-key match (dominant). */
+export const DEFAULT_EXACT_BOOST = 100;
+/** Additive boost for an exact reviewed-alias phrase match (very high). */
+export const DEFAULT_ALIAS_BOOST = 60;
+/** Grounding-context token budget. */
+export const DEFAULT_MAX_CONTEXT_TOKENS = 4000;
+/** Hard ceiling for one grounding operation before it fails open. */
+export const DEFAULT_TIMEOUT_MS = 800;
+/** Bounded recent-turn window used to contextualize the query. */
+export const DEFAULT_RECENT_TURNS = 4;

package/dist/knowledge/engine.d.ts

@@ -0,0 +1,35 @@
+/**
+ * KnowledgeGroundingEngine — the provider-neutral orchestrator.
+ *
+ * Loads the source set once at construction, reuses the process-level
+ * in-memory index cache when possible, and runs one retrieval + context
+ * assembly per eligible turn. The engine's snapshot is never reset after
+ * construction — sources are supplied only via the constructor config.
+ *
+ * The engine never throws from `ground()` — any failure fails open to "no
+ * grounding" with a `failureReason`, so an informational turn is never broken.
+ * It performs no logging and no telemetry itself; the client wiring reads
+ * `getStatus()`/the outcome metadata and emits spans.
+ */
+import type { KnowledgeEngineStatus, KnowledgeGroundingConfig, KnowledgeGroundingInput, KnowledgeGroundingOutcome } from "../types/index.js";
+export declare class KnowledgeGroundingEngine {
+    private readonly config;
+    private readonly resolved;
+    private snapshot;
+    private buildPromise;
+    private lastError;
+    private validationIssues;
+    private readonly now;
+    constructor(config: KnowledgeGroundingConfig, now?: () => number);
+    isEnabled(): boolean;
+    /** Resolve once the one-time build settles. Safe to call before every turn. */
+    ready(): Promise<void>;
+    getStatus(): KnowledgeEngineStatus;
+    private build;
+    private buildRequest;
+    /**
+     * Retrieve + assemble for one turn. Returns the ephemeral context to inject
+     * (or null), aggregate metadata, and the full retrieval. Never throws.
+     */
+    ground(input: KnowledgeGroundingInput): Promise<KnowledgeGroundingOutcome>;
+}

package/dist/knowledge/engine.js

@@ -0,0 +1,179 @@
+/**
+ * KnowledgeGroundingEngine — the provider-neutral orchestrator.
+ *
+ * Loads the source set once at construction, reuses the process-level
+ * in-memory index cache when possible, and runs one retrieval + context
+ * assembly per eligible turn. The engine's snapshot is never reset after
+ * construction — sources are supplied only via the constructor config.
+ *
+ * The engine never throws from `ground()` — any failure fails open to "no
+ * grounding" with a `failureReason`, so an informational turn is never broken.
+ * It performs no logging and no telemetry itself; the client wiring reads
+ * `getStatus()`/the outcome metadata and emits spans.
+ */
+import { assembleKnowledgeContext } from "./context.js";
+import { DEFAULT_ALIAS_BOOST, DEFAULT_CANDIDATE_LIMIT, DEFAULT_EXACT_BOOST, DEFAULT_FIELD_WEIGHTS, DEFAULT_RECENT_TURNS, DEFAULT_RELATION_LIMIT, DEFAULT_RESULT_LIMIT, DEFAULT_TIMEOUT_MS, } from "./defaults.js";
+import { getOrBuildKnowledgeIndexSnapshot } from "./indexCache.js";
+import { retrieve } from "./retrieval.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
+/** Fallback source version when a source (or manifest) declares none. */
+const FALLBACK_VERSION = "0";
+const resolveRetrieval = (retrieval) => ({
+    candidateLimit: retrieval?.candidateLimit ?? DEFAULT_CANDIDATE_LIMIT,
+    resultLimit: retrieval?.resultLimit ?? DEFAULT_RESULT_LIMIT,
+    relationLimit: retrieval?.relationLimit ?? DEFAULT_RELATION_LIMIT,
+    fieldWeights: retrieval?.fieldWeights ?? DEFAULT_FIELD_WEIGHTS,
+    exactBoost: retrieval?.exactBoost ?? DEFAULT_EXACT_BOOST,
+    aliasBoost: retrieval?.aliasBoost ?? DEFAULT_ALIAS_BOOST,
+});
+const emptyMetadata = (durationMs, failureReason) => ({
+    retrievalMode: "lexical",
+    selectedIds: [],
+    expandedIds: [],
+    candidateCount: 0,
+    contextTokens: 0,
+    truncated: false,
+    durationMs,
+    failureReason,
+});
+export class KnowledgeGroundingEngine {
+    config;
+    resolved;
+    snapshot = null;
+    buildPromise = null;
+    lastError = null;
+    validationIssues = [];
+    now;
+    constructor(config, now = () => Date.now()) {
+        this.config = config;
+        this.resolved = resolveRetrieval(config.retrieval);
+        this.now = now;
+        if (config.enabled && config.sources && config.sources.length > 0) {
+            this.buildPromise = this.build(config.sources).catch((error) => {
+                this.lastError = String(error);
+            });
+        }
+    }
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /** Resolve once the one-time build settles. Safe to call before every turn. */
+    async ready() {
+        if (this.buildPromise) {
+            await this.buildPromise;
+        }
+    }
+    getStatus() {
+        return {
+            enabled: this.config.enabled,
+            ready: this.snapshot !== null,
+            entryCount: this.snapshot?.entryCount ?? 0,
+            lastError: this.lastError,
+            validationIssues: this.validationIssues,
+        };
+    }
+    async build(sources) {
+        const { snapshot, validation } = await getOrBuildKnowledgeIndexSnapshot(sources, FALLBACK_VERSION, this.resolved.fieldWeights);
+        this.validationIssues = validation.issues;
+        if (!validation.ok) {
+            // Never load a partially valid registry — leave the index unbuilt.
+            const errorCount = validation.issues.filter((issue) => issue.level === "error").length;
+            this.lastError = `knowledge validation failed with ${errorCount} error(s)`;
+            return;
+        }
+        // The snapshot may be newly built or reused from another NeuroLink instance
+        // in this process. It is immutable and safe to share across conversations.
+        this.snapshot = snapshot;
+        this.lastError = null;
+    }
+    buildRequest(input) {
+        const scope = input.scope ?? {};
+        return {
+            query: input.query,
+            recentTurns: (input.recentTurns ?? []).slice(-DEFAULT_RECENT_TURNS),
+            enabledIntegrations: scope.enabledIntegrations ?? [],
+        };
+    }
+    /**
+     * Retrieve + assemble for one turn. Returns the ephemeral context to inject
+     * (or null), aggregate metadata, and the full retrieval. Never throws.
+     */
+    async ground(input) {
+        const started = this.now();
+        const wallClockStarted = Date.now();
+        if (!this.config.enabled) {
+            return {
+                ephemeralContext: null,
+                metadata: emptyMetadata(0),
+                retrieval: null,
+            };
+        }
+        try {
+            const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const outcome = await withTimeout((async () => {
+                await this.ready();
+                const snapshot = this.snapshot;
+                if (!snapshot) {
+                    return {
+                        ephemeralContext: null,
+                        metadata: emptyMetadata(this.now() - started, "index-not-ready"),
+                        retrieval: null,
+                    };
+                }
+                const request = this.buildRequest(input);
+                const selection = retrieve(snapshot, request, this.resolved, this.config.blockedDomains);
+                const assembled = assembleKnowledgeContext(selection, this.config.context);
+                const durationMs = this.now() - started;
+                const retrieval = {
+                    entries: [...selection.primary, ...selection.expanded],
+                    assembledContext: assembled.assembledContext,
+                    confidence: selection.confidence,
+                    citations: assembled.citations,
+                    selectedEntryIds: selection.primary.map((entry) => entry.id),
+                    expandedEntryIds: selection.expanded.map((entry) => entry.id),
+                    candidateCount: selection.candidateCount,
+                    contextTokens: assembled.contextTokens,
+                    truncated: assembled.truncated,
+                    durationMs,
+                };
+                const metadata = {
+                    retrievalMode: "lexical",
+                    selectedIds: retrieval.selectedEntryIds,
+                    expandedIds: retrieval.expandedEntryIds,
+                    candidateCount: selection.candidateCount,
+                    contextTokens: assembled.contextTokens,
+                    truncated: assembled.truncated,
+                    durationMs,
+                    confidence: selection.confidence,
+                };
+                // Nothing to inject when retrieval found nothing (or all matches were filtered out).
+                if (!assembled.assembledContext) {
+                    return { ephemeralContext: null, metadata, retrieval };
+                }
+                const ephemeralContext = {
+                    content: assembled.assembledContext,
+                    kind: "knowledge",
+                    trusted: true,
+                    citations: assembled.citations,
+                    metadata: { confidence: selection.confidence },
+                };
+                return { ephemeralContext, metadata, retrieval };
+            })(), timeoutMs, `Knowledge grounding timed out after ${timeoutMs}ms`);
+            // Promise timers cannot pre-empt synchronous indexing/scoring work. Check
+            // elapsed wall time as well so an over-budget synchronous pass still
+            // fails open instead of injecting a late result.
+            if (Date.now() - wallClockStarted > timeoutMs) {
+                throw new Error(`Knowledge grounding timed out after ${timeoutMs}ms`);
+            }
+            return outcome;
+        }
+        catch (error) {
+            // Fail open: no grounding rather than a broken turn.
+            return {
+                ephemeralContext: null,
+                metadata: emptyMetadata(this.now() - started, String(error)),
+                retrieval: null,
+            };
+        }
+    }
+}

package/dist/knowledge/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public runtime exports for the knowledge-grounding engine.
+ *
+ * Per the repo convention, this module barrel re-exports only runtime values
+ * (classes and functions). All knowledge types flow through the canonical
+ * types barrel (`../types/index.js`) and are re-exported from the package root
+ * alongside every other public type.
+ */
+export { KnowledgeGroundingEngine } from "./engine.js";
+export { manifestToSources, normalizeAndValidate, resolveEntry, } from "./resolve.js";
+export { buildDocument, buildIndexSnapshot, KnowledgeLexicalIndex, } from "./knowledgeIndex.js";
+export { assembleKnowledgeContext } from "./context.js";
+export { retrieve } from "./retrieval.js";
+export { normalizePhrases, normalizeText, tokenize } from "./normalize.js";
+export { DEFAULT_ALIAS_BOOST, DEFAULT_CANDIDATE_LIMIT, DEFAULT_EXACT_BOOST, DEFAULT_FIELD_WEIGHTS, DEFAULT_MAX_CONTEXT_TOKENS, DEFAULT_TIMEOUT_MS, DEFAULT_RECENT_TURNS, DEFAULT_RELATION_LIMIT, DEFAULT_RESULT_LIMIT, } from "./defaults.js";

package/dist/knowledge/index.js

@@ -0,0 +1,15 @@
+/**
+ * Public runtime exports for the knowledge-grounding engine.
+ *
+ * Per the repo convention, this module barrel re-exports only runtime values
+ * (classes and functions). All knowledge types flow through the canonical
+ * types barrel (`../types/index.js`) and are re-exported from the package root
+ * alongside every other public type.
+ */
+export { KnowledgeGroundingEngine } from "./engine.js";
+export { manifestToSources, normalizeAndValidate, resolveEntry, } from "./resolve.js";
+export { buildDocument, buildIndexSnapshot, KnowledgeLexicalIndex, } from "./knowledgeIndex.js";
+export { assembleKnowledgeContext } from "./context.js";
+export { retrieve } from "./retrieval.js";
+export { normalizePhrases, normalizeText, tokenize } from "./normalize.js";
+export { DEFAULT_ALIAS_BOOST, DEFAULT_CANDIDATE_LIMIT, DEFAULT_EXACT_BOOST, DEFAULT_FIELD_WEIGHTS, DEFAULT_MAX_CONTEXT_TOKENS, DEFAULT_TIMEOUT_MS, DEFAULT_RECENT_TURNS, DEFAULT_RELATION_LIMIT, DEFAULT_RESULT_LIMIT, } from "./defaults.js";

package/dist/knowledge/indexCache.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Process-level cache for knowledge index snapshots.
+ *
+ * Knowledge sources are constructor-level static content. Multiple NeuroLink
+ * instances in the same server process can therefore share the same immutable
+ * lexical index instead of rebuilding it for every conversation/session.
+ */
+import type { KnowledgeFieldWeights, KnowledgeIndexSnapshot, KnowledgeSource, KnowledgeValidationResult } from "../types/index.js";
+export declare const KNOWLEDGE_INDEX_CACHE_LIMIT = 32;
+/**
+ * Cache key intentionally uses source/version metadata, not conversation scope.
+ * The source content hash prevents stale reuse even when a host forgets to bump
+ * a source version after changing entries.
+ */
+export declare const buildKnowledgeIndexCacheKey: (sources: KnowledgeSource[], fallbackVersion: string, weights: KnowledgeFieldWeights) => string;
+export declare const getOrBuildKnowledgeIndexSnapshot: (sources: KnowledgeSource[], fallbackVersion: string, weights: KnowledgeFieldWeights) => Promise<{
+    snapshot: KnowledgeIndexSnapshot | null;
+    validation: KnowledgeValidationResult;
+}>;

package/dist/knowledge/indexCache.js

@@ -0,0 +1,109 @@
+/**
+ * Process-level cache for knowledge index snapshots.
+ *
+ * Knowledge sources are constructor-level static content. Multiple NeuroLink
+ * instances in the same server process can therefore share the same immutable
+ * lexical index instead of rebuilding it for every conversation/session.
+ */
+import { createHash } from "crypto";
+import { buildIndexSnapshot } from "./knowledgeIndex.js";
+import { normalizeAndValidate, resolveEntry } from "./resolve.js";
+const CACHE_SCHEMA_VERSION = "knowledge-index-cache:v1";
+export const KNOWLEDGE_INDEX_CACHE_LIMIT = 32;
+const indexBuildCache = new Map();
+const rememberCacheEntry = (cacheKey, buildPromise) => {
+    if (indexBuildCache.has(cacheKey)) {
+        indexBuildCache.delete(cacheKey);
+    }
+    indexBuildCache.set(cacheKey, buildPromise);
+    while (indexBuildCache.size > KNOWLEDGE_INDEX_CACHE_LIMIT) {
+        const oldestKey = indexBuildCache.keys().next().value;
+        if (oldestKey === undefined) {
+            return;
+        }
+        indexBuildCache.delete(oldestKey);
+    }
+};
+const escapePart = (value) => encodeURIComponent(value);
+const stableStringify = (value) => {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    const record = value;
+    const entries = Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);
+    return `{${entries.join(",")}}`;
+};
+const compareEntries = (left, right) => left.id.localeCompare(right.id) ||
+    stableStringify(left).localeCompare(stableStringify(right));
+const hashSourceContent = (source, fallbackVersion) => {
+    const version = source.version ?? fallbackVersion;
+    const effectiveContent = {
+        id: source.id,
+        version,
+        entries: source.entries
+            .map((entry) => resolveEntry(entry, version))
+            .sort(compareEntries),
+    };
+    return createHash("sha256")
+        .update(stableStringify(effectiveContent))
+        .digest("hex");
+};
+const formatFieldWeights = (weights) => [
+    `title=${weights.title}`,
+    `aliases=${weights.aliases}`,
+    `keywords=${weights.keywords}`,
+    `summary=${weights.summary}`,
+    `body=${weights.body}`,
+].join(",");
+const formatSource = (source, fallbackVersion) => [
+    escapePart(source.id),
+    escapePart(source.version ?? fallbackVersion),
+    source.entries.length,
+    source.entries
+        .map((entry) => escapePart(entry.id))
+        .sort()
+        .join(","),
+    hashSourceContent(source, fallbackVersion),
+].join(":");
+/**
+ * Cache key intentionally uses source/version metadata, not conversation scope.
+ * The source content hash prevents stale reuse even when a host forgets to bump
+ * a source version after changing entries.
+ */
+export const buildKnowledgeIndexCacheKey = (sources, fallbackVersion, weights) => [
+    CACHE_SCHEMA_VERSION,
+    `weights=${formatFieldWeights(weights)}`,
+    ...sources.map((source) => formatSource(source, fallbackVersion)),
+].join("|");
+export const getOrBuildKnowledgeIndexSnapshot = async (sources, fallbackVersion, weights) => {
+    const cacheKey = buildKnowledgeIndexCacheKey(sources, fallbackVersion, weights);
+    const cached = indexBuildCache.get(cacheKey);
+    if (cached) {
+        rememberCacheEntry(cacheKey, cached);
+        return cached;
+    }
+    const buildPromise = (async () => {
+        const { entries, validation } = await normalizeAndValidate(sources, {
+            manifestVersion: fallbackVersion,
+        });
+        if (!validation.ok) {
+            return { snapshot: null, validation };
+        }
+        return {
+            snapshot: buildIndexSnapshot(entries, weights),
+            validation,
+        };
+    })();
+    rememberCacheEntry(cacheKey, buildPromise);
+    void buildPromise.catch(() => {
+        if (indexBuildCache.get(cacheKey) === buildPromise) {
+            indexBuildCache.delete(cacheKey);
+        }
+    });
+    return buildPromise;
+};

package/dist/knowledge/knowledgeIndex.d.ts

@@ -0,0 +1,41 @@
+/**
+ * In-memory knowledge index construction.
+ *
+ * Index construction is an application-process lifecycle operation, not a
+ * per-session one. A complete `KnowledgeIndexSnapshot` is built once from the
+ * normalized entries and then queried by every turn.
+ *
+ * The lexical scorer is a compact field-aware BM25 (BM25F-style): each of the
+ * five text fields is scored independently and combined with per-field
+ * weights, retaining the per-field breakdown so a retrieval decision is
+ * explainable in traces. No embedding model or vector store is involved.
+ */
+import type { IndexedKnowledgeDocument, KnowledgeFieldWeights, KnowledgeIndexSnapshot, KnowledgeLexicalMatch, NormalizedKnowledgeEntry } from "../types/index.js";
+/**
+ * Field-aware BM25 over the document set. Query text is scored per field and
+ * the weighted per-field scores are summed. Satisfies the structural
+ * `KnowledgeLexicalSearcher` type held by a snapshot.
+ */
+export declare class KnowledgeLexicalIndex {
+    private readonly weights;
+    private readonly postings;
+    private readonly fieldLengths;
+    private readonly fieldTokenTotals;
+    private readonly avgFieldLength;
+    private docCount;
+    constructor(weights: KnowledgeFieldWeights);
+    add(document: IndexedKnowledgeDocument): void;
+    finalize(): void;
+    search(queryTokens: string[], topK: number, eligibleEntryIds?: ReadonlySet<string>): KnowledgeLexicalMatch[];
+}
+/**
+ * Build the internal search document from a normalized entry. `exactKeys`
+ * carry whole-phrase identifiers (entry id and title); each
+ * text field is tokenized for the field-aware scorer.
+ */
+export declare const buildDocument: (entry: NormalizedKnowledgeEntry) => IndexedKnowledgeDocument;
+/**
+ * Build the complete immutable snapshot: entry map, exact/alias/relation
+ * indexes, and the field-aware lexical index.
+ */
+export declare const buildIndexSnapshot: (entries: NormalizedKnowledgeEntry[], weights: KnowledgeFieldWeights) => KnowledgeIndexSnapshot;

package/dist/knowledge/knowledgeIndex.js

@@ -0,0 +1,204 @@
+/**
+ * In-memory knowledge index construction.
+ *
+ * Index construction is an application-process lifecycle operation, not a
+ * per-session one. A complete `KnowledgeIndexSnapshot` is built once from the
+ * normalized entries and then queried by every turn.
+ *
+ * The lexical scorer is a compact field-aware BM25 (BM25F-style): each of the
+ * five text fields is scored independently and combined with per-field
+ * weights, retaining the per-field breakdown so a retrieval decision is
+ * explainable in traces. No embedding model or vector store is involved.
+ */
+import { normalizePhrases, normalizeText, tokenize } from "./normalize.js";
+const FIELD_NAMES = [
+    "title",
+    "aliases",
+    "keywords",
+    "summary",
+    "body",
+];
+/** Okapi BM25 saturation and length-normalization parameters. */
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+/**
+ * Field-aware BM25 over the document set. Query text is scored per field and
+ * the weighted per-field scores are summed. Satisfies the structural
+ * `KnowledgeLexicalSearcher` type held by a snapshot.
+ */
+export class KnowledgeLexicalIndex {
+    weights;
+    // field -> (term -> (docId -> term frequency))
+    postings = new Map();
+    // field -> (docId -> field length in tokens)
+    fieldLengths = new Map();
+    // field -> total tokens across all docs (for average length)
+    fieldTokenTotals = new Map();
+    // field -> average field length (computed in finalize)
+    avgFieldLength = new Map();
+    docCount = 0;
+    constructor(weights) {
+        this.weights = weights;
+        for (const field of FIELD_NAMES) {
+            this.postings.set(field, new Map());
+            this.fieldLengths.set(field, new Map());
+            this.fieldTokenTotals.set(field, 0);
+        }
+    }
+    add(document) {
+        this.docCount += 1;
+        for (const field of FIELD_NAMES) {
+            const tokens = document.fields[field];
+            const postingsForField = this.postings.get(field);
+            const lengthsForField = this.fieldLengths.get(field);
+            if (!postingsForField || !lengthsForField) {
+                continue;
+            }
+            lengthsForField.set(document.id, tokens.length);
+            this.fieldTokenTotals.set(field, (this.fieldTokenTotals.get(field) ?? 0) + tokens.length);
+            const termFrequency = new Map();
+            for (const token of tokens) {
+                termFrequency.set(token, (termFrequency.get(token) ?? 0) + 1);
+            }
+            for (const [term, frequency] of termFrequency) {
+                const docMap = postingsForField.get(term);
+                if (docMap) {
+                    docMap.set(document.id, frequency);
+                }
+                else {
+                    postingsForField.set(term, new Map([[document.id, frequency]]));
+                }
+            }
+        }
+    }
+    finalize() {
+        for (const field of FIELD_NAMES) {
+            const total = this.fieldTokenTotals.get(field) ?? 0;
+            this.avgFieldLength.set(field, this.docCount > 0 ? total / this.docCount : 0);
+        }
+    }
+    search(queryTokens, topK, eligibleEntryIds) {
+        if (this.docCount === 0 || queryTokens.length === 0) {
+            return [];
+        }
+        const uniqueTerms = Array.from(new Set(queryTokens));
+        const totals = new Map();
+        const breakdowns = new Map();
+        for (const field of FIELD_NAMES) {
+            const weight = this.weights[field];
+            const avgdl = this.avgFieldLength.get(field) ?? 0;
+            const postingsForField = this.postings.get(field);
+            const lengthsForField = this.fieldLengths.get(field);
+            if (weight <= 0 || avgdl <= 0 || !postingsForField || !lengthsForField) {
+                continue;
+            }
+            for (const term of uniqueTerms) {
+                const docMap = postingsForField.get(term);
+                if (!docMap) {
+                    continue;
+                }
+                const documentFrequency = docMap.size;
+                const idf = Math.log(1 +
+                    (this.docCount - documentFrequency + 0.5) /
+                        (documentFrequency + 0.5));
+                for (const [docId, frequency] of docMap) {
+                    if (eligibleEntryIds && !eligibleEntryIds.has(docId)) {
+                        continue;
+                    }
+                    const length = lengthsForField.get(docId) ?? 0;
+                    const denominator = frequency + BM25_K1 * (1 - BM25_B + BM25_B * (length / avgdl));
+                    const contribution = ((idf * (frequency * (BM25_K1 + 1))) / denominator) * weight;
+                    totals.set(docId, (totals.get(docId) ?? 0) + contribution);
+                    const breakdown = breakdowns.get(docId) ?? {};
+                    breakdown[field] = (breakdown[field] ?? 0) + contribution;
+                    breakdowns.set(docId, breakdown);
+                }
+            }
+        }
+        const matches = [];
+        for (const [id, score] of totals) {
+            matches.push({ id, score, fieldScores: breakdowns.get(id) ?? {} });
+        }
+        matches.sort((left, right) => right.score - left.score || compareIds(left.id, right.id));
+        return matches.slice(0, topK);
+    }
+}
+/** Deterministic tiebreak so equal scores produce a stable order. */
+const compareIds = (left, right) => {
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+};
+const addToIndex = (index, key, id) => {
+    const bucket = index.get(key);
+    if (bucket) {
+        bucket.add(id);
+    }
+    else {
+        index.set(key, new Set([id]));
+    }
+};
+/**
+ * Build the internal search document from a normalized entry. `exactKeys`
+ * carry whole-phrase identifiers (entry id and title); each
+ * text field is tokenized for the field-aware scorer.
+ */
+export const buildDocument = (entry) => {
+    const exactKeys = normalizePhrases([entry.id, entry.title]);
+    return {
+        id: entry.id,
+        exactKeys,
+        fields: {
+            title: tokenize(entry.title),
+            aliases: entry.aliases.flatMap((alias) => tokenize(alias)),
+            keywords: entry.keywords.flatMap((keyword) => tokenize(keyword)),
+            summary: tokenize(entry.summary),
+            body: tokenize(entry.body),
+        },
+    };
+};
+/**
+ * Build the complete immutable snapshot: entry map, exact/alias/relation
+ * indexes, and the field-aware lexical index.
+ */
+export const buildIndexSnapshot = (entries, weights) => {
+    const entriesById = new Map();
+    const exactIndex = new Map();
+    const aliasIndex = new Map();
+    const relationIndex = new Map();
+    const lexical = new KnowledgeLexicalIndex(weights);
+    for (const entry of entries) {
+        entriesById.set(entry.id, entry);
+        const document = buildDocument(entry);
+        for (const key of document.exactKeys) {
+            addToIndex(exactIndex, key, entry.id);
+        }
+        for (const alias of entry.aliases) {
+            const key = normalizeText(alias);
+            if (key) {
+                addToIndex(aliasIndex, key, entry.id);
+            }
+        }
+        const relations = [...entry.relatedEntryIds];
+        if (entry.parentEntryId) {
+            relations.push(entry.parentEntryId);
+        }
+        if (relations.length > 0) {
+            relationIndex.set(entry.id, relations);
+        }
+        lexical.add(document);
+    }
+    lexical.finalize();
+    return {
+        entriesById,
+        exactIndex,
+        aliasIndex,
+        relationIndex,
+        lexical,
+        entryCount: entries.length,
+    };
+};