oceanway-contracts 实施计划

OceanWay 跨仓契约、Schema、生成制品与兼容治理仓库的实施计划

仓库：Oceanway-AI/oceanway-contracts。当前已发布基线：@oceanway-ai/contracts@0.2.0。

目标结果与当前基线

Contracts 是所有跨仓 wire object 的唯一 Canonical Source，负责 Public API、内部服务、事件、错误、标识、Canonicalization、JSON Schema 和生成类型制品。0.2.0 已用于受控 API Admission；B1、B2 的新契约尚待以新固定版本发布。

Contracts 不实现领域逻辑、数据库、运行时调度或环境配置。Schema 的业务语义由事实 Owner 负责，Contracts 负责让生产者与消费者对同一语义可验证。

B1 的实时任务、依赖和评审统一进入 GitHub Milestone B1 · Operations Contracts。本页只维护稳定边界和退出门禁，不复制 Issue 的实时状态。

导出边界

导出面	消费者	内容
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 或诊断私有字段。

仓库里程碑

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 字段不自动视为兼容。
新能力优先增加新 Schema/Event Type，不追溯改写已经发布的历史对象。
Contracts 不包含 Provider 私有 Payload、Channel/Supply、环境 Secret 或客户正文。
所有消费仓固定精确版本，禁止 workspace:*、本地相对路径、分支 URL 或同名公共包回退。

当前 B1 交付细节见Operations 实施计划，B2 语义见ADR-031。