@sema-agent/server 7.148.0 → 7.150.0

package/dist/plugins/file-run-store.js

@@ -10,10 +10,10 @@ import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprin
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 import { joinFromStore, splitForStore } from "./wiring-section-codec.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, RUN_STALL_DEFAULT_WIRING, RUN_STALL_VERDICT_UNLANDED_TAG, StoreBootRefusalError, runLivenessOf, buildRunOrphanedError, isTerminalRunStatus, settledLegObservationOf } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, RUN_STALL_DEFAULT_WIRING, RUN_STALL_VERDICT_UNLANDED_TAG, StoreBootRefusalError, mintRunLegId, runLivenessOf, buildRunOrphanedError, isTerminalRunStatus, settledLegObservationOf } from "./store-contracts.js";
 import { buildSessionRunRollups } from "./session-run-rollup.js";
 import { normalizedRunPreviewM45 } from "./run-preview-m45.js";
-import { SHELL_SENTINEL_OWNER_M48 } from "./shell-sentinel-owner-m48.js";
+import { isShellSentinelOwnerM48 } from "./shell-sentinel-owner-m48.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
 import { readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 import { createInProcessSpaceCommitTable, fenceSpaceCommitAtTerminal, SPACE_COMMIT_RECORD_SCHEMA } from "../workspace-space-commit.js";
@@ -174,6 +174,7 @@ export class FileRunStore {
         return {
             ...rest,
             result: d.result ?? null,
+            legId: typeof d.legId === "string" ? d.legId : null,
             idemKey: typeof d.idemKey === "string" ? d.idemKey : null,
             idemBodyFingerprint: typeof d.idemBodyFingerprint === "string" ? d.idemBodyFingerprint : null,
             identity: readRunIdentityCells(identitySource, identityScope, identityPrincipalInc),
@@ -198,6 +199,7 @@ export class FileRunStore {
             source: r.source,
             identity: r.identity,
             instanceId: r.instanceId,
+            legId: r.legId,
             cancelRequested: r.cancelRequested,
             objectivePreview: r.objectivePreview,
             createdAt: r.createdAt.toISOString(),
@@ -421,6 +423,7 @@ export class FileRunStore {
         }
         this.active.set(sessionId, taskId);
         const now = new Date();
+        const legId = mintRunLegId();
         try {
             this.persist({
                 taskId,
@@ -433,6 +436,7 @@ export class FileRunStore {
                 jobId: meta.jobId ?? null,
                 source: meta.source ?? null,
                 instanceId,
+                legId,
                 objectivePreview: meta.objectivePreview ?? null,
                 idemKey,
                 idemBodyFingerprint: meta.idem?.bodyFingerprint ?? null,
@@ -449,7 +453,7 @@ export class FileRunStore {
         }
         if (idemKey !== null)
             this.byIdem.set(idemKey, taskId);
-        return { ok: true };
+        return { ok: true, legId };
     }
     async fillObjectivePreview(taskId, preview) {
         const r = this.runs.get(taskId);
@@ -606,35 +610,39 @@ export class FileRunStore {
             notifyRunTerminal(pending);
         return fenced;
     }
-    async setSuspended(taskId, result) {
+    async setSuspended(taskId, result, legId) {
         const sealed = sealRunRowResult(result);
         const r = this.runs.get(taskId);
-        if (r && (r.status === "running" || r.status === "suspended")) {
-            this.persist({ ...r, status: "suspended", result: sealed, errorCode: runRowErrorCodeOf(sealed), updatedAt: new Date() });
-        }
+        if (!r || r.legId !== legId || (r.status !== "running" && r.status !== "suspended") || r.cancelRequested)
+            return false;
+        this.persist({ ...r, status: "suspended", result: sealed, errorCode: runRowErrorCodeOf(sealed), updatedAt: new Date() });
+        return true;
     }
-    async setNeedsReview(taskId, result) {
+    async setNeedsReview(taskId, result, legId) {
         const sealed = sealRunRowResult(result);
         const r = this.runs.get(taskId);
-        if (r && (r.status === "running" || r.status === "needs_review")) {
-            this.persist({ ...r, status: "needs_review", result: sealed, errorCode: runRowErrorCodeOf(sealed), updatedAt: new Date() });
-        }
+        if (!r || r.legId !== legId || (r.status !== "running" && r.status !== "needs_review") || r.cancelRequested)
+            return false;
+        this.persist({ ...r, status: "needs_review", result: sealed, errorCode: runRowErrorCodeOf(sealed), updatedAt: new Date() });
+        return true;
     }
     async markResuming(taskId, instanceId) {
         const r = this.runs.get(taskId);
         if (!r || (r.status !== "suspended" && r.status !== "needs_review"))
-            return false;
+            return undefined;
+        const legId = mintRunLegId();
         this.persist({
             ...r,
             status: "running",
             result: null,
             errorCode: null,
             instanceId,
+            legId,
             cancelRequested: false,
             preemptRequested: false,
             updatedAt: new Date(),
         });
-        return true;
+        return legId;
     }
     async getActiveTaskId(sessionId) {
         return this.active.get(sessionId);
@@ -644,7 +652,7 @@ export class FileRunStore {
         if (this.active.get(sessionId) !== taskId || r === undefined || r.status !== "running")
             return false;
         this.persist({ ...r, updatedAt: new Date() });
-        write({ instanceId: r.instanceId });
+        write({ instanceId: r.instanceId, legId: r.legId });
         return true;
     }
     async getRun(taskId) {
@@ -653,13 +661,31 @@ export class FileRunStore {
     }
     async releaseIdemKey(taskId) {
         const r = this.runs.get(taskId);
-        if (!r || (r.idemKey === null && r.idemBodyFingerprint === null))
+        if (r)
+            this.dropIdemBinding(r);
+    }
+    dropIdemBinding(r) {
+        if (r.idemKey === null && r.idemBodyFingerprint === null)
             return;
         const key = r.idemKey;
         this.persist({ ...r, idemKey: null, idemBodyFingerprint: null });
-        if (key !== null && this.byIdem.get(key) === taskId)
+        if (key !== null && this.byIdem.get(key) === r.taskId)
             this.byIdem.delete(key);
     }
+    async withdrawMintedRun(taskId, legId) {
+        const r = this.runs.get(taskId);
+        if (r === undefined || r.legId !== legId)
+            return false;
+        if (r.status !== "running") {
+            if (isTerminalRunStatus(r.status))
+                this.dropIdemBinding(r);
+            return false;
+        }
+        this.dropRun(taskId);
+        if (this.active.get(r.sessionId) === taskId)
+            this.releaseClaim(r.sessionId);
+        return true;
+    }
     async bindIdemBodyFingerprint(taskId, idem) {
         const r = this.runs.get(taskId);
         if (!r || r.idemKey !== idem.key)
@@ -1146,14 +1172,16 @@ export class FileRunStore {
         return migrated;
     }
     clearShellSentinelOwnersM48() {
-        let cleared = 0;
-        for (const r of this.runs.values()) {
-            if (r.owner !== SHELL_SENTINEL_OWNER_M48)
-                continue;
+        const hits = this.shellSentinelRunsM48();
+        for (const r of hits)
             this.persist({ ...r, owner: null });
-            cleared += 1;
-        }
-        return cleared;
+        return hits.length;
+    }
+    countShellSentinelOwnersM48() {
+        return this.shellSentinelRunsM48().length;
+    }
+    shellSentinelRunsM48() {
+        return [...this.runs.values()].filter((r) => isShellSentinelOwnerM48(r.owner));
     }
     sessionIdsWithRuns() {
         return new Set([...this.runs.values()].map((r) => r.sessionId));

package/dist/plugins/local-checkpoint-store.d.ts

@@ -1,4 +1,4 @@
-import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ExecutionOutcomeRecordWord, type GateOutcome, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointPage, type CheckpointRowRead, type CheckpointSessionCursor, type CheckpointSessionQuery, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ExecutionOutcomeRecordWord, type GateOutcome, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
 import { type CheckpointAskCandidate, type CtxClaimPut, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type ExpiredApprovalGate, type ExpiredGatePosition, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-face.js";
 import { type CtxWriteClaim } from "./store-contracts.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
@@ -9,6 +9,8 @@ import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
  */
 export declare function dropLocalCheckpointCtxStrict(root: string, sessionId: string): void;
 export interface LocalCheckpointStoreOptions {
+    /** 本店对引擎的耐久声明(装配方给 —— local 后端递 `localStoreDeclarationOf` 那一份,与会话店同读:两半一起)。缺席 ⇒ 内核的读数 `"durable"`(见字段注)。 */
+    durability?: StoreDurability;
     /** 会话认领联结(the local FileRunStore's `getActiveTaskId`)—— 停驻行 `taskId` 的第二格读数([ref],写者 `parkedLegTaskId`)。Absent ⇒ 只剩行上的记录。 */
     getActiveTaskId?: (sessionId: string) => Promise<string | undefined>;
     /** E21 owner guard (the LocalSessionStore's owner read, `headOf(id)?.owner`: `undefined` = no session row). Absent ⇒ owner guard degrades
@@ -31,6 +33,8 @@ export declare class LocalCheckpointStore {
      *
      * 它与「session store 的 local 形声明 durable 就拒启」不矛盾:那条判据管的是**声明 vs 介质**,而这里
      * 的介质就是盘。真正的 process-local 形(`InMemoryCheckpointStore`)由 core 自己声明 `"process-local"`。
+     * 装配方给了声明就用它(local 后端递 `localStoreDeclarationOf` 那一份 —— 运维声明易失 / 调用方自己那块易失盘 ⇒ 与会话店一起降为 `"process-local"`:
+     * 进程重启照旧活过,容器替换不保留;只降一半会让引擎的 durable-park 自检读出缺口)。
      */
     readonly durability: StoreDurability;
     /**
@@ -114,6 +118,9 @@ export declare class LocalCheckpointStore {
     expire(token: CheckpointToken, scope: string): Promise<boolean>;
     reap(scope: string, cutoff: number): Promise<number>;
     listByScope(scope: string): Promise<CheckpointSummary[]>;
+    /** core `CheckpointStore.listBySession`(可选动词,按在不在探):纯委派给内核 —— 读法是 core 的 `selectSessionPage`(SQL 孪生把「这只会话的行」交给同一只);
+     *  内核读的是它自己的全部行(任何状态),坏行由内核按行答 `unreadable`、经数据根那只披露座说。包装层不另判、不另列。 */
+    listBySession(query: CheckpointSessionQuery): Promise<CheckpointPage<CheckpointRowRead, CheckpointSessionCursor>>;
     close(): void;
     /** C4-B:注册表损坏时从**数据本体**懒重建 scope 集(core 1.424 `listScopes?` = 「有 ≥1 条 pending 的
      *  distinct scope 集」,与 listByScope 可见面对齐 —— 恰好是本注册表要的内容)。一次性:重建后回写

package/dist/plugins/local-checkpoint-store.js

@@ -94,7 +94,7 @@ export function localCheckpointStoreDirsFor(root) {
 }
 export class LocalCheckpointStore {
     retention = UNMANAGED_RETENTION;
-    durability = "durable";
+    durability;
     fidelity = "json";
     execution = { outcome: true };
     inner;
@@ -110,6 +110,7 @@ export class LocalCheckpointStore {
     opts;
     constructor(root, opts = {}) {
         this.inner = new FileCheckpointStore(root);
+        this.durability = opts.durability ?? this.inner.durability;
         this.opts = opts;
         this.scopesPath = join(root, "checkpoint-scopes.json");
         this.sessionTokensPath = join(root, "checkpoint-session-tokens.json");
@@ -226,6 +227,9 @@ export class LocalCheckpointStore {
     listByScope(scope) {
         return this.inner.listByScope(scope);
     }
+    listBySession(query) {
+        return this.inner.listBySession(query);
+    }
     close() {
         this.inner.close();
     }

package/dist/plugins/local-data-root-admission.d.ts

@@ -0,0 +1,52 @@
+import { type EngineHighWaterReading } from "./local-engine-high-water.js";
+import { type ArchiveTokenAdoptionDutyAction, type DataRootFileText } from "./local-session-store.js";
+import { type SkillExemptionCutoffAction } from "./approval-exemption-skill-cutoff.js";
+import { type ReleaseTriple } from "./release-version.js";
+/** 准入的一次观察(纯数据;判的全部输入)—— 锁内逐项比的那一份。读不出的输入在判里已拒,所以存下来的观察里只有「缺席 / 字节」两态。 */
+export interface LocalDataRootObservation {
+    readonly marker: DataRootFileText;
+    /** 严格边档清册的字节(按清册次序)。 */
+    readonly strictSidecars: readonly DataRootFileText[];
+    /** 存档目录里的会话 id(目录不在 ⇒ 空)。 */
+    readonly archiveIds: readonly string[];
+    /** 收令牌欠账标记在不在。 */
+    readonly adoptionPending: boolean;
+    /** `Skill` 豁免截点文件的字节。 */
+    readonly skillCutoff: DataRootFileText;
+    /** 会话豁免日志目录的指纹(`exemptionLogFingerprints`);`null` = 没读:本构建还带 M46,截点之前的行归它删,判不读日志。 */
+    readonly exemptionLogs: readonly string[] | null;
+}
+/** 准入的读数(纯数据;唯一铸点 {@link admitLocalDataRoot},唯一消费者 {@link holdLocalDataRootAdmission})。 */
+export interface LocalDataRootAdmission {
+    /** 判的是哪只根:物理路径(core 打开它的同一读法);`undefined` = 准入时数据根上什么都没有(还不存在 / 不是目录 / 空目录)。 */
+    readonly root: string | undefined;
+    /** 判的输入(锁内逐项比)。 */
+    readonly observed: LocalDataRootObservation;
+    /** 引擎高水位的读数(抬的依据)。 */
+    readonly highWater: EngineHighWaterReading;
+    /** 跳版臂要在锁内、抬之前做的动作。 */
+    readonly archiveDuty: ArchiveTokenAdoptionDutyAction;
+    /** `Skill` 豁免截点要在锁内、抬之前做的动作(缺席 ⇒ 落)。 */
+    readonly skillCutoff: SkillExemptionCutoffAction;
+}
+/**
+ * **准入**(只读;拒 = 抛 —— 拒句是 `LocalDataRootSchemaMismatchError` 的 `boot` 形,或本构建版本读不出的那一只 `StoreBootRefusalError`;
+ * 判不了的 I/O 故障如存档目录读不了原样抛 = 不放行)。`engine` 缺席 = 本构建(`serviceVersion()`)。
+ * 数据根上什么都没有(不存在 / 不是目录 / 空目录 —— {@link localDataRootHoldsData},与起服降级臂同一读法)⇒ 没有可判的,按缺席放行(首启;只判本构建发布线);
+ * 建不建得出根是打开那一步的事(显式 local 拒句点名「打不开数据根」,缺省推导的 local 走降级臂)—— 准入不把「根还不存在」读成「marker 读不出」。
+ */
+export declare function admitLocalDataRoot(root: string, engine?: string): LocalDataRootAdmission;
+/**
+ * **判 `Skill` 豁免截点**(律见 `approval-exemption-skill-cutoff.ts`;唯一调用点 = {@link admitLocalDataRoot},判的是准入那一次观察里的截点文件字节):
+ *  · 截点文件读不出(I/O / 正文不是时刻)⇒ 拒(读不出的那一形)—— 带不带 M46 都判(fail-closed 律:读不出的截点不猜);
+ *  · `carried`(本构建还带 M46)⇒ 不读日志、不因行拒:截点缺席 ⇒ `lay`(锁内先落,M46 读它删截点之前的行),否则 `none`;
+ *  · 不带 ⇒ 首次放行早于截点(截点缺席 ⇒ 任一)的 `Skill` 行所在的会话 > 0 ⇒ 拒(`skipped-required-migration`,
+ *    出路版本不低于 {@link SKILL_EXEMPTION_CUTOFF_SINCE} 与已记高水位);都没有 ⇒ 截点缺席则 `lay`。拒在准入里 ⇒ 数据根零写、高水位不抬 ⇒ 拒句点名的那一版仍开得了这只根。
+ */
+export declare function judgeLocalSkillExemptionCutoff(root: string, raw: DataRootFileText, priorHighWater: ReleaseTriple | undefined, carried: boolean): SkillExemptionCutoffAction;
+/**
+ * **锁内一步**(唯一调用点 = `openLocalBackend`:数据根锁在手之后、本仓任何一只店建起之前):核数据根没动(物理路径是准入那一只、再观察一次与准入那一次逐项相同)
+ * → 做跳版臂的动作 → 落 `Skill` 豁免截点(缺席才落)→ 抬。任一步抛 ⇒ 不抬、不建店(调用方交回拒后端,只放锁)。
+ */
+export declare function holdLocalDataRootAdmission(physicalRoot: string, admission: LocalDataRootAdmission): void;
+//# sourceMappingURL=local-data-root-admission.d.ts.map

package/dist/plugins/local-data-root-admission.js

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import { physicalPathOf } from "@sema-agent/core";
+import { serviceVersion } from "../service-version.js";
+import { localDataRootHoldsData } from "../store-posture.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { engineHighWaterPath, judgeEngineHighWater, ownReleaseLine, raiseEngineHighWater } from "./local-engine-high-water.js";
+import { archiveIdsInSync, archiveTokenAdoptionPendingPresent, judgeArchiveTokenAdoptionDuty, judgeStrictSidecars, readDataRootFileTextSync, readStrictSidecarTextsSync, settleArchiveTokenAdoptionDuty, dataRootMismatchOf, LocalDataRootSchemaMismatchError, } from "./local-session-store.js";
+import { LOCAL_SKILL_EXEMPTION_CUTOFF_FILE, SKILL_EXEMPTION_CUTOFF_SINCE, exemptionLogFingerprints, localSkillExemptionSessionsBefore, settleLocalSkillExemptionCutoff, skillExemptionCutoffOfText, } from "./approval-exemption-skill-cutoff.js";
+import { APPROVAL_EXEMPTION_DIR } from "./approval-exemption-store.js";
+import { SKILL_EXEMPTION_CUTOFF_ID } from "./one-time-migration-marker.js";
+import { migrationCarried } from "./one-time-migrations.js";
+import { releaseText } from "./release-version.js";
+const ABSENT = { state: "absent" };
+const EMPTY_OBSERVATION = Object.freeze({ marker: ABSENT, strictSidecars: [], archiveIds: [], adoptionPending: false, skillCutoff: ABSENT, exemptionLogs: [] });
+function observeLocalDataRoot(root, exemptionLogs) {
+    return {
+        marker: readDataRootFileTextSync(engineHighWaterPath(root)),
+        strictSidecars: readStrictSidecarTextsSync(root),
+        archiveIds: archiveIdsInSync(root),
+        adoptionPending: archiveTokenAdoptionPendingPresent(root),
+        skillCutoff: readDataRootFileTextSync(join(root, LOCAL_SKILL_EXEMPTION_CUTOFF_FILE)),
+        exemptionLogs: exemptionLogs ? exemptionLogFingerprints(root) : null,
+    };
+}
+const textOf = (r) => (r.state === "text" ? r.text : r.state === "absent" ? undefined : null);
+function movedInput(admitted, now) {
+    if (textOf(admitted.marker) !== textOf(now.marker))
+        return "the engine high-water marker";
+    const sidecars = Math.max(admitted.strictSidecars.length, now.strictSidecars.length);
+    for (let i = 0; i < sidecars; i++) {
+        if (textOf(admitted.strictSidecars[i] ?? ABSENT) !== textOf(now.strictSidecars[i] ?? ABSENT))
+            return "a strict sidecar (session-meta)";
+    }
+    if (admitted.archiveIds.join("\n") !== now.archiveIds.join("\n"))
+        return "the session archive directory";
+    if (admitted.adoptionPending !== now.adoptionPending)
+        return "the archive-token adoption record";
+    if (textOf(admitted.skillCutoff) !== textOf(now.skillCutoff))
+        return "the Skill exemption cutoff";
+    if ((admitted.exemptionLogs ?? []).join("\n") !== (now.exemptionLogs ?? []).join("\n"))
+        return "the session approval exemption logs";
+    return undefined;
+}
+export function admitLocalDataRoot(root, engine = serviceVersion()) {
+    const given = root.normalize("NFC");
+    if (!localDataRootHoldsData(given)) {
+        return Object.freeze({ root: undefined, observed: EMPTY_OBSERVATION, highWater: { own: ownReleaseLine(given, engine), prior: undefined }, archiveDuty: "none", skillCutoff: "lay" });
+    }
+    const carried = migrationCarried(SKILL_EXEMPTION_CUTOFF_ID);
+    const physical = physicalPathOf(given);
+    const observed = observeLocalDataRoot(physical, !carried);
+    const highWater = judgeEngineHighWater(physical, observed.marker, engine);
+    const cells = judgeStrictSidecars(physical, observed.strictSidecars);
+    const archiveDuty = judgeArchiveTokenAdoptionDuty(physical, highWater.prior, migrationCarried("M47"), { cells, archiveIds: observed.archiveIds, adoptionPending: observed.adoptionPending });
+    const skillCutoff = judgeLocalSkillExemptionCutoff(physical, observed.skillCutoff, highWater.prior, carried);
+    return Object.freeze({ root: physical, observed, highWater, archiveDuty, skillCutoff });
+}
+export function judgeLocalSkillExemptionCutoff(root, raw, priorHighWater, carried) {
+    const path = join(root, LOCAL_SKILL_EXEMPTION_CUTOFF_FILE);
+    const label = `${LOCAL_SKILL_EXEMPTION_CUTOFF_FILE} (the local Skill exemption cutoff)`;
+    if (raw.state === "unreadable")
+        throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, label, raw.fault)], "boot");
+    const cutoffMs = raw.state === "text" ? skillExemptionCutoffOfText(raw.text) : undefined;
+    if (raw.state === "text" && cutoffMs === undefined)
+        throw new LocalDataRootSchemaMismatchError([{ path, label, problem: "malformed", unknownFields: [] }], "boot");
+    if (carried)
+        return cutoffMs === undefined ? "lay" : "none";
+    const sessions = localSkillExemptionSessionsBefore(root, cutoffMs);
+    if (sessions > 0) {
+        throw new LocalDataRootSchemaMismatchError([
+            {
+                path: join(root, APPROVAL_EXEMPTION_DIR),
+                label: `${APPROVAL_EXEMPTION_DIR} (the local session approval exemptions)`,
+                problem: "skipped-required-migration",
+                unknownFields: [],
+                skippedMigration: {
+                    residue: "pre-cutoff-skill-exemptions",
+                    highWater: priorHighWater === undefined ? null : releaseText(priorHighWater),
+                    requiredSince: SKILL_EXEMPTION_CUTOFF_SINCE,
+                    sessions,
+                    cutoff: cutoffMs === undefined ? null : new Date(cutoffMs).toISOString(),
+                },
+            },
+        ], "boot");
+    }
+    return cutoffMs === undefined ? "lay" : "none";
+}
+export function holdLocalDataRootAdmission(physicalRoot, admission) {
+    const moved = admission.root !== undefined && admission.root !== physicalRoot
+        ? "the data root's physical path"
+        : movedInput(admission.observed, observeLocalDataRoot(physicalRoot, admission.observed.exemptionLogs !== null));
+    if (moved !== undefined) {
+        throw new StoreBootRefusalError(`DB_BACKEND=local: ${moved} under ${physicalRoot} changed between this start's data-root admission and taking the data-root lock — another engine opened this data root meanwhile; ` +
+            "refusing to open it on a stale reading. Restart: the next start judges the data root as it is then.");
+    }
+    settleArchiveTokenAdoptionDuty(physicalRoot, admission.highWater.prior, admission.archiveDuty);
+    settleLocalSkillExemptionCutoff(physicalRoot, admission.skillCutoff);
+    raiseEngineHighWater(physicalRoot, admission.highWater);
+}
+//# sourceMappingURL=local-data-root-admission.js.map

package/dist/plugins/local-engine-high-water.d.ts

@@ -1,13 +1,34 @@
+import { type DataRootFileText } from "./local-session-store.js";
 import { type ReleaseTriple } from "./release-version.js";
 /** marker 的文件名(数据根顶层;公开契约)。 */
 export declare const ENGINE_HIGH_WATER_FILE = "engine-high-water.json";
 /**
- * **判与抬**(唯一的座;唯一调用点 `openLocalBackend`,数据根锁在手、本仓任何一只店建起之前):
- *  ① 本构建版本 `engine` 按发布线读不出({@link buildReleaseTriple})⇒ 抛 {@link StoreBootRefusalError}(marker 不读、不写);
- *  ② 读 `<root>/engine-high-water.json`:读不出 / 高水位高于本构建 ⇒ 抛 {@link LocalDataRootSchemaMismatchError}(`boot` 形;文件原地不动,不抬);
- *  ③ 判前钩 `judgePrior`(在场时)以打开之前的高水位(缺席 ⇒ `undefined`)调一次(它可以在判过之后写调用方自己的事实 —— 先于抬);它抛 ⇒ 原样上抛、不抬;
- *  ④ 缺席或低于本构建 ⇒ 原子写 `{"highWater": <本构建的纯三段>}`(`required`);相等 ⇒ 不写,只过持久化屏障(读到的可能是上一次没证完的那份)。写不进 / 证不了 ⇒ 抛(点名路径与原因)。
- * 同步:它在后端打开的同步段里跑(建店之前),拒在这里就不会有一只店被建起。
+ * 准入判出的高水位(**读数**,不是活物):{@link raiseEngineHighWater} 按它抬。唯一的铸点 = {@link judgeEngineHighWater} / 空根那一格的 {@link ownReleaseLine}
+ * (都在数据根准入 `local-data-root-admission.ts` 的 `admitLocalDataRoot` 里)。
  */
-export declare function holdEngineHighWater(root: string, engine: string, judgePrior?: (prior: ReleaseTriple | undefined) => void): void;
+export interface EngineHighWaterReading {
+    /** 本构建的发布线(纯三段;判与抬都按它)。 */
+    readonly own: ReleaseTriple;
+    /** marker 记的高水位(缺席 = `undefined`);跳版拒启臂读它。 */
+    readonly prior: ReleaseTriple | undefined;
+}
+/**
+ * 本构建的发布线(判与抬都按它):`engine` 按发布线读不出({@link buildReleaseTriple})⇒ 抛 {@link StoreBootRefusalError} —— 判不了「不比打开过这只根的引擎旧」,
+ * 也写不出自己的水位(坏包,不服务这只根;数据根上有没有东西都一样拒)。
+ */
+export declare function ownReleaseLine(root: string, engine: string): ReleaseTriple;
+/** marker 在一只(物理)数据根下的路径。 */
+export declare function engineHighWaterPath(root: string): string;
+/**
+ * **判**(纯;唯一调用点 = 数据根准入:判的是准入那一次观察里 marker 的字节 `raw`,不自己读盘):
+ *  ① 本构建版本按发布线读不出 ⇒ 抛({@link ownReleaseLine});
+ *  ② marker 读不出 / 高水位高于本构建 ⇒ 抛 {@link LocalDataRootSchemaMismatchError}(`boot` 形);
+ *  ③ 否则交回读数(缺席 / 低于 / 等于)。
+ */
+export declare function judgeEngineHighWater(root: string, raw: DataRootFileText, engine: string): EngineHighWaterReading;
+/**
+ * **抬**(锁内;紧随准入的「数据根没动」核对与跳版臂的记账之后、本仓任何一只店建起之前):缺席或低于本构建 ⇒ 原子写 `{"highWater": <本构建的纯三段>}`(`required`);
+ * 相等 ⇒ 不写,只过持久化屏障(读到的可能是上一次没证完的那份)。写不进 / 证不了 ⇒ 抛(点名路径与原因)。
+ */
+export declare function raiseEngineHighWater(physicalRoot: string, admitted: EngineHighWaterReading): void;
 //# sourceMappingURL=local-engine-high-water.d.ts.map

package/dist/plugins/local-engine-high-water.js

@@ -2,7 +2,7 @@ import { join, resolve } from "node:path";
 import { z } from "zod";
 import { atomicWriteFileSync, proveDurableSync } from "./owner-only-file-mode.js";
 import { createZodColumnReader, decodeJsonColumn } from "./sql-json-column.js";
-import { LocalDataRootSchemaMismatchError, dataRootMismatchOf, readDataRootFileTextSync } from "./local-session-store.js";
+import { LocalDataRootSchemaMismatchError, dataRootMismatchOf } from "./local-session-store.js";
 import { buildReleaseTriple, compareReleaseTriples, releaseText, releaseTriple } from "./release-version.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 export const ENGINE_HIGH_WATER_FILE = "engine-high-water.json";
@@ -19,40 +19,45 @@ const ENGINE_HIGH_WATER_SHAPE = z
     return { highWater: v.highWater, triple };
 });
 const readEngineHighWater = createZodColumnReader(ENGINE_HIGH_WATER_SHAPE);
-export function holdEngineHighWater(root, engine, judgePrior) {
+export function ownReleaseLine(root, engine) {
     const own = buildReleaseTriple(engine);
     if (own === undefined) {
         throw new StoreBootRefusalError(`DB_BACKEND=local: this build's own version (package.json "version": ${JSON.stringify(engine.slice(0, 64))}) is not a release version (x.y.z, optionally with a prerelease or build suffix) — refusing to open the data root ${root}: ` +
             "the engine high-water fence needs this build's release line to show it is not older than the engines that opened this data root, and to record its own. " +
             "Run a build whose package.json carries a release version.");
     }
-    const path = resolve(join(root, ENGINE_HIGH_WATER_FILE));
-    const raw = readDataRootFileTextSync(path);
-    let equal = false;
-    let prior;
+    return own;
+}
+export function engineHighWaterPath(root) {
+    return resolve(join(root, ENGINE_HIGH_WATER_FILE));
+}
+export function judgeEngineHighWater(root, raw, engine) {
+    const own = ownReleaseLine(root, engine);
+    const path = engineHighWaterPath(root);
     if (raw.state === "unreadable")
         throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, ENGINE_HIGH_WATER_LABEL, raw.fault)], "boot");
-    if (raw.state === "text") {
-        let marker;
-        try {
-            marker = decodeJsonColumn(raw.text, readEngineHighWater, ENGINE_HIGH_WATER_LABEL);
-        }
-        catch (e) {
-            throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, ENGINE_HIGH_WATER_LABEL, e)], "boot");
-        }
-        const order = compareReleaseTriples(marker.triple, own);
-        if (order > 0) {
-            throw new LocalDataRootSchemaMismatchError([{ path, label: ENGINE_HIGH_WATER_LABEL, problem: "newer-engine", unknownFields: [], engineHighWater: { highWater: marker.highWater, engine } }], "boot");
-        }
-        equal = order === 0;
-        prior = marker.triple;
+    if (raw.state === "absent")
+        return { own, prior: undefined };
+    let marker;
+    try {
+        marker = decodeJsonColumn(raw.text, readEngineHighWater, ENGINE_HIGH_WATER_LABEL);
     }
-    judgePrior?.(prior);
+    catch (e) {
+        throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, ENGINE_HIGH_WATER_LABEL, e)], "boot");
+    }
+    if (compareReleaseTriples(marker.triple, own) > 0) {
+        throw new LocalDataRootSchemaMismatchError([{ path, label: ENGINE_HIGH_WATER_LABEL, problem: "newer-engine", unknownFields: [], engineHighWater: { highWater: marker.highWater, engine } }], "boot");
+    }
+    return { own, prior: marker.triple };
+}
+export function raiseEngineHighWater(physicalRoot, admitted) {
+    const path = engineHighWaterPath(physicalRoot);
+    const equal = admitted.prior !== undefined && compareReleaseTriples(admitted.prior, admitted.own) === 0;
     try {
         if (equal)
             proveDurableSync(path);
         else
-            atomicWriteFileSync(path, `${JSON.stringify({ highWater: releaseText(own) })}\n`, { durability: "required" });
+            atomicWriteFileSync(path, `${JSON.stringify({ highWater: releaseText(admitted.own) })}\n`, { durability: "required" });
     }
     catch (e) {
         throw new Error(`DB_BACKEND=local cannot record the engine high-water ${path} durably: ${e instanceof Error ? e.message : String(e)} — refusing to open the data root: ` +