@tangle-network/agent-knowledge 1.2.0 → 1.3.0

package/dist/{chunk-JLCQ6O7W.js → chunk-HKYD765Q.js}

@@ -1,14 +1,158 @@
-// src/ids.ts
-import { createHash } from "crypto";
-function sha256(text) {
-  return createHash("sha256").update(text).digest("hex");
+import {
+  sha256,
+  slugify,
+  stableId
+} from "./chunk-YMKHCTS2.js";
+
+// src/adapters.ts
+var textSourceAdapter = {
+  id: "text",
+  canLoad: (input) => Boolean(input.text) || /\.(md|txt|json|csv)$/i.test(input.uri),
+  load: (input) => ({
+    title: input.uri.split("/").pop(),
+    mediaType: mediaTypeFor(input.uri),
+    text: decodeText(input),
+    anchors: anchorsForText(input.uri, decodeText(input)),
+    metadata: input.metadata
+  })
+};
+function mediaTypeFor(uri) {
+  const lower = uri.toLowerCase();
+  if (lower.endsWith(".md")) return "text/markdown";
+  if (lower.endsWith(".txt")) return "text/plain";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".csv")) return "text/csv";
+  if (lower.endsWith(".pdf")) return "application/pdf";
+  return "application/octet-stream";
 }
-function slugify(input) {
-  const out = input.trim().toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-").replace(/^-+|-+$/g, "");
-  return out || "untitled";
+function decodeText(input) {
+  return input.text ?? (input.bytes ? new TextDecoder().decode(input.bytes).slice(0, 2e5) : void 0);
 }
-function stableId(prefix, content) {
-  return `${prefix}_${sha256(content).slice(0, 16)}`;
+function anchorsForText(uri, text) {
+  if (!text) return [];
+  const lines = text.split("\n");
+  const anchors = [
+    { id: "all", sourceId: "", label: "Full source", lineStart: 1, lineEnd: lines.length }
+  ];
+  for (let i = 0; i < lines.length; i += 50) {
+    anchors.push({
+      id: `l${i + 1}`,
+      sourceId: "",
+      label: `${uri}:${i + 1}`,
+      lineStart: i + 1,
+      lineEnd: Math.min(lines.length, i + 50)
+    });
+  }
+  return anchors;
+}
+
+// src/search.ts
+var RRF_K = 60;
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "is",
+  "a",
+  "an",
+  "what",
+  "how",
+  "are",
+  "was",
+  "were",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "in",
+  "on",
+  "and"
+]);
+function searchKnowledge(index, query, limit = 10) {
+  const trimmed = query.trim();
+  if (trimmed === "") return [];
+  const tokenRanked = rankByTokens(index.pages, trimmed);
+  const graphRanked = rankByGraph(index.pages, tokenRanked);
+  const scores = reciprocalRankFusion([tokenRanked.map((p) => p.id), graphRanked.map((p) => p.id)]);
+  const byId = new Map(index.pages.map((page) => [page.id, page]));
+  const ranked = [...scores.entries()].map(([id, score]) => ({ page: byId.get(id), score })).filter((item) => Boolean(item.page)).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).slice(0, limit);
+  const topScore = ranked[0]?.score ?? 0;
+  return ranked.map((item, i) => ({
+    page: item.page,
+    score: item.score,
+    rrfScore: item.score,
+    normalizedScore: topScore > 0 ? item.score / topScore : 0,
+    rank: i + 1,
+    snippet: buildSnippet(item.page.text, trimmed),
+    reasons: reasonsFor(item.page, trimmed)
+  }));
+}
+function tokenizeQuery(query) {
+  const raw = query.toLowerCase().split(/[\s,，。！？、；：""''（）()\-_/\\·~～…]+/).filter((token) => token.length > 1 && !STOP_WORDS.has(token));
+  const tokens = [];
+  for (const token of raw) {
+    if (/[\u4e00-\u9fff\u3400-\u4dbf]/.test(token) && token.length > 2) {
+      const chars = [...token];
+      for (let i = 0; i < chars.length - 1; i++) tokens.push(chars[i] + chars[i + 1]);
+      tokens.push(...chars);
+    }
+    tokens.push(token);
+  }
+  return [...new Set(tokens)];
+}
+function reciprocalRankFusion(rankLists, k = RRF_K) {
+  const scores = /* @__PURE__ */ new Map();
+  for (const list of rankLists) {
+    list.forEach((id, idx) => {
+      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + idx + 1));
+    });
+  }
+  return scores;
+}
+function rankByTokens(pages, query) {
+  const tokens = tokenizeQuery(query);
+  const effective = tokens.length > 0 ? tokens : [query.toLowerCase()];
+  return pages.map((page) => ({ page, score: tokenScore(page, query, effective) })).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).map((item) => item.page);
+}
+function rankByGraph(pages, tokenRanked) {
+  if (tokenRanked.length === 0) return [];
+  const seeds = new Set(tokenRanked.slice(0, 5).map((page) => page.id));
+  return pages.map((page) => ({
+    page,
+    score: page.outLinks.filter((link) => seeds.has(link)).length + page.sourceIds.filter(
+      (source) => tokenRanked.some((seed) => seed.sourceIds.includes(source))
+    ).length
+  })).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).map((item) => item.page);
+}
+function tokenScore(page, query, tokens) {
+  const title = page.title.toLowerCase();
+  const path = page.path.toLowerCase();
+  const body = page.text.toLowerCase();
+  const phrase = query.toLowerCase();
+  let score = 0;
+  if (path.endsWith(`${phrase}.md`) || title === phrase) score += 200;
+  if (title.includes(phrase)) score += 50;
+  if (body.includes(phrase)) score += 20;
+  for (const token of tokens) {
+    if (title.includes(token)) score += 5;
+    if (body.includes(token)) score += 1;
+    if (path.includes(token)) score += 3;
+  }
+  return score;
+}
+function buildSnippet(text, query) {
+  const compact = text.replace(/\s+/g, " ").trim();
+  const idx = compact.toLowerCase().indexOf(query.toLowerCase());
+  if (idx < 0) return compact.slice(0, 180);
+  return compact.slice(Math.max(0, idx - 80), Math.min(compact.length, idx + query.length + 100));
+}
+function reasonsFor(page, query) {
+  const lower = `${page.title}
+${page.text}`.toLowerCase();
+  const reasons = [];
+  if (lower.includes(query.toLowerCase())) reasons.push("phrase");
+  if (page.sourceIds.length > 0) reasons.push("sourced");
+  if (page.outLinks.length > 0) reasons.push("linked");
+  return reasons;
 }
 
 // src/frontmatter.ts
