workinf_Blender_Wasm/docs/BLENDER_WEB_PARITY_FOLLOWUP_PLAN.md

Blender/Web 移植后续执行安排

更新时间：2026-08-26（America/New_York）

1. 目标与当前结论

目标是让 Web 版本在 Chromium 中形成可持续的 Blender 工作流：打开 .blend、读取 SceneIR、执行受约束的 Main mutation、保存/重开、恢复和导出，并且每项声明都绑定可复现证据。

当前基线已经可以正常工作，但还不能宣称“与 Blender 全量 parity”：

• quick CI 已修复 Node 堆内存问题：7/7 lane READY，128 个 unit 文件隔离执行。
• Blender 5.2 inventory 有 6,900 条记录，聚合为 15 个 capability family；当前记录仍是 L0 / METADATA_ONLY。
• P7-002 已生成 45 个原子任务，即 15 个 family 乘以 desktopPositive、wasmMutation、saveReopenExact。
• P7-003 的恢复链为 READY，但 parityClosure 和 releaseDecision 为 BLOCKED；当前 9/45 atomic 行为已有可审计 Chromium receipt。
• M12 有 82 条、42 个路径的 SHA 漂移；Git-history snapshot 已恢复 22 条，剩余 60 条保持 BLOCKED_SOURCE_LOST，历史 manifest 不得重写。

因此后续安排分为两条并行轨道：

1. 新证据驱动的 Blender/Web 正向移植。
2. M12 原始来源快照恢复与 provenance 重建。

当前机器整合入口为 node tools/web/generate-wbv2-integration-readiness.mjs，输出 tests/golden/WBV2-P7-003/integration-readiness-report.json；该报告是继续开发的 checkpoint，不是 parity 成功声明。

2. 不可违反的规则

1. 只使用 Chromium 作为浏览器证据；Firefox/WebKit 不进入本计划的验收范围。
2. 旧 manifest 的原始 SHA、时间线和状态不可改写。新发现只能追加 corrective evidence。
3. 一个执行任务只负责一个主要行为。共享代码可以复用，但每个行为必须有独立 fixture、报告和 manifest。
4. FEATURE_PARITY 只有在以下条件同时满足时才能出现：
   • Blender desktop 正向结果；
   • WASM/Main 正向 mutation；
   • save/reopen 精确保持；
   • Chromium 生产路径通过；
   • malformed、unsupported、cancel、duplicate、over-budget 和 hash-drift 负例均 fail-closed。
5. 任何失败都保持 in_progress 或 blocked，不能手工推进 nextTask。
6. 所有产物必须由 generator/checker 生成，并由 SHA-256 manifest 绑定。

3. 阶段安排

阶段 A：构建与证据基础设施（第 1-2 天）

目标：让桌面 binary、WASM binary、测试 runner 在同一工作区可重复运行。

工作项：

• 重新配置 build_blender_5.2.0 的 CMake cache，使 RUNPATH 指向当前工作区的依赖目录；禁止依赖 /home/mes123456/working 的隐式路径。
• 记录 Blender、Emscripten、Node、Chrome、依赖库版本和 SHA；生成一份可复现环境 receipt。
• 保持 tools/web/run-unit-tests.mjs 的隔离策略，quick lane 每次提交都运行。
• 为 generated-gap checker 抽出通用的 open -> snapshot -> mutate -> save -> reopen -> negative runner，减少各任务重复代码。
• 统一 comparator：对象 ID、Main revision、delta、资源 hash、save/reopen hash 必须使用 canonical JSON 比较。

完成条件：

• cmake --build build_blender_5.2.0 -j2 成功；桌面 binary 在不依赖旧工作区路径的情况下启动。
• quick CI、typecheck、lint、context governance 全部通过。
• 同一 fixture 连续生成两次字节一致。

阶段 B：三条现有正向链路固化（第 3-5 天）

目标：把已有 C5 pilot 的 Mesh、Modifier、Asset 能力转成标准 Web evidence 模板。

复用模块：

