@tangle-network/agent-knowledge 14.0.2 → 15.0.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as formatKnowledgeCitationReference, $t as inspectPendingKnowledgeMutation, A as addSourceText, An as writeJsonDurableWithinRoot, At as ResearchSourceVersionSchema, B as KB_STORE_DIR, Bt as claimId, C as gradeClaims, Cn as renameDurable, Ct as KnowledgePageSchema, D as buildKnowledgeIndex, Dn as writeFileDurable, Dt as ResearchClaimEvidenceSchema, E as verifyGradeableEvidence, En as withSafeDirectory, Et as KnowledgeRelationSchema, F as ClaimLedgerMigrationRequiredError, Ft as assertDeepQuestionIntegrity, G as KnowledgeCitationAuditError, Gt as materializeRegisteredClaimEvidence, H as assertClaimLedgerId, Ht as deepQuestionId, I as FileSystemKbStore, It as assertResearchClaimEvidenceIntegrity, J as assertKnowledgeCitationAudit, Jt as normalizeClaimText, K as KnowledgeCitationResolutionError, Kt as mergeClaimLedgers, L as KB_CLAIM_LEDGER_DIR, Lt as assertResearchClaimLedgerIntegrity, M as snapshotSourceTextInput, Mn as textSourceAdapter, Mt as SourceRecordSchema, N as sourceRegistryPath, Nt as KNOWLEDGE_EVENT_TYPES, O as writeKnowledgeIndex, On as writeFileDurableWithinRoot, Ot as ResearchClaimLedgerSchema, P as writeSourceRegistry, Pt as ClaimLedgerGoalConflictError, Q as auditKnowledgeCitations, Qt as acquireDurableFileLock, R as KB_EVENTS_PATH, Rt as assertTrackedClaimIntegrity, S as claimCheckKey, Sn as removeDurable, St as KnowledgePageInvalidationSchema, T as verdictFor, Tn as withSafeDescendant, Tt as KnowledgeRelationNodeSchema, U as buildKnowledgeGraph, Ut as emptyClaimLedger, V as MemoryKbStore, Vt as claimSourceHost, W as knowledgePageRelations, Wt as linkClaimContradictions, X as assertRunScopedCitationsResolved, Xt as formatFrontmatter, Y as assertKnowledgeCitationsResolved, Yt as researchSourceVersionKey, Z as auditCurrentRunCitations, Zt as parseFrontmatter, _ as lintKnowledgeIndex, _n as isMissingFile, _t as KnowledgeBaseCandidateSchema, a as applyKnowledgeWriteBlocksFile, an as applyKnowledgeFileTransaction, at as SCAFFOLD_PAGE_BASENAMES, b as UncheckableClaimError, bn as readRegularFileWithinRoot, bt as KnowledgeGraphNodeSchema, c as KnowledgeDuplicateIntakeError, cn as finishKnowledgeFileTransaction, ct as isScaffoldPath, d as createFileRunLineageAuthority, dn as rollbackKnowledgeFileTransaction, dt as loadKnowledgePages, en as isKnowledgeMutationHeld, et as parseKnowledgeCitationReference, f as createRunScopedStores, fn as DEFAULT_PAGES_DIRECTORY, ft as writeJson, g as validateKnowledgeIndex, gn as isKernelAnchoredPath, gt as DeepQuestionSchema, h as normalizePageText, hn as canonicalRelativeWithinRoot, ht as normalizeLinkTarget, i as applyKnowledgeWriteBlocks, in as withKnowledgeRead, it as resolveRunScopedCitations, j as loadSourceRegistry, jn as mediaTypeFor, jt as SourceAnchorSchema, k as addSourcePath, kn as writeJsonDurable, kt as ResearchClaimRecordSchema, l as assertKnowledgeWriteIntake, ln as knowledgeFileTransactionPlanHash, lt as knowledgePageFromMarkdown, m as detectNearDuplicatePages, mn as canonicalPathsEqual, mt as extractWikilinks, n as inspectKnowledgeIndex, nn as runInKnowledgeMutationScope, nt as resolveKnowledgeCitations, o as isSafeKnowledgePath, on as assertKnowledgeMutationPath, ot as initKnowledgeBase, p as originatedPages, pn as normalizePagesDirectory, pt as WIKILINK_REGEX, q as assertCurrentRunCitationsResolved, qt as mergeTrackedClaims, r as stringMetadata, rn as withKnowledgeMutation, rt as resolveRunScopedCitation, s as parseKnowledgeWriteBlocks, sn as commitKnowledgeFileMutations, st as isKnowledgePagePath, t as explainKnowledgeTarget, tn as recoverPendingKnowledgeMutation, tt as resolveKnowledgeCitation, u as RUN_LINEAGE_BASENAME, un as prepareKnowledgeFileTransaction, ut as layoutFor, v as CHECKABLE_RUNG_THRESHOLD, vn as listRegularFilesWithinRoot, vt as KnowledgeEventSchema, w as gradeFor, wn as syncDirectory, wt as KnowledgeRelationGraphSchema, x as assertGradeableEvidence, xn as relativeWithinRoot, xt as KnowledgeIndexSchema, y as DEADLINE_EXIT_CODE, yn as readRegularFileNoFollow, yt as KnowledgeGraphEdgeSchema, z as KB_INDEX_PATH, zt as claimEvidenceId } from "./inspect-DCpUoPVb.js";
+import { $ as formatKnowledgeCitationReference, $t as inspectPendingKnowledgeMutation, A as addSourceText, An as writeJsonDurableWithinRoot, At as ResearchSourceVersionSchema, B as KB_STORE_DIR, Bt as claimId, C as gradeClaims, Cn as renameDurable, Ct as KnowledgePageSchema, D as buildKnowledgeIndex, Dn as writeFileDurable, Dt as ResearchClaimEvidenceSchema, E as verifyGradeableEvidence, En as withSafeDirectory, Et as KnowledgeRelationSchema, F as ClaimLedgerMigrationRequiredError, Ft as assertDeepQuestionIntegrity, G as KnowledgeCitationAuditError, Gt as materializeRegisteredClaimEvidence, H as assertClaimLedgerId, Ht as deepQuestionId, I as FileSystemKbStore, It as assertResearchClaimEvidenceIntegrity, J as assertKnowledgeCitationAudit, Jt as normalizeClaimText, K as KnowledgeCitationResolutionError, Kt as mergeClaimLedgers, L as KB_CLAIM_LEDGER_DIR, Lt as assertResearchClaimLedgerIntegrity, M as snapshotSourceTextInput, Mn as textSourceAdapter, Mt as SourceRecordSchema, N as sourceRegistryPath, Nt as KNOWLEDGE_EVENT_TYPES, O as writeKnowledgeIndex, On as writeFileDurableWithinRoot, Ot as ResearchClaimLedgerSchema, P as writeSourceRegistry, Pt as ClaimLedgerGoalConflictError, Q as auditKnowledgeCitations, Qt as acquireDurableFileLock, R as KB_EVENTS_PATH, Rt as assertTrackedClaimIntegrity, S as claimCheckKey, Sn as removeDurable, St as KnowledgePageInvalidationSchema, T as verdictFor, Tn as withSafeDescendant, Tt as KnowledgeRelationNodeSchema, U as buildKnowledgeGraph, Ut as emptyClaimLedger, V as MemoryKbStore, Vt as claimSourceHost, W as knowledgePageRelations, Wt as linkClaimContradictions, X as assertRunScopedCitationsResolved, Xt as formatFrontmatter, Y as assertKnowledgeCitationsResolved, Yt as researchSourceVersionKey, Z as auditCurrentRunCitations, Zt as parseFrontmatter, _ as lintKnowledgeIndex, _n as isMissingFile, _t as KnowledgeBaseCandidateSchema, a as applyKnowledgeWriteBlocksFile, an as applyKnowledgeFileTransaction, at as SCAFFOLD_PAGE_BASENAMES, b as UncheckableClaimError, bn as readRegularFileWithinRoot, bt as KnowledgeGraphNodeSchema, c as KnowledgeDuplicateIntakeError, cn as finishKnowledgeFileTransaction, ct as isScaffoldPath, d as createFileRunLineageAuthority, dn as rollbackKnowledgeFileTransaction, dt as loadKnowledgePages, en as isKnowledgeMutationHeld, et as parseKnowledgeCitationReference, f as createRunScopedStores, fn as DEFAULT_PAGES_DIRECTORY, ft as writeJson, g as validateKnowledgeIndex, gn as isKernelAnchoredPath, gt as DeepQuestionSchema, h as normalizePageText, hn as canonicalRelativeWithinRoot, ht as normalizeLinkTarget, i as applyKnowledgeWriteBlocks, in as withKnowledgeRead, it as resolveRunScopedCitations, j as loadSourceRegistry, jn as mediaTypeFor, jt as SourceAnchorSchema, k as addSourcePath, kn as writeJsonDurable, kt as ResearchClaimRecordSchema, l as assertKnowledgeWriteIntake, ln as knowledgeFileTransactionPlanHash, lt as knowledgePageFromMarkdown, m as detectNearDuplicatePages, mn as canonicalPathsEqual, mt as extractWikilinks, n as inspectKnowledgeIndex, nn as runInKnowledgeMutationScope, nt as resolveKnowledgeCitations, o as isSafeKnowledgePath, on as assertKnowledgeMutationPath, ot as initKnowledgeBase, p as originatedPages, pn as normalizePagesDirectory, pt as WIKILINK_REGEX, q as assertCurrentRunCitationsResolved, qt as mergeTrackedClaims, r as stringMetadata, rn as withKnowledgeMutation, rt as resolveRunScopedCitation, s as parseKnowledgeWriteBlocks, sn as commitKnowledgeFileMutations, st as isKnowledgePagePath, t as explainKnowledgeTarget, tn as recoverPendingKnowledgeMutation, tt as resolveKnowledgeCitation, u as RUN_LINEAGE_BASENAME, un as prepareKnowledgeFileTransaction, ut as layoutFor, v as CHECKABLE_RUNG_THRESHOLD, vn as listRegularFilesWithinRoot, vt as KnowledgeEventSchema, w as gradeFor, wn as syncDirectory, wt as KnowledgeRelationGraphSchema, x as assertGradeableEvidence, xn as relativeWithinRoot, xt as KnowledgeIndexSchema, y as DEADLINE_EXIT_CODE, yn as readRegularFileNoFollow, yt as KnowledgeGraphEdgeSchema, z as KB_INDEX_PATH, zt as claimEvidenceId } from "./inspect-DMZXOQYl.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-BxwOtvd7.js";
 import { C as sleepForMemoryRecovery, F as buildIndustryRagBenchmarkSmokeCases, G as buildRetrievalEvalDispatch, H as createNoopMemoryBenchmarkAdapter, I as respondToIndustryMemoryBenchmarkSmokeCase, J as retrievalConfigSurface, K as partitionRetrievalScenarios, L as respondToIndustryRagBenchmarkSmokeCase, M as INDUSTRY_RAG_BENCHMARKS, N as buildFirstPartyMemoryLifecycleBenchmarkCases, P as buildIndustryMemoryBenchmarkSmokeCases, R as isKnowledgeMemoryBenchmarkCase, S as runBoundedMemoryLifecycle, U as memoryHitToSourceRecord, V as createInMemoryBenchmarkAdapter, W as memoryWriteResultToSourceRecord, X as scoreRetrievalArtifact, Y as retrievalRecallJudge, Z as mean, 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 retrievalConfigFromSurface, r as parseKnowledgeBenchmarkQrels, s as renderKnowledgeBenchmarkReportMarkdown, t as buildRetrievalBenchmarkCasesFromQrels, u as scoreMemoryBenchmarkArtifact, x as resolveMemoryCleanupTimeoutMs, y as createMemoryExecutionPool } from "./benchmarks-BbPJdmHe.js";
