opencode-ruby-upgrader 0.1.7 → 0.1.9

package/src/bundler-compat.js

@@ -0,0 +1,68 @@
+// Bundler/Ruby compatibility facts for the Bundler bridge.
+//
+// This module deliberately holds no version table. The tool performs no network
+// requests, so it cannot look up which Bundler supports which Ruby, and a
+// hardcoded table would silently rot the first time RubyGems cut a series.
+// Instead the *floor* is supplied by the agent as cited research at the moment a
+// bridge is approved -- the same way Rails and Ruby compatibility facts already
+// enter this system -- and recorded in run evidence so it can be re-verified.
+//
+// What lives here is the arithmetic: comparing versions, and deciding whether a
+// declared floor is genuinely above the project's pin. That logic must be local
+// and deterministic, because it is what makes an approval defensible.
+
+export const BUNDLER_COMPATIBILITY_SOURCE = "https://guides.rubygems.org/bundler-compatibility/";
+
+// The official guide is a table of *minimum floors*, not fixed pairings: Bundler
+// 2.5 requires Ruby >= 3.0, 2.6 requires >= 3.1, and 2.7 and 4.0 both require
+// >= 3.2. A higher Bundler supports a wider range of Rubies, so a Ruby hop
+// forward essentially never forces a Bundler upgrade -- an *existing* Bundler
+// pin is what breaks when the Ruby moves. The bridge therefore exists because
+// this project's pin lags its new Ruby, which is the mirror image of the Rails
+// bridge (where Rails lagging Ruby blocks the hop).
+export const bundlerVersion = /^\d+\.\d+(?:\.\d+)?$/;
+
+export const bundlerSeries = (value) => String(value ?? "").split(".").slice(0, 2).join(".");
+const parts = (value) => bundlerSeries(value).split(".").map(Number);
+export const compareBundler = (left, right) => {
+  const [lMajor, lMinor] = parts(left); const [rMajor, rMinor] = parts(right);
+  return lMajor !== rMajor ? lMajor - rMajor : lMinor - rMinor;
+};
+
+// Bundler series move +1 per minor, with one major boundary: the 2.x line ends
+// at 2.7 and the next series is 4.0. That jump is major 2 to 4 -- major 3 was
+// never a Bundler series -- so this is an explicit successor rather than the
+// +1 pattern Ruby uses. Treating 2.7 -> 4.0 as a valid single hop is required
+// because that is how the official series run; without it a project on 2.4 could
+// never reach 4.0 through a reviewed ladder.
+const bundlerSeriesSuccessors = new Map([["2.7", "4.0"]]);
+export const contiguousBundlerHop = (from, to) => {
+  const [fromMajor, fromMinor] = parts(from); const [toMajor, toMinor] = parts(to);
+  if (![fromMajor, fromMinor, toMajor, toMinor].every((value) => Number.isInteger(value))) return false;
+  return toMajor === fromMajor && toMinor === fromMinor + 1
+    || bundlerSeriesSuccessors.get(bundlerSeries(from)) === bundlerSeries(to);
+};
+
+// True when the project's recorded `BUNDLED WITH` pin sits below a researched
+// floor. Bundler auto-switches to that pin, so this is the version that will
+// actually run -- and the reason a hop is blocked.
+export function bundlerPinBelowFloor({ pinned, minimum }) {
+  if (!bundlerVersion.test(String(pinned ?? "")) || !bundlerVersion.test(String(minimum ?? ""))) return false;
+  return compareBundler(pinned, minimum) < 0;
+}
+
+// A ladder must start at the pin and reach the researched floor one contiguous
+// minor series at a time, so no hop can skip an intermediate Bundler whose
+// behavior changes are themselves unreviewed.
+export function validateBundlerLadder({ ladder, pinned, target }) {
+  if (!Array.isArray(ladder) || ladder.length < 2) return "A Bundler research ladder must contain at least two versions.";
+  if (ladder.some((version) => !bundlerVersion.test(version))) return "A Bundler research ladder must contain Bundler versions.";
+  if (bundlerSeries(ladder[0]) !== bundlerSeries(pinned)) return "A Bundler research ladder must begin at the version recorded in BUNDLED WITH.";
+  // Contiguity is checked before the endpoint so a ladder that both skips a
+  // series and overshoots reports the more specific problem.
+  for (let index = 1; index < ladder.length; index += 1) {
+    if (!contiguousBundlerHop(ladder[index - 1], ladder[index])) return "A Bundler research ladder must advance one minor series per hop, or across the 2.7 to 4.0 series boundary.";
+  }
+  if (bundlerSeries(ladder.at(-1)) !== bundlerSeries(target)) return "A Bundler research ladder must end at the researched target Bundler.";
+  return null;
+}

package/src/commit-hop.js

@@ -34,11 +34,12 @@ function readReport(root, reportPath) {
   catch { throw new CommitGateError("The upgrade report is missing or fails the run schema.", "invalid-report"); }
 }
 
