@tangle-network/agent-knowledge 2.0.0 → 3.0.0

package/README.md

@@ -343,7 +343,7 @@ console.log(promoted.promoted)
 Calling it again with the same `runId` resumes interrupted work.
 `withKnowledgeImprovementCandidate` materializes the measured bytes in an isolated temporary directory for the callback, checks them again afterward, and removes the directory.
 `promoteKnowledgeCandidate` applies only the frozen bytes identified by the approved candidate reference, and refuses if the live base changed.
-The current release intentionally accepts only its strict run-state format; incomplete runs created by 1.x must be completed or restarted before upgrading.
+The current release accepts one strict run-state format; incomplete runs created before 3.0 must be completed or restarted before upgrading.
 The exact candidate workflow requires Linux; other knowledge, retrieval, and evaluation APIs remain cross-platform.
 
 If a required phase is missing its hook, the loop throws.

package/dist/benchmarks/index.d.ts

@@ -1,5 +1,5 @@
 import '@tangle-network/agent-eval/campaign';
-import '../types-CjqPcTTK.js';
-export { B as BuildRetrievalBenchmarkCasesFromQrelsOptions, I as INDUSTRY_MEMORY_BENCHMARKS, d as INDUSTRY_RAG_BENCHMARKS, K as KnowledgeAnswerBenchmarkCase, e as KnowledgeAnswerBenchmarkTaskKind, f as KnowledgeBenchmarkArtifact, g as KnowledgeBenchmarkCase, h as KnowledgeBenchmarkCaseBase, i as KnowledgeBenchmarkDistribution, j as KnowledgeBenchmarkEvaluation, k as KnowledgeBenchmarkFamily, l as KnowledgeBenchmarkReport, m as KnowledgeBenchmarkResponder, n as KnowledgeBenchmarkScenario, o as KnowledgeBenchmarkSliceSummary, p as KnowledgeBenchmarkSource, q as KnowledgeBenchmarkSpec, r as KnowledgeBenchmarkSplit, s as KnowledgeBenchmarkTaskKind, t as KnowledgeClaimMatcher, u as KnowledgeMemoryBenchmarkCase, v as KnowledgeMemoryBenchmarkTaskKind, w as KnowledgeMemoryEvent, x as KnowledgeMemoryFactMatcher, y as KnowledgeRetrievalBenchmarkCase, z as KnowledgeRetrievalBenchmarkQrel, A as KnowledgeRetrievalBenchmarkQuery, M as MemoryAdapterBenchmarkCandidate, C as MemoryAdapterBenchmarkRankingRow, V as RunKnowledgeBenchmarkSuiteOptions, W as RunKnowledgeBenchmarkSuiteResult, X as RunMemoryAdapterBenchmarkOptions, Y as RunMemoryAdapterBenchmarkResult, Z as buildFirstPartyMemoryLifecycleBenchmarkCases, _ as buildIndustryMemoryBenchmarkSmokeCases, $ as buildIndustryRagBenchmarkSmokeCases, a0 as buildKnowledgeBenchmarkScenarios, a1 as buildRetrievalBenchmarkCasesFromQrels, a4 as createInMemoryBenchmarkAdapter, a5 as createMemoryAdapterBenchmarkResponder, a6 as createNoopMemoryBenchmarkAdapter, a7 as isKnowledgeMemoryBenchmarkCase, a8 as knowledgeBenchmarkJudge, a9 as parseKnowledgeBenchmarkJsonl, aa as parseKnowledgeBenchmarkQrels, ab as renderKnowledgeBenchmarkReportMarkdown, ac as respondToIndustryMemoryBenchmarkSmokeCase, ad as respondToIndustryRagBenchmarkSmokeCase, ai as runKnowledgeBenchmarkSuite, aj as runMemoryAdapterBenchmark, al as scoreKnowledgeBenchmarkArtifact, am as scoreMemoryBenchmarkArtifact, ao as summarizeKnowledgeBenchmarkCampaign } from '../index-BLxw1I_F.js';
-import '../types-C17sAROL.js';
+import '../types-BFRyr390.js';
+export { B as BuildRetrievalBenchmarkCasesFromQrelsOptions, I as INDUSTRY_MEMORY_BENCHMARKS, d as INDUSTRY_RAG_BENCHMARKS, K as KnowledgeAnswerBenchmarkCase, e as KnowledgeAnswerBenchmarkTaskKind, f as KnowledgeBenchmarkArtifact, g as KnowledgeBenchmarkCase, h as KnowledgeBenchmarkCaseBase, i as KnowledgeBenchmarkDistribution, j as KnowledgeBenchmarkEvaluation, k as KnowledgeBenchmarkFamily, l as KnowledgeBenchmarkReport, m as KnowledgeBenchmarkResponder, n as KnowledgeBenchmarkScenario, o as KnowledgeBenchmarkSliceSummary, p as KnowledgeBenchmarkSource, q as KnowledgeBenchmarkSpec, r as KnowledgeBenchmarkSplit, s as KnowledgeBenchmarkTaskKind, t as KnowledgeClaimMatcher, u as KnowledgeMemoryBenchmarkCase, v as KnowledgeMemoryBenchmarkTaskKind, w as KnowledgeMemoryEvent, x as KnowledgeMemoryFactMatcher, y as KnowledgeRetrievalBenchmarkCase, z as KnowledgeRetrievalBenchmarkQrel, A as KnowledgeRetrievalBenchmarkQuery, M as MemoryAdapterBenchmarkCandidate, C as MemoryAdapterBenchmarkRankingRow, V as RunKnowledgeBenchmarkSuiteOptions, W as RunKnowledgeBenchmarkSuiteResult, X as RunMemoryAdapterBenchmarkOptions, Y as RunMemoryAdapterBenchmarkResult, Z as buildFirstPartyMemoryLifecycleBenchmarkCases, _ as buildIndustryMemoryBenchmarkSmokeCases, $ as buildIndustryRagBenchmarkSmokeCases, a0 as buildKnowledgeBenchmarkScenarios, a1 as buildRetrievalBenchmarkCasesFromQrels, a4 as createInMemoryBenchmarkAdapter, a5 as createMemoryAdapterBenchmarkResponder, a6 as createNoopMemoryBenchmarkAdapter, a7 as isKnowledgeMemoryBenchmarkCase, a8 as knowledgeBenchmarkJudge, a9 as parseKnowledgeBenchmarkJsonl, aa as parseKnowledgeBenchmarkQrels, ab as renderKnowledgeBenchmarkReportMarkdown, ac as respondToIndustryMemoryBenchmarkSmokeCase, ad as respondToIndustryRagBenchmarkSmokeCase, ai as runKnowledgeBenchmarkSuite, aj as runMemoryAdapterBenchmark, al as scoreKnowledgeBenchmarkArtifact, am as scoreMemoryBenchmarkArtifact, ao as summarizeKnowledgeBenchmarkCampaign } from '../index-BHQk7jOT.js';
+import '../types-6x0OpfW6.js';
 import '@tangle-network/agent-eval/rl';

