@tangle-network/agent-knowledge 8.0.6 → 8.0.7

package/dist/{inspect-CJQGYuKa.js → inspect-B7AJ7CZS.js}

@@ -1,5 +1,5 @@
 import { i as textSourceId, n as slugify, r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
-import { n as searchKnowledge } from "./search-CP0QtBJZ.js";
+import { n as searchKnowledge } from "./search-CtVJ0PKX.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";
@@ -982,232 +982,47 @@ function parseSimpleYaml(raw) {
 			while (i + 1 < lines.length) {
 				const item = /^\s*-\s*(.+?)\s*$/.exec(lines[i + 1]);
 				if (!item) break;
-				items.push(unquote(item[1]));
+				items.push(parseYamlScalar(item[1]));
 				i++;
 			}
 			out[key] = items;
 			continue;
 		}
-		if (rest.startsWith("[") && rest.endsWith("]")) out[key] = rest.slice(1, -1).split(",").map((part) => unquote(part.trim())).filter(Boolean);
-		else if (rest === "true" || rest === "false") out[key] = rest === "true";
-		else if (/^-?\d+(?:\.\d+)?$/.test(rest)) out[key] = Number(rest);
-		else out[key] = unquote(rest);
+		out[key] = parseYamlScalar(rest);
 	}
 	return out;
 }
