@plurnk/plurnk-providers 1.3.11 → 1.4.0

package/.env.defaults

@@ -1,6 +1,6 @@
 # REFERENCE - @plurnk/plurnk-providers' shipped .env.defaults: the operative floor for
-# PLURNK_PROVIDERS_* knobs and provider declarations (providers#44: every package owns
-# what it reads; the file IS the configuration reference).
+# PLURNK_PROVIDERS_* knobs and provider declarations ({§operator-config-env-defaults});
+# every package owns what it reads, and this file IS the configuration reference.
 # The daemon assembles every installed member's file into one floor (set-if-unset under the
 # operator's env) - do NOT edit this file; put YOUR config in ~/.plurnk/.env or ./.env. A key
 # claimed by two packages crashes boot naming both.
@@ -10,8 +10,8 @@
 # whose UNSET state is meaningful (derive/auto/off, or a required secret) - uncomment to pin.
 #
 # Models.dev supplies cataloged providers' SDK package, endpoint, credential names,
-# model metadata, and prices. Operator declarations below cover only facts absent
-# from or deliberately overridden over that catalog. Secret VALUES never belong here.
+# and model facts. {§model-fact-resolution} defines precedence per fact; there is
+# no live price fetch. Secret VALUES never belong here.
 
 # --- Side-channel reasoning (SPEC §4, #32/#33/#399) ---
 # ACTIVATION and BUDGET are separate so a numeric can never silently flip wire flags.
@@ -19,14 +19,22 @@
 # (reasoning_effort, enable_thinking, think, ...). Default ADAPTIVE (owner ruling,
 # #399): reasoning ACTIVE on a fresh install, each backend's own adaptive depth,
 # no shipped magnitude - a reasoning model that ships un-reasoning blind-edits and
-# declares done (svc#396 A/B: 25 EXECs -> 0, build broken, confident SEND[200]).
+# declares done.
 PLURNK_PROVIDERS_REASONING=adaptive
-# Positive int, REQUIRED iff REASONING=on - the magnitude for tier/budget mapping. On
-# llama.cpp the ENFORCEMENT is the box's --reasoning-budget LAUNCH flag (per-request
-# numerics are ignored): env budget and launch flag are the same number, changed together.
+# Positive int, REQUIRED iff REASONING=on - the magnitude for tier/budget mapping.
+# On llama-server it is a request-scoped reasoning allowance and may tighten, but
+# cannot exceed, the resolved PLURNK_PROVIDERS_REASONING_RESERVE.
 # PLURNK_PROVIDERS_REASONING_BUDGET=4096
 
-# --- Decode tuning (measured canonical values; bench/TUNING-EPIC.md F1/F6; #9/#30) ---
+# Response-content interpretation ({§provider-tagged-reasoning}) is independent
+# from request-side reasoning activation. The portable floor trusts only
+# structured provider/SDK reasoning fields and leaves visible content verbatim.
+# Set think-tags only on an alias whose exact model/endpoint contract emits one
+# leading <think> envelope; it is never inferred from generic reasoning capability.
+PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE=verbatim
+# PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_cfds1=think-tags
+
+# --- Decode tuning (measured canonical values; #9/#30) ---
 # TEMPERATURE is the default for EVERY request (under caller sampling); REPEAT_PENALTY is
 # the floor the provider manages wherever a grammar rides (greedy-under-mask loops without it).
 PLURNK_PROVIDERS_TEMPERATURE=0.2
@@ -44,19 +52,20 @@ PLURNK_PROVIDERS_FREQUENCY_PENALTY=0
 # stable worker id for replica-local prefix affinity. Official native SDKs own
 # their cache mechanisms and do not receive this compatible extension.
 PLURNK_PROVIDERS_PROMPT_CACHE_KEY=1
-# #567: DRY loop-breaker - llama.cpp-only (grammarStyle "none" paths skip it). MULTIPLIER=0
-# disables DRY at the general floor: the #567 sweep showed L=2 is WORSE than DRY-off on both
-# runaways AND corruption; L=32 is the measured plurnk-safe threshold (0 corruption fails,
-# ~6% runaways vs 19% off). Enable per-alias: DRY_MULTIPLIER_<alias>=0.8, ALLOWED_LENGTH_<alias>=32.
+# #567: DRY is a llama.cpp-only repeated-sequence penalty. It can reduce
+# degenerate loops, but it can also corrupt exact source, identifiers, quoted
+# evidence, and other repetition required by PLURNK operations. The portable
+# server-wide default is off. A nonzero alias override is an explicit fidelity
+# tradeoff; DRY_BASE_<alias> and DRY_ALLOWED_LENGTH_<alias> tune that opt-in.
 PLURNK_PROVIDERS_DRY_MULTIPLIER=0
