历史 · oceanway-core 实施计划

历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。

B1 跨仓工作包、固定版本门、阻塞规则与证据汇总见 B1 交付控制页。

仓库：Oceanway-AI/oceanway-core。既有基线：Organization-backed Run Admission、credits Reservation 与事务内 B0 Outbox 写入；B1 的受控 Append/Bootstrap 是后续切片。

当前实施入口

现有 B0 准入继续复用。B1 存储、包资格、Catalog 和投影候选内核已进入主线；候选内核不是完整 Projector，生产 Operations UoW 仍关闭，尚无 B1 Worker/Query 的跨仓运行验收。

2026-09-09 的旧合并态迁移失败及后续存储防护问题已由 PR #21 先合入修复分支、再随 PR #19 进入 main 118f232c。该主线 CI通过 123 单元与 105 PostgreSQL 测试。接收记录需对齐新证据，不能继续沿用旧失败作为技术阻塞；这不等于生产启用或总门已经接收。

动态任务与接收状态集中于本机工作台，固定跨仓证据见 B1 控制页。本页不重复维护 PR 实时状态。

目标结果与当前基线

Core 是 Identity、Tenant、Authorization、Developer Access、Wallet、Billing、Asset、Execution、Metering、Agent、MCP、Model Control、Operations 与 Audit 的模块化运行时。当前受控基线可以创建 Run/Reservation，但没有正式 Outbox Dispatcher、Gateway 执行、模型输出、Metering、Settlement、Asset 或 Public Admission。

Core 保持一个仓库，但模块继续拥有独立 Command、Service、Repository、表、事件和权限。模块合仓不等于跨模块直接改表。

既有 GitHub Milestone保留为历史及可选同步链接；本机工作台负责当前任务、依赖和接收状态。

模块 Owner

本轮全流程：先统一调用需求、领域设计与原型

Owner：本人，负责需求、服务设计、原型、数据库/后台 API、文档和验收。通过本机工作台分配当前切片，按实施工作流关联需求→原型→接口→代码→证据。

消费者需求与待决策项

先列用户动作对应的 Command/Query、成功判据、等待/重放/失败体验和非目标。模块清单只定义目标所有权，不等于所有能力已经实现；优先复用已存在的准入、Catalog 和存储原语。

领域、数据、权限与错误设计

每个切片提交调用时序、聚合/表所有权、状态迁移和事务边界：谁读取、谁校验、谁写入，失败后哪些事实必须一起回滚。将领域终局与 Operations 投影状态分别标注；不可变事实的更正走追加记录。

权限矩阵同时列调用 Workload、业务主体、Tenant/Workspace/Project、Scope/Purpose 和响应字段裁剪；错误矩阵区分未提交、已提交但响应未知、可重试失败、冲突和权限拒绝。保存策略、分页上限、幂等键范围、数据库角色及迁移锁预算在设计中明确；未核定值保留待定，不凭计划赋予生产权限。

非 UI 原型与首轮验收

复用 B0 fixture，增加以合成数据驱动的时序/状态原型：准入→事件→候选投影→定向查询；为尚未实现的节点显式标注 stub。至少包含并发同键、Wallet/Run 乱序、提交后响应丢失、Gap/Quarantine、查询无权限和完整性未知。

原型产出为可复现输入、预期状态/错误、调用次数和事件关系；数据库模拟不能证明实际事务约束。B1 已有纯函数和资格入口可作为设计材料，保持生产 UoW 关闭。首轮验收需求范围、权威事实和消费者反馈是否一致，不把原型图中的节点计作服务上线。

后台 API 与文档清单

Core 仓维护其 HTTP OpenAPI、接口说明和运行示例，本人是维护 Owner；wire schema 引用固定 Contracts 并做一致性检查。每条 API 列协议版本、实现状态、Workload/Auth、错误状态码、分页/幂等（不适用也标明）、成功/拒绝/重放示例、变更和弃用记录。Docs 组织说明，不另写一份运行 DTO；内部接口不进入 Public API 目录。

后台实现切片与固定版本接入

1. 对齐既有存储修复与合并态证据，完成包资格接收记录，不重写 B0。
2. Append/Bootstrap：在同一业务事务生成 v2 配对事实和精确 Delivery；处理历史 v1、旧 Writer 排空与权限收口。
3. Dispatcher 与完整 Projector：复用已建 Repository/候选内核，补循环、租约恢复、原子 Receipt/Projection 与历史语义。
4. Shadow/Verifier/Cutover：实现独立完整性证明、切换及对称回滚；资格 fixture 不能替代生产语义 verifier。
5. Intake 可按其依赖单独实现；随后组合 Workforce Grant、Audit 和定向 Query，支持 Admin/Edge 的最小消费场景。
6. 最后组装 API/Worker，固定镜像、迁移包、运行身份与跨仓证据；B2 执行、计量和账务按后续里程碑推进。

