candor-ts 0.8.8 → 0.8.10

package/AGENTS.md

@@ -97,6 +97,8 @@ Q map      $P 1                     # {module: {effects, functions}}
 Q containment $P [baseline-prefix]  # §6.1 boundary-effect dispersion; with a baseline = AS-EFF-010 ratchet (exit 1 on a leak)
 Q blindspots $P                     # the Unknown SOURCES (fns with unknownWhy), ranked by Unknown blast radius
 Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it would violate)
+Q fix      $P <fn> <Effect> <policy>  # the boundary FIX: where the effect belongs + the hoist refactor
+Q fix-gate $P <policy>              # a fix for EVERY crossing — the loop's block-message remedy
 Q diff     $P <baseline-prefix> 1   # per-function effect delta (exit 1 on a gained effect)
 Q gains    $P <baseline-prefix>     # supply-chain alarm: {gained, byFunction} — effects a surface grew
 Q reachable $P 1                    # what the app DOES at runtime: effects over the entry points
@@ -105,9 +107,14 @@ Q parsepolicy <policy-file>         # the canonical §6.2 parse (what the gate w
 
 And as an MCP server, so an agent pulls these as tools instead of shelling out:
 `CANDOR_REPORT=$P npx -y candor-ts-mcp` (tools `candor_impact`/`candor_reachable`/`candor_where`/…,
-plus `candor_gate`/`candor_whatif` — a given-but-unreadable `policy` is a loud tool error, never a
-clean verdict). `npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and reports the
-edit-delta); `candor-lsp` serves the same report as CodeLens/hover/diagnostics in any LSP editor.
+plus `candor_gate`/`candor_whatif`/`candor_fix` — a given-but-unreadable `policy` is a loud tool
+error, never a clean verdict). `npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and
+reports the edit-delta); `candor-lsp` serves the same report as CodeLens/hover/diagnostics in any LSP
+editor, plus two code actions (plain LSP — helix/neovim/VS Code/JetBrains-via-LSP4IJ all get them
+without client code): the pre-edit whatif (`candor: what if <fn> performed <E>?` → the `candor.whatif`
+command) and, when the cursor sits in a function that actually violates the policy, the boundary FIX
+(`candor fix: hoist <E> out of <fn>` → the `candor.fix` command: where the effect belongs + the hoist
+refactor, as a showMessage and a transient diagnostic, cleared on the file's next open/save).
 CAVEAT — the MCP/LSP gate verdicts are computed FROM THE REPORT: the engine's own `--policy` /
 `--gate-json` run additionally fails an allow rule whose literal surface is incomplete (a masked
 endpoint — internal state, not a report field), so treat a report-side green as advisory and the

package/README.md

@@ -123,6 +123,14 @@ engine's report — and never scans. (Both report-computed gates are advisory: t
 `--gate-json` run additionally fails masked/incomplete literal surfaces and is the authoritative
 CI form.)
 
+It also answers the pre-edit question in place: inside a function, a code action per boundary
+effect the fn doesn't yet perform — `candor: what if handler performed Net?` — runs the same
+whatif as `candor-ts-query whatif`/`candor_whatif` (blast radius + the policy rule that WOULD
+fire) and shows the verdict as a message plus a transient diagnostic at the function (cleared on
+the file's next open/save; with no policy discovered it says so and reports the radius alone).
+Plain `textDocument/codeAction` + `workspace/executeCommand` (`candor.whatif`) — it works
+unmodified in helix, neovim, VS Code, and JetBrains via LSP4IJ.
+
 **The live loop** — `candor-ts-watch` keeps the report fresh as the agent edits, so the answers are
 about the *current* code, not a stale snapshot:
 

package/lsp.mjs

@@ -13,6 +13,18 @@
  *     red in CI. The engine's --gate-json is the authoritative form (same caveat as MCP candor_gate).
  *   • 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.
+ *   • CodeAction (pre-edit whatif): inside a function the report knows, one action per BOUNDARY effect
+ *     the fn does NOT already perform — `candor: what if <fn> performed Net?`. Each resolves to the
+ *     `candor.whatif` workspace/executeCommand, answered server-side with the SAME query-core whatif the
+ *     CLI and MCP use (single-source): a window/showMessage one-liner (the policy rule that WOULD fire +
+ *     the blast radius; no policy discovered → radius only, said so) and a transient Information
+ *     diagnostic at the fn's line carrying the detail (rule + first callers), cleared on the next
+ *     didOpen/didSave/didChange of that file or replaced by re-running the action. Plain LSP — works in
+ *     helix/neovim/VS Code/JetBrains-via-LSP4IJ without client-side code.
+ *
+ *   Perf (measured on the 5k-fn synthetic fixture in test-lsp.mjs — 50 files × 100 fns, one 5k-deep
+ *   call chain, worst-case doc): codeLens ≈ 63ms, codeAction ≈ 5ms per request, INCLUDING the
+ *   per-request report re-read. No caching layer — the freshness contract stays "re-read per request".
  *
  * 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
@@ -33,7 +45,7 @@ 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";
+import { discoverConfigPolicy, evaluatePolicy, parsePolicy, scopeMatches } 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.
@@ -110,17 +122,22 @@ function codeLenses(docPath) {
   });
 }
 
