Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

2026-09-15 08:41:51 +08:00
commit bb35e661b2
114 changed files with 20240 additions and 0 deletions
@@ -0,0 +1,41 @@
+# 兼容矩阵（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 变更。