candor-ts 0.8.6 → 0.8.8

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
@@ -117,16 +130,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 +161,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/Cases.ts

@@ -0,0 +1,77 @@
+// The candor-spec conformance cases in TypeScript — paired by bare function name with the Rust and
+// Java fixtures; the expected effect sets are conformance/expected.json (the SAME oracle).
+import * as fsm from "node:fs";
+import * as netm from "node:net";
+import * as cp from "node:child_process";
+import * as cryptom from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import * as winstonm from "winston";
+
+// --- one function per std-only effect ---
+export function fs_read(): void { try { fsm.readFileSync("/tmp/x"); } catch {} }
+export function net_connect(): void { try { netm.connect(1, "h"); } catch {} }
+export function exec_spawn(): void { try { cp.spawn("x"); } catch {} }
+// Exec-cliff refinement (spec §4 ⟨0.5⟩): a known literal head adds its effect; all engines must agree.
+export function exec_curl(): void { try { cp.spawn("curl"); } catch {} }
+// Exec-refinement reads the HEAD (argv[0]) only: a dynamic program with a literal ARGUMENT keeps the
+// bare cliff — "curl" in the args array must NOT fabricate Net (spec §4 ⟨0.5⟩: the head is argv[0]).
+export function exec_dyn_head(tool: string): void { try { cp.spawn(tool, ["curl"]); } catch {} }
+export function env_read(): void { void process.env.X; }
+export function clock_now(): void { void Date.now(); }
+// Rand: node:crypto's CSPRNG. candor-ts is syntactic (AST), so the builtin need not resolve at scan time.
+export function rand_gen(): void { void cryptom.randomBytes(16); }
+// Db: node:sqlite's DatabaseSync.exec is the store round-trip (named import — candor-ts tracks the symbol).
+export function db_query(): void { void new DatabaseSync(":memory:").exec("SELECT 1"); }
+export function log_msg(): void { winstonm.info("m"); }
+
+// --- purity (negative) ---
+export function pure_fn(): number { return 1 + 2; }
+
+// --- the Unknown trust contract: a function-valued field the engine cannot see through ---
+class Holder { cb: () => void = () => {}; }
+const h = new Holder();
+export function unknown_dyn(): void { const cb = h.cb; cb(); }
+
+// --- multi-effect union in one body ---
+export function combined(): void { try { fsm.readFileSync("/tmp/x"); netm.connect(1, "h"); } catch {} }
+
+// --- transitive propagation across a call ---
+export function transitive_leaf(): void { try { fsm.readFileSync("/tmp/x"); } catch {} }
+export function transitive_caller(): void { transitive_leaf(); }
+
+// --- an effect inside a closure attributes to the enclosing function (SEMANTICS §2) ---
+export function closure_effect(): void { const f = () => { try { fsm.readFileSync("/tmp/x"); } catch {} }; f(); }
+
+// --- Unknown propagates like an effect ---
+export function unknown_propagates(): void { unknown_dyn(); }
+
+// --- mixed: a concrete effect AND an Unknown in one transitive set ---
+export function mixed_unknown(): void { try { fsm.readFileSync("/tmp/x"); } catch {} unknown_dyn(); }
+
+// --- a 3-hop chain a -> b -> c(Net) ---
+export function hop_c(): void { try { netm.connect(1, "h"); } catch {} }
+export function hop_b(): void { hop_c(); }
+export function hop_a(): void { hop_b(); }
+
+// --- a caller unions the effects of two distinct callees ---
+export function union_b(): void { try { fsm.readFileSync("/tmp/x"); } catch {} }
+export function union_c(): void { try { netm.connect(1, "h"); } catch {} }
+export function union_a(): void { union_b(); union_c(); }
+
+// --- recursion: the fixpoint must terminate AND keep the effect ---
+export function recurse(n: number): void { if (n > 0) { void process.env.X; recurse(n - 1); } }
+
+// --- an effect in one branch only is still inferred (over-approximation) ---
+export function conditional(b: boolean): void { if (b) { try { cp.spawn("x"); } catch {} } }
+
+// --- transitive purity: a -> b -> c, all pure, stays pure (negative) ---
+export function pure_c(): number { return 3; }
+export function pure_b(): number { return pure_c(); }
+export function pure_a(): number { return pure_b(); }
+
+// --- a method call on a concrete LOCAL-type receiver propagates the method's effect ---
+export class Svc { act(): void { try { fsm.readFileSync("/tmp/x"); } catch {} } }
+export function method_call(s: Svc): void { s.act(); }
+
+// --- scheduler attribution: an effect inside a scheduled task attributes to the SCHEDULER ---
+export function sched(): void { setTimeout(() => { try { fsm.readFileSync("/tmp/x"); } catch {} }, 0); }

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
@@ -132,16 +151,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 +196,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.8.6",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
+  "version": "0.8.8",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",
@@ -40,6 +40,7 @@
     "node": ">=20"
   },
   "files": [
+    "Cases.ts",
     "scan.mjs",
     "query.mjs",
     "policy.mjs",

package/policy.mjs

@@ -120,7 +120,13 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
   for (const f of functions) {
     for (const r of pol.deny) {
       if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
-      const hits = r.effects.length === 0 ? f.inferred : f.inferred.filter((e) => r.effects.includes(e));
+      // `pure` (empty forbidden set) forbids every EFFECT — not `Unknown`, which is the §4 trust
+      // marker, not an effect (AS-EFF-003's concern; `deny Unknown <scope>` is the explicit knob).
+      // The reference engine (candor-java) and the rust deep engine exclude it identically; candor-ts
+      // wrongly counted an Unknown-only fn as a `pure` violation until 2026-07-09.
+      const hits = r.effects.length === 0
+        ? f.inferred.filter((e) => e !== "Unknown")
+        : f.inferred.filter((e) => r.effects.includes(e));
       if (hits.length) push("AS-EFF-006", f.fn, hits, `\`${f.fn}\` performs { ${hits.join(", ")} }, forbidden by policy: \`${r.raw}\``);
     }
     for (const r of pol.allow) {

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 = {
@@ -498,6 +509,27 @@ function moduleOf(sf) {
   const rel = path.relative(rootDir, path.resolve(sf.fileName)).replace(/\.[mc]?[tj]sx?$/, "");
   return rel.split(path.sep).join(".");
 }
+// Enclosing `namespace`/`module` blocks are NAME SEGMENTS (the family ruling: §6.2 scope segments
+// split on the same boundaries as the §3.1 query name ladder, and a namespace is a segment — rust
+// modules and swift enum-namespaces already qualify this way). A unit declared in
+// `export namespace app { … }` is `mod.app.fn`, so a layer policy authored against namespace layers
+// (`forbid app -> repo`, `deny Db app`) bites in TS instead of being silently inert. Returns the
+// dotted prefix ("app." / "a.b.") or "". Dotted (`namespace a.b`) and nested forms both contribute
+// each identifier segment; ambient string-named modules (`declare module "x"`) and `declare global`
+// augmentations contribute nothing (not lexical layers of THIS module).
+function namespacePrefixOf(node) {
+  const segs = [];
+  for (let p = node.parent; p && !ts.isSourceFile(p); p = p.parent) {
+    if (!ts.isModuleBlock(p)) continue;
+    // `namespace a.b { … }` nests ModuleDeclarations (a -> b -> block); walk the chain so every
+    // dotted segment lands, innermost-first up.
+    for (let d = p.parent; d && ts.isModuleDeclaration(d); d = ts.isModuleDeclaration(d.parent) ? d.parent : null) {
+      if (d.name && ts.isIdentifier(d.name) && !(d.flags & ts.NodeFlags.GlobalAugmentation))
+        segs.unshift(d.name.text);
+    }
+  }
+  return segs.length ? `${segs.join(".")}.` : "";
+}
 // Is `node` (a function-expression / method-declaration / arrow) the `get` or `set` member of an
 // accessor DESCRIPTOR object passed to `Object.defineProperty(target, key, desc)` /
 // `Object.defineProperties(target, { key: desc, … })` / `Object.create(proto, { key: desc, … })`?
@@ -698,7 +730,7 @@ for (const sf of sources) {
           }
         }
       }
-      const ctorQual = `${mod}.${node.name.text}.constructor`;
+      const ctorQual = `${mod}.${namespacePrefixOf(node)}${node.name.text}.constructor`;
       if (!fns.has(ctorQual)) {
         const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
         fns.set(ctorQual, { local: `${node.name.text}.constructor`, direct: new Set(), edges: new Set(),
@@ -719,7 +751,11 @@ for (const sf of sources) {
       // shared entry — FABRICATING them onto a pure caller. `nodeName` is keyed by NODE identity, so a
       // per-node-unique key keeps resolution exact; only TOP-LEVEL units need the stable bare name a
       // consumer's hash-join targets (a function-scoped local is never an export, so nothing joins to it).
-      const qual = isFunctionScoped(node) ? `${mod}.${n}#${line + 1}:${character + 1}` : `${mod}.${n}`;
+      // Namespace segments go in the QUAL only; `local` (and so the §2 hash `pkg#local`) stays the
+      // bare name — a consumer's cross-package join resolves the callee's own name, never the
+      // producer's namespace nesting, so widening the hash would break report chaining.
+      const nsp = namespacePrefixOf(node);
+      const qual = isFunctionScoped(node) ? `${mod}.${nsp}${n}#${line + 1}:${character + 1}` : `${mod}.${nsp}${n}`;
       fns.set(qual, { local: n, 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, isCjsExport,
                       loc: `${path.relative(rootDir, sf.fileName)}:${line + 1}:${character + 1}` });
@@ -988,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;
@@ -1195,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",
@@ -1277,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.)
@@ -1486,7 +1522,7 @@ function visitCalls(node) {
                 // dispatch-frontier (callers --include-unknown) can resolve overrides against the
                 // hierarchy sidecar. Bare `decl.parent.name` would not match a reacher's declaringType.
                 const tn = decl.parent?.name
-                  ? `${moduleOf(decl.parent.getSourceFile())}.${decl.parent.name.getText()}`
+                  ? `${moduleOf(decl.parent.getSourceFile())}.${namespacePrefixOf(decl.parent)}${decl.parent.name.getText()}`
                   : "type";
                 const mn = decl.name?.getText?.() ?? "member";
                 rec.why.add(`dispatch:${tn}.${mn}`); // resolution landed on a type, not a body — canonical `dispatch:OWNER.member` (frontier-relevant)
@@ -1592,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;
@@ -2112,10 +2148,10 @@ for (const sf of sources) {
           let sym = checker.getSymbolAtLocation(t.expression);
           if (sym && sym.flags & ts.SymbolFlags.Alias) { try { sym = checker.getAliasedSymbol(sym); } catch { /* keep */ } }
           const d = (sym?.declarations ?? []).find((x) => ts.isClassDeclaration(x) || ts.isInterfaceDeclaration(x));
-          supers.push(d && d.name ? `${moduleOf(d.getSourceFile())}.${d.name.getText()}` : t.expression.getText());
+          supers.push(d && d.name ? `${moduleOf(d.getSourceFile())}.${namespacePrefixOf(d)}${d.name.getText()}` : t.expression.getText());
         }
       }
-      if (supers.length) hierarchy[`${mod}.${node.name.getText()}`] = supers;
+      if (supers.length) hierarchy[`${mod}.${namespacePrefixOf(node)}${node.name.getText()}`] = supers;
     }
     ts.forEachChild(node, walk);
   })(sf);
@@ -2143,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 {
@@ -2162,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.
@@ -2182,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)

package/watch.mjs

@@ -121,6 +121,14 @@ async function main() {
   // NO .unref() — the interval is the ONLY thing keeping the process alive; unref'ing it made Node exit
   // ~0.6s after the startup scan, so the watcher did ONE scan and died while printing "Watching…" (the
   // whole feature was silently broken, and test-watch.mjs only tests the helpers, never the live loop).
+
+  // GRACEFUL stop: the documented quit is Ctrl-C, but the default SIGINT/SIGTERM handler TERMINATES —
+  // exit hooks never run, the stop reads as a signal death (no exit code) to a supervisor, and a child
+  // instrumented with NODE_V8_COVERAGE discards its coverage (the TESTING.md §6 flush rule — this made
+  // the live loop measure 0% while actually exercised). Handle both: announce, exit 0.
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => { console.error(`candor-ts-watch: ${sig} — stopping`); process.exit(0); });
+  }
 }
 
 if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) main();