niceeval 0.13.1 → 0.13.2

package/dist/runner/teardown-registry.cjs

@@ -4,6 +4,8 @@ exports.teardownsDirOf = teardownsDirOf;
 exports.teardownEntryId = teardownEntryId;
 exports.writeTeardownRegistrationEffect = writeTeardownRegistrationEffect;
 exports.readTeardownRegistrationEffect = readTeardownRegistrationEffect;
+exports.readExactTeardownRegistrationEffect = readExactTeardownRegistrationEffect;
+exports.isExactTeardownRegistrationOwnerTerminatedEffect = isExactTeardownRegistrationOwnerTerminatedEffect;
 exports.readTeardownRegistrationsEffect = readTeardownRegistrationsEffect;
 exports.removeTeardownRegistrationIfPresentEffect = removeTeardownRegistrationIfPresentEffect;
 exports.isOrphanedTeardownRegistration = isOrphanedTeardownRegistration;
@@ -12,41 +14,36 @@ exports.orphanedTeardownReminderEffect = orphanedTeardownReminderEffect;
 // (sandbox/keep-registry.ts)同一套原子写纪律,两者都建在 shared/entry-file-store.ts 之上
 // (temp → fsync → rename → fsync 目录)。
 // 契约见 docs/feature/experiments/architecture.md「强杀后的收尾兜底:收尾登记与启动自愈」。
