@plurnk/plurnk-providers 1.16.5 → 1.18.0

package/src/errors.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { APICallError, RetryError } from "ai";
+import { APICallError, JSONParseError, RetryError, TypeValidationError } from "ai";
 import { ProviderError, ProviderTimeoutError, classifyProviderError, toProviderError } from "./errors.ts";
 import type { ProviderAttempt } from "./types.ts";
 import { providerSource } from "./notices.ts";
@@ -15,6 +15,22 @@ const apiError = (statusCode: number, responseBody = "body") => new APICallError
 
 const SOURCE_PATTERN = /^[a-z]+(:[a-z][a-z0-9-]*)?$/;
 
+test("HTTP request rejection preserves its cause without becoming a response-contract strike", () => {
+    for (const status of [400, 404, 405, 422]) {
+        const message = "The requested model is not available on this endpoint.";
+        const cause = apiError(status, JSON.stringify({ error: { message } }));
+        Object.defineProperty(cause, "message", { value: message });
+        const failure = toProviderError(cause, "provider:example");
+        assert.equal(failure.kind, "request_rejected");
+        assert.equal(failure.status, status);
+        assert.equal(failure.message, message);
+        assert.equal(failure.problem.detail, message);
+        assert.equal(failure.problem.retryable, false);
+        assert.equal(failure.cause, cause);
+    }
+    assert.equal(classifyProviderError(apiError(200)).kind, "invalid_response", "a malformed successful response still violates the response contract");
+});
+
 test("providerSource produces a schema-valid colon-namespaced source", () => {
     assert.equal(providerSource("openai"), "provider:openai");
     assert.match(providerSource("openrouter"), SOURCE_PATTERN);
@@ -34,8 +50,8 @@ test("classifyProviderError maps HTTP status to kind", () => {
     assert.equal(k(500), "network_failure");
     assert.equal(k(503), "network_failure");
     assert.equal(k(413), "capacity_exceeded");
-    assert.equal(k(400), "invalid_response");
-    assert.equal(k(404), "invalid_response");
+    assert.equal(k(400), "request_rejected");
+    assert.equal(k(404), "request_rejected");
 });
 
 test("capacity normalization prefers structured provider codes and keeps generic 400s distinct", () => {
@@ -53,7 +69,7 @@ test("capacity normalization prefers structured provider codes and keeps generic
     assert.equal(normalized.problem.providerStatus, 400);
     assert.equal(classifyProviderError(apiError(400, JSON.stringify({
         error: { type: "invalid_request_error", code: "bad_temperature", message: "bad temperature" },
-    }))).kind, "invalid_response");
+    }))).kind, "request_rejected");
 });
 
 test("provider retry directives survive HTTP failure normalization", () => {
@@ -69,11 +85,11 @@ test("provider retry directives survive HTTP failure normalization", () => {
     assert.equal(error.problem.retryable, false);
 });
 
-test("classifyProviderError: a 422 flagged grammar_invalid is distinct; other 422s are invalid responses", () => {
+test("classifyProviderError: a 422 flagged grammar_invalid is distinct from other request rejections", () => {
     const rejected = apiError(422, JSON.stringify({ error: { type: "grammar_invalid", message: "non-conforming emission rejected: ..." } }));
     assert.equal(classifyProviderError(rejected).kind, "grammar_invalid");
-    assert.equal(classifyProviderError(apiError(422, JSON.stringify({ error: { type: "invalid_request_error" } }))).kind, "invalid_response");
-    assert.equal(classifyProviderError(apiError(422, "<html>Bad</html>")).kind, "invalid_response");
+    assert.equal(classifyProviderError(apiError(422, JSON.stringify({ error: { type: "invalid_request_error" } }))).kind, "request_rejected");
+    assert.equal(classifyProviderError(apiError(422, "<html>Bad</html>")).kind, "request_rejected");
 });
 
 test("classifyProviderError treats non-HTTP errors as network_failure", () => {
@@ -225,3 +241,38 @@ test("retry exhaustion retains the exact inner deadline phase", () => {
     assert.equal(error.problem.timeoutPhase, "attempt");
     assert.equal(error.problem.timeoutMs, 10);
 });
+
+// {§provider-failure-cause} — the SDK wraps every processing failure of a 2xx body in one message;
+// the durable Problem keeps a bounded classification of what actually happened underneath.
+const processingFailure = (cause: Error) => new APICallError({
+    message: "Failed to process successful response",
+    url: "https://example.test/v1/chat/completions",
+    requestBodyValues: {},
+    statusCode: 200,
+    responseHeaders: { authorization: "Bearer never-copied", "x-request-id": "req_1" },
+    cause,
+});
+
+test("#593: a terminated body, invalid JSON, a schema-invalid body, and an internal fault are told apart in durable evidence", () => {
+    const terminated = toProviderError(processingFailure(new TypeError("terminated")), "provider:test", 512);
+    assert.equal(terminated.problem.providerKind, "network_failure");
+    assert.deepEqual(terminated.problem.cause, { causeKind: "transport_terminated", causeName: "TypeError", causeMessage: "terminated" });
+
+    const parse = toProviderError(processingFailure(new JSONParseError({ text: "<html>502 Bad Gateway</html>".repeat(40), cause: new SyntaxError("Unexpected token <") })), "provider:test", 512);
+    assert.equal(parse.problem.providerKind, "invalid_response");
+    assert.deepEqual(parse.problem.cause, { causeKind: "invalid_json", causeName: "AI_JSONParseError", causeMessage: "JSON parsing failed (1120 characters)" });
+    assert.doesNotMatch(JSON.stringify(parse.problem), /Bad Gateway/, "the payload never enters the Problem");
+
+    const schema = toProviderError(processingFailure(new TypeValidationError({ value: { choices: "not-an-array", secret: "sk-live" }, cause: new Error("Expected array, received string at choices\nmore lines") })), "provider:test", 512);
+    assert.equal(schema.problem.providerKind, "invalid_response");
+    assert.deepEqual(schema.problem.cause, { causeKind: "schema_invalid", causeName: "AI_TypeValidationError", causeMessage: "Type validation failed: Expected array, received string at choices" });
+    assert.doesNotMatch(JSON.stringify(schema.problem), /sk-live|not-an-array/, "the value never enters the Problem");
+
+    const internal = toProviderError(processingFailure(new RangeError("Invalid array length\n    at Array.push (stack frame)")), "provider:test", 512);
+    assert.deepEqual(internal.problem.cause, { causeKind: "internal", causeName: "RangeError", causeMessage: "Invalid array length" });
+    assert.doesNotMatch(JSON.stringify(internal.problem), /stack frame|authorization|Bearer|req_1/, "no stack, no headers");
+
+    const bounded = toProviderError(processingFailure(new Error("x".repeat(100))), "provider:test", 8);
+    assert.equal((bounded.problem.cause as { causeMessage: string }).causeMessage, "xxxxxxxx...", "the cause message honours the configured detail limit");
+    assert.equal(toProviderError(apiError(502), "provider:test", 512).problem.cause, undefined, "an error without a cause reports none");
+});

package/src/errors.ts

@@ -1,4 +1,4 @@
-import { APICallError, RetryError } from "ai";
+import { APICallError, InvalidResponseDataError, JSONParseError, RetryError, TypeValidationError } from "ai";
 import { ProviderError } from "./providerError.ts";
 import type { ProviderErrorKind } from "./providerError.ts";
 import type { ProviderRequestCapacity } from "./types.ts";
@@ -81,6 +81,34 @@ const preview = (value: unknown, limit: number | undefined): string => {
         : text;
 };
 
+export type ProviderFailureCauseKind = "transport_terminated" | "invalid_json" | "schema_invalid" | "invalid_response_data" | "internal";
+
+export interface ProviderFailureCause {
+    readonly causeKind: ProviderFailureCauseKind;
+    readonly causeName: string;
+    readonly causeMessage: string;
+}
+
+const firstLine = (text: string): string => text.split("\n")[0]?.trim() ?? "";
+
+// {§provider-failure-cause} — what the SDK wrapped. "Failed to process successful response" is
+// the SDK's one message for a body that terminated, a body that was not JSON, a body that failed
+// the response schema, and its own internal faults; the durable Problem keeps a bounded
+// classification of the cause so forensics can tell them apart. The SDK's parse and validation
+// messages embed the payload, so those two report shape, never text.
+const failureCause = (err: APICallError, detailLimit: number | undefined): ProviderFailureCause | null => {
+    const cause = err.cause;
+    if (!(cause instanceof Error)) return null;
+    if (peerTerminated(cause)) return { causeKind: "transport_terminated", causeName: cause.name, causeMessage: preview(firstLine(cause.message), detailLimit) };
+    if (JSONParseError.isInstance(cause)) return { causeKind: "invalid_json", causeName: cause.name, causeMessage: `JSON parsing failed (${cause.text.length} characters)` };
+    if (TypeValidationError.isInstance(cause)) {
+        const inner = cause.cause instanceof Error ? firstLine(cause.cause.message) : "";
+        return { causeKind: "schema_invalid", causeName: cause.name, causeMessage: inner === "" ? "Type validation failed" : `Type validation failed: ${preview(inner, detailLimit)}` };
+    }
+    if (InvalidResponseDataError.isInstance(cause)) return { causeKind: "invalid_response_data", causeName: cause.name, causeMessage: preview(firstLine(cause.message), detailLimit) };
+    return { causeKind: "internal", causeName: cause.name, causeMessage: preview(firstLine(cause.message), detailLimit) };
+};
+
 export const classifyProviderError = (
     err: unknown,
     detailLimit?: number,
@@ -94,6 +122,31 @@ export const classifyProviderError = (
         };
     }
     if (APICallError.isInstance(err)) {
+        const classified = classifyApiCallError(err, detailLimit);
+        const cause = failureCause(err, detailLimit);
+        return cause === null ? classified : { ...classified, extensions: { ...(classified.extensions ?? {}), cause } };
+    }
+    const wire = err as { message?: unknown; type?: unknown };
+    if (wire?.type === "grammar_invalid") {
+        return {
+            kind: "grammar_invalid",
+            message: typeof wire.message === "string"
+                ? preview(wire.message, detailLimit)
+                : "The provider rejected the response grammar.",
+        };
+    }
+    const error = err as { message?: string };
+    return {
+        kind: "network_failure",
+        message: preview(
+            (error?.message ?? String(err)) || "The provider request failed.",
+            detailLimit,
+        ),
+    };
+};
+
+const classifyApiCallError = (err: APICallError, detailLimit: number | undefined): ClassifiedProviderError => {
+    {
         const timeout = providerTimeoutOf(err);
         if (timeout !== null) {
             return {
@@ -146,25 +199,9 @@ export const classifyProviderError = (
         if (status === 422 && wire.type === "grammar_invalid") {
             return { kind: "grammar_invalid", message };
         }
+        if (status >= 400 && status < 500) return { kind: "request_rejected", message };
         return { kind: "invalid_response", message };
     }
-    const wire = err as { message?: unknown; type?: unknown };
-    if (wire?.type === "grammar_invalid") {
-        return {
-            kind: "grammar_invalid",
-            message: typeof wire.message === "string"
-                ? preview(wire.message, detailLimit)
-                : "The provider rejected the response grammar.",
-        };
-    }
-    const error = err as { message?: string };
-    return {
-        kind: "network_failure",
-        message: preview(
-            (error?.message ?? String(err)) || "The provider request failed.",
-            detailLimit,
-        ),
-    };
 };
 
 export const toProviderError = (

package/src/index.ts

@@ -45,8 +45,8 @@ export {
     loadActiveProvider,
     resetDiscoveryCache,
 } from "./ProviderRegistry.ts";
-export { createEmbeddingModel, providerReadiness } from "./sdkModels.ts";
-export type { EmbeddingModelResolution } from "./sdkModels.ts";
+export { providerReadiness } from "./sdkModels.ts";
+export { catalogReasoningPolicies } from "./catalogProvider.ts";
 
 // Scope-agnostic plugin discovery ({§plugin-family-kind}).
 export { discover } from "./discover.ts";

package/src/providerError.ts

@@ -7,6 +7,7 @@ export type ProviderErrorKind =
     | "network_failure"
     | "deadline_exceeded"
     | "model_refused"
+    | "request_rejected"
     | "invalid_response"
     | "unauthorized"
     | "quota_exceeded"
@@ -16,6 +17,7 @@ export type ProviderErrorKind =
 
 const defaultStatus = (kind: ProviderErrorKind): number => {
     switch (kind) {
+        case "request_rejected": return 400;
         case "unauthorized": return 401;
         case "quota_exceeded": return 402;
         case "capacity_exceeded": return 413;
@@ -36,6 +38,7 @@ const retryable = (kind: ProviderErrorKind): boolean => {
             return true;
         case "deadline_exceeded":
         case "invalid_response":
+        case "request_rejected":
         case "grammar_invalid":
         case "capacity_exceeded":
         case "resource_interrupted":
@@ -60,6 +63,7 @@ const buildProblem = (
         deadline_exceeded: "deadline-exceeded",
         model_refused: "model-refused",
         invalid_response: "invalid-response",
+        request_rejected: "request-rejected",
         unauthorized: "unauthorized",
         quota_exceeded: "quota-exceeded",
         grammar_invalid: "grammar-invalid",

package/src/sdkModels.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { configuredProviderInfo, createEmbeddingModel, createSdkModel, providerReadiness } from "./sdkModels.ts";
+import { configuredProviderInfo, createSdkModel, providerReadiness } from "./sdkModels.ts";
 
 test("{§provider-fact-authority} one env declaration holds one credential name", () => {
     assert.deepEqual(configuredProviderInfo("acme-cloud", {
@@ -301,44 +301,3 @@ test("createSdkModel fails clearly for a declared but unsupported SDK package",
         /Models.dev declares unsupported AI SDK package @acme\/ai-sdk/,
     );
 });
-
-test("{§provider-embedding-resolution} compatible catalog and declared routes share the standard embedding adapter", () => {
-    const cloudflare = createEmbeddingModel("cloudflare-workers-ai", "@cf/qwen/qwen3-embedding-0.6b", {
-        CLOUDFLARE_ACCOUNT_ID: "account",
-        CLOUDFLARE_API_KEY: "key",
-    });
-    assert.equal(cloudflare?.providerId, "cloudflare-workers-ai");
-    assert.equal(cloudflare?.embeddingModel.provider, "cloudflare-workers-ai.embedding");
-    assert.equal(cloudflare?.embeddingModel.modelId, "@cf/qwen/qwen3-embedding-0.6b");
-
-    const fireworks = createEmbeddingModel("fireworks-ai", "fireworks/qwen3-embedding-8b", {
-        FIREWORKS_API_KEY: "key",
-    });
-    assert.equal(fireworks?.providerId, "fireworks-ai");
-    assert.equal(fireworks?.embeddingModel.provider, "fireworks-ai.embedding");
-
-    const local = createEmbeddingModel("local-embed", "Qwen/Qwen3-Embedding-0.6B", {
-        PLURNK_PROVIDERS_PROVIDER_LOCAL_EMBED_NPM: "@ai-sdk/openai-compatible",
-        PLURNK_PROVIDERS_PROVIDER_LOCAL_EMBED_BASE_URL: "http://127.0.0.1:8080/v1",
-    });
-    assert.equal(local?.providerId, "local-embed");
-    assert.equal(local?.embeddingModel.provider, "local-embed.embedding");
-});
-
-test("{§provider-embedding-resolution} OpenRouter uses its official embedding model", () => {
-    const resolved = createEmbeddingModel("openrouter", "openai/text-embedding-3-small", {
-        OPENROUTER_API_KEY: "key",
-        OPENROUTER_HTTP_REFERER: "https://github.com/plurnk/plurnk-service",
-        OPENROUTER_APP_TITLE: "Plurnk",
-    });
-    assert.equal(resolved?.providerId, "openrouter");
-    assert.equal(resolved?.embeddingModel.provider, "openrouter");
-    assert.equal(resolved?.embeddingModel.modelId, "openai/text-embedding-3-small");
-});
-
-test("{§provider-embedding-resolution} a generation-only SDK fails before transport", () => {
-    assert.throws(
-        () => createEmbeddingModel("cerebras", "text-embedding", { CEREBRAS_API_KEY: "key" }),
-        /@ai-sdk\/cerebras does not expose an embedding model/,
-    );
-});

package/src/sdkModels.ts

@@ -6,15 +6,12 @@ import { createGoogle } from "@ai-sdk/google";
 import { createGroq } from "@ai-sdk/groq";
 import { createMistral } from "@ai-sdk/mistral";
 import { createOpenAI } from "@ai-sdk/openai";
-import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { createTogetherAI } from "@ai-sdk/togetherai";
 import { createXai } from "@ai-sdk/xai";
-import type { EmbeddingModelV4, EmbeddingModelV4Result } from "@ai-sdk/provider";
 import { createOpenRouter, type OpenRouterChatSettings } from "@openrouter/ai-sdk-provider";
 import {
     resolveModel,
     isProviderCredentialName,
-    lookup,
     lookupProvider,
     providerCatalogSnapshot,
     type ProviderInfo,
@@ -23,13 +20,10 @@ import {
     Validator,
     type ModelReadiness,
     type ModelReadinessCause,
-    type ProviderRequestAccounting,
-    type ProviderUsage,
     type ReasoningPolicy,
 } from "@plurnk/plurnk-contracts";
 import type { LanguageModel } from "ai";
-import { providerCostNormalizer, validateProviderRequestAccounting } from "./accounting.ts";
-import { estimateProviderCost, resolveProviderCost } from "./cost.ts";
+import { providerCostNormalizer } from "./accounting.ts";
 import type { AiSdkProviderOptions, CacheAffinity } from "./AiSdkProvider.ts";
 import type { ProviderCostNormalizer } from "./types.ts";
 
@@ -47,17 +41,6 @@ export type SdkModel = {
     readonly catalog: ProviderInfo | null;
 };
 
-export type EmbeddingModelResolution = {
-    readonly embeddingModel: EmbeddingModelV4;
-    readonly providerId: string;
-    readonly modelId: string;
-    readonly normalizeAccounting: (evidence: {
-        readonly outcome: "response" | "error";
-        readonly status?: number;
-        readonly result?: EmbeddingModelV4Result;
-    }) => ProviderRequestAccounting;
-};
-
 const cacheControl = { type: "ephemeral" as const };
 // The release generator admits only packages implemented by this package.
 // Derive runtime readiness from that same pinned provider projection instead
@@ -485,108 +468,3 @@ export const createSdkModel = (
             throw new Error(`${provider} provider: Models.dev declares unsupported AI SDK package ${catalog.npm}`);
     }
 };
-
-// {§provider-embedding-resolution} Provider construction owns transport and
-// authentication only. Model-space facts stay in the embedding profile.
-export const createEmbeddingModel = (
-    provider: string,
-    model: string,
-    env: NodeJS.ProcessEnv,
-    baseUrlOverride?: string,
-): EmbeddingModelResolution | null => {
-    const resolved = resolveSdkProvider(provider, env, baseUrlOverride);
-    if (resolved === null) return null;
-    const { catalog, url } = resolved;
-    const directCost = providerCostNormalizer(catalog.npm);
-    const modelCost = lookup(provider, model)?.cost ?? lookup(catalog.id, model)?.cost;
-    const rates = modelCost === undefined
-        ? null
-        : {
-            input: modelCost.inputPer1M,
-            output: modelCost.outputPer1M,
-            ...(modelCost.reasoningPer1M === undefined ? {} : { reasoning: modelCost.reasoningPer1M }),
-            ...(modelCost.cacheReadPer1M === undefined ? {} : { cacheRead: modelCost.cacheReadPer1M }),
-            ...(modelCost.cacheWritePer1M === undefined ? {} : { cacheWrite: modelCost.cacheWritePer1M }),
-        };
-    const normalizeAccounting: EmbeddingModelResolution["normalizeAccounting"] = (evidence) => {
-        const tokens = evidence.result?.usage?.tokens;
-        const usage: ProviderUsage | undefined = Number.isSafeInteger(tokens) && tokens! >= 0
-            ? { inputTokens: tokens!, outputTokens: 0, totalTokens: tokens! }
-            : undefined;
-        const body = evidence.result?.response?.body;
-        const rawUsage = typeof body === "object" && body !== null && !Array.isArray(body)
-            ? (body as Record<string, unknown>).usage
-            : undefined;
-        const direct = directCost?.({
-            providerMetadata: evidence.result?.providerMetadata,
-            usage: rawUsage,
-            response: { headers: evidence.result?.response?.headers },
-        });
-        const cost = resolveProviderCost(
-            direct,
-            estimateProviderCost(
-                usage,
-                rates,
-                `Models.dev ${catalog.id}/${model} rates`,
-            ),
-        );
-        return validateProviderRequestAccounting({
-            provider: catalog.id,
-            model,
-            outcome: evidence.outcome,
-            ...(evidence.status === undefined ? {} : { status: evidence.status }),
-            ...(usage === undefined ? {} : { usage }),
-            cost,
-        });
-    };
-    const result = (embeddingModel: EmbeddingModelV4): EmbeddingModelResolution => ({
-        embeddingModel,
-        providerId: catalog.id,
-        modelId: model,
-        normalizeAccounting,
-    });
-
-    switch (catalog.npm) {
-        case "@ai-sdk/openai":
-            return result(createOpenAI({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embedding(model));
-        case "@ai-sdk/google":
-            return result(createGoogle({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embedding(model));
-        case "@ai-sdk/mistral":
-            return result(createMistral({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embedding(model));
-        case "@ai-sdk/deepinfra":
-            return result(createDeepInfra({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embeddingModel(model));
-        case "@ai-sdk/togetherai":
-            return result(createTogetherAI({ apiKey: requireApiKey(provider, env, catalog), baseURL: url }).embeddingModel(model));
-        case "@ai-sdk/amazon-bedrock":
-            return result(createAmazonBedrock({
-                region: env.AWS_REGION ?? env.AWS_DEFAULT_REGION,
-                accessKeyId: env.AWS_ACCESS_KEY_ID,
-                secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
-                sessionToken: env.AWS_SESSION_TOKEN,
-                apiKey: env.AWS_BEARER_TOKEN_BEDROCK,
-                baseURL: url,
-            }).embedding(model));
-        case "@openrouter/ai-sdk-provider":
-            return result(createOpenRouter({
-                apiKey: requireApiKey(provider, env, catalog),
-                baseURL: url,
-                headers: openRouterHeaders(provider, env, catalog),
-            }).textEmbeddingModel(model));
-        case "@ai-sdk/openai-compatible": {
-            if (url === undefined) {
-                throw new Error(`${provider} provider: Models.dev supplies no API URL and no base URL was configured`);
-            }
-            const keyNames = configuredKeyNames(provider, env, catalog);
-            const key = keyNames.length === 0 ? undefined : requireApiKey(provider, env, catalog);
-            return result(createOpenAICompatible({
-                name: provider,
-                baseURL: url,
-                ...(key === undefined ? {} : { apiKey: key }),
-            }).embeddingModel(model));
-        }
-        default:
-            throw new Error(
-                `${provider} provider: ${catalog.npm} does not expose an embedding model through Plurnk's AI SDK adapter`,
-            );
-    }
-};

package/src/types.ts

@@ -187,10 +187,10 @@ export interface ProviderAssistant<TFinish extends ProviderAttemptFinishReason =
     readonly meanLogprob?: number;
 }
 
+// {§provider-grammar-transport} — transport evidence for an operator's grammar: the exact
+// pre-projection response, where the projected content starts within it, and whether the
+// grammar reached the wire. Evidence only; nothing grades it.
 export interface GrammarEvidence {
-    // Exact pre-projection response represented by the provider. A generated
-    // rail's response root composes any template prefix before @plurnk/gbnf
-    // grades it. Offsets are Unicode code points, matching validator verdicts.
     readonly input: string;
     readonly contentStart: number;
     readonly transported: boolean;
@@ -203,7 +203,7 @@ export interface ProviderResponse<TFinish extends ProviderAttemptFinishReason =
     // failover that preceded this response. {§provider-request-accounting}
     readonly accounting: readonly ProviderRequestAccounting[];
     readonly capacity: ProviderRequestCapacity;
-    // {§gbnf-response-observation} — evidence only; the consumer owns the verdict.
+    // {§provider-grammar-transport} — transport evidence; present only when a grammar was configured.
     readonly grammarEvidence?: GrammarEvidence;
     // Per-turn provider→client metadata bag: the backend's non-standard top-level
     // response fields passed through verbatim. Monetary values carry their own
@@ -250,12 +250,10 @@ export interface Provider {
     // Optional package-authored folksonomy evaluated by the consumer immediately
     // before a provider emission attempt ({§plugin-attribution}).
     attributions?(context: PluginAttributionContext): PluginAttribution;
-    // `grammar` is an optional GBNF string (canonically @plurnk/plurnk-contracts'
-    // plurnk.gemma.gbnf or plurnk.qwen.gbnf, possibly root-substituted by the consumer). Backends that
-    // support grammar-constrained sampling attach it verbatim; all others
-    // ignore it. The provider never chooses or modifies the grammar — whether
-    // to constrain and which root variant to send is consumer policy
-    // ({§gbnf-response-observation}).
+    // `grammar` is an optional GBNF string, the operator's own file read by the consumer.
+    // Backends that support grammar-constrained sampling attach it verbatim; all others
+    // ignore it. The provider never chooses or modifies the grammar
+    // ({§provider-grammar-transport}).
     //
     // `maxOutputTokens` may tighten the provider's configured total output
     // budget for this call. It includes visible output and hidden reasoning;

package/src/usage.ts

@@ -179,16 +179,14 @@ export const normalizeUsage = (raw: RawUsage | null | undefined): ProviderUsage
             ? inputTokens - cacheReadTokens - cacheWriteTokens
             : undefined);
 
+    const inputTokenDetails = nonEmptyDetails({ noCacheTokens, cacheReadTokens, cacheWriteTokens });
+    const outputTokenDetails = nonEmptyDetails({ textTokens, reasoningTokens: normalizedReasoning });
     const usage: ProviderUsage = {
         ...(inputTokens === undefined ? {} : { inputTokens }),
         ...(outputTokens === undefined ? {} : { outputTokens }),
         ...(totalTokens === undefined ? {} : { totalTokens }),
-        ...(nonEmptyDetails({ noCacheTokens, cacheReadTokens, cacheWriteTokens }) === undefined
-            ? {}
-            : { inputTokenDetails: nonEmptyDetails({ noCacheTokens, cacheReadTokens, cacheWriteTokens })! }),
-        ...(nonEmptyDetails({ textTokens, reasoningTokens: normalizedReasoning }) === undefined
-            ? {}
-            : { outputTokenDetails: nonEmptyDetails({ textTokens, reasoningTokens: normalizedReasoning })! }),
+        ...(inputTokenDetails === undefined ? {} : { inputTokenDetails }),
+        ...(outputTokenDetails === undefined ? {} : { outputTokenDetails }),
     };
     if (Object.keys(usage).length === 0) return undefined;
     return validateProviderUsage(usage);
@@ -244,15 +242,25 @@ export const calculateCostUsdDecimal = (
     if (cacheWriteRate !== rates.input && cacheWriteTokens === undefined) return null;
     if (reasoningRate !== rates.output && reasoningTokens === undefined) return null;
 
-    const parts = [rates.input, rates.output, reasoningRate, cacheReadRate, cacheWriteRate].map(decimalParts);
-    const rateScale = Math.max(...parts.map(({ scale }) => scale));
-    const [input, output, reasoning, cacheRead, cacheWrite] = parts.map(({ coefficient, scale }) =>
-        coefficient * 10n ** BigInt(rateScale - scale));
-    const coefficient = BigInt(usage.inputTokens) * input!
-        + BigInt(usage.outputTokens) * output!
-        + BigInt(reasoningTokens ?? 0) * (reasoning! - output!)
-        + BigInt(cacheReadTokens ?? 0) * (cacheRead! - input!)
-        + BigInt(cacheWriteTokens ?? 0) * (cacheWrite! - input!);
+    const parts = {
+        input: decimalParts(rates.input),
+        output: decimalParts(rates.output),
+        reasoning: decimalParts(reasoningRate),
+        cacheRead: decimalParts(cacheReadRate),
+        cacheWrite: decimalParts(cacheWriteRate),
+    };
+    const rateScale = Math.max(...Object.values(parts).map(({ scale }) => scale));
+    const scaled = ({ coefficient, scale }: { coefficient: bigint; scale: number }): bigint => coefficient * 10n ** BigInt(rateScale - scale);
+    const input = scaled(parts.input);
+    const output = scaled(parts.output);
+    const reasoning = scaled(parts.reasoning);
+    const cacheRead = scaled(parts.cacheRead);
+    const cacheWrite = scaled(parts.cacheWrite);
+    const coefficient = BigInt(usage.inputTokens) * input
+        + BigInt(usage.outputTokens) * output
+        + BigInt(reasoningTokens ?? 0) * (reasoning - output)
+        + BigInt(cacheReadTokens ?? 0) * (cacheRead - input)
+        + BigInt(cacheWriteTokens ?? 0) * (cacheWrite - input);
     if (coefficient < 0n) throw new TypeError("provider token-rate details produced a negative estimate");
     return canonicalDecimal(coefficient, rateScale + 6);
 };