nas/MoviePilot
1
0
Fork 0
mirror of https://github.com/jxxghp/MoviePilot.git synced 2026-11-09 03:13:11 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
f7fe0c8fe00a1efb2a538c533ef08d00a090bc70
MoviePilot/docs/refactor/refactor-roadmap.md
jxxghp 1a1aa59838 docs(architecture): move refactor documents
2026-09-11 06:20:59 +08:00

619 lines
49 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MoviePilot V3 架构重构路线图
> 战略目标：完成 S0-S3 与 S5 的宿主架构重构和最终收口；S4 按维护者决定取消，
> S3 完成后直接进入 S5，S5 完成即结束本轮战略任务。
>
> 执行分支：`v3`；每个叶子完成后独立验证、提交、推送并确认远端 SHA。
>
> 排除范围：`app/plugins/**` 是插件运行时副本，不参与宿主重构。
>
> 兼容原则：新插件只使用 `app.sdk`；旧插件导入、符号和行为只由统一 Compat/Legacy 层承接。
## 0.1 当前追踪目标：G-ARCH-RESIDUAL（COMPLETE）
原 G-ARCH 的 S0-S3、S5 交付记录和 S4 `CANCELLED` 决定保持不变。基于 2026-08-30
对 exact-head 的复核，另行建立本次追踪目标 `G-ARCH-RESIDUAL`，只收口审计已经明确的残余
语义和治理缺口，不把 S4 的全量质量债务重新作为隐性依赖。
| Leaf | 状态 | 依赖 | 退出条件 |
|---|---|---|---|
| R0 事实基线刷新 | `DELIVERED` | 无 | `87269610e`：exact-head、远端、工作树、CI 和五类残余问题证据冻结；未修改 `app/plugins/**` |
| R1 System API 边界收口 | `DELIVERED` | R0 | `d50177f45`：日志、Wiki、配置、事件、更新与重启进入 `application/system.py` 和 `composition/system.py`；endpoint 只保留 HTTP/SSE/ZIP/响应映射 |
| R2 复杂度与原生并发门禁 | `DELIVERED` | R0 | `f7ca7e517`、`5cd5780d3`：完整 AST、Scheduler、canonical alias、TaskGroup、稳定 owner/count 与低水位门禁落地；本范围新增债务为零 |
| R3 Outbox after_commit 恢复语义 | `DELIVERED` | R0 | `9d06f91bb`：下载提交后通知、模块和字幕副作用改为同事务持久 intent，具备 handler、claim/fencing、重启回放、幂等与失败观测 |
| R4 Startup/插件市场单一装配 | `DELIVERED` | R0 | `7f5b8b469` 至 `046b0b305`：市场 Transport/Package/Dependency/Health、Domain、网络、站点、Chain、缓存、资源、DoH 和 Workflow 构造归入 composition；Compat 复用同一 owner |
| R5 验收与交付收口 | `DELIVERED` | R1,R2,R3,R4 | 路线图、优化清单、规则和机器门禁一致；Application/Domain 固定覆盖率基线为 `80.00%` / `80.00%`，Pylint `10.00/10`、架构/兼容门禁、真实启动和最终 exact-head GitHub CI 通过；`HEAD == origin/v3` 且 ahead/behind 为 `0/0` |
执行合同：任一时刻只允许一个 `ACTIVE` 叶子；每个叶子必须独立验证、显式提交和推送，
并在交付前复核插件 ABI、canonical 旧实现/重复导出和 `app/plugins/**` 排除边界。
R5 以 2026-08-30 的精确代码头完成验收：四个 GitHub Unit Tests 分片和 Architecture Contract
Gate 在运行 `33293899659` 中通过，Coverage Report 生成并上传同一份 `coverage.json`；该运行只因
Application 低水位从 `81.61%` 提升到 `81.77%` 后尚未固化而失败。R5 使用相同 locked 命令在
本地重新生成报告并写入整数计数，随后由最终文档/基线提交对应的 exact-head CI 复核。真实进程使用
临时配置目录完成启动，`/health/live` 与 `/health/ready` 均返回 HTTP 200，并完成有序关闭。
## 1. 治理合同
### 1.1 Goal 层级
- **G-ARCH（父目标）**：宿主架构、模块职责、持久化、生命周期、合同和质量债务全部达到本路线图终态。
- **Stage（阶段）**：一组有共同退出条件的能力面，可包含多个独立叶子。
- **Leaf（叶子）**：单一所有权面、可独立实现、验证、提交、推送和回滚的最小交付单元。
原生 Codex Goal 保存 G-ARCH 的稳定目标；本文件保存阶段、叶子、依赖、状态和停止条件。
### 1.2 状态
| 状态 | 含义 |
|---|---|
| `ACTIVE` | 当前唯一允许编辑的叶子 |
| `PLANNED` | 已定义边界，依赖满足后可激活 |
| `BLOCKED` | 有明确阻塞证据，且没有可推进的替代叶子 |
| `VERIFIED` | 本地验收完成，尚未推送或尚未确认远端 |
| `DELIVERED` | 已提交、推送，远端 SHA 与本地交付一致，且本叶要求的远端 CI 已闭环 |
| `COMPLETE` | 叶子验收和后续依赖均已结清 |
| `CANCELLED` | 经维护者明确取消，不进入执行、验收或完成计数 |
任何时刻只允许一个 `ACTIVE` 叶子。子代理可以并行做只读审计、测试设计和下一叶准备；只有当前
叶子的明确文件所有者可以写入源码。共享工作树中发现的并发改动必须先确认归属，不能覆盖。
### 1.3 叶子完成条件
一个叶子只有同时满足以下条件才可标记 `DELIVERED`：
1. 所有定义在该叶子内的债务计数降为零，或变为有业务理由、精确路径、机器约束的非债务例外。
2. 真实调用链已切换到新 owner；不能只增加新类、Port、DTO、门禁或测试而保留主路径走旧实现。
3. canonical 主程序删除被替代的旧实现、兼容分支和重复导出，不保留“新旧两套正式入口”。
4. 插件兼容只落在 `app/sdk`、`app/sdk/_legacy`、`app/runtime/compat` 或经批准的稳定 Facade；
canonical 实现不得为了兼容反向依赖这些层。
5. 受影响专项、架构门禁、strict mypy、Ruff/mypy ratchet、scoped pylint 全部通过。
6. 广泛架构、启动、生命周期、持久化或兼容变更运行锁定全量测试；插件 ABI 变更独立检查官方插件仓。
7. diff、工作树、提交范围经过主线程审查；提交推送后 `HEAD == origin/v3` 且 ahead/behind 为 `0/0`。
不得以以下状态宣称完成：只建立 baseline、只新增抽象未迁移调用方、只留下 TODO、只让新测试通过、
只完成目录移动、只在兼容层外保留旧导出，或用 `--write` 接受新增债务。
## 2. 最终停止条件
G-ARCH 只有在 S3、S5 及以下条件全部满足后才可完成；S4 不属于本轮完成范围：
- [x] `ARCH-001`、`ARCH-101` 至 `ARCH-109`、`ARCH-201` 至 `ARCH-204` 全部完成；`ARCH-110/111` 随 S4 取消且不作为完成依赖。
- [x] 宿主依赖图没有未解释 SCC；只允许精确 containment 的 TMDB 移植包例外，成员不能增长。
- [x] Application/Chain 到具体 Adapter、direct egress，以及本轮迁移资源的并发 owner 例外均精确、可解释、不可增长。
- [x] Chain/Agent 正式数据入口不再注入无 Session Oper，不再以 `Any`/ORM 作为跨层合同。
- [x] 正式业务写入均有单一事务 owner；E2/E3 动作完成语义、幂等、恢复与人工决策路径一致。
- [x] import、普通对象构造不启动进程资源；资源由 bootstrap/lifecycle 显式创建、发布、关闭和重试收口。
- [x] S3、S5 各叶子定义的类型、复杂度、覆盖率和并发债务清零，现有全局 ratchet 不发生回退。
- [x] canonical 主程序无旧实现、重复导出和 legacy import；插件兼容检查基于同步后的官方插件仓 SHA 通过。
- [x] 锁定全量测试、Pylint、依赖一致性和最终远端一致性全部通过；本轮未修改依赖。
## 3. 阶段与叶子
### S0：可信基线与事实源
退出条件：主线门禁全绿；架构规则、总览、机器快照和语义门禁一致；新增债务不能靠更新 fixture 进入。
| Leaf | 状态 | 依赖 | 完成定义 |
|---|---|---|---|
| S0-L1 可信基线恢复 | `DELIVERED` | 无 | `5df388719`：交付架构审计/路线图，修复 `ARCH-001` 两个 mypy 增量错误；远端 `0/0` |
| S0-L2.1 Host Oper/UoW 规范 | `DELIVERED` | S0-L1 | `3bf94ffed`：宿主无 Session Oper 规范债务归零，远端 `0/0` |
| S0-L2.2 完整宿主 SCC policy | `DELIVERED` | S0-L2.1 | `a884ab5c2`：完整宿主 SCC 精确 policy 生效，远端 `0/0` |
| S0-L2.3 Adapter 直连事实 | `DELIVERED` | S0-L2.1 | `e1483e85d`：锁定 28 条原始 Adapter import 事实，远端 `0/0` |
| S0-L2.4 Adapter zero-growth | `DELIVERED` | S0-L2.3 | `2553226f3`：冻结 28 条直连及 owner，收缩/新增/stale policy 门禁生效，远端 `0/0` |
| S0-L2.4b HTTP/Egress 事实与政策 | `DELIVERED` | S0-L2.4 | `47f0de745`、`43d52a35b`、`8d602149f`：冻结 66 条出口事实，消除 CI 类型/覆盖率漂移；远端全绿且 `0/0` |
| S0-L2.5 Event consumer 识别 | `DELIVERED` | S0-L2.1 | `86157be2a`：consumer 只识别可静态证明的 EventManager 注册；全量 6,459 passed / 6 skipped，CI `33029645165`/`33029645254` 全绿，远端 `0/0` |
| S0-L2.6 事实源与 CI 投影 | `DELIVERED` | S0-L2.2,S0-L2.4b,S0-L2.5 | `113355784`：99/17 条逐调用事实、17 条 consumer policy 与 CI 分层交付；Unit Tests `33031697902`、Pylint `33031697785` 全绿，远端 `0/0` |
### S1：可靠性、事务与数据合同
退出条件：Transfer 达到 E3；正式数据 Port 类型化；跨表业务操作有单一 UoW；post-commit/Outbox
竞争、失败呈现、at-least-once 和幂等语义全部闭环。
`S1-L1` 是 ARCH-102 的 Transfer E3 父项，当前状态为 **DELIVERED**。`S1-L1.5` 聚合交付
`S1-L1.1` 至 `S1-L1.4` 的阶段性结果已由最终精确 head 统一交付；真实调用链已完成迁移，旧 fail-open、重复状态和
兼容层外旧入口已退出 canonical 主程序，兼容只经统一 Compat/SDK 门面提供。
| Leaf | 状态 | 依赖 | 完成定义 |
|---|---|---|---|
| S1-L1.1 Durable admission | `DELIVERED` | S0 | Application-owned typed Port + DB adapter + migration 落地；先持久 commit 再入队，入队失败保留可恢复记录；宿主不再通过 raw/`Any` `TransferPendingOper` 处理 admission |
| S1-L1.2 Planning checkpoint | `DELIVERED` | S1-L1.1 | 版本化输入与指纹先持久化；无 legacy provider 时以 `accepted -> planned` CAS 提交完整计划，有 provider 时先提交 `provider_pending`，全部返回空后再以第二次 CAS 提交 `planned`；重放只执行冻结目标，所有文件副作用晚于对应 checkpoint commit |
| S1-L1.3 Lease 与恢复调度 | `DELIVERED` | S1-L1.2 | claim/lease/heartbeat/attempt 与过期接管规则落地；启动回放和同进程恢复共用唯一调度入口，同一任务同时只有一个 worker owner |
| S1-L1.4 幂等执行与终态结算 | `DELIVERED` | S1-L1.3 | 文件操作、历史提交和 checkpoint 可重放；唯一 retry owner 生效，未知外部结果进入 `manual_review`，仅完整终态删除 pending |
| S1-L1.5 E3 全链收口 | `DELIVERED` | S1-L1.4 | `e9de149db`、`a2e249f20`：崩溃矩阵、3.0.17 升降级、重复回放和插件 ABI 验收完整；旧 fail-open、重复状态与兼容层外旧入口删除；Unit Tests `33092427327`、Pylint `33092427348` 全绿，ARCH-102 债务归零 |
| S1-L2 Workflow typed query | `DELIVERED` | S0 | `b4f873654`、`a01a35bcb`：Workflow Application Port 不返回 `Any`/ORM，Session 内投影冻结 DTO，正式调用方全部切换；Unit Tests `33098869736`、Pylint `33098869837` 全绿，覆盖率低水位提升至 Application `78.78%` |
| S1-L3 Chain/Agent typed data ports | `DELIVERED` | S1-L2 | User、History、Site、Subscription 的冻结 DTO/typed Port 已完成；`ChainDataPorts`/`AgentDataPorts` 与 raw Oper/`Any` factory 清零，旧公开 ABI 仅由 Legacy/Compat 承接 |
| S1-L3.1 Workflow typed execution | `DELIVERED` | S1-L2 | `17d8be2af`、`b33b29876`：Chain 直连类型化事务服务且单次执行只取一个 port；canonical Oper 删除旧 writer/无 Session 写方法，旧 ABI 只在 `_legacy/workflow.py` 与 Compat overlay；Unit Tests `33103913838`、Pylint `33103913935` 全绿，Application 覆盖率低水位提升至 `78.79%` |
| S1-L3.2 Chain registry/DI | `DELIVERED` | S1-L3.1 | 显式类型化 context，删除 PortProxy、全局数据 getter 与失效的双重注入，构造器注入真实控制调用 |
| S1-L3.2.1 Registry hygiene | `DELIVERED` | S1-L3.1 | `ac7a20132`：删除零消费者 PortProxy/动态转发和 `ChainRuntimeContext.data_ports` 伪注入；Workflow 退出 Chain registry，只保留 Application owner 单一配置入口；Unit Tests `33120205586`、Pylint `33120205581` 全绿 |
| S1-L3.3 DownloadFailure/MediaServer | `DELIVERED` | S1-L3.2 | `5fb62108a`：两组 raw factory 已替换为冻结 DTO/typed Port；失败冷却在 Session 内投影，媒体库查询只返回标量且每个 upsert/cleanup 独立短事务，远端枚举不持有 Session；旧 Oper 与插件可见 Chain ABI 保持不变；Unit Tests `33127544925`、Pylint `33127544927` 全绿，Application 覆盖率低水位提升至 `78.95%` |
| S1-L3.4 User | `DELIVERED` | S1-L3.3 | User Chain/Agent/认证改用冻结 typed snapshot；创建、更名、删除与最后一个启用超级管理员保护归并到单 UoW；用户名唯一索引及 UserConfig/PassKey 级联迁移落地，UserConfig 在 commit 后持写锁重载数据库事实源并发布内存快照 |
| S1-L3.5 History | `DELIVERED` | S1-L3.4 | DownloadHistory 与 TransferHistory 均已迁入深度冻结 DTO、typed query/write/staging Port 与短 Session adapter；请求级删除和 durable 结算各自保持单一 UoW，canonical 调用方不再接收 raw Oper/ORM，旧写入 ABI 只由 SDK Legacy/Compat 提供 |
| S1-L3.6 Site | `DELIVERED` | S1-L3.5 | Site 配置、用户数据、图标和统计统一为深度冻结 DTO 与 typed query/write/staging Port；请求写入复用 AsyncSession，Chain/Agent 使用独立短事务，canonical 不再接收 raw Oper/ORM，旧插件 ABI 只经 SDK Legacy/Compat |
| S1-L3.7 Subscription | `DELIVERED` | S1-L3.6 | `application/subscription/contract.py` 统一深度冻结 Snapshot/History/Identity/Patch 与 typed query/write/staging Repository；DB adapter 在 Session 内完成 ORM 投影，Chain/API/Agent/Workflow/interaction 不再消费 raw Oper/ORM/`Any`；旧 `SubscribeOper`/`SubscribeHistoryOper` 只经同一 SDK Legacy/Compat 门面保留插件 ABI |
| S1-L3.8 Agent/Transfer locator gate | `DELIVERED` | S1-L3.7 | `chain/data.py`、`agentdata.py` 及其 getter 已删除；Chain/Agent 改用显式 typed context，AST 门禁确认 canonical 无 raw getter/Oper/Any；全量有效 `6955 passed, 9 skipped`，Application 覆盖率提升至 `79.83%`，依赖边降至 `7,062` |
| S1-L4 Subscription mutation UoW | `DELIVERED` | S1-L3.8 | `d9e4a973c`：新增、修改、删除、完成均由显式 Session-bound Command/UoW 拥有事务；Servarr 多季新增在一个请求事务内提交全部订阅和 durable intents，任一季失败整批回滚；canonical 自动提交写入口与 locator 已退出，专项联合测试 327 项通过；当前依赖事实为 7,091 条边，远端 `0/0` |
| S1-L5 站点/规则引用原子清理 | `DELIVERED` | S1-L4 | `d9e4a973c`：站点、规则组及自定义规则改名的 SystemConfig+Subscribe 共享一个 UoW，双事实 CAS 防止过期覆盖，commit 后一次发布配置快照；故障注入、通配重置、并发冲突与事件循环心跳测试通过，远端 `0/0` |
| S1-L6 Outbox 完成语义 | `DELIVERED` | S0 | 事务内 `OutboxStager` 与独立短事务 `OutboxDispatchStore` 已分离；即时投递与 dispatcher 均先 claim，complete/retry 受 attempt fencing；`PostCommitResult` 区分已提交业务、已完成与 pending effect。事件载荷和宿主 correlation context 携带稳定 event key；旧通知插件保持原签名并承认 at-least-once 重复边界 |
### S2：进程生命周期、循环与 Adapter 边界
退出条件：导入/构造零资源副作用；Chain SCC 清零；Application/Chain 只依赖经批准的技术合同，
安全和命名外部能力全部经注入 Port。
| Leaf | 状态 | 依赖 | 完成定义 |
|---|---|---|---|
| S2-L1 日志/消息资源显式生命周期 | `DELIVERED` | S0 | 配置冷导入和非消息 Chain 构造零新增日志/消息线程；lifespan 显式创建共享 owner，启动失败、关闭超时、重试及连续两轮 lifespan 均收口；Chain 轻量客户端不保留首个回调 |
| S2-L2 ChainBase 与 SCC 清零 | `DELIVERED` | S0-L2.2 | canonical `app.chain.base` 已落地，包根无 eager/重复导出，宿主包根导入清零，旧符号只经 `app.sdk.chain` 与 Compat 保持同一类身份；完整宿主 SCC 只剩精确 containment 的 TMDB 移植包 |
| S2-L3 GlobalVar/provider 注册收口 | `DELIVERED` | S2-L1 | 停止、主循环和 WebPush 各有唯一 runtime owner，canonical `global_vars` 消费清零并由 AST 门禁冻结；Workflow、Scheduler、Command、Agent、技能和 LLM provider 均在生命周期显式 configure/reset，冷导入保持未注册；Legacy SDK 门面继续共享同一事实源 |
| S2-L4 Passkey 缓存边界 | `DELIVERED` | S0-L2.4 | `PasskeyChallengeCache` 由 startup 注入，Application 不识别 Redis；严格 `AtomicCacheBackend.store/consume` 由 Memory/Redis backend 分别实现，challenge 仅能被原子领取一次 |
| S2-L5 Backup artifact Port | `DELIVERED` | S0-L2.4 | Application-owned `BackupArtifactStore`/factory 覆盖创建、发布、清理、列举、解析、删除和元数据读取；startup 注入唯一 `BackupFiles` 实现，Application 具体 Adapter 直连由 14 降至 13，完整备份调用链 62 项通过 |
| S2-L6 Application Adapter/DNS 债务清零 | `DELIVERED` | S2-L4,S2-L5 | Application 自有 DNS、图片、消息回环、RSS、站点登录、种子、系统加速 Port，startup 统一注入；13 条具体 Adapter 边及 Application DNS I/O 均归零，未装配和失败回滚语义已验证 |
| S2-L7 Chain Adapter/宿主 HTTP 债务清零 | `DELIVERED` | S2-L6 | Chain 具体 Adapter 与 11 条普通 direct HTTP/Session bridge 均归零；当前 53 条出口事实全部属于精确 SDK/stream/vendor/canonical containment，policy 无 unreviewed、stale 或指纹漂移 |
### S3：大型编排器职责清零
退出条件：每个热点 Facade 只保留稳定公开入口；决策、I/O、状态和生命周期各有单一 owner；
旧实现从 canonical 文件删除，现有复杂度 ratchet 与叶子结构门禁对该所有权面无新增债务。
| Leaf | 状态 | 依赖 | 完成定义 |
|---|---|---|---|
| S3-L1 TransferChain | `DELIVERED` | S1-L1 | 旧 `transfer.py`/`_transfer.py` 单体退役，由 `app.chain.transfer` 同名职责包承接；queue/recovery、plan、execute、settle、history/notify 各有唯一 owner，原 836 行执行方法消失，包根只保留稳定 ABI |
| S3-L2 SubscribeChain | `DELIVERED` | S1-L5 | 旧 `subscribe.py` 单体退役，由 `app.chain.subscribe` 同名职责包承接；search、match、refresh、completion、reference reconciliation、notification 各有唯一 owner，包根只保留稳定 `SubscribeChain` |
| S3-L3 Scheduler | `DELIVERED` | S2-L3 | 旧 `app/scheduler.py` 已退役并迁入 `app.scheduler` 同名包；catalog、execution/bridge/progress、`ExecutionRegistry`、reconciler、lifecycle 与 maintenance 已分离，业务 callable 由 startup 经 `SchedulerServices` 注入，包内无参 Chain 构造清零；功能/生命周期 215 项、架构/兼容/文档 189 项通过，官方插件基线语义未变化 |
| S3-L4 DownloadChain | `DELIVERED` | S1-L6 | `7941fd921`：旧单体退役；selection、submission、batch、history、post-processing 等职责进入同名包单一 owner，提交后动作遵守新完成语义；锁定全量 `7162 passed, 9 skipped`，远端 `0/0` |
| S3-L5 SearchChain | `DELIVERED` | S2-L7 | `1c145d716`：旧单体退役并由同名职责包承接；稳定 ABI、官方插件兼容、类型/复杂度门禁和锁定全量 `7222 passed, 9 skipped` 通过；远端 `0/0` |
| S3-L5.1 Runtime dependencies 命名治理 | `DELIVERED` | S3-L5 | `13fba96fd`：平铺模块退役为 `runtime/dependencies/` 同名包；单词子模块、包根无重复导出、旧快照回滚兼容、命名规则与机器门禁均已交付，锁定全量 `7224 passed, 9 skipped`，远端 `0/0` |
| S3-L6 MediaChain | `DELIVERED` | S2-L2 | `13c4a71f4`：旧单体退役并由同名职责包承接；稳定 ABI、官方插件兼容、缓存并发/别名语义、类型/复杂度门禁和锁定全量 `7244 passed, 9 skipped` 通过；远端 `0/0` |
| S3-L7 Agent/System/Plugin API | `DELIVERED` | S2,S1-L6 | `f38637dce`：WebAgent 会话/file/audio、System nettest 和 Plugin market/rating/release/folders 用例进入 Application；endpoint 只保留传输适配，锁定全量 `7256 passed, 9 skipped`、官方插件基线和远端 `0/0` 通过 |
### S4：可执行合同与质量债务清零
**阶段状态：`CANCELLED`（2026-08-28 维护者决定）**
本阶段不再执行，也不作为 S5 或父目标完成的依赖。S4 原定义保留为取消记录，
不得把 `CANCELLED` 写成 `COMPLETE` 或用 S5 顺带扩张为全宿主质量债务清零。
| Leaf | 状态 | 依赖 | 完成定义 |
|---|---|---|---|
| S4-L1 Module strict contract | `CANCELLED` | — | 原计划取消 |
| S4-L2 Event strict contract | `CANCELLED` | — | 原计划取消 |
| S4-L3 Complexity v2 | `CANCELLED` | — | 原计划取消 |
| S4-L4 全量 mypy 清零 | `CANCELLED` | — | 原计划取消 |
| S4-L5 Ruff 治理债务清零 | `CANCELLED` | — | 原计划取消 |
| S4-L6 Coverage/并发/质量证据 | `CANCELLED` | — | 原计划取消 |
#### S4 Lite：后续增量治理边界（非阶段）
S4 Lite 不是新的 Stage、Leaf 或 Goal，不设置状态、进度或统一完成日期，也不改变 S4
`CANCELLED` 的事实。它只约束后续实际触及相关 owner 时的增量治理，避免取消全量清零后失去
防回退边界：
- Module/Event 合同继续以插件兼容为硬边界。第三方插件的合同校验保持 diagnostic；只有宿主
内置的高风险能力或 durable internal event，才可在独立变更中引入 strict contract
enforcement，并补齐对应行为、生命周期和失败恢复证据。这里的 strict 仅指合同校验策略；
现有 `run_module_strict` / `send_event_strict` 是调用方选择的异常传播接口，仍可触达插件
provider，不属于本条收窄范围。
- 宿主升级不得要求已可用插件先行适配。`run_module` / `async_run_module` 的字符串方法 ABI、
参数兼容、聚合与原始返回形状，以及现有 SDK/Compat/Legacy 行为保持稳定；若增量 strict
治理导致既有插件失效，首先按宿主兼容回归处理，而不是把迁移责任转给插件。
- complexity v2、原生并发、mypy、Ruff 和 coverage 保留现有 zero-growth/低水位 ratchet；
新增或实质修改高风险 owner 时补对应专项证据，但不恢复全宿主历史债务清零目标。
- 每项治理必须在独立变更中说明 owner、风险、兼容影响和退出条件，并通过受影响宿主路径与插件
兼容验证；不得以刷新 baseline、增加文档或只通过静态快照宣称语义完成。
### S5：Plugin、Agent、Domain、Startup 与最终收口
退出条件：剩余 Facade/Manager/Domain/Startup 重复职责清零；官方插件兼容、全量测试和远端交付完成。
| Leaf | 状态 | 依赖 | 完成定义 |
|---|---|---|---|
| S5-L1 PluginHelper/PluginManager | `DELIVERED` | S2,S3 | `fa40f29df`：市场/包/依赖/备份/健康服务各归 owner；Facade 只转发稳定 ABI，构造归 typed PluginRuntime |
| S5-L2 Agent/LLM provider | `DELIVERED` | S3-L7 | `c000c4fff`、`3a33da0b3`、`dbdf7d058` 已在 `origin/v3` 祖先链：catalog、发现、认证、session、runtime 分离；Manager/Facade 只保留稳定 API，最终精确 head CI 已闭环 |
| S5-L3 Domain projection | `DELIVERED` | S3-L6 | `MediaInfo` canonical 路径和 setter ABI 保留；四来源纯投影归入单词 owner，输入不可变、重复业务语义清零 |
| S5-L4 Startup composition | `DELIVERED` | S2,S3,S5-L1,S5-L2 | 领域构造全部归单词型 composition owner；HostRuntime/ApiData 同源；显式逆序 reset manifest 在 worker 收敛后撤销 Provider，失败保留完整诊断边界 |
| S5-L5 Sync/async 重复清零 | `DELIVERED` | S3,S5 | 双 ABI 外壳共享纯逻辑，重复业务实现清零，Session/客户端不跨并发边界复用 |
| S5-L6 最终兼容与交付 | `DELIVERED` | S3,S5-L1,S5-L2,S5-L3,S5-L4,S5-L5 | canonical 旧实现/重复导出清零；官方插件仓、锁定全量、Pylint、架构、类型、覆盖率与远端一致性全部通过，本轮战略任务结束 |
## 4. 叶子合同与交付记录
### S3-L5.1 Runtime dependencies 命名治理
**Status:** `DELIVERED`
**Outcome**
退役平铺且语义相似的 `app/runtime/dependencies.py` 与
`app/runtime/native_dependencies.py`，由同名 `app.runtime.dependencies` 包承接。
`profile.py` 只拥有运行环境依赖分组与同步参数，`native.py` 只拥有已加载原生发行版快照和变更探测；
包根不放实现、不重复导出内部符号，canonical 宿主调用方直接导入职责子模块。
同步把该决策写入 `docs/rules/07-naming-conventions.md`：新增生产模块优先使用准确的单个小写单词；
同一能力需要多个文件时建立同名单词目录包，再使用单词职责文件；禁止在父目录平铺相似复合文件名、
用 `source.py` 保存旧实现，或通过包根重复导出内部 owner。架构测试锁定本包结构和退役文件，
让后续 Agent 的错误命名在 CI 中直接失败。
**Acceptance**
- `app/runtime/dependencies.py` 与 `app/runtime/native_dependencies.py` 删除且不得复活。
- `app/runtime/dependencies/` 只包含 `__init__.py`、`profile.py`、`native.py`；包根没有实现或重复导出。
- 所有宿主 canonical 导入改为明确子模块；最新官方插件仓扫描决定是否需要精确 Compat 映射。
- 命名规范、架构文档、依赖基线和结构门禁同步；`app/plugins/**` 不扫描、不修改。
- 运行依赖分组、插件原生依赖激活、插件安装/包管理专项及架构/质量门禁全部通过。
- 提交推送后确认远端 SHA、祖先关系和 ahead/behind `0/0`。
**Evidence（2026-08-29）**
- 平铺实现已删除，`app/runtime/dependencies/` 仅有 `__init__.py`、`profile.py`、`native.py`；包根只有包说明，宿主导入全部直达职责子模块。
- Docker 更新边界同时覆盖新包载荷与旧版本 `dependencies.py` 快照回滚，未把旧实现恢复到主程序。
- 官方插件仓最新远端 `aa40b961a2093474a77edd9eed88844ff07425ac` 对旧路径及全部公开符号零命中，因此未新增无消费者的 SDK/Compat 债务。
- 运行依赖、原生激活、插件安装/包管理及架构专项 `406 passed`；最终架构/CI/Docker 门禁 `182 passed`。
- 锁定全量 `7224 passed, 9 skipped`；Pylint `10.00/10` 且重复率 `0.000%`；mypy、Ruff（历史诊断降至 `667`）、复杂度和依赖基线门禁全部通过。
- 交付提交 `13fba96fd82f4e94dbda8cff5dc635966e06fa67` 已推送；本地、`origin/v3` 与远端引用一致，ahead/behind `0/0`。
### S3-L5 SearchChain
**Status:** `DELIVERED`
**Outcome**
退役 `app/chain/search.py` 单体，由同名 `app.chain.search` 包承接搜索计划、provider fan-out、
分页、结果状态、AI 推荐、字幕与音乐搜索等职责。包根只惰性保留稳定 `SearchChain`，Facade 只组合
职责 owner 与稳定入口；主程序不保留 `source.py`、旧实现或内部 owner/port 重复导出。
同步、异步和流式入口必须复用同一组纯规则与状态 owner；provider 并发、取消、分页推进和结果发布
各自只有一个执行所有者，不能通过复制现有大方法形成多套业务实现。
**Acceptance**
- 公开 `SearchChain` 类身份、方法签名、MRO、pickle 身份和官方插件调用形态不变。
- `app/plugins/**` 不扫描、不修改；官方插件仓通过独立宿主兼容基线验证。
- 搜索计划、provider fan-out、分页、取消和状态发布的同步/异步/流式行为保持一致并有回归覆盖。
- Search 专项、架构/兼容、mypy/Ruff/complexity、scoped Pylint 全部通过；广泛变更运行锁定全量。
- 本叶提交推送后确认远端 SHA、祖先关系和 ahead/behind `0/0`。
### S3-L6 MediaChain
**Status:** `DELIVERED`
**Outcome**
退役 `app/chain/media.py` 单体，由同名 `app.chain.media` 包承接 recognition、plugin event、
auxiliary、projection、search、catalog、path、album 和 cache。包根只惰性暴露稳定
`MediaChain`；Facade 保持直接 `ChainBase` MRO、Singleton/pickle 类身份和官方插件真实调用签名，
内部 owner 与刮削兼容符号不从包根重复导出。
目录缓存使用有界 LRU、文件内容签名、深拷贝隔离与同步/异步单飞；等待者取消不会反向取消共享
flight，符号链接目录别名不会因物理路径相同而错误共享专辑线索。跨 Chain 音乐来源复用只依赖公开
`MusicMetadataSourceChain`，架构门禁拒绝跨 owner 导入下划线私有合同。
**Evidence**
- Media/架构/插件端点集中回归 `551 passed`；锁定全量 `7244 passed, 9 skipped`。
- Pylint `10.00/10`、零重复；mypy 低水位 `10686 / 597`，Ruff 低水位 `661`，复杂度、宿主
dependency/runtime contract baseline 全部通过。
- 最新官方插件仓 `aa40b961a2093474a77edd9eed88844ff07425ac` 的 MediaChain 消费者 15 个，
official-plugin baseline 与 V3 聚焦测试 `130 passed`；`app/plugins/**` 未扫描、未修改。
- 交付提交 `13c4a71f42d189f618ac8663afb967d1517a79bb` 已推送；本地、`origin/v3` 与远端引用
一致，ahead/behind `0/0`。
### S3-L7 Agent/System/Plugin API
**Status:** `DELIVERED`
**Outcome**
把 WebAgent SSE/file/audio、System nettest/log/update 与 Plugin market 入口中的可复用用例编排下沉到
Application owner；endpoint 只保留请求鉴权、参数/响应映射和流式传输适配，不直接组合具体 Adapter、
Helper、Manager 或跨多个领域状态。
**Acceptance**
- 先以真实入口调用图确认厚方法、I/O、状态和生命周期边界，再按独立用例迁移，不复制 endpoint 实现。
- Application 自有明确 Port/DTO，具体 Adapter 和 Runtime manager 只由 startup/composition 注入。
- 旧插件兼容只经 SDK/Compat；canonical endpoint 不保留旧业务实现或重复导出，`app/plugins/**` 排除。
- Agent/System/Plugin API 专项、架构/外联/类型/复杂度门禁及锁定全量通过后才可交付。
**Evidence**
- `app/api/endpoints/agent.py` 从 2,000 余行收敛为传输层；WebAgent 事件、会话、附件和音频用例由
`app/application/messaging/agent.py` 承担，运行时实现进入单词命名的 `app/agent/web.py`。
- System 网络探测目录、HTTPS/重定向准入和内容校验进入 `app/application/network.py`；Plugin 市场投影、
Release、评分和目录读写分别由 `catalog.py`、`release.py`、`rating.py`、`folders.py` 唯一拥有。
- 提交 `f38637dceaa2b7fedc8ab30a41aaad3d67392ec5` 已推送；本地锁定全量 `7256 passed, 9 skipped`，
Pylint `10.00/10`、架构/外联/类型/复杂度门禁和官方插件基线通过，远端 ahead/behind `0/0`。
### S5-L1 PluginHelper/PluginManager
**Status:** `DELIVERED`
**Outcome**
清除 `PluginHelper`、`PluginManager` 中仍混合的市场、包、依赖、备份、健康检查和运行时构造职责；
每项能力归入现有单一 owner，稳定插件 ABI 只由受控 Facade/SDK/Compat 暴露。
**Acceptance**
- 先审计真实宿主与官方插件调用图；现有 owner 能承接的能力不得新建近义文件或重复 Facade。
- 多文件能力使用同名包和单词子模块，包根不得为宿主提供重复导出；`app/plugins/**` 排除。
- PluginHelper/PluginManager 专项、兼容基线、架构门禁及受影响测试全部通过后才可交付。
**Delivery (2026-08-29)**
- `PluginHelper` 仅保留精确旧 ABI、安装 Gateway 和 owner 委托；市场传输、索引、Release 与本地候选
由 `PluginMarketTransport` 唯一拥有。
- `PluginPackageManager`、`PluginDependencyInstaller`、`PluginRuntimeHealth` 分别唯一拥有包事务、依赖安装
与运行环境检查/恢复；API、Agent 与 Manager 不再保留物理删除或具体 Adapter 构造。
- `PluginManager` 只消费 startup 提前注入的 typed `PluginRuntime` factory；Compat/SDK 无重复 canonical 导出。
- 最新官方插件仓 `d5a786882` 基线与兼容探针通过；架构全集 `220 passed`，锁定覆盖率全量
`7302 passed, 9 skipped`，Pylint `10.00/10` 且零重复，Ruff `654`、mypy `10496`，覆盖率低水位
Application `80.92%`、Domain `79.87%`。实现提交 `fa40f29df` 已推送，远端 ahead/behind `0/0`；
GitHub 工作流已触发，不把 queued/in_progress 状态记作远端绿色。
### S5-L3 Domain projection
**Status:** `DELIVERED`
**Outcome**
`app/domain/context.py` 继续唯一拥有 canonical `MediaInfo` 类型、构造参数、属性和四个历史 setter ABI；
TMDB、豆瓣、Bangumi、AniList 详情到统一字段的规则一次迁入 `app/domain/projection/`，接收只读快照并
返回字段映射，不修改来源或当前输入。TMDB 图片构造器归 `tmdb.py` owner，宿主调用方直接导入来源 owner。
**Compatibility and gates**
- `app.core.context` 继续由现有精确 Compat 映射到 `app.domain.context`，未新增 SDK/Compat 或包根重复导出。
- `app/schemas/context.py` 仍是传输 DTO，不复制 setter 或投影业务；`app/plugins/**` 未改动。
- 架构门禁固定投影包文件集合、空包根、setter 薄委托和宿主禁用 `MediaInfo` helper；golden、输入不可变、
多来源顺序、字段对齐与 setter 签名测试共同守住行为和 ABI。
**Local verification (2026-08-29)**
- 基于 `origin/v3@d17d62e95` 锁定全量 `7375 passed, 9 skipped`；投影/响应/来源/Compat/架构专项全绿。
- scoped Pylint `10.00/10` 且零重复；新 `domain/projection` owner mypy 零错误，strict frontier、
Ruff、mypy、复杂度和宿主依赖低水位均通过。
- 最新官方插件仓 `2d6946eb1` 兼容基线通过；`app/plugins/**` 零改动，包根只有说明且无重复导出。
### S5-L4 Startup composition
**Status:** `DELIVERED`
- configuration、database、network、security、agent、server、outbox、subscription 与 Chain 的具体构造
全部归入单词型 `startup/composition/*` owner；initializer 只消费 composition API。
- `RuntimeDependencies`、HostRuntime、命名领域 Runtime 与旧 `ApiDataPorts` 投影共享同一对象身份，
不再由 initializer、Facade 或兼容入口二次构造。
- lifecycle 通过显式逆序 reset manifest 撤销 Provider；数据库 worker 未收敛时保留 owner 与连接供诊断，
启动失败复用同一正式清理路径。
- 2026-08-29 真实进程启动达到 `Application startup complete`，`/health/live` 与 `/health/ready`
均返回 HTTP 200，随后达到 `Application shutdown complete`；验证未加入 revision 白名单、自动 stamp、
跳过迁移或环境判断脚本。
### S5-L5 Sync/async 重复清零
**Status:** `DELIVERED`
- Search/TVDB、MusicBrainz、TheAudioDB、AcoustID、AniList、Bangumi、ServerReport、Memory、Yema、
通知、豆瓣、媒体识别、目录源、Indexer、TMDB API 与 Recommend 的双 ABI 共用请求计划、响应投影、
回退条件和业务状态机；同步/异步入口只保留真实 I/O 差异。
- 移除 TVDB 整段同步方法的伪异步线程包装；网络客户端和数据库 Session 均按调用或事件循环持有，
不跨事件循环复用。
- 新增或改造的 parity/生命周期测试均为 pytest-native，并恢复 provider、singleton、cache、事件循环与
`sys.modules`；本轮未新增 `unittest.TestCase`。
- `5ba7e6170` 完成本叶最后一批共享决策，mypy 低水位降至 10,008，Ruff 低水位降至 633，
Pylint 保持 `10.00/10` 且重复代码为零。
### S5-L6 最终兼容与交付
**Status:** `DELIVERED`
- 22 个不符合规范的 canonical 文件名已归并为单词文件或同名职责包；旧实现文件和主程序包根重复导出
已删除，宿主调用方直接导入真实 owner，兼容只由精确 SDK/Compat manifest 提供。
- 官方插件仓已同步至 `161fce34caa31deb7d82dd50a31f217d5e6784c2`；285 个 Python 文件的
ABI/导入语义基线不变，仅更新 provenance。
- `app/plugins/**` 始终作为插件副本排除，未修改、未纳入基线写入或提交。
- 锁定串行覆盖率全量 `7659 passed, 9 skipped`；Application/Domain 低水位提升并固化为
`81.61%` / `81.03%`。Host 架构、Event/Egress policy、复杂度、async 阻塞、TaskRegistry、
service locator、mypy/Ruff ratchet、启动性能、Pylint `10.00/10` 与依赖一致性均通过。
- exact-head 失败后已将 canonical `SearchChain` Facade 改为显式类型转发，并修正 API/Workflow 的
Optional、Domain/Schema DTO 边界；2026-08-30 最终本地锁定全量 `7659 passed, 9 skipped`，
CI 同构架构测试 `197 passed`，mypy 低水位降至 `9,987`，Ruff、Pylint `10.00/10`、复杂度、
async、TaskRegistry、service locator、启动性能与依赖快照门禁均通过。
- `4575b11d8` 修复 canonical `SearchChain` 类型转发并更新真实低水位，`c204e2e97` 修正架构测试对
Chain owner 的直接导入；两者均已推送并进入 `origin/v3` 祖先链。精确 head `c204e2e97` 的
Unit Tests `33269394727` 与 Pylint `33269394716` 全绿，本地与远端 ahead/behind 为 `0/0`，
S5-L3 至 S5-L6 的最终远端门禁统一闭环。
### S1-L1.1 Durable admission
**Status:** `DELIVERED`
**Outcome**
把“接受整理任务”变成真正的 durable admission：Application 先通过类型化 Port 在独立事务中
commit pending，再尝试写入进程内队列。队列写入失败或进程在 commit 后退出时，持久记录仍能成为
后续恢复起点；持久化失败则不允许任务进入队列。该叶只结清 admission 所有权和顺序，不预先宣称
planning、lease、幂等执行或终态恢复已经完成。
**Ownership**
- `app/application/transfer/workflow.py` 拥有 admission DTO、Protocol、结果语义与 persist-before-enqueue 编排。
- `app/db/adapters/` 提供短 Session/UoW 的 Transfer pending 持久化实现；`app/db/oper/` 只接收
adapter 拥有的 Session 并 stage/flush。
- `app/startup/` 负责构造并注入 adapter，宿主 Chain 不再取得 raw/`Any` `TransferPendingOper`。
- `app/db/models/transferpending.py` 与配套 Alembic migration 只承载该叶需要的 durable admission
schema，并验证既有记录升级及 downgrade。
- Transfer queue、pending repository、migration、架构边界及兼容回归测试。
**Excluded**
- 不在本叶实现 planning checkpoint、lease/heartbeat、文件操作幂等、历史结算或 `manual_review`；
这些分别由 `S1-L1.2` 至 `S1-L1.4` 完整交付。
- 不修改插件公开 Transfer ABI、旧插件导入路径或第三方插件行为；必要兼容只通过统一 Compat/Legacy
层委托新的 canonical admission 实现。
- 不修改或扫描 `app/plugins/**` 插件副本。
- 不保留宿主 canonical raw/`Any` pending port 与新 typed Port 两套正式入口。
**Acceptance**
```bash
.venv/bin/python -m pytest \
tests/test_transfer_queue_service.py \
tests/test_transfer_pending_replay.py \
tests/test_transfer_admission_migration.py \
tests/test_db_transferpending_queries.py \
tests/test_database_migration_startup.py \
tests/test_architecture_dependencies.py \
tests/test_legacy_import_compat.py -q
.venv/bin/mypy --config-file mypy.ini
.venv/bin/python scripts/architecture/baseline.py --check-host --diagnostics
.venv/bin/python scripts/architecture/ruff_ratchet.py
.venv/bin/python scripts/architecture/mypy_ratchet.py
uv run --locked --no-sync python tests/run.py
git diff --check
```
**Delivery**
- 单一提交主题：交付 Transfer durable admission、类型化持久化边界及可逆 migration。
- 提交前证明 pending commit 发生在 enqueue 之前；持久化失败不入队，enqueue 失败或 commit 后崩溃
均保留可恢复记录；宿主 canonical 路径不再导入或取得 raw/`Any` `TransferPendingOper`。
- 运行锁定全量测试与 scoped Pylint；插件公开 Transfer ABI 和统一兼容导入测试必须保持通过。
- 推送 `origin/v3` 后确认提交祖先关系、远端 SHA 和 ahead/behind `0/0`。
**Local verification (2026-08-27)**
- 锁定全量：`6,496 passed, 7 skipped`；跳过项包含本机未配置隔离库的 PostgreSQL migration
用例，SQLite upgrade/downgrade/re-upgrade 已真实执行。
- scoped Pylint：`10.00/10`；host dependency baseline、Ruff ratchet、mypy ratchet 与
`git diff --check` 全部通过。
- failure injection 已覆盖 admission 失败不入队、batch/enqueue 失败保留记录、批次返回失败、
queue -> worker -> terminal discard 稳定身份，以及 Legacy TransferTask 序列化字段不变。
### S1-L1.2 Planning checkpoint
**Status:** `DELIVERED`
**Outcome**
把 durable admission 推进为可独立恢复的 `accepted -> provider_pending -> planned` 状态：准入时冻结
版本化请求 JSON 和 SHA-256 指纹；存在旧插件 provider 时先 CAS 提交精确身份、顺序和原始 ABI 参数，
全部返回空后才由 FileManager 只读规划目标及有序叶操作，并通过第二次 CAS 提交宿主 checkpoint。
任何对应 checkpoint 提交前都不允许进入其文件副作用；`provider_pending` 重放只消费冻结调用，
`planned` 重放只消费冻结 resolved 上下文、目标和操作，不重新访问在线识别、目录选择或重命名配置。
**Ownership and compatibility**
- `app/application/transfer/workflow.py` 拥有 planning input、plan item、checkpoint 和状态错误合同；JSON 版本、
指纹及 resolved 上下文均可跨进程 round-trip。
- `app/modules/filemanager/transhandler.py` 是唯一目标规划与文件执行实现；`FileManagerModule.transfer`
与 `TransHandler.transfer_media` 已删除，不保留第二套重命名、覆盖或目录递归逻辑。
- `app/db/adapters/transfer/admission.py` 通过短 Session/UoW 提交 checkpoint；Oper 只负责带状态和指纹条件的
stage，3.0.14 migration 可升级、降级并在中断后重跑。
- cleanup intent 随准入输入冻结。宿主路径由 FileManager 在 `TransferIntercept` 放行后、任何文件写入前
执行；legacy provider 路径为保持旧 ABI 顺序，在全部冻结引用解析成功后、调用 provider 前执行。
strict 查询确认目标不存在才视为幂等成功，查询或删除失败抛错并保留对应 checkpoint 供重试；provider
全空后提升的宿主 checkpoint 会记录 cleanup 已完成，禁止二次查询或删除。
- 插件公开 Transfer 方法签名、事件类型和 payload 不变；旧 provider 身份和顺序随 checkpoint
冻结，提交后由统一 dispatcher 精确解析并严格执行，缺失或异常时明确失败而不静默换路；全部返回空
才生成宿主 plan，并以第二次 CAS 提交 `planned` checkpoint 后执行。`ChainBase.transfer` 仅委托启动
组合根注入的 canonical durable
command，内部 plan/execute 合同不向插件调度；新 DTO 不从包根重复导出，`app/plugins/**` 插件
副本不参与改造。
**Excluded**
- 本叶不引入 claim、lease、heartbeat、attempt、执行步骤幂等或 `manual_review`；这些由
`S1-L1.3` 和 `S1-L1.4` 交付。
- 本叶当时不单独承诺文件操作成功后到历史结算前的未知结果；该能力现已由 `S1-L1.4` 和
`S1-L1.5` 的持久步骤账本、严格探测、`manual_review` 与 task-aware settlement 完整交付。
**Local verification (2026-08-27)**
- planning、持久化、迁移、兼容、replay 和 worker 聚焦回归：`224 passed, 2 skipped`；跳过项仅为
本机未配置隔离 PostgreSQL，SQLite upgrade/downgrade/re-upgrade 已覆盖。
- 完整本地套件：`6,578 passed, 8 skipped`；架构回归：`174 passed`；scoped Pylint `10.00/10`；
host baseline、Ruff/mypy ratchet 与 `git diff --check` 通过。
- failure injection 覆盖 commit 前零文件副作用、commit 后崩溃重放、离线 resolved context 恢复、
配置漂移仍使用冻结 target storage、规划失败留痕、旧 provider 提交后短路、严格异常、空结果两阶段
fallback、缺失引用零 cleanup，以及 cleanup 顺序/幂等/瞬时失败。
### S1-L1.3 Lease 与恢复调度
**Status:** `DELIVERED`
**Outcome**
为 durable transfer 增加可过期、可接管且带 fencing token 的执行租约。`owner` 只用于标识执行者，
每次有效 claim 生成的新 token 才是后续 heartbeat、checkpoint、失败留痕和终态删除的授权；所有写入
必须同时匹配当前且未过期的 token，过期 worker 即使稍后恢复也不能修改新 owner 的记录。
`accepted`、`provider_pending`、`planned` 仍是业务 planning phase，lease 与其正交：claim、heartbeat
和 takeover 不改变 phase，恢复 worker 继续按冻结 checkpoint 决定执行路径。启动回放与同进程恢复共用
唯一调度入口：恢复任务在入队前完成原子 claim 并绑定 token，新 admission 由 worker 在任何副作用前
claim。已经 claim 的恢复任务不在 worker 内二次 claim。
**State machine**
| 当前租约 | 操作 | 结果与 fencing 约束 |
|---|---|---|
| 无租约 | `claim` | 生成新 token、设置 owner/到期时间并递增 attempt；phase 不变 |
| 当前租约未过期 | 同 token `heartbeat` | 只延长当前租约；owner、token、attempt 和 phase 不变 |
| 当前租约未过期 | 任意再次 `claim`，包括同 owner | 原子拒绝，不递增 attempt、不入队、不执行副作用 |
| 当前租约已过期 | `heartbeat` 或旧 token 写入 | 原子拒绝；旧租约不可复活 |
| 当前租约已过期 | 新 worker `claim` | 生成新 token 并递增 attempt；旧 token 永久失效，phase 不变 |
| 当前 token 有效 | checkpoint、失败留痕或终态删除 | 仅精确 token CAS 成功；状态提交后不得由旧 worker 覆盖 |
任意时刻一条 pending 记录最多只有一个数据库认可的有效 fencing owner。该保证不等同于外部文件、
插件或历史副作用 exactly-once；租约在不可中断调用期间过期时，旧调用的外部结果仍可能未知。
**Scheduling and shutdown**
- 启动回放和同进程恢复只调用一个 claim-and-schedule 入口；禁止另建 list-then-enqueue 回放路径或
第二个 retry owner。批量恢复必须先原子 claim，再把已绑定 token 的任务交给唯一 worker 队列。
- heartbeat 由 Transfer worker 生命周期拥有，不创建游离后台 owner；停止时先封口新 claim 和调度，
再通知并有限等待 worker，heartbeat 在 worker 存活期间继续维持其租约。worker 收敛后才停止
heartbeat；超时时保留仍存活的 worker/heartbeat owner 并返回失败。
- checkpoint、失败留痕和 pending 删除在同次持久化写入中执行 token CAS；租约丢失后 worker 停止
继续提交状态，不以预查询替代 fencing，也不把 stale mutation 伪装成成功。
- 确定性失败只确保唯一 scheduler 存在，不即时唤醒；新建的失败恢复 owner 首次扫描先等待固定轮询
周期。损坏持久投影按单任务事务回滚，再以无有效租约 CAS 留下去重诊断，不能饿死后续健康记录。
- 精确旧 `app.db.transferpending_oper` 导入只解析到 `app/sdk/_legacy` 门面；canonical Model、Oper、
Application Port 不保留旧 list-then-act 或无 fencing mutation。兼容 `discard/clear` 也不得删除任何
带 token 的有效或过期 claim。
**Excluded**
- 本叶不承诺文件、legacy provider、历史写入或其他外部副作用 exactly-once，也不以延长 lease
掩盖不可判定结果。
- 文件步骤幂等键、逐步结果 checkpoint、崩溃后未知结果判定、唯一 retry owner 和
`manual_review` 终态由 `S1-L1.4` 完整交付。
- 不增加 `processing` 等与 planning phase 重复的业务状态；不修改插件公开 Transfer ABI，不扫描或
修改 `app/plugins/**`，不恢复宿主旧 pending 入口或重复导出。
**Acceptance matrix**
| 场景 | 必须证明 |
|---|---|
| 新 admission 与恢复记录竞争 | 只有 claim 成功者入队并执行；失败者零文件副作用 |
| 两进程同时 claim 同一记录 | 仅一个新 token 成功，attempt 只按真实新 claim 增长 |
| heartbeat 与 takeover 竞争 | 未过期 heartbeat 可续租；过期租约不可复活，接管 token 唯一有效 |
| 旧 worker 延迟提交 | checkpoint、失败留痕和删除均被 token CAS 拒绝，不覆盖新 owner |
| 三种 planning phase 恢复 | claim/续租/接管保持 phase，并消费各自冻结输入或 checkpoint |
| 启动与同进程恢复同时触发 | 只经过唯一 scheduler 入口，同一任务只有一个 worker owner |
| 正常与超时关闭 | 先封口后有限等待；存活 scheduler/heartbeat/worker 不丢失 owner、不报告成功 |
**Failure injection matrix**
| 注入点 | 预期持久结果 |
|---|---|
| claim commit 前崩溃 | 无新 token、attempt 不变，可由后续 worker claim |
| claim commit 后、入队前崩溃 | 租约到期后可接管，新 token fencing 旧 worker |
| worker 执行前 lease 丢失 | 不执行文件副作用，不提交失败或终态状态 |
| heartbeat commit 前后崩溃 | 仅已提交到期时间生效；过期后不可用旧 token 续租 |
| checkpoint/失败留痕提交时被接管 | stale CAS 失败，新 owner 的 phase、错误和 token 不被覆盖 |
| 终态删除提交时被接管 | stale delete 为零行，pending 保留给当前 owner |
| shutdown 时 scheduler、worker 或 lease release 阻塞 | 有限等待返回失败并保留 owner/heartbeat，禁止清句柄后重建重复 owner |
本叶验收还必须运行 lease persistence、replay/worker、startup lifecycle、migration、架构与兼容聚焦
测试，以及锁定全量测试和 scoped Pylint；插件 ABI 只经统一 Compat/SDK 验证。
Reference in New Issue View Git Blame Copy Permalink