coderifts 4.12.0 → 5.0.1

package/package.json

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

package/scripts/assert-guard-major.js

@@ -15,13 +15,43 @@
  * 4.12.0: floor raised to 10 (ENFORCING_STRICT requires the execution chain — a strict
  *   composition that built under 9.x refuses to construct under 10.x, so a CLI that documents or
  *   scaffolds strict must not run against a guard with the older meaning).
+ * 4.13.0: floor raised to 11 (computeBundleFingerprint returned a WRONG digest in 10.x — it
+ *   omitted the artifact count and the whole context block, so on identical inputs it produced
+ *   sha256:1a0e7470… where the server produced sha256:049650f2…; 11.0.0 delegates to the single
+ *   canonical crbundle.v1 preimage and matches byte for byte. COST MEASURED AS ZERO, the same way
+ *   the 10-raise was: the CLI imports only deployGate, asVerifiedDeployReceiptView,
+ *   DEPLOY_RECEIPT_VIEW_SPEC and matchGlob, none of which 11.0.0 touched, and the suite staged
+ *   against 11.0.0 returned an identical 532/530/2 with a byte-identical failure set. The floor
+ *   rises anyway, because a semantics floor is about what the CLI may RUN against, not about what
+ *   it happens to import today — a fingerprint that disagrees with the server is exactly the class
+ *   of difference this gate exists to refuse.)
+ * 5.0.0: floor raised to 12 (requireConditionalWrite now FIRES on an ordinary mutation. Through
+ *   11.0.1 the policy gated on isWriteStyleCall, which answers "did the caller supply a both-sides
+ *   snapshot" — the right question for FRESHNESS, which it was written for, and the wrong one for
+ *   atomicity. So a mutation carrying artifacts[] with non-empty before AND after classified as
+ *   not-write-style and the demand never fired: reproduced against the published 11.0.1 tarball,
+ *   where the side effect RAN with enforced:true and conditional_write:"not_reported". It bites on
+ *   the NORMAL path, not an exotic config, because the tool-registry defaultBinder lifts
+ *   old_string/new_string and edits[] into exactly that shape — so an agent editing a contract
+ *   artifact under ENFORCING_STRICT wrote unconditionally. 12.0.0 adds isMutatingCall and gates on
+ *   it; ConditionalWriteBasis gains a required `mutating` field. COST MEASURED AS ZERO, the same
+ *   way the 11-raise was: the CLI imports only deployGate, asVerifiedDeployReceiptView,
+ *   DEPLOY_RECEIPT_VIEW_SPEC and matchGlob, whose implementing modules (deploy-gate.js,
+ *   resolver-glob.js, deploy-receipt-token.js) are BYTE-IDENTICAL 11.0.1 -> 12.0.0; the CLI
+ *   constructs no ConditionalWriteBasis and never sets requireConditionalWrite, so the one
+ *   type-level break cannot reach it — it is JS besides. Suite on 12.0.0: 556/554/2, identical to
+ *   11.0.0 with a byte-identical failure set; the only edits the raise needed were this gate's own
+ *   two value-pins in assert-guard-major-coverage.test.js, which exist to move with each recorded
+ *   raise, and no product code. The floor rises anyway, because a semantics floor is about
+ *   what the CLI may RUN against: a guard that silently skips the atomicity demand on an ordinary
+ *   edit is exactly the class of difference this gate exists to refuse.)
  */
 
 const fs = require('fs');
 const path = require('path');
 
 /** Minimum acceptable major for @coderifts/agent-guard in THIS package (the CLI). */