+// The entry ENCLOSING a 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). Shared by hover and codeAction — one rule for "which function is the cursor in".
+function enclosingEntry(docPath, line, fns = null) {
+  const found = entriesInDoc(docPath, fns);
+  if (!found || !found.length) return null;
+  return found.filter((x) => x.line <= line).sort((a, b) => b.line - a.line)[0] ?? null;
+}
+
 // ---- 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.
+// 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) {
   if (!hasReport(reportPrefix)) return null;
-  const fns = Q.loadReport(reportPrefix);          // ONE load per request (entriesInDoc reuses it)
-  const found = entriesInDoc(docPath, fns);
-  if (!found || !found.length) return null;
-  const at = found.filter((x) => x.line <= line).sort((a, b) => b.line - a.line)[0];
+  const fns = Q.loadReport(reportPrefix);          // ONE load per request (enclosingEntry reuses it)
+  const at = enclosingEntry(docPath, line, fns);
   if (!at) return null;
   const { entry } = at;
   const cg = Q.loadCallgraph(reportPrefix);
@@ -188,12 +205,165 @@ function publishDiagnostics(uri) {
   let docPath;
   try { docPath = fileURLToPath(uri); } catch { return; }
   try {
-    send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri, diagnostics: diagnosticsFor(docPath) } });
+    const diags = diagnosticsFor(docPath).concat(transient.get(uri) ?? []);
+    send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri, diagnostics: diags } });
   } 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 } }); }