-PLURNK_PROVIDERS_DRY_BASE=1.75
-PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=32
-# REPEAT_LAST_N widens the older repeat_penalty window past the box's 64; optional (DRY's
-# whole-context window makes it secondary). Set per-alias if a model wants it.
+# PLURNK_PROVIDERS_DRY_BASE_<alias>=
+# PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH_<alias>=
+# REPEAT_LAST_N widens the older repeat_penalty window past the box's default.
+# Set it per alias only from measured model behavior.
 # PLURNK_PROVIDERS_REPEAT_LAST_N_<alias>=512
 
 # --- Transport budgets (§4, #18) ---
-# Per-attempt fetch timeout (ms); the caller's abort signal spans retries.
+# Total generation-operation timeout (ms), including retries; caller cancellation also spans the operation.
 PLURNK_PROVIDERS_FETCH_TIMEOUT=600000
 # Maximum silence (ms) between streamed response-body chunks after response
 # streaming begins. Disabled at the portable floor: slow local inference may
@@ -66,6 +75,9 @@ PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT=0
 # Transient-failure retries: 0 = surface the first failure; N = retries on 429/5xx/timeout
 # with exponential backoff (Retry-After wins). RETRY_DELAY is the backoff base (ms).
 PLURNK_PROVIDERS_RETRY_ATTEMPTS=3
+# Maximum characters retained from an upstream provider diagnostic in the
+# public Problem detail. Structured failure facts are not truncated.
+PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT=512
 
 # --- Endpoint probe (#34) ---
 # GET /v1/models at construction (context window + llama-server fingerprint). One failure
@@ -82,13 +94,14 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
 # unconstrained output's divergence. Development aid; leave unset in production.
 # PLURNK_PROVIDERS_GBNF_DEBUG=0
 
-# --- Window (SPEC §11) ---
-# Unset = derive: env -> live endpoint probe (n_ctx) -> models.dev catalog -> null (surfaced
-# once via PLURNK_CONTEXT_UNKNOWN naming the model). Set to pin the window deliberately -
-# per-alias (_<alias>) for a box whose model the catalog doesn't know.
+# --- Window ({§model-fact-resolution}) ---
+# Physical provider context only. Unset derives from a live endpoint probe (n_ctx) or
+# models.dev, else null (surfaced once via PLURNK_CONTEXT_UNKNOWN). A configured value
+# caps detected physics or declares it when unknown. Prompt packing and model-facing
+# pressure are consumer policy, not provider configuration.
 # PLURNK_PROVIDERS_CONTEXT_WINDOW=200000
 
-# --- Model pricing override (USD per million tokens; SPEC §4) ---
+# --- Model pricing override (USD per million tokens; {§model-fact-resolution}) ---
 # Models.dev owns catalog rates. Set these together for a model absent from the
 # snapshot or to deliberately override its rates. Cached input defaults to the
 # input rate when omitted. All three knobs are per-alias scopable.
@@ -122,6 +135,8 @@ PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_API_KEY_ENV=CLOUDFLARE_API_TOKEN,CLOUDFLARE
 # Fireworks reasoners default on when reasoning_effort is omitted; explicit
 # "none" is its off switch. This is a declared wire exception, not a registry.
 PLURNK_PROVIDERS_PROVIDER_FIREWORKS_REASONING_STYLE=effort_explicit
+# Direct DeepSeek reasoning follows {§deepseek-reasoning-request}.
+PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_STYLE=thinking_effort
 PLURNK_PROVIDERS_PROVIDER_VOLCENGINE_NPM=@ai-sdk/openai-compatible
 PLURNK_PROVIDERS_PROVIDER_VOLCENGINE_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3
 PLURNK_PROVIDERS_PROVIDER_VOLCENGINE_API_KEY_ENV=ARK_API_KEY