@@ -63,7 +207,7 @@ function parseSimpleYaml(raw) {
 }
 function formatYamlField(key, value) {
   if (Array.isArray(value)) {
-    return [key + ":", ...value.map((item) => `  - ${String(item)}`)];
+    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)}`];
@@ -88,238 +232,6 @@ function normalizeLinkTarget(target) {
   return target.trim().replace(/\.md$/i, "").toLowerCase().replace(/\s+/g, "-");
 }
 
-// src/write-protocol.ts
-var OPENER_LINE = /^---\s*FILE:\s*(.+?)\s*---\s*$/i;
-var CLOSER_LINE = /^---\s*END\s+FILE\s*---\s*$/i;
-var FENCE_LINE = /^\s{0,3}(```+|~~~+)/;
-function isSafeKnowledgePath(path, allowedPrefixes = ["knowledge/"]) {
-  if (typeof path !== "string" || path.trim() === "") return false;
-  if (/[\x00-\x1f]/.test(path)) return false;
-  if (path.startsWith("/") || path.startsWith("\\")) return false;
-  if (/^[a-zA-Z]:/.test(path)) return false;
-  const normalized = path.replace(/\\/g, "/");
-  if (normalized.split("/").some((part) => part === "..")) return false;
-  return allowedPrefixes.some((prefix) => normalized.startsWith(prefix));
-}
-function parseKnowledgeWriteBlocks(text, allowedPrefixes = ["knowledge/"]) {
-  const lines = text.replace(/\r\n/g, "\n").split("\n");
-  const blocks = [];
-  const warnings = [];
-  let i = 0;
-  while (i < lines.length) {
-    const opener = OPENER_LINE.exec(lines[i]);
-    if (!opener) {
-      i++;
-      continue;
-    }
-    const path = opener[1].trim();
-    i++;
-    const contentLines = [];
-    let fenceMarker = null;
-    let fenceLen = 0;
-    let closed = false;
-    while (i < lines.length) {
-      const line = lines[i];
-      const fence = FENCE_LINE.exec(line);
-      if (fence) {
-        const run = fence[1];
-        const char = run[0];
-        if (fenceMarker === null) {
-          fenceMarker = char;
-          fenceLen = run.length;
-        } else if (char === fenceMarker && run.length >= fenceLen) {
-          fenceMarker = null;
-          fenceLen = 0;
-        }
-        contentLines.push(line);
-        i++;
-        continue;
-      }
-      if (fenceMarker === null && CLOSER_LINE.test(line)) {
-        closed = true;
-        i++;
-        break;
-      }
-      contentLines.push(line);
-      i++;
-    }
-    if (!closed) {
-      warnings.push(`FILE block "${path || "(empty)"}" was not closed before end of stream.`);
-      continue;
-    }
-    if (!isSafeKnowledgePath(path, allowedPrefixes)) {
-      warnings.push(`FILE block with unsafe path "${path}" rejected.`);
-      continue;
-    }
-    blocks.push({ path, content: contentLines.join("\n") });
-  }
-  return { blocks, warnings };
-}
-
-// src/adapters.ts
-var textSourceAdapter = {
-  id: "text",
-  canLoad: (input) => Boolean(input.text) || /\.(md|txt|json|csv)$/i.test(input.uri),
-  load: (input) => ({
-    title: input.uri.split("/").pop(),
-    mediaType: mediaTypeFor(input.uri),
-    text: decodeText(input),
-    anchors: anchorsForText(input.uri, decodeText(input)),
-    metadata: input.metadata
-  })
-};
-function mediaTypeFor(uri) {
-  const lower = uri.toLowerCase();
-  if (lower.endsWith(".md")) return "text/markdown";
-  if (lower.endsWith(".txt")) return "text/plain";
-  if (lower.endsWith(".json")) return "application/json";
-  if (lower.endsWith(".csv")) return "text/csv";
-  if (lower.endsWith(".pdf")) return "application/pdf";
-  return "application/octet-stream";
-}
-function decodeText(input) {
-  return input.text ?? (input.bytes ? new TextDecoder().decode(input.bytes).slice(0, 2e5) : void 0);
-}
-function anchorsForText(uri, text) {
-  if (!text) return [];
-  const lines = text.split("\n");
-  const anchors = [{ id: "all", sourceId: "", label: "Full source", lineStart: 1, lineEnd: lines.length }];
-  for (let i = 0; i < lines.length; i += 50) {
-    anchors.push({
-      id: `l${i + 1}`,
-      sourceId: "",
-      label: `${uri}:${i + 1}`,
-      lineStart: i + 1,
-      lineEnd: Math.min(lines.length, i + 50)
-    });
-  }
-  return anchors;
-}
-
-// src/proposals.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { dirname, join } from "path";
-async function applyKnowledgeWriteBlocks(root, proposalText) {
-  const parsed = parseKnowledgeWriteBlocks(proposalText);
-  const written = [];
-  for (const block of parsed.blocks) {
-    const path = join(root, block.path);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, block.content.endsWith("\n") ? block.content : `${block.content}
-`, "utf8");
-    written.push(block.path);
-  }
-  return { written, warnings: parsed.warnings };
-}
-async function applyKnowledgeWriteBlocksFile(root, proposalPath) {
-  return applyKnowledgeWriteBlocks(root, await readFile(proposalPath, "utf8"));
-}
-
-// src/schemas.ts
-import { z } from "zod";
-var SourceAnchorSchema = z.object({
-  id: z.string().min(1),
-  sourceId: z.string().min(1),
-  label: z.string().optional(),
-  page: z.number().int().positive().optional(),
-  lineStart: z.number().int().positive().optional(),
-  lineEnd: z.number().int().positive().optional(),
-  charStart: z.number().int().nonnegative().optional(),
-  charEnd: z.number().int().nonnegative().optional(),
-  timestampMs: z.number().nonnegative().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional()
-});
-var SourceRecordSchema = z.object({
-  id: z.string().min(1),
-  uri: z.string().min(1),
-  title: z.string().optional(),
-  mediaType: z.string().optional(),
-  contentHash: z.string().min(16),
-  text: z.string().optional(),
-  anchors: z.array(SourceAnchorSchema).optional(),
-  metadata: z.record(z.string(), z.unknown()).optional(),
-  createdAt: z.string().min(1)
-});
-var KnowledgePageSchema = z.object({
-  id: z.string().min(1),
-  path: z.string().min(1),
-  title: z.string().min(1),
-  text: z.string(),
-  frontmatter: z.record(z.string(), z.unknown()),
-  sourceIds: z.array(z.string()),
-  tags: z.array(z.string()),
-  outLinks: z.array(z.string())
-});
-var KnowledgeGraphNodeSchema = z.object({
-  id: z.string(),
-  title: z.string(),
-  path: z.string(),
-  tags: z.array(z.string()),
-  sourceIds: z.array(z.string()),
-  outDegree: z.number().int().nonnegative(),
-  inDegree: z.number().int().nonnegative()
-});
-var KnowledgeGraphEdgeSchema = z.object({
-  source: z.string(),
-  target: z.string(),
-  weight: z.number(),
-  reasons: z.array(z.string())
-});
-var KnowledgeIndexSchema = z.object({
-  root: z.string(),
-  generatedAt: z.string(),
-  sources: z.array(SourceRecordSchema),
-  pages: z.array(KnowledgePageSchema),
-  graph: z.object({
-    nodes: z.array(KnowledgeGraphNodeSchema),
-    edges: z.array(KnowledgeGraphEdgeSchema)
-  })
-});
-var KnowledgeEventSchema = z.object({
-  id: z.string().min(1),
-  type: z.enum(["source.added", "proposal.applied", "index.built", "lint.run", "optimization.run", "release.promoted", "release.rejected"]),
-  createdAt: z.string().min(1),
-  actor: z.string().optional(),
-  target: z.string().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional()
-});
-var KnowledgeBaseCandidateSchema = z.object({
-  id: z.string().min(1),
-  units: z.array(z.object({
-    id: z.string().min(1),
-    title: z.string().min(1),
-    text: z.string(),
-    claims: z.array(z.object({
-      id: z.string().min(1),
-      text: z.string().min(1),
-      refs: z.array(z.object({
-        sourceId: z.string().min(1),
-        anchorId: z.string().optional(),
-        quote: z.string().optional()
-      })),
-      confidence: z.number().min(0).max(1).optional(),
-      status: z.enum(["draft", "active", "superseded", "rejected"]).optional(),
-      metadata: z.record(z.string(), z.unknown()).optional()
-    })).optional(),
-    relations: z.array(z.object({
-      sourceId: z.string(),
-      targetId: z.string(),
-      predicate: z.string(),
-      weight: z.number().optional(),
-      metadata: z.record(z.string(), z.unknown()).optional()
-    })).optional(),
-    sourceIds: z.array(z.string()).optional(),
-    tags: z.array(z.string()).optional(),
-    metadata: z.record(z.string(), z.unknown()).optional(),
-    updatedAt: z.string().optional()
-  })),
-  retrievalPolicy: z.string().optional(),
-  synthesisPolicy: z.string().optional(),
-  questionPolicy: z.string().optional(),
-  updatePolicy: z.string().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional()
-});
-
 // src/graph.ts
 function buildKnowledgeGraph(pages) {
   const byId = /* @__PURE__ */ new Map();
@@ -344,7 +256,13 @@ function buildKnowledgeGraph(pages) {
       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"] });
+      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);
     }
