@plurnk/plurnk-providers 1.5.0 → 1.6.1

package/SPEC.md

@@ -9,8 +9,8 @@ ordinary provider protocols.
 The provider stack has four owners:
 
 1. Models.dev supplies a release-time snapshot of provider package, API
-   endpoint, credential names, models, context windows, output limits,
-   reasoning capability, and USD prices.
+   endpoint, credential names, models, context/input/output limits, reasoning
+   capability, and USD rates including distinct reasoning rates when supplied.
 2. Official AI SDK providers own vendor request and response protocols.
 3. This package owns the PLURNK contract: aliases, envelopes, normalized usage
    and errors, evidence, local capabilities, and first-party metadata.
@@ -22,6 +22,14 @@ model prefix, context window, price, or vendor request shape into a PLURNK
 table. A missing or wrong catalog fact is fixed upstream, overridden through a
 provider declaration, or left explicitly unknown.
 
+§provider-runtime-neutral-accounting The public
+`@plurnk/plurnk-providers/accounting` subpath exposes provider-request
+aggregation and Models.dev cost estimation, plus their wire types, without
+evaluating Node-only provider discovery, filesystem defaults, or runtime
+construction. It re-exports the package's sole accounting implementation. The
+package root remains the Node provider-runtime composition surface and is not a
+Worker entrypoint.
+
 ## §2 Provider interface
 
 §provider-interface `Provider` exposes immutable model facts and one generation
