@plurnk/plurnk-providers 1.6.1 → 1.8.0

package/src/compatibleProvider.ts

@@ -182,6 +182,7 @@ export const compatibleProviderFromEnv = async (
     }
     const envelope = generationEnvelopeFromEnv(env, provider, contextWindow, null);
     const reasoning = reasoningFromEnv(env, provider, envelope.reasoningBudget);
+    const supportedReasoningPolicies = ["off", "adaptive"] as const;
     return new AiSdkProvider({
         model,
         url,
@@ -191,6 +192,7 @@ export const compatibleProviderFromEnv = async (
         maxOutputTokens: null,
         outputBudget: envelope.outputBudget,
         reasoningBudget: reasoning.budget,
+        supportedReasoningPolicies,
         fetchTimeoutMs: timeout,
         operationTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_OPERATION_TIMEOUT, "PLURNK_PROVIDERS_OPERATION_TIMEOUT", provider),
         firstContentTimeoutMs: parseTimeoutMs(env.PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT, "PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT", provider),

package/src/cost.ts

@@ -132,8 +132,9 @@ export const addDecimals = (values: readonly string[]): string => {
 };
 
 export const sumProviderCostsUsd = (costs: readonly ProviderCost[]): string | null => {
-    const values = costs.map(providerCostUsd);
-    return values.some((value) => value === null)
-        ? null
-        : addDecimals(values as string[]);
+    // {§tokenomics-provider-usage} — a request without USD-expressible cost
+    // (an uncataloged model, or a response-less failure) is skipped; it never
+    // erases the expressible evidence. Null only when nothing is expressible.
+    const values = costs.map(providerCostUsd).filter((value): value is string => value !== null);
+    return values.length === 0 ? null : addDecimals(values);
 };

package/src/discover.test.ts

@@ -47,6 +47,33 @@ test("discover: a provider package missing plurnk.name is ignored, not crashed",
     assert.deepEqual([...registry.keys()], ["named"]);
 });
 
+test("{§provider-grammar-transport} discover: the manifest grammarStyle declaration is recorded and validated", async (t) => {
+    const root = await buildModules(t, {
+        "@acme/llamacpp-rail": {
+            name: "@acme/llamacpp-rail",
+            plurnk: { kind: "provider", name: "rail", grammarStyle: "llamacpp" },
+        },
+        "@acme/plain": {
+            name: "@acme/plain",
+            plurnk: { kind: "provider", name: "plain" },
+        },
+    });
+    const { grammarStyles } = await discover({ cwd: root });
+    assert.equal(grammarStyles.get("rail"), "llamacpp");
+    assert.equal(grammarStyles.get("plain"), "none");
+    assert.equal(grammarStyles.get("absent"), undefined);
+});
+
+test("{§provider-grammar-transport} discover: an invalid grammarStyle fails loudly, never guessing", async (t) => {
+    const root = await buildModules(t, {
+        "@acme/bad-grammar": {
+            name: "@acme/bad-grammar",
+            plurnk: { kind: "provider", name: "bad", grammarStyle: "guff" },
+        },
+    });
+    await assert.rejects(discover({ cwd: root }), /grammarStyle must be "none" or "llamacpp"/);
+});
+
 test("discover: an array kind claims no provider family", async (t) => {
     const root = await buildModules(t, {
         "@acme/dual": {

package/src/discover.ts

@@ -6,6 +6,7 @@ import type {
     PluginAttribution,
     PluginAttributionDeclaration,
 } from "@plurnk/plurnk-meta";
+import type { GrammarStyle } from "./AiSdkProvider.ts";
 
 // Scope-agnostic discovery of installed AI SDK provider packages
 // ({§plugin-family-kind}).
@@ -40,6 +41,9 @@ export type Discovery = {
     // Published name-keyed projection retained for 1.x consumers.
     attributions: Map<string, string | string[]>;
     packageAttributions: PackageAttributions;
+    // {§provider-grammar-transport} — plugin-declared constrained-decoding
+    // capability per provider name; "none" unless the manifest declares one.
+    grammarStyles: Map<string, GrammarStyle>;
 };
 
 
@@ -51,6 +55,7 @@ export const discover = async (options: DiscoverOptions = {}): Promise<Discovery
     const skipped = new Map<string, string>();
     const attributions = new Map<string, PluginAttributionDeclaration>();
     const packageAttributions = new Map<string, PluginAttribution>();
+    const grammarStyles = new Map<string, GrammarStyle>();
     for (const dir of dirs) {
         const info = await readProviderInfo(dir);
         if (info === null) continue;
@@ -67,11 +72,12 @@ export const discover = async (options: DiscoverOptions = {}): Promise<Discovery
         }
         const tags = Meta.normalizeAttribution(info.attribution, info.packageName);
         registry.set(info.name, info.packageName);
+        grammarStyles.set(info.name, info.grammarStyle);
         const attribution = attributionProjection(info.attribution, tags);
         if (attribution !== undefined) attributions.set(info.name, attribution);
         if (tags.length > 0) packageAttributions.set(info.packageName, tags);
     }
-    return { registry, skipped, attributions, packageAttributions };
+    return { registry, skipped, attributions, packageAttributions, grammarStyles };
 };
 
 // Enumerate every installed package directory — scoped and unscoped — under
@@ -84,7 +90,7 @@ const defaultPackageDirs = async (cwd: string): Promise<string[]> => {
 // One inert manifest record for a provider package, or null for anything that
 // isn't one. Attribution remains unknown until trust admission, then the shared
 // {§plugin-attribution} boundary validates it.
-type ProviderInfo = { name: string; packageName: string; attribution: unknown };
+type ProviderInfo = { name: string; packageName: string; attribution: unknown; grammarStyle: GrammarStyle };
 
 const readProviderInfo = async (dir: string): Promise<ProviderInfo | null> => {
     let raw: string;
@@ -107,7 +113,18 @@ const readProviderInfo = async (dir: string): Promise<ProviderInfo | null> => {
     if (!Meta.declaresKind(plurnkRec, "provider")) return null;
     if (typeof plurnkRec.name !== "string" || plurnkRec.name === "") return null;
     if (typeof record.name !== "string" || record.name === "") return null;
-    return { name: plurnkRec.name, packageName: record.name, attribution: plurnkRec.attribution };
+    const grammarStyle = plurnkRec.grammarStyle;
+    if (grammarStyle !== undefined && grammarStyle !== "none" && grammarStyle !== "llamacpp") {
+        throw new Error(
+            `${record.name}: plurnk.grammarStyle must be "none" or "llamacpp", got ${JSON.stringify(grammarStyle)}.`,
+        );
+    }
+    return {
+        name: plurnkRec.name,
+        packageName: record.name,
+        attribution: plurnkRec.attribution,
+        grammarStyle: grammarStyle === undefined ? "none" : grammarStyle,
+    };
 };
 
 const attributionProjection = (

package/src/env.test.ts

@@ -48,14 +48,14 @@ test("parseOptionalInt: rejects fractional and negative values", () => {
     assert.throws(() => parseOptionalInt("-8", "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), /must be a non-negative integer/);
 });
 
-test("reasoningFromEnv: activation is independent from an optional explicit budget", () => {
+test("reasoningFromEnv: durable policy is independent from an optional explicit budget", () => {
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "off" }, "openai"), { mode: "off", budget: null });
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai"), { mode: "adaptive", budget: null });
-    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on" }, "openai"), { mode: "on", budget: null });
-    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on" }, "openai", 4096), { mode: "on", budget: 4096 });
+    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "high" }, "openai"), { mode: "high", budget: null });
+    assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "high" }, "openai", 4096), { mode: "high", budget: 4096 });
     assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai", 4096), { mode: "adaptive", budget: 4096 });
     assert.throws(() => reasoningFromEnv({}, "openai"), /PLURNK_PROVIDERS_REASONING must be set/);
-    assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "8192" }, "openai"), /must be one of "off", "adaptive", "on"/); // the old numeric habit fails loudly
+    assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "8192" }, "openai"), /must be one of "off", "adaptive", "low", "medium", "high"/); // the old numeric habit fails loudly
 });
 
 test("{§provider-tagged-reasoning} response style is explicit and invalid values fail at the provider boundary", () => {
@@ -108,7 +108,7 @@ test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases i
     const { scopeEnvToAlias } = await import("./env.ts");
     const env = {
         PLURNK_PROVIDERS_REASONING: "off",
-        PLURNK_PROVIDERS_REASONING_turboderp: "on",
+        PLURNK_PROVIDERS_REASONING_turboderp: "high",
         PLURNK_PROVIDERS_REASONING_BUDGET_TURBODERP: "4096", // case-folds like PLURNK_MODEL_ keys
         PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_TURBODERP: "think-tags",
         PLURNK_PROVIDERS_CONTEXT_WINDOW_turboderp: "8000",
@@ -116,7 +116,7 @@ test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases i
         PLURNK_PROVIDERS_CONTEXT_WINDOW_other: "1",
     } as NodeJS.ProcessEnv;
     const scoped = scopeEnvToAlias(env, "turboderp");
-    assert.equal(scoped.PLURNK_PROVIDERS_REASONING, "on");
+    assert.equal(scoped.PLURNK_PROVIDERS_REASONING, "high");
     assert.equal(scoped.PLURNK_PROVIDERS_REASONING_BUDGET, "4096");
     assert.equal(scoped.PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE, "think-tags");
     assert.equal(scoped.PLURNK_PROVIDERS_CONTEXT_WINDOW, "8000");
@@ -185,7 +185,7 @@ test("scopeEnvToAlias: a caller-supplied knob list scopes consumer-owned vars",
     assert.equal(cloud.PLURNK_SERVICE_LOOP_TIMEOUT, "16384"); // 64k envelope untouched by gemma overrides
     assert.equal(cloud.PLURNK_SERVICE_EXEC_HOLD_MS, "49152");
     // custom list does NOT scope providers-family knobs (closed-list isolation both ways)
-    const mixed = scopeEnvToAlias({ PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_REASONING_turboderp: "on" } as NodeJS.ProcessEnv, "turboderp", SERVICE_KNOBS);
+    const mixed = scopeEnvToAlias({ PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_REASONING_turboderp: "high" } as NodeJS.ProcessEnv, "turboderp", SERVICE_KNOBS);
     assert.equal(mixed.PLURNK_PROVIDERS_REASONING, "off");
 });
 
@@ -224,11 +224,26 @@ test("still-set old THINKING names fail hard with the rename pointer", () => {
     );
 });
 
