回退完美像素原尺寸恢复

直接持久化逻辑分辨率 PNG 并使用最终实际尺寸
升级手动完美像素算法版本并拦截跨版本重放孤儿对象
补充非整除网格和前端权威对账回归测试
同步完美像素契约、决策记录与排障说明

docs/project-memory/shared-memory/decision-log.md

@@ -6896,3 +6896,13 @@
 - 一致性：`start-tauri-dev.mjs` 是端口选择权威，最终端口通过 Tauri CLI `--config` 覆盖 `build.devUrl`，通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，并通过 Vite CLI `--port` 启动严格监听。父启动器选定端口后，子启动器只允许严格使用同一端口，配套后端漂移必须跳过该预留端口，竞态占用必须失败关闭。
 - 安全边界：动态端口不恢复旧 Vite 复用。无法证明 worktree 归属的监听器仍不复用、不主动终止；同用户多 worktree 通过段内漂移并行，不通过共享未知服务并行。
 - 验证：公共端口映射、Linux 默认槽位与段内漂移、非 Linux 兼容漂移、Tauri 动态配置、启动前预检、进程树收束、AGC typecheck / 配置门禁、编码检查和差异检查必须通过。
+
+## 2026-08-10 完美像素最终持久化逻辑分辨率 PNG
+
+- 背景：SpriteFusion Pixel Snapper 上游在网格采样后直接输出 `(列切线数 - 1) × (行切线数 - 1)` 的逻辑图，每个检测单元恰好对应一个输出像素。Genarrative 首版在此后增加了 nearest 输入尺寸恢复；当输入宽高不能被逻辑列数、行数整除时，最近邻只能把同一逻辑像素分配到 `floor / ceil` 数量不等的目标列或行，最终物理像素块宽窄不一。已有 `128 → 64` 的整数倍测试没有覆盖该问题。
+- 决策：生成请求勾选 `style="pixelArt"` 与已有图片手动 `POST /api/editor/images/pixel-art-snaps` 共用同一输出语义：snapper 直接编码并持久化唯一的逻辑分辨率 PNG，不再 nearest 恢复到源图、RGBA 输入、业务交付或 generation dialog 占位尺寸。成功输出宽高固定为 `(columns.len() - 1) × (rows.len() - 1)`，允许与输入、交付和占位尺寸不同；响应、project resource、账号素材和结果 layer 一律记录最终 PNG 的实际宽高。
+- 保留边界：普通图片和角色在规整前执行的 Lanczos 交付尺寸归一继续保留；角色 / 图标的平底网格分析源与透明 RGBA 采样源仍必须同尺寸，Alpha 覆盖、Alpha 加权 RGB、二值 Alpha、P30 步长估算、确定性采样、输入上限、deadline、strict 无网格拒绝和失败降级尺寸守卫全部不变。这些约束保护输入坐标系、资源安全或失败路径，不构成成功输出与输入同尺寸的承诺。
+- 持久化边界：数量增量保持不变。普通图片只保存一张最终逻辑主图；角色保留一张 provider 原图与一张最终透明逻辑主图；图标保留一张 provider 原图、一张最终透明逻辑图集和原有成功切片；手动完美像素只保存一张最终逻辑 PNG。不得另外保存输入尺寸恢复版、像素化前后双份主图、预览、诊断或报告，不修改 asset kind、队列类型、数据库 schema、路由或请求 / 响应字段形状。
+- 跨版本重放：手动入口算法指纹升为 `perfect-pixel-v2`。同一稳定 operation 已有结果时，candidate object key 相同才继续既有 exact replay；key 不同或既有稳定资源缺 key 时，必须在 preflight 与 OSS PUT 前返回 `409 + operationResultAlreadyExists=true`，由客户端 GET 权威项目收口，不得冒充本次请求已经设置 `resultPersistenceStarted`。preflight 到最终提交之间仍无数据库 reservation，滚动发布必须排空旧算法实例，不能把该护栏解释为消除了并发 TOCTOU。
+- 历史边界：本条覆盖 2026-07-28 首发决策中“逻辑结果 nearest 恢复交付尺寸 / 逻辑图不持久化”和 2026-07-30 手动入口中“右侧新增同尺寸 PNG / 不保存逻辑低分辨率图”的旧口径；旧条目作为历史记录保留，不回写改造。
+- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

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

