@tangle-network/agent-knowledge 6.1.10 → 6.2.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as writeFileDurableWithinRoot, A as loadKnowledgePages, B as withKnowledgeMutation, C as SourceAnchorSchema, D as initKnowledgeBase, E as SCAFFOLD_PAGE_BASENAMES, F as formatFrontmatter, G as knowledgeFileTransactionPlanHash, H as applyKnowledgeFileTransaction, I as parseFrontmatter, J as isMissingFile, K as prepareKnowledgeFileTransaction, L as acquireDurableFileLock, M as WIKILINK_REGEX, N as extractWikilinks, O as isScaffoldPath, P as normalizeLinkTarget, Q as withSafeDirectory, R as inspectPendingKnowledgeMutation, S as KnowledgePageSchema, T as buildKnowledgeGraph, U as assertKnowledgeMutationPath, V as withKnowledgeRead, W as finishKnowledgeFileTransaction, X as readRegularFileWithinRoot, Y as listRegularFilesWithinRoot, Z as renameDurable, _ as KnowledgeBaseCandidateSchema, a as applyKnowledgeWriteBlocksFile, b as KnowledgeGraphNodeSchema, c as validateKnowledgeIndex, d as writeKnowledgeIndex, et as writeJsonDurableWithinRoot, f as addSourcePath, g as writeSourceRegistry, h as sourceRegistryPath, i as applyKnowledgeWriteBlocks, j as writeJson, k as layoutFor, l as lintKnowledgeIndex, m as loadSourceRegistry, n as inspectKnowledgeIndex, nt as textSourceAdapter, o as isSafeKnowledgePath, p as addSourceText, q as rollbackKnowledgeFileTransaction, r as stringMetadata, s as parseKnowledgeWriteBlocks, t as explainKnowledgeTarget, tt as mediaTypeFor, u as buildKnowledgeIndex, v as KnowledgeEventSchema, w as SourceRecordSchema, x as KnowledgeIndexSchema, y as KnowledgeGraphEdgeSchema, z as recoverPendingKnowledgeMutation } from "./inspect-DAXpFyrs.js";
+import { $ as SCAFFOLD_PAGE_BASENAMES, A as KnowledgePageSchema, At as withSafeDirectory, B as assertResearchClaimLedgerIntegrity, C as assertClaimLedgerId, Ct as listRegularFilesWithinRoot, D as KnowledgeGraphEdgeSchema, Dt as renameDurable, E as KnowledgeEventSchema, Et as removeDurable, F as SourceRecordSchema, Ft as mediaTypeFor, G as deepQuestionId, H as claimEvidenceId, I as KNOWLEDGE_EVENT_TYPES, It as textSourceAdapter, J as materializeRegisteredClaimEvidence, K as emptyClaimLedger, L as ClaimLedgerGoalConflictError, M as ResearchClaimLedgerSchema, Mt as writeFileDurableWithinRoot, N as ResearchClaimRecordSchema, Nt as writeJsonDurable, O as KnowledgeGraphNodeSchema, Ot as syncDirectory, P as SourceAnchorSchema, Pt as writeJsonDurableWithinRoot, Q as buildKnowledgeGraph, R as assertDeepQuestionIntegrity, S as MemoryKbStore, St as isMissingFile, T as KnowledgeBaseCandidateSchema, Tt as readRegularFileWithinRoot, U as claimId, V as assertTrackedClaimIntegrity, W as claimSourceHost, X as mergeTrackedClaims, Y as mergeClaimLedgers, Z as normalizeClaimText, _ as FileSystemKbStore, _t as finishKnowledgeFileTransaction, a as applyKnowledgeWriteBlocksFile, at as WIKILINK_REGEX, b as KB_INDEX_PATH, bt as rollbackKnowledgeFileTransaction, c as validateKnowledgeIndex, ct as formatFrontmatter, d as writeKnowledgeIndex, dt as inspectPendingKnowledgeMutation, et as initKnowledgeBase, f as addSourcePath, ft as recoverPendingKnowledgeMutation, g as writeSourceRegistry, gt as assertKnowledgeMutationPath, h as sourceRegistryPath, ht as applyKnowledgeFileTransaction, i as applyKnowledgeWriteBlocks, it as writeJson, j as ResearchClaimEvidenceSchema, jt as writeFileDurable, k as KnowledgeIndexSchema, kt as withSafeDescendant, l as lintKnowledgeIndex, lt as parseFrontmatter, m as loadSourceRegistry, mt as withKnowledgeRead, n as inspectKnowledgeIndex, nt as layoutFor, o as isSafeKnowledgePath, ot as extractWikilinks, p as addSourceText, pt as withKnowledgeMutation, q as linkClaimContradictions, r as stringMetadata, rt as loadKnowledgePages, s as parseKnowledgeWriteBlocks, st as normalizeLinkTarget, t as explainKnowledgeTarget, tt as isScaffoldPath, u as buildKnowledgeIndex, ut as acquireDurableFileLock, v as KB_CLAIM_LEDGER_DIR, vt as knowledgeFileTransactionPlanHash, w as DeepQuestionSchema, wt as readRegularFileNoFollow, x as KB_STORE_DIR, xt as isKernelAnchoredPath, y as KB_EVENTS_PATH, yt as prepareKnowledgeFileTransaction, z as assertResearchClaimEvidenceIntegrity } from "./inspect-LUMkas6A.js";
 import { n as slugify, r as stableId, t as sha256 } from "./ids-DRqPZ42_.js";
 import { A as assertImmutableRef, C as resetRetrievalHoldoutRegistry, D as jsonObjectCandidateCodec, E as jsonCandidateCodec, O as runSerializedKnowledgeOptimization, S as emitRetrievalHoldoutBypass, T as toOffPolicyTrajectory, _ as defaultGetMemoryContext, a as createNeo4jAgentMemoryAdapter, b as applySessionStickyRetrievalHoldout, c as runAgentMemoryImprovement, d as runAgentMemoryExperiment, f as agentMemorySequenceJudge, g as forkAgentMemoryBranchSnapshot, h as createAgentMemoryBranch, i as AgentMemoryWriteInputSchema, k as scenarioContentFingerprint, l as createGraphitiMemoryAdapter, m as buildAgentMemorySequencesFromBenchmarkCases, n as AgentMemoryKindSchema, o as createMem0MemoryAdapter, p as buildAgentMemorySequenceScenarios, r as AgentMemoryScopeSchema, s as mem0MemoryAdapterIdentity, t as AgentMemoryHitSchema, u as graphitiMemoryAdapterIdentity, v as renderMemoryContext, w as retrievalHoldoutConfigHash, x as deterministicRng, y as applyRetrievalHoldout } from "./memory-C6KPRhoU.js";
 import { n as searchKnowledge, r as tokenizeQuery, t as reciprocalRankFusion } from "./search-CP0QtBJZ.js";
