@remnic/core 9.3.693 → 9.3.694

package/dist/{chunk-MQTPUPLP.js → chunk-5A35EGHM.js}

@@ -11,7 +11,7 @@ import {
 } from "./chunk-ARV3AUOM.js";
 import {
   toRecallExplainJson
-} from "./chunk-2D27ODNX.js";
+} from "./chunk-B55EAZNF.js";
 import {
   applyTagFilter,
   normalizeTags,
@@ -46,7 +46,7 @@ import {
 } from "./chunk-FF4KLI5W.js";
 import {
   estimateRecallTokens
-} from "./chunk-AFWEUTMS.js";
+} from "./chunk-MOGFK2DU.js";
 import {
   recordObjectiveStateSnapshotsFromObservedMessages
 } from "./chunk-BMFZLLNI.js";
@@ -60,7 +60,7 @@ import {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact,
   runMemoryGovernance
-} from "./chunk-SAC5V6JT.js";
+} from "./chunk-MSUA4KAK.js";
 import {
   namespaceCollectionName
 } from "./chunk-E6BOD3UJ.js";
@@ -103,17 +103,17 @@ import {
   buildBriefing,
   parseBriefingFocus,
   parseBriefingWindow
-} from "./chunk-66HROLW5.js";
+} from "./chunk-P7IDNF7H.js";
 import {
   parseEntityFile
-} from "./chunk-VFVG4NS2.js";
+} from "./chunk-NXNUG7IA.js";
 import {
   stripAttributesSuffix
 } from "./chunk-SVOZFLIQ.js";
 import {
   DEFAULT_RECALL_DISCLOSURE,
   isRecallDisclosure
-} from "./chunk-DQHZA7Y3.js";
+} from "./chunk-U62ZGWU7.js";
 import {
   normalizeProjectionPreview,
   normalizeProjectionTags
@@ -175,7 +175,8 @@ import {
 import { stat as stat2 } from "fs/promises";
 import * as nodeFs from "fs/promises";
 import { constants as fsConstants } from "fs";
-import { createHash as createHash2 } from "crypto";
+import { readdirSync, unlinkSync } from "fs";
+import { createHash as createHash3 } from "crypto";
 import { ZodError } from "zod";
 
 // src/coding/decision-records.ts
@@ -1160,9 +1161,726 @@ function createArchitectureVersioningHook(enabled, maxVersionsPerPage, sidecarDi
   };
 }
 
+// src/coding/codegraph-runtime.ts
+import path2 from "path";
+import { createHash } from "crypto";
+var CODEGRAPH_SPECIFIER = "@remnic/coding-graph";
+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();
+var cachedModule;
+var moduleLoadPromise = null;
+function storeCacheKey(principalSafe, projectSafe, dbPath) {
+  return `${principalSafe}::${projectSafe}::${dbPath}`;
+}
+async function loadCodegraphModule() {
+  if (cachedModule !== void 0) return cachedModule;
+  if (moduleLoadPromise === null) {
+    moduleLoadPromise = (async () => {
+      try {
+        const mod = await import(CODEGRAPH_SPECIFIER);
+        if (mod && typeof mod === "object" && mod.GraphStore && typeof mod.GraphStore.open === "function") {
+          cachedModule = mod;
+          return cachedModule;
+        }
+        cachedModule = null;
+        return null;
+      } catch {
+        cachedModule = null;
+        return null;
+      }
+    })();
+  }
+  return moduleLoadPromise;
+}
+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 loadCodegraphModule();
+  if (mod === null) {
+    throw new CodegraphRuntimeError(
+      "package_missing",
+      "The @remnic/coding-graph package is not installed; install it to use codegraph tools."
+    );
+  }
+  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 })
+  };
+}
+async function runCodegraphReindex(params) {
+  const mod = await loadCodegraphModule();
+  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 reportCodegraphIndexStatus(params) {
+  const mod = await loadCodegraphModule();
+  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 loadCodegraphModule();
+  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/codegraph-surfaces.ts
+var CODEGRAPH_TOOL_NAMES = [
+  "index",
+  "list_projects",
+  "delete_project",
+  "index_status",
+  "search_graph",
+  "trace_path",
+  "detect_changes",
+  "query_graph",
+  "get_schema",
+  "get_snippet",
+  "get_architecture",
+  "search_code",
+  "manage_adr",
+  "ingest_traces"
+];
+var TOOL_NAME_SET = new Set(CODEGRAPH_TOOL_NAMES);
+function isCodegraphToolName(value) {
+  return typeof value === "string" && TOOL_NAME_SET.has(value);
+}
+var TRACE_DIRECTIONS = ["inbound", "outbound", "both"];
+var TRACE_DIRECTION_SET = new Set(TRACE_DIRECTIONS);
+var INDEX_MODES = ["auto", "full", "incremental"];
+var INDEX_MODE_SET = new Set(INDEX_MODES);
+var MANAGE_ADR_SUBCOMMANDS = DECISION_SUBCOMMANDS;
+async function handleCodegraphTool(request, ctx) {
+  if (!codegraphSurfaceVisible(ctx.config)) {
+    return disabledResponse(request.tool, "codegraph tools are disabled in config");
+  }
+  switch (request.tool) {
+    case "list_projects":
+      return handleListProjects(request, ctx);
+    case "get_schema":
+      return withStore(request, ctx, (store) => handleGetSchema(store, request.tool));
+    case "search_graph":
+      return withStore(request, ctx, (store) => handleSearchGraph(store, request, ctx));
+    case "search_code":
+      return withStore(request, ctx, (store) => handleSearchCode(store, request, ctx));
+    case "trace_path":
+      return withStore(request, ctx, (store) => handleTracePath(store, request, ctx));
+    case "get_snippet":
+      return withStore(request, ctx, (store) => handleGetSnippet(store, request, ctx));
+    case "query_graph":
+      return withStore(request, ctx, (store) => handleQueryGraph(store, request, ctx));
+    case "index_status":
+      return withStore(request, ctx, (store) => handleIndexStatus(store, request, ctx));
+    case "detect_changes":
+      return withStore(request, ctx, (store) => handleDetectChanges(store, request, ctx));
+    case "index":
+      return handleIndex(request, ctx);
+    case "delete_project":
+      return handleDeleteProject(request, ctx);
+    case "get_architecture":
+      return handleGetArchitecture(request, ctx);
+    case "manage_adr":
+      return handleManageAdr(request, ctx);
+    case "ingest_traces":
+      return withStore(request, ctx, (store) => handleIngestTraces(store, request, ctx));
+    default: {
+      const _exhaustive = request.tool;
+      void _exhaustive;
+      ctx.throwInputError(`unknown codegraph tool: ${request.tool}`);
+    }
+  }
+}
+function disabledResponse(tool, message) {
+  return { tool, ok: false, code: "disabled", message };
+}
+async function withStore(request, ctx, fn) {
+  let store;
+  try {
+    store = await ctx.resolveStore(request);
+  } catch (err) {
+    if (err instanceof CodegraphRuntimeError) {
+      return { tool: request.tool, ok: false, code: err.code, message: err.message };
+    }
+    throw err;
+  }
+  return fn(store);
+}
+async function handleListProjects(request, ctx) {
+  const projects = listCodegraphProjects({
+    config: ctx.config,
+    memoryDir: ctx.memoryDir,
+    principal: ctx.principal,
+    listDir: ctx.listDirs
+  });
+  return { tool: request.tool, ok: true, result: { projects } };
+}
+async function handleGetSchema(store, tool) {
+  const stats = store.schemaStats();
+  if (!stats.ok) {
+    return { tool, ok: false, code: stats.code, message: "schemaStats failed" };
+  }
+  return { tool, ok: true, result: stats };
+}
+async function handleSearchGraph(store, request, ctx) {
+  const query = requireString2(request.query, "query", ctx);
+  const limit = clampPositiveInteger(request.limit, 50, "limit", ctx);
+  const result = store.searchGraph({ namePattern: query, limit });
+  if (!result.ok) {
+    return { tool: request.tool, ok: false, code: result.code, message: "searchGraph failed" };
+  }
+  return { tool: request.tool, ok: true, result };
+}
+var SEARCH_CODE_KINDS = ["function", "class", "method"];
+async function handleSearchCode(store, request, ctx) {
+  const query = requireString2(request.query, "query", ctx);
+  const limit = clampPositiveInteger(request.limit, 50, "limit", ctx);
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const kind of SEARCH_CODE_KINDS) {
+    if (merged.length >= limit) break;
+    const result = store.searchGraph({ label: kind, namePattern: query, limit });
+    if (!result.ok) {
+      return { tool: request.tool, ok: false, code: result.code, message: "searchGraph failed" };
+    }
+    for (const hit of result.hits) {
+      const id = typeof hit?.nodeId === "string" ? hit.nodeId : JSON.stringify(hit);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      merged.push(hit);
+      if (merged.length >= limit) break;
+    }
+  }
+  return { tool: request.tool, ok: true, result: { hits: merged } };
+}
+async function handleTracePath(store, request, ctx) {
+  const start = requireString2(request.start, "start", ctx);
+  const direction = request.direction ?? "outbound";
+  if (!TRACE_DIRECTION_SET.has(direction)) {
+    ctx.throwInputError(
+      `direction must be one of ${TRACE_DIRECTIONS.join(", ")}; got ${JSON.stringify(direction)}`
+    );
+  }
+  const depth = clampPositiveInteger(request.depth ?? 2, 2, "depth", ctx);
+  const storeDirection = direction === "outbound" ? "outgoing" : direction === "inbound" ? "incoming" : direction;
+  const result = store.traverse({ start, direction: storeDirection, maxDepth: depth });
+  if (!result.ok) {
+    return { tool: request.tool, ok: false, code: result.code, message: "traverse failed" };
+  }
+  return { tool: request.tool, ok: true, result };
+}
+async function handleGetSnippet(store, request, ctx) {
+  const qualifiedName = requireString2(request.qualifiedName, "qualifiedName", ctx);
+  const result = await store.snippetFor({ qualifiedName });
+  if (!result.ok) {
+    return { tool: request.tool, ok: false, code: result.code, message: "snippetFor failed" };
+  }
+  return { tool: request.tool, ok: true, result };
+}
+async function handleQueryGraph(store, request, ctx) {
+  if (typeof request.query === "string" && isLikelyCypher(request.query)) {
+    ctx.throwInputError(
+      "codegraph_query_graph does not accept Cypher text; pass a structured query via structuredQuery (issue #1554 rejection table)"
+    );
+  }
+  if (request.structuredQuery === void 0) {
+    ctx.throwInputError("codegraph_query_graph requires structuredQuery");
+  }
+  const result = store.searchGraph(request.structuredQuery);
+  if (!result.ok) {
+    return { tool: request.tool, ok: false, code: result.code, message: "searchGraph failed" };
+  }
+  return { tool: request.tool, ok: true, result };
+}
+async function handleIndexStatus(store, request, ctx) {
+  const repoRoot = resolveRepoRoot(request, ctx);
+  if (!ctx.reportIndexStatus) {
+    return {
+      tool: request.tool,
+      ok: false,
+      code: "runtime_unavailable",
+      message: "index_status requires @remnic/coding-graph; the runtime is unavailable."
+    };
+  }
+  void store;
+  const outcome = await ctx.reportIndexStatus(store, repoRoot);
+  if (!outcome.ok) {
+    return { tool: request.tool, ok: false, code: outcome.code, message: outcome.message };
+  }
+  return { tool: request.tool, ok: true, result: outcome.status };
+}
+async function handleDetectChanges(store, request, ctx) {
+  const head = requireString2(request.head, "head", ctx);
+  if (!ctx.detectChanges) {
+    return {
+      tool: request.tool,
+      ok: false,
+      code: "runtime_unavailable",
+      message: "detect_changes requires @remnic/coding-graph; the runtime is unavailable."
+    };
+  }
+  const repoRoot = resolveRepoRoot(request, ctx);
+  void store;
+  const outcome = await ctx.detectChanges(store, repoRoot, head);
+  if (!outcome.ok) {
+    return { tool: request.tool, ok: false, code: outcome.code, message: outcome.message };
+  }
+  return { tool: request.tool, ok: true, result: { head, affected: outcome.affected } };
+}
+async function handleIndex(request, ctx) {
+  const repoRoot = requireString2(request.repoRoot, "repoRoot", ctx);
+  const modeRaw = request.mode ?? "auto";
+  if (!INDEX_MODE_SET.has(modeRaw)) {
+    ctx.throwInputError(`mode must be one of ${INDEX_MODES.join(", ")}; got ${JSON.stringify(modeRaw)}`);
+  }
+  const resolveReq = { ...request, repoRoot };
+  let store;
+  try {
+    store = await ctx.resolveStore(resolveReq);
+  } catch (err) {
+    if (err instanceof CodegraphRuntimeError) {
+      return { tool: request.tool, ok: false, code: err.code, message: err.message };
+    }
+    throw err;
+  }
+  if (!ctx.runReindex) {
+    return {
+      tool: request.tool,
+      ok: false,
+      code: "runtime_unavailable",
+      message: "index requires @remnic/coding-graph's reindex executor; the runtime is unavailable."
+    };
+  }
+  const outcome = await ctx.runReindex(store, repoRoot, modeRaw);
+  if (!outcome.ok) {
+    return { tool: request.tool, ok: false, code: outcome.code, message: outcome.message };
+  }
+  const stats = store.schemaStats();
+  return {
+    tool: request.tool,
+    ok: true,
+    result: {
+      repoRoot,
+      mode: outcome.mode,
+      filesIngested: outcome.filesIngested,
+      head: outcome.head,
+      stats
+    }
+  };
+}
+async function handleDeleteProject(request, ctx) {
+  const projectId = resolveProjectId(request, ctx);
+  if (request.confirm !== true) {
+    return {
+      tool: request.tool,
+      ok: false,
+      code: "confirm_required",
+      message: "codegraph_delete_project requires confirm: true (rule 48)"
+    };
+  }
+  try {
+    const result = await deleteCodegraphProject({
+      config: ctx.config,
+      memoryDir: ctx.memoryDir,
+      principal: ctx.principal,
+      projectId,
+      confirm: true,
+      removeFile: ctx.removeFile
+    });
+    return { tool: request.tool, ok: true, result };
+  } catch (err) {
+    if (err instanceof CodegraphRuntimeError) {
+      return { tool: request.tool, ok: false, code: err.code, message: err.message };
+    }
+    throw err;
+  }
+}
+async function handleGetArchitecture(request, ctx) {
+  const codingContext = resolveCodingContext(request, ctx);
+  const repoRoot = request.repoRoot ?? codingContext.rootPath;
+  const card = await ctx.buildArchitectureCard(repoRoot);
+  let stats;
+  try {
+    const store = await ctx.resolveStore(request);
+    stats = store.schemaStats();
+  } catch (err) {
+    if (err instanceof CodegraphRuntimeError) {
+      stats = { ok: false, code: err.code };
+    } else {
+      throw err;
+    }
+  }
+  return {
+    tool: request.tool,
+    ok: true,
+    result: { card, graphStats: stats }
+  };
+}
+async function handleManageAdr(request, ctx) {
+  const subcommand = request.subcommand;
+  if (typeof subcommand !== "string" || !MANAGE_ADR_SUBCOMMANDS.includes(subcommand)) {
+    ctx.throwInputError(
+      `manage_adr subcommand must be one of ${MANAGE_ADR_SUBCOMMANDS.join(", ")}; got ${JSON.stringify(subcommand)}`
+    );
+  }
+  const codingContext = resolveCodingContext(request, ctx);
+  if (!isDecisionRecordSurfaceEnabled(ctx.config.codingKnowledge, codingContext)) {
+    return disabledResponse(
+      request.tool,
+      "manage_adr requires codingKnowledge.enabled + decisionRecords + an attached coding context"
+    );
+  }
+  const decisionRequest = {
+    subcommand,
+    sessionKey: request.sessionKey,
+    id: request.id,
+    title: request.title,
+    status: request.status,
+    context: request.context,
+    decision: request.decision,
+    consequences: request.consequences,
+    entityRefs: request.entityRefs,
+    supersedesId: request.supersedesId
+  };
+  const result = await ctx.delegateDecisionRecord(decisionRequest);
+  return { tool: request.tool, ok: true, result };
+}
+async function handleIngestTraces(store, request, ctx) {
+  if (!Array.isArray(request.traces)) {
+    ctx.throwInputError("codegraph_ingest_traces requires traces: an array of call-site observations");
+  }
+  if (!ctx.ingestTraces) {
+    return {
+      tool: request.tool,
+      ok: false,
+      code: "runtime_unavailable",
+      message: "ingest_traces requires @remnic/coding-graph's store write path; the runtime is unavailable."
+    };
+  }
+  const outcome = await ctx.ingestTraces(store, request.traces);
+  if (!outcome.ok) {
+    return { tool: request.tool, ok: false, code: outcome.code, message: outcome.message };
+  }
+  return {
+    tool: request.tool,
+    ok: true,
+    result: {
+      accepted: outcome.accepted,
+      persisted: outcome.persisted
+    }
+  };
+}
+function requireString2(value, field, ctx) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    ctx.throwInputError(`codegraph: ${field} is required and must be a non-empty string`);
+  }
+  return value;
+}
+function clampPositiveInteger(value, defaultValue, field, ctx) {
+  if (value === void 0) return defaultValue;
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
+    ctx.throwInputError(`codegraph: ${field} must be a positive integer; got ${JSON.stringify(value)}`);
+  }
+  return Math.min(value, 200);
+}
+function resolveCodingContext(request, ctx) {
+  if (!request.sessionKey) {
+    ctx.throwInputError("codegraph tool requires a sessionKey with an attached coding context");
+  }
+  const codingContext = ctx.getCodingContext(request.sessionKey);
+  if (codingContext === null) {
+    ctx.throwInputError(
+      `no coding context attached to session ${request.sessionKey}; attach one via set_coding_context first`
+    );
+  }
+  return codingContext;
+}
+function resolveProjectId(request, ctx) {
+  if (typeof request.project === "string" && request.project.trim().length > 0) {
+    return request.project.trim();
+  }
+  return resolveCodingContext(request, ctx).projectId;
+}
+function resolveRepoRoot(request, ctx) {
+  if (typeof request.repoRoot === "string" && request.repoRoot.trim().length > 0) {
+    return request.repoRoot.trim();
+  }
+  return resolveCodingContext(request, ctx).rootPath;
+}
+function isLikelyCypher(input) {
+  return /^\s*(MATCH|RETURN|WHERE|CREATE|MERGE|DELETE|WITH|OPTIONAL|CALL|YIELD|UNWIND)\b/i.test(input);
+}
+
 // src/coding/session-delta.ts
 import { readFile as readFile2, writeFile, mkdir, rename } from "fs/promises";
