candor-ts 0.39.3 → 0.40.0

package/AGENTS.md

@@ -23,7 +23,7 @@ the TypeScript-specific production + query surface.
 > **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.39)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.40)."*
 > 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`.
 >
@@ -62,9 +62,12 @@ set the exit code. A checked-in `.candor/config` (spec §3.4; `policy <file>` /
 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
+config `baseline` key) and the scan compares per function — a function that gained an effect versus
+the baseline fails the run (exit 1, `[AS-EFF-005]` lines, records join `--gate-json` with `origin`);
+⟨0.40⟩ a function ABSENT from the baseline is compared against nothing (a new effectful function fails,
+`origin:"new"`; a new pure one passes; a new `Unknown`-only one is named in a note) — keys are
+`Module.fn`, so a renamed file reads as absent: run `candor diff <this run's report> <baseline>` before
+re-recording. 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

package/README.md

@@ -50,9 +50,12 @@ scan target; relative values resolve against the config's repo, so CI is "point
 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
+point `CANDOR_BASELINE` (or the config's `baseline` key) at a saved report, and any
 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
+verdict, each carrying `origin` (`existing` / `new` / `unknown`). ⟨0.40⟩ A function ABSENT from the
+baseline is compared against nothing, so a new effectful function fails too; a new pure one passes,
+and a new `Unknown`-only one is named in a note. `Module.fn` keys mean a renamed file reads as absent:
+review with `candor diff <this run's report> <baseline>` before re-recording. 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
@@ -202,7 +205,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.39" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.40" }, 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 |
 
@@ -220,7 +223,7 @@ read the Rust source".
 
 ## Status
 
