Add archer import and allow date-mode bulk delete

archer import replays a sealed archive into an existing table: shard
selection (`--select`), SHA-256 pre-verification, idempotent modes
(`ignore`/`insert`/`replace`), and both LOAD DATA and batched-INSERT
engines. It reads manifest.jsonl strictly so corruption is reported
instead of skipped, and supports --dry-run, --allow-partial, and
per-shard workers.

--bulk-delete no longer rejects --shard-by date. Range deletion now
derives its bounds from the chunk's actual keys (date scanners rewrite
LastKey into a resumption cursor) and keeps safe-auto-increment
semantics by excluding the current max key. A startup warning documents
the monotonic-shard-column assumption.

Also splits CLI/format/sharding/progress/safety reference docs out of
the README, and adds the corresponding OpenSpec change artifacts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 21:14:23 +08:00
1 parent bc4a6b504f
commit 366d61ca25
49 files changed
+5099 -342

No files matched your search

@@ -0,0 +1,30 @@
## MODIFIED Requirements
### Requirement: 删除语义
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按 chunk 实际读取行的首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`。日期分片模式下,区间删除仅在“分片列相对扫描键单调、无回填”的前提下安全,系统 SHALL 允许该组合并在启动时打印该前提警告。
#### Scenario: 默认 IN 列表删除
- **WHEN** 一个 chunk 读取到主键 1001..3000,且 `--where "created_at < '2026-01-01'"`
- **THEN** 系统生成 `DELETE ... WHERE id IN (1001,...,3000)`,不删除未被读取的行
#### Scenario: 区间删除附带回填条件
- **WHEN** 启用 `--bulk-delete`,chunk 首尾主键为 1001 与 3000
- **THEN** 系统生成 `DELETE ... WHERE id BETWEEN 1001 AND 3000 AND (<where>)`
#### Scenario: 日期模式启用区间删除
- **WHEN** `--shard-by date` 与 `--bulk-delete` 同时出现
- **THEN** 系统允许执行,并在启动时警告:该组合要求分片列永不相对扫描键回退,否则迟到或回填的行可能在归档前被删除
#### Scenario: 日期模式使用裸键区间
- **WHEN** 日期扫描器把 chunk 的 `LastKey` 改写为 `(分片列, 键...)` 的续跑游标
- **THEN** 区间删除仍使用 chunk 实际读取行的裸唯一键首尾,不把分片列拼入删除上界
#### Scenario: 区间删除保留最大自增行
- **WHEN** 启用 `--bulk-delete` 且 `--safe-auto-increment` 为默认值,chunk 区间包含源表当前 `MAX(pk)`
- **THEN** 区间删除语句额外排除该最大键,最大行不被删除,其余区间内行正常删除
@@ -0,0 +1,25 @@
## MODIFIED Requirements
### Requirement: 参数依赖与互斥
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge`;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误。违反时 MUST 在启动阶段报错。
#### Scenario: 数量模式误传日期列
- **WHEN** `--shard-by count` 同时带上 `--shard-column`
- **THEN** 系统报错,说明该参数仅在日期模式下有效
#### Scenario: 未启用 purge 却要求 bulk-delete
- **WHEN** 用户指定 `--bulk-delete` 但未指定 `--purge`
- **THEN** 系统报错,说明 bulk-delete 必须配合 purge
#### Scenario: 日期模式使用 bulk-delete
- **WHEN** 用户同时指定 `--shard-by date`、`--shard-column`、`--purge` 与 `--bulk-delete`
- **THEN** 系统通过启动校验,并在开始扫描前打印区间删除的安全前提警告
#### Scenario: 插入模式互斥
- **WHEN** 用户同时指定普通插入、`--insert-ignore` 与 `--replace` 中的多项
- **THEN** 系统在启动阶段报错