candor-ts 0.8.7 → 0.8.9

package/AGENTS.md

@@ -12,16 +12,16 @@ chains by hand.
 > **Already installed? Report the version and ask before upgrading — before you scan.** If this
 > project already has candor (a `.candor/` report directory, or `candor-ts` reachable via `npx`/a
 > global install), do this *first*: run `npx -y candor-ts --version` (offline) and **tell the user
-> plainly which version they're on** — e.g. *"This project is on candor-ts 0.7.1 (spec 0.7)."* On a
-> build too old for the flag, read `candor.version` / `candor.spec` from an existing
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.8)."*
+> On a build too old for the flag, read `candor.version` / `candor.spec` from an existing
 > `.candor/report*.json`, or `npm ls -g candor-ts`.
 >
 > **Staying current is your job, not candor's.** candor never phones home — it audits and denies the
 > Net effect, so it will not reach the network to check itself. `candor-ts --version` prints the
 > installed build, the spec contract it speaks, and the upgrade line (`npm install -g
 > candor-ts@latest`) — fully offline. **You** have the network: compare the installed version against
-> npm. If it's behind, **ask the user before upgrading** — e.g. *"candor-ts 0.7.2 is available
-> (you're on 0.7.1) — upgrade before I scan?"* — and run `npm install -g candor-ts@latest` (or `npx
+> npm. If it's behind, **ask the user before upgrading** — e.g. *"candor-ts `<latest>` is available
+> (you're on `<installed>`) — upgrade before I scan?"* — and run `npm install -g candor-ts@latest` (or `npx
 > -y candor-ts@latest`) only if they agree. Never upgrade silently: an analysis tool's version is
 > part of its result's provenance, so the user decides when it changes. If it's already current (or
 > the user declines), just proceed; if candor isn't installed at all, install it normally.
@@ -41,19 +41,32 @@ npx -y candor-ts <dir> --allow-js       # also analyze .js/.mjs sources (walks t
 
 This writes `<project-dir>/.candor/report.json` and `.candor/report.callgraph.json` (override
 with `--out <prefix>`). **Install the TARGET's dependencies first** (`npm install` in the project)
-— without node_modules, imports don't resolve and most functions honestly read `Unknown` (the
+— without node_modules, imports don't resolve and most functions read `Unknown` (disclosed; the
 scanner warns loudly). Add `--policy <file>` (or set `CANDOR_POLICY`) to enforce a §6.2 policy over the
 scan: exit 1 on violation, exit 2 LOUDLY if the policy file is unreadable. `--gate-json <file|->`
 additionally writes the structured verdict `{spec, ok, violations:[{rule,fn,effects,detail}]}`
 (spec §3.3) — the machine-readable form CI/SARIF converters consume, from the SAME violations that
-set the exit code. A checked-in `.candor/config` (spec §3.4; `policy <file>` / `deps <paths>`, one
-key per line, discovered walking UP from the scan target, relative values anchored to the config's
-repo) is the no-env-wiring floor; flag → env → config → default.
+set the exit code. A checked-in `.candor/config` (spec §3.4; `policy <file>` / `baseline <report>` /
+`deps <paths>`, one key per line, discovered walking UP from the scan target, relative values
+anchored to the config's repo) is the no-env-wiring floor; flag → env → config → default.
+
+**The AS-EFF-005 baseline guard** (spec §7): set `CANDOR_BASELINE=<saved report.json>` (or the
+config `baseline` key) and the scan compares per function — an EXISTING function that gained an
+effect versus the baseline fails the run (exit 1, `[AS-EFF-005]` lines, records join `--gate-json`);
+new functions are exempt. Fail-closed: an unparseable baseline, or one from a different engine
+build, is invalid gate input — exit 2 WITHOUT evaluating (never a silent skip); an absent file is a
+note and the guard is inactive. `query diff` is the read-only twin: it DISCLOSES a build mismatch
+(⚠, exit 0) instead of failing — use the scan-time guard, not `diff`, as the CI gate. Semantics
+match the reference engine (candor-java).
 
 **Report shape:** the file is `{ "candor": {version, toolchain, spec}, "functions": [...] }`;
 `functions` is an **array** of entries (not a map — don't index it by name), each carrying **`fn`**
 — module-qualified, `.`-separated
-(`src.db.save` for `save()` in `src/db.ts`; class methods are `src.api.Client.send`) — with
+(`src.db.save` for `save()` in `src/db.ts`; class methods are `src.api.Client.send`; a function
+declared inside a TS `namespace` carries the namespace segments too — `src.util.Ns.helper` — in
+`fn` AND the callgraph/hierarchy keys, while its `hash` keeps the bare local name for cross-package
+joining; builds before 0.8.7 omitted the namespace segments, so an engine upgrade across that line
+is baseline-invalidating — regenerate saved reports) — with
 `inferred` (the full transitive set) / `direct` / `unresolved` / optional `hosts`/`cmds`/`paths`/
 `tables` (the literal surfaces). **Only effectful-or-unresolved functions appear in the report;
 pure functions are omitted** — a function present in the callgraph sidecar but absent from
@@ -61,7 +74,7 @@ pure functions are omitted** — a function present in the callgraph sidecar but
 (a test file? an unexported arrow inside an object literal?) — conclude nothing.
 
 A dist-CJS export unit (a `module.exports` surface scanned with `--allow-js`) carries
-`unitKind: "export"` (spec 0.7, informative); ordinary functions omit the field.
+`unitKind: "export"` (spec 0.8, informative); ordinary functions omit the field.
 
 **Multi-package (monorepos / private deps):** point `CANDOR_DEPS` at the dependencies' reports
 (a path list, or a directory of `*.json`); an unclassified call into a package with a loaded
@@ -94,7 +107,11 @@ 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.
+edit-delta); `candor-lsp` serves the same report as CodeLens/hover/diagnostics in any LSP editor,
+plus the pre-edit whatif as a code action (`candor: what if <fn> performed <E>?` → the
+`candor.whatif` command: the query-core whatif's verdict + blast radius as a showMessage and a
+transient diagnostic, cleared on the file's next open/save — plain LSP, so helix/neovim/VS
+Code/JetBrains-via-LSP4IJ all get it without client code).
 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
@@ -117,16 +134,17 @@ want-JSON flag.
 - **Arrow-const functions are first-class**: `export const f = async () => …` is analyzed and named
   like a declaration; calls to it are edges. An arrow assigned inside a function body becomes its
   own unit (`src.x.helper`) — effects still propagate to the enclosing caller through the edge.
-- **The classifier is curated** (node builtins + a small npm tier: axios/got/node-fetch/undici/ws,
-  pg/mysql2/mongodb/redis/knex, execa/cross-spawn, fs-extra/rimraf/glob, dotenv, winston/pino).
+- **The classifier is curated** — the node builtins plus a growing npm tier; the README's
+  "classifier" paragraph is the ONE current list (this file deliberately doesn't duplicate it — a
+  vendored copy here drifted a full generation once).
   An unlisted package contributes nothing — an effect through it is invisible, not `Unknown`. The
   scanner **names these per scan**: the receipt's `κ doesn't know N packages…` line lists every npm
   package the code demonstrably calls that κ neither classifies nor has reviewed-pure — read it
   before concluding "no effect" through anything it names.
 - **`process.env.X` reads are `Env`** (a property read, not a call); `Date.now()` is `Clock`.
-- **DI-style code reads `Unknown` a lot, honestly**: a function-typed parameter or field being
+- **DI-style code reads `Unknown` a lot, by design**: a function-typed parameter or field being
   called is genuinely indeterminate (rimraf's injected-fs style yields many `Unknown`s — that's the
-  §4 contract, not noise). When every visible call site passes a *named* function, the callback
+  §4 disclosure contract, not noise). When every visible call site passes a *named* function, the callback
   resolves instead. And a method call on a **local-interface-typed value** (`store.save()` where
   `class PgStore implements Store`) resolves to the local implementors when the dispatch is narrow
   (≤12 classes) — the layered-DI pattern carries its real effects; only an interface with no
@@ -147,6 +165,10 @@ allow Db in db  orders ledger.*       # the db module touches ONLY these tables
 forbid domain -> infra
 ```
 
+Note the `pure` semantics: it forbids every *effect* but NOT `Unknown` — the §4 trust marker is
+uncertainty, not an effect (matching the reference engine, candor-java). Where a boundary must also
+exclude the unverifiable case, say so explicitly: `deny Unknown <scope>` is the knob.
+
 ## The trust rule — do not skip this
 
 `inferred` is authoritative for what candor-ts resolved. When `unresolved` is true (or `Unknown` is

package/PROVE-IT.md

@@ -30,7 +30,9 @@ TRANSITIVE caller, across all files?" Work as you normally would (grep, read). W
 list to ./candor-manual-<target>.txt in the repo root (NOT a fixed /tmp name — repeated runs must
 not cross-contaminate) — one function per line, named the way the callgraph keys them:
 module-qualified with "." segments (src.db.save for save() in src/db.ts; class members
-src.api.Client.send, constructors src.api.Client.constructor; a NESTED named function is keyed flat
+src.api.Client.send, constructors src.api.Client.constructor; a function declared inside a TS
+namespace carries the namespace segments — src.util.Ns.helper for helper() in namespace Ns — only
+the report's `hash` field keeps the bare local name; a NESTED named function is keyed flat
 under its module, while an anonymous arrow — including one wrapped in a cast — folds into its
 enclosing function). Also note roughly how
 many file-reads/searches it took you.

package/README.md

@@ -5,7 +5,7 @@
 **candor for TypeScript: per-function side effects, transitively, with a deterministic policy
 gate.** candor-ts resolves every call through the TypeScript compiler API and reports, for each
 function in your project, which effects it can reach — `Net`, `Fs`, `Db`, `Exec`, `Env`, `Clock`,
-… — **including effects inherited through any chain of calls across files**, with an honest
+… — **including effects inherited through any chain of calls across files**, with a disclosed
 `Unknown` wherever resolution fails (a callback value, an `any`-typed callee — never silently
 pure). A [candor-spec](https://github.com/tombaldwin/candor-spec) implementation, sibling of the
 [Rust](https://github.com/tombaldwin/candor-rust) and
@@ -20,6 +20,8 @@ node scan.mjs <project-dir>                 # tsconfig.json honored; tests exclu
                                             #   <dir>/.candor/report.json + .callgraph.json
 node scan.mjs . --policy .candor/policy     # the §6.2 gate: exit 1 on violation, 2 if unreadable
 node scan.mjs . --gate-json gate.json       # + the structured verdict {spec, ok, violations} (§3.3)
+CANDOR_BASELINE=saved.json node scan.mjs .  # AS-EFF-005 guard: exit 1 if an existing fn GAINED an
+                                            #   effect vs the saved report; 2 if it can't evaluate
 
 node scan.mjs --version                     # installed build + spec contract (offline), + upgrade line
 
@@ -35,14 +37,31 @@ node query.mjs diff     .candor/report baseline 1  # per-function effect delta (
 ```
 
 A checked-in **`.candor/config`** (spec §3.4) replaces the env wiring — `policy arch.policy` /
-`deps <report paths>` one per line, discovered by walking up from the scan target; relative values
-resolve against the config's repo, so CI is "point at the repo". A configured-but-unusable
-config/policy fails loud (exit 2), never silently gateless.
+`baseline <report.json>` / `deps <report paths>` one per line, discovered by walking up from the
+scan target; relative values resolve against the config's repo, so CI is "point at the repo". A
+configured-but-unusable config/policy/baseline fails loud (exit 2), never silently gateless.
+
+The scan-time **baseline guard** (AS-EFF-005, spec §7) makes effect *regressions* un-shippable:
+point `CANDOR_BASELINE` (or the config's `baseline` key) at a saved report, and any existing
+function that **gained** an effect fails the scan — exit 1, the records join the `--gate-json`
+verdict. New functions are exempt (reviewed as new code, not a regression). The guard is
+fail-closed like the policy gate: a present-but-unparseable baseline, or one produced by a
+different engine build (§2.1 — an engine upgrade is baseline-invalidating), exits 2 **without
+evaluating**; only a genuinely absent file is a one-line note (guard not active). Keep the two
+surfaces straight: `query diff` is the read-only comparison — it *discloses* a producing-build
+mismatch (⚠, exit 0) and informs; the scan-time guard is the gate-grade fail-closed surface, the
+one CI should hold. Semantics mirror the reference engine (candor-java) exactly.
 
 **Staying current:** check your installed version and upgrade — [candor/AGENTS.md §2a](https://github.com/tombaldwin/candor/blob/main/AGENTS.md#2a-staying-current--check-the-version-upgrade). `npx -y candor-ts --version` prints the build, the spec, and the upgrade one-liner (offline; candor never phones home).
 
 Function names are module-qualified with `.` segments (`src.db.save`), so policy scopes read
-naturally:
+naturally. A function declared inside a TS `namespace` carries the namespace segments in `fn` and
+the callgraph keys (`src.util.Ns.helper`) — so layer policies on namespaces bite — while the §2
+`hash` join key keeps the bare local name; builds before 0.8.7 omitted the segments, so crossing
+that line invalidates saved baselines (regenerate them). A `pure <scope>` rule forbids every
+*effect* but not `Unknown` — the §4 trust marker is uncertainty, not an effect (matching the
+reference engine, candor-java); `deny Unknown <scope>` is the explicit knob for boundaries that
+must also exclude the unverifiable case.
 
 ```text
 # .candor/policy
@@ -104,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:
 
@@ -132,16 +159,17 @@ a κ-ledger blind spot. A name outside the §1 vocabulary voids the declaration
 silently narrow a surface). And `candor-ts-query gains <cur> <base>` flags the **supply-chain**
 delta — the effects a surface *gained* between two reports.
 Real-world consequence, measured on [rimraf](https://github.com/isaacs/rimraf) (50 files, 55
-functions analyzed): its DI-style fs injection means many functions honestly read `Unknown` —
+functions analyzed): its DI-style fs injection means many functions read `Unknown`, disclosed —
 that's the contract working, not noise. The report says "can reach", never "does"; an absent
 literal is never a claim of absence.
 
 ## Cross-engine consistency — machine-checked
 
-candor-ts runs live in the spec's conformance CI as the third engine in **three differentials**:
-the effect-set oracle (20 shared cases), the §6.2 policy-grammar battery (including `allow Db`),
-and the §3.1 query-shape and match-ladder checks — all three engines must answer identically, on
-every push to the spec.
+candor-ts is one of the **four code engines** (with the reference engine candor-java, the Rust
+engines, and candor-swift) held together by the spec's **16-part conformance suite**: the shared
+effect-set oracle, the §6.2 policy-grammar battery (including `allow Db`), the §3.1 query-shape
+and match-ladder checks, the gate exit-code contracts, and the newer parts up through the
+pure-vs-Unknown ruling (PART 16) — the engines must answer identically, on every push to the spec.
 
 ## What the analysis core implements (and where the spec told it how)
 
@@ -176,13 +204,14 @@ read the Rust source".
 0.8.x, speaking candor-spec 0.8: the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
 `--include-unknown` dispatch frontier), the MCP server, the LSP server, and the watch loop are
-real, behaviorally tested (`npm test` — ~360 assertions across six suites), **soundness-fuzzed
+real, behaviorally tested (`npm test` — the behavioral suite across six harnesses), **soundness-fuzzed
 with verified teeth** (`node fuzz.mjs` — spec §7.13: generated effect chains through every encoded
 call form, any silent-pure = red), and conformance-held against the Rust/JVM/Swift engines. The
 npm classifier tier is deliberately curated and keeps growing case-by-case. Entry points
 (Nest/Next populations), `unknownWhy` origins, `reachable`, cross-package inheritance
 (`CANDOR_DEPS` + the spec §2 `hash`, version-trusted per §2.1), and `--allow-js` are all in.
-On npm: `npx -y candor-ts <dir>`.
+On npm: `npx -y candor-ts <dir>`. Per-release detail (⚠ marks report/verdict-affecting changes):
+[CHANGELOG.md](CHANGELOG.md).
 
 ## Development
 

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,90 @@ 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";
+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 }],
+      },
+    });
+  }
+  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 LSP method surface ---------------------------------------------------------------------------
 function handle(msg) {
@@ -211,14 +306,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] },
       },
       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 +329,18 @@ 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") {
+    if (params?.command !== WHATIF_COMMAND) {
+      logMessage(`candor-lsp: unknown command \`${params?.command}\` — this server provides only ${WHATIF_COMMAND}`);
+      return result(id, null);
+    }
+    try { return result(id, runWhatif(params?.arguments?.[0])); }
+    catch (e) { logMessage(`candor-lsp: ${WHATIF_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/package.json

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

package/scan-core.mjs

@@ -36,11 +36,11 @@ export const KAPPA_RULES = [
   // 0/4/6 (or a boolean) with no socket, no fd, no syscall — pure functions. The whole-module Net rule
   // once fabricated Net onto them; a real-world sweep on node-fetch caught it (its trustworthy URL
   // predicates isOriginPotentiallyTrustworthy/isUrlPotentiallyTrustworthy call isIP() and inherited a
-  // FABRICATED Net — the cardinal sin — purely from this classification, with no local Net edge). Only
+  // FABRICATED Net — the precision failure — purely from this classification, with no local Net edge). Only
   // these three named validators are freed; every genuine verb (connect/createConnection/createServer…)
   // stays Net (the matcher excludes ONLY new + the three validators, nothing else).
   // ALSO exempt the pure CONFIG/METADATA members the whole-module rule fabricated Net on (sweep [9], the
-  // cardinal sin — none touch a socket/fd/syscall): tls.getCiphers/createSecureContext/checkServerIdentity
+  // precision failure — none touch a socket/fd/syscall): tls.getCiphers/createSecureContext/checkServerIdentity
   // (cipher-list + cert helpers), http.validateHeaderName/validateHeaderValue (string validators, like
   // isIP), and a Socket/Server's setKeepAlive/setNoDelay/ref/unref/address (TCP-option + bound-address
   // metadata — no I/O). Every genuine verb still classifies; only these proven-pure names are freed.
@@ -51,7 +51,7 @@ export const KAPPA_RULES = [
   // reverse query DNS servers directly). Was unclassified, so a `dns.resolve(...)` read silently pure.
   // Same construction-and-pure-accessor carve-out as the net cluster: `new dns.Resolver()` ("new") is
   // inert, and the SERVER-CONFIG accessors getServers/setServers/get|setDefaultResultOrder touch no
-  // network (in-process config) — classifying them Net would FABRICATE the cardinal sin. Every genuine
+  // network (in-process config) — classifying them Net would be a FABRICATION (the precision failure). Every genuine
   // resolver verb (lookup/resolve4/resolveMx/reverse/…) stays Net. Covers node:dns/promises too.
   [/^(node:)?dns(\/promises)?$/,
    /^(?!(new|getServers|setServers|getDefaultResultOrder|setDefaultResultOrder)$)/, "Net"],

package/scan.mjs

@@ -13,7 +13,9 @@
  * `any`-typed callee or a function-valued parameter/field IS the "could not resolve" case), and
  * emit the §2 report envelope + the §2.2 call-graph sidecar (every analyzed function a key). With
  * --policy (or CANDOR_POLICY), evaluate the §6.2 gate (AS-EFF-006/008/009) over the result: exit 1
- * on violation, exit 2 LOUDLY on an unreadable policy.
+ * on violation, exit 2 LOUDLY on an unreadable policy. With CANDOR_BASELINE (or a config `baseline`
+ * key), run the AS-EFF-005 regression guard against a saved report: an existing fn gaining an effect
+ * is a violation (exit 1); an unparseable or different-build baseline is invalid gate input (exit 2).
  *
  * Usage: node scan.mjs <dir | file.ts | tsconfig.json> [--out <prefix>] [--policy <file>]
  *        node scan.mjs <file.ts> <out-prefix>                  (legacy positional form)
@@ -65,6 +67,10 @@ USAGE: candor-ts <dir | file.ts | tsconfig.json> [--out <prefix>] [--json] [--po
   -V, --version     print the build and spec version (offline)
   -h, --help        show this help
 
+CANDOR_BASELINE=<report.json> (or a .candor/config \`baseline\` key) runs the AS-EFF-005 regression
+guard against a saved same-build report: exit 1 when an existing function gained an effect, exit 2
+on an unparseable or different-build baseline (never evaluated), a stderr note when absent.
+
 See https://github.com/tombaldwin/candor`);
   process.exit(0);
 }
@@ -168,6 +174,11 @@ 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;
+// baseline (the AS-EFF-005 regression guard, SPEC §7 item 5): CANDOR_BASELINE env → config `baseline`
+// (path-valued keys are already resolved against the config's anchor above). No CLI flag — matching
+// candor-java, the reference engine (env/config only). A BARE `baseline` line ("") fails loud below.
+let baselinePath = process.env.CANDOR_BASELINE ?? null;
+if (baselinePath === null && candorConfig.baseline !== undefined) baselinePath = candorConfig.baseline;
 
 // ---- project discovery (a dir, a single file, or a tsconfig) --------------------------------------
 let rootDir, fileNames, compilerOptions = {
@@ -1013,7 +1024,7 @@ function enclosing(node) {
     // the decorated declaration's body. The parent chain of a decorator's expression is
     // CallExpression → Decorator → MethodDeclaration/ClassDeclaration/Parameter, so `enclosing` otherwise
     // lands on the decorated unit and FABRICATES the factory's effects onto that method/class/param and
-    // every transitive caller (a cardinal sin — @Entity/@Injectable factories that touch I/O would
+    // every transitive caller (a fabrication — @Entity/@Injectable factories that touch I/O would
     // poison every decorated handler). Stop at the Decorator: the factory's own effects live in its own
     // function unit; the application site attributes to nothing (load-time, like a no-arg decorator).
     if (ts.isDecorator(p)) return null;
@@ -1220,7 +1231,7 @@ function noteOpaqueIteration(node, iterExpr, localResolved) {
 // Callee names that INVOKE a function/method argument (so a fn-reference passed to one is reachable
 // through it). Array/iterable HOFs, the timer/microtask schedulers, and Promise continuations. A
 // STORE/compare/log sink (`set`/`push`/`add`/`includes`/`indexOf`/`concat`/`log`/`stringify`/…) is
-// deliberately ABSENT — edging there would fabricate the fn's effects on a pure path (the cardinal sin).
+// deliberately ABSENT — edging there would fabricate the fn's effects on a pure path (the precision failure).
 const HOF_INVOKERS = new Set([
   "map", "forEach", "filter", "reduce", "reduceRight", "find", "findIndex", "findLast", "findLastIndex",
   "some", "every", "flatMap", "sort", "group", "groupBy", "partition", "mapValues", "flatMapDeep",
@@ -1302,7 +1313,7 @@ function visitCalls(node) {
         // on a non-local callee so a local callee that merely STORES (never invokes) keeps its precision.
         // ONLY a callee that actually INVOKES its fn argument makes the reference reachable here. The
         // earlier version edged for ANY non-local callee — fabricating the fn's effects onto a pure path
-        // (the cardinal sin) for STORE/compare/log sinks that never call it (`map.set(k, fn)`,
+        // (the precision failure) for STORE/compare/log sinks that never call it (`map.set(k, fn)`,
         // `arr.push(fn)`, `arr.includes(fn)`, `console.log(fn)`, `[fn]`). Gate on a known INVOKING HOF by
         // callee name; a custom non-local HOF that invokes its arg is an honest under-report (sound),
         // never a fabrication. (A LOCAL callee keeps its precise callback-flow below.)
@@ -1617,7 +1628,7 @@ function visitCalls(node) {
           // "Console" effect in §1, so it must be PURE. Suppress the fabricated effect for these receivers
           // (a real `net.Socket` you constructed and `.write()` to still classifies Net — only the three
           // std streams are freed). Real-world sweep: nanoid/commander(×43)/bunyan/pino fabricated Net
-          // purely from a `process.stdout.write` — the cardinal sin.
+          // purely from a `process.stdout.write` — the precision failure.
           if (eff && (ts.isPropertyAccessExpression(node.expression) || ts.isElementAccessExpression(node.expression))
               && rootsAtStdStream(node.expression.expression))
             eff = null;
@@ -2168,12 +2179,74 @@ if (unlistedSeen.size > 0) {
     + `effects through ${top.length === 1 ? "it are" : "them are"} INVISIBLE (not Unknown): ${shown}${more}`);
 }
 
+// ---- the gate surfaces: the AS-EFF-005 baseline guard + the standing §6.2 policy gate --------------
+// When stdout carries a JSON document — the §2 envelope (--json) OR the streamed gate verdict
+// (--gate-json -) — it must stay pure JSON: route the gate's [AS-EFF-…] violation lines to stderr so
+// a `… | jq` / `… | candor-sarif` pipe never breaks.
+const emitViolation = (wantJson || gateJsonPath === "-") ? (l) => console.error(l) : (l) => console.log(l);
+let gateViolations = [];
+
+// ---- the AS-EFF-005 baseline guard (CANDOR_BASELINE / config `baseline`; SPEC §7 item 5) -----------
+// Semantics mirror the reference engine (candor-java Policy.checkBaseline) exactly:
+//  · ABSENT file → one stderr note, guard inactive (ratchet not adopted; exit unchanged).
+//  · PRESENT but unparseable (corrupt/truncated/not-a-report) → exit 2 WITHOUT evaluating — the guard
+//    must never silently pass on unreadable gate input (the unreadable-policy class, §6.2).
+//  · A missing provenance header (legacy bare array) OR a producing `candor.version` ≠ this build →
+//    exit 2 WITHOUT evaluating (§2.1: a baseline is comparable only to its OWN producing version —
+//    evaluating a stale one yields a bogus AS-EFF-005 wave; skipping is an unbounded fail-open window).
+//    The read-only `diff`/`gains` QUERIES disclose a mismatch instead of failing — a comparison the
+//    user explicitly asked for should inform; this scan-time guard is the gate and fails closed.
+//  · Valid + same build → per-fn compare: an EXISTING fn gaining an effect is an [AS-EFF-005]
+//    violation (exit 1, joins --gate-json); a fn absent from the baseline is NEW code, reviewed as
+//    such, not a regression. Baselines omit pure fns (spec §2), so absent-prior means no prior claim.
+if (baselinePath !== null) {
+  const shownB = baselinePath === "" ? "(configured empty)" : baselinePath;
+  if (baselinePath !== "" && !fs.existsSync(baselinePath)) {
+    console.error(`candor-ts: CANDOR_BASELINE ${baselinePath} does not exist — the regression guard is `
+      + `not active (record one: candor-ts <target> --out <prefix>, then point at the report .json).`);
+  } else {
+    let root = null;
+    try { root = JSON.parse(fs.readFileSync(baselinePath, "utf8")); } catch { /* root stays null → exit 2 */ }
+    const arr = Array.isArray(root) ? root : (root && typeof root === "object" ? root.functions : null);
+    if (!Array.isArray(arr)) {
+      console.error(`candor-ts: baseline ${shownB} exists but could not be parsed (corrupt/truncated?) — `
+        + `failing (exit 2); the guard must not silently pass on an unreadable baseline. Regenerate it with this build.`);
+      process.exit(2);
+    }
+    const baseVersion = !Array.isArray(root) && root.candor && typeof root.candor === "object"
+      && typeof root.candor.version === "string" ? root.candor.version : null;
+    if (baseVersion === null) {
+      console.error(`candor-ts: the baseline ${shownB} has no provenance header (a legacy/bare-array report) — `
+        + `a baseline is comparable only to its producing build (§2.1). Failing (exit 2); regenerate it with this build.`);
+      process.exit(2);
+    }
+    if (baseVersion !== ENGINE_VERSION) {
+      console.error(`candor-ts: the baseline ${shownB} was produced by engine build ${baseVersion} but this is `
+        + `build ${ENGINE_VERSION} — an engine swap is baseline-invalidating and the gate cannot evaluate `
+        + `(exit 2; never a silent skip, never a bogus AS-EFF-005 wave). Regenerate deliberately with this build.`);
+      process.exit(2);
+    }
+    const base = new Map();
+    for (const e of arr) {
+      if (e && typeof e.fn === "string" && e.fn) base.set(e.fn, new Set(Array.isArray(e.inferred) ? e.inferred : []));
+    }
+    for (const name of [...inferred.keys()].sort()) {
+      const prior = base.get(name);
+      if (prior === undefined) continue;                    // new function — not a regression
+      const gained = [...inferred.get(name)].filter((x) => !prior.has(x)).sort();
+      if (gained.length) {
+        gateViolations.push({ rule: "AS-EFF-005", fn: name, effects: gained,
+          detail: `\`${name}\` gained effect { ${gained.join(", ")} } not present in the baseline` });
+      }
+    }
+  }
+}
+
 // ---- the standing §6.2 gate (--policy / CANDOR_POLICY) --------------------------------------------
 // `!== null`, not truthiness: a CONFIGURED-but-EMPTY policy (a bare `policy` config line, a set-but-
 // empty CANDOR_POLICY) is "" — falsy, so a truthy check silently skipped the gate, the exact quiet
 // drop the config comment above promises fails loud. "" now reaches the read, which fails → exit 2
 // (the Rust engine's behavior on the same input).
-let gateViolations = [];
 if (policyPath !== null) {
   let text;
   try {
@@ -2187,13 +2260,9 @@ if (policyPath !== null) {
   // java/rust engines (not a report field) — passed to the gate so an incomplete surface fails closed.
   const incompleteMap = new Map();
   for (const [name, rec] of fns) if (rec.incomplete.size) incompleteMap.set(name, rec.incomplete);
-  gateViolations = evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap);
-  // When stdout carries a JSON document — the §2 envelope (--json) OR the streamed gate verdict
-  // (--gate-json -) — it must stay pure JSON: route the gate's [AS-EFF-…] violation lines to stderr so
-  // a `… | jq` / `… | candor-sarif` pipe never breaks.
-  const emitViolation = (wantJson || gateJsonPath === "-") ? (l) => console.error(l) : (l) => console.log(l);
-  for (const x of gateViolations) emitViolation(`[${x.rule}] ${x.detail}`);
+  gateViolations = gateViolations.concat(evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap));
 }
+for (const x of gateViolations) emitViolation(`[${x.rule}] ${x.detail}`);
 // --gate-json ⟨0.8⟩: the structured gate verdict { spec, ok, violations:[{rule,fn,effects,detail}] }, from
 // the SAME gateViolations that set the exit code (so it can't disagree). Written whenever the flag is set —
 // ok:true,[] when no gate is configured. Must precede the exit(1) below.
@@ -2207,8 +2276,10 @@ if (gateJsonPath) {
     catch (e) { console.error(`candor-ts: could not write --gate-json ${gateJsonPath}: ${e.message}`); }
   }
 }
-if (policyPath !== null && gateViolations.length) {
+// gateViolations is non-empty only when a gate surface (policy / baseline) was active and fired.
+if (gateViolations.length) {
   console.error(`candor-ts: ${gateViolations.length} policy violation(s)`);
   process.exit(1);
 }
 if (policyPath !== null) console.error("candor-ts: policy ✓");
+if (baselinePath !== null && fs.existsSync(baselinePath)) console.error("candor-ts: baseline ✓"); // absent = inactive (noted above)