澄清 AI Gateway adapter contract、clone semantics 与 resilience model

[xiaoland]

摘要

AI Gateway 需要从“内部重构但不清晰收口”推进到可执行的 hard cutover：

• 继续保持 chat capability surface 最小且语义稳定。
• 将 context control 收敛到高层语义操作（derive_context / rewrite_context），不再暴露 legacy clone primitive。
• 明确 route alias 与 route key 的边界，避免 route 选择输入与持久化路由身份混淆。
• 在不引入虚假抽象层的前提下增强 thread-level observability lineage。

范围更新（相对原 issue 的补充）

本 issue 现在覆盖 strict issue-17 之外的 follow-up 方向，作为同一 working set 的收口任务：

1. Canonical Route Contract 收口

• 区分 ChatRouteAlias（人类可选别名）与 ChatRouteKey（解析后稳定身份）。
• API 输入使用 route_ref（alias/key union），而不是把 alias 与 key 混作一个字符串语义。

2. Context Control Hard Cutover

• 引入并采用高层请求族：ThreadContextRequest。
• 以语义 sibling operation 承载上下文管理：
  • derive_context(...)
  • rewrite_context(...)
• 删除 legacy approach：clone_thread_with_turns(...) 不再作为公共迁移路径保留。
• 要求 turn identity 稳定：derive/rewrite 保留 surviving turn_id，不做 reindex。

3. AI Gateway Observability 增强

• 保持 family 不变：
  • ai-gateway.request
  • ai-gateway.chat.turn
  • ai-gateway.chat.thread
• 在线程族增强 lineage/context-control 语义字段（可选字段，非破坏）：
  • source_thread_id?
  • source_turn_ids?
  • kept_turn_ids?
  • dropped_turn_ids?
  • continuation_dropped?
  • context_reason?

保持不变的约束

• 不因为命名对称新增装饰性抽象。
• provider context 仍然 explicit + default-deny。
• runtime-only metadata 不得隐式进入 provider-thread 可继承上下文。
• 除非有独立 issue 与契约更新，不扩张 chat capability surface。

验收标准（更新后）

• clone_thread_with_turns(...) 从公共迁移路径中删除，Cortex 侧迁移完成。
• context control 统一通过 derive_context(...) / rewrite_context(...)，并有明确 request/result 语义。
• alias/key contract 不再混淆：route 输入与 resolved route identity 明确分离。
• ai-gateway.chat.thread 能表达 parent vs derived/rewrite lineage，且不新增虚假 observability 层。
• turn identity 在 derive/rewrite 场景保持稳定（不 reindex）。

非目标

• 不在本 issue 内引入 rich provider-context channel。
• 不在本 issue 内重做 phase-aware streaming/resume retry 架构。
• 不在本 issue 内扩展 asr / tts 公共契约。

参考

• 相关 Cortex integration issue：重构 Cortex 拆分结构，以提升可维护性并明确 Primary / Attention / Cleanup 所有权 #14
• 本 issue 的 working set：tasks/issue-17-ai-gateway-architecture-20260401/*