@tangle-network/agent-knowledge 20.0.1 → 22.0.0

package/dist/search/index.d.ts

@@ -0,0 +1,3 @@
+import { b as KnowledgeSearchResult, h as KnowledgePage } from "../types-BekdNwGD.js";
+import { d as KnowledgeLexicalIndexOptions, n as KnowledgeSearchHit, o as searchKnowledgePages, p as buildKnowledgeLexicalIndex, r as SearchKnowledgeOptions, t as KNOWLEDGE_SEARCH_RETRIEVER_ID, u as KnowledgeLexicalIndex } from "../search-Dde0PEtY.js";
+export { KNOWLEDGE_SEARCH_RETRIEVER_ID, type KnowledgeLexicalIndex, type KnowledgeLexicalIndexOptions, type KnowledgePage, type KnowledgeSearchHit, type KnowledgeSearchResult, type SearchKnowledgeOptions, buildKnowledgeLexicalIndex, searchKnowledgePages };

package/dist/search/index.js

@@ -0,0 +1,2 @@
+import { a as buildKnowledgeLexicalIndex, i as searchKnowledgePages, t as KNOWLEDGE_SEARCH_RETRIEVER_ID } from "../search-BBr5eUyT.js";
+export { KNOWLEDGE_SEARCH_RETRIEVER_ID, buildKnowledgeLexicalIndex, searchKnowledgePages };

package/dist/search-BBr5eUyT.js

@@ -0,0 +1,275 @@
+//#region src/lexical-postings.ts
+const DEFAULT_FIELD_BOOSTS = Object.freeze({
+	title: 3,
+	path: 2,
+	text: 1
+});
+function lexicalPageTerms(page, tokenize, fieldBoosts) {
+	const frequencies = /* @__PURE__ */ new Map();
+	let length = 0;
+	for (const [text, boost] of [
+		[page.title, fieldBoosts.title],
+		[page.path.replace(/\.md$/, ""), fieldBoosts.path],
+		[page.text, fieldBoosts.text]
+	]) {
+		if (boost === 0) continue;
+		for (const token of tokenize(text)) {
+			frequencies.set(token, (frequencies.get(token) ?? 0) + boost);
+			length += boost;
+		}
+	}
+	return {
+		frequencies,
+		length
+	};
+}
+/** Inverted index from per-page terms already computed with `tokenize` and `fieldBoosts`. */
+function assembleLexicalIndex(pages, terms, tokenize, fieldBoosts) {
+	const postings = /* @__PURE__ */ new Map();
+	const documentLengths = [];
+	let totalLength = 0;
+	terms.forEach(({ frequencies, length }, ordinal) => {
+		documentLengths.push(length);
+		totalLength += length;
+		for (const [term, tf] of frequencies) {
+			let list = postings.get(term);
+			if (!list) {
+				list = [];
+				postings.set(term, list);
+			}
+			list.push({
+				ordinal,
+				tf
+			});
+		}
+	});
+	return {
+		pages,
+		postings,
+		documentLengths,
+		averageDocumentLength: pages.length > 0 ? totalLength / pages.length : 0,
+		documentCount: pages.length,
+		tokenize,
+		fieldBoosts
+	};
+}
+//#endregion
+//#region src/lexical-index.ts
+const STOP_WORDS = /* @__PURE__ */ new Set([
+	"the",
+	"is",
+	"a",
+	"an",
+	"what",
+	"how",
+	"are",
+	"was",
+	"were",
+	"to",
+	"for",
+	"of",
+	"with",
+	"by",
+	"in",
+	"on",
+	"and"
+]);
+/**
+* The token stream of one text: lower-cased, split on whitespace and
+* punctuation, single characters and stop words removed, and a CJK run
+* expanded into its bigrams and characters. Repeats are kept so a term
+* frequency can be counted. Indexing and querying share this function, so the
+* two vocabularies cannot drift.
+*/
+function tokenizeText(text) {
+	const raw = text.toLowerCase().split(/[\s,，。！？、；：""''（）()\-_/\\·~～…]+/).filter((token) => token.length > 1 && !STOP_WORDS.has(token));
+	const tokens = [];
+	for (const token of raw) {
+		if (/[\u4e00-\u9fff\u3400-\u4dbf]/.test(token) && token.length > 2) {
+			const chars = [...token];
+			for (let i = 0; i < chars.length - 1; i++) tokens.push(chars[i] + chars[i + 1]);
+			tokens.push(...chars);
+		}
+		tokens.push(token);
+	}
+	return tokens;
+}
+/** The distinct query terms, in first-occurrence order. */
+function tokenizeQuery(query) {
+	return [...new Set(tokenizeText(query))];
+}
+function buildKnowledgeLexicalIndex(pages, options = {}) {
+	const tokenize = options.tokenize ?? tokenizeText;
+	const fieldBoosts = resolveFieldBoosts(options.fieldBoosts);
+	return assembleLexicalIndex(pages, pages.map((page) => lexicalPageTerms(page, tokenize, fieldBoosts)), tokenize, fieldBoosts);
+}
+/**
+* Okapi BM25 over the distinct query terms, with the Lucene inverse document
+* frequency `ln(1 + (N - df + 0.5) / (df + 0.5))`, which is positive for every
+* indexed term. Pages with no matching term are absent. The result is ordered
+* by score, then by path, so it does not depend on page order.
+*/
+function scoreBm25(index, tokens, options = {}) {
+	const k1 = options.k1 ?? 1.2;
+	const b = options.b ?? .75;
+	if (!Number.isFinite(k1) || k1 < 0) throw new Error(`bm25 k1 must be >= 0, got ${String(k1)}`);
+	if (!Number.isFinite(b) || b < 0 || b > 1) throw new Error(`bm25 b must lie in [0, 1], got ${String(b)}`);
+	const scores = /* @__PURE__ */ new Map();
+	const { documentCount, averageDocumentLength, documentLengths } = index;
+	for (const term of new Set(tokens)) {
+		const list = index.postings.get(term);
+		if (!list) continue;
+		const df = list.length;
+		const idf = Math.log(1 + (documentCount - df + .5) / (df + .5));
+		for (const { ordinal, tf } of list) {
+			const lengthRatio = averageDocumentLength > 0 ? documentLengths[ordinal] / averageDocumentLength : 1;
+			const saturated = tf * (k1 + 1) / (tf + k1 * (1 - b + b * lengthRatio));
+			scores.set(ordinal, (scores.get(ordinal) ?? 0) + idf * saturated);
+		}
+	}
+	return [...scores.entries()].map(([ordinal, score]) => ({
+		page: index.pages[ordinal],
+		score
+	})).sort((left, right) => right.score - left.score || left.page.path.localeCompare(right.page.path));
+}
+function resolveFieldBoosts(boosts) {
+	const resolved = {
+		...DEFAULT_FIELD_BOOSTS,
+		...boosts
+	};
+	for (const [field, boost] of Object.entries(resolved)) if (!Number.isFinite(boost) || boost < 0) throw new Error(`lexical field boost ${field} must be >= 0, got ${String(boost)}`);
+	return Object.freeze(resolved);
+}
+//#endregion
+//#region src/search.ts
+const RRF_K = 60;
+/**
+* Identity of the ranking `searchKnowledge` performs: BM25 over title, path,
+* and body, exact-title and phrase matches ahead of bag-of-words matches, and
+* reciprocal rank fusion with link and shared-source structure. Declare it as
+* the retriever id of a retrieval receipt minted from these results.
+*/
+const KNOWLEDGE_SEARCH_RETRIEVER_ID = "bm25-rrf-v1";
+function searchKnowledge(index, query, limitOrOptions = 10) {
+	return searchKnowledgePages(index.pages, query, limitOrOptions);
+}
+/**
+* Rank a page set that is not a built index, such as the chain a run can see.
+*
+* `searchKnowledge` is this function over `index.pages`, so both entry points
+* rank identically and neither can drift from the other.
+*/
+function searchKnowledgePages(pages, query, limitOrOptions = 10) {
+	const trimmed = query.trim();
+	if (trimmed === "") return [];
+	const options = typeof limitOrOptions === "number" ? { limit: limitOrOptions } : { ...limitOrOptions };
+	const limit = options.limit ?? 10;
+	if (!Number.isInteger(limit) || limit < 0) throw new Error(`search limit must be a non-negative integer, got ${String(limit)}`);
+	const matched = filterPages(pages, options);
+	const lexicalRanked = rankLexical(matched, trimmed, options.lexicalIndex ? assertLexicalIndexMatches(options.lexicalIndex, pages) : buildKnowledgeLexicalIndex(pages));
+	const ranked = [...fuseRanks([lexicalRanked, rankByGraph(matched, lexicalRanked, pages)]).entries()].map(([page, score]) => ({
+		page,
+		score
+	})).sort((a, b) => b.score - a.score || comparePages(a.page, b.page)).slice(0, limit);
+	const topScore = ranked[0]?.score ?? 0;
+	return ranked.map((item, i) => ({
+		citationId: item.page.id,
+		page: item.page,
+		score: item.score,
+		rrfScore: item.score,
+		normalizedScore: topScore > 0 ? item.score / topScore : 0,
+		rank: i + 1,
+		snippet: buildSnippet(item.page.text, trimmed),
+		reasons: reasonsFor(item.page, trimmed)
+	}));
+}
+function reciprocalRankFusion(rankLists, k = RRF_K) {
+	return fuseRanks(rankLists, k);
+}
+function fuseRanks(rankLists, k = RRF_K) {
+	const scores = /* @__PURE__ */ new Map();
+	for (const list of rankLists) list.forEach((id, idx) => {
+		scores.set(id, (scores.get(id) ?? 0) + 1 / (k + idx + 1));
+	});
+	return scores;
+}
+function filterPages(pages, options) {
+	const pageIds = options.pageIds ? new Set(options.pageIds) : null;
+	const tags = options.tags ? new Set(options.tags) : null;
+	const kinds = options.kinds ? new Set(options.kinds) : null;
+	return pages.filter((page) => {
+		if (options.excludeInvalidated && page.invalidation !== void 0) return false;
+		if (pageIds && !pageIds.has(page.id)) return false;
+		if (tags && !page.tags.some((tag) => tags.has(tag))) return false;
+		if (kinds) {
+			const kind = page.frontmatter.kind;
+			if (typeof kind !== "string" || !kinds.has(kind)) return false;
+		}
+		return options.predicate?.(page) ?? true;
+	});
+}
+function assertLexicalIndexMatches(lexicalIndex, pages) {
+	if (lexicalIndex.pages.length !== pages.length || lexicalIndex.pages.some((page, ordinal) => page !== pages[ordinal])) throw new Error("lexical index was not built from the searched pages");
+	return lexicalIndex;
+}
+/**
+* The lexical rank list. An exact title or path match outranks a title that
+* contains the query, which outranks a body that contains the query, which
+* outranks a bag-of-words match; BM25 orders pages inside each of those tiers.
+* The tiers are an ordering, not a score, so a strong bag-of-words page cannot
+* overtake an exact match by term repetition alone.
+*/
+function rankLexical(pages, query, lexicalIndex) {
+	const tokens = [...new Set(lexicalIndex.tokenize(query))];
+	const bm25 = new Map(scoreBm25(lexicalIndex, tokens).map((hit) => [hit.page, hit.score]));
+	const phrase = query.toLowerCase();
+	return pages.flatMap((page) => {
+		const score = bm25.get(page) ?? 0;
+		if (score === 0 && tokens.length > 0) return [];
+		const tier = phraseTier(page, phrase);
+		if (score === 0 && tier === 0) return [];
+		return [{
+			page,
+			tier,
+			score
+		}];
+	}).sort((a, b) => b.tier - a.tier || b.score - a.score || comparePages(a.page, b.page)).map((item) => item.page);
+}
+function phraseTier(page, phrase) {
+	const title = page.title.toLowerCase();
+	if (title === phrase || page.path.toLowerCase().endsWith(`${phrase}.md`)) return 3;
+	if (title.includes(phrase)) return 2;
+	if (page.text.toLowerCase().includes(phrase)) return 1;
+	return 0;
+}
+function rankByGraph(pages, lexicalRanked, visiblePages) {
+	if (lexicalRanked.length === 0) return [];
+	const counts = /* @__PURE__ */ new Map();
+	for (const page of visiblePages) counts.set(page.id, (counts.get(page.id) ?? 0) + 1);
+	const seeds = new Set(lexicalRanked.slice(0, 5).filter((page) => counts.get(page.id) === 1).map((page) => page.id));
+	return pages.map((page) => ({
+		page,
+		score: page.outLinks.filter((link) => seeds.has(link)).length + page.sourceIds.filter((source) => lexicalRanked.some((seed) => seed.sourceIds.includes(source))).length
+	})).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || comparePages(a.page, b.page)).map((item) => item.page);
+}
+function comparePages(a, b) {
+	return a.path.localeCompare(b.path) || a.id.localeCompare(b.id);
+}
+function buildSnippet(text, query) {
+	const compact = text.replace(/\s+/g, " ").trim();
+	const idx = compact.toLowerCase().indexOf(query.toLowerCase());
+	if (idx < 0) return compact.slice(0, 180);
+	return compact.slice(Math.max(0, idx - 80), Math.min(compact.length, idx + query.length + 100));
+}
+function reasonsFor(page, query) {
+	const lower = `${page.title}\n${page.text}`.toLowerCase();
+	const reasons = [];
+	if (lower.includes(query.toLowerCase())) reasons.push("phrase");
+	if (page.sourceIds.length > 0) reasons.push("sourced");
+	if (page.outLinks.length > 0) reasons.push("linked");
+	return reasons;
+}
+//#endregion
+export { buildKnowledgeLexicalIndex as a, tokenizeText as c, lexicalPageTerms as d, searchKnowledgePages as i, DEFAULT_FIELD_BOOSTS as l, reciprocalRankFusion as n, scoreBm25 as o, searchKnowledge as r, tokenizeQuery as s, KNOWLEDGE_SEARCH_RETRIEVER_ID as t, assembleLexicalIndex as u };
+
+//# sourceMappingURL=search-BBr5eUyT.js.map

