docs(spec): CK#1 @ai-sdk completeness audit — provider-extras bag + 3 field gaps

Two independent audits (MC + SUBC) against @ai-sdk v2 provider-spec canonical
(LanguageModelV2Prompt, ~/Work/OSS/ai packages/provider) converged on the same
root finding. Closes the lossless-superset gaps before the canonical blessing.

G-A (architectural): @ai-sdk routes ALL provider-specific per-part data through ONE
opaque providerOptions/providerMetadata bag (Record<provider,Record<key,JSONValue>>)
on every message AND part — reasoning signature, redacted-data, cacheControl, even
a compaction marker all ride it; the canonical types NONE of them. Typed-field
enumeration kept discovering holes (Gemini thoughtSignature was the latest). Adds a
NATIVE-PRESERVED provider_extras bag at message + part level (§5.10, ordered BTreeMap
so key order can't bust cache; transform never parses it) — makes CK PROVABLY
lossless vs any unenumerated provider extra. New typed-vs-bag rule: a datum is a
typed neutral field IFF the transform branches on it (today: Reasoning.signature,
RedactedReasoning, provider_executed); else it rides the bag. Refactors ContentBlock
to {kind, provider_extras}; demotes the speculative Text/ToolCall signature fields
into the bag.

G-B: ToolResultOutput typed variants (Text|Json|ErrorText|ErrorJson|Content) — JSON
tool results no longer flatten to text; error-ness in the variant (drops is_error).
G-C: provider_executed on ToolCall/ToolResult + Assistant-role result placement
(server-side tools: web_search/built-ins/grounding). G-D: Media.filename.
Plus ToolResult.tool_name preserved (no fragile cross-message re-derive).

Verified NON-gaps (both audits): source/citation parts (response-side, CK is
request-only), system-as-string (CK multi-System richer), cache_control (render-side
+ provider_extras safety net). Conformance §10 gains lossless-round-trip property
test (3c) + typed-output/filename checks (3d).

Co-authored-by: Alfonso [Magic Context] <288211368+alfonso-magic-context@users.noreply.github.com>

Author: ualtinok

docs/specs/ck-message.md

@@ -92,42 +92,75 @@ pub struct CkMessage {
     pub role: Role,
     /// ORDER is byte-affecting (bucket a). MUST be preserved verbatim.
     pub content: Vec<ContentBlock>,
+    /// MESSAGE-level provider extras (§5.10). NATIVE-PRESERVED, in the projection,
+    /// deterministic key order. Carries provider-specific message data the
+    /// transform never interprets (e.g. message-level cache hints, provider tags).
+    pub provider_extras: ProviderExtras,
     /// Bucket `flag`. project() strips this entirely. The keystone invariant
     /// (§2) forbids any field here from changing rendered bytes.
     pub meta: HarnessMeta,
 }
 
 pub enum Role { System, User, Assistant, Tool }
 
-pub enum ContentBlock {
+/// A content part = its typed kind + a part-level provider-extras bag (§5.10).
+pub struct ContentBlock {
+    pub kind: ContentKind,
+    /// PART-level provider extras. NATIVE-PRESERVED, in the projection,
+    /// deterministic key order. The general-form catch-all for any provider
+    /// per-part datum the transform does NOT branch on (Gemini text/tool
+    /// thought-signatures, provider part tags, cache hints the renderer can't
+    /// re-derive, future provider extras). See §5.10 + the typed-vs-bag rule.
+    pub provider_extras: ProviderExtras,
+}
+
+pub enum ContentKind {
     /// `§N§` tag prefixes live as LITERAL TEXT inside `text`, never as a field.
     Text { text: String },
-    /// `signature` is provider-issued; MUST round-trip byte-verbatim when present.
+    /// `signature` is TYPED because the transform branches on it (nulls it when
+    /// clearing reasoning, §6.1). The codec maps it to/from the provider's native
+    /// location, keeping the transform provider-neutral. Byte-verbatim when present.
     Reasoning { text: String, signature: Option<String> },
-    /// Opaque provider blob; MUST round-trip byte-verbatim and MUST NOT be emptied.
+    /// Separate variant (not a flag on Reasoning) because the transform branches on
+    /// it (skip-clear, §5.5). `data` is opaque; byte-verbatim; MUST NOT be emptied.
     RedactedReasoning { data: String },
     /// `id` is the CK-CANONICAL tool-call id; pairing is ALWAYS on it (§5.6.1).
-    ToolCall { id: String, name: String, input: serde_json::Value },
-    /// `id` MUST equal the paired ToolCall.id (the CK-canonical id, §5.6.1).
-    ToolResult { id: String, content: ToolResultContent, is_error: bool },
+    /// `provider_executed` is TYPED because tool-pairing branches on it (§7).
+    ToolCall { id: String, name: String, input: serde_json::Value, provider_executed: bool },
+    /// `id` MUST equal the paired ToolCall.id (§5.6.1). `tool_name` preserved
+    /// (avoids cross-message name-recovery fragility, §5.6). `output` carries the
+    /// typed shape incl. structured JSON + typed errors (§5.6.2).
+    ToolResult { id: String, tool_name: String, output: ToolResultOutput, provider_executed: bool },
     /// Multimodal input (§9). Bucket (a) CONTENT in CK day one.
     Media(MediaBlock),
 }
 
-pub enum ToolResultContent {
+/// Mirrors @ai-sdk LanguageModelV2ToolResultOutput so structured/typed-error
+/// results round-trip losslessly (§5.6.2). Error-ness is encoded in the variant.
+pub enum ToolResultOutput {
     Text(String),
-    Blocks(Vec<ResultBlock>),
+    Json(serde_json::Value),
+    ErrorText(String),
+    ErrorJson(serde_json::Value),
+    Content(Vec<ResultBlock>),   // text + media
 }
 pub enum ResultBlock { Text(String), Media(MediaBlock) }
 
 pub struct MediaBlock {
-    pub kind: MediaKind,         // Image | File | Document
-    pub mime: String,
-    pub source: MediaSource,     // Base64 | Url | FileId
+    pub kind: MediaKind,             // Image | File | Document
+    pub mime: String,                // IANA media type (mediaType)
+    pub filename: Option<String>,    // preserved where the provider carries it (§9)
+    pub source: MediaSource,         // Base64 | Url | FileId
 }
 pub enum MediaKind { Image, File, Document }
 pub enum MediaSource { Base64(String), Url(String), FileId(String) }
 
+/// Provider-keyed, deterministic-order extras bag (§5.10). Mirrors @ai-sdk
+/// SharedV2ProviderOptions: Record<provider, Record<key, JSONValue>>. BTreeMap
+/// (NOT HashMap) because key order is byte-affecting on render -> a nondeterministic
+/// order would bust the cache. Empty map renders to nothing.
+pub type ProviderExtras = BTreeMap<String, BTreeMap<String, serde_json::Value>>;
+
 /// Harness-only. project() strips ALL of these; none may affect rendered bytes.
 pub struct HarnessMeta {
     pub harness_id: Option<String>,  // provider wire never sees this
@@ -138,7 +171,9 @@ pub struct HarnessMeta {
 
 The downstream-emitter typed policies (bucket b) and render params are NOT fields
 of `CkMessage` - they are defined in §6 and §8. The MC Transform reads CK content
-+ `meta`; it MUST NOT carry a provider field on the message.
++ `provider_extras` (opaque, never interpreted) + `meta`; it MUST NOT carry a
+provider-INTERPRETED field on the message (the typed `signature` /
+`provider_executed` fields are provider-NEUTRAL - the codec owns the mapping).
 
 ## 4. The three-bucket field model
 
@@ -161,16 +196,20 @@ Every byte-relevant CK field is EXACTLY ONE of:
 | `role` | a | content, all paths |
 | `content` part ORDER | a | byte-affecting; Anthropic rejects thinking-after-text |
 | `Text.text` (incl. `§N§` tag prefix) | a | a changed tag number IS a content change (bust) |
-| `Reasoning.text` + `signature` | a | signature byte-verbatim when present |
+| `Reasoning.text` | a | content; `signature` is TYPED-neutral (§5.10 rule) |
+| `Reasoning.signature` | a (typed-neutral) | transform branches on it (clear nulls it, §6.1); byte-verbatim |
 | `RedactedReasoning.data` | a | byte-verbatim; MUST NOT be emptied |
 | `ToolCall.id` / `name` / `input` | a | content, all paths |
-| `ToolResult.id` / `content` / `is_error` | a | content, all paths |
-| `Media` (image/file/document) | a | CK content day one (§9) |
+| `ToolCall.provider_executed` | a (typed-neutral) | pairing branches on it (§7) |
+| `ToolResult.id` / `tool_name` / `output` | a | content; `output` typed shape (§5.6.2) |
+| `ToolResult.provider_executed` | a (typed-neutral) | pairing / placement branches on it (§7) |
+| `Media` (kind/mime/filename/source) | a | CK content day one (§9) |
+| message + part `provider_extras` | a (NATIVE-PRESERVED) | the catch-all bag; byte-verbatim; deterministic order (§5.10) |
 | reasoning keep/clear shape | b | `decide_reasoning` (§6.1) |
 | drop / empty-content shape | b | `decide_drop_shape` / EmptyContent (§6.2) |
 | reasoning_content-required | b | `ReasoningContentRequired`, default-off (§6.3) |
 | tool-call/result pairing | c | `synthesize_hard_stop` (§7) |
-| `cache_control` placement | param | `CachePolicy`; renderer places it (§8) |
+| `cache_control` placement | param | `CachePolicy`; renderer places it (§8); unrecoverable hints survive in `provider_extras` |
 | `step_context` | param | rides run-config; never CK content (§8) |
 | `synthetic` | flag | harness titling/TUI; no byte effect |
 | `harness_id` / `ordinal` | flag | MC anchoring; not on the wire |
@@ -191,18 +230,29 @@ Transform and all codecs MUST preserve it verbatim.
 text part, NOT a structural field. A change to a tag number is a content change
 and therefore a cache bust. `project()` MUST NOT strip tags (they are content).
 
-**5.4 `Reasoning`** - `text` plus optional provider `signature`. When a signature
-is present it MUST round-trip byte-verbatim through encode/decode; a signature
-over modified text is invalid. Clearing reasoning is a bucket-(b) decision (§6.1),
-not a content edit.
-
-**5.5 `RedactedReasoning`** - opaque provider blob. MUST round-trip byte-verbatim
-and MUST NOT be emptied or signature-stripped (Pi's serializers bypass the
-empty-drop for redacted blocks; emptying one yields a malformed wire block).
-
-**5.6 `ToolCall` / `ToolResult`** - name, input JSON, output content, error flag
-are content. `ToolResultContent` is text or a block list (text + media); encoders
-MUST preserve which form the harness used. The id is governed by §5.6.1.
+**5.4 `Reasoning`** - `text` plus optional provider `signature` (typed-neutral per
+§5.10: the transform branches on it, so it is a named field, but the codec owns
+the native mapping). When a signature is present it MUST round-trip byte-verbatim;
+a signature over modified text is invalid. Clearing reasoning is a bucket-(b)
+decision (§6.1) that nulls the signature, not a content edit. NOTE: @ai-sdk's
+canonical does not type the signature - it rides `providerMetadata.anthropic.signature`.
+CK types it (the transform reads it on clear) while the codec maps it to/from the
+provider's native bag location; everything the transform does NOT read stays in
+`provider_extras` (§5.10).
+
+**5.5 `RedactedReasoning`** - opaque provider blob, a distinct variant (not a flag
+on `Reasoning`) because the transform branches on it (skip-clear). MUST round-trip
+byte-verbatim and MUST NOT be emptied or signature-stripped (Pi's serializers
+bypass the empty-drop for redacted blocks; emptying one yields a malformed wire
+block). @ai-sdk represents this as a `reasoning` part with empty `text` +
+`providerMetadata.anthropic.redactedData`; the codec maps that shape to/from this
+CK variant.
+
+**5.6 `ToolCall` / `ToolResult`** - name, input JSON, and output are content.
+`ToolResult` carries its own `tool_name` (preserved, not re-derived) to avoid
+cross-message name-recovery fragility when the result is in a separate Tool-role
+message from the call. The id is governed by §5.6.1; the output shape by §5.6.2;
+`provider_executed` by §5.6.3.
 
 **5.6.1 `tool_call_id` is CANONICAL with per-edge mapping (NORMATIVE).** The CK
 `ToolCall.id` / `ToolResult.id` is a **CK-canonical** id. Each codec maps
@@ -235,12 +285,63 @@ round-trip fidelity is required only where a decoded id is later RE-RENDERED to
 wire (plugin round-trip, owned path) - and rule 1 (identity-preserving) makes
 that automatic for same-family round-trips.
 
+**5.6.2 `ToolResultOutput` (typed shape, NORMATIVE).** Mirrors @ai-sdk
+`LanguageModelV2ToolResultOutput` so structured results round-trip losslessly:
+`Text(String) | Json(Value) | ErrorText(String) | ErrorJson(Value) |
+Content(Vec<ResultBlock>)`. A structured-JSON tool result MUST be carried as `Json`
+(NOT flattened to text - flattening changes wire bytes and loses structure).
+Error-ness is encoded in the variant (`ErrorText` / `ErrorJson`), replacing a bare
+`is_error: bool` so a structured error's JSON survives. Encoders MUST preserve
+which variant the source used.
+
+**5.6.3 `provider_executed` (NORMATIVE).** `ToolCall.provider_executed` /
+`ToolResult.provider_executed` mark a provider-side / server-executed tool
+(Anthropic web_search, OpenAI built-ins, Gemini grounding). It is typed-neutral
+(§5.10): tool-pairing (§7) branches on it. A provider-executed `ToolResult` MAY
+appear inside an **Assistant-role** message (where @ai-sdk and the providers place
+server-executed results), not only a Tool-role message; the pairing invariant (§7)
+holds on the canonical id regardless of which role carries the result. Encoders
+MUST preserve both the flag and the role placement; a default of `false` =
+client-executed.
+
 **5.7 `Media`** - §9.
 
 **5.8 `HarnessMeta`** - `harness_id`/`ordinal` drive MC anchoring, tagging, and
 `computeRawRangeFingerprint`; `synthetic` drives the harness titling gate and TUI
 visibility. `project()` MUST drop all three; §2 forbids any byte effect.
 
+**5.10 `provider_extras` - the provider-extras bag (NORMATIVE, the lossless
+catch-all).** CK carries a provider-keyed extras bag at BOTH message level
+(`CkMessage.provider_extras`) and part level (`ContentBlock.provider_extras`),
+mirroring @ai-sdk's `SharedV2ProviderOptions`
+(`Record<provider, Record<key, JSONValue>>`). This is what makes CK **provably
+lossless** against any provider per-part datum we did not enumerate, rather than
+"lossless against the providers we listed."
+
+- **Bucket: NATIVE-PRESERVED** (in the projection; origin-provider bytes;
+  byte-verbatim; valid only for the origin provider - a provider switch is a HARD
+  bust so cross-provider reuse never arises mid-epoch, the same rule as signatures).
+- **Deterministic key order is MANDATORY.** Both levels use an ordered map
+  (`BTreeMap`, NOT a hash map): provider-extras render into wire bytes, so a
+  nondeterministic key order would bust the cache. Encoders MUST emit a stable
+  order; decoders MUST preserve it.
+- **The transform MUST NOT interpret it.** `provider_extras` is opaque to the MC
+  Transform and the cache core (a frozen unit's bytes include it but are never
+  parsed). Only codecs read/write it (mapping native<->bag at their edge).
+
+**Typed-vs-bag rule (NORMATIVE, resolves "field or bag?").** A provider-specific
+datum is given a TYPED neutral CK field IF AND ONLY IF the MC Transform branches on
+it; everything else rides `provider_extras`. By this rule exactly four data are
+typed today - `Reasoning.signature` (nulled on clear, §6.1), `RedactedReasoning`
+as a variant (skip-clear, §5.5), `ToolCall/ToolResult.provider_executed` (pairing,
+§7) - and they are PROVIDER-NEUTRAL fields whose native mapping the codec owns, so
+the transform stays provider-neutral while still reasoning about them. Everything
+else provider-specific (Gemini text/tool thought-signatures, message/part cache
+hints the renderer can't re-derive, provider message tags, any future extra) rides
+the bag untyped. A datum is promoted from bag to typed field ONLY when a transform
+rule needs to branch on it; until then the bag keeps it lossless with zero
+transform coupling.
+
 **5.9 Edge-normalization ownership (which codec owns native<->canonical).** Every
 field that has a native representation differing across edges MUST declare ONE
 ownership mode, so no two edges assume the other's format. Three modes:
@@ -256,13 +357,15 @@ ownership mode, so no two edges assume the other's format. Three modes:
 | field | mode | rule / who owns it |
 |---|---|---|
 | `tool_call_id` (call/result) | CANONICAL + per-edge mapping | §5.6.1; pairing on canonical; identity where native id exists; Gemini name-binding resolved per-render |
-| tool `name` | CONTENT, canonical string | byte-content; load-bearing for Gemini name-binding pairing (§5.6.1 rule 2) |
-| `Reasoning.signature` | NATIVE-PRESERVED verbatim | origin-provider-issued; round-trips byte-verbatim; never canonicalized; valid only for its origin family |
-| `RedactedReasoning.data` | NATIVE-PRESERVED verbatim | opaque origin blob; byte-verbatim; never emptied/canonicalized |
+| tool `name` / `ToolResult.tool_name` | CONTENT, canonical string | byte-content; result carries its own name (no cross-message re-derive); load-bearing for Gemini name-binding (§5.6.1 rule 2) |
+| `Reasoning.signature` | TYPED-NEUTRAL + per-edge mapping | typed because transform branches (clear, §6.1); codec maps native bag location (e.g. `providerMetadata.anthropic.signature`) <-> the field |
+| `RedactedReasoning.data` | NATIVE-PRESERVED verbatim | opaque origin blob; byte-verbatim; never emptied/canonicalized; codec maps the @ai-sdk empty-reasoning+redactedData shape |
+| `provider_executed` (call/result) | TYPED-NEUTRAL + per-edge mapping | typed because pairing branches (§7); codec maps `providerExecuted` <-> the field |
+| `provider_extras` (msg + part) | NATIVE-PRESERVED verbatim, ordered | the catch-all bag (§5.10); deterministic key order; codec owns native<->bag; transform never reads |
 | `role` | CANONICAL + per-edge mapping | 4-value enum; each codec maps native role names; assembly (system-pull, tool-role reshape) is RENDER-SIDE, not encode-side |
 | system block / identity lead | CONTENT, opaque + pinned | §5.11; no distinct identity field; pinned (never summarized); identity PLACEMENT is render-side SystemPromptPolicy |
-| `Media.source` (base64/url/file-id) | CANONICAL + per-edge mapping | each codec maps its native media representation to `MediaSource`; owned-render deferred (§9) |
-| `cache_control` placement | RENDER-SIDE | not a CK field; renderer places per `CachePolicy` (§8) |
+| `Media.source` (base64/url/file-id) + `filename` | CANONICAL + per-edge mapping | each codec maps its native media representation to `MediaSource`; `filename` preserved; owned-render deferred (§9) |
+| `cache_control` placement | RENDER-SIDE | not a typed CK field; renderer places per `CachePolicy` (§8); a hint the renderer can't re-derive survives in `provider_extras` |
 | `step_context` | RENDER-SIDE param | rides run-config; never CK content (§8) |
 
 Scope note: CK Message represents conversation messages sent TO a provider (the
@@ -429,6 +532,17 @@ per-provider wire policy, and applies on every path.
    (§5.6.1): pair on the canonical id; use identity where a native id exists (no
    durable mapping state); resolve name-binding families per-render. Every field
    in the §5.9 ownership table normalized by the declared edge/mode.
+3c. Carry `provider_extras` (§5.10) at message + part level as an ORDERED map
+   (`BTreeMap`); round-trip byte-verbatim; the transform/cache-core never parse it;
+   apply the typed-vs-bag rule (a datum is typed ONLY if the transform branches on
+   it - today: `Reasoning.signature`, `RedactedReasoning`, `provider_executed`).
+   Pass the LOSSLESS-ROUND-TRIP property test: `encode(decode(wire)) == wire` over a
+   same-family corpus that includes provider-extras-bearing parts (Gemini
+   thought-signatures, anthropic cacheControl, redacted reasoning).
+3d. Carry `ToolResultOutput` typed variants (§5.6.2) incl. `Json` and typed errors
+   (never flatten JSON to text); preserve `ToolResult.tool_name`; preserve
+   `provider_executed` + Assistant-role result placement (§5.6.3); preserve
+   `Media.filename` (§9).
 4. Implement `decide_reasoning` (§6.1) with the FROZEN-BIT RULE: positional bits
    captured at freeze, never re-derived on defer. Covered by a defer-replay test
    (tail growth MUST NOT flip a frozen turn's reasoning bytes).