@sentropic/h2a 0.97.9 → 0.97.10

package/dist/runtime/local-files/succession-lock.js

@@ -0,0 +1,777 @@
+/**
+ * Succession lock (v4) — single-machine succession protocol.
+ *
+ * Extracted from `runtime/upgrade/index.ts` (Lot 4, step 1: neutral
+ * intra-package move — zero behaviour change). This is the shared lock primitive
+ * used by the auto-upgrade prefix lock today, and (later lots) by the identity
+ * binding lock. It is a LEAF: it imports only `node:fs/os/crypto/child_process`
+ * and nothing from the store, so `upgrade/index.ts` and `local-files/locks.ts`
+ * import it directly by file, never via `local-files/index.js`.
+ *
+ * The full protocol proof-sketch (I1–I7, Lemmas A–C) lives with the code below,
+ * moved unchanged from its original location.
+ */
+import { randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, join } from "node: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}$/;
+export 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}`;
+}
+export 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.
+export 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. */
+export 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");
+}
+export 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()
+    };
+}
+export 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). */
+export 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).
+ */
+export 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).
+ */
+export 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). */
+export 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. */
+export function isOlderThan(path, now, maxAgeMs) {
+    try {
+        return now - statSync(path).mtimeMs > maxAgeMs;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=succession-lock.js.map