candor-ts 0.38.3 → 0.39.1

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.38)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.39)."*
 > On a build too old for the flag, read `candor.version` / `candor.spec` from an existing
 > `.candor/report*.json`, or `npm ls -g candor-ts`.
 >

package/README.md

@@ -201,7 +201,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.38" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.39" }, 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 |
 
@@ -219,7 +219,7 @@ read the Rust source".
 
 ## Status
 
-0.30.0, speaking candor-spec 0.38: the analysis core, the gate (`--policy` / `--gate-json` /
+0.30.0, speaking candor-spec 0.39: 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/mcp.mjs

@@ -344,6 +344,9 @@ const TOOLS = {
     // available to it. Fixed key sets, so the caveat spreads at the root and every pinned tool shape is
     // unchanged on a complete report (`completenessFields` → `{}`). These three certify nothing, so they
     // are on the descriptive side of the ⟨0.32⟩ boundary stated on `nestWithCaveat` below.
+    // SOUNDNESS R507 — see the dispatcher's `oneSubject` guard. `impact` answers about ONE function, so
+    // a selector naming several is REFUSED rather than silently resolved to an arbitrary one.
+    oneSubject: true,
     run: (a, p) => { const fns = loadReportLoud(p); return withCompleteness(p, capImpact(Q.impact(fns, graphOrReportEdges(p, fns), a.fn))); },
   },
   candor_where: {
@@ -361,6 +364,7 @@ const TOOLS = {
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, ...reportArg }, required: ["fn", "effect"] },
     // ⟨0.32⟩ see `candor_impact` above: `path: []` to an agent is *this function does not reach that
     // effect*, and a hop through an unread unit breaks the chain.
+    oneSubject: true,   // SOUNDNESS R507 — see `candor_impact` and the dispatcher's guard
     run: (a, p) => { const fns = loadReportLoud(p); return withCompleteness(p, Q.path(fns, graphOrReportEdges(p, fns), a.fn, a.effect)); },
   },
   candor_callers: {
@@ -914,6 +918,14 @@ function handle(msg) {
         const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...loadReportLoud(prefix).map((e) => e.fn)])];
         if (Q.matches(names, args.fn).length === 0)
           return result(id, { content: [{ type: "text", text: `candor: no function matching \`${clip(args.fn)}\` in this report` }], isError: true });
+        // SOUNDNESS R507 — the OTHER half of the same resolution, and scoped to the tools that answer
+        // about ONE subject. `candor_show`/`candor_callers`/`candor_whatif` answer over the WHOLE
+        // best-tier set, so several matches WIDEN their answer rather than substituting a subject;
+        // `candor_path`/`candor_impact` take one and print a confident verdict about it. Refusing here
+        // rather than inside the verbs keeps the decision beside the zero-match guard it is the twin of.
+        const amb = t.oneSubject ? Q.ambiguousSelector(names, args.fn) : null;
+        if (amb)
+          return result(id, { content: [{ type: "text", text: `candor: \`${clip(args.fn)}\` names ${amb.length} functions in this report — refusing to answer about one of them. Re-run with the full name: ${amb.map((n) => clip(n)).join(", ")}` }], isError: true });
       }
       const out = t.run(args, prefix);
       // Minified, not pretty-printed: the consumer is an AGENT (it parses the JSON), so the indentation

package/package.json

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

package/policy.mjs

