@sema-agent/server 7.135.0 → 7.137.0

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

@@ -24,22 +24,20 @@
  * ⇒ 换成本段:**升一次级把存量字节改完,兼容臂当场删干净**。代价是每一条在它的窗内每次启动都要跑一遍(第二次起全是
  * 零命中的空转);收益是窗关之后可以把那一条连同它的 SQL 一起删,而读腿从引入那一版起就只有**一种**读法。
  *
- * ## 已退役的 M1–M4
+ * ## 已退役的 M1–M5 与 M14
  * 退役的整树快照索引表(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 写了语句)。
+ * 会话化身列(M5:`session_meta.incarnation` 的补列与空化身行的逐行铸令牌)同样已删码(本版提前于窗关删),登记行一并删;它没有自己的拒启臂,跳过了它直接升的库由两道**既有、常设**的臂接住:
+ * ① 列不在 ⇒ 起服列册对账(`schema-consistency.ts`)缺列拒启 `config.schema_mismatch`,拒句里的 `ALTER TABLE … ADD COLUMN …` 由中央建表语句生成;
+ * ② 列在但行上仍是空化身 ⇒ 会话店头读投成活住客(`session-incarnation.ts` 的 `sessionFaceOfHead`)时对那一行响亮拒 `session.incarnation_missing`(parked 决定腿因此拒、记忆座退回按 id 绑定并 warn),
+ * 出路是运维给那些行各填一只互不相同的随机令牌,或删会话(MIGRATION 写了升级序)。
+ * LKG 的 formatVersion 1 迁移(M14:7.98.0 及以前写在默认路径的旧缓存文件迁进身份箱;非店迁移,不写库)同样已删码(本版提前于窗关删),登记行一并删;它没有自己的拒启臂 —— 那是缓存文件、不是数据:
+ * `CONFIG_LKG_PATH` 指到旧文件 ⇒ `loadLkg` 的 1 臂答 `config_lkg_unusable`(env 兜底),默认路径上的旧文件名不是身份箱的文件名形、不再被读,中心可达时第一份干净候选照常写出身份箱。
  *
  * ## 窗内的迁移(逐条的失败方向刻意不同)
