coderifts 8.2.0 → 8.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 8.3.0 - 2026-09-05
+
+### Changed
+- `@coderifts/agent-guard` range raised to `^17.1.0`. Guard 17.1.0 fixes the audience binding (the Guard now sends top-level `audience`, which the server actually reads) and makes its public suite hermetic. No CLI behaviour change beyond the installed guard minor.
+
+
 ## 8.2.0 - 2026-09-05
 
 ### Changed

package/bin/coderifts.js

@@ -52,6 +52,19 @@ program
 // Exit status is set only at this command boundary (library never process.exit).
 // program.parse() does not await async actions; process.exit here makes the gate's
 // fail-closed status authoritative for npm prepublishOnly / child_process callers.
+// ── doctor (1222) — the adoption entry point ──
+// Tier 0 needs no key and calls no model; Tier 1 is BYOK on the developer's own machine.
+program
+  .command('doctor')
+  .description('Would an agent select CodeRifts for a contract change? Structural check (no key), or the 15-fixture benchmark on your own model.')
+  .option('--tools <file>', 'Your host\'s tools/list response (array, { tools }, or { result: { tools } })')
+  .option('--model <id>', 'TIER 1: run the fixtures through this model using YOUR key from the environment')
+  .option('--mock', 'TIER 1 dry run: a deterministic scripted model. Measures the script, not a model.')
+  .action(async (options) => {
+    const { runDoctor } = require('../src/commands/doctor');
+    await runDoctor(options);
+  });
+
 program
   .command('publish-gate')
   .description('Gate npm publish on contract-artifact preflight (before=git baseline, after=working tree)')

package/dist/.build-source-sha

@@ -1,5 +1,5 @@
 {
   "$comment": "GENERATED by scripts/build.js. sha256 over src/**.js + bin/**.js (path + bytes). test/build-freshness.test.js recomputes it; a mismatch means dist/cli.js is stale.",
-  "sha256": "d9d48f2b01fa76855978dbbaa67d81be419b7632e1cc80eb5b999d5efcf9c090",
-  "file_count": 42
+  "sha256": "9596f98c3c463ea53896621305484fd1ca3c5685b15c410fa4205c07a285c709",
+  "file_count": 44
 }

package/dist/cli.js

@@ -3028,7 +3028,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "coderifts",
-      version: "8.2.0",
+      version: "8.3.0",
       description: "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
       author: "CodeRifts <hello@coderifts.com>",
       license: "MIT",