+test("reasoning policy accepts only the exact portable durable vocabulary", () => {
+    for (const mode of ["off", "adaptive", "low", "medium", "high"] as const) {
+        assert.deepEqual(reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: mode }, "openai"), {
+            mode,
+            budget: null,
+        });
+    }
+    for (const retired of ["on", "minimal", "xhigh"]) {
+        assert.throws(
+            () => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: retired }, "openai"),
+            /must be one of "off", "adaptive", "low", "medium", "high"/,
+        );
+    }
+});
+
 test("the shipped floor defers reasoning posture to the provider by default (adaptive)", async () => {
     const { readFileSync } = await import("node:fs");
     const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
     assert.ok(defaults.includes("PLURNK_PROVIDERS_REASONING=adaptive"), "floor must ship REASONING=adaptive");
-    assert.ok(!defaults.match(/^PLURNK_PROVIDERS_REASONING_BUDGET=/m), "no shipped magnitude — an explicit on-mode budget is optional");
+    assert.ok(!defaults.match(/^PLURNK_PROVIDERS_REASONING_BUDGET=/m), "no shipped magnitude — provider-adaptive depth remains unpinned");
 });
 
 test("the shipped DRY floor is off and claims no universally safe shape", async () => {

package/src/env.ts

@@ -1,6 +1,8 @@
 // Env-parsing helpers shared by provider construction. `label` keeps failures
 // local to the selected provider.
 
+import { REASONING_POLICIES, Validator, type ReasoningPolicy } from "@plurnk/plurnk-contracts";
+
 export const parseRequiredInt = (raw: string | undefined, name: string, label: string): number => {
     if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set`);
     const n = Number(raw);
@@ -231,15 +233,22 @@ export const resolveGenerationEnvelopeFromEnv = (
     );
 };
 
-// {§provider-configuration} The side-channel reasoning knobs — activation and budget
-// are separate vars, so a numeric budget can never silently flip wire flags:
-//   PLURNK_PROVIDERS_REASONING           off | adaptive | on   (REQUIRED, fail-hard)
+// {§provider-configuration} The side-channel reasoning knobs — policy and budget
+// are separate vars, so a numeric budget can never silently select an effort:
+//   PLURNK_PROVIDERS_REASONING  off | adaptive | low | medium | high (REQUIRED, fail-hard)
 //   PLURNK_PROVIDERS_REASONING_BUDGET  optional reasoning subset of the total
 //     output budget, used for tier/budget mapping where the backend supports it.
 // The provider maps intent to the backend's mechanism; the consumer states
 // intent, never mechanism. PLAN is a separate public intended-goals record.
-export type ReasoningMode = "off" | "adaptive" | "on";
-export type Reasoning = { mode: ReasoningMode; budget: number | null };
+export type Reasoning = { mode: ReasoningPolicy; budget: number | null };
+
+export const parseReasoningPolicy = (value: unknown, label: string): ReasoningPolicy => {
+    const result = Validator.validateReasoningPolicy(value);
+    if (!result.valid) {
+        throw new Error(`${label} must be one of ${REASONING_POLICIES.map((policy) => `"${policy}"`).join(", ")} (got "${String(value)}")`);
+    }
+    return value as ReasoningPolicy;
+};
 
 export type ReasoningResponseStyle = "verbatim" | "think-tags";
 
@@ -265,9 +274,9 @@ export const reasoningFromEnv = (
     shedRenamed(env, "PLURNK_PROVIDERS_THINKING_CAPACITY", "PLURNK_PROVIDERS_REASONING_BUDGET", label, "provider configuration contract"); // lexicon-allow
     const name = "PLURNK_PROVIDERS_REASONING";
     const raw = env[name];
-    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (off | adaptive | on)`);
-    if (raw !== "off" && raw !== "adaptive" && raw !== "on") throw new Error(`${label} provider: ${name} must be one of "off", "adaptive", "on" (got "${raw}")`);
-    return { mode: raw, budget: raw === "off" ? null : resolvedBudget };
+    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (${REASONING_POLICIES.join(" | ")})`);
+    const mode = parseReasoningPolicy(raw, `${label} provider: ${name}`);
+    return { mode, budget: mode === "off" ? null : resolvedBudget };
 };
 
 // ── Per-alias knob scoping (per-alias scoping doctrine, user 2026-07-03): PLURNK_PROVIDERS_<KNOB>[_<alias>] ──

package/src/errors.ts

@@ -1,19 +1,10 @@
-import { Problems, type ProblemDetails } from "@plurnk/plurnk-contracts";
 import { APICallError, RetryError } from "ai";
-import { providerSource } from "./notices.ts";
-import type { ProviderAttempt, ProviderRequestAccounting, ProviderRequestCapacity } from "./types.ts";
+import { ProviderError } from "./providerError.ts";
+import type { ProviderErrorKind } from "./providerError.ts";
+import type { ProviderRequestCapacity } from "./types.ts";
 
-export type ProviderErrorKind =
-    | "rate_limit"
-    | "network_failure"
-    | "deadline_exceeded"
-    | "model_refused"
-    | "invalid_response"
-    | "unauthorized"
-    | "quota_exceeded"
-    | "grammar_invalid"
-    | "capacity_exceeded"
-    | "resource_interrupted";
+export { ProviderError } from "./providerError.ts";
+export type { ProviderErrorKind } from "./providerError.ts";
 
 export interface ClassifiedProviderError {
     kind: ProviderErrorKind;
@@ -55,128 +46,6 @@ export const providerTimeoutOf = (error: unknown): ProviderTimeoutError | null =
     return null;
 };
 
-const defaultStatus = (kind: ProviderErrorKind): number => {
-    switch (kind) {
-        case "unauthorized": return 401;
-        case "quota_exceeded": return 402;
-        case "capacity_exceeded": return 413;
-        case "rate_limit": return 429;
-        case "model_refused":
-        case "grammar_invalid": return 422;
-        case "invalid_response": return 502;
-        case "deadline_exceeded": return 504;
-        case "network_failure":
-        case "resource_interrupted": return 503;
-    }
-};
-
-const retryable = (kind: ProviderErrorKind): boolean => {
-    switch (kind) {
-        case "rate_limit":
-        case "network_failure":
-            return true;
-        case "deadline_exceeded":
-        case "invalid_response":
-        case "grammar_invalid":
-        case "capacity_exceeded":
-        case "resource_interrupted":
-        case "model_refused":
-        case "unauthorized":
-        case "quota_exceeded":
-            return false;
-    }
-};
-
-const buildProblem = (
-    source: string,
-    kind: ProviderErrorKind,
-    message: string,
-    status: number,
-    extensions: Readonly<Record<string, unknown>>,
-    retryableOverride: boolean | undefined,
-): ProblemDetails => {
-    const code: Record<ProviderErrorKind, string> = {
-        rate_limit: "rate-limit",
-        network_failure: "network-failure",
-        deadline_exceeded: "deadline-exceeded",
-        model_refused: "model-refused",
-        invalid_response: "invalid-response",
-        unauthorized: "unauthorized",
-        quota_exceeded: "quota-exceeded",
-        grammar_invalid: "grammar-invalid",
-        capacity_exceeded: "capacity-exceeded",
-        resource_interrupted: "resource-interrupted",
-    };
-    return Problems.create(source, code[kind], status, message, {
-        providerKind: kind,
-        stage: "provider-request",
-        retryable: retryableOverride ?? retryable(kind),
-        ...extensions,
-    });
-};
-
-// A provider operation failed before a completed exchange existed. An
-// interrupted response may still carry attempt evidence for its consumer.
-// The standardized Problem is the public failure contract; kind remains the
-// provider pool's routing discriminator and is repeated as a Problem extension.
-export class ProviderError extends Error {
-    readonly source: string;
-    readonly kind: ProviderErrorKind;
-    readonly problem: ProblemDetails;
-    readonly attempt?: ProviderAttempt;
-    readonly capacity?: ProviderRequestCapacity;
-    #accounting: ProviderRequestAccounting[];
-
-    constructor(
-        source: string,
-        kind: ProviderErrorKind,
-        message: string,
-        options: {
-            status?: number | null;
-            cause?: unknown;
-            retryable?: boolean;
-            extensions?: Readonly<Record<string, unknown>>;
-            attempt?: ProviderAttempt;
-            accounting?: readonly ProviderRequestAccounting[];
-            capacity?: ProviderRequestCapacity;
-        } = {},
-    ) {
-        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        this.name = "ProviderError";
-        this.source = providerSource(source);
-        this.kind = kind;
-        this.attempt = options.attempt;
-        this.capacity = options.capacity ?? options.attempt?.capacity;
-        this.#accounting = [...(options.accounting ?? options.attempt?.accounting ?? [])];
-        const status = options.status !== null && options.status !== undefined
-            && Number.isInteger(options.status) && options.status >= 400 && options.status <= 599
-            ? options.status
-            : defaultStatus(kind);
-        this.problem = buildProblem(
-            this.source,
-            kind,
-            message,
-            status,
-            options.extensions ?? {},
-            options.retryable,
-        );
-    }
-
-    get status(): number {
-        return this.problem.status;
-    }
-
-    get accounting(): readonly ProviderRequestAccounting[] {
-        return this.#accounting;
-    }
-
-    // A capacity pool adds the already-settled requests from prior backends as
-    // the same failure crosses that orchestration boundary.
-    prependAccounting(accounting: readonly ProviderRequestAccounting[]): void {
-        if (accounting.length > 0) this.#accounting = [...accounting, ...this.#accounting];
-    }
-}
-
 const wireError = (body: string): { type: string | null; code: string | null; message: string | null } => {
     try {
         const { error } = JSON.parse(body) as { error?: { type?: unknown } };

package/src/index.ts

@@ -29,32 +29,40 @@ export type {
 export { assertPromptTokenMeasurement } from "./promptTokens.ts";
 export { assessRequestCapacity, effectiveInputCapacity, effectiveOutputBudget, requestCapacityDecision } from "./capacity.ts";
 
-// 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";
-export { parseAliasesFromEnv, resolveActiveAlias } from "@plurnk/plurnk-aliases";
+// Selector and alias parsing stay runtime-free in @plurnk/plurnk-aliases;
+// ModelRoute is the contracts-owned client wire shape; ProviderSpec is the
+// daemon-private construction identity that may retain an endpoint override.
+export type { ModelRoute, ProviderAlias, ProviderSpec } from "@plurnk/plurnk-aliases";
+export {
+    parseAliasesFromEnv,
+    resolveActiveRoute,
+    resolveModelSelector,
+} from "@plurnk/plurnk-aliases";
 
 export {
     instantiateProvider,
     loadActiveProvider,
     resetDiscoveryCache,
 } from "./ProviderRegistry.ts";
+export { providerReadiness } from "./sdkModels.ts";
 
 // 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 { default as AiSdkProvider } from "./AiSdkProvider.ts";
 export type { AiSdkProviderConfig, ReasoningStyle, GrammarStyle } from "./AiSdkProvider.ts";
 // {§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, reasoningResponseStyleFromEnv, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, effectiveContextWindow, generationEnvelopeFromEnv, resolveGenerationEnvelopeFromEnv, resolveTokenBudget, PROVIDERS_KNOBS } from "./env.ts";
-export type { GenerationEnvelope, Reasoning, ReasoningMode, ReasoningResponseStyle, TokenBudgetSpec } from "./env.ts";
+export { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv, parseReasoningPolicy, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, effectiveContextWindow, generationEnvelopeFromEnv, resolveGenerationEnvelopeFromEnv, resolveTokenBudget, PROVIDERS_KNOBS } from "./env.ts";
+export type { GenerationEnvelope, Reasoning, ReasoningResponseStyle, TokenBudgetSpec } from "./env.ts";
+export { REASONING_POLICIES } from "@plurnk/plurnk-contracts";
+export type { ReasoningPolicy } from "@plurnk/plurnk-contracts";
+export { UnsupportedReasoningPolicyError } from "./types.ts";
 export { normalizeUsage, calculateCostUsdDecimal, validateProviderUsage } from "./usage.ts";
 export {
     addDecimals,

package/src/notices.ts

@@ -1,4 +1,4 @@
-export type ProviderNoticeKind = "grammar_unenforced";
+export type ProviderNoticeKind = "grammar_unenforced" | "provider_warning";
 
 // Observations about a completed model exchange. These never represent a
 // failed provider operation; transport failures throw ProviderError with an

package/src/openai.ts

@@ -1,4 +1,4 @@
-export { default as AiSdkProvider, effortFromBudget } from "./AiSdkProvider.ts";
+export { default as AiSdkProvider } from "./AiSdkProvider.ts";
 export type { AiSdkProviderConfig, GrammarStyle, ProviderFetch, ReasoningStyle } from "./AiSdkProvider.ts";
 export type {
     ChatMessage,

package/src/providerDefaults.test.ts

@@ -0,0 +1,50 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { lookupProvider, providerIdMap } from "@plurnk/plurnk-models";
+
+const defaultsPath = fileURLToPath(new URL("../.env.defaults", import.meta.url));
+const declarations = readFileSync(defaultsPath, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("#"))
+    .map((line) => /^([A-Z0-9_]+)=(.*)$/.exec(line))
+    .filter((match): match is RegExpExecArray => match !== null)
+    .map((match) => ({ key: match[1]!, value: match[2]! }));
+
+const providerFact = (key: string): { provider: string; fact: string } | null => {
+    const match = /^PLURNK_PROVIDERS_PROVIDER_([A-Z0-9_]+)_(NPM|BASE_URL|API_KEY_ENV)$/.exec(key);
+    return match === null ? null : { provider: match[1]!.toLowerCase(), fact: match[2]! };
+};
+
+test("{§provider-fact-authority} package defaults never redefine cataloged provider facts", () => {
+    const ids = providerIdMap();
+    for (const { key, value } of declarations) {
+        const fact = providerFact(key);
+        if (fact === null) continue;
+        const catalogId = ids[fact.provider] ?? fact.provider;
+        assert.equal(
+            lookupProvider(catalogId),
+            null,
+            `package default '${key}=${value}' redefines a Models.dev-cataloged provider fact (${catalogId})`,
+        );
+    }
+});
+
+test("{§provider-fact-authority} package defaults never ship ordered credential fallbacks", () => {
+    for (const { key, value } of declarations) {
+        if (!key.endsWith("_API_KEY_ENV")) continue;
+        assert.ok(
+            /^[A-Z0-9_]+$/.test(value),
+            `package default '${key}' must hold one exact environment name, got '${value}'`,
+        );
+    }
+});
+
+test("{§openrouter-app-attribution} the shipped floor identifies the public Plurnk application", () => {
+    const values = new Map(declarations.map(({ key, value }) => [key, value]));
+    assert.equal(values.get("OPENROUTER_HTTP_REFERER"), "https://github.com/plurnk/plurnk-service");
+    assert.equal(values.get("OPENROUTER_APP_TITLE"), "Plurnk");
+    assert.equal(values.has("OPENROUTER_X_TITLE"), false);
+});