@sema-agent/server 7.10.0 → 7.12.0

package/dist/parked-decide.d.ts

@@ -8,7 +8,7 @@
  * 判别必须 parked-first:legacy 腿的 `resumeStream` 会绕开 bg registry(无 consumeParkedFlip、
  * 行永 parked、生命周期分叉)。
  */
-import type { BackgroundAgentRecord, BackgroundAgentStore, CheckpointStore, QuestionAnswer, TaskRegistry, ToolSpec } from "@sema-agent/core";
+import type { ApprovalSettledBy, BackgroundAgentRecord, BackgroundAgentStore, CheckpointStore, QuestionAnswer, TaskRegistry, ToolSpec } from "@sema-agent/core";
 export interface ParkedAgentMatch {
     handle: string;
     row: BackgroundAgentRecord;
@@ -46,8 +46,13 @@ export interface ParkedDecideDeps {
      *  解析槽一条,单层链;exempt 探针锚= row.rootSessionId,与 remember grant 锚同键)。core 1.396 起
      *  `parkedResume.inheritedGate` 席位把它透传进 resume 的官方重供通道——不供 = 重启后带
      *  requiresParentConstraint 的 checkpoint 恒被 pre-CAS 门拒(retryable 假话,永不可赎回)。链长形状
-     *  校验在 core(fail-closed,供错链长照拒)。 */
-    rebuildInheritedGate?: (row: BackgroundAgentRecord) => unknown;
+     *  校验在 core(fail-closed,供错链长照拒)。
+     *
+     *  ⚠️ **async**(A-010.1):重建条目的第三位决议链元数据 `autoModeArmed` 与 `durableMandate` 的
+     *  `forceDurableGate` 项都要按**本行的 principal** 现解 entitlement(`RunnerDeps.runtimeCapsResolver`
+     *  本身就是 sync-or-async 的座),理由全在 `boot/parked-revive-gate.ts`。本腿一直就在 async 里,
+     *  「席位必须同步」是那个文件此前自设的约束、不是结构事实。 */
+    rebuildInheritedGate?: (row: BackgroundAgentRecord) => Promise<unknown>;
     warn?: (event: string, fields: Record<string, unknown>) => void;
 }
 export interface ParkedDecideRequest {
@@ -57,6 +62,11 @@ export interface ParkedDecideRequest {
     /** cp.pendingAction 原样(outcome 铸造的 persisted 回落源,与 legacy 腿 D-1 姿势逐字同形)。 */
     pendingAction: unknown;
     decision: "approve" | "deny";
+    /** #204 件6③ core `ApprovalSettledBy`:**这次结算的出处**,由调用方命名(必填,理由与 legacy 腿
+     *  `resumeCheckpoint` 的同名参数逐字同源 —— 本函数分辨不出谁在叫它,漏报要是编译错而不是假出处)。
+     *  今天唯一的调用方是 `server.ts` 的人为 `/decide`(那道门写着 `req !== undefined`,而内部 D-D SLA
+     *  deny-sweep 恰是 req 缺席的那条腿,它对 parked 行另有静默跳过臂)⇒ 恒 `"human"`。 */
+    settledBy: ApprovalSettledBy;
     reason?: string;
     /** D-1 decision-binding echo(操作员在 GET 看到的 boundCallId/boundInputHash 原样透传;server
      *  绝不重算,core resume 侧做 fail-closed 等值校验——与 legacy 腿同姿势)。 */

package/dist/parked-decide.js

@@ -97,6 +97,13 @@ export async function decideParkedAgent(deps, req) {
         // ([1588] Q1:name 必传承重——省略会把 revive 降级成匿名形)。
         return { status: 409, body: { error: "parked row carries no agent name — the revive path requires a named agent (row damaged?)", errorCode: "decide.row_unrevivable", taskId: match.handle } };
     }
+    // [1597]/A-010.1:席位重建**在 claim 之前**解开(codex 对抗复审 R1-中 的真 finding)。
+    // 🔴 位置即正确性:claim 之后到下面那道 try/catch(它才挂 `rollbackParkedClaim`)之间是一段
+    // **无回滚保护区**。工厂现在是 async(要现解 entitlement),把 await 放进那一段 = 任何 rejection
+    // 都带着一个已认领的 claim 逃逸,行上的 `parkClaimId` 要等 stale-claim 清算窗(默认可达一小时)
+    // 才放开,这期间该审批**再决不动**。搬到 claim 前:此刻还没有任何东西需要回滚,抛错就是干净地抛错。
+    // (工厂本身只读 row 的 scope/handle/sessionId/rootSessionId —— claim 不改这四个字段,搬位零语义差。)
+    const inheritedGate = deps.rebuildInheritedGate ? await deps.rebuildInheritedGate(row) : undefined;
     const stores = { agentStore: deps.agentStore, checkpointStore: deps.checkpointStore };
     const claim = await deps.registry.claimParkedAgent(stores, match.handle, { scope: row.scope, owner: row.owner });
     if (!claim.ok) {
@@ -147,6 +154,8 @@ export async function decideParkedAgent(deps, req) {
         // 是两件不同的事(姊妹 approval-hmac.ts `env.reason ?? null` 同判据:`??` 只在 null/undefined 时落
         // null,空串照样入签名载荷)。真值判定会把显式 "" 与缺席折成同一个结果,审计/签名面丢了这个区分。
         ...(req.reason !== undefined ? { reason: req.reason } : {}),
+        // #204 件6③:结算出处逐字上 outcome(见 `ParkedDecideRequest.settledBy` 顶注)。
+        settledBy: req.settledBy,
     };
     const ctx = {
         toolCallId: `drv-${ticket.claimId}`,
@@ -158,7 +167,7 @@ export async function decideParkedAgent(deps, req) {
                 outcome,
                 // [1597] 席位:重建父约束链(同进程时 core 的内存 registry 也能自动重供,席位供了也无害
                 // ——core 侧 count 校验对得上即用;跨进程/重启形全靠这里)。
-                ...(deps.rebuildInheritedGate ? { inheritedGate: deps.rebuildInheritedGate(row) } : {}),
+                ...(deps.rebuildInheritedGate ? { inheritedGate } : {}),
             },
         },
     };

package/dist/plugins/adoption-log-sql.d.ts

@@ -0,0 +1,191 @@
+/**
+ * design/183 I2(form b 位)—— **SQL 收编日志**:phase 真源与被迁的行**同库**。
+ *
+ * 🔴 为什么 phase 必须住 SQL 而不是一个 sidecar 文件(183 r3 按 codex r2-F2):发起收编的那个 pod 在两条
+ * 腿之间被摧毁时,进程本地的标记会与已经半迁移的 SQL 状态**分家** —— 接棒副本读不到「迁到哪了」。
+ * 标记与行同事务 ⇒ 崩溃后接棒副本按日志续跑,分家形不存在。
+ *
+ * ── 幂等身份 = DB 约束,不是「查了再插」(小票 v2/F2)────────────────────────────────────────────
+ * `from_principal` 上有 **UNIQUE**(183 D7「拒二次收编」的 DB 强形)。发起走 **insert-or-fetch 原子形**:
+ * 一条 `INSERT … ON CONFLICT DO NOTHING` / `INSERT IGNORE`,再按 `from_principal` 读回行。
+ * **禁 SELECT-then-INSERT** —— 那两句之间的窗正是两个并发同参 POST 各插一行(或各读到空)的地方,
+ * 而 UNIQUE 让「谁插进去了」由数据库仲裁,`affected` 就是判别式。
+ * 同 from 异 to ⇒ 读回的行 `to_principal` 不等 ⇒ typed conflict(调用方看到的是 409,不是「成功」)。
+ *
+ * ── 列的口径 ────────────────────────────────────────────────────────────────────────────────────
+ *  · `legs` / `configs` / `report` 是 **TEXT 不是 JSON 列**:`report` 是 `immutableReport` 的落库形,
+ *    契约是「逐字节恒同」;JSON 列会按引擎自己的规范形重排键序,而 TEXT 是「存什么读什么」。
+ *    (workflow_run.run / workflow_journal.result 同款先例,理由同源:String()→JSON.parse 的字节面。)
+ *  · 时间列一律 `_ms BIGINT`(schema-naming 门 ② 咬 `_at BIGINT`)。
+ *  · `phase` 是**单调**推进的阶段号,不是乐观锁计数 —— 但它的推进走的就是 CAS(`WHERE phase = :expect`),
+ *    所以它同时是那把锁。命名不叫 `rev`,因为它不守卫「行内容有没有变」,而守卫「弧走到哪了」。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SqlDriver, type SqlExec, type SqlTxConn } from "./sql-driver.js";
+import type { AdoptionRejectCode } from "../adoption/wire.js";
+export declare const ADOPTION_LOG_TABLE = "adoption_log";
+/** 弧的阶段(183 §3.2 根级状态机的 form b 投影)。**单调**,只增不减。 */
+export declare const ADOPTION_PHASE: {
+    /** ② 意图已落库(行在,尚未动任何数据行)。 */
+    readonly INTENT: 2;
+    /** ③ 身份轴重绑腿全部完成(与腿的 UPDATE **同一个事务**)。 */
+    readonly REBOUND: 3;
+    /** ④ 解析切换 / 配置清单产出。form b 的 server 半场:配置账已物化进 `configs`。 */
+    readonly CONFIGS: 4;
+    /** ⑤ 承运腿。**form b 恒零承运**(数据本来就在 SQL)—— 阶段位仍显式推进,好让 form a 上车时挂得上。 */
+    readonly CARRIED: 5;
+    /** ⑥ 永久终态。 */
+    readonly TERMINAL: 6;
+};
+export type AdoptionState = "in_flight" | "adopted" | "rejected";
+export interface AdoptionRow {
+    adoptionId: string;
+    fromPrincipal: string;
+    toPrincipal: string;
+    phase: number;
+    state: AdoptionState;
+    /** `AdoptionLeg[]` 的 JSON 文本(phase 3 与腿同事务落库,此后不改)。 */
+    legsJson: string;
+    /** `AdoptionConfigEntry[]` 的 JSON 文本(phase 4 落库;见证位后续可更新)。 */
+    configsJson: string;
+    /** `AdoptionReport` 的 JSON 文本;`null` = 尚未终态。**落库后逐字节不变**(183 I4)。 */
+    reportJson: string | null;
+    rejectCode: string | null;
+    rejectDetail: string | null;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+export interface NewAdoptionRow {
+    adoptionId: string;
+    fromPrincipal: string;
+    toPrincipal: string;
+    nowMs: number;
+}
+/** `INSERT … ON CONFLICT DO NOTHING` 之后按 `from_principal` 读回的结果。`inserted` 只有真插进去的那一
+ *  路为 true —— 并发同参 POST 里恰有一条为 true,其余全 false 且拿到**同一行**。 */
+export interface EnsureAdoptionResult {
+    row: AdoptionRow;
+    inserted: boolean;
+}
+/**
+ * 收编日志的**消费面接口**。真实现只有 {@link SqlAdoptionLogStore} 一个(双方言);抽出接口是为了让
+ * 协议层(`adoption/runner.ts`)只依赖行为而不依赖那个带 `protected db` 的类 —— 后者是**名义类型**,
+ * 测试想给一个结构等价的假店都做不到,于是「弧的状态机」与「SQL 文本」这两件事只能一起测,
+ * 两个变量同时动的实验没有判别力。
+ */
+export interface AdoptionLogStore {
+    /** 池级只读执行面(**不在弧锁下**的读用它:锁外的现势查询、boot 扫描的名单)。 */
+    readonly reader: SqlExec;
+    ensureAdoption(row: NewAdoptionRow): Promise<EnsureAdoptionResult>;
+    /**
+     * 🔴 每个弧内方法都收一个 `exec`(codex R3-F2):弧锁**占着一条池连接**,如果弧内的读/事务再去池里
+     * 要第二条,`connectionLimit=1` 的部署会当场死锁(而 boot 的在飞扫描跑在 listen 之前 ⇒ 副本起不来)。
+     * 收编弧因此**全程单连接**:锁、preflight 读、腿的事务、phase CAS,全在 `withLock` 交出来的那一条上。
+     */
+    getById(adoptionId: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    getByFrom(fromPrincipal: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    listInFlight(exec?: SqlExec): Promise<AdoptionRow[]>;
+    /** 在**给定连接**上跑腿 + phase CAS(不自己 connect —— 见 getById 的注)。 */
+    rebindOn<L>(conn: SqlTxConn, adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, work: (exec: SqlExec) => Promise<L[]>, encodeLegs: (legs: L[]) => string): Promise<{
+        ok: true;
+        legs: L[];
+    } | {
+        ok: false;
+        reason: "phase_moved";
+    }>;
+    /** 终态后的迟到行清扫,同样在给定连接上。 */
+    sweepOn<T>(conn: SqlTxConn, work: (exec: SqlExec) => Promise<T>): Promise<T>;
+    advancePhase(adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    putConfigs(adoptionId: string, expectPhase: number, nextPhase: number, configsJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    finalizeAdopted(adoptionId: string, expectPhase: number, reportJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    finalizeRejected(adoptionId: string, code: AdoptionRejectCode, detail: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /** 取弧锁并把**那一条连接**交给回调(整条弧都跑在它上面)。`undefined` = 没取到锁。 */
+    withLock<T>(name: string, fn: (conn: SqlTxConn) => Promise<T>, attempts?: number, sleepMs?: number): Promise<T | undefined>;
+}
+/** MySQL 协议方言的建表语句(展开进 tidb-pool 的中央 `SCHEMA_STATEMENTS`,与 approval-ask 同姿势:
+ *  跟着中央 ensureSchema 在 named-lock 的那条 conn 上建,不绕开 DDL 串行化)。 */
+export declare const TIDB_ADOPTION_LOG_STATEMENTS: readonly string[];
+/** PostgreSQL 孪生(由 `ensurePgSchema` 在 advisory lock 的那条 client 上调用)。 */
+export declare function ensurePgAdoptionLogSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
+/**
+ * 弧锁的名字。**定长**(前缀 14 + 32 位十六进制 = 46 字符)。
+ *
+ * 🔴 为什么必须 hash 而不是把 principal 直接拼进去(codex R3-F3,亲核属实):TiDB/MySQL 的 `GET_LOCK`
+ * 锁名上限是 **64 字符**,而请求面收的 principal 到 190 —— 超过 50 字符的源身份会让取锁**在弧动起来
+ * 之前**就失败,而那时意图行已经落库,于是每一次重发、每一次副本 boot 续跑都确定性地再撞一次同一堵墙。
+ * (PG 那条腿本来就走 hash 出来的 int4 对象键,这里只是把 MySQL 腿补齐到同一姿势。)
+ */
+export declare function adoptionLockName(fromPrincipal: string): string;
+/**
+ * 收编日志店(单文件双方言,SqlDriver 形——checkpoint-store / approval-ask-store 同款)。
+ *
+ * 每条语句的两方言文本**并排写在调用点**(A12 判据:方言差异必须显式,不许用占位符编号循环拼)。
+ */
+export declare class SqlAdoptionLogStore implements AdoptionLogStore {
+    protected readonly db: SqlDriver;
+    constructor(db: SqlDriver);
+    private q;
+    /** 池级只读执行面(phase 0 的 preflight 扫描用——它**零写**,不需要也不该占一条事务连接)。
+     *  写路径一律走 {@link rebindTransaction};把驱动整个暴露出去会让调用方能绕开 phase CAS。 */
+    get reader(): SqlExec;
+    /**
+     * 发起腿的 **insert-or-fetch 原子形**。返回读回的行(可能是别人插的)+ 是否本次插入。
+     * 调用方据 `row.toPrincipal !== toPrincipal` 判「同 from 异 to」⇒ typed 409。
+     */
+    ensureAdoption(row: NewAdoptionRow): Promise<EnsureAdoptionResult>;
+    getById(adoptionId: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    getByFrom(fromPrincipal: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    /** I6 server 同族:每副本 boot 必查的在飞名单(**响亮**,不静默跳过)。 */
+    listInFlight(exec?: SqlExec): Promise<AdoptionRow[]>;
+    /**
+     * 迁移事务:腿的全部 UPDATE **与** phase CAS 落在**同一个事务**里。
+     *
+     * 🔴 为什么必须同事务(而不是「先迁完再推 phase」):两句分开就留下一个窗 —— 腿提交了、phase 没推,
+     * 崩溃后接棒副本重跑腿(幂等,零行变化)却把**首次的行数读数**丢了,回执里的 `legs` 会变成一串 0。
+     * 同事务之后这个窗根本不存在:要么「行迁了且 phase=3 且 legs 读数在」,要么什么都没发生。
+     * 任何异常(含唯一键违例 = 跨轴组合冲突)⇒ ROLLBACK ⇒ **源/目的地两侧字节零变更**。
+     */
+    rebindOn<L>(conn: SqlTxConn, adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, work: (exec: SqlExec) => Promise<L[]>, encodeLegs: (legs: L[]) => string): Promise<{
+        ok: true;
+        legs: L[];
+    } | {
+        ok: false;
+        reason: "phase_moved";
+    }>;
+    /**
+     * 终态**之后**的迟到行清扫事务(无 phase 变更 —— phase 已经是终态,而终态是永久的)。
+     *
+     * 🔴 它不是「再收编一次」:腿本身幂等,清扫只是把收编**结束后**又落到旧身份下的行(配置未随迁的
+     * 部署会持续制造它们)一并搬过去,并让 `current.residualSourceRows` 有个能归零的动作。
+     * `immutableReport` 一个字节都不动(史实与现势分家,183 §6)。
+     */
+    sweepOn<T>(conn: SqlTxConn, work: (exec: SqlExec) => Promise<T>): Promise<T>;
+    /** 单调 CAS 推进(无数据写的阶段;`false` = 别人已经推过了/相位不符 ⇒ 调用方重读行)。 */
+    advancePhase(adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /** phase 4:配置账物化(与 phase 推进同一条语句,免得账落了相位没推)。 */
+    putConfigs(adoptionId: string, expectPhase: number, nextPhase: number, configsJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /**
+     * ⑥ 终态:`report` 一次写入,`state='adopted'`。
+     * 🔴 `AND report IS NULL` 是 I4(永久终态 + 不可变史实)的**数据库强形**:即使调用序漂了,快照也
+     * 不可能被第二次写盖掉 —— 「逐字节恒同」于是不依赖调用方自觉。
+     */
+    finalizeAdopted(adoptionId: string, expectPhase: number, reportJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /** 目的地冲突 ⇒ rejected 终态(源/目的地两侧字节零变更;phase 停在 INTENT)。 */
+    finalizeRejected(adoptionId: string, code: AdoptionRejectCode, detail: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /**
+     * 收编弧的 advisory 锁(183 I1 的 form b 形:「与任何活写互斥」在 SQL 侧 = 一次只有一个副本在推这条弧)。
+     *
+     * **非阻塞取 + 有界轮询**(tidb-pool 的 `acquireEnsureSchemaLock` 同款判据:阻塞式 GET_LOCK 会把并发
+     * 调用方全部park 在 TiDB 的悲观锁行上,既耗它的重试预算又饿死应用自己的 FOR UPDATE 路)。取不到 ⇒
+     * 返回 `undefined`,调用方按「在飞」应答 —— **不假装成功,也不无限等**。
+     */
+    withLock<T>(name: string, fn: (conn: SqlTxConn) => Promise<T>, attempts?: number, sleepMs?: number): Promise<T | undefined>;
+}
+export declare class TiDBAdoptionLogStore extends SqlAdoptionLogStore {
+    constructor(pool: MySqlPool);
+}
+export declare class PgAdoptionLogStore extends SqlAdoptionLogStore {
+    constructor(pool: PgPool);
+}
+//# sourceMappingURL=adoption-log-sql.d.ts.map

package/dist/plugins/adoption-log-sql.js

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+export const ADOPTION_LOG_TABLE = "adoption_log";
+/** 弧的阶段(183 §3.2 根级状态机的 form b 投影)。**单调**,只增不减。 */
+export const ADOPTION_PHASE = {
+    /** ② 意图已落库(行在,尚未动任何数据行)。 */
+    INTENT: 2,
+    /** ③ 身份轴重绑腿全部完成(与腿的 UPDATE **同一个事务**)。 */
+    REBOUND: 3,
+    /** ④ 解析切换 / 配置清单产出。form b 的 server 半场:配置账已物化进 `configs`。 */
+    CONFIGS: 4,
+    /** ⑤ 承运腿。**form b 恒零承运**(数据本来就在 SQL)—— 阶段位仍显式推进,好让 form a 上车时挂得上。 */
+    CARRIED: 5,
+    /** ⑥ 永久终态。 */
+    TERMINAL: 6,
+};
+/** MySQL 协议方言的建表语句(展开进 tidb-pool 的中央 `SCHEMA_STATEMENTS`,与 approval-ask 同姿势:
+ *  跟着中央 ensureSchema 在 named-lock 的那条 conn 上建,不绕开 DDL 串行化)。 */
+export const TIDB_ADOPTION_LOG_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS ${ADOPTION_LOG_TABLE} (
+     adoption_id    VARCHAR(64)  NOT NULL,
+     -- from_principal 上的 UNIQUE = 183 D7「同一个源不许被收编两次」的**数据库强形**。
+     -- 它同时是发起腿的幂等身份:并发同参 POST 由这条约束仲裁,不靠应用层先查后插。
+     from_principal VARCHAR(190) NOT NULL,
+     to_principal   VARCHAR(190) NOT NULL,
+     phase          INT          NOT NULL,
+     state          VARCHAR(16)  NOT NULL,
+     -- legs/configs/report 是 TEXT 不是 JSON:report 的契约是「逐字节恒同」,JSON 列会重排键序(顶注)。
+     legs           MEDIUMTEXT   NOT NULL,
+     configs        MEDIUMTEXT   NOT NULL,
+     report         MEDIUMTEXT   NULL,
+     reject_code    VARCHAR(64)  NULL,
+     reject_detail  TEXT         NULL,
+     created_at_ms  BIGINT       NOT NULL,
+     updated_at_ms  BIGINT       NOT NULL,
+     PRIMARY KEY (adoption_id),
+     UNIQUE KEY uq_adoption_log_from (from_principal),
+     KEY idx_adoption_log_state (state)
+   ) COLLATE utf8mb4_bin`,
+];
+/** PostgreSQL 孪生(由 `ensurePgSchema` 在 advisory lock 的那条 client 上调用)。 */
+export async function ensurePgAdoptionLogSchema(q) {
+    await q(`CREATE TABLE IF NOT EXISTS ${ADOPTION_LOG_TABLE} (
+     adoption_id    VARCHAR(64) COLLATE "C"  NOT NULL,
+     -- MySQL 孪生的行内注解释了这条 UNIQUE 为什么是幂等身份的真源(183 D7 的 DB 强形)。
+     from_principal VARCHAR(190) COLLATE "C" NOT NULL,
+     to_principal   VARCHAR(190) COLLATE "C" NOT NULL,
+     phase          INT          NOT NULL,
+     state          VARCHAR(16) COLLATE "C"  NOT NULL,
+     legs           TEXT COLLATE "C"         NOT NULL,
+     configs        TEXT COLLATE "C"         NOT NULL,
+     report         TEXT COLLATE "C",
+     reject_code    VARCHAR(64) COLLATE "C",
+     reject_detail  TEXT COLLATE "C",
+     created_at_ms  BIGINT       NOT NULL,
+     updated_at_ms  BIGINT       NOT NULL,
+     PRIMARY KEY (adoption_id),
+     CONSTRAINT uq_adoption_log_from UNIQUE (from_principal)
+   )`);
+    await q(`CREATE INDEX IF NOT EXISTS idx_adoption_log_state ON ${ADOPTION_LOG_TABLE} (state)`);
+}
+const COLS = "adoption_id, from_principal, to_principal, phase, state, legs, configs, report, reject_code, reject_detail, created_at_ms, updated_at_ms";
+function toRow(r) {
+    return {
+        adoptionId: String(r.adoption_id),
+        fromPrincipal: String(r.from_principal),
+        toPrincipal: String(r.to_principal),
+        phase: Number(r.phase),
+        state: String(r.state),
+        legsJson: String(r.legs),
+        configsJson: String(r.configs),
+        reportJson: r.report == null ? null : String(r.report),
+        rejectCode: r.reject_code == null ? null : String(r.reject_code),
+        rejectDetail: r.reject_detail == null ? null : String(r.reject_detail),
+        createdAtMs: Number(r.created_at_ms),
+        updatedAtMs: Number(r.updated_at_ms),
+    };
+}
+/** PG advisory lock 的 32 位对象键(类键固定,对象键 = 名字的 sha256 前 4 字节转有符号 int4)。 */
+const PG_ADOPTION_LOCK_CLASS = 4907;
+function pgLockObjectKey(name) {
+    return createHash("sha256").update(name).digest().readInt32BE(0);
+}
+/**
+ * 弧锁的名字。**定长**(前缀 14 + 32 位十六进制 = 46 字符)。
+ *
+ * 🔴 为什么必须 hash 而不是把 principal 直接拼进去(codex R3-F3,亲核属实):TiDB/MySQL 的 `GET_LOCK`
+ * 锁名上限是 **64 字符**,而请求面收的 principal 到 190 —— 超过 50 字符的源身份会让取锁**在弧动起来
+ * 之前**就失败,而那时意图行已经落库,于是每一次重发、每一次副本 boot 续跑都确定性地再撞一次同一堵墙。
+ * (PG 那条腿本来就走 hash 出来的 int4 对象键,这里只是把 MySQL 腿补齐到同一姿势。)
+ */
+export function adoptionLockName(fromPrincipal) {
+    return `sema_adoption:${createHash("sha256").update(fromPrincipal).digest("hex").slice(0, 32)}`;
+}
+/**
+ * 收编日志店(单文件双方言,SqlDriver 形——checkpoint-store / approval-ask-store 同款)。
+ *
+ * 每条语句的两方言文本**并排写在调用点**(A12 判据:方言差异必须显式,不许用占位符编号循环拼)。
+ */
+export class SqlAdoptionLogStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    /** 池级只读执行面(phase 0 的 preflight 扫描用——它**零写**,不需要也不该占一条事务连接)。
+     *  写路径一律走 {@link rebindTransaction};把驱动整个暴露出去会让调用方能绕开 phase CAS。 */
+    get reader() {
+        return this.db;
+    }
+    /**
+     * 发起腿的 **insert-or-fetch 原子形**。返回读回的行(可能是别人插的)+ 是否本次插入。
+     * 调用方据 `row.toPrincipal !== toPrincipal` 判「同 from 异 to」⇒ typed 409。
+     */
+    async ensureAdoption(row) {
+        const emptyLegs = "[]";
+        const res = await this.db.query(this.q(`INSERT IGNORE INTO ${ADOPTION_LOG_TABLE} (${COLS}) VALUES (?, ?, ?, ?, 'in_flight', ?, ?, NULL, NULL, NULL, ?, ?)`, `INSERT INTO ${ADOPTION_LOG_TABLE} (${COLS}) VALUES ($1, $2, $3, $4, 'in_flight', $5, $6, NULL, NULL, NULL, $7, $8) ON CONFLICT (from_principal) DO NOTHING`), [row.adoptionId, row.fromPrincipal, row.toPrincipal, ADOPTION_PHASE.INTENT, emptyLegs, emptyLegs, row.nowMs, row.nowMs]);
+        const inserted = res.affected > 0;
+        const stored = await this.getByFrom(row.fromPrincipal);
+        if (!stored)
+            throw new Error(`ensureAdoption: row vanished right after insert (from=${row.fromPrincipal})`);
+        return { row: stored, inserted };
+    }
+    async getById(adoptionId, exec = this.db) {
+        const res = await exec.query(this.q(`SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE adoption_id = ?`, `SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE adoption_id = $1`), [adoptionId]);
+        return res.rows[0] ? toRow(res.rows[0]) : null;
+    }
+    async getByFrom(fromPrincipal, exec = this.db) {
+        const res = await exec.query(this.q(`SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE from_principal = ?`, `SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE from_principal = $1`), [fromPrincipal]);
+        return res.rows[0] ? toRow(res.rows[0]) : null;
+    }
+    /** I6 server 同族:每副本 boot 必查的在飞名单(**响亮**,不静默跳过)。 */
+    async listInFlight(exec = this.db) {
+        const res = await exec.query(this.q(`SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE state = 'in_flight' ORDER BY created_at_ms ASC`, `SELECT ${COLS} FROM ${ADOPTION_LOG_TABLE} WHERE state = 'in_flight' ORDER BY created_at_ms ASC`), []);
+        return res.rows.map(toRow);
+    }
+    /**
+     * 迁移事务:腿的全部 UPDATE **与** phase CAS 落在**同一个事务**里。
+     *
+     * 🔴 为什么必须同事务(而不是「先迁完再推 phase」):两句分开就留下一个窗 —— 腿提交了、phase 没推,
+     * 崩溃后接棒副本重跑腿(幂等,零行变化)却把**首次的行数读数**丢了,回执里的 `legs` 会变成一串 0。
+     * 同事务之后这个窗根本不存在:要么「行迁了且 phase=3 且 legs 读数在」,要么什么都没发生。
+     * 任何异常(含唯一键违例 = 跨轴组合冲突)⇒ ROLLBACK ⇒ **源/目的地两侧字节零变更**。
+     */
+    async rebindOn(conn, adoptionId, expectPhase, nextPhase, nowMs, work, encodeLegs) {
+        try {
+            await conn.begin();
+            const legs = await work(conn);
+            const cas = await conn.query(
+            // 🔴 谓词里必须带 `state = 'in_flight'`(codex R2-F1..F3 的 F3):被拒的行**故意**停在 phase INTENT
+            // (「两侧字节零变更」要求它一步都别走),所以只判 phase 的 CAS 对一条已 rejected 的行是**满足**的
+            // —— 一个在锁上排队的过期调用方于是能把一条永久拒了的弧推去迁数据。终态永久性是库级不变量,
+            // 这道守卫就该在库里,不在调用方的 if 里。
+            this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, legs = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ? AND state = 'in_flight'`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, legs = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND phase = $5 AND state = 'in_flight'`), [nextPhase, encodeLegs(legs), nowMs, adoptionId, expectPhase]);
+            if (cas.affected !== 1) {
+                await conn.rollback();
+                return { ok: false, reason: "phase_moved" };
+            }
+            await conn.commit();
+            return { ok: true, legs };
+        }
+        catch (err) {
+            try {
+                await conn.rollback();
+            }
+            catch (rollbackErr) {
+                // 🔴 不空吞(#191 静默降级门):回滚本身失败通常意味着连接已经废了,原始异常才是要上抛的那个,
+                // 但「回滚没成功」是运维必须看见的事 —— 它决定了库里可能留着一段未提交/已废弃的事务状态。
+                console.warn("[adoption-log] rollback after a failed rebind transaction also failed:", rollbackErr);
+            }
+            throw err;
+        }
+    }
+    /**
+     * 终态**之后**的迟到行清扫事务(无 phase 变更 —— phase 已经是终态,而终态是永久的)。
+     *
+     * 🔴 它不是「再收编一次」:腿本身幂等,清扫只是把收编**结束后**又落到旧身份下的行(配置未随迁的
+     * 部署会持续制造它们)一并搬过去,并让 `current.residualSourceRows` 有个能归零的动作。
+     * `immutableReport` 一个字节都不动(史实与现势分家,183 §6)。
+     */
+    async sweepOn(conn, work) {
+        try {
+            await conn.begin();
+            const out = await work(conn);
+            await conn.commit();
+            return out;
+        }
+        catch (err) {
+            try {
+                await conn.rollback();
+            }
+            catch (rollbackErr) {
+                console.warn("[adoption-log] rollback after a failed sweep transaction also failed:", rollbackErr); // 同上:不空吞
+            }
+            throw err;
+        }
+    }
+    /** 单调 CAS 推进(无数据写的阶段;`false` = 别人已经推过了/相位不符 ⇒ 调用方重读行)。 */
+    async advancePhase(adoptionId, expectPhase, nextPhase, nowMs, exec = this.db) {
+        const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ?`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, updated_at_ms = $2 WHERE adoption_id = $3 AND phase = $4`), [nextPhase, nowMs, adoptionId, expectPhase]);
+        return res.affected === 1;
+    }
+    /** phase 4:配置账物化(与 phase 推进同一条语句,免得账落了相位没推)。 */
+    async putConfigs(adoptionId, expectPhase, nextPhase, configsJson, nowMs, exec = this.db) {
+        const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, configs = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ?`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, configs = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND phase = $5`), [nextPhase, configsJson, nowMs, adoptionId, expectPhase]);
+        return res.affected === 1;
+    }
+    /**
+     * ⑥ 终态:`report` 一次写入,`state='adopted'`。
+     * 🔴 `AND report IS NULL` 是 I4(永久终态 + 不可变史实)的**数据库强形**:即使调用序漂了,快照也
+     * 不可能被第二次写盖掉 —— 「逐字节恒同」于是不依赖调用方自觉。
+     */
+    async finalizeAdopted(adoptionId, expectPhase, reportJson, nowMs, exec = this.db) {
+        const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET phase = ?, state = 'adopted', report = ?, updated_at_ms = ? WHERE adoption_id = ? AND phase = ? AND report IS NULL`, `UPDATE ${ADOPTION_LOG_TABLE} SET phase = $1, state = 'adopted', report = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND phase = $5 AND report IS NULL`), [ADOPTION_PHASE.TERMINAL, reportJson, nowMs, adoptionId, expectPhase]);
+        return res.affected === 1;
+    }
+    /** 目的地冲突 ⇒ rejected 终态(源/目的地两侧字节零变更;phase 停在 INTENT)。 */
+    async finalizeRejected(adoptionId, code, detail, nowMs, exec = this.db) {
+        const res = await exec.query(this.q(`UPDATE ${ADOPTION_LOG_TABLE} SET state = 'rejected', reject_code = ?, reject_detail = ?, updated_at_ms = ? WHERE adoption_id = ? AND state = 'in_flight'`, `UPDATE ${ADOPTION_LOG_TABLE} SET state = 'rejected', reject_code = $1, reject_detail = $2, updated_at_ms = $3 WHERE adoption_id = $4 AND state = 'in_flight'`), [code, detail, nowMs, adoptionId]);
+        return res.affected === 1;
+    }
+    /**
+     * 收编弧的 advisory 锁(183 I1 的 form b 形:「与任何活写互斥」在 SQL 侧 = 一次只有一个副本在推这条弧)。
+     *
+     * **非阻塞取 + 有界轮询**(tidb-pool 的 `acquireEnsureSchemaLock` 同款判据:阻塞式 GET_LOCK 会把并发
+     * 调用方全部park 在 TiDB 的悲观锁行上,既耗它的重试预算又饿死应用自己的 FOR UPDATE 路)。取不到 ⇒
+     * 返回 `undefined`,调用方按「在飞」应答 —— **不假装成功,也不无限等**。
+     */
+    async withLock(name, fn, attempts = 20, sleepMs = 100) {
+        const conn = await this.db.connect();
+        let held = false;
+        try {
+            for (let i = 0; i < attempts && !held; i += 1) {
+                const res = await conn.query(this.q("SELECT GET_LOCK(?, 0) AS got", "SELECT pg_try_advisory_lock($1, $2) AS got"), this.db.dialect === "tidb" ? [name] : [PG_ADOPTION_LOCK_CLASS, pgLockObjectKey(name)]);
+                const got = res.rows[0]?.got;
+                held = got === 1 || got === true || got === "1";
+                if (!held)
+                    await new Promise((r) => setTimeout(r, sleepMs));
+            }
+            if (!held)
+                return undefined;
+            // 🔴 把**这一条**连接交出去:整条弧(读 / 事务 / CAS)都跑在它上面,弧内绝不再向池要第二条
+            // ——`connectionLimit=1` 的部署上那第二条永远等不到(codex R3-F2)。
+            return await fn(conn);
+        }
+        finally {
+            if (held) {
+                try {
+                    await conn.query(this.q("SELECT RELEASE_LOCK(?) AS released", "SELECT pg_advisory_unlock($1, $2) AS released"), this.db.dialect === "tidb" ? [name] : [PG_ADOPTION_LOCK_CLASS, pgLockObjectKey(name)]);
+                }
+                catch (releaseErr) {
+                    // 锁在连接关闭时会自动释放,所以释放失败不该盖掉真正的结果 —— 但同样不空吞:
+                    // 释放失败意味着这把弧锁会一直持到连接回收,下一个副本要多等一会儿,那是要能看见的。
+                    console.warn("[adoption-log] releasing the adoption arc lock failed (it auto-frees when the connection closes):", releaseErr);
+                }
+            }
+            conn.release();
+        }
+    }
+}
+export class TiDBAdoptionLogStore extends SqlAdoptionLogStore {
+    constructor(pool) {
+        super(mysqlDriver(pool));
+    }
+}
+export class PgAdoptionLogStore extends SqlAdoptionLogStore {
+    constructor(pool) {
+        super(pgDriver(pool));
+    }
+}
+//# sourceMappingURL=adoption-log-sql.js.map

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

@@ -152,6 +152,19 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * `wiring-governance-operator.test.ts` 的 #172 组;已上报上游求一个能表达该宽度的词。
      */
     readonly fidelity: StoreFidelity;
+    /**
+     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[3342] clay 裁放行)——**如实按能力判**:
+     * 本店的 {@link SqlCheckpointStore.reopen} 是真 CAS 实现(`resolved`→`pending` 原子翻回 + `reopen_reason`
+     * 权威列,design/80 D-1 的两条重开腿都走它),声明 `reopen: true` 是读数不是抬举。core 的沙箱准入
+     * 模式(pre-flight 要求 `redecision.reopen === true`,declaration never duck-typing——方法在场不算数)
+     * 由这一格武装:Kata 腿(`capabilities.isolation` 真声明)+ durable park 部署下,`sandbox_local` ask
+     * 自动放行并以 `permission.sandbox_admitted` durable 事件披露(缺席披露=core 侧变异恰红)。
+     * `validatingLease` **不声明**:本店没有 durable validating-lease 纪律,不承诺没有的东西。
+     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
+     */
+    readonly redecision: {
+        readonly reopen: true;
+    };
     constructor(db: SqlDriver, logger?: {
         info?(msg: string, meta?: unknown): void;
     } | undefined);

package/dist/plugins/checkpoint-store-sql.js

@@ -269,6 +269,17 @@ export class SqlCheckpointStore {
      * `wiring-governance-operator.test.ts` 的 #172 组;已上报上游求一个能表达该宽度的词。
      */
     fidelity = "json";
+    /**
+     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[3342] clay 裁放行)——**如实按能力判**:
+     * 本店的 {@link SqlCheckpointStore.reopen} 是真 CAS 实现(`resolved`→`pending` 原子翻回 + `reopen_reason`
+     * 权威列,design/80 D-1 的两条重开腿都走它),声明 `reopen: true` 是读数不是抬举。core 的沙箱准入
+     * 模式(pre-flight 要求 `redecision.reopen === true`,declaration never duck-typing——方法在场不算数)
+     * 由这一格武装:Kata 腿(`capabilities.isolation` 真声明)+ durable park 部署下,`sandbox_local` ask
+     * 自动放行并以 `permission.sandbox_admitted` durable 事件披露(缺席披露=core 侧变异恰红)。
+     * `validatingLease` **不声明**:本店没有 durable validating-lease 纪律,不承诺没有的东西。
+     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
+     */
+    redecision = { reopen: true };
     constructor(db, logger) {
         this.db = db;
         this.logger = logger;

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

@@ -27,6 +27,16 @@ export declare class LocalCheckpointStore {
      * 内核哪天改宽度,包装层的声明会被那条钉当场揪出来,而不是靠人记得同步。
      */
     readonly fidelity: StoreFidelity;
+    /**
+     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[3342] clay 裁放行)——**如实按内核判**,
+     * 与 durability/fidelity 同一条判据:内核 core `FileCheckpointStore` **自己**声明 `{ reopen: true }`,
+     * 本类的 {@link LocalCheckpointStore.reopen} 纯委派给它 ⇒ 抄内核的读数是诚实的。包装类**不继承**被
+     * 包装者的声明(委派不是子类),所以这一格必须自己写。`validatingLease` 不声明(内核也没声明)。
+     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
+     */
+    readonly redecision: {
+        readonly reopen: true;
+    };
     private readonly inner;
     private readonly scopesPath;
     private readonly sessionTokensPath;

package/dist/plugins/local-checkpoint-store.js

@@ -54,6 +54,14 @@ export class LocalCheckpointStore {
      * 内核哪天改宽度,包装层的声明会被那条钉当场揪出来,而不是靠人记得同步。
      */
     fidelity = "json";
+    /**
+     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[3342] clay 裁放行)——**如实按内核判**,
+     * 与 durability/fidelity 同一条判据:内核 core `FileCheckpointStore` **自己**声明 `{ reopen: true }`,
+     * 本类的 {@link LocalCheckpointStore.reopen} 纯委派给它 ⇒ 抄内核的读数是诚实的。包装类**不继承**被
+     * 包装者的声明(委派不是子类),所以这一格必须自己写。`validatingLease` 不声明(内核也没声明)。
+     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
+     */
+    redecision = { reopen: true };
     inner;
     scopesPath;
     sessionTokensPath;