历史 · oceanway-api-edge 实施计划
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
仓库：Oceanway-AI/oceanway-api-edge。目标入口：api.oceanway.tech/v1。当前受控入口默认关闭公网。
当前实施入口
受控 Admission 和脱敏完成日志继续作为基线。Observation 的 PR #4 提供 README 与既有准入故障测试准备，尚无 sender，也未升级当前固定的 Contracts 0.2.0。不得把这些基线测试计作真实 Intake 联调。
首轮先补消费者需求、调用设计和无接线原型。正式接线需要 Contracts 资格、Core Intake method/path/Schema，以及环境身份、网络和并发/背压预算；缺项明确登记，不猜路由、replay 或 Token Audience。当前状态由本机工作台协调；既有 Issue #3作为历史及可选同步链接。
目标结果与当前基线
API Edge 的目标职责包括 Public API 的 DeveloperCredential 终止、协议校验、幂等要求、限流、低敏关联 ID、流式/异步协议和到 Core 的短期 Workload JWT；各能力按以下阶段交付。受控 POST /v1/responses Admission 已验收，但只返回 reserved，不产生模型输出。
Edge 无业务持久化，不保存 Credential/Digest/Snapshot、Run Input、余额、Run、Asset 或 Provider 事实；Raw Developer Secret 只在请求生命周期内到达 Edge。
本轮全流程：先统一开发者体验、调用设计与原型
Owner：本人，负责需求、服务设计、原型、后台 API、接口文档和验收。首轮产物在本机工作台登记，使用实施工作流的需求到验收对应关系。
消费者需求与待决策项
开发者需要知道请求是否被接受、何时可安全重试、如何关联一次调用及如何取得真实结果；Core 需要可信上下文而不接收 Raw Secret；运维需要低敏诊断且不影响业务响应。
本轮输出请求/响应旅程、错误恢复矩阵和最小协议范围。待决定项包括首批结果读取体验、未来同步/异步/流式范围、取消/超时含义，以及 Observation 允许的状态来源与资源预算。保留 reserved 的现有含义，不把它展示为文本已经生成或费用已经结算。
服务、数据和权限设计
画出 Header/Host 检查→Credential Snapshot→本地 Secret 校验→Core Admission→公共回执的既有时序，再单独画 best-effort Observation 分支。逐字段注明客户端输入、Edge 计算、Core 权威来源与日志白名单；不建立业务数据库或本地 replay 缓存。
设计错误映射表同时列公共 HTTP 状态、公共错误、submissionState、客户端下一步和允许观测字段。Observation 的失败、超时、凭据不可读和背压必须隔离；它不成为 readiness 必需依赖。缺少明确权威 replay 来源时保留未知；没有确认的 Audience/Scope/网络绑定时不发送。
无接线原型与首轮验收
复用真实 app 与现有 Core HTTP adapter 的注入 fetch 测试，用合成请求制作成功、拒绝、重复请求、未知提交、网络失败、慢响应和非法 Core 响应的回放台/fixture；原型只模拟尚未实现的 Observation Intake。
每个场景显示公共 status/body/关键 headers、lookup/admit 次数、状态来源与敏感字段排除结果。首轮验收的是开发者理解和不改变已有业务响应的设计；注入 TimeoutError 不算真实取消/超时验证，mock 调用次数不算数据库无重复 Reservation 的证明。
API 文档清单
| 接口/能力 | 当前范围 | 必须说明 |
|---|---|---|
POST /v1/responses | 已有严格 { model, input }，返回 202 reserved | API Key grammar、Host、Idempotency-Key、指纹版本与语义、公共错误及重放示例 |
GET /livez、GET /readyz | 现有探针 | Core/JWT 文件依赖和 503，Observation 不改变现有 readiness |
| Core Snapshot/Admission 调用 | 现有内部消费边界 | 引用 Core 接口说明与固定 Contracts，不在公共文档泄露 verifier/Workload 详情 |
| Observation sender | 未接线能力 | 先取得 Intake method/path/Schema、身份和预算，不发布猜测端点 |
| 结果、取消、流式、Webhook 等 | 后续需求设计 | 先明确 Core 能力和客户体验，再登记实际 HTTP 协议 |
Edge 仓拥有公共 HTTP OpenAPI 和错误/示例，本人维护；Schema 与固定 Contracts 校验一致，Developer Center/Docs 链接该版本化来源。文档逐接口记录 Owner、API/包版本、支持状态、鉴权、错误、幂等和分页适用性；当前准入无分页。Key 示例使用不可用合成值，公共文档不含 Credential Snapshot 或内部诊断。
后台切片、验证和发布
- 固化 B0 准入回归与首轮设计，保持 Contracts
0.2.0和默认 disabled。 - 上游条件齐备后升级精确正式包，实现独立 Observation port/mapper/client，再做最小 app 接线；不重写准入算法。
- 验证 Intake 接受/拒绝/冲突/purged、超时/取消、同步抛错/异步拒绝、背压/排空与响应隔离；真实 Core/Infra 联调补 JWT/JWKS 和无重复 Run/Reservation 证据。
- Text Canary/真实结果就绪后推进执行协议；再按里程碑加入公网限流、容量和其他 API。
- 固定服务镜像、契约版本、配置与回滚策略后进行环境验收；关闭 Observation 或新协议不撤销 Core 已接受事实，公网启用独立记录。
仓库里程碑
- EDGE-1 已完成基线：22/43 Credential Grammar、本地 SHA-256 constant-time 校验、强制
Idempotency-Key、V1 Canonical Fingerprint、Workload JWT 和稳定错误。 - EDGE-2 B1 Observation：提交低敏 Request/Error/Replay Observation；Intake 失败不改变客户响应，不建立 Prompt/Body Spool。
- EDGE-3 执行响应：在 Text Canary 完成后把
reserved扩展为真实异步 Run 查询与结果协议，不在 Edge 拼装业务终态。 - EDGE-4 公网安全：多实例分布式限流、IP/Scope 策略、WAF、滥用检测、完整 Telemetry 与容量压测。
- EDGE-5 API 扩展：模型目录、取消、Webhook、Embedding/Rerank、流式或兼容接口逐项按 Contracts 发布。
Observation 边界
- 只提交版本化低敏字段、请求时间和已有稳定关联 ID；不提交 Authorization、Raw Secret、Prompt、正文或签名 URL。
- Edge 没有 Durable Spool 或连续 Sequence，因此 Operations 只能声明“已接受记录范围”，不能声称请求全集完整。
- Producer 自报 Tenant、Run 或 Fingerprint 不能用于授权或业务终局；Core 只有在领域事实交叉验证后才建立关联。
- Observation Intake 不可用时客户业务请求仍按原结果返回，但 Edge 记录低基数健康指标。
公网进入门禁
- B1 可诊断链、B2 计量终局、B3 文本 canary 与正式 Asset 均通过；
- Customer-facing Run 状态、错误、费用和结果契约已发布；
- 多实例限流、容量、超时、断连、重放、Webhook/流式恢复与降级演练通过；
- Secret 扫描、日志脱敏、WAF、DDoS、密钥轮换和应急关闭 Runbook 完成；
PUBLIC_ADMISSION_MODE从disabled的改变由独立发布决策和证据控制。
验收与回滚
- 相同幂等键和语义只产生一个 Core Operation；异语义冲突不创建第二 Run。
- 无效/撤销 Credential、跨 Environment、Web-only/internal 模型和预算拒绝不产生部分事实。
- Edge 实例无状态，可水平扩展；重启不丢失业务真相，因为所有业务结果由 Core 持久化。
- 回滚先关闭新流量或协议版本，不撤销已经被 Core 接受的 Operation。
正式边界见Public API Runtime与ADR-029。