@@ -546,7 +546,7 @@ function triageSource(source, options) {
 		triage: "drop",
 		reason: `thin body (${bodyLen} < ${options.minBodyChars} chars)`
 	};
-	const host = hostOf$1(source.uri);
+	const host = hostOf(source.uri);
 	if (host.length > 0 && options.authoritativeHosts.some((suffix) => hostMatches(host, suffix)) && bodyLen >= options.substantialBodyChars) return {
 		triage: "keep",
 		reason: `authoritative host ${host} + substantial body (${bodyLen})`
@@ -556,7 +556,7 @@ function triageSource(source, options) {
 		reason: `unknown host ${host || "(none)"}, body ${bodyLen} chars`
 	};
 }
-function hostOf$1(uri) {
+function hostOf(uri) {
 	try {
 		return new URL(uri.trim()).hostname.toLowerCase().replace(/^www\./, "");
 	} catch {
@@ -5082,8 +5082,10 @@ async function materialFactsSurfaced(kb, checklist) {
 async function runVerifiedResearchLoop(options) {
 	const maxRounds = Math.max(1, options.maxRounds ?? 3);
 	await initKnowledgeBase(options.root);
+	const store = new FileSystemKbStore({ root: options.root });
 	const steps = [];
 	let index = await buildKnowledgeIndex(options.root);
+	await confirmRegisteredSources(options.driver, index.sources);
 	let readiness = readinessFor(options, index);
 	let ready = isReady(readiness?.report);
 	let steer;
@@ -5127,6 +5129,7 @@ async function runVerifiedResearchLoop(options) {
 			});
 		}
 		const acceptedWorkerSources = await registerSources(options, accepted);
+		await confirmRegisteredSources(options.driver, acceptedWorkerSources);
 		const writtenPages = [];
 		writtenPages.push(...await applyPages(options.root, workerContribution, acceptedWorkerSources));
 		index = await buildKnowledgeIndex(options.root);
@@ -5146,13 +5149,18 @@ async function runVerifiedResearchLoop(options) {
 			});
 			driverNotes = driverContribution.notes;
 			driverSources = await registerSources(options, driverContribution.sources ?? []);
+			await confirmRegisteredSources(options.driver, driverSources);
 			writtenPages.push(...await applyPages(options.root, driverContribution, driverSources));
 			index = await buildKnowledgeIndex(options.root);
 			readiness = readinessFor(options, index);
 		}
 		ready = isReady(readiness?.report);
 		const remainingGaps = gapsFromReadiness(readiness);
-		steer = ready ? void 0 : foldGaps(options.driver, remainingGaps);
+		if (ready || remainingGaps.length === 0) steer = void 0;
+		else {
+			await options.driver.prepareFold?.();
+			steer = foldGaps(options.driver, remainingGaps);
+		}
 		const step = {
 			round,
 			gaps,
@@ -5182,6 +5190,8 @@ async function runVerifiedResearchLoop(options) {
 				driver: driverNotes
 			}
 		};
+		await options.driver.checkpoint?.();
+		await store.putEvent(step.event);
 		steps.push(step);
 		await options.onRound?.(step);
 	}
@@ -5228,6 +5238,12 @@ async function registerSources(options, sources) {
 	for (const source of sources) records.push(await addSourceText(options.root, source, options.sourceOptions));
 	return records;
 }
