@sema-agent/server 7.10.0 → 7.11.0

package/dist/adoption/sql.js

@@ -0,0 +1,106 @@
+/** 第 `i` 个占位符(1-based)。TiDB `?` / PG `$i` —— 这是本文件唯一的方言分岔点。 */
+export function ph(dialect, i) {
+    return dialect === "tidb" ? "?" : `$${i}`;
+}
+/**
+ * 目的地冲突探针(phase 0,**任何 UPDATE 之前**)。
+ *
+ * 判据 = 「to 侧已有的行,与 from 侧的行,是否共享同一个**逻辑键**」。逻辑键 =
+ * `leg.residualKey`(该表最紧的唯一键**去掉身份轴**之后剩下的列):
+ *  · `undefined` ⇒ 没有唯一键含这根轴 ⇒ 结构性无冲突,本函数不该被调用(调用方按 `undefined` 短路);
+ *  · `[]`        ⇒ 唯一键**就是**这根轴(PK(scope))⇒ 两侧各有任意一行即冲突,退化成笛卡尔计数;
+ *  · 非空        ⇒ 逐列相等的自连接计数。
+ *
+ * 参数序:`[toValue, fromValue]`。
+ */
+export function buildConflictProbeSql(dialect, leg) {
+    const on = (leg.residualKey ?? []).map((c) => ` AND a.${c} = b.${c}`).join("");
+    return (`SELECT COUNT(*) AS n FROM ${leg.table} a, ${leg.table} b` +
+        ` WHERE a.${leg.matchColumn} = ${ph(dialect, 1)} AND b.${leg.matchColumn} = ${ph(dialect, 2)}${on}`);
+}
+/**
+ * 桶迁/行迁的等值 UPDATE。`columns` 里的每一列都被设成**同一个**新值(字节孪生 `*_key` 与可读列一起走),
+ * 谓词打在 `matchColumn` 上。参数序:`[...新值 × columns.length, 旧值]`。
+ *
+ * 幂等性来自谓词本身:重跑时旧值已经不在库里 ⇒ 零行匹配 ⇒ 零行变化。
+ */
+export function buildRebindSql(dialect, leg) {
+    const sets = leg.columns.map((c, i) => `${c} = ${ph(dialect, i + 1)}`).join(", ");
+    return `UPDATE ${leg.table} SET ${sets} WHERE ${leg.matchColumn} = ${ph(dialect, leg.columns.length + 1)}`;
+}
+/**
+ * memory 族的 scope 值扫描:把「属于这个 principal 的 scope 键」从库里**读出来**,而不是用 LIKE 去猜。
+ *
+ * 🔴 为什么不是 `LIKE '<前缀>%'`:scope 的 tenant 段是**百分号编码**的(`user%3Aweb-demo`),而 `%` 在
+ * LIKE 里是通配符 —— 不逐字符转义就会误命中别的租户的盘(**跨租户误迁**,不是性能问题)。`LEFT(col, n) = ?`
+ * 是纯等值比较,没有元字符面,两方言同形。
+ *
+ * 参数序:`[userScope, projHead.length, projHead, userProjHead.length, userProjHead]`。
+ */
+export function buildMemoryScopeScanSql(dialect, table) {
+    return (`SELECT DISTINCT scope FROM ${table}` +
+        ` WHERE scope = ${ph(dialect, 1)}` +
+        ` OR LEFT(scope, ${ph(dialect, 2)}) = ${ph(dialect, 3)}` +
+        ` OR LEFT(scope, ${ph(dialect, 4)}) = ${ph(dialect, 5)}`);
+}
+/**
+ * 残留计数:某条腿上**仍挂在旧身份名下**的行数。参数序:`[fromValue]`。
+ *
+ * 用途见 wire.ts 的 `current.residualSourceRows`:收编不给普通写者上栅栏(183 I1 = 运维前提「引擎先停」),
+ * 所以「终态之后旧身份下又长出行」是一个真实可能的形 —— 这条查询把它变成可见读数,而不是靠祈祷。
+ */
+export function buildResidualCountSql(dialect, table, matchColumns) {
+    // 🔴 **一张表一条 COUNT**,谓词是该表全部身份轴的**并**(codex R3-F4):逐腿各数一次会把一条
+    // 两根轴都还带旧身份的行数成 2(background_agent 甚至能数成 3),而字段名承诺的是「行数」。
+    const where = matchColumns.map((c, i) => `${c} = ${ph(dialect, i + 1)}`).join(" OR ");
+    return `SELECT COUNT(*) AS n FROM ${table} WHERE ${where}`;
+}
+/**
+ * `blob-rewrite` 腿的扫描:按**旧**身份值把行连同 JSON 载荷读出来。
+ * 匹配面 = `matchColumn` 与 `blob.alsoMatch` 的**并**(同表两根轴都可能带旧值)。
+ * 参数序:`[fromValue × (1 + alsoMatch.length)]`。
+ */
+export function buildBlobScanSql(dialect, leg) {
+    const blob = leg.blob;
+    if (blob === undefined)
+        throw new Error(`buildBlobScanSql: leg ${leg.leg} has no blob spec`);
+    const cols = [...blob.pk, blob.revColumn, blob.column].join(", ");
+    // 🔴 匹配面同时收**旧值与新值**两个桶(codex R2-F1 的可见性半):投影列已经迁了、载荷还停在旧身份的
+    // 那种「劈开」行(列腿与载荷腿之间插进来的写、或上一轮扫描漏掉的行),只按旧值找是**永远找不到**的
+    // ——而那正是最危险的一类残留:黑盒上看起来已迁移。载荷里真带旧身份才会被改写,所以多扫一个桶零副作用。
+    const cells = [leg.matchColumn, ...(blob.alsoMatch ?? [])];
+    const match = [...cells.map((c, i) => `${c} = ${ph(dialect, i + 1)}`), ...cells.map((c, i) => `${c} = ${ph(dialect, cells.length + i + 1)}`)].join(" OR ");
+    return `SELECT ${cols} FROM ${leg.table} WHERE ${match}`;
+}
+/**
+ * `blob-rewrite` 腿的逐行回写。参数序:`[新载荷文本, ...pk 值]`。
+ *
+ * 幂等性:重跑时载荷里的身份字段已是新值 ⇒ 调用方算出的新载荷与库里逐字节相同 ⇒ 语义无操作
+ * (行数可能仍报 1,故回执的行数按「**内容真变了**才计」在调用侧收窄)。
+ */
+export function buildBlobWriteSql(dialect, leg) {
+    const blob = leg.blob;
+    if (blob === undefined)
+        throw new Error(`buildBlobWriteSql: leg ${leg.leg} has no blob spec`);
+    const where = blob.pk.map((c, i) => `${c} = ${ph(dialect, i + 2)}`).join(" AND ");
+    // 🔴 `AND rev = ?` = 乐观并发守卫(codex R2-F1):这三张表的正常写路径都用 rev 做 CAS,收编不许绕过。
+    // 读到的 rev 与写时不符 ⇒ `affected === 0` ⇒ 调用方响亮抛、整事务回滚,而不是把别人刚写的载荷盖掉。
+    // 🔴 `SET rev = rev + 1` 同样是承重的(codex R3-F1):只**读**不**推**这把守卫,一个在收编写入**之前**
+    // 就读到 rev=N 的正常写者,在收编提交之后仍然能以 rev=N 的 CAS 写成功,把刚迁好的载荷原样盖回旧身份
+    // —— 收编那时已经报 adopted。推进 rev 才让那些「站在过去」的写者按 OCC 的本意输掉并重试。
+    return `UPDATE ${leg.table} SET ${blob.column} = ${ph(dialect, 1)}, ${blob.revColumn} = ${blob.revColumn} + 1 WHERE ${where} AND ${blob.revColumn} = ${ph(dialect, blob.pk.length + 2)}`;
+}
+/** session_policy 重键腿的扫描:拿到 from 侧每一行的 `(policy_key, session_id)`。参数序:`[fromPrincipal]`。 */
+export function buildSessionPolicyScanSql(dialect) {
+    return `SELECT policy_key, session_id FROM session_policy WHERE principal = ${ph(dialect, 1)}`;
+}
+/**
+ * session_policy 的逐行重键改写。`policy_key = sha256(JSON.stringify([sessionId, principal ?? null]))`,
+ * 身份在**主键的 hash 原像**里 ⇒ 等值 UPDATE 够不着,必须读出来重算再改写。
+ * 参数序:`[newPolicyKey, toPrincipal, oldPolicyKey]`。
+ */
+export function buildSessionPolicyRewriteSql(dialect) {
+    return (`UPDATE session_policy SET policy_key = ${ph(dialect, 1)}, principal = ${ph(dialect, 2)}` +
+        ` WHERE policy_key = ${ph(dialect, 3)}`);
+}
+//# sourceMappingURL=sql.js.map