+const node_fs_1 = require("node:fs");
+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");
-function recordOf(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? value
+const shared_state_lease_ts_1 = require("./shared-state-lease.cjs");
+const PositiveSafeIntegerSchema = effect_1.Schema.Number.pipe(effect_1.Schema.filter((value) => Number.isSafeInteger(value) && value > 0, { identifier: "PositiveSafeInteger" }));
+const TimestampSchema = effect_1.Schema.String.pipe(effect_1.Schema.filter((value) => Number.isFinite(Date.parse(value)), { identifier: "Timestamp" }));
+const TeardownRegistrationSchema = effect_1.Schema.Struct({
+    experimentId: effect_1.Schema.String,
+    selectedEvalIds: effect_1.Schema.Array(effect_1.Schema.String),
+    pid: PositiveSafeIntegerSchema,
+    host: effect_1.Schema.String,
+    startedAt: TimestampSchema,
+});
+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 isTimestamp(value) {
-    return typeof value === "string" && Number.isFinite(Date.parse(value));
-}
 /** 收尾登记的完整持久形状；单条读取还会核对文件身份。 */
 function decodeTeardownRegistration(value, expected = {}) {
-    const record = recordOf(value);
-    if (record === undefined ||
-        typeof record.experimentId !== "string" ||
-        !Array.isArray(record.selectedEvalIds) ||
-        !record.selectedEvalIds.every((id) => typeof id === "string") ||
-        !isPositiveInteger(record.pid) ||
-        typeof record.host !== "string" ||
-        !isTimestamp(record.startedAt) ||
-        (expected.experimentId !== undefined && record.experimentId !== expected.experimentId) ||
-        (expected.pid !== undefined && record.pid !== expected.pid)) {
+    const decoded = effect_1.Schema.decodeUnknownEither(TeardownRegistrationSchema)(value);
+    if (effect_1.Either.isLeft(decoded))
         return undefined;
-    }
-    return {
-        experimentId: record.experimentId,
-        selectedEvalIds: record.selectedEvalIds,
-        pid: record.pid,
-        host: record.host,
-        startedAt: record.startedAt,
-    };
+    const registration = decoded.right;
+    return (expected.experimentId !== undefined && registration.experimentId !== expected.experimentId) ||
+        (expected.pid !== undefined && registration.pid !== expected.pid)
+        ? undefined
+        : registration;
 }
 function teardownsDirOf(niceevalRoot) {
     return (0, node_path_1.join)(niceevalRoot, "teardowns");
@@ -64,6 +61,54 @@ function writeTeardownRegistrationEffect(niceevalRoot, entry) {
 function readTeardownRegistrationEffect(niceevalRoot, experimentId, pid) {
     return (0, entry_file_store_ts_1.readEntryFileEffect)(teardownsDirOf(niceevalRoot), teardownEntryId(experimentId, pid), (value) => decodeTeardownRegistration(value, { experimentId, pid }));
 }
+/**
+ * Exact recovery cannot treat a malformed or unreadable expected entry as an
+ * absent cleanup obligation. Normal registry scans deliberately tolerate
+ * damaged historical rows; a recovery is instead about to publish a new
+ * sharedState generation, so only a genuinely absent path is safe to accept.
+ */
+function readExactTeardownRegistrationEffect(niceevalRoot, experimentId, pid) {
+    const id = teardownEntryId(experimentId, pid);
+    const path = (0, node_path_1.join)(teardownsDirOf(niceevalRoot), `${id}.json`);
+    return effect_1.Effect.tryPromise({
+        try: () => (0, promises_1.readFile)(path, "utf8"),
+        catch: (cause) => cause,
+    }).pipe(effect_1.Effect.catchAll((cause) => errnoCode(cause) === "ENOENT" ? effect_1.Effect.succeed(undefined) : effect_1.Effect.fail(cause)), effect_1.Effect.flatMap((raw) => raw === undefined ? effect_1.Effect.succeed(undefined) : effect_1.Effect.try({
+        try: () => {
+            let value;
+            try {
+                value = JSON.parse(raw);
+            }
+            catch (cause) {
+                throw new Error(`teardown registration ${JSON.stringify(id)} is not valid JSON`, { cause });
+            }
+            const registration = decodeTeardownRegistration(value, { experimentId, pid });
+            if (registration === undefined) {
+                throw new Error(`teardown registration ${JSON.stringify(id)} has an invalid identity or shape`);
+            }
+            return registration;
+        },
+        catch: (cause) => cause,
+    })));
+}
+/**
+ * Checks the terminal state of the exact owner recorded by a sharedState
+ * generation. On the local host, this uses the same PID + process-identity
+ * probe as lease recovery: ENOENT, PID reuse, and Linux Z/X/x are terminal;
+ * unreadable or malformed probe evidence fails rather than guessing. Remote
+ * termination was already explicitly confirmed by the recovery command.
+ */
+function isExactTeardownRegistrationOwnerTerminatedEffect(input) {
+    const { registration, owner, currentHost } = input;
+    if (registration.experimentId !== owner.experimentId ||
+        registration.pid !== owner.pid ||
+        registration.host !== owner.host) {
+        return effect_1.Effect.fail(new Error("teardown registration does not match the immutable sharedState owner identity"));
+    }
+    if (owner.host !== currentHost)
+        return effect_1.Effect.succeed(true);
+    return (0, shared_state_lease_ts_1.processIdentityForPidEffect)(owner.pid).pipe(effect_1.Effect.map((currentIdentity) => currentIdentity === undefined || currentIdentity !== owner.processIdentity));
+}
 /** 读全部登记项(损坏条目跳过,不整体失败;目录不存在时返回空集合)。 */
 function readTeardownRegistrationsEffect(niceevalRoot) {
     return (0, entry_file_store_ts_1.readAllEntryFilesEffect)(teardownsDirOf(niceevalRoot), decodeTeardownRegistration);
@@ -76,20 +121,38 @@ function readTeardownRegistrationsEffect(niceevalRoot) {
 function removeTeardownRegistrationIfPresentEffect(niceevalRoot, id) {
     return (0, entry_file_store_ts_1.claimEntryFileEffect)(teardownsDirOf(niceevalRoot), id);
 }
-/** 同宿主 pid 存活探测。runner 已依赖 sandbox 模块;此处保持本地小函数,是因为收尾登记只需
- * `kill(pid, 0)` 这一无副作用的宿主进程事实,不应把 sandbox 身份分类策略带进来。 */
-function isPidAlive(pid) {
+/**
+ * Normal startup scans only persist PID + host, so they cannot prove PID
+ * reuse. They still share lease recovery's terminal Linux process states:
+ * a Z/X/x task cannot execute cleanup. Any `/proc` read/parse ambiguity is
+ * deliberately treated as live here; the explicit recovery path above has
+ * stronger immutable identity evidence and fails closed on that ambiguity.
+ */
+function isPidTerminal(pid) {
+    if (process.platform === "linux") {
+        try {
+            const raw = (0, node_fs_1.readFileSync)(`/proc/${pid}/stat`, "utf8");
+            const closing = raw.lastIndexOf(")");
+            if (closing < 0 || raw[closing + 1] !== " ")
+                return false;
+            const state = raw.slice(closing + 2).trim().split(/\s+/u)[0];
+            return state === "Z" || state === "X" || state === "x";
+        }
+        catch (cause) {
+            return errnoCode(cause) === "ENOENT";
+        }
+    }
     try {
         process.kill(pid, 0);
-        return true;
+        return false;
     }
     catch (e) {
-        return e.code === "EPERM";
+        return e.code !== "EPERM";
     }
 }
-/** 遗留义务判定:同宿主且 pid 不存活。pid 存活或异宿主可能属于并发 run,不触碰。 */
+/** 遗留义务判定:同宿主且 PID 已缺失或处于终态。pid 存活、读取不明或异宿主可能属于并发 run,不触碰。 */
 function isOrphanedTeardownRegistration(entry, currentHost) {
-    return entry.host === currentHost && !isPidAlive(entry.pid);
+    return entry.host === currentHost && isPidTerminal(entry.pid);
 }
 /**
  * `niceeval exp` 启动提醒:遗留义务里「不在本次选择」的那部分,各给一行 `--teardown` 命令。

package/dist/runner/teardown-registry.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"teardown-registry.js","sourceRoot":"","sources":["teardown-registry.ts"],"names":[],"mappings":";;AAmDA,wCAEC;AAED,0CAEC;AAED,0EAGC;AAED,wEAEC;AAED,0EAKC;AAMD,8FAEC;AAaD,wEAEC;AAMD,wEAYC;AAlHD,kDAAkD;AAClD,yEAAyE;AACzE,sCAAsC;AACtC,oEAAoE;AACpE,yCAAiC;AACjC,mCAAgC;AAChC,uEAAuJ;AASvJ,SAAS,QAAQ,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACvE,CAAC,CAAC,KAA2C;QAC7C,CAAC,CAAC,SAAS,CAAC;AACpB,CAAC;AACD,SAAS,iBAAiB,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AACjF,CAAC;AACD,SAAS,WAAW,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3E,CAAC;AACD,gCAAgC;AAChC,SAAS,0BAA0B,CAAC,KAAc,EAAE,WAGhD,EAAE;IACF,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS;QACpB,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ;QACvC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC;QACtC,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC;QAC7D,CAAC,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC;QAC9B,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAC/B,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC;QAC9B,CAAC,QAAQ,CAAC,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,YAAY,KAAK,QAAQ,CAAC,YAAY,CAAC;QACtF,CAAC,QAAQ,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9D,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,OAAO;QACH,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,SAAS,EAAE,MAAM,CAAC,SAAS;KAC9B,CAAC;AACN,CAAC;AACD,SAAgB,cAAc,CAAC,YAAoB;IAC/C,OAAO,IAAA,gBAAI,EAAC,YAAY,EAAE,WAAW,CAAC,CAAC;AAC3C,CAAC;AACD,sDAAsD;AACtD,SAAgB,eAAe,CAAC,YAAoB,EAAE,GAAW;IAC7D,OAAO,IAAA,iCAAW,EAAC,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AACD,mDAAmD;AACnD,SAAgB,+BAA+B,CAAC,YAAoB,EAAE,KAA2B;IAC7F,MAAM,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1D,OAAO,IAAA,0CAAoB,EAAC,cAAc,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;AACzE,CAAC;AACD,uCAAuC;AACvC,SAAgB,8BAA8B,CAAC,YAAoB,EAAE,YAAoB,EAAE,GAAW;IAClG,OAAO,IAAA,yCAAmB,EAAC,cAAc,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC,YAAY,EAAE,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,0BAA0B,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AACtK,CAAC;AACD,wCAAwC;AACxC,SAAgB,+BAA+B,CAAC,YAAoB;IAIhE,OAAO,IAAA,6CAAuB,EAAC,cAAc,CAAC,YAAY,CAAC,EAAE,0BAA0B,CAAC,CAAC;AAC7F,CAAC;AACD;;;;GAIG;AACH,SAAgB,yCAAyC,CAAC,YAAoB,EAAE,EAAU;IACtF,OAAO,IAAA,0CAAoB,EAAC,cAAc,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;AAClE,CAAC;AACD;yDACyD;AACzD,SAAS,UAAU,CAAC,GAAW;IAC3B,IAAI,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,CAAC,EAAE,CAAC;QACP,OAAQ,CAA2B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACL,CAAC;AACD,oDAAoD;AACpD,SAAgB,8BAA8B,CAAC,KAA2B,EAAE,WAAmB;IAC3F,OAAO,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAChE,CAAC;AACD;;;;GAIG;AACH,SAAgB,8BAA8B,CAAC,YAAoB,EAAE,uBAA4C,EAAE,WAAmB;IAClI,OAAO,+BAA+B,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,eAAM,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,EAAE;QACnF,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,EAAE,KAAK,EAAE,IAAI,aAAa,EAAE,CAAC;YACpC,IAAI,CAAC,8BAA8B,CAAC,KAAK,EAAE,WAAW,CAAC;gBACnD,SAAS;YACb,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC;gBAC/C,SAAS;YACb,KAAK,CAAC,IAAI,CAAC,uCAAuC,KAAK,CAAC,YAAY,sCAAsC,KAAK,CAAC,YAAY,eAAe,CAAC,CAAC;QACjJ,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,CAAC,CAAC,CAAC,CAAC;AACR,CAAC","sourcesContent":["// 强杀后的收尾登记表:`.niceeval/teardowns/` 下的逐条目文件,与留存注册表\n// (sandbox/keep-registry.ts)同一套原子写纪律,两者都建在 shared/entry-file-store.ts 之上\n// (temp → fsync → rename → fsync 目录)。\n// 契约见 docs/feature/experiments/architecture.md「强杀后的收尾兜底:收尾登记与启动自愈」。\nimport { join } from \"node:path\";\nimport { Effect } from \"effect\";\nimport { claimEntryFileEffect, hashEntryId, readAllEntryFilesEffect, readEntryFileEffect, writeEntryFileEffect, } from \"../shared/entry-file-store.ts\";\n/** 一条收尾登记项(逐条目文件的 JSON 形状)。 */\nexport interface TeardownRegistration {\n    experimentId: string;\n    selectedEvalIds: readonly string[];\n    pid: number;\n    host: string;\n    startedAt: string;\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 isTimestamp(value: unknown): value is string {\n    return typeof value === \"string\" && Number.isFinite(Date.parse(value));\n}\n/** 收尾登记的完整持久形状；单条读取还会核对文件身份。 */\nfunction decodeTeardownRegistration(value: unknown, expected: {\n    experimentId?: string;\n    pid?: number;\n} = {}): TeardownRegistration | undefined {\n    const record = recordOf(value);\n    if (record === undefined ||\n        typeof record.experimentId !== \"string\" ||\n        !Array.isArray(record.selectedEvalIds) ||\n        !record.selectedEvalIds.every((id) => typeof id === \"string\") ||\n        !isPositiveInteger(record.pid) ||\n        typeof record.host !== \"string\" ||\n        !isTimestamp(record.startedAt) ||\n        (expected.experimentId !== undefined && record.experimentId !== expected.experimentId) ||\n        (expected.pid !== undefined && record.pid !== expected.pid)) {\n        return undefined;\n    }\n    return {\n        experimentId: record.experimentId,\n        selectedEvalIds: record.selectedEvalIds,\n        pid: record.pid,\n        host: record.host,\n        startedAt: record.startedAt,\n    };\n}\nexport function teardownsDirOf(niceevalRoot: string): string {\n    return join(niceevalRoot, \"teardowns\");\n}\n/** entry id:实验身份 + 进程身份的稳定散列。同一实验的并发 run 各有独立收尾义务。 */\nexport function teardownEntryId(experimentId: string, pid: number): string {\n    return hashEntryId([experimentId, String(pid)]);\n}\n/** 原子写入一条登记项(委托给共享层的 write-tmp-then-rename 纪律)。 */\nexport function writeTeardownRegistrationEffect(niceevalRoot: string, entry: TeardownRegistration): Effect.Effect<void, unknown> {\n    const id = teardownEntryId(entry.experimentId, entry.pid);\n    return writeEntryFileEffect(teardownsDirOf(niceevalRoot), id, entry);\n}\n/** 读一条登记项(不存在或损坏都返回 undefined,不抛错)。 */\nexport function readTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown> {\n    return readEntryFileEffect(teardownsDirOf(niceevalRoot), teardownEntryId(experimentId, pid), (value) => decodeTeardownRegistration(value, { experimentId, pid }));\n}\n/** 读全部登记项(损坏条目跳过,不整体失败;目录不存在时返回空集合)。 */\nexport function readTeardownRegistrationsEffect(niceevalRoot: string): Effect.Effect<{\n    id: string;\n    entry: TeardownRegistration;\n}[], unknown> {\n    return readAllEntryFilesEffect(teardownsDirOf(niceevalRoot), decodeTeardownRegistration);\n}\n/**\n * 删登记是互斥点:委托给共享层的认领原语(rename-墓碑,见 ../shared/entry-file-store.ts 的\n * `claimEntryFile` 头注释)。成功认领(返回 true)即拿到执行权;登记已被别的进程删除\n * (返回 false)则跳过——同一份遗留义务不会被两个进程双跑。\n */\nexport function removeTeardownRegistrationIfPresentEffect(niceevalRoot: string, id: string): Effect.Effect<boolean, unknown> {\n    return claimEntryFileEffect(teardownsDirOf(niceevalRoot), id);\n}\n/** 同宿主 pid 存活探测。runner 已依赖 sandbox 模块;此处保持本地小函数,是因为收尾登记只需\n * `kill(pid, 0)` 这一无副作用的宿主进程事实,不应把 sandbox 身份分类策略带进来。 */\nfunction isPidAlive(pid: number): boolean {\n    try {\n        process.kill(pid, 0);\n        return true;\n    }\n    catch (e) {\n        return (e as NodeJS.ErrnoException).code === \"EPERM\";\n    }\n}\n/** 遗留义务判定:同宿主且 pid 不存活。pid 存活或异宿主可能属于并发 run,不触碰。 */\nexport function isOrphanedTeardownRegistration(entry: TeardownRegistration, currentHost: string): boolean {\n    return entry.host === currentHost && !isPidAlive(entry.pid);\n}\n/**\n * `niceeval exp` 启动提醒:遗留义务里「不在本次选择」的那部分,各给一行 `--teardown` 命令。\n * 在本次选择且仍声明 teardown 的遗留义务由 run.ts 在调度前自动补执行,不出现在这里\n * (见 docs/feature/experiments/architecture.md「强杀后的收尾兜底」)。\n */\nexport function orphanedTeardownReminderEffect(niceevalRoot: string, recoveringExperimentIds: ReadonlySet<string>, currentHost: string): Effect.Effect<string | undefined, unknown> {\n    return readTeardownRegistrationsEffect(niceevalRoot).pipe(Effect.map((registrations) => {\n        const lines: string[] = [];\n        for (const { entry } of registrations) {\n            if (!isOrphanedTeardownRegistration(entry, currentHost))\n                continue;\n            if (recoveringExperimentIds.has(entry.experimentId))\n                continue;\n            lines.push(`unfinished experiment teardown for \"${entry.experimentId}\" from a killed run — niceeval exp ${entry.experimentId} --teardown\\n`);\n        }\n        return lines.length > 0 ? lines.join(\"\") : undefined;\n    }));\n}\n"]}
+{"version":3,"file":"teardown-registry.js","sourceRoot":"","sources":["teardown-registry.ts"],"names":[],"mappings":"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","sourcesContent":["// 强杀后的收尾登记表:`.niceeval/teardowns/` 下的逐条目文件,与留存注册表\n// (sandbox/keep-registry.ts)同一套原子写纪律,两者都建在 shared/entry-file-store.ts 之上\n// (temp → fsync → rename → fsync 目录)。\n// 契约见 docs/feature/experiments/architecture.md「强杀后的收尾兜底:收尾登记与启动自愈」。\nimport { readFileSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { Effect, Either, Schema } from \"effect\";\nimport { claimEntryFileEffect, hashEntryId, readAllEntryFilesEffect, readEntryFileEffect, writeEntryFileEffect, } from \"../shared/entry-file-store.ts\";\nimport { processIdentityForPidEffect } from \"./shared-state-lease.ts\";\n/** 一条收尾登记项(逐条目文件的 JSON 形状)。 */\nexport interface TeardownRegistration {\n    experimentId: string;\n    selectedEvalIds: readonly string[];\n    pid: number;\n    host: string;\n    startedAt: string;\n}\nconst PositiveSafeIntegerSchema = Schema.Number.pipe(Schema.filter((value) => Number.isSafeInteger(value) && value > 0, { identifier: \"PositiveSafeInteger\" }));\nconst TimestampSchema = Schema.String.pipe(Schema.filter((value) => Number.isFinite(Date.parse(value)), { identifier: \"Timestamp\" }));\nconst TeardownRegistrationSchema = Schema.Struct({\n    experimentId: Schema.String,\n    selectedEvalIds: Schema.Array(Schema.String),\n    pid: PositiveSafeIntegerSchema,\n    host: Schema.String,\n    startedAt: TimestampSchema,\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}\n/** 收尾登记的完整持久形状；单条读取还会核对文件身份。 */\nfunction decodeTeardownRegistration(value: unknown, expected: {\n    experimentId?: string;\n    pid?: number;\n} = {}): TeardownRegistration | undefined {\n    const decoded = Schema.decodeUnknownEither(TeardownRegistrationSchema)(value);\n    if (Either.isLeft(decoded))\n        return undefined;\n    const registration = decoded.right;\n    return (expected.experimentId !== undefined && registration.experimentId !== expected.experimentId) ||\n        (expected.pid !== undefined && registration.pid !== expected.pid)\n        ? undefined\n        : registration;\n}\nexport function teardownsDirOf(niceevalRoot: string): string {\n    return join(niceevalRoot, \"teardowns\");\n}\n/** entry id:实验身份 + 进程身份的稳定散列。同一实验的并发 run 各有独立收尾义务。 */\nexport function teardownEntryId(experimentId: string, pid: number): string {\n    return hashEntryId([experimentId, String(pid)]);\n}\n/** 原子写入一条登记项(委托给共享层的 write-tmp-then-rename 纪律)。 */\nexport function writeTeardownRegistrationEffect(niceevalRoot: string, entry: TeardownRegistration): Effect.Effect<void, unknown> {\n    const id = teardownEntryId(entry.experimentId, entry.pid);\n    return writeEntryFileEffect(teardownsDirOf(niceevalRoot), id, entry);\n}\n/** 读一条登记项(不存在或损坏都返回 undefined,不抛错)。 */\nexport function readTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown> {\n    return readEntryFileEffect(teardownsDirOf(niceevalRoot), teardownEntryId(experimentId, pid), (value) => decodeTeardownRegistration(value, { experimentId, pid }));\n}\n/**\n * Exact recovery cannot treat a malformed or unreadable expected entry as an\n * absent cleanup obligation. Normal registry scans deliberately tolerate\n * damaged historical rows; a recovery is instead about to publish a new\n * sharedState generation, so only a genuinely absent path is safe to accept.\n */\nexport function readExactTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown> {\n    const id = teardownEntryId(experimentId, pid);\n    const path = join(teardownsDirOf(niceevalRoot), `${id}.json`);\n    return Effect.tryPromise({\n        try: () => readFile(path, \"utf8\"),\n        catch: (cause) => cause,\n    }).pipe(Effect.catchAll((cause) => errnoCode(cause) === \"ENOENT\" ? Effect.succeed(undefined) : Effect.fail(cause)), Effect.flatMap((raw) => raw === undefined ? Effect.succeed(undefined) : Effect.try({\n        try: () => {\n            let value: unknown;\n            try {\n                value = JSON.parse(raw);\n            }\n            catch (cause) {\n                throw new Error(`teardown registration ${JSON.stringify(id)} is not valid JSON`, { cause });\n            }\n            const registration = decodeTeardownRegistration(value, { experimentId, pid });\n            if (registration === undefined) {\n                throw new Error(`teardown registration ${JSON.stringify(id)} has an invalid identity or shape`);\n            }\n            return registration;\n        },\n        catch: (cause) => cause,\n    })));\n}\n/** Immutable sharedState owner facts that can prove a registry row is old. */\nexport interface ExactTeardownRegistrationOwner {\n    readonly experimentId: string;\n    readonly pid: number;\n    readonly host: string;\n    readonly processIdentity: string;\n}\n/**\n * Checks the terminal state of the exact owner recorded by a sharedState\n * generation. On the local host, this uses the same PID + process-identity\n * probe as lease recovery: ENOENT, PID reuse, and Linux Z/X/x are terminal;\n * unreadable or malformed probe evidence fails rather than guessing. Remote\n * termination was already explicitly confirmed by the recovery command.\n */\nexport function isExactTeardownRegistrationOwnerTerminatedEffect(input: {\n    readonly registration: TeardownRegistration;\n    readonly owner: ExactTeardownRegistrationOwner;\n    readonly currentHost: string;\n}): Effect.Effect<boolean, unknown> {\n    const { registration, owner, currentHost } = input;\n    if (registration.experimentId !== owner.experimentId ||\n        registration.pid !== owner.pid ||\n        registration.host !== owner.host) {\n        return Effect.fail(new Error(\"teardown registration does not match the immutable sharedState owner identity\"));\n    }\n    if (owner.host !== currentHost)\n        return Effect.succeed(true);\n    return processIdentityForPidEffect(owner.pid).pipe(Effect.map((currentIdentity) => currentIdentity === undefined || currentIdentity !== owner.processIdentity));\n}\n/** 读全部登记项(损坏条目跳过,不整体失败;目录不存在时返回空集合)。 */\nexport function readTeardownRegistrationsEffect(niceevalRoot: string): Effect.Effect<{\n    id: string;\n    entry: TeardownRegistration;\n}[], unknown> {\n    return readAllEntryFilesEffect(teardownsDirOf(niceevalRoot), decodeTeardownRegistration);\n}\n/**\n * 删登记是互斥点:委托给共享层的认领原语(rename-墓碑,见 ../shared/entry-file-store.ts 的\n * `claimEntryFile` 头注释)。成功认领(返回 true)即拿到执行权;登记已被别的进程删除\n * (返回 false)则跳过——同一份遗留义务不会被两个进程双跑。\n */\nexport function removeTeardownRegistrationIfPresentEffect(niceevalRoot: string, id: string): Effect.Effect<boolean, unknown> {\n    return claimEntryFileEffect(teardownsDirOf(niceevalRoot), id);\n}\n/**\n * Normal startup scans only persist PID + host, so they cannot prove PID\n * reuse. They still share lease recovery's terminal Linux process states:\n * a Z/X/x task cannot execute cleanup. Any `/proc` read/parse ambiguity is\n * deliberately treated as live here; the explicit recovery path above has\n * stronger immutable identity evidence and fails closed on that ambiguity.\n */\nfunction isPidTerminal(pid: number): boolean {\n    if (process.platform === \"linux\") {\n        try {\n            const raw = readFileSync(`/proc/${pid}/stat`, \"utf8\");\n            const closing = raw.lastIndexOf(\")\");\n            if (closing < 0 || raw[closing + 1] !== \" \")\n                return false;\n            const state = raw.slice(closing + 2).trim().split(/\\s+/u)[0];\n            return state === \"Z\" || state === \"X\" || state === \"x\";\n        }\n        catch (cause) {\n            return errnoCode(cause) === \"ENOENT\";\n        }\n    }\n    try {\n        process.kill(pid, 0);\n        return false;\n    }\n    catch (e) {\n        return (e as NodeJS.ErrnoException).code !== \"EPERM\";\n    }\n}\n/** 遗留义务判定:同宿主且 PID 已缺失或处于终态。pid 存活、读取不明或异宿主可能属于并发 run,不触碰。 */\nexport function isOrphanedTeardownRegistration(entry: TeardownRegistration, currentHost: string): boolean {\n    return entry.host === currentHost && isPidTerminal(entry.pid);\n}\n/**\n * `niceeval exp` 启动提醒:遗留义务里「不在本次选择」的那部分,各给一行 `--teardown` 命令。\n * 在本次选择且仍声明 teardown 的遗留义务由 run.ts 在调度前自动补执行,不出现在这里\n * (见 docs/feature/experiments/architecture.md「强杀后的收尾兜底」)。\n */\nexport function orphanedTeardownReminderEffect(niceevalRoot: string, recoveringExperimentIds: ReadonlySet<string>, currentHost: string): Effect.Effect<string | undefined, unknown> {\n    return readTeardownRegistrationsEffect(niceevalRoot).pipe(Effect.map((registrations) => {\n        const lines: string[] = [];\n        for (const { entry } of registrations) {\n            if (!isOrphanedTeardownRegistration(entry, currentHost))\n                continue;\n            if (recoveringExperimentIds.has(entry.experimentId))\n                continue;\n            lines.push(`unfinished experiment teardown for \"${entry.experimentId}\" from a killed run — niceeval exp ${entry.experimentId} --teardown\\n`);\n        }\n        return lines.length > 0 ? lines.join(\"\") : undefined;\n    }));\n}\n"]}

package/dist/runner/teardown-registry.d.cts

@@ -14,6 +14,32 @@ export declare function teardownEntryId(experimentId: string, pid: number): stri
 export declare function writeTeardownRegistrationEffect(niceevalRoot: string, entry: TeardownRegistration): Effect.Effect<void, unknown>;
 /** 读一条登记项(不存在或损坏都返回 undefined,不抛错)。 */
 export declare function readTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown>;
+/**
+ * Exact recovery cannot treat a malformed or unreadable expected entry as an
+ * absent cleanup obligation. Normal registry scans deliberately tolerate
+ * damaged historical rows; a recovery is instead about to publish a new
+ * sharedState generation, so only a genuinely absent path is safe to accept.
+ */
+export declare function readExactTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown>;
+/** Immutable sharedState owner facts that can prove a registry row is old. */
+export interface ExactTeardownRegistrationOwner {
+    readonly experimentId: string;
+    readonly pid: number;
+    readonly host: string;
+    readonly processIdentity: string;
+}
+/**
+ * Checks the terminal state of the exact owner recorded by a sharedState
+ * generation. On the local host, this uses the same PID + process-identity
+ * probe as lease recovery: ENOENT, PID reuse, and Linux Z/X/x are terminal;
+ * unreadable or malformed probe evidence fails rather than guessing. Remote
+ * termination was already explicitly confirmed by the recovery command.
+ */
+export declare function isExactTeardownRegistrationOwnerTerminatedEffect(input: {
+    readonly registration: TeardownRegistration;
+    readonly owner: ExactTeardownRegistrationOwner;
+    readonly currentHost: string;
+}): Effect.Effect<boolean, unknown>;
 /** 读全部登记项(损坏条目跳过,不整体失败;目录不存在时返回空集合)。 */
 export declare function readTeardownRegistrationsEffect(niceevalRoot: string): Effect.Effect<{
     id: string;
@@ -25,7 +51,7 @@ export declare function readTeardownRegistrationsEffect(niceevalRoot: string): E
  * (返回 false)则跳过——同一份遗留义务不会被两个进程双跑。
  */
 export declare function removeTeardownRegistrationIfPresentEffect(niceevalRoot: string, id: string): Effect.Effect<boolean, unknown>;
-/** 遗留义务判定:同宿主且 pid 不存活。pid 存活或异宿主可能属于并发 run,不触碰。 */
+/** 遗留义务判定:同宿主且 PID 已缺失或处于终态。pid 存活、读取不明或异宿主可能属于并发 run,不触碰。 */
 export declare function isOrphanedTeardownRegistration(entry: TeardownRegistration, currentHost: string): boolean;
 /**
  * `niceeval exp` 启动提醒:遗留义务里「不在本次选择」的那部分,各给一行 `--teardown` 命令。

package/dist/runner/teardown-registry.d.mts

@@ -14,6 +14,32 @@ export declare function teardownEntryId(experimentId: string, pid: number): stri
 export declare function writeTeardownRegistrationEffect(niceevalRoot: string, entry: TeardownRegistration): Effect.Effect<void, unknown>;
 /** 读一条登记项(不存在或损坏都返回 undefined,不抛错)。 */
 export declare function readTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown>;
+/**
+ * Exact recovery cannot treat a malformed or unreadable expected entry as an
+ * absent cleanup obligation. Normal registry scans deliberately tolerate
+ * damaged historical rows; a recovery is instead about to publish a new
+ * sharedState generation, so only a genuinely absent path is safe to accept.
+ */
+export declare function readExactTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown>;
+/** Immutable sharedState owner facts that can prove a registry row is old. */
+export interface ExactTeardownRegistrationOwner {
+    readonly experimentId: string;
+    readonly pid: number;
+    readonly host: string;
+    readonly processIdentity: string;
+}
+/**
+ * Checks the terminal state of the exact owner recorded by a sharedState
+ * generation. On the local host, this uses the same PID + process-identity
+ * probe as lease recovery: ENOENT, PID reuse, and Linux Z/X/x are terminal;
+ * unreadable or malformed probe evidence fails rather than guessing. Remote
+ * termination was already explicitly confirmed by the recovery command.
+ */
+export declare function isExactTeardownRegistrationOwnerTerminatedEffect(input: {
+    readonly registration: TeardownRegistration;
+    readonly owner: ExactTeardownRegistrationOwner;
+    readonly currentHost: string;
+}): Effect.Effect<boolean, unknown>;
 /** 读全部登记项(损坏条目跳过,不整体失败;目录不存在时返回空集合)。 */
 export declare function readTeardownRegistrationsEffect(niceevalRoot: string): Effect.Effect<{
     id: string;
@@ -25,7 +51,7 @@ export declare function readTeardownRegistrationsEffect(niceevalRoot: string): E
  * (返回 false)则跳过——同一份遗留义务不会被两个进程双跑。
  */
 export declare function removeTeardownRegistrationIfPresentEffect(niceevalRoot: string, id: string): Effect.Effect<boolean, unknown>;
-/** 遗留义务判定:同宿主且 pid 不存活。pid 存活或异宿主可能属于并发 run,不触碰。 */
+/** 遗留义务判定:同宿主且 PID 已缺失或处于终态。pid 存活、读取不明或异宿主可能属于并发 run,不触碰。 */
 export declare function isOrphanedTeardownRegistration(entry: TeardownRegistration, currentHost: string): boolean;
 /**
  * `niceeval exp` 启动提醒:遗留义务里「不在本次选择」的那部分,各给一行 `--teardown` 命令。

package/dist/runner/teardown-registry.d.ts

@@ -14,6 +14,32 @@ export declare function teardownEntryId(experimentId: string, pid: number): stri
 export declare function writeTeardownRegistrationEffect(niceevalRoot: string, entry: TeardownRegistration): Effect.Effect<void, unknown>;
 /** 读一条登记项(不存在或损坏都返回 undefined,不抛错)。 */
 export declare function readTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown>;
+/**
+ * Exact recovery cannot treat a malformed or unreadable expected entry as an
+ * absent cleanup obligation. Normal registry scans deliberately tolerate
+ * damaged historical rows; a recovery is instead about to publish a new
+ * sharedState generation, so only a genuinely absent path is safe to accept.
+ */
+export declare function readExactTeardownRegistrationEffect(niceevalRoot: string, experimentId: string, pid: number): Effect.Effect<TeardownRegistration | undefined, unknown>;
+/** Immutable sharedState owner facts that can prove a registry row is old. */
+export interface ExactTeardownRegistrationOwner {
+    readonly experimentId: string;
+    readonly pid: number;
+    readonly host: string;
+    readonly processIdentity: string;
+}
+/**
+ * Checks the terminal state of the exact owner recorded by a sharedState
+ * generation. On the local host, this uses the same PID + process-identity
+ * probe as lease recovery: ENOENT, PID reuse, and Linux Z/X/x are terminal;
+ * unreadable or malformed probe evidence fails rather than guessing. Remote
+ * termination was already explicitly confirmed by the recovery command.
+ */
+export declare function isExactTeardownRegistrationOwnerTerminatedEffect(input: {
+    readonly registration: TeardownRegistration;
+    readonly owner: ExactTeardownRegistrationOwner;
+    readonly currentHost: string;
+}): Effect.Effect<boolean, unknown>;
 /** 读全部登记项(损坏条目跳过,不整体失败;目录不存在时返回空集合)。 */
 export declare function readTeardownRegistrationsEffect(niceevalRoot: string): Effect.Effect<{
     id: string;
@@ -25,7 +51,7 @@ export declare function readTeardownRegistrationsEffect(niceevalRoot: string): E
  * (返回 false)则跳过——同一份遗留义务不会被两个进程双跑。
  */
 export declare function removeTeardownRegistrationIfPresentEffect(niceevalRoot: string, id: string): Effect.Effect<boolean, unknown>;
-/** 遗留义务判定:同宿主且 pid 不存活。pid 存活或异宿主可能属于并发 run,不触碰。 */
+/** 遗留义务判定:同宿主且 PID 已缺失或处于终态。pid 存活、读取不明或异宿主可能属于并发 run,不触碰。 */
 export declare function isOrphanedTeardownRegistration(entry: TeardownRegistration, currentHost: string): boolean;
 /**
  * `niceeval exp` 启动提醒:遗留义务里「不在本次选择」的那部分,各给一行 `--teardown` 命令。

package/dist/runner/teardown-registry.js

@@ -1,20 +1,24 @@
 import { createRequire as __niceevalCreateRequire } from "node:module";
 const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
 const __niceevalCanonical = __niceevalRequire("./teardown-registry.cjs");
-const __niceevalExport0 = __niceevalCanonical["isOrphanedTeardownRegistration"];
-export { __niceevalExport0 as isOrphanedTeardownRegistration };
-const __niceevalExport1 = __niceevalCanonical["orphanedTeardownReminderEffect"];
-export { __niceevalExport1 as orphanedTeardownReminderEffect };
-const __niceevalExport2 = __niceevalCanonical["readTeardownRegistrationEffect"];
-export { __niceevalExport2 as readTeardownRegistrationEffect };
-const __niceevalExport3 = __niceevalCanonical["readTeardownRegistrationsEffect"];
-export { __niceevalExport3 as readTeardownRegistrationsEffect };
-const __niceevalExport4 = __niceevalCanonical["removeTeardownRegistrationIfPresentEffect"];
-export { __niceevalExport4 as removeTeardownRegistrationIfPresentEffect };
-const __niceevalExport5 = __niceevalCanonical["teardownEntryId"];
-export { __niceevalExport5 as teardownEntryId };
-const __niceevalExport6 = __niceevalCanonical["teardownsDirOf"];
-export { __niceevalExport6 as teardownsDirOf };
-const __niceevalExport7 = __niceevalCanonical["writeTeardownRegistrationEffect"];
-export { __niceevalExport7 as writeTeardownRegistrationEffect };
+const __niceevalExport0 = __niceevalCanonical["isExactTeardownRegistrationOwnerTerminatedEffect"];
+export { __niceevalExport0 as isExactTeardownRegistrationOwnerTerminatedEffect };
+const __niceevalExport1 = __niceevalCanonical["isOrphanedTeardownRegistration"];
+export { __niceevalExport1 as isOrphanedTeardownRegistration };
+const __niceevalExport2 = __niceevalCanonical["orphanedTeardownReminderEffect"];
+export { __niceevalExport2 as orphanedTeardownReminderEffect };
+const __niceevalExport3 = __niceevalCanonical["readExactTeardownRegistrationEffect"];
+export { __niceevalExport3 as readExactTeardownRegistrationEffect };
+const __niceevalExport4 = __niceevalCanonical["readTeardownRegistrationEffect"];
+export { __niceevalExport4 as readTeardownRegistrationEffect };
+const __niceevalExport5 = __niceevalCanonical["readTeardownRegistrationsEffect"];
+export { __niceevalExport5 as readTeardownRegistrationsEffect };
+const __niceevalExport6 = __niceevalCanonical["removeTeardownRegistrationIfPresentEffect"];
+export { __niceevalExport6 as removeTeardownRegistrationIfPresentEffect };
+const __niceevalExport7 = __niceevalCanonical["teardownEntryId"];
+export { __niceevalExport7 as teardownEntryId };
+const __niceevalExport8 = __niceevalCanonical["teardownsDirOf"];
+export { __niceevalExport8 as teardownsDirOf };
+const __niceevalExport9 = __niceevalCanonical["writeTeardownRegistrationEffect"];
+export { __niceevalExport9 as writeTeardownRegistrationEffect };
 //# sourceMappingURL=teardown-registry.js.map