@tangle-network/agent-knowledge 8.0.7 → 8.0.9

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as ResearchSourceVersionSchema, A as MemoryKbStore, At as prepareKnowledgeFileTransaction, B as extractWikilinks, Bt as withSafeDescendant, C as writeSourceRegistry, Ct as recoverPendingKnowledgeMutation, D as KB_EVENTS_PATH, Dt as assertKnowledgeMutationPath, E as KB_CLAIM_LEDGER_DIR, Et as applyKnowledgeFileTransaction, F as isScaffoldPath, Ft as readRegularFileNoFollow, G as KnowledgeGraphEdgeSchema, Gt as writeJsonDurableWithinRoot, H as DeepQuestionSchema, Ht as writeFileDurable, I as layoutFor, It as readRegularFileWithinRoot, J as KnowledgePageInvalidationSchema, K as KnowledgeGraphNodeSchema, Kt as mediaTypeFor, L as loadKnowledgePages, Lt as removeDurable, M as buildKnowledgeGraph, Mt as isKernelAnchoredPath, N as SCAFFOLD_PAGE_BASENAMES, Nt as isMissingFile, O as KB_INDEX_PATH, Ot as finishKnowledgeFileTransaction, P as initKnowledgeBase, Pt as listRegularFilesWithinRoot, Q as ResearchClaimRecordSchema, R as writeJson, Rt as renameDurable, S as sourceRegistryPath, St as inspectPendingKnowledgeMutation, T as FileSystemKbStore, Tt as withKnowledgeRead, U as KnowledgeBaseCandidateSchema, Ut as writeFileDurableWithinRoot, V as normalizeLinkTarget, Vt as withSafeDirectory, W as KnowledgeEventSchema, Wt as writeJsonDurable, X as ResearchClaimEvidenceSchema, Y as KnowledgePageSchema, Z as ResearchClaimLedgerSchema, _ as writeKnowledgeIndex, _t as normalizeClaimText, a as applyKnowledgeWriteBlocksFile, at as assertResearchClaimEvidenceIntegrity, b as loadSourceRegistry, bt as parseFrontmatter, c as validateKnowledgeIndex, ct as claimEvidenceId, d as UncheckableClaimError, dt as deepQuestionId, et as SourceAnchorSchema, f as assertGradeableEvidence, ft as emptyClaimLedger, g as buildKnowledgeIndex, gt as mergeTrackedClaims, h as verifyGradeableEvidence, ht as mergeClaimLedgers, i as applyKnowledgeWriteBlocks, it as assertDeepQuestionIntegrity, j as assertClaimLedgerId, jt as rollbackKnowledgeFileTransaction, k as KB_STORE_DIR, kt as knowledgeFileTransactionPlanHash, l as lintKnowledgeIndex, lt as claimId, m as verdictFor, mt as materializeRegisteredClaimEvidence, n as inspectKnowledgeIndex, nt as KNOWLEDGE_EVENT_TYPES, o as isSafeKnowledgePath, ot as assertResearchClaimLedgerIntegrity, p as gradeFor, pt as linkClaimContradictions, q as KnowledgeIndexSchema, qt as textSourceAdapter, r as stringMetadata, rt as ClaimLedgerGoalConflictError, s as parseKnowledgeWriteBlocks, st as assertTrackedClaimIntegrity, t as explainKnowledgeTarget, tt as SourceRecordSchema, u as CHECKABLE_RUNG_THRESHOLD, ut as claimSourceHost, v as addSourcePath, vt as researchSourceVersionKey, w as ClaimLedgerMigrationRequiredError, wt as withKnowledgeMutation, x as snapshotSourceTextInput, xt as acquireDurableFileLock, y as addSourceText, yt as formatFrontmatter, z as WIKILINK_REGEX, zt as syncDirectory } from "./inspect-B7AJ7CZS.js";
+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 { 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";
@@ -3997,6 +3997,270 @@ async function optimizeKnowledgeBasePolicy(options) {
 	};
 }
 //#endregion
