candor-ts 0.8.2 → 0.8.4

package/lsp.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * candor-lsp — candor's effect map as a Language Server (AGENT-SURFACE-DESIGN bet 2, P1): the report,
+ * rendered where the code is.
+ *
+ *   • CodeLens per effectful function: `⚡ Db, Net · blast radius 12` — the transitive effect set and
+ *     how many functions transitively call it (who is affected if it changes).
+ *   • Diagnostics: the repo's architecture-policy verdict (the §6.2 gate, resolved from CANDOR_POLICY
+ *     or the checked-in .candor/config — spec §3.4) as squiggles at each violating function's line.
+ *   • Hover: effect PROVENANCE — for each inherited effect, the `path` hop chain to the function that
+ *     performs it directly ("Net via mid → leaf (source)"), plus unknownWhy when the fn discloses opacity.
+ *
+ * The server is a pure CONSUMER of the spec report envelope + callgraph sidecar (any engine — JVM /
+ * Rust / TS / Swift / agents; the same read layer as candor-mcp), and it never scans (the analyzer
+ * self-boundary, spec §7.12): whatever refreshes the report (candor-ts-watch, the Claude Code stop
+ * hook, a build step) refreshes the lenses — reports are re-read per request, so freshness is free.
+ * A stale report is a stale map, disclosed by its own provenance (§2.1), never re-derived here.
+ *
+ * Report prefix resolution: initializationOptions.report → $CANDOR_REPORT → <workspace>/.candor/report.
+ * Transport: LSP stdio (Content-Length framed JSON-RPC 2.0).
+ *
+ * Editor wiring (no dedicated extension needed where the editor speaks LSP natively):
+ *   helix   languages.toml:  language-server.candor = { command = "candor-lsp" }
+ *   neovim  vim.lsp.start({ name = "candor", cmd = { "candor-lsp" } })
+ *   VS Code needs a thin client extension — a later slice.
+ */
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import nodePath from "node:path";
+import { fileURLToPath } from "node:url";
+import * as Q from "./query-core.mjs";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy } from "./policy.mjs";
+
+// Version: from the sibling package.json when running inside the npm package; a single-file BUNDLE of
+// this server (the IDE-plugin embedding) has no sibling package.json — fall back rather than crash.
+let VERSION = "bundled";
+try { VERSION = createRequire(import.meta.url)("./package.json").version; } catch { /* bundled */ }
+
+// ---- state (set at initialize) ---------------------------------------------------------------------
+let rootPath = null;
+let reportPrefix = process.env.CANDOR_REPORT || process.argv[2] || null;
+
+function hasReport(p) {
+  if (!p) return false;
+  if (fs.existsSync(`${p}.json`)) return true;
+  const base = nodePath.basename(p);
+  try {
+    return fs.readdirSync(nodePath.dirname(p) || ".").some((f) => f.startsWith(base + ".") && f.endsWith(".json") && Q.isReport(f));
+  } catch { return false; }
+}
+
+// ---- fn → document mapping --------------------------------------------------------------------------
+// A report `loc` is `<file>:<line>[:col…]` where <file> is either a repo-relative PATH (the scan-source
+// engines) or a BARE filename (JVM bytecode SourceFile) — for the bare form the path is rebuilt from the
+// fn's package segments, the same rule candor-sarif ships. Documents are matched by path SUFFIX (the
+// workspace root need not equal the report's root).
+function locParts(loc) {
+  if (typeof loc !== "string") return null;
+  const m = loc.match(/^(.*?):(\d+)/);
+  return m ? { file: m[1], line: Math.max(0, parseInt(m[2], 10) - 1) } : null;
+}
+function candidatePaths(fn, file) {
+  if (file.includes("/")) return [file];
+  const parts = fn.split(".");
+  const cands = [file];
+  if (parts.length >= 3) cands.unshift(parts.slice(0, -2).join("/") + "/" + file);
+  return cands;
+}
+function docMatches(docPath, fn, file) {
+  const norm = docPath.split(nodePath.sep).join("/");
+  return candidatePaths(fn, file).some((c) => norm === c || norm.endsWith("/" + c));
+}
+/** Every report entry whose loc maps into this document: [{ entry, line }]. Loaded FRESH per call. */
+function entriesInDoc(docPath) {
+  if (!hasReport(reportPrefix)) return null;
+  const out = [];
+  for (const e of Q.loadReport(reportPrefix)) {
+    const lp = e.loc && locParts(e.loc);
+    if (lp && docMatches(docPath, e.fn, lp.file)) out.push({ entry: e, line: lp.line });
+  }
+  return out;
+}
+
+// ---- CodeLens ---------------------------------------------------------------------------------------
+function codeLenses(docPath) {
+  const found = entriesInDoc(docPath);
+  if (found === null) return [];
+  const cg = Q.loadCallgraph(reportPrefix);
+  return found.map(({ entry, line }) => {
+    let blast = "";
+    try {
+      const c = Q.callers(cg, entry.fn);
+      const n = (c && c.transitive && c.transitive.length) || 0;
+      blast = ` · blast radius ${n}`;
+    } catch { /* no callgraph — effects-only lens */ }
+    const eff = (entry.inferred || []).join(", ") || "pure";
+    return {
+      range: { start: { line, character: 0 }, end: { line, character: 0 } },
+      command: { title: `⚡ ${eff}${blast}`, command: "" },   // informational lens (no action) — P1
+    };
+  });
+}
+
+// ---- Hover: effect provenance at the cursor ----------------------------------------------------------
+// The entry ENCLOSING the hovered line: the report pins each fn at its declaration line, so the match is
+// the greatest entry line ≤ the cursor (functions are sequential in a file — a sound approximation that
+// needs no parser). For each inferred effect: direct → "performed here"; inherited → the §3.1 `path`
+// chain to the direct source. unknownWhy rides along when the fn introduces opacity.
+function hoverAt(docPath, line) {
+  const found = entriesInDoc(docPath);
+  if (!found || !found.length) return null;
+  const at = found.filter((x) => x.line <= line).sort((a, b) => b.line - a.line)[0];
+  if (!at) return null;
+  const { entry } = at;
+  const fns = Q.loadReport(reportPrefix);
+  const cg = Q.loadCallgraph(reportPrefix);
+  const lines = [`**${entry.fn}** — ⚡ { ${(entry.inferred || []).join(", ") || "pure"} }`];
+  for (const eff of entry.inferred || []) {
+    if (eff === "Unknown") continue;                          // covered by unknownWhy below
+    if ((entry.direct || []).includes(eff)) {
+      lines.push(`- **${eff}** — performed directly here`);
+      continue;
+    }
+    try {
+      const hops = (Q.path(fns, cg, entry.fn, eff)?.path || []).map((h) => h.fn.split(/[.:]+/).pop() + (h.source ? " (source)" : ""));
+      lines.push(hops.length > 1 ? `- **${eff}** — via ${hops.slice(1).join(" → ")}` : `- **${eff}** — inherited (source is cross-boundary or framework-synthesised)`);
+    } catch { lines.push(`- **${eff}** — inherited`); }
+  }
+  if (entry.unknownWhy?.length) lines.push(`- **Unknown** — ${entry.unknownWhy.join(", ")}`);
+  if (entry.invisible?.length) lines.push(`- _invisible_: ${entry.invisible.join(", ")} (unmodeled — the effect set is a lower bound)`);
+  try {
+    const c = Q.callers(cg, entry.fn);
+    lines.push(`\nBlast radius: **${(c?.transitive || []).length}** transitive caller(s)`);
+  } catch { /* no callgraph */ }
+  return {
+    contents: { kind: "markdown", value: lines.join("\n") },
+    range: { start: { line: at.line, character: 0 }, end: { line: at.line, character: 200 } },
+  };
+}
+
+// ---- Diagnostics (the live gate) ---------------------------------------------------------------------
+function activePolicy() {
+  const env = process.env.CANDOR_POLICY;
+  if (env && fs.existsSync(env)) return fs.readFileSync(env, "utf8");
+  const from = reportPrefix ? nodePath.dirname(nodePath.resolve(reportPrefix)) : rootPath;
+  const cfg = from ? discoverConfigPolicy(from) : null;
+  if (cfg && fs.existsSync(cfg.policyPath)) return fs.readFileSync(cfg.policyPath, "utf8");
+  return null;
+}
+function diagnosticsFor(docPath) {
+  const text = activePolicy();
+  if (text === null || !hasReport(reportPrefix)) return [];
+  const fns = Q.loadReport(reportPrefix);
+  const violations = evaluatePolicy(parsePolicy(text), fns, Q.loadCallgraph(reportPrefix));
+  const locByFn = new Map(fns.filter((e) => e.loc).map((e) => [e.fn, locParts(e.loc)]));
+  const out = [];
+  for (const v of violations) {
+    const lp = locByFn.get(v.fn);
+    if (!lp || !docMatches(docPath, v.fn, lp.file)) continue;
+    out.push({
+      range: { start: { line: lp.line, character: 0 }, end: { line: lp.line, character: 200 } },
+      severity: v.rule === "AS-EFF-007" ? 2 : 1,   // the advisory code is a warning, the rest errors
+      source: "candor",
+      code: v.rule,
+      message: v.detail || `${v.fn} violates ${v.rule}`,
+    });
+  }
+  return out;
+}
+function publishDiagnostics(uri) {
+  let docPath;
+  try { docPath = fileURLToPath(uri); } catch { return; }
+  try {
+    send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri, diagnostics: diagnosticsFor(docPath) } });
+  } catch (e) {
+    logMessage(`candor-lsp: diagnostics failed for ${uri}: ${e.message}`);
+  }
+}
+function logMessage(message) { send({ jsonrpc: "2.0", method: "window/logMessage", params: { type: 2, message } }); }
+
+// ---- the LSP method surface ---------------------------------------------------------------------------
+function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    if (params?.rootUri) { try { rootPath = fileURLToPath(params.rootUri); } catch { /* keep null */ } }
+    else if (params?.rootPath) rootPath = params.rootPath;
+    if (params?.initializationOptions?.report) reportPrefix = params.initializationOptions.report;
+    if (!reportPrefix && rootPath) {
+      const cand = nodePath.join(rootPath, ".candor", "report");
+      if (hasReport(cand)) reportPrefix = cand;
+    }
+    return result(id, {
+      capabilities: {
+        textDocumentSync: { openClose: true, save: true, change: 0 },  // report-backed: buffer edits don't move the map
+        codeLensProvider: { resolveProvider: false },
+        hoverProvider: true,
+      },
+      serverInfo: { name: "candor-lsp", version: VERSION },
+    });
+  }
+  if (method === "initialized" || method === "$/cancelRequest" || method === "$/setTrace") return;
+  if (method === "textDocument/didOpen") return publishDiagnostics(params.textDocument.uri);
+  if (method === "textDocument/didSave") return publishDiagnostics(params.textDocument.uri);
+  if (method === "textDocument/didChange") return;                    // see textDocumentSync: report-backed
+  if (method === "textDocument/didClose")
+    return send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri: params.textDocument.uri, diagnostics: [] } });
+  if (method === "textDocument/hover") {
+    try { return result(id, hoverAt(fileURLToPath(params.textDocument.uri), params.position?.line ?? 0)); }
+    catch { return result(id, null); }   // hover is best-effort — null, never a crash
+  }
+  if (method === "textDocument/codeLens") {
+    try { return result(id, codeLenses(fileURLToPath(params.textDocument.uri))); }
+    catch { return result(id, []); }   // a non-file URI / unreadable report → no lenses, never a crash
+  }
+  if (method === "shutdown") return result(id, null);
+  if (method === "exit") process.exit(0);
+  if (id !== undefined) error(id, -32601, `method not found: ${method}`);
+}
+
+// ---- LSP stdio transport (Content-Length framed JSON-RPC) ---------------------------------------------
+function send(msg) {
+  const body = Buffer.from(JSON.stringify(msg), "utf8");
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  process.stdout.write(body);
+}
+function result(id, r) { send({ jsonrpc: "2.0", id, result: r }); }
+function error(id, code, message) { send({ jsonrpc: "2.0", id, error: { code, message } }); }
+
+let buf = Buffer.alloc(0);
+process.stdin.on("data", (chunk) => {
+  buf = Buffer.concat([buf, chunk]);
+  for (;;) {
+    const headerEnd = buf.indexOf("\r\n\r\n");
+    if (headerEnd < 0) return;
+    const header = buf.slice(0, headerEnd).toString("utf8");
+    const m = header.match(/Content-Length:\s*(\d+)/i);
+    if (!m) { buf = buf.slice(headerEnd + 4); continue; }            // skip an unframed preamble
+    const len = parseInt(m[1], 10);
+    if (buf.length < headerEnd + 4 + len) return;                     // body not fully arrived
+    const body = buf.slice(headerEnd + 4, headerEnd + 4 + len).toString("utf8");
+    buf = buf.slice(headerEnd + 4 + len);
+    let msg;
+    try { msg = JSON.parse(body); } catch { continue; }
+    if (!msg || typeof msg !== "object" || Array.isArray(msg)) continue;
+    try { handle(msg); } catch (e) { if (msg.id !== undefined) error(msg.id, -32603, e.message); }
+  }
+});
+process.stdin.on("end", () => process.exit(0));

