@tangle-network/agent-knowledge 15.0.3 → 17.0.0

package/dist/index.js

@@ -1,6 +1,6 @@
-import { $ as formatKnowledgeCitationReference, $t as inspectPendingKnowledgeMutation, A as addSourceText, An as writeJsonDurableWithinRoot, At as ResearchSourceVersionSchema, B as KB_STORE_DIR, Bt as claimId, C as gradeClaims, Cn as renameDurable, Ct as KnowledgePageSchema, D as buildKnowledgeIndex, Dn as writeFileDurable, Dt as ResearchClaimEvidenceSchema, E as verifyGradeableEvidence, En as withSafeDirectory, Et as KnowledgeRelationSchema, F as ClaimLedgerMigrationRequiredError, Ft as assertDeepQuestionIntegrity, G as KnowledgeCitationAuditError, Gt as materializeRegisteredClaimEvidence, H as assertClaimLedgerId, Ht as deepQuestionId, I as FileSystemKbStore, It as assertResearchClaimEvidenceIntegrity, J as assertKnowledgeCitationAudit, Jt as normalizeClaimText, K as KnowledgeCitationResolutionError, Kt as mergeClaimLedgers, L as KB_CLAIM_LEDGER_DIR, Lt as assertResearchClaimLedgerIntegrity, M as snapshotSourceTextInput, Mn as textSourceAdapter, Mt as SourceRecordSchema, N as sourceRegistryPath, Nt as KNOWLEDGE_EVENT_TYPES, O as writeKnowledgeIndex, On as writeFileDurableWithinRoot, Ot as ResearchClaimLedgerSchema, P as writeSourceRegistry, Pt as ClaimLedgerGoalConflictError, Q as auditKnowledgeCitations, Qt as acquireDurableFileLock, R as KB_EVENTS_PATH, Rt as assertTrackedClaimIntegrity, S as claimCheckKey, Sn as removeDurable, St as KnowledgePageInvalidationSchema, T as verdictFor, Tn as withSafeDescendant, Tt as KnowledgeRelationNodeSchema, U as buildKnowledgeGraph, Ut as emptyClaimLedger, V as MemoryKbStore, Vt as claimSourceHost, W as knowledgePageRelations, Wt as linkClaimContradictions, X as assertRunScopedCitationsResolved, Xt as formatFrontmatter, Y as assertKnowledgeCitationsResolved, Yt as researchSourceVersionKey, Z as auditCurrentRunCitations, Zt as parseFrontmatter, _ as lintKnowledgeIndex, _n as isMissingFile, _t as KnowledgeBaseCandidateSchema, a as applyKnowledgeWriteBlocksFile, an as applyKnowledgeFileTransaction, at as SCAFFOLD_PAGE_BASENAMES, b as UncheckableClaimError, bn as readRegularFileWithinRoot, bt as KnowledgeGraphNodeSchema, c as KnowledgeDuplicateIntakeError, cn as finishKnowledgeFileTransaction, ct as isScaffoldPath, d as createFileRunLineageAuthority, dn as rollbackKnowledgeFileTransaction, dt as loadKnowledgePages, en as isKnowledgeMutationHeld, et as parseKnowledgeCitationReference, f as createRunScopedStores, fn as DEFAULT_PAGES_DIRECTORY, ft as writeJson, g as validateKnowledgeIndex, gn as isKernelAnchoredPath, gt as DeepQuestionSchema, h as normalizePageText, hn as canonicalRelativeWithinRoot, ht as normalizeLinkTarget, i as applyKnowledgeWriteBlocks, in as withKnowledgeRead, it as resolveRunScopedCitations, j as loadSourceRegistry, jn as mediaTypeFor, jt as SourceAnchorSchema, k as addSourcePath, kn as writeJsonDurable, kt as ResearchClaimRecordSchema, l as assertKnowledgeWriteIntake, ln as knowledgeFileTransactionPlanHash, lt as knowledgePageFromMarkdown, m as detectNearDuplicatePages, mn as canonicalPathsEqual, mt as extractWikilinks, n as inspectKnowledgeIndex, nn as runInKnowledgeMutationScope, nt as resolveKnowledgeCitations, o as isSafeKnowledgePath, on as assertKnowledgeMutationPath, ot as initKnowledgeBase, p as originatedPages, pn as normalizePagesDirectory, pt as WIKILINK_REGEX, q as assertCurrentRunCitationsResolved, qt as mergeTrackedClaims, r as stringMetadata, rn as withKnowledgeMutation, rt as resolveRunScopedCitation, s as parseKnowledgeWriteBlocks, sn as commitKnowledgeFileMutations, st as isKnowledgePagePath, t as explainKnowledgeTarget, tn as recoverPendingKnowledgeMutation, tt as resolveKnowledgeCitation, u as RUN_LINEAGE_BASENAME, un as prepareKnowledgeFileTransaction, ut as layoutFor, v as CHECKABLE_RUNG_THRESHOLD, vn as listRegularFilesWithinRoot, vt as KnowledgeEventSchema, w as gradeFor, wn as syncDirectory, wt as KnowledgeRelationGraphSchema, x as assertGradeableEvidence, xn as relativeWithinRoot, xt as KnowledgeIndexSchema, y as DEADLINE_EXIT_CODE, yn as readRegularFileNoFollow, yt as KnowledgeGraphEdgeSchema, z as KB_INDEX_PATH, zt as claimEvidenceId } from "./inspect-DMZXOQYl.js";
+import { $ as formatKnowledgeCitationReference, $t as inspectPendingKnowledgeMutation, A as addSourceText, An as writeJsonDurableWithinRoot, At as ResearchSourceVersionSchema, B as KB_STORE_DIR, Bt as claimId, C as gradeClaims, Cn as renameDurable, Ct as KnowledgePageSchema, D as buildKnowledgeIndex, Dn as writeFileDurable, Dt as ResearchClaimEvidenceSchema, E as verifyGradeableEvidence, En as withSafeDirectory, Et as KnowledgeRelationSchema, F as ClaimLedgerMigrationRequiredError, Ft as assertDeepQuestionIntegrity, G as KnowledgeCitationAuditError, Gt as materializeRegisteredClaimEvidence, H as assertClaimLedgerId, Ht as deepQuestionId, I as FileSystemKbStore, It as assertResearchClaimEvidenceIntegrity, J as assertKnowledgeCitationAudit, Jt as normalizeClaimText, K as KnowledgeCitationResolutionError, Kt as mergeClaimLedgers, L as KB_CLAIM_LEDGER_DIR, Lt as assertResearchClaimLedgerIntegrity, M as snapshotSourceTextInput, Mn as textSourceAdapter, Mt as SourceRecordSchema, N as sourceRegistryPath, Nt as KNOWLEDGE_EVENT_TYPES, O as writeKnowledgeIndex, On as writeFileDurableWithinRoot, Ot as ResearchClaimLedgerSchema, P as writeSourceRegistry, Pt as ClaimLedgerGoalConflictError, Q as auditKnowledgeCitations, Qt as acquireDurableFileLock, R as KB_EVENTS_PATH, Rt as assertTrackedClaimIntegrity, S as claimCheckKey, Sn as removeDurable, St as KnowledgePageInvalidationSchema, T as verdictFor, Tn as withSafeDescendant, Tt as KnowledgeRelationNodeSchema, U as buildKnowledgeGraph, Ut as emptyClaimLedger, V as MemoryKbStore, Vt as claimSourceHost, W as knowledgePageRelations, Wt as linkClaimContradictions, X as assertRunScopedCitationsResolved, Xt as formatFrontmatter, Y as assertKnowledgeCitationsResolved, Yt as researchSourceVersionKey, Z as auditCurrentRunCitations, Zt as parseFrontmatter, _ as lintKnowledgeIndex, _n as isMissingFile, _t as KnowledgeBaseCandidateSchema, a as applyKnowledgeWriteBlocksFile, an as applyKnowledgeFileTransaction, at as SCAFFOLD_PAGE_BASENAMES, b as UncheckableClaimError, bn as readRegularFileWithinRoot, bt as KnowledgeGraphNodeSchema, c as KnowledgeDuplicateIntakeError, cn as finishKnowledgeFileTransaction, ct as isScaffoldPath, d as createFileRunLineageAuthority, dn as rollbackKnowledgeFileTransaction, dt as loadKnowledgePages, en as isKnowledgeMutationHeld, et as parseKnowledgeCitationReference, f as createRunScopedStores, fn as DEFAULT_PAGES_DIRECTORY, ft as writeJson, g as validateKnowledgeIndex, gn as isKernelAnchoredPath, gt as DeepQuestionSchema, h as normalizePageText, hn as canonicalRelativeWithinRoot, ht as normalizeLinkTarget, i as applyKnowledgeWriteBlocks, in as withKnowledgeRead, it as resolveRunScopedCitations, j as loadSourceRegistry, jn as mediaTypeFor, jt as SourceAnchorSchema, k as addSourcePath, kn as writeJsonDurable, kt as ResearchClaimRecordSchema, l as assertKnowledgeWriteIntake, ln as knowledgeFileTransactionPlanHash, lt as knowledgePageFromMarkdown, m as detectNearDuplicatePages, mn as canonicalPathsEqual, mt as extractWikilinks, n as inspectKnowledgeIndex, nn as runInKnowledgeMutationScope, nt as resolveKnowledgeCitations, o as isSafeKnowledgePath, on as assertKnowledgeMutationPath, ot as initKnowledgeBase, p as originatedPages, pn as normalizePagesDirectory, pt as WIKILINK_REGEX, q as assertCurrentRunCitationsResolved, qt as mergeTrackedClaims, r as stringMetadata, rn as withKnowledgeMutation, rt as resolveRunScopedCitation, s as parseKnowledgeWriteBlocks, sn as commitKnowledgeFileMutations, st as isKnowledgePagePath, t as explainKnowledgeTarget, tn as recoverPendingKnowledgeMutation, tt as resolveKnowledgeCitation, u as RUN_LINEAGE_BASENAME, un as prepareKnowledgeFileTransaction, ut as layoutFor, v as CHECKABLE_RUNG_THRESHOLD, vn as listRegularFilesWithinRoot, vt as KnowledgeEventSchema, w as gradeFor, wn as syncDirectory, wt as KnowledgeRelationGraphSchema, x as assertGradeableEvidence, xn as relativeWithinRoot, xt as KnowledgeIndexSchema, y as DEADLINE_EXIT_CODE, yn as readRegularFileNoFollow, yt as KnowledgeGraphEdgeSchema, z as KB_INDEX_PATH, zt as claimEvidenceId } from "./inspect-Dn7xCZLn.js";
 import { i as textSourceId, n as slugify, r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
-import { A as runSerializedKnowledgeOptimization, C as deterministicRng, D as toOffPolicyTrajectory, E as retrievalHoldoutConfigHash, M as assertImmutableRef, O as jsonCandidateCodec, S as applySessionStickyRetrievalHoldout, T as resetRetrievalHoldoutRegistry, _ as createAgentMemoryBranch, a as createNeo4jAgentMemoryAdapter, b as renderMemoryContext, c as runAgentMemoryImprovement, d as compareAgentMemoryLearning, f as runAgentMemoryLearningExperiment, g as buildAgentMemorySequencesFromBenchmarkCases, h as buildAgentMemorySequenceScenarios, i as AgentMemoryWriteInputSchema, j as scenarioContentFingerprint, k as jsonObjectCandidateCodec, l as createGraphitiMemoryAdapter, m as agentMemorySequenceJudge, n as AgentMemoryKindSchema, o as createMem0MemoryAdapter, p as runAgentMemoryExperiment, r as AgentMemoryScopeSchema, s as mem0MemoryAdapterIdentity, t as AgentMemoryHitSchema, u as graphitiMemoryAdapterIdentity, v as forkAgentMemoryBranchSnapshot, w as emitRetrievalHoldoutBypass, x as applyRetrievalHoldout, y as defaultGetMemoryContext } from "./memory-BxwOtvd7.js";
+import { A as runSerializedKnowledgeOptimization, C as deterministicRng, D as toOffPolicyTrajectory, E as retrievalHoldoutConfigHash, M as assertImmutableRef, O as jsonCandidateCodec, S as applySessionStickyRetrievalHoldout, T as resetRetrievalHoldoutRegistry, _ as createAgentMemoryBranch, a as createNeo4jAgentMemoryAdapter, b as renderMemoryContext, c as runAgentMemoryImprovement, d as compareAgentMemoryLearning, f as runAgentMemoryLearningExperiment, g as buildAgentMemorySequencesFromBenchmarkCases, h as buildAgentMemorySequenceScenarios, i as AgentMemoryWriteInputSchema, j as scenarioContentFingerprint, k as jsonObjectCandidateCodec, l as createGraphitiMemoryAdapter, m as agentMemorySequenceJudge, n as AgentMemoryKindSchema, o as createMem0MemoryAdapter, p as runAgentMemoryExperiment, r as AgentMemoryScopeSchema, s as mem0MemoryAdapterIdentity, t as AgentMemoryHitSchema, u as graphitiMemoryAdapterIdentity, v as forkAgentMemoryBranchSnapshot, w as emitRetrievalHoldoutBypass, x as applyRetrievalHoldout, y as defaultGetMemoryContext } from "./memory-ce9n5O24.js";
 import { C as sleepForMemoryRecovery, F as buildIndustryRagBenchmarkSmokeCases, G as buildRetrievalEvalDispatch, H as createNoopMemoryBenchmarkAdapter, I as respondToIndustryMemoryBenchmarkSmokeCase, J as retrievalConfigSurface, K as partitionRetrievalScenarios, L as respondToIndustryRagBenchmarkSmokeCase, M as INDUSTRY_RAG_BENCHMARKS, N as buildFirstPartyMemoryLifecycleBenchmarkCases, P as buildIndustryMemoryBenchmarkSmokeCases, R as isKnowledgeMemoryBenchmarkCase, S as runBoundedMemoryLifecycle, U as memoryHitToSourceRecord, V as createInMemoryBenchmarkAdapter, W as memoryWriteResultToSourceRecord, X as scoreRetrievalArtifact, Y as retrievalRecallJudge, Z as mean, a as buildKnowledgeBenchmarkScenarios, b as memoryRecoveryDelayMs, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, f as acquireAgentMemoryRunLease, h as DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, i as runMemoryAdapterBenchmark, j as INDUSTRY_MEMORY_BENCHMARKS, l as scoreKnowledgeBenchmarkArtifact, m as AgentMemoryLifecycleUnsafeError, n as parseKnowledgeBenchmarkJsonl, o as knowledgeBenchmarkJudge, p as AgentMemoryLifecycleTimeoutError, q as retrievalConfigFromSurface, r as parseKnowledgeBenchmarkQrels, s as renderKnowledgeBenchmarkReportMarkdown, t as buildRetrievalBenchmarkCasesFromQrels, u as scoreMemoryBenchmarkArtifact, x as resolveMemoryCleanupTimeoutMs, y as createMemoryExecutionPool } from "./benchmarks-BbPJdmHe.js";
 import { a as buildKnowledgeLexicalIndex, c as tokenizeText, i as searchKnowledgePages, n as reciprocalRankFusion, o as scoreBm25, r as searchKnowledge, s as tokenizeQuery, t as KNOWLEDGE_SEARCH_RETRIEVER_ID } from "./search-Cw6eYfSd.js";
 import { IRS_DIMENSION_HINTS, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from "./sources/index.js";
@@ -2583,7 +2583,7 @@ function rejectUnsafePromotionEvidence(evidence) {
 		if (!comparison.totalCost.accountingComplete) reasons.push(`${label} final comparison has incomplete cost accounting`);
 		const optimizerSource = comparison.best.provenance?.source;
 		if (optimizerSource && optimizerSource.evidence !== "observed") reasons.push(`${label} optimizer package identity was not observed`);
-		if (comparison.best.liftCi.low < 0) reasons.push(`${label} final comparison does not rule out a regression`);
+		if (!comparison.best.decision.promote) reasons.push(comparison.best.decision.low < 0 ? `${label} final comparison does not rule out a regression` : `${label} final comparison does not establish the required improvement`);
 		if (costCeiling !== void 0 && exceedsCostCeiling(comparison.totalCost.totalCostUsd, costCeiling)) reasons.push(`${label} final comparison cost ${comparison.totalCost.totalCostUsd} exceeds ${costCeiling}`);
 	}
 	if (evidence.answerQuality) reasons.push(...ragAnswerEvidenceRejectionReasons(evidence.answerQuality, evidence.answerQualityCostCeiling));
@@ -5979,32 +5979,9 @@ function originOf(originByPage, hit) {
 	return origin;
 }
 //#endregion
-//#region src/knowledge-use-receipts.ts
+//#region src/knowledge-visibility.ts
 const KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION = "2.0.0";
 const KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM = "rfc8785-sha256";
-/**
-* The visibility snapshot a receipt references could not be obtained, so the
-* result-to-visibility join cannot be proven. This is distinct from a snapshot
-* that loads and fails to match.
-*/
-var KnowledgeVisibilityUnavailableError = class extends Error {
-	reason;
-	snapshotDigest;
-	uri;
-	constructor(input) {
-		const where = input.uri === void 0 ? "" : ` at '${input.uri}'`;
-		const detail = {
-			"no-artifact-reference": "the receipt carries no artifact reference",
-			missing: `no artifact is stored${where}`,
-			"load-failed": `the artifact${where} could not be loaded`
-		}[input.reason];
-		super(`knowledge visibility snapshot ${input.snapshotDigest} is unavailable: ${detail}`, input.cause === void 0 ? void 0 : { cause: input.cause });
-		this.name = "KnowledgeVisibilityUnavailableError";
-		this.reason = input.reason;
-		this.snapshotDigest = input.snapshotDigest;
-		if (input.uri !== void 0) this.uri = input.uri;
-	}
-};
 /** Stable content identity for one exact knowledge page. */
 function knowledgePageDigest(page) {
 	validateKnowledgePage(page);
@@ -6110,6 +6087,128 @@ function knowledgeVisibilityArtifactRef(input) {
 		byteLength: input.bytes.byteLength
 	});
 }
+const visibilityIndexes = /* @__PURE__ */ new WeakMap();
+function visibilityIndexOf(snapshot) {
+	if (!snapshot || typeof snapshot !== "object") throw new TypeError("knowledge visibility snapshot is required");
+	const cached = visibilityIndexes.get(snapshot);
+	if (cached !== void 0) return cached;
+	assertSchemaVersion(snapshot.schemaVersion, "knowledge visibility");
+	if (snapshot.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge visibility digestAlgorithm '${snapshot.digestAlgorithm}'`);
+	if (!Array.isArray(snapshot.entries)) throw new TypeError("knowledge visibility snapshot entries must be an array");
+	if (canonicalCandidateDigest(visibilityMaterial(snapshot.entries)) !== digest(snapshot.snapshotDigest, "knowledge visibility snapshotDigest")) throw new Error("knowledge visibility snapshot digest mismatch");
+	const index = indexVisibility(snapshot);
+	visibilityIndexes.set(snapshot, index);
+	return index;
+}
+function indexVisibility(snapshot) {
+	const byIdentity = /* @__PURE__ */ new Map();
+	for (const entry of snapshot.entries) {
+		const identity = visibilityIdentity(entry.origin, entry.path);
+		if (byIdentity.has(identity)) throw new Error(`knowledge visibility repeats path '${entry.path}' at origin '${entry.origin}'`);
+		byIdentity.set(identity, entry);
+	}
+	return {
+		snapshot,
+		byIdentity
+	};
+}
+function visibilityIdentity(origin, path) {
+	return `${origin}\u0000${path}`;
+}
+function assertSchemaVersion(value, label) {
+	if (value === "2.0.0") return;
+	throw new Error(`unsupported ${label} schemaVersion '${String(value)}'${value === "1.0.0" ? "; 1.0.0 records embed the visibility snapshot and have no reader, create a 2.0.0 record from the snapshot" : ""}`);
+}
+function visibilityMaterial(entries) {
+	return {
+		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
+		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
+		entries: entries.map((entry, position) => {
+			if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an object`);
+			if (entry.position !== position) throw new Error(`knowledge visibility position mismatch: expected ${position}, observed ${entry.position}`);
+			if (!Array.isArray(entry.sourceIds)) throw new TypeError(`knowledge visibility[${position}].sourceIds must be an array`);
+			return {
+				position,
+				pageId: nonEmpty$1(entry.pageId, `knowledge visibility[${position}].pageId`),
+				origin: validateOrigin(entry.origin, `knowledge visibility[${position}].origin`),
+				path: nonEmpty$1(entry.path, `knowledge visibility[${position}].path`),
+				pageDigest: digest(entry.pageDigest, `knowledge visibility[${position}].pageDigest`),
+				sourceIds: entry.sourceIds.map((sourceId, sourceIndex) => nonEmpty$1(sourceId, `knowledge visibility[${position}].sourceIds[${sourceIndex}]`)),
+				invalidated: Boolean(entry.invalidated)
+			};
+		})
+	};
+}
+function normalizeVisibilityRef(input) {
+	if (!input || typeof input !== "object") throw new TypeError("knowledge retrieval visibility reference is required");
+	if (!Number.isSafeInteger(input.pageCount) || input.pageCount < 0) throw new TypeError("knowledge retrieval visibility pageCount must be a non-negative integer");
+	return Object.freeze({
+		snapshotDigest: digest(input.snapshotDigest, "knowledge retrieval visibility snapshotDigest"),
+		pageCount: input.pageCount,
+		...input.artifact === void 0 ? {} : { artifact: normalizeVisibilityArtifact(input.artifact, "knowledge retrieval visibility artifact") }
+	});
+}
+function normalizeVisibilityArtifact(input, label) {
+	if (!input || typeof input !== "object") throw new TypeError(`${label} must be an object`);
+	if (!Number.isSafeInteger(input.byteLength) || input.byteLength < 1) throw new TypeError(`${label} byteLength must be a positive integer`);
+	return Object.freeze({
+		uri: nonEmpty$1(input.uri, `${label} uri`),
+		digest: digest(input.digest, `${label} digest`),
+		byteLength: input.byteLength
+	});
+}
+function validateKnowledgePage(page) {
+	if (!page || typeof page !== "object") throw new TypeError("knowledge page must be an object");
+	nonEmpty$1(page.id, "knowledge page id");
+	nonEmpty$1(page.path, "knowledge page path");
+	nonEmpty$1(page.title, "knowledge page title");
+	if (typeof page.text !== "string") throw new TypeError("knowledge page text must be a string");
+	if (!page.frontmatter || typeof page.frontmatter !== "object" || Array.isArray(page.frontmatter)) throw new TypeError("knowledge page frontmatter must be an object");
+	for (const [name, values] of [
+		["sourceIds", page.sourceIds],
+		["tags", page.tags],
+		["outLinks", page.outLinks]
+	]) if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) throw new TypeError(`knowledge page ${name} must be a string array`);
+}
+function validateOrigin(value, label) {
+	if (value === "here" || value === "shared") return value;
+	if (typeof value === "string" && value.startsWith("inherited:") && value.slice(10).trim().length > 0) return value;
+	throw new TypeError(`${label} is invalid: ${String(value)}`);
+}
+function digest(value, label) {
+	const parsed = sha256DigestSchema.safeParse(value);
+	if (!parsed.success) throw new TypeError(`${label} must be a lowercase sha256 digest`);
+	return parsed.data;
+}
+function nonEmpty$1(value, label) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${label} must be a non-empty string`);
+	return value.trim();
+}
+//#endregion
+//#region src/knowledge-use-receipts.ts
+/**
+* The visibility snapshot a receipt references could not be obtained, so the
+* result-to-visibility join cannot be proven. This is distinct from a snapshot
+* that loads and fails to match.
+*/
+var KnowledgeVisibilityUnavailableError = class extends Error {
+	reason;
+	snapshotDigest;
+	uri;
+	constructor(input) {
+		const where = input.uri === void 0 ? "" : ` at '${input.uri}'`;
+		const detail = {
+			"no-artifact-reference": "the receipt carries no artifact reference",
+			missing: `no artifact is stored${where}`,
+			"load-failed": `the artifact${where} could not be loaded`
+		}[input.reason];
+		super(`knowledge visibility snapshot ${input.snapshotDigest} is unavailable: ${detail}`, input.cause === void 0 ? void 0 : { cause: input.cause });
+		this.name = "KnowledgeVisibilityUnavailableError";
+		this.reason = input.reason;
+		this.snapshotDigest = input.snapshotDigest;
+		if (input.uri !== void 0) this.uri = input.uri;
+	}
+};
 /**
 * Create a retrieval receipt over a precomputed snapshot. Every result must
 * occur in the snapshot with the same page id and bytes; the receipt stores the
@@ -6314,34 +6413,6 @@ function verifyKnowledgeRetrievalDisposition(disposition, retrieval) {
 	})) !== disposition.receiptDigest) throw new Error("knowledge retrieval disposition digest mismatch");
 	return disposition;
 }
-const visibilityIndexes = /* @__PURE__ */ new WeakMap();
-function visibilityIndexOf(snapshot) {
-	if (!snapshot || typeof snapshot !== "object") throw new TypeError("knowledge visibility snapshot is required");
-	const cached = visibilityIndexes.get(snapshot);
-	if (cached !== void 0) return cached;
-	assertSchemaVersion(snapshot.schemaVersion, "knowledge visibility");
-	if (snapshot.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported knowledge visibility digestAlgorithm '${snapshot.digestAlgorithm}'`);
-	if (!Array.isArray(snapshot.entries)) throw new TypeError("knowledge visibility snapshot entries must be an array");
-	if (canonicalCandidateDigest(visibilityMaterial(snapshot.entries)) !== digest(snapshot.snapshotDigest, "knowledge visibility snapshotDigest")) throw new Error("knowledge visibility snapshot digest mismatch");
-	const index = indexVisibility(snapshot);
-	visibilityIndexes.set(snapshot, index);
-	return index;
-}
-function indexVisibility(snapshot) {
-	const byIdentity = /* @__PURE__ */ new Map();
-	for (const entry of snapshot.entries) {
-		const identity = visibilityIdentity(entry.origin, entry.path);
-		if (byIdentity.has(identity)) throw new Error(`knowledge visibility repeats path '${entry.path}' at origin '${entry.origin}'`);
-		byIdentity.set(identity, entry);
-	}
-	return {
-		snapshot,
-		byIdentity
-	};
-}
-function visibilityIdentity(origin, path) {
-	return `${origin}\u0000${path}`;
-}
 function assertReceiptJoinsVisibility(receipt, index) {
 	if (index.snapshot.snapshotDigest !== receipt.visibility.snapshotDigest || index.snapshot.entries.length !== receipt.visibility.pageCount) throw new Error("knowledge retrieval receipt does not match the supplied visibility snapshot");
 	for (const result of receipt.results) {
@@ -6349,30 +6420,6 @@ function assertReceiptJoinsVisibility(receipt, index) {
 		if (!entry || entry.pageId !== result.pageId || entry.pageDigest !== result.pageDigest) throw new Error(`knowledge retrieval result rank ${result.rank} is not in the visibility snapshot`);
 	}
 }
-function assertSchemaVersion(value, label) {
-	if (value === "2.0.0") return;
-	throw new Error(`unsupported ${label} schemaVersion '${String(value)}'${value === "1.0.0" ? "; 1.0.0 records embed the visibility snapshot and have no reader, create a 2.0.0 record from the snapshot" : ""}`);
-}
-function visibilityMaterial(entries) {
-	return {
-		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
-		digestAlgorithm: KNOWLEDGE_RECEIPT_DIGEST_ALGORITHM,
-		entries: entries.map((entry, position) => {
-			if (!entry || typeof entry !== "object") throw new TypeError(`knowledge visibility[${position}] must be an object`);
-			if (entry.position !== position) throw new Error(`knowledge visibility position mismatch: expected ${position}, observed ${entry.position}`);
-			if (!Array.isArray(entry.sourceIds)) throw new TypeError(`knowledge visibility[${position}].sourceIds must be an array`);
-			return {
-				position,
-				pageId: nonEmpty$1(entry.pageId, `knowledge visibility[${position}].pageId`),
-				origin: validateOrigin(entry.origin, `knowledge visibility[${position}].origin`),
-				path: nonEmpty$1(entry.path, `knowledge visibility[${position}].path`),
-				pageDigest: digest(entry.pageDigest, `knowledge visibility[${position}].pageDigest`),
-				sourceIds: entry.sourceIds.map((sourceId, sourceIndex) => nonEmpty$1(sourceId, `knowledge visibility[${position}].sourceIds[${sourceIndex}]`)),
-				invalidated: Boolean(entry.invalidated)
-			};
-		})
-	};
-}
 function retrievalMaterial(input) {
 	return {
 		schemaVersion: KNOWLEDGE_USE_RECEIPT_SCHEMA_VERSION,
@@ -6503,24 +6550,6 @@ function assertResultScores(result, position) {
 	finite(result.normalizedScore, `knowledge retrieval results[${position}].normalizedScore`);
 	if (result.normalizedScore < 0 || result.normalizedScore > 1) throw new TypeError(`knowledge retrieval results[${position}].normalizedScore must be in [0,1]`);
 }
-function normalizeVisibilityRef(input) {
-	if (!input || typeof input !== "object") throw new TypeError("knowledge retrieval visibility reference is required");
-	if (!Number.isSafeInteger(input.pageCount) || input.pageCount < 0) throw new TypeError("knowledge retrieval visibility pageCount must be a non-negative integer");
-	return Object.freeze({
-		snapshotDigest: digest(input.snapshotDigest, "knowledge retrieval visibility snapshotDigest"),
-		pageCount: input.pageCount,
-		...input.artifact === void 0 ? {} : { artifact: normalizeVisibilityArtifact(input.artifact, "knowledge retrieval visibility artifact") }
-	});
-}
-function normalizeVisibilityArtifact(input, label) {
-	if (!input || typeof input !== "object") throw new TypeError(`${label} must be an object`);
-	if (!Number.isSafeInteger(input.byteLength) || input.byteLength < 1) throw new TypeError(`${label} byteLength must be a positive integer`);
-	return Object.freeze({
-		uri: nonEmpty$1(input.uri, `${label} uri`),
-		digest: digest(input.digest, `${label} digest`),
-		byteLength: input.byteLength
-	});
-}
 function normalizeRetriever(input) {
 	if (!input || typeof input !== "object") throw new TypeError("knowledge retriever identity is required");
 	return Object.freeze({
@@ -6584,36 +6613,9 @@ function validateUseRelation(value) {
 	].includes(value)) throw new TypeError(`knowledge use relation is invalid: ${String(value)}`);
 	return value;
 }
-function validateKnowledgePage(page) {
-	if (!page || typeof page !== "object") throw new TypeError("knowledge page must be an object");
-	nonEmpty$1(page.id, "knowledge page id");
-	nonEmpty$1(page.path, "knowledge page path");
-	nonEmpty$1(page.title, "knowledge page title");
-	if (typeof page.text !== "string") throw new TypeError("knowledge page text must be a string");
-	if (!page.frontmatter || typeof page.frontmatter !== "object" || Array.isArray(page.frontmatter)) throw new TypeError("knowledge page frontmatter must be an object");
-	for (const [name, values] of [
-		["sourceIds", page.sourceIds],
-		["tags", page.tags],
-		["outLinks", page.outLinks]
-	]) if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) throw new TypeError(`knowledge page ${name} must be a string array`);
-}
-function validateOrigin(value, label) {
-	if (value === "here" || value === "shared") return value;
-	if (typeof value === "string" && value.startsWith("inherited:") && value.slice(10).trim().length > 0) return value;
-	throw new TypeError(`${label} is invalid: ${String(value)}`);
-}
-function digest(value, label) {
-	const parsed = sha256DigestSchema.safeParse(value);
-	if (!parsed.success) throw new TypeError(`${label} must be a lowercase sha256 digest`);
-	return parsed.data;
-}
 function optionalDigest(value, label) {
 	return value === void 0 ? void 0 : digest(value, label);
 }
-function nonEmpty$1(value, label) {
-	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${label} must be a non-empty string`);
-	return value.trim();
-}
 function optionalText(value, label) {
 	return value === void 0 ? void 0 : nonEmpty$1(value, label);
 }
@@ -6708,6 +6710,7 @@ function createKnowledgeTools(options) {
 			const intake = options.intake;
 			return applyKnowledgeWriteBlocks(stores.storePath(runId), input.proposal, {
 				...pages,
+				retainHistory: options.retainHistory,
 				...intake === void 0 ? {} : { intake: {
 					...intake,
 					inheritedPages: await inheritedOf(stores, runId)
@@ -6803,16 +6806,16 @@ async function promoteRunScopedPages(stores, runId, options) {
 	const reason = nonEmpty(options.reason, "promotion reason");
 	if (!Array.isArray(options.pageIds) || options.pageIds.length === 0) throw new TypeError("promotion pageIds must name at least one page");
 	const travellers = collectTravellers(await stores.loadChain(runId), options.pageIds);
+	const mutations = await Promise.all(travellers.map(async (traveller) => ({
+		path: traveller.entry.page.path,
+		content: await readPageBytes(stores, runId, traveller.entry, pagesDirectory)
+	})));
 	await initKnowledgeBase(sharedRoot);
 	return withKnowledgeMutation(sharedRoot, async (lock) => {
 		const existing = await loadKnowledgePages(sharedRoot, { pagesDirectory });
 		assertNoIdentityConflict(travellers, existing);
 		const promotedPaths = new Set(travellers.map((traveller) => traveller.entry.page.path));
 		assertKnowledgeCitationsResolved(originatedPages([...existing.filter((page) => !promotedPaths.has(page.path)), ...travellers.map((traveller) => traveller.entry.page)], "shared"), travellers.flatMap((traveller) => (traveller.entry.page.cites ?? []).map((persisted) => parseKnowledgeCitationReference(persisted))));
-		const mutations = await Promise.all(travellers.map(async (traveller) => ({
-			path: traveller.entry.page.path,
-			content: await readPageBytes(stores, runId, traveller.entry)
-		})));
 		await commitKnowledgeFileMutations({
 			root: sharedRoot,
 			transactionRoot: lock.transactionRoot,
@@ -6900,9 +6903,11 @@ function assertNoIdentityConflict(travellers, existing) {
 * The page as its own store holds it. A promoted page must be the same bytes
 * in both scopes, so the record's digest describes what a reader will load.
 */
-async function readPageBytes(stores, runId, entry) {
+async function readPageBytes(stores, runId, entry, pagesDirectory) {
 	const sourceRunId = sourceRunOf(entry.origin, runId);
-	return (await readRegularFileWithinRoot(stores.storePath(sourceRunId), entry.page.path)).bytes.toString("utf8");
+	const content = (await readRegularFileWithinRoot(stores.storePath(sourceRunId), entry.page.path)).bytes.toString("utf8");
+	if (knowledgePageDigest(knowledgePageFromMarkdown(entry.page.path, content, pagesDirectory)) !== knowledgePageDigest(entry.page)) throw new KnowledgePromotionError("path-conflict", `source page "${entry.page.path}" in run "${sourceRunId}" changed after the promotion snapshot`);
+	return content;
 }
 function sourceRunOf(origin, runId) {
 	if (origin === "here") return runId;