candor-ts 0.4.6 → 0.5.1

package/AGENTS.md

@@ -9,6 +9,12 @@ chains by hand.
 > the *installed* version — always prefer that over a vendored or fetched copy, which can describe
 > a different candor-ts than the one you are running.
 
+> **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: read the installed version here, compare
+> it against npm, and upgrade if it is stale. Every command is offline.
+
 The language-agnostic consumption contract is
 [candor-spec/AGENTS.md](https://github.com/tombaldwin/candor-spec/blob/main/AGENTS.md); this file is
 the TypeScript-specific production + query surface.
@@ -54,20 +60,28 @@ downgraded to `Unknown` rather than silently trusted (spec §2.1). Caveat: a typ
 Q() { npx -y candor-ts-query "$@"; }; P=".candor/report"   # a function — works in bash AND zsh
 Q show     $P <fn-query> 1          # a function's effects (+ hosts/tables when visible)
 Q where    $P <Effect>   1          # {effect, directly, inherited}
-Q callers  $P <fn-query> 1          # the BLAST RADIUS: {of, direct, transitive} — works for pure fns
+Q impact   $P <fn-query>            # THE BLAST RADIUS: {fn, affectedCount, affected, entryPoints}
+Q callers  $P <fn-query> 1          # the lower-level form: {of, direct, transitive} — works for pure fns
+Q path     $P <fn> <Effect>         # how a fn reaches an effect: the chain to the nearest source
 Q map      $P 1                     # {module: {effects, functions}}
 Q whatif   $P <fn> <Effect> [policy]  # pre-edit gate verdict (exit 1 if it would violate)
 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
 Q reachable $P 1                    # what the app DOES at runtime: effects over the entry points
 Q parsepolicy <policy-file>         # the canonical §6.2 parse (what the gate will enforce)
 ```
 
+And as an MCP server, so an agent pulls these as tools instead of shelling out:
+`CANDOR_REPORT=$P npx -y candor-ts-mcp` (tools `candor_impact`/`candor_reachable`/`candor_where`/…).
+`npx -y candor-ts-watch <dir>` keeps the report fresh as you edit (and reports the edit-delta).
+
 Name queries resolve exact > segment-suffix (`db.save` matches `src.db.save`, never
 `src.db.save_all`) > substring — the same ladder as the other engines. The trailing `1` is the
 want-JSON flag.
 
-- **Blast radius of editing a function** → `callers <fn>` (NOT its `inferred`, which is what the
-  function itself does). Works pre-edit for a still-pure function.
+- **Blast radius of editing a function** → `impact <fn>` (the `affected` list + downstream
+  `entryPoints`; NOT its `inferred`, which is what the function itself does). Works pre-edit for a
+  still-pure function. `callers <fn>` is the lower-level raw-callers form.
 - **Decide BEFORE you edit** → `whatif <fn> <Effect> [policy]` — every transitive caller gains the
   effect, crossed with the policy.
 - **After you change code** → `diff` against a baseline report; a gained `Net`/`Db`/`Exec`/`Fs` you
@@ -119,4 +133,7 @@ curated-κ caveat cuts the other way:** a call into an npm package κ doesn't kn
 NOTHING — invisible, not `Unknown`. The scan's receipt now DISCLOSES these by name (`κ doesn't
 know N packages…`), so the blind spots are per-scan evidence, not a doc footnote: never conclude
 "no effect" through a package that line names (the documented weaker edge of the
-never-silently-pure promise, same as every candor engine's curated classifier).
+never-silently-pure promise, same as every candor engine's curated classifier). An uncurated
+dependency can opt out of that blind spot by declaring `"candorEffects": ["Net", …]` in its
+`package.json` (the §5.1 effect manifest, read declared-not-verified) — its calls then classify to
+the declared set instead of contributing nothing.

package/README.md

@@ -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 --version                     # installed build + spec contract (offline), + upgrade line
+
 node query.mjs show     .candor/report db.save 1   # a function's effects (match ladder)
 node query.mjs where    .candor/report Net 1       # direct sources vs inheritors
 node query.mjs callers  .candor/report db.save 1   # the blast radius (transitive callers)
@@ -28,6 +30,8 @@ node query.mjs whatif   .candor/report db.save Net policy  # pre-edit gate verdi
 node query.mjs diff     .candor/report baseline 1  # per-function effect delta (exit 1 on a gain)
 ```
 
+**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:
 
@@ -54,10 +58,53 @@ plus a small npm tier (axios/got/node-fetch/undici/ws, pg/mysql2/mongodb/redis/k
 execa/cross-spawn, fs-extra/rimraf/glob, dotenv, winston/pino). An unlisted package contributes
 nothing — candor never guesses an effect.
 
+## MCP server — candor as agent ground truth
+
+`candor-ts-mcp` exposes the read-only queries as an [MCP](https://modelcontextprotocol.io) server, so
+a coding agent can ask **"if I change this, what's the runtime blast radius?"** or **"what reaches the
+network?"** and get deterministic ground truth from a precomputed report — instead of burning tokens
+tracing the call graph by hand (the measured ~700–2000× token win on blast-radius questions).
+
+```jsonc
+// in an MCP client config — point it at a report you've already scanned
+{ "command": "npx", "args": ["-y", "candor-ts-mcp"],
+  "env": { "CANDOR_REPORT": ".candor/report.myPkg.scan" } }
+```
+
+Tools: `candor_impact` (backward blast radius), `candor_reachable` (what runs at runtime),
+`candor_where` (effect surface), `candor_path` (how an effect is reached), `candor_callers`,
+`candor_show`, `candor_map`, `candor_whatif` (pre-edit gate check). Each takes an optional `report`
+prefix (else `$CANDOR_REPORT`). The server is **query-only** — it never scans (the analyzer
+self-boundary, spec §7.12: an agent or a hook produces the report; the server reads it, Fs only). The
+query logic is the shared `query-core.mjs`, the same answers the CLI gives.
+
+**The live loop** — `candor-ts-watch` keeps the report fresh as the agent edits, so the answers are
+about the *current* code, not a stale snapshot:
+
+```sh
+candor-ts-watch ./src --out .candor/report   # re-scans only when a tracked source actually changes
+```
+
+It tracks the project's sources by content hash and re-scans on a real change (a no-op save or an
+unrelated write does nothing), writing the same prefix the MCP server reads. So: **agent edits →
+watcher refreshes the report → agent asks `candor_impact` and gets the post-edit answer.** And it
+reports the **edit-delta** — not just that the report is fresh but *what the edit did* to the effect
+surface (`re-scanned (1 changed: app.ts) — Δ f +Net`), so the agent learns the consequence of its
+own change. v1 runs a full (sound) scan per change; the deeper *perf* optimisation — re-analysing
+only the changed file's subgraph instead of the whole project — is the staged next step (the
+content-hash gate is its first increment).
+
 ## Trust contract (spec §4)
 
 Anything candor-ts can't resolve is `Unknown`, never silently pure: a function-valued parameter or
 field being called, an `any`-typed callee, resolution landing on a type rather than a body.
