修复 migration blocker。

- preview MP4 规划为 video，且 layout 是普通 video：跳过动作清理。
- layout 明确是 image-sequence 却指向 video：继续 blocker。
- 原始动作资源本身规划失败：继续 blocker，不静默跳过。
- 正式图片序列：正常清理 legacy layout 字段。
- apply 仍要求前置 scope 已物理落库。

docs/project-memory/shared-memory/pitfalls.md

@@ -3933,7 +3933,7 @@
 - 原因：`editor_asset.image_src` 只指向首帧；若 worker 把完整帧集塞进 `generation_inputs_json`，素材 DTO、用户输入清洗或画布布局任一层丢字段，就会退化成 PNG。再增加一个 `mediaType` 只能掩盖结果字段没有落到正式资源的问题。
 - 处理：worker 只把完整帧集与图片序列毫秒时长写入 `editor_project_resource` / `editor_asset` 的 `image_sequence_frames_json`、`image_sequence_duration_ms`；数组位置是唯一帧序，不保存 `frameIndex`，帧数和 FPS 均按需派生。`assetKind=character-animation` 决定序列渲染。素材映射、单项下载和拖回画布只读取这两个正式字段，项目 resource 在保存 / 刷新后继续作为主真相；动作 layout 只保留资源引用和 placement，不再复制正式媒体结果。账号素材提交精选审核时，`editor_showcase_asset` 必须冻结复制相同字段，公开 read model 只返回正式字段。外部 helper 只调用一次动作生成接口并直接使用响应 `resource` / `asset`。
 - 画布回填：角色动作会形成“原角色资源 → 预览视频资源 → 最终序列资源”的血缘链。生成响应必须返回已经持久化的最终 resource，前端图层直接使用其 `resourceId`；不能继续构造 `local-resource-character-animation-*`，否则 `appendCanvasLayersWithResources` 会再次创建重复资源。新图层的 `sourceResourceId` 同时使用最终 resource 的直接来源（预览视频 resource），不能继续沿用请求中的原角色 resource；否则结构化保存会在已生成并计费后因血缘不一致而拒绝。修复时只替换资源关联与血缘字段，不要顺带把动作图层显示尺寸从生成占位尺寸改成原始帧分辨率。
