@sema-agent/server 7.10.0 → 7.11.0

package/dist/adoption/runner.d.ts

@@ -0,0 +1,54 @@
+import { type AdoptionLogStore } from "../plugins/adoption-log-sql.js";
+import type { SqlDialect } from "../plugins/sql-driver.js";
+import { type AdoptionReceipt, type AdoptionRejectCode } from "./wire.js";
+/** 冲突表族的逐项读数(进 409 响应体;运维据此知道**该去清理哪张表**,不是一句「冲突了」)。 */
+export interface AdoptionConflict {
+    /** 腿标识(`<表名>#<身份轴>`)。 */
+    leg: string;
+    table: string;
+    /** 目的地侧与源侧共享同一逻辑键的行对数(>0 即冲突)。 */
+    overlapping: number;
+}
+/** 收编弧的三种结局。**回执与拒绝分家**:拒从不产出 200 回执(183 §7.3 拒绝可判别)。 */
+export type AdoptionOutcome = {
+    kind: "receipt";
+    adoptionId: string;
+    receipt: AdoptionReceipt;
+} | {
+    kind: "rejected";
+    code: AdoptionRejectCode;
+    adoptionId: string;
+    detail: string;
+    conflicts: AdoptionConflict[];
+} | {
+    kind: "source_already_bound";
+    adoptionId: string;
+    fromPrincipal: string;
+    boundTo: string;
+};
+export interface AdoptionRunnerDeps {
+    store: AdoptionLogStore;
+    dialect: SqlDialect;
+    /** 注入时钟(测试要确定性;生产传 `Date.now`)。 */
+    now: () => number;
+    /** 锁轮询次数/间隔——测试把它调到 1 次好确定性地打到「取不到锁」那条臂。 */
+    lockAttempts?: number;
+    lockSleepMs?: number;
+    logger?: {
+        info?(msg: string, meta?: unknown): void;
+        warn?(msg: string, meta?: unknown): void;
+    };
+}
+export interface AdoptionRunner {
+    start(fromPrincipal: string, toPrincipal: string): Promise<AdoptionOutcome>;
+    get(adoptionId: string): Promise<AdoptionOutcome | null>;
+    /** I6 server 同族:副本 boot 的在飞扫描(续跑或响亮拒,禁静默跳过)。 */
+    resumeInFlight(): Promise<{
+        resumed: string[];
+        stalled: string[];
+        rejected: string[];
+        failed: string[];
+    }>;
+}
+export declare function createAdoptionRunner(deps: AdoptionRunnerDeps): AdoptionRunner;
+//# sourceMappingURL=runner.d.ts.map

package/dist/adoption/runner.js