需求设计与无副作用原型可先行；正式固定包消费遵守资格，运行路径接入仍须事务、角色与环境证据。数据库变化使用真实 PostgreSQL 覆盖最小权限、RC/RR 并发、SAVEPOINT、重放和迁移回滚；客户端 adapter 测试不替代该证明。发布前验证原 B0/Catalog 回归、独立进程 API/Worker 和恢复路径，服务上线不以 PR 合并单独判定。

仓库里程碑

CORE-1 已完成：受控 Run Admission

• 原 B0 基线使用 Contracts 0.2.0；主线升级 0.3.0 后继续回归既有准入语义；
• API Edge Workload JWT 与 Credential Snapshot；
• Organization-backed Tenant/Project/Model/Billing 校验；
• 不可变 Run Input/Manifest、credits Reservation、幂等与事务 Outbox；
• 真实 PostgreSQL 并发、约束与回滚测试。

该基线不开放公网，也不执行模型。

CORE-2 当前：Outbox 与 Operations

• 配对产生 Run/Wallet v2 与精确 Append-time Delivery Set；
• Dispatcher Claim/Lease/Fencing、Attempt、Receipt、Quarantine 与 published_at 受控更新；
• Event/Accepted Observation 幂等 Projector、Versioned Read Model 与 Shadow Rebuild；
• Workforce Grant Exchange、Private Query、完整性 Snapshot/Guard 与两阶段 Audit；
• API Edge Observation Intake 和 Admin Run Explorer 所需 BFF Contract。

详细阶段继续以既有 Operations 实施计划为规范；本页负责把它纳入多仓总控。

CORE-3：Execution、Metering 与 Billing

• Execution 创建 Attempt Manifest、消费 Gateway 结果并以不可逆 Closure 冻结完整 Attempt Set；
• Metering 独占 Eligibility、MeterEvent、ProviderCostFact 与 Settlement Input；
• Billing 通过 Purpose-bound Validation Bundle 在本地事务终局 Ledger/Reservation；
• 成功终局后的更正只追加 Transition/Exposure；
• 两类正式 Reconciliation Case 使用 Billing-authoritative Source/Resolution Fact；其他冲突保留 Owner-local Blocked Work。

CORE-4：Text Canary 与 Asset

• 固定一个 Organization、credits、Offering、Execution Target 与 Text Gateway 路径；
• 从 Admission 到 Attempt、Evidence、Metering、Billing 和 Output 全链路收敛；
• 成功 Output 登记 Asset Version/Lineage，失败或未知不创建伪 Asset；
• 为 Console /ai 与 Studio 提供最小 Product/Customer BFF Contract。

CORE-5：共享生态扩展

• Personal Space、企业治理、预算和订阅；
• Media Gateway、Drama、Commerce 与 FDE 私有交付；
• Agent Revision/Deployment、MCP Connection/Grant 和 Canvas Runtime；
• Public API 查询、取消、Webhook 与多模型能力。

数据与事务门禁

• 同一业务命令只有一个 Owner Repository 和幂等结果；失败不得留下部分事实。
• 跨模块原子行为使用明确事务协调；跨仓只通过版本化 Service/Event Contract。
• 在线 PostgreSQL 查询必须定向、有界并使用参数化 Repository；Operations 全量快照只用于显式重建/证明。
• Event、Manifest、Ledger、Asset Version、Receipt、Conflict Fact 与 Audit 等不可变对象不能原地修补。
• Personal Space 不能映射成 Organization 兼容；必须等待 tenant-aware 新版本和完整授权/账务门禁。

仓库验收

• 所有模块边界有依赖负向测试，禁止产品/Gateway 私有类型进入 Core 领域。
• 真实 PostgreSQL 覆盖唯一性、锁、CAS、事务回滚、租约失效、重放、乱序与并发。
• 每个跨仓 Read/Validate 都验证 Workload Audience、Purpose、Scope、完整四元组和摘要。
• 故障注入覆盖 Commit 后响应丢失、Consumer Ack 前后崩溃、未知 Provider 提交和 Billing 终局回滚。
• 每个批次登记固定 Commit、CI、Migration、Image Digest、SBOM、跨进程证据和回滚演练。

核心不变量见共享内核、钱包与商业系统和调度链路。