@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/approval-exemption-skill-cutoff.d.ts

@@ -0,0 +1,64 @@
+import type { Logger } from "../observability/logger.js";
+import type { RetiredSchemaProbeTarget } from "./schema-consistency.js";
+import type { SqlDialect } from "./sql-driver.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
+/** 被判的行的 wire 工具名 —— 引擎 `Skill` 工具的名字,core 导出(不手抄;core 改名 ⇒ 谓词跟着走)。 */
+export declare const SKILL_EXEMPTION_TOOL_NAME: string;
+/** 第一只落截点、删截点之前的行的版本(一次性迁移 M46 的引入版本;登记表 M46 行在时两者逐字相同 —— `test/approval-exemption-skill-cutoff.test.ts` 钉)。拒句点名的出路版本下限。 */
+export declare const SKILL_EXEMPTION_CUTOFF_SINCE = "7.148.0";
+/** local 车道的截点文件(数据根顶层;文件名沿用 M46 —— 7.148.0 起的数据根里已经是它)。 */
+export declare const LOCAL_SKILL_EXEMPTION_CUTOFF_FILE = "one-time-migration-M46.marker";
+/** 截点之前的行写下时的意思与今天读法的差 —— SQL 拒句与 local 读数段同一句。 */
+export declare const PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE: string;
+/** 判用的读口:一句带参数的查询 ⇒ 行。 */
+type CutoffQuery = (sql: string, params?: readonly unknown[]) => Promise<Array<Record<string, unknown>>>;
+/**
+ * **SQL 截点的唯一读者**(常设臂与一次性迁移 M46 的删句同读;调用方先确认标记表在):行不在 ⇒ `undefined`(缺席);行在而读不出时刻 ⇒ 拒启 {@link StoreBootRefusalError}
+ * —— 不按「此刻」、也不按「没有」猜(非法时刻进比较,驱动把它写成 `NULL`,`created_at < NULL` 数出 0 = 静默放行)。拒句只带读到的数值与出路。
+ */
+export declare function readSqlSkillExemptionCutoff(query: CutoffQuery, dialect: SqlDialect): Promise<number | undefined>;
+/**
+ * SQL 腿的拒启:这只库里有首次放行早于截点(或截点缺席)的 `Skill` 豁免行,而本构建已不带删它们的一次性迁移。**具名类型**(族基类 {@link StoreBootRefusalError}:
+ * 起服降级臂不吞、开库等待窗不重试);码与退役 schema / 列册对账同一个 `config.schema_mismatch`。拒句只带行数、截点与工具名(行的会话 / 放行人不进句子)。
+ */
+export declare class LegacySkillExemptionsPresentError extends StoreBootRefusalError {
+    /** 截点之前的 `Skill` 行数。 */
+    readonly rows: number;
+    /** 截点(ISO 时刻;`null` = 这只库没记截点:从没在落截点的版本上起过服)。 */
+    readonly cutoff: string | null;
+    /** 机读码(与退役 schema / 列册对账的拒启同一个)。 */
+    readonly code = "config.schema_mismatch";
+    constructor(
+    /** 截点之前的 `Skill` 行数。 */
+    rows: number, 
+    /** 截点(ISO 时刻;`null` = 这只库没记截点:从没在落截点的版本上起过服)。 */
+    cutoff: string | null);
+}
+/**
+ * SQL 腿的判(纯读,**唯一一只**;律见文件头):读截点({@link readSqlSkillExemptionCutoff};标记表不在 ⇒ 缺席,读不出 ⇒ 拒 —— `carried` 也判,建表之前)→
+ * `carried`(本构建还带 M46)或豁免表不在(新库,建表之前)⇒ 无事 → 数截点之前的 `Skill` 行(截点缺席 ⇒ 全部 `Skill` 行)→ 非零 ⇒ 拒。
+ * 谓词与 M46 的删句同一条,比较在库里做(`created_at < ?`,参数是截点的 `Date`)。读抛 ⇒ 原样上抛(判不了 ⇒ 不放行;不是确定的拒启表态)。
+ */
+export declare function judgeSqlSkillExemptionCutoff(query: CutoffQuery, dialect: SqlDialect, carried: boolean): Promise<void>;
+/**
+ * **探针口**(SQL 腿的判唯一的读处;唯一调用点 = `store-backend.ts` 的 `withRetiredSchemaProbe`,先于第一条 CREATE):借一条连接判一次、用完即还(拒时连接也已归还);
+ * `carried`(本构建还带 M46)⇒ 只验截点读得出、不数行(存量行交给 M46 删)。不取 `ensureSchema` 那把锁:纯读。
+ */
+export declare function assertSkillExemptionCutoffHeldOnPool(target: RetiredSchemaProbeTarget, carried: boolean): Promise<void>;
+/** local 截点文件正文 ⇒ T0(epoch 毫秒);读不出时刻 ⇒ `undefined`(调用方决定拒形:准入点名文件拒、M46 的腿拒并给「删掉再起」)。 */
+export declare function skillExemptionCutoffOfText(text: string): number | undefined;
+/** 写截点文件(原子、`required`:目录项没证落盘也算没写成 ⇒ 抛)。本车道截点文件唯一的写口:准入的锁内一步与 M46 的腿同调。 */
+export declare function writeLocalSkillExemptionCutoff(path: string, cutoffMs: number): void;
+/**
+ * 截点之前的 `Skill` 行所在的会话数(`cutoffMs` 缺席 ⇒ 任一 `Skill` 行都算):逐只日志经店的唯一读者 {@link readExemptionLog} 重放(同一套撤销 / 首次放行读法);
+ * 闸合上的日志不算(店对那只会话拒读、照问)。坏行的披露走 `warn`(缺席 ⇒ 日志接缝;同一次起服里店的 hydrate 会再披露一次)。
+ */
+export declare function localSkillExemptionSessionsBefore(root: string, cutoffMs: number | undefined, warn?: Logger["warn"]): number;
+/** 豁免日志目录的指纹(文件名 · 字节数 · 修改时刻;按名排序)—— 准入与锁内「没动」核对比同一只(锁内不再重放日志)。 */
+export declare function exemptionLogFingerprints(root: string): string[];
+/** 截点在 local 上的动作(准入判、锁内做):`lay` = 截点缺席,落「此刻」;`none` = 不写。 */
+export type SkillExemptionCutoffAction = "none" | "lay";
+/** **落截点**(锁内;准入的读数核过之后、抬引擎版本高水位之前;唯一调用点 = 数据根准入的锁内一步)。写不进 ⇒ 抛(抬之前拒)。 */
+export declare function settleLocalSkillExemptionCutoff(physicalRoot: string, action: SkillExemptionCutoffAction, now?: () => number): void;
+export {};
+//# sourceMappingURL=approval-exemption-skill-cutoff.d.ts.map

