@tangle-network/agent-knowledge 8.0.9 → 10.6.0

package/dist/index.js

@@ -1,13 +1,13 @@
-import { $ as WIKILINK_REGEX, $t as syncDirectory, A as MemoryKbStore, At as mergeTrackedClaims, B as auditKnowledgeCitations, Bt as applyKnowledgeFileTransaction, C as writeSourceRegistry, Ct as claimId, D as KB_EVENTS_PATH, Dt as linkClaimContradictions, E as KB_CLAIM_LEDGER_DIR, Et as emptyClaimLedger, F as assertCurrentRunCitationsResolved, Ft as acquireDurableFileLock, G as resolveRunScopedCitation, Gt as rollbackKnowledgeFileTransaction, H as parseKnowledgeCitationReference, Ht as finishKnowledgeFileTransaction, I as assertKnowledgeCitationAudit, It as inspectPendingKnowledgeMutation, J as initKnowledgeBase, Jt as listRegularFilesWithinRoot, K as resolveRunScopedCitations, Kt as isKernelAnchoredPath, L as assertKnowledgeCitationsResolved, Lt as recoverPendingKnowledgeMutation, M as buildKnowledgeGraph, Mt as researchSourceVersionKey, N as KnowledgeCitationAuditError, Nt as formatFrontmatter, O as KB_INDEX_PATH, Ot as materializeRegisteredClaimEvidence, P as KnowledgeCitationResolutionError, Pt as parseFrontmatter, Q as writeJson, Qt as renameDurable, R as assertRunScopedCitationsResolved, Rt as withKnowledgeMutation, S as sourceRegistryPath, St as claimEvidenceId, T as FileSystemKbStore, Tt as deepQuestionId, U as resolveKnowledgeCitation, Ut as knowledgeFileTransactionPlanHash, V as formatKnowledgeCitationReference, Vt as assertKnowledgeMutationPath, W as resolveKnowledgeCitations, Wt as prepareKnowledgeFileTransaction, X as layoutFor, Xt as readRegularFileWithinRoot, Y as isScaffoldPath, Yt as readRegularFileNoFollow, Z as loadKnowledgePages, Zt as removeDurable, _ as writeKnowledgeIndex, _t as ClaimLedgerGoalConflictError, a as applyKnowledgeWriteBlocksFile, an as writeJsonDurableWithinRoot, at as KnowledgeGraphEdgeSchema, b as loadSourceRegistry, bt as assertResearchClaimLedgerIntegrity, c as validateKnowledgeIndex, ct as KnowledgePageInvalidationSchema, d as UncheckableClaimError, dt as ResearchClaimLedgerSchema, en as withSafeDescendant, et as extractWikilinks, f as assertGradeableEvidence, ft as ResearchClaimRecordSchema, g as buildKnowledgeIndex, gt as KNOWLEDGE_EVENT_TYPES, h as verifyGradeableEvidence, ht as SourceRecordSchema, i as applyKnowledgeWriteBlocks, in as writeJsonDurable, it as KnowledgeEventSchema, j as assertClaimLedgerId, jt as normalizeClaimText, k as KB_STORE_DIR, kt as mergeClaimLedgers, l as lintKnowledgeIndex, lt as KnowledgePageSchema, m as verdictFor, mt as SourceAnchorSchema, n as inspectKnowledgeIndex, nn as writeFileDurable, nt as DeepQuestionSchema, o as isSafeKnowledgePath, on as mediaTypeFor, ot as KnowledgeGraphNodeSchema, p as gradeFor, pt as ResearchSourceVersionSchema, q as SCAFFOLD_PAGE_BASENAMES, qt as isMissingFile, r as stringMetadata, rn as writeFileDurableWithinRoot, rt as KnowledgeBaseCandidateSchema, s as parseKnowledgeWriteBlocks, sn as textSourceAdapter, st as KnowledgeIndexSchema, t as explainKnowledgeTarget, tn as withSafeDirectory, tt as normalizeLinkTarget, u as CHECKABLE_RUNG_THRESHOLD, ut as ResearchClaimEvidenceSchema, v as addSourcePath, vt as assertDeepQuestionIntegrity, w as ClaimLedgerMigrationRequiredError, wt as claimSourceHost, x as snapshotSourceTextInput, xt as assertTrackedClaimIntegrity, y as addSourceText, yt as assertResearchClaimEvidenceIntegrity, z as auditCurrentRunCitations, zt as withKnowledgeRead } from "./inspect-0tmv3xV8.js";
+import { $ as resolveKnowledgeCitations, $t as withKnowledgeRead, A as sourceRegistryPath, At as KNOWLEDGE_EVENT_TYPES, B as buildKnowledgeGraph, Bt as emptyClaimLedger, C as verifyGradeableEvidence, Cn as mediaTypeFor, Ct as KnowledgeRelationSchema, D as addSourceText, Dt as ResearchSourceVersionSchema, E as addSourcePath, Et as ResearchClaimRecordSchema, F as KB_EVENTS_PATH, Ft as assertTrackedClaimIntegrity, G as assertKnowledgeCitationAudit, Gt as normalizeClaimText, H as KnowledgeCitationAuditError, Ht as materializeRegisteredClaimEvidence, I as KB_INDEX_PATH, It as claimEvidenceId, J as auditCurrentRunCitations, Jt as parseFrontmatter, K as assertKnowledgeCitationsResolved, Kt as researchSourceVersionKey, L as KB_STORE_DIR, Lt as claimId, M as ClaimLedgerMigrationRequiredError, Mt as assertDeepQuestionIntegrity, N as FileSystemKbStore, Nt as assertResearchClaimEvidenceIntegrity, O as loadSourceRegistry, Ot as SourceAnchorSchema, P as KB_CLAIM_LEDGER_DIR, Pt as assertResearchClaimLedgerIntegrity, Q as resolveKnowledgeCitation, Qt as withKnowledgeMutation, R as MemoryKbStore, Rt as claimSourceHost, S as verdictFor, Sn as writeJsonDurableWithinRoot, St as KnowledgeRelationNodeSchema, T as writeKnowledgeIndex, Tt as ResearchClaimLedgerSchema, U as KnowledgeCitationResolutionError, Ut as mergeClaimLedgers, V as knowledgePageRelations, Vt as linkClaimContradictions, W as assertCurrentRunCitationsResolved, Wt as mergeTrackedClaims, X as formatKnowledgeCitationReference, Xt as inspectPendingKnowledgeMutation, Y as auditKnowledgeCitations, Yt as acquireDurableFileLock, Z as parseKnowledgeCitationReference, Zt as recoverPendingKnowledgeMutation, _ as lintKnowledgeIndex, _n as withSafeDescendant, _t as KnowledgeGraphNodeSchema, a as applyKnowledgeWriteBlocksFile, an as prepareKnowledgeFileTransaction, at as isScaffoldPath, b as assertGradeableEvidence, bn as writeFileDurableWithinRoot, bt as KnowledgePageSchema, c as KnowledgeDuplicateIntakeError, cn as normalizePagesDirectory, ct as loadKnowledgePages, d as createFileRunLineageAuthority, dn as listRegularFilesWithinRoot, dt as extractWikilinks, en as applyKnowledgeFileTransaction, et as resolveRunScopedCitation, f as createRunScopedStores, fn as readRegularFileNoFollow, ft as normalizeLinkTarget, g as validateKnowledgeIndex, gn as syncDirectory, gt as KnowledgeGraphEdgeSchema, h as normalizePageText, hn as renameDurable, ht as KnowledgeEventSchema, i as applyKnowledgeWriteBlocks, in as knowledgeFileTransactionPlanHash, it as isKnowledgePagePath, j as writeSourceRegistry, jt as ClaimLedgerGoalConflictError, k as snapshotSourceTextInput, kt as SourceRecordSchema, l as assertKnowledgeWriteIntake, ln as isKernelAnchoredPath, lt as writeJson, m as detectNearDuplicatePages, mn as removeDurable, mt as KnowledgeBaseCandidateSchema, n as inspectKnowledgeIndex, nn as commitKnowledgeFileMutations, nt as SCAFFOLD_PAGE_BASENAMES, o as isSafeKnowledgePath, on as rollbackKnowledgeFileTransaction, ot as knowledgePageFromMarkdown, p as originatedPages, pn as readRegularFileWithinRoot, pt as DeepQuestionSchema, q as assertRunScopedCitationsResolved, qt as formatFrontmatter, r as stringMetadata, rn as finishKnowledgeFileTransaction, rt as initKnowledgeBase, s as parseKnowledgeWriteBlocks, sn as DEFAULT_PAGES_DIRECTORY, st as layoutFor, t as explainKnowledgeTarget, tn as assertKnowledgeMutationPath, tt as resolveRunScopedCitations, u as RUN_LINEAGE_BASENAME, un as isMissingFile, ut as WIKILINK_REGEX, v as CHECKABLE_RUNG_THRESHOLD, vn as withSafeDirectory, vt as KnowledgeIndexSchema, w as buildKnowledgeIndex, wn as textSourceAdapter, wt as ResearchClaimEvidenceSchema, x as gradeFor, xn as writeJsonDurable, xt as KnowledgeRelationGraphSchema, y as UncheckableClaimError, yn as writeFileDurable, yt as KnowledgePageInvalidationSchema, z as assertClaimLedgerId, zt as deepQuestionId } from "./inspect-DALsvG10.js";
 import { i as textSourceId, n as slugify, r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
-import { A as runSerializedKnowledgeOptimization, C as deterministicRng, D as toOffPolicyTrajectory, E as retrievalHoldoutConfigHash, M as assertImmutableRef, O as jsonCandidateCodec, S as applySessionStickyRetrievalHoldout, T as resetRetrievalHoldoutRegistry, _ as createAgentMemoryBranch, a as createNeo4jAgentMemoryAdapter, b as renderMemoryContext, c as runAgentMemoryImprovement, d as compareAgentMemoryLearning, f as runAgentMemoryLearningExperiment, g as buildAgentMemorySequencesFromBenchmarkCases, h as buildAgentMemorySequenceScenarios, i as AgentMemoryWriteInputSchema, j as scenarioContentFingerprint, k as jsonObjectCandidateCodec, l as createGraphitiMemoryAdapter, m as agentMemorySequenceJudge, n as AgentMemoryKindSchema, o as createMem0MemoryAdapter, p as runAgentMemoryExperiment, r as AgentMemoryScopeSchema, s as mem0MemoryAdapterIdentity, t as AgentMemoryHitSchema, u as graphitiMemoryAdapterIdentity, v as forkAgentMemoryBranchSnapshot, w as emitRetrievalHoldoutBypass, x as applyRetrievalHoldout, y as defaultGetMemoryContext } from "./memory-BPgPIEhj.js";
-import { n as searchKnowledge, r as tokenizeQuery, t as reciprocalRankFusion } from "./search-CtVJ0PKX.js";
-import { B as createNoopMemoryBenchmarkAdapter, C as sleepForMemoryRecovery, F as buildIndustryRagBenchmarkSmokeCases, G as retrievalConfigFromSurface, H as memoryWriteResultToSourceRecord, I as respondToIndustryMemoryBenchmarkSmokeCase, J as scoreRetrievalArtifact, K as retrievalConfigSurface, L as respondToIndustryRagBenchmarkSmokeCase, M as INDUSTRY_RAG_BENCHMARKS, N as buildFirstPartyMemoryLifecycleBenchmarkCases, P as buildIndustryMemoryBenchmarkSmokeCases, R as isKnowledgeMemoryBenchmarkCase, S as runBoundedMemoryLifecycle, U as buildRetrievalEvalDispatch, V as memoryHitToSourceRecord, W as partitionRetrievalScenarios, a as buildKnowledgeBenchmarkScenarios, b as memoryRecoveryDelayMs, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, f as acquireAgentMemoryRunLease, h as DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, i as runMemoryAdapterBenchmark, j as INDUSTRY_MEMORY_BENCHMARKS, l as scoreKnowledgeBenchmarkArtifact, m as AgentMemoryLifecycleUnsafeError, n as parseKnowledgeBenchmarkJsonl, o as knowledgeBenchmarkJudge, p as AgentMemoryLifecycleTimeoutError, q as retrievalRecallJudge, r as parseKnowledgeBenchmarkQrels, s as renderKnowledgeBenchmarkReportMarkdown, t as buildRetrievalBenchmarkCasesFromQrels, u as scoreMemoryBenchmarkArtifact, x as resolveMemoryCleanupTimeoutMs, y as createMemoryExecutionPool, z as createInMemoryBenchmarkAdapter } from "./benchmarks-B_07vX0Q.js";
+import { A as runSerializedKnowledgeOptimization, C as deterministicRng, D as toOffPolicyTrajectory, E as retrievalHoldoutConfigHash, M as assertImmutableRef, O as jsonCandidateCodec, S as applySessionStickyRetrievalHoldout, T as resetRetrievalHoldoutRegistry, _ as createAgentMemoryBranch, a as createNeo4jAgentMemoryAdapter, b as renderMemoryContext, c as runAgentMemoryImprovement, d as compareAgentMemoryLearning, f as runAgentMemoryLearningExperiment, g as buildAgentMemorySequencesFromBenchmarkCases, h as buildAgentMemorySequenceScenarios, i as AgentMemoryWriteInputSchema, j as scenarioContentFingerprint, k as jsonObjectCandidateCodec, l as createGraphitiMemoryAdapter, m as agentMemorySequenceJudge, n as AgentMemoryKindSchema, o as createMem0MemoryAdapter, p as runAgentMemoryExperiment, r as AgentMemoryScopeSchema, s as mem0MemoryAdapterIdentity, t as AgentMemoryHitSchema, u as graphitiMemoryAdapterIdentity, v as forkAgentMemoryBranchSnapshot, w as emitRetrievalHoldoutBypass, x as applyRetrievalHoldout, y as defaultGetMemoryContext } from "./memory-BRGsy2QN.js";
+import { a as buildKnowledgeLexicalIndex, c as tokenizeText, i as searchKnowledgePages, n as reciprocalRankFusion, o as scoreBm25, r as searchKnowledge, s as tokenizeQuery, t as KNOWLEDGE_SEARCH_RETRIEVER_ID } from "./search-Cw6eYfSd.js";
+import { B as createNoopMemoryBenchmarkAdapter, C as sleepForMemoryRecovery, F as buildIndustryRagBenchmarkSmokeCases, G as retrievalConfigFromSurface, H as memoryWriteResultToSourceRecord, I as respondToIndustryMemoryBenchmarkSmokeCase, J as scoreRetrievalArtifact, K as retrievalConfigSurface, L as respondToIndustryRagBenchmarkSmokeCase, M as INDUSTRY_RAG_BENCHMARKS, N as buildFirstPartyMemoryLifecycleBenchmarkCases, P as buildIndustryMemoryBenchmarkSmokeCases, R as isKnowledgeMemoryBenchmarkCase, S as runBoundedMemoryLifecycle, U as buildRetrievalEvalDispatch, V as memoryHitToSourceRecord, W as partitionRetrievalScenarios, a as buildKnowledgeBenchmarkScenarios, b as memoryRecoveryDelayMs, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, f as acquireAgentMemoryRunLease, h as DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, i as runMemoryAdapterBenchmark, j as INDUSTRY_MEMORY_BENCHMARKS, l as scoreKnowledgeBenchmarkArtifact, m as AgentMemoryLifecycleUnsafeError, n as parseKnowledgeBenchmarkJsonl, o as knowledgeBenchmarkJudge, p as AgentMemoryLifecycleTimeoutError, q as retrievalRecallJudge, r as parseKnowledgeBenchmarkQrels, s as renderKnowledgeBenchmarkReportMarkdown, t as buildRetrievalBenchmarkCasesFromQrels, u as scoreMemoryBenchmarkArtifact, x as resolveMemoryCleanupTimeoutMs, y as createMemoryExecutionPool, z as createInMemoryBenchmarkAdapter } from "./benchmarks-B6fCb6AD.js";
 import { IRS_DIMENSION_HINTS, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from "./sources/index.js";
 import { createHash } from "node:crypto";
 import { cp, lstat, mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { agentImprovementActivationResultSchema, agentImprovementActivationSchema, canonicalCandidateDigest, omitTopLevelDigest, sha256DigestSchema } from "@tangle-network/agent-interface";
+import { agentImprovementActivationResultSchema, agentImprovementActivationSchema, canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, omitTopLevelDigest, sha256Bytes, sha256DigestSchema } from "@tangle-network/agent-interface";
 import { acquisitionPlansForKnowledgeGaps, blockingKnowledgeEval, canonicalJson, contentHash, evaluateReleaseConfidence, objectiveEval, scoreKnowledgeReadiness, userQuestionsForKnowledgeGaps, validateRunRecord } from "@tangle-network/agent-eval";
 import { z } from "zod";
 import { surfaceHash } from "@tangle-network/agent-eval/campaign";
@@ -1931,168 +1931,6 @@ async function calibrateRagAnswerJudge(options) {
 	};
 }
 //#endregion
-//#region src/rag-eval/near-duplicates.ts
-/**
-* Detect exact and near-duplicate pages without a model, embedding service, or clock.
-*
-* The detector uses word shingles when prose has enough tokens and Unicode
-* character shingles otherwise. An inverted index proposes candidate pairs;
-* high-document-frequency shingles are ignored so common boilerplate cannot
-* make candidate generation quadratic. Exact normalized copies are always
-* proposed before ordinary shingle candidates, even when every shingle is
-* common. Every limit and sort order is explicit so the same corpus produces
-* the same report on every run.
-*/
-function detectNearDuplicatePages(pages, options = {}) {
-	const threshold = finiteUnitInterval(options.threshold ?? .82, "threshold");
-	const minCharacters = nonNegativeInteger(options.minCharacters ?? 80, "minCharacters");
-	const wordShingleSize = positiveInteger$1(options.wordShingleSize ?? 5, "wordShingleSize");
-	const characterShingleSize = positiveInteger$1(options.characterShingleSize ?? 16, "characterShingleSize");
-	const maxDocumentFrequency = positiveInteger$1(options.maxDocumentFrequency ?? 64, "maxDocumentFrequency");
-	const maxCandidatePairs = positiveInteger$1(options.maxCandidatePairs ?? 25e4, "maxCandidatePairs");
-	const maxReportedPairs = nonNegativeInteger(options.maxReportedPairs ?? 1e3, "maxReportedPairs");
-	const prepared = pages.map((page) => preparePage(page, wordShingleSize, characterShingleSize)).filter((item) => item !== null && item.normalized.length >= minCharacters).sort((left, right) => left.page.path.localeCompare(right.page.path));
-	const candidateKeys = /* @__PURE__ */ new Set();
-	const exactGroups = /* @__PURE__ */ new Map();
-	const byShingle = /* @__PURE__ */ new Map();
-	for (const [index, item] of prepared.entries()) {
-		exactGroups.set(item.normalized, [...exactGroups.get(item.normalized) ?? [], index]);
-		for (const shingle of item.shingles) byShingle.set(shingle, [...byShingle.get(shingle) ?? [], index]);
-	}
-	let truncated = false;
-	const addPair = (left, right) => {
-		if (left === right) return true;
-		const key = pairKey(Math.min(left, right), Math.max(left, right));
-		if (candidateKeys.has(key)) return true;
-		if (candidateKeys.size >= maxCandidatePairs) {
-			truncated = true;
-			return false;
-		}
-		candidateKeys.add(key);
-		return true;
-	};
-	for (const normalized of [...exactGroups.keys()].sort()) if (!addGroupPairs(exactGroups.get(normalized), addPair)) break;
-	if (!truncated) for (const shingle of [...byShingle.keys()].sort()) {
-		const group = byShingle.get(shingle);
-		if (group.length > maxDocumentFrequency) continue;
-		if (!addGroupPairs(group, addPair)) break;
-	}
-	const duplicatePageIndices = /* @__PURE__ */ new Set();
-	const pairs = [];
-	let duplicatePairCount = 0;
-	let comparedPairCount = 0;
-	for (const key of [...candidateKeys].sort(pairKeyOrder)) {
-		const [leftIndex, rightIndex] = parsePairKey(key);
-		const left = prepared[leftIndex];
-		const right = prepared[rightIndex];
-		comparedPairCount += 1;
-		const exact = left.normalized === right.normalized;
-		const overlap = jaccard(left.shingles, right.shingles);
-		if (!exact && overlap.similarity < threshold) continue;
-		duplicatePairCount += 1;
-		duplicatePageIndices.add(leftIndex);
-		duplicatePageIndices.add(rightIndex);
-		if (pairs.length >= maxReportedPairs) {
-			truncated = true;
-			continue;
-		}
-		pairs.push({
-			leftPageId: left.page.id,
-			leftPath: left.page.path,
-			rightPageId: right.page.id,
-			rightPath: right.page.path,
-			similarity: exact ? 1 : round$1(overlap.similarity),
-			intersectionSize: overlap.intersectionSize,
-			unionSize: overlap.unionSize,
-			exact
-		});
-	}
-	pairs.sort((left, right) => right.similarity - left.similarity || left.leftPath.localeCompare(right.leftPath) || left.rightPath.localeCompare(right.rightPath));
-	return {
-		algorithm: "deterministic-shingle-jaccard-v1",
-		threshold,
-		pageCount: pages.length,
-		eligiblePageCount: prepared.length,
-		candidatePairCount: candidateKeys.size,
-		comparedPairCount,
-		duplicatePairCount,
-		duplicatePageCount: duplicatePageIndices.size,
-		duplicatePageRate: prepared.length === 0 ? 0 : round$1(duplicatePageIndices.size / prepared.length),
-		truncated,
-		pairs
-	};
-}
-function preparePage(page, wordShingleSize, characterShingleSize) {
-	const normalized = normalizePageText(`${page.title}\n${page.text}`);
-	if (normalized.length === 0) return null;
-	const words = normalized.match(/[\p{L}\p{N}]+/gu) ?? [];
-	const shingles = words.length >= wordShingleSize + 2 ? sequenceShingles(words, wordShingleSize) : characterShingles(normalized.replace(/\s+/g, ""), characterShingleSize);
-	if (shingles.size === 0) shingles.add(normalized);
-	return {
-		page,
-		normalized,
-		shingles
-	};
-}
-function normalizePageText(value) {
-	return value.normalize("NFKC").toLowerCase().replace(/https?:\/\/\S+/g, "<url>").replace(/\s+/g, " ").trim();
-}
-function sequenceShingles(items, width) {
-	const out = /* @__PURE__ */ new Set();
-	if (items.length < width) return out;
-	for (let index = 0; index <= items.length - width; index += 1) out.add(items.slice(index, index + width).join(""));
-	return out;
-}
-function characterShingles(value, width) {
-	const chars = [...value];
-	const out = /* @__PURE__ */ new Set();
-	if (chars.length < width) return out;
-	for (let index = 0; index <= chars.length - width; index += 1) out.add(chars.slice(index, index + width).join(""));
-	return out;
-}
-function addGroupPairs(group, add) {
-	for (let left = 0; left < group.length; left += 1) for (let right = left + 1; right < group.length; right += 1) if (!add(group[left], group[right])) return false;
-	return true;
-}
-function jaccard(left, right) {
-	const [small, large] = left.size <= right.size ? [left, right] : [right, left];
-	let intersectionSize = 0;
-	for (const item of small) if (large.has(item)) intersectionSize += 1;
-	const unionSize = left.size + right.size - intersectionSize;
-	return {
-		similarity: unionSize === 0 ? 1 : intersectionSize / unionSize,
-		intersectionSize,
-		unionSize
-	};
-}
-function pairKey(left, right) {
-	return `${left}:${right}`;
-}
-function parsePairKey(value) {
-	const [left, right] = value.split(":");
-	return [Number(left), Number(right)];
-}
-function pairKeyOrder(left, right) {
-	const [leftA, leftB] = parsePairKey(left);
-	const [rightA, rightB] = parsePairKey(right);
-	return leftA - rightA || leftB - rightB;
-}
-function finiteUnitInterval(value, name) {
-	if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${name} must be a finite number in [0, 1]`);
-	return value;
-}
-function positiveInteger$1(value, name) {
-	if (!Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer`);
-	return value;
-}
-function nonNegativeInteger(value, name) {
-	if (!Number.isInteger(value) || value < 0) throw new Error(`${name} must be a non-negative integer`);
-	return value;
-}
-function round$1(value) {
-	return Math.round(value * 1e6) / 1e6;
-}
-//#endregion
 //#region src/rag-eval/knowledge-base.ts
 function scoreKnowledgeBaseIndex(index, options = {}) {
 	const validation = validateKnowledgeIndex(index, { strict: options.strict });
@@ -4698,21 +4536,33 @@ function positiveInteger(value, name) {
 */
 var FileSystemSearchProvider = class {
 	root;
+	/** Root-relative directory the provider indexes. */
+	pagesDirectory;
 	index;
+	lexicalIndex;
 	defaultLimit;
 	refreshMode;
 	constructor(options) {
 		this.root = options.root;
+		this.pagesDirectory = normalizePagesDirectory(options.pagesDirectory);
 		this.index = options.index;
 		this.defaultLimit = options.defaultLimit ?? 10;
 		this.refreshMode = options.refresh ?? "manual";
 	}
 	async getIndex(options = {}) {
-		if (this.refreshMode === "always" || options.refresh || !this.index) this.index = await buildKnowledgeIndex(this.root);
+		if (this.refreshMode === "always" || options.refresh || !this.index) {
+			this.index = await buildKnowledgeIndex(this.root, { pagesDirectory: this.pagesDirectory });
+			this.lexicalIndex = void 0;
+		}
 		return this.index;
 	}
 	async search(query, options = {}) {
-		return searchKnowledge(await this.getIndex(options), query, options.limit ?? this.defaultLimit);
+		const index = await this.getIndex(options);
+		if (!this.lexicalIndex) this.lexicalIndex = buildKnowledgeLexicalIndex(index.pages);
+		return searchKnowledge(index, query, {
+			limit: options.limit ?? this.defaultLimit,
+			lexicalIndex: this.lexicalIndex
+		});
 	}
 	async retrieve(query, options = {}) {
 		return (await this.search(query, options)).map(hitFromSearchResult);
@@ -4725,6 +4575,7 @@ var FileSystemSearchProvider = class {
 	}
 	invalidate() {
 		this.index = void 0;
+		this.lexicalIndex = void 0;
 	}
 };
 function createFileSystemSearchProvider(options) {
@@ -4830,6 +4681,77 @@ function buildKey(key) {
 	return `${key.workspaceId}::${key.sourceId}`;
 }
 //#endregion
+//#region src/invalidation-propagation.ts
+/**
+* Invalidation propagation.
+*
+* A page whose own evidence refuted it carries an `invalidation`. That verdict
+* is invisible to a reader who arrives through a citation, so a page that cites
+* a refuted page records which of its citations are refuted. The pass is
+* planned as a diff, so a store already stamped produces no mutation and the
+* pass can run after every grading round.
+*/
+/** Frontmatter field naming the cited pages whose evidence refuted them. */
+const CITES_INVALIDATED_FIELD = "citesInvalidated";
+/**
+* Plan the `citesInvalidated` stamp for every page authored in the target
+* store.
+*
+* Citations resolve over the whole chain, so a page here may be stamped for
+* citing a refuted inherited or shared page. Only `here` pages are stamped: a
+* run does not write the stores it inherits or shares.
+*/
+function planInvalidationPropagation(visiblePages) {
+	if (!Array.isArray(visiblePages)) throw new TypeError("knowledge invalidation propagation requires the visible pages");
+	const invalidatedPageIds = [...new Set(visiblePages.filter((entry) => entry.page.invalidation !== void 0).map((entry) => entry.page.id))].sort();
+	const stamps = [];
+	for (const entry of visiblePages) {
+		if (entry.origin !== "here") continue;
+		const page = entry.page;
+		const refuted = /* @__PURE__ */ new Set();
+		for (const persisted of page.cites ?? []) {
+			const resolution = resolveKnowledgeCitation(visiblePages, parseKnowledgeCitationReference(persisted));
+			if (resolution.resolved?.page.invalidation !== void 0) refuted.add(resolution.resolved.page.id);
+		}
+		const citesInvalidated = [...refuted].sort();
+		const current = idList(page.frontmatter[CITES_INVALIDATED_FIELD]);
+		if (sameOrder(current, citesInvalidated)) continue;
+		stamps.push({
+			page,
+			citesInvalidated,
+			current
+		});
+	}
+	stamps.sort((left, right) => left.page.path.localeCompare(right.page.path));
+	return {
+		invalidatedPageIds,
+		stamps
+	};
+}
+/**
+* Render one plan as a write-block proposal for `applyKnowledgeWriteBlocks`.
+*
+* Only the stamped field changes. The page is rendered through
+* `formatFrontmatter`, so its frontmatter is written in that writer's
+* normalized form.
+*/
+function formatKnowledgeInvalidationProposal(plan) {
+	return plan.stamps.map((stamp) => renderStampedBlock(stamp)).join("\n");
+}
+function renderStampedBlock(stamp) {
+	const frontmatter = { ...stamp.page.frontmatter };
+	if (stamp.citesInvalidated.length === 0) delete frontmatter[CITES_INVALIDATED_FIELD];
+	else frontmatter[CITES_INVALIDATED_FIELD] = [...stamp.citesInvalidated];
+	const content = formatFrontmatter(frontmatter, stamp.page.text);
+	return `---FILE: ${stamp.page.path}---\n${content.replace(/\n+$/, "")}\n---END FILE---`;
+}
+function idList(value) {
+	return (typeof value === "string" ? [value] : Array.isArray(value) ? value : []).filter((item) => typeof item === "string" && item.trim() !== "");
+}
+function sameOrder(left, right) {
+	return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+//#endregion
 //#region src/investment-thesis-set.ts
 /**
 * The eval set. 5 public companies, 5-8 held-out material facts each, every fact
@@ -5954,9 +5876,107 @@ async function runInvestmentThesisTask(input, options) {
 	};
 }
 //#endregion
+//#region src/knowledge-brief.ts
+/**
+* Retrieval briefing.
+*
+* A brief turns "retrieved" from something a run claims into something the
+* infrastructure can prove. It ranks the knowledge visible to a question,
+* renders it with the ids a later write must cite, and returns the ranked
+* results in the shape a retrieval receipt takes, so what an actor was given
+* is recorded rather than asserted.
+*
+* Pure: no clock, no filesystem, no network.
+*/
+/** Pages in a brief when the caller names no limit. */
+const DEFAULT_KNOWLEDGE_BRIEF_LIMIT = 5;
+/**
+* Rank the knowledge one question can see and render it for injection.
+*
+* The same page set produces the same brief on every run: ranking, ordering,
+* and rendering are deterministic, and no field carries a timestamp.
+*/
+function buildKnowledgeBrief(visiblePages, question, options = {}) {
+	if (!Array.isArray(visiblePages)) throw new TypeError("knowledge brief requires the visible pages");
+	if (typeof question !== "string" || question.trim().length === 0) throw new TypeError("knowledge brief question must be a non-empty string");
+	const limit = options.limit ?? 5;
+	const excludeInvalidated = options.excludeInvalidated ?? true;
+	const maxChars = options.maxChars;
+	if (maxChars !== void 0 && (!Number.isInteger(maxChars) || maxChars < 0)) throw new Error(`knowledge brief maxChars must be a non-negative integer, got ${maxChars}`);
+	const originByPage = /* @__PURE__ */ new Map();
+	for (const entry of visiblePages) originByPage.set(entry.page, entry.origin);
+	const ranked = searchKnowledgePages(visiblePages.map((entry) => entry.page), question, {
+		limit,
+		excludeInvalidated,
+		...options.tags === void 0 ? {} : { tags: options.tags },
+		...options.kinds === void 0 ? {} : { kinds: options.kinds }
+	});
+	const hits = [];
+	const lines = [];
+	let length = 0;
+	for (const hit of ranked) {
+		const line = briefLine(hit);
+		const next = length === 0 ? line.length : length + 1 + line.length;
+		if (maxChars !== void 0 && next > maxChars) break;
+		hits.push(hit);
+		lines.push(line);
+		length = next;
+	}
+	return Object.freeze({
+		question: question.trim(),
+		retrieverId: KNOWLEDGE_SEARCH_RETRIEVER_ID,
+		retrieverConfigDigest: canonicalCandidateDigest({
+			limit,
+			excludeInvalidated,
+			tags: options.tags === void 0 ? null : [...options.tags],
+			kinds: options.kinds === void 0 ? null : [...options.kinds],
+			maxChars: maxChars ?? null
+		}),
+		hits: Object.freeze(hits),
+		citationIds: Object.freeze(hits.map((hit) => hit.citationId)),
+		results: Object.freeze(hits.map((hit) => Object.freeze({
+			...hit,
+			origin: originOf(originByPage, hit)
+		}))),
+		text: lines.join("\n")
+	});
+}
+function briefLine(hit) {
+	const snippet = hit.snippet.replace(/\s+/g, " ").trim();
+	return snippet === "" ? `- [${hit.citationId}] ${hit.page.title}` : `- [${hit.citationId}] ${hit.page.title} — ${snippet}`;
+}
+function originOf(originByPage, hit) {
+	const origin = originByPage.get(hit.page);
+	if (origin === void 0) throw new Error(`knowledge brief ranked a page outside the visible chain: ${hit.page.path}`);
+	return origin;
+}
+//#endregion
 //#region src/knowledge-use-receipts.ts
-const KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION = "1.0.0";
+const KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION = "2.0.0";
 const KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM = "rfc8785-sha256";
+/**
+* The visibility snapshot a receipt references could not be obtained, so the
+* result-to-visibility join cannot be proven. This is distinct from a snapshot
+* that loads and fails to match.
+*/
+var KnowledgeVisibilityUnavailableError = class extends Error {
+	reason;
+	snapshotDigest;
+	uri;
+	constructor(input) {
+		const where = input.uri === void 0 ? "" : ` at '${input.uri}'`;
+		const detail = {
+			"no-artifact-reference": "the receipt carries no artifact reference",
+			missing: `no artifact is stored${where}`,
+			"load-failed": `the artifact${where} could not be loaded`
+		}[input.reason];
+		super(`knowledge visibility snapshot ${input.snapshotDigest} is unavailable: ${detail}`, input.cause === void 0 ? void 0 : { cause: input.cause });
+		this.name = "KnowledgeVisibilityUnavailableError";
+		this.reason = input.reason;
+		this.snapshotDigest = input.snapshotDigest;
+		if (input.uri !== void 0) this.uri = input.uri;
+	}
+};
 /** Stable content identity for one exact knowledge page. */
 function knowledgePageDigest(page) {
 	validateKnowledgePage(page);
@@ -5981,7 +6001,7 @@ function createKnowledgeVisibilitySnapshot(visiblePages) {
 		if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an originated page`);
 		const origin = validateOrigin(entry.origin, `knowledge visibility[${position}].origin`);
 		validateKnowledgePage(entry.page);
-		const identity = `${origin}\u0000${entry.page.path}`;
+		const identity = visibilityIdentity(origin, entry.page.path);
 		if (identities.has(identity)) throw new Error(`knowledge visibility repeats path '${entry.page.path}' at origin '${origin}'`);
 		identities.add(identity);
 		return Object.freeze({
@@ -5995,23 +6015,94 @@ function createKnowledgeVisibilitySnapshot(visiblePages) {
 		});
 	});
 	const material = visibilityMaterial(entries);
-	return Object.freeze({
+	const snapshot = Object.freeze({
 		...material,
 		snapshotDigest: canonicalCandidateDigest(material),
 		entries: Object.freeze(entries)
 	});
+	visibilityIndexes.set(snapshot, indexVisibility(snapshot));
+	return snapshot;
 }
-/** Create a retrieval receipt and refuse results that were not in the view. */
+/**
+* Verify a snapshot's schema and canonical digest. The check runs once per
+* snapshot object; later calls with the same object are free.
+*/
+function verifyKnowledgeVisibilitySnapshot(snapshot) {
+	return visibilityIndexOf(snapshot).snapshot;
+}
+/** Canonical bytes of a verified snapshot, for durable storage. */
+function encodeKnowledgeVisibilitySnapshot(snapshot) {
+	const verified = verifyKnowledgeVisibilitySnapshot(snapshot);
+	return canonicalCandidateBytes({
+		schemaVersion: verified.schemaVersion,
+		digestAlgorithm: verified.digestAlgorithm,
+		snapshotDigest: verified.snapshotDigest,
+		entries: visibilityMaterial(verified.entries).entries
+	});
+}
+/** Parse stored snapshot bytes and verify their schema and digest. */
+function decodeKnowledgeVisibilitySnapshot(bytes) {
+	if (!(bytes instanceof Uint8Array)) throw new TypeError("knowledge visibility snapshot bytes must be a Uint8Array");
+	let parsed;
+	try {
+		parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+	} catch (error) {
+		throw new Error(`knowledge visibility snapshot bytes are not JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError("knowledge visibility snapshot must be an object");
+	const candidate = parsed;
+	if (!Array.isArray(candidate.entries)) throw new TypeError("knowledge visibility snapshot entries must be an array");
+	return verifyKnowledgeVisibilitySnapshot(Object.freeze({
+		schemaVersion: candidate.schemaVersion,
+		digestAlgorithm: candidate.digestAlgorithm,
+		snapshotDigest: digest(candidate.snapshotDigest, "knowledge visibility snapshotDigest"),
+		entries: Object.freeze(candidate.entries.map((entry, position) => {
+			if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an object`);
+			const value = entry;
+			if (!Array.isArray(value.sourceIds)) throw new TypeError(`knowledge visibility[${position}].sourceIds must be an array`);
+			return Object.freeze({
+				position: value.position,
+				pageId: value.pageId,
+				origin: value.origin,
+				path: value.path,
+				pageDigest: value.pageDigest,
+				sourceIds: Object.freeze([...value.sourceIds]),
+				invalidated: value.invalidated
+			});
+		}))
+	}));
+}
+/** Locator for snapshot bytes stored at `uri`. */
+function knowledgeVisibilityArtifactRef(input) {
+	if (!input || typeof input !== "object" || !(input.bytes instanceof Uint8Array)) throw new TypeError("knowledge visibility artifact bytes must be a Uint8Array");
+	if (input.bytes.byteLength === 0) throw new TypeError("knowledge visibility artifact bytes must not be empty");
+	return Object.freeze({
+		uri: nonEmpty$1(input.uri, "knowledge visibility artifact uri"),
+		digest: sha256Bytes(input.bytes),
+		byteLength: input.bytes.byteLength
+	});
+}
+/**
+* Create a retrieval receipt over a precomputed snapshot. Every result must
+* occur in the snapshot with the same page id and bytes; the receipt stores the
+* snapshot's reference, not its entries.
+*/
 function createKnowledgeRetrievalReceipt(input) {
 	if (!input || typeof input !== "object") throw new TypeError("knowledge retrieval receipt input is required");
-	const runId = nonEmpty(input.runId, "knowledge retrieval runId");
+	const runId = nonEmpty$1(input.runId, "knowledge retrieval runId");
 	const actorId = optionalText(input.actorId, "knowledge retrieval actorId");
 	const profileDigest = optionalDigest(input.profileDigest, "knowledge retrieval profileDigest");
 	const executionRef = optionalDigest(input.executionRef, "knowledge retrieval executionRef");
-	const query = nonEmpty(input.query, "knowledge retrieval query");
+	const query = nonEmpty$1(input.query, "knowledge retrieval query");
 	const retriever = normalizeRetriever(input.retriever);
-	const visibility = createKnowledgeVisibilitySnapshot(input.visiblePages);
-	const results = normalizeRetrievalResults(input.results, visibility);
+	const index = visibilityIndexOf(input.visibility);
+	const artifact = input.visibilityArtifact === void 0 ? void 0 : normalizeVisibilityArtifact(input.visibilityArtifact, "knowledge retrieval visibilityArtifact");
+	const visibility = Object.freeze({
+		snapshotDigest: index.snapshot.snapshotDigest,
+		pageCount: index.snapshot.entries.length,
+		...artifact === void 0 ? {} : { artifact }
+	});
+	const results = normalizeRetrievalResults(input.results, index);
 	const evidenceRefs = normalizeEvidenceRefs(input.evidenceRefs ?? []);
 	const attributes = normalizeAttributes(input.attributes ?? {});
 	const material = retrievalMaterial({
@@ -6032,33 +6123,82 @@ function createKnowledgeRetrievalReceipt(input) {
 		receiptDigest: canonicalCandidateDigest(material)
 	});
 }
-/** Verify the receipt's schema, internal joins, and canonical digest. */
+/**
+* Verify the receipt's schema, canonical digest, rank continuity, finite
+* scores, and well-formed visibility reference. This proves what the receipt
+* says; it does not prove that the results occur in the referenced snapshot.
+* Use `assertKnowledgeRetrievalMatchesVisibility` or
+* `assertKnowledgeRetrievalMatchesVisibilityArtifact` for that join.
+*/
 function verifyKnowledgeRetrievalReceipt(receipt) {
 	if (!receipt || typeof receipt !== "object") throw new TypeError("knowledge retrieval receipt is required");
-	if (receipt.schemaVersion !== "1.0.0") throw new Error(`unsupported knowledge retrieval schemaVersion '${receipt.schemaVersion}'`);
+	assertSchemaVersion(receipt.schemaVersion, "knowledge retrieval");
 	if (receipt.kind !== "knowledge-retrieval") throw new Error(`knowledge retrieval receipt kind must be 'knowledge-retrieval'`);
 	if (receipt.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge retrieval digestAlgorithm '${receipt.digestAlgorithm}'`);
-	if (canonicalCandidateDigest(visibilityMaterial(receipt.visibility.entries)) !== receipt.visibility.snapshotDigest) throw new Error("knowledge retrieval visibility snapshot digest mismatch");
-	validateReceiptResults(receipt.results, receipt.visibility);
+	const visibility = normalizeVisibilityRef(receipt.visibility);
+	validateReceiptResultShape(receipt.results, visibility.pageCount);
 	if (canonicalCandidateDigest(retrievalMaterial({
 		createdAt: isoTimestamp(receipt.createdAt, "knowledge retrieval createdAt"),
-		runId: nonEmpty(receipt.runId, "knowledge retrieval runId"),
+		runId: nonEmpty$1(receipt.runId, "knowledge retrieval runId"),
 		actorId: optionalText(receipt.actorId, "knowledge retrieval actorId"),
 		profileDigest: optionalDigest(receipt.profileDigest, "knowledge retrieval profileDigest"),
 		executionRef: optionalDigest(receipt.executionRef, "knowledge retrieval executionRef"),
-		query: nonEmpty(receipt.query, "knowledge retrieval query"),
+		query: nonEmpty$1(receipt.query, "knowledge retrieval query"),
 		retriever: normalizeRetriever(receipt.retriever),
-		visibility: receipt.visibility,
+		visibility,
 		results: receipt.results,
 		evidenceRefs: normalizeEvidenceRefs(receipt.evidenceRefs),
 		attributes: normalizeAttributes(receipt.attributes)
 	})) !== receipt.receiptDigest) throw new Error("knowledge retrieval receipt digest mismatch");
 	return receipt;
 }
-/** Prove that a receipt still describes the supplied visibility bytes. */
-function assertKnowledgeRetrievalMatchesVisibility(receipt, visiblePages) {
+/**
+* Prove that the receipt references exactly this snapshot and that every
+* returned result occurs in it with the same page id and bytes. Pass the
+* snapshot itself, or the originated pages to snapshot them first.
+*/
+function assertKnowledgeRetrievalMatchesVisibility(receipt, visibility) {
+	verifyKnowledgeRetrievalReceipt(receipt);
+	assertReceiptJoinsVisibility(receipt, visibilityIndexOf(Array.isArray(visibility) ? createKnowledgeVisibilitySnapshot(visibility) : visibility));
+}
+/**
+* Load the snapshot artifact the receipt references, prove the stored bytes
+* match the reference, and prove every returned result occurs in the decoded
+* snapshot. A snapshot that cannot be obtained raises
+* `KnowledgeVisibilityUnavailableError`; it is never treated as empty.
+*/
+async function assertKnowledgeRetrievalMatchesVisibilityArtifact(receipt, loadArtifact) {
 	verifyKnowledgeRetrievalReceipt(receipt);
-	if (createKnowledgeVisibilitySnapshot(visiblePages).snapshotDigest !== receipt.visibility.snapshotDigest) throw new Error("knowledge retrieval receipt does not match the supplied visibility snapshot");
+	if (typeof loadArtifact !== "function") throw new TypeError("knowledge visibility artifact loader must be a function");
+	const reference = receipt.visibility;
+	if (reference.artifact === void 0) throw new KnowledgeVisibilityUnavailableError({
+		reason: "no-artifact-reference",
+		snapshotDigest: reference.snapshotDigest
+	});
+	const artifact = reference.artifact;
+	let bytes;
+	try {
+		bytes = await loadArtifact(artifact);
+	} catch (error) {
+		throw new KnowledgeVisibilityUnavailableError({
+			reason: "load-failed",
+			snapshotDigest: reference.snapshotDigest,
+			uri: artifact.uri,
+			cause: error
+		});
+	}
+	if (bytes === void 0) throw new KnowledgeVisibilityUnavailableError({
+		reason: "missing",
+		snapshotDigest: reference.snapshotDigest,
+		uri: artifact.uri
+	});
+	if (!(bytes instanceof Uint8Array)) throw new TypeError(`knowledge visibility artifact '${artifact.uri}' loaded a non-byte value`);
+	if (bytes.byteLength !== artifact.byteLength) throw new Error(`knowledge visibility artifact '${artifact.uri}' byteLength mismatch: expected ${artifact.byteLength}, observed ${bytes.byteLength}`);
+	if (sha256Bytes(bytes) !== artifact.digest) throw new Error(`knowledge visibility artifact '${artifact.uri}' digest mismatch`);
+	const snapshot = decodeKnowledgeVisibilitySnapshot(bytes);
+	if (snapshot.snapshotDigest !== reference.snapshotDigest) throw new Error(`knowledge visibility artifact '${artifact.uri}' holds snapshot ${snapshot.snapshotDigest}, not ${reference.snapshotDigest}`);
+	assertReceiptJoinsVisibility(receipt, visibilityIndexOf(snapshot));
+	return snapshot;
 }
 /** Create a downstream-use receipt for one exact ranked result. */
 function createKnowledgeUseReceipt(input) {
@@ -6095,7 +6235,7 @@ function createKnowledgeUseReceipt(input) {
 function verifyKnowledgeUseReceipt(receipt, retrieval) {
 	if (!receipt || typeof receipt !== "object") throw new TypeError("knowledge use receipt is required");
 	const verifiedRetrieval = verifyKnowledgeRetrievalReceipt(retrieval);
-	if (receipt.schemaVersion !== "1.0.0") throw new Error(`unsupported knowledge use schemaVersion '${receipt.schemaVersion}'`);
+	assertSchemaVersion(receipt.schemaVersion, "knowledge use");
 	if (receipt.kind !== "knowledge-use") throw new Error(`knowledge use receipt kind must be 'knowledge-use'`);
 	if (receipt.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge use digestAlgorithm '${receipt.digestAlgorithm}'`);
 	if (receipt.retrievalReceiptDigest !== verifiedRetrieval.receiptDigest) throw new Error("knowledge use receipt references a different retrieval receipt");
@@ -6112,19 +6252,94 @@ function verifyKnowledgeUseReceipt(receipt, retrieval) {
 	})) !== receipt.receiptDigest) throw new Error("knowledge use receipt digest mismatch");
 	return receipt;
 }
+/** Record that one retrieval led to no use, with no rank to select. */
+function createKnowledgeRetrievalDisposition(input) {
+	if (!input || typeof input !== "object") throw new TypeError("knowledge retrieval disposition input is required");
+	const material = dispositionMaterial({
+		createdAt: isoTimestamp(input.createdAt, "knowledge retrieval disposition createdAt"),
+		retrieval: verifyKnowledgeRetrievalReceipt(input.retrieval),
+		relation: validateDispositionRelation(input.relation),
+		consumer: normalizeConsumer(input.consumer),
+		evidenceRefs: normalizeEvidenceRefs(input.evidenceRefs ?? []),
+		attributes: normalizeAttributes(input.attributes ?? {})
+	});
+	return Object.freeze({
+		...material,
+		receiptDigest: canonicalCandidateDigest(material)
+	});
+}
+/** Verify one disposition against the exact retrieval that authorized it. */
+function verifyKnowledgeRetrievalDisposition(disposition, retrieval) {
+	if (!disposition || typeof disposition !== "object") throw new TypeError("knowledge retrieval disposition is required");
+	const verifiedRetrieval = verifyKnowledgeRetrievalReceipt(retrieval);
+	assertSchemaVersion(disposition.schemaVersion, "knowledge retrieval disposition");
+	if (disposition.kind !== "knowledge-retrieval-disposition") throw new Error(`knowledge retrieval disposition kind must be 'knowledge-retrieval-disposition'`);
+	if (disposition.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge retrieval disposition digestAlgorithm '${disposition.digestAlgorithm}'`);
+	if (disposition.retrievalReceiptDigest !== verifiedRetrieval.receiptDigest) throw new Error("knowledge retrieval disposition references a different retrieval receipt");
+	if (canonicalCandidateDigest(dispositionMaterial({
+		createdAt: isoTimestamp(disposition.createdAt, "knowledge retrieval disposition createdAt"),
+		retrieval: verifiedRetrieval,
+		relation: validateDispositionRelation(disposition.relation),
+		consumer: normalizeConsumer(disposition.consumer),
+		evidenceRefs: normalizeEvidenceRefs(disposition.evidenceRefs),
+		attributes: normalizeAttributes(disposition.attributes)
+	})) !== disposition.receiptDigest) throw new Error("knowledge retrieval disposition digest mismatch");
+	return disposition;
+}
+const visibilityIndexes = /* @__PURE__ */ new WeakMap();
+function visibilityIndexOf(snapshot) {
+	if (!snapshot || typeof snapshot !== "object") throw new TypeError("knowledge visibility snapshot is required");
+	const cached = visibilityIndexes.get(snapshot);
+	if (cached !== void 0) return cached;
+	assertSchemaVersion(snapshot.schemaVersion, "knowledge visibility");
+	if (snapshot.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge visibility digestAlgorithm '${snapshot.digestAlgorithm}'`);
+	if (!Array.isArray(snapshot.entries)) throw new TypeError("knowledge visibility snapshot entries must be an array");
+	if (canonicalCandidateDigest(visibilityMaterial(snapshot.entries)) !== digest(snapshot.snapshotDigest, "knowledge visibility snapshotDigest")) throw new Error("knowledge visibility snapshot digest mismatch");
+	const index = indexVisibility(snapshot);
+	visibilityIndexes.set(snapshot, index);
+	return index;
+}
+function indexVisibility(snapshot) {
+	const byIdentity = /* @__PURE__ */ new Map();
+	for (const entry of snapshot.entries) {
+		const identity = visibilityIdentity(entry.origin, entry.path);
+		if (byIdentity.has(identity)) throw new Error(`knowledge visibility repeats path '${entry.path}' at origin '${entry.origin}'`);
+		byIdentity.set(identity, entry);
+	}
+	return {
+		snapshot,
+		byIdentity
+	};
+}
+function visibilityIdentity(origin, path) {
+	return `${origin}\u0000${path}`;
+}
+function assertReceiptJoinsVisibility(receipt, index) {
+	if (index.snapshot.snapshotDigest !== receipt.visibility.snapshotDigest || index.snapshot.entries.length !== receipt.visibility.pageCount) throw new Error("knowledge retrieval receipt does not match the supplied visibility snapshot");
+	for (const result of receipt.results) {
+		const entry = index.byIdentity.get(visibilityIdentity(result.origin, result.path));
+		if (!entry || entry.pageId !== result.pageId || entry.pageDigest !== result.pageDigest) throw new Error(`knowledge retrieval result rank ${result.rank} is not in the visibility snapshot`);
+	}
+}
+function assertSchemaVersion(value, label) {
+	if (value === "2.0.0") return;
+	throw new Error(`unsupported ${label} schemaVersion '${String(value)}'${value === "1.0.0" ? "; 1.0.0 records embed the visibility snapshot and have no reader, create a 2.0.0 record from the snapshot" : ""}`);
+}
 function visibilityMaterial(entries) {
 	return {
 		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
 		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
 		entries: entries.map((entry, position) => {
+			if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an object`);
 			if (entry.position !== position) throw new Error(`knowledge visibility position mismatch: expected ${position}, observed ${entry.position}`);
+			if (!Array.isArray(entry.sourceIds)) throw new TypeError(`knowledge visibility[${position}].sourceIds must be an array`);
 			return {
 				position,
-				pageId: nonEmpty(entry.pageId, `knowledge visibility[${position}].pageId`),
+				pageId: nonEmpty$1(entry.pageId, `knowledge visibility[${position}].pageId`),
 				origin: validateOrigin(entry.origin, `knowledge visibility[${position}].origin`),
-				path: nonEmpty(entry.path, `knowledge visibility[${position}].path`),
+				path: nonEmpty$1(entry.path, `knowledge visibility[${position}].path`),
 				pageDigest: digest(entry.pageDigest, `knowledge visibility[${position}].pageDigest`),
-				sourceIds: entry.sourceIds.map((sourceId, sourceIndex) => nonEmpty(sourceId, `knowledge visibility[${position}].sourceIds[${sourceIndex}]`)),
+				sourceIds: entry.sourceIds.map((sourceId, sourceIndex) => nonEmpty$1(sourceId, `knowledge visibility[${position}].sourceIds[${sourceIndex}]`)),
 				invalidated: Boolean(entry.invalidated)
 			};
 		})
@@ -6148,17 +6363,27 @@ function retrievalMaterial(input) {
 		attributes: input.attributes
 	};
 }
+/**
+* The actor identity a downstream record inherits from the retrieval that
+* authorized it. A record that re-declared these could disagree with the
+* receipt it references.
+*/
+function retrievalIdentity(retrieval) {
+	return {
+		runId: retrieval.runId,
+		...retrieval.actorId === void 0 ? {} : { actorId: retrieval.actorId },
+		...retrieval.profileDigest === void 0 ? {} : { profileDigest: retrieval.profileDigest },
+		...retrieval.executionRef === void 0 ? {} : { executionRef: retrieval.executionRef },
+		retrievalReceiptDigest: retrieval.receiptDigest
+	};
+}
 function useMaterial(input) {
 	return {
 		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
 		kind: "knowledge-use",
 		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
 		createdAt: input.createdAt,
-		runId: input.retrieval.runId,
-		...input.retrieval.actorId === void 0 ? {} : { actorId: input.retrieval.actorId },
-		...input.retrieval.profileDigest === void 0 ? {} : { profileDigest: input.retrieval.profileDigest },
-		...input.retrieval.executionRef === void 0 ? {} : { executionRef: input.retrieval.executionRef },
-		retrievalReceiptDigest: input.retrieval.receiptDigest,
+		...retrievalIdentity(input.retrieval),
 		used: input.used,
 		relation: input.relation,
 		consumer: input.consumer,
@@ -6166,28 +6391,42 @@ function useMaterial(input) {
 		attributes: input.attributes
 	};
 }
-function normalizeRetrievalResults(results, visibility) {
+function dispositionMaterial(input) {
+	return {
+		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
+		kind: "knowledge-retrieval-disposition",
+		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
+		createdAt: input.createdAt,
+		...retrievalIdentity(input.retrieval),
+		relation: input.relation,
+		consumer: input.consumer,
+		evidenceRefs: input.evidenceRefs,
+		attributes: input.attributes
+	};
+}
+function validateDispositionRelation(value) {
+	if (value !== "irrelevant" && value !== "no-use") throw new TypeError(`knowledge retrieval disposition relation is invalid: ${String(value)}`);
+	return value;
+}
+function normalizeRetrievalResults(results, index) {
 	if (!Array.isArray(results)) throw new TypeError("knowledge retrieval results must be an array");
-	const visible = new Map(visibility.entries.map((entry) => [`${entry.origin}\u0000${entry.path}`, entry]));
 	const seenRanks = /* @__PURE__ */ new Set();
 	const seenPages = /* @__PURE__ */ new Set();
-	const normalized = results.map((result, index) => {
-		if (!result || typeof result !== "object") throw new TypeError(`knowledge retrieval results[${index}] must be an object`);
-		if (!Number.isSafeInteger(result.rank) || result.rank < 1) throw new TypeError(`knowledge retrieval results[${index}].rank must be positive`);
+	const normalized = results.map((result, position) => {
+		if (!result || typeof result !== "object") throw new TypeError(`knowledge retrieval results[${position}] must be an object`);
+		if (!Number.isSafeInteger(result.rank) || result.rank < 1) throw new TypeError(`knowledge retrieval results[${position}].rank must be positive`);
 		if (seenRanks.has(result.rank)) throw new Error(`knowledge retrieval repeats rank ${result.rank}`);
 		seenRanks.add(result.rank);
-		const origin = validateOrigin(result.origin, `knowledge retrieval results[${index}].origin`);
+		const origin = validateOrigin(result.origin, `knowledge retrieval results[${position}].origin`);
 		validateKnowledgePage(result.page);
-		const key = `${origin}\u0000${result.page.path}`;
-		if (seenPages.has(key)) throw new Error(`knowledge retrieval repeats page '${result.page.path}' at origin '${origin}'`);
-		seenPages.add(key);
-		const visibleEntry = visible.get(key);
+		const identity = visibilityIdentity(origin, result.page.path);
+		if (seenPages.has(identity)) throw new Error(`knowledge retrieval repeats page '${result.page.path}' at origin '${origin}'`);
+		seenPages.add(identity);
+		const visibleEntry = index.byIdentity.get(identity);
 		if (!visibleEntry) throw new Error(`knowledge retrieval result '${result.page.path}' at origin '${origin}' was not visible`);
 		const pageDigest = knowledgePageDigest(result.page);
 		if (visibleEntry.pageId !== result.page.id || visibleEntry.pageDigest !== pageDigest) throw new Error(`knowledge retrieval result '${result.page.path}' does not match its visibility snapshot`);
-		finite(result.rrfScore, `knowledge retrieval results[${index}].rrfScore`);
-		finite(result.normalizedScore, `knowledge retrieval results[${index}].normalizedScore`);
-		if (result.normalizedScore < 0 || result.normalizedScore > 1) throw new TypeError(`knowledge retrieval results[${index}].normalizedScore must be in [0,1]`);
+		assertResultScores(result, position);
 		return Object.freeze({
 			rank: result.rank,
 			pageId: result.page.id,
@@ -6197,36 +6436,68 @@ function normalizeRetrievalResults(results, visibility) {
 			rrfScore: result.rrfScore,
 			normalizedScore: result.normalizedScore,
 			snippet: typeof result.snippet === "string" ? result.snippet : "",
-			reasons: Object.freeze(result.reasons.map((reason, reasonIndex) => nonEmpty(reason, `knowledge retrieval results[${index}].reasons[${reasonIndex}]`)))
+			reasons: Object.freeze(result.reasons.map((reason, reasonIndex) => nonEmpty$1(reason, `knowledge retrieval results[${position}].reasons[${reasonIndex}]`)))
 		});
 	});
 	normalized.sort((left, right) => left.rank - right.rank);
-	normalized.forEach((result, index) => {
-		if (result.rank !== index + 1) throw new Error(`knowledge retrieval ranks must be contiguous from 1; expected ${index + 1}, observed ${result.rank}`);
-	});
+	assertContiguousRanks(normalized);
 	return Object.freeze(normalized);
 }
-function validateReceiptResults(results, visibility) {
-	const visible = new Map(visibility.entries.map((entry) => [`${entry.origin}\u0000${entry.path}`, entry]));
+function validateReceiptResultShape(results, pageCount) {
+	if (!Array.isArray(results)) throw new TypeError("knowledge retrieval results must be an array");
+	if (results.length > pageCount) throw new Error(`knowledge retrieval returns ${results.length} results from ${pageCount} visible pages`);
+	assertContiguousRanks(results);
 	const seen = /* @__PURE__ */ new Set();
-	results.forEach((result, index) => {
-		if (result.rank !== index + 1) throw new Error(`knowledge retrieval ranks must be contiguous from 1; expected ${index + 1}, observed ${result.rank}`);
-		const key = `${validateOrigin(result.origin, `knowledge retrieval results[${index}].origin`)}\u0000${nonEmpty(result.path, `knowledge retrieval results[${index}].path`)}`;
-		if (seen.has(key)) throw new Error(`knowledge retrieval repeats visible page '${result.path}'`);
-		seen.add(key);
-		const entry = visible.get(key);
-		if (!entry || entry.pageId !== result.pageId || entry.pageDigest !== result.pageDigest) throw new Error(`knowledge retrieval result rank ${result.rank} is not in the visibility snapshot`);
-		finite(result.rrfScore, `knowledge retrieval results[${index}].rrfScore`);
-		finite(result.normalizedScore, `knowledge retrieval results[${index}].normalizedScore`);
-		if (result.normalizedScore < 0 || result.normalizedScore > 1) throw new TypeError(`knowledge retrieval results[${index}].normalizedScore must be in [0,1]`);
-		if (!Array.isArray(result.reasons)) throw new TypeError(`knowledge retrieval results[${index}].reasons must be an array`);
+	results.forEach((result, position) => {
+		if (!result || typeof result !== "object") throw new TypeError(`knowledge retrieval results[${position}] must be an object`);
+		const identity = visibilityIdentity(validateOrigin(result.origin, `knowledge retrieval results[${position}].origin`), nonEmpty$1(result.path, `knowledge retrieval results[${position}].path`));
+		if (seen.has(identity)) throw new Error(`knowledge retrieval repeats visible page '${result.path}'`);
+		seen.add(identity);
+		nonEmpty$1(result.pageId, `knowledge retrieval results[${position}].pageId`);
+		digest(result.pageDigest, `knowledge retrieval results[${position}].pageDigest`);
+		assertResultScores(result, position);
+		if (typeof result.snippet !== "string") throw new TypeError(`knowledge retrieval results[${position}].snippet must be a string`);
+		if (!Array.isArray(result.reasons)) throw new TypeError(`knowledge retrieval results[${position}].reasons must be an array`);
+	});
+}
+/**
+* Ranks a retriever returned: one-based, unique, and contiguous, so a receipt
+* cannot hide a result by omitting its rank.
+*/
+function assertContiguousRanks(results) {
+	results.forEach((result, position) => {
+		if (result.rank !== position + 1) throw new Error(`knowledge retrieval ranks must be contiguous from 1; expected ${position + 1}, observed ${result.rank}`);
+	});
+}
+/** Scores a receipt may carry: finite, with the normalized score inside [0,1]. */
+function assertResultScores(result, position) {
+	finite(result.rrfScore, `knowledge retrieval results[${position}].rrfScore`);
+	finite(result.normalizedScore, `knowledge retrieval results[${position}].normalizedScore`);
+	if (result.normalizedScore < 0 || result.normalizedScore > 1) throw new TypeError(`knowledge retrieval results[${position}].normalizedScore must be in [0,1]`);
+}
+function normalizeVisibilityRef(input) {
+	if (!input || typeof input !== "object") throw new TypeError("knowledge retrieval visibility reference is required");
+	if (!Number.isSafeInteger(input.pageCount) || input.pageCount < 0) throw new TypeError("knowledge retrieval visibility pageCount must be a non-negative integer");
+	return Object.freeze({
+		snapshotDigest: digest(input.snapshotDigest, "knowledge retrieval visibility snapshotDigest"),
+		pageCount: input.pageCount,
+		...input.artifact === void 0 ? {} : { artifact: normalizeVisibilityArtifact(input.artifact, "knowledge retrieval visibility artifact") }
+	});
+}
+function normalizeVisibilityArtifact(input, label) {
+	if (!input || typeof input !== "object") throw new TypeError(`${label} must be an object`);
+	if (!Number.isSafeInteger(input.byteLength) || input.byteLength < 1) throw new TypeError(`${label} byteLength must be a positive integer`);
+	return Object.freeze({
+		uri: nonEmpty$1(input.uri, `${label} uri`),
+		digest: digest(input.digest, `${label} digest`),
+		byteLength: input.byteLength
 	});
 }
 function normalizeRetriever(input) {
 	if (!input || typeof input !== "object") throw new TypeError("knowledge retriever identity is required");
 	return Object.freeze({
-		id: nonEmpty(input.id, "knowledge retriever id"),
-		version: nonEmpty(input.version, "knowledge retriever version"),
+		id: nonEmpty$1(input.id, "knowledge retriever id"),
+		version: nonEmpty$1(input.version, "knowledge retriever version"),
 		configDigest: digest(input.configDigest, "knowledge retriever configDigest")
 	});
 }
@@ -6242,7 +6513,7 @@ function normalizeConsumer(input) {
 	].includes(input.kind)) throw new TypeError(`knowledge consumer kind is invalid: ${String(input.kind)}`);
 	return Object.freeze({
 		kind: input.kind,
-		uri: nonEmpty(input.uri, "knowledge consumer uri"),
+		uri: nonEmpty$1(input.uri, "knowledge consumer uri"),
 		...input.digest === void 0 ? {} : { digest: digest(input.digest, "knowledge consumer digest") }
 	});
 }
@@ -6259,8 +6530,8 @@ function normalizeEvidenceRefs(values) {
 		if (!value || typeof value !== "object" || !allowed.includes(value.kind)) throw new TypeError(`knowledge evidenceRefs[${index}].kind is invalid`);
 		return Object.freeze({
 			kind: value.kind,
-			uri: nonEmpty(value.uri, `knowledge evidenceRefs[${index}].uri`),
-			...value.excerpt === void 0 ? {} : { excerpt: nonEmpty(value.excerpt, `knowledge evidenceRefs[${index}].excerpt`) }
+			uri: nonEmpty$1(value.uri, `knowledge evidenceRefs[${index}].uri`),
+			...value.excerpt === void 0 ? {} : { excerpt: nonEmpty$1(value.excerpt, `knowledge evidenceRefs[${index}].excerpt`) }
 		});
 	}));
 }
@@ -6268,7 +6539,7 @@ function normalizeAttributes(input) {
 	if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError("knowledge receipt attributes must be an object");
 	const normalized = {};
 	for (const [key, value] of Object.entries(input)) {
-		const name = nonEmpty(key, "knowledge receipt attribute key");
+		const name = nonEmpty$1(key, "knowledge receipt attribute key");
 		if (value !== null && typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") throw new TypeError(`knowledge receipt attribute '${name}' has an unsupported value`);
 		if (typeof value === "number") finite(value, `knowledge receipt attribute '${name}'`);
 		normalized[name] = value;
@@ -6287,9 +6558,9 @@ function validateUseRelation(value) {
 }
 function validateKnowledgePage(page) {
 	if (!page || typeof page !== "object") throw new TypeError("knowledge page must be an object");
-	nonEmpty(page.id, "knowledge page id");
-	nonEmpty(page.path, "knowledge page path");
-	nonEmpty(page.title, "knowledge page title");
+	nonEmpty$1(page.id, "knowledge page id");
+	nonEmpty$1(page.path, "knowledge page path");
+	nonEmpty$1(page.title, "knowledge page title");
 	if (typeof page.text !== "string") throw new TypeError("knowledge page text must be a string");
 	if (!page.frontmatter || typeof page.frontmatter !== "object" || Array.isArray(page.frontmatter)) throw new TypeError("knowledge page frontmatter must be an object");
 	for (const [name, values] of [
@@ -6311,12 +6582,12 @@ function digest(value, label) {
 function optionalDigest(value, label) {
 	return value === void 0 ? void 0 : digest(value, label);
 }
-function nonEmpty(value, label) {
+function nonEmpty$1(value, label) {
 	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${label} must be a non-empty string`);
 	return value.trim();
 }
 function optionalText(value, label) {
-	return value === void 0 ? void 0 : nonEmpty(value, label);
+	return value === void 0 ? void 0 : nonEmpty$1(value, label);
 }
 function finite(value, label) {
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${label} must be a finite number`);
@@ -6327,6 +6598,285 @@ function isoTimestamp(value, label) {
 	return date.toISOString();
 }
 //#endregion
+//#region src/knowledge-tools.ts
+const searchInput = z.object({
+	question: z.string().min(1),
+	limit: z.int().min(1).max(50).optional()
+});
+const readInput = z.object({ pageId: z.string().min(1) });
+const recordInput = z.object({ proposal: z.string().min(1) });
+const resolveInput = z.object({ references: z.array(z.string().min(1)).min(1) });
+/**
+* The four tools an agent needs to use a knowledge store: search, read, record,
+* resolve.
+*/
+function createKnowledgeTools(options) {
+	const { stores, runId } = options;
+	if (!stores || typeof stores.loadChain !== "function") throw new TypeError("knowledge tools require run-scoped stores");
+	if (typeof runId !== "string" || runId.trim().length === 0) throw new TypeError("knowledge tools require a runId");
+	if (typeof options.retrieverVersion !== "string" || options.retrieverVersion.trim() === "") throw new TypeError("knowledge tools require the running retrieverVersion");
+	const pages = options.pagesDirectory === void 0 ? {} : { pagesDirectory: options.pagesDirectory };
+	return [
+		tool("knowledge_search", "Search the knowledge this run can see and return a brief with the ids to cite.", searchInput, async (input) => {
+			const chain = await stores.loadChain(runId);
+			const brief = buildKnowledgeBrief(chain, input.question, {
+				...options.brief,
+				...input.limit === void 0 ? {} : { limit: input.limit }
+			});
+			const receipt = createKnowledgeRetrievalReceipt({
+				runId,
+				...options.actorId === void 0 ? {} : { actorId: options.actorId },
+				query: brief.question,
+				retriever: {
+					id: brief.retrieverId,
+					version: options.retrieverVersion,
+					configDigest: brief.retrieverConfigDigest
+				},
+				visibility: createKnowledgeVisibilitySnapshot(chain),
+				results: brief.results,
+				createdAt: options.now?.()
+			});
+			await options.recordRetrieval?.(receipt);
+			return {
+				text: brief.text,
+				citationIds: brief.citationIds,
+				retrievalReceiptDigest: receipt.receiptDigest,
+				receipt
+			};
+		}),
+		tool("knowledge_read", "Read one page by its id, optionally qualified with here::, shared:: or inherited:<runId>::.", readInput, async (input) => {
+			const resolution = resolveKnowledgeCitation(await stores.loadChain(runId), parseKnowledgeCitationReference(input.pageId));
+			return {
+				status: resolution.status,
+				page: resolution.resolved === void 0 ? null : {
+					pageId: resolution.resolved.page.id,
+					origin: resolution.resolved.origin,
+					path: resolution.resolved.page.path,
+					title: resolution.resolved.page.title,
+					text: resolution.resolved.page.text
+				},
+				candidates: resolution.candidates.map((candidate) => ({
+					pageId: candidate.pageId,
+					origin: candidate.origin,
+					path: candidate.page.path
+				}))
+			};
+		}),
+		tool("knowledge_record", "Write pages into the store of this run from ---FILE: ...--- blocks.", recordInput, async (input) => {
+			const intake = options.intake;
+			return applyKnowledgeWriteBlocks(stores.storePath(runId), input.proposal, {
+				...pages,
+				...intake === void 0 ? {} : { intake: {
+					...intake,
+					inheritedPages: await inheritedOf(stores, runId)
+				} }
+			});
+		}),
+		tool("knowledge_resolve", "Resolve page ids against everything this run can see, without hiding an ambiguity.", resolveInput, async (input) => ({ resolutions: (await resolveRunScopedCitations(stores, runId, input.references.map((reference) => parseKnowledgeCitationReference(reference)))).map((resolution) => ({
+			pageId: resolution.reference.pageId,
+			...resolution.reference.origin === void 0 ? {} : { origin: resolution.reference.origin },
+			status: resolution.status,
+			candidates: resolution.candidates.map((candidate) => ({
+				pageId: candidate.pageId,
+				origin: candidate.origin,
+				path: candidate.page.path
+			}))
+		})) }))
+	];
+}
+/** Everything the run can see except what it wrote, which the write path reads itself. */
+async function inheritedOf(stores, runId) {
+	return (await stores.loadChain(runId)).filter((entry) => entry.origin !== "here");
+}
+function tool(name, description, inputSchema, handler) {
+	return {
+		name,
+		description,
+		inputSchema,
+		inputSchemaJson: z.toJSONSchema(inputSchema),
+		handler: (input) => handler(inputSchema.parse(input))
+	};
+}
+//#endregion
+//#region src/promotion.ts
+/**
+* Run-scope to shared-scope promotion.
+*
+* A run writes only its own store. Knowledge reaches the curated shared store
+* through this call and no other, and every promotion leaves a record naming
+* the source run, the promoted bytes, the support carried with them, the actor,
+* and the reason.
+*
+* A claim's cited support travels with it. Promoting a claim while leaving the
+* run-local pages it cites behind is what turns a resolved citation into a
+* dangling one, so the closure of cited pages is carried and the promotion is
+* refused when any citation would not resolve in the target.
+*/
+const KNOWLEDGE_PROMOTION_SCHEMA_VERSION = "1.0.0";
+const KNOWLEDGE_PROMOTION_DIGEST_ALGORITHM = "rfc8785-sha256";
+/** Root-relative directory holding one JSON record per promotion. */
+const KNOWLEDGE_PROMOTIONS_DIRECTORY = ".agent-knowledge/promotions";
+/** A promotion that cannot be performed exactly as asked. */
+var KnowledgePromotionError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "KnowledgePromotionError";
+		this.code = code;
+	}
+};
+/**
+* Promote pages a run authored into the shared store, with their cited support.
+*
+* Support keeps its own evidence fields exactly as written, so a promoted claim
+* cannot inherit a confidence its support does not carry. Pages travel as the
+* bytes their store holds.
+*
+* Re-running the same promotion is safe: unchanged pages produce no file
+* mutation and the record is content-addressed, so it lands at the same path
+* with the same bytes.
+*/
+async function promoteRunScopedPages(stores, runId, options) {
+	const pagesDirectory = normalizePagesDirectory(options.pagesDirectory);
+	const sharedRoot = nonEmpty(options.sharedRoot, "promotion sharedRoot");
+	const actor = nonEmpty(options.actor, "promotion actor");
+	const reason = nonEmpty(options.reason, "promotion reason");
+	if (!Array.isArray(options.pageIds) || options.pageIds.length === 0) throw new TypeError("promotion pageIds must name at least one page");
+	const travellers = collectTravellers(await stores.loadChain(runId), options.pageIds);
+	await initKnowledgeBase(sharedRoot);
+	return withKnowledgeMutation(sharedRoot, async (lock) => {
+		const existing = await loadKnowledgePages(sharedRoot, { pagesDirectory });
+		assertNoIdentityConflict(travellers, existing);
+		const promotedPaths = new Set(travellers.map((traveller) => traveller.entry.page.path));
+		assertKnowledgeCitationsResolved(originatedPages([...existing.filter((page) => !promotedPaths.has(page.path)), ...travellers.map((traveller) => traveller.entry.page)], "shared"), travellers.flatMap((traveller) => (traveller.entry.page.cites ?? []).map((persisted) => parseKnowledgeCitationReference(persisted))));
+		const mutations = await Promise.all(travellers.map(async (traveller) => ({
+			path: traveller.entry.page.path,
+			content: await readPageBytes(stores, runId, traveller.entry)
+		})));
+		await commitKnowledgeFileMutations({
+			root: sharedRoot,
+			transactionRoot: lock.transactionRoot,
+			purpose: `knowledge-promotion:${runId}`,
+			mutations,
+			pagesDirectory,
+			assertOwned: lock.assertOwned
+		});
+		const record = buildRecord({
+			runId,
+			actor,
+			reason,
+			travellers,
+			createdAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+		});
+		await writeJsonDurableWithinRoot(sharedRoot, `${KNOWLEDGE_PROMOTIONS_DIRECTORY}/${record.recordDigest}.json`, record);
+		return record;
+	});
+}
+/** Read one promotion record written by `promoteRunScopedPages`. */
+async function loadKnowledgePromotionRecord(sharedRoot, recordDigest) {
+	try {
+		const snapshot = await readRegularFileWithinRoot(sharedRoot, `${KNOWLEDGE_PROMOTIONS_DIRECTORY}/${recordDigest}.json`);
+		return JSON.parse(snapshot.bytes.toString("utf8"));
+	} catch (error) {
+		if (isMissingFile(error)) return null;
+		throw error;
+	}
+}
+/**
+* The requested pages plus the closure of the run-local pages they cite.
+*
+* A citation into the shared store needs no carrying, and an unresolved
+* citation is left to the target-side check, which reports every one of them
+* together rather than failing on the first.
+*/
+function collectTravellers(chain, pageIds) {
+	const byId = /* @__PURE__ */ new Map();
+	const queue = [];
+	for (const pageId of pageIds) {
+		const authored = chain.filter((entry) => entry.origin === "here" && entry.page.id === pageId);
+		if (authored.length === 0) throw new KnowledgePromotionError("unknown-page", `promotion page "${pageId}" was not authored by this run`);
+		if (authored.length > 1) throw new KnowledgePromotionError("ambiguous-support", `promotion page "${pageId}" names ${authored.length} pages in this run`);
+		queue.push({
+			entry: authored[0],
+			requested: true
+		});
+	}
+	while (queue.length > 0) {
+		const next = queue.shift();
+		const seen = byId.get(next.entry.page.id);
+		if (seen) {
+			if (next.requested) seen.requested = true;
+			if (seen.entry.page.path !== next.entry.page.path) throw new KnowledgePromotionError("ambiguous-support", `promotion support "${next.entry.page.id}" names more than one visible page`);
+			continue;
+		}
+		byId.set(next.entry.page.id, {
+			entry: next.entry,
+			requested: next.requested
+		});
+		for (const persisted of next.entry.page.cites ?? []) {
+			const target = resolveKnowledgeCitation(chain, parseKnowledgeCitationReference(persisted)).resolved;
+			if (target === void 0 || target.origin === "shared") continue;
+			queue.push({
+				entry: {
+					page: target.page,
+					origin: target.origin
+				},
+				requested: false
+			});
+		}
+	}
+	return [...byId.values()].sort((left, right) => Number(right.requested) - Number(left.requested) || left.entry.page.path.localeCompare(right.entry.page.path));
+}
+function assertNoIdentityConflict(travellers, existing) {
+	for (const traveller of travellers) {
+		const page = traveller.entry.page;
+		const idClash = existing.find((other) => other.id === page.id && other.path !== page.path);
+		if (idClash) throw new KnowledgePromotionError("id-conflict", `shared page "${idClash.path}" already holds id "${page.id}"; promoting "${page.path}" would create two`);
+		const pathClash = existing.find((other) => other.path === page.path && other.id !== page.id);
+		if (pathClash) throw new KnowledgePromotionError("path-conflict", `shared page "${page.path}" holds id "${pathClash.id}", not "${page.id}"`);
+	}
+}
+/**
+* The page as its own store holds it. A promoted page must be the same bytes
+* in both scopes, so the record's digest describes what a reader will load.
+*/
+async function readPageBytes(stores, runId, entry) {
+	const sourceRunId = sourceRunOf(entry.origin, runId);
+	return (await readRegularFileWithinRoot(stores.storePath(sourceRunId), entry.page.path)).bytes.toString("utf8");
+}
+function sourceRunOf(origin, runId) {
+	if (origin === "here") return runId;
+	if (origin.startsWith("inherited:")) return origin.slice(10);
+	throw new Error(`promotion cannot read the bytes of a ${origin} page`);
+}
+function buildRecord(input) {
+	const entries = input.travellers.map((traveller) => Object.freeze({
+		pageId: traveller.entry.page.id,
+		path: traveller.entry.page.path,
+		sourceOrigin: traveller.entry.origin,
+		pageDigest: knowledgePageDigest(traveller.entry.page),
+		requested: traveller.requested
+	}));
+	const material = {
+		schemaVersion: KNOWLEDGE_PROMOTION_SCHEMA_VERSION,
+		kind: "knowledge-promotion",
+		digestAlgorithm: KNOWLEDGE_PROMOTION_DIGEST_ALGORITHM,
+		createdAt: input.createdAt,
+		runId: input.runId,
+		actor: input.actor,
+		reason: input.reason,
+		entries
+	};
+	return Object.freeze({
+		...material,
+		recordDigest: canonicalCandidateDigest(material)
+	});
+}
+function nonEmpty(value, label) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${label} must be a non-empty string`);
+	return value.trim();
+}
+//#endregion
 //#region src/propose-from-finding.ts
 var KnowledgeProposalParseError = class extends Error {
 	findingId;
@@ -6602,6 +7152,227 @@ async function evaluateKnowledgeBaseReadiness(options) {
 	};
 }
 //#endregion
+//#region src/relation-graph.ts
+/** A relation graph input or query that cannot be honored exactly. */
+var KnowledgeRelationGraphError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "KnowledgeRelationGraphError";
+		this.code = code;
+	}
+};
+/**
+* Build a labeled multi-edge graph from caller relations.
+*
+* The graph keeps one edge per `(sourceId, targetId, predicate)`, in first-seen
+* order. A repeated triple is accepted only when its weight and metadata are
+* identical in canonical JSON; any other repeat is a conflict and is refused.
+* Node and relation metadata must be finite, acyclic JSON so the graph
+* round-trips through `KnowledgeRelationGraphSchema` unchanged.
+*/
+function buildKnowledgeRelationGraph(input) {
+	const declared = input.nodes === void 0 ? void 0 : /* @__PURE__ */ new Map();
+	const nodes = [];
+	if (declared !== void 0) for (const [position, node] of input.nodes.entries()) {
+		const normalized = normalizeNode(node, position);
+		if (declared.has(normalized.id)) throw new KnowledgeRelationGraphError("duplicate-node", `node "${normalized.id}" is declared more than once`);
+		declared.set(normalized.id, normalized);
+		nodes.push(normalized);
+	}
+	const edges = [];
+	const canonicalByTriple = /* @__PURE__ */ new Map();
+	for (const [position, relation] of input.relations.entries()) {
+		const normalized = normalizeRelation(relation, position);
+		if (declared !== void 0) {
+			for (const endpoint of [normalized.sourceId, normalized.targetId]) if (!declared.has(endpoint)) throw new KnowledgeRelationGraphError("undeclared-endpoint", `relation ${describeTriple(normalized)} names undeclared node "${endpoint}"`);
+		}
+		const canonical = canonicalRelationJson(normalized);
+		const key = tripleKey(normalized);
+		const prior = canonicalByTriple.get(key);
+		if (prior !== void 0) {
+			if (prior === canonical) continue;
+			throw new KnowledgeRelationGraphError("duplicate-relation", `relation ${describeTriple(normalized)} is repeated with different weight or metadata`);
+		}
+		canonicalByTriple.set(key, canonical);
+		edges.push(normalized);
+	}
+	return {
+		nodes,
+		edges
+	};
+}
+/** Relations touching `id`, each with the node at the other end, in graph order. */
+function neighbors(graph, id, query) {
+	const index = indexOf(graph);
+	validateQuery(query);
+	assertKnownNode(index, id);
+	return neighborsOf(index, id, query);
+}
+/**
+* Breadth-first traversal from `id` over matching relations. Each reachable
+* node is reported once, at the depth where the search first reached it; the
+* start node is never reported, so a cycle back to it adds no step.
+*/
+function walk(graph, id, options) {
+	const index = indexOf(graph);
+	validateQuery(options);
+	validateMaxDepth(options.maxDepth);
+	assertKnownNode(index, id);
+	const steps = [];
+	for (const step of traverse(index, id, options, options.maxDepth)) steps.push(step);
+	return steps;
+}
+/**
+* Whether `to` is `from` or lies on a path of matching relations out of `from`.
+*/
+function isReachable(graph, from, to, query) {
+	const index = indexOf(graph);
+	validateQuery(query);
+	assertKnownNode(index, from);
+	assertKnownNode(index, to);
+	if (from === to) return true;
+	for (const step of traverse(index, from, query, void 0)) if (step.nodeId === to) return true;
+	return false;
+}
+const indexes = /* @__PURE__ */ new WeakMap();
+function indexOf(graph) {
+	const cached = indexes.get(graph);
+	if (cached !== void 0) return cached;
+	const outgoing = /* @__PURE__ */ new Map();
+	const incoming = /* @__PURE__ */ new Map();
+	const known = /* @__PURE__ */ new Set();
+	for (const node of graph.nodes) known.add(node.id);
+	for (const relation of graph.edges) {
+		known.add(relation.sourceId);
+		known.add(relation.targetId);
+		push(outgoing, relation.sourceId, relation);
+		push(incoming, relation.targetId, relation);
+	}
+	const index = {
+		outgoing,
+		incoming,
+		known
+	};
+	indexes.set(graph, index);
+	return index;
+}
+function push(map, key, relation) {
+	const list = map.get(key);
+	if (list === void 0) map.set(key, [relation]);
+	else list.push(relation);
+}
+function neighborsOf(index, id, query) {
+	const matches = (relation) => query.predicate === void 0 || relation.predicate === query.predicate;
+	const result = [];
+	if (query.direction !== "in") {
+		for (const relation of index.outgoing.get(id) ?? []) if (matches(relation)) result.push({
+			nodeId: relation.targetId,
+			relation
+		});
+	}
+	if (query.direction !== "out") for (const relation of index.incoming.get(id) ?? []) {
+		if (query.direction === "both" && relation.sourceId === id) continue;
+		if (matches(relation)) result.push({
+			nodeId: relation.sourceId,
+			relation
+		});
+	}
+	return result;
+}
+function* traverse(index, start, query, maxDepth) {
+	const visited = /* @__PURE__ */ new Set([start]);
+	const queue = [{
+		nodeId: start,
+		depth: 0
+	}];
+	for (let head = 0; head < queue.length; head++) {
+		const current = queue[head];
+		if (maxDepth !== void 0 && current.depth >= maxDepth) continue;
+		for (const neighbor of neighborsOf(index, current.nodeId, query)) {
+			if (visited.has(neighbor.nodeId)) continue;
+			visited.add(neighbor.nodeId);
+			const depth = current.depth + 1;
+			yield {
+				nodeId: neighbor.nodeId,
+				depth,
+				from: current.nodeId,
+				relation: neighbor.relation
+			};
+			queue.push({
+				nodeId: neighbor.nodeId,
+				depth
+			});
+		}
+	}
+}
+function assertKnownNode(index, id) {
+	if (!index.known.has(id)) throw new KnowledgeRelationGraphError("unknown-node", `node "${id}" is not in the graph`);
+}
+function validateQuery(query) {
+	if (query.direction !== "out" && query.direction !== "in" && query.direction !== "both") throw new KnowledgeRelationGraphError("invalid-query", `direction must be "out", "in", or "both", got ${JSON.stringify(query.direction)}`);
+	if (query.predicate !== void 0 && !isNonEmptyString(query.predicate)) throw new KnowledgeRelationGraphError("invalid-query", "predicate must be a non-empty string");
+}
+function validateMaxDepth(maxDepth) {
+	if (maxDepth === void 0) return;
+	if (!Number.isInteger(maxDepth) || maxDepth < 0) throw new KnowledgeRelationGraphError("invalid-query", `maxDepth must be a non-negative integer, got ${JSON.stringify(maxDepth)}`);
+}
+function normalizeNode(node, position) {
+	if (!isNonEmptyString(node.id)) throw new KnowledgeRelationGraphError("invalid-node", `node at ${position} has no id`);
+	if (!isNonEmptyString(node.kind)) throw new KnowledgeRelationGraphError("invalid-node", `node "${node.id}" has no kind`);
+	if (node.label !== void 0 && typeof node.label !== "string") throw new KnowledgeRelationGraphError("invalid-node", `node "${node.id}" label is not a string`);
+	if (node.metadata !== void 0) assertCanonicalMetadata(node.metadata, `node "${node.id}"`, "invalid-node");
+	return {
+		id: node.id,
+		kind: node.kind,
+		...node.label !== void 0 ? { label: node.label } : {},
+		...node.metadata !== void 0 ? { metadata: node.metadata } : {}
+	};
+}
+function normalizeRelation(relation, position) {
+	for (const field of [
+		"sourceId",
+		"targetId",
+		"predicate"
+	]) if (!isNonEmptyString(relation[field])) throw new KnowledgeRelationGraphError("invalid-relation", `relation at ${position} has no ${field}`);
+	if (relation.weight !== void 0 && !Number.isFinite(relation.weight)) throw new KnowledgeRelationGraphError("invalid-relation", `relation ${describeTriple(relation)} weight must be a finite number`);
+	return {
+		sourceId: relation.sourceId,
+		targetId: relation.targetId,
+		predicate: relation.predicate,
+		...relation.weight !== void 0 ? { weight: relation.weight } : {},
+		...relation.metadata !== void 0 ? { metadata: relation.metadata } : {}
+	};
+}
+function canonicalRelationJson(relation) {
+	if (relation.metadata !== void 0) assertCanonicalMetadata(relation.metadata, `relation ${describeTriple(relation)}`, "invalid-relation");
+	return canonicalCandidateJson({
+		...relation.weight !== void 0 ? { weight: relation.weight } : {},
+		...relation.metadata !== void 0 ? { metadata: relation.metadata } : {}
+	});
+}
+function assertCanonicalMetadata(metadata, subject, code) {
+	if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) throw new KnowledgeRelationGraphError(code, `${subject} metadata must be an object`);
+	try {
+		canonicalCandidateJson(metadata);
+	} catch (error) {
+		throw new KnowledgeRelationGraphError(code, `${subject} metadata must be finite, acyclic JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function tripleKey(relation) {
+	return JSON.stringify([
+		relation.sourceId,
+		relation.targetId,
+		relation.predicate
+	]);
+}
+function describeTriple(relation) {
+	return `${relation.sourceId} -[${relation.predicate}]-> ${relation.targetId}`;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+//#endregion
 //#region src/release.ts
 function knowledgeReleaseReport(input) {
 	const baselineRuns = input.baselineRuns ?? [];
@@ -7293,150 +8064,6 @@ function buildSteerText(gaps, deepQuestions, invalidationTargets, minIndependent
 	return lines.join("\n");
 }
 //#endregion
-//#region src/run-scoped.ts
-/**
-* Run-scoped knowledge stores with lineage-chain reads.
-*
-* One store exists per run, physically isolated, with inheritance only through
-* declared ancestry. Reads expose the current store, every declared ancestor,
-* and an optional curated shared store with an explicit origin label.
-*/
-const RUN_LINEAGE_BASENAME = "lineage.json";
-/** Ancestry beyond this bound is invalid durable state. */
-const MAX_LINEAGE_HOPS = 64;
-function createRunScopedStores(options) {
-	if (!options || typeof options !== "object") throw new TypeError("createRunScopedStores options are required");
-	if (typeof options.root !== "string" || options.root.trim().length === 0) throw new TypeError("createRunScopedStores root must be a non-empty string");
-	if (options.runStorePath !== void 0 && typeof options.runStorePath !== "function") throw new TypeError("createRunScopedStores runStorePath must be a function when present");
-	if (options.lineageAuthority !== void 0) validateLineageAuthority(options.lineageAuthority);
-	const storePath = options.runStorePath ?? ((runId) => join(options.root, runId, "knowledge-base"));
-	const internalAuthority = createFileRunLineageAuthority(storePath);
-	const authority = options.lineageAuthority ?? internalAuthority;
-	const resolveLineage = async (runId) => {
-		assertRunId(runId);
-		const chain = [];
-		const seen = /* @__PURE__ */ new Set([runId]);
-		let current = runId;
-		for (let hop = 0; hop <= MAX_LINEAGE_HOPS; hop += 1) {
-			const parent = await authority.parentOf(current);
-			if (parent === null) return chain;
-			assertRunId(parent, `parent of '${current}'`);
-			if (seen.has(parent)) throw new Error(`run lineage cycle: ${parent} is its own ancestor (via ${runId})`);
-			seen.add(parent);
-			chain.push(parent);
-			current = parent;
-		}
-		throw new Error(`run lineage for '${runId}' exceeds ${MAX_LINEAGE_HOPS} ancestors`);
-	};
-	return {
-		async init(runId, initOptions = {}) {
-			assertRunId(runId);
-			const parentRunId = initOptions.parentRunId ?? null;
-			if (parentRunId !== null) assertRunId(parentRunId, `parent of '${runId}'`);
-			if (!authority.record) {
-				const existingParent = await authority.parentOf(runId);
-				if (existingParent !== parentRunId) throw new Error(`external lineage authority disagrees for '${runId}': expected ${renderParent(parentRunId)}, observed ${renderParent(existingParent)}`);
-			}
-			const layout = await initKnowledgeBase(storePath(runId));
-			if (authority.record) await authority.record(Object.freeze({
-				runId,
-				parentRunId,
-				createdAt: (/* @__PURE__ */ new Date()).toISOString()
-			}));
-			return layout;
-		},
-		lineage: resolveLineage,
-		async loadChain(runId) {
-			assertRunId(runId);
-			const out = [];
-			const readInto = async (root, origin) => {
-				let pages;
-				try {
-					pages = await loadKnowledgePages(root);
-				} catch (error) {
-					if (isMissingFile(error)) return;
-					throw error;
-				}
-				for (const page of pages) out.push({
-					page,
-					origin
-				});
-			};
-			await readInto(storePath(runId), "here");
-			for (const ancestor of await resolveLineage(runId)) await readInto(storePath(ancestor), `inherited:${ancestor}`);
-			if (options.sharedRoot) await readInto(options.sharedRoot, "shared");
-			return out;
-		}
-	};
-}
-/** File-backed authority used when the product has no separate run manifest. */
-function createFileRunLineageAuthority(runStorePath) {
-	if (typeof runStorePath !== "function") throw new TypeError("createFileRunLineageAuthority requires a runStorePath function");
-	const readRecord = async (runId) => {
-		assertRunId(runId);
-		const root = runStorePath(runId);
-		try {
-			return parseLineageRecord((await readRegularFileWithinRoot(root, RUN_LINEAGE_BASENAME)).bytes.toString("utf8"), runId);
-		} catch (error) {
-			if (isMissingFile(error)) return null;
-			throw error;
-		}
-	};
-	return {
-		async parentOf(runId) {
-			return (await readRecord(runId))?.parentRunId ?? null;
-		},
-		async record(record) {
-			const validated = validateLineageRecord(record);
-			const root = runStorePath(validated.runId);
-			await withKnowledgeMutation(root, async () => {
-				const existing = await readRecord(validated.runId);
-				if (existing) {
-					if (existing.parentRunId !== validated.parentRunId) throw new Error(`run lineage conflict for '${validated.runId}': existing parent ${renderParent(existing.parentRunId)}, requested ${renderParent(validated.parentRunId)}`);
-					return;
-				}
-				await writeJson(join(root, RUN_LINEAGE_BASENAME), validated);
-			});
-		}
-	};
-}
-function validateLineageAuthority(authority) {
-	if (!authority || typeof authority !== "object") throw new TypeError("lineageAuthority must be an object");
-	if (typeof authority.parentOf !== "function") throw new TypeError("lineageAuthority.parentOf must be a function");
-	if (authority.record !== void 0 && typeof authority.record !== "function") throw new TypeError("lineageAuthority.record must be a function when present");
-}
-function parseLineageRecord(text, expectedRunId) {
-	let parsed;
-	try {
-		parsed = JSON.parse(text);
-	} catch (cause) {
-		throw new Error(`invalid lineage JSON for '${expectedRunId}'`, { cause });
-	}
-	const record = validateLineageRecord(parsed);
-	if (record.runId !== expectedRunId) throw new Error(`lineage record identity mismatch: expected '${expectedRunId}', found '${record.runId}'`);
-	return record;
-}
-function validateLineageRecord(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("run lineage record must be an object");
-	const record = value;
-	assertRunId(record.runId, "lineage record runId");
-	if (record.parentRunId !== null) assertRunId(record.parentRunId, `parent of '${record.runId}'`);
-	if (typeof record.createdAt !== "string" || record.createdAt.trim().length === 0 || !Number.isFinite(Date.parse(record.createdAt))) throw new TypeError("run lineage record createdAt must be an ISO timestamp");
-	return {
-		runId: record.runId,
-		parentRunId: record.parentRunId,
-		createdAt: record.createdAt
-	};
-}
-function assertRunId(value, label = "runId") {
-	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${label} must be a non-empty string`);
-	const trimmed = value.trim();
-	if (trimmed === "." || trimmed === ".." || /[/\\\0]/.test(value)) throw new TypeError(`${label} must not contain path separators or dot segments`);
-}
-function renderParent(parentRunId) {
-	return parentRunId === null ? "none" : `'${parentRunId}'`;
-}
-//#endregion
-export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, CHECKABLE_RUNG_THRESHOLD, ClaimLedgerGoalConflictError, ClaimLedgerMigrationRequiredError, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, DeepQuestionSchema, FileSystemKbStore, FileSystemSearchProvider, INDUSTRY_MEMORY_BENCHMARKS, INDUSTRY_RAG_BENCHMARKS, IRS_DIMENSION_HINTS, KB_CLAIM_LEDGER_DIR, KB_EVENTS_PATH, KB_INDEX_PATH, KB_STORE_DIR, KNOWLEDGE_EVENT_TYPES, KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM, KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION, KnowledgeBaseCandidateSchema, KnowledgeCitationAuditError, KnowledgeCitationResolutionError, KnowledgeEventSchema, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeImprovementCandidateRefSchema, KnowledgeImprovementEvidenceSchema, KnowledgeImprovementRunStateSchema, KnowledgeIndexSchema, KnowledgePageInvalidationSchema, KnowledgePageSchema, KnowledgeProposalParseError, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, MemoryKbStore, POLITE_USER_AGENT, READINESS_SPEC_DEFAULTS, RUN_LINEAGE_BASENAME, ResearchClaimEvidenceSchema, ResearchClaimLedgerSchema, ResearchClaimRecordSchema, ResearchSourceVersionSchema, RouterError, SCAFFOLD_PAGE_BASENAMES, SourceAnchorSchema, SourceRecordSchema, UncheckableClaimError, WIKILINK_REGEX, __resetHttpThrottle, acquireAgentMemoryRunLease, addSourcePath, addSourceText, agentMemorySequenceJudge, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, applyRetrievalHoldout, applySessionStickyRetrievalHoldout, assertClaimLedgerId, assertCurrentRunCitationsResolved, assertDeepQuestionIntegrity, assertGradeableEvidence, assertKnowledgeCitationAudit, assertKnowledgeCitationsResolved, assertKnowledgeRetrievalMatchesVisibility, assertResearchClaimEvidenceIntegrity, assertResearchClaimLedgerIntegrity, assertRunScopedCitationsResolved, assertTrackedClaimIntegrity, auditCurrentRunCitations, auditKnowledgeCitations, buildAgentMemorySequenceScenarios, buildAgentMemorySequencesFromBenchmarkCases, buildEvalKnowledgeBundle, buildFirstPartyMemoryLifecycleBenchmarkCases, buildIndustryMemoryBenchmarkSmokeCases, buildIndustryRagBenchmarkSmokeCases, buildKnowledgeBenchmarkScenarios, buildKnowledgeGraph, buildKnowledgeIndex, buildRetrievalBenchmarkCasesFromQrels, buildRetrievalEvalDispatch, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, claimEvidenceId, claimId, claimSourceHost, compareAgentMemoryLearning, contentKey, createAdaptiveResearchDriver, createAgentMemoryBranch, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createCornellLiiSource, createD1FreshnessStoreStub, createFileRunLineageAuthority, createFileSystemFreshnessStore, createFileSystemSearchProvider, createGraphitiMemoryAdapter, createInMemoryBenchmarkAdapter, createIrsPublicationsSource, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createKnowledgeRetrievalReceipt, createKnowledgeUseReceipt, createKnowledgeVisibilitySnapshot, createLocalDiscoveryDispatcher, createMem0MemoryAdapter, createMemoryExecutionPool, createNeo4jAgentMemoryAdapter, createNoopMemoryBenchmarkAdapter, createPersistentResearchDrivingDriver, createRagAnswerQualityHook, createResearchDrivingDriver, createRunScopedStores, createStateSosSource, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, deepQuestionId, defaultGetMemoryContext, defineReadinessSpec, detectChanges, detectNearDuplicatePages, deterministicRng, diagnoseRagAnswerFailure, emitRetrievalHoldoutBypass, emptyClaimLedger, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractLinks, extractWikilinks, firstMatch, forkAgentMemoryBranchSnapshot, formatFrontmatter, formatKnowledgeCitationReference, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, gradeFor, graphitiMemoryAdapterIdentity, groundClaimInText, hashKnowledgeBase, htmlToText, improveKnowledgeBase, improveSelectedKnowledgeCandidate, initKnowledgeBase, innerHtmlById, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isKernelAnchoredPath, isKnowledgeMemoryBenchmarkCase, isMissingFile, isSafeKnowledgePath, isScaffoldPath, jsonCandidateCodec, jsonObjectCandidateCodec, kbIndexToText, knowledgeBenchmarkJudge, knowledgeCitationAuditFindings, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgePageDigest, knowledgeReleaseReport, layoutFor, lensDistribution, linkClaimContradictions, lintCurrentRunCitations, lintKnowledgeIndex, listRegularFilesWithinRoot, loadKnowledgeImprovementActivationResult, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, looksLikeBlockPage, materialFactsSurfaced, materialFactsSurfacedInText, materializeRegisteredClaimEvidence, mediaTypeFor, mem0MemoryAdapterIdentity, memoryHitToSourceRecord, memoryRecoveryDelayMs, memoryWriteResultToSourceRecord, mergeClaimLedgers, mergeTrackedClaims, normalizeClaimText, normalizeExternalRagScores, normalizeLinkTarget, normalizePageText, optimizeKnowledgeBasePolicy, parseFrontmatter, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, parseKnowledgeCitationReference, parseKnowledgeWriteBlocks, partitionRetrievalScenarios, politeFetch, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, readRegularFileNoFollow, readRegularFileWithinRoot, reciprocalRankFusion, recoverPendingKnowledgeMutation, removeDurable, renameDurable, renderKnowledgeBenchmarkReportMarkdown, renderMemoryContext, researchSourceVersionKey, resetRetrievalHoldoutRegistry, resolveKnowledgeCitation, resolveKnowledgeCitations, resolveMemoryCleanupTimeoutMs, resolveRunScopedCitation, resolveRunScopedCitations, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, restoreKnowledgeCandidateBaseline, retrievalConfigFromSurface, retrievalConfigSurface, retrievalHoldoutConfigHash, retrievalRecallJudge, runAgentMemoryExperiment, runAgentMemoryImprovement, runAgentMemoryLearningExperiment, runBoundedMemoryLifecycle, runDiscoveryLoop, runInvestmentThesisTask, runKnowledgeBenchmarkSuite, runKnowledgeResearchLoop, runMemoryAdapterBenchmark, runRagKnowledgeImprovementLoop, runRagOptimization, runRetrievalImprovementLoop, runSerializedKnowledgeOptimization, runVerifiedResearchLoop, scenarioContentFingerprint, scoreKnowledgeBaseIndex, scoreKnowledgeBenchmarkArtifact, scoreMemoryBenchmarkArtifact, scoreRagAnswerArtifact, scoreRetrievalArtifact, searchKnowledge, sha256, sleepForMemoryRecovery, slugify, snapshotSourceTextInput, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, summarizeKnowledgeBenchmarkCampaign, syncDirectory, textSourceAdapter, textSourceId, thesisReadinessSpecs, toAgentCandidateKnowledgeRef, toDeepEvalTestCases, toOffPolicyTrajectory, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, verdictFor, verifyGradeableEvidence, verifyKnowledgeRetrievalReceipt, verifyKnowledgeUseReceipt, withCitedClaim, withKnowledgeImprovementCandidate, withKnowledgeImprovementComparison, withKnowledgeMutation, withKnowledgeRead, withSafeDescendant, withSafeDirectory, writeFileDurable, writeFileDurableWithinRoot, writeJson, writeJsonDurable, writeJsonDurableWithinRoot, writeKnowledgeIndex, writeSourceRegistry };
+export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, CHECKABLE_RUNG_THRESHOLD, CITES_INVALIDATED_FIELD, ClaimLedgerGoalConflictError, ClaimLedgerMigrationRequiredError, DEFAULT_KNOWLEDGE_BRIEF_LIMIT, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, DEFAULT_PAGES_DIRECTORY, DeepQuestionSchema, FileSystemKbStore, FileSystemSearchProvider, INDUSTRY_MEMORY_BENCHMARKS, INDUSTRY_RAG_BENCHMARKS, IRS_DIMENSION_HINTS, KB_CLAIM_LEDGER_DIR, KB_EVENTS_PATH, KB_INDEX_PATH, KB_STORE_DIR, KNOWLEDGE_EVENT_TYPES, KNOWLEDGE_PROMOTIONS_DIRECTORY, KNOWLEDGE_PROMOTION_DIGEST_ALGORITHM, KNOWLEDGE_PROMOTION_SCHEMA_VERSION, KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM, KNOWLEDGE_SEARCH_RETRIEVER_ID, KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION, KnowledgeBaseCandidateSchema, KnowledgeCitationAuditError, KnowledgeCitationResolutionError, KnowledgeDuplicateIntakeError, KnowledgeEventSchema, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeImprovementCandidateRefSchema, KnowledgeImprovementEvidenceSchema, KnowledgeImprovementRunStateSchema, KnowledgeIndexSchema, KnowledgePageInvalidationSchema, KnowledgePageSchema, KnowledgePromotionError, KnowledgeProposalParseError, KnowledgeRelationGraphError, KnowledgeRelationGraphSchema, KnowledgeRelationNodeSchema, KnowledgeRelationSchema, KnowledgeVisibilityUnavailableError, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, MemoryKbStore, POLITE_USER_AGENT, READINESS_SPEC_DEFAULTS, RUN_LINEAGE_BASENAME, ResearchClaimEvidenceSchema, ResearchClaimLedgerSchema, ResearchClaimRecordSchema, ResearchSourceVersionSchema, RouterError, SCAFFOLD_PAGE_BASENAMES, SourceAnchorSchema, SourceRecordSchema, UncheckableClaimError, WIKILINK_REGEX, __resetHttpThrottle, acquireAgentMemoryRunLease, addSourcePath, addSourceText, agentMemorySequenceJudge, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, applyRetrievalHoldout, applySessionStickyRetrievalHoldout, assertClaimLedgerId, assertCurrentRunCitationsResolved, assertDeepQuestionIntegrity, assertGradeableEvidence, assertKnowledgeCitationAudit, assertKnowledgeCitationsResolved, assertKnowledgeRetrievalMatchesVisibility, assertKnowledgeRetrievalMatchesVisibilityArtifact, assertKnowledgeWriteIntake, assertResearchClaimEvidenceIntegrity, assertResearchClaimLedgerIntegrity, assertRunScopedCitationsResolved, assertTrackedClaimIntegrity, auditCurrentRunCitations, auditKnowledgeCitations, buildAgentMemorySequenceScenarios, buildAgentMemorySequencesFromBenchmarkCases, buildEvalKnowledgeBundle, buildFirstPartyMemoryLifecycleBenchmarkCases, buildIndustryMemoryBenchmarkSmokeCases, buildIndustryRagBenchmarkSmokeCases, buildKnowledgeBenchmarkScenarios, buildKnowledgeBrief, buildKnowledgeGraph, buildKnowledgeIndex, buildKnowledgeLexicalIndex, buildKnowledgeRelationGraph, buildRetrievalBenchmarkCasesFromQrels, buildRetrievalEvalDispatch, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, claimEvidenceId, claimId, claimSourceHost, compareAgentMemoryLearning, contentKey, createAdaptiveResearchDriver, createAgentMemoryBranch, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createCornellLiiSource, createD1FreshnessStoreStub, createFileRunLineageAuthority, createFileSystemFreshnessStore, createFileSystemSearchProvider, createGraphitiMemoryAdapter, createInMemoryBenchmarkAdapter, createIrsPublicationsSource, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createKnowledgeRetrievalDisposition, createKnowledgeRetrievalReceipt, createKnowledgeTools, createKnowledgeUseReceipt, createKnowledgeVisibilitySnapshot, createLocalDiscoveryDispatcher, createMem0MemoryAdapter, createMemoryExecutionPool, createNeo4jAgentMemoryAdapter, createNoopMemoryBenchmarkAdapter, createPersistentResearchDrivingDriver, createRagAnswerQualityHook, createResearchDrivingDriver, createRunScopedStores, createStateSosSource, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, decodeKnowledgeVisibilitySnapshot, deepQuestionId, defaultGetMemoryContext, defineReadinessSpec, detectChanges, detectNearDuplicatePages, deterministicRng, diagnoseRagAnswerFailure, emitRetrievalHoldoutBypass, emptyClaimLedger, encodeKnowledgeVisibilitySnapshot, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractLinks, extractWikilinks, firstMatch, forkAgentMemoryBranchSnapshot, formatFrontmatter, formatKnowledgeCitationReference, formatKnowledgeInvalidationProposal, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, gradeFor, graphitiMemoryAdapterIdentity, groundClaimInText, hashKnowledgeBase, htmlToText, improveKnowledgeBase, improveSelectedKnowledgeCandidate, initKnowledgeBase, innerHtmlById, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isKernelAnchoredPath, isKnowledgeMemoryBenchmarkCase, isKnowledgePagePath, isMissingFile, isReachable, isSafeKnowledgePath, isScaffoldPath, jsonCandidateCodec, jsonObjectCandidateCodec, kbIndexToText, knowledgeBenchmarkJudge, knowledgeCitationAuditFindings, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgePageDigest, knowledgePageFromMarkdown, knowledgePageRelations, knowledgeReleaseReport, knowledgeVisibilityArtifactRef, layoutFor, lensDistribution, linkClaimContradictions, lintCurrentRunCitations, lintKnowledgeIndex, listRegularFilesWithinRoot, loadKnowledgeImprovementActivationResult, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadKnowledgePromotionRecord, loadSourceRegistry, looksLikeBlockPage, materialFactsSurfaced, materialFactsSurfacedInText, materializeRegisteredClaimEvidence, mediaTypeFor, mem0MemoryAdapterIdentity, memoryHitToSourceRecord, memoryRecoveryDelayMs, memoryWriteResultToSourceRecord, mergeClaimLedgers, mergeTrackedClaims, neighbors, normalizeClaimText, normalizeExternalRagScores, normalizeLinkTarget, normalizePageText, normalizePagesDirectory, optimizeKnowledgeBasePolicy, originatedPages, parseFrontmatter, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, parseKnowledgeCitationReference, parseKnowledgeWriteBlocks, partitionRetrievalScenarios, planInvalidationPropagation, politeFetch, promoteKnowledgeCandidate, promoteRunScopedPages, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, readRegularFileNoFollow, readRegularFileWithinRoot, reciprocalRankFusion, recoverPendingKnowledgeMutation, removeDurable, renameDurable, renderKnowledgeBenchmarkReportMarkdown, renderMemoryContext, researchSourceVersionKey, resetRetrievalHoldoutRegistry, resolveKnowledgeCitation, resolveKnowledgeCitations, resolveMemoryCleanupTimeoutMs, resolveRunScopedCitation, resolveRunScopedCitations, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, restoreKnowledgeCandidateBaseline, retrievalConfigFromSurface, retrievalConfigSurface, retrievalHoldoutConfigHash, retrievalRecallJudge, runAgentMemoryExperiment, runAgentMemoryImprovement, runAgentMemoryLearningExperiment, runBoundedMemoryLifecycle, runDiscoveryLoop, runInvestmentThesisTask, runKnowledgeBenchmarkSuite, runKnowledgeResearchLoop, runMemoryAdapterBenchmark, runRagKnowledgeImprovementLoop, runRagOptimization, runRetrievalImprovementLoop, runSerializedKnowledgeOptimization, runVerifiedResearchLoop, scenarioContentFingerprint, scoreBm25, scoreKnowledgeBaseIndex, scoreKnowledgeBenchmarkArtifact, scoreMemoryBenchmarkArtifact, scoreRagAnswerArtifact, scoreRetrievalArtifact, searchKnowledge, searchKnowledgePages, sha256, sleepForMemoryRecovery, slugify, snapshotSourceTextInput, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, summarizeKnowledgeBenchmarkCampaign, syncDirectory, textSourceAdapter, textSourceId, thesisReadinessSpecs, toAgentCandidateKnowledgeRef, toDeepEvalTestCases, toOffPolicyTrajectory, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, tokenizeText, totalMaterialFacts, triageSource, validateKnowledgeIndex, verdictFor, verifyGradeableEvidence, verifyKnowledgeRetrievalDisposition, verifyKnowledgeRetrievalReceipt, verifyKnowledgeUseReceipt, verifyKnowledgeVisibilitySnapshot, walk, withCitedClaim, withKnowledgeImprovementCandidate, withKnowledgeImprovementComparison, withKnowledgeMutation, withKnowledgeRead, withSafeDescendant, withSafeDirectory, writeFileDurable, writeFileDurableWithinRoot, writeJson, writeJsonDurable, writeJsonDurableWithinRoot, writeKnowledgeIndex, writeSourceRegistry };
 
 //# sourceMappingURL=index.js.map