• web/protocol/corrective-main-transaction.ts
• web/protocol/corrective-mesh-command.ts
• web/protocol/corrective-modifier-command.ts
• web/protocol/corrective-asset-catalog-command.ts
• 现有 C5 Chromium family reports 和 save/reopen checker

每个 family 必须补齐：

• desktop positive fixture；
• WASM/Main mutation 和 revision 变化；
• undo/redo 与 save/reopen；
• Chromium production interaction；
• malformed payload、stale revision、missing target、budget overflow 负例。

完成条件：

• 三个 family 的 evidence 从 CANDIDATE 变为可审计的正向结果。
• 旧 C5/M12 证据只读消费，不改变历史 SHA。
• 共享 runner 能在单条命令中重复三族验证。

阶段 C：按风险批量移植高价值 family（第 2-3 周）

采用“一个共享能力实现 + 三个原子证据任务”的节奏。实现一次，证据拆成三个独立任务，不为 6,900 条 legacy 记录重复造轮子。

优先级如下：

顺序	family	规模	先解决的问题	主要复用方向
1	UI_EDITOR	3,930	editor/context/keymap 与 Chromium 输入一致性	editor workflow、keyboard/pointer/input-modal
2	MEDIA_IO	585	import/export、媒体资源、外部依赖与 loss report	GLB/OBJ/PLY/STL、asset sandbox、media recovery
3	NODES_GRAPH	543	Geometry Nodes/shader allowlist、预算和 compile rollback	geometry-nodes、shader-compiler、render budget
4	MESH_EDITING	431	选择、拓扑 mutation、binary delta	mesh command、mesh geometry delta、topology comparator
5	OBJECT_OPERATIONS	316	transform、parent、collection、undo/redo	Main transaction、scene delta、selection history
6	RIG_ANIMATION	375	Action、TRS、pose、constraint、skin	animation、NLA、armature、skin protocol
7	MATERIAL_RENDER	125	PBR/UV/texture 与渲染路由	shader graph、render routing、packed assets
8	SIMULATION	155	cache identity、cancel、quota、restart	simulation cache、worker fault、storage journal
9	SCULPT_PAINT	117	PBVH 限制、笔刷/笔画和非 mesh slice	sculpt、paint、non-mesh binary
10	CORE_SCENE_GRAPH	66	Scene/Collection/Object/Depsgraph canonical state	SceneIR、stable IDs、world matrices
11	CORE_DNA_RNA	38	RNA metadata read and unsupported retention	reader metadata、unknown-field preservation
12	CORE_MESH	31	Mesh datablock schema and attributes	binary mesh、attribute domains
13	OTHER_OPERATOR	103	无法归入高阶 family 的小范围 operator	explicit unsupported/EXCLUDED routing
14	CORE_OBJECT	2	Object identity/read compatibility	scene graph reader

MODIFIER_SYSTEM（83）虽然 legacy 记录相对完整，也必须经过同样的 WASM mutation 和 persistence 证明，不能仅凭旧 completed 状态提升 parity。

每个 family 的固定工作包：

1. 选 1 个最小可观察行为，建立 Blender fixture 和 canonical expected state。
2. 在 web/protocol 建立或复用 bounded command，统一走 Main transaction。
3. 接入 web_engine_blend_reader.cpp，只读取声明的数据，不执行任意 Blender operator 或脚本。
4. 添加桌面 checker、WASM checker、Chromium e2e、unit negatives。
5. 生成该 family 的三个原子 manifest，只有三项证据均通过时才提升 capability 状态。
6. 通过 handoff 后再由 generator 激活下一个任务。

阶段 D：完整 45 项原子队列关闭（第 3-4 周）

目标：逐项清空 P7-002 队列，但不把同类 legacy 记录重复实现。

每项任务的最小证据包：

• fixture 和 generator；
• desktop report；
• WASM/Main report；
• Chromium report（涉及生产交互时必须有）；
• persistence/hash report；
• negative matrix；
• status、manifest、task-context；
• parent manifest SHA 和当前 source/build SHA。

