@tangle-network/agent-knowledge 6.1.11 → 6.2.0

package/dist/{inspect-DAXpFyrs.js → inspect-LUMkas6A.js}

@@ -1208,6 +1208,358 @@ function addSourceOverlapEdges(pages, edges) {
 	}
 }
 //#endregion
+//#region src/claim-ledger.ts
+/**
+* The algebra of a research claim ledger: claim identity, and how two ledgers
+* that accumulated evidence for the same goal combine into one.
+*
+* This lives apart from `research-driving-driver.ts` because it is no longer
+* that driver's private business. A ledger is a durable record now, and a
+* durable record addressed by id is a record two writers can reach: two rounds
+* of one run resuming from disk, or two workers researching one goal in
+* parallel. `putClaimLedger` writes the whole record, so the second writer's
+* write erases the first writer's claims — the ledger persists and the
+* knowledge still does not compound. Combining is therefore part of what the
+* record MEANS, and it belongs next to the record rather than inside one
+* consumer of it.
+*
+* Every combination here is monotone: support only grows, contradiction edges
+* only accumulate, `contested` only latches on, `firstSeenRound` only moves
+* earlier. That is what makes it safe to apply twice — a retried write cannot
+* produce a different ledger than a single write did.
+*/
+/**
+* Claim identity = sha256 of the normalized claim text, so the same assertion
+* discovered independently by two workers is ONE claim with two supporting
+* sources rather than two claims with one each — which is the difference
+* between corroborated and unsupported.
+*/
+function claimId(text) {
+	return `c_${sha256(normalizeClaimText(text)).slice(0, 16)}`;
+}
+/** Stable identity for one extracted claim/source/contradiction observation. */
+function claimEvidenceId(claim) {
+	return `e_${sha256(JSON.stringify([
+		claim.claimId,
+		claim.sourceUri,
+		claim.contradictsClaimId ?? null
+	])).slice(0, 16)}`;
+}
+/** Case-, whitespace-, and stylistic-punctuation-insensitive claim identity form. */
+function normalizeClaimText(text) {
+	return text.normalize("NFKC").toLowerCase().replace(/<=|≤/gu, " symbol_less_than_or_equal ").replace(/>=|≥/gu, " symbol_greater_than_or_equal ").replace(/!=|≠/gu, " symbol_not_equal ").replace(/==|=/gu, " symbol_equal ").replace(/±/gu, " symbol_plus_or_minus ").replace(/[≈~]/gu, " symbol_approximately ").replace(/<|←|⇐/gu, " symbol_less_or_left ").replace(/>|→|⇒/gu, " symbol_greater_or_right ").replace(/[+]/gu, " symbol_plus_or_positive ").replace(/[-−]/gu, " symbol_minus_or_negative ").replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim();
+}
+/**
+* The canonical host a source uri counts as, which is what makes two sources
+* INDEPENDENT: corroboration is "distinct hosts", so this function is the rule
+* that decides whether a claim is confirmed or merely repeated. Exported so a
+* consumer building a `ResearchClaimRecord` cannot answer it a different way — a
+* consumer that counted raw uris would report two pages of one site as
+* independent confirmation.
+*/
+function claimSourceHost(uri) {
+	try {
+		return new URL(uri.trim()).hostname.toLowerCase().replace(/^www\./, "");
+	} catch {
+		return uri.trim().toLowerCase();
+	}
+}
+/** Stable identity for one deep question. */
+function deepQuestionId(kind, text) {
+	return `q_${sha256(`${kind}:${text}`).slice(0, 16)}`;
+}
+/**
+* Refuse a claim record whose identity or source count disagrees with its evidence.
+*
+* `supportingHosts` is used as the independent-source count, so accepting hosts
+* that cannot be derived from `supportingUris` would let a malformed record
+* manufacture corroboration. Canonical ordering also makes equal records have
+* equal bytes regardless of which process assembled them.
+*/
+function assertTrackedClaimIntegrity(claim) {
+	if (claim.id !== claimId(claim.text)) throw new Error(`claim '${claim.id}' does not match its text-derived identity`);
+	if (claim.text !== claim.text.trim()) throw new Error(`claim '${claim.id}' text must not have surrounding whitespace`);
+	assertSortedUnique(`claim '${claim.id}' supportingUris`, claim.supportingUris);
+	assertSortedUnique(`claim '${claim.id}' supportingHosts`, claim.supportingHosts);
+	assertSortedUnique(`claim '${claim.id}' contradicts`, claim.contradicts);
+	const expectedHosts = [...new Set(claim.supportingUris.map(claimSourceHost).filter(Boolean))].sort();
+	if (!sameStrings(claim.supportingHosts, expectedHosts)) throw new Error(`claim '${claim.id}' supportingHosts must equal the hosts derived from supportingUris`);
+	if (claim.contradicts.includes(claim.id)) throw new Error(`claim '${claim.id}' cannot contradict itself`);
+	if (claim.contradicts.length > 0 && !claim.contested) throw new Error(`claim '${claim.id}' with a contradiction must be contested`);
+}
+/** Refuse a deep question whose stable identity or set fields are malformed. */
+function assertDeepQuestionIntegrity(question) {
+	if (question.id !== deepQuestionId(question.kind, question.text)) throw new Error(`question '${question.id}' does not match its kind-and-text identity`);
+	if (question.text !== question.text.trim()) throw new Error(`question '${question.id}' text must not have surrounding whitespace`);
+	assertSortedUnique(`question '${question.id}' claimIds`, question.claimIds);
+}
+/** Refuse an extracted observation whose identity or content is malformed. */
+function assertResearchClaimEvidenceIntegrity(evidence) {
+	if (evidence.claimId !== claimId(evidence.text)) throw new Error(`claim evidence '${evidence.id}' does not match its text-derived claim identity`);
+	if (evidence.id !== claimEvidenceId(evidence)) throw new Error(`claim evidence '${evidence.id}' does not match its content-derived identity`);
+	if (evidence.text !== evidence.text.trim()) throw new Error(`claim evidence '${evidence.id}' text must not have surrounding whitespace`);
+	if (evidence.contradictsClaimId === evidence.claimId) throw new Error(`claim evidence '${evidence.id}' cannot contradict its own claim`);
+}
+/** Refuse a ledger that is not one canonical, internally consistent record. */
+function assertResearchClaimLedgerIntegrity(ledger) {
+	if (ledger.preparedRounds !== void 0 && ledger.preparedRounds <= ledger.rounds) throw new Error(`claim ledger '${ledger.id}' preparedRounds must be greater than completed rounds`);
+	assertSortedUnique(`claim ledger '${ledger.id}' claimEvidence`, ledger.claimEvidence.map((evidence) => evidence.id));
+	assertSortedUnique(`claim ledger '${ledger.id}' registeredSourceUris`, ledger.registeredSourceUris);
+	assertSortedUnique(`claim ledger '${ledger.id}' claims`, ledger.claims.map((claim) => claim.id));
+	assertSortedUnique(`claim ledger '${ledger.id}' questions`, ledger.questions.map((question) => question.id));
+	for (const evidence of ledger.claimEvidence) assertResearchClaimEvidenceIntegrity(evidence);
+	const registeredSourceUris = new Set(ledger.registeredSourceUris);
+	for (const claim of ledger.claims) {
+		assertTrackedClaimIntegrity(claim);
+		for (const sourceUri of claim.supportingUris) if (!registeredSourceUris.has(sourceUri)) throw new Error(`claim '${claim.id}' counts source '${sourceUri}' before its registration is confirmed`);
+	}
+	const claimsById = new Map(ledger.claims.map((claim) => [claim.id, claim]));
+	const claimIds = new Set(claimsById.keys());
+	for (const evidence of ledger.claimEvidence) {
+		if (!registeredSourceUris.has(evidence.sourceUri)) continue;
+		const claim = claimsById.get(evidence.claimId);
+		if (!claim?.supportingUris.includes(evidence.sourceUri)) throw new Error(`registered claim evidence '${evidence.id}' must be materialized in its claim`);
+		if (evidence.contradictsClaimId !== void 0 && claimsById.has(evidence.contradictsClaimId) && !claim.contradicts.includes(evidence.contradictsClaimId)) throw new Error(`registered claim evidence '${evidence.id}' must materialize its contradiction`);
+	}
+	for (const question of ledger.questions) {
+		assertDeepQuestionIntegrity(question);
+		for (const claimId of question.claimIds) if (!claimIds.has(claimId)) throw new Error(`question '${question.id}' references claim '${claimId}' outside its ledger`);
+	}
+}
+/** A ledger with nothing in it yet. */
+function emptyClaimLedger(id, goal) {
+	return {
+		id,
+		...goal === void 0 ? {} : { goal },
+		updatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+		rounds: 0,
+		claimEvidence: [],
+		registeredSourceUris: [],
+		claims: [],
+		questions: []
+	};
+}
+/**
+* Turn only evidence backed by a confirmed source registration into support.
+*
+* This is a monotone closure: it never removes claims or evidence, and running
+* it twice is a no-op. Keeping it in the ledger algebra means a source-confirming
+* writer and an evidence-producing writer can arrive in either order.
+*/
+function materializeRegisteredClaimEvidence(ledger) {
+	const registered = new Set(ledger.registeredSourceUris);
+	const claims = new Map(ledger.claims.map((claim) => [claim.id, claim]));
+	for (const evidence of ledger.claimEvidence) {
+		if (!registered.has(evidence.sourceUri)) continue;
+		const host = claimSourceHost(evidence.sourceUri);
+		const observed = {
+			id: evidence.claimId,
+			text: evidence.text,
+			supportingHosts: host ? [host] : [],
+			supportingUris: [evidence.sourceUri],
+			contradicts: [],
+			contested: false,
+			firstSeenRound: evidence.firstSeenRound
+		};
+		const existing = claims.get(observed.id);
+		claims.set(observed.id, existing ? mergeTrackedClaims(existing, observed) : observed);
+	}
+	for (const evidence of ledger.claimEvidence) {
+		const otherId = evidence.contradictsClaimId;
+		if (!registered.has(evidence.sourceUri) || !otherId || !claims.has(otherId)) continue;
+		const claim = claims.get(evidence.claimId);
+		if (!claim) continue;
+		claims.set(claim.id, {
+			...claim,
+			contradicts: union(claim.contradicts, [otherId]),
+			contested: true
+		});
+	}
+	return linkClaimContradictions({
+		...ledger,
+		claims: [...claims.values()].sort((left, right) => left.id.localeCompare(right.id))
+	});
+}
+/**
+* Raised when two ledgers that accumulated evidence for DIFFERENT goals are
+* combined. Merging them would pool two questions' evidence into one
+* corroboration count, which reports a claim as independently confirmed when
+* nobody confirmed it — strictly worse than losing the ledger, so this refuses.
+*/
+var ClaimLedgerGoalConflictError = class extends Error {
+	ledgerId;
+	existingGoal;
+	incomingGoal;
+	constructor(ledgerId, existingGoal, incomingGoal) {
+		super(`claim ledger '${ledgerId}' accumulated evidence for goal '${existingGoal}' and cannot be merged with evidence for '${incomingGoal}'`);
+		this.ledgerId = ledgerId;
+		this.existingGoal = existingGoal;
+		this.incomingGoal = incomingGoal;
+		this.name = "ClaimLedgerGoalConflictError";
+	}
+};
+/**
+* Combine two records of the same claim.
+*
+* Union on every support collection, because a claim asserted by hosts {a} in
+* one writer and {b} in another is asserted by two independent hosts and the
+* whole completion oracle turns on that count. `contested` is OR — one writer
+* seeing a contradiction is enough for the claim to be contested, and no later
+* writer that simply did not see it may clear the flag.
+*/
+function mergeTrackedClaims(base, incoming) {
+	assertTrackedClaimIntegrity(base);
+	assertTrackedClaimIntegrity(incoming);
+	if (base.id !== incoming.id) throw new Error(`cannot merge claim '${base.id}' with a different claim '${incoming.id}'`);
+	const text = incoming.firstSeenRound < base.firstSeenRound ? incoming.text : incoming.firstSeenRound > base.firstSeenRound ? base.text : incoming.text < base.text ? incoming.text : base.text;
+	return {
+		id: base.id,
+		text,
+		supportingHosts: union(base.supportingHosts, incoming.supportingHosts),
+		supportingUris: union(base.supportingUris, incoming.supportingUris),
+		contradicts: union(base.contradicts, incoming.contradicts),
+		contested: base.contested || incoming.contested,
+		firstSeenRound: Math.min(base.firstSeenRound, incoming.firstSeenRound)
+	};
+}
+/**
+* Combine two ledgers for the same run.
+*
+* `addressed` on a question is OR for the same reason `contested` is: a writer
+* that answered a question has answered it, and a writer that never saw the
+* answer must not reopen it. Everything else is a union or an extreme, so this
+* is associative and idempotent — merge order cannot change the result and a
+* replayed merge is a no-op.
+*/
+function mergeClaimLedgers(base, incoming) {
+	assertResearchClaimLedgerIntegrity(base);
+	assertResearchClaimLedgerIntegrity(incoming);
+	if (base.id !== incoming.id) throw new Error(`cannot merge claim ledger '${base.id}' with a different ledger '${incoming.id}'`);
+	if (base.goal !== void 0 && incoming.goal !== void 0 && base.goal !== incoming.goal) throw new ClaimLedgerGoalConflictError(base.id, base.goal, incoming.goal);
+	const goal = base.goal ?? incoming.goal;
+	const claimEvidence = new Map(base.claimEvidence.map((evidence) => [evidence.id, evidence]));
+	for (const evidence of incoming.claimEvidence) {
+		const existing = claimEvidence.get(evidence.id);
+		claimEvidence.set(evidence.id, existing ? mergeClaimEvidence(existing, evidence) : evidence);
+	}
+	const claims = new Map(base.claims.map((claim) => [claim.id, claim]));
+	for (const claim of incoming.claims) {
+		const existing = claims.get(claim.id);
+		claims.set(claim.id, existing ? mergeTrackedClaims(existing, claim) : claim);
+	}
+	const questions = new Map(base.questions.map((question) => [question.id, question]));
+	for (const question of incoming.questions) {
+		const existing = questions.get(question.id);
+		if (existing && (existing.kind !== question.kind || existing.text !== question.text)) throw new Error(`question '${question.id}' has conflicting immutable content`);
+		questions.set(question.id, existing ? {
+			...existing,
+			claimIds: union(existing.claimIds, question.claimIds),
+			addressed: existing.addressed || question.addressed,
+			raisedRound: Math.min(existing.raisedRound, question.raisedRound)
+		} : question);
+	}
+	const rounds = Math.max(base.rounds, incoming.rounds);
+	const preparedRounds = Math.max(base.preparedRounds ?? base.rounds, incoming.preparedRounds ?? incoming.rounds);
+	return materializeRegisteredClaimEvidence({
+		id: base.id,
+		...goal === void 0 ? {} : { goal },
+		updatedAt: incoming.updatedAt.localeCompare(base.updatedAt) > 0 ? incoming.updatedAt : base.updatedAt,
+		rounds,
+		...preparedRounds > rounds ? { preparedRounds } : {},
+		claimEvidence: [...claimEvidence.values()].sort((left, right) => left.id.localeCompare(right.id)),
+		registeredSourceUris: union(base.registeredSourceUris, incoming.registeredSourceUris),
+		claims: [...claims.values()].sort((a, b) => a.id.localeCompare(b.id)),
+		questions: [...questions.values()].sort((a, b) => a.id.localeCompare(b.id))
+	});
+}
+function mergeClaimEvidence(base, incoming) {
+	assertResearchClaimEvidenceIntegrity(base);
+	assertResearchClaimEvidenceIntegrity(incoming);
+	if (base.id !== incoming.id || base.claimId !== incoming.claimId || base.sourceUri !== incoming.sourceUri || base.contradictsClaimId !== incoming.contradictsClaimId) throw new Error(`claim evidence '${base.id}' has conflicting immutable content`);
+	const text = incoming.firstSeenRound < base.firstSeenRound ? incoming.text : incoming.firstSeenRound > base.firstSeenRound ? base.text : incoming.text < base.text ? incoming.text : base.text;
+	return {
+		...base,
+		text,
+		firstSeenRound: Math.min(base.firstSeenRound, incoming.firstSeenRound)
+	};
+}
+/**
+* Make every contradiction edge symmetric and mark both ends contested.
+*
+* A contradiction is a property of a PAIR, and a writer only ever sees one side
+* of it: the worker that found the refuting source records "X contradicts Y" and
+* knows nothing about Y's record. Left one-sided, Y reads as an uncontested
+* claim, and the completion oracle would settle a question two sources disagree
+* about. `createResearchDrivingDriver` does this pairwise as it records; this is
+* the same rule stated over a whole ledger, for writers that assemble one from
+* events rather than from a live loop.
+*
+* Idempotent and monotone like every other rule here: edges only appear and
+* `contested` only latches on, so applying it twice changes nothing. An edge
+* pointing at a claim this ledger does not hold is KEPT — the other side may
+* arrive from another writer later, and discarding evidence of disagreement
+* because the counterpart has not shown up yet is the failure this prevents.
+*/
+function linkClaimContradictions(ledger) {
+	const inbound = /* @__PURE__ */ new Map();
+	for (const claim of ledger.claims) for (const other of claim.contradicts) {
+		if (other === claim.id) continue;
+		const edges = inbound.get(other);
+		if (edges) edges.push(claim.id);
+		else inbound.set(other, [claim.id]);
+	}
+	return {
+		...ledger,
+		claims: ledger.claims.map((claim) => {
+			const contradicts = union(claim.contradicts.filter((other) => other !== claim.id), inbound.get(claim.id) ?? []);
+			return {
+				...claim,
+				contradicts,
+				contested: claim.contested || contradicts.length > 0
+			};
+		}).sort((a, b) => a.id.localeCompare(b.id))
+	};
+}
+/**
+* Set union, SORTED.
+*
+* Sorted because these collections are sets and merging must be commutative:
+* arrival order is not part of what the ledger says, so two writers arriving in
+* either order have to produce identical bytes. Preserving first-seen order
+* instead made `merge(a, b)` and `merge(b, a)` differ, which the order-
+* independence test caught — and a non-commutative merge under a filesystem
+* lock means the record depends on scheduling.
+*/
+function union(base, incoming) {
+	return [.../* @__PURE__ */ new Set([...base, ...incoming])].sort();
+}
+function assertSortedUnique(label, values) {
+	for (let index = 1; index < values.length; index += 1) if ((values[index - 1] ?? "") >= (values[index] ?? "")) throw new Error(`${label} must be sorted and contain no duplicates`);
+}
+function sameStrings(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+//#endregion
+//#region src/types.ts
+/**
+* The event vocabulary, as a value so the runtime schema is DERIVED from it
+* rather than restated. A restated copy in `schemas.ts` drifted: it omitted
+* `research.iteration`, which is the only event `runVerifiedResearchLoop`
+* produces, so every attempt to store one would have been rejected. Nothing
+* caught it because nothing ever stored an event. Add a type here and the
+* schema accepts it in the same edit.
+*/
+const KNOWLEDGE_EVENT_TYPES = [
+	"source.added",
+	"proposal.applied",
+	"index.built",
+	"lint.run",
+	"research.iteration",
+	"optimization.run",
+	"release.promoted",
+	"release.rejected"
+];
+//#endregion
 //#region src/schemas.ts
 const SourceAnchorSchema = z.object({
 	id: z.string().min(1),
@@ -1271,20 +1623,71 @@ const KnowledgeIndexSchema = z.object({
 });
 const KnowledgeEventSchema = z.object({
 	id: z.string().min(1),
-	type: z.enum([
-		"source.added",
-		"proposal.applied",
-		"index.built",
-		"lint.run",
-		"optimization.run",
-		"release.promoted",
-		"release.rejected"
-	]),
+	type: z.enum(KNOWLEDGE_EVENT_TYPES),
 	createdAt: z.string().min(1),
 	actor: z.string().optional(),
 	target: z.string().optional(),
 	metadata: z.record(z.string(), z.unknown()).optional()
 });
+const DeepQuestionSchema = z.object({
+	kind: z.enum([
+		"comparative",
+		"mechanism",
+		"gap",
+		"contradiction"
+	]),
+	text: z.string().min(1),
+	id: z.string().min(1),
+	claimIds: z.array(z.string().min(1)),
+	addressed: z.boolean(),
+	raisedRound: z.number().int().nonnegative()
+}).strict().superRefine((question, context) => {
+	reportIntegrityError(context, () => assertDeepQuestionIntegrity(question));
+});
+const ResearchClaimRecordSchema = z.object({
+	id: z.string().min(1),
+	text: z.string().min(1),
+	supportingHosts: z.array(z.string().min(1)),
+	supportingUris: z.array(z.string().min(1)),
+	contradicts: z.array(z.string().min(1)),
+	contested: z.boolean(),
+	firstSeenRound: z.number().int().nonnegative()
+}).strict().superRefine((claim, context) => {
+	reportIntegrityError(context, () => assertTrackedClaimIntegrity(claim));
+});
+const ResearchClaimEvidenceSchema = z.object({
+	id: z.string().min(1),
+	claimId: z.string().min(1),
+	text: z.string().min(1),
+	sourceUri: z.string().min(1),
+	contradictsClaimId: z.string().min(1).optional(),
+	firstSeenRound: z.number().int().nonnegative()
+}).strict().superRefine((evidence, context) => {
+	reportIntegrityError(context, () => assertResearchClaimEvidenceIntegrity(evidence));
+});
+const ResearchClaimLedgerSchema = z.object({
+	id: z.string().min(1),
+	goal: z.string().trim().min(1).optional(),
+	updatedAt: z.iso.datetime(),
+	rounds: z.number().int().nonnegative(),
+	preparedRounds: z.number().int().nonnegative().optional(),
+	claimEvidence: z.array(ResearchClaimEvidenceSchema),
+	registeredSourceUris: z.array(z.string().min(1)),
+	claims: z.array(ResearchClaimRecordSchema),
+	questions: z.array(DeepQuestionSchema)
+}).strict().superRefine((ledger, context) => {
+	reportIntegrityError(context, () => assertResearchClaimLedgerIntegrity(ledger));
+});
+function reportIntegrityError(context, check) {
+	try {
+		check();
+	} catch (error) {
+		context.addIssue({
+			code: "custom",
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
 const KnowledgeBaseCandidateSchema = z.object({
 	id: z.string().min(1),
 	units: z.array(z.object({
@@ -1327,6 +1730,263 @@ const KnowledgeBaseCandidateSchema = z.object({
 	metadata: z.record(z.string(), z.unknown()).optional()
 });
 //#endregion
+//#region src/kb-store.ts
+/**
+* Where a filesystem knowledge base keeps its machine-written records, relative
+* to the knowledge-base root.
+*
+* This is the ONE location. `FileSystemKbStore` used to write `<dir>/index.json`
+* while `writeKnowledgeIndex` wrote `<root>/.agent-knowledge/index.json` — two
+* index writers, two files, and only the second one reachable, so a store that
+* had just been written to reported an empty knowledge base. Both now go through
+* `FileSystemKbStore`, anchored on the knowledge-base root, which is also the
+* directory `withKnowledgeMutation` locks: one file, one lock domain.
+*/
+const KB_STORE_DIR = ".agent-knowledge";
+const KB_INDEX_PATH = `${KB_STORE_DIR}/index.json`;
+const KB_EVENTS_PATH = `${KB_STORE_DIR}/events.json`;
+const KB_CLAIM_LEDGER_DIR = `${KB_STORE_DIR}/claim-ledgers`;
+/**
+* A claim-ledger id is used as a filename, so it is restricted to one safe path
+* segment. Rejecting rather than sanitising is deliberate: a sanitised id maps
+* two different runs onto one file and silently merges their belief state.
+*/
+const LEDGER_ID_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+function assertClaimLedgerId(id) {
+	if (!LEDGER_ID_PATTERN.test(id) || id === "." || id === "..") throw new Error(`claim ledger id must match ${LEDGER_ID_PATTERN} and cannot be a path segment: ${id}`);
+	return id;
+}
+var MemoryKbStore = class {
+	sources = /* @__PURE__ */ new Map();
+	pages = /* @__PURE__ */ new Map();
+	events = [];
+	claimLedgers = /* @__PURE__ */ new Map();
+	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);
+	}
+	async putClaimLedger(ledger) {
+		const parsed = ResearchClaimLedgerSchema.parse(ledger);
+		this.claimLedgers.set(assertClaimLedgerId(parsed.id), clone(parsed));
+	}
+	async getClaimLedger(id) {
+		return clone(this.claimLedgers.get(assertClaimLedgerId(id)) ?? null);
+	}
+	async listClaimLedgers() {
+		return [...this.claimLedgers.values()].map(clone).sort((a, b) => a.id.localeCompare(b.id));
+	}
+	async mergeClaimLedger(id, merge) {
+		const key = assertClaimLedgerId(id);
+		const next = assertMergedLedgerId(key, merge(clone(this.claimLedgers.get(key) ?? null)));
+		await this.putClaimLedger(next);
+		return clone(next);
+	}
+};
+const knowledgeEventsSchema = z.array(KnowledgeEventSchema);
+var FileSystemKbStore = class {
+	root;
+	indexPath;
+	eventsPath;
+	claimLedgerDir;
+	/**
+	* A string retains the published direct-directory contract.
+	* The object form explicitly selects a knowledge-base root and the canonical
+	* `.agent-knowledge/` layout. A string naming that exact canonical directory
+	* keeps its file paths but shares the root form's lock domain.
+	*/
+	constructor(input) {
+		const directDirectory = typeof input === "string" ? resolve(input) : void 0;
+		const aliasesCanonicalDirectory = directDirectory !== void 0 && basename(directDirectory) === ".agent-knowledge";
+		this.root = aliasesCanonicalDirectory ? dirname(directDirectory) : typeof input === "string" ? input : input.root;
+		const canonicalLayout = typeof input !== "string" || aliasesCanonicalDirectory;
+		this.indexPath = canonicalLayout ? KB_INDEX_PATH : "index.json";
+		this.eventsPath = canonicalLayout ? KB_EVENTS_PATH : "events.json";
+		this.claimLedgerDir = canonicalLayout ? KB_CLAIM_LEDGER_DIR : "claim-ledgers";
+	}
+	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.root, async () => {
+			return clone((await this.readIndex())?.sources.find((source) => source.id === id) ?? null);
+		});
+	}
+	async listSources() {
+		return withKnowledgeRead(this.root, 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.root, async () => {
+			return clone((await this.readIndex())?.pages.find((page) => page.id === idOrPath || page.path === idOrPath) ?? null);
+		});
+	}
+	async listPages() {
+		return withKnowledgeRead(this.root, async () => clone((await this.readIndex())?.pages ?? []));
+	}
+	async putIndex(index) {
+		const parsed = KnowledgeIndexSchema.parse(index);
+		await withKnowledgeMutation(this.root, () => writeJsonDurableWithinRoot(this.root, this.indexPath, parsed));
+	}
+	async getIndex() {
+		return withKnowledgeRead(this.root, () => this.readIndex());
+	}
+	async putEvent(event) {
+		const parsed = KnowledgeEventSchema.parse(event);
+		await withKnowledgeMutation(this.root, async () => {
+			const next = [...(await this.readEvents()).filter((entry) => entry.id !== parsed.id), parsed].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+			await writeJsonDurableWithinRoot(this.root, this.eventsPath, next);
+		});
+	}
+	async listEvents(query = {}) {
+		return withKnowledgeRead(this.root, async () => {
+			let events = await this.readEvents();
+			if (query.type) events = events.filter((event) => event.type === query.type);
+			if (query.target) events = events.filter((event) => event.target === query.target);
+			return clone(events.slice(-(query.limit ?? events.length)));
+		});
+	}
+	async putClaimLedger(ledger) {
+		const parsed = ResearchClaimLedgerSchema.parse(ledger);
+		const path = this.claimLedgerPath(parsed.id);
+		await withKnowledgeMutation(this.root, () => writeJsonDurableWithinRoot(this.root, path, parsed));
+	}
+	async getClaimLedger(id) {
+		const path = this.claimLedgerPath(id);
+		return withKnowledgeRead(this.root, () => readJsonFile(this.root, path, ResearchClaimLedgerSchema));
+	}
+	async listClaimLedgers() {
+		return withKnowledgeRead(this.root, async () => {
+			let files;
+			try {
+				files = await listRegularFilesWithinRoot(this.root, this.claimLedgerDir);
+			} catch (error) {
+				if (isMissingFile(error)) return [];
+				throw error;
+			}
+			const ledgers = [];
+			for (const file of files) {
+				if (!file.path.endsWith(".json")) continue;
+				ledgers.push(ResearchClaimLedgerSchema.parse(JSON.parse(file.bytes.toString("utf8"))));
+			}
+			return ledgers.sort((a, b) => a.id.localeCompare(b.id));
+		});
+	}
+	async mergeClaimLedger(id, merge) {
+		const key = assertClaimLedgerId(id);
+		return withKnowledgeMutation(this.root, async () => {
+			const current = await readJsonFile(this.root, this.claimLedgerPath(key), ResearchClaimLedgerSchema);
+			const next = assertMergedLedgerId(key, merge(current));
+			await this.putClaimLedger(next);
+			return next;
+		});
+	}
+	async updateIndex(change) {
+		await withKnowledgeMutation(this.root, async () => {
+			const current = await this.readIndex() ?? emptyIndex(this.root);
+			const next = KnowledgeIndexSchema.parse(change(current));
+			await writeJsonDurableWithinRoot(this.root, this.indexPath, next);
+		});
+	}
+	async readIndex() {
+		return readJsonFile(this.root, this.indexPath, KnowledgeIndexSchema);
+	}
+	async readEvents() {
+		return await readJsonFile(this.root, this.eventsPath, knowledgeEventsSchema) ?? [];
+	}
+	claimLedgerPath(id) {
+		return `${this.claimLedgerDir}/${assertClaimLedgerId(id)}.json`;
+	}
+};
+/**
+* A merge that returns a ledger under a different id would write that ledger to
+* the file the caller asked to merge, giving one file two identities. Refuse
+* rather than trust the merge function to be well behaved.
+*/
+function assertMergedLedgerId(id, merged) {
+	if (merged.id !== id) throw new Error(`merge of claim ledger '${id}' returned a ledger with id '${merged.id}'`);
+	return merged;
+}
+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/sources.ts
 const sourceRegistrySchema = z.object({
 	generatedAt: z.string().min(1),
@@ -1552,10 +2212,19 @@ async function buildKnowledgeIndexUnlocked(root) {
 		graph: buildKnowledgeGraph(pages)
 	};
 }
+/**
+* Build the index from the knowledge tree and store it.
+*
+* The write goes through `FileSystemKbStore` rather than straight to disk: this
+* function and the store used to write two different index files in two
+* different places, so a knowledge base could hold two disagreeing indexes and
+* a store-based reader saw none of the indexer's work. One writer now, and it
+* validates through `KnowledgeIndexSchema` on the way out.
+*/
 async function writeKnowledgeIndex(root) {
 	return withKnowledgeMutation(root, async () => {
 		const index = await buildKnowledgeIndexUnlocked(root);
-		await writeJsonDurableWithinRoot(root, ".agent-knowledge/index.json", index);
+		await new FileSystemKbStore({ root }).putIndex(index);
 		return index;
 	});
 }
@@ -1865,6 +2534,6 @@ function explainKnowledgeTarget(index, target) {
 	};
 }
 //#endregion
-export { writeFileDurableWithinRoot as $, loadKnowledgePages as A, withKnowledgeMutation as B, SourceAnchorSchema as C, initKnowledgeBase as D, SCAFFOLD_PAGE_BASENAMES as E, formatFrontmatter as F, knowledgeFileTransactionPlanHash as G, applyKnowledgeFileTransaction as H, parseFrontmatter as I, isMissingFile as J, prepareKnowledgeFileTransaction as K, acquireDurableFileLock as L, WIKILINK_REGEX as M, extractWikilinks as N, isScaffoldPath as O, normalizeLinkTarget as P, withSafeDirectory as Q, inspectPendingKnowledgeMutation as R, KnowledgePageSchema as S, buildKnowledgeGraph as T, assertKnowledgeMutationPath as U, withKnowledgeRead as V, finishKnowledgeFileTransaction as W, readRegularFileWithinRoot as X, listRegularFilesWithinRoot as Y, renameDurable as Z, KnowledgeBaseCandidateSchema as _, applyKnowledgeWriteBlocksFile as a, KnowledgeGraphNodeSchema as b, validateKnowledgeIndex as c, writeKnowledgeIndex as d, writeJsonDurableWithinRoot as et, addSourcePath as f, writeSourceRegistry as g, sourceRegistryPath as h, applyKnowledgeWriteBlocks as i, writeJson as j, layoutFor as k, lintKnowledgeIndex as l, loadSourceRegistry as m, inspectKnowledgeIndex as n, textSourceAdapter as nt, isSafeKnowledgePath as o, addSourceText as p, rollbackKnowledgeFileTransaction as q, stringMetadata as r, parseKnowledgeWriteBlocks as s, explainKnowledgeTarget as t, mediaTypeFor$1 as tt, buildKnowledgeIndex as u, KnowledgeEventSchema as v, SourceRecordSchema as w, KnowledgeIndexSchema as x, KnowledgeGraphEdgeSchema as y, recoverPendingKnowledgeMutation as z };
+export { SCAFFOLD_PAGE_BASENAMES as $, KnowledgePageSchema as A, withSafeDirectory as At, assertResearchClaimLedgerIntegrity as B, assertClaimLedgerId as C, listRegularFilesWithinRoot as Ct, KnowledgeGraphEdgeSchema as D, renameDurable as Dt, KnowledgeEventSchema as E, removeDurable as Et, SourceRecordSchema as F, mediaTypeFor$1 as Ft, deepQuestionId as G, claimEvidenceId as H, KNOWLEDGE_EVENT_TYPES as I, textSourceAdapter as It, materializeRegisteredClaimEvidence as J, emptyClaimLedger as K, ClaimLedgerGoalConflictError as L, ResearchClaimLedgerSchema as M, writeFileDurableWithinRoot as Mt, ResearchClaimRecordSchema as N, writeJsonDurable as Nt, KnowledgeGraphNodeSchema as O, syncDirectory as Ot, SourceAnchorSchema as P, writeJsonDurableWithinRoot as Pt, buildKnowledgeGraph as Q, assertDeepQuestionIntegrity as R, MemoryKbStore as S, isMissingFile as St, KnowledgeBaseCandidateSchema as T, readRegularFileWithinRoot as Tt, claimId as U, assertTrackedClaimIntegrity as V, claimSourceHost as W, mergeTrackedClaims as X, mergeClaimLedgers as Y, normalizeClaimText as Z, FileSystemKbStore as _, finishKnowledgeFileTransaction as _t, applyKnowledgeWriteBlocksFile as a, WIKILINK_REGEX as at, KB_INDEX_PATH as b, rollbackKnowledgeFileTransaction as bt, validateKnowledgeIndex as c, formatFrontmatter as ct, writeKnowledgeIndex as d, inspectPendingKnowledgeMutation as dt, initKnowledgeBase as et, addSourcePath as f, recoverPendingKnowledgeMutation as ft, writeSourceRegistry as g, assertKnowledgeMutationPath as gt, sourceRegistryPath as h, applyKnowledgeFileTransaction as ht, applyKnowledgeWriteBlocks as i, writeJson as it, ResearchClaimEvidenceSchema as j, writeFileDurable as jt, KnowledgeIndexSchema as k, withSafeDescendant as kt, lintKnowledgeIndex as l, parseFrontmatter as lt, loadSourceRegistry as m, withKnowledgeRead as mt, inspectKnowledgeIndex as n, layoutFor as nt, isSafeKnowledgePath as o, extractWikilinks as ot, addSourceText as p, withKnowledgeMutation as pt, linkClaimContradictions as q, stringMetadata as r, loadKnowledgePages as rt, parseKnowledgeWriteBlocks as s, normalizeLinkTarget as st, explainKnowledgeTarget as t, isScaffoldPath as tt, buildKnowledgeIndex as u, acquireDurableFileLock as ut, KB_CLAIM_LEDGER_DIR as v, knowledgeFileTransactionPlanHash as vt, DeepQuestionSchema as w, readRegularFileNoFollow as wt, KB_STORE_DIR as x, isKernelAnchoredPath as xt, KB_EVENTS_PATH as y, prepareKnowledgeFileTransaction as yt, assertResearchClaimEvidenceIntegrity as z };
 
-//# sourceMappingURL=inspect-DAXpFyrs.js.map
+//# sourceMappingURL=inspect-LUMkas6A.js.map