docs(rfc): add TypeScript control-plane migration compatibility notes

[now-ing]

Summary

Publish the migration-compatibility notes requested by contributor task GH-C96: a concise review of the TypeScript control-plane migration RFC (typescript-control-plane-migration-v0.md) against merged reality on main, covering the four required surfaces — typed state rules, domain neutrality, behavior-change disclosure, and the public/private boundary — without starting any new migration work.

Key findings:

• Typed state rules: generated decoders (refactor(control-plane): centralize runtime decoders #3443) and immutable bindings are in place; a sweep of the product TypeScript sources confirmed zero as unknown as double casts and one internal clone assertion (JSON.parse(...) as JsonObject in loopx/control_plane/quota/void_commit.ts:259), documented in a named seam inventory with negative decoder coverage and a quota-slice removal owner rather than an external trust-boundary bypass. The no-generic-schema-framework and v0-provenance invariants are restated as ongoing constraints.
• Domain neutrality: every merged cutover keeps providers behind explicit adapters; the transport shell has no second owner; host automation intentionally remains Python.
• Behavior changes: all seven disclosed changes (delivery typed-only fix(control-plane): remove narrative-derived delivery obligations and advance migration RFC #3957, void fail-closed feat(quota): migrate void commit transaction to TypeScript #3832, claim retry semantics refactor(authority): route promoted Todo claims through TypeScript #3945/refactor(todo): unify claim decision in TypeScript #3972, promoted create terminal authority refactor(todo): route promoted create through TypeScript #3973, ...) are collected into one table mapped to RFC sections and merging PRs. No undisclosed behavior change was found.
• Public/private boundary: lifecycle projection constraints, public-safe economics receipts, license tiering references, and the zh mirror (611 lines, structurally complete) are verified intact.

The notes also add a stage ledger: the RFC text carries three mutually unsynchronized time snapshots (§4 prose lists 7 cutovers, the status list 9, §3.1 table fewer), while main already carries sixteen merged Stage 2B transaction families — vision refresh (#3720) and host Todo settlement (#3724) are merged but absent from every RFC list. A gap ledger and a six-item checklist for the next migration slice close the notes.

Issue

Closes contributor task GH-C96 (docs/development/contributor-tasks.md, design / migration column): "Review the TypeScript control-plane migration RFC for compatibility completeness ... then publish concise migration-compatibility notes without starting the migration." The board entry is updated to Claimed: with a link to the notes, following the GH-C70 precedent.

Validation

• python3 examples/docs-governance-smoke.py → docs-governance-smoke ok
• loopx check --scan-path docs/architecture/rfcs/typescript-control-plane-migration-v0.md --scan-path docs/development/contributor-tasks.md → errors=0, warnings=0, checks=6, public boundary scan clean: 2 files
• New document scanned standalone → public boundary scan clean (1 file)
• Manual re-verification of every PR reference cited in the ledger against git log upstream/main (all sixteen Stage 2B families confirmed merged; feat(todo): add provider-first native update #3974 noted as queued, not counted)

Type of change

• Bug fix
• New feature
• Documentation update
• Refactoring
• CI / build improvements

Area

• docs/ (architecture notes + contributor board)
• loopx/ runtime
• apps/presentation/dashboard
• examples/
• other:

Direction & Boundary

Read-only documentation: no runtime behavior, no schema, no CLI surface, and no migration work is introduced. The notes reference RFC sections and merged PRs only; the RFC text itself is left untouched. docs/architecture/README.md gains one index line (placement checklist requires an owning index) and the contributor board row is updated per the GH-C70 claiming precedent.

DCO sign-off is present on all commits.

[huangruiteng]

评审结论：Request changes

评审目标：3976@147079e049d70fab0fb9960924518859efe77f67

动机

GH-C96 要求在不启动新迁移工作的前提下，对 TypeScript control-plane migration RFC 做一次兼容性完整性复核，覆盖 typed state、domain neutrality、行为变化披露和 public/private boundary。这个补丁选择新增一份非规范性的 snapshot，而不直接改写 RFC；它试图把 RFC 内不同时间层与 main@bf217e1e 的已合并事实对齐，帮助下一位迁移作者知道哪些 transaction family 已经完成、哪些约束仍然有效。方向合理，也比继续往 RFC 的多个历史段落里叠加状态更容易审计。

改动思路

文档从四个合同面切入：先复核 typed decoder / assertion seam，再检查 provider 是否仍位于显式 adapter 边界，然后集中列出已经披露的行为变化，最后确认公开证据和中英镜像没有越过 public/private boundary。之后它把 Stage 0–4 状态、16 个 Stage 2B transaction family、RFC 三个不同时间快照之间的差距整理为 ledger，并给下一迁移 slice 留下六项 checklist。

这条阅读路径本身是清楚的：读者从 RFC 的长期约束出发，通过 exact main snapshot 验证已交付现实，最后得到下一步约束。失败责任也明确应落在“事实复核”本身——如果 source scan、PR 状态或 merged-family 计数不准确，这份文档就不能作为兼容性审计结论关闭 contributor task，而必须保留差距。

具体改动

本 PR 是纯文档变更，共 3 个文件、+187/-1：

• docs/architecture/typescript-migration-compatibility-notes.md 新增主体，覆盖 typed state、domain neutrality、behavior disclosure、public/private boundary、Stage ledger、gap ledger、next-slice checklist 和引用；
• docs/architecture/README.md 增加 owning index 链接，符合文档放置规则；
• docs/development/contributor-tasks.md 把 GH-C96 从待办描述改成 “Claimed”，并把“zero unvalidated assertion seams”等结论投影到 contributor board。

关键内容讲解

1. “Typed state rules” 段把 decoder-once-at-boundary、禁止泛化 schema framework、保留 v0 provenance 作为后续 slice 的不变量，这是本 notes 最重要的兼容性门槛。
2. “Disclosed behavior changes” 表把 typed-only delivery、void fail-closed、claim replay、promoted create/update 等行为变化映射回 RFC 和合并 PR，降低了读者从多段历史中重建事实的成本。
3. “Stage status ledger / compatibility gap ledger” 明确 RFC 的三个时间层不同步，并列出 16 个 merged Stage 2B family；这比笼统说“迁移仍在进行”更可操作。
4. contributor board 的状态更新是任务关闭投影，因此它必须只复述已被证据证明的结论，不能比 notes 本身更强。

对主干的风险

[P1] “零 assertion seam”的核心审计结论与 exact base 源码不符

文档在第 1 节明确声称：扫描 70 个 loopx/**/*.ts 文件，得到零 as unknown as，并且零 JSON.parse(...) as T assertion；contributor board 随后把它进一步概括为 “zero unvalidated assertion seams”。但在这份文档声明的 exact snapshot main@bf217e1e 上，loopx/control_plane/quota/void_commit.ts:259 仍然存在：

return JSON.parse(JSON.stringify(value)) as JsonObject;

我在 exact head 上重新执行 product-source scan：文件数确实是 70，as unknown as 为零，但上述 JSON.parse(...) as JsonObject 是一个稳定命中。它来自已合并的 #3832，并非本 PR 之后的新变化。这里的输入原本已经是 JsonObject，所以可以讨论它是不是外部 trust-boundary 风险；但无论如何，“零这种语法 assertion”是字面错误的，board 上“零 unvalidated seam”的更强结论也没有被当前证据支持。

最小修复有两种可接受形式：

1. 修正文档和 contributor board：明确记录这一处 internal clone assertion，解释为什么它不属于外部 trust boundary，并把它放入 named seam inventory（含负向覆盖与 removal owner）；或
2. 在独立的运行时代码 PR 中用 typed clone/decoder 消除它，然后让本 notes 基于新的 merged snapshot 重跑扫描。

本 PR 的边界是“不启动迁移”，所以第一种更符合当前任务。还应把可复现的 scan 命令写入 notes 或 validation，避免未来再次用比实际 matcher 更强的自然语言关闭任务。

验证矩阵：docs-governance-smoke.py 通过；两次 loopx check 均 ok=true 且目标文件 public-boundary clean（仅出现与本 PR 无关的全局 state projection warnings）；git diff --check 通过；远端 5 个 checks 全绿。上述 70-file source scan 则稳定复现 1 个与文档结论矛盾的 assertion。其余链接、Stage ledger 结构和纯文档边界没有发现阻塞问题。

我的整体评价

文档结构、范围和维护价值都不错：没有借审计名义启动新迁移，也把分散的 Stage 2B 现实整理成了一个可用的交接面。问题不在方案，而在最核心的“兼容性完整性”证据有一个可直接复现的反例，并且这个错误已经被提升到 contributor board 的任务状态中。请先把这处 assertion 如实纳入 notes/ledger，再基于新 exact head 复审；修正后我倾向批准。

English verdict: REQUEST CHANGES on exact head 147079e049d70fab0fb9960924518859efe77f67. The compatibility note is well structured and all docs/CI checks pass, but its central claim of zero JSON.parse(...) as T assertions is false at the declared main@bf217e1e snapshot: loopx/control_plane/quota/void_commit.ts:259 still casts a JSON round-trip to JsonObject. Record and classify that seam (and correct the contributor-board claim), or remove it in a separately merged runtime change, then rerun the documented scan.

[now-ing]

Thanks for the precise counterexample — the note now records the seam truthfully at fce752d8, taking your first sanctioned path (record and classify, no runtime change).

The "zero JSON.parse(...) as T" claim is corrected to the actual scan result: zero as unknown as casts and one assertion, exactly the one you found — loopx/control_plane/quota/void_commit.ts:259, the internal cloneObject helper from #3832 that round-trips an already-validated JsonObject through JSON.parse(JSON.stringify(value)) for a deep copy. The notes now classify it explicitly as an internal clone rather than an external trust boundary (the input has already passed the module's decoders), and enter it into a named seam inventory with negative-coverage notes and a removal owner (the quota/void-commit migration slice, replacing the cast with a typed clone or generator-emitted copy helper).

Two supporting changes so the claim can never drift again:

• the reproducible scan commands (fd -e ts . loopx -x rg -n ... for both patterns) are embedded in the notes next to the claim — re-running them on the declared snapshot yields 0 and exactly that one hit, which I verified before pushing;
• the contributor-board summary was weakened from "zero unvalidated assertion seams" to "zero as unknown as casts and a one-entry named seam inventory for the internal clone assertion", so the board no longer states anything stronger than the notes' evidence.

Validation: docs-governance-smoke.py ok; loopx check on both files → errors=0, warnings=0, public boundary scan clean; git diff --check clean.

[huangruiteng]

评审结论：APPROVE

Exact head: fce752d8939eaced6fec1f46dd0b14efab735e79；声明/复核基线：bf217e1e01bec79f357c9ecbd580cf2dfa73db8b。

没有剩余阻断性文档问题。上一轮“零 JSON.parse assertion”的反例已在文档及 contributor board 如实修正。一个非阻断建议：PR description 仍保留 zero assertion 的旧说法，请同步成当前的一处 internal clone seam，避免 PR 摘要与最终 diff 相互矛盾；不要把修正文档描述成消除了 runtime cast。

动机

GH-C96 要求只做迁移兼容性复核，不启动新的迁移。RFC 的 checkpoint、Stage 2B status 和早期 baseline 表处于不同时间层，贡献者需要一个可追溯的固定快照。本 PR 用非规范性 notes 汇总四个合同面、16 个 family 和剩余缺口，而不是把历史总结变成新的控制面 authority。

改动思路

阅读链是 architecture index → 带 immutable baseline 的 notes → RFC/已合并历史 → 下一 slice 的兼容性检查项。notes 不替代 RFC，不修改运行时规则；contributor board 只投影已完成的 review 输出。新的修正将语法扫描与安全判断分开：存在一次断言，不等于它位于外部输入 trust boundary。

具体改动

完整重审三个文件，+209/-1，全部 docs：architecture README 增加 owning index 链接；207 行 notes 包含 typed state、domain neutrality、行为披露、public/private、stage/gap ledger、下一 slice checklist 和引用；contributor board 更新 GH-C96 状态及准确的 seam 结论。没有新增生产代码、测试 scaffolding、CLI/schema 或自动加载的 agent 指令。

关键内容复核：

1. Typed-state inventory：实际扫描 pinned product source 共 70 个 TS 文件；as unknown as 零处，JSON.parse(...) as 一处，正是 quota/void_commit.ts:259 的 cloneObject。当前 notes 记录其已解码 JsonObject 的内部 clone 语义、负向 decoder 覆盖和 quota migration removal owner，并提供重跑命令。旧 blocker 已消除，而不是被改名隐藏。
2. 行为与 stage ledger：重新核对 Turn/quota/Todo/lease/host/vision 交易归属、相关 Git 历史和 RFC 的七项 opening list、后续 status 与 checkpoint；#3720/#3724 的合并存在，#3973 是声明快照的 head。#3974 的 in-flight 描述是该快照的历史状态，不是声称今天仍未合并。
3. 性能/公开边界：表中 void +27.81ms/+3.36%、monitor −93.31ms/−9.61% 与该 RFC 的 receipts 一致；5%/未解释25ms 的 owner gate 没被降级成通过。中英文 revision 日期与相关 economics/Stage 段落对应，raw runtime details 仍不得投影。

正向走查：下一位迁移作者可从 index 找到 notes，定位已有 transaction owner，核对 exact snapshot，再按 checklist 做 disclosure/decoder/中英文同步。负向走查：再次出现 assertion 时，文档要求进入 seam inventory、给出负向覆盖和 removal owner，不允许用“零 unvalidated seam”代替实际事实检查。本 PR 没有替未来运行时 PR 发放授权。

对主干的风险

独立验证：examples/docs-governance-smoke.py 通过；对三个 changed docs 的 loopx check 为 ok、errors=0，目标 public-boundary clean（另有与 diff 无关的全局状态 warnings，不作为文档失败）；git diff --check 通过；70-file source scan 与新 inventory 一致。远端已执行 Sign-off、dependency-review、build 通过，deploy skipped。链接目标、clone helper/decoder negatives、声明 baseline 的 merged history 和 RFC 对应段落已核对；不是仅凭 PR body 或上轮结果批准。

未复测历史性能数字或声称穷举验证全部 runtime 的“无未披露变化”：这些是 notes 在声明 revision 的审计范围与已有 receipt 引用，本次批准是文档准确性/范围判断，不是当前运行时的兼容性认证。文档-only 的 schema/activation/authority runtime counterfactual 不适用。最大后续风险是历史 snapshot 被当作实时 status，因此保留明确 baseline，不要求为不断移动的 main 反复重写这份 notes。

我的整体评价

Approve，不执行合并。 修正覆盖了原来的实质问题，也没有为了满足 review 启动不属于本任务的 runtime 重构。future-facing pass：seam 的长期清理归到 quota owner，当前保留一个有界 inventory 比新增 typed clone framework 更合适。三文件范围与贡献任务一致；建议顺手同步 PR description 的旧 zero-assertion 句子。

English verdict: APPROVE exact head fce752d8939eaced6fec1f46dd0b14efab735e79. The previous false zero-assertion claim is corrected in the notes and contributor board: the pinned 70-file scan confirms one internal JsonObject clone assertion and zero double casts. Docs governance, boundary and diff checks pass; history/RFC cross-checks support the snapshot. Please update the stale PR-description claim too. This is a docs approval, not a new runtime qualification or merge.

[now-ing]

Thanks for the approval and the catch on the stale PR description.

I have updated the PR description directly via API to align with the final diff at approved head fce752d89:

• Typed state rules: Updated the finding summary to state that product TypeScript sources have zero as unknown as double casts and one internal clone assertion (JSON.parse(...) as JsonObject in loopx/control_plane/quota/void_commit.ts:259), entered into a named seam inventory with negative decoder coverage and a quota-slice removal owner (rather than mischaracterizing docs updates as eliminating the runtime cast or retaining the stale zero assertion claim).
• Exact head preserved: No git commits or history modifications were made, keeping approved exact head fce752d8939eaced6fec1f46dd0b14efab735e79 intact.
• Validation re-check: Re-verified locally on exact head fce752d89 — docs-governance-smoke.py ok, loopx check clean (errors=0, warnings=0 on scanned docs), and quality gates pass.