opencode-ruby-upgrader 0.1.0

package/src/run-state.js

@@ -0,0 +1,200 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const SECRET_VALUE = /(?:gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|\bAKIA[0-9A-Z]{16}\b|-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----|\b(?:xox[baprs]-|npm_|glpat-)[A-Za-z0-9_-]{16,})/g;
+const SECRET_KEY = /(?:password|secret|token|api[_-]?key|credential|authorization)/i;
+const URL_CREDENTIALS = /([a-z][a-z0-9+.-]*:\/\/)[^\s/@]*@/ig;
+const URL_SECRET_QUERY = /([?&](?:password|secret|token|api[_-]?key|credential|authorization)=)[^&#\s]*/ig;
+const statuses = new Set(["in_progress", "paused", "blocked", "complete"]);
+const phases = new Set(["initialized", "inventory_complete", "research_complete", "hop_validated", "committed", "paused", "blocked", "complete"]);
+const reportName = /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/;
+
+export class RunStateError extends Error {
+  constructor(message, code) { super(message); this.code = code; }
+}
+
+export function redact(value, key = "") {
+  if (/^(?:root|worktreeRoot)$/i.test(key)) return "[LOCAL PATH]";
+  if (SECRET_KEY.test(key)) return "[REDACTED]";
+  if (typeof value === "string") return redactSourceUrl(value).replace(SECRET_VALUE, "[REDACTED]");
+  if (Array.isArray(value)) return value.map((item) => redact(item));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, redact(item, name)]));
+  return value;
+}
+
+export function redactSourceUrl(value) {
+  return typeof value === "string" ? value.replace(URL_CREDENTIALS, "$1[REDACTED]@").replace(URL_SECRET_QUERY, "$1[REDACTED]") : value;
+}
+
+function validVersion(value) { return typeof value === "string" && /^\d+\.\d+(?:\.(?:\d+|x))?$/.test(value); }
+function validRailsVersion(value) { return typeof value === "string" && /^\d+(?:\.\d+)+$/.test(value); }
+function validCitation(value) { return value && typeof value.title === "string" && /^https:\/\//.test(value.url ?? ""); }
+function safeFiles(files) { return Array.isArray(files) && files.every((file) => typeof file === "string" && !path.isAbsolute(file) && !file.includes("..")); }
+function validAppUpdateReview(review) { return review && review.command === "bin/rails app:update" && typeof review.receiptId === "string" && !Number.isNaN(Date.parse(review.executedAt ?? "")) && !Number.isNaN(Date.parse(review.reviewedAt ?? "")) && validFingerprint(review.worktree) && ["no_changes", "changes_applied", "changes_deferred"].includes(review.outcome) && safeFiles(review.files) && typeof review.summary === "string" && Boolean(review.summary); }
+function validFingerprint(fingerprint) { return fingerprint && fingerprint.algorithm === "sha256" && /^[a-f0-9]{40}$/i.test(fingerprint.headSha ?? "") && /^[a-f0-9]{64}$/i.test(fingerprint.diffSha256 ?? ""); }
+function validReceipt(receipt) { return receipt && receipt.receiptVersion === 1 && typeof receipt.id === "string" && /^[a-f0-9-]{36}$/i.test(receipt.id) && ["test", "rails_app_update"].includes(receipt.kind) && typeof receipt.commandId === "string" && Array.isArray(receipt.argv) && !Number.isNaN(Date.parse(receipt.startedAt ?? "")) && !Number.isNaN(Date.parse(receipt.finishedAt ?? "")) && typeof receipt.durationMs === "number" && (typeof receipt.exitCode === "number" || receipt.exitCode === null) && typeof receipt.timedOut === "boolean" && /^[a-f0-9]{64}$/i.test(receipt.output?.redactedSha256 ?? "") && Number.isSafeInteger(receipt.output?.bytes) && receipt.output.bytes >= 0 && receipt.output.summary === undefined && validFingerprint(receipt.worktree); }
+function receiptErrors(iteration, index, rails, required, errors) {
+  const receipts = iteration?.validationReceipts;
+  if (!required && receipts === undefined) return;
+  if (!Array.isArray(receipts) || !receipts.length || receipts.some((receipt) => !validReceipt(receipt))) errors.push(`${rails ? "Rails " : ""}iteration ${index + 1} requires valid executed validation receipts.`);
+  if (iteration?.tests?.passed === true && !receipts?.some((receipt) => receipt.kind === "test" && receipt.exitCode === 0 && receipt.testEvidence?.passed === true)) errors.push(`${rails ? "Rails " : ""}iteration ${index + 1} requires a passing executed test receipt.`);
+  if (rails && !receipts?.some((receipt) => receipt.kind === "rails_app_update" && receipt.exitCode === 0)) errors.push(`Rails iteration ${index + 1} requires a successful executed app:update receipt.`);
+  if (rails) {
+    const update = receipts?.[0];
+    const test = receipts?.at(-1);
+    const review = iteration?.appUpdateReview;
+    if (receipts?.length !== 2 || update?.kind !== "rails_app_update" || update.exitCode !== 0 || test?.kind !== "test" || test.exitCode !== 0 || test.testEvidence?.passed !== true || !review || review.receiptId !== update.id || review.executedAt !== update.startedAt || review.worktree.headSha !== update.worktree.headSha || review.worktree.diffSha256 !== update.worktree.diffSha256 || Date.parse(update.finishedAt) > Date.parse(review.reviewedAt) || Date.parse(review.reviewedAt) > Date.parse(test.startedAt)) errors.push(`Rails iteration ${index + 1} must execute app:update, review its receipt and diff, then run final passing tests.`);
+  }
+}
+
+function validateRailsBridge(run, errors) {
+  for (const key of ["runId", "title", "startedAt", "targetRails", "targetRailsPinnedAt", "phase", "status", "bridge"]) if (!run[key]) errors.push(`Rails bridge report requires ${key}.`);
+  if (!validRailsVersion(run.targetRails)) errors.push("targetRails must be a Rails version.");
+  if (typeof run.runId !== "string" || !/^[a-f0-9-]{36}$/i.test(run.runId ?? "")) errors.push("runId must be a UUID.");
+  if (run.startedAt && Number.isNaN(Date.parse(run.startedAt))) errors.push("startedAt must be ISO-8601.");
+  if (!statuses.has(run.status) || !phases.has(run.phase)) errors.push("Rails bridge has invalid status or phase.");
+  if (run.lockNonce !== undefined && (typeof run.lockNonce !== "string" || !/^[a-f0-9-]{36}$/i.test(run.lockNonce))) errors.push("lockNonce must be a UUID.");
+  if (run.targetRailsPinnedAt && Number.isNaN(Date.parse(run.targetRailsPinnedAt))) errors.push("targetRailsPinnedAt must be ISO-8601.");
+  if (!run.bridge || typeof run.bridge !== "object" || typeof run.bridge.rubyReportPath !== "string" || !/^[a-f0-9-]{36}$/i.test(run.bridge.rubyRunId ?? "") || !validVersion(run.bridge.rubyFrom) || !validVersion(run.bridge.rubyTo) || !validRailsVersion(run.bridge.railsFrom) || !validRailsVersion(run.bridge.railsTo)) errors.push("Rails bridge report has invalid Ruby-run linkage.");
+  if (!Array.isArray(run.research?.ladder) || run.research.ladder.some((version) => !validRailsVersion(version))) errors.push("Rails bridge research.ladder must contain Rails versions.");
+  if (!Array.isArray(run.research?.citations) || run.research.citations.some((citation) => !validCitation(citation))) errors.push("research.citations must contain HTTPS citations.");
+  if (!Array.isArray(run.iterations)) errors.push("iterations must be an array.");
+  if (run.pendingAppUpdate !== undefined && (!validReceipt(run.pendingAppUpdate) || run.pendingAppUpdate.kind !== "rails_app_update" || run.pendingAppUpdate.exitCode !== 0 || !["research_complete", "committed"].includes(run.phase))) errors.push("Rails bridge pending app:update receipt is invalid.");
+  for (const [index, iteration] of (run.iterations ?? []).entries()) {
+    if (!validRailsVersion(iteration?.from) || !validRailsVersion(iteration?.to) || iteration?.status !== "complete") errors.push(`Rails iteration ${index + 1} is invalid.`);
+    if (!safeFiles(iteration?.files) || iteration?.tests?.passed !== true || !iteration.tests?.command || !iteration.tests?.smoke || !Array.isArray(iteration?.citations) || !iteration.citations.length || !Array.isArray(iteration?.fixes) || iteration.fixes.some((fix) => !safeFiles(fix.files) || !fix.explanation)) errors.push(`Rails iteration ${index + 1} lacks required evidence.`);
+    if (!validAppUpdateReview(iteration?.appUpdateReview)) errors.push(`Rails iteration ${index + 1} requires reviewed bin/rails app:update evidence.`);
+    if (iteration?.appUpdateReview?.outcome === "changes_applied" && iteration.appUpdateReview.files.some((file) => !iteration.files.includes(file))) errors.push(`Rails iteration ${index + 1} must declare applied app:update files.`);
+    if (iteration?.checkpointSha !== undefined && !/^[a-f0-9]{40}$/i.test(iteration.checkpointSha)) errors.push(`Rails iteration ${index + 1} checkpointSha must be a Git SHA.`);
+    receiptErrors(iteration, index, true, run.validationReceiptsRequired === true, errors);
+  }
+}
+
+export function validateRun(run) {
+  const errors = [];
+  if (!run || typeof run !== "object" || Array.isArray(run)) return { valid: false, errors: ["Report must be a JSON object."] };
+  if (run.schemaVersion !== 2) errors.push("Report schemaVersion must be 2.");
+  if (run.validationReceiptsRequired !== undefined && run.validationReceiptsRequired !== true) errors.push("validationReceiptsRequired must be true when present.");
+  if (run.reportType === "rails_bridge") { validateRailsBridge(run, errors); return { valid: errors.length === 0, errors }; }
+  if (run.reportType !== undefined && run.reportType !== "ruby") errors.push("Unknown reportType.");
+  for (const key of ["runId", "title", "startedAt", "targetRuby", "targetPinnedAt", "phase", "status"]) if (!run[key]) errors.push(`Report requires ${key}.`);
+  if (run.lockNonce !== undefined && (typeof run.lockNonce !== "string" || !/^[a-f0-9-]{36}$/i.test(run.lockNonce))) errors.push("lockNonce must be a UUID.");
+  if (typeof run.runId !== "string" || !/^[a-f0-9-]{36}$/i.test(run.runId ?? "")) errors.push("runId must be a UUID.");
+  if (run.startedAt && Number.isNaN(Date.parse(run.startedAt))) errors.push("startedAt must be ISO-8601.");
+  if (!validVersion(run.targetRuby)) errors.push("targetRuby must be a Ruby version.");
+  if (run.targetPinnedAt && Number.isNaN(Date.parse(run.targetPinnedAt))) errors.push("targetPinnedAt must be ISO-8601.");
+  if (!statuses.has(run.status)) errors.push("Invalid run status.");
+  if (!phases.has(run.phase)) errors.push("Invalid run phase.");
+  if (!Array.isArray(run.iterations)) errors.push("iterations must be an array.");
+  if (!Array.isArray(run.research?.ladder) || run.research.ladder.some((version) => !validVersion(version))) errors.push("research.ladder must be Ruby versions.");
+  if (!Array.isArray(run.research?.citations) || run.research.citations.some((citation) => !validCitation(citation))) errors.push("research.citations must contain HTTPS citations.");
+  if (!Array.isArray(run.riskDecisions)) errors.push("riskDecisions must be an array.");
+  if (run.requiredRisks !== undefined && (!Array.isArray(run.requiredRisks) || run.requiredRisks.some((risk) => typeof risk !== "string"))) errors.push("requiredRisks must be string identifiers.");
+  if (run.frameworkBridge !== undefined && run.frameworkBridge !== null) {
+    const bridge = run.frameworkBridge;
+    if (!bridge || typeof bridge !== "object" || bridge.status !== "approved") errors.push("frameworkBridge must be an approved compatibility decision.");
+    if (!validVersion(bridge?.rubyFrom) || !validVersion(bridge?.rubyTo) || !validRailsVersion(bridge?.railsFrom) || !validRailsVersion(bridge?.railsTo)) errors.push("frameworkBridge requires Ruby and Rails from/to versions.");
+    if (typeof bridge?.rationale !== "string" || !bridge.rationale) errors.push("frameworkBridge requires a rationale.");
+    if (!Array.isArray(bridge?.citations) || !bridge.citations.length || bridge.citations.some((citation) => !validCitation(citation))) errors.push("frameworkBridge requires HTTPS citations.");
+  }
+  for (const [index, iteration] of (run.iterations ?? []).entries()) {
+    if (!validVersion(iteration?.from) || !validVersion(iteration?.to)) errors.push(`Iteration ${index + 1} requires Ruby from/to versions.`);
+    if (iteration?.status !== "complete") errors.push(`Iteration ${index + 1} must be complete.`);
+    if (!safeFiles(iteration?.files)) errors.push(`Iteration ${index + 1} files must be safe relative paths.`);
+    if (iteration?.tests?.passed !== true || typeof iteration.tests.command !== "string" || !iteration.tests.command) errors.push(`Iteration ${index + 1} requires passing test evidence.`);
+    if (typeof iteration.tests.smoke !== "string" || !iteration.tests.smoke) errors.push(`Iteration ${index + 1} requires smoke evidence.`);
+    if (!Array.isArray(iteration.citations) || iteration.citations.length === 0 || iteration.citations.some((citation) => !validCitation(citation))) errors.push(`Iteration ${index + 1} requires HTTPS citations.`);
+    if (!Array.isArray(iteration.fixes) || iteration.fixes.some((fix) => !Array.isArray(fix.files) || typeof fix.explanation !== "string" || !fix.explanation)) errors.push(`Iteration ${index + 1} requires explained fixes.`);
+    if (iteration.dependencyReview && (iteration.dependencyReview.completed !== true || typeof iteration.dependencyReview.compatibility !== "string" || typeof iteration.dependencyReview.licenses !== "string")) errors.push(`Iteration ${index + 1} dependency review is incomplete.`);
+    if (iteration.checkpointSha !== undefined && !/^[a-f0-9]{40}$/i.test(iteration.checkpointSha)) errors.push(`Iteration ${index + 1} checkpointSha must be a Git SHA.`);
+    receiptErrors(iteration, index, false, run.validationReceiptsRequired === true, errors);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function canonicalRoot(root) { return fs.realpathSync(root); }
+function runsDirectory(root, create = false) {
+  const canonical = canonicalRoot(root);
+  let current = canonical;
+  for (const component of [".ruby-upgrades", "runs"]) {
+    current = path.join(current, component);
+    if (!fs.existsSync(current)) {
+      if (!create) return current;
+      fs.mkdirSync(current, { mode: 0o700 });
+    }
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new RunStateError("Upgrade evidence directories must be real directories inside the worktree.", "unsafe-report-path");
+  }
+  return current;
+}
+
+function reportPath(root, relativePath, create = false) {
+  if (typeof relativePath !== "string" || relativePath !== path.join(".ruby-upgrades", "runs", path.basename(relativePath)) || !reportName.test(path.basename(relativePath))) throw new RunStateError("Report must be a generated JSON basename under .ruby-upgrades/runs/.", "invalid-report-path");
+  const directory = runsDirectory(root, create);
+  const file = path.join(directory, path.basename(relativePath));
+  if (fs.existsSync(file)) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new RunStateError("Report must be a regular file inside the worktree.", "unsafe-report-path");
+  }
+  return file;
+}
+
+export function readRun(root, relativePath) {
+  try {
+    const run = JSON.parse(fs.readFileSync(reportPath(root, relativePath), "utf8"));
+    const validation = validateRun(run);
+    if (!validation.valid) throw new RunStateError(validation.errors.join(" "), "invalid-report");
+    return redact(run);
+  } catch (error) {
+    if (error instanceof RunStateError) throw error;
+    throw new RunStateError("The upgrade report is missing or invalid JSON.", "invalid-report");
+  }
+}
+
+export function writeRun(root, relativePath, run) {
+  const validation = validateRun(run);
+  if (!validation.valid) throw new RunStateError(validation.errors.join(" "), "invalid-report");
+  const file = reportPath(root, relativePath, true);
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  fs.writeFileSync(temporary, `${JSON.stringify(redact(run), null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  fs.renameSync(temporary, file);
+  const markdown = file.replace(/\.json$/, ".md");
+  if (fs.existsSync(markdown) && (!fs.lstatSync(markdown).isFile() || fs.lstatSync(markdown).isSymbolicLink())) throw new RunStateError("Markdown evidence must be a regular file inside the worktree.", "unsafe-report-path");
+  const safe = redact(run);
+  const target = safe.reportType === "rails_bridge" ? `- **Target Rails:** ${safe.targetRails}` : `- **Target Ruby:** ${safe.targetRuby}`;
+  const markdownBody = `# ${safe.title}\n\n- **Status:** ${safe.status}\n- **Phase:** ${safe.phase}\n${target}\n- **Started:** ${safe.startedAt}\n\n## Durable evidence\n\n\`\`\`json\n${JSON.stringify(safe, null, 2)}\n\`\`\`\n`;
+  const markdownTemporary = path.join(path.dirname(markdown), `.${path.basename(markdown)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  fs.writeFileSync(markdownTemporary, markdownBody, { mode: 0o600, flag: "wx" });
+  fs.renameSync(markdownTemporary, markdown);
+}
+
+function lockPath(root) {
+  try { return execFileSync("git", ["rev-parse", "--git-path", "opencode-ruby-upgrade.lock"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
+  catch { return path.join(runsDirectory(root, true), ".run.lock"); }
+}
+export function acquireRunLock(root, relativePath) {
+  reportPath(root, relativePath, true);
+  const file = lockPath(root);
+  const payload = { pid: process.pid, nonce: crypto.randomUUID(), report: relativePath, acquiredAt: new Date().toISOString() };
+  try { fs.writeFileSync(file, `${JSON.stringify(payload)}\n`, { flag: "wx", mode: 0o600 }); return payload; }
+  catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    let current = {}; try { current = JSON.parse(fs.readFileSync(file, "utf8")); } catch { /* explicit recovery only */ }
+    throw new RunStateError(`An upgrade lock exists for ${current.report ?? "an unknown run"}. Inspect it, then explicitly release it if the prior session is gone.`, "run-locked");
+  }
+}
+export function assertRunLock(root, relativePath, expectedNonce) {
+  try {
+    const current = JSON.parse(fs.readFileSync(lockPath(root), "utf8"));
+    if (current.report !== relativePath || !current.nonce || (expectedNonce && current.nonce !== expectedNonce)) throw new RunStateError("Another upgrade run owns the worktree lock.", "lock-owner-mismatch");
+    return current;
+  } catch (error) { if (error instanceof RunStateError) throw error; throw new RunStateError("No active run lock exists. Resume the recorded run before continuing.", "run-lock-missing"); }
+}
+export function releaseRunLock(root, relativePath, expectedNonce) {
+  const file = lockPath(root); const current = assertRunLock(root, relativePath, expectedNonce);
+  const latest = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (latest.nonce !== current.nonce) throw new RunStateError("Lock changed while releasing; refusing to remove it.", "lock-raced");
+  fs.rmSync(file);
+}

package/src/supply-chain.js

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+import path from "node:path";
+import { redactSourceUrl } from "./run-state.js";
+
+export function inspectSupplyChain(root = process.cwd()) {
+  const lockfile = path.join(root, "Gemfile.lock");
+  const gemfile = path.join(root, "Gemfile");
+  if (!fs.existsSync(lockfile) && !fs.existsSync(gemfile)) return { lockfile: null, sources: [], privateSources: [], dependencyCount: 0, vulnerabilityStatus: "unavailable", licenseStatus: "unavailable" };
+  const contents = fs.existsSync(lockfile) ? fs.readFileSync(lockfile, "utf8") : "";
+  const gemfileContents = fs.existsSync(gemfile) ? fs.readFileSync(gemfile, "utf8") : "";
+  const sources = [...contents.matchAll(/^\s*remote:\s*(.+)$/gm)].map((match) => redactSourceUrl(match[1].trim()));
+  const declaredSources = [...gemfileContents.matchAll(/(?:git|github|path)\s*:\s*["']([^"']+)["']/g), ...gemfileContents.matchAll(/\bsource\s*["']([^"']+)["']/g)].map((match) => redactSourceUrl(match[1]));
+  const privateSources = [...sources, ...declaredSources].filter((source) => !/^https:\/\/rubygems\.org\/?$/i.test(source));
+  const dependencyCount = (contents.match(/^    [\w.-]+ \(/gm) ?? []).length;
+  return { lockfile: fs.existsSync(lockfile) ? "Gemfile.lock" : null, sources, declaredSources, privateSources, dependencyCount, vulnerabilityStatus: "requires_bundle_audit_review", licenseStatus: "requires_bundle_license_review" };
+}

package/src/target-runtime.js

@@ -0,0 +1,165 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { RunStateError, readRun } from "./run-state.js";
+
+const RUNTIME_FILE = "runtime.json";
+const LABEL = "io.opencode-ruby-upgrader.run-id";
+const rubyVersion = /^\d+\.\d+\.\d+$/;
+const NODE_INSTALL = "set -eu; . /etc/os-release; codename=${VERSION_CODENAME:-stretch}; printf '%s\\n' \"deb http://deb.debian.org/debian ${codename} main\" > /etc/apt/sources.list; printf '%s\\n' 'Acquire::Check-Valid-Until \"false\";' > /etc/apt/apt.conf.d/99archive; if ! apt-get update; then printf '%s\\n' \"deb http://archive.debian.org/debian ${codename} main\" > /etc/apt/sources.list; apt-get update; fi; apt-get install -y --no-install-recommends nodejs; if [ ! -x /usr/bin/node ]; then ln -sf /usr/bin/nodejs /usr/local/bin/node; fi; node --version";
+
+function canonicalRoot(root) { return fs.realpathSync(root); }
+function upgradesDirectory(root, create = false) {
+  const directory = path.join(canonicalRoot(root), ".ruby-upgrades");
+  if (!fs.existsSync(directory) && create) fs.mkdirSync(directory, { mode: 0o700 });
+  if (fs.existsSync(directory)) {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(".ruby-upgrades must be a real directory inside the worktree.");
+  }
+  return directory;
+}
+function runtimePath(root, create = false) {
+  const file = path.join(upgradesDirectory(root, create), RUNTIME_FILE);
+  if (fs.existsSync(file)) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Target runtime metadata must be a regular file.");
+  }
+  return file;
+}
+function docker(spawn, args) {
+  const result = spawn("docker", args, { shell: false, encoding: "utf8", maxBuffer: 256 * 1024 });
+  if (result.error) throw new Error(`Docker command failed: ${result.error.message}`);
+  return result;
+}
+function waitForPostgres(spawn, runtime) {
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    if (docker(spawn, ["exec", runtime.postgresContainer, "pg_isready", "-U", "postgres", "-d", "ruby_upgrade_test"]).status === 0) return;
+    Atomics.wait(sleeper, 0, 0, 1000);
+  }
+  throw new Error("Target PostgreSQL did not become ready within 30 seconds. Rerun prepare-target-runtime --ruby <x.y.z>.");
+}
+function preparationResult(result) {
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  return { sha256: crypto.createHash("sha256").update(output).digest("hex"), bytes: Buffer.byteLength(output) };
+}
+function bootstrap(spawn, runtime, rails) {
+  const labels = ["Node.js setup", "Bundler installation", "dependency installation", ...(rails ? ["Rails test database initialization"] : []), "Ruby version attestation"];
+  const commands = [
+    ["exec", runtime.appContainer, "sh", "-c", NODE_INSTALL],
+    ["exec", runtime.appContainer, "gem", "install", "bundler", "-v", "2.4.22", "--no-document"],
+    ["exec", runtime.appContainer, "bundle", "_2.4.22_", "install"],
+    ...(rails ? [["exec", runtime.appContainer, "bundle", "exec", "rake", "db:create"]] : []),
+    ["exec", runtime.appContainer, "ruby", "--version"]
+  ];
+  const results = commands.map((args, index) => {
+    const result = docker(spawn, args);
+    if (result.status !== 0) throw new Error(`Target runtime bootstrap failed during ${labels[index]}. Rerun prepare-target-runtime --ruby <x.y.z>.`);
+    return result;
+  });
+  const rubyOutput = `${results.at(-1).stdout ?? ""}${results.at(-1).stderr ?? ""}`;
+  if (!new RegExp(`^ruby ${runtime.ruby.replaceAll(".", "\\.")}(?:p\\d+|\\s|$)`).test(rubyOutput.trim())) throw new Error("Target runtime did not execute the requested Ruby version.");
+  return {
+    node: preparationResult(results[0]),
+    bundler: preparationResult(results[1]),
+    bundleInstall: preparationResult(results[2]),
+    ...(rails ? { databaseCreate: preparationResult(results[3]) } : {}),
+    rubyVersion: preparationResult(results.at(-1))
+  };
+}
+function railsProject(root) {
+  const gemfile = path.join(root, "Gemfile");
+  return fs.existsSync(gemfile) && /^\s*gem\s+["']rails["']/m.test(fs.readFileSync(gemfile, "utf8"));
+}
+function inspect(spawn, name, message) {
+  const result = docker(spawn, ["inspect", name]);
+  if (result.status !== 0) throw new Error(message);
+  try { const parsed = JSON.parse(result.stdout); return parsed[0]; } catch { throw new Error("Docker inspection returned invalid JSON."); }
+}
+function activeRun(root) {
+  const directory = path.join(upgradesDirectory(root), "runs");
+  if (!fs.existsSync(directory)) throw new RunStateError("No active or paused upgrade run exists. Start or resume a run first.", "no-active-run");
+  const candidates = fs.readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/.test(entry.name))
+    .map((entry) => `.ruby-upgrades/runs/${entry.name}`)
+    .map((reportPath) => ({ reportPath, run: readRun(root, reportPath) }))
+    .filter(({ run }) => ["in_progress", "paused"].includes(run.status));
+  if (candidates.length !== 1) throw new RunStateError(candidates.length ? "Multiple active or paused upgrade runs exist. Resolve them before preparing a target runtime." : "No active or paused upgrade run exists. Start or resume a run first.", candidates.length ? "ambiguous-active-run" : "no-active-run");
+  return candidates[0];
+}
+function selectedRun(root, reportPath) {
+  if (!reportPath) return activeRun(root);
+  const run = readRun(root, reportPath);
+  if (!["in_progress", "paused"].includes(run.status)) throw new RunStateError("Target runtime preparation requires an active or paused upgrade run.", "run-not-resumable");
+  return { reportPath, run };
+}
+function names(runId) {
+  const prefix = `ruby-upgrader-${runId}`;
+  return { appContainer: `${prefix}-app`, postgresContainer: `${prefix}-postgres`, network: `${prefix}-network` };
+}
+function writeRuntime(root, runtime) {
+  const file = runtimePath(root, true);
+  const temporary = path.join(path.dirname(file), `.${RUNTIME_FILE}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  fs.writeFileSync(temporary, `${JSON.stringify(runtime, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  fs.renameSync(temporary, file);
+}
+
+export function readTargetRuntime(root = process.cwd()) {
+  const file = runtimePath(root);
+  if (!fs.existsSync(file)) return undefined;
+  try {
+    const runtime = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (runtime?.version !== 2 || typeof runtime.runId !== "string" || !rubyVersion.test(runtime.ruby ?? "") || !/^sha256:[a-f0-9]{64}$/i.test(runtime.resolvedImageId ?? "") || !runtime.preparation || ![runtime.appContainer, runtime.postgresContainer, runtime.network].every((name) => /^[a-z0-9][a-z0-9-]{0,127}$/.test(name ?? ""))) throw new Error();
+    return runtime;
+  } catch { throw new Error("Target runtime metadata is invalid. Rerun prepare-target-runtime --ruby <x.y.z>."); }
+}
+
+export function prepareTargetRuntime({ root = process.cwd(), reportPath, ruby, spawn = spawnSync }) {
+  if (!rubyVersion.test(ruby ?? "")) throw new Error("--ruby must be an exact numeric Ruby version such as 3.4.1.");
+  const canonical = canonicalRoot(root);
+  const selected = selectedRun(canonical, reportPath);
+  const runtime = { version: 2, runId: selected.run.runId, reportPath: selected.reportPath, ruby, ...names(selected.run.runId) };
+  const existing = readTargetRuntime(canonical);
+  if (existing && existing.runId !== runtime.runId) {
+    const prior = readRun(canonical, existing.reportPath);
+    if (!["blocked", "complete"].includes(prior.status)) throw new Error("Target runtime metadata belongs to another resumable run. Pause and resolve that run before preparing this one.");
+  }
+
+  const network = docker(spawn, ["network", "inspect", runtime.network]);
+  if (network.status !== 0 && docker(spawn, ["network", "create", "--label", `${LABEL}=${selected.run.runId}`, runtime.network]).status !== 0) throw new Error("Could not create the isolated target-runtime Docker network.");
+  const postgres = docker(spawn, ["inspect", runtime.postgresContainer]);
+  if (postgres.status !== 0 && docker(spawn, ["run", "--detach", "--name", runtime.postgresContainer, "--label", `${LABEL}=${selected.run.runId}`, "--network", runtime.network, "--env", "POSTGRES_HOST_AUTH_METHOD=trust", "--env", "POSTGRES_DB=ruby_upgrade_test", "postgres:16-alpine"]).status !== 0) throw new Error("Could not start the isolated target-runtime PostgreSQL container.");
+  waitForPostgres(spawn, runtime);
+  let app = docker(spawn, ["inspect", runtime.appContainer]);
+  if (app.status === 0 && existing && existing.ruby !== ruby) {
+    let container;
+    try { [container] = JSON.parse(app.stdout); } catch { throw new Error("Docker validation container inspection returned invalid JSON."); }
+    if (container?.Config?.Labels?.[LABEL] !== selected.run.runId) throw new Error("Refusing to replace an app container not labelled for this run.");
+    if (docker(spawn, ["rm", "--force", runtime.appContainer]).status !== 0) throw new Error("Could not replace the prior target Ruby app container.");
+    app = docker(spawn, ["inspect", runtime.appContainer]);
+  }
+  if (app.status !== 0 && docker(spawn, ["run", "--detach", "--name", runtime.appContainer, "--label", `${LABEL}=${selected.run.runId}`, "--network", runtime.network, "--mount", `type=bind,src=${canonical},dst=/app`, "--workdir", "/app", "--env", "RAILS_ENV=test", "--env", `DATABASE_URL=postgresql://postgres@${runtime.postgresContainer}:5432/ruby_upgrade_test`, `ruby:${ruby}`, "sleep", "infinity"]).status !== 0) throw new Error("Could not start the target Ruby app container.");
+  const prepared = bootstrap(spawn, runtime, railsProject(canonical));
+  const appInspection = inspect(spawn, runtime.appContainer, "Target Ruby app container is unavailable. Rerun prepare-target-runtime --ruby <x.y.z>.");
+  if (!/^sha256:[a-f0-9]{64}$/i.test(appInspection?.Image ?? "")) throw new Error("Target Ruby image ID is unavailable.");
+  runtime.resolvedImageId = appInspection.Image;
+  runtime.preparation = prepared;
+  validateTargetRuntime({ root: canonical, runtime, spawn });
+  writeRuntime(canonical, runtime);
+  return runtime;
+}
+
+export function validateTargetRuntime({ root = process.cwd(), runtime = readTargetRuntime(root), spawn = spawnSync }) {
+  if (!runtime) return undefined;
+  const canonical = canonicalRoot(root);
+  const app = inspect(spawn, runtime.appContainer, "Target Ruby app container is unavailable. Rerun prepare-target-runtime --ruby <x.y.z>.");
+  const postgres = inspect(spawn, runtime.postgresContainer, "Target PostgreSQL container is unavailable. Rerun prepare-target-runtime --ruby <x.y.z>.");
+  const env = Object.fromEntries((app?.Config?.Env ?? []).map((entry) => { const index = entry.indexOf("="); return [entry.slice(0, index), entry.slice(index + 1)]; }));
+  const mountedRoot = app?.Mounts?.some((mount) => mount.Type === "bind" && mount.Source === canonical && mount.Destination === "/app");
+  const appNetwork = app?.NetworkSettings?.Networks?.[runtime.network];
+  const postgresNetwork = postgres?.NetworkSettings?.Networks?.[runtime.network];
+  const valid = app?.State?.Running && postgres?.State?.Running && app?.Config?.Labels?.[LABEL] === runtime.runId && postgres?.Config?.Labels?.[LABEL] === runtime.runId && app?.Config?.Image === `ruby:${runtime.ruby}` && app?.Image === runtime.resolvedImageId && app?.Config?.WorkingDir === "/app" && mountedRoot && appNetwork && postgresNetwork && env.RAILS_ENV === "test" && env.DATABASE_URL === `postgresql://postgres@${runtime.postgresContainer}:5432/ruby_upgrade_test`;
+  if (!valid) throw new Error("Target runtime no longer matches its prepared run. Rerun prepare-target-runtime --ruby <x.y.z>.");
+  return { name: runtime.appContainer, id: app.Id, imageId: app.Image, imageRef: app.Config.Image, ruby: runtime.ruby };
+}

package/src/test-evidence.js

@@ -0,0 +1,9 @@
+export function parseTestEvidence(output, command, durationSeconds = null) {
+  const rspec = output.match(/(\d+) examples?,\s*(\d+) failures?/i);
+  const minitest = output.match(/(\d+) runs?,\s*(\d+) assertions?,\s*(\d+) failures?,\s*(\d+) errors?/i);
+  const elapsed = output.match(/Finished in\s+([\d.]+)\s+seconds/i);
+  const duration = durationSeconds ?? (elapsed ? Number(elapsed[1]) : null);
+  if (rspec) return { command, count: Number(rspec[1]), passed: Number(rspec[2]) === 0, failures: Number(rspec[2]), durationSeconds: duration, coveragePercent: null };
+  if (minitest) return { command, count: Number(minitest[1]), passed: Number(minitest[3]) + Number(minitest[4]) === 0, failures: Number(minitest[3]) + Number(minitest[4]), assertions: Number(minitest[2]), durationSeconds: duration, coveragePercent: null };
+  return { command, count: null, passed: null, failures: null, durationSeconds: duration, coveragePercent: null, parseStatus: "unrecognized" };
+}

package/src/validation-executor.js

@@ -0,0 +1,45 @@
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { redact } from "./run-state.js";
+import { parseTestEvidence } from "./test-evidence.js";
+import { worktreeFingerprint } from "./provenance.js";
+import { readTargetRuntime, validateTargetRuntime } from "./target-runtime.js";
+
+const railsAppUpdateSkipExisting = [
+  'require "./config/application"',
+  'require "rails/generators"',
+  'require "rails/generators/rails/app/app_generator"',
+  'generator = Rails::Generators::AppGenerator.new(["rails"], { api: !!Rails.application.config.api_only, update: true }, destination_root: Rails.root, behavior: :skip)',
+  'File.exist?(Rails.root.join("config", "application.rb")) ? generator.send(:app_const) : generator.send(:valid_const?)',
+  '[:create_boot_file, :update_config_files, :create_bin_files, :display_upgrade_guide_info].each { |method| generator.send(method) }',
+].join("; ");
+
+const commands = Object.freeze({
+  "bundle-rspec": { argv: ["bundle", "exec", "rspec"], kind: "test", expected: "bundle exec rspec" },
+  "docker-bundle-rspec": { argv: ["bundle", "exec", "rspec"], kind: "test", expected: "bundle exec rspec", docker: true },
+  "bundle-rails-test": { argv: ["bundle", "exec", "rails", "test"], kind: "test", expected: "bundle exec rails test" },
+  "bundle-rake-test": { argv: ["bundle", "exec", "rake", "test"], kind: "test", expected: "bundle exec rake test" },
+  "bin-rails-test": { argv: ["bin/rails", "test"], kind: "test", expected: "bin/rails test" },
+  "rails-app-update": { argv: ["bundle", "exec", "ruby", "-e", railsAppUpdateSkipExisting], kind: "rails_app_update", expected: "bin/rails app:update", docker: true }
+});
+
+function dockerContainer(root, spawn) {
+  const runtime = readTargetRuntime(root);
+  if (!runtime) throw new Error("Prepare the isolated target runtime with prepare-target-runtime --ruby <x.y.z> before Docker validation.");
+  return validateTargetRuntime({ root, runtime, spawn });
+}
+
+export function executeValidation({ root = process.cwd(), inventory, commandId, timeoutMs = 600000, spawn = spawnSync }) {
+  const definition = commands[commandId];
+  if (!definition) throw new Error("Unknown validation command ID.");
+  if (definition.kind === "rails_app_update" ? inventory.framework !== "rails" : !inventory.recommendedCommands.includes(definition.expected)) throw new Error("Validation command is not supported by this project's detected adapter.");
+  const environment = definition.docker ? { type: "docker", ...dockerContainer(root, spawn) } : undefined;
+  const argv = definition.docker ? ["docker", "exec", "--env", "DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true", environment.name, ...definition.argv] : definition.argv;
+  const startedAt = new Date().toISOString(); const started = Date.now();
+  const result = spawn(argv[0], argv.slice(1), { cwd: root, shell: false, encoding: "utf8", timeout: timeoutMs, maxBuffer: 256 * 1024 });
+  const output = redact(`${result.stdout ?? ""}${result.stderr ?? ""}`).slice(0, 8192);
+  const durationMs = Date.now() - started; const timedOut = result.error?.code === "ETIMEDOUT";
+  const receipt = { receiptVersion: 1, id: crypto.randomUUID(), kind: definition.kind, commandId, argv, ...(environment ? { environment } : {}), startedAt, finishedAt: new Date().toISOString(), durationMs, exitCode: typeof result.status === "number" ? result.status : null, timedOut, output: { redactedSha256: crypto.createHash("sha256").update(output).digest("hex"), bytes: Buffer.byteLength(output) }, worktree: worktreeFingerprint(root) };
+  if (definition.kind === "test") receipt.testEvidence = parseTestEvidence(output, definition.expected, durationMs / 1000);
+  return receipt;
+}