@sema-agent/server 7.134.0 → 7.136.0

package/dist/plugins/checkpoint-index-columns.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `checkpoint` 表的**索引列**:怎么写(一只派生)、到期 facet 怎么从列上读(一只生成谓词)。SQL 两孪生的写口(`checkpoint-store-sql.ts` `put`)、
+ * 一次性迁移 M29 的存量回填(`one-time-migrations.ts`)与到期两条腿(`reapExpired` / `listExpiredApprovalGates`)都只读本模块。
+ *
+ * ## 写:一只派生 = core `checkpointIndexFacts(cp)`(core 7.55.0 [ref] P1 阶段二)
+ * 行上「core 铸下、此后不动」的十三个事实(令牌、scope、会话、格式版本、门型、卡、待决工具的名 / 调用 id / 入参摘要、deadline、铸行时刻、风险描述符、
+ * 双向控制字符在场位),每一个都由 core 那一只函数答;本模块只把它们落到列名下({@link buildCheckpointIndexCells})。修前写口自己从寄存行 / 门上逐格读,
+ * 对任何寄存臂、任何门都不分臂 —— 与 core 读法在契约外的行上答两样(计划门上的卡、审阅寄存行上的工具位)。键表对 core 的事实键闭合
+ * ({@link CHECKPOINT_INDEX_COLUMNS} `satisfies Record<keyof CheckpointIndexFacts, …>`):core 加 / 删一个事实 ⇒ 编译红,由人决定它落不落列。
+ * 不在这里的:CAS 面推动的状态(`status` / `rev` / `reopen_reason` / 执行记录)、部署铸的值(`terminal_at_ms` 兜底)、部署截长脱敏的展示投影(`tool_input` /
+ * `rule_suggestions`)—— 它们不是行的不变事实,core 也不答。
+ *
+ * ## 写之前:一只判官 = {@link judgeCheckpointIndexCells}
+ * 一份文档能不能落进这些列,在写之前由**同一只**判官答 —— 写口 `put` 与 M29 的存量回填都问它,界不抄第二份。三个答案:`cells`(放得下,列格在手);`unreadable`(门或待决动作
+ * 不是对象 —— core 的派生按这两棵读,读不了会抛裸 TypeError,或对非对象照写出垃圾列格;引擎的 `judgeAsStored` 在 put 之前拦着,所以这样的文档只来自嵌入方 / 手改数据);
+ * `card_too_long`(卡词的 UTF-8 字节超出方言的列容量 {@link APPROVAL_CARD_COLUMN_MAX_BYTES} —— 严格 sql_mode 下库抛 `Data too long`,非严格下静默截成半只卡词,两形都不许到库)。
+ * 写口把后两个答案翻成类型化拒 {@link CheckpointIndexRefusedError}(零写);M29 把它们记成收据(计数 + 点名,不挡起服)。
+ *
+ * ## 读:到期 facet 是由 core 两张表**生成**的一条 SQL 表达式
+ * facet = 部署收割器对一行的 deadline 的读法(`A` = 审批门,deadline 是 SLA 拒;`B` = 无人值守 TTL,到期作废;`-` = 非门停驻)。core 的判官是
+ * `facetOf(gate)`:门上的卡是 `CARD_FACET_OVERRIDES` 的键 ⇒ 那个键的 facet,否则门型在 `PAUSE_REGISTRY` 的 `facet` 列。列上存的是卡词本身
+ * (`approval_card`,不是 facet —— 存一份 facet 会在 core 改表那天陈旧),谓词由那两张表机械生成({@link CHECKPOINT_FACET_CASES} → {@link CHECKPOINT_FACET_SQL}),
+ * 逐行与 `facetOf` 同答(`test/checkpoint-index-columns.test.ts` B 节、db 组同名文件)。本仓不写第二份判据:没有手写门型表、没有手写卡词。
+ * 卡那一侧不带「是不是审批门」的合取:列上的卡只在审批门上非 NULL(同一只派生),与 core 对生成谓词的成文形逐字相同。未登记门型 / NULL 门型 ⇒ 表达式 NULL(无 ELSE)。
+ * 拒扫腿的选行序见 {@link CHECKPOINT_SWEEP_ORDER_SQL}:卡列有词的行先取 —— 混跑窗里旧副本写的行卡列为空,它们的 facet 要等下一次起服的 M29 才确证。
+ *
+ * ## 谓词什么时候开
+ * core 的迁移条款:存量行的卡列由同一只函数回填,并且只在部署自己记下「回填跑完了」之后才开生成谓词。本仓的记录 = 起服序列:M29 跑在一次性迁移段
+ * (`boot/stores.ts`,先于任何路由与收割器装配),跑不完就拒启 —— 所以每只副本的收割器只在本次起服的 M29 完成之后才运行。混跑期间旧副本新写的行
+ * 不带卡列(它们不认这一列),由下一次起服的 M29 补上;升级序见 MIGRATION 7.135.0 节(同一只库不混跑两版)。
+ */
+import { PAUSE_REGISTRY, type Checkpoint, type CheckpointIndexFacts, type GateKind, type RiskDescriptor } from "@sema-agent/core";
+import type { SqlDialect } from "./sql-driver.js";
+/** 每个索引事实落在哪一列(键表对 core 的事实键闭合:core 加 / 删一个事实 ⇒ 编译红)。 */
+export declare const CHECKPOINT_INDEX_COLUMNS: {
+    readonly token: "token";
+    readonly scope: "scope";
+    readonly sessionId: "session_id";
+    readonly version: "version";
+    readonly gateKind: "gate_kind";
+    readonly approvalCard: "approval_card";
+    readonly toolName: "tool_name";
+    readonly toolCallId: "tool_call_id";
+    readonly boundInputHash: "bound_input_hash";
+    readonly deadline: "deadline";
+    readonly createdAt: "created_at_ms";
+    readonly riskDescriptor: "risk_descriptor";
+    readonly hasBidiControls: "has_bidi_controls";
+};
+type IndexColumnOf<K extends keyof CheckpointIndexFacts> = (typeof CHECKPOINT_INDEX_COLUMNS)[K];
+/**
+ * 一行的索引列格:core 的事实落在列名下。值逐字是事实本身,只有一处换形:双向控制字符在场位落 `1` 或 NULL(列是 TINYINT / SMALLINT,恒不写 0 —— core 的契约
+ * 是「`true` 或缺席」,0 会把「没检出」谎成「已确认干净」)。描述符是行自己的对象,写口负责编码(两方言的 JSON 编码器不同)。
+ */
+export type CheckpointIndexCells = {
+    readonly [K in keyof CheckpointIndexFacts as IndexColumnOf<K>]: K extends "hasBidiControls" ? 1 | null : K extends "riskDescriptor" ? RiskDescriptor | null : CheckpointIndexFacts[K];
+};
+/** 一行的索引列格(纯数据;写口与 M29 回填同调这一只 —— 回填不另读门子树自算)。 */
+export declare function buildCheckpointIndexCells(cp: Checkpoint): CheckpointIndexCells;
+/**
+ * `approval_card` 列放得下的卡词**字节数**(UTF-8 字节,不是字符数),按方言各一格(键表对 {@link SqlDialect} 闭合:加一种方言 ⇒ 编译红)。
+ * MySQL 协议(TiDB / MySQL)的列型是 `TEXT`,上限 65,535 字节 —— 严格模式下超长写入抛 `Data too long`,非严格模式静默截成半只卡词;PG 的 `TEXT` 没有这个上限。
+ * 列型的属主是中央 DDL(`tidb-pool.ts` / `pg-pool.ts` 的 `approval_card`),本表只是那一列的容量事实(`test/checkpoint-index-columns.test.ts` 把两处同读,换列型 ⇒ 红)。
+ * 引擎照存集外词、长度不由本仓定,但引擎铸得出的卡词是闭集短词 —— 超出容量的只会是手改 / 外来写者写下的文档;读这张表的只有 {@link judgeCheckpointIndexCells}
+ * (写口超出 ⇒ 类型化拒,M29 超出 ⇒ 计数 + 点名跳过、不挡起服)。
+ */
+export declare const APPROVAL_CARD_COLUMN_MAX_BYTES: Readonly<Record<SqlDialect, number>>;
+/**
+ * 一份文档对索引列的判决(闭集:加一种答案 ⇒ 读它的 `switch` 编译红)。
+ *  · `cells` —— 放得下,列格在手;
+ *  · `unreadable` —— `member` 指的那一棵(`gate` / `pendingAction`)不是对象:core 的派生读不了它;
+ *  · `card_too_long` —— 门上的卡词按 UTF-8 字节超出方言的列容量(`bytes` > `maxBytes`)。
+ */
+export type CheckpointIndexJudgement = {
+    readonly kind: "cells";
+    readonly cells: CheckpointIndexCells;
+} | {
+    readonly kind: "unreadable";
+    readonly member: "gate" | "pendingAction";
+} | {
+    readonly kind: "card_too_long";
+    readonly bytes: number;
+    readonly maxBytes: number;
+};
+/** 不是 `cells` 的两个答案 —— 写口把它们带进 {@link CheckpointIndexRefusedError}。 */
+export type CheckpointIndexRefusal = Exclude<CheckpointIndexJudgement, {
+    readonly kind: "cells";
+}>;
+/**
+ * **写之前**的唯一判官(写口 `put` 与 M29 回填共读;理由见头注「写之前」)。先看门与待决动作是不是对象 —— `Checkpoint` 的类型说它们必填,但嵌入方 /
+ * 手改数据不受类型约束,而 core 的 `checkpointIndexFacts` 对缺门 / 缺待决动作抛裸 TypeError、对非对象的门写出 `gate_kind` 为 undefined 的列格 ——
+ * 再派生,最后按方言的列容量数卡词的 UTF-8 **字节**(不是字符数)。纯函数:不读钟、不写任何东西。
+ */
+export declare function judgeCheckpointIndexCells(cp: Checkpoint, dialect: SqlDialect): CheckpointIndexJudgement;
+/**
+ * 写口 `put` 对一份放不进索引列的文档的拒(类型化,零写;`refusal` 是机读位,与 M29 收据读的是同一个判决)。这是店错误,不是 wire 码 —— 调用方(引擎的停驻写、嵌入方)
+ * 怎么收场由它们决定;句子不带卡词本身(卡词是外来数据,只报字节数)。
+ */
+export declare class CheckpointIndexRefusedError extends Error {
+    readonly refusal: CheckpointIndexRefusal;
+    constructor(sessionId: unknown, refusal: CheckpointIndexRefusal);
+}
+/** facet 的词(core 登记表 `facet` 列的值域)。 */
+type Facet = (typeof PAUSE_REGISTRY)[GateKind]["facet"];
+/** 生成谓词的一条 WHEN:某一列的值落在这几个词里 ⇒ 这个 facet。 */
+export interface FacetCase {
+    readonly column: typeof CHECKPOINT_INDEX_COLUMNS.approvalCard | typeof CHECKPOINT_INDEX_COLUMNS.gateKind;
+    readonly words: readonly string[];
+    readonly facet: Facet;
+}
+/**
+ * 生成谓词的 WHEN 表:先卡(`CARD_FACET_OVERRIDES` 的键 ⇒ 它的 facet),后门型(`PAUSE_REGISTRY` 每一行 ⇒ 它的 `facet` 列)。第一条命中的赢;都不中 ⇒ NULL。
+ * 纯数据,只由 core 那两张表生成 —— 零手写词。
+ */
+export declare const CHECKPOINT_FACET_CASES: readonly FacetCase[];
+/**
+ * 一行的到期 facet,按方言各一份(同一张 WHEN 表):`CASE WHEN approval_card IN (…) THEN 'B' WHEN gate_kind IN (…) THEN 'A' … END`(无 ELSE ⇒ 未登记门型读 NULL)。
+ * 两份的差别只在「列怎么比」:引擎按**字节**认词(`'question '` 是集外词),而 MySQL 协议表的 `utf8mb4_bin` 是 PAD SPACE 排序(比较时忽略尾空格,`'question '` = `'question'`)
+ * ⇒ 那一方言两列按 `CAST(… AS BINARY)` 比(变长二进制串逐字节比,不补位);PG 的 `varchar` / `text` 比较本来不补位,列原样。
+ * 列名不带表限定:两条读腿都只查 `checkpoint` 一张表。拒扫腿读 `= 'A'`,收割的作废分支读 `COALESCE(…, '') <> 'A'`(NULL 门型的行走作废,与修前同向)。
+ */
+export declare const CHECKPOINT_FACET_SQL: Readonly<Record<SqlDialect, string>>;
+/**
+ * SLA 拒扫腿(`listExpiredApprovalGates`)的选行序:**卡列有词的行先取**,其后 deadline、token。卡列为 NULL 的审批行有两种来历 —— 引擎没给卡的门(照常是审批 SLA),或混跑窗里
+ * 不认这一列的旧副本写的行(可能是引擎要拒收 `sla_timeout` 的问答卡,facet 要等下一次起服的 M29 回填才确证);列上没有任何东西能把两者分开,所以不在谓词里猜,而在序里:
+ * 有卡词的行 facet 已确证,先占窗;卡列为空的行排在它们之后,各自仍按 deadline 升序。LIMIT 仍是调用方的界,不加旋钮。两方言同一句(`CASE` 在 MySQL 协议与 PG 上同形)。
+ */
+export declare const CHECKPOINT_SWEEP_ORDER_SQL = "CASE WHEN approval_card IS NULL THEN 1 ELSE 0 END ASC, deadline ASC, token ASC";
+export {};
+//# sourceMappingURL=checkpoint-index-columns.d.ts.map

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