package/dist/adoption/wire.d.ts

@@ -0,0 +1,250 @@
+/**
+ * design/183 §6 —— 收编回执的**唯一包络**(form b:纯身份重绑,数据已在 SQL、承运腿为零)。
+ *
+ * 🔴 为什么 schema 在这里而不是散在路由里(clay 最高宪法「边界必 schema 禁裸 as-cast」):这份包络是
+ * **跨仓 wire 契约** —— 下游(cli / web-admin / 围栏 E2E)要按字段名逐字钉围栏。请求体在入口 zod 解析,
+ * 响应体从这里的类型铸出,于是「路由改了字段名而围栏不知道」是编译红而不是运行期静默漂移。
+ *
+ * ── 与 183 §6 的**逐条差异**(如实登记,不假装同形)────────────────────────────────────────────────
+ *  ① `AdoptionReport.credentials` **缺席**。183 的那一格服务的是 form a「云铸新身份 ⇒ 凭据领取位」;
+ *     form b 的 `toPrincipal` 是**运维在请求体里点名的既存身份**,本车不铸任何凭据 ⇒ 给一个 `ref` 就是
+ *     凭空发明一个兑取不到的 claim(而 183 §4.3 恰恰要求该 ref 是 durable 可重复兑取的)。缺席是诚实,
+ *     假字段是谎。form a 承运车落地时由那台车补这一格。
+ *  ② `AdoptionReceipt.current.quarantined` **恒 0**。隔离位是承运腿(对端拒收行)的概念,form b 零承运
+ *     ⇒ 结构位在场、读数恒 0。保留字段是为了 form a 上车时包络不变形(下游围栏不用改)。
+ *  ③ `notMigratedByDesign` 是 **v2 小票新增**的机读位(183 只在散文里说「按设计不迁」)。成员标识符
+ *     ({@link NotMigratedFace})与字段名一样是**冻结的机读词表**,下游按它写正向断言(§10.5:把「按
+ *     设计不迁」与「漏了没迁」在黑盒上分开)。加成员=加行为面,减成员=下游围栏红。
+ *
+ * `immutableReport` 逐字节恒同 = 幂等判据(183 §8):它在 phase 6 一次性落库,此后任何重跑原样回放,
+ * **绝不重算**。`current` 反过来每次现算(配置账未见证项、隔离计数),两半各钉各的(§10.6)。
+ */
+import { z } from "zod";
+/** 收编来源(form b 只有具名 principal 一形;`local-owner` 是 form a 的形,本车不产出也不接受)。 */
+export declare const AdoptionSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"principal">;
+    principal: z.ZodString;
+}, z.core.$strict>;
+export type AdoptionSource = z.infer<typeof AdoptionSourceSchema>;
+/** per-store 腿的动作词(183 §6 闭集;form b 只会产出前两个 + `none`)。 */
+export declare const AdoptionLegActionSchema: z.ZodEnum<{
+    reset: "reset";
+    none: "none";
+    "bucket-rebind": "bucket-rebind";
+    "row-rewrite": "row-rewrite";
+    carried: "carried";
+}>;
+export type AdoptionLegAction = z.infer<typeof AdoptionLegActionSchema>;
+export declare const AdoptionLegSchema: z.ZodObject<{
+    store: z.ZodString;
+    action: z.ZodEnum<{
+        reset: "reset";
+        none: "none";
+        "bucket-rebind": "bucket-rebind";
+        "row-rewrite": "row-rewrite";
+        carried: "carried";
+    }>;
+    rows: z.ZodOptional<z.ZodNumber>;
+    quarantined: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AdoptionLeg = z.infer<typeof AdoptionLegSchema>;
+/**
+ * 受影响部署配置清单(183 §6 表)。`migrated` 对 server 半场**恒 false**——这些配置全在别的部署单元
+ * (BFF / cli / env / core 声明位),收编动作**够不到**它们,而 183 §3.3 的明令是「改不到的配置,不假装
+ * 改了」。清单在场 + `migrated:false` + 配置账不清 = 下游围栏「配置不迁如实红」的凭据(§10.4)。
+ */
+export declare const AdoptionConfigEntrySchema: z.ZodObject<{
+    deployment: z.ZodString;
+    key: z.ZodString;
+    requiredValue: z.ZodString;
+    migrated: z.ZodBoolean;
+    ack: z.ZodBoolean;
+    witnessedAtMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export type AdoptionConfigEntry = z.infer<typeof AdoptionConfigEntrySchema>;
+/**
+ * **机读词表**:server 侧按设计不迁的面,逐项挂 183 的裁决号。
+ *
+ * 🔴 这是**冻结的闭集**(下游按成员名写正向断言)。改名/删员 = wire 破坏;新增 = 新行为面,要先过三问。
+ * 判据形见 183 §10.5:「按设计不迁」与「漏了没迁」在黑盒上必须可分,所以它是**正向声明**而不是沉默。
+ */
+export declare const NOT_MIGRATED_FACES: readonly ["usage-window", "cost-quota", "rate-limit", "approval-exemption-grantor", "approval-ask-decision-actor", "image-bake-requested-by"];
+export type NotMigratedFace = (typeof NOT_MIGRATED_FACES)[number];
+export declare const AdoptionNotMigratedSchema: z.ZodObject<{
+    face: z.ZodEnum<{
+        "usage-window": "usage-window";
+        "cost-quota": "cost-quota";
+        "rate-limit": "rate-limit";
+        "approval-exemption-grantor": "approval-exemption-grantor";
+        "approval-ask-decision-actor": "approval-ask-decision-actor";
+        "image-bake-requested-by": "image-bake-requested-by";
+    }>;
+    ruling: z.ZodEnum<{
+        D1: "D1";
+        D2: "D2";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type AdoptionNotMigrated = z.infer<typeof AdoptionNotMigratedSchema>;
+/** 终态快照(**不可变史实**,phase 6 一次落库,逐字节恒同 —— 183 I4 + §8 幂等判据)。 */
+export declare const AdoptionReportSchema: z.ZodObject<{
+    adoptionId: z.ZodString;
+    form: z.ZodLiteral<"b">;
+    from: z.ZodObject<{
+        kind: z.ZodLiteral<"principal">;
+        principal: z.ZodString;
+    }, z.core.$strict>;
+    toPrincipal: z.ZodString;
+    atMs: z.ZodNumber;
+    affectedDeploymentConfigs: z.ZodArray<z.ZodObject<{
+        deployment: z.ZodString;
+        key: z.ZodString;
+        requiredValue: z.ZodString;
+        migrated: z.ZodBoolean;
+        ack: z.ZodBoolean;
+        witnessedAtMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+    legs: z.ZodArray<z.ZodObject<{
+        store: z.ZodString;
+        action: z.ZodEnum<{
+            reset: "reset";
+            none: "none";
+            "bucket-rebind": "bucket-rebind";
+            "row-rewrite": "row-rewrite";
+            carried: "carried";
+        }>;
+        rows: z.ZodOptional<z.ZodNumber>;
+        quarantined: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    notMigratedByDesign: z.ZodArray<z.ZodObject<{
+        face: z.ZodEnum<{
+            "usage-window": "usage-window";
+            "cost-quota": "cost-quota";
+            "rate-limit": "rate-limit";
+            "approval-exemption-grantor": "approval-exemption-grantor";
+            "approval-ask-decision-actor": "approval-ask-decision-actor";
+            "image-bake-requested-by": "image-bake-requested-by";
+        }>;
+        ruling: z.ZodEnum<{
+            D1: "D1";
+            D2: "D2";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AdoptionReport = z.infer<typeof AdoptionReportSchema>;
+/**
+ * 唯一回执包络。**首次成功与一切幂等重跑同形**(183 §6 r7);别处不得另造第二种回执。
+ *
+ * `status`:`adopted` = 终态在;`stalled` = 在飞(锁被别的副本持着 / 崩溃后尚未续完)。
+ * **`rejected` 不在这个闭集里**:被拒的收编从来不产出回执,POST 与 GET 一律以 typed 409 应答
+ * (`adoption.destination_conflict` / `adoption.source_already_bound`),否则「拒」与「成」共用一个 200
+ * 包络,消费端要靠读字段猜——那正是 183 §7.3「拒绝可判别」要消灭的形。
+ */
+export declare const AdoptionReceiptSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        stalled: "stalled";
+        adopted: "adopted";
+    }>;
+    immutableReport: z.ZodObject<{
+        adoptionId: z.ZodString;
+        form: z.ZodLiteral<"b">;
+        from: z.ZodObject<{
+            kind: z.ZodLiteral<"principal">;
+            principal: z.ZodString;
+        }, z.core.$strict>;
+        toPrincipal: z.ZodString;
+        atMs: z.ZodNumber;
+        affectedDeploymentConfigs: z.ZodArray<z.ZodObject<{
+            deployment: z.ZodString;
+            key: z.ZodString;
+            requiredValue: z.ZodString;
+            migrated: z.ZodBoolean;
+            ack: z.ZodBoolean;
+            witnessedAtMs: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>>;
+        legs: z.ZodArray<z.ZodObject<{
+            store: z.ZodString;
+            action: z.ZodEnum<{
+                reset: "reset";
+                none: "none";
+                "bucket-rebind": "bucket-rebind";
+                "row-rewrite": "row-rewrite";
+                carried: "carried";
+            }>;
+            rows: z.ZodOptional<z.ZodNumber>;
+            quarantined: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        notMigratedByDesign: z.ZodArray<z.ZodObject<{
+            face: z.ZodEnum<{
+                "usage-window": "usage-window";
+                "cost-quota": "cost-quota";
+                "rate-limit": "rate-limit";
+                "approval-exemption-grantor": "approval-exemption-grantor";
+                "approval-ask-decision-actor": "approval-ask-decision-actor";
+                "image-bake-requested-by": "image-bake-requested-by";
+            }>;
+            ruling: z.ZodEnum<{
+                D1: "D1";
+                D2: "D2";
+            }>;
+            reason: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    current: z.ZodObject<{
+        outstandingConfigs: z.ZodArray<z.ZodString>;
+        quarantined: z.ZodNumber;
+        residualSourceRows: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AdoptionReceipt = z.infer<typeof AdoptionReceiptSchema>;
+/**
+ * 库里那三个 JSON 文本列(`legs` / `configs` / `reject_detail`)读回内域时的 schema。
+ *
+ * 🔴 为什么不是「解析完直接裸铸形」(clay 最高宪法 §2 + `boundary-cast-gate`):DB 行与 HTTP body 同属
+ * **进程外数据**。裸 `as` 是「库里的字节直接冒充内域类型」—— 一次手改库/一次旧版本残留行,坏形就会带着
+ * 一个说谎的类型annotation 流进回执,而回执是下游围栏的判据源。
+ */
+export declare const AdoptionLegsSchema: z.ZodArray<z.ZodObject<{
+    store: z.ZodString;
+    action: z.ZodEnum<{
+        reset: "reset";
+        none: "none";
+        "bucket-rebind": "bucket-rebind";
+        "row-rewrite": "row-rewrite";
+        carried: "carried";
+    }>;
+    rows: z.ZodOptional<z.ZodNumber>;
+    quarantined: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>>;
+export declare const AdoptionConfigsSchema: z.ZodArray<z.ZodObject<{
+    deployment: z.ZodString;
+    key: z.ZodString;
+    requiredValue: z.ZodString;
+    migrated: z.ZodBoolean;
+    ack: z.ZodBoolean;
+    witnessedAtMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>>;
+export declare const AdoptionRejectDetailSchema: z.ZodObject<{
+    detail: z.ZodString;
+    conflicts: z.ZodArray<z.ZodObject<{
+        leg: z.ZodString;
+        table: z.ZodString;
+        overlapping: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AdoptionRejectDetail = z.infer<typeof AdoptionRejectDetailSchema>;
+/**
+ * 拒绝码的**闭集**(与附录 A 的 `adoption.*` 族逐字同名)。住在 wire 契约里而不是实现里,因为落库的
+ * `adoption_log.reject_code` 与 wire 上的 `errorCode` 必须是**同一个词表** —— 两处各写一份字符串字面量,
+ * 就是「库里记了一个 wire 上不存在的码」这类漂移的入口。路由的 switch 对它穷举:加成员即编译红。
+ */
+export declare const ADOPTION_REJECT_CODES: readonly ["adoption.destination_conflict", "adoption.destination_unrepresentable"];
+export type AdoptionRejectCode = (typeof ADOPTION_REJECT_CODES)[number];
+/** `POST /v1/adoption` 的请求体。`.strict()` = 写面纪律:多余键是调用方错误,当场 400(不静默吞)。 */
+export declare const AdoptionRequestSchema: z.ZodObject<{
+    fromPrincipal: z.ZodString;
+    toPrincipal: z.ZodString;
+}, z.core.$strict>;
+export type AdoptionRequest = z.infer<typeof AdoptionRequestSchema>;
+//# sourceMappingURL=wire.d.ts.map

package/dist/adoption/wire.js

@@ -0,0 +1,153 @@
+/**
+ * design/183 §6 —— 收编回执的**唯一包络**(form b:纯身份重绑,数据已在 SQL、承运腿为零)。
+ *
+ * 🔴 为什么 schema 在这里而不是散在路由里(clay 最高宪法「边界必 schema 禁裸 as-cast」):这份包络是
+ * **跨仓 wire 契约** —— 下游(cli / web-admin / 围栏 E2E)要按字段名逐字钉围栏。请求体在入口 zod 解析,
+ * 响应体从这里的类型铸出,于是「路由改了字段名而围栏不知道」是编译红而不是运行期静默漂移。
+ *
+ * ── 与 183 §6 的**逐条差异**(如实登记,不假装同形)────────────────────────────────────────────────
+ *  ① `AdoptionReport.credentials` **缺席**。183 的那一格服务的是 form a「云铸新身份 ⇒ 凭据领取位」;
+ *     form b 的 `toPrincipal` 是**运维在请求体里点名的既存身份**,本车不铸任何凭据 ⇒ 给一个 `ref` 就是
+ *     凭空发明一个兑取不到的 claim(而 183 §4.3 恰恰要求该 ref 是 durable 可重复兑取的)。缺席是诚实,
+ *     假字段是谎。form a 承运车落地时由那台车补这一格。
+ *  ② `AdoptionReceipt.current.quarantined` **恒 0**。隔离位是承运腿(对端拒收行)的概念,form b 零承运
+ *     ⇒ 结构位在场、读数恒 0。保留字段是为了 form a 上车时包络不变形(下游围栏不用改)。
+ *  ③ `notMigratedByDesign` 是 **v2 小票新增**的机读位(183 只在散文里说「按设计不迁」)。成员标识符
+ *     ({@link NotMigratedFace})与字段名一样是**冻结的机读词表**,下游按它写正向断言(§10.5:把「按
+ *     设计不迁」与「漏了没迁」在黑盒上分开)。加成员=加行为面,减成员=下游围栏红。
+ *
+ * `immutableReport` 逐字节恒同 = 幂等判据(183 §8):它在 phase 6 一次性落库,此后任何重跑原样回放,
+ * **绝不重算**。`current` 反过来每次现算(配置账未见证项、隔离计数),两半各钉各的(§10.6)。
+ */
+import { z } from "zod";
+/** 收编来源(form b 只有具名 principal 一形;`local-owner` 是 form a 的形,本车不产出也不接受)。 */
+export const AdoptionSourceSchema = z.object({ kind: z.literal("principal"), principal: z.string().min(1) }).strict();
+/** per-store 腿的动作词(183 §6 闭集;form b 只会产出前两个 + `none`)。 */
+export const AdoptionLegActionSchema = z.enum(["bucket-rebind", "row-rewrite", "carried", "none", "reset"]);
+export const AdoptionLegSchema = z
+    .object({
+    /** 腿的稳定标识 = `<表名>#<身份轴列>`(下游按它对账;表名/列名都是本仓 schema 的真名)。 */
+    store: z.string().min(1),
+    action: AdoptionLegActionSchema,
+    /** 本次真改了几行。**重跑恒 0**,而 `immutableReport` 里冻的是**首次**的读数(史实)。 */
+    rows: z.number().int().nonnegative().optional(),
+    quarantined: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * 受影响部署配置清单(183 §6 表)。`migrated` 对 server 半场**恒 false**——这些配置全在别的部署单元
+ * (BFF / cli / env / core 声明位),收编动作**够不到**它们,而 183 §3.3 的明令是「改不到的配置,不假装
+ * 改了」。清单在场 + `migrated:false` + 配置账不清 = 下游围栏「配置不迁如实红」的凭据(§10.4)。
+ */
+export const AdoptionConfigEntrySchema = z
+    .object({
+    deployment: z.string().min(1),
+    key: z.string().min(1),
+    requiredValue: z.string(),
+    migrated: z.boolean(),
+    /** 运维表态位(只作记录,**不清账**——183 r3 按 codex r2-F6:手写布尔可以把账清成假绿)。 */
+    ack: z.boolean(),
+    /** 消费端运行时真读回 requiredValue 的 typed 回执时刻。**null = 未见证 = 未清账**。 */
+    witnessedAtMs: z.number().int().nonnegative().nullable(),
+})
+    .strict();
+/**
+ * **机读词表**:server 侧按设计不迁的面,逐项挂 183 的裁决号。
+ *
+ * 🔴 这是**冻结的闭集**(下游按成员名写正向断言)。改名/删员 = wire 破坏;新增 = 新行为面,要先过三问。
+ * 判据形见 183 §10.5:「按设计不迁」与「漏了没迁」在黑盒上必须可分,所以它是**正向声明**而不是沉默。
+ */
+export const NOT_MIGRATED_FACES = [
+    "usage-window",
+    "cost-quota",
+    "rate-limit",
+    "approval-exemption-grantor",
+    "approval-ask-decision-actor",
+    "image-bake-requested-by",
+];
+export const AdoptionNotMigratedSchema = z
+    .object({
+    face: z.enum(NOT_MIGRATED_FACES),
+    /** 183 §12 的裁决号(`D1` = 配额窗清零重计;`D2` = 史实字段不改写)。 */
+    ruling: z.enum(["D1", "D2"]),
+    reason: z.string().min(1),
+})
+    .strict();
+/** 终态快照(**不可变史实**,phase 6 一次落库,逐字节恒同 —— 183 I4 + §8 幂等判据)。 */
+export const AdoptionReportSchema = z
+    .object({
+    adoptionId: z.string().min(1),
+    /** 本车只做 form b;`form` 显式在场是为了 form a 上车后回执可分辨(下游不必按缺席位推断)。 */
+    form: z.literal("b"),
+    from: AdoptionSourceSchema,
+    toPrincipal: z.string().min(1),
+    atMs: z.number().int().nonnegative(),
+    affectedDeploymentConfigs: z.array(AdoptionConfigEntrySchema),
+    legs: z.array(AdoptionLegSchema),
+    notMigratedByDesign: z.array(AdoptionNotMigratedSchema),
+})
+    .strict();
+/**
+ * 唯一回执包络。**首次成功与一切幂等重跑同形**(183 §6 r7);别处不得另造第二种回执。
+ *
+ * `status`:`adopted` = 终态在;`stalled` = 在飞(锁被别的副本持着 / 崩溃后尚未续完)。
+ * **`rejected` 不在这个闭集里**:被拒的收编从来不产出回执,POST 与 GET 一律以 typed 409 应答
+ * (`adoption.destination_conflict` / `adoption.source_already_bound`),否则「拒」与「成」共用一个 200
+ * 包络,消费端要靠读字段猜——那正是 183 §7.3「拒绝可判别」要消灭的形。
+ */
+export const AdoptionReceiptSchema = z
+    .object({
+    status: z.enum(["adopted", "stalled"]),
+    immutableReport: AdoptionReportSchema,
+    current: z
+        .object({
+        /** 配置账里 `witnessedAtMs === null` 的项(`<deployment>:<key>`)。空 = 账已清。 */
+        outstandingConfigs: z.array(z.string()),
+        /** form b 恒 0(零承运 ⇒ 无拒收行);字段在场见本文件顶注差异②。 */
+        quarantined: z.number().int().nonnegative(),
+        /**
+         * **仍挂在旧身份名下的行数**(每次现算,跨全部迁移腿求和)。
+         *
+         * 🔴 为什么这一格是承重的(codex 对抗复审 R1-F1,采纳其可检测半):收编**不**给普通写者上栅栏
+         * ——183 I1 的口径是「引擎必须先停」,那是**运维前提**,不是机器保证。于是一个还在按旧身份注入的
+         * 调用方(配置未随迁 ⇒ `outstandingConfigs` 非空)会在终态之后继续往旧身份下写行,而终态 + 幂等
+         * 短路会让回执一直说「adopted」。
+         *
+         * 这一格把那件事**变成可见的读数**:`>0` = 这个部署仍在往旧身份写,配置随迁没做完。
+         * 每次 **POST**(写动词)会顺带把这些迟到行扫进新身份并重报此数;**GET** 只读不扫。
+         * `immutableReport` 是史实、不受影响 —— 史实与现势各住各的字段(183 §6)。
+         */
+        residualSourceRows: z.number().int().nonnegative(),
+    })
+        .strict(),
+})
+    .strict();
+/**
+ * 库里那三个 JSON 文本列(`legs` / `configs` / `reject_detail`)读回内域时的 schema。
+ *
+ * 🔴 为什么不是「解析完直接裸铸形」(clay 最高宪法 §2 + `boundary-cast-gate`):DB 行与 HTTP body 同属
+ * **进程外数据**。裸 `as` 是「库里的字节直接冒充内域类型」—— 一次手改库/一次旧版本残留行,坏形就会带着
+ * 一个说谎的类型annotation 流进回执,而回执是下游围栏的判据源。
+ */
+export const AdoptionLegsSchema = z.array(AdoptionLegSchema);
+export const AdoptionConfigsSchema = z.array(AdoptionConfigEntrySchema);
+export const AdoptionRejectDetailSchema = z
+    .object({
+    detail: z.string(),
+    conflicts: z.array(z.object({ leg: z.string(), table: z.string(), overlapping: z.number().int().nonnegative() }).strict()),
+})
+    .strict();
+/**
+ * 拒绝码的**闭集**(与附录 A 的 `adoption.*` 族逐字同名)。住在 wire 契约里而不是实现里,因为落库的
+ * `adoption_log.reject_code` 与 wire 上的 `errorCode` 必须是**同一个词表** —— 两处各写一份字符串字面量,
+ * 就是「库里记了一个 wire 上不存在的码」这类漂移的入口。路由的 switch 对它穷举:加成员即编译红。
+ */
+export const ADOPTION_REJECT_CODES = ["adoption.destination_conflict", "adoption.destination_unrepresentable"];
+/** `POST /v1/adoption` 的请求体。`.strict()` = 写面纪律:多余键是调用方错误,当场 400(不静默吞)。 */
+export const AdoptionRequestSchema = z
+    .object({
+    fromPrincipal: z.string().min(1).max(190),
+    toPrincipal: z.string().min(1).max(190),
+})
+    .strict();
+//# sourceMappingURL=wire.js.map

package/dist/approval-card.d.ts

@@ -50,6 +50,14 @@ export declare const ApprovalCardSchema: z.ZodObject<{
         requiresRealApproval: z.ZodBoolean;
     }, z.core.$strict>;
     governanceForced: z.ZodOptional<z.ZodLiteral<true>>;
+    ruleSuggestions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        rule: z.ZodString;
+        match: z.ZodEnum<{
+            exact: "exact";
+            prefix: "prefix";
+        }>;
+        command: z.ZodString;
+    }, z.core.$strict>>>;
     fromSubagent: z.ZodOptional<z.ZodLiteral<true>>;
     sourceTaskId: z.ZodOptional<z.ZodString>;
     sourceAgentName: z.ZodOptional<z.ZodString>;
@@ -81,6 +89,14 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
             requiresRealApproval: z.ZodBoolean;
         }, z.core.$strict>;
         governanceForced: z.ZodOptional<z.ZodLiteral<true>>;
+        ruleSuggestions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            rule: z.ZodString;
+            match: z.ZodEnum<{
+                exact: "exact";
+                prefix: "prefix";
+            }>;
+            command: z.ZodString;
+        }, z.core.$strict>>>;
         fromSubagent: z.ZodOptional<z.ZodLiteral<true>>;
         sourceTaskId: z.ZodOptional<z.ZodString>;
         sourceAgentName: z.ZodOptional<z.ZodString>;
@@ -116,6 +132,14 @@ export interface ApprovalCardSource {
     /** [2942]/[2943]:治理来源标 —— 与 wire 帧**同一份素材**(`ToolApprovalFrame` 结构上满足本接口),
      *  于是 live 帧 / `card_json` / 重放帧三面同源,不是三处各判一遍。 */
     governanceForced?: true;
+    /** #154 车二:引擎铸的规则候选(**只在规则店装配时**由发帧点填;语义与在场性契约见
+     *  `ApprovalCardSchema.ruleSuggestions`)。与 wire 帧**同一份素材** ⇒ live 帧 / `card_json` / 重放帧
+     *  三面同源。 */
+    ruleSuggestions?: ReadonlyArray<{
+        rule: string;
+        match: "exact" | "prefix";
+        command: string;
+    }>;
     fromSubagent?: true;
     sourceTaskId?: string;
     /** 已 redactSecrets。 */

package/dist/approval-card.js

@@ -21,6 +21,7 @@
  * 没有方法、没有捕获的行为。
  */
 import { z } from "zod";
+import { MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 /** 模型自由文本(`sourceAgentName` / `delegation.agentName`)的限长(设计稿 §6.2)。设计 §3.1 把
  *  「限长 + 脱敏」写成 **server 新增责任**(引擎无此层):spawning model 挑的名字是自由文本,
  *  不能指望壳去截——一条 100KB 的 agentName 在 server 侧就该被拒,而不是变成一张撑爆呈卡面的卡。 */
@@ -78,6 +79,32 @@ export const ApprovalCardSchema = z
      * park(fail-safe),回滚窗结束即自愈。
      */
     governanceForced: z.literal(true).optional(),
+    /**
+     * #154 车二(core 5.18.0 design/179):引擎为这次 ask 铸的**规则候选**(`Bash(git status)` 精确 /
+     * `Bash(git status:*)` 词界前缀)—— 呈卡面据它渲「不再询问」。
+     *
+     * 🔴 **在场性即承诺**:这一格只在**规则店真装配**(`RunnerDeps.permissionRuleStore` 在场 ⇔ manifest
+     * 的 `permissionRules.storeWired: true`)时投影。店缺席仍投 = 给客户端渲一格它按下去无处可兑的
+     * 「不再询问」,那是 wire 谎言,比缺席更坏(判据逐字见 `core-keyset-guard.ts` ④ 面本键那一段)。
+     * 缺席 ⇒ 这只 ask 没有可兑的候选(命令不可匹配,或本部署没接店),两种都读作「本卡无此选项」。
+     * 值**逐字**取自 core(闭词表 `match` + 引擎铸的文本),server 不重铸、不重排。
+     *
+     * ⚠️ **兑付面的射程,如实说清**(codex 交叉复审 round1 [medium],验真后按「真实但已知」登记):
+     * 本键随卡进 `card_json`,于是重放帧也带它;而它的兑付通道**只有一条** —— 重放帧自己携带的
+     * `approvalId` 所指的那条 live 回决口(`POST /v1/tool-approvals/:id/respond` 的 `persistRule`)。
+     * 那条口是**进程内**的(pending map 随副本走),所以:同副本重连 ⇒ 兑得动;换副本/重启之后 ⇒ 那个
+     * `approvalId` 已经 404,人只能走 durable 回决口(`POST /v1/tasks/:id/asks/:askId/decision`),
+     * 而**那条口 v1 不带规则位**(它的 zod 体是 `.strict()`,多给一个 `persistRule` 是响亮 400,不是静默丢)。
+     * 这不是本键独有的射程:`approvalId` 本身就是同一个可用性信封(卡还能不能被这条通道决,取决于它)。
+     * ⇒ 处置 = 不缩键(缩了,同副本重连这条真实可用的路也一起没了),把「durable 回决腿的规则位」
+     * 登记为后续件(车4 域)。
+     */
+    ruleSuggestions: z
+        .array(z
+        .object({ rule: z.string().max(MAX_RULE_TEXT_CHARS), match: z.enum(["exact", "prefix"]), command: z.string().max(MAX_RULE_TEXT_CHARS) })
+        .strict())
+        .max(4)
+        .optional(),
     /** 委派出处(子代 ask 才在场;判别键 = `fromSubagent`,core RB-39②)。 */
     fromSubagent: z.literal(true).optional(),
     sourceTaskId: z.string().max(MAX_IDENT).optional(),
@@ -168,6 +195,11 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
         },
         // [2942]/[2943]:只在为真时投影(`=== true` 严判:非布尔真值不得把一张普通卡染成治理卡)。
         ...(source.governanceForced === true ? { governanceForced: true } : {}),
+        // #154 车二:候选**逐字**投影(空数组 ⇒ 不投键 —— 「没有候选」与「本部署不供候选」在卡面上都读作
+        // 「本卡无此选项」,铸一个空数组只会让消费端多一条无意义的分支)。拷贝一份:卡不与调用方共享可变引用。
+        ...(source.ruleSuggestions !== undefined && source.ruleSuggestions.length > 0
+            ? { ruleSuggestions: source.ruleSuggestions.map((s) => ({ rule: s.rule, match: s.match, command: s.command })) }
+            : {}),
         ...(source.fromSubagent === true ? { fromSubagent: true } : {}),
         ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
         ...(sourceAgentName !== undefined ? { sourceAgentName } : {}),

package/dist/boot/adoption.d.ts

@@ -0,0 +1,30 @@
+import type { StoreBackend } from "../plugins/store-backend.js";
+export interface AdoptionBootCtx {
+    backend: StoreBackend | undefined;
+    logger: {
+        info?(msg: string, meta?: unknown): void;
+        warn?(msg: string, meta?: unknown): void;
+        error?(msg: string, meta?: unknown): void;
+    };
+    now?: () => number;
+}
+export interface AdoptionBootReading {
+    /** 本次扫到的在飞行数(0 = 常态)。 */
+    scanned: number;
+    /** 推到终态的弧。 */
+    resumed: string[];
+    /** 推不动的弧(锁被别的副本持着,或还差一步)—— 留在库里,下一个副本/下一次读面继续推。 */
+    stalled: string[];
+    /** 续跑时撞上目的地冲突而落 rejected 终态的弧。 */
+    rejected: string[];
+    /** 推不动**且抛了异常**的弧(逐弧兜住 —— 一条坏行不许绑架其它弧的恢复)。 */
+    failed: string[];
+    /** 扫描本身失败(库不可达等)。**不吞** —— 消息进启动日志。 */
+    error?: string;
+}
+/**
+ * boot 期的在飞收编扫描。无 SQL 后端 ⇒ 零动作(收编面在那种部署上本来就 501)。
+ * 绝不抛:一次库抖动不该拒掉整台 worker 的启动,但**必须**留下响亮读数(`error` 位 + error 级日志)。
+ */
+export declare function runAdoptionBootScan(ctx: AdoptionBootCtx): Promise<AdoptionBootReading>;
+//# sourceMappingURL=adoption.d.ts.map