合并 origin/master

合入 master 的钱包退款 outbox、拼图后台编译互斥与公开链路更新

保留当前分支外部生成 worker 队列语义，并对齐拼图首图 claim 释放顺序

.hermes/shared-memory/decision-log.md

@@ -296,7 +296,7 @@
 - 背景：Match3D、SquareHole、Puzzle、Jump Hop 等 runtime client 重复手写 path segment 编码、JSON header / body、runtime guest token、auth options 和 retry options，新增玩法容易遗漏同一请求骨架。
 - 决策：新增 `src/services/runtimeRequest.ts`，以 `buildRuntimeApiPath` 统一 runtime path 编码，以 `requestRuntimeJson` 统一 JSON 请求、runtime guest auth 和 retry 合并。Match3D 与 SquareHole runtime client 已先迁移，保留原导出函数名、错误文案、返回契约和重试常量。
 - 追加决策：Big Fish 与 Bark Battle runtime client 也迁入 `runtimeRequest.ts`；玩法专属 payload 归一化（如 Bark Battle start / finish 自动补 `workId`、`runId`）仍留在各玩法 client，通用 Module 只承接请求骨架。
-- 追加决策：Puzzle 的 start / get / swap / drag / next-level / leaderboard 与 Jump Hop 的 start / jump / restart 也迁入 `runtimeRequest.ts`；Puzzle `pause` 与 `props` 仍保留原账号态 auth options，不直接接入 runtime guest auth。
+- 追加决策：Puzzle 的 start / get / swap / drag / next-level / leaderboard / pause / props 与 Jump Hop 的 start / jump / restart 也迁入 `runtimeRequest.ts`；只要调用方传入 Runtime Guest Token，所有正式 runtime 请求都统一带局部 Authorization、`skipAuth` 与 `skipRefresh`。
 - 追加决策：Wooden Fish 的 start / checkpoint / finish 与 Visual Novel 的 gallery / run / history / regenerate JSON 请求也迁入 `runtimeRequest.ts`；Wooden Fish 的 `clientEventId` 生成仍留在木鱼 client，Visual Novel start 因 `timeoutMs`、SSE 因流式 `fetchWithApiAuth` 仍暂留原实现。
 - 影响范围：`src/services/runtimeRequest.ts`、Match3D / SquareHole / Big Fish / Bark Battle / Puzzle / Jump Hop / Wooden Fish / Visual Novel runtime client。
 - 验证方式：`npm run test -- src/services/runtimeRequest.test.ts src/services/recommendedRuntimeGuestLaunch.test.ts src/services/match3d-runtime/match3dRuntimeAdapter.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
@@ -445,7 +445,7 @@
 ## 2026-05-25 抓大鹅运行态 HUD 收敛为拼图同款低遮挡样式
 
 - 背景：抓大鹅游玩阶段 UI 需要继续对齐拼图运行态的观感，同时移除右上角设置入口、灰白半透底板和显眼锅壳，让棋盘区域更专注。
-- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo.png` 产品 logo；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
+- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo-runtime-hud.webp` 产品 logo 小图；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
 - 影响范围：`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`、`src/index.css`、抓大鹅玩法链路文档。
 - 验证方式：运行态页面不再渲染“打开抓大鹅设置”，顶部仍显示关卡名和倒计时，底部槽位和道具按钮 class 中不含旧白底视觉；相关测试通过后保持该口径。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
@@ -1745,3 +1745,11 @@
 - 影响范围：`shared-contracts` 默认 spec、`module-runtime` 入口配置响应、`spacetime-module` 后台保存校验、后台入口开关页摘要和前端 fallback spec。
 - 验证方式：`GET /api/creation-entry/config` 中各玩法 `unifiedCreationSpec.title` 等于已保存契约内容；后台只修改入口名称时不应隐式改写已保存的统一创作页表头。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-11 资产计费边界改为 fail-closed 并补偿退款
+
+- 背景：图片 / 资产生成入口曾在钱包或 SpacetimeDB 预扣费连通性异常时允许继续生成，且失败后同步退款如果遇到 SpacetimeDB 短暂不可用缺少本地补偿；拼图首图后台任务还使用 api-server 进程内 HashSet 互斥，多实例下不能防重复。
+- 决策：暂不实现 token 限流。所有资产生成预扣费改为 fail-closed，预扣费失败直接返回错误；支持 retry 的计费 ledger id 统一包含 HTTP `request_id`，前端静默刷新重试复用同一个 `x-request-id`。生成失败后的退款先同步调用 SpacetimeDB，失败则写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。拼图首图后台生成互斥改为 SpacetimeDB `puzzle_background_compile_task` 表，使用 `task_id + request_id` 作为 claim id，释放时校验 claim id，避免旧任务误删新租约。
+- 影响范围：`api-server` 资产计费包裹、钱包退款补偿、拼图首图后台生成、`spacetime-module` 拼图 task 表、`spacetime-client` bindings/facade、前端 API request id 复用和后端架构文档。
+- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`node scripts/check-server-rs-ddd-boundaries.mjs`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml wallet_refund_outbox`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml asset_operation`、`npm run test -- src/services/apiClient.test.ts`、`npm run check:encoding`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

.hermes/shared-memory/pitfalls.md

@@ -1181,6 +1181,7 @@
 - 追加处理：generated 私有图片换签 `/api/assets/read-url` 也属于展示层后台请求；推荐页拼图运行态挂载后会立即解析封面图，若换签 401 触发全局鉴权事件，也会表现成“进入拼图作品后瞬间未登录”。资源换签失败只应让当前图片为空，不应清 token、广播 auth 事件或主动 refresh。
 - 追加处理：从推荐页点进公开拼图作品并启动完整运行态后，`startPuzzleRun`、通关自动 `submitPuzzleLeaderboard`、下一关 `advancePuzzleNextLevel` 和重开同样属于当前玩法局部同步；这些请求失败时只应留在拼图错误态，不应清 token 或广播 auth 事件。
 - 追加处理：通关后 `refreshSaveArchives()`、首屏 bootstrap 的个人看板/作品架/浏览历史读写也只是平台投影刷新，失败应显示局部错误，不能充当全局登录态判定。
+- 追加处理：未登录推荐页启动任一公开正式玩法时，`/api/runtime/*` 局内路由必须使用 `RuntimePrincipal`，前端通过 `PlatformEntryFlowShellImpl` 的统一 request options helper 给 start / checkpoint / finish / input / drop / click / restart / time-up / leaderboard / next-level 等动作透传 runtime guest token；公开 runtime detail 读取如跳一跳、敲木鱼必须显式 `skipAuth/skipRefresh`，匿名推荐流不能补读受保护创作详情，否则会在真正开局前打出 `/api/auth/refresh 401`。
 - 验证：`npm run test -- src/services/apiClient.test.ts src/services/assetReadUrlService.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation starts embedded puzzle"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle runtime uses frontend move merge logic and backend leaderboard"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle similar work keeps current run level progression"`。
 - 关联：`src/services/apiClient.ts`、`src/services/assetReadUrlService.ts`、`src/services/puzzle-runtime/puzzleRuntimeClient.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md`。
 
@@ -2221,3 +2222,11 @@
 - 待处理：将跳一跳生成改为后端任务化 / 可轮询真实阶段进度，按背景、返回按钮、图集、切片、持久化、写草稿分阶段落库；统一后端全局生成 deadline、VectorEngine 重试预算、前端等待窗口和失败态回写。超时后再次进入同一 session 应优先恢复正在运行或已完成的任务，不应重复生图。
 - 验证：模拟首张 image2 超长耗时或超时重试时，生成页应显示真实阶段和可恢复状态；前端请求超时不应把最终成功草稿标记为失败；刷新 `/creation/jump-hop/generating?sessionId=<id>` 后应能恢复到后端真实状态；同一 session 重试不得重复生成已完成阶段。
 - 关联：`src/services/jump-hop/jumpHopClient.ts`、`src/services/miniGameDraftGenerationProgress.ts`、`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/platform-image/src/vector_engine/client.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## SpacetimeDB 连接池租约必须有 Drop 兜底，acquire 不允许无界自旋
+
+- 现象：release 上 api-server 周期性出现全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 业务超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），`/healthz` 仍 200，只有重启能恢复，过若干小时复发。
+- 原因：旧 `PooledConnectionLease` 只能显式 `release_connection` 归还；HTTP 请求方在等待 StDB 回包期间断开时 handler future 被取消，permit 自动归还但槽位 `in_use` 永不复位。后续 acquire 在拿到 permit 后进入无界 `loop + yield_now` 扫描空闲槽位，泄漏积累到 pool_size 后整池挂死。
+- 处理：租约持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop` 统一复位槽位/归还连接；槽位改 `AtomicBool` CAS 抢占，删除自旋循环（持有 permit 必然命中空闲槽位）。任何新的"显式归还"资源在 async 取消语义下都要先想 Drop 兜底。
+- 验证：`cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（`dropped_lease_releases_slot_and_permit`、`acquire_times_out_at_pool_acquire_when_pool_is_busy`）。
+- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md`。

docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md

@@ -0,0 +1,40 @@
+# SpacetimeDB 连接池租约 Drop 兜底与取消安全
+
+- 日期：2026-06-11
+- 关联故障：release 环境 api-server 周期性全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），重启后临时恢复。
+- 涉及代码：`server-rs/crates/spacetime-client/src/lib.rs`
+
+## 故障根因
+
+修复前的连接池存在两个叠加缺陷：
+
+1. **租约没有 Drop 兜底**。`PooledConnectionLease` 只能通过显式 `release_connection` 归还。当 HTTP 请求方在等待 StDB 回包期间断开（前端超时、用户刷新、Nginx 截断），axum/hyper 会直接丢弃 handler future，租约被 Drop：permit 因 `OwnedSemaphorePermit` 自动归还，但槽位的 `in_use` 标记永远不会复位。
+2. **acquire 在槽位泄漏后永久空转**。后续请求拿到 permit 后进入 `loop { 扫描槽位; yield_now }`，找不到空闲槽位就无限自旋，且这段自旋不受 `procedure_timeout` 约束，自旋期间 permit 不归还。
+
+叠加效果：StDB 一旦变慢（请求占用连接接近 45 秒），客户端取消请求的概率大增，每次取消泄漏一个槽位并连带吞掉一个 permit；泄漏数量达到 `pool_size`（release 为 8）后，所有业务请求与健康检查全部在 `pool_acquire` 阶段 45 秒超时，服务表现为"连不上 StDB"，只有重启能恢复。
+
+## 本地复现
+
+不需要真实 SpacetimeDB，单元测试即可复现机制（位于 `spacetime-client` tests 模块）：
+
+- 修复前：将一个槽位置为 `in_use=true` 后调用 `acquire_connection_with_timeout(200ms)`，acquire 在 5 秒守护窗口内不返回（永久自旋），测试红。
+- `dropped_lease_releases_slot_and_permit`：模拟"请求被取消、租约未经 release 直接 Drop"，断言槽位与 permit 都被复位归还。
+- `acquire_times_out_at_pool_acquire_when_pool_is_busy`：池内 permit 全部被占用时，acquire 必须在超时窗口内返回 `PoolAcquire + Timeout`，不允许无限等待。
+
+## 修复方案
+
+1. `PooledConnectionSlot` 改为 `in_use: AtomicBool + connection: Mutex<Option<PooledConnection>>`，槽位占用标记不再依赖异步锁。
+2. `PooledConnectionLease` 持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop`：无论显式归还还是 future 被取消，统一在 Drop 中复位槽位、按 broken 状态决定连接是否回池，permit 随后自动归还。Drop 体先复位 `in_use` 再释放 permit（字段在 Drop 体之后析构），保证新请求拿到 permit 时必有空闲槽位。
+3. acquire 改为 CAS 抢占槽位：持有 permit 即保证并发持有者不超过 `pool_size`，扫描一轮必然命中空闲槽位，彻底删除自旋循环；建连失败直接返回错误，槽位由租约 Drop 复位。
+4. `release_connection` 退化为 `drop(lease)`，显式与隐式归还共用同一条兜底路径。
+
+## 验收
+
+- `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（35 通过，含上述新测试）
+- `cargo test -p api-server --manifest-path server-rs/Cargo.toml readyz`（2 通过）
+- `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
+
+## 运维提示
+
+- 此修复解决的是"取消导致的永久泄漏"。StDB 真慢时仍会出现成批 45 秒超时（连接被在途请求合法占用），那是容量/上游问题，应结合 `GENARRATIVE_SPACETIME_POOL_SIZE` 与 StDB 负载排查，不要再怀疑池泄漏。
+- 健康检查 `/readyz` 在池被在途请求占满时仍可能短暂 503（stage=pool_acquire），恢复后自动转好，无需重启。

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

@@ -125,11 +125,14 @@ npm run check:server-rs-ddd
 
 `/api/runtime/puzzle/runs*` 当前接受 `RuntimePrincipal`，可同时识别登录用户 Bearer 和 runtime guest token。推荐页嵌入运行态的正式开局、交换、拖拽、下一关、暂停、道具与排行榜请求，应由前端在登录态下继续携带账号 access token；匿名游客仅在确认为未登录时走 runtime guest token。不要再把拼图 runtime 当成只认普通 Bearer 的纯账号接口。
 
+公开正式 runtime 的启动与局内同步动作统一接受 `RuntimePrincipal`，包括拼图、拼消消、跳一跳、敲木鱼、抓大鹅 Match3D、方洞挑战、视觉小说、大鱼吃小鱼和汪汪声浪。登录用户仍使用账号 Bearer；未登录推荐页或公开运行态使用 Runtime Guest Token，后端以 `principal.subject()` 作为本局 owner / player subject，并用 `WorkPlayTrackingDraft::runtime_principal(...)` 记录游玩。创作、个人作品、删除、发布、Remix、点赞等账号或所有权动作不得改成 runtime guest 鉴权。
+
 抓大鹅 Match3D `api-server` 内部拆分：
 
 - `server-rs/crates/api-server/src/modules/match3d.rs` 继续负责路由装配和 body limit；对外 handler 名称保持不变。
 - `server-rs/crates/api-server/src/match3d.rs` 只作为聚合入口，保留共享 import / 常量 / 内部类型、模块声明和 handler re-export。
 - `server-rs/crates/api-server/src/match3d/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP 响应。
+- `/api/runtime/match3d/works/{profile_id}/runs`、`/api/runtime/match3d/runs/{run_id}`、`/click`、`/stop`、`/restart` 与 `/time-up` 属于正式运行态局部请求，必须接受 `RuntimePrincipal`；登录用户使用账号 Bearer，推荐页匿名游客使用 runtime guest token，后端以 principal subject 作为本局 owner，不得退回只认普通 Bearer 的路由。
 - `server-rs/crates/api-server/src/match3d/draft.rs` 承接 Agent session、草稿编译、题材 / 难度 / 物品计划和草稿持久化编排。
 - `server-rs/crates/api-server/src/match3d/works.rs` 承接作品 CRUD、封面 / 背景 / 容器资产生成入口、发布 / Remix / 点赞 / 游玩记录和作品级 helper。
 - `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品生成批次编排、append / replace / delete / sort / merge、计费外层和草稿素材映射；sheet prompt、绿幕 / 近白底透明化、切图和切片持久化复用 `generated_asset_sheets` 通用模块。
@@ -187,6 +190,10 @@ npm run check:server-rs-ddd
 1. `creation_entry_type_config.unified_creation_spec_json` 内的 `mudPointCost` 是玩法新建草稿初始生成的泥点成本真相源，同时供入口卡展示和前端余额前置校验使用；旧契约缺失时允许按代码默认成本兜底。
 2. `api-server` 执行拼图首图生成、抓大鹅完整草稿生成和汪汪声浪初始三图生成时，必须通过 `GET /api/creation-entry/config` 同源配置解析对应玩法成本后再调用钱包扣费 procedure，不得继续使用前端或后端硬编码常量作为实际扣费真相。
 3. 结果页单图重生成、发布、道具使用和其它独立资产操作仍按各自业务操作成本执行；不要把初始草稿成本误套到这些单次操作上。
+4. 资产操作的预扣费必须 fail-closed：钱包或 SpacetimeDB 预扣费不可达、超时或返回业务错误时，`api-server` 直接返回错误，不允许继续调用图片、音频、GLB 等外部生成 provider。
+5. 需要支持 HTTP retry 的计费 ledger id 必须包含当前请求的 `request_id`；前端 `fetchWithApiAuth` 同一次业务请求的静默刷新重试复用同一个 `x-request-id`，后端不得再使用 prompt 指纹或随机 asset id 作为扣费幂等键。
+6. 外部生成已预扣费但后续失败时必须先同步调用钱包退款；若 SpacetimeDB 暂不可用，退款请求写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。默认启用，配置项为 `GENARRATIVE_WALLET_REFUND_OUTBOX_ENABLED`、`GENARRATIVE_WALLET_REFUND_OUTBOX_DIR`、`GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE`、`GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS` 和 `GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES`。outbox 文件按 refund ledger id 幂等落盘；成功重放后删除，坏文件隔离为 `corrupt-*`。
+7. 拼图首图后台生成的跨实例互斥锁必须落在 SpacetimeDB `puzzle_background_compile_task` 表，claim id 由 `task_id + request_id` 构成，释放时必须校验 claim id，避免旧后台任务释放新请求抢到的租约。
 
 ## 外部服务与资产
 
@@ -643,6 +650,12 @@ npm run check:server-rs-ddd
 - Rust 结构体：`PuzzleAgentSessionRow`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
 
+### `puzzle_background_compile_task`
+
+- Rust 结构体：`PuzzleBackgroundCompileTaskRow`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
+- 说明：拼图首图后台生成的跨 api-server 实例互斥 claim 表，只保存活动任务租约，不表达最终生成结果；`task_id` 为主键，`claim_id` 用于释放时防止误删新租约，租约超时时间为 30 分钟。
+
 ### `puzzle_event`
 
 - Rust 结构体：`PuzzleEvent`

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -146,12 +146,13 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 拼图试玩和正式运行态刷新恢复不复用创作私有 query。进入 `/runtime/puzzle` 时必须写入 `runtimeProfileId`、草稿 `runtimeSessionId`、可选 `runtimeLevelId`、公开作品 `work` 和 `mode=draft|published`；进入运行态的导航顺序必须先切到 `/runtime/puzzle`，再写这些 runtime query，避免被阶段导航清掉后刷新停在“正在进入拼图关卡”。
 - 结果页生成关卡图时若关卡名为空，前端必须传 `shouldAutoNameLevel=true`，后端复用首关命名契约先按画面描述生成关卡名，再在图片生成后用视觉命名结果精修，并把生成名和 UI 背景提示词随本次关卡快照写回。
 - 拼图运行态背景优先读取当前关卡 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，旧数据才兼容 `uiBackgroundImageSrc/uiBackgroundImageObjectKey`；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺关卡背景时必须继承同作品首个可用关卡背景，仍缺失时才沿用当前运行态快照背景或默认 UI。运行态按钮视觉优先读取当前关卡 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，先按透明 alpha 自动边界检测识别 spritesheet 中的独立按钮展示矩形，再按原图位置从左到右、从上到下映射到返回、设置、下一关、提示、原图、冻结；同一组件还要按较高 alpha 阈值派生紧致点击热区，透明留白和柔边低 alpha 区域尽量不响应点击。检测失败时回退旧固定六格裁切，缺失时才用现有图标按钮兜底。有 spritesheet 时，返回、设置和下一关的点击容器只提供透明点击区，不再叠加默认白色圆形底、胶囊主按钮底或额外文字；下一关按钮在通关弹窗和底部入口中都直接使用 spritesheet 裁切出的 next 素材作为按钮本体。底部提示、原图、冻结三枚素材按检测矩形的原始宽高比显示，不能强行拉伸成正圆或铺满整列。底部道具区不再使用连片胶囊背景，提示、原图、冻结三个按钮均匀分布；运行态只展示按钮素材本身，不额外叠加“提示 / 原图 / 冻结”文字。
-- 推荐页本身不是登录门禁入口，未登录用户点击底部或侧边栏的推荐 Tab 应直接进入嵌入运行态，不主动打开登录弹窗。推荐页嵌入运行态必须按真实身份分流：已登录用户或本地已有 access token 时，启动拼图和后续排行榜 / 下一关等正式请求继续走账号 Bearer；只有确认为匿名访客时才申请并透传 runtime guest token。`/api/runtime/puzzle/runs*` 后端统一接受 `RuntimePrincipal`，可识别账号用户和匿名 runtime guest；推荐卡片的后台读写请求仍使用 local auth impact，避免单卡 401 清空整站登录态。创作、个人作品、删除、发布、Remix 等账号或所有权动作仍保持普通用户鉴权。
+- 推荐页本身不是登录门禁入口，未登录用户点击底部或侧边栏的推荐 Tab 应直接进入嵌入运行态，不主动打开登录弹窗。推荐页嵌入运行态必须按真实身份分流：已登录用户或本地已有 access token 时，正式 runtime 启动与后续局内动作继续走账号 Bearer；只有确认为匿名访客时才申请并透传 runtime guest token。平台壳统一通过 `buildRecommendRuntimeRequestOptions(...)` 为各玩法的 start / checkpoint / finish / input / drop / click / restart / time-up / leaderboard / next-level 等动作生成局部 request options，不允许每个玩法各写一套匿名分支。后端 `/api/runtime/*` 正式运行态写请求统一接受 `RuntimePrincipal`，可识别账号用户和匿名 runtime guest；推荐卡片的后台读写请求仍使用 local auth impact，避免单卡 401 清空整站登录态。创作、个人作品、删除、发布、Remix 等账号或所有权动作仍保持普通用户鉴权。
+- 推荐页作品队列只能通过 `buildPlatformRecommendFeedEntries(...)` 生成，首页卡片窗口、桌面推荐格、嵌入 runtime 自动启动和上一条 / 下一条切换都必须消费同一队列。不得在首页和 `PlatformEntryFlowShellImpl` 内分别按“最新列表顺序”和“评分推荐顺序”各算一套相邻作品，否则连续切换会出现视觉上跳过作品或回跳。
 - 拼图运行态棋盘不叠加分块蒙版、描边、阴影、选中底色或合并块 SVG 轮廓；拼图片本体需要裁切为圆角形状，单块使用独立圆角裁切，合并块使用 SVG 原生 `clipPath` 裁切整体外轮廓，外凸角和内凹角分别计算半径，内凹角半径要比外凸角更明显以避免手机 WebView 中看起来仍是直角。原图道具只在用户主动确认后打开独立原图查看层，不在当前拼图棋盘上叠加原图。
 - 拼图运行态拖拽必须完全跟随手指或鼠标位置，`pointermove` 期间即时写入可见拼块的 transform，不依赖等待后端回包、React 重渲染或下一帧动画队列；进入拖动后不展示拼块选中态或“已选择”提示，松手后再提交目标格同步规则真相。
 - 拼图运行态的提示、设置等点击弹层跟随当前运行态主色主题，使用普通圆角主题面板，不复用像素九宫格素材框。
 - 拼图运行态壳层自身要补齐 `platform-ui-shell` / `platform-theme` / `platform-theme--light|dark`，不能依赖外层平台壳来提供主题变量；`/puzzle` 直达页和平台内嵌页都必须渲染同一套主题语义类。
-- 拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 `第 N 关` 和关卡名，左侧固定使用 `media/logo.png` 卡通形象；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
+- 拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 `第 N 关` 和关卡名，左侧固定使用 `media/logo-runtime-hud.webp` 卡通形象小图；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
 - 拼图运行态进行中关卡的 `elapsedMs` 仍是结算字段，设置面板的“当前用时”必须按 `startedAtMs`、暂停累计和冻结累计实时派生；不要直接把进行中的 `currentLevel.elapsedMs` 当作展示值。
 - 推荐页嵌入拼图运行态时，通关结算弹层必须挂到页面级 fixed 浮层，不能留在推荐卡片视觉区内的 absolute 覆盖层；推荐页滑动卡片和运行态视口都使用 `overflow: hidden`，半屏内容区会裁剪排行榜、下一关按钮和相似作品卡。
 - 推荐页嵌入拼图运行态时，“下一关”应优先切到相似作品；如果当前推荐候选为空，才回退到同作品下一关，避免匿名推荐流在多关卡作品上持续停留在同一作品内。下一关请求 pending 期间必须保留当前 `PuzzleRuntimeShell` 和棋盘，不得把推荐卡整体切回 `加载中...` 占位态；局部同步状态由拼图运行态自己的 busy 表现承接。后端返回的新关卡属于其它作品时，前端必须同步 `selectedPuzzleDetail`、推荐页 `puzzleGalleryEntries` 缓存和 `activeRecommendEntryKey`，让底部作品信息、分享 / 点赞 / 改造和下一次“下一个”基准都指向新作品。
@@ -304,7 +305,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 难度只决定本局加载的物品种类数量：轻松 3、标准 9、进阶 15、硬核 20。硬核仍保留 21 次消除和 63 件总物品，运行态按 20 种素材循环复用，不要求生成第 21 种素材。
 - 运行态启动前要预加载 `generatedItemAssets[].imageViews[]`、顶层 `generatedBackgroundAsset`、物品挂载 `backgroundAsset` 中的背景、UI spritesheet 和物品 spritesheet；首次生成自动试玩、结果页手动试玩、推荐流和公开详情启动都必须传入提升后的 profile。卡片摘要缺图集字段时，进入运行态前必须补读 work detail。补读后的 profile 也要再次提升 `generatedItemAssets[].backgroundAsset`，确保背景和图集字段传给 `Match3DRuntimeShell`。
 - 背景图作为运行态全屏背景，图内已经保留容器；旧 `containerImage*` 只作为历史透明容器兼容字段。若 `containerImage*` 与 `uiSpritesheetImage*` 同源，运行态不得把 UI spritesheet 当中心容器图叠到棋盘上。
-- 抓大鹅运行态 HUD 需贴近拼图顶部信息条的视觉口径：左上只保留透明返回按钮；右上不再暴露设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板和同造型，并在牌面左侧挂上 `media/logo.png` 产品 logo；下方备选栏和道具图标只保留内容与交互边界，不再显示灰白半透底板；中央容器图层视觉可隐藏，但棋盘命中边界仍保留。
+- 抓大鹅运行态 HUD 需贴近拼图顶部信息条的视觉口径：左上只保留透明返回按钮；右上不再暴露设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板和同造型，并在牌面左侧挂上 `media/logo-runtime-hud.webp` 产品 logo 小图；下方备选栏和道具图标只保留内容与交互边界，不再显示灰白半透底板；中央容器图层视觉可隐藏，但棋盘命中边界仍保留。
 - generated 私有图换签未完成时，局内物品先隐藏等待，不得短暂显示默认积木；同一批资源在重启 run 时保留已解析签名 URL，只有资源源列表变化或换签失败后才允许进入兜底视觉。
 - `itemSize` 只缩放生成 2D 图片本体：`大`、`中`、`小` 均按相对尺寸缩放，其中 `大` 也比原始图片略小，`中` 和 `小` 进一步缩小；不改变后端下发的布局半径、点击半径或三消规则。
 - 物品进入底部物品栏时按同类型插入：如果物品栏已有同类物品，新物品插到该类型最后一个物品后面，后续物品整体后移；没有同类时追加到当前末尾。达到三件同类时，在飞入物品栏动画结束后，左侧和右侧同类物品向中间合成，三件一起消失，播放合成音效，不展示星星图标，后面的物品再向前补位。该动效只是前端表现层，后端和本地试玩仍负责权威插入、指定点击类型清除与补位后的槽位快照。

server-rs/crates/api-server/src/asset_billing.rs

@@ -4,7 +4,11 @@ use axum::http::StatusCode;
 use serde_json::json;
 use spacetime_client::SpacetimeClientError;
 
-use crate::{http_error::AppError, state::AppState};
+use crate::{
+    http_error::AppError,
+    state::AppState,
+    wallet_refund_outbox::{WalletRefundOutboxEnqueueOutcome, WalletRefundOutboxRecord},
+};
 
 pub(crate) const ASSET_OPERATION_POINTS_COST: u64 = 1;
 
@@ -104,22 +108,11 @@ async fn consume_asset_operation_points(
         .await
     {
         Ok(_) => Ok(true),
-        Err(error) if should_skip_asset_operation_billing_for_connectivity(&error) => {
-            // 中文注释：外部生图不应被 Maincloud 钱包短暂 503 阻断；此时跳过扣费，让业务链路继续，避免用户重复点击。
-            tracing::warn!(
-                owner_user_id,
-                asset_kind,
-                asset_id,
-                error = %error,
-                "资产操作泥点预扣因 SpacetimeDB 连接不可用而降级跳过"
-            );
-            Ok(false)
-        }
         Err(error) => Err(map_asset_operation_wallet_error(error)),
     }
 }
 
-/// 外部生成或发布 mutation 失败后补偿退款；退款失败只记日志，避免覆盖原始业务错误。
+/// 外部生成或发布 mutation 失败后补偿退款；立即退款失败会进入 outbox，避免覆盖原始业务错误。
 async fn refund_asset_operation_points(
     state: &AppState,
     owner_user_id: &str,
@@ -131,22 +124,74 @@ async fn refund_asset_operation_points(
         "asset_operation_refund:{}:{}:{}",
         owner_user_id, asset_kind, asset_id
     );
+    let created_at_micros = current_utc_micros();
     if let Err(error) = state
         .spacetime_client()
         .refund_profile_wallet_points(
             owner_user_id.to_string(),
             points_cost,
-            ledger_id,
-            current_utc_micros(),
+            ledger_id.clone(),
+            created_at_micros,
         )
         .await
     {
+        let refund_error = error.to_string();
+        if let Some(outbox) = state.wallet_refund_outbox() {
+            match outbox
+                .enqueue(WalletRefundOutboxRecord {
+                    owner_user_id: owner_user_id.to_string(),
+                    amount: points_cost,
+                    ledger_id: ledger_id.clone(),
+                    created_at_micros,
+                    asset_kind: asset_kind.to_string(),
+                    asset_id: asset_id.to_string(),
+                })
+                .await
+            {
+                Ok(WalletRefundOutboxEnqueueOutcome::Enqueued) => {
+                    tracing::warn!(
+                        owner_user_id,
+                        asset_kind,
+                        asset_id,
+                        ledger_id,
+                        error = %refund_error,
+                        "资产操作失败后的泥点退款立即执行失败，已写入 wallet refund outbox"
+                    );
+                    return;
+                }
+                Ok(WalletRefundOutboxEnqueueOutcome::Dropped { reason }) => {
+                    tracing::error!(
+                        owner_user_id,
+                        asset_kind,
+                        asset_id,
+                        ledger_id,
+                        reason,
+                        error = %refund_error,
+                        "资产操作失败后的泥点退款立即执行失败，且 wallet refund outbox 因容量限制丢弃"
+                    );
+                    return;
+                }
+                Err(outbox_error) => {
+                    tracing::error!(
+                        owner_user_id,
+                        asset_kind,
+                        asset_id,
+                        ledger_id,
+                        refund_error = %refund_error,
+                        outbox_error = %outbox_error,
+                        "资产操作失败后的泥点退款立即执行失败，且写入 wallet refund outbox 失败"
+                    );
+                    return;
+                }
+            }
+        }
         tracing::error!(
             owner_user_id,
             asset_kind,
             asset_id,
-            error = %error,
-            "资产操作失败后的泥点退款失败"
+            ledger_id,
+            error = %refund_error,
+            "资产操作失败后的泥点退款失败，且 wallet refund outbox 未启用"
         );
     }
 }
@@ -199,7 +244,7 @@ mod tests {
     use super::*;
 
     #[test]
-    fn asset_operation_billing_skips_spacetime_connectivity_errors() {
+    fn asset_operation_connectivity_errors_are_classified_for_non_billing_fallbacks() {
         assert_eq!(ASSET_OPERATION_POINTS_COST, 1);
         assert!(should_skip_asset_operation_billing_for_connectivity(
             &SpacetimeClientError::ConnectDropped

server-rs/crates/api-server/src/bark_battle.rs

@@ -37,7 +37,7 @@ use time::{Duration as TimeDuration, OffsetDateTime};
 use crate::{
     api_response::json_success_body,
     asset_billing::execute_billable_asset_operation_with_cost,
-    auth::AuthenticatedAccessToken,
+    auth::{AuthenticatedAccessToken, RuntimePrincipal},
     generated_image_assets::{
         GeneratedImageAssetAdapter, GeneratedImageAssetDataUrl,
         adapter::{GeneratedImageAssetAdapterMetadata, GeneratedImageAssetPersistInput},
@@ -306,11 +306,12 @@ pub async fn generate_bark_battle_image_asset(
         .filter(|value| !value.is_empty())
         .map(ToString::to_string);
     let points_cost = resolve_bark_battle_image_asset_points_cost(&state, &payload).await;
+    let billing_asset_id = request_context.request_id().to_string();
     let result = execute_billable_asset_operation_with_cost(
         &state,
         &owner_user_id,
         bark_battle_slot_asset_kind(&slot),
-        asset_id.as_str(),
+        billing_asset_id.as_str(),
         points_cost,
         async {
             generate_and_persist_bark_battle_image_asset(
@@ -506,13 +507,13 @@ pub async fn get_bark_battle_runtime_config(
     State(state): State<AppState>,
     Path(work_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, &work_id, "workId")?;
 
     let config = state
         .spacetime_client()
-        .get_bark_battle_runtime_config(work_id, Some(authenticated.claims().user_id().to_string()))
+        .get_bark_battle_runtime_config(work_id, Some(principal.subject().to_string()))
         .await
         .map_err(|error| {
             bark_battle_error_response(&request_context, map_bark_battle_client_error(error))
@@ -526,7 +527,7 @@ pub async fn start_bark_battle_run(
     State(state): State<AppState>,
     Path(work_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<BarkBattleRunStartRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let maybe_payload = payload.ok().map(|Json(payload)| payload);
@@ -543,7 +544,7 @@ pub async fn start_bark_battle_run(
     };
     ensure_non_empty(&request_context, &work_id, "workId")?;
 
-    let owner_user_id = authenticated.claims().user_id().to_string();
+    let owner_user_id = principal.subject().to_string();
     let runtime_config = state
         .spacetime_client()
         .get_bark_battle_runtime_config(work_id.clone(), Some(owner_user_id.clone()))
@@ -593,12 +594,13 @@ pub async fn start_bark_battle_run(
     record_work_play_start_after_success(
         &state,
         &request_context,
-        WorkPlayTrackingDraft::new(
+        WorkPlayTrackingDraft::runtime_principal(
             BARK_BATTLE_PLAY_TYPE_ID,
             work_id.clone(),
-            &authenticated,
+            &principal,
             "/api/runtime/bark-battle/...",
         )
+        .owner_user_id(owner_user_id.clone())
         .extra(json!({
             "runId": run_snapshot.run_id,
             "workId": work_id,
@@ -607,6 +609,7 @@ pub async fn start_bark_battle_run(
             "difficultyPreset": runtime_config.difficulty_preset,
             "sourceRoute": request.source_route,
             "clientRuntimeVersion": request.client_runtime_version,
+            "principalKind": principal.kind().as_str(),
         })),
     )
     .await;
@@ -638,12 +641,12 @@ pub async fn get_bark_battle_run(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, &run_id, "runId")?;
     let run = state
         .spacetime_client()
-        .get_bark_battle_run(run_id, authenticated.claims().user_id().to_string())
+        .get_bark_battle_run(run_id, principal.subject().to_string())
         .await
         .map_err(|error| {
             bark_battle_error_response(&request_context, map_bark_battle_client_error(error))
@@ -657,7 +660,7 @@ pub async fn finish_bark_battle_run(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<BarkBattleRunFinishRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let Json(payload) = bark_battle_json(payload, &request_context)?;
@@ -698,7 +701,7 @@ pub async fn finish_bark_battle_run(
         .finish_bark_battle_run(BarkBattleRunFinishRecordInput {
             run_id,
             run_token: payload.run_token,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             work_id: payload.work_id.clone(),
             config_version: u64::from(payload.config_version),
             ruleset_version: payload.ruleset_version.clone(),

server-rs/crates/api-server/src/big_fish.rs

@@ -63,7 +63,7 @@ use crate::{
     },
     api_response::json_success_body,
     asset_billing::execute_billable_asset_operation,
-    auth::AuthenticatedAccessToken,
+    auth::{AuthenticatedAccessToken, RuntimePrincipal},
     character_visual_assets::try_apply_background_alpha_to_png,
     http_error::AppError,
     platform_errors::map_oss_error,
@@ -224,7 +224,7 @@ pub async fn record_big_fish_play(
     State(state): State<AppState>,
     Path(session_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<RecordBigFishPlayRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let Json(payload) = payload.map_err(|error| {
@@ -242,7 +242,7 @@ pub async fn record_big_fish_play(
         .spacetime_client()
         .record_big_fish_play(BigFishPlayReportRecordInput {
             session_id: session_id.clone(),
-            user_id: authenticated.claims().user_id().to_string(),
+            user_id: principal.subject().to_string(),
             elapsed_ms: payload.elapsed_ms.unwrap_or(0),
             reported_at_micros: current_utc_micros(),
         })
@@ -254,13 +254,14 @@ pub async fn record_big_fish_play(
     record_work_play_start_after_success(
         &state,
         &request_context,
-        WorkPlayTrackingDraft::new(
+        WorkPlayTrackingDraft::runtime_principal(
             "big-fish",
             session_id.clone(),
-            &authenticated,
+            &principal,
             "/api/runtime/big-fish/sessions/{session_id}/play",
         )
-        .run_id(session_id.clone()),
+        .run_id(session_id.clone())
+        .owner_user_id(principal.subject().to_string()),
     )
     .await;
 
@@ -279,7 +280,7 @@ pub async fn start_big_fish_run(
     State(state): State<AppState>,
     Path(session_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, &session_id, "sessionId")?;
 
@@ -288,7 +289,7 @@ pub async fn start_big_fish_run(
         .start_big_fish_run(BigFishRunStartRecordInput {
             run_id: build_prefixed_uuid_id("big-fish-run-"),
             session_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             started_at_micros: current_utc_micros(),
         })
         .await
@@ -339,13 +340,13 @@ pub async fn get_big_fish_run(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, &run_id, "runId")?;
 
     let run = state
         .spacetime_client()
-        .get_big_fish_run(run_id, authenticated.claims().user_id().to_string())
+        .get_big_fish_run(run_id, principal.subject().to_string())
         .await
         .map_err(|error| {
             big_fish_error_response(&request_context, map_big_fish_client_error(error))
@@ -363,7 +364,7 @@ pub async fn submit_big_fish_input(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<SubmitBigFishInputRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let Json(payload) = payload.map_err(|error| {
@@ -384,7 +385,7 @@ pub async fn submit_big_fish_input(
         .spacetime_client()
         .submit_big_fish_input(BigFishInputSubmitRecordInput {
             run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             x: payload.x,
             y: payload.y,
             submitted_at_micros: current_utc_micros(),
@@ -721,7 +722,7 @@ pub async fn execute_big_fish_action(
         "big_fish_publish_game" => Some("big_fish_publish_game"),
         _ => None,
     };
-    let billing_asset_id = format!("{session_id}:{now}");
+    let billing_asset_id = format!("{}:{}:{}", session_id, action, request_context.request_id());
     let session_operation = async {
         match action.as_str() {
             "big_fish_compile_draft" => {

server-rs/crates/api-server/src/config.rs

@@ -38,6 +38,11 @@ pub struct AppConfig {
     pub tracking_outbox_batch_size: usize,
     pub tracking_outbox_flush_interval: Duration,
     pub tracking_outbox_max_bytes: u64,
+    pub wallet_refund_outbox_enabled: bool,
+    pub wallet_refund_outbox_dir: PathBuf,
+    pub wallet_refund_outbox_batch_size: usize,
+    pub wallet_refund_outbox_flush_interval: Duration,
+    pub wallet_refund_outbox_max_bytes: u64,
     pub log_filter: String,
     pub otel_enabled: bool,
     pub admin_username: Option<String>,
@@ -239,6 +244,11 @@ impl Default for AppConfig {
             tracking_outbox_batch_size: 500,
             tracking_outbox_flush_interval: Duration::from_millis(1_000),
             tracking_outbox_max_bytes: 256 * 1024 * 1024,
+            wallet_refund_outbox_enabled: true,
+            wallet_refund_outbox_dir: PathBuf::from("server-rs/.data/wallet-refund-outbox"),
+            wallet_refund_outbox_batch_size: 100,
+            wallet_refund_outbox_flush_interval: Duration::from_millis(1_000),
+            wallet_refund_outbox_max_bytes: 64 * 1024 * 1024,
             log_filter: "info,tower_http=info".to_string(),
             otel_enabled: false,
             admin_username: None,
@@ -494,6 +504,27 @@ impl AppConfig {
         {
             config.tracking_outbox_max_bytes = max_bytes;
         }
+        if let Some(enabled) = read_first_bool_env(&["GENARRATIVE_WALLET_REFUND_OUTBOX_ENABLED"]) {
+            config.wallet_refund_outbox_enabled = enabled;
+        }
+        if let Some(dir) = read_first_non_empty_env(&["GENARRATIVE_WALLET_REFUND_OUTBOX_DIR"]) {
+            config.wallet_refund_outbox_dir = PathBuf::from(dir);
+        }
+        if let Some(batch_size) =
+            read_first_usize_env(&["GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE"])
+        {
+            config.wallet_refund_outbox_batch_size = batch_size;
+        }
+        if let Some(flush_interval_ms) =
+            read_first_positive_u64_env(&["GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS"])
+        {
+            config.wallet_refund_outbox_flush_interval = Duration::from_millis(flush_interval_ms);
+        }
+        if let Some(max_bytes) =
+            read_first_positive_u64_env(&["GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES"])
+        {
+            config.wallet_refund_outbox_max_bytes = max_bytes;
+        }
         if let Some(otel_enabled) = read_first_bool_env(&["GENARRATIVE_OTEL_ENABLED"]) {
             config.otel_enabled = otel_enabled;
         }
@@ -1593,6 +1624,11 @@ mod tests {
             std::env::remove_var("GENARRATIVE_TRACKING_OUTBOX_BATCH_SIZE");
             std::env::remove_var("GENARRATIVE_TRACKING_OUTBOX_FLUSH_INTERVAL_MS");
             std::env::remove_var("GENARRATIVE_TRACKING_OUTBOX_MAX_BYTES");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_ENABLED");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_DIR");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES");
             std::env::remove_var("GENARRATIVE_OTEL_ENABLED");
             std::env::set_var("GENARRATIVE_API_LISTEN_BACKLOG", "2048");
             std::env::set_var("GENARRATIVE_API_WORKER_THREADS", "6");
@@ -1609,6 +1645,14 @@ mod tests {
             std::env::set_var("GENARRATIVE_TRACKING_OUTBOX_BATCH_SIZE", "250");
             std::env::set_var("GENARRATIVE_TRACKING_OUTBOX_FLUSH_INTERVAL_MS", "2000");
             std::env::set_var("GENARRATIVE_TRACKING_OUTBOX_MAX_BYTES", "1048576");
+            std::env::set_var("GENARRATIVE_WALLET_REFUND_OUTBOX_ENABLED", "false");
+            std::env::set_var(
+                "GENARRATIVE_WALLET_REFUND_OUTBOX_DIR",
+                "/tmp/genarrative-wallet-refund-outbox",
+            );
+            std::env::set_var("GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE", "50");
+            std::env::set_var("GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS", "3000");
+            std::env::set_var("GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES", "524288");
             std::env::set_var("GENARRATIVE_OTEL_ENABLED", "true");
         }
 
@@ -1634,6 +1678,17 @@ mod tests {
             std::time::Duration::from_millis(2_000)
         );
         assert_eq!(config.tracking_outbox_max_bytes, 1_048_576);
+        assert!(!config.wallet_refund_outbox_enabled);
+        assert_eq!(
+            config.wallet_refund_outbox_dir,
+            std::path::PathBuf::from("/tmp/genarrative-wallet-refund-outbox")
+        );
+        assert_eq!(config.wallet_refund_outbox_batch_size, 50);
+        assert_eq!(
+            config.wallet_refund_outbox_flush_interval,
+            std::time::Duration::from_millis(3_000)
+        );
+        assert_eq!(config.wallet_refund_outbox_max_bytes, 524_288);
         assert!(config.otel_enabled);
 
         unsafe {
@@ -1649,6 +1704,11 @@ mod tests {
             std::env::remove_var("GENARRATIVE_TRACKING_OUTBOX_BATCH_SIZE");
             std::env::remove_var("GENARRATIVE_TRACKING_OUTBOX_FLUSH_INTERVAL_MS");
             std::env::remove_var("GENARRATIVE_TRACKING_OUTBOX_MAX_BYTES");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_ENABLED");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_DIR");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS");
+            std::env::remove_var("GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES");
             std::env::remove_var("GENARRATIVE_OTEL_ENABLED");
         }
     }

server-rs/crates/api-server/src/custom_world_ai.rs

@@ -547,11 +547,12 @@ pub async fn generate_custom_world_scene_image(
     require_openai_image_settings(&state)
         .map_err(|error| custom_world_ai_error_response(&request_context, error))?;
     let asset_id = format!("custom-scene-{}", current_utc_millis());
+    let billing_asset_id = request_context.request_id().to_string();
     let asset = execute_billable_asset_operation(
         &state,
         &owner_user_id,
         "scene_image",
-        asset_id.as_str(),
+        billing_asset_id.as_str(),
         async {
             let settings = require_openai_image_settings(&state)?.with_external_api_audit_context(
                 &request_context,
@@ -806,11 +807,12 @@ pub async fn generate_custom_world_cover_image(
     require_dashscope_settings(&state)
         .map_err(|error| custom_world_ai_error_response(&request_context, error))?;
     let asset_id = format!("custom-cover-{}", current_utc_millis());
+    let billing_asset_id = request_context.request_id().to_string();
     let asset = execute_billable_asset_operation(
         &state,
         &owner_user_id,
         "custom_world_cover",
-        asset_id.as_str(),
+        billing_asset_id.as_str(),
         async {
             let settings = require_dashscope_settings(&state)?;
             let http_client = build_dashscope_http_client(&settings)?;
@@ -1011,11 +1013,12 @@ pub async fn generate_custom_world_opening_cg(
         .map_err(|error| custom_world_ai_error_response(&request_context, error))?;
 
     let opening_cg_id = normalized.opening_cg_id.clone();
+    let billing_asset_id = request_context.request_id().to_string();
     let generated = execute_billable_asset_operation_with_cost(
         &state,
         &owner_user_id,
         "custom_world_opening_cg",
-        opening_cg_id.as_str(),
+        billing_asset_id.as_str(),
         OPENING_CG_POINTS_COST,
         async {
             let image_settings = require_openai_image_settings(&state)?

server-rs/crates/api-server/src/external_generation_worker.rs

@@ -19,7 +19,7 @@ use crate::{
         ExternalGenerationWriteLeaseGuard, PuzzleCompileDraftWorkerPayload,
         PuzzleGenerateImagesWorkerPayload, PuzzleGenerateUiBackgroundWorkerPayload,
         execute_puzzle_compile_draft_worker_job, execute_puzzle_generate_images_worker_job,
-        execute_puzzle_generate_ui_background_worker_job,
+        execute_puzzle_generate_ui_background_worker_job, release_puzzle_compile_background_claim,
     },
     request_context::RequestContext,
     state::{AppState, PuzzleApiState},
@@ -256,13 +256,13 @@ async fn process_external_generation_job_once(
             match execute_puzzle_compile_draft_worker_job(
                 &puzzle_state,
                 &request_context,
-                payload,
+                payload.clone(),
                 write_guard,
             )
             .await
             {
                 Ok(session) => {
-                    complete_job(
+                    let result = complete_job(
                         &state,
                         &worker_id,
                         &job,
@@ -274,12 +274,23 @@ async fn process_external_generation_job_once(
                             .to_string(),
                         ),
                     )
-                    .await
+                    .await;
+                    if result.is_ok() {
+                        release_puzzle_compile_background_claim(&puzzle_state, &payload);
+                    }
+                    result
                 }
                 Err(error) => {
                     let message = error.body_text();
-                    fail_queue_job_after_worker_error(&state, &worker_id, &job, &error, &message)
-                        .await?;
+                    let should_release_claim = error.should_fail_queue_job();
+                    let result = fail_queue_job_after_worker_error(
+                        &state, &worker_id, &job, &error, &message,
+                    )
+                    .await;
+                    if result.is_ok() && should_release_claim {
+                        release_puzzle_compile_background_claim(&puzzle_state, &payload);
+                    }
+                    result?;
                     Err(message)
                 }
             }

server-rs/crates/api-server/src/main.rs

@@ -90,6 +90,7 @@ mod tracking_outbox;
 mod vector_engine_audio_generation;
 mod visual_novel;
 mod volcengine_speech;
+mod wallet_refund_outbox;
 mod wechat;
 mod wooden_fish;
 mod work_author;
@@ -117,6 +118,7 @@ use crate::{
     external_generation_worker::run_external_generation_worker,
     state::{AppState, AppStateInitError},
     tracking_outbox::TrackingOutbox,
+    wallet_refund_outbox::WalletRefundOutbox,
 };
 
 const API_SERVER_STARTUP_STACK_SIZE_BYTES: usize = 32 * 1024 * 1024;
@@ -127,6 +129,7 @@ const AUTH_STORE_STARTUP_RETRY_INTERVAL: Duration = Duration::from_secs(5);
 struct ShutdownContext {
     app_state: Option<AppState>,
     tracking_outbox: Option<Arc<TrackingOutbox>>,
+    wallet_refund_outbox: Option<Arc<WalletRefundOutbox>>,
     outbox_flush_timeout: Duration,
 }
 
@@ -204,6 +207,7 @@ async fn run_http_role(config: AppConfig) -> Result<(), io::Error> {
         Ok(state) => {
             spawn_app_state_background_workers(&state);
             let tracking_outbox = state.tracking_outbox();
+            let wallet_refund_outbox = state.wallet_refund_outbox();
             let worker_state = process_role
                 .runs_external_generation_worker()
                 .then(|| state.clone());
@@ -212,6 +216,7 @@ async fn run_http_role(config: AppConfig) -> Result<(), io::Error> {
                 ShutdownContext {
                     app_state: Some(state),
                     tracking_outbox,
+                    wallet_refund_outbox,
                     outbox_flush_timeout,
                 },
                 worker_state,
@@ -222,6 +227,7 @@ async fn run_http_role(config: AppConfig) -> Result<(), io::Error> {
             ShutdownContext {
                 app_state: None,
                 tracking_outbox: None,
+                wallet_refund_outbox: None,
                 outbox_flush_timeout,
             },
             None,
@@ -310,12 +316,8 @@ async fn finalize_shutdown(context: ShutdownContext) {
         state.mark_not_ready();
     }
 
-    let Some(outbox) = context.tracking_outbox else {
-        return;
-    };
-
     if context.outbox_flush_timeout.is_zero() {
-        warn!("api-server 退出时 tracking outbox flush timeout 为 0，跳过主动 flush");
+        warn!("api-server 退出时 outbox flush timeout 为 0，跳过主动 flush");
         return;
     }
 
@@ -323,22 +325,45 @@ async fn finalize_shutdown(context: ShutdownContext) {
         .outbox_flush_timeout
         .as_millis()
         .min(u128::from(u64::MAX)) as u64;
-    info!(timeout_ms, "api-server 退出前封存并 flush tracking outbox");
-    match timeout(context.outbox_flush_timeout, outbox.flush_for_shutdown()).await {
-        Ok(Ok(())) => {
-            info!("api-server 退出前 tracking outbox flush 完成");
+    if let Some(outbox) = context.tracking_outbox {
+        info!(timeout_ms, "api-server 退出前封存并 flush tracking outbox");
+        match timeout(context.outbox_flush_timeout, outbox.flush_for_shutdown()).await {
+            Ok(Ok(())) => {
+                info!("api-server 退出前 tracking outbox flush 完成");
+            }
+            Ok(Err(error)) => {
+                warn!(
+                    error = %error,
+                    "api-server 退出前 tracking outbox flush 未完成，已保留本地文件等待下次启动重试"
+                );
+            }
+            Err(_) => {
+                warn!(
+                    timeout_ms,
+                    "api-server 退出前 tracking outbox flush 超时，已保留本地文件等待下次启动重试"
+                );
+            }
         }
-        Ok(Err(error)) => {
-            warn!(
-                error = %error,
-                "api-server 退出前 tracking outbox flush 未完成，已保留本地文件等待下次启动重试"
-            );
-        }
-        Err(_) => {
-            warn!(
-                timeout_ms,
-                "api-server 退出前 tracking outbox flush 超时，已保留本地文件等待下次启动重试"
-            );
+    }
+
+    if let Some(outbox) = context.wallet_refund_outbox {
+        info!(timeout_ms, "api-server 退出前 flush wallet refund outbox");
+        match timeout(context.outbox_flush_timeout, outbox.flush_for_shutdown()).await {
+            Ok(Ok(())) => {
+                info!("api-server 退出前 wallet refund outbox flush 完成");
+            }
+            Ok(Err(error)) => {
+                warn!(
+                    error = %error,
+                    "api-server 退出前 wallet refund outbox flush 未完成，已保留本地文件等待下次启动重试"
+                );
+            }
+            Err(_) => {
+                warn!(
+                    timeout_ms,
+                    "api-server 退出前 wallet refund outbox flush 超时，已保留本地文件等待下次启动重试"
+                );
+            }
         }
     }
 }
@@ -348,6 +373,9 @@ fn spawn_app_state_background_workers(state: &AppState) {
     if let Some(outbox) = state.tracking_outbox() {
         outbox.spawn_worker();
     }
+    if let Some(outbox) = state.wallet_refund_outbox() {
+        outbox.spawn_worker();
+    }
 }
 
 fn build_tcp_listener(

server-rs/crates/api-server/src/match3d.rs

@@ -1,4 +1,4 @@
-use std::{
+use std::{
     collections::BTreeMap,
     convert::Infallible,
     future::Future,
@@ -65,11 +65,8 @@ use spacetime_client::{
 
 use crate::{
     api_response::json_success_body,
-    asset_billing::{
-        execute_billable_asset_operation_with_cost, map_asset_operation_wallet_error,
-        should_skip_asset_operation_billing_for_connectivity,
-    },
-    auth::AuthenticatedAccessToken,
+    asset_billing::{execute_billable_asset_operation_with_cost, map_asset_operation_wallet_error},
+    auth::{AuthenticatedAccessToken, RuntimePrincipal},
     config::AppConfig,
     generated_asset_sheets::apply_generated_asset_sheet_green_screen_alpha,
     http_error::AppError,
@@ -354,13 +351,6 @@ impl Match3DItemAssetsGenerationPlan {
             Self::Replace(plan) => plan.requested_item_names.len(),
         }
     }
-
-    fn billing_fingerprint_source(&self) -> String {
-        match self {
-            Self::Append(plan) => format!("append:{}", plan.requested_item_names.join("|")),
-            Self::Replace(plan) => format!("replace:{}", plan.requested_item_names.join("|")),
-        }
-    }
 }
 
 fn serialize_match3d_generated_item_assets(assets: &[Match3DGeneratedItemAsset]) -> Option<String> {

server-rs/crates/api-server/src/match3d/draft.rs

@@ -162,7 +162,12 @@ pub(super) async fn compile_match3d_draft_for_session(
     let initial_tags = requested_tags
         .clone()
         .unwrap_or_else(|| fallback_work_metadata.tags.clone());
-    let billing_asset_id = format!("{}:{}:{}", session_id, profile_id, current_utc_micros());
+    let billing_asset_id = format!(
+        "{}:{}:{}",
+        session_id,
+        profile_id,
+        request_context.request_id()
+    );
     let points_cost = crate::creation_entry_config::resolve_creation_entry_mud_point_cost(
         state,
         "match3d",
@@ -514,15 +519,6 @@ async fn consume_match3d_draft_generation_points(
         .await
     {
         Ok(_) => Ok(true),
-        Err(error) if should_skip_asset_operation_billing_for_connectivity(&error) => {
-            tracing::warn!(
-                owner_user_id,
-                billing_asset_id,
-                error = %error,
-                "抓大鹅草稿泥点预扣因 SpacetimeDB 连接不可用而降级跳过"
-            );
-            Ok(false)
-        }
         Err(error) => Err(match3d_error_response(
             request_context,
             MATCH3D_AGENT_PROVIDER,

server-rs/crates/api-server/src/match3d/handlers.rs

@@ -751,7 +751,6 @@ pub async fn generate_match3d_background_image_for_work(
     )?;
     let prompt = normalize_match3d_background_prompt(payload.prompt.as_str());
     ensure_non_empty(&request_context, MATCH3D_WORKS_PROVIDER, &prompt, "prompt")?;
-    let prompt_fingerprint = build_match3d_prompt_fingerprint(prompt.as_str());
 
     let context =
         load_match3d_work_asset_context(&state, &request_context, &authenticated, &profile_id)
@@ -763,7 +762,12 @@ pub async fn generate_match3d_background_image_for_work(
         config,
         assets,
     } = context;
-    let billing_asset_id = format!("{}:{}:{}", session_id, profile_id, prompt_fingerprint);
+    let billing_asset_id = format!(
+        "{}:{}:{}",
+        session_id,
+        profile_id,
+        request_context.request_id()
+    );
     let (generated_background, generated_assets) = execute_billable_asset_operation_with_cost(
         &state,
         owner_user_id.as_str(),
@@ -860,7 +864,6 @@ pub async fn generate_match3d_container_image_for_work(
     )?;
     let prompt = normalize_match3d_background_prompt(payload.prompt.as_str());
     ensure_non_empty(&request_context, MATCH3D_WORKS_PROVIDER, &prompt, "prompt")?;
-    let prompt_fingerprint = build_match3d_prompt_fingerprint(prompt.as_str());
 
     let context =
         load_match3d_work_asset_context(&state, &request_context, &authenticated, &profile_id)
@@ -874,7 +877,9 @@ pub async fn generate_match3d_container_image_for_work(
     } = context;
     let billing_asset_id = format!(
         "{}:{}:{}:container",
-        session_id, profile_id, prompt_fingerprint
+        session_id,
+        profile_id,
+        request_context.request_id()
     );
     let (generated_background, generated_assets) = execute_billable_asset_operation_with_cost(
         &state,
@@ -1017,7 +1022,7 @@ pub async fn generate_match3d_item_assets_for_work(
         session_id,
         profile_id,
         billed_item_count,
-        build_match3d_prompt_fingerprint(generation_plan.billing_fingerprint_source().as_str())
+        request_context.request_id()
     );
     let generated_assets = execute_billable_asset_operation_with_cost(
         &state,
@@ -1171,7 +1176,7 @@ pub async fn start_match3d_run(
     State(state): State<AppState>,
     Path(profile_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<StartMatch3DRunRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let maybe_payload = payload.ok().map(|Json(payload)| payload);
@@ -1191,7 +1196,7 @@ pub async fn start_match3d_run(
         .spacetime_client()
         .start_match3d_run(Match3DRunStartRecordInput {
             run_id: build_prefixed_uuid_id(MATCH3D_RUN_ID_PREFIX),
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             profile_id: profile_id.clone(),
             started_at_ms: current_utc_ms(),
             item_type_count_override: maybe_payload
@@ -1211,15 +1216,17 @@ pub async fn start_match3d_run(
     record_work_play_start_after_success(
         &state,
         &request_context,
-        WorkPlayTrackingDraft::new(
+        WorkPlayTrackingDraft::runtime_principal(
             "match3d",
             profile_id.clone(),
-            &authenticated,
+            &principal,
             "/api/runtime/match3d/...",
         )
         .profile_id(profile_id.clone())
+        .owner_user_id(principal.subject().to_string())
         .extra(json!({
             "runId": run.run_id,
+            "principalKind": principal.kind().as_str(),
         })),
     )
     .await;
@@ -1236,13 +1243,13 @@ pub async fn get_match3d_run(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, MATCH3D_RUNTIME_PROVIDER, &run_id, "runId")?;
 
     let run = state
         .spacetime_client()
-        .get_match3d_run(run_id, authenticated.claims().user_id().to_string())
+        .get_match3d_run(run_id, principal.subject().to_string())
         .await
         .map_err(|error| {
             match3d_error_response(
@@ -1264,7 +1271,7 @@ pub async fn click_match3d_item(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<ClickMatch3DItemRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let Json(payload) = match3d_json(payload, &request_context, MATCH3D_RUNTIME_PROVIDER)?;
@@ -1286,7 +1293,7 @@ pub async fn click_match3d_item(
         .spacetime_client()
         .click_match3d_item(Match3DRunClickRecordInput {
             run_id: payload.run_id.unwrap_or(run_id),
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             item_instance_id: payload.item_instance_id,
             client_snapshot_version: payload.client_snapshot_version.min(u32::MAX as u64) as u32,
             client_event_id: payload.client_event_id,
@@ -1313,7 +1320,7 @@ pub async fn stop_match3d_run(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
     payload: Result<Json<StopMatch3DRunRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
     let _ = payload.ok();
@@ -1323,7 +1330,7 @@ pub async fn stop_match3d_run(
         .spacetime_client()
         .stop_match3d_run(Match3DRunStopRecordInput {
             run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             stopped_at_ms: current_utc_ms(),
         })
         .await
@@ -1347,7 +1354,7 @@ pub async fn restart_match3d_run(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, MATCH3D_RUNTIME_PROVIDER, &run_id, "runId")?;
 
@@ -1356,7 +1363,7 @@ pub async fn restart_match3d_run(
         .restart_match3d_run(Match3DRunRestartRecordInput {
             source_run_id: run_id,
             next_run_id: build_prefixed_uuid_id(MATCH3D_RUN_ID_PREFIX),
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             restarted_at_ms: current_utc_ms(),
         })
         .await
@@ -1380,7 +1387,7 @@ pub async fn finish_match3d_time_up(
     State(state): State<AppState>,
     Path(run_id): Path<String>,
     Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
     ensure_non_empty(&request_context, MATCH3D_RUNTIME_PROVIDER, &run_id, "runId")?;
 
@@ -1388,7 +1395,7 @@ pub async fn finish_match3d_time_up(
         .spacetime_client()
         .finish_match3d_time_up(Match3DRunTimeUpRecordInput {
             run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
             finished_at_ms: current_utc_ms(),
         })
         .await

server-rs/crates/api-server/src/match3d/item_assets.rs

@@ -1208,14 +1208,6 @@ pub(super) fn normalize_match3d_background_prompt(raw: &str) -> String {
         .to_string()
 }
 
-pub(super) fn build_match3d_prompt_fingerprint(value: &str) -> String {
-    let mut hash = 0u32;
-    for character in value.chars() {
-        hash = hash.wrapping_mul(31).wrapping_add(character as u32);
-    }
-    format!("{hash:08x}")
-}
-
 pub(super) fn build_fallback_match3d_background_prompt(config: &Match3DConfigJson) -> String {
     let theme = config.theme_text.trim();
     let normalized_theme = if theme.is_empty() { "抓大鹅" } else { theme };

server-rs/crates/api-server/src/modules/bark_battle.rs

@@ -4,7 +4,7 @@ use axum::{
 };
 
 use crate::{
-    auth::require_bearer_auth,
+    auth::{require_bearer_auth, require_runtime_principal_auth},
     bark_battle::{
         create_bark_battle_draft, delete_bark_battle_work, finish_bark_battle_run,
         generate_bark_battle_image_asset, get_bark_battle_run, get_bark_battle_runtime_config,
@@ -66,26 +66,28 @@ pub fn router(state: AppState) -> Router<AppState> {
             "/api/runtime/bark-battle/works/{work_id}/config",
             get(get_bark_battle_runtime_config).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/bark-battle/works/{work_id}/runs",
             post(start_bark_battle_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/bark-battle/runs/{run_id}",
             get(get_bark_battle_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/bark-battle/runs/{run_id}/finish",
-            post(finish_bark_battle_run)
-                .route_layer(middleware::from_fn_with_state(state, require_bearer_auth)),
+            post(finish_bark_battle_run).route_layer(middleware::from_fn_with_state(
+                state,
+                require_runtime_principal_auth,
+            )),
         )
 }

server-rs/crates/api-server/src/modules/big_fish.rs

@@ -4,7 +4,7 @@ use axum::{
 };
 
 use crate::{
-    auth::require_bearer_auth,
+    auth::{require_bearer_auth, require_runtime_principal_auth},
     big_fish::{
         create_big_fish_session, delete_big_fish_work, execute_big_fish_action, get_big_fish_run,
         get_big_fish_session, get_big_fish_works, list_big_fish_gallery,
@@ -85,35 +85,35 @@ pub fn router(state: AppState) -> Router<AppState> {
             "/api/runtime/big-fish/sessions/{session_id}/play",
             post(record_big_fish_play).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/big-fish/works/{session_id}/play",
             post(record_big_fish_play).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/big-fish/sessions/{session_id}/runs",
             post(start_big_fish_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/big-fish/runs/{run_id}",
             get(get_big_fish_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/big-fish/runs/{run_id}/input",
             post(submit_big_fish_input).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
 }

server-rs/crates/api-server/src/modules/match3d.rs

@@ -4,7 +4,7 @@ use axum::{
 };
 
 use crate::{
-    auth::require_bearer_auth,
+    auth::{require_bearer_auth, require_runtime_principal_auth},
     match3d::{
         click_match3d_item, compile_match3d_agent_draft, create_match3d_agent_session,
         delete_match3d_work, execute_match3d_agent_action, finish_match3d_time_up,
@@ -139,42 +139,42 @@ pub fn router(state: AppState) -> Router<AppState> {
             "/api/runtime/match3d/works/{profile_id}/runs",
             post(start_match3d_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/match3d/runs/{run_id}",
             get(get_match3d_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/match3d/runs/{run_id}/click",
             post(click_match3d_item).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/match3d/runs/{run_id}/stop",
             post(stop_match3d_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/match3d/runs/{run_id}/restart",
             post(restart_match3d_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/match3d/runs/{run_id}/time-up",
             post(finish_match3d_time_up).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
 }

server-rs/crates/api-server/src/modules/square_hole.rs

@@ -4,7 +4,7 @@ use axum::{
 };
 
 use crate::{
-    auth::require_bearer_auth,
+    auth::{require_bearer_auth, require_runtime_principal_auth},
     square_hole::{
         compile_square_hole_agent_draft, create_square_hole_agent_session, delete_square_hole_work,
         drop_square_hole_shape, execute_square_hole_agent_action, finish_square_hole_time_up,
@@ -101,42 +101,42 @@ pub fn router(state: AppState) -> Router<AppState> {
             "/api/runtime/square-hole/works/{profile_id}/runs",
             post(start_square_hole_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/square-hole/runs/{run_id}",
             get(get_square_hole_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/square-hole/runs/{run_id}/drop",
             post(drop_square_hole_shape).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/square-hole/runs/{run_id}/stop",
             post(stop_square_hole_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/square-hole/runs/{run_id}/restart",
             post(restart_square_hole_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/square-hole/runs/{run_id}/time-up",
             post(finish_square_hole_time_up).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
 }

server-rs/crates/api-server/src/modules/visual_novel.rs

@@ -4,7 +4,7 @@ use axum::{
 };
 
 use crate::{
-    auth::require_bearer_auth,
+    auth::{require_bearer_auth, require_runtime_principal_auth},
     state::AppState,
     vector_engine_audio_generation::{
         create_background_music_task, create_sound_effect_task,
@@ -151,33 +151,35 @@ pub fn router(state: AppState) -> Router<AppState> {
             "/api/runtime/visual-novel/works/{profile_id}/runs",
             post(start_visual_novel_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/visual-novel/runs/{run_id}",
             get(get_visual_novel_run).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/visual-novel/runs/{run_id}/actions/stream",
             post(stream_visual_novel_action).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/visual-novel/runs/{run_id}/history",
             get(list_visual_novel_history).route_layer(middleware::from_fn_with_state(
                 state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
             )),
         )
         .route(
             "/api/runtime/visual-novel/runs/{run_id}/regenerate",
-            post(regenerate_visual_novel_run)
-                .route_layer(middleware::from_fn_with_state(state, require_bearer_auth)),
+            post(regenerate_visual_novel_run).route_layer(middleware::from_fn_with_state(
+                state,
+                require_runtime_principal_auth,
+            )),
         )
 }

server-rs/crates/api-server/src/puzzle.rs

@@ -55,7 +55,8 @@ use spacetime_client::{
     ExternalGenerationJobEnqueueRecordInput, PuzzleAgentMessageRecord,
     PuzzleAgentMessageSubmitRecordInput, PuzzleAgentSessionCreateRecordInput,
     PuzzleAgentSessionRecord, PuzzleAgentSuggestedActionRecord, PuzzleAnchorItemRecord,
-    PuzzleAnchorPackRecord, PuzzleAudioAssetRecord, PuzzleCreatorIntentRecord,
+    PuzzleAnchorPackRecord, PuzzleAudioAssetRecord, PuzzleBackgroundCompileTaskClaimRecordInput,
+    PuzzleBackgroundCompileTaskReleaseRecordInput, PuzzleCreatorIntentRecord,
     PuzzleDraftCompileFailureRecordInput, PuzzleDraftLevelRecord, PuzzleFormDraftRecord,
     PuzzleFormDraftSaveRecordInput, PuzzleGeneratedImageCandidateRecord,
     PuzzleGeneratedImagesSaveRecordInput, PuzzleLeaderboardEntryRecord,
@@ -138,6 +139,75 @@ const PUZZLE_UI_BACKGROUND_PROMPT_FALLBACK_MARKER: &str =
 const PUZZLE_VECTOR_ENGINE_SQUARE_IMAGE_SIZE: &str = "1024x1024";
 const PUZZLE_VECTOR_ENGINE_PORTRAIT_IMAGE_SIZE: &str = "1024x1536";
 
+fn build_puzzle_background_compile_task_id(session_id: &str) -> String {
+    format!("puzzle_initial_background:{session_id}")
+}
+
+fn build_puzzle_background_compile_claim_id(task_id: &str, request_id: &str) -> String {
+    format!("{task_id}:{request_id}")
+}
+
+async fn release_claimed_puzzle_background_compile_task(
+    state: &PuzzleApiState,
+    task_id: &str,
+    claim_id: &str,
+    session_id: &str,
+    owner_user_id: &str,
+) {
+    let result = state
+        .spacetime_client()
+        .release_puzzle_background_compile_task(PuzzleBackgroundCompileTaskReleaseRecordInput {
+            task_id: task_id.to_string(),
+            claim_id: claim_id.to_string(),
+            session_id: session_id.to_string(),
+            owner_user_id: owner_user_id.to_string(),
+        })
+        .await;
+    match result {
+        Ok(true) => {}
+        Ok(false) => {
+            tracing::warn!(
+                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
+                task_id,
+                claim_id,
+                session_id,
+                owner_user_id,
+                "拼图首图后台生成任务释放未命中当前 claim"
+            );
+        }
+        Err(error) => {
+            tracing::warn!(
+                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
+                task_id,
+                claim_id,
+                session_id,
+                owner_user_id,
+                error = %error,
+                "拼图首图后台生成任务释放失败"
+            );
+        }
+    }
+}
+
+pub(crate) fn spawn_release_claimed_puzzle_background_compile_task(
+    state: PuzzleApiState,
+    task_id: String,
+    claim_id: String,
+    session_id: String,
+    owner_user_id: String,
+) {
+    tokio::spawn(async move {
+        release_claimed_puzzle_background_compile_task(
+            &state,
+            &task_id,
+            &claim_id,
+            &session_id,
+            &owner_user_id,
+        )
+        .await;
+    });
+}
+
 fn has_puzzle_cover_image_src(value: &Option<String>) -> bool {
     value
         .as_deref()

server-rs/crates/api-server/src/puzzle/draft.rs

@@ -157,6 +157,10 @@ pub(crate) struct PuzzleCompileDraftWorkerPayload {
     #[serde(default)]
     pub image_model: Option<String>,
     pub requested_at_micros: i64,
+    #[serde(default)]
+    pub background_task_id: Option<String>,
+    #[serde(default)]
+    pub background_claim_id: Option<String>,
 }
 
 pub(crate) async fn execute_puzzle_compile_draft_worker_job(
@@ -228,6 +232,11 @@ pub(crate) async fn execute_puzzle_compile_draft_worker_job(
                 )
                 .await;
             }
+            release_inline_puzzle_compile_background_claim(
+                state,
+                &payload,
+                &external_generation_guard,
+            );
             Ok(session)
         }
         Err(error) => {
@@ -255,6 +264,11 @@ pub(crate) async fn execute_puzzle_compile_draft_worker_job(
                         },
                     )
                     .await;
+                    release_inline_puzzle_compile_background_claim(
+                        state,
+                        &payload,
+                        &external_generation_guard,
+                    );
                     Err(PuzzleExternalGenerationWorkerError::with_failure_state_written(error))
                 }
                 Err(mark_error) => {
@@ -265,6 +279,37 @@ pub(crate) async fn execute_puzzle_compile_draft_worker_job(
     }
 }
 
+fn release_inline_puzzle_compile_background_claim(
+    state: &PuzzleApiState,
+    payload: &PuzzleCompileDraftWorkerPayload,
+    external_generation_guard: &ExternalGenerationWriteLeaseGuard,
+) {
+    if external_generation_guard.job_id.is_some() {
+        return;
+    }
+    release_puzzle_compile_background_claim(state, payload);
+}
+
+pub(crate) fn release_puzzle_compile_background_claim(
+    state: &PuzzleApiState,
+    payload: &PuzzleCompileDraftWorkerPayload,
+) {
+    let (Some(task_id), Some(claim_id)) = (
+        payload.background_task_id.as_ref(),
+        payload.background_claim_id.as_ref(),
+    ) else {
+        return;
+    };
+
+    spawn_release_claimed_puzzle_background_compile_task(
+        state.clone(),
+        task_id.clone(),
+        claim_id.clone(),
+        payload.session_id.clone(),
+        payload.owner_user_id.clone(),
+    );
+}
+
 pub(crate) async fn mark_puzzle_compile_failure_for_worker(
     state: &PuzzleApiState,
     session_id: &str,

server-rs/crates/api-server/src/puzzle/handlers.rs

@@ -588,7 +588,7 @@ pub async fn execute_puzzle_agent_action(
     let owner_user_id = authenticated.claims().user_id().to_string();
     let now = current_utc_micros();
     let action = payload.action.trim().to_string();
-    let billing_asset_id = format!("{session_id}:{now}");
+    let billing_asset_id = format!("{}:{}:{}", session_id, action, request_context.request_id());
     tracing::info!(
         provider = PUZZLE_AGENT_API_BASE_PROVIDER,
         session_id = %session_id,
@@ -658,6 +658,79 @@ pub async fn execute_puzzle_agent_action(
                 reference_image_src: primary_reference_image_src.map(ToOwned::to_owned),
                 image_model: payload.image_model.clone(),
                 requested_at_micros: now,
+                background_task_id: None,
+                background_claim_id: None,
+            };
+            let worker_payload = if ai_redraw {
+                let background_task_id =
+                    build_puzzle_background_compile_task_id(&compile_session_id);
+                let background_claim_id = build_puzzle_background_compile_claim_id(
+                    &background_task_id,
+                    request_context.request_id(),
+                );
+                let claim_result = state
+                    .spacetime_client()
+                    .claim_puzzle_background_compile_task(
+                        PuzzleBackgroundCompileTaskClaimRecordInput {
+                            task_id: background_task_id.clone(),
+                            claim_id: background_claim_id.clone(),
+                            session_id: compile_session_id.clone(),
+                            owner_user_id: owner_user_id.clone(),
+                            claimed_at_micros: current_utc_micros(),
+                        },
+                    )
+                    .await
+                    .map_err(|error| {
+                        puzzle_error_response(
+                            &request_context,
+                            PUZZLE_AGENT_API_BASE_PROVIDER,
+                            map_puzzle_client_error(error),
+                        )
+                    })?;
+                if !claim_result {
+                    tracing::info!(
+                        provider = PUZZLE_AGENT_API_BASE_PROVIDER,
+                        session_id = %compile_session_id,
+                        owner_user_id = %owner_user_id,
+                        task_id = %background_task_id,
+                        "拼图首图后台生成任务已存在，本次 action 直接返回生成中会话"
+                    );
+                    let session = state
+                        .spacetime_client()
+                        .get_puzzle_agent_session(compile_session_id.clone(), owner_user_id.clone())
+                        .await
+                        .map(mark_puzzle_initial_generation_started_snapshot)
+                        .map_err(|error| {
+                            puzzle_error_response(
+                                &request_context,
+                                PUZZLE_AGENT_API_BASE_PROVIDER,
+                                map_puzzle_client_error(error),
+                            )
+                        })?;
+                    return Ok(json_success_body(
+                        Some(&request_context),
+                        PuzzleAgentActionResponse {
+                            operation: PuzzleAgentOperationResponse {
+                                operation_id: background_task_id,
+                                operation_type: "compile_puzzle_draft".to_string(),
+                                status: "running".to_string(),
+                                phase_label: "首关拼图草稿".to_string(),
+                                phase_detail: "首关草稿生成已在后台处理中。".to_string(),
+                                progress: session.progress_percent.max(10),
+                                error: None,
+                            },
+                            session: map_puzzle_agent_session_response(session),
+                        },
+                    ));
+                }
+
+                PuzzleCompileDraftWorkerPayload {
+                    background_task_id: Some(background_task_id),
+                    background_claim_id: Some(background_claim_id),
+                    ..worker_payload
+                }
+            } else {
+                worker_payload
             };
             if state
                 .root_state()
@@ -675,7 +748,7 @@ pub async fn execute_puzzle_agent_action(
                 let session = execute_puzzle_compile_draft_worker_job(
                     &state,
                     &request_context,
-                    worker_payload,
+                    worker_payload.clone(),
                     ExternalGenerationWriteLeaseGuard::inline(),
                 )
                 .await
@@ -707,6 +780,18 @@ pub async fn execute_puzzle_agent_action(
                 ));
             }
             let request_payload_json = serde_json::to_string(&worker_payload).map_err(|error| {
+                if let (Some(task_id), Some(claim_id)) = (
+                    worker_payload.background_task_id.as_deref(),
+                    worker_payload.background_claim_id.as_deref(),
+                ) {
+                    spawn_release_claimed_puzzle_background_compile_task(
+                        state.clone(),
+                        task_id.to_string(),
+                        claim_id.to_string(),
+                        compile_session_id.clone(),
+                        owner_user_id.clone(),
+                    );
+                }
                 puzzle_error_response(
                     &request_context,
                     PUZZLE_AGENT_API_BASE_PROVIDER,
@@ -736,6 +821,18 @@ pub async fn execute_puzzle_agent_action(
                 })
                 .await
                 .map_err(|error| {
+                    if let (Some(task_id), Some(claim_id)) = (
+                        worker_payload.background_task_id.as_deref(),
+                        worker_payload.background_claim_id.as_deref(),
+                    ) {
+                        spawn_release_claimed_puzzle_background_compile_task(
+                            state.clone(),
+                            task_id.to_string(),
+                            claim_id.to_string(),
+                            compile_session_id.clone(),
+                            owner_user_id.clone(),
+                        );
+                    }
                     puzzle_error_response(
                         &request_context,
                         PUZZLE_AGENT_API_BASE_PROVIDER,
@@ -2034,7 +2131,7 @@ pub async fn use_puzzle_runtime_prop(
         }
     };
     let should_sync_freeze_boundary = matches!(prop_kind.as_str(), "freezeTime" | "freeze_time");
-    let billing_asset_id = format!("{}:{}:{}", run_id, prop_kind, current_utc_micros());
+    let billing_asset_id = format!("{}:{}:{}", run_id, prop_kind, request_context.request_id());
     let reducer_owner_user_id = owner_user_id.clone();
     let reducer_run_id = run_id.clone();
     let fallback_run_id = run_id.clone();