@@ -670,6 +670,20 @@ export function refusalVerdict(spec, reason, unevaluated = null) {
  * ⟨0.24⟩ §3.3.1 requires every ordering to be locale-INDEPENDENT. `Array.prototype.sort` has been
  * stable since ES2019, so rows with an equal key keep their arrival order.
  */
+// ⟨0.23⟩/⟨0.39⟩ Say out loud, WITHOUT moving the verdict, which synthetic `interfaceUnion` entries a
+// rule matched. One printer, called from the two VERDICT routes (`scan --policy` and `gate --report`),
+// so §3.1's byte-equality between them covers the note as well as the rows.
+export function noteSyntheticHits(violations, err = console.error) {
+  const hits = violations?.syntheticHits ?? [];
+  if (!hits.length) return;
+  err(`candor-ts: note — ${hits.length} ⟨0.23⟩ interfaceUnion entr`
+    + (hits.length === 1 ? "y matches a policy rule and is NOT gated as a function"
+                         : "ies match a policy rule and are NOT gated as functions")
+    + ": the key names a BODILESS declaration, and the effects under it are the CHA union over "
+    + "implementors, each of which IS gated under its own entry.");
+  for (const h of hits) err(`    \`${h.fn}\`  { ${h.effects.join(", ")} }  would have matched  \`${h.rule}\``);
+}
+
 export function sortViolations(violations) {
   const c = (x, y) => (x < y ? -1 : x > y ? 1 : 0);
   return violations.sort((a, b) =>
@@ -1066,6 +1080,11 @@ export function classFilterExcludes(r, entry, eff, reasonAcc, netClassOf, units
 
 export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map(), partners = new Set(), netClasses = null, withhold = null, units = null, hashByName = null) {
   const out = [];
+  // ⟨0.39⟩ the synthetic `interfaceUnion` entries a rule MATCHED — carried on the returned array (a
+  // non-index property, so `length`, iteration and `JSON.stringify` are all untouched) rather than
+  // printed from here, because this function is also called for sub-evaluations that must stay silent.
+  const syntheticHits = [];
+  out.syntheticHits = syntheticHits;
   // `Llm` ⟨0.13⟩ reaches the SAME hosts surface as Net (an Llm host WAS captured as a Net host literal).
   const surfaces = { Net: "hosts", Llm: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
   // §6.2 ⟨0.19⟩: `reasonClass` (all classes on the fn) rides an AS-EFF-006 Unknown violation; ⟨0.20⟩ `netClass`
@@ -1130,6 +1149,34 @@ export function evaluatePolicy(pol, functions, callgraph, incomplete = new Map()
   // The gate's TEST and the class list it REPORTS both read it, so the two can't disagree about one function.
   const netClassOf = netClassResolver(incomplete, partners, netClasses, units);
   for (const f of functions) {
+    // ⟨0.23⟩/⟨0.39⟩ A SYNTHETIC `interfaceUnion` ENTRY IS NOT A UNIT, so it cannot PERFORM anything and
+    // must not become a violation ROW. Its `fn` names a BODILESS declaration (`Store.save` on an
+    // interface); the effects under it are the CHA union over implementors, published under that hash so
+    // a CHAINED CONSUMER's dispatch resolves across the scan boundary. Every effect it carries is
+    // already on an implementor's OWN entry in the same report — which IS a unit, and IS gated one loop
+    // iteration away.
+    //
+    // MEASURED HERE, not inherited from the reference engine's argument: over `interface Entry { state()
+    // }` with a single STRUCTURAL implementor, `deny Unknown` went exit 0 -> 1 the moment ⟨0.39⟩ un-gated
+    // the union — while the package's own `stringify` resolved the dispatch PRECISELY (a real `calls`
+    // edge to the structural member) and carried no Unknown at all. The union's Unknown is an artifact of
+    // what the WIRE can name (a structural implementor has no class name to key on), never a fact about
+    // a body this scan read, so gating on it is a fabricated violation in the producer's own verdict.
+    // candor-java measured the identical flip (`Policy.java:778`) and takes the identical course.
+    //
+    // DISCLOSED, NOT DROPPED: the hits are recorded on the returned array and printed by the verdict
+    // routes, because the one thing a reader of a chained dependency's report wants to know here is that
+    // the dependency publishes a dispatch surface reaching a denied effect.
+    if (f?.interfaceUnion === true) {
+      for (const r of pol.deny) {
+        if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
+        const inf = Array.isArray(f.inferred) ? f.inferred : [];
+        const hits = r.effects.length === 0 ? inf.filter((e) => e !== "Unknown")
+                                            : inf.filter((e) => r.effects.includes(e));
+        if (hits.length) syntheticHits.push({ fn: f.fn, effects: hits.slice().sort(), rule: r.raw });
+      }
+      continue;
+    }
     // ⟨0.32⟩ the KEY identifies the unit; `f.fn` is the NAME, and the name is what a policy SCOPE matches
     // and what the verdict row prints (§3.3.1 byte-equality with `scan --policy` rests on it).
     const uk = unitKey(units, f);

package/query-core.mjs

@@ -196,7 +196,7 @@ function normFn(e) {
   // non-string in `unknownWhy` reaches `reasonClass()` and one in `hosts`/`netClass` reaches the ⟨0.20⟩
   // destination-class matcher.
   for (const k of ["unknownWhy", "netClass", "hosts", "cmds", "paths", "tables",
-                   "declared", "undeclared", "overdeclared"]) if (k in e) o[k] = arr(e[k]);
+                   "declared", "undeclared", "overdeclared", "dispatchesOn"]) if (k in e) o[k] = arr(e[k]);
   return o;
 }
 
@@ -215,8 +215,12 @@ function normFn(e) {
 // on, the ⟨0.19⟩/⟨0.20⟩ class fields it scopes with, and the `calls` edges the reason-class fixpoint runs
 // over. `loc`/`hash`/`unitKind`/`invisible`/`unresolved` are deliberately NOT here: no verdict reads them,
 // so refusing on them would be a spurious refusal on a report whose gate-relevant content is intact.
+// ⟨0.39⟩ `dispatchesOn` is a VERDICT key, not a diagnostic one: a chained consumer unions the effects
+// of every implementor published under each key it names, so a present-but-unparseable one coerced to
+// `[]` silently drops that union — an effect the consumer really reaches, gone, with no hedge. Exactly
+// the fail-OPEN direction this list exists to refuse.
 const VERDICT_STR_ARRAY_KEYS = ["inferred", "direct", "calls", "unknownWhy", "netClass", "hosts",
-                                "declared", "undeclared", "overdeclared"];
+                                "declared", "undeclared", "overdeclared", "dispatchesOn"];
 const isStrArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
 export function entryCorruptKeys(e) {
   if (!e || typeof e !== "object" || Array.isArray(e)) return ["<entry is not an object>"];
@@ -1382,6 +1386,29 @@ export function matches(names, q) {
   return best === 0 ? [] : names.filter((n) => matchTier(n, q) >= best);
 }
 
+/** SOUNDNESS R507/R497 — THE SELECTOR THAT NAMES SEVERAL FUNCTIONS, for the verbs that answer about ONE.
+ *
+ * Returns the distinct best-tier candidates when MORE THAN ONE survives, else null. The asymmetry it
+ * closes is the whole defect: `path` and `impact` ALREADY refuse at exit 2 when ZERO functions match —
+ * only MANY was answered silently, by taking `targets[0]` and printing a confident verdict about a
+ * function the caller did not ask about. Measured in candor-java on `auth-2.25.60`: `path
+ * resolveCredentials Exec` had FOURTEEN dot-anchored candidates and answered a confident negative about
+ * `AnonymousCredentialsProvider` while three of the fourteen perform `Exec`. A negative is a claim in
+ * this family; a negative about a substituted subject is a fabricated one.
+ *
+ * Anchoring is NOT this function's job and is already done: `matchTier` requires a `[.$#]` boundary
+ * before a suffix match (tier 2), so `ProfileCredentialsProvider` never matches inside
+ * `InstanceProfileCredentialsProvider` — that half of R497 is what candor-ts already had, and it is why
+ * an EXACT match (tier 3) still resolves alone and is never counted as ambiguity.
+ *
+ * DISTINCT names, because the verbs resolve over the union of the callgraph's keys and the report's
+ * `fn`s and one function is routinely in both — a duplicate is one subject, not two.
+ */
+export function ambiguousSelector(names, q) {
+  const m = [...new Set(matches(names, q))].sort(byCodePoint);
+  return m.length > 1 ? m : null;
+}
+
 // Exported for consumers that answer MANY caller-count questions over one loaded graph (the LSP
 // codeLens): building the inversion once per request instead of once per `callers()` call.
 export function reverseGraph(cg) {
@@ -1599,6 +1626,11 @@ export function callersFrontier(cg, fns, hierarchy, q) {
   const possible = [];
   for (const f of fns) {
     if (confirmed.has(f.fn)) continue;
+    // ⟨0.39⟩: a synthetic `interfaceUnion` entry is the union over an abstraction member's implementors,
+    // not a function with a body — it cannot CALL anything, so it is not a possible caller. Un-gating
+    // ⟨0.23⟩ made these default rather than opt-in, and this arm then named the bodiless DECLARATION
+    // beside the dispatcher. Found by the four-way frontier differential on (producer=java, consumer=ts).
+    if (f.interfaceUnion) continue;
     const hits = new Set();
     for (const w of f.unknownWhy ?? []) {
       if (!w.startsWith("dispatch:")) continue;

package/query.mjs

@@ -27,7 +27,7 @@ import { parsePolicy, scopeMatches, discoverConfigPolicy, parseUnknownAliases, d
          evaluatePolicy, reportNetClasses, resolveReasonClasses, discoverConfigPath,
          policyVocabularyAnchor, policyErrorText, policyRefusalUnevaluated, policyUnreadable, policyZeroRules,
          fatalPolicyErrors, refusalVerdict, sortViolations,
-         unanswerableScoped, wholePolicyUnanswerable, reportUnits } from "./policy.mjs";
+         unanswerableScoped, wholePolicyUnanswerable, reportUnits, noteSyntheticHits } from "./policy.mjs";
 import { hasReport, refusalMarkerFor, refusalSentence } from "./query-core.mjs";
 import { printAgents, writeStdoutSync, writeSinkAtomic, isCandorConfigSink } from "./contract.mjs";
 import { bestFinds } from "./surface.mjs";
@@ -42,7 +42,7 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
          fix as coreFix, fixGate as coreFixGate, unverified as coreUnverified,
-         matches as coreMatches, gainsCoverage, gainsCompletenessFields, parseClassFilter, ClassFilterError,
+         matches as coreMatches, ambiguousSelector, gainsCoverage, gainsCompletenessFields, parseClassFilter, ClassFilterError,
          loadReport, loadCallgraph, reportCallsGraph, loadGateReport, gateReportInputFiles,
          reportVersion, reportPackage,
          advisoryAnswer,
@@ -679,6 +679,19 @@ function renderPathHuman(fns, cg, fnQ, eff, hedge = false) {
     console.error(`candor-query path: no function matching '${fnQ}'`);
     process.exit(2);
   }
+  // SOUNDNESS R507 — the human renderer's OWN resolution, refused on the same condition. The gate in the
+  // `path` case above resolves over the UNION of the callgraph keys and the report's `fn`s; this one
+  // resolves over the report alone, and the two name sets can put their best tier in different places
+  // (an exact callgraph key makes the union unambiguous while the report-only set still holds two
+  // suffix matches). Same helper, so the two cannot answer the question differently.
+  {
+    const ambH = ambiguousSelector(fns.map((e) => e.fn), fnQ);
+    if (ambH) {
+      console.error(`candor-ts-query path: '${fnQ}' names ${ambH.length} functions — refusing to answer `
+        + `about one of them. Re-run with the full name:\n  ${ambH.join("\n  ")}`);
+      process.exit(2);
+    }
+  }
   const startEntry = fns.find((e) => e.fn === start);
   const inferred = startEntry?.inferred ?? [];
   if (!inferred.includes(eff)) {
@@ -717,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.38";
+const SPEC_VERSION = "0.39";
 
 // ---- 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]
@@ -1725,6 +1738,20 @@ switch (cmd) {
     if (coreMatches(knownFnNames(impCg, impFns), q).length === 0) {
       console.error(`candor-ts-query impact: no function matching '${q}'`); process.exit(2);
     }
+    // SOUNDNESS R507, the same refusal on the verb that answers the OTHER direction — and here the
+    // substitution was HALF-hidden, which is worse than `path`'s. `coreImpact` walks the reverse graph
+    // from EVERY target (so `affectedCount` is a union over all of them) and then prints
+    // `fn: targets[0]`: a blast radius computed for several functions, attributed to one. A reader
+    // checking whether `save` is safe to change gets a count that may belong to a different `save`.
+    // See the `path` gate above for the asymmetry and for why one resolution decides both outcomes.
+    {
+      const amb = ambiguousSelector(knownFnNames(impCg, impFns), q);
+      if (amb) {
+        console.error(`candor-ts-query impact: '${q}' names ${amb.length} functions — refusing to answer `
+          + `about one of them. Re-run with the full name:\n  ${amb.join("\n  ")}`);
+        process.exit(2);
+      }
+    }
     // ⟨0.32⟩ `putAnswer`, not `put` — this verb had NO completeness reader at all (see `CALLERS_SOWHAT`
     // above for the measurement and the boundary). `affectedCount: 0` is the strongest claim in this
     // verb's vocabulary, and over a report whose own `excluded` names a class nothing opened it rests on
@@ -1995,6 +2022,27 @@ switch (cmd) {
     if (coreMatches(knownFnNames(cg, fns), fn).length === 0) {
       console.error(`candor-ts-query path: no function matching '${fn}'`); process.exit(2);
     }
+    // SOUNDNESS R507 — …AND THE OTHER HALF OF THE SAME RESOLUTION: MANY. Note the asymmetry that IS the
+    // defect: this verb has refused at exit 2 for ZERO matches for a long time (the gate directly above),
+    // while SEVERAL matches were answered silently — `targets[0]`, an arbitrary one, printed as a
+    // confident verdict about a function the caller never named. Measured in candor-java on
+    // `auth-2.25.60`: `path resolveCredentials Exec` had FOURTEEN anchored candidates and returned a
+    // confident negative about `AnonymousCredentialsProvider` while three of the fourteen perform `Exec`.
+    // A negative is a claim in this family, so a negative about a substituted subject is a fabricated one
+    // — strictly worse than unhelpful.
+    //
+    // ONE RESOLUTION, TWO OUTCOMES: the same `knownFnNames` set and the same `matches` ladder decide
+    // zero and many, so the two cannot drift apart the way a second, parallel check would. Anchoring is
+    // already in `matchTier` (this engine has always had R497's first half), so an EXACT match resolves
+    // alone and is never refused.
+    {
+      const amb = ambiguousSelector(knownFnNames(cg, fns), fn);
+      if (amb) {
+        console.error(`candor-ts-query path: '${fn}' names ${amb.length} functions — refusing to answer `
+          + `about one of them. Re-run with the full name:\n  ${amb.join("\n  ")}`);
+        process.exit(2);
+      }
+    }
     // ⟨0.32⟩ THE COMPLETENESS READER THIS VERB DID NOT HAVE (see `PATH_SOWHAT` above). `path: []` is the
     // determined negative here — *this function does not reach that effect* — and a hop through an unread
     // unit BREAKS the chain, so a hedging report can produce that answer for a function that really does
@@ -2500,6 +2548,8 @@ switch (cmd) {
     // fire AS-EFF-008 "no visible literal" on every report entry whose surface the wire does not carry.
     const gviol = evaluatePolicy(gwp.answerable,
                                  g.functions, {}, new Map(), new Set(), gnet, gwithhold, gunits);
+    // ⟨0.39⟩ see scan.mjs's twin — one printer, both verdict routes.
+    noteSyntheticHits(gviol);
     // Route the human output exactly as a scan does: to stderr whenever stdout carries the verdict
     // document, so `candor-ts-query gate … --json | jq` sees pure JSON.
     const gsay = (json || gateJsonPath === "-") ? (l) => console.error(l) : (l) => console.log(l);