chore(docs): MIGRATION.md 版本账本脱节——v0.6.0/v0.6.1 已打 tag 发布，全部 break 仍压在「Unreleased（0.5.x）」下，无 0.6 段

Start with the heading lines in MIGRATION.md (line 9 ## Unreleased（0.5.x）, the ### entries from 9 to 324) and compare them with git show v0.6.0:MIGRATION.md. Move the 11 entries that already existed at the v0.6.0 tag into a new ## 0.6.0 section, and keep only the 5 post-0.6.1 entries under Unreleased. Also fix the version promise at plaita/errors.py:40, the matching line at MIGRATION.md:381, and the heading at docs-site/docs/reference/migration-guide.md:3. Done means the ledger headings match the tags and a check such as tests/unit/test_migration_ledger.py passes.

优先级 P2 · 依赖：无

基线 HEAD = 65f48f2

Summary

MIGRATION.md 是升级者的权威迁移契约（MIGRATION.md:3：「本文件列出 plaita 历次版本中破坏向后兼容的改动……如果你升级后遇到行为变化，先来这里查。」），但其版本账本停在 0.5.x：v0.6.0 / v0.6.1 已打 tag 发布，文档里没有任何 0.6 段，全部 break 仍压在标题写着「Unreleased（0.5.x）」的段落下。

1. 发布版本号（源码声明）

$ grep -n 'version = ' pyproject.toml
7:version = "0.6.1"

$ sed -n '1p' plaita/__init__.py
__version__ = "0.6.1"

2. v0.6.0 / v0.6.1 确已打 tag 发布（非仅 pyproject 声明）

$ git tag
v0.5.0
v0.6.0
v0.6.1

$ git log -1 --format='%ci' v0.6.0
2026-10-02 16:45:30 +0800
$ git log -1 --format='%ci' v0.6.1
2026-10-03 09:23:36 +0800

3. MIGRATION.md 无 0.6 段（反证命令 + 完整输出）

$ grep -n '^## ' MIGRATION.md
9:## Unreleased（0.5.x）
325:## 0.5.0
514:## 0.4.0
665:## 升级检查清单

^## 只有 4 条命中，第一条就是 ## Unreleased（0.5.x），不存在 ## 0.6.0 / ## 0.6.1，也没有 ## 0.6.x。

4. 关键：打 tag 当时账本就已经是错的（说明不是「发布后忘记补」，而是发布动作从不碰这个账本）

$ git show v0.6.0:pyproject.toml | grep -n '^version'
7:version = "0.6.0"
$ git show v0.6.0:MIGRATION.md | grep -n '^## '
9:## Unreleased（0.5.x）
215:## 0.5.0
404:## 0.4.0
555:## 升级检查清单

$ git show v0.6.1:pyproject.toml | grep -n '^version'
7:version = "0.6.1"
$ git show v0.6.1:MIGRATION.md | grep -n '^## '
9:## Unreleased（0.5.x）
215:## 0.5.0
404:## 0.4.0
555:## 升级检查清单

v0.6.0 与 v0.6.1 两次发布，MIGRATION.md 的版本段标题与内容逐字节相同（git diff --stat v0.6.0..v0.6.1 -- MIGRATION.md → 空输出），首位版本段始终是 ## Unreleased（0.5.x）。

5. 段落内容自述其归属版本，却仍在 Unreleased 下

$ sed -n '112p' MIGRATION.md
### 编排内核行为收紧（2026-09 评审修复轮，建议以 0.6.0 发布）

该条目明文写着「建议以 0.6.0 发布」，而 0.6.0 已经发布——它却仍是 ## Unreleased（0.5.x） 段内的三级标题。当前 Unreleased 段下共 16 个 ### 三级标题：

$ sed -n '9,324p' MIGRATION.md | grep -c '^### '
16

其中 11 个在 v0.6.0 tag 时就已存在（即已随 v0.6.0/v0.6.1 出货），含 ### Storage：\db` 执行/流程存储从公开路径下架、### 任务队列：Redis List → Stream（at-least-once）、### Resume：execution lease（防并发）、### Experimental：`db` / SQLAlchemy 需显式门闩` 等：

$ git show v0.6.0:MIGRATION.md | sed -n '9,214p' | grep -n '^### '
3:### 安全与分布式加固（2026-09 R4 定向深潜轮）
32:### 编排内核行为收紧（2026-09 评审修复轮，建议以 0.6.0 发布）
89:### Storage：`db` 执行/流程存储从公开路径下架
116:### Event：`HAS_SQLALCHEMY` 与 `__all__` 条件修复
121:### 任务队列：Redis List → Stream（at-least-once）
143:### 中间态落盘：每步持久化
148:### Resume：execution lease（防并发）
161:### Experimental：`db` / SQLAlchemy 需显式门闩
167:### 任务队列：DLQ + max deliveries
177:### 文档：Distributed / FlowWorker 可靠性表述收紧（非 API break）
187:### 升级时存量状态处理（Redis / SQLite 里已有的东西怎么办）

而 v0.6.1 之后新增的 5 个条目（writefile jail、#29 js 沙箱、#22 code 白名单、sqlalchemy DDL 迁移、redis execution index ZSET）才是真正未发布的：

$ git diff -U0 v0.6.1..HEAD -- MIGRATION.md | grep '^+' | grep '^+### '
+### writefile 写入 jail 默认开启（2026-10）
+### js 语言接入沙箱档位体系 + 语言白名单默认只放行 python（plaita#29）
+### code 沙箱后端白名单在生产入口默认开启（plaita#22）
+### Storage（experimental sqlalchemy）：DDL 迁移由手工 `ALTER TABLE` 改为版本化脚本
+### Storage：redis 执行列表新增 `{ns}:execution:index` ZSET

即同一段里混着已发布与未发布两种条目，读者无法从分段判断某条 break 属于哪个版本。

6. 版本承诺已过期，代码里的话与账本互相矛盾

$ sed -n '40p' plaita/errors.py
            f"removed in plaita 0.6.0. Use 'plaita.core.errors' instead.",

该 shim 在 0.6.1 上仍然存活（实测）：

$ /tmp/plaita-audit-venv/bin/python -c "
import warnings, plaita, plaita.errors as m
print('plaita.__version__ =', plaita.__version__)
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter('always')
    print('shim resolves ->', m.FlowResultError.__name__)
    print('warning ->', str(w[0].message))
"
plaita.__version__ = 0.6.1
shim resolves -> FlowResultError
warning -> Importing 'FlowResultError' from 'plaita.errors' is deprecated and will be removed in plaita 0.6.0. Use 'plaita.core.errors' instead.

MIGRATION.md:381 的同一承诺也留在已发布版本里：

$ sed -n '381p' MIGRATION.md
**变更前**：`from plaita.flow import Flow, FlowExecution, ...` 可用（带 `DeprecationWarning`，原计划 0.6.0 删）。

7. 文档站同步页同样停在 0.5.0

$ sed -n '3p;5p' docs-site/docs/reference/migration-guide.md
本页帮你从旧版扁平 API 迁到当前分层架构，并标出 **0.5.0 已落地的 break**。详细旧→新对照见 [节点系统 - 弃用迁移](../nodes/migration.md)；破坏性变更全文见仓库根目录 [`MIGRATION.md`](https://github.com/jeffkit/plaita/blob/main/MIGRATION.md)。
## 0.5.0 必看（已 break）

8. 无任何门禁会发现这种漂移（反证命令 + 完整输出）

$ grep -rn -i 'MIGRATION.md' scripts/ .github/ Makefile
.github/workflows/ci.yml:76:      # BLE001 历史位点多，按 MIGRATION.md 约定仅 warn、逐步清理；

唯一命中是 CI 里一行提到 BLE001 约定的注释，没有任何步骤校验 MIGRATION.md 的分段与 pyproject.toml 的 version / git tag 是否一致。docs/DOC_CODE_MAP.md:24 只把 MIGRATION.md 映射到 plaita/**、plaita-ai/**，即改代码时要看它，反过来改版本时没有任何触发条件提醒改它。

影响

• 升级者（0.5.x → 0.6.1）：按 MIGRATION.md:3 的指引「升级后遇到行为变化，先来这里查」，但翻遍全文找不到 0.6 段，最自然的结论是「0.6.x 没有 break」——而 0.6.0 确实带着 db 执行/流程存储路径下架、Redis List → Stream 队列改造、execution lease、DLQ + max deliveries 等一批需要人工迁移动作的变更。代价是升级时漏做迁移动作，在分布式档表现为存量状态与代码不匹配（例如继续按 List 语义读队列、按旧路径取 db 存储）。
• 反向误判：## Unreleased（0.5.x） 这个标题会让人把这些 break 记在 0.5.x 账上，从而在「我已经是 0.5.0 了，这些应该早就生效」的假设下跳过动作。
• 依赖 shim 的代码：plaita/errors.py:40 承诺 0.6.0 删除，实际 0.6.1 仍在且只发 DeprecationWarning。读到该承诺的人会认为 0.6.x 上 plaita.errors 已不可用而提前改造，或反之以为删除已被推迟而继续依赖，在下一个真删除的版本上炸。
• 这是纯文档账本问题，无运行期数据损坏、无越权，但升级路径无法从权威文档判定；不修的后果是每发一个版本，账本与现实的偏差再叠一层。

建议

1. 把 ## Unreleased（0.5.x） 拆成「已发布」与「未发布」两段（具体到行）：
   • 新建 ## 0.6.0 段，把 MIGRATION.md:9-324 中在 v0.6.0 tag 时就已存在的 11 个 ### 条目整体移入（含 :112「建议以 0.6.0 发布」那条，并去掉其「建议以 0.6.0 发布」的待定措辞、### Storage：\db` 执行/流程存储从公开路径下架、### 任务队列：Redis List → Stream` 等）。
   • 保留一个 ## Unreleased 段，只装 v0.6.1 之后新增的 5 个条目（writefile jail / #29 / #22 / sqlalchemy DDL / redis execution index ZSET）；标题里的 （0.5.x） 必须去掉或改为真实的下一版目标版本号。
2. 订正 shim 的版本承诺：plaita/errors.py:40 的 removed in plaita 0.6.0 与 MIGRATION.md:381 的「原计划 0.6.0 删」二选一落地——要么在本轮真删除 shim，要么把承诺版本改成下一个真实目标版本（如 0.7.0）并同步两处文案。
3. 同步文档站：docs-site/docs/reference/migration-guide.md:3 的「标出 0.5.0 已落地的 break」与 :5 的 ## 0.5.0 必看（已 break） 改为覆盖到 0.6.x。

验收条件（可执行、可断言）：

• 新增一个校验脚本（例如 scripts/check-migration-ledger.sh）或单测（例如 tests/unit/test_migration_ledger.py），断言：当 pyproject.toml 的 version 对应 tag v<version> 已存在时，MIGRATION.md 中必须存在 ## <version> 分段。

• 该断言在当前 HEAD 上必须失败，修复后必须通过。一个等价的低成本人工验收是：

  $ git tag --list "v$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
  v0.6.1
  $ grep -n '^## ' MIGRATION.md
  ...   # 期望输出中包含 "## 0.6.1" 或 "## 0.6.0"，且 ## Unreleased 段内不再含已发布的 11 个条目
  

• git show v0.6.0:MIGRATION.md | grep -n '^## ' 在修复后于最新 tag 上重跑，首位版本段不应再是 ## Unreleased（0.5.x）。

最小修法：把 MIGRATION.md:9 由 ## Unreleased（0.5.x） 改为 ## 0.6.1（已发布内容归位），在文件顶部另起一个只含那 5 个未发布条目的 ## Unreleased；同时改掉 plaita/errors.py:40 的过期版本号。

边界

• 本单只处理版本账本与分段归属，不改任何运行期代码逻辑；errors.py 的 shim 是否真的删除属兼容性决策，本单只要求「文案承诺的版本号与账本一致」，不要求必须删。
• 不重写 MIGRATION.md 的 ## 0.5.0（:325）/ ## 0.4.0（:514）/ ## 升级检查清单（:665）三个既有段落，也不重构全文排版。
• 与 docs-site/docs/reference/configuration.md 的 extras 漂移问题是不同文件、不同根因（那是不随 pyproject.toml 同步），本单不合并处理。
• 本单不复述/不重开 #22（code 沙箱白名单）、#29（js 沙箱档位）、#39（writefile jail）等代码侧缺陷——它们的代码修复已完成，本单只负责它们写入 MIGRATION.md 后的版本归属。
• 查重：gh issue list -R jeffkit/plaita --state all --limit 100 返回的 33 单中，无任一条涉及 MIGRATION.md 分段/版本账本或 shim 版本承诺过期，无同根既有单。