@plurnk/plurnk-providers 1.3.12 → 1.4.0

package/src/index.ts

@@ -1,17 +1,25 @@
 export type {
     ChatMessage,
     FinishReason,
+    GrammarEvidence,
     Provider,
     ProviderAssistant,
+    ProviderAttempt,
+    ProviderAttemptFinishReason,
     AiSdkProviderPlugin,
     ProviderOptions,
     ProviderResponse,
+    ProviderEncryptedReasoningItem,
     ProviderUsage,
+    PromptTokenMeasurement,
     TokenLogprob,
     TokenAlternative,
+    AuthoritativeCharge,
 } from "./types.ts";
+export type { ProviderCost } from "@plurnk/plurnk-contracts";
+export { assertPromptTokenMeasurement } from "./promptTokens.ts";
 
-// Alias cascade — re-exported from the zero-dep @plurnk/plurnk-aliases (#27), so
+// Alias cascade — re-exported from the zero-dep @plurnk/plurnk-aliases, so
 // the "." surface is unchanged for existing importers and there's one source of
 // truth for the parser (thin clients depend on that package directly).
 export type { ProviderAlias } from "@plurnk/plurnk-aliases";
@@ -23,24 +31,38 @@ export {
     resetDiscoveryCache,
 } from "./ProviderRegistry.ts";
 
-// Scope-agnostic plugin discovery (SPEC §5).
+// Scope-agnostic plugin discovery ({§plugin-family-kind}).
 export { discover } from "./discover.ts";
 export type { DiscoverOptions, Discovery } from "./discover.ts";
 
 // Stable PLURNK adapter over AI SDK language models and compatible local URLs.
 export { default as AiSdkProvider, effortFromBudget } from "./AiSdkProvider.ts";
 export type { AiSdkProviderConfig, ReasoningStyle, GrammarStyle } from "./AiSdkProvider.ts";
-// Capacity pool (SPEC §15): front N interchangeable backends as one Provider -
+// {§provider-capacity-pool} Front N interchangeable backends as one Provider -
 // worker-sticky for KV-cache reuse, overflow to a healthy sibling; the blend
 // DECISION stays the consumer's, by choosing which pool to call.
 export { default as Pool } from "./Pool.ts";
 export type { ProviderFetch } from "./AiSdkProvider.ts";
-export { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, requireEnv, reasoningFromEnv, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, envelopeFromEnv, resolveReserve } from "./env.ts";
-export type { Reasoning, ReasoningMode, ReserveSpec } from "./env.ts";
+export { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, effectiveContextWindow, envelopeFromEnv, resolveReserve, PROVIDERS_KNOBS } from "./env.ts";
+export type { Reasoning, ReasoningMode, ReasoningResponseStyle, ReserveSpec } from "./env.ts";
 export { normalizeUsage, calculateCostUsd } from "./usage.ts";
+export {
+    providerCostFor,
+    providerCostUsd,
+    resolveProviderCost,
+    validateAuthoritativeCharge,
+    validateProviderCost,
+} from "./cost.ts";
 export type { RawUsage, TokenRates } from "./usage.ts";
-export { ProviderError, classifyProviderError, toProviderError, providerSource } from "./telemetry.ts";
-export type { TelemetryEvent, ProviderTelemetryKind } from "./telemetry.ts";
+export { ProviderError, classifyProviderError, toProviderError } from "./errors.ts";
+export { providerSource } from "./notices.ts";
+export type { ProviderErrorKind } from "./errors.ts";
+export type { ProviderNotice, ProviderNoticeKind } from "./notices.ts";
+export type {
+    PluginAttributionContext,
+    PluginAttributionDeclaration,
+    PluginAttributionSource,
+} from "@plurnk/plurnk-meta";
 
 export { default as Mock } from "./Mock.ts";
 export type { MockAssistant, MockResponse, MockReturnedAssistant } from "./Mock.ts";

package/src/lexicon-guard.test.ts

@@ -1,4 +1,4 @@
-// [§lexicon] the providers-lane standing guard (#472/#477, owner-ruled OpenAI
+// {§lexicon} The providers-lane standing guard (OpenAI
 // lexicon). Retired terms fail CI here, not at the next audit — the mirror of
 // core's plurnk-core guard, tuned to what PROVIDERS retired. Scope: src/ non-test
 // + SPEC.md. A `lexicon-allow` line marker exempts the shed's own call sites