+//#region src/kb-improvement/selected-candidate.ts
+const DERIVED_KNOWLEDGE_PATHS = /* @__PURE__ */ new Set(["knowledge/index.md"]);
+const selectionPathSchema = z.string().min(1).transform((path, context) => {
+	try {
+		return assertKnowledgeMutationPath(path);
+	} catch (error) {
+		context.addIssue({
+			code: "custom",
+			message: error instanceof Error ? error.message : String(error)
+		});
+		return z.NEVER;
+	}
+});
+const selectionMetadataSchema = z.record(z.string(), z.json());
+const measuredSelectionLifecycleSchema = z.object({
+	kind: z.literal("measured-knowledge-change-selection"),
+	version: z.literal(1),
+	selectionDigest: z.string().regex(/^[a-f0-9]{64}$/),
+	sourceCandidateId: z.string().min(1),
+	sourceEvidenceHash: z.string().regex(/^[a-f0-9]{64}$/),
+	sourcePlanHash: z.string().regex(/^[a-f0-9]{64}$/),
+	selectedPaths: z.array(selectionPathSchema),
+	selectedCandidateHash: z.string().regex(/^[a-f0-9]{64}$/),
+	selectedPlanHash: z.string().regex(/^[a-f0-9]{64}$/)
+}).strict();
+const measuredSelectionReceiptSchema = z.object({
+	kind: z.literal("measured-knowledge-change-selection-receipt"),
+	version: z.literal(1),
+	receiptHash: z.string().regex(/^[a-f0-9]{64}$/),
+	selectionDigest: z.string().regex(/^[a-f0-9]{64}$/),
+	sourceCandidate: KnowledgeImprovementCandidateRefSchema,
+	sourcePlanHash: z.string().regex(/^[a-f0-9]{64}$/),
+	selectedPaths: z.array(selectionPathSchema),
+	derivedImplementationRef: immutableRefSchema,
+	runId: z.string().min(1),
+	derivedCandidateId: z.string().min(1),
+	derivedCandidateStatus: z.string().min(1),
+	selectedCandidateHash: z.string().regex(/^[a-f0-9]{64}$/),
+	selectedPlanHash: z.string().regex(/^[a-f0-9]{64}$/),
+	selectedEvidenceHash: z.string().regex(/^[a-f0-9]{64}$/),
+	rationale: z.string().trim().min(1).optional(),
+	metadata: selectionMetadataSchema.optional()
+}).strict();
+/**
+* Derive a subset from an already measured candidate, then measure the subset as
+* a new candidate before it can be promoted.
+*
+* Directly filtering an activation plan is unsafe: a whole candidate can pass
+* while one page subset breaks links, removes supporting sources, or changes a
+* readiness score. This helper instead applies the chosen changed paths to an
+* isolated baseline, recomputes the index, runs the ordinary improvement
+* evaluator, and returns the ordinary candidate reference. Promotion therefore
+* remains one path and can never admit an unmeasured hybrid.
+*/
+async function improveSelectedKnowledgeCandidate(options) {
+	const sourceCandidate = Object.freeze(KnowledgeImprovementCandidateRefSchema.parse(options.sourceCandidate));
+	const requestedImplementationRef = immutableRefSchema.parse(options.implementationRef);
+	const enabledEvaluationPhases = normalizeEvaluationPhases(options.enabledEvaluationPhases ?? EVALUATION_PHASES, "enabledEvaluationPhases");
+	const requiredEvaluationPhases = normalizeEvaluationPhases(options.requiredEvaluationPhases ?? [], "requiredEvaluationPhases");
+	const metadata = options.selectionMetadata ? selectionMetadataSchema.parse(structuredClone(options.selectionMetadata)) : void 0;
+	return withKnowledgeImprovementComparison({
+		root: options.root,
+		candidate: sourceCandidate
+	}, async (source) => {
+		const sourcePlan = await knowledgeFilePlanEntries(source.baseline.root, source.candidate.root);
+		const sourcePlanHash = knowledgeFileTransactionPlanHash(sourcePlan);
+		if (sourcePlanHash !== sourceCandidate.promotionPlanHash) throw new Error("source knowledge candidate plan no longer matches its measured identity");
+		const changedSourcePlan = sourcePlan.filter(planEntryChanged).filter(notDerivedPath);
+		const selectedPaths = normalizeSelectedPaths(options.selectedPaths, changedSourcePlan);
+		const selectionDigest = contentHash(immutableJson({
+			kind: "measured-knowledge-change-selection",
+			version: 1,
+			sourceCandidate,
+			sourcePlanHash,
+			selectedPaths,
+			...options.rationale?.trim() ? { rationale: options.rationale.trim() } : {},
+			...metadata ? { metadata } : {}
+		}));
+		const derivedImplementationRef = immutableRefSchema.parse(`sha256:${contentHash({
+			engine: "agent-knowledge/measured-selection-v1",
+			implementationRef: requestedImplementationRef,
+			selectionDigest
+		})}`);
+		const runId = options.runId ?? stableId("kimpsel", canonicalJson({
+			root: options.root,
+			goal: options.goal,
+			derivedImplementationRef,
+			selectionDigest
+		}));
+		const selectedEntries = selectedPaths.map((path) => {
+			const entry = changedSourcePlan.find((candidate) => candidate.path === path);
+			if (!entry) throw new Error(`selected knowledge path disappeared: ${path}`);
+			return entry;
+		});
+		const selectionMutationPlanHash = knowledgeFileTransactionPlanHash(selectedEntries);
+		let lifecycleSelection;
+		const result = await improveKnowledgeBase({
+			...improvementOptions(options),
+			root: options.root,
+			goal: options.goal,
+			implementationRef: derivedImplementationRef,
+			runId,
+			enabledPhases: ["knowledge-update", ...enabledEvaluationPhases],
+			requiredPhases: ["knowledge-update", ...requiredEvaluationPhases],
+			async updateKnowledge(input) {
+				const purpose = `knowledge-selected-candidate:${selectionDigest}`;
+				const recoveryOwner = `knowledge-selected-candidate:${sourceCandidate.candidateId}`;
+				await withKnowledgeMutation(input.candidateRoot, async (lock) => {
+					lock.assertOwned();
+					if (!lock.recovery && selectedEntries.length > 0) {
+						const transaction = await prepareKnowledgeFileTransaction({
+							root: input.candidateRoot,
+							transactionRoot: lock.transactionRoot,
+							purpose,
+							recoveryOwner,
+							mutations: await selectionMutations(source.candidate.root, selectedEntries),
+							now: options.now
+						});
+						if (transaction) {
+							assertSelectionTransaction(transaction, selectionMutationPlanHash);
+							await applyKnowledgeFileTransaction({
+								root: input.candidateRoot,
+								transactionRoot: lock.transactionRoot,
+								transaction,
+								beforeCommit: lock.assertOwned
+							});
+							await finishKnowledgeFileTransaction({
+								root: input.candidateRoot,
+								transactionRoot: lock.transactionRoot,
+								transaction,
+								assertOwned: lock.assertOwned
+							});
+						}
+					}
+					await writeKnowledgeIndex(input.candidateRoot);
+					lock.assertOwned();
+				}, { resumeTransaction: {
+					purpose,
+					recoveryOwner,
+					validate: (transaction) => assertSelectionTransaction(transaction, selectionMutationPlanHash)
+				} });
+				const selectedPlan = await knowledgeFilePlanEntries(source.baseline.root, input.candidateRoot);
+				assertExactSelectedChanges(selectedPlan, selectedPaths);
+				const selectedPlanHash = knowledgeFileTransactionPlanHash(selectedPlan);
+				const selectedCandidateHash = await hashKnowledgeBase(input.candidateRoot);
+				lifecycleSelection = measuredSelectionLifecycleSchema.parse({
+					kind: "measured-knowledge-change-selection",
+					version: 1,
+					selectionDigest,
+					sourceCandidateId: sourceCandidate.candidateId,
+					sourceEvidenceHash: sourceCandidate.evidenceHash,
+					sourcePlanHash,
+					selectedPaths,
+					selectedCandidateHash,
+					selectedPlanHash
+				});
+				return {
+					applied: selectedPaths.length > 0,
+					summary: selectedPaths.length > 0 ? `Applied ${selectedPaths.length} selected measured change(s).` : "Selected no changes; measuring the exact baseline as a null candidate.",
+					metadata: { selection: lifecycleSelection }
+				};
+			}
+		});
+		const candidate = result.candidate;
+		if (!candidate?.candidateHash || !candidate.promotionPlanHash || !candidate.evidenceHash) throw new Error("selected knowledge candidate did not produce measured candidate evidence");
+		const recordedSelection = measuredSelectionLifecycleSchema.parse(result.lifecycle?.knowledgeUpdate?.metadata?.selection ?? lifecycleSelection);
+		if (recordedSelection.selectionDigest !== selectionDigest || recordedSelection.selectedCandidateHash !== candidate.candidateHash || recordedSelection.selectedPlanHash !== candidate.promotionPlanHash || canonicalJson(recordedSelection.selectedPaths) !== canonicalJson(selectedPaths)) throw new Error("selected knowledge candidate evidence does not bind the measured subset");
+		const receiptWithoutHash = immutableJson({
+			kind: "measured-knowledge-change-selection-receipt",
+			version: 1,
+			selectionDigest,
+			sourceCandidate,
+			sourcePlanHash,
+			selectedPaths,
+			derivedImplementationRef,
+			runId: result.runId,
+			derivedCandidateId: candidate.candidateId,
+			derivedCandidateStatus: candidate.status,
+			selectedCandidateHash: candidate.candidateHash,
+			selectedPlanHash: candidate.promotionPlanHash,
+			selectedEvidenceHash: candidate.evidenceHash,
+			...options.rationale?.trim() ? { rationale: options.rationale.trim() } : {},
+			...metadata ? { metadata } : {}
+		});
+		const receipt = measuredSelectionReceiptSchema.parse({
+			...receiptWithoutHash,
+			receiptHash: contentHash(receiptWithoutHash)
+		});
+		await persistSelectionReceipt(options.root, receipt);
+		return {
+			...result,
+			selection: receipt
+		};
+	});
+}
+function improvementOptions(options) {
+	const { root: _root, goal: _goal, implementationRef: _implementationRef, sourceCandidate: _sourceCandidate, selectedPaths: _selectedPaths, runId: _runId, rationale: _rationale, selectionMetadata: _selectionMetadata, enabledEvaluationPhases: _enabledEvaluationPhases, requiredEvaluationPhases: _requiredEvaluationPhases, ...rest } = options;
+	return rest;
+}
+function normalizeEvaluationPhases(phases, field) {
+	const unique = [...new Set(phases)];
+	for (const phase of unique) if (phase === "knowledge-acquisition" || phase === "knowledge-update") throw new Error(`${field} cannot contain the selection-owned phase '${phase}'`);
+	return unique;
+}
+function normalizeSelectedPaths(paths, changedPlan) {
+	const available = new Set(changedPlan.map((entry) => entry.path));
+	const selected = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const input of paths) {
+		const path = selectionPathSchema.parse(input);
+		if (DERIVED_KNOWLEDGE_PATHS.has(path)) throw new Error(`derived knowledge path cannot be selected directly: ${path}`);
+		if (seen.has(path)) throw new Error(`selected knowledge path is repeated: ${path}`);
+		if (!available.has(path)) throw new Error(`selected knowledge path is not a changed source-candidate file: ${path}`);
+		seen.add(path);
+		selected.push(path);
+	}
+	return selected.sort((left, right) => left.localeCompare(right));
+}
+function planEntryChanged(entry) {
+	return entry.beforeHash !== entry.afterHash || entry.beforeHash !== null && entry.afterHash !== null && entry.beforeMode !== entry.afterMode;
+}
+function notDerivedPath(entry) {
+	return !DERIVED_KNOWLEDGE_PATHS.has(entry.path);
+}
+async function selectionMutations(sourceCandidateRoot, entries) {
+	return Promise.all(entries.map(async (entry) => {
+		if (entry.afterHash === null) return {
+			path: entry.path,
+			content: null
+		};
+		const file = await readRegularFileWithinRoot(sourceCandidateRoot, entry.path);
+		if (createHash("sha256").update(file.bytes).digest("hex") !== entry.afterHash || file.mode !== entry.afterMode) throw new Error(`source candidate changed before subset materialization: ${entry.path}`);
+		return {
+			path: entry.path,
+			content: file.bytes,
+			mode: file.mode
+		};
+	}));
+}
+function assertSelectionTransaction(transaction, expectedPlanHash) {
+	if (knowledgeFileTransactionPlanHash(transaction.entries) !== expectedPlanHash) throw new Error("selected knowledge transaction does not match its approved path set");
+}
+function assertExactSelectedChanges(plan, selectedPaths) {
+	const actual = plan.filter(planEntryChanged).filter(notDerivedPath).map((entry) => entry.path).sort((left, right) => left.localeCompare(right));
+	if (canonicalJson(actual) !== canonicalJson(selectedPaths)) throw new Error(`selected knowledge candidate changed the wrong files: expected ${selectedPaths.join(", ") || "(none)"}, got ${actual.join(", ") || "(none)"}`);
+}
+async function persistSelectionReceipt(root, receipt) {
+	const runDir = knowledgeImprovementRunDir(root, receipt.runId);
+	const relativePath = join("candidates", safePathSegmentSchema.parse(receipt.derivedCandidateId), "selection.json").replace(/\\/g, "/");
+	try {
+		if (canonicalJson(measuredSelectionReceiptSchema.parse(JSON.parse((await readRegularFileWithinRoot(runDir, relativePath)).bytes.toString("utf8")))) !== canonicalJson(receipt)) throw new Error("measured knowledge selection receipt conflicts with durable content");
+		return;
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+	}
+	await writeJsonDurableWithinRoot(runDir, relativePath, receipt);
+}
+function immutableJson(value) {
+	if (value === null || typeof value !== "object") return value;
+	const children = Array.isArray(value) ? value : Object.values(value);
+	for (const child of children) immutableJson(child);
+	return Object.freeze(value);
+}
+//#endregion
 //#region src/agent-candidate.ts
 /** Convert a measured knowledge candidate into the shared review and execution identity. */
 function toAgentCandidateKnowledgeRef(candidate) {
@@ -4259,6 +4523,45 @@ function mergeTinyChunks(chunks, opts) {
 	return out;
 }
 //#endregion
+//#region src/citation-lint.ts
+/** Convert a chain-aware citation audit into the package lint vocabulary. */
+function knowledgeCitationAuditFindings(report) {
+	return report.issues.map(issueToFinding);
+}
+/** Lint only current-run pages against their complete declared visibility chain. */
+async function lintCurrentRunCitations(stores, runId) {
+	return knowledgeCitationAuditFindings(await auditCurrentRunCitations(stores, runId));
+}
+function issueToFinding(issue) {
+	const candidates = issue.candidates.map((candidate) => ({
+		pageId: candidate.pageId,
+		path: candidate.page.path,
+		origin: candidate.origin
+	}));
+	if (issue.kind === "ambiguous") return {
+		type: "ambiguous-citation",
+		severity: "error",
+		page: issue.sourcePath,
+		message: `Citation "${issue.persistedCitation}" resolves to ${issue.candidates.length} visible pages; qualify it as here::<pageId>, inherited:<runId>::<pageId>, or shared::<pageId>.`,
+		metadata: {
+			sourcePageId: issue.sourcePageId,
+			sourceOrigin: issue.sourceOrigin,
+			candidates
+		}
+	};
+	return {
+		type: "broken-citation",
+		severity: "error",
+		page: issue.sourcePath,
+		message: issue.kind === "self" ? `Page "${issue.sourcePageId}" cites itself through "${issue.persistedCitation}".` : `Citation "${issue.persistedCitation}" resolves to no visible page.`,
+		metadata: {
+			sourcePageId: issue.sourcePageId,
+			sourceOrigin: issue.sourceOrigin,
+			candidates
+		}
+	};
+}
+//#endregion
 //#region src/collection-research-driver.ts
 /**
 * Build the single-agent collection driver. Accepts every source; never gates,
@@ -5651,6 +5954,379 @@ async function runInvestmentThesisTask(input, options) {
 	};
 }
 //#endregion
+//#region src/knowledge-use-receipts.ts
+const KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION = "1.0.0";
+const KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM = "rfc8785-sha256";
+/** Stable content identity for one exact knowledge page. */
+function knowledgePageDigest(page) {
+	validateKnowledgePage(page);
+	return canonicalCandidateDigest({
+		id: page.id,
+		path: page.path,
+		title: page.title,
+		text: page.text,
+		frontmatter: page.frontmatter,
+		sourceIds: [...page.sourceIds],
+		tags: [...page.tags],
+		outLinks: [...page.outLinks],
+		contradicts: [...page.contradicts ?? []],
+		invalidation: page.invalidation ?? null
+	});
+}
+/** Snapshot the exact ordered current/ancestor/shared page view. */
+function createKnowledgeVisibilitySnapshot(visiblePages) {
+	if (!Array.isArray(visiblePages)) throw new TypeError("knowledge visibility must be an array");
+	const identities = /* @__PURE__ */ new Set();
+	const entries = visiblePages.map((entry, position) => {
+		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}`;
+		if (identities.has(identity)) throw new Error(`knowledge visibility repeats path '${entry.page.path}' at origin '${origin}'`);
+		identities.add(identity);
+		return Object.freeze({
+			position,
+			pageId: entry.page.id,
+			origin,
+			path: entry.page.path,
+			pageDigest: knowledgePageDigest(entry.page),
+			sourceIds: Object.freeze([...entry.page.sourceIds]),
+			invalidated: entry.page.invalidation !== void 0
+		});
+	});
+	const material = visibilityMaterial(entries);
+	return Object.freeze({
+		...material,
+		snapshotDigest: canonicalCandidateDigest(material),
+		entries: Object.freeze(entries)
+	});
+}
+/** Create a retrieval receipt and refuse results that were not in the view. */
+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 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 retriever = normalizeRetriever(input.retriever);
+	const visibility = createKnowledgeVisibilitySnapshot(input.visiblePages);
+	const results = normalizeRetrievalResults(input.results, visibility);
+	const evidenceRefs = normalizeEvidenceRefs(input.evidenceRefs ?? []);
+	const attributes = normalizeAttributes(input.attributes ?? {});
+	const material = retrievalMaterial({
+		createdAt: isoTimestamp(input.createdAt, "knowledge retrieval createdAt"),
+		runId,
+		actorId,
+		profileDigest,
+		executionRef,
+		query,
+		retriever,
+		visibility,
+		results,
+		evidenceRefs,
+		attributes
+	});
+	return Object.freeze({
+		...material,
+		receiptDigest: canonicalCandidateDigest(material)
+	});
+}
+/** Verify the receipt's schema, internal joins, and canonical digest. */
+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}'`);
+	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);
+	if (canonicalCandidateDigest(retrievalMaterial({
+		createdAt: isoTimestamp(receipt.createdAt, "knowledge retrieval createdAt"),
+		runId: nonEmpty(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"),
+		retriever: normalizeRetriever(receipt.retriever),
+		visibility: receipt.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) {
+	verifyKnowledgeRetrievalReceipt(receipt);
+	if (createKnowledgeVisibilitySnapshot(visiblePages).snapshotDigest !== receipt.visibility.snapshotDigest) throw new Error("knowledge retrieval receipt does not match the supplied visibility snapshot");
+}
+/** Create a downstream-use receipt for one exact ranked result. */
+function createKnowledgeUseReceipt(input) {
+	if (!input || typeof input !== "object") throw new TypeError("knowledge use receipt input is required");
+	const retrieval = verifyKnowledgeRetrievalReceipt(input.retrieval);
+	if (!Number.isSafeInteger(input.selectedRank) || input.selectedRank < 1) throw new TypeError("knowledge use selectedRank must be a positive safe integer");
+	const selected = retrieval.results.find((result) => result.rank === input.selectedRank);
+	if (!selected) throw new Error(`knowledge use selectedRank ${input.selectedRank} was not returned by retrieval ${retrieval.receiptDigest}`);
+	const relation = validateUseRelation(input.relation);
+	const consumer = normalizeConsumer(input.consumer);
+	const evidenceRefs = normalizeEvidenceRefs(input.evidenceRefs ?? []);
+	const attributes = normalizeAttributes(input.attributes ?? {});
+	const material = useMaterial({
+		createdAt: isoTimestamp(input.createdAt, "knowledge use createdAt"),
+		retrieval,
+		used: Object.freeze({
+			rank: selected.rank,
+			pageId: selected.pageId,
+			origin: selected.origin,
+			path: selected.path,
+			pageDigest: selected.pageDigest
+		}),
+		relation,
+		consumer,
+		evidenceRefs,
+		attributes
+	});
+	return Object.freeze({
+		...material,
+		receiptDigest: canonicalCandidateDigest(material)
+	});
+}
+/** Verify one use receipt against the exact retrieval that authorized it. */
+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}'`);
+	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");
+	const selected = verifiedRetrieval.results.find((result) => result.rank === receipt.used.rank);
+	if (!selected || selected.pageId !== receipt.used.pageId || selected.origin !== receipt.used.origin || selected.path !== receipt.used.path || selected.pageDigest !== receipt.used.pageDigest) throw new Error("knowledge use receipt selected result does not match the retrieval receipt");
+	if (canonicalCandidateDigest(useMaterial({
+		createdAt: isoTimestamp(receipt.createdAt, "knowledge use createdAt"),
+		retrieval: verifiedRetrieval,
+		used: receipt.used,
+		relation: validateUseRelation(receipt.relation),
+		consumer: normalizeConsumer(receipt.consumer),
+		evidenceRefs: normalizeEvidenceRefs(receipt.evidenceRefs),
+		attributes: normalizeAttributes(receipt.attributes)
+	})) !== receipt.receiptDigest) throw new Error("knowledge use receipt digest mismatch");
+	return receipt;
+}
+function visibilityMaterial(entries) {
+	return {
+		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
+		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
+		entries: entries.map((entry, position) => {
+			if (entry.position !== position) throw new Error(`knowledge visibility position mismatch: expected ${position}, observed ${entry.position}`);
+			return {
+				position,
+				pageId: nonEmpty(entry.pageId, `knowledge visibility[${position}].pageId`),
+				origin: validateOrigin(entry.origin, `knowledge visibility[${position}].origin`),
+				path: nonEmpty(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}]`)),
+				invalidated: Boolean(entry.invalidated)
+			};
+		})
+	};
+}
+function retrievalMaterial(input) {
+	return {
+		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
+		kind: "knowledge-retrieval",
+		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
+		createdAt: input.createdAt,
+		runId: input.runId,
+		...input.actorId === void 0 ? {} : { actorId: input.actorId },
+		...input.profileDigest === void 0 ? {} : { profileDigest: input.profileDigest },
+		...input.executionRef === void 0 ? {} : { executionRef: input.executionRef },
+		query: input.query,
+		retriever: input.retriever,
+		visibility: input.visibility,
+		results: input.results,
+		evidenceRefs: input.evidenceRefs,
+		attributes: input.attributes
+	};
+}
+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,
+		used: input.used,
+		relation: input.relation,
+		consumer: input.consumer,
+		evidenceRefs: input.evidenceRefs,
+		attributes: input.attributes
+	};
+}
+function normalizeRetrievalResults(results, visibility) {
+	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`);
+		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`);
+		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);
+		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]`);
+		return Object.freeze({
+			rank: result.rank,
+			pageId: result.page.id,
+			origin,
+			path: result.page.path,
+			pageDigest,
+			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}]`)))
+		});
+	});
+	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}`);
+	});
+	return Object.freeze(normalized);
+}
+function validateReceiptResults(results, visibility) {
+	const visible = new Map(visibility.entries.map((entry) => [`${entry.origin}\u0000${entry.path}`, entry]));
+	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`);
+	});
+}
+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"),
+		configDigest: digest(input.configDigest, "knowledge retriever configDigest")
+	});
+}
+function normalizeConsumer(input) {
+	if (!input || typeof input !== "object") throw new TypeError("knowledge consumer reference is required");
+	if (![
+		"decision",
+		"artifact",
+		"experiment",
+		"candidate",
+		"message",
+		"other"
+	].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"),
+		...input.digest === void 0 ? {} : { digest: digest(input.digest, "knowledge consumer digest") }
+	});
+}
+function normalizeEvidenceRefs(values) {
+	if (!Array.isArray(values)) throw new TypeError("knowledge evidenceRefs must be an array");
+	const allowed = [
+		"span",
+		"event",
+		"artifact",
+		"finding",
+		"metric"
+	];
+	return Object.freeze(values.map((value, index) => {
+		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`) }
+		});
+	}));
+}
+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");
+		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;
+	}
+	return Object.freeze(normalized);
+}
+function validateUseRelation(value) {
+	if (![
+		"supports",
+		"contradicts",
+		"extends",
+		"rederives",
+		"background"
+	].includes(value)) throw new TypeError(`knowledge use relation is invalid: ${String(value)}`);
+	return 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");
+	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 [
+		["sourceIds", page.sourceIds],
+		["tags", page.tags],
+		["outLinks", page.outLinks]
+	]) if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) throw new TypeError(`knowledge page ${name} must be a string array`);
+}
+function validateOrigin(value, label) {
+	if (value === "here" || value === "shared") return value;
+	if (typeof value === "string" && value.startsWith("inherited:") && value.slice(10).trim().length > 0) return value;
+	throw new TypeError(`${label} is invalid: ${String(value)}`);
+}
+function digest(value, label) {
+	const parsed = sha256DigestSchema.safeParse(value);
+	if (!parsed.success) throw new TypeError(`${label} must be a lowercase sha256 digest`);
+	return parsed.data;
+}
+function optionalDigest(value, label) {
+	return value === void 0 ? void 0 : digest(value, label);
+}
+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();
+}
+function optionalText(value, label) {
+	return value === void 0 ? void 0 : nonEmpty(value, label);
+}
+function finite(value, label) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${label} must be a finite number`);
+}
+function isoTimestamp(value, label) {
+	const date = value === void 0 ? /* @__PURE__ */ new Date() : value instanceof Date ? value : new Date(value);
+	if (!Number.isFinite(date.getTime())) throw new TypeError(`${label} must be a valid timestamp`);
+	return date.toISOString();
+}
+//#endregion
 //#region src/propose-from-finding.ts
 var KnowledgeProposalParseError = class extends Error {
 	findingId;
@@ -6621,57 +7297,57 @@ function buildSteerText(gaps, deepQuestions, invalidationTargets, minIndependent
 /**
 * Run-scoped knowledge stores with lineage-chain reads.
 *
-* One store per run, physically isolated, with inheritance only by declared ancestry. The design
-* answers a failure mode a discovery campaign paid for twice: when every run writes one shared
-* store, a false "measured" claim from one arm becomes the next arm's settled provenance — twice
-* in that campaign a wrong claim crossed run boundaries and became standing instruction before
-* anyone re-derived it. Isolation makes "what did THIS run learn" a directory listing, and the
-* knowledge delta between two runs a diff of two directories.
-*
-* A branch still inherits: reads walk the run's own store, then each ancestor up a recorded
-* parent chain, then an optional shared store — every page labeled with where it came from,
-* because "I established this", "an earlier attempt believed this", and "the lab curates this"
-* are three different provenance claims and a reader must be able to weigh them differently.
+* 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 chains longer than this indicate a cycle or a runaway, not a real lineage. */
+/** 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"));
-	async function parentOf(runId) {
-		try {
-			const snapshot = await readRegularFileWithinRoot(storePath(runId), RUN_LINEAGE_BASENAME);
-			return JSON.parse(snapshot.bytes.toString("utf8")).parentRunId;
-		} catch (error) {
-			if (isMissingFile(error)) return null;
-			throw error;
+	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));
-			const record = {
+			if (authority.record) await authority.record(Object.freeze({
 				runId,
-				parentRunId: initOptions.parentRunId ?? null,
+				parentRunId,
 				createdAt: (/* @__PURE__ */ new Date()).toISOString()
-			};
-			await writeJson(join(storePath(runId), RUN_LINEAGE_BASENAME), record);
+			}));
 			return layout;
 		},
-		async lineage(runId) {
-			const chain = [];
-			const seen = /* @__PURE__ */ new Set([runId]);
-			let current = runId;
-			for (let hop = 0; hop < MAX_LINEAGE_HOPS && current !== null; hop += 1) {
-				current = await parentOf(current);
-				if (current === null) break;
-				if (seen.has(current)) throw new Error(`run lineage cycle: ${current} is its own ancestor (via ${runId})`);
-				seen.add(current);
-				chain.push(current);
-			}
-			return chain;
-		},
+		lineage: resolveLineage,
 		async loadChain(runId) {
+			assertRunId(runId);
 			const out = [];
 			const readInto = async (root, origin) => {
 				let pages;
@@ -6687,13 +7363,80 @@ function createRunScopedStores(options) {
 				});
 			};
 			await readInto(storePath(runId), "here");
-			for (const ancestor of await this.lineage(runId)) await readInto(storePath(ancestor), `inherited:${ancestor}`);
+			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, KnowledgeBaseCandidateSchema, 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, assertDeepQuestionIntegrity, assertGradeableEvidence, assertResearchClaimEvidenceIntegrity, assertResearchClaimLedgerIntegrity, assertTrackedClaimIntegrity, 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, createFileSystemFreshnessStore, createFileSystemSearchProvider, createGraphitiMemoryAdapter, createInMemoryBenchmarkAdapter, createIrsPublicationsSource, createKnowledgeControlLoopAdapter, createKnowledgeEvent, 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, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, gradeFor, graphitiMemoryAdapterIdentity, groundClaimInText, hashKnowledgeBase, htmlToText, improveKnowledgeBase, initKnowledgeBase, innerHtmlById, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isKernelAnchoredPath, isKnowledgeMemoryBenchmarkCase, isMissingFile, isSafeKnowledgePath, isScaffoldPath, jsonCandidateCodec, jsonObjectCandidateCodec, kbIndexToText, knowledgeBenchmarkJudge, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, linkClaimContradictions, 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, parseKnowledgeWriteBlocks, partitionRetrievalScenarios, politeFetch, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, readRegularFileNoFollow, readRegularFileWithinRoot, reciprocalRankFusion, recoverPendingKnowledgeMutation, removeDurable, renameDurable, renderKnowledgeBenchmarkReportMarkdown, renderMemoryContext, researchSourceVersionKey, resetRetrievalHoldoutRegistry, resolveMemoryCleanupTimeoutMs, 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, withCitedClaim, withKnowledgeImprovementCandidate, withKnowledgeImprovementComparison, withKnowledgeMutation, withKnowledgeRead, withSafeDescendant, withSafeDirectory, writeFileDurable, writeFileDurableWithinRoot, writeJson, writeJsonDurable, writeJsonDurableWithinRoot, writeKnowledgeIndex, writeSourceRegistry };
+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 };
 
 //# sourceMappingURL=index.js.map