candor-ts 0.8.15 → 0.9.2

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.8)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.9)."*
 > 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`.
 >
@@ -98,6 +98,7 @@ Q containment $P [baseline-prefix]  # §6.1 boundary-effect dispersion; with a b
 Q blindspots $P                     # the Unknown SOURCES (fns with unknownWhy), ranked by Unknown blast radius
 Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it would violate)
 Q fix      $P <fn> <Effect> <policy>  # the boundary FIX: where the effect belongs + the hoist refactor
+Q unverified $P <policy> [--strict]  # pure/deny layers that PASS but are Unknown (not PROVABLY clean)
 Q fix-gate $P <policy>              # a fix for EVERY crossing — the loop's block-message remedy
 Q diff     $P <baseline-prefix> 1   # per-function effect delta (exit 1 on a gained effect)
 Q gains    $P <baseline-prefix>     # supply-chain alarm: {gained, byFunction} — effects a surface grew

package/README.md

@@ -183,7 +183,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-κ caveat) | SEMANTICS §8 C1 |
 | The literal surfaces `hosts`/`cmds`/`paths`/`tables`, literal-read only | SPEC §2 |
-| `{ candor: { version, toolchain, spec: "0.8" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.9" }, 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 |
 
@@ -201,7 +201,7 @@ read the Rust source".
 
 ## Status
 
-0.8.x, speaking candor-spec 0.8: the analysis core, the gate (`--policy` / `--gate-json` /
+0.9.x, speaking candor-spec 0.9: 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

@@ -215,6 +215,26 @@ const TOOLS = {
       return { ok: v.length === 0, violations: v };
     },
   },
+  candor_unverified: {
+    description: "PROVABLE-PURITY check (INSTANT): a `pure`/`deny <E>` policy layer PASSES a function that has "
+                 + "no such effect — but if that function is Unknown (candor couldn't resolve one of its calls), "
+                 + "the pass is UNVERIFIED: the Unknown could hide the very effect the rule forbids. The classic "
+                 + "case is a fn/closure-injected 'port' — the domain reads as Unknown, so `deny Net domain`/`pure "
+                 + "domain` clear it though it may reach Net at runtime. Returns each such function + the `deny <E> "
+                 + "Unknown <scope>` upgrade that makes the layer PROVABLY clean. Uses `policy` if given, else the "
+                 + "repo's checked-in .candor/config policy.",
+    schema: { type: "object", properties: { policy: { type: "string", description: "path to a §6.2 policy file (optional; defaults to the repo's .candor/config `policy`)" }, ...reportArg }, required: [] },
+    run: (a, p) => {
+      let text;
+      if (a.policy) text = confinedPolicyRead(a.policy, p);
+      else {
+        const cfg = configPolicy(p);
+        if (!cfg) throw new Error("no policy: pass `policy`, or check one into the repo's .candor/config (spec §3.4)");
+        text = confinedPolicyRead(cfg.policyPath, p, cfg.repoRoot);
+      }
+      return Q.unverified(Q.loadReport(p), parsePolicy(text), scopeMatches);
+    },
+  },
   candor_containment: {
     description: "Per boundary effect (Db/Net/Exec/Fs/Ipc/Clipboard): how contained it is in one architectural layer — the dispersion diagnostic (spec §6.1). Not a score; per-effect facts.",
     schema: { type: "object", properties: { ...reportArg } },

package/package.json

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

package/query-core.mjs

@@ -620,3 +620,48 @@ export function fixGate(cg, fns, policyParsed, scopeMatches) {
   const remedies = [...plans.keys()].sort().map((k) => plans.get(k));
   return { ok: remedies.length === 0, remedies };
 }
+
+// unverified: the PROVABLE-PURITY disclosure (eval/fixloop/DISPATCH-NOTE.md, mirrors candor-query). A
+// `pure`/`deny E` layer PASSES a function that carries none of its forbidden effects — but if that function is
+// `Unknown` (an unresolvable call), the pass is UNVERIFIED: the Unknown could hide the very effect the rule
+// forbids (the fn/closure-port hole). Returns each such function + the `deny E Unknown <scope>` upgrade.
+/** Reconstruct a rule's source form and its `Unknown`-forbidding upgrade: `[source, upgrade]`. `pure
+ *  <scope>` → ["pure <scope>", "deny Unknown <scope>"]; `deny <E…> <scope>` → ["deny <E…> <scope>",
+ *  "deny <E…> Unknown <scope>"]. Shared so the gate note and `unverified` name the identical upgrade. */
+export function ruleUpgrade(r) {
+  const suffix = r.scope ? ` ${r.scope}` : "";
+  return r.effects.length === 0
+    ? [`pure${suffix}`, `deny Unknown${suffix}`]
+    : [`deny ${r.effects.join(" ")}${suffix}`, `deny ${r.effects.join(" ")} Unknown${suffix}`];
+}
+
+/** The single predicate for a provable-purity hole (eval/fixloop/DISPATCH-NOTE.md): a function that is
+ *  Unknown, sits in a pure/deny scope, and PASSES that rule (carries none of its forbidden real effects) —
+ *  so its compliance is asserted but not verified (the Unknown could hide the very effect the rule forbids;
+ *  the classic case is a fn/closure-injected port). A *real* violation is the gate's job, not this. Returns
+ *  the first governing rule under which the function is such a hole, or null. Shared by the gate note
+ *  (scan.mjs) and `unverified` so "what a hole is" has ONE definition (conformance PART 12d pins agreement). */
+export function unverifiedHoleRule(fn, inferred, policyParsed, scopeMatches) {
+  const inf = inferred ?? [];
+  if (!inf.includes("Unknown")) return null;
+  for (const r of policyParsed.deny) {
+    if (r.scope && !scopeMatches(fn, r.scope)) continue;
+    const violates = r.effects.length === 0
+      ? inf.some((x) => x !== "Unknown")        // pure: any real effect is a violation
+      : inf.some((x) => r.effects.includes(x)); // deny: a named effect is a violation
+    if (!violates) return r;                    // else it's a real violation the gate already reports
+  }
+  return null;
+}
+
+export function unverified(fns, policyParsed, scopeMatches) {
+  const holes = [];
+  for (const e of fns) {
+    // Same predicate + upgrade as the gate note (scan.mjs) — one source of truth for a hole.
+    const r = unverifiedHoleRule(e.fn, e.inferred, policyParsed, scopeMatches);
+    if (!r) continue;
+    const [rule, upgrade] = ruleUpgrade(r);
+    holes.push({ fn: e.fn, rule, unknownWhy: e.unknownWhy ?? [], upgrade });
+  }
+  return { ok: holes.length === 0, unverified: holes };
+}

package/query.mjs

@@ -31,7 +31,7 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          callers as coreCallers, callersFrontier, loadHierarchy,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
-         fix as coreFix, fixGate as coreFixGate,
+         fix as coreFix, fixGate as coreFixGate, unverified as coreUnverified,
          loadReport, loadCallgraph, reportVersion } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
@@ -39,7 +39,7 @@ const emit = (v) => console.log(JSON.stringify(v, null, 1));
 // 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.8";
+const SPEC_VERSION = "0.9";
 
 // The full subcommand catalogue — name + one-line description (derived from the per-subcommand
 // comments + the module-doc header). The single source for the --help list AND the no-arg/unknown
@@ -60,6 +60,7 @@ const SUBCOMMANDS = [
   ["whatif", "<prefix> <fn> <Effect> [policy-file] [0|1]", "the impact of giving a function an effect, vs a policy (exit 1 on a violation)"],
   ["fix", "<prefix> <fn> <Effect> <policy-file>", "the boundary fix: where the effect belongs + the hoist refactor"],
   ["fix-gate", "<prefix> <policy-file>", "a fix for EVERY boundary crossing — the loop's block-message remedy"],
+  ["unverified", "<prefix> <policy-file> [--strict]", "pure/deny layers that PASS but are Unknown (not PROVABLY clean)"],
   ["agents", "", "print the agent contract for this build (AGENTS.md)"],
 ];
 
@@ -284,6 +285,20 @@ switch (cmd) {
     emit(coreFixGate(cg, loadReport(prefix), parsePolicy(ptext), scopeMatches));
     break;
   }
+  case "unverified": {
+    // PROVABLE-PURITY disclosure: pure/deny layers that PASS but contain Unknown (not provably clean). A
+    // policy is required; `--strict` exits 1 on a hole. Advisory (exit 0) otherwise.
+    const strict = args.includes("--strict");
+    const [prefix, policyFile] = args.filter((a) => a !== "--strict");
+    if (!policyFile) { console.error("candor: unverified requires a policy file"); process.exit(2); }
+    let ptext;
+    try { ptext = fs.readFileSync(policyFile, "utf8"); }
+    catch { console.error(`candor: policy ${policyFile} could not be read`); process.exit(2); }
+    const r = coreUnverified(loadReport(prefix), parsePolicy(ptext), scopeMatches);
+    emit(r);
+    process.exit(strict && !r.ok ? 1 : 0);
+    break; // unreachable
+  }
   default:
     // no command (cmd === undefined) or an unknown one: the FULL usage, not the stale 6-item list.
     if (cmd !== undefined) console.error(`candor-ts-query: unknown command '${cmd}'`);

package/scan-core.mjs

@@ -123,6 +123,18 @@ export const KAPPA_RULES = [
   [/^open$/, /^(open|openApp)$/, "Exec"],
   [/^(fs-extra|graceful-fs|rimraf|glob|chokidar)$/, null, "Fs"],
   [/^dotenv$/, null, "Env"],
+  // CLI-tool packages surfaced by the 0.9 dogfood on `zx` (read `invisible` before — a κ-coverage gap, not
+  // a cardinal sin; modeled against each package's SOURCE, not its name):
+  // - `which`: resolves an executable by stat-ing PATH candidates (via `isexe`) — Fs. Both the async default
+  //   `which(cmd)` and `which.sync(cmd)` hit the filesystem; no pure member → whole-module Fs.
+  [/^which$/, null, "Fs"],
+  // - `@webpod/ps`: process listing/kill — kill/lookup/lookupSync/tree/treeSync ALL spawn the OS via
+  //   `exec({...})` (zurk/spawn) — verified in ps.js. Uniform process surface, no pure member → Exec.
+  [/^@webpod\/ps$/, null, "Exec"],
+  // - `envapi` (a dotenv variant): MIXED — `parse`/`stringify` are pure string transforms; `load`/`loadSafe`/
+  //   `config` READ the .env file (`fs.readFileSync`). Member-precise so `parse` never fabricates Fs (the
+  //   argon2 curated-κ lesson: model the effectful member, never blanket-grant a mixed package).
+  [/^envapi$/, /^(load|loadSafe|config)$/, "Fs"],
   [/^(winston|pino|bunyan|npmlog)$/, null, "Log"],
   // nest-winston wraps winston; the injected logger's level verbs are the Log boundary (the
   // WinstonModule.createLogger/forRoot config is inert).

package/scan.mjs

@@ -26,7 +26,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
-import { parsePolicy, evaluatePolicy } from "./policy.mjs";
+import { parsePolicy, evaluatePolicy, scopeMatches } from "./policy.mjs";
+import { unverifiedHoleRule, ruleUpgrade } from "./query-core.mjs";
 import { printAgents } from "./contract.mjs";
 import { isTestPath, kappa, kappaKnows, commandHeadEffects, hostLiteral, tablesInSql } from "./scan-core.mjs";
 
@@ -38,7 +39,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.8";
+const SPEC_VERSION = "0.9";
 
 // --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
@@ -272,14 +273,25 @@ if (!wantJson) fs.mkdirSync(path.dirname(path.resolve(outPrefix)), { recursive:
 // would "succeed" with a near-total-Unknown report a fresh user could ship (CTA-dogfood finding).
 // Warn LOUDLY; the report is still written (it is sound), but the cause must be visible.
 {
-  const pkg = path.join(rootDir, "package.json");
-  if (fs.existsSync(pkg) && !fs.existsSync(path.join(rootDir, "node_modules"))) {
+  // Find the nearest package.json AT OR ABOVE the scan root: scanning a `src/` subdirectory must still see
+  // the project manifest one level up, else the warning stays silent and a deps-less scan reads as a
+  // codebase full of spurious `Unknown`s (the exact trap a 0.9 dogfood fell into — scanning `zx/src`).
+  let projDir = null;
+  for (let d = rootDir; ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, "package.json"))) { projDir = d; break; }
+    if (path.dirname(d) === d) break;                       // filesystem root
+  }
+  if (projDir && !fs.existsSync(path.join(projDir, "node_modules"))) {
     try {
-      const deps = JSON.parse(fs.readFileSync(pkg, "utf8")).dependencies ?? {};
+      // BOTH dependency kinds: `npm install` installs devDependencies too, and a project can import a
+      // dev/vendored package in its source (zx imports `chalk` as a devDependency) — a `dependencies`-only
+      // check left exactly that case unwarned.
+      const pj = JSON.parse(fs.readFileSync(path.join(projDir, "package.json"), "utf8"));
+      const deps = { ...(pj.dependencies ?? {}), ...(pj.devDependencies ?? {}) };
       if (Object.keys(deps).length > 0)
-        console.error("candor-ts: WARNING — the target declares dependencies but has no node_modules; " +
-                      "imports won't resolve, so calls into those packages read pure/invisible (not Unknown) " +
-                      "and effects through them are silently dropped. Run `npm install` in the target first.");
+        console.error("candor-ts: WARNING — the project declares dependencies but has no node_modules; " +
+                      "imports won't resolve, so calls into those packages can't be analyzed (they read " +
+                      "`Unknown`, and their types don't resolve). Run `npm install` in the project first.");
     } catch {}
   }
   // Prisma's client types are GENERATED — a project with the prisma dependency but no generated
@@ -2261,6 +2273,21 @@ if (policyPath !== null) {
   const incompleteMap = new Map();
   for (const [name, rec] of fns) if (rec.incomplete.size) incompleteMap.set(name, rec.incomplete);
   gateViolations = gateViolations.concat(evaluatePolicy(parsePolicy(text), functions, cg, incompleteMap));
+  // Provable-purity DISCLOSURE (advisory — NEVER a violation, so the exit/verdict are untouched): functions
+  // in a pure/deny scope that PASS but are Unknown (the Unknown could hide the forbidden effect — a
+  // fn/closure-injected port). Surfaces the gap automatically (eval/fixloop/DISPATCH-NOTE.md).
+  const disclosePolicy = parsePolicy(text);
+  const purityHoles = [];
+  for (const f of functions) {
+    // Same predicate + upgrade as `candor-ts-query unverified` (query-core.mjs) — one source of truth.
+    const r = unverifiedHoleRule(f.fn, f.inferred, disclosePolicy, scopeMatches);
+    if (r) purityHoles.push([f.fn, ruleUpgrade(r)[1]]);
+  }
+  if (purityHoles.length) {
+    console.error(`candor-ts: note — ${purityHoles.length} function(s) PASS the policy but are Unknown (purity NOT verified — the Unknown could hide a forbidden effect):`);
+    for (const [fn, up] of purityHoles) console.error(`    \`${fn}\`  → add  \`${up}\``);
+    console.error("  (advisory; add the upgrade(s) to REQUIRE provable purity, or run `candor-ts-query unverified` for detail — the gate verdict is unchanged)");
+  }
 }
 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