@@ -33,13 +33,13 @@ const WIRE_THINKING = /enable_thinking|`thinking`|thinking\s*:|\.thinking\b|thin
 
 // Each entry: the banned pattern and the canonical term the violation must become.
 const BANNED: Array<{ label: string; re: RegExp; canon: string; exempt?: RegExp }> = [
-    { label: "thinking (our-voice)", re: /\bthinking\b/i, canon: "reasoning (the #472 lexicon ruling)", exempt: WIRE_THINKING },
-    { label: "contextSize", re: /\bcontextSize\b/, canon: "contextWindow — the provider window (#472)" },
-    { label: "retired providers knob", re: /PLURNK_PROVIDERS_(THINKING|LOGPROB\b|CONTEXT_SIZE\b)/, canon: "PLURNK_PROVIDERS_{REASONING,TOP_LOGPROBS,CONTEXT_WINDOW} (#399/#472) — only the shed may name these" },
-    // #511: catch the retired run/session noun in the WIRE-HEADER form too (a
+    { label: "thinking (our-voice)", re: /\bthinking\b/i, canon: "reasoning ({§lexicon})", exempt: WIRE_THINKING },
+    { label: "contextSize", re: /\bcontextSize\b/, canon: "contextWindow — the provider window ({§model-fact-resolution})" },
+    { label: "retired providers knob", re: /PLURNK_PROVIDERS_(THINKING|LOGPROB\b|CONTEXT_SIZE\b)/, canon: "PLURNK_PROVIDERS_{REASONING,TOP_LOGPROBS,CONTEXT_WINDOW} ({§provider-configuration}) — only the shed may name these" },
+    // Catch the retired run/session noun in the wire-header form too (a
     // quoted string, not an identifier — the hole the old `Plurnk-Run-Id` hid in),
     // alongside the coordinate identifiers.
-    { label: "run/session (retired noun — coordinate or wire header)", re: /\b(sessionId|runId)\b|Plurnk-(Run|Session)-Id/, canon: "workerId/workspaceId, Plurnk-Worker-Id/Plurnk-Workspace-Id (#486/#511)" },
+    { label: "run/session (retired noun — coordinate or wire header)", re: /\b(sessionId|runId)\b|Plurnk-(Run|Session)-Id/, canon: "workerId/workspaceId, Plurnk-Worker-Id/Plurnk-Workspace-Id ({§lifecycle-terms})" },
 ];
 
 test("retired provider terms never reappear in src or SPEC — drift fails CI, not the next audit", () => {

package/src/notices.ts

@@ -0,0 +1,22 @@
+export type ProviderNoticeKind = "grammar_unenforced";
+
+// Observations about a completed model exchange. These never represent a
+// failed provider operation; transport failures throw ProviderError with an
+// RFC 9457 Problem Details object.
+export interface ProviderNotice {
+    readonly source: string;
+    readonly kind: ProviderNoticeKind;
+    readonly level: "warn";
+    readonly message: string;
+    readonly position: number | null;
+}
+
+export const providerSource = (vendor: string): string => {
+    const raw = vendor.startsWith("provider:") ? vendor.slice("provider:".length) : vendor;
+    const normalized = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (normalized.length === 0) throw new TypeError("provider source must name a provider");
+    return `provider:${/^[a-z]/.test(normalized) ? normalized : `p-${normalized}`}`;
+};

package/src/ollama.test.ts

@@ -0,0 +1,64 @@
+import test, { mock } from "node:test";
+import { strict as assert } from "node:assert";
+import { ollamaProviderFromEnv } from "./ollama.ts";
+
+const env = Object.freeze({
+    PLURNK_PROVIDERS_FETCH_TIMEOUT: "1000",
+    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",
+    PLURNK_PROVIDERS_REASONING_RESERVE: "10%",
+    PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+    PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT: "512",
+    PLURNK_PROVIDERS_PROMPT_CACHE_KEY: "1",
+});
+
+test.afterEach(() => mock.restoreAll());
+
+// {§model-fact-resolution}
+test("#126: Ollama always probes model physics and applies an operator context-window ceiling", async () => {
+    const calls: string[] = [];
+    mock.method(globalThis, "fetch", async (input: string | URL | Request) => {
+        calls.push(String(input));
+        return new Response(JSON.stringify({
+            model_info: { "qwen.context_length": 32_768 },
+        }));
+    });
+
+    const windows: Array<number | null> = [];
+    for (const operatorCap of [undefined, "8192", "65536"] as const) {
+        const provider = await ollamaProviderFromEnv({
+            ...env,
+            ...(operatorCap === undefined ? {} : { PLURNK_PROVIDERS_CONTEXT_WINDOW: operatorCap }),
+        }, "qwen2.5-coder", { baseUrl: "http://ollama.test:11434/v1" });
+        windows.push(provider.contextWindow);
+    }
+
+    assert.deepEqual(windows, [32_768, 8_192, 32_768]);
+    assert.deepEqual(calls, Array.from({ length: 3 }, () => "http://ollama.test:11434/api/show"));
+});
+
+test("#126: an operator ceiling does not hide an Ollama probe HTTP failure", async () => {
+    mock.method(globalThis, "fetch", async () => new Response(null, { status: 503 }));
+    await assert.rejects(
+        () => ollamaProviderFromEnv({
+            ...env,
+            PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
+        }, "qwen2.5-coder", { baseUrl: "http://ollama.test:11434" }),
+        /ollama provider: \/api\/show returned 503/,
+    );
+});
+
+test("#126: an operator ceiling does not hide a missing Ollama model fact", async () => {
+    mock.method(globalThis, "fetch", async () => new Response(JSON.stringify({ model_info: {} })));
+    await assert.rejects(
+        () => ollamaProviderFromEnv({
+            ...env,
+            PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
+        }, "qwen2.5-coder", { baseUrl: "http://ollama.test:11434" }),
+        /ollama provider: \/api\/show has no \*\.context_length key for "qwen2\.5-coder"/,
+    );
+});

package/src/ollama.ts

@@ -1,5 +1,5 @@
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
-import { contextWindowFromEnv, parseRequiredInt, requireEnv } from "./env.ts";
+import { contextWindowFromEnv, effectiveContextWindow, parseRequiredInt, requireEnv } from "./env.ts";
 import { providerFromSdkModel } from "./catalogProvider.ts";
 import type { Provider, ProviderOptions } from "./types.ts";
 
@@ -46,8 +46,11 @@ export const ollamaProviderFromEnv = async (
         "PLURNK_PROVIDERS_FETCH_TIMEOUT",
         "ollama",
     );
-    const contextWindow = contextWindowFromEnv(env, "ollama")
-        ?? await fetchContextWindow({ baseUrl, model, timeout });
+    // {§model-fact-resolution}
+    const contextWindow = effectiveContextWindow(
+        contextWindowFromEnv(env, "ollama"),
+        await fetchContextWindow({ baseUrl, model, timeout }),
+    );
     const languageModel = createOpenAICompatible({
         name: "ollama",
         baseURL: `${baseUrl}/v1`,

package/src/openai.ts

@@ -5,8 +5,11 @@ export type {
     FinishReason,
     Provider,
     ProviderAssistant,
+    ProviderAttempt,
+    ProviderAttemptFinishReason,
     ProviderResponse,
     ProviderUsage,
+    PromptTokenMeasurement,
     TokenAlternative,
     TokenLogprob,
 } from "./types.ts";

package/src/promptTokens.ts

@@ -0,0 +1,41 @@
+import type { ChatMessage, PromptTokenMeasurement } from "./types.ts";
+
+const KINDS = new Set<PromptTokenMeasurement["kind"]>([
+    "exact",
+    "upper_bound",
+    "estimate",
+]);
+
+export const assertPromptTokenMeasurement = (
+    value: unknown,
+    owner = "provider",
+): PromptTokenMeasurement => {
+    if (typeof value !== "object" || value === null) {
+        throw new TypeError(`${owner}: prompt token measurement must be an object`);
+    }
+    const candidate = value as Partial<PromptTokenMeasurement>;
+    if (!KINDS.has(candidate.kind as PromptTokenMeasurement["kind"])) {
+        throw new TypeError(`${owner}: prompt token measurement has invalid kind ${JSON.stringify(candidate.kind)}`);
+    }
+    if (!Number.isInteger(candidate.tokens) || candidate.tokens! < 0) {
+        throw new TypeError(`${owner}: prompt token measurement tokens must be a non-negative integer`);
+    }
+    if (typeof candidate.source !== "string" || candidate.source.length === 0) {
+        throw new TypeError(`${owner}: prompt token measurement source must be a non-empty string`);
+    }
+    if (candidate.kind === "estimate"
+        && (typeof candidate.detail !== "string" || candidate.detail.length === 0)) {
+        throw new TypeError(`${owner}: estimated prompt token measurement requires detail`);
+    }
+    return value as PromptTokenMeasurement;
+};
+
+export const estimatePromptTokens = (
+    messages: readonly ChatMessage[],
+    detail = "chars/2 over message content; provider request framing is unknown",
+): PromptTokenMeasurement => ({
+    kind: "estimate",
+    tokens: Math.ceil(messages.reduce((sum, { content }) => sum + content.length, 0) / 2),
+    source: "heuristic:chars2",
+    detail,
+});

package/src/sdkModels.test.ts

@@ -37,6 +37,13 @@ test("createSdkModel expands catalog endpoint variables without treating them as
     });
 });
 
+test("#157: a cataloged compatible provider fails before transport when its declared credential is absent", () => {
+    assert.throws(
+        () => createSdkModel("deepseek", "deepseek-v4-flash", {}),
+        /deepseek provider: DEEPSEEK_API_KEY must be set/,
+    );
+});
+
 test("createSdkModel fails clearly for a declared but unsupported SDK package", () => {
     assert.throws(
         () => createSdkModel("acme", "model", {

package/src/sdkModels.ts

@@ -85,12 +85,6 @@ const baseUrl = (
     return value === undefined ? undefined : expandEnv(value, env, provider).replace(/\/+$/, "");
 };
 
-const apiKey = (
-    provider: string,
-    env: NodeJS.ProcessEnv,
-    catalog: ProviderInfo,
-): string | undefined => firstSet(env, configuredKeyNames(provider, env, catalog));
-
 const requireApiKey = (
     provider: string,
     env: NodeJS.ProcessEnv,
@@ -179,12 +173,14 @@ export const createSdkModel = (
             };
         case "@ai-sdk/openai-compatible":
             if (url === undefined) throw new Error(`${provider} provider: Models.dev supplies no API URL and no base URL was configured`);
+            const keyNames = configuredKeyNames(provider, env, catalog);
+            const key = keyNames.length === 0 ? undefined : requireApiKey(provider, env, catalog);
             return {
                 compatible: {
                     url: `${url}/chat/completions`,
-                    headers: apiKey(provider, env, catalog) === undefined
+                    headers: key === undefined
                         ? {}
-                        : { Authorization: `Bearer ${apiKey(provider, env, catalog)}` },
+                        : { Authorization: `Bearer ${key}` },
                 },
                 catalog,
             };

package/src/types.ts

@@ -1,15 +1,36 @@
 // Provider transport contract. Providers return raw wire-level output —
-// content unparsed (consumer parses via @plurnk/plurnk-grammar), reasoning
+// content unparsed (consumer parses via @plurnk/plurnk-contracts), reasoning
 // is the wire-reported CoT only.
 
-import type { TelemetryEvent } from "./telemetry.ts";
+import type { ProviderNotice } from "./notices.ts";
 import type { LanguageModel } from "ai";
+import type {
+    PluginAttribution,
+    PluginAttributionContext,
+    PluginAttributionSource,
+} from "@plurnk/plurnk-meta";
+import type { ProviderCost } from "@plurnk/plurnk-contracts";
 
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
 }
 
+// Preflight evidence for the complete provider request. An empirical estimate
+// is useful telemetry but cannot authorize a hard physical-capacity decision.
+export type PromptTokenMeasurement =
+    | {
+        readonly kind: "exact" | "upper_bound";
+        readonly tokens: number;
+        readonly source: string;
+    }
+    | {
+        readonly kind: "estimate";
+        readonly tokens: number;
+        readonly source: string;
+        readonly detail: string;
+    };
+
 // Normalized token accounting. Invariant (enforced by normalizeUsage at the
 // provider boundary): total = prompt + completion + reasoning; cached is a
 // subset of prompt. `completion` is visible output EXCLUDING reasoning; the
@@ -23,11 +44,14 @@ export interface ProviderUsage {
     readonly total: number;        // prompt + completion + reasoning
 }
 
-// Closed set per SPEC §2. Relay/aggregator providers MUST normalize wire
-// values back to one of these at the provider boundary.
+export type AuthoritativeCharge = Extract<ProviderCost, { kind: "authoritative" }>;
+
+// A successful exchange's closed finish set. ProviderAttemptFinishReason adds
+// the failed disposition that may occur only on ProviderError attempt evidence.
 export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | null;
+export type ProviderAttemptFinishReason = FinishReason | "resource_interrupted";
 
-// A per-token logprob (#36, SPEC §14). `logprob` is the backend's RAW model
+// {§provider-evidence} A per-token logprob. `logprob` is the backend's raw model
 // log-probability of the emitted token — the sampling-transform-invariant
 // confidence, chosen over Fireworks' post-mask `sampling_logprob` (measured
 // IDENTICAL under grammar, incl. an adversarial mask; the raw value is the honest
@@ -45,20 +69,24 @@ export interface TokenLogprob {
     readonly top?: readonly TokenAlternative[];
 }
 
-export interface ProviderAssistant {
+// {§provider-encrypted-reasoning} `id` is provider detail identity; `subtype`
+// is the provider's evidence-backed classification. Neither is a client entity
+// correlation, so consumers must not substitute `id` for a message/tool-call ID.
+export interface ProviderEncryptedReasoningItem {
+    readonly id: string | null;
+    readonly subtype: string;
+    readonly encrypted: ReadonlyArray<{ data: string; format: string | null }>;
+}
+
+export interface ProviderAssistant<TFinish extends ProviderAttemptFinishReason = FinishReason> {
     readonly content: string;
     readonly reasoning: string | null;
-    // Sealed reasoning (#482): a relay backend (OpenRouter fronting OpenAI
-    // o-series) returns the chain-of-thought ENCRYPTED — surfaced verbatim as
-    // items { id, subtype, encrypted: [{data, format}] } (id from the wire,
-    // subtype from wire position), never decoded, never synthesized. Readable text
-    // stays on `reasoning`. Absent when the turn produced none; consumers (agui)
-    // project it as REASONING_ENCRYPTED_VALUE.
-    readonly reasoningEncrypted?: ReadonlyArray<{ id: string | null; subtype: string; encrypted: ReadonlyArray<{ data: string; format: string | null }> }>;
+    // Encrypted reasoning remains distinct from readable `reasoning`.
+    readonly reasoningEncrypted?: ReadonlyArray<ProviderEncryptedReasoningItem>;
     readonly usage: ProviderUsage;
-    readonly finishReason: FinishReason;
+    readonly finishReason: TFinish;
     readonly model: string;
-    // Per-token logprobs (#36), present ONLY when PLURNK_PROVIDERS_TOP_LOGPROBS is set
+    // Per-token logprobs, present only when PLURNK_PROVIDERS_TOP_LOGPROBS is set
     // AND the backend returned them. Absent otherwise — NEVER synthesized. Opt-in,
     // per-alias: a scraping alias enables it; serving turns carry nothing.
     readonly logprobs?: readonly TokenLogprob[];
@@ -66,42 +94,59 @@ export interface ProviderAssistant {
     readonly meanLogprob?: number;
 }
 
-export interface ProviderResponse {
-    readonly assistant: ProviderAssistant;
+export interface GrammarEvidence {
+    // Exact sentence observed at the grammar boundary before any reasoning/content
+    // projection. Offsets are Unicode code points, matching @plurnk/gbnf verdicts.
+    readonly input: string;
+    readonly contentStart: number;
+    readonly transported: boolean;
+}
+
+export interface ProviderResponse<TFinish extends ProviderAttemptFinishReason = FinishReason> {
+    readonly assistant: ProviderAssistant<TFinish>;
     readonly assistantRaw: unknown;
+    // A settled upstream charge is a validated public fact, not opaque metadata.
+    // Non-USD settlement carries an explicit provider-owned USD equivalent for
+    // the platform's existing USD aggregate. Core never supplies an FX rate.
+    readonly charge?: AuthoritativeCharge;
+    // {§gbnf-response-observation} — evidence only; the consumer owns the verdict.
+    readonly grammarEvidence?: GrammarEvidence;
     // Per-turn provider→client metadata bag: the backend's non-standard top-level
     // response fields passed through verbatim. Monetary values carry their own
     // amount and currency; the provider does not reinterpret them. The consumer
     // (service) merges this into its Turn metadata and
     // filters what reaches the client; it reads `meta`, never mines `assistantRaw`.
-    // Absent when the backend reported no extra fields (#23, generalized).
+    // Absent when the backend reported no extra fields.
     readonly meta?: Record<string, unknown>;
-    // The VERBATIM backend response body (#36, SPEC §14) — the full wire JSON for
+    // The verbatim backend response body ({§provider-evidence}) — the full wire JSON for
     // a non-streamed turn, or the reassembled equivalent for a streamed one.
     // `assistantRaw` is a normalized DIGEST (it drops choices[]); this is the
     // capture-everything record for the endpoint's fine-tune corpus. Present ONLY
     // when PLURNK_PROVIDERS_RAWBODY is on — off by default so serving turns never
     // carry it. Absent otherwise.
     readonly rawBody?: unknown;
-    // Observations attached to a COMPLETED exchange (#24, SPEC §13). The model's
-    // bytes always flow through `assistant`; these events annotate them. Today: a
-    // `grammar_unenforced` event whenever the output diverges from the grammar —
-    // transported OR withheld (filter mode) — carrying the divergence `position`.
-    // The provider never adjudicates conformance; discard/retry/escalate/
-    // self-correct is consumer policy. Absent when the turn produced no telemetry.
-    readonly telemetry?: readonly TelemetryEvent[];
+    // Notices attached to the represented attempt. Successful
+    // returns may relay them; interrupted attempt notices remain forensic.
+    // Grammar conformance itself is consumer-owned.
+    readonly notices?: readonly ProviderNotice[];
 }
 
+export type ProviderAttempt = ProviderResponse<ProviderAttemptFinishReason>;
+
 export interface Provider {
-    // `grammar` is an optional GBNF string (canonically @plurnk/plurnk-grammar's
+    // Optional package-authored folksonomy evaluated by the consumer immediately
+    // before a provider emission attempt ({§plugin-attribution}).
+    attributions?(context: PluginAttributionContext): PluginAttribution;
+    // `grammar` is an optional GBNF string (canonically @plurnk/plurnk-contracts'
     // plurnk.gbnf, possibly root-substituted by the consumer). Backends that
     // support grammar-constrained sampling attach it verbatim; all others
     // ignore it. The provider never chooses or modifies the grammar — whether
-    // to constrain and which root variant to send is consumer policy (SPEC §13).
+    // to constrain and which root variant to send is consumer policy
+    // ({§gbnf-response-observation}).
     //
     // `maxTokens` is the consumer's per-call output ceiling (wire `max_tokens`).
     // Without it, most servers generate UNBOUNDED (llama-server n_predict -1) —
-    // under a multi-op grammar that degenerates to the context wall (SPEC §13),
+    // under a multi-op grammar that degenerates to the context wall,
     // so a constrained consumer is expected to pass it. Policy stays the
     // consumer's; the provider only transports.
     //
@@ -109,70 +154,64 @@ export interface Provider {
     // stream (loop/run). Providers MAY key backend affinity on it — e.g.
     // llama-server slot pinning for KV-cache reuse — and MUST NOT interpret
     // its content. The consumer never sees or chooses backend resources
-    // (slot integers, connections); the *mechanism* is the provider's (#11).
+    // (slot integers, connections); the mechanism is the provider's.
     //
-    // `attributions` (per-turn, runtime-observed) and `client` (workspace-stable,
-    // self-identified) are first-party telemetry the consumer hands down: which
-    // installed plugin packages dispatched this turn, and which frontend
-    // originated the worker. They are forwarded ONLY by a provider whose spec opts
-    // in (the first-party `plurnk` endpoint, via `Plurnk-Attribution` /
-    // `Plurnk-Client` headers); every other provider DROPS them — the gate is
-    // structural so first-party metadata can never leak to a third-party backend.
+    // `attributions` is opaque consumer-supplied creator telemetry; the consumer
+    // owns what contribution that set claims ({§attribution}). `client` is the
+    // consumer's workspace-stable, self-identified frontend. They are forwarded ONLY by a
+    // provider whose spec opts in (the first-party `plurnk` endpoint, via
+    // `Plurnk-Attribution` / `Plurnk-Client` headers); every other provider DROPS
+    // them — the gate is structural so first-party metadata can never leak to a
+    // third-party backend.
     //
     // `sampling` is an optional bag of standard OpenAI-compat sampling params
     // (temperature, top_p, top_k, min_p, penalties, stop, seed, …) forwarded into
     // the request body UNDER the provider's managed fields — model/messages/grammar/
     // reasoning/max_tokens/slot always win, and transport/protocol keys (stream,
     // response_format, grammar, id_slot) are stripped, so it carries sampling intent
-    // only and can't bypass grammar transport (SPEC §8 holds). A PROXY consumer (the
+    // only and can't bypass grammar transport ({§provider-request-authority}). A
+    // proxy consumer (the
     // plurnk endpoint fronting its own backends) uses it to pass its caller's sampling
     // knobs through; a direct consumer typically leaves it unset.
     //
     // `strikes` is the worker's CURRENT rail-strike streak at time-of-generate
-    // (0 = clean; a clean turn zeroes it; every loop starts at 0 — contract:
-    // plurnk-service#313). Forwarded as a `Plurnk-Strikes` header ONLY under the
+    // (0 = clean; a clean turn zeroes it; every loop starts at 0 — contract
+    // {§strikes-first-party-metadata}). Forwarded as a `Plurnk-Strikes` header ONLY under the
     // same firstPartyMetadata gate as attributions/client; dropped everywhere
     // else. Headers only — the packet NEVER carries strike state (the model must
     // not see engine accounting; it would become a metric to game).
     //
-    // `workspaceId`/`loop`/`turn` (#404, per #391) are the turn COORDINATE — the
+    // `workspaceId`/`loop`/`turn` are the turn coordinate ({§lifecycle-terms}) — the
     // daemon-side sequence of the turn being generated, which the endpoint can
     // never scrape from the wire. Forwarded as `Plurnk-Workspace-Id`/`Plurnk-Loop`/
     // `Plurnk-Turn` ONLY under the same firstPartyMetadata gate; dropped
     // everywhere else. Coordinates are 1-based: absent/0 emits no header (no
     // strikes-style zero exception). Headers only, never the packet.
     generate(args: { 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>;
-    // The model's context window in tokens. The provider RESOLVES it (operator pin
-    // -> live probe -> @plurnk/plurnk-models catalog). A CLOUD provider (no probe)
-    // FAILS AT CONSTRUCTION when it can't (#419/#417: never budget against a wrong
-    // number). A PROBING provider (openai/llama-server) instead DEGRADES to null on a
-    // probe miss - a blip must not crash it (#34) - and surfaces it once
-    // (PLURNK_CONTEXT_UNKNOWN). So null still means "window unknown -> no cap"; the
-    // consumer must NOT improvise a stand-in from it (#421). NOTE: under llama-server
-    // --parallel N, the window is PER SLOT (the server splits --ctx-size across slots
-    // and reports the divided value).
+    // {§model-fact-resolution} — effective physical context in tokens. `null`
+    // means unknown; under llama-server parallelism the probed value is per slot.
     readonly contextWindow: number | null;
     readonly model: string;
-    // OPTIONAL (#37): the backend's SELF-REPORTED served model id, from a
+    // Optional: the backend's self-reported served model id, from a
     // /v1/models-shaped probe (llama-server today; any such backend). For a local
     // alias, `model` is the alias but this is the real served name (the .gguf) the
     // tokenizer seam maps exactly. Read-only, best-effort, no extra probing —
     // absent when no probe ran. Consumers resolve `servedModel ?? model`.
     readonly servedModel?: string;
-    // OPTIONAL resolved capability (#34): true when a transported grammar will
+    // Optional resolved capability: true when a transported grammar will
     // actually constrain the decode (rails LIVE), false/undefined otherwise —
     // introspectable so the consumer can fail hard on a dark-rails boot instead
     // of discovering it from unconstrained emissions.
     readonly constrainsOutput?: boolean;
-    // OPTIONAL resolved capability (#43): true when this backend decodes
+    // Optional resolved capability: true when this backend decodes
     // UNBOUNDED absent a caller cap — llama-server honors n_predict to the
-    // context wall (the 30,736-junk-token wall-run, providers#10), so a consumer
-    // MUST bring an output envelope (SPEC §13). Cloud backends that silently
+    // context wall (observed in a 30,736-junk-token wall run), so a consumer
+    // MUST bring an output envelope ({§provider-generation-envelope}). Cloud backends that silently
     // clamp an over-ask (fireworks/xai, verified live) never set this; undefined
     // = no claim. Introspectable so a consumer can refuse AT BOOT a local alias
     // with no declared envelope, instead of dying mid-turn in partition math.
     readonly requiresMaxTokens?: boolean;
-    // OPTIONAL generation-envelope reserves (#507, owner-ruled) — the amounts OF
+    // Optional generation-envelope reserves ({§provider-generation-envelope}) — the amounts of
     // the DETECTED window reserved for reasoning and completion: floor
     // percentages of `contextWindow`, or absolute per-alias pins that win
     // outright. The consumer's prompt budget is `contextWindow - reasoningReserve
@@ -182,22 +221,25 @@ export interface Provider {
     // as null). All first-party providers claim, so null means genuinely-unknown.
     readonly reasoningReserve?: number | null;
     readonly completionReserve?: number | null;
-    // Provider-owned tokenizer. Synchronous, non-negative integer. Without an
-    // exact family configured this is the chars/2 UPPER BOUND (surfaced at
-    // construction, never silent) — safe for refusal math, not an exact count.
-    countTokens(text: string): number;
+    // Provider-owned preflight measurement of the complete chat request,
+    // including provider/template framing when the adapter can know it.
+    // Estimates are explicit and MUST NOT authorize hard physical admission.
+    countPromptTokens(messages: readonly ChatMessage[], signal?: AbortSignal): Promise<PromptTokenMeasurement>;
     // OPTIONAL capability: exact tokenization served by the backend's own vocab
     // (llama-server /tokenize) — token ids in the model's real vocabulary.
     // Present ONLY when the backend exposes such an endpoint (probe-gated);
     // `tokenize === undefined` means the backend can't. Exact-counting
     // consumers (the tokenizer seam) prefer this over any client-side data.
     tokenize?(text: string): Promise<number[]>;
-    // Provider-owned estimated cost calculation. Returns USD.
-    // Returns 0 for siblings/models with no known rates.
+    // {§model-fact-resolution} — frozen 1.x local USD estimate compatibility.
+    // Consumers adapt its zero to unknown; only calculateCharge can prove free.
     calculateCost(usage: ProviderUsage): number;
+    // Current monetary result. The numeric calculateCost surface remains frozen
+    // for 1.x compatibility; zero on that legacy surface cannot prove `free`.
+    calculateCharge?(usage: ProviderUsage): Exclude<ProviderCost, AuthoritativeCharge>;
 }
 
-// ProviderAlias moved to @plurnk/plurnk-aliases (the zero-dep parser, #27);
+// ProviderAlias lives in @plurnk/plurnk-aliases (the zero-dependency parser);
 // index.ts re-exports it so the "." surface is unchanged.
 
 // Per-alias instantiation overrides, threaded from the alias cascade into the
@@ -211,6 +253,6 @@ export interface ProviderOptions {
 
 // A discovered provider plugin default-exports an AI SDK provider. PLURNK owns
 // the adapter into Provider; the plugin owns only its protocol binding.
-export interface AiSdkProviderPlugin {
+export interface AiSdkProviderPlugin extends PluginAttributionSource {
     languageModel(model: string): LanguageModel;
 }