@plurnk/plurnk-providers 1.3.12 → 1.5.0

package/src/AiSdkProvider.test.ts

@@ -1,7 +1,9 @@
 import test, { mock } from "node:test";
 import { strict as assert } from "node:assert";
 import AiSdkProvider, { effortFromBudget } from "./AiSdkProvider.ts";
-import { ProviderError } from "./telemetry.ts";
+import { ProviderError } from "./errors.ts";
+import { authoritativeChargeNormalizer } from "./accounting.ts";
+import type { LanguageModel } from "ai";
 
 // Build a fake fetch returning a one-chunk SSE stream, capturing the request
 // so tests can assert what the spine sent on the wire.
@@ -71,7 +73,7 @@ const injectedBase = {
     reasoning: { mode: "off" as const, budget: null },
 };
 
-test("#608: per-instance fetch owns streaming and buffered requests", async () => {
+test("per-instance fetch owns streaming and buffered requests", async () => {
     const calls: Array<{ input: string | URL | Request; init?: RequestInit }> = [];
     const streamingFetch: typeof globalThis.fetch = async (input, init) => {
         calls.push({ input, init });
@@ -105,7 +107,7 @@ test("#608: per-instance fetch owns streaming and buffered requests", async () =
     assert.equal(JSON.parse(String(calls[1].init?.body)).stream, undefined);
 });
 
-test("#608: caller cancellation and provider timeout reach an injected fetch", async () => {
+test("caller cancellation and provider timeout reach an injected fetch", async () => {
     const pendingFetch: typeof globalThis.fetch = async (_input, init) => {
         init?.signal?.throwIfAborted();
         return new Promise((_resolve, reject) => {
@@ -126,7 +128,7 @@ test("#608: caller cancellation and provider timeout reach an injected fetch", a
     );
 });
 
-test("#608: per-instance fetch owns tokenization and retry attempts", async () => {
+test("per-instance fetch owns tokenization and retry attempts", async () => {
     const calls: string[] = [];
     let generationAttempts = 0;
     const providerFetch: typeof globalThis.fetch = async (input) => {
@@ -192,7 +194,7 @@ const installFetchScript = (responses: ScriptedResponse[]) => {
 const flush = () => new Promise<void>((r) => setImmediate(r));
 
 import { resetEmittedWarnings } from "./warnings.ts";
-test.afterEach(() => { mock.restoreAll(); resetEmittedWarnings(); }); // #40: warning-asserting tests stay order-independent
+test.afterEach(() => { mock.restoreAll(); resetEmittedWarnings(); });
 
 test("effortFromBudget: maps budget to tiers", () => {
     assert.equal(effortFromBudget(1), "low");
@@ -202,7 +204,7 @@ test("effortFromBudget: maps budget to tiers", () => {
     assert.equal(effortFromBudget(4001), "high");
 });
 
-test("#543: a 524 Cloudflare edge timeout fails fast - not retried despite retryAttempts", async () => {
+test("a 524 Cloudflare edge timeout fails fast - not retried despite retryAttempts", async () => {
     const calls = installFetchScript([{ status: 524, retryAfter: 120 }]);
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 1000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 3 });
     await assert.rejects(p.generate({ workerId: "r", messages: [] }));
@@ -211,7 +213,7 @@ test("#543: a 524 Cloudflare edge timeout fails fast - not retried despite retry
     mock.restoreAll();
 });
 
-test("#548: a 422 grammar_invalid is a failed exchange, not transport replay policy", async () => {
+test("a 422 grammar_invalid is a failed exchange, not transport replay policy", async () => {
     const body = JSON.stringify({ error: { message: "non-conforming emission rejected: ...", type: "grammar_invalid" } });
     const calls = installFetchScript([{ status: 422, body }]);
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 1000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 2 });
@@ -237,43 +239,59 @@ test("an SSE error frame is a failed exchange, not an empty completion", async (
     assert.equal(calls.length, 1);
 });
 
-test("#539: a trailing eos_token (--special EOG leak) is stripped from content", async () => {
+test("a trailing eos_token (--special EOG leak) is stripped from content", async () => {
     installFetchJson({ model: "m", choices: [{ message: { content: "the answer<eos>" }, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 3, total_tokens: 4 } });
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false, eosText: "<eos>" });
     const res = await p.generate({ workerId: "r", messages: [] });
     assert.equal(res.assistant.content, "the answer"); // trailing <eos> gone; packet + verdict see clean bytes
 });
 
-test("#539: without a probed eos_token the content passes through untouched", async () => {
+test("without a probed eos_token the content passes through untouched", async () => {
     installFetchJson({ model: "m", choices: [{ message: { content: "keeps <eos> literally" }, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 3, total_tokens: 4 } });
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false });
     const res = await p.generate({ workerId: "r", messages: [] });
     assert.equal(res.assistant.content, "keeps <eos> literally"); // no eosText (a cloud backend) -> no strip
 });
 
-test("#539: only the TRAILING eos_token is stripped; a quoted one mid-body survives", async () => {
+test("only the trailing eos_token is stripped; a quoted one mid-body survives", async () => {
     installFetchJson({ model: "m", choices: [{ message: { content: "quotes <eos> in the body<eos>" }, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 5, total_tokens: 6 } });
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false, eosText: "<eos>" });
     const res = await p.generate({ workerId: "r", messages: [] });
     assert.equal(res.assistant.content, "quotes <eos> in the body"); // only the tail goes
 });
 
-test("identity getters and defaults", () => {
+test("identity getters and default prompt estimate", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 1000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     assert.equal(p.model, "m");
     assert.equal(p.contextWindow, null); // default
-    assert.equal(p.countTokens(""), 0);
-    assert.equal(p.countTokens("four"), 2); // default heuristic ceil(4/2) upper bound
-    assert.equal(p.calculateCost({ prompt: 9, completion: 9, reasoning: 0, cached: 0, total: 18 }), 0); // default free
+    assert.deepEqual(
+        await p.countPromptTokens([{ role: "user", content: "漢漢漢" }]),
+        {
+            kind: "estimate",
+            tokens: 2,
+            source: "heuristic:chars2",
+            detail: "chars/2 over message content; provider request framing is unknown",
+        },
+        "chars/2 is explicitly an estimate; high-token-density Unicode prevents an upper-bound claim",
+    );
+    assert.equal(p.calculateCost({ prompt: 9, completion: 9, reasoning: 0, cached: 0, total: 18 }), 0); // current unknown-rate sentinel
 });
 
-test("injected countTokens and calculateCost are used", () => {
+test("injected prompt measurement preserves provenance and calculateCost is used", async () => {
+    const seen: string[] = [];
     const p = new AiSdkProvider({
         model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 1000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0,
-        countTokens: (t) => t.length,
+        countPromptTokens: (messages) => {
+            seen.push(...messages.map(({ content }) => content));
+            return { kind: "upper_bound", tokens: 7, source: "test:proven-bound" };
+        },
         calculateCost: (u) => u.total * 2,
     });
-    assert.equal(p.countTokens("abc"), 3);
+    assert.deepEqual(
+        await p.countPromptTokens([{ role: "system", content: "system" }, { role: "user", content: "user" }]),
+        { kind: "upper_bound", tokens: 7, source: "test:proven-bound" },
+    );
+    assert.deepEqual(seen, ["system", "user"]);
     assert.equal(p.calculateCost({ prompt: 1, completion: 1, reasoning: 0, cached: 0, total: 5 }), 10);
 });
 
@@ -293,6 +311,139 @@ test("generate maps a streamed response into ProviderResponse", async () => {
     assert.notEqual(assistantRaw, undefined);
 });
 
+test("native SDK accounting metadata becomes a normalized charge in buffered and streamed responses", async (t) => {
+    const usage = {
+        inputTokens: { total: 2, noCache: 2, cacheRead: 0, cacheWrite: 0 },
+        outputTokens: { total: 1, text: 1, reasoning: 0 },
+    };
+    const providerMetadata = { openrouter: { usage: { cost: 0.00154935 } } };
+    const charge = {
+        kind: "authoritative",
+        amount: { amount: "0.00154935", currency: "USD" },
+        usdEquivalent: "0.00154935",
+        source: "OpenRouter response usage.cost",
+    };
+    const languageModel = {
+        specificationVersion: "v4",
+        provider: "openrouter.chat",
+        modelId: "router-test",
+        supportedUrls: {},
+        doGenerate: async () => ({
+            content: [{ type: "text", text: "ok" }],
+            finishReason: { unified: "stop", raw: "completed" },
+            usage,
+            providerMetadata,
+            response: { id: "response-buffered", modelId: "router-test" },
+            warnings: [],
+        }),
+        doStream: async () => ({
+            stream: new ReadableStream({
+                start(controller) {
+                    controller.enqueue({ type: "stream-start", warnings: [] });
+                    controller.enqueue({ type: "response-metadata", id: "response-streamed", modelId: "router-test" });
+                    controller.enqueue({ type: "text-start", id: "text-1" });
+                    controller.enqueue({ type: "text-delta", id: "text-1", delta: "ok" });
+                    controller.enqueue({ type: "text-end", id: "text-1" });
+                    controller.enqueue({
+                        type: "finish",
+                        finishReason: { unified: "stop", raw: "completed" },
+                        usage,
+                        providerMetadata,
+                    });
+                    controller.close();
+                },
+            }),
+            response: {},
+        }),
+    } as unknown as LanguageModel;
+    const config = {
+        model: "router-test",
+        languageModel,
+        fetchTimeoutMs: 5_000,
+        temperature: 0.2,
+        repeatPenalty: 1.15,
+        reasoning: { mode: "off" as const, budget: null },
+        retryAttempts: 0,
+        normalizeCharge: authoritativeChargeNormalizer("@openrouter/ai-sdk-provider"),
+    };
+
+    await t.test("buffered", async () => {
+        const response = await new AiSdkProvider({ ...config, streaming: false })
+            .generate({ workerId: "buffered", messages: [] });
+        assert.deepEqual(response.charge, charge);
+    });
+    await t.test("streamed", async () => {
+        const response = await new AiSdkProvider(config)
+            .generate({ workerId: "streamed", messages: [] });
+        assert.deepEqual(response.charge, charge);
+    });
+});
+
+test("compatible xAI wire usage becomes an exact tick charge without raw-body capture", async () => {
+    const p = new AiSdkProvider({
+        model: "grok-test",
+        url: "http://x/v1/chat/completions",
+        fetchTimeoutMs: 5_000,
+        temperature: 0.2,
+        repeatPenalty: 1.15,
+        reasoning: { mode: "off", budget: null },
+        retryAttempts: 0,
+        streaming: false,
+        normalizeCharge: authoritativeChargeNormalizer("@ai-sdk/xai"),
+    });
+    installFetchJson({
+        id: "response-1",
+        model: "grok-test",
+        choices: [{ message: { content: "ok" }, finish_reason: "stop" }],
+        usage: {
+            prompt_tokens: 2,
+            completion_tokens: 1,
+            total_tokens: 3,
+            cost_in_usd_ticks: 15_493_500,
+        },
+    });
+    const response = await p.generate({ workerId: "xai", messages: [] });
+    assert.deepEqual(response.charge, {
+        kind: "authoritative",
+        amount: { amount: "15493500", currency: "USDTICK" },
+        usdEquivalent: "0.00154935",
+        source: "xAI response usage.cost_in_usd_ticks",
+    });
+    assert.equal(response.rawBody, undefined);
+});
+
+test("streamed xAI final usage retains its exact tick charge", async () => {
+    const p = new AiSdkProvider({
+        model: "grok-test",
+        url: "http://x/v1/chat/completions",
+        fetchTimeoutMs: 5_000,
+        temperature: 0.2,
+        repeatPenalty: 1.15,
+        reasoning: { mode: "off", budget: null },
+        retryAttempts: 0,
+        normalizeCharge: authoritativeChargeNormalizer("@ai-sdk/xai"),
+    });
+    installFetch([
+        { choices: [{ delta: { content: "ok" }, finish_reason: "stop" }] },
+        {
+            choices: [],
+            usage: {
+                prompt_tokens: 2,
+                completion_tokens: 1,
+                total_tokens: 3,
+                cost_in_usd_ticks: 15_493_500,
+            },
+        },
+    ]);
+    const response = await p.generate({ workerId: "xai", messages: [] });
+    assert.deepEqual(response.charge, {
+        kind: "authoritative",
+        amount: { amount: "15493500", currency: "USDTICK" },
+        usdEquivalent: "0.00154935",
+        source: "xAI response usage.cost_in_usd_ticks",
+    });
+});
+
 test("generate surfaces and normalizes an out-of-set finish_reason", async () => {
     const warnings: Array<{ message: string; code?: string }> = [];
     mock.method(process, "emitWarning", (message: string | Error, options?: string | { code?: string }) => {
@@ -311,7 +462,88 @@ test("generate surfaces and normalizes an out-of-set finish_reason", async () =>
     }]);
 });
 
-test("generate translates a backend cap synonym to canonical length (#425)", async () => {
+test("#161: a streamed resource interruption is a failed exchange with complete attempt evidence", async () => {
+    const calls = installFetch([
+        { model: "served-model", choices: [{ delta: { reasoning_content: "partial thought", content: "partial answer" } }] },
+        {
+            choices: [{ delta: {}, finish_reason: "insufficient_system_resource" }],
+            usage: { prompt_tokens: 7, completion_tokens: 5, total_tokens: 12 },
+        },
+    ]);
+    const provider = new AiSdkProvider({
+        ...injectedBase,
+        retryAttempts: 2,
+        rawBody: true,
+    });
+
+    await assert.rejects(
+        provider.generate({ workerId: "interrupted", messages: [{ role: "user", content: "hello" }] }),
+        (error: unknown) => {
+            assert.ok(error instanceof ProviderError);
+            assert.equal(error.kind, "resource_interrupted");
+            assert.equal(error.status, 503);
+            assert.equal(error.problem.stage, "provider-response");
+            assert.equal(error.problem.retryable, false);
+            assert.equal(error.problem.finishReason, "resource_interrupted");
+            assert.equal(error.problem.rawFinishReason, "insufficient_system_resource");
+            assert.equal(error.attempt?.assistant.content, "partial answer");
+            assert.equal(error.attempt?.assistant.reasoning, "partial thought");
+            assert.equal(error.attempt?.assistant.finishReason, "resource_interrupted");
+            assert.deepEqual(error.attempt?.assistant.usage, {
+                prompt: 7,
+                completion: 2,
+                reasoning: 3,
+                cached: 0,
+                total: 12,
+            });
+            assert.equal(
+                (error.attempt?.assistantRaw as { rawFinishReason?: string }).rawFinishReason,
+                "insufficient_system_resource",
+            );
+            assert.ok(Array.isArray(error.attempt?.rawBody));
+            return true;
+        },
+    );
+    assert.equal(calls.length, 1, "a semantic interruption is not replayed as an HTTP failure");
+});
+
+test("#161: a buffered resource interruption preserves the successful wire response as failed-attempt evidence", async () => {
+    const wire = {
+        model: "served-model",
+        choices: [{
+            message: { content: "partial answer", reasoning_content: "partial thought" },
+            finish_reason: "insufficient_system_resource",
+        }],
+        usage: { prompt_tokens: 7, completion_tokens: 5, total_tokens: 12 },
+    };
+    const calls = installFetchJson(wire);
+    const provider = new AiSdkProvider({
+        ...injectedBase,
+        streaming: false,
+        retryAttempts: 2,
+        rawBody: true,
+    });
+
+    await assert.rejects(
+        provider.generate({ workerId: "interrupted", messages: [{ role: "user", content: "hello" }] }),
+        (error: unknown) => {
+            assert.ok(error instanceof ProviderError);
+            assert.equal(error.kind, "resource_interrupted");
+            assert.equal(error.attempt?.assistant.content, "partial answer");
+            assert.equal(error.attempt?.assistant.reasoning, "partial thought");
+            assert.equal(error.attempt?.assistant.finishReason, "resource_interrupted");
+            assert.deepEqual(error.attempt?.rawBody, wire);
+            assert.equal(
+                (error.attempt?.assistantRaw as { rawFinishReason?: string }).rawFinishReason,
+                "insufficient_system_resource",
+            );
+            return true;
+        },
+    );
+    assert.equal(calls.length, 1);
+});
+
+test("generate translates a backend cap synonym to canonical length", async () => {
     // gemini shouts MAX_TOKENS, anthropic says max_tokens -- both must reach core as
     // "length" so its truncation check (=== "length") is a cross-backend invariant.
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
@@ -320,7 +552,7 @@ test("generate translates a backend cap synonym to canonical length (#425)", asy
     assert.equal(assistant.finishReason, "length");
 });
 
-test("generate translates end_turn to canonical stop (#425)", async () => {
+test("generate translates end_turn to canonical stop", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     installFetch([{ choices: [{ delta: { content: "x" }, finish_reason: "end_turn" }] }]);
     const { assistant } = await p.generate({ workerId: "r", messages: [] });
@@ -339,10 +571,172 @@ test("generate aggregates reasoning deltas under multiple field names", async ()
     installFetch([{ choices: [{ delta: { reasoning_content: "be", thinking: "cause" } }] }]);
     const { assistant } = await p.generate({ workerId: "r", messages: [] });
     assert.equal(assistant.reasoning, "because");
-    assert.equal("reasoningEncrypted" in assistant, false); // open reasoning only -> field absent (#482)
+    assert.equal("reasoningEncrypted" in assistant, false); // open reasoning only -> field absent
+});
+
+test("{§provider-tagged-reasoning} explicit think-tags projects one streamed leading envelope and reclassifies usage", async () => {
+    const config = { ...injectedBase, reasoningResponseStyle: "think-tags" as const, rawBody: true };
+    const p = new AiSdkProvider(config);
+    installFetch([
+        { choices: [{ delta: { content: "<thi" } }] },
+        { choices: [{ delta: { content: "nk>12345</th" } }] },
+        { choices: [{ delta: { content: "ink>abcde" }, finish_reason: "stop" }] },
+        { usage: { prompt_tokens: 3, completion_tokens: 10, total_tokens: 13 } },
+    ]);
+
+    const response = await p.generate({ workerId: "tagged-stream", messages: [] });
+
+    assert.equal(response.assistant.reasoning, "12345");
+    assert.equal(response.assistant.content, "abcde");
+    assert.deepEqual(response.assistant.usage, {
+        prompt: 3,
+        completion: 5,
+        reasoning: 5,
+        cached: 0,
+        total: 13,
+    });
+    assert.deepEqual(
+        ((response.assistantRaw as { content: string; reasoning: string }).content),
+        "abcde",
+    );
+    assert.equal((response.assistantRaw as { reasoning: string }).reasoning, "12345");
+    assert.match(JSON.stringify(response.rawBody), /<thi/);
+    assert.match(JSON.stringify(response.rawBody), /nk>12345/);
+});
+
+test("{§provider-tagged-reasoning} explicit think-tags projects one buffered leading envelope", async () => {
+    installFetchJson({
+        model: "m",
+        choices: [{ message: { content: "<think>12345</think>abcde" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 3, completion_tokens: 10, total_tokens: 13 },
+    });
+    const config = { ...injectedBase, streaming: false, reasoningResponseStyle: "think-tags" as const };
+    const response = await new AiSdkProvider(config).generate({ workerId: "tagged-buffer", messages: [] });
+
+    assert.equal(response.assistant.reasoning, "12345");
+    assert.equal(response.assistant.content, "abcde");
+    assert.equal(response.assistant.usage.completion, 5);
+    assert.equal(response.assistant.usage.reasoning, 5);
+});
+
+test("{§provider-tagged-reasoning} tagged text does not overwrite itemized reasoning usage", async () => {
+    installFetchJson({
+        model: "m",
+        choices: [{ message: { content: "<think>12345</think>abcde" }, finish_reason: "stop" }],
+        usage: {
+            prompt_tokens: 3,
+            completion_tokens: 10,
+            total_tokens: 13,
+            completion_tokens_details: { reasoning_tokens: 3 },
+        },
+    });
+    const config = { ...injectedBase, streaming: false, reasoningResponseStyle: "think-tags" as const };
+    const response = await new AiSdkProvider(config).generate({ workerId: "tagged-itemized", messages: [] });
+
+    assert.equal(response.assistant.reasoning, "12345");
+    assert.equal(response.assistant.content, "abcde");
+    assert.equal(response.assistant.usage.completion, 7);
+    assert.equal(response.assistant.usage.reasoning, 3);
+});
+
+test("{§provider-tagged-reasoning} an unclosed capped envelope is wholly reasoning in streamed and buffered responses", async () => {
+    const config = { ...injectedBase, reasoningResponseStyle: "think-tags" as const };
+    installFetch([
+        { choices: [{ delta: { content: "<think>unfinished" }, finish_reason: "length" }] },
+        { usage: { prompt_tokens: 3, completion_tokens: 8, total_tokens: 11 } },
+    ]);
+    const streamed = await new AiSdkProvider(config).generate({ workerId: "tagged-capped-stream", messages: [] });
+    assert.equal(streamed.assistant.reasoning, "unfinished");
+    assert.equal(streamed.assistant.content, "");
+    assert.deepEqual(streamed.assistant.usage, {
+        prompt: 3,
+        completion: 0,
+        reasoning: 8,
+        cached: 0,
+        total: 11,
+    });
+
+    mock.restoreAll();
+    installFetchJson({
+        model: "m",
+        choices: [{ message: { content: "<think>unfinished" }, finish_reason: "length" }],
+        usage: { prompt_tokens: 3, completion_tokens: 8, total_tokens: 11 },
+    });
+    const bufferedConfig = { ...config, streaming: false };
+    const buffered = await new AiSdkProvider(bufferedConfig).generate({ workerId: "tagged-capped-buffer", messages: [] });
+    assert.equal(buffered.assistant.reasoning, "unfinished");
+    assert.equal(buffered.assistant.content, "");
+    assert.equal(buffered.assistant.usage.completion, 0);
+    assert.equal(buffered.assistant.usage.reasoning, 8);
 });
 
-test("#482 sealed relay reasoning (non-streamed): encrypted reasoning_details surface verbatim, text entries do not", async () => {
+test("{§provider-tagged-reasoning} verbatim, non-leading, and structured-reasoning controls preserve literal tags", async () => {
+    installFetchJson({
+        model: "m",
+        choices: [{ message: { content: "<think>literal</think>answer" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 1, completion_tokens: 4, total_tokens: 5 },
+    });
+    const verbatim = await new AiSdkProvider({ ...injectedBase, streaming: false })
+        .generate({ workerId: "verbatim", messages: [] });
+    assert.equal(verbatim.assistant.content, "<think>literal</think>answer");
+    assert.equal(verbatim.assistant.reasoning, null);
+    assert.equal(verbatim.assistant.usage.completion, 4);
+
+    mock.restoreAll();
+    installFetchJson({
+        model: "m",
+        choices: [{ message: { content: "show <think>literal</think> exactly" }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 1, completion_tokens: 5, total_tokens: 6 },
+    });
+    const taggedConfig = { ...injectedBase, streaming: false, reasoningResponseStyle: "think-tags" as const };
+    const nonLeading = await new AiSdkProvider(taggedConfig)
+        .generate({ workerId: "non-leading", messages: [] });
+    assert.equal(nonLeading.assistant.content, "show <think>literal</think> exactly");
+    assert.equal(nonLeading.assistant.reasoning, null);
+
+    mock.restoreAll();
+    installFetchJson({
+        model: "m",
+        choices: [{ message: {
+            content: "<think>literal visible bytes</think>",
+            reasoning_content: "structured reasoning",
+        }, finish_reason: "stop" }],
+        usage: { prompt_tokens: 1, completion_tokens: 7, total_tokens: 8 },
+    });
+    const structured = await new AiSdkProvider(taggedConfig)
+        .generate({ workerId: "structured", messages: [] });
+    assert.equal(structured.assistant.content, "<think>literal visible bytes</think>");
+    assert.equal(structured.assistant.reasoning, "structured reasoning");
+});
+
+test("{§provider-tagged-reasoning} grammar evidence retains the exact pre-projection tagged sentence", async () => {
+    const content = "<think>🧠reason</think><<PLAN::PLAN\n<<SEND[200]:done:SEND";
+    const config = {
+        ...injectedBase,
+        contextWindow: 640,
+        reasoning: { mode: "adaptive" as const, budget: null },
+        reasoningResponseStyle: "think-tags" as const,
+        reasoningStyle: "think" as const,
+        grammarStyle: "llamacpp" as const,
+    };
+    installFetch([{ choices: [{ delta: { content }, finish_reason: "stop" }] }]);
+
+    const response = await new AiSdkProvider(config).generate({
+        workerId: "tagged-grammar",
+        messages: [],
+        grammar: `root ::= ${JSON.stringify(content)}`,
+    });
+
+    assert.equal(response.assistant.reasoning, "🧠reason");
+    assert.equal(response.assistant.content, "<<PLAN::PLAN\n<<SEND[200]:done:SEND");
+    assert.deepEqual(response.grammarEvidence, {
+        input: content,
+        contentStart: [..."<think>🧠reason</think>"].length,
+        transported: true,
+    });
+});
+
+test("encrypted reasoning (non-streamed): encrypted entries normalize and text entries stay separate", async () => {
     // The live o4-mini-via-OpenRouter shape: reasoning null, one encrypted entry.
     installFetchJson({ model: "m", choices: [{ message: {
         content: "4", reasoning: null,
@@ -353,13 +747,14 @@ test("#482 sealed relay reasoning (non-streamed): encrypted reasoning_details su
     }, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 } });
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false });
     const { assistant } = await p.generate({ workerId: "r", messages: [] });
-    // item shape: wire `id` preserved, subtype from position (#482 widening)
+    // Wire detail ID is preserved; the assistant-message location supports the
+    // derived classification but supplies no downstream client entity ID.
     assert.deepEqual(assistant.reasoningEncrypted, [{ id: "rs_1", subtype: "message", encrypted: [{ data: "gAAAAABqBLOB", format: "openai-responses-v1" }] }]);
-    assert.equal(assistant.reasoning, null); // sealed turn: nothing readable
+    assert.equal(assistant.reasoning, null); // Encrypted turn: nothing readable.
     assert.equal(assistant.content, "4");
 });
 
-test("#482 widening: distinct wire ids stay distinct items (a single-object shape would collide them)", async () => {
+test("distinct encrypted-reasoning wire ids stay distinct items", async () => {
     installFetchJson({ model: "m", choices: [{ message: { content: "ok", reasoning: null, reasoning_details: [
         { type: "reasoning.encrypted", data: "AAA", format: "openai-responses-v1", id: "rs_1" },
         { type: "reasoning.encrypted", data: "BBB", format: "openai-responses-v1", id: "rs_2" },
@@ -370,7 +765,20 @@ test("#482 widening: distinct wire ids stay distinct items (a single-object shap
     assert.deepEqual(assistant.reasoningEncrypted?.map((i) => i.id), ["rs_1", "rs_2"]);
 });
 
-test("#482 sealed relay reasoning (streamed): chunked blob concatenates per entry index", async () => {
+test("assistant-message location classifies encrypted reasoning without inventing a missing detail id", async () => {
+    installFetchJson({ model: "m", choices: [{ message: { content: "ok", reasoning_details: [
+        { type: "reasoning.encrypted", data: "OPAQUE", format: "openai-responses-v1", id: null, index: 0 },
+    ] }, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 } });
+    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false });
+    const { assistant } = await p.generate({ workerId: "r", messages: [] });
+    assert.deepEqual(assistant.reasoningEncrypted, [{
+        id: null,
+        subtype: "message",
+        encrypted: [{ data: "OPAQUE", format: "openai-responses-v1" }],
+    }]);
+});
+
+test("encrypted reasoning (streamed): chunked blob concatenates per entry index", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     installFetch([
         { choices: [{ delta: { reasoning_details: [{ type: "reasoning.encrypted", data: "gAAAA", format: "openai-responses-v1", id: "rs_1", index: 0 }] } }] },
@@ -402,10 +810,10 @@ test("reasoningStyle 'effort' sends a reasoning_effort tier from the budget", as
     assert.equal(JSON.parse(calls[0].init.body as string).reasoning_effort, "high");
 });
 
-test("reasoningStyle 'effort_explicit': off SENDS none, adaptive OMITS (#403 — literal is MiniMax-only), on sends the tier", async () => {
+test("reasoningStyle 'effort_explicit': off SENDS none, adaptive OMITS, on sends the tier", async () => {
     // expected === null → the field must be ABSENT from the wire body. Fireworks
     // 400s reasoning_effort='adaptive' for non-MiniMax models (wire-verified,
-    // #403): adaptive = the backend's own default posture = omission.
+    // Adaptive = the backend's own default posture = omission.
     for (const [reasoning, expected] of [[{ mode: "off", budget: null }, "none"], [{ mode: "adaptive", budget: null }, null], [{ mode: "on", budget: 5000 }, "high"]] as Array<[{ mode: "off" | "adaptive" | "on"; budget: number | null }, string | null]>) {
         const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning, retryAttempts: 0, reasoningStyle: "effort_explicit" });
         const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
@@ -417,7 +825,39 @@ test("reasoningStyle 'effort_explicit': off SENDS none, adaptive OMITS (#403 —
     }
 });
 
-test("the family temperature default rides every request; caller sampling overrides it (#30)", async () => {
+test("{§deepseek-reasoning-request} #157: thinking_effort maps the complete DeepSeek reasoning contract", async () => {
+    const cases = [
+        [{ mode: "off", budget: null }, { thinking: { type: "disabled" } }],
+        [{ mode: "adaptive", budget: null }, {}],
+        [{ mode: "on", budget: 5000 }, { thinking: { type: "enabled" }, reasoning_effort: "high" }],
+    ] as const;
+    for (const [reasoning, expected] of cases) {
+        const p = new AiSdkProvider({
+            model: "m",
+            url: "http://x/v1/chat/completions",
+            fetchTimeoutMs: 5000,
+            temperature: 0.2,
+            repeatPenalty: 1.15,
+            reasoning,
+            retryAttempts: 0,
+            reasoningStyle: "thinking_effort",
+        });
+        const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
+        await p.generate({
+            workerId: "r",
+            messages: [],
+            sampling: { thinking: { type: "disabled" }, reasoning_effort: "max" },
+        });
+        const body = JSON.parse(calls[0].init.body as string);
+        assert.deepEqual(
+            Object.fromEntries(Object.entries(body).filter(([key]) => key === "thinking" || key === "reasoning_effort")),
+            expected,
+        );
+        mock.restoreAll();
+    }
+});
+
+test("the family temperature default rides every request; caller sampling overrides it", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     let calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "r", messages: [] });
@@ -434,7 +874,7 @@ test("the family temperature default rides every request; caller sampling overri
     assert.equal(JSON.parse(calls[0].init.body as string).temperature, 0.2);
 });
 
-test("#567: DRY + repeat_last_n ride the llamacpp path when set; unset leaves the box default; never on cloud", async () => {
+test("DRY + repeat_last_n ride the llamacpp path when set; unset leaves the box default; never on cloud", async () => {
     const base = { model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off" as const, budget: null }, retryAttempts: 0 };
     // set + llamacpp -> the loop-breakers ride the wire
     const p = new AiSdkProvider({ ...base, grammarStyle: "llamacpp", dryMultiplier: 0.8, dryBase: 1.75, dryAllowedLength: 2, repeatLastN: 512 });
@@ -474,14 +914,14 @@ test("llamacpp grammar path: temperature default + the managed repeat-penalty fl
     assert.equal(body.repeat_penalty, 1.15);
 });
 
-test("#426: the repeat penalty rides EVERY request rail-off, keyed per backend (cloud degeneration guard)", async () => {
+test("the repeat penalty rides every request rail-off, keyed per backend", async () => {
     // llama.cpp with NO grammar carries its key too (unconstrained local is guarded)
     const llama = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp" });
     let calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await llama.generate({ workerId: "r", messages: [] });
     assert.equal(JSON.parse(calls[0].init.body as string).repeat_penalty, 1.15);
     mock.restoreAll();
-    // a `none`-style cloud backend WITH a frequency penalty gets frequency_penalty (OpenAI-standard, #426)
+    // A `none`-style cloud backend with a frequency penalty gets frequency_penalty.
     const cloud = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, frequencyPenalty: 0.4, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await cloud.generate({ workerId: "r", messages: [] });
@@ -520,7 +960,7 @@ test("sampling passthrough forwards caller params; managed + reserved keys win",
     assert.equal("id_slot" in body, false); // reserved slot key stripped
 });
 
-test("#477 sampling passthrough guards contract invariants: n/tools/caps stripped, platform knobs pass", async () => {
+test("sampling passthrough guards contract invariants: n/tools/caps stripped, platform knobs pass", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({
@@ -531,7 +971,7 @@ test("#477 sampling passthrough guards contract invariants: n/tools/caps strippe
             n: 3,                                                    // breaks choices[0] atomicity -> stripped
             tools: [{ type: "function" }], tool_choice: "auto",      // tools-in-body doctrine -> stripped
             modalities: ["text", "audio"], prediction: { type: "content" }, // text-only / decode semantics -> stripped
-            max_tokens: 999999, max_completion_tokens: 999999,       // envelope bypass (#425 cap) -> stripped
+            max_tokens: 999999, max_completion_tokens: 999999,       // envelope bypass -> stripped
             seed: 42, user: "acct-7", service_tier: "flex",          // platform/sampling intent -> pass
         },
     });
@@ -545,58 +985,134 @@ test("#477 sampling passthrough guards contract invariants: n/tools/caps strippe
     assert.equal(body.service_tier, "flex");
 });
 
-test("#488 postmortem: intent maps IDENTICALLY under a transported grammar — sanctioned channel coexists with rails", async () => {
-    // The brief rails-win-the-channel clamp is REVERTED: closing the channel starved a
-    // reasoning-tuned model into escaping mid-content (unconstrained, discarded, billed).
-    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
+test("template reasoning returns the exact pre-projection grammar sentence ({§gbnf-response-observation})", async () => {
+    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { tokens: 64 }, completionReserve: { tokens: 160 }, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
+    const grammarInput = "<|channel>thought\ncon🙂sider<channel|>x";
+    const calls = installFetch([{ choices: [{ delta: { content: grammarInput } }] }]);
+    const res = await p.generate({ workerId: "r", messages: [], grammar: `root ::= ${JSON.stringify(grammarInput)}` });
+    const body = JSON.parse(calls[0].init.body as string);
+    assert.deepEqual(body.chat_template_kwargs, { enable_thinking: true });
+    assert.equal(body.reasoning_format, "none");
+    assert.equal(body.thinking_budget_tokens, 64);
+    assert.equal(body.grammar, `root ::= ${JSON.stringify(grammarInput)}`);
+    assert.equal(res.assistant.reasoning, "con🙂sider");
+    assert.equal(res.assistant.content, "x");
+    assert.deepEqual(res.grammarEvidence, {
+        input: grammarInput,
+        contentStart: [..."<|channel>thought\ncon🙂sider<channel|>"].length,
+        transported: true,
+    });
+    assert.equal(res.meta?.railsVerdict, undefined, "the provider represents evidence but does not grade itself");
+});
+
+test("a verbatim template response remains exact evidence when it has no channel envelope", async () => {
+    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { tokens: 64 }, completionReserve: { tokens: 160 }, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
+    const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
+    const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "x"' });
+    const body = JSON.parse(calls[0].init.body as string);
+    assert.equal(body.reasoning_format, "none");
+    assert.deepEqual(res.grammarEvidence, { input: "x", contentStart: 0, transported: true });
+});
+
+test("a template grammar preserves exact evidence when reasoning is disabled", async () => {
+    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { tokens: 64 }, completionReserve: { tokens: 160 }, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "x"' });
     const body = JSON.parse(calls[0].init.body as string);
-    assert.deepEqual(body.chat_template_kwargs, { enable_thinking: true }); // channel stays sanctioned under the grammar
-    assert.equal(typeof body.grammar, "string"); // rails ride beside it
-    // #488 per-request loud state: rail attachment + verdict on meta, drill-readable per turn
-    assert.equal(res.meta?.railsAttached, true);
-    assert.equal(res.meta?.railsVerdict, "accept");
+    assert.deepEqual(body.chat_template_kwargs, { enable_thinking: false });
+    assert.equal(body.reasoning_format, "none");
+    assert.deepEqual(res.grammarEvidence, { input: "x", contentStart: 0, transported: true });
+});
+
+test("an unexpectedly projected template response cannot claim pre-projection evidence", async () => {
+    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { tokens: 64 }, completionReserve: { tokens: 160 }, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
+    installFetch([{ choices: [{ delta: { reasoning_content: "reason", content: "x" } }] }]);
+    const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "x"' });
+    assert.equal(res.grammarEvidence, undefined);
+});
+
+test("template reasoning preserves an empty grammar-required channel as exact evidence", async () => {
+    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { tokens: 64 }, completionReserve: { tokens: 160 }, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
+    const input = "<|channel>thought\n<channel|>x";
+    const calls = installFetch([{ choices: [{ delta: { content: input } }] }]);
+    const res = await p.generate({ workerId: "r", messages: [], grammar: `root ::= ${JSON.stringify(input)}` });
+    const body = JSON.parse(calls[0].init.body as string);
+    assert.equal(body.reasoning_format, "none");
+    assert.equal(res.assistant.reasoning, null);
+    assert.equal(res.assistant.content, "x");
+    assert.deepEqual(res.grammarEvidence, {
+        input,
+        contentStart: [..."<|channel>thought\n<channel|>"].length,
+        transported: true,
+    });
 });
 
-test("#488 channel-escape detector: billed completion tokens vastly beyond visible channels attach grammar_unenforced", async () => {
+test("channel-escape detector: billed completion tokens vastly beyond visible channels attach grammar_unenforced", async () => {
     // The run105 shape: tiny visible content, no reasoning, thousands billed — the decode
     // escaped into a discarded reasoning block, unconstrained.
-    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
-    installFetch([
+    const chunks = [
         { choices: [{ delta: { content: "x" }, finish_reason: "length" }] },
         { usage: { prompt_tokens: 10, completion_tokens: 5000, total_tokens: 5010 } },
-    ]);
+    ];
+    const fetch: typeof globalThis.fetch = async (input, init) => {
+        if (String(input).endsWith("/tokenize")) {
+            const body = JSON.parse(String(init?.body)) as { content: string };
+            return new Response(JSON.stringify({
+                tokens: body.content.length === 0 ? [] : [1],
+            }), { headers: { "content-type": "application/json" } });
+        }
+        return new Response(sseStream(chunks), { status: 200 });
+    };
+    const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetch, tokenizeUrl: "http://x/tokenize", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
     const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "x"' });
-    assert.equal(res.meta?.railsVerdict, "accept"); // the visible fragment conforms...
-    const escape = res.telemetry?.find((e) => e.message?.includes("escaped the grammar") === true);
-    assert.ok(escape, "escape telemetry attached");
+    const escape = res.notices?.find((e) => e.message.includes("escaped the grammar"));
+    assert.ok(escape, "escape notice attached");
     assert.equal(escape!.kind, "grammar_unenforced");
     assert.match(escape!.message ?? "", /5000 completion tokens billed/);
 });
 
-test("#488 loud state absent on grammarless calls; no escape event without a transported grammar", async () => {
+test("channel-escape state is absent without a transported grammar", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template", grammarStyle: "llamacpp" });
     installFetch([
         { choices: [{ delta: { content: "x" }, finish_reason: "length" }] },
         { usage: { prompt_tokens: 10, completion_tokens: 5000, total_tokens: 5010 } },
     ]);
     const res = await p.generate({ workerId: "r", messages: [] }); // no grammar arg
-    assert.equal(res.meta?.railsAttached, undefined);
-    assert.equal(res.telemetry, undefined);
+    assert.equal(res.grammarEvidence, undefined);
+    assert.equal(res.notices, undefined);
 });
 
-test("reasoningStyle 'template' always emits enable_thinking mirroring budget != 0 — explicit false, never omitted", async () => {
-    const on = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template" });
+test("reasoningStyle 'template' sends llama-server activation, parser, and response-wide allowance", async () => {
+    const on = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { percent: 0.1 }, completionReserve: { percent: 0.25 }, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "adaptive", budget: null }, retryAttempts: 0, reasoningStyle: "template" });
     let calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await on.generate({ workerId: "r", messages: [] });
-    assert.deepEqual(JSON.parse(calls[0].init.body as string).chat_template_kwargs, { enable_thinking: true });
+    let body = JSON.parse(calls[0].init.body as string);
+    assert.deepEqual(body.chat_template_kwargs, { enable_thinking: true });
+    assert.equal(body.reasoning_format, "auto");
+    assert.equal(body.thinking_budget_tokens, 64);
 
     mock.restoreAll();
-    const off = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, reasoningStyle: "template" });
+    const off = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { percent: 0.1 }, completionReserve: { percent: 0.25 }, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, reasoningStyle: "template" });
     calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await off.generate({ workerId: "r", messages: [] });
-    assert.deepEqual(JSON.parse(calls[0].init.body as string).chat_template_kwargs, { enable_thinking: false });
+    body = JSON.parse(calls[0].init.body as string);
+    assert.deepEqual(body.chat_template_kwargs, { enable_thinking: false });
+    assert.equal(body.reasoning_format, "auto");
+    assert.equal(body.thinking_budget_tokens, 0);
+});
+
+test("reasoningStyle 'template' explicit budget tightens the reserve and cannot exceed it", async () => {
+    const base = { model: "m", url: "http://x/v1/chat/completions", contextWindow: 640, reasoningReserve: { tokens: 64 } as const, completionReserve: { tokens: 160 } as const, fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, retryAttempts: 0, reasoningStyle: "template" as const };
+    const p = new AiSdkProvider({ ...base, reasoning: { mode: "on", budget: 32 } });
+    const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
+    await p.generate({ workerId: "r", messages: [], sampling: { thinking_budget_tokens: 999, reasoning_format: "none" } });
+    const body = JSON.parse(calls[0].init.body as string);
+    assert.equal(body.thinking_budget_tokens, 32);
+    assert.equal(body.reasoning_format, "auto");
+    assert.throws(
+        () => new AiSdkProvider({ ...base, reasoning: { mode: "on", budget: 65 } }),
+        /REASONING_BUDGET \(65\) exceeds the resolved PLURNK_PROVIDERS_REASONING_RESERVE \(64\)/,
+    );
 });
 
 test("budget 0 suppresses effort and include_reasoning", async () => {
@@ -619,7 +1135,7 @@ test("reasoningStyle 'include_reasoning' sets the relay passthrough toggle", asy
     assert.equal(JSON.parse(calls[0].init.body as string).include_reasoning, true);
 });
 
-// — grammar-constrained sampling (SPEC §13, issues #8/#9) —
+// — grammar-constrained sampling —
 
 test("grammar transport 'llamacpp': top-level grammar + the repeat-penalty floor", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp" });
@@ -640,106 +1156,81 @@ test("grammar transport 'none' (default): the grammar is never sent — no silen
     assert.equal("response_format" in body, false);
 });
 
-// — grammar conformance OBSERVATION (SPEC §10.14, §13): a completed exchange always
-//   returns; bytes flow; a non-accept verdict rides response.telemetry —
+// — exact pre-projection grammar evidence ({§gbnf-response-observation}) —
 
 const grammarProvider = () => new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp", source: "provider:test" });
 const streamingContent = (content: string) => installFetch([{ choices: [{ delta: { content }, finish_reason: "stop" }] }]);
 
-test("enforcement: conforming output passes through unchanged", async () => {
+test("an unsplit grammar response carries the exact observed sentence", async () => {
     const p = grammarProvider();
     streamingContent("ok");
-    const { assistant } = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
-    assert.equal(assistant.content, "ok");
-});
-
-test("observation: REJECTED output still returns — bytes present, verdict attached with position", async () => {
-    const p = grammarProvider();
-    streamingContent("no");
     const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
-    assert.equal(res.assistant.content, "no"); // bytes ALWAYS flow
-    assert.equal(res.telemetry?.length, 1);
-    const ev = res.telemetry![0];
-    assert.equal(ev.kind, "grammar_unenforced");
-    assert.equal(ev.source, "provider:test");
-    assert.match(String(ev.message), /grammar not enforced: output rejected .* at code point 0/);
-    assert.equal(ev.position, 0); // divergence offset for consumer policy
-});
-
-test("observation: an incomplete (valid prefix, never terminated) also returns with the verdict", async () => {
-    const p = grammarProvider();
-    streamingContent("ok");
-    const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok" "!"' });
     assert.equal(res.assistant.content, "ok");
-    assert.equal(res.telemetry?.length, 1);
-    assert.match(String(res.telemetry![0].message), /incomplete match .* never terminated/);
-    assert.equal(res.telemetry![0].position, 2);
+    assert.deepEqual(res.grammarEvidence, {
+        input: "ok",
+        contentStart: 0,
+        transported: true,
+    });
 });
 
-test("observation: conforming output attaches NO telemetry", async () => {
+test("the provider returns rejected or incomplete bytes as evidence without grading them", async () => {
     const p = grammarProvider();
-    streamingContent("ok");
+    streamingContent("no");
     const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
-    assert.equal(res.telemetry, undefined);
+    assert.equal(res.assistant.content, "no");
+    assert.deepEqual(res.grammarEvidence, { input: "no", contentStart: 0, transported: true });
+    assert.equal(res.notices, undefined);
+    assert.equal(res.meta?.railsVerdict, undefined);
 });
 
-test("observation: empty content under a non-empty grammar returns with the verdict (the 'content never arrives' leak, observed)", async () => {
+test("empty unsplit content remains exact grammar evidence", async () => {
     const p = grammarProvider();
-    installFetch([{ choices: [{ delta: {}, finish_reason: "stop" }] }]); // no content delta → ""
+    installFetch([{ choices: [{ delta: {}, finish_reason: "stop" }] }]);
     const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
     assert.equal(res.assistant.content, "");
-    assert.equal(res.telemetry?.[0].kind, "grammar_unenforced");
+    assert.deepEqual(res.grammarEvidence, { input: "", contentStart: 0, transported: true });
 });
 
-test("enforcement: when no grammar is sent (grammarStyle 'none'), output is NOT validated — no wire fields, no error (SPEC )", async () => {
+test("grammarStyle 'none' produces no grammar observation", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 }); // grammarStyle defaults to "none"
     streamingContent("anything goes");
-    const { assistant } = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' }); // grammar passed but never transported
-    assert.equal(assistant.content, "anything goes"); // no enforcement check
+    const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
+    assert.equal(res.assistant.content, "anything goes");
+    assert.equal(res.grammarEvidence, undefined);
 });
 
-test("enforcement: a grammar our validator can't parse is a NON-FATAL verify gap — warn, return content", async () => {
+test("provider evidence does not depend on the local validator understanding the grammar", async () => {
     const p = grammarProvider();
     streamingContent("whatever");
-    const warnings: Error[] = [];
-    const onWarn = (w: Error) => warnings.push(w);
-    process.on("warning", onWarn);
-    const { assistant } = await p.generate({ workerId: "r", messages: [], grammar: 'foo ::= "a"' }); // no `root` rule → validateGbnf throws
-    await flush();
-    process.off("warning", onWarn);
-    assert.equal(assistant.content, "whatever"); // transport not failed
-    assert.ok(warnings.some((w) => (w as Error & { code?: string }).code === "PLURNK_GRAMMAR_UNVERIFIABLE"), "emitted the verify-gap warning");
+    const res = await p.generate({ workerId: "r", messages: [], grammar: 'foo ::= "a"' });
+    assert.equal(res.assistant.content, "whatever");
+    assert.deepEqual(res.grammarEvidence, { input: "whatever", contentStart: 0, transported: true });
+    assert.equal(res.notices, undefined);
 });
 
-// — PLURNK_PROVIDERS_GBNF_DEBUG: run unconstrained, then verify the free output against the grammar —
+// — PLURNK_PROVIDERS_GBNF_DEBUG: validate the grammar, withhold it, and preserve the observation —
 
-test("gbnfDebug: the grammar is NOT transported; conforming free output passes through with NO telemetry", async () => {
+test("gbnfDebug marks an unconstrained observation as not transported", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp", gbnfDebug: true, source: "provider:test" });
     const calls = installFetch([{ choices: [{ delta: { content: "ok" }, finish_reason: "stop" }] }]);
     const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
     const body = JSON.parse(calls[0].init.body as string);
-    assert.equal("grammar" in body, false);            // grammar never sent — model ran unconstrained
-    assert.equal(body.repeat_penalty, 1.15);           // #426: penalty rides even rail-off - unconstrained decode needs it MORE
-    assert.equal(res.assistant.content, "ok");         // free output happens to conform → returned
-    assert.equal("telemetry" in res, false);           // conforming → no event
+    assert.equal("grammar" in body, false);
+    assert.equal(body.repeat_penalty, 1.15);
+    assert.equal(res.assistant.content, "ok");
+    assert.deepEqual(res.grammarEvidence, { input: "ok", contentStart: 0, transported: false });
+    assert.equal(res.notices, undefined);
 });
 
-test("gbnfDebug: a conflict does NOT throw — it returns the bytes plus a grammar_unenforced telemetry event with the divergence position (#24)", async () => {
+test("gbnfDebug preserves conflicting bytes without a provider verdict", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp", gbnfDebug: true, source: "provider:test" });
-    const calls = installFetch([{ choices: [{ delta: { reasoning_content: "let me think about ok", content: "xon-conforming output" }, finish_reason: "stop" }] }]);
+    const calls = installFetch([{ choices: [{ delta: { content: "xon-conforming output" }, finish_reason: "stop" }] }]);
     const res = await p.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
-    // The model's bytes survive — not discarded by a throw (the empty-turn cascade root cause).
     assert.equal(res.assistant.content, "xon-conforming output");
-    assert.equal(res.assistant.reasoning, "let me think about ok");
-    // Non-fatal telemetry carries the divergence so the consumer can self-correct.
-    assert.equal(res.telemetry?.length, 1);
-    const [event] = res.telemetry ?? [];
-    assert.equal(event.source, "provider:test");
-    assert.equal(event.kind, "grammar_unenforced");
-    assert.equal(event.position, 0);                   // 'x' rejected at code point 0
-    assert.match(event.message ?? "", /output rejected by the transported grammar at code point 0 \("x"\)/);
+    assert.deepEqual(res.grammarEvidence, { input: "xon-conforming output", contentStart: 0, transported: false });
+    assert.equal(res.notices, undefined);
     const body = JSON.parse(calls[0].init.body as string);
-    assert.equal("grammar" in body, false);            // still never sent — diagnosed, not enforced
+    assert.equal("grammar" in body, false);
 });
 
 test("gbnfDebug: an INVALID grammar throws before any wire call — it never reaches the model", async () => {
@@ -752,7 +1243,7 @@ test("gbnfDebug: an INVALID grammar throws before any wire call — it never rea
     assert.equal(calls.length, 0); // fail-hard before the fetch — grammar never transported
 });
 
-// — meta bag: verbatim provider metadata (#23) —
+// — meta bag: verbatim provider metadata —
 
 test("meta: passes backend fields through without reinterpreting monetary values", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false });
@@ -763,7 +1254,7 @@ test("meta: passes backend fields through without reinterpreting monetary values
     assert.equal(res.meta?.system_fingerprint, "fp_abc");
 });
 
-// — first-party telemetry headers (attribution + client, SPEC §5) —
+// — first-party telemetry headers ({§provider-request-authority}) —
 
 const headerVal = (init: RequestInit, name: string): string | undefined =>
     new Headers(init.headers).get(name) ?? undefined;
@@ -776,7 +1267,7 @@ test("firstPartyMetadata: attributions + client ride as Plurnk-* headers", async
     assert.equal(headerVal(calls[0].init, "Plurnk-Client"), "plurnk.nvim/1.4.0");
 });
 
-test("#522 Plurnk-Worker-Primary: the lineage root rides under the gate; emitted even when it equals workerId", async () => {
+test("Plurnk-Worker-Primary: the lineage root rides under the gate; emitted even when it equals workerId", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, firstPartyMetadata: true });
     let calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "w-child", primaryWorkerId: "w-root", messages: [] });
@@ -795,7 +1286,7 @@ test("#522 Plurnk-Worker-Primary: the lineage root rides under the gate; emitted
     assert.equal(headerVal(calls[0].init, "Plurnk-Worker-Primary"), undefined);
 });
 
-test("#522 Plurnk-Worker-Primary is structurally dropped when firstPartyMetadata is off", async () => {
+test("Plurnk-Worker-Primary is structurally dropped when firstPartyMetadata is off", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "w-child", primaryWorkerId: "w-root", messages: [] });
@@ -818,13 +1309,13 @@ test("firstPartyMetadata on but empty values: no header emitted", async () => {
     assert.equal(headerVal(calls[0].init, "Plurnk-Client"), undefined);
 });
 
-test("grammar transport: no grammar passed sends no grammar field, but the penalty rides (#426)", async () => {
+test("grammar transport: no grammar passed sends no grammar field, but the penalty rides", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, grammarStyle: "llamacpp" });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "r", messages: [] });
     const body = JSON.parse(calls[0].init.body as string);
     assert.equal("grammar" in body, false);
-    assert.equal(body.repeat_penalty, 1.15);           // #426: penalty is no longer grammar-gated - it rides rail-off
+    assert.equal(body.repeat_penalty, 1.15);           // penalty is not grammar-gated
 });
 
 test("maxTokens transports as max_tokens; absent → no wire field (server default)", async () => {
@@ -839,7 +1330,7 @@ test("maxTokens transports as max_tokens; absent → no wire field (server defau
     assert.equal("max_tokens" in JSON.parse(calls[0].init.body as string), false);
 });
 
-test("slot affinity is internal: sticky per workerId, distinct runs spread across slots (#11)", async () => {
+test("slot affinity is internal: sticky per workerId, distinct workers spread across slots", async () => {
     const pinning = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, supportsSlotPinning: true, slotCount: 2 });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await pinning.generate({ workerId: "run-A", messages: [] });
@@ -863,7 +1354,7 @@ test("slot affinity: no pinning backend or unknown slotCount → no id_slot ever
     assert.equal("id_slot" in JSON.parse(calls[0].init.body as string), false);
 });
 
-test("slot affinity: a worker past the LRU window (slotCount*8) loses its pin; recent runs stay sticky (#11)", async () => {
+test("slot affinity: a worker past the LRU window (slotCount*8) loses its pin; recent workers stay sticky", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, supportsSlotPinning: true, slotCount: 2 });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     const slotOf = (i: number) => JSON.parse(calls[i].init.body as string).id_slot;
@@ -877,11 +1368,11 @@ test("slot affinity: a worker past the LRU window (slotCount*8) loses its pin; r
 });
 
 test("streaming:false: a non-ok response rejects as a classified ProviderError (covers the non-streamed transport)", async () => {
-    const { ProviderError } = await import("./telemetry.ts");
+    const { ProviderError } = await import("./errors.ts");
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, streaming: false, source: "provider:test" });
     mock.method(globalThis, "fetch", async () => new Response("boom", { status: 500 }));
     await assert.rejects(() => p.generate({ workerId: "r", messages: [] }), (err: unknown) => {
-        assert.ok(err instanceof ProviderError);
+        assert.ok(err instanceof ProviderError, `expected ProviderError, got ${String(err)}`);
         assert.equal(err.kind, "network_failure"); // ≥500 → network_failure
         assert.equal(err.status, 500);
         return true;
@@ -904,15 +1395,17 @@ test("messages pass through verbatim — the provider injects no turn (PLAN live
     assert.equal(res.assistant.content, "out"); // content returned verbatim
 });
 
-test("generate wraps an HTTP failure as a ProviderError carrying a TelemetryEvent", async () => {
-    const { ProviderError } = await import("./telemetry.ts");
+test("generate wraps an HTTP failure as a ProviderError carrying Problem Details", async () => {
+    const { ProviderError } = await import("./errors.ts");
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, source: "provider:test" });
     mock.method(globalThis, "fetch", async () => new Response("rate limited", { status: 429 }));
     await assert.rejects(() => p.generate({ workerId: "r", messages: [] }), (err: unknown) => {
-        assert.ok(err instanceof ProviderError);
+        assert.ok(err instanceof ProviderError, `expected ProviderError, got ${String(err)}`);
         assert.equal(err.kind, "rate_limit");
         assert.equal(err.status, 429);
-        assert.deepEqual(err.toTelemetryEvent(), { source: "provider:test", kind: "rate_limit", message: err.message, position: null });
+        assert.equal(err.problem.status, 429);
+        assert.equal(err.problem.detail, err.message);
+        assert.equal(err.problem.type, "https://problems.plurnk.dev/provider/test/rate-limit");
         return true;
     });
 });
@@ -937,10 +1430,19 @@ test("configured headers and url are sent verbatim", async () => {
     assert.equal(headers.get("x-title"), "plurnk");
 });
 
-// — transient-failure retry (#18) —
+// — transient-failure retry —
 
 const retryCfg = { model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null } as const };
 
+const stalledStreamResponse = (): Response => new Response(new ReadableStream({
+    start(controller) {
+        controller.enqueue(new TextEncoder().encode(
+            'data: {"id":"stalled","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{"content":"partial"},"finish_reason":null}]}\n\n',
+        ));
+        setTimeout(() => controller.close(), 100);
+    },
+}), { status: 200 });
+
 test("retry: a transient failure retries and a later success resolves", async () => {
     const calls = installFetchScript([
         { status: 429, retryAfter: 0 },
@@ -953,20 +1455,11 @@ test("retry: a transient failure retries and a later success resolves", async ()
     assert.equal(calls.length, 3); // 429 → 503 → 200
 });
 
-test("#559: streamed-body silence fails the exchange without replaying partial output", async () => {
+test("streamed-body silence retries and returns the retry's complete output", async () => {
     let calls = 0;
     mock.method(globalThis, "fetch", async () => {
         calls++;
-        if (calls === 1) {
-            return new Response(new ReadableStream({
-                start(controller) {
-                    controller.enqueue(new TextEncoder().encode(
-                        'data: {"id":"first","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{"content":"partial"},"finish_reason":null}]}\n\n',
-                    ));
-                    setTimeout(() => controller.close(), 100);
-                },
-            }), { status: 200 });
-        }
+        if (calls === 1) return stalledStreamResponse();
         return new Response(new ReadableStream({
             start(controller) {
                 controller.enqueue(new TextEncoder().encode(
@@ -979,7 +1472,7 @@ test("#559: streamed-body silence fails the exchange without replaying partial o
     const p = new AiSdkProvider({
         model: "m",
         url: "http://x/v1/chat/completions",
-        fetchTimeoutMs: 1000,
+        fetchTimeoutMs: 5000,
         streamIdleTimeoutMs: 10,
         temperature: 0.2,
         repeatPenalty: 1.15,
@@ -987,16 +1480,104 @@ test("#559: streamed-body silence fails the exchange without replaying partial o
         retryAttempts: 1,
         source: "provider:test",
     });
+    const result = await p.generate({ workerId: "r", messages: [] });
+    assert.equal(result.assistant.content, "recovered", "the retry's complete output, not the stalled partial");
+    assert.equal(calls, 2, "the stall retried once and the retry succeeded");
+    mock.restoreAll();
+});
+
+test("streamed-body silence does not replay when retries are disabled", async () => {
+    let calls = 0;
+    mock.method(globalThis, "fetch", async () => {
+        calls++;
+        return stalledStreamResponse();
+    });
+    const p = new AiSdkProvider({
+        model: "m",
+        url: "http://x/v1/chat/completions",
+        fetchTimeoutMs: 1000,
+        streamIdleTimeoutMs: 10,
+        temperature: 0.2,
+        repeatPenalty: 1.15,
+        reasoning: { mode: "off", budget: null },
+        retryAttempts: 0,
+        source: "provider:test",
+    });
     await assert.rejects(
         p.generate({ workerId: "r", messages: [] }),
         (error: ProviderError) => error.kind === "network_failure"
             && /chunk timeout/i.test(error.message),
     );
-    assert.equal(calls, 1);
+    assert.equal(calls, 1, "zero retries permits exactly one provider request");
+    mock.restoreAll();
+});
+
+test("streamed-body silence exhausts the configured retry budget once", async () => {
+    let calls = 0;
+    mock.method(globalThis, "fetch", async () => {
+        calls++;
+        return stalledStreamResponse();
+    });
+    const p = new AiSdkProvider({
+        model: "m",
+        url: "http://x/v1/chat/completions",
+        fetchTimeoutMs: 5000,
+        streamIdleTimeoutMs: 10,
+        temperature: 0.2,
+        repeatPenalty: 1.15,
+        reasoning: { mode: "off", budget: null },
+        retryAttempts: 1,
+        source: "provider:test",
+    });
+    await assert.rejects(
+        p.generate({ workerId: "r", messages: [] }),
+        (error: ProviderError) => error.kind === "network_failure"
+            && error.problem.attempts === 2
+            && error.problem.retryExhausted === true
+            && error.problem.retryable === false,
+    );
+    assert.equal(calls, 2, "one configured retry permits exactly two provider requests");
+    mock.restoreAll();
+});
+
+test("the total generation deadline spans stalled-stream retry scheduling", async () => {
+    let calls = 0;
+    mock.method(globalThis, "fetch", async () => {
+        calls++;
+        if (calls > 1) {
+            return new Response(new ReadableStream({
+                start(controller) {
+                    controller.enqueue(new TextEncoder().encode(
+                        'data: {"id":"second","object":"chat.completion.chunk","created":2,"model":"m","choices":[{"index":0,"delta":{"content":"late"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n',
+                    ));
+                    controller.close();
+                },
+            }), { status: 200 });
+        }
+        return stalledStreamResponse();
+    });
+    const p = new AiSdkProvider({
+        model: "m",
+        url: "http://x/v1/chat/completions",
+        fetchTimeoutMs: 50,
+        streamIdleTimeoutMs: 10,
+        temperature: 0.2,
+        repeatPenalty: 1.15,
+        reasoning: { mode: "off", budget: null },
+        retryAttempts: 3,
+        source: "provider:test",
+    });
+    const started = Date.now();
+    await assert.rejects(
+        p.generate({ workerId: "r", messages: [] }),
+        (error: ProviderError) => error.kind === "network_failure",
+    );
+    assert.ok(Date.now() - started < 500, "the configured total deadline ends retry scheduling");
+    assert.equal(calls, 1, "the total deadline expires before another request begins");
     mock.restoreAll();
 });
 
-test("#559: a zero stream-idle timeout permits a slow inter-chunk pause", async () => {
+test("a zero stream-idle timeout permits a slow inter-chunk pause", async () => {
     mock.method(globalThis, "fetch", async () => new Response(new ReadableStream({
         async start(controller) {
             controller.enqueue(new TextEncoder().encode('data: {"choices":[{"delta":{"content":"slow "}}]}\n\n'));
@@ -1021,7 +1602,7 @@ test("#559: a zero stream-idle timeout permits a slow inter-chunk pause", async
 });
 
 test("retry: exhausting the budget surfaces the classified ProviderError", async () => {
-    const { ProviderError } = await import("./telemetry.ts");
+    const { ProviderError } = await import("./errors.ts");
     const calls = installFetchScript([{ status: 429, retryAfter: 0 }]); // always rate-limited
     const p = new AiSdkProvider({ ...retryCfg, retryAttempts: 2 });
     await assert.rejects(
@@ -1056,7 +1637,7 @@ test("retry: retryAttempts 0 surfaces the first transient failure immediately",
     assert.equal(calls.length, 1); // no retry budget
 });
 
-test("retry: a caller abort during backoff rejects promptly with no further attempt (mid-flight abort, SPEC )", async () => {
+test("retry: a caller abort during backoff rejects promptly with no further attempt", async () => {
     const ac = new AbortController();
     const calls = installFetchScript([{ status: 503, retryAfter: 5 }]); // 5s backoff we never wait out
     const p = new AiSdkProvider({ ...retryCfg, retryAttempts: 3 });
@@ -1068,7 +1649,7 @@ test("retry: a caller abort during backoff rejects promptly with no further atte
     assert.equal(calls.length, 1); // never retried after cancellation
 });
 
-// — anthropic reasoning style (thinking param, #18) —
+// — Anthropic reasoning style (wire `thinking` parameter) —
 
 test("reasoningStyle 'anthropic' maps the budget to the thinking param", async () => {
     // N>0 → enabled with budget_tokens
@@ -1115,10 +1696,10 @@ test("streaming:false posts without stream and parses the single JSON response",
     mock.restoreAll();
 });
 
-// ── Data capture (#36): logprobs + verbatim rawBody, opt-in, off by default ──
+// ── Data capture ({§provider-evidence}): logprobs + verbatim rawBody, opt-in, off by default ──
 const captureBase = { model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 1000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null } as const, retryAttempts: 0 };
 
-test("#36 logprobs OFF by default: no wire request, no assistant.logprobs, no rawBody", async () => {
+test("logprobs OFF by default: no wire request, no assistant.logprobs, no rawBody", async () => {
     const calls = installFetch([{ model: "m", choices: [{ delta: { content: "hi" }, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 } }]);
     const p = new AiSdkProvider({ ...captureBase });
     const res = await p.generate({ workerId: "r", messages: [{ role: "user", content: "q" }] });
@@ -1131,7 +1712,7 @@ test("#36 logprobs OFF by default: no wire request, no assistant.logprobs, no ra
     mock.restoreAll();
 });
 
-test("#36 logprobs ON (streamed): requests logprobs+top_logprobs, surfaces raw logprob + meanLogprob", async () => {
+test("logprobs ON (streamed): requests logprobs+top_logprobs, surfaces raw logprob + meanLogprob", async () => {
     const chunk = { model: "m", usage: { prompt_tokens: 1, completion_tokens: 2, total_tokens: 3 }, choices: [{ delta: { content: "yesno" }, finish_reason: "stop", logprobs: { content: [
         { token: "yes", logprob: -0.5, sampling_logprob: -0.5, top_logprobs: [{ token: "yes", logprob: -0.5 }, { token: "no", logprob: -1.0 }] },
         { token: "no", logprob: -0.1, sampling_logprob: -0.1, top_logprobs: [{ token: "no", logprob: -0.1 }] },
@@ -1148,7 +1729,7 @@ test("#36 logprobs ON (streamed): requests logprobs+top_logprobs, surfaces raw l
     mock.restoreAll();
 });
 
-test("#36 rawBody ON (non-streamed): verbatim wire body incl. sampling_logprob preserved", async () => {
+test("rawBody ON (non-streamed): verbatim wire body incl. sampling_logprob preserved", async () => {
     const wire = { model: "m", extra_top_level: "kept", choices: [{ message: { content: "no" }, finish_reason: "stop", logprobs: { content: [{ token: "no", logprob: -0.1, sampling_logprob: -0.1, token_id: 42 }] } }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 } };
     installFetchJson(wire);
     const p = new AiSdkProvider({ ...captureBase, streaming: false, topLogprobs: 0, rawBody: true });
@@ -1160,7 +1741,7 @@ test("#36 rawBody ON (non-streamed): verbatim wire body incl. sampling_logprob p
     mock.restoreAll();
 });
 
-test("#36 caller sampling cannot forge logprobs (reserved keys): the env flag is the only control", async () => {
+test("caller sampling cannot forge logprobs (reserved keys): the env flag is the only control", async () => {
     const calls = installFetch([{ model: "m", choices: [{ delta: { content: "hi" }, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 } }]);
     const p = new AiSdkProvider({ ...captureBase }); // logprobs OFF
     await p.generate({ workerId: "r", messages: [{ role: "user", content: "q" }], sampling: { logprobs: true, top_logprobs: 5 } });
@@ -1170,9 +1751,9 @@ test("#36 caller sampling cannot forge logprobs (reserved keys): the env flag is
     mock.restoreAll();
 });
 
-// — turn coordinate headers (#404, per #391): same gate as every first-party signal —
+// — turn coordinate headers ({§lifecycle-terms}): same gate as every first-party signal —
 
-test("#404: workspaceId/loop/turn ride as Plurnk-Workspace-Id/Loop/Turn under the first-party gate", async () => {
+test("workspaceId/loop/turn ride as Plurnk-Workspace-Id/Loop/Turn under the first-party gate", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, firstPartyMetadata: true });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "r", messages: [], workspaceId: "s-9", loop: 3, turn: 41 });
@@ -1182,7 +1763,7 @@ test("#404: workspaceId/loop/turn ride as Plurnk-Workspace-Id/Loop/Turn under th
     assert.equal(headers.get("plurnk-turn"), "41");
 });
 
-test("#404: third-party providers structurally DROP the coordinate (gate off by default)", async () => {
+test("third-party providers structurally DROP the coordinate (gate off by default)", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "r", messages: [], workspaceId: "s-9", loop: 3, turn: 41 });
@@ -1192,7 +1773,7 @@ test("#404: third-party providers structurally DROP the coordinate (gate off by
     assert.equal(headers.has("plurnk-turn"), false);
 });
 
-test("#404: coordinates are 1-based — 0/absent/empty emit no header (no strikes-style zero exception)", async () => {
+test("coordinates are 1-based — 0/absent/empty emit no header", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, firstPartyMetadata: true });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "r", messages: [], workspaceId: "", loop: 0, turn: 0 });
@@ -1203,9 +1784,9 @@ test("#404: coordinates are 1-based — 0/absent/empty emit no header (no strike
     assert.equal(headers.has("plurnk-strikes"), false);
 });
 
-// -- #507: envelope surface + router-owned tuning --
+// -- {§provider-generation-envelope} --
 
-test("#507 reserves derive from the detected window; absolutes stand alone; null window + percent = no claim", () => {
+test("reserves derive from the detected window; absolutes stand alone; null window + percent = no claim", () => {
     const base = { model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 1000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null } as const, retryAttempts: 0 };
     const derived = new AiSdkProvider({ ...base, contextWindow: 49152, reasoningReserve: { percent: 0.1 }, completionReserve: { percent: 0.25 } });
     assert.equal(derived.reasoningReserve, 4915);   // jennifer/turboderp: 10% of 49152
@@ -1217,32 +1798,32 @@ test("#507 reserves derive from the detected window; absolutes stand alone; null
     assert.equal(legacy.reasoningReserve, null);    // out-of-date sibling: no claim
 });
 
-test("#507 router-owned tuning: tuningFloors:false drops the temperature/penalty floors, caller sampling still rides", async () => {
+test("router-owned tuning: tuningFloors:false drops the temperature/penalty floors, caller sampling still rides", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, frequencyPenalty: 0.4, reasoning: { mode: "off", budget: null }, retryAttempts: 0, tuningFloors: false });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "r", messages: [], sampling: { temperature: 0.9 } });
     const body = JSON.parse(calls[0].init.body as string);
     assert.equal(body.temperature, 0.9);           // caller intent passes verbatim
-    assert.equal("frequency_penalty" in body, false); // the floor is suppressed (router owns tuning, SPEC §5)
+    assert.equal("frequency_penalty" in body, false); // the floor is suppressed; the router owns tuning
 });
 
-// -- #518: prompt-cache affinity (workerId -> prompt_cache_key) --
+// -- prompt-cache affinity (workerId -> prompt_cache_key) --
 
-test("#518 promptCacheKey on: body sends prompt_cache_key = workerId (serverless replica affinity)", async () => {
+test("promptCacheKey on: body sends prompt_cache_key = workerId (serverless replica affinity)", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, promptCacheKey: true });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "worker-abc", messages: [] });
     assert.equal(JSON.parse(calls[0].init.body as string).prompt_cache_key, "worker-abc");
 });
 
-test("#518 promptCacheKey off (default): no prompt_cache_key on the wire", async () => {
+test("promptCacheKey off (default): no prompt_cache_key on the wire", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0 });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "worker-abc", messages: [] });
     assert.equal("prompt_cache_key" in JSON.parse(calls[0].init.body as string), false);
 });
 
-test("#518 prompt_cache_key is managed: caller sampling cannot forge/override the affinity key", async () => {
+test("prompt_cache_key is managed: caller sampling cannot forge/override the affinity key", async () => {
     const p = new AiSdkProvider({ model: "m", url: "http://x/v1/chat/completions", fetchTimeoutMs: 5000, temperature: 0.2, repeatPenalty: 1.15, reasoning: { mode: "off", budget: null }, retryAttempts: 0, promptCacheKey: true });
     const calls = installFetch([{ choices: [{ delta: { content: "x" } }] }]);
     await p.generate({ workerId: "worker-abc", messages: [], sampling: { prompt_cache_key: "hijack" } });