队列推进规则：

• 始终只有一个 active + ready；
• 当前任务完成后由 manifest 的 nextTask 决定下一项；
• 任何 hash drift、环境缺失或测试失败都停在当前任务；
• 每完成一个 family，重新计算 6,900 条 legacy 覆盖映射，已证明的记录保留 regression coverage。

阶段 E：M12 provenance 恢复（与阶段 C/D 并行）

这条轨道不依赖 Web 功能实现，责任人必须提供以下任一权威来源：

• 原始 immutable repository snapshot；
• 带签名的 M12 artifact archive；
• CI artifact store 中可验证的原始文件和时间戳。

恢复步骤：

1. 只读导入来源，计算原始 SHA，不覆盖当前文件。
2. 将原始文件与当前观察值做逐项三方比较：original manifest、source snapshot、current worktree。
3. 对能复原的条目生成 PROVENANCE_RESTORED corrective evidence。
4. 对仍无法复原的条目保留 BLOCKED_SOURCE_LOST。
5. 只有 provenance checker 和 protected hash checker 同时通过，才允许影响 release gate。

在来源恢复前，禁止以下行为：

• 用当前文件反推旧文件；
• 用新 manifest 覆盖旧 manifest；
• 删除 drift entry；
• 把 BLOCKED_SOURCE_LOST 改成 READY 或 FEATURE_PARITY。

阶段 F：Release closure（第 5 周）

只有阶段 D 和 E 都完成后执行：

• 重新生成完整 capability parity map；
• 统计 FEATURE_PARITY、READ_COMPATIBILITY、NEGATIVE_BOUNDARY、EXCLUDED、BLOCKED；
• 运行 quick、Chromium、release、offline、SBOM、rollback 全套 lane；
• 检查所有声明都绑定 manifest 和 immutable source/build SHA；
• 生成 known limitations 和最终 release decision。

release decision 的允许状态：

• READY：所有目标 capability 达到声明级别，历史 provenance 完整；
• BLOCKED：存在任何未闭合 parity、来源丢失、hash drift、负例不安全或 release lane 失败；
• 不允许使用“近似完成”或隐式降级状态替代上述两种状态。

4. 每周产出与效率指标

每周必须产出：

• 完成的 capability family 数；
• 新增正向 desktop/WASM/Chromium evidence 数；
• 从 L0 提升的 legacy 覆盖条目数；
• 仍为 BLOCKED 的条目数及原因分布；
• quick CI 平均耗时与峰值 Node heap；
• fixture 重生成字节一致率；
• M12 provenance 恢复条目数。

建议效率目标：

• 每个 family 至少关闭 3 个原子行为证据，覆盖同族 legacy 记录；
• 每周完成 3-5 个 family，而不是逐条处理 6,900 个 legacy operator；
• 每个 family 的重复 checker 代码不超过一个模板文件的 20%；
• quick lane 保持单次提交可运行，Chromium lane 在 family 合并前运行；
• 失败任务平均恢复时间小于一个工作日，且不通过改历史证据解决。

5. 当前立即执行顺序

1. 修复 build_blender_5.2.0 的 workspace RUNPATH，并生成环境 receipt。
2. 用现有 C5 Mesh/Modifier/Asset 证据跑通统一 family runner。
3. 激活 P7-002 队列中第一个高风险 family 的 desktopPositive 任务。
4. 依次完成该 family 的 wasmMutation 和 saveReopenExact，再推进下一个 family。
5. 每个 family 完成后更新 parity map 和风险报告，但不修改 M12 历史 manifest。
6. 并行向 provenance 责任人索取 M12 immutable snapshot；在收到前保持 release gate BLOCKED。
7. 只有 45 项原子任务和 M12 provenance 都闭合，才重新运行 P7-003 release gate。

6. 回滚与停止条件

出现以下任一情况时立即停在当前任务：

