feat: add incremental spacetime migration import

docs/technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md

@@ -95,13 +95,21 @@ node scripts/spacetime-revoke-migration-operator.mjs \
 
 `import_database_migration_from_file(ctx, input)`
 
+`import_database_migration_incremental_from_file(ctx, input)`
+
 输入字段：
 
 - `migration_json`: 导出 procedure 生成的完整迁移 JSON 字符串。
 - `include_tables`: 可选表名白名单。为空时导入文件内所有支持表。
-- `replace_existing`: 是否先清空目标表。跨服务器全量迁移必须为 `true`。
+- `replace_existing`: 是否先清空本次迁移文件内实际导入的目标表。不会清空迁移文件未包含的表；分批迁移时只覆盖当前批次。
 - `dry_run`: 只解析和统计，不写表。
 
+导入模式：
+
+- 默认严格追加：不清空目标表，逐行插入；遇到主键或唯一约束冲突时失败并回滚，适合确认目标库没有同表旧数据时使用。
+- 增量追加：调用 `import_database_migration_incremental_from_file`，不清空目标表；遇到已存在或唯一约束冲突的行会跳过并计入 `skipped_row_count`，只插入目标库缺失的行。该模式不会更新目标库已有行。
+- 覆盖导入：`replace_existing = true` 时先删除覆盖范围内的目标表旧数据，再插入迁移文件中的数据；只适合迁移文件是这些表完整快照的场景。
+
 返回字段：
 
 - `ok`: 是否成功。
@@ -152,10 +160,22 @@ node scripts/spacetime-import-migration-json.mjs \
   --server maincloud \
   --database xushi-p4wfr \
   --bootstrap-secret <服务器目标库发布时输出的随机密钥> \
-  --in tmp/spacetime-migrations/source-2026-04-27.json \
-  --replace-existing
+  --in tmp/spacetime-migrations/source-2026-04-27.json
 ```
 
+如果目标库已有部分数据，且只想补充缺失行，使用增量模式：
+
+```bash
+node scripts/spacetime-import-migration-json.mjs \
+  --server maincloud \
+  --database xushi-p4wfr \
+  --bootstrap-secret <服务器目标库发布时输出的随机密钥> \
+  --in tmp/spacetime-migrations/source-2026-04-27.json \
+  --incremental
+```
+
+如果目标库对应表已有数据，并且本次文件应作为这些表的覆盖来源，再显式追加 `--replace-existing`。脚本会把覆盖范围限定为迁移文件内实际包含且本次会导入的表，避免分批导入时清空文件外的其它表。
+
 默认情况下，脚本会自动完成三步：
 
 1. `POST /v1/identity` 创建临时 Web API identity/token。
@@ -169,6 +189,10 @@ node scripts/spacetime-import-migration-json.mjs \
 
 正式导入前建议先加 `--dry-run`，确认 JSON 可解析、版本匹配、表名都在迁移白名单内。
 
+`--dry-run` 不会模拟目标库主键或唯一约束冲突，因此增量模式的 `skipped_row_count` 只有真实导入时才准确。
+
+不要在只想追加数据时使用 `--replace-existing`。该参数会先删除覆盖范围内的目标表旧数据，再插入迁移文件中的数据；如果源文件不是完整快照，会造成目标表数据丢失。
+
 如需分批迁移，可用逗号分隔表名：
 
 ```bash