candor-ts 0.25.0 → 0.26.0

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.25)."*
+> plainly which version they're on** — e.g. *"This project is on candor-ts `<version>` (spec 0.26)."*
 > 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

@@ -192,7 +192,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.25" }, functions }` envelope; pure fns omitted | SPEC §2/§2.1 |
+| `{ candor: { version, toolchain, spec: "0.26" }, 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 |
 
@@ -210,7 +210,7 @@ read the Rust source".
 
 ## Status
 
-0.19.x, speaking candor-spec 0.25: the analysis core, the gate (`--policy` / `--gate-json` /
+0.19.x, speaking candor-spec 0.26: 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,7 +1,7 @@
 {
   "name": "candor-ts",
-  "version": "0.25.0",
-  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.25)",
+  "version": "0.26.0",
+  "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.26)",
   "type": "module",
   "dependencies": {
     "@types/node": "^25.9.2",

package/query-core.mjs

@@ -696,13 +696,37 @@ export const byCodePoint = (a, b) => {
 };
 
 // Reflexive+transitive subtype test over the hierarchy sidecar.
-function isSubtypeOf(type, owner, hierarchy) {
-  if (type === owner) return true;
+//
+// ⟨0.26⟩ THREE-VALUED, because the format now distinguishes what it could not before. SPEC §2.2 makes the
+// KEY SET the manifest: a producer emits a key for every type it indexed, `[]` included, so a type with NO
+// key is one the pass never looked at. `hierarchy[t] ?? []` read those two cases alike and answered
+// `false` — a positive claim about a type nobody analysed.
+//
+// MEASURED before the rung, doctoring only the sidecar of a real scan: removing the REACHING implementor's
+// entry silently dropped the dispatcher from `possibleViaUnknownDispatch` (`[]` where the control gives
+// `[Dispatcher.run]`), while removing the sidecar ENTIRELY left it correct — the ⟨0.24⟩ per-file rule
+// over-lists. LESS information was SAFER than partial information. candor-java behaved identically, which
+// is what said the defect was the FORMAT rather than either consumer.
+//
+// A POSITIVE DOMINATES: if a known path reaches `owner` the answer is YES even when another branch ran
+// into an unindexed type — the relation is established and an unknown branch cannot un-establish it. NO is
+// reserved for a walk that stayed entirely inside types the sidecar answers for.
+function subtypeOf(type, owner, hierarchy) {
+  if (type === owner) return "YES";
+  let sawUnindexed = false;
   const seen = new Set(), stack = [type];
   while (stack.length) {
-    for (const s of hierarchy[stack.pop()] ?? []) { if (s === owner) return true; if (!seen.has(s)) { seen.add(s); stack.push(s); } }
+    const cur = stack.pop();
+    if (!Object.prototype.hasOwnProperty.call(hierarchy, cur)) { sawUnindexed = true; continue; }
+    for (const s of hierarchy[cur]) { if (s === owner) return "YES"; if (!seen.has(s)) { seen.add(s); stack.push(s); } }
   }
-  return false;
+  return sawUnindexed ? "UNANSWERABLE" : "NO";
+}
+
+// The two-valued form. UNANSWERABLE collapses to TRUE — disclose, never drop — which is the direction
+// §2.2 ⟨0.26⟩ requires and the opposite of what absence used to do.
+function isSubtypeOf(type, owner, hierarchy) {
+  return subtypeOf(type, owner, hierarchy) !== "NO";
 }
 
 // callers + the unresolved-dispatch frontier (--include-unknown, SPEC §3.1/§4 0.7): the CONFIRMED set,
@@ -1236,7 +1260,7 @@ export function narrowingContext(fns, cg = {}, policyParsed = null) {
           const u = byRaw.get(r.raw);
           if (!u) continue;                                  // unreachable: every held triple has a group
           const cur = heldByFn.get(f.fn) ?? new Map();
-          cur.set(`${r.raw}${eff}`, { fn: f.fn, rule: r.raw, effect: eff, why: u.why });
+          cur.set(`${r.raw}\0${eff}`, { fn: f.fn, rule: r.raw, effect: eff, why: u.why });
           heldByFn.set(f.fn, cur);
         }
   return {

package/query.mjs

@@ -232,7 +232,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
 // 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.25";
+const SPEC_VERSION = "0.26";
 
 // ---- 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.mjs

@@ -44,7 +44,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.25";
+const SPEC_VERSION = "0.26";
 
 // --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
@@ -4371,9 +4371,13 @@ for (const [name, rec] of fns) {
     hash: `${pkgName}#${rec.local}`, // SPEC §2: the cross-package join key (package + local tail)
     inferred: inf,
     direct: [...rec.direct].sort(),
-    declared: [],
-    undeclared: [],
-    overdeclared: [],
+    // ⟨0.26⟩ `declared`/`undeclared`/`overdeclared` are DELIBERATELY ABSENT. They are the §5
+    // capability-reconciliation outputs and this engine runs no such pass, so emitting `[]` would be a
+    // positive claim — `undeclared: []` reads as "this function performs no undeclared effect", an
+    // AS-EFF-001 all-clear from a check that never ran. SPEC §2 ⟨0.26⟩: present means the pass ran,
+    // absent means it did not, and `[]` from an engine that computed nothing is forbidden.
+    // They were emitted as hardcoded constants "for cross-engine schema parity" — a schema-parity check
+    // is exactly what made that look conforming, which is why the rule now forbids requiring them.
     unresolved: inf.includes("Unknown"),
   };
   // Inline call edges (§2 `calls`) — the SAME edges the callgraph sidecar carries, embedded per entry so a
@@ -4909,7 +4913,13 @@ for (const sf of sources) {
           supers.push(d && d.name ? `${moduleOf(d.getSourceFile())}.${namespacePrefixOf(d)}${d.name.getText()}` : t.expression.getText());
         }
       }
-      if (supers.length) hierarchy[`${mod}.${namespacePrefixOf(node)}${node.name.getText()}`] = supers;
+      // ⟨0.26⟩ A KEY FOR EVERY TYPE INDEXED, `[]` INCLUDED — the key set IS the manifest (SPEC §2.2).
+      // This was `if (supers.length)`, so a type with no supertypes was OMITTED and absence meant BOTH
+      // "no supertypes" and "never indexed". Measured: removing one entry from a real sidecar silently
+      // dropped a `callers --include-unknown` frontier row, while removing the sidecar ENTIRELY left it
+      // correct — so LESS information was SAFER than partial information. §2.2's own example has always
+      // shown `"app.Base": []`; this producer contradicted it.
+      hierarchy[`${mod}.${namespacePrefixOf(node)}${node.name.getText()}`] = supers;
     }
     ts.forEachChild(node, walk);
   })(sf);