package/dist/plugins/approval-exemption-skill-cutoff.js

@@ -0,0 +1,122 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { SKILL_TOOL_NAME } from "@sema-agent/core";
+import { APPROVAL_EXEMPTION_DIR, EXEMPTION_LOG_SUFFIX, readExemptionLog } from "./approval-exemption-store.js";
+import { MIGRATION_MARKER_TABLE, SKILL_EXEMPTION_CUTOFF_ID } from "./one-time-migration-marker.js";
+import { atomicWriteFileSync } from "./owner-only-file-mode.js";
+import { readLiveColumns } from "./schema-live-columns.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
+export const SKILL_EXEMPTION_TOOL_NAME = SKILL_TOOL_NAME;
+export const SKILL_EXEMPTION_CUTOFF_SINCE = "7.148.0";
+export const LOCAL_SKILL_EXEMPTION_CUTOFF_FILE = "one-time-migration-M46.marker";
+export const PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE = `Such a row was written when approving a \`${SKILL_TOOL_NAME}\` call meant activating a skill (and pre-approving the tools that skill lists); ` +
+    `this build would read it as a standing answer for any later call of a tool named \`${SKILL_TOOL_NAME}\` in that session — a wider grant than the one given.`;
+function cutoffMsOf(raw) {
+    const n = typeof raw === "number" ? raw : typeof raw === "bigint" ? Number(raw) : typeof raw === "string" && /^-?\d+$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN;
+    return Number.isSafeInteger(n) && !Number.isNaN(new Date(n).getTime()) ? n : undefined;
+}
+export async function readSqlSkillExemptionCutoff(query, dialect) {
+    const [row] = await query(`SELECT marked_at_ms FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = ${dialect === "mysql" ? "?" : "$1"}`, [SKILL_EXEMPTION_CUTOFF_ID]);
+    if (row === undefined)
+        return undefined;
+    const ms = cutoffMsOf(row["marked_at_ms"]);
+    if (ms !== undefined)
+        return ms;
+    throw new StoreBootRefusalError(`${SCHEMA_MISMATCH_ERROR_CODE}: the Skill exemption cutoff row (${MIGRATION_MARKER_TABLE}, migration_id '${SKILL_EXEMPTION_CUTOFF_ID}') holds ${JSON.stringify(String(row["marked_at_ms"]))}, ` +
+        "which is not a time this build can read — refusing to start rather than guess which stored Skill session approval exemption rows predate it. " +
+        `Way out: DELETE FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = '${SKILL_EXEMPTION_CUTOFF_ID}'; then restart — the start records a new cutoff once the stored \`${SKILL_TOOL_NAME}\` rows are dealt with ` +
+        "(a release that still carries the one-time migration deletes them; a later release refuses until they are gone). This check only reads that row and changes nothing.");
+}
+export class LegacySkillExemptionsPresentError extends StoreBootRefusalError {
+    rows;
+    cutoff;
+    code = SCHEMA_MISMATCH_ERROR_CODE;
+    constructor(rows, cutoff) {
+        super(`${SCHEMA_MISMATCH_ERROR_CODE}: this database holds ${rows} \`${SKILL_TOOL_NAME}\` session approval exemption row(s) first granted before its Skill exemption cutoff ` +
+            `(${cutoff ?? "none recorded: no release that records it has started against this database"}) — refusing to start. ` +
+            `${PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE} ` +
+            `This build no longer carries the one-time migration (introduced in ${SKILL_EXEMPTION_CUTOFF_SINCE}) that deletes such rows. ` +
+            `Ways out: (1) start a server release at or above ${SKILL_EXEMPTION_CUTOFF_SINCE} that still carries that migration against this database once — it records the cutoff and deletes those rows — then start this build; ` +
+            `(2) or delete them yourself: DELETE FROM approval_exemption WHERE tool_name = '${SKILL_TOOL_NAME}'; — each session that held one is asked once more on its next \`${SKILL_TOOL_NAME}\` call. ` +
+            "The check behind this refusal is read-only and runs before this build creates any table: it changed nothing in the database.");
+        this.rows = rows;
+        this.cutoff = cutoff;
+        this.name = "LegacySkillExemptionsPresentError";
+    }
+}
+export async function judgeSqlSkillExemptionCutoff(query, dialect, carried) {
+    const live = await readLiveColumns((sql) => query(sql), dialect);
+    const cutoffMs = live.has(MIGRATION_MARKER_TABLE) ? await readSqlSkillExemptionCutoff(query, dialect) : undefined;
+    if (carried || !live.has("approval_exemption"))
+        return;
+    const ph = (i) => (dialect === "mysql" ? "?" : `$${i}`);
+    const [counted] = cutoffMs === undefined
+        ? await query(`SELECT COUNT(*) AS n FROM approval_exemption WHERE tool_name = ${ph(1)}`, [SKILL_EXEMPTION_TOOL_NAME])
+        : await query(`SELECT COUNT(*) AS n FROM approval_exemption WHERE tool_name = ${ph(1)} AND created_at < ${ph(2)}`, [SKILL_EXEMPTION_TOOL_NAME, new Date(cutoffMs)]);
+    const rows = Number(counted?.["n"] ?? 0);
+    if (rows > 0)
+        throw new LegacySkillExemptionsPresentError(rows, cutoffMs === undefined ? null : new Date(cutoffMs).toISOString());
+}
+export async function assertSkillExemptionCutoffHeldOnPool(target, carried) {
+    if (target.dialect === "mysql") {
+        const conn = await target.pool.getConnection();
+        try {
+            await judgeSqlSkillExemptionCutoff(async (sql, params) => (await conn.query(sql, params === undefined ? [] : [...params]))[0], "mysql", carried);
+        }
+        finally {
+            conn.release();
+        }
+        return;
+    }
+    const client = await target.pool.connect();
+    try {
+        await judgeSqlSkillExemptionCutoff(async (sql, params) => (await client.query(sql, params === undefined ? [] : [...params])).rows, "pg", carried);
+    }
+    finally {
+        client.release();
+    }
+}
+export function skillExemptionCutoffOfText(text) {
+    const t = Date.parse(text.trim());
+    return Number.isFinite(t) ? t : undefined;
+}
+export function writeLocalSkillExemptionCutoff(path, cutoffMs) {
+    atomicWriteFileSync(path, `${new Date(cutoffMs).toISOString()}\n`, { durability: "required" });
+}
+function exemptionLogNames(root) {
+    try {
+        return readdirSync(join(root, APPROVAL_EXEMPTION_DIR)).filter((name) => name.endsWith(EXEMPTION_LOG_SUFFIX)).sort();
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return [];
+        throw e;
+    }
+}
+export function localSkillExemptionSessionsBefore(root, cutoffMs, warn) {
+    let sessions = 0;
+    for (const name of exemptionLogNames(root)) {
+        const { rows, gate } = readExemptionLog(join(root, APPROVAL_EXEMPTION_DIR, name), warn);
+        if (gate.tripped)
+            continue;
+        const row = rows.get(SKILL_EXEMPTION_TOOL_NAME);
+        if (row !== undefined && (cutoffMs === undefined || row.createdAt < cutoffMs))
+            sessions += 1;
+    }
+    return sessions;
+}
+export function exemptionLogFingerprints(root) {
+    return exemptionLogNames(root).map((name) => {
+        const st = statSync(join(root, APPROVAL_EXEMPTION_DIR, name));
+        return `${name}\u0000${st.size}\u0000${st.mtimeMs}`;
+    });
+}
+export function settleLocalSkillExemptionCutoff(physicalRoot, action, now = Date.now) {
+    switch (action) {
+        case "none":
+            return;
+        case "lay":
+            return writeLocalSkillExemptionCutoff(join(physicalRoot, LOCAL_SKILL_EXEMPTION_CUTOFF_FILE), now());
+    }
+}
+//# sourceMappingURL=approval-exemption-skill-cutoff.js.map