-function assertValidatedIteration(report, rails = false) {
+function assertValidatedIteration(report, bridge = null) {
   const iteration = report.iterations?.at(-1);
-  if (rails ? (!report.targetRails || !report.targetRailsPinnedAt || !report.bridge) : (!report.targetRuby || !report.targetPinnedAt)) {
-    throw new CommitGateError("The report must pin its target and bridge evidence before an automatic commit.", "target-not-pinned");
-  }
+  const pinned = bridge === "rails" ? (report.targetRails && report.targetRailsPinnedAt && report.bridge)
+    : bridge === "bundler" ? (report.targetBundler && report.targetBundlerPinnedAt && report.bridge)
+      : (report.targetRuby && report.targetPinnedAt);
+  if (!pinned) throw new CommitGateError("The report must pin its target and bridge evidence before an automatic commit.", "target-not-pinned");
   if (!iteration || iteration.status !== "complete" || iteration.tests?.passed !== true) {
     throw new CommitGateError("The latest hop is not recorded as complete with passing tests.", "validation-missing");
   }
@@ -52,7 +53,11 @@ function assertValidatedIteration(report, rails = false) {
   if (!Array.isArray(iteration.fixes) || !iteration.fixes.length || !Array.isArray(iteration.citations) || !iteration.citations.length || !iteration.tests?.smoke) {
     throw new CommitGateError("The latest hop requires explained fixes, citations, and smoke-test evidence.", "evidence-missing");
   }
-  if (rails && !iteration.appUpdateReview) throw new CommitGateError("The latest Rails hop requires reviewed bin/rails app:update evidence.", "app-update-review-missing");
+  if (bridge === "rails" && !iteration.appUpdateReview) throw new CommitGateError("The latest Rails hop requires reviewed bin/rails app:update evidence.", "app-update-review-missing");
+  // A Bundler hop changes the lockfile, so the commit must carry the pin it
+  // produced. Committing a hop whose recorded pin disagrees with its target
+  // would publish evidence that does not match the repository state.
+  if (bridge === "bundler" && (!iteration.lockfilePin || iteration.lockfilePin.split(".").slice(0, 2).join(".") !== iteration.to.split(".").slice(0, 2).join("."))) throw new CommitGateError("The latest Bundler hop must record the BUNDLED WITH pin it produced.", "bundler-pin-missing");
   return iteration;
 }
 
@@ -161,9 +166,13 @@ function assertValidationFingerprint(cwd, iteration) {
   }
 }
 
-function messageFor(iteration, reportPath, report, rails = false) {
+function messageFor(iteration, reportPath, report, bridge = null) {
   const receiptTrailer = iteration.validationReceipts?.length ? [`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`] : [];
-  if (rails) return [
+  if (bridge === "bundler") return [
+    `chore(bundler): upgrade ${iteration.from} to ${iteration.to}`, "", "Raise the BUNDLED WITH floor recorded in Gemfile.lock so this project can run on the target Ruby.", `Validation: ${iteration.tests.command || "project test suite"} executed on Bundler ${iteration.lockfilePin}.`, `Evidence: ${reportPath}`,
+    `Bundler-Upgrade-Report: ${reportPath}`, `Bundler-Upgrade-Hop: ${iteration.from}->${iteration.to}`, `Bundler-Bridge-Ruby-Report: ${report.bridge.rubyReportPath}`, ...receiptTrailer
+  ].join("\n");
+  if (bridge === "rails") return [
     `chore(rails): upgrade ${iteration.from} to ${iteration.to}`, "", "Apply the reviewed Rails framework compatibility changes.", `Validation: ${iteration.tests.command || "project test suite"}.`, `Evidence: ${reportPath}`,
     `Rails-Upgrade-Report: ${reportPath}`, `Rails-Upgrade-Hop: ${iteration.from}->${iteration.to}`, `Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`, `Rails-Bridge-Ruby-Report: ${report.bridge.rubyReportPath}`, ...receiptTrailer
   ].join("\n");
@@ -178,7 +187,7 @@ function messageFor(iteration, reportPath, report, rails = false) {
   ].join("\n");
 }
 
-function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false, allowBroadLockfile = false, allowPrivateSources = false, rails = false }) {
+function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false, allowBroadLockfile = false, allowPrivateSources = false, bridge = null }) {
   if (!reportPath) throw new CommitGateError("Provide --report .ruby-upgrades/runs/<run>.json.", "missing-report-path");
   const state = gitState(cwd);
   if (!state.linked || !state.branch || !state.defaultBranch || state.branch === state.defaultBranch) {
@@ -191,8 +200,9 @@ function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false,
   if (!report.lockNonce) throw new CommitGateError("The report is missing its active lock capability.", "lock-capability-missing");
   try { assertRunLock(state.root, reportPath, report.lockNonce); }
   catch (error) { throw new CommitGateError(error.message, error.code); }
-  const iteration = assertValidatedIteration(report, rails);
-  if (report.schemaVersion !== 2 || report.phase !== "hop_validated" || Boolean(report.reportType === "rails_bridge") !== rails) throw new CommitGateError("The run must use the current schema and transition to hop_validated before an automatic commit.", "phase-not-validated");
+  const iteration = assertValidatedIteration(report, bridge);
+  const expectedType = bridge === "rails" ? "rails_bridge" : bridge === "bundler" ? "bundler_bridge" : "ruby";
+  if (report.schemaVersion !== 2 || report.phase !== "hop_validated" || (report.reportType ?? "ruby") !== expectedType) throw new CommitGateError("The run must use the current schema and transition to hop_validated before an automatic commit.", "phase-not-validated");
   if (report.branch !== state.branch) throw new CommitGateError("The worktree branch no longer matches the recorded run branch.", "unexpected-branch");
   assertExpectedHead(state, report);
   const indexPath = path.resolve(cwd, text(cwd, ["rev-parse", "--git-path", "index"]));
@@ -216,7 +226,7 @@ function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false,
     throw new CommitGateError(`Potential credential material detected in: ${secretPaths.join(", ")}. Review it manually; it was not committed.`, "secret-detected");
   }
 
-  const message = messageFor(iteration, relativeReport, report, rails);
+  const message = messageFor(iteration, relativeReport, report, bridge);
     assertValidationFingerprint(cwd, iteration);
     if (text(cwd, ["rev-parse", "HEAD"]) !== report.expectedHead) throw new CommitGateError("HEAD changed while the commit gate was validating; refusing to commit atop unexpected history.", "unexpected-head");
     commit(cwd, message, env);
@@ -230,5 +240,6 @@ function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false,
   }
 }
 
-export function commitValidatedHop(options = {}) { return commitValidated(options); }
-export function commitValidatedRailsHop(options = {}) { return commitValidated({ ...options, rails: true }); }
+export function commitValidatedHop(options = {}) { return commitValidated({ ...options, bridge: null }); }
+export function commitValidatedRailsHop(options = {}) { return commitValidated({ ...options, bridge: "rails" }); }
+export function commitValidatedBundlerHop(options = {}) { return commitValidated({ ...options, bridge: "bundler" }); }

package/src/controller.js

