@remnic/core 9.65.8 → 9.66.1

package/dist/chunk-QJCWK2A7.js

@@ -0,0 +1,1466 @@
+import {
+  buildCodingGraphInstallHint,
+  tryLoadCodingGraphModule
+} from "./chunk-VQ7B2Q6M.js";
+import {
+  composeMemoryEnvelope
+} from "./chunk-WKAXBXVA.js";
+import {
+  isCodingKnowledgeFeatureEnabled
+} from "./chunk-FEHIOYML.js";
+import {
+  displayErrorDetail
+} from "./chunk-RL6NEVXT.js";
+import {
+  stripAttributesSuffix
+} from "./chunk-JDSVLVCG.js";
+import {
+  expandTildePath
+} from "./chunk-EYIEWJNI.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/coding/architecture-card.ts
+import { readFile, readdir, lstat } from "fs/promises";
+import path from "path";
+var ARCHITECTURE_CARD_MAX_BYTES = 4096;
+var ARCHITECTURE_CARD_TRUNCATION_MARKER = "\u2026 card truncated to fit size cap \u2026";
+var ARCHITECTURE_CARD_MAX_SUMMARY_BYTES = 1024;
+var KNOWN_MANIFEST_FILES = [
+  "package.json",
+  "Cargo.toml",
+  "go.mod",
+  "pyproject.toml",
+  "setup.py",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "Gemfile",
+  "composer.json",
+  "mix.exs",
+  "deno.json"
+];
+var SCAN_IGNORE_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".svn",
+  ".hg",
+  "vendor",
+  "__pycache__",
+  ".venv",
+  "venv",
+  "env",
+  "dist",
+  "build",
+  "target",
+  "out",
+  ".next",
+  ".nuxt",
+  "coverage",
+  ".cache",
+  ".turbo",
+  ".idea",
+  ".vscode"
+]);
+var ARCHITECTURE_CARD_SUMMARY_SYSTEM_PROMPT = `You write a concise overview for a repository architecture card.
+Given the deterministic card (languages, manifests, entry points), produce a 3-5 sentence plain-text overview naming the dominant language, the primary entry point, and the project's shape.
+Rules:
+- Never invent facts absent from the input.
+- No headings, no markdown \u2014 just sentences.
+- Keep it under 600 characters.`;
+function createArchitectureCardSummariser(client) {
+  if (!client) return void 0;
+  return async (deterministicCard, repoRoot) => {
+    const response = await client.chatCompletion(
+      [
+        { role: "system", content: ARCHITECTURE_CARD_SUMMARY_SYSTEM_PROMPT },
+        { role: "user", content: `Repository: ${path.basename(repoRoot) || repoRoot}
+
+${deterministicCard}` }
+      ],
+      {
+        temperature: 0.2,
+        maxTokens: 512,
+        operation: "architecture-card-summary",
+        priority: "background"
+      }
+    );
+    return response?.content ?? null;
+  };
+}
+async function buildArchitectureCard(repoRoot, options = {}) {
+  if (typeof repoRoot !== "string" || repoRoot.length === 0) {
+    return { ok: false, code: "invalid_root", detail: "repoRoot must be a non-empty string" };
+  }
+  const absoluteRoot = path.resolve(expandTildePath(repoRoot));
+  try {
+    const rootStat = await lstat(absoluteRoot);
+    if (!rootStat.isDirectory()) {
+      return { ok: false, code: "invalid_root", detail: `not a directory: ${absoluteRoot}` };
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      code: "invalid_root",
+      detail: `repoRoot not accessible: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  try {
+    await readdir(absoluteRoot);
+  } catch (err) {
+    return {
+      ok: false,
+      code: "scan_failed",
+      detail: `repoRoot not readable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  try {
+    const scan = await scanRepository(absoluteRoot);
+    const deterministic = renderCard(scan, options.now ?? /* @__PURE__ */ new Date());
+    const maxBytes = options.maxBytes ?? ARCHITECTURE_CARD_MAX_BYTES;
+    let content = deterministic;
+    if (options.llmSummary === true && options.summariser) {
+      try {
+        const summary = await options.summariser(deterministic, absoluteRoot);
+        if (typeof summary === "string" && summary.trim().length > 0) {
+          const separator = "\n\n---\n\n";
+          const detBytes = Buffer.byteLength(deterministic, "utf-8");
+          const sepBytes = Buffer.byteLength(separator, "utf-8");
+          const summaryBudget = Math.min(
+            ARCHITECTURE_CARD_MAX_SUMMARY_BYTES,
+            maxBytes - detBytes - sepBytes
+          );
+          if (summaryBudget > 0) {
+            const clampedSummary = clampSummaryToBytes(summary.trim(), summaryBudget);
+            if (clampedSummary.length > 0) {
+              content = `${clampedSummary}${separator}${deterministic}`;
+            }
+          }
+        }
+      } catch (err) {
+        void err;
+      }
+    }
+    const { text: truncatedContent, truncated } = capToBytes(content, maxBytes);
+    return {
+      ok: true,
+      card: {
+        content: truncatedContent,
+        generatedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
+        byteSize: Buffer.byteLength(truncatedContent, "utf-8"),
+        truncated
+      }
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      code: "scan_failed",
+      detail: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function scanRepository(root) {
+  const topEntries = await readSortedDirEntries(root);
+  const topDirs = topEntries.filter((e) => e.isDirectory && !SCAN_IGNORE_DIRS.has(e.name)).map((e) => e.name);
+  const manifestFiles = topEntries.filter((e) => e.isFile && KNOWN_MANIFEST_FILES.includes(e.name)).map((e) => e.name);
+  const manifests = [];
+  for (const mf of sortStrings(manifestFiles)) {
+    const parsed = await parseManifest(path.join(root, mf));
+    manifests.push({ filename: mf, name: parsed.name, entryPoints: sortStrings(parsed.entryPoints) });
+  }
+  const languageHistogram = await computeLanguageHistogram(root, topEntries);
+  return {
+    root: path.basename(root) || root,
+    topDirs: sortStrings(topDirs),
+    manifests,
+    languageHistogram: sortLanguageHistogram(languageHistogram)
+  };
+}
+async function readSortedDirEntries(dir) {
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const name of sortStrings(names)) {
+    try {
+      const s = await lstat(path.join(dir, name));
+      if (s.isSymbolicLink()) continue;
+      entries.push({ name, isDirectory: s.isDirectory(), isFile: s.isFile() });
+    } catch {
+    }
+  }
+  return entries;
+}
+async function computeLanguageHistogram(root, topEntries) {
+  const counts = /* @__PURE__ */ new Map();
+  const dirsToScan = topEntries.filter((e) => e.isDirectory && !SCAN_IGNORE_DIRS.has(e.name)).map((e) => path.join(root, e.name));
+  const rootFiles = topEntries.filter((e) => e.isFile);
+  const visitDir = async (dir, depth) => {
+    if (depth > 2) return;
+    let entries;
+    try {
+      entries = await readSortedDirEntries(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory) {
+        if (!SCAN_IGNORE_DIRS.has(entry.name)) {
+          await visitDir(path.join(dir, entry.name), depth + 1);
+        }
+      } else if (entry.isFile) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (ext.length > 0) {
+          counts.set(ext, (counts.get(ext) ?? 0) + 1);
+        }
+      }
+    }
+  };
+  for (const f of rootFiles) {
+    const ext = path.extname(f.name).toLowerCase();
+    if (ext.length > 0) counts.set(ext, (counts.get(ext) ?? 0) + 1);
+  }
+  for (const dir of dirsToScan) {
+    await visitDir(dir, 0);
+  }
+  return Array.from(counts.entries()).map(([ext, count]) => ({ ext, count }));
+}
+async function parseManifest(filePath) {
+  const filename = path.basename(filePath);
+  try {
+    const raw = await readFile(filePath, "utf-8");
+    switch (filename) {
+      case "package.json":
+        return parsePackageJson(raw);
+      case "pyproject.toml":
+      case "setup.py":
+        return parsePythonProject(raw, filename);
+      case "go.mod":
+        return parseGoMod(raw);
+      case "Cargo.toml":
+        return parseCargoToml(raw);
+      default:
+        return { name: null, entryPoints: [] };
+    }
+  } catch {
+    return { name: null, entryPoints: [] };
+  }
+}
+function parsePackageJson(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { name: null, entryPoints: [] };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { name: null, entryPoints: [] };
+  }
+  const obj = parsed;
+  const name = typeof obj["name"] === "string" ? obj["name"] : null;
+  const entryPoints = [];
+  const bin = obj["bin"];
+  if (typeof bin === "string") {
+    entryPoints.push(bin);
+  } else if (typeof bin === "object" && bin !== null && !Array.isArray(bin)) {
+    for (const [key, value] of Object.entries(bin)) {
+      entryPoints.push(typeof value === "string" ? value : `bin/${key}`);
+    }
+  }
+  const main = typeof obj["main"] === "string" ? obj["main"] : null;
+  if (main) entryPoints.push(main);
+  const module = typeof obj["module"] === "string" ? obj["module"] : null;
+  if (module) entryPoints.push(module);
+  const scripts = obj["scripts"];
+  if (typeof scripts === "object" && scripts !== null && !Array.isArray(scripts)) {
+    const scriptKeys = Object.keys(scripts);
+    for (const key of ["start", "dev", "serve"]) {
+      if (scriptKeys.includes(key)) entryPoints.push(`scripts.${key}`);
+    }
+  }
+  return { name, entryPoints };
+}
+function parsePythonProject(raw, _filename) {
+  const entryPoints = [];
+  let name = null;
+  const nameMatch = raw.match(/^name\s*=\s*["']([^"']+)["']/m);
+  if (nameMatch) name = nameMatch[1] ?? null;
+  const scriptsMatch = raw.match(/\[project\.scripts\]([\s\S]*?)(?:\n\[|$)/);
+  if (scriptsMatch && scriptsMatch[1]) {
+    for (const line of scriptsMatch[1].split("\n")) {
+      const m = line.match(/^([a-zA-Z0-9_-]+)\s*=/);
+      if (m && m[1]) entryPoints.push(`scripts.${m[1]}`);
+    }
+  }
+  return { name, entryPoints };
+}
+function parseGoMod(raw) {
+  const moduleMatch = raw.match(/^module\s+(\S+)/m);
+  const name = moduleMatch && moduleMatch[1] ? moduleMatch[1] : null;
+  return { name, entryPoints: name ? ["main.go"] : [] };
+}
+function parseCargoToml(raw) {
+  const nameMatch = raw.match(/^name\s*=\s*"([^"]+)"/m);
+  const name = nameMatch && nameMatch[1] ? nameMatch[1] : null;
+  const entryPoints = [];
+  if (/\[\[bin\]\]/.test(raw)) entryPoints.push("src/bin/");
+  if (name) entryPoints.push("src/main.rs");
+  return { name, entryPoints };
+}
+function renderCard(scan, now) {
+  const lines = [];
+  lines.push(`# Architecture Card \u2014 ${scan.root}`);
+  lines.push("");
+  lines.push(`_Generated ${now.toISOString()}_`);
+  lines.push("");
+  const namedManifest = scan.manifests.find((m) => m.name !== null);
+  if (namedManifest && namedManifest.name) {
+    lines.push(`**Project:** ${namedManifest.name}`);
+    lines.push("");
+  }
+  if (scan.manifests.length > 0) {
+    lines.push("## Manifests");
+    for (const m of scan.manifests) {
+      const label = m.name ? `${m.filename} (${m.name})` : m.filename;
+      lines.push(`- ${label}`);
+    }
+    lines.push("");
+  }
+  if (scan.topDirs.length > 0) {
+    lines.push("## Top-level directories");
+    const cols = 4;
+    for (let i = 0; i < scan.topDirs.length; i += cols) {
+      const row = scan.topDirs.slice(i, i + cols).join(" \xB7 ");
+      lines.push(`- ${row}`);
+    }
+    lines.push("");
+  }
+  if (scan.languageHistogram.length > 0) {
+    lines.push("## Languages (by file count)");
+    const top = scan.languageHistogram.slice(0, 10);
+    for (const entry of top) {
+      lines.push(`- ${entry.ext}: ${entry.count}`);
+    }
+    lines.push("");
+  }
+  const allEntryPoints = sortStrings(scan.manifests.flatMap((m) => m.entryPoints));
+  if (allEntryPoints.length > 0) {
+    lines.push("## Entry points");
+    for (const ep of allEntryPoints) {
+      lines.push(`- ${ep}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+function sortStrings(values) {
+  return [...values].sort((a, b) => a.localeCompare(b));
+}
+function sortLanguageHistogram(entries) {
+  return [...entries].sort((a, b) => {
+    if (b.count !== a.count) return b.count - a.count;
+    return a.ext.localeCompare(b.ext);
+  });
+}
+function capToBytes(text, maxBytes) {
+  const byteLen = Buffer.byteLength(text, "utf-8");
+  if (byteLen <= maxBytes) {
+    return { text, truncated: false };
+  }
+  const marker = `
+
+_${ARCHITECTURE_CARD_TRUNCATION_MARKER}_`;
+  const markerBytes = Buffer.byteLength(marker, "utf-8");
+  const budget = maxBytes - markerBytes;
+  if (budget <= 0) {
+    return { text: marker.trimStart(), truncated: true };
+  }
+  let cut = 0;
+  let running = 0;
+  const chars = [...text];
+  for (let i = 0; i < chars.length; i++) {
+    const charBytes = Buffer.byteLength(chars[i], "utf-8");
+    if (running + charBytes > budget) break;
+    running += charBytes;
+    cut = i + 1;
+  }
+  return { text: chars.slice(0, cut).join("") + marker, truncated: true };
+}
+function clampSummaryToBytes(text, maxBytes) {
+  if (maxBytes <= 0) return "";
+  if (Buffer.byteLength(text, "utf-8") <= maxBytes) return text;
+  const ellipsis = " \u2026";
+  const budget = maxBytes - Buffer.byteLength(ellipsis, "utf-8");
+  if (budget <= 0) return "";
+  let cut = 0;
+  let running = 0;
+  const chars = [...text];
+  for (let i = 0; i < chars.length; i++) {
+    const charBytes = Buffer.byteLength(chars[i], "utf-8");
+    if (running + charBytes > budget) break;
+    running += charBytes;
+    cut = i + 1;
+  }
+  return chars.slice(0, cut).join("") + ellipsis;
+}
+
+// src/coding/architecture-surfaces.ts
+var ARCHITECTURE_CARD_TAG = "architecture-card";
+var ARCHITECTURE_CARD_KIND = "architecture";
+async function handleCodingArchitecture(request, ctx) {
+  const codingContext = request.sessionKey ? ctx.getCodingContext(request.sessionKey) : null;
+  if (codingContext === null || !isCodingKnowledgeFeatureEnabled(ctx.codingKnowledge, "architectureCard", codingContext)) {
+    ctx.throwInputError(
+      "coding_architecture requires codingKnowledge.enabled, codingKnowledge.architectureCard, and an attached coding context"
+    );
+  }
+  switch (request.subcommand) {
+    case "get":
+      return architectureGet(request, ctx);
+    case "refresh":
+      return architectureRefresh(request, ctx, codingContext);
+  }
+}
+async function architectureGet(request, ctx) {
+  const storage = await ctx.resolveStorage(request);
+  const existing = await findArchitectureCardMemory(storage);
+  if (!existing) {
+    return { subcommand: "get", found: false };
+  }
+  const content = stripAttributesSuffix(existing.content);
+  return {
+    subcommand: "get",
+    found: true,
+    card: {
+      content,
+      generatedAt: existing.frontmatter.updated ?? existing.frontmatter.created,
+      byteSize: Buffer.byteLength(content, "utf-8"),
+      // Derive truncation from the CONTENT marker, not a frontmatter tag —
+      // the refresh update path changes content without rewriting tags, so
+      // a tag-based check goes stale (cursor review: stale truncated tag).
+      truncated: content.includes(ARCHITECTURE_CARD_TRUNCATION_MARKER)
+    }
+  };
+}
+async function architectureRefresh(request, ctx, codingContext) {
+  const repoRoot = codingContext.rootPath ?? codingContext.projectId;
+  const storage = await ctx.resolveStorage(request);
+  const buildResult = await ctx.buildCard(repoRoot);
+  if (!buildResult.ok) {
+    log.warn(
+      `coding_architecture/refresh: card build failed (code=${buildResult.code}): ${buildResult.detail}`
+    );
+    ctx.throwInputError(
+      `coding_architecture refresh failed: card build returned ${buildResult.code}`
+    );
+  }
+  const cardContent = buildResult.card.content;
+  const tags = [ARCHITECTURE_CARD_TAG];
+  if (buildResult.card.truncated) tags.push("truncated");
+  const existing = await findArchitectureCardMemory(storage);
+  if (existing) {
+    await ctx.versioning.snapshotIfExists(existing);
+    const updated = await storage.updateMemory(existing.frontmatter.id, cardContent, {
+      actor: "coding-architecture-refresh",
+      ...ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}
+    });
+    if (!updated) {
+      log.warn(
+        `coding_architecture/refresh: updateMemory returned false for id=${existing.frontmatter.id} \u2014 falling back to writeMemory`
+      );
+      const fallbackWrite = await storage.writeSealedMemory(
+        composeMemoryEnvelope(
+          {
+            content: cardContent,
+            category: "fact",
+            confidence: 1,
+            tags,
+            structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
+            ...ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}
+          },
+          { source: "coding-architecture" }
+        ),
+        {}
+      );
+      log.info(
+        `access-write op=coding_architecture/refresh memoryId=${fallbackWrite.id} (fallback write) byteSize=${buildResult.card.byteSize}`
+      );
+      return refreshResponse(fallbackWrite, buildResult.card);
+    }
+    log.info(
+      `access-write op=coding_architecture/refresh memoryId=${existing.frontmatter.id} (updated) byteSize=${buildResult.card.byteSize}`
+    );
+    return {
+      subcommand: "refresh",
+      refreshed: true,
+      memoryId: existing.frontmatter.id,
+      byteSize: buildResult.card.byteSize,
+      truncated: buildResult.card.truncated
+    };
+  }
+  const newWrite = await storage.writeSealedMemory(
+    composeMemoryEnvelope(
+      {
+        content: cardContent,
+        category: "fact",
+        confidence: 1,
+        tags,
+        structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
+        ...ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}
+      },
+      { source: "coding-architecture" }
+    ),
+    {}
+  );
+  log.info(
+    `access-write op=coding_architecture/refresh memoryId=${newWrite.id} (new) byteSize=${buildResult.card.byteSize}`
+  );
+  return refreshResponse(newWrite, buildResult.card);
+}
+function refreshResponse(writeResult, card) {
+  if (writeResult.tombstoneBlocked) {
+    return {
+      subcommand: "refresh",
+      refreshed: false,
+      memoryId: writeResult.id,
+      byteSize: card.byteSize,
+      truncated: card.truncated,
+      blockedReason: "tombstone-blocked",
+      ...writeResult.blockedBy !== void 0 ? { blockedBy: writeResult.blockedBy } : {}
+    };
+  }
+  return {
+    subcommand: "refresh",
+    refreshed: true,
+    memoryId: writeResult.id,
+    byteSize: card.byteSize,
+    truncated: card.truncated
+  };
+}
+async function findArchitectureCardMemory(storage) {
+  const memories = await storage.readAllMemories();
+  const cards = memories.filter((m) => {
+    if (m.frontmatter.category !== "fact") return false;
+    const tags = m.frontmatter.tags ?? [];
+    if (!tags.includes(ARCHITECTURE_CARD_TAG)) return false;
+    if (m.frontmatter.structuredAttributes?.cardKind !== ARCHITECTURE_CARD_KIND) return false;
+    const outer = m.frontmatter.status;
+    if (outer !== void 0 && outer !== "active") return false;
+    if (m.frontmatter.archivedAt !== void 0 && m.frontmatter.archivedAt !== null) return false;
+    return true;
+  });
+  if (cards.length === 0) return null;
+  cards.sort((a, b) => {
+    const aUpdated = a.frontmatter.updated ?? a.frontmatter.created;
+    const bUpdated = b.frontmatter.updated ?? b.frontmatter.created;
+    if (aUpdated !== bUpdated) return bUpdated.localeCompare(aUpdated);
+    return b.frontmatter.id.localeCompare(a.frontmatter.id);
+  });
+  return cards[0] ?? null;
+}
+function createArchitectureVersioningHook(enabled, maxVersionsPerPage, sidecarDir, memoryDir, readFile3, writeVersion) {
+  return {
+    async snapshotIfExists(memory) {
+      if (!enabled) return;
+      try {
+        const fullContent = await readFile3(memory.path);
+        await writeVersion(
+          memory.path,
+          fullContent,
+          "manual",
+          { enabled: true, maxVersionsPerPage, sidecarDir },
+          void 0,
+          "architecture-card-refresh",
+          memoryDir
+        );
+      } catch {
+      }
+    }
+  };
+}
+
+// src/coding/codegraph-runtime.ts
+import path2 from "path";
+import { readFile as readFile2, realpath } from "fs/promises";
+import { readFileSync, realpathSync } from "fs";
+import { pathToFileURL } from "url";
+import { createHash } from "crypto";
+function codegraphSurfaceVisible(config) {
+  const ck = config.codingKnowledge;
+  if (ck === void 0 || ck === null) return false;
+  return ck.enabled === true && ck.codegraphTools === true;
+}
+function resolveCodegraphRoot(config, memoryDir) {
+  const rawDir = config.codingKnowledge.codegraphDbDir.trim();
+  const root = rawDir.length > 0 ? expandTildePath(rawDir) : path2.join(memoryDir, "codegraph");
+  if (!path2.isAbsolute(root)) {
+    throw new CodegraphRuntimeError(
+      "store_error",
+      "codegraph DB root must be an absolute path; set codingKnowledge.codegraphDbDir (or memoryDir) to an absolute path"
+    );
+  }
+  return root;
+}
+function resolveCodegraphDbPath(params) {
+  const { config, memoryDir, principal, projectId } = params;
+  const root = resolveCodegraphRoot(config, memoryDir);
+  const principalSafe = sanitizePathSegment(principal);
+  const projectSafe = sanitizePathSegment(projectId);
+  return path2.join(root, principalSafe, `${projectSafe}.sqlite`);
+}
+function sanitizePathSegment(input) {
+  const trimmed = (input ?? "").trim();
+  if (trimmed.length === 0) return "_";
+  const sanitized = trimmed.replace(/[^A-Za-z0-9._:-]+/g, "_");
+  return sanitized.replace(/^\.+/, "").replace(/[/\\]+/g, "_") || "_";
+}
+var storeCache = /* @__PURE__ */ new Map();
+function storeCacheKey(principalSafe, projectSafe, dbPath) {
+  return `${principalSafe}::${projectSafe}::${dbPath}`;
+}
+function isCodegraphModule(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  const graphStore = candidate.GraphStore;
+  return graphStore !== void 0 && typeof graphStore.open === "function";
+}
+async function resolveCodegraphModule() {
+  const mod = await tryLoadCodingGraphModule();
+  if (mod === null || !isCodegraphModule(mod)) return null;
+  return mod;
+}
+async function getCodegraphStore(params) {
+  const { config, memoryDir, principal, projectId, repoRoot } = params;
+  if (!codegraphSurfaceVisible(config)) {
+    throw new CodegraphRuntimeError(
+      "disabled",
+      "codegraph tools are disabled (codingKnowledge.enabled or codingKnowledge.codegraphTools is false)"
+    );
+  }
+  const mod = await resolveCodegraphModule();
+  if (mod === null) {
+    throw new CodegraphRuntimeError("package_missing", buildCodingGraphInstallHint());
+  }
+  const principalSafe = sanitizePathSegment(principal);
+  const projectSafe = sanitizePathSegment(projectId);
+  const dbPath = resolveCodegraphDbPath({ config, memoryDir, principal, projectId });
+  const key = storeCacheKey(principalSafe, projectSafe, dbPath);
+  const cached = storeCache.get(key);
+  if (cached !== void 0) {
+    if (repoRoot !== void 0 && cached.repoRoot === void 0) {
+      storeCache.delete(key);
+      try {
+        await cached.store.close();
+      } catch {
+      }
+      const store2 = await mod.GraphStore.open({ dbPath, repoRoot });
+      storeCache.set(key, { store: store2, repoRoot, openedAt: Date.now() });
+      return store2;
+    }
+    if (repoRoot !== void 0 && cached.repoRoot !== void 0 && cached.repoRoot !== repoRoot) {
+      throw new CodegraphRuntimeError(
+        "repo_root_conflict",
+        `codegraph store for project ${projectId} is already bound to repo root ${cached.repoRoot}; refusing to rebind to ${repoRoot}`
+      );
+    }
+    return cached.store;
+  }
+  const store = await mod.GraphStore.open({ dbPath, repoRoot });
+  storeCache.set(key, { store, repoRoot, openedAt: Date.now() });
+  return store;
+}
+function listCodegraphProjects(params) {
+  const { config, memoryDir, principal, listDir } = params;
+  if (!codegraphSurfaceVisible(config)) return [];
+  let root;
+  try {
+    root = resolveCodegraphRoot(config, memoryDir);
+  } catch {
+    return [];
+  }
+  const principalSafe = sanitizePathSegment(principal);
+  const principalDir = path2.join(root, principalSafe);
+  let entries;
+  try {
+    entries = listDir(principalDir);
+  } catch {
+    return [];
+  }
+  const projects = [];
+  for (const entry of entries) {
+    if (entry.endsWith(".sqlite")) {
+      projects.push(entry.slice(0, -".sqlite".length));
+    }
+  }
+  return projects;
+}
+async function deleteCodegraphProject(params) {
+  const { config, memoryDir, principal, projectId, confirm, removeFile } = params;
+  if (!confirm) {
+    throw new CodegraphRuntimeError(
+      "confirm_required",
+      "codegraph_delete_project requires confirm: true; destructive operations are never defaulted to proceed (rule 48)"
+    );
+  }
+  if (!codegraphSurfaceVisible(config)) {
+    throw new CodegraphRuntimeError("disabled", "codegraph tools are disabled");
+  }
+  const principalSafe = sanitizePathSegment(principal);
+  const projectSafe = sanitizePathSegment(projectId);
+  const dbPath = resolveCodegraphDbPath({ config, memoryDir, principal, projectId });
+  const key = storeCacheKey(principalSafe, projectSafe, dbPath);
+  const cached = storeCache.get(key);
+  if (cached !== void 0) {
+    storeCache.delete(key);
+    try {
+      await cached.store.close();
+    } catch {
+    }
+  }
+  let deleted = false;
+  try {
+    removeFile(dbPath);
+    deleted = true;
+  } catch (err) {
+    const code = err?.code;
+    if (code === "ENOENT") {
+      deleted = true;
+    } else {
+      deleted = false;
+    }
+  }
+  return { deleted, projectId };
+}
+function makeCodegraphRuntimeDelegates() {
+  return {
+    runReindex: (store, repoRoot, mode) => runCodegraphReindex({ store, repoRoot, mode }),
+    reportIndexStatus: (store, repoRoot) => reportCodegraphIndexStatus({ store, repoRoot }),
+    detectChanges: (store, repoRoot, head) => detectCodegraphChanges({ store, repoRoot, head }),
+    ingestTraces: (store, traces) => ingestCodegraphTraces({ store, traces }),
+    runLspResolution: (store, repoRoot, lspConfig) => runCodegraphLspResolution({ store, repoRoot, lspConfig })
+  };
+}
+async function runCodegraphReindex(params) {
+  const mod = await resolveCodegraphModule();
+  if (mod === null) {
+    return { ok: false, code: "package_missing", message: "The @remnic/coding-graph package is not installed." };
+  }
+  if (typeof mod.executeReindex !== "function" || typeof mod.defaultCodingGitInvoker !== "function") {
+    return { ok: false, code: "runtime_unavailable", message: "executeReindex is not available in the installed @remnic/coding-graph." };
+  }
+  const git = mod.defaultCodingGitInvoker();
+  let engine;
+  try {
+    if (typeof mod.createCodingGraphEngine !== "function") {
+      return { ok: false, code: "engine_unavailable", message: "createCodingGraphEngine is not exported by @remnic/coding-graph." };
+    }
+    engine = mod.createCodingGraphEngine();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, code: "engine_unavailable", message: `The coding-graph engine is not ready: ${msg}` };
+  }
+  let candidatePaths = [];
+  try {
+    const tracked = git.listTrackedFiles(params.repoRoot);
+    if (tracked.ok) {
+      candidatePaths = tracked.paths;
+    }
+  } catch {
+  }
+  try {
+    const result = await mod.executeReindex({
+      store: params.store,
+      git,
+      repoRoot: params.repoRoot,
+      parseFile: (input) => engine.parseFile(input),
+      candidatePaths
+    });
+    if (result && result.ok === true) {
+      return { ok: true, mode: result.mode ?? "auto", filesIngested: result.filesIngested ?? 0, head: result.head ?? null };
+    }
+    return {
+      ok: false,
+      code: result?.code ?? "store_error",
+      message: result?.message ?? "executeReindex reported a failure."
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, code: "store_error", message: msg };
+  }
+}
+async function lspPathEscapesRoot(repoRoot, absPath) {
+  try {
+    const [realRoot, realAbs] = await Promise.all([realpath(repoRoot), realpath(absPath)]);
+    const rel = path2.relative(realRoot, realAbs);
+    return rel === ".." || rel.startsWith(".." + path2.sep) || path2.isAbsolute(rel);
+  } catch {
+    return false;
+  }
+}
+function lspPathEscapesRootSync(repoRoot, absPath) {
+  try {
+    const realRoot = realpathSync(repoRoot);
+    const realAbs = realpathSync(absPath);
+    const rel = path2.relative(realRoot, realAbs);
+    return rel === ".." || rel.startsWith(".." + path2.sep) || path2.isAbsolute(rel);
+  } catch {
+    return false;
+  }
+}
+var DEFAULT_LSP_SERVERS = {
+  typescript: { command: "typescript-language-server", args: ["--stdio"] },
+  tsx: { command: "typescript-language-server", args: ["--stdio"] },
+  javascript: { command: "typescript-language-server", args: ["--stdio"] },
+  python: { command: "pyright-langserver", args: ["--stdio"] },
+  go: { command: "gopls", args: [] },
+  rust: { command: "rust-analyzer", args: [] }
+};
+async function runCodegraphLspResolution(params) {
+  const mod = await resolveCodegraphModule();
+  if (mod === null) {
+    return { ok: false, code: "package_missing", message: "@remnic/coding-graph is not installed." };
+  }
+  if (typeof mod.executeLspResolution !== "function" || typeof mod.planLspUpgrades !== "function" || typeof mod.LspClient?.connect !== "function") {
+    return { ok: false, code: "runtime_unavailable", message: "LSP resolution is not available in the installed @remnic/coding-graph." };
+  }
+  const engine = mod.createCodingGraphEngine?.() ?? null;
+  if (engine === null) {
+    return { ok: false, code: "engine_unavailable", message: "createCodingGraphEngine is not available." };
+  }
+  const repoRoot = path2.resolve(params.repoRoot);
+  const gitFactory = mod.defaultCodingGitInvoker;
+  if (typeof gitFactory !== "function") {
+    return { ok: true, upgraded: 0, unresolved: 0, budgetExhausted: 0 };
+  }
+  const tracked = gitFactory().listTrackedFiles(repoRoot);
+  if (!("paths" in tracked)) {
+    return { ok: true, upgraded: 0, unresolved: 0, budgetExhausted: 0 };
+  }
+  const resolvedCalleesBySrc = /* @__PURE__ */ new Map();
+  const alreadyResolved = (filePath, srcQualifiedName, calleeName) => {
+    const key = `${filePath}\0${srcQualifiedName}`;
+    let names = resolvedCalleesBySrc.get(key);
+    if (names === void 0) {
+      names = /* @__PURE__ */ new Set();
+      if (typeof params.store.resolvedCalleeNames === "function") {
+        for (const name of params.store.resolvedCalleeNames(srcQualifiedName, "heuristic", filePath)) {
+          names.add(name);
+        }
+      }
+      resolvedCalleesBySrc.set(key, names);
+    }
+    return names.has(calleeName);
+  };
+  const sites = [];
+  const gatheredCountByFile = /* @__PURE__ */ new Map();
+  const filteredCountByFile = /* @__PURE__ */ new Map();
+  const filteredSrcByFile = /* @__PURE__ */ new Map();
+  const parsedFiles = /* @__PURE__ */ new Set();
+  for (const rel of tracked.paths) {
+    const absPath = path2.join(repoRoot, rel);
+    if (await lspPathEscapesRoot(repoRoot, absPath)) continue;
+    let content;
+    try {
+      content = await readFile2(absPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = await engine.parseFile({ path: rel, content });
+    } catch {
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || !("ok" in parsed) || parsed.ok !== true || !("ir" in parsed)) continue;
+    const ir = parsed.ir;
+    if (!ir || typeof ir !== "object" || !("callSites" in ir) || !Array.isArray(ir.callSites)) continue;
+    parsedFiles.add(rel);
+    const language = "language" in ir && typeof ir.language === "string" ? ir.language : "";
+    const symbols = "symbols" in ir && Array.isArray(ir.symbols) ? ir.symbols : [];
+    const contentBytes = Buffer.from(content, "utf-8");
+    for (const site of ir.callSites) {
+      if (!site || typeof site !== "object" || !("span" in site)) continue;
+      const span = site.span;
+      if (!span || typeof span !== "object" || !("startByte" in span) || typeof span.startByte !== "number") continue;
+      const calleeName = "calleeNameCandidates" in site && Array.isArray(site.calleeNameCandidates) && typeof site.calleeNameCandidates[0] === "string" ? site.calleeNameCandidates[0] : "";
+      if (calleeName.length === 0) continue;
+      let srcQualifiedName = "";
+      let bestSpanSize = Number.POSITIVE_INFINITY;
+      for (const sym of symbols) {
+        if (!sym || typeof sym !== "object" || !("span" in sym) || !("qualifiedName" in sym)) continue;
+        const ss = sym.span;
+        if (!ss || typeof ss !== "object" || !("startByte" in ss) || !("endByte" in ss)) continue;
+        if (typeof ss.startByte !== "number" || typeof ss.endByte !== "number") continue;
+        if (ss.startByte <= span.startByte && span.startByte < ss.endByte) {
+          const size = ss.endByte - ss.startByte;
+          if (size < bestSpanSize) {
+            bestSpanSize = size;
+            srcQualifiedName = typeof sym.qualifiedName === "string" ? sym.qualifiedName : "";
+          }
+        }
+      }
+      if (srcQualifiedName.length === 0) continue;
+      const memberAccess = "memberAccess" in site && site.memberAccess === true;
+      if (!memberAccess && alreadyResolved(rel, srcQualifiedName, calleeName)) {
+        filteredCountByFile.set(rel, (filteredCountByFile.get(rel) ?? 0) + 1);
+        let srcs = filteredSrcByFile.get(rel);
+        if (srcs === void 0) {
+          srcs = /* @__PURE__ */ new Map();
+          filteredSrcByFile.set(rel, srcs);
+        }
+        const callees = srcs.get(srcQualifiedName);
+        if (callees === void 0) srcs.set(srcQualifiedName, /* @__PURE__ */ new Set([calleeName]));
+        else callees.add(calleeName);
+        continue;
+      }
+      const nameIdx = contentBytes.indexOf(Buffer.from(calleeName, "utf-8"), span.startByte);
+      const endByte = "endByte" in span && typeof span.endByte === "number" ? span.endByte : span.startByte + calleeName.length;
+      const calleeByteOffset = nameIdx >= 0 && nameIdx < endByte ? nameIdx : span.startByte;
+      sites.push({ filePath: rel, language, content, calleeByteOffset, calleeName, srcQualifiedName });
+      gatheredCountByFile.set(rel, (gatheredCountByFile.get(rel) ?? 0) + 1);
+    }
+  }
+  const canPreserve = typeof params.store.callEdgesForCaller === "function";
+  const preservedEdgesForFile = (rel) => {
+    const srcs = filteredSrcByFile.get(rel);
+    if (srcs === void 0 || !canPreserve) return [];
+    const preserved = [];
+    for (const [src] of srcs) {
+      const heuristicDsts = new Set(
+        params.store.callEdgesForCaller(src, rel, "heuristic").map((e) => e.dstQualifiedName)
+      );
+      for (const edge of params.store.callEdgesForCaller(src, rel, "lsp")) {
+        if (!heuristicDsts.has(edge.dstQualifiedName)) continue;
+        preserved.push({
+          srcQualifiedName: edge.srcQualifiedName,
+          dstQualifiedName: edge.dstQualifiedName,
+          type: edge.type
+        });
+      }
+    }
+    return preserved;
+  };
+  if (typeof params.store.reconcileLspEdges === "function") {
+    for (const rel of parsedFiles) {
+      if ((gatheredCountByFile.get(rel) ?? 0) !== 0) continue;
+      const filteredCount = filteredCountByFile.get(rel) ?? 0;
+      if (filteredCount > 0 && !canPreserve) continue;
+      params.store.reconcileLspEdges(rel, preservedEdgesForFile(rel));
+    }
+  }
+  if (sites.length === 0) {
+    return { ok: true, upgraded: 0, unresolved: 0, budgetExhausted: 0 };
+  }
+  const byLanguage = /* @__PURE__ */ new Map();
+  const srcToFiles = /* @__PURE__ */ new Map();
+  for (const site of sites) {
+    const group = byLanguage.get(site.language);
+    if (group === void 0) byLanguage.set(site.language, [site]);
+    else group.push(site);
+    const files = srcToFiles.get(site.srcQualifiedName);
+    if (files === void 0) srcToFiles.set(site.srcQualifiedName, /* @__PURE__ */ new Set([site.filePath]));
+    else files.add(site.filePath);
+  }
+  const configServers = params.lspConfig.servers ?? {};
+  const timeoutMs = params.lspConfig.timeoutMs ?? 3e3;
+  let remainingBudget = Math.max(1, Math.floor(params.lspConfig.maxRequestsPerRun ?? 500));
+  const rootUri = pathToFileURL(repoRoot).href;
+  const resolveContent = (filePath) => {
+    const absPath = path2.join(repoRoot, filePath);
+    if (lspPathEscapesRootSync(repoRoot, absPath)) return null;
+    try {
+      return readFileSync(absPath, "utf-8");
+    } catch {
+      return null;
+    }
+  };
+  let upgraded = 0;
+  let unresolved = 0;
+  let budgetExhausted = 0;
+  const degradations = [];
+  for (const [language, group] of byLanguage) {
+    if (remainingBudget <= 0) {
+      budgetExhausted += group.length;
+      continue;
+    }
+    const rawSpec = configServers[language] ?? DEFAULT_LSP_SERVERS[language];
+    if (rawSpec === void 0) {
+      degradations.push({
+        language,
+        code: "no_launch_spec",
+        message: `No LSP server configured for ${language} (${group.length} candidate call site(s)); set codingKnowledge.lsp.servers.${language}.`
+      });
+      unresolved += group.length;
+      continue;
+    }
+    const launchSpec = { command: rawSpec.command, args: rawSpec.args ?? [] };
+    const plan = mod.planLspUpgrades(group, { maxRequests: remainingBudget });
+    budgetExhausted += plan.budgetExhausted;
+    remainingBudget -= plan.requests.length;
+    if (plan.requests.length === 0) continue;
+    const plannedCountByFile = /* @__PURE__ */ new Map();
+    for (const req of plan.requests) {
+      if (req && typeof req === "object" && "filePath" in req && typeof req.filePath === "string") {
+        plannedCountByFile.set(req.filePath, (plannedCountByFile.get(req.filePath) ?? 0) + 1);
+      }
+    }
+    const connected = await mod.LspClient.connect({ launchSpec, rootUri, timeoutMs });
+    if (!connected.ok) {
+      const deg = connected.degradation;
+      const code = deg && typeof deg === "object" && "code" in deg && typeof deg.code === "string" ? deg.code : "connect_failed";
+      const message = deg && typeof deg === "object" && "detail" in deg && typeof deg.detail === "string" ? deg.detail : `LSP server for ${language} failed to connect.`;
+      degradations.push({ language, code, message });
+      unresolved += plan.requests.length;
+      remainingBudget += plan.requests.length;
+      continue;
+    }
+    const client = connected.client;
+    let skippedEdgesTotal = 0;
+    const skippedFiles = /* @__PURE__ */ new Set();
+    try {
+      const result = await mod.executeLspResolution(plan.requests, {
+        client,
+        workspaceRoot: repoRoot,
+        resolveContent,
+        nodeLocator: (filePath, byteOffset) => typeof params.store.findNodeBySpan === "function" ? params.store.findNodeBySpan(filePath, byteOffset) : null,
+        applyUpgrades: async (upgrades) => {
+          if (typeof params.store.upsertEdges !== "function") {
+            throw new Error("store.upsertEdges is not available");
+          }
+          const result2 = await params.store.upsertEdges(upgrades);
+          if (!result2.ok) {
+            degradations.push({
+              language,
+              code: "edge_write_failed",
+              message: `upsertEdges failed for ${language}: ${result2.code}.`
+            });
+            throw new Error(`upsertEdges failed: ${result2.code}`);
+          }
+          if (result2.skipped > 0) {
+            skippedEdgesTotal += result2.skipped;
+            for (const upgrade of upgrades) {
+              for (const file of srcToFiles.get(upgrade.srcQualifiedName) ?? []) {
+                skippedFiles.add(file);
+              }
+            }
+            degradations.push({
+              language,
+              code: "edges_skipped",
+              message: `upsertEdges persisted ${result2.persisted} and skipped ${result2.skipped} edge(s) for ${language} (unresolvable endpoints).`
+            });
+          }
+        },
+        reconcileLspEdges: (filePath, assertedEdges) => {
+          if (typeof params.store.reconcileLspEdges !== "function") return;
+          if (plannedCountByFile.get(filePath) !== gatheredCountByFile.get(filePath)) return;
+          if (skippedFiles.has(filePath)) return;
+          if ((filteredCountByFile.get(filePath) ?? 0) > 0 && !canPreserve) return;
+          params.store.reconcileLspEdges(filePath, [...assertedEdges, ...preservedEdgesForFile(filePath)]);
+        }
+      });
+      if (result && typeof result === "object" && "upgraded" in result && typeof result.upgraded === "number") {
+        upgraded += Math.max(0, result.upgraded - skippedEdgesTotal);
+        unresolved += "unresolved" in result && typeof result.unresolved === "number" ? result.unresolved : 0;
+        budgetExhausted += "budgetExhausted" in result && typeof result.budgetExhausted === "number" ? result.budgetExhausted : 0;
+        if ("degradation" in result && result.degradation && typeof result.degradation === "object") {
+          const rd = result.degradation;
+          degradations.push({
+            language,
+            code: "code" in rd && typeof rd.code === "string" ? rd.code : "lsp_degraded",
+            message: "detail" in rd && typeof rd.detail === "string" ? rd.detail : `LSP pass for ${language} degraded mid-run.`
+          });
+        }
+      } else {
+        unresolved += plan.requests.length;
+      }
+    } catch (err) {
+      const detail = displayErrorDetail(err);
+      return {
+        ok: false,
+        code: "lsp_resolution_error",
+        message: detail.length > 0 ? `LSP resolution failed: ${detail}.` : "LSP resolution failed."
+      };
+    } finally {
+      const disposable = client;
+      if (typeof disposable.dispose === "function") {
+        try {
+          await disposable.dispose();
+        } catch {
+        }
+      }
+    }
+  }
+  return {
+    ok: true,
+    upgraded,
+    unresolved,
+    budgetExhausted,
+    ...degradations.length > 0 ? { degradations } : {}
+  };
+}
+async function reportCodegraphIndexStatus(params) {
+  const mod = await resolveCodegraphModule();
+  if (mod === null) {
+    return { ok: false, code: "package_missing", message: "The @remnic/coding-graph package is not installed." };
+  }
+  if (typeof mod.getIndexStatus !== "function" || typeof mod.defaultCodingGitInvoker !== "function") {
+    return { ok: false, code: "runtime_unavailable", message: "getIndexStatus is not available in the installed @remnic/coding-graph." };
+  }
+  const git = mod.defaultCodingGitInvoker();
+  try {
+    const status = mod.getIndexStatus(params.store, git, params.repoRoot);
+    return { ok: true, status };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, code: "store_error", message: msg };
+  }
+}
+async function detectCodegraphChanges(params) {
+  const mod = await resolveCodegraphModule();
+  if (mod === null) {
+    return { ok: false, code: "package_missing", message: "The @remnic/coding-graph package is not installed." };
+  }
+  if (typeof mod.computeBlastRadius !== "function") {
+    return { ok: false, code: "runtime_unavailable", message: "computeBlastRadius is not available in the installed @remnic/coding-graph." };
+  }
+  let engine;
+  try {
+    if (typeof mod.createCodingGraphEngine !== "function") {
+      return { ok: false, code: "engine_unavailable", message: "createCodingGraphEngine is not exported by @remnic/coding-graph." };
+    }
+    engine = mod.createCodingGraphEngine();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, code: "engine_unavailable", message: `The coding-graph engine is not ready: ${msg}` };
+  }
+  void engine;
+  void params;
+  try {
+    const result = mod.computeBlastRadius(params.store, /* @__PURE__ */ new Set());
+    if (result && result.ok === true) {
+      return { ok: true, affected: result.affected ?? [] };
+    }
+    return { ok: false, code: result?.code ?? "store_error", message: "computeBlastRadius reported a failure." };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, code: "store_error", message: msg };
+  }
+}
+async function ingestCodegraphTraces(params) {
+  if (typeof params.store.upsertEdges !== "function") {
+    return {
+      ok: false,
+      code: "runtime_unavailable",
+      message: "The installed @remnic/coding-graph does not expose upsertEdges; traces cannot be persisted."
+    };
+  }
+  const edges = [];
+  let accepted = 0;
+  for (const trace of params.traces) {
+    const t = trace;
+    if (typeof t?.caller !== "string" || typeof t?.callee !== "string") {
+      continue;
+    }
+    accepted += 1;
+    edges.push({
+      srcQualifiedName: t.caller,
+      dstQualifiedName: t.callee,
+      type: "HTTP_CALLS",
+      confidence: typeof t.confidence === "number" && t.confidence >= 0 && t.confidence <= 1 ? t.confidence : 0.5,
+      provenance: "trace"
+    });
+  }
+  try {
+    const result = await params.store.upsertEdges(edges);
+    if (result.ok === true) {
+      return { ok: true, accepted, persisted: result.persisted, skipped: result.skipped };
+    }
+    return { ok: false, code: result.code, message: "store.upsertEdges reported a failure." };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, code: "store_error", message: msg };
+  }
+}
+function deriveCodegraphProjectId(repoRoot) {
+  return `root:${createHash("sha256").update(repoRoot).digest("hex").slice(0, 16)}`;
+}
+function resolveCodegraphProjectId(params) {
+  const { request, getCodingContext } = params;
+  const explicit = typeof request.project === "string" ? request.project.trim() : "";
+  if (explicit.length > 0) return explicit;
+  const sessionKey = typeof request.sessionKey === "string" ? request.sessionKey.trim() : "";
+  if (sessionKey.length > 0) {
+    const cc = getCodingContext(sessionKey);
+    if (cc !== null) return cc.projectId;
+  }
+  const repoRoot = typeof request.repoRoot === "string" ? request.repoRoot.trim() : "";
+  if (repoRoot.length > 0) return deriveCodegraphProjectId(repoRoot);
+  throw new CodegraphRuntimeError(
+    "project_required",
+    "codegraph: project must be supplied explicitly, via a session coding context, or alongside a repoRoot"
+  );
+}
+var CodegraphRuntimeError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CodegraphRuntimeError";
+    this.code = code;
+  }
+};
+
+// src/coding/decision-records.ts
+var DECISION_STATUSES = [
+  "proposed",
+  "accepted",
+  "superseded",
+  "rejected"
+];
+var ACTIVE_DECISION_STATUSES = /* @__PURE__ */ new Set([
+  "proposed",
+  "accepted"
+]);
+var DEFAULT_DECISION_STATUS = "proposed";
+var DECISION_STATUS_BY_VALUE = Object.freeze({
+  proposed: "proposed",
+  accepted: "accepted",
+  superseded: "superseded",
+  rejected: "rejected"
+});
+function isDecisionStatus(value) {
+  return typeof value === "string" && Object.prototype.hasOwnProperty.call(DECISION_STATUS_BY_VALUE, value);
+}
+var FRONTMATTER_KEYS = Object.freeze([
+  "id",
+  "title",
+  "status",
+  "context",
+  "decision",
+  "consequences",
+  "entityRefs",
+  "supersedes"
+]);
+function serializeDecisionRecord(record) {
+  const lines = ["---"];
+  for (const key of FRONTMATTER_KEYS) {
+    const present = key === "supersedes" ? record.supersedes !== void 0 : key === "consequences" ? record.consequences !== void 0 : true;
+    if (!present) continue;
+    lines.push(`${key}: ${encodeFrontmatterValue(key, record)}`);
+  }
+  lines.push("---", "");
+  if (record.context) lines.push(record.context);
+  lines.push("");
+  lines.push("# Decision");
+  lines.push("");
+  if (record.decision) lines.push(record.decision);
+  if (record.consequences !== void 0 && record.consequences.length > 0) {
+    lines.push("");
+    lines.push("# Consequences");
+    lines.push("");
+    lines.push(record.consequences);
+  }
+  if (record.entityRefs.length > 0) {
+    lines.push("");
+    lines.push("# Entity references");
+    for (const ref of record.entityRefs) lines.push(`- ${ref}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function encodeFrontmatterValue(key, record) {
+  if (key === "entityRefs") {
+    const refs = record.entityRefs;
+    if (refs.length === 0) return "[]";
+    const inner = refs.map((ref) => `"${escapeYamlString(ref)}"`).join(", ");
+    return `[${inner}]`;
+  }
+  if (key === "status") return `"${record.status}"`;
+  if (key === "supersedes") return `"${record.supersedes ?? ""}"`;
+  if (key === "consequences") return `"${escapeYamlString(record.consequences ?? "")}"`;
+  const value = record[key];
+  return `"${escapeYamlString(typeof value === "string" ? value : String(value))}"`;
+}
+function escapeYamlString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function parseDecisionRecord(raw) {
+  const { fields, body } = extractFrontmatter(raw);
+  for (const fieldKey of Object.keys(fields)) {
+    if (!FRONTMATTER_KEYS.includes(fieldKey)) {
+      throw new Error(
+        `decision record frontmatter contains unknown key '${fieldKey}'; valid keys are ${FRONTMATTER_KEYS.join(", ")}.`
+      );
+    }
+  }
+  const id = requireString(fields.id, "id");
+  const title = requireString(fields.title, "title");
+  const context = requireString(fields.context, "context");
+  const decision = requireString(fields.decision, "decision");
+  const consequences = fields.consequences === void 0 ? void 0 : requireString(fields.consequences, "consequences");
+  let status = DEFAULT_DECISION_STATUS;
+  if (fields.status !== void 0 && fields.status !== null) {
+    if (!isDecisionStatus(fields.status)) {
+      throw new Error(
+        `decision '${id}' has invalid status '${JSON.stringify(fields.status)}'; valid statuses are ${DECISION_STATUSES.join(", ")}.`
+      );
+    }
+    status = fields.status;
+  }
+  const entityRefs = parseEntityRefs(fields.entityRefs);
+  const supersedes = fields.supersedes === void 0 ? void 0 : requireString(fields.supersedes, "supersedes");
+  const record = {
+    id,
+    title,
+    status,
+    context,
+    decision,
+    consequences,
+    entityRefs,
+    ...supersedes !== void 0 ? { supersedes } : {}
+  };
+  void body;
+  return record;
+}
+function requireString(field, key) {
+  if (field === void 0 || field === null) {
+    throw new Error(`decision record frontmatter is missing required field '${key}'.`);
+  }
+  if (typeof field !== "string") {
+    throw new Error(
+      `decision record frontmatter field '${key}' must be a string; got ${JSON.stringify(field)}.`
+    );
+  }
+  return field;
+}
+function parseEntityRefs(field) {
+  if (field === void 0) return [];
+  if (!Array.isArray(field)) {
+    throw new Error(
+      `decision record frontmatter field 'entityRefs' must be an array of strings; got ${JSON.stringify(field)}.`
+    );
+  }
+  for (const entry of field) {
+    if (typeof entry !== "string") {
+      throw new Error(
+        `decision record frontmatter 'entityRefs' entries must be strings; got ${JSON.stringify(entry)}.`
+      );
+    }
+  }
+  return [...field];
+}
+function extractFrontmatter(raw) {
+  const text = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+  if (!text.startsWith("---\n")) {
+    throw new Error(
+      "decision record must start with a YAML frontmatter fence (`---\\n`); got a document with no leading fence."
+    );
+  }
+  const closeAt = text.indexOf("\n---", 4);
+  if (closeAt === -1) {
+    throw new Error(
+      "decision record frontmatter is missing its closing fence (`\\n---`); the document is truncated."
+    );
+  }
+  const yamlBody = text.slice(4, closeAt);
+  const after = text.slice(closeAt + 4);
+  const body = after.startsWith("\n") ? after.slice(1) : after;
+  return { fields: parseYamlMapping(yamlBody), body };
+}
+function parseYamlMapping(input) {
+  const fields = {};
+  for (const rawLine of input.split("\n")) {
+    const line = rawLine.trimEnd();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const colonAt = line.indexOf(":");
+    if (colonAt === -1) {
+      throw new Error(`decision record frontmatter line is not a key:value pair: "${line}".`);
+    }
+    const key = line.slice(0, colonAt).trim();
+    const valueText = line.slice(colonAt + 1).trim();
+    if (key.length === 0) {
+      throw new Error(`decision record frontmatter has an empty key in line: "${line}".`);
+    }
+    fields[key] = decodeScalar(valueText);
+  }
+  return fields;
+}
+function decodeScalar(valueText) {
+  if (valueText.length === 0) return "";
+  const lower = valueText.toLowerCase();
+  if (lower === "true") return true;
+  if (lower === "false") return false;
+  if (lower === "null" || lower === "~") return null;
+  if (/^-?\d+$/.test(valueText)) return Number(valueText);
+  if (/^".*"$/.test(valueText)) {
+    return valueText.slice(1, -1).replace(/\\\\/g, "\0").replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\u0000/g, "\\");
+  }
+  if (/^\[.*\]$/.test(valueText)) return parseFlowList(valueText);
+  return valueText;
+}
+function parseFlowList(valueText) {
+  const inner = valueText.slice(1, -1).trim();
+  if (inner.length === 0) return [];
+  const out = [];
+  let buf = "";
+  let inQuotes = false;
+  let escaped = false;
+  for (let i = 0; i < inner.length; i += 1) {
+    const c = inner[i];
+    if (escaped) {
+      buf += c;
+      escaped = false;
+      continue;
+    }
+    if (c === "\\") {
+      buf += c;
+      escaped = true;
+      continue;
+    }
+    if (c === '"') {
+      inQuotes = !inQuotes;
+      buf += c;
+      continue;
+    }
+    if (c === "," && !inQuotes) {
+      out.push(stripFlowStringQuotes(buf.trim()));
+      buf = "";
+      continue;
+    }
+    buf += c;
+  }
+  if (buf.length > 0) out.push(stripFlowStringQuotes(buf.trim()));
+  return out;
+}
+function stripFlowStringQuotes(value) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\\\/g, "\0").replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\u0000/g, "\\");
+  }
+  return value;
+}
+
+export {
+  createArchitectureCardSummariser,
+  buildArchitectureCard,
+  handleCodingArchitecture,
+  findArchitectureCardMemory,
+  createArchitectureVersioningHook,
+  codegraphSurfaceVisible,
+  resolveCodegraphDbPath,
+  getCodegraphStore,
+  listCodegraphProjects,
+  deleteCodegraphProject,
+  makeCodegraphRuntimeDelegates,
+  resolveCodegraphProjectId,
+  CodegraphRuntimeError,
+  DECISION_STATUSES,
+  ACTIVE_DECISION_STATUSES,
+  DEFAULT_DECISION_STATUS,
+  isDecisionStatus,
+  serializeDecisionRecord,
+  parseDecisionRecord
+};
+//# sourceMappingURL=chunk-QJCWK2A7.js.map