@sema-agent/server 7.134.0 → 7.135.0

package/dist/plugins/checkpoint-index-columns.js

@@ -0,0 +1,62 @@
+import { CARD_FACET_OVERRIDES, PAUSE_REGISTRY, checkpointIndexFacts } from "@sema-agent/core";
+export const CHECKPOINT_INDEX_COLUMNS = {
+    token: "token",
+    scope: "scope",
+    sessionId: "session_id",
+    version: "version",
+    gateKind: "gate_kind",
+    approvalCard: "approval_card",
+    toolName: "tool_name",
+    toolCallId: "tool_call_id",
+    boundInputHash: "bound_input_hash",
+    deadline: "deadline",
+    createdAt: "created_at_ms",
+    riskDescriptor: "risk_descriptor",
+    hasBidiControls: "has_bidi_controls",
+};
+export function buildCheckpointIndexCells(cp) {
+    const f = checkpointIndexFacts(cp);
+    return {
+        token: f.token,
+        scope: f.scope,
+        session_id: f.sessionId,
+        version: f.version,
+        gate_kind: f.gateKind,
+        approval_card: f.approvalCard,
+        tool_name: f.toolName,
+        tool_call_id: f.toolCallId,
+        bound_input_hash: f.boundInputHash,
+        deadline: f.deadline,
+        created_at_ms: f.createdAt,
+        risk_descriptor: f.riskDescriptor,
+        has_bidi_controls: f.hasBidiControls === true ? 1 : null,
+    };
+}
+export const APPROVAL_CARD_COLUMN_MAX_BYTES = {
+    tidb: 65_535,
+    pg: Number.POSITIVE_INFINITY,
+};
+function groupByFacet(pairs, column) {
+    const groups = new Map();
+    for (const [word, facet] of pairs) {
+        const words = groups.get(facet);
+        if (words === undefined)
+            groups.set(facet, [word]);
+        else
+            words.push(word);
+    }
+    return [...groups].map(([facet, words]) => ({ column, words, facet }));
+}
+export const CHECKPOINT_FACET_CASES = [
+    ...groupByFacet(Object.entries(CARD_FACET_OVERRIDES), CHECKPOINT_INDEX_COLUMNS.approvalCard),
+    ...groupByFacet(Object.keys(PAUSE_REGISTRY).map((k) => [k, PAUSE_REGISTRY[k].facet]), CHECKPOINT_INDEX_COLUMNS.gateKind),
+];
+const literal = (word) => `'${word.replace(/'/g, "''")}'`;
+function renderFacetCase(compared) {
+    return `CASE ${CHECKPOINT_FACET_CASES.map((c) => `WHEN ${compared(c.column)} IN (${c.words.map(literal).join(", ")}) THEN ${literal(c.facet)}`).join(" ")} END`;
+}
+export const CHECKPOINT_FACET_SQL = Object.freeze({
+    tidb: renderFacetCase((column) => `CAST(${column} AS BINARY)`),
+    pg: renderFacetCase((column) => column),
+});
+//# sourceMappingURL=checkpoint-index-columns.js.map

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

