niceeval 0.13.1 → 0.13.2

package/dist/runner/shared-state-lease.cjs

@@ -0,0 +1,803 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharedStateLeaseError = exports.SHARED_STATE_LEASE_HEARTBEAT_INTERVAL_MS = void 0;
+exports.sharedStateLeasesDirOf = sharedStateLeasesDirOf;
+exports.readSharedStateLeaseEffect = readSharedStateLeaseEffect;
+exports.readSharedStateLeaseRecoveryTargetEffect = readSharedStateLeaseRecoveryTargetEffect;
+exports.processIdentityForPidEffect = processIdentityForPidEffect;
+exports.currentProcessIdentityEffect = currentProcessIdentityEffect;
+exports.acquireSharedStateLeaseEffect = acquireSharedStateLeaseEffect;
+exports.beginExplicitSharedStateRecoveryEffect = beginExplicitSharedStateRecoveryEffect;
+exports.completeExplicitSharedStateRecoveryEffect = completeExplicitSharedStateRecoveryEffect;
+// Shared-state leases protect an author's external mutable state. They are
+// deliberately *not* case locks: a lease never expires and is never taken
+// over by a waiter. A crashed or failed cleanup path stays visible until an
+// operator performs the explicit, owner-token-checked recovery flow.
+//
+// The durable authority is an append-only generation chain. A transition may
+// only publish generation N + 1 after observing exact generation N, and uses
+// a same-directory hard-link to occupy that fixed N + 1 name. Consequently a
+// stale actor cannot delete, replace, or otherwise reach a newer generation.
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const effect_1 = require("effect");
+const entry_file_store_ts_1 = require("../shared/entry-file-store.cjs");
+const SHARED_STATE_LEASE_NAMESPACE = "niceeval/shared-state/v3";
+const SHARED_STATE_GENERATION_FORMAT = "niceeval.shared-state-generation/v1";
+const SHARED_STATE_HEARTBEAT_FORMAT = "niceeval.shared-state-heartbeat/v1";
+const GENERATION_FILE_PREFIX = "generation-";
+const GENERATION_FILE_SUFFIX = ".json";
+const GENERATION_WIDTH = 20;
+exports.SHARED_STATE_LEASE_HEARTBEAT_INTERVAL_MS = 10000;
+class SharedStateLeaseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SharedStateLeaseError";
+    }
+}
+exports.SharedStateLeaseError = SharedStateLeaseError;
+function errnoCode(cause) {
+    return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string"
+        ? cause.code
+        : undefined;
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function recordOf(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nodeIo(operation) {
+    return effect_1.Effect.tryPromise({ try: operation, catch: (cause) => cause });
+}
+function nodeSync(operation) {
+    return effect_1.Effect.try({ try: operation, catch: (cause) => cause });
+}
+function withOpenFile(path, flags, use) {
+    return effect_1.Effect.scoped(effect_1.Effect.acquireRelease(nodeIo(() => (0, promises_1.open)(path, flags)), (handle) => nodeIo(() => handle.close()).pipe(effect_1.Effect.orDie)).pipe(effect_1.Effect.flatMap(use)));
+}
+function sharedStateLeasesDirOf(niceevalRoot) {
+    return (0, node_path_1.join)(niceevalRoot, "shared-state-leases");
+}
+function sharedStateLeaseEntryId(key) {
+    return (0, entry_file_store_ts_1.slugHashEntryId)(key, [SHARED_STATE_LEASE_NAMESPACE, key]);
+}
+function sharedStateLeaseGenerationDirOf(niceevalRoot, key) {
+    return (0, node_path_1.join)(sharedStateLeasesDirOf(niceevalRoot), `${sharedStateLeaseEntryId(key)}.generations`);
+}
+function sharedStateLeaseHeartbeatDirOf(generationDir) {
+    return (0, node_path_1.join)(generationDir, "heartbeats");
+}
+function sharedStateLeaseHeartbeatEntryId(record) {
+    return (0, entry_file_store_ts_1.slugHashEntryId)(`generation-${record.generation}`, ["niceeval/shared-state-heartbeat/v1", record.key, record.ownerToken, String(record.generation)]);
+}
+/** v2 used a mutable flat entry. We only read it to fail closed or explicitly recover it. */
+function legacySharedStateLeasePath(niceevalRoot, key) {
+    return (0, node_path_1.join)(sharedStateLeasesDirOf(niceevalRoot), `${(0, entry_file_store_ts_1.slugHashEntryId)(key, ["niceeval/shared-state/v2", key])}.json`);
+}
+function generationFileName(generation) {
+    return `${GENERATION_FILE_PREFIX}${String(generation).padStart(GENERATION_WIDTH, "0")}${GENERATION_FILE_SUFFIX}`;
+}
+function generationFromFileName(name) {
+    const match = /^generation-(\d+)\.json$/u.exec(name);
+    if (match === null)
+        return undefined;
+    const generation = Number(match[1]);
+    return isPositiveInteger(generation) && name === generationFileName(generation) ? generation : undefined;
+}
+function decodeRecoveryActor(value) {
+    const actor = recordOf(value);
+    if (actor === undefined ||
+        !isPositiveInteger(actor.pid) ||
+        !isNonEmptyString(actor.host) ||
+        !isNonEmptyString(actor.processIdentity) ||
+        !isTimestamp(actor.startedAt)) {
+        return undefined;
+    }
+    return Object.freeze({
+        pid: actor.pid,
+        host: actor.host,
+        processIdentity: actor.processIdentity,
+        startedAt: actor.startedAt,
+    });
+}
+function decodeSharedStateLeaseRecord(key, value, opts = {}) {
+    const record = recordOf(value);
+    if (record === undefined)
+        return undefined;
+    const recoveryActor = record.recoveryActor === undefined ? undefined : decodeRecoveryActor(record.recoveryActor);
+    const recovering = record.status === "recovering";
+    const generation = opts.legacy ? 0 : record.generation;
+    const parentGeneration = opts.legacy ? 0 : record.parentGeneration;
+    if (record.key !== key ||
+        !isNonEmptyString(record.experimentId) ||
+        !isNonEmptyString(record.ownerToken) ||
+        !isPositiveInteger(record.pid) ||
+        !isNonEmptyString(record.host) ||
+        !isNonEmptyString(record.processIdentity) ||
+        !isTimestamp(record.acquiredAt) ||
+        !isTimestamp(record.heartbeatAt) ||
+        (record.status !== "active" && !recovering) ||
+        (!opts.legacy && (!isPositiveInteger(generation) || !isNonNegativeInteger(parentGeneration) || parentGeneration >= generation)) ||
+        (recovering && (!isNonEmptyString(record.recoveryId) || recoveryActor === undefined)) ||
+        (!recovering && (record.recoveryId !== undefined || record.recoveryActor !== undefined))) {
+        return undefined;
+    }
+    return Object.freeze({
+        key,
+        experimentId: record.experimentId,
+        ownerToken: record.ownerToken,
+        pid: record.pid,
+        host: record.host,
+        processIdentity: record.processIdentity,
+        acquiredAt: record.acquiredAt,
+        heartbeatAt: record.heartbeatAt,
+        status: record.status,
+        generation: generation,
+        parentGeneration: parentGeneration,
+        ...(recovering ? { recoveryId: record.recoveryId, recoveryActor: recoveryActor } : {}),
+    });
+}
+function decodeSharedStateLeaseHeartbeat(record, value) {
+    const heartbeat = recordOf(value);
+    if (heartbeat === undefined ||
+        heartbeat.format !== SHARED_STATE_HEARTBEAT_FORMAT ||
+        heartbeat.key !== record.key ||
+        heartbeat.ownerToken !== record.ownerToken ||
+        heartbeat.generation !== record.generation ||
+        heartbeat.parentGeneration !== record.parentGeneration ||
+        !isTimestamp(heartbeat.heartbeatAt) ||
+        Date.parse(heartbeat.heartbeatAt) < Date.parse(record.acquiredAt)) {
+        return undefined;
+    }
+    return Object.freeze({
+        format: SHARED_STATE_HEARTBEAT_FORMAT,
+        key: record.key,
+        ownerToken: record.ownerToken,
+        generation: record.generation,
+        parentGeneration: record.parentGeneration,
+        heartbeatAt: heartbeat.heartbeatAt,
+    });
+}
+/**
+ * A heartbeat is diagnostic only: unreadable, missing, stale, or malformed
+ * sidecars leave the immutable generation record unchanged. Matching all of
+ * key/token/generation/parent makes an old owner's sidecar inapplicable after
+ * any release, recovery, or later acquisition.
+ */
+function readDiagnosticHeartbeatEffect(generationDir, record) {
+    return (0, entry_file_store_ts_1.readEntryFileEffect)(sharedStateLeaseHeartbeatDirOf(generationDir), sharedStateLeaseHeartbeatEntryId(record), (value) => decodeSharedStateLeaseHeartbeat(record, value)).pipe(effect_1.Effect.map((heartbeat) => heartbeat === undefined
+        ? record
+        : Object.freeze({ ...record, heartbeatAt: heartbeat.heartbeatAt })), effect_1.Effect.catchAll(() => effect_1.Effect.succeed(record)));
+}
+function writeDiagnosticHeartbeatEffect(generationDir, record, heartbeatAt) {
+    const heartbeat = Object.freeze({
+        format: SHARED_STATE_HEARTBEAT_FORMAT,
+        key: record.key,
+        ownerToken: record.ownerToken,
+        generation: record.generation,
+        parentGeneration: record.parentGeneration,
+        heartbeatAt,
+    });
+    return (0, entry_file_store_ts_1.writeEntryFileEffect)(sharedStateLeaseHeartbeatDirOf(generationDir), sharedStateLeaseHeartbeatEntryId(record), heartbeat);
+}
+function decodeGeneration(key, value) {
+    const generation = recordOf(value);
+    if (generation === undefined || generation.format !== SHARED_STATE_GENERATION_FORMAT)
+        return undefined;
+    if (generation.kind === "lease") {
+        const record = decodeSharedStateLeaseRecord(key, generation);
+        return record === undefined ? undefined : Object.freeze({ kind: "lease", record });
+    }
+    if (generation.kind !== "free")
+        return undefined;
+    const previous = decodeSharedStateLeaseRecord(key, generation.previous);
+    if (previous === undefined ||
+        generation.key !== key ||
+        !isPositiveInteger(generation.generation) ||
+        !isNonNegativeInteger(generation.parentGeneration) ||
+        generation.parentGeneration >= generation.generation ||
+        generation.parentGeneration !== previous.generation ||
+        !isTimestamp(generation.releasedAt)) {
+        return undefined;
+    }
+    return Object.freeze({
+        kind: "free",
+        key,
+        generation: generation.generation,
+        parentGeneration: generation.parentGeneration,
+        releasedAt: generation.releasedAt,
+        previous,
+    });
+}
+function durableLeaseGeneration(record) {
+    return { format: SHARED_STATE_GENERATION_FORMAT, kind: "lease", ...record };
+}
+function durableFreeGeneration(record) {
+    return {
+        format: SHARED_STATE_GENERATION_FORMAT,
+        kind: "free",
+        key: record.key,
+        generation: record.generation,
+        parentGeneration: record.parentGeneration,
+        releasedAt: record.releasedAt,
+        previous: record.previous,
+    };
+}
+function generationNumber(generation) {
+    if (generation === undefined)
+        return 0;
+    return generation.kind === "free" ? generation.generation : generation.record.generation;
+}
+function leaseRecordOf(generation) {
+    return generation?.kind === "lease" || generation?.kind === "legacy" ? generation.record : undefined;
+}
+function sameRecoveryActor(left, right) {
+    return left.pid === right.pid &&
+        left.host === right.host &&
+        left.processIdentity === right.processIdentity &&
+        left.startedAt === right.startedAt;
+}
+function sameLeaseRecord(left, right) {
+    return left.key === right.key &&
+        left.experimentId === right.experimentId &&
+        left.ownerToken === right.ownerToken &&
+        left.pid === right.pid &&
+        left.host === right.host &&
+        left.processIdentity === right.processIdentity &&
+        left.acquiredAt === right.acquiredAt &&
+        left.heartbeatAt === right.heartbeatAt &&
+        left.status === right.status &&
+        left.generation === right.generation &&
+        left.parentGeneration === right.parentGeneration &&
+        left.recoveryId === right.recoveryId &&
+        (left.recoveryActor === undefined
+            ? right.recoveryActor === undefined
+            : right.recoveryActor !== undefined && sameRecoveryActor(left.recoveryActor, right.recoveryActor));
+}
+/** The immutable holder evidence must survive a recovery-to-recovery transition. */
+function sameLeaseOwnerEvidence(left, right) {
+    return left.key === right.key &&
+        left.experimentId === right.experimentId &&
+        left.ownerToken === right.ownerToken &&
+        left.pid === right.pid &&
+        left.host === right.host &&
+        left.processIdentity === right.processIdentity &&
+        left.acquiredAt === right.acquiredAt &&
+        left.heartbeatAt === right.heartbeatAt;
+}
+function legalFirstGeneration(first, legacy) {
+    if (first.kind !== "lease")
+        return false;
+    if (first.record.status === "active")
+        return legacy === undefined;
+    // The only allowed v2 migration is explicit recovery: legacy has no v3
+    // transition slot, so it becomes immutable recovering generation 1.
+    return legacy !== undefined && sameLeaseOwnerEvidence(first.record, legacy);
+}
+function legalGenerationTransition(previous, next) {
+    if (previous.kind === "free") {
+        // Only a normal acquisition may follow a released generation.
+        return next.kind === "lease" && next.record.status === "active";
+    }
+    const previousRecord = previous.record;
+    if (next.kind === "free") {
+        // A free record is a compare-owner release, not a newly invented history.
+        return sameLeaseRecord(next.previous, previousRecord);
+    }
+    // An active holder cannot be replaced by another active holder. The sole
+    // lease-to-lease transition is explicit recovery, retaining the original
+    // owner evidence while assigning a new recovery actor/id.
+    if (next.record.status !== "recovering" || !sameLeaseOwnerEvidence(next.record, previousRecord))
+        return false;
+    if (previousRecord.status !== "recovering")
+        return true;
+    // Recovering -> recovering is a new, separately identified recovery after
+    // the prior actor stopped. Reusing either identity would make a stale actor
+    // indistinguishable from the new operation.
+    return next.record.recoveryId !== previousRecord.recoveryId &&
+        next.record.recoveryActor !== undefined &&
+        previousRecord.recoveryActor !== undefined &&
+        !sameRecoveryActor(next.record.recoveryActor, previousRecord.recoveryActor);
+}
+function validateGenerationTransitions(key, entries, legacy) {
+    let previousGeneration = 0;
+    let previous;
+    for (const entry of entries) {
+        const stateGeneration = generationNumber(entry.state);
+        const parentGeneration = entry.state.kind === "free"
+            ? entry.state.parentGeneration
+            : entry.state.record.parentGeneration;
+        if (entry.generation !== previousGeneration + 1 || stateGeneration !== entry.generation || parentGeneration !== previousGeneration) {
+            return invalidLeaseError(key, "generations are not a contiguous exact-parent chain");
+        }
+        if (previous === undefined) {
+            if (!legalFirstGeneration(entry.state, legacy)) {
+                return invalidLeaseError(key, "generation 1 must be an active fresh lease or a recovery of the exact v2 legacy owner");
+            }
+        }
+        else if (!legalGenerationTransition(previous, entry.state)) {
+            return invalidLeaseError(key, `generation ${entry.generation} is not a legal transition from generation ${previousGeneration}`);
+        }
+        previous = entry.state;
+        previousGeneration = entry.generation;
+    }
+    return undefined;
+}
+function invalidLeaseError(key, message) {
+    return new SharedStateLeaseError("shared-state-lease-invalid", `sharedState generation chain for ${JSON.stringify(key)} is invalid: ${message}. Recovery fails closed.`);
+}
+function readLegacySharedStateLeaseEffect(niceevalRoot, key) {
+    return nodeIo(() => (0, promises_1.readFile)(legacySharedStateLeasePath(niceevalRoot, key), "utf8")).pipe(effect_1.Effect.flatMap((raw) => nodeSync(() => JSON.parse(raw))), effect_1.Effect.flatMap((value) => {
+        const record = decodeSharedStateLeaseRecord(key, value, { legacy: true });
+        return record === undefined
+            ? effect_1.Effect.fail(invalidLeaseError(key, "the legacy mutable record cannot be decoded"))
+            : effect_1.Effect.succeed(record);
+    }), effect_1.Effect.catchAll((cause) => errnoCode(cause) === "ENOENT" ? effect_1.Effect.succeed(undefined) : effect_1.Effect.fail(cause)));
+}
+/**
+ * Read a contiguous immutable generation chain. Proposal files are ignored:
+ * they are not authoritative until the hard-link has occupied a generation
+ * filename. A malformed committed filename or record is an explicit fail
+ * closed condition, never an opportunity to silently start a new holder.
+ */
+function readSharedStateLedgerEffect(niceevalRoot, key) {
+    const dir = sharedStateLeaseGenerationDirOf(niceevalRoot, key);
+    return nodeIo(() => (0, promises_1.readdir)(dir)).pipe(effect_1.Effect.catchAll((cause) => errnoCode(cause) === "ENOENT" ? effect_1.Effect.succeed([]) : effect_1.Effect.fail(cause)), effect_1.Effect.flatMap((names) => {
+        const generationNames = names.filter((name) => name.startsWith(GENERATION_FILE_PREFIX));
+        const ordered = [];
+        for (const name of generationNames) {
+            const generation = generationFromFileName(name);
+            if (generation === undefined) {
+                return effect_1.Effect.fail(invalidLeaseError(key, `committed filename ${JSON.stringify(name)} is not canonical`));
+            }
+            ordered.push({ name, generation });
+        }
+        ordered.sort((left, right) => left.generation - right.generation);
+        if (ordered.length === 0) {
+            return readLegacySharedStateLeaseEffect(niceevalRoot, key).pipe(effect_1.Effect.map((legacy) => Object.freeze({
+                dir,
+                latest: legacy === undefined ? undefined : Object.freeze({ kind: "legacy", record: legacy }),
+            })));
+        }
+        return effect_1.Effect.forEach(ordered, ({ name, generation }) => nodeIo(() => (0, promises_1.readFile)((0, node_path_1.join)(dir, name), "utf8")).pipe(effect_1.Effect.flatMap((raw) => nodeSync(() => JSON.parse(raw))), effect_1.Effect.flatMap((value) => {
+            const decoded = decodeGeneration(key, value);
+            return decoded === undefined
+                ? effect_1.Effect.fail(invalidLeaseError(key, `generation ${generation} cannot be decoded`))
+                : effect_1.Effect.succeed({ generation, state: decoded });
+        }))).pipe(effect_1.Effect.flatMap((entries) => readLegacySharedStateLeaseEffect(niceevalRoot, key).pipe(effect_1.Effect.flatMap((legacy) => {
+            const invalid = validateGenerationTransitions(key, entries, legacy);
+            return invalid === undefined
+                ? effect_1.Effect.succeed(Object.freeze({ dir, latest: entries.at(-1).state }))
+                : effect_1.Effect.fail(invalid);
+        }))));
+    }));
+}
+/**
+ * Publish one immutable generation. `link(proposal, generation-N)` is the
+ * linearization point: it succeeds only if no other transition has occupied
+ * the same next-generation slot. The proposal is unique and non-authoritative
+ * before the link, so a crash cannot leave a reusable fence or an ABA target.
+ */
+function publishGenerationExclusiveEffect(dir, generation, state) {
+    const name = generationFileName(generation);
+    const proposalPath = (0, node_path_1.join)(dir, `.${name}.${process.pid}.${(0, node_crypto_1.randomUUID)()}.proposal`);
+    const targetPath = (0, node_path_1.join)(dir, name);
+    const data = state.kind === "lease"
+        ? durableLeaseGeneration(state.record)
+        : state.kind === "free"
+            ? durableFreeGeneration(state)
+            : undefined;
+    if (data === undefined) {
+        return effect_1.Effect.fail(new SharedStateLeaseError("shared-state-lease-invalid", "A legacy sharedState record cannot be republished without explicit recovery."));
+    }
+    const writeProposal = withOpenFile(proposalPath, "wx", (handle) => nodeIo(() => handle.writeFile(JSON.stringify(data, null, 2), "utf8")).pipe(effect_1.Effect.zipRight(nodeIo(() => handle.sync()))));
+    return nodeIo(() => (0, promises_1.mkdir)(dir, { recursive: true })).pipe(effect_1.Effect.zipRight(writeProposal), effect_1.Effect.zipRight(nodeIo(() => (0, promises_1.link)(proposalPath, targetPath)).pipe(effect_1.Effect.as("published"), effect_1.Effect.catchAll((cause) => errnoCode(cause) === "EEXIST" ? effect_1.Effect.succeed("occupied") : effect_1.Effect.fail(cause)))), effect_1.Effect.flatMap((result) => result === "published"
+        ? (0, entry_file_store_ts_1.fsyncDirEffect)(dir).pipe(effect_1.Effect.as(result))
+        : effect_1.Effect.succeed(result)), 
+    // Only this caller's random proposal is removed. Published generation
+    // files are intentionally never deleted, renamed, or reused.
+    effect_1.Effect.ensuring(nodeIo(() => (0, promises_1.rm)(proposalPath, { force: true })).pipe(effect_1.Effect.ignore)));
+}
+function readSharedStateLeaseEffect(niceevalRoot, key) {
+    return readSharedStateLedgerEffect(niceevalRoot, key).pipe(effect_1.Effect.flatMap((ledger) => {
+        const record = leaseRecordOf(ledger.latest);
+        return record === undefined
+            ? effect_1.Effect.succeed(undefined)
+            // Sidecar I/O is deliberately non-authoritative. A bad/missing read
+            // cannot hide or invalidate the immutable lease generation.
+            : readDiagnosticHeartbeatEffect(ledger.dir, record).pipe(effect_1.Effect.catchAll(() => effect_1.Effect.succeed(record)));
+    }));
+}
+/**
+ * The public recovery command may show the prior owner after a completed
+ * release. This lets it report `AlreadyReleased` without asking users to look
+ * at private files; a new active generation still takes precedence and makes
+ * an old token fail exact-owner validation.
+ */
+function readSharedStateLeaseRecoveryTargetEffect(niceevalRoot, key) {
+    return readSharedStateLedgerEffect(niceevalRoot, key).pipe(effect_1.Effect.flatMap((ledger) => {
+        const record = ledger.latest?.kind === "free" ? ledger.latest.previous : leaseRecordOf(ledger.latest);
+        return record === undefined
+            ? effect_1.Effect.succeed(undefined)
+            : readDiagnosticHeartbeatEffect(ledger.dir, record).pipe(effect_1.Effect.catchAll(() => effect_1.Effect.succeed(record)));
+    }));
+}
+function makeAbortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error)
+        return reason;
+    const error = new Error("aborted while waiting for shared-state recovery");
+    error.name = "AbortError";
+    return error;
+}
+function awaitAbort(signal) {
+    if (signal === undefined)
+        return effect_1.Effect.never;
+    return effect_1.Effect.async((resume, effectSignal) => {
+        let completed = false;
+        const cleanup = () => {
+            signal.removeEventListener("abort", onAbort);
+            effectSignal.removeEventListener("abort", onEffectAbort);
+        };
+        const complete = () => {
+            if (completed)
+                return;
+            completed = true;
+            cleanup();
+        };
+        const onAbort = () => {
+            if (completed)
+                return;
+            complete();
+            resume(effect_1.Effect.fail(makeAbortError(signal)));
+        };
+        const onEffectAbort = () => complete();
+        signal.addEventListener("abort", onAbort, { once: true });
+        effectSignal.addEventListener("abort", onEffectAbort, { once: true });
+        // Both listeners must be live before inspecting either signal: otherwise
+        // an abort between inspection and registration could strand the waiter.
+        if (effectSignal.aborted)
+            onEffectAbort();
+        else if (signal.aborted)
+            onAbort();
+        return effect_1.Effect.sync(complete);
+    });
+}
+function delayOrAbortEffect(ms, signal) {
+    if (signal?.aborted)
+        return effect_1.Effect.fail(makeAbortError(signal));
+    return effect_1.Effect.raceFirst(effect_1.Effect.sleep(ms), awaitAbort(signal)).pipe(effect_1.Effect.asVoid);
+}
+/**
+ * Returns a host-local process identity that distinguishes a PID reuse. Linux
+ * uses the kernel start tick plus `/proc`'s terminal-state boundary; other
+ * POSIX hosts use `ps`'s process start time. An absent or terminal process
+ * returns undefined; unreadable or malformed identity evidence fails closed.
+ */
+function processIdentityForPidEffect(pid) {
+    return effect_1.Effect.tryPromise({
+        try: async () => {
+            if (process.platform === "linux") {
+                try {
+                    const raw = await (0, promises_1.readFile)(`/proc/${pid}/stat`, "utf8");
+                    const closing = raw.lastIndexOf(")");
+                    if (closing < 0 || raw[closing + 1] !== " ") {
+                        throw new Error("Could not parse /proc/<pid>/stat process identity.");
+                    }
+                    const fields = raw.slice(closing + 2).trim().split(/\s+/u);
+                    const state = fields[0];
+                    // field 3 is the task state. A zombie or either Linux dead state
+                    // cannot execute the owner cleanup, even though its start tick still
+                    // matches the durable lease. Treat only these exact terminal states
+                    // as stopped; a missing or malformed state remains unavailable.
+                    if (state === "Z" || state === "X" || state === "x")
+                        return undefined;
+                    if (state === undefined || !/^[A-Za-z]$/u.test(state)) {
+                        throw new Error("Could not parse /proc/<pid>/stat process state.");
+                    }
+                    // /proc/<pid>/stat field 22 is starttime; `fields[0]` is field 3.
+                    const started = fields[19];
+                    if (started !== undefined && /^\d+$/u.test(started))
+                        return `linux-starttime:${started}`;
+                    throw new Error("Could not parse /proc/<pid>/stat process identity.");
+                }
+                catch (cause) {
+                    if (errnoCode(cause) === "ENOENT")
+                        return undefined;
+                    throw cause;
+                }
+            }
+            return await new Promise((resolve, reject) => {
+                (0, node_child_process_1.execFile)("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" }, (error, stdout) => {
+                    if (error !== null) {
+                        if (stdout.trim().length === 0)
+                            resolve(undefined);
+                        else
+                            reject(error);
+                        return;
+                    }
+                    const started = stdout.trim();
+                    resolve(started.length === 0 ? undefined : `ps-lstart:${started}`);
+                });
+            });
+        },
+        catch: (cause) => cause,
+    });
+}
+function currentProcessIdentityEffect() {
+    return processIdentityForPidEffect(process.pid).pipe(effect_1.Effect.flatMap((identity) => identity === undefined
+        ? effect_1.Effect.fail(new SharedStateLeaseError("shared-state-process-identity-unavailable", "NiceEval could not establish this process identity; sharedState fails closed rather than coordinating from a PID alone."))
+        : effect_1.Effect.succeed(identity)));
+}
+function recoveryActor(host, processIdentity) {
+    return Object.freeze({
+        pid: process.pid,
+        host,
+        processIdentity,
+        startedAt: new Date().toISOString(),
+    });
+}
+/**
+ * Heartbeats intentionally make no authority transition. They verify that the
+ * exact immutable generation/token is still current, then atomically replace
+ * only that generation's diagnostic sidecar. A sidecar failure is ignored and
+ * cannot expire, take over, or resurrect any owner.
+ */
+function heartbeatEffect(niceevalRoot, key, expected) {
+    return readSharedStateLedgerEffect(niceevalRoot, key).pipe(effect_1.Effect.flatMap((ledger) => {
+        const current = leaseRecordOf(ledger.latest);
+        if (current === undefined || !sameLeaseRecord(current, expected))
+            return effect_1.Effect.succeed("lost");
+        return effect_1.Clock.currentTimeMillis.pipe(effect_1.Effect.flatMap((nowMs) => writeDiagnosticHeartbeatEffect(ledger.dir, expected, new Date(nowMs).toISOString()).pipe(
+        // This write is merely user-facing evidence. The immutable head is
+        // still authoritative even if the filesystem rejects the sidecar.
+        effect_1.Effect.catchAll(() => effect_1.Effect.void), effect_1.Effect.as("confirmed"))));
+    }));
+}
+function makeActiveLeaseRecord(input) {
+    return Object.freeze({
+        key: input.key,
+        experimentId: input.identity.experimentId,
+        ownerToken: input.ownerToken,
+        pid: input.identity.pid,
+        host: input.identity.host,
+        processIdentity: input.identity.processIdentity,
+        acquiredAt: input.now,
+        heartbeatAt: input.now,
+        status: "active",
+        generation: input.generation,
+        parentGeneration: input.parentGeneration,
+    });
+}
+function freeGenerationFrom(record, generation, releasedAt) {
+    return Object.freeze({
+        kind: "free",
+        key: record.key,
+        generation,
+        parentGeneration: record.generation,
+        releasedAt,
+        previous: record,
+    });
+}
+function releaseError(key, latest) {
+    return new SharedStateLeaseError(latest === undefined ? "shared-state-lease-missing" : "shared-state-lease-owner-mismatch", `sharedState lease ${JSON.stringify(key)} was not released because its exact owner generation no longer matches; explicit recovery is required.`);
+}
+/**
+ * Advance exactly this active generation to a free generation. A competing
+ * transition can only occupy the same next slot; after that happens we inspect
+ * the new immutable head and accept it only if it is this exact release.
+ */
+function releaseExactLeaseEffect(niceevalRoot, key, expected) {
+    return effect_1.Effect.suspend(() => readSharedStateLedgerEffect(niceevalRoot, key).pipe(effect_1.Effect.flatMap((ledger) => {
+        if (ledger.latest?.kind === "free" && sameLeaseRecord(ledger.latest.previous, expected))
+            return effect_1.Effect.void;
+        const current = leaseRecordOf(ledger.latest);
+        if (current === undefined || !sameLeaseRecord(current, expected))
+            return effect_1.Effect.fail(releaseError(key, ledger.latest));
+        const next = freeGenerationFrom(expected, expected.generation + 1, new Date().toISOString());
+        return publishGenerationExclusiveEffect(ledger.dir, next.generation, next).pipe(effect_1.Effect.flatMap((published) => published === "published" ? effect_1.Effect.void : releaseExactLeaseEffect(niceevalRoot, key, expected)));
+    })));
+}
+/**
+ * Acquires only a free/absent generation head. Existing active/recovering
+ * leases are waited on indefinitely; heartbeat age and PID liveness are
+ * diagnostic facts, never authority to take ownership.
+ */
+function acquireSharedStateLeaseEffect(niceevalRoot, key, identity, opts = {}) {
+    const ownerToken = (0, node_crypto_1.randomUUID)();
+    const pollIntervalMs = opts.pollIntervalMs ?? exports.SHARED_STATE_LEASE_HEARTBEAT_INTERVAL_MS;
+    const heartbeatIntervalMs = opts.heartbeatIntervalMs ?? exports.SHARED_STATE_LEASE_HEARTBEAT_INTERVAL_MS;
+    let waitReported = false;
+    const acquire = () => effect_1.Effect.suspend(() => {
+        if (opts.signal?.aborted)
+            return effect_1.Effect.fail(makeAbortError(opts.signal));
+        return readSharedStateLedgerEffect(niceevalRoot, key).pipe(effect_1.Effect.flatMap((ledger) => {
+            const holder = leaseRecordOf(ledger.latest);
+            if (holder !== undefined) {
+                const reportWait = waitReported
+                    ? effect_1.Effect.void
+                    : readDiagnosticHeartbeatEffect(ledger.dir, holder).pipe(effect_1.Effect.flatMap((displayHolder) => effect_1.Effect.sync(() => {
+                        waitReported = true;
+                        opts.onWaitStart?.(displayHolder);
+                    })));
+                return reportWait.pipe(effect_1.Effect.zipRight(delayOrAbortEffect(pollIntervalMs, opts.signal)), effect_1.Effect.zipRight(acquire()));
+            }
+            return effect_1.Clock.currentTimeMillis.pipe(effect_1.Effect.flatMap((nowMs) => {
+                const parentGeneration = generationNumber(ledger.latest);
+                const record = makeActiveLeaseRecord({
+                    key,
+                    identity,
+                    ownerToken,
+                    generation: parentGeneration + 1,
+                    parentGeneration,
+                    now: new Date(nowMs).toISOString(),
+                });
+                const next = Object.freeze({ kind: "lease", record });
+                return publishGenerationExclusiveEffect(ledger.dir, record.generation, next).pipe(effect_1.Effect.flatMap((published) => published === "published" ? effect_1.Effect.succeed(record) : acquire()));
+            }));
+        }));
+    });
+    return effect_1.Effect.uninterruptibleMask((restore) => restore(acquire()).pipe(effect_1.Effect.flatMap((record) => {
+        let heartbeatStopped = false;
+        let lostOwnership = false;
+        const heartbeat = effect_1.Effect.forever(effect_1.Effect.sleep(heartbeatIntervalMs).pipe(effect_1.Effect.zipRight(heartbeatEffect(niceevalRoot, key, record).pipe(effect_1.Effect.tap((outcome) => effect_1.Effect.sync(() => {
+            if (outcome === "lost")
+                lostOwnership = true;
+        })), 
+        // A diagnostic probe failure does not silently abandon an
+        // otherwise-owned lease; release still performs the exact CAS.
+        effect_1.Effect.ignore))));
+        return effect_1.Effect.forkDaemon(restore(heartbeat)).pipe(effect_1.Effect.flatMap((fiber) => effect_1.Deferred.make().pipe(effect_1.Effect.map((releaseCompletion) => {
+            const stopHeartbeat = effect_1.Effect.uninterruptible(effect_1.Effect.suspend(() => {
+                if (heartbeatStopped)
+                    return effect_1.Effect.void;
+                heartbeatStopped = true;
+                return effect_1.Fiber.interrupt(fiber).pipe(effect_1.Effect.asVoid);
+            }));
+            const releaseOperation = stopHeartbeat.pipe(effect_1.Effect.zipRight(releaseExactLeaseEffect(niceevalRoot, key, record)), effect_1.Effect.catchAll((cause) => {
+                // Keep the exact failure visible to the caller. `lostOwnership`
+                // only improves the diagnosis; it never changes authority.
+                if (cause instanceof SharedStateLeaseError)
+                    return effect_1.Effect.fail(cause);
+                return effect_1.Effect.fail(lostOwnership
+                    ? new SharedStateLeaseError("shared-state-lease-owner-mismatch", `sharedState lease ${JSON.stringify(key)} changed while this owner was active; explicit recovery is required.`)
+                    : cause);
+            }));
+            const release = effect_1.Effect.uninterruptible(effect_1.Deferred.complete(releaseCompletion, releaseOperation).pipe(effect_1.Effect.zipRight(effect_1.Deferred.await(releaseCompletion))));
+            return Object.freeze({ claim: Object.freeze({ ownerToken, release, abandon: stopHeartbeat }) });
+        }))));
+    })));
+}
+function assertRecoveryConfirmed(input) {
+    return input.confirmOwnerTerminated && input.confirmRemoteQuiesced
+        ? effect_1.Effect.void
+        : effect_1.Effect.fail(new SharedStateLeaseError("shared-state-recovery-confirmation-required", "Shared-state recovery requires explicit confirmation that the owner terminated and remote state is quiesced."));
+}
+/** A local identity mismatch proves PID reuse; an unreadable identity fails closed. */
+function assertActorStoppedEffect(actor, localHost, code, remoteQuiesced) {
+    if (actor.host !== localHost) {
+        return remoteQuiesced
+            ? effect_1.Effect.void
+            : effect_1.Effect.fail(new SharedStateLeaseError("shared-state-recovery-identity-unavailable", `NiceEval cannot verify remote owner ${actor.host} without an explicit remote-quiesced acknowledgement.`));
+    }
+    return processIdentityForPidEffect(actor.pid).pipe(effect_1.Effect.mapError(() => new SharedStateLeaseError("shared-state-recovery-identity-unavailable", `NiceEval could not verify local process identity for PID ${actor.pid}; recovery fails closed.`)), effect_1.Effect.flatMap((current) => {
+        if (current === undefined || current !== actor.processIdentity)
+            return effect_1.Effect.void;
+        return effect_1.Effect.fail(new SharedStateLeaseError(code, code === "shared-state-owner-still-live"
+            ? `sharedState owner is still live on ${actor.host} as PID ${actor.pid}; recovery is refused.`
+            : `A prior sharedState recovery is still live on ${actor.host} as PID ${actor.pid}; recovery is refused.`));
+    }));
+}
+function recoveryRecordFrom(source, recoveryId, actor) {
+    return Object.freeze({
+        ...source,
+        status: "recovering",
+        generation: source.generation + 1,
+        parentGeneration: source.generation,
+        recoveryId,
+        recoveryActor: actor,
+    });
+}
+function isExactRecoveringSource(record, recoveryId, actor) {
+    return record.status === "recovering" &&
+        record.recoveryId === recoveryId &&
+        record.recoveryActor !== undefined &&
+        // Do not reduce this to processIdentity: PID, host, and the immutable
+        // recovery id are all part of the replacement compare-owner predicate.
+        sameRecoveryActor(record.recoveryActor, actor);
+}
+/**
+ * Claims a failed holder for one recovery command without releasing it. The
+ * recovery record is an immutable next generation. If two operators recover
+ * concurrently, only one can publish that exact next slot; the loser never
+ * clears or reuses a coordination path and must re-inspect/retry explicitly.
+ */
+function beginExplicitSharedStateRecoveryEffect(input) {
+    return effect_1.Effect.gen(function* () {
+        yield* assertRecoveryConfirmed(input);
+        const processIdentity = yield* currentProcessIdentityEffect();
+        const actor = recoveryActor(input.localHost, processIdentity);
+        const ledger = yield* readSharedStateLedgerEffect(input.niceevalRoot, input.key);
+        if (ledger.latest === undefined) {
+            return yield* effect_1.Effect.fail(new SharedStateLeaseError("shared-state-lease-missing", `No decodable sharedState lease exists for ${JSON.stringify(input.key)}.`));
+        }
+        if (ledger.latest.kind === "free") {
+            if (ledger.latest.previous.ownerToken === input.ownerToken) {
+                return Object.freeze({ _tag: "AlreadyReleased", record: ledger.latest.previous });
+            }
+            return yield* effect_1.Effect.fail(new SharedStateLeaseError("shared-state-lease-owner-mismatch", `The supplied owner token does not own sharedState key ${JSON.stringify(input.key)}.`));
+        }
+        const observed = ledger.latest.record;
+        if (observed.ownerToken !== input.ownerToken) {
+            return yield* effect_1.Effect.fail(new SharedStateLeaseError("shared-state-lease-owner-mismatch", `The supplied owner token does not own sharedState key ${JSON.stringify(input.key)}.`));
+        }
+        yield* assertActorStoppedEffect(observed, input.localHost, "shared-state-owner-still-live", input.confirmRemoteQuiesced);
+        if (observed.status === "recovering") {
+            const observedRecoveryId = observed.recoveryId;
+            const observedRecoveryActor = observed.recoveryActor;
+            // The observed immutable parent itself is the exact compare-owner input.
+            // Keep the full predicate explicit so a PID/processIdentity coincidence
+            // cannot replace a different recovery operation.
+            if (!isExactRecoveringSource(observed, observedRecoveryId, observedRecoveryActor)) {
+                return yield* effect_1.Effect.fail(invalidLeaseError(input.key, "recovering generation lacks an exact recovery actor"));
+            }
+            yield* assertActorStoppedEffect(observedRecoveryActor, input.localHost, "shared-state-recovery-in-progress", input.confirmRemoteQuiesced);
+        }
+        const recoveryId = (0, node_crypto_1.randomUUID)();
+        const recovered = recoveryRecordFrom(observed, recoveryId, actor);
+        const next = Object.freeze({ kind: "lease", record: recovered });
+        const published = yield* publishGenerationExclusiveEffect(ledger.dir, recovered.generation, next);
+        if (published === "published")
+            return Object.freeze({ _tag: "Claimed", record: recovered, recoveryId });
+        return yield* effect_1.Effect.fail(new SharedStateLeaseError("shared-state-recovery-state-mismatch", `sharedState lease ${JSON.stringify(input.key)} changed before explicit recovery could claim its exact generation.`));
+    });
+}
+function exactRecoveryActorMatchesCurrentProcess(actor, localHost, processIdentity) {
+    return actor.pid === process.pid && actor.host === localHost && actor.processIdentity === processIdentity;
+}
+/**
+ * Final recovery transition: exactly owner token + recovery id + recovery
+ * actor host/PID/process identity advances its observed generation to free.
+ * It does not unlink anything and therefore cannot erase a later holder.
+ */
+function completeExplicitSharedStateRecoveryEffect(input) {
+    const complete = (expected) => effect_1.Effect.suspend(() => readSharedStateLedgerEffect(input.niceevalRoot, input.key).pipe(effect_1.Effect.flatMap((ledger) => {
+        if (ledger.latest?.kind === "free" && expected !== undefined && sameLeaseRecord(ledger.latest.previous, expected)) {
+            return effect_1.Effect.void;
+        }
+        const current = leaseRecordOf(ledger.latest);
+        if (current === undefined ||
+            (expected !== undefined && !sameLeaseRecord(current, expected)) ||
+            current.ownerToken !== input.ownerToken ||
+            current.status !== "recovering" ||
+            current.recoveryId !== input.recoveryId ||
+            current.recoveryActor === undefined) {
+            return effect_1.Effect.fail(new SharedStateLeaseError(ledger.latest === undefined ? "shared-state-lease-missing" : "shared-state-recovery-state-mismatch", `sharedState lease ${JSON.stringify(input.key)} no longer matches this explicit recovery operation.`));
+        }
+        return currentProcessIdentityEffect().pipe(effect_1.Effect.flatMap((processIdentity) => {
+            if (!exactRecoveryActorMatchesCurrentProcess(current.recoveryActor, input.localHost, processIdentity)) {
+                return effect_1.Effect.fail(new SharedStateLeaseError("shared-state-recovery-state-mismatch", `sharedState lease ${JSON.stringify(input.key)} is not owned by this exact recovery actor.`));
+            }
+            const next = freeGenerationFrom(current, current.generation + 1, new Date().toISOString());
+            return publishGenerationExclusiveEffect(ledger.dir, next.generation, next).pipe(effect_1.Effect.flatMap((published) => published === "published" ? effect_1.Effect.void : complete(current)));
+        }));
+    })));
+    return complete();
+}
+//# sourceMappingURL=shared-state-lease.cjs.map