42 lines
3.9 KiB
Markdown
42 lines
3.9 KiB
Markdown
# 兼容矩阵（COMPATIBILITY）
|
||
|
||
Core 与 octopus 实例（dogfood）之间的兼容性契约。随各 Increment 更新；
|
||
自首个 semver 发布起，本表挂接 changelog（发布仓 `CHANGELOG.md` 的
|
||
条目以本表的行作为兼容性依据）。
|
||
|
||
## core 版本 × octopus 版本
|
||
|
||
| core 版本 | 对应 octopus 侧状态 | 兼容说明 |
|
||
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 0.x（Increment 1–4：骨架 + G0–G4 全量迁移） | octopus 实例 `.octopus/` 为消费镜像；core 与 dogfood 内容逐字/改写对齐 | core 是 SSOT 权威副本；dogfood 经 `script/core-sync.sh` 单向同步。schema 尚未迁入 core。 |
|
||
| 0.x（Increment 5：schema $id 迁移四件套） | dogfood `.octopus/schemas/*.json` 的 `$id` **保持旧命名空间不动**（活系统仍引用）；core 侧 `$id` 已迁至 `https://eightarms.net/octopus-workflow/schemas/` | 双轨期：core schema 与 dogfood schema 是**不同 $id 的两份文件**（manifest 登记为 `rewritten`，不逐字同步）。活归档 run 的 index.json 携带旧 $id，读取侧经别名表解析。 |
|
||
| 1.0.0（首个 semver 发布，规划中） | 发布仓创建；live 迁移（dogfood 侧切新命名空间）完成 | `id-aliases.json` 置 `frozen: true`——$id 一经发布不可变（v3 §G）。别名保留 ≥2 个 major 版本。 |
|
||
|
||
## builtin overlay 语料兼容
|
||
|
||
- 自 Increment 6b 起，builtin overlay（`builtin-data.gen.ts`）内嵌
|
||
**中立版语料**（源权威 = `core/`）；旧版内嵌本组织实例表述（含组织
|
||
工单号活链接与实例 token）。overlay 仅在实例磁盘无 `<instance-root>/`
|
||
目录时生效——已初始化实例（含本组织 dogfood）运行时行为不变。
|
||
|
||
## $id 行（schema 命名空间兼容）
|
||
|
||
- 旧命名空间 `$id`（历史形态 `https://eightarms.net/{legacy-owner}/octopus/.octopus/schemas/*.schema.json`）
|
||
经 `core/schemas/id-aliases.json` 解析到新命名空间
|
||
（`https://eightarms.net/octopus-workflow/schemas/*.schema.json`）。
|
||
- **别名保留期 ≥2 个 major 版本**：自 frozen 起至少两个 major 版本内，
|
||
旧 `$id` 仍被接受（`runs-index.schema.json` 的 `artifacts[].schema`
|
||
字段声明该历史接受集）。
|
||
- **twin token 归一记录**：scaffold-template 侧 schema `$id` 的 owner
|
||
token（旧命名空间 owner → Octopus）差异经 `normalizeSchemaOwnerToken`
|
||
（`script/check-scaffold-parity.ts`）归一化比较，双向等价；Increment 5
|
||
已将残留旧 owner token 的 6 份模板 schema 统一为 Octopus token（纯
|
||
一致性清理，归一化语义不变）。
|
||
|
||
## 后续 semver changelog 挂钩
|
||
|
||
- 首个 semver 发布（1.0.0）起，任何影响本表行的变更（$id 变更、别名
|
||
增删、兼容语义调整）必须在发布仓 changelog 中登记，并同步更新本表。
|
||
- 别名表 `frozen: true` 后新增别名视为 minor 变更；删除别名须满足
|
||
「≥2 个 major 版本保留期」并视为 major 变更。
|