@swarmvaultai/engine 0.6.5 → 0.6.7

package/dist/index.js

@@ -9,6 +9,7 @@ import {
   firstSentences,
   getProviderForTask,
   initWorkspace,
+  isPathWithin,
   listFilesRecursive,
   loadVaultConfig,
   normalizeWhitespace,
@@ -21,7 +22,7 @@ import {
   uniqueBy,
   writeFileIfChanged,
   writeJsonFile
-} from "./chunk-OK5752AP.js";
+} from "./chunk-HRRPWXRZ.js";
 
 // src/agents.ts
 import crypto from "crypto";
@@ -63,6 +64,13 @@ function buildManagedBlock(target) {
     ""
   ].join("\n");
 }
+function buildCursorRule() {
+  const frontmatter = YAML.stringify({
+    description: "SwarmVault graph-first repository instructions.",
+    alwaysApply: true
+  }).trimEnd();
+  return ["---", frontmatter, "---", "", buildManagedBlock("cursor").trimEnd(), ""].join("\n");
+}
 function supportsAgentHook(agent) {
   return agent === "claude" || agent === "opencode" || agent === "gemini" || agent === "copilot";
 }
@@ -689,8 +697,7 @@ async function installAgent(rootDir, agent, options = {}) {
       await upsertManagedBlock(target, buildManagedBlock("gemini"));
       break;
     case "cursor":
-      await writeOwnedFile(target, `${buildManagedBlock("cursor")}
-`);
+      await writeOwnedFile(target, buildCursorRule());
       break;
     case "aider":
       await upsertManagedBlock(target, buildManagedBlock("aider"));
@@ -1342,10 +1349,13 @@ function buildBenchmarkArtifact(input) {
   const corpusTokens = Math.max(1, Math.round(input.corpusWords * (100 / 75)));
   const perQuestion = input.perQuestion.filter((entry) => entry.queryTokens > 0).map((entry) => ({
     ...entry,
-    reduction: Number(Math.max(0, 1 - entry.queryTokens / Math.max(1, corpusTokens)).toFixed(3))
+    // Honest reduction: negative values mean graph context is larger than the
+    // full corpus, which is the truth on very small vaults. Clamping to zero
+    // hid that signal.
+    reduction: Number((1 - entry.queryTokens / Math.max(1, corpusTokens)).toFixed(3))
   }));
   const avgQueryTokens = perQuestion.length ? Math.max(1, Math.round(perQuestion.reduce((total, entry) => total + entry.queryTokens, 0) / perQuestion.length)) : 0;
-  const reductionRatio = avgQueryTokens ? Number(Math.max(0, 1 - avgQueryTokens / Math.max(1, corpusTokens)).toFixed(3)) : 0;
+  const reductionRatio = avgQueryTokens ? Number((1 - avgQueryTokens / Math.max(1, corpusTokens)).toFixed(3)) : 0;
   const uniqueVisitedNodes = new Set(perQuestion.flatMap((entry) => entry.visitedNodeIds)).size;
   const summary = {
     questionCount: input.questions.length,
@@ -1727,6 +1737,7 @@ import { pathToFileURL } from "url";
 import { Readability } from "@mozilla/readability";
 import matter3 from "gray-matter";
 import ignore from "ignore";
+import { isText } from "istextorbinary";
 import { JSDOM as JSDOM2 } from "jsdom";
 import mime from "mime-types";
 import TurndownService2 from "turndown";
@@ -2446,14 +2457,18 @@ function rubyStringContent(node) {
   const contentNode = node.descendantsOfType(["string_content", "simple_symbol", "bare_string"]).find((item) => item !== null) ?? null;
   return contentNode?.text.trim() || void 0;
 }
+function normalizePowerShellDotSourceSpecifier(raw) {
+  const unquoted = raw.replace(/^['"]+|['"]+$/g, "").trim();
+  return unquoted.replace(/^\$PSScriptRoot(?:[\\/]+|$)/i, "./");
+}
 function parsePowerShellImport(commandNode) {
   const commandName = commandNode.descendantsOfType(["command_name", "command_name_expr"]).find((item) => item !== null)?.text.trim();
   const genericTokens = commandNode.descendantsOfType("generic_token").filter((item) => item !== null).map((item) => item.text.trim());
   if (commandNode.namedChildren.some((child) => child?.type === "command_invokation_operator")) {
-    const specifier = commandName?.trim();
-    if (specifier) {
+    const raw = commandName?.trim();
+    if (raw) {
       return {
-        specifier,
+        specifier: normalizePowerShellDotSourceSpecifier(raw),
         importedSymbols: [],
         isExternal: false,
         reExport: false
@@ -2934,6 +2949,21 @@ function rustCodeAnalysis(manifest, rootNode, diagnostics) {
       imports.push(parseRustUse(child.text));
       continue;
     }
+    if (child.type === "mod_item") {
+      const hasInlineBody = child.namedChildren.some((item) => item?.type === "declaration_list");
+      if (!hasInlineBody) {
+        const modName = extractIdentifier(child.childForFieldName("name") ?? findNamedChild(child, "identifier"));
+        if (modName) {
+          imports.push({
+            specifier: `self::${modName}`,
+            importedSymbols: [],
+            isExternal: false,
+            reExport: false
+          });
+        }
+      }
+      continue;
+    }
     const name = child.type === "function_item" ? extractIdentifier(child.childForFieldName("name")) : extractIdentifier(child.childForFieldName("name"));
     if (child.type === "impl_item") {
       const traitName = normalizeSymbolReference(nodeText(child.childForFieldName("trait")));
@@ -3517,8 +3547,9 @@ function rubyCodeAnalysis(manifest, rootNode, diagnostics) {
         if (callee === "require" || callee === "require_relative") {
           const specifier = rubyStringContent(child.childForFieldName("arguments") ?? child.namedChildren.at(1) ?? null);
           if (specifier) {
+            const normalizedSpecifier = callee === "require_relative" && !specifier.startsWith(".") && !specifier.startsWith("/") ? `./${specifier}` : specifier;
             imports.push({
-              specifier,
+              specifier: normalizedSpecifier,
               importedSymbols: [],
               isExternal: callee === "require" && !specifier.startsWith("."),
               reExport: false
@@ -3765,7 +3796,7 @@ async function analyzeTreeSitterCode(manifest, content, language) {
     };
   }
   try {
-    const diagnostics = diagnosticsFromTree(tree.rootNode);
+    const diagnostics = language === "lua" ? [] : diagnosticsFromTree(tree.rootNode);
     const rationales = extractTreeSitterRationales(manifest, language, tree.rootNode);
     switch (language) {
       case "bash":
@@ -3869,8 +3900,31 @@ function interpreterFromShebang(content) {
   }
   return basename(parts[0] ?? "");
 }
-function isShellInterpreter(value) {
-  return value === "sh" || value === "bash" || value === "zsh";
+function languageFromInterpreter(interpreter) {
+  switch (interpreter) {
+    case "sh":
+    case "bash":
+    case "zsh":
+    case "dash":
+    case "ksh":
+    case "ash":
+      return "bash";
+    case "node":
+    case "nodejs":
+      return "javascript";
+    case "python":
+    case "python2":
+    case "python3":
+      return "python";
+    case "ruby":
+      return "ruby";
+    case "php":
+      return "php";
+    case "lua":
+      return "lua";
+    default:
+      return void 0;
+  }
 }
 function formatDiagnosticCategory(category) {
   switch (category) {
@@ -4472,8 +4526,11 @@ function inferCodeLanguage(filePath, mimeType = "", options = {}) {
   if ([".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx"].includes(extension)) {
     return "cpp";
   }
-  if (!extension && options.executable && isShellInterpreter(interpreterFromShebang(options.content))) {
-    return "bash";
+  if (!extension && options.executable) {
+    const fromShebang = languageFromInterpreter(interpreterFromShebang(options.content));
+    if (fromShebang) {
+      return fromShebang;
+    }
   }
   return void 0;
 }
@@ -4482,7 +4539,13 @@ function modulePageTitle(manifest) {
 }
 function importResolutionCandidates(basePath, specifier, extensions) {
   const resolved = path6.posix.normalize(path6.posix.join(path6.posix.dirname(basePath), specifier));
-  if (path6.posix.extname(resolved)) {
+  const resolvedExt = path6.posix.extname(resolved);
+  if (resolvedExt) {
+    if (extensions.includes(resolvedExt)) {
+      const resolvedBase = resolved.slice(0, -resolvedExt.length);
+      const candidates = [resolved, ...extensions.map((extension) => `${resolvedBase}${extension}`)];
+      return uniqueBy(candidates, (candidate) => candidate);
+    }
     return [resolved];
   }
   const direct = extensions.map((extension) => path6.posix.normalize(`${resolved}${extension}`));
@@ -4577,7 +4640,9 @@ async function readNearestGoModulePath(startPath, cache) {
 }
 function rustModuleAlias(repoRelativePath) {
   const withoutExt = stripCodeExtension2(normalizeAlias(repoRelativePath));
-  const trimmed = withoutExt.replace(/^src\//, "").replace(/\/mod$/i, "");
+  const srcIdx = withoutExt.lastIndexOf("/src/");
+  const withinCrate = srcIdx >= 0 ? withoutExt.slice(srcIdx + "/src/".length) : withoutExt.replace(/^src\//, "");
+  const trimmed = withinCrate.replace(/\/mod$/i, "");
   if (!trimmed || trimmed === "lib" || trimmed === "main") {
     return "crate";
   }
@@ -4792,7 +4857,7 @@ function resolveRustAliases(manifest, specifier) {
   if (!currentAlias) {
     return [];
   }
-  const currentParts = currentAlias.replace(/^crate::?/, "").split("::").filter(Boolean);
+  const currentParts = currentAlias.replace(/^crate(?:::)?/, "").split("::").filter(Boolean);
   if (specifier.startsWith("self::")) {
     return [`crate${currentParts.length ? `::${currentParts.join("::")}` : ""}::${specifier.slice("self::".length)}`];
   }
@@ -6583,7 +6648,7 @@ function inferKind(mimeType, filePath, detectionOptions = {}) {
   if (mimeType === "text/csv" || mimeType === "text/tab-separated-values" || filePath.toLowerCase().endsWith(".csv") || filePath.toLowerCase().endsWith(".tsv")) {
     return "csv";
   }
-  if (mimeType.startsWith("text/")) {
+  if (mimeType.startsWith("text/") || isStructuredTextMime(mimeType)) {
     return "text";
   }
   if (mimeType === "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" || filePath.toLowerCase().endsWith(".xlsx")) {
@@ -6597,6 +6662,26 @@ function inferKind(mimeType, filePath, detectionOptions = {}) {
   }
   return "binary";
 }
+function isStructuredTextMime(mimeType) {
+  switch (mimeType) {
+    case "application/json":
+    case "application/json5":
+    case "application/ld+json":
+    case "application/manifest+json":
+    case "application/xml":
+    case "application/toml":
+    case "application/yaml":
+    case "application/x-yaml":
+    case "application/javascript":
+    case "application/ecmascript":
+    case "application/typescript":
+    case "application/x-sh":
+    case "application/x-shellscript":
+      return true;
+    default:
+      return false;
+  }
+}
 async function localCodeDetectionOptions(absolutePath, payloadBytes) {
   if (path12.extname(absolutePath)) {
     return {};
@@ -6645,8 +6730,35 @@ function guessMimeType(target) {
   if (isRstFilePath(target)) {
     return "text/x-rst";
   }
+  const extension = path12.extname(target).toLowerCase();
+  if (extension === ".ts" || extension === ".tsx" || extension === ".mts" || extension === ".cts") {
+    return "text/typescript";
+  }
   return mime.lookup(target) || "application/octet-stream";
 }
+function refineBinaryKindWithBytes(absolutePath, currentKind, bytes) {
+  if (currentKind !== "binary") {
+    return currentKind;
+  }
+  const sniffSlice = bytes.length > 4096 ? bytes.subarray(0, 4096) : bytes;
+  return isText(absolutePath, sniffSlice) ? "text" : currentKind;
+}
+async function refineBinaryKindWithContentSniff(absolutePath, currentKind) {
+  if (currentKind !== "binary") {
+    return currentKind;
+  }
+  let handle;
+  try {
+    handle = await fs11.open(absolutePath, "r");
+    const chunk = Buffer.alloc(4096);
+    const { bytesRead } = await handle.read(chunk, 0, chunk.length, 0);
+    return refineBinaryKindWithBytes(absolutePath, currentKind, chunk.subarray(0, bytesRead));
+  } catch {
+    return currentKind;
+  } finally {
+    await handle?.close().catch(() => void 0);
+  }
+}
 function sourceGroupIdFor(prepared) {
   const originKey = prepared.originType === "url" ? prepared.url ?? prepared.title : prepared.originalPath ?? prepared.title;
   return `${slugify(prepared.title)}-${sha256(originKey).slice(0, 8)}`;
@@ -7497,6 +7609,7 @@ async function collectDirectoryFiles(rootDir, inputDir, repoRoot, options) {
           sourceKind = "chat_export";
         }
       }
+      sourceKind = await refineBinaryKindWithContentSniff(absolutePath, sourceKind);
       const sourceClass = sourceClassForRelativePath(relativePath, options);
       if (!supportedDirectoryKind(sourceKind)) {
         skipped.push({ path: toPosix(path12.relative(rootDir, absolutePath)), reason: `unsupported_kind:${sourceKind}` });
@@ -8118,7 +8231,7 @@ async function prepareFileInputs(rootDir, absoluteInput, repoRoot, sourceClass)
   }
   const mimeType = guessMimeType(absoluteInput);
   const detectionOptions = await localCodeDetectionOptions(absoluteInput, payloadBytes);
-  const sourceKind = inferKind(mimeType, absoluteInput, detectionOptions);
+  const sourceKind = refineBinaryKindWithBytes(absoluteInput, inferKind(mimeType, absoluteInput, detectionOptions), payloadBytes);
   const language = inferCodeLanguage(absoluteInput, mimeType, detectionOptions);
   const storedExtension = path12.extname(absoluteInput) || `.${mime.extension(mimeType) || "bin"}`;
   let title;
@@ -8564,7 +8677,7 @@ async function collectInboxAttachmentRefs(inputDir, files) {
     const sourceRefs = [];
     for (const ref of refs) {
       const resolved = path12.resolve(path12.dirname(absolutePath), ref);
-      if (!resolved.startsWith(inputDir) || !await fileExists(resolved)) {
+      if (!isPathWithin(inputDir, resolved) || !await fileExists(resolved)) {
         continue;
       }
       sourceRefs.push({
@@ -8902,6 +9015,7 @@ async function importInbox(rootDir, inputDir) {
         sourceKind = "chat_export";
       }
     }
+    sourceKind = await refineBinaryKindWithContentSniff(absolutePath, sourceKind);
     if (!isSupportedInboxKind(sourceKind)) {
       skipped.push({ path: toPosix(path12.relative(rootDir, absolutePath)), reason: `unsupported_kind:${sourceKind}` });
       continue;
@@ -9099,6 +9213,7 @@ import { z as z7 } from "zod";
 
 // src/analysis.ts
 import path14 from "path";
+import nlp from "compromise";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { z as z2 } from "zod";
 var ANALYSIS_FORMAT_VERSION = 7;
@@ -9176,11 +9291,31 @@ function extractTopTerms(text, count) {
   return [...frequency.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).slice(0, count).map(([token]) => token);
 }
 function extractEntities(text, count) {
-  const matches = text.match(/\b[A-Z][A-Za-z0-9-]+(?:\s+[A-Z][A-Za-z0-9-]+){0,2}\b/g) ?? [];
-  return uniqueBy(
-    matches.map((value) => normalizeWhitespace(value)),
-    (value) => value.toLowerCase()
-  ).slice(0, count);
+  const candidates = [];
+  try {
+    const doc = nlp(text);
+    const segments = [
+      doc.match("#ProperNoun+").out("array"),
+      doc.people().out("array"),
+      doc.places().out("array"),
+      doc.organizations().out("array"),
+      doc.topics().out("array")
+    ];
+    for (const segment of segments) {
+      for (const term of segment) {
+        const normalized = normalizeWhitespace(term);
+        if (normalized) {
+          candidates.push(normalized);
+        }
+      }
+    }
+  } catch {
+  }
+  if (candidates.length === 0) {
+    const matches = text.match(/\b[A-Z][A-Za-z0-9-]+(?:\s+[A-Z][A-Za-z0-9-]+){0,2}\b/g) ?? [];
+    candidates.push(...matches.map((value) => normalizeWhitespace(value)));
+  }
+  return uniqueBy(candidates, (value) => value.toLowerCase()).slice(0, count);
 }
 function detectPolarity(text) {
   if (/\b(no|not|never|cannot|can't|won't|without)\b/i.test(text)) {
@@ -10899,15 +11034,37 @@ function graphAdjacency(graph) {
   }
   return adjacency;
 }
+var NODE_TYPE_PRIORITY = {
+  concept: 6,
+  entity: 5,
+  source: 4,
+  module: 3,
+  symbol: 2,
+  rationale: 1
+};
+function nodeTypePriority(type) {
+  return NODE_TYPE_PRIORITY[type] ?? 0;
+}
+function compareLabelCandidates(left, right) {
+  const priorityDelta = nodeTypePriority(right.type) - nodeTypePriority(left.type);
+  if (priorityDelta !== 0) {
+    return priorityDelta;
+  }
+  const degreeDelta = (right.degree ?? 0) - (left.degree ?? 0);
+  if (degreeDelta !== 0) {
+    return degreeDelta;
+  }
+  return left.id.localeCompare(right.id);
+}
 function resolveNode(graph, target) {
   const normalized = normalizeTarget(target);
   const byId = nodeById(graph);
   if (byId.has(target)) {
     return byId.get(target);
   }
-  const exact = graph.nodes.find((node) => normalizeTarget(node.label) === normalized || normalizeTarget(node.id) === normalized);
-  if (exact) {
-    return exact;
+  const labelMatches = graph.nodes.filter((node) => normalizeTarget(node.label) === normalized || normalizeTarget(node.id) === normalized);
+  if (labelMatches.length) {
+    return labelMatches.sort(compareLabelCandidates)[0];
   }
   const pages = graph.pages.map((page) => ({
     page,
@@ -10916,7 +11073,7 @@ function resolveNode(graph, target) {
   if (pages[0]) {
     return primaryNodeForPage(graph, pages[0].page);
   }
-  return graph.nodes.map((node) => ({ node, score: Math.max(scoreMatch(target, node.label), scoreMatch(target, node.id)) })).filter((item) => item.score > 0).sort((left, right) => right.score - left.score || left.node.label.localeCompare(right.node.label))[0]?.node;
+  return graph.nodes.map((node) => ({ node, score: Math.max(scoreMatch(target, node.label), scoreMatch(target, node.id)) })).filter((item) => item.score > 0).sort((left, right) => right.score - left.score || compareLabelCandidates(left.node, right.node))[0]?.node;
 }
 function communityLabel(graph, communityId) {
   if (!communityId) {
@@ -13592,7 +13749,7 @@ async function resolveImageGenerationProvider(rootDir) {
   if (!providerConfig) {
     throw new Error(`No provider configured with id "${preferredProviderId}" for task "imageProvider".`);
   }
-  const { createProvider: createProvider2 } = await import("./registry-TYROWPR5.js");
+  const { createProvider: createProvider2 } = await import("./registry-NBLIJHZT.js");
   return createProvider2(preferredProviderId, providerConfig, rootDir);
 }
 async function generateOutputArtifacts(rootDir, input) {
@@ -17631,9 +17788,16 @@ async function listPages(rootDir) {
   return graph?.pages ?? [];
 }
 async function readPage(rootDir, relativePath) {
+  if (!relativePath) {
+    return null;
+  }
   const { paths } = await loadVaultConfig(rootDir);
   const absolutePath = path23.resolve(paths.wikiDir, relativePath);
-  if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
+  if (!isPathWithin(paths.wikiDir, absolutePath)) {
+    return null;
+  }
+  const stats = await fs19.stat(absolutePath).catch(() => null);
+  if (!stats?.isFile()) {
     return null;
   }
   const raw = await fs19.readFile(absolutePath, "utf8");
@@ -17662,6 +17826,32 @@ async function getWorkspaceInfo(rootDir) {
     pageCount: pages.length
   };
 }
+function extractClaimSectionLines(content) {
+  const lines = content.split("\n");
+  let inClaims = false;
+  let found = false;
+  const claimLines = [];
+  for (const line of lines) {
+    const trimmed = line.trimEnd();
+    if (trimmed === "## Claims") {
+      inClaims = true;
+      found = true;
+      continue;
+    }
+    if (inClaims) {
+      if (/^#{1,2}\s/.test(trimmed)) {
+        inClaims = false;
+        continue;
+      }
+      claimLines.push(line);
+    }
+  }
+  return found ? claimLines : null;
+}
+function isClaimPlaceholderBullet(line) {
+  const trimmed = line.trim();
+  return /^-\s+No\s+claims\s+extracted\.?$/i.test(trimmed);
+}
 function structuralLintFindings(_rootDir, paths, graph, schemas, manifests, sourceProjects) {
   const manifestMap = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
   const pageMap2 = new Map(graph.pages.map((page) => [page.id, page]));
@@ -17707,8 +17897,11 @@ function structuralLintFindings(_rootDir, paths, graph, schemas, manifests, sour
       const absolutePath = path23.join(paths.wikiDir, page.path);
       if (await fileExists(absolutePath)) {
         const content = await fs19.readFile(absolutePath, "utf8");
-        if (content.includes("## Claims")) {
-          const uncited = content.split("\n").filter((line) => line.startsWith("- ") && !line.includes("[source:"));
+        const claimLines = extractClaimSectionLines(content);
+        if (claimLines !== null) {
+          const uncited = claimLines.filter(
+            (line) => line.startsWith("- ") && !line.includes("[source:") && !isClaimPlaceholderBullet(line)
+          );
           if (uncited.length) {
             findings.push({
               severity: "warning",
@@ -17823,7 +18016,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.6.5";
+var SERVER_VERSION = "0.6.7";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -18158,7 +18351,7 @@ async function createMcpServer(rootDir) {
       const encodedPath = typeof variables.path === "string" ? variables.path : "";
       const relativePath = decodeURIComponent(encodedPath);
       const absolutePath = path24.resolve(paths.sessionsDir, relativePath);
-      if (!absolutePath.startsWith(paths.sessionsDir) || !await fileExists(absolutePath)) {
+      if (!isPathWithin(paths.sessionsDir, absolutePath) || !await fileExists(absolutePath)) {
         return asTextResource(`swarmvault://sessions/${encodedPath}`, `Session not found: ${relativePath}`);
       }
       return asTextResource(`swarmvault://sessions/${encodedPath}`, await fs20.readFile(absolutePath, "utf8"));
@@ -18497,6 +18690,15 @@ var DOCS_HINT_SEGMENTS = /* @__PURE__ */ new Set([
 function uniqueStrings4(values) {
   return uniqueBy(values.filter(Boolean), (value) => value);
 }
+function sourceOutputSchemaHash(schemas, projectIds) {
+  if (!projectIds.length) {
+    return schemas.effective.global.hash;
+  }
+  return composeVaultSchema(
+    schemas.root,
+    uniqueStrings4([...projectIds].sort((left, right) => left.localeCompare(right))).map((projectId) => schemas.projects[projectId]).filter((schema) => Boolean(schema?.hash))
+  ).hash;
+}
 function normalizeManagedStatus(value) {
   return value === "missing" || value === "error" ? value : "ready";
 }
@@ -19080,6 +19282,7 @@ async function writeSourceBriefForScope(rootDir, source) {
     return null;
   }
   const graph = await readJsonFile(paths.graphPath);
+  const schemas = await loadVaultSchemas(rootDir);
   const relatedPages = graph ? scopedSourcePages(graph, source.sourceIds) : [];
   const relatedPageIds = relatedPages.slice(0, 12).map((page) => page.id);
   const relatedNodeIds = graph ? scopedNodeIds(graph, source.sourceIds).slice(0, 20) : [];
@@ -19090,7 +19293,7 @@ async function writeSourceBriefForScope(rootDir, source) {
     question: `Brief ${source.title}`,
     answer: markdown,
     citations: source.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -19325,6 +19528,7 @@ async function buildSourceReviewStagedPage(rootDir, scope) {
     throw new Error(`Could not generate a source review for ${scope.id}.`);
   }
   const graph = await readJsonFile(paths.graphPath);
+  const schemas = await loadVaultSchemas(rootDir);
   const scopeManifests = manifestsForScope(graph, scope);
   const relatedPages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
   const relatedPageIds = relatedPages.slice(0, 16).map((page) => page.id);
@@ -19336,7 +19540,7 @@ async function buildSourceReviewStagedPage(rootDir, scope) {
     question: `Review ${scope.title}`,
     answer: markdown,
     citations: scope.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -19570,6 +19774,7 @@ async function buildSourceGuideStagedPage(rootDir, scope) {
     throw new Error(`Could not generate a source guide for ${scope.id}.`);
   }
   const graph = await readJsonFile(paths.graphPath);
+  const schemas = await loadVaultSchemas(rootDir);
   const scopeManifests = manifestsForScope(graph, scope);
   const relatedPages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
   const contradictions = findContradictionsForScope(scope, await readGraphReport(rootDir));
@@ -19583,7 +19788,7 @@ async function buildSourceGuideStagedPage(rootDir, scope) {
     question: `Guide ${scope.title}`,
     answer: markdown,
     citations: scope.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -19672,6 +19877,7 @@ async function buildSourceSessionSavedPage(rootDir, scope, session) {
     await compileVault(rootDir, {});
     graph = await readJsonFile(paths.graphPath);
   }
+  const schemas = await loadVaultSchemas(rootDir);
   const scopeManifests = manifestsForScope(graph, scope);
   const sourcePages = graph ? scopedSourcePages(graph, scope.sourceIds) : [];
   const analyses = await loadSourceAnalyses(rootDir, scope.sourceIds);
@@ -19737,7 +19943,7 @@ async function buildSourceSessionSavedPage(rootDir, scope, session) {
     question: `Guided Session ${scope.title}`,
     answer: sessionMarkdown,
     citations: scope.sourceIds,
-    schemaHash: graph?.generatedAt ?? "",
+    schemaHash: sourceOutputSchemaHash(schemas, projectIds),
     outputFormat: "report",
     relatedPageIds,
     relatedNodeIds,
@@ -20782,10 +20988,21 @@ async function getWatchStatus(rootDir) {
 
 // src/viewer.ts
 var execFileAsync = promisify(execFile);
+async function isReadableFile(absolutePath) {
+  try {
+    const stats = await fs23.stat(absolutePath);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
 async function readViewerPage(rootDir, relativePath) {
+  if (!relativePath) {
+    return null;
+  }
   const { paths } = await loadVaultConfig(rootDir);
   const absolutePath = path28.resolve(paths.wikiDir, relativePath);
-  if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
+  if (!isPathWithin(paths.wikiDir, absolutePath) || !await isReadableFile(absolutePath)) {
     return null;
   }
   const raw = await fs23.readFile(absolutePath, "utf8");
@@ -20799,9 +21016,12 @@ async function readViewerPage(rootDir, relativePath) {
   };
 }
 async function readViewerAsset(rootDir, relativePath) {
+  if (!relativePath) {
+    return null;
+  }
   const { paths } = await loadVaultConfig(rootDir);
   const absolutePath = path28.resolve(paths.wikiDir, relativePath);
-  if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
+  if (!isPathWithin(paths.wikiDir, absolutePath) || !await isReadableFile(absolutePath)) {
     return null;
   }
   return {
@@ -20843,178 +21063,200 @@ async function startGraphServer(rootDir, port, options = {}) {
   await ensureViewerDist(paths.viewerDistDir);
   const server = http.createServer(async (request, response) => {
     const url = new URL(request.url ?? "/", `http://${request.headers.host ?? `localhost:${effectivePort}`}`);
-    if (url.pathname === "/api/graph") {
-      if (!await fileExists(paths.graphPath)) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+    try {
+      if (url.pathname === "/api/graph") {
+        if (!await fileExists(paths.graphPath)) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const graph = await readJsonFile(paths.graphPath);
+        if (!graph) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
+        const report = await readJsonFile(reportPath) ?? null;
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(buildViewerGraphArtifact(graph, { report, full: options.full ?? false })));
         return;
       }
-      const graph = await readJsonFile(paths.graphPath);
-      if (!graph) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+      if (url.pathname === "/api/graph/query") {
+        const question = url.searchParams.get("q") ?? "";
+        const traversal = url.searchParams.get("traversal");
+        const budget = Number.parseInt(url.searchParams.get("budget") ?? "12", 10);
+        const result = await queryGraphVault(rootDir, question, {
+          traversal: traversal === "dfs" ? "dfs" : "bfs",
+          budget: Number.isFinite(budget) ? budget : 12
+        });
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
         return;
       }
-      const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
-      const report = await readJsonFile(reportPath) ?? null;
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(buildViewerGraphArtifact(graph, { report, full: options.full ?? false })));
-      return;
-    }
-    if (url.pathname === "/api/graph/query") {
-      const question = url.searchParams.get("q") ?? "";
-      const traversal = url.searchParams.get("traversal");
-      const budget = Number.parseInt(url.searchParams.get("budget") ?? "12", 10);
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(
-        JSON.stringify(
-          await queryGraphVault(rootDir, question, {
-            traversal: traversal === "dfs" ? "dfs" : "bfs",
-            budget: Number.isFinite(budget) ? budget : 12
-          })
-        )
-      );
-      return;
-    }
-    if (url.pathname === "/api/graph/path") {
-      const from = url.searchParams.get("from") ?? "";
-      const to = url.searchParams.get("to") ?? "";
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await pathGraphVault(rootDir, from, to)));
-      return;
-    }
-    if (url.pathname === "/api/graph/explain") {
-      const target2 = url.searchParams.get("target") ?? "";
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await explainGraphVault(rootDir, target2)));
-      return;
-    }
-    if (url.pathname === "/api/search") {
-      if (!await fileExists(paths.searchDbPath)) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Search index not found. Run `swarmvault compile` first." }));
+      if (url.pathname === "/api/graph/path") {
+        const from = url.searchParams.get("from") ?? "";
+        const to = url.searchParams.get("to") ?? "";
+        const result = await pathGraphVault(rootDir, from, to);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
         return;
       }
-      const query = url.searchParams.get("q") ?? "";
-      const limit = Number.parseInt(url.searchParams.get("limit") ?? "10", 10);
-      const kind = url.searchParams.get("kind") ?? "all";
-      const status = url.searchParams.get("status") ?? "all";
-      const project = url.searchParams.get("project") ?? "all";
-      const sourceType = url.searchParams.get("sourceType") ?? "all";
-      const sourceClass = url.searchParams.get("sourceClass") ?? "all";
-      const results = searchPages(paths.searchDbPath, query, {
-        limit: Number.isFinite(limit) ? limit : 10,
-        kind,
-        status,
-        project,
-        sourceType,
-        sourceClass
-      });
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(results));
-      return;
-    }
-    if (url.pathname === "/api/graph-report") {
-      const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
-      if (!await fileExists(reportPath)) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Graph report artifact not found. Run `swarmvault compile` first." }));
+      if (url.pathname === "/api/graph/explain") {
+        const target2 = url.searchParams.get("target") ?? "";
+        if (!target2) {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing explain target." }));
+          return;
+        }
+        const result = await explainGraphVault(rootDir, target2);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
         return;
       }
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(await fs23.readFile(reportPath, "utf8"));
-      return;
-    }
-    if (url.pathname === "/api/watch-status") {
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await getWatchStatus(rootDir)));
-      return;
-    }
-    if (url.pathname === "/api/page") {
-      const relativePath2 = url.searchParams.get("path") ?? "";
-      const page = await readViewerPage(rootDir, relativePath2);
-      if (!page) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: `Page not found: ${relativePath2}` }));
+      if (url.pathname === "/api/search") {
+        if (!await fileExists(paths.searchDbPath)) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Search index not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const query = url.searchParams.get("q") ?? "";
+        const limit = Number.parseInt(url.searchParams.get("limit") ?? "10", 10);
+        const kind = url.searchParams.get("kind") ?? "all";
+        const status = url.searchParams.get("status") ?? "all";
+        const project = url.searchParams.get("project") ?? "all";
+        const sourceType = url.searchParams.get("sourceType") ?? "all";
+        const sourceClass = url.searchParams.get("sourceClass") ?? "all";
+        const results = searchPages(paths.searchDbPath, query, {
+          limit: Number.isFinite(limit) ? limit : 10,
+          kind,
+          status,
+          project,
+          sourceType,
+          sourceClass
+        });
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(results));
         return;
       }
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(page));
-      return;
-    }
-    if (url.pathname === "/api/asset") {
-      const relativePath2 = url.searchParams.get("path") ?? "";
-      const asset = await readViewerAsset(rootDir, relativePath2);
-      if (!asset) {
-        response.writeHead(404, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: `Asset not found: ${relativePath2}` }));
+      if (url.pathname === "/api/graph-report") {
+        const reportPath = path28.join(paths.wikiDir, "graph", "report.json");
+        if (!await fileExists(reportPath)) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Graph report artifact not found. Run `swarmvault compile` first." }));
+          return;
+        }
+        const body = await fs23.readFile(reportPath, "utf8");
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(body);
         return;
       }
-      response.writeHead(200, { "content-type": asset.mimeType });
-      response.end(asset.buffer);
-      return;
-    }
-    if (url.pathname === "/api/reviews" && request.method === "GET") {
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await listApprovals(rootDir)));
-      return;
-    }
-    if (url.pathname === "/api/review" && request.method === "GET") {
-      const approvalId = url.searchParams.get("id") ?? "";
-      if (!approvalId) {
-        response.writeHead(400, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Missing approval id." }));
+      if (url.pathname === "/api/watch-status") {
+        const watchStatus = await getWatchStatus(rootDir);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(watchStatus));
         return;
       }
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await readApproval(rootDir, approvalId)));
-      return;
-    }
-    if (url.pathname === "/api/review" && request.method === "POST") {
-      const body = await readJsonBody(request);
-      const approvalId = typeof body.approvalId === "string" ? body.approvalId : "";
-      const targets = Array.isArray(body.targets) ? body.targets.filter((item) => typeof item === "string") : [];
-      const action = url.searchParams.get("action") ?? "";
-      if (!approvalId || action !== "accept" && action !== "reject") {
-        response.writeHead(400, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Missing approval id or invalid review action." }));
+      if (url.pathname === "/api/page") {
+        const relativePath2 = url.searchParams.get("path") ?? "";
+        const page = await readViewerPage(rootDir, relativePath2);
+        if (!page) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: `Page not found: ${relativePath2}` }));
+          return;
+        }
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(page));
         return;
       }
-      const result = action === "accept" ? await acceptApproval(rootDir, approvalId, targets) : await rejectApproval(rootDir, approvalId, targets);
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(result));
-      return;
-    }
-    if (url.pathname === "/api/candidates" && request.method === "GET") {
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(await listCandidates(rootDir)));
-      return;
-    }
-    if (url.pathname === "/api/candidate" && request.method === "POST") {
-      const body = await readJsonBody(request);
-      const target2 = typeof body.target === "string" ? body.target : "";
-      const action = url.searchParams.get("action") ?? "";
-      if (!target2 || action !== "promote" && action !== "archive") {
-        response.writeHead(400, { "content-type": "application/json" });
-        response.end(JSON.stringify({ error: "Missing candidate target or invalid candidate action." }));
+      if (url.pathname === "/api/asset") {
+        const relativePath2 = url.searchParams.get("path") ?? "";
+        const asset = await readViewerAsset(rootDir, relativePath2);
+        if (!asset) {
+          response.writeHead(404, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: `Asset not found: ${relativePath2}` }));
+          return;
+        }
+        response.writeHead(200, { "content-type": asset.mimeType });
+        response.end(asset.buffer);
         return;
       }
-      const result = action === "promote" ? await promoteCandidate(rootDir, target2) : await archiveCandidate(rootDir, target2);
-      response.writeHead(200, { "content-type": "application/json" });
-      response.end(JSON.stringify(result));
-      return;
-    }
-    const relativePath = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
-    const target = path28.join(paths.viewerDistDir, relativePath);
-    const fallback = path28.join(paths.viewerDistDir, "index.html");
-    const filePath = await fileExists(target) ? target : fallback;
-    if (!await fileExists(filePath)) {
-      response.writeHead(503, { "content-type": "text/plain" });
-      response.end("Viewer build not found. Run `pnpm build` first.");
-      return;
+      if (url.pathname === "/api/reviews" && request.method === "GET") {
+        const approvals = await listApprovals(rootDir);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(approvals));
+        return;
+      }
+      if (url.pathname === "/api/review" && request.method === "GET") {
+        const approvalId = url.searchParams.get("id") ?? "";
+        if (!approvalId) {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing approval id." }));
+          return;
+        }
+        const approval = await readApproval(rootDir, approvalId);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(approval));
+        return;
+      }
+      if (url.pathname === "/api/review" && request.method === "POST") {
+        const body = await readJsonBody(request);
+        const approvalId = typeof body.approvalId === "string" ? body.approvalId : "";
+        const targets = Array.isArray(body.targets) ? body.targets.filter((item) => typeof item === "string") : [];
+        const action = url.searchParams.get("action") ?? "";
+        if (!approvalId || action !== "accept" && action !== "reject") {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing approval id or invalid review action." }));
+          return;
+        }
+        const result = action === "accept" ? await acceptApproval(rootDir, approvalId, targets) : await rejectApproval(rootDir, approvalId, targets);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
+        return;
+      }
+      if (url.pathname === "/api/candidates" && request.method === "GET") {
+        const candidates = await listCandidates(rootDir);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(candidates));
+        return;
+      }
+      if (url.pathname === "/api/candidate" && request.method === "POST") {
+        const body = await readJsonBody(request);
+        const target2 = typeof body.target === "string" ? body.target : "";
+        const action = url.searchParams.get("action") ?? "";
+        if (!target2 || action !== "promote" && action !== "archive") {
+          response.writeHead(400, { "content-type": "application/json" });
+          response.end(JSON.stringify({ error: "Missing candidate target or invalid candidate action." }));
+          return;
+        }
+        const result = action === "promote" ? await promoteCandidate(rootDir, target2) : await archiveCandidate(rootDir, target2);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify(result));
+        return;
+      }
+      const relativePath = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
+      const target = path28.join(paths.viewerDistDir, relativePath);
+      const fallback = path28.join(paths.viewerDistDir, "index.html");
+      const filePath = await fileExists(target) ? target : fallback;
+      if (!await fileExists(filePath)) {
+        response.writeHead(503, { "content-type": "text/plain" });
+        response.end("Viewer build not found. Run `pnpm build` first.");
+        return;
+      }
+      const staticBody = await fs23.readFile(filePath);
+      response.writeHead(200, { "content-type": mime2.lookup(filePath) || "text/plain" });
+      response.end(staticBody);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`[viewer] ${request.method ?? "GET"} ${url.pathname} failed: ${message}`);
+      if (!response.headersSent) {
+        const status = /not found|could not resolve|cannot resolve/i.test(message) ? 404 : 500;
+        response.writeHead(status, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: message }));
+      } else {
+        response.end();
+      }
     }
-    response.writeHead(200, { "content-type": mime2.lookup(filePath) || "text/plain" });
-    response.end(await fs23.readFile(filePath));
   });
   await new Promise((resolve) => {
     server.listen(effectivePort, resolve);