package/mcp.mjs

@@ -19,11 +19,12 @@ import fs from "node:fs";
 import { createRequire } from "node:module";
 import nodePath from "node:path";
 import * as Q from "./query-core.mjs";
-import { parsePolicy, scopeMatches } from "./policy.mjs";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches } from "./policy.mjs";
 
 const VERSION = createRequire(import.meta.url)("./package.json").version; // single-sourced, like scan.mjs
 
-const DEFAULT_PREFIX = process.env.CANDOR_REPORT || process.argv[2] || null;
+const DEFAULT_PREFIX = process.env.CANDOR_REPORT || process.argv[2]
+  || (fs.existsSync(".candor") ? ".candor/report" : null);   // the engines' default --out convention
 
 // A report exists at the prefix if there's an exact `<prefix>.json` (candor-ts) OR a sibling
 // `<prefix>.<crate>.scan.json` (the candor-scan/Rust multi-report form) — the loaders read both, so
@@ -52,13 +53,16 @@ const clip = (s, n = 120) => { s = String(s); return s.length > n ? s.slice(0, n
 // report-query-only (spec §7.12); an arbitrary `policy` path (/etc/passwd, ~/.aws/credentials) whose
 // parsed deny-rule scopes are reflected back in violations[].rule is an arbitrary-file-read exfiltration
 // channel — tie the policy to the project it gates.
-function confinedPolicyRead(policyPath, prefix) {
-  const root = nodePath.resolve(nodePath.dirname(prefix));
+function confinedPolicyRead(policyPath, prefix, root = nodePath.resolve(nodePath.dirname(prefix))) {
   const abs = nodePath.resolve(policyPath);
   if (abs !== root && !abs.startsWith(root + nodePath.sep))
     throw new Error(`policy must be within the report's directory (${root}) — refusing to read \`${clip(policyPath)}\``);
   return fs.readFileSync(abs, "utf8");
 }
+// The repo's .candor/config (spec §3.4), from the report's directory upward — shared impl in policy.mjs.
+function configPolicy(prefix) {
+  return discoverConfigPolicy(nodePath.dirname(nodePath.resolve(prefix)) || ".");
+}
 
 // ---- the tools: name -> {description, schema, run} ------------------------------------------------
 const reportArg = { report: { type: "string", description: "report prefix (optional; defaults to $CANDOR_REPORT)" } };
@@ -130,8 +134,63 @@ const TOOLS = {
       return r;
     },
   },
+  candor_gate: {
+    description: "The policy verdict over this report: { ok, violations:[{rule, fn, effects, detail}] } — 'would this repo pass its architecture gate?'. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4). Computed from the report (an engine's own --gate-json run is the authoritative CI form).",
+    schema: { type: "object", properties: { policy: { type: "string", description: "path to a §6.2 policy file (optional; defaults to the repo's .candor/config `policy`)" }, ...reportArg }, required: [] },
+    run: (a, p) => {
+      let text;
+      if (a.policy) text = confinedPolicyRead(a.policy, p);
+      else {
+        const cfg = configPolicy(p);
+        if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4)");
+        text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
+      }
+      const v = evaluatePolicy(parsePolicy(text), Q.loadReport(p), Q.loadCallgraph(p));
+      return { ok: v.length === 0, violations: v };
+    },
+  },
+  candor_containment: {
+    description: "Per boundary effect (Db/Net/Exec/Fs/Ipc/Clipboard): how contained it is in one architectural layer — the dispersion diagnostic (spec §6.1). Not a score; per-effect facts.",
+    schema: { type: "object", properties: { ...reportArg } },
+    run: (_a, p) => Q.containment(Q.loadReport(p)),
+  },
+  candor_blindspots: {
+    description: "The Unknown SOURCES — calls the engine genuinely could not resolve (reflection, wide dispatch, fn-pointers) — ranked by how many functions inherit Unknown through each. Turns a high-Unknown report into a short worklist.",
+    schema: { type: "object", properties: { ...reportArg } },
+    run: (_a, p) => Q.blindspots(Q.loadReport(p), Q.loadCallgraph(p)),
+  },
+  candor_diff: {
+    description: "The per-function effect delta versus a baseline report: gained (introduced vs inherited) and lost effects. 'What did this change do to the effect surface?'.",
+    schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
+    run: (a, p) => Q.diff(Q.loadReport(p), Q.loadReport(a.baseline)),
+  },
+  candor_gains: {
+    description: "The supply-chain alarm: effects the surface GAINED versus a baseline (package-level + per-function) — 'did this dependency bump add Net/Exec somewhere?'.",
+    schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
+    run: (a, p) => Q.gains(Q.loadReport(p), Q.loadReport(a.baseline)),
+  },
 };
 