• desktop 与 WASM/Main 状态不一致；
• save/reopen 改变 Main revision、资源 hash 或稳定 ID；
• malformed/unsupported/cancel/over-budget 输入改变 Main；
• source/build/fixture/manifest hash 漂移；
• CMake、Node heap、Chromium 或 Blender 环境不可复现；
• M12 来源仍不可验证。

回滚只删除当前新任务的 fixture、报告、manifest、status 和 context，恢复 parent 的 queue tail；不得触碰已完成任务的历史 evidence，也不得把失败任务标成完成。

7. 完成定义

本计划只有在以下条件同时满足时才算完成：

• Web 生产路径可在 Chromium 中完成 open/edit/undo/redo/save/restart/reopen/export；
• 15 个 capability family 的目标 parity level 有逐项证据；
• 45 个原子行为任务全部完成或明确 EXCLUDED/BLOCKED 并有原因；
• 负向边界、资源预算、取消、重启、OOM、quota、device loss 均 fail-closed；
• M12 historical SHA 的可复原部分有权威 source snapshot，剩余部分明确保留 blocked；
• quick/Chromium/release/offline/SBOM/rollback 和 protected hashes 全部通过；
• 最终 release gate 不依赖人工解释或手工重写历史文件。

8. 项目完成情况总表（整合视图）

这里的“完成”严格指对应任务的机器验收和 manifest handoff 已完成，不把它扩大解释为 Blender 全产品 parity。

区域	机器状态	已有成果	仍需整合的内容
P0 事实与合同	3/3 done	scope、6,900 条 Blender 5.2 inventory、capability/error/budget contract	将 inventory 条目映射到最终 FEATURE_PARITY、READ_COMPATIBILITY 或 EXCLUDED
P1 Runtime/Main	5/5 done	single/pthread receipt、SceneIR stable ID、Main transaction/history、Worker lifecycle、OPFS/IndexedDB recovery	将所有后续 family runner 统一接入同一 revision/generation/store
P2 核心建模闭环	5/5 done	open/context、transform/hierarchy、mesh edit、双 viewport、open-edit-undo-redo-save-reopen	将已有 P2 证据作为 family regression，不重复实现基础 writer
P3 Authoring/IO	5/5 done	material/UV、animation、rig/skin、GLB round-trip、library append/link/override	补齐各 family 的统一 WASM mutation receipt 和 Chromium 生产证据
P4 高级本地切片	4/4 done	modifier、Geometry Nodes/shader、sculpt/non-mesh/paint、simulation cache	将能力边界、预算和 recovery 结果汇入 capability ledger
P5 Render/Server	3/3 done	render routing、media recovery、server job binding	保持 local/server/excluded 分类，不把 server 结果当作本地 parity
P6 安全/发布	3/3 done	default-deny scripting、故障矩阵、offline/CI/SBOM/rollback	修复构建环境 receipt 的可复现路径，避免旧工作区依赖
P7 差距程序	P7-001/P7-002 done，P7-003 blocked	15 family、45 原子行为任务、release gate；9/45 Chromium receipt 已绑定	剩余 36 项 WASM mutation/persistence/Chromium 证据和 M12 provenance
Quick CI	READY	7/7 lane，128 个 unit 文件隔离执行	每次 capability 合并继续作为必需回归，不重引入单进程 OOM
M12 历史证据	BLOCKED_SOURCE_LOST	82 条、42 路径 drift ledger；Git-history snapshot 恢复 22 条，历史文件保持不变	取得剩余 immutable snapshot 或签名 artifact 后只读重建 provenance

9. 不重复开发的模块所有权

所有后续工作先按以下所有权表复用；除非现有接口无法表达新行为，否则不创建第二套协议、store、runner 或 comparator。

