@plurnk/plurnk-providers 1.6.0 → 1.7.0

package/src/capacity.ts

@@ -0,0 +1,140 @@
+import type {
+    PromptTokenMeasurement,
+    ProviderRequestCapacity,
+} from "./types.ts";
+import { assertPromptTokenMeasurement } from "./promptTokens.ts";
+
+const positiveOrNull = (value: number | null, name: string): number | null => {
+    if (value === null) return null;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer or null`);
+    }
+    return value;
+};
+
+export const effectiveOutputBudget = ({
+    requested,
+    configured,
+    maxOutputTokens,
+    contextWindow,
+}: {
+    requested?: number;
+    configured: number | null;
+    maxOutputTokens: number | null;
+    contextWindow: number | null;
+}): number | null => {
+    if (requested !== undefined && (!Number.isSafeInteger(requested) || requested <= 0)) {
+        throw new TypeError("maxOutputTokens must be a positive safe integer");
+    }
+    const policies = [requested ?? null, configured].filter((value): value is number => value !== null);
+    if (policies.length === 0) return null;
+    const physical = [
+        positiveOrNull(maxOutputTokens, "maxOutputTokens"),
+        positiveOrNull(contextWindow, "contextWindow"),
+    ].filter((value): value is number => value !== null);
+    return Math.min(...policies, ...physical);
+};
+
+export const effectiveReasoningBudget = ({
+    configured,
+    outputBudget,
+}: {
+    configured: number | null;
+    outputBudget: number | null;
+}): number | null => {
+    positiveOrNull(configured, "reasoningBudget");
+    positiveOrNull(outputBudget, "outputBudget");
+    if (configured === null) return null;
+    if (outputBudget === null) {
+        throw new TypeError("a reasoning budget requires a resolved total output budget");
+    }
+    if (outputBudget < 2) {
+        throw new TypeError("maxOutputTokens must leave at least one token outside the reasoning budget");
+    }
+    return Math.min(configured, outputBudget - 1);
+};
+
+export const effectiveInputCapacity = ({
+    contextWindow,
+    maxInputTokens,
+    outputBudget,
+}: {
+    contextWindow: number | null;
+    maxInputTokens: number | null;
+    outputBudget: number | null;
+}): number | null => {
+    positiveOrNull(contextWindow, "contextWindow");
+    positiveOrNull(maxInputTokens, "maxInputTokens");
+    positiveOrNull(outputBudget, "outputBudget");
+    const combinedCapacity = contextWindow !== null && outputBudget !== null
+        ? contextWindow - outputBudget
+        : null;
+    if (combinedCapacity !== null && combinedCapacity <= 0) {
+        throw new TypeError(
+            `outputBudget (${outputBudget}) must leave positive input capacity inside contextWindow (${contextWindow})`,
+        );
+    }
+    const capacities = [
+        maxInputTokens,
+        combinedCapacity,
+    ].filter((value): value is number => value !== null);
+    return capacities.length === 0 ? null : Math.min(...capacities);
+};
+
+export const requestCapacityDecision = (
+    inputCapacity: number | null,
+    measurement: PromptTokenMeasurement,
+): ProviderRequestCapacity["decision"] => {
+    const prompt = assertPromptTokenMeasurement(measurement, "provider capacity");
+    // An upper bound can prove fit when it is below the limit, but exceeding
+    // the limit proves nothing about the unknown exact count. Estimates never
+    // authorize or reject; the provider remains the capacity oracle.
+    return inputCapacity === null
+        || prompt.kind === "estimate"
+        || prompt.kind === "unavailable"
+        ? "defer"
+        : prompt.tokens <= inputCapacity
+            ? "admit"
+            : prompt.kind === "exact"
+                ? "reject"
+                : "defer";
+};
+
+export const assessRequestCapacity = ({
+    contextWindow,
+    maxInputTokens,
+    maxOutputTokens,
+    outputBudget,
+    reasoningBudget,
+    measurement,
+}: {
+    contextWindow: number | null;
+    maxInputTokens: number | null;
+    maxOutputTokens: number | null;
+    outputBudget: number | null;
+    reasoningBudget: number | null;
+    measurement: PromptTokenMeasurement;
+}): ProviderRequestCapacity => {
+    positiveOrNull(contextWindow, "contextWindow");
+    positiveOrNull(maxInputTokens, "maxInputTokens");
+    positiveOrNull(maxOutputTokens, "maxOutputTokens");
+    positiveOrNull(outputBudget, "outputBudget");
+    positiveOrNull(reasoningBudget, "reasoningBudget");
+    if (reasoningBudget !== null
+        && (outputBudget === null || reasoningBudget >= outputBudget)) {
+        throw new TypeError("reasoningBudget must be a strict subset of outputBudget");
+    }
+    const prompt = assertPromptTokenMeasurement(measurement, "provider capacity");
+    const inputCapacity = effectiveInputCapacity({ contextWindow, maxInputTokens, outputBudget });
+
+    return {
+        decision: requestCapacityDecision(inputCapacity, prompt),
+        contextWindow,
+        maxInputTokens,
+        maxOutputTokens,
+        outputBudget,
+        reasoningBudget,
+        inputCapacity,
+        prompt,
+    };
+};

package/src/catalogProvider.test.ts

@@ -16,8 +16,7 @@ const env = {
     PLURNK_PROVIDERS_TEMPERATURE: "0.2",
     PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15",
     PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0",
-    PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
-    PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+    PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%",
     PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
     PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512",
     PLURNK_PROVIDERS_CACHE_AFFINITY: "1",
@@ -34,18 +33,20 @@ test("catalog provider resolves model physics and Models.dev USD rates", () => {
     assert.notEqual(provider, null);
     assert.equal(provider?.model, "gpt-4.1-mini");
     assert.equal(provider?.contextWindow, 1_047_576);
-    assert.equal(provider?.reasoningReserve, 16_384);
-    assert.equal(provider?.completionReserve, 32_768);
+    assert.equal(provider?.maxInputTokens, null);
+    assert.equal(provider?.maxOutputTokens, 32_768);
+    assert.equal(provider?.outputBudget, 32_768);
+    assert.equal(provider?.reasoningBudget, null);
 });
 
-test("an operator context window caps catalog physics and percentage reserves derive from the cap", () => {
+test("an operator context window caps catalog physics and percentage output policy", () => {
     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);
+    assert.equal(provider?.outputBudget, 32_768, "the model output maximum remains the tighter cap");
+    assert.equal(provider?.reasoningBudget, null);
 
     const oversized = catalogProviderFromEnv("openai", {
         ...env,
@@ -89,7 +90,7 @@ test("official AI SDK provider owns the native request while PLURNK owns call se
     const result = await provider?.generate({
         workerId: "worker",
         messages: [{ role: "user", content: "hello" }],
-        maxTokens: 64,
+        maxOutputTokens: 64,
         sampling: { top_p: 0.8, seed: 7 },
     });
 
@@ -109,6 +110,78 @@ test("official AI SDK provider owns the native request while PLURNK owns call se
     assert.equal(calls[0]?.body.prompt_cache_key, "worker", "the official OpenAI SDK projects the documented affinity key");
 });
 
+test("xAI's native chat contract caps the complete reasoning response", async () => {
+    let call: { headers: Headers; body: Record<string, unknown> } | undefined;
+    mock.method(globalThis, "fetch", async (_input: string | URL | Request, init?: RequestInit) => {
+        call = {
+            headers: new Headers(init?.headers),
+            body: JSON.parse(String(init?.body)) as Record<string, unknown>,
+        };
+        return new Response([
+            `data: ${JSON.stringify({
+                id: "response-xai",
+                object: "chat.completion.chunk",
+                created: 1,
+                model: "grok-build-0.1",
+                choices: [{ index: 0, delta: { reasoning_content: "consider" }, finish_reason: null }],
+            })}`,
+            `data: ${JSON.stringify({
+                id: "response-xai",
+                object: "chat.completion.chunk",
+                created: 2,
+                model: "grok-build-0.1",
+                choices: [{ index: 0, delta: { content: "OK" }, finish_reason: "stop" }],
+            })}`,
+            `data: ${JSON.stringify({
+                id: "response-xai",
+                object: "chat.completion.chunk",
+                created: 3,
+                model: "grok-build-0.1",
+                choices: [],
+                usage: {
+                    prompt_tokens: 5,
+                    completion_tokens: 4,
+                    total_tokens: 9,
+                    prompt_tokens_details: { cached_tokens: 2 },
+                    completion_tokens_details: { reasoning_tokens: 3 },
+                    cost_in_usd_ticks: 1_230_000,
+                },
+            })}`,
+            "data: [DONE]",
+        ].join("\n\n"), { headers: { "content-type": "text/event-stream" } });
+    });
+
+    const provider = catalogProviderFromEnv("xai", {
+        ...env,
+        XAI_API_KEY: "test-key",
+        PLURNK_PROVIDERS_REASONING: "adaptive",
+    }, "grok-build-0.1");
+    const result = await provider?.generate({
+        workerId: "xai-worker",
+        messages: [{ role: "user", content: "hello" }],
+        maxOutputTokens: 16,
+    });
+
+    assert.equal(call?.body.max_completion_tokens, 16);
+    assert.equal("max_tokens" in (call?.body ?? {}), false);
+    assert.equal(call?.headers.get("x-grok-conv-id"), "xai-worker");
+    assert.equal(result?.assistant.reasoning, "consider");
+    assert.equal(result?.assistant.content, "OK");
+    assert.deepEqual(result?.accounting[0]?.usage, {
+        inputTokens: 5,
+        outputTokens: 4,
+        totalTokens: 9,
+        inputTokenDetails: { cacheReadTokens: 2 },
+        outputTokenDetails: { textTokens: 1, reasoningTokens: 3 },
+    });
+    assert.deepEqual(result?.accounting[0]?.cost, {
+        kind: "charged",
+        amount: { amount: "1230000", currency: "USDTICK" },
+        usdEquivalent: "0.000123",
+        source: "xAI response usage.cost_in_usd_ticks",
+    });
+});
+
 test("Cerebras explicit reasoning activation needs no operator effort or token budget", async () => {
     let body: Record<string, unknown> | undefined;
     mock.method(globalThis, "fetch", async (_input: string | URL | Request, init?: RequestInit) => {
@@ -347,7 +420,7 @@ test("Models.dev is the only fallback rate table", async () => {
         `data: ${JSON.stringify({
             id: "response",
             model: "served",
-            choices: [{ delta: { content: "ok" }, finish_reason: "stop" }],
+            choices: [{ index: 0, delta: { content: "ok" }, finish_reason: "stop" }],
         })}`,
         `data: ${JSON.stringify({
             id: "response",

package/src/catalogProvider.ts

@@ -3,7 +3,7 @@ import {
     contextWindowFromEnv,
     effectiveContextWindow,
     dataCaptureFromEnv,
-    envelopeFromEnv,
+    generationEnvelopeFromEnv,
     parseRequiredFloat,
     parseRequiredInt,
     parseTimeoutMs,
@@ -11,8 +11,6 @@ import {
     cacheWritePolicyFromEnv,
     reasoningFromEnv,
     reasoningResponseStyleFromEnv,
-    resolveReserve,
-    type ReserveSpec,
 } from "./env.ts";
 import AiSdkProvider, { type ReasoningStyle } from "./AiSdkProvider.ts";
 import { configuredProviderInfo, createSdkModel } from "./sdkModels.ts";
@@ -55,6 +53,7 @@ export const providerFromSdkModel = ({
     cacheAffinity,
     systemCacheProviderOptions,
     reasoningResponseProviderOptions,
+    additiveReasoningProvider,
 }: {
     name: string;
     env: NodeJS.ProcessEnv;
@@ -69,32 +68,32 @@ export const providerFromSdkModel = ({
     cacheAffinity?: CacheAffinity;
     systemCacheProviderOptions?: AiSdkProviderOptions;
     reasoningResponseProviderOptions?: AiSdkProviderOptions;
+    additiveReasoningProvider?: "anthropic" | "bedrock";
 }): Provider => {
     emitWarningOnce(
-        `${name} provider: request-level prompt counting is a chars/2 estimate; hard context-envelope admission fails closed without exact or bounded evidence`,
+        `${name} provider: request-level prompt counting is a chars/2 estimate; capacity is deferred to the provider`,
         "PLURNK_PROMPT_COUNT_ESTIMATE",
     );
 
-    const reasoning = reasoningFromEnv(env, name);
-    const { reasoningReserve: configuredReasoning, completionReserve: configuredCompletion } = envelopeFromEnv(env, name);
-    const completionReserve: ReserveSpec = "tokens" in configuredCompletion
-        ? configuredCompletion
-        : info?.maxOutput === undefined
-            ? configuredCompletion
-            : { tokens: Math.min(info.maxOutput, Math.round(configuredCompletion.percent * contextWindow)) };
-    const completionTokens = resolveReserve(completionReserve, contextWindow);
-    const reasoningReserve: ReserveSpec = "tokens" in configuredReasoning
-        ? configuredReasoning
-        : reasoning.budget !== null
-            ? { tokens: reasoning.budget }
-            : completionTokens === null
-                ? configuredReasoning
-                : { tokens: Math.round(completionTokens / 2) };
+    const maxInputTokens = info?.maxInputTokens ?? null;
+    const maxOutputTokens = info?.maxOutputTokens === undefined
+        ? null
+        : Math.min(info.maxOutputTokens, contextWindow);
+    const envelope = generationEnvelopeFromEnv(
+        env,
+        name,
+        contextWindow,
+        maxOutputTokens,
+    );
+    const reasoning = reasoningFromEnv(env, name, envelope.reasoningBudget);
 
     const catalogCost = info?.cost;
     const rates = catalogCost === undefined ? null : {
         input: catalogCost.inputPer1M,
         output: catalogCost.outputPer1M,
+        ...(catalogCost.reasoningPer1M === undefined
+            ? {}
+            : { reasoning: catalogCost.reasoningPer1M }),
         ...(catalogCost.cacheReadPer1M === undefined
             ? {}
             : { cacheRead: catalogCost.cacheReadPer1M }),
@@ -115,6 +114,11 @@ export const providerFromSdkModel = ({
         ...(url === undefined ? {} : { url }),
         ...(headers === undefined ? {} : { headers: { ...headers } }),
         contextWindow,
+        maxInputTokens,
+        maxOutputTokens,
+        outputBudget: envelope.outputBudget,
+        reasoningBudget: reasoning.budget,
+        ...(additiveReasoningProvider === undefined ? {} : { additiveReasoningProvider }),
         fetchTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "PLURNK_PROVIDERS_FETCH_TIMEOUT", name),
         operationTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_OPERATION_TIMEOUT, "PLURNK_PROVIDERS_OPERATION_TIMEOUT", name),
         firstContentTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT, "PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT", name),
@@ -124,8 +128,6 @@ export const providerFromSdkModel = ({
         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),
@@ -183,6 +185,7 @@ export const catalogProviderFromEnv = (
         cacheAffinity: sdk.cacheAffinity,
         systemCacheProviderOptions: sdk.systemCacheProviderOptions,
         reasoningResponseProviderOptions: sdk.reasoningResponseProviderOptions,
+        additiveReasoningProvider: sdk.additiveReasoningProvider,
         contextWindow,
         info,
     });

package/src/compatibleProvider.test.ts

@@ -12,8 +12,7 @@ const env = {
     PLURNK_PROVIDERS_TEMPERATURE: "0.2",
     PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15",
     PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0",
-    PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
-    PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+    PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%",
     PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
     PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512",
     PLURNK_PROVIDERS_PROBE_ATTEMPTS: "1",

package/src/compatibleProvider.ts

@@ -3,7 +3,7 @@ import {
     contextWindowFromEnv,
     effectiveContextWindow,
     dataCaptureFromEnv,
-    envelopeFromEnv,
+    generationEnvelopeFromEnv,
     parseOptionalFloat,
     parseOptionalInt,
     parseRequiredFloat,
@@ -176,21 +176,26 @@ export const compatibleProviderFromEnv = async (
 
     if (!llamaServer) {
         emitWarningOnce(
-            `${provider} provider: request-level prompt counting is a chars/2 estimate; hard context-envelope admission fails closed without exact or bounded evidence`,
+            `${provider} provider: request-level prompt counting is a chars/2 estimate; capacity is deferred to the provider`,
             "PLURNK_PROMPT_COUNT_ESTIMATE",
         );
     }
-    const { reasoningReserve, completionReserve } = envelopeFromEnv(env, provider);
+    const envelope = generationEnvelopeFromEnv(env, provider, contextWindow, null);
+    const reasoning = reasoningFromEnv(env, provider, envelope.reasoningBudget);
     return new AiSdkProvider({
         model,
         url,
         headers,
         contextWindow,
+        maxInputTokens: null,
+        maxOutputTokens: null,
+        outputBudget: envelope.outputBudget,
+        reasoningBudget: reasoning.budget,
         fetchTimeoutMs: timeout,
         operationTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_OPERATION_TIMEOUT, "PLURNK_PROVIDERS_OPERATION_TIMEOUT", provider),
         firstContentTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT, "PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT", provider),
         streamIdleTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", provider),
-        reasoning: reasoningFromEnv(env, provider),
+        reasoning,
         reasoningResponseStyle: reasoningResponseStyleFromEnv(env, provider),
         reasoningStyle,
         temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", provider, 0),
@@ -200,8 +205,6 @@ export const compatibleProviderFromEnv = async (
         dryBase: parseOptionalFloat(env.PLURNK_PROVIDERS_DRY_BASE, "PLURNK_PROVIDERS_DRY_BASE", provider, 0) ?? undefined,
         dryAllowedLength: parseOptionalInt(env.PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH, "PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH", provider) ?? undefined,
         repeatLastN: parseOptionalInt(env.PLURNK_PROVIDERS_REPEAT_LAST_N, "PLURNK_PROVIDERS_REPEAT_LAST_N", provider) ?? undefined,
-        reasoningReserve,
-        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),
@@ -222,6 +225,6 @@ export const compatibleProviderFromEnv = async (
         tokenizeUrl,
         promptTokensUrl,
         servedModel: probe.servedModel ?? undefined,
-        requiresMaxTokens: llamaServer || undefined,
+        requiresOutputBudget: llamaServer || undefined,
     });
 };

package/src/cost.test.ts

@@ -54,6 +54,37 @@ test("a distinct cache rate requires the applicable token category", () => {
     );
 });
 
+test("a distinct reasoning rate prices reasoning as a subset of output", () => {
+    const withReasoning: ProviderUsage = {
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+        outputTokenDetails: { reasoningTokens: 20 },
+    };
+    assert.deepEqual(
+        estimateProviderCost(withReasoning, {
+            input: 1,
+            output: 2,
+            reasoning: 5,
+        }, "Models.dev"),
+        {
+            kind: "estimated",
+            amount: { amount: "0.00026", currency: "USD" },
+            source: "Models.dev",
+        },
+    );
+});
+
+test("a distinct reasoning rate requires reported reasoning usage", () => {
+    assert.deepEqual(
+        estimateProviderCost(usage, { input: 1, output: 2, reasoning: 5 }, "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([

package/src/env.test.ts

@@ -3,6 +3,7 @@ import { strict as assert } from "node:assert";
 import {
     cacheAffinityFromEnv,
     cacheWritePolicyFromEnv,
+    generationEnvelopeFromEnv,
     parseRequiredInt,
     parseOptionalInt,
     parseTimeoutMs,
@@ -51,11 +52,10 @@ test("reasoningFromEnv: activation is independent from an optional explicit budg
     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.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", 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", () => {
@@ -112,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");
@@ -120,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
 });
 
@@ -171,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");
@@ -241,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(
-        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: "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(
+        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/);
 });