getculpa 1.0.2 → 1.0.4

package/lib/provision.mjs

@@ -1,318 +1,329 @@
-// CF20-T3 — the defer-start provisioner. Lays down everything the Windows
-// installer lays down; starts nothing (compose up, collector start, and a
-// browser open are all launch-time work — CF20-T4).
-//
-// Docker interaction (presence, engine reachability, image pull) and the
-// win32 installer delegation both take injectable dependencies, defaulting
-// to the real ones. Tests MUST override them: this module runs on the
-// founder's own dev machine, and the real win32 delegate writes to the real
-// Desktop, Start Menu and HKCU — never acceptable as a side effect of a test
-// run. Docker-command recording (for the "nothing started" fact) happens
-// through the injected dockerSpawnSync rather than a PATH shim, for the same
-// reason install-culpa.ps1 injects -Probe into Test-DockerInstalled: an
-// explicit dependency is more reliable than relying on OS PATH resolution
-// rules for a fake executable.
-
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { checkDockerEngineReachable, checkDockerPresent, classifyUpgrade, isIncomingComposeOlder } from "./preflight.mjs";
-import { resolveAssetPath } from "./assets.mjs";
-import { canonicalAppDir } from "./paths.mjs";
-
-// T-CF29-8: where lib/fetch.mjs stages the vendored binaries. Same derivation
-// lib/repair.mjs already uses, so the two agree on one vendor directory.
-const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
-
-// The full parity file-set (Windows inventory: culpa-setup.iss:43-54, minus
-// the collectord binary, which lib/fetch.mjs stages separately by triple).
-// This is the WINDOWS inventory and stays the canonical full list — use
-// parityAssetsFor(platform) to get what a given platform should actually
-// receive.
-export const PARITY_ASSETS = [
-  "culpa-compose.yml",
-  "install-culpa.ps1",
-  "launch-culpa.ps1",
-  "uninstall-culpa.ps1",
-  "culpa-collector.ps1",
-  "register.mjs",
-];
-
-// T-CF28-6 — four of the six are PowerShell scripts that only win32 can run:
-// lib/start.mjs delegates to launch-culpa.ps1 only when platform === "win32"
-// (start.mjs:457), lib/uninstall.mjs only delegates to uninstall-culpa.ps1 on
-// win32 (uninstall.mjs:80-82), and install-culpa.ps1/culpa-collector.ps1 are
-// invoked by the Windows installer path alone. Staging them on darwin/linux
-// put four inert files in the user's app dir and made `getculpa doctor` grade
-// them as part of a healthy install.
-export const WINDOWS_ONLY_ASSETS = Object.freeze([
-  "install-culpa.ps1",
-  "launch-culpa.ps1",
-  "uninstall-culpa.ps1",
-  "culpa-collector.ps1",
-]);
-
-// The single source of truth for "which parity files belong on this platform".
-// provision(), repair() and doctor() ALL read it — if any one of them used the
-// flat list instead, repair would restore what provision skipped, or doctor
-// would fail an install for a file that is correctly absent.
-export function parityAssetsFor(platform = process.platform) {
-  if (platform === "win32") return PARITY_ASSETS;
-  return PARITY_ASSETS.filter((name) => !WINDOWS_ONLY_ASSETS.includes(name));
-}
-
-// CF20-T6 — protects the SHIPPED culpa-compose.yml the same way
-// stageLiveComposeIfAbsent already protects the live one, mirroring
-// launch-culpa.ps1's QW-1 one-direction rule: an older incoming pin must
-// never silently overwrite a newer one already staged (the
-// downgrade-package case — npm delivered an older getculpa than what is
-// already here). CULPA_ALLOW_DOWNGRADE=1 is the same escape hatch T4's
-// start.mjs already honors for QW-3 at launch time.
-function stageShippedCompose(appDir, env) {
-  const src = resolveAssetPath("culpa-compose.yml");
-  const dest = path.join(appDir, "culpa-compose.yml");
-  const allowDowngrade = env.CULPA_ALLOW_DOWNGRADE === "1";
-  if (existsSync(dest) && !allowDowngrade) {
-    const incoming = readFileSync(src, "utf8");
-    const staged = readFileSync(dest, "utf8");
-    if (isIncomingComposeOlder(incoming, staged)) {
-      console.warn(
-        "getculpa: the incoming package's culpa-compose.yml pin is older than the one already staged - skipped (set CULPA_ALLOW_DOWNGRADE=1 to override).",
-      );
-      return;
-    }
-  }
-  copyFileSync(src, dest);
-}
-
-// CF20-T5 (repair): exported so lib/repair.mjs can re-stage the parity
-// file-set and (only-if-absent) the live compose without duplicating this
-// logic — same reason the task instructions call out reuse over a second
-// copy. Purely additive: behavior and call sites inside this file are
-// unchanged.
-export function stageParityFiles(appDir, env = process.env, platform = process.platform) {
-  mkdirSync(appDir, { recursive: true });
-  stageShippedCompose(appDir, env);
-  for (const name of parityAssetsFor(platform)) {
-    if (name === "culpa-compose.yml") continue;
-    copyFileSync(resolveAssetPath(name), path.join(appDir, name));
-  }
-}
-
-// The live compose is staged ONLY when absent. An existing live compose
-// belongs to launch-time's QW-1 sync (launch-culpa.ps1) — provisioning must
-// never re-pin a running install out from under it.
-export function stageLiveComposeIfAbsent(appDir) {
-  const live = path.join(appDir, "docker-compose.yml");
-  if (existsSync(live)) return false;
-  copyFileSync(path.join(appDir, "culpa-compose.yml"), live);
-  return true;
-}
-
-// T-CF29-8 — the name culpa-collector.ps1:35 reads from the app dir, and the
-// same name culpa-setup.iss:52 installs there. NOT the Rust target triple
-// lib/fetch.mjs uses for the release asset (x86_64-pc-windows-msvc): this is
-// the Node-style platform-arch pair.
-export function collectorBinaryName(platform = process.platform, arch = process.arch) {
-  const exe = platform === "win32" ? ".exe" : "";
-  return `culpa-collectord-${platform}-${arch}${exe}`;
-}
-
-// T-CF29-8 — capture was silently OFF on every Windows npm install:
-// "culpa-collectord-win32-x64.exe not present in this package - skipping
-// capture setup". lib/fetch.mjs stages the binary into the PACKAGE's vendor/
-// as culpa-collectord.exe, the .ps1 reads it from the APP DIR under the
-// triple-suffixed name, and nothing bridged the two. The Windows installer
-// path has always put it in the app dir, so this is the npm path catching up
-// to installer parity, not a new convention.
-//
-// Returns whether the binary is really there afterwards — never a hopeful
-// echo of the caller's collectorFetched flag, because "capture is on" is
-// exactly the kind of claim that must be backed by a file on disk.
-export function stageCollectorBinary({ appDir, vendorDir, platform, arch }) {
-  const exe = platform === "win32" ? ".exe" : "";
-  const src = path.join(vendorDir, `culpa-collectord${exe}`);
-  if (!existsSync(src)) return false;
-  const dest = path.join(appDir, collectorBinaryName(platform, arch));
-  try {
-    copyFileSync(src, dest);
-  } catch (e) {
-    console.warn(`getculpa: capture collector could not be staged (${e.message}) - capture OFF, everything else works.`);
-    return false;
-  }
-  return existsSync(dest);
-}
-
-function detectDockerState(dockerSpawnSync) {
-  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
-  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
-  return "ready";
-}
-
-// Staging only — `pull`, never `up`. This is the defer invariant's other
-// half: even with a reachable engine, provisioning must not start anything.
-function stageImages(appDir, dockerSpawnSync) {
-  const shipped = path.join(appDir, "culpa-compose.yml");
-  const result = dockerSpawnSync("docker", ["compose", "-f", shipped, "-p", "culpa", "pull"], {
-    encoding: "utf8",
-  });
-  return result.status === 0;
-}
-
-// Real win32 delegate: -DeferStart -NonInteractive is what makes this safe
-// to run unattended from postinstall (no dialogs, no engine start, no
-// compose up, no browser) while still producing the same shortcuts + HKCU
-// registration the Windows installer produces.
-function defaultDelegateWindowsInstaller(appDir) {
-  const script = path.join(appDir, "install-culpa.ps1");
-  const result = realSpawnSync(
-    "powershell.exe",
-    ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script, "-DeferStart", "-NonInteractive"],
-    { stdio: "inherit" },
-  );
-  return result.status === 0;
-}
-
-function writeState(appDir, state) {
-  writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(state, null, 2)}\n`);
-}
-
-function readExistingState(appDir) {
-  try {
-    return JSON.parse(readFileSync(path.join(appDir, "install-state.json"), "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-// CF20-T6 — the honest, human-facing line for each classifyUpgrade outcome.
-// "upgrade" is explicit that the new version is STAGED, not running yet —
-// it applies at the next `getculpa` (start.mjs's QW-1-equivalent sync + T4's
-// launch orchestration), never here. Postinstall stays silent about
-// migrations by design: those are QW-4's job at that next `getculpa`, not
-// this one.
-function describeClassification(classification, previousVersion, currentVersion) {
-  switch (classification) {
-    case "fresh":
-      return `getculpa: installing Culpa ${currentVersion}.`;
-    case "upgrade":
-      return `getculpa: upgrading Culpa ${previousVersion} -> ${currentVersion} (staged; applies at next \`getculpa\`).`;
-    case "same-version":
-      return `getculpa: repairing the existing Culpa ${currentVersion} installation (same version reinstalled).`;
-    case "downgrade-package":
-      return (
-        `getculpa: this package (${currentVersion}) is older than the installed Culpa ${previousVersion} - ` +
-        "refusing to downgrade (set CULPA_ALLOW_DOWNGRADE=1 to override)."
-      );
-    case "repair":
-    default:
-      return "getculpa: repairing the existing Culpa installation.";
-  }
-}
-
-export async function provision(opts) {
-  const {
-    appDir,
-    currentVersion,
-    collectorFetched = false,
-    platform = process.platform,
-    arch = process.arch,
-    vendorDir = path.join(packageRoot, "vendor"),
-    dockerSpawnSync = realSpawnSync,
-    delegateWindowsInstaller = defaultDelegateWindowsInstaller,
-    env = process.env,
-  } = opts;
-
-  // Classify + capture the pre-existing state BEFORE anything below mutates
-  // appDir — both read the install-state.json / live compose that staging
-  // is about to overwrite.
-  const { classification, previousVersion } = classifyUpgrade({ appDir, currentVersion });
-  console.log(describeClassification(classification, previousVersion, currentVersion));
-  const existingState = readExistingState(appDir);
-
-  // CF20-R: a REFUSED downgrade (classification === "downgrade-package",
-  // CULPA_ALLOW_DOWNGRADE not set) used to still restage every OTHER parity
-  // file (the ps1 scripts, register.mjs) with the older package's copies —
-  // only culpa-compose.yml was protected (stageShippedCompose's own guard).
-  // That left a mixed-version app dir: a newer compose pin beside older
-  // scripts. Skip the WHOLE parity re-stage in this case instead, so the app
-  // dir stays wholly at the newer version; dir/state handling below is
-  // unaffected.
-  const allowDowngrade = env.CULPA_ALLOW_DOWNGRADE === "1";
-  const refusedDowngrade = classification === "downgrade-package" && !allowDowngrade;
-  if (refusedDowngrade) {
-    console.warn(
-      `getculpa: this package is older than the installed Culpa ${previousVersion} - skipping the parity file re-stage entirely (compose, scripts, register.mjs) to avoid a mixed-version app dir (set CULPA_ALLOW_DOWNGRADE=1 to override).`,
-    );
-  } else {
-    stageParityFiles(appDir, env, platform);
-  }
-  stageLiveComposeIfAbsent(appDir);
-
-  // T-CF29-8: only attempt it when the fetch reported success; the result is
-  // what gets recorded, not the intent.
-  const collectorStaged = collectorFetched && stageCollectorBinary({ appDir, vendorDir, platform, arch });
-  if (collectorFetched && !collectorStaged) {
-    console.warn(
-      "getculpa: the capture collector was downloaded but could not be placed in the app directory - capture OFF, everything else works.",
-    );
-  }
-
-  const dockerState = detectDockerState(dockerSpawnSync);
-  let imagesStaged = false;
-  if (dockerState === "ready") {
-    imagesStaged = stageImages(appDir, dockerSpawnSync);
-    if (!imagesStaged) {
-      console.warn("getculpa: image staging failed - images will be pulled at first `getculpa`.");
-    }
-  } else {
-    const why = dockerState === "missing" ? "Docker was not found" : "Docker is not running";
-    console.warn(`getculpa: ${why} - image staging deferred to first \`getculpa\`.`);
-  }
-
-  if (platform === "win32") {
-    // CF20-R: the Windows delegate registers the ONE fixed, per-machine HKCU
-    // uninstall key (install-culpa.ps1 / culpa-setup.iss's AppId). A second
-    // app dir on the same machine (CULPA_APP_DIR pointed somewhere
-    // non-default) must never overwrite that shared key — the gate's
-    // historical incident class. Only delegate when this appDir IS the
-    // canonical one (CULPA_APP_DIR's override stripped); otherwise skip
-    // registration and say so, once, honestly.
-    if (appDir === canonicalAppDir({ platform, env })) {
-      const ok = delegateWindowsInstaller(appDir);
-      if (!ok) {
-        console.warn("getculpa: Windows shortcut/registry setup did not complete cleanly - shortcuts may be missing.");
-      }
-    } else {
-      console.log("getculpa: non-canonical app dir: shortcuts/registry registration skipped.");
-    }
-  }
-
-  // T6 review (Important): a REFUSED downgrade must not record the rejected,
-  // older currentVersion as installed — the protected artifacts still carry
-  // the newer version, and this field is the ground truth the next run's
-  // classification reads. Persist the true installed version instead.
-  const recordedPackageVersion =
-    classification === "downgrade-package" && previousVersion ? previousVersion : currentVersion;
-  writeState(appDir, {
-    packageVersion: recordedPackageVersion,
-    previousVersion,
-    classification,
-    // provisionedAt is the FIRST install's timestamp, preserved across every
-    // subsequent provision() run; updatedAt is this run's.
-    provisionedAt: existingState?.provisionedAt ?? new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-    dockerState,
-    imagesStaged,
-    collectorStaged,
-    platform,
-  });
-
-  // T-CF28-5/7: the Docker and staging facts were already computed above and
-  // written to install-state.json, but the caller that has to REPORT them
-  // (scripts/install.js) could not see them — which is how a Docker-less
-  // install still printed "Culpa installed successfully." Returning them
-  // changes no behavior here; it just stops postinstall from having to guess.
-  return { classification, previousVersion, dockerState, imagesStaged, collectorStaged };
-}
+// CF20-T3 — the defer-start provisioner. Lays down everything the Windows
+// installer lays down; starts nothing (compose up, collector start, and a
+// browser open are all launch-time work — CF20-T4).
+//
+// Docker interaction (presence, engine reachability, image pull) and the
+// win32 installer delegation both take injectable dependencies, defaulting
+// to the real ones. Tests MUST override them: this module runs on the
+// founder's own dev machine, and the real win32 delegate writes to the real
+// Desktop, Start Menu and HKCU — never acceptable as a side effect of a test
+// run. Docker-command recording (for the "nothing started" fact) happens
+// through the injected dockerSpawnSync rather than a PATH shim, for the same
+// reason install-culpa.ps1 injects -Probe into Test-DockerInstalled: an
+// explicit dependency is more reliable than relying on OS PATH resolution
+// rules for a fake executable.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkDockerEngineReachable, checkDockerPresent, classifyUpgrade, isIncomingComposeOlder } from "./preflight.mjs";
+import { resolveAssetPath } from "./assets.mjs";
+import { canonicalAppDir } from "./paths.mjs";
+
+// T-CF29-8: where lib/fetch.mjs stages the vendored binaries. Same derivation
+// lib/repair.mjs already uses, so the two agree on one vendor directory.
+const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// The full parity file-set (Windows inventory: culpa-setup.iss:43-54, minus
+// the collectord binary, which lib/fetch.mjs stages separately by triple).
+// This is the WINDOWS inventory and stays the canonical full list — use
+// parityAssetsFor(platform) to get what a given platform should actually
+// receive.
+export const PARITY_ASSETS = [
+  "culpa-compose.yml",
+  "install-culpa.ps1",
+  "launch-culpa.ps1",
+  "uninstall-culpa.ps1",
+  "culpa-collector.ps1",
+  "register.mjs",
+];
+
+// Shipped, but NOT parity and NOT graded by doctor — see stageParityFiles.
+export const RELAY_FLY_CONFIG = "culpa-relay-fly.toml";
+
+// T-CF28-6 — four of the six are PowerShell scripts that only win32 can run:
+// lib/start.mjs delegates to launch-culpa.ps1 only when platform === "win32"
+// (start.mjs:457), lib/uninstall.mjs only delegates to uninstall-culpa.ps1 on
+// win32 (uninstall.mjs:80-82), and install-culpa.ps1/culpa-collector.ps1 are
+// invoked by the Windows installer path alone. Staging them on darwin/linux
+// put four inert files in the user's app dir and made `getculpa doctor` grade
+// them as part of a healthy install.
+export const WINDOWS_ONLY_ASSETS = Object.freeze([
+  "install-culpa.ps1",
+  "launch-culpa.ps1",
+  "uninstall-culpa.ps1",
+  "culpa-collector.ps1",
+]);
+
+// The single source of truth for "which parity files belong on this platform".
+// provision(), repair() and doctor() ALL read it — if any one of them used the
+// flat list instead, repair would restore what provision skipped, or doctor
+// would fail an install for a file that is correctly absent.
+export function parityAssetsFor(platform = process.platform) {
+  if (platform === "win32") return PARITY_ASSETS;
+  return PARITY_ASSETS.filter((name) => !WINDOWS_ONLY_ASSETS.includes(name));
+}
+
+// CF20-T6 — protects the SHIPPED culpa-compose.yml the same way
+// stageLiveComposeIfAbsent already protects the live one, mirroring
+// launch-culpa.ps1's QW-1 one-direction rule: an older incoming pin must
+// never silently overwrite a newer one already staged (the
+// downgrade-package case — npm delivered an older getculpa than what is
+// already here). CULPA_ALLOW_DOWNGRADE=1 is the same escape hatch T4's
+// start.mjs already honors for QW-3 at launch time.
+function stageShippedCompose(appDir, env) {
+  const src = resolveAssetPath("culpa-compose.yml");
+  const dest = path.join(appDir, "culpa-compose.yml");
+  const allowDowngrade = env.CULPA_ALLOW_DOWNGRADE === "1";
+  if (existsSync(dest) && !allowDowngrade) {
+    const incoming = readFileSync(src, "utf8");
+    const staged = readFileSync(dest, "utf8");
+    if (isIncomingComposeOlder(incoming, staged)) {
+      console.warn(
+        "getculpa: the incoming package's culpa-compose.yml pin is older than the one already staged - skipped (set CULPA_ALLOW_DOWNGRADE=1 to override).",
+      );
+      return;
+    }
+  }
+  copyFileSync(src, dest);
+}
+
+// CF20-T5 (repair): exported so lib/repair.mjs can re-stage the parity
+// file-set and (only-if-absent) the live compose without duplicating this
+// logic — same reason the task instructions call out reuse over a second
+// copy. Purely additive: behavior and call sites inside this file are
+// unchanged.
+export function stageParityFiles(appDir, env = process.env, platform = process.platform) {
+  mkdirSync(appDir, { recursive: true });
+  stageShippedCompose(appDir, env);
+  for (const name of parityAssetsFor(platform)) {
+    if (name === "culpa-compose.yml") continue;
+    copyFileSync(resolveAssetPath(name), path.join(appDir, name));
+  }
+  // ISS-V103-9: the Cloud Relay page's Fly tab prints
+  // `flyctl deploy --config culpa-relay-fly.toml` and tells the customer to
+  // run it from THIS folder, so the file has to be here. Staged OUTSIDE
+  // PARITY_ASSETS deliberately: that list is the Windows-installer parity
+  // set and doctor grades every member as load-bearing, but a relay config
+  // is optional — most installs never deploy one, and a missing relay
+  // config must never make `getculpa doctor` unhappy.
+  copyFileSync(resolveAssetPath(RELAY_FLY_CONFIG), path.join(appDir, RELAY_FLY_CONFIG));
+}
+
+// The live compose is staged ONLY when absent. An existing live compose
+// belongs to launch-time's QW-1 sync (launch-culpa.ps1) — provisioning must
+// never re-pin a running install out from under it.
+export function stageLiveComposeIfAbsent(appDir) {
+  const live = path.join(appDir, "docker-compose.yml");
+  if (existsSync(live)) return false;
+  copyFileSync(path.join(appDir, "culpa-compose.yml"), live);
+  return true;
+}
+
+// T-CF29-8 — the name culpa-collector.ps1:35 reads from the app dir, and the
+// same name culpa-setup.iss:52 installs there. NOT the Rust target triple
+// lib/fetch.mjs uses for the release asset (x86_64-pc-windows-msvc): this is
+// the Node-style platform-arch pair.
+export function collectorBinaryName(platform = process.platform, arch = process.arch) {
+  const exe = platform === "win32" ? ".exe" : "";
+  return `culpa-collectord-${platform}-${arch}${exe}`;
+}
+
+// T-CF29-8 — capture was silently OFF on every Windows npm install:
+// "culpa-collectord-win32-x64.exe not present in this package - skipping
+// capture setup". lib/fetch.mjs stages the binary into the PACKAGE's vendor/
+// as culpa-collectord.exe, the .ps1 reads it from the APP DIR under the
+// triple-suffixed name, and nothing bridged the two. The Windows installer
+// path has always put it in the app dir, so this is the npm path catching up
+// to installer parity, not a new convention.
+//
+// Returns whether the binary is really there afterwards — never a hopeful
+// echo of the caller's collectorFetched flag, because "capture is on" is
+// exactly the kind of claim that must be backed by a file on disk.
+export function stageCollectorBinary({ appDir, vendorDir, platform, arch }) {
+  const exe = platform === "win32" ? ".exe" : "";
+  const src = path.join(vendorDir, `culpa-collectord${exe}`);
+  if (!existsSync(src)) return false;
+  const dest = path.join(appDir, collectorBinaryName(platform, arch));
+  try {
+    copyFileSync(src, dest);
+  } catch (e) {
+    console.warn(`getculpa: capture collector could not be staged (${e.message}) - capture OFF, everything else works.`);
+    return false;
+  }
+  return existsSync(dest);
+}
+
+function detectDockerState(dockerSpawnSync) {
+  if (!checkDockerPresent(dockerSpawnSync)) return "missing";
+  if (!checkDockerEngineReachable(dockerSpawnSync)) return "installed-not-running";
+  return "ready";
+}
+
+// Staging only — `pull`, never `up`. This is the defer invariant's other
+// half: even with a reachable engine, provisioning must not start anything.
+function stageImages(appDir, dockerSpawnSync) {
+  const shipped = path.join(appDir, "culpa-compose.yml");
+  const result = dockerSpawnSync("docker", ["compose", "-f", shipped, "-p", "culpa", "pull"], {
+    encoding: "utf8",
+  });
+  return result.status === 0;
+}
+
+// Real win32 delegate: -DeferStart -NonInteractive is what makes this safe
+// to run unattended from postinstall (no dialogs, no engine start, no
+// compose up, no browser) while still producing the same shortcuts + HKCU
+// registration the Windows installer produces.
+function defaultDelegateWindowsInstaller(appDir) {
+  const script = path.join(appDir, "install-culpa.ps1");
+  const result = realSpawnSync(
+    "powershell.exe",
+    ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script, "-DeferStart", "-NonInteractive"],
+    { stdio: "inherit" },
+  );
+  return result.status === 0;
+}
+
+function writeState(appDir, state) {
+  writeFileSync(path.join(appDir, "install-state.json"), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function readExistingState(appDir) {
+  try {
+    return JSON.parse(readFileSync(path.join(appDir, "install-state.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// CF20-T6 — the honest, human-facing line for each classifyUpgrade outcome.
+// "upgrade" is explicit that the new version is STAGED, not running yet —
+// it applies at the next `getculpa` (start.mjs's QW-1-equivalent sync + T4's
+// launch orchestration), never here. Postinstall stays silent about
+// migrations by design: those are QW-4's job at that next `getculpa`, not
+// this one.
+function describeClassification(classification, previousVersion, currentVersion) {
+  switch (classification) {
+    case "fresh":
+      return `getculpa: installing Culpa ${currentVersion}.`;
+    case "upgrade":
+      return `getculpa: upgrading Culpa ${previousVersion} -> ${currentVersion} (staged; applies at next \`getculpa\`).`;
+    case "same-version":
+      return `getculpa: repairing the existing Culpa ${currentVersion} installation (same version reinstalled).`;
+    case "downgrade-package":
+      return (
+        `getculpa: this package (${currentVersion}) is older than the installed Culpa ${previousVersion} - ` +
+        "refusing to downgrade (set CULPA_ALLOW_DOWNGRADE=1 to override)."
+      );
+    case "repair":
+    default:
+      return "getculpa: repairing the existing Culpa installation.";
+  }
+}
+
+export async function provision(opts) {
+  const {
+    appDir,
+    currentVersion,
+    collectorFetched = false,
+    platform = process.platform,
+    arch = process.arch,
+    vendorDir = path.join(packageRoot, "vendor"),
+    dockerSpawnSync = realSpawnSync,
+    delegateWindowsInstaller = defaultDelegateWindowsInstaller,
+    env = process.env,
+  } = opts;
+
+  // Classify + capture the pre-existing state BEFORE anything below mutates
+  // appDir — both read the install-state.json / live compose that staging
+  // is about to overwrite.
+  const { classification, previousVersion } = classifyUpgrade({ appDir, currentVersion });
+  console.log(describeClassification(classification, previousVersion, currentVersion));
+  const existingState = readExistingState(appDir);
+
+  // CF20-R: a REFUSED downgrade (classification === "downgrade-package",
+  // CULPA_ALLOW_DOWNGRADE not set) used to still restage every OTHER parity
+  // file (the ps1 scripts, register.mjs) with the older package's copies —
+  // only culpa-compose.yml was protected (stageShippedCompose's own guard).
+  // That left a mixed-version app dir: a newer compose pin beside older
+  // scripts. Skip the WHOLE parity re-stage in this case instead, so the app
+  // dir stays wholly at the newer version; dir/state handling below is
+  // unaffected.
+  const allowDowngrade = env.CULPA_ALLOW_DOWNGRADE === "1";
+  const refusedDowngrade = classification === "downgrade-package" && !allowDowngrade;
+  if (refusedDowngrade) {
+    console.warn(
+      `getculpa: this package is older than the installed Culpa ${previousVersion} - skipping the parity file re-stage entirely (compose, scripts, register.mjs) to avoid a mixed-version app dir (set CULPA_ALLOW_DOWNGRADE=1 to override).`,
+    );
+  } else {
+    stageParityFiles(appDir, env, platform);
+  }
+  stageLiveComposeIfAbsent(appDir);
+
+  // T-CF29-8: only attempt it when the fetch reported success; the result is
+  // what gets recorded, not the intent.
+  const collectorStaged = collectorFetched && stageCollectorBinary({ appDir, vendorDir, platform, arch });
+  if (collectorFetched && !collectorStaged) {
+    console.warn(
+      "getculpa: the capture collector was downloaded but could not be placed in the app directory - capture OFF, everything else works.",
+    );
+  }
+
+  const dockerState = detectDockerState(dockerSpawnSync);
+  let imagesStaged = false;
+  if (dockerState === "ready") {
+    imagesStaged = stageImages(appDir, dockerSpawnSync);
+    if (!imagesStaged) {
+      console.warn("getculpa: image staging failed - images will be pulled at first `getculpa`.");
+    }
+  } else {
+    const why = dockerState === "missing" ? "Docker was not found" : "Docker is not running";
+    console.warn(`getculpa: ${why} - image staging deferred to first \`getculpa\`.`);
+  }
+
+  if (platform === "win32") {
+    // CF20-R: the Windows delegate registers the ONE fixed, per-machine HKCU
+    // uninstall key (install-culpa.ps1 / culpa-setup.iss's AppId). A second
+    // app dir on the same machine (CULPA_APP_DIR pointed somewhere
+    // non-default) must never overwrite that shared key — the gate's
+    // historical incident class. Only delegate when this appDir IS the
+    // canonical one (CULPA_APP_DIR's override stripped); otherwise skip
+    // registration and say so, once, honestly.
+    if (appDir === canonicalAppDir({ platform, env })) {
+      const ok = delegateWindowsInstaller(appDir);
+      if (!ok) {
+        console.warn("getculpa: Windows shortcut/registry setup did not complete cleanly - shortcuts may be missing.");
+      }
+    } else {
+      console.log("getculpa: non-canonical app dir: shortcuts/registry registration skipped.");
+    }
+  }
+
+  // T6 review (Important): a REFUSED downgrade must not record the rejected,
+  // older currentVersion as installed — the protected artifacts still carry
+  // the newer version, and this field is the ground truth the next run's
+  // classification reads. Persist the true installed version instead.
+  const recordedPackageVersion =
+    classification === "downgrade-package" && previousVersion ? previousVersion : currentVersion;
+  writeState(appDir, {
+    packageVersion: recordedPackageVersion,
+    previousVersion,
+    classification,
+    // provisionedAt is the FIRST install's timestamp, preserved across every
+    // subsequent provision() run; updatedAt is this run's.
+    provisionedAt: existingState?.provisionedAt ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    dockerState,
+    imagesStaged,
+    collectorStaged,
+    platform,
+  });
+
+  // T-CF28-5/7: the Docker and staging facts were already computed above and
+  // written to install-state.json, but the caller that has to REPORT them
+  // (scripts/install.js) could not see them — which is how a Docker-less
+  // install still printed "Culpa installed successfully." Returning them
+  // changes no behavior here; it just stops postinstall from having to guess.
+  return { classification, previousVersion, dockerState, imagesStaged, collectorStaged };
+}