+function parseYamlScalar(value) {
+	const trimmed = value.trim();
+	if (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("[") && trimmed.endsWith("]") || trimmed.startsWith("{") && trimmed.endsWith("}")) try {
+		return JSON.parse(trimmed);
+	} catch {}
+	if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed.slice(1, -1).split(",").map((part) => unquote(part.trim())).filter(Boolean);
+	if (trimmed === "true" || trimmed === "false") return trimmed === "true";
+	if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+	return unquote(trimmed);
+}
 function formatYamlField(key, value) {
-	if (Array.isArray(value)) return [`${key}:`, ...value.map((item) => `  - ${String(item)}`)];
-	if (typeof value === "string") return [`${key}: ${value}`];
-	if (typeof value === "number" || typeof value === "boolean") return [`${key}: ${String(value)}`];
-	return [`${key}: ${JSON.stringify(value)}`];
+	if (Array.isArray(value)) return [`${key}:`, ...value.map((item) => `  - ${formatYamlScalar(item)}`)];
+	return [`${key}: ${formatYamlScalar(value)}`];
+}
+function formatYamlScalar(value) {
+	if (typeof value === "string") return stringNeedsJsonEncoding(value) ? JSON.stringify(value) : value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	const encoded = JSON.stringify(value);
+	if (encoded === void 0) throw new TypeError(`frontmatter value of type ${typeof value} is not JSON-serializable`);
+	return encoded;
+}
+function stringNeedsJsonEncoding(value) {
+	if (value.length === 0 || value !== value.trim()) return true;
+	if (value.includes("\n") || value.includes("\r")) return true;
+	if (value === "true" || value === "false" || /^-?\d+(?:\.\d+)?$/.test(value)) return true;
+	return /^[[{"']/.test(value) || /["']$/.test(value);
 }
 function unquote(value) {
 	return value.replace(/^['"]|['"]$/g, "");
 }
 //#endregion
-//#region src/wikilinks.ts
-const WIKILINK_REGEX = /\[\[([^\]|]+?)(?:\|[^\]]+?)?\]\]/g;
-function extractWikilinks(content) {
-	const links = [];
-	const regex = new RegExp(WIKILINK_REGEX.source, "g");
-	let match;
-	match = regex.exec(content);
-	while (match !== null) {
-		links.push(match[1].trim());
-		match = regex.exec(content);
-	}
-	return [...new Set(links)];
-}
-function normalizeLinkTarget(target) {
-	return target.trim().replace(/\.md$/i, "").toLowerCase().replace(/\s+/g, "-");
-}
-//#endregion
-//#region src/store.ts
-function layoutFor(root) {
-	return {
-		root,
-		knowledgeDir: join(root, "knowledge"),
-		rawSourcesDir: join(root, "raw", "sources"),
-		sourceRegistryPath: join(root, ".agent-knowledge", "sources.json"),
-		indexPath: join(root, "knowledge", "index.md"),
-		logPath: join(root, "knowledge", "log.md"),
-		cacheDir: join(root, ".agent-knowledge")
-	};
-}
-/**
-* Filenames that `initKnowledgeBase` writes as human-navigation scaffolding.
-* These are excluded from the page index — they exist on disk so authors can
-* curate their vault, but they are not searchable content.
-*
-* Add new scaffold filenames here (and only here) to keep lint, validate, viz,
-* and the indexer consistent.
-*/
-const SCAFFOLD_PAGE_BASENAMES = ["index.md", "log.md"];
-/**
-* True when a knowledge-relative path points at a scaffold file rather than
-* authored content. Accepts both repo-relative paths (`knowledge/index.md`)
-* and any nested `<dir>/index.md` or `<dir>/log.md` (for example
-* `knowledge/concepts/index.md`) so subdirectory README-style scaffolds are
-* also excluded.
-*/
-function isScaffoldPath(path) {
-	const normalized = path.replace(/\\/g, "/");
-	for (const basename of SCAFFOLD_PAGE_BASENAMES) {
-		if (normalized === `knowledge/${basename}`) return true;
-		if (normalized.endsWith(`/${basename}`)) return true;
-	}
-	return false;
-}
-async function initKnowledgeBase(root) {
-	const layout = layoutFor(root);
-	if (await knowledgeBaseInitialized(layout)) return layout;
-	return withKnowledgeMutation(root, () => initKnowledgeBaseUnlocked(root));
-}
-async function initKnowledgeBaseUnlocked(root) {
-	const layout = layoutFor(root);
-	await withSafeDirectory(root, "knowledge", true, () => void 0);
-	await withSafeDirectory(root, "raw/sources", true, () => void 0);
-	await withSafeDirectory(root, ".agent-knowledge", true, () => void 0);
-	await writeIfMissing(root, "knowledge/index.md", "# Knowledge Index\n\n");
-	await writeIfMissing(root, "knowledge/log.md", "# Knowledge Log\n\n");
-	await writeIfMissing(root, ".agent-knowledge/sources.json", "{\n  \"generatedAt\": \"1970-01-01T00:00:00.000Z\",\n  \"sources\": []\n}\n");
-	return layout;
-}
-async function loadKnowledgePages(root) {
-	return withKnowledgeRead(root, () => loadKnowledgePagesUnlocked(root));
-}
-async function loadKnowledgePagesUnlocked(root) {
-	let files;
-	try {
-		files = await listRegularFilesWithinRoot(root, "knowledge");
-	} catch (error) {
-		if (isMissingFile(error)) return [];
-		throw error;
-	}
-	const pages = [];
-	for (const file of files) {
-		const rel = file.path;
-		if (!rel.endsWith(".md")) continue;
-		if (isScaffoldPath(rel)) continue;
-		const { frontmatter, body } = parseFrontmatter(file.bytes.toString("utf8"));
-		const title = stringField(frontmatter.title) ?? firstHeading(body) ?? rel.split("/").pop().replace(/\.md$/, "");
-		const sourceIds = arrayField(frontmatter.sources);
-		const tags = arrayField(frontmatter.tags);
-		pages.push({
-			id: stringField(frontmatter.id) ?? slugify(rel.replace(/^knowledge\//, "").replace(/\.md$/, "")),
-			path: rel,
-			title,
-			text: body,
-			frontmatter,
-			sourceIds,
-			tags,
-			outLinks: extractWikilinks(body).map(normalizeLinkTarget)
-		});
-	}
-	pages.sort((a, b) => a.path.localeCompare(b.path));
-	return pages;
-}
-async function writeJson(path, value) {
-	await writeJsonDurable(path, value);
-}
-async function writeIfMissing(root, relativePath, content) {
-	try {
-		await readRegularFileWithinRoot(root, relativePath);
-	} catch (error) {
-		if (!isMissingFile(error)) throw error;
-		await writeFileDurableWithinRoot(root, relativePath, content, { encoding: "utf8" });
-	}
-}
-async function knowledgeBaseInitialized(layout) {
-	try {
-		await withSafeDirectory(layout.root, "knowledge", false, () => void 0);
-		await withSafeDirectory(layout.root, "raw/sources", false, () => void 0);
-		await withSafeDirectory(layout.root, ".agent-knowledge", false, () => void 0);
-		await readRegularFileWithinRoot(layout.root, "knowledge/index.md");
-		await readRegularFileWithinRoot(layout.root, "knowledge/log.md");
-		await readRegularFileWithinRoot(layout.root, ".agent-knowledge/sources.json");
-		return true;
-	} catch (error) {
-		if (isMissingFile(error)) return false;
-		throw error;
-	}
-}
-function stringField(value) {
-	return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
-}
-function arrayField(value) {
-	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
-}
-function firstHeading(body) {
-	return /^#\s+(.+)$/m.exec(body)?.[1]?.trim();
-}
-//#endregion
-//#region src/graph.ts
-function buildKnowledgeGraph(pages) {
-	const byId = /* @__PURE__ */ new Map();
-	const bySlug = /* @__PURE__ */ new Map();
-	for (const page of pages) {
-		byId.set(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);
-	}
-	const incoming = /* @__PURE__ */ new Map();
-	const outgoing = /* @__PURE__ */ new Map();
-	const edgesByKey = /* @__PURE__ */ new Map();
-	for (const page of 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);
-	}
-	addSourceOverlapEdges(pages, edgesByKey);
-	return {
-		nodes: pages.map((page) => ({
-			id: page.id,
-			title: page.title,
-			path: page.path,
-			tags: page.tags,
-			sourceIds: page.sourceIds,
-			outDegree: outgoing.get(page.id) ?? 0,
-			inDegree: incoming.get(page.id) ?? 0
-		})),
-		edges: [...edgesByKey.values()].sort((a, b) => b.weight - a.weight)
-	};
-}
-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];
-		const b = pages[j];
-		const overlap = a.sourceIds.filter((source) => b.sourceIds.includes(source));
-		if (overlap.length === 0) continue;
-		const key = `${a.id}->${b.id}`;
-		const edge = edges.get(key);
-		if (edge) {
-			edge.weight += overlap.length * .5;
-			edge.reasons.push("shared-source");
-		} else edges.set(key, {
-			source: a.id,
-			target: b.id,
-			weight: overlap.length * .5,
-			reasons: ["shared-source"]
-		});
-	}
-}
-//#endregion
 //#region src/claim-ledger.ts
 /**
 * The algebra of a research claim ledger: claim identity, and how two ledgers
@@ -1641,6 +1456,14 @@ const SourceRecordSchema = z.object({
 	metadata: z.record(z.string(), z.unknown()).optional(),
 	createdAt: z.string().min(1)
 });
+const KnowledgePageInvalidationSchema = z.object({
+	verdict: z.literal("contradicted"),
+	observedAt: z.iso.datetime(),
+	reason: z.string().trim().min(1),
+	evidencePath: z.string().trim().min(1).optional(),
+	grader: z.string().trim().min(1).optional(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+}).strict();
 const KnowledgePageSchema = z.object({
 	id: z.string().min(1),
 	path: z.string().min(1),
@@ -1649,7 +1472,9 @@ const KnowledgePageSchema = z.object({
 	frontmatter: z.record(z.string(), z.unknown()),
 	sourceIds: z.array(z.string()),
 	tags: z.array(z.string()),
-	outLinks: z.array(z.string())
+	outLinks: z.array(z.string()),
+	contradicts: z.array(z.string().min(1)).optional(),
+	invalidation: KnowledgePageInvalidationSchema.optional()
 });
 const KnowledgeGraphNodeSchema = z.object({
 	id: z.string(),
@@ -1793,6 +1618,225 @@ const KnowledgeBaseCandidateSchema = z.object({
 	metadata: z.record(z.string(), z.unknown()).optional()
 });
 //#endregion
+//#region src/wikilinks.ts
+const WIKILINK_REGEX = /\[\[([^\]|]+?)(?:\|[^\]]+?)?\]\]/g;
+function extractWikilinks(content) {
+	const links = [];
+	const regex = new RegExp(WIKILINK_REGEX.source, "g");
+	let match;
+	match = regex.exec(content);
+	while (match !== null) {
+		links.push(match[1].trim());
+		match = regex.exec(content);
+	}
+	return [...new Set(links)];
+}
+function normalizeLinkTarget(target) {
+	return target.trim().replace(/\.md$/i, "").toLowerCase().replace(/\s+/g, "-");
+}
+//#endregion
+//#region src/store.ts
+function layoutFor(root) {
+	return {
+		root,
+		knowledgeDir: join(root, "knowledge"),
+		rawSourcesDir: join(root, "raw", "sources"),
+		sourceRegistryPath: join(root, ".agent-knowledge", "sources.json"),
+		indexPath: join(root, "knowledge", "index.md"),
+		logPath: join(root, "knowledge", "log.md"),
+		cacheDir: join(root, ".agent-knowledge")
+	};
+}
+/**
+* Filenames that `initKnowledgeBase` writes as human-navigation scaffolding.
+* These are excluded from the page index — they exist on disk so authors can
+* curate their vault, but they are not searchable content.
+*
+* Add new scaffold filenames here (and only here) to keep lint, validate, viz,
+* and the indexer consistent.
+*/
+const SCAFFOLD_PAGE_BASENAMES = ["index.md", "log.md"];
+/**
+* True when a knowledge-relative path points at a scaffold file rather than
+* authored content. Accepts both repo-relative paths (`knowledge/index.md`)
+* and any nested `<dir>/index.md` or `<dir>/log.md` (for example
+* `knowledge/concepts/index.md`) so subdirectory README-style scaffolds are
+* also excluded.
+*/
+function isScaffoldPath(path) {
+	const normalized = path.replace(/\\/g, "/");
+	for (const basename of SCAFFOLD_PAGE_BASENAMES) {
+		if (normalized === `knowledge/${basename}`) return true;
+		if (normalized.endsWith(`/${basename}`)) return true;
+	}
+	return false;
+}
+async function initKnowledgeBase(root) {
+	const layout = layoutFor(root);
+	if (await knowledgeBaseInitialized(layout)) return layout;
+	return withKnowledgeMutation(root, () => initKnowledgeBaseUnlocked(root));
+}
+async function initKnowledgeBaseUnlocked(root) {
+	const layout = layoutFor(root);
+	await withSafeDirectory(root, "knowledge", true, () => void 0);
+	await withSafeDirectory(root, "raw/sources", true, () => void 0);
+	await withSafeDirectory(root, ".agent-knowledge", true, () => void 0);
+	await writeIfMissing(root, "knowledge/index.md", "# Knowledge Index\n\n");
+	await writeIfMissing(root, "knowledge/log.md", "# Knowledge Log\n\n");
+	await writeIfMissing(root, ".agent-knowledge/sources.json", "{\n  \"generatedAt\": \"1970-01-01T00:00:00.000Z\",\n  \"sources\": []\n}\n");
+	return layout;
+}
+async function loadKnowledgePages(root, options = {}) {
+	return withKnowledgeRead(root, () => loadKnowledgePagesUnlocked(root, options));
+}
+async function loadKnowledgePagesUnlocked(root, options) {
+	const pagesDirectory = normalizePagesDirectory(options.pagesDirectory ?? "knowledge");
+	let files;
+	try {
+		files = await listRegularFilesWithinRoot(root, pagesDirectory);
+	} catch (error) {
+		if (isMissingFile(error)) return [];
+		throw error;
+	}
+	const pages = [];
+	const pagesPrefix = `${pagesDirectory}/`;
+	for (const file of files) {
+		const rel = file.path.replace(/\\/g, "/");
+		if (!rel.endsWith(".md")) continue;
+		if (isScaffoldPath(rel)) continue;
+		const { frontmatter, body } = parseFrontmatter(file.bytes.toString("utf8"));
+		const title = stringField(frontmatter.title) ?? firstHeading(body) ?? rel.split("/").pop().replace(/\.md$/, "");
+		const sourceIds = arrayField(frontmatter.sources);
+		const tags = arrayField(frontmatter.tags);
+		const contradicts = idListField(frontmatter.contradicts);
+		const invalidation = KnowledgePageInvalidationSchema.safeParse(frontmatter.invalidation);
+		const pageRelativePath = rel.startsWith(pagesPrefix) ? rel.slice(pagesPrefix.length) : rel;
+		pages.push({
+			id: stringField(frontmatter.id) ?? slugify(pageRelativePath.replace(/\.md$/, "")),
+			path: rel,
+			title,
+			text: body,
+			frontmatter,
+			sourceIds,
+			tags,
+			outLinks: extractWikilinks(body).map(normalizeLinkTarget),
+			...contradicts.length > 0 ? { contradicts } : {},
+			...invalidation.success ? { invalidation: invalidation.data } : {}
+		});
+	}
+	pages.sort((a, b) => a.path.localeCompare(b.path));
+	return pages;
+}
+async function writeJson(path, value) {
+	await writeJsonDurable(path, value);
+}
+async function writeIfMissing(root, relativePath, content) {
+	try {
+		await readRegularFileWithinRoot(root, relativePath);
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+		await writeFileDurableWithinRoot(root, relativePath, content, { encoding: "utf8" });
+	}
+}
+async function knowledgeBaseInitialized(layout) {
+	try {
+		await withSafeDirectory(layout.root, "knowledge", false, () => void 0);
+		await withSafeDirectory(layout.root, "raw/sources", false, () => void 0);
+		await withSafeDirectory(layout.root, ".agent-knowledge", false, () => void 0);
+		await readRegularFileWithinRoot(layout.root, "knowledge/index.md");
+		await readRegularFileWithinRoot(layout.root, "knowledge/log.md");
+		await readRegularFileWithinRoot(layout.root, ".agent-knowledge/sources.json");
+		return true;
+	} catch (error) {
+		if (isMissingFile(error)) return false;
+		throw error;
+	}
+}
+function normalizePagesDirectory(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+	if (normalized.length === 0 || normalized === ".") throw new Error("pagesDirectory must name a root-relative directory");
+	return normalized;
+}
+function stringField(value) {
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+}
+function arrayField(value) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function idListField(value) {
+	const values = typeof value === "string" ? [value] : arrayField(value);
+	return [...new Set(values.map((item) => item.trim()).filter(Boolean))];
+}
+function firstHeading(body) {
+	return /^#\s+(.+)$/m.exec(body)?.[1]?.trim();
+}
+//#endregion
+//#region src/graph.ts
+function buildKnowledgeGraph(pages) {
+	const byId = /* @__PURE__ */ new Map();
+	const bySlug = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		byId.set(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);
+	}
+	const incoming = /* @__PURE__ */ new Map();
+	const outgoing = /* @__PURE__ */ new Map();
+	const edgesByKey = /* @__PURE__ */ new Map();
+	for (const page of 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);
+	}
+	addSourceOverlapEdges(pages, edgesByKey);
+	return {
+		nodes: pages.map((page) => ({
+			id: page.id,
+			title: page.title,
+			path: page.path,
+			tags: page.tags,
+			sourceIds: page.sourceIds,
+			outDegree: outgoing.get(page.id) ?? 0,
+			inDegree: incoming.get(page.id) ?? 0
+		})),
+		edges: [...edgesByKey.values()].sort((a, b) => b.weight - a.weight)
+	};
+}
+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];
+		const b = pages[j];
+		const overlap = a.sourceIds.filter((source) => b.sourceIds.includes(source));
+		if (overlap.length === 0) continue;
+		const key = `${a.id}->${b.id}`;
+		const edge = edges.get(key);
+		if (edge) {
+			edge.weight += overlap.length * .5;
+			edge.reasons.push("shared-source");
+		} else edges.set(key, {
+			source: a.id,
+			target: b.id,
+			weight: overlap.length * .5,
+			reasons: ["shared-source"]
+		});
+	}
+}
+//#endregion
 //#region src/kb-store.ts
 /**
 * Where a filesystem knowledge base keeps its machine-written records, relative
@@ -2352,7 +2396,188 @@ async function writeKnowledgeIndex(root) {
 	});
 }
 //#endregion
+//#region src/claim-evidence.ts
+/** The rung at and above which a claim must be machine-checkable to be recorded at that rung. */
+const CHECKABLE_RUNG_THRESHOLD = 4;
+/**
+* The refusal vocabulary, shared by both boundaries. Record time and grade time refuse the same
+* static shapes for the same reasons, so they read from one detector and one set of notes. A
+* second definition would let the two boundaries drift, and a claim the recorder admitted but the
+* grader refuses is exactly the gap this section exists to close.
+*/
+/** The commands that succeed unconditionally, so their exit code carries no information. */
+const ALWAYS_SUCCEEDS = /* @__PURE__ */ new Set(["true", ":"]);
+/** The commands that print their arguments back, so their output carries only their arguments. */
+const PRINTS_ITS_ARGUMENTS = /* @__PURE__ */ new Set(["echo", "printf"]);
+/**
+* A character that makes an argument depend on something outside the command line: a pipe, a
+* command separator, a redirection from a file, a backtick or `$(` substitution, or a variable
+* reference. `$'` and `$"` are quoting sigils, not variable references.
+*/
+const READS_SOMETHING_ELSE = /[|;&\n<`]|\$(?!['"])/;
+/**
+* Whether a check emits a constant, and therefore cannot fail whatever the claim's subject does.
+*
+* The test is deliberately narrow and mechanical. It recognizes exactly two shapes: the whole
+* command is `true` or `:`, or the whole command is one `echo` or `printf` whose arguments read
+* nothing outside the command line. Anything else is treated as a real check.
+*
+* This CANNOT catch every check that cannot fail. A script that prints a hard-coded number, a
+* command whose output an author copied into `expect`, and an `echo` behind a shell alias all look
+* identical to a real check from here. Catching those is not this function's job: it needs an
+* independent party to re-derive the value, which is what rung 5 means. This function refuses only
+* the shapes that carry zero information on their face, where refusing costs the author nothing
+* but a rewrite of the command.
+*/
+function isConstantEmitter(check) {
+	const command = check.trim();
+	if (ALWAYS_SUCCEEDS.has(command)) return true;
+	const argumentStart = command.search(/\s/);
+	const head = argumentStart === -1 ? command : command.slice(0, argumentStart);
+	if (!PRINTS_ITS_ARGUMENTS.has(head)) return false;
+	const argumentText = argumentStart === -1 ? "" : command.slice(argumentStart + 1);
+	return !READS_SOMETHING_ELSE.test(argumentText);
+}
+const NO_CHECK_NOTE = "a claim at this rung asserts that a command reproduces a value, and no command was recorded — record the command that re-establishes it (evidence.check); without one the claim is a self-grade, which is rung 3 at most";
+const NO_EXPECTATION_NOTE = "exit code alone cannot verify a claim at this rung — record the value the check must print";
+const CONSTANT_EMITTER_NOTE = "the check is a constant emitter: it prints a fixed string and exits zero whatever the claim describes, so it can never fail — record a command that reads the artifact the claim is about";
+const MULTILINE_EXPECTATION_NOTE = "the expected value spans multiple lines, but the grader performs one contiguous-substring comparison — record one decisive single-line value per claim";
+const MULTI_VALUE_EXPECTATION_NOTE = "the expected value carries three or more key=value tokens, so any extra token in the check output breaks an otherwise correct claim — record one decisive value per claim";
+const LONG_FIRST_WORD_NOTE = "the check begins with a shell word longer than 200 characters; this is the escaped-newline failure shape where \\n text was recorded instead of real line breaks — write the script to a file or record a real heredoc and a short invocation";
+const INVALID_SHELL_SYNTAX_NOTE = "the recorded check does not parse under bash and would fail independently of the claim — record the exact command only after bash -n accepts it";
+/**
+* The evidence recorded for a claim cannot be graded at the rung it was recorded at.
+*
+* One error type for every mechanically refused shape, because the grader reaches one verdict for
+* all of them: `uncheckable`. `note` names which shape was refused and what to record instead, in
+* the same words the grader reports, so an author reads one message wherever the claim is stopped.
+*/
+var UncheckableClaimError = class extends Error {
+	/** The rung whose evidence rule the recorded claim failed. */
+	rung;
+	/** The refused shape and the fix for it, in the grader's vocabulary. */
+	note;
+	constructor(rung, note) {
+		super(`a claim at rung ${rung} cannot be recorded at that rung: ${note}`);
+		this.name = "UncheckableClaimError";
+		this.rung = rung;
+		this.note = note;
+	}
+};
+/**
+* Refuse the evidence shapes that made self-grading and false refutation possible. Call at record
+* time, not grade time: by grading it is too late — the ungradeable claim has already circulated.
+*
+* At and above `CHECKABLE_RUNG_THRESHOLD` this refuses every statically recognizable shape that
+* `gradeFor` grades `uncheckable`: no check, a check that cannot fail, an unusable expectation,
+* or the escaped-newline command shape. Below the threshold nothing is refused.
+*
+* Four additional rules are calibrated on downstream losses, not taste: four correct claims died
+* from multiline expectations, two from brittle multi-value expectations, one campaign recorded
+* an enormous first word made of literal `\\n` sequences, and a 299-run fleet autopsy reduced ten
+* reported grader failures to checks that were never executed before their authors disappeared.
+* The dynamic half of that last rule is `verifyGradeableEvidence` below.
+*/
+function assertGradeableEvidence(evidence) {
+	if (evidence.rung < 4) return evidence;
+	const note = checkRefusalNote(evidence.check) ?? expectationRefusalNote(evidence.expect);
+	if (note) throw new UncheckableClaimError(evidence.rung, note);
+	return evidence;
+}
+/** The error signatures that mean the check could not run, as opposed to ran and failed. */
+const UNRUNNABLE_SIGNATURES = /No such file|FileNotFoundError|ModuleNotFoundError|command not found|ENOENT|AbortError|timed out|ERR_CHILD_PROCESS_STDIO_MAXBUFFER/;
+/**
+* The calibrated verdict function, pure so every grader shares one semantics. Callers execute the
+* check however their environment requires and pass the observation; this function only judges.
+*/
+function gradeFor(evidence, execution) {
+	const mustBeCheckable = evidence.rung >= 4;
+	if (mustBeCheckable) {
+		const note = checkRefusalNote(evidence.check);
+		if (note) return {
+			verdict: "uncheckable",
+			note
+		};
+	}
+	if (!execution) return { verdict: "unrunnable" };
+	const output = `${execution.stdout}\n${execution.stderr}`.trim();
+	if (execution.exitCode !== 0) return { verdict: UNRUNNABLE_SIGNATURES.test(output) ? "unrunnable" : "contradicted" };
+	if (mustBeCheckable) {
+		const note = expectationRefusalNote(evidence.expect);
+		if (note) return {
+			verdict: "uncheckable",
+			note
+		};
+	}
+	if (evidence.expect && !output.includes(evidence.expect)) return { verdict: output === "" ? "silent-check" : "contradicted" };
+	return { verdict: "verified" };
+}
+/** The verdict alone, for graders that report a lattice member and not a reason. */
+function verdictFor(evidence, execution) {
+	return gradeFor(evidence, execution).verdict;
+}
+/**
+* Parse, execute, and grade evidence at intake using the same cwd and environment the blind grader
+* will use later.
+*
+* This function executes `evidence.check` verbatim. It is intentionally opt-in, Node-only at call
+* time, and dynamically imports `node:child_process` so edge consumers that never invoke it remain
+* importable. Callers must apply their own sandbox and capability policy before passing untrusted
+* commands here.
+*/
+async function verifyGradeableEvidence(evidence, options) {
+	const accepted = assertGradeableEvidence(evidence);
+	const check = accepted.check;
+	const syntax = await runBash([
+		"-n",
+		"-c",
+		check
+	], options);
+	if (syntax.exitCode !== 0) {
+		const detail = `${syntax.stdout}\n${syntax.stderr}`.trim();
+		const note = detail ? `${INVALID_SHELL_SYNTAX_NOTE}: ${detail}` : INVALID_SHELL_SYNTAX_NOTE;
+		throw new UncheckableClaimError(accepted.rung, note);
+	}
+	const execution = await runBash(["-c", check], options);
+	return {
+		evidence: accepted,
+		execution,
+		grade: gradeFor(accepted, execution)
+	};
+}
+function checkRefusalNote(check) {
+	if (!check) return NO_CHECK_NOTE;
+	if (isConstantEmitter(check)) return CONSTANT_EMITTER_NOTE;
+	if ((check.trimStart().split(/\s/, 1)[0] ?? "").length > 200) return LONG_FIRST_WORD_NOTE;
+}
+function expectationRefusalNote(expect) {
+	if (!expect?.trim()) return NO_EXPECTATION_NOTE;
+	if (expect.includes("\n") || expect.includes("\r")) return MULTILINE_EXPECTATION_NOTE;
+	if (expect.trim().split(/\s+/).filter((token) => token.includes("=")).length >= 3) return MULTI_VALUE_EXPECTATION_NOTE;
+}
+async function runBash(args, options) {
+	const { execFile } = await import("node:child_process");
+	return new Promise((resolve) => {
+		execFile(options.bashPath ?? "bash", args, {
+			cwd: options.cwd,
+			env: options.env ?? {},
+			timeout: options.timeoutMs ?? 3e4,
+			maxBuffer: options.maxBufferBytes ?? 1024 * 1024,
+			signal: options.signal,
+			encoding: "utf8"
+		}, (error, stdout, stderr) => {
+			const diagnostic = error && typeof error.code !== "number" ? `${stderr}\n${error}` : stderr;
+			resolve({
+				exitCode: typeof error?.code === "number" ? error.code : error ? 127 : 0,
+				stdout: String(stdout ?? ""),
+				stderr: String(diagnostic ?? "")
+			});
+		});
+	});
+}
+//#endregion
 //#region src/lint.ts
+const ABSOLUTE_PATH_TOKEN = /(?:^|[\s"'=(])(?:\/(?!dev\/null\b)[^\s"'();]+|[A-Za-z]:\\[^\s"'();]+)/m;
 function lintKnowledgeIndex(index) {
 	const findings = [];
 	const byTarget = /* @__PURE__ */ new Set();
@@ -2421,6 +2646,9 @@ function lintKnowledgeIndex(index) {
 			message: `Page cites unknown source anchor "${ref.sourceId}#${ref.anchorId}".`,
 			metadata: ref
 		});
+		findings.push(...lintPageEvidence(page));
+		findings.push(...lintPageContradictions(page, pageIds));
+		findings.push(...lintPageInvalidation(page));
 	}
 	for (const [title, paths] of titles) if (title && paths.length > 1) findings.push({
 		type: "duplicate-title",
@@ -2442,6 +2670,90 @@ function lintKnowledgeIndex(index) {
 	});
 	return findings;
 }
+function lintPageEvidence(page) {
+	if (page.frontmatter.rung === void 0) return [];
+	const rung = evidenceRung(page.frontmatter.rung);
+	if (rung === void 0) return [{
+		type: "ungradeable-evidence",
+		severity: "error",
+		page: page.path,
+		message: "Evidence rung must be an integer from 1 through 5.",
+		metadata: { rung: page.frontmatter.rung }
+	}];
+	const check = stringValue(page.frontmatter.check);
+	const expect = stringValue(page.frontmatter.expect);
+	const evidencePath = stringValue(page.frontmatter.evidencePath);
+	const evidence = {
+		rung,
+		...check ? { check } : {},
+		...expect ? { expect } : {},
+		...evidencePath ? { evidencePath } : {}
+	};
+	const findings = [];
+	try {
+		assertGradeableEvidence(evidence);
+	} catch (error) {
+		if (!(error instanceof UncheckableClaimError)) throw error;
+		findings.push({
+			type: "ungradeable-evidence",
+			severity: "error",
+			page: page.path,
+			message: error.note,
+			metadata: { rung: error.rung }
+		});
+	}
+	if (rung >= 4 && !evidence.evidencePath) findings.push({
+		type: "missing-evidence-path",
+		severity: "warning",
+		page: page.path,
+		message: `Rung ${rung} evidence has no evidencePath for a human to inspect.`,
+		metadata: { rung }
+	});
+	for (const [field, value] of [["check", evidence.check], ["evidencePath", evidence.evidencePath]]) if (value && ABSOLUTE_PATH_TOKEN.test(value)) findings.push({
+		type: "nonportable-evidence",
+		severity: "warning",
+		page: page.path,
+		message: `${field} contains an absolute path and may not re-run outside the author machine.`,
+		metadata: {
+			rung,
+			field
+		}
+	});
+	return findings;
+}
+function lintPageContradictions(page, pageIds) {
+	const findings = [];
+	for (const targetId of page.contradicts ?? []) {
+		const selfReference = targetId === page.id;
+		if (selfReference || !pageIds.has(targetId)) findings.push({
+			type: "broken-contradiction",
+			severity: "error",
+			page: page.path,
+			message: selfReference ? `Page "${page.id}" cannot contradict itself.` : `Page contradicts unknown page id "${targetId}".`,
+			metadata: { targetId }
+		});
+	}
+	return findings;
+}
+function lintPageInvalidation(page) {
+	if (page.frontmatter.invalidation === void 0) return [];
+	const parsed = KnowledgePageInvalidationSchema.safeParse(page.frontmatter.invalidation);
+	if (parsed.success) return [];
+	return [{
+		type: "invalid-invalidation",
+		severity: "error",
+		page: page.path,
+		message: "Page invalidation must record verdict=contradicted, an ISO observedAt timestamp, and a non-empty reason.",
+		metadata: { issues: parsed.error.issues }
+	}];
+}
+function evidenceRung(value) {
+	const parsed = typeof value === "string" && /^\d+$/.test(value) ? Number(value) : value;
+	return parsed === 1 || parsed === 2 || parsed === 3 || parsed === 4 || parsed === 5 ? parsed : void 0;
+}
+function stringValue(value) {
+	return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
 function extractSourceRefs(text) {
 	const refs = [];
 	const regex = /\[\^([A-Za-z0-9_-]+)(?:#([A-Za-z0-9_.:-]+))?\]/g;
@@ -2657,6 +2969,6 @@ function explainKnowledgeTarget(index, target) {
 	};
 }
 //#endregion
-export { mergeTrackedClaims as $, KnowledgeGraphNodeSchema as A, removeDurable as At, ClaimLedgerGoalConflictError as B, textSourceAdapter as Bt, KB_STORE_DIR as C, prepareKnowledgeFileTransaction as Ct, KnowledgeBaseCandidateSchema as D, listRegularFilesWithinRoot as Dt, DeepQuestionSchema as E, isMissingFile as Et, ResearchClaimRecordSchema as F, writeFileDurable as Ft, claimEvidenceId as G, assertResearchClaimEvidenceIntegrity as H, ResearchSourceVersionSchema as I, writeFileDurableWithinRoot as It, deepQuestionId as J, claimId as K, SourceAnchorSchema as L, writeJsonDurable as Lt, KnowledgePageSchema as M, syncDirectory as Mt, ResearchClaimEvidenceSchema as N, withSafeDescendant as Nt, KnowledgeEventSchema as O, readRegularFileNoFollow as Ot, ResearchClaimLedgerSchema as P, withSafeDirectory as Pt, mergeClaimLedgers as Q, SourceRecordSchema as R, writeJsonDurableWithinRoot as Rt, KB_INDEX_PATH as S, knowledgeFileTransactionPlanHash as St, assertClaimLedgerId as T, isKernelAnchoredPath as Tt, assertResearchClaimLedgerIntegrity as U, assertDeepQuestionIntegrity as V, assertTrackedClaimIntegrity as W, linkClaimContradictions as X, emptyClaimLedger as Y, materializeRegisteredClaimEvidence as Z, writeSourceRegistry as _, withKnowledgeMutation as _t, applyKnowledgeWriteBlocksFile as a, isScaffoldPath as at, KB_CLAIM_LEDGER_DIR as b, assertKnowledgeMutationPath as bt, validateKnowledgeIndex as c, writeJson as ct, writeKnowledgeIndex as d, normalizeLinkTarget as dt, normalizeClaimText as et, addSourcePath as f, formatFrontmatter as ft, sourceRegistryPath as g, recoverPendingKnowledgeMutation as gt, snapshotSourceTextInput as h, inspectPendingKnowledgeMutation as ht, applyKnowledgeWriteBlocks as i, initKnowledgeBase as it, KnowledgeIndexSchema as j, renameDurable as jt, KnowledgeGraphEdgeSchema as k, readRegularFileWithinRoot as kt, lintKnowledgeIndex as l, WIKILINK_REGEX as lt, loadSourceRegistry as m, acquireDurableFileLock as mt, inspectKnowledgeIndex as n, buildKnowledgeGraph as nt, isSafeKnowledgePath as o, layoutFor as ot, addSourceText as p, parseFrontmatter as pt, claimSourceHost as q, stringMetadata as r, SCAFFOLD_PAGE_BASENAMES as rt, parseKnowledgeWriteBlocks as s, loadKnowledgePages as st, explainKnowledgeTarget as t, researchSourceVersionKey as tt, buildKnowledgeIndex as u, extractWikilinks as ut, ClaimLedgerMigrationRequiredError as v, withKnowledgeRead as vt, MemoryKbStore as w, rollbackKnowledgeFileTransaction as wt, KB_EVENTS_PATH as x, finishKnowledgeFileTransaction as xt, FileSystemKbStore as y, applyKnowledgeFileTransaction as yt, KNOWLEDGE_EVENT_TYPES as z, mediaTypeFor$1 as zt };
+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 };
 
-//# sourceMappingURL=inspect-CJQGYuKa.js.map
+//# sourceMappingURL=inspect-B7AJ7CZS.js.map