eric8810 · Oct 17, 2026 · Sep 29, 2026 · Sep 29, 2026 · Oct 11, 2026 · Oct 1, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -642,6 +642,8 @@ jobs:
       - uses: actions/checkout@v4
       - name: Providers doc generator drift (docs/api/providers.md must match generator output)
         run: python3 scripts/gen_providers_doc.py --check
+      - name: Provider boundaries (no call-level reads or provider-name branches in providers, removed names stay removed)
+        run: bash scripts/check_provider_boundaries.sh
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
         with:

diff --git a/.gitignore b/.gitignore
@@ -53,3 +53,6 @@ quirks-corpus/
 # Generated audit artifacts — keep conclusions in Markdown, not raw output.
 /docs/quality-audit/**/lcov.info
 /docs/quality-audit/**/*.log
+
+# AI SDK protocol fixture recorder (scripts/aisdk-fixtures) — npm install output
+scripts/aisdk-fixtures/node_modules/
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -9,8 +9,8 @@ to set up a development environment, run the tests, and submit changes.
 aimux/
 ├── aimux-core/            # Core abstractions: LanguageModel / Provider / Message / StreamPart
 ├── aimux-providers/       # provider implementations + cassettes (counts: docs/api/providers.md)
-├── aimux-stream/          # SSE parsing
-├── aimux-provider-utils/  # HTTP utilities: retry, backoff, error parsing, API-key loading, streamed tool-call tracking
+├── aimux-stream/          # SSE decoding
+├── aimux-provider-utils/  # HTTP utilities: Fetch transport, Resolvable settings, error parsing, API-key loading, streamed tool-call tracking
 ├── aimux-ffi/             # C ABI (opaque handle + JSON + push callback) for non-native bindings
 ├── bindings/              # Node, Python, Swift, Kotlin, Flutter, Go, C — share one Rust core
 ├── rfc/                   # Design docs (RFCs)
