@zq-silk/yui 0.2.0 → 0.4.2

package/dist/storage/upgrade/upgradeReceipt.js

@@ -0,0 +1,161 @@
+/**
+ * The upgrade completion receipt — a verifiable, out-of-band marker that a
+ * storage switch actually committed.
+ *
+ * ## Why (the activation-ambiguity problem)
+ *
+ * `yui update` activates storage by spawning the staged binary's `yui upgrade`.
+ * If that child is killed (SIGTERM/OOM) *after* the atomic switch commits but
+ * *before* it prints its success JSON, the parent sees empty stdout and cannot
+ * tell "nothing happened" from "storage already switched". Treating that as
+ * recoverable (source unchanged) is a false claim that can hide a completed
+ * migration.
+ *
+ * The receipt closes that gap: `runStorageUpgrade` writes it the instant the
+ * switch commits and clears it only on a clean, fully-verified return. So its
+ * presence is a durable "the switch committed but clean completion was not
+ * confirmed" signal that the parent can read even when stdout was lost.
+ *
+ * It lives at a SIBLING path of the Home (`<home>.upgrade-receipt.json`), never
+ * inside it, so it survives the switch's `home -> backup` / `staging -> home`
+ * renames and is readable by both the child (new binary) and the parent (old
+ * binary), which share the same fixed `YUI_HOME` path.
+ */
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { writeTextFileAtomically } from "../durableFile.js";
+/** The sibling receipt path for a Home. */
+export function upgradeReceiptPath(home) {
+    return join(dirname(home), `${basename(home)}.upgrade-receipt.json`);
+}
+/** Write the completion receipt atomically, just after the switch commits. */
+export function writeUpgradeReceipt(home, receipt) {
+    writeTextFileAtomically(upgradeReceiptPath(home), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+/**
+ * Read the completion receipt, or `null` when absent/unreadable. A malformed
+ * receipt reads as `null`: it is only ever corroborating evidence, and the
+ * caller separately inspects the on-disk schema and backup.
+ */
+export function readUpgradeReceipt(home) {
+    const path = upgradeReceiptPath(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (value.switched !== true || typeof value.completedAt !== "string")
+            return null;
+        return {
+            switched: true,
+            completedAt: value.completedAt,
+            ...(typeof value.homePath === "string" ? { homePath: value.homePath } : {}),
+            ...(typeof value.backupPath === "string" ? { backupPath: value.backupPath } : {}),
+            ...(Number.isInteger(value.targetLayoutVersion)
+                ? { targetLayoutVersion: value.targetLayoutVersion }
+                : {}),
+            ...(Number.isInteger(value.targetAggregateVersion)
+                ? { targetAggregateVersion: value.targetAggregateVersion }
+                : {})
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate that a receipt genuinely corresponds to the current Home AND its
+ * backup before trusting it for a recovery decision (P2-6 / R3-F6). Existence
+ * alone is not correspondence: a receipt is trusted only when it carries the
+ * current protocol's correlating fields and its backup is a REAL directory at the
+ * exact timestamped-sibling path this Home's switch would have produced. Each
+ * rule closes a concrete staleness/impersonation gap:
+ *
+ *  - **no receipt** — nothing to correlate.
+ *  - **missing/foreign homePath** — a legacy receipt without `homePath`, or one
+ *    naming a different Home, says nothing trustworthy about THIS Home; the
+ *    current protocol always stamps `homePath`, so its absence is a legacy/degraded
+ *    marker that must be re-probed, not reused.
+ *  - **missing backupPath** — a receipt with no backup path is a degraded/legacy
+ *    marker; without the exact backup to correlate against we cannot confirm it,
+ *    so we re-probe rather than assert a committed switch.
+ *  - **backup not the expected sibling** — a `backupPath` that is not
+ *    `<home>.backup-*` in the Home's own parent directory is unrelated evidence
+ *    (a copied/foreign receipt); reject it.
+ *  - **backup absent or not a directory** — the switch it recorded was already
+ *    rolled back/cleaned, or the path is not a real backup dir; re-probe.
+ *
+ * On any rejection the caller falls back to an explicit "uncertain → re-probe the
+ * real on-disk state" rather than deriving a recovery instruction from stale or
+ * unrelated evidence.
+ */
+export function correlateUpgradeReceipt(home) {
+    const receipt = readUpgradeReceipt(home);
+    if (receipt === null) {
+        return { corresponds: false, reason: "no receipt present", receipt: null };
+    }
+    // The current protocol always records the Home it is about; a receipt without
+    // `homePath`, or naming a different Home, is legacy/foreign — never trusted.
+    if (receipt.homePath === undefined) {
+        return {
+            corresponds: false,
+            reason: "receipt has no homePath (legacy/degraded marker); re-probing current state",
+            receipt
+        };
+    }
+    if (receipt.homePath !== home) {
+        return {
+            corresponds: false,
+            reason: `receipt names a different Home (${receipt.homePath} != ${home})`,
+            receipt
+        };
+    }
+    // A trustworthy receipt must carry the exact backup its switch created.
+    if (receipt.backupPath === undefined) {
+        return {
+            corresponds: false,
+            reason: "receipt has no backupPath; cannot correlate a committed switch — re-probing",
+            receipt
+        };
+    }
+    if (!isExpectedBackupSibling(home, receipt.backupPath)) {
+        return {
+            corresponds: false,
+            reason: `receipt backup ${receipt.backupPath} is not this Home's expected timestamped sibling; unrelated evidence`,
+            receipt
+        };
+    }
+    if (!isRealDirectory(receipt.backupPath)) {
+        return {
+            corresponds: false,
+            reason: `receipt backup ${receipt.backupPath} is absent or not a directory (already restored or cleaned)`,
+            receipt
+        };
+    }
+    return { corresponds: true, receipt };
+}
+/**
+ * True when `backupPath` is the exact `<home>.backup-<stamp>` sibling in the
+ * Home's own parent directory that this Home's atomic switch would produce (see
+ * `homeMigrationTarget.atomicSwitchWithBackup`). Rejects any path in a different
+ * directory or without the `<basename>.backup-` prefix — i.e. unrelated evidence.
+ */
+function isExpectedBackupSibling(home, backupPath) {
+    if (dirname(backupPath) !== dirname(home))
+        return false;
+    const prefix = `${basename(home)}.backup-`;
+    const name = basename(backupPath);
+    return name.startsWith(prefix) && name.length > prefix.length;
+}
+/** True when `path` exists and is a real directory (not a file/symlink target miss). */
+function isRealDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Best-effort removal of the receipt (on clean success or before a fresh run). */
+export function clearUpgradeReceipt(home) {
+    rmSync(upgradeReceiptPath(home), { force: true });
+}

package/dist/storage/upgradeCoordination.js

@@ -0,0 +1,186 @@
+/**
+ * Shared coordination boundary for durable runtime-hook admission and the
+ * final Home snapshot/switch.
+ *
+ * The upgrade fence answers "may a new writer start?" but a writer that has
+ * already passed that check can still be in the middle of its durable inbox
+ * write.  This sibling lock supplies the missing linearization point:
+ *
+ *   inbox publish: acquire lock -> check fence/progress -> write -> release
+ *   upgrade cutover: acquire lock -> check drain -> copy -> switch -> release
+ *
+ * The lock lives beside (not inside) the Home, so the home -> backup and
+ * staging -> home renames cannot move it out from under a live holder.  It is
+ * a short, non-reentrant-on-disk critical section with a bounded wait.  A
+ * crashed holder leaves its directory behind; a later entrant may atomically
+ * rename it aside only after the owner is provably dead (or an owner-less
+ * directory has exceeded the conservative age bound).  No TTL is used to
+ * evict a live owner, and a live/undeterminable holder fails closed.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { assertHomeWritable, UpgradeFenceError } from "./upgradeFence.js";
+import { STORAGE_SCHEMA_FILE } from "./storageSchema.js";
+import { switchProgressPath } from "./upgrade/switchProgress.js";
+/** Sibling directory used for the shared inbox/cutover critical section. */
+export function upgradeCoordinationLockPath(home) {
+    return `${home}.upgrade-coordination.lock`;
+}
+const COORDINATION_LOCK_TIMEOUT_MS = 5_000;
+const COORDINATION_LOCK_RETRY_MS = 10;
+const COORDINATION_LOCK_MIN_AGE_MS = 1_000;
+/**
+ * Run a synchronous operation at the shared admission/cutover boundary.
+ *
+ * The admission check is intentionally performed *after* acquiring the lock.
+ * A hook that passed a check before an upgrade placed its fence either owns the
+ * lock and finishes before cutover, or waits and receives an explicit
+ * UpgradeFenceError after the cutover holder releases it.  There is no second
+ * scan or retry protocol hidden in this helper.
+ */
+export function withUpgradeCoordinationLock(home, execute) {
+    const release = acquireUpgradeCoordinationLock(home);
+    try {
+        assertUpgradeAdmission(home);
+        return execute();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Refuse admission when a foreign upgrade fence or an unresolved durable
+ * switch-progress marker is present.  A marker is actionable only while the
+ * filesystem corroborates a missing/uninitialized Home; a stale marker beside
+ * an intact Home is safe to ignore, matching update's recovery probe and
+ * avoiding a permanent post-promote hook deadlock.  A malformed marker with a
+ * missing Home still fails closed because its recovery phase cannot be trusted.
+ */
+export function assertUpgradeAdmission(home) {
+    assertHomeWritable(home);
+    const progressPath = switchProgressPath(home);
+    if (!existsSync(progressPath))
+        return;
+    const homeInitialized = existsSync(join(home, STORAGE_SCHEMA_FILE));
+    if (!homeInitialized) {
+        throw new UpgradeFenceError("storage switch recovery is in progress; the Home is not yet safe for a new write");
+    }
+    // A marker with an intact Home is stale relative to the filesystem (for
+    // example, a best-effort marker-clear failure after promotion). Reads and
+    // normal hook writes may proceed; update reports the marker only when
+    // backup+missing-Home evidence corroborates an interrupted switch.
+}
+// A same-process nested call is safe because the critical section is synchronous
+// and cannot interleave with another turn.  Cross-process ownership remains
+// governed by the on-disk mkdir boundary.
+const ownedLocks = new Map();
+function acquireUpgradeCoordinationLock(home) {
+    const lock = upgradeCoordinationLockPath(home);
+    const nested = ownedLocks.get(lock);
+    if (nested !== undefined) {
+        nested.depth += 1;
+        return () => releaseNested(lock, nested);
+    }
+    mkdirSync(dirname(lock), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + COORDINATION_LOCK_TIMEOUT_MS;
+    while (true) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            try {
+                writeFileSync(`${lock}/owner`, `${process.pid}\n`, { mode: 0o600 });
+            }
+            catch (error) {
+                rmSync(lock, { recursive: true, force: true });
+                throw error;
+            }
+            const release = () => releaseOwnedLock(lock, process.pid);
+            ownedLocks.set(lock, { depth: 1, release });
+            return release;
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+            if (reclaimStaleCoordinationLock(lock))
+                continue;
+            if (Date.now() >= deadline) {
+                throw new UpgradeFenceError("shared inbox/cutover coordination is held by another process; retry after it exits");
+            }
+            // Match the bounded wait used by the existing storage lock.  This is
+            // contention backoff, not a correctness delay or a blind retry of a
+            // publish/switch operation.
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, COORDINATION_LOCK_RETRY_MS);
+        }
+    }
+}
+function releaseNested(lock, owned) {
+    owned.depth -= 1;
+    if (owned.depth === 0) {
+        ownedLocks.delete(lock);
+        owned.release();
+    }
+}
+function releaseOwnedLock(lock, ownerPid) {
+    const current = readOwnerPid(lock);
+    // Never remove a successor's lock if a stale release races with recovery.
+    if (current === ownerPid)
+        rmSync(lock, { recursive: true, force: true });
+}
+/**
+ * Move an orphaned lock aside atomically.  The directory is never deleted in
+ * place while another process could be acquiring it: rename-aside gives the
+ * next O_EXCL mkdir a clean path and preserves a live replacement.
+ */
+function reclaimStaleCoordinationLock(lock) {
+    let age;
+    try {
+        age = Date.now() - statSync(lock).mtimeMs;
+    }
+    catch (error) {
+        return isEnoent(error);
+    }
+    if (age < COORDINATION_LOCK_MIN_AGE_MS)
+        return false;
+    const ownerPid = readOwnerPid(lock);
+    if (ownerPid !== null && processIsAlive(ownerPid))
+        return false;
+    const abandoned = `${lock}.reclaim-${process.pid}-${randomUUID()}`;
+    try {
+        renameSync(lock, abandoned);
+        rmSync(abandoned, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        // ENOENT means the holder released it (or another reclaimer won); retry the
+        // mkdir.  Any other failure is undeterminable and therefore fail-closed.
+        return isEnoent(error);
+    }
+}
+function readOwnerPid(lock) {
+    let raw;
+    try {
+        raw = readFileSync(`${lock}/owner`, "utf8").trim();
+    }
+    catch {
+        return null;
+    }
+    if (!/^\d+$/.test(raw))
+        return null;
+    const pid = Number(raw);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "EPERM";
+    }
+}
+function isEexist(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+function isEnoent(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}