@tangle-network/agent-knowledge 20.0.0 → 21.0.0

package/dist/{inspect-CMigdsD5.js → inspect-DXN6SE2o.js}

@@ -1,9 +1,10 @@
 import { i as textSourceId, n as slugify, r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
+import { r as searchKnowledge } from "./search-BBr5eUyT.js";
 import { canonicalCandidateBytes, canonicalCandidateDigest, sha256Bytes, sha256DigestSchema } from "@tangle-network/agent-interface";
 import { contentHash } from "@tangle-network/agent-eval";
 import { z } from "zod";
 import { createHash, randomUUID } from "node:crypto";
-import { constants, lstatSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
 import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -399,6 +400,19 @@ function normalizePagesDirectory(value = DEFAULT_PAGES_DIRECTORY) {
 	return normalized;
 }
 //#endregion
+//#region src/bounded-file-io.ts
+/** Keep filesystem descriptors bounded and drain a failed batch before its owner releases handles. */
+async function mapFileIo(values, operation) {
+	const results = [];
+	for (let start = 0; start < values.length; start += 8) {
+		const batch = await Promise.allSettled(values.slice(start, start + 8).map((value, offset) => Promise.resolve().then(() => operation(value, start + offset))));
+		const failed = batch.find((result) => result.status === "rejected");
+		if (failed?.status === "rejected") throw failed.reason;
+		for (const result of batch) if (result.status === "fulfilled") results.push(result.value);
+	}
+	return results;
+}
+//#endregion
 //#region src/file-transaction.ts
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
 const fileModeSchema = z.number().int().min(0).max(511);
@@ -460,7 +474,7 @@ async function prepareKnowledgeFileTransaction(input) {
 		const activeTransactions = await activeTransactionDirectoryNames(transactionRoot);
 		if (activeTransactions.length > 0) throw new Error(`knowledge file transaction is already active: ${activeTransactions.join(", ")}`);
 		const paths = /* @__PURE__ */ new Set();
-		const changed = (await Promise.all(input.mutations.map(async (mutation, index) => {
+		const changed = (await mapFileIo(input.mutations, async (mutation, index) => {
 			const path = assertKnowledgeMutationPath(mutation.path, boundPagesDirectory, input.researchState);
 			if (paths.has(path)) throw new Error(`knowledge file transaction repeats path: ${path}`);
 			if (mutation.content === null && mutation.mode !== void 0) throw new Error(`deleted knowledge file cannot declare a mode: ${path}`);
@@ -485,7 +499,7 @@ async function prepareKnowledgeFileTransaction(input) {
 				before: before?.bytes ?? null,
 				after
 			};
-		}))).filter((entry) => entry !== null);
+		})).filter((entry) => entry !== null);
 		if (changed.length === 0) return null;
 		const preparationDir = await mkdtemp(join(transactionRoot, "prepare-"));
 		let activated = false;
@@ -504,10 +518,14 @@ async function prepareKnowledgeFileTransaction(input) {
 				entries: changed.map((item) => item.entry)
 			});
 			for (const side of ["before", "after"]) if (changed.some((item) => item[side])) await mkdir(join(preparationDir, side));
-			await Promise.all([...changed.flatMap((item) => ["before", "after"].flatMap((side) => {
+			await mapFileIo(changed.flatMap((item) => ["before", "after"].flatMap((side) => {
 				const bytes = item[side];
-				return bytes ? [writeFileDurable(snapshotPath(preparationDir, side, item.entry.index), bytes)] : [];
-			})), writeJsonDurable(join(preparationDir, "transaction.json"), transaction)]);
+				return bytes ? [{
+					path: snapshotPath(preparationDir, side, item.entry.index),
+					bytes
+				}] : [];
+			})), (item) => writeFileDurable(item.path, item.bytes));
+			await writeJsonDurable(join(preparationDir, "transaction.json"), transaction);
 			const activeDir = join(transactionRoot, activeTransactionDirectoryName(transaction.transactionId));
 			await renameDurable(preparationDir, activeDir);
 			activated = true;
@@ -833,7 +851,7 @@ function knowledgeMutationPathPrefixes(pagesDirectory) {
 }
 function assertKnowledgeMutationPath(path, pagesDirectory, researchState = false) {
 	const normalized = normalizeTransactionPath(path);
-	if (normalized === SOURCE_REGISTRY_PATH || researchState && (normalized === ".agent-knowledge/events.json" || /^\.agent-knowledge\/claim-ledgers\/[^/]+\.json$/.test(normalized)) || knowledgeMutationPathPrefixes(pagesDirectory).some((prefix) => normalized.startsWith(prefix))) return normalized;
+	if (normalized === SOURCE_REGISTRY_PATH || researchState && (normalized === ".agent-knowledge/events.json" || normalized === "events.json" || /^(?:\.agent-knowledge\/)?event-log\/(?:state\.json|(?:records\/[a-f0-9]{64}|index\/[a-f0-9]{2,64})\.json)$/.test(normalized) || /^\.agent-knowledge\/claim-ledgers\/[^/]+\.json$/.test(normalized)) || knowledgeMutationPathPrefixes(pagesDirectory).some((prefix) => normalized.startsWith(prefix))) return normalized;
 	throw new Error(`knowledge transaction contains an unsupported path: ${path}`);
 }
 function normalizeTransactionPath(path) {
@@ -2448,6 +2466,249 @@ function citedPageId(persisted) {
 	}
 }
 //#endregion
+//#region src/event-store.ts
+/** Durable immutable event payloads with bounded, hash-partitioned metadata buckets. */
+const stateSchema = z.object({
+	version: z.literal(1),
+	sequence: z.number().int().nonnegative().safe(),
+	count: z.number().int().nonnegative().safe()
+}).strict();
+const entrySchema = z.object({
+	id: z.string().min(1),
+	createdAt: z.string().min(1),
+	type: KnowledgeEventSchema.shape.type,
+	target: z.string().optional(),
+	sequence: z.number().int().nonnegative().safe(),
+	digest: z.string().regex(/^[a-f0-9]{64}$/)
+}).strict();
+const MAX_BUCKET_ENTRIES = 256;
+const bucketSchema = z.discriminatedUnion("kind", [z.object({ kind: z.literal("branch") }).strict(), z.object({
+	kind: z.literal("leaf"),
+	entries: z.array(entrySchema).max(MAX_BUCKET_ENTRIES)
+}).strict()]);
+const encode = (value) => `${JSON.stringify(value)}\n`;
+const recordPath = (directory, digest) => `${directory}/records/${digest}.json`;
+const bucketPath = (directory, prefix) => `${directory}/index/${prefix}.json`;
+async function readOptional(root, path) {
+	try {
+		return (await readRegularFileWithinRoot(root, path)).bytes;
+	} catch (error) {
+		if (isMissingFile(error)) return void 0;
+		throw error;
+	}
+}
+async function assertNoLegacy(root, path) {
+	if (await withSafeDescendant(root, path, async (target) => {
+		try {
+			await lstat(target);
+			return true;
+		} catch (error) {
+			if (isMissingFile(error)) return false;
+			throw error;
+		}
+	})) throw new Error("legacy event history reappeared after migration; reconcile the older writer before proceeding");
+}
+function ordered(entries) {
+	return entries.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.sequence - b.sequence);
+}
+async function putStoredEvent(root, legacyPath, event) {
+	const directory = legacyPath === "events.json" ? "event-log" : ".agent-knowledge/event-log";
+	const statePath = `${directory}/state.json`;
+	const parsed = KnowledgeEventSchema.parse(structuredClone(event));
+	const purpose = `event-put:${sha256(encode({
+		legacyPath,
+		event: parsed
+	}))}`;
+	await withKnowledgeMutation(root, async (lock) => {
+		const saved = await readOptional(root, statePath);
+		let sequence = 0;
+		let count = 0;
+		const mutations = /* @__PURE__ */ new Map();
+		const add = (path, content) => mutations.set(path, {
+			path,
+			content
+		});
+		const bucketCache = /* @__PURE__ */ new Map();
+		const writeBucket = (prefix, entries) => {
+			const writeTree = (prefix, entries) => {
+				if (entries.length <= MAX_BUCKET_ENTRIES) {
+					const bucket = {
+						kind: "leaf",
+						entries: entries.sort((a, b) => a.id.localeCompare(b.id))
+					};
+					bucketCache.set(prefix, bucket);
+					add(bucketPath(directory, prefix), encode(bucket));
+					return;
+				}
+				if (prefix.length >= 64) throw new Error("event id hash collision");
+				const branch = { kind: "branch" };
+				bucketCache.set(prefix, branch);
+				add(bucketPath(directory, prefix), encode(branch));
+				const groups = /* @__PURE__ */ new Map();
+				for (const entry of entries) {
+					const child = sha256(entry.id).slice(0, prefix.length + 1);
+					const group = groups.get(child) ?? [];
+					group.push(entry);
+					groups.set(child, group);
+				}
+				for (const [child, group] of groups) writeTree(child, group);
+			};
+			writeTree(prefix, entries);
+		};
+		const putIndexEntry = async (entry) => {
+			const idHash = sha256(entry.id);
+			for (let length = 2; length <= 64; length++) {
+				const prefix = idHash.slice(0, length);
+				let bucket = bucketCache.get(prefix);
+				if (!bucket) {
+					const bytes = await readOptional(root, bucketPath(directory, prefix));
+					bucket = bytes ? parseBucket(prefix, bytes, sequence) : {
+						kind: "leaf",
+						entries: []
+					};
+					bucketCache.set(prefix, bucket);
+				}
+				if (bucket.kind === "branch") continue;
+				if (!bucket.entries.some((value) => value.id === entry.id)) count += 1;
+				writeBucket(prefix, [...bucket.entries.filter((value) => value.id !== entry.id), entry]);
+				return;
+			}
+			throw new Error("event index has an invalid terminal branch");
+		};
+		const append = async (value) => {
+			if (sequence >= Number.MAX_SAFE_INTEGER) throw new Error("event sequence exhausted");
+			sequence += 1;
+			const content = encode(value);
+			const digest = sha256(content);
+			add(recordPath(directory, digest), content);
+			await putIndexEntry({
+				id: value.id,
+				createdAt: value.createdAt,
+				type: value.type,
+				...value.target === void 0 ? {} : { target: value.target },
+				sequence,
+				digest
+			});
+		};
+		if (saved) {
+			const state = stateSchema.parse(JSON.parse(saved.toString("utf8")));
+			sequence = state.sequence;
+			count = state.count;
+			await assertNoLegacy(root, legacyPath);
+		} else {
+			await assertEmptyLog(root, directory);
+			const legacy = await readOptional(root, legacyPath);
+			if (legacy) {
+				const events = z.array(KnowledgeEventSchema).parse(JSON.parse(legacy.toString("utf8")));
+				for (const value of events) await append(value);
+				add(legacyPath, null);
+			}
+		}
+		await append(parsed);
+		add(statePath, encode({
+			version: 1,
+			sequence,
+			count
+		}));
+		await commitKnowledgeFileMutations({
+			root,
+			transactionRoot: lock.transactionRoot,
+			purpose,
+			researchState: true,
+			mutations: [...mutations.values()],
+			assertOwned: lock.assertOwned
+		});
+	}, { resumeTransaction: { purpose } });
+}
+async function listStoredEvents(root, legacyPath, query) {
+	const directory = legacyPath === "events.json" ? "event-log" : ".agent-knowledge/event-log";
+	const statePath = `${directory}/state.json`;
+	return withKnowledgeRead(root, async () => {
+		const saved = await readOptional(root, statePath);
+		if (!saved) {
+			await assertEmptyLog(root, directory);
+			const bytes = await readOptional(root, legacyPath);
+			let events = bytes ? z.array(KnowledgeEventSchema).parse(JSON.parse(bytes.toString("utf8"))) : [];
+			if (query.type) events = events.filter((event) => event.type === query.type);
+			if (query.target) events = events.filter((event) => event.target === query.target);
+			return events.slice(-(query.limit ?? events.length));
+		}
+		const state = stateSchema.parse(JSON.parse(saved.toString("utf8")));
+		await assertNoLegacy(root, legacyPath);
+		const entries = [];
+		const buckets = /* @__PURE__ */ new Map();
+		for (const file of await readEventIndex(root, `${directory}/index`)) {
+			const prefix = file.path.slice(`${directory}/index/`.length, -5);
+			buckets.set(prefix, parseBucket(prefix, file.bytes, state.sequence));
+		}
+		let count = 0;
+		for (const [prefix, bucket] of buckets) {
+			for (let length = 2; length < prefix.length; length++) if (buckets.get(prefix.slice(0, length))?.kind !== "branch") throw new Error("event index has an orphaned bucket");
+			if (bucket.kind === "branch") {
+				if (![...buckets.keys()].some((child) => child.length === prefix.length + 1 && child.startsWith(prefix))) throw new Error("event index branch has no children");
+				continue;
+			}
+			count += bucket.entries.length;
+			for (const entry of bucket.entries) {
+				if (query.type && entry.type !== query.type) continue;
+				if (query.target && entry.target !== query.target) continue;
+				entries.push(entry);
+			}
+		}
+		if (count !== state.count) throw new Error("event index entry count mismatch");
+		return mapFileIo(ordered(entries).slice(-(query.limit ?? entries.length)), async (entry) => {
+			const bytes = (await readRegularFileWithinRoot(root, recordPath(directory, entry.digest))).bytes;
+			if (createHash("sha256").update(bytes).digest("hex") !== entry.digest) throw new Error("event payload digest mismatch");
+			const event = KnowledgeEventSchema.parse(JSON.parse(bytes.toString("utf8")));
+			if (event.id !== entry.id || event.createdAt !== entry.createdAt || event.type !== entry.type || event.target !== entry.target) throw new Error("event payload index mismatch");
+			return event;
+		});
+	});
+}
+async function assertEmptyLog(root, directory) {
+	try {
+		if ((await listRegularFilesWithinRoot(root, directory)).length) throw new Error("event log state is missing; recover the log before proceeding");
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+	}
+}
+async function readEventIndex(root, relativeDirectory) {
+	return withSafeDirectory(root, relativeDirectory, false, async (directory) => {
+		const entries = await readdir(directory, { withFileTypes: true });
+		const files = [];
+		for (let start = 0; start < entries.length; start += 64) {
+			if (start > 0) await new Promise((resolve) => setImmediate(resolve));
+			for (const entry of entries.slice(start, start + 64)) {
+				if (!entry.isFile() || !/^[a-f0-9]{2,64}\.json$/.test(entry.name)) throw new Error("event index contains an unsupported entry");
+				const fd = openSync(join(directory, entry.name), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+				try {
+					if (!fstatSync(fd).isFile()) throw new Error("event index contains an unsupported entry");
+					files.push({
+						path: `${relativeDirectory}/${entry.name}`,
+						bytes: readFileSync(fd)
+					});
+				} finally {
+					closeSync(fd);
+				}
+			}
+		}
+		return files;
+	});
+}
+function parseBucket(prefix, bytes, sequence) {
+	const bucket = bucketSchema.parse(JSON.parse(bytes.toString("utf8")));
+	if (bucket.kind === "branch") {
+		if (prefix.length >= 64) throw new Error("event index has an invalid terminal branch");
+		return bucket;
+	}
+	const ids = /* @__PURE__ */ new Set();
+	for (const entry of bucket.entries) {
+		if (!sha256(entry.id).startsWith(prefix) || entry.sequence > sequence || ids.has(entry.id)) throw new Error("event index identity mismatch");
+		ids.add(entry.id);
+	}
+	return bucket;
+}
+//#endregion
 //#region src/kb-store.ts
 /**
 * Where a filesystem knowledge base keeps its machine-written records, relative
@@ -2462,6 +2723,7 @@ function citedPageId(persisted) {
 */
 const KB_STORE_DIR = ".agent-knowledge";
 const KB_INDEX_PATH = `${KB_STORE_DIR}/index.json`;
+/** Legacy array import path; new events live in the adjacent event-log directory. */
 const KB_EVENTS_PATH = `${KB_STORE_DIR}/events.json`;
 const KB_CLAIM_LEDGER_DIR = `${KB_STORE_DIR}/claim-ledgers`;
 /**
@@ -2525,6 +2787,8 @@ var MemoryKbStore = class {
 		};
 	}
 	async putEvent(event) {
+		const position = this.events.findIndex((entry) => entry.id === event.id);
+		if (position !== -1) this.events.splice(position, 1);
 		this.events.push(clone(event));
 	}
 	async listEvents(query = {}) {
@@ -2551,7 +2815,6 @@ var MemoryKbStore = class {
 		return clone(next);
 	}
 };
-const knowledgeEventsSchema = z.array(KnowledgeEventSchema);
 var FileSystemKbStore = class {
 	root;
 	indexPath;
@@ -2616,19 +2879,10 @@ var FileSystemKbStore = class {
 		return withKnowledgeRead(this.root, () => this.readIndex());
 	}
 	async putEvent(event) {
-		const parsed = KnowledgeEventSchema.parse(event);
-		await withKnowledgeMutation(this.root, async () => {
-			const next = [...(await this.readEvents()).filter((entry) => entry.id !== parsed.id), parsed].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-			await writeJsonDurableWithinRoot(this.root, this.eventsPath, next);
-		});
+		await putStoredEvent(this.root, this.eventsPath, event);
 	}
 	async listEvents(query = {}) {
-		return withKnowledgeRead(this.root, async () => {
-			let events = await this.readEvents();
-			if (query.type) events = events.filter((event) => event.type === query.type);
-			if (query.target) events = events.filter((event) => event.target === query.target);
-			return clone(events.slice(-(query.limit ?? events.length)));
-		});
+		return this.readEvents(query);
 	}
 	async putClaimLedger(ledger) {
 		const parsed = parseResearchClaimLedger(ledger);
@@ -2678,8 +2932,8 @@ var FileSystemKbStore = class {
 	async readIndex() {
 		return readJsonFile(this.root, this.indexPath, KnowledgeIndexSchema);
 	}
-	async readEvents() {
-		return await readJsonFile(this.root, this.eventsPath, knowledgeEventsSchema) ?? [];
+	async readEvents(query = {}) {
+		return listStoredEvents(this.root, this.eventsPath, query);
 	}
 	claimLedgerPath(id) {
 		return `${this.claimLedgerDir}/${assertClaimLedgerId(id)}.json`;
@@ -4556,278 +4810,6 @@ function stringMetadata(metadata, key) {
 	return typeof value === "string" ? value : void 0;
 }
 //#endregion
-//#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
 //#region src/inspect.ts
 function inspectKnowledgeIndex(index, options = {}) {
 	const now = options.now ?? /* @__PURE__ */ new Date();
@@ -4891,6 +4873,6 @@ function explainKnowledgeTarget(index, target) {
 	};
 }
 //#endregion
-export { assertGradeableEvidence as $, removeDurable as $n, KnowledgeIndexSchema as $t, createKnowledgeVisibilitySnapshot as A, isKnowledgeMutationHeld as An, auditKnowledgeCitations as At, snapshotImmutableVisibility as B, knowledgeFileTransactionPlanHash as Bn, isScaffoldPath as Bt, createRunScopedStores as C, mergeTrackedClaims as Cn, KnowledgeCitationAuditError as Ct, KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM as D, parseFrontmatter as Dn, assertKnowledgeCitationsResolved as Dt, originatedPages as E, formatFrontmatter as En, assertKnowledgeCitationAudit as Et, knowledgePageDigest as F, withKnowledgeRead as Fn, resolveRunScopedCitation as Ft, visibilityIndexOf as G, canonicalPathsEqual as Gn, WIKILINK_REGEX as Gt, validateOrigin as H, rollbackKnowledgeFileTransaction as Hn, layoutFor as Ht, knowledgeVisibilityArtifactRef as I, applyKnowledgeFileTransaction as In, resolveRunScopedCitations as It, validateKnowledgeIndex as J, isMissingFile as Jn, DeepQuestionSchema as Jt, detectNearDuplicatePages as K, canonicalRelativeWithinRoot as Kn, extractWikilinks as Kt, nonEmpty as L, assertKnowledgeMutationPath as Ln, SCAFFOLD_PAGE_BASENAMES as Lt, digest as M, recoverPendingKnowledgeMutation as Mn, parseKnowledgeCitationReference as Mt, encodeKnowledgeVisibilitySnapshot as N, runInKnowledgeMutationScope as Nn, resolveKnowledgeCitation as Nt, KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION as O, acquireDurableFileLock as On, assertRunScopedCitationsResolved as Ot, immutablePageDigest as P, withKnowledgeMutation as Pn, resolveKnowledgeCitations as Pt, UncheckableClaimError as Q, relativeWithinRoot as Qn, KnowledgeGraphNodeSchema as Qt, normalizeVisibilityArtifact as R, commitKnowledgeFileMutations as Rn, initKnowledgeBase as Rt, createFileRunLineageAuthority as S, mergeClaimLedgers as Sn, knowledgePageRelations as St, loadKnowledgeToolChain as T, researchSourceVersionKey as Tn, assertCurrentRunCitationsResolved as Tt, verifyKnowledgeVisibilitySnapshot as U, DEFAULT_PAGES_DIRECTORY as Un, loadKnowledgePages as Ut, validateKnowledgePage as V, prepareKnowledgeFileTransaction as Vn, knowledgePageFromMarkdown as Vt, visibilityIdentity as W, normalizePagesDirectory as Wn, writeJson as Wt, CHECKABLE_RUNG_THRESHOLD as X, readRegularFileNoFollow as Xn, KnowledgeEventSchema as Xt, lintKnowledgeIndex as Y, listRegularFilesWithinRoot as Yn, KnowledgeBaseCandidateSchema as Yt, DEADLINE_EXIT_CODE as Z, readRegularFileWithinRoot as Zn, KnowledgeGraphEdgeSchema as Zt, isSafeKnowledgePath as _, claimSourceHost as _n, KB_INDEX_PATH as _t, searchKnowledge as a, ResearchClaimRecordSchema as an, writeFileDurableWithinRoot as ar, buildKnowledgeIndex as at, assertKnowledgeWriteIntake as b, linkClaimContradictions as bn, assertClaimLedgerId as bt, scoreBm25 as c, SourceRecordSchema as cn, mediaTypeFor$1 as cr, addSourceText as ct, DEFAULT_FIELD_BOOSTS as d, assertDeepQuestionIntegrity as dn, sourceRegistryPath as dt, KnowledgePageInvalidationSchema as en, renameDurable as er, claimCheckKey as et, assembleLexicalIndex as f, assertResearchClaimEvidenceIntegrity as fn, writeSourceRegistry as ft, applyKnowledgeWriteBlocksFile as g, claimId as gn, KB_EVENTS_PATH as gt, applyKnowledgeWriteBlocks as h, claimEvidenceId as hn, KB_CLAIM_LEDGER_DIR as ht, reciprocalRankFusion as i, ResearchClaimLedgerSchema as in, writeFileDurable as ir, verifyGradeableEvidence as it, decodeKnowledgeVisibilitySnapshot as j, measureKnowledgeMutation as jn, formatKnowledgeCitationReference as jt, assertSchemaVersion as k, inspectPendingKnowledgeMutation as kn, auditCurrentRunCitations as kt, tokenizeQuery as l, KNOWLEDGE_EVENT_TYPES as ln, textSourceAdapter as lr, loadSourceRegistry as lt, stringMetadata as m, assertTrackedClaimIntegrity as mn, FileSystemKbStore as mt, inspectKnowledgeIndex as n, KnowledgeRelationSchema as nn, withSafeDescendant as nr, gradeFor as nt, searchKnowledgePages as o, ResearchSourceVersionSchema as on, writeJsonDurable as or, writeKnowledgeIndex as ot, lexicalPageTerms as p, assertResearchClaimLedgerIntegrity as pn, ClaimLedgerMigrationRequiredError as pt, normalizePageText as q, isKernelAnchoredPath as qn, normalizeLinkTarget as qt, KNOWLEDGE_SEARCH_RETRIEVER_ID as r, ResearchClaimEvidenceSchema as rn, withSafeDirectory as rr, verdictFor as rt, buildKnowledgeLexicalIndex as s, SourceAnchorSchema as sn, writeJsonDurableWithinRoot as sr, addSourcePath as st, explainKnowledgeTarget as t, KnowledgePageSchema as tn, syncDirectory as tr, gradeClaims as tt, tokenizeText as u, ClaimLedgerGoalConflictError as un, snapshotSourceTextInput as ut, parseKnowledgeWriteBlocks as v, deepQuestionId as vn, KB_STORE_DIR as vt, isKnowledgeToolChain as w, normalizeClaimText as wn, KnowledgeCitationResolutionError as wt, RUN_LINEAGE_BASENAME as x, materializeRegisteredClaimEvidence as xn, buildKnowledgeGraph as xt, KnowledgeDuplicateIntakeError as y, emptyClaimLedger as yn, MemoryKbStore as yt, normalizeVisibilityRef as z, finishKnowledgeFileTransaction as zn, isKnowledgePagePath as zt };
+export { snapshotSourceTextInput as $, ClaimLedgerGoalConflictError as $t, validateKnowledgePage as A, prepareKnowledgeFileTransaction as An, knowledgePageFromMarkdown as At, DEADLINE_EXIT_CODE as B, readRegularFileWithinRoot as Bn, KnowledgeGraphEdgeSchema as Bt, immutablePageDigest as C, withKnowledgeMutation as Cn, resolveKnowledgeCitations as Ct, normalizeVisibilityArtifact as D, commitKnowledgeFileMutations as Dn, initKnowledgeBase as Dt, nonEmpty as E, assertKnowledgeMutationPath as En, SCAFFOLD_PAGE_BASENAMES as Et, detectNearDuplicatePages as F, canonicalRelativeWithinRoot as Fn, extractWikilinks as Ft, gradeFor as G, withSafeDescendant as Gn, KnowledgeRelationSchema as Gt, assertGradeableEvidence as H, removeDurable as Hn, KnowledgeIndexSchema as Ht, normalizePageText as I, isKernelAnchoredPath as In, normalizeLinkTarget as It, buildKnowledgeIndex as J, writeFileDurableWithinRoot as Jn, ResearchClaimRecordSchema as Jt, verdictFor as K, withSafeDirectory as Kn, ResearchClaimEvidenceSchema as Kt, validateKnowledgeIndex as L, isMissingFile as Ln, DeepQuestionSchema as Lt, verifyKnowledgeVisibilitySnapshot as M, DEFAULT_PAGES_DIRECTORY as Mn, loadKnowledgePages as Mt, visibilityIdentity as N, normalizePagesDirectory as Nn, writeJson as Nt, normalizeVisibilityRef as O, finishKnowledgeFileTransaction as On, isKnowledgePagePath as Ot, visibilityIndexOf as P, canonicalPathsEqual as Pn, WIKILINK_REGEX as Pt, loadSourceRegistry as Q, textSourceAdapter as Qn, KNOWLEDGE_EVENT_TYPES as Qt, lintKnowledgeIndex as R, listRegularFilesWithinRoot as Rn, KnowledgeBaseCandidateSchema as Rt, encodeKnowledgeVisibilitySnapshot as S, runInKnowledgeMutationScope as Sn, resolveKnowledgeCitation as St, knowledgeVisibilityArtifactRef as T, applyKnowledgeFileTransaction as Tn, resolveRunScopedCitations as Tt, claimCheckKey as U, renameDurable as Un, KnowledgePageInvalidationSchema as Ut, UncheckableClaimError as V, relativeWithinRoot as Vn, KnowledgeGraphNodeSchema as Vt, gradeClaims as W, syncDirectory as Wn, KnowledgePageSchema as Wt, addSourcePath as X, writeJsonDurableWithinRoot as Xn, SourceAnchorSchema as Xt, writeKnowledgeIndex as Y, writeJsonDurable as Yn, ResearchSourceVersionSchema as Yt, addSourceText as Z, mediaTypeFor$1 as Zn, SourceRecordSchema as Zt, KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION as _, acquireDurableFileLock as _n, assertRunScopedCitationsResolved as _t, applyKnowledgeWriteBlocksFile as a, claimId as an, KB_EVENTS_PATH as at, decodeKnowledgeVisibilitySnapshot as b, measureKnowledgeMutation as bn, formatKnowledgeCitationReference as bt, KnowledgeDuplicateIntakeError as c, emptyClaimLedger as cn, MemoryKbStore as ct, createFileRunLineageAuthority as d, mergeClaimLedgers as dn, knowledgePageRelations as dt, assertDeepQuestionIntegrity as en, sourceRegistryPath as et, createRunScopedStores as f, mergeTrackedClaims as fn, KnowledgeCitationAuditError as ft, KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM as g, parseFrontmatter as gn, assertKnowledgeCitationsResolved as gt, originatedPages as h, formatFrontmatter as hn, assertKnowledgeCitationAudit as ht, applyKnowledgeWriteBlocks as i, claimEvidenceId as in, KB_CLAIM_LEDGER_DIR as it, validateOrigin as j, rollbackKnowledgeFileTransaction as jn, layoutFor as jt, snapshotImmutableVisibility as k, knowledgeFileTransactionPlanHash as kn, isScaffoldPath as kt, assertKnowledgeWriteIntake as l, linkClaimContradictions as ln, assertClaimLedgerId as lt, loadKnowledgeToolChain as m, researchSourceVersionKey as mn, assertCurrentRunCitationsResolved as mt, inspectKnowledgeIndex as n, assertResearchClaimLedgerIntegrity as nn, ClaimLedgerMigrationRequiredError as nt, isSafeKnowledgePath as o, claimSourceHost as on, KB_INDEX_PATH as ot, isKnowledgeToolChain as p, normalizeClaimText as pn, KnowledgeCitationResolutionError as pt, verifyGradeableEvidence as q, writeFileDurable as qn, ResearchClaimLedgerSchema as qt, stringMetadata as r, assertTrackedClaimIntegrity as rn, FileSystemKbStore as rt, parseKnowledgeWriteBlocks as s, deepQuestionId as sn, KB_STORE_DIR as st, explainKnowledgeTarget as t, assertResearchClaimEvidenceIntegrity as tn, writeSourceRegistry as tt, RUN_LINEAGE_BASENAME as u, materializeRegisteredClaimEvidence as un, buildKnowledgeGraph as ut, assertSchemaVersion as v, inspectPendingKnowledgeMutation as vn, auditCurrentRunCitations as vt, knowledgePageDigest as w, withKnowledgeRead as wn, resolveRunScopedCitation as wt, digest as x, recoverPendingKnowledgeMutation as xn, parseKnowledgeCitationReference as xt, createKnowledgeVisibilitySnapshot as y, isKnowledgeMutationHeld as yn, auditKnowledgeCitations as yt, CHECKABLE_RUNG_THRESHOLD as z, readRegularFileNoFollow as zn, KnowledgeEventSchema as zt };
 
-//# sourceMappingURL=inspect-CMigdsD5.js.map
+//# sourceMappingURL=inspect-DXN6SE2o.js.map