@@ -4470,3 +4470,11 @@
 - 原因：`normalize_generated_asset_folder_id` 只处理 `project`、旧 `folder-*` 和默认目录 ID 的兼容映射，不读取 SpacetimeDB；真正的 `require_owned_asset_folder` 位于生成结果持久化末端。把“失败会退款”误当成副作用补偿，漏掉退款不能撤销 provider 请求与 OSS PUT。
 - 处理：所有付费编辑器生成在队列 enqueue 前和 worker / inline 执行前复用只读 `preflight_editor_generation_target_and_return`，按认证 owner 校验可选项目及归一化目录；读取失败和归属不匹配一律失败关闭。helper 返回 canonical 项目与目录并覆写后续入队 / worker / 原子准备使用的 payload，不能校验 trim 后的项目却持久化原始空白值。角色图片、角色动作、图标 spritesheet 与 UI 提取省略目录时按实际默认目录预检；默认目录允许尚未创建，自定义目录必须存在且 owned。预检不替代最终 procedure 复验，也不保证跨外部调用的目录锁定。
 - 验证：源码顺序回归必须覆盖图片生成、图片修改、图标 spritesheet、UI 设计图提取、视频、角色动作、SFX 与 BGM 的 enqueue / direct 两层，证明纯本地格式和 `data:` / `blob:` 稳定引用门禁先执行，canonical target 在预检后写回 payload，远端引用解析、generation input rebuild、扣费、入队、provider 与 OSS 均留在预检之后；模块侧扫描证明预检只调用 runtime identity、项目、目录只读校验且不含 insert / update / delete，并覆盖带空白项目、`project`、旧 `folder-*`、默认目录 ID、自定义目录与 `None` 归一化。
+
+## 非整除 nearest 会让逻辑像素块宽窄不一（2026-08-10）
+
+- 现象：像素规整后的图片虽然保持了源图宽高，放大观察却能看到相邻逻辑块占用的物理列数或行数不同，表现为部分块更宽、部分块更窄；整数倍样例看起来正常，换一张网格数不能整除输入尺寸的图才复现。
+- 原因：逻辑图宽高为检测后的列数、行数。把 `C × R` 的逻辑图用 nearest 恢复到 `W × H` 时，只要 `W % C != 0` 或 `H % R != 0`，目标栅格就只能在不同逻辑像素间分配 `floor / ceil` 数量的列或行；nearest 能避免混色，却不能让非整数缩放后的块严格等大。只用 `128 × 128 → 64 × 64 → 128 × 128` 这类整数倍测试会掩盖问题。
+- 处理：最终资产直接编码一格一像素的逻辑分辨率 PNG，不再执行输入 / 交付尺寸 nearest 恢复，也不要求成功输出与源图或占位尺寸相等。普通图片和角色的前置 Lanczos 交付尺寸归一仍用于确定检测输入；平底网格源与透明 RGBA 源仍必须同尺寸，不能把“取消输出同尺寸”误解为放开两个内部采样坐标系。
+- 验证：使用至少一组逻辑列数或行数不能整除输入尺寸的图片，断言输出宽高等于切线数减一而不是输入宽高；同时核对响应、project resource、账号素材和结果 layer 都记录最终 PNG 实际尺寸，且只持久化一个最终 PNG，没有输入尺寸恢复版、诊断图或额外资源。失败降级用例继续验证 Alpha / 交付尺寸守卫，不应因成功输出改为逻辑分辨率而删除。
+- 关联：`server-rs/crates/platform-image/src/pixel_art_snapper.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。