@sema-agent/server 7.43.0 → 7.44.0

package/dist/adoption/quiesce.js

@@ -1,69 +1,13 @@
-/**
- * A-010.18 —— 收编弧跑动期间的**进程内静默闸**(design/183 I1「引擎先停」在本进程里的执法面)。
- *
- * ── 病 ──────────────────────────────────────────────────────────────────────────────────────────
- * 183 I1 写的是「发起收编之前必须先把引擎停掉」。那是一条**运维前提**,而本进程此前对它**零执法**:
- * `POST /v1/adoption` 收下请求、弧开始逐表 UPDATE 的同时,本副本的维护 tick 照常每几秒跑一轮,
- * 而那一轮里好几条腿写的正是被迁的那些表。最锋利的一条是**审批收敛器**(`approval-reconciler.ts`):
- * 它按 `owner` 读 PARKING/STREAM_PENDING 行并 CAS 结算。收编把 `approval_ask.owner` 从 A 改成 B 的
- * 那一瞬,收敛器手里可能正握着按**旧** owner 读出来的一批行 —— 结算下去就是把一只本该 PARKED 的 ask
- * 写成 **DENIED**,而 DENIED 是终局:收编回滚不了它,重跑也追认不回来。
- *
- * ── 修 ──────────────────────────────────────────────────────────────────────────────────────────
- * 弧跑动期间把维护 tick 整轮让开。判据不是「挑几条腿避让」而是**整轮**:
- *  ① 维护 tick 是 best-effort 的周期动作(每条腿都幂等、都能等下一轮),让开几轮零代价;而逐腿判
- *    「这条腿碰不碰被迁的表」会立刻变成第二份需要与 `REBIND_LEGS` 同步的表 —— 那正是本仓反复吃过亏的
- *    「两份判据必然漂」形(漏判一条新腿是**静默**的:它照写不误)。
- *  ② 弧本身是毫秒级的几条 UPDATE,库里常态在飞行数为 0 —— 让开的窗极短。
- *
- * ── 射程边界(如实登记,不假称已解)──────────────────────────────────────────────────────────────
- * 两条边界,都写在明处:
- *  ① **进程内**。这道闸只挡得住**运行这条弧的那个副本**;多副本部署里别的副本的 tick 照跑,那部分仍然
- *     只能靠 183 I1 的运维前提(以及弧内那些 rev-CAS:载荷改写撞上并发写会响亮抛、整体回滚)。
- *     更强的形(跨副本静默)需要一枚库上的 quiesce 租约 + 每条腿的取租,那是一次独立设计,不在本条射程。
- *  ② **排空有界**。等不到就带着读数继续(见下),所以「本进程零腿在写被迁的表」是**通常**成立而不是
- *     恒成立 —— 超时那一次由 `onDrainTimeout` 响亮说出来,不许静默当成已排空。
- * 本闸因此是**纵深防御**,不是把 I1 变成机器保证。
- *
- * ── 形态 ────────────────────────────────────────────────────────────────────────────────────────
- * 模块级计数器而不是布尔:并发同参 POST 是本车明确支持的形(UNIQUE 仲裁),两条弧可以叠在一起,
- * 布尔会被先结束的那条**提前**放开闸。计数器 + `try/finally` ⇒ 抛错也一定归零。
- */
-/** 当前正在本进程里跑的收编弧条数。**只**由 {@link withAdoptionQuiesce} 增减。 */
 let inFlight = 0;
-/** 本进程此刻是否有收编弧在跑(维护 tick 的让路判据)。 */
 export function isAdoptionQuiescing() {
     return inFlight > 0;
 }
-/**
- * **已经起飞**的维护腿(codex 对抗复审 R1 [high],验真后修)。
- *
- * 🔴 病:第一版的闸只在 tick 的**入口**判一次。可维护 tick 的每条腿都是 `void <promise>` 异步起飞的
- * —— tick 回调本身立刻返回。于是这个次序完全可能:`t0` tick 起飞了审批收敛器(它按旧 owner 读出一批
- * 行,正等库回话)→ `t0+ε` 收编弧开始改 `approval_ask.owner` → 收敛器拿着旧读数回来 CAS,把一只本该
- * PARKED 的 ask 结算成 **DENIED**。也就是说:**这正是本条声称要消灭的那一形**,闸只是让它更难撞上。
- * 我原来的钉也测不出来 —— 它先开闸再推进时钟,探针又是立即完成的,反向次序根本没被覆盖。
- *
- * 🔴 修:闸不止「拦住下一轮」,还要**排空这一轮**。每条腿起飞时在这里登记,收编弧进库之前先等它们落地。
- *
- * ⏱ **有界等待**是硬的:维护腿里有会长时间挂住的(`worktreeReap` 的 `git worktree prune` 随 worktree
- * 数增长,它自己的重入守卫就是为此而设)。无界 await 会把「一条腿卡住」升级成「收编永远起不来」——
- * 比原病更坏。所以排空是**尽力而为 + 响亮**:超时就带着读数继续,让运维看得见「这次收编没能等到 N 条
- * 腿落地」,而不是既没等到也没人知道。
- */
 const airborneLegs = new Set();
