niceeval 0.12.1 → 0.12.2-canary.31

package/dist/runner/fingerprint.d.ts

@@ -1,189 +1,71 @@
 import { Effect } from "effect";
-import type { DiscoveredEval, EvalResult } from "../types.ts";
-import type { AgentRun, FingerprintMigration } from "./types.ts";
-import { type PreparedRunPair, type SandboxRunPlanningError } from "./sandbox-selection.ts";
-import { type EvalManifest, type FingerprintComparison, type FingerprintDelta } from "./manifest.ts";
-import { type ConfigIdentity } from "./config-identity.ts";
+import type { DiscoveredEval, ResolvedJudgeConfig } from "../types.js";
+import type { ProjectCurrentTarget } from "./project-target.js";
+import { type AgentRun } from "./types.js";
+import { type PreparedRunPair, type SandboxRunPlanningError } from "./sandbox-selection.js";
+import type { EvalManifest } from "./manifest.js";
+import { type ConfigIdentity } from "./config-identity.js";
+declare const FingerprintFileError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FingerprintFileError";
+} & Readonly<A>;
+/** Files that participate in a fingerprint are an explicit planning boundary. */
+export declare class FingerprintFileError extends FingerprintFileError_base<{
+    readonly operation: "read" | "hash";
+    readonly path: string;
+    readonly message: string;
+}> {
+}
+declare const FingerprintPlanningError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FingerprintPlanningError";
+} & Readonly<A>;
+/** A malformed or internally inconsistent planning input must not become a defect. */
+export declare class FingerprintPlanningError extends FingerprintPlanningError_base<{
+    readonly stage: "configuration" | "invariant";
+    readonly message: string;
+}> {
+}
+export type FingerprintPlanningFailure = FingerprintFileError | FingerprintPlanningError;
+export type FingerprintSourceCache = Map<string, Effect.Effect<string, FingerprintFileError>>;
+export declare function createFingerprintSourceCache(): FingerprintSourceCache;
 export declare function cacheKey(run: AgentRun, evalId: string): string;
 /** Run 级配置身份。所有会改变结果解释口径的实验配置只在 `configIdentityForRun` 里裁决一次。 */
 export declare function computeConfigHash(pair: PreparedRunPair): string;
-/** 身份对象 → 配置身份哈希;反事实重算(`--accept`)与正常路径共用同一个序列化口径。 */
+/** 身份对象 → 配置身份哈希。 */
 export declare function hashConfigIdentity(identity: ConfigIdentity): string;
-/**
- * @param projection 正常重算是 `Current`；`--accept` 按换回历史值的身份重算时显式传
- * `Counterfactual`。两条路径不能拼一袋互相矛盾的 optional override。
- */
-export declare function computeFingerprint(pair: PreparedRunPair, sourceCache?: Map<string, Promise<string>>, projection?: FingerprintProjection): Promise<string>;
-export type FingerprintProjection = {
+/** The only supported projection is the immutable current configuration identity. */
+export declare function computeFingerprint(pair: PreparedRunPair, sourceCache?: FingerprintSourceCache, projection?: FingerprintProjection): Effect.Effect<string, FingerprintPlanningFailure>;
+export interface FingerprintProjection {
     readonly _tag: "Current";
     readonly identity: ConfigIdentity;
-} | {
-    readonly _tag: "Counterfactual";
-    readonly identity: ConfigIdentity;
-};
+}
 /**
  * 指纹与它的可读清单一次算出。两者**同一份输入**:清单不是事后再扫一遍磁盘拼出来的近似,
  * 而是哈希那一刻手里的原料换一种投影(内容换成内容哈希)。分开算迟早分叉,症状是
  * 「`--dry` 说这个文件变了,指纹却相等」。
  *
- * @param projection 语义见 `computeFingerprint`；反事实路径只要指纹，清单照常一并算出，
- * 但调用方通常丢弃。
+ * @param projection The immutable current configuration identity.
  */