+
+An **uncurated dependency** can opt out of `Unknown`/silent-pure by **declaring its effects** in its
+`package.json` — `"candorEffects": ["Net"]` (spec §5.1, the effect manifest). candor-ts reads it as
+the declared-not-verified tier: the package's calls classify to the declared set, and it stops being
+a κ-ledger blind spot. A name outside the §1 vocabulary voids the declaration loudly (a typo must not
+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` —
 that's the contract working, not noise. The report says "can reach", never "does"; an absent
@@ -82,7 +129,7 @@ every push to the spec.
 | 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.4" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.5" }, 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 |
 
@@ -107,3 +154,21 @@ conformance-held. The npm classifier tier is
 deliberately curated and will keep 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>`.
+
+## Development
+
+No build step — the engine runs on Node directly.
+
+```sh
+npm install
+npm test            # the full CI gate: lint + unit (node:test) + behavioural + MCP + watch + the
+                    # fabrication probe + the §7.13 soundness fuzzer
+npm run test:unit   # just the native unit tests — the query algebra + policy DSL + the scan-core
+                    # classifier/literal leaves (query-core / policy / scan-core)
+npm run lint        # eslint (the recommended ruleset; the CI lint gate)
+node scan.mjs <dir | file.ts | tsconfig.json> --out .candor/report   # scan a project
+```
+
+The pure cores are factored into importable modules — `query-core.mjs` (the §3.1 queries),
+`policy.mjs` (the §6.2 DSL + literal matchers), and `scan-core.mjs` (the κ classifier + the SQL/
+command/host extractors) — so they're unit-tested directly; the TS-compiler-driven walk stays in `scan.mjs`.

package/mcp.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * candor-mcp — candor's read-only query surface as an MCP server (roadmap direction #1: candor as
+ * agent infrastructure). An agent asks "if I change X, what's the runtime blast radius?" or "what
+ * reaches the network?" and gets DETERMINISTIC ground truth from a precomputed report in ~zero
+ * exploration tokens — the measured ~700-2000x token win over grepping to the same answer.
+ *
+ * Transport: newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio framing), implemented directly
+ * so candor-ts's `npx` scan/query path stays dependency-free. Query logic is the shared query-core.mjs
+ * (one source of truth with the CLI). The server is QUERY-ONLY (it never scans — the analyzer self-
+ * boundary, SPEC §7.12; an agent/hook produces the report, the server reads it: Fs only).
+ *
+ * The report to query is resolved per call from the tool's `report` arg, else $CANDOR_REPORT, else
+ * the first CLI arg. A `<prefix>` names `<prefix>.json` + `<prefix>.callgraph.json`.
+ *
+ *   CANDOR_REPORT=.candor/report.myCrate.scan  npx -y candor-ts mcp
+ */
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import nodePath from "node:path";
+import * as Q from "./query-core.mjs";
+import { parsePolicy, scopeMatches } from "./policy.mjs";
+
+const VERSION = createRequire(import.meta.url)("./package.json").version; // single-sourced, like scan.mjs
+
+const DEFAULT_PREFIX = process.env.CANDOR_REPORT || process.argv[2] || null;
+
+// A report exists at the prefix if there's an exact `<prefix>.json` (candor-ts) OR a sibling
+// `<prefix>.<crate>.scan.json` (the candor-scan/Rust multi-report form) — the loaders read both, so
+// the MCP server serves a report from ANY engine, not just candor-ts's.
+function hasReport(p) {
+  if (fs.existsSync(`${p}.json`)) return true;
+  const base = nodePath.basename(p);
+  try {
+    // SAME predicate (Q.isReport) the loader uses — a prefix whose only sibling is `.encountered-*` /
+    // `.calibrated.json` must NOT pass here, else loadReport finds zero functions and the tool returns an
+    // authoritative-empty result instead of "no report" (a silent under-report — review find).
+    return fs.readdirSync(nodePath.dirname(p) || ".").some((f) =>
+      f.startsWith(base + ".") && f.endsWith(".json") && Q.isReport(f));
+  } catch { return false; }
+}
+function resolvePrefix(args) {
+  const p = args?.report || DEFAULT_PREFIX;
+  if (!p) throw new Error("no report prefix: pass `report`, set $CANDOR_REPORT, or give one as the CLI arg");
+  if (!hasReport(p)) throw new Error(`no report at \`${p}\` (.json or .<crate>.scan.json) — run a candor scan first`);
+  return p;
+}
+
+// ---- the tools: name -> {description, schema, run} ------------------------------------------------
+const reportArg = { report: { type: "string", description: "report prefix (optional; defaults to $CANDOR_REPORT)" } };
+
+// Bound a blast-radius/caller LIST for the agent transport: on a large repo a single fn can have
+// hundreds-to-thousands of transitive callers, an unbounded multi-thousand-token answer. The agent's
+// question ("how big is the blast radius / where does it surface") is answered by the COUNT + the entry
+// points + the top names — so cap the list to MCP_LIST_CAP, keep the exact count, and flag truncation.
+// The full list stays available from the CLI / `--json` (the spec-pinned §3.1 shape is UNCHANGED — this
+// only shapes the MCP result for its token-sensitive transport). Small results are returned verbatim.
+const MCP_LIST_CAP = 50;
+function capImpact(r) {
+  if (!Array.isArray(r.affected) || r.affected.length <= MCP_LIST_CAP) return r; // affectedCount is the full count
+  return { ...r, affected: r.affected.slice(0, MCP_LIST_CAP), affectedTruncated: true };
+}
+function capCallers(r) {
+  const d = r.direct ?? [], t = r.transitive ?? [];
+  if (d.length <= MCP_LIST_CAP && t.length <= MCP_LIST_CAP) return r;
+  return {
+    of: r.of,
+    directCount: d.length, direct: d.slice(0, MCP_LIST_CAP),
+    transitiveCount: t.length, transitive: t.slice(0, MCP_LIST_CAP),
+    truncated: true,
+  };
+}
+const TOOLS = {
+  candor_impact: {
+    description: "Backward blast radius: every effectful function that transitively calls `fn`, and which runtime entry points are downstream. Answers 'if I change this, what surfaces at runtime?' — the cheapest possible alternative to tracing callers by hand.",
+    schema: { type: "object", properties: { fn: { type: "string", description: "the function/unit to assess" }, ...reportArg }, required: ["fn"] },
+    run: (a, p) => capImpact(Q.impact(Q.loadReport(p), Q.loadCallgraph(p), a.fn)),
+  },
+  candor_where: {
+    description: "Which functions perform a given effect (e.g. Net, Db, Exec, Fs) — `directly` vs `inherited` via a callee. The effect-surface map.",
+    schema: { type: "object", properties: { effect: { type: "string", description: "Net|Fs|Db|Exec|Env|Clock|Ipc|Log|Rand|Clipboard|Unknown" }, ...reportArg }, required: ["effect"] },
+    run: (a, p) => Q.where(Q.loadReport(p), a.effect),
+  },
+  candor_reachable: {
+    description: "What the program/fleet actually DOES at runtime: effects unioned over the entry points, with how many roots reach each and via which.",
+    schema: { type: "object", properties: { ...reportArg } },
+    run: (_a, p) => Q.reachable(Q.loadReport(p)),
+  },
+  candor_path: {
+    description: "Forward provenance: the shortest call chain from `fn` to the nearest function that performs `effect` DIRECTLY — 'this reaches Net through WHAT?'.",
+    schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, ...reportArg }, required: ["fn", "effect"] },
+    run: (a, p) => Q.path(Q.loadReport(p), Q.loadCallgraph(p), a.fn, a.effect),
+  },
+  candor_callers: {
+    description: "Who calls `fn` — direct (one hop) and transitive callers over the effect-relevant call graph.",
+    schema: { type: "object", properties: { fn: { type: "string" }, ...reportArg }, required: ["fn"] },
+    run: (a, p) => capCallers(Q.callers(Q.loadCallgraph(p), a.fn)),
+  },
+  candor_show: {
+    description: "A function's effects (inferred = transitive, direct = own body) plus its literal surfaces (hosts/cmds/paths/tables) when present.",
+    schema: { type: "object", properties: { fn: { type: "string" }, ...reportArg }, required: ["fn"] },
+    run: (a, p) => Q.show(Q.loadReport(p), a.fn),
+  },
+  candor_map: {
+    description: "Per-module effect overview: each module's union of effects and function count. The architecture-at-a-glance.",
+    schema: { type: "object", properties: { ...reportArg } },
+    run: (_a, p) => Q.map(Q.loadReport(p)),
+  },
+  candor_whatif: {
+    description: "Hypothetically add `effect` to `fn` and report the blast radius; with `policy`, also the deny-rule violations it would cause. Pre-edit gate check.",
+    schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a CANDOR_POLICY file (optional)" }, ...reportArg }, required: ["fn", "effect"] },
+    run: (a, p) => {
+      const pol = a.policy && fs.existsSync(a.policy) ? parsePolicy(fs.readFileSync(a.policy, "utf8")) : null;
+      const r = Q.whatif(Q.loadCallgraph(p), a.fn, a.effect, pol, scopeMatches);
+      if (r === null) throw new Error(`no function matching \`${a.fn}\` in the call graph`);
+      return r;
+    },
+  },
+};
+
+// ---- JSON-RPC 2.0 over stdio (newline-delimited; the MCP stdio framing) ---------------------------
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n"); }
+function result(id, r) { send({ jsonrpc: "2.0", id, result: r }); }
+function error(id, code, message) { send({ jsonrpc: "2.0", id, error: { code, message } }); }
+
+function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    return result(id, {
+      protocolVersion: params?.protocolVersion || "2025-06-18",
+      capabilities: { tools: {} },
+      serverInfo: { name: "candor-mcp", version: VERSION },
+      instructions: "candor's read-only effect queries. Prefer candor_impact/candor_reachable/candor_where over manually tracing the call graph — they return deterministic ground truth from a precomputed report. Run a candor scan first to produce the report.",
+    });
+  }
+  if (method === "notifications/initialized" || method === "notifications/cancelled") return; // notifications: no reply
+  if (method === "ping") return result(id, {});
+  if (method === "tools/list") {
+    return result(id, {
+      tools: Object.entries(TOOLS).map(([name, t]) => ({ name, description: t.description, inputSchema: t.schema })),
+    });
+  }
+  if (method === "tools/call") {
+    const t = TOOLS[params?.name];
+    if (!t) return error(id, -32602, `unknown tool: ${params?.name}`);
+    try {
+      const args = params.arguments || {};
+      // Enforce the tool's declared required args server-side — a missing `fn` must be a clear error,
+      // not a silently-empty result (a defensive server doesn't trust the client to validate).
+      const missing = (t.schema.required || []).filter((k) => args[k] === undefined || args[k] === "");
+      if (missing.length)
+        return result(id, { content: [{ type: "text", text: `candor: missing required argument(s): ${missing.join(", ")}` }], isError: true });
+      const prefix = resolvePrefix(args);
+      // A tool that targets a `fn` gets a clear "not found" rather than a silently-empty result —
+      // an agent must distinguish "no such function" from "found, nothing calls it".
+      if (args.fn !== undefined) {
+        const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...Q.loadReport(prefix).map((e) => e.fn)])];
+        if (Q.matches(names, args.fn).length === 0)
+          return result(id, { content: [{ type: "text", text: `candor: no function matching \`${args.fn}\` in this report` }], isError: true });
+      }
+      const out = t.run(args, prefix);
+      // Minified, not pretty-printed: the consumer is an AGENT (it parses the JSON), so the indentation
+      // was ~25-30% of every result's tokens for no benefit. The CLI keeps its human-readable shapes.
+      return result(id, { content: [{ type: "text", text: JSON.stringify(out) }] });
+    } catch (e) {
+      // A tool-level failure is reported in the result (isError), not as a protocol error.
+      return result(id, { content: [{ type: "text", text: `candor: ${e.message}` }], isError: true });
+    }
+  }
+  if (id !== undefined) error(id, -32601, `method not found: ${method}`);
+}
+
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; } // ignore unparseable frames
+    // A JSON-RPC frame is a (non-null, non-array) object. `null`, a bare primitive, or a batch array
+    // would crash `handle`'s destructure — and the catch's own `msg.id` deref re-threw OUTSIDE the
+    // handler, killing the whole server (and the agent's session) on a single `null\n` line (review find).
+    if (!msg || typeof msg !== "object" || Array.isArray(msg)) continue;
+    try { handle(msg); } catch (e) { if (msg.id !== undefined) error(msg.id, -32603, e.message); }
+  }
+});
+process.stdin.on("end", () => process.exit(0));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.4.6",
-  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.4)",
+  "version": "0.5.1",
+  "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",
@@ -9,10 +9,16 @@
   },
   "bin": {
     "candor-ts": "./scan.mjs",
-    "candor-ts-query": "./query.mjs"
+    "candor-ts-query": "./query.mjs",
+    "candor-ts-mcp": "./mcp.mjs",
+    "candor-ts-watch": "./watch.mjs"
   },
   "scripts": {
-    "test": "node test.mjs"
+    "lint": "eslint *.mjs",
+    "test": "npm run lint && node --test test-unit.mjs && node test.mjs && node test-mcp.mjs && node test-watch.mjs && npm run test:probe && npm run test:fuzz",
+    "test:unit": "node --test test-unit.mjs",
+    "test:probe": "node fabrication_probe.mjs",
+    "test:fuzz": "node fuzz.mjs"
   },
   "license": "(MIT OR Apache-2.0)",
   "repository": {
@@ -40,6 +46,15 @@
     "AGENTS.md",
     "PROVE-IT.md",
     "LICENSE-MIT",
-    "LICENSE-APACHE"
-  ]
+    "LICENSE-APACHE",
+    "query-core.mjs",
+    "scan-core.mjs",
+    "mcp.mjs",
+    "watch.mjs"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "eslint": "^9.39.4",
+    "globals": "^17.6.0"
+  }
 }