能力	唯一生产入口	复用的现有证据/测试	允许新增的最小内容
文件读取和 SceneIR	web_engine_blend_reader.cpp、web/protocol/scene-ir.ts	P1/P2/P7 reader receipts	新字段的 typed parser、fallback、schema negative
Main mutation/history	web/protocol/corrective-main-transaction.ts 与现有 Main state	P1-003、P2-002、P2-005	一个 bounded command 和对应 transaction case
Mesh	corrective-mesh-command.ts、mesh delta comparator	C5 Mesh、P2-003	新拓扑/attribute case，不复制 transaction
Modifier	corrective-modifier-command.ts	C5 Modifier、P4-001	一个声明参数或 apply slice
Asset/library	corrective-asset-catalog-command.ts 与 library protocols	C5 Asset、P3-005、M12 library receipts	新 ownership/reload case，不重写 catalog schema
渲染与节点	render routing、shader/geometry-node protocols	P4-002、P5-001、M12 format receipts	只添加 allowlist/预算条目
Worker/存储/recovery	runtime lifecycle、OPFS/IndexedDB journal	P1-004/P1-005、P4-004、P6-002	新 fault injection 或资源计数，不新建 recovery store
CI/release	run-ci-lane.mjs、release checkers、manifest	P6-003、quick report	新 lane 仅在现有 lane 无法表达时增加

禁止事项：为同一行为同时新增一个 Web protocol 和一个 corrective protocol；为同一 family 同时维护手工 expected JSON 和 generator 产物；用 UI 像素相似度替代 Main/SceneIR 语义比较。

10. 统一整合数据流

所有能力证据按同一条数据流进入 ledger，任何环节缺失都不能提升 parity level：

Blender fixture/generator
        |
        +--> desktop checker --> canonical semantic report
        |
        +--> WASM reader --> SceneIR snapshot --> Main bounded mutation
                                      |
                                      +--> save/reopen + stable-ID/hash report
                                      |
                                      +--> Chromium production interaction
                                                        |
                                                        +--> negative/recovery report
                                                                    |
                                                                    +--> manifest/status/ledger

整合时只比较 canonical semantic state：stable ID、Main revision、delta、拓扑/属性、资源 hash、错误码和 save/reopen state。.blend 原始字节只用于来源完整性和 fixture 保护，不把 Blender 进程指针字节误当成业务差异。

生成器规则：首次 fixture 生成可以写入目标；验证重跑必须保留已存在目标。P7-003 已实现这一规则，后续 generator 统一采用同一约定，避免重复触发二进制 hash drift。

11. 队列整合策略

当前 P7-003 是 release gate，不是新的功能 family。它在 nextTask=null 时必须停留在 blocked；不得从历史文档猜测 successor，也不得把 P7-003 改成一个批量实现任务。

队列重新打开的唯一条件：

1. P7-003 依赖的 release receipt、fixture、generator、reports、status、task-context 的 SHA 全部通过 handoff。
2. 由新的机器 manifest 明确给出 successor；手工修改 nextTask 无效。
3. successor 只领取一个 family 的一个行为，先完成 desktopPositive，再完成 wasmMutation，最后完成 saveReopenExact。
4. 同一 family 的 Chromium、negative 和 recovery 证据作为该行为的必需门，不另起重复功能实现任务。
5. family 完成后只更新 parity map 和 regression coverage，不修改已完成任务的历史 manifest。

如果现有 45 项原子队列的实现类别与 capability matrix 不一致，先新增一个“分类修正”证据任务，由 generator 重新输出 READ_COMPATIBILITY/EXCLUDED/SERVER_EXACT；不能直接把 metadata-only 或 negative-only 记录标成 feature parity。

12. 分阶段整合安排

I. 基础环境和证据入口

• 重新配置或封装 Blender desktop 运行环境，消除 /home/mes123456/working 的隐式 RUNPATH；记录 Blender source/build、Emscripten、Node、Chromium 和依赖库 receipt。
• 抽出一个 family runner 外壳，参数只包含 fixture、行为 catalog、desktop checker、WASM command、Chromium case 和负例集合。
• comparator 统一输出 canonical JSON 和 SHA；命令输出写入任务 evidence 目录，manifest 只绑定最终构件。

II. 复用现有 C5 正向链路