@@ -38,6 +38,20 @@ cargo fmt --all -- --check
 cargo clippy --workspace --all-targets -- -D warnings
 ```
 
+Provider changes also run the generator and boundary checks CI runs in the
+`contract-tests` job:
+
+```bash
+python3 scripts/gen_providers_doc.py --check  # docs/api/providers.md
+python3 scripts/gen_ts_types.py --check       # ts-rs types for the Node binding
+bash scripts/check_provider_boundaries.sh     # factory-shape rules for provider packages
+```
+
+The Node and Python bindings are separate workspaces: run `cargo fmt` and
+`cargo clippy -- -D warnings` inside each, then `npm ci && npm run build &&
+npm test` (Node) or `maturin build --release`, `pip install` the wheel and
+`python -m pytest tests/` (Python).
+
 ## Testing
 
 Tests run entirely on **cassette playback** — no network access and no API keys
@@ -62,10 +76,13 @@ aimux distinguishes three kinds of providers:
 1. **Native protocol** — providers with their own request/response model
    (OpenAI, Anthropic, Google, Bedrock, …). Implement the full `convert`/model
    path and handle provider-specific differences.
-2. **OpenAI-compatible thin wrapper** — the majority. Describe differences via
-   `OpenAICompatProfile` (top_k, tools, response_format, streaming usage,
-   request-body post-processing) so the thin wrapper does not erase
-   provider-specific behavior.
+2. **OpenAI-compatible preset** — the majority. One row of
+   `aimux-providers/src/provider_registry.json` (base URL, key variable or
+   `auth: none`, optional URL variable and template parameters) that
+   is embedded and parsed once into a runtime table. Create presets by name
+   through `provider(name, ...)`. Vendors with behavior of their own get a package on
+   the shared compatible chat model (`groq/`, `deepseek/`) instead of a
+   branch on their name.
 3. **Modality-specific** — speech, image, video, transcription, etc.
 
 Step-by-step checklists (with the generator and CI rules) live in

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
   <img src="assets/aimux-banner.png" alt="aimux banner" width="100%">
 </p>
 
-> **A unified LLM access layer written in Rust. One API for [327 AI providers](docs/api/providers.md).**
+> **A unified LLM access layer written in Rust. One API for [327 provider names](docs/api/providers.md).**
 
 [![CI](https://github.com/arcships/aimux/actions/workflows/ci.yml/badge.svg)](https://github.com/arcships/aimux/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -32,13 +32,10 @@ For planned milestones and their current status, see the [roadmap](ROADMAP.md).
 
 ## Why aimux
 
-- **327 providers** (as of 2026-09-24) — 251 registry-backed OpenAI-compatible
-  (unified `provider(name, ...)` entry) + 76 typed providers (native protocol
-  implementations such as OpenAI/Anthropic/Google/Bedrock/Vertex, local
-  engines like Ollama/vLLM, and speech/image/video/search modality providers).
-  Counts by category and the full list live in
-  [docs/api/providers.md](docs/api/providers.md) — generated, and the single
-  source of truth for provider counts (only the badge above repeats the total).
+- **327 provider names** — 282 registry-backed OpenAI-compatible presets
+  + 45 vendor packages, covering text and other modalities. Local engines
+  such as Ollama/vLLM are presets. `provider_names()` lists the Rust names;
+  the generated catalogue lives in [docs/api/providers.md](docs/api/providers.md).
 - **Unified, object-safe interface** — the `LanguageModel` trait supports
   `Box<dyn>` so providers are interchangeable without changing call sites.
 - **Full multimodal** — text, streaming, tool calling, embeddings, image,
@@ -51,10 +48,12 @@ For planned milestones and their current status, see the [roadmap](ROADMAP.md).
 - **Composite models** (new in 0.3.0) — `RouterModel` routes each call with
   fallback (RFC-0021); `MoaModel` aggregates parallel reference models
   mixture-of-agents style (RFC-0022). Both are plain `LanguageModel`s.
-- **Config-driven provider registry** — `provider-registry.json` describes
-  each registry-backed OpenAI-compatible provider (base URL, env var, profile
-  quirks: top_k, tools, response_format, streaming usage, max_tokens key);
-  one unified `provider(name, ...)` entry in every binding.
+- **Config-driven provider registry** — `provider_registry.json` describes
+  each registry-backed OpenAI-compatible provider (base URL, env var, auth
+  mode, template parameters); the embedded JSON is parsed once into a runtime
+  descriptor table. Rust uses `create_provider(name, PresetSettings)` for
+  presets and vendor packages; bindings retain `provider(name, ...)`.
+  Packages follow the AI SDK shape: `XxxProviderSettings` + `create_xxx()` + a default `xxx()`.
 - **Fast and small** — Rust core, release profile tuned for binary size
   (`lto`, `codegen-units=1`, `panic="abort"`, `strip`, `opt-level="z"`).
 - **8 language bindings** from one core: Node, Python, Swift, Kotlin, Flutter,
@@ -150,14 +149,12 @@ console.log(result.text)
 
 ```rust
 use aimux_core::prelude::*;
