refactor(core)!: align public core types with the AI SDK V4 shapes

.github/workflows/ci.yml

@@ -390,47 +390,31 @@ jobs:
         working-directory: bindings/flutter/example
         run: flutter test
 
-  # ── Contract tests: shared JSON fixtures (catches cross-language type drift) ──
+  # Generated files must match their generators.
   contract-tests:
-    name: Contract tests
+    name: Generator drift checks
     runs-on: ubuntu-latest
     steps:
       - 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
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - name: Run Rust contract tests
-        run: cargo test --test contract_test -p aimux-core
       - name: ts-rs export drift (checked-in types must match generator output)
         run: python3 scripts/gen_ts_types.py --check
-      - name: Build Node binding
-        working-directory: bindings/node
-        run: |
-          npm ci
-          npx napi build --platform
-      - name: Run Node contract tests
-        working-directory: contract-tests
-        run: |
-          node --experimental-strip-types run-node.ts
 
-  # ── Swift contract tests: the eighth binding joins the shared fixtures ─────
-  # Needs macOS (XCTest) and the FFI cdylib, which the Swift package links via
-  # the CAimuxFFI system module. The Dart side needs no job here: flutter-binding
-  # already runs `flutter test`, which picks up bindings/flutter/test/contract_test.dart.
+  # Swift tests need macOS (XCTest) and the FFI cdylib, which the Swift package
+  # links via the CAimuxFFI system module.
   swift-contract-tests:
-    name: Swift contract tests
+    name: Swift tests
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - name: Build the FFI library the Swift package links against
         run: cargo build -p aimux-ffi --release
-      - name: Run Swift contract tests
+      - name: Run Swift tests
         working-directory: bindings/swift
         env:
           DYLD_LIBRARY_PATH: ${{ github.workspace }}/target/release

CHANGELOG.md

@@ -9,6 +9,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Breaking
 
+- Provider results carry request and response information as the AI SDK does
+  (`aimux-core`). `GenerateResult` has `request: Option<RequestInfo>` and
+  `response: Option<ResponseInfo>`; `ResponseInfo` gains `id` and holds the
+  timestamp, model id, headers and body. `StreamResult` has `request` and
+  `response: Option<StreamResponseInfo>`. The flat `request_body` and
+  `response_headers` fields are removed and `response` is optional; the call
+  layer fills a missing id, timestamp and model id. The user-facing results and
+  their JSON are unchanged.
+
+- The prompt a provider receives is modelled by role (`aimux-core`), as the AI
+  SDK's `LanguageModelV4Message`. `LanguageModelPrompt` is
+  `Vec<LanguageModelMessage>`: `System { content: String }`,
+  `User { content: Vec<UserPart> }`, `Assistant { content: Vec<AssistantPart> }`,
+  `Tool { content: Vec<ToolPart> }`. The parts are `TextPart`, `FilePart`,
+  `ReasoningPart`, `ToolCallPart`, `ToolResultPart`. A provider sees one file
+  part, `FilePart { data: FileData, media_type, filename }`; the five
+  user-facing file variants are folded into it by
+  `convert_to_language_model_prompt`, which now returns `Result` and rejects a
+  part its role does not allow. `LanguageModelPromptMessage` is removed. The
+  user-facing `ModelMessage` and `ContentPart` are unchanged. Recordings store
+  the new prompt JSON: a system message's `content` is a string and every file
+  input is a `file` part.
+
+- Provider options and provider metadata have one typed shape, the AI SDK's
+  `Record<string, JSONObject>`: `SharedProviderOptions` and
+  `SharedProviderMetadata` (`ProviderMetadata` is an alias) are
+  `HashMap<String, JsonObject>`, namespace to JSON object. They replace
+  `serde_json::Value`, `HashMap<String, Value>` and the per-part
+  `Option<Value>`. Every `provider_options` / `provider_metadata` field of
+  content parts, messages, call options, tools, results and stream parts uses
+  them. `{"namespace": {"key": value}}` serializes as before; a value that is
+  not namespace -> object (a number, string or array under a namespace, or a
+  non-object at the top) is rejected when deserialized. Build one with
+  `provider_namespace(ns, json!({..}))`.
+
+- Tool-call and tool-result types are unified, one per protocol layer
+  (`aimux-core`). A provider emits `tool::RawToolCall` (`input` is the raw
+  argument text) in `GenerateContent::ToolCall(..)` and
+  `StreamPart::ToolCall(..)`, and `tool::ToolResult` in the `ToolResult`
+  variants; these variants are newtype variants now. `StreamPart` is generic
+  over the tool-call type: a provider's `do_stream` yields `StreamPart`
+  (= `StreamPart<RawToolCall>`), `stream_text` and everything after it yield
+  `TextStreamPart` (= `StreamPart<ToolCall>`, parsed input with `invalid` /
+  `error`). `RawToolCall` moved from `parse_tool_call` to `tool`. Wire format:
+  enum variants keep their JSON shape; a provider-layer `StreamPart::ToolCall`
+  has a string `input` and no `invalid` / `error`; a
+  `GenerateContent::ToolCall` with a non-string `input` no longer
+  deserializes; the standalone `tool::ToolResult` gains a required
+  `tool_name` and optional `dynamic` / `provider_metadata`.
+- Source, generated-file and reasoning types are unified, one per concept
+  (`aimux-core`). `result::Source`, `result::GeneratedFile` and
+  `result::ReasoningOutput` are the payloads of `GenerateContent::{Source,
+  File, Reasoning}` and `StreamPart::{Source, File}` (newtype variants now) and
+  the elements of `sources`, `files` and `reasoning` on `GenerateTextResult`
+  and `StreamTextResultAggregated`; `StreamPart::ResponseMetadata` wraps
+  `types::ResponseMetadata`. `SourcePart`, `FilePart` and `ReasoningPart` are
+  removed (TypeScript: `Source`, `GeneratedFile`, `ReasoningOutput`). Wire
+  format: enum variants keep their JSON shape; the top-level `sources` /
+  `files` / `reasoning` arrays gain `provider_metadata` (so the reasoning
+  signature is no longer dropped), and a source's `url` / `title` serialize as
+  `null` when absent instead of being omitted.
+
 - Removed the generated `ProviderName` type in every binding (Rust enum, TS
   const object, Go/Java/Kotlin consts, Swift enum, Dart consts, Python
   `Literal`) and `scripts/gen_provider_names.py`. Provider names are plain