@@ -6,13 +6,14 @@ import { a as buildKnowledgeLexicalIndex, c as tokenizeText, i as searchKnowledg
 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, join, relative } from "node:path";
+import { dirname, join } from "node:path";
 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";
 import { tmpdir } from "node:os";
 import { isDeepStrictEqual } from "node:util";
+import { pathToFileURL } from "node:url";
 //#region src/web-research-worker.ts
 /**
 * Real web-research worker + verifying driver for `runVerifiedResearchLoop`.
@@ -685,6 +686,20 @@ function createAdaptiveResearchDriver(options = {}) {
 	};
 }
 //#endregion
+//#region src/knowledge-state-scope.ts
+const knowledgeStateScopeSchema = z.object({
+	pagesDirectory: z.string().transform((value) => normalizePagesDirectory(value)).optional(),
+	researchState: z.boolean().optional()
+}).strict();
+function normalizeKnowledgeStateScope(scope = {}) {
+	const parsed = knowledgeStateScopeSchema.parse(scope);
+	return {
+		pagesDirectory: normalizePagesDirectory(parsed.pagesDirectory),
+		researchState: parsed.researchState ?? false
+	};
+}
+const KNOWLEDGE_RESEARCH_STATE_PATHS = [".agent-knowledge/claim-ledgers", ".agent-knowledge/events.json"];
+//#endregion
 //#region src/kb-improvement/contracts.ts
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
 const immutableRefSchema = z.string().regex(/^(?:sha256:[a-f0-9]{64}|git:[a-f0-9]{40})$/);
@@ -770,6 +785,7 @@ const candidateRecordSchema = z.object({
 	updatedAt: z.iso.datetime()
 }).strict();
 const KnowledgeImprovementRunStateSchema = z.object({
+	stateScope: knowledgeStateScopeSchema.optional(),
 	runId: runIdSchema,
 	root: z.string().min(1),
 	goal: z.string().min(1),
@@ -2263,7 +2279,7 @@ function createKnowledgeControlLoopAdapter(options) {
 				await initKnowledgeBase(options.root);
 				initialized = true;
 			}
-			const index = await buildKnowledgeIndex(options.root);
+			const index = await buildKnowledgeIndex(options.root, options);
 			const validation = validateKnowledgeIndex(index, { strict: options.strict });
 			const lintFindings = lintKnowledgeIndex(index);
 			const readiness = readinessFor(options, index);
@@ -2316,7 +2332,7 @@ async function runKnowledgeResearchLoop(options) {
 	const maxIterations = Math.max(1, options.maxIterations ?? 3);
 	await initKnowledgeBase(options.root);
 	const steps = [];
-	let index = await buildKnowledgeIndex(options.root);
+	let index = await buildKnowledgeIndex(options.root, options);
 	let validation = validateKnowledgeIndex(index, { strict: options.strict });
 	let lintFindings = lintKnowledgeIndex(index);
 	let readiness = readinessFor(options, index);
@@ -2336,7 +2352,7 @@ async function runKnowledgeResearchLoop(options) {
 		});
 		done = Boolean(decision.done);
 		const step = await applyKnowledgeResearchDecision(options, decision, iteration);
-		index = await buildKnowledgeIndex(options.root);
+		index = await buildKnowledgeIndex(options.root, options);
 		validation = step.validation;
 		lintFindings = step.lintFindings;
 		readiness = step.readiness;
@@ -2361,8 +2377,8 @@ async function applyKnowledgeResearchDecision(options, decision, iteration = 1)
 	const addedSources = [];
 	for (const sourcePath of decision.sourcePaths ?? []) addedSources.push(...await addSourcePath(options.root, sourcePath, options.sourceOptions));
 	for (const sourceText of decision.sourceTexts ?? []) addedSources.push(await addSourceText(options.root, sourceText, options.sourceOptions));
-	const applied = decision.proposalText ? await applyKnowledgeWriteBlocks(options.root, decision.proposalText) : void 0;
-	const index = await buildKnowledgeIndex(options.root);
+	const applied = decision.proposalText ? await applyKnowledgeWriteBlocks(options.root, decision.proposalText, { pagesDirectory: options.pagesDirectory }) : void 0;
+	const index = await buildKnowledgeIndex(options.root, options);
 	const validation = validateKnowledgeIndex(index, { strict: options.strict });
 	const lintFindings = lintKnowledgeIndex(index);
 	const readiness = readinessFor(options, index);
@@ -2735,6 +2751,7 @@ async function withKnowledgeImprovementComparison(options, use) {
 		const state = await loadKnowledgeImprovementStateFromRun(options.root, reference.runId, runDir);
 		return withMeasuredCandidateSnapshot(options.root, runDir, state, reference, (resolved) => withBaselineSnapshot(runDir, reference.baseHash, (baselineRoot) => withIsolatedKnowledgeCopy(baselineRoot, reference.baseHash, "baseline", (baseline) => withIsolatedKnowledgeCopy(resolved.root, reference.candidateHash, "candidate", (candidate) => use(Object.freeze({
 			reference,
+			stateScope: Object.freeze(normalizeKnowledgeStateScope(state.stateScope)),
 			evaluation: immutableJsonValue(structuredClone(resolved.evidence.evaluation)),
 			baseline: Object.freeze({
 				root: baseline,
@@ -2744,7 +2761,7 @@ async function withKnowledgeImprovementComparison(options, use) {
 				root: candidate,
 				hash: reference.candidateHash
 			})
-		}))))));
+		})), state.stateScope), state.stateScope), state.stateScope));
 	});
 }
 /** Use the frozen candidate side of one measured comparison. */
