@tangle-network/agent-knowledge 8.0.8 → 8.0.10

package/dist/{inspect-B7AJ7CZS.js → inspect-0tmv3xV8.js}

@@ -1473,6 +1473,7 @@ const KnowledgePageSchema = z.object({
 	sourceIds: z.array(z.string()),
 	tags: z.array(z.string()),
 	outLinks: z.array(z.string()),
+	cites: z.array(z.string().min(1)).optional(),
 	contradicts: z.array(z.string().min(1)).optional(),
 	invalidation: KnowledgePageInvalidationSchema.optional()
 });
@@ -1708,6 +1709,7 @@ async function loadKnowledgePagesUnlocked(root, options) {
 		const title = stringField(frontmatter.title) ?? firstHeading(body) ?? rel.split("/").pop().replace(/\.md$/, "");
 		const sourceIds = arrayField(frontmatter.sources);
 		const tags = arrayField(frontmatter.tags);
+		const cites = idListField(frontmatter.cites);
 		const contradicts = idListField(frontmatter.contradicts);
 		const invalidation = KnowledgePageInvalidationSchema.safeParse(frontmatter.invalidation);
 		const pageRelativePath = rel.startsWith(pagesPrefix) ? rel.slice(pagesPrefix.length) : rel;
@@ -1720,6 +1722,7 @@ async function loadKnowledgePagesUnlocked(root, options) {
 			sourceIds,
 			tags,
 			outLinks: extractWikilinks(body).map(normalizeLinkTarget),
+			...cites.length > 0 ? { cites } : {},
 			...contradicts.length > 0 ? { contradicts } : {},
 			...invalidation.success ? { invalidation: invalidation.data } : {}
 		});
@@ -1771,12 +1774,164 @@ function firstHeading(body) {
 	return /^#\s+(.+)$/m.exec(body)?.[1]?.trim();
 }
 //#endregion
