@plurnk/plurnk-providers 1.5.0 → 1.6.1

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,16 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { parseRequiredInt, parseOptionalInt, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv } from "./env.ts";
+import {
+    cacheAffinityFromEnv,
+    cacheWritePolicyFromEnv,
+    generationEnvelopeFromEnv,
+    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 +28,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,15 +48,14 @@ 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", PLURNK_PROVIDERS_REASONING_BUDGET: "4096" }, "openai"), { mode: "on", budget: 4096 });
+    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on" }, "openai"), { mode: "on", budget: null });
+    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on" }, "openai", 4096), { mode: "on", budget: 4096 });
+    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai", 4096), { mode: "adaptive", 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/);
 });
 
 test("{§provider-tagged-reasoning} response style is explicit and invalid values fail at the provider boundary", () => {
@@ -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 () => {
@@ -69,7 +112,7 @@ test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases i
         PLURNK_PROVIDERS_REASONING_BUDGET_TURBODERP: "4096", // case-folds like PLURNK_MODEL_ keys
         PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_TURBODERP: "think-tags",
         PLURNK_PROVIDERS_CONTEXT_WINDOW_turboderp: "8000",
-        PLURNK_PROVIDERS_COMPLETION_RESERVE_turboderp: "4096",
+        PLURNK_PROVIDERS_OUTPUT_BUDGET_turboderp: "4096",
         PLURNK_PROVIDERS_CONTEXT_WINDOW_other: "1",
     } as NodeJS.ProcessEnv;
     const scoped = scopeEnvToAlias(env, "turboderp");
@@ -77,7 +120,7 @@ test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases i
     assert.equal(scoped.PLURNK_PROVIDERS_REASONING_BUDGET, "4096");
     assert.equal(scoped.PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE, "think-tags");
     assert.equal(scoped.PLURNK_PROVIDERS_CONTEXT_WINDOW, "8000");
-    assert.equal(scoped.PLURNK_PROVIDERS_COMPLETION_RESERVE, "4096");
+    assert.equal(scoped.PLURNK_PROVIDERS_OUTPUT_BUDGET, "4096");
     assert.equal(scopeEnvToAlias(env, "plain").PLURNK_PROVIDERS_REASONING, "off"); // fallback intact
 });
 
@@ -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
 });
 