@@ -162,5 +177,7 @@ PLURNK_BASE_URL=https://plurnk.ai/v1
 # tuning. Each accepts a percentage of the window ("10%") or an absolute token count
 # ("4096"; absolutes win outright, alias-scopable for measured envelopes). The prompt
 # budget is window - reasoning - completion - the consumer's own safety margin.
+# On llama-server, the resolved reasoning reserve is also the adaptive per-response
+# reasoning ceiling. It is one cumulative allowance across every reasoning block.
 PLURNK_PROVIDERS_REASONING_RESERVE=10%
 PLURNK_PROVIDERS_COMPLETION_RESERVE=25%

package/README.md

@@ -5,13 +5,21 @@ PLURNK's stable model-provider contract and its adapter to the
 
 Ordinary provider behavior is intentionally not reimplemented here:
 
-- Models.dev supplies provider package, endpoint, credential, context-window,
-  output-limit, and pricing metadata at build time.
+- A release-time Models.dev snapshot supplies provider package, endpoint, and
+  credential names, plus context-window, output-limit, reasoning-capability,
+  and pricing metadata.
 - Official AI SDK providers own vendor request and response protocols.
 - PLURNK owns aliases, generation envelopes, normalized usage and errors,
   evidence capture, first-party metadata, and local endpoint capabilities.
 
 See `SPEC.md` for the contract and `.env.defaults` for every operational knob.
+The package-owned `PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT` bounds upstream
+diagnostic text in public provider Problems.
+
+Model facts do not share one fallback chain. Context windows, output envelopes,
+reasoning activation, and estimated prices resolve independently
+({§model-fact-resolution}). PLURNK does not fetch live per-token prices, and the
+local estimate is not an authoritative relay-settled charge.
 
 ## Configure a model
 
@@ -60,10 +68,15 @@ It may use any npm scope. Its package manifest declares the PLURNK name:
 The default export is an AI SDK provider with
 `languageModel(modelId)`. PLURNK adapts that language model into its own
 contract, so plugins do not reproduce retries, usage normalization, envelopes,
-or telemetry.
+notices, or RFC 9457 failure normalization.
+
+The manifest may declare always-on `plurnk.attribution`. The default export may
+also implement synchronous `attributions(context)` and decide per provider
+attempt whether to return no, one, or many additional opaque tags
+({§plugin-attribution}).
 
 Discovery is scope-agnostic and rejects duplicate names.
-`PLURNK_PLUGINS_TRUSTED_ONLY` restricts third-party discovery.
+Third-party discovery uses the shared pre-import trust contract ({§plugin-trust-boundary}).
 
 ## Local endpoints
 
@@ -75,6 +88,54 @@ The `plurnk` provider retains the compatible transport because it carries
 first-party attribution and loop metadata and leaves model tuning to the
 endpoint.
 
