@sema-agent/server 7.147.0 → 7.149.0

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

@@ -1,24 +1,66 @@
+import { writeLogText } from "../observability/logger.js";
 import { z } from "zod";
 import { denySweepOwns, parkedApprovalCard } from "../approval-content-kind.js";
 import { parkRowFacts, skillCardFacts } from "../approval-card.js";
 import { durableRowIdentity } from "../checkpoint-identity.js";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { IS_WIN32 } from "./host-platform.js";
 import { join } from "node:path";
-import { CHECKPOINT_LIST_LIMITS, FileCheckpointStore, atomicWriteFile, ensureDir, executionVerdict, sanitizePathComponent, } from "@sema-agent/core";
+import { CHECKPOINT_LIST_LIMITS, FileCheckpointStore, atomicWriteFile, checkpointDeadlinePassed, ensureDir, executionVerdict, sanitizePathComponent, } from "@sema-agent/core";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
-import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, pendingRowPrecedes, queueRowGateKind, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-face.js";
+import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DENY_SWEEP_PAGE_ROWS, isUnreadableSummaryForm, parkedLegTaskId, pendingRowPrecedes, queueRowGateKind, queueTriageOrder, readRiskDescriptorBody, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, } from "./checkpoint-store-face.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
-import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, readStringArrayColumn } from "./sql-json-column.js";
+import { hostSessionOf } from "./checkpoint-index-columns.js";
+import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, isJsonObject, readStringArrayColumn } from "./sql-json-column.js";
 import { UNMANAGED_RETENTION } from "./retention-declaration.js";
 import { assertJsonColumnWritable, createObjectColumnReader } from "./sql-json-column.js";
 import { FENCE_LANDED } from "./store-contracts.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+const isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
 function terminalAtOf(cp) {
-    return Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS);
+    const createdAt = cp.createdAt;
+    const deadline = cp.deadline;
+    const deadlineTerm = deadline === undefined ? 0 : isFiniteNumber(deadline) ? deadline : undefined;
+    if (!isFiniteNumber(createdAt) || deadlineTerm === undefined)
+        return -Infinity;
+    return Math.max(createdAt + TERMINAL_BACKSTOP_MS, deadlineTerm + TERMINAL_GRACE_MS);
+}
+function sweepDeadlineKey(deadline) {
+    return isFiniteNumber(deadline) ? deadline : -Infinity;
+}
+function sweepPositionPrecedes(a, b) {
+    return a.deadline < b.deadline || (a.deadline === b.deadline && a.token < b.token);
+}
+function queueRiskDescriptorOf(gate) {
+    const raw = isJsonObject(gate) ? gate.riskDescriptor : undefined;
+    if (raw === undefined || raw === null)
+        return null;
+    const shape = readRiskDescriptorBody(raw);
+    if (shape.problem === undefined)
+        return shape.value;
+    recordFailOpen("server.approvals.risk-descriptor-cell-unreadable");
+    return null;
 }
 function ctxFileOf(sessionId) {
     return `${sanitizePathComponent(sessionId).slice(0, 48)}-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}.json`;
 }
