@sema-agent/server 7.140.0 → 7.142.0

package/dist/plugins/approval-ask-store-memory.js

@@ -11,8 +11,8 @@ function applyPatch(row, patch) {
         row.decisionNote = patch.decisionNote;
     if (patch.decidedAtMs !== undefined)
         row.decidedAtMs = patch.decidedAtMs;
-    if (patch.deniedReason !== undefined)
-        row.deniedReason = patch.deniedReason;
+    if (patch.endingCause !== undefined)
+        row.endingCause = patch.endingCause;
     if (patch.gateToken !== undefined)
         row.gateToken = patch.gateToken;
     if (patch.gateBoundCallId !== undefined)
@@ -99,7 +99,8 @@ export class InMemoryApprovalAskStore {
             decisionNote: null,
             settledBy: null,
             decidedAtMs: null,
-            deniedReason: null,
+            endingCause: null,
+            parkTrigger: null,
             gateToken: null,
             gateBoundCallId: null,
             gateBoundInputHash: null,
@@ -181,7 +182,7 @@ export class InMemoryApprovalAskStore {
                 const scoped = this.asks.get(askId);
                 if (scoped !== undefined && scoped.batchId !== batchId)
                     return { claimed: false, current: { state: "absent" } };
-                const won = await this.transitionAsk(askId, "STREAM_PENDING", "VOID", { updatedAtMs: this.now(), ...(opts?.cause !== undefined ? { deniedReason: opts.cause } : {}) });
+                const won = await this.transitionAsk(askId, "STREAM_PENDING", "VOID", { updatedAtMs: this.now(), ...(opts?.cause !== undefined ? { endingCause: opts.cause } : {}) });
                 if (won)
                     return { claimed: true, voidedSiblings: [] };
                 break;
@@ -222,7 +223,7 @@ export class InMemoryApprovalAskStore {
             return { won: false, voidedSiblings: [] };
         ask.state = "PARKING";
         if (cause !== undefined)
-            ask.deniedReason = cause;
+            ask.parkTrigger = cause;
         ask.rev += 1;
         ask.updatedAtMs = now;
         if (batch.state === "OPEN") {
@@ -234,7 +235,7 @@ export class InMemoryApprovalAskStore {
         for (const [id, r] of this.asks) {
             if (r.batchId === batchId && r.state === "STREAM_PENDING" && id !== askId) {
                 r.state = "VOID";
-                r.deniedReason = APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN;
+                r.endingCause = APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN;
                 r.rev += 1;
                 r.updatedAtMs = now;
                 voided.push(id);
@@ -267,7 +268,7 @@ export class InMemoryApprovalAskStore {
         for (const [id, r] of this.asks) {
             if (r.batchId === batchId && r.state === "PARKING" && id !== askId) {
                 r.state = "VOID";
-                r.deniedReason = APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE;
+                r.endingCause = APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE;
                 r.rev += 1;
                 r.updatedAtMs = now;
                 voidedSiblings.push(id);
@@ -295,7 +296,7 @@ export class InMemoryApprovalAskStore {
         for (const [id, r] of this.asks) {
             if (r.batchId === batchId && r.state === "STREAM_PENDING") {
                 r.state = "VOID";
-                r.deniedReason = APPROVAL_ENDING_CAUSES.BATCH_ABORTED;
+                r.endingCause = APPROVAL_ENDING_CAUSES.BATCH_ABORTED;
                 r.rev += 1;
                 r.updatedAtMs = now;
                 voided.push(id);

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -42,7 +42,7 @@ import type { PgQueryFn } from "./pg-query.js";
 import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
 import type { HostSettledBy } from "../host-decision.js";
-import { type AskRowCause, type SettleCause } from "../approval-deny-reasons.js";
+import { type AskRowEndingCause, type SettleCause, type ParkTriggerCause } from "../approval-deny-reasons.js";
 import { type IndexSpec } from "./ensure-index.js";
 import { type ExecutionLane } from "../execution-lane-caps.js";
 export type AskDecision = "approve" | "deny";
@@ -132,7 +132,16 @@ export interface AskRow {
      */
     updatedInput?: unknown;
     decidedAtMs: number | null;
-    deniedReason: string | null;
+    /**
+     * `ending_cause` 列原值 —— **终态成因**:这一行为什么没被人答就结束了(到 `VOID` / `DENIED` 的转移带着它写:取消 claim、店内撤兄弟 / bind-once 落选 / 批中止、对账器、起服收敛;没带的转移 ⇒ 保持 `null`)。
+     * 只经 {@link askRowEndingCause} 读(词表 + 行不变式在那里);`null` = 没写归因。
+     */
+    endingCause: string | null;
+    /**
+     * `park_trigger` 列原值 —— **转 park 的触发成因**:这一行为什么被转进投递面。**唯一写者** = 赢下 `STREAM_PENDING → PARKING` 的那一次 `claimTerminal(expire, { cause })`,
+     * 此后不再被写(行走到 `PARKED` / `DENIED` / `VOID` 之后它仍在;{@link AskTransitionPatch} 没有这一键)。只经 {@link askRowParkTrigger} 读;`null` = 没写(不带 cause 的转 park)。
+     */
+    parkTrigger: string | null;
     /** PARKED 坐标三件。 */
     gateToken: string | null;
     gateBoundCallId: string | null;
@@ -222,7 +231,9 @@ export interface AskTransitionPatch {
     decisionActor?: unknown | null;
     decisionNote?: string | null;
     decidedAtMs?: number | null;
-    deniedReason?: string | null;
+    /** 终态成因(值域与终局 claim 的 `cause` 同一型 {@link SettleCause};读口按终态成因词表读,且只在 `VOID` / `DENIED` 上作数 —— 别的转移上写了也读成缺席)。
+     *  补丁**没有**触发成因那一键:它只由 `claimTerminal(expire, { cause })` 写一次。 */
+    endingCause?: SettleCause;
     gateToken?: string | null;
     gateBoundCallId?: string | null;
     gateBoundInputHash?: string | null;
@@ -330,9 +341,10 @@ export interface ExpireResult {
  */
 export type AskTerminalClaimIntent = "expire" | "cancel" | "refuse";
 /**
- * 终局 claim 的可选实参:`cause` —— **赢下 `cancel`(VOID)/ `expire`(PARKING)时写进这一行 `denied_reason` 列的成因词**(决断口 410 / 晚答 404 / 跨副本的败方读数读同一列,
- * 所以这一行自己记着「为什么」,读面不靠任何进程内的东西)。`cancel` 写终态成因({@link SettleCause} 里的 `run_cancelled` / `run_exited`),
- * `expire` 写转 park 的触发成因({@link ParkTriggerCause}:`ttl_expired` / `broadcast_lost` / `stream_disconnected` / `undeliverable` / `shutdown_before_park`);缺席 ⇒ 列保持 NULL(读面缺席即缺席)。
+ * 终局 claim 的可选实参:`cause` —— **赢下终局的同一步写进这一行的成因词**,列由意图定({@link claimCauseColumn}):`cancel`(VOID)写 `ending_cause` = 终态成因
+ * ({@link SettleCause} 里的 `run_cancelled` / `run_exited`;决断口 410 / 晚答 404 / 跨副本的败方读数读这一列),`expire`(PARKING)写 `park_trigger` = 转 park 的触发成因
+ * ({@link ParkTriggerCause}:`ttl_expired` / `broadcast_lost` / `stream_disconnected` / `undeliverable` / `shutdown_before_park`;跨副本的悬挂腿与败方读数读这一列)。
+ * 所以这一行自己记着「为什么」,读面不靠任何进程内的东西;缺席 ⇒ 列保持 NULL(读面缺席即缺席)。
  * `refuse` 不读它(落的是一条决议,来源位 `policy`,不是结局成因);`expire` 撤兄弟时店自己写 `batch_sibling_withdrawn`(那是这条事务本身的事实)。
  */
 export interface AskTerminalClaimOpts {
@@ -348,6 +360,11 @@ export declare const POLICY_REFUSAL_DECISION: {
     readonly decision: "deny";
     readonly settledBy: Extract<HostSettledBy, "policy">;
 };
+/**
+ * 带成因的终局 claim 把成因写进哪一列(穷举 switch:意图闭集加一个词 ⇒ 这里编译期先红)。一列一义:`cancel` 赢下的是终态(`ending_cause`),
+ * `expire` 赢下的是转 park(`park_trigger`);`refuse` 落的是一条决议,不带成因(不进本表)。SQL 两孪生读这一只;内存孪生的两臂各自落同一格(`transitionAsk` 的补丁 / `expireAsk`)。
+ */
+export declare function claimCauseColumn(intent: Exclude<AskTerminalClaimIntent, "refuse">): "ending_cause" | "park_trigger";
 /** 终局 claim 意图 → 本次 CAS 的目标态(穷举 switch:意图闭集加一个词 ⇒ 这里编译期先红)。 */
 export declare function claimTargetState(intent: AskTerminalClaimIntent): AskState;
 /**
@@ -374,10 +391,11 @@ export type AskTerminalClaimCurrent = {
     /** [ref]:赢家决议的**结算来源**(语义与两态读法见 {@link AskRow.settledBy})。**必填**(不是可选)——
      *  可选会让投影漏挑这一列时静默编译过,而漏挑的后果恰是本批要修的病:CAS 输家把赢家的策略拒读成人拒。 */
     settledBy: HostSettledBy | null;
-    /** 行上记着的成因,经问账行成因的唯一读口 `causeOfAskRow` 读出(`kind` 说它在这一行上的意思:VOID / DENIED = 终态成因,PARKING / PARKED = 转 park 的触发成因);
-     *  **只在读得出时在场**(没写 / 与 state 不配 ⇒ 缺席;DECIDED 的败方读数逐字不变)。CAS 输家据它按**行上那个成因**结算(而不是把别人撤的卡读成一次拒绝);
-     *  投影的唯一函数是 {@link projectAskTerminalClaimTruth},三 twin 不各自挑列,原始列值不出店层。 */
-    cause?: AskRowCause;
+    /** 行上记着的终态成因(`ending_cause` 列,经唯一读口 `askRowEndingCause` 读出)。**只在读得出时在场**(没写 / 与 state 不配 ⇒ 缺席;DECIDED 的败方读数逐字不变)。
+     *  CAS 输家据它按**行上那个成因**结算(而不是把别人撤的卡读成一次拒绝);投影的唯一函数是 {@link projectAskTerminalClaimTruth},三 twin 不各自挑列,原始列值不出店层。 */
+    endingCause?: AskRowEndingCause;
+    /** 行上记着的转 park 触发成因(`park_trigger` 列,经唯一读口 `askRowParkTrigger` 读出;行走过 PARKING 才可能在场)。在场律同 {@link endingCause}。 */
+    parkTrigger?: ParkTriggerCause;
 };
 /**
  * 单次原子往返的答案(语义律的唯一规范陈述点 = core `checkpoint-store.ts` `claimTerminal` 契约 JSDoc,
@@ -578,6 +596,20 @@ export declare const APPROVAL_ASK_EXECUTION_LANE_COLUMN: {
     readonly mysql: "execution_lane VARCHAR(32) NOT NULL DEFAULT ''";
     readonly pg: "execution_lane VARCHAR(32) COLLATE \"C\" NOT NULL DEFAULT ''";
 };
+/**
+ * 问行两列成因的列定义(两方言;唯一属主 —— 建表 DDL 内联它们,存量库的改名 / 加列只由一次性迁移做,那一步也读这里:窗口见 `plugins/one-time-migrations.ts` 登记表 M34)。
+ * 宽度 64 = 成因闭集里最长的词有余(钉在 `test/approval-reconciler.test.ts`)。语义见 {@link AskRow.endingCause} / {@link AskRow.parkTrigger}。
+ */
+export declare const APPROVAL_ASK_ENDING_CAUSE_COLUMN: {
+    readonly name: "ending_cause";
+    readonly mysql: "ending_cause VARCHAR(64) NULL";
+    readonly pg: "ending_cause VARCHAR(64) COLLATE \"C\"";
+};
+export declare const APPROVAL_ASK_PARK_TRIGGER_COLUMN: {
+    readonly name: "park_trigger";
+    readonly mysql: "park_trigger VARCHAR(64) NULL";
+    readonly pg: "park_trigger VARCHAR(64) COLLATE \"C\"";
+};
 export declare const APPROVAL_BATCH_TABLE = "approval_batch";
 /**
  * TiDB/MySQL-protocol 侧的两条建表语句,**抽成导出数组**(车3 刀 3a):`tidb-pool.ts` 的

package/dist/plugins/approval-ask-store-sql.js

@@ -1,6 +1,6 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
-import { APPROVAL_ENDING_CAUSES, causeOfAskRow } from "../approval-deny-reasons.js";
+import { APPROVAL_ENDING_CAUSES, askRowEndingCause, askRowParkTrigger } from "../approval-deny-reasons.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
 import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
@@ -61,6 +61,18 @@ async function withReadSignal(op, signal, where) {
     }
 }
 export const POLICY_REFUSAL_DECISION = { decision: "deny", settledBy: "policy" };
+export function claimCauseColumn(intent) {
+    switch (intent) {
+        case "cancel":
+            return "ending_cause";
+        case "expire":
+            return "park_trigger";
+        default: {
+            const unreachable = intent;
+            throw new Error(`approval-ask-store: no cause column for terminal claim intent ${String(unreachable)}`);
+        }
+    }
+}
 export function claimTargetState(intent) {
     switch (intent) {
         case "expire":
@@ -78,14 +90,16 @@ export function claimTargetState(intent) {
 export function projectAskTerminalClaimTruth(row) {
     if (row === null || row.state === "STREAM_PENDING")
         return { state: "absent" };
-    const cause = causeOfAskRow(row);
+    const endingCause = askRowEndingCause(row);
+    const parkTrigger = askRowParkTrigger(row);
     return {
         state: row.state,
         rev: row.rev,
         decision: row.decision,
         ...(row.updatedInput !== undefined ? { updatedInput: row.updatedInput } : {}),
         settledBy: row.settledBy,
-        ...(cause !== undefined ? { cause } : {}),
+        ...(endingCause !== undefined ? { endingCause } : {}),
+        ...(parkTrigger !== undefined ? { parkTrigger } : {}),
     };
 }
 export function askRowOnCall(row, call) {
@@ -105,6 +119,16 @@ export const APPROVAL_ASK_EXECUTION_LANE_COLUMN = {
     mysql: "execution_lane VARCHAR(32) NOT NULL DEFAULT ''",
     pg: `execution_lane VARCHAR(32) COLLATE "C" NOT NULL DEFAULT ''`,
 };
+export const APPROVAL_ASK_ENDING_CAUSE_COLUMN = {
+    name: "ending_cause",
+    mysql: "ending_cause VARCHAR(64) NULL",
+    pg: `ending_cause VARCHAR(64) COLLATE "C"`,
+};
+export const APPROVAL_ASK_PARK_TRIGGER_COLUMN = {
+    name: "park_trigger",
+    mysql: "park_trigger VARCHAR(64) NULL",
+    pg: `park_trigger VARCHAR(64) COLLATE "C"`,
+};
 function executionLaneColumnOf(raw, askId) {
     const lane = typeof raw === "string" ? raw : "";
     if (!isExecutionLane(lane)) {
@@ -163,7 +187,10 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     -- 编辑实参是整只工具入参,VARCHAR/TEXT 会造静默截断面。语义三态与读法见 AskRow.updatedInput 顶注。
     updated_input LONGTEXT NULL,
     decided_at_ms BIGINT NULL,
-    denied_reason VARCHAR(64) NULL,
+    -- 成因两列,一列一义(语义见 AskRow.endingCause / AskRow.parkTrigger):ending_cause = 终态成因(到 VOID / DENIED 的转移写);
+    -- park_trigger = 转 park 的触发成因(只由 expire claim 写一次,终态不覆盖)。
+    ${APPROVAL_ASK_ENDING_CAUSE_COLUMN.mysql},
+    ${APPROVAL_ASK_PARK_TRIGGER_COLUMN.mysql},
     gate_token VARCHAR(120) NULL,
     gate_bound_call_id VARCHAR(255) NULL,
     gate_bound_input_hash VARCHAR(255) NULL,
@@ -244,7 +271,9 @@ export async function ensurePgApprovalAskSchema(q) {
     -- updated_input(S-26 / #304)—— MySQL 孪生逐字同形(语义/类型理由见那侧行内注;PG TEXT 无长度上限)。
     updated_input TEXT COLLATE "C",
     decided_at_ms BIGINT,
-    denied_reason VARCHAR(64) COLLATE "C",
+    -- 成因两列 —— MySQL 孪生逐字同形(语义见那侧行内注)。
+    ${APPROVAL_ASK_ENDING_CAUSE_COLUMN.pg},
+    ${APPROVAL_ASK_PARK_TRIGGER_COLUMN.pg},
     gate_token VARCHAR(120) COLLATE "C",
     gate_bound_call_id VARCHAR(255) COLLATE "C",
     gate_bound_input_hash VARCHAR(255) COLLATE "C",
@@ -290,7 +319,7 @@ function askCols(dialect) {
         jsonColumnText(dialect, "decision_actor"),
         "decision_note, settled_by",
         jsonColumnText(dialect, "updated_input"),
-        "decided_at_ms, denied_reason, gate_token",
+        "decided_at_ms, ending_cause, park_trigger, gate_token",
         "gate_bound_call_id, gate_bound_input_hash, idempotency_key",
         jsonColumnText(dialect, "card_json"),
         "rule_command, rule_scope_root, schema_version, expires_at_ms",
@@ -338,7 +367,8 @@ function mapAskRowBody(r, askId) {
         settledBy: strOrNull(r.settled_by),
         ...(r.updated_input == null ? {} : { updatedInput: decodeJsonColumn(r.updated_input, readTriStateJsonValueColumn, `${APPROVAL_ASK_TABLE}.updated_input for ask ${askId}`) }),
         decidedAtMs: numOrNull(r.decided_at_ms),
-        deniedReason: strOrNull(r.denied_reason),
+        endingCause: strOrNull(r.ending_cause),
+        parkTrigger: strOrNull(r.park_trigger),
         gateToken: strOrNull(r.gate_token),
         gateBoundCallId: strOrNull(r.gate_bound_call_id),
         gateBoundInputHash: strOrNull(r.gate_bound_input_hash),
@@ -373,8 +403,8 @@ function patchColumns(patch, json) {
         out.push(["decision_note", patch.decisionNote]);
     if (patch.decidedAtMs !== undefined)
         out.push(["decided_at_ms", patch.decidedAtMs]);
-    if (patch.deniedReason !== undefined)
-        out.push(["denied_reason", patch.deniedReason]);
+    if (patch.endingCause !== undefined)
+        out.push(["ending_cause", patch.endingCause]);
     if (patch.gateToken !== undefined)
         out.push(["gate_token", patch.gateToken]);
     if (patch.gateBoundCallId !== undefined)
@@ -427,9 +457,9 @@ export class SqlApprovalAskStore {
         try {
             await conn.begin();
             await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES (?, ?, 'OPEN', 0, ?, ?)`, `INSERT INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES ($1, $2, 'OPEN', 0, $3, $4) ON CONFLICT (batch_id) DO NOTHING`), [row.batchId, row.taskId, now, now]);
-            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
-                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $12, $13, $14, $15, $16, $17, $18) ON CONFLICT (ask_id) DO NOTHING"), [
+            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, ending_cause, park_trigger, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, ending_cause, park_trigger, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
+                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $12, $13, $14, $15, $16, $17, $18) ON CONFLICT (ask_id) DO NOTHING"), [
                 row.askId,
                 row.taskId,
                 row.sourceTaskId,
@@ -566,7 +596,7 @@ export class SqlApprovalAskStore {
                 ? await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, decision = ${ph(dialect, 2)}, settled_by = ${ph(dialect, 3)}, decided_at_ms = ${ph(dialect, 4)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 5)} WHERE ${pendingClaimWhere(dialect, 6)}`, [to, POLICY_REFUSAL_DECISION.decision, POLICY_REFUSAL_DECISION.settledBy, now, now, askId, batchId])
                 : (intent === "cancel" || intent === "expire") && opts?.cause !== undefined
                     ?
-                        await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, denied_reason = ${ph(dialect, 2)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 3)} WHERE ${pendingClaimWhere(dialect, 4)}`, [to, opts.cause, now, askId, batchId])
+                        await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, ${claimCauseColumn(intent)} = ${ph(dialect, 2)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 3)} WHERE ${pendingClaimWhere(dialect, 4)}`, [to, opts.cause, now, askId, batchId])
                     : await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 2)} WHERE ${pendingClaimWhere(dialect, 3)}`, [
                         to,
                         now,
@@ -585,7 +615,7 @@ export class SqlApprovalAskStore {
             await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=? WHERE batch_id=? AND state='OPEN'`, `UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='OPEN'`), [now, batchId]);
             let voidedSiblings;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -593,7 +623,7 @@ export class SqlApprovalAskStore {
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
                     const inList = voidedSiblings.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [
                         APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN,
                         now,
                         ...voidedSiblings,
@@ -639,7 +669,7 @@ export class SqlApprovalAskStore {
             }
             let voidedSiblings;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='PARKING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='PARKING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -647,7 +677,7 @@ export class SqlApprovalAskStore {
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
                     const inList = voidedSiblings.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='PARKING'`, [APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE, now, ...voidedSiblings]);
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='PARKING'`, [APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE, now, ...voidedSiblings]);
                 }
             }
             await conn.commit();
@@ -677,7 +707,7 @@ export class SqlApprovalAskStore {
             }
             let voided;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$3, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' RETURNING ask_id`, [now, batchId, APPROVAL_ENDING_CAUSES.BATCH_ABORTED]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=$3, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' RETURNING ask_id`, [now, batchId, APPROVAL_ENDING_CAUSES.BATCH_ABORTED]);
                 voided = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -685,7 +715,7 @@ export class SqlApprovalAskStore {
                 voided = sel.rows.map((r) => String(r.ask_id));
                 if (voided.length > 0) {
                     const inList = voided.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [APPROVAL_ENDING_CAUSES.BATCH_ABORTED, now, ...voided]);
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', ending_cause=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [APPROVAL_ENDING_CAUSES.BATCH_ABORTED, now, ...voided]);
                 }
             }
             await conn.commit();

package/dist/plugins/caching-session-store.d.ts

@@ -142,6 +142,12 @@ export declare class CachingSessionStore implements SessionStore {
      * 只读快照而非 getter:声明是店的构造期常量(会变的声明本身就是缺陷)。
      */
     readonly placements?: SessionStore["placements"];
+    /**
+     * 内层店的**会话耐久声明**(core `SessionStore.durability`,说的是未 placed 的会话)转发 —— 与 {@link retention} / {@link placements} 同一族教训:
+     * 生产默认把真店包进本类,core 的接线清单(`wiring_manifest.session.store`)与停驻自检读的就是包装层;不转发 = 一只声明了 `durable` 的店在默认部署上
+     * 读成 `process_local`(core 对缺席的 fail-closed 读法),没有任何一处报错。只读快照;缺席则不设。
+     */
+    readonly durability?: SessionStore["durability"];
     /** [ref]:placed 分区的两只读面(reap 分区腿 / 准入探针)——同款转发理由:reaper 与准入判据拿到的
      *  是包装层,不转发 = 分区腿静默不可用、暖命中的 claim 关门静默失效。缺席则不设(诚实降级)。 */
     readonly listPlaced?: (kind: "subagent", opts?: {

package/dist/plugins/caching-session-store.js

@@ -33,6 +33,7 @@ export class CachingSessionStore {
     replaceEntries;
     retention;
     placements;
+    durability;
     listPlaced;
     placementOf;
     constructor(inner, opts) {
@@ -43,6 +44,8 @@ export class CachingSessionStore {
         const declared = inner.retention;
         if (declared !== undefined)
             this.retention = declared;
+        if (inner.durability !== undefined)
+            this.durability = inner.durability;
         if (inner.placements !== undefined)
             this.placements = inner.placements;
         if (typeof inner.listPlaced === "function")

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

@@ -2,7 +2,10 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointGate, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolvedOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor, type StoreDurability, type StoreFidelity, type ToolApprovalCard } from "@sema-agent/core";
 import { type ParkRowFacts, type RuleOfferProjection, type SkillCardFacts } from "../approval-card.js";
+import type { KindlessBatchRowSource, KindlessBatchScan } from "../approval-batch-census.js";
 import { type SqlDialect, type SqlDriver } from "./sql-driver.js";
+import type { SqlRunStore } from "./run-store-sql.js";
+import type { FencedRun } from "./store-contracts.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
 /** ctx 行改写店腿的读数(两孪生同形):扫到的可读行 · 回写成的行 · 回写成的行里改写函数报的改动数 · 读不出的行 · 改写之后一行装不下的行。 */
@@ -59,7 +62,8 @@ export declare function tokenFingerprint(token: string): string;
  *  型与值都只有一个来源:`approval-card.ts` 的 {@link parkRowFacts}(两只店各读自己手里的那只寄存行 `pendingAction`,
  *  交给它、原样展开)。继承而不是在这里逐键再写一遍:core 给这一臂再加一位同类事实时,改的只有那张 Pick 表。
  *
- *  技能卡三位({@link SkillCardFacts}:`boundGrantDigest` / `boundGrants` / `classifierNoRuling`)另有一只投影 {@link skillCardFacts},输入是 core 的检查点摘要而不是
+ *  [ref]:授予绑定那一臂(`boundGrantDigest` / `boundGrantAbsence` 恰带其一)是 {@link ParkRowFacts} 的一部分,同样读自寄存行。
+ *  技能卡两位({@link SkillCardFacts}:`boundGrants` / `classifierNoRuling`)另有一只投影 {@link skillCardFacts},输入是 core 的检查点摘要而不是
  *  寄存行原值(清单只在哈希等于摘要时才配上 wire,校验点单点在 core —— 见 {@link skillCardFacts} 顶注);同一张行上与收件箱行逐字同值,在场才带。 */
 export interface PendingCheckpoint extends ParkRowFacts, SkillCardFacts {
     sessionId: string;
@@ -271,6 +275,12 @@ export declare const CHECKPOINT_ADDED_COLUMNS: ReadonlyArray<{
 export declare function assertCheckpointColumnSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>, dialect: SqlDialect): Promise<void>;
+/**
+ * 本店读者({@link boundedRuleOffers})**交给 core 读者的那份输入**:offer 扫描窗 {@link MAX_RULE_OFFER_SCAN} 与成员前缀帽({@link preboundBatchMembers})都扣在读之前,
+ * 不是列表的值原样透传。**唯一写法**:回读 / 铸行 / LOCAL 孪生三条腿与起服普查({@link SqlCheckpointStore.scanKindlessBatchRows} 的 `rule_suggestions` 载体)读同一份输入 ——
+ * 普查若对整只数组另判,「前 8 个成员合法、第 9 个是垃圾」的行本店读者读得出(走存量臂)而普查读不出,会把仍靠存量臂的行报成零。
+ */
+export declare function boundedReaderInput(raw: unknown): unknown;
 /**
  * `pendingAction.ruleOffers` 的**铸行侧**投影(mint 面,与 {@link boundedToolInput} 同位同待遇)。
  *
@@ -460,8 +470,17 @@ interface SteerColumnRead {
  * 列有内容却读不出 ⇒ `lossy`(两个调用点对它的处置见 {@link SteerColumnRead})。
  */
 export declare function readPendingSteerQueueColumn(queueRaw: unknown): SteerColumnRead;
+/** 认领栅栏下改写一行 ctx 的结局(闭集;SQL / local 两孪生同词):`written` 写了;`claim_released` 接下改写的那条腿此刻已不持有这条 run(认领放了 / 不在跑 / 腿判据答否)⇒ 零写;
+ *  `context_absent` 持有、但会话没有 ctx 行 ⇒ 零写(不建行)。 */
+export declare const CTX_CLAIM_REWRITES: readonly ["written", "claim_released", "context_absent"];
+export type CtxClaimRewrite = (typeof CTX_CLAIM_REWRITES)[number];
+/** SQL checkpoint 店的装配选项:托管留存声明 + ctx 改写的认领栅栏(同一只池上的 run 店)。 */
+export interface SqlCheckpointStoreOptions {
+    readonly retention?: RetentionDeclaration;
+    readonly claims?: SqlRunStore;
+}
 /** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
-export declare class SqlCheckpointStore implements CheckpointStore {
+export declare class SqlCheckpointStore implements CheckpointStore, KindlessBatchRowSource {
     protected readonly db: SqlDriver;
     protected readonly logger?: {
         info?(msg: string, meta?: unknown): void;
@@ -514,11 +533,12 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     readonly execution: {
         readonly outcome: true;
     };
+    /** ctx 改写的认领栅栏({@link SqlCheckpointStore.rewriteCtxWhileClaimed}):后端装配绑**同一只池**上的 run 店(`plugins/store-backend.ts` 的 `checkpoint()`)。
+     *  缺席 ⇒ 那一口响亮抛(装配缺陷),其余口不读它。 */
+    private readonly claims;
     constructor(db: SqlDriver, logger?: {
         info?(msg: string, meta?: unknown): void;
-    } | undefined, opts?: {
-        readonly retention?: RetentionDeclaration;
-    });
+    } | undefined, opts?: SqlCheckpointStoreOptions);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** JSON column binding. TiDB: plain `JSON.stringify`, stored verbatim. PG: `pgProtocolJsonStringify` —
@@ -691,18 +711,19 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      */
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
     /**
-     * 🔴 [ref] —— 运维队列行的**技能卡三位**({@link SkillCardFacts})。值与收件箱行同源:core `summarizeCheckpoint` 对同一行投的摘要,经 {@link skillCardFacts} 这一只投影。
+     * 🔴 [ref] —— 运维队列行的**技能卡两位**({@link SkillCardFacts}:清单 / 成因词)。值与收件箱行同源:core `summarizeCheckpoint` 对同一行投的摘要,经 {@link skillCardFacts} 这一只投影。
+     * (授予绑定那一臂 —— 摘要 / 缺席词 —— 不在这里:[ref] 起由 {@link parkRowFacts} 读子树投出,本读口失败时它照在。)
      *
-     * 为什么不像 {@link parkRowFacts} 那几位一样直接读 `pendingAction` 子树原值:三位里的**清单** `boundGrants` 在寄存行上是未经哈希校验的原值,core 只在摘要里「哈希等于摘要」
+     * 为什么不像 {@link parkRowFacts} 那几位一样直接读 `pendingAction` 子树原值:**清单** `boundGrants` 在寄存行上是未经哈希校验的原值,core 只在摘要里「哈希等于摘要」
      * 才发布它(「never a list beside a digest that binds another」);校验读口与哈希函数都不在 core 的公开导出面上,本仓既算不出也不该再写一份 ——
      * 于是要拿到校验过的清单,只有对这一行跑 core 的 `summarizeCheckpoint`,而它吃的是整只 {@link Checkpoint}(不是子树)。
      *
-     * 读放大(如实):**只对行上真带三位之一的行**(摘要是串,或成因词键在场 —— {@link parkRowCarriesSkillCardFacts})多读该行一次整只快照;普通卡(绝大多数行)零额外读,
-     * 主 SELECT 仍只取 `pendingAction` 子树(NP-3 不退)。这是一个**只增不改的代价**:带三位之一的待决行数 × 读次数(`/stream` 每连接每 3s 一拍)。
-     * 🚧 清单校验读口成为 core 公开导出的那一版,本读口与门一并退役,三位改走 `parkRowFacts` 读原值经 core 的读口 —— 零额外读。
+     * 读放大(如实):**只对行上可能带两位之一的行**(摘要是串,或成因词键在场 —— {@link parkRowCarriesSkillCardFacts})多读该行一次整只快照;普通卡(绝大多数行)零额外读,
+     * 主 SELECT 仍只取 `pendingAction` 子树(NP-3 不退)。这是一个**只增不改的代价**:带两位之一的待决行数 × 读次数(`/stream` 每连接每 3s 一拍)。
+     * 🚧 清单校验读口成为 core 公开导出的那一版,本读口与门一并退役,两位改走 `parkRowFacts` 读原值经 core 的读口 —— 零额外读。
      *
      * 失败方向与 {@link readParkRowActionCell} 逐字同一条判据(展示/分诊材料、行级容忍 + 响亮、同一个 tag):整只快照在场却不是一只合法的检查点(读回的体坏了,或 core 的摘要读不动它)
-     * ⇒ 只丢**这一行**的三位;行已不在待决(两次读之间被决/过期)⇒ 三位缺席;`not-text`(读腿漏了投影)原样抛。
+     * ⇒ 只丢**这一行**的两位(授予绑定那一臂照在);行已不在待决(两次读之间被决/过期)⇒ 两位缺席;`not-text`(读腿漏了投影)原样抛。
      */
     private readParkedSkillCardFacts;
     /**
@@ -836,6 +857,23 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      *  reader the read leg uses — BEFORE the statement runs: refuse loudly, leave the row on disk untouched. */
     putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
     getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
+    /**
+     * **认领栅栏下改写既有 ctx 行** —— 在飞 run 的切档口(`http/routes/run-permission-mode.ts`)把准入的模式词写回存储体的唯一写口。
+     *
+     * 规则:只有**接下这笔改写的那条腿**此刻仍持有这条 run 时才写 —— `taskId` 持有 `sessionId` 的会话认领、这条 run 在跑、且调用方的腿判据 `legHolds`
+     * 对锁住那一行的 {@link FencedRun} 答是(认领与 `running` 只认 taskId:续跑腿让同一个 taskId 停驻之后回到 `running`、认领仍在,旧腿迟到的改写不许盖掉续跑的新腿
+     * 写下的体 —— 那是 ABA,只有腿判据分得开;今天的腿身份 = 副本 `instanceId`(续跑的 CAS 赢点改写它)∧ 调用方进程里这条 run 的活流仍是接下改写的那一只)。
+     * 写在所绑 run 店的认领栅栏事务里
+     * (`SqlRunStore.whileHoldingClaim`:先锁 run 行、再锁认领行 —— 与终局 / 收割同序 —— 刷新活性,本口的锁读 + UPDATE 在同一个事务连接上)。
+     * 于是「这条 run 终局放掉认领 → 同会话新 run 写下它自己的 ctx → 本口迟到的改写」这一序**结构上不可能**盖掉新 run 的行:终局要等本事务提交才拿得到
+     * run 行的锁,拿到之后本口再来就判出不持有、一个字节都不写。`putCtx` 的无条件 upsert 只给持有认领的那几条腿自己的写点(提交 / 续跑 CAS 赢点)用;
+     * 不在腿里的写者走这一口。
+     * 只改**既有**行(锁读零行 ⇒ `context_absent`,不建行):切档改的是这条 run 提交时写下的那一行,没有那一行就没有要改的存储体。
+     * 结局闭集 {@link CtxClaimRewrite}:`written` / `claim_released`(接下改写的那条腿已不持有这条 run —— 认领放了 / 不在跑 / 腿判据答否:零写)/ `context_absent`(持有、无行:零写)。
+     * 腿判据在栅栏里同步问一次(锁已持有、写之前);它只读、不许 await。
+     * 编码与形闸同 {@link SqlCheckpointStore.putCtx}(写之前判,坏形响亮拒、盘上不动);一行装不下 ⇒ `StoreRowTooLargeError`。
+     */
+    rewriteCtxWhileClaimed(sessionId: string, taskId: string, ctx: SealedCheckpointCtx, legHolds: (run: FencedRun) => boolean): Promise<CtxClaimRewrite>;
     /**
      * 🔴 **一次性迁移的 ctx 行改写店腿**({@link CheckpointCtxRowsRewriter};用它的迁移与各自的行改写见那里,窗与删法见 `plugins/one-time-migrations.ts` 登记表;
      * 本店不知道改写是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`
@@ -845,6 +883,20 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * ⇒ 不计、不重试(新写者是本版写下的、已是新形;是旧版副本就由之后的起服再扫到)。一行装不下(如封签比明文长)⇒ 计 `tooLarge`、那一行留原样,其余照扫。
      */
     rewriteCtxRows(rewrite: CtxRowRewrite): Promise<CtxRowsRewrite>;
+    /**
+     * 起服普查的读口({@link KindlessBatchRowSource};用法、范围与『为什么只数不改』见 `approval-batch-census.ts` 头注)—— 两个 SQL 方言**同一份实现**:
+     * 按 `token` 键集分页扫 `checkpoint`(所有状态的行),取两个载体,**各按它的读者判**(判官都是 core `readRuleOffers` 给读出的 batch 打的 `kindlessForm` 记号,
+     * {@link countKindlessBatchOffers};一行里任一载体带旧形成员即算一行):
+     *  · `rule_suggestions` 列(审批候选的落列)—— 读者是本店的回读口,吃的是 {@link boundedReaderInput}(扫描窗 + 成员前缀帽);普查读同一份输入;
+     *  · blob 里 `pendingAction.ruleOffers`(引擎铸、本店原样存、`put` 不校验)—— 读者是引擎(整只数组,没有本店的窗),普查读整只数组;在场却不是列表 ⇒ 数进 `unreadableCells`。
+     * 预筛(只为省传输,**不是判官**):`rule_suggestions` 是原样存的 TEXT(转义写法可以不同于 `JSON.stringify`),所以只问 `IS NOT NULL`,不做字符串匹配;
+     * blob 是 JSON 承载列(MySQL 协议 JSON / PG jsonb 入库即规范化),它的 `pendingAction` 子树文本里一个字符串值 `batch` 恒以 `"batch"` 字面出现 ⇒ `LIKE '%"batch"%'` 对它是完备的
+     * (空白不同无妨:MySQL 协议 `"kind": "batch"`)。
+     * 读不出形的 cell(坏 JSON / 不是列该有的形;读口是 {@link decodeNullableJsonColumn} 同一只,只容忍「体」的问题,读腿漏投影的 `not-text` 原样抛)不计入行,
+     * 数进 `unreadableCells`(到不了读者,但不静默:`rule_suggestions` 坏 cell 在队列读面有 `server.approvals.rule-suggestions-cell-unreadable`,普查另出 warn)。
+     * 行指纹 = {@link tokenFingerprint}(token 是机密,永不进遥测)。**只读**:不改任何一行;逐页读、**不是原子快照**(页间别的副本的写入可以让一行被漏数或多数一行)。
+     */
+    scanKindlessBatchRows(): Promise<KindlessBatchScan>;
     /**
      * GC ctx rows whose lifecycle is over (bound to the checkpoint, don't leak):
      * a session with NO pending checkpoint, NO active run, AND not touched since `cutoff`.
@@ -883,16 +935,12 @@ export declare class SqlCheckpointStore implements CheckpointStore {
 export declare class TiDBCheckpointStore extends SqlCheckpointStore {
     constructor(pool: MySqlPool, logger?: {
         info?(msg: string, meta?: unknown): void;
-    }, opts?: {
-        readonly retention?: RetentionDeclaration;
-    });
+    }, opts?: SqlCheckpointStoreOptions);
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgCheckpointStore extends SqlCheckpointStore {
     constructor(pool: PgPool, logger?: {
         info?(msg: string, meta?: unknown): void;
-    }, opts?: {
-        readonly retention?: RetentionDeclaration;
-    });
+    }, opts?: SqlCheckpointStoreOptions);
 }
 //# sourceMappingURL=checkpoint-store-sql.d.ts.map