@@ -3074,7 +3074,7 @@ var require_package = __commonJS({
         test: "node --test test/*.test.js"
       },
       dependencies: {
-        "@coderifts/agent-guard": "^17.0.0",
+        "@coderifts/agent-guard": "^17.1.0",
         chalk: "^4.1.2",
         "cli-table3": "^0.6.4",
         commander: "^12.0.0",
@@ -71328,7 +71328,21 @@ These feed DIFFERENT halves of the system \u2014 the top level binds the ATOMIC
       ["target_uri", "targetUri"],
       ["tenant_id", "tenantId"],
       ["policy_hash", "policyHash"],
-      ["audience_hash", "audienceHash"],
+      // 1402 — `audience_hash` IS NOT ON THIS LIST, and its absence is the fix.
+      //
+      // MEASURED 2026-09-06 against the server, read-only:
+      //   src/change-set.js:1138            reads TOP-LEVEL `input.audience`, strict /^v:[0-9a-f]{12}$/
+      //   execution-grant-v2.js:166         derives `audience_hash: sha256pref(audience)` ITSELF
+      //   execution-grant-request.v2.producer.json  states it outright: "`audience_hash` is NOT a
+      //                                     request field of its own … sending it separately has no
+      //                                     effect and it stays out of this schema"
+      //
+      // So the Guard was sending a field nobody reads. Worse, it was ALSO sending the audience under
+      // `context.audience`, which the handler does not read either (it reads `input.audience`) — both
+      // channels were severed, and the binding a host configured reached the server through neither.
+      // A field that looks bound and is not is the exact failure the server's own 1206 note describes.
+      //
+      // The fix is to send what the server consumes: top-level `audience`. See guard.ts.
       ["expected_state_token", "expectedStateToken"]
     ]);
     function v2WireFields(config) {
@@ -71872,6 +71886,17 @@ var require_guard = __commonJS({
         previous_receipt: resolvePreviousReceipt(config),
         idempotency_key: void 0
       };
+      if (typeof config.audience === "string" && config.audience.length > 0) {
+        if (/^v:[0-9a-f]{12}$/.test(config.audience)) {
+          request.audience = config.audience;
+        } else {
+          emit(config, {
+            type: "audience_not_bindable",
+            at: iso(),
+            cause: `audience ${JSON.stringify(config.audience)} is not the measured v:<12 hex> form; the server discards any other string to null, so it would NOT be bound. Nothing was sent for it.`
+          });
+        }
+      }
       let grantObs;
       let grantForCall = null;
       if ((0, execution_grant_js_1.isExecutionGrantEnabled)(config)) {
@@ -230166,6 +230191,272 @@ var require_deploy_gate2 = __commonJS({
   }
 });
 
+// src/doctor.js
+var require_doctor = __commonJS({
+  "src/doctor.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    function harness() {
+      return require(path.join(__dirname, "..", "..", "..", "benchmark", "tool-selection-benchmark.js"));
+    }
+    var PREFLIGHT = "preflight_change_set";
+    function bare(name) {
+      return String(name == null ? "" : name).replace(/^coderifts\./, "");
+    }
+    function parseToolsDocument(doc) {
+      if (Array.isArray(doc)) return { ok: true, tools: doc };
+      if (doc && Array.isArray(doc.tools)) return { ok: true, tools: doc.tools };
+      if (doc && doc.result && Array.isArray(doc.result.tools)) return { ok: true, tools: doc.result.tools };
+      return {
+        ok: false,
+        why: "expected a tools/list response \u2014 an array, { tools: [...] }, or { result: { tools: [...] } }"
+      };
+    }
+    function descriptionOf(t) {
+      return typeof t.description === "string" ? t.description : "";
+    }
+    function schemaOf(t) {
+      return t.inputSchema || t.input_schema || t.parameters || void 0;
+    }
+    function signalPreflightPresent(tools) {
+      const hit = tools.find((t) => bare(t.name) === PREFLIGHT);
+      return hit ? { ok: true, detail: `\`${bare(hit.name)}\` is in the table` } : {
+        ok: false,
+        detail: `no \`${PREFLIGHT}\` tool in the table \u2014 nothing to select for a contract change`,
+        fix: "coderifts agent-setup"
+      };
+    }
+    function signalDescriptionMatchesShipped(tools, shipped) {
+      const hit = tools.find((t) => bare(t.name) === PREFLIGHT);
+      if (!hit) return { ok: false, detail: "not applicable \u2014 no preflight tool", fix: "coderifts agent-setup" };
+      const ship = shipped.find((t) => bare(t.name) === PREFLIGHT);
+      if (!ship) return { ok: false, detail: "the shipped manifest carries no preflight tool to compare against" };
+      const mine = descriptionOf(hit).trim();
+      const theirs = descriptionOf(ship).trim();
+      if (mine === theirs) return { ok: true, detail: "description is byte-identical to the shipped text" };
+      const pct = theirs.length ? Math.round(mine.length / theirs.length * 100) : 0;
+      return {
+        ok: false,
+        detail: `description DRIFTED from the shipped text (${mine.length} vs ${theirs.length} chars, ${pct}%) \u2014 the model reads this to decide, so a shortened or stale copy changes selection`,
+        fix: "coderifts agent-setup --force"
+      };
+    }
+    function signalSchemaValid(tools, h) {
+      const checks = [];
+      const attempt = (label, fn, arg) => {
+        try {
+          fn(arg);
+          checks.push({ label, ok: true });
+        } catch (err) {
+          checks.push({ label, ok: false, why: err && err.message || "rejected" });
+        }
+      };
+      const anthropicShape = tools.map((t) => ({ name: bare(t.name), description: descriptionOf(t), input_schema: schemaOf(t) }));
+      if (typeof h.validateAnthropicTools === "function") attempt("anthropic", h.validateAnthropicTools, anthropicShape.map(h.toAnthropicTool || ((x) => x)));
+      if (typeof h.validateOpenAITools === "function") attempt("openai", h.validateOpenAITools, anthropicShape.map(h.toOpenAITool || ((x) => x)));
+      if (typeof h.validateGoogleTools === "function") attempt("google", h.validateGoogleTools, anthropicShape.map(h.toGoogleFunctionDeclaration || ((x) => x)));
+      const bad = checks.filter((c) => !c.ok);
+      return bad.length === 0 ? { ok: true, detail: `accepted by ${checks.map((c) => c.label).join(", ") || "(no validator available)"}` } : {
+        ok: false,
+        detail: `rejected by ${bad.map((c) => `${c.label} (${c.why})`).join("; ")}`,
+        fix: "coderifts agent-setup --force"
+      };
+    }
+    var RIVAL_HINTS = ["breaking", "openapi", "contract", "api diff", "api change", "schema diff"];
+    function signalNoAbsorbingRival(tools, shipped = []) {
+      const own = new Set(shipped.map((t) => bare(t.name)));
+      const rivals = tools.filter((t) => bare(t.name) !== PREFLIGHT && !own.has(bare(t.name))).filter((t) => {
+        const text = `${bare(t.name)} ${descriptionOf(t)}`.toLowerCase();
+        return RIVAL_HINTS.some((h) => text.includes(h));
+      }).map((t) => bare(t.name));
+      return rivals.length === 0 ? { ok: true, detail: "no other tool advertises contract-change checking" } : {
+        ok: false,
+        warning: true,
+        detail: `${rivals.length} other tool(s) advertise contract-change work and may absorb the call: ` + rivals.join(", ") + " \u2014 Tier 1 measures whether they actually do",
+        fix: null
+      };
+    }
+    function tier0(tools) {
+      const h = harness();
+      const shipped = h.getCanonicalTools();
+      const signals = [
+        { id: "preflight_present", ...signalPreflightPresent(tools) },
+        { id: "description_matches_shipped", ...signalDescriptionMatchesShipped(tools, shipped) },
+        { id: "schema_valid", ...signalSchemaValid(tools, h) },
+        { id: "no_absorbing_rival", ...signalNoAbsorbingRival(tools, shipped) }
+      ];
+      const blocking = signals.filter((s) => !s.ok && !s.warning);
+      return {
+        tier: 0,
+        tool_count: tools.length,
+        signals,
+        passed: signals.filter((s) => s.ok).length,
+        total: signals.length,
+        blocking: blocking.length,
+        fixes: [...new Set(signals.filter((s) => !s.ok && s.fix).map((s) => s.fix))]
+      };
+    }
+    var DOES_NOT_PROVE = Object.freeze({
+      0: [
+        "that your model WOULD select CodeRifts \u2014 Tier 0 is structural only, a necessary condition",
+        "that a change reached a merge/deploy/publish sink, or that any gate fired",
+        "anything about tools this file was not shown"
+      ],
+      1: [
+        "that a change reached a merge/deploy/publish sink \u2014 selection is not enforcement",
+        "anything about a model other than the one you ran, at the version you ran it",
+        "that your production prompt behaves like the harness prompt"
+      ]
+    });
+    module2.exports = {
+      parseToolsDocument,
+      tier0,
+      harness,
+      bare,
+      DOES_NOT_PROVE,
+      PREFLIGHT,
+      signalPreflightPresent,
+      signalDescriptionMatchesShipped,
+      signalSchemaValid,
+      signalNoAbsorbingRival
+    };
+  }
+});
+
+// src/commands/doctor.js
+var require_doctor2 = __commonJS({
+  "src/commands/doctor.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var chalk = require_source();
+    var {
+      parseToolsDocument,
+      tier0,
+      harness,
+      DOES_NOT_PROVE
+    } = require_doctor();
+    function readToolsFile(file) {
+      const resolved = path.resolve(file);
+      if (!fs.existsSync(resolved)) return { ok: false, why: `no such file: ${file}` };
+      let doc;
+      try {
+        doc = JSON.parse(fs.readFileSync(resolved, "utf8"));
+      } catch (err) {
+        return { ok: false, why: `not JSON: ${err && err.message || "parse error"}` };
+      }
+      return parseToolsDocument(doc);
+    }
+    function printBoundary(tier, log) {
+      log("");
+      log(chalk.bold("  WHAT THIS DOES NOT PROVE"));
+      for (const line of DOES_NOT_PROVE[tier]) log(chalk.dim(`    \xB7 ${line}`));
+    }
+    function renderTier0(r, log) {
+      log("");
+      log(chalk.bold(`  coderifts doctor \u2014 structural fitness (${r.tool_count} tools, no model called)`));
+      log("");
+      for (const s of r.signals) {
+        const mark = s.ok ? chalk.green("  ok  ") : s.warning ? chalk.yellow("  !!  ") : chalk.red("  X   ");
+        log(`${mark}${s.id}`);
+        log(chalk.dim(`        ${s.detail}`));
+      }
+      log("");
+      const verdict = r.blocking === 0 ? chalk.green(`  structurally fit to be selected: ${r.passed}/${r.total} signals`) : chalk.red(`  NOT structurally fit: ${r.blocking} blocking signal(s), ${r.passed}/${r.total} passed`);
+      log(verdict);
+      if (r.fixes.length) {
+        log("");
+        log(chalk.bold("  NEXT COMMAND"));
+        for (const f of r.fixes) log(`    ${chalk.cyan(f)}`);
+      }
+      log("");
+      log(chalk.dim("  Tier 0 is the NECESSARY condition, not selectability. To measure whether your"));
+      log(chalk.dim("  model actually selects, run the 15 fixtures on your own key:"));
+      log(chalk.dim("    coderifts doctor --tools <file> --model <model-id>"));
+    }
+    async function runTier1({ tools, model, log, mock }) {
+      const h = harness();
+      const fixtures = h.loadSelectionFixtures();
+      log("");
+      log(chalk.bold(`  coderifts doctor \u2014 selection benchmark (${fixtures.length} fixtures, model ${model})`));
+      let client;
+      if (mock) {
+        client = new h.MockClient(h.perfectScript());
+        log(chalk.yellow("  MOCK RUN \u2014 a scripted model that answers perfectly by construction."));
+        log(chalk.yellow("  This measures the script. It is not a measurement of any model."));
+      } else {
+        const provider = h.PROVIDERS && Object.keys(h.PROVIDERS).find((p) => String(model).toLowerCase().includes(p));
+        const factory = provider === "openai" ? h.createOpenAIClient : provider === "google" ? h.createGoogleClient : provider === "xai" ? h.createXaiClient : h.createAnthropicClient;
+        const envVar = provider === "openai" ? "OPENAI_API_KEY" : provider === "google" ? "GOOGLE_API_KEY" : provider === "xai" ? "XAI_API_KEY" : "ANTHROPIC_API_KEY";
+        const key = process.env[envVar];
+        if (!key) {
+          log("");
+          log(chalk.red(`  ${envVar} is not set.`));
+          log(chalk.dim("  Tier 1 runs on YOUR key, on YOUR machine. CodeRifts never sees it, and"));
+          log(chalk.dim("  never pays for the run. Export the key and re-run, or use --mock for a"));
+          log(chalk.dim("  no-cost dry run of the harness path."));
+          return { ok: false, reason: "missing_key" };
+        }
+        client = factory({ apiKey: key, model });
+      }
+      const userNames = new Set(tools.map((t) => String(t.name || "").replace(/^coderifts\./, "")));
+      const withUserTable = fixtures.map((f) => ({
+        ...f,
+        available_tools: f.available_tools.filter((n) => userNames.has(String(n).replace(/^coderifts\./, "")))
+      }));
+      const unreachable = withUserTable.filter((f) => f.available_tools.length === 0).length;
+      if (unreachable) {
+        log(chalk.yellow(`  ${unreachable} fixture(s) have no matching tool in your table \u2014 they can only score as a miss.`));
+      }
+      const unanswerable = withUserTable.filter((f) => {
+        const want = String(f.expected_tool || "").replace(/^coderifts\./, "");
+        return want && want !== "none" && !userNames.has(want);
+      }).map((f) => f.id);
+      if (unanswerable.length) {
+        log(chalk.yellow(`  ${unanswerable.length} fixture(s) expect a tool your table does not offer (${unanswerable.join(", ")}) \u2014 they CANNOT score correct. That is your table, not your model.`));
+      }
+      const run = await h.runBenchmark({ modelId: model, client, fixtures: withUserTable });
+      const m = run && run.metrics ? run.metrics : h.computeMetrics(run.results || []);
+      log("");
+      for (const k of ["selection_coverage", "bypass_rate", "omission_rate", "wrong_tool_rate", "overall_accuracy"]) {
+        if (m[k] !== void 0) log(`    ${String(k).padEnd(20)} ${m[k]}`);
+      }
+      return { ok: true, metrics: m };
+    }
+    async function runDoctor(options = {}) {
+      const log = options.logFn || ((s) => process.stdout.write(`${s}
+`));
+      const exitFn = options.exitFn || ((c) => process.exit(c));
+      if (!options.tools) {
+        log(chalk.red("  --tools <file> is required: the tools/list your host actually serves."));
+        log(chalk.dim(`    Save it with your MCP client, or: curl .../mcp -d '{"method":"tools/list"}' > tools.json`));
+        exitFn(2);
+        return { exitCode: 2 };
+      }
+      const parsed = readToolsFile(options.tools);
+      if (!parsed.ok) {
+        log(chalk.red(`  could not read the tool table: ${parsed.why}`));
+        exitFn(2);
+        return { exitCode: 2 };
+      }
+      if (options.model) {
+        const r = await runTier1({ tools: parsed.tools, model: options.model, log, mock: !!options.mock });
+        printBoundary(1, log);
+        const code = r.ok ? 0 : 1;
+        exitFn(code);
+        return { exitCode: code, tier: 1, metrics: r.metrics };
+      }
+      const report = tier0(parsed.tools);
+      renderTier0(report, log);
+      printBoundary(0, log);
+      exitFn(0);
+      return { exitCode: 0, tier: 0, report };
+    }
+    module2.exports = { runDoctor, readToolsFile, renderTier0, printBoundary };
+  }
+});
+
 // src/commands/publish-gate.js
 var require_publish_gate = __commonJS({
   "src/commands/publish-gate.js"(exports2, module2) {
@@ -264666,6 +264957,10 @@ program.command("deploy-gate").description("Gate a deploy on the current { envir
   const { runDeployGate } = require_deploy_gate2();
   await runDeployGate(options);
 });
+program.command("doctor").description("Would an agent select CodeRifts for a contract change? Structural check (no key), or the 15-fixture benchmark on your own model.").option("--tools <file>", "Your host's tools/list response (array, { tools }, or { result: { tools } })").option("--model <id>", "TIER 1: run the fixtures through this model using YOUR key from the environment").option("--mock", "TIER 1 dry run: a deterministic scripted model. Measures the script, not a model.").action(async (options) => {
+  const { runDoctor } = require_doctor2();
+  await runDoctor(options);
+});
 program.command("publish-gate").description("Gate npm publish on contract-artifact preflight (before=git baseline, after=working tree)").option("--spec <path>", "Contract artifact path (default: git config coderifts.specPath or api/openapi.yaml)").option("--json", "Machine-readable JSON result").action(async (options) => {
   const { runPublishGate } = require_publish_gate();
   const result = await runPublishGate(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderifts",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
   "author": "CodeRifts <hello@coderifts.com>",
   "license": "MIT",
@@ -46,7 +46,7 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@coderifts/agent-guard": "^17.0.0",
+    "@coderifts/agent-guard": "^17.1.0",
     "chalk": "^4.1.2",
     "cli-table3": "^0.6.4",
     "commander": "^12.0.0",