@@ -122,16 +171,16 @@ test("contextWindowFromEnv: reads the new name, sheds CONTEXT_SIZE hard, null wh
 
 test("scopeEnvToAlias: a caller-supplied knob list scopes consumer-owned vars", async () => {
     const { scopeEnvToAlias } = await import("./env.ts");
-    const SERVICE_KNOBS = ["PLURNK_SERVICE_MAX_TURNS", "PLURNK_SERVICE_LOOP_TIMEOUT", "PLURNK_SERVICE_EXEC_HOLD_MS", "PLURNK_SERVICE_SAFETY"];
+    const SERVICE_KNOBS = ["PLURNK_SERVICE_MAX_TURNS", "PLURNK_SERVICE_LOOP_TIMEOUT", "PLURNK_SERVICE_EXEC_HOLD_MS", "PLURNK_SERVICE_PROMPT_PROJECTION"];
     const env = {
-        PLURNK_SERVICE_MAX_TURNS: "163840", PLURNK_SERVICE_LOOP_TIMEOUT: "16384", PLURNK_SERVICE_EXEC_HOLD_MS: "49152", PLURNK_SERVICE_SAFETY: "1024",
+        PLURNK_SERVICE_MAX_TURNS: "163840", PLURNK_SERVICE_LOOP_TIMEOUT: "16384", PLURNK_SERVICE_EXEC_HOLD_MS: "49152", PLURNK_SERVICE_PROMPT_PROJECTION: "25%",
         PLURNK_SERVICE_MAX_TURNS_turboderp: "78848", PLURNK_SERVICE_LOOP_TIMEOUT_turboderp: "4096", PLURNK_SERVICE_EXEC_HOLD_MS_TURBODERP: "8192", // case-folds
     } as NodeJS.ProcessEnv;
     const gemma = scopeEnvToAlias(env, "turboderp", SERVICE_KNOBS);
     assert.equal(gemma.PLURNK_SERVICE_MAX_TURNS, "78848");
     assert.equal(gemma.PLURNK_SERVICE_LOOP_TIMEOUT, "4096");
     assert.equal(gemma.PLURNK_SERVICE_EXEC_HOLD_MS, "8192");
-    assert.equal(gemma.PLURNK_SERVICE_SAFETY, "1024"); // bare fallback intact
+    assert.equal(gemma.PLURNK_SERVICE_PROMPT_PROJECTION, "25%"); // bare fallback intact
     const cloud = scopeEnvToAlias(env, "fireslow", SERVICE_KNOBS);
     assert.equal(cloud.PLURNK_SERVICE_LOOP_TIMEOUT, "16384"); // 64k envelope untouched by gemma overrides
     assert.equal(cloud.PLURNK_SERVICE_EXEC_HOLD_MS, "49152");
@@ -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 () => {
@@ -192,23 +241,52 @@ test("the shipped DRY floor is off and claims no universally safe shape", async
 
 // -- {§provider-generation-envelope} --
 
-test("envelopeFromEnv: percentages and absolutes parse; missing/invalid fail hard", async () => {
-    const { envelopeFromEnv } = await import("./env.ts");
+test("generationEnvelopeFromEnv: output is total and reasoning is an optional subset", () => {
+    assert.deepEqual(
+        generationEnvelopeFromEnv({
+            PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%",
+            PLURNK_PROVIDERS_REASONING_BUDGET: "4096",
+        } as NodeJS.ProcessEnv, "x", 100_000, 32_000),
+        { outputBudget: 32_000, reasoningBudget: 4096 },
+    );
+    assert.throws(() => generationEnvelopeFromEnv({}, "x", 100_000, null), /PLURNK_PROVIDERS_OUTPUT_BUDGET must be set/);
+    assert.throws(() => generationEnvelopeFromEnv({ PLURNK_PROVIDERS_OUTPUT_BUDGET: "150%" }, "x", 100_000, null), /percentage must be in \(0, 100\)/);
+    assert.throws(() => generationEnvelopeFromEnv({ PLURNK_PROVIDERS_OUTPUT_BUDGET: "-5" }, "x", 100_000, null), /positive integer token count/);
+    assert.throws(() => generationEnvelopeFromEnv({ PLURNK_PROVIDERS_OUTPUT_BUDGET: "100000" }, "x", 100_000, null), /must leave positive input capacity/);
+    assert.throws(() => generationEnvelopeFromEnv({
+        PLURNK_PROVIDERS_OUTPUT_BUDGET: "20%",
+        PLURNK_PROVIDERS_REASONING_BUDGET: "25%",
+    }, "x", 100_000, null), /reasoning is a subset of total output/);
     assert.deepEqual(
-        envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "4096" } as NodeJS.ProcessEnv, "x"),
-        { reasoningReserve: { percent: 0.1 }, completionReserve: { tokens: 4096 } },
+        generationEnvelopeFromEnv({ PLURNK_PROVIDERS_OUTPUT_BUDGET: "1%" }, "x", 2, null),
+        { outputBudget: 1, reasoningBudget: null },
+        "a valid percentage always resolves to at least one whole token",
+    );
+    assert.throws(
+        () => generationEnvelopeFromEnv({ PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%" }, "x", 1, null),
+        /must leave positive input capacity/,
     );
-    assert.throws(() => envelopeFromEnv({ PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%" } as NodeJS.ProcessEnv, "x"), /PLURNK_PROVIDERS_REASONING_RESERVE must be set/);
-    assert.throws(() => envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "150%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%" } as NodeJS.ProcessEnv, "x"), /percentage must be in \(0, 100\)/);
-    assert.throws(() => envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "-5", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%" } as NodeJS.ProcessEnv, "x"), /positive integer token count/);
 });
 
 test("envelope knobs are per-alias scopable (measured envelope per box)", async () => {
-    const { scopeEnvToAlias, envelopeFromEnv } = await import("./env.ts");
+    const { scopeEnvToAlias } = await import("./env.ts");
     const env = {
-        PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
-        PLURNK_PROVIDERS_REASONING_RESERVE_turboderp: "4096", PLURNK_PROVIDERS_COMPLETION_RESERVE_turboderp: "8192",
+        PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%",
+        PLURNK_PROVIDERS_REASONING_BUDGET: "10%",
+        PLURNK_PROVIDERS_OUTPUT_BUDGET_turboderp: "8192",
+        PLURNK_PROVIDERS_REASONING_BUDGET_turboderp: "4096",
     } as NodeJS.ProcessEnv;
-    assert.deepEqual(envelopeFromEnv(scopeEnvToAlias(env, "turboderp"), "x"), { reasoningReserve: { tokens: 4096 }, completionReserve: { tokens: 8192 } });
-    assert.deepEqual(envelopeFromEnv(scopeEnvToAlias(env, "jennifer"), "x"), { reasoningReserve: { percent: 0.1 }, completionReserve: { percent: 0.25 } });
+    assert.deepEqual(generationEnvelopeFromEnv(scopeEnvToAlias(env, "turboderp"), "x", 49_152, null), { outputBudget: 8192, reasoningBudget: 4096 });
+    assert.deepEqual(generationEnvelopeFromEnv(scopeEnvToAlias(env, "jennifer"), "x", 100_000, null), { outputBudget: 35_000, reasoningBudget: 10_000 });
+});
+
+test("retired additive reserve knobs fail rather than creating a dual contract", () => {
+    assert.throws(() => generationEnvelopeFromEnv({
+        PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%",
+        PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
+    }, "x", 100_000, null), /PLURNK_PROVIDERS_REASONING_RESERVE is retired/);
+    assert.throws(() => generationEnvelopeFromEnv({
+        PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%",
+        PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+    }, "x", 100_000, null), /PLURNK_PROVIDERS_COMPLETION_RESERVE is retired/);
 });