# 兼容矩阵（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 变更。