package/dist/plugins/approval-exemption-skill-m46.d.ts

@@ -0,0 +1,14 @@
+import type { FileApprovalExemptionStore } from "./approval-exemption-store.js";
+/** SQL 腿一页的会话数(键集分批:`session_id` 升序,一页一次读、一句删)。 */
+export declare const LEGACY_SKILL_EXEMPTION_PAGE = 500;
+/**
+ * local 腿的 T0:标记文件在 ⇒ 读它(正文 = T0 的 ISO 时刻);不在 ⇒ **先**原子落盘再返回(`required`:标记没落盘就不算开始过 —— 写不进 ⇒ 抛,起服拒,下一次起服重来,一行没删)。
+ * 标记文件在而读不出(正文不是时刻 —— 手改过 / 写坏了)⇒ **响亮拒启**,点名文件与出路:不替人猜一个 T0(猜晚了会多删、猜早了会少删)。出路 = 删掉那只文件再起服(本步取新的 T0)。
+ */
+export declare function legacySkillExemptionCutoffLocal(markerPath: string, now?: () => number): number;
+/**
+ * 🔴 M46 的 local 腿(唯一调用点 `LocalBackend.runOneTimeMigrations`):T0 先落盘,再对 File 店删「首次放行早于 T0 的 `Skill` 行」(墓碑,与按名撤销同形)。返回删了几行。
+ * 数据根独占(根锁):同一只根上没有第二个起服者,也没有更早版本的副本与本次并跑。
+ */
+export declare function dropLocalLegacySkillExemptionsM46(markerPath: string, store: Pick<FileApprovalExemptionStore, "dropToolRowsCreatedBeforeM46">): number;
+//# sourceMappingURL=approval-exemption-skill-m46.d.ts.map

