@sema-agent/server 7.133.0 → 7.135.0

package/dist/plugins/one-time-migrations.d.ts

@@ -1,6 +1,6 @@
 /**
  * 🔴 **一次性迁移段 —— 每一条都有窗;窗、删法与删码后存量旧形由谁接住,逐条只写在下面的 {@link ONE_TIME_MIGRATIONS}
- * 登记表里**(唯一属主,S-590)。硬 breaking 纪律:持久数据面 = **响亮拒 + 一次性迁移,窗过即删,永不长期双读**。
+ * 登记表里**(唯一属主,[ref])。硬 breaking 纪律:持久数据面 = **响亮拒 + 一次性迁移,窗过即删,永不长期双读**。
  *
  * ## 窗(规则写在这里一次,日期只在登记表)
  * 窗 = 引入该条的版本的发布日 + 30 天(`removableAfter`);窗关之后的第一个 minor 删该条的码(删什么 = 那一行的 `removal`)。
@@ -13,37 +13,31 @@
  * 最后一条删掉时,整个文件连同 `StoreBackend.runOneTimeMigrations()`(npm 公面上的接口成员)、`NO_SQL_MIGRATIONS`、
  * `logOneTimeMigrations` / `runAndLogOneTimeMigrations`、三只后端与两只测试夹具上的实现、`boot/stores.ts` 的调用点一起删 —— 零例外:本文件里只有带窗的迁移与它们自己的
  * 帮手(两只在场探针、锁腿、方言适配器);没有窗的东西(跳版升级的库的拒启臂)住在起服对账一族(`schema-consistency.ts`),不在这里。
- * 其余文件一律只写「窗口见本文件登记表」,不各写一个日期或版本 —— S-590 之前本文件头写死了一个删除版本号(7.75.0),
- * 连同 11 个文件里的复述共 23 行;那一版过去了 28 个 minor 也没删,7.93.5 反倒往本文件里又加了 M4。
+ * 其余文件一律只写「窗口见本文件登记表」,不各写一个日期或版本 —— [ref] 之前本文件头写死了一个删除版本号(7.75.0),
+ * 连同 11 个文件里的复述共 23 行;那一版过去了 28 个 minor 也没删,7.93.5 反倒往本文件里又加了一条迁移。
  *
  * ## 为什么这一段存在,以及为什么它必须短命
- * 本仓的退役落在**已经写进库里的字节**上(例:审计明细里「没有明细」的第二种写法 —— JSON 文本 `null`,7.93.5 引入)。这类旧读法
+ * 本仓的退役落在**已经写进库里的字节**上(例:引擎换了名的停驻行披露键 —— 旧键只在存量字节里还有)。这类旧读法
  * 此前各自靠一条**长期兼容臂**活着(探针 / 折叠读 / 改名表 / 读侧容忍),而兼容臂是最坏的一种持久层欠债:它没有到期日,
  * 读腿与写腿从此对同一份字节有两种理解,而下一个人只看得到「有两条路」这个事实、看不到「哪一条是真的」。
  *
  * ⇒ 换成本段:**升一次级把存量字节改完,兼容臂当场删干净**。代价是每一条在它的窗内每次启动都要跑一遍(第二次起全是
  * 零命中的空转);收益是窗关之后可以把那一条连同它的 SQL 一起删,而读腿从引入那一版起就只有**一种**读法。
  *
- * ## 已退役的 M1–M3
+ * ## 已退役的 M1–M4
  * 退役的整树快照索引表(M1)、退役的单座 steering 列(M2)、被上游改了名的闭集词 `unresolvable` → `ancestor_marked`(M3)三条的改写、计数与读数
  * 窗关后已全部删码,登记行一并删。跳过了它们直接升的库由起服对账一族的拒启臂接住(`schema-consistency.ts` 头注「第二道对账」一节:两件退役 schema
  * 任一在场 ⇒ 拒启、点名出路;先于一切建表)—— 那一道没有窗,所以不在本文件里。本段入口({@link runSqlOneTimeMigrations})不问这一问。
+ * 审计明细里的 JSON 文本 `null`(M4:`device_audit.detail` 里「没有明细」的另一种写法)同样窗关后已删码,登记行一并删;它没有拒启臂 —— 跳过了它直接升的库,
+ * 含这种旧行的那一页审计由 `device-store-sql.ts` 的 `listAudit` 读形拒接住(一行读不出形 ⇒ 整页拒,拒句点名行 id;刻意不逐行隔离),出路是运维把那些行的 `detail` 置成 SQL NULL(MIGRATION 写了语句)。
  *
  * ## 窗内的迁移(逐条的失败方向刻意不同)
- *  · **M4 审计明细里的 JSON 文本 `null`** —— S-550 把 `device_audit.detail` 的读回收进唯一属主并判形之后,
- *    「这条审计没有明细」在盘上**只剩一种**表示(列 NULL);而 7.93.4 及更早的写腿对**显式** `detail: null`
- *    会写下 JSON 文本 `null`(写口 `input.detail === undefined ? null : json(input.detail)`)。那种旧行在新读腿
- *    下是坏体 ⇒ `listAudit` 整页 5xx。持久数据面是**唯一不能「翻红」的面**(CLAUDE.md 硬 breaking 三句):
- *    ⇒ **一次性迁移**把那些行改成列 NULL,**不留**「把 JSON null 读成缺席」的兼容臂(那正是被禁的长期双读)。
- *    判等用的正是读腿的那只投影表达式(`sql-json-column.ts#jsonColumnTextExpr`),两种承载(真 JSON 列 /
- *    MariaDB 的 LONGTEXT 别名)同一句 SQL、同一份字节 —— 迁移与读腿不可能对同一行有两种看法。
- *
- *  · **M5 会话化身列**(S-790 / S-506,[ref] §2)—— `session_meta.incarnation` 是本版新加的列(新库由中央 DDL 建;
+ *  · **M5 会话化身列**([ref] / [ref],[ref] §2)—— `session_meta.incarnation` 是本版新加的列(新库由中央 DDL 建;
  *    列定义唯一属主 = `src/session-incarnation.ts` 的 `SESSION_META_INCARNATION_COLUMN`,迁移内插同一串)。存量库:
  *    列不在 ⇒ `ADD COLUMN`(加法 DDL,不丢任何字节),然后给每一行空化身(`''` = 没铸过)铸一只**互不相同**的令牌
  *    (应用侧 `randomUUID()`,不用库函数:MySQL / TiDB 的 `UUID()` 是 v1,带时间与机器信息)。回填之后读到空化身 ⇒ 读口响亮拒
  *    (`SessionIncarnationMissingError`),**不**当作通配 —— 硬 breaking 三句里持久数据那一句的形:一次性迁移 + 响亮拒,无双读。
- *    local 文件车道没有这张表:那一车道的存量会话在第一次被读时补铸并落盘(`LocalSessionStore.sessionFaceOf`),本段答
+ *    local 文件车道没有这张表:那一车道的存量会话在第一次被读时补铸并落盘(`LocalSessionStore.headOf`),本段答
  *    `"lazy-on-read"` / 0。
  *
  *  · **M6 run 死亡判决码** —— 7.116.0 起 run 店的两只死亡判决(失联收割 / 重启孤儿回收)在行上同写机读码(`error_code` =
@@ -57,7 +51,7 @@
  *    `settings.permissions.allow`、而 ctx 上的读法记号不是当前的 `"allow_layer"`(名单时代无记号 / 表态时代 `"statement"`)⇒ 认领之前 409、行字节不动。
  *    规则、两句拒句与写点在 `http/checkpoint-ctx.ts`;本条只登记它的窗(7.115.0 引入的同一只拒臂当时没有登记,7.117.0 起它覆盖两代旧词,登记在这里)。
  *    没有读数键(它不写库)。
- *  · **M8 停驻行披露位换名**(7.117.0,core 7.42.0 #1327)—— `checkpoint.risk_descriptor` 里 7.41.x 引擎写下的 `shadowedRule`(字符串:命中却清不掉的
+ *  · **M8 停驻行披露位换名**(7.117.0,core 7.42.0 [ref])—— `checkpoint.risk_descriptor` 里 7.41.x 引擎写下的 `shadowedRule`(字符串:命中却清不掉的
  *    持久 allow 规则原文)在 7.42.0 引擎里换成 `allowRuleShadowed: { member, entries, omitted? }[]`,旧键不再有人读。旧键只由规则店成员铸
  *    (core 7.41.2 `gate-lanes.ts` 的披露臂是它唯一的铸点;本仓的策略从不自铸它)⇒ **一次性改写**:`{ ..., shadowedRule: v }` →
  *    `{ ..., allowRuleShadowed: [{ member: "persisted", entries: [v] }] }`(旧值是引擎拼好的「最多五条 + and N more」一串,原样作为一条条目,不拆)。
@@ -65,7 +59,7 @@
  *    旧副本新写的旧键行只缺结构化披露(卡上 `message` 那句话引擎已经写好),旧键的文本由脱敏叶表的「认不得的键按内容脱敏」一条兜住
  *    (`observability/run-terminal.ts` `redactRiskDescriptor`)—— 不为它开第二种读法。local 车道没有这一列(停驻行在引擎自己的 File 店里,本仓
  *    没有合法缝改写那些字节,盘上格式归引擎):旧键留在原地、不被读,文本同样经脱敏叶表兜住。
- *  · **M9 park 指针索引改主键**(7.118.0,core 7.44.0 #1319)—— `workflow_agent_session` 的主键由 `(session_id)` 改成 `(session_id, run_id)`:
+ *  · **M9 park 指针索引改主键**(7.118.0,core 7.44.0 [ref])—— `workflow_agent_session` 的主键由 `(session_id)` 改成 `(session_id, run_id)`:
  *    停驻持有者有了引擎写的位(`parkedBy` / `generation`)之后,判决要看到点名同一个子会话的每一条记录(续跑链 / 分叉),单列主键下后写覆盖先写。
  *    表是派生投影 ⇒ **复制 + 原子换名**:照中央 DDL 建新形暂存表 → 一条 `INSERT … SELECT` 整表复制 → 正表换成待删名、暂存表换成正表名、删待删旧表
  *    (TiDB 一条 `RENAME TABLE`;PG 一个事务)→ 补建索引(旧行就是指针,新读法从记录判,不存在第二种读法)。**暂存表在场 = 上一次没走完**(唯一判据,
@@ -110,20 +104,20 @@
  *    调契约的目录迁移 `migrateConfigDirectory`(覆盖面 = 本地读腿会读的那几份:便携域 + 退役域 `runtime`),整域终判通过才原子写回、搬空的
  *    `runtime.json` 删;读腿不读的域文件(`hosts` / `workers` …)不碰;
  *    迁不动 ⇒ 一字不写、`config_dir_migration_refused` 一行。没有读数键(它不写库)。
- *  · **M17 会话规则一列一文法**(7.129.0,引擎 7.51.0 #1480)—— 引擎把会话规则的 `toolDeny` / `toolAllow` 换成规则条目文法(`Bash(rm:*)` 是一条拒 `rm`
+ *  · **M17 会话规则一列一文法**(7.129.0,引擎 7.51.0 [ref])—— 引擎把会话规则的 `toolDeny` / `toolAllow` 换成规则条目文法(`Bash(rm:*)` 是一条拒 `rm`
  *    的规则),退役 `commandAllow` / `commandDeny` 两只命令桶。持久面三件事,同一步做:
  *    ① **列改名** `session_policy.rules` → `rule_entries`(列定义唯一属主 `session-rules-column.ts`):7.128.x 及以前的副本按整串工具名读 `rules`,
  *       `Bash(rm:*)` 在那种读法下匹配不到任何工具 —— 一只没改名的列会让混跑窗里的旧副本、回滚上来的旧二进制把本版写下的命令拒读成「没有这条拒」。
  *       改名之后它们找不到那一列:已在跑的旧副本每一条规则语句响亮失败(新任务起不来、规则面 500,在跑的腿留着它已执行的快照),旧二进制起服被列册探针拒启 ——
  *       没有一只副本按旧文法读到新文法的行。行里不带文法版本(一个旧写者维护不了的第二个事实,恰在混跑窗里说谎),也不读规则体猜版本。
  *       MySQL 协议方言 `CHANGE COLUMN`(MariaDB 10.5 以前没有 `RENAME COLUMN`;定义内插同一串),PG `RENAME COLUMN`;成功判据是后置条件(列名换过来了)。
- *    ② **改名那一拍的改写:每一行在它自己的文法里由引擎读,改写成当前文法的同一句话**(core 7.51.2 #1761,行自带规则文法戳 `grammar`:写口判官盖、店整只存、
+ *    ② **改名那一拍的改写:每一行在它自己的文法里由引擎读,改写成当前文法的同一句话**(core 7.51.2 [ref],行自带规则文法戳 `grammar`:写口判官盖、店整只存、
  *       引擎按行自带的戳读;无戳行 = 戳之前写的行,引擎读成文法 0)。改名那一刻库里每一行都是无戳行(≤7.128.x 写的)—— 判据只有引擎的:行(体 + `rev`)经
  *       `readSessionRulesShape` 读成它自己的文法,`compileSessionRuleBucket` 在那种文法下编译 `toolAllow`,归 `earlier_grammar` 的条目(文法 0 里拼写不是它所指名字的条目
  *       —— `Bash(rm:*)` / `Edit(src/**)` / `Bash(*)`:什么都不放行,文法 1 里是一条放行规则)删掉,其余原样,盖 `grammar: SESSION_RULES_GRAMMAR` —— 文法 0 与 1 在引擎里只差
  *       这一条子句,所以改写后的行是引擎对原行读法的逐调用同义重述(名单保持在场:删到空 = 在场的空名单,什么都不放行)。**每一行**都改写(只盖戳的也写):改写之后
- *       部署里零无戳行,除下一条留下的行(引擎 7.52.0 #1790 起文法 0 里的 `*` 也是 `earlier_grammar` 惰性条目、只作废它自己 —— 与别的读不出的 allow 条目同一条判:删、盖戳;7.129.0–7.131.x 引擎把带 `*` 的名单整张读成作废,本步对那种行曾不改写、只点名,那一臂随引擎修正退役)。
- *       **盖戳前先问引擎读者**(S-1691,引擎 7.52.0 [ref]):行的 `toolDeny` 里有 `unreadableDenyEntries` 答的条目(引擎在这一行的文法里读成「不是任何一条规则」:空串、`-deploy`、非 ASCII 名、`(` 前带不可见空白 ……
+ *       部署里零无戳行,除下一条留下的行(引擎 7.52.0 [ref] 起文法 0 里的 `*` 也是 `earlier_grammar` 惰性条目、只作废它自己 —— 与别的读不出的 allow 条目同一条判:删、盖戳;7.129.0–7.131.x 引擎把带 `*` 的名单整张读成作废,本步对那种行曾不改写、只点名,那一臂随引擎修正退役)。
+ *       **盖戳前先问引擎读者**([ref],引擎 7.52.0 [ref]):行的 `toolDeny` 里有 `unreadableDenyEntries` 答的条目(引擎在这一行的文法里读成「不是任何一条规则」:空串、`-deploy`、非 ASCII 名、`(` 前带不可见空白 ……
  *       7.129.0–7.131.x 的写口收下过)⇒ 引擎对这一行的**每一次工具调用都拒**(读成更少的规则是 fail-open,引擎不这么读),并按行自带的旧文法通告(`config.session_rules_earlier_grammar`,只对戳早于当前文法的行发)。
  *       盖成当前文法戳什么都解不开,只让那条通告消失 ⇒ **整行不改写、不盖戳、不删任何条目**(同行 toolAllow 里该删的条目也不动 —— 不盖戳的行不做半截改写),收据点名(键 / 会话 / 条目 + 引擎读者对每条的原因词),
  *       一行一条 warn `session_rule_row_unreadable_deny`;出路是 operator 按新文法改写那一行或删会话(MIGRATION 写了)。**其余 `toolDeny` 一个字节不动、不点名**:引擎读得出的 deny 条目在每个文法下读法相同
@@ -145,14 +139,14 @@
  *    (句子给出路),引擎按行自带的文法读无戳文件(文法 0),旧文法写下的 `toolAllow` 规则形条目照旧什么都不放行、不放宽(MIGRATION 写了)。待决停驻行里持久化的
  *    祖先会话规则快照(`checkpoint` 文档 `state.inheritedGate.ancestorRules`)同理照新文法读,而它是引擎行摘要(`requirementsDigest`)覆盖的成员 ——
  *    改写它 = 续跑被判 `requirements_damaged`;本仓不重铸引擎的摘要 ⇒ 不改写,引擎续跑同样按文法 0 读它(不放宽;MIGRATION 写了)。
- *  · **M18 存卡上两个退役词(停驻行只有读侧半场)**(7.129.0,引擎 7.51.0 #1515 / #1702)—— 7.128.x 写下的 `approval_ask.card_json`(卡)与停驻行
+ *  · **M18 存卡上两个退役词(停驻行只有读侧半场)**(7.129.0,引擎 7.51.0 [ref] / [ref])—— 7.128.x 写下的 `approval_ask.card_json`(卡)与停驻行
  *    (`checkpoint.checkpoint` 文档 `pendingAction` 的 `tool_approval` 臂)上两座可能带引擎退役的词:`ruleOffersAbsence: "shadowed"`、类对里的
  *    `governance_unavailable`。今天的读者只读引擎的今日闭集 ⇒ 修前整张存卡读不出(断连重放跳过、幂等重入走 park、回决口按要人)、停驻行的
  *    `shadowed` 读成「读不出 ⇒ 按强制」。⇒ **一只改写规则**(`src/retired-card-words.ts`:前者删键 = 合法缺席 —— 一词两义不可确定拆;后者换成
  *    `rule_unreadable`,类集去重、按引擎序、首员重取),**两处两种用法,按谁写的字节分**:
  *    · **卡 = 本服务自己写的**(`approval_ask.card_json`):起服**一次性改写** + 应用侧解析 + CAS 回写(`WHERE <列文本> = <读到的原文>`;第二跑零命中)。
  *      全表按字样扫(`card_json` 是 TEXT,按 `ask_id` 键集分页)。
- *    · **停驻行 = 引擎写的文档**(`checkpoint.checkpoint`):本服务**一个字节不改写**。引擎的行摘要(`requirementsDigest`,引擎 7.49.0 #1320 起每条 v10 行都带)
+ *    · **停驻行 = 引擎写的文档**(`checkpoint.checkpoint`):本服务**一个字节不改写**。引擎的行摘要(`requirementsDigest`,引擎 7.49.0 [ref] 起每条 v10 行都带)
  *      覆盖 `pendingAction` 的 `askClass` / `classes`(`decision-read` 成员),续跑入口 `judgeCheckpointRequirements` 重算摘要 —— 成员被改 = 摘要不符 =
  *      判 `damaged` ⇒ 拒续跑(`checkpoint.invalid_outcome`,行留 pending、无人能续);盖章的函数不在引擎包根出口,重铸摘要不是本服务的事
  *      (与 M17 对祖先会话规则快照同一条纪律)。停驻行上的退役词对引擎续跑无害:续跑入口读的是摘要,引擎里 `askClass` 只在铸造 / 拒数 / 出门路径读(core 7.51.1 dist 亲读)。
@@ -168,7 +162,7 @@
  *    窗 = 发布日 + 30 天 = 停驻行的终局兜底窗缺省(`APPROVAL_TERMINAL_BACKSTOP_MS` 缺省 30 天)—— 与 M7 / M12 同一条论证。没有起服读数(它不写库)。
  *    窗按**发布日**算、停驻行的期限按**停驻时刻**算 ⇒ 三类部署会有升级前停驻的行活过窗、窗关后回到「整条不进」:发布后才升级的部署(发布日到它升级那天之间
  *    停驻的行)、把 `APPROVAL_TERMINAL_BACKSTOP_MS` 调长的部署、滚动升级里仍跑 7.129.x 的副本在窗内新写的行。与 M7 / M18 一样如实登记,不为它们加长窗。
- *    **A2A 一面**(core 7.53.0 #1835 提货批,同一只重读座、同一个窗,不另立迁移号):请求体 `a2aPeers[].toolAxes` 的判官也换成了引擎的 `readToolAxes`,7.131.x 的 A2A 读者
+ *    **A2A 一面**(core 7.53.0 [ref] 提货批,同一只重读座、同一个窗,不另立迁移号):请求体 `a2aPeers[].toolAxes` 的判官也换成了引擎的 `readToolAxes`,7.131.x 的 A2A 读者
  *    对每只 skill 的记录只挑三个轴、多余成员静默忽略 ⇒ 续跑重放腿同一只重读座按 **7.131.x 的 A2A 读法**重读一次(重读座按面分读者:两面升级前的读法不同 ——
  *    7.131.x 的 A2A 读者对已知轴写坏是整条丢对端,重读照旧整条丢,不把 7.131.x 当时没挂上的对端救活),真挂上的对端一行 `a2a_tool_axes_read_as_before_upgrade`。窗仍按 7.130.0 的发布日算 ——
  *    7.131.x 停驻、窗关(2026-11-15)之后才续跑的 A2A 行回到「整条不进」,与上一句三类部署同一处如实登记。
@@ -256,16 +250,38 @@
  *    箱的键;判官拒的 owner 持不了租(`ack` / `releaseLease` 照「不是持租者」答、`claimLease` 抛),存量那一格随租约到期失效;② MySQL 协议上带孤立代理的主体
  *    在升级前写下的箱 —— 驱动把孤立代理换成 U+FFFD 的三字节,库里的键与字面带 U+FFFD 的那只主体的键逐字节相同,判官收这只键 ⇒ 不删(挑出来就得删掉一只律认为
  *    存在的箱)。local 车道用引擎自己的 File 信箱(盘上格式归引擎)⇒ 恒 0。
+ *  · **M28 停驻行里的明文凭据原地封好**(7.134.0)—— 7.134.0 起提交体里请求面凭据位上的每一个值(闭集 `CHECKPOINT_CTX_CREDENTIAL_SLOTS` 与规则的属主
+ *    `http/checkpoint-ctx.ts` 末段「凭据位密封」;本处不重列)在 `checkpoint_ctx` 里只以封签存在,续跑上下文读口对凭据位上的明文答 409 `conflict.checkpoint_ctx_unsealable`(`reason:"plaintext"`)。升级之前写下的
+ *    行是明文 ⇒ **起服扫一遍、原地封好**:不在本文件的迁移段里(封要保管店的封签器,而本段跑在建店的 web-admin 运行时能交给它之前的店层 ——
+ *    与 M10 / M19 / M25 同为在本段之外跑的条目),编排在 `checkpoint-ctx-seal-m28.ts`(起服第 6 段,checkpoint 店建成之后、任何路由装配之前调一次),
+ *    店腿是两孪生各自的 `rewriteCtxRowsM28`(SQL:键集分页 + 按原文 CAS、`updated_at_ms` 不动;local:逐档原子重写、信封的 `updatedAt` 不动),
+ *    行改写是读写两侧同一只封口(`sealStoredCheckpointCtxM28`),封的是「读口会答 `plaintext` 的每一个值」(与开口同一只判词)—— 7.135.0 闭集加了一位
+ *    (command 条目的 `plugin.options`)之后,7.134.0 写下的带记号行在那一位上的明文也落在这一条里、同窗补封(本条没有新窗)。不删行、不改续跑语义;读不出的行计数不动;已封与不带凭据的行零写。读数不进
+ *    {@link OneTimeMigrationReport}(`reportKeys` 空,与 M25 同形),由起服 info 一行 `checkpoint_ctx_credentials_sealed` 说(扫了几行、封了几行几个值)。
+ *    窗外不扫。窗 = 发布日 + 30 天(与 M21 / M23 同一条论证:窗关时缺省部署上升级前停驻的行已被终局兜底收走);窗关之后仍是明文的行由读口的 `plaintext` 拒接住
+ *    (出路 = 重提)。**本条不覆盖混跑(如实登记)**:≤7.133.x 的续跑读者对凭据位上的封签值没有拒臂(读口、重放判据、店的形判都不看那一格,各消费者按「形不对」把它丢掉、
+ *    任务照跑),而它改写过的行与 7.134.0 副本新写的行都是封签 ⇒ 升级序是**先停光 ≤7.133.x 副本、再起第一个 7.134.0 副本**(本条在它起服时跑),回滚之前先结掉带凭据的停驻行
+ *    (随包 MIGRATION 7.134.0 第 1 条)。
+ *  · **M29 存量停驻行的 `approval_card` 列回填**(7.135.0,引擎 7.55.0 [ref] P1 阶段二)—— `checkpoint` 表本版加一列 `approval_card`(门上的卡词照存;新库由中央 DDL 建,
+ *    存量库由运维照 MIGRATION 加列 —— 本仓不发 ALTER,缺列由起服列册对账拒启并给句子)。写口从本版起由引擎那一只派生(`checkpointIndexFacts`,经
+ *    `plugins/checkpoint-index-columns.ts` 的 `buildCheckpointIndexCells`)落这一列;升级前停驻、升级时还挂着的行列上是 NULL ⇒ **起服回填,调同一只函数**:
+ *    只扫 `status = 'pending'` ∧ `approval_card IS NULL` ∧ 审批门型(`APPROVAL_GATE_KINDS`,core 登记表派生;只有审批门上卡列可能非 NULL)的行,按 `token` 键集分页,
+ *    每行单独读整只文档(一页里不同时持有两份停驻快照)、问那一只派生,答出词才写(`WHERE … AND approval_card IS NULL` CAS,第二跑零写);文档读不出 / 不是一只
+ *    引擎读得了的检查点 ⇒ 计数、不写(这样的行续不了,`get()` 对同一格拒);答出的卡词放不进列(MySQL 协议 `TEXT` 按 UTF-8 字节 65,535;PG 无上限)⇒ 同一个态度:
+ *    计数 + 一行 warn 点名(会话 id + 字节数)、不写、起服不挡 —— 引擎铸的卡词是闭集短词,超长只会是手改 / 外来写者写下的行,列留 NULL、读面按缺列读(与「无卡」同读;到期 facet 不变 —— 超长的词不可能是 core `CARD_FACET_OVERRIDES` 的键;文档一个字节没动)。排在 M21 之后:M21 给存量问答行补上的卡词由本条落列。**列不在 ⇒ 延后**(与 M11 同一条前置:
+ *    迁移段先于起服列册对账,缺列表上的扫描会抛裸的「未知列」、盖住随后的拒启句)。到期 facet 的生成谓词与运维队列行的卡读这一列 —— 本条跑完之前它们不运行
+ *    (迁移段先于任何路由与收割器装配)。**够不到的一格(如实登记)**:已决 / 已作废的行不扫(没有读者读它们的卡);local 车道没有这一列(停驻行在引擎自己的 File 店,
+ *    卡从文档读)。窗 = 发布日 + 30 天(与 M21 同一条论证:窗关时缺省部署上升级前停驻的行已被终局兜底收走)。
  *
  * ## 收据账(一次起服一只,每一条迁移同一只)
  * 每一步把它**已提交**的改写 / 删除与点名读数当场记进同一只收据账({@link MigrationReceipts}):计数随每次提交累加、行随每次提交追加、形读数在那一步落定时写。走完 ⇒
  * 账就是读数,起服日志打一行 `one_time_migrations_applied` + 逐行的那几种;任何一步失败 ⇒ 账里有动过的格就随拒因交出({@link OneTimeMigrationInterruptedError}),起服日志在抛之前
  * 用**同一只打印口**打一行 `one_time_migrations_interrupted`(读数键与读数行同一只投影)+ 逐行的那几种({@link runAndLogOneTimeMigrations})。理由:提交了的改写下一次起服再扫是
  * 零命中 —— 被改写 / 被删的行、它们的计数只有「改写发生的那一拍」说得出。没有任何一格动过就失败 ⇒ 原错误原样抛。
- * 如实的残余:提交与那一行日志之间进程被杀、或一条提交的确认在连接上丢了 —— 收据没有耐久载体(不为短命的迁移另建迁移账表,见 M4 一节的同一条论证)。
+ * 如实的残余:提交与那一行日志之间进程被杀、或一条提交的确认在连接上丢了 —— 收据没有耐久载体(不为短命的迁移另建迁移账表:有 schema 形可当「跑过了」标记的几条用它自己的形 —— M5 的列、M9 的主键宽度、M17 的列名;改值类的几条没有这种标记,为它们造一张账表 / 一个旋钮,就是给一条短命的迁移留一份长命的状态)。
  *
  * ## 幂等
- * 改写的几条都可重复跑(M4:`detail IS NOT NULL AND … = 'null'`;M5:列在场探针 + `WHERE incarnation = ''`;M6:`WHERE error_code IS NULL`;
+ * 改写的几条都可重复跑(M5:列在场探针 + `WHERE incarnation = ''`;M6:`WHERE error_code IS NULL`;
  * M8 / M18:字样扫描 + CAS 回写 —— 写过的行不再命中;M17 的改写只在改名那一拍跑,第二跑列名已是新名 ⇒ 零读零写;续判时已带戳的行零动作;
  * M24:正表 scope 列在场探针 —— 换名之后只补收尾(删待删旧表),换名之前被打断则暂存表删掉重建、回填只补缺的属主记录(`NOT EXISTS`);
  * M27:只按判官挑 —— 删过的键不再被扫到)。并发起动由 {@link runSqlOneTimeMigrations} 的 advisory 锁 + 每步的后置条件判据兜住(见那里)。
@@ -276,16 +292,13 @@ import { type AllowEntryInertReason, type GateKind } from "@sema-agent/core";
 import { type UndurableScopeRuleRow, type UnreadableRuleBucket } from "./permission-rule-store-sql.js";
 /** 迁移读数(启动日志一行写全;测试按它断言,不靠日志文本)。 */
 export interface OneTimeMigrationReport {
-    /** M4:`device_audit.detail` 里 JSON 文本 `null` 被改成列 NULL 的行数(表不在 ⇒ 恒 0)。
-     *  非零 = 这次迁移真改写了存量字节,必须让运维看见。 */
-    readonly auditDetailJsonNullRows: number;
     /** M5:`session_meta.incarnation` 列 —— `added` = 本次 `ADD COLUMN`;`present` = 早已在(新库 / 第二跑);
      *  `no-table` = 这只库上没有 `session_meta`(中央 DDL 之后不可达,只为不编一个读数);`lazy-on-read` = local 文件车道
      *  (没有这张表,存量会话首读补铸)。 */
     readonly sessionIncarnationColumn: "added" | "present" | "no-table" | "lazy-on-read";
-    /** M5:本次给空化身铸了令牌的行数。非零 = 这次迁移真写了存量行,必须让运维看见(与 M4 同一条纪律)。 */
+    /** M5:本次给空化身铸了令牌的行数。非零 = 这次迁移真写了存量行,必须让运维看见。 */
     readonly sessionIncarnationsBackfilled: number;
-    /** M6:本次给「只有句子」的死亡判决行补上机读码的 run 行数(SQL `task_run` / local `run.json`)。非零 = 这次迁移真写了存量行(与 M4 同一条纪律)。 */
+    /** M6:本次给「只有句子」的死亡判决行补上机读码的 run 行数(SQL `task_run` / local `run.json`)。非零 = 这次迁移真写了存量行(与 M5 同一条纪律)。 */
     readonly holderDeathCodeRowsBackfilled: number;
     /** M8:本次把 `checkpoint.risk_descriptor` 的旧披露键 `shadowedRule` 改写成 `allowRuleShadowed` 的行数(SQL 独有;local 恒 0)。非零 = 真写了存量行。 */
     readonly allowRuleShadowRowsMigrated: number;
@@ -345,6 +358,14 @@ export interface OneTimeMigrationReport {
     readonly retiredBreakerTablesDropped: number;
     /** M27:本次从收件箱三张表(盒 / 消息 / 墓碑)删掉的、键(scope / handle)过不了收件箱键判官的行数(SQL 独有,local 恒 0)。只有计数 —— 键是主体与会话 handle,一只都不进日志。 */
     readonly mailboxRejectedKeyRowsRemoved: number;
+    /** M29:本次给存量停驻行的 `approval_card` 列写上卡词的行数(与写口同一只派生答出的词;SQL 独有,local 恒 0)。非零 = 真写了存量行。 */
+    readonly parkedApprovalCardsBackfilled: number;
+    /** M29:该回填、却读不出的停驻行 —— 整只文档读不懂,或不是一只引擎读得了的检查点(缺门 / 缺寄存行);列留 NULL、一个字节没动(这样的行续不了;非空 = 运维该看一眼)。
+     *  与 {@link parkedApprovalCardRowsTooLong} 同一个报法(两个跳过臂同一个态度、同一个补救动作):点名行数组(会话 id),一行一条 warn。SQL 独有;local 恒空。 */
+    readonly parkedApprovalCardRowsUnreadable: readonly ParkedApprovalCardRowUnreadable[];
+    /** M29:该回填、卡词却放不进列的停驻行 —— 门上的卡词超过 `approval_card` 列的容量(MySQL 协议方言 TEXT = 65,535 UTF-8 字节;PG 无上限,恒空)。引擎铸不出这样的词,
+     *  只会是手改 / 外来写者写下的行;一个字节没写(列留 NULL,读面按缺列读 —— 与「无卡」同读),起服不挡。一行一条 warn 点名(会话 id + 字节数)。SQL 独有;local 恒空。 */
+    readonly parkedApprovalCardRowsTooLong: readonly ParkedApprovalCardRowTooLong[];
 }
 /** 退役的两只命令桶(引擎 7.51.0 起不是桶;只给 M17 点名认)。 */
 export type RetiredSessionRuleBucket = "commandAllow" | "commandDeny";
@@ -377,6 +398,14 @@ export interface SessionRuleRowUnreadableDeny {
      *  出路只能是在库里按新文法改写那一行(`rev` / `gen` 不动)或删会话 —— 与退役桶那条点名同一条出路。 */
     readonly retiredBuckets?: readonly RetiredSessionRuleBucket[];
 }
+/** M29 被跳过的一行(文档读不出):会话 id 是点名用的坐标(按它查那一行;令牌是能力键,文档内容是那一格要判的数据,都不出店)。M29 两个跳过臂的点名行同这一形。 */
+export interface ParkedApprovalCardRowUnreadable {
+    readonly sessionId: string;
+}
+/** M29 被跳过的一行(卡词超过 `approval_card` 列的容量):{@link ParkedApprovalCardRowUnreadable} 的坐标 + 卡词的 UTF-8 字节数。 */
+export interface ParkedApprovalCardRowTooLong extends ParkedApprovalCardRowUnreadable {
+    readonly bytes: number;
+}
 /** 三个形读数(M5 列 / M9 主键 / M17 列名)—— 那一步**落定**之前收据账里缺席(读数行要它们齐;被打断的那一行只带已落定的)。 */
 type ShapeReadingKey = "sessionIncarnationColumn" | "workflowParkIndexKey" | "sessionRuleColumn" | "workflowJournalScopeColumn";
 /**
@@ -389,12 +418,12 @@ type Appendable<T> = {
     -readonly [K in keyof T]: T[K] extends ReadonlyArray<infer E> ? E[] : T[K];
 };
 /**
- * 🔴 S-1594 —— **一次起服的迁移收据账(唯一一只)**:每一步把它**已提交**的改写 / 删除与点名读数当场记进来 —— 计数随每次提交累加、行随每次提交追加、
+ * 🔴 [ref] —— **一次起服的迁移收据账(唯一一只)**:每一步把它**已提交**的改写 / 删除与点名读数当场记进来 —— 计数随每次提交累加、行随每次提交追加、
  * 形读数在那一步落定时写。走完 ⇒ 它就是读数({@link completedReport});任何一步抛 ⇒ 它随拒因交出({@link OneTimeMigrationInterruptedError}),
  * 起服日志在抛之前用同一只打印口打出来({@link runAndLogOneTimeMigrations})。理由:提交了的改写下一次起服再扫是零命中 —— 被改写 / 被删的行、它们的计数
  * 只有「改写发生的那一拍」说得出;只记成功的读数,等于让一次被打断的起服把这一拍之前全部提交的事实都丢掉。
  * 只盖戳的 M17 改写不记(戳不丢信息,重来再判零动作)。如实的残余:提交与那一行日志之间进程被杀、或一条提交的确认在连接上丢了 —— 收据没有耐久载体
- * (不为短命的迁移另建迁移账表,见头注 M4 一节的同一条论证)。
+ * (不为短命的迁移另建迁移账表,理由见头注「收据账」一节)。
  */
 export type MigrationReceipts = Appendable<OneTimeMigrationReadings>;
 /** 一本空收据账(迁移段每次起服一本;每一步往里记)。 */
@@ -408,11 +437,11 @@ export declare class OneTimeMigrationInterruptedError extends Error {
     constructor(cause: unknown, receipts: OneTimeMigrationReadings);
 }
 /**
- * S-590 —— 一条一次性迁移的窗(登记表的一行;纯数据)。字段注写着每个值的取证方式,改一行之前照着重核。
+ * [ref] —— 一条一次性迁移的窗(登记表的一行;纯数据)。字段注写着每个值的取证方式,改一行之前照着重核。
  * 规则(窗长 30 天、窗关后的第一个 minor 删码、门怎么判)在本文件头注「窗」一节,只写那一次。
  */
 export interface OneTimeMigrationWindow {
-    /** 本文件里的条目名(头注「窗内的迁移」的 M4…)。 */
+    /** 本文件里的条目名(头注「窗内的迁移」的 M5…)。 */
     readonly id: string;
     /** 引入这条迁移的版本 = 第一只含其代码的发布 tag(取证:`git log -S '<该条的常量名>' -- src/plugins/one-time-migrations.ts`
      *  找引入提交 → `git tag --contains <提交> --sort=creatordate` 取最早)。 */
@@ -431,7 +460,7 @@ export interface OneTimeMigrationWindow {
     readonly reportKeys: readonly (keyof OneTimeMigrationReport)[];
 }
 /**
- * 🔴 S-590 —— 一次性迁移登记表,本文件各条的窗的**唯一属主**。别处(接口 JSDoc、调用点、DDL 注、部署文档)只写「窗口见
+ * 🔴 [ref] —— 一次性迁移登记表,本文件各条的窗的**唯一属主**。别处(接口 JSDoc、调用点、DDL 注、部署文档)只写「窗口见
  * `plugins/one-time-migrations.ts` 登记表」;起动日志行 `one_time_migrations_applied` 的 `removableAfter` 读数由本表派生。
  */
 export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
@@ -441,7 +470,7 @@ export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
  * 只给**窗内才生效的行为臂**用(M10 的认领、M19 / M20 的续跑重读):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
  */
 export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow, "removableAfter">, today: string): boolean;
-/** local 车道上 SQL 独有的几条(M4 / M5 / M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27)的读数(M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
+/** local 车道上 SQL 独有的几条(M5 / M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
 export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "holderDeathCodeRowsBackfilled">;
 /** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */
 export interface MigrationLogSink {
@@ -469,7 +498,7 @@ export interface MigrationDb {
  * 每条改表 DDL 的成功判据仍是它的**后置条件**({@link execUntil}),「另一个副本抢先把同一张表换了形」不会把滚动升级变成启动失败循环。
  *
  * ## 次序(codex r1 [medium] 同轮)
- * 非破坏改写(M4–M9、M18:改值不丢信息 / 加法 DDL / 复制 + 换名)在前,破坏性步骤(M11 的删行、M24 丢下跨 scope 行的换名)排在最后;
+ * 非破坏改写(M5–M9、M18:改值不丢信息 / 加法 DDL / 复制 + 换名)在前,破坏性步骤(M11 的删行、M24 丢下跨 scope 行的换名)排在最后;
  * M11 自己半途失败时,拒因自带已删的行(`purgeUndurableScopeRows`)—— 否则重试看不见已删的行,证据永久消失;M24 的丢行计数在换名提交之后进收据账。
  *
  * 本函数**不问**退役 schema:带着它的库在更早处就被 `ensureSchema()` 自身拒掉了(起服对账一族 `schema-consistency.ts` 的探针口,先于建表);走公开序列
@@ -515,7 +544,7 @@ export interface OldGrammarEntries {
  *    而改写的是同一行其余的桶 —— 人按出路删掉退役桶的那一刻,行已是当前文法的真话);
  *  · `toolAllow` 经 `compileSessionRuleBucket` 在那种文法下编译,归 `earlier_grammar` 的条目删掉(文法 0 与 1 在引擎里只差这一条子句:拼写不是它所指名字的 allow 条目
  *    在文法 0 里什么都不放行、在文法 1 里是一条放行规则),名单**保持在场**(在场的空 `toolAllow` 引擎读作「什么都不放行」);别的桶一个字节不动;
- *  · **盖戳前先问引擎读者**(S-1691):行的 `toolDeny` 里有 `unreadableDenyEntries` 答的条目(引擎在这一行的文法里读成「不是任何一条规则」)⇒ **整行不改写、不盖戳、不删任何条目**,
+ *  · **盖戳前先问引擎读者**([ref]):行的 `toolDeny` 里有 `unreadableDenyEntries` 答的条目(引擎在这一行的文法里读成「不是任何一条规则」)⇒ **整行不改写、不盖戳、不删任何条目**,
  *    条目与读者的原因词随 {@link OldGrammarEntries.toolDenyUnreadable} 交出(收据点名)。引擎对这种行本来就拒一切 —— 本函数只问、不判:不复刻引擎的条目读者,不替运维删条目或改写。
  *  · 新体盖 `grammar: SESSION_RULES_GRAMMAR`:无戳行每一行都写(改写之后部署里零无戳行 —— 除上一条留下的行);已带戳且没有可删条目的行零动作(幂等)。
  * 读不出形(不是对象、有别的非桶键、桶不是一列字符串、坏戳 / 比引擎新的戳)⇒ `undefined`,不判(读回照旧 `corrupt`)。本函数零处读 / 比较戳的数值:
@@ -587,6 +616,14 @@ export declare function parkedRowRepairOf(gateKindCell: unknown, gate: unknown,
  * 每一次提交当场记进收据账。
  */
 export declare function repairParkedRows(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
+/**
+ * M29 —— 存量停驻行的 `approval_card` 列回填(规则、为什么、够不到的一格见头注 M29 段):列不在 ⇒ 延后(零扫描);只扫 `status = 'pending'` ∧ 列为 NULL ∧ 审批门型的行,
+ * 按 `token` 键集分页,每行单独读整只文档、交给写口用的**同一只**派生({@link buildCheckpointIndexCells},core `checkpointIndexFacts`):答出词 ⇒
+ * `UPDATE … SET approval_card = ? WHERE token = ? AND status = 'pending' AND approval_card IS NULL`(第二跑零写;两次读之间被决掉 / 收割 ⇒ 零命中);答 NULL(无卡、非串、
+ * 文档的门不是审批门)⇒ 不写;文档读不出、或派生读不了它(缺门 / 缺寄存行)⇒ 计数不写;答出的词超过列的容量({@link APPROVAL_CARD_COLUMN_MAX_BYTES},MySQL 协议 TEXT 65,535 UTF-8 字节)⇒ 计数 + 点名不写
+ * (同一个态度:一行手改数据不许挡整只部署起服)。每一次提交当场记进收据账。
+ */
+export declare function backfillParkedApprovalCards(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
 /**
  * M23 —— 存量 placed 子代行的属主回填,**每次起服单趟、幂等**(规则、为什么、够不到的一格见头注 M23 段):键集分页扫完 placed ∧ 属主 NULL 的行,每一行按唯一判据判
  * (`judgeDelegatedOwner`,建行那一笔与停驻挂点同一只:来源顺序根、父;属主 = 这一读见证到的):