@@ -4,9 +4,11 @@ import { execFileSync } from "node:child_process";
 import { inspectGitCapabilities, inspectWorktree } from "./preflight.js";
 import { inventoryProject } from "./inventory.js";
 import { inspectSupplyChain } from "./supply-chain.js";
+import { bundledWith as inventoryBundledWith } from "./advisory.js";
 import { acquireRunLock, assertRunLock, readRun, releaseRunLock, writeRun } from "./run-state.js";
 import { executeValidation } from "./validation-executor.js";
 import { receiptDigest } from "./provenance.js";
+import { BUNDLER_COMPATIBILITY_SOURCE, bundlerVersion, bundlerSeries, compareBundler, bundlerPinBelowFloor, contiguousBundlerHop, validateBundlerLadder } from "./bundler-compat.js";
 
 const rubyVersion = /^\d+\.\d+(?:\.\d+)?$/;
 const railsVersion = /^\d+(?:\.\d+)+$/;
@@ -74,6 +76,31 @@ export function beginRailsBridgeRun({ root = process.cwd(), rubyReportPath, dryR
   return { ...plan, reportPath, report, lock };
 }
 
+export function beginBundlerBridgeRun({ root = process.cwd(), rubyReportPath, dryRun = false, stopAfterHop = false } = {}) {
+  const rubyRun = readRun(root, rubyReportPath);
+  if (rubyRun.reportType?.endsWith("_bridge") || rubyRun.phase !== "blocked" || rubyRun.status !== "blocked" || !rubyRun.bundlerBridge) throw new Error("A Bundler bridge can start only from a blocked Ruby run with an approved Bundler compatibility bridge.");
+  const preflight = inspectWorktree(root); const inventory = inventoryProject(root); const supplyChain = inspectSupplyChain(root); const gitCapabilities = inspectGitCapabilities(root); const bridge = rubyRun.bundlerBridge;
+  const plan = { preflight, inventory, supplyChain, gitCapabilities, bridge, dryRun, stopAfterHop };
+  if (dryRun) return plan;
+  if (!preflight.ok || preflight.mode !== "linked-worktree") throw new Error("A durable Bundler bridge requires a supported linked Git worktree.");
+  if (bundlerSeries(inventory.bundler?.bundledWith ?? "") !== bundlerSeries(bridge.bundlerFrom)) throw new Error("The current Gemfile.lock must still record the Bundler version recorded by the blocked Ruby run.");
+  if (preflight.branch !== rubyRun.branch || preflight.sha !== rubyRun.expectedHead) throw new Error("Bundler bridge must start on the blocked Ruby run's recorded branch and checkpoint SHA.");
+  const reportPath = path.join(".ruby-upgrades", "runs", runName());
+  const report = { schemaVersion: 2, validationReceiptsRequired: true, reportType: "bundler_bridge", runId: crypto.randomUUID(), title: `Bundler bridge ${bridge.bundlerFrom} to ${bridge.bundlerTo}`, status: "in_progress", phase: "initialized", startedAt: new Date().toISOString(), targetBundler: bridge.bundlerTo, targetBundlerPinnedAt: new Date().toISOString(), targetRuby: bridge.rubyTo, branch: preflight.branch ?? null, worktreeRoot: preflight.root ?? root, startingSha: preflight.sha ?? null, expectedHead: preflight.sha ?? null, control: { stopAfterHop }, inventory, supplyChain, gitCapabilities, bridge: { rubyReportPath, rubyRunId: rubyRun.runId, rubyFrom: bridge.rubyFrom, rubyTo: bridge.rubyTo, bundlerFrom: bridge.bundlerFrom, bundlerTo: bridge.bundlerTo, minimumBundler: bridge.minimumBundler, compatibilitySource: bridge.compatibilitySource, approvedAt: bridge.recordedAt }, research: { ladder: [], citations: [] }, riskDecisions: [], requiredRisks: requiredRisksFor(supplyChain, gitCapabilities), summary: [`Bundler bridge initialized from a blocked Ruby hop; researched floor ${bridge.minimumBundler}.`], iterations: [], sessionSummary: "" };
+  const lock = acquireRunLock(root, reportPath); report.lockNonce = lock.nonce;
+  try { writeRun(root, reportPath, report); } catch (error) { releaseRunLock(root, reportPath, lock.nonce); throw error; }
+  return { ...plan, reportPath, report, lock };
+}
+
+export function recordBundlerResearch({ root = process.cwd(), reportPath, ladder, citations }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "bundler_bridge") throw new Error("Bundler research belongs only to a Bundler bridge report.");
+  const problem = validateBundlerLadder({ ladder, pinned: run.bridge.bundlerFrom, target: run.targetBundler });
+  if (problem) throw new Error(problem);
+  if (!Array.isArray(citations) || !citations.length || citations.some((citation) => !citation?.title || !/^https:\/\//.test(citation.url ?? ""))) throw new Error("Bundler research requires at least one HTTPS official-source citation.");
+  run.research = { ladder, citations }; writeRun(root, reportPath, run); return run;
+}
+
 export function recordResearch({ root = process.cwd(), reportPath, ladder, citations }) {
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
   if (!Array.isArray(ladder) || !ladder.length || ladder.some((version) => !rubyVersion.test(version))) throw new Error("Research requires a Ruby-version ladder.");
@@ -98,6 +125,31 @@ export function recordRiskDecision({ root = process.cwd(), reportPath, risk, dec
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce); run.riskDecisions.push({ risk, decision, evidence, recordedAt: new Date().toISOString() }); writeRun(root, reportPath, run); return run;
 }
 
+// A Bundler bridge records the same kind of decision the Rails bridge does: the
+// project's own pin cannot cross the researched Ruby hop, so the change happens
+// in its own separately scoped run. What differs is the evidence -- a Rails hop
+// produces a reviewable `app:update` receipt, while a Bundler hop produces a
+// lockfile change that must be confirmed against the version actually executed.
+export function recordBundlerBridge({ root = process.cwd(), reportPath, rubyFrom, rubyTo, bundlerFrom, bundlerTo, minimumBundler, rationale, citations }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (!["research_complete", "committed"].includes(run.phase)) throw new Error("Record a Bundler compatibility bridge only after research or a committed Ruby checkpoint and before a blocked Ruby hop.");
+  if (run.frameworkBridge || run.bundlerBridge) throw new Error("This run already has an approved compatibility bridge; complete it in a separately scoped run.");
+  if (![rubyFrom, rubyTo].every((version) => rubyVersion.test(version)) || ![bundlerFrom, bundlerTo, minimumBundler].every((version) => bundlerVersion.test(version))) throw new Error("A Bundler compatibility bridge requires Ruby from/to and Bundler from/to/floor versions.");
+  if (series(rubyFrom) !== series(run.iterations.at(-1)?.to ?? run.research.ladder[0]) || series(rubyTo) !== series(run.research.ladder[run.research.ladder.findIndex((version) => series(version) === series(rubyFrom)) + 1])) throw new Error("Bundler compatibility bridge must describe the next researched Ruby hop.");
+  if (series(bundlerFrom) !== series(run.inventory.bundler?.bundledWith ?? "")) throw new Error("A Bundler compatibility bridge must begin at the version recorded in the project's BUNDLED WITH.");
+  // Without this the bridge could be approved for a pin that already satisfies
+  // the floor, which would block a hop for no reason. It is deliberately the
+  // last check before approval, so the message names the actual pin and floor
+  // rather than a generic validation failure.
+  const pin = run.inventory.bundler?.bundledWith ?? bundlerFrom;
+  if (!bundlerPinBelowFloor({ pinned: pin, minimum: minimumBundler })) throw new Error(`Bundler ${pin} is not below the researched floor ${minimumBundler}; approving a bridge would block the hop without cause.`);
+  if (compareBundler(bundlerTo, minimumBundler) < 0) throw new Error("The bridge target Bundler must be at or above the researched minimum floor.");
+  if (!rationale || !Array.isArray(citations) || !citations.length || citations.some((citation) => !citation?.title || !/^https:\/\//.test(citation.url ?? ""))) throw new Error("A Bundler compatibility bridge requires a rationale and HTTPS citations.");
+  run.bundlerBridge = { status: "approved", rubyFrom, rubyTo, bundlerFrom, bundlerTo, minimumBundler, compatibilitySource: BUNDLER_COMPATIBILITY_SOURCE, rationale, citations, recordedAt: new Date().toISOString() };
+  run.summary = [...run.summary, `User approved a separately scoped Bundler ${bundlerFrom} → ${bundlerTo} bridge before Ruby ${rubyFrom} → ${rubyTo}, on a researched floor of ${minimumBundler}.`];
+  writeRun(root, reportPath, run); return run;
+}
+
 export function recordFrameworkBridge({ root = process.cwd(), reportPath, rubyFrom, rubyTo, railsFrom, railsTo, rationale, citations }) {
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
   if (!["research_complete", "committed"].includes(run.phase)) throw new Error("Record a Rails compatibility bridge only after research or a committed Ruby checkpoint and before a blocked Ruby hop.");
@@ -114,7 +166,7 @@ export function recordFrameworkBridge({ root = process.cwd(), reportPath, rubyFr
 
 function recordIterationInternal({ root = process.cwd(), reportPath, iteration, executed = false }) {
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
-  if (run.reportType === "rails_bridge") throw new Error("Use record-rails-iteration for a Rails bridge report.");
+  if (run.reportType?.endsWith("_bridge")) throw new Error(`Use the ${run.reportType === "rails_bridge" ? "Rails" : "Bundler"} bridge iteration recorder for a bridge report.`);
   if (run.validationReceiptsRequired && !executed) throw new Error("New reports require record-executed-iteration so validation receipts are created by the executor.");
   if (run.phase !== "research_complete" && run.phase !== "committed") throw new Error("Record iterations only after research or a prior checkpoint.");
   assertApprovedRisks(run);
@@ -190,6 +242,27 @@ export function discardLastRailsIteration({ root = process.cwd(), reportPath, re
   writeRun(root, reportPath, run); return run;
 }
 
+// A Bundler hop is evidenced by what it changed and what actually ran. `bundle
+// lock --bundler` rewrites the `BUNDLED WITH` pin, and the runtime attests the
+// Bundler that executed the tests; requiring both to agree is what stops a hop
+// being recorded on the strength of a lockfile edit alone.
+export function recordExecutedBundlerIteration({ root = process.cwd(), reportPath, iteration, validationCommandId, executed = false }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "bundler_bridge" || !["research_complete", "committed"].includes(run.phase)) throw new Error("Record Bundler iterations only after Bundler research or a prior Bundler checkpoint.");
+  assertApprovedRisks(run);
+  if (run.iterations.length && (run.phase !== "committed" || !run.iterations.at(-1).checkpointSha)) throw new Error("Each iteration requires exactly one checkpoint before the next iteration.");
+  const expectedFrom = run.iterations.at(-1)?.to ?? run.research.ladder[0];
+  const index = run.research.ladder.findIndex((version) => bundlerSeries(version) === bundlerSeries(expectedFrom));
+  const expectedTo = run.research.ladder[index + 1];
+  if (!iteration || index < 0 || !expectedTo || bundlerSeries(iteration.from) !== bundlerSeries(expectedFrom) || bundlerSeries(iteration.to) !== bundlerSeries(expectedTo)) throw new Error("Iteration must advance exactly one researched Bundler series from the prior ladder point.");
+  const receipt = executeValidation({ root, inventory: run.inventory, commandId: validationCommandId, expectedRuntime: { runId: run.runId, reportPath } });
+  if (receipt.kind !== "test" || receipt.exitCode !== 0 || receipt.testEvidence?.passed !== true) throw new Error(`Validation failed; receipt ${receipt.id} was not recorded as a passing hop.`);
+  const pinned = inventoryBundledWith(root);
+  if (bundlerSeries(pinned ?? "") !== bundlerSeries(iteration.to)) throw new Error(`Gemfile.lock still records Bundler ${pinned ?? "none"}; a hop to ${iteration.to} requires the BUNDLED WITH pin to be rewritten first.`);
+  if (bundlerSeries(receipt.environment?.bundlerVersion ?? "") !== bundlerSeries(iteration.to)) throw new Error(`Validation executed Bundler ${receipt.environment?.bundlerVersion ?? "an unrecorded version"}, not ${iteration.to}. Re-prepare the target runtime on the new Bundler before recording this hop.`);
+  run.iterations.push({ ...iteration, status: "complete", lockfilePin: pinned }); writeRun(root, reportPath, run); return run;
+}
+
 export function recordDependencyReview({ root = process.cwd(), reportPath, compatibility, licenses }) {
   if (!compatibility?.trim() || !licenses?.trim()) throw new Error("Dependency review requires compatibility and license findings.");
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
@@ -205,7 +278,8 @@ function validRailsReviewForExecution(review, receipt) { return review?.command
 function validationPreflight(root, reportPath, rails) {
   const run = readRun(root, reportPath);
   assertRunLock(root, reportPath, run.lockNonce);
-  if (Boolean(run.reportType === "rails_bridge") !== rails || !["research_complete", "committed"].includes(run.phase)) throw new Error("Validation can run only for the active report type after research or a prior checkpoint.");
+  const activeType = run.reportType === "rails_bridge" ? "rails_bridge" : run.reportType === "bundler_bridge" ? "bundler_bridge" : "ruby";
+  if ((rails ? "rails_bridge" : "ruby") !== activeType || !["research_complete", "committed"].includes(run.phase)) throw new Error("Validation can run only for the active report type after research or a prior checkpoint.");
   assertApprovedRisks(run);
   if (run.iterations.length && (run.phase !== "committed" || !run.iterations.at(-1).checkpointSha)) throw new Error("Each iteration requires exactly one checkpoint before validation can run again.");
   return run;
@@ -213,7 +287,7 @@ function validationPreflight(root, reportPath, rails) {
 
 function assertCompletion(run) {
   const final = run.iterations.at(-1);
-  const target = run.reportType === "rails_bridge" ? run.targetRails : run.targetRuby;
+  const target = run.reportType === "rails_bridge" ? run.targetRails : run.reportType === "bundler_bridge" ? run.targetBundler : run.targetRuby;
   if (!final || series(final.to) !== series(target)) throw new Error("A run can complete only after the final validated iteration reaches its pinned target.");
   if (series(run.research.ladder.at(-1)) !== series(target)) throw new Error("Research ladder does not reach its pinned target.");
   if (hasUnapprovedRisks(run)) throw new Error("Unresolved risks prevent completion.");
@@ -228,14 +302,14 @@ function verifyCheckpoint(root, reportPath, run, commitSha) {
   if (git(root, ["rev-parse", `${head}^`]) !== run.expectedHead) throw new Error("Checkpoint must be a direct child of the prior recorded checkpoint.");
   const iteration = run.iterations.at(-1);
   const message = git(root, ["log", "-1", "--format=%B"]);
-  const prefix = run.reportType === "rails_bridge" ? "Rails" : "Ruby";
-  if (!message.includes(`${prefix}-Upgrade-Report: ${reportPath}`) || !message.includes(`${prefix}-Upgrade-Hop: ${iteration.from}->${iteration.to}`) || (iteration.validationReceipts?.length && !message.includes(`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`)) || (prefix === "Rails" && (!message.includes(`Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`) || !message.includes(`Rails-Bridge-Ruby-Report: ${run.bridge.rubyReportPath}`)))) throw new Error("Checkpoint commit does not carry the required run and hop trailers.");
+  const prefix = run.reportType === "rails_bridge" ? "Rails" : run.reportType === "bundler_bridge" ? "Bundler" : "Ruby";
+  if (!message.includes(`${prefix}-Upgrade-Report: ${reportPath}`) || !message.includes(`${prefix}-Upgrade-Hop: ${iteration.from}->${iteration.to}`) || (iteration.validationReceipts?.length && !message.includes(`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`)) || (prefix === "Rails" && (!message.includes(`Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`) || !message.includes(`Rails-Bridge-Ruby-Report: ${run.bridge.rubyReportPath}`))) || (prefix === "Bundler" && !message.includes(`Bundler-Bridge-Ruby-Report: ${run.bridge.rubyReportPath}`))) throw new Error("Checkpoint commit does not carry the required run and hop trailers.");
 }
 
 export function transitionRun({ root = process.cwd(), reportPath, phase, note = "", commitSha = "" }) {
   if (!Object.hasOwn(transitions, phase)) throw new Error(`Unknown run phase: ${phase}.`);
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce); const current = run.phase;
-  if (current === "blocked" && run.frameworkBridge) throw new Error("A Ruby run blocked by a Rails bridge is terminal; complete the bridge and start a fresh Ruby run.");
+  if (current === "blocked" && (run.frameworkBridge || run.bundlerBridge)) throw new Error("A Ruby run blocked by an approved compatibility bridge is terminal; complete that bridge and start a fresh Ruby run.");
   if (!transitions[current]?.includes(phase)) throw new Error(`Cannot transition from ${current} to ${phase}.`);
   if (phase === "research_complete" && (!run.research.ladder.length || !run.research.citations.length)) throw new Error("Record research and citations before completing research.");
   if (phase === "hop_validated" && (run.iterations.at(-1)?.tests?.passed !== true || !run.iterations.at(-1)?.validationReceipts?.length)) throw new Error("A hop requires passing tests and executed validation receipts.");
@@ -258,7 +332,7 @@ export function transitionRun({ root = process.cwd(), reportPath, phase, note =
 export function resumeRun({ root = process.cwd(), reportPath, continueAfterHop = false }) {
   const run = readRun(root, reportPath);
   if (run.status === "complete") throw new Error("This run is complete; start a new run instead.");
-  if (run.frameworkBridge && run.phase === "blocked") throw new Error("This Ruby run is blocked by an approved Rails bridge and cannot resume. Complete the linked Rails bridge, then begin a fresh Ruby run.");
+  if ((run.frameworkBridge || run.bundlerBridge) && run.phase === "blocked") throw new Error("This Ruby run is blocked by an approved compatibility bridge and cannot resume. Complete the linked bridge, then begin a fresh Ruby run.");
   if (run.phase === "paused" && !transitions.paused.includes(run.resumePhase)) throw new Error("Paused run has no safe resume phase.");
   if (run.control.stopAfterHop && run.iterations.length >= 1 && run.resumePhase === "committed" && !continueAfterHop) throw new Error("This run stopped after its requested hop. Resume with explicit --continue-after-hop only after user review.");
   if (continueAfterHop) run.control.stopAfterHop = false;

package/src/dashboard-page.js

@@ -11,6 +11,6 @@ const testValue=(tests,key,fallback='—')=>tests&&tests[key]!==undefined&&tests
 fetch('/api/runs').then(response=>response.json()).then(runs=>{
  const app=document.querySelector('#app');
  if(!runs.length){app.innerHTML='<article class="card"><b>No upgrade runs yet.</b><p>Run <code>/ruby-upgrade</code> from a linked Git worktree. Evidence will appear under <code>.ruby-upgrades/runs/</code>.</p></article>';return;}
- app.innerHTML=runs.map(run=>{const iterations=run.iterations||[];const latest=iterations.at(-1)||{};const tests=latest.tests||{};const commits=(run.localCommits||[]).map(sha=>'<code>'+esc(sha)+'</code>').join(' ')||'No local commit found yet.';const target=run.reportType==='rails_bridge'?'Rails '+(run.targetRails||'target unknown'):'Ruby '+(run.targetRuby||'target unknown');const bridge=run.reportType==='rails_bridge'?'<p><b>Blocked Ruby hop:</b> '+esc(run.bridge?.rubyFrom)+' → '+esc(run.bridge?.rubyTo)+' · <code>'+esc(run.bridge?.rubyReportPath)+'</code></p>':'';const details=iterations.map(iteration=>{const itTests=iteration.tests||{};const fixes=(iteration.fixes||[]).map(fix=>'<li><b>'+esc((fix.files||[]).join(', ')||'Migration fix')+'</b><br>'+esc(fix.explanation)+'</li>').join('')||'<li>No code or dependency fixes recorded.</li>';const citations=(iteration.citations||[]).map(citation=>'<a href="'+safeUrl(citation.url)+'" target="_blank" rel="noreferrer">'+esc(citation.title||citation.url)+'</a>').join(' · ')||'No citations recorded.';const appUpdate=iteration.appUpdateReview?'<p><small>app:update: '+esc(iteration.appUpdateReview.outcome)+' — '+esc(iteration.appUpdateReview.summary)+'</small></p>':'';const receipts=(iteration.validationReceipts||[]).map(receipt=>{const digest=receipt.output&&receipt.output.redactedSha256?receipt.output.redactedSha256.slice(0,16):'';const meta=['kind:'+esc(receipt.kind||'—'),'exit:'+esc(receipt.exitCode??'—'),(receipt.durationMs?'ms:'+esc(receipt.durationMs):'')].filter(Boolean).join(' · ');return '<li><code>'+meta+'</code>'+((receipt.testEvidence&&receipt.testEvidence.passed===true)?' <b>[PASS]</b>':'')+'<br><small>digest <code>'+esc(digest||'—')+'</code> · '+(receipt.environment?esc(receipt.environment.imageRef||receipt.environment.ruby||'')+' · <code>'+esc(receipt.environment.imageId||receipt.environment.id||'')+'</code>':'')+'</small></li>';}).join('');const review=iteration.dependencyReview&&iteration.dependencyReview.completed?'<p><small>Dependency review: '+esc(iteration.dependencyReview.compatibility||'completed')+(iteration.dependencyReview.licenses?' · '+esc(iteration.dependencyReview.licenses):'')+'</small></p>':'';return '<section class="iteration"><b>'+esc(iteration.from)+' → '+esc(iteration.to)+' · '+esc(iteration.status)+'</b><div class="grid">'+metric('Test result',itTests.passed===true?'Passed':itTests.passed===false?'Failed':'—')+metric('Smoke check',testValue(itTests,'smoke'))+metric('Coverage',testValue(itTests,'coveragePercent',null)===null?'—':testValue(itTests,'coveragePercent')+'%')+'</div><ul>'+fixes+'</ul>'+review+((iteration.validationReceipts&&iteration.validationReceipts.length)?'<p><b>Receipts</b></p><ul>'+receipts+'</ul>':'')+appUpdate+'<br><small>Sources: '+citations+'</small></section>';}).join('');return '<article class="card"><span class="tag">'+esc(run.status||'unknown')+'</span><span class="tag">'+esc(target)+'</span><h2>'+esc(run.title||run.file)+'</h2><p class="sub">'+esc(run.startedAt||'Unknown start')+' · '+esc(run.branch||'Unknown branch')+'</p><div class="grid">'+metric('Tests',testValue(tests,'count'))+metric('Coverage',testValue(tests,'coveragePercent',null)===null?'—':testValue(tests,'coveragePercent')+'%')+metric('Duration',testValue(tests,'durationSeconds',null)===null?'—':testValue(tests,'durationSeconds')+'s')+metric('Smoke check',testValue(tests,'smoke'))+'</div><pre>'+esc((run.summary||[]).join('\n'))+'</pre>'+bridge+details+'<p><b>Local commits:</b> '+commits+'</p><p><b>Session:</b> '+esc(run.sessionSummary||'—')+'</p></article>';}).join('');
+ app.innerHTML=runs.map(run=>{const iterations=run.iterations||[];const latest=iterations.at(-1)||{};const tests=latest.tests||{};const commits=(run.localCommits||[]).map(sha=>'<code>'+esc(sha)+'</code>').join(' ')||'No local commit found yet.';const target=run.reportType==='rails_bridge'?'Rails '+(run.targetRails||'target unknown'):run.reportType==='bundler_bridge'?'Bundler '+(run.targetBundler||'target unknown'):'Ruby '+(run.targetRuby||'target unknown');const advisories=(run.advisories||[]).map(item=>'<li><span class="tag">'+esc(item.area)+'</span> <b>'+esc(item.title)+'</b><br><small>'+esc(item.detail)+'</small><br><small>Evidence: <code>'+esc(item.evidence)+'</code> · '+esc(item.confidence)+'</small></li>').join('')||'<li><small>No infrastructure inconsistencies detected against the current worktree.</small></li>';const advisoryBlock='<p><b>Infrastructure review (advisory)</b> <small>— about files this run did not change; nothing here blocks the upgrade</small></p><ul>'+advisories+'</ul>';const bridge=run.bridge?'<p><b>Blocked Ruby hop:</b> '+esc(run.bridge.rubyFrom)+' → '+esc(run.bridge.rubyTo)+(run.bridge.minimumBundler?' · researched Bundler floor <code>'+esc(run.bridge.minimumBundler)+'</code>':'')+' · <code>'+esc(run.bridge.rubyReportPath)+'</code></p>':'';const details=iterations.map(iteration=>{const itTests=iteration.tests||{};const fixes=(iteration.fixes||[]).map(fix=>'<li><b>'+esc((fix.files||[]).join(', ')||'Migration fix')+'</b><br>'+esc(fix.explanation)+'</li>').join('')||'<li>No code or dependency fixes recorded.</li>';const citations=(iteration.citations||[]).map(citation=>'<a href="'+safeUrl(citation.url)+'" target="_blank" rel="noreferrer">'+esc(citation.title||citation.url)+'</a>').join(' · ')||'No citations recorded.';const appUpdate=iteration.appUpdateReview?'<p><small>app:update: '+esc(iteration.appUpdateReview.outcome)+' — '+esc(iteration.appUpdateReview.summary)+'</small></p>':'';const receipts=(iteration.validationReceipts||[]).map(receipt=>{const digest=receipt.output&&receipt.output.redactedSha256?receipt.output.redactedSha256.slice(0,16):'';const meta=['kind:'+esc(receipt.kind||'—'),'exit:'+esc(receipt.exitCode??'—'),(receipt.durationMs?'ms:'+esc(receipt.durationMs):'')].filter(Boolean).join(' · ');return '<li><code>'+meta+'</code>'+((receipt.testEvidence&&receipt.testEvidence.passed===true)?' <b>[PASS]</b>':'')+'<br><small>digest <code>'+esc(digest||'—')+'</code> · '+(receipt.environment?esc(receipt.environment.imageRef||receipt.environment.ruby||'')+' · <code>'+esc(receipt.environment.imageId||receipt.environment.id||'')+'</code>':'')+'</small></li>';}).join('');const pin=iteration.lockfilePin?'<p><small>BUNDLED WITH: <code>'+esc(iteration.lockfilePin)+'</code></small></p>':'';const review=iteration.dependencyReview&&iteration.dependencyReview.completed?'<p><small>Dependency review: '+esc(iteration.dependencyReview.compatibility||'completed')+(iteration.dependencyReview.licenses?' · '+esc(iteration.dependencyReview.licenses):'')+'</small></p>':'';return '<section class="iteration"><b>'+esc(iteration.from)+' → '+esc(iteration.to)+' · '+esc(iteration.status)+'</b><div class="grid">'+metric('Test result',itTests.passed===true?'Passed':itTests.passed===false?'Failed':'—')+metric('Smoke check',testValue(itTests,'smoke'))+metric('Coverage',testValue(itTests,'coveragePercent',null)===null?'—':testValue(itTests,'coveragePercent')+'%')+'</div><ul>'+fixes+'</ul>'+pin+review+((iteration.validationReceipts&&iteration.validationReceipts.length)?'<p><b>Receipts</b></p><ul>'+receipts+'</ul>':'')+appUpdate+'<br><small>Sources: '+citations+'</small></section>';}).join('');return '<article class="card"><span class="tag">'+esc(run.status||'unknown')+'</span><span class="tag">'+esc(target)+'</span><h2>'+esc(run.title||run.file)+'</h2><p class="sub">'+esc(run.startedAt||'Unknown start')+' · '+esc(run.branch||'Unknown branch')+'</p><div class="grid">'+metric('Tests',testValue(tests,'count'))+metric('Coverage',testValue(tests,'coveragePercent',null)===null?'—':testValue(tests,'coveragePercent')+'%')+metric('Duration',testValue(tests,'durationSeconds',null)===null?'—':testValue(tests,'durationSeconds')+'s')+metric('Smoke check',testValue(tests,'smoke'))+'</div><pre>'+esc((run.summary||[]).join('\n'))+'</pre>'+bridge+advisoryBlock+details+'<p><b>Local commits:</b> '+commits+'</p><p><b>Session:</b> '+esc(run.sessionSummary||'—')+'</p></article>';}).join('');
 }).catch(error=>{document.querySelector('#app').innerHTML='<article class="card">Could not load upgrade reports: '+esc(error.message)+'</article>';});
 </script></body></html>`;

package/src/dashboard.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { dashboardPage } from "./dashboard-page.js";
 import { readRun } from "./run-state.js";
+import { advisoryFindings } from "./advisory.js";
 
 const MAX_RUN_FILES = 250;
 const MAX_RUN_BYTES = 1024 * 1024;
@@ -53,8 +54,15 @@ export function startDashboard({ root = process.cwd(), port = 0 } = {}) {
       return response.end("Method not allowed");
     }
     if (request.url === "/api/runs") {
+      // Advisory findings are recomputed per request rather than stored in the
+      // report. They describe the worktree as it stands now, so a stale value in
+      // a historical run would be worse than no value at all.
+      const runs = readUpgradeRuns(root).map((run) => {
+        try { return { ...run, advisories: advisoryFindings({ root, run, inventory: run.inventory ?? {} }) }; }
+        catch { return { ...run, advisories: [] }; }
+      });
       response.writeHead(200, { ...securityHeaders, "content-type": "application/json; charset=utf-8" });
-      return response.end(JSON.stringify(readUpgradeRuns(root)));
+      return response.end(JSON.stringify(runs));
     }
     if (request.url === "/" || request.url === "/index.html") {
       response.writeHead(200, { ...securityHeaders, "content-type": "text/html; charset=utf-8" });

package/src/databases.js

@@ -40,7 +40,11 @@ export const databases = Object.freeze({
     startArgs: () => ["--env", "POSTGRES_HOST_AUTH_METHOD=trust", "--env", `POSTGRES_DB=${DB_NAME}`, "postgres:16-alpine"],
     readyArgs: (container) => ["exec", container, "pg_isready", "-U", "postgres", "-d", DB_NAME],
     // Use the app's own Rails task so framework-specific database setup remains
-    // consistent with the project's PostgreSQL adapter.
+    // consistent with the project's PostgreSQL adapter. DATABASE_URL is already
+    // set on the app container and Rails prefers it over database.yml, so a
+    // project pinning `host: localhost` or a socket-only DSN still resolves to
+    // the isolated container -- no rewriting of the config under test, which
+    // would be a source change to the worktree.
     createArgs: ({ appContainer }) => ["exec", appContainer, "bundle", "exec", "rake", "db:create"],
     databaseUrl: (container) => `postgresql://postgres@${container}:5432/${DB_NAME}`,
     ensureReady: ({ probe }) => readyLoop({ probe, attempts: 30, label: "PostgreSQL" })
@@ -75,18 +79,42 @@ export function resolveDatabase(adapter) {
   return databases[key];
 }
 
+// Declarative forms only. A bare word is not a declaration: real
+// `config/database.yml` files carry YAML keys that merely *name* a profile
+// (rails/rails ships `connections:` with `mysql2:` and `postgresql:` keys and
+// only `adapter: sqlite3` in play), and a Gemfile may carry a driver for an
+// unrelated tool. Matching bare tokens made detection asymmetric -- mysql2
+// matched anywhere while postgres required `adapter:` -- so the bias could only
+// ever produce a false MySQL answer, silently.
+const MYSQL = [/\badapter\s*:\s*mysql2\b/i, /\bgem\s*\(?\s*["']mysql2["']/i, /\bmysql2:\/\//i];
+const POSTGRES = [/\badapter\s*:\s*(?:postgresql|postgres)\b/i, /\bgem\s*\(?\s*["']pg["']/i, /\b(?:postgresql|postgres):\/\//i];
+// Gemfile.lock records resolved specs as `    mysql2 (0.5.6)` / `    pg (1.6.2)`.
+const MYSQL_LOCK = /^[ \t]*mysql2 \(/m;
+const POSTGRES_LOCK = /^[ \t]*pg \(/m;
+
 // Best-effort adapter detection from the project's own declarations. An
 // explicit `--database` always wins; this only fills the gap so the common case
 // needs no flag.
 export function detectDatabase(root = process.cwd()) {
   const read = (file) => { try { return fs.readFileSync(path.join(root, file), "utf8"); } catch { return ""; } };
   const uncommented = (contents) => contents.replace(/#.*$/gm, "");
-  const corpus = [read("Gemfile"), read("Gemfile.lock"), read("config/database.yml")].map(uncommented).join("\n");
-  const mysql = /\bmysql2\b/i.test(corpus) || /adapter:\s*mysql2\b/i.test(corpus);
-  const postgres = /\bpg\b/i.test(corpus) || /adapter:\s*(?:postgresql|postgres)\b/i.test(corpus) || /postgresql:\/\//i.test(corpus);
-  if (mysql && postgres) throw new Error("Both MySQL and PostgreSQL were detected. Specify --database mysql or --database postgres.");
-  if (mysql && !postgres) return "mysql";
-  return "postgres";
+  const declares = (contents, lock) => ({
+    mysql: MYSQL.some((re) => re.test(contents)) || (lock && MYSQL_LOCK.test(contents)),
+    postgres: POSTGRES.some((re) => re.test(contents)) || (lock && POSTGRES_LOCK.test(contents)),
+  });
+  const resolve = ({ mysql, postgres }) => {
+    if (mysql && postgres) throw new Error("Both MySQL and PostgreSQL were detected. Specify --database mysql or --database postgres.");
+    return mysql ? "mysql" : postgres ? "postgres" : null;
+  };
+  // `config/database.yml` is what the app actually connects to; a `gem` line
+  // only says a driver is *available*. Discourse, for instance, is PostgreSQL
+  // (`adapter: postgresql` throughout) but carries `gem "mysql2"` behind an
+  // import-mode conditional. OR-ing both files reported that as ambiguous and
+  // needlessly forced an explicit flag on an unambiguous project.
+  const configured = resolve(declares(uncommented(read("config/database.yml")), false));
+  if (configured) return configured;
+  const gems = resolve(declares(`${uncommented(read("Gemfile"))}\n${uncommented(read("Gemfile.lock"))}`, true));
+  return gems ?? "postgres";
 }
 
 export { DB_NAME, NAME };

package/src/inventory.js

@@ -23,7 +23,11 @@ export function inventoryProject(root = process.cwd()) {
   const deploy = ["Dockerfile", "docker-compose.yml", "Procfile", "app.json", "render.yaml", "fly.toml", "config/deploy.yml"].filter((file) => exists(root, file));
   return {
     root, supported: exists(root, "Gemfile"), framework: rails ? "rails" : "ruby", testFramework: rspec ? "rspec" : minitest ? "minitest" : "unknown",
-    rubyDeclarations, rails: rails ? { declaredVersion: declaredRails, resolvedVersion: resolvedRails } : null, recommendedCommands: commands, ci, deploy,
+    rubyDeclarations, rails: rails ? { declaredVersion: declaredRails, resolvedVersion: resolvedRails } : null,
+    // Bundler switches to the version under `BUNDLED WITH`, so this is the
+    // version that will actually run -- not merely the newest one installed.
+    bundler: { bundledWith: lockfile.match(/^BUNDLED WITH\s*\r?\n\s+(\d+(?:\.\d+)+)/m)?.[1] ?? null },
+    recommendedCommands: commands, ci, deploy,
     requiresDecision: !exists(root, "Gemfile") || commands.length === 0,
     reason: !exists(root, "Gemfile") ? "No Gemfile found." : commands.length === 0 ? "No recognized test adapter found." : undefined
   };