getculpa 1.0.7 → 1.0.10

package/lib/preflight.mjs

@@ -1,274 +1,322 @@
-// CF20-T3 — preflight checks for the shared install core. Detection only:
-// nothing here starts Docker, pulls an image, or touches the app dir.
-//
-// Docker checks take an injectable spawnSync (default: the real one), the
-// same pattern install-culpa.ps1 uses for Test-DockerInstalled's -Probe —
-// so a test can stub docker's presence/engine state without a real Docker
-// install or a fragile PATH shim.
-
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { existsSync, readFileSync, statfsSync } from "node:fs";
-import path from "node:path";
-import { PROBE_TIMEOUT_MS } from "./docker.mjs";
-
-const SUPPORTED_TRIPLES = new Set(["win32-x64", "linux-x64", "darwin-x64", "darwin-arm64"]);
-
-// Mirrors the launcher triples already load-bearing in scripts/install.js's
-// targetTriple() (win32/x64, linux/x64, darwin/x64, darwin/arm64).
-export function checkPlatformSupport(platform = process.platform, arch = process.arch) {
-  if (SUPPORTED_TRIPLES.has(`${platform}-${arch}`)) return { supported: true };
-  const message =
-    "Culpa currently supports Windows x64, Linux x64, and macOS (Intel or Apple Silicon). " +
-    `Detected: ${platform}/${arch}.`;
-  return { supported: false, message };
-}
-
-// Best-effort: `statfs` is unavailable or throws on some hosts/paths (e.g. a
-// directory that does not exist yet). Unknown is a valid, honestly-reported
-// outcome — this never blocks or fails the install.
-export function checkDiskSpaceBestEffort(targetDir) {
-  try {
-    const probeDir = nearestExistingAncestor(targetDir);
-    const stats = statfsSync(probeDir);
-    return { known: true, availableBytes: stats.bavail * stats.bsize };
-  } catch {
-    return { known: false, availableBytes: null };
-  }
-}
-
-function nearestExistingAncestor(startDir) {
-  let dir = startDir;
-  for (let i = 0; i < 64; i++) {
-    if (existsSync(dir)) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) return dir; // reached the filesystem root
-    dir = parent;
-  }
-  return dir;
-}
-
-export function checkDockerPresent(spawnSync = realSpawnSync) {
-  // CF20-R: PROBE_TIMEOUT_MS (docker.mjs) — a hung docker CLI must not stall
-  // npm install forever.
-  const result = spawnSync("docker", ["--version"], { timeout: PROBE_TIMEOUT_MS });
-  return result.status === 0;
-}
-
-// Reachability only — never starts the engine (that is launch-time's job).
-export function checkDockerEngineReachable(spawnSync = realSpawnSync) {
-  const result = spawnSync("docker", ["info", "--format", "ok"], { timeout: PROBE_TIMEOUT_MS });
-  return result.status === 0;
-}
-
-// Same parsing target as launch-culpa.ps1's Get-PinnedServerVersion.
-// Full-line YAML comments, removed before any pin is parsed. Review finding
-// (2026-08-23): the unanchored parser below matched
-//   #     ghcr.io/myaigidev/culpa-server:v1.0.3
-// inside installers/culpa-compose.yml's cosign-verify EXAMPLE at line 29 —
-// which precedes the real `image:` pin at line 58, so the comment won the
-// first-match race.
-// Both read v1.0.3 today so nothing was visibly wrong, but publish.sh rewrites
-// the example and the pin with SEPARATE seds: a server release whose example
-// sed failed to match would leave QW-3 comparing a stale version against
-// last-boot-version.txt and REFUSING to launch a perfectly good pin.
-function stripComposeComments(composeText) {
-  return String(composeText ?? "")
-    .split(/\r?\n/)
-    .filter((line) => !/^\s*#/.test(line))
-    .join("\n");
-}
-
-// Anchored on `image:` as well as comment-stripped: a pin is something docker
-// would actually pull, never prose that happens to name the image.
-export function parsePinnedServerVersion(composeText) {
-  // Comment-stripping is what actually cures the defect: prose can never be a
-  // pin. The `image:` anchor is preferred but NOT required — callers legitimately
-  // pass a bare "culpa-server:vX.Y.Z" fragment (isIncomingComposeOlder's unit
-  // facts do), and requiring the anchor turned 5 of those 7 tests vacuous while
-  // only 2 went red. Anchored first so a real compose is read from its image
-  // line; unanchored fallback over the SAME comment-stripped text, where the
-  // only thing left to match is real content.
-  const text = stripComposeComments(composeText);
-  const anchored = /^[ \t]*image:\s*\S*?culpa-server:([^"'\s]+)/m.exec(text);
-  if (anchored) return anchored[1];
-  const bare = /culpa-server:([^"'\s]+)/.exec(text);
-  return bare ? bare[1] : null;
-}
-
-// Same fail-open-to-"equal" semantics as launch-culpa.ps1's
-// Compare-CulpaVersions: an unparsable tag never brick the comparison, it
-// just reads as 0 (equal). -1 = a older, 1 = a newer.
-export function compareVersions(a, b) {
-  const rx = /^v?(\d+)\.(\d+)\.(\d+)/;
-  const ma = rx.exec(a ?? "");
-  const mb = rx.exec(b ?? "");
-  if (!ma || !mb) return 0;
-  for (let i = 1; i <= 3; i++) {
-    const na = Number(ma[i]);
-    const nb = Number(mb[i]);
-    if (na < nb) return -1;
-    if (na > nb) return 1;
-  }
-  return 0;
-}
-
-// ISS-V103-12. Every pinned CULPA image in a compose text, as
-// { "culpa-server": "v1.0.3", "culpa-dashboard": "v1.0.5" }.
-//
-// Deliberately scoped to `culpa-*`: the compose also pins postgres, and a
-// postgres bump must never be read as a Culpa release. Non-Culpa images are
-// simply absent from the map.
-export function parsePinnedImageVersions(composeText) {
-  const out = {};
-  // `^[ \t]*image:` with /m, not a bare `image:` anywhere. Comment-stripping
-  // alone was not enough: `command: echo "image: .../culpa-dashboard:v9.9.9"`
-  // is not a comment, yet an unanchored match read v9.9.9 as the pin (verified
-  // 2026-08-23, from a CodeRabbit finding). A pin is a YAML key at line start.
-  const rx = /^[ \t]*image:\s*\S*?(culpa-[A-Za-z0-9_-]+):([^"'\s]+)/gm;
-  let m;
-  // comment-stripped for the same reason parsePinnedServerVersion is: a
-  // commented-out or example `image:` line is documentation, not a pin.
-  const text = stripComposeComments(composeText);
-  while ((m = rx.exec(text)) !== null) out[m[1]] = m[2];
-  return out;
-}
-
-// ISS-V103-12. Is the SHIPPED compose a release the live one has not had?
-//
-// This used to be `compareVersions(shippedServerPin, livePin) === 1` — the
-// culpa-server tag and nothing else. A release is PER-COMPONENT (D-087), so
-// any release that did not bump culpa-server left shipped == live and the
-// re-pin never fired: v1.0.4 and v1.0.5 both reached existing installs as new
-// npm FILES over old CONTAINERS, which is worse than not shipping because the
-// two then disagree.
-//
-// The rule now: at least one pinned Culpa image is NEWER, and none is OLDER.
-//   - "at least one newer" generalises the original intent (the shipped file
-//     represents a release that moved something forward) without caring WHICH
-//     component moved;
-//   - "none older" preserves the one-direction rule this function has always
-//     had — an OLDER shipped file never wins. A file moving one image forward
-//     and another back is ambiguous, cannot be produced by publish.sh, and
-//     must not silently win;
-//   - an image in shipped but not live counts as newer: a release that ADDS a
-//     service must reach the live file or that service never starts;
-//   - an image in live but not shipped is ignored, not treated as older;
-//   - unparsable tags still compare as 0, so exotic dev tags contribute
-//     neither direction and can never brick a launch.
-//
-// NB QW-3 (backward-pin refusal) and QW-4 (pre-migration backup) deliberately
-// still key off the culpa-server pin: those are about database migration
-// history, not release delivery, and widening them would change when backups
-// and refusals fire.
-export function isComposeUpgrade(shippedComposeText, liveComposeText, onRefusal = () => {}) {
-  const shipped = parsePinnedImageVersions(shippedComposeText);
-  const live = parsePinnedImageVersions(liveComposeText);
-  if (Object.keys(shipped).length === 0 || Object.keys(live).length === 0) return false;
-
-  let anyNewer = false;
-  for (const [name, shippedTag] of Object.entries(shipped)) {
-    if (!(name in live)) {
-      anyNewer = true;
-      continue;
-    }
-    const cmp = compareVersions(shippedTag, live[name]);
-    // Refusing an ambiguous file must not look like "nothing to do". QW-3
-    // explains itself loudly when it refuses; this branch used to be silent,
-    // leaving an operator asking why an upgrade never landed. The claim that
-    // publish.sh cannot produce such a file is also weaker than it sounds —
-    // this very release had step 5 applied BY HAND.
-    if (cmp === -1) {
-      onRefusal(
-        `getculpa: the shipped compose moves ${name} BACKWARD (${live[name]} -> ${shippedTag}) while moving others forward; refusing to re-pin from an ambiguous file.`,
-      );
-      return false;
-    }
-    if (cmp === 1) anyNewer = true;
-  }
-  return anyNewer;
-}
-
-// Shared by classifyInstall and classifyUpgrade so the two can never read
-// "what version is already here" two different ways.
-function resolveInstalledVersionInfo(appDir) {
-  const liveComposePath = path.join(appDir, "docker-compose.yml");
-  if (!existsSync(appDir) || !existsSync(liveComposePath)) {
-    return { exists: false, installedVersion: null, state: null };
-  }
-  const statePath = path.join(appDir, "install-state.json");
-  const state = readJsonSafe(statePath);
-  const pinned = parsePinnedServerVersion(readTextSafe(liveComposePath));
-  const installedVersion = state?.packageVersion ?? pinned ?? null;
-  return { exists: true, installedVersion, state };
-}
-
-// fresh: nothing installed here yet.
-// repair: something is here (a live compose exists) but there is no state
-//   file we trust to say what version it is (e.g. a Windows-GUI-only
-//   install, or a corrupt state file) — never guess, ask for a repair.
-// upgrade / same-version: read from install-state.json's packageVersion
-//   (falling back to the live compose's pinned tag) compared against the
-//   version of the package currently running.
-export function classifyInstall({ appDir, currentVersion }) {
-  const info = resolveInstalledVersionInfo(appDir);
-  if (!info.exists) return "fresh";
-  if (!info.installedVersion || !info.state) return "repair";
-
-  const cmp = compareVersions(info.installedVersion, currentVersion);
-  if (cmp === 0) return "same-version";
-  if (cmp === -1) return "upgrade";
-  return "repair"; // installed reads NEWER than this package — never silently downgrade
-}
-
-// CF20-T6 — wires classifyInstall (T3 review Minor #4: implemented, tested,
-// ORPHANED — nothing called it) into the postinstall flow, and splits
-// classifyInstall's "repair" bucket into the two shapes postinstall must
-// message and record differently:
-//   - a genuinely unknown install (no trusted version info at all), vs.
-//   - "downgrade-package": npm delivered an OLDER getculpa than the
-//     version already staged here (a stale mirror, a pinned older version,
-//     an explicit rollback) — never silently downgrade.
-// previousVersion is best-effort (state's packageVersion first, the live
-// compose's pinned tag as fallback) and is null only for a genuinely fresh
-// install.
-export function classifyUpgrade({ appDir, currentVersion }) {
-  const classification = classifyInstall({ appDir, currentVersion });
-  const { installedVersion: previousVersion } = resolveInstalledVersionInfo(appDir);
-  if (classification === "repair" && previousVersion && compareVersions(previousVersion, currentVersion) === 1) {
-    return { classification: "downgrade-package", previousVersion };
-  }
-  return { classification, previousVersion };
-}
-
-// CF20-T6 — mirrors launch-culpa.ps1's Test-BackwardPin one-direction rule
-// (QW-1/QW-3 semantics) so the SHIPPED culpa-compose.yml can get the same
-// protection the live compose already has via provision.mjs's
-// stageLiveComposeIfAbsent: an older shipped file must never silently win
-// over a newer one already staged — the downgrade-package case. A malformed
-// incoming pin against a well-formed staged baseline fails CLOSED (treated
-// as older, the same asymmetry Test-BackwardPin uses); an absent incoming
-// or staged pin is permissive — there is no provable baseline to violate.
-export function isIncomingComposeOlder(incomingComposeText, stagedComposeText) {
-  const incoming = parsePinnedServerVersion(incomingComposeText);
-  const staged = parsePinnedServerVersion(stagedComposeText);
-  if (!incoming || !staged) return false;
-  const rx = /^v?(\d+)\.(\d+)\.(\d+)/;
-  if (!rx.test(incoming) && rx.test(staged)) return true;
-  return compareVersions(incoming, staged) === -1;
-}
-
-function readJsonSafe(filePath) {
-  try {
-    return JSON.parse(readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function readTextSafe(filePath) {
-  try {
-    return readFileSync(filePath, "utf8");
-  } catch {
-    return "";
-  }
-}
+// CF20-T3 — preflight checks for the shared install core. Detection only:
+// nothing here starts Docker, pulls an image, or touches the app dir.
+//
+// Docker checks take an injectable spawnSync (default: the real one), the
+// same pattern install-culpa.ps1 uses for Test-DockerInstalled's -Probe —
+// so a test can stub docker's presence/engine state without a real Docker
+// install or a fragile PATH shim.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, readFileSync, statfsSync } from "node:fs";
+import path from "node:path";
+import { PROBE_TIMEOUT_MS } from "./docker.mjs";
+
+const SUPPORTED_TRIPLES = new Set(["win32-x64", "linux-x64", "darwin-x64", "darwin-arm64"]);
+
+// Mirrors the launcher triples already load-bearing in scripts/install.js's
+// targetTriple() (win32/x64, linux/x64, darwin/x64, darwin/arm64).
+// T-179 (ISS-MAC-8): the ONE diagnosis for an install whose postinstall never
+// ran. Verified against npm's own reference (npm-install-scripts, v12): from
+// npm 12.0.0 (2026-07-08) dependency install scripts are blocked by default;
+// a global install has no project package.json for `npm install-scripts
+// approve` (EGLOBAL), so the documented forms are the --allow-scripts install
+// flag or a one-time user config. An older npm with ignore-scripts=true leaves
+// the same silent state. `getculpa` and `getculpa doctor` print exactly this.
+export function unprovisionedDiagnosis() {
+  return {
+    message:
+      "Culpa is installed but was never provisioned: npm did not run this package's install script (npm 12 blocks install scripts by default; an older npm with ignore-scripts=true does the same), so nothing was staged.",
+    recovery:
+      "Run `npm config get ignore-scripts` (it must be false), then reinstall with scripts allowed: `npm i -g --allow-scripts=getculpa getculpa` (npm 12 or newer; or run `npm config set allow-scripts=getculpa --location=user` once and reinstall). On npm 11 a plain `npm i -g getculpa` provisions.",
+  };
+}
+
+export function checkPlatformSupport(platform = process.platform, arch = process.arch) {
+  if (SUPPORTED_TRIPLES.has(`${platform}-${arch}`)) return { supported: true };
+  const message =
+    "Culpa currently supports Windows x64, Linux x64, and macOS (Intel or Apple Silicon). " +
+    `Detected: ${platform}/${arch}.`;
+  return { supported: false, message };
+}
+
+// Best-effort: `statfs` is unavailable or throws on some hosts/paths (e.g. a
+// directory that does not exist yet). Unknown is a valid, honestly-reported
+// outcome — this never blocks or fails the install.
+export function checkDiskSpaceBestEffort(targetDir) {
+  try {
+    const probeDir = nearestExistingAncestor(targetDir);
+    const stats = statfsSync(probeDir);
+    return { known: true, availableBytes: stats.bavail * stats.bsize };
+  } catch {
+    return { known: false, availableBytes: null };
+  }
+}
+
+function nearestExistingAncestor(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return dir; // reached the filesystem root
+    dir = parent;
+  }
+  return dir;
+}
+
+export function checkDockerPresent(spawnSync = realSpawnSync) {
+  // CF20-R: PROBE_TIMEOUT_MS (docker.mjs) — a hung docker CLI must not stall
+  // npm install forever.
+  const result = spawnSync("docker", ["--version"], { timeout: PROBE_TIMEOUT_MS });
+  return result.status === 0;
+}
+
+// Reachability only — never starts the engine (that is launch-time's job).
+export function checkDockerEngineReachable(spawnSync = realSpawnSync) {
+  const result = spawnSync("docker", ["info", "--format", "ok"], { timeout: PROBE_TIMEOUT_MS });
+  return result.status === 0;
+}
+
+// Same parsing target as launch-culpa.ps1's Get-PinnedServerVersion.
+// Full-line YAML comments, removed before any pin is parsed. Review finding
+// (2026-08-23): the unanchored parser below matched
+//   #     ghcr.io/myaigidev/culpa-server:v1.0.3
+// inside installers/culpa-compose.yml's cosign-verify EXAMPLE at line 29 —
+// which precedes the real `image:` pin at line 58, so the comment won the
+// first-match race.
+// Both read v1.0.3 today so nothing was visibly wrong, but publish.sh rewrites
+// the example and the pin with SEPARATE seds: a server release whose example
+// sed failed to match would leave QW-3 comparing a stale version against
+// last-boot-version.txt and REFUSING to launch a perfectly good pin.
+function stripComposeComments(composeText) {
+  return String(composeText ?? "")
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*#/.test(line))
+    .join("\n");
+}
+
+// Anchored on `image:` as well as comment-stripped: a pin is something docker
+// would actually pull, never prose that happens to name the image.
+export function parsePinnedServerVersion(composeText) {
+  // Comment-stripping is what actually cures the defect: prose can never be a
+  // pin. The `image:` anchor is preferred but NOT required — callers legitimately
+  // pass a bare "culpa-server:vX.Y.Z" fragment (isIncomingComposeOlder's unit
+  // facts do), and requiring the anchor turned 5 of those 7 tests vacuous while
+  // only 2 went red. Anchored first so a real compose is read from its image
+  // line; unanchored fallback over the SAME comment-stripped text, where the
+  // only thing left to match is real content.
+  const text = stripComposeComments(composeText);
+  const anchored = /^[ \t]*image:\s*\S*?culpa-server:([^"'\s]+)/m.exec(text);
+  if (anchored) return anchored[1];
+  const bare = /culpa-server:([^"'\s]+)/.exec(text);
+  return bare ? bare[1] : null;
+}
+
+// Same fail-open-to-"equal" semantics as launch-culpa.ps1's
+// Compare-CulpaVersions: an unparsable tag never brick the comparison, it
+// just reads as 0 (equal). -1 = a older, 1 = a newer.
+export function compareVersions(a, b) {
+  const rx = /^v?(\d+)\.(\d+)\.(\d+)/;
+  const ma = rx.exec(a ?? "");
+  const mb = rx.exec(b ?? "");
+  if (!ma || !mb) return 0;
+  for (let i = 1; i <= 3; i++) {
+    const na = Number(ma[i]);
+    const nb = Number(mb[i]);
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+  return 0;
+}
+
+// ISS-V103-12. Every pinned CULPA image in a compose text, as
+// { "culpa-server": "v1.0.3", "culpa-dashboard": "v1.0.5" }.
+//
+// Deliberately scoped to `culpa-*`: the compose also pins postgres, and a
+// postgres bump must never be read as a Culpa release. Non-Culpa images are
+// simply absent from the map.
+export function parsePinnedImageVersions(composeText) {
+  const out = {};
+  // `^[ \t]*image:` with /m, not a bare `image:` anywhere. Comment-stripping
+  // alone was not enough: `command: echo "image: .../culpa-dashboard:v9.9.9"`
+  // is not a comment, yet an unanchored match read v9.9.9 as the pin (verified
+  // 2026-08-23, from a CodeRabbit finding). A pin is a YAML key at line start.
+  const rx = /^[ \t]*image:\s*\S*?(culpa-[A-Za-z0-9_-]+):([^"'\s]+)/gm;
+  let m;
+  // comment-stripped for the same reason parsePinnedServerVersion is: a
+  // commented-out or example `image:` line is documentation, not a pin.
+  const text = stripComposeComments(composeText);
+  while ((m = rx.exec(text)) !== null) out[m[1]] = m[2];
+  return out;
+}
+
+// ISS-V103-12. Is the SHIPPED compose a release the live one has not had?
+//
+// This used to be `compareVersions(shippedServerPin, livePin) === 1` — the
+// culpa-server tag and nothing else. A release is PER-COMPONENT (D-087), so
+// any release that did not bump culpa-server left shipped == live and the
+// re-pin never fired: v1.0.4 and v1.0.5 both reached existing installs as new
+// npm FILES over old CONTAINERS, which is worse than not shipping because the
+// two then disagree.
+//
+// The rule now: at least one pinned Culpa image is NEWER, and none is OLDER.
+//   - "at least one newer" generalises the original intent (the shipped file
+//     represents a release that moved something forward) without caring WHICH
+//     component moved;
+//   - "none older" preserves the one-direction rule this function has always
+//     had — an OLDER shipped file never wins. A file moving one image forward
+//     and another back is ambiguous, cannot be produced by publish.sh, and
+//     must not silently win;
+//   - an image in shipped but not live counts as newer: a release that ADDS a
+//     service must reach the live file or that service never starts;
+//   - an image in live but not shipped is ignored, not treated as older;
+//   - unparsable tags still compare as 0, so exotic dev tags contribute
+//     neither direction and can never brick a launch.
+//
+// NB QW-3 (backward-pin refusal) and QW-4 (pre-migration backup) deliberately
+// still key off the culpa-server pin: those are about database migration
+// history, not release delivery, and widening them would change when backups
+// and refusals fire.
+// T-178 (ISS-MAC-7 + ISS-V103-7): ONE skew rule for launch, postinstall and
+// doctor. A skew is either a RUNNING Culpa container whose image tag is not
+// the live compose's pin for it (checked first — the stack's truth), or a
+// shipped compose that is a release the live one has not had (isComposeUpgrade,
+// the one-direction rule unchanged). `running` is the map runningImageVersions
+// returns ({} when unknown — unknown never reports a skew); unparsable tags
+// compare 0 and never report a skew either. `component` prefers culpa-server.
+export function versionSkew({ shippedText, liveText, running }) {
+  const live = parsePinnedImageVersions(liveText ?? "");
+  const runningMap = running ?? {};
+  const ordered = (names) => [...names].sort((a, b) => (a === "culpa-server" ? -1 : b === "culpa-server" ? 1 : a.localeCompare(b)));
+  for (const name of ordered(Object.keys(live))) {
+    const runningTag = runningMap[name];
+    if (runningTag === undefined) continue;
+    // Direction-agnostic on purpose (review N1): the stack's truth is "not on
+    // the pin". Nothing today moves a container PAST its compose pin, so a
+    // running tag ahead of the pin has no path; if one ever appears the label
+    // is still "running-behind" but the message carries from/to verbatim.
+    if (compareVersions(runningTag, live[name]) !== 0) {
+      return { kind: "running-behind", component: name, from: runningTag, to: live[name] };
+    }
+  }
+  if (!isComposeUpgrade(shippedText ?? "", liveText ?? "")) return null;
+  const shipped = parsePinnedImageVersions(shippedText ?? "");
+  for (const name of ordered(Object.keys(shipped))) {
+    if (!(name in live) || compareVersions(shipped[name], live[name]) === 1) {
+      return { kind: "staged-upgrade", component: name, from: live[name] ?? "absent", to: shipped[name] };
+    }
+  }
+  return null;
+}
+
+export function isComposeUpgrade(shippedComposeText, liveComposeText, onRefusal = () => {}) {
+  const shipped = parsePinnedImageVersions(shippedComposeText);
+  const live = parsePinnedImageVersions(liveComposeText);
+  if (Object.keys(shipped).length === 0 || Object.keys(live).length === 0) return false;
+
+  let anyNewer = false;
+  for (const [name, shippedTag] of Object.entries(shipped)) {
+    if (!(name in live)) {
+      anyNewer = true;
+      continue;
+    }
+    const cmp = compareVersions(shippedTag, live[name]);
+    // Refusing an ambiguous file must not look like "nothing to do". QW-3
+    // explains itself loudly when it refuses; this branch used to be silent,
+    // leaving an operator asking why an upgrade never landed. The claim that
+    // publish.sh cannot produce such a file is also weaker than it sounds —
+    // this very release had step 5 applied BY HAND.
+    if (cmp === -1) {
+      onRefusal(
+        `getculpa: the shipped compose moves ${name} BACKWARD (${live[name]} -> ${shippedTag}) while moving others forward; refusing to re-pin from an ambiguous file.`,
+      );
+      return false;
+    }
+    if (cmp === 1) anyNewer = true;
+  }
+  return anyNewer;
+}
+
+// Shared by classifyInstall and classifyUpgrade so the two can never read
+// "what version is already here" two different ways.
+function resolveInstalledVersionInfo(appDir) {
+  const liveComposePath = path.join(appDir, "docker-compose.yml");
+  if (!existsSync(appDir) || !existsSync(liveComposePath)) {
+    return { exists: false, installedVersion: null, state: null };
+  }
+  const statePath = path.join(appDir, "install-state.json");
+  const state = readJsonSafe(statePath);
+  const pinned = parsePinnedServerVersion(readTextSafe(liveComposePath));
+  const installedVersion = state?.packageVersion ?? pinned ?? null;
+  return { exists: true, installedVersion, state };
+}
+
+// fresh: nothing installed here yet.
+// repair: something is here (a live compose exists) but there is no state
+//   file we trust to say what version it is (e.g. a Windows-GUI-only
+//   install, or a corrupt state file) — never guess, ask for a repair.
+// upgrade / same-version: read from install-state.json's packageVersion
+//   (falling back to the live compose's pinned tag) compared against the
+//   version of the package currently running.
+export function classifyInstall({ appDir, currentVersion }) {
+  const info = resolveInstalledVersionInfo(appDir);
+  if (!info.exists) return "fresh";
+  if (!info.installedVersion || !info.state) return "repair";
+
+  const cmp = compareVersions(info.installedVersion, currentVersion);
+  if (cmp === 0) return "same-version";
+  if (cmp === -1) return "upgrade";
+  return "repair"; // installed reads NEWER than this package — never silently downgrade
+}
+
+// CF20-T6 — wires classifyInstall (T3 review Minor #4: implemented, tested,
+// ORPHANED — nothing called it) into the postinstall flow, and splits
+// classifyInstall's "repair" bucket into the two shapes postinstall must
+// message and record differently:
+//   - a genuinely unknown install (no trusted version info at all), vs.
+//   - "downgrade-package": npm delivered an OLDER getculpa than the
+//     version already staged here (a stale mirror, a pinned older version,
+//     an explicit rollback) — never silently downgrade.
+// previousVersion is best-effort (state's packageVersion first, the live
+// compose's pinned tag as fallback) and is null only for a genuinely fresh
+// install.
+export function classifyUpgrade({ appDir, currentVersion }) {
+  const classification = classifyInstall({ appDir, currentVersion });
+  const { installedVersion: previousVersion } = resolveInstalledVersionInfo(appDir);
+  if (classification === "repair" && previousVersion && compareVersions(previousVersion, currentVersion) === 1) {
+    return { classification: "downgrade-package", previousVersion };
+  }
+  return { classification, previousVersion };
+}
+
+// CF20-T6 — mirrors launch-culpa.ps1's Test-BackwardPin one-direction rule
+// (QW-1/QW-3 semantics) so the SHIPPED culpa-compose.yml can get the same
+// protection the live compose already has via provision.mjs's
+// stageLiveComposeIfAbsent: an older shipped file must never silently win
+// over a newer one already staged — the downgrade-package case. A malformed
+// incoming pin against a well-formed staged baseline fails CLOSED (treated
+// as older, the same asymmetry Test-BackwardPin uses); an absent incoming
+// or staged pin is permissive — there is no provable baseline to violate.
+export function isIncomingComposeOlder(incomingComposeText, stagedComposeText) {
+  const incoming = parsePinnedServerVersion(incomingComposeText);
+  const staged = parsePinnedServerVersion(stagedComposeText);
+  if (!incoming || !staged) return false;
+  const rx = /^v?(\d+)\.(\d+)\.(\d+)/;
+  if (!rx.test(incoming) && rx.test(staged)) return true;
+  return compareVersions(incoming, staged) === -1;
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}