@plurnk/plurnk-providers 1.3.12 → 1.5.0

package/src/boundaries.test.ts

@@ -19,17 +19,23 @@ test("provider source does not import the service or database", () => {
 test("provider source does not import the PLURNK parser", () => {
     for (const file of sourceFiles()) {
         const source = readFileSync(join(root, file), "utf8");
-        assert.ok(!/from\s+["']@plurnk\/plurnk-grammar/.test(source), `${file} imports the parser`);
+        assert.ok(
+            !/from\s+["']@plurnk\/plurnk-contracts\/grammar["']/.test(source),
+            `${file} imports the parser rather than the runtime-neutral contracts entrypoint`,
+        );
     }
 });
 
-test("#608: the OpenAI-compatible entrypoint excludes Node-owned provider machinery", () => {
+test("the OpenAI-compatible entrypoint excludes Node-owned provider machinery", () => {
     const allowed = new Set([
         "AiSdkProvider.ts",
         "aiSdkTransport.ts",
+        "cost.ts",
         "env.ts",
+        "errors.ts",
+        "notices.ts",
         "openai.ts",
-        "telemetry.ts",
+        "promptTokens.ts",
         "types.ts",
         "usage.ts",
         "warnings.ts",

package/src/catalogProvider.test.ts

@@ -1,6 +1,7 @@
 import test, { mock } from "node:test";
 import { strict as assert } from "node:assert";
 import { catalogProviderFromEnv } from "./catalogProvider.ts";
+import { providerCostFor } from "./cost.ts";
 import { resetEmittedWarnings } from "./warnings.ts";
 
 const env = {
@@ -15,6 +16,7 @@ const env = {
     PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
     PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
     PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512",
     PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
 };
 
@@ -39,6 +41,22 @@ test("catalog provider resolves model physics and Models.dev USD rates", () => {
     }) ?? 0) > 0);
 });
 
+test("an operator context window caps catalog physics and percentage reserves derive from the cap", () => {
+    const provider = catalogProviderFromEnv("openai", {
+        ...env,
+        PLURNK_PROVIDERS_CONTEXT_WINDOW: "128000",
+    }, "gpt-4.1-mini");
+    assert.equal(provider?.contextWindow, 128_000);
+    assert.equal(provider?.reasoningReserve, 16_000);
+    assert.equal(provider?.completionReserve, 32_000);
+
+    const oversized = catalogProviderFromEnv("openai", {
+        ...env,
+        PLURNK_PROVIDERS_CONTEXT_WINDOW: "2000000",
+    }, "gpt-4.1-mini");
+    assert.equal(oversized?.contextWindow, 1_047_576, "an operator ceiling cannot enlarge model physics");
+});
+
 test("official AI SDK provider owns the native request while PLURNK owns call settings", async () => {
     const calls: Array<{ url: string; body: Record<string, unknown> }> = [];
     mock.method(globalThis, "fetch", async (input: string | URL | Request, init?: RequestInit) => {
@@ -102,22 +120,32 @@ test("cataloged unknown model fails unless its context is explicit", () => {
     assert.equal(provider?.contextWindow, 8192);
 });
 
-test("explicit operator rates price out-of-snapshot models and override catalog rates", () => {
-    const priced = {
+test("Models.dev is the only fallback rate table", () => {
+    const usage = {
+        prompt: 1_000,
+        cached: 400,
+        completion: 100,
+        reasoning: 50,
+        total: 1_150,
+    };
+    const cataloged = catalogProviderFromEnv("deepseek", {
+        ...env,
+        DEEPSEEK_API_KEY: "test-key",
+    }, "deepseek-v4-flash");
+    assert.notEqual(cataloged, null);
+    assert.deepEqual(providerCostFor(cataloged!, usage), {
+        kind: "estimated",
+        usd: "0.00012712",
+        source: "Models.dev catalog rates",
+    });
+
+    const uncataloged = catalogProviderFromEnv("xai", {
         ...env,
         XAI_API_KEY: "test-key",
         PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
-        PLURNK_PROVIDERS_INPUT_USD_PER_MILLION: "2",
-        PLURNK_PROVIDERS_CACHE_READ_USD_PER_MILLION: "0.5",
-        PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION: "8",
-    };
-    const usage = {
-        prompt: 1_000_000,
-        cached: 250_000,
-        completion: 500_000,
-        reasoning: 500_000,
-        total: 2_000_000,
-    };
-    assert.equal(catalogProviderFromEnv("xai", priced, "not-in-the-catalog")?.calculateCost(usage), 9.625);
-    assert.equal(catalogProviderFromEnv("openai", priced, "gpt-4.1-mini")?.calculateCost(usage), 9.625);
+    }, "not-in-the-catalog");
+    assert.deepEqual(providerCostFor(uncataloged!, usage), {
+        kind: "unknown",
+        reason: "the response reported no cost and Models.dev has no rate for this model",
+    });
 });

package/src/catalogProvider.ts

@@ -1,23 +1,26 @@
 import { lookupProvider, resolveModel, type ModelInfo } from "@plurnk/plurnk-models";
 import {
     contextWindowFromEnv,
+    effectiveContextWindow,
     dataCaptureFromEnv,
     envelopeFromEnv,
     parseRequiredFloat,
     parseRequiredInt,
     promptCacheKeyFromEnv,
     reasoningFromEnv,
+    reasoningResponseStyleFromEnv,
     resolveReserve,
-    tokenRatesFromEnv,
     type ReserveSpec,
 } from "./env.ts";
 import AiSdkProvider, { type ReasoningStyle } from "./AiSdkProvider.ts";
 import { configuredProviderInfo, createSdkModel } from "./sdkModels.ts";
-import { providerSource } from "./telemetry.ts";
-import type { Provider, ProviderUsage } from "./types.ts";
-import { calculateCostUsd } from "./usage.ts";
+import { providerSource } from "./notices.ts";
+import type { AuthoritativeChargeNormalizer, Provider, ProviderUsage } from "./types.ts";
+import { calculateCostUsd, calculateCostUsdDecimal } from "./usage.ts";
 import { emitWarningOnce } from "./warnings.ts";
 import type { LanguageModel } from "ai";
+import type { PluginAttribution, PluginAttributionContext } from "@plurnk/plurnk-meta";
+import type { ProviderCost } from "@plurnk/plurnk-contracts";
 
 const reasoningStyleFromEnv = (
     env: NodeJS.ProcessEnv,
@@ -28,7 +31,7 @@ const reasoningStyleFromEnv = (
     if (value === undefined || value.length === 0) return undefined;
     const styles: readonly ReasoningStyle[] = [
         "none", "think", "include_reasoning", "effort",
-        "effort_explicit", "template", "anthropic",
+        "effort_explicit", "thinking_effort", "template", "anthropic",
     ];
     if (!styles.includes(value as ReasoningStyle)) {
         throw new Error(`${name} provider: PLURNK_PROVIDERS_PROVIDER_${prefix}_REASONING_STYLE has invalid value "${value}"`);
@@ -41,23 +44,27 @@ export const providerFromSdkModel = ({
     env,
     model,
     languageModel,
+    normalizeCharge,
     url,
     headers,
     contextWindow,
     info,
+    attributions,
 }: {
     name: string;
     env: NodeJS.ProcessEnv;
     model: string;
     languageModel?: LanguageModel;
+    normalizeCharge?: AuthoritativeChargeNormalizer;
     url?: string;
     headers?: Readonly<Record<string, string>>;
     contextWindow: number;
     info?: ModelInfo;
+    attributions?: (context: PluginAttributionContext) => PluginAttribution;
 }): Provider => {
     emitWarningOnce(
-        `${name} provider: countTokens is a chars/2 upper bound — exact counts come from the mimetypes tokenizer seam or tokenize()`,
-        "PLURNK_TOKENIZER_HEURISTIC",
+        `${name} provider: physical prompt counting is a chars/2 estimate; over-policy recovery fails closed without exact or bounded request evidence`,
+        "PLURNK_PROMPT_COUNT_ESTIMATE",
     );
 
     const reasoning = reasoningFromEnv(env, name);
@@ -76,36 +83,49 @@ export const providerFromSdkModel = ({
                 ? configuredReasoning
                 : { tokens: Math.round(completionTokens / 2) };
 
-    const configuredRates = tokenRatesFromEnv(env, name);
     const catalogCost = info?.cost;
-    const rates = configuredRates ?? (catalogCost === undefined ? null : {
+    const rates = catalogCost === undefined ? null : {
         input: catalogCost.inputPer1M,
         output: catalogCost.outputPer1M,
         cached: catalogCost.cacheReadPer1M ?? catalogCost.inputPer1M,
-    });
+    };
     const calculateCost = rates === null
         ? undefined
         : (usage: ProviderUsage): number => calculateCostUsd(usage, rates);
+    const calculateCharge: (usage: ProviderUsage) => Exclude<ProviderCost, { kind: "authoritative" }> = rates === null
+        ? () => ({ kind: "unknown", reason: "the response reported no cost and Models.dev has no rate for this model" })
+        : rates.input === 0 && rates.output === 0 && rates.cached === 0
+            ? () => ({ kind: "free", source: "Models.dev catalog rates" })
+            : (usage: ProviderUsage) => ({
+                kind: "estimated",
+                usd: calculateCostUsdDecimal(usage, rates),
+                source: "Models.dev catalog rates",
+            });
 
     return new AiSdkProvider({
         model,
+        ...(attributions === undefined ? {} : { attributions }),
         ...(languageModel === undefined ? {} : { languageModel }),
+        ...(normalizeCharge === undefined ? {} : { normalizeCharge }),
         ...(url === undefined ? {} : { url }),
         ...(headers === undefined ? {} : { headers: { ...headers } }),
         contextWindow,
         fetchTimeoutMs: parseRequiredInt(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "PLURNK_PROVIDERS_FETCH_TIMEOUT", name),
         streamIdleTimeoutMs: parseRequiredInt(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", name),
         reasoning,
+        reasoningResponseStyle: reasoningResponseStyleFromEnv(env, name),
         temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", name, 0),
         repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", name, 0),
         frequencyPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_FREQUENCY_PENALTY, "PLURNK_PROVIDERS_FREQUENCY_PENALTY", name, 0),
         reasoningReserve,
         completionReserve,
         retryAttempts: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "PLURNK_PROVIDERS_RETRY_ATTEMPTS", name),
+        errorDetailLimit: parseRequiredInt(env.PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT, "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT", name),
         reasoningStyle: reasoningStyleFromEnv(env, name),
         promptCacheKey: url === undefined ? false : promptCacheKeyFromEnv(env, name),
         serviceTier: env.PLURNK_PROVIDERS_SERVICE_TIER,
         calculateCost,
+        calculateCharge,
         source: providerSource(name),
         gbnfDebug: env.PLURNK_PROVIDERS_GBNF_DEBUG !== undefined
             && env.PLURNK_PROVIDERS_GBNF_DEBUG !== ""
@@ -133,13 +153,8 @@ export const catalogProviderFromEnv = (
     const sdk = createSdkModel(name, wireModel, env, baseUrlOverride);
     if (sdk === null) return null;
 
-    emitWarningOnce(
-        `${name} provider: countTokens is a chars/2 upper bound — exact counts come from the mimetypes tokenizer seam or tokenize()`,
-        "PLURNK_TOKENIZER_HEURISTIC",
-    );
-
     const info = resolved?.info;
-    const contextWindow = contextOverride ?? info?.contextWindow ?? null;
+    const contextWindow = effectiveContextWindow(contextOverride, info?.contextWindow ?? null);
     if (contextWindow === null) {
         throw new Error(
             `${name} provider: context window unresolved for "${wireModel}" — set PLURNK_PROVIDERS_CONTEXT_WINDOW or update the Models.dev snapshot`,
@@ -150,6 +165,7 @@ export const catalogProviderFromEnv = (
         env,
         model: wireModel,
         languageModel: sdk.languageModel,
+        normalizeCharge: sdk.normalizeCharge,
         url: sdk.compatible?.url,
         headers: sdk.compatible?.headers,
         contextWindow,

package/src/compatibleProvider.test.ts

@@ -13,6 +13,7 @@ const env = {
     PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
     PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
     PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512",
     PLURNK_PROVIDERS_PROBE_ATTEMPTS: "1",
     PLURNK_PROVIDERS_PROBE_DELAY: "0",
     PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
@@ -42,3 +43,98 @@ test("compatible endpoints preserve configured prompt-cache affinity", async ()
 
     assert.equal(body?.prompt_cache_key, "worker-affinity");
 });
+
+test("the server-wide DRY-off floor emits no DRY request fields", async () => {
+    let body: Record<string, unknown> | undefined;
+    mock.method(globalThis, "fetch", async (input: string | URL | Request, init?: RequestInit) => {
+        if (String(input).endsWith("/models")) {
+            return new Response(JSON.stringify({
+                data: [{ id: "local", meta: { n_ctx: 8192 } }],
+            }));
+        }
+        body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+        return new Response(JSON.stringify({
+            model: "local",
+            choices: [{ message: { content: "ok" }, finish_reason: "stop" }],
+            usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+        }), { headers: { "content-type": "application/json" } });
+    });
+
+    const provider = await compatibleProviderFromEnv("openai", {
+        ...env,
+        PLURNK_PROVIDERS_DRY_MULTIPLIER: "0",
+        // Stale or independently supplied shape values cannot activate DRY.
+        PLURNK_PROVIDERS_DRY_BASE: "1.75",
+        PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH: "32",
+    }, "local");
+    await provider.generate({
+        workerId: "worker-dry-off",
+        messages: [{ role: "user", content: "repeat exactly" }],
+    });
+
+    assert.equal(body?.repeat_penalty, 1.15);
+    assert.equal("dry_multiplier" in (body ?? {}), false);
+    assert.equal("dry_base" in (body ?? {}), false);
+    assert.equal("dry_allowed_length" in (body ?? {}), false);
+});
+
+test("detected llama-server measures the complete chat request through input_tokens", async () => {
+    let countUrl: string | undefined;
+    let countBody: Record<string, unknown> | undefined;
+    mock.method(globalThis, "fetch", async (input: string | URL | Request, init?: RequestInit) => {
+        const url = String(input);
+        if (url.endsWith("/models")) {
+            return new Response(JSON.stringify({
+                data: [{ id: "served.gguf", meta: { n_ctx: 8192 } }],
+            }));
+        }
+        if (url.endsWith("/props")) {
+            return new Response(JSON.stringify({ total_slots: 1 }));
+        }
+        if (url.endsWith("/chat/completions/input_tokens")) {
+            countUrl = url;
+            countBody = JSON.parse(String(init?.body)) as Record<string, unknown>;
+            return new Response(JSON.stringify({ input_tokens: 37 }), {
+                headers: { "content-type": "application/json" },
+            });
+        }
+        throw new Error(`unexpected request ${url}`);
+    });
+
+    const provider = await compatibleProviderFromEnv("openai", env, "local");
+    const messages = [
+        { role: "system" as const, content: "system slot" },
+        { role: "user" as const, content: "漢漢漢" },
+    ];
+    assert.deepEqual(await provider.countPromptTokens(messages), {
+        kind: "exact",
+        tokens: 37,
+        source: "llama-server:/v1/chat/completions/input_tokens",
+    });
+    assert.equal(countUrl, "http://local.test/v1/chat/completions/input_tokens");
+    assert.deepEqual(countBody?.messages, messages, "measurement receives the exact dispatched message slots");
+    assert.equal(countBody?.model, "local");
+    assert.deepEqual(countBody?.chat_template_kwargs, { enable_thinking: false });
+});
+
+test("a missing llama-server input-token endpoint degrades explicitly, never to a claimed bound", async () => {
+    mock.method(globalThis, "fetch", async (input: string | URL | Request) => {
+        const url = String(input);
+        if (url.endsWith("/models")) {
+            return new Response(JSON.stringify({
+                data: [{ id: "served.gguf", meta: { n_ctx: 8192 } }],
+            }));
+        }
+        if (url.endsWith("/props")) return new Response(JSON.stringify({ total_slots: 1 }));
+        if (url.endsWith("/chat/completions/input_tokens")) return new Response("missing", { status: 404 });
+        throw new Error(`unexpected request ${url}`);
+    });
+
+    const provider = await compatibleProviderFromEnv("openai", env, "local");
+    assert.deepEqual(await provider.countPromptTokens([{ role: "user", content: "漢漢漢" }]), {
+        kind: "estimate",
+        tokens: 2,
+        source: "heuristic:chars2",
+        detail: "llama-server input-token endpoint returned HTTP 404",
+    });
+});

package/src/compatibleProvider.ts

@@ -1,6 +1,7 @@
 import AiSdkProvider, { type GrammarStyle, type ReasoningStyle } from "./AiSdkProvider.ts";
 import {
     contextWindowFromEnv,
+    effectiveContextWindow,
     dataCaptureFromEnv,
     envelopeFromEnv,
     parseOptionalFloat,
@@ -9,8 +10,9 @@ import {
     parseRequiredInt,
     promptCacheKeyFromEnv,
     reasoningFromEnv,
+    reasoningResponseStyleFromEnv,
 } from "./env.ts";
-import { providerSource } from "./telemetry.ts";
+import { providerSource } from "./notices.ts";
 import type { Provider } from "./types.ts";
 import { emitWarningOnce } from "./warnings.ts";
 
@@ -125,7 +127,7 @@ export const compatibleProviderFromEnv = async (
         attempts,
         parseRequiredInt(env.PLURNK_PROVIDERS_PROBE_DELAY, "PLURNK_PROVIDERS_PROBE_DELAY", provider),
     );
-    let contextWindow = contextWindowFromEnv(env, provider) ?? probe.nCtx;
+    const contextWindow = effectiveContextWindow(contextWindowFromEnv(env, provider), probe.nCtx);
     const pinRaw = env.PLURNK_PROVIDERS_LLAMA_SERVER;
     if (pinRaw !== undefined && pinRaw !== "" && pinRaw !== "0" && pinRaw !== "1") {
         throw new Error(`${provider} provider: PLURNK_PROVIDERS_LLAMA_SERVER must be "1", "0", or unset`);
@@ -150,6 +152,7 @@ export const compatibleProviderFromEnv = async (
     let slotCount: number | null = null;
     let eosText: string | undefined;
     let tokenizeUrl: string | undefined;
+    let promptTokensUrl: string | undefined;
     if (llamaServer) {
         grammarStyle = "llamacpp";
         reasoningStyle = "template";
@@ -157,12 +160,15 @@ export const compatibleProviderFromEnv = async (
         slotCount = props.slotCount;
         eosText = props.eosText ?? undefined;
         tokenizeUrl = url.replace(/\/v1\/chat\/completions$/, "/tokenize");
+        promptTokensUrl = url.replace(/\/v1\/chat\/completions$/, "/v1/chat/completions/input_tokens");
     }
 
-    emitWarningOnce(
-        `${provider} provider: countTokens is a chars/2 upper bound — exact counts come from the mimetypes tokenizer seam or tokenize()`,
-        "PLURNK_TOKENIZER_HEURISTIC",
-    );
+    if (!llamaServer) {
+        emitWarningOnce(
+            `${provider} provider: physical prompt counting is a chars/2 estimate; over-policy recovery fails closed without exact or bounded request evidence`,
+            "PLURNK_PROMPT_COUNT_ESTIMATE",
+        );
+    }
     const { reasoningReserve, completionReserve } = envelopeFromEnv(env, provider);
     return new AiSdkProvider({
         model,
@@ -172,6 +178,7 @@ export const compatibleProviderFromEnv = async (
         fetchTimeoutMs: timeout,
         streamIdleTimeoutMs: parseRequiredInt(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", provider),
         reasoning: reasoningFromEnv(env, provider),
+        reasoningResponseStyle: reasoningResponseStyleFromEnv(env, provider),
         reasoningStyle,
         temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", provider, 0),
         repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", provider, 0),
@@ -184,6 +191,7 @@ export const compatibleProviderFromEnv = async (
         completionReserve,
         tuningFloors: provider !== "plurnk",
         retryAttempts: parseRequiredInt(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "PLURNK_PROVIDERS_RETRY_ATTEMPTS", provider),
+        errorDetailLimit: parseRequiredInt(env.PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT, "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT", provider),
         promptCacheKey: promptCacheKeyFromEnv(env, provider),
         source: providerSource(provider),
         grammarStyle,
@@ -199,6 +207,7 @@ export const compatibleProviderFromEnv = async (
         slotCount,
         eosText,
         tokenizeUrl,
+        promptTokensUrl,
         servedModel: probe.servedModel ?? undefined,
         requiresMaxTokens: llamaServer || undefined,
     });

package/src/cost.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+    providerCostFor,
+    providerCostUsd,
+    validateAuthoritativeCharge,
+} from "./cost.ts";
+import type { ProviderUsage } from "./types.ts";
+
+const usage: ProviderUsage = {
+    prompt: 1,
+    completion: 1,
+    reasoning: 0,
+    cached: 0,
+    total: 2,
+};
+
+test("authoritative provider charge wins over a local estimate", () => {
+    const provider = {
+        calculateCost: () => 12,
+        calculateCharge: () => ({ kind: "estimated", usd: "12", source: "catalog" } as const),
+    };
+    const charge = {
+        kind: "authoritative",
+        amount: { amount: "0.0000042", currency: "XMR" },
+        usdEquivalent: "0.73",
+        source: "settled upstream turn charge",
+    } as const;
+    assert.deepEqual(providerCostFor(provider, usage, charge), charge);
+    assert.equal(providerCostUsd(charge), 0.73);
+});
+
+test("explicit free remains distinguishable from unknown", () => {
+    const free = providerCostFor({
+        calculateCost: () => 0,
+        calculateCharge: () => ({ kind: "free", source: "local model" }),
+    }, usage);
+    const unknown = providerCostFor({ calculateCost: () => 0 }, usage);
+    assert.deepEqual(free, { kind: "free", source: "local model" });
+    assert.deepEqual(unknown, {
+        kind: "unknown",
+        reason: "the response reported no cost and Models.dev has no rate for this model",
+    });
+    assert.equal(providerCostUsd(free), 0);
+    assert.equal(providerCostUsd(unknown), null);
+});
+
+test("legacy calculateCost is not a monetary-reporting authority", () => {
+    const cost = providerCostFor({ calculateCost: () => 0.25 }, usage);
+    assert.deepEqual(cost, {
+        kind: "unknown",
+        reason: "the response reported no cost and Models.dev has no rate for this model",
+    });
+    assert.equal(providerCostUsd(cost), null);
+});
+
+test("rejects malformed money instead of mining or coercing it", () => {
+    assert.throws(() => validateAuthoritativeCharge({
+        kind: "authoritative",
+        amount: { amount: "1e3", currency: "usd" },
+        usdEquivalent: "1000",
+        source: "wire",
+    }), /canonical non-negative decimal string/);
+});

package/src/cost.ts

@@ -0,0 +1,78 @@
+import type {
+    AuthoritativeCharge,
+    ProviderUsage,
+} from "./types.ts";
+import type { ProviderCost } from "@plurnk/plurnk-contracts";
+
+const DECIMAL = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
+const CURRENCY = /^[A-Z][A-Z0-9]{2,11}$/;
+
+const nonEmpty = (value: string, name: string): string => {
+    if (value.trim() === "") throw new TypeError(`${name} must be non-empty`);
+    return value;
+};
+
+const decimal = (value: string, name: string): string => {
+    if (!DECIMAL.test(value)) throw new TypeError(`${name} must be a canonical non-negative decimal string`);
+    return value;
+};
+
+export const validateAuthoritativeCharge = (charge: AuthoritativeCharge): AuthoritativeCharge => {
+    if (charge.kind !== "authoritative") throw new TypeError("provider charge must be authoritative");
+    decimal(charge.amount.amount, "provider charge amount");
+    if (!CURRENCY.test(charge.amount.currency)) {
+        throw new TypeError("provider charge currency must be an uppercase currency code");
+    }
+    decimal(charge.usdEquivalent, "provider charge USD equivalent");
+    nonEmpty(charge.source, "provider charge source");
+    return charge;
+};
+
+export const validateProviderCost = (cost: ProviderCost): ProviderCost => {
+    switch (cost.kind) {
+        case "authoritative":
+            return validateAuthoritativeCharge(cost);
+        case "estimated":
+            decimal(cost.usd, "provider cost estimate");
+            nonEmpty(cost.source, "provider cost estimate source");
+            return cost;
+        case "free":
+            nonEmpty(cost.source, "provider free source");
+            return cost;
+        case "unknown":
+            nonEmpty(cost.reason, "provider unknown-cost reason");
+            return cost;
+    }
+};
+
+export const resolveProviderCost = (
+    charge: AuthoritativeCharge | undefined,
+    current: ProviderCost | undefined,
+): ProviderCost => {
+    if (charge !== undefined) return validateAuthoritativeCharge(charge);
+    if (current !== undefined) return validateProviderCost(current);
+    return {
+        kind: "unknown",
+        reason: "the response reported no cost and Models.dev has no rate for this model",
+    };
+};
+
+export const providerCostUsd = (cost: ProviderCost): number | null => {
+    const value = cost.kind === "authoritative"
+        ? cost.usdEquivalent
+        : cost.kind === "estimated"
+            ? cost.usd
+            : cost.kind === "free"
+                ? "0"
+                : null;
+    return value === null ? null : Number(value);
+};
+
+export const providerCostFor = (
+    provider: { calculateCharge?(usage: ProviderUsage): Exclude<ProviderCost, AuthoritativeCharge>; calculateCost(usage: ProviderUsage): number },
+    usage: ProviderUsage,
+    charge?: AuthoritativeCharge,
+): ProviderCost => resolveProviderCost(
+    charge,
+    provider.calculateCharge?.(usage),
+);

package/src/defaults.test.ts

@@ -7,6 +7,7 @@ test("withProviderDefaults supplies the package-owned operational floor", () =>
     assert.equal(env.PLURNK_PROVIDERS_PROMPT_CACHE_KEY, "1");
     assert.equal(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "600000");
     assert.equal(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "3");
+    assert.equal(env.PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT, "512");
 });
 
 test("withProviderDefaults preserves every explicit operator value", () => {