+//#region src/citation-resolution.ts
+/** A batch contains at least one citation that is missing or ambiguous. */
+var KnowledgeCitationResolutionError = class extends Error {
+	resolutions;
+	constructor(resolutions) {
+		const unresolved = resolutions.filter((resolution) => resolution.status !== "resolved");
+		const missing = unresolved.filter((resolution) => resolution.status === "missing").map((resolution) => formatKnowledgeCitationReference(resolution.reference));
+		const ambiguous = unresolved.filter((resolution) => resolution.status === "ambiguous").map((resolution) => `${formatKnowledgeCitationReference(resolution.reference)} (${resolution.candidates.length} matches)`);
+		const parts = [missing.length > 0 ? `missing: ${missing.join(", ")}` : "", ambiguous.length > 0 ? `ambiguous: ${ambiguous.join(", ")}` : ""].filter(Boolean);
+		super(`knowledge citation resolution failed: ${parts.join("; ")}`);
+		this.name = "KnowledgeCitationResolutionError";
+		this.resolutions = Object.freeze([...unresolved]);
+	}
+};
+/** A persisted page contains a self, missing, or ambiguous citation. */
+var KnowledgeCitationAuditError = class extends Error {
+	report;
+	constructor(report) {
+		const counts = /* @__PURE__ */ new Map();
+		for (const issue of report.issues) counts.set(issue.kind, (counts.get(issue.kind) ?? 0) + 1);
+		const summary = [...counts.entries()].map(([kind, count]) => `${kind}=${count}`).join(", ");
+		super(`knowledge citation audit failed: ${summary}`);
+		this.name = "KnowledgeCitationAuditError";
+		this.report = report;
+	}
+};
+/**
+* Parse the persisted citation form.
+*
+* `page-id` is unqualified. `here::page-id`, `shared::page-id`, and
+* `inherited:<runId>::page-id` bind an intentional duplicate to one origin.
+*/
+function parseKnowledgeCitationReference(value) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError("persisted knowledge citation must be a non-empty string");
+	const normalized = value.trim();
+	const separator = normalized.indexOf("::");
+	if (separator < 0) return Object.freeze({ pageId: normalized });
+	const possibleOrigin = normalized.slice(0, separator);
+	const pageId = normalized.slice(separator + 2);
+	if (!isPageOrigin(possibleOrigin)) return Object.freeze({ pageId: normalized });
+	return normalizeReference({
+		pageId,
+		origin: possibleOrigin
+	});
+}
+/** Serialize one reference into the canonical frontmatter representation. */
+function formatKnowledgeCitationReference(reference) {
+	const normalized = normalizeReference(reference);
+	return normalized.origin === void 0 ? normalized.pageId : `${normalized.origin}::${normalized.pageId}`;
+}
+/** Resolve one reference against an already materialized visibility chain. */
+function resolveKnowledgeCitation(visiblePages, reference) {
+	const normalized = normalizeReference(reference);
+	const candidates = visiblePages.filter((entry) => entry.page.id === normalized.pageId && (normalized.origin === void 0 || entry.origin === normalized.origin)).map((entry) => Object.freeze({
+		pageId: entry.page.id,
+		origin: entry.origin,
+		page: entry.page
+	}));
+	const status = candidates.length === 0 ? "missing" : candidates.length === 1 ? "resolved" : "ambiguous";
+	return Object.freeze({
+		reference: normalized,
+		status,
+		candidates: Object.freeze(candidates),
+		...status === "resolved" ? { resolved: candidates[0] } : {}
+	});
+}
+/** Resolve a batch without discarding missing or ambiguous rows. */
+function resolveKnowledgeCitations(visiblePages, references) {
+	return Object.freeze(references.map((reference) => resolveKnowledgeCitation(visiblePages, reference)));
+}
+/**
+* Resolve a batch and fail closed unless every reference names exactly one
+* visible page. Returned candidates preserve the caller's reference order.
+*/
+function assertKnowledgeCitationsResolved(visiblePages, references) {
+	const resolutions = resolveKnowledgeCitations(visiblePages, references);
+	if (resolutions.some((resolution) => resolution.status !== "resolved")) throw new KnowledgeCitationResolutionError(resolutions);
+	return Object.freeze(resolutions.map((resolution) => resolution.resolved));
+}
+/** Audit persisted `cites` relations against one immutable visibility snapshot. */
+function auditKnowledgeCitations(visiblePages, options = {}) {
+	const origins = options.sourceOrigins ? new Set(options.sourceOrigins.map((origin) => validatePageOrigin(origin))) : null;
+	const sources = visiblePages.filter((entry) => origins === null || origins.has(entry.origin));
+	const issues = [];
+	let checkedCitations = 0;
+	for (const source of sources) for (const persistedCitation of new Set(source.page.cites ?? [])) {
+		checkedCitations += 1;
+		const reference = parseKnowledgeCitationReference(persistedCitation);
+		const resolution = resolveKnowledgeCitation(visiblePages, reference);
+		const kind = resolution.candidates.some((candidate) => candidate.page === source.page || candidate.origin === source.origin && candidate.page.path === source.page.path) ? "self" : resolution.status === "missing" ? "missing" : resolution.status === "ambiguous" ? "ambiguous" : null;
+		if (kind === null) continue;
+		issues.push(Object.freeze({
+			kind,
+			sourcePageId: source.page.id,
+			sourcePath: source.page.path,
+			sourceOrigin: source.origin,
+			persistedCitation,
+			reference,
+			candidates: resolution.candidates
+		}));
+	}
+	return Object.freeze({
+		ok: issues.length === 0,
+		checkedPages: sources.length,
+		checkedCitations,
+		issues: Object.freeze(issues)
+	});
+}
+/** Audit and fail closed when any persisted citation is unresolved. */
+function assertKnowledgeCitationAudit(report) {
+	if (!report.ok) throw new KnowledgeCitationAuditError(report);
+}
+/** Resolve one citation using a run-scoped store's declared visibility chain. */
+async function resolveRunScopedCitation(stores, runId, reference) {
+	return resolveKnowledgeCitation(await stores.loadChain(runId), reference);
+}
+/** Resolve citations using one chain read so every row sees the same snapshot. */
+async function resolveRunScopedCitations(stores, runId, references) {
+	return resolveKnowledgeCitations(await stores.loadChain(runId), references);
+}
+/** Resolve a run-scoped batch and fail closed on any missing or ambiguous id. */
+async function assertRunScopedCitationsResolved(stores, runId, references) {
+	return assertKnowledgeCitationsResolved(await stores.loadChain(runId), references);
+}
+/** Audit only pages authored in the current run against the full visible chain. */
+async function auditCurrentRunCitations(stores, runId) {
+	return auditKnowledgeCitations(await stores.loadChain(runId), { sourceOrigins: ["here"] });
+}
+/** Audit current-run citations and fail closed on every unresolved relation. */
+async function assertCurrentRunCitationsResolved(stores, runId) {
+	const report = await auditCurrentRunCitations(stores, runId);
+	assertKnowledgeCitationAudit(report);
+	return report;
+}
+function normalizeReference(reference) {
+	if (!reference || typeof reference !== "object") throw new TypeError("knowledge citation reference must be an object");
+	if (typeof reference.pageId !== "string" || reference.pageId.trim().length === 0) throw new TypeError("knowledge citation pageId must be a non-empty string");
+	if (reference.origin !== void 0) validatePageOrigin(reference.origin);
+	return Object.freeze({
+		pageId: reference.pageId.trim(),
+		...reference.origin === void 0 ? {} : { origin: reference.origin }
+	});
+}
+function validatePageOrigin(value) {
+	if (!isPageOrigin(value)) throw new TypeError(`knowledge citation origin is invalid: ${String(value)}`);
+	return value;
+}
+function isPageOrigin(value) {
+	if (value === "here" || value === "shared") return true;
+	return typeof value === "string" && value.startsWith("inherited:") && value.slice(10).trim().length > 0;
+}
+//#endregion
 //#region src/graph.ts
 function buildKnowledgeGraph(pages) {
-	const byId = /* @__PURE__ */ new Map();
 	const bySlug = /* @__PURE__ */ new Map();
+	const byId = /* @__PURE__ */ new Map();
 	for (const page of pages) {
-		byId.set(page.id, page);
+		byId.set(page.id, [...byId.get(page.id) ?? [], page]);
 		bySlug.set(normalizeLinkTarget(page.id), page);
 		bySlug.set(normalizeLinkTarget(page.title), page);
 		bySlug.set(normalizeLinkTarget(page.path.split("/").pop().replace(/\.md$/, "")), page);
@@ -1788,20 +1943,17 @@ function buildKnowledgeGraph(pages) {
 		outgoing.set(page.id, 0);
 		incoming.set(page.id, 0);
 	}
-	for (const page of pages) for (const raw of page.outLinks) {
-		const target = bySlug.get(normalizeLinkTarget(raw));
-		if (!target || target.id === page.id) continue;
-		const key = `${page.id}->${target.id}`;
-		const edge = edgesByKey.get(key);
-		if (edge) edge.weight += 1;
-		else edgesByKey.set(key, {
-			source: page.id,
-			target: target.id,
-			weight: 1,
-			reasons: ["wikilink"]
-		});
-		outgoing.set(page.id, (outgoing.get(page.id) ?? 0) + 1);
-		incoming.set(target.id, (incoming.get(target.id) ?? 0) + 1);
+	for (const page of pages) {
+		for (const raw of page.outLinks) {
+			const target = bySlug.get(normalizeLinkTarget(raw));
+			if (!target || target.id === page.id) continue;
+			addDirectedEdge(page, target, "wikilink", edgesByKey, incoming, outgoing);
+		}
+		for (const persisted of page.cites ?? []) {
+			const targets = byId.get(citedPageId(persisted)) ?? [];
+			if (targets.length !== 1 || targets[0].id === page.id) continue;
+			addDirectedEdge(page, targets[0], "citation", edgesByKey, incoming, outgoing);
+		}
 	}
 	addSourceOverlapEdges(pages, edgesByKey);
 	return {
@@ -1817,6 +1969,34 @@ function buildKnowledgeGraph(pages) {
 		edges: [...edgesByKey.values()].sort((a, b) => b.weight - a.weight)
 	};
 }
+/**
+* An origin-qualified citation (`here::x`, `inherited:<run>::x`, `shared::x`)
+* must keep its graph edge: qualification is the documented remedy for an
+* ambiguous id, so it cannot cost the citation signal. A value the parser
+* rejects stays a literal page id so index builds never fail on stored data.
+*/
+function citedPageId(persisted) {
+	try {
+		return parseKnowledgeCitationReference(persisted).pageId;
+	} catch {
+		return persisted;
+	}
+}
+function addDirectedEdge(source, target, reason, edges, incoming, outgoing) {
+	const key = `${source.id}->${target.id}`;
+	const edge = edges.get(key);
+	if (edge) {
+		edge.weight += 1;
+		if (!edge.reasons.includes(reason)) edge.reasons.push(reason);
+	} else edges.set(key, {
+		source: source.id,
+		target: target.id,
+		weight: 1,
+		reasons: [reason]
+	});
+	outgoing.set(source.id, (outgoing.get(source.id) ?? 0) + 1);
+	incoming.set(target.id, (incoming.get(target.id) ?? 0) + 1);
+}
 function addSourceOverlapEdges(pages, edges) {
 	for (let i = 0; i < pages.length; i++) for (let j = i + 1; j < pages.length; j++) {
 		const a = pages[i];
@@ -1827,7 +2007,7 @@ function addSourceOverlapEdges(pages, edges) {
 		const edge = edges.get(key);
 		if (edge) {
 			edge.weight += overlap.length * .5;
-			edge.reasons.push("shared-source");
+			if (!edge.reasons.includes("shared-source")) edge.reasons.push("shared-source");
 		} else edges.set(key, {
 			source: a.id,
 			target: b.id,
@@ -2969,6 +3149,6 @@ function explainKnowledgeTarget(index, target) {
 	};
 }
 //#endregion
-export { ResearchSourceVersionSchema as $, MemoryKbStore as A, prepareKnowledgeFileTransaction as At, extractWikilinks as B, withSafeDescendant as Bt, writeSourceRegistry as C, recoverPendingKnowledgeMutation as Ct, KB_EVENTS_PATH as D, assertKnowledgeMutationPath as Dt, KB_CLAIM_LEDGER_DIR as E, applyKnowledgeFileTransaction as Et, isScaffoldPath as F, readRegularFileNoFollow as Ft, KnowledgeGraphEdgeSchema as G, writeJsonDurableWithinRoot as Gt, DeepQuestionSchema as H, writeFileDurable as Ht, layoutFor as I, readRegularFileWithinRoot as It, KnowledgePageInvalidationSchema as J, KnowledgeGraphNodeSchema as K, mediaTypeFor$1 as Kt, loadKnowledgePages as L, removeDurable as Lt, buildKnowledgeGraph as M, isKernelAnchoredPath as Mt, SCAFFOLD_PAGE_BASENAMES as N, isMissingFile as Nt, KB_INDEX_PATH as O, finishKnowledgeFileTransaction as Ot, initKnowledgeBase as P, listRegularFilesWithinRoot as Pt, ResearchClaimRecordSchema as Q, writeJson as R, renameDurable as Rt, sourceRegistryPath as S, inspectPendingKnowledgeMutation as St, FileSystemKbStore as T, withKnowledgeRead as Tt, KnowledgeBaseCandidateSchema as U, writeFileDurableWithinRoot as Ut, normalizeLinkTarget as V, withSafeDirectory as Vt, KnowledgeEventSchema as W, writeJsonDurable as Wt, ResearchClaimEvidenceSchema as X, KnowledgePageSchema as Y, ResearchClaimLedgerSchema as Z, writeKnowledgeIndex as _, normalizeClaimText as _t, applyKnowledgeWriteBlocksFile as a, assertResearchClaimEvidenceIntegrity as at, loadSourceRegistry as b, parseFrontmatter as bt, validateKnowledgeIndex as c, claimEvidenceId as ct, UncheckableClaimError as d, deepQuestionId as dt, SourceAnchorSchema as et, assertGradeableEvidence as f, emptyClaimLedger as ft, buildKnowledgeIndex as g, mergeTrackedClaims as gt, verifyGradeableEvidence as h, mergeClaimLedgers as ht, applyKnowledgeWriteBlocks as i, assertDeepQuestionIntegrity as it, assertClaimLedgerId as j, rollbackKnowledgeFileTransaction as jt, KB_STORE_DIR as k, knowledgeFileTransactionPlanHash as kt, lintKnowledgeIndex as l, claimId as lt, verdictFor as m, materializeRegisteredClaimEvidence as mt, inspectKnowledgeIndex as n, KNOWLEDGE_EVENT_TYPES as nt, isSafeKnowledgePath as o, assertResearchClaimLedgerIntegrity as ot, gradeFor as p, linkClaimContradictions as pt, KnowledgeIndexSchema as q, textSourceAdapter as qt, stringMetadata as r, ClaimLedgerGoalConflictError as rt, parseKnowledgeWriteBlocks as s, assertTrackedClaimIntegrity as st, explainKnowledgeTarget as t, SourceRecordSchema as tt, CHECKABLE_RUNG_THRESHOLD as u, claimSourceHost as ut, addSourcePath as v, researchSourceVersionKey as vt, ClaimLedgerMigrationRequiredError as w, withKnowledgeMutation as wt, snapshotSourceTextInput as x, acquireDurableFileLock as xt, addSourceText as y, formatFrontmatter as yt, WIKILINK_REGEX as z, syncDirectory as zt };
+export { WIKILINK_REGEX as $, syncDirectory as $t, MemoryKbStore as A, mergeTrackedClaims as At, auditKnowledgeCitations as B, applyKnowledgeFileTransaction as Bt, writeSourceRegistry as C, claimId as Ct, KB_EVENTS_PATH as D, linkClaimContradictions as Dt, KB_CLAIM_LEDGER_DIR as E, emptyClaimLedger as Et, assertCurrentRunCitationsResolved as F, acquireDurableFileLock as Ft, resolveRunScopedCitation as G, rollbackKnowledgeFileTransaction as Gt, parseKnowledgeCitationReference as H, finishKnowledgeFileTransaction as Ht, assertKnowledgeCitationAudit as I, inspectPendingKnowledgeMutation as It, initKnowledgeBase as J, listRegularFilesWithinRoot as Jt, resolveRunScopedCitations as K, isKernelAnchoredPath as Kt, assertKnowledgeCitationsResolved as L, recoverPendingKnowledgeMutation as Lt, buildKnowledgeGraph as M, researchSourceVersionKey as Mt, KnowledgeCitationAuditError as N, formatFrontmatter as Nt, KB_INDEX_PATH as O, materializeRegisteredClaimEvidence as Ot, KnowledgeCitationResolutionError as P, parseFrontmatter as Pt, writeJson as Q, renameDurable as Qt, assertRunScopedCitationsResolved as R, withKnowledgeMutation as Rt, sourceRegistryPath as S, claimEvidenceId as St, FileSystemKbStore as T, deepQuestionId as Tt, resolveKnowledgeCitation as U, knowledgeFileTransactionPlanHash as Ut, formatKnowledgeCitationReference as V, assertKnowledgeMutationPath as Vt, resolveKnowledgeCitations as W, prepareKnowledgeFileTransaction as Wt, layoutFor as X, readRegularFileWithinRoot as Xt, isScaffoldPath as Y, readRegularFileNoFollow as Yt, loadKnowledgePages as Z, removeDurable as Zt, writeKnowledgeIndex as _, ClaimLedgerGoalConflictError as _t, applyKnowledgeWriteBlocksFile as a, writeJsonDurableWithinRoot as an, KnowledgeGraphEdgeSchema as at, loadSourceRegistry as b, assertResearchClaimLedgerIntegrity as bt, validateKnowledgeIndex as c, KnowledgePageInvalidationSchema as ct, UncheckableClaimError as d, ResearchClaimLedgerSchema as dt, withSafeDescendant as en, extractWikilinks as et, assertGradeableEvidence as f, ResearchClaimRecordSchema as ft, buildKnowledgeIndex as g, KNOWLEDGE_EVENT_TYPES as gt, verifyGradeableEvidence as h, SourceRecordSchema as ht, applyKnowledgeWriteBlocks as i, writeJsonDurable as in, KnowledgeEventSchema as it, assertClaimLedgerId as j, normalizeClaimText as jt, KB_STORE_DIR as k, mergeClaimLedgers as kt, lintKnowledgeIndex as l, KnowledgePageSchema as lt, verdictFor as m, SourceAnchorSchema as mt, inspectKnowledgeIndex as n, writeFileDurable as nn, DeepQuestionSchema as nt, isSafeKnowledgePath as o, mediaTypeFor$1 as on, KnowledgeGraphNodeSchema as ot, gradeFor as p, ResearchSourceVersionSchema as pt, SCAFFOLD_PAGE_BASENAMES as q, isMissingFile as qt, stringMetadata as r, writeFileDurableWithinRoot as rn, KnowledgeBaseCandidateSchema as rt, parseKnowledgeWriteBlocks as s, textSourceAdapter as sn, KnowledgeIndexSchema as st, explainKnowledgeTarget as t, withSafeDirectory as tn, normalizeLinkTarget as tt, CHECKABLE_RUNG_THRESHOLD as u, ResearchClaimEvidenceSchema as ut, addSourcePath as v, assertDeepQuestionIntegrity as vt, ClaimLedgerMigrationRequiredError as w, claimSourceHost as wt, snapshotSourceTextInput as x, assertTrackedClaimIntegrity as xt, addSourceText as y, assertResearchClaimEvidenceIntegrity as yt, auditCurrentRunCitations as z, withKnowledgeRead as zt };
 
-//# sourceMappingURL=inspect-B7AJ7CZS.js.map
+//# sourceMappingURL=inspect-0tmv3xV8.js.map