+## Configured-provider packet conformance matrix
+
+Every configured model alias is exercised through a real PLURNK loop — the
+production packet, a model-selected operation, its materialized result, and
+completion — never a transport-only completion. Provider-exposed reasoning must
+survive in the durable assistant packet and digest; a provider with no private
+reasoning is valid when the observable operation cycle succeeds.
+
+One specimen at a time, deterministically:
+
+```sh
+cd plurnk-core
+npm run test:live:specimen -- "<test-name-pattern>"
+```
+
+The selector inserts `--test-name-pattern` before the expanded live file list in
+the exact standard `test:live` invocation; trailing npm arguments alone cannot
+narrow the suite. This procedure is `plurnk-core`'s own; the ledger below is
+maintained with the evidence for every alias it names.
+
+### Classifications
+
+| Class | Meaning |
+|---|---|
+| pass | Full packet cycle completed; durable packet and digest verified |
+| auth/credential | The route is blocked before the model by authorization or credential handling |
+| transport | The route fails at a transport/capability boundary, not the model |
+| op:stable-fail | An operation-level failure repeated on replay; assertion unweakened |
+| op:stochastic | An operation-level failure did not repeat on a later roll |
+| unreachable | The endpoint cannot be reached from this machine |
+
+Authorization and credential failures are reported as their own class, never as
+model failures. Repeated stochastic and stable operation failures are reported
+separately in the ledger's specimens.
+
+### Ledger
+
+| Alias | Route (snapshot) | Class | Evidence |
+|---|---|---|---|
+| 38 configured aliases — 2026-07 sweep | — | 20 × pass; 14 × auth/credential/transport; 4 × operation-level | Initial READ line-slice sweep (`#7`) |
+| `cfgpt120b`, `grok` | — | op:stochastic → pass on replay | `#7` |
+| `cfkimi27`, `kimi` | — | op:stable-fail (unresolved, unweakened assertion) | `#7` |
+| `cfds1` | `cloudflare/@cf/deepseek-ai/deepseek-r1-distill-qwen-32b` | op:stable-fail — READ repeated 13 turns to the 508 strike threshold; retrieval materialization verified (`2:beta` present, exact 409 recovery given) | `/home/hyzen/benchmarks/live-contract-read-L-TIgart/digest/` (`#7`) |
+
+The full current classifications of every configured alias are refreshed by the
+frozen-candidate live drill's honest reporting; this ledger is the maintained
+record of that procedure, never a substitute for it.
+
 ## Development
 
 ```sh

package/SPEC.md

@@ -8,8 +8,9 @@ ordinary provider protocols.
 
 The provider stack has four owners:
 
-1. Models.dev supplies a build-time snapshot of provider package, API endpoint,
-   credential names, models, context windows, output limits, and USD prices.
+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.
 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.
@@ -23,7 +24,8 @@ provider declaration, or left explicitly unknown.
 
 ## §2 Provider interface
 
-`Provider` exposes immutable model facts and one generation operation:
+§provider-interface `Provider` exposes immutable model facts and one generation
+operation:
 
 ```ts
 interface Provider {
@@ -35,26 +37,49 @@ interface Provider {
   readonly reasoningReserve?: number | null;
   readonly completionReserve?: number | null;
 
-  countTokens(text: string): number;
+  countPromptTokens(
+    messages: readonly ChatMessage[],
+    signal?: AbortSignal,
+  ): Promise<PromptTokenMeasurement>;
   tokenize?(text: string): Promise<number[]>;
   calculateCost(usage: ProviderUsage): number;
+  calculateCharge?(usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }>;
   generate(args: GenerateArgs): Promise<ProviderResponse>;
 }
 ```
 
-`contextWindow: null` means genuinely unknown. A consumer MUST NOT invent a
-stand-in. A cataloged cloud model without a context window fails construction
-unless the operator pins `PLURNK_PROVIDERS_CONTEXT_WINDOW`. A local probe
-failure degrades to `null` and emits one warning because a transient probe
-failure must not make a usable local endpoint unbootable.
-
-`countTokens` is synchronous and non-negative. The common fallback is a
-conservative chars/2 ruler and is announced once. `tokenize` exists only when
-the endpoint exposes its real vocabulary.
-
-`calculateCost` returns estimated USD. Models.dev rates are converted at the
-provider boundary. Unknown pricing returns `0`; it is not represented as a
-fabricated rate.
+`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.
+
+`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.                              |
+
+Every result carries a non-negative integer `tokens` and a non-empty `source`.
+`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.
+
+`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 A provider response may carry an authoritative
+settled `charge`; it wins over every local calculation. Otherwise
+`calculateCharge` returns estimated, explicitly free, or unknown evidence under
+{§provider-cost}. The numeric `calculateCost` method remains only as a frozen
+1.x compatibility surface: a positive value adapts to an estimate, while zero
+adapts to unknown because it cannot prove free.
 
 ### Generation
 
@@ -64,13 +89,13 @@ fabricated rate.
 - caller cancellation through `signal`;
 - optional `grammar` and `maxTokens`;
 - standard `sampling` intent;
-- first-party attribution, client, strike, workspace, loop, and turn metadata.
+- opaque attribution tags plus client, strike, workspace, loop, and turn metadata.
 
-It returns the model's raw content and reasoning, normalized usage, normalized
-finish reason, model identity, opaque evidence, optional metadata, and optional
-telemetry. The provider transports and observes model output; it never retries,
-discards, or repairs an otherwise completed exchange because PLURNK grammar did
-not accept it.
+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
+output; it never retries, discards, or repairs an otherwise completed exchange
+because PLURNK grammar did not accept it.
 
 Usage obeys:
 
@@ -79,13 +104,38 @@ total = prompt + completion + reasoning
 cached ⊆ prompt
 ```
 
-`completion` excludes reasoning. Known vendor finish reasons normalize to
+`completion` excludes reasoning. Ordinary vendor finish reasons normalize to
 `stop`, `length`, `tool_calls`, or `content_filter`; an unknown value becomes
-`null` and emits a warning.
+`null` and emits a warning. `resource_interrupted` is the distinct failed-attempt
+disposition defined by {§provider-interrupted-attempt}.
+
+### Tagged reasoning responses
+
+§provider-tagged-reasoning Structured provider or SDK reasoning fields are
+authoritative. Visible content is interpreted as tagged reasoning only under an
+explicit alias-scoped response style:
+
+| Effective style | Leading content                                            | Normalized result                                                                                         |
+| --------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `verbatim`      | Any bytes.                                                 | Content remains exact; only structured reasoning fields populate `reasoning`.                             |
+| `think-tags`    | No exact leading `<think>`.                                | Content remains exact.                                                                                   |
+| `think-tags`    | `<think>reasoning</think>visible`.                         | The first envelope body becomes reasoning; the exact suffix becomes content. Later tags remain literal.  |
+| `think-tags`    | `<think>reasoning` with no close, including a capped turn. | The complete post-open tail becomes reasoning; content is empty.                                         |
+
+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.
+
+Grammar evidence retains the exact pre-projection sentence and its Unicode
+content offset. Response classification cannot rewrite what a transported GBNF
+rail observed.
 
 ## §3 AI SDK boundary
 
-Cataloged providers instantiate their Models.dev-declared AI SDK package.
+§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.
 
@@ -100,6 +150,15 @@ PLURNK maps its generic settings to AI SDK call settings:
 Provider-specific options are permitted only where they preserve a documented
 PLURNK product contract the generic SDK surface cannot express.
 
+§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  |
+
 The compatible transport is deliberately retained for:
 
 - `openai` local endpoints, including llama-server and vLLM;
@@ -112,7 +171,8 @@ SDK's ordinary transport.
 
 ## §4 Operator configuration
 
-Every operational value is an environment knob documented in `.env.defaults`.
+§provider-configuration Every operational value is an environment knob
+documented in `.env.defaults`.
 There are no hidden tuning constants. Every `PLURNK_PROVIDERS_*` knob may be
 scoped to an alias by appending `_<alias>`; the scoped value wins.
 
@@ -125,6 +185,7 @@ knob's owning contract.
 The universal groups are:
 
 - reasoning activation and optional explicit budget;
+- explicit reasoning response-content style;
 - decode tuning;
 - request, stream-idle, retry, and probe budgets;
 - local GBNF and llama-server capability pins;
@@ -138,10 +199,27 @@ defaults.
 
 ## §5 Resolution
 
-`PLURNK_MODEL_<alias>=<provider>/<model-id>` declares an alias.
+§provider-resolution `PLURNK_MODEL_<alias>=<provider>/<model-id>` declares an
+alias.
 `PLURNK_MODEL=<alias>` selects the boot alias. Model IDs may contain `/`.
 `PLURNK_BASEURL_<alias>` is a per-alias endpoint override.
 
+### §model-fact-resolution Model fact precedence
+
+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  | Catalog input, output, and optional cache-read rates.  | Complete input/output rate override; cache optional. | Operator rates win; otherwise catalog rates apply. Missing rates produce unknown evidence; explicit all-zero rates produce free evidence. No live price fetch exists. |
+
+The cached-input override defaults to the explicit input rate when omitted.
+Catalog cache-read cost likewise defaults to catalog input cost. Catalog
+cache-write cost remains snapshot information; the current usage estimator has
+no cache-write quantity to price.
+
 `instantiateProvider` resolves in this order:
 
 1. A Models.dev provider and model, using its declared AI SDK package.
@@ -181,29 +259,35 @@ belongs in MCP, schemes, executors, or mimetypes instead.
 
 A provider plugin:
 
-1. declares `plurnk: { kind: "provider", name }` in `package.json`;
-2. may use any npm scope;
-3. default-exports an AI SDK provider with `languageModel(modelId)`;
-4. peers on compatible `ai` and `@plurnk/plurnk-providers` majors.
+1. declares the exact string `plurnk: { kind: "provider", name }` in `package.json` ({§plugin-family-kind});
+2. may declare always-on package-level `plurnk.attribution` and/or implement the
+   synchronous runtime `attributions(context)` hook under {§plugin-attribution};
+3. may use any npm scope;
+4. default-exports an AI SDK provider with `languageModel(modelId)`;
+5. peers on compatible `ai` and `@plurnk/plurnk-providers` majors.
 
 PLURNK adapts the returned language model. The plugin does not implement the
 PLURNK `Provider`, read PLURNK tuning knobs, or reproduce transport policy.
 
 Discovery is scope-agnostic and memoized per process. Duplicate names fail hard.
-The common plugin trust gate applies before import. A plugin absent from
+The common plugin trust gate applies before import ({§plugin-trust-boundary}). A plugin absent from
 Models.dev requires an explicit context-window pin because PLURNK will not guess
-model physics.
+model physics. `Discovery.packageAttributions` carries the canonical package map;
+the published name-keyed `Discovery.attributions` remains its 1.x projection.
 
 ## §7 Local capabilities
 
-The `openai` local adapter probes `/v1/models`. A llama-server fingerprint may
+§provider-local-capabilities The `openai` local adapter probes `/v1/models`. A
+llama-server fingerprint may
 also expose:
 
 - the actual served model and per-slot context window;
+- request-scoped reasoning parsing and a cumulative response-wide allowance;
 - GBNF constrained sampling;
 - slot count and worker-sticky slot affinity;
 - EOS marker removal;
-- exact `/tokenize`;
+- exact complete-request counting through `/v1/chat/completions/input_tokens`;
+- exact content token IDs through `/tokenize`;
 - the requirement that the caller provide `maxTokens`.
 
 `PLURNK_PROVIDERS_LLAMA_SERVER` may force or disable detection. Probe attempts
@@ -212,9 +296,31 @@ and delay are knobs. A failed probe does not silently assert capabilities.
 Ollama probes `/api/show` for its model context and uses its documented
 OpenAI-compatible generation endpoint through the SDK adapter.
 
+### llama-server reasoning
+
+For a detected llama-server, PLURNK sends the complete reasoning contract on
+every request:
+
+| Mode | Template activation | `thinking_budget_tokens` |
+|---|---:|---:|
+| `off` | false | `0` |
+| `adaptive` | true | resolved reasoning reserve |
+| `on` | true | explicit reasoning budget |
+
+The explicit budget may tighten but MUST NOT exceed the resolved reasoning
+reserve. `reasoning_format: "auto"` requests a separate readable reasoning
+channel. Process-wide llama-server flags are fallback server configuration, not
+part of the PLURNK contract and need not be synchronized with an alias.
+
+§llama-reasoning-request The allowance is cumulative across the complete response. Opening a second or
+later reasoning block does not replenish it. Template parsing, the reasoning
+sampler, normalized usage, and the returned reasoning channel MUST agree on that
+response boundary.
+
 ## §8 Request authority
 
-The caller's `sampling` bag expresses sampling intent. It cannot override:
+§provider-request-authority The caller's `sampling` bag expresses sampling
+intent. It cannot override:
 
 - model or messages;
 - stream mode;
@@ -235,9 +341,17 @@ backend.
 
 ## §9 Failures, retries, and cancellation
 
-Provider failures normalize to `ProviderError` with source, kind, status where
-available, and the original cause. A caught failure is surfaced or deliberately
-preserved; it is never converted into an empty model turn.
+§provider-failure-normalization Provider failures normalize to `ProviderError`.
+Its public contract is an RFC
+9457 Problem Details object with an exact status, stable type, occurrence
+detail, and provider-kind extension; the original error remains its cause.
+A caught failure is surfaced or deliberately preserved; it is never converted
+into an empty model turn or reduced to a message plus a generic status.
+Upstream diagnostic text is bounded by
+`PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT`; the committed `.env.defaults` owns its
+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 attempt scheduling. `PLURNK_PROVIDERS_RETRY_ATTEMPTS` is the
 maximum retry count. Caller cancellation spans the operation. Total and
@@ -247,20 +361,51 @@ 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.
 
+### §provider-interrupted-attempt Provider-declared interruption
+
+A successful transport response can still declare that inference did not
+complete. That response is evidence for one failed provider attempt, never a
+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`.       |
+| 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.             |
+| Consumer admission         | Persist the evidence as an unaccepted attempt; never parse it into executable work, even when its frame looks complete.      |
+
 ## §10 Grammar
 
 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.
 
-When transported, output is validated locally after completion. Divergence
-attaches `grammar_unenforced` telemetry with its position; the bytes still
-return. `PLURNK_PROVIDERS_GBNF_DEBUG` validates but withholds the grammar and
-compares the unconstrained result for diagnostics.
+GBNF defines the accepted raw sampled text; it runs before response reasoning
+is separated from regular content. The shipped PLURNK sentence is owned by
+`plurnk-contracts` {§gbnf-turn-shape} and {§gbnf-reasoning-boundary}; this package does
+not restate or rewrite it.
+
+When a grammar-capable adapter receives a grammar, `ProviderResponse` carries
+`grammarEvidence: { input, contentStart, transported }`. `input` is the exact
+pre-projection sentence represented by the response, `contentStart` is its
+Unicode-code-point offset to `assistant.content`, and `transported` says whether
+the grammar was actually sent. For active llama-server template reasoning, the
+adapter reconstructs the Harmony enclosure only when the response demonstrates
+that `reasoning_format: "auto"` projected it; otherwise it cannot claim evidence.
+For an unsplit response, `input` is `content` and `contentStart` is zero.
+
+§gbnf-response-observation The provider transports and represents; it does not grade its own enforcement.
+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
 
-`assistantRaw` is an opaque normalized transport record. Provider top-level
+§provider-evidence `assistantRaw` is an opaque normalized transport record.
+Provider top-level
 metadata is forwarded as an open bag without reinterpreting currencies or
 vendor fields.
 
@@ -270,25 +415,42 @@ When enabled, raw per-token model logprob is canonical; alternatives are
 preserved when returned. Raw body/chunks preserve wire evidence the normalized
 record omits.
 
-Readable reasoning and encrypted reasoning are separate. Encrypted reasoning is
-preserved verbatim and never decoded or synthesized.
+§provider-encrypted-reasoning **Readable reasoning and encrypted reasoning are
+separate.** Encrypted payload bytes remain opaque and are never decoded. The
+provider boundary distinguishes preserved detail evidence from derived entity
+classification:
+
+| Provider fact                    | Meaning |
+| -------------------------------- | ------- |
+| `id`                             | The provider's reasoning-detail identity, or `null`; never an AG-UI message or tool-call identity. |
+| `subtype`                        | A provider-normalized classification supported by wire structure. OpenAI-compatible `message.reasoning_details` is `message`; no PLURNK operation is reclassified as a native tool call. |
+| `encrypted[*].data` / `format`   | Ordered provider evidence, retained without decoding or concatenation across distinct details. |
+
+Unrecognized detail shapes are omitted at this normalization boundary. Core
+may preserve normalized items as forensic evidence, but a client protocol must
+correlate them to an entity it actually created rather than reusing `id`.
 
 ## §12 Generation envelopes
 
-Reasoning and completion reserves are percentages of the resolved context
+§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.
-
-Models.dev `maxOutput` constrains a percentage-derived completion reserve but
-does not override an explicit absolute operator choice. Unknown model physics
-remain unknown.
+resolved reserves; the consumer owns prompt packing and the per-call output
+cap. Model-limit precedence is defined once in {§model-fact-resolution}.
 
 ## §13 Capacity pool
 
-`Pool` fronts interchangeable `Provider` instances. It keeps workers sticky for
+§provider-capacity-pool `Pool` fronts interchangeable `Provider` instances. It
+keeps workers sticky for
 cache locality, selects a healthy sibling for overflow, and preserves the same
 Provider contract. Whether endpoints are interchangeable is a consumer
-decision, not inferred from provider names.
+decision, not inferred from provider names. Overflow is limited to transport
+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.
 
 ## §14 Conformance
 
@@ -298,8 +460,12 @@ Coverage MUST prove:
 - exact and unique-suffix model lookup;
 - native SDK request mapping and normalized responses;
 - compatible extension preservation;
-- timeout, retry, cancellation, and final-error behavior;
+- timeout, retry, cancellation, interrupted-attempt, and final-error behavior;
 - local capability probes and pins;
+- exact, bounded, and estimated complete-request token measurements;
+- local reasoning activation, response-wide allowance, and GBNF coexistence;
+- explicit tagged-reasoning projection across streamed, buffered, capped, and
+  literal-tag responses;
 - usage, costs, evidence, metadata isolation, and grammar observation;
 - alias scoping and fail-hard invalid configuration.