-- 历史处理：不要再在 read mapper 增加 `generationInputs` / layout fallback。使用 migration operator procedure 按 `asset → project-resource → showcase → canvas` 迁移；只有动作身份已由 `assetKind`、正式字段、嵌套 `characterAnimation` 或权威对象证明后，才解释顶层 `frames/durationSeconds`，否则会把无关任意 JSON 误分类。同一 task 可能同时存在误标为动作的预览 MP4 和最终首帧 PNG，候选查找必须先按权威对象类型做计划态分类，排除视频并要求唯一正式图片序列，不能按原始 `assetKind` 计数。正式序列还要逐帧用稳定对象路径匹配同 owner / task 的已登记图片对象并补齐 `objectKey/assetObjectId`。迁移不得验证 layout 复制的 `sourceResourceId`：历史 layer 可能仍指向原角色，而最终素材已指向预览资源；清理副本后采用最终素材的 DB 血缘即可，新生成链路仍保持严格校验。正式与旧版结果冲突、候选为零或多个均形成 blocker。普通 layer 顶层 `mediaType` 在迁移和响应清洗时删除，但嵌套生成参考的 `mediaType` 保留。
+- 历史处理：不要再在 read mapper 增加 `generationInputs` / layout fallback。使用 migration operator procedure 按 `asset → project-resource → showcase → canvas` 迁移；只有动作身份已由 `assetKind`、正式字段、嵌套 `characterAnimation` 或权威对象证明后，才解释顶层 `frames/durationSeconds`，否则会把无关任意 JSON 误分类。同一 task 可能同时存在误标为动作的预览 MP4 和最终首帧 PNG，候选查找必须先按权威对象类型做计划态分类，排除视频并要求唯一正式图片序列，不能按原始 `assetKind` 计数。账号素材仍有旧帧、但后来拖入画布的 project-resource 只剩清洗后 `fields/references` 时，project-resource dry-run 必须按同 owner / task / 首帧对象精确消费 asset 计划态结果；apply 仍要求前置 asset scope 已物理完成。canvas 判断已有 resource 是否为动作时也必须消费 project-resource 的计划态类型：旧库误标为动作、但权威对象证明为 preview MP4 且 layout 本身是 video 的图层直接跳过动作清理；layout 明确为 `image-sequence` 却指向该视频时继续形成 blocker，资源规划本身有 blocker 时也不得静默跳过。正式序列还要逐帧用稳定对象路径匹配同 owner / task 的已登记图片对象并补齐 `objectKey/assetObjectId`。迁移不得验证 layout 复制的 `sourceResourceId`：历史 layer 可能仍指向原角色，而最终素材已指向预览资源；清理副本后采用最终素材的 DB 血缘即可，新生成链路仍保持严格校验。正式与旧版结果冲突、候选为零或多个均形成 blocker；脚本诊断应直接打印 scope、ID、原因、owner/project/task、对象身份和来源资源，不能只报 blocker ID。普通 layer 顶层 `mediaType` 在迁移和响应清洗时删除，但嵌套生成参考的 `mediaType` 保留。
 - 新写入与验证：动作 `generationInputs` 出现 `characterAnimation/frames/previewVideoPath/frameCount/fps/durationSeconds/screenColorHex`，或正式帧出现 `frameIndex`，HTTP 与 storage 双层拒绝；其它 asset kind 的任意 JSON 不受该动作门禁影响。测试覆盖两种历史 JSON、无关顶层同名字段、正式/旧版相等与冲突、可选帧引用合并、screen color 和 frameIndex 清理、预览 MP4 重分类、幂等、blocker/hash apply、画布 placement 清理/资源补建、正式字段缺失失败关闭和 helper 单请求。
 
 ## 图片序列时长不要复用通用媒体秒数

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -433,7 +433,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - 角色动作 worker 在透明帧全部持久化后创建最终项目资源与账号素材，并写入帧数组与 `image_sequence_duration_ms`；生成响应可继续返回请求 / 结果层面的 `frameCount`、`fps`、`durationSeconds`，但它们不是持久化真相。预览视频仍作为独立 `asset_kind = video` 中间素材保留并承担生成成本，最终派生素材成本为 0。
 - `create_editor_project_resource`、`create_editor_asset` 和同源资源回填必须在 procedure/storage 边界验证最终状态：`asset_kind = character-animation` 必须同时包含至少两帧的有效数组和大于 0 的 `image_sequence_duration_ms`；其他类别不得携带任一图片序列字段。同源资源只允许从 `None` 单调补齐字段，非空冲突失败关闭，补写后的 `updated_at` 不得早于既有时间。
 - `generation_inputs_json` 只保存用户生成 / 重放输入，例如 `fields`、`references`、`artSpec`；动作输出和内部背景决策色不得再写入该 JSON。背景决策审计继续走独立审计链路。
