1

docs/technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md

@@ -13,6 +13,8 @@ SpacetimeDB reducer 必须保持确定性，不能访问文件系统和网络。
 
 procedure 不再访问 HTTP 文件桥，也不接收部署机本地文件路径。这样可以避开 SpacetimeDB 对 private/special-purpose 地址的 HTTP 访问限制，并避免把 private 表内容通过临时 HTTP 服务转发。
 
+SpacetimeDB Wasm 运行环境不支持 `std::time::SystemTime::now()`，procedure 或 reducer 内需要当前时间时必须使用 `ctx.timestamp`。如果共享 crate 同时服务前端/本地纯逻辑与 SpacetimeDB 模块，应提供 `*_at(now_ms)` 或显式时间参数版本，SpacetimeDB 模块只调用注入时间的函数，避免发布后在 maincloud 触发 `time not implemented on this platform` panic。
+
 `spacetime login show --token` 输出的是 CLI 登录 token，不是 HTTP `/v1/database/.../call` 所需的数据库连接 token。导入脚本如果没有显式传 `--token`，会自动调用 `POST /v1/identity` 获取 Web API token；迁移时不要把 CLI token 传给 `--token`。
 
 ## 接口
@@ -132,6 +134,10 @@ node scripts/spacetime-revoke-migration-operator.mjs \
 4. 导出成功后执行清库发布新 wasm。
 5. 新 wasm 发布成功后，把第 3 步导出的 JSON 自动导入回灌。
 
+SpacetimeDB 2.1 对 schema 冲突的报错文案可能不再包含 `schema conflict`，而是直接提示 `manual migration`、`default value annotation` 或 `--delete-data`。发布脚本必须把这些文案同样识别为可迁移冲突，否则会停在原始失败而不进入导出回灌流程。
+
+新增字段优先采用低风险热升级策略：旧字段顺序保持不变，新字段追加到表尾，并用 `#[default(...)]` 提供旧行默认值。只有仍无法通过发布器检查时，才执行清库发布与 JSON 回灌。
+
 任一阶段失败都会中止流程，并保留已经导出的迁移 JSON。非 schema 冲突的发布失败不会进入迁移流程。
 
 ```bash
@@ -253,7 +259,9 @@ node scripts/spacetime-export-migration-json.mjs \
 - 自定义世界：`custom_world_profile`、`custom_world_session`、`custom_world_agent_session`、`custom_world_agent_message`、`custom_world_agent_operation`、`custom_world_draft_card`、`custom_world_gallery_entry`
 - 资产索引：`asset_object`、`asset_entity_binding`
 - 拼图：`puzzle_agent_session`、`puzzle_agent_message`、`puzzle_work_profile`、`puzzle_runtime_run`
-- 大鱼：`big_fish_creation_session`、`big_fish_agent_message`、`big_fish_asset_slot`、`big_fish_runtime_run`
+- 大鱼：`big_fish_creation_session`、`big_fish_agent_message`、`big_fish_asset_slot`
+
+`big_fish_runtime_run` 当前运行态已由前端本地运行服务承接，不再加入迁移白名单；但 maincloud 旧库仍可能存在该表。为避免热升级被 “Removing the table big_fish_runtime_run requires a manual migration” 阻断，模块发布期可以保留兼容空壳表，后续确认旧数据可丢弃后再走正式删除表迁移。
 
 后续新增 SpacetimeDB 表时，必须同步把表加入迁移白名单与本文档。