@tangle-network/agent-knowledge 1.12.1 → 2.0.1

package/dist/chunk-R7ADUA44.js

@@ -0,0 +1,2119 @@
+import {
+  searchKnowledge
+} from "./chunk-DQ3PDMDP.js";
+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 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/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";
+import { dirname as dirname2, join as join2, resolve as resolve3 } from "path";
+import { check, lock } from "proper-lockfile";
+
+// src/durable-fs.ts
+import { randomUUID } from "crypto";
+import { constants } from "fs";
+import {
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  realpath,
+  rename,
+  rm
+} from "fs/promises";
+import { basename, dirname, isAbsolute, resolve } from "path";
+var DIRECTORY_FLAGS = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+var CREATE_FILE_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+var READ_FILE_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW;
+async function writeFileDurable(path, data, options = {}) {
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true });
+  await withDirectoryHandle(directory, async (handle, anchoredDirectory) => {
+    const target = resolve(anchoredDirectory, basename(path));
+    const existingMode = await regularFileModeOrUndefined(target);
+    const requestedMode = options.mode ?? existingMode;
+    const temporary = resolve(anchoredDirectory, `.${basename(path)}.${randomUUID()}.tmp`);
+    let temporaryHandle;
+    try {
+      temporaryHandle = await open(temporary, CREATE_FILE_FLAGS, requestedMode ?? 438);
+      await temporaryHandle.writeFile(
+        data,
+        options.encoding === void 0 ? void 0 : { encoding: options.encoding }
+      );
+      if (requestedMode !== void 0) await temporaryHandle.chmod(requestedMode);
+      await temporaryHandle.sync();
+      await temporaryHandle.close();
+      temporaryHandle = void 0;
+      await rename(temporary, target);
+      await syncDirectoryHandle(handle);
+    } finally {
+      await temporaryHandle?.close().catch(() => void 0);
+      await rm(temporary, { force: true }).catch(() => void 0);
+    }
+  });
+}
+async function writeJsonDurable(path, value) {
+  await writeFileDurable(path, `${JSON.stringify(value, null, 2)}
+`, { encoding: "utf8" });
+}
+async function writeFileDurableWithinRoot(root, relativePath, data, options = {}) {
+  await withSafeDescendant(root, relativePath, (path) => writeFileDurable(path, data, options));
+}
+async function writeJsonDurableWithinRoot(root, relativePath, value) {
+  await writeFileDurableWithinRoot(root, relativePath, `${JSON.stringify(value, null, 2)}
+`, {
+    encoding: "utf8"
+  });
+}
+async function renameDurable(source, target) {
+  const sourceDir = dirname(source);
+  const targetDir = dirname(target);
+  await withDirectoryHandle(sourceDir, async (sourceHandle, anchoredSourceDir) => {
+    await withDirectoryHandle(targetDir, async (targetHandle, anchoredTargetDir) => {
+      await rename(
+        resolve(anchoredSourceDir, basename(source)),
+        resolve(anchoredTargetDir, basename(target))
+      );
+      await syncDirectoryHandle(sourceHandle);
+      if (targetDir !== sourceDir) await syncDirectoryHandle(targetHandle);
+    });
+  });
+}
+async function removeDurable(path) {
+  await withDirectoryHandle(dirname(path), async (handle, anchoredDirectory) => {
+    await rm(resolve(anchoredDirectory, basename(path)), { force: true });
+    await syncDirectoryHandle(handle);
+  });
+}
+async function syncDirectory(path) {
+  await withDirectoryHandle(path, syncDirectoryHandle);
+}
+async function withSafeDescendant(root, relativePath, use) {
+  const normalized = normalizeRelativePath(relativePath);
+  const parts = normalized.split("/");
+  const filename = parts.pop();
+  const directory = await openSafeDirectoryTree(root, parts.join("/"), true);
+  try {
+    const target = resolve(anchoredDirectoryPath(directory.handle, directory.path), filename);
+    await regularFileModeOrUndefined(target);
+    return await use(target);
+  } finally {
+    await directory.handle.close();
+  }
+}
+async function withSafeDirectory(root, relativePath, create, use) {
+  const directory = await openSafeDirectoryTree(root, relativePath, create);
+  try {
+    return await use(anchoredDirectoryPath(directory.handle, directory.path));
+  } finally {
+    await directory.handle.close();
+  }
+}
+async function readRegularFileNoFollow(path) {
+  let handle;
+  try {
+    handle = await open(path, READ_FILE_FLAGS);
+    const entry = await handle.stat();
+    if (!entry.isFile()) throw new Error(`knowledge path is not a regular file: ${path}`);
+    return { bytes: await handle.readFile(), mode: entry.mode & 511 };
+  } catch (error) {
+    const code = error?.code;
+    if (code === "ELOOP" || code === "ENOTDIR") {
+      throw new Error(`knowledge path is not a regular file: ${path}`, { cause: error });
+    }
+    throw error;
+  } finally {
+    await handle?.close().catch(() => void 0);
+  }
+}
+async function readRegularFileWithinRoot(root, relativePath) {
+  const normalized = normalizeRelativePath(relativePath);
+  const parts = normalized.split("/");
+  const filename = parts.pop();
+  const directory = await openSafeDirectoryTree(root, parts.join("/"), false);
+  try {
+    return await readRegularFileNoFollow(
+      resolve(anchoredDirectoryPath(directory.handle, directory.path), filename)
+    );
+  } finally {
+    await directory.handle.close();
+  }
+}
+async function listRegularFilesWithinRoot(root, relativeDirectory) {
+  const normalized = normalizeRelativePath(relativeDirectory);
+  return withSafeDirectory(
+    root,
+    normalized,
+    false,
+    (directory) => listRegularFilesFromOpenDirectory(directory, normalized)
+  );
+}
+function isMissingFile(error) {
+  return error?.code === "ENOENT";
+}
+async function withDirectoryHandle(path, use) {
+  const handle = await openDirectory(path);
+  try {
+    return await use(handle, anchoredDirectoryPath(handle, path));
+  } finally {
+    await handle.close();
+  }
+}
+async function listRegularFilesFromOpenDirectory(directory, relativeDirectory) {
+  const out = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const relativePath = `${relativeDirectory}/${entry.name}`;
+    if (entry.isDirectory()) {
+      out.push(
+        ...await withSafeDirectory(
+          directory,
+          entry.name,
+          false,
+          (child) => listRegularFilesFromOpenDirectory(child, relativePath)
+        )
+      );
+    } else if (entry.isFile()) {
+      out.push({
+        path: relativePath,
+        ...await readRegularFileNoFollow(resolve(directory, entry.name))
+      });
+    } else {
+      throw new Error(`knowledge tree contains an unsupported filesystem entry: ${relativePath}`);
+    }
+  }
+  return out;
+}
+async function openSafeDirectoryTree(root, relativePath, create) {
+  if (create) await mkdir(root, { recursive: true });
+  const resolvedRoot = isKernelAnchoredPath(root) ? root : await realpath(root);
+  const normalized = relativePath === "" ? "" : normalizeRelativePath(relativePath);
+  let currentPath = resolvedRoot;
+  let currentHandle = await openDirectory(resolvedRoot);
+  try {
+    for (const part of normalized.split("/").filter(Boolean)) {
+      const anchoredParent = anchoredDirectoryPath(currentHandle, currentPath);
+      const childPath = resolve(anchoredParent, part);
+      let childHandle;
+      try {
+        childHandle = await openDirectory(childPath);
+      } catch (error) {
+        if (!create || !isMissingFile(error)) throw unsafeDirectoryError(childPath, error);
+        let created = false;
+        try {
+          await mkdir(childPath);
+          created = true;
+        } catch (mkdirError) {
+          if (mkdirError?.code !== "EEXIST") throw mkdirError;
+        }
+        childHandle = await openDirectory(childPath).catch((openError) => {
+          throw unsafeDirectoryError(childPath, openError);
+        });
+        if (created) await syncDirectoryHandle(currentHandle);
+      }
+      await currentHandle.close();
+      currentHandle = childHandle;
+      currentPath = resolve(currentPath, part);
+    }
+    return { handle: currentHandle, path: currentPath };
+  } catch (error) {
+    await currentHandle.close().catch(() => void 0);
+    throw error;
+  }
+}
+async function openDirectory(path) {
+  const isKernelDescriptor = /^\/proc\/self\/fd\/\d+$/.test(path);
+  if (!isKernelDescriptor) {
+    const entry2 = await lstat(path);
+    if (entry2.isSymbolicLink() || !entry2.isDirectory()) {
+      throw new Error(`knowledge path has an unsafe directory: ${path}`);
+    }
+  }
+  const flags = isKernelDescriptor ? constants.O_RDONLY | constants.O_DIRECTORY : DIRECTORY_FLAGS;
+  const handle = await open(path, flags);
+  const entry = await handle.stat();
+  if (!entry.isDirectory()) {
+    await handle.close();
+    throw new Error(`knowledge path has an unsafe directory: ${path}`);
+  }
+  return handle;
+}
+function isKernelAnchoredPath(path) {
+  return process.platform === "linux" && /^\/proc\/self\/fd\/\d+(?:\/|$)/.test(path);
+}
+function anchoredDirectoryPath(handle, fallback) {
+  return process.platform === "linux" ? `/proc/self/fd/${handle.fd}` : fallback;
+}
+async function regularFileModeOrUndefined(path) {
+  try {
+    const entry = await lstat(path);
+    if (entry.isSymbolicLink() || !entry.isFile()) {
+      throw new Error(`knowledge path is not a regular file: ${path}`);
+    }
+    return entry.mode & 511;
+  } catch (error) {
+    if (isMissingFile(error)) return void 0;
+    throw error;
+  }
+}
+async function syncDirectoryHandle(handle) {
+  if (process.platform === "win32") return;
+  await handle.sync();
+}
+function unsafeDirectoryError(path, cause) {
+  const code = cause?.code;
+  if (code === "ELOOP" || code === "ENOTDIR") {
+    return new Error(`knowledge path has an unsafe directory: ${path}`, { cause });
+  }
+  return cause instanceof Error ? cause : new Error(`could not open knowledge directory: ${path}`);
+}
+function normalizeRelativePath(path) {
+  if (path.length === 0 || isAbsolute(path)) {
+    throw new Error(`knowledge path must be a non-empty relative path: ${path}`);
+  }
+  const normalized = path.replace(/\\/g, "/");
+  if (normalized.split("/").some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`knowledge path contains an unsafe segment: ${path}`);
+  }
+  return normalized;
+}
+
+// src/file-transaction.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { mkdtemp, readdir as readdir2, rm as rm2 } from "fs/promises";
+import { join, relative, resolve as resolve2, sep } from "path";
+import { contentHash } from "@tangle-network/agent-eval";
+import { z } from "zod";
+var digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
+var fileModeSchema = z.number().int().min(0).max(511);
+var DEFAULT_FILE_MODE = 420;
+var transactionEntrySchema = z.object({
+  index: z.number().int().nonnegative(),
+  path: z.string().min(1),
+  beforeHash: digestSchema.nullable(),
+  afterHash: digestSchema.nullable(),
+  beforeMode: fileModeSchema.optional(),
+  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),
+  createdAt: z.string().min(1),
+  entries: z.array(transactionEntrySchema).min(1)
+}).strict();
+var transactionDirectionSchema = z.object({
+  schemaVersion: z.literal(1),
+  transactionId: z.string().uuid(),
+  direction: z.literal("rollback")
+}).strict();
+function knowledgeFileTransactionPlanHash(entries) {
+  const normalized = entries.map((entry) => normalizePlanEntry(entry)).sort((left, right) => left.path.localeCompare(right.path));
+  if (new Set(normalized.map((entry) => entry.path)).size !== normalized.length) {
+    throw new Error("knowledge transaction plan repeats a path");
+  }
+  return contentHash(normalized);
+}
+async function prepareKnowledgeFileTransaction(input) {
+  if (input.mutations.length === 0) throw new Error("knowledge file transaction has no mutations");
+  return withTransactionRoot(input.root, input.transactionRoot, true, async (transactionRoot) => {
+    const activeTransactions = await activeTransactionDirectoryNames(transactionRoot);
+    if (activeTransactions.length > 0) {
+      throw new Error(
+        `knowledge file transaction is already active: ${activeTransactions.join(", ")}`
+      );
+    }
+    const paths = /* @__PURE__ */ new Set();
+    const prepared = await Promise.all(
+      input.mutations.map(async (mutation, index) => {
+        const path = assertKnowledgeMutationPath(mutation.path);
+        if (paths.has(path)) throw new Error(`knowledge file transaction repeats path: ${path}`);
+        if (mutation.content === null && mutation.mode !== void 0) {
+          throw new Error(`deleted knowledge file cannot declare a mode: ${path}`);
+        }
+        paths.add(path);
+        const before = await withSafeDescendant(input.root, path, readRegularFile);
+        const after = mutation.content === null ? null : Buffer.isBuffer(mutation.content) ? mutation.content : Buffer.from(mutation.content, "utf8");
+        const afterMode = after ? fileModeSchema.parse(mutation.mode ?? before?.mode ?? DEFAULT_FILE_MODE) : void 0;
+        if (!input.includeUnchanged && sameBytes(before?.bytes ?? null, after) && before?.mode === afterMode) {
+          return null;
+        }
+        return {
+          entry: {
+            index,
+            path,
+            beforeHash: before ? hashBytes(before.bytes) : null,
+            afterHash: after ? hashBytes(after) : null,
+            ...before ? { beforeMode: before.mode } : {},
+            ...afterMode === void 0 ? {} : { afterMode }
+          },
+          before: before?.bytes ?? null,
+          after
+        };
+      })
+    );
+    const changed = prepared.filter((entry) => entry !== null);
+    if (changed.length === 0) return null;
+    const preparationDir = await mkdtemp(join(transactionRoot, "prepare-"));
+    let activated = false;
+    try {
+      for (const item of changed) {
+        if (item.before) {
+          await writeFileDurable(
+            snapshotPath(preparationDir, "before", item.entry.index),
+            item.before
+          );
+        }
+        if (item.after) {
+          await writeFileDurable(
+            snapshotPath(preparationDir, "after", item.entry.index),
+            item.after
+          );
+        }
+      }
+      const transaction = transactionSchema.parse({
+        schemaVersion: 1,
+        kind: "knowledge-file-transaction",
+        transactionId: randomUUID2(),
+        purpose: input.purpose,
+        createdAt: (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+        entries: changed.map((item) => item.entry)
+      });
+      await writeJsonDurable(join(preparationDir, "transaction.json"), transaction);
+      const activeDir = join(
+        transactionRoot,
+        activeTransactionDirectoryName(transaction.transactionId)
+      );
+      await renameDurable(preparationDir, activeDir);
+      activated = true;
+      const competingTransactions = await activeTransactionDirectoryNames(transactionRoot);
+      if (competingTransactions.length > 1) {
+        await rm2(activeDir, { recursive: true, force: true });
+        await syncDirectory(transactionRoot);
+        throw new Error("multiple knowledge file transactions became active concurrently");
+      }
+      return transaction;
+    } finally {
+      if (!activated) await rm2(preparationDir, { recursive: true, force: true });
+    }
+  });
+}
+async function commitKnowledgeFileMutations(input) {
+  if (await loadKnowledgeFileTransaction({
+    root: input.root,
+    transactionRoot: input.transactionRoot
+  })) {
+    throw new Error("recover the pending knowledge transaction before planning another write");
+  }
+  const transaction = await prepareKnowledgeFileTransaction({
+    root: input.root,
+    transactionRoot: input.transactionRoot,
+    purpose: input.purpose,
+    mutations: input.mutations,
+    now: input.now
+  });
+  if (!transaction) return false;
+  input.assertOwned?.();
+  await applyKnowledgeFileTransaction({
+    root: input.root,
+    transactionRoot: input.transactionRoot,
+    transaction,
+    beforeCommit: input.assertOwned
+  });
+  await finishKnowledgeFileTransaction({
+    root: input.root,
+    transactionRoot: input.transactionRoot,
+    transaction,
+    assertOwned: input.assertOwned
+  });
+  return true;
+}
+async function recoverKnowledgeFileTransaction(input) {
+  const pending = await inspectKnowledgeFileTransaction({
+    root: input.root,
+    transactionRoot: input.transactionRoot
+  });
+  if (!pending) return false;
+  const { transaction, direction } = pending;
+  if (transaction.purpose !== input.expectedPurpose) {
+    throw new Error(`knowledge transaction '${transaction.purpose}' requires its owner to resume`);
+  }
+  input.validate?.(transaction);
+  input.assertOwned?.();
+  if (input.direction === "apply" && direction === "rollback") {
+    throw new Error(`knowledge transaction '${transaction.transactionId}' is already rolling back`);
+  }
+  const requestedDirection = input.direction ?? direction;
+  if (requestedDirection === "rollback") {
+    await rollbackKnowledgeFileTransaction({
+      root: input.root,
+      transactionRoot: input.transactionRoot,
+      transaction,
+      beforeCommit: input.assertOwned
+    });
+  } else {
+    await applyKnowledgeFileTransaction({
+      root: input.root,
+      transactionRoot: input.transactionRoot,
+      transaction,
+      beforeCommit: input.assertOwned
+    });
+  }
+  await finishKnowledgeFileTransaction({
+    root: input.root,
+    transactionRoot: input.transactionRoot,
+    transaction,
+    assertOwned: input.assertOwned
+  });
+  return true;
+}
+async function loadKnowledgeFileTransaction(input) {
+  return (await inspectKnowledgeFileTransaction(input))?.transaction ?? null;
+}
+async function inspectKnowledgeFileTransaction(input) {
+  return loadKnowledgeFileTransactionState(input);
+}
+async function applyKnowledgeFileTransaction(input) {
+  const transaction = transactionSchema.parse(input.transaction);
+  assertTransactionEntries(transaction);
+  await withTransactionDirectory(
+    input.root,
+    input.transactionRoot,
+    transaction,
+    async (transactionDir) => {
+      await assertActiveTransaction(transactionDir, transaction);
+      if (await readTransactionDirection(transactionDir, transaction) === "rollback") {
+        throw new Error(`knowledge transaction '${transaction.transactionId}' is rolling back`);
+      }
+      for (const entry of transaction.entries) {
+        await withSafeDescendant(input.root, entry.path, async (target) => {
+          const current = await readRegularFile(target);
+          if (fileMatches(current, entry.afterHash, entry.afterMode)) return;
+          if (!fileMatches(current, entry.beforeHash, entry.beforeMode)) {
+            throw new Error(`knowledge file changed outside transaction: ${entry.path}`);
+          }
+          await input.beforeCommit?.(entry);
+          if (entry.afterHash === null) {
+            await removeDurable(target);
+            return;
+          }
+          const after = (await readRegularFileNoFollow(snapshotPath(transactionDir, "after", entry.index))).bytes;
+          if (hashBytes(after) !== entry.afterHash) {
+            throw new Error(`knowledge transaction snapshot changed: ${entry.path}`);
+          }
+          await writeFileDurable(target, after, { mode: entry.afterMode });
+        });
+      }
+      await assertKnowledgeFileTransactionApplied(input.root, transaction);
+    }
+  );
+}
+async function assertKnowledgeFileTransactionApplied(root, transaction) {
+  for (const entry of transaction.entries) {
+    await withSafeDescendant(root, entry.path, async (target) => {
+      const current = await readRegularFile(target);
+      if (!fileMatches(current, entry.afterHash, entry.afterMode)) {
+        throw new Error(`knowledge file transaction did not commit: ${entry.path}`);
+      }
+    });
+  }
+}
+async function finishKnowledgeFileTransaction(input) {
+  const transaction = transactionSchema.parse(input.transaction);
+  assertTransactionEntries(transaction);
+  await withTransactionRoot(input.root, input.transactionRoot, false, async (transactionRoot) => {
+    const activeName = activeTransactionDirectoryName(transaction.transactionId);
+    await withTransactionDirectory(
+      input.root,
+      input.transactionRoot,
+      transaction,
+      async (transactionDir) => {
+        await assertActiveTransaction(transactionDir, transaction);
+        input.assertOwned?.();
+        const direction = await readTransactionDirection(transactionDir, transaction);
+        await assertKnowledgeFileTransactionTerminal(input.root, transaction, direction);
+        await withSafeDirectory(transactionRoot, activeName, false, async (currentDir) => {
+          await assertActiveTransaction(currentDir, transaction);
+          const currentDirection = await readTransactionDirection(currentDir, transaction);
+          if (currentDirection !== direction) {
+            throw new Error(
+              `knowledge transaction '${transaction.transactionId}' changed direction`
+            );
+          }
+          await assertKnowledgeFileTransactionTerminal(input.root, transaction, currentDirection);
+        });
+      }
+    );
+    await rm2(join(transactionRoot, activeName), { recursive: true, force: false });
+    await syncDirectory(transactionRoot);
+  });
+}
+async function rollbackKnowledgeFileTransaction(input) {
+  await withTransactionDirectory(
+    input.root,
+    input.transactionRoot,
+    input.transaction,
+    async (transactionDir) => {
+      const transaction = transactionSchema.parse(input.transaction);
+      assertTransactionEntries(transaction);
+      await assertActiveTransaction(transactionDir, transaction);
+      await input.beforeCommit?.(transaction.entries.at(-1));
+      const direction = await readTransactionDirection(transactionDir, transaction);
+      if (direction !== "rollback") {
+        await writeJsonDurable(join(transactionDir, "direction.json"), {
+          schemaVersion: 1,
+          transactionId: transaction.transactionId,
+          direction: "rollback"
+        });
+      }
+      for (const entry of [...transaction.entries].reverse()) {
+        await withSafeDescendant(input.root, entry.path, async (target) => {
+          const current = await readRegularFile(target);
+          if (fileMatches(current, entry.beforeHash, entry.beforeMode)) return;
+          if (!fileMatches(current, entry.afterHash, entry.afterMode)) {
+            throw new Error(`knowledge file changed outside rollback: ${entry.path}`);
+          }
+          await input.beforeCommit?.(entry);
+          if (entry.beforeHash === null) {
+            await removeDurable(target);
+            return;
+          }
+          const before = (await readRegularFileNoFollow(snapshotPath(transactionDir, "before", entry.index))).bytes;
+          if (hashBytes(before) !== entry.beforeHash) {
+            throw new Error(`knowledge rollback snapshot changed: ${entry.path}`);
+          }
+          await writeFileDurable(target, before, { mode: entry.beforeMode });
+        });
+      }
+      await input.beforeCommit?.(transaction.entries[0]);
+      for (const entry of transaction.entries) {
+        await withSafeDescendant(input.root, entry.path, async (target) => {
+          const current = await readRegularFile(target);
+          if (!fileMatches(current, entry.beforeHash, entry.beforeMode)) {
+            throw new Error(`knowledge file transaction did not roll back: ${entry.path}`);
+          }
+        });
+      }
+    }
+  );
+}
+async function loadKnowledgeFileTransactionState(input) {
+  try {
+    return await withTransactionRoot(input.root, input.transactionRoot, false, async (root) => {
+      const activeTransactions = await activeTransactionDirectoryNames(root);
+      if (activeTransactions.length === 0) return null;
+      if (activeTransactions.length > 1) {
+        throw new Error("multiple knowledge file transactions are active");
+      }
+      return withSafeDirectory(root, activeTransactions[0], false, async (transactionDir) => {
+        const transaction = await readActiveTransaction(transactionDir);
+        return {
+          transaction,
+          direction: await readTransactionDirection(transactionDir, transaction)
+        };
+      });
+    });
+  } catch (error) {
+    if (isMissingFile(error)) return null;
+    throw error;
+  }
+}
+async function readActiveTransaction(transactionDir) {
+  const transaction = transactionSchema.parse(
+    JSON.parse(
+      (await readRegularFileNoFollow(join(transactionDir, "transaction.json"))).bytes.toString(
+        "utf8"
+      )
+    )
+  );
+  assertTransactionEntries(transaction);
+  return transaction;
+}
+async function assertActiveTransaction(transactionDir, expected) {
+  const active = await readActiveTransaction(transactionDir);
+  if (active.transactionId !== expected.transactionId || contentHash(active) !== contentHash(transactionSchema.parse(expected))) {
+    throw new Error(`active knowledge transaction does not match '${expected.transactionId}'`);
+  }
+}
+async function readTransactionDirection(transactionDir, transaction) {
+  try {
+    const direction = transactionDirectionSchema.parse(
+      JSON.parse(
+        (await readRegularFileNoFollow(join(transactionDir, "direction.json"))).bytes.toString(
+          "utf8"
+        )
+      )
+    );
+    if (direction.transactionId !== transaction.transactionId) {
+      throw new Error("knowledge transaction direction belongs to another transaction");
+    }
+    return direction.direction;
+  } catch (error) {
+    if (isMissingFile(error)) return "apply";
+    throw error;
+  }
+}
+function snapshotPath(root, side, index) {
+  return join(root, side, `${index}.bin`);
+}
+async function withTransactionDirectory(root, transactionRoot, transaction, use) {
+  const parsed = transactionSchema.parse(transaction);
+  try {
+    return await withTransactionRoot(
+      root,
+      transactionRoot,
+      false,
+      (safeRoot) => withSafeDirectory(safeRoot, activeTransactionDirectoryName(parsed.transactionId), false, use)
+    );
+  } catch (error) {
+    if (isMissingFile(error)) {
+      throw new Error(`active knowledge transaction does not match '${parsed.transactionId}'`, {
+        cause: error
+      });
+    }
+    throw error;
+  }
+}
+async function activeTransactionDirectoryNames(transactionRoot) {
+  const active = [];
+  for (const entry of await readdir2(transactionRoot, { withFileTypes: true })) {
+    if (entry.name === "active") {
+      throw new Error("knowledge transaction store contains an unsupported active journal");
+    }
+    if (!entry.name.startsWith("active-")) continue;
+    if (!entry.isDirectory()) {
+      throw new Error(`knowledge transaction journal is not a directory: ${entry.name}`);
+    }
+    activeTransactionDirectoryName(entry.name.slice("active-".length));
+    active.push(entry.name);
+  }
+  return active.sort();
+}
+function activeTransactionDirectoryName(transactionId) {
+  return `active-${z.string().uuid().parse(transactionId)}`;
+}
+async function assertKnowledgeFileTransactionTerminal(root, transaction, direction) {
+  if (direction === "apply") {
+    await assertKnowledgeFileTransactionApplied(root, transaction);
+    return;
+  }
+  for (const entry of transaction.entries) {
+    await withSafeDescendant(root, entry.path, async (target) => {
+      const current = await readRegularFile(target);
+      if (!fileMatches(current, entry.beforeHash, entry.beforeMode)) {
+        throw new Error(`knowledge file transaction did not roll back: ${entry.path}`);
+      }
+    });
+  }
+}
+async function withTransactionRoot(root, transactionRoot, create, use) {
+  if (isKernelAnchoredPath(transactionRoot)) {
+    const match = transactionRoot.match(/^(\/proc\/self\/fd\/\d+)(?:\/(.*))?$/);
+    if (!match?.[1]) throw new Error("knowledge transaction directory has an invalid anchor");
+    return withSafeDirectory(match[1], match[2] ?? "", create, use);
+  }
+  const resolvedRoot = resolve2(root);
+  const resolvedTransactionRoot = resolve2(transactionRoot);
+  if (!resolvedTransactionRoot.startsWith(`${resolvedRoot}${sep}`)) {
+    throw new Error("knowledge transaction directory escaped its root");
+  }
+  return withSafeDirectory(
+    root,
+    relative(resolvedRoot, resolvedTransactionRoot).replace(/\\/g, "/"),
+    create,
+    use
+  );
+}
+function assertTransactionEntries(transaction) {
+  const indexes = /* @__PURE__ */ new Set();
+  const paths = /* @__PURE__ */ new Set();
+  for (const entry of transaction.entries) {
+    const normalized = assertKnowledgeMutationPath(entry.path);
+    if (entry.path !== normalized || indexes.has(entry.index) || paths.has(entry.path)) {
+      throw new Error("knowledge file transaction has duplicate or unsafe entries");
+    }
+    assertHashModePair(entry.path, "before", entry.beforeHash, entry.beforeMode);
+    assertHashModePair(entry.path, "after", entry.afterHash, entry.afterMode);
+    indexes.add(entry.index);
+    paths.add(entry.path);
+  }
+}
+function normalizePlanEntry(entry) {
+  const path = assertKnowledgeMutationPath(entry.path);
+  assertHashModePair(path, "before", entry.beforeHash, entry.beforeMode);
+  assertHashModePair(path, "after", entry.afterHash, entry.afterMode);
+  return {
+    path,
+    beforeHash: entry.beforeHash,
+    afterHash: entry.afterHash,
+    ...entry.beforeMode === void 0 ? {} : { beforeMode: fileModeSchema.parse(entry.beforeMode) },
+    ...entry.afterMode === void 0 ? {} : { afterMode: fileModeSchema.parse(entry.afterMode) }
+  };
+}
+function assertHashModePair(path, side, hash, mode) {
+  if (hash === null !== (mode === void 0)) {
+    throw new Error(`knowledge transaction ${side} hash and mode disagree: ${path}`);
+  }
+  if (mode !== void 0) fileModeSchema.parse(mode);
+}
+function assertKnowledgeMutationPath(path) {
+  const normalized = normalizeTransactionPath(path);
+  if (normalized === ".agent-knowledge/sources.json" || normalized.startsWith("knowledge/") || normalized.startsWith("raw/")) {
+    return normalized;
+  }
+  throw new Error(`knowledge transaction contains an unsupported path: ${path}`);
+}
+function normalizeTransactionPath(path) {
+  const normalized = path.replace(/\\/g, "/");
+  if (normalized.length === 0 || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized) || normalized.split("/").some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`knowledge file transaction has an unsafe path: ${path}`);
+  }
+  return normalized;
+}
+async function readRegularFile(path) {
+  try {
+    return await readRegularFileNoFollow(path);
+  } catch (error) {
+    if (isMissingFile(error)) return null;
+    throw error;
+  }
+}
+function hashBytes(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function sameBytes(left, right) {
+  if (left === null || right === null) return left === right;
+  return left.equals(right);
+}
+function fileMatches(file, hash, mode) {
+  return (file ? hashBytes(file.bytes) : null) === hash && file?.mode === mode;
+}
+
+// src/mutation-lock.ts
+var DEFAULT_STALE_MS = 15 * 60 * 1e3;
+var DEFAULT_READ_RETRIES = 100;
+var DEFAULT_READ_WAIT_MS = 25;
+var activeRoots = new AsyncLocalStorage();
+var activeReadRoots = new AsyncLocalStorage();
+var KnowledgeLockLostError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "KnowledgeLockLostError";
+  }
+};
+async function withKnowledgeMutation(root, mutate, options = {}) {
+  const resolvedRoot = resolve3(root);
+  const active = activeRoots.getStore();
+  const existing = active?.get(resolvedRoot);
+  if (existing?.active) {
+    existing.lock.assertOwned();
+    const result = await mutate(existing.lock);
+    existing.lock.assertOwned();
+    return result;
+  }
+  return withSafeDirectory(resolvedRoot, ".agent-knowledge", true, async (cacheDir) => {
+    const acquired = await acquireDurableFileLock(resolvedRoot, {
+      lockfilePath: join2(cacheDir, "mutation.lock.durable"),
+      staleMs: options.staleMs,
+      retries: options.retries ?? { retries: 100, factor: 1.1, minTimeout: 10, maxTimeout: 200, randomize: true }
+    });
+    const mutationLock = {
+      transactionRoot: join2(cacheDir, "file-transactions"),
+      assertOwned: acquired.assertOwned
+    };
+    const scope = { active: true, lock: mutationLock };
+    try {
+      const pending = await loadKnowledgeFileTransaction({
+        root: resolvedRoot,
+        transactionRoot: mutationLock.transactionRoot
+      });
+      if (pending) {
+        const resume = options.resumeTransaction;
+        if (!resume || pending.purpose !== resume.purpose) {
+          throw new Error(`knowledge transaction '${pending.purpose}' requires its owner to resume`);
+        }
+      }
+      const locks = new Map(active);
+      locks.set(resolvedRoot, scope);
+      return await activeRoots.run(locks, async () => {
+        const epoch = await beginMutationEpoch(cacheDir);
+        let completed = false;
+        try {
+          if (pending) {
+            const resume = options.resumeTransaction;
+            if (!resume)
+              throw new Error(
+                `knowledge transaction '${pending.purpose}' requires its owner to resume`
+              );
+            await recoverKnowledgeFileTransaction({
+              root: resolvedRoot,
+              transactionRoot: mutationLock.transactionRoot,
+              expectedPurpose: resume.purpose,
+              direction: resume.direction,
+              validate: resume.validate,
+              assertOwned: acquired.assertOwned
+            });
+          }
+          mutationLock.assertOwned();
+          const result = await mutate(mutationLock);
+          mutationLock.assertOwned();
+          completed = true;
+          return result;
+        } finally {
+          mutationLock.assertOwned();
+          const stillPending = await loadKnowledgeFileTransaction({
+            root: resolvedRoot,
+            transactionRoot: mutationLock.transactionRoot
+          });
+          if (completed || !stillPending) await finishMutationEpoch(cacheDir, epoch);
+        }
+      });
+    } finally {
+      scope.active = false;
+      await acquired.release();
+    }
+  });
+}
+async function inspectPendingKnowledgeMutation(root) {
+  const resolvedRoot = resolve3(root);
+  const pending = await inspectKnowledgeFileTransaction({
+    root: resolvedRoot,
+    transactionRoot: join2(resolvedRoot, ".agent-knowledge", "file-transactions")
+  });
+  if (!pending) return null;
+  const { transaction, direction } = pending;
+  return {
+    transactionId: transaction.transactionId,
+    purpose: transaction.purpose,
+    createdAt: transaction.createdAt,
+    direction,
+    paths: transaction.entries.map((entry) => entry.path)
+  };
+}
+async function recoverPendingKnowledgeMutation(root, options) {
+  const pending = await inspectPendingKnowledgeMutation(root);
+  if (!pending) throw new Error("knowledge base has no pending mutation");
+  let matched = false;
+  await withKnowledgeMutation(
+    root,
+    () => {
+      if (!matched) throw new Error("pending knowledge mutation changed before recovery");
+    },
+    {
+      resumeTransaction: {
+        purpose: pending.purpose,
+        direction: options.action,
+        validate(transaction) {
+          if (transaction.transactionId !== options.transactionId) {
+            throw new Error(`pending knowledge mutation does not match '${options.transactionId}'`);
+          }
+          matched = true;
+        }
+      }
+    }
+  );
+}
+async function withKnowledgeRead(root, read, options = {}) {
+  const resolvedRoot = resolve3(root);
+  if (activeRoots.getStore()?.get(resolvedRoot)?.active) return await read();
+  if (activeReadRoots.getStore()?.has(resolvedRoot)) return await read();
+  const readRoots = new Set(activeReadRoots.getStore());
+  readRoots.add(resolvedRoot);
+  return activeReadRoots.run(readRoots, async () => {
+    const retries = options.retries ?? DEFAULT_READ_RETRIES;
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+      const before = await readMutationEpoch(resolvedRoot);
+      if (isOdd(before)) {
+        await waitForActiveMutationEpoch(resolvedRoot, before, options);
+        continue;
+      }
+      const result = await read();
+      const after = await readMutationEpoch(resolvedRoot);
+      if (before === after && !isOdd(after)) return result;
+      if (isOdd(after)) await waitForActiveMutationEpoch(resolvedRoot, after, options);
+    }
+    throw new Error("knowledge read could not observe a stable mutation epoch");
+  });
+}
+async function acquireDurableFileLock(target, options) {
+  const stale = Math.max(5e3, options.staleMs ?? DEFAULT_STALE_MS);
+  const update = Math.max(1e3, Math.floor(stale / 3));
+  let compromised;
+  let released = false;
+  await mkdir2(dirname2(options.lockfilePath), { recursive: true });
+  const release = await lock(target, {
+    lockfilePath: options.lockfilePath,
+    realpath: false,
+    stale,
+    update,
+    retries: options.retries,
+    onCompromised(error) {
+      compromised = error;
+    }
+  });
+  return {
+    assertOwned() {
+      if (released) throw new KnowledgeLockLostError("knowledge filesystem lock is no longer owned");
+      if (compromised)
+        throw new KnowledgeLockLostError("knowledge filesystem lock was compromised", {
+          cause: compromised
+        });
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      let releaseError;
+      try {
+        await release();
+      } catch (error) {
+        releaseError = error;
+      }
+      if (releaseError && compromised) {
+        throw new AggregateError(
+          [releaseError, compromised],
+          "knowledge filesystem lock was compromised and could not be released"
+        );
+      }
+      if (releaseError) throw releaseError;
+      if (compromised) {
+        throw new KnowledgeLockLostError("knowledge filesystem lock was compromised", {
+          cause: compromised
+        });
+      }
+    }
+  };
+}
+async function beginMutationEpoch(cacheDir) {
+  const current = await readMutationEpochFromCache(cacheDir);
+  const odd = isOdd(current) ? current : current + 1;
+  await writeMutationEpoch(cacheDir, odd);
+  return odd;
+}
+async function finishMutationEpoch(cacheDir, odd) {
+  await writeMutationEpoch(cacheDir, isOdd(odd) ? odd + 1 : odd);
+}
+async function readMutationEpoch(root) {
+  try {
+    return await withSafeDirectory(root, ".agent-knowledge", false, readMutationEpochFromCache);
+  } catch (error) {
+    if (isMissingFile(error)) return 0;
+    throw error;
+  }
+}
+async function readMutationEpochFromCache(cacheDir) {
+  try {
+    const text = await withSafeDescendant(
+      cacheDir,
+      "mutation-epoch.json",
+      (path) => readFile(path, "utf8")
+    );
+    const parsed = JSON.parse(text);
+    const epoch = parsed.epoch;
+    if (typeof epoch !== "number" || !Number.isSafeInteger(epoch) || epoch < 0) {
+      throw new Error("knowledge mutation epoch is invalid");
+    }
+    return epoch;
+  } catch (error) {
+    if (isMissingFile(error)) return 0;
+    throw error;
+  }
+}
+async function writeMutationEpoch(cacheDir, epoch) {
+  await writeJsonDurableWithinRoot(cacheDir, "mutation-epoch.json", {
+    epoch,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+async function waitForActiveMutationEpoch(root, epoch, options) {
+  if (!await hasActiveMutationLock(root, options)) {
+    throw new Error(`knowledge mutation epoch ${epoch} is odd with no active writer`);
+  }
+  await new Promise((resolve4) => setTimeout(resolve4, options.waitMs ?? DEFAULT_READ_WAIT_MS));
+}
+async function hasActiveMutationLock(root, options) {
+  try {
+    return await withSafeDirectory(
+      root,
+      ".agent-knowledge",
+      false,
+      (cacheDir) => check(root, {
+        lockfilePath: join2(cacheDir, "mutation.lock.durable"),
+        realpath: false,
+        stale: Math.max(5e3, options.staleMs ?? DEFAULT_STALE_MS)
+      })
+    );
+  } catch (error) {
+    if (isMissingFile(error)) return false;
+    throw error;
+  }
+}
+function isOdd(value) {
+  return value % 2 === 1;
+}
+
+// src/schemas.ts
+import { z as z2 } from "zod";
+var SourceAnchorSchema = z2.object({
+  id: z2.string().min(1),
+  sourceId: z2.string().min(1),
+  label: z2.string().optional(),
+  page: z2.number().int().positive().optional(),
+  lineStart: z2.number().int().positive().optional(),
+  lineEnd: z2.number().int().positive().optional(),
+  charStart: z2.number().int().nonnegative().optional(),
+  charEnd: z2.number().int().nonnegative().optional(),
+  timestampMs: z2.number().nonnegative().optional(),
+  metadata: z2.record(z2.string(), z2.unknown()).optional()
+});
+var SourceRecordSchema = z2.object({
+  id: z2.string().min(1),
+  uri: z2.string().min(1),
+  title: z2.string().optional(),
+  mediaType: z2.string().optional(),
+  contentHash: z2.string().min(16),
+  text: z2.string().optional(),
+  anchors: z2.array(SourceAnchorSchema).optional(),
+  validUntil: z2.iso.datetime().optional(),
+  lastVerifiedAt: z2.iso.datetime().optional(),
+  metadata: z2.record(z2.string(), z2.unknown()).optional(),
+  createdAt: z2.string().min(1)
+});
+var KnowledgePageSchema = z2.object({
+  id: z2.string().min(1),
+  path: z2.string().min(1),
+  title: z2.string().min(1),
+  text: z2.string(),
+  frontmatter: z2.record(z2.string(), z2.unknown()),
+  sourceIds: z2.array(z2.string()),
+  tags: z2.array(z2.string()),
+  outLinks: z2.array(z2.string())
+});
+var KnowledgeGraphNodeSchema = z2.object({
+  id: z2.string(),
+  title: z2.string(),
+  path: z2.string(),
+  tags: z2.array(z2.string()),
+  sourceIds: z2.array(z2.string()),
+  outDegree: z2.number().int().nonnegative(),
+  inDegree: z2.number().int().nonnegative()
+});
+var KnowledgeGraphEdgeSchema = z2.object({
+  source: z2.string(),
+  target: z2.string(),
+  weight: z2.number(),
+  reasons: z2.array(z2.string())
+});
+var KnowledgeIndexSchema = z2.object({
+  root: z2.string(),
+  generatedAt: z2.string(),
+  sources: z2.array(SourceRecordSchema),
+  pages: z2.array(KnowledgePageSchema),
+  graph: z2.object({
+    nodes: z2.array(KnowledgeGraphNodeSchema),
+    edges: z2.array(KnowledgeGraphEdgeSchema)
+  })
+});
+var KnowledgeEventSchema = z2.object({
+  id: z2.string().min(1),
+  type: z2.enum([
+    "source.added",
+    "proposal.applied",
+    "index.built",
+    "lint.run",
+    "optimization.run",
+    "release.promoted",
+    "release.rejected"
+  ]),
+  createdAt: z2.string().min(1),
+  actor: z2.string().optional(),
+  target: z2.string().optional(),
+  metadata: z2.record(z2.string(), z2.unknown()).optional()
+});
+var KnowledgeBaseCandidateSchema = z2.object({
+  id: z2.string().min(1),
+  units: z2.array(
+    z2.object({
+      id: z2.string().min(1),
+      title: z2.string().min(1),
+      text: z2.string(),
+      claims: z2.array(
+        z2.object({
+          id: z2.string().min(1),
+          text: z2.string().min(1),
+          refs: z2.array(
+            z2.object({
+              sourceId: z2.string().min(1),
+              anchorId: z2.string().optional(),
+              quote: z2.string().optional()
+            })
+          ),
+          confidence: z2.number().min(0).max(1).optional(),
+          status: z2.enum(["draft", "active", "superseded", "rejected"]).optional(),
+          metadata: z2.record(z2.string(), z2.unknown()).optional()
+        })
+      ).optional(),
+      relations: z2.array(
+        z2.object({
+          sourceId: z2.string(),
+          targetId: z2.string(),
+          predicate: z2.string(),
+          weight: z2.number().optional(),
+          metadata: z2.record(z2.string(), z2.unknown()).optional()
+        })
+      ).optional(),
+      sourceIds: z2.array(z2.string()).optional(),
+      tags: z2.array(z2.string()).optional(),
+      metadata: z2.record(z2.string(), z2.unknown()).optional(),
+      updatedAt: z2.string().optional()
+    })
+  ),
+  retrievalPolicy: z2.string().optional(),
+  synthesisPolicy: z2.string().optional(),
+  questionPolicy: z2.string().optional(),
+  updatePolicy: z2.string().optional(),
+  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) {
+  return {
+    root,
+    knowledgeDir: join3(root, "knowledge"),
+    rawSourcesDir: join3(root, "raw", "sources"),
+    sourceRegistryPath: join3(root, ".agent-knowledge", "sources.json"),
+    indexPath: join3(root, "knowledge", "index.md"),
+    logPath: join3(root, "knowledge", "log.md"),
+    cacheDir: join3(root, ".agent-knowledge")
+  };
+}
+var SCAFFOLD_PAGE_BASENAMES = ["index.md", "log.md"];
+function isScaffoldPath(path) {
+  const normalized = path.replace(/\\/g, "/");
+  for (const basename3 of SCAFFOLD_PAGE_BASENAMES) {
+    if (normalized === `knowledge/${basename3}`) return true;
+    if (normalized.endsWith(`/${basename3}`)) 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 content = file.bytes.toString("utf8");
+    const { frontmatter, body } = parseFrontmatter(content);
+    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();
+}
+
+// src/sources.ts
+import { lstat as lstat2, readdir as readdir3, readFile as readFile2 } from "fs/promises";
+import { basename as basename2, join as join4, relative as relative2 } from "path";
+import { z as z3 } from "zod";
+var sourceRegistrySchema = z3.object({
+  generatedAt: z3.string().min(1),
+  sources: z3.array(SourceRecordSchema.passthrough())
+}).strict();
+async function loadSourceRegistry(root) {
+  return withKnowledgeRead(root, () => loadSourceRegistryUnlocked(root));
+}
+async function loadSourceRegistryUnlocked(root) {
+  try {
+    const file = await readRegularFileWithinRoot(root, ".agent-knowledge/sources.json");
+    return sourceRegistrySchema.parse(JSON.parse(file.bytes.toString("utf8")));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { generatedAt: (/* @__PURE__ */ new Date(0)).toISOString(), sources: [] };
+    }
+    throw error;
+  }
+}
+async function writeSourceRegistry(root, registry) {
+  await withKnowledgeMutation(root, async () => {
+    await writeJsonDurableWithinRoot(
+      root,
+      ".agent-knowledge/sources.json",
+      sourceRegistrySchema.parse(registry)
+    );
+  });
+}
+async function addSourcePath(root, sourcePath, options = {}) {
+  const sourceStat = await lstat2(sourcePath);
+  if (sourceStat.isDirectory()) {
+    const files = await listSourceFiles(sourcePath);
+    const prepared = await Promise.all(
+      files.map((file) => preparePathSource(root, file.path, file.mode, options))
+    );
+    return commitSourceBatch(root, prepared, options);
+  }
+  if (!sourceStat.isFile()) throw new Error(`unsupported source path: ${sourcePath}`);
+  return commitSourceBatch(
+    root,
+    [await preparePathSource(root, sourcePath, sourceStat.mode & 511, options)],
+    options
+  );
+}
+async function preparePathSource(root, sourcePath, mode, options) {
+  const bytes = await readFile2(sourcePath);
+  const contentHash3 = sha256(bytes.toString("base64"));
+  const fileName = basename2(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", `${contentHash3}:${fileName}`);
+  const targetRel = rawSourcePath(fileName, contentHash3, ext(fileName));
+  const copyIntoRaw = options.copyIntoRaw ?? true;
+  return {
+    record: {
+      id,
+      uri: copyIntoRaw ? targetRel : sourcePath,
+      title: loaded.title ?? fileName,
+      mediaType: loaded.mediaType ?? mediaTypeFor2(fileName),
+      contentHash: contentHash3,
+      text: loaded.text ?? textPreview(fileName, bytes),
+      anchors: (loaded.anchors ?? []).map((anchor) => ({ ...anchor, sourceId: id })),
+      createdAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+      metadata: {
+        ...loaded.metadata ?? {},
+        originalPath: sourcePath,
+        sizeBytes: bytes.length,
+        projectRelativePath: relative2(root, sourcePath).replace(/\\/g, "/")
+      }
+    },
+    mutation: copyIntoRaw ? { path: targetRel, content: bytes, mode } : null,
+    purposeParts: [sourcePath, contentHash3, copyIntoRaw, mode]
+  };
+}
+async function addSourceText(root, input, options = {}) {
+  const [record] = await commitSourceBatch(root, [await prepareTextSource(input, options)], options);
+  return record;
+}
+async function prepareTextSource(input, options) {
+  const text = input.text;
+  const contentHash3 = sha256(text);
+  const fileName = basename2(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 loaded = adapter ? await adapter.load(adapterInput) : {};
+  const id = stableId("src", `${contentHash3}:${input.uri}`);
+  const targetRel = rawSourcePath(fileName, contentHash3, ".txt");
+  const rawContent = text.endsWith("\n") ? text : `${text}
+`;
+  return {
+    record: {
+      id,
+      uri: targetRel,
+      title: input.title ?? loaded.title ?? fileName,
+      mediaType: input.mediaType ?? loaded.mediaType ?? "text/plain",
+      contentHash: contentHash3,
+      text: loaded.text ?? text.slice(0, 2e5),
+      anchors: (loaded.anchors ?? []).map((anchor) => ({ ...anchor, sourceId: id })),
+      ...input.validUntil === void 0 ? {} : { validUntil: input.validUntil },
+      ...input.lastVerifiedAt === void 0 ? {} : { lastVerifiedAt: input.lastVerifiedAt },
+      createdAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+      metadata: {
+        ...loaded.metadata ?? {},
+        ...input.metadata ?? {},
+        originalUri: input.uri,
+        sizeBytes: Buffer.byteLength(text, "utf8")
+      }
+    },
+    mutation: { path: targetRel, content: rawContent },
+    purposeParts: [input.uri, contentHash3]
+  };
+}
+async function commitSourceBatch(root, prepared, options) {
+  if (prepared.length === 0) return [];
+  const purpose = `source-import:${sha256(JSON.stringify(prepared.map((item) => item.purposeParts)))}`;
+  return withKnowledgeMutation(
+    root,
+    async (lock2) => {
+      const existing = await loadSourceRegistry(root);
+      const records = uniqueSources(prepared.map((item) => item.record));
+      const next = sourceRegistrySchema.parse({
+        generatedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+        sources: [
+          ...records,
+          ...existing.sources.filter(
+            (source) => !records.some((record) => record.id === source.id)
+          )
+        ]
+      });
+      await commitKnowledgeFileMutations({
+        root,
+        transactionRoot: lock2.transactionRoot,
+        purpose,
+        mutations: [
+          ...uniqueMutations(prepared.flatMap((item) => item.mutation ? [item.mutation] : [])),
+          {
+            path: relative2(root, sourceRegistryPath(root)).replace(/\\/g, "/"),
+            content: `${JSON.stringify(next, null, 2)}
+`
+          }
+        ],
+        assertOwned: lock2.assertOwned
+      });
+      return records;
+    },
+    { resumeTransaction: { purpose } }
+  );
+}
+function sourceRegistryPath(root) {
+  return join4(layoutFor(root).cacheDir, "sources.json");
+}
+function uniqueSources(records) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const record of records) byId.set(record.id, record);
+  return [...byId.values()];
+}
+function uniqueMutations(mutations) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const mutation of mutations) {
+    const existing = byPath.get(mutation.path);
+    if (existing && !sameMutation(existing, mutation)) {
+      throw new Error(`source import produced conflicting raw path: ${mutation.path}`);
+    }
+    byPath.set(mutation.path, mutation);
+  }
+  return [...byPath.values()];
+}
+function sameMutation(left, right) {
+  if (left.mode !== right.mode) return false;
+  if (Buffer.isBuffer(left.content) && Buffer.isBuffer(right.content)) {
+    return left.content.equals(right.content);
+  }
+  return left.content === right.content;
+}
+async function listSourceFiles(root) {
+  const entries = await readdir3(root, { withFileTypes: true });
+  const out = [];
+  for (const entry of entries) {
+    const full = join4(root, entry.name);
+    const entryStat = await lstat2(full);
+    if (entryStat.isDirectory()) out.push(...await listSourceFiles(full));
+    else if (entryStat.isFile()) out.push({ path: full, mode: entryStat.mode & 511 });
+    else throw new Error(`unsupported directory entry in source import: ${full}`);
+  }
+  return out;
+}
+function rawSourcePath(fileName, contentHash3, extension) {
+  return join4(
+    "raw",
+    "sources",
+    `${slugify(fileName.replace(/\.[^.]+$/, ""))}-${contentHash3.slice(0, 8)}${extension}`
+  ).replace(/\\/g, "/");
+}
+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/indexer.ts
+async function buildKnowledgeIndex(root) {
+  return withKnowledgeRead(root, () => buildKnowledgeIndexUnlocked(root));
+}
+async function buildKnowledgeIndexUnlocked(root) {
+  const [pages, sourceRegistry] = await Promise.all([
+    loadKnowledgePages(root),
+    loadSourceRegistry(root)
+  ]);
+  const index = {
+    root,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    sources: sourceRegistry.sources,
+    pages,
+    graph: buildKnowledgeGraph(pages)
+  };
+  return index;
+}
+async function writeKnowledgeIndex(root) {
+  return withKnowledgeMutation(root, async () => {
+    const index = await buildKnowledgeIndexUnlocked(root);
+    await writeJsonDurableWithinRoot(root, ".agent-knowledge/index.json", index);
+    return index;
+  });
+}
+
+// src/lint.ts
+function lintKnowledgeIndex(index) {
+  const findings = [];
+  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 pageIds = /* @__PURE__ */ new Map();
+  const sourceHashes = /* @__PURE__ */ new Map();
+  for (const page of index.pages) {
+    pageIds.set(page.id, [...pageIds.get(page.id) ?? [], page.path]);
+    byTarget.add(normalizeLinkTarget(page.id));
+    byTarget.add(normalizeLinkTarget(page.title));
+    byTarget.add(normalizeLinkTarget(page.path.split("/").pop().replace(/\.md$/, "")));
+    const titleKey = page.title.toLowerCase();
+    titles.set(titleKey, [...titles.get(titleKey) ?? [], page.path]);
+  }
+  for (const source of index.sources) {
+    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 && !isScaffoldPath(page.path)) {
+      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}]].`
+        });
+      }
+    }
+  }
+  for (const edge of index.graph.edges)
+    inbound.set(edge.target, (inbound.get(edge.target) ?? 0) + 1);
+  for (const page of index.pages) {
+    if (!isScaffoldPath(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."
+      });
+    }
+    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."
+      });
+    }
+    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 }
+        });
+      }
+    }
+    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
+        });
+      } 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
+        });
+      }
+    }
+  }
+  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 }
+      });
+    }
+  }
+  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 }
+      });
+    }
+  }
+  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 }
+      });
+    }
+  }
+  return findings;
+}
+function extractSourceRefs(text) {
+  const refs = [];
+  const regex = /\[\^([A-Za-z0-9_-]+)(?:#([A-Za-z0-9_.:-]+))?\]/g;
+  let match;
+  match = regex.exec(text);
+  while (match !== null) {
+    refs.push({ sourceId: match[1], anchorId: match[2] });
+    match = regex.exec(text);
+  }
+  return refs;
+}
+
+// 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
+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 { readFile as readFile3 } from "fs/promises";
+import { contentHash as contentHash2 } from "@tangle-network/agent-eval";
+async function applyKnowledgeWriteBlocks(root, proposalText) {
+  const parsed = parseKnowledgeWriteBlocks(proposalText);
+  const purpose = `knowledge-proposal:${contentHash2(parsed.blocks)}`;
+  return withKnowledgeMutation(
+    root,
+    async (lock2) => {
+      if (parsed.blocks.length > 0) {
+        await commitKnowledgeFileMutations({
+          root,
+          transactionRoot: lock2.transactionRoot,
+          purpose,
+          mutations: parsed.blocks.map((block) => ({
+            path: block.path,
+            content: block.content.endsWith("\n") ? block.content : `${block.content}
+`
+          })),
+          assertOwned: lock2.assertOwned
+        });
+      }
+      return { written: parsed.blocks.map((block) => block.path), warnings: parsed.warnings };
+    },
+    { resumeTransaction: { purpose } }
+  );
+}
+async function applyKnowledgeWriteBlocksFile(root, proposalPath) {
+  return applyKnowledgeWriteBlocks(root, await readFile3(proposalPath, "utf8"));
+}
+
+// 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,
+  writeFileDurableWithinRoot,
+  writeJsonDurableWithinRoot,
+  renameDurable,
+  withSafeDirectory,
+  readRegularFileWithinRoot,
+  listRegularFilesWithinRoot,
+  isMissingFile,
+  knowledgeFileTransactionPlanHash,
+  prepareKnowledgeFileTransaction,
+  applyKnowledgeFileTransaction,
+  finishKnowledgeFileTransaction,
+  rollbackKnowledgeFileTransaction,
+  assertKnowledgeMutationPath,
+  WIKILINK_REGEX,
+  extractWikilinks,
+  normalizeLinkTarget,
+  buildKnowledgeGraph,
+  withKnowledgeMutation,
+  inspectPendingKnowledgeMutation,
+  recoverPendingKnowledgeMutation,
+  withKnowledgeRead,
+  acquireDurableFileLock,
+  SourceAnchorSchema,
+  SourceRecordSchema,
+  KnowledgePageSchema,
+  KnowledgeGraphNodeSchema,
+  KnowledgeGraphEdgeSchema,
+  KnowledgeIndexSchema,
+  KnowledgeEventSchema,
+  KnowledgeBaseCandidateSchema,
+  parseFrontmatter,
+  formatFrontmatter,
+  layoutFor,
+  SCAFFOLD_PAGE_BASENAMES,
+  isScaffoldPath,
+  initKnowledgeBase,
+  loadKnowledgePages,
+  writeJson,
+  loadSourceRegistry,
+  writeSourceRegistry,
+  addSourcePath,
+  addSourceText,
+  sourceRegistryPath,
+  buildKnowledgeIndex,
+  writeKnowledgeIndex,
+  lintKnowledgeIndex,
+  validateKnowledgeIndex,
+  isSafeKnowledgePath,
+  parseKnowledgeWriteBlocks,
+  applyKnowledgeWriteBlocks,
+  applyKnowledgeWriteBlocksFile,
+  stringMetadata,
+  inspectKnowledgeIndex,
+  explainKnowledgeTarget
+};
+//# sourceMappingURL=chunk-R7ADUA44.js.map