-- 存量 `generation_inputs_json.characterAnimation`、已确认动作行的 helper 顶层 `frames/previewVideoPath/frameCount/fps/durationSeconds`、`screenColorHex`、正式帧中的 `frameIndex` 和误标动作预览 MP4，统一由 migration operator procedure `normalize_editor_character_animation_metadata_and_return` 分 `asset → project-resource → showcase → canvas` 四个 scope 迁移。顶层旧字段只有在 `asset_kind=character-animation`、正式序列字段、嵌套 `characterAnimation` 或权威 `asset_object` 已证明该行属于角色动作时才解释，普通图片 / 视频任意 JSON 中同名字段保持原样。迁移在计划态先把同 task 的已验证预览 MP4 重分类为 `video`，只有能形成正式图片序列的候选才可用于补建 `local-*` 动作资源；每一帧还必须按首帧 bucket 下的精确对象路径匹配同 owner、同 task、`editor_character_animation` 且为图片的 `asset_object`，并从登记对象补齐 `objectKey/assetObjectId`。canvas layout 复制的 `sourceResourceId` 不参与迁移血缘校验，补建资源只采用最终账号素材的 DB 血缘；新生成链路仍严格校验直接来源。正式与旧版帧或时长冲突、最终候选为零或多于一个、帧对象无法精确验证和缺失正式帧集均作为 blocker，整批拒绝 apply。
+- 存量 `generation_inputs_json.characterAnimation`、已确认动作行的 helper 顶层 `frames/previewVideoPath/frameCount/fps/durationSeconds`、`screenColorHex`、正式帧中的 `frameIndex` 和误标动作预览 MP4，统一由 migration operator procedure `normalize_editor_character_animation_metadata_and_return` 分 `asset → project-resource → showcase → canvas` 四个 scope 迁移。顶层旧字段只有在 `asset_kind=character-animation`、正式序列字段、嵌套 `characterAnimation` 或权威 `asset_object` 已证明该行属于角色动作时才解释，普通图片 / 视频任意 JSON 中同名字段保持原样。迁移在计划态先把同 task 的已验证预览 MP4 重分类为 `video`，只有能形成正式图片序列的候选才可用于后续 scope；project-resource 自身缺帧但能用同 owner、同 task、同首帧 `assetObjectId/objectKey` 精确定位唯一最终账号素材时，dry-run 可消费 asset 的计划态正式序列，apply 仍要求 asset scope 已物理完成。canvas 同样按 project-resource 的计划态类型分类：旧库误标为动作、但规划后为 `video` 且 layout 未声明动作的 preview 图层不参与动作副本清理；layout 明确声明动作却指向该视频，或原始动作资源的规划存在 blocker，继续失败关闭。每一帧必须按首帧 bucket 下的精确对象路径匹配同 owner、同 task、`editor_character_animation` 且为图片的 `asset_object`，并从登记对象补齐 `objectKey/assetObjectId`。canvas layout 复制的 `sourceResourceId` 不参与迁移血缘校验，补建资源只采用最终账号素材的 DB 血缘；新生成链路仍严格校验直接来源。正式与旧版帧或时长冲突、最终候选为零或多于一个、帧对象无法精确验证和缺失正式帧集均作为 blocker，整批拒绝 apply；procedure 同时返回不含生成输入正文的 blocker 完整诊断，包含 scope、ID、原因、owner、project、task、对象身份和来源资源。
 - 运维入口固定为 `node scripts/spacetime-normalize-editor-character-actions.mjs --database <database> --server-url <url>`；默认全量 dry-run，`--apply` 时每批先 dry-run，再用返回的 batch SHA-256 写入，四个 scope 完成后从头执行零匹配 / 零 blocker 复核。迁移完成后 api-server、后台、前端和外部 helper 只读取正式字段，不再包含 legacy fallback。新建动作资源 / 素材若在 `generationInputs` 提交旧运行字段，或正式帧包含 `frameIndex`，api-server 与 SpacetimeDB storage 均失败关闭；其它素材的任意生成输入不受动作专属门禁影响。
 - 普通画布 layer 的持久化和前端响应不包含顶层 `mediaType`；渲染类型只由资源 / 素材 `assetKind` 在前端派生。`generationInputs.references[*].mediaType` 是生成参考输入契约，不属于画布 layer legacy 字段，迁移和响应清洗不得递归删除。
 

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -92,7 +92,7 @@ BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去
 
 外部生成任务摘要投影与历史 payload 维护使用 `npm run spacetime:external-generation:maintain -- ...`，且只能由已授权 migration operator 的 SpacetimeDB CLI 登录态执行。脚本默认 dry-run、每次只处理一批，绝不自动循环全表；`--apply` 才写入。先发布包含 `external_generation_job_summary` 与 cursor 索引的 SpacetimeDB 模块，在维护模式内对事故时间以前的编辑器终态任务执行小批 dry-run，例如 `npm run spacetime:external-generation:maintain -- --database <database> --server-url <url> --limit 5 --completed-before-micros <micros>`；核对 `matched_count`、`before_bytes`、`after_bytes` 和 `inline_media_count` 后，保持本批输入 cursor 不变并追加 `--apply` 重跑同一批，即使最后一批 `has_more = false`，只要 dry-run 仍有 `matched_count` / `selected_count` 也必须 apply；只有 apply 成功后才使用它返回的 `next_cursor_job_id` 继续。B-tree cursor 的选择阶段最多反序列化 `limit + 1` 行，apply 会再按主键逐条读取选中行但不会同时保留整批 payload；如怀疑存在单行异常巨型历史 JSON，先用 `--limit 1`。payload 压缩硬限制 `source_module = editor-canvas`；终态压缩完成后，用 `--backfill-summaries` 先 dry-run、再 `--apply` 分批补齐仍缺失的活动任务或无内联媒体历史任务摘要，直到 `has_more = false`，最后再切换使用 summary procedure 的 api-server。Stdb 构建 artifact 和完整 release 包都必须包含 `scripts/spacetime-maintain-external-generation-jobs.mjs` 与 `scripts/spacetime-migration-common.mjs`。首次上线不得让 Full Build 从 Stdb 自动直落 API：`STDB_API_ROLLOUT_MODE` 默认 fail-closed 为 `pause-after-stdb`，必须填写受限的 `STDB_API_ROLLOUT_APPROVERS`；Stdb Publish 通过 `KEEP_MAINTENANCE_MODE` 保持维护文件并停止旧 API/controller/worker，暂停点最多等待 4 小时，完成上述维护并确认无后续批次后才由指定审批人放行 API。定时构建缺少审批人时必须在发布前失败，不能静默退回 `normal`；也可分开运行 Stdb publish、维护、API deploy 三个受控 Job。任一批次都不得处理 pending / running payload；不要用 runtime writer、bootstrap secret 或匿名 identity 代替 migration operator，也不要在未核对 dry-run 时直接 apply。
 