@@ -0,0 +1,505 @@
+/**
+ * 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";
+import { AFFECTED_CONFIG_TEMPLATES, MEMORY_SCOPE_MAX_CHARS, NOT_MIGRATED_BY_DESIGN, REBIND_LEGS, buildVerbatimPair, rewriteMemoryScope, } from "./plan.js";
+import { buildBlobScanSql, buildBlobWriteSql, buildConflictProbeSql, buildMemoryScopeScanSql, buildResidualCountSql, buildRebindSql, buildSessionPolicyRewriteSql, buildSessionPolicyScanSql, } from "./sql.js";
+import { AdoptionConfigsSchema, AdoptionLegsSchema, AdoptionReceiptSchema, AdoptionRejectDetailSchema, AdoptionReportSchema, } from "./wire.js";
+import { formatUserScope, encodeScopeSegment } from "@sema-agent/core";
+/** MySQL `ER_DUP_ENTRY` / PG `unique_violation` —— 跨轴组合冲突的最后一道 fail-closed 门。 */
+function isDupKey(dialect, err) {
+    const e = err;
+    return dialect === "tidb" ? e?.errno === 1062 : e?.code === "23505";
+}
+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)];
+    const seg = encodeScopeSegment(fromPrincipal);
+    const projHead = `proj:${seg}/`;
+    const userProjHead = `userproj:${seg}/`;
+    const res = await exec.query(buildMemoryScopeScanSql(dialect, leg.table), [
+        formatUserScope(fromPrincipal),
+        projHead.length,
+        projHead,
+        userProjHead.length,
+        userProjHead,
+    ]);
+    const pairs = [];
+    for (const row of res.rows) {
+        const scope = String(row.scope);
+        const to = rewriteMemoryScope(scope, fromPrincipal, toPrincipal);
+        if (to !== undefined)
+            pairs.push({ from: scope, to });
+    }
+    return pairs;
+}
+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();
+        for (const leg of REBIND_LEGS) {
+            if (leg.encoding !== "memory-scope")
+                continue;
+            for (const pair of await resolveValuePairs(exec, dialect, leg, fromPrincipal, toPrincipal)) {
+                if (pair.to.length <= MEMORY_SCOPE_MAX_CHARS || seen.has(pair.to))
+                    continue;
+                seen.add(pair.to);
+                bad.push(`${leg.table}: "${pair.from}" would become a ${pair.to.length}-character scope key (column caps it at ${MEMORY_SCOPE_MAX_CHARS})`);
+            }
+        }
+        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);
+            for (const pair of pairs) {
+                const res = await exec.query(buildConflictProbeSql(dialect, leg), [pair.to, pair.from]);
+                const n = Number(res.rows[0]?.n ?? 0);
+                if (n > 0)
+                    hits.push({ leg: leg.leg, table: leg.table, overlapping: n });
+            }
+        }
+        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;
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`adoption: ${leg.table}.${leg.blob.column} is not a JSON object (leg ${leg.leg}) — refusing to declare this row migrated`);
+        }
+        return parsed;
+    }
+    async function runBlobLeg(exec, leg, fromValue, toValue) {
+        const blob = leg.blob;
+        if (blob === undefined)
+            throw new Error(`runBlobLeg: leg ${leg.leg} has no blob spec`);
+        let rows = 0;
+        for (const row of await scanBlobRows(exec, leg, fromValue, toValue)) {
+            const parsed = parseBlob(leg, row);
+            const before = JSON.stringify(parsed);
+            const next = { ...parsed };
+            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; // 已是新身份(重跑/本来就属新主)⇒ 语义无操作,不计数
+            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.");
+            }
+            rows += 1;
+        }
+        return rows;
+    }
+    /** phase 3 的腿:全部在**一个事务**里(见 store.rebindTransaction 的顶注)。 */
+    async function runLegs(exec, fromPrincipal, toPrincipal) {
+        const out = [];
+        for (const leg of REBIND_LEGS) {
+            if (leg.kind === "blob-rewrite") {
+                out.push({ store: leg.leg, action: leg.action, rows: await runBlobLeg(exec, leg, fromPrincipal, toPrincipal) });
+                continue;
+            }
+            if (leg.kind === "session-policy-rekey") {
+                const scan = await exec.query(buildSessionPolicyScanSql(dialect), [fromPrincipal]);
+                let rows = 0;
+                for (const row of scan.rows) {
+                    const sessionId = String(row.session_id);
+                    const oldKey = String(row.policy_key);
+                    const newKey = policyKeyFor(sessionId, toPrincipal);
+                    const res = await exec.query(buildSessionPolicyRewriteSql(dialect), [newKey, toPrincipal, oldKey]);
+                    rows += res.affected;
+                }
+                out.push({ store: leg.leg, action: leg.action, rows });
+                continue;
+            }
+            const pairs = await resolveValuePairs(exec, dialect, leg, fromPrincipal, toPrincipal);
+            let rows = 0;
+            for (const pair of pairs) {
+                const res = await exec.query(buildRebindSql(dialect, leg), [...leg.columns.map(() => pair.to), pair.from]);
+                rows += res.affected;
+            }
+            out.push({ store: leg.leg, action: leg.action, rows });
+        }
+        return out;
+    }
+    function buildConfigs(toPrincipal) {
+        return AFFECTED_CONFIG_TEMPLATES.map((t) => ({
+            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() };
+            if (leg.kind === "blob-rewrite")
+                slot.blob = leg;
+            else {
+                slot.match.add(leg.matchColumn);
+                if (leg.encoding === "memory-scope")
+                    slot.memoryLeg = leg;
+            }
+            byTable.set(leg.table, slot);
+        }
+        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)) {
+                    const payloadStale = blob.blob.fields.some((f) => parseBlob(blob, row)[f] === fromPrincipal);
+                    const projectionStale = projection.some((c) => row[c] === fromPrincipal);
+                    if (payloadStale || projectionStale)
+                        n += 1;
+                }
+                continue;
+            }
+            // 普通表:一条 COUNT,谓词是该表全部身份轴的并。memory 族的值对逐对各来一次(不同 scope 键 =
+            // 不同的行集合,不会重复计数同一行)。
+            const cols = [...slot.match];
+            const pairs = slot.memoryLeg !== undefined
+                ? await resolveValuePairs(exec, dialect, slot.memoryLeg, fromPrincipal, toPrincipal)
+                : [{ from: fromPrincipal, to: toPrincipal }];
+            for (const pair of pairs) {
+                const res = await exec.query(buildResidualCountSql(dialect, table, cols), cols.map(() => pair.from));
+                n += Number(res.rows[0]?.n ?? 0);
+            }
+        }
+        return n;
+    }
+    function receiptOf(row, residualSourceRows) {
+        const configs = parseConfigs(row);
+        const report = row.reportJson !== null
+            ? AdoptionReportSchema.parse(JSON.parse(row.reportJson))
+            : AdoptionReportSchema.parse({
+                adoptionId: row.adoptionId,
+                form: "b",
+                from: { kind: "principal", principal: row.fromPrincipal },
+                toPrincipal: row.toPrincipal,
+                atMs: row.updatedAtMs,
+                affectedDeploymentConfigs: configs,
+                legs: parseLegs(row),
+                notMigratedByDesign: [...NOT_MIGRATED_BY_DESIGN],
+            });
+        return AdoptionReceiptSchema.parse({
+            status: row.state === "adopted" ? "adopted" : "stalled",
+            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;
+                conflicts = parsed.data.conflicts;
+            }
+        }
+        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 () => {
+            const r = await store.getById(row.adoptionId, conn);
+            if (!r)
+                throw new Error(`adoption row vanished mid-arc (id=${row.adoptionId})`);
+            return r;
+        };
+        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({
+                    detail: `the destination principal cannot be represented in every derived key: ${unrepresentable.join("; ")}`,
+                    conflicts: [],
+                });
+                await store.finalizeRejected(row.adoptionId, "adoption.destination_unrepresentable", detail, now(), conn);
+                return rejectedOutcome(await reread());
+            }
+            const conflicts = await preflight(conn, row.fromPrincipal, row.toPrincipal);
+            if (conflicts.length > 0) {
+                const detail = JSON.stringify({ detail: "destination already holds rows sharing a logical key with the source", conflicts });
+                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: [],
+                });
+                await store.finalizeRejected(row.adoptionId, "adoption.destination_conflict", detail, now(), conn);
+                return rejectedOutcome(await reread());
+            }
+            row = await reread();
+        }
+        if (row.state === "in_flight" && row.phase === ADOPTION_PHASE.REBOUND) {
+            await store.putConfigs(row.adoptionId, ADOPTION_PHASE.REBOUND, ADOPTION_PHASE.CONFIGS, JSON.stringify(buildConfigs(row.toPrincipal)), now(), conn);
+            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();
+        }
+        if (row.state === "in_flight" && row.phase === ADOPTION_PHASE.CARRIED) {
+            const report = AdoptionReportSchema.parse({
+                adoptionId: row.adoptionId,
+                form: "b",
+                from: { kind: "principal", principal: row.fromPrincipal },
+                toPrincipal: row.toPrincipal,
+                atMs: now(),
+                affectedDeploymentConfigs: parseConfigs(row),
+                legs: parseLegs(row),
+                notMigratedByDesign: [...NOT_MIGRATED_BY_DESIGN],
+            });
+            await store.finalizeAdopted(row.adoptionId, ADOPTION_PHASE.CARRIED, JSON.stringify(report), now(), conn);
+            row = await reread();
+        }
+        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));
+            const moved = legs.reduce((n, l) => n + (l.rows ?? 0), 0);
+            if (moved > 0) {
+                deps.logger?.warn?.("adoption_late_rows_swept", {
+                    adoptionId: row.adoptionId,
+                    fromPrincipal: row.fromPrincipal,
+                    rows: moved,
+                    note: "rows kept landing under the source principal AFTER adoption terminalised — the deployment configs are still injecting the old identity (see affectedDeploymentConfigs / outstandingConfigs)",
+                });
+            }
+        }
+        catch (err) {
+            // 清扫是收敛动作,不是终态的一部分:失败不该把一个已完成的收编变成错误应答。
+            // 但也**绝不静默** —— 留痕 + 残留读数会继续报非零。
+            deps.logger?.warn?.("adoption_late_sweep_failed", { adoptionId: row.adoptionId, error: msgOf(err) });
+        }
+    }
+    async function residualOf(row, exec = store.reader) {
+        try {
+            return await countResidual(exec, row.fromPrincipal, row.toPrincipal);
+        }
+        catch (err) {
+            deps.logger?.warn?.("adoption_residual_count_failed", { adoptionId: row.adoptionId, error: msgOf(err) });
+            // 数不出来 ⇒ **不报 0**(那是「一切干净」的字面断言)。报 -1 不合 schema,故原样上抛给调用方
+            // 之外的唯一诚实选择是把它当成「至少有一行没数到」。fail-closed:宁可报 1 让人去查。
+            return 1;
+        }
+    }
+    async function driveUnderLock(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);
+        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")
+            return rejectedOutcome(cur);
+        return { kind: "receipt", adoptionId: cur.adoptionId, receipt: receiptOf(cur, await residualOf(cur)) };
+    }
+    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);
+        },
+        async get(adoptionId) {
+            const row = await store.getById(adoptionId);
+            if (!row)
+                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() {
+            const rows = await store.listInFlight();
+            const resumed = [];
+            const stalled = [];
+            const rejected = [];
+            const failed = [];
+            for (const row of rows) {
+                // 🔴 **逐弧兜住异常**(本车自测逮到):一条推不动的弧(库上有一行坏数据、一次并发写撞了 CAS…)
+                // 若把整趟扫描一起掀翻,**别的**弧就再也没人续跑了 —— 一条坏行绑架了全部恢复。
+                // 逐行 fail-loud(进 `failed` + 留痕),扫描继续。
+                let out;
+                try {
+                    out = await driveUnderLock(row, true); // boot 是写得起的场合:顺带把迟到行扫干净
+                }
+                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;
+                    case "receipt":
+                        if (out.receipt.status === "adopted")
+                            resumed.push(out.adoptionId);
+                        else
+                            stalled.push(out.adoptionId);
+                        break;
+                }
+            }
+            return { resumed, stalled, rejected, failed };
+        },
+    };
+}
+//# sourceMappingURL=runner.js.map