@@ -0,0 +1,90 @@
+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,
+};
+export function judgeCheckpointIndexCells(cp, dialect) {
+    const gate = cp.gate;
+    if (typeof gate !== "object" || gate === null)
+        return { kind: "unreadable", member: "gate" };
+    const pendingAction = cp.pendingAction;
+    if (typeof pendingAction !== "object" || pendingAction === null)
+        return { kind: "unreadable", member: "pendingAction" };
+    const cells = buildCheckpointIndexCells(cp);
+    if (cells.approval_card !== null) {
+        const bytes = Buffer.byteLength(cells.approval_card, "utf8");
+        const maxBytes = APPROVAL_CARD_COLUMN_MAX_BYTES[dialect];
+        if (bytes > maxBytes)
+            return { kind: "card_too_long", bytes, maxBytes };
+    }
+    return { kind: "cells", cells };
+}
+export class CheckpointIndexRefusedError extends Error {
+    refusal;
+    constructor(sessionId, refusal) {
+        const where = `the checkpoint row for session ${JSON.stringify(sessionId) ?? "(none)"} was not written`;
+        super(refusal.kind === "unreadable"
+            ? `${where}: its document carries no \`${refusal.member}\` object — the index columns are derived from the gate and the pending action, so a document without one cannot be parked`
+            : `${where}: the approval card word is ${refusal.bytes} UTF-8 bytes and the approval_card column holds at most ${refusal.maxBytes} on this database`);
+        this.name = "CheckpointIndexRefusedError";
+        this.refusal = refusal;
+    }
+}
+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),
+});
+export const CHECKPOINT_SWEEP_ORDER_SQL = "CASE WHEN approval_card IS NULL THEN 1 ELSE 0 END ASC, deadline ASC, token ASC";
+//# sourceMappingURL=checkpoint-index-columns.js.map

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

