oceanway-api-edge 实施计划

api.oceanway.tech/v1 机器凭据终止、Public API 协议与低敏观测仓库的实施计划

仓库：Oceanway-AI/oceanway-api-edge。目标入口：api.oceanway.tech/v1。当前受控入口默认关闭公网。

目标结果与当前基线

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。

仓库里程碑

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。