@sentropic/h2a 0.97.9 → 0.97.11

package/dist/runtime/upgrade/index.js

@@ -26,12 +26,11 @@
  * atomic publication via `link(2)` (I1), a no-false-positive liveness predicate
  * (I3), a one-shot `SUCC(t)` succession chain (Lemmas B/C), token monotonicity
  * (I2). No age or mtime ever decides acquisition — `at` is diagnostic only
- * (I7). See the lock section below.
+ * (I7). See `../local-files/succession-lock.ts`.
  */
 import { randomBytes, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, fsyncSync, linkSync, openSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-import { hostname } from "node:os";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 export const H2A_CLI_PACKAGE = "@sentropic/h2a";
@@ -226,763 +225,12 @@ function readJsonIfExists(path) {
     }
 }
 // ---------------------------------------------------------------------------
-// Prefix lock (v4): single-machine succession protocol.
-//
-// At most one holder (proof sketch in the design notes):
-// - I1 (atomic publication): a name appears only with complete, durable
-//   content — tmp file (wx + write + fsync + close) then `link(2)`; a reader
-//   sees ENOENT or a full record, so unreadable content means corruption
-//   (fail closed), never a torn write. A FS without hard links fails closed.
-// - I2 (monotonicity): a retired token never reappears; LOCK != g is forever.
-// - I3 (predicate): `isCertainlyDead` has no false positive; death is stable.
-// - I4: only (R) the live owner releasing, or (S) a successor that created its
-//   SUCC then re-read LOCK == g, can remove LOCK == g.
-// - I5: no SUCC targeting g is removed while LOCK == g.
-// - I6: SUCC(t) always targets the same g (created after t judged dead).
-// - I7: no age or mtime in any acquisition decision; `at` is diagnostic only.
-//   Ages below are used solely for debris GC, never to break a lock.
-//
-// Lemma A (stability): while live holder P holds p, LOCK == p — removing it
-// would require SUCC(p), which requires P certainly dead. Lemma B (unique
-// successor): while LOCK == g the chain g -> r0 -> r1 ... is linear, so only
-// the last link can be live. Lemma C (targeted unlink): a successor that read
-// LOCK == g removes g, since no other live successor exists (Lemma B) and any
-// earlier one would already have made LOCK != g (I2).
-//
-// H1: the prefix is on a single machine's local FS; `link(2)` is atomic and
-// returns EEXIST when the name exists. H2: the recorded process runs the
-// shared mutation (swap) for the whole critical section; children (npm) only
-// touch a per-token private staging dir. H3: tokens are random (>= 96 bits)
-// and never republished.
-/**
- * R2 staleness-alert threshold. An upgrade held under the lock completes in seconds to
- * a few minutes (bounded tarball fetch + stage + atomic swap), so a lock far older than
- * that whose holder reads "live" ONLY for want of a comparable start time is worth
- * surfacing (a reused PID may be masking a dead holder). Set well above any legitimate
- * hold. It NEVER triggers a reclaim — purely diagnostic (I7: `at` informs, never decides).
- */
-export const STALE_LOCK_ALERT_MS = 30 * 60 * 1000;
-/** Acquire rounds before giving up (a retry means a rival won meanwhile). */
-export const PREFIX_LOCK_MAX_ROUNDS = 3;
-/** Succession chain depth before failing closed with a diagnostic. */
-export const PREFIX_LOCK_MAX_CHAIN = 8;
-/** Holder-only GC age for abandoned TMP files (debris, never a decision). */
-export const PREFIX_LOCK_TMP_DEBRIS_MAX_AGE_MS = 60 * 60 * 1000;
-/** Fallback age for the residue sweep when no owner can be identified. */
-export const UPGRADE_RESIDUE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
-/** Tokens are hex (plus -/_ tolerance); anything else in a record is corruption. */
-const LOCK_TOKEN_RE = /^[A-Za-z0-9_-]{12,128}$/;
-function lockPathFor(prefix) {
-    return join(prefix, ".h2a-upgrade.lock");
-}
-function succPathFor(lockPath, t) {
-    return `${lockPath}.succ.${t}`;
-}
-function tmpPathFor(path, t) {
-    // C2: the publish tmp must never live in the `.succ.` namespace, even when
-    // publishing a SUCC record. Derive it from the LOCK base so sweeps that
-    // match real SUCC records never collect a tmp before its link(2).
-    const idx = path.indexOf(".succ.");
-    const base = idx >= 0 ? path.slice(0, idx) : path;
-    return `${base}.tmp.${t}`;
-}
-function errnoOf(e) {
-    const code = e?.code;
-    return typeof code === "string" && code.length > 0 ? code : "EIO";
-}
-// N3: `at` is validated only as a finite number (parseLockRec), so it may be out of
-// Date's representable range; `new Date(at).toISOString()` would throw a RangeError.
-// Never let a diagnostic string crash the caller (at boot the exception would swallow
-// the whole M-2 alarm; `h2a upgrade` would abort). Fall back to the raw number.
-function safeAtIso(at) {
-    const ms = Number(at);
-    if (Number.isFinite(ms) && Math.abs(ms) <= 8.64e15) {
-        try {
-            return new Date(ms).toISOString();
-        }
-        catch {
-            // fall through
-        }
-    }
-    return `epoch-ms:${at}`;
-}
-function readHostId() {
-    try {
-        const v = readFileSync("/etc/machine-id", "utf8").trim();
-        if (v)
-            return v;
-    }
-    catch {
-        // fall through to hostname
-    }
-    try {
-        const h = hostname().trim();
-        if (h)
-            return h;
-    }
-    catch {
-        // fall through to sentinel
-    }
-    return "unknown-host";
-}
-function readBootId() {
-    try {
-        const v = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
-        if (v)
-            return v;
-    }
-    catch {
-        // not Linux: fall through to sysctl below
-    }
-    // Outside Linux prefer the stable session UUID (TZ-independent) when present.
-    try {
-        const r = spawnSync("sysctl", ["-n", "kern.bootsessionuuid"], {
-            encoding: "utf8",
-            timeout: 2000,
-            env: { ...process.env, LC_ALL: "C", TZ: "UTC0" }
-        });
-        const v = (r.stdout ?? "").trim();
-        if (r.status === 0 && v)
-            return v;
-    }
-    catch {
-        // best-effort
-    }
-    try {
-        const r = spawnSync("sysctl", ["-n", "kern.boottime"], {
-            encoding: "utf8",
-            timeout: 2000,
-            env: { ...process.env, LC_ALL: "C", TZ: "UTC0" }
-        });
-        const v = (r.stdout ?? "").trim();
-        if (r.status === 0 && v)
-            return v;
-    }
-    catch {
-        // best-effort
-    }
-    return null;
-}
-// B2 decomposition: distinguish "this platform has no namespaces" (a KNOWN fact —
-// one space per host) from "the namespace exists but is unreadable" (a genuine
-// unknown). Only the latter is null; the former is the sentinel "host" so same-host
-// liveness stays decidable (macOS/Windows/BSD). `platform`/`readLink` are injected
-// only by tests (macOS/Windows/no-/proc sims); production passes none.
-//
-// readPidNs is the CONSERVATIVE gate that decides reclaim at all: an unknown (null)
-// pid namespace makes even a PID-absent holder undecidable, because "absent" in an
-// unknown namespace proves nothing. Any Linux /proc failure → null, never a false
-// "host" that could match a foreign namespace.
-export function readPidNs(platform = process.platform, readLink = readlinkSync) {
-    if (platform !== "linux")
-        return "host";
-    try {
-        return readLink("/proc/self/ns/pid");
-    }
-    catch {
-        return null; // the namespace exists here but is unreadable: genuine unknown
-    }
-}
-// The reader's time namespace (Linux): /proc/<pid>/stat starttime is expressed
-// relative to it, so two lanes in different time namespaces read different values
-// for the same live process. timeNs is consulted ONLY to gate the start-time
-// COMPARISON (the PID-present branch of livenessOf); the PID-absent incident branch
-// never needs it. So this reader is SYMMETRIC with readPidNs on purpose — no ENOENT
-// special-case: a genuinely masked /proc (e.g. gVisor exposing ns/pid but not
-// ns/time while time namespaces are in use) must yield null (⇒ "start not
-// comparable ⇒ live"), never a false "host" that would compare across time bases
-// and risk a false death (the B-1 class). null here is safe and quiet, not a wedge.
-export function readTimeNs(platform = process.platform, readLink = readlinkSync) {
-    if (platform !== "linux")
-        return "host";
-    try {
-        return readLink("/proc/self/ns/time");
-    }
-    catch {
-        return null; // no readable time namespace: start times are not comparable
-    }
-}
-// Trust /proc for start/state only when it maps to THIS process's pid namespace.
-// Under `unshare --pid` without `--mount-proc`, `kill` targets the right process
-// but `/proc/<pid>` describes another — a false start mismatch or zombie.
-function procMapsToSelf() {
-    try {
-        return readlinkSync("/proc/self") === String(process.pid);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Process start identity, prefixed by its source ("proc:" from Linux /proc
- * field 22, "ps:" from `ps lstart`). The prefix is part of the stored value
- * so a reader using a different source never concludes "dead" from a
- * format/TZ-fragile comparison (C1).
- */
-// `platform`/`mapsToSelf` are injected only by tests (mis-mapped-/proc / non-Linux
-// sims); production passes none.
-export function procStartInfo(pid, platform = process.platform, mapsToSelf = procMapsToSelf) {
-    // A start time is only trusted from a source whose value is STABLE for the life of the
-    // process (never moving under a wall-clock step), else a clock jump while the lock is held
-    // could make a live holder's start "differ" ⇒ a false death ⇒ two holders (I3).
-    // - Linux: /proc field 22 (proc:) is the only trusted source.
-    //   - B3: a mis-mapped /proc (unshare --pid without --mount-proc) makes both /proc AND
-    //     `ps` (procps reads /proc/<pid>) describe another namespace's process ⇒ undatable.
-    //   - N5: `ps` lstart under Linux derives from btime + starttime and moves on a clock step,
-    //     so it is not stable either. So under Linux: /proc when it maps to us, else undefined.
-    // - darwin: `ps lstart` is the ABSOLUTE fork wall-clock time (p_starttime), stable ⇒ trusted.
-    // - R-BSD: on FreeBSD/OpenBSD `ps` start is boot-relative and its boot time is re-derived on
-    //   a clock step, so it is NOT stable. Every other non-Linux platform (incl. Windows, no ps)
-    //   ⇒ undefined (undatable ⇒ live). In doubt, never dead.
-    if (platform === "linux") {
-        if (!mapsToSelf())
-            return undefined;
-        try {
-            const s = readFileSync(`/proc/${pid}/stat`, "utf8");
-            const close = s.lastIndexOf(")");
-            if (close >= 0) {
-                const after = s.slice(close + 1).trim().split(/\s+/);
-                // after[0] is state (field 3); after[19] is starttime (field 22).
-                if (after.length >= 20 && after[0] && after[19]) {
-                    return { state: after[0], start: `proc:${after[19]}` };
-                }
-            }
-        }
-        catch {
-            // no readable /proc for this pid: undatable
-        }
-        return undefined;
-    }
-    if (platform !== "darwin")
-        return undefined; // only darwin ps is a stable source
-    try {
-        const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
-            encoding: "utf8",
-            timeout: 5000,
-            env: { ...process.env, LC_ALL: "C", TZ: "UTC0" }
-        });
-        const v = (r.stdout ?? "").trim();
-        if (r.status === 0 && v)
-            return { start: `ps:${v}` };
-    }
-    catch {
-        // best-effort
-    }
-    return undefined;
-}
-function startSource(s) {
-    if (s.startsWith("proc:"))
-        return "proc";
-    if (s.startsWith("ps:"))
-        return "ps";
-    return "legacy";
-}
-let ME_CACHE;
-/** This process's identity, computed once and memoized. */
-function me() {
-    ME_CACHE ??= {
-        host: readHostId(),
-        boot: readBootId(),
-        ns: readPidNs(),
-        timeNs: readTimeNs(),
-        pid: process.pid,
-        start: procStartInfo(process.pid)?.start ?? null
-    };
-    return ME_CACHE;
-}
-/** Fresh random token, >= 96 bits, never republished (H3). */
-function newToken() {
-    return randomBytes(16).toString("hex");
-}
-function makeLockRec(token, target) {
-    const self = me();
-    return {
-        host: self.host,
-        boot: self.boot,
-        ns: self.ns,
-        timeNs: self.timeNs,
-        pid: self.pid,
-        start: self.start,
-        token,
-        ...(target !== undefined ? { target } : {}),
-        at: Date.now()
-    };
-}
-function parseLockRec(raw) {
-    if (typeof raw !== "object" || raw === null)
-        throw new Error("bad lock record");
-    const o = raw;
-    const { host, boot, ns, timeNs, pid, start, token, target, at } = o;
-    // timeNs is a required field like host/boot/ns/pid/start: an absent field is a
-    // malformed record → corrupt → fail-closed. No back-compat exception is carved
-    // for a "v4 without timeNs" — the redesign was never published, so no such lock
-    // exists outside fixtures (kept in step with makeLockRec). The VALUE may be null
-    // (genuine unknown time namespace); the liveness guard then treats the proc start
-    // as undatable ⇒ "live" (never reclaim, never a false death), not undecidable.
-    if (typeof host !== "string" || host.length === 0)
-        throw new Error("bad host");
-    if (boot !== null && typeof boot !== "string")
-        throw new Error("bad boot");
-    if (ns !== null && typeof ns !== "string")
-        throw new Error("bad ns");
-    if (timeNs !== null && typeof timeNs !== "string")
-        throw new Error("bad timeNs");
-    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
-        throw new Error("bad pid");
-    if (start !== null && typeof start !== "string")
-        throw new Error("bad start");
-    if (typeof token !== "string" || !LOCK_TOKEN_RE.test(token))
-        throw new Error("bad token");
-    if (target !== undefined && typeof target !== "string")
-        throw new Error("bad target");
-    if (typeof at !== "number" || !Number.isFinite(at))
-        throw new Error("bad at");
-    return {
-        host,
-        boot,
-        ns,
-        timeNs,
-        pid,
-        start,
-        token,
-        ...(target !== undefined ? { target } : {}),
-        at
-    };
-}
-/** opus `read`: ENOENT -> absent, anything else unreadable -> corrupt (I1). */
-function readLockRecord(path) {
-    try {
-        return parseLockRec(JSON.parse(readFileSync(path, "utf8")));
-    }
-    catch (e) {
-        return e?.code === "ENOENT" ? "absent" : "corrupt";
-    }
-}
-/**
- * opus `publish` (I1): a name appears only with complete, durable content.
- * Write tmp (wx + byte-count-checked write + fsync + close), then `link(2)`;
- * EEXIST -> "exists", ENOENT at link -> "retry" (tmp reaped before link),
- * any other failure -> "error" with the errno (no hard links -> fail closed).
- * The tmp never contains `.succ.` (C2).
- */
-function publishLockRecord(path, rec) {
-    const tmp = tmpPathFor(path, rec.token);
-    try {
-        const data = JSON.stringify(rec);
-        const fd = openSync(tmp, "wx", 0o644);
-        let truncated = false;
-        try {
-            const written = writeSync(fd, data);
-            if (written !== Buffer.byteLength(data)) {
-                truncated = true;
-            }
-            else {
-                fsyncSync(fd);
-            }
-        }
-        finally {
-            try {
-                closeSync(fd);
-            }
-            catch {
-                // best-effort
-            }
-        }
-        if (truncated) {
-            try {
-                unlinkSync(tmp);
-            }
-            catch {
-                // best-effort
-            }
-            return { status: "error", code: "ENOSPC" };
-        }
-    }
-    catch (e) {
-        try {
-            unlinkSync(tmp);
-        }
-        catch {
-            // best-effort
-        }
-        return { status: "error", code: errnoOf(e) };
-    }
-    try {
-        linkSync(tmp, path);
-        return { status: "ok" };
-    }
-    catch (e) {
-        const code = errnoOf(e);
-        if (code === "EEXIST")
-            return { status: "exists" };
-        if (code === "ENOENT")
-            return { status: "retry" };
-        return { status: "error", code };
-    }
-    finally {
-        try {
-            unlinkSync(tmp);
-        }
-        catch {
-            // best-effort
-        }
-    }
-}
-/**
- * Single liveness classifier. `livenessOf` and `isCertainlyDead` are exactly its
- * "verdict"/"dead" arm, and the R2 staleness alert reads its `datable` bit, so none
- * of them can drift from this one decision. Never derives "dead" from a fragile
- * comparison: a source mismatch or an unknown/differing time namespace both yield a
- * safe "live" (undatable), and a corrupt "legacy" start yields "undecidable" (C1).
- */
-function classifyLiveness(r, self, deps = {}) {
-    const platform = deps.platform ?? process.platform;
-    const probe = deps.probe ?? procStartInfo;
-    if (r.host !== self.host)
-        return { verdict: "undecidable", datable: false }; // other machine
-    // B1: only a Linux boot_id is a stable, trustworthy boot identity, so a difference
-    // there is a previous boot ⇒ dead. Off Linux a boot difference must NOT short-circuit
-    // to undecidable (that wedged a Mac rebooted mid-lock forever); fall through to kill(0)
-    // (PID absent ⇒ dead, on every platform) then the start comparison (only conclusive
-    // where the start is datable — Linux /proc and darwin ps; on BSD/Windows it is undatable
-    // ⇒ live, so after a reboot a reused PID blocks until it exits, surfaced by R2).
-    if (r.boot && self.boot && r.boot !== self.boot && platform === "linux") {
-        return { verdict: "dead", datable: false };
-    }
-    // An unreadable namespace on EITHER side is a genuine unknown — two records with a
-    // null namespace must never be treated as co-located (null-equality).
-    if (r.ns === null || self.ns === null)
-        return { verdict: "undecidable", datable: false };
-    if (r.ns !== self.ns)
-        return { verdict: "undecidable", datable: false }; // other, known ns
-    // From here the namespace is known AND shared, so a PID's absence is conclusive.
-    let exists = false;
-    try {
-        process.kill(r.pid, 0);
-        exists = true;
-    }
-    catch (e) {
-        const code = errnoOf(e);
-        // PID absent in a known, shared namespace ⇒ dead, with certainty, no start time.
-        if (code === "ESRCH")
-            return { verdict: "dead", datable: false };
-        if (code === "EPERM")
-            exists = true; // exists, no permission: keep checking
-        else
-            return { verdict: "undecidable", datable: false };
-    }
-    const p = probe(r.pid); // undefined when unknown
-    if (p?.state === "Z")
-        return { verdict: "dead", datable: false }; // zombie never runs again
-    if (r.start !== null && p?.start !== undefined) {
-        const rSrc = startSource(r.start);
-        const pSrc = startSource(p.start);
-        // A "legacy" (malformed, pre-source-prefix) start is not a trustworthy value ⇒
-        // undecidable (fail closed). Any other source mismatch (proc vs ps) is simply not
-        // comparable ⇒ undatable ⇒ live.
-        if (rSrc === "legacy" || pSrc === "legacy")
-            return { verdict: "undecidable", datable: false };
-        if (rSrc !== pSrc)
-            return { verdict: "live", datable: false };
-        // proc starttime is expressed relative to the reader's time namespace, so a
-        // proc-sourced comparison is only meaningful when both time namespaces are KNOWN and
-        // EQUAL. Otherwise the recorded start is UNDATABLE ⇒ "live" — never reclaim, never a
-        // false death, never a false M-2 alarm. This never wedges an incident: the PID-absent
-        // branch concluded "dead" without a start. The only cost is a genuinely-reused PID
-        // left alive until it exits — rare, bounded, and surfaced by the R2 staleness alert.
-        // A ps: start now arises ONLY on darwin (procStartInfo trusts ps only there), where
-        // lstart is the absolute fork wall-clock (TZ-normalised), stable ⇒ it needs no time gate.
-        if (rSrc === "proc" && (r.timeNs === null || self.timeNs === null || r.timeNs !== self.timeNs)) {
-            return { verdict: "live", datable: false };
-        }
-        return p.start !== r.start
-            ? { verdict: "dead", datable: true } // PID reused (a confirmed different start)
-            : { verdict: "live", datable: true }; // same, confirmed process
-    }
-    // Present but with an undatable start ⇒ live: never reclaim a live-or-unknown holder.
-    return { verdict: exists ? "live" : "undecidable", datable: false };
-}
-export function livenessOf(r, self, deps = {}) {
-    return classifyLiveness(r, self, deps).verdict;
-}
-/** No false positive: true implies certainly dead; any doubt is alive (I3). */
-function isCertainlyDead(r) {
-    return classifyLiveness(r, me()).verdict === "dead";
-}
-function lockDenied(reason) {
-    return { acquired: false, release: () => { }, reason };
-}
-function invokeLockHook(fn, ctx) {
-    if (!fn)
-        return;
-    try {
-        fn(ctx);
-    }
-    catch {
-        // Observation-only: a test hook must never break the protocol.
-    }
-}
-/** opus `acquirePrefixLock`, plus M5 reasons and test-only critical hooks. */
-export function acquirePrefixLock(prefix, hooks = {}) {
-    const lockPath = lockPathFor(prefix);
-    try {
-        mkdirSync(prefix, { recursive: true });
-    }
-    catch (e) {
-        return lockDenied(`error:${errnoOf(e)}`);
-    }
-    const self = me();
-    for (let round = 0; round < PREFIX_LOCK_MAX_ROUNDS; round++) {
-        if (round === 0) {
-            invokeLockHook(hooks.beforePublishLock, { prefix, lockPath, path: lockPath, round, depth: 0 });
-        }
-        const tok = newToken();
-        const pub = publishLockRecord(lockPath, makeLockRec(tok));
-        if (pub.status === "ok")
-            return makeLease(prefix, lockPath, tok);
-        if (pub.status === "error")
-            return lockDenied(`error:${pub.code}`);
-        if (pub.status === "retry")
-            continue;
-        const cur = readLockRecord(lockPath);
-        if (cur === "absent")
-            continue; // released meanwhile
-        if (cur === "corrupt")
-            return lockDenied("dead-undecidable"); // fail closed
-        const live = livenessOf(cur, self);
-        if (live !== "dead")
-            return lockDenied(live === "live" ? "busy" : "dead-undecidable");
-        const next = succeedDeadToken(prefix, lockPath, cur.token, hooks, round);
-        if (next !== "retry")
-            return next;
-    }
-    return lockDenied("busy");
-}
-/**
- * opus `succeed`: the owner of g is certainly dead. Walk the one-shot chain
- * SUCC(g) -> SUCC(r0) -> ...; publishing a link elects the sole live
- * successor (Lemma B). "retry" means the chain settled meanwhile (re-read).
- */
-function succeedDeadToken(prefix, lockPath, g, hooks, round) {
-    const self = me();
-    let t = g;
-    for (let depth = 0; depth < PREFIX_LOCK_MAX_CHAIN; depth++) {
-        const tok = newToken();
-        const pub = publishLockRecord(succPathFor(lockPath, t), makeLockRec(tok, g));
-        if (pub.status === "ok") {
-            invokeLockHook(hooks.afterPublishSucc, {
-                prefix,
-                lockPath,
-                path: succPathFor(lockPath, t),
-                token: tok,
-                target: g,
-                round,
-                depth
-            });
-            return retireDeadToken(prefix, lockPath, g, hooks, round, depth);
-        }
-        if (pub.status === "error")
-            return lockDenied(`error:${pub.code}`);
-        if (pub.status === "retry")
-            return "retry";
-        const s = readLockRecord(succPathFor(lockPath, t));
-        if (s === "absent")
-            return "retry"; // chain already settled
-        if (s === "corrupt" || s.target !== g)
-            return lockDenied("dead-undecidable");
-        const live = livenessOf(s, self);
-        if (live !== "dead")
-            return lockDenied(live === "live" ? "busy" : "dead-undecidable");
-        t = s.token; // it died: succeed it
-    }
-    // Chain too deep: fail closed (diagnostic-only; no sink at this layer).
-    return lockDenied("dead-undecidable");
-}
-/**
- * opus `retire`: targeted removal (S) of exactly g (Lemma C), then purge the
- * now-inert SUCC files targeting g (I5), then publish a fresh token.
- */
-function retireDeadToken(prefix, lockPath, g, hooks, round, depth) {
-    const cur = readLockRecord(lockPath);
-    if (cur === "corrupt")
-        return lockDenied("dead-undecidable"); // keep our SUCC: fail closed
-    if (cur !== "absent" && cur.token === g) {
-        invokeLockHook(hooks.beforeRetireUnlink, {
-            prefix,
-            lockPath,
-            path: lockPath,
-            target: g,
-            round,
-            depth
-        });
-        // Lemma C (targeted removal), hardened: re-read LOCK as the LAST step before the
-        // unlink and remove it ONLY while it is STILL exactly g. Successor uniqueness
-        // (Lemma B) + monotonicity (I2) prove LOCK cannot legally change from g under this
-        // sole successor, so in production this re-read always confirms g. It is the
-        // defense-in-depth that also holds under manual intervention / a fresh owner /
-        // corruption appearing in this window: such a LOCK bears a different token (or is
-        // corrupt) and is NEVER deleted — we only ever unlink a lock we still own.
-        const now = readLockRecord(lockPath);
-        if (now === "corrupt")
-            return lockDenied("dead-undecidable"); // keep our SUCC: fail closed
-        if (now !== "absent" && now.token !== g) {
-            // A different owner appeared in the window: our SUCC(g) is inert. Purge it and
-            // retry against the new LOCK — never delete a lock we do not own.
-            purgeSuccession(prefix, lockPath, g);
-            return "retry";
-        }
-        if (now !== "absent") {
-            // now.token === g: safe to remove exactly g.
-            let unlinkCode;
-            try {
-                unlinkSync(lockPath); // (S) removes exactly g (Lemma C)
-            }
-            catch (e) {
-                unlinkCode = errnoOf(e);
-            }
-            invokeLockHook(hooks.afterRetireUnlink, {
-                prefix,
-                lockPath,
-                path: lockPath,
-                target: g,
-                round,
-                depth
-            });
-            // LOCK != g not established: keep our SUCC file, fail closed.
-            if (unlinkCode !== undefined && unlinkCode !== "ENOENT") {
-                return lockDenied(`error:${unlinkCode}`);
-            }
-        }
-        // now === "absent": g already removed by someone else; fall through to publish.
-    }
-    // From here LOCK != g forever (I2): every SUCC targeting g is inert.
-    purgeSuccession(prefix, lockPath, g); // unlink SUCC files whose target === g
-    const tok = newToken();
-    const pub = publishLockRecord(lockPath, makeLockRec(tok));
-    if (pub.status === "ok")
-        return makeLease(prefix, lockPath, tok);
-    if (pub.status === "exists" || pub.status === "retry")
-        return "retry";
-    return lockDenied(`error:${pub.code}`);
-}
-/**
- * opus `lease`: conditional release — unlink only when LOCK == tok (I2/Lemma
- * A: while we live, LOCK == tok is stable). Runs on process exit too.
- */
-function makeLease(prefix, lockPath, token) {
-    let done = false;
-    const release = () => {
-        if (done)
-            return;
-        done = true;
-        try {
-            process.off("exit", release);
-        }
-        catch {
-            // best-effort
-        }
-        const cur = readLockRecord(lockPath);
-        if (cur !== "absent" && cur !== "corrupt" && cur.token === token) {
-            try {
-                unlinkSync(lockPath); // (R) safe: LOCK == tok stable while we live
-            }
-            catch {
-                // best-effort
-            }
-        }
-        // else: lock lost — unreachable under the invariants (Lemma A).
-    };
-    try {
-        process.on("exit", release);
-    }
-    catch {
-        // best-effort
-    }
-    collectLockDebris(prefix, lockPath, token); // holder-only GC (I5-safe)
-    return { acquired: true, release, token };
-}
-/** Unlink SUCC files whose target === g (called only when LOCK != g can hold). */
-function purgeSuccession(prefix, lockPath, g) {
-    let names;
-    try {
-        names = readdirSync(prefix);
-    }
-    catch {
-        return;
-    }
-    const base = basename(lockPath);
-    for (const n of names) {
-        if (!n.startsWith(`${base}.succ.`))
-            continue;
-        if (n.includes(".tmp."))
-            continue; // C2: never treat a tmp as a SUCC record
-        const full = join(prefix, n);
-        const rec = readLockRecord(full);
-        if (rec !== "absent" && rec !== "corrupt" && rec.target === g) {
-            try {
-                unlinkSync(full);
-            }
-            catch {
-                // best-effort
-            }
-        }
-    }
-}
-/**
- * Holder-only GC (I5-safe: our token is the current LOCK value, so SUCC files
- * targeting anything else are inert; TMP files are never lock state).
- */
-function collectLockDebris(prefix, lockPath, token) {
-    let names;
-    try {
-        names = readdirSync(prefix);
-    }
-    catch {
-        return;
-    }
-    const base = basename(lockPath);
-    const now = Date.now();
-    for (const n of names) {
-        const full = join(prefix, n);
-        if (n.startsWith(`${base}.succ.`) && !n.includes(".tmp.")) {
-            const rec = readLockRecord(full);
-            if (rec !== "absent" && rec !== "corrupt" && rec.target !== token) {
-                try {
-                    unlinkSync(full);
-                }
-                catch {
-                    // best-effort
-                }
-            }
-        }
-        else if (n.startsWith(base) && n.includes(".tmp.")) {
-            // TMP debris (including legacy `.succ.*.tmp.*` names), never lock state.
-            try {
-                const age = now - statSync(full).mtimeMs;
-                if (age > PREFIX_LOCK_TMP_DEBRIS_MAX_AGE_MS) {
-                    try {
-                        unlinkSync(full);
-                    }
-                    catch {
-                        // best-effort
-                    }
-                }
-            }
-            catch {
-                // best-effort: leave what cannot be stated
-            }
-        }
-    }
-}
-/** True when the path is older than the threshold; false when unstated. */
-function isOlderThan(path, now, maxAgeMs) {
-    try {
-        return now - statSync(path).mtimeMs > maxAgeMs;
-    }
-    catch {
-        return false;
-    }
-}
+// Prefix lock (v4): extracted to `../local-files/succession-lock.ts` (Lot 4,
+// step 1 — neutral intra-package move). Re-exported here so the module's public
+// API is unchanged for existing importers (tests, cli.ts, src/index.ts).
+// ---------------------------------------------------------------------------
+export { STALE_LOCK_ALERT_MS, PREFIX_LOCK_MAX_ROUNDS, PREFIX_LOCK_MAX_CHAIN, PREFIX_LOCK_TMP_DEBRIS_MAX_AGE_MS, UPGRADE_RESIDUE_MAX_AGE_MS, readPidNs, readTimeNs, procStartInfo, livenessOf, acquirePrefixLock } from "../local-files/succession-lock.js";
+import { STALE_LOCK_ALERT_MS, PREFIX_LOCK_TMP_DEBRIS_MAX_AGE_MS, UPGRADE_RESIDUE_MAX_AGE_MS, errnoOf, acquirePrefixLock, classifyLiveness, isOlderThan, lockPathFor, me, readLockRecord, safeAtIso } from "../local-files/succession-lock.js";
 function pidFromAttemptName(name) {
     const m = /^\.h2a-upgrade-(?:staging|tarball)-(\d+)-/.exec(name);
     if (!m)