@@ -386,17 +304,17 @@ function addSourceOverlapEdges(pages, edges) {
 }
 
 // src/store.ts
-import { mkdir as mkdir2, readFile as readFile2, readdir, stat, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname2, join as join2, relative } from "path";
+import { mkdir, readdir, readFile, stat, writeFile } from "fs/promises";
+import { dirname, join, relative } from "path";
 function layoutFor(root) {
   return {
     root,
-    knowledgeDir: join2(root, "knowledge"),
-    rawSourcesDir: join2(root, "raw", "sources"),
-    sourceRegistryPath: join2(root, ".agent-knowledge", "sources.json"),
-    indexPath: join2(root, "knowledge", "index.md"),
-    logPath: join2(root, "knowledge", "log.md"),
-    cacheDir: join2(root, ".agent-knowledge")
+    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")
   };
 }
 var SCAFFOLD_PAGE_BASENAMES = ["index.md", "log.md"];
@@ -410,12 +328,15 @@ function isScaffoldPath(path) {
 }
 async function initKnowledgeBase(root) {
   const layout = layoutFor(root);
-  await mkdir2(layout.knowledgeDir, { recursive: true });
-  await mkdir2(layout.rawSourcesDir, { recursive: true });
-  await mkdir2(layout.cacheDir, { recursive: true });
+  await mkdir(layout.knowledgeDir, { recursive: true });
+  await mkdir(layout.rawSourcesDir, { recursive: true });
+  await mkdir(layout.cacheDir, { recursive: true });
   await writeIfMissing(layout.indexPath, "# Knowledge Index\n\n");
   await writeIfMissing(layout.logPath, "# Knowledge Log\n\n");
-  await writeIfMissing(layout.sourceRegistryPath, '{\n  "generatedAt": "1970-01-01T00:00:00.000Z",\n  "sources": []\n}\n');
+  await writeIfMissing(
+    layout.sourceRegistryPath,
+    '{\n  "generatedAt": "1970-01-01T00:00:00.000Z",\n  "sources": []\n}\n'
+  );
   return layout;
 }
 async function loadKnowledgePages(root) {
@@ -425,7 +346,7 @@ async function loadKnowledgePages(root) {
   for (const file of files) {
     const rel = relative(root, file).replace(/\\/g, "/");
     if (isScaffoldPath(rel)) continue;
-    const content = await readFile2(file, "utf8");
+    const content = await readFile(file, "utf8");
     const { frontmatter, body } = parseFrontmatter(content);
     const title = stringField(frontmatter.title) ?? firstHeading(body) ?? rel.split("/").pop().replace(/\.md$/, "");
     const sourceIds = arrayField(frontmatter.sources);
@@ -445,15 +366,16 @@ async function loadKnowledgePages(root) {
   return pages;
 }
 async function writeJson(path, value) {
-  await mkdir2(dirname2(path), { recursive: true });
-  await writeFile2(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
 }
 async function writeIfMissing(path, content) {
   try {
     await stat(path);
   } catch {
-    await mkdir2(dirname2(path), { recursive: true });
-    await writeFile2(path, content, "utf8");
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
   }
 }
 async function listMarkdownFiles(root) {
@@ -461,7 +383,7 @@ async function listMarkdownFiles(root) {
     const entries = await readdir(root, { withFileTypes: true });
     const out = [];
     for (const entry of entries) {
-      const full = join2(root, entry.name);
+      const full = join(root, entry.name);
       if (entry.isDirectory()) out.push(...await listMarkdownFiles(full));
       else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
     }
@@ -481,12 +403,12 @@ function firstHeading(body) {
 }
 
 // src/sources.ts
-import { copyFile, mkdir as mkdir3, readFile as readFile3, readdir as readdir2, stat as stat2, writeFile as writeFile3 } from "fs/promises";
-import { basename, dirname as dirname3, join as join3, relative as relative2 } from "path";
+import { copyFile, mkdir as mkdir2, readdir as readdir2, readFile as readFile2, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import { basename, dirname as dirname2, join as join2, relative as relative2 } from "path";
 async function loadSourceRegistry(root) {
   const path = sourceRegistryPath(root);
   try {
-    const parsed = JSON.parse(await readFile3(path, "utf8"));
+    const parsed = JSON.parse(await readFile2(path, "utf8"));
     return {
       generatedAt: typeof parsed.generatedAt === "string" ? parsed.generatedAt : (/* @__PURE__ */ new Date(0)).toISOString(),
       sources: Array.isArray(parsed.sources) ? parsed.sources : []
@@ -497,8 +419,9 @@ async function loadSourceRegistry(root) {
 }
 async function writeSourceRegistry(root, registry) {
   const path = sourceRegistryPath(root);
-  await mkdir3(dirname3(path), { recursive: true });
-  await writeFile3(path, JSON.stringify(registry, null, 2) + "\n", "utf8");
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(path, `${JSON.stringify(registry, null, 2)}
+`, "utf8");
 }
 async function addSourcePath(root, sourcePath, options = {}) {
   const s = await stat2(sourcePath);
@@ -510,18 +433,22 @@ async function addSourcePath(root, sourcePath, options = {}) {
     return out;
   }
   const layout = layoutFor(root);
-  await mkdir3(layout.rawSourcesDir, { recursive: true });
-  const bytes = await readFile3(sourcePath);
+  await mkdir2(layout.rawSourcesDir, { recursive: true });
+  const bytes = await readFile2(sourcePath);
   const contentHash = sha256(bytes.toString("base64"));
   const fileName = basename(sourcePath);
   const adapters = options.adapters ?? [textSourceAdapter];
   const adapter = adapters.find((candidate) => candidate.canLoad({ uri: sourcePath, bytes }));
   const loaded = adapter ? await adapter.load({ uri: sourcePath, bytes }) : {};
   const id = stableId("src", `${contentHash}:${fileName}`);
-  const targetRel = join3("raw", "sources", `${slugify(fileName.replace(/\.[^.]+$/, ""))}-${contentHash.slice(0, 8)}${ext(fileName)}`).replace(/\\/g, "/");
-  const targetAbs = join3(root, targetRel);
+  const targetRel = join2(
+    "raw",
+    "sources",
+    `${slugify(fileName.replace(/\.[^.]+$/, ""))}-${contentHash.slice(0, 8)}${ext(fileName)}`
+  ).replace(/\\/g, "/");
+  const targetAbs = join2(root, targetRel);
   if (options.copyIntoRaw ?? true) {
-    await mkdir3(dirname3(targetAbs), { recursive: true });
+    await mkdir2(dirname2(targetAbs), { recursive: true });
     await copyFile(sourcePath, targetAbs);
   }
   const existing = await loadSourceRegistry(root);
@@ -553,13 +480,19 @@ async function addSourceText(root, input, options = {}) {
   const contentHash = sha256(text);
   const fileName = basename(input.uri) || `${slugify(input.title ?? input.uri)}.txt`;
   const adapterInput = { uri: input.uri, text, metadata: input.metadata };
-  const adapter = (options.adapters ?? [textSourceAdapter]).find((candidate) => candidate.canLoad(adapterInput));
+  const adapter = (options.adapters ?? [textSourceAdapter]).find(
+    (candidate) => candidate.canLoad(adapterInput)
+  );
   const loaded = adapter ? await adapter.load(adapterInput) : {};
   const id = stableId("src", `${contentHash}:${input.uri}`);
-  const targetRel = join3("raw", "sources", `${slugify(fileName.replace(/\.[^.]+$/, ""))}-${contentHash.slice(0, 8)}.txt`).replace(/\\/g, "/");
-  const targetAbs = join3(root, targetRel);
-  await mkdir3(dirname3(targetAbs), { recursive: true });
-  await writeFile3(targetAbs, text.endsWith("\n") ? text : `${text}
+  const targetRel = join2(
+    "raw",
+    "sources",
+    `${slugify(fileName.replace(/\.[^.]+$/, ""))}-${contentHash.slice(0, 8)}.txt`
+  ).replace(/\\/g, "/");
+  const targetAbs = join2(root, targetRel);
+  await mkdir2(dirname2(targetAbs), { recursive: true });
+  await writeFile2(targetAbs, text.endsWith("\n") ? text : `${text}
 `, "utf8");
   const existing = await loadSourceRegistry(root);
   const record = {
@@ -577,138 +510,49 @@ async function addSourceText(root, input, options = {}) {
       ...loaded.metadata ?? {},
       ...input.metadata ?? {},
       originalUri: input.uri,
-      sizeBytes: Buffer.byteLength(text, "utf8")
-    }
-  };
-  await writeSourceRegistry(root, {
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    sources: [record, ...existing.sources.filter((source) => source.id !== id)]
-  });
-  return record;
-}
-function sourceRegistryPath(root) {
-  return join3(layoutFor(root).cacheDir, "sources.json");
-}
-async function listFiles(root) {
-  const entries = await readdir2(root, { withFileTypes: true });
-  const out = [];
-  for (const entry of entries) {
-    const full = join3(root, entry.name);
-    if (entry.isDirectory()) out.push(...await listFiles(full));
-    else if (entry.isFile()) out.push(full);
-  }
-  return out;
-}
-function ext(fileName) {
-  const idx = fileName.lastIndexOf(".");
-  return idx >= 0 ? fileName.slice(idx) : "";
-}
-function mediaTypeFor2(fileName) {
-  const lower = fileName.toLowerCase();
-  if (lower.endsWith(".md")) return "text/markdown";
-  if (lower.endsWith(".txt")) return "text/plain";
-  if (lower.endsWith(".json")) return "application/json";
-  if (lower.endsWith(".csv")) return "text/csv";
-  if (lower.endsWith(".pdf")) return "application/pdf";
-  return "application/octet-stream";
-}
-function textPreview(fileName, bytes) {
-  const mediaType = mediaTypeFor2(fileName);
-  if (!mediaType.startsWith("text/") && mediaType !== "application/json") return void 0;
-  return bytes.toString("utf8").slice(0, 2e5);
-}
-
-// src/search.ts
-var RRF_K = 60;
-var STOP_WORDS = /* @__PURE__ */ new Set(["the", "is", "a", "an", "what", "how", "are", "was", "were", "to", "for", "of", "with", "by", "in", "on", "and"]);
-function searchKnowledge(index, query, limit = 10) {
-  const trimmed = query.trim();
-  if (trimmed === "") return [];
-  const tokenRanked = rankByTokens(index.pages, trimmed);
-  const graphRanked = rankByGraph(index.pages, tokenRanked);
-  const scores = reciprocalRankFusion([tokenRanked.map((p) => p.id), graphRanked.map((p) => p.id)]);
-  const byId = new Map(index.pages.map((page) => [page.id, page]));
-  const ranked = [...scores.entries()].map(([id, score]) => ({ page: byId.get(id), score })).filter((item) => Boolean(item.page)).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).slice(0, limit);
-  const topScore = ranked[0]?.score ?? 0;
-  return ranked.map((item, i) => ({
-    page: item.page,
-    score: item.score,
-    rrfScore: item.score,
-    normalizedScore: topScore > 0 ? item.score / topScore : 0,
-    rank: i + 1,
-    snippet: buildSnippet(item.page.text, trimmed),
-    reasons: reasonsFor(item.page, trimmed)
-  }));
-}
-function tokenizeQuery(query) {
-  const raw = query.toLowerCase().split(/[\s,，。！？、；：""''（）()\-_/\\·~～…]+/).filter((token) => token.length > 1 && !STOP_WORDS.has(token));
-  const tokens = [];
-  for (const token of raw) {
-    if (/[\u4e00-\u9fff\u3400-\u4dbf]/.test(token) && token.length > 2) {
-      const chars = [...token];
-      for (let i = 0; i < chars.length - 1; i++) tokens.push(chars[i] + chars[i + 1]);
-      tokens.push(...chars);
-    }
-    tokens.push(token);
-  }
-  return [...new Set(tokens)];
-}
-function reciprocalRankFusion(rankLists, k = RRF_K) {
-  const scores = /* @__PURE__ */ new Map();
-  for (const list of rankLists) {
-    list.forEach((id, idx) => {
-      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + idx + 1));
-    });
-  }
-  return scores;
-}
-function rankByTokens(pages, query) {
-  const tokens = tokenizeQuery(query);
-  const effective = tokens.length > 0 ? tokens : [query.toLowerCase()];
-  return pages.map((page) => ({ page, score: tokenScore(page, query, effective) })).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).map((item) => item.page);
-}
-function rankByGraph(pages, tokenRanked) {
-  if (tokenRanked.length === 0) return [];
-  const seeds = new Set(tokenRanked.slice(0, 5).map((page) => page.id));
-  return pages.map((page) => ({
-    page,
-    score: page.outLinks.filter((link) => seeds.has(link)).length + page.sourceIds.filter((source) => tokenRanked.some((seed) => seed.sourceIds.includes(source))).length
-  })).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).map((item) => item.page);
-}
-function tokenScore(page, query, tokens) {
-  const title = page.title.toLowerCase();
-  const path = page.path.toLowerCase();
-  const body = page.text.toLowerCase();
-  const phrase = query.toLowerCase();
-  let score = 0;
-  if (path.endsWith(`${phrase}.md`) || title === phrase) score += 200;
-  if (title.includes(phrase)) score += 50;
-  if (body.includes(phrase)) score += 20;
-  for (const token of tokens) {
-    if (title.includes(token)) score += 5;
-    if (body.includes(token)) score += 1;
-    if (path.includes(token)) score += 3;
+      sizeBytes: Buffer.byteLength(text, "utf8")
+    }
+  };
+  await writeSourceRegistry(root, {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    sources: [record, ...existing.sources.filter((source) => source.id !== id)]
+  });
+  return record;
+}
+function sourceRegistryPath(root) {
+  return join2(layoutFor(root).cacheDir, "sources.json");
+}
+async function listFiles(root) {
+  const entries = await readdir2(root, { withFileTypes: true });
+  const out = [];
+  for (const entry of entries) {
+    const full = join2(root, entry.name);
+    if (entry.isDirectory()) out.push(...await listFiles(full));
+    else if (entry.isFile()) out.push(full);
   }
-  return score;
+  return out;
 }
-function buildSnippet(text, query) {
-  const compact = text.replace(/\s+/g, " ").trim();
-  const idx = compact.toLowerCase().indexOf(query.toLowerCase());
-  if (idx < 0) return compact.slice(0, 180);
-  return compact.slice(Math.max(0, idx - 80), Math.min(compact.length, idx + query.length + 100));
+function ext(fileName) {
+  const idx = fileName.lastIndexOf(".");
+  return idx >= 0 ? fileName.slice(idx) : "";
 }
-function reasonsFor(page, query) {
-  const lower = `${page.title}
-${page.text}`.toLowerCase();
-  const reasons = [];
-  if (lower.includes(query.toLowerCase())) reasons.push("phrase");
-  if (page.sourceIds.length > 0) reasons.push("sourced");
-  if (page.outLinks.length > 0) reasons.push("linked");
-  return reasons;
+function mediaTypeFor2(fileName) {
+  const lower = fileName.toLowerCase();
+  if (lower.endsWith(".md")) return "text/markdown";
+  if (lower.endsWith(".txt")) return "text/plain";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".csv")) return "text/csv";
+  if (lower.endsWith(".pdf")) return "application/pdf";
+  return "application/octet-stream";
+}
+function textPreview(fileName, bytes) {
+  const mediaType = mediaTypeFor2(fileName);
+  if (!mediaType.startsWith("text/") && mediaType !== "application/json") return void 0;
+  return bytes.toString("utf8").slice(0, 2e5);
 }
 
 // src/indexer.ts
-import { join as join4 } from "path";
+import { join as join3 } from "path";
 async function buildKnowledgeIndex(root) {
   const [pages, sourceRegistry] = await Promise.all([
     loadKnowledgePages(root),
@@ -725,7 +569,7 @@ async function buildKnowledgeIndex(root) {
 }
 async function writeKnowledgeIndex(root) {
   const index = await buildKnowledgeIndex(root);
-  await writeJson(join4(layoutFor(root).cacheDir, "index.json"), index);
+  await writeJson(join3(layoutFor(root).cacheDir, "index.json"), index);
   return index;
 }
 
@@ -735,7 +579,12 @@ function lintKnowledgeIndex(index) {
   const byTarget = /* @__PURE__ */ new Set();
   const titles = /* @__PURE__ */ new Map();
   const sourceIds = new Set(index.sources.map((source) => source.id));
-  const anchorIds = new Map(index.sources.map((source) => [source.id, new Set((source.anchors ?? []).map((anchor) => anchor.id))]));
+  const anchorIds = new Map(
+    index.sources.map((source) => [
+      source.id,
+      new Set((source.anchors ?? []).map((anchor) => anchor.id))
+    ])
+  );
   const pageIds = /* @__PURE__ */ new Map();
   const sourceHashes = /* @__PURE__ */ new Map();
   for (const page of index.pages) {
@@ -747,54 +596,111 @@ function lintKnowledgeIndex(index) {
     titles.set(titleKey, [...titles.get(titleKey) ?? [], page.path]);
   }
   for (const source of index.sources) {
-    sourceHashes.set(source.contentHash, [...sourceHashes.get(source.contentHash) ?? [], source.id]);
+    sourceHashes.set(source.contentHash, [
+      ...sourceHashes.get(source.contentHash) ?? [],
+      source.id
+    ]);
   }
   const inbound = /* @__PURE__ */ new Map();
   for (const page of index.pages) inbound.set(page.id, 0);
   for (const page of index.pages) {
     if (page.outLinks.length === 0 && !isStructural(page.path)) {
-      findings.push({ type: "no-outlinks", severity: "info", page: page.path, message: "Page has no wikilinks to other knowledge pages." });
+      findings.push({
+        type: "no-outlinks",
+        severity: "info",
+        page: page.path,
+        message: "Page has no wikilinks to other knowledge pages."
+      });
     }
     for (const link of page.outLinks) {
       if (!byTarget.has(normalizeLinkTarget(link))) {
-        findings.push({ type: "broken-link", severity: "warning", page: page.path, message: `Broken wikilink [[${link}]].` });
+        findings.push({
+          type: "broken-link",
+          severity: "warning",
+          page: page.path,
+          message: `Broken wikilink [[${link}]].`
+        });
       }
     }
   }
-  for (const edge of index.graph.edges) inbound.set(edge.target, (inbound.get(edge.target) ?? 0) + 1);
+  for (const edge of index.graph.edges)
+    inbound.set(edge.target, (inbound.get(edge.target) ?? 0) + 1);
   for (const page of index.pages) {
     if (!isStructural(page.path) && (inbound.get(page.id) ?? 0) === 0) {
-      findings.push({ type: "orphan", severity: "info", page: page.path, message: "No other page links to this page." });
+      findings.push({
+        type: "orphan",
+        severity: "info",
+        page: page.path,
+        message: "No other page links to this page."
+      });
     }
     if (/\bclaim\b/i.test(page.text) && page.sourceIds.length === 0) {
-      findings.push({ type: "uncited-claim", severity: "warning", page: page.path, message: "Page appears to contain claims but has no sources frontmatter." });
+      findings.push({
+        type: "uncited-claim",
+        severity: "warning",
+        page: page.path,
+        message: "Page appears to contain claims but has no sources frontmatter."
+      });
     }
     for (const sourceId of page.sourceIds) {
       if (!sourceIds.has(sourceId)) {
-        findings.push({ type: "missing-source", severity: "error", page: page.path, message: `Page cites unknown source "${sourceId}".`, metadata: { sourceId } });
+        findings.push({
+          type: "missing-source",
+          severity: "error",
+          page: page.path,
+          message: `Page cites unknown source "${sourceId}".`,
+          metadata: { sourceId }
+        });
       }
     }
     for (const ref of extractSourceRefs(page.text)) {
       if (!sourceIds.has(ref.sourceId)) {
-        findings.push({ type: "missing-source", severity: "error", page: page.path, message: `Page cites unknown source "${ref.sourceId}".`, metadata: ref });
+        findings.push({
+          type: "missing-source",
+          severity: "error",
+          page: page.path,
+          message: `Page cites unknown source "${ref.sourceId}".`,
+          metadata: ref
+        });
       } else if (ref.anchorId && !anchorIds.get(ref.sourceId)?.has(ref.anchorId)) {
-        findings.push({ type: "missing-source", severity: "error", page: page.path, message: `Page cites unknown source anchor "${ref.sourceId}#${ref.anchorId}".`, metadata: ref });
+        findings.push({
+          type: "missing-source",
+          severity: "error",
+          page: page.path,
+          message: `Page cites unknown source anchor "${ref.sourceId}#${ref.anchorId}".`,
+          metadata: ref
+        });
       }
     }
   }
   for (const [title, paths] of titles) {
     if (title && paths.length > 1) {
-      findings.push({ type: "duplicate-title", severity: "warning", message: `Duplicate title "${title}" in ${paths.join(", ")}.`, metadata: { paths } });
+      findings.push({
+        type: "duplicate-title",
+        severity: "warning",
+        message: `Duplicate title "${title}" in ${paths.join(", ")}.`,
+        metadata: { paths }
+      });
     }
   }
   for (const [id, paths] of pageIds) {
     if (id && paths.length > 1) {
-      findings.push({ type: "duplicate-page-id", severity: "error", message: `Duplicate page id "${id}" in ${paths.join(", ")}.`, metadata: { paths } });
+      findings.push({
+        type: "duplicate-page-id",
+        severity: "error",
+        message: `Duplicate page id "${id}" in ${paths.join(", ")}.`,
+        metadata: { paths }
+      });
     }
   }
   for (const [hash, ids] of sourceHashes) {
     if (hash && ids.length > 1) {
-      findings.push({ type: "duplicate-source-hash", severity: "warning", message: `Duplicate source content hash across ${ids.join(", ")}.`, metadata: { sourceIds: ids } });
+      findings.push({
+        type: "duplicate-source-hash",
+        severity: "warning",
+        message: `Duplicate source content hash across ${ids.join(", ")}.`,
+        metadata: { sourceIds: ids }
+      });
     }
   }
   return findings;
@@ -826,7 +732,12 @@ function inspectKnowledgeIndex(index, options = {}) {
     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 })),
+    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
   };
@@ -842,9 +753,21 @@ function stringMetadata(metadata, key) {
   return typeof value === "string" ? value : void 0;
 }
 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 }));
+  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,
@@ -855,6 +778,219 @@ function explainKnowledgeTarget(index, target) {
   };
 }
 
+// src/write-protocol.ts
+var OPENER_LINE = /^---\s*FILE:\s*(.+?)\s*---\s*$/i;
+var CLOSER_LINE = /^---\s*END\s+FILE\s*---\s*$/i;
+var FENCE_LINE = /^\s{0,3}(```+|~~~+)/;
+function isSafeKnowledgePath(path, allowedPrefixes = ["knowledge/"]) {
+  if (typeof path !== "string" || path.trim() === "") return false;
+  const controlRangeRegex = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(31)}]`);
+  if (controlRangeRegex.test(path)) return false;
+  if (path.startsWith("/") || path.startsWith("\\")) return false;
+  if (/^[a-zA-Z]:/.test(path)) return false;
+  const normalized = path.replace(/\\/g, "/");
+  if (normalized.split("/").some((part) => part === "..")) return false;
+  return allowedPrefixes.some((prefix) => normalized.startsWith(prefix));
+}
+function parseKnowledgeWriteBlocks(text, allowedPrefixes = ["knowledge/"]) {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const blocks = [];
+  const warnings = [];
+  let i = 0;
+  while (i < lines.length) {
+    const opener = OPENER_LINE.exec(lines[i]);
+    if (!opener) {
+      i++;
+      continue;
+    }
+    const path = opener[1].trim();
+    i++;
+    const contentLines = [];
+    let fenceMarker = null;
+    let fenceLen = 0;
+    let closed = false;
+    while (i < lines.length) {
+      const line = lines[i];
+      const fence = FENCE_LINE.exec(line);
+      if (fence) {
+        const run = fence[1];
+        const char = run[0];
+        if (fenceMarker === null) {
+          fenceMarker = char;
+          fenceLen = run.length;
+        } else if (char === fenceMarker && run.length >= fenceLen) {
+          fenceMarker = null;
+          fenceLen = 0;
+        }
+        contentLines.push(line);
+        i++;
+        continue;
+      }
+      if (fenceMarker === null && CLOSER_LINE.test(line)) {
+        closed = true;
+        i++;
+        break;
+      }
+      contentLines.push(line);
+      i++;
+    }
+    if (!closed) {
+      warnings.push(`FILE block "${path || "(empty)"}" was not closed before end of stream.`);
+      continue;
+    }
+    if (!isSafeKnowledgePath(path, allowedPrefixes)) {
+      warnings.push(`FILE block with unsafe path "${path}" rejected.`);
+      continue;
+    }
+    blocks.push({ path, content: contentLines.join("\n") });
+  }
+  return { blocks, warnings };
+}
+
+// src/proposals.ts
+import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname3, join as join4 } from "path";
+async function applyKnowledgeWriteBlocks(root, proposalText) {
+  const parsed = parseKnowledgeWriteBlocks(proposalText);
+  const written = [];
+  for (const block of parsed.blocks) {
+    const path = join4(root, block.path);
+    await mkdir3(dirname3(path), { recursive: true });
+    await writeFile3(
+      path,
+      block.content.endsWith("\n") ? block.content : `${block.content}
+`,
+      "utf8"
+    );
+    written.push(block.path);
+  }
+  return { written, warnings: parsed.warnings };
+}
+async function applyKnowledgeWriteBlocksFile(root, proposalPath) {
+  return applyKnowledgeWriteBlocks(root, await readFile3(proposalPath, "utf8"));
+}
+
+// src/schemas.ts
+import { z } from "zod";
+var SourceAnchorSchema = z.object({
+  id: z.string().min(1),
+  sourceId: z.string().min(1),
+  label: z.string().optional(),
+  page: z.number().int().positive().optional(),
+  lineStart: z.number().int().positive().optional(),
+  lineEnd: z.number().int().positive().optional(),
+  charStart: z.number().int().nonnegative().optional(),
+  charEnd: z.number().int().nonnegative().optional(),
+  timestampMs: z.number().nonnegative().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+var SourceRecordSchema = z.object({
+  id: z.string().min(1),
+  uri: z.string().min(1),
+  title: z.string().optional(),
+  mediaType: z.string().optional(),
+  contentHash: z.string().min(16),
+  text: z.string().optional(),
+  anchors: z.array(SourceAnchorSchema).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  createdAt: z.string().min(1)
+});
+var KnowledgePageSchema = z.object({
+  id: z.string().min(1),
+  path: z.string().min(1),
+  title: z.string().min(1),
+  text: z.string(),
+  frontmatter: z.record(z.string(), z.unknown()),
+  sourceIds: z.array(z.string()),
+  tags: z.array(z.string()),
+  outLinks: z.array(z.string())
+});
+var KnowledgeGraphNodeSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  path: z.string(),
+  tags: z.array(z.string()),
+  sourceIds: z.array(z.string()),
+  outDegree: z.number().int().nonnegative(),
+  inDegree: z.number().int().nonnegative()
+});
+var KnowledgeGraphEdgeSchema = z.object({
+  source: z.string(),
+  target: z.string(),
+  weight: z.number(),
+  reasons: z.array(z.string())
+});
+var KnowledgeIndexSchema = z.object({
+  root: z.string(),
+  generatedAt: z.string(),
+  sources: z.array(SourceRecordSchema),
+  pages: z.array(KnowledgePageSchema),
+  graph: z.object({
+    nodes: z.array(KnowledgeGraphNodeSchema),
+    edges: z.array(KnowledgeGraphEdgeSchema)
+  })
+});
+var KnowledgeEventSchema = z.object({
+  id: z.string().min(1),
+  type: z.enum([
+    "source.added",
+    "proposal.applied",
+    "index.built",
+    "lint.run",
+    "optimization.run",
+    "release.promoted",
+    "release.rejected"
+  ]),
+  createdAt: z.string().min(1),
+  actor: z.string().optional(),
+  target: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+var KnowledgeBaseCandidateSchema = z.object({
+  id: z.string().min(1),
+  units: z.array(
+    z.object({
+      id: z.string().min(1),
+      title: z.string().min(1),
+      text: z.string(),
+      claims: z.array(
+        z.object({
+          id: z.string().min(1),
+          text: z.string().min(1),
+          refs: z.array(
+            z.object({
+              sourceId: z.string().min(1),
+              anchorId: z.string().optional(),
+              quote: z.string().optional()
+            })
+          ),
+          confidence: z.number().min(0).max(1).optional(),
+          status: z.enum(["draft", "active", "superseded", "rejected"]).optional(),
+          metadata: z.record(z.string(), z.unknown()).optional()
+        })
+      ).optional(),
+      relations: z.array(
+        z.object({
+          sourceId: z.string(),
+          targetId: z.string(),
+          predicate: z.string(),
+          weight: z.number().optional(),
+          metadata: z.record(z.string(), z.unknown()).optional()
+        })
+      ).optional(),
+      sourceIds: z.array(z.string()).optional(),
+      tags: z.array(z.string()).optional(),
+      metadata: z.record(z.string(), z.unknown()).optional(),
+      updatedAt: z.string().optional()
+    })
+  ),
+  retrievalPolicy: z.string().optional(),
+  synthesisPolicy: z.string().optional(),
+  questionPolicy: z.string().optional(),
+  updatePolicy: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+
 // src/validate.ts
 function validateKnowledgeIndex(index, options = {}) {
   const findings = [...lintKnowledgeIndex(index)];
@@ -886,28 +1022,16 @@ function isStructuralPage(path) {
 }
 
 export {
-  sha256,
-  slugify,
-  stableId,
+  textSourceAdapter,
+  mediaTypeFor,
+  searchKnowledge,
+  tokenizeQuery,
+  reciprocalRankFusion,
   parseFrontmatter,
   formatFrontmatter,
   WIKILINK_REGEX,
   extractWikilinks,
   normalizeLinkTarget,
-  isSafeKnowledgePath,
-  parseKnowledgeWriteBlocks,
-  textSourceAdapter,
-  mediaTypeFor,
-  applyKnowledgeWriteBlocks,
-  applyKnowledgeWriteBlocksFile,
-  SourceAnchorSchema,
-  SourceRecordSchema,
-  KnowledgePageSchema,
-  KnowledgeGraphNodeSchema,
-  KnowledgeGraphEdgeSchema,
-  KnowledgeIndexSchema,
-  KnowledgeEventSchema,
-  KnowledgeBaseCandidateSchema,
   buildKnowledgeGraph,
   layoutFor,
   SCAFFOLD_PAGE_BASENAMES,
@@ -920,14 +1044,23 @@ export {
   addSourcePath,
   addSourceText,
   sourceRegistryPath,
-  searchKnowledge,
-  tokenizeQuery,
-  reciprocalRankFusion,
   buildKnowledgeIndex,
   writeKnowledgeIndex,
   lintKnowledgeIndex,
   inspectKnowledgeIndex,
   explainKnowledgeTarget,
+  isSafeKnowledgePath,
+  parseKnowledgeWriteBlocks,
+  applyKnowledgeWriteBlocks,
+  applyKnowledgeWriteBlocksFile,
+  SourceAnchorSchema,
+  SourceRecordSchema,
+  KnowledgePageSchema,
+  KnowledgeGraphNodeSchema,
+  KnowledgeGraphEdgeSchema,
+  KnowledgeIndexSchema,
+  KnowledgeEventSchema,
+  KnowledgeBaseCandidateSchema,
   validateKnowledgeIndex
 };
-//# sourceMappingURL=chunk-JLCQ6O7W.js.map
+//# sourceMappingURL=chunk-HKYD765Q.js.map