- *  · **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.headOf`),本段答
- *    `"lazy-on-read"` / 0。
- *
  *  · **M6 run 死亡判决码** —— 7.116.0 起 run 店的两只死亡判决(失联收割 / 重启孤儿回收)在行上同写机读码(`error_code` =
  *    `run.stalled` / `run.orphaned`,词表属主 `store-contracts.ts` 的 `RUN_HOLDER_DEATH_CODES`),读者(`isHolderDeathVerdict`)只认码。
  *    存量行只有句子、码列空 ⇒ **写回半场**:起服把「`failed` ∧ 码列空 ∧ 句子是那两句(接管臂的括注形按前缀认)」的行补上码
@@ -111,11 +109,12 @@
  *       改名之后它们找不到那一列:已在跑的旧副本每一条规则语句响亮失败(新任务起不来、规则面 500,在跑的腿留着它已执行的快照),旧二进制起服被列册探针拒启 ——
  *       没有一只副本按旧文法读到新文法的行。行里不带文法版本(一个旧写者维护不了的第二个事实,恰在混跑窗里说谎),也不读规则体猜版本。
  *       MySQL 协议方言 `CHANGE COLUMN`(MariaDB 10.5 以前没有 `RENAME COLUMN`;定义内插同一串),PG `RENAME COLUMN`;成功判据是后置条件(列名换过来了)。
- *    ② **改名那一拍的改写:每一行在它自己的文法里由引擎读,改写成当前文法的同一句话**(core 7.51.2 [ref],行自带规则文法戳 `grammar`:写口判官盖、店整只存、
+ *    ② **改名那一拍的改写:每一行在它自己的文法里由引擎读,改写成文法 1 里的同一句话**(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 在引擎里只差
- *       这一条子句,所以改写后的行是引擎对原行读法的逐调用同义重述(名单保持在场:删到空 = 在场的空名单,什么都不放行)。**每一行**都改写(只盖戳的也写):改写之后
+ *       —— `Bash(rm:*)` / `Edit(src/**)` / `Bash(*)`:什么都不放行,文法 1 里是一条放行规则)删掉,其余原样,盖 `grammar: 1` —— 文法 0 与 1 在引擎里只差
+ *       这一条子句,所以改写后的行在文法 1 里是原行的逐调用同义重述(名单保持在场:删到空 = 在场的空名单,什么都不放行);之后几次修订由引擎按行戳读、保住写者的意思
+ *       (7.137.0 起;此前盖的是当时的当前文法,引擎 7.56.0 把名内 `*` 的意思改了之后那一盖会越过修订、静默把 `toolDeny: ["*"]` 变成拒每一只工具)。**每一行**都改写(只盖戳的也写):改写之后
  *       部署里零无戳行,除下一条留下的行(引擎 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`,只对戳早于当前文法的行发)。
@@ -254,9 +253,10 @@
  *    `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` 不动),
+ *    店腿是两孪生共有的 ctx 行改写腿 `rewriteCtxRows`(`checkpoint-store-sql.ts` `CheckpointCtxRowsRewriter`;M30 用同一只;SQL:键集分页 + 按原文 CAS、`updated_at_ms` 不动;local:逐档原子重写、信封的 `updatedAt` 不动),
  *    行改写是读写两侧同一只封口(`sealStoredCheckpointCtxM28`),封的是「读口会答 `plaintext` 的每一个值」(与开口同一只判词)—— 7.135.0 闭集加了一位
- *    (command 条目的 `plugin.options`)之后,7.134.0 写下的带记号行在那一位上的明文也落在这一条里、同窗补封(本条没有新窗)。不删行、不改续跑语义;读不出的行计数不动;已封与不带凭据的行零写。读数不进
+ *    (command 条目的 `plugin.options`)之后,7.134.0 写下的带记号行在那一位上的明文也落在这一条里、同窗补封(本条没有新窗);7.136.0 再加四位(子进程的命令行:MCP stdio 传输与
+ *    command 条目各自的 `command` / `args`,第 3 代)同理 —— 无记号行与 7.134.0 / 7.135.0 写下的第 1 / 2 代行上的明文命令行同窗补封。不删行、不改续跑语义;读不出的行计数不动;已封与不带凭据的行零写。读数不进
  *    {@link OneTimeMigrationReport}(`reportKeys` 空,与 M25 同形),由起服 info 一行 `checkpoint_ctx_credentials_sealed` 说(扫了几行、封了几行几个值)。
  *    窗外不扫。窗 = 发布日 + 30 天(与 M21 / M23 同一条论证:窗关时缺省部署上升级前停驻的行已被终局兜底收走);窗关之后仍是明文的行由读口的 `plaintext` 拒接住
  *    (出路 = 重提)。**本条不覆盖混跑(如实登记)**:≤7.133.x 的续跑读者对凭据位上的封签值没有拒臂(读口、重放判据、店的形判都不看那一格,各消费者按「形不对」把它丢掉、
@@ -272,16 +272,28 @@
  *    迁移段先于起服列册对账,缺列表上的扫描会抛裸的「未知列」、盖住随后的拒启句)。到期 facet 的生成谓词与运维队列行的卡读这一列 —— 本条跑完之前它们不运行
  *    (迁移段先于任何路由与收割器装配)。**够不到的一格(如实登记)**:已决 / 已作废的行不扫(没有读者读它们的卡);local 车道没有这一列(停驻行在引擎自己的 File 店,
  *    卡从文档读)。窗 = 发布日 + 30 天(与 M21 同一条论证:窗关时缺省部署上升级前停驻的行已被终局兜底收走)。
+ *  · **M30 停驻行请求体里的退役键 `promptProfile` 原地改写**(7.137.0,引擎 7.56.0)—— 提示词形收成布尔 `promptLean`,双形词 `promptProfile` 整键退役(新提交在键闭集门 400)。
+ *    7.136.x 及以前停驻的任务,`checkpoint_ctx` 存的请求体带旧键 —— 续跑腿重放它而没有读者 ⇒ `"classic"`(要长形)静默回到模型声明的短形。⇒ **起服扫一遍、原地改写**
+ *    (与 M28 同形同处:不在本文件的迁移段里 —— 那一段跑在 checkpoint 店建成之前;编排在 `stored-request-prompt-profile-m30.ts`,起服第 6 段 M28 之后调一次,
+ *    早于任何路由装配;店腿是两孪生共有的 `rewriteCtxRows`,与 M28 同一只;行改写 = `http/checkpoint-ctx.ts` `rewriteStoredBodyKeys`,只动体的这两个顶层键,
+ *    读法记号与凭据位原样随行)。映射与 MIGRATION 写给调用方的同一张:`"classic"` 且体里没有布尔 `promptLean` ⇒ 删旧键、写 `promptLean: false`;`"simple"` / 词表外 /
+ *    体里已有布尔 `promptLean` ⇒ 只删旧键。已改写与不带旧键的行零写;读不出的行计数不动;续跑时钟不动。读数不进 {@link OneTimeMigrationReport}(`reportKeys` 空,与 M28 同形),
+ *    由起服 info 一行 `checkpoint_ctx_prompt_profile_rewritten` 说(行数,不带值)。窗外不扫。**续跑腿不读旧键**(没有按日历分的第二种读法);存体里仍带它的行
+ *    (窗内从没起过本版的部署;滚动升级里旧副本在本版起服扫描之后才写下的行)由续跑判据响亮拒(`http/stored-body-replay.ts` 第四问,409 `checkpoint.unsupported_version`),
+ *    窗内再起一次本版即被改写。窗 = 发布日 + 30 天(与 M28 / M29 同一条论证:窗关时缺省部署上升级前停驻的行已被终局兜底收走)。**本条不覆盖混跑(如实登记)**:
+ *    ≤7.136.x 的读者只认 `promptProfile`,读到本条改写过的体(旧键已删、换成 `promptLean`)回到缺省形 —— 本版副本起服之后仍在续跑的 7.136.x 副本、回滚到 7.136.x 之后,
+ *    被改写过的 `"classic"` 行静默回短形;也不能给旧读者留旧键(那是同一事实的两份表示,本版读者对仍带旧键的体响亮拒)⇒ 升级序是**先停光 ≤7.136.x 副本、再起第一个 7.137.0 副本**,
+ *    回滚之前先决完或取消停驻的任务(随包 MIGRATION 7.137.0 第 4 条;与 M28 的混跑登记同形)。
  *
  * ## 收据账(一次起服一只,每一条迁移同一只)
  * 每一步把它**已提交**的改写 / 删除与点名读数当场记进同一只收据账({@link MigrationReceipts}):计数随每次提交累加、行随每次提交追加、形读数在那一步落定时写。走完 ⇒
  * 账就是读数,起服日志打一行 `one_time_migrations_applied` + 逐行的那几种;任何一步失败 ⇒ 账里有动过的格就随拒因交出({@link OneTimeMigrationInterruptedError}),起服日志在抛之前
  * 用**同一只打印口**打一行 `one_time_migrations_interrupted`(读数键与读数行同一只投影)+ 逐行的那几种({@link runAndLogOneTimeMigrations})。理由:提交了的改写下一次起服再扫是
  * 零命中 —— 被改写 / 被删的行、它们的计数只有「改写发生的那一拍」说得出。没有任何一格动过就失败 ⇒ 原错误原样抛。
- * 如实的残余:提交与那一行日志之间进程被杀、或一条提交的确认在连接上丢了 —— 收据没有耐久载体(不为短命的迁移另建迁移账表:有 schema 形可当「跑过了」标记的几条用它自己的形 —— M5 的列、M9 的主键宽度、M17 的列名;改值类的几条没有这种标记,为它们造一张账表 / 一个旋钮,就是给一条短命的迁移留一份长命的状态)。
+ * 如实的残余:提交与那一行日志之间进程被杀、或一条提交的确认在连接上丢了 —— 收据没有耐久载体(不为短命的迁移另建迁移账表:有 schema 形可当「跑过了」标记的几条用它自己的形 —— M9 的主键宽度、M17 的列名;改值类的几条没有这种标记,为它们造一张账表 / 一个旋钮,就是给一条短命的迁移留一份长命的状态)。
  *
  * ## 幂等
- * 改写的几条都可重复跑(M5:列在场探针 + `WHERE incarnation = ''`;M6:`WHERE error_code IS NULL`;
+ * 改写的几条都可重复跑(M6:`WHERE error_code IS NULL`;
  * M8 / M18:字样扫描 + CAS 回写 —— 写过的行不再命中;M17 的改写只在改名那一拍跑,第二跑列名已是新名 ⇒ 零读零写;续判时已带戳的行零动作;
  * M24:正表 scope 列在场探针 —— 换名之后只补收尾(删待删旧表),换名之前被打断则暂存表删掉重建、回填只补缺的属主记录(`NOT EXISTS`);
  * M27:只按判官挑 —— 删过的键不再被扫到)。并发起动由 {@link runSqlOneTimeMigrations} 的 advisory 锁 + 每步的后置条件判据兜住(见那里)。
@@ -292,13 +304,7 @@ import { type AllowEntryInertReason, type GateKind } from "@sema-agent/core";
 import { type UndurableScopeRuleRow, type UnreadableRuleBucket } from "./permission-rule-store-sql.js";
 /** 迁移读数(启动日志一行写全;测试按它断言,不靠日志文本)。 */
 export interface OneTimeMigrationReport {
-    /** 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:本次给空化身铸了令牌的行数。非零 = 这次迁移真写了存量行,必须让运维看见。 */
-    readonly sessionIncarnationsBackfilled: number;
-    /** M6:本次给「只有句子」的死亡判决行补上机读码的 run 行数(SQL `task_run` / local `run.json`)。非零 = 这次迁移真写了存量行(与 M5 同一条纪律)。 */
+    /** M6:本次给「只有句子」的死亡判决行补上机读码的 run 行数(SQL `task_run` / local `run.json`)。非零 = 这次迁移真写了存量行,必须让运维看见。 */
     readonly holderDeathCodeRowsBackfilled: number;
     /** M8:本次把 `checkpoint.risk_descriptor` 的旧披露键 `shadowedRule` 改写成 `allowRuleShadowed` 的行数(SQL 独有;local 恒 0)。非零 = 真写了存量行。 */
     readonly allowRuleShadowRowsMigrated: number;
@@ -406,8 +412,8 @@ export interface ParkedApprovalCardRowUnreadable {
 export interface ParkedApprovalCardRowTooLong extends ParkedApprovalCardRowUnreadable {
     readonly bytes: number;
 }
-/** 三个形读数(M5 列 / M9 主键 / M17 列名)—— 那一步**落定**之前收据账里缺席(读数行要它们齐;被打断的那一行只带已落定的)。 */
-type ShapeReadingKey = "sessionIncarnationColumn" | "workflowParkIndexKey" | "sessionRuleColumn" | "workflowJournalScopeColumn";
+/** 三个形读数(M9 主键 / M17 列名 / M24 scope 列)—— 那一步**落定**之前收据账里缺席(读数行要它们齐;被打断的那一行只带已落定的)。 */
+type ShapeReadingKey = "workflowParkIndexKey" | "sessionRuleColumn" | "workflowJournalScopeColumn";
 /**
  * 读数的「已记下的那些」形:形读数可缺席(那一步还没落定),其余每一键与 {@link OneTimeMigrationReport} 同名同形。读数行({@link logOneTimeMigrations})与
  * 被打断的那一行({@link logOneTimeMigrationsInterrupted})读同一只投影({@link readingFields}),拒因({@link OneTimeMigrationInterruptedError})带的也是这一形。
@@ -441,7 +447,7 @@ export declare class OneTimeMigrationInterruptedError extends Error {
  * 规则(窗长 30 天、窗关后的第一个 minor 删码、门怎么判)在本文件头注「窗」一节,只写那一次。
  */
 export interface OneTimeMigrationWindow {
-    /** 本文件里的条目名(头注「窗内的迁移」的 M5…)。 */
+    /** 本文件里的条目名(头注「窗内的迁移」的 M6…)。 */
     readonly id: string;
     /** 引入这条迁移的版本 = 第一只含其代码的发布 tag(取证:`git log -S '<该条的常量名>' -- src/plugins/one-time-migrations.ts`
      *  找引入提交 → `git tag --contains <提交> --sort=creatordate` 取最早)。 */
@@ -467,17 +473,23 @@ export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
 /**
  * 一条登记行的窗**此刻**开着没有(`today` = UTC 日历日 YYYY-MM-DD):未发布形(`removableAfter: null`)⇒ 开;否则今天不晚于 `removableAfter` ⇒ 开
  * (窗关当天仍开,与到期门「今天严格晚于才红」同一条边界)。
- * 只给**窗内才生效的行为臂**用(M10 的认领、M19 / M20 的续跑重读):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
+ * 给**窗内才生效的行为臂**(M10 的认领、M19 / M20 的续跑重读)与本文件迁移段之外的起服扫描(M28 / M30)用:过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
  */
 export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow, "removableAfter">, today: string): boolean;
-/** local 车道上 SQL 独有的几条(M5 / M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
+/**
+ * 一条登记行的窗的**最后一天**(= `removableAfter`,UTC 日历日 YYYY-MM-DD;与 {@link migrationWindowOpen} 同一条边界:这一天仍开)—— 给**要在句子里写绝对日期**的读者读
+ * (续跑拒句「在这一天之前重启即被改写」):窗只写在本表这一处,句子不手写第二份。行不在(读者活过了它的登记行,该随那一行一起删)或未发布形(`removableAfter: null`,
+ * 还没有日期可写)⇒ 响亮抛,不铸一句带空日期的句子。
+ */
+export declare function migrationWindowEnd(id: string): string;
+/** local 车道上 SQL 独有的几条(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 {
     warn(msg: string, meta?: Record<string, unknown>): void;
     info(msg: string, meta?: Record<string, unknown>): void;
 }
-/** 方言无关的最小查询口(两方言的返回形不同,由下面两只适配器收平)。`params` 只给带值的语句用(M5 的回填:会话 id 是
+/** 方言无关的最小查询口(两方言的返回形不同,由下面两只适配器收平)。`params` 只给带值的语句用(会话 id、行原文等
  *  调用方自选的任意串,不许内插进 SQL 文本);占位符形由调用方按方言写(`?` / `$n`)。 */
 export interface MigrationDb {
     /** 取行(只读探针用)。 */
@@ -498,7 +510,7 @@ export interface MigrationDb {
  * 每条改表 DDL 的成功判据仍是它的**后置条件**({@link execUntil}),「另一个副本抢先把同一张表换了形」不会把滚动升级变成启动失败循环。
  *
  * ## 次序(codex r1 [medium] 同轮)
- * 非破坏改写(M5–M9、M18:改值不丢信息 / 加法 DDL / 复制 + 换名)在前,破坏性步骤(M11 的删行、M24 丢下跨 scope 行的换名)排在最后;
+ * 非破坏改写(M6–M9、M18:改值不丢信息 / 复制 + 换名)在前,破坏性步骤(M11 的删行、M24 丢下跨 scope 行的换名)排在最后;
  * M11 自己半途失败时,拒因自带已删的行(`purgeUndurableScopeRows`)—— 否则重试看不见已删的行,证据永久消失;M24 的丢行计数在换名提交之后进收据账。
  *
  * 本函数**不问**退役 schema:带着它的库在更早处就被 `ensureSchema()` 自身拒掉了(起服对账一族 `schema-consistency.ts` 的探针口,先于建表);走公开序列
@@ -527,26 +539,26 @@ export declare function moveWorkflowJournalScope(db: MigrationDb, dialect: "tidb
  * 不是对象 / 没有这两个键 / 条目文字里出现同名字样 ⇒ 空。不改写:新文法写不出旧命令桶的拒(头注 M17 段 ③)。
  */
 export declare function retiredSessionRuleBucketsOf(body: unknown): readonly RetiredSessionRuleBucket[];
-/** M17 —— 一份存量规则体按引擎在它自己的文法里的读法改写成当前文法的同一句话({@link oldGrammarEntriesOf} 的读数)。 */
+/** M17 —— 一份存量规则体按引擎在它自己的文法里的读法改写成文法 1 里的同一句话({@link oldGrammarEntriesOf} 的读数)。 */
 export interface OldGrammarEntries {
     /** toolAllow 里删掉的条目(引擎的 `earlier_grammar` 读数;见 {@link SessionRuleRowOldGrammarEntries.toolAllowDropped})。行因 {@link toolDenyUnreadable} 整行不动时恒空(没写 ⇒ 没删)。 */
     readonly toolAllowDropped: readonly string[];
     /** toolDeny 里引擎 `unreadableDenyEntries` 读成「不是任何一条规则」的条目(条目 + 引擎读者的原因词)。**非空 ⇒ 这一行不改写、不盖戳**({@link rewritten} 缺席):
      *  这种行引擎对每一次工具调用都拒(读成更少的规则是 fail-open,引擎不这么读),并按行自带的旧文法通告;盖成当前文法戳只会让通告消失、行照旧拒一切。缺席 = 没有这样的条目。 */
     readonly toolDenyUnreadable?: readonly UnreadableDenyEntry[];
-    /** 这一行要落的新体 —— 被删条目去掉、其余键原样(退役命令桶也原样)、`grammar: SESSION_RULES_GRAMMAR`;在场 = 要写。缺席 = 零动作:行已带戳且没有可删的条目
+    /** 这一行要落的新体 —— 被删条目去掉、其余键原样(退役命令桶也原样)、`grammar: 1`(本步证过同义的那一版);在场 = 要写。缺席 = 零动作:行已带戳且没有可删的条目
      *  (上一次没走完的判读已改写过的行)。 */
     readonly rewritten?: Record<string, unknown>;
 }
 /**
  * M17 —— 一行存量规则(体 + 它的 `rev`)的改写判读(纯函数,判据只有引擎的):
  *  · 行按引擎的形读法在**它自己的文法**里读 —— `readSessionRulesShape` 对与 `rev` 并排的值按戳读,无戳 ⇒ 文法 0(戳之前写的行);退役命令桶先放一边(形读法拒它们,
- *    而改写的是同一行其余的桶 —— 人按出路删掉退役桶的那一刻,行已是当前文法的真话);
+ *    而改写的是同一行其余的桶 —— 人按出路删掉退役桶的那一刻,行已是文法 1 的真话);
  *  · `toolAllow` 经 `compileSessionRuleBucket` 在那种文法下编译,归 `earlier_grammar` 的条目删掉(文法 0 与 1 在引擎里只差这一条子句:拼写不是它所指名字的 allow 条目
  *    在文法 0 里什么都不放行、在文法 1 里是一条放行规则),名单**保持在场**(在场的空 `toolAllow` 引擎读作「什么都不放行」);别的桶一个字节不动;
  *  · **盖戳前先问引擎读者**([ref]):行的 `toolDeny` 里有 `unreadableDenyEntries` 答的条目(引擎在这一行的文法里读成「不是任何一条规则」)⇒ **整行不改写、不盖戳、不删任何条目**,
  *    条目与读者的原因词随 {@link OldGrammarEntries.toolDenyUnreadable} 交出(收据点名)。引擎对这种行本来就拒一切 —— 本函数只问、不判:不复刻引擎的条目读者,不替运维删条目或改写。
- *  · 新体盖 `grammar: SESSION_RULES_GRAMMAR`:无戳行每一行都写(改写之后部署里零无戳行 —— 除上一条留下的行);已带戳且没有可删条目的行零动作(幂等)。
+ *  · 新体盖 `grammar: 1`({@link M17_PROVEN_GRAMMAR}:本步证过同义的那一版):无戳行每一行都写(改写之后部署里零无戳行 —— 除上一条留下的行);已带戳且没有可删条目的行零动作(幂等)。
  * 读不出形(不是对象、有别的非桶键、桶不是一列字符串、坏戳 / 比引擎新的戳)⇒ `undefined`,不判(读回照旧 `corrupt`)。本函数零处读 / 比较戳的数值:
  * 「有没有戳」是形读法自己判戳之前的同一问;条目在哪种文法下算什么只有引擎读。
  */
@@ -618,10 +630,10 @@ 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`):答出词 ⇒
+ * 按 `token` 键集分页,每行单独读整只文档、交给写口用的**同一只**判官({@link judgeCheckpointIndexCells} → `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 字节)⇒ 计数 + 点名不写
- * (同一个态度:一行手改数据不许挡整只部署起服)。每一次提交当场记进收据账。
+ * 文档的门不是审批门)⇒ 不写;文档读不出、或派生读不了它(缺门 / 缺寄存行)⇒ 计数不写;答出的词超过列的容量(判官 {@link judgeCheckpointIndexCells} 的 `card_too_long`,
+ * MySQL 协议 TEXT 65,535 UTF-8 字节)⇒ 计数 + 点名不写(同一个态度:一行手改数据不许挡整只部署起服)。每一次提交当场记进收据账。
  */
 export declare function backfillParkedApprovalCards(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
 /**