package/dist/{chunk-QID2QVR5.js → chunk-2BJ5JR3L.js}

@@ -49,6 +49,94 @@ function anchorsForText(uri, text) {
   return anchors;
 }
 
+// src/wikilinks.ts
+var 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, "-");
+}
+
+// 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);
+  const 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
+  }));
+  return { nodes, 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 * 0.5;
+        edge.reasons.push("shared-source");
+      } else {
+        edges.set(key, {
+          source: a.id,
+          target: b.id,
+          weight: overlap.length * 0.5,
+          reasons: ["shared-source"]
+        });
+      }
+    }
+  }
+}
+
 // src/mutation-lock.ts
 import { AsyncLocalStorage } from "async_hooks";
 import { mkdir as mkdir2, readFile } from "fs/promises";
@@ -341,7 +429,6 @@ var transactionEntrySchema = z.object({
   afterMode: fileModeSchema.optional()
 }).strict();
 var transactionSchema = z.object({
-  schemaVersion: z.literal(1),
   kind: z.literal("knowledge-file-transaction"),
   transactionId: z.string().uuid(),
   purpose: z.string().min(1),
@@ -349,7 +436,6 @@ var transactionSchema = z.object({
   entries: z.array(transactionEntrySchema).min(1)
 }).strict();
 var transactionDirectionSchema = z.object({
-  schemaVersion: z.literal(1),
   transactionId: z.string().uuid(),
   direction: z.literal("rollback")
 }).strict();
@@ -418,7 +504,6 @@ async function prepareKnowledgeFileTransaction(input) {
         }
       }
       const transaction = transactionSchema.parse({
-        schemaVersion: 1,
         kind: "knowledge-file-transaction",
         transactionId: randomUUID2(),
         purpose: input.purpose,
@@ -607,7 +692,6 @@ async function rollbackKnowledgeFileTransaction(input) {
       const direction = await readTransactionDirection(transactionDir, transaction);
       if (direction !== "rollback") {
         await writeJsonDurable(join(transactionDir, "direction.json"), {
-          schemaVersion: 1,
           transactionId: transaction.transactionId,
           direction: "rollback"
         });
@@ -1097,156 +1181,6 @@ function isOdd(value) {
   return value % 2 === 1;
 }
 
-// src/frontmatter.ts
-function parseFrontmatter(content) {
-  const normalized = content.replace(/\r\n/g, "\n");
-  if (!normalized.startsWith("---\n")) return { frontmatter: {}, body: normalized };
-  const end = normalized.indexOf("\n---", 4);
-  if (end < 0) return { frontmatter: {}, body: normalized };
-  const raw = normalized.slice(4, end);
-  const after = normalized.slice(end).replace(/^\n---\s*\n?/, "");
-  return { frontmatter: parseSimpleYaml(raw), body: after };
-}
-function formatFrontmatter(frontmatter, body) {
-  const lines = Object.entries(frontmatter).filter(([, value]) => value !== void 0).flatMap(([key, value]) => formatYamlField(key, value));
-  if (lines.length === 0) return body;
-  return `---
-${lines.join("\n")}
----
-${body.replace(/^\n+/, "")}`;
-}
-function parseSimpleYaml(raw) {
-  const out = {};
-  const lines = raw.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const scalar = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
-    if (!scalar) continue;
-    const key = scalar[1];
-    const rest = scalar[2].trim();
-    if (rest === "") {
-      const items = [];
-      while (i + 1 < lines.length) {
-        const item = /^\s*-\s*(.+?)\s*$/.exec(lines[i + 1]);
-        if (!item) break;
-        items.push(unquote(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);
-    }
-  }
-  return out;
-}
-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)}`];
-}
-function unquote(value) {
-  return value.replace(/^['"]|['"]$/g, "");
-}
-
-// src/wikilinks.ts
-var 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, "-");
-}
-
-// 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);
-  const 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
-  }));
-  return { nodes, 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 * 0.5;
-        edge.reasons.push("shared-source");
-      } else {
-        edges.set(key, {
-          source: a.id,
-          target: b.id,
-          weight: overlap.length * 0.5,
-          reasons: ["shared-source"]
-        });
-      }
-    }
-  }
-}
-
 // src/schemas.ts
 import { z as z2 } from "zod";
 var SourceAnchorSchema = z2.object({
@@ -1370,6 +1304,68 @@ var KnowledgeBaseCandidateSchema = z2.object({
   metadata: z2.record(z2.string(), z2.unknown()).optional()
 });
 
+// src/frontmatter.ts
+function parseFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) return { frontmatter: {}, body: normalized };
+  const end = normalized.indexOf("\n---", 4);
+  if (end < 0) return { frontmatter: {}, body: normalized };
+  const raw = normalized.slice(4, end);
+  const after = normalized.slice(end).replace(/^\n---\s*\n?/, "");
+  return { frontmatter: parseSimpleYaml(raw), body: after };
+}
+function formatFrontmatter(frontmatter, body) {
+  const lines = Object.entries(frontmatter).filter(([, value]) => value !== void 0).flatMap(([key, value]) => formatYamlField(key, value));
+  if (lines.length === 0) return body;
+  return `---
+${lines.join("\n")}
+---
+${body.replace(/^\n+/, "")}`;
+}
+function parseSimpleYaml(raw) {
+  const out = {};
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const scalar = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (!scalar) continue;
+    const key = scalar[1];
+    const rest = scalar[2].trim();
+    if (rest === "") {
+      const items = [];
+      while (i + 1 < lines.length) {
+        const item = /^\s*-\s*(.+?)\s*$/.exec(lines[i + 1]);
+        if (!item) break;
+        items.push(unquote(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);
+    }
+  }
+  return out;
+}
+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)}`];
+}
+function unquote(value) {
+  return value.replace(/^['"]|['"]$/g, "");
+}
+
 // src/store.ts
 import { join as join3 } from "path";
 function layoutFor(root) {
@@ -1869,66 +1865,31 @@ function extractSourceRefs(text) {
   return refs;
 }
 
-// src/metadata.ts
-function stringMetadata(metadata, key) {
-  const value = metadata?.[key];
-  return typeof value === "string" ? value : void 0;
-}
-
-// src/inspect.ts
-function inspectKnowledgeIndex(index, options = {}) {
-  const now = options.now ?? /* @__PURE__ */ new Date();
-  const findings = lintKnowledgeIndex(index);
-  const degree = new Map(index.graph.nodes.map((node) => [node.id, node.inDegree + node.outDegree]));
-  const sourceFreshness = index.sources.map((source) => inspectSourceFreshness(source, now));
-  return {
-    pageCount: index.pages.length,
-    sourceCount: index.sources.length,
-    expiredSourceCount: sourceFreshness.filter((source) => source.status === "expired").length,
-    staleSourceCount: sourceFreshness.filter((source) => source.status !== "fresh").length,
-    edgeCount: index.graph.edges.length,
-    findingCount: findings.length,
-    blockingFindingCount: findings.filter((finding) => finding.severity === "error").length,
-    topPages: [...index.pages].sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0)).slice(0, 10).map((page) => ({
-      path: page.path,
-      title: page.title,
-      degree: degree.get(page.id) ?? 0,
-      sources: page.sourceIds.length
-    })),
-    sourceFreshness,
-    findings
-  };
-}
-function inspectSourceFreshness(source, now) {
-  const validUntil = source.validUntil ?? stringMetadata(source.metadata, "validUntil") ?? stringMetadata(source.metadata, "expiresAt");
-  const lastVerifiedAt = source.lastVerifiedAt ?? stringMetadata(source.metadata, "lastVerifiedAt");
-  const status = validUntil && Number.isFinite(Date.parse(validUntil)) ? Date.parse(validUntil) <= now.getTime() ? "expired" : "fresh" : "unknown";
-  return { id: source.id, title: source.title, uri: source.uri, status, validUntil, lastVerifiedAt };
-}
-function explainKnowledgeTarget(index, target) {
-  const page = index.pages.find(
-    (candidate) => candidate.path === target || candidate.id === target || candidate.title.toLowerCase() === target.toLowerCase()
-  );
-  const inbound = page ? index.graph.edges.filter((edge) => edge.target === page.id).map(
-    (edge) => index.pages.find((candidate) => candidate.id === edge.source)?.path ?? edge.source
-  ) : [];
-  const related = page ? searchKnowledge(index, `${page.title} ${page.tags.join(" ")}`, 6).filter((result) => result.page.id !== page.id).map((result) => ({
-    path: result.page.path,
-    title: result.page.title,
-    score: result.score
-  })) : searchKnowledge(index, target, 6).map((result) => ({
-    path: result.page.path,
-    title: result.page.title,
-    score: result.score
-  }));
-  return {
-    target,
-    page,
-    sources: page ? index.sources.filter((source) => page.sourceIds.includes(source.id)).map((source) => ({ id: source.id, title: source.title, uri: source.uri })) : [],
-    links: page?.outLinks ?? [],
-    inbound,
-    related
-  };
+// src/validate.ts
+function validateKnowledgeIndex(index, options = {}) {
+  const findings = [...lintKnowledgeIndex(index)];
+  const parsed = KnowledgeIndexSchema.safeParse(index);
+  if (!parsed.success) {
+    findings.push({
+      type: "missing-frontmatter",
+      severity: "error",
+      message: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
+    });
+  }
+  if (options.strict) {
+    for (const page of index.pages) {
+      if (isScaffoldPath(page.path)) continue;
+      if (!page.frontmatter.id || !page.frontmatter.title) {
+        findings.push({
+          type: "missing-frontmatter",
+          severity: "error",
+          page: page.path,
+          message: "Strict mode requires id and title frontmatter."
+        });
+      }
+    }
+  }
+  return { ok: !findings.some((finding) => finding.severity === "error"), findings };
 }
 
 // src/write-protocol.ts
@@ -2031,37 +1992,71 @@ async function applyKnowledgeWriteBlocksFile(root, proposalPath) {
   return applyKnowledgeWriteBlocks(root, await readFile3(proposalPath, "utf8"));
 }
 
-// src/validate.ts
-function validateKnowledgeIndex(index, options = {}) {
-  const findings = [...lintKnowledgeIndex(index)];
-  const parsed = KnowledgeIndexSchema.safeParse(index);
-  if (!parsed.success) {
-    findings.push({
-      type: "missing-frontmatter",
-      severity: "error",
-      message: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
-    });
-  }
-  if (options.strict) {
-    for (const page of index.pages) {
-      if (isScaffoldPath(page.path)) continue;
-      if (!page.frontmatter.id || !page.frontmatter.title) {
-        findings.push({
-          type: "missing-frontmatter",
-          severity: "error",
-          page: page.path,
-          message: "Strict mode requires id and title frontmatter."
-        });
-      }
-    }
-  }
-  return { ok: !findings.some((finding) => finding.severity === "error"), findings };
+// src/metadata.ts
+function stringMetadata(metadata, key) {
+  const value = metadata?.[key];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/inspect.ts
+function inspectKnowledgeIndex(index, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const findings = lintKnowledgeIndex(index);
+  const degree = new Map(index.graph.nodes.map((node) => [node.id, node.inDegree + node.outDegree]));
+  const sourceFreshness = index.sources.map((source) => inspectSourceFreshness(source, now));
+  return {
+    pageCount: index.pages.length,
+    sourceCount: index.sources.length,
+    expiredSourceCount: sourceFreshness.filter((source) => source.status === "expired").length,
+    staleSourceCount: sourceFreshness.filter((source) => source.status !== "fresh").length,
+    edgeCount: index.graph.edges.length,
+    findingCount: findings.length,
+    blockingFindingCount: findings.filter((finding) => finding.severity === "error").length,
+    topPages: [...index.pages].sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0)).slice(0, 10).map((page) => ({
+      path: page.path,
+      title: page.title,
+      degree: degree.get(page.id) ?? 0,
+      sources: page.sourceIds.length
+    })),
+    sourceFreshness,
+    findings
+  };
+}
+function inspectSourceFreshness(source, now) {
+  const validUntil = source.validUntil ?? stringMetadata(source.metadata, "validUntil") ?? stringMetadata(source.metadata, "expiresAt");
+  const lastVerifiedAt = source.lastVerifiedAt ?? stringMetadata(source.metadata, "lastVerifiedAt");
+  const status = validUntil && Number.isFinite(Date.parse(validUntil)) ? Date.parse(validUntil) <= now.getTime() ? "expired" : "fresh" : "unknown";
+  return { id: source.id, title: source.title, uri: source.uri, status, validUntil, lastVerifiedAt };
+}
+function explainKnowledgeTarget(index, target) {
+  const page = index.pages.find(
+    (candidate) => candidate.path === target || candidate.id === target || candidate.title.toLowerCase() === target.toLowerCase()
+  );
+  const inbound = page ? index.graph.edges.filter((edge) => edge.target === page.id).map(
+    (edge) => index.pages.find((candidate) => candidate.id === edge.source)?.path ?? edge.source
+  ) : [];
+  const related = page ? searchKnowledge(index, `${page.title} ${page.tags.join(" ")}`, 6).filter((result) => result.page.id !== page.id).map((result) => ({
+    path: result.page.path,
+    title: result.page.title,
+    score: result.score
+  })) : searchKnowledge(index, target, 6).map((result) => ({
+    path: result.page.path,
+    title: result.page.title,
+    score: result.score
+  }));
+  return {
+    target,
+    page,
+    sources: page ? index.sources.filter((source) => page.sourceIds.includes(source.id)).map((source) => ({ id: source.id, title: source.title, uri: source.uri })) : [],
+    links: page?.outLinks ?? [],
+    inbound,
+    related
+  };
 }
 
 export {
   textSourceAdapter,
   mediaTypeFor,
-  stringMetadata,
   writeFileDurableWithinRoot,
   writeJsonDurableWithinRoot,
   renameDurable,
@@ -2075,17 +2070,15 @@ export {
   finishKnowledgeFileTransaction,
   rollbackKnowledgeFileTransaction,
   assertKnowledgeMutationPath,
+  WIKILINK_REGEX,
+  extractWikilinks,
+  normalizeLinkTarget,
+  buildKnowledgeGraph,
   withKnowledgeMutation,
   inspectPendingKnowledgeMutation,
   recoverPendingKnowledgeMutation,
   withKnowledgeRead,
   acquireDurableFileLock,
-  parseFrontmatter,
-  formatFrontmatter,
-  WIKILINK_REGEX,
-  extractWikilinks,
-  normalizeLinkTarget,
-  buildKnowledgeGraph,
   SourceAnchorSchema,
   SourceRecordSchema,
   KnowledgePageSchema,
@@ -2094,6 +2087,8 @@ export {
   KnowledgeIndexSchema,
   KnowledgeEventSchema,
   KnowledgeBaseCandidateSchema,
+  parseFrontmatter,
+  formatFrontmatter,
   layoutFor,
   SCAFFOLD_PAGE_BASENAMES,
   isScaffoldPath,
@@ -2108,12 +2103,13 @@ export {
   buildKnowledgeIndex,
   writeKnowledgeIndex,
   lintKnowledgeIndex,
-  inspectKnowledgeIndex,
-  explainKnowledgeTarget,
+  validateKnowledgeIndex,
   isSafeKnowledgePath,
   parseKnowledgeWriteBlocks,
   applyKnowledgeWriteBlocks,
   applyKnowledgeWriteBlocksFile,
-  validateKnowledgeIndex
+  stringMetadata,
+  inspectKnowledgeIndex,
+  explainKnowledgeTarget
 };
-//# sourceMappingURL=chunk-QID2QVR5.js.map
+//# sourceMappingURL=chunk-2BJ5JR3L.js.map