+// ---- MCP resources: the report + the checked-in policy, readable directly --------------------------
+function listResources(prefix) {
+  const res = [{ uri: `candor://report?prefix=${encodeURIComponent(prefix)}`, name: "candor report",
+                 description: "the spec §2 report envelope (all packages under the prefix)", mimeType: "application/json" }];
+  const cfg = prefix ? configPolicy(prefix) : null;
+  if (cfg && fs.existsSync(cfg.policyPath))
+    res.push({ uri: `candor://policy?prefix=${encodeURIComponent(prefix)}`, name: "candor policy",
+               description: "the repo's checked-in §6.2 architecture policy (via .candor/config)", mimeType: "text/plain" });
+  return res;
+}
+function readResource(uri, prefix) {
+  if (uri.startsWith("candor://report")) return { mimeType: "application/json", text: JSON.stringify(Q.loadReport(prefix)) };
+  if (uri.startsWith("candor://policy")) {
+    const cfg = configPolicy(prefix);
+    if (!cfg) throw new Error("no checked-in policy (no .candor/config with a `policy` key)");
+    return { mimeType: "text/plain", text: confinedPolicyRead(cfg.policyPath, prefix, cfg.repoRoot) };
+  }
+  throw new Error(`unknown resource: ${uri}`);
+}
+
 // ---- JSON-RPC 2.0 over stdio (newline-delimited; the MCP stdio framing) ---------------------------
 function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n"); }
 function result(id, r) { send({ jsonrpc: "2.0", id, result: r }); }