@@ -2756,8 +2773,9 @@ async function withKnowledgeImprovementCandidate(options, use) {
 		return withMeasuredCandidateSnapshot(options.root, runDir, state, candidateRef, (resolved) => withIsolatedKnowledgeCopy(resolved.root, candidateRef.candidateHash, "candidate", (root) => use(Object.freeze({
 			root,
 			candidate: candidateRef,
+			stateScope: Object.freeze(normalizeKnowledgeStateScope(state.stateScope)),
 			evaluation: immutableJsonValue(structuredClone(resolved.evidence.evaluation))
-		}))));
+		})), state.stateScope));
 	});
 }
 function candidateRefFor(runId, state, candidate) {
@@ -2786,24 +2804,24 @@ async function withMeasuredCandidateSnapshot(liveRoot, runDir, state, candidateR
 	if (canonicalJson(candidateRefFor(candidateRef.runId, state, candidate)) !== canonicalJson(candidateRef)) throw new Error("knowledge candidate approval does not match the measured candidate");
 	const evidence = await assertCandidateEvidence(runDir, candidateRef, state.implementationRef);
 	return withSafeDirectory(runDir, join("candidates", candidate.candidateId, "snapshots", candidateRef.candidateHash), false, async (root) => {
-		if (await hashKnowledgeBase(root) !== candidateRef.candidateHash) throw new Error("knowledge candidate snapshot changed after approval");
+		if (await hashKnowledgeBase(root, state.stateScope) !== candidateRef.candidateHash) throw new Error("knowledge candidate snapshot changed after approval");
 		const result = await use({
 			root,
 			candidate,
 			evidence
 		});
-		if (await hashKnowledgeBase(root) !== candidateRef.candidateHash) throw new Error("knowledge candidate snapshot changed during use");
+		if (await hashKnowledgeBase(root, state.stateScope) !== candidateRef.candidateHash) throw new Error("knowledge candidate snapshot changed during use");
 		return result;
 	});
 }
-async function withIsolatedKnowledgeCopy(sourceRoot, expectedHash, target, use) {
+async function withIsolatedKnowledgeCopy(sourceRoot, expectedHash, target, use, scope) {
 	const isolationRoot = await mkdtemp(join(tmpdir(), "agent-knowledge-snapshot-"));
 	const snapshotRoot = join(isolationRoot, "snapshot");
 	try {
-		await copyKnowledgeWorkspace(sourceRoot, snapshotRoot);
-		if (await hashKnowledgeBase(snapshotRoot) !== expectedHash) throw new Error(`isolated knowledge ${target} does not match its measured content`);
+		await copyKnowledgeWorkspace(sourceRoot, snapshotRoot, scope);
+		if (await hashKnowledgeBase(snapshotRoot, scope) !== expectedHash) throw new Error(`isolated knowledge ${target} does not match its measured content`);
 		const result = await use(snapshotRoot);
-		if (await hashKnowledgeBase(snapshotRoot) !== expectedHash) throw new Error(`knowledge ${target} snapshot changed during use`);
+		if (await hashKnowledgeBase(snapshotRoot, scope) !== expectedHash) throw new Error(`knowledge ${target} snapshot changed during use`);
 		return result;
 	} finally {
 		await rm(isolationRoot, {
@@ -2828,7 +2846,7 @@ async function assertStateIdentity(root, candidateRef, state) {
 async function createCandidateWorkspace(runDir, state, root, now) {
 	const iteration = state.candidates.length + 1;
 	const candidateId = stableId("kcand", `${state.runId}:${iteration}:${now().toISOString()}`);
-	await copyKnowledgeWorkspace(root, candidateWorkspacePath(runDir, candidateId));
+	await copyKnowledgeWorkspace(root, candidateWorkspacePath(runDir, candidateId), state.stateScope);
 	const createdAt = now().toISOString();
 	return {
 		iteration,
@@ -2845,10 +2863,10 @@ function candidateWorkspacePath(runDir, candidateId) {
 function baselineSnapshotPath(runDir) {
 	return join(runDir, "baseline");
 }
-async function createBaselineSnapshot(runDir, root, expectedHash) {
+async function createBaselineSnapshot(runDir, root, expectedHash, scope) {
 	const target = baselineSnapshotPath(runDir);
 	try {
-		await assertBaselineSnapshot(runDir, expectedHash);
+		await assertBaselineSnapshot(runDir, expectedHash, scope);
 		return;
 	} catch (error) {
 		if (!isMissingFile(error)) throw error;
@@ -2856,8 +2874,8 @@ async function createBaselineSnapshot(runDir, root, expectedHash) {
 	const preparation = await mkdtemp(join(runDir, "baseline-prepare-"));
 	let activated = false;
 	try {
-		await copyKnowledgeWorkspace(root, preparation);
-		const actualHash = await hashKnowledgeBase(preparation);
+		await copyKnowledgeWorkspace(root, preparation, scope);
+		const actualHash = await hashKnowledgeBase(preparation, scope);
 		if (actualHash !== expectedHash) throw new Error(`knowledge base changed while baseline was frozen: expected ${expectedHash}, got ${actualHash}`);
 		await renameDurable(preparation, target);
 		activated = true;
@@ -2868,35 +2886,35 @@ async function createBaselineSnapshot(runDir, root, expectedHash) {
 		});
 	}
 }
-async function ensureBaselineSnapshot(runDir, root, expectedHash) {
+async function ensureBaselineSnapshot(runDir, root, expectedHash, scope) {
 	try {
-		await assertBaselineSnapshot(runDir, expectedHash);
+		await assertBaselineSnapshot(runDir, expectedHash, scope);
 	} catch (error) {
 		if (!isMissingFile(error)) throw error;
-		if (await hashKnowledgeBase(root) !== expectedHash) throw new Error("knowledge improvement baseline snapshot is missing and cannot be reconstructed");
-		await createBaselineSnapshot(runDir, root, expectedHash);
+		if (await hashKnowledgeBase(root, scope) !== expectedHash) throw new Error("knowledge improvement baseline snapshot is missing and cannot be reconstructed");
+		await createBaselineSnapshot(runDir, root, expectedHash, scope);
 	}
 }
-async function assertBaselineSnapshot(runDir, expectedHash) {
-	await withBaselineSnapshot(runDir, expectedHash, () => void 0);
+async function assertBaselineSnapshot(runDir, expectedHash, scope) {
+	await withBaselineSnapshot(runDir, expectedHash, () => void 0, scope);
 }
-async function withBaselineSnapshot(runDir, expectedHash, use) {
+async function withBaselineSnapshot(runDir, expectedHash, use, scope) {
 	return withSafeDirectory(runDir, "baseline", false, async (baselineRoot) => {
-		const actualHash = await hashKnowledgeBase(baselineRoot);
+		const actualHash = await hashKnowledgeBase(baselineRoot, scope);
 		if (actualHash !== expectedHash) throw new Error(`knowledge improvement baseline changed: expected ${expectedHash}, got ${actualHash}`);
 		return use(baselineRoot);
 	});
 }
-async function withFrozenCandidateWorkspace(runDir, candidate, candidateRoot, use) {
+async function withFrozenCandidateWorkspace(runDir, candidate, candidateRoot, use, scope) {
 	return withSafeDirectory(runDir, join("candidates", safePathSegmentSchema.parse(candidate.candidateId), "snapshots"), true, async (snapshotsDir) => {
 		const preparation = await mkdtemp(join(snapshotsDir, "prepare-"));
 		let activated = false;
 		try {
-			await copyKnowledgeWorkspace(candidateRoot, preparation);
-			const hash = await hashKnowledgeBase(preparation);
+			await copyKnowledgeWorkspace(candidateRoot, preparation, scope);
+			const hash = await hashKnowledgeBase(preparation, scope);
 			try {
 				const result = await withSafeDirectory(snapshotsDir, hash, false, async (existing) => {
-					if (await hashKnowledgeBase(existing) !== hash) throw new Error("knowledge candidate snapshot does not match its content identity");
+					if (await hashKnowledgeBase(existing, scope) !== hash) throw new Error("knowledge candidate snapshot does not match its content identity");
 					return use({
 						root: existing,
 						hash
@@ -2930,17 +2948,27 @@ function clearCandidateMeasurement(candidate) {
 	delete candidate.evidenceHash;
 	delete candidate.promotionPlanHash;
 }
-async function copyKnowledgeWorkspace(sourceRoot, targetRoot) {
-	await rm(targetRoot, {
-		recursive: true,
-		force: true
+async function copyKnowledgeWorkspace(sourceRoot, targetRoot, scope) {
+	const normalized = normalizeKnowledgeStateScope(scope);
+	await withKnowledgeRead(sourceRoot, async () => {
+		await rm(targetRoot, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(join(targetRoot, normalized.pagesDirectory), { recursive: true });
+		await mkdir(join(targetRoot, "raw", "sources"), { recursive: true });
+		for (const path of knowledgeScopePaths(normalized)) await copyIfExists(join(sourceRoot, path), join(targetRoot, path));
 	});
-	await mkdir(join(targetRoot, "knowledge"), { recursive: true });
-	await mkdir(join(targetRoot, "raw", "sources"), { recursive: true });
-	await copyIfExists(join(sourceRoot, "knowledge"), join(targetRoot, "knowledge"));
-	await copyIfExists(join(sourceRoot, "raw"), join(targetRoot, "raw"));
-	await copyIfExists(join(layoutFor(sourceRoot).cacheDir, "sources.json"), join(layoutFor(targetRoot).cacheDir, "sources.json"));
-	await writeKnowledgeIndex(targetRoot);
+	await writeKnowledgeIndex(targetRoot, { pagesDirectory: normalized.pagesDirectory });
+}
+function knowledgeScopePaths(scope) {
+	const normalized = normalizeKnowledgeStateScope(scope);
+	return [
+		normalized.pagesDirectory,
+		"raw",
+		".agent-knowledge/sources.json",
+		...normalized.researchState ? KNOWLEDGE_RESEARCH_STATE_PATHS : []
+	];
 }
 async function copyIfExists(source, target) {
 	let sourceStat;
@@ -2957,28 +2985,29 @@ async function copyIfExists(source, target) {
 		dereference: false
 	});
 }
-async function hashKnowledgeBase(root) {
-	return withKnowledgeRead(root, () => hashKnowledgeBaseUnlocked(root));
+async function hashKnowledgeBase(root, scope) {
+	return withKnowledgeRead(root, () => hashKnowledgeBaseUnlocked(root, scope));
 }
-async function hashKnowledgeBaseUnlocked(root) {
-	const entries = await knowledgeHashEntries(root);
-	return sha256(JSON.stringify(entries.map(({ path, hash, mode }) => ({
+async function hashKnowledgeBaseUnlocked(root, scope) {
+	const normalized = normalizeKnowledgeStateScope(scope);
+	const files = (await knowledgeHashEntries(root, normalized)).map(({ path, hash, mode }) => ({
 		path,
 		hash,
 		mode
-	}))));
+	}));
+	return sha256(JSON.stringify(normalized.pagesDirectory === "knowledge" && !normalized.researchState ? files : {
+		scope: normalized,
+		files
+	}));
 }
-async function knowledgeHashEntries(root) {
+async function knowledgeHashEntries(root, scope) {
 	const entries = [];
-	for (const rel of ["knowledge", "raw"]) try {
-		for (const file of await listRegularFilesWithinRoot(root, rel)) entries.push(knowledgeFileIdentity(file.path, file.bytes, file.mode));
-	} catch (error) {
-		if (!isMissingFile(error)) throw error;
-	}
-	const sourceRegistry = relative(root, layoutFor(root).sourceRegistryPath).replace(/\\/g, "/");
-	try {
-		const file = await readRegularFileWithinRoot(root, sourceRegistry);
-		entries.push(knowledgeFileIdentity(sourceRegistry, file.bytes, file.mode));
+	for (const path of knowledgeScopePaths(scope ?? {})) try {
+		const files = path === ".agent-knowledge/sources.json" || path === ".agent-knowledge/events.json" ? [{
+			...await readRegularFileWithinRoot(root, path),
+			path
+		}] : await listRegularFilesWithinRoot(root, path);
+		for (const file of files) entries.push(knowledgeFileIdentity(file.path, file.bytes, file.mode));
 	} catch (error) {
 		if (!isMissingFile(error)) throw error;
 	}
@@ -3054,7 +3083,7 @@ async function applyKnowledgeCandidateTarget(input, target) {
 		if (existingActivation) {
 			if (recovery?.direction === "rollback") throw new Error("stored knowledge activation result conflicts with a pending rollback");
 			if (recovery) {
-				if (await hashKnowledgeBase(input.root) !== existingActivation.mutation.afterHash) throw new Error("stored knowledge activation result does not match the recovered files");
+				if (await hashKnowledgeBase(input.root, state.stateScope) !== existingActivation.mutation.afterHash) throw new Error("stored knowledge activation result does not match the recovered files");
 				await finishKnowledgeFileTransaction({
 					root: input.root,
 					transactionRoot,
@@ -3079,7 +3108,7 @@ async function applyKnowledgeCandidateTarget(input, target) {
 		});
 		const recovered = recovery?.direction === "apply" ? recovery : void 0;
 		let pending = input.activation && recovered ? recovered.transaction : null;
-		const currentHash = await hashKnowledgeBase(input.root);
+		const currentHash = await hashKnowledgeBase(input.root, state.stateScope);
 		let transactionId = recovered?.transactionId ?? null;
 		if (recovered && currentHash !== desiredHash) throw new Error(`recovered knowledge ${action} does not match the approved target`);
 		if (state.status === "promoted" && state.promotedCandidateId !== candidate.candidateId) throw new Error(`knowledge run already promoted '${state.promotedCandidateId ?? "unknown"}'`);
@@ -3106,22 +3135,23 @@ async function applyKnowledgeCandidateTarget(input, target) {
 			pending = await withMeasuredCandidateSnapshot(input.root, runDir, state, candidateRef, (resolved) => withBaselineSnapshot(runDir, state.baseHash, async (baselineRoot) => {
 				const sourceRoot = target === "candidate" ? baselineRoot : resolved.root;
 				const targetRoot = target === "candidate" ? resolved.root : baselineRoot;
-				const plan = await knowledgeFilePlanEntries(sourceRoot, targetRoot);
-				assertCandidateTransitionPlan(plan, candidateRef, target);
+				const plan = await knowledgeFilePlanEntries(sourceRoot, targetRoot, state.stateScope);
+				assertCandidateTransitionPlan(plan, candidateRef, target, state.stateScope);
 				return prepareKnowledgeFileTransaction({
 					root: input.root,
 					transactionRoot,
 					purpose,
+					...normalizeKnowledgeStateScope(state.stateScope),
 					recoveryOwner,
 					mutations: await knowledgePlanMutations(targetRoot, plan),
 					includeUnchanged: true,
 					now: input.now
 				});
-			}));
+			}, state.stateScope));
 			if (!pending) throw new Error(`knowledge ${action} plan unexpectedly contained no file changes`);
 			transactionId = pending.transactionId;
 			try {
-				assertCandidateTransitionTransaction(pending, candidateRef, target);
+				assertCandidateTransitionTransaction(pending, candidateRef, target, state.stateScope);
 			} catch (error) {
 				try {
 					await rollbackKnowledgeFileTransaction({
@@ -3150,8 +3180,8 @@ async function applyKnowledgeCandidateTarget(input, target) {
 				beforeCommit: assertOwned
 			});
 			assertOwned();
-			if (await hashKnowledgeBase(input.root) !== desiredHash) throw new Error(`knowledge ${action} content does not match the approved target`);
-			await writeKnowledgeIndex(input.root);
+			if (await hashKnowledgeBase(input.root, state.stateScope) !== desiredHash) throw new Error(`knowledge ${action} content does not match the approved target`);
+			await writeKnowledgeIndex(input.root, state.stateScope);
 		} catch (error) {
 			if (!pending) throw error;
 			if (recovered && input.activation) throw error;
@@ -3173,7 +3203,7 @@ async function applyKnowledgeCandidateTarget(input, target) {
 					transaction: pending,
 					assertOwned
 				});
-				await writeKnowledgeIndex(input.root);
+				await writeKnowledgeIndex(input.root, state.stateScope);
 			} catch (rollbackError) {
 				throw new AggregateError([error, rollbackError], `knowledge ${action} failed and could not restore the previous files`);
 			}
@@ -3188,7 +3218,7 @@ async function applyKnowledgeCandidateTarget(input, target) {
 		state.updatedAt = input.now().toISOString();
 		await saveState(runDir, state, input.onState);
 		await ensureCandidateTransitionEvent(runDir, candidateRef, target);
-		let finalHash = await hashKnowledgeBase(input.root);
+		let finalHash = await hashKnowledgeBase(input.root, state.stateScope);
 		if (finalHash !== desiredHash) throw new Error(`knowledge ${action} changed before its result was returned`);
 		const mutation = Object.freeze({
 			target,
@@ -3199,14 +3229,14 @@ async function applyKnowledgeCandidateTarget(input, target) {
 			recovered: recovered !== void 0
 		});
 		const activationResult = input.activation ? await persistKnowledgeActivationResult(runDir, candidateRef, input.activation, target, mutation) : void 0;
-		if (await hashKnowledgeBase(input.root) !== finalHash) throw new Error(`knowledge ${action} changed while its result was persisted`);
+		if (await hashKnowledgeBase(input.root, state.stateScope) !== finalHash) throw new Error(`knowledge ${action} changed while its result was persisted`);
 		if (pending) await finishKnowledgeFileTransaction({
 			root: input.root,
 			transactionRoot,
 			transaction: pending,
 			assertOwned
 		});
-		finalHash = await hashKnowledgeBase(input.root);
+		finalHash = await hashKnowledgeBase(input.root, state.stateScope);
 		if (finalHash !== desiredHash) throw new Error(`knowledge ${action} changed before its result was returned`);
 		return candidateTransitionResult(input, candidate, target === "candidate", false, mutation, activationResult);
 	}, {
@@ -3214,7 +3244,7 @@ async function applyKnowledgeCandidateTarget(input, target) {
 		resumeTransaction: {
 			purpose,
 			recoveryOwner,
-			validate: (transaction) => assertCandidateTransitionTransaction(transaction, candidateRef, target),
+			validate: (transaction) => assertCandidateTransitionTransaction(transaction, candidateRef, target, state.stateScope),
 			deferFinish: input.activation !== void 0
 		}
 	});
@@ -3262,12 +3292,12 @@ function knowledgeCandidateTransitionPurpose(candidate, implementationRef, targe
 		implementationRef
 	})}`;
 }
-async function knowledgeFilePlanEntries(sourceRoot, targetRoot) {
-	const [before, after] = await Promise.all([knowledgeHashEntries(sourceRoot), knowledgeHashEntries(targetRoot)]);
+async function knowledgeFilePlanEntries(sourceRoot, targetRoot, scope) {
+	const [before, after] = await Promise.all([knowledgeHashEntries(sourceRoot, scope), knowledgeHashEntries(targetRoot, scope)]);
 	const beforeByPath = new Map(before.map((entry) => [entry.path, entry]));
 	const afterByPath = new Map(after.map((entry) => [entry.path, entry]));
 	return [.../* @__PURE__ */ new Set([...before.map((entry) => entry.path), ...after.map((entry) => entry.path)])].sort((left, right) => left.localeCompare(right)).map((path) => {
-		assertKnowledgeMutationPath(path, KB_IMPROVEMENT_PAGES_DIRECTORY);
+		assertKnowledgeMutationPath(path, normalizeKnowledgeStateScope(scope).pagesDirectory, scope?.researchState);
 		const beforeEntry = beforeByPath.get(path);
 		const afterEntry = afterByPath.get(path);
 		return {
@@ -3294,12 +3324,12 @@ async function knowledgePlanMutations(targetRoot, plan) {
 		};
 	}));
 }
-function assertCandidateTransitionPlan(plan, candidate, target) {
-	const actualPlanHash = knowledgeFileTransactionPlanHash(target === "candidate" ? plan : reverseKnowledgeFilePlan(plan), KB_IMPROVEMENT_PAGES_DIRECTORY);
+function assertCandidateTransitionPlan(plan, candidate, target, scope) {
+	const actualPlanHash = knowledgeFileTransactionPlanHash(target === "candidate" ? plan : reverseKnowledgeFilePlan(plan), normalizeKnowledgeStateScope(scope).pagesDirectory, scope?.researchState);
 	if (actualPlanHash !== candidate.promotionPlanHash) throw new Error(`knowledge candidate plan changed after approval: expected ${candidate.promotionPlanHash}, got ${actualPlanHash}`);
 }
-function assertCandidateTransitionTransaction(transaction, candidate, target) {
-	assertCandidateTransitionPlan(transaction.entries, candidate, target);
+function assertCandidateTransitionTransaction(transaction, candidate, target, scope) {
+	assertCandidateTransitionPlan(transaction.entries, candidate, target, scope);
 }
 function reverseKnowledgeFilePlan(plan) {
 	return plan.map((entry) => ({
@@ -3335,6 +3365,7 @@ async function hasCandidateTransitionEvent(runDir, candidateRef, target) {
 //#region src/kb-improvement/evaluation.ts
 function assertKnowledgeImprovementOptions(options) {
 	assertImmutableRef(options.implementationRef, "knowledge improvement implementationRef");
+	normalizeKnowledgeStateScope(options.stateScope);
 	for (const phase of options.requiredPhases ?? []) if (options.enabledPhases && !options.enabledPhases.includes(phase)) throw new Error(`required phase ${phase} is not enabled`);
 	if (options.answerQualityCostCeiling !== void 0 && (!Number.isFinite(options.answerQualityCostCeiling) || options.answerQualityCostCeiling < 0)) throw new Error("knowledge improvement answerQualityCostCeiling must be a non-negative finite number");
 	if (options.ragOptimization) assertImmutableRef(options.ragOptimization.executionRef, "knowledge improvement RAG executionRef");
@@ -3344,7 +3375,7 @@ function assertKnowledgeImprovementOptions(options) {
 }
 async function measureCandidate(runId, runDir, state, candidate, options, now) {
 	return withCandidateWorkspace(runDir, candidate, async (candidateRoot) => {
-		const currentCandidateHash = await hashKnowledgeBase(candidateRoot);
+		const currentCandidateHash = await hashKnowledgeBase(candidateRoot, options.stateScope);
 		if (candidate.status === "candidate-ready" && candidate.candidateHash === currentCandidateHash && candidate.evidenceHash !== void 0 && candidate.promotionPlanHash !== void 0) {
 			const evidence = await assertCandidateEvidence(runDir, candidateRefFor(runId, state, candidate), state.implementationRef);
 			return {
@@ -3379,7 +3410,7 @@ async function measureCandidate(runId, runDir, state, candidate, options, now) {
 				...lifecycle ? { lifecycle } : {},
 				finalEvaluated: true
 			};
-		});
+		}, options.stateScope);
 	});
 }
 async function runCandidateUpdateLifecycle(runId, candidate, candidateRoot, options, now) {
@@ -3398,7 +3429,7 @@ async function runCandidateUpdateLifecycle(runId, candidate, candidateRoot, opti
 }
 async function runCandidateEvaluationLifecycle(runId, runDir, candidate, candidateRoot, candidateHash, lifecycle, options, now) {
 	if (!shouldRunEvaluationStage(options)) return void 0;
-	const candidateIndex = await buildKnowledgeIndex(candidateRoot);
+	const candidateIndex = await buildKnowledgeIndex(candidateRoot, options.stateScope);
 	return withBaselineSnapshot(runDir, candidate.baseHash, (baselineRoot) => runRagKnowledgeImprovementPhases({
 		goal: options.goal,
 		optimization: options.ragOptimization ? {
@@ -3430,7 +3461,7 @@ async function runCandidateEvaluationLifecycle(runId, runDir, candidate, candida
 		requiredPhases: selectedStageRequiredPhases(options, EVALUATION_PHASES),
 		signal: options.signal,
 		now
-	}, lifecycle));
+	}, lifecycle), options.stateScope);
 }
 function candidateExecutionRef(executionRef, candidateHash) {
 	return `sha256:${sha256(`${executionRef}\n${candidateHash}`)}`;
@@ -3442,6 +3473,7 @@ function candidateKnowledgeResearchOptions(candidateRoot, options) {
 	return {
 		...rest,
 		root: candidateRoot,
+		pagesDirectory: normalizeKnowledgeStateScope(options.stateScope).pagesDirectory,
 		step,
 		maxIterations: rest.maxIterations ?? (step ? options.candidateResearchIterations ?? 3 : void 0),
 		strict: rest.strict ?? options.strict,
@@ -3481,7 +3513,7 @@ function selectedStageRequiredPhases(options, stagePhases) {
 }
 async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle, options, now, useConfiguredEvaluator) {
 	return withBaselineSnapshot(runDir, state.baseHash, async (baselineRoot) => {
-		const [baselineIndex, candidateIndex] = await Promise.all([buildKnowledgeIndex(baselineRoot), buildKnowledgeIndex(snapshot.root)]);
+		const [baselineIndex, candidateIndex] = await Promise.all([buildKnowledgeIndex(baselineRoot, options.stateScope), buildKnowledgeIndex(snapshot.root, options.stateScope)]);
 		const validation = validateKnowledgeIndex(candidateIndex, { strict: options.strict });
 		const readiness = readinessFor(options, candidateIndex);
 		const kbQuality = scoreKnowledgeBaseIndex(candidateIndex, {
@@ -3506,10 +3538,10 @@ async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle,
 			lifecycle,
 			signal: options.signal
 		}) : void 0) ?? defaultKnowledgeImprovementMetric(validation, readiness, options.readinessSpecs, kbQuality, lifecycle))), lifecycle, options.answerQualityCostCeiling);
-		const measuredHash = await hashKnowledgeBase(snapshot.root);
+		const measuredHash = await hashKnowledgeBase(snapshot.root, options.stateScope);
 		if (measuredHash !== candidateHash) throw new Error(`knowledge candidate changed during evaluation: expected ${candidateHash}, got ${measuredHash}`);
 		candidate.candidateHash = candidateHash;
-		candidate.promotionPlanHash = knowledgeFileTransactionPlanHash(await knowledgeFilePlanEntries(baselineRoot, snapshot.root), KB_IMPROVEMENT_PAGES_DIRECTORY);
+		candidate.promotionPlanHash = knowledgeFileTransactionPlanHash(await knowledgeFilePlanEntries(baselineRoot, snapshot.root, options.stateScope), normalizeKnowledgeStateScope(options.stateScope).pagesDirectory, options.stateScope?.researchState);
 		const evidence = KnowledgeImprovementEvidenceSchema.parse(JSON.parse(JSON.stringify({
 			kind: "knowledge-improvement-evidence",
 			runId: state.runId,
@@ -3540,7 +3572,7 @@ async function evaluateCandidate(runDir, state, candidate, snapshot, lifecycle,
 			candidate,
 			evaluation
 		};
-	});
+	}, options.stateScope);
 }
 function defaultKnowledgeImprovementMetric(validation, readiness, readinessSpecs, kbQuality, lifecycle) {
 	const blockingMissing = readiness?.report.blockingMissingRequirements.length ?? 0;
@@ -3590,6 +3622,10 @@ function normalizeMetric(metric) {
 //#region src/kb-improvement/run.ts
 async function improveKnowledgeBase(options) {
 	assertExactCandidatePlatform();
+	options = {
+		...options,
+		...options.stateScope === void 0 ? {} : { stateScope: Object.freeze(normalizeKnowledgeStateScope(options.stateScope)) }
+	};
 	assertKnowledgeImprovementOptions(options);
 	const now = options.now ?? (() => /* @__PURE__ */ new Date());
 	const runId = runIdSchema.parse(options.runId ?? knowledgeImprovementRunId(options.root, options.goal));
@@ -3607,13 +3643,14 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
 			throw error;
 		});
 		if (!state) {
-			const baseHash = await hashKnowledgeBase(options.root);
-			await createBaselineSnapshot(runDir, options.root, baseHash);
+			const baseHash = await hashKnowledgeBase(options.root, options.stateScope);
+			await createBaselineSnapshot(runDir, options.root, baseHash, options.stateScope);
 			state = {
 				runId,
 				root: options.root,
 				goal: options.goal,
 				implementationRef: options.implementationRef,
+				...options.stateScope === void 0 ? {} : { stateScope: normalizeKnowledgeStateScope(options.stateScope) },
 				status: "running",
 				baseHash,
 				createdAt: now().toISOString(),
@@ -3628,6 +3665,7 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
 				baseHash
 			});
 		}
+		if (canonicalJson(normalizeKnowledgeStateScope(state.stateScope)) !== canonicalJson(normalizeKnowledgeStateScope(options.stateScope))) throw new Error("knowledge improvement state does not match the requested stateScope");
 		if (state.goal !== options.goal) throw new Error("knowledge improvement state does not match the requested goal");
 		if (state.implementationRef !== options.implementationRef) throw new Error("knowledge improvement state does not match the requested implementationRef");
 		const promotedCandidateId = state.promotedCandidateId;
@@ -3637,7 +3675,7 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
 			const promoted = promotedCandidate;
 			const promotedState = state;
 			return withKnowledgeMutation(options.root, async () => {
-				const currentHash = await hashKnowledgeBase(options.root);
+				const currentHash = await hashKnowledgeBase(options.root, options.stateScope);
 				if (currentHash !== promoted.candidateHash) throw new Error(`promoted knowledge base changed: expected ${promoted.candidateHash}, got ${currentHash}`);
 				const evidence = await assertCandidateEvidence(runDir, candidateRefFor(runId, promotedState, promoted), promotedState.implementationRef);
 				return {
@@ -3651,7 +3689,7 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
 			});
 		}
 		await withKnowledgeMutation(options.root, () => void 0);
-		await ensureBaselineSnapshot(runDir, options.root, state.baseHash);
+		await ensureBaselineSnapshot(runDir, options.root, state.baseHash, state.stateScope);
 		if (state.status === "blocked") return {
 			runId,
 			state,
@@ -3675,7 +3713,7 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
 				};
 			}
 			if (!candidate) {
-				const currentHash = await hashKnowledgeBase(options.root);
+				const currentHash = await hashKnowledgeBase(options.root, options.stateScope);
 				if (currentHash !== state.baseHash) {
 					state = await blockRun(runDir, state, `base changed before candidate creation: expected ${state.baseHash}, got ${currentHash}`, options.onState, now);
 					return {
@@ -3686,7 +3724,7 @@ async function improveKnowledgeBaseInRun(options, runId, runDir, now) {
 					};
 				}
 				const activeState = state;
-				candidate = await withBaselineSnapshot(runDir, activeState.baseHash, (baselineRoot) => createCandidateWorkspace(runDir, activeState, baselineRoot, now));
+				candidate = await withBaselineSnapshot(runDir, activeState.baseHash, (baselineRoot) => createCandidateWorkspace(runDir, activeState, baselineRoot, now), state.stateScope);
 				state.candidates.push(candidate);
 				state.status = "running";
 				state.updatedAt = now().toISOString();
@@ -3769,7 +3807,7 @@ async function optimizeKnowledgeBasePolicy(options) {
 	if (typeof goal !== "string" || !goal.trim()) throw new Error("optimizeKnowledgeBasePolicy goal must be non-empty");
 	assertImmutableRef(policyApplicationRef, "optimizeKnowledgeBasePolicy policyApplicationRef");
 	if (candidateRunLabel !== void 0 && (typeof candidateRunLabel !== "string" || !candidateRunLabel.trim())) throw new Error("optimizeKnowledgeBasePolicy candidateRunLabel must be non-empty");
-	const baseHash = await hashKnowledgeBase(root);
+	const baseHash = await hashKnowledgeBase(root, candidate?.stateScope);
 	const optimization = await runSerializedKnowledgeOptimization({
 		...optimizationOptions,
 		executionRef: policyApplicationRef,
@@ -3780,7 +3818,7 @@ async function optimizeKnowledgeBasePolicy(options) {
 		finalScenarios
 	});
 	const winner = optimization.winner;
-	const currentBaseHash = await hashKnowledgeBase(root);
+	const currentBaseHash = await hashKnowledgeBase(root, candidate?.stateScope);
 	if (currentBaseHash !== baseHash) throw new Error(`knowledge base changed during policy optimization: expected ${baseHash}, got ${currentBaseHash}`);
 	const runId = stableId("kbpolicy", `${candidateRunLabel ?? "default"}:${goal}:${optimization.methodName}:${winner.surfaceHash}:${policyApplicationRef}:${baseHash}`);
 	return {
@@ -3818,10 +3856,13 @@ async function optimizeKnowledgeBasePolicy(options) {
 }
 //#endregion
 //#region src/kb-improvement/selected-candidate.ts
-const DERIVED_KNOWLEDGE_PATHS = /* @__PURE__ */ new Set([`${KB_IMPROVEMENT_PAGES_DIRECTORY}/index.md`]);
 const selectionPathSchema = z.string().min(1).transform((path, context) => {
 	try {
-		return assertKnowledgeMutationPath(path, KB_IMPROVEMENT_PAGES_DIRECTORY);
+		try {
+			return assertKnowledgeMutationPath(path, KB_IMPROVEMENT_PAGES_DIRECTORY, true);
+		} catch {
+			return normalizePagesDirectory(path);
+		}
 	} catch (error) {
 		context.addIssue({
 			code: "custom",
@@ -3881,11 +3922,13 @@ async function improveSelectedKnowledgeCandidate(options) {
 		root: options.root,
 		candidate: sourceCandidate
 	}, async (source) => {
-		const sourcePlan = await knowledgeFilePlanEntries(source.baseline.root, source.candidate.root);
-		const sourcePlanHash = knowledgeFileTransactionPlanHash(sourcePlan, KB_IMPROVEMENT_PAGES_DIRECTORY);
+		const scope = normalizeKnowledgeStateScope(source.stateScope);
+		if (options.stateScope !== void 0 && canonicalJson(normalizeKnowledgeStateScope(options.stateScope)) !== canonicalJson(scope)) throw new Error("selected knowledge candidate stateScope differs from its source");
+		const sourcePlan = await knowledgeFilePlanEntries(source.baseline.root, source.candidate.root, scope);
+		const sourcePlanHash = knowledgeFileTransactionPlanHash(sourcePlan, scope.pagesDirectory, scope.researchState);
 		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 changedSourcePlan = sourcePlan.filter(planEntryChanged).filter((entry) => notDerivedPath(entry, scope));
+		const selectedPaths = normalizeSelectedPaths(options.selectedPaths, changedSourcePlan, scope);
 		const selectionDigest = contentHash(immutableJson({
 			kind: "measured-knowledge-change-selection",
 			version: 1,
@@ -3911,11 +3954,12 @@ async function improveSelectedKnowledgeCandidate(options) {
 			if (!entry) throw new Error(`selected knowledge path disappeared: ${path}`);
 			return entry;
 		});
-		const selectionMutationPlanHash = knowledgeFileTransactionPlanHash(selectedEntries, KB_IMPROVEMENT_PAGES_DIRECTORY);
+		const selectionMutationPlanHash = knowledgeFileTransactionPlanHash(selectedEntries, scope.pagesDirectory, scope.researchState);
 		let lifecycleSelection;
 		const result = await improveKnowledgeBase({
 			...improvementOptions(options),
 			root: options.root,
+			stateScope: scope,
 			goal: options.goal,
 			implementationRef: derivedImplementationRef,
 			runId,
@@ -3931,6 +3975,7 @@ async function improveSelectedKnowledgeCandidate(options) {
 							root: input.candidateRoot,
 							transactionRoot: lock.transactionRoot,
 							purpose,
+							...scope,
 							recoveryOwner,
 							mutations: await selectionMutations(source.candidate.root, selectedEntries),
 							now: options.now
@@ -3951,17 +3996,17 @@ async function improveSelectedKnowledgeCandidate(options) {
 							});
 						}
 					}
-					await writeKnowledgeIndex(input.candidateRoot);
+					await writeKnowledgeIndex(input.candidateRoot, scope);
 					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, KB_IMPROVEMENT_PAGES_DIRECTORY);
-				const selectedCandidateHash = await hashKnowledgeBase(input.candidateRoot);
+				const selectedPlan = await knowledgeFilePlanEntries(source.baseline.root, input.candidateRoot, scope);
+				assertExactSelectedChanges(selectedPlan, selectedPaths, scope);
+				const selectedPlanHash = knowledgeFileTransactionPlanHash(selectedPlan, scope.pagesDirectory, scope.researchState);
+				const selectedCandidateHash = await hashKnowledgeBase(input.candidateRoot, scope);
 				lifecycleSelection = measuredSelectionLifecycleSchema.parse({
 					kind: "measured-knowledge-change-selection",
 					version: 1,
@@ -4021,13 +4066,13 @@ function normalizeEvaluationPhases(phases, field) {
 	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) {
+function normalizeSelectedPaths(paths, changedPlan, scope) {
 	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}`);
+		const path = assertKnowledgeMutationPath(selectionPathSchema.parse(input), normalizeKnowledgeStateScope(scope).pagesDirectory, scope.researchState);
+		if (!notDerivedPath({ path }, scope)) 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);
@@ -4038,8 +4083,8 @@ function normalizeSelectedPaths(paths, changedPlan) {
 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);
+function notDerivedPath(entry, scope) {
+	return entry.path !== `${normalizeKnowledgeStateScope(scope).pagesDirectory}/index.md`;
 }
 async function selectionMutations(sourceCandidateRoot, entries) {
 	return Promise.all(entries.map(async (entry) => {
@@ -4057,10 +4102,10 @@ async function selectionMutations(sourceCandidateRoot, entries) {
 	}));
 }
 function assertSelectionTransaction(transaction, expectedPlanHash) {
-	if (knowledgeFileTransactionPlanHash(transaction.entries, KB_IMPROVEMENT_PAGES_DIRECTORY) !== expectedPlanHash) throw new Error("selected knowledge transaction does not match its approved path set");
+	if (knowledgeFileTransactionPlanHash(transaction.entries, normalizePagesDirectory(transaction.pagesDirectory), transaction.researchState) !== 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));
+function assertExactSelectedChanges(plan, selectedPaths, scope) {
+	const actual = plan.filter(planEntryChanged).filter((entry) => notDerivedPath(entry, scope)).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) {
@@ -6582,6 +6627,17 @@ function isoTimestamp(value, label) {
 }
 //#endregion
 //#region src/knowledge-tools.ts
+/**
+* Provider-neutral knowledge tools.
+*
+* Knowledge owns what each tool does; a runtime only transports the definitions
+* and the calls. The shape is `ToolDefinition` from `@tangle-network/agent-interface`,
+* so no provider vocabulary reaches this package and no knowledge behavior
+* reaches a provider adapter.
+*
+* Every search mints a retrieval receipt. Configured receipt capture also
+* persists the exact visibility snapshot before delivering the receipt.
+*/
 const searchInput = z.object({
 	question: z.string().min(1),
 	limit: z.int().min(1).max(50).optional()
@@ -6606,6 +6662,8 @@ function createKnowledgeTools(options) {
 				...options.brief,
 				...input.limit === void 0 ? {} : { limit: input.limit }
 			});
+			const visibility = createKnowledgeVisibilitySnapshot(chain);
+			const visibilityArtifact = options.recordRetrieval ? await persistVisibility(stores.storePath(runId), visibility) : void 0;
 			const receipt = createKnowledgeRetrievalReceipt({
 				runId,
 				...options.actorId === void 0 ? {} : { actorId: options.actorId },
@@ -6615,7 +6673,8 @@ function createKnowledgeTools(options) {
 					version: options.retrieverVersion,
 					configDigest: brief.retrieverConfigDigest
 				},
-				visibility: createKnowledgeVisibilitySnapshot(chain),
+				visibility,
+				...visibilityArtifact ? { visibilityArtifact } : {},
 				results: brief.results,
 				createdAt: options.now?.()
 			});
@@ -6680,6 +6739,24 @@ function tool(name, description, inputSchema, handler) {
 		handler: (input) => handler(inputSchema.parse(input))
 	};
 }
+/** Snapshot artifacts are immutable evidence, separate from authoritative KB state. */
+async function persistVisibility(root, snapshot) {
+	const bytes = encodeKnowledgeVisibilitySnapshot(snapshot);
+	const path = `.agent-knowledge/retrieval-visibility/${snapshot.snapshotDigest.replace("sha256:", "")}.json`;
+	await withKnowledgeMutation(root, async () => {
+		try {
+			const existing = await readRegularFileWithinRoot(root, path);
+			if (!Buffer.from(existing.bytes).equals(Buffer.from(bytes))) throw new Error("stored knowledge visibility artifact does not match its content identity");
+		} catch (error) {
+			if (!isMissingFile(error)) throw error;
+			await writeFileDurableWithinRoot(root, path, Buffer.from(bytes));
+		}
+	});
+	return knowledgeVisibilityArtifactRef({
+		uri: pathToFileURL(join(root, path)).href,
+		bytes
+	});
+}
 //#endregion
 //#region src/promotion.ts
 /**
@@ -8047,6 +8124,6 @@ function buildSteerText(gaps, deepQuestions, invalidationTargets, minIndependent
 	return lines.join("\n");
 }
 //#endregion
-export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, CHECKABLE_RUNG_THRESHOLD, CITES_INVALIDATED_FIELD, ClaimLedgerGoalConflictError, ClaimLedgerMigrationRequiredError, DEADLINE_EXIT_CODE, 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, canonicalPathsEqual, canonicalRelativeWithinRoot, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, claimCheckKey, 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, gradeClaims, gradeCompanyAgainstText, gradeFactAgainstText, gradeFor, graphitiMemoryAdapterIdentity, groundClaimInText, hashKnowledgeBase, htmlToText, improveKnowledgeBase, improveSelectedKnowledgeCandidate, initKnowledgeBase, innerHtmlById, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isKernelAnchoredPath, isKnowledgeMemoryBenchmarkCase, isKnowledgeMutationHeld, 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, relativeWithinRoot, removeDurable, renameDurable, renderKnowledgeBenchmarkReportMarkdown, renderMemoryContext, researchSourceVersionKey, resetRetrievalHoldoutRegistry, resolveKnowledgeCitation, resolveKnowledgeCitations, resolveMemoryCleanupTimeoutMs, resolveRunScopedCitation, resolveRunScopedCitations, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, restoreKnowledgeCandidateBaseline, retrievalConfigFromSurface, retrievalConfigSurface, retrievalHoldoutConfigHash, retrievalRecallJudge, runAgentMemoryExperiment, runAgentMemoryImprovement, runAgentMemoryLearningExperiment, runBoundedMemoryLifecycle, runDiscoveryLoop, runInKnowledgeMutationScope, 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 };
+export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, CHECKABLE_RUNG_THRESHOLD, CITES_INVALIDATED_FIELD, ClaimLedgerGoalConflictError, ClaimLedgerMigrationRequiredError, DEADLINE_EXIT_CODE, 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, canonicalPathsEqual, canonicalRelativeWithinRoot, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, claimCheckKey, 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, gradeClaims, gradeCompanyAgainstText, gradeFactAgainstText, gradeFor, graphitiMemoryAdapterIdentity, groundClaimInText, hashKnowledgeBase, htmlToText, improveKnowledgeBase, improveSelectedKnowledgeCandidate, initKnowledgeBase, innerHtmlById, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isKernelAnchoredPath, isKnowledgeMemoryBenchmarkCase, isKnowledgeMutationHeld, 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, normalizeKnowledgeStateScope, normalizeLinkTarget, normalizePageText, normalizePagesDirectory, optimizeKnowledgeBasePolicy, originatedPages, parseFrontmatter, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, parseKnowledgeCitationReference, parseKnowledgeWriteBlocks, partitionRetrievalScenarios, planInvalidationPropagation, politeFetch, promoteKnowledgeCandidate, promoteRunScopedPages, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, readRegularFileNoFollow, readRegularFileWithinRoot, reciprocalRankFusion, recoverPendingKnowledgeMutation, relativeWithinRoot, removeDurable, renameDurable, renderKnowledgeBenchmarkReportMarkdown, renderMemoryContext, researchSourceVersionKey, resetRetrievalHoldoutRegistry, resolveKnowledgeCitation, resolveKnowledgeCitations, resolveMemoryCleanupTimeoutMs, resolveRunScopedCitation, resolveRunScopedCitations, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, restoreKnowledgeCandidateBaseline, retrievalConfigFromSurface, retrievalConfigSurface, retrievalHoldoutConfigHash, retrievalRecallJudge, runAgentMemoryExperiment, runAgentMemoryImprovement, runAgentMemoryLearningExperiment, runBoundedMemoryLifecycle, runDiscoveryLoop, runInKnowledgeMutationScope, 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