+function showMessage(type, message) { send({ jsonrpc: "2.0", method: "window/showMessage", params: { type, message } }); }
+
+// ---- CodeAction: the pre-edit whatif (spec §3.1 whatif, rendered as an editor action) -----------------
+// From a position inside a function the report knows, offer "what if <fn> performed <E>?" for each
+// BOUNDARY effect (Q.CONTAINED — ambient effects gate nothing) the fn does not already carry. The action
+// carries a plain `command` (no client-side resolve, no edit) so it works in any LSP client verbatim.
+const WHATIF_COMMAND = "candor.whatif";
+const FIX_COMMAND = "candor.fix";
+function codeActions(docPath, uri, range) {
+  const at = enclosingEntry(docPath, range?.start?.line ?? 0);
+  if (!at) return [];                                  // a fn the report doesn't know → no actions, never an error
+  const have = new Set(at.entry.inferred || []);
+  const out = [];
+  for (const eff of Q.CONTAINED) {                     // ≤6 boundary effects — the natural cap
+    if (have.has(eff)) continue;
+    out.push({
+      title: `candor: what if ${at.entry.fn} performed ${eff}?`,
+      command: {
+        title: `candor: what if ${at.entry.fn} performed ${eff}?`,
+        command: WHATIF_COMMAND,
+        arguments: [{ fn: at.entry.fn, effect: eff, uri, line: at.line }],
+      },
+    });
+  }
+  // The REMEDIAL companion (integrations/FIX-SPEC.md): for each BOUNDARY effect the fn ALREADY performs that
+  // the active policy FORBIDS here, offer the FIX — where the effect belongs + the hoist. Only real crossings
+  // are offered (Q.fix returns `crossing:false` otherwise), so this is empty unless the cursor sits in a
+  // function that actually violates the boundary. Same policy source as the diagnostics + the whatif action.
+  const policyText = activePolicy();
+  if (policyText !== null && hasReport(reportPrefix)) {
+    const pol = parsePolicy(policyText);
+    const cg = Q.loadCallgraph(reportPrefix);
+    const fns = Q.loadReport(reportPrefix);
+    for (const eff of Q.CONTAINED) {
+      if (!have.has(eff)) continue;
+      const r = Q.fix(cg, fns, at.entry.fn, eff, pol, scopeMatches);
+      if (r && r.crossing) {
+        out.push({
+          title: `candor fix: hoist ${eff} out of ${at.entry.fn}`,
+          command: {
+            title: `candor fix: hoist ${eff} out of ${at.entry.fn}`,
+            command: FIX_COMMAND,
+            arguments: [{ fn: at.entry.fn, effect: eff, uri, line: at.line }],
+          },
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// Transient whatif diagnostics (Information severity, appended to the gate diagnostics on publish):
+// uri -> Diagnostic[]. Cleared on the next didOpen/didSave/didChange of that file; re-running the
+// action replaces the previous answer (one live whatif overlay per file, not an accumulating pile).
+const transient = new Map();
+function clearTransient(uri) {
+  if (transient.delete(uri)) publishDiagnostics(uri);   // republish without the overlay
+}
+
+// The candor.whatif command: the SAME query-core whatif the CLI (`query.mjs whatif`) and MCP
+// (`candor_whatif`) run — blast radius over the callgraph + the deny rules that WOULD fire, against the
+// live policy (CANDOR_POLICY / .candor/config discovery, same source as the diagnostics). Everything is
+// re-read per call (the freshness contract). Malformed args → logMessage + null, never a throw.
+function runWhatif(a) {
+  if (!a || typeof a !== "object" || typeof a.fn !== "string" || typeof a.effect !== "string") {
+    logMessage(`candor-lsp: ${WHATIF_COMMAND} called with malformed arguments (expected [{ fn, effect, uri?, line? }]) — ignored`);
+    return null;
+  }
+  if (!hasReport(reportPrefix)) {
+    showMessage(2, "candor: no report found — scan first (candor-ts <dir> --out .candor/report)");
+    return null;
+  }
+  const policyText = activePolicy();
+  const r = Q.whatif(Q.loadCallgraph(reportPrefix), a.fn, a.effect,
+                     policyText === null ? null : parsePolicy(policyText), scopeMatches);
+  if (r === null) {
+    showMessage(2, `candor: no function matching \`${a.fn}\` in the call graph — the report may be stale`);
+    return null;
+  }
+  const callers = r.affected.filter((f) => !r.of.includes(f));   // affected minus the target(s) themselves
+  const rules = [...new Set(r.violations.map((v) => v.rule))];
+  const verdict = policyText === null
+    ? `candor: no policy discovered — blast radius only: ${callers.length} caller(s) would inherit ${a.effect}`
+    : rules.length
+      ? `✗ ${rules[0]} would fire — ${callers.length} caller(s) inherit ${a.effect}`
+      : `✓ no policy rule fires — ${callers.length} caller(s) would inherit ${a.effect}`;
+  showMessage(rules.length ? 2 : 3, verdict);                    // warning when a rule fires, info otherwise
+  if (typeof a.uri === "string" && Number.isInteger(a.line)) {   // the detail, pinned at the fn's line
+    const head = callers.slice(0, 10);
+    const lines = [`what if ${r.of.join(", ")} performed ${a.effect}? ${verdict}`];
+    if (rules.length > 1) lines.push(`rules: ${rules.join("; ")}`);
+    lines.push(head.length
+      ? `callers: ${head.join(", ")}${callers.length > head.length ? ` +${callers.length - head.length} more` : ""}`
+      : "no callers — the blast radius is the function itself");
+    transient.set(a.uri, [{
+      range: { start: { line: a.line, character: 0 }, end: { line: a.line, character: 200 } },
+      severity: 3, source: "candor", code: "whatif", message: lines.join("\n"),
+    }]);
+    publishDiagnostics(a.uri);
+  }
+  return r;   // the raw whatif result rides back as the executeCommand result (a thick client can render it)
+}
+
+// The candor.fix command: the SAME query-core `fix` the CLI (`query.mjs fix`) and MCP (`candor_fix`) run —
+// the boundary remedy (where the effect belongs + the hoist refactor), against the live policy (same source
+// as the diagnostics). Re-read per call (the freshness contract). Malformed args → logMessage + null.
+function runFix(a) {
+  if (!a || typeof a !== "object" || typeof a.fn !== "string" || typeof a.effect !== "string") {
+    logMessage(`candor-lsp: ${FIX_COMMAND} called with malformed arguments (expected [{ fn, effect, uri?, line? }]) — ignored`);
+    return null;
+  }
+  if (!hasReport(reportPrefix)) {
+    showMessage(2, "candor: no report found — scan first (candor-ts <dir> --out .candor/report)");
+    return null;
+  }
+  const policyText = activePolicy();
+  if (policyText === null) {
+    showMessage(2, "candor: no policy discovered — a fix is defined relative to a boundary; set CANDOR_POLICY or check one into .candor/config");
+    return null;
+  }
+  const r = Q.fix(Q.loadCallgraph(reportPrefix), Q.loadReport(reportPrefix), a.fn, a.effect,
+                  parsePolicy(policyText), scopeMatches);
+  if (r === null) {
+    showMessage(2, `candor: no function matching \`${a.fn}\` in the call graph — the report may be stale`);
+    return null;
+  }
+  if (!r.crossing) {
+    showMessage(3, `candor: \`${a.fn}\` — ${a.effect} isn't forbidden here; no boundary fix needed`);
+    return r;
+  }
+  const verdict = r.cleanHoist
+    ? `candor fix: hoist ${a.effect} to ${r.hoistTo.join(", ")} — the ${r.deniedSpan.length} ${r.layer || "(root)"} function(s) then stay pure (or relax the boundary: ${r.policyAlternative})`
+    : `candor fix: no clean hoist for ${a.effect} — introduce a port, or relax the boundary: ${r.policyAlternative}`;
+  showMessage(2, verdict);
+  if (typeof a.uri === "string" && Number.isInteger(a.line)) {   // the plan, pinned at the fn's line
+    const lines = [`candor fix — hoist ${a.effect} out of the ${r.layer || "(root)"} boundary`];
+    lines.push(`site: ${r.site.join(", ") || "(cross-module or Unknown source)"}`);
+    if (r.cleanHoist) {
+      lines.push(`hoist ${a.effect} to: ${r.hoistTo.join(", ")}`);
+      lines.push(`then pure (thread the value): ${r.deniedSpan.join(", ")}`);
+    } else {
+      lines.push("no clean hoist — introduce a port (inject the effect from an allowed layer), or relax the boundary");
+    }
+    lines.push(`policy alternative: ${r.policyAlternative}`);
+    transient.set(a.uri, [{
+      range: { start: { line: a.line, character: 0 }, end: { line: a.line, character: 200 } },
+      severity: 3, source: "candor", code: "fix", message: lines.join("\n"),
+    }]);
+    publishDiagnostics(a.uri);
+  }
+  return r;   // the raw remedy rides back as the executeCommand result (a thick client can render it)
+}
 
 // ---- the LSP method surface ---------------------------------------------------------------------------
 function handle(msg) {
@@ -211,14 +381,19 @@ function handle(msg) {
         textDocumentSync: { openClose: true, save: true, change: 0 },  // report-backed: buffer edits don't move the map
         codeLensProvider: { resolveProvider: false },
         hoverProvider: true,
+        codeActionProvider: { resolveProvider: false },                // actions carry their command inline
+        executeCommandProvider: { commands: [WHATIF_COMMAND, FIX_COMMAND] },
       },
       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
+  // didOpen/didSave/didChange drop the file's transient whatif overlay — a fresh look at the file (or an
+  // edit) invalidates a hypothetical answered against the previous state. didChange is not negotiated
+  // (change: 0) but is handled defensively for clients that send it anyway.
+  if (method === "textDocument/didOpen") { transient.delete(params.textDocument.uri); return publishDiagnostics(params.textDocument.uri); }
+  if (method === "textDocument/didSave") { transient.delete(params.textDocument.uri); return publishDiagnostics(params.textDocument.uri); }
+  if (method === "textDocument/didChange") return clearTransient(params.textDocument.uri);
   if (method === "textDocument/didClose")
     return send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params: { uri: params.textDocument.uri, diagnostics: [] } });
   if (method === "textDocument/hover") {
@@ -229,6 +404,20 @@ function handle(msg) {
     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 === "textDocument/codeAction") {
+    try { return result(id, codeActions(fileURLToPath(params.textDocument.uri), params.textDocument.uri, params.range)); }
+    catch { return result(id, []); }   // unknown fn / non-file URI / unreadable report → no actions, never an error
+  }
+  if (method === "workspace/executeCommand") {
+    const handlers = { [WHATIF_COMMAND]: runWhatif, [FIX_COMMAND]: runFix };
+    const run = handlers[params?.command];
+    if (!run) {
+      logMessage(`candor-lsp: unknown command \`${params?.command}\` — this server provides ${WHATIF_COMMAND} and ${FIX_COMMAND}`);
+      return result(id, null);
+    }
+    try { return result(id, run(params?.arguments?.[0])); }
+    catch (e) { logMessage(`candor-lsp: ${params?.command} failed: ${e.message}`); return result(id, null); }
+  }
   if (method === "shutdown") return result(id, null);
   if (method === "exit") process.exit(0);
   if (id !== undefined) error(id, -32601, `method not found: ${method}`);

package/mcp.mjs

@@ -178,6 +178,24 @@ const TOOLS = {
       return r;
     },
   },
+  candor_fix: {
+    description: "THE BOUNDARY FIX: when `fn` performs `effect` in a layer the policy forbids (a violation candor_whatif/candor_gate reports), compute the architectural REMEDY — not just 'the domain can't do Net', but WHERE the effect belongs and the refactor to put it there: the direct call site to hoist, the forbidden-layer functions that become pure and thread the value as a parameter, and the nearest allowed-layer caller to perform the effect ({ crossing, site, deniedSpan, hoistTo, policyAlternative }). The remedial inverse of candor_whatif. Call this INSTEAD OF guessing a fix (adding `allow` to the domain, moving the I/O one call up, threading a handle the wrong way). Advisory: it names the structure, you write the code; the gate re-scan verifies. Uses `policy` if given, else the repo's checked-in .candor/config policy (spec §3.4).",
+    schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a §6.2 policy file (optional; defaults to the repo's .candor/config `policy`)" }, ...reportArg }, required: ["fn", "effect"] },
+    run: (a, p) => {
+      // The fix is defined relative to a boundary — a policy is required. Given → confined fail-closed read;
+      // else the repo's checked-in policy (same resolution as candor_gate), so it works zero-config.
+      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) — the fix is defined relative to the boundary it crosses");
+        text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
+      }
+      const r = Q.fix(Q.loadCallgraph(p), Q.loadReport(p), a.fn, a.effect, parsePolicy(text), scopeMatches);
+      if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
+      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 — the engine's own --gate-json run is the authoritative CI form: it additionally fails an allow rule whose literal surface is INCOMPLETE (a masked/invisible endpoint), which is not a report field, so a green here can still be red in CI.",
     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: [] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
   "type": "module",
   "dependencies": {

package/query-core.mjs

@@ -486,3 +486,103 @@ export function whatif(cg, target, eff, policyParsed, scopeMatches) {
   }
   return { of: targets, effect: eff, affected: [...affected].sort(), violations, ok: violations.length === 0 };
 }
+
+// deniedLayer: the deny/`pure` scope (the "layer") forbidding `eff` at `fn`, or null if allowed there.
+// Mirrors the gate's AS-EFF-006 predicate (candor-java/candor-query): a `deny` fires when it names the
+// effect; a `pure` rule (empty effects) forbids every real effect but not Unknown.
+function deniedLayer(fn, eff, policyParsed, scopeMatches) {
+  for (const r of policyParsed.deny) {
+    const denies = r.effects.length === 0 ? eff !== "Unknown" : r.effects.includes(eff);
+    if (denies && (!r.scope || scopeMatches(fn, r.scope))) return r.scope ?? "";
+  }
+  return null;
+}
+
+// The site-anchored cut (integrations/FIX-SPEC.md), shared by fix + fixGate — the byte-for-byte port of
+// candor-query / candor-java's computeRemedy. Forward-BFS to the direct site(s), then climb UP through the
+// denied layer so the pure span is the same whichever inheriting function triggered it (root-independent);
+// the allowed-layer callers where the climb stops are the hoist frontier.
+function computeRemedy(start, eff, layer, cg, rev, byName, policyParsed, scopeMatches) {
+  const sites = new Set();
+  const fseen = new Set([start]);
+  const fq = [start];
+  while (fq.length) {
+    const cur = fq.shift();
+    const fe = byName.get(cur);
+    if (fe && (fe.direct ?? []).includes(eff)) sites.add(cur);
+    for (const c of cg[cur] ?? []) {
+      const ce = byName.get(c);
+      if (ce && (ce.inferred ?? []).includes(eff) && !fseen.has(c)) { fseen.add(c); fq.push(c); }
+    }
+  }
+  const anchors = sites.size ? [...sites] : [start];
+  const deniedSpan = new Set();
+  const hoistTo = new Set();
+  const up = [];
+  for (const a of anchors) {
+    if (deniedLayer(a, eff, policyParsed, scopeMatches) !== null) deniedSpan.add(a);
+    up.push(a);
+  }
+  while (up.length) {
+    const cur = up.shift();
+    for (const caller of rev.get(cur) ?? []) {
+      const ce = byName.get(caller);
+      if (ce && !(ce.inferred ?? []).includes(eff)) continue; // doesn't route the effect
+      if (deniedLayer(caller, eff, policyParsed, scopeMatches) !== null) {
+        if (!deniedSpan.has(caller)) { deniedSpan.add(caller); up.push(caller); }
+      } else {
+        hoistTo.add(caller);
+      }
+    }
+  }
+  return {
+    fn: start, effect: eff, layer,
+    cleanHoist: hoistTo.size > 0,
+    site: [...sites].sort(),
+    deniedSpan: [...deniedSpan].sort(),
+    hoistTo: [...hoistTo].sort(),
+    policyAlternative: layer ? `allow ${eff} ${layer}` : `allow ${eff}`,
+  };
+}
+
+// fix: the boundary remedy for ONE function (the remedial inverse of whatif). Returns null if the function
+// isn't in the graph; `{ crossing:false, reason }` if it performs the effect but no policy forbids it there
+// (or it doesn't perform it) — a no-op the caller reports plainly; else the full remedy (`crossing:true`).
+export function fix(cg, fns, target, eff, policyParsed, scopeMatches) {
+  const names = new Set(Object.keys(cg));
+  for (const e of fns) names.add(e.fn);
+  const m = matches([...names], target);
+  if (m.length === 0) return null;
+  const byName = indexFns(fns);
+  // prefer a match that actually performs the effect, so a bare leaf resolves to the violating function
+  const start = m.find((n) => (byName.get(n)?.inferred ?? []).includes(eff)) ?? m[0];
+  const se = byName.get(start);
+  if (!se || !(se.inferred ?? []).includes(eff))
+    return { fn: start, effect: eff, crossing: false, reason: "does-not-perform" };
+  const layer = deniedLayer(start, eff, policyParsed, scopeMatches);
+  if (layer === null)
+    return { fn: start, effect: eff, crossing: false, reason: "not-forbidden" };
+  const rev = reverseGraph(cg);
+  return { crossing: true, ...computeRemedy(start, eff, layer, cg, rev, byName, policyParsed, scopeMatches) };
+}
+
+// fixGate: a remedy for EVERY deny/`pure` (AS-EFF-006) crossing in the report, collapsing the inheritors of
+// one root cause to a single plan (keyed by effect|layer|site|hoist). Returns { ok, remedies } — the shape
+// the edit-time loop folds into its block message.
+export function fixGate(cg, fns, policyParsed, scopeMatches) {
+  const byName = indexFns(fns);
+  const rev = reverseGraph(cg);
+  const plans = new Map();
+  for (const e of fns) {
+    for (const eff of (e.inferred ?? [])) {
+      const layer = deniedLayer(e.fn, eff, policyParsed, scopeMatches);
+      if (layer !== null) {
+        const p = computeRemedy(e.fn, eff, layer, cg, rev, byName, policyParsed, scopeMatches);
+        const key = `${p.effect}|${p.layer}|${p.site}|${p.hoistTo}`;
+        if (!plans.has(key)) plans.set(key, p);
+      }
+    }
+  }
+  const remedies = [...plans.values()];
+  return { ok: remedies.length === 0, remedies };
+}

package/query.mjs

@@ -31,6 +31,7 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          callers as coreCallers, callersFrontier, loadHierarchy,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
+         fix as coreFix, fixGate as coreFixGate,
          loadReport, loadCallgraph, reportVersion } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
@@ -57,6 +58,8 @@ const SUBCOMMANDS = [
   ["gains", "<cur-prefix> <base-prefix>", "the supply-chain alarm: what the surface gained between two reports"],
   ["path", "<prefix> <fn> <Effect>", "a call path from a function to where an effect enters"],
   ["whatif", "<prefix> <fn> <Effect> [policy-file] [0|1]", "the impact of giving a function an effect, vs a policy (exit 1 on a violation)"],
+  ["fix", "<prefix> <fn> <Effect> <policy-file>", "the boundary fix: where the effect belongs + the hoist refactor"],
+  ["fix-gate", "<prefix> <policy-file>", "a fix for EVERY boundary crossing — the loop's block-message remedy"],
   ["agents", "", "print the agent contract for this build (AGENTS.md)"],
 ];
 
@@ -250,6 +253,31 @@ switch (cmd) {
     process.exit(r.violations.length ? 1 : 0);
     break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
+  case "fix": {
+    // THE BOUNDARY FIX (integrations/FIX-SPEC.md): where a forbidden effect belongs + the hoist refactor.
+    // The remedial inverse of whatif. A policy is REQUIRED and must be readable (the fix is defined relative
+    // to the boundary the edit crossed) — a typo'd path fails LOUD, never a silently-empty "no crossing".
+    const [prefix, target, eff, policyFile] = args;
+    if (!target || !eff) { console.error("usage: candor-ts-query fix <prefix> <fn> <Effect> <policy-file>"); process.exit(2); }
+    if (!policyFile) { console.error("candor: fix requires a policy file — the fix is the refactor that restores the boundary the edit crossed"); process.exit(2); }
+    let ptext;
+    try { ptext = fs.readFileSync(policyFile, "utf8"); }
+    catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
+    const r = coreFix(loadCallgraph(prefix), loadReport(prefix), target, eff, parsePolicy(ptext), scopeMatches);
+    if (r === null) { console.error(`candor: no function matching \`${target}\` in the call graph`); process.exit(2); }
+    emit(r);
+    break;
+  }
+  case "fix-gate": {
+    // A remedy for EVERY deny/pure crossing — the shape the edit-time loop folds into its block message.
+    const [prefix, policyFile] = args;
+    if (!policyFile) { console.error("candor: fix-gate requires a policy file"); process.exit(2); }
+    let ptext;
+    try { ptext = fs.readFileSync(policyFile, "utf8"); }
+    catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
+    emit(coreFixGate(loadCallgraph(prefix), loadReport(prefix), parsePolicy(ptext), scopeMatches));
+    break;
+  }
   default:
     // no command (cmd === undefined) or an unknown one: the FULL usage, not the stale 6-item list.
     if (cmd !== undefined) console.error(`candor-ts-query: unknown command '${cmd}'`);