@@ -41,7 +41,7 @@ export declare const TERMINAL_GRACE_MS = 3600000;
 export declare function tokenFingerprint(token: string): string;
 /** Non-secret view of a pending checkpoint for the operator approval queue — deliberately NO token.
  *
- *  🔴 S-700:行**顶层**另带 {@link ParkRowFacts}(`requiresRealApproval` / `ruleOffersAbsence`,真才带、缺席 ≠ false)——
+ *  🔴 [ref]:行**顶层**另带 {@link ParkRowFacts}(`requiresRealApproval` / `ruleOffersAbsence`,真才带、缺席 ≠ false)——
  *  型与值都只有一个来源:`approval-card.ts` 的 {@link parkRowFacts}(两只店各读自己手里的那只寄存行 `pendingAction`,
  *  交给它、原样展开)。继承而不是在这里逐键再写一遍:core 给这一臂再加一位同类事实时,改的只有那张 Pick 表。 */
 export interface PendingCheckpoint extends ParkRowFacts {
@@ -71,7 +71,7 @@ export interface PendingCheckpoint extends ParkRowFacts {
     /** 🔴 [ref]③: the checkpoint's gate kind — the operator queue mixes tool approvals with
      *  plan_review / resource_limit / task_done parks (all of which carry `toolName: null`), so a durable-recovery
      *  consumer needs this to ROUTE a row to the right wire (`/decide` vs `/plan_review` vs `/resume`). ALWAYS present
-     *  (S-1681, 7.132.0): every park stamps it, the one-time migration M21 filled any row without it from the row's gate,
+     *  ([ref], 7.132.0): every park stamps it, the one-time migration M21 filled any row without it from the row's gate,
      *  and a SQL row that still carries none is not listed by `listPending` (counted: `server.approvals.queue-row-gate-kind-missing`; no decide route binds it either). */
     gateKind: CheckpointGate["kind"];
     /** The suspended run's taskId (task_active join) — the key to the run/trace ("view task context"). */
@@ -131,7 +131,7 @@ export interface PendingCheckpoint extends ParkRowFacts {
      * (`PendingAction.hasBidiControls`,core [ref]),`put()` 在铸行
      * 这一刻反范式成 `checkpoint.has_bidi_controls` 列(同行 `tool_input` / `bound_input_hash` / `gate_kind` /
      * `risk_descriptor` / `rule_suggestions` 五列同一条「铸行时一格、读口零 blob」先例),server 不重算。
-     * (S-700 起本读口**确实**逐行读 blob —— 只为 {@link ParkRowFacts} 那几位,且是按「本仓不发 ALTER TABLE、
+     * ([ref] 起本读口**确实**逐行读 blob —— 只为 {@link ParkRowFacts} 那几位,且是按「本仓不发 ALTER TABLE、
      * 加列 = 删库丢在飞 park」裁出来的代价,见 `listPending` 那一段;本位与五列的「铸行时一格」形不变。)
      *
      * 🔴 `true` **或缺席,恒不写 `false`/`null`**(core d.ts 的 OMIT 契约逐字点名 BFF:「never null, never
@@ -145,12 +145,12 @@ export interface PendingCheckpoint extends ParkRowFacts {
      */
     hasBidiControls?: true;
     /**
-     * core 7.49.0 #1414:**这一行渲在哪张卡上** —— 门上引擎铸的 `gate.approvalCard`(闭集 core `TOOL_APPROVAL_CARDS`;`question` = 问用户的
+     * core 7.49.0 [ref]:**这一行渲在哪张卡上** —— 门上引擎铸的 `gate.approvalCard`(闭集 core `TOOL_APPROVAL_CARDS`;`question` = 问用户的
      * 问题,不是副作用工具),即 core `summarizeCheckpoint` 投给 `CheckpointSummary.approvalCard` 的同一个词。读法单点 = `approval-content-kind.ts`
      * 的 `parkedApprovalCard`(只在审批门型上读、闭集窄读;两只店同调它:SQL 孪生读 `checkpoint` 列的 `gate` 子树,LOCAL 孪生读 blob 上的门)。
      * 🔴 缺席即缺席([ref]② OMIT 纪律):非审批门、7.49.0 之前停驻的存量行(门上无卡 —— core 的读法「无卡 = 不是一问」,本仓**不**从
      * 工具名回推)。两条 durable 读面(`GET /v1/approvals` 行 + `/stream` `pending` 帧)经同一投影同时携带;live 腿的同名键在
-     * `LivePendingRow.approvalCard`。展示/分诊用,永不参与 resume / gate / CAS。(此前此处是按 `tool_name` 列派生的 `contentKind`,随 #1414 删。)
+     * `LivePendingRow.approvalCard`。展示/分诊用,永不参与 resume / gate / CAS。(此前此处是按 `tool_name` 列派生的 `contentKind`,随 [ref] 删。)
      */
     approvalCard?: ToolApprovalCard;
 }
@@ -221,7 +221,7 @@ export declare function pendingRowPrecedes(a: {
  * 的唯一数据源。一行一列:列名 + 这一列不在时**运行期**先坏在哪(拒启文案逐字用它,所以运维读到的是
  * 「我会先在哪里挂」,不是一句泛泛的 schema 不齐)。
  *
- * 🔴 为什么是一张表而不是每列一个 `assert*ColumnSchema` 函数(S-160 归一):[ref]① 那次是一列一函数,
+ * 🔴 为什么是一张表而不是每列一个 `assert*ColumnSchema` 函数([ref] 归一):[ref]① 那次是一列一函数,
  * 本批 [ref] 又要加两列 —— 照抄就是第二、第三份三十行的同形代码,而它们**唯一的差别只有列名与那句话**。
  * 探测法(恒空 `WHERE 1=0` 读 + 方言缺列码)、失败方向(只在**可证**缺列时才给删表指路)、恢复动作
  * (DROP TABLE checkpoint 的代价交代)三者对整张表是同一条,所以规则只留一条,列变成数据:下一次加列
@@ -234,7 +234,7 @@ export declare const CHECKPOINT_ADDED_COLUMNS: ReadonlyArray<{
 /**
  * [ref]① 升级前置断言 —— **拒启**,不是 warn(形照 [ref] `assertApprovalAskRuleMaterialSchema` / [ref] /
  * [ref] 三条先例;codex 店面轮 R1-[high] 采纳 —— 其引证的「MIGRATION.md 常设策略」经亲验不存在,采纳的
- * 依据是本仓 assert*Schema 探针族的真先例与失败方向本身)。S-160 起判据对 {@link CHECKPOINT_ADDED_COLUMNS}
+ * 依据是本仓 assert*Schema 探针族的真先例与失败方向本身)。[ref] 起判据对 {@link CHECKPOINT_ADDED_COLUMNS}
  * **整张列册**跑(见那张表的头注:归一的理由)。
  *
  * 病:本仓不发 `ALTER TABLE`(SCHEMA POLICY:改列就改 CREATE + 删库重建)。一台**没删表**就升上来的
@@ -256,31 +256,26 @@ export declare function assertCheckpointColumnSchema(query: (sql: string) => Pro
 /**
  * `pendingAction.ruleOffers` 的**铸行侧**投影(mint 面,与 {@link boundedToolInput} 同位同待遇)。
  *
- * 三件事,一件都不能少:
- *  1. **结构窄读**(宪法 [ref] 边界必 schema / 禁裸 as-cast):blob 里的这一格是 `unknown`(旧 core /
- *     坏行 / 未来加字段都可能)。形不合的**整条丢弃**(不是整只丢弃)——一条坏 offer 不该让另一条真 offer 消失。
- *     判据按 `kind` 判别联合分臂合形(`RuleOfferRawSchema` 两臂各自 **strip 形** `.strip()`,
- *     多余键**剥掉**、且不拒收 —— 重扫二轮更正:旧注写 `.loose()`,而 zod 4 的 loose = passthrough,
- *     未知键会**留在** `parsed.data` 里,与「剥掉」相反)。上游 additive 加一键是 core 的常规做法,拿 strict 去窄读会让那一次加字段把整只
- *     offer 静默清零 —— 「有供给」当场变「无供给」,与本键的存在理由正相反(顶注第三段)。
+ * 四件事,一件都不能少:
+ *  1. **读**(宪法 [ref] 边界必判形 / 禁裸 as-cast):blob 里的这一格是 `unknown`(旧 core / 坏行 / 未来加字段都可能)。读者只有一只 =
+ *     core `readRuleOffers`(经 `approval-card.ts` 的 {@link readRuleOfferList};core 7.55.0 [ref] P1 阶段二起,修前本仓自己一份 zod 形):读不出的**整条丢弃**
+ *     (不是整只丢弃)——一条坏 offer 不该让另一条真 offer 消失;多余键逐级剥、不拒收(上游 additive 加一键是 core 的常规做法,拒收会把「有供给」静默变成「无供给」);
+ *     丢弃**响亮**(`server.rule-offers.offer-dropped`,修前这一腿静默)。
  *  2. **脱敏**:offer 文本是从**命令原文**铸出来的(`Bash(curl -H "Authorization: Bearer …")` 这种 exact
  *     形拼得出秘密),而 `GET /v1/approvals` 是**跨租户可见**的运维队列。落列前过 `redactSecrets` ——
- *     与同行 `tool_input` 在 mint 就 `redactDeep` 是**同一条**纪律([ref] 件4 把 `shadowedRule` 修在读面
- *     是因为那条路的行早已落库、改铸点救不了存量;本键是**新**列,没有存量行要救,修在铸点更彻底:
- *     秘密从此连**落库**都不落,不是落了库再在两条读面各洗一遍)。
+ *     与同行 `tool_input` 在 mint 就 `redactDeep` 是**同一条**纪律(秘密从此连**落库**都不落,不是落了库再在两条读面各洗一遍)。
  *  3. **脱敏之后**才截长(codex 交叉复审 [medium],验真后修):`redactSecrets` 会**变长**,先按限长校验
  *     原文再脱敏会产出超限文本,而 SQL 腿有**回读**(列 → 本函数再跑一遍)、LOCAL 腿没有 ⇒ 同一份素材
- *     两个后端给出不同卡面。顺序反过来之后本函数对自己的输出**幂等**,两条腿同形。完整论证见
- *     `RuleOfferRawSchema` 顶注。
+ *     两个后端给出不同卡面。顺序反过来之后本函数对自己的输出**幂等**,两条腿同形。
  *  4. **限基数**:core 契约今天 ≤2,这里按 {@link MAX_RULE_OFFERS}(=4,server 侧容忍帽,两个数的
  *     分工逐字见该常量顶注)截;`batch.rules` 成员另按 {@link MAX_RULE_OFFER_BATCH_MEMBERS}(=8)截 ——
  *     一条被改坏/未来放宽的上游不该把运维队列的一行撑爆。两个截都是**前缀截**(保序)。
  *     ⚠️ **但本函数整体不保原始下标**:第 1 条的「坏的逐条丢」会压紧数组 ⇒ 中间剔除后下标前移。
  *     本腿因此是**纯展示腿**,下标不得当选择键 —— 硬条款与它站得住的理由逐字见
  *     {@link PendingCheckpoint.ruleOffers} 顶注(同步腿相反:那侧零逐条丢弃,下标恒等于 core 的 offer index)。
- *     🔴 **成员帽扣在判形之前**(5.58 复审 F-2):见 {@link preboundBatchMembers} —— offer 条数那一维由
+ *     🔴 **成员帽扣在读之前**(5.58 复审 F-2):见 {@link preboundBatchMembers} —— offer 条数那一维由
  *     {@link MAX_RULE_OFFER_SCAN} 管,成员那一维在那之前是**无界**的。
- *     🔴 **扣预算在合形之后**(合并码重扫):旧序先 `slice` 再判形,于是 ≥MAX 条坏 offer 能把唯一的真
+ *     🔴 **扣预算在读出之后**(合并码重扫):旧序先 `slice` 再判形,于是 ≥MAX 条坏 offer 能把唯一的真
  *     offer 挤出预算,读数是 `undefined` —— 与上面第 1 条自证的不变量(坏的丢、好的照投)正相反。扫描窗
  *     {@link MAX_RULE_OFFER_SCAN} 仍是有界的:一条被改坏成上万条的行不该让每 3s 一拍的读路径去逐条判形。
  *
@@ -291,13 +286,13 @@ export declare function assertCheckpointColumnSchema(query: (sql: string) => Pro
  * 用来识别「过度脱敏 / pattern 从不触发」的指标灌成不可读。关掉的是**计数**:重扫仍在,手改过的行 /
  * 将来某条写路径漏了脱敏,读面照样兜住(运维队列跨租户可见,少脱一次的代价永远不能省)。
  *
- * 返回 `undefined` = **无供给**(键不落列):core 没给、给了空数组、或整只形不合。
+ * 返回 `undefined` = **无供给**(键不落列):core 没给、给了空数组、或整只读不出。
  */
 export declare function boundedRuleOffers(raw: unknown, opts?: {
     countRedactions?: boolean;
 }): RuleOfferProjection[] | undefined;
 /**
- * S-1681 —— 运维队列行的门型:**两只孪生同一只判官**(SQL 孪生读 `gate_kind` 列 —— put 时从同一只门反范式下来的那一格,每次停驻都盖,一次性迁移 M21 把没有它的
+ * [ref] —— 运维队列行的门型:**两只孪生同一只判官**(SQL 孪生读 `gate_kind` 列 —— put 时从同一只门反范式下来的那一格,每次停驻都盖,一次性迁移 M21 把没有它的
  * 存量行从门子树补齐;local 孪生读快照上的门 `cp.gate.kind`)。
  * 读到的值是 NULL / 缺席 / 不是 core 登记的门型 ⇒ `undefined`:这一行**不列**(响亮:计一次 `server.approvals.queue-row-gate-kind-missing`)—— 与每一条决断口同一个读法:
  * 按门型绑定取行的读口对这种行本来就不命中(`pendingRowQuery` 的 `gate_kind IN (…)`,证不出门型就不当它是这道门),队列不再把一行谁也决不了的行投出去,
@@ -367,7 +362,7 @@ export interface DecidedApprovalRecord {
      */
     payloadFp: string | null;
     /**
-     * S-160(core 7.7.0 [ref])—— 这条已决行上**已决动作最后被怎么处置**的结算记录,`null` = **未知**。
+     * [ref](core 7.7.0 [ref])—— 这条已决行上**已决动作最后被怎么处置**的结算记录,`null` = **未知**。
      *
      * 🔴 缺席只有一个含义:未知,**绝不是**「放行过」。`decision` 说的是决定(人批了没有),这一格说的是
      * 那次决定在 resume 腿上执行时的处置(部署自己的复核可能在 post-CAS 把人批过的、改过参数的调用否掉,
@@ -412,7 +407,7 @@ export declare function approvalDecisionOfWinner(winner: ResolvedOutcome | undef
  *
  * 逐层 `typeof` 收窄,不做裸 `as` 断言:blob 是持久层读回来的 `unknown`,是信任边界(宪法 [ref])。
  *
- * 🔴 S-550:入参是**已经解过码的体**,不是一格列文本 —— 本函数不再自己 `JSON.parse`(SQL 车道的解码
+ * 🔴 [ref]:入参是**已经解过码的体**,不是一格列文本 —— 本函数不再自己 `JSON.parse`(SQL 车道的解码
  * 唯一属主是 `sql-json-column.ts`,见 {@link pendingActionOfColumn};local 孪生本来就递一只对象进来)。
  * 于是「串就再解一次」这条读法在这里按构造消失,两条车道递进来的东西同形。
  */
@@ -503,7 +498,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
         readonly reopen: true;
     };
     /**
-     * `CheckpointStore.execution` 声明(core 7.7.0 [ref];S-160)——**必填**,且必须恰是 `{ outcome: true }`:
+     * `CheckpointStore.execution` 声明(core 7.7.0 [ref];[ref])——**必填**,且必须恰是 `{ outcome: true }`:
      * 店在此承诺 {@link SqlCheckpointStore.recordExecutionOutcome} 是契约描述的那条真 CAS(谓词、四词、
      * 冲突抛),且 {@link SqlCheckpointStore.reopen} 认这条记录。与 `durability`/`fidelity`/`redecision`
      * 三格同一条「声明而非鸭子判」姿势,区别只在这一格**不可缺席**:缺席的店会被 core 在 store 席的
@@ -582,7 +577,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      */
     reopen(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
     /**
-     * core 7.7.0 [ref](S-160)—— 记录**已决动作在 resume 腿上最后被怎么处置**:那一次调用的 `tool_end` 帧
+     * core 7.7.0 [ref]([ref])—— 记录**已决动作在 resume 腿上最后被怎么处置**:那一次调用的 `tool_end` 帧
      * 携带的 {@link GateOutcome}。契约(答案闭集四词 / 幂等 / 冲突抛 / 一个字都不碰 status·rev·outcome·
      * reopen_reason)的**判词逻辑一行都不自铸**:全部消费 core 导出的
      * {@link executionRecordDisposition} —— 它是每个后端共用的那一份「CAS 谓词 + 幂等/冲突两臂」,
@@ -645,53 +640,36 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * whose per-approval `deadline` OR its [ref] D-1 §3-inv#3 `terminal_at_ms` crash-safe backstop has passed —
      * the latter closes the forever-leak of a pending row with a NULL `deadline` (no approval TTL was configured).
      *
-     * [ref] D-D: the deadline-branch EXPIRES (≈ abort) every kind EXCEPT a tool-approval human/irreversible_ask
-     * gate — those are resolve-DENIED gracefully by the SLA deny-sweep (listExpiredApprovalGates →
-     * resumeCheckpoint(deny)), so expiring them here too would race + lose the graceful denial. Legacy rows (gate_kind
-     * NULL) stay on the expire path. The terminal_at_ms-branch is the crash-safe backstop for ANY kind (incl. a human
-     * gate whose deny-resume keeps failing) — it always abort-expires past the absolute cap (which is now STRICTLY
-     * after the deadline, so it never races the deny-sweep at the deadline instant).
-     *
-     * core 7.49.0 #1414 / #1468 A-S4: among the approval kinds, which rows the deny-sweep owns has ONE judge — core
-     * `facetOf(gate)`. A gate carrying the `question` card is facet `B` (a question's deadline voids it; denying a question
-     * is incoherent), so step ② expires it here row by row (token CAS, `status='pending'` guarded — a concurrent decide or
-     * another replica wins cleanly). The card lives only in the `checkpoint` blob's `gate` subtree, so the split cannot be
-     * one SQL predicate without writing core's judgment a second time in SQL; the old `tool_name` literal arm is gone. A
-     * gate with no card (parked before 7.49.0) is no question — core's reading — and stays with the deny-sweep.
+     * The deadline-branch expires every row whose facet is NOT `A` (core 7.55.0 [ref] P1 stage two): the facet is
+     * {@link CHECKPOINT_FACET_SQL}, the expression generated from core's `CARD_FACET_OVERRIDES` and `PAUSE_REGISTRY` over the
+     * row's `approval_card` / `gate_kind` columns — row by row it answers what core `facetOf(gate)` answers. Facet `A` (an
+     * approval gate whose deadline is an SLA) is resolve-DENIED by the deny-sweep instead ({@link listExpiredApprovalGates});
+     * a question parked under an approval gate (card `question`, facet `B`) is voided here in the same statement; a row whose
+     * gate kind is NULL or not registered reads NULL and is voided (as before). The terminal_at_ms-branch is the crash-safe
+     * backstop for ANY kind (incl. a human gate whose deny-resume keeps failing) — STRICTLY after the deadline, so it never
+     * races the deny-sweep at the deadline instant. Before: a hand-written approval-kind list in SQL, then a second pass that
+     * read each overdue approval row's `gate` subtree out of the blob and voided the question rows one by one (bounded pages,
+     * a cross-tick cursor).
      */
     reapExpired(cutoff: number): Promise<number>;
-    /** reapExpired ②'s position in the overdue approval rows, per store instance (see there). Absent = start from the earliest deadline. */
-    private reapCursor;
-    /**
-     * [ref] D-D (SLA-timer): the sessions of pending approval-kind checkpoints past their `deadline` (the per-approval
-     * SLA) that the deny-sweep owns ({@link denySweepOwns} — core `facetOf` reads them as facet `A`) — the reaper resolve-DENIES
-     * each (re-resume with decision=deny → the model continues with the denial) — graceful, vs the abort that expire() gives
-     * resource_limit/needs_review. Excludes legacy rows (gate_kind NULL — they predate the split and fall through to
-     * reapExpired's expire path). `limit` bounds the per-tick deny-resume work (each is a model run).
-     * 🔴 core 7.49.0 #1414 / #1468 A-S4: a gate carrying the `question` card (facet `B`) is NOT deny-swept — core refuses
-     * `sla_timeout` on it pre-CAS — reapExpired voids it instead. The card lives only in the blob's `gate` subtree and the
-     * judge is core's (the split is not one SQL predicate — see {@link reapExpired}), so the filter runs on the rows read;
-     * the read is therefore PAGED, filter first and `limit` after: pages of {@link REAP_CLASSIFY_BATCH} rows in the stable
-     * (deadline, token) order, the cursor advancing, until `limit` rows are collected or the overdue rows run out — the same
-     * "filter, then take `limit`" the LOCAL twin does. A backlog of question rows ahead of the deny-sweep's rows costs extra
-     * bounded pages, never a hidden deny-sweep row (they used to hold slots of a `LIMIT limit` window until voided).
+    /**
+     * [ref] D-D (SLA-timer): the sessions of pending checkpoints past their `deadline` whose facet is `A` — approval gates
+     * whose deadline is an SLA ({@link CHECKPOINT_FACET_SQL}, generated from core's two tables; the LOCAL twin reads core
+     * `facetOf` through `denySweepOwns`) — the reaper resolve-DENIES each (re-resume with decision=deny → the model continues
+     * with the denial), graceful, vs the abort that {@link reapExpired} gives every other facet. A question parked under an
+     * approval gate (facet `B`) is not here: core refuses `sla_timeout` on it pre-CAS, and reapExpired voids it. The filter is
+     * in SQL, before the LIMIT: `limit` bounds the per-tick deny-resume work (each is a model run), never hides a row behind
+     * rows the sweep does not own.
      */
     listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
         sessionId: string;
         scope: string;
     }>>;
-    /**
-     * core 7.49.0 #1414 / #1468 A-S4 —— 审批门型里过了 deadline 的 pending 行(deadline 升序),每行带 core 对它的到期读法
-     * (`denySweepOwns` = 审批门型 ∧ core `facetOf` 读作 `A`,门型取列、卡取 `gate` 子树)。到期两条腿(reapExpired 的 ②、拒扫腿的选行)读同一只:
-     * 对审批门型「谁拒扫、谁作废」本仓不写第二份判据。读恒有界(每次一页 `limit` 行),序 = (deadline, token) 稳定序;`after` = 从这一位置之后读
-     * (reapExpired 的跨拍游标;拒扫腿选行一次之内的翻页游标)。
-     */
-    private overdueApprovalRows;
     /** Pending checkpoints for the operator queue — NON-secret fields only (never the token). `taskId` is
      *  joined from task_active (the JOIN KEY to the run/trace — a suspended run KEEPS its
      *  session claim, so the join is live for every pending row; null only in pathological windows). */
     /**
-     * S-160 显式记账 —— **本口与 {@link SqlCheckpointStore.listByScope} 都不投执行判词,这是结构性的不是遗漏**:
+     * [ref] 显式记账 —— **本口与 {@link SqlCheckpointStore.listByScope} 都不投执行判词,这是结构性的不是遗漏**:
      * 两口的谓词都硬 `status='pending'`,而执行记录的 CAS 谓词是 `status='resolved' AND execution_outcome IS NULL`
      * ⇒ 一条 pending 行**按构造**不可能带记录;反向也封死了(记过的行 `reopen` 拒,永远回不到 pending)。
      * 所以这两条读面上「没有 `executionOutcome`」不是「缺席=未知」,而是「这一格在这条读面上不存在」。
@@ -811,11 +789,11 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      */
     peekScopeByToken(token: CheckpointToken): Promise<string | null | undefined>;
     peekPendingScope(sessionId: string, binding?: PendingRowBinding): Promise<string | null | undefined>;
-    /** Upsert the resume rebuild inputs for a session — written at SUBMIT (durable mode on) and, since S-433 F2,
+    /** Upsert the resume rebuild inputs for a session — written at SUBMIT (durable mode on) and, since [ref] F2,
      *  once per resume leg at its CAS win point (`DriveResumeArgs.resumeCtx`). Unconditional per `session_id`:
      *  the ordering fence lives at the CALLER's CAS win, not in a version column here.
      *
-     *  🔴 `ctx: object`, not `unknown` (S-577): the read leg judges this column as a JSON **object**
+     *  🔴 `ctx: object`, not `unknown` ([ref]): the read leg judges this column as a JSON **object**
      *  ({@link decodeCtxColumn}), so a writer that took `unknown` would be the "writes fine, reads back
      *  refused" asymmetry this repo keeps paying for — and `putCtx(sessionId, null)` was exactly the
      *  reachable arm that made the JSON literal `null` (indistinguishable from "no such row" at every
@@ -847,7 +825,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      *
      * The extra `task_active` guard closes a multi-gate window: between a resume's CAS (pending→resolved) and
      * the task hitting its NEXT gate (writing a new pending checkpoint), the session has no pending checkpoint —
-     * yet `putCtx` stamps `updated_at_ms` at submit and — since S-433 F2 (server 7.86.0) — once more on EVERY
+     * yet `putCtx` stamps `updated_at_ms` at submit and — since [ref] F2 (server 7.86.0) — once more on EVERY
      * resume leg, at the moment that leg wins the resume CAS (`DriveResumeArgs.resumeCtx`; before that fix only
      * the plan approval's mode write-back re-stamped it, and it did so AFTER acceptance). Both extra writes only
      * ever REFRESH the stamp, so they lengthen a ctx's life and touch none of the three guards — the direction is

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

@@ -1,17 +1,16 @@
-import { parkedApprovalCard, parkedFacetOf } from "../approval-content-kind.js";
+import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
-import { APPROVAL_GATE_KINDS_SQL_IN, denySweepOwns } from "../tool-approval.js";
-import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
+import { CHECKPOINT_FACET_SQL, buildCheckpointIndexCells } from "./checkpoint-index-columns.js";
+import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
-import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, parkRowFacts, screenUncoveredDetailSeat } from "../approval-card.js";
+import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, parkRowFacts, readRuleOfferList } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { durableRowIdentity } from "../checkpoint-identity.js";
+import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
-const REAP_CLASSIFY_BATCH = 200;
 const CTX_REWRITE_PAGE = 500;
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const MAX_TOOL_INPUT_CHARS = 8192;
@@ -82,36 +81,36 @@ function preboundBatchMembers(item) {
     return { ...candidate, rules: candidate.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS) };
 }
 export function boundedRuleOffers(raw, opts = {}) {
-    if (!Array.isArray(raw))
-        return undefined;
     const observe = opts.countRedactions ?? true;
     const scrub = (text) => redactSecrets(text, { observe }).slice(0, MAX_RULE_TEXT_CHARS);
+    const read = readRuleOfferList(Array.isArray(raw) ? raw.slice(0, MAX_RULE_OFFER_SCAN).map(preboundBatchMembers) : raw);
     const out = [];
-    for (const item of raw.slice(0, MAX_RULE_OFFER_SCAN)) {
+    for (const { offer } of read) {
         if (out.length >= MAX_RULE_OFFERS)
             break;
-        const parsed = RuleOfferRawSchema.safeParse(screenUncoveredDetailSeat(backfillLegacyBatchMemberKind(preboundBatchMembers(item))));
-        if (!parsed.success)
-            continue;
-        if (parsed.data.kind === "single") {
-            out.push({ kind: "single", rule: scrub(parsed.data.rule), match: parsed.data.match, command: scrub(parsed.data.command) });
-        }
-        else {
-            out.push({
-                kind: "batch",
-                rules: parsed.data.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS).map((r) => {
-                    switch (r.kind) {
-                        case "command":
-                            return { kind: "command", rule: scrub(r.rule), match: r.match, command: scrub(r.command), segment: scrub(r.segment) };
-                        case "directoryRead":
-                            return { kind: "directoryRead", rule: scrub(r.rule), directory: scrub(r.directory), segment: scrub(r.segment) };
-                        default:
-                            throw new Error(`unknown rule-offer batch member kind: ${JSON.stringify(r)}`);
-                    }
-                }),
-                uncoveredSegments: parsed.data.uncoveredSegments,
-                ...(parsed.data.uncoveredDetail !== undefined ? { uncoveredDetail: parsed.data.uncoveredDetail.map((d) => ({ segment: scrub(d.segment), reason: d.reason })) } : {}),
-            });
+        switch (offer.kind) {
+            case "single":
+                out.push({ kind: "single", rule: scrub(offer.rule), match: offer.match, command: scrub(offer.command) });
+                break;
+            case "batch":
+                out.push({
+                    kind: "batch",
+                    rules: offer.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS).map((r) => {
+                        switch (r.kind) {
+                            case "command":
+                                return { kind: "command", rule: scrub(r.rule), match: r.match, command: scrub(r.command), segment: scrub(r.segment) };
+                            case "directoryRead":
+                                return { kind: "directoryRead", rule: scrub(r.rule), directory: scrub(r.directory), segment: scrub(r.segment) };
+                            default:
+                                throw new Error(`unknown rule-offer batch member kind: ${JSON.stringify(r)}`);
+                        }
+                    }),
+                    uncoveredSegments: offer.uncoveredSegments,
+                    ...(offer.uncoveredDetail !== undefined ? { uncoveredDetail: offer.uncoveredDetail.map((d) => ({ segment: scrub(d.segment), reason: d.reason })) } : {}),
+                });
+                break;
+            default:
+                throw new Error(`unknown rule-offer kind: ${JSON.stringify(offer)}`);
         }
     }
     return out.length > 0 ? out : undefined;
@@ -197,28 +196,12 @@ function readCheckpointIdCell(cell) {
         return null;
     }
 }
-const PARK_ROW_GATE = { key: "gate", as: "park_gate" };
-function readParkGateCell(cell) {
-    try {
-        return decodeNullableJsonColumn(cell, readParkGateMemberBody, "checkpoint.checkpoint $.gate (approval card / expiry facet)");
-    }
-    catch (e) {
-        if (!isJsonColumnBodyProblem(e))
-            throw e;
-        recordFailOpen("server.approvals.park-row-blob-unreadable", "member=gate");
-        return undefined;
-    }
-}
-const readParkGateMemberBody = createObjectColumnReader();
 export function queueRowGateKind(kind) {
     if (isGateKind(kind))
         return kind;
     recordFailOpen("server.approvals.queue-row-gate-kind-missing", `gate_kind=${kind === null || kind === undefined ? "NULL" : redactSecrets(String(kind)).slice(0, 40)}`);
     return undefined;
 }
-function parkedGateOfRow(r) {
-    return { kind: r.gate_kind ?? undefined, approvalCard: readParkGateCell(r[PARK_ROW_GATE.as])?.approvalCard };
-}
 const readPendingActionMemberBody = createObjectColumnReader();
 export function boundedToolInput(args) {
     if (args === undefined)
@@ -400,34 +383,34 @@ export class SqlCheckpointStore {
         return { sql: `SELECT ${select} FROM checkpoint WHERE ${where.join(" AND ")} ORDER BY created_at_ms ${dir}, token ${dir} LIMIT 1`, params };
     }
     async put(token, cp) {
+        const cells = buildCheckpointIndexCells(cp);
         const pa = cp.pendingAction;
-        const version = checkpointVersionOf(cp);
         const toolInput = boundedToolInput(pa?.args);
         const ruleOffers = boundedRuleOffers(pa?.ruleOffers);
-        const hasBidiControls = pa?.hasBidiControls === true ? 1 : null;
         const executionOutcome = cp.executionOutcome === undefined ? null : this.json(cp.executionOutcome, "execution outcome");
         const executionAtMs = cp.executionOutcome === undefined ? null : (cp.executionAtMs ?? null);
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20::jsonb,$21)"), [
+            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
+                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21::jsonb,$22)"), [
                 token,
-                cp.scope,
-                cp.sessionId,
-                version,
+                cells.scope,
+                cells.session_id,
+                cells.version,
                 cp.status,
-                pa?.toolName ?? null,
-                pa?.toolCallId ?? null,
+                cells.tool_name,
+                cells.tool_call_id,
                 toolInput === null ? null : this.json(toolInput, "approval tool_input"),
                 this.json(cp, "checkpoint"),
-                cp.deadline ?? null,
-                cp.createdAt,
+                cells.deadline,
+                cells.created_at_ms,
                 Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS),
-                cp.gate?.kind ?? null,
-                pa?.boundInputHash ?? null,
-                ((g) => (g?.riskDescriptor ? this.json(g.riskDescriptor, "risk descriptor") : null))(cp.gate),
+                cells.gate_kind,
+                cells.approval_card,
+                cells.bound_input_hash,
+                cells.risk_descriptor === null ? null : this.json(cells.risk_descriptor, "risk descriptor"),
                 ruleOffers === undefined ? null : this.json(ruleOffers, "rule offers"),
-                hasBidiControls,
+                cells.has_bidi_controls,
                 cp.rev ?? 0,
                 cp.reopenReason ?? null,
                 executionOutcome,
@@ -555,49 +538,19 @@ export class SqlCheckpointStore {
     }
     async reapExpired(cutoff) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at_ms = ? " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN})) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ${APPROVAL_GATE_KINDS_SQL_IN})) OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
-        let n = res.affected;
-        const batch = await this.overdueApprovalRows(cutoff, REAP_CLASSIFY_BATCH, this.reapCursor);
-        for (const row of batch) {
-            if (!row.denySweeps && (await this.expire(row.token, row.scope)))
-                n++;
-        }
-        const last = batch.at(-1);
-        this.reapCursor = batch.length < REAP_CLASSIFY_BATCH || last === undefined ? undefined : { deadline: last.deadline, token: last.token };
-        return n;
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND COALESCE(${CHECKPOINT_FACET_SQL.tidb}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND COALESCE(${CHECKPOINT_FACET_SQL.pg}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
+        return res.affected;
     }
-    reapCursor;
     async listExpiredApprovalGates(cutoff, limit = 100) {
-        const hits = [];
-        let after;
-        while (hits.length < limit) {
-            const page = await this.overdueApprovalRows(cutoff, REAP_CLASSIFY_BATCH, after);
-            for (const r of page) {
-                if (hits.length < limit && r.denySweeps)
-                    hits.push({ sessionId: r.sessionId, scope: r.scope });
-            }
-            const last = page.at(-1);
-            if (page.length < REAP_CLASSIFY_BATCH || last === undefined)
-                break;
-            after = { deadline: last.deadline, token: last.token };
-        }
-        return hits;
-    }
-    async overdueApprovalRows(cutoff, limit, after) {
-        const head = `SELECT c.token, c.session_id, c.scope, c.gate_kind, c.deadline, ${jsonColumnText(this.db.dialect, "checkpoint", PARK_ROW_GATE)} FROM checkpoint c ` +
-            `WHERE c.status = 'pending' AND c.gate_kind IN ${APPROVAL_GATE_KINDS_SQL_IN} AND c.deadline IS NOT NULL AND `;
-        const { rows } = await this.db.query(after === undefined
-            ? head + this.q("c.deadline <= ? ORDER BY c.deadline ASC, c.token ASC LIMIT ?", "c.deadline <= $1 ORDER BY c.deadline ASC, c.token ASC LIMIT $2")
-            : head +
-                this.q("c.deadline <= ? AND (c.deadline > ? OR (c.deadline = ? AND c.token > ?)) ORDER BY c.deadline ASC, c.token ASC LIMIT ?", "c.deadline <= $1 AND (c.deadline > $2 OR (c.deadline = $3 AND c.token > $4)) ORDER BY c.deadline ASC, c.token ASC LIMIT $5"), after === undefined ? [cutoff, limit] : [cutoff, after.deadline, after.deadline, after.token, limit]);
-        return rows.map((r) => ({ token: String(r.token), sessionId: String(r.session_id), scope: String(r.scope), deadline: Number(r.deadline), denySweeps: denySweepOwns(parkedGateOfRow(r)) }));
+        const { rows } = await this.db.query(this.q(`SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ? AND ${CHECKPOINT_FACET_SQL.tidb} = 'A' ORDER BY deadline ASC, token ASC LIMIT ?`, `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= $1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY deadline ASC, token ASC LIMIT $2`), [cutoff, limit]);
+        return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
     }
     async listPending(scope) {
         const d = this.db.dialect;
         const base = `SELECT c.session_id, c.token, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
-            `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id, ` +
-            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_GATE)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)} ` +
+            `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, c.approval_card, ta.task_id, ` +
+            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)} ` +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
@@ -610,7 +563,7 @@ export class SqlCheckpointStore {
             const toolCallId = r.tool_call_id ?? null;
             const boundInputHash = r.bound_input_hash ?? null;
             const ruleOffers = readRuleOffersCell(r.rule_suggestions);
-            const approvalCard = parkedApprovalCard(parkedGateOfRow(r));
+            const approvalCard = parkedApprovalCard({ kind: gateKind, approvalCard: r.approval_card ?? undefined });
             return [{
                     sessionId: String(r.session_id),
                     ...durableRowIdentity("approvals-queue", readCheckpointIdCell(r[PARK_ROW_CHECKPOINT_ID.as]), r.token),
@@ -639,7 +592,7 @@ export class SqlCheckpointStore {
         for (const r of rows) {
             const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `in the ${scope} scheduler view`));
             cp.status = r.status;
-            out.push(summarizeCheckpoint(cp));
+            out.push(summarizeCheckpoint(cp, (sentence) => recordFailOpen("server.checkpoint.inbox-risk-axes-damaged", withoutCheckpointToken(sentence, cp.token))));
         }
         return out;
     }

package/dist/plugins/device-store-sql.d.ts

@@ -64,7 +64,7 @@ export declare const TIDB_DEVICE_STATEMENTS: readonly string[];
 /** {@link TIDB_DEVICE_STATEMENTS} 的遍历壳(集成测试用;生产装配由中央 ensureSchema 展开同一份数组)。 */
 export declare function ensureTiDBDeviceSchema(pool: MySqlPool): Promise<void>;
 type PgQuery = (sql: string, params?: unknown[]) => Promise<unknown>;
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgDeviceSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgDeviceSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const DEVICE_INDEXES: readonly IndexSpec[];
 export declare function ensurePgDeviceSchema(q: PgQuery): Promise<void>;
 /**
@@ -141,7 +141,7 @@ export declare class SqlDeviceStore implements DeviceStore {
      * 前提写在 {@link SqlTxConn.begin} 的 @contract txn.read-semantics。这把锁在 `devices` 表上,与下面
      * 被插入的 `device_session` 行不是同一行。
      *
-     * 🔴 形 B · cas-insert(S-127 / B-013)—— 本站点是全仓 `INSERT IGNORE` 的**正当用法**:
+     * 🔴 形 B · cas-insert([ref] / [ref])—— 本站点是全仓 `INSERT IGNORE` 的**正当用法**:
      * `INSERT IGNORE` / `ON CONFLICT DO NOTHING` 的 affected(1/0)是引擎对「谁赢」的**权威**回答,而
      * `ON DUPLICATE KEY UPDATE pk = pk` 的 affected 新行/既有行都是 1、分不出赢家 ⇒ 这里换不得动词。
      * 代价必须付清:**同一事务此后不得对被插入的那一行做加锁读**。InnoDB 下撞重复键的 IGNORE 在既有行
@@ -156,13 +156,13 @@ export declare class SqlDeviceStore implements DeviceStore {
      */
     bindSession(input: BindSessionInput): Promise<BindSessionResult>;
     /**
-     * 首绑 CAS 的**输家观察**(形 B 的后半,S-127)—— 独立事务,与那次 `INSERT IGNORE` 无锁关系。
+     * 首绑 CAS 的**输家观察**(形 B 的后半,[ref])—— 独立事务,与那次 `INSERT IGNORE` 无锁关系。
      *
      * 🔴 `FOR UPDATE`(**真库红修**,2026-08-28 双库跑当场抓到,mock 抓不到):TiDB 的悲观事务里**普通
      * SELECT 仍是快照读**(读的是本事务 start_ts 的视图),只有加锁读才是当前读。放在新事务里读同样要
      * 这把锁 —— 新事务的 start_ts 虽在赢家提交之后,但「读的是不是当前」这条判据不该靠时序巧合来满足。
      * 与旧形的**唯一**差别:此刻我们手上没有那一行的 S 锁,于是这把 X 是**直接取**的,不是升级 ⇒ 两个
-     * 并发输家不会互等(B-013 的死锁形正是那次升级)。
+     * 并发输家不会互等([ref] 的死锁形正是那次升级)。
      *
      * 行不在 = 赢家的绑定在这一瞬被 `unbindSession` 删了(真实可能,不是不变量破)。这仍然是**响亮**的:
      * 首绑既没成、也说不出冲突对象,折成任何一种业务回执都是撒谎([ref]:未知失败不伪装成正常拒绝)。
@@ -189,12 +189,13 @@ export declare class SqlDeviceStore implements DeviceStore {
     /**
      * 审计列表。
      *
-     * 🔴 **一行读不出形 ⇒ 整页拒,刻意不做逐行隔离**(S-550 修复验证轮,主会话裁定后入档):方向由设计
+     * 🔴 **一行读不出形 ⇒ 整页拒,刻意不做逐行隔离**([ref] 修复验证轮,主会话裁定后入档):方向由设计
      * §2「失败方向 = 拒(fail-closed),全店同向」定。逐行隔离(坏行跳过 / 占位)在**审计**面上尤其危险 ——
      * 它把「这一页少了一条」变得和「本来就没有那一条」同形,而审计面的全部意义就是「发生过的事都在」。
      * 一页 5xx 是响亮的运维事件,一条静默消失不是。
      *
-     * ⇒ 存量库里旧写腿留下的坏字节由**一次性迁移**清掉(`one-time-migrations.ts` M4),不靠读侧容忍。
+     * ⇒ 存量库里旧写腿留下的坏字节(JSON 文本 `null`)7.93.5 起由启动期一次性迁移清过、窗关后已删码,读侧不容忍:
+     *   跳过了那些版本直接升的库,含这种行的那一页读不出来,拒句点名行 id,出路是运维把那些行的 `detail` 置成 SQL NULL(MIGRATION 写了语句)。
      */
     listAudit(filter?: ListAuditFilter): Promise<DeviceAuditRow[]>;
 }