@plurnk/plurnk-providers 1.3.11 → 1.4.0

package/src/AiSdkProvider.ts

@@ -6,28 +6,24 @@
 // ordinary vendor protocol. The compatible URL path remains only for PLURNK
 // extensions and local endpoint probes the SDK cannot represent.
 
-import type { ChatMessage, FinishReason, Provider, ProviderResponse, ProviderUsage } from "./types.ts";
-import type { Reasoning, ReserveSpec } from "./env.ts";
+import type { ChatMessage, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderResponse, ProviderUsage } from "./types.ts";
+import type { ProviderCost } from "@plurnk/plurnk-contracts";
+import type { Reasoning, ReasoningResponseStyle, ReserveSpec } from "./env.ts";
 import { executeAiSdkModel, executeOpenAICompatible } from "./aiSdkTransport.ts";
 import type { LanguageModel } from "ai";
-import { toProviderError, ProviderError, type TelemetryEvent } from "./telemetry.ts";
-import { validateGbnf, type Verdict } from "@plurnk/gbnf";
+import { toProviderError, ProviderError } from "./errors.ts";
+import { attributeUnitemizedReasoning } from "./usage.ts";
+import type { ProviderNotice } from "./notices.ts";
+import { validateGbnf } from "@plurnk/gbnf";
+import { assertPromptTokenMeasurement, estimatePromptTokens } from "./promptTokens.ts";
 import { emitWarningOnce } from "./warnings.ts";
+import type { PluginAttribution, PluginAttributionContext } from "@plurnk/plurnk-meta";
 
 export type ProviderFetch = typeof globalThis.fetch;
 
-// How the reasoning intent (PLURNK_PROVIDERS_REASONING: off | adaptive | on, plus
-// REASONING_BUDGET iff on — #32/#33) translates to each backend's wire mechanism
-// (SPEC §4); the per-style mapping lives in #reasoningBody. Non-obvious ones:
-// "template" ALWAYS emits enable_thinking — the explicit false is llama-server's
-// only working off-switch (§13); "anthropic" uses the `thinking` object and IGNORES
-// reasoning_effort; "effort_explicit" (fireworks) sends the EXPLICIT "none" for OFF
-// instead of omitting — reason-by-DEFAULT models (DeepSeek V4 defaults
-// 'high') keep reasoning when the field is omitted, fatal under an active grammar
-// (#30). Intent maps IDENTICALLY with or without a transported grammar — fireworks
-// masks only the content channel, so reasoning and rails coexist in one call
-// (canary-verified; the #32 clamp is lifted — it caused the plan-less service#331).
-export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" | "effort_explicit" | "template" | "anthropic";
+// Backend wire spellings for the resolved reasoning intent. The switch beside each
+// mapping retains any backend-specific omission/explicit-disable constraint.
+export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" | "effort_explicit" | "thinking_effort" | "template" | "anthropic";
 
 // GBNF transport is a local llama-server capability. "none" means no
 // service-managed constrained sampling; endpoint-owned settings are not inferred.