-角色动作正式字段收口使用 `node scripts/spacetime-normalize-editor-character-actions.mjs --database <database> --server-url <url>`，且同样只能由已授权 migration operator 执行。必须先发布包含 normalization cursor 索引和 `normalize_editor_character_animation_metadata_and_return` 的 SpacetimeDB 模块，在 API / worker 仍处于维护模式时先运行默认全量 dry-run；脚本固定按 `asset → project-resource → showcase → canvas` 扫描，普通 scope 每批最多 25 行，canvas 每批最多 5 行。全量 dry-run 会在不写库的情况下把前置 scope 的计划结果投影给 canvas 检查，因此同 task 的误标预览 MP4 会先按权威视频对象排除，最终图片序列会逐帧核对并补齐精确 `asset_object` 身份；apply 时仍要求前置 scope 已按顺序物理完成。历史 canvas 复制的 `sourceResourceId` 不是迁移证据，不要因它仍指向原角色而手工改库，补建资源会采用最终账号素材的 DB 血缘。出现 blocker 时先按输出 ID 区分最终候选为零 / 多个、正式与旧版冲突、帧对象不匹配或缺失资源，不得跳过 scope；确认 dry-run 后追加 `--apply`，脚本会对每批重新 dry-run、携带该批 SHA-256 apply，并在最后从头要求四个 scope 均为零匹配、零 blocker。只有该复核通过后才发布移除 action fallback 的 API / Web。Stdb build artifact 和完整 release 包必须同时包含 `scripts/spacetime-normalize-editor-character-actions.mjs` 与 `scripts/spacetime-migration-common.mjs`。本地切换分支时若要避免 dev publish 因 schema 冲突使用 `-c=on-conflict` 清库，启动命令必须追加 `--preserve-database`，让冲突直接失败。
+角色动作正式字段收口使用 `node scripts/spacetime-normalize-editor-character-actions.mjs --database <database> --server-url <url>`，且同样只能由已授权 migration operator 执行。必须先发布包含 normalization cursor 索引和 `normalize_editor_character_animation_metadata_and_return` 的 SpacetimeDB 模块，在 API / worker 仍处于维护模式时先运行默认全量 dry-run；脚本固定按 `asset → project-resource → showcase → canvas` 扫描，普通 scope 每批最多 25 行，canvas 每批最多 5 行。全量 dry-run 会在不写库的情况下把 asset 计划结果投影给同 owner / task / 首帧对象精确匹配的 project-resource，再把前置 scope 的计划结果投影给 canvas 检查；因此同 task 的误标预览 MP4 会先按权威视频对象排除，最终图片序列会逐帧核对并补齐精确 `asset_object` 身份。canvas 中仍引用误标 preview resource 的普通 video layer 会按 project-resource 计划态 `video` 跳过，只有 layout 明确声明动作却指向视频，或资源规划本身失败时才形成 blocker。apply 时仍要求前置 scope 已按顺序物理完成，不能跳过 asset 直接让 project-resource 借未落库结果。历史 canvas 复制的 `sourceResourceId` 不是迁移证据，不要因它仍指向原角色而手工改库，补建资源会采用最终账号素材的 DB 血缘。出现 blocker 时脚本会打印 ID、原因、owner、project、task、对象身份和来源资源；先据此区分最终候选为零 / 多个、正式与旧版冲突、帧对象不匹配或缺失资源，不得跳过 scope。确认 dry-run 后追加 `--apply`，脚本会对每批重新 dry-run、携带该批 SHA-256 apply，并在最后从头要求四个 scope 均为零匹配、零 blocker。只有该复核通过后才发布移除 action fallback 的 API / Web。Stdb build artifact 和完整 release 包必须同时包含 `scripts/spacetime-normalize-editor-character-actions.mjs` 与 `scripts/spacetime-migration-common.mjs`。本地切换分支时若要避免 dev publish 因 schema 冲突使用 `-c=on-conflict` 清库，启动命令必须追加 `--preserve-database`，让冲突直接失败。
 
 自 2026-07-11 起，`Genarrative-Full-Build-And-Deploy` 的每日 04:00 timer 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate。三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，不得依赖下游 Job 默认值或提前各自发布；统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。上文“定时构建缺少审批人时失败”的旧口径不再作为当前 dev 定时发布行为。