-const MIN_GUARD_MAJOR = 10;
+const MIN_GUARD_MAJOR = 12;
 const DEP = '@coderifts/agent-guard';
 
 /**
@@ -55,17 +85,54 @@ const CHECKOUTS = [
     /**
      * DELIBERATE, MEASURED, AND LOWER THAN THE CLI'S — recorded so it is a decision, not a default.
      *
-     * 2026-08-26: bumping the root to ^10 breaks three merge-gate tests. gateDecision under 10.0.0
-     * returns residuals: [] where the app expects 'required_check_app_not_bound'
-     * (test/mergegate-webhook.test.js: 46/46 on 3.0.0, 3 failures on 10.0.0). The app's own comment
-     * at webhook-integration.js:336-339 records why 3.x has been SAFE rather than merely unnoticed:
-     * the app ANDs three conditions so a stale package can never fail-open.
+     * 2026-08-26: bumping the root to ^10 breaks three merge-gate tests
+     * (test/mergegate-webhook.test.js: 46/46 on 3.0.0, 43/46 on 10.x). The app's own comment at
+     * webhook-integration.js:336-339 records why 3.x has been SAFE rather than merely unnoticed:
+     * the app ANDs three conditions (protection_inescapable && change_set_rebound && app_bound) so
+     * a stale package can never fail-open. That AND is load-bearing — measured against 3.0.0,
+     * gateDecision claims inescapable_merge:true even when required_check_app_bound is false or
+     * absent; the published claim is correct only because the app re-derives it.
      *
-     * So the floor is pinned at 3 to stop it drifting LOWER unnoticed, and raising it is a separate
-     * round that must first reconcile the residual vocabulary. Raise this number in that round and
-     * record the reason on the line below, in the style of the CLI history above.
+     * RE-MEASURED 2026-08-26 against 11.0.0, and TWO THINGS IN THE OLD NOTE WERE WRONG:
+     *
+     *  1. It said 10.0.0 "returns residuals: []". It does not. Given the correct input shape it
+     *     returns ['required_check_app_not_bound'] / ['required_check_app_binding_unknown'] — the
+     *     app's own vocabulary. The earlier reading passed protection.enforcement_state; the field
+     *     the gate reads is protection.enforcement, so the gate saw no protection at all.
+     *  2. The real difference is PRECEDENCE, not absence. The guard emits exactly ONE residual and
+     *     short-circuits on the enforcement gap, so where two gaps hold at once it reports
+     *     'admin_bypass_open' and the app expects 'required_check_app_binding_unknown'. The app's
+     *     collectBindingResiduals emits EVERY residual that holds — its docstring says so: "the
+     *     pure gate's published shape is a single honesty slot ... the second was suppressed".
+     *     That is why the app duplicates rather than consumes, and it is the whole reconciliation.
+     *
+     * 11.0.0 vs 10.0.0: NO CHANGE. Residual output is byte-identical across all three app-binding
+     * cases, and 11.0.0 touched only computeBundleFingerprint, which this path does not import. So
+     * 11 makes the bump neither easier nor harder — the blocker is unchanged and the deferral still
+     * holds for exactly the reason above, not for a residual shape that moved.
+     *
+     *
+     * WHAT THE RESOLVED-RANGE CHECK SAYS ABOUT THIS ENTRY: NOTHING, and that is the correct
+     * answer rather than a lucky one. The check added for the 5.0.0 finding grades whether the
+     * DECLARED range and the RESOLVED install AGREE. The root declares ^3.0.0 and resolves 3.0.0,
+     * so they agree exactly and it reports "in range". The root's gap is not drift between its
+     * manifest and its tree — it is a deliberately LOW FLOOR, and a floor is a human decision this
+     * gate records rather than derives. That decision lives in `floor: 3` and the reason above.
+     *
+     * A check that DID flag it — "resolved major must equal the newest published major" — was
+     * considered and rejected: it would force exactly the bump the paragraphs above say must not
+     * be forced before the residual-precedence reconciliation. The gate must not legislate a
+     * decision it is only supposed to remember.
+     * WHAT THE BUMP ROUND MUST DECIDE: whether the guard should emit all holding residuals (then
+     * the app consumes gateOut.residuals and collectBindingResiduals is deleted), or whether the
+     * single-slot shape is deliberate (then the app keeps its collector and the duplication is
+     * documented as intended rather than left looking accidental). Do not bump before that choice.
+     *
+     * So the floor is pinned at 3 to stop it drifting LOWER unnoticed. Raise this number in that
+     * round and record the reason on the line below, in the style of the CLI history above.
      */
-    why: 'root pinned at 3 pending the gateDecision residual-vocabulary reconciliation (see comment).',
+    why: 'root pinned at 3 pending the gateDecision residual-PRECEDENCE reconciliation (see comment; '
+      + 're-measured against 11.0.0 — unchanged from 10.0.0).',
   },
 ];
 