package/dist/adoption/sql.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 收编迁移语句的**双方言文本铸造**(design/183 §4.3 form b)。
+ *
+ * 🔴 为什么这里是**生成**而不是像别的店那样把两句话手写并排(sql-driver.ts 的 A12 判据):那条纪律的
+ * 目的是「读代码的人能一眼对比两方言」。本车的语句是从 {@link REBIND_LEGS} 计划表派生的 —— 手抄 26 条
+ * 腿 × 3 类语句 × 2 方言 = 156 段几乎一样的 SQL,抄漏一个列名是**静默**的(库上照样跑,只是少迁一列)。
+ * 所以判据换了个执行面、强度不降反升:每条腿每个方言的**成品文本**由
+ * `test/adoption-sql-text.test.ts` 逐字钉成 golden —— 计划表改一个字,红的是那条腿的文本对照,
+ * 而不是等真库上撞。
+ *
+ * 方言差异全部集中在 {@link ph}(占位符 `?` vs `$n`)与 `LEFT()` 的大小写无关形上;除此之外两方言的
+ * 文本**逐字相同**(本车的语句只用等值谓词、COUNT、UPDATE —— 刻意不碰任何方言分岔的语法面:
+ * 没有 upsert、没有 JSON 转型、没有 null-safe 比较)。
+ */
+import type { SqlDialect } from "../plugins/sql-driver.js";
+import type { RebindLegSpec } from "./plan.js";
+/** 第 `i` 个占位符(1-based)。TiDB `?` / PG `$i` —— 这是本文件唯一的方言分岔点。 */
+export declare function ph(dialect: SqlDialect, i: number): string;
+/**
+ * 目的地冲突探针(phase 0,**任何 UPDATE 之前**)。
+ *
+ * 判据 = 「to 侧已有的行,与 from 侧的行,是否共享同一个**逻辑键**」。逻辑键 =
+ * `leg.residualKey`(该表最紧的唯一键**去掉身份轴**之后剩下的列):
+ *  · `undefined` ⇒ 没有唯一键含这根轴 ⇒ 结构性无冲突,本函数不该被调用(调用方按 `undefined` 短路);
+ *  · `[]`        ⇒ 唯一键**就是**这根轴(PK(scope))⇒ 两侧各有任意一行即冲突,退化成笛卡尔计数;
+ *  · 非空        ⇒ 逐列相等的自连接计数。
+ *
+ * 参数序:`[toValue, fromValue]`。
+ */
+export declare function buildConflictProbeSql(dialect: SqlDialect, leg: RebindLegSpec): string;
+/**
+ * 桶迁/行迁的等值 UPDATE。`columns` 里的每一列都被设成**同一个**新值(字节孪生 `*_key` 与可读列一起走),
+ * 谓词打在 `matchColumn` 上。参数序:`[...新值 × columns.length, 旧值]`。
+ *
+ * 幂等性来自谓词本身:重跑时旧值已经不在库里 ⇒ 零行匹配 ⇒ 零行变化。
+ */
+export declare function buildRebindSql(dialect: SqlDialect, leg: RebindLegSpec): string;
+/**
+ * memory 族的 scope 值扫描:把「属于这个 principal 的 scope 键」从库里**读出来**,而不是用 LIKE 去猜。
+ *
+ * 🔴 为什么不是 `LIKE '<前缀>%'`:scope 的 tenant 段是**百分号编码**的(`user%3Aweb-demo`),而 `%` 在
+ * LIKE 里是通配符 —— 不逐字符转义就会误命中别的租户的盘(**跨租户误迁**,不是性能问题)。`LEFT(col, n) = ?`
+ * 是纯等值比较,没有元字符面,两方言同形。
+ *
+ * 参数序:`[userScope, projHead.length, projHead, userProjHead.length, userProjHead]`。
+ */
+export declare function buildMemoryScopeScanSql(dialect: SqlDialect, table: string): string;
+/**
+ * 残留计数:某条腿上**仍挂在旧身份名下**的行数。参数序:`[fromValue]`。
+ *
+ * 用途见 wire.ts 的 `current.residualSourceRows`:收编不给普通写者上栅栏(183 I1 = 运维前提「引擎先停」),
+ * 所以「终态之后旧身份下又长出行」是一个真实可能的形 —— 这条查询把它变成可见读数,而不是靠祈祷。
+ */
+export declare function buildResidualCountSql(dialect: SqlDialect, table: string, matchColumns: readonly string[]): string;
+/**
+ * `blob-rewrite` 腿的扫描:按**旧**身份值把行连同 JSON 载荷读出来。
+ * 匹配面 = `matchColumn` 与 `blob.alsoMatch` 的**并**(同表两根轴都可能带旧值)。
+ * 参数序:`[fromValue × (1 + alsoMatch.length)]`。
+ */
+export declare function buildBlobScanSql(dialect: SqlDialect, leg: RebindLegSpec): string;
+/**
+ * `blob-rewrite` 腿的逐行回写。参数序:`[新载荷文本, ...pk 值]`。
+ *
+ * 幂等性:重跑时载荷里的身份字段已是新值 ⇒ 调用方算出的新载荷与库里逐字节相同 ⇒ 语义无操作
+ * (行数可能仍报 1,故回执的行数按「**内容真变了**才计」在调用侧收窄)。
+ */
+export declare function buildBlobWriteSql(dialect: SqlDialect, leg: RebindLegSpec): string;
+/** session_policy 重键腿的扫描:拿到 from 侧每一行的 `(policy_key, session_id)`。参数序:`[fromPrincipal]`。 */
+export declare function buildSessionPolicyScanSql(dialect: SqlDialect): string;
+/**
+ * session_policy 的逐行重键改写。`policy_key = sha256(JSON.stringify([sessionId, principal ?? null]))`,
+ * 身份在**主键的 hash 原像**里 ⇒ 等值 UPDATE 够不着,必须读出来重算再改写。
+ * 参数序:`[newPolicyKey, toPrincipal, oldPolicyKey]`。
+ */
+export declare function buildSessionPolicyRewriteSql(dialect: SqlDialect): string;
+//# sourceMappingURL=sql.d.ts.map