@@ -31,88 +39,139 @@ operation:
 interface Provider {
   readonly model: string;
   readonly contextWindow: number | null;
+  readonly maxInputTokens: number | null;
+  readonly maxOutputTokens: number | null;
+  readonly outputBudget: number | null;
+  readonly reasoningBudget: number | null;
+  readonly inputCapacity: number | null;
   readonly servedModel?: string;
   readonly constrainsOutput?: boolean;
-  readonly requiresMaxTokens?: boolean;
-  readonly reasoningReserve?: number | null;
-  readonly completionReserve?: number | null;
+  readonly requiresOutputBudget?: boolean;
 
   countPromptTokens(
     messages: readonly ChatMessage[],
     signal?: AbortSignal,
   ): Promise<PromptTokenMeasurement>;
+  assessRequestCapacity(
+    messages: readonly ChatMessage[],
+    maxOutputTokens?: number,
+    signal?: AbortSignal,
+  ): Promise<ProviderRequestCapacity>;
   tokenize?(text: string): Promise<number[]>;
-  calculateCost(usage: ProviderUsage): number;
-  calculateCharge?(usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }>;
   generate(args: GenerateArgs): Promise<ProviderResponse>;
 }
 ```
 
-`contextWindow` is provider physics and resolves under
-{§model-fact-resolution}. `null` means genuinely unknown; a consumer MUST NOT
-invent a stand-in. The context-window knob never carries model-facing prompt
-policy or grinder pressure.
+`contextWindow` is the effective total context envelope resolved under
+{§model-fact-resolution}: the minimum of known model capacity and any stricter
+operator cap. `null` means genuinely unknown; a consumer MUST NOT invent a
+stand-in. The context-window knob is a hard cap, never model-facing grinder
+pressure.
 
-`PromptTokenMeasurement` is a discriminated request-level result:
+§provider-prompt-measurement `PromptTokenMeasurement` is a discriminated
+request-level result:
 
-| `kind`        | Meaning                                                | May authorize physical admission |
-| ------------- | ------------------------------------------------------ | -------------------------------- |
-| `exact`       | Exact count for the complete provider request.         | Yes.                             |
-| `upper_bound` | Proven upper bound for the complete provider request.  | Yes.                             |
-| `estimate`    | Empirical prediction with required causal `detail`.    | No.                              |
+| `kind` | Meaning | Capacity authority |
+| --- | --- | --- |
+| `exact` | Exact count for the complete provider request. | May prove fit or overflow. |
+| `upper_bound` | Proven upper bound for the complete provider request. | May prove fit; exceeding a limit does not prove overflow. |
+| `estimate` | Empirical prediction with required causal `detail`. | Cannot admit or reject. |
+| `unavailable` | No quantified measurement, with required causal `detail`. | Cannot admit or reject. |
 
-Every result carries a non-negative integer `tokens` and a non-empty `source`.
+Every result carries a non-empty `source`; quantified kinds carry non-negative
+integer `tokens`.
 `countPromptTokens` receives the same messages supplied to `generate` and may
 perform cancellable provider I/O. The common fallback is chars/2 over message
 content; it is announced once and reported honestly as an estimate because it
 knows neither the serving vocabulary nor provider-owned request framing.
-An unavailable optional counting endpoint likewise returns an estimate naming
-the cause. A malformed measurement is a provider contract violation and fails
-hard; consumers do not reinterpret it as ordinary unavailability.
+An adapter may retain that estimate when an optional counting endpoint fails,
+provided its detail names the cause; one unable to quantify anything returns
+`unavailable`. A malformed measurement is a provider contract violation and
+fails hard.
+
+§provider-capacity-admission `assessRequestCapacity` intersects every known
+physical input constraint: independent `maxInputTokens` and
+`contextWindow - outputBudget`. Its result is `admit`, `reject`, or `defer` and
+retains the complete limit and measurement evidence. Exact fit admits; exact
+overflow rejects. A proven upper bound admits only when it fits. Unknown limits,
+an upper bound above a limit, estimates, and unavailable measurements defer to
+the upstream provider as capacity oracle. The same stable intersection is
+exposed as `inputCapacity`; `null` means the available limits cannot establish
+one. A known combined context and output budget must leave positive input
+capacity. Consumers may display or use that fact as policy, but MUST NOT
+substitute their own content heuristic for request-shaped admission.
 
 `tokenize` is the separate content-token capability and exists only when the
 endpoint exposes its real vocabulary. Content tokenization does not substitute
 for complete-request measurement.
 
-§provider-monetary-evidence One precedence path converts each provider response
-into {§provider-cost} evidence:
+§provider-monetary-evidence One precedence path converts each physical provider
+request into {§provider-cost} evidence before the request leaves the provider
+boundary:
 
 | Precedence | Evidence | Result |
 | --- | --- | --- |
-| 1 | A documented monetary field on that response | The adapter normalizes it as `ProviderResponse.charge`; its decimal USD equivalent wins. |
-| 2 | Exact response usage and the exact model's Models.dev rates | `calculateCharge` returns estimated USD, or explicit free when every applicable rate is zero. |
-| 3 | Neither | Unknown; no cost is reported. |
+| 1 | A documented monetary field on that response or error | The adapter validates and preserves its documented `charged` or `estimated` character; its exact amount wins. |
+| 2 | Known response usage and the exact model's Models.dev rates | The adapter returns an exact decimal USD `estimated` amount only when every differently-priced applicable category is known. |
+| 3 | Neither | `unknown` with a concrete reason. |
 
-Models.dev is the sole supported fallback rate table. Missing usage or rates
-never proves free. The numeric `calculateCost` method remains callable only as a
-frozen 1.x compatibility surface and is not a monetary-reporting authority.
-`providerCostUsd` exposes authoritative, estimated, and free evidence as decimal
-USD and returns `null` for unknown evidence.
+Models.dev is the sole supported fallback rate table. Missing usage, a missing
+applicable category, or missing rates never proves zero. An exact zero rate
+produces an ordinary estimated amount of USD `0`. Rate calculation is internal
+to the provider request; Core, digest, ping, and clients never call a parallel
+pricing method.
 
 ### Generation
 
-`generate` requires a non-empty, stable, opaque `workerId`. It accepts:
+§provider-cache-identity `generate` requires a non-empty, stable, opaque
+`workerId`. A durable worker uses one globally unique value for its lifetime;
+independent databases and processes cannot mint the same local sequence. A
+`bare` call instead uses a fresh per-call value, preventing unrelated prompts
+from acquiring affinity with either the parent worker or another BARE call.
+Providers MUST NOT interpret either value.
+
+`generate` accepts:
 
 - `messages`: system, user, and assistant text messages;
 - caller cancellation through `signal`;
-- optional `grammar` and `maxTokens`;
+- optional `grammar` and call-specific `maxOutputTokens` tightening;
 - standard `sampling` intent;
+- the caller-owned `callKind` output contract when one applies;
 - opaque attribution tags plus client, strike, workspace, loop, and turn metadata.
 
+§provider-call-kind `callKind` is either `emission` (the response is a PLURNK
+turn emission) or `bare` (the response is unconstrained answer text). The
+consumer states this semantic fact explicitly; providers MUST NOT infer it from
+message count, grammar presence, worker identity, or another incidental request
+shape. The first-party adapter transports a supplied value as
+`Plurnk-Call-Kind`; the metadata gate drops it for every third-party backend.
+The signal is request metadata and never enters model-facing messages. Generic
+provider callers MAY omit it; Core supplies it for every model call.
+
 A successful return carries the model's raw content and reasoning, normalized
-usage, normalized finish reason, model identity, opaque evidence, optional
-metadata, and optional notices. The provider transports and observes model
+finish reason, model identity, its ordered {§provider-request-accounting}, the
+request's `ProviderRequestCapacity`, opaque evidence, optional metadata, and
+optional notices. A `ProviderError` carries the same available capacity and
+accounting evidence. The provider transports and observes model
 output; it never retries, discards, or repairs an otherwise completed exchange
 because PLURNK grammar did not accept it.
 
-Usage obeys:
+§provider-request-observer When a consumer supplies the request observer, the
+provider opens one durable identity through it immediately before each physical
+I/O and settles that identity with the resulting
+`ProviderRequestAccounting`. This applies to every automatic retry and capacity
+failover request. The observer is a durability sink, not an alternate evidence
+representation; the same ordered records remain on the final response or error.
+
+Usage obeys {§provider-usage}:
 
 ```text