package/dist/plugins/approval-exemption-skill-m46.js

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from "node:fs";
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { SKILL_EXEMPTION_TOOL_NAME, skillExemptionCutoffOfText, writeLocalSkillExemptionCutoff } from "./approval-exemption-skill-cutoff.js";
+export const LEGACY_SKILL_EXEMPTION_PAGE = 500;
+export function legacySkillExemptionCutoffLocal(markerPath, now = Date.now) {
+    if (existsSync(markerPath)) {
+        const marked = skillExemptionCutoffOfText(readFileSync(markerPath, "utf8"));
+        if (marked === undefined) {
+            throw new StoreBootRefusalError(`one-time migration M46: ${markerPath} exists but does not hold a readable cutoff time (expected one ISO time, e.g. 2026-11-06T09:00:00.000Z); ` +
+                `refusing to start rather than guess which stored Skill exemption rows predate the upgrade. Delete the file and restart: the step then records a new cutoff (now) and deletes the stored Skill exemption rows older than it.`);
+        }
+        return marked;
+    }
+    const t0 = now();
+    writeLocalSkillExemptionCutoff(markerPath, t0);
+    return t0;
+}
+export function dropLocalLegacySkillExemptionsM46(markerPath, store) {
+    return store.dropToolRowsCreatedBeforeM46(SKILL_EXEMPTION_TOOL_NAME, legacySkillExemptionCutoffLocal(markerPath));
+}
+//# sourceMappingURL=approval-exemption-skill-m46.js.map

