@plurnk/plurnk-providers 1.3.12 → 1.5.0

package/dist/AiSdkProvider.js

@@ -6,10 +6,13 @@
 // ordinary vendor protocol. The compatible URL path remains only for PLURNK
 // extensions and local endpoint probes the SDK cannot represent.
 import { executeAiSdkModel, executeOpenAICompatible } from "./aiSdkTransport.js";
-import { toProviderError, ProviderError } from "./telemetry.js";
+import { toProviderError, ProviderError } from "./errors.js";
+import { attributeUnitemizedReasoning } from "./usage.js";
 import { validateGbnf } from "@plurnk/gbnf";
+import { assertPromptTokenMeasurement, estimatePromptTokens } from "./promptTokens.js";
 import { emitWarningOnce } from "./warnings.js";
-// #539: drop trailing occurrences of a server-rendered EOG marker. llama-server
+import { validateAuthoritativeCharge } from "./cost.js";
+// 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
@@ -22,6 +25,38 @@ const stripTrailingSpecial = (content, marker) => {
         out = out.slice(0, -marker.length);
     return out;
 };
+const projectLeadingReasoning = (content, structuredReasoning, opening, closing) => {
+    if (structuredReasoning.length > 0 || !content.startsWith(opening)) {
+        return { content, reasoning: structuredReasoning, projected: false, contentStart: 0 };
+    }
+    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,
+    };
+};
+// {§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, structuredReasoning, style) => style === "think-tags"
+    ? projectLeadingReasoning(content, structuredReasoning, "<think>", "</think>")
+    : { content, reasoning: structuredReasoning, projected: false, contentStart: 0 };
+// llama-server's template reasoning parser can project this leading channel out
+// of the OpenAI-compatible response. Grammar evidence needs the sentence before
+// that lossy projection, so constrained template turns request it verbatim and
+// split the observed enclosure here.
+const projectTemplateReasoning = (content) => projectLeadingReasoning(content, "", "<|channel>thought\n", "<channel|>");
 // Shared budget→effort breakpoints (xai and google had identical copies).
 export const effortFromBudget = (budget) => {
     if (budget <= 1000)
@@ -30,41 +65,27 @@ export const effortFromBudget = (budget) => {
         return "medium";
     return "high";
 };
-// chars/2 upper bound (see ./tokenizers.ts) — overcounts safely, never under.
-const heuristicTokens = (text) => (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 = 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) => {
-    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 {
     #model;
     #url;
@@ -86,8 +107,12 @@ export default class AiSdkProvider {
     #dryAllowedLength;
     #repeatLastN;
     #reasoningStyle;
-    #countTokens;
+    #reasoningResponseStyle;
+    #countPromptTokens;
+    #promptTokensUrl;
     #calculateCost;
+    #calculateCharge;
+    #normalizeCharge;
     #source;
     #grammarStyle;
     #promptCacheKey;
@@ -98,6 +123,7 @@ export default class AiSdkProvider {
     #supportsSlotPinning;
     #slotCount;
     #retryAttempts;
+    #errorDetailLimit;
     #topLogprobs;
     #reasoningReserve;
     #completionReserve;
@@ -105,7 +131,8 @@ export default class AiSdkProvider {
     #rawBody;
     #servedModel;
     #requiresMaxTokens;
-    // Optional capability (SPEC §2): exact tokenization served by the backend's
+    attributions;
+    // 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.
@@ -114,6 +141,7 @@ export default class AiSdkProvider {
         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`);
         }
@@ -137,9 +165,17 @@ export default class AiSdkProvider {
         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.#normalizeCharge = config.normalizeCharge;
         this.#source = config.source ?? "provider";
         this.#grammarStyle = config.grammarStyle ?? "none";
         this.#promptCacheKey = config.promptCacheKey ?? false;
@@ -159,6 +195,13 @@ export default class AiSdkProvider {
         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) => {
@@ -179,7 +222,7 @@ export default class AiSdkProvider {
         }
     }
     get contextWindow() { 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) {
         if (spec === undefined)
@@ -191,61 +234,93 @@ export default class AiSdkProvider {
     get reasoningReserve() { return this.#resolveReserve(this.#reasoningReserve); }
     get completionReserve() { return this.#resolveReserve(this.#completionReserve); }
     get model() { 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() { 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() { 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() { return this.#grammarStyle !== "none"; }
-    countTokens(text) { return this.#countTokens(text); }
+    async countPromptTokens(messages, signal) {
+        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();
+            if (!Number.isInteger(body.input_tokens) || body.input_tokens < 0) {
+                return estimatePromptTokens(messages, "llama-server input-token endpoint returned no non-negative integer input_tokens");
+            }
+            return {
+                kind: "exact",
+                tokens: body.input_tokens,
+                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) { return this.#calculateCost(usage); }
-    // 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).
-    #reasoningBody() {
+    calculateCharge(usage) {
+        return this.#calculateCharge?.(usage)
+            ?? { kind: "unknown", reason: "no provider rate or settled charge is available" };
+    }
+    // Reasoning activation and allowance are independent of grammar transport;
+    // only the response representation becomes lossless when evidence is needed.
+    // The llama-server template mapping is owned by {§llama-reasoning-request}.
+    #reasoningBody(preserveGrammarSentence = false) {
         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: preserveGrammarSentence ? "none" : "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"
@@ -254,7 +329,7 @@ export default class AiSdkProvider {
             case "none": return {};
         }
     }
-    // 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 —
@@ -277,19 +352,19 @@ export default class AiSdkProvider {
         this.#runSlots.set(workerId, slot);
         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) {
         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
@@ -300,7 +375,7 @@ export default class AiSdkProvider {
     // live: together/deepinfra/fireworks; it is OpenAI's own param, so real OpenAI takes it too).
     #repetitionPenaltyBody() {
         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 {
@@ -315,12 +390,12 @@ export default class AiSdkProvider {
             case "none": return this.#frequencyPenalty > 0 ? { frequency_penalty: this.#frequencyPenalty } : {};
         }
     }
-    // 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, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn) {
@@ -333,11 +408,11 @@ export default class AiSdkProvider {
             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
@@ -346,7 +421,7 @@ export default class AiSdkProvider {
         // 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.
@@ -358,30 +433,7 @@ export default class AiSdkProvider {
             h["Plurnk-Turn"] = String(turn);
         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, content) {
-        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.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;
@@ -396,7 +448,7 @@ export default class AiSdkProvider {
             throw new Error(`grammar validation (PLURNK_PROVIDERS_GBNF_DEBUG): invalid GBNF — ${cause.message}`, { cause });
         }
     }
-    // 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) {
@@ -407,7 +459,8 @@ export default class AiSdkProvider {
     // 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) {
         if (sampling === undefined)
             return {};
@@ -418,48 +471,49 @@ export default class AiSdkProvider {
         return out;
     }
     async generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling }) {
-        // 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;
+        const preserveGrammarSentence = wantGrammar
+            && this.#reasoningStyle === "template";
         // 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 = {
-            // #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),
             ...(this.#serviceTier !== undefined ? { service_tier: this.#serviceTier } : {}),
             model: this.#model,
             messages,
-            ...this.#reasoningBody(),
+            ...this.#reasoningBody(preserveGrammarSentence),
             ...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 } : {}),
         };
         // Per-request headers = static auth/routing + any first-party telemetry.
         const metaHeaders = this.#metadataHeaders(attributions, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn);
-        const headers = Object.keys(metaHeaders).length > 0 ? { ...this.#headers, ...metaHeaders } : this.#headers;
+        const headers = Object.keys(metaHeaders).length === 0
+            ? this.#headers
+            : { ...this.#headers, ...metaHeaders };
         let raw;
         try {
             raw = this.#languageModel === undefined
@@ -513,13 +567,13 @@ export default class AiSdkProvider {
         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
@@ -527,64 +581,118 @@ export default class AiSdkProvider {
         // 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;
-        let railsMeta;
-        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 grammarInput = raw.content;
+        const projectedReasoning = preserveGrammarSentence && !raw.reasoningProjected
+            ? projectTemplateReasoning(raw.content)
+            : projectTaggedReasoning(raw.content, raw.reasoning, this.#reasoningResponseStyle);
+        // Preserve the exact sentence seen at the grammar boundary. Constrained
+        // template turns request `reasoning_format: "none"`, so even an empty
+        // channel remains observable. An unexpectedly projected response cannot
+        // supply independent pre-projection evidence.
+        let grammarEvidence;
+        if (wantGrammar) {
+            if (preserveGrammarSentence) {
+                if (!raw.reasoningProjected) {
+                    grammarEvidence = {
+                        input: grammarInput,
+                        contentStart: projectedReasoning.projected ? projectedReasoning.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
+            else if (projectedReasoning.projected) {
+                grammarEvidence = {
+                    input: grammarInput,
+                    contentStart: projectedReasoning.contentStart,
+                    transported: sendGrammar !== undefined,
+                };
+            }
+            else {
+                grammarEvidence = {
+                    input: grammarInput,
+                    contentStart: 0,
+                    transported: sendGrammar !== undefined,
+                };
+            }
+        }
+        if (projectedReasoning.projected) {
+            raw.content = projectedReasoning.content;
+            raw.reasoning = projectedReasoning.reasoning;
+            raw.usage = attributeUnitemizedReasoning(raw.usage, raw.reasoning, raw.content);
+        }
+        let notices;
+        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 normalizedCharge = this.#normalizeCharge?.(raw.chargeEvidence);
+        const charge = normalizedCharge === undefined
+            ? undefined
+            : validateAuthoritativeCharge(normalizedCharge);
+        const evidence = {
             assistantRaw: raw,
+            ...(charge === undefined ? {} : { charge }),
+            ...(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 = {
+                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,
         };
     }
 }