@@ -1,7 +1,7 @@
 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 } from "../approval-card.js";
+import { type ParkRowFacts, type RuleOfferProjection, type SkillCardFacts } from "../approval-card.js";
 import { type SqlDialect, type SqlDriver } from "./sql-driver.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
 /** M28 店腿的读数(两孪生同形;随 M28 删):扫到的可读行 · 回写成的行 · 回写成的行里被改写的值 · 读不出的行 · 封好之后一行装不下的行。 */
@@ -41,10 +41,13 @@ 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 {
+ *  交给它、原样展开)。继承而不是在这里逐键再写一遍:core 给这一臂再加一位同类事实时,改的只有那张 Pick 表。
+ *
+ *  技能卡三位({@link SkillCardFacts}:`boundGrantDigest` / `boundGrants` / `classifierNoRuling`)另有一只投影 {@link skillCardFacts},输入是 core 的检查点摘要而不是
+ *  寄存行原值(清单只在哈希等于摘要时才配上 wire,校验点单点在 core —— 见 {@link skillCardFacts} 顶注);同一张行上与收件箱行逐字同值,在场才带。 */
+export interface PendingCheckpoint extends ParkRowFacts, SkillCardFacts {
     sessionId: string;
     /**
      * 这道停驻门的**非秘密稳定身份**(core `Checkpoint.checkpointId`,引擎每次停驻铸)—— 三处 durable 读面(本行 = `GET /v1/approvals` 的 `pending[]`
@@ -71,7 +74,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 +134,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 +148,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 +224,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 +237,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 +259,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 +289,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 +365,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 +410,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 +501,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 +580,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,59 +643,63 @@ 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.
+     *
+     * Order ({@link CHECKPOINT_SWEEP_ORDER_SQL}): rows whose `approval_card` column carries a word come first, then rows whose card
+     * is NULL, each by deadline. A NULL card on an approval gate is either a gate the engine gave no card (a real SLA row) or a
+     * row a replica that does not know the column wrote during a mixed-version window — possibly a question, which the engine
+     * refuses to deny (`sla_timeout`) and which the next boot's M29 backfill settles. The column cannot tell the two apart, so the
+     * order does: rows whose facet is certain take the window first and a straggler cannot crowd them out.
      */
     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`」不是「缺席=未知」,而是「这一格在这条读面上不存在」。
      * 真正需要它的读面是**已决行**的那一条:`findDecidedApprovalsForBinding`(decide 幂等回放),见那里。
      */
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
+    /**
+     * 🔴 [ref] —— 运维队列行的**技能卡三位**({@link SkillCardFacts})。值与收件箱行同源:core `summarizeCheckpoint` 对同一行投的摘要,经 {@link skillCardFacts} 这一只投影。
+     *
+     * 为什么不像 {@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 readParkRowActionCell} 逐字同一条判据(展示/分诊材料、行级容忍 + 响亮、同一个 tag):整只快照在场却不是一只合法的检查点(读回的体坏了,或 core 的摘要读不动它)
+     * ⇒ 只丢**这一行**的三位;行已不在待决(两次读之间被决/过期)⇒ 三位缺席;`not-text`(读腿漏了投影)原样抛。
+     */
+    private readParkedSkillCardFacts;
     /**
      * [ref] #2 (scheduler seam, core 1.105): a scope's PENDING checkpoints as lightweight
      * {@link CheckpointSummary} rows in ONE query — the cross-task triage view a supervisor scheduler needs
@@ -811,11 +813,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 +849,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