@remnic/core 9.63.6 → 9.63.7

package/src/coding/codegraph-runtime-loader.test.ts

@@ -0,0 +1,228 @@
+// Regression tests for issue #2478: the runtime bridge must resolve
+// @remnic/coding-graph through the shared loader
+// (optional-coding-graph.ts) -- ONE import, ONE cache, ONE contract
+// check -- and the miss path must surface the canonical install hint,
+// never a raw ERR_MODULE_NOT_FOUND.
+//
+// Both tests drive the REAL dynamic-import machinery in a child process
+// with a registered resolve hook (the established technique from
+// packages/remnic-cli/src/openclaw-managed-upgrade.test.ts):
+//
+//   1. pass-through hook that COUNTS resolutions of the specifier --
+//      the shared loader caches success, so a probe + a store open must
+//      resolve "@remnic/coding-graph" exactly once. A parallel loader
+//      in codegraph-runtime.ts resolves it a second time and fails.
+//   2. throwing hook that simulates the absent package -- the store
+//      open must reject with the tagged CodegraphRuntimeError whose
+//      message is the canonical install hint (buildCodingGraphInstallHint).
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const tsxCli = path.join(repoRoot, "node_modules", "tsx", "dist", "cli.mjs");
+const optionalLoaderSource = path.join(
+  repoRoot,
+  "packages",
+  "remnic-core",
+  "src",
+  "coding",
+  "optional-coding-graph.ts",
+);
+const runtimeSource = path.join(
+  repoRoot,
+  "packages",
+  "remnic-core",
+  "src",
+  "coding",
+  "codegraph-runtime.ts",
+);
+
+interface DriverReport {
+  opened?: boolean;
+  threw?: boolean;
+  name?: string;
+  code?: unknown;
+  message?: string;
+}
+
+function makeScratch(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function writeCountingResolveHook(root: string): { hookPath: string; logPath: string } {
+  const logPath = path.join(root, "resolves.log");
+  const hookPath = path.join(root, "count-resolves.mjs");
+  fs.writeFileSync(
+    hookPath,
+    `import { appendFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier === "@remnic/coding-graph") {
+    if (process.env.CODEGRAPH_RESOLVE_LOG) {
+      appendFileSync(process.env.CODEGRAPH_RESOLVE_LOG, specifier + "\\n");
+    }
+    try {
+      return await nextResolve(specifier, context);
+    } catch (err) {
+      if (err && err.code === "ERR_MODULE_NOT_FOUND" && process.env.CODEGRAPH_SOURCE_FALLBACK) {
+        // Worktree/base install where the optional peer is not linked:
+        // map the specifier to the workspace source so the import
+        // SUCCEEDS and the shared loader's success cache is observable.
+        return { url: pathToFileURL(process.env.CODEGRAPH_SOURCE_FALLBACK).href, shortCircuit: true };
+      }
+      throw err;
+    }
+  }
+  return nextResolve(specifier, context);
+}
+`,
+    "utf8",
+  );
+  return { hookPath, logPath };
+}
+
+function writeMissingPackageResolveHook(root: string): string {
+  const hookPath = path.join(root, "missing-coding-graph.mjs");
+  fs.writeFileSync(
+    hookPath,
+    `export async function resolve(specifier, context, nextResolve) {
+  if (specifier === "@remnic/coding-graph") {
+    const error = new Error("Cannot find package '@remnic/coding-graph' imported from test");
+    error.code = "ERR_MODULE_NOT_FOUND";
+    throw error;
+  }
+  return nextResolve(specifier, context);
+}
+`,
+    "utf8",
+  );
+  return hookPath;
+}
+
+function writeStoreOpenDriver(root: string): string {
+  const driverPath = path.join(root, "store-open.mts");
+  fs.writeFileSync(
+    driverPath,
+    `import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [, , runtimePath, optionalLoaderPath, scratch] = process.argv;
+// Prime the shared loader exactly like the real surfaces do (the
+// runtime-availability probe runs before any store open).
+const optional = await import(pathToFileURL(optionalLoaderPath).href);
+await optional.isCodingGraphInstalled();
+const runtime = await import(pathToFileURL(runtimePath).href);
+const memoryDir = path.join(scratch, "memory");
+mkdirSync(path.join(memoryDir, "codegraph", "loader-principal"), { recursive: true });
+const config = {
+  codingKnowledge: { enabled: true, codegraphTools: true, codegraphDbDir: "" },
+};
+const request = {
+  config,
+  memoryDir,
+  principal: "loader-principal",
+  projectId: "loader-test",
+};
+try {
+  const store = await runtime.getCodegraphStore(request);
+  const schemaVersion = store.schemaVersion();
+  await store.close();
+  console.log(JSON.stringify({ opened: true, schemaVersion }));
+} catch (err) {
+  const e = err instanceof Error ? err : new Error(String(err));
+  console.log(
+    JSON.stringify({ threw: true, name: e.name, code: e.code, message: e.message }),
+  );
+}
+`,
+    "utf8",
+  );
+  return driverPath;
+}
+
+
+function runChild(
+  scriptPath: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+): { status: number | null; stdout: string; stderr: string } {
+  const result = spawnSync(process.execPath, [tsxCli, scriptPath, ...args], {
+    encoding: "utf8",
+    cwd: repoRoot,
+    env: { ...process.env, ...env },
+    timeout: 60_000,
+  });
+  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+}
+
+function lastJsonLine(stdout: string): DriverReport {
+  const lines = stdout.trim().split(/\n/).filter(Boolean);
+  let line: string | undefined;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i].startsWith("{")) {
+      line = lines[i];
+      break;
+    }
+  }
+  assert.ok(line, `expected a JSON line in child stdout, got: ${stdout}`);
+  return JSON.parse(line) as DriverReport;
+}
+
+test("codegraph-runtime resolves @remnic/coding-graph exactly once (shared loader, no parallel import)", async () => {
+  // The counting hook maps the specifier to the workspace source when the
+  // optional peer is not linked, so the import SUCCEEDS in every install
+  // state. The shared loader then caches the success: a probe + a store
+  // open must resolve the specifier exactly once. A parallel loader in
+  // codegraph-runtime.ts imports the package again and fails this count.
+  const root = makeScratch("remnic-2478-single-load-");
+  try {
+    const { hookPath, logPath } = writeCountingResolveHook(root);
+    const driver = writeStoreOpenDriver(root);
+    const result = runChild(driver, [runtimeSource, optionalLoaderSource, root], {
+      CODEGRAPH_RESOLVE_LOG: logPath,
+      CODEGRAPH_SOURCE_FALLBACK: path.join(repoRoot, "packages", "coding-graph", "src", "index.ts"),
+      NODE_OPTIONS: `--experimental-loader=${pathToFileURL(hookPath).href} --conditions=remnic-source`,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const report = lastJsonLine(result.stdout);
+    assert.equal(report.opened, true, `store must open against the loaded module: ${JSON.stringify(report)}`);
+    const resolves = fs.existsSync(logPath)
+      ? fs.readFileSync(logPath, "utf8").trim().split(/\n/).filter(Boolean)
+      : [];
+    assert.equal(
+      resolves.length,
+      1,
+      `the shared loader must resolve "@remnic/coding-graph" exactly once; saw ${resolves.length} resolutions -- a second resolve means codegraph-runtime still imports the package in parallel`,
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("codegraph-runtime miss path throws the canonical install hint, not raw MODULE_NOT_FOUND", async () => {
+  // The throwing resolve hook simulates the absent package even on a dev
+  // workspace where it is installed, so this runs everywhere.
+  const root = makeScratch("remnic-2478-miss-");
+  try {
+    const hookPath = writeMissingPackageResolveHook(root);
+    const driver = writeStoreOpenDriver(root);
+    const result = runChild(driver, [runtimeSource, optionalLoaderSource, root], {
+      NODE_OPTIONS: `--experimental-loader=${pathToFileURL(hookPath).href} --conditions=remnic-source`,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const report = lastJsonLine(result.stdout);
+    assert.equal(report.threw, true, `store open must fail when the package is absent: ${JSON.stringify(report)}`);
+    assert.equal(report.code, "package_missing");
+    assert.match(report.message ?? "", /npm install @remnic\/coding-graph/);
+    assert.doesNotMatch(report.message ?? "", /ERR_MODULE_NOT_FOUND|Cannot find module/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/coding/codegraph-runtime.ts

@@ -9,9 +9,11 @@
  * dependency that hosts opt into. Every code path that needs a GraphStore
  * calls {@link getCodegraphStore} here; this module owns:
  *
- *   - the loader boundary (one place that dynamically imports the optional
- *     package; CLAUDE.md rule 57 / AGENTS.md rule 44 documented exception --
- *     the optional peer genuinely does not exist on every install);
+ *   - the store-module boundary — @remnic/coding-graph is imported by the
+ *     ONE shared loader (optional-coding-graph.ts; single cache and
+ *     contract check per process). This module narrows that shared module
+ *     to the runtime's GraphStore view; it never imports the package
+ *     itself;
  *   - per-project GraphStore caching (one open SQLite handle per
  *     `(principal, projectId)` pair, lifecycle-tracked so a host process can
  *     close them on shutdown);
@@ -30,20 +32,14 @@ import { createHash } from "node:crypto";
 import { expandTildePath } from "../utils/path.js";
 
 import type { PluginConfig, CodingKnowledgeConfig, CodingContext } from "../types.js";
-import { isCodingGraphInstalled } from "./optional-coding-graph.js";
+import { buildCodingGraphInstallHint, isCodingGraphInstalled, tryLoadCodingGraphModule } from "./optional-coding-graph.js";
 import { displayErrorDetail } from "../runtime/better-sqlite.js";
 // Type-only reference to the surface context shape (ts-import-type rule).
 // Erased at compile time, so the runtime → surfaces → runtime import cycle is
 // type-only and has no runtime effect.
 import type { CodegraphSurfaceContext } from "./codegraph-surfaces.js";
 
-// Lazy-loaded optional package -- see file header. The dynamic import below
-// is the documented exception to the static-import rule: @remnic/coding-graph
-// is an optional peer dependency that is genuinely absent on base installs,
-// so a static import would either fail the base install or be bundled into
-// @remnic/core's dist. The specifier is composed from string literals to
-// keep this a runtime-only reference.
-const CODEGRAPH_SPECIFIER = "@remnic/" + "coding-graph";
+
 
 /**
  * Minimal structural shape of the @remnic/coding-graph public surface this
@@ -270,8 +266,6 @@ interface CachedStore {
 }
 
 const storeCache = new Map<string, CachedStore>();
-let cachedModule: CodegraphModule | null | undefined;
-let moduleLoadPromise: Promise<CodegraphModule | null> | null = null;
 
 function storeCacheKey(principalSafe: string, projectSafe: string, dbPath: string): string {
   // Thread 8 (issue #1554): include the resolved DB path so two configs
@@ -282,29 +276,24 @@ function storeCacheKey(principalSafe: string, projectSafe: string, dbPath: strin
 }
 
 /**
- * Dynamically import the optional package ONCE per process. Subsequent
- * callers await the same promise. Missing/incompatible installs collapse
- * to `null` (graceful degradation -- surfaces translate to a clean hint).
+ * Narrow the module served by the shared loader (optional-coding-graph.ts)
+ * to this runtime's structural view. The shared loader owns the single
+ * dynamic import, cache, and miss/incompatible diagnostics; this predicate
+ * only checks the GraphStore capability the runtime needs. A missing,
+ * broken, or engine-incompatible install collapses to `null` (graceful
+ * degradation -- surfaces translate to the install hint).
  */
-async function loadCodegraphModule(): Promise<CodegraphModule | null> {
-  if (cachedModule !== undefined) return cachedModule;
-  if (moduleLoadPromise === null) {
-    moduleLoadPromise = (async () => {
-      try {
-        const mod = (await import(CODEGRAPH_SPECIFIER)) as Partial<CodegraphModule>;
-        if (mod && typeof mod === "object" && mod.GraphStore && typeof mod.GraphStore.open === "function") {
-          cachedModule = mod as CodegraphModule;
-          return cachedModule;
-        }
-        cachedModule = null;
-        return null;
-      } catch {
-        cachedModule = null;
-        return null;
-      }
-    })();
-  }
-  return moduleLoadPromise;
+function isCodegraphModule(value: object): value is CodegraphModule {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Record<string, unknown>;
+  const graphStore = candidate.GraphStore as { open?: unknown } | undefined;
+  return graphStore !== undefined && typeof graphStore.open === "function";
+}
+
+async function resolveCodegraphModule(): Promise<CodegraphModule | null> {
+  const mod = await tryLoadCodingGraphModule();
+  if (mod === null || !isCodegraphModule(mod)) return null;
+  return mod;
 }
 
 /**
@@ -332,12 +321,9 @@ export async function getCodegraphStore(params: {
       "codegraph tools are disabled (codingKnowledge.enabled or codingKnowledge.codegraphTools is false)",
     );
   }
-  const mod = await loadCodegraphModule();
+  const mod = await resolveCodegraphModule();
   if (mod === null) {
-    throw new CodegraphRuntimeError(
-      "package_missing",
-      "The @remnic/coding-graph package is not installed; install it to use codegraph tools.",
-    );
+    throw new CodegraphRuntimeError("package_missing", buildCodingGraphInstallHint());
   }
   // Key the cache on SANITIZED values AND the resolved DB path (thread 8):
   // two different raw identifiers that sanitize to the same path segment
@@ -533,7 +519,7 @@ export async function runCodegraphReindex(params: {
   readonly repoRoot: string;
   readonly mode: string;
 }): Promise<CodegraphDelegateOutcome<{ mode: string; filesIngested: number; head: string | null }>> {
-  const mod = await loadCodegraphModule();
+  const mod = await resolveCodegraphModule();
   if (mod === null) {
     return { ok: false, code: "package_missing", message: "The @remnic/coding-graph package is not installed." };
   }
@@ -676,7 +662,7 @@ export async function runCodegraphLspResolution(params: {
     }
   | { ok: false; code: string; message: string }
 > {
-  const mod = await loadCodegraphModule();
+  const mod = await resolveCodegraphModule();
   if (mod === null) {
     return { ok: false, code: "package_missing", message: "@remnic/coding-graph is not installed." };
   }
@@ -1112,7 +1098,7 @@ export async function reportCodegraphIndexStatus(params: {
   readonly store: CodegraphStore;
   readonly repoRoot: string;
 }): Promise<CodegraphDelegateOutcome<{ status: Record<string, unknown> }>> {
-  const mod = await loadCodegraphModule();
+  const mod = await resolveCodegraphModule();
   if (mod === null) {
     return { ok: false, code: "package_missing", message: "The @remnic/coding-graph package is not installed." };
   }
@@ -1140,7 +1126,7 @@ export async function detectCodegraphChanges(params: {
   readonly repoRoot: string;
   readonly head: string;
 }): Promise<CodegraphDelegateOutcome<{ affected: readonly unknown[] }>> {
-  const mod = await loadCodegraphModule();
+  const mod = await resolveCodegraphModule();
   if (mod === null) {
     return { ok: false, code: "package_missing", message: "The @remnic/coding-graph package is not installed." };
   }
@@ -1229,12 +1215,6 @@ export async function ingestCodegraphTraces(params: {
   }
 }
 
-/** Test seam: reset the module cache so a fresh import can be observed. */
-export function __resetCodegraphRuntimeForTest(): void {
-  cachedModule = undefined;
-  moduleLoadPromise = null;
-  storeCache.clear();
-}
 
 /**
  * Derive a stable per-repo project id from an absolute repoRoot (issue #1554

package/src/coding/codegraph-surfaces.ts

@@ -32,11 +32,11 @@ import {
 import {
   DECISION_SUBCOMMANDS,
   handleCodingDecision,
-  isDecisionRecordSurfaceEnabled,
   type DecisionSurfaceContext,
   type DecisionSurfaceRequest,
   type DecisionSurfaceResponse,
 } from "./decision-surfaces.js";
+import { isCodingKnowledgeFeatureEnabled } from "./coding-knowledge-config.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Canonical tool names — mirror the external codebase-memory-mcp surface
@@ -674,7 +674,7 @@ async function handleManageAdr(
   // done-when) asserts that `manage_adr record` and `coding_decision record`
   // write byte-identical records -- both routes call handleCodingDecision.
   const codingContext = resolveCodingContext(request, ctx);
-  if (!isDecisionRecordSurfaceEnabled(ctx.config.codingKnowledge, codingContext)) {
+  if (!isCodingKnowledgeFeatureEnabled(ctx.config.codingKnowledge, "decisionRecords", codingContext)) {
     return disabledResponse(
       request.tool,
       "manage_adr requires codingKnowledge.enabled + decisionRecords + an attached coding context",

package/src/coding/coding-knowledge-config.ts

@@ -21,7 +21,7 @@
  * the existing `ENGRAM_*` env vars from earlier releases do not pair them up.
  */
 
-import type { CodingKnowledgeConfig, CodingGraphLspConfig } from "../types.js";
+import type { CodingContext, CodingGraphLspConfig, CodingKnowledgeConfig } from "../types.js";
 import { TIER_1_LANGUAGES } from "./coding-graph-types.js";
 import { coerceBool } from "../connectors/coerce.js";
 
@@ -81,6 +81,40 @@ export function parseCodingKnowledgeConfig(raw: unknown): CodingKnowledgeConfig
   };
 }
 
+// ──────────────────────────────────────────────────────────────────────────
+// Shared surface gates (rule 39: ONE predicate pair, identical on every
+// surface — issue #2478 dedupe). Each Track A surface used to carry its own
+// copy of this logic; they all resolve here now. The booleans are already
+// strict-coerced by parseCodingKnowledgeConfig, so `=== true` is safe here.
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Boolean feature switches governed by the master `codingKnowledge.enabled` gate. */
+export type CodingKnowledgeFeatureFlag = "decisionRecords" | "architectureCard" | "sessionDelta";
+
+/**
+ * Config-only visibility gate — used by the MCP constructor to decide
+ * whether a coding tool is advertised in `tools/list`. True only when the
+ * master gate AND the feature switch are both on.
+ */
+export function isCodingKnowledgeFeatureVisible(
+  config: CodingKnowledgeConfig,
+  feature: CodingKnowledgeFeatureFlag,
+): boolean {
+  return config.enabled === true && config[feature] === true;
+}
+
+/**
+ * Full call-time gate: visibility PLUS an attached coding context
+ * (project/branch-scoped session). Handlers check this before dispatch.
+ */
+export function isCodingKnowledgeFeatureEnabled(
+  config: CodingKnowledgeConfig,
+  feature: CodingKnowledgeFeatureFlag,
+  codingContext: CodingContext | null | undefined,
+): boolean {
+  return isCodingKnowledgeFeatureVisible(config, feature) && codingContext != null;
+}
+
 /**
  * Read the optional `codingKnowledge.lsp` sub-object. Absent → empty
  * spread (no own key). Present-but-malformed (string/number/array) is

package/src/coding/decision-surfaces.test.ts

@@ -21,12 +21,11 @@ import { EngramMcpServer } from "../access-mcp.js";
 import {
   DECISION_SUBCOMMANDS,
   formatDecisionSubcommands,
-  isDecisionRecordSurfaceEnabled,
-  isDecisionRecordSurfaceVisible,
   isDecisionSubcommand,
   type DecisionSurfaceRequest,
   type DecisionSurfaceResponse,
 } from "./decision-surfaces.js";
+import { isCodingKnowledgeFeatureEnabled, isCodingKnowledgeFeatureVisible } from "./coding-knowledge-config.js";
 import type { CodingContext, CodingKnowledgeConfig, PluginConfig } from "../types.js";
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -104,28 +103,28 @@ function makeMockServiceWithConfig(
 // ──────────────────────────────────────────────────────────────────────────
 
 test("gate: disabled when config.enabled is false", () => {
-  assert.equal(isDecisionRecordSurfaceEnabled(GATE_OFF_CONFIG, CODING_CONTEXT), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(GATE_OFF_CONFIG, "decisionRecords", CODING_CONTEXT), false);
 });
 
 test("gate: disabled when decisionRecords is false", () => {
   const cfg: CodingKnowledgeConfig = { ...GATE_ON_CONFIG, decisionRecords: false };
-  assert.equal(isDecisionRecordSurfaceEnabled(cfg, CODING_CONTEXT), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(cfg, "decisionRecords", CODING_CONTEXT), false);
 });
 
 test("gate: disabled when no coding context attached", () => {
-  assert.equal(isDecisionRecordSurfaceEnabled(GATE_ON_CONFIG, null), false);
-  assert.equal(isDecisionRecordSurfaceEnabled(GATE_ON_CONFIG, undefined), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(GATE_ON_CONFIG, "decisionRecords", null), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(GATE_ON_CONFIG, "decisionRecords", undefined), false);
 });
 
 test("gate: enabled only when all three conditions hold", () => {
-  assert.equal(isDecisionRecordSurfaceEnabled(GATE_ON_CONFIG, CODING_CONTEXT), true);
+  assert.equal(isCodingKnowledgeFeatureEnabled(GATE_ON_CONFIG, "decisionRecords", CODING_CONTEXT), true);
 });
 
 test("visibility gate: config-only check for tools/list construction", () => {
-  assert.equal(isDecisionRecordSurfaceVisible(GATE_OFF_CONFIG), false);
-  assert.equal(isDecisionRecordSurfaceVisible(GATE_ON_CONFIG), true);
+  assert.equal(isCodingKnowledgeFeatureVisible(GATE_OFF_CONFIG, "decisionRecords"), false);
+  assert.equal(isCodingKnowledgeFeatureVisible(GATE_ON_CONFIG, "decisionRecords"), true);
   assert.equal(
-    isDecisionRecordSurfaceVisible({ ...GATE_ON_CONFIG, decisionRecords: false }),
+    isCodingKnowledgeFeatureVisible({ ...GATE_ON_CONFIG, decisionRecords: false }, "decisionRecords"),
     false,
   );
 });

package/src/coding/decision-surfaces.ts

@@ -24,6 +24,7 @@ import {
 import { log } from "../logger.js";
 import { composeMemoryEnvelope, type SealedMemoryEnvelope } from "../write-envelope.js";
 import type { MemoryWriteResult } from "../storage.js";
+import { isCodingKnowledgeFeatureEnabled } from "./coding-knowledge-config.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Subcommands
@@ -56,45 +57,6 @@ export function formatDecisionSubcommands(): string {
   return DECISION_SUBCOMMANDS.join(", ");
 }
 
-// ──────────────────────────────────────────────────────────────────────────
-// Gate predicate — rule 39: one predicate, identical on every surface
-// ──────────────────────────────────────────────────────────────────────────
-
-/**
- * The single decision-record surface gate. Returns `true` only when:
- *  1. `codingKnowledge.enabled` is on (the master Track A gate),
- *  2. `codingKnowledge.decisionRecords` is on (the feature switch), AND
- *  3. A coding context is attached (the session is project/branch scoped —
- *     decision records live *in* the coding namespace, rule 42).
- *
- * Every surface — MCP `engram.coding_decision`, HTTP
- * `POST /engram/v1/coding/decisions`, CLI `engram-access decision` — MUST call
- * this predicate (or the handler that embeds it) before dispatching. The
- * tool-visibility gate in the MCP constructor checks conditions 1–2 only
- * (coding context is per-session and cannot be evaluated at construction
- * time); the call-time gate checks all three.
- */
-export function isDecisionRecordSurfaceEnabled(
-  config: CodingKnowledgeConfig,
-  codingContext: CodingContext | null | undefined,
-): boolean {
-  return (
-    config.enabled === true &&
-    config.decisionRecords === true &&
-    codingContext != null
-  );
-}
-
-/**
- * Config-only visibility gate — used by the MCP constructor to decide whether
- * to advertise `engram.coding_decision` in `tools/list`. When this returns
- * `false` the tools array is byte-identical to pre-feature (rule 39).
- */
-export function isDecisionRecordSurfaceVisible(
-  config: CodingKnowledgeConfig,
-): boolean {
-  return config.enabled === true && config.decisionRecords === true;
-}
 
 // ──────────────────────────────────────────────────────────────────────────
 // Surface request / response shapes
@@ -228,7 +190,7 @@ export async function handleCodingDecision(
   const codingContext = request.sessionKey
     ? ctx.getCodingContext(request.sessionKey)
     : null;
-  if (!isDecisionRecordSurfaceEnabled(ctx.codingKnowledge, codingContext)) {
+  if (!isCodingKnowledgeFeatureEnabled(ctx.codingKnowledge, "decisionRecords", codingContext)) {
     ctx.throwInputError(
       "coding_decision requires codingKnowledge.enabled, codingKnowledge.decisionRecords, and an attached coding context",
     );

package/src/coding/session-delta-surfaces.test.ts

@@ -18,11 +18,10 @@ import {
   formatDeltaSubcommands,
   handleCodingDelta,
   isDeltaSubcommand,
-  isSessionDeltaSurfaceEnabled,
-  isSessionDeltaSurfaceVisible,
   type DeltaSurfaceContext,
   type DeltaSurfaceStorage,
 } from "./session-delta-surfaces.js";
+import { isCodingKnowledgeFeatureEnabled, isCodingKnowledgeFeatureVisible } from "./coding-knowledge-config.js";
 import type {
   CodingKnowledgeConfig,
   CodingContext,
@@ -111,28 +110,28 @@ test("isDeltaSubcommand: narrows valid + rejects unknown", () => {
 });
 
 test("gate: surface enabled when config + sessionDelta + coding context all true", () => {
-  assert.equal(isSessionDeltaSurfaceEnabled(DEFAULT_CONFIG, CODING_CONTEXT), true);
+  assert.equal(isCodingKnowledgeFeatureEnabled(DEFAULT_CONFIG, "sessionDelta", CODING_CONTEXT), true);
 });
 
 test("gate: surface disabled when master gate off", () => {
   const config: CodingKnowledgeConfig = { ...DEFAULT_CONFIG, enabled: false };
-  assert.equal(isSessionDeltaSurfaceEnabled(config, CODING_CONTEXT), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(config, "sessionDelta", CODING_CONTEXT), false);
 });
 
 test("gate: surface disabled when sessionDelta off", () => {
   const config: CodingKnowledgeConfig = { ...DEFAULT_CONFIG, sessionDelta: false };
-  assert.equal(isSessionDeltaSurfaceEnabled(config, CODING_CONTEXT), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(config, "sessionDelta", CODING_CONTEXT), false);
 });
 
 test("gate: surface disabled when no coding context", () => {
-  assert.equal(isSessionDeltaSurfaceEnabled(DEFAULT_CONFIG, null), false);
-  assert.equal(isSessionDeltaSurfaceEnabled(DEFAULT_CONFIG, undefined), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(DEFAULT_CONFIG, "sessionDelta", null), false);
+  assert.equal(isCodingKnowledgeFeatureEnabled(DEFAULT_CONFIG, "sessionDelta", undefined), false);
 });
 
 test("visibility gate: config-only check mirrors full gate minus context", () => {
-  assert.equal(isSessionDeltaSurfaceVisible(DEFAULT_CONFIG), true);
-  assert.equal(isSessionDeltaSurfaceVisible({ ...DEFAULT_CONFIG, enabled: false }), false);
-  assert.equal(isSessionDeltaSurfaceVisible({ ...DEFAULT_CONFIG, sessionDelta: false }), false);
+  assert.equal(isCodingKnowledgeFeatureVisible(DEFAULT_CONFIG, "sessionDelta"), true);
+  assert.equal(isCodingKnowledgeFeatureVisible({ ...DEFAULT_CONFIG, enabled: false }, "sessionDelta"), false);
+  assert.equal(isCodingKnowledgeFeatureVisible({ ...DEFAULT_CONFIG, sessionDelta: false }, "sessionDelta"), false);
 });
 
 // ──────────────────────────────────────────────────────────────────────────