+async function confirmRegisteredSources(driver, sources) {
+	if (!driver.commitSources) return;
+	const originalUris = sources.flatMap((source) => typeof source.metadata?.originalUri === "string" ? [source.metadata.originalUri] : []);
+	if (originalUris.length === 0) return;
+	await driver.commitSources([...new Set(originalUris)].sort());
+}
 /**
 * Apply a contribution's curated pages. Static `proposalText` plus a
 * `buildPages(acceptedSources)` result are concatenated and run through the safe
@@ -5248,11 +5264,11 @@ function requireReadiness(readiness, options) {
 	return buildEvalKnowledgeBundle({
 		...options.readiness ?? {},
 		taskId: options.readinessTaskId ?? options.goal,
-		index: emptyIndex$1(options.root),
+		index: emptyIndex(options.root),
 		specs: []
 	});
 }
-function emptyIndex$1(root) {
+function emptyIndex(root) {
 	return {
 		root,
 		generatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
@@ -5436,159 +5452,6 @@ async function runInvestmentThesisTask(input, options) {
 	};
 }
 //#endregion
-//#region src/kb-store.ts
-var MemoryKbStore = class {
-	sources = /* @__PURE__ */ new Map();
-	pages = /* @__PURE__ */ new Map();
-	events = [];
-	index = null;
-	async putSource(source) {
-		this.sources.set(source.id, clone(source));
-	}
-	async getSource(id) {
-		return clone(this.sources.get(id) ?? null);
-	}
-	async listSources() {
-		return [...this.sources.values()].map(clone);
-	}
-	async putPage(page) {
-		this.pages.set(page.id, clone(page));
-	}
-	async getPage(idOrPath) {
-		return clone(this.pages.get(idOrPath) ?? [...this.pages.values()].find((page) => page.path === idOrPath) ?? null);
-	}
-	async listPages() {
-		return [...this.pages.values()].map(clone);
-	}
-	async putIndex(index) {
-		this.index = clone(index);
-	}
-	async getIndex() {
-		if (this.index) return clone(this.index);
-		const pages = await this.listPages();
-		const sources = await this.listSources();
-		return {
-			root: "memory",
-			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			sources,
-			pages,
-			graph: buildKnowledgeGraph(pages)
-		};
-	}
-	async putEvent(event) {
-		this.events.push(clone(event));
-	}
-	async listEvents(query = {}) {
-		let out = this.events;
-		if (query.type) out = out.filter((event) => event.type === query.type);
-		if (query.target) out = out.filter((event) => event.target === query.target);
-		out = [...out].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-		return out.slice(-(query.limit ?? out.length)).map(clone);
-	}
-};
-const knowledgeEventsSchema = z.array(KnowledgeEventSchema);
-var FileSystemKbStore = class {
-	dir;
-	constructor(dir) {
-		this.dir = dir;
-	}
-	async putSource(source) {
-		const parsed = SourceRecordSchema.parse(source);
-		await this.updateIndex((index) => ({
-			...index,
-			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			sources: [parsed, ...index.sources.filter((entry) => entry.id !== parsed.id)]
-		}));
-	}
-	async getSource(id) {
-		return withKnowledgeRead(this.dir, async () => {
-			return clone((await this.readIndex())?.sources.find((source) => source.id === id) ?? null);
-		});
-	}
-	async listSources() {
-		return withKnowledgeRead(this.dir, async () => clone((await this.readIndex())?.sources ?? []));
-	}
-	async putPage(page) {
-		const parsed = KnowledgePageSchema.parse(page);
-		await this.updateIndex((index) => {
-			const pages = [parsed, ...index.pages.filter((entry) => entry.id !== parsed.id)];
-			return {
-				...index,
-				generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-				pages,
-				graph: buildKnowledgeGraph(pages)
-			};
-		});
-	}
-	async getPage(idOrPath) {
-		return withKnowledgeRead(this.dir, async () => {
-			return clone((await this.readIndex())?.pages.find((page) => page.id === idOrPath || page.path === idOrPath) ?? null);
-		});
-	}
-	async listPages() {
-		return withKnowledgeRead(this.dir, async () => clone((await this.readIndex())?.pages ?? []));
-	}
-	async putIndex(index) {
-		const parsed = KnowledgeIndexSchema.parse(index);
-		await withKnowledgeMutation(this.dir, () => writeJsonDurableWithinRoot(this.dir, "index.json", parsed));
-	}
-	async getIndex() {
-		return withKnowledgeRead(this.dir, () => this.readIndex());
-	}
-	async putEvent(event) {
-		const parsed = KnowledgeEventSchema.parse(event);
-		await withKnowledgeMutation(this.dir, async () => {
-			const next = [...(await this.readEvents()).filter((entry) => entry.id !== parsed.id), parsed].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-			await writeJsonDurableWithinRoot(this.dir, "events.json", next);
-		});
-	}
-	async listEvents(query = {}) {
-		return withKnowledgeRead(this.dir, async () => {
-			let events = await this.readEvents();
-			if (query.type) events = events.filter((event) => event.type === query.type);
-			if (query.target) events = events.filter((event) => event.target === query.target);
-			return clone(events.slice(-(query.limit ?? events.length)));
-		});
-	}
-	async updateIndex(change) {
-		await withKnowledgeMutation(this.dir, async () => {
-			const current = await this.readIndex() ?? emptyIndex(this.dir);
-			const next = KnowledgeIndexSchema.parse(change(current));
-			await writeJsonDurableWithinRoot(this.dir, "index.json", next);
-		});
-	}
-	async readIndex() {
-		return readJsonFile(this.dir, "index.json", KnowledgeIndexSchema);
-	}
-	async readEvents() {
-		return await readJsonFile(this.dir, "events.json", knowledgeEventsSchema) ?? [];
-	}
-};
-function emptyIndex(root) {
-	return {
-		root,
-		generatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
-		sources: [],
-		pages: [],
-		graph: {
-			nodes: [],
-			edges: []
-		}
-	};
-}
-async function readJsonFile(root, relativePath, schema) {
-	try {
-		const file = await readRegularFileWithinRoot(root, relativePath);
-		return schema.parse(JSON.parse(file.bytes.toString("utf8")));
-	} catch (error) {
-		if (error?.code === "ENOENT") return null;
-		throw error;
-	}
-}
-function clone(value) {
-	return value == null ? value : JSON.parse(JSON.stringify(value));
-}
-//#endregion
 //#region src/propose-from-finding.ts
 var KnowledgeProposalParseError = class extends Error {
 	findingId;
@@ -5941,29 +5804,132 @@ function knowledgeReleaseReport(input) {
 * contested IS.
 *
 * It reuses `runVerifiedResearchLoop` (it is a plain `ResearchDriver`), the web
-* worker, `sha256` (claim identity), `canonicalizeUrl` (independent-source
-* identity), and the `RouterClient` chat surface; it reinvents none of them.
+* worker, `claim-ledger.ts` (claim identity, independent-source identity, and
+* the merge rule), and the `RouterClient` chat surface; it reinvents none of
+* them.
+*/
+/**
+* The in-memory driver. Its belief state lives for exactly as long as the
+* process does — use `createPersistentResearchDrivingDriver` when the run must
+* survive a crash or resume.
 */
 function createResearchDrivingDriver(options = {}) {
+	return buildDriver(options);
+}
+/**
+* The durable driver: same behaviour, plus its claim ledger is read from the
+* store at construction and written back after every claim and every round.
+*
+* Construction is asynchronous because loading is I/O, and loading has to happen
+* before the caller can read `researchState()` or `isComplete()` — a driver that
+* loaded lazily would answer "nothing researched, not complete" for a run that
+* had already corroborated everything.
+*/
+async function createPersistentResearchDrivingDriver(options) {
+	const ledgerId = assertClaimLedgerId(options.ledgerId);
+	const existing = await options.store.getClaimLedger(ledgerId);
+	const driver = buildDriver(options, {
+		store: options.store,
+		ledgerId
+	}, existing ?? void 0);
+	if (existing && (existing.preparedRounds ?? existing.rounds) > existing.rounds) await driver.checkpoint();
+	return driver;
+}
+function buildDriver(options, persistence, restored) {
 	const minIndependentSources = Math.max(2, options.minIndependentSources ?? 2);
 	const maxQuestionsPerRound = Math.max(1, options.maxQuestionsPerRound ?? 6);
 	const maxClaimsPerSource = Math.max(1, options.maxClaimsPerSource ?? 3);
 	const deterministicFallback = options.deterministicFallback ?? true;
-	const claims = /* @__PURE__ */ new Map();
-	const questions = /* @__PURE__ */ new Map();
-	let rounds = 0;
+	const claims = new Map((restored?.claims ?? []).map((claim) => [claim.id, fromRecord(claim)]));
+	const claimEvidence = new Map((restored?.claimEvidence ?? []).map((evidence) => [evidence.id, evidence]));
+	const registeredSourceUris = new Set(restored?.registeredSourceUris ?? []);
+	const questions = new Map((restored?.questions ?? []).map((question) => [question.id, question]));
+	let rounds = restored?.rounds ?? 0;
+	let preparedRounds = Math.max(rounds, restored?.preparedRounds ?? rounds);
+	let goal = restored?.goal;
 	let lastSteer;
+	if (preparedRounds > rounds) {
+		for (let round = rounds + 1; round <= preparedRounds; round += 1) for (const question of synthesizeDeepQuestions([...claims.values()], round).slice(0, maxQuestionsPerRound)) if (!questions.has(question.id)) questions.set(question.id, question);
+		rounds = preparedRounds;
+	}
+	function toLedger() {
+		return {
+			id: persistence?.ledgerId ?? "in-memory",
+			...goal === void 0 ? {} : { goal },
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			rounds,
+			...preparedRounds > rounds ? { preparedRounds } : {},
+			claimEvidence: [...claimEvidence.values()].sort((left, right) => left.id.localeCompare(right.id)),
+			registeredSourceUris: [...registeredSourceUris].sort(),
+			claims: [...claims.values()].map((claim) => ({
+				...claim,
+				supportingHosts: [...new Set(claim.supportingHosts)].sort(),
+				supportingUris: [...new Set(claim.supportingUris)].sort(),
+				contradicts: [...new Set(claim.contradicts)].sort()
+			})).sort((a, b) => a.id.localeCompare(b.id)),
+			questions: [...questions.values()].map((question) => ({
+				...question,
+				claimIds: [...new Set(question.claimIds)].sort()
+			})).sort((a, b) => a.id.localeCompare(b.id))
+		};
+	}
+	/**
+	* Write this driver's belief state into the stored ledger and adopt the
+	* result.
+	*
+	* It merges rather than overwrites, and then rehydrates from the merged
+	* record, which is the whole of what makes knowledge compound across
+	* workers. Two drivers on one ledger id — a resumed run beside a still-live
+	* one, or two workers researching one goal in parallel — would otherwise each
+	* write a whole record built from what it read before the other wrote, and
+	* the later write would erase the earlier writer's claims. Rehydrating means
+	* a claim another worker corroborated counts toward THIS driver's completion
+	* oracle from the next round onward.
+	*/
+	async function persist() {
+		if (!persistence) return;
+		const mine = toLedger();
+		const merged = await persistence.store.mergeClaimLedger(persistence.ledgerId, (current) => current === null ? mine : mergeClaimLedgers(current, mine));
+		claims.clear();
+		for (const claim of merged.claims) claims.set(claim.id, fromRecord(claim));
+		claimEvidence.clear();
+		for (const evidence of merged.claimEvidence) claimEvidence.set(evidence.id, evidence);
+		registeredSourceUris.clear();
+		for (const sourceUri of merged.registeredSourceUris) registeredSourceUris.add(sourceUri);
+		questions.clear();
+		for (const question of merged.questions) questions.set(question.id, question);
+		rounds = Math.max(rounds, merged.rounds);
+		preparedRounds = Math.max(rounds, merged.preparedRounds ?? merged.rounds);
+		goal = merged.goal ?? goal;
+	}
+	async function prepareFold() {
+		if (!persistence) return;
+		preparedRounds = Math.max(preparedRounds, rounds + 1);
+		await persist();
+	}
+	/**
+	* A ledger accumulates evidence FOR a goal. Reusing one id across two goals
+	* merges two runs' beliefs into one corroboration count, which is worse than
+	* losing them, so it fails rather than merging.
+	*/
+	function bindGoal(nextGoal) {
+		if (goal === void 0) {
+			goal = nextGoal;
+			return;
+		}
+		if (goal !== nextGoal) throw new Error(`claim ledger '${persistence?.ledgerId ?? "in-memory"}' accumulated evidence for goal '${goal}' and cannot be reused for '${nextGoal}'`);
+	}
 	function resolveRouter() {
 		return options.router ?? createTangleRouterClient(options.router_options);
 	}
 	/** Record a claim from a source, growing its independent-source support. */
 	function recordClaim(extracted, sourceUri, round) {
 		const id = claimId(extracted.text);
-		const host = hostOf(sourceUri);
+		const host = claimSourceHost(sourceUri);
 		const existing = claims.get(id);
 		if (existing) {
 			if (host) existing.supportingHosts.add(host);
-			if (!existing.supportingUris.includes(sourceUri)) existing.supportingUris.push(sourceUri);
+			addUnique(existing.supportingUris, sourceUri);
 			linkContradiction(existing, extracted.contradictsExistingId);
 			return existing;
 		}
@@ -5980,6 +5946,62 @@ function createResearchDrivingDriver(options = {}) {
 		claims.set(id, tracked);
 		return tracked;
 	}
+	/** Persist an extraction observation without treating its source as registered. */
+	function recordEvidence(extracted, sourceUri, round) {
+		const text = extracted.text.trim();
+		const observedClaimId = claimId(text);
+		const contradictsClaimId = extracted.contradictsExistingId === observedClaimId ? void 0 : extracted.contradictsExistingId;
+		const evidence = {
+			id: claimEvidenceId({
+				claimId: observedClaimId,
+				sourceUri,
+				contradictsClaimId
+			}),
+			claimId: observedClaimId,
+			text,
+			sourceUri,
+			...contradictsClaimId === void 0 ? {} : { contradictsClaimId },
+			firstSeenRound: round
+		};
+		const existing = claimEvidence.get(evidence.id);
+		if (!existing) {
+			claimEvidence.set(evidence.id, evidence);
+			return evidence;
+		}
+		const merged = {
+			...evidence.firstSeenRound < existing.firstSeenRound || evidence.firstSeenRound === existing.firstSeenRound && evidence.text < existing.text ? evidence : existing,
+			firstSeenRound: Math.min(existing.firstSeenRound, evidence.firstSeenRound)
+		};
+		claimEvidence.set(merged.id, merged);
+		return merged;
+	}
+	/** Materialize evidence for newly confirmed source URIs into live claims. */
+	function materializeEvidenceFor(sourceUris) {
+		const evidence = [...claimEvidence.values()].filter((item) => sourceUris.has(item.sourceUri));
+		const texts = [];
+		for (const item of evidence) {
+			recordClaim({
+				text: item.text,
+				contradictsExistingId: item.contradictsClaimId
+			}, item.sourceUri, item.firstSeenRound);
+			texts.push(item.text);
+		}
+		for (const item of evidence) {
+			const claim = claims.get(item.claimId);
+			if (claim) linkContradiction(claim, item.contradictsClaimId);
+		}
+		return texts;
+	}
+	async function commitSources(sourceUris) {
+		const newlyRegistered = /* @__PURE__ */ new Set();
+		for (const sourceUri of sourceUris) {
+			if (registeredSourceUris.has(sourceUri)) continue;
+			registeredSourceUris.add(sourceUri);
+			newlyRegistered.add(sourceUri);
+		}
+		if (newlyRegistered.size > 0) markAddressed(materializeEvidenceFor(newlyRegistered));
+		await persist();
+	}
 	/** Wire a bidirectional contradiction edge and mark BOTH claims contested. */
 	function linkContradiction(claim, otherId) {
 		if (!otherId || otherId === claim.id) return;
@@ -6049,17 +6071,18 @@ function createResearchDrivingDriver(options = {}) {
 		* because such a source cannot drive the research and pollutes the KB.
 		*/
 		async verifySource(source, ctx) {
+			bindGoal(ctx.goal);
 			const extracted = await extractClaims(source, ctx);
 			if (extracted.length === 0) return {
 				accept: false,
 				reason: "no extractable claim: source yields nothing to drive the research deeper"
 			};
-			const newTexts = [];
-			for (const claim of extracted) {
-				recordClaim(claim, source.uri, ctx.round);
-				newTexts.push(claim.text);
-			}
-			markAddressed(newTexts);
+			for (const claim of extracted) recordEvidence(claim, source.uri, ctx.round);
+			if (!persistence) {
+				registeredSourceUris.add(source.uri);
+				markAddressed(materializeEvidenceFor(/* @__PURE__ */ new Set([source.uri])));
+			} else if (registeredSourceUris.has(source.uri)) markAddressed(materializeEvidenceFor(/* @__PURE__ */ new Set([source.uri])));
+			await persist();
 			return { accept: true };
 		},
 		/**
@@ -6069,6 +6092,7 @@ function createResearchDrivingDriver(options = {}) {
 		* (3) INVALIDATION challenges for weakly-supported / contradicted claims.
 		*/
 		foldGaps(gaps) {
+			if (persistence && preparedRounds <= rounds) throw new Error("persistent research driver must prepareFold before foldGaps");
 			rounds += 1;
 			const round = rounds;
 			const ledger = [...claims.values()];
@@ -6096,14 +6120,34 @@ function createResearchDrivingDriver(options = {}) {
 		},
 		lastSteer() {
 			return lastSteer;
-		}
+		},
+		checkpoint: persist,
+		prepareFold,
+		commitSources,
+		toLedger
 	};
 	async function extractClaims(source, ctx) {
-		const fromLlm = await extractClaimsWithLlm(source, ctx, [...claims.values()]);
+		const fromLlm = await extractClaimsWithLlm(source, ctx, claimsForExtraction());
 		if (fromLlm.length > 0) return fromLlm.slice(0, maxClaimsPerSource);
 		if (deterministicFallback) return deterministicClaims(source).slice(0, maxClaimsPerSource);
 		return [];
 	}
+	function claimsForExtraction() {
+		const known = new Map(claims);
+		for (const evidence of claimEvidence.values()) {
+			if (known.has(evidence.claimId)) continue;
+			known.set(evidence.claimId, {
+				id: evidence.claimId,
+				text: evidence.text,
+				supportingHosts: /* @__PURE__ */ new Set(),
+				supportingUris: [],
+				contradicts: /* @__PURE__ */ new Set(),
+				contested: false,
+				firstSeenRound: evidence.firstSeenRound
+			});
+		}
+		return [...known.values()];
+	}
 	async function extractClaimsWithLlm(source, ctx, ledger) {
 		let router;
 		try {
@@ -6177,25 +6221,26 @@ function makeQuestion(kind, text, claimIds, raisedRound) {
 	return {
 		kind,
 		text,
-		id: `q_${sha256(`${kind}:${text}`).slice(0, 16)}`,
-		claimIds,
+		id: deepQuestionId(kind, text),
+		claimIds: [...new Set(claimIds)].sort(),
 		addressed: false,
 		raisedRound
 	};
 }
-/** Claim identity = sha256 of the normalized claim text (same words ⇒ same claim). */
-function claimId(text) {
-	return `c_${sha256(normalizeText(text)).slice(0, 16)}`;
-}
-function hostOf(uri) {
-	try {
-		return new URL(uri.trim()).hostname.toLowerCase().replace(/^www\./, "");
-	} catch {
-		return canonicalizeUrl(uri);
-	}
+function fromRecord(claim) {
+	return {
+		...claim,
+		supportingHosts: new Set(claim.supportingHosts),
+		supportingUris: [...claim.supportingUris],
+		contradicts: new Set(claim.contradicts)
+	};
 }
-function normalizeText(text) {
-	return text.toLowerCase().replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim();
+/**
+* Set-like insert into the array form. The ledger's collections are arrays so
+* they survive `JSON.stringify`; dedup is enforced here instead of by the type.
+*/
+function addUnique(values, value) {
+	if (!values.includes(value)) values.push(value);
 }
 const stopwords = /* @__PURE__ */ new Set([
 	"the",
@@ -6249,7 +6294,7 @@ const stopwords = /* @__PURE__ */ new Set([
 	"them"
 ]);
 function contentWordSet(text) {
-	return new Set(normalizeText(text).split(" ").filter((word) => word.length >= 3 && !stopwords.has(word)));
+	return new Set(normalizeClaimText(text).split(" ").filter((word) => word.length >= 3 && !stopwords.has(word)));
 }
 function overlapFraction(a, b) {
 	if (a.size === 0) return 0;
@@ -6326,6 +6371,6 @@ function buildSteerText(gaps, deepQuestions, invalidationTargets, minIndependent
 	return lines.join("\n");
 }
 //#endregion
-export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, FileSystemKbStore, FileSystemSearchProvider, INDUSTRY_MEMORY_BENCHMARKS, INDUSTRY_RAG_BENCHMARKS, IRS_DIMENSION_HINTS, KnowledgeBaseCandidateSchema, KnowledgeEventSchema, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeImprovementCandidateRefSchema, KnowledgeImprovementEvidenceSchema, KnowledgeImprovementRunStateSchema, KnowledgeIndexSchema, KnowledgePageSchema, KnowledgeProposalParseError, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, MemoryKbStore, POLITE_USER_AGENT, READINESS_SPEC_DEFAULTS, RouterError, SCAFFOLD_PAGE_BASENAMES, SourceAnchorSchema, SourceRecordSchema, WIKILINK_REGEX, __resetHttpThrottle, acquireAgentMemoryRunLease, addSourcePath, addSourceText, agentMemorySequenceJudge, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, applyRetrievalHoldout, applySessionStickyRetrievalHoldout, buildAgentMemorySequenceScenarios, buildAgentMemorySequencesFromBenchmarkCases, buildEvalKnowledgeBundle, buildFirstPartyMemoryLifecycleBenchmarkCases, buildIndustryMemoryBenchmarkSmokeCases, buildIndustryRagBenchmarkSmokeCases, buildKnowledgeBenchmarkScenarios, buildKnowledgeGraph, buildKnowledgeIndex, buildRetrievalBenchmarkCasesFromQrels, buildRetrievalEvalDispatch, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, contentKey, createAdaptiveResearchDriver, createAgentMemoryBranch, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createCornellLiiSource, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createFileSystemSearchProvider, createGraphitiMemoryAdapter, createInMemoryBenchmarkAdapter, createIrsPublicationsSource, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createMem0MemoryAdapter, createMemoryExecutionPool, createNeo4jAgentMemoryAdapter, createNoopMemoryBenchmarkAdapter, createRagAnswerQualityHook, createResearchDrivingDriver, createStateSosSource, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defaultGetMemoryContext, defineReadinessSpec, detectChanges, deterministicRng, diagnoseRagAnswerFailure, emitRetrievalHoldoutBypass, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractLinks, extractWikilinks, firstMatch, forkAgentMemoryBranchSnapshot, formatFrontmatter, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, graphitiMemoryAdapterIdentity, groundClaimInText, hashKnowledgeBase, htmlToText, improveKnowledgeBase, initKnowledgeBase, innerHtmlById, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isKnowledgeMemoryBenchmarkCase, isSafeKnowledgePath, isScaffoldPath, jsonCandidateCodec, jsonObjectCandidateCodec, kbIndexToText, knowledgeBenchmarkJudge, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, lintKnowledgeIndex, loadKnowledgeImprovementActivationResult, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, looksLikeBlockPage, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, mem0MemoryAdapterIdentity, memoryHitToSourceRecord, memoryRecoveryDelayMs, memoryWriteResultToSourceRecord, normalizeExternalRagScores, normalizeLinkTarget, optimizeKnowledgeBasePolicy, parseFrontmatter, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, parseKnowledgeWriteBlocks, partitionRetrievalScenarios, politeFetch, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, recoverPendingKnowledgeMutation, renderKnowledgeBenchmarkReportMarkdown, renderMemoryContext, resetRetrievalHoldoutRegistry, resolveMemoryCleanupTimeoutMs, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, restoreKnowledgeCandidateBaseline, retrievalConfigFromSurface, retrievalConfigSurface, retrievalHoldoutConfigHash, retrievalRecallJudge, runAgentMemoryExperiment, runAgentMemoryImprovement, runBoundedMemoryLifecycle, runDiscoveryLoop, runInvestmentThesisTask, runKnowledgeBenchmarkSuite, runKnowledgeResearchLoop, runMemoryAdapterBenchmark, runRagKnowledgeImprovementLoop, runRagOptimization, runRetrievalImprovementLoop, runSerializedKnowledgeOptimization, runVerifiedResearchLoop, scenarioContentFingerprint, scoreKnowledgeBaseIndex, scoreKnowledgeBenchmarkArtifact, scoreMemoryBenchmarkArtifact, scoreRagAnswerArtifact, scoreRetrievalArtifact, searchKnowledge, sha256, sleepForMemoryRecovery, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, summarizeKnowledgeBenchmarkCampaign, textSourceAdapter, thesisReadinessSpecs, toAgentCandidateKnowledgeRef, toDeepEvalTestCases, toOffPolicyTrajectory, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, withCitedClaim, withKnowledgeImprovementCandidate, withKnowledgeImprovementComparison, writeJson, writeKnowledgeIndex, writeSourceRegistry };
+export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, ClaimLedgerGoalConflictError, 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, KnowledgePageSchema, KnowledgeProposalParseError, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, MemoryKbStore, POLITE_USER_AGENT, READINESS_SPEC_DEFAULTS, ResearchClaimEvidenceSchema, ResearchClaimLedgerSchema, ResearchClaimRecordSchema, RouterError, SCAFFOLD_PAGE_BASENAMES, SourceAnchorSchema, SourceRecordSchema, WIKILINK_REGEX, __resetHttpThrottle, acquireAgentMemoryRunLease, addSourcePath, addSourceText, agentMemorySequenceJudge, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, applyRetrievalHoldout, applySessionStickyRetrievalHoldout, assertClaimLedgerId, assertDeepQuestionIntegrity, assertResearchClaimEvidenceIntegrity, assertResearchClaimLedgerIntegrity, assertTrackedClaimIntegrity, buildAgentMemorySequenceScenarios, buildAgentMemorySequencesFromBenchmarkCases, buildEvalKnowledgeBundle, buildFirstPartyMemoryLifecycleBenchmarkCases, buildIndustryMemoryBenchmarkSmokeCases, buildIndustryRagBenchmarkSmokeCases, buildKnowledgeBenchmarkScenarios, buildKnowledgeGraph, buildKnowledgeIndex, buildRetrievalBenchmarkCasesFromQrels, buildRetrievalEvalDispatch, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, claimEvidenceId, claimId, claimSourceHost, contentKey, createAdaptiveResearchDriver, createAgentMemoryBranch, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createCornellLiiSource, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createFileSystemSearchProvider, createGraphitiMemoryAdapter, createInMemoryBenchmarkAdapter, createIrsPublicationsSource, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createMem0MemoryAdapter, createMemoryExecutionPool, createNeo4jAgentMemoryAdapter, createNoopMemoryBenchmarkAdapter, createPersistentResearchDrivingDriver, createRagAnswerQualityHook, createResearchDrivingDriver, createStateSosSource, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, deepQuestionId, defaultGetMemoryContext, defineReadinessSpec, detectChanges, deterministicRng, diagnoseRagAnswerFailure, emitRetrievalHoldoutBypass, emptyClaimLedger, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractLinks, extractWikilinks, firstMatch, forkAgentMemoryBranchSnapshot, formatFrontmatter, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, 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, optimizeKnowledgeBasePolicy, parseFrontmatter, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, parseKnowledgeWriteBlocks, partitionRetrievalScenarios, politeFetch, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, readRegularFileNoFollow, readRegularFileWithinRoot, reciprocalRankFusion, recoverPendingKnowledgeMutation, removeDurable, renameDurable, renderKnowledgeBenchmarkReportMarkdown, renderMemoryContext, resetRetrievalHoldoutRegistry, resolveMemoryCleanupTimeoutMs, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, restoreKnowledgeCandidateBaseline, retrievalConfigFromSurface, retrievalConfigSurface, retrievalHoldoutConfigHash, retrievalRecallJudge, runAgentMemoryExperiment, runAgentMemoryImprovement, runBoundedMemoryLifecycle, runDiscoveryLoop, runInvestmentThesisTask, runKnowledgeBenchmarkSuite, runKnowledgeResearchLoop, runMemoryAdapterBenchmark, runRagKnowledgeImprovementLoop, runRagOptimization, runRetrievalImprovementLoop, runSerializedKnowledgeOptimization, runVerifiedResearchLoop, scenarioContentFingerprint, scoreKnowledgeBaseIndex, scoreKnowledgeBenchmarkArtifact, scoreMemoryBenchmarkArtifact, scoreRagAnswerArtifact, scoreRetrievalArtifact, searchKnowledge, sha256, sleepForMemoryRecovery, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, summarizeKnowledgeBenchmarkCampaign, syncDirectory, textSourceAdapter, thesisReadinessSpecs, toAgentCandidateKnowledgeRef, toDeepEvalTestCases, toOffPolicyTrajectory, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, withCitedClaim, withKnowledgeImprovementCandidate, withKnowledgeImprovementComparison, withSafeDescendant, withSafeDirectory, writeFileDurable, writeFileDurableWithinRoot, writeJson, writeJsonDurable, writeJsonDurableWithinRoot, writeKnowledgeIndex, writeSourceRegistry };
 
 //# sourceMappingURL=index.js.map