@@ -142,13 +201,24 @@ function handle(msg) {
   if (method === "initialize") {
     return result(id, {
       protocolVersion: params?.protocolVersion || "2025-06-18",
-      capabilities: { tools: {} },
+      capabilities: { tools: {}, resources: {} },
       serverInfo: { name: "candor-mcp", version: VERSION },
       instructions: "candor's read-only effect queries. Prefer candor_impact/candor_reachable/candor_where over manually tracing the call graph — they return deterministic ground truth from a precomputed report. Run a candor scan first to produce the report.",
     });
   }
   if (method === "notifications/initialized" || method === "notifications/cancelled") return; // notifications: no reply
   if (method === "ping") return result(id, {});
+  if (method === "resources/list") {
+    try { return result(id, { resources: DEFAULT_PREFIX && hasReport(DEFAULT_PREFIX) ? listResources(DEFAULT_PREFIX) : [] }); }
+    catch { return result(id, { resources: [] }); }
+  }
+  if (method === "resources/read") {
+    try {
+      const prefix = resolvePrefix({});
+      const r = readResource(params?.uri || "", prefix);
+      return result(id, { contents: [{ uri: params?.uri, ...r }] });
+    } catch (e) { return error(id, -32602, `candor: ${e.message}`); }
+  }
   if (method === "tools/list") {
     return result(id, {
       tools: Object.entries(TOOLS).map(([name, t]) => ({ name, description: t.description, inputSchema: t.schema })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
   "type": "module",
   "dependencies": {
@@ -11,11 +11,13 @@
     "candor-ts": "./scan.mjs",
     "candor-ts-query": "./query.mjs",
     "candor-ts-mcp": "./mcp.mjs",
-    "candor-ts-watch": "./watch.mjs"
+    "candor-ts-watch": "./watch.mjs",
+    "candor-mcp": "./mcp.mjs",
+    "candor-lsp": "./lsp.mjs"
   },
   "scripts": {
     "lint": "eslint *.mjs",
-    "test": "npm run lint && node --test test-unit.mjs && node test.mjs && node test-mcp.mjs && node test-watch.mjs && npm run test:probe && npm run test:fuzz",
+    "test": "npm run lint && node --test test-unit.mjs && node test.mjs && node test-mcp.mjs && node test-lsp.mjs && node test-watch.mjs && npm run test:probe && npm run test:fuzz",
     "test:unit": "node --test test-unit.mjs",
     "test:probe": "node fabrication_probe.mjs",
     "test:fuzz": "node fuzz.mjs"
@@ -50,7 +52,8 @@
     "query-core.mjs",
     "scan-core.mjs",
     "mcp.mjs",
-    "watch.mjs"
+    "watch.mjs",
+    "lsp.mjs"
   ],
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/policy.mjs

@@ -158,3 +158,26 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
   }
   return out;
 }
+
+// ---- .candor/config discovery (spec §3.4) — shared by the MCP + LSP surfaces -----------------------
+// Walk UP from `fromDir` to the nearest .candor/config and return its `policy` entry resolved against
+// that config's repo root: { policyPath, repoRoot } — or null. Read-only + best-effort (a consumer
+// surface never gates a build; a broken config surfaces as the caller's error).
+import fs from "node:fs";
+import nodePath from "node:path";
+export function discoverConfigPolicy(fromDir) {
+  let dir = nodePath.resolve(fromDir);
+  for (;;) {
+    const cand = nodePath.join(dir, ".candor", "config");
+    if (fs.existsSync(cand)) {
+      const m = fs.readFileSync(cand, "utf8").split(/\r?\n/)
+        .map((l) => l.split("#", 1)[0].trim()).filter(Boolean)
+        .map((l) => l.match(/^(\S+)\s*(.*)$/)).find((mm) => mm && mm[1].toLowerCase() === "policy");
+      if (!m) return null;
+      return { policyPath: nodePath.resolve(dir, m[2].trim()), repoRoot: dir };
+    }
+    const parent = nodePath.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}

package/scan.mjs

@@ -100,6 +100,59 @@ for (let i = 0; i < argv.length; i++) {
 if (wantAgents) { printAgents(); process.exit(0); }
 if (target === null) { console.error(usage); process.exit(2); }
 
+// ---- .candor/config (candor-spec §config; the checked-in alternative to the CANDOR_* env vars) -----
+// Discovery is anchored to the SCAN TARGET (walk up from the target dir to the repo root's
+// .candor/config), never the CWD; $CANDOR_CONFIG overrides discovery entirely. Precedence: CLI flag →
+// CANDOR_* env → this file → default. FAIL-CLOSED: a configured-but-unusable file (a set CANDOR_CONFIG
+// naming a missing path; a discovered file that exists but can't be read) exits 2 — a gate source must
+// never vanish silently (the §6.2 unreadable-policy posture). Only genuine absence is an empty config.
+// Keys are the shared vocabulary (policy/baseline/strict/no-ambient/closed-world/taint/deps); candor-ts
+// implements `policy` + `deps` — the others are inert here (they drive other engines' gates), and a key
+// OUTSIDE the vocabulary warns (typo protection: a misspelt `policy` must not silently drop the gate).
+const CONFIG_KEYS = new Set(["policy", "baseline", "strict", "no-ambient", "closed-world", "taint", "deps"]);
+function loadCandorConfig(targetPath) {
+  let file = process.env.CANDOR_CONFIG ?? null;
+  if (file !== null) {
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+      console.error(`candor-ts: CANDOR_CONFIG set but ${file} is not a readable file — failing (exit 2)`);
+      process.exit(2);
+    }
+  } else {
+    let dir = path.resolve(targetPath);
+    try { if (!fs.statSync(dir).isDirectory()) dir = path.dirname(dir); } catch { dir = path.dirname(dir); }
+    for (let d = dir; ; d = path.dirname(d)) {
+      const cand = path.join(d, ".candor", "config");
+      if (fs.existsSync(cand)) { file = cand; break; }
+      if (path.dirname(d) === d) break;                       // filesystem root
+    }
+    if (file === null && fs.existsSync(".candor/config")) file = ".candor/config";
+    if (file === null) return {};
+  }
+  let text;
+  try { text = fs.readFileSync(file, "utf8"); }
+  catch (e) {
+    console.error(`candor-ts: config ${file} exists but could not be read (${e.message}) — failing (exit 2)`);
+    process.exit(2);
+  }
+  const cfg = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.split("#", 1)[0].trim();                 // strip inline comments (§6.2 lexical)
+    if (!line) continue;
+    const m = line.match(/^(\S+)\s*(.*)$/);
+    const key = m[1].toLowerCase(), val = (m[2] ?? "").trim();
+    if (!CONFIG_KEYS.has(key)) {
+      console.error(`candor-ts: ignoring unknown config key '${key}' in ${file}`);
+      continue;
+    }
+    cfg[key] = val;
+  }
+  return cfg;
+}
+const candorConfig = loadCandorConfig(target);
+// precedence: the --policy flag / CANDOR_POLICY env already populated policyPath; the config is the floor.
+// A BARE `policy` line ("" value) means configured-with-empty → the unreadable-policy path fails loud.
+if (policyPath === null && candorConfig.policy !== undefined) policyPath = candorConfig.policy;
+
 // ---- project discovery (a dir, a single file, or a tsconfig) --------------------------------------
 let rootDir, fileNames, compilerOptions = {
   target: ts.ScriptTarget.ES2022,
@@ -228,7 +281,7 @@ const crossDeps = new Map(); // hash -> {inferred:Set, hosts:[], cmds:[], paths:
 // the envelope's `package` field (works for an all-pure EMPTY report) and from entry hash prefixes.
 const depCoveredPkgs = new Set();
 {
-  const spec = process.env.CANDOR_DEPS ?? "";
+  const spec = process.env.CANDOR_DEPS ?? candorConfig.deps ?? "";   // env overrides the config `deps` key
   const files = [];
   for (const tok of spec.split(/[\s:,]+/).filter(Boolean)) {
     try {