feat(providers)!: AI SDK-shaped provider factories, request layer and replay tests

[cunninghamcard-bit]

What

Moves provider construction, the shared request layer and their callers to package factories shaped by the AI SDK. It also adds the fixtures/aisdk samples, the factory replay tests and the migration documentation. Core, provider-utils, vendor packages, FFI, bindings, CLI, web console and replay change together because they share these interfaces. Base rfc-0036/provider-result-types (A); follows A, precedes C. Replaces #222, #223, #224 and the previous content of #214.

Layers

Branch	PR	Content	Diff against its updated base
rfc-0036/factory-test-removal	#222	Deletes four hand-written test files; no source or type changes	4 files, 1594 deletions(-)
rfc-0036/upstream-samples	#223	Adds the fixtures/aisdk sample set	29 files, 3440 insertions(+)
rfc-0036/provider-factory-source	#224	Factories, request layer, callers; restores and migrates upstream-ported tests	435 files, 36665 insertions(+), 24801 deletions(-)
rfc-0036/provider-factory	#214	Factory replay tests, helpers and documentation; no production source changes	34 files, 4277 insertions(+), 387 deletions(-)

Before and after

Area	Before	After	Upstream reference
Deleted tests	Tests of registry construction and configuration, profile and body overrides, the realtime WebSocket stream, the Node-to-Rust HTTP path	Deleted: aimux-providers/tests/config_snapshot_test.rs, reasoning_map_test.rs, openai_transcription_stream_test.rs, bindings/node/__test__/body_overrides.test.ts	openai-provider.ts; provider request modules; openai-transcription-model.ts
Samples	No fixtures/aisdk	Reconstructed JSON inputs, requests, responses and results for Anthropic messages, Google generation and embeddings, OpenAI chat, responses and embeddings, compatible chat and embeddings; not verbatim upstream payloads	@ai-sdk/anthropic, google, openai, openai-compatible
Sample versions	No manifest	VERSIONS.json: ai 7.0.127 with matching @ai-sdk/*; the local reference checkout for ported tests is 7.0.122	Package manifests
Construction	Previous model construction paths and provider-specific setup	Package create_* factories, settings and default instances create models through Provider. create_provider, provider_names, default_providers assemble factories and compatible presets (an aimux extension)	createOpenAI, createAnthropic and other package provider modules
Docs	Config builders and older by-name exports; Chat Completions as default; base-URL variables unread; reasoning option as reasoning_format	Package settings and factories, create_provider(name, PresetSettings), provider_names(), default_providers(), Provider::discovery() (discovery is an aimux extension); option is provider_options.groq.reasoningFormat, converted to reasoning_format	groq-chat-language-model-options.ts
OpenAI default	FFI, Node, Python chose chat; Rust factory chose Responses	Provider::language_model and call select Responses; chat selects Chat Completions explicitly; Responses factory supplies the file- prefix	openai-provider.ts
Settings	Extra resolvable keys or request transforms; supported hooks missing	OpenAI, Anthropic, Google, Mistral, Cohere, Groq, DeepSeek, xAI and OpenAI-compatible use static Option<String> keys and header maps; env-key fallback loads at request time; Azure and PresetSettings keep resolvable keys, Azure also a token provider; Mistral, Cohere, Anthropic expose generateId	Provider settings modules
Base URL, auth	Docs implied every package loaded an env key and sent an empty key	OpenAI, Anthropic: explicit base URL, then OPENAI_BASE_URL or ANTHROPIC_BASE_URL, then default; an explicit empty key does not fall back to env. OpenAI-compatible reads no env key and sends no authorization for a missing or empty key	openai-compatible-provider.ts
Compatible requests	URL support and usage conversion not suppliable; body transform reached other modalities	OpenAICompatibleProviderSettings has supported_urls, convert_usage; transform_request_body applies to chat only; Groq and DeepSeek have own settings and conversion	openai-compatible-provider.ts
Request execution	Transport and retry mixed into providers	provider-utils holds injectable fetch, resolvable values, response handlers, media-type detection; Core owns call retry; redirects followed only within the issuing origin; User-Agent suffixes append	withUserAgentSuffix, postToApi
Azure auth	Token resolved before header merge	A caller Authorization header suppresses token resolution	azure-openai-provider.ts
Registry, middleware	No caller-assembled registry; incomplete wrapping	create_provider_registry splits IDs at the first separator and applies language and image middleware; wrappers accept ID overrides; language hooks get generate and stream callbacks; NoSuchProvider carries provider ID, model ID, model type, available providers	createProviderRegistry, wrapLanguageModel, wrapImageModel, NoSuchProviderError
Conversions	Anthropic iteration metadata lost fields; Mistral merged choices; fallback file representations	Anthropic keeps iteration model and cache fields, custom-name metadata conditional on options; Mistral reads the first choice and assembles tool-call fragments; Cohere and Mistral detect bare image media types; Bedrock converter rejects unsupported tool-content files	anthropic-language-model.ts, mistral-chat-language-model.ts
Replay headers	Replays removed user-agent	Replays expect the suffixes	with-user-agent-suffix.ts

Vendor option schemas live in each package: the shared OpenAI-style parser takes its schema from the caller; OpenAI, Azure, Groq, DeepSeek own theirs in options.rs; Anthropic spells its namespace and skill type once there. The files model exposes no specification version, as scripts/check_provider_boundaries.sh requires. TypeScript-only constraints (JSONSchema7, dotted IDs, URL, Date, numbers) are not enforced upstream at runtime; Rust keeps Value, String, u32.

Tests

• Delete the four hand-written files above; no replacements. Cassette replays are kept.
• Migrate the sixteen upstream-ported embedding, image, speech, transcription, files and video test files to the factory API. Restore the DeepSeek strict-option cases. Delete hand-written tests in anthropic/options.rs and provider-utils fetch.rs, and the hand-written DeepSeek namespace and env-key cases; no bedrock_factory_test.rs or ws_connector_test.rs remains.
• The OpenAI, OpenAI-compatible, Anthropic and Google factory suites read fixtures/aisdk through the shared mock-fetch helper. The samples are recordings: scripts/aisdk-fixtures/record.mjs runs ai and @ai-sdk/* over a mocked fetch and writes the request sent and the normalised result. Requests and results are upstream behaviour; response bodies are fixed inputs. Replays check agreement with these records, not upstream test payloads.
• The DeepSeek cassette replay is kept. The fetch-injection suite keeps its guarded-download test: validated downloads use the fixed guarded transport, a security decision. Hand-written preset and Node provider-config tests remain.
• Cassettes are unchanged. Not every remaining hand-written test is removed or every upstream case ported.
• create_provider with an unknown name reports every built-in name in NoSuchProvider.available_providers. Before dfe9a453 the miss fell through to preset::create, which lists only the registry rows, so a misspelled openai got a list without any of the 45 vendor packages. Unit test: default_providers::tests::an_unknown_name_lists_every_built_in_provider.

Not in this pull request

• Serde naming, the by-name entries in aimux_providers::provider, and the call-layer ModelMessage tool-result shape: covered by D.
• Samples stay as recorded. Aligning the recorder pin, covering the other eight packages and scheduled re-recording are follow-up work.
• Google speech, transcription and evaluation; xAI speech, transcription and video; Groq transcription; Mistral speech and transcription; registry evaluationModel and customProvider: covered by C. xAI image and files, and OpenAI skills, are not ported.
• Vertex application default credentials, Azure/Vertex transcription routing, Azure Foundry Responses explicit message-item typing, Groq first-SSE-error handling: covered by C.
• specificationVersion stays omitted by the public-surface decision. Search, discovery and built-in assembly are aimux extensions, not parity claims.

Relation to the maintainer's design

Reference order: the pinned AI SDK source first; where it has no counterpart (C ABI, bindings, recording, code generation), the maintainer's RFCs 0039 (ops and bindings, #209), 0040 (provider construction and auth, #210), 0041 (replay governance, #211) and 0042 (V4 type boundaries, #212), which are Drafts that refine the #200 design doc docs/aisdk-architecture-alignment.md; that design doc only where those RFCs defer to it or are silent. Where an RFC restates upstream behaviour differently from the pinned source, upstream wins and the RFC gets an amendment request. The stack targets rfc-0036/integration; RFC-0039 §11 and RFC-0040 §7.2 require the whole closure to switch to master at once, so items marked "before master" must land on integration first. "Branch E" is the follow-up branch stacked on D, in progress.

• Recording schema 3 (implemented in branch E). This PR sets RECORDING_SCHEMA to 3 with input, provider: ProviderRecord { provider_id, provider, model_id }, exchanges, outcome, complete, transport_closed. It drops the configuration snapshot, but it is a subset of RFC-0041 §4's schema 3: target (model reference and identity), operation, capture_policy and Captured values, model_calls, exchange id/phase/boundary/timing, ws_sessions and replayability are missing, and it identifies the provider through ProviderRecord instead of §4.1's target; RFC-0041 §2 drops ProviderRecord as a replay mechanism. Mock replay still decodes recorded OpenAI bodies in aimux-core/src/replay.rs (rebuild_generate_result) instead of RFC-0041 §3's ReplaySession with replay_fetch / replay_web_socket running the real provider converters. Branch E replaces it with RFC-0041's schema 3 and replay, so no file with this subset ships under the number 3.
• Package descriptors and provider registration (implemented in branch E). RFC-0040 §2.1–2.2: package descriptor, ProviderRegistration (provider + extensions + metadata), pure-assembly providers_from_config(document). This PR has create_<vendor> factories, default_providers and create_provider(name, PresetSettings), which returns Arc<dyn Provider>; named methods such as chat, responses and completion exist only on the concrete provider types and are lost through it.
• Fixture governance (with the schema 3 work in branch E). RFC-0041 §5 (Draft): fixture manifest with source=synthetic|approved_capture, redaction policy and review status. The 28 fixtures/aisdk samples carry only VERSIONS.json; the 2,799 cassettes keep their format.
• One-shot breaking change (agrees). No forwarding, old-config or old-recording reading (RFC-0039 §0.1.9, RFC-0040 §7.2, RFC-0041 §2).

Verification

Gate on the head 419ac220: cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, cargo doc with -D warnings, tests of core, provider-utils, providers, ffi, web, replay and cli: 2,437 passed, 0 failed, 6 ignored; Node and Python bindings cargo check; provider boundary script; gen_ts_types.py --check; gen_providers_doc.py --check. Cassettes unchanged; the 29 files under fixtures/aisdk are added. Diff against the base: 502 files changed, 44382 insertions(+), 26782 deletions(-). After the restack onto the current master, only this head was tested; the intermediate layers were checked with fmt and clippy only.

Restacked head 78c9a41f. Restack (2026-10-09): merged master (#213, SSE) and the rewritten #204 tracker down the stack by merge, no history rewrite. This layer ports the groq, deepseek, mistral and openai_compatible call sites to the new tracker API (the openai_compatible thought signature now travels as StreamingToolCallDelta::provider_metadata). Checked: cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, tests of provider-utils and providers (107 test binaries, 0 failed). cargo doc, binding checks and the generator --check scripts were not rerun.

Fix dfe9a453 (merged into head 9bd3da58): the new unit test passed on provider-factory-source, on this head, and after merging into wire-format. presets_test and cargo clippy -p aimux-providers --all-targets -D warnings were run on provider-factory-source. The full gate above was not rerun.

Not verified

No GitHub check runs were attached at the last refresh. Go, Java, Kotlin, Swift and Flutter were not compiled locally in that refresh; Node npm test and Python pytest were not run. Live vendor calls and unported upstream cases are outside validation.

🤖 Generated with Claude Code

[cunninghamcard-bit]

[P1] Correct the HMAC derivation in the moved SigV4 signer

This is inherited from the previous Bedrock signer rather than a new regression in the refactor, but the shared SigV4Fetch still produces signatures that do not match AWS SigV4.

hmac_sha256 takes (key, data). The calls at lines 169–178 reverse those arguments at every step, including the final signature, and omit the AWS4 prefix on the secret. With the current helper, the correct order is:

let k_date = hmac_sha256(
    format!("AWS4{}", credentials.secret_access_key).as_bytes(),
    date_stamp.as_bytes(),
);
let k_region = hmac_sha256(&k_date, credentials.region.as_bytes());
let k_service = hmac_sha256(&k_region, service.as_bytes());
let k_signing = hmac_sha256(&k_service, b"aws4_request");
let signature = hex::encode(hmac_sha256(&k_signing, string_to_sign.as_bytes()));

This matches AWS's documented derivation.

I reproduced the existing signer_output_is_unchanged_by_the_move fixture offline with its public example credentials and fixed timestamp. Holding both the canonical request and string-to-sign identical, aws4fetch 1.0.20 gives:

current golden: 50198f4d3c821ae4aa0518965cd3ecaeb81e542a155dc57766e1e28a6ae696b8
AWS-compatible: cd5e8832ab041bc9557910ef3dd094d8eb37b14b0edd903c4b45d83bbda888ca

The comparison explicitly asserts equal canonical requests and strings-to-sign; singleEncode: true keeps the PR's existing URI representation so this isolates the HMAC defect. It does not validate the rest of the current canonicalization. The existing golden test pins the previous algorithm, and the decorator test compares against that same signer, so neither establishes AWS compatibility. Please replace the incorrect golden with an independent AWS-compatible reference and retain the checks that the inner fetch receives the same signed body bytes.

For implementation, the existing SigV4Fetch → inner.fetch boundary can stay. An alternative to maintaining a private SigV4 implementation is AWS's standalone aws-sigv4 HTTP signer; AWS documents using it independently of the SDK. A full aws-sdk-bedrockruntime client is not required for this fix. The pinned AI SDK likewise delegates its signing algorithm to AwsV4Signer from aws4fetch, while keeping its own fetch wrapper.

Clarification: Rig vs. the standalone signer

The Rig Bedrock transport inspected here calls the full aws-sdk-bedrockruntime client via client.converse().customize().send(). The AWS SDK then invokes aws-sigv4 internally before its HTTP connector. Rig does not directly integrate the standalone signer.

For aimux, I recommend using that official signer directly inside the existing decorator:

SigV4Fetch::fetch(final FetchRequest)
  ① resolve credentials
  ② Credentials::new(...).into() → Identity
  ③ v4::SigningParams::builder()
     identity / region / service="bedrock" / clock / settings
  ④ SignableRequest::new(method, URL, headers, SignableBody::Bytes(body))
  ⑤ aws_sigv4::http_request::sign(...)
  ⑥ apply the returned SigningInstructions
  ⑦ existing inner.fetch(signed request)

This keeps aimux's existing request conversion, response parsing, call-level retry and fetch injection. It delegates canonicalization and cryptographic signing without introducing a Bedrock service client. See the official HTTP signing API. Check the signing settings against Bedrock's URI encoding, path normalization and header rules rather than preserving the old sign-every-header behavior.

Dependency compatibility also needs checking: the locally inspected aws-sigv4 1.3.8 declares Rust 1.88, while aimux declares 1.85. Select compatible dependency versions or explicitly raise the MSRV.