历史 · oceanway-contracts 实施计划
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
B1 跨仓工作包、固定版本门、阻塞规则与证据汇总见 B1 交付控制页。
仓库：Oceanway-AI/oceanway-contracts。已发布基线：B0 @oceanway-ai/contracts@0.2.0；B1 0.3.0（消费者总门待接收）。
当前实施入口
B0 0.2.0 保留；B1 正式 0.3.0 已发布，包资格与总接收分别记录。继续使用既有正式制品和资格证据，不因补计划重新发布。当前任务及待决策项进入本机工作台，历史固定证据见 B1 控制页。
目标结果与当前基线
Contracts 是所有跨仓 wire object 的唯一 Canonical Source，负责 Public API、内部服务、事件、错误、标识、Canonicalization、JSON Schema 和生成类型制品。0.2.0 已用于受控 API Admission；B1 新契约已由 0.3.0 发布，消费者总门仍待接收；B2 不属于该发布范围。
Contracts 不实现领域逻辑、数据库、运行时调度或环境配置。Schema 的业务语义由事实 Owner 负责，Contracts 负责让生产者与消费者对同一语义可验证。
本机工作台是当前任务、依赖和接收记录的协调主入口；既有 GitHub Milestone保留为历史及可选同步链接。本页维护需求、设计、原型和实施边界。
导出边界
| 导出面 | 消费者 | 内容 |
|---|---|---|
| Public | Site、Developer Center、Console、产品 UI、SDK | 公开模型目录、Public API、公共错误与分页 |
| Service | Core、API Edge、Admin BFF、产品 BFF | 受控内部请求/响应与 Workload Audience |
| Internal | Core、Text/Media Gateway、Infrastructure 测试 | Execution、Gateway、Metering、Billing、Operations 严格 DTO |
| Event | Producer、Dispatcher、Projector | Canonical Envelope、Payload、Delivery Set 与版本注册表 |
Public 导出不能间接引用内部 Execution Target、Provider Route、Credential 或诊断私有字段。
本轮全流程：先统一消费者需求、协议设计与原型
Owner：本人，覆盖需求、设计、原型、Schema 实现、API 文档、资格和发布记录；任务在本机工作台维护，产物遵循实施工作流。本轮先交需求矩阵、语义设计和合成 fixture，不重做 B0。
消费者需求与待决策项
| 消费者/场景 | 需求产物 | 需要明确的决定 |
|---|---|---|
| API Edge/Core 准入 | 请求、回执、重复请求、拒绝/未知提交对照 | 客户可见状态与内部当前状态的区别，重放稳定字段 |
| Core Operations/Admin | Event/Observation 到查询的字段追踪 | 谁提供权威事实，完整/过期/部分/未知如何表达，哪些字段允许披露 |
| Core Execution/Text/Media | Attempt、路由、提交结果、Usage/Cost Evidence 对照 | B2 最小范围、未知提交与取消语义、证据缺失状态；未定项不提前发布 |
| 产品 BFF/SDK/文档 | 产品动作到公共对象的映射 | 共用引用与产品私有字段、分页/错误/版本兼容的范围 |
逐场景列输入、预期结果、失败与重放、敏感字段、事实 Owner、消费者动作和非目标；不从“某仓需要一个字段”直接推导跨仓公共类型。
协议与服务设计
先画生产者→事实 Owner→消费者的调用/事件时序，再完成字段字典、状态联合、错误矩阵与权限矩阵。每个对象标清权威字段、Claim、引用、摘要、不可变部分及保存责任；金额、时间、ID、Canonicalization 使用现有定义。
需求设计阶段可以比较方案和增加合成场景；仅在语义收敛后修改 canonical Schema。鉴权配置值由运行环境提供，Schema 只描述边界，不能把具体环境 Secret 或猜测的 Audience 写入包。
原型及首轮可验收产物
原型为消息流图、状态机、脱敏示例和可运行 consumer fixture。B0 复用已有 Golden；新场景在显式草案区演示，不复制已发布 DTO、也不让产品依赖草案源码。原型至少展示一次成功、一次同键重放、一次异摘要冲突、一次跨租户/权限拒绝和一个缺失/未知状态。
首轮检查的是“消费者能否仅凭接口理解下一步动作、所有字段是否有 Owner、错误是否可区分、待定项是否显式”。草案运行成功不等于包已发布或消费者有资格接入。
API/Schema 文档清单
| 清单 | 维护方式与责任 |
|---|---|
| Public API / Public Catalog | Contracts 维护版本化 Schema、字段语义与错误；HTTP Owner 维护 OpenAPI 的 method/path/状态码 |
| Internal API Edge / Execution / Gateway / Operations | 按现有导出面列请求/响应/事件、调用者、敏感级别和引用；未发布能力标草案 |
| Event 与 Canonical Golden | 同时列事件版本、算法、因果关系、去重坐标、示例和兼容期 |
| 发布制品 | 从 canonical Zod 生成类型/JSON Schema；登记导出、版本、digest、源提交和 producer/consumer 资格 |
每条文档必须标 Owner（本人）、事实模块、状态、包/协议版本、鉴权责任、错误、分页适用性、幂等适用性及成功/失败示例。没有 HTTP 的对象不虚构路由；不适用分页或幂等的条目明确写“不适用”。OpenAPI 中的 wire schema 与正式生成制品校验，不手写第二套模型。Docs 负责解释与索引，生产代码从固定包消费。
后台实现、验证与接入顺序
- 复用 0.2.0/0.3.0，收口既有包资格及证据记录；需求文档修订不触发重发。
- 按一个消费者场景新增或演进 Schema、语义校验、Golden 与兼容记录；基础 ID/金额不重复建设。
- 验证 strict parse、未知字段、Public 导出隔离、Node/Web 和非 TypeScript JSON Schema 消费；运行实际旧版本兼容比较。
- 固定版本与同一 tgz 的双源摘要后，目标生产者/消费者各完成契约测试；包发布不自动启动 runtime。
- 依赖方使用精确版本完成集成；切流和旧版本退出由运行 Owner 按实际证据安排。保留历史 Schema，不删除仍被事实引用的版本。
仓库里程碑
- CONTRACTS-1 已完成基线：固定
0.2.0的 Admission、Credential、Model Public/Internal 导出和制品比对。 - CONTRACTS-2 B1 运维事件：发布 Run/Wallet v2 配对、Delivery、Observation、Projection、Query 与完整性严格联合。
- CONTRACTS-3 B2 执行终局：发布 Attempt/Dispatch/Binding/Route/Evidence、Closure、Eligibility、Settlement、Finalization 与两类 Case Resolution。
- CONTRACTS-4 Asset 与产品接入：发布 Asset Version/Lineage、Resource Reference、Handoff 和最小 Product Command Contract。
- CONTRACTS-5 Agent/MCP/Canvas：只在对应业务设计完成后发布 Revision、Grant、Binding 与审批契约。
- CONTRACTS-6 公共生态：OpenAPI、SDK、CLI、Webhook 和废弃策略随已上线能力发布。
每次 Release 门禁
- 所有严格 DTO 有运行时验证、TypeScript 类型、JSON Schema 与 Canonical Golden。
- 未知字段、错版本、半联合、错摘要算法、跨租户/跨对象重绑和语义冲突有负向夹具。
- Node/Web 消费测试、Package Export 负向测试、打包清单、依赖审计和许可证检查通过。
- Registry 与 GitHub Release 使用同一个 tgz，并递归比较内容与 SHA-256。
- 至少一个目标生产者和一个目标消费者在固定版本上通过 Contract Test，才能进入切流。
- 旧版本的保留、废弃和最后消费时间有登记；不能删除仍存在历史事实的 Schema。
版本规则
- 严格对象字段集合或语义变化不自动视为兼容，增加 Optional 字段同样需要检查。版本按仓库 SemVer 规则处理；1.0.0 前的基线破坏性演进须明确记录，可使用 minor，1.0.0 后使用 major。
- 新能力优先增加新 Schema/Event Type，不追溯改写已经发布的历史对象。
- Contracts 不包含 Provider 私有 Payload、Channel/Supply、环境 Secret 或客户正文。
- 所有消费仓固定精确版本，禁止
workspace:*、本地相对路径、分支 URL 或同名公共包回退。
当前 B1 交付细节见Operations 实施计划，B2 语义见ADR-031。