+export function dropLocalCheckpointCtxStrict(root, sessionId) {
+    const dir = localCheckpointStoreDirsFor(root).ctx;
+    const path = join(dir, ctxFileOf(sessionId));
+    if (!existsSync(path))
+        return;
+    rmSync(path, { force: true });
+    if (IS_WIN32)
+        return;
+    const fd = openSync(dir, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 const CtxRecordSchema = z.object({
     sessionId: z.string(),
     updatedAt: z.number(),
@@ -52,7 +94,7 @@ export function localCheckpointStoreDirsFor(root) {
 }
 export class LocalCheckpointStore {
     retention = UNMANAGED_RETENTION;
-    durability = "durable";
+    durability;
     fidelity = "json";
     execution = { outcome: true };
     inner;
@@ -62,12 +104,17 @@ export class LocalCheckpointStore {
     tmpDir;
     scopes = new Set();
     sessionTokens = new Map();
+    hostTokens = new Map();
+    hostOfToken = new Map();
+    hostSessionsPath;
     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");
+        this.hostSessionsPath = join(root, "checkpoint-host-sessions.json");
         const dirs = localCheckpointStoreDirsFor(root);
         this.ctxDir = dirs.ctx;
         this.tmpDir = dirs.tmp;
@@ -81,7 +128,7 @@ export class LocalCheckpointStore {
             catch (e) {
                 quarantineUnreadableSidecar(this.scopesPath, "LocalCheckpointStore scope registry", e instanceof Error ? e.message : String(e));
                 this.scopeRegistryCorrupt = true;
-                console.warn("LocalCheckpointStore: will rebuild the scope set from the data plane on first read (core listScopes) — enumeration is EMPTY until then");
+                writeLogText("stderr", "LocalCheckpointStore: will rebuild the scope set from the data plane on first read (core listScopes) — enumeration is EMPTY until then");
             }
         }
         if (existsSync(this.sessionTokensPath)) {
@@ -94,21 +141,66 @@ export class LocalCheckpointStore {
                 quarantineUnreadableSidecar(this.sessionTokensPath, "LocalCheckpointStore session→tokens index", e instanceof Error ? e.message : String(e));
             }
         }
+        if (existsSync(this.hostSessionsPath)) {
+            for (const [host, toks] of Object.entries(decodeJsonColumn(readFileSync(this.hostSessionsPath, "utf8"), readSessionTokenIndex, "checkpoint-host-sessions.json (the local card→host-session index)"))) {
+                this.indexHost(host, toks);
+            }
+        }
+    }
+    registerDurably(record, undo, persist) {
+        if (!record())
+            return;
+        try {
+            persist();
+        }
+        catch (e) {
+            undo();
+            throw e;
+        }
+    }
+    indexHost(host, tokens) {
+        let added = 0;
+        for (const t of tokens) {
+            if (this.hostOfToken.has(t))
+                continue;
+            const set = this.hostTokens.get(host) ?? new Set();
+            set.add(t);
+            this.hostTokens.set(host, set);
+            this.hostOfToken.set(t, host);
+            added += 1;
+        }
+        return added;
+    }
+    unindexHost(host, token) {
+        const set = this.hostTokens.get(host);
+        set?.delete(token);
+        if (set?.size === 0)
+            this.hostTokens.delete(host);
+        this.hostOfToken.delete(token);
+    }
+    persistHostSessions() {
+        atomicWriteFile(this.tmpDir, this.hostSessionsPath, JSON.stringify(Object.fromEntries([...this.hostTokens].map(([host, set]) => [host, [...set]]))));
     }
     persistSessionTokens() {
         atomicWriteFile(this.tmpDir, this.sessionTokensPath, JSON.stringify(Object.fromEntries([...this.sessionTokens].map(([sid, set]) => [sid, [...set]]))));
     }
     async put(token, cp) {
-        if (!this.scopes.has(cp.scope)) {
-            this.scopes.add(cp.scope);
-            atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
-        }
-        if (!this.sessionTokens.get(cp.sessionId)?.has(token)) {
+        const host = hostSessionOf(cp);
+        this.registerDurably(() => !this.scopes.has(cp.scope) && (this.scopes.add(cp.scope), true), () => this.scopes.delete(cp.scope), () => atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes])));
+        this.registerDurably(() => this.indexHost(host, [token]) > 0, () => this.unindexHost(host, token), () => this.persistHostSessions());
+        this.registerDurably(() => {
+            if (this.sessionTokens.get(cp.sessionId)?.has(token))
+                return false;
             const set = this.sessionTokens.get(cp.sessionId) ?? new Set();
             set.add(token);
             this.sessionTokens.set(cp.sessionId, set);
-            this.persistSessionTokens();
-        }
+            return true;
+        }, () => {
+            const set = this.sessionTokens.get(cp.sessionId);
+            set?.delete(token);
+            if (set?.size === 0)
+                this.sessionTokens.delete(cp.sessionId);
+        }, () => this.persistSessionTokens());
         return this.inner.put(token, cp);
     }
     get(token) {
@@ -150,7 +242,7 @@ export class LocalCheckpointStore {
             this.scopes.add(s);
         this.scopeRegistryCorrupt = false;
         atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
-        console.warn(`LocalCheckpointStore: scope registry REBUILT from the data plane (${rebuilt.length} scope(s) with pending gates) — enumeration restored`);
+        writeLogText("stderr", `LocalCheckpointStore: scope registry REBUILT from the data plane (${rebuilt.length} scope(s) with pending gates) — enumeration restored`);
     }
     async pendings(scope) {
         await this.ensureScopesRebuilt();
@@ -189,26 +281,34 @@ export class LocalCheckpointStore {
     async listPending(scope) {
         const rows = [];
         for (const { token, cp, summary } of await this.pendings(scope)) {
-            const pa = cp.pendingAction;
-            const gate = cp.gate;
-            const gateKind = queueRowGateKind(gate?.kind);
+            const gateKind = queueRowGateKind(summary.gateKind);
             if (gateKind === undefined)
                 continue;
+            const joinKey = durableRowIdentity("approvals-queue", summary.checkpointId, token);
+            const host = this.hostOfToken.get(token);
+            const taskId = parkedLegTaskId(cp.state?.rowTaskId, host === undefined ? null : ((await this.opts.getActiveTaskId?.(host)) ?? null));
+            const createdAt = summary.createdAt !== undefined ? { createdAt: summary.createdAt } : {};
+            const deadline = summary.deadline ?? null;
+            if (isUnreadableSummaryForm(summary)) {
+                rows.push({ sessionId: summary.sessionId, ...joinKey, scope: summary.scope, toolName: null, toolCallId: null, gateKind, taskId, input: null, ...createdAt, deadline, riskDescriptor: null, rowVerdict: summary.rowVerdict });
+                continue;
+            }
+            const pa = cp.pendingAction;
             const toolCallId = pa?.toolCallId ?? null;
             rows.push({
-                sessionId: cp.sessionId,
-                ...durableRowIdentity("approvals-queue", cp.checkpointId, token),
-                scope: cp.scope,
+                sessionId: summary.sessionId,
+                ...joinKey,
+                scope: summary.scope,
                 toolName: pa?.toolName ?? null,
                 toolCallId,
                 ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
                 ...(pa?.boundInputHash !== undefined ? { boundInputHash: pa.boundInputHash } : {}),
                 gateKind,
-                taskId: (await this.opts.getActiveTaskId?.(cp.sessionId)) ?? null,
+                taskId,
                 input: boundedToolInput(pa?.args),
-                createdAt: cp.createdAt,
-                deadline: cp.deadline ?? null,
-                riskDescriptor: gate?.riskDescriptor ?? null,
+                ...createdAt,
+                deadline,
+                riskDescriptor: queueRiskDescriptorOf(cp.gate),
                 ...(() => {
                     const rs = boundedRuleOffers(pa?.ruleOffers);
                     return rs !== undefined ? { ruleOffers: rs } : {};
@@ -220,15 +320,18 @@ export class LocalCheckpointStore {
                 rowVerdict: summary.rowVerdict,
             });
         }
-        return rows.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
+        return rows.sort(queueTriageOrder);
     }
     async findPendingTokenBySession(sessionId, scope, binding) {
-        return this.pickPendingRow(await this.sessionPendings(sessionId, scope || undefined), sessionId, binding)?.token ?? null;
+        return this.pickPendingRow(await this.axisPendings(sessionId, scope || undefined, binding), binding?.axis === "run" ? undefined : sessionId, binding)?.token ?? null;
+    }
+    axisPendings(sessionId, scope, binding) {
+        return binding?.axis === "run" ? this.runPendings(sessionId, scope) : this.sessionPendings(sessionId, scope);
     }
-    pickPendingRow(rows, sessionId, binding) {
+    pickPendingRow(rows, cardSessionId, binding) {
         let best;
         for (const row of rows) {
-            if (row.cp.sessionId !== sessionId)
+            if (cardSessionId !== undefined && row.cp.sessionId !== cardSessionId)
                 continue;
             if (binding?.gateKinds !== undefined) {
                 const kind = row.cp.gate?.kind;
@@ -240,30 +343,11 @@ export class LocalCheckpointStore {
         }
         return best;
     }
-    async hasExpiredBySession(sessionId) {
-        const tokens = this.sessionTokens.get(sessionId);
-        if (!tokens)
-            return false;
-        let pruned = false;
-        for (const t of [...tokens]) {
-            const cp = await this.inner.get(t);
-            if (!cp) {
-                tokens.delete(t);
-                pruned = true;
-                continue;
-            }
-            if (cp.status === "expired")
+    async hasExpiredForRun(runSessionId) {
+        for (const t of this.hostTokens.get(runSessionId) ?? []) {
+            if ((await this.inner.get(t))?.status === "expired")
                 return true;
         }
-        if (pruned) {
-            if (tokens.size === 0)
-                this.sessionTokens.delete(sessionId);
-            try {
-                this.persistSessionTokens();
-            }
-            catch {
-            }
-        }
         return false;
     }
     async findDecidedApprovalsForBinding(sessionId, boundCallId) {
@@ -315,34 +399,68 @@ export class LocalCheckpointStore {
         return (await this.inner.get(token))?.scope;
     }
     async peekPendingScope(sessionId, binding) {
-        return this.pickPendingRow(await this.sessionPendings(sessionId), sessionId, binding)?.cp.scope;
+        return this.pickPendingRow(await this.axisPendings(sessionId, undefined, binding), binding?.axis === "run" ? undefined : sessionId, binding)?.cp.scope;
+    }
+    async runPendings(runSessionId, scope) {
+        const out = [];
+        for (const token of this.hostTokens.get(runSessionId) ?? []) {
+            const cp = await this.inner.get(token);
+            if (cp === null || cp.status !== "pending" || (scope !== undefined && cp.scope !== scope))
+                continue;
+            out.push({ token, cp });
+        }
+        return out;
+    }
+    async hostSessionOfCard(token) {
+        const host = this.hostOfToken.get(token);
+        if (host !== undefined)
+            return host;
+        return (await this.inner.get(token)) === null ? undefined : null;
+    }
+    async backfillHostSessionsM49() {
+        let added = 0;
+        for (const [sessionId, toks] of this.sessionTokens)
+            added += this.indexHost(sessionId, toks);
+        for (const { token, cp } of await this.pendings())
+            added += this.indexHost(cp.sessionId, [token]);
+        if (added > 0)
+            this.persistHostSessions();
+        return added;
     }
     async reapExpired(cutoff) {
         let n = 0;
         for (const { token, cp } of await this.pendings()) {
-            const deadlineBranch = cp.deadline !== undefined && cp.deadline <= cutoff && !denySweepOwns(cp.gate);
+            const deadlineBranch = checkpointDeadlinePassed(cp.deadline, cutoff) && !denySweepOwns(cp.gate);
             const terminalBranch = terminalAtOf(cp) <= cutoff;
             if ((deadlineBranch || terminalBranch) && (await this.inner.expire(token, cp.scope)))
                 n++;
         }
         return n;
     }
-    async listExpiredApprovalGates(cutoff, limit = 100) {
+    async listExpiredApprovalGates(cutoff, limit = DENY_SWEEP_PAGE_ROWS, after) {
         const hits = [];
-        for (const { cp } of await this.pendings()) {
-            if (denySweepOwns(cp.gate) && cp.deadline !== undefined && cp.deadline <= cutoff)
-                hits.push({ sessionId: cp.sessionId, scope: cp.scope, deadline: cp.deadline });
+        for (const { token, cp } of await this.pendings()) {
+            if (!denySweepOwns(cp.gate) || !checkpointDeadlinePassed(cp.deadline, cutoff))
+                continue;
+            const position = { deadline: sweepDeadlineKey(cp.deadline), token };
+            if (after !== undefined && !sweepPositionPrecedes(after, position))
+                continue;
+            hits.push({ sessionId: cp.sessionId, scope: cp.scope, position });
         }
-        return hits
-            .sort((a, b) => a.deadline - b.deadline)
-            .slice(0, limit)
-            .map(({ sessionId, scope }) => ({ sessionId, scope }));
+        return hits.sort((a, b) => (sweepPositionPrecedes(a.position, b.position) ? -1 : sweepPositionPrecedes(b.position, a.position) ? 1 : 0)).slice(0, limit);
     }
-    async putCtx(sessionId, ctx) {
+    async putCtx(sessionId, ctx, claim) {
+        if (claim !== undefined) {
+            return this.writeCtxWhileClaimed(sessionId, ctx, claim, "local claim-fenced write", (path, text) => {
+                atomicWriteFile(this.tmpDir, path, text);
+                return "written";
+            });
+        }
         const rec = { sessionId, updatedAt: Date.now(), ctx };
         const text = JSON.stringify(rec);
         assertJsonColumnWritable(text, createCtxRecordReader(), `checkpoint ctx for session ${JSON.stringify(sessionId)} (local write leg)`);
         atomicWriteFile(this.tmpDir, join(this.ctxDir, ctxFileOf(sessionId)), text);
+        return "written";
     }
     async getCtx(sessionId) {
         const p = join(this.ctxDir, ctxFileOf(sessionId));
@@ -351,23 +469,25 @@ export class LocalCheckpointStore {
         const rec = refusingCtx(sessionId, () => decodeJsonColumn(readFileSync(p, "utf8"), createCtxRecordReader(), `checkpoint-ctx ${ctxFileOf(sessionId)} for session ${JSON.stringify(sessionId)}`));
         return rec.sessionId === sessionId ? rec.ctx : null;
     }
-    async rewriteCtxWhileClaimed(sessionId, taskId, ctx, legHolds) {
-        const claims = this.opts.claims;
-        if (claims === undefined)
-            throw new Error("LocalCheckpointStore.rewriteCtxWhileClaimed: no claim fence is bound to this store (wiring defect: the local backend binds its own run store)");
+    async rewriteCtxWhileClaimed(sessionId, ctx, claim) {
+        return this.writeCtxWhileClaimed(sessionId, ctx, claim, "local claim-fenced rewrite", (path, text) => {
+            if (!existsSync(path))
+                return "context_absent";
+            atomicWriteFile(this.tmpDir, path, text);
+            return "written";
+        });
+    }
+    writeCtxWhileClaimed(sessionId, ctx, claim, leg, write) {
+        const fence = claim.fence;
+        if ("db" in fence)
+            throw new Error(`LocalCheckpointStore ${leg}: the claim fence must be the in-process run store on this data root (wiring defect: the run store and the checkpoint store come from one backend)`);
         const rec = { sessionId, updatedAt: Date.now(), ctx };
         const text = JSON.stringify(rec);
-        assertJsonColumnWritable(text, createCtxRecordReader(), `checkpoint ctx for session ${JSON.stringify(sessionId)} (local claim-fenced rewrite)`);
+        assertJsonColumnWritable(text, createCtxRecordReader(), `checkpoint ctx for session ${JSON.stringify(sessionId)} (${leg})`);
         const path = join(this.ctxDir, ctxFileOf(sessionId));
-        let outcome = "context_absent";
-        const held = claims.whileHoldingClaim(sessionId, taskId, (run) => {
-            if (!legHolds(run)) {
-                outcome = "claim_released";
-            }
-            else if (existsSync(path)) {
-                atomicWriteFile(this.tmpDir, path, text);
-                outcome = "written";
-            }
+        let outcome = "claim_released";
+        const held = fence.whileHoldingClaim(sessionId, claim.taskId, (run) => {
+            outcome = claim.legHolds(run) ? write(path, text) : "claim_released";
             return FENCE_LANDED;
         });
         return held ? outcome : "claim_released";
@@ -413,7 +533,7 @@ export class LocalCheckpointStore {
             }
             if (rec.updatedAt >= cutoff)
                 continue;
-            if ((await this.findPendingTokenBySession(rec.sessionId)) !== null)
+            if ((await this.findPendingTokenBySession(rec.sessionId, undefined, { axis: "run" })) !== null)
                 continue;
             if ((await this.opts.getActiveTaskId?.(rec.sessionId)) !== undefined)
                 continue;

package/dist/plugins/local-data-dir-modes-m39.js

@@ -1,3 +1,4 @@
+import { createLogger } from "../observability/logger.js";
 import { closeSync, constants as FS, fchmodSync, fstatSync, lstatSync, openSync, readdirSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { physicalPathOf } from "@sema-agent/core";
@@ -45,7 +46,7 @@ const emit = (sink, msg, meta) => {
         sink(msg, meta);
     }
     catch {
-        console.warn(msg, meta);
+        createLogger().warn(msg, meta);
     }
 };
 const sameObject = (a, b) => a.dev === b.dev && a.ino === b.ino;

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