-/**
- * 登记一条**刚起飞**的维护腿。调用方仍然 `void` 它自己的链(错误处置不变);本函数只借用它的落地时刻。
- *
- * `catch` 是必须的:登记的这一份引用绝不能变成第二个未处理拒绝源(腿自己的链已经有 guard 接住了)。
- */
 export function trackMaintenanceLeg(leg) {
     const tracked = leg.catch(() => undefined);
     airborneLegs.add(tracked);
     void tracked.finally(() => {
         airborneLegs.delete(tracked);
-        // 集合空了才是「排空」——通知所有在等的收编弧。这是**唯一**挂在腿身上的 handler(每条腿恰一个,
-        // 在它起飞时挂),排空等待方一律等下面那只**自己的** waiter,不再往腿上加第二个 handler。
         if (airborneLegs.size === 0) {
             for (const wake of drainWaiters)
                 wake();
@@ -71,23 +15,10 @@ export function trackMaintenanceLeg(leg) {
         }
     });
 }
-/**
- * 正在等排空的收编弧(codex 对抗复审 R2 [medium],验真后修)。
- *
- * 🔴 病:第一版每次排空都现铸 `Promise.allSettled([...airborneLegs])`。**超时那一路**里,那只 allSettled
- * 永远不会兑现,而它已经把 handler 挂在了每一条挂死的腿上 —— 且 `clearTimeout` 清不掉这些 promise
- * reaction。于是「有一条腿永久挂住」这个**本来就是有界逃逸要处理的**场景,会让每一次 POST / 每一次 boot
- * 续跑再挂一批清不掉的闭包上去:逃逸机制自己变成了泄漏源。
- *
- * 🔴 修:等待方注册一只**自己的** waiter,超时时把它注销掉(`finally` 里 delete)。腿身上的 handler 恒为
- * 「起飞时挂的那一个」,与等待次数无关 ⇒ 重复超时不再增长任何东西。
- */
 const drainWaiters = new Set();
-/** 取证口(测试用):此刻有几只等待方挂着。生产不读 —— 它存在是为了让「重复超时不泄漏」可被断言。 */
 export function drainWaiterCountForTest() {
     return drainWaiters.size;
 }
-/** 有界排空(见 {@link airborneLegs} 的注)。`timeoutMs <= 0` ⇒ 不等,直接如实回报在飞数。 */
 export async function drainMaintenanceLegs(timeoutMs) {
     if (airborneLegs.size === 0)
         return { drained: true, pending: 0 };
@@ -101,7 +32,7 @@ export async function drainMaintenanceLegs(timeoutMs) {
     let timer;
     const deadline = new Promise((resolve) => {
         timer = setTimeout(() => resolve("timeout"), timeoutMs);
-        timer.unref?.(); // 排空的等待绝不该把进程吊住
+        timer.unref?.();
     });
     try {
         const outcome = await Promise.race([drained, deadline]);
@@ -110,36 +41,22 @@ export async function drainMaintenanceLegs(timeoutMs) {
     finally {
         if (timer !== undefined)
             clearTimeout(timer);
-        // 🔴 注销是本修的**全部内容**:超时之后这只 waiter 不许继续挂着(见 drainWaiters 的注)。
         drainWaiters.delete(wake);
     }
 }
-/** 排空的默认上界。取值理由:维护腿的常态是毫秒级的几条 SQL;5s 足够让它们全部落地,又不会把一次
- *  收编吊死在一条卡住的腿上(卡住的那一条由它自己的重入守卫与 throttled-warn 负责被看见)。 */
 export const ADOPTION_DRAIN_TIMEOUT_MS = 5_000;
-/**
- * 在闸内跑一条收编弧:**先关闸,再排空,最后才动数据**。
- *
- * 三步的次序是承重的 —— 先关闸(此后不会再有新 tick 起飞新腿),再等已经在飞的那些落地,然后才把
- * 控制权交给弧。反过来(先排空再关闸)之间那道窗里正好可以起飞新的一轮。
- *
- * `finally` 归零是硬的:抛出去的异常照常上抛(调用方的错误语义一个字不改),但闸绝不能因为一次失败
- * 就永久关着 —— 那会把一次收编失败升级成「这台副本从此不再做任何后台维护」。
- */
 export async function withAdoptionQuiesce(fn, opts) {
-    inFlight += 1; // ① 关闸:此后的 tick 一律让路
+    inFlight += 1;
     try {
-        // ② 排空这一轮已经起飞的腿(有界;超时如实响亮)。
         const reading = await drainMaintenanceLegs(opts?.drainTimeoutMs ?? ADOPTION_DRAIN_TIMEOUT_MS);
         if (!reading.drained)
             opts?.onDrainTimeout?.(reading);
-        return await fn(); // ③ 动数据
+        return await fn();
     }
     finally {
         inFlight -= 1;
     }
 }
-/** 测试用的复位口(用例之间零串味)。生产路径**不调** —— 它会把别的在飞弧的计数一起抹掉。 */
 export function resetAdoptionQuiesceForTest() {
     inFlight = 0;
     airborneLegs.clear();

package/dist/adoption/runner.js

@@ -1,25 +1,3 @@
-/**
- * design/183 §3.2 根级状态机的 **form b 实施**(纯身份重绑;数据已在 SQL、承运腿为零)。
- *
- * 一条弧的全部判断都在这里,店(`adoption-log-sql.ts`)只负责语句,计划表(`plan.ts`)只负责「迁什么」。
- *
- * ── 弧 ──────────────────────────────────────────────────────────────────────────────────────────
- *   ① 取弧锁(advisory;取不到 ⇒ **不等死也不假装成功**,回 `stalled` 回执)
- *   ② 意图落库(insert-or-fetch 原子形;`from_principal` UNIQUE 仲裁并发)      ⇒ phase 2
- *   ③ 目的地冲突 preflight(**任何 UPDATE 之前**)+ 全部重绑腿(同一事务)      ⇒ phase 3
- *   ④ 配置账物化(server 够不到的部署配置逐项点名,`migrated:false`)           ⇒ phase 4
- *   ⑤ 承运腿:form b **恒零**(阶段位显式在场,给 form a 上车留挂点)           ⇒ phase 5
- *   ⑥ 永久终态:`immutableReport` 一次落库,此后逐字节恒同                      ⇒ phase 6
- *
- * ── 崩溃续跑 ────────────────────────────────────────────────────────────────────────────────────
- * 每一步都是「读当前 phase → 做这一步 → CAS 推进」。任一步崩溃,下一次(重发同参 POST、或副本 boot 的
- * 在飞扫描)从库里的 phase 处接着跑;腿本身幂等(重跑改到同值 = 零行变化),所以「续跑」与「重做」在
- * 数据面等价。**绝不**因为「上次跑到一半」就拒绝续跑 —— 那会把一次网络抖动变成永久半迁移。
- *
- * ── 拒绝 ────────────────────────────────────────────────────────────────────────────────────────
- * 目的地冲突 ⇒ `rejected` 终态 + typed 409,**源/目的地两侧字节零变更**(preflight 在任何 UPDATE 之前;
- * 跨轴组合形的漏网由事务里的唯一键违例整体回滚兜住)。不做逐表 merge —— 183 未裁,拒比合安全且可重来。
- */
 import { randomUUID } from "node:crypto";
 import { ADOPTION_PHASE, adoptionLockName, } from "../plugins/adoption-log-sql.js";
 import { policyKeyFor } from "../plugins/session-policy-store-sql.js";
@@ -30,23 +8,13 @@ import { buildBlobScanSql, buildBlobWriteSql, buildConflictProbeSql, buildMemory
 import { AdoptionConfigsSchema, AdoptionLegsSchema, AdoptionReceiptSchema, AdoptionRejectDetailSchema, AdoptionReportSchema, } from "./wire.js";
 import { formatUserScope, encodeScopeSegment } from "@sema-agent/core";
 import { isDupKeyError } from "../plugins/sql-errors.js";
-/** MySQL `ER_DUP_ENTRY` / PG `unique_violation` —— 跨轴组合冲突的最后一道 fail-closed 门。
- *  判据属主 = `plugins/sql-errors.ts`(A-032 P1-①:本站点旧形只认 errno,只带 `code` 的驱动错误漏判)。 */
 const isDupKey = isDupKeyError;
 function msgOf(e) {
     return e instanceof Error ? e.message : String(e);
 }
-/**
- * 一根身份轴上的「旧值 → 新值」对。`verbatim` 恒一对;`memory-scope` 由库里 DISTINCT 扫出来
- * (user 盘 1 个 + 每个 project 盘各 1 个)——**扫而不猜**,理由见 `sql.ts` 的 LIKE 段。
- */
 async function resolveValuePairs(exec, dialect, leg, fromPrincipal, toPrincipal) {
     if (leg.encoding === "verbatim")
         return [buildVerbatimPair(fromPrincipal, toPrincipal)];
-    // 规则桶键:恒一对,**算**出来而不是扫出来(原像里只有 principal,没有逐行变量)。
-    // 🔴 这一支同时服务 preflight 的冲突探针与 `countResidual` 的残留计数 —— 少了它,那两处会拿**明文**
-    // principal 去比 `owner_key`,而那个谓词在这张表上永远匹配不到任何一行:preflight 恒说「无冲突」、
-    // 残留恒报 0(A-010.16 / A-010.22 点名的正是后者)。
     if (leg.encoding === "rule-owner-key") {
         return [
             {
@@ -76,13 +44,6 @@ async function resolveValuePairs(exec, dialect, leg, fromPrincipal, toPrincipal)
 }
 export function createAdoptionRunner(deps) {
     const { store, dialect, now } = deps;
-    /**
-     * phase 0 的**列宽实证**(codex R2-F2,亲核属实):路由那道 `checkAdoptionWidths` 是纯函数,只看得见
-     * `user:<enc(to)>`;而 memory 迁移还会重写 `proj:`/`userproj:` 键并**保留原有的项目段后缀**。源侧
-     * principal 短 + 项目段长的键可以正好装进 VARCHAR(190),换上更长的目的地段之后就越界 —— 那时行已经
-     * 铸好、失败发生在 phase 3 的腿里,弧永远停在 INTENT,每次重发和每次 boot 续跑都确定性地再撞一次。
-     * ⇒ 在**任何 UPDATE 之前**拿库里真实存在的 scope 值算一遍,越界就 typed 拒(可重来,不留半迁移)。
-     */
     async function unrepresentableScopes(exec, fromPrincipal, toPrincipal) {
         const bad = [];
         const seen = new Set();
@@ -98,12 +59,9 @@ export function createAdoptionRunner(deps) {
         }
         return bad;
     }
-    /** phase 0 探针:逐迁移表族查目的地侧是否已有与源侧重叠的逻辑键。**零 UPDATE**。 */
     async function preflight(exec, fromPrincipal, toPrincipal) {
         const hits = [];
         for (const leg of REBIND_LEGS) {
-            // residualKey === undefined = 没有任何唯一键含这根轴 ⇒ 重写**结构上**不可能撞键。
-            // 这不是「跳过没查」:它是判定表里逐条写死的判据(plan.ts 每条腿的 residualKey 行内注记了它的唯一键)。
             if (leg.residualKey === undefined)
                 continue;
             const pairs = await resolveValuePairs(exec, dialect, leg, fromPrincipal, toPrincipal);
@@ -116,20 +74,11 @@ export function createAdoptionRunner(deps) {
         }
         return hits;
     }
-    /**
-     * `blob-rewrite` 腿:逐行改写 JSON 载荷里的身份字段。
-     *
-     * 🔴 **只改值等于旧身份的字段**(不盲改):载荷里可能有同名但语义不同的字段,而且盲改会让「重跑」
-     * 变成一次真写。计数按**内容真变了**算 —— 重跑时新载荷与库里逐字节相同,行数报 0(诚实的幂等读数)。
-     * 载荷解析失败 ⇒ **原样上抛**:一条读不动的真源行,静默跳过就等于宣布它已迁移(fail-closed)。
-     */
     async function scanBlobRows(exec, leg, fromValue, toValue) {
         const blob = leg.blob;
         const cells = 1 + (blob.alsoMatch?.length ?? 0);
-        // 两个桶:旧值(还没迁的行)+ 新值(投影迁了而载荷停在旧身份的「劈开」行)。见 buildBlobScanSql 的注。
         return (await exec.query(buildBlobScanSql(dialect, leg), [...Array.from({ length: cells }, () => fromValue), ...Array.from({ length: cells }, () => toValue)])).rows;
     }
-    /** 载荷 JSON 的解析(两方言:node-pg 对 jsonb 自己 parse,mysql2 对 JSON 列同样可能已 parse)。 */
     function parseBlob(leg, row) {
         const raw = row[leg.blob.column];
         const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
@@ -150,23 +99,15 @@ export function createAdoptionRunner(deps) {
             for (const field of blob.fields)
                 if (next[field] === fromValue)
                     next[field] = toValue;
-            // 载荷内嵌的版本号跟着列上的 `rev + 1` 走(见 BlobRewriteSpec.revInPayload 的注:两处是同一个
-            // CAS 的读写两端,让它们各说一个版本 = 下一次正常写的守卫读到的基准是假的)。
             const bumped = { ...next };
             const scannedRev = Number(row[blob.revColumn]);
-            // 只有真读到数才同步载荷里的版本号。读不到时**不编一个**(写进 NaN/null 比不写更坏):
-            // 列上的 `rev = rev + 1` 仍然是权威的那一次推进,而 CAS 的 `AND rev = ?` 会用同一个值,
-            // 所以读不到数的行根本写不进去(响亮抛),不存在「悄悄写了个坏版本号」这条路。
             if (blob.revInPayload !== undefined && Number.isFinite(scannedRev))
                 bumped[blob.revInPayload] = scannedRev + 1;
             const after = JSON.stringify(bumped);
-            // 判「有没有变」只看**身份字段**那一半:rev 是我们自己推的,拿它去判会让每次重跑都变成一次真写。
             if (JSON.stringify(next) === before)
-                continue; // 已是新身份(重跑/本来就属新主)⇒ 语义无操作,不计数
+                continue;
             const res = await exec.query(buildBlobWriteSql(dialect, leg), [after, ...blob.pk.map((c) => row[c]), row[blob.revColumn]]);
             if (res.affected !== 1) {
-                // rev-CAS 落空 = 读到写之间有一次正常业务写提交(codex R2-F1)。**响亮抛** ⇒ 整个事务回滚
-                // ⇒ 两侧字节零变更。绝不「重读再盖」:那正是把别人的写吞掉的那条路。
                 throw new Error(`adoption: concurrent write on ${leg.table} (leg ${leg.leg}, pk=${blob.pk.map((c) => String(row[c])).join("/")}) — ` +
                     "its rev moved between read and write, so the payload rewrite was refused and the whole rebind rolled back. " +
                     "Adoption requires the source identity to be quiesced (design/183 I1: stop the engine first), then retry.");
@@ -175,7 +116,6 @@ export function createAdoptionRunner(deps) {
         }
         return rows;
     }
-    /** phase 3 的腿:全部在**一个事务**里(见 store.rebindTransaction 的顶注)。 */
     async function runLegs(exec, fromPrincipal, toPrincipal) {
         const out = [];
         for (const leg of REBIND_LEGS) {
@@ -197,7 +137,6 @@ export function createAdoptionRunner(deps) {
                 continue;
             }
             if (leg.kind === "rule-owner-rekey") {
-                // 一对键算一次(见 buildRuleOwnerRekeySql 的注),一条等值 UPDATE 走完;`principal` 明文列同改。
                 const [pair] = await resolveValuePairs(exec, dialect, leg, fromPrincipal, toPrincipal);
                 if (pair === undefined)
                     throw new Error(`runLegs: leg ${leg.leg} resolved no identity pair`);
@@ -220,31 +159,18 @@ export function createAdoptionRunner(deps) {
             deployment: t.deployment,
             key: t.key,
             requiredValue: t.requiredValue.replace("%TO%", toPrincipal),
-            // 🔴 恒 false:这些配置住在别的部署单元,收编动作够不到 —— 183 §3.3「改不到的配置,不假装改了」。
             migrated: false,
             ack: false,
             witnessedAtMs: null,
         }));
     }
-    // 🔴 库行 → 内域一律过 schema(禁裸 `as`,见 wire.ts 的 AdoptionLegsSchema 段)。
     function parseLegs(row) {
         return AdoptionLegsSchema.parse(JSON.parse(row.legsJson));
     }
     function parseConfigs(row) {
         return AdoptionConfigsSchema.parse(JSON.parse(row.configsJson));
     }
-    /**
-     * 回执的铸造。终态行 ⇒ `immutableReport` 是**落库的那份字节**原样解回(逐字节恒同的来源);
-     * 非终态行 ⇒ 同形投影(`status:"stalled"` 就是「这还不是冻结快照」的机读位)。
-     * `current` 一律**现算**(183 §6:史实与现势各住各的字段)。
-     */
-    /**
-     * 仍挂在旧身份名下的行数(跨全部腿求和,只读)。
-     * 每次回执都现算 —— 它是**现势**,不是史实(183 §6 的两半分家)。
-     */
     async function countResidual(exec, fromPrincipal, toPrincipal) {
-        // 🔴 按**表**聚合,不按腿(codex R3-F4):字段名承诺的是「行数」,而一条 background_agent 行可以同时
-        // 在 owner 轴、scope 轴、载荷三处带旧身份 —— 逐腿累加会把它报成 3。一张表一次判定,行只算一次。
         const byTable = new Map();
         for (const leg of REBIND_LEGS) {
             const slot = byTable.get(leg.table) ?? { match: new Set() };
@@ -252,19 +178,11 @@ export function createAdoptionRunner(deps) {
                 slot.blob = leg;
             else {
                 slot.match.add(leg.matchColumn);
-                // 🔴 A-010.16(验真后修):这里此前只认 `memory-scope` 一种**非明文**编码,别的编码一律
-                // 落到下面那条 `[{ from: fromPrincipal, … }]` 兜底 —— 也就是拿**明文 principal** 去比一根存
-                // 派生键的列。对 `permission_rule.owner_key`(sha256 原像里带身份)那个谓词**永远匹配不到
-                // 任何一行**,于是残留计数在这张表上结构性恒 0:回执一边说「adopted」、一边把一整桶还挂在
-                // 旧身份名下的活规则报成「零残留」。判据改成**编码非 verbatim 即需解析**,新编码天然进对臂。
                 if (leg.encoding !== "verbatim")
                     slot.codedLeg = leg;
             }
             byTable.set(leg.table, slot);
         }
-        // 🔴 一张表内**混编码**会让下面那条「一条 COUNT + 一个值对」的形悄悄算错(OR 起来的每一列都会被
-        // 绑上同一个值,而它们的编码不同 ⇒ 至少一列的谓词恒假)。今天没有这样的表;真出现时必须响亮拦下,
-        // 而不是报一个偏小的残留数(偏小 = 说「没落下」,正是本条要消灭的谎)。
         for (const [table, slot] of byTable) {
             const encodings = new Set(REBIND_LEGS.filter((l) => l.table === table && l.kind !== "blob-rewrite").map((l) => l.encoding));
             if (encodings.size > 1) {
@@ -275,7 +193,6 @@ export function createAdoptionRunner(deps) {
         let n = 0;
         for (const [table, slot] of byTable) {
             if (slot.blob !== undefined) {
-                // 载荷表:一次并集扫描(旧值桶 + 新值桶),行只要**投影或载荷**任一处还带旧身份就计一次。
                 const blob = slot.blob;
                 const projection = [...slot.match, blob.matchColumn, ...(blob.blob?.alsoMatch ?? [])];
                 for (const row of await scanBlobRows(exec, blob, fromPrincipal, toPrincipal)) {
@@ -286,8 +203,6 @@ export function createAdoptionRunner(deps) {
                 }
                 continue;
             }
-            // 普通表:一条 COUNT,谓词是该表全部身份轴的并。memory 族的值对逐对各来一次(不同 scope 键 =
-            // 不同的行集合,不会重复计数同一行)。
             const cols = [...slot.match];
             const pairs = slot.codedLeg !== undefined
                 ? await resolveValuePairs(exec, dialect, slot.codedLeg, fromPrincipal, toPrincipal)
@@ -318,19 +233,15 @@ export function createAdoptionRunner(deps) {
             immutableReport: report,
             current: {
                 outstandingConfigs: configs.filter((c) => c.witnessedAtMs === null).map((c) => `${c.deployment}:${c.key}`),
-                // form b 零承运 ⇒ 无拒收行(结构位在场的理由见 wire.ts 顶注差异②)。
                 quarantined: 0,
                 residualSourceRows,
             },
         });
     }
-    /** 拒绝详情的落库形 = `{detail, conflicts}` 的 JSON(一列存两件,免得再加两个只有拒才用的列)。 */
     function rejectedOutcome(row) {
         let detail = "destination conflict";
         let conflicts = [];
         if (row.rejectDetail !== null) {
-            // safeParse:一条**坏掉的**拒绝详情不该把「这条弧被拒了」这件更重要的事实吞掉 —— 拒仍然是拒,
-            // 只是失去了逐表族的明细(fail-closed 的方向:降级成粗理由,绝不降级成「成功」)。
             const parsed = AdoptionRejectDetailSchema.safeParse(JSON.parse(row.rejectDetail));
             if (parsed.success) {
                 detail = parsed.data.detail;
@@ -340,7 +251,6 @@ export function createAdoptionRunner(deps) {
         const code = row.rejectCode === "adoption.destination_unrepresentable" ? "adoption.destination_unrepresentable" : "adoption.destination_conflict";
         return { kind: "rejected", code, adoptionId: row.adoptionId, detail, conflicts };
     }
-    /** 从任意 phase 把弧推到终态(幂等、可重入)。**必须在弧锁下调用**。 */
     async function drive(start, sweep, conn) {
         let row = start;
         const reread = async () => {
@@ -352,7 +262,6 @@ export function createAdoptionRunner(deps) {
         if (row.state === "rejected")
             return rejectedOutcome(row);
         if (row.state === "in_flight" && row.phase === ADOPTION_PHASE.INTENT) {
-            // ③a preflight —— 任何 UPDATE 之前,只读。先证「装得下」,再查「撞不撞」。
             const unrepresentable = await unrepresentableScopes(conn, row.fromPrincipal, row.toPrincipal);
             if (unrepresentable.length > 0) {
                 const detail = JSON.stringify({
@@ -368,15 +277,12 @@ export function createAdoptionRunner(deps) {
                 await store.finalizeRejected(row.adoptionId, "adoption.destination_conflict", detail, now(), conn);
                 return rejectedOutcome(await reread());
             }
-            // ③b 全部腿 + phase CAS,同一个事务(任何异常 ⇒ 整体回滚 ⇒ 两侧字节零变更)。
             try {
                 await store.rebindOn(conn, row.adoptionId, ADOPTION_PHASE.INTENT, ADOPTION_PHASE.REBOUND, now(), (exec) => runLegs(exec, row.fromPrincipal, row.toPrincipal), (legs) => JSON.stringify(legs));
             }
             catch (err) {
                 if (!isDupKey(dialect, err))
                     throw err;
-                // 跨轴组合形:preflight 按迁移**前**的库态逐轴算,两根轴的组合可能在中途撞唯一键。
-                // 事务已回滚 ⇒ 字节零变更;这里把它落成与 preflight 同码的拒(fail-closed,不 fail-open)。
                 const detail = JSON.stringify({
                     detail: `unique-key violation while rebinding (cross-axis destination conflict): ${msgOf(err)}`,
                     conflicts: [],
@@ -391,7 +297,6 @@ export function createAdoptionRunner(deps) {
             row = await reread();
         }
         if (row.state === "in_flight" && row.phase === ADOPTION_PHASE.CONFIGS) {
-            // ⑤ 承运腿:form b 恒零(数据本来就在 SQL)。阶段位显式推进 —— 见本文件顶注的弧图。
             await store.advancePhase(row.adoptionId, ADOPTION_PHASE.CONFIGS, ADOPTION_PHASE.CARRIED, now(), conn);
             row = await reread();
         }
@@ -411,23 +316,10 @@ export function createAdoptionRunner(deps) {
         }
         if (row.state === "rejected")
             return rejectedOutcome(row);
-        // ⑦ 终态**之后**的迟到行清扫(codex R1-F1 的可检测/可收敛半)。见 sweepLate 的注。
         if (sweep && row.state === "adopted")
             await sweepLate(row, conn);
         return { kind: "receipt", adoptionId: row.adoptionId, receipt: receiptOf(row, await residualOf(row, conn)) };
     }
-    /**
-     * 把收编**结束之后**又落到旧身份下的行搬过去。
-     *
-     * 🔴 为什么需要它:收编不给普通写者上栅栏 —— 183 I1 的口径是「引擎必须先停」,那是**运维前提**不是
-     * 机器保证(§3.2 明写「单靠锁文件是运维假设」)。真实部署里配置随迁是**别的部署单元**的活
-     * (`affectedDeploymentConfigs` 全部 `migrated:false`),所以在配置改完之前,BFF/cli 会继续按旧身份
-     * 注入、继续往旧身份下写行。终态 + 幂等短路会让回执一直说「adopted」,而那些行永远没人搬。
-     *
-     * 处置:**每次 POST**(写动词)在终态之后再跑一遍腿(幂等,干净时零行变化)。这不是「二次收编」——
-     * `immutableReport` 一个字节不动,变的只有 `current.residualSourceRows` 这个现势读数。
-     * 清扫本身不改 phase(终态是永久的),失败也不把弧打回在飞:留痕 + 让残留读数继续报真话。
-     */
     async function sweepLate(row, conn) {
         try {
             const legs = await store.sweepOn(conn, (exec) => runLegs(exec, row.fromPrincipal, row.toPrincipal));
@@ -442,8 +334,6 @@ export function createAdoptionRunner(deps) {
             }
         }
         catch (err) {
-            // 清扫是收敛动作,不是终态的一部分:失败不该把一个已完成的收编变成错误应答。
-            // 但也**绝不静默** —— 留痕 + 残留读数会继续报非零。
             deps.logger?.warn?.("adoption_late_sweep_failed", { adoptionId: row.adoptionId, error: msgOf(err) });
         }
     }
@@ -453,21 +343,11 @@ export function createAdoptionRunner(deps) {
         }
         catch (err) {
             deps.logger?.warn?.("adoption_residual_count_failed", { adoptionId: row.adoptionId, error: msgOf(err) });
-            // 数不出来 ⇒ **不报 0**(那是「一切干净」的字面断言)。报 -1 不合 schema,故原样上抛给调用方
-            // 之外的唯一诚实选择是把它当成「至少有一行没数到」。fail-closed:宁可报 1 让人去查。
             return 1;
         }
     }
-    /**
-     * 🔴 A-010.18:**唯一**的静默闸挂点。三条入口(`start` / `get` 的在飞续跑 / boot 的 `resumeInFlight`)
-     * 全部经由本函数动数据,所以闸挂在这里一处就覆盖全部会写被迁表的路径 —— 挂在 `start` 上会漏掉后两条,
-     * 而那两条恰恰是「没人按重试、副本自己续跑」的场景,与维护 tick 撞车的概率并不更低。
-     * 闸的语义、为什么让开**整轮** tick、以及它只挡本副本这条射程边界,逐字见 `adoption/quiesce.ts`。
-     */
     async function driveUnderLock(row, sweep) {
         return withAdoptionQuiesce(() => driveUnderLockInner(row, sweep), {
-            // 排空没等到 ⇒ **响亮**(codex R1 [high] 的第二半):等不到不等于可以装作等到了。这条 warn 是
-            // 运维判断「那次收编期间有没有腿在跟它抢同一批行」的唯一读数。
             onDrainTimeout: (reading) => deps.logger?.warn?.("adoption_maintenance_drain_timeout", {
                 adoptionId: row.adoptionId,
                 pendingLegs: reading.pending,
@@ -479,15 +359,9 @@ export function createAdoptionRunner(deps) {
         });
     }
     async function driveUnderLockInner(row, sweep) {
-        const out = await store.withLock(adoptionLockName(row.fromPrincipal), 
-        // 🔴 **拿到锁之后重读**(codex R2-F3):`row` 是排队**之前**读到的快照,而排队期间别的副本可能已经
-        // 把这条弧推完或拒掉了。拿旧快照进状态机 = 按一个已经不成立的世界做决定(实测可达的形:一条已被
-        // 拒的弧被排队者推去真迁数据 —— 拒**故意**停在 phase INTENT,只判 phase 的 CAS 对它是满足的)。
-        // 库级守卫(rebind CAS 里的 `state='in_flight'`)是第二道;这一道让常路根本走不到那儿。
-        async (conn) => drive((await store.getById(row.adoptionId, conn)) ?? row, sweep, conn), deps.lockAttempts, deps.lockSleepMs);
+        const out = await store.withLock(adoptionLockName(row.fromPrincipal), async (conn) => drive((await store.getById(row.adoptionId, conn)) ?? row, sweep, conn), deps.lockAttempts, deps.lockSleepMs);
         if (out !== undefined)
             return out;
-        // 锁被别的副本持着 ⇒ 那条弧正在被推进。回**现势**回执(`stalled`),不等死也不假装成功。
         const cur = (await store.getById(row.adoptionId)) ?? row;
         deps.logger?.info?.("adoption_arc_locked_elsewhere", { adoptionId: cur.adoptionId, phase: cur.phase });
         if (cur.state === "rejected")
@@ -496,10 +370,8 @@ export function createAdoptionRunner(deps) {
     }
     return {
         async start(fromPrincipal, toPrincipal) {
-            // 幂等身份 = DB 约束:并发同参 POST 由 `from_principal` UNIQUE 仲裁,禁 SELECT-then-INSERT。
             const { row } = await store.ensureAdoption({ adoptionId: randomUUID(), fromPrincipal, toPrincipal, nowMs: now() });
             if (row.toPrincipal !== toPrincipal) {
-                // 同 from 异 to = 183 D7「二次收编/多租转让」,非本协议射程 ⇒ typed 409。
                 return { kind: "source_already_bound", adoptionId: row.adoptionId, fromPrincipal, boundTo: row.toPrincipal };
             }
             return driveUnderLock(row, true);
@@ -510,11 +382,8 @@ export function createAdoptionRunner(deps) {
                 return null;
             if (row.state === "rejected")
                 return rejectedOutcome(row);
-            // GET 是读动词:只报残留读数,**不**顺带清扫(清扫是 POST 的活)。
             if (row.state === "adopted")
                 return { kind: "receipt", adoptionId, receipt: receiptOf(row, await residualOf(row)) };
-            // 在飞行读面**顺手续跑**:一次崩溃之后没人再发 POST 的部署,读一次状态就把弧推完
-            // (与 boot 扫描同一条 drive,不是第二套状态机)。
             return driveUnderLock(row, false);
         },
         async resumeInFlight() {
@@ -524,26 +393,20 @@ export function createAdoptionRunner(deps) {
             const rejected = [];
             const failed = [];
             for (const row of rows) {
-                // 🔴 **逐弧兜住异常**(本车自测逮到):一条推不动的弧(库上有一行坏数据、一次并发写撞了 CAS…)
-                // 若把整趟扫描一起掀翻,**别的**弧就再也没人续跑了 —— 一条坏行绑架了全部恢复。
-                // 逐行 fail-loud(进 `failed` + 留痕),扫描继续。
                 let out;
                 try {
-                    out = await driveUnderLock(row, true); // boot 是写得起的场合:顺带把迟到行扫干净
+                    out = await driveUnderLock(row, true);
                 }
                 catch (err) {
                     failed.push(row.adoptionId);
                     deps.logger?.warn?.("adoption_resume_failed", { adoptionId: row.adoptionId, error: msgOf(err) });
                     continue;
                 }
-                // 闭集穷举:结局多一种 ⇒ 这里编译红,不会静默落进某个默认臂。
                 switch (out.kind) {
                     case "rejected":
                         rejected.push(out.adoptionId);
                         break;
                     case "source_already_bound":
-                        // 到不了:`drive` 只从库里既有行推进,不铸新行 —— 这一支是 `start()` 的入口判决。
-                        // 留一条**响亮**的记账而不是 `default: break`(静默吞会把一次真的状态机漂移变成看不见的丢弧)。
                         stalled.push(out.adoptionId);
                         deps.logger?.warn?.("adoption_resume_unexpected_outcome", { adoptionId: out.adoptionId, kind: out.kind });
                         break;