@plurnk/plurnk-providers 1.5.0 → 1.6.0

package/src/cost.test.ts

@@ -1,62 +1,81 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import {
-    providerCostFor,
+    addDecimals,
+    estimateProviderCost,
     providerCostUsd,
-    validateAuthoritativeCharge,
+    resolveProviderCost,
+    sumProviderCostsUsd,
+    validateChargedCost,
 } from "./cost.ts";
 import type { ProviderUsage } from "./types.ts";
 
 const usage: ProviderUsage = {
-    prompt: 1,
-    completion: 1,
-    reasoning: 0,
-    cached: 0,
-    total: 2,
+    inputTokens: 1,
+    outputTokens: 1,
+    totalTokens: 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",
+test("direct charged evidence wins over a Models.dev estimate", () => {
+    const charged = {
+        kind: "charged",
         amount: { amount: "0.0000042", currency: "XMR" },
         usdEquivalent: "0.73",
-        source: "settled upstream turn charge",
+        source: "settled upstream request charge",
     } as const;
-    assert.deepEqual(providerCostFor(provider, usage, charge), charge);
-    assert.equal(providerCostUsd(charge), 0.73);
+    const estimated = estimateProviderCost(usage, { input: 1, output: 1 }, "Models.dev");
+    assert.deepEqual(resolveProviderCost(charged, estimated), charged);
+    assert.equal(providerCostUsd(charged), "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" });
+test("an exact zero estimate remains distinguishable from unknown cost", () => {
+    const zero = estimateProviderCost(usage, { input: 0, output: 0 }, "Models.dev");
+    const unknown = estimateProviderCost(usage, null, "Models.dev");
+    assert.deepEqual(zero, {
+        kind: "estimated",
+        amount: { amount: "0", currency: "USD" },
+        source: "Models.dev",
+    });
     assert.deepEqual(unknown, {
         kind: "unknown",
-        reason: "the response reported no cost and Models.dev has no rate for this model",
+        reason: "Models.dev has no complete rate for this model",
     });
-    assert.equal(providerCostUsd(free), 0);
+    assert.equal(providerCostUsd(zero), "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("a distinct cache rate requires the applicable token category", () => {
+    assert.deepEqual(
+        estimateProviderCost(usage, { input: 1, output: 1, cacheRead: 0.1 }, "Models.dev"),
+        {
+            kind: "unknown",
+            reason: "the provider response omitted a token category with a distinct Models.dev rate",
+        },
+    );
+});
+
+test("decimal aggregation is exact and becomes unknown if any request is unknown", () => {
+    assert.equal(addDecimals(["0.1", "0.02", "3"]), "3.12");
+    assert.equal(sumProviderCostsUsd([
+        {
+            kind: "charged",
+            amount: { amount: "0.1", currency: "USD" },
+            source: "provider",
+        },
+        {
+            kind: "estimated",
+            amount: { amount: "0.02", currency: "USD" },
+            source: "Models.dev",
+        },
+    ]), "0.12");
+    assert.equal(sumProviderCostsUsd([
+        { kind: "unknown", reason: "no evidence" },
+    ]), null);
 });
 
-test("rejects malformed money instead of mining or coercing it", () => {
-    assert.throws(() => validateAuthoritativeCharge({
-        kind: "authoritative",
+test("malformed charged money is rejected instead of coerced", () => {
+    assert.throws(() => validateChargedCost({
+        kind: "charged",
         amount: { amount: "1e3", currency: "usd" },
         usdEquivalent: "1000",
         source: "wire",

package/src/cost.ts

@@ -1,78 +1,139 @@
 import type {
-    AuthoritativeCharge,
+    ChargedCost,
+    ProviderCost,
     ProviderUsage,
 } from "./types.ts";
-import type { ProviderCost } from "@plurnk/plurnk-contracts";
+import {
+    calculateCostUsdDecimal,
+    canonicalDecimal,
+    type TokenRates,
+} from "./usage.ts";
 
 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`);
+const recordOf = (value: unknown, name: string): Record<string, unknown> => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${name} must be an object`);
+    }
+    return value as Record<string, unknown>;
+};
+
+const nonEmpty = (value: unknown, name: string): string => {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new TypeError(`${name} must be a non-empty string`);
+    }
     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`);
+export const validateDecimal = (value: unknown, name: string): string => {
+    if (typeof value !== "string" || !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");
+const monetaryAmount = (value: unknown, name: string): { amount: string; currency: string } => {
+    const amount = recordOf(value, name);
+    const decimalAmount = validateDecimal(amount.amount, `${name} amount`);
+    if (typeof amount.currency !== "string" || !CURRENCY.test(amount.currency)) {
+        throw new TypeError(`${name} currency must be an uppercase currency code`);
     }
-    decimal(charge.usdEquivalent, "provider charge USD equivalent");
-    nonEmpty(charge.source, "provider charge source");
-    return charge;
+    return { amount: decimalAmount, currency: amount.currency };
 };
 
-export const validateProviderCost = (cost: ProviderCost): ProviderCost => {
+export const validateChargedCost = (value: unknown): ChargedCost => {
+    const cost = recordOf(value, "provider charged cost");
+    if (cost.kind !== "charged") throw new TypeError("provider charged cost kind must be charged");
+    monetaryAmount(cost.amount, "provider charged cost");
+    if (cost.usdEquivalent !== undefined) {
+        validateDecimal(cost.usdEquivalent, "provider charged cost USD equivalent");
+    }
+    nonEmpty(cost.source, "provider charged cost source");
+    return value as ChargedCost;
+};
+
+export const validateProviderCost = (value: unknown): ProviderCost => {
+    const cost = recordOf(value, "provider cost");
     switch (cost.kind) {
-        case "authoritative":
-            return validateAuthoritativeCharge(cost);
+        case "charged":
+            return validateChargedCost(value);
         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;
+            monetaryAmount(cost.amount, "provider estimated cost");
+            nonEmpty(cost.source, "provider estimated cost source");
+            return value as ProviderCost;
         case "unknown":
             nonEmpty(cost.reason, "provider unknown-cost reason");
-            return cost;
+            return value as ProviderCost;
+        default:
+            throw new TypeError("provider cost kind must be charged, estimated, or unknown");
     }
 };
 
-export const resolveProviderCost = (
-    charge: AuthoritativeCharge | undefined,
-    current: ProviderCost | undefined,
+export const estimateProviderCost = (
+    usage: ProviderUsage | undefined,
+    rates: TokenRates | null,
+    source: string,
 ): 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",
-    };
+    if (usage === undefined) {
+        return { kind: "unknown", reason: "the provider response reported no normalized usage" };
+    }
+    if (rates === null) {
+        return { kind: "unknown", reason: "Models.dev has no complete rate for this model" };
+    }
+    const usd = calculateCostUsdDecimal(usage, rates);
+    return usd === null
+        ? {
+            kind: "unknown",
+            reason: "the provider response omitted a token category with a distinct Models.dev rate",
+        }
+        : {
+            kind: "estimated",
+            amount: { amount: usd, currency: "USD" },
+            source,
+        };
 };
 
-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 resolveProviderCost = (
+    direct: ProviderCost | undefined,
+    estimated: ProviderCost,
+): ProviderCost => direct === undefined
+    ? validateProviderCost(estimated)
+    : validateProviderCost(direct);
+
+export const providerCostUsd = (cost: ProviderCost): string | null => {
+    const validated = validateProviderCost(cost);
+    switch (validated.kind) {
+        case "charged":
+            return validated.amount.currency === "USD"
+                ? validated.amount.amount
+                : validated.usdEquivalent ?? null;
+        case "estimated":
+            return validated.amount.currency === "USD" ? validated.amount.amount : null;
+        case "unknown":
+            return null;
+    }
 };
 
-export const providerCostFor = (
-    provider: { calculateCharge?(usage: ProviderUsage): Exclude<ProviderCost, AuthoritativeCharge>; calculateCost(usage: ProviderUsage): number },
-    usage: ProviderUsage,
-    charge?: AuthoritativeCharge,
-): ProviderCost => resolveProviderCost(
-    charge,
-    provider.calculateCharge?.(usage),
-);
+const decimalParts = (value: string): { coefficient: bigint; scale: number } => {
+    validateDecimal(value, "decimal amount");
+    const [integer, fraction = ""] = value.split(".");
+    return { coefficient: BigInt(`${integer}${fraction}`), scale: fraction.length };
+};
+
+export const addDecimals = (values: readonly string[]): string => {
+    const parts = values.map(decimalParts);
+    const scale = Math.max(0, ...parts.map((part) => part.scale));
+    const coefficient = parts.reduce(
+        (sum, part) => sum + part.coefficient * 10n ** BigInt(scale - part.scale),
+        0n,
+    );
+    return canonicalDecimal(coefficient, scale);
+};
+
+export const sumProviderCostsUsd = (costs: readonly ProviderCost[]): string | null => {
+    const values = costs.map(providerCostUsd);
+    return values.some((value) => value === null)
+        ? null
+        : addDecimals(values as string[]);
+};

package/src/defaults.test.ts

@@ -4,17 +4,27 @@ import { withProviderDefaults } from "./defaults.ts";
 
 test("withProviderDefaults supplies the package-owned operational floor", () => {
     const env = withProviderDefaults({});
-    assert.equal(env.PLURNK_PROVIDERS_PROMPT_CACHE_KEY, "1");
+    assert.equal(env.PLURNK_PROVIDERS_CACHE_AFFINITY, "1");
+    assert.equal(env.PLURNK_PROVIDERS_CACHE_WRITE_POLICY, "stable-system");
+    assert.equal(env.PLURNK_PROVIDERS_OPERATION_TIMEOUT, "2700000");
     assert.equal(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "600000");
+    assert.equal(env.PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT, "600000");
+    assert.equal(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "120000");
     assert.equal(env.PLURNK_PROVIDERS_RETRY_ATTEMPTS, "3");
     assert.equal(env.PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT, "512");
 });
 
 test("withProviderDefaults preserves every explicit operator value", () => {
     const env = withProviderDefaults({
-        PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "malformed",
+        PLURNK_PROVIDERS_CACHE_AFFINITY: "malformed",
+        PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "off",
+        PLURNK_PROVIDERS_OPERATION_TIMEOUT: "84",
         PLURNK_PROVIDERS_FETCH_TIMEOUT: "42",
+        PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT: "21",
     });
-    assert.equal(env.PLURNK_PROVIDERS_PROMPT_CACHE_KEY, "malformed");
+    assert.equal(env.PLURNK_PROVIDERS_CACHE_AFFINITY, "malformed");
+    assert.equal(env.PLURNK_PROVIDERS_CACHE_WRITE_POLICY, "off");
+    assert.equal(env.PLURNK_PROVIDERS_OPERATION_TIMEOUT, "84");
     assert.equal(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "42");
+    assert.equal(env.PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT, "21");
 });

package/src/env.test.ts

@@ -1,6 +1,15 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { parseRequiredInt, parseOptionalInt, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv } from "./env.ts";
+import {
+    cacheAffinityFromEnv,
+    cacheWritePolicyFromEnv,
+    parseRequiredInt,
+    parseOptionalInt,
+    parseTimeoutMs,
+    requireEnv,
+    reasoningFromEnv,
+    reasoningResponseStyleFromEnv,
+} from "./env.ts";
 
 test("parseRequiredInt: parses a non-negative integer", () => {
     assert.equal(parseRequiredInt("600000", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), 600000);
@@ -18,6 +27,15 @@ test("parseRequiredInt: rejects non-numeric, fractional, and negative values", (
     assert.throws(() => parseRequiredInt("-1", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), /must be a non-negative integer \(got "-1"\)/);
 });
 
+test("parseTimeoutMs accepts disabled deadlines and rejects timer overflow", () => {
+    assert.equal(parseTimeoutMs("0", "PLURNK_PROVIDERS_OPERATION_TIMEOUT", "openai"), 0);
+    assert.equal(parseTimeoutMs("2147483647", "PLURNK_PROVIDERS_OPERATION_TIMEOUT", "openai"), 2_147_483_647);
+    assert.throws(
+        () => parseTimeoutMs("2147483648", "PLURNK_PROVIDERS_OPERATION_TIMEOUT", "openai"),
+        /must be at most 2147483647 milliseconds/,
+    );
+});
+
 test("parseOptionalInt: absent → null, present → integer", () => {
     assert.equal(parseOptionalInt(undefined, "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), null);
     assert.equal(parseOptionalInt("", "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), null);
@@ -29,13 +47,13 @@ test("parseOptionalInt: rejects fractional and negative values", () => {
     assert.throws(() => parseOptionalInt("-8", "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), /must be a non-negative integer/);
 });
 
-test("reasoningFromEnv: activation modes parse; budget required IFF on; fail-hard on everything else", () => {
+test("reasoningFromEnv: activation is independent from an optional explicit budget", () => {
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "off" }, "openai"), { mode: "off", budget: null });
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai"), { mode: "adaptive", budget: null });
+    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on" }, "openai"), { mode: "on", budget: null });
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "4096" }, "openai"), { mode: "on", budget: 4096 });
     assert.throws(() => reasoningFromEnv({}, "openai"), /PLURNK_PROVIDERS_REASONING must be set/);
     assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "8192" }, "openai"), /must be one of "off", "adaptive", "on"/); // the old numeric habit fails loudly
-    assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on" }, "openai"), /PLURNK_PROVIDERS_REASONING_BUDGET must be set when/);
     assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "0" }, "openai"), /positive integer/);
     assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "1.5" }, "openai"), /positive integer/);
 });
@@ -59,6 +77,31 @@ test("requireEnv: returns the value or throws a named error", () => {
     assert.throws(() => requireEnv("", "GROQ_API_KEY", "groq"), /must be set/);
 });
 
+test("cache policy keeps cost-neutral affinity separate from paid cache writes", () => {
+    assert.equal(cacheAffinityFromEnv({ PLURNK_PROVIDERS_CACHE_AFFINITY: "1" }, "openai"), true);
+    assert.equal(cacheAffinityFromEnv({ PLURNK_PROVIDERS_CACHE_AFFINITY: "0" }, "openai"), false);
+    assert.equal(cacheWritePolicyFromEnv({ PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "stable-system" }, "anthropic"), "stable-system");
+    assert.equal(cacheWritePolicyFromEnv({ PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "off" }, "anthropic"), "off");
+    assert.throws(
+        () => cacheAffinityFromEnv({ PLURNK_PROVIDERS_CACHE_AFFINITY: "auto" }, "openai"),
+        /PLURNK_PROVIDERS_CACHE_AFFINITY must be "0" or "1"/,
+    );
+    assert.throws(
+        () => cacheWritePolicyFromEnv({ PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "everything" }, "anthropic"),
+        /PLURNK_PROVIDERS_CACHE_WRITE_POLICY must be "off" or "stable-system"/,
+    );
+});
+
+test("the generic prompt-cache-key knob is retired rather than retained as a compatibility path", () => {
+    assert.throws(
+        () => cacheAffinityFromEnv({
+            PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
+            PLURNK_PROVIDERS_CACHE_AFFINITY: "1",
+        }, "fireworks"),
+        /PLURNK_PROVIDERS_PROMPT_CACHE_KEY was renamed to PLURNK_PROVIDERS_CACHE_AFFINITY/,
+    );
+});
+
 // — per-alias knob scoping (per-alias scoping doctrine, user 2026-07-03) —
 
 test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases ignored", async () => {
@@ -86,10 +129,16 @@ test("scopeEnvToAlias: aliases with underscores resolve; a bare knob is never mi
     const env = {
         PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000",
         PLURNK_PROVIDERS_FETCH_TIMEOUT_my_box: "5000",
+        PLURNK_PROVIDERS_OPERATION_TIMEOUT: "2700000",
+        PLURNK_PROVIDERS_OPERATION_TIMEOUT_my_box: "15000",
+        PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT: "600000",
+        PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT_my_box: "2500",
         PLURNK_PROVIDERS_REASONING: "off",
         PLURNK_PROVIDERS_REASONING_BUDGET: "4096", // bare budget — NOT a "_capacity" alias override of REASONING
     } as NodeJS.ProcessEnv;
     assert.equal(scopeEnvToAlias(env, "my_box").PLURNK_PROVIDERS_FETCH_TIMEOUT, "5000");
+    assert.equal(scopeEnvToAlias(env, "my_box").PLURNK_PROVIDERS_OPERATION_TIMEOUT, "15000");
+    assert.equal(scopeEnvToAlias(env, "my_box").PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT, "2500");
     assert.equal(scopeEnvToAlias(env, "budget").PLURNK_PROVIDERS_REASONING, "off"); // collision guard
 });
 
@@ -175,11 +224,11 @@ test("still-set old THINKING names fail hard with the rename pointer", () => {
     );
 });
 
-test("the shipped floor activates reasoning by default (adaptive)", async () => {
+test("the shipped floor defers reasoning posture to the provider by default (adaptive)", async () => {
     const { readFileSync } = await import("node:fs");
     const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
     assert.ok(defaults.includes("PLURNK_PROVIDERS_REASONING=adaptive"), "floor must ship REASONING=adaptive");
-    assert.ok(!defaults.match(/^PLURNK_PROVIDERS_REASONING_BUDGET=/m), "no shipped magnitude — budget is on-mode only");
+    assert.ok(!defaults.match(/^PLURNK_PROVIDERS_REASONING_BUDGET=/m), "no shipped magnitude — an explicit on-mode budget is optional");
 });
 
 test("the shipped DRY floor is off and claims no universally safe shape", async () => {

package/src/env.ts

@@ -8,6 +8,16 @@ export const parseRequiredInt = (raw: string | undefined, name: string, label: s
     return n;
 };
 
+export const MAX_PROVIDER_TIMEOUT_MS = 2_147_483_647;
+
+export const parseTimeoutMs = (raw: string | undefined, name: string, label: string): number => {
+    const timeoutMs = parseRequiredInt(raw, name, label);
+    if (timeoutMs > MAX_PROVIDER_TIMEOUT_MS) {
+        throw new Error(`${label} provider: ${name} must be at most ${MAX_PROVIDER_TIMEOUT_MS} milliseconds (got "${raw}")`);
+    }
+    return timeoutMs;
+};
+
 export const parseOptionalInt = (raw: string | undefined, name: string, label: string): number | null => {
     if (raw === undefined || raw.length === 0) return null;
     const n = Number(raw);
@@ -34,15 +44,6 @@ export const requireEnv = (raw: string | undefined, name: string, label: string)
     return raw;
 };
 
-export const promptCacheKeyFromEnv = (env: NodeJS.ProcessEnv, label: string): boolean => {
-    const name = "PLURNK_PROVIDERS_PROMPT_CACHE_KEY";
-    const value = env[name];
-    if (value !== "0" && value !== "1") {
-        throw new Error(`${label} provider: ${name} must be "0" or "1"`);
-    }
-    return value === "1";
-};
-
 // {§provider-configuration} A still-set retired knob fails
 // hard pointing at its successor — never silently coexists with the new floor.
 // The retired names appear ONLY as this function's ARGUMENTS at the call sites
@@ -52,6 +53,27 @@ const shedRenamed = (env: NodeJS.ProcessEnv, oldName: string, newName: string, l
     if (stale !== undefined && stale.length > 0) throw new Error(`${label} provider: ${oldName} was renamed to ${newName} (${ref}); update the env`);
 };
 
+export type CacheWritePolicy = "off" | "stable-system";
+
+export const cacheAffinityFromEnv = (env: NodeJS.ProcessEnv, label: string): boolean => {
+    const name = "PLURNK_PROVIDERS_CACHE_AFFINITY";
+    shedRenamed(env, "PLURNK_PROVIDERS_PROMPT_CACHE_KEY", name, label, "{§provider-cache-affinity}"); // lexicon-allow
+    const value = env[name];
+    if (value !== "0" && value !== "1") {
+        throw new Error(`${label} provider: ${name} must be "0" or "1"`);
+    }
+    return value === "1";
+};
+
+export const cacheWritePolicyFromEnv = (env: NodeJS.ProcessEnv, label: string): CacheWritePolicy => {
+    const name = "PLURNK_PROVIDERS_CACHE_WRITE_POLICY";
+    const value = env[name];
+    if (value !== "off" && value !== "stable-system") {
+        throw new Error(`${label} provider: ${name} must be "off" or "stable-system"`);
+    }
+    return value;
+};
+
 // {§provider-evidence} Data-capture knobs are read identically by every provider
 // (standard AND
 // plugin) so the opt-in surface is one source of truth. Both OFF by default —
@@ -79,8 +101,8 @@ export const contextWindowFromEnv = (env: NodeJS.ProcessEnv, label: string): num
     return parseOptionalInt(env.PLURNK_PROVIDERS_CONTEXT_WINDOW, "PLURNK_PROVIDERS_CONTEXT_WINDOW", label);
 };
 
-// {§model-fact-resolution} — an operator value caps known model physics and
-// declares the window only when no natural value is known.
+// {§model-fact-resolution} — an operator value caps known natural model
+// capacity and declares the envelope only when no natural value is known.
 export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number): number;
 export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number | null): number | null;
 export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number | null): number | null {
@@ -92,10 +114,10 @@ export function effectiveContextWindow(operatorCap: number | null, naturalWindow
 }
 
 // {§provider-generation-envelope} How much of a
-// DETECTED context window is reserved for reasoning and for completion — the
+// effective context window is reserved for reasoning and for completion — the
 // remainder (minus the consumer's own packing-safety margin) is the prompt
-// budget. Provider-owned: the window is a provider fact and these are amounts OF
-// it. Each knob accepts a percentage of the window
+// gauge. Provider-owned: the window is the effective hard envelope and these are
+// amounts OF it. Each knob accepts a percentage of the window
 // ("10%") or an absolute token count ("4096"); the floor ships percentages so
 // every window-advertising endpoint (llama-server n_ctx, the plurnk.ai router,
 // a cataloged cloud model) arrives at sane defaults with ZERO operator tuning.
@@ -144,8 +166,8 @@ export const resolveEnvelopeFromEnv = (env: NodeJS.ProcessEnv, window: number |
 // {§provider-configuration} The side-channel reasoning knobs — activation and budget
 // are separate vars, so a numeric budget can never silently flip wire flags:
 //   PLURNK_PROVIDERS_REASONING           off | adaptive | on   (REQUIRED, fail-hard)
-//   PLURNK_PROVIDERS_REASONING_BUDGET  positive int, REQUIRED iff REASONING=on —
-//     the magnitude for tier/budget mapping. On llama-server it is the explicit
+//   PLURNK_PROVIDERS_REASONING_BUDGET  optional positive int when REASONING=on —
+//     an explicit magnitude for tier/budget mapping. On llama-server it is the
 //     request-scoped allowance and cannot exceed the physical reasoning reserve.
 // The provider maps intent to the backend's mechanism; the consumer states
 // intent, never mechanism. PLAN is a separate public intended-goals record.
@@ -177,7 +199,7 @@ export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoni
     if (raw !== "on") return { mode: raw, budget: null };
     const capName = "PLURNK_PROVIDERS_REASONING_BUDGET";
     const capRaw = env[capName];
-    if (capRaw === undefined || capRaw.length === 0) throw new Error(`${label} provider: ${capName} must be set when ${name}=on`);
+    if (capRaw === undefined || capRaw.length === 0) return { mode: "on", budget: null };
     const n = Number(capRaw);
     if (!Number.isInteger(n) || n <= 0) throw new Error(`${label} provider: ${capName} must be a positive integer (got "${capRaw}")`);
     return { mode: "on", budget: n };
@@ -199,14 +221,17 @@ export const PROVIDERS_KNOBS = Object.freeze([
     "PLURNK_PROVIDERS_CONTEXT_WINDOW",
     "PLURNK_PROVIDERS_RETRY_ATTEMPTS",
     "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT",
+    "PLURNK_PROVIDERS_OPERATION_TIMEOUT",
     "PLURNK_PROVIDERS_FETCH_TIMEOUT",
+    "PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT",
     "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT",
     "PLURNK_PROVIDERS_LLAMA_SERVER",
     "PLURNK_PROVIDERS_TEMPERATURE",
     "PLURNK_PROVIDERS_REPEAT_PENALTY",
     "PLURNK_PROVIDERS_FREQUENCY_PENALTY",
     "PLURNK_PROVIDERS_SERVICE_TIER",
-    "PLURNK_PROVIDERS_PROMPT_CACHE_KEY",
+    "PLURNK_PROVIDERS_CACHE_WRITE_POLICY",
+    "PLURNK_PROVIDERS_CACHE_AFFINITY",
     "PLURNK_PROVIDERS_REPEAT_LAST_N",
     "PLURNK_PROVIDERS_DRY_MULTIPLIER",
     "PLURNK_PROVIDERS_DRY_BASE",