candor-ts 0.8.4 → 0.8.5

package/mcp.mjs

@@ -162,12 +162,14 @@ const TOOLS = {
   candor_diff: {
     description: "The per-function effect delta versus a baseline report: gained (introduced vs inherited) and lost effects. 'What did this change do to the effect surface?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => Q.diff(Q.loadReport(p), Q.loadReport(a.baseline)),
+    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
+                      ...Q.diff(Q.loadReport(p), Q.loadReport(a.baseline)) }),
   },
   candor_gains: {
     description: "The supply-chain alarm: effects the surface GAINED versus a baseline (package-level + per-function) — 'did this dependency bump add Net/Exec somewhere?'.",
     schema: { type: "object", properties: { baseline: { type: "string", description: "the baseline report prefix" }, ...reportArg }, required: ["baseline"] },
-    run: (a, p) => Q.gains(Q.loadReport(p), Q.loadReport(a.baseline)),
+    run: (a, p) => ({ baseline_version: Q.reportVersion(a.baseline) ?? "", engine_version: Q.reportVersion(p) ?? "",
+                      ...Q.gains(Q.loadReport(p), Q.loadReport(a.baseline)) }),
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "candor for TypeScript \u2014 per-function side effects, transitively, with a policy gate (candor-spec 0.8)",
   "type": "module",
   "dependencies": {

package/query-core.mjs

@@ -55,6 +55,21 @@ function normFns(parsed, source) {
   return out;
 }
 
+/** The producing engine build of the report(s) at a prefix (the §2.1 envelope `candor.version`) — null
+ *  when unreadable/absent (a legacy bare array has no provenance). Baselines are comparable only to
+ *  their own producing version (§2.1): diff/gains consumers disclose a mismatch (an engine swap makes
+ *  "gained" effects ambiguous — unmasking vs regression — the baseline-invalidation rule, AGENTS §2a). */
+export function reportVersion(prefix) {
+  const files = fs.existsSync(`${prefix}.json`) ? [`${prefix}.json`] : siblings(prefix, isReport);
+  for (const f of files) {
+    try {
+      const v = JSON.parse(fs.readFileSync(f, "utf8"))?.candor?.version;
+      if (v) return String(v);
+    } catch { /* unreadable sibling — keep looking */ }
+  }
+  return null;
+}
+
 export function loadReport(prefix) {
   if (fs.existsSync(`${prefix}.json`)) {
     // The PRIMARY report parse must DISCLOSE-and-tolerate like the sibling path — a bare JSON.parse here

package/query.mjs

@@ -30,7 +30,7 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          show as coreShow, blindspots as coreBlindspots,
          callers as coreCallers, callersFrontier, loadHierarchy,
          containment as coreContainment,
-         loadReport, loadCallgraph, matches } from "./query-core.mjs";
+         loadReport, loadCallgraph, matches , reportVersion } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 
 // ONE version + spec source, the SAME way scan.mjs reads them: PKG_VERSION is the bare semver from
@@ -180,8 +180,19 @@ switch (cmd) {
       if (gained.length || lost.length) changes.push({ fn, gained, lost });
     }
     changes.sort((a, b) => a.fn.localeCompare(b.fn));
-    emit({ changes });
-    process.exit(changes.some((c) => c.gained.length) ? 1 : 0);
+    // §2.1: a baseline is comparable only to its own producing build — disclose a mismatch (the gains
+    // may be the engine reclassifying after a coverage batch, not the code changing). Same note + JSON
+    // provenance fields as the Rust candor-query (cross-engine parity, item 10).
+    const engineV = reportVersion(curPrefix), baseV = reportVersion(basePrefix);
+    const versionMismatch = engineV && baseV && engineV !== baseV;
+    if (versionMismatch)
+      console.error(`candor-ts: ⚠ baseline @${baseV} ≠ engine @${engineV} — some changes may be the engine reclassifying, not your code. Treat an engine swap as baseline-invalidating: review, then regenerate the baseline.`);
+    emit({ baseline_version: baseV ?? "", engine_version: engineV ?? "", changes });
+    // diff DISCLOSES (the posture) — it is not a gate. Its gained-effect exit 1 is a convenience for
+    // same-build ratchet use; under a version mismatch that signal is BOGUS (unmasking, not regression),
+    // so exit 0 and let the ⚠ inform — never deliver the wave as a CI failure (review §2.1: guards fail
+    // closed, queries disclose).
+    process.exit(!versionMismatch && changes.some((c) => c.gained.length) ? 1 : 0);
     break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
   case "reachable": {
@@ -215,7 +226,10 @@ switch (cmd) {
     // the supply-chain alarm (SPEC §5.1): {gained:[Effect], byFunction:[{fn,effect}]} — what the
     // surface gained between two reports (base → cur), the cross-engine machine-readable form.
     const [curPrefix, basePrefix] = args;
-    emit(coreGains(loadReport(curPrefix), loadReport(basePrefix)));
+    const gv = reportVersion(curPrefix), gbv = reportVersion(basePrefix);
+    if (gv && gbv && gv !== gbv)
+      console.error(`candor-ts: ⚠ baseline @${gbv} ≠ engine @${gv} — a "gained capability" may be the engine reclassifying, not the dependency changing. Regenerate both reports with one build to compare releases.`);
+    emit({ baseline_version: gbv ?? "", engine_version: gv ?? "", ...coreGains(loadReport(curPrefix), loadReport(basePrefix)) });
     break;
   }
   case "path": {