package/dist/plugins/approval-exemption-store.d.ts

@@ -1,5 +1,6 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+import { type JsonlStoreGate } from "../observability/corrupt-read-seat.js";
 import type { Logger } from "../observability/logger.js";
 /** The server's own audit event for a question a row answered without asking anyone — one name for both reading positions
  *  (the list gate: field `seat: "deployment_list"`; the approval seat: `seat: "approval_seat"`). Not a settlement record: nobody
@@ -48,6 +49,30 @@ export declare class MemoryApprovalExemptionStore implements ApprovalExemptionSt
     revoke(sessionId: string, toolName: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;
 }
+/** The File twin's directory under the data root (one JSONL log per session) and the log suffix — the store and the `Skill` cutoff's skip-version arm read the same layout. */
+export declare const APPROVAL_EXEMPTION_DIR = "approval-exemptions";
+export declare const EXEMPTION_LOG_SUFFIX = ".jsonl";
+/**
+ * A record whose first-grant time cannot be read (no `ts`, or a `ts` that is not a time — only a damaged or hand-edited log; the writer always stamps it)
+ * reads as the EARLIEST time, never as "now": every reader that asks "granted before cutoff X?" (the `Skill` exemption cutoff arm, one-time migration M46)
+ * then answers yes — the fail-closed direction. ("Now" changed with every restart and, read after a cutoff was recorded, silently kept such a row.)
+ */
+export declare const UNDATED_FIRST_GRANT_MS = 0;
+/** One session log's replayed rows: per wire tool name, the row in force (`createdAt` = its FIRST grant since the last revoke; unreadable ⇒ {@link UNDATED_FIRST_GRANT_MS}). */
+export type ExemptionLogRows = ReadonlyMap<string, {
+    readonly grantedBy: string | null;
+    readonly createdAt: number;
+}>;
+/**
+ * Replay ONE session log (the only reader of a log's bytes: the store's hydrate and the `Skill` cutoff's skip-version arm both call it —
+ * `approval-exemption-skill-cutoff.ts`). Torn-tail-safe, last-wins with revoke tombstones; a record in the middle that cannot be read closes
+ * that file's gate (`gate.tripped`) — the store then refuses every read of that session (ask anyway), so its rows answer nothing.
+ * A record without a parseable `ts` reads as granted now (the replay's own moment).
+ */
+export declare function readExemptionLog(path: string, warn?: Logger["warn"]): {
+    readonly rows: ExemptionLogRows;
+    readonly gate: JsonlStoreGate;
+};
 /**
  * 🔴 [ref] —— **fail-closed per session file.** A record in the MIDDLE of a session's log that cannot be read (bit rot,
  * a hand edit, a line `42`, an object missing `toolName`) used to be skipped silently. When that line was a REVOKE
@@ -66,20 +91,25 @@ export declare class FileApprovalExemptionStore implements ApprovalExemptionStor
     /** [ref]: sanitized session key → that session log's gate (only files that replayed a bad record are listed). */
     private readonly corruptGates;
     private readonly warn;
-    /** @param opts.warn corrupt-read disclosure seat (`LocalBackend` wires `discloseWarn`; absent ⇒ the owner falls back to `console.warn`, never to silence). */
+    /** @param opts.warn corrupt-read disclosure seat (`LocalBackend` wires `discloseWarn`; absent ⇒ the owner falls back to the log seam's text exit `writeLogText`, never to silence). */
     constructor(root: string, opts?: {
         warn?: Logger["warn"];
     });
     /** [ref]: first line of every judging / appending method (see the class note). */
     private assertUsable;
     private pathFor;
-    /** Replay every session log (torn-tail-safe; last-wins with revoke tombstones). Index keyed by the SANITIZED id. */
+    /** Replay every session log (torn-tail-safe; last-wins with revoke tombstones). Index keyed by the SANITIZED id. One reader per file: {@link readExemptionLog}. */
     private hydrate;
     private logFor;
     grant(sessionId: string, toolName: string, grantedBy: string | null): Promise<void>;
     has(sessionId: string, toolName: string): Promise<boolean>;
     list(sessionId: string): Promise<ApprovalExemptionRow[]>;
     revoke(sessionId: string, toolName: string): Promise<boolean>;
