@plurnk/plurnk-providers 1.6.0 → 1.7.0

package/src/Mock.ts

@@ -5,10 +5,11 @@
 // Provider contract. Production providers don't expose the `ops` escape
 // hatch — that's an intg-only convenience.
 
-import type { ChatMessage, FinishReason, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderAssistant, ProviderCost, ProviderEncryptedReasoningItem, ProviderRequestAccounting, ProviderResponse, ProviderUsage } from "./types.ts";
-import { resolveEnvelopeFromEnv } from "./env.ts";
+import type { ChatMessage, FinishReason, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderAssistant, ProviderCost, ProviderEncryptedReasoningItem, ProviderRequestAccounting, ProviderRequestCapacity, ProviderResponse, ProviderUsage } from "./types.ts";
+import { resolveGenerationEnvelopeFromEnv } from "./env.ts";
 import { validateProviderRequestAccounting } from "./accounting.ts";
 import { ProviderError } from "./errors.ts";
+import { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget } from "./capacity.ts";
 
 export type MockAssistant = {
     content: string;
@@ -46,29 +47,35 @@ type MockGenerateArgs = Omit<Parameters<Provider["generate"]>[0], "workerId"> &
 
 export default class Mock implements Provider {
     #contextWindow: number | null;
-    #reasoningReserve: number | null;
-    #completionReserve: number | null;
+    #outputBudget: number | null;
+    #reasoningBudget: number | null;
     #queue: MockResponse[];
 
-    // {§provider-generation-envelope} Reserves resolve the same way a real
-    // provider's do — the tolerant env read (the service's partition/budget
-    // suite sets PLURNK_PROVIDERS_*_RESERVE
-    // and Mock reflects it, resolved against contextWindow). Tolerant, NOT the
-    // fail-hard envelopeFromEnv: Mock is the universal fixture, constructed
-    // without the reserves in most base tests, so absent env → null → the
-    // consumer's no-cap path, and the ~100 `new Mock({ contextWindow, responses })`
-    // sites stay untouched. Mock has no alias identity, so it reads the BARE knobs.
+    // {§provider-generation-envelope} Mock resolves the same generation
+    // envelope as a real provider, but tolerates absent policy because it is
+    // also the universal test fixture. No output budget means its context
+    // window alone cannot determine an input capacity. Mock has no alias
+    // identity, so it reads the bare knobs.
     constructor({ contextWindow, responses }: { contextWindow: number | null; responses: MockResponse[] }) {
         this.#contextWindow = contextWindow;
-        const env = resolveEnvelopeFromEnv(process.env, contextWindow);
-        this.#reasoningReserve = env.reasoningReserve;
-        this.#completionReserve = env.completionReserve;
+        const envelope = resolveGenerationEnvelopeFromEnv(process.env, contextWindow);
+        this.#outputBudget = envelope.outputBudget;
+        this.#reasoningBudget = envelope.reasoningBudget;
         this.#queue = [...responses];
     }
 
     get contextWindow(): number | null { return this.#contextWindow; }
-    get reasoningReserve(): number | null { return this.#reasoningReserve; }
-    get completionReserve(): number | null { return this.#completionReserve; }
+    get maxInputTokens(): number | null { return null; }
+    get maxOutputTokens(): number | null { return null; }
+    get outputBudget(): number | null { return this.#outputBudget; }
+    get reasoningBudget(): number | null { return this.#reasoningBudget; }
+    get inputCapacity(): number | null {
+        return effectiveInputCapacity({
+            contextWindow: this.#contextWindow,
+            maxInputTokens: this.maxInputTokens,
+            outputBudget: this.#outputBudget,
+        });
+    }
     get model(): string { return "mock"; }
 
     // Mock's deliberately simple vocabulary defines each two content code units
@@ -82,11 +89,42 @@ export default class Mock implements Provider {
         };
     }
 
-    async generate({ signal, grammar, observeRequest }: MockGenerateArgs): Promise<MockReturnedResponse> {
+    async assessRequestCapacity(
+        messages: readonly ChatMessage[],
+        maxOutputTokens?: number,
+    ): Promise<ProviderRequestCapacity> {
+        const outputBudget = effectiveOutputBudget({
+            requested: maxOutputTokens,
+            configured: this.#outputBudget,
+            maxOutputTokens: null,
+            contextWindow: this.#contextWindow,
+        });
+        const reasoningBudget = effectiveReasoningBudget({
+            configured: this.#reasoningBudget,
+            outputBudget,
+        });
+        return assessRequestCapacity({
+            contextWindow: this.#contextWindow,
+            maxInputTokens: null,
+            maxOutputTokens: null,
+            outputBudget,
+            reasoningBudget,
+            measurement: await this.countPromptTokens(messages),
+        });
+    }
+
+    async generate({ messages, maxOutputTokens, signal, grammar, observeRequest }: MockGenerateArgs): Promise<MockReturnedResponse> {
         // Honor abort before consuming the queue — an aborted call makes no
         // "wire call" and must not exhaust a queued response
         // ({§provider-failure-normalization}).
         signal?.throwIfAborted();
+        const capacity = await this.assessRequestCapacity(messages, maxOutputTokens);
+        if (capacity.decision === "reject") {
+            throw new ProviderError("mock", "capacity_exceeded", "Mock request exceeds its exact input capacity.", {
+                capacity,
+                extensions: { capacityStage: "preflight", capacity },
+            });
+        }
         const settle = await observeRequest?.({ provider: "provider:mock", model: this.model });
         const next = this.#queue.shift();
         if (next === undefined) {
@@ -101,7 +139,7 @@ export default class Mock implements Provider {
                 "mock",
                 "invalid_response",
                 "Mock provider exhausted: no more queued responses",
-                { accounting: [accounting] },
+                { accounting: [accounting], capacity },
             );
         }
         const a = next.assistant;
@@ -137,6 +175,7 @@ export default class Mock implements Provider {
             assistant,
             assistantRaw: next.assistantRaw ?? null,
             accounting: [requestAccounting],
+            capacity,
             ...(grammarEvidence !== undefined ? { grammarEvidence } : {}),
         };
     }

package/src/Pool.test.ts

@@ -4,6 +4,7 @@ import Pool from "./Pool.ts";
 import { ProviderError } from "./errors.ts";
 import type { PromptTokenMeasurement, Provider, ProviderResponse } from "./types.ts";
 import { resetEmittedWarnings } from "./warnings.ts";
+import { effectiveInputCapacity } from "./capacity.ts";
 
 test.afterEach(() => { resetEmittedWarnings(); });
 
@@ -22,12 +23,23 @@ const RESP: ProviderResponse = {
         usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
         cost: { kind: "unknown", reason: "test fixture has no cost" },
     }],
+    capacity: {
+        decision: "admit",
+        contextWindow: 48_000,
+        maxInputTokens: null,
+        maxOutputTokens: null,
+        outputBudget: 12_000,
+        reasoningBudget: null,
+        inputCapacity: 36_000,
+        prompt: { kind: "exact", tokens: 0, source: "test:exact" },
+    },
 };
 
 type FakeOpts = {
     model?: string; window?: number | null; servedModel?: string;
-    constrainsOutput?: boolean; requiresMaxTokens?: boolean;
-    reasoningReserve?: number | null; completionReserve?: number | null;
+    constrainsOutput?: boolean; requiresOutputBudget?: boolean;
+    maxInputTokens?: number | null; maxOutputTokens?: number | null;
+    outputBudget?: number | null; reasoningBudget?: number | null;
     tokenize?: boolean; throws?: Error;
     promptMeasurement?: PromptTokenMeasurement;
 };
@@ -37,17 +49,38 @@ const backend = (opts: FakeOpts = {}) => {
     const b: Provider = {
         model: opts.model ?? "gemma",
         contextWindow: opts.window === undefined ? 48000 : opts.window,
+        maxInputTokens: opts.maxInputTokens ?? null,
+        maxOutputTokens: opts.maxOutputTokens ?? null,
+        outputBudget: opts.outputBudget ?? null,
+        reasoningBudget: opts.reasoningBudget ?? null,
+        inputCapacity: effectiveInputCapacity({
+            contextWindow: opts.window === undefined ? 48_000 : opts.window,
+            maxInputTokens: opts.maxInputTokens ?? null,
+            outputBudget: opts.outputBudget ?? null,
+        }),
         ...(opts.servedModel !== undefined ? { servedModel: opts.servedModel } : {}),
         ...(opts.constrainsOutput !== undefined ? { constrainsOutput: opts.constrainsOutput } : {}),
-        ...(opts.requiresMaxTokens !== undefined ? { requiresMaxTokens: opts.requiresMaxTokens } : {}),
-        ...(opts.reasoningReserve !== undefined ? { reasoningReserve: opts.reasoningReserve } : {}),
-        ...(opts.completionReserve !== undefined ? { completionReserve: opts.completionReserve } : {}),
+        ...(opts.requiresOutputBudget !== undefined ? { requiresOutputBudget: opts.requiresOutputBudget } : {}),
         ...(opts.tokenize ? { tokenize: async (t: string) => [t.length] } : {}),
         countPromptTokens: async (messages) => opts.promptMeasurement ?? ({
             kind: "exact",
             tokens: messages.reduce((sum, { content }) => sum + content.length, 0),
             source: "test:exact",
         }),
+        assessRequestCapacity: async (messages, maxOutputTokens) => ({
+            decision: "admit",
+            contextWindow: opts.window === undefined ? 48_000 : opts.window,
+            maxInputTokens: opts.maxInputTokens ?? null,
+            maxOutputTokens: opts.maxOutputTokens ?? null,
+            outputBudget: maxOutputTokens ?? opts.outputBudget ?? null,
+            reasoningBudget: opts.reasoningBudget ?? null,
+            inputCapacity: null,
+            prompt: opts.promptMeasurement ?? {
+                kind: "exact",
+                tokens: messages.reduce((sum, { content }) => sum + content.length, 0),
+                source: "test:exact",
+            },
+        }),
         generate: async (args: Parameters<Provider["generate"]>[0]): Promise<ProviderResponse> => {
             served.push(args.workerId);
             if (opts.throws !== undefined) throw opts.throws;
@@ -82,20 +115,22 @@ test("Pool: any unknown (null) window makes the pool null - no improvised cap",
     assert.equal(new Pool([backend({ window: 48000 }).b, backend({ window: null }).b]).contextWindow, null);
 });
 
-test("Pool: reserves travel with the floor window", () => {
-    const big = backend({ window: 48000, reasoningReserve: 4800, completionReserve: 12000 }).b;
-    const small = backend({ window: 32000, reasoningReserve: 3200, completionReserve: 8000 }).b;
+test("Pool: physical limits and budgets aggregate to independent safe floors", () => {
+    const big = backend({ window: 48000, maxInputTokens: 40_000, maxOutputTokens: 16_000, outputBudget: 12_000, reasoningBudget: 4_800 }).b;
+    const small = backend({ window: 32000, maxInputTokens: 24_000, maxOutputTokens: 12_000, outputBudget: 8_000, reasoningBudget: 3_200 }).b;
     const p = new Pool([big, small]);
     assert.equal(p.contextWindow, 32000);
-    assert.equal(p.reasoningReserve, 3200);   // the floor backend's, not the larger one's
-    assert.equal(p.completionReserve, 8000);
+    assert.equal(p.maxInputTokens, 24_000);
+    assert.equal(p.maxOutputTokens, 12_000);
+    assert.equal(p.outputBudget, 8_000);
+    assert.equal(p.reasoningBudget, 3_200);
 });
 
-test("Pool: capabilities aggregate conservatively (constrainsOutput all-true, requiresMaxTokens any-true)", () => {
+test("Pool: capabilities aggregate conservatively (constrainsOutput all-true, requiresOutputBudget any-true)", () => {
     assert.equal(new Pool([backend({ constrainsOutput: true }).b, backend({ constrainsOutput: true }).b]).constrainsOutput, true);
     assert.equal(new Pool([backend({ constrainsOutput: true }).b, backend({ constrainsOutput: false }).b]).constrainsOutput, undefined);
-    assert.equal(new Pool([backend({ requiresMaxTokens: false }).b, backend({ requiresMaxTokens: true }).b]).requiresMaxTokens, true);
-    assert.equal(new Pool([backend({}).b]).requiresMaxTokens, undefined);
+    assert.equal(new Pool([backend({ requiresOutputBudget: false }).b, backend({ requiresOutputBudget: true }).b]).requiresOutputBudget, true);
+    assert.equal(new Pool([backend({}).b]).requiresOutputBudget, undefined);
 });
 
 test("Pool: servedModel is the common id, undefined when they differ", () => {
@@ -131,6 +166,29 @@ test("Pool: prompt evidence is conservative across every routable backend", asyn
         source: "pool:test:a,heuristic:chars2",
         detail: "at least one interchangeable backend has only an estimate: unknown framing",
     });
+
+    const unavailable = backend({ promptMeasurement: {
+        kind: "unavailable", source: "test:none", detail: "counter offline",
+    } }).b;
+    assert.deepEqual(await new Pool([exact, unavailable]).countPromptTokens([]), {
+        kind: "unavailable",
+        source: "pool:test:a,test:none",
+        detail: "at least one interchangeable backend cannot measure the request: counter offline",
+    });
+});
+
+test("Pool: request capacity uses the smallest complete backend envelope", async () => {
+    const prompt = { kind: "exact", tokens: 11, source: "test:exact" } as const;
+    const narrowInput = backend({ window: 100, outputBudget: 90, promptMeasurement: prompt }).b;
+    const narrowContext = backend({ window: 50, outputBudget: 10, promptMeasurement: prompt }).b;
+    const pool = new Pool([narrowInput, narrowContext]);
+
+    assert.equal(pool.inputCapacity, 10);
+    const capacity = await pool.assessRequestCapacity([]);
+    assert.equal(capacity.contextWindow, 50);
+    assert.equal(capacity.outputBudget, 10);
+    assert.equal(capacity.inputCapacity, 10, "independent minima do not synthesize a nonexistent 40-token envelope");
+    assert.equal(capacity.decision, "reject");
 });
 
 // --- dispatch: round-robin + affinity ---

package/src/Pool.ts

@@ -1,4 +1,4 @@
-import type { Provider, ProviderRequestAccounting, ProviderResponse, ChatMessage, PromptTokenMeasurement } from "./types.ts";
+import type { Provider, ProviderRequestAccounting, ProviderRequestCapacity, ProviderResponse, ChatMessage, PromptTokenMeasurement } from "./types.ts";
 import { ProviderError, type ProviderErrorKind } from "./errors.ts";
 import { emitWarningOnce } from "./warnings.ts";
 import { assertPromptTokenMeasurement } from "./promptTokens.ts";
@@ -6,6 +6,7 @@ import Meta, {
     type PluginAttribution,
     type PluginAttributionContext,
 } from "@plurnk/plurnk-meta";
+import { effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget, requestCapacityDecision } from "./capacity.ts";
 
 // A backend-AVAILABILITY failure: the sub-provider already exhausted its OWN
 // transient retries before throwing one of these, so re-hitting the same
@@ -33,7 +34,7 @@ export default class Pool implements Provider {
     readonly #affinity = new Map<string, number>(); // workerId -> backend index; sticky, LRU-bounded
     readonly #cap: number;                            // LRU ceiling on the affinity map
     #next = 0;                                        // round-robin cursor for NEW workers
-    readonly #floor: Provider;                        // the min-window backend: the safe budget floor
+    readonly #floor: Provider;                        // the min-window backend: the safe context floor
 
     // Optional exact tokenizer: present iff every backend exposes one (same
     // vocab, since interchangeable). Delegated; absent when the fleet can't.
@@ -52,9 +53,9 @@ export default class Pool implements Provider {
         this.#cap = backends.length * 8;
 
         // The exposed window is the SAFE FLOOR across backends (a packet that fits the
-        // smallest fits all); its reserves travel with it so the budget stays
-        // self-consistent. ANY unknown (null) window makes the pool null - a worker
-        // might route to it, and the consumer must not improvise a cap
+        // smallest fits all). Every other capacity fact aggregates independently
+        // below. ANY unknown (null) window makes the pool null - a worker might
+        // route to it, and the consumer must not improvise a cap
         // ({§model-fact-resolution}).
         const anyUnknown = backends.find((b) => b.contextWindow === null);
         this.#floor = anyUnknown ?? backends.reduce((lo, b) => (b.contextWindow! < lo.contextWindow! ? b : lo));
@@ -78,12 +79,21 @@ export default class Pool implements Provider {
 
     get model(): string { return this.#backends[0].model; }
     get contextWindow(): number | null { return this.#floor.contextWindow; }
-    get reasoningReserve(): number | null | undefined { return this.#floor.reasoningReserve; }
-    get completionReserve(): number | null | undefined { return this.#floor.completionReserve; }
+    #minimumKnown(project: (provider: Provider) => number | null): number | null {
+        const values = this.#backends.map(project);
+        return values.some((value) => value === null)
+            ? null
+            : Math.min(...values as number[]);
+    }
+    get maxInputTokens(): number | null { return this.#minimumKnown((provider) => provider.maxInputTokens); }
+    get maxOutputTokens(): number | null { return this.#minimumKnown((provider) => provider.maxOutputTokens); }
+    get outputBudget(): number | null { return this.#minimumKnown((provider) => provider.outputBudget); }
+    get reasoningBudget(): number | null { return this.#minimumKnown((provider) => provider.reasoningBudget); }
+    get inputCapacity(): number | null { return this.#minimumKnown((provider) => provider.inputCapacity); }
 
     // Served id / capabilities aggregate CONSERVATIVELY: a worker could land on any
     // backend, so claim `constrainsOutput` only if EVERY backend does, and
-    // `requiresMaxTokens` if ANY does (bring a cap if even one backend needs it).
+    // `requiresOutputBudget` if ANY does (bring a cap if even one backend needs it).
     get servedModel(): string | undefined {
         const s = this.#backends[0].servedModel;
         return this.#backends.every((b) => b.servedModel === s) ? s : undefined;
@@ -91,8 +101,8 @@ export default class Pool implements Provider {
     get constrainsOutput(): boolean | undefined {
         return this.#backends.every((b) => b.constrainsOutput === true) ? true : undefined;
     }
-    get requiresMaxTokens(): boolean | undefined {
-        return this.#backends.some((b) => b.requiresMaxTokens === true) ? true : undefined;
+    get requiresOutputBudget(): boolean | undefined {
+        return this.#backends.some((b) => b.requiresOutputBudget === true) ? true : undefined;
     }
 
     async countPromptTokens(
@@ -104,8 +114,20 @@ export default class Pool implements Provider {
                 await backend.countPromptTokens(messages, signal),
                 `Pool backend ${backend.model}`,
             )));
-        const tokens = Math.max(...measurements.map((measurement) => measurement.tokens));
         const sources = [...new Set(measurements.map(({ source }) => source))].join(",");
+        const unavailable = measurements.find((measurement) => measurement.kind === "unavailable");
+        if (unavailable?.kind === "unavailable") {
+            return {
+                kind: "unavailable",
+                source: `pool:${sources}`,
+                detail: `at least one interchangeable backend cannot measure the request: ${unavailable.detail}`,
+            };
+        }
+        const available = measurements.filter(
+            (measurement): measurement is Exclude<PromptTokenMeasurement, { readonly kind: "unavailable" }> =>
+                measurement.kind !== "unavailable",
+        );
+        const tokens = Math.max(...available.map((measurement) => measurement.tokens));
         const estimate = measurements.find((measurement) => measurement.kind === "estimate");
         if (estimate?.kind === "estimate") {
             return {
@@ -115,14 +137,57 @@ export default class Pool implements Provider {
                 detail: `at least one interchangeable backend has only an estimate: ${estimate.detail}`,
             };
         }
-        const exact = measurements.every((measurement) => measurement.kind === "exact")
-            && measurements.every((measurement) => measurement.tokens === tokens);
+        const exact = available.every((measurement) => measurement.kind === "exact")
+            && available.every((measurement) => measurement.tokens === tokens);
         return {
             kind: exact ? "exact" : "upper_bound",
             tokens,
             source: `pool:${sources}`,
         };
     }
+
+    async assessRequestCapacity(
+        messages: readonly ChatMessage[],
+        maxOutputTokens?: number,
+        signal?: AbortSignal,
+    ): Promise<ProviderRequestCapacity> {
+        const envelopes = this.#backends.map((provider) => {
+            const outputBudget = effectiveOutputBudget({
+                requested: maxOutputTokens,
+                configured: provider.outputBudget,
+                maxOutputTokens: provider.maxOutputTokens,
+                contextWindow: provider.contextWindow,
+            });
+            return {
+                outputBudget,
+                reasoningBudget: effectiveReasoningBudget({
+                    configured: provider.reasoningBudget,
+                    outputBudget,
+                }),
+                inputCapacity: effectiveInputCapacity({
+                    contextWindow: provider.contextWindow,
+                    maxInputTokens: provider.maxInputTokens,
+                    outputBudget,
+                }),
+            };
+        });
+        const minimum = (values: readonly (number | null)[]): number | null =>
+            values.some((value) => value === null)
+                ? null
+                : Math.min(...values as number[]);
+        const measurement = await this.countPromptTokens(messages, signal);
+        const inputCapacity = minimum(envelopes.map((envelope) => envelope.inputCapacity));
+        return {
+            decision: requestCapacityDecision(inputCapacity, measurement),
+            contextWindow: this.contextWindow,
+            maxInputTokens: this.maxInputTokens,
+            maxOutputTokens: this.maxOutputTokens,
+            outputBudget: minimum(envelopes.map((envelope) => envelope.outputBudget)),
+            reasoningBudget: minimum(envelopes.map((envelope) => envelope.reasoningBudget)),
+            inputCapacity,
+            prompt: measurement,
+        };
+    }
     // --- dispatch ---
 
     async generate(args: Parameters<Provider["generate"]>[0]): Promise<ProviderResponse> {

package/src/ProviderRegistry.test.ts

@@ -17,7 +17,7 @@ const fullEnv = Object.freeze({
     PLURNK_PROVIDERS_OPERATION_TIMEOUT: "2700000",
     PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT: "600000",
     PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT: "0",
-    PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0", PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512", PLURNK_PROVIDERS_CACHE_AFFINITY: "1", PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "stable-system",
+    PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_OUTPUT_BUDGET: "35%", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0", PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512", PLURNK_PROVIDERS_CACHE_AFFINITY: "1", PLURNK_PROVIDERS_CACHE_WRITE_POLICY: "stable-system",
     OPENAI_BASE_URL: "http://x",
 });
 

package/src/accounting.ts

@@ -1,7 +1,6 @@
 import type {
     ChargedCost,
     ProviderAccounting,
-    ProviderCost,
     ProviderCostNormalizer,
     ProviderRequestAccounting,
     ProviderUsage,

package/src/accountingPublic.ts

@@ -0,0 +1,9 @@
+export { aggregateProviderAccounting } from "./accounting.ts";
+export { estimateProviderCost } from "./cost.ts";
+export type {
+    ProviderAccounting,
+    ProviderCost,
+    ProviderRequestAccounting,
+    ProviderUsage,
+} from "./types.ts";
+export type { TokenRates } from "./usage.ts";

package/src/boundaries.test.ts

@@ -26,32 +26,45 @@ test("provider source does not import the PLURNK parser", () => {
     }
 });
 
+const assertRuntimeNeutralGraph = (entrypoint: string, allowed: ReadonlySet<string>): void => {
+    const pending = [entrypoint];
+    const visited = new Set<string>();
+    while (pending.length > 0) {
+        const file = pending.pop()!;
+        if (visited.has(file)) continue;
+        visited.add(file);
+        assert.ok(allowed.has(file), `${entrypoint} reaches ${file}`);
+        const source = readFileSync(join(root, file), "utf8");
+        assert.doesNotMatch(source, /from\s+["']node:/, `${file} imports a Node built-in`);
+        for (const match of source.matchAll(/from\s+["']\.\/([^"']+)\.ts["']/g)) {
+            pending.push(`${match[1]}.ts`);
+        }
+    }
+};
+
 test("the OpenAI-compatible entrypoint excludes Node-owned provider machinery", () => {
-    const allowed = new Set([
+    assertRuntimeNeutralGraph("openai.ts", new Set([
         "accounting.ts",
         "AiSdkProvider.ts",
         "aiSdkTransport.ts",
+        "capacity.ts",
         "cost.ts",
         "env.ts",
         "errors.ts",
         "notices.ts",
         "openai.ts",
         "promptTokens.ts",
+        "providerError.ts",
         "types.ts",
         "usage.ts",
         "warnings.ts",
-    ]);
-    const pending = ["openai.ts"];
-    const visited = new Set<string>();
-    while (pending.length > 0) {
-        const file = pending.pop()!;
-        if (visited.has(file)) continue;
-        visited.add(file);
-        assert.ok(allowed.has(file), `runtime-neutral entrypoint reaches ${file}`);
-        const source = readFileSync(join(root, file), "utf8");
-        assert.doesNotMatch(source, /from\s+["']node:/, `${file} imports a Node built-in`);
-        for (const match of source.matchAll(/from\s+["']\.\/([^"']+)\.ts["']/g)) {
-            pending.push(`${match[1]}.ts`);
-        }
-    }
+    ]));
+});
+
+test("the normalized-error entrypoint excludes transport and Node machinery", () => {
+    assertRuntimeNeutralGraph("providerError.ts", new Set([
+        "notices.ts",
+        "providerError.ts",
+        "types.ts",
+    ]));
 });

package/src/capacity.test.ts

@@ -0,0 +1,92 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, effectiveReasoningBudget } from "./capacity.ts";
+
+test("effective output budget is caller-tightenable and physically capped", () => {
+    assert.equal(effectiveOutputBudget({
+        requested: undefined,
+        configured: 40_000,
+        maxOutputTokens: 32_000,
+        contextWindow: 128_000,
+    }), 32_000);
+    assert.equal(effectiveOutputBudget({
+        requested: 8_000,
+        configured: 40_000,
+        maxOutputTokens: 32_000,
+        contextWindow: 128_000,
+    }), 8_000);
+});
+
+test("call-specific output tightening also tightens its reasoning subset", () => {
+    assert.equal(effectiveReasoningBudget({ configured: 8_000, outputBudget: 4_000 }), 3_999);
+    assert.equal(effectiveReasoningBudget({ configured: 2_000, outputBudget: 4_000 }), 2_000);
+    assert.equal(effectiveReasoningBudget({ configured: null, outputBudget: 1 }), null);
+    assert.throws(
+        () => effectiveReasoningBudget({ configured: 1, outputBudget: 1 }),
+        /leave at least one token outside the reasoning budget/,
+    );
+});
+
+test("capacity applies independent input and combined-context limits", () => {
+    assert.equal(effectiveInputCapacity({
+        contextWindow: 100_000,
+        maxInputTokens: 70_000,
+        outputBudget: 20_000,
+    }), 70_000);
+    const capacity = assessRequestCapacity({
+        contextWindow: 100_000,
+        maxInputTokens: 70_000,
+        maxOutputTokens: 40_000,
+        outputBudget: 20_000,
+        reasoningBudget: null,
+        measurement: { kind: "exact", tokens: 70_001, source: "fixture" },
+    });
+    assert.equal(capacity.inputCapacity, 70_000);
+    assert.equal(capacity.decision, "reject");
+});
+
+test("a known combined context must leave positive input capacity", () => {
+    assert.equal(effectiveInputCapacity({
+        contextWindow: 2,
+        maxInputTokens: null,
+        outputBudget: 1,
+    }), 1);
+    assert.throws(
+        () => effectiveInputCapacity({
+            contextWindow: 1,
+            maxInputTokens: null,
+            outputBudget: 1,
+        }),
+        /must leave positive input capacity/,
+    );
+});
+
+test("only exact overflow rejects before provider I/O", () => {
+    const base = {
+        contextWindow: 100,
+        maxInputTokens: null,
+        maxOutputTokens: 40,
+        outputBudget: 40,
+        reasoningBudget: null,
+    } as const;
+    assert.equal(assessRequestCapacity({
+        ...base,
+        measurement: { kind: "exact", tokens: 61, source: "exact" },
+    }).decision, "reject");
+    assert.equal(assessRequestCapacity({
+        ...base,
+        measurement: { kind: "upper_bound", tokens: 61, source: "bound" },
+    }).decision, "defer");
+    assert.equal(assessRequestCapacity({
+        ...base,
+        measurement: { kind: "estimate", tokens: 61, source: "estimate", detail: "heuristic" },
+    }).decision, "defer");
+    assert.equal(assessRequestCapacity({
+        ...base,
+        measurement: { kind: "unavailable", source: "fixture", detail: "no request tokenizer" },
+    }).decision, "defer");
+    assert.equal(assessRequestCapacity({
+        ...base,
+        measurement: { kind: "upper_bound", tokens: 60, source: "bound" },
+    }).decision, "admit");
+});