@sema-agent/server 7.10.0 → 7.12.0

package/dist/adoption/plan.js

@@ -0,0 +1,513 @@
+/**
+ * design/183 §4.3 —— **form b 收编的迁移计划表**(server 半场细设计;183 §1 明写「表级细设计归 server」)。
+ *
+ * 这张表是本车的**单一真源**:phase 0 的目的地冲突 preflight、phase 3 的行迁/桶迁、回执里的 `legs`
+ * 三者全部由它派生 —— 三处各抄一份表正是「preflight 说没冲突、迁移腿却撞 UNIQUE」这类分家的温床。
+ *
+ * ── 判定轴(183 §4.1 身份轴三形,落到本仓真 schema)────────────────────────────────────────────────
+ *  · **形Ⅰ 行迁**(`row-rewrite`):数据里有 owner/principal 结构位,且该位**不在任何唯一键里**
+ *    ⇒ 一条 `UPDATE … SET col = :to WHERE col = :from` 即可,重跑改到同值 = 零行变化(幂等),
+ *    且**不可能撞唯一键**(`residualKey: undefined` 就是这句话的机器形)。
+ *  · **形Ⅱ 桶迁**(`bucket-rebind`):键是 scope,而本部署的 scope 词表把身份编进去(server durable
+ *    scope ≡ principal 的恒等涟漪)。scope 若**在**唯一键里,重绑就可能与目的地已有的同逻辑键撞
+ *    ⇒ `residualKey` 记下「唯一键去掉身份轴之后剩下的列」,preflight 按它查重叠。
+ *  · **形Ⅲ 无身份轴**:键=session/ref/内容寻址(session_event / task_event / task_active /
+ *    checkpoint_ctx / tool_result / snapshot_manifest / snapshot_blob / approval_batch /
+ *    task_list_* / workflow_completion_inbox 的 session_id 那一半 …)⇒ **零改写**:归属随它挂靠的
+ *    资产(会话 / run / 内容)一起走,本表不列它们,也不该列 —— 列了就是给「跟着 session_id 走的行」
+ *    再造一个第二真源。
+ *
+ * ── 一张表两根身份轴的处置(agent_roster / background_agent)────────────────────────────────────
+ * 逐轴各一条腿,各带**自己**的 `residualKey`(= 该表唯一键去掉这根轴)。两条腿在**同一个事务**里
+ * 顺序跑;preflight 是按迁移**前**的库态逐轴算的,理论上仍存在一个跨轴的组合形撞唯一键
+ * (A 行只动 owner、B 行只动 scope 后同键)—— 那一形由 phase 3 事务里的唯一键违例**响亮拒 + 整体
+ * 回滚**兜住(两侧字节零变更),而不是靠 preflight 声称自己算全了。fail-closed,不 fail-open。
+ *
+ * ── 为什么腿的集合比小票逐字点名的多(**如实登记,候属主裁**)────────────────────────────────────
+ * 小票 §行迁/桶迁 点名的是 `session_meta.owner` / `session_policy` / checkpoint / mailbox / workflow /
+ * background-agent / snapshot / memory。本表在此之外还迁了 `task_run.owner`、`resume_anchor.owner`、
+ * `sendfile_link.scope`、`task_attachment.owner`、`approval_ask.owner`、`agent_roster` 两轴、
+ * `workflow_completion_inbox.owner` / `workflow_inbox_fence.owner` / `workflow_notify_journal.principal`、
+ * `sandbox_image_index.tenant_id`。判据不是「多迁点保险」,是小票自己写的那条**类判据**:
+ * 「形Ⅰ = owner/principal 结构位」「形Ⅱ = scope ≡ principal 分区面」—— 上面每一列都逐字落在这两句里,
+ * 且每一列都是**活的授权/可见性轴**(不是史实字段):`session_meta.owner` 迁了而 `task_run.owner` 没迁,
+ * 结果就是「会话看得见、它的 run 历史读不到」= 183 §6 明令要防的第一病形「owner 变了调用方够不着」。
+ * 反向的「不该迁」一律进 {@link NOT_MIGRATED_BY_DESIGN}(D1/D2 裁决号在案),不进本表。
+ */
+import { formatUserScope, encodeScopeSegment, SCOPE_SEGMENT_MAX_ENCODED } from "@sema-agent/core";
+/**
+ * 全部重绑腿。**次序即执行序**(同一事务内顺序跑):同表两轴相邻,workflow 家族相邻
+ * (183 §4.3「run + journal 同事务」在本车是「**全部腿同一个事务**」的更强形)。
+ */
+export const REBIND_LEGS = [
+    // ── 形Ⅰ:owner/principal 结构位,不在任何唯一键里 ⇒ 结构性无冲突 ────────────────────────────
+    {
+        leg: "session_meta#owner",
+        table: "session_meta",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(session_id) 不含 owner
+        why: "会话归属主列(183 §4.3 形Ⅰ 首项;存量 `anon:shell-live` 哨兵行同走此腿——它只是一个 principal 字面量,不需要 ad hoc 分支)",
+    },
+    {
+        leg: "task_run#owner",
+        table: "task_run",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(task_id)
+        why: "run 列表/属主门的过滤列(GET /v1/runs 与 trace 属主门读它)——不迁 = 会话迁了它的 run 历史读不到",
+    },
+    {
+        leg: "resume_anchor#owner",
+        table: "resume_anchor",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(session_id, event_id)
+        why: "E18 anchor 的单库舰队纵深防御列(与 session 同生命周期)",
+    },
+    {
+        leg: "sendfile_link#scope",
+        table: "sendfile_link",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(id)
+        why: "SendUserFile 台账的租户列(DDL 行内注:scope = VERIFIED principal verbatim)= 逐租户 list/revoke 句柄",
+    },
+    {
+        leg: "task_attachment#owner",
+        table: "task_attachment",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(id)
+        why: "D-1 附件面的属主列(auth principal ?? default)",
+    },
+    {
+        leg: "approval_ask#owner",
+        table: "approval_ask",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(ask_id);UNIQUE(task_id, idempotency_key) 不含 owner
+        why: "#151 流内审批 ask 行的租户列(读面按它过滤)。**decision_actor / decision_note 不动** —— 那是史实(D2)",
+    },
+    {
+        leg: "sandbox_image_index#tenant_id",
+        table: "sandbox_image_index",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["tenant_id"],
+        matchColumn: "tenant_id",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(id);UNIQUE(repo, digest) 不含 tenant_id
+        why: "镜像可见性的租户列(tenant-scoped 镜像只对该 principal 可见)—— 活的可见性轴,不是史实",
+    },
+    {
+        leg: "workflow_completion_inbox#owner",
+        table: "workflow_completion_inbox",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(session_id, run_id)
+        why: "workflow 完成收件箱的属主列(投递门读它)",
+    },
+    {
+        leg: "workflow_inbox_fence#owner",
+        table: "workflow_inbox_fence",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(session_id, kind, run_id)
+        why: "收件箱围栏行的属主列(与 inbox 同轴,漏迁 ⇒ 围栏对新身份失效)",
+    },
+    {
+        leg: "workflow_notify_journal#principal",
+        table: "workflow_notify_journal",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["principal"],
+        matchColumn: "principal",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(run_id)
+        why: "notify 日志的投递身份列(未 ack 的通知按它重投)",
+    },
+    {
+        // 🔴 这条腿是**普查门逮出来的**(2026-08-10 建门当天):本表有 `principal` 与 `scope` **两根**身份轴,
+        // 初版只迁了 principal。漏掉 scope 的后果是恢复扫描按 `WHERE scope = <新身份>` 一条都捞不到,
+        // 未 ack 的通知对新身份永久不可见 —— 而 principal 那半迁了,黑盒上看起来「迁过了」。
+        leg: "workflow_notify_journal#scope",
+        table: "workflow_notify_journal",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(run_id) 不含 scope
+        why: "notify 日志的 scope 分区(与 workflow run/journal 同轴同事务;principal 是投递身份、scope 是租户分区,两根轴各迁各的)",
+    },
+    {
+        // 两根轴(scope_key / owner)都可能带旧身份 ⇒ 匹配面必须是它们的**并**,否则只在 owner 上带旧值的行找不到。
+        leg: "background_agent#record_json",
+        table: "background_agent",
+        kind: "blob-rewrite",
+        action: "row-rewrite",
+        columns: ["scope_key"],
+        matchColumn: "scope_key",
+        encoding: "verbatim",
+        residualKey: undefined,
+        blob: { column: "record_json", pk: ["scope_key", "handle"], fields: ["scope", "owner"], alsoMatch: ["owner"], revColumn: "rev", revInPayload: "rev" },
+        why: "store 自注「真源在 record_json,摘要投影截断是诚实形」—— 只迁投影列 = 说了算的那份没迁",
+    },
+    {
+        leg: "background_agent#owner",
+        table: "background_agent",
+        kind: "bulk-rebind",
+        action: "row-rewrite",
+        columns: ["owner"],
+        matchColumn: "owner",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(scope_key, handle) 不含 owner
+        why: "后台代理行的 default-deny 谓词两根轴之一(owner);另一根 scope 见下面的桶迁腿",
+    },
+    {
+        // 🔴 载荷腿排在同表的列腿**之前**:改写要按**旧**身份值找行,列一旦换掉就再也找不到了。
+        leg: "checkpoint#checkpoint_blob",
+        table: "checkpoint",
+        kind: "blob-rewrite",
+        action: "row-rewrite",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined, // 逐行按 PK 回写,不可能撞唯一键
+        blob: { column: "checkpoint", pk: ["token"], fields: ["scope"], revColumn: "rev" },
+        why: "core `Checkpoint.scope`(类型注:Multi-tenant isolation key)住在 blob 里 —— 只迁 `scope` 列会让载荷里的隔离键留在旧身份",
+    },
+    {
+        leg: "checkpoint#scope",
+        table: "checkpoint",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(token) 不含 scope ⇒ 桶迁语义、结构性无冲突
+        why: "durable HITL 检查点的租户分区列(scope = `principal ?? \"_\"`)——不迁 ⇒ 新身份 resume 不了自己的挂起任务",
+    },
+    {
+        leg: "workflow_run#run_blob",
+        table: "workflow_run",
+        kind: "blob-rewrite",
+        action: "row-rewrite",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined,
+        blob: { column: "run", pk: ["id"], fields: ["scope"], revColumn: "rev", revInPayload: "rev" },
+        why: "`WorkflowRunStore.get()` 是 `JSON.parse(run)` 且**只**覆盖 rev —— 不改载荷,`get().scope` 恒旧身份,回传给 scope-guarded 的 update() 就命中不了已迁移的行(活 workflow 挂死)",
+    },
+    {
+        leg: "workflow_run#scope",
+        table: "workflow_run",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(id)
+        why: "workflow run 行的 scope 分区(scope = `principal ?? \"default\"`)。183 §4.2 D4:不变量属 update 动词面,存储层迁移豁免",
+    },
+    {
+        leg: "workflow_journal#scope",
+        table: "workflow_journal",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: undefined, // PK(run_id, ordinal)
+        why: "resume 重放日志的 scope 守卫列 —— 与 run 行**同事务**(错配会让 load 守卫拒掉整条 resume)",
+    },
+    // ── 形Ⅱ:身份轴**在**唯一键里 ⇒ residualKey 非 undefined,preflight 必须逐族查重叠 ──────────
+    {
+        leg: "workflow_resume_claim#scope",
+        table: "workflow_resume_claim",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "verbatim",
+        residualKey: ["source_run_id"], // PK(source_run_id, scope)
+        why: "跨副本 resume 准入租约(与 run/journal 同族同事务)",
+    },
+    {
+        leg: "mailbox#scope",
+        table: "mailbox",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope_key", "scope"],
+        matchColumn: "scope_key",
+        encoding: "verbatim",
+        residualKey: ["handle"], // PK(scope_key, handle)
+        why: "信箱行的 scope 分区。`scope_key`(字节列)与 `scope`(可读列)存的是同一个值,必须一起改",
+    },
+    {
+        leg: "mailbox_message#scope_key",
+        table: "mailbox_message",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope_key"],
+        matchColumn: "scope_key",
+        encoding: "verbatim",
+        residualKey: ["handle", "seq"], // PK(scope_key, handle, seq)
+        why: "未投递通知 = 183 [3265] A 类资产(消息体随信箱同迁;本表无 `scope` 可读列)",
+    },
+    {
+        leg: "background_agent#scope",
+        table: "background_agent",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope_key", "scope"],
+        matchColumn: "scope_key",
+        encoding: "verbatim",
+        residualKey: ["handle"], // PK(scope_key, handle)
+        why: "后台代理行的 scope 分区(default-deny 谓词的第二根轴)",
+    },
+    {
+        leg: "agent_roster#owner",
+        table: "agent_roster",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["owner_key", "owner"],
+        matchColumn: "owner_key",
+        encoding: "verbatim",
+        residualKey: ["name_key", "scope_key"], // PK(name_key, owner_key, scope_key)
+        why: "花名册行的 owner 轴(core 1.365 起 owner/scope 双轴必填 = default-deny 谓词的两根轴)",
+    },
+    {
+        leg: "agent_roster#scope",
+        table: "agent_roster",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope_key", "scope"],
+        matchColumn: "scope_key",
+        encoding: "verbatim",
+        residualKey: ["name_key", "owner_key"], // PK(name_key, owner_key, scope_key)
+        why: "花名册行的 scope 轴(与 owner 轴同表两根轴,逐轴各一条腿——见顶注「一张表两根身份轴」段)",
+    },
+    // ── 形Ⅱ(memory 族):scope 是 core 的 v2 typed 键,身份在**段**里 ⇒ 值对由 DISTINCT 扫描解出 ──
+    {
+        leg: "agent_memory_engine_entry#scope",
+        table: "agent_memory_engine_entry",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "memory-scope",
+        residualKey: ["slug"], // UNIQUE(scope, slug)
+        why: "记忆条目盘(user:/proj:/userproj: 三形键的 tenant 段 = principal)",
+    },
+    {
+        leg: "agent_memory_engine_cursor#scope",
+        table: "agent_memory_engine_cursor",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "memory-scope",
+        residualKey: [], // PK(scope) —— 唯一键**就是**身份轴:两侧各有一行即冲突
+        why: "记忆盘游标(每 scope 一行)",
+    },
+    {
+        leg: "agent_memory_engine_sync_cursor#scope",
+        table: "agent_memory_engine_sync_cursor",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "memory-scope",
+        residualKey: ["peer"], // PK(scope, peer)
+        why: "记忆同步的 per-peer 游标",
+    },
+    {
+        leg: "agent_memory_engine_push_queue#scope",
+        table: "agent_memory_engine_push_queue",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "memory-scope",
+        residualKey: undefined, // PK(id)
+        why: "记忆推送队列(未推完的条目随盘走)",
+    },
+    {
+        leg: "agent_memory_engine_history#scope",
+        table: "agent_memory_engine_history",
+        kind: "bulk-rebind",
+        action: "bucket-rebind",
+        columns: ["scope"],
+        matchColumn: "scope",
+        encoding: "memory-scope",
+        residualKey: undefined, // PK(id, rev)
+        why: "记忆修订史的 scope 列(随盘走;`op`/`snapshot` 是内容不是身份)",
+    },
+    // ── 唯一一条要逐行重算主键的腿 ────────────────────────────────────────────────────────────────
+    {
+        leg: "session_policy#principal",
+        table: "session_policy",
+        kind: "session-policy-rekey",
+        action: "row-rewrite",
+        columns: ["principal"], // policy_key 由 (session_id, principal) 重算,不是等值搬运
+        matchColumn: "principal",
+        encoding: "verbatim",
+        residualKey: ["session_id"], // policy_key = sha256([session_id, principal]) ⇒ 同 session 的目的地行即冲突
+        why: "E6 逐会话逐 principal 的工具收紧规则:身份在**主键的 hash 原像**里,等值 UPDATE 够不着 ⇒ 逐行读出→重算 policy_key→改写",
+    },
+];
+/**
+ * server 侧**按设计不迁**的面(183 §12 裁决号在案)。这份清单进回执的 `notMigratedByDesign`,
+ * 让「按设计不迁」与「漏了没迁」在黑盒上可分(183 §10.5)。
+ *
+ * 🔴 D1 三员为什么同族:它们全是**按对齐窗口分桶的治理瞬态计数**(usage_window / cost_quota /
+ * rate_limit),窗口语义与身份绑在一起搬过去要跨窗口对齐,复杂度与价值不成比例;清零重计的代价是
+ * 新身份在当前窗口拿到一份新额度 —— 一次性部署级动作里这是可接受的,而且**方向偏松不偏紧**,
+ * 不会把人锁在门外。
+ * 🔴 D2 三员为什么不改:它们是**谁在什么时候做了什么**的史实字段。改写史实 = 伪造审计。
+ */
+/**
+ * 🔴 本数组的成员集合必须与 {@link NOT_MIGRATED_FACES}(冻结词表)**全等** —— 词表说有而这里没有
+ * 就是一条下游按名写了断言、回执里却永远不出现的幽灵成员。等式由 `test/adoption-arc.test.ts` 钉住。
+ * (建表时真发生过:`outcome-ledger` 一度只进了词表 —— 它压根没有身份轴,属于「无可迁」而不是
+ * 「按设计不迁」,两者混在一起会让 D2 的语义从「史实不改写」滑成「凡是没迁的都算设计」。)
+ */
+export const NOT_MIGRATED_BY_DESIGN = [
+    { face: "usage-window", ruling: "D1", reason: "deployment token-governance window (usage_window): a windowed governance transient — not carried, recounted from zero" },
+    { face: "cost-quota", ruling: "D1", reason: "per-window cumulative spend counter (cost_quota.scope_key) — same windowed-transient class as usage-window" },
+    { face: "rate-limit", ruling: "D1", reason: "per-window request counter (rate_limit.limit_key) — same windowed-transient class as usage-window" },
+    { face: "approval-exemption-grantor", ruling: "D2", reason: "approval_exemption.granted_by is a historical fact (who granted this exemption), not a live authorization axis" },
+    { face: "approval-ask-decision-actor", ruling: "D2", reason: "approval_ask.decision_actor / decision_note record who decided — historical audit fields, never rewritten" },
+    { face: "image-bake-requested-by", ruling: "D2", reason: "image_bake.requested_by records who requested the build — historical audit field" },
+];
+export const AFFECTED_CONFIG_TEMPLATES = [
+    { deployment: "web-client-bff", key: "BFF injected principal (bff/server.mjs)", requiredValue: "%TO%" },
+    { deployment: "cli", key: "~/.sema/cloud/credentials + cloud/profiles.json", requiredValue: "%TO%" },
+    { deployment: "cli", key: "SEMA_LIVE_PRINCIPAL", requiredValue: "%TO%" },
+    { deployment: "env", key: "REQUIRE_PRINCIPAL", requiredValue: "true (multi-tenant posture must stay on)" },
+    { deployment: "core-decl", key: "localOwnerRules", requiredValue: "(withdraw — the declaration resolves to the adopted principal after adoption)" },
+];
+/**
+ * 目的地身份值的**列宽约束**(codex 对抗复审 R1-F3,亲核属实)。
+ *
+ * 🔴 病:请求面收 ≤190 字符的 principal,而迁移腿要把它写进**最窄**只有 `VARCHAR(64)` 的列
+ * (`sandbox_image_index.tenant_id`),两根键列还是 `VARBINARY(190)`(**字节**,不是字符),memory scope
+ * 更是在 principal 外面再套前缀 + 百分号编码(非 ASCII 膨胀约 9 倍)。于是一个**合法**请求可以跑到腿的
+ * 中途才被库以截断/超宽打回 —— 那时 phase 停在 INTENT,每次重发与每次 boot 扫描都会再撞一次同样的墙。
+ *
+ * 🔴 姿势:在**铸行之前**按最窄真列校验并 typed 拒(fail-closed)。**不**在这里加自动截断——截断身份
+ * 就是把 A 的数据交给 B。
+ *
+ * 另一条可选解是把 `tenant_id` 拓宽到与其它身份列同宽(183/codex 的「统一身份契约」建议)。本车不动
+ * 别的特性的 schema:那是一次跨车道的列变更,该由镜像面属主拍。此处如实登记这条不对称。
+ */
+export const IDENTITY_WIDTH_LIMITS = [
+    { what: "sandbox_image_index.tenant_id VARCHAR(64)", unit: "chars", max: 64 },
+    { what: "owner/principal/scope columns VARCHAR(190)", unit: "chars", max: 190 },
+    { what: "mailbox/background_agent/agent_roster key columns VARBINARY(190) (MySQL: bytes, not characters)", unit: "bytes", max: 190 },
+];
+/**
+ * core 的段编码器对超长/不可编码的段是**抛错**而不是返回。这里把那个异常**转成调用方的拒绝理由**
+ * (错误本身被带出去,不是吞掉换个默认值)—— 拒绝理由要能指着具体是哪一侧、为什么装不下。
+ */
+function scopeSegmentRejection(label, principal) {
+    let encoded;
+    try {
+        encoded = encodeScopeSegment(principal);
+    }
+    catch (err) {
+        return `${label} cannot be encoded as a core memory scope segment: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    return encoded.length > SCOPE_SEGMENT_MAX_ENCODED
+        ? `${label} does not fit core's memory scope-segment limit (${SCOPE_SEGMENT_MAX_ENCODED} encoded characters; percent-encoding expands non-ASCII ~9x)`
+        : undefined;
+}
+/** memory scope 列宽(两方言 VARCHAR(190) 同宽;段编码后才是真长度)。 */
+export const MEMORY_SCOPE_MAX_CHARS = 190;
+/**
+ * 目的地身份能不能被每一根被写列容纳?返回**人可读的拒绝理由**,`undefined` = 可以。
+ * 纯函数(零 I/O),所以校验发生在任何库动作之前。
+ */
+export function checkAdoptionWidths(fromPrincipal, toPrincipal) {
+    // 🔴 判据的**次序**有讲究(不是随手排):先查「写进列装不装得下」,再查「core 的段编码上限」。
+    // 反过来排的话,段上限(64 个**编码后**字符)对任何带 `:` 的 principal 都比 `tenant_id VARCHAR(64)`
+    // 更早触发 ⇒ 列宽那条臂**永远走不到**(一条摆着好看的死支;本仓有过「变异打在不可达死支上」的判例)。
+    const bytes = Buffer.byteLength(toPrincipal, "utf8");
+    for (const limit of IDENTITY_WIDTH_LIMITS) {
+        const got = limit.unit === "bytes" ? bytes : toPrincipal.length;
+        if (got > limit.max)
+            return `toPrincipal is ${got} ${limit.unit}, but ${limit.what} caps it at ${limit.max}`;
+    }
+    // **两侧都要查**(本车自测逮到,与 codex R3-F3 同族):`from` 不写进任何列,但它要经
+    // `encodeScopeSegment` 铸出 memory 扫描的前缀,而 core 对**段**的上限是 64 个编码后字符且是**抛错**。
+    // 只查 `to` 的话,一个超长的源身份会让弧在 phase 0 的扫描里抛一个未分类异常:意图行已经落库、
+    // phase 停在 INTENT,此后每次重发与每次 boot 续跑都确定性地再抛一次 —— 一条永远跑不完的弧。
+    for (const [label, p] of [["fromPrincipal", fromPrincipal], ["toPrincipal", toPrincipal]]) {
+        const rejection = scopeSegmentRejection(label, p);
+        if (rejection !== undefined)
+            return rejection;
+    }
+    // 派生的 memory scope 键(前缀 + 段编码)也要能装下 —— 非 ASCII 在这里膨胀最猛。
+    const derived = formatUserScope(toPrincipal);
+    if (derived.length > MEMORY_SCOPE_MAX_CHARS) {
+        return `the derived memory scope key for toPrincipal is ${derived.length} characters (percent-encoding expands non-ASCII ~9x), but the scope column caps it at ${MEMORY_SCOPE_MAX_CHARS}`;
+    }
+    return undefined;
+}
+/** `proj:` / `userproj:` 键的 tenant 段前缀(值对由 DISTINCT 扫描按前缀解出)。 */
+export const MEMORY_PROJECT_SCOPE_PREFIXES = ["proj:", "userproj:"];
+/** `verbatim` 轴的值对(纯数据,零 I/O)。 */
+export function buildVerbatimPair(fromPrincipal, toPrincipal) {
+    return { from: fromPrincipal, to: toPrincipal };
+}
+/**
+ * memory scope 键的重写(纯函数,给扫描出来的每个 scope 值算新值)。
+ *  · `user:<enc(from)>` ⇒ `user:<enc(to)>`(逐字等值);
+ *  · `proj:<enc(from)>/…` / `userproj:<enc(from)>/…` ⇒ 只换 tenant 段,项目段原样;
+ *  · 其它(`org:` 组织盘、无前缀的旧不透明键)⇒ `undefined` = **不属这个 principal,不动**。
+ *
+ * 🔴 为什么不用 `LIKE '<prefix>%'`:段是**百分号编码**的(`user%3Aweb-demo`),`%` 在 LIKE 里是通配符,
+ * 不逐字符转义就会误命中一大片。用「DISTINCT 扫 + 纯函数判前缀」把这道坑整个绕开:判定在 JS 里做,
+ * 落到 SQL 的永远只有**等值**谓词。
+ */
+export function rewriteMemoryScope(scope, fromPrincipal, toPrincipal) {
+    const fromUser = formatUserScope(fromPrincipal);
+    if (scope === fromUser)
+        return formatUserScope(toPrincipal);
+    const fromSeg = encodeScopeSegment(fromPrincipal);
+    const toSeg = encodeScopeSegment(toPrincipal);
+    for (const prefix of MEMORY_PROJECT_SCOPE_PREFIXES) {
+        const head = `${prefix}${fromSeg}/`;
+        if (scope.startsWith(head))
+            return `${prefix}${toSeg}/${scope.slice(head.length)}`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=plan.js.map

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