package/policy.mjs

@@ -7,12 +7,17 @@
 export const EFFECTS = ["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard"];
 const ALLOW_EFFECTS = new Set(["Net", "Exec", "Fs", "Db"]); // the four literal surfaces
 
+// The §6.2 token separator: ASCII whitespace ONLY (space/tab/LF/VT/FF/CR). JS `\s`/`String.trim` strip
+// Unicode spaces (NBSP, ideographic, …) that Java drops — a gateless-green cross-engine divergence
+// (adversarial DSL review). A non-ASCII space stays part of its token → the rule is malformed, dropped.
+const ASCII_WS = /[ \t\n\v\f\r]+/;
+const ASCII_WS_TRIM = /^[ \t\n\v\f\r]+|[ \t\n\v\f\r]+$/g;
 export function parsePolicy(text) {
   const deny = [], allow = [], forbid = [];
   for (const rawLine of text.split("\n")) {
-    const line = rawLine.split("#")[0].trim();
+    const line = rawLine.split("#")[0].replace(ASCII_WS_TRIM, "");
     if (!line) continue;
-    const t = line.split(/\s+/);
+    const t = line.split(ASCII_WS);
     const warn = (why) => console.error(`candor: ignoring policy rule (${why}): ${line}`);
     if (t[0] === "deny") {
       const effects = [];
@@ -22,7 +27,7 @@ export function parsePolicy(text) {
         else { scope = tok; break; }
       }
       if (effects.length === 0) { warn("deny names no known effect"); continue; }
-      deny.push({ effects: effects.sort(), scope, raw: line });
+      deny.push({ effects: [...new Set(effects)].sort(), scope, raw: line }); // dedup: a set, like rust/java
     } else if (t[0] === "pure") {
       deny.push({ effects: [], scope: t[1] ?? "", raw: line });
     } else if (t[0] === "allow") {
@@ -32,7 +37,7 @@ export function parsePolicy(text) {
       if (t[2] === "in") { scope = t[3] ?? ""; vi = 4; }
       const values = t.slice(vi);
       if (values.length === 0) { warn("allow names no values"); continue; }
-      allow.push({ effect: t[1], scope, values: values.sort(), raw: line });
+      allow.push({ effect: t[1], scope, values: [...new Set(values)].sort(), raw: line }); // dedup (set)
     } else if (t[0] === "forbid") {
       // Token-wise like the Rust/JVM parsers: the arrow must be its own whitespace-separated token
       // (`a->b` glued is malformed), and tokens past `b` are ignored. A regex here once accepted and