CONTRIBUTING.md

@@ -13,7 +13,6 @@ aimux/
 ├── aimux-provider-utils/  # HTTP utilities: retry, backoff, 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
-├── contract-tests/        # Shared JSON fixtures exercised across languages
 ├── rfc/                   # Design docs (RFCs)
 ├── docs/                  # Public product docs (see docs/README.md)
 └── scripts/               # Code-generation and maintenance scripts
@@ -50,9 +49,6 @@ cargo test --workspace
 
 # A single crate
 cargo test -p aimux-providers --tests
-
-# Contract tests (cross-language shared fixtures)
-cargo test --test contract_test -p aimux-core
 ```
 
 If you add or change a provider's request/response shapes, record a new
@@ -108,8 +104,7 @@ Keep the subject line imperative and ≤ 72 characters.
 2. Make your change with focused commits.
 3. Ensure `cargo fmt`, `cargo clippy -D warnings`, and `cargo test --workspace`
    all pass locally. CI runs the same.
-4. If you add a provider or binding, include cassette tests or contract
-   fixtures as appropriate.
+4. If you add a provider or binding, include cassette tests.
 5. Update the relevant doc (README, `docs/`, or `rfc/`) if your change affects
    the public surface.
 6. Open a PR against `master` and fill in the template.

MIGRATION-NS.md

@@ -0,0 +1,195 @@
+# Namespace types migration recipe (provider options / provider metadata)
+
+Do not commit this file.
+
+## What changed
+
+Both are now `HashMap<String, JsonObject>` (namespace -> JSON object), the AI SDK `Record<string, JSONObject>`:
+
+```rust
+// aimux_core::shared  (also re-exported from aimux_core::prelude)
+pub type JsonObject = serde_json::Map<String, serde_json::Value>;
+pub type SharedProviderOptions = HashMap<String, JsonObject>;
+pub type SharedProviderMetadata = HashMap<String, JsonObject>;
+pub fn provider_namespace(namespace: &str, object: serde_json::Value) -> SharedProviderMetadata;
+// aimux_core::types
+pub type ProviderMetadata = SharedProviderMetadata;   // was serde_json::Value
+```
+
+Every `provider_options` field (content parts, messages, CallOptions, GenerateTextOptions, FunctionTool, every
+`*CallOptions`) is `Option<SharedProviderOptions>` (the media/embedding call options that were already non-Option stay
+non-Option). Every `provider_metadata` field (GenerateContent, StreamPart, ToolCall/ToolResult/RawToolCall, Source,
+ReasoningOutput, GenerateResult, ...) is `Option<ProviderMetadata>`. Not changed: `recording::ProviderRecord.provider_options`
+(provider construction options such as org/project, flat, not namespaced).
+
+Imports:
+
+```rust
+use aimux_core::shared::{provider_namespace, JsonObject, SharedProviderMetadata, SharedProviderOptions};
+use aimux_core::types::ProviderMetadata;
+```
+
+Wire JSON is unchanged: `{"openai": {"k": v}}`. A non-object namespace value (`{"openai": 1}`, `[]`, `"x"`, `null`) or a
+non-object top level is now a deserialization error.
+
+## Patterns
+
+### 1. Build metadata / options, one namespace (the common case)
+
+```rust
+// before
+provider_metadata: Some(json!({ "xai": { "itemId": item_id } })),
+// after
+provider_metadata: Some(provider_namespace("xai", json!({ "itemId": item_id }))),
+```
+
+Same for `provider_options: Some(...)` (identical type). The helper is `#[must_use]`; a non-object second argument yields
+an empty namespace, so pass an object literal, or build a `JsonObject` yourself (pattern 3).
+
+Functions that returned `Value` metadata now return `ProviderMetadata`:
+
+```rust
+// before
+fn server_tool_metadata(...) -> Value { ...; json!({ "google": payload }) }
+// after
+fn server_tool_metadata(...) -> ProviderMetadata { ...; provider_namespace("google", payload) }
+```
+
+### 2. Build metadata with several namespaces
+
+```rust
+// before
+Some(json!({
+    "googleVertex": { "thoughtSignature": "a" },
+    "vertex": { "thoughtSignature": "b" },
+}))
+// after (tests / fixtures): deserialize the literal, shape is checked by the type
+Some(serde_json::from_value(json!({
+    "googleVertex": { "thoughtSignature": "a" },
+    "vertex": { "thoughtSignature": "b" },
+})).unwrap())
+// after (non-test code): extend
+let mut m = provider_namespace("bedrock", json!({ "signature": sig }));
+m.extend(provider_namespace("amazonBedrock", json!({ "signature": sig })));
+Some(m)
+```
+
+### 3. Build from a `Map` you filled imperatively
+
+The `Value::Object(..)` wrapper goes away.
+
+```rust
+// before
+let mut metadata = HashMap::new();
+let mut prodia_meta = Map::new();
+prodia_meta.insert("images".into(), json!([job_result]));
+metadata.insert("prodia".into(), Value::Object(prodia_meta));
+// after
+metadata.insert("prodia".into(), prodia_meta);        // prodia_meta: JsonObject (= Map<String, Value>)
+
+// before
+std::iter::once(("google".to_string(), Value::Object(metadata))).collect()
+// after
+HashMap::from([("google".to_string(), metadata)])     // or provider_namespace("google", Value::Object(metadata))
+```
+
+`Map::new()` is the same type as `JsonObject::new()`; `use aimux_core::shared::JsonObject` if you want the alias.
+
+### 4. Merge into existing metadata
+
+```rust
+// before (Value)
+meta["xai"]["reasoningEncryptedContent"] = json!(ec);
+if let Some(o) = meta.as_object_mut() { o.insert(...) }
+// after
+meta.entry("xai".into()).or_default().insert("reasoningEncryptedContent".into(), json!(ec));
+// merge a whole map one level deep
+for (ns, obj) in other { meta.entry(ns).or_default().extend(obj); }
+```
+
+Building the inner object first and wrapping once is also fine:
+
+```rust
+let mut inner = json!({ "itemId": part_id });             // before: json! then index-assign
+inner["reasoningEncryptedContent"] = json!(ec);           // still works on a Value
+provider_namespace("xai", inner)                          // wrap at the end
+```
+
+### 5. Read an option from a namespace
+
+`options.provider_options.get("x")` now returns `Option<&JsonObject>`, not `Option<&Value>`. Method chains that call
+`.get("k")`, `.and_then(|o| o.get("k"))`, `.as_str()` on the *inner values* are unchanged.
+
+```rust
+// before and after (compiles unchanged)
+let v = opts.provider_options.get("openai").and_then(|o| o.get("user")).and_then(|v| v.as_str());
+// per-part options (Option<Value> before, Option<SharedProviderOptions> now)
+let cc = provider_options.as_ref().and_then(|o| o.get("anthropic")).and_then(|a| a.get("cacheControl"));
+```
+
+What breaks:
+
+```rust
+// before: object-ness check on the namespace value
+let o = provider_opts.as_object()?;           // E0599: no method as_object on &Map
+// after: it already is the object
+let o = provider_opts;
+// before: .and_then(|v| v.as_object())   after: delete the and_then (the value is already &JsonObject)
+// before: opts["k"] (Value index, Null on miss)   after: Map index PANICS on a missing key; use opts.get("k")
+// before: Value::is_object / is_null on the namespace   after: gone (always an object)
+// need a Value again (e.g. to feed serde_json::from_value or json!): Value::Object(obj.clone())
+```
+
+Looping a string-literal slice: `for key in &["bedrock", "amazonBedrock"] { po.get(key) }` fails with
+`String: Borrow<&str>` (E0277); iterate by value (`for key in ["bedrock", "amazonBedrock"]`) or write `po.get(*key)`.
+
+### 6. Pass through
+
+Fields and function parameters that merely carry a value need no change except the declared type:
+
+```rust
+// before
+fn f(meta: Option<Value>) -> StreamPart { StreamPart::TextEnd { id, provider_metadata: meta } }
+// after
+fn f(meta: Option<ProviderMetadata>) -> StreamPart { ... }
+```
+
+Local variables typed `Option<Value>` / `HashMap<String, Value>` that end up in these fields: retype them.
+This includes `StreamingToolCallDelta::provider_metadata`, which is an `Option<ProviderMetadata>`: build it
+with `provider_namespace("google", json!({...}))`.
+
+### 7. Tests comparing against `json!`
+
+```rust
+// before
+assert_eq!(part.provider_metadata, Some(json!({ "anthropic": { "signature": "s" } })));
+// after, option 1: compare typed
+assert_eq!(part.provider_metadata, Some(provider_namespace("anthropic", json!({ "signature": "s" }))));
+// after, option 2: compare the serialized shape (keeps the json! literal as-is)
+assert_eq!(serde_json::to_value(&part.provider_metadata).unwrap(), json!({ "anthropic": { "signature": "s" } }));
+// indexing keeps working: HashMap<String, Map> -> m["anthropic"]["signature"] == json!("s")
+// but a whole namespace is a Map, not a Value: Value::Object(m["anthropic"].clone()) == json!({ ... })
+```
+
+### 8. `Option<Value>` per-part / per-message options
+
+`ContentPart::*.provider_options`, `LanguageModelPromptMessage.provider_options` were `Option<Value>`; now
+`Option<SharedProviderOptions>`. Constructing sites become `Some(provider_namespace(..))` (pattern 1); `None` unchanged.
+A flat (non-namespaced) object such as `json!({ "organization": "o" })` is no longer representable there; if a test
+or code passed one, it was relying on the loose shape: wrap it in a namespace or drop it.
+
+### 9. `Value` results holding provider metadata
+
+`GenerateTextResult.provider_metadata`, `GenerateObjectResult.provider_metadata`, `ReasoningOutput.provider_metadata` and
+the stream `Finish` part are `Option<ProviderMetadata>`. `ResponseMessageBuilder` is `pub(crate)` (core only).
+
+## Contract-test fixtures / tests that fail because they pin a non-object namespace value
+
+Scanned every `*.json` / `*.jsonl` under contract-tests, aimux-core, aimux-provider-utils, aimux-providers/tests
+(fixtures and cassettes), bindings and tools for `provider_options|provider_metadata|providerOptions|providerMetadata`
+keys whose value is not `null` or an object of objects: none found. In particular
+`contract-tests/fixtures/wire-format.json` (15 occurrences) already uses the namespace -> object shape, and
+`aimux-core/tests/contract_test.rs` passes. Tests inside `aimux-providers/tests/*.rs` that build these values with
+`json!` do not compile yet and are handled per vendor directory with the recipe above; any that pin a non-object
+namespace value (for example `json!({ "openai": 1 })` or a flat `{ "organization": ... }`) must be reported with
+file:line rather than kept loose.

aimux-core/Cargo.toml

@@ -17,12 +17,10 @@ futures = { workspace = true }
 async-stream = { workspace = true }
 tracing = { workspace = true }
 ts-rs = { workspace = true }
-# Deliberately narrower than the workspace-wide `full`: core's production
-# code uses only timers (`time`) and `select!` (`macros`). Keeping the
-# declaration at the real API surface documents what Core actually asks
-# of the runtime (RFC-0016 had removed core's tokio dependency; RFC-0031
-# reintroduces it for operation deadlines and retry backoff).
-tokio = { version = "1", features = ["time", "macros", "rt", "sync"] }
+# Core also resolves generated file URLs before exposing file outputs.
+tokio = { version = "1", features = ["time", "macros", "rt", "sync", "net"] }
+reqwest = { workspace = true }
+url = { workspace = true }
 tokio-util = "0.7"
 httpdate = { workspace = true }
 rand = { workspace = true }