@@ -113,6 +180,94 @@ function resolvedVersionFor(startDir) {
   return null;
 }
 
+/**
+ * RESOLVED-VERSION GRADING — the half the floor check cannot do.
+ *
+ * WHY THIS EXISTS. coderifts@5.0.0 published declaring `@coderifts/agent-guard: ^11.0.0` while
+ * guard 12.0.0 was already out carrying a semantics break (requireConditionalWrite began firing on
+ * ordinary mutations). This gate PASSED, and it was not wrong to: it graded the declared floor
+ * (11 >= 11) and the resolved version (11.0.0 >= 11) against a constant a human maintains by hand.
+ * Both facts were true. Both were stale. A gate that can only compare against the last floor
+ * someone remembered to raise cannot notice a major it has never been told about.
+ *
+ * So the constant is not the whole gate. What CAN be checked without a registry call is whether
+ * the tree and the manifest AGREE — and they must agree in both directions:
+ *
+ *   · resolved BELOW the declared range  → a stale install. The suite measured an older guard than
+ *     the one we ship against, so every "cost measured as zero" conclusion is about the wrong
+ *     package.
+ *   · resolved ABOVE the declared range  → the more dangerous direction, and the one that produced
+ *     this finding's shape. Staging a NEWER guard into node_modules to measure a raise, then
+ *     publishing with the old range, means the suite proved something adopters never receive: they
+ *     resolve the range, not our node_modules. A green suite over a version we do not declare is a
+ *     false confidence, not a measurement.
+ *
+ * NOT RESOLVED IS A FAILURE, not a pass. The previous code returned a success line reading
+ * "not resolved in tree" — "we could not look" recorded as "we looked and it is fine", which is
+ * the exact fail-open class this repository refuses elsewhere (a 404 on the source_ref anchor is
+ * deliberately on the FAIL side for the same reason). A publish gate that verifies nothing must
+ * say so by failing.
+ *
+ * WHAT THIS STILL CANNOT DO, named rather than implied: it makes no network call, so it cannot
+ * know that a newer major exists. Raising the floor stays a human act with a recorded reason. This
+ * check only guarantees that what we measured is what we declare.
+ */
+
+/** Parse "1.2.3" (ignoring any prerelease/build suffix) to [1,2,3], or null. */
+function parseVersion(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v || '').trim());
+  return m ? [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)] : null;
+}
+
+/** -1 / 0 / 1 over [maj,min,pat] triples. */
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Inclusive lower bound and EXCLUSIVE upper bound for the range forms this gate already accepts.
+ * Deliberately dependency-free — the rest of this file is, and a publish gate that needs an
+ * install to run is a gate that stops running.
+ *
+ * ^1.2.3 -> [1.2.3, 2.0.0)   ~1.2.3 -> [1.2.3, 1.3.0)   >=1.2.3 -> [1.2.3, inf)
+ * 1.2.3  -> [1.2.3, 1.2.4)   1.x    -> [1.0.0, 2.0.0)
+ * Anything else -> null (caller treats an unparseable range as unverifiable, never as satisfied).
+ */
+function rangeBounds(range) {
+  const s = String(range || '').trim();
+  const m = /^(\^|~|>=|=)?\s*(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?/.exec(s);
+  if (!m) return null;
+  const op = m[1] || '';
+  const maj = parseInt(m[2], 10);
+  const minRaw = m[3];
+  const patRaw = m[4];
+  const wild = (t) => t === undefined || t === 'x' || t === '*';
+  const min = wild(minRaw) ? 0 : parseInt(minRaw, 10);
+  const pat = wild(patRaw) ? 0 : parseInt(patRaw, 10);
+  const lower = [maj, min, pat];
+  if (wild(minRaw)) return { lower, upper: [maj + 1, 0, 0] };      // 1.x
+  if (op === '^') return { lower, upper: [maj + 1, 0, 0] };
+  if (op === '~') return { lower, upper: [maj, min + 1, 0] };
+  if (op === '>=') return { lower, upper: null };
+  if (wild(patRaw)) return { lower, upper: [maj, min + 1, 0] };    // 1.2.x
+  return { lower, upper: [maj, min, pat + 1] };                    // exact
+}
+
+/**
+ * @returns {'in'|'below'|'above'|'unknown'} where `version` sits relative to `range`.
+ */
+function versionVsRange(version, range) {
+  const v = parseVersion(version);
+  const b = rangeBounds(range);
+  if (!v || !b) return 'unknown';
+  if (compareVersions(v, b.lower) < 0) return 'below';
+  if (b.upper && compareVersions(v, b.upper) >= 0) return 'above';
+  return 'in';
+}
+
 /** Check ONE checkout. Returns a line for the summary; calls fail() and exits on a violation. */
 function checkCheckout(c) {
   if (!fs.existsSync(c.pkgPath)) {
@@ -138,7 +293,15 @@ function checkCheckout(c) {
 
   const resolved = resolvedVersionFor(path.dirname(c.pkgPath));
   if (!resolved) {
-    return `${c.label}: declared ${range} (floor ${floor} >= ${c.floor}); not resolved in tree`;
+    // FAIL-CLOSED, with NO opt-out. An `allowUnresolved` flag was written and then removed on
+    // purpose: the first time this fires in CI the cheapest response is to set the flag, and the
+    // hole is back with a config line to justify it. If a checkout ever legitimately ships
+    // uninstalled, add the exemption THEN, with the measurement that earned it.
+    fail(
+      `${c.label}: ${DEP} is declared ${JSON.stringify(range)} but is NOT RESOLVABLE from `
+      + `${path.dirname(c.pkgPath)}. This gate cannot verify what will ship, and an unverified `
+      + 'publish is not a verified one. Install dependencies for this checkout and re-run.',
+    );
   }
   const rm = /^(\d+)/.exec(resolved);
   const rMajor = rm ? parseInt(rm[1], 10) : null;
@@ -148,7 +311,32 @@ function checkCheckout(c) {
   if (rMajor < floor) {
     fail(`${c.label}: resolved ${DEP}@${resolved} major ${rMajor} is below declared range floor ${floor}`);
   }
-  return `${c.label}: declared ${range} (floor ${floor} >= ${c.floor}); resolved ${resolved}`;
+
+  // THE DECLARED RANGE AND THE INSTALLED TREE MUST AGREE — both directions, full precision.
+  const where = versionVsRange(resolved, range);
+  if (where === 'below') {
+    fail(
+      `${c.label}: resolved ${DEP}@${resolved} is BELOW the declared range ${JSON.stringify(range)} `
+      + '— a stale install. Every cost measured against this tree describes an older guard than the '
+      + 'one this package declares. Run npm install for this checkout and re-measure.',
+    );
+  }
+  if (where === 'above') {
+    fail(
+      `${c.label}: resolved ${DEP}@${resolved} is ABOVE the declared range ${JSON.stringify(range)}. `
+      + 'The tree runs a guard this package does not declare, so the suite measured a version '
+      + 'adopters will never receive — they resolve the range, not our node_modules. Either raise '
+      + `the declared range to admit ${resolved} (and record WHY in the history block), or remove `
+      + 'the staged install.',
+    );
+  }
+  if (where === 'unknown') {
+    fail(
+      `${c.label}: cannot decide whether resolved ${DEP}@${resolved} satisfies declared range `
+      + `${JSON.stringify(range)} — unparseable. A range this gate cannot grade must not ship.`,
+    );
+  }
+  return `${c.label}: declared ${range} (floor ${floor} >= ${c.floor}); resolved ${resolved} (in range)`;
 }
 
 function main() {
@@ -171,4 +359,7 @@ function main() {
 // floorMajorFromRange without triggering a process.exit.
 if (require.main === module) main();
 
-module.exports = { CHECKOUTS, floorMajorFromRange, MIN_GUARD_MAJOR, DEP };
+module.exports = {
+  CHECKOUTS, floorMajorFromRange, MIN_GUARD_MAJOR, DEP,
+  parseVersion, compareVersions, rangeBounds, versionVsRange, resolvedVersionFor,
+};