@tangle-network/agent-knowledge 10.7.0 → 10.8.0

package/dist/{inspect-DALsvG10.js → inspect-yYqLQuM4.js}

@@ -2,7 +2,7 @@ import { i as textSourceId, n as slugify, r as stableId, t as sha256 } from "./i
 import { r as searchKnowledge } from "./search-Cw6eYfSd.js";
 import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { contentHash } from "@tangle-network/agent-eval";
 import { z } from "zod";
 import { constants } from "node:fs";
@@ -244,6 +244,72 @@ async function openDirectory(path) {
 function isKernelAnchoredPath(path) {
 	return process.platform === "linux" && /^\/proc\/self\/fd\/\d+(?:\/|$)/.test(path);
 }
+/**
+* The path from `root` down to `candidate`, or undefined when `candidate` is not
+* strictly inside `root`.
+*
+* The comparison is lexical, so both arguments must already share one
+* canonicalization basis. Use `canonicalRelativeWithinRoot` when either side can
+* carry a different basis.
+*
+* An empty result means the two paths are equal. A root is not inside itself,
+* and a caller that treats it as a descendant would hand its own root to
+* machinery that may remove the directory it is given.
+*/
+function relativeWithinRoot(root, candidate) {
+	const value = relative(resolve(root), resolve(candidate)).replace(/\\/g, "/");
+	if (value === "" || value === ".." || value.startsWith("../") || isAbsolute(value)) return;
+	return value;
+}
+/**
+* The path from `root` down to `candidate`, with both sides canonicalized before
+* they are compared.
+*
+* `resolve` is lexical: it cannot read a symbolic link, so a path that has been
+* through `realpath` and one that has not describe the same directory with
+* different strings, and comparing the two rejects a directory that genuinely
+* sits inside the root. `openSafeDirectoryTree` canonicalizes the root it opens,
+* so any path that reaches a caller through `withSafeDirectory` carries the
+* canonical form while a path the caller built itself does not.
+*
+* Canonicalizing both sides also tightens the boundary: a candidate that leaves
+* the root through a symbolic link is rejected here, where a lexical comparison
+* admits it.
+*
+* Neither path has to exist. The deepest existing ancestor of each is
+* canonicalized and the remaining segments are appended, so a directory that is
+* about to be created is measured against the same root as one that already is.
+*/
+async function canonicalRelativeWithinRoot(root, candidate) {
+	return relativeWithinRoot(isKernelAnchoredPath(root) ? root : await canonicalizeThroughMissing(root), isKernelAnchoredPath(candidate) ? candidate : await canonicalizeThroughMissing(candidate));
+}
+/**
+* Whether two paths name the same location, with both sides canonicalized first.
+*
+* A path stored by one caller and a path supplied by another reach this
+* comparison through different routes, so the same location can arrive under two
+* spellings. Comparing the resolved strings reports a mismatch that does not
+* exist.
+*/
+async function canonicalPathsEqual(left, right) {
+	const [canonicalLeft, canonicalRight] = await Promise.all([isKernelAnchoredPath(left) ? left : canonicalizeThroughMissing(left), isKernelAnchoredPath(right) ? right : canonicalizeThroughMissing(right)]);
+	return canonicalLeft === canonicalRight;
+}
+/** The canonical form of a path whose trailing segments may not exist yet. */
+async function canonicalizeThroughMissing(path) {
+	const missing = [];
+	let current = resolve(path);
+	for (;;) try {
+		const existing = await realpath(current);
+		return missing.length === 0 ? existing : join(existing, ...missing.reverse());
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+		const parent = dirname(current);
+		if (parent === current) throw error;
+		missing.push(basename(current));
+		current = parent;
+	}
+}
 function anchoredDirectoryPath(handle, fallback) {
 	return process.platform === "linux" ? `/proc/self/fd/${handle.fd}` : fallback;
 }
@@ -340,20 +406,21 @@ const transactionDirectionSchema = z.object({
 	transactionId: z.string().uuid(),
 	direction: z.literal("rollback")
 }).strict();
-function knowledgeFileTransactionPlanHash(entries) {
-	const normalized = entries.map((entry) => normalizePlanEntry(entry)).sort((left, right) => left.path.localeCompare(right.path));
+function knowledgeFileTransactionPlanHash(entries, pagesDirectory) {
+	const normalized = entries.map((entry) => normalizePlanEntry(entry, pagesDirectory)).sort((left, right) => left.path.localeCompare(right.path));
 	if (new Set(normalized.map((entry) => entry.path)).size !== normalized.length) throw new Error("knowledge transaction plan repeats a path");
 	return contentHash(normalized);
 }
 async function prepareKnowledgeFileTransaction(input) {
 	if (input.mutations.length === 0) throw new Error("knowledge file transaction has no mutations");
 	const pagesDirectory = input.pagesDirectory === void 0 ? void 0 : normalizePagesDirectory(input.pagesDirectory);
+	const boundPagesDirectory = normalizePagesDirectory(input.pagesDirectory);
 	return withTransactionRoot(input.root, input.transactionRoot, true, async (transactionRoot) => {
 		const activeTransactions = await activeTransactionDirectoryNames(transactionRoot);
 		if (activeTransactions.length > 0) throw new Error(`knowledge file transaction is already active: ${activeTransactions.join(", ")}`);
 		const paths = /* @__PURE__ */ new Set();
 		const changed = (await Promise.all(input.mutations.map(async (mutation, index) => {
-			const path = assertKnowledgeMutationPath(mutation.path, pagesDirectory);
+			const path = assertKnowledgeMutationPath(mutation.path, boundPagesDirectory);
 			if (paths.has(path)) throw new Error(`knowledge file transaction repeats path: ${path}`);
 			if (mutation.content === null && mutation.mode !== void 0) throw new Error(`deleted knowledge file cannot declare a mode: ${path}`);
 			paths.add(path);
@@ -637,16 +704,16 @@ async function withTransactionRoot(root, transactionRoot, create, use) {
 		if (!match?.[1]) throw new Error("knowledge transaction directory has an invalid anchor");
 		return withSafeDirectory(match[1], match[2] ?? "", create, use);
 	}
-	const resolvedRoot = resolve(root);
-	const resolvedTransactionRoot = resolve(transactionRoot);
-	if (!resolvedTransactionRoot.startsWith(`${resolvedRoot}${sep}`)) throw new Error("knowledge transaction directory escaped its root");
-	return withSafeDirectory(root, relative(resolvedRoot, resolvedTransactionRoot).replace(/\\/g, "/"), create, use);
+	const within = await canonicalRelativeWithinRoot(root, transactionRoot);
+	if (within === void 0) throw new Error("knowledge transaction directory escaped its root");
+	return withSafeDirectory(root, within, create, use);
 }
 function assertTransactionEntries(transaction) {
 	const indexes = /* @__PURE__ */ new Set();
 	const paths = /* @__PURE__ */ new Set();
+	const boundPagesDirectory = normalizePagesDirectory(transaction.pagesDirectory);
 	for (const entry of transaction.entries) {
-		const normalized = assertKnowledgeMutationPath(entry.path, transaction.pagesDirectory);
+		const normalized = assertKnowledgeMutationPath(entry.path, boundPagesDirectory);
 		if (entry.path !== normalized || indexes.has(entry.index) || paths.has(entry.path)) throw new Error("knowledge file transaction has duplicate or unsafe entries");
 		assertHashModePair(entry.path, "before", entry.beforeHash, entry.beforeMode);
 		assertHashModePair(entry.path, "after", entry.afterHash, entry.afterMode);
@@ -654,8 +721,8 @@ function assertTransactionEntries(transaction) {
 		paths.add(entry.path);
 	}
 }
-function normalizePlanEntry(entry) {
-	const path = assertKnowledgeMutationPath(entry.path);
+function normalizePlanEntry(entry, pagesDirectory) {
+	const path = assertKnowledgeMutationPath(entry.path, pagesDirectory);
 	assertHashModePair(path, "before", entry.beforeHash, entry.beforeMode);
 	assertHashModePair(path, "after", entry.afterHash, entry.afterMode);
 	return {
@@ -674,6 +741,12 @@ function assertHashModePair(path, side, hash, mode) {
 * Root-relative prefixes a knowledge transaction may write under. The pages
 * directory is the only caller-selected member; the source registry file and
 * the `raw/` evidence tree are package-owned and always present.
+*
+* The pages directory is stated rather than defaulted. A store laid out under
+* `kb/pages/` is checked against a different allowlist from one laid out under
+* `knowledge/`, so a caller that omits it is not asking for a safe default: it
+* is asking for someone else's allowlist. Pass `DEFAULT_PAGES_DIRECTORY` where
+* the default is the deliberate answer.
 */
 function knowledgeMutationPathPrefixes(pagesDirectory) {
 	return [`${normalizePagesDirectory(pagesDirectory)}/`, "raw/"];
@@ -3721,6 +3794,6 @@ function explainKnowledgeTarget(index, target) {
 	};
 }
 //#endregion
-export { resolveKnowledgeCitations as $, withKnowledgeRead as $t, sourceRegistryPath as A, KNOWLEDGE_EVENT_TYPES as At, buildKnowledgeGraph as B, emptyClaimLedger as Bt, verifyGradeableEvidence as C, mediaTypeFor$1 as Cn, KnowledgeRelationSchema as Ct, addSourceText as D, ResearchSourceVersionSchema as Dt, addSourcePath as E, ResearchClaimRecordSchema as Et, KB_EVENTS_PATH as F, assertTrackedClaimIntegrity as Ft, assertKnowledgeCitationAudit as G, normalizeClaimText as Gt, KnowledgeCitationAuditError as H, materializeRegisteredClaimEvidence as Ht, KB_INDEX_PATH as I, claimEvidenceId as It, auditCurrentRunCitations as J, parseFrontmatter as Jt, assertKnowledgeCitationsResolved as K, researchSourceVersionKey as Kt, KB_STORE_DIR as L, claimId as Lt, ClaimLedgerMigrationRequiredError as M, assertDeepQuestionIntegrity as Mt, FileSystemKbStore as N, assertResearchClaimEvidenceIntegrity as Nt, loadSourceRegistry as O, SourceAnchorSchema as Ot, KB_CLAIM_LEDGER_DIR as P, assertResearchClaimLedgerIntegrity as Pt, resolveKnowledgeCitation as Q, withKnowledgeMutation as Qt, MemoryKbStore as R, claimSourceHost as Rt, verdictFor as S, writeJsonDurableWithinRoot as Sn, KnowledgeRelationNodeSchema as St, writeKnowledgeIndex as T, ResearchClaimLedgerSchema as Tt, KnowledgeCitationResolutionError as U, mergeClaimLedgers as Ut, knowledgePageRelations as V, linkClaimContradictions as Vt, assertCurrentRunCitationsResolved as W, mergeTrackedClaims as Wt, formatKnowledgeCitationReference as X, inspectPendingKnowledgeMutation as Xt, auditKnowledgeCitations as Y, acquireDurableFileLock as Yt, parseKnowledgeCitationReference as Z, recoverPendingKnowledgeMutation as Zt, lintKnowledgeIndex as _, withSafeDescendant as _n, KnowledgeGraphNodeSchema as _t, applyKnowledgeWriteBlocksFile as a, prepareKnowledgeFileTransaction as an, isScaffoldPath as at, assertGradeableEvidence as b, writeFileDurableWithinRoot as bn, KnowledgePageSchema as bt, KnowledgeDuplicateIntakeError as c, normalizePagesDirectory as cn, loadKnowledgePages as ct, createFileRunLineageAuthority as d, listRegularFilesWithinRoot as dn, extractWikilinks as dt, applyKnowledgeFileTransaction as en, resolveRunScopedCitation as et, createRunScopedStores as f, readRegularFileNoFollow as fn, normalizeLinkTarget as ft, validateKnowledgeIndex as g, syncDirectory as gn, KnowledgeGraphEdgeSchema as gt, normalizePageText as h, renameDurable as hn, KnowledgeEventSchema as ht, applyKnowledgeWriteBlocks as i, knowledgeFileTransactionPlanHash as in, isKnowledgePagePath as it, writeSourceRegistry as j, ClaimLedgerGoalConflictError as jt, snapshotSourceTextInput as k, SourceRecordSchema as kt, assertKnowledgeWriteIntake as l, isKernelAnchoredPath as ln, writeJson as lt, detectNearDuplicatePages as m, removeDurable as mn, KnowledgeBaseCandidateSchema as mt, inspectKnowledgeIndex as n, commitKnowledgeFileMutations as nn, SCAFFOLD_PAGE_BASENAMES as nt, isSafeKnowledgePath as o, rollbackKnowledgeFileTransaction as on, knowledgePageFromMarkdown as ot, originatedPages as p, readRegularFileWithinRoot as pn, DeepQuestionSchema as pt, assertRunScopedCitationsResolved as q, formatFrontmatter as qt, stringMetadata as r, finishKnowledgeFileTransaction as rn, initKnowledgeBase as rt, parseKnowledgeWriteBlocks as s, DEFAULT_PAGES_DIRECTORY as sn, layoutFor as st, explainKnowledgeTarget as t, assertKnowledgeMutationPath as tn, resolveRunScopedCitations as tt, RUN_LINEAGE_BASENAME as u, isMissingFile as un, WIKILINK_REGEX as ut, CHECKABLE_RUNG_THRESHOLD as v, withSafeDirectory as vn, KnowledgeIndexSchema as vt, buildKnowledgeIndex as w, textSourceAdapter as wn, ResearchClaimEvidenceSchema as wt, gradeFor as x, writeJsonDurable as xn, KnowledgeRelationGraphSchema as xt, UncheckableClaimError as y, writeFileDurable as yn, KnowledgePageInvalidationSchema as yt, assertClaimLedgerId as z, deepQuestionId as zt };
+export { resolveKnowledgeCitations as $, withKnowledgeRead as $t, sourceRegistryPath as A, KNOWLEDGE_EVENT_TYPES as At, buildKnowledgeGraph as B, emptyClaimLedger as Bt, verifyGradeableEvidence as C, writeFileDurableWithinRoot as Cn, KnowledgeRelationSchema as Ct, addSourceText as D, textSourceAdapter as Dn, ResearchSourceVersionSchema as Dt, addSourcePath as E, mediaTypeFor$1 as En, ResearchClaimRecordSchema as Et, KB_EVENTS_PATH as F, assertTrackedClaimIntegrity as Ft, assertKnowledgeCitationAudit as G, normalizeClaimText as Gt, KnowledgeCitationAuditError as H, materializeRegisteredClaimEvidence as Ht, KB_INDEX_PATH as I, claimEvidenceId as It, auditCurrentRunCitations as J, parseFrontmatter as Jt, assertKnowledgeCitationsResolved as K, researchSourceVersionKey as Kt, KB_STORE_DIR as L, claimId as Lt, ClaimLedgerMigrationRequiredError as M, assertDeepQuestionIntegrity as Mt, FileSystemKbStore as N, assertResearchClaimEvidenceIntegrity as Nt, loadSourceRegistry as O, SourceAnchorSchema as Ot, KB_CLAIM_LEDGER_DIR as P, assertResearchClaimLedgerIntegrity as Pt, resolveKnowledgeCitation as Q, withKnowledgeMutation as Qt, MemoryKbStore as R, claimSourceHost as Rt, verdictFor as S, writeFileDurable as Sn, KnowledgeRelationNodeSchema as St, writeKnowledgeIndex as T, writeJsonDurableWithinRoot as Tn, ResearchClaimLedgerSchema as Tt, KnowledgeCitationResolutionError as U, mergeClaimLedgers as Ut, knowledgePageRelations as V, linkClaimContradictions as Vt, assertCurrentRunCitationsResolved as W, mergeTrackedClaims as Wt, formatKnowledgeCitationReference as X, inspectPendingKnowledgeMutation as Xt, auditKnowledgeCitations as Y, acquireDurableFileLock as Yt, parseKnowledgeCitationReference as Z, recoverPendingKnowledgeMutation as Zt, lintKnowledgeIndex as _, removeDurable as _n, KnowledgeGraphNodeSchema as _t, applyKnowledgeWriteBlocksFile as a, prepareKnowledgeFileTransaction as an, isScaffoldPath as at, assertGradeableEvidence as b, withSafeDescendant as bn, KnowledgePageSchema as bt, KnowledgeDuplicateIntakeError as c, normalizePagesDirectory as cn, loadKnowledgePages as ct, createFileRunLineageAuthority as d, isKernelAnchoredPath as dn, extractWikilinks as dt, applyKnowledgeFileTransaction as en, resolveRunScopedCitation as et, createRunScopedStores as f, isMissingFile as fn, normalizeLinkTarget as ft, validateKnowledgeIndex as g, relativeWithinRoot as gn, KnowledgeGraphEdgeSchema as gt, normalizePageText as h, readRegularFileWithinRoot as hn, KnowledgeEventSchema as ht, applyKnowledgeWriteBlocks as i, knowledgeFileTransactionPlanHash as in, isKnowledgePagePath as it, writeSourceRegistry as j, ClaimLedgerGoalConflictError as jt, snapshotSourceTextInput as k, SourceRecordSchema as kt, assertKnowledgeWriteIntake as l, canonicalPathsEqual as ln, writeJson as lt, detectNearDuplicatePages as m, readRegularFileNoFollow as mn, KnowledgeBaseCandidateSchema as mt, inspectKnowledgeIndex as n, commitKnowledgeFileMutations as nn, SCAFFOLD_PAGE_BASENAMES as nt, isSafeKnowledgePath as o, rollbackKnowledgeFileTransaction as on, knowledgePageFromMarkdown as ot, originatedPages as p, listRegularFilesWithinRoot as pn, DeepQuestionSchema as pt, assertRunScopedCitationsResolved as q, formatFrontmatter as qt, stringMetadata as r, finishKnowledgeFileTransaction as rn, initKnowledgeBase as rt, parseKnowledgeWriteBlocks as s, DEFAULT_PAGES_DIRECTORY as sn, layoutFor as st, explainKnowledgeTarget as t, assertKnowledgeMutationPath as tn, resolveRunScopedCitations as tt, RUN_LINEAGE_BASENAME as u, canonicalRelativeWithinRoot as un, WIKILINK_REGEX as ut, CHECKABLE_RUNG_THRESHOLD as v, renameDurable as vn, KnowledgeIndexSchema as vt, buildKnowledgeIndex as w, writeJsonDurable as wn, ResearchClaimEvidenceSchema as wt, gradeFor as x, withSafeDirectory as xn, KnowledgeRelationGraphSchema as xt, UncheckableClaimError as y, syncDirectory as yn, KnowledgePageInvalidationSchema as yt, assertClaimLedgerId as z, deepQuestionId as zt };
 
-//# sourceMappingURL=inspect-DALsvG10.js.map
+//# sourceMappingURL=inspect-yYqLQuM4.js.map