candor-ts 0.14.0 → 0.15.0

package/AGENTS.md

@@ -12,7 +12,7 @@ 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 `<version>` (spec 0.14)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.15)."*
 > 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`.
 >

package/README.md

@@ -184,7 +184,7 @@ pure-vs-Unknown ruling (PART 16) — the engines must answer identically, on eve
 | A call resolving to a *type* (function-typed field/param) → `Unknown`, never silent-pure | SPEC §4 |
 | Unmatched external calls contribute nothing (curated-classifier caveat) | SEMANTICS §8 C1 |
 | The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
-| `{ candor: { version, toolchain, spec: "0.14" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.15" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
 | Call-graph sidecar with **every** analyzed function a key | SPEC §2.2 |
 | The gate: AS-EFF-006 / 008 / 009, loud on an unreadable policy | SPEC §6.2 |
 
@@ -202,7 +202,7 @@ read the Rust source".
 
 ## Status
 
-0.14.x, speaking candor-spec 0.14: the analysis core, the gate (`--policy` / `--gate-json` /
+0.15.x, speaking candor-spec 0.15: 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` — the behavioral suite across six harnesses), **soundness-fuzzed

package/mcp.mjs

@@ -291,8 +291,12 @@ const TOOLS = {
       // ⟨spec 0.12 staged⟩ baseline callgraph → byFunction[].origin, same as the CLI (parity). The
       // loader's non-enumerable `partial` tag rides along: a corrupt baseline sidecar (edges dropped,
       // disclosed) downgrades origin to "unknown", never a fabricated "new" over a truncated graph.
+      // ⟨0.15 staged⟩ coverage disclosure — the SAME gainsCoverage the CLI verb spreads (the parity
+      // rule): optional `coverage` (current envelope's ledger) + `coverageDelta` (baseline names
+      // differ), both omitted when nothing applies — no other field of the tool result changes.
       return { baseline_version: Q.reportVersion(b) ?? "", engine_version: Q.reportVersion(p) ?? "",
-               ...Q.gains(loadReportLoud(p), loadReportLoud(b), Q.loadCallgraph(b)) };
+               ...Q.gains(loadReportLoud(p), loadReportLoud(b), Q.loadCallgraph(b)),
+               ...Q.gainsCoverage(p, b) };
     },
   },
   candor_activity: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.14.0",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.14)",
+  "version": "0.15.0",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.15)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query-core.mjs

@@ -124,6 +124,57 @@ function packagesLabel(pkgs) {
   return first.slice(0, n).join(".");
 }
 
+/** ⟨0.15 staged⟩ the report's §2 `coverage` envelope field (COVERAGE-DESIGN.md §1) — the κ ledger of
+ *  packages whose effects were INVISIBLE to the scan (absent, NOT a claim they're pure). Returns the
+ *  normalized uncovered list [{name, calls}] (multi-report siblings merged, counts summed, sorted the
+ *  producer's way: count desc, name asc), or null when absent/empty — the pre-0.15 report and the
+ *  fully-covered report look identical here, and null keeps the consumer's output field OMITTED
+ *  (never a fabricated `coverage: []` claim over a report that never carried the field). */
+export function reportCoverage(prefix) {
+  const files = fs.existsSync(`${prefix}.json`) ? [`${prefix}.json`] : siblings(prefix, isReport);
+  const merged = new Map();
+  for (const f of files) {
+    try {
+      const unc = JSON.parse(fs.readFileSync(f, "utf8"))?.coverage?.uncovered;
+      if (!Array.isArray(unc)) continue;   // absent/malformed field → contributes nothing (§2 forward-compat)
+      for (const e of unc) {
+        // Tolerate a foreign/hand-edited entry: a string `name` is required; a non-numeric `calls`
+        // counts as 0 (the entry still NAMES the blind spot — dropping it would under-disclose).
+        if (e && typeof e === "object" && typeof e.name === "string" && e.name) {
+          const n = typeof e.calls === "number" && Number.isFinite(e.calls) ? e.calls : 0;
+          merged.set(e.name, (merged.get(e.name) ?? 0) + n);
+        }
+      }
+    } catch { /* unreadable sibling — the reportVersion posture: keep looking */ }
+  }
+  if (merged.size === 0) return null;
+  return [...merged.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([name, calls]) => ({ name, calls }));
+}
+
+/** ⟨0.15 staged⟩ gains' coverage disclosure (COVERAGE-DESIGN.md §3) — the OPTIONAL blocks the gains
+ *  JSON carries, computed from the two reports' envelopes. ONE code path for the CLI verb and the MCP
+ *  `candor_gains` tool (the parity rule). Returns a spreadable object:
+ *   · `coverage: {uncovered:[{name,calls}]}` — the CURRENT report's ledger, when non-empty (a gained
+ *     effect in an uncovered dep is invisible, so "no gains" must not read as total);
+ *   · `coverageDelta: {nowUncovered:[name], noLongerUncovered:[name]}` — whenever the two ledgers
+ *     NAME different packages (a dep becoming uncovered between scans is itself a signal). The field
+ *     names are the java reference engine's exactly (cross-engine wire parity). Keyed on names, not
+ *     counts: a call-count wobble is ordinary code change, a new blind package is the alarm.
+ *  Both omitted when nothing applies — a coverage-free comparison is byte-identical to ⟨0.14⟩. */
+export function gainsCoverage(curPrefix, basePrefix) {
+  const cur = reportCoverage(curPrefix);
+  const base = reportCoverage(basePrefix);
+  const out = {};
+  if (cur) out.coverage = { uncovered: cur };
+  const curNames = new Set((cur ?? []).map((e) => e.name));
+  const baseNames = new Set((base ?? []).map((e) => e.name));
+  const nowUncovered = [...curNames].filter((n) => !baseNames.has(n)).sort();
+  const noLongerUncovered = [...baseNames].filter((n) => !curNames.has(n)).sort();
+  if (nowUncovered.length || noLongerUncovered.length) out.coverageDelta = { nowUncovered, noLongerUncovered };
+  return out;
+}
+
 // The returned array carries a non-enumerable `hardFail` flag: true iff a report file was FOUND but
 // yielded NO trustworthy functions — a parse failure OR a malformed shape (a `null`/array/wrong-typed
 // doc, a non-array `functions`, all-junk entries). The loud CLI wrapper (loadReportOrDie) needs it to

package/query.mjs

@@ -38,7 +38,7 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
          fix as coreFix, fixGate as coreFixGate, unverified as coreUnverified,
-         matches as coreMatches,
+         matches as coreMatches, gainsCoverage,
          loadReport, loadCallgraph, reportVersion, reportPackage } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
@@ -94,7 +94,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
 // package.json; SPEC_VERSION is the spec contract this build speaks. Reused, never re-littered.
 const QUERY_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(QUERY_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.14";
+const SPEC_VERSION = "0.15";
 
 // ---- the §3.3.1 canonical query grammar (⟨0.10⟩, additive over 0.9) --------------------------------
 // One shape for every verb: `<verb> <verb-args…> [--report <locator>] [--policy <file>] [--json]
@@ -571,7 +571,14 @@ switch (cmd) {
     // a MISSING sidecar loads {} and a corrupt (matched-but-unparseable) one is tagged `partial`
     // with its edges dropped-and-disclosed: either way "new" is unavailable and origin falls back
     // to "unknown" — the JSON itself discloses, never guessing "new" over a truncated graph.
-    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)) });
+    // ⟨0.15 staged⟩ coverage disclosure (COVERAGE-DESIGN.md §3): the CURRENT report's `coverage`
+    // envelope rides along (a gained effect in an uncovered dep is invisible — "no gains" must not
+    // read as total), plus `coverageDelta` when the baseline names different blind packages. Both
+    // OMITTED when nothing applies, so a coverage-free comparison is byte-identical to ⟨0.14⟩.
+    // Shared with the MCP `candor_gains` tool (gainsCoverage — the parity rule).
+    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "",
+           ...coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix)),
+           ...gainsCoverage(curPrefix, basePrefix) });
     break;
   }
   case "path": {

package/scan.mjs

@@ -41,7 +41,7 @@ const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 // literal stamped into the envelope's `spec` field, so the doc lines and the report can never drift.
 // Reused, never re-littered.
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(ENGINE_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.14";
+const SPEC_VERSION = "0.15";
 
 // --version: a print-and-exit MODE, handled before the main arg walk so it never depends on a target.
 // Fully OFFLINE — candor never phones home. Staying current is the AGENT's job: read the installed
@@ -477,9 +477,122 @@ function programHeadLiteral(node) {
 // options in the other overloads) — so those two members read arg0-or-arg1. Only STRING-LITERAL positions
 // are considered; returns null when the URL slot is not a static string literal — the safe direction.
 const NET_URL_ARG1_MEMBERS = new Set(["connect", "createConnection"]);
+// CONST-STRING PROPAGATION (java constant-inlining parity): resolve a bare identifier that references a
+// `const NAME = "literal"` string to its literal value, and ONLY then. Returns the string, or null. The
+// soundness rule is strict: resolve ONLY when EVERY value-declaration of the symbol is an immutable
+// `const` (or a `readonly` field) whose initializer is a plain string literal. A `let`/`var` (reassignable),
+// a declaration with no string-literal initializer (runtime value, function result, env read, config field,
+// concatenation, another template), or a symbol with MORE than the string-literal decls we can see → null,
+// so the call stays bare/runtime as before. NEVER guess a value we cannot read off a `const` initializer.
+function constStringValue(expr) {
+  if (!ts.isIdentifier(expr)) return null;
+  const sym = checker.getSymbolAtLocation(expr);
+  const decls = sym?.declarations ?? [];
+  if (decls.length === 0) return null;
+  let resolved = null;
+  for (const d of decls) {
+    // A `const x = "..."` variable declaration, or a `readonly x = "..."` class/property field. Both are
+    // VariableDeclaration/PropertyDeclaration nodes with an initializer; the immutability gate differs.
+    if (ts.isVariableDeclaration(d)) {
+      // the enclosing VariableDeclarationList must be `const` — a `let`/`var` can be reassigned later.
+      const list = d.parent;
+      const isConst = list && ts.isVariableDeclarationList(list)
+        && (list.flags & ts.NodeFlags.Const) !== 0;
+      if (!isConst || !d.initializer || !ts.isStringLiteral(d.initializer)) return null;
+      if (resolved != null && resolved !== d.initializer.text) return null; // conflicting decls — bail
+      resolved = d.initializer.text;
+    } else if (ts.isPropertyDeclaration(d)) {
+      const isReadonly = (ts.getCombinedModifierFlags(d) & ts.ModifierFlags.Readonly) !== 0;
+      if (!isReadonly || !d.initializer || !ts.isStringLiteral(d.initializer)) return null;
+      if (resolved != null && resolved !== d.initializer.text) return null;
+      resolved = d.initializer.text;
+    } else {
+      return null; // any other declaration shape (function, param, import alias, …) → do not resolve
+    }
+  }
+  return resolved;
+}
+// Resolve a URL ARGUMENT EXPRESSION to a statically-known URL/host string when its HOST is anchored by a
+// `const NAME = "literal"` string (java constant-inlining parity). Three shapes, all requiring the host to
+// live at the HEAD of the value:
+//   • a bare const identifier            fetch(API_BASE)             → API_BASE's value
+//   • a template whose HEAD is a const   fetch(`${API_BASE}/chat`)   → value + the literal template tail
+//   • a concat whose LEFT is a const     fetch(API_BASE + "/chat")   → value + the right literal
+// The template tail / concat right are appended ONLY when they are themselves plain literals, so the
+// returned string is a real static URL prefix `hostLiteral` can parse (`https://host/…`). A template with a
+// literal host-bearing PREFIX before the interpolation (`\`https://${h}\``) has a non-empty template HEAD, so
+// its head is NOT a const identifier → not resolved here (and the literal prefix alone never named a full
+// host). Anything else (non-const identifier, interpolation of a runtime value, nested template) → null.
+function resolveConstUrlString(expr) {
+  if (expr == null) return null;
+  // bare identifier: fetch(API_BASE)
+  const bare = constStringValue(expr);
+  if (bare != null) return bare;
+  // template literal `${HEAD_CONST}<tail literal>`: the const value must sit at the HEAD (empty template
+  // head text), and we may only append a SINGLE trailing literal span — a second `${…}` interpolation is a
+  // runtime value we will not resolve, but it only follows the host, so the host prefix is still sound.
+  if (ts.isTemplateExpression(expr)) {
+    if (expr.head.text !== "") return null;              // literal prefix before the const → not const-anchored
+    const first = expr.templateSpans[0];
+    const head = first && constStringValue(first.expression);
+    if (head == null) return null;                       // first interpolation is not a const string
+    // append the literal text between the first interpolation and the next (or end) — the URL path segment.
+    return head + (first.literal.text ?? "");
+  }
+  // string concat `CONST + "…"`: left must be a const string; append the right ONLY if it is a plain literal.
+  if (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const left = constStringValue(expr.left);
+    if (left == null) return null;
+    const right = ts.isStringLiteralLike(expr.right) ? expr.right.text : "";
+    return left + right;
+  }
+  return null;
+}
+// Does a literal URL-head string already contain a COMPLETE authority — i.e. is there a `/` AFTER the
+// `://` still WITHIN the literal text? `https://api.openai.com/v1/` → yes (host fully present, only the
+// PATH follows); `https://api.` / `https://` / `https://api.openai.com:` → no (the authority is not yet
+// terminated, so an interpolation could still be part of the host/port). Requires a `scheme://` prefix;
+// a bare relative path never qualifies.
+function literalHeadCompletesAuthority(head) {
+  const m = head.match(/^[a-z][a-z0-9+.-]*:\/\//i);
+  if (!m) return false;                          // no scheme://… → authority not started in the literal
+  return head.indexOf("/", m[0].length) >= 0;    // a `/` after the `://` terminates the authority
+}
+// LITERAL-HEAD HOST EXTRACTION (java literal-inlining parity): a template `\`https://host/${path}\`` or a
+// concat `"https://host/" + path` whose FIRST STATIC segment (the text before the first interpolation /
+// the concat's left literal) ALREADY contains a complete `scheme://authority/…` carries a statically-known
+// host — the interpolation is only in the PATH. Return that literal head (a real URL prefix `hostLiteral`
+// parses to the authority). If the head does NOT terminate the authority with a `/` (`https://${h}/x`,
+// `https://api.${x}.com/y`, `https://host:${port}/y`, `https://api.openai${x}/v1`) the interpolation could
+// be part of the host/port → return null (safe under-report: stays bare Net). Distinct from
+// resolveConstUrlString, which anchors on a CONST identifier at the head; here the head is a plain LITERAL.
+function literalHeadHostUrl(expr) {
+  if (expr == null) return null;
+  // template `\`<head>${…}…\``: the literal head is expr.head.text (empty when the interpolation leads).
+  if (ts.isTemplateExpression(expr)) {
+    const head = expr.head.text;
+    return literalHeadCompletesAuthority(head) ? head : null;
+  }
+  // concat `"<left literal>" + <anything>`: only the LEFT operand's literal text is the static head; the
+  // right is a runtime value living in the path. (A nested `"a" + "b" + x` left is a BinaryExpression, not
+  // a string literal, so it is not read here — a safe under-report, not a fabrication.)
+  if (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.PlusToken
+      && ts.isStringLiteralLike(expr.left)) {
+    const head = expr.left.text;
+    return literalHeadCompletesAuthority(head) ? head : null;
+  }
+  return null;
+}
 function urlArgLiteral(node, member) {
   const args = node.arguments ?? [];
-  const litAt = (i) => (args[i] && ts.isStringLiteralLike(args[i]) ? args[i].text : null);
+  const litAt = (i) => {
+    const a = args[i];
+    if (!a) return null;
+    if (ts.isStringLiteralLike(a)) return a.text;
+    // const-anchored host (fetch(API_BASE), `${API_BASE}/x`, API_BASE+"/x"), THEN literal-head extraction
+    // (`\`https://host/${p}\``, `"https://host/" + p`) when the literal head already completes the authority.
+    return resolveConstUrlString(a) ?? literalHeadHostUrl(a);
+  };
   if (member && NET_URL_ARG1_MEMBERS.has(member)) return litAt(0) ?? litAt(1); // (port, host) or (path)
   return litAt(0);
 }
@@ -1114,9 +1227,34 @@ function moduleUnit(sf) {
   }
   return qual;
 }
+// The synthesized static-initializer unit for a `class C { static { … } }` block (spec §2 unitKind
+// "initializer"). A static block runs at class-DEFINITION time, not instance construction — but its
+// body's effects otherwise walked up in `enclosing` to the ClassDeclaration, which maps to the
+// `C.constructor` unit, so a static-init effect was MISLABELED as the instance ctor (and carried no
+// unitKind). Mint it as its own unit, lazily, mirroring `moduleUnit`. (An anonymous class expression's
+// static block keys under `<anonymous>`; there is at most one static-init unit per class name.)
+function staticBlockUnit(node) {
+  const cls = node.parent;
+  const sf = node.getSourceFile();
+  const mod = moduleOf(sf);
+  const cname = (ts.isClassDeclaration(cls) || ts.isClassExpression(cls)) && cls.name ? cls.name.text : "<anonymous>";
+  const qual = `${mod}.${cname}.<static-init>`;
+  let rec = fns.get(qual);
+  if (!rec) {
+    rec = { local: "<static-init>", direct: new Set(), edges: new Set(), hosts: new Set(), tables: new Set(),
+            cmds: new Set(), paths: new Set(), blind: new Set(), incomplete: new Set(), why: new Set(),
+            entry: false, unitKind: "initializer",
+            loc: `${path.relative(rootDir, sf.fileName)}:${sf.getLineAndCharacterOfPosition(node.getStart()).line + 1}:1` };
+    fns.set(qual, rec);
+  }
+  return qual;
+}
 // nearest enclosing analyzed function (closures attribute to it — SEMANTICS §2)
 function enclosing(node) {
   for (let p = node; p; p = p.parent) {
+    // A `static { … }` block is its own initializer unit (class-definition time), NOT the instance ctor
+    // the ClassDeclaration maps to — intercept before the nodeName lookup would fold it into .constructor.
+    if (ts.isClassStaticBlockDeclaration(p)) return staticBlockUnit(p);
     // A call/effect lexically inside a DECORATOR (`@factory(arg)`) runs at class-DEFINITION time, NOT in
     // the decorated declaration's body. The parent chain of a decorator's expression is
     // CallExpression → Decorator → MethodDeclaration/ClassDeclaration/Parameter, so `enclosing` otherwise
@@ -1339,6 +1477,83 @@ const HOF_INVOKERS = new Set([
   "then", "catch", "finally", "nextTick",
 ]);
 
+// ---- process.env recognition: the direct dot access (`process.env.KEY`) is the JVM System.getenv twin,
+// but the same environment READ is spelled several other ways that all read silent-pure without help:
+// bracket access (`process.env[k]`), a local const-alias (`const env = process.env; env.KEY`),
+// destructuring (`const {KEY} = process.env`), and the `in` operator (`"KEY" in process.env`). Each of
+// these on process.env (or a confirmed direct alias of it) is Env. SOUNDNESS: only process.env and a
+// DIRECT `x = process.env` / `const {env} = process` binding trigger — a bracket/alias/destructure/`in`
+// on any OTHER object stays pure (no fabrication), and a reassigned alias local is cleared.
+//
+// `process` here must be Node's process object, NOT a project-local `const process = {…}` shadow
+// (mirrors the process.hrtime/send guard). It qualifies when it is the ambient GLOBAL (no project
+// declaration) OR a default-import of the `node:process` builtin (`import process from 'node:process'`,
+// as chalk's supports-color does) — the two are the same object.
+const declImportsNodeProcess = (decl) => {
+  // ImportClause default binding or a namespace/named import from 'node:process' | 'process'.
+  let spec = null;
+  if (ts.isImportClause(decl) && decl.parent && ts.isImportDeclaration(decl.parent)) spec = decl.parent.moduleSpecifier;
+  else if (ts.isImportSpecifier(decl)) spec = decl.parent?.parent?.parent?.moduleSpecifier;
+  else if (ts.isNamespaceImport(decl)) spec = decl.parent?.parent?.moduleSpecifier;
+  const text = spec && ts.isStringLiteral(spec) ? spec.text : null;
+  return text === "node:process" || text === "process";
+};
+const identIsGlobalProcess = (id) => {
+  if (!ts.isIdentifier(id) || id.text !== "process") return false;
+  const decls = checker.getSymbolAtLocation(id)?.declarations ?? [];
+  if (decls.some(declImportsNodeProcess)) return true;                       // `import process from 'node:process'`
+  return !decls.some((d) => projectFiles.has(path.resolve(d.getSourceFile().fileName))); // else the ambient global
+};
+// `process.env` as an expression (PropertyAccess `process.env` where `process` is the global).
+const isProcessEnvExpr = (expr) =>
+  expr && ts.isPropertyAccessExpression(expr) && expr.name.text === "env" && identIsGlobalProcess(expr.expression);
+
+// The set of local-binding SYMBOLS that alias process.env — collected below, one pre-pass over the
+// sources. A symbol lands here iff its ONLY initializer/assignment is `= process.env` (a reassignment
+// to anything else removes it → the alias is cleared, per the spec's reassignment rule).
+const envAliasSymbols = new Set();
+{
+  const aliasCandidates = new Set();   // symbol -> declared `= process.env`
+  const disqualified = new Set();      // symbol assigned to something that is NOT process.env
+  const noteBinding = (symbol, init) => {
+    if (!symbol) return;
+    if (init && isProcessEnvExpr(init)) aliasCandidates.add(symbol);
+    else disqualified.add(symbol);     // bound/assigned to a non-process.env value → not (or no longer) an alias
+  };
+  const collectAliases = (node) => {
+    // `const env = process.env` / `let`/`var` — a name-identifier binding with an initializer.
+    if (ts.isVariableDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
+      noteBinding(checker.getSymbolAtLocation(node.name), node.initializer ?? null);
+    }
+    // `const { env } = process` — destructuring `env` off the global `process` makes `env` an alias too.
+    else if (ts.isVariableDeclaration(node) && node.name && ts.isObjectBindingPattern(node.name)
+             && node.initializer && ts.isIdentifier(node.initializer) && identIsGlobalProcess(node.initializer)) {
+      for (const el of node.name.elements) {
+        // the property picked off `process` must be `env` (`{env}` or `{env: local}`); the bound name is the alias.
+        const propName = el.propertyName ? (ts.isIdentifier(el.propertyName) ? el.propertyName.text : null)
+                                         : (ts.isIdentifier(el.name) ? el.name.text : null);
+        if (propName === "env" && ts.isIdentifier(el.name)) aliasCandidates.add(checker.getSymbolAtLocation(el.name));
+      }
+    }
+    // `env = <expr>` reassignment — a `let`/`var` alias reassigned to a non-process.env value is cleared.
+    else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken
+             && ts.isIdentifier(node.left)) {
+      noteBinding(checker.getSymbolAtLocation(node.left), node.right);
+    }
+    ts.forEachChild(node, collectAliases);
+  };
+  for (const sf of sources) collectAliases(sf);
+  for (const s of aliasCandidates) if (s && !disqualified.has(s)) envAliasSymbols.add(s);
+}
+// True when `id` is an identifier resolving to a confirmed process.env alias local.
+const identIsEnvAlias = (id) => {
+  if (!id || !ts.isIdentifier(id)) return false;
+  const sym = checker.getSymbolAtLocation(id);
+  return !!sym && envAliasSymbols.has(sym);
+};
+// The receiver expression READS process.env — it is either `process.env` itself or a confirmed alias.
+const readsProcessEnv = (expr) => isProcessEnvExpr(expr) || identIsEnvAlias(expr);
+
 // ---- pass 2: per call site, the (CLASSIFY)/(EDGE)/(UNKNOWN) resolution of SEMANTICS §4 ------------
 function visitCalls(node) {
   if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
@@ -1886,10 +2101,25 @@ function visitCalls(node) {
       }
     }
   }
-  // process.env.X — a property READ, not a call (the JVM's System.getenv twin) → Env
-  if (ts.isPropertyAccessExpression(node) && node.expression.getText() === "process.env") {
-    const owner = enclosing(node);
-    if (owner) fns.get(owner).direct.add("Env");
+  // Reading process.env — the JVM System.getenv twin → Env. All the common idioms count, not just the
+  // direct `process.env.KEY` dot access (see the process.env-recognition note above): dot/bracket access
+  // on process.env or a confirmed alias, destructuring a key off it, and the `in` membership test.
+  {
+    const markEnv = () => { const owner = enclosing(node); if (owner) fns.get(owner).direct.add("Env"); };
+    // `process.env.KEY` / `env.KEY` (dot) and `process.env["KEY"]` / `env[k]` (bracket, literal OR dynamic key).
+    if ((ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) && readsProcessEnv(node.expression)) {
+      markEnv();
+    }
+    // `const {KEY} = process.env` / `const {KEY} = env` — the object-binding pattern's initializer reads env.
+    else if (ts.isVariableDeclaration(node) && node.name && ts.isObjectBindingPattern(node.name)
+             && node.initializer && readsProcessEnv(node.initializer)) {
+      markEnv();
+    }
+    // `"KEY" in process.env` / `"KEY" in env` — the `in` operator's right operand reads env.
+    else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.InKeyword
+             && readsProcessEnv(node.right)) {
+      markEnv();
+    }
   }
   // Runtime GLOBALS reached as CALLS with no import for the κ resolver to classify: `process.hrtime()`/
   // `.hrtime.bigint()` is a monotonic clock read (Clock); `process.send(...)` is the child↔parent IPC
@@ -2272,6 +2502,19 @@ for (const [name, rec] of fns) {
 // `functions` is empty (an all-pure package's report is its purity claim, SPEC §2 rule 3).
 const envelope = { candor: { version: ENGINE_VERSION, toolchain: `node-${process.versions.node}`, spec: SPEC_VERSION },
                    package: pkgName, functions };
+// ⟨0.15 staged⟩ the κ-coverage ledger as DATA (COVERAGE-DESIGN.md §1): ONE sorted form (count desc,
+// name asc — exactly the stderr line's order) feeds the envelope field, the stderr receipt below, and
+// the --gate-json advisory, so the three can never tell different stories.
+const uncoveredLedger = [...unlistedSeen.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+// ⟨0.15 staged⟩ `coverage` envelope field — the stderr disclosure travels WITH the artifact, so a
+// report-consuming verb can no longer read a partially-covered report as total. Same names/counts as
+// the stderr line. OMITTED entirely when nothing is uncovered (the `extensions`-field precedent): a
+// fully-covered report stays byte-identical to a ⟨0.14⟩ one, so the rung is wire-compatible. The
+// per-function posture is UNCHANGED: a resolvable-but-uncovered call keeps `invisible`, an
+// unresolvable one keeps the stronger `Unknown` (COVERAGE-DESIGN.md §2 blesses both).
+if (uncoveredLedger.length) {
+  envelope.coverage = { uncovered: uncoveredLedger.map(([name, calls]) => ({ name, calls })) };
+}
 const cg = {};
 for (const [name, rec] of fns) cg[name] = [...rec.edges].sort();
 // Write ATOMICALLY (temp + rename): a concurrent reader — the MCP server or another `query` while
@@ -2325,7 +2568,7 @@ if (!wantJson) {
   }
 }
 if (unlistedSeen.size > 0) {
-  const top = [...unlistedSeen.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const top = uncoveredLedger; // ⟨0.15 staged⟩ the shared sorted ledger — same names/counts as envelope `coverage`
   const shown = top.slice(0, 8).map(([p, n]) => `${p} (${n} call${n === 1 ? "" : "s"})`).join(", ");
   const more = top.length > 8 ? ` + ${top.length - 8} more` : "";
   console.error(`candor-ts: candor's classifier doesn't cover ${top.length} package${top.length === 1 ? "" : "s"} this code calls into — `
@@ -2456,7 +2699,17 @@ for (const x of gateViolations) emitViolation(`[${x.rule}] ${x.detail}`);
 // 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.
 if (gateJsonPath) {
-  const verdict = JSON.stringify({ spec: SPEC_VERSION, ok: gateViolations.length === 0, violations: gateViolations }, null, 1);
+  const verdictObj = { spec: SPEC_VERSION, ok: gateViolations.length === 0, violations: gateViolations };
+  // ⟨0.15 staged⟩ coverage ADVISORY (COVERAGE-DESIGN.md §3): when the κ ledger is non-empty, the
+  // verdict discloses what the gate could NOT see — VERDICT-PRESERVING (the ⟨0.9⟩ provable-purity
+  // auto-disclosure precedent exactly): ok/violations/exit are computed above and untouched here. A
+  // gate does not fail on uncovered deps (nearly every real scan has some); the policy author sees
+  // the note and decides — `deny Unknown` remains the opt-in strict posture. OMITTED when fully
+  // covered, so a pre-0.15 consumer's verdict is byte-identical.
+  if (uncoveredLedger.length) {
+    verdictObj.coverage = { uncovered: uncoveredLedger.length, packages: uncoveredLedger.map(([p]) => p) };
+  }
+  const verdict = JSON.stringify(verdictObj, null, 1);
   if (gateJsonPath === "-") console.log(verdict);
   else {
     // The verdict is a SURFACING side-output: an unwritable path must be one stderr line, never a raw