-total = prompt + completion + reasoning
-cached ⊆ prompt
+totalTokens = inputTokens + outputTokens
+cacheReadTokens, cacheWriteTokens ⊆ inputTokens
+reasoningTokens ⊆ outputTokens
 ```
 
-`completion` excludes reasoning. Ordinary vendor finish reasons normalize to
+Unknown fields remain absent. Ordinary vendor finish reasons normalize to
 `stop`, `length`, `tool_calls`, or `content_filter`; an unknown value becomes
 `null` and emits a warning. `resource_interrupted` is the distinct failed-attempt
 disposition defined by {§provider-interrupted-attempt}.
@@ -132,9 +191,9 @@ explicit alias-scoped response style:
 
 Tag projection never runs when readable structured reasoning is already
 present. Streamed and buffered transports converge on this response boundary.
-When the upstream reports only combined output usage, the existing
-sum-preserving text-proportion estimate reclassifies completion versus reasoning
-without changing prompt, cached input, total output, or billed output.
+When the upstream reports only combined output usage, that value remains
+`outputTokens` and its unavailable text/reasoning detail stays absent. The
+adapter never apportions tokens from character lengths.
 
 Grammar evidence retains the exact pre-projection sentence and its Unicode
 content offset. Response classification cannot rewrite what a transported GBNF
@@ -144,8 +203,10 @@ rail observed.
 
 §provider-sdk-boundary Cataloged providers instantiate their
 Models.dev-declared AI SDK package.
-Standard request shaping, streaming, retries, cancellation, timeouts, usage,
-and vendor error parsing belong to the SDK.
+Standard request shaping, streaming, usage, and vendor error parsing belong to
+the SDK. PLURNK supplies cancellation and deadline signals and owns the sole
+cross-attempt scheduler so every physical request remains observable and
+accountable.
 
 PLURNK maps its generic settings to AI SDK call settings:
 
@@ -153,19 +214,48 @@ PLURNK maps its generic settings to AI SDK call settings:
 - presence and frequency penalties;
 - stop sequences and seed;
 - output-token ceiling;
-- `off`, `adaptive`, or budget-derived reasoning intent.
+- `off`, provider-default `adaptive`, or explicit `on` reasoning intent, with
+  an optional operator budget.
 
 Provider-specific options are permitted only where they preserve a documented
 PLURNK product contract the generic SDK surface cannot express.
 
+§provider-readable-reasoning When the effective reasoning posture is not
+`off`, a native adapter MUST request readable reasoning summaries if its
+provider requires a separate response-visibility option. That option neither
+activates reasoning nor selects its depth. The exact wire projection belongs to
+the provider adapter; Models.dev's reasoning bit remains capability metadata.
+
+The portable SDK surface has no boolean-enabled reasoning value. An unqualified
+`on` therefore projects to its conventional `medium` enabled posture. This is a
+wire activation value, not a reasoning budget or output-token ceiling.
+
+§provider-cache-affinity **Cache affinity is route-owned request projection.**
+When a provider documents a semantics-preserving conversation, session, or
+prompt-cache routing key, its catalog adapter projects `workerId` through that
+provider's documented header, body field, or native SDK option. The common
+transport neither guesses from protocol resemblance nor sends a generic cache
+field to an unknown provider. The operator may disable affinity globally or per
+alias; automatic provider caching without an affinity control remains untouched.
+
+§provider-cache-write-policy **Cache-write policy is separate from affinity.**
+`PLURNK_PROVIDERS_CACHE_WRITE_POLICY` is `off` or `stable-system`. The latter
+marks only the final leading system instruction as an explicit reusable cache
+boundary, and only on routes whose native SDK documents that control. It does
+not mark the changing user packet or enable an API-wide automatic cache mode.
+Unsupported routes receive no invented option. The default five-minute
+provider lifetime is used; a longer, differently priced lifetime is not an
+implicit transport choice.
+
 §deepseek-reasoning-request The direct DeepSeek catalog path maps the common
 reasoning intent to its OpenAI-compatible controls:
 
-| PLURNK mode | `thinking`            | `reasoning_effort`   |
-| ----------- | --------------------- | -------------------- |
-| `off`       | `{ type: disabled }`  | omitted              |
-| `adaptive`  | omitted               | omitted              |
-| `on`        | `{ type: enabled }`   | budget-derived tier  |
+| PLURNK posture | `thinking`            | `reasoning_effort`   |
+| --------------- | --------------------- | -------------------- |
+| `off`           | `{ type: disabled }`  | omitted              |
+| `adaptive`      | omitted               | omitted              |
+| `on`            | `{ type: enabled }`   | omitted              |
+| `on` + budget   | `{ type: enabled }`   | budget-derived tier  |
 
 The compatible transport is deliberately retained for:
 
@@ -195,9 +285,10 @@ The universal groups are:
 - reasoning activation and optional explicit budget;
 - explicit reasoning response-content style;
 - decode tuning;
-- request, stream-idle, retry, and probe budgets;
+- operation, physical-attempt, first-content, stream-idle, retry, and probe budgets;
 - local GBNF and llama-server capability pins;
 - context-window and generation-envelope overrides;
+- provider-documented cache affinity and explicit cache-write policy;
 - opt-in logprob and raw-body capture.
 
 Operator secrets and machine-specific values never belong in committed
@@ -214,16 +305,20 @@ alias.
 
 Provider and model facts resolve independently:
 
-| Fact                 | Natural source                                         | Operator source                                      | Effective value                                                                                                                                        |
-| -------------------- | ------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Context window       | Catalog metadata or a local endpoint probe.            | `PLURNK_PROVIDERS_CONTEXT_WINDOW`.                   | Minimum when both exist; the sole value otherwise. A cataloged cloud miss fails construction; a compatible probe miss remains `null` with one warning. |
-| Completion envelope  | Catalog `maxOutput`; there is no live limit probe.     | `PLURNK_PROVIDERS_COMPLETION_RESERVE`.               | An absolute reserve wins. A percentage derives from the effective window and is capped by catalog `maxOutput` when present.                            |
-| Reasoning capability | Catalog `reasoning: true`, exposed by snapshot lookup. | Runtime activation, reserve, and adapter wire style. | The catalog bit is informational; provider construction neither activates nor blocks reasoning from it.                                                |
-| Estimated USD rates  | Models.dev input, output, and optional cache-read rates. | None. | Missing rates produce unknown evidence; explicit all-zero rates produce free evidence. No live price fetch exists. |
-
-Models.dev cache-read cost defaults to its input cost when omitted. Cache-write
-cost remains snapshot information; the current usage record has no cache-write
-quantity to price.
+| Fact | Natural source | Operator source | Effective value |
+| --- | --- | --- | --- |
+| Context window | Catalog metadata or local endpoint probe. | `PLURNK_PROVIDERS_CONTEXT_WINDOW`. | Minimum when both exist; sole value otherwise. Cataloged cloud miss fails construction; compatible probe miss remains `null` with one warning. |
+| Maximum input | Catalog `limit.input`; no generic live probe. | None. | Catalog value or `null`; never reconstructed from context and output. |
+| Maximum output | Catalog `limit.output`; no generic live probe. | None. | Minimum of catalog value and effective context, or `null`. |
+| Total output budget | None. | `PLURNK_PROVIDERS_OUTPUT_BUDGET`. | Percentage of effective context or absolute count, capped by known context/output limits; a call may only tighten it. |
+| Reasoning budget | None. | Optional `PLURNK_PROVIDERS_REASONING_BUDGET`. | Percentage of effective context or absolute count; valid only as a strict subset of total output and effective only while reasoning is on or adaptive. |
+| Reasoning capability | Catalog `reasoning: true`. | Runtime activation and adapter wire style. | Catalog bit remains informational; it neither activates nor blocks reasoning. |
+| Estimated USD rates | Models.dev input, output, optional reasoning, and optional cache rates. | None. | Missing differently-priced usage or rates produces unknown; exact all-zero rates produces estimated USD zero. |
+
+Models.dev cache-read and cache-write rates default to the input rate, and the
+reasoning rate defaults to the output rate, when omitted. A differently priced
+category requires its corresponding usage detail or the request estimate is
+unknown.
 
 `instantiateProvider` resolves in this order:
 
@@ -298,7 +393,7 @@ also expose:
 - EOS marker removal;
 - exact complete-request counting through `/v1/chat/completions/input_tokens`;
 - exact content token IDs through `/tokenize`;
-- the requirement that the caller provide `maxTokens`.
+- the requirement that the adapter apply a finite output budget.
 
 `PLURNK_PROVIDERS_LLAMA_SERVER` may force or disable detection. Probe attempts
 and delay are knobs. A failed probe does not silently assert capabilities.
@@ -311,14 +406,14 @@ OpenAI-compatible generation endpoint through the SDK adapter.
 For a detected llama-server, PLURNK sends the complete reasoning contract on
 every request:
 
-| Mode | Template activation | `thinking_budget_tokens` |
+| Posture | Template activation | `thinking_budget_tokens` |
 |---|---:|---:|
 | `off` | false | `0` |
-| `adaptive` | true | resolved reasoning reserve |
-| `on` | true | explicit reasoning budget |
+| `adaptive` | true | configured reasoning subset, otherwise omitted |
+| `on` | true | configured reasoning subset, otherwise omitted |
 
-The explicit budget may tighten but MUST NOT exceed the resolved reasoning
-reserve. Template calls normally use `reasoning_format: "auto"` for a separate
+The allowance is contained by the request's total output budget. Template calls
+normally use `reasoning_format: "auto"` for a separate
 readable channel. A GBNF-bearing call uses `"none"` so the exact constrained
 sentence survives response projection; the adapter separates its leading
 reasoning enclosure only after preserving grammar evidence. Process-wide
@@ -342,7 +437,7 @@ intent. It cannot override:
 - data-capture settings;
 - tool, modality, or multi-choice behavior;
 - the consumer-owned output envelope;
-- prompt-cache identity.
+- cache affinity identity or cache-write policy.
 
 Generic AI SDK calls accept only settings represented by the SDK's portable
 surface. Compatible endpoints may carry additional sampling keys after reserved
@@ -366,16 +461,40 @@ normal value. Retry exhaustion is preserved as `attempts` and
 `retryExhausted`, and the resulting Problem is not marked retryable after the
 provider has consumed its automatic retry budget.
 
-The AI SDK owns one attempt scheduler around the complete generation exchange.
-`PLURNK_PROVIDERS_RETRY_ATTEMPTS` is the maximum retry count, including a
-configured stream-chunk deadline that expires while consuming a response body.
-The total generation deadline and caller cancellation span that scheduler and
-every attempt; neither restarts during replay. Total and stream-chunk deadlines
-are separately configurable.
+§provider-capacity-failure A proven exact preflight overflow and an upstream
+context rejection normalize to `ProviderError(kind="capacity_exceeded")` and
+an RFC 9457 status 413. `capacityStage` is `preflight` or `upstream`; a
+non-413 upstream status remains `providerStatus`, while physical request
+accounting retains the status actually received. Preflight rejection occurs
+before provider I/O and therefore opens no request identity and creates no
+request-accounting row. Capacity failures are not connectivity failures and are
+never retried by the provider scheduler; bounded packet recovery belongs to the
+consumer.
+
+§provider-connectivity The provider adapter owns one attempt scheduler around
+the complete generation exchange; SDK-internal retries are disabled.
+`PLURNK_PROVIDERS_RETRY_ATTEMPTS=N` permits at most `N + 1` physical requests.
+The layers are independent and a configured value of zero disables only that
+deadline:
+
+| Layer | Operator knob | Boundary | Expiry |
+| --- | --- | --- | --- |
+| Operation | `PLURNK_PROVIDERS_OPERATION_TIMEOUT` | Complete logical call, including every attempt and retry delay. | Final `deadline_exceeded` Problem at 504 with `timeoutPhase=operation`; never retried. |
+| Attempt | `PLURNK_PROVIDERS_FETCH_TIMEOUT` | One physical generation request, including response consumption. | Retryable `network_failure` with `timeoutPhase=attempt`. |
+| First content | `PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT` | Response-stream start through first semantic model content; metadata, empty deltas, and transport activity do not satisfy it. | Retryable `network_failure` with `timeoutPhase=first_content`. |
+| Stream idle | `PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT` | Silence between semantic content chunks after content begins. | Retryable `network_failure` with `timeoutPhase=stream_idle`. |
+
+Caller cancellation spans the operation and preserves the caller's reason.
+Inner deadline failures consume the ordinary retry budget; retry exhaustion
+adds `attempts` and `retryExhausted`, retains the inner `timeoutPhase` and
+`timeoutMs`, and is final. Every scheduler iteration opens and settles exactly
+one ordered {§provider-request-accounting} record, including response-less
+network failures and timed-out attempts.
 
 HTTP 408, 409, 429, and ordinary 5xx responses are retryable unless the endpoint
-explicitly says otherwise. Endpoint control responses 520–527 are final so a
-router can prevent multiplicative retries behind its own retry policy.
+explicitly says otherwise through `X-Should-Retry`. That header is authoritative;
+without an explicit directive, endpoint control responses 520–527 are final so
+a router can prevent multiplicative retries behind its own policy.
 
 ### §provider-interrupted-attempt Provider-declared interruption
 
@@ -386,10 +505,10 @@ completed exchange.
 | Concern                    | Contract                                                                                                                     |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | Normalized finish reason   | Exact `insufficient_system_resource` becomes `resource_interrupted`; the raw value remains in `assistantRaw`.                |
-| `generate` outcome         | Throw `ProviderError(kind="resource_interrupted")` at local status 503 with the normalized attempt on `error.attempt`.       |
+| `generate` outcome         | Throw `ProviderError(kind="resource_interrupted")` at local status 503 with the normalized attempt on `error.attempt` and the same accounting on `error.accounting`. |
 | Partial response           | Preserve content, reasoning, usage, model, metadata, optional raw body, and other evidence without admitting it as success.  |
 | Automatic replay           | None; the Problem has `retryable: false`, and AI SDK retry scheduling has already completed at the successful transport.     |
-| Capacity-pool overflow     | None; a sibling success would erase the known billed failed attempt from the current `ProviderResponse` surface.             |
+| Capacity-pool overflow     | None under the existing routing policy; when other overflow-eligible failures do reach a sibling, the pool concatenates their request accounting. |
 | Consumer admission         | Persist the evidence as an unaccepted attempt; never parse it into executable work, even when its frame looks complete.      |
 
 ## §10 Grammar
@@ -398,8 +517,9 @@ GBNF is a local llama-server capability, not a generic provider expectation.
 The consumer chooses whether to supply a grammar. The provider never creates or
 rewrites one.
 
-GBNF defines the accepted raw sampled text; it runs before response reasoning
-is separated from regular content. The shipped PLURNK sentence is owned by
+GBNF defines the accepted sampled text; it runs before response reasoning is
+separated from regular content. A generated rail may declare a response root
+that composes a template-provided prefix for independent evidence grading. The shipped PLURNK sentence is owned by
 `plurnk-contracts` {§gbnf-turn-shape} and {§gbnf-reasoning-boundary}; this package does
 not restate or rewrite it.
 
@@ -418,7 +538,6 @@ The consumer validates `grammarEvidence.input` outside the enforcer's failure
 domain. `PLURNK_PROVIDERS_GBNF_DEBUG` still validates grammar syntax before the
 call and sets `transported: false` for the unconstrained comparison.
 
-
 ## §11 Evidence and metadata
 
 §provider-evidence `assistantRaw` is an opaque normalized transport record.
@@ -449,11 +568,35 @@ correlate them to an entity it actually created rather than reusing `id`.
 
 ## §12 Generation envelopes
 
-§provider-generation-envelope Reasoning and completion reserves are percentages
-of the resolved context
-window or absolute token counts. Absolute pins win. The provider reports the
-resolved reserves; the consumer owns prompt packing and the per-call output
-cap. Model-limit precedence is defined once in {§model-fact-resolution}.
+§provider-generation-envelope Every request has at most one total output
+budget. It includes visible output and hidden reasoning. An optional reasoning
+budget is a strict subset of that total, never an additive reserve. The
+configured total is a percentage of effective context or an absolute count;
+percentages resolve to the nearest whole token with a one-token minimum. It is
+capped by known context and model-output limits; `generate.maxOutputTokens` may
+only tighten it for one call. The effective reasoning subset tightens with that
+total and remains strictly smaller.
+
+The adapter owns native projection. A backend whose generic SDK maximum already
+includes reasoning receives the total directly. When a native SDK instead adds
+an explicit reasoning allowance to its generic visible-output maximum, the
+adapter sends `total - reasoning` through the generic field and the reasoning
+subset through the documented provider option. Core and other callers never
+reconstruct this arithmetic.
+
+§provider-output-budget-conformance When a completed response reports
+normalized output-token usage greater than its effective total output budget,
+the exchange is an `invalid_response` at 502 rather than an admitted result or
+a prompt-capacity 413. Its complete failed-attempt evidence and settled charged
+request remain available. The violation is final and is never automatically
+replayed. Missing output usage cannot prove a violation.
+
+`PLURNK_PROVIDERS_OUTPUT_BUDGET` is required for standard providers and ships
+as `35%`. `PLURNK_PROVIDERS_REASONING_BUDGET` is optional; leaving it unset
+preserves provider-adaptive depth. A backend known to decode without a finite
+limit advertises `requiresOutputBudget` and fails construction when no total can
+be resolved. The retired additive reserve knobs fail hard rather than creating
+a second envelope contract.
 
 ## §13 Capacity pool
 
@@ -466,8 +609,13 @@ availability and rate-limit failures that carry no normalized response attempt;
 {§provider-interrupted-attempt} propagates without overflow.
 
 Prompt measurement covers every backend that could receive the request. The
-pool takes the largest result; differing exact counts or any proven bound yield
-an `upper_bound`, while any estimate makes the aggregate an estimate.
+pool takes the largest quantified result; differing exact counts or any proven
+bound yield an `upper_bound`, any estimate makes the aggregate an estimate, and
+any unavailable backend makes it unavailable. Physical limits and budgets are
+independent safe minima across the pool. `inputCapacity` is the minimum of each
+backend's complete derived input capacity, never a synthetic subtraction across
+minima from different backends; request-specific output tightening repeats the
+complete-envelope derivation per backend before taking the minimum.
 
 ## §14 Conformance
 
@@ -479,7 +627,12 @@ Coverage MUST prove:
 - compatible extension preservation;
 - timeout, retry, cancellation, interrupted-attempt, and final-error behavior;
 - local capability probes and pins;
-- exact, bounded, and estimated complete-request token measurements;
+- exact, bounded, estimated, and unavailable complete-request measurements;
+- independent input/context/output limits, asymmetric admission, and normalized
+  local/upstream capacity failures;
+- one total output budget and native additive-reasoning projection;
+- provider-reported output beyond that budget failing once with complete
+  attempt and accounting evidence;
 - local reasoning activation, response-wide allowance, and GBNF coexistence;
 - explicit tagged-reasoning projection across streamed, buffered, capped, and
   literal-tag responses;

package/dist/AiSdkProvider.d.ts

@@ -1,32 +1,48 @@
-import type { AuthoritativeChargeNormalizer, ChatMessage, PromptTokenMeasurement, Provider, ProviderResponse, ProviderUsage } from "./types.ts";
+import type { ChatMessage, PromptTokenMeasurement, Provider, ProviderCostNormalizer, ProviderGenerateArgs, ProviderRequestCapacity, ProviderResponse, ProviderUsage } from "./types.ts";
 import type { ProviderCost } from "@plurnk/plurnk-contracts";
-import type { Reasoning, ReasoningResponseStyle, ReserveSpec } from "./env.ts";
+import type { JSONValue } from "ai";
+import type { Reasoning, ReasoningResponseStyle } from "./env.ts";
 import type { LanguageModel } from "ai";
 import type { PluginAttribution, PluginAttributionContext } from "@plurnk/plurnk-meta";
 export type ProviderFetch = typeof globalThis.fetch;
 export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" | "effort_explicit" | "thinking_effort" | "template" | "anthropic";
 export type GrammarStyle = "none" | "llamacpp";
+export type CacheAffinity = {
+    readonly target: "header" | "body";
+    readonly name: string;
+} | {
+    readonly target: "provider-option";
+    readonly provider: string;
+    readonly name: string;
+};
+export type AiSdkProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
 export type AiSdkProviderConfig = {
     model: string;
     url?: string;
     languageModel?: LanguageModel;
     attributions?: (context: PluginAttributionContext) => PluginAttribution;
     fetchTimeoutMs: number;
+    operationTimeoutMs: number;
+    firstContentTimeoutMs: number;
     streamIdleTimeoutMs?: number;
     headers?: Record<string, string>;
     fetch?: ProviderFetch;
     contextWindow?: number | null;
+    maxInputTokens?: number | null;
+    maxOutputTokens?: number | null;
+    outputBudget?: number | null;
+    reasoningBudget?: number | null;
+    additiveReasoningProvider?: "anthropic" | "bedrock";
     reasoningStyle?: ReasoningStyle;
     reasoningResponseStyle?: ReasoningResponseStyle;
     countPromptTokens?: (messages: readonly ChatMessage[], signal?: AbortSignal) => PromptTokenMeasurement | Promise<PromptTokenMeasurement>;
-    calculateCost?: (usage: ProviderUsage) => number;
-    calculateCharge?: (usage: ProviderUsage) => Exclude<ProviderCost, {
-        kind: "authoritative";
-    }>;
-    normalizeCharge?: AuthoritativeChargeNormalizer;
+    estimateCost?: (usage: ProviderUsage | undefined) => ProviderCost;
+    normalizeCost?: ProviderCostNormalizer;
     source?: string;
     grammarStyle?: GrammarStyle;
-    promptCacheKey?: boolean;
+    cacheAffinity?: CacheAffinity;
+    systemCacheProviderOptions?: AiSdkProviderOptions;
+    reasoningResponseProviderOptions?: AiSdkProviderOptions;
     serviceTier?: string;
     gbnfDebug?: boolean;
     streaming?: boolean;
@@ -38,7 +54,7 @@ export type AiSdkProviderConfig = {
     tokenizeUrl?: string;
     promptTokensUrl?: string;
     servedModel?: string;
-    requiresMaxTokens?: boolean;
+    requiresOutputBudget?: boolean;
     reasoning: Reasoning;
     temperature: number;
     repeatPenalty: number;
@@ -51,8 +67,6 @@ export type AiSdkProviderConfig = {
     errorDetailLimit?: number;
     topLogprobs?: number | null;
     rawBody?: boolean;
-    reasoningReserve?: ReserveSpec;
-    completionReserve?: ReserveSpec;
     tuningFloors?: boolean;
 };
 export declare const effortFromBudget: (budget: number) => "low" | "medium" | "high";
@@ -62,31 +76,17 @@ export default class AiSdkProvider implements Provider {
     tokenize?: (text: string) => Promise<number[]>;
     constructor(config: AiSdkProviderConfig);
     get contextWindow(): number | null;
-    get reasoningReserve(): number | null;
-    get completionReserve(): number | null;
+    get maxInputTokens(): number | null;
+    get maxOutputTokens(): number | null;
+    get outputBudget(): number | null;
+    get reasoningBudget(): number | null;
+    get inputCapacity(): number | null;
     get model(): string;
     get servedModel(): string | undefined;
-    get requiresMaxTokens(): boolean | undefined;
+    get requiresOutputBudget(): boolean | undefined;
     get constrainsOutput(): boolean;
     countPromptTokens(messages: readonly ChatMessage[], signal?: AbortSignal): Promise<PromptTokenMeasurement>;
-    calculateCost(usage: ProviderUsage): number;
-    calculateCharge(usage: ProviderUsage): Exclude<ProviderCost, {
-        kind: "authoritative";
-    }>;
-    generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling }: {
-        messages: ChatMessage[];
-        workerId: string;
-        primaryWorkerId?: string;
-        signal?: AbortSignal;
-        grammar?: string;
-        maxTokens?: number;
-        attributions?: string[];
-        client?: string;
-        strikes?: number;
-        workspaceId?: string;
-        loop?: number;
-        turn?: number;
-        sampling?: Record<string, unknown>;
-    }): Promise<ProviderResponse>;
+    assessRequestCapacity(messages: readonly ChatMessage[], maxOutputTokens?: number, signal?: AbortSignal): Promise<ProviderRequestCapacity>;
+    generate({ messages, workerId, primaryWorkerId, signal, grammar, maxOutputTokens, attributions, client, strikes, workspaceId, loop, turn, sampling, observeRequest, callKind }: ProviderGenerateArgs): Promise<ProviderResponse>;
 }
 //# sourceMappingURL=AiSdkProvider.d.ts.map