@@ -37,17 +33,20 @@ export type AiSdkProviderConfig = {
     model: string;
     url?: string;                             // OpenAI-compatible chat-completions URL
     languageModel?: LanguageModel;            // native AI SDK provider model
+    attributions?: (context: PluginAttributionContext) => PluginAttribution;
     fetchTimeoutMs: number;
     streamIdleTimeoutMs?: number;             // streamed body inter-chunk deadline; zero/unset disables
     headers?: Record<string, string>;         // fully-resolved request headers (incl. auth); default {}
     fetch?: ProviderFetch;                    // per-instance request executor; default globalThis.fetch
-    contextWindow?: number | null;              // default null; caller resolves-or-fails (#419), narrows to required with the interface
+    contextWindow?: number | null;              // default null; caller resolves-or-fails, narrows to required with the interface
     reasoningStyle?: ReasoningStyle;          // default "none"
-    countTokens?: (text: string) => number;   // default chars/2 upper-bound heuristic
+    reasoningResponseStyle?: ReasoningResponseStyle; // {§provider-tagged-reasoning}; default "verbatim"
+    countPromptTokens?: (messages: readonly ChatMessage[], signal?: AbortSignal) => PromptTokenMeasurement | Promise<PromptTokenMeasurement>;
     calculateCost?: (usage: ProviderUsage) => number; // default () => 0
-    source?: string;                           // telemetry source, e.g. "provider:openai"; default "provider"
+    calculateCharge?: (usage: ProviderUsage) => Exclude<ProviderCost, { kind: "authoritative" }>;
+    source?: string;                           // notice/problem source, e.g. "provider:openai"; default "provider"
     grammarStyle?: GrammarStyle;               // how a GBNF grammar is carried; default "none" (not sent)
-    // #518: send the OpenAI-standard `prompt_cache_key` set to workerId, so a
+    // Send the OpenAI-standard `prompt_cache_key` set to workerId, so a
     // serverless backend with REPLICA-LOCAL prompt caching (fireworks, verified)
     // pins a worker's turns to one replica and claims its stable prefix. Default
     // false -- a backend that strict-validates unknown fields 400s, so enable only
@@ -59,21 +58,24 @@ export type AiSdkProviderConfig = {
     gbnfDebug?: boolean;                        // PLURNK_PROVIDERS_GBNF_DEBUG: validate the grammar locally + throw on invalid, but DON'T transport it (run unconstrained); default false
     streaming?: boolean;                        // SSE transport (default true); false → one non-streamed JSON
     firstPartyMetadata?: boolean;              // forward per-turn attributions + client as Plurnk-* headers (plurnk only); default false
-    apiKeyRejectedMessage?: string;            // #537: friendly hint when a PRESENT key is 401/403-rejected (distinct from unset); default undefined
-    eosText?: string;                          // #539: server-reported eos_token, stripped from the content tail (--special renders it as text); default undefined
-    // Slot affinity wiring (provider-INTERNAL — never consumer-facing, #11).
+    apiKeyRejectedMessage?: string;            // friendly hint when a present key is 401/403-rejected (distinct from unset); default undefined
+    eosText?: string;                          // server-reported eos_token, stripped from the content tail (--special renders it as text); default undefined
+    // Slot affinity wiring is provider-internal, never consumer-facing.
     supportsSlotPinning?: boolean;             // backend accepts an `id_slot` body field (llama-server); default false
     slotCount?: number | null;                 // probed slot count for pinning backends; default null
     // Backend-served exact tokenization (llama-server /tokenize). When set, the
     // provider exposes the optional `tokenize()` capability — the model's OWN
     // vocab, no client-side tokenizer data needed; default unset (capability absent).
     tokenizeUrl?: string;
-    // #37: the backend's self-reported served model id (from the /v1/models probe),
+    // Provider-authoritative count of a complete chat-completions request. This
+    // is distinct from /tokenize, which sees content but not the chat template.
+    promptTokensUrl?: string;
+    // The backend's self-reported served model id (from the /v1/models probe),
     // surfaced as Provider.servedModel. For a local llama-server the wire `model` is
     // the alias; this is the real name (the .gguf) the tokenizer seam maps. Absent
     // when no probe ran or it read no row.
     servedModel?: string;
-    // #43: backend decodes unbounded without a caller cap (llama-server n_predict
+    // Backend decodes unbounded without a caller cap (llama-server n_predict
     // to the wall) — surfaced as Provider.requiresMaxTokens so consumers can
     // boot-refuse an envelope-less local alias. Default unset (no claim).
     requiresMaxTokens?: boolean;
@@ -81,36 +83,39 @@ export type AiSdkProviderConfig = {
     // (PLURNK_PROVIDERS_REASONING + _BUDGET, read via reasoningFromEnv):
     // { mode: off|adaptive|on, budget: iff on }. The provider maps it to the
     // backend's mechanism via reasoningStyle; budget is only ever a magnitude,
-    // never a hidden activation flag (#33).
+    // never a hidden activation flag.
     reasoning: Reasoning;
     // Decode tuning: no in-code defaults; the canonical measured values (0.2 /
     // 1.15) ship as the floor in .env.defaults (alias-scopable). `temperature` is the
-    // DEFAULT for EVERY request, spread UNDER caller sampling (#30/endpoint#7).
+    // DEFAULT for EVERY request, spread UNDER caller sampling.
     // `repeatPenalty` is the FLOOR the provider manages wherever a grammar rides
-    // (greedy-under-mask loops without it, #9) — the VALUE is operator config;
+    // (greedy-under-mask loops without it) — the VALUE is operator config;
     // WHERE it applies stays mechanism.
     temperature: number;
     repeatPenalty: number;
-    // #426: anti-degeneration guard on the CLOUD path (grammarStyle "none"), where the
+    // Anti-degeneration guard on the cloud path (grammarStyle "none"), where the
     // repeat_penalty multiplier isn't available - the OpenAI-standard frequency_penalty.
     // Optional (default 0 = off) so an out-of-date plugin that omits it just runs unguarded
     // rather than failing construction; the standard factory always supplies it.
     frequencyPenalty?: number;
-    // #567: llama.cpp anti-repetition-LOOP controls, sent on the llamacpp path (DRY is a
-    // llama.cpp sampler). DRY penalizes repeated SEQUENCES with a penalty escalating in run
-    // length — the tool for a plan-restart loop a single-token repeat_penalty over a short
-    // window can't see. The GENERIC DRY defaults (0.8/1.75/2) ship as a floor in .env.defaults
-    // like repeatPenalty — applied for a detected llama.cpp backend, customer-overridable;
-    // absent (a plugin omitting them) = the box's own default. repeatLastN widens the window.
+    // Optional llama.cpp anti-repetition controls. DRY can suppress long
+    // repeated sequences, but it can also corrupt exact repetition required by
+    // PLURNK operations. The portable default is off; these fields ride only
+    // after an explicit operator opt-in. repeatLastN widens the repeat window.
     dryMultiplier?: number;
     dryBase?: number;
     dryAllowedLength?: number;
     repeatLastN?: number;
     // Transient-failure retry budget — REQUIRED, no in-code default
     // (PLURNK_PROVIDERS_RETRY_ATTEMPTS, a non-negative int): 0 = surface the
-    // first failure; N = up to N retries on a transient error (§4, #18).
+    // first failure; N = up to N retries on a transient error
+    // ({§provider-failure-normalization}).
     retryAttempts: number;
-    // Data-capture knobs (#36), OFF by default — the flag IS the isolation, so a
+    // Maximum characters retained from an upstream diagnostic in the public
+    // ProviderError Problem. Standard factories supply the env-owned value;
+    // direct construction may omit it to preserve the complete diagnostic.
+    errorDetailLimit?: number;
+    // Data-capture knobs ({§provider-evidence}), off by default — the flag is the isolation, so a
     // serving turn requests nothing and carries nothing. `topLogprobs`: when a
     // non-negative int, request `logprobs:true, top_logprobs:<n>` and surface the
     // per-token confidence on assistant.logprobs (PLURNK_PROVIDERS_TOP_LOGPROBS;
@@ -119,7 +124,7 @@ export type AiSdkProviderConfig = {
     // gated per-alias.
     topLogprobs?: number | null;
     rawBody?: boolean;
-    // #507 (owner-ruled): the generation-envelope reserves, env-read via
+    // {§provider-generation-envelope} The generation-envelope reserves, env-read via
     // envelopeFromEnv — a percentage of the DETECTED window or an absolute token
     // count. Optional so an out-of-date sibling keeps constructing (no claim);
     // the standard factory always supplies them. Resolved against contextWindow
@@ -127,13 +132,13 @@ export type AiSdkProviderConfig = {
     // derives correctly.
     reasoningReserve?: ReserveSpec;
     completionReserve?: ReserveSpec;
-    // #507: the plurnk.ai router owns tuning (SPEC §5) — false suppresses the
+    // The plurnk.ai router owns tuning — false suppresses the
     // client-side temperature/penalty FLOORS on this provider (caller `sampling`
     // still passes through verbatim). Default true (floors ride).
     tuningFloors?: boolean;
 };
 
-// #539: drop trailing occurrences of a server-rendered EOG marker. llama-server
+// Drop trailing occurrences of a server-rendered EOG marker. llama-server
 // under --special renders EOS as literal text, so a raw-EOS-ended turn carries a
 // trailing <eos> the grammar never sanctioned. Trailing-only + exact-match, so it
 // can never eat body content (a body ending in the literal marker isn't producible
@@ -145,6 +150,44 @@ const stripTrailingSpecial = (content: string, marker: string): string => {
     return out;
 };
 
+type TaggedReasoningProjection = {
+    readonly content: string;
+    readonly reasoning: string;
+    readonly projected: boolean;
+    readonly contentStart: number;
+};
+
+// {§provider-tagged-reasoning} Only the model-contract position is structural:
+// one exact leading envelope. Parsing after stream assembly keeps SSE and JSON
+// on one path and leaves later literal tags in the visible suffix untouched.
+const projectTaggedReasoning = (
+    content: string,
+    structuredReasoning: string,
+    style: ReasoningResponseStyle,
+): TaggedReasoningProjection => {
+    const opening = "<think>";
+    if (style !== "think-tags" || structuredReasoning.length > 0 || !content.startsWith(opening)) {
+        return { content, reasoning: structuredReasoning, projected: false, contentStart: 0 };
+    }
+    const closing = "</think>";
+    const closingIndex = content.indexOf(closing, opening.length);
+    if (closingIndex === -1) {
+        return {
+            content: "",
+            reasoning: content.slice(opening.length),
+            projected: true,
+            contentStart: [...content].length,
+        };
+    }
+    const suffixStart = closingIndex + closing.length;
+    return {
+        content: content.slice(suffixStart),
+        reasoning: content.slice(opening.length, closingIndex),
+        projected: true,
+        contentStart: [...content.slice(0, suffixStart)].length,
+    };
+};
+
 // Shared budget→effort breakpoints (xai and google had identical copies).
 export const effortFromBudget = (budget: number): "low" | "medium" | "high" => {
     if (budget <= 1000) return "low";
@@ -152,44 +195,28 @@ export const effortFromBudget = (budget: number): "low" | "medium" | "high" => {
     return "high";
 };
 
-// chars/2 upper bound (see ./tokenizers.ts) — overcounts safely, never under.
-const heuristicTokens = (text: string): number => (text.length === 0 ? 0 : Math.ceil(text.length / 2));
-
 // Body keys the provider owns — a caller's `sampling` passthrough may not set
-// these. Two families (#477 audit):
+// these. Two families:
 //   transport/managed — grammar transport, the stream/JSON choice, slot pinning,
-//     data capture (SPEC §8: backend-specific fields never cross the contract);
+//     data capture ({§provider-evidence}: backend-specific fields never cross the contract);
 //   contract invariants — `n` (atomic single completion: choices[0] is the
 //     response; n>1 = paid, dropped output), the tool-calling family (tools-in-
 //     body doctrine, §2: native tool_calls return null content = a broken turn),
 //     modalities/audio (text-only contract), prediction (decode semantics, not
 //     sampling), and the token caps (the envelope is the managed maxTokens —
-//     sampling must not bypass the consumer's #425 cap).
+//     sampling must not bypass the consumer's cap).
 // Sampling intent (temperature, top_p, penalties, stop, seed, logit_bias) and
 // platform knobs (user, service_tier, prompt_cache_*, safety_identifier,
 // metadata, store, verbosity) pass through; the managed floors spread UNDER
 // sampling stay deliberately caller-overridable.
 const RESERVED_BODY_KEYS: ReadonlySet<string> = new Set([
     "model", "messages", "stream", "stream_options", "grammar", "response_format", "id_slot", "logprobs", "top_logprobs",
+    "reasoning_format", "reasoning_effort", "thinking", "think", "include_reasoning", "chat_template_kwargs", "thinking_budget_tokens", // lexicon-allow: backend wire fields
     "n", "tools", "tool_choice", "functions", "function_call", "parallel_tool_calls",
     "modalities", "audio", "prediction", "max_tokens", "max_completion_tokens",
     "prompt_cache_key",
 ]);
 
-// Render a non-accept verdict into a terse, factual grammar_unenforced message
-// (SPEC §12 message policy: no guidance prose). `reject` names the diverging code
-// point + what the grammar would have accepted; `incomplete` names the valid-prefix
-// length that never reached a terminal state.
-const describeUnenforced = (v: Exclude<Verdict, { status: "accept" }>): string => {
-    if (v.status === "reject") {
-        const expected = v.expected.length > 0
-            ? v.expected.map((e) => `${e.rule} accepts ${e.accepts}`).join(", ")
-            : "end of input";
-        return `grammar not enforced: output rejected by the transported grammar at code point ${v.pos} (${JSON.stringify(v.char)}); expected ${expected}`;
-    }
-    return `grammar not enforced: output is an incomplete match of the transported grammar — a valid prefix of ${v.pos} code points that never terminated`;
-};
-
 export default class AiSdkProvider implements Provider {
     #model: string;
     #url: string | undefined;
@@ -211,8 +238,11 @@ export default class AiSdkProvider implements Provider {
     #dryAllowedLength: number | undefined;
     #repeatLastN: number | undefined;
     #reasoningStyle: ReasoningStyle;
-    #countTokens: (text: string) => number;
+    #reasoningResponseStyle: ReasoningResponseStyle;
+    #countPromptTokens: (messages: readonly ChatMessage[], signal?: AbortSignal) => PromptTokenMeasurement | Promise<PromptTokenMeasurement>;
+    #promptTokensUrl: string | undefined;
     #calculateCost: (usage: ProviderUsage) => number;
+    #calculateCharge?: (usage: ProviderUsage) => Exclude<ProviderCost, { kind: "authoritative" }>;
     #source: string;
     #grammarStyle: GrammarStyle;
     #promptCacheKey: boolean;
@@ -223,6 +253,7 @@ export default class AiSdkProvider implements Provider {
     #supportsSlotPinning: boolean;
     #slotCount: number | null;
     #retryAttempts: number;
+    #errorDetailLimit: number | undefined;
     #topLogprobs: number | null;
     #reasoningReserve: ReserveSpec | undefined;
     #completionReserve: ReserveSpec | undefined;
@@ -230,8 +261,9 @@ export default class AiSdkProvider implements Provider {
     #rawBody: boolean;
     #servedModel: string | undefined;
     #requiresMaxTokens: boolean | undefined;
+    readonly attributions?: (context: PluginAttributionContext) => PluginAttribution;
 
-    // Optional capability (SPEC §2): exact tokenization served by the backend's
+    // Optional capability ({§provider-local-capabilities}): exact tokenization served by the backend's
     // own vocab. Assigned in the constructor ONLY when the config carries a
     // tokenizeUrl (llama-server), so `provider.tokenize === undefined` remains
     // the honest capability signal for every other backend.
@@ -241,6 +273,7 @@ export default class AiSdkProvider implements Provider {
         this.#model = config.model;
         this.#url = config.url;
         this.#languageModel = config.languageModel;
+        this.attributions = config.attributions;
         if ((this.#url === undefined) === (this.#languageModel === undefined)) {
             throw new Error(`${config.source ?? "provider"}: configure exactly one AI SDK model or OpenAI-compatible URL`);
         }
@@ -264,9 +297,16 @@ export default class AiSdkProvider implements Provider {
         this.#dryAllowedLength = config.dryAllowedLength;
         this.#repeatLastN = config.repeatLastN;
         this.#retryAttempts = config.retryAttempts;
+        this.#errorDetailLimit = config.errorDetailLimit;
         this.#reasoningStyle = config.reasoningStyle ?? "none";
-        this.#countTokens = config.countTokens ?? heuristicTokens;
+        this.#reasoningResponseStyle = config.reasoningResponseStyle ?? "verbatim";
+        if (config.countPromptTokens !== undefined && config.promptTokensUrl !== undefined) {
+            throw new Error(`${config.source ?? "provider"}: configure countPromptTokens or promptTokensUrl, not both`);
+        }
+        this.#countPromptTokens = config.countPromptTokens ?? ((messages) => estimatePromptTokens(messages));
+        this.#promptTokensUrl = config.promptTokensUrl;
         this.#calculateCost = config.calculateCost ?? (() => 0);
+        this.#calculateCharge = config.calculateCharge;
         this.#source = config.source ?? "provider";
         this.#grammarStyle = config.grammarStyle ?? "none";
         this.#promptCacheKey = config.promptCacheKey ?? false;
@@ -286,6 +326,13 @@ export default class AiSdkProvider implements Provider {
         this.#rawBody = config.rawBody ?? false;
         this.#servedModel = config.servedModel;
         this.#requiresMaxTokens = config.requiresMaxTokens;
+        const reasoningReserve = this.reasoningReserve;
+        if (this.#reasoningStyle === "template"
+            && this.#reasoning.mode === "on"
+            && reasoningReserve !== null
+            && this.#reasoning.budget! > reasoningReserve) {
+            throw new Error(`${this.#source}: PLURNK_PROVIDERS_REASONING_BUDGET (${this.#reasoning.budget}) exceeds the resolved PLURNK_PROVIDERS_REASONING_RESERVE (${reasoningReserve})`);
+        }
         const { tokenizeUrl } = config;
         if (tokenizeUrl !== undefined) {
             this.tokenize = async (text: string): Promise<number[]> => {
@@ -306,7 +353,7 @@ export default class AiSdkProvider implements Provider {
     }
 
     get contextWindow(): number | null { return this.#contextWindow; }
-    // #507: envelope reserves — absolute pins stand alone; percentages need the
+    // {§provider-generation-envelope} Envelope reserves — absolute pins stand alone; percentages need the
     // detected window; null = underivable (no claim for core's no-cap path).
     #resolveReserve(spec: ReserveSpec | undefined): number | null {
         if (spec === undefined) return null;
@@ -316,63 +363,109 @@ export default class AiSdkProvider implements Provider {
     get reasoningReserve(): number | null { return this.#resolveReserve(this.#reasoningReserve); }
     get completionReserve(): number | null { return this.#resolveReserve(this.#completionReserve); }
     get model(): string { return this.#model; }
-    // #37: backend's self-reported served id; undefined when unprobed/unknown.
+    // Backend's self-reported served id; undefined when unprobed/unknown.
     get servedModel(): string | undefined { return this.#servedModel; }
-    // #43: resolved "decodes unbounded without a cap" fact; undefined = no claim.
+    // Resolved "decodes unbounded without a cap" fact; undefined = no claim.
     get requiresMaxTokens(): boolean | undefined { return this.#requiresMaxTokens; }
-    // Resolved capability (#34): will a transported grammar actually constrain
+    // Resolved capability: will a transported grammar actually constrain
     // this backend's decode? Introspectable so a consumer can verify the rails
     // are LIVE without spending a generation on a forcing-grammar probe.
     get constrainsOutput(): boolean { return this.#grammarStyle !== "none"; }
 
-    countTokens(text: string): number { return this.#countTokens(text); }
+    async countPromptTokens(
+        messages: readonly ChatMessage[],
+        signal?: AbortSignal,
+    ): Promise<PromptTokenMeasurement> {
+        if (this.#promptTokensUrl === undefined) {
+            return assertPromptTokenMeasurement(
+                await this.#countPromptTokens(messages, signal),
+                this.#source,
+            );
+        }
+
+        signal?.throwIfAborted();
+        try {
+            const timeout = AbortSignal.timeout(this.#fetchTimeoutMs);
+            const response = await this.#fetch(this.#promptTokensUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...this.#headers },
+                body: JSON.stringify({
+                    model: this.#model,
+                    messages,
+                    ...this.#reasoningBody(),
+                }),
+                signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+            });
+            if (!response.ok) {
+                return estimatePromptTokens(
+                    messages,
+                    `llama-server input-token endpoint returned HTTP ${response.status}`,
+                );
+            }
+            const body = await response.json() as { input_tokens?: unknown };
+            if (!Number.isInteger(body.input_tokens) || (body.input_tokens as number) < 0) {
+                return estimatePromptTokens(
+                    messages,
+                    "llama-server input-token endpoint returned no non-negative integer input_tokens",
+                );
+            }
+            return {
+                kind: "exact",
+                tokens: body.input_tokens as number,
+                source: "llama-server:/v1/chat/completions/input_tokens",
+            };
+        } catch (cause) {
+            signal?.throwIfAborted();
+            return estimatePromptTokens(
+                messages,
+                `llama-server input-token measurement failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+            );
+        }
+    }
     calculateCost(usage: ProviderUsage): number { return this.#calculateCost(usage); }
+    calculateCharge(usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }> {
+        return this.#calculateCharge?.(usage)
+            ?? { kind: "unknown", reason: "no provider rate or settled charge is available" };
+    }
 
-    // Maps the reasoning INTENT (off | adaptive | on+budget, #33) to the
-    // backend's wire mechanism — including under a transported grammar. The #32
-    // clamp (force reasoning_effort "none" under response_format) is LIFTED:
-    // canary-verified live that fireworks masks ONLY the content channel — the
-    // reasoning channel rides beside it unmasked, and the plurnk grammar's
-    // reasoning?/preplan regions absorb any in-band spillover. The old measured
-    // failures (low→cycles, high→spirals) were pre-max_tokens-cap; with a bounded
-        // cap the matrix ACCEPTs across efforts (reasoning-rails matrix
-    // F9). Clamping was the root of the plan-less regression (service#331).
+    // Reasoning intent maps independently of grammar transport. The llama-server
+    // template mapping is owned by {§llama-reasoning-request}.
     #reasoningBody(): Record<string, unknown> {
         const { mode, budget } = this.#reasoning;
         const on = mode !== "off";
         switch (this.#reasoningStyle) {
-            // Native-channel styles. "template" ALWAYS emits — the explicit
-            // enable_thinking:false is the only working off-switch on llama-server
-            // (§13). Activation only; budget is enforced by the box's
-            // --reasoning-budget launch flag (per-request numerics ignored, F7).
-            //
-            // #488 postmortem: intent maps IDENTICALLY under a transported
-            // grammar. The brief rails-win-the-channel clamp (enable_thinking
-            // forced false under a grammar) is REVERTED — specimens proved the
-            // SANCTIONED think block is the protection, not the hazard: the
-            // server auto-gates the grammar around it and content decodes
-            // constrained (26-run baseline green; zero grammar rejects across
-            // the #488 "railless" specimens). Closing the channel starved a
-            // reasoning-tuned model into ESCAPING mid-content into the raw
-            // thought channel — discarded server-side, decode unconstrained,
-            // 12,288 tokens billed for 1,033 visible chars. The escape is
-            // surfaced instead (vanished-token telemetry + meta rail state).
-            case "template": return { chat_template_kwargs: { enable_thinking: on } };
+            case "template": {
+                const allowance = mode === "off"
+                    ? 0
+                    : mode === "on" ? budget : this.reasoningReserve;
+                return {
+                    chat_template_kwargs: { enable_thinking: on },
+                    reasoning_format: "auto",
+                    ...(allowance === null ? {} : { thinking_budget_tokens: allowance }),
+                };
+            }
             case "think": return on ? { think: true } : {};
             case "include_reasoning": return on ? { include_reasoning: true } : {};
             // effort tiers from the budget; off/adaptive omit the field (the
             // API's default depth is its adaptive).
             case "effort": return mode === "on" ? { reasoning_effort: effortFromBudget(budget!) } : {};
             // Fireworks enum: OFF is sent EXPLICITLY ("none") — omission leaves a
-            // reason-by-default model (DeepSeek V4: default 'high') reasoning (#30).
+            // reason-by-default model (DeepSeek V4: default 'high') reasoning.
             // ADAPTIVE omits the field: the backend's own default posture IS the
             // adaptive semantics, and the literal "adaptive" is MiniMax-M3-only —
-            // fireworks 400s it for every other model (wire-verified, #403; the
+            // Fireworks 400s it for every other model (wire-verified; the
             // 1.0.2 adaptive default refused to boot on it). V4 gotcha: integer
             // efforts 400.
             case "effort_explicit": return mode === "off"
                 ? { reasoning_effort: "none" }
                 : mode === "on" ? { reasoning_effort: effortFromBudget(budget!) } : {};
+            // {§deepseek-reasoning-request}
+            case "thinking_effort": return mode === "off"
+                ? { thinking: { type: "disabled" } }
+                : mode === "on" ? {
+                    thinking: { type: "enabled" },
+                    reasoning_effort: effortFromBudget(budget!),
+                } : {};
             // Anthropic compat: explicit thinking object. off → disabled; on →
             // enabled with budget_tokens; adaptive → omit (the API default).
             case "anthropic": return mode === "off"
@@ -382,7 +475,7 @@ export default class AiSdkProvider implements Provider {
         }
     }
 
-    // Per-run slot affinity (#11): the consumer passes WHICH run this is; the
+    // Per-worker slot affinity: the consumer passes which worker this is; the
     // provider owns WHICH slot serves it. Sticky per workerId, round-robin across
     // new runs (distinct runs → distinct slots while slots last), LRU-bounded
     // bookkeeping so a long-lived daemon never grows the map unboundedly —
@@ -405,19 +498,19 @@ export default class AiSdkProvider implements Provider {
         return { id_slot: slot };
     }
 
-    // Optional local llama-server GBNF transport (SPEC §13). Unsupported
+    // Optional local llama-server GBNF transport ({§gbnf-response-observation}). Unsupported
     // backends receive no grammar-related field.
     #grammarBody(grammar: string | undefined): Record<string, unknown> {
         if (grammar === undefined) return {};
         switch (this.#grammarStyle) {
             // Greedy decoding under hard constraint loops without a repeat-penalty
-            // floor (#9, SPEC §13) — llama.cpp spells it `repeat_penalty`.
+            // floor — llama.cpp spells it `repeat_penalty`.
             case "llamacpp": return { grammar, repeat_penalty: this.#repeatPenalty };
             case "none": return {};
         }
     }
 
-    // Anti-degeneration DEFAULT on EVERY request (#426), keyed to the backend's wire
+    // Anti-degeneration default on every request, keyed to the backend's wire
     // convention - NOT grammar-bound. GBNF is a local constraint, so a cloud
     // alias runs the sampler bare: firefast (deepseek/fireworks) ran 4/86 bench turns
     // straight to the token cap on pure looped repetition (run52). Ships next to
@@ -428,7 +521,7 @@ export default class AiSdkProvider implements Provider {
     // live: together/deepinfra/fireworks; it is OpenAI's own param, so real OpenAI takes it too).
     #repetitionPenaltyBody(): Record<string, unknown> {
         switch (this.#grammarStyle) {
-            // #567: repeat_penalty + optional DRY (repeated-SEQUENCE penalty) + a wider
+            // repeat_penalty + optional DRY (repeated-sequence penalty) + a wider
             // repeat_last_n window — the loop-breaking tools a llama.cpp backend serves.
             // Each rides only when its operator knob is set; absent = the box's default.
             case "llamacpp": return {
@@ -444,12 +537,12 @@ export default class AiSdkProvider implements Provider {
         }
     }
 
-    // First-party telemetry headers (SPEC §5): forwarded ONLY when the spec
+    // First-party telemetry headers ({§provider-request-authority}): forwarded only when the spec
     // opted in (the plurnk endpoint). The gate is here, not at the call site, so
     // attributions/client/strikes can never reach a third-party backend even if
     // the consumer passes them to the wrong provider. Empty values emit no header
     // — EXCEPT strikes, where 0 is a real value (clean streak) distinct from
-    // absent (consumer didn't report); contract per plurnk-service#313. Strikes
+    // absent (consumer didn't report); contract {§strikes-first-party-metadata}. Strikes
     // ride HTTP headers only — the packet never carries them (the model must
     // never see strike state; engine accounting is not a metric to game).
     #metadataHeaders(attributions: string[] | undefined, client: string | undefined, strikes: number | undefined, workerId: string, primaryWorkerId: string | undefined, workspaceId: string | undefined, loop: number | undefined, turn: number | undefined): Record<string, string> {
@@ -458,11 +551,11 @@ export default class AiSdkProvider implements Provider {
         if (attributions !== undefined && attributions.length > 0) h["Plurnk-Attribution"] = JSON.stringify(attributions);
         if (client !== undefined && client.length > 0) h["Plurnk-Client"] = client;
         if (strikes !== undefined && Number.isInteger(strikes) && strikes >= 0) h["Plurnk-Strikes"] = String(strikes);
-        // Worker identity (#26, wire-name completed #486/#511): the opaque workerId
+        // Worker identity: the opaque workerId
         // the consumer already supplies, forwarded so the endpoint can key
         // per-worker affinity/telemetry — same gate as every first-party signal.
         h["Plurnk-Worker-Id"] = workerId;
-        // Root worker of the lineage (#522): the no-parent ancestor of this turn's
+        // Root worker of the lineage ({§worker-primary}): the no-parent ancestor of this turn's
         // worker tree. The consumer classifies primary-vs-spawned by equality
         // (primaryWorkerId == workerId ⇒ the primary/root worker). The provider
         // EMITS what the consumer supplies and never invents a primary; the
@@ -470,7 +563,7 @@ export default class AiSdkProvider implements Provider {
         // own, where it equals workerId). Absence is the consumer's violation for
         // the endpoint to surface, not a provider default.
         if (primaryWorkerId !== undefined && primaryWorkerId.length > 0) h["Plurnk-Worker-Primary"] = primaryWorkerId;
-        // Turn coordinate (#404, extends #26 per #391): workspace/loop/turn, the
+        // Turn coordinate ({§lifecycle-terms}): workspace/loop/turn, the
         // daemon-side sequence the endpoint can never scrape from the wire.
         // Coordinates are 1-based — 0 is not a real value, so no strikes-style
         // zero exception; absent/empty/0 emits no header.
@@ -480,33 +573,7 @@ export default class AiSdkProvider implements Provider {
         return h;
     }
 
-    // Enforcement verification (SPEC §13). When a grammar was actually transported
-    // (grammarStyle !== "none"), the backend MUST have constrained the output;
-    // some silently drop the grammar field or mislabel the channel, and without
-    // this check we would return unconstrained output as if enforced. STRICT: any
-    // non-accept verdict (reject, or an incomplete/never-terminated match) is a
-    // grammar_unenforced failure. A grammar our own validator can't parse — even
-    // though the backend accepted it (a port-vs-llama.cpp gap) — is a non-fatal
-    // verify gap: warn, don't fail a transport that may have worked. This is a
-    // conformance check against the grammar we already hold, NOT a plurnk-DSL
-    // parse (§8) — it stays grammar-generic and backend-agnostic.
-    // Validate output against the grammar. Returns the verdict, or null on the
-    // verify GAP — a grammar our own validator can't parse (a port-vs-llama.cpp
-    // gap): warn, don't manufacture a conflict from a check that didn't run.
-    #grammarVerdict(grammar: string, content: string): Verdict | null {
-        try {
-            return validateGbnf(grammar, content);
-        } catch (cause) {
-            // Once per (code, message) — #40: this fires PER TURN otherwise.
-            emitWarningOnce(
-                `${this.#source}: could not verify grammar enforcement — the transported grammar did not parse in @plurnk/gbnf (${(cause as Error).message})`,
-                "PLURNK_GRAMMAR_UNVERIFIABLE",
-            );
-            return null;
-        }
-    }
-
-    // PLURNK_PROVIDERS_GBNF_DEBUG (SPEC §13): validate the supplied GBNF locally and fail
+    // PLURNK_PROVIDERS_GBNF_DEBUG ({§gbnf-response-observation}): validate the supplied GBNF locally and fail
     // hard if it's malformed, BEFORE any wire call — and the grammar is NOT
     // transported, so the request runs unconstrained. A debug aid to catch invalid
     // grammars (e.g. while editing the plurnk grammar) without a model round-trip;
@@ -521,7 +588,7 @@ export default class AiSdkProvider implements Provider {
         }
     }
 
-    // Per-turn metadata bag (#23): pass the backend's non-standard top-level fields
+    // Per-turn metadata bag: pass the backend's non-standard top-level fields
     // through verbatim. Providers do not reinterpret vendor currency or account
     // metadata; a monetary value carries its own amount and currency.
     #buildMeta(chunkMetadata: Record<string, unknown>): Record<string, unknown> | undefined {
@@ -533,7 +600,8 @@ export default class AiSdkProvider implements Provider {
     // penalties, stop, seed, …) merged UNDER the managed body: model, messages,
     // reasoning, grammar (+ its repeat-penalty floor), max_tokens and slot always
     // win, and reserved transport/protocol keys are stripped so the passthrough
-    // can't smuggle a grammar, a stream toggle, or a backend slot (SPEC §8).
+    // can't smuggle a grammar, a stream toggle, or a backend slot
+    // ({§provider-request-authority}).
     #samplingBody(sampling: Record<string, unknown> | undefined): Record<string, unknown> {
         if (sampling === undefined) return {};
         const out: Record<string, unknown> = {};
@@ -542,27 +610,24 @@ export default class AiSdkProvider implements Provider {
     }
 
     async generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling }: { messages: ChatMessage[]; workerId: string; primaryWorkerId?: string; signal?: AbortSignal; grammar?: string; maxTokens?: number; attributions?: string[]; client?: string; strikes?: number; workspaceId?: string; loop?: number; turn?: number; sampling?: Record<string, unknown> }): Promise<ProviderResponse> {
-        // Boundary validation (SPEC §2): the worker identity is required.
+        // {§provider-interface} The worker identity is required.
         if (workerId === undefined || workerId.length === 0) throw new Error("generate: workerId is required — the worker's stable, opaque identity");
-        // Reject before any wire call when already aborted (SPEC §10.8).
+        // Reject before any wire call when already aborted
+        // ({§provider-failure-normalization}).
         signal?.throwIfAborted();
 
-        // Grammar handling (SPEC §13). PLURNK_PROVIDERS_GBNF_DEBUG validates the supplied
-        // grammar locally and throws on a malformed one, then WITHHOLDS it so the
-        // model generates UNCONSTRAINED — and the free output is still verified
-        // against the grammar (below), surfacing exactly where the model's natural
-        // output and the grammar conflict. Otherwise the grammar is sent when the
-        // backend supports it (grammarStyle !== "none").
+        // Grammar handling ({§gbnf-response-observation}). Debug validates the
+        // supplied grammar before the call but withholds it from the backend.
         const wantGrammar = grammar !== undefined && this.#grammarStyle !== "none";
         if (wantGrammar && this.#gbnfDebug) this.#assertGrammarValid(grammar!);
         const sendGrammar = wantGrammar && !this.#gbnfDebug ? grammar : undefined;
 
         // Assembly order = precedence: the family's sampling DEFAULTS
-        // (PLURNK_PROVIDERS_TEMPERATURE — universal, #30 measured it on grammar
+        // (PLURNK_PROVIDERS_TEMPERATURE — universal, measured on grammar
         // paths and the name promises every request) < the caller's `sampling`
         // < the managed fields, which always win.
         const body: Record<string, unknown> = {
-            // #507: floors suppressed on router-owned-tuning providers (plurnk) —
+            // Floors are suppressed on router-owned-tuning providers (plurnk) —
             // the router's per-model tuning must not be overridden by client floors.
             ...(this.#tuningFloors ? { temperature: this.#temperature, ...this.#repetitionPenaltyBody() } : {}),
             ...this.#samplingBody(sampling),
@@ -572,11 +637,11 @@ export default class AiSdkProvider implements Provider {
             ...this.#reasoningBody(),
             ...this.#grammarBody(sendGrammar),
             ...(maxTokens !== undefined ? { max_tokens: maxTokens } : {}),
-            // #36: request per-token logprobs only when enabled (managed field —
+            // Request per-token logprobs only when enabled (managed field —
             // reserved from caller sampling; the env flag is the single control).
             ...(this.#topLogprobs !== null ? { logprobs: true, top_logprobs: this.#topLogprobs } : {}),
             ...this.#slotBody(workerId),
-            // #518: prompt-cache affinity -- workerId as the OpenAI-standard
+            // Prompt-cache affinity -- workerId as the OpenAI-standard
             // prompt_cache_key routes a worker's turns to one serverless replica so
             // its stable prefix caches (managed; reserved from caller sampling).
             ...(this.#promptCacheKey ? { prompt_cache_key: workerId } : {}),
@@ -636,14 +701,14 @@ export default class AiSdkProvider implements Provider {
                 });
         } catch (err) {
             if (signal?.aborted) throw err;
-            const pe = toProviderError(err, this.#source);
+            const pe = toProviderError(err, this.#source, this.#errorDetailLimit);
             if ((pe.status === 401 || pe.status === 403) && this.#hasApiKey && this.#apiKeyRejectedMessage !== undefined) {
                 throw new ProviderError(this.#source, "unauthorized", this.#apiKeyRejectedMessage, { status: pe.status, cause: err });
             }
             throw pe;
         }
 
-        // #539: llama-server --special renders EOG tokens as text, so a turn ending
+        // llama-server --special renders EOG tokens as text, so a turn ending
         // via raw EOS carries a trailing <eos> the grammar never sanctioned - it both
         // false-rejects the rail verdict and leaks a control token into the packet.
         // Strip the server-reported eos_token from the tail ONCE, before the verdict
@@ -651,66 +716,125 @@ export default class AiSdkProvider implements Provider {
         // wire text for forensics.
         if (this.#eosText !== undefined) raw.content = stripTrailingSpecial(raw.content, this.#eosText);
 
-        // Grammar conformance (§13): bytes always flow; the verdict is an
-        // observation. Same check whether the grammar was transported
-        // (sendGrammar) or withheld (PLURNK_PROVIDERS_GBNF_DEBUG filter mode) — a
-        // non-accept verdict attaches a grammar_unenforced telemetry event
-        // (message + divergence position) and the response returns normally.
-        // Discard/retry/escalate/self-correct is the consumer's policy.
-        let telemetry: TelemetryEvent[] | undefined;
-        let railsMeta: Record<string, unknown> | undefined;
-        const usage = raw.usage;
-        const observedGrammar = sendGrammar ?? (wantGrammar && this.#gbnfDebug ? grammar : undefined);
-        if (observedGrammar !== undefined) {
-            const verdict = this.#grammarVerdict(observedGrammar, raw.content);
-            if (verdict !== null && verdict.status !== "accept") {
-                telemetry = [{ source: this.#source, kind: "grammar_unenforced", message: describeUnenforced(verdict), position: verdict.pos }];
+        const taggedReasoning = projectTaggedReasoning(
+            raw.content,
+            raw.reasoning,
+            this.#reasoningResponseStyle,
+        );
+
+        // Preserve the exact sentence seen at the grammar boundary. llama-server's
+        // `reasoning_format: "auto"` projects one raw Harmony enclosure into the
+        // reasoning/content fields; the wire field's presence is the proof that the
+        // projection occurred. The provider represents this evidence and never grades it.
+        let grammarEvidence: GrammarEvidence | undefined;
+        if (wantGrammar) {
+            if (taggedReasoning.projected) {
+                grammarEvidence = {
+                    input: raw.content,
+                    contentStart: taggedReasoning.contentStart,
+                    transported: sendGrammar !== undefined,
+                };
+            } else if (this.#reasoningStyle === "template" && this.#reasoning.mode !== "off") {
+                if (raw.reasoningProjected) {
+                    const prefix = `<|channel>thought\n${raw.reasoning}<channel|>`;
+                    grammarEvidence = {
+                        input: `${prefix}${raw.content}`,
+                        contentStart: [...prefix].length,
+                        transported: sendGrammar !== undefined,
+                    };
+                }
+            } else {
+                grammarEvidence = {
+                    input: raw.content,
+                    contentStart: 0,
+                    transported: sendGrammar !== undefined,
+                };
             }
-            // #488 per-request loud state: rail attachment + conformance verdict
-            // ride `meta` into the consumer's turn row, so a drill reads rail
-            // presence PER TURN from the run db instead of inferring it from
-            // output shape (the #488 misdiagnosis, twice).
-            railsMeta = { railsAttached: sendGrammar !== undefined, railsVerdict: verdict?.status ?? "unverifiable" };
-            // #488 channel-escape detector (the run105 class): completion tokens
+        }
+
+        if (taggedReasoning.projected) {
+            raw.content = taggedReasoning.content;
+            raw.reasoning = taggedReasoning.reasoning;
+            raw.usage = attributeUnitemizedReasoning(raw.usage, raw.reasoning, raw.content);
+        }
+
+        let notices: ProviderNotice[] | undefined;
+        const usage = raw.usage;
+        if (sendGrammar !== undefined && this.tokenize !== undefined) {
+            // Channel-escape detector: completion tokens
             // billed far beyond every visible channel mean the decode ESCAPED into
-            // a server-discarded reasoning block mid-emission — unconstrained,
-            // invisible, billed (12,288 billed vs 1,033 chars visible, live).
-            // countTokens OVERCOUNTS text (chars/2 upper bound), so billed
-            // exceeding visible-plus-slack is real vanishing, not estimator noise.
-            const visible = this.#countTokens(raw.content) + this.#countTokens(raw.reasoning);
-            if (sendGrammar !== undefined && usage.completion > visible + 64) {
-                (telemetry ??= []).push({
-                    source: this.#source,
-                    kind: "grammar_unenforced",
-                    message: `decode escaped the grammar: ${usage.completion} completion tokens billed but only ~${visible} visible across content+reasoning — the balance ran unconstrained in a discarded reasoning channel`,
-                    position: [...raw.content].length,
-                });
+            // a server-discarded reasoning block mid-emission. This diagnostic
+            // requires the serving vocabulary; an estimate cannot prove absence.
+            try {
+                const [contentTokens, reasoningTokens] = await Promise.all([
+                    this.tokenize(raw.content),
+                    this.tokenize(raw.reasoning),
+                ]);
+                const visible = contentTokens.length + reasoningTokens.length;
+                if (usage.completion > visible + 64) {
+                    (notices ??= []).push({
+                        source: this.#source,
+                        kind: "grammar_unenforced",
+                        level: "warn",
+                        message: `decode escaped the grammar: ${usage.completion} completion tokens billed but only ${visible} visible across content+reasoning — the balance ran unconstrained in a discarded reasoning channel`,
+                        position: [...raw.content].length,
+                    });
+                }
+            } catch (cause) {
+                emitWarningOnce(
+                    `${this.#source}: exact visible-token diagnostic unavailable (${cause instanceof Error ? cause.message : String(cause)})`,
+                    "PLURNK_VISIBLE_TOKEN_COUNT_UNAVAILABLE",
+                );
             }
         }
 
-        const builtMeta = this.#buildMeta(raw.metadata);
-        const meta = railsMeta !== undefined ? { ...builtMeta, ...railsMeta } : builtMeta;
+        const meta = this.#buildMeta(raw.metadata);
         const logprobs = raw.logprobs.length > 0 ? raw.logprobs : undefined;
         const meanLogprob = logprobs !== undefined
             ? logprobs.reduce((sum, token) => sum + token.logprob, 0) / logprobs.length
             : undefined;
 
-        return {
-            assistant: {
-                content: raw.content,
-                reasoning: raw.reasoning.length > 0 ? raw.reasoning : null,
-                ...(raw.reasoningEncrypted.length > 0
-                    ? { reasoningEncrypted: raw.reasoningEncrypted }
-                    : {}),
-                usage,
-                finishReason: raw.finishReason,
-                model: raw.model,
-                ...(logprobs !== undefined ? { logprobs, meanLogprob } : {}),
-            },
+        const assistant = {
+            content: raw.content,
+            reasoning: raw.reasoning.length > 0 ? raw.reasoning : null,
+            ...(raw.reasoningEncrypted.length > 0
+                ? { reasoningEncrypted: raw.reasoningEncrypted }
+                : {}),
+            usage,
+            model: raw.model,
+            ...(logprobs !== undefined ? { logprobs, meanLogprob } : {}),
+        };
+        const evidence = {
             assistantRaw: raw,
+            ...(grammarEvidence !== undefined ? { grammarEvidence } : {}),
             ...(raw.rawBody !== undefined ? { rawBody: raw.rawBody } : {}),
             ...(meta !== undefined ? { meta } : {}),
-            ...(telemetry !== undefined ? { telemetry } : {}),
+            ...(notices !== undefined ? { notices } : {}),
+        };
+        if (raw.finishReason === "resource_interrupted") {
+            const attempt: ProviderResponse<"resource_interrupted"> = {
+                assistant: { ...assistant, finishReason: raw.finishReason },
+                ...evidence,
+            };
+            throw new ProviderError(
+                this.#source,
+                "resource_interrupted",
+                "The provider interrupted generation because inference resources were unavailable.",
+                {
+                    attempt,
+                    extensions: {
+                        stage: "provider-response",
+                        finishReason: "resource_interrupted",
+                        ...(raw.rawFinishReason === undefined
+                            ? {}
+                            : { rawFinishReason: raw.rawFinishReason }),
+                    },
+                },
+            );
+        }
+        return {
+            assistant: { ...assistant, finishReason: raw.finishReason },
+            ...evidence,
         };
     }
 }