docs: full-chain AI SDK alignment design and impact map

[cunninghamcard-bit]

Summary

Design document for the full-chain AI SDK alignment (provider → model factories, call runtime, recording/replay, identity, four-layer message protocol), implementing the direction set by RFC-0036 (positioning and layered architecture). Per review, it is documentation under RFC-0036, not a new RFC: the two files live in docs/ next to ai-sdk-request-pipeline.md and take no RFC number.

• docs/aisdk-architecture-alignment.md — the design (Part I provider → model chain, Part II core message protocol).
• docs/aisdk-architecture-impact-map.md — appendix: 201 verified findings across 12 modules, cross-module coupling chains.
• docs/README.md indexes both.

Changes since the RFC draft (review on d8c3d15)

1. No RFC number. Moved to docs/; title and header rewritten. The header states the relation to RFC-0036 and that the file takes effect on merge (no "Accepted" status).
2. Which earlier commitments it keeps, adjusts or postpones — new §0.7 table, one row per ROADMAP / RFC-0036 item:
   • L2 choice: fixed to the AI SDK V4 shape; the 0.7 "L2 survey RFC" is withdrawn; "not frozen at 1.0" kept.
   • One-shot breaking switch (§9.1) vs. "old ABI coexists one minor": the switch itself has no coexistence period; the coexistence rule stays for the later ops-protocol ABI (0.8 C1). C2 forwarding shim and C4 cleanup are no longer needed.
   • ops protocol / stdio CLI / L0 passthrough: kept, sequenced after the switch (they build on the new handle model and the injectable Fetch).
   • B track (RFC-0032 / B1–B8): direction kept, form adjusted (vendor factories + descriptor-generated presets).
   • Auth level 1: registry auth spec and a single apply_auth #174/Auth level 2: credential resolution, CredentialStore, and a generic token refresher #175 auth: registry auth column kept as descriptor data; CredentialStore / TokenRefresher postponed with host callbacks.
   • Complete recording and replay (RFC-0023): protocol-generic replay, one record format, all bindings #167/aimux-cli follow-ups (RFC-0025): online mode and replay subcommand #179 replay: kept as replay_fetch at the transport leaf; "ProviderRecord = registry row + protocol" withdrawn.
   • Tool-call input boundary: type the raw/parsed distinction, drop the unused StreamingToolCallTracker #185: tracker is aligned and moved rather than deleted (feat(provider-utils)!: align StreamingToolCallTracker with the AI SDK and move it next to its users #204); ToolInput Raw/Parsed covered by Part II.
   • A2–A5, E1, Registry maintenance: weekly models.dev diff report and monthly reachability probe #170/Registry triage: 27 base_url disagreements and 116 missing providers vs models.dev #171, Cache probe (RFC-0015): track the §10 known limitations #180/Session aggregation follow-ups (RFC-0024): partial-match merging and debug CLI #181, S1/S2/S3/P, 0.9 governance: unaffected.
   • Second commit (78a2876), after RFC-0036: 补齐 roadmap 全节点设计与验收映射 #207 §12.2: the "old exports coexist one minor" rule is withdrawn rather than deferred (the cutover has no coexistence period, and the symbols replaced by the later ops ABI go on that cutover gate, RFC-0039); §3.3 / S4-7 record that xAI and Hugging Face keep Chat Completions only as an explicit chat_completions(id) extension outside the Provider trait.
     ROADMAP.md and rfc/0036-positioning-and-layered-architecture.md carry short notes pointing at §0.7 where their wording is adjusted (L2 survey RFC, Tool-call input boundary: type the raw/parsed distinction, drop the unused StreamingToolCallTracker #185 line, 0.8 coexistence sentence). The header lines and §4 of ROADMAP are untouched to stay clear of docs: 校准 roadmap 状态与近期依赖 #205.
3. Old wording fixed to the recorded decisions. §0.4 Q4, D18, §6.4 and §10 now all say host callbacks are postponed in every language (the Node TSFN / Python GIL bridges included). Part II's "two items pending" are written as conclusions (no aimux-protocol crate; JSON adaptation rules adopted). The impact map's §6.4 list of "decisions the RFC must make" now cites, per item, the section that settles it.

Decisions (§0.4, unchanged in substance)

1. No multi-step engine / tool execution / approval runtime — single-step core stays.
2. String models resolve via a local registry, never Vercel Gateway.
3. One-shot breaking cutover on an integration branch; no compat layers, migrations, or deprecated aliases.
4. Scope is cleanup + alignment + bug fixes; host callbacks in every binding and new capabilities are deferred.

Test plan

• Docs only; no code or CI changes.
• Relative links re-checked from docs/ (the ../reference/aisdk-review/... source links are unchanged from the draft and point at the local review checkout, as before).

🤖 Generated with Claude Code

https://claude.ai/code/session_01WGwanvo9WLU9HWD7sRR8TS

[eric8810]

先把文档状态和架构决策分开处理：

1. docs(rfc): RFC-0036 positioning and layered architecture #198 已合入 0036-positioning-and-layered-architecture.md，这里再次使用 RFC-0036，会造成编号和引用冲突。请调整为独立编号，并说明与现有 RFC / ROADMAP 的关系。
2. 新文档直接标为 Accepted、§0.4 标为已拍板，但当前 PR 没有对应讨论记录。请补充已有决策记录，并澄清其与已合入 ROADMAP 的关系，使文档状态与实际决策保持一致。
3. 架构上需要单独对齐：现有 ROADMAP 是 L0/L1 为真相、L2 独立版本化，旧 C ABI 至少共存一个 minor；这里是全链路 V4 对齐、一次性切换、不留兼容层。请列出哪些现有承诺保留、哪些撤销，以及迁移和发布影响，讨论后再同步 roadmap。

PR 先保持开放。编号/状态修正不等于接受或否决本方案，也不要让依赖栈默认替代这一步决策。

[eric8810]

合并前请把以下三处文档改一致：

1. 修改 RFC 编号。仓库已经有 RFC-0036，这份 RFC 请使用未占用的编号，并更新正文和附录中的引用。

2. 写清楚这份 RFC 替代哪些旧决策。当前 ROADMAP 和原定位 RFC 要求旧 ABI 至少共存一个 minor 版本，并将 L2 作为独立版本化的投影；这里改成全链路 V4 对齐和一次性 breaking 切换。请在本 PR 中列出被替代的章节，并同步修改旧文档中的对应说明。原路线图里的 L0 passthrough、stdio ops、auth 和 replay 计划，也请明确哪些保留、哪些调整或后置。不需要重新写整份路线图，但不能让相互矛盾的要求同时有效。

3. 按 §0.4 和 §0.5 已记录的决定，修正文中旧表述。§6.4、§10 仍有 Node/Python 宿主回调本期交付的说法，与全语言宿主回调后置不一致；文末也还有已经决定却仍写成“待拍板”的事项。请逐项改成最终结论。

这次要求是把已有决定写一致，不是重新讨论已经确定的方向。以上修改完成后再合并。

[cunninghamcard-bit]

按三点改好了，head 已更新：

1. 不占 RFC 编号：两个文件移到 docs/aisdk-architecture-alignment.md 与 docs/aisdk-architecture-impact-map.md，标题和头部重写，头部说明它是 RFC-0036 之下的实施设计、随合入生效，不再写 "Accepted"。
2. 替代哪些旧决策：新增 §0.7 表，逐项定性 ROADMAP / RFC-0036 的承诺——L2 选型（定为 AI SDK V4 形态，0.7 的调研 RFC 撤销，"不随 1.0 冻结"保留）、旧 ABI 共存一个 minor（本次切换没有共存期；该原则对之后的 ops ABI 仍然有效，C2 shim / C4 清理不再需要）、ops 协议 / stdio / L0 passthrough（保留，排在切换之后）、B 轨（方向保留、形式调整）、Auth level 1: registry auth spec and a single apply_auth #174/Auth level 2: credential resolution, CredentialStore, and a generic token refresher #175（registry auth 列保留为 descriptor 数据，CredentialStore/TokenRefresher 随宿主回调后置）、Complete recording and replay (RFC-0023): protocol-generic replay, one record format, all bindings #167/aimux-cli follow-ups (RFC-0025): online mode and replay subcommand #179（保留，就是 replay_fetch；"ProviderRecord = registry 行 + protocol" 撤销）、Tool-call input boundary: type the raw/parsed distinction, drop the unused StreamingToolCallTracker #185（见 feat(provider-utils)!: align StreamingToolCallTracker with the AI SDK and move it next to its users #204）。ROADMAP 和 RFC-0036 里被调整的那几句加了指向 §0.7 的注，没动 ROADMAP 头部和 §4，避开 docs: 校准 roadmap 状态与近期依赖 #205。
3. 旧表述：§0.4 Q4、D18、§6.4、§10 统一为"所有语言的宿主回调本期不做"（含 Node TSFN / Python GIL 桥接）；第二部分末尾两项"待拍板"改成结论；附录 §6.4 的 13 个问题逐条标注主文档落点。

§0.7 与 #207 增补的 §12.2 替代清单是逐行对应的，两边合入后再互相回链；#206–#212 里标为"待接受"的新增提案（0040 的 G2/G3、0042 的 T1–T5）不算本文的决定，§0.7 已注明。

第二个提交（78a2876）对着 #207 §12.2 再对了一遍：§0.7 和 ROADMAP 0.8 那句不再把“旧导出共存一个 minor”留给以后决定，直接撤销（切换没有共存期，之后 ops ABI 的旧符号也按 RFC-0039 的切换门一次替换，与 §12.2 的 C2 / C4 行一致）；§3.3 和驳回表 S4-7 写清 xAI / Hugging Face 的 Chat Completions 只作 trait 外的显式扩展保留（上游没有该入口，登记为产品差异），对应 §12.3 B5 行“撤销须明示”的要求。

另外去掉了之前顺带改 ci.yml 的提交：#203 / #204 已改到 master 上，不再需要。

---

Generated by Claude Code

[eric8810]

审核：Approve

前一轮 changes requested 的三项均已确认处理：无 RFC 编号（移入 docs/）、§0.7 逐项保留/调整/后置清单 + 旧文档加注、§0.4/§0.5/§6.4/§10 旧表述按已记录决定修正。

独立核验

对文中证据做了抽查（约 20 处 file:line 断言），全部精确属实，包括：

• FFI「40 个融合工厂」= 20 对 _new/_new_with_base；「123 个 extern C」= #[unsafe(no_mangle)] 计数
• 「7 处 == "groq"」、response_messages.rs:31 写死 ["anthropic","bedrock","amazonBedrock"]、TraceLayer scope_key 读 config_snapshot().base_url（layer.rs:166-184）
• as:STREAM-1（1 MiB 不可配）、pu:PU-5（空串 key 回落 env）、tl:TOOLS-1（web env: 任意变量）、bd:BIND-4（Python block_on 持 GIL）
• 附录统计自洽：201 = 51 redesign + 97 偏差 + 53 bug，逐模块求和对
• 主文档与 ROADMAP/RFC-0036 的加注互相回链、锚点有效；#185 相关行与 #204 一致

评审修复（22580ef）

按审核意见同步补充：

1. 补全附录 §6.4-14 缺失的裁定（原文件在此截断）：本期不提供 pull 式流式 ABI，C ABI 保持同步 + push callback，与异步 C ABI 一并后置
2. S5-1/S5-2 就地加注：2→3 迁移表与 rebuild_provider 两条扫描期建议已被 D24/§4.3/§4.4 否决，正文标注最终形态
3. 第二部分 ts-rs 建议加注：§0.5 已裁定不采纳（ts-rs 退役，descriptor + manifest 是唯一生成链）
4. 7 处指向 reference/aisdk-review 的可点击死链改为 AI:/A: 代码引用（reference/ 在 .gitignore，链接对其他读者 404）；证据约定注明本地检出
5. ROADMAP 0.6 表 B1+C2 行补加注（B1 形式调整、C2 shim 取消）；#185 两处嵌套括号展平；附录去重复 H1；Date 补修订记录

未动 ROADMAP §4（留给 #205）。