-import path2 from "path";
+import path3 from "path";
 var MAX_DELTA_COMMITS = 20;
 var MAX_DELTA_FILES = 50;
 function computeSessionDelta(lastSeen, current) {
@@ -1215,10 +1933,10 @@ function formatSinceDate(iso) {
   const match = /^(\d{4}-\d{2}-\d{2})/.exec(iso);
   return match ? match[1] : iso;
 }
-var CODING_KNOWLEDGE_STATE_DIR = path2.join("state", "coding-knowledge");
+var CODING_KNOWLEDGE_STATE_DIR = path3.join("state", "coding-knowledge");
 function sessionDeltaStatePath(memoryDir, namespace) {
   const safe = sanitizeFragment(namespace) || "default";
-  return path2.join(memoryDir, CODING_KNOWLEDGE_STATE_DIR, `${safe}.json`);
+  return path3.join(memoryDir, CODING_KNOWLEDGE_STATE_DIR, `${safe}.json`);
 }
 async function readLastSeenState(statePath) {
   try {
@@ -1240,7 +1958,7 @@ async function writeLastSeenState(statePath, state) {
       `writeLastSeenState: invalid state (head=${JSON.stringify(state.head)}, at=${JSON.stringify(state.at)})`
     );
   }
-  const dir = path2.dirname(statePath);
+  const dir = path3.dirname(statePath);
   await mkdir(dir, { recursive: true });
   const tmp = `${statePath}.tmp-${process.pid}-${Date.now()}`;
   await writeFile(tmp, JSON.stringify(state, null, 2), "utf8");
@@ -1402,9 +2120,9 @@ async function deltaGet(request, ctx, codingContext) {
 }
 
 // src/procedural/procedure-miner.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { mkdir as mkdir2, rm, stat } from "fs/promises";
-import path3 from "path";
+import path4 from "path";
 var PROCEDURE_CLUSTER_ATTR_MAX = 500;
 var PROCEDURE_CLUSTER_LOCK_STALE_MS = 12e4;
 var PROCEDURE_CLUSTER_LOCK_TIMEOUT_MS = 3e4;
@@ -1415,7 +2133,7 @@ function clusterKey(record) {
   return `${goal}|${refs.join(",")}`;
 }
 function clusterKeyHash(cluster) {
-  return createHash("sha256").update(cluster).digest("hex");
+  return createHash2("sha256").update(cluster).digest("hex");
 }
 function isErrnoCode(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
@@ -1424,8 +2142,8 @@ function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function acquireClusterWriteLock(memoryDir, clusterHash) {
-  const lockRoot = path3.join(path3.resolve(memoryDir), "state", "procedure-miner-locks");
-  const lockDir = path3.join(lockRoot, `${clusterHash}.lock`);
+  const lockRoot = path4.join(path4.resolve(memoryDir), "state", "procedure-miner-locks");
+  const lockDir = path4.join(lockRoot, `${clusterHash}.lock`);
   await mkdir2(lockRoot, { recursive: true });
   const startedAt = Date.now();
   let attempts = 0;
@@ -1456,7 +2174,7 @@ async function acquireClusterWriteLock(memoryDir, clusterHash) {
   }
 }
 async function withClusterWriteLock(memoryDir, clusterHash, fn) {
-  const inProcessKey = `${path3.resolve(memoryDir)}:${clusterHash}`;
+  const inProcessKey = `${path4.resolve(memoryDir)}:${clusterHash}`;
   const previous = inProcessClusterWriteLocks.get(inProcessKey) ?? Promise.resolve();
   let releaseInProcess;
   const current = previous.catch(() => void 0).then(
@@ -2404,7 +3122,7 @@ var EngramAccessService = class {
     const snapshotForSerialization = {
       sessionKey: options.sessionKey ?? "",
       recordedAt: new Date(options.snapshot.capturedAt).toISOString(),
-      queryHash: createHash2("sha256").update(options.query).digest("hex"),
+      queryHash: createHash3("sha256").update(options.query).digest("hex"),
       queryLen: options.query.length,
       memoryIds,
       namespace,
@@ -4013,6 +4731,62 @@ var EngramAccessService = class {
       memory: this.serializeMemory(memory)
     };
   }
+  /**
+   * Codegraph parity tool delegate (issue #1554). All three surfaces (MCP,
+   * HTTP, CLI) arrive here via the codegraph_* boundary operations. The
+   * handler lives in coding/codegraph-surfaces.ts; this method just wires
+   * the context. Memory dir + principal + coding-context lookup come from
+   * the orchestrator/access-service fabric -- no handler-side state.
+   */
+  async codegraphTool(request, authenticatedPrincipal) {
+    const principal = authenticatedPrincipal ?? "default";
+    const memoryDir = this.orchestrator.config.memoryDir;
+    const ctx = {
+      config: this.orchestrator.config,
+      memoryDir,
+      principal,
+      getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk),
+      // Project resolution chokepoint lives in codegraph-runtime.ts so every
+      // store-backed tool derives the same id and the tagged error flows back
+      // as a structured response (issue #1554 threads 7/9/11). Thin wiring.
+      resolveStore: async (req) => {
+        const projectId = resolveCodegraphProjectId({
+          request: req,
+          getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk)
+        });
+        return getCodegraphStore({
+          config: this.orchestrator.config,
+          memoryDir,
+          principal,
+          projectId,
+          repoRoot: req.repoRoot
+        });
+      },
+      listDirs: (dir) => {
+        try {
+          return readdirSync(dir);
+        } catch {
+          return [];
+        }
+      },
+      removeFile: (filePath) => unlinkSync(filePath),
+      // propagate failures → deleteCodegraphProject classifies (thread 7)
+      throwInputError: (msg) => {
+        throw new EngramAccessInputError(msg);
+      },
+      delegateDecisionRecord: async (decisionRequest) => {
+        return this.codingDecision(decisionRequest, authenticatedPrincipal);
+      },
+      buildArchitectureCard: async (repoRoot) => {
+        return buildArchitectureCard(repoRoot, {
+          llmSummary: this.orchestrator.config.codingKnowledge?.architectureCardLlmSummary === true,
+          summariser: createArchitectureCardSummariser(this.fallbackLlmRef ?? this.localLlmRef)
+        });
+      },
+      ...makeCodegraphRuntimeDelegates()
+    };
+    return handleCodegraphTool(request, ctx);
+  }
   /** Whether the coding_decision tool should appear in tools/list (rule 39). */
   get decisionRecordSurfaceVisible() {
     return this.orchestrator.config.codingKnowledge?.enabled === true && this.orchestrator.config.codingKnowledge?.decisionRecords === true;
@@ -4051,6 +4825,14 @@ var EngramAccessService = class {
   get architectureCardSurfaceVisible() {
     return this.orchestrator.config.codingKnowledge?.enabled === true && this.orchestrator.config.codingKnowledge?.architectureCard === true;
   }
+  /**
+   * Whether the 14 codegraph parity tools should appear in tools/list
+   * (rule 39). Config-only -- runtime availability is checked at call time.
+   * When false the tools array is byte-identical to pre-feature.
+   */
+  get codegraphSurfaceVisible() {
+    return codegraphSurfaceVisible(this.orchestrator.config);
+  }
   /**
    * Thin delegate — handler logic in coding/architecture-surfaces.ts (#1548 PR3).
    * All three surfaces (MCP/HTTP/CLI) arrive here via the boundary operation.
@@ -6177,7 +6959,7 @@ ${next}`);
       sourceSessionKey: request.sessionKey,
       inputSummary: inputSummaryParts.length > 0 ? inputSummaryParts.join(" | ").slice(0, 500) : void 0,
       dryRun: request.dryRun === true,
-      promptHash: typeof request.sourcePrompt === "string" && request.sourcePrompt.length > 0 ? createHash2("sha256").update(request.sourcePrompt).digest("hex") : void 0
+      promptHash: typeof request.sourcePrompt === "string" && request.sourcePrompt.length > 0 ? createHash3("sha256").update(request.sourcePrompt).digest("hex") : void 0
     };
     const preview = this.orchestrator.previewMemoryActionEvent(event);
     if (request.dryRun === true) {
@@ -6654,7 +7436,7 @@ ${next}`);
   async offlineSyncSnapshot(options = {}) {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const storageHash = createHash2("sha256").update(storage.dir).digest("hex").slice(0, 16);
+    const storageHash = createHash3("sha256").update(storage.dir).digest("hex").slice(0, 16);
     const snapshotBuilder = options.includeContent === false && options.baseFiles && options.baseFiles.length > 0 ? buildOfflineSyncSnapshotFromBase : buildOfflineSyncSnapshot;
     const snapshot = await snapshotBuilder({
       root: storage.dir,
@@ -6674,7 +7456,7 @@ ${next}`);
   async offlineSyncSnapshotStream(options = {}) {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const storageHash = createHash2("sha256").update(storage.dir).digest("hex").slice(0, 16);
+    const storageHash = createHash3("sha256").update(storage.dir).digest("hex").slice(0, 16);
     return {
       namespace: resolvedNamespace,
       format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
@@ -6695,7 +7477,7 @@ ${next}`);
   async offlineSyncFiles(options) {
     const resolvedNamespace = this.resolveReadableNamespace(options.namespace, options.principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const storageHash = createHash2("sha256").update(storage.dir).digest("hex").slice(0, 16);
+    const storageHash = createHash3("sha256").update(storage.dir).digest("hex").slice(0, 16);
     try {
       const snapshot = await buildOfflineSyncSnapshotForPaths({
         root: storage.dir,
@@ -6932,6 +7714,7 @@ ${next}`);
 
 export {
   DECISION_SUBCOMMANDS,
+  isCodegraphToolName,
   DELTA_SUBCOMMANDS,
   computeProcedureStats,
   formatProcedureStatsText,
@@ -6940,4 +7723,4 @@ export {
   shapeMemorySummary,
   EngramAccessService
 };
-//# sourceMappingURL=chunk-MQTPUPLP.js.map
+//# sourceMappingURL=chunk-5A35EGHM.js.map