package/dist/search-BBr5eUyT.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-BBr5eUyT.js","names":[],"sources":["../src/lexical-postings.ts","../src/lexical-index.ts","../src/search.ts"],"sourcesContent":["import type {\n  KnowledgeLexicalFieldBoosts,\n  KnowledgeLexicalIndex,\n  KnowledgeLexicalPosting,\n} from './lexical-index'\nimport type { KnowledgePage } from './types'\n\nexport const DEFAULT_FIELD_BOOSTS: Readonly<Required<KnowledgeLexicalFieldBoosts>> = Object.freeze({\n  title: 3,\n  path: 2,\n  text: 1,\n})\n\n/** Field-boosted term frequencies and length of one page. */\nexport interface LexicalPageTerms {\n  readonly frequencies: ReadonlyMap<string, number>\n  readonly length: number\n}\n\nexport function lexicalPageTerms(\n  page: KnowledgePage,\n  tokenize: (text: string) => string[],\n  fieldBoosts: Readonly<Required<KnowledgeLexicalFieldBoosts>>,\n): LexicalPageTerms {\n  const frequencies = new Map<string, number>()\n  let length = 0\n  for (const [text, boost] of [\n    [page.title, fieldBoosts.title],\n    [page.path.replace(/\\.md$/, ''), fieldBoosts.path],\n    [page.text, fieldBoosts.text],\n  ] as const) {\n    if (boost === 0) continue\n    for (const token of tokenize(text)) {\n      frequencies.set(token, (frequencies.get(token) ?? 0) + boost)\n      length += boost\n    }\n  }\n  return { frequencies, length }\n}\n\n/** Inverted index from per-page terms already computed with `tokenize` and `fieldBoosts`. */\nexport function assembleLexicalIndex(\n  pages: readonly KnowledgePage[],\n  terms: readonly LexicalPageTerms[],\n  tokenize: (text: string) => string[],\n  fieldBoosts: Readonly<Required<KnowledgeLexicalFieldBoosts>>,\n): KnowledgeLexicalIndex {\n  const postings = new Map<string, KnowledgeLexicalPosting[]>()\n  const documentLengths: number[] = []\n  let totalLength = 0\n  terms.forEach(({ frequencies, length }, ordinal) => {\n    documentLengths.push(length)\n    totalLength += length\n    for (const [term, tf] of frequencies) {\n      let list = postings.get(term)\n      if (!list) {\n        list = []\n        postings.set(term, list)\n      }\n      list.push({ ordinal, tf })\n    }\n  })\n  return {\n    pages,\n    postings,\n    documentLengths,\n    averageDocumentLength: pages.length > 0 ? totalLength / pages.length : 0,\n    documentCount: pages.length,\n    tokenize,\n    fieldBoosts,\n  }\n}\n","import { assembleLexicalIndex, DEFAULT_FIELD_BOOSTS, lexicalPageTerms } from './lexical-postings'\nimport type { KnowledgePage } from './types'\n\nconst STOP_WORDS = new Set([\n  'the',\n  'is',\n  'a',\n  'an',\n  'what',\n  'how',\n  'are',\n  'was',\n  'were',\n  'to',\n  'for',\n  'of',\n  'with',\n  'by',\n  'in',\n  'on',\n  'and',\n])\n\n/**\n * The token stream of one text: lower-cased, split on whitespace and\n * punctuation, single characters and stop words removed, and a CJK run\n * expanded into its bigrams and characters. Repeats are kept so a term\n * frequency can be counted. Indexing and querying share this function, so the\n * two vocabularies cannot drift.\n */\nexport function tokenizeText(text: string): string[] {\n  const raw = text\n    .toLowerCase()\n    .split(/[\\s,，。！？、；：\"\"''（）()\\-_/\\\\·~～…]+/)\n    .filter((token) => token.length > 1 && !STOP_WORDS.has(token))\n  const tokens: string[] = []\n  for (const token of raw) {\n    if (/[\\u4e00-\\u9fff\\u3400-\\u4dbf]/.test(token) && token.length > 2) {\n      const chars = [...token]\n      for (let i = 0; i < chars.length - 1; i++) tokens.push(chars[i]! + chars[i + 1]!)\n      tokens.push(...chars)\n    }\n    tokens.push(token)\n  }\n  return tokens\n}\n\n/** The distinct query terms, in first-occurrence order. */\nexport function tokenizeQuery(query: string): string[] {\n  return [...new Set(tokenizeText(query))]\n}\n\nexport interface KnowledgeLexicalFieldBoosts {\n  /** Multiplier for a term occurrence in the page title. Defaults to 3. */\n  title?: number\n  /** Multiplier for a term occurrence in the page path without its extension. Defaults to 2. */\n  path?: number\n  /** Multiplier for a term occurrence in the page body. Defaults to 1. */\n  text?: number\n}\n\nexport interface KnowledgeLexicalIndexOptions {\n  /** Token stream of one text. Defaults to `tokenizeText`. */\n  tokenize?: (text: string) => string[]\n  fieldBoosts?: KnowledgeLexicalFieldBoosts\n}\n\nexport interface KnowledgeLexicalPosting {\n  /** Position of the page in `KnowledgeLexicalIndex.pages`. */\n  ordinal: number\n  /** Field-boosted term frequency in that page. */\n  tf: number\n}\n\n/**\n * Inverted index over a fixed page list.\n *\n * Ordinals are positions in `pages`. `documentLengths` are field-boosted token\n * counts, so length normalization and term frequency use one scale.\n */\nexport interface KnowledgeLexicalIndex {\n  readonly pages: readonly KnowledgePage[]\n  readonly postings: ReadonlyMap<string, readonly KnowledgeLexicalPosting[]>\n  readonly documentLengths: readonly number[]\n  readonly averageDocumentLength: number\n  readonly documentCount: number\n  readonly tokenize: (text: string) => string[]\n  readonly fieldBoosts: Readonly<Required<KnowledgeLexicalFieldBoosts>>\n}\n\nexport interface Bm25Options {\n  /** Term-frequency saturation. Defaults to 1.2. */\n  k1?: number\n  /** Length-normalization strength in [0, 1]. Defaults to 0.75. */\n  b?: number\n}\n\nexport interface Bm25Hit {\n  page: KnowledgePage\n  score: number\n}\n\nexport function buildKnowledgeLexicalIndex(\n  pages: readonly KnowledgePage[],\n  options: KnowledgeLexicalIndexOptions = {},\n): KnowledgeLexicalIndex {\n  const tokenize = options.tokenize ?? tokenizeText\n  const fieldBoosts = resolveFieldBoosts(options.fieldBoosts)\n  return assembleLexicalIndex(\n    pages,\n    pages.map((page) => lexicalPageTerms(page, tokenize, fieldBoosts)),\n    tokenize,\n    fieldBoosts,\n  )\n}\n\n/**\n * Okapi BM25 over the distinct query terms, with the Lucene inverse document\n * frequency `ln(1 + (N - df + 0.5) / (df + 0.5))`, which is positive for every\n * indexed term. Pages with no matching term are absent. The result is ordered\n * by score, then by path, so it does not depend on page order.\n */\nexport function scoreBm25(\n  index: KnowledgeLexicalIndex,\n  tokens: readonly string[],\n  options: Bm25Options = {},\n): Bm25Hit[] {\n  const k1 = options.k1 ?? 1.2\n  const b = options.b ?? 0.75\n  if (!Number.isFinite(k1) || k1 < 0) throw new Error(`bm25 k1 must be >= 0, got ${String(k1)}`)\n  if (!Number.isFinite(b) || b < 0 || b > 1) {\n    throw new Error(`bm25 b must lie in [0, 1], got ${String(b)}`)\n  }\n  const scores = new Map<number, number>()\n  const { documentCount, averageDocumentLength, documentLengths } = index\n  for (const term of new Set(tokens)) {\n    const list = index.postings.get(term)\n    if (!list) continue\n    const df = list.length\n    const idf = Math.log(1 + (documentCount - df + 0.5) / (df + 0.5))\n    for (const { ordinal, tf } of list) {\n      const lengthRatio =\n        averageDocumentLength > 0 ? documentLengths[ordinal]! / averageDocumentLength : 1\n      const saturated = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * lengthRatio))\n      scores.set(ordinal, (scores.get(ordinal) ?? 0) + idf * saturated)\n    }\n  }\n  return [...scores.entries()]\n    .map(([ordinal, score]) => ({ page: index.pages[ordinal]!, score }))\n    .sort(\n      (left, right) => right.score - left.score || left.page.path.localeCompare(right.page.path),\n    )\n}\n\nfunction resolveFieldBoosts(\n  boosts: KnowledgeLexicalFieldBoosts | undefined,\n): Readonly<Required<KnowledgeLexicalFieldBoosts>> {\n  const resolved = { ...DEFAULT_FIELD_BOOSTS, ...boosts }\n  for (const [field, boost] of Object.entries(resolved)) {\n    if (!Number.isFinite(boost) || boost < 0) {\n      throw new Error(`lexical field boost ${field} must be >= 0, got ${String(boost)}`)\n    }\n  }\n  return Object.freeze(resolved)\n}\n","import { buildKnowledgeLexicalIndex, type KnowledgeLexicalIndex, scoreBm25 } from './lexical-index'\nimport type { KnowledgeId, KnowledgeIndex, KnowledgePage, KnowledgeSearchResult } from './types'\n\nconst RRF_K = 60\n\n/**\n * Identity of the ranking `searchKnowledge` performs: BM25 over title, path,\n * and body, exact-title and phrase matches ahead of bag-of-words matches, and\n * reciprocal rank fusion with link and shared-source structure. Declare it as\n * the retriever id of a retrieval receipt minted from these results.\n */\nexport const KNOWLEDGE_SEARCH_RETRIEVER_ID = 'bm25-rrf-v1'\n\nexport interface SearchKnowledgeOptions {\n  /** Maximum results returned. Defaults to 10. */\n  limit?: number\n  /** Match pages whose stable id is one of these values. */\n  pageIds?: readonly KnowledgeId[]\n  /** Match pages carrying at least one of these tags. */\n  tags?: readonly string[]\n  /** Match the exact string stored in `frontmatter.kind`. */\n  kinds?: readonly string[]\n  /**\n   * Drop pages whose own evidence refuted them. Defaults to false: a caller\n   * that reads history needs them, and a silent change of what search returns\n   * is worse than an explicit option.\n   */\n  excludeInvalidated?: boolean\n  /** Additional caller-owned filter, applied before either ranking stage. */\n  predicate?: (page: KnowledgePage) => boolean\n  /**\n   * A lexical index built from exactly the searched pages, supplied by a caller\n   * that searches one page set repeatedly. When absent, one is built for this\n   * call.\n   */\n  lexicalIndex?: KnowledgeLexicalIndex\n}\n\n/**\n * A retrieval result with an explicit citation handle.\n *\n * Unscoped search returns `page.id`; a run-scoped brief qualifies ambiguous ids\n * through the citation resolver. Later writes should persist the returned value. Keeping it at the result's top level prevents tool\n * renderers from accidentally hiding the only stable handle a model can copy.\n */\nexport interface KnowledgeSearchHit extends KnowledgeSearchResult {\n  citationId: KnowledgeId\n}\n\nexport function searchKnowledge(\n  index: KnowledgeIndex,\n  query: string,\n  limit?: number,\n): KnowledgeSearchHit[]\nexport function searchKnowledge(\n  index: KnowledgeIndex,\n  query: string,\n  options?: SearchKnowledgeOptions,\n): KnowledgeSearchHit[]\nexport function searchKnowledge(\n  index: KnowledgeIndex,\n  query: string,\n  limitOrOptions: number | SearchKnowledgeOptions = 10,\n): KnowledgeSearchHit[] {\n  return searchKnowledgePages(index.pages, query, limitOrOptions)\n}\n\n/**\n * Rank a page set that is not a built index, such as the chain a run can see.\n *\n * `searchKnowledge` is this function over `index.pages`, so both entry points\n * rank identically and neither can drift from the other.\n */\nexport function searchKnowledgePages(\n  pages: readonly KnowledgePage[],\n  query: string,\n  limitOrOptions: number | SearchKnowledgeOptions = 10,\n): KnowledgeSearchHit[] {\n  const trimmed = query.trim()\n  if (trimmed === '') return []\n  const options =\n    typeof limitOrOptions === 'number' ? { limit: limitOrOptions } : { ...limitOrOptions }\n  const limit = options.limit ?? 10\n  if (!Number.isInteger(limit) || limit < 0) {\n    throw new Error(`search limit must be a non-negative integer, got ${String(limit)}`)\n  }\n\n  const matched = filterPages(pages, options)\n  const lexicalIndex = options.lexicalIndex\n    ? assertLexicalIndexMatches(options.lexicalIndex, pages)\n    : buildKnowledgeLexicalIndex(pages)\n  const lexicalRanked = rankLexical(matched, trimmed, lexicalIndex)\n  const graphRanked = rankByGraph(matched, lexicalRanked, pages)\n  // Stable ids are citation addresses, not unique document identities across stores.\n  // Fuse the same page objects used by BM25, then return those exact pages.\n  const scores = fuseRanks([lexicalRanked, graphRanked])\n\n  const ranked = [...scores.entries()]\n    .map(([page, score]) => ({ page, score }))\n    .sort((a, b) => b.score - a.score || comparePages(a.page, b.page))\n    .slice(0, limit)\n\n  // Normalize against the top hit so callers can compare against natural\n  // [0, 1] thresholds. Raw RRF values are typically ~0.016, which reads as\n  // \"no relevance\" to humans even when the result is the best available.\n  // The top hit becomes 1 by definition; lower-ranked hits scale linearly.\n  const topScore = ranked[0]?.score ?? 0\n\n  return ranked.map((item, i) => ({\n    citationId: item.page.id,\n    page: item.page,\n    score: item.score,\n    rrfScore: item.score,\n    normalizedScore: topScore > 0 ? item.score / topScore : 0,\n    rank: i + 1,\n    snippet: buildSnippet(item.page.text, trimmed),\n    reasons: reasonsFor(item.page, trimmed),\n  }))\n}\n\nexport function reciprocalRankFusion(rankLists: string[][], k = RRF_K): Map<string, number> {\n  return fuseRanks(rankLists, k)\n}\n\n// The public string-key helper and document retrieval share one ranking implementation.\nfunction fuseRanks<T>(rankLists: readonly (readonly T[])[], k = RRF_K): Map<T, number> {\n  const scores = new Map<T, number>()\n  for (const list of rankLists) {\n    list.forEach((id, idx) => {\n      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + idx + 1))\n    })\n  }\n  return scores\n}\n\nfunction filterPages(\n  pages: readonly KnowledgePage[],\n  options: SearchKnowledgeOptions,\n): KnowledgePage[] {\n  const pageIds = options.pageIds ? new Set(options.pageIds) : null\n  const tags = options.tags ? new Set(options.tags) : null\n  const kinds = options.kinds ? new Set(options.kinds) : null\n\n  return pages.filter((page) => {\n    if (options.excludeInvalidated && page.invalidation !== undefined) return false\n    if (pageIds && !pageIds.has(page.id)) return false\n    if (tags && !page.tags.some((tag) => tags.has(tag))) return false\n    if (kinds) {\n      const kind = page.frontmatter.kind\n      if (typeof kind !== 'string' || !kinds.has(kind)) return false\n    }\n    return options.predicate?.(page) ?? true\n  })\n}\n\nfunction assertLexicalIndexMatches(\n  lexicalIndex: KnowledgeLexicalIndex,\n  pages: readonly KnowledgePage[],\n): KnowledgeLexicalIndex {\n  if (\n    lexicalIndex.pages.length !== pages.length ||\n    lexicalIndex.pages.some((page, ordinal) => page !== pages[ordinal])\n  ) {\n    throw new Error('lexical index was not built from the searched pages')\n  }\n  return lexicalIndex\n}\n\n/**\n * The lexical rank list. An exact title or path match outranks a title that\n * contains the query, which outranks a body that contains the query, which\n * outranks a bag-of-words match; BM25 orders pages inside each of those tiers.\n * The tiers are an ordering, not a score, so a strong bag-of-words page cannot\n * overtake an exact match by term repetition alone.\n */\nfunction rankLexical(\n  pages: KnowledgePage[],\n  query: string,\n  lexicalIndex: KnowledgeLexicalIndex,\n): KnowledgePage[] {\n  const tokens = [...new Set(lexicalIndex.tokenize(query))]\n  const bm25 = new Map(scoreBm25(lexicalIndex, tokens).map((hit) => [hit.page, hit.score]))\n  const phrase = query.toLowerCase()\n  return pages\n    .flatMap((page) => {\n      const score = bm25.get(page) ?? 0\n      // A query that tokenizes to nothing (stop words, single characters) can\n      // still match as a phrase; otherwise only pages with a scored term are\n      // candidates, and every phrase match is one of them.\n      if (score === 0 && tokens.length > 0) return []\n      const tier = phraseTier(page, phrase)\n      if (score === 0 && tier === 0) return []\n      return [{ page, tier, score }]\n    })\n    .sort((a, b) => b.tier - a.tier || b.score - a.score || comparePages(a.page, b.page))\n    .map((item) => item.page)\n}\n\nfunction phraseTier(page: KnowledgePage, phrase: string): number {\n  const title = page.title.toLowerCase()\n  if (title === phrase || page.path.toLowerCase().endsWith(`${phrase}.md`)) return 3\n  if (title.includes(phrase)) return 2\n  if (page.text.toLowerCase().includes(phrase)) return 1\n  return 0\n}\n\nfunction rankByGraph(\n  pages: KnowledgePage[],\n  lexicalRanked: KnowledgePage[],\n  visiblePages: readonly KnowledgePage[],\n): KnowledgePage[] {\n  if (lexicalRanked.length === 0) return []\n  // A bare link to a duplicate id has no unambiguous target. Scoped callers\n  // qualify links before ranking; unscoped callers must not invent that edge.\n  const counts = new Map<string, number>()\n  for (const page of visiblePages) counts.set(page.id, (counts.get(page.id) ?? 0) + 1)\n  const seeds = new Set(\n    lexicalRanked\n      .slice(0, 5)\n      .filter((page) => counts.get(page.id) === 1)\n      .map((page) => page.id),\n  )\n  return pages\n    .map((page) => ({\n      page,\n      score:\n        page.outLinks.filter((link) => seeds.has(link)).length +\n        page.sourceIds.filter((source) =>\n          lexicalRanked.some((seed) => seed.sourceIds.includes(source)),\n        ).length,\n    }))\n    .filter((item) => item.score > 0)\n    .sort((a, b) => b.score - a.score || comparePages(a.page, b.page))\n    .map((item) => item.page)\n}\n\nfunction comparePages(a: KnowledgePage, b: KnowledgePage): number {\n  return a.path.localeCompare(b.path) || a.id.localeCompare(b.id)\n}\n\nfunction buildSnippet(text: string, query: string): string {\n  const compact = text.replace(/\\s+/g, ' ').trim()\n  const idx = compact.toLowerCase().indexOf(query.toLowerCase())\n  if (idx < 0) return compact.slice(0, 180)\n  return compact.slice(Math.max(0, idx - 80), Math.min(compact.length, idx + query.length + 100))\n}\n\nfunction reasonsFor(page: KnowledgePage, query: string): string[] {\n  const lower = `${page.title}\\n${page.text}`.toLowerCase()\n  const reasons: string[] = []\n  if (lower.includes(query.toLowerCase())) reasons.push('phrase')\n  if (page.sourceIds.length > 0) reasons.push('sourced')\n  if (page.outLinks.length > 0) reasons.push('linked')\n  return reasons\n}\n"],"mappings":";AAOA,MAAa,uBAAwE,OAAO,OAAO;CACjG,OAAO;CACP,MAAM;CACN,MAAM;AACR,CAAC;AAQD,SAAgB,iBACd,MACA,UACA,aACkB;CAClB,MAAM,8BAAc,IAAI,IAAoB;CAC5C,IAAI,SAAS;CACb,KAAK,MAAM,CAAC,MAAM,UAAU;EAC1B,CAAC,KAAK,OAAO,YAAY,KAAK;EAC9B,CAAC,KAAK,KAAK,QAAQ,SAAS,EAAE,GAAG,YAAY,IAAI;EACjD,CAAC,KAAK,MAAM,YAAY,IAAI;CAC9B,GAAY;EACV,IAAI,UAAU,GAAG;EACjB,KAAK,MAAM,SAAS,SAAS,IAAI,GAAG;GAClC,YAAY,IAAI,QAAQ,YAAY,IAAI,KAAK,KAAK,KAAK,KAAK;GAC5D,UAAU;EACZ;CACF;CACA,OAAO;EAAE;EAAa;CAAO;AAC/B;;AAGA,SAAgB,qBACd,OACA,OACA,UACA,aACuB;CACvB,MAAM,2BAAW,IAAI,IAAuC;CAC5D,MAAM,kBAA4B,CAAC;CACnC,IAAI,cAAc;CAClB,MAAM,SAAS,EAAE,aAAa,UAAU,YAAY;EAClD,gBAAgB,KAAK,MAAM;EAC3B,eAAe;EACf,KAAK,MAAM,CAAC,MAAM,OAAO,aAAa;GACpC,IAAI,OAAO,SAAS,IAAI,IAAI;GAC5B,IAAI,CAAC,MAAM;IACT,OAAO,CAAC;IACR,SAAS,IAAI,MAAM,IAAI;GACzB;GACA,KAAK,KAAK;IAAE;IAAS;GAAG,CAAC;EAC3B;CACF,CAAC;CACD,OAAO;EACL;EACA;EACA;EACA,uBAAuB,MAAM,SAAS,IAAI,cAAc,MAAM,SAAS;EACvE,eAAe,MAAM;EACrB;EACA;CACF;AACF;;;ACpEA,MAAM,6BAAa,IAAI,IAAI;CACzB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;;AASD,SAAgB,aAAa,MAAwB;CACnD,MAAM,MAAM,KACT,YAAY,CAAC,CACb,MAAM,iCAAiC,CAAC,CACxC,QAAQ,UAAU,MAAM,SAAS,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC;CAC/D,MAAM,SAAmB,CAAC;CAC1B,KAAK,MAAM,SAAS,KAAK;EACvB,IAAI,+BAA+B,KAAK,KAAK,KAAK,MAAM,SAAS,GAAG;GAClE,MAAM,QAAQ,CAAC,GAAG,KAAK;GACvB,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,SAAS,GAAG,KAAK,OAAO,KAAK,MAAM,KAAM,MAAM,IAAI,EAAG;GAChF,OAAO,KAAK,GAAG,KAAK;EACtB;EACA,OAAO,KAAK,KAAK;CACnB;CACA,OAAO;AACT;;AAGA,SAAgB,cAAc,OAAyB;CACrD,OAAO,CAAC,GAAG,IAAI,IAAI,aAAa,KAAK,CAAC,CAAC;AACzC;AAoDA,SAAgB,2BACd,OACA,UAAwC,CAAC,GAClB;CACvB,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,cAAc,mBAAmB,QAAQ,WAAW;CAC1D,OAAO,qBACL,OACA,MAAM,KAAK,SAAS,iBAAiB,MAAM,UAAU,WAAW,CAAC,GACjE,UACA,WACF;AACF;;;;;;;AAQA,SAAgB,UACd,OACA,QACA,UAAuB,CAAC,GACb;CACX,MAAM,KAAK,QAAQ,MAAM;CACzB,MAAM,IAAI,QAAQ,KAAK;CACvB,IAAI,CAAC,OAAO,SAAS,EAAE,KAAK,KAAK,GAAG,MAAM,IAAI,MAAM,6BAA6B,OAAO,EAAE,GAAG;CAC7F,IAAI,CAAC,OAAO,SAAS,CAAC,KAAK,IAAI,KAAK,IAAI,GACtC,MAAM,IAAI,MAAM,kCAAkC,OAAO,CAAC,GAAG;CAE/D,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,EAAE,eAAe,uBAAuB,oBAAoB;CAClE,KAAK,MAAM,QAAQ,IAAI,IAAI,MAAM,GAAG;EAClC,MAAM,OAAO,MAAM,SAAS,IAAI,IAAI;EACpC,IAAI,CAAC,MAAM;EACX,MAAM,KAAK,KAAK;EAChB,MAAM,MAAM,KAAK,IAAI,KAAK,gBAAgB,KAAK,OAAQ,KAAK,GAAI;EAChE,KAAK,MAAM,EAAE,SAAS,QAAQ,MAAM;GAClC,MAAM,cACJ,wBAAwB,IAAI,gBAAgB,WAAY,wBAAwB;GAClF,MAAM,YAAa,MAAM,KAAK,MAAO,KAAK,MAAM,IAAI,IAAI,IAAI;GAC5D,OAAO,IAAI,UAAU,OAAO,IAAI,OAAO,KAAK,KAAK,MAAM,SAAS;EAClE;CACF;CACA,OAAO,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC,CACzB,KAAK,CAAC,SAAS,YAAY;EAAE,MAAM,MAAM,MAAM;EAAW;CAAM,EAAE,CAAC,CACnE,MACE,MAAM,UAAU,MAAM,QAAQ,KAAK,SAAS,KAAK,KAAK,KAAK,cAAc,MAAM,KAAK,IAAI,CAC3F;AACJ;AAEA,SAAS,mBACP,QACiD;CACjD,MAAM,WAAW;EAAE,GAAG;EAAsB,GAAG;CAAO;CACtD,KAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,QAAQ,GAClD,IAAI,CAAC,OAAO,SAAS,KAAK,KAAK,QAAQ,GACrC,MAAM,IAAI,MAAM,uBAAuB,MAAM,qBAAqB,OAAO,KAAK,GAAG;CAGrF,OAAO,OAAO,OAAO,QAAQ;AAC/B;;;ACjKA,MAAM,QAAQ;;;;;;;AAQd,MAAa,gCAAgC;AAgD7C,SAAgB,gBACd,OACA,OACA,iBAAkD,IAC5B;CACtB,OAAO,qBAAqB,MAAM,OAAO,OAAO,cAAc;AAChE;;;;;;;AAQA,SAAgB,qBACd,OACA,OACA,iBAAkD,IAC5B;CACtB,MAAM,UAAU,MAAM,KAAK;CAC3B,IAAI,YAAY,IAAI,OAAO,CAAC;CAC5B,MAAM,UACJ,OAAO,mBAAmB,WAAW,EAAE,OAAO,eAAe,IAAI,EAAE,GAAG,eAAe;CACvF,MAAM,QAAQ,QAAQ,SAAS;CAC/B,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,GACtC,MAAM,IAAI,MAAM,oDAAoD,OAAO,KAAK,GAAG;CAGrF,MAAM,UAAU,YAAY,OAAO,OAAO;CAI1C,MAAM,gBAAgB,YAAY,SAAS,SAHtB,QAAQ,eACzB,0BAA0B,QAAQ,cAAc,KAAK,IACrD,2BAA2B,KAAK,CAC4B;CAMhE,MAAM,SAAS,CAAC,GAFD,UAAU,CAAC,eAHN,YAAY,SAAS,eAAe,KAGL,CAAC,CAE5B,CAAC,CAAC,QAAQ,CAAC,CAAC,CACjC,KAAK,CAAC,MAAM,YAAY;EAAE;EAAM;CAAM,EAAE,CAAC,CACzC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CACjE,MAAM,GAAG,KAAK;CAMjB,MAAM,WAAW,OAAO,EAAE,EAAE,SAAS;CAErC,OAAO,OAAO,KAAK,MAAM,OAAO;EAC9B,YAAY,KAAK,KAAK;EACtB,MAAM,KAAK;EACX,OAAO,KAAK;EACZ,UAAU,KAAK;EACf,iBAAiB,WAAW,IAAI,KAAK,QAAQ,WAAW;EACxD,MAAM,IAAI;EACV,SAAS,aAAa,KAAK,KAAK,MAAM,OAAO;EAC7C,SAAS,WAAW,KAAK,MAAM,OAAO;CACxC,EAAE;AACJ;AAEA,SAAgB,qBAAqB,WAAuB,IAAI,OAA4B;CAC1F,OAAO,UAAU,WAAW,CAAC;AAC/B;AAGA,SAAS,UAAa,WAAsC,IAAI,OAAuB;CACrF,MAAM,yBAAS,IAAI,IAAe;CAClC,KAAK,MAAM,QAAQ,WACjB,KAAK,SAAS,IAAI,QAAQ;EACxB,OAAO,IAAI,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,KAAK,IAAI,MAAM,EAAE;CAC1D,CAAC;CAEH,OAAO;AACT;AAEA,SAAS,YACP,OACA,SACiB;CACjB,MAAM,UAAU,QAAQ,UAAU,IAAI,IAAI,QAAQ,OAAO,IAAI;CAC7D,MAAM,OAAO,QAAQ,OAAO,IAAI,IAAI,QAAQ,IAAI,IAAI;CACpD,MAAM,QAAQ,QAAQ,QAAQ,IAAI,IAAI,QAAQ,KAAK,IAAI;CAEvD,OAAO,MAAM,QAAQ,SAAS;EAC5B,IAAI,QAAQ,sBAAsB,KAAK,iBAAiB,KAAA,GAAW,OAAO;EAC1E,IAAI,WAAW,CAAC,QAAQ,IAAI,KAAK,EAAE,GAAG,OAAO;EAC7C,IAAI,QAAQ,CAAC,KAAK,KAAK,MAAM,QAAQ,KAAK,IAAI,GAAG,CAAC,GAAG,OAAO;EAC5D,IAAI,OAAO;GACT,MAAM,OAAO,KAAK,YAAY;GAC9B,IAAI,OAAO,SAAS,YAAY,CAAC,MAAM,IAAI,IAAI,GAAG,OAAO;EAC3D;EACA,OAAO,QAAQ,YAAY,IAAI,KAAK;CACtC,CAAC;AACH;AAEA,SAAS,0BACP,cACA,OACuB;CACvB,IACE,aAAa,MAAM,WAAW,MAAM,UACpC,aAAa,MAAM,MAAM,MAAM,YAAY,SAAS,MAAM,QAAQ,GAElE,MAAM,IAAI,MAAM,qDAAqD;CAEvE,OAAO;AACT;;;;;;;;AASA,SAAS,YACP,OACA,OACA,cACiB;CACjB,MAAM,SAAS,CAAC,GAAG,IAAI,IAAI,aAAa,SAAS,KAAK,CAAC,CAAC;CACxD,MAAM,OAAO,IAAI,IAAI,UAAU,cAAc,MAAM,CAAC,CAAC,KAAK,QAAQ,CAAC,IAAI,MAAM,IAAI,KAAK,CAAC,CAAC;CACxF,MAAM,SAAS,MAAM,YAAY;CACjC,OAAO,MACJ,SAAS,SAAS;EACjB,MAAM,QAAQ,KAAK,IAAI,IAAI,KAAK;EAIhC,IAAI,UAAU,KAAK,OAAO,SAAS,GAAG,OAAO,CAAC;EAC9C,MAAM,OAAO,WAAW,MAAM,MAAM;EACpC,IAAI,UAAU,KAAK,SAAS,GAAG,OAAO,CAAC;EACvC,OAAO,CAAC;GAAE;GAAM;GAAM;EAAM,CAAC;CAC/B,CAAC,CAAC,CACD,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CACpF,KAAK,SAAS,KAAK,IAAI;AAC5B;AAEA,SAAS,WAAW,MAAqB,QAAwB;CAC/D,MAAM,QAAQ,KAAK,MAAM,YAAY;CACrC,IAAI,UAAU,UAAU,KAAK,KAAK,YAAY,CAAC,CAAC,SAAS,GAAG,OAAO,IAAI,GAAG,OAAO;CACjF,IAAI,MAAM,SAAS,MAAM,GAAG,OAAO;CACnC,IAAI,KAAK,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,OAAO;CACrD,OAAO;AACT;AAEA,SAAS,YACP,OACA,eACA,cACiB;CACjB,IAAI,cAAc,WAAW,GAAG,OAAO,CAAC;CAGxC,MAAM,yBAAS,IAAI,IAAoB;CACvC,KAAK,MAAM,QAAQ,cAAc,OAAO,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,EAAE,KAAK,KAAK,CAAC;CACnF,MAAM,QAAQ,IAAI,IAChB,cACG,MAAM,GAAG,CAAC,CAAC,CACX,QAAQ,SAAS,OAAO,IAAI,KAAK,EAAE,MAAM,CAAC,CAAC,CAC3C,KAAK,SAAS,KAAK,EAAE,CAC1B;CACA,OAAO,MACJ,KAAK,UAAU;EACd;EACA,OACE,KAAK,SAAS,QAAQ,SAAS,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,SAChD,KAAK,UAAU,QAAQ,WACrB,cAAc,MAAM,SAAS,KAAK,UAAU,SAAS,MAAM,CAAC,CAC9D,CAAC,CAAC;CACN,EAAE,CAAC,CACF,QAAQ,SAAS,KAAK,QAAQ,CAAC,CAAC,CAChC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CACjE,KAAK,SAAS,KAAK,IAAI;AAC5B;AAEA,SAAS,aAAa,GAAkB,GAA0B;CAChE,OAAO,EAAE,KAAK,cAAc,EAAE,IAAI,KAAK,EAAE,GAAG,cAAc,EAAE,EAAE;AAChE;AAEA,SAAS,aAAa,MAAc,OAAuB;CACzD,MAAM,UAAU,KAAK,QAAQ,QAAQ,GAAG,CAAC,CAAC,KAAK;CAC/C,MAAM,MAAM,QAAQ,YAAY,CAAC,CAAC,QAAQ,MAAM,YAAY,CAAC;CAC7D,IAAI,MAAM,GAAG,OAAO,QAAQ,MAAM,GAAG,GAAG;CACxC,OAAO,QAAQ,MAAM,KAAK,IAAI,GAAG,MAAM,EAAE,GAAG,KAAK,IAAI,QAAQ,QAAQ,MAAM,MAAM,SAAS,GAAG,CAAC;AAChG;AAEA,SAAS,WAAW,MAAqB,OAAyB;CAChE,MAAM,QAAQ,GAAG,KAAK,MAAM,IAAI,KAAK,OAAO,YAAY;CACxD,MAAM,UAAoB,CAAC;CAC3B,IAAI,MAAM,SAAS,MAAM,YAAY,CAAC,GAAG,QAAQ,KAAK,QAAQ;CAC9D,IAAI,KAAK,UAAU,SAAS,GAAG,QAAQ,KAAK,SAAS;CACrD,IAAI,KAAK,SAAS,SAAS,GAAG,QAAQ,KAAK,QAAQ;CACnD,OAAO;AACT"}

package/dist/search-Dde0PEtY.d.ts

@@ -0,0 +1,120 @@
+import { b as KnowledgeSearchResult, f as KnowledgeId, h as KnowledgePage, p as KnowledgeIndex } from "./types-BekdNwGD.js";
+//#region src/lexical-index.d.ts
+/**
+ * The token stream of one text: lower-cased, split on whitespace and
+ * punctuation, single characters and stop words removed, and a CJK run
+ * expanded into its bigrams and characters. Repeats are kept so a term
+ * frequency can be counted. Indexing and querying share this function, so the
+ * two vocabularies cannot drift.
+ */
+declare function tokenizeText(text: string): string[];
+/** The distinct query terms, in first-occurrence order. */
+declare function tokenizeQuery(query: string): string[];
+interface KnowledgeLexicalFieldBoosts {
+  /** Multiplier for a term occurrence in the page title. Defaults to 3. */
+  title?: number;
+  /** Multiplier for a term occurrence in the page path without its extension. Defaults to 2. */
+  path?: number;
+  /** Multiplier for a term occurrence in the page body. Defaults to 1. */
+  text?: number;
+}
+interface KnowledgeLexicalIndexOptions {
+  /** Token stream of one text. Defaults to `tokenizeText`. */
+  tokenize?: (text: string) => string[];
+  fieldBoosts?: KnowledgeLexicalFieldBoosts;
+}
+interface KnowledgeLexicalPosting {
+  /** Position of the page in `KnowledgeLexicalIndex.pages`. */
+  ordinal: number;
+  /** Field-boosted term frequency in that page. */
+  tf: number;
+}
+/**
+ * Inverted index over a fixed page list.
+ *
+ * Ordinals are positions in `pages`. `documentLengths` are field-boosted token
+ * counts, so length normalization and term frequency use one scale.
+ */
+interface KnowledgeLexicalIndex {
+  readonly pages: readonly KnowledgePage[];
+  readonly postings: ReadonlyMap<string, readonly KnowledgeLexicalPosting[]>;
+  readonly documentLengths: readonly number[];
+  readonly averageDocumentLength: number;
+  readonly documentCount: number;
+  readonly tokenize: (text: string) => string[];
+  readonly fieldBoosts: Readonly<Required<KnowledgeLexicalFieldBoosts>>;
+}
+interface Bm25Options {
+  /** Term-frequency saturation. Defaults to 1.2. */
+  k1?: number;
+  /** Length-normalization strength in [0, 1]. Defaults to 0.75. */
+  b?: number;
+}
+interface Bm25Hit {
+  page: KnowledgePage;
+  score: number;
+}
+declare function buildKnowledgeLexicalIndex(pages: readonly KnowledgePage[], options?: KnowledgeLexicalIndexOptions): KnowledgeLexicalIndex;
+/**
+ * Okapi BM25 over the distinct query terms, with the Lucene inverse document
+ * frequency `ln(1 + (N - df + 0.5) / (df + 0.5))`, which is positive for every
+ * indexed term. Pages with no matching term are absent. The result is ordered
+ * by score, then by path, so it does not depend on page order.
+ */
+declare function scoreBm25(index: KnowledgeLexicalIndex, tokens: readonly string[], options?: Bm25Options): Bm25Hit[];
+//#endregion
+//#region src/search.d.ts
+/**
+ * Identity of the ranking `searchKnowledge` performs: BM25 over title, path,
+ * and body, exact-title and phrase matches ahead of bag-of-words matches, and
+ * reciprocal rank fusion with link and shared-source structure. Declare it as
+ * the retriever id of a retrieval receipt minted from these results.
+ */
+declare const KNOWLEDGE_SEARCH_RETRIEVER_ID = "bm25-rrf-v1";
+interface SearchKnowledgeOptions {
+  /** Maximum results returned. Defaults to 10. */
+  limit?: number;
+  /** Match pages whose stable id is one of these values. */
+  pageIds?: readonly KnowledgeId[];
+  /** Match pages carrying at least one of these tags. */
+  tags?: readonly string[];
+  /** Match the exact string stored in `frontmatter.kind`. */
+  kinds?: readonly string[];
+  /**
+   * Drop pages whose own evidence refuted them. Defaults to false: a caller
+   * that reads history needs them, and a silent change of what search returns
+   * is worse than an explicit option.
+   */
+  excludeInvalidated?: boolean;
+  /** Additional caller-owned filter, applied before either ranking stage. */
+  predicate?: (page: KnowledgePage) => boolean;
+  /**
+   * A lexical index built from exactly the searched pages, supplied by a caller
+   * that searches one page set repeatedly. When absent, one is built for this
+   * call.
+   */
+  lexicalIndex?: KnowledgeLexicalIndex;
+}
+/**
+ * A retrieval result with an explicit citation handle.
+ *
+ * Unscoped search returns `page.id`; a run-scoped brief qualifies ambiguous ids
+ * through the citation resolver. Later writes should persist the returned value. Keeping it at the result's top level prevents tool
+ * renderers from accidentally hiding the only stable handle a model can copy.
+ */
+interface KnowledgeSearchHit extends KnowledgeSearchResult {
+  citationId: KnowledgeId;
+}
+declare function searchKnowledge(index: KnowledgeIndex, query: string, limit?: number): KnowledgeSearchHit[];
+declare function searchKnowledge(index: KnowledgeIndex, query: string, options?: SearchKnowledgeOptions): KnowledgeSearchHit[];
+/**
+ * Rank a page set that is not a built index, such as the chain a run can see.
+ *
+ * `searchKnowledge` is this function over `index.pages`, so both entry points
+ * rank identically and neither can drift from the other.
+ */
+declare function searchKnowledgePages(pages: readonly KnowledgePage[], query: string, limitOrOptions?: number | SearchKnowledgeOptions): KnowledgeSearchHit[];
+declare function reciprocalRankFusion(rankLists: string[][], k?: number): Map<string, number>;
+//#endregion
+export { searchKnowledge as a, Bm25Options as c, KnowledgeLexicalIndexOptions as d, KnowledgeLexicalPosting as f, tokenizeText as g, tokenizeQuery as h, reciprocalRankFusion as i, KnowledgeLexicalFieldBoosts as l, scoreBm25 as m, KnowledgeSearchHit as n, searchKnowledgePages as o, buildKnowledgeLexicalIndex as p, SearchKnowledgeOptions as r, Bm25Hit as s, KNOWLEDGE_SEARCH_RETRIEVER_ID as t, KnowledgeLexicalIndex as u };
+//# sourceMappingURL=search-Dde0PEtY.d.ts.map

package/dist/search-Dde0PEtY.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-Dde0PEtY.d.ts","names":[],"sources":["../src/lexical-index.ts","../src/search.ts"],"mappings":";;;;;;;;;iBA8BgB,aAAa;;iBAkBb,cAAc;UAIb;;EAEf;;EAEA;;EAEA;;UAGe;;EAEf,YAAY;EACZ,cAAc;;UAGC;;EAEf;;EAEA;;;;;;;;UASe;WACN,gBAAgB;WAChB,UAAU,6BAA6B;WACvC;WACA;WACA;WACA,WAAW;WACX,aAAa,SAAS,SAAS;;UAGzB;;EAEf;;EAEA;;UAGe;EACf,MAAM;EACN;;iBAGc,2BACd,gBAAgB,iBAChB,UAAS,+BACR;;;;;;;iBAiBa,UACd,OAAO,uBACP,2BACA,UAAS,cACR;;;;;;;;;cCnHU;UAEI;;EAEf;;EAEA,mBAAmB;;EAEnB;;EAEA;;;;;;EAMA;;EAEA,aAAa,MAAM;;;;;;EAMnB,eAAe;;;;;;;;;UAUA,2BAA2B;EAC1C,YAAY;;iBAGE,gBACd,OAAO,gBACP,eACA,iBACC;iBACa,gBACd,OAAO,gBACP,eACA,UAAU,yBACT;;;;;;;iBAea,qBACd,gBAAgB,iBAChB,eACA,0BAAyB,yBACxB;iBA2Ca,qBAAqB,uBAAuB,aAAY"}

package/docs/agent-tools.md

@@ -0,0 +1,60 @@
+# Give an agent the tools
+
+> Extracted from the README — see the [README](../README.md) for the package overview.
+
+## Give an agent the tools
+
+`createKnowledgeTools` returns provider-neutral `ToolDefinition[]` for search, read, record, and resolve. Knowledge owns what each tool does; a runtime only transports the definitions and the calls.
+
+```ts
+const tools = createKnowledgeTools({
+  stores,
+  runId,
+  retrieverVersion,
+  actorId,
+  intake: {},
+  recordRetrieval: (receipt) => ledger.append(receipt),
+})
+```
+
+`knowledge_search` builds a brief and mints a retrieval receipt on every call, so retrieval is recorded by the infrastructure rather than claimed by the run.
+`knowledge_read` reports an id visible at two origins as `ambiguous` with both candidates, and never chooses one.
+`knowledge_record` writes into this run's store through the intake gate.
+Each proposal must contain complete `---FILE: <page-path>---` / `---END FILE---` blocks, with delimiters on separate lines.
+The tool rejects malformed, unsafe, or empty proposals before writing any pages.
+Read an existing page before editing it.
+Pass expectedPageDigests with the page path and pageDigest returned by knowledge_read.
+The write checks each digest under the store lock.
+A stale edit refuses the whole proposal and names the current digest.
+New pages need no digest; an explicit null requires the path to be absent.
+Retrying an identical completed write is safe.
+It does not report a partial write as tool success.
+The lower-level `applyKnowledgeWriteBlocks` API retains its explicit `written` and `warnings` result for callers that inspect partial proposals.
+`knowledge_resolve` returns the resolution status of each reference.
+Every tool result carries `timing` in milliseconds: `viewMs` to obtain the current page view for search, read and resolve, `visibilityMs` to persist a search's snapshot, and `lockWaitMs` and `lockHoldMs` for a record.
+Tools re-read only the page files whose identity changed since the previous call, and concurrent calls share one refresh.
+
+Knowledge tools retain write history by default.
+Each transaction records the host actorId, runId, and exact prior and new bytes.
+An absent author remains explicitly null.
+An application can disable history with retainHistory: false.
+Lower-level writers opt into history with retainHistory: true and conditional edits with expectedPageDigests.
+Completed write transactions then retain their existing manifest and before/after snapshots under `.agent-knowledge/history/<transactionId>`.
+The move is atomic and a repeated finish after a lost acknowledgement is idempotent.
+The default remains cleanup after completion, so callers choose retention deliberately and account for its unbounded storage growth.
+Retained bytes inherit the store's access boundary; this option does not publish or merge them.
+Use the existing transaction and candidate-snapshot readers to inspect or restore them.
+
+Supply `retrieverVersion` yourself: a bundled build cannot read its own manifest, and a receipt that guessed the version would be a receipt that lies about what ranked the results.
+
+When a retrieval influences nothing, record that too:
+
+```ts
+createKnowledgeRetrievalDisposition({
+  retrieval: receipt,
+  relation: 'no-use',
+  consumer: { kind: 'decision', uri },
+})
+```
+
+A use receipt requires a selected rank, so without this record a retrieval that influenced nothing is indistinguishable from a retrieval nobody bothered to record. `irrelevant` means the results did not bear on the question; `no-use` means they did and the consumer still used none of them.

package/docs/architecture.md

@@ -37,7 +37,8 @@ When that string is the canonical `<root>/.agent-knowledge` directory, both form
 | Path | Record |
 | --- | --- |
 | `.agent-knowledge/index.json` | the built knowledge index (`writeKnowledgeIndex` writes it through this store) |
-| `.agent-knowledge/events.json` | the knowledge event log, including one `research.iteration` per research-loop round |
+| `.agent-knowledge/event-log/` | immutable event payload segments, bounded metadata buckets, and sequence state |
+| `.agent-knowledge/events.json` | legacy event array; migrated transactionally on the first event write |
 | `.agent-knowledge/claim-ledgers/<id>.json` | one research run's claim ledger: corroboration counts, contradiction edges, open deep questions |
 | `.agent-knowledge/sources.json` | the immutable source registry |
 | `.agent-knowledge/mutation.lock.durable`, `mutation-epoch.json`, `file-transactions/` | the cross-process mutation lock and its crash-recovery state |
@@ -50,6 +51,44 @@ Other processes still meet the file lock and the epoch.
 Retrieval visibility snapshots under `.agent-knowledge/retrieval-visibility/` are content-addressed evidence, written without the lock and without moving the epoch.
 There is exactly one writer per file: a second index writer alongside this one is a defect, not a variation.
 
+### Event persistence
+
+Event writes append a content-addressed payload under `event-log/records/` and replace only the affected metadata bucket under `event-log/index/` plus `state.json`. All changes use the existing recoverable file transaction under the store mutation lock. Transaction preparation, snapshot writes and full event reads admit at most eight filesystem operations per batch and drain admitted operations before reporting an error, so a large migration cannot exhaust ordinary descriptor limits or race cleanup. A repeated id replaces its visible value; older payload segments remain as retained history. Repeated writes replace the visible id without creating duplicate results. Backdated events and non-ISO `createdAt` strings retain the published `localeCompare` ordering; ties use insertion sequence.
+
+Metadata is partitioned by event-id hash prefix. A leaf holds at most 256 entries; an overflowing leaf splits into narrower hash prefixes under the same transaction. Upserts read only the matching branch and leaf, so index writes are bounded independently of the total event count.
+
+A limited query inventories and sorts the compact metadata buckets, then reads only the selected payloads. Filters apply before the limit. This is O(n) index metadata work and O(k) payload reads, not an O(1) tail lookup. Event writes do not read, sort, or rewrite the prior payload history. Retained payloads grow with distinct event versions; automatic compaction is intentionally absent because deleting history requires an explicit retention policy.
+
+**Version 21 changes the on-disk event format. Older package versions cannot read migrated roots and may report an empty event history. Do not downgrade in place.**
+
+Local comparison against `fdce05e` on Linux/Node 24 (three timed repetitions, median; fixtures preloaded, no ingestion timed):
+
+| Events | Payload | Old append | New append | Old filtered tail(5) | New filtered tail(5) |
+| --- | --- | --- | --- | --- | --- |
+| 1,000 | research iteration | 16 ms | 33 ms | 8 ms | 14 ms |
+| 10,000 | research iteration | 66 ms | 30 ms | 33 ms | 40 ms |
+| 10,000 | 8 KiB metadata | 552 ms | 24 ms | 207 ms | 40 ms |
+| 10,000 | 32 B metadata | 38 ms | 28 ms | 18 ms | 37 ms |
+
+The representative fixture follows `src/research-loop.ts`: a goal, iteration, done flag, source count, three written paths, warning count and error count. This is the package's current event producer, and its events are typically compact summaries; 8 KiB is a stress control, not the expected workload. These observations show the tradeoff, not a latency guarantee: transaction overhead makes small-store writes slower, and scanning the index can make compact-payload reads slower. At 10,000 representative events the old array is about 4.88 MB and the metadata index 1.86 MB; only five full payloads are read. The prior per-id-file design was rejected after a 7× small-payload tail regression.
+
+No claim is made of constant-time indexed tail access. Reproduce after building both revisions with `node scripts/benchmark-event-store.mjs /path/to/previous/dist/index.js`; the script emits JSONL measurements. The metadata scan uses anchored, no-follow descriptors in bounded 64-file slices, yielding between slices, and no process-global cache whose identity could go stale on promotion.
+
+Read-only access to an unmigrated `events.json` remains supported. The first write migrates it and removes it atomically; interrupted migrations use the same recovery journal as other writes. Stop older writers before upgrading. If an older writer recreates `events.json` after migration, reads and writes refuse rather than silently combining divergent histories. A missing state record alongside log files is also refused. `KB_EVENTS_PATH` continues to identify the legacy import path, not a live array to edit.
+
+For a quiesced rollback, stop all readers and writers, retain a backup of the migrated root, and export the current visible events into a separate, fresh legacy root. Use the current package to read, then the public durable writer to save the legacy array:
+
+```ts
+const events = await new FileSystemKbStore({ root: migratedRoot }).listEvents()
+await writeJsonDurableWithinRoot(freshLegacyRoot, '.agent-knowledge/events.json', events)
+```
+
+Copy the other authoritative KB content (pages, raw sources, source registry and claim ledgers) to that fresh root without `event-log/`, locks, or transaction journals, while the source remains quiescent. Validate the exported array before directing older code at the fresh root. For a direct-directory store, use its string constructor and export to `events.json`. This exports the latest value per id, which is the old array's contract; historical superseded segments remain in the backup. Never write the export into a migrated root. The original root and its snapshots remain intact, and switching back to them is possible without rebuilding lost history.
+
+The direct-directory string constructor stores `event-log/` beside its former `events.json`; the explicit root constructor stores `.agent-knowledge/event-log/`. The canonical `.agent-knowledge` string alias shares the explicit root's layout and lock. Distinct direct and root layouts remain isolated even when their roots are the same directory.
+
+Research-state candidate snapshots include the entire canonical event log, including retained payloads, so hashing, promotion, rollback and recovery preserve the exact declared event history. Default candidates still exclude research state.
+
 A claim ledger is the one record several writers legitimately share, such as a resumed run beside a live one or several workers researching one goal in parallel.
 They reach it through `mergeClaimLedger(id, merge)`, which holds the mutation lock across the read, the merge, and the write, so no writer can build its record from a value another writer has already replaced.
 `putClaimLedger` writes the whole record and is correct only for a single writer.

package/docs/cli.md

@@ -0,0 +1,19 @@
+# Use the CLI
+
+> Extracted from the README — see the [README](../README.md) for the package overview.
+
+## Use the CLI
+
+The CLI exposes the same file-backed workflow.
+
+```bash
+pnpm exec agent-knowledge init --root ./support-kb
+pnpm exec agent-knowledge source-add ./refund-policy.md --root ./support-kb
+pnpm exec agent-knowledge apply-write-blocks ./proposal.txt --root ./support-kb
+pnpm exec agent-knowledge index --root ./support-kb
+pnpm exec agent-knowledge search "refund window" --root ./support-kb
+pnpm exec agent-knowledge validate --strict --root ./support-kb
+```
+
+Run `pnpm exec agent-knowledge help` for every command.
+Pass `--pages-dir <dir>` to `apply-write-blocks`, `index`, `search`, and the other index-reading commands when the pages live outside `knowledge/`.

package/docs/compatibility.md

@@ -0,0 +1,12 @@
+# Compatibility and peer versions
+
+Knowledge 22 requires Node.js 22.12 or later and Interface 5.
+
+Eval 0.213 is the supported minor. Development and packed-package checks use its exact
+0.213.0 floor, with one physical copy each of Eval, Core 0.12, Interface 5 and Zod 4.6.5.
+Official optimizer checks require the matching `agent-eval-rpc==0.213.0` Python bridge.
+The new cohort retains Trace Contract 2.
+
+Use Knowledge 21 with Interface 4 and Eval 0.212. Use Knowledge 20 with Interface 3
+and Eval 0.209 through 0.211. Use Knowledge 19 with Interface 2 and Eval 0.201
+through 0.208, and Knowledge 17 with older Eval releases.