+    /**
+     * 一次性迁移 M46 的 local 腿(窗关随 M46 删;登记表 `removal` 点名):每只会话上 `toolName` 那一行的**首次放行**早于 `beforeMs` 的,追加一条墓碑(与 {@link revoke} 同形、fsync)并出索引。
+     * 返回删了几行。日志已被判坏的会话不碰(它的 `has` / `list` 本来就拒;删会话即清闸)。幂等:删过的行不在索引里,第二跑零命中。
+     */
+    dropToolRowsCreatedBeforeM46(toolName: string, beforeMs: number): number;
     deleteBySession(sessionId: string): Promise<number>;
     /** Release every open append-log fd (LocalBackend.close → graceful-restart re-open). */
     dispose(): void;

package/dist/plugins/approval-exemption-store.js

@@ -115,6 +115,27 @@ const EXEMPTION_RECORD_SHAPE = {
         return { toolName, grantedBy: grantedBy ?? null, ts: ts ?? "", ...(revoked !== undefined ? { revoked } : {}) };
     },
 };
+export const APPROVAL_EXEMPTION_DIR = "approval-exemptions";
+export const EXEMPTION_LOG_SUFFIX = ".jsonl";
+export const UNDATED_FIRST_GRANT_MS = 0;
+const firstGrantMsOf = (ts) => {
+    const t = Date.parse(ts);
+    return Number.isNaN(t) ? UNDATED_FIRST_GRANT_MS : t;
+};
+export function readExemptionLog(path, warn) {
+    const { records, gate } = replayJsonlGuarded(path, "approval-exemption", EXEMPTION_RECORD_SHAPE, warn);
+    const rows = new Map();
+    for (const r of records) {
+        if (r.revoked) {
+            rows.delete(r.toolName);
+        }
+        else {
+            const prior = rows.get(r.toolName);
+            rows.set(r.toolName, { grantedBy: r.grantedBy ?? null, createdAt: prior?.createdAt ?? firstGrantMsOf(r.ts) });
+        }
+    }
+    return { rows, gate };
+}
 export class FileApprovalExemptionStore {
     dir;
     bySession = new Map();
@@ -122,7 +143,7 @@ export class FileApprovalExemptionStore {
     corruptGates = new Map();
     warn;
     constructor(root, opts) {
-        this.dir = join(root, "approval-exemptions");
+        this.dir = join(root, APPROVAL_EXEMPTION_DIR);
         this.warn = opts?.warn;
         ensureDir(this.dir);
         this.hydrate();
@@ -131,7 +152,7 @@ export class FileApprovalExemptionStore {
         this.corruptGates.get(key)?.assertUsable();
     }
     pathFor(sessionId) {
-        return join(this.dir, `${sanitizePathComponent(sessionId)}.jsonl`);
+        return join(this.dir, `${sanitizePathComponent(sessionId)}${EXEMPTION_LOG_SUFFIX}`);
     }
     hydrate() {
         let names;
@@ -142,26 +163,14 @@ export class FileApprovalExemptionStore {
             return;
         }
         for (const name of names) {
-            if (!name.endsWith(".jsonl"))
+            if (!name.endsWith(EXEMPTION_LOG_SUFFIX))
                 continue;
-            const key = name.slice(0, -".jsonl".length);
-            const { records, gate } = replayJsonlGuarded(join(this.dir, name), "approval-exemption", EXEMPTION_RECORD_SHAPE, this.warn);
+            const key = name.slice(0, -EXEMPTION_LOG_SUFFIX.length);
+            const { rows, gate } = readExemptionLog(join(this.dir, name), this.warn);
             if (gate.tripped)
                 this.corruptGates.set(key, gate);
-            if (!records.length)
-                continue;
-            const m = this.bySession.get(key) ?? new Map();
-            for (const r of records) {
-                if (r.revoked) {
-                    m.delete(r.toolName);
-                }
-                else {
-                    const prior = m.get(r.toolName);
-                    m.set(r.toolName, { grantedBy: r.grantedBy ?? null, createdAt: prior?.createdAt ?? (Date.parse(r.ts) || Date.now()) });
-                }
-            }
-            if (m.size)
-                this.bySession.set(key, m);
+            if (rows.size)
+                this.bySession.set(key, new Map(rows));
             else
                 this.bySession.delete(key);
         }
@@ -212,6 +221,20 @@ export class FileApprovalExemptionStore {
         m.delete(toolName);
         return true;
     }
+    dropToolRowsCreatedBeforeM46(toolName, beforeMs) {
+        let dropped = 0;
+        for (const [key, m] of this.bySession) {
+            if (this.corruptGates.has(key))
+                continue;
+            const row = m.get(toolName);
+            if (row === undefined || !(row.createdAt < beforeMs))
+                continue;
+            this.logFor(key).append({ toolName, grantedBy: null, ts: new Date().toISOString(), revoked: true }, true);
+            m.delete(toolName);
+            dropped += 1;
+        }
+        return dropped;
+    }
     async deleteBySession(sessionId) {
         const key = sanitizePathComponent(sessionId);
         const removed = this.bySession.get(key)?.size ?? 0;

package/dist/plugins/approval-nonce-store.d.ts

@@ -1,7 +1,7 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
-import type { Logger } from "../observability/logger.js";
+import { type Logger } from "../observability/logger.js";
 /** 表名(单数形;`test/schema-naming-invariants.test.ts` 的闭集词表钉着)。 */
 export declare const APPROVAL_NONCE_TABLE = "approval_nonce";
 /**
@@ -10,6 +10,12 @@ export declare const APPROVAL_NONCE_TABLE = "approval_nonce";
  * 设限是**保守**方向(星平面字符在 JS 里算 2、在两个引擎的 VARCHAR 里算 1),永远不会撞到列宽。
  */
 export declare const MAX_APPROVAL_NONCE_CHARS = 190;
+/** 时间地板的表名(单行表,与 `retention_lease` 同形:`singleton` 恒 `'x'`)。判据见头注「时间地板」。 */
+export declare const APPROVAL_NONCE_FLOOR_TABLE = "approval_nonce_floor";
+/** 原始钟低于地板(钟被往回拨)时那一行 warn 的事件名。字段:`rolledBackMs`(地板 − 原始钟)/ `floorMs` / `clockMs`(原始钟读数)/ `store`(哪条腿)。 */
+export declare const APPROVAL_NONCE_CLOCK_ROLLBACK_EVENT = "approval_nonce_clock_rollback";
+/** 回拨 warn 的落点;店没接日志座时退回日志出口接缝的缺省 logger(不退回沉默)。 */
+export type ApprovalNonceWarn = Logger["warn"];
 export interface ApprovalNonceStore {
     /**
      * **这只店为它的记录计时的那口钟**(epoch ms)—— 见头注「到期 —— 一口钟」。
@@ -17,9 +23,8 @@ export interface ApprovalNonceStore {
      * 它是消费记录这条命上**唯一**的参照:受理窗的判定、落地后的复核、到期清扫三处全读它,于是
      * 「还受理 ⇒ 记录还在」是结构性的,不靠「两台副本的钟差不多」这条没人声明过的假设。
      *
-     * ⚠️ **要求:单调不减**。同源只挡「两只钟各走各的」,挡不住「这一只往回走」—— 钟回拨会让一条已被
-     * 清扫的记录所对应的证明重新过验签(头注「由构造」那段的残余,🚧 见 `approval-nonce-store.test.ts`)。
-     * 现役三实现都**不**自己强制这一条(Memory/File = `Date.now()`,SQL = 库钟),登记在案。
+     * 🔴 **由构造不低于地板**(头注「时间地板」):答 `max(原始钟, 地板)`。原始钟低于地板 ⇒ 答地板 + 一行
+     * {@link APPROVAL_NONCE_CLOCK_ROLLBACK_EVENT} warn(点名回拨量)。于是三处判决都不会读到「已删记录的到期时刻之前」的钟。
      * 🔴 读不出来 ⇒ **响亮抛**([ref] fail-closed):调用方必须把它当不确定失败,**绝不**掉回本地墙钟。
      */
     nowMs(): Promise<number>;
@@ -30,7 +35,8 @@ export interface ApprovalNonceStore {
      */
     consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
     /**
-     * GC:删掉 `expires_at_ms <= ` **{@link nowMs}** 的记录,返回删除行数(维护 tick 调)。
+     * GC:读一次 **{@link nowMs}** → 把地板抬到这一读数(**先落地**)→ 删掉 `expires_at_ms <=` 这一读数的记录,返回删除行数(维护 tick 调)。
+     * 地板的唯一写者:行不会在已落地的地板低于它的到期时刻时消失,中途崩溃只留下「地板已抬、行还在」(下一拍再删)。
      *
      * 🔴 **一个时钟入参都没有**,而且这不是省事:形参会让删除线由**跑清理的那台副本**说了算,而它跟
      * 验签那台不是同一口钟 —— 那正是本店要消灭的那条依赖(与票据店 [ref] 删掉 `now: () => number`
@@ -41,24 +47,42 @@ export interface ApprovalNonceStore {
 }
 export declare class SqlApprovalNonceStore implements ApprovalNonceStore {
     private readonly db;
-    constructor(db: SqlDriver);
+    private readonly warn;
+    /** @param opts.warn 回拨 warn 的落点(缺席 ⇒ 日志出口接缝的缺省 logger,不退回沉默)。 */
+    constructor(db: SqlDriver, opts?: {
+        readonly warn?: ApprovalNonceWarn;
+    });
     private q;
-    /** 库钟({@link sqlDbNowMs})—— 一组无状态副本唯一共享的那口钟。读不出 ⇒ 响亮抛。 */
+    /**
+     * 店钟 = max(库钟, 地板)。库钟({@link SQL_DB_NOW_MS})是一组无状态副本唯一共享的那口钟;地板与它**同一条语句**读出(两条语句之间
+     * 一次清扫会把地板抬到第一读之后,于是一次正常的读也会被报成回拨)。没有地板行 = 这只店从没删过记录。读不出 ⇒ 响亮抛。
+     */
     nowMs(): Promise<number>;
     consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
     reapExpired(): Promise<number>;
 }
 /** MySQL 协议腿的构造绑定(与兄弟店同形:类名/构造元数不变,消费方不必动)。 */
 export declare class TiDBApprovalNonceStore extends SqlApprovalNonceStore {
-    constructor(pool: MysqlPool);
+    constructor(pool: MysqlPool, opts?: {
+        readonly warn?: ApprovalNonceWarn;
+    });
 }
 /** PostgreSQL 腿的构造绑定。 */
 export declare class PgApprovalNonceStore extends SqlApprovalNonceStore {
-    constructor(pool: PgPool);
+    constructor(pool: PgPool, opts?: {
+        readonly warn?: ApprovalNonceWarn;
+    });
 }
 export declare class MemoryApprovalNonceStore implements ApprovalNonceStore {
     private readonly rows;
-    /** 单进程腿:店 = 这个进程,所以店钟就是本进程的墙钟(验签、复核、清扫本来就同一只钟,无第二口)。 */
+    /** 时间地板(头注「时间地板」):进程内即可 —— 店随进程死,它保护的记录同亡。缺席 = 从没删过。 */
+    private floorMs;
+    private readonly warn;
+    /** @param opts.warn 回拨 warn 的落点(缺席 ⇒ 日志出口接缝的缺省 logger)。 */
+    constructor(opts?: {
+        readonly warn?: ApprovalNonceWarn;
+    });
+    /** 单进程腿:店 = 这个进程,所以原始钟就是本进程的墙钟(验签、复核、清扫本来就同一只钟,无第二口);店钟 = 它与地板取大。 */
     nowMs(): Promise<number>;
     consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
     reapExpired(): Promise<number>;
@@ -91,12 +115,15 @@ export declare class FileApprovalNonceStore implements ApprovalNonceStore {
     private log;
     /** [ref]:本账的损坏闸(见类注)。 */
     private readonly gate;
-    /** @param opts.warn 腐读披露座(`LocalBackend` 接 `discloseWarn`;缺席 ⇒ 属主退回 `console.warn`,不退回沉默)。 */
+    /** 时间地板(头注「时间地板」):重放时取账里的地板行,每次压实与幸存行一起写回。缺席 = 这本账从没被清扫过。 */
+    private floorMs;
+    private readonly warn;
+    /** @param opts.warn 腐读披露座与回拨 warn 的落点(`LocalBackend` 接 `discloseWarn`;缺席 ⇒ 日志出口接缝的缺省出口,不退回沉默)。 */
     constructor(root: string, opts?: {
         warn?: Logger["warn"];
     });
     private logFor;
-    /** local 车道:店 = 这台机器上的这个数据根,所以店钟就是本进程的墙钟(理由同 Memory 腿)。 */
+    /** local 车道:店 = 这台机器上的这个数据根,所以原始钟就是本进程的墙钟(理由同 Memory 腿);店钟 = 它与地板取大(地板活过重启)。 */
     nowMs(): Promise<number>;
     consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
     reapExpired(): Promise<number>;