@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/upgrade/switchProgress.js

@@ -0,0 +1,80 @@
+/**
+ * The atomic-switch progress marker — a durable, out-of-band record of where a
+ * two-step storage switch is in its lifecycle.
+ *
+ * ## Why (the partial-switch problem, P1-4)
+ *
+ * `atomicSwitchWithBackup` promotes a staged Home with two atomic renames on the
+ * same filesystem:
+ *
+ *   1. `home -> backup`   (move the original aside)
+ *   2. `staging -> home`  (promote the migrated output into place)
+ *
+ * The only non-atomic window is *between* those renames. If step 2 fails after
+ * step 1 committed, the original Home no longer exists at its path — so a naive
+ * "the source Home is unchanged" claim is FALSE. The switch either rolled back
+ * (original restored, truly unchanged) or is genuinely interrupted (original at
+ * the backup, nothing promoted into `home`).
+ *
+ * This marker makes the phase durable and readable AFTER the fact, so the
+ * orchestrator can tell:
+ *  - **not-started** — no marker (or cleared): nothing moved; source unchanged.
+ *  - **interrupted** — `phase: "interrupted"`: the original was moved aside and
+ *    neither promotion nor rollback completed; recover from the backup.
+ *  - **complete**    — the switch cleared its marker after a fully-committed
+ *    promotion.
+ *
+ * It lives at a SIBLING path of the Home (`<home>.upgrade-switch.json`), never
+ * inside it, so it survives the `home -> backup` / `staging -> home` renames —
+ * exactly like the completion receipt it coordinates with (see
+ * `upgradeReceipt.ts`).
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { writeTextFileAtomically } from "../durableFile.js";
+/** The sibling switch-progress marker path for a Home. */
+export function switchProgressPath(home) {
+    return join(dirname(home), `${basename(home)}.upgrade-switch.json`);
+}
+/** Write the switch-progress marker atomically. */
+export function writeSwitchProgress(home, progress) {
+    writeTextFileAtomically(switchProgressPath(home), `${JSON.stringify(progress, null, 2)}\n`);
+}
+/**
+ * Read the switch-progress marker, or `null` when absent/unreadable/malformed.
+ * A marker whose `phase` is not a recognized value reads as `null` — the caller
+ * treats an unreadable marker conservatively (it separately inspects the backup
+ * and the on-disk Home).
+ */
+export function readSwitchProgress(home) {
+    const path = switchProgressPath(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        const phase = value.phase;
+        if (phase !== "backing-up" && phase !== "promoting" && phase !== "interrupted") {
+            return null;
+        }
+        if (typeof value.homePath !== "string"
+            || typeof value.backupPath !== "string"
+            || typeof value.stagingPath !== "string"
+            || typeof value.updatedAt !== "string") {
+            return null;
+        }
+        return {
+            phase,
+            homePath: value.homePath,
+            backupPath: value.backupPath,
+            stagingPath: value.stagingPath,
+            updatedAt: value.updatedAt
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort removal of the switch-progress marker (on rollback / completion). */
+export function clearSwitchProgress(home) {
+    rmSync(switchProgressPath(home), { force: true });
+}