-Speaking candor-spec 0.39 (the package version is in `package.json`): the analysis core, the gate (`--policy` / `--gate-json` /
+Speaking candor-spec 0.40 (the package version is in `package.json`): the analysis core, the gate (`--policy` / `--gate-json` /
 `.candor/config`), the full §3.1 query surface (including `containment`, `blindspots`, the
 `--include-unknown` dispatch frontier, and ⟨0.24⟩ `gate --report` — the gate applied to an EXISTING
 report, byte-equivalent to `scan --policy`'s verdict), the MCP server, the LSP server, and the watch loop are

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "candor-ts",
-  "version": "0.39.3",
+  "version": "0.40.0",
   "mcpName": "io.github.tombaldwin/candor",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.39)",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.40)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query.mjs

@@ -730,7 +730,7 @@ function renderPathHuman(fns, cg, fnQ, eff, hedge = false) {
 // 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.39";
+const SPEC_VERSION = "0.40";
 
 // ---- 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]

package/scan-core.mjs

@@ -259,12 +259,64 @@ export const RESERVED_SIDECAR_SEGMENTS =
 // into a use-verb denylist beside the other two; that is a wider change with its own
 // over-charge bill to price, so it is filed rather than smuggled in here.
 
+//
+// SOUNDNESS R781 (the destination half) — THE URL-FIRST CLIENT VERBS OF THE WHOLE-MODULE Net PACKAGES WERE
+// MISSING. κ charges every member of `undici`/`got`/`axios`/… `Net`, so `undici.stream(u, …)`,
+// `undici.pipeline(u, …)`, `undici.upgrade(u)` carried the effect while contributing no host, and beside
+// `undici.request("https://ok.example/a")` the gate `allow Net in <fn> ok.example` exited 0 — EXECUTED,
+// a local server logged each request to the caller's URL. `stream` and `pipeline` were ALREADY named in
+// `NET_REQUEST_NAMED` below as undici's URL-taking callables: two tables answering one question, and only
+// one was consulted for masking. That set is now held to be a SUBSET of this one (test.mjs), so the next
+// request callable added there cannot be missing here. `axios`'s `postForm`/`putForm`/`patchForm` take the
+// URL first exactly like `post`/`put`/`patch` and are written in with them (R346: the family, not the
+// spelling in hand). FAILURE DIRECTION of these additions: a whole-module Net package whose `stream` takes
+// no destination is now marked incomplete — an over-charge, fail-closed. The pinned ts roster has ZERO
+// unmasked Net calls under any of these names (MASKPROBE over all 28 entries), so the price there is 0.
+//
+// NOT HERE, DELIBERATELY: `listen`/`bind`. This set answers "does this call name the DESTINATION it reaches?",
+// and a listen/bind address names the process's OWN address (SPEC §2 ⟨0.40⟩ "A BIND OR LISTEN ADDRESS IS
+// WHERE THE PROCESS LISTENS"). Putting `listen` here would be wrong in the silent direction: a call in this
+// set marks `incomplete` only when NO host was captured, so `server.listen("10.0.0.5")` (a pipe path that
+// `hostLiteral` reads as a host) would publish the local address AND certify it. The accept side is its own
+// question with its own set, NET_ACCEPTING below.
 export const NET_ESTABLISHING = new Set(["request", "get", "post", "put", "patch", "delete", "head",
   "options", "connect", "createConnection", "fetch",
+  "stream", "pipeline", "upgrade", "postForm", "putForm", "patchForm",
   "lookup", "lookupService", "reverse", "resolve", "resolve4", "resolve6", "resolveAny",
   "resolveCname", "resolveCaa", "resolveMx", "resolveNaptr", "resolveNs", "resolvePtr",
   "resolveSoa", "resolveSrv", "resolveTlsa", "resolveTxt"]);
 
+// SOUNDNESS R817 / SPEC §2 ⟨0.40⟩ — THE CALLS THAT ACCEPT. "A UNIT THAT ACCEPTS A CONNECTION TALKS TO PEERS NO
+// LITERAL CAN NAME, SO ITS `Net` SURFACE IS INCOMPLETE": node's server `listen` is the call that hands every
+// arriving connection to the server's handler, so it fixes the peer exactly as `connect` does for a client —
+// except that whoever connects chooses it. Read by scan.mjs's `netAccepting`, which marks `incomplete`
+// UNCONDITIONALLY (no literal makes an accept determined) and suppresses any capture from the call's
+// arguments (its address is local — the R809 fabrication). MEASURED before the fix (SOUNDNESS R781's listen
+// half, PART 96 c_accept): `netm.connect(80, "ok.example")` beside `netm.createServer(h).listen(8080)` read
+// `hosts: ["ok.example"]`, complete, and `allow Net ok.example` exited 0 over a server writing to anyone.
+//
+// MEMBER-KEYED, MODULE-FREE ON PURPOSE, and the module is the derived half. `listen` is read off the RESOLVED
+// declaration, so every server type node ships reaches it through `net.Server.listen` — `http`/`https`/
+// `http2`(`createSecureServer`)/`tls` servers, `new net.Server(h)`, and a project `class S extends
+// net.Server` — without being enumerated; and κ already decides WHICH modules' `listen` is a network call (the
+// net cluster; `socket.io`'s whole-module rule). A `listen` κ does not classify `Net` never reaches this set,
+// so it cannot over-charge a JSON-RPC `connection.listen()`. Two module-specific accepts sit in scan.mjs beside
+// the reader, because their member name is too common to key on alone: `inspector.open` (starts the debugger's
+// WebSocket server) and `ws`'s `WebSocketServer` construction.
+//
+// NOT AN ACCEPT: `bind`. A datagram socket's `bind` receives; its replies go out through `send`, which carries
+// its own locator (SPEC: "a datagram receive is not an accept"), and "A bind marks nothing". `createServer` is
+// not one either: it constructs a server and registers a handler, and nothing arrives until a `listen` — which
+// is marked in whichever unit calls it, and `incomplete` reaches that unit's callers over the edge like any
+// other. FAILURE DIRECTION: forgetting an accept spelling here UNDER-reports (an allowlist, R781's warning);
+// the spellings this does not see are listed at the reader.
+export const NET_ACCEPTING = new Set(["listen"]);
+
+// The NAMED imports `scan.mjs`'s `importedFromNetPkg` treats as a package's REQUEST CALLABLE (`import {
+// fetch, request, stream, pipeline } from "undici"`). Every one takes its URL first, so every one must also
+// be host-ESTABLISHING above — R781's two-tables shape; test.mjs asserts the subset relation.
+export const NET_REQUEST_NAMED = new Set(["fetch", "request", "stream", "pipeline"]);
+
 // Fs/Exec USE-verbs whose LOCATOR was fixed earlier, not an arg of THIS call — so a missing literal
 // here is the legitimate split-construct/use shape, never the masking signal (the establishing-
 // allowlist discipline, generalized from Net to all 4 effects; sweep [11]). Fs: the fd/FileHandle