-use aimux_providers::{OpenAIConfig, OpenAIProvider};
+use aimux_providers::openai::openai;
 
 #[tokio::main]
 async fn main() -> Result<(), AiMuxError> {
-    let provider = OpenAIProvider::new(
-        OpenAIConfig::new(std::env::var("OPENAI_API_KEY")?)
-    );
-    let model = provider.model("gpt-4o");
+    // The default provider loads OPENAI_API_KEY when a request is made.
+    let model = openai().chat("gpt-4o");
 
     let result = generate_text(
         &model,
@@ -222,9 +219,10 @@ use aimux_core::moa::{MoaConfig, MoaModel};
 use aimux_core::router::{FallbackPolicy, RouterConfig, RouterModel, RuleRouter};
 
 // Router: pick one model per call, fall back on failure (RFC-0021).
+let provider = aimux_providers::openai::openai();
 let children: Vec<ChildModel> = vec![
-    Arc::new(provider.model("gpt-4o")) as ChildModel,
-    Arc::new(provider.model("gpt-4o-mini")) as ChildModel,
+    Arc::new(provider.chat("primary-model-id")) as ChildModel,
+    Arc::new(provider.chat("secondary-model-id")) as ChildModel,
 ];
 let routed = RouterModel::new(
     children.clone(),
@@ -236,7 +234,7 @@ let routed = RouterModel::new(
 // MoA: fan out to references, aggregate their answers (RFC-0022).
 let moa = MoaModel::new(
     children,
-    Arc::new(provider.model("gpt-4o")) as ChildModel,
+    Arc::new(provider.chat("primary-model-id")) as ChildModel,
     MoaConfig::default(),
 );
 
@@ -275,35 +273,36 @@ session.close()
 ## Switch providers
 
 ```rust
-// OpenAI → DeepSeek: only the provider name changes (registry-backed;
-// key read from the provider's env var)
-use aimux_providers::{provider, provider_from_env};
+use aimux_core::provider_registry::create_provider_registry;
+use aimux_providers::{create_provider, default_providers, provider_names, PresetSettings};
 
-let model = provider("deepseek", None, "deepseek-chat", None)?;
-let model = provider_from_env("deepseek", "deepseek-chat", None)?;
+// Keys are loaded when a request is made.
+let provider = create_provider("deepseek", PresetSettings::default())?;
+let model = provider.language_model("deepseek-chat")?;
+
+// Or assemble the built-in providers and resolve a provider:model id.
+let registry = create_provider_registry(default_providers(), Default::default());
+let model = registry.language_model("deepseek:deepseek-chat")?;
+let names = provider_names();
 // model usage is identical — it's all dyn LanguageModel
 ```
 
-All registry-backed OpenAI-compatible providers share one entry:
-`provider(name, ...)` in every binding. Provider names are runtime strings;
-the generated provider list is the discovery surface.
-The retired per-provider shell types (`XxxConfig`/`XxxProvider`) are gone —
-see [docs/API.md](docs/API.md#providers).
-
-> **Scope:** OpenAI-compatible → `provider(name, ...)`; others (Anthropic,
-> multimodal, local…) → their constructors. List:
-> [docs/api/providers.md](docs/api/providers.md).
+Rust by-name creation covers vendor packages and all 282 presets. Each vendor
+also has `create_xxx(XxxProviderSettings {..})` and a default instance `xxx()`.
+Bindings keep their own `provider(name, ...)` API. Runtime model listing uses
+`Provider::discovery()` and then `ProviderDiscovery::list_models()` — see
+[docs/api/rust.md](docs/api/rust.md#providers).
 
 ## Provider coverage
 
-Counts by category live in
-[docs/api/providers.md](docs/api/providers.md#totals) — generated from the
-registry and `lib.rs`, and the single source of truth. The rough shape of
+The generated catalogue is [docs/api/providers.md](docs/api/providers.md).
+The accepted Rust names come from `provider_names()`. The rough shape of
 the roster:
 
-- **Native protocol** — OpenAI, Anthropic, Google, Bedrock, Vertex, Azure, Cohere, Mistral, xAI, Anthropic-AWS, Voyage, Codex, OpenRouter
-- **OpenAI-compatible (registry-backed)** — Groq, Fireworks, Together, Perplexity, Ollama Cloud, DeepSeek, Alibaba Tongyi, Zhipu, Baidu, Tencent, Moonshot, SiliconFlow…
-- **OpenAI-compatible (standalone + Vertex-hosted)** — Hugging Face, Ollama, vLLM, SGLang, Llama.cpp, LiteLLM Proxy, Vertex-hosted DeepSeek/Qwen/Llama…
+- **Native protocol** — OpenAI, Anthropic, Google, Bedrock, Vertex, Azure, Cohere, Mistral, Groq, DeepSeek, xAI, Anthropic-AWS, Voyage
+- **OpenAI-compatible (registry-backed)** — Fireworks, Together, Perplexity, OpenRouter, Ollama Cloud, Alibaba Tongyi, Zhipu, Baidu, Tencent, Moonshot, SiliconFlow…
+- **Local and Vertex-hosted presets** — Ollama, vLLM, SGLang, Llama.cpp, LiteLLM Proxy, Vertex-hosted DeepSeek/Qwen/Llama…
+- **Responses API for text** — xAI and Hugging Face (no chat-completions entry)
 - **Speech / transcription** — ElevenLabs, Deepgram, AssemblyAI, AWS Polly, Cartesia, Hume, Gladia, RevAI, LMNT, Fal
 - **Image / video** — Black Forest Labs, Replicate, Luma, Prodia, KlingAI, Recraft, Stability, RunwayML
 - **Embeddings / rerank / search** — Voyage, Jina, Tavily, Exa, Firecrawl, Serper, SearXNG, You.com…

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -35,7 +35,7 @@ aimux 是 **provider 接入与治理的运行时**：
 │   ├─→ #174 Auth L1 ──→ #175 Auth L2          ← 依赖 B1
 │   └─→ #167 transport-level replay ──→ #179 replay 子命令   ← 依赖 B1
 ├─ C 轨 FFI（现 123 个 extern "C"，#166 基线 109）→ ops 协议（C1 升级为传输无关协议：op 表 / 二进制帧 / 版本协商）
-│   └─ C2 构造器转发 shim 是 B4/B5 前置
+│   └─ C2 构造器转发 shim 取消：B4/B5 的直接构造调用点随 provider 工厂切换一次迁移（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)）
 ├─ D 轨 8 种绑定重写为 ops 薄封装（依赖 C1）+ D8 类型镜像生成
 ├─ E 轨 内部清理（#164 已合入，改为 master 上独立 PR）+ 文档三层重组
 │
@@ -75,12 +75,12 @@ aimux 是 **provider 接入与治理的运行时**：
 | 项 | 内容 |
 |---|---|
 | B2–B8 | 17 个 LanguageModel 实现 → ~7 个协议；33 个 wrapper 退役；responses 家族合并（遵循 #166 修正 3/6） |
-| #174 / #175 | registry `auth` schema + `apply_auth()`；Credential 解析序 + CredentialStore + TokenRefresher |
+| #174 / #175 | registry `auth` 列作为 preset descriptor 数据，鉴权在各厂商包内以 headers 闭包 / fetch 装饰器实现；CredentialStore + TokenRefresher 随宿主回调后置（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)） |
 | L2 补齐 | `StreamPart::Raw` / `provider_metadata` 在各协议接线——投影不下的不得静默丢弃 |
 | **S3** | `cargo-bloat` 审计 0.5.0 增重（Android `.so` 13.4 → 21 MB）；feature gating 仅作可选小体积路径，默认全量 |
 | ~~调研 RFC~~ | ~~L2 数据模型选型（AI SDK 形态 / Open Responses items / 自有），指标见 RFC-0036 §3~~ 撤销：选型已定为 AI SDK V4 形态（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)） |
 
-版本语义：Rust API 大 breaking（33 wrapper 退役）；C ABI 经 C2 转发不受影响。
+版本语义：Rust API、binding wire 与 C ABI 在全链路对齐切换时一次性 breaking（33 wrapper 退役、构造器替换），不经 C2 转发（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)）。
 
 ### 0.8.0 ——「ops 协议落地」（~4-5 周）
 
@@ -92,13 +92,13 @@ aimux 是 **provider 接入与治理的运行时**：
 | D8 | 类型镜像生成：serde → JSON Schema → 各语言，`--check` 门禁扩到全部输出 |
 | P | stdio 入口往返开销纳入性能门禁 |
 
-版本语义：新 ABI 加入，旧导出并存（#166 要求共存至少一个 minor 版本）；绑定按各自节奏迁移。“共存至少一个 minor”不再作为承诺：全链路对齐切换本身没有共存期，之后 ops ABI 引入时的旧符号也按切换门一次替换；C2 转发 shim 与 C4 旧导出清理随之取消（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)）。
+版本语义：新 ABI 按切换门一次替换旧符号，不提供共存期（#166 原要求的“共存至少一个 minor”撤销）；全链路对齐切换本身同样没有共存期，C2 转发 shim 与 C4 旧导出清理随之取消（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)）。
 
 ### 0.9.0 ——「治理」（~3-4 周）
 
 | 项 | 内容 |
 |---|---|
-| #167 | transport-level replay：mock 挂 HTTP 层跑真协议代码，覆盖全协议 / 全模态；`ProviderRecord` = registry 行 + protocol |
+| #167 | transport-level replay：mock 挂 HTTP 层跑真协议代码，覆盖全协议 / 全模态；录制只存身份，不保存可重建的 `ProviderRecord`（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)） |
 | 漂移检测 | #170 扩展：定期重录，与 cassette 字节级 diff |
 | 能力矩阵 | provider × 能力，每格由探测或录制支撑；后置到全链路对齐迁移之后（见 §6.1） |
 | CLI | `aimux probe / replay / diff`（#179 replay 子命令并入）；#181 debug CLI 并入 |
@@ -107,7 +107,7 @@ aimux 是 **provider 接入与治理的运行时**：
 
 | 项 | 内容 |
 |---|---|
-| C4 | 8 种绑定全部迁移后删除旧导出、旧头文件、旧 FFI 测试 |
+| ~~C4~~ | ~~8 种绑定全部迁移后删除旧导出、旧头文件、旧 FFI 测试~~ 取消：旧导出在切换时随绑定一起删除，1.0 不再补删（调整：见 [docs/aisdk-architecture-alignment.md §0.7](docs/aisdk-architecture-alignment.md#07-与-roadmap--rfc-0036-既有承诺的关系)） |
 | 冻结范围 | ops 协议与 L0 / L1 契约。**L2 独立版本化，不随 1.0 冻结** |
 | 发布判据 | #166 ledger 全勾（B9 / #171 后半除外）；错误模型 #95 与请求管线 #164 稳定一个周期；各门禁（S2 / P）连续绿 |
 

diff --git a/aimux-core/Cargo.toml b/aimux-core/Cargo.toml
@@ -32,6 +32,7 @@ httpdate = { workspace = true }
 rand = { workspace = true }
 base64 = "0.22"
 jsonschema = { workspace = true }
+regex = "1"
 
 [dev-dependencies]
 tokio = { workspace = true, features = ["macros", "rt", "test-util"] }

diff --git a/aimux-core/src/composite.rs b/aimux-core/src/composite.rs
@@ -10,9 +10,9 @@
 //! - [`ChildModel`] — the child-handle shape (`Arc<dyn LanguageModel>`).
 //! - `step_context` — the recording context of one child step.
 //! - `child_max_retries` — the operation's retry count for a child call.
-//! - [`add_usage`] — per-field `Usage` accumulation.
-//! - [`extract_text`] — pull text out of a `GenerateContent` list.
-//! - [`build_aggregator_prompt`] — assemble the MoA aggregator prompt.
+//! - `add_usage` — per-field `Usage` accumulation.
+//! - `extract_text` — pull text out of a `GenerateContent` list.
+//! - `build_aggregator_prompt` — assemble the MoA aggregator prompt.
 //!
 //! See [`crate::trace::layer::TraceLayer`] for the established decorator pattern
 //! (`inner: Arc<dyn LanguageModel>` implementing `LanguageModel`); composite
@@ -43,7 +43,8 @@ pub(crate) fn step_context(step: impl Into<String>) -> Option<RecordingContext>
 
 /// The retry count of a child call: the `max_retries` of the operation the
 /// composite runs in ([`OperationSettings::current`]). `None` outside an
-/// operation, or when the operation sets none, leaves the child's default.
+/// operation, or when the operation sets none, retries twice, the AI SDK
+/// default.
 pub(crate) fn child_max_retries() -> Option<u32> {
     OperationSettings::current().and_then(|settings| settings.max_retries)
 }
@@ -54,7 +55,7 @@ pub(crate) fn child_max_retries() -> Option<u32> {
 /// Each usage detail field is `Option<u32>`; `None` is treated as zero so a
 /// child that doesn't report a breakdown doesn't erase the other child's data.
 #[must_use]
-pub fn add_usage(a: Usage, b: &Usage) -> Usage {
+pub(crate) fn add_usage(a: Usage, b: &Usage) -> Usage {
     Usage {
         input_tokens: InputTokenUsage {
             total: opt_add(a.input_tokens.total, b.input_tokens.total),
@@ -84,7 +85,7 @@ fn opt_add(a: Option<u32>, b: Option<u32>) -> Option<u32> {
 /// are kept; `Reasoning` / `ToolCall` / `Source` / `File` are dropped (MoA
 /// thin version — references contribute analysis text, not tool calls).
 #[must_use]
-pub fn extract_text(content: &[GenerateContent]) -> String {
+pub(crate) fn extract_text(content: &[GenerateContent]) -> String {
     let mut out = String::new();
     for c in content {
         if let GenerateContent::Text { text, .. } = c {
@@ -103,7 +104,7 @@ pub fn extract_text(content: &[GenerateContent]) -> String {
 /// The reference list may be empty — in that case the aggregator just runs the
 /// original prompt (degenerates to a single-model call).
 #[must_use]
-pub fn build_aggregator_prompt(
+pub(crate) fn build_aggregator_prompt(
     prompt: &LanguageModelPrompt,
     instructions: Option<&str>,
     references: &[(String, String)],