• 先整合 Mesh、Modifier、Asset 三个已有 pilot，不改它们的协议语义。
• 对每个 pilot 补齐同一个证据形状：desktop state、WASM/Main revision、undo/redo、save/reopen、Chromium result、malformed/stale/missing/budget negatives。
• 三个 pilot 只能在证据字段齐全后提升为 capability ledger 的正向候选；旧 C5/M12 SHA 只读消费。

III. 按收益和风险推进 family

• 首批：MESH_EDITING、OBJECT_OPERATIONS、MEDIA_IO，因为已有 P2/P3/C5 可复用且能覆盖大量 legacy regression。
• 第二批：MODIFIER_SYSTEM、NODES_GRAPH、RIG_ANIMATION、MATERIAL_RENDER。
• 第三批：SIMULATION、SCULPT_PAINT、CORE_SCENE_GRAPH、CORE_MESH。
• 最后处理 UI_EDITOR、CORE_DNA_RNA、OTHER_OPERATOR、CORE_OBJECT：优先做 read-compatibility 或 explicit excluded 分类，只有存在真实 Main writer 时才创建 mutation task。

每个 family 只选择一个最小可观察行为作为实现入口，已覆盖的 P2/P3/P4/P5 行为直接引用 regression receipt，不重复造 fixture 或 command。

IV. M12 provenance 并行轨道

• 接收 immutable repository snapshot、签名 artifact archive 或 CI artifact store 原件后，先只读计算原始 SHA。
• 可先从本仓库 Git 历史提取精确匹配项：node tools/web/build-m12-git-snapshot.mjs，再执行 intake；该过程不读取或重写当前工作树。
• 统一入口：node tools/web/intake-m12-immutable-snapshot.mjs --write；收到快照时追加 --snapshot <目录或 snapshot-manifest.json>，工具只读校验并输出 tests/golden/corrective/rehydration/M12-provenance-intake.json。
• 运行三方比较：original manifest、source snapshot、current worktree。
• 可复原项生成 PROVENANCE_RESTORED corrective evidence，无法复原项继续保留 BLOCKED_SOURCE_LOST。
• provenance 修复不得修改 M12 历史 manifest，不得删除 drift entry，也不得覆盖当前工作树文件。

V. Release closure

• 45 项行为证据和 M12 provenance 都满足后，重新生成 parity map、known limitations 和 release decision。
• 依次运行 quick、Chromium、release、offline、SBOM、rollback 及 protected-hash gates。
• 只有 FEATURE_PARITY、READ_COMPATIBILITY、SERVER_EXACT、EXCLUDED、BLOCKED 的数量和原因都可从机器证据重算时，才允许 release READY。

13. 每个整合任务的交付模板

<family>/<behavior>/
  fixture.blend or source fixture reference
  generator.py or generator.mjs
  desktop-report.json
  wasm-main-report.json
  chromium-report.json (when production interaction is involved)
  persistence-report.json
  negative-report.json
  manifest.json
  status.md
  task-context.json

交付前固定运行：focused command、determinism check、desktop/WASM comparator、save/reopen、negative matrix、manifest hash、context governance、typecheck/lint 和 quick CI。任何一个命令失败都保留 in_progress/blocked，不创建 successor。

14. 项目级完成判定

项目整合完成需要同时满足：

• P0-P6 的已有生产实现全部由同一 SceneIR/Main/Worker/storage/CI 入口消费；没有重复协议或第二套状态源。
• 已实现能力、只读兼容能力、server/excluded 能力和真正未完成能力可以从 ledger 自动区分。
• P7 inventory 的 6,900 条记录均有稳定 family/implementation class/证据映射；不要求每条记录都拥有独立 writer。
• 45 项原子行为已完成，或明确标记为 READ_COMPATIBILITY、SERVER_EXACT、EXCLUDED、BLOCKED 并绑定原因。
• Chromium 是唯一浏览器验收入口，quick CI 保持稳定，不再出现 Node exit 134。
• M12 可复原 SHA 有权威来源；不可复原项继续显式 blocked。
• release gate 可以只从 manifest、status、ledger 和 immutable source/build hash 重新计算，无需人工解释或历史重写。