@zq-silk/yui 0.13.9 → 0.14.0

package/dist/storage/upgrade/switchProgress.js

@@ -1,80 +0,0 @@
-/**
- * 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 });
-}

package/dist/storage/upgrade/upgradeReceipt.js

@@ -1,161 +0,0 @@
-/**
- * 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

@@ -1,187 +0,0 @@
-/**
- * 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. A staged updater child passes
- * its already-authenticated parent fence owner through this same boundary.
- */
-export function withUpgradeCoordinationLock(home, execute, fenceOwnerPid = process.pid) {
-    const release = acquireUpgradeCoordinationLock(home);
-    try {
-        assertUpgradeAdmission(home, fenceOwnerPid);
-        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, fenceOwnerPid = process.pid) {
-    assertHomeWritable(home, fenceOwnerPid);
-    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";
-}