-export declare function fingerprintWithManifest(pair: PreparedRunPair, sourceCache?: Map<string, Promise<string>>, projection?: FingerprintProjection): Promise<{
+export declare function fingerprintWithManifest(pair: PreparedRunPair, sourceCache?: FingerprintSourceCache, projection?: FingerprintProjection): Effect.Effect<{
     fingerprint: string;
     manifest: EvalManifest;
-}>;
-/**
- * 携带的五道门(docs/feature/experiments/cache.md「携带要过的门」)加上「无历史」。
- * `--dry --json` 的 `ExpPlanDispatch.gate` 用这套词。
- */
-export type CarryGate = "terminal" | "fingerprint" | "eligibility" | "rerun" | "mode" | "missing";
-/**
- * 同一道门的人读词(`--dry` 计划行尾);模式门按两个来源分成两个词,缺历史门按「真没有」与
- * 「有但格式读不动」分成两个词——后者是 `incompatible`,把「上一版写的结果还躺在盘上」
- * 与「这条 eval 从没跑过」区分开(判定见 `CarryGateOptions.incompatibleKeys`)。
- */
-export type DispatchReason = "errored" | "stale" | "exceeds-timeout" | "rerun" | "keep-sandbox" | "incompatible" | "new";
-/** 一条 (experiment, eval) 行里,卡在同一道门上的那些 attempt 序号。 */
-export interface DispatchGroup {
-    readonly gate: CarryGate;
-    readonly reason: DispatchReason;
-    /** 这组原因覆盖的 attempt 序号(0-based,升序)。 */
-    readonly attempts: readonly number[];
-    /** 指纹门的比较解释；不等时只能是非空 changed 或带闭集原因的 unexplained。 */
-    readonly comparison?: FingerprintComparison;
-}
-export interface CarryPlan {
-    /** discovery/selector/link/physical planning 的唯一完成态；run/attempt 不再二次选择或重建。 */
+}, FingerprintPlanningFailure>;
+/** 无派发项目规划：身份目标与 runner 后续真正消费的 prepared pair 来自同一产物。 */
+export interface ProjectTargetPlan {
+    readonly target: ProjectCurrentTarget;
     readonly preparedPairsByKey: ReadonlyMap<string, PreparedRunPair>;
-    /** `cacheKey(run, evalId)` → Run 级配置身份。 */
     readonly plannedConfigHashes: ReadonlyMap<string, string>;
-    /** `cacheKey(run, evalId)` → 本次规划出的指纹,供调用方按同一口径判断"这条要不要携入"。 */
+    readonly resolvedJudgesByKey: ReadonlyMap<string, ResolvedJudgeConfig | undefined>;
     readonly plannedFingerprints: ReadonlyMap<string, string>;
-    /**
-     * `cacheKey(run, evalId)` → 这条组合**可以携带的全部指纹**:本次规划的那个,加上
-     * 「只在 provenance flag 上与本次不同」的历史口径(见 `acceptableFingerprints`)。
-     * 没声明 provenance flag 时恒是单元素集合 = `plannedFingerprints` 的那一个。
-     * 携带判定一律读这个集合,`plannedFingerprints` 只用来给新跑的 attempt 落盘打戳。
-     */
-    readonly acceptableFingerprints: ReadonlyMap<string, ReadonlySet<string>>;
-    /**
-     * 携带以 attempt 为粒度:命中携入条件(该 attempt 自身 passed/failed 终态 + 指纹匹配)的
-     * `${experimentId}|${evalId}` → 该 eval 下具体携入的 attempt 序号集合(0-based)。同一个
-     * eval 在 `runs > 1` 时可能只有部分序号是终态、其余是 errored/未跑完——只有逐条命中的那些
-     * 序号才在这个集合里,不是"key 命中就整段携入"(反例与修法见 memory 的
-     * carry-includes-failed-verdict)。
-     */
-    readonly carriedAttemptsByKey: ReadonlyMap<string, ReadonlySet<number>>;
-    /** carriedAttemptsByKey 对应的完整结果对象,供 run.ts 直接并入 summary、cli.ts 直接取 verdict 展示。 */
-    readonly carriedResults: readonly EvalResult[];
-    /** 仅 `--accept` 授权放行的历史条目 → 它跨过的那几条差异(留痕落到条目的 `carriedAccepting`)。 */
-    readonly carriedAcceptingByResult: ReadonlyMap<EvalResult, readonly FingerprintDelta[]>;
-    /** 已知旧 opaque carryEpoch → 当前确定性指纹的自动迁移来源。 */
-    readonly migratedFromByResult: ReadonlyMap<EvalResult, FingerprintMigration>;
-    /**
-     * `cacheKey(run, evalId)` → 本行要派发的 attempt 按未携带原因分组(升序、同一门聚一组)。
-     * 全部携带的行不出现在表里。`--dry` 的逐条作废原因读它。
-     */
-    readonly dispatchByKey: ReadonlyMap<string, readonly DispatchGroup[]>;
-    /**
-     * `cacheKey(run, evalId)` → 本次算出的指纹输入清单,与指纹同刻、同一份输入
-     * (见 `fingerprintWithManifest`)。Run 记录根下的 `manifests.json` 落的就是它,
-     * 下一轮的差异解释靠它。
-     */
     readonly manifestsByKey: ReadonlyMap<string, EvalManifest>;
-    /**
-     * 本次计划里**真实存在**的可授权差异(按 selector 去重)。`--accept` 的空转校验读它:
-     * 两侧都没有的 selector 多半是打错了,按启动期用法错误报出并列出这张表。
-     * 它与 `--accept` 是否给出无关——授权成功的差异照样在表里,否则「授权一次之后同一条命令
-     * 再跑就说这个 selector 空转」。
-     */
-    readonly availableDeltas: readonly FingerprintDelta[];
+    /** 仅供本地 watcher；不会序列化进 Target/report。 */
+    readonly watchInputs: readonly string[];
 }
-export type CarryGateDecision = {
-    readonly _tag: "Eligible";
-} | {
-    readonly _tag: "Blocked";
-    readonly gate: CarryGate;
-    readonly reason: DispatchReason;
-};
-/**
- * 与 `attempt.ts` 里实际生效超时的解析顺序保持一致(`run.timeoutMs ?? evalDef.timeoutMs ??
- * configTimeoutMs`),但刻意不叠加 attempt.ts 的硬编码兜底(10 分钟):携带判据要问的是「用户
- * 有没有显式配置一条线」,三层都未设时线本身不存在,`Infinity` 让 durationMs 判据恒成立
- * (「当前未设上限 = 恒可携带」,见 docs/runner.md「缓存:指纹去重」)。10 分钟兜底是
- * attempt.ts 的执行期默认值,不是携带判据要遵守的线。
- */
-export declare function resolvedTimeoutMsForCarry(run: AgentRun, evalDef: DiscoveredEval, configTimeoutMs?: number): number;
 /**
- * 携带资格判据的**唯一**实现:从 `priorResults` 里挑出 `key` 这条 `(experimentId, evalId)`
- * 可以携入(跳过重跑)的 attempt。三条判据逐条 attempt 独立成立才算命中——
- *
- * 1. 该 attempt 自己是终态(`passed` / `failed`)。`errored` 是框架/环境层面的不确定失败,
- *    判定本身不可信;`skipped` 根本没跑。同一 eval 的别的序号命中不能连带把它捎上
- *    (反例与修法见 memory 的 carry-must-be-per-attempt-not-whole-eval-key)。
- * 2. 该 attempt 落盘的 `fingerprint` 落在本次的可携带指纹集合里(`CarryPlan.acceptableFingerprints`
- *    的那一条,通常只有本次规划出的那一个;声明了 provenance flag 时还含「只在这些键上与本次
- *    不同」的历史口径)。
- * 3. 该 attempt 的 `durationMs` 不超过本次 resolved 的 `timeoutMs`——`timeoutMs` 是携带资格
- *    判据、不进指纹哈希(docs/runner.md「缓存:指纹去重」)。
- *
- * `planCarry`(整场静态规划)与 run.ts 派发时刻的携带重查共用这一个函数:两条路径一旦把判据
- * 各写一份就会分叉,重查会携入静态规划判过不可携带的条目(或反过来)。
- */
-export interface CarryGateOptions {
-    rerun?: "failed" | "all";
-    keepSandbox?: "failed" | "all";
-    /** 本次授权的差异 selector(`--accept`);只放松指纹门,其余四道门不受影响。 */
-    accept?: readonly string[];
-    /**
-     * 有历史、但那份落盘的 `schemaVersion` 与本读取器不同的 `cacheKey`(见
-     * `loadCarryInputs` 的 `incompatibleHistory`)。这些条目读不进 `priorResults`,不标出来
-     * 就会跟从没跑过的坐标一样落在 `new` 上——那是句事实错误的话。
-     */
-    incompatibleKeys?: ReadonlySet<string>;
-}
-export interface CarryPlanOptions {
-    rerun?: "failed" | "all";
-    keepSandbox?: "failed" | "all";
-    accept?: readonly string[];
-    /** 历史侧的指纹输入清单；缺席时差异保守落为 opaque。 */
-    priorManifests?: ReadonlyMap<string, EvalManifest>;
-    /** 有历史但格式不兼容的 cache key。 */
-    incompatibleKeys?: ReadonlySet<string>;
-    /** 项目级 Judge 默认；与 Experiment / Eval 逐字段解析。 */
-    configJudge?: import("../types.ts").JudgeConfig;
-}
-/**
- * 一条历史 attempt 的携带判定。成功返回 `Eligible`，失败返回带 gate/reason 的 `Blocked`。
- * 这是判据的唯一实现——
- * `carriableAttempts`(能不能携带)与 `--dry` 的逐条作废原因(为什么没携带)都读它,
- * 两条路径因此不可能给出不一致的结论:「这条会重跑」与「它是被这道门拦下的」永远同源。
- * 门的顺序就是 docs 那张表的行序,一条 attempt 同时卡在多道门上时报最先那道。
- */
-export declare function carryGateFor(r: EvalResult, configHash: string | undefined, fingerprints: ReadonlySet<string> | undefined, timeoutMs: number, options?: CarryGateOptions): CarryGateDecision;
-/**
- * 计划内某个序号**根本没有历史条目**时报哪个词:盘上真没有是 `new`,有但那份落盘的
- * `schemaVersion` 读不动是 `incompatible`。两者都是缺历史门(`missing`),`--dry --json` 的
- * gate 词不因此增加成员——分的是给人看的原因,不是新的一道门。
- */
-export declare function missingReason(key: string, options: CarryGateOptions): Extract<CarryGateDecision, {
-    readonly _tag: "Blocked";
-}>;
-export declare function carriableAttempts(priorResults: EvalResult[] | undefined, key: string, configHash: string | undefined, fingerprints: ReadonlySet<string> | undefined, timeoutMs: number, options?: CarryGateOptions): EvalResult[];
-/**
- * 算出这一批 (agentRun × eval) 的指纹,并据此从 priorResults 里筛出可以携入(跳过重跑)的结果。
- * run.ts 与 cli.ts(live 表格构建)必须共用这同一份计算 —— 否则两边一旦对"哪些携入"的判断
- * 不一致,live 表格就会显示"还在等名额",而 run.ts 其实已经把它筛掉、根本不会调度这个 attempt
- * (见 memory 的 live-carry-row-shows-waiting-forever)。
- *
- * 携带来源不要求快照收尾:`priorResults` 来自 `loadLatestResultsPerEval`,它按落盘的
- * `result.json` 一条条读,不检查所属快照有没有 `completedAt`——被中断或强杀的 run 留下的
- * 未收尾快照,其中已落盘的终态 attempt 同样进入这里的候选集合(见 docs/runner.md
- * 「缓存:指纹去重」)。
- *
- * @param configTimeoutMs 项目级 `Config.timeoutMs`(携带资格判据的最后一层兜底,见
- * `resolvedTimeoutMsForCarry`)。省略时按未配置处理,不是当作 0——只有 `run.timeoutMs` /
- * `evalDef.timeoutMs` 都缺席时才轮到它兜底。
+ * 只做 discovery 之后的 link + physical identity planning 与 fingerprint；不读 Record，
+ * 不调用 setup/create/build/Agent Ensure，也不决定 reuse/派发。
  */
-export declare function planCarry(evals: readonly DiscoveredEval[], agentRuns: readonly AgentRun[], priorResults: EvalResult[] | undefined, configTimeoutMs?: number, options?: CarryPlanOptions): Effect.Effect<CarryPlan, SandboxRunPlanningError>;
+export declare function planProjectTarget(evals: readonly DiscoveredEval[], agentRuns: readonly AgentRun[], configTimeoutMs?: number, options?: {
+    readonly configJudge?: import("../types.js").JudgeConfig;
+    readonly keepSandbox?: "failed" | "all";
+}): Effect.Effect<ProjectTargetPlan, SandboxRunPlanningError | FingerprintPlanningFailure>;
+export {};

package/dist/runner/fingerprint.js

@@ -0,0 +1,22 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./fingerprint.cjs");
+const __niceevalExport0 = __niceevalCanonical["FingerprintFileError"];
+export { __niceevalExport0 as FingerprintFileError };
+const __niceevalExport1 = __niceevalCanonical["FingerprintPlanningError"];
+export { __niceevalExport1 as FingerprintPlanningError };
+const __niceevalExport2 = __niceevalCanonical["cacheKey"];
+export { __niceevalExport2 as cacheKey };
+const __niceevalExport3 = __niceevalCanonical["computeConfigHash"];
+export { __niceevalExport3 as computeConfigHash };
+const __niceevalExport4 = __niceevalCanonical["computeFingerprint"];
+export { __niceevalExport4 as computeFingerprint };
+const __niceevalExport5 = __niceevalCanonical["createFingerprintSourceCache"];
+export { __niceevalExport5 as createFingerprintSourceCache };
+const __niceevalExport6 = __niceevalCanonical["fingerprintWithManifest"];
+export { __niceevalExport6 as fingerprintWithManifest };
+const __niceevalExport7 = __niceevalCanonical["hashConfigIdentity"];
+export { __niceevalExport7 as hashConfigIdentity };
+const __niceevalExport8 = __niceevalCanonical["planProjectTarget"];
+export { __niceevalExport8 as planProjectTarget };
+//# sourceMappingURL=fingerprint.js.map

package/dist/runner/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sources":[],"names":[],"mappings":""}

package/dist/runner/gate-lease.cjs

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATE_LEASE_EXPIRY_MS = exports.GATE_LEASE_HEARTBEAT_INTERVAL_MS = void 0;
+exports.gateLeasesDirOf = gateLeasesDirOf;
+exports.readGateLeasesEffect = readGateLeasesEffect;
+exports.isGateLeaseExpired = isGateLeaseExpired;
+exports.tryAcquireGateSlotOnceEffect = tryAcquireGateSlotOnceEffect;
+exports.acquireGateSlotEffect = acquireGateSlotEffect;
+exports.drainHeldGateLeasesEffect = drainHeldGateLeasesEffect;
+exports.pendingHeldGateLeaseCount = pendingHeldGateLeaseCount;
+// 实验闸租约:把实验级 `maxConcurrency` 的 N 个名额做成跨 Invocation 共用的逐槽租约。
+// 与 ./lock.ts 的用例锁同一套文件纪律(O_EXCL 独占创建、心跳续租、过期判据、rename 接管、
+// 释放即删除),建在 ../shared/entry-file-store.ts 的原语之上,不复制第三份纪律。
+// 契约见 docs/feature/experiments/architecture.md「并发 Invocation:用例锁」末条与
+// docs/runner.md#调度有界并发。
+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 lock_ts_1 = require("./lock.cjs");
+function recordOf(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isSlot(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function errnoCode(cause) {
+    return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string"
+        ? cause.code
+        : undefined;
+}
+function nodeIo(operation) {
+    return effect_1.Effect.tryPromise({ 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 decodeGateLeaseRecord(value, expected = {}) {
+    const record = recordOf(value);
+    if (record === undefined ||
+        typeof record.experimentId !== "string" ||
+        !isSlot(record.slot) ||
+        !isPositiveInteger(record.declaredN) ||
+        !isPositiveInteger(record.pid) ||
+        typeof record.host !== "string" ||
+        !isTimestamp(record.startedAt) ||
+        !isTimestamp(record.heartbeatAt) ||
+        (expected.experimentId !== undefined && record.experimentId !== expected.experimentId) ||
+        (expected.slot !== undefined && record.slot !== expected.slot)) {
+        return undefined;
+    }
+    return {
+        experimentId: record.experimentId,
+        slot: record.slot,
+        declaredN: record.declaredN,
+        pid: record.pid,
+        host: record.host,
+        startedAt: record.startedAt,
+        heartbeatAt: record.heartbeatAt,
+    };
+}
+/** 持有者续租心跳的周期。与用例锁同参数。 */
+exports.GATE_LEASE_HEARTBEAT_INTERVAL_MS = lock_ts_1.CASE_LOCK_HEARTBEAT_INTERVAL_MS;
+/** `heartbeatAt` 落后当前时间超过这个阈值(三个心跳周期)即视为持有者已死。 */
+exports.GATE_LEASE_EXPIRY_MS = lock_ts_1.CASE_LOCK_EXPIRY_MS;
+function gateLeasesDirOf(niceevalRoot) {
+    return (0, lock_ts_1.locksDirOf)(niceevalRoot);
+}
+function gateLeaseEntryId(experimentId, slot) {
+    return (0, entry_file_store_ts_1.slugHashEntryId)(`gate-${experimentId}-${slot}`, ["gate-lease", experimentId, String(slot)]);
+}
+/** Effect 主 API:读取该实验当前在场的全部租约记录,无副作用。 */
+function readGateLeasesEffect(niceevalRoot, experimentId) {
+    return (0, entry_file_store_ts_1.readAllEntryFilesEffect)(gateLeasesDirOf(niceevalRoot), decodeGateLeaseRecord).pipe(effect_1.Effect.map((entries) => entries
+        .map(({ entry }) => entry)
+        .filter((entry) => entry.experimentId === experimentId)
+        .sort((a, b) => a.slot - b.slot)));
+}
+/** 过期判据:只看心跳时间戳,不看 pid。 */
+function isGateLeaseExpired(record, nowMs) {
+    const heartbeatMs = Date.parse(record.heartbeatAt);
+    if (Number.isNaN(heartbeatMs))
+        return true;
+    return nowMs - heartbeatMs > exports.GATE_LEASE_EXPIRY_MS;
+}
+/** 本进程声明的 N:非法值收敛到 1，避免永久满位。 */
+function normalizeN(n) {
+    const floored = Math.floor(n);
+    return Number.isFinite(floored) && floored >= 1 ? floored : 1;
+}
+/** min-N:有效名额取自己声明和所有新鲜租约声明的最小值。 */
+function effectiveSlotCount(maxConcurrency, leases, nowMs) {
+    let n = normalizeN(maxConcurrency);
+    for (const lease of leases) {
+        if (isGateLeaseExpired(lease, nowMs))
+            continue;
+        const declared = normalizeN(lease.declaredN);
+        if (declared < n)
+            n = declared;
+    }
+    return n;
+}
+/** O_EXCL 独占创建租约文件;存在时返回 false,不覆盖。 */
+function createLeaseFileExclusiveEffect(dir, id, record) {
+    const path = (0, node_path_1.join)(dir, `${id}.json`);
+    return nodeIo(() => (0, promises_1.mkdir)(dir, { recursive: true })).pipe(effect_1.Effect.zipRight(withOpenFile(path, "wx", (handle) => nodeIo(() => handle.writeFile(JSON.stringify(record, null, 2), "utf-8")).pipe(effect_1.Effect.zipRight(nodeIo(() => handle.sync()))))), effect_1.Effect.zipRight((0, entry_file_store_ts_1.fsyncDirEffect)(dir)), effect_1.Effect.as(true), effect_1.Effect.catchAll((cause) => errnoCode(cause) === "EEXIST" ? effect_1.Effect.succeed(false) : effect_1.Effect.fail(cause)));
+}
+/** 同一持有者判定:身份(pid/host)加上取位时刻——接管重建后 `startedAt` 必然不同。 */
+function isSameHolder(record, mine) {
+    return record.pid === mine.pid && record.host === mine.host && record.startedAt === mine.startedAt;
+}
+/** 一次非阻塞取位:空槽 O_EXCL 创建，满位时只接管过期或损坏槽。 */
+function tryAcquireGateSlotOnceEffect(niceevalRoot, experimentId, maxConcurrency, identity, nowMs) {
+    const dir = gateLeasesDirOf(niceevalRoot);
+    return effect_1.Effect.gen(function* () {
+        const effectiveN = effectiveSlotCount(maxConcurrency, yield* readGateLeasesEffect(niceevalRoot, experimentId), nowMs);
+        const stamp = new Date(nowMs).toISOString();
+        const recordFor = (slot) => ({
+            experimentId,
+            slot,
+            declaredN: normalizeN(maxConcurrency),
+            pid: identity.pid,
+            host: identity.host,
+            startedAt: stamp,
+            heartbeatAt: stamp,
+        });
+        const acquired = (slot, record, options) => ({ kind: "acquired", slot, record, ...options });
+        // 第一趟不预读占用情况：O_EXCL 本身就是判据。
+        for (let slot = 0; slot < effectiveN; slot += 1) {
+            const record = recordFor(slot);
+            if (yield* createLeaseFileExclusiveEffect(dir, gateLeaseEntryId(experimentId, slot), record)) {
+                return acquired(slot, record, { takenOver: false });
+            }
+        }
+        // 第二趟只对坏条目或过期条目执行 rename 认领；输掉竞态后继续下一槽。
+        for (let slot = 0; slot < effectiveN; slot += 1) {
+            const id = gateLeaseEntryId(experimentId, slot);
+            const current = yield* (0, entry_file_store_ts_1.readEntryFileEffect)(dir, id, (value) => decodeGateLeaseRecord(value, { experimentId, slot }));
+            if (current === undefined) {
+                if (!(yield* (0, entry_file_store_ts_1.claimEntryFileEffect)(dir, id)))
+                    continue;
+                const record = recordFor(slot);
+                if (!(yield* createLeaseFileExclusiveEffect(dir, id, record)))
+                    continue;
+                return acquired(slot, record, { takenOver: false });
+            }
+            if (!isGateLeaseExpired(current, nowMs))
+                continue;
+            if (!(yield* (0, entry_file_store_ts_1.claimEntryFileEffect)(dir, id)))
+                continue;
+            const record = recordFor(slot);
+            if (!(yield* createLeaseFileExclusiveEffect(dir, id, record)))
+                continue;
+            return acquired(slot, record, { takenOver: true, takenOverFrom: current });
+        }
+        const holders = (yield* readGateLeasesEffect(niceevalRoot, experimentId)).filter((lease) => !isGateLeaseExpired(lease, nowMs));
+        return { kind: "full", holders };
+    });
+}
+/** 续租只改 heartbeat；槽被接管后不写、不删别人的租约。 */
+function renewHeartbeatEffect(dir, id, mine, nowMs, isReleased) {
+    if (isReleased())
+        return effect_1.Effect.void;
+    return (0, entry_file_store_ts_1.readEntryFileEffect)(dir, id, (value) => decodeGateLeaseRecord(value, { experimentId: mine.experimentId, slot: mine.slot })).pipe(effect_1.Effect.flatMap((current) => {
+        if (current === undefined || !isSameHolder(current, mine) || isReleased())
+            return effect_1.Effect.void;
+        return (0, entry_file_store_ts_1.writeEntryFileEffect)(dir, id, { ...current, heartbeatAt: new Date(nowMs).toISOString() });
+    }));
+}
+function makeAbortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error)
+        return reason;
+    const err = new Error("aborted while waiting for experiment gate slot");
+    err.name = "AbortError";
+    return err;
+}
+function awaitAbort(signal) {
+    return effect_1.Effect.async((resume, effectSignal) => {
+        if (signal === undefined)
+            return;
+        const cleanup = () => {
+            signal.removeEventListener("abort", onAbort);
+            effectSignal.removeEventListener("abort", cleanup);
+        };
+        const onAbort = () => {
+            cleanup();
+            resume(effect_1.Effect.fail(makeAbortError(signal)));
+        };
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        effectSignal.addEventListener("abort", cleanup, { once: true });
+    });
+}
+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);
+}
+const held = new Map();
+function heldKey(niceevalRoot, id) {
+    return `${niceevalRoot} ${id}`;
+}
+/** 高层 Effect 入口:等待可中断；心跳顺序化，release 等正在飞的不可中断续租结束再删除。 */
+function acquireGateSlotEffect(niceevalRoot, experimentId, maxConcurrency, identity, opts = {}) {
+    const heartbeatIntervalMs = opts.heartbeatIntervalMs ?? exports.GATE_LEASE_HEARTBEAT_INTERVAL_MS;
+    const pollIntervalMs = opts.pollIntervalMs ?? heartbeatIntervalMs;
+    let waitStarted = false;
+    const acquireLoop = () => effect_1.Effect.suspend(() => {
+        if (opts.signal?.aborted)
+            return effect_1.Effect.fail(makeAbortError(opts.signal));
+        return tryAcquireGateSlotOnceEffect(niceevalRoot, experimentId, maxConcurrency, identity, Date.now()).pipe(effect_1.Effect.flatMap((result) => {
+            if (result.kind === "acquired")
+                return effect_1.Effect.succeed(result);
+            const reportWait = waitStarted
+                ? effect_1.Effect.void
+                : effect_1.Effect.sync(() => {
+                    waitStarted = true;
+                    opts.onWaitStart?.(result.holders);
+                });
+            return reportWait.pipe(effect_1.Effect.zipRight(delayOrAbortEffect(pollIntervalMs, opts.signal)), effect_1.Effect.zipRight(acquireLoop()));
+        }));
+    });
+    return effect_1.Effect.uninterruptibleMask((restore) => restore(acquireLoop()).pipe(effect_1.Effect.flatMap(({ slot, takenOver, takenOverFrom, record }) => {
+        const dir = gateLeasesDirOf(niceevalRoot);
+        const id = gateLeaseEntryId(experimentId, slot);
+        const key = heldKey(niceevalRoot, id);
+        let released = false;
+        const heartbeat = effect_1.Effect.forever(effect_1.Effect.sleep(heartbeatIntervalMs).pipe(effect_1.Effect.zipRight(effect_1.Effect.suspend(() => effect_1.Effect.uninterruptible(renewHeartbeatEffect(dir, id, record, Date.now(), () => released)))
+            .pipe(effect_1.Effect.ignore))));
+        // A child inherits the parent's interruptibility. This branch still
+        // runs under the acquisition mask, so restore the heartbeat before
+        // forking; otherwise release would wait forever while interrupting an
+        // uninterruptible sleeping fiber.
+        return effect_1.Effect.forkDaemon(restore(heartbeat)).pipe(effect_1.Effect.map((fiber) => {
+            const release = effect_1.Effect.uninterruptible(effect_1.Effect.suspend(() => {
+                if (released)
+                    return effect_1.Effect.void;
+                released = true;
+                held.delete(key);
+                return effect_1.Fiber.interrupt(fiber).pipe(effect_1.Effect.zipRight((0, entry_file_store_ts_1.readEntryFileEffect)(dir, id, (value) => decodeGateLeaseRecord(value, { experimentId, slot }))), effect_1.Effect.flatMap((current) => current !== undefined && !isSameHolder(current, record)
+                    ? effect_1.Effect.void
+                    : nodeIo(() => (0, promises_1.rm)((0, node_path_1.join)(dir, `${id}.json`), { force: true })).pipe(effect_1.Effect.zipRight((0, entry_file_store_ts_1.fsyncDirEffect)(dir)))));
+            }));
+            held.set(key, release);
+            return { claim: { slot, release }, takenOver, ...(takenOverFrom === undefined ? {} : { takenOverFrom }) };
+        }));
+    })));
+}
+/** 强清兜底:尽力释放当前进程持有的每一条租约。 */
+function drainHeldGateLeasesEffect() {
+    const releases = [...held.values()];
+    return effect_1.Effect.forEach(releases, (release) => effect_1.Effect.exit(release), { discard: true }).pipe(effect_1.Effect.as(releases.length));
+}
+/** 当前进程仍持有的实验闸租约数量，供退出清理与可观察状态汇总。 */
+function pendingHeldGateLeaseCount() {
+    return held.size;
+}
+//# sourceMappingURL=gate-lease.cjs.map

package/dist/runner/gate-lease.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-lease.js","sourceRoot":"","sources":["gate-lease.ts"],"names":[],"mappings":"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","sourcesContent":["// 实验闸租约:把实验级 `maxConcurrency` 的 N 个名额做成跨 Invocation 共用的逐槽租约。\n// 与 ./lock.ts 的用例锁同一套文件纪律(O_EXCL 独占创建、心跳续租、过期判据、rename 接管、\n// 释放即删除),建在 ../shared/entry-file-store.ts 的原语之上,不复制第三份纪律。\n// 契约见 docs/feature/experiments/architecture.md「并发 Invocation:用例锁」末条与\n// docs/runner.md#调度有界并发。\nimport { mkdir, open, rm, type FileHandle } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { Effect, Fiber } from \"effect\";\nimport { claimEntryFileEffect, fsyncDirEffect, readAllEntryFilesEffect, readEntryFileEffect, slugHashEntryId, writeEntryFileEffect, } from \"../shared/entry-file-store.ts\";\nimport { CASE_LOCK_EXPIRY_MS, CASE_LOCK_HEARTBEAT_INTERVAL_MS, locksDirOf } from \"./lock.ts\";\n/** 逐槽租约文件的 JSON 形状。身份的权威在内容,文件名只须无碰撞、不承载解析。 */\nexport interface GateLeaseRecord {\n    experimentId: string;\n    /** 槽位序号,取值 0..N-1。 */\n    slot: number;\n    /** 本持有者 resolved 的名额上限 N。用于 min-N:生效名额取在场声明的最小值。 */\n    declaredN: number;\n    pid: number;\n    host: string;\n    startedAt: string; // ISO\n    heartbeatAt: string; // ISO\n}\ntype GateSlotAcquired = {\n    kind: \"acquired\";\n    slot: number;\n    takenOver: boolean;\n    takenOverFrom?: GateLeaseRecord;\n    record: GateLeaseRecord;\n};\ntype GateSlotAttempt = GateSlotAcquired | {\n    kind: \"full\";\n    holders: GateLeaseRecord[];\n};\nfunction recordOf(value: unknown): globalThis.Record<string, unknown> | undefined {\n    return typeof value === \"object\" && value !== null && !Array.isArray(value)\n        ? value as globalThis.Record<string, unknown>\n        : undefined;\n}\nfunction isPositiveInteger(value: unknown): value is number {\n    return typeof value === \"number\" && Number.isSafeInteger(value) && value > 0;\n}\nfunction isSlot(value: unknown): value is number {\n    return typeof value === \"number\" && Number.isSafeInteger(value) && value >= 0;\n}\nfunction isTimestamp(value: unknown): value is string {\n    return typeof value === \"string\" && Number.isFinite(Date.parse(value));\n}\nfunction errnoCode(cause: unknown): string | undefined {\n    return typeof cause === \"object\" && cause !== null && \"code\" in cause && typeof cause.code === \"string\"\n        ? cause.code\n        : undefined;\n}\nfunction nodeIo<A>(operation: (signal: AbortSignal) => Promise<A>): Effect.Effect<A, unknown> {\n    return Effect.tryPromise({ try: operation, catch: (cause) => cause });\n}\nfunction withOpenFile<A>(path: string, flags: string, use: (handle: FileHandle) => Effect.Effect<A, unknown>): Effect.Effect<A, unknown> {\n    return Effect.scoped(Effect.acquireRelease(nodeIo(() => open(path, flags)), (handle) => nodeIo(() => handle.close()).pipe(Effect.orDie)).pipe(Effect.flatMap(use)));\n}\n/** 验证租约的全部持久字段；按槽读取时还会核对身份，防止错位记录冒充当前持有者。 */\nfunction decodeGateLeaseRecord(value: unknown, expected: {\n    experimentId?: string;\n    slot?: number;\n} = {}): GateLeaseRecord | undefined {\n    const record = recordOf(value);\n    if (record === undefined ||\n        typeof record.experimentId !== \"string\" ||\n        !isSlot(record.slot) ||\n        !isPositiveInteger(record.declaredN) ||\n        !isPositiveInteger(record.pid) ||\n        typeof record.host !== \"string\" ||\n        !isTimestamp(record.startedAt) ||\n        !isTimestamp(record.heartbeatAt) ||\n        (expected.experimentId !== undefined && record.experimentId !== expected.experimentId) ||\n        (expected.slot !== undefined && record.slot !== expected.slot)) {\n        return undefined;\n    }\n    return {\n        experimentId: record.experimentId,\n        slot: record.slot,\n        declaredN: record.declaredN,\n        pid: record.pid,\n        host: record.host,\n        startedAt: record.startedAt,\n        heartbeatAt: record.heartbeatAt,\n    };\n}\n/** 持有者续租心跳的周期。与用例锁同参数。 */\nexport const GATE_LEASE_HEARTBEAT_INTERVAL_MS = CASE_LOCK_HEARTBEAT_INTERVAL_MS;\n/** `heartbeatAt` 落后当前时间超过这个阈值(三个心跳周期)即视为持有者已死。 */\nexport const GATE_LEASE_EXPIRY_MS = CASE_LOCK_EXPIRY_MS;\nexport function gateLeasesDirOf(niceevalRoot: string): string {\n    return locksDirOf(niceevalRoot);\n}\nfunction gateLeaseEntryId(experimentId: string, slot: number): string {\n    return slugHashEntryId(`gate-${experimentId}-${slot}`, [\"gate-lease\", experimentId, String(slot)]);\n}\n/** Effect 主 API:读取该实验当前在场的全部租约记录,无副作用。 */\nexport function readGateLeasesEffect(niceevalRoot: string, experimentId: string): Effect.Effect<GateLeaseRecord[], unknown> {\n    return readAllEntryFilesEffect(gateLeasesDirOf(niceevalRoot), decodeGateLeaseRecord).pipe(Effect.map((entries) => entries\n        .map(({ entry }) => entry)\n        .filter((entry) => entry.experimentId === experimentId)\n        .sort((a, b) => a.slot - b.slot)));\n}\n/** 过期判据:只看心跳时间戳,不看 pid。 */\nexport function isGateLeaseExpired(record: GateLeaseRecord, nowMs: number): boolean {\n    const heartbeatMs = Date.parse(record.heartbeatAt);\n    if (Number.isNaN(heartbeatMs))\n        return true;\n    return nowMs - heartbeatMs > GATE_LEASE_EXPIRY_MS;\n}\n/** 本进程声明的 N:非法值收敛到 1，避免永久满位。 */\nfunction normalizeN(n: number): number {\n    const floored = Math.floor(n);\n    return Number.isFinite(floored) && floored >= 1 ? floored : 1;\n}\n/** min-N:有效名额取自己声明和所有新鲜租约声明的最小值。 */\nfunction effectiveSlotCount(maxConcurrency: number, leases: readonly GateLeaseRecord[], nowMs: number): number {\n    let n = normalizeN(maxConcurrency);\n    for (const lease of leases) {\n        if (isGateLeaseExpired(lease, nowMs))\n            continue;\n        const declared = normalizeN(lease.declaredN);\n        if (declared < n)\n            n = declared;\n    }\n    return n;\n}\n/** O_EXCL 独占创建租约文件;存在时返回 false,不覆盖。 */\nfunction createLeaseFileExclusiveEffect(dir: string, id: string, record: GateLeaseRecord): Effect.Effect<boolean, unknown> {\n    const path = join(dir, `${id}.json`);\n    return nodeIo(() => mkdir(dir, { recursive: true })).pipe(Effect.zipRight(withOpenFile(path, \"wx\", (handle) => nodeIo(() => handle.writeFile(JSON.stringify(record, null, 2), \"utf-8\")).pipe(Effect.zipRight(nodeIo(() => handle.sync()))))), Effect.zipRight(fsyncDirEffect(dir)), Effect.as(true), Effect.catchAll((cause) => errnoCode(cause) === \"EEXIST\" ? Effect.succeed(false) : Effect.fail(cause)));\n}\n/** 同一持有者判定:身份(pid/host)加上取位时刻——接管重建后 `startedAt` 必然不同。 */\nfunction isSameHolder(record: GateLeaseRecord, mine: GateLeaseRecord): boolean {\n    return record.pid === mine.pid && record.host === mine.host && record.startedAt === mine.startedAt;\n}\n/** 一次非阻塞取位:空槽 O_EXCL 创建，满位时只接管过期或损坏槽。 */\nexport function tryAcquireGateSlotOnceEffect(niceevalRoot: string, experimentId: string, maxConcurrency: number, identity: {\n    pid: number;\n    host: string;\n}, nowMs: number): Effect.Effect<GateSlotAttempt, unknown> {\n    const dir = gateLeasesDirOf(niceevalRoot);\n    return Effect.gen(function* () {\n        const effectiveN = effectiveSlotCount(maxConcurrency, yield* readGateLeasesEffect(niceevalRoot, experimentId), nowMs);\n        const stamp = new Date(nowMs).toISOString();\n        const recordFor = (slot: number): GateLeaseRecord => ({\n            experimentId,\n            slot,\n            declaredN: normalizeN(maxConcurrency),\n            pid: identity.pid,\n            host: identity.host,\n            startedAt: stamp,\n            heartbeatAt: stamp,\n        });\n        const acquired = (slot: number, record: GateLeaseRecord, options: {\n            takenOver: boolean;\n            takenOverFrom?: GateLeaseRecord;\n        }): GateSlotAcquired => ({ kind: \"acquired\", slot, record, ...options });\n        // 第一趟不预读占用情况：O_EXCL 本身就是判据。\n        for (let slot = 0; slot < effectiveN; slot += 1) {\n            const record = recordFor(slot);\n            if (yield* createLeaseFileExclusiveEffect(dir, gateLeaseEntryId(experimentId, slot), record)) {\n                return acquired(slot, record, { takenOver: false });\n            }\n        }\n        // 第二趟只对坏条目或过期条目执行 rename 认领；输掉竞态后继续下一槽。\n        for (let slot = 0; slot < effectiveN; slot += 1) {\n            const id = gateLeaseEntryId(experimentId, slot);\n            const current = yield* readEntryFileEffect(dir, id, (value) => decodeGateLeaseRecord(value, { experimentId, slot }));\n            if (current === undefined) {\n                if (!(yield* claimEntryFileEffect(dir, id)))\n                    continue;\n                const record = recordFor(slot);\n                if (!(yield* createLeaseFileExclusiveEffect(dir, id, record)))\n                    continue;\n                return acquired(slot, record, { takenOver: false });\n            }\n            if (!isGateLeaseExpired(current, nowMs))\n                continue;\n            if (!(yield* claimEntryFileEffect(dir, id)))\n                continue;\n            const record = recordFor(slot);\n            if (!(yield* createLeaseFileExclusiveEffect(dir, id, record)))\n                continue;\n            return acquired(slot, record, { takenOver: true, takenOverFrom: current });\n        }\n        const holders = (yield* readGateLeasesEffect(niceevalRoot, experimentId)).filter((lease) => !isGateLeaseExpired(lease, nowMs));\n        return { kind: \"full\", holders };\n    });\n}\n/** 续租只改 heartbeat；槽被接管后不写、不删别人的租约。 */\nfunction renewHeartbeatEffect(dir: string, id: string, mine: GateLeaseRecord, nowMs: number, isReleased: () => boolean): Effect.Effect<void, unknown> {\n    if (isReleased())\n        return Effect.void;\n    return readEntryFileEffect(dir, id, (value) => decodeGateLeaseRecord(value, { experimentId: mine.experimentId, slot: mine.slot })).pipe(Effect.flatMap((current) => {\n        if (current === undefined || !isSameHolder(current, mine) || isReleased())\n            return Effect.void;\n        return writeEntryFileEffect(dir, id, { ...current, heartbeatAt: new Date(nowMs).toISOString() });\n    }));\n}\nfunction makeAbortError(signal: AbortSignal | undefined): Error {\n    const reason = signal?.reason;\n    if (reason instanceof Error)\n        return reason;\n    const err = new Error(\"aborted while waiting for experiment gate slot\");\n    err.name = \"AbortError\";\n    return err;\n}\nfunction awaitAbort(signal: AbortSignal | undefined): Effect.Effect<never, Error> {\n    return Effect.async((resume, effectSignal) => {\n        if (signal === undefined)\n            return;\n        const cleanup = (): void => {\n            signal.removeEventListener(\"abort\", onAbort);\n            effectSignal.removeEventListener(\"abort\", cleanup);\n        };\n        const onAbort = (): void => {\n            cleanup();\n            resume(Effect.fail(makeAbortError(signal)));\n        };\n        if (signal.aborted) {\n            onAbort();\n            return;\n        }\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n        effectSignal.addEventListener(\"abort\", cleanup, { once: true });\n    });\n}\nfunction delayOrAbortEffect(ms: number, signal: AbortSignal | undefined): Effect.Effect<void, Error> {\n    if (signal?.aborted)\n        return Effect.fail(makeAbortError(signal));\n    return Effect.raceFirst(Effect.sleep(ms), awaitAbort(signal)).pipe(Effect.asVoid);\n}\nexport interface GateLeaseEffectClaim {\n    readonly slot: number;\n    readonly release: Effect.Effect<void, unknown>;\n}\nexport interface AcquireGateSlotEffectResult {\n    claim: GateLeaseEffectClaim;\n    takenOver: boolean;\n    takenOverFrom?: GateLeaseRecord;\n}\nconst held = new Map<string, Effect.Effect<void, unknown>>();\nfunction heldKey(niceevalRoot: string, id: string): string {\n    return `${niceevalRoot} ${id}`;\n}\n/** 高层 Effect 入口:等待可中断；心跳顺序化，release 等正在飞的不可中断续租结束再删除。 */\nexport function acquireGateSlotEffect(niceevalRoot: string, experimentId: string, maxConcurrency: number, identity: {\n    pid: number;\n    host: string;\n}, opts: {\n    signal?: AbortSignal;\n    pollIntervalMs?: number;\n    heartbeatIntervalMs?: number;\n    onWaitStart?: (holders: GateLeaseRecord[]) => void;\n} = {}): Effect.Effect<AcquireGateSlotEffectResult, unknown> {\n    const heartbeatIntervalMs = opts.heartbeatIntervalMs ?? GATE_LEASE_HEARTBEAT_INTERVAL_MS;\n    const pollIntervalMs = opts.pollIntervalMs ?? heartbeatIntervalMs;\n    let waitStarted = false;\n    const acquireLoop = (): Effect.Effect<{\n        slot: number;\n        takenOver: boolean;\n        takenOverFrom?: GateLeaseRecord;\n        record: GateLeaseRecord;\n    }, unknown> => Effect.suspend(() => {\n        if (opts.signal?.aborted)\n            return Effect.fail(makeAbortError(opts.signal));\n        return tryAcquireGateSlotOnceEffect(niceevalRoot, experimentId, maxConcurrency, identity, Date.now()).pipe(Effect.flatMap((result) => {\n            if (result.kind === \"acquired\")\n                return Effect.succeed(result);\n            const reportWait = waitStarted\n                ? Effect.void\n                : Effect.sync(() => {\n                    waitStarted = true;\n                    opts.onWaitStart?.(result.holders);\n                });\n            return reportWait.pipe(Effect.zipRight(delayOrAbortEffect(pollIntervalMs, opts.signal)), Effect.zipRight(acquireLoop()));\n        }));\n    });\n    return Effect.uninterruptibleMask((restore) => restore(acquireLoop()).pipe(Effect.flatMap(({ slot, takenOver, takenOverFrom, record }) => {\n        const dir = gateLeasesDirOf(niceevalRoot);\n        const id = gateLeaseEntryId(experimentId, slot);\n        const key = heldKey(niceevalRoot, id);\n        let released = false;\n        const heartbeat = Effect.forever(Effect.sleep(heartbeatIntervalMs).pipe(Effect.zipRight(Effect.suspend(() => Effect.uninterruptible(renewHeartbeatEffect(dir, id, record, Date.now(), () => released)))\n            .pipe(Effect.ignore))));\n        // A child inherits the parent's interruptibility. This branch still\n        // runs under the acquisition mask, so restore the heartbeat before\n        // forking; otherwise release would wait forever while interrupting an\n        // uninterruptible sleeping fiber.\n        return Effect.forkDaemon(restore(heartbeat)).pipe(Effect.map((fiber) => {\n            const release = Effect.uninterruptible(Effect.suspend(() => {\n                if (released)\n                    return Effect.void;\n                released = true;\n                held.delete(key);\n                return Fiber.interrupt(fiber).pipe(Effect.zipRight(readEntryFileEffect(dir, id, (value) => decodeGateLeaseRecord(value, { experimentId, slot }))), Effect.flatMap((current) => current !== undefined && !isSameHolder(current, record)\n                    ? Effect.void\n                    : nodeIo(() => rm(join(dir, `${id}.json`), { force: true })).pipe(Effect.zipRight(fsyncDirEffect(dir)))));\n            }));\n            held.set(key, release);\n            return { claim: { slot, release }, takenOver, ...(takenOverFrom === undefined ? {} : { takenOverFrom }) };\n        }));\n    })));\n}\n/** 强清兜底:尽力释放当前进程持有的每一条租约。 */\nexport function drainHeldGateLeasesEffect(): Effect.Effect<number> {\n    const releases = [...held.values()];\n    return Effect.forEach(releases, (release) => Effect.exit(release), { discard: true }).pipe(Effect.as(releases.length));\n}\n/** 当前进程仍持有的实验闸租约数量，供退出清理与可观察状态汇总。 */\nexport function pendingHeldGateLeaseCount(): number {\n    return held.size;\n}\n"]}