@plurnk/plurnk-providers 1.6.1 → 1.8.0

package/src/providerError.ts

@@ -0,0 +1,139 @@
+import { Problems, type ProblemDetails } from "@plurnk/plurnk-contracts";
+import { providerSource } from "./notices.ts";
+import type { ProviderAttempt, ProviderRequestAccounting, 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";
+
+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];
+    }
+}
+
+export type { ProviderAttempt, ProviderRequestAccounting, ProviderRequestCapacity } from "./types.ts";

package/src/sdkModels.test.ts

@@ -1,18 +1,106 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { configuredProviderInfo, createSdkModel } from "./sdkModels.ts";
+import { configuredProviderInfo, createSdkModel, providerReadiness } from "./sdkModels.ts";
 
-test("configuredProviderInfo translates one env declaration into provider facts", () => {
+test("{§provider-fact-authority} one env declaration holds one credential name", () => {
     assert.deepEqual(configuredProviderInfo("acme-cloud", {
         PLURNK_PROVIDERS_PROVIDER_ACME_CLOUD_NPM: "@ai-sdk/openai-compatible",
         PLURNK_PROVIDERS_PROVIDER_ACME_CLOUD_BASE_URL: "https://api.acme.test/v1",
-        PLURNK_PROVIDERS_PROVIDER_ACME_CLOUD_API_KEY_ENV: "ACME_API_KEY, ACME_TOKEN",
+        PLURNK_PROVIDERS_PROVIDER_ACME_CLOUD_API_KEY_ENV: "ACME_API_KEY",
     }), {
         id: "acme-cloud",
+        name: "acme-cloud",
         npm: "@ai-sdk/openai-compatible",
-        env: ["ACME_API_KEY", "ACME_TOKEN"],
+        env: ["ACME_API_KEY"],
         api: "https://api.acme.test/v1",
     });
+    assert.throws(
+        () => configuredProviderInfo("acme-cloud", {
+            PLURNK_PROVIDERS_PROVIDER_ACME_CLOUD_NPM: "@ai-sdk/openai-compatible",
+            PLURNK_PROVIDERS_PROVIDER_ACME_CLOUD_API_KEY_ENV: "ACME_API_KEY,ACME_TOKEN",
+        }),
+        /one exact name, never an ordered fallback/,
+    );
+});
+
+test("{§model-catalog-readiness}: readiness uses the construction credential and endpoint requirements without exposing values", () => {
+    assert.deepEqual(providerReadiness("google", {}), {
+        ready: false,
+        causes: [{
+            kind: "credential",
+            alternatives: [["GOOGLE_API_KEY"], ["GOOGLE_GENERATIVE_AI_API_KEY"], ["GEMINI_API_KEY"]],
+        }],
+    });
+    assert.deepEqual(providerReadiness("google", { GEMINI_API_KEY: "secret-value" }), {
+        ready: true,
+        causes: [],
+    });
+    assert.doesNotMatch(JSON.stringify(providerReadiness("google", { GEMINI_API_KEY: "secret-value" })), /secret-value/);
+
+    assert.deepEqual(providerReadiness("cloudflare", { CLOUDFLARE_API_KEY: "key" }), {
+        ready: false,
+        causes: [{
+            kind: "configuration",
+            alternatives: [["CLOUDFLARE_ACCOUNT_ID"]],
+        }],
+    });
+    assert.deepEqual(providerReadiness("cloudflare", {
+        CLOUDFLARE_ACCOUNT_ID: "account",
+        CLOUDFLARE_API_KEY: "key",
+    }), { ready: true, causes: [] });
+});
+
+test("{§model-catalog-readiness}: Bedrock reports its actual alternative authentication sets and region requirement", () => {
+    assert.deepEqual(providerReadiness("bedrock", {}), {
+        ready: false,
+        causes: [{
+            kind: "credential",
+            alternatives: [
+                ["AWS_BEARER_TOKEN_BEDROCK", "AWS_REGION"],
+                ["AWS_BEARER_TOKEN_BEDROCK", "AWS_DEFAULT_REGION"],
+                ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+                ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_DEFAULT_REGION"],
+            ],
+        }],
+    });
+    assert.deepEqual(providerReadiness("bedrock", {
+        AWS_BEARER_TOKEN_BEDROCK: "bearer",
+        AWS_REGION: "us-east-1",
+    }), { ready: true, causes: [] });
+    assert.deepEqual(providerReadiness("bedrock", {
+        AWS_ACCESS_KEY_ID: "access",
+        AWS_SECRET_ACCESS_KEY: "secret",
+    }), {
+        ready: false,
+        causes: [{
+            kind: "configuration",
+            alternatives: [["AWS_REGION"], ["AWS_DEFAULT_REGION"]],
+        }],
+    });
+});
+
+test("{§model-catalog-readiness}: operator-declared unauthenticated compatible endpoints are ready without an invented credential", () => {
+    assert.deepEqual(providerReadiness("acme", {
+        PLURNK_PROVIDERS_PROVIDER_ACME_NPM: "@ai-sdk/openai-compatible",
+        PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL: "http://127.0.0.1:9000/v1",
+    }), { ready: true, causes: [] });
+});
+
+test("{§model-catalog-readiness}: an authenticated operator declaration reports its missing credential-name configuration", () => {
+    const env = {
+        PLURNK_PROVIDERS_PROVIDER_ACME_NPM: "@ai-sdk/openai",
+    };
+    assert.deepEqual(providerReadiness("acme", env), {
+        ready: false,
+        causes: [{
+            kind: "configuration",
+            alternatives: [["PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV"]],
+        }],
+    });
+    assert.throws(
+        () => createSdkModel("acme", "model", env),
+        /PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV must be set/,
+    );
 });
 
 test("createSdkModel uses Models.dev provider facts and operator credentials", () => {
@@ -35,6 +123,23 @@ test("createSdkModel constructs Cerebras from Models.dev facts", () => {
     assert.equal(sdk?.compatible, undefined);
 });
 
+test("{§openrouter-app-attribution} attribution rejects malformed URLs and the retired title name", () => {
+    assert.throws(
+        () => createSdkModel("openrouter", "openai/gpt-5", {
+            OPENROUTER_API_KEY: "key",
+            OPENROUTER_HTTP_REFERER: "plurnk",
+        }),
+        /OPENROUTER_HTTP_REFERER must be an absolute HTTP\(S\) URL/,
+    );
+    assert.throws(
+        () => createSdkModel("openrouter", "openai/gpt-5", {
+            OPENROUTER_API_KEY: "key",
+            OPENROUTER_X_TITLE: "Plurnk",
+        }),
+        /OPENROUTER_X_TITLE was renamed to OPENROUTER_APP_TITLE/,
+    );
+});
+
 test("the Google SDK adapter owns its readable-reasoning response projection", () => {
     assert.deepEqual(
         createSdkModel("google", "gemini-3.7-flash", { GEMINI_API_KEY: "test-key" })?.reasoningResponseProviderOptions,
@@ -61,20 +166,49 @@ test("createSdkModel attaches DeepInfra's documented response-cost normalizer",
     });
 });
 
-test("createSdkModel expands catalog endpoint variables without treating them as credentials", () => {
+test("{§provider-fact-authority} catalog credential names are law without any package or operator alias", () => {
     const sdk = createSdkModel("cloudflare", "@cf/google/gemma-4-26b-a4b-it", {
         CLOUDFLARE_ACCOUNT_ID: "account",
-        CLOUDFLARE_API_TOKEN: "token",
-        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_API_KEY_ENV: "CLOUDFLARE_API_TOKEN,CLOUDFLARE_API_KEY",
+        CLOUDFLARE_API_KEY: "key",
     });
     assert.equal(sdk?.languageModel, undefined);
     assert.deepEqual(sdk?.compatible, {
         url: "https://api.cloudflare.com/client/v4/accounts/account/ai/v1/chat/completions",
-        headers: { Authorization: "Bearer token" },
+        headers: { Authorization: "Bearer key" },
     });
     assert.deepEqual(sdk?.cacheAffinity, { target: "header", name: "x-session-affinity" });
 });
 
+test("{§provider-fact-authority} an operator credential override holds one exact name", () => {
+    const sdk = createSdkModel("cloudflare", "@cf/google/gemma-4-26b-a4b-it", {
+        CLOUDFLARE_ACCOUNT_ID: "account",
+        MY_ORG_CLOUDFLARE_KEY: "key",
+        PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_API_KEY_ENV: "MY_ORG_CLOUDFLARE_KEY",
+    });
+    assert.deepEqual(sdk?.compatible, {
+        url: "https://api.cloudflare.com/client/v4/accounts/account/ai/v1/chat/completions",
+        headers: { Authorization: "Bearer key" },
+    });
+});
+
+test("{§provider-fact-authority} ordered credential fallbacks are rejected at construction", () => {
+    assert.throws(
+        () => createSdkModel("cloudflare", "@cf/google/gemma-4-26b-a4b-it", {
+            CLOUDFLARE_ACCOUNT_ID: "account",
+            CLOUDFLARE_API_TOKEN: "token",
+            PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_API_KEY_ENV: "CLOUDFLARE_API_TOKEN,CLOUDFLARE_API_KEY",
+        }),
+        /one exact name, never an ordered fallback/,
+    );
+    assert.throws(
+        () => createSdkModel("acme", "model", {
+            PLURNK_PROVIDERS_PROVIDER_ACME_NPM: "@ai-sdk/openai-compatible",
+            PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV: "ACME_API_KEY,ACME_TOKEN",
+        }),
+        /one exact name, never an ordered fallback/,
+    );
+});
+
 test("catalog routes own their documented cache-affinity request projection", () => {
     assert.deepEqual(
         createSdkModel("openai", "gpt-4.1-mini", { OPENAI_API_KEY: "key" })?.cacheAffinity,

package/src/sdkModels.ts

@@ -9,7 +9,13 @@ import { createOpenAI } from "@ai-sdk/openai";
 import { createTogetherAI } from "@ai-sdk/togetherai";
 import { createXai } from "@ai-sdk/xai";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
-import { lookupProvider, type ProviderInfo } from "@plurnk/plurnk-models";
+import {
+    isProviderCredentialName,
+    lookupProvider,
+    providerCatalogSnapshot,
+    type ProviderInfo,
+} from "@plurnk/plurnk-models";
+import { Validator, type ModelReadiness, type ModelReadinessCause } from "@plurnk/plurnk-contracts";
 import type { LanguageModel } from "ai";
 import { providerCostNormalizer } from "./accounting.ts";
 import type { AiSdkProviderOptions, CacheAffinity } from "./AiSdkProvider.ts";
@@ -30,10 +36,57 @@ export type SdkModel = {
 };
 
 const cacheControl = { type: "ephemeral" as const };
+// The release generator admits only packages implemented by this package.
+// Derive runtime readiness from that same pinned provider projection instead
+// of maintaining a second support list beside the construction switch.
+const supportedSdkPackages = new Set(
+    Object.values(providerCatalogSnapshot()).map(({ npm }) => npm),
+);
+
+const openRouterHeaders = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+): Readonly<Record<string, string>> => {
+    if (catalog.id !== "openrouter") return {};
+    if (env.OPENROUTER_X_TITLE !== undefined) {
+        throw new Error(`${provider} provider: OPENROUTER_X_TITLE was renamed to OPENROUTER_APP_TITLE.`);
+    }
+    const referer = env.OPENROUTER_HTTP_REFERER?.trim();
+    if (referer === undefined || referer === "") return {};
+    let parsed: URL;
+    try {
+        parsed = new URL(referer);
+    } catch (cause) {
+        throw new Error(`${provider} provider: OPENROUTER_HTTP_REFERER must be an absolute HTTP(S) URL.`, { cause });
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`${provider} provider: OPENROUTER_HTTP_REFERER must be an absolute HTTP(S) URL.`);
+    }
+    const title = env.OPENROUTER_APP_TITLE?.trim();
+    return {
+        "HTTP-Referer": parsed.href,
+        ...(title === undefined || title === "" ? {} : { "X-OpenRouter-Title": title }),
+    };
+};
 
 const envPrefix = (provider: string): string =>
     provider.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase();
 
+// {§provider-fact-authority} — one credential declaration holds exactly one
+// name. An ordered fallback list would paper over an operator/catalog naming
+// mismatch; that mismatch belongs at its owning boundary instead.
+const singleCredentialName = (provider: string, value: string): string => {
+    const name = value.trim();
+    if (name.length === 0) throw new Error(`${provider} provider: API_KEY_ENV must name one environment variable.`);
+    if (name.includes(",")) {
+        throw new Error(
+            `${provider} provider: API_KEY_ENV holds one exact name, never an ordered fallback; reconcile the operator environment with the Models.dev contract instead.`,
+        );
+    }
+    return name;
+};
+
 export const configuredProviderInfo = (
     provider: string,
     env: NodeJS.ProcessEnv,
@@ -41,13 +94,14 @@ export const configuredProviderInfo = (
     const prefix = `PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}`;
     const npm = env[`${prefix}_NPM`];
     if (npm === undefined || npm.length === 0) return null;
-    const keyNames = env[`${prefix}_API_KEY_ENV`]
-        ?.split(",")
-        .map((name) => name.trim())
-        .filter(Boolean) ?? [];
+    const declared = env[`${prefix}_API_KEY_ENV`];
+    const keyNames = declared === undefined
+        ? []
+        : [singleCredentialName(provider, declared)];
     const api = env[`${prefix}_BASE_URL`];
     return {
         id: provider,
+        name: provider,
         npm,
         env: keyNames,
         ...(api === undefined || api.length === 0 ? {} : { api }),
@@ -62,6 +116,11 @@ const firstSet = (env: NodeJS.ProcessEnv, names: readonly string[]): string | un
     return undefined;
 };
 
+const isSet = (env: NodeJS.ProcessEnv, name: string): boolean => {
+    const value = env[name];
+    return value !== undefined && value.length > 0;
+};
+
 const configuredKeyNames = (
     provider: string,
     env: NodeJS.ProcessEnv,
@@ -70,7 +129,125 @@ const configuredKeyNames = (
     const configured = env[`PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}_API_KEY_ENV`];
     return configured === undefined || configured.length === 0
         ? catalog.env
-        : configured.split(",").map((name) => name.trim()).filter(Boolean);
+        : [singleCredentialName(provider, configured)];
+};
+
+const credentialCandidates = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+): readonly string[] => {
+    const names = configuredKeyNames(provider, env, catalog);
+    const credentials = names.filter(isProviderCredentialName);
+    return credentials.length > 0 ? credentials : names;
+};
+
+const configuredBaseUrl = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    catalog: ProviderInfo,
+    override?: string,
+): string | undefined => {
+    const prefix = envPrefix(provider);
+    return override
+        ?? env[`PLURNK_PROVIDERS_PROVIDER_${prefix}_BASE_URL`]
+        ?? env[`${prefix}_BASE_URL`]
+        ?? catalog.api;
+};
+
+const templateEnvironmentNames = (value: string | undefined): readonly string[] => value === undefined
+    ? []
+    : [...new Set([...value.matchAll(/\$\{([A-Z0-9_]+)\}/g)].map((match) => match[1]!))];
+
+const missingCause = (
+    kind: ModelReadinessCause["kind"],
+    alternatives: readonly (readonly string[])[],
+): ModelReadinessCause => ({
+    kind,
+    alternatives: alternatives.map((alternative) => [...alternative]) as ModelReadinessCause["alternatives"],
+});
+
+const bedrockReadinessCauses = (
+    env: NodeJS.ProcessEnv,
+    hasExplicitBaseUrl: boolean,
+): ModelReadinessCause[] => {
+    const bearer = isSet(env, "AWS_BEARER_TOKEN_BEDROCK");
+    const sigv4 = isSet(env, "AWS_ACCESS_KEY_ID") && isSet(env, "AWS_SECRET_ACCESS_KEY");
+    const region = isSet(env, "AWS_REGION") || isSet(env, "AWS_DEFAULT_REGION");
+    if (bearer) {
+        return hasExplicitBaseUrl || region
+            ? []
+            : [missingCause("configuration", [["AWS_REGION"], ["AWS_DEFAULT_REGION"]])];
+    }
+    if (sigv4) {
+        return region
+            ? []
+            : [missingCause("configuration", [["AWS_REGION"], ["AWS_DEFAULT_REGION"]])];
+    }
+    return [missingCause("credential", hasExplicitBaseUrl
+        ? [
+            ["AWS_BEARER_TOKEN_BEDROCK"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_DEFAULT_REGION"],
+        ]
+        : [
+            ["AWS_BEARER_TOKEN_BEDROCK", "AWS_REGION"],
+            ["AWS_BEARER_TOKEN_BEDROCK", "AWS_DEFAULT_REGION"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+            ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_DEFAULT_REGION"],
+        ])];
+};
+
+// Local evidence only: this shares the exact environment and endpoint rules
+// used by createSdkModel, but never probes a provider or validates a secret.
+export const providerReadiness = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    baseUrlOverride?: string,
+): ModelReadiness | null => {
+    const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
+    if (catalog === null) return null;
+    if (!supportedSdkPackages.has(catalog.npm)) return null;
+    const rawUrl = configuredBaseUrl(provider, env, catalog, baseUrlOverride);
+    const missingCoordinates = templateEnvironmentNames(rawUrl).filter((name) => !isSet(env, name));
+    const causes: ModelReadinessCause[] = missingCoordinates.length === 0
+        ? []
+        : [missingCause("configuration", [missingCoordinates])];
+
+    if (catalog.npm === "@ai-sdk/amazon-bedrock") {
+        causes.push(...bedrockReadinessCauses(env, rawUrl !== undefined));
+    } else {
+        const candidates = credentialCandidates(provider, env, catalog);
+        const credentialRequired = catalog.npm !== "@ai-sdk/openai-compatible" || candidates.length > 0;
+        if (credentialRequired && candidates.length === 0) {
+            causes.push(missingCause("configuration", [[
+                `PLURNK_PROVIDERS_PROVIDER_${envPrefix(provider)}_API_KEY_ENV`,
+            ]]));
+        } else if (credentialRequired && firstSet(env, candidates) === undefined) {
+            causes.push(missingCause("credential", candidates.map((name) => [name])));
+        }
+        if (catalog.npm === "@ai-sdk/openai-compatible" && rawUrl === undefined) {
+            const prefix = envPrefix(provider);
+            causes.push(missingCause("configuration", [
+                [`PLURNK_PROVIDERS_PROVIDER_${prefix}_BASE_URL`],
+                [`${prefix}_BASE_URL`],
+            ]));
+        }
+    }
+    return Validator.assertModelReadiness({ ready: causes.length === 0, causes });
+};
+
+const assertProviderReady = (
+    provider: string,
+    env: NodeJS.ProcessEnv,
+    baseUrlOverride?: string,
+): void => {
+    const readiness = providerReadiness(provider, env, baseUrlOverride);
+    if (readiness === null || readiness.ready) return;
+    const requirements = readiness.causes
+        .map(({ alternatives }) => alternatives.map((group) => group.join(" and ")).join(" or "))
+        .join("; ");
+    throw new Error(`${provider} provider: ${requirements} must be set`);
 };
 
 const expandEnv = (value: string, env: NodeJS.ProcessEnv, provider: string): string =>
@@ -88,11 +265,11 @@ const baseUrl = (
     catalog: ProviderInfo,
     override?: string,
 ): string | undefined => {
-    const prefix = envPrefix(provider);
-    const configured = env[`PLURNK_PROVIDERS_PROVIDER_${prefix}_BASE_URL`]
-        ?? env[`${prefix}_BASE_URL`]
-        ?? catalog.api;
-    const value = override ?? configured;
+    // {§provider-fact-authority} — distinct sources, one precedence: the PLURNK
+    // knob, then the provider-native convention (OPENAI_BASE_URL etc.), then
+    // the catalog. This is not an alias fallback: each source is a different
+    // owner, and the catalog remains the last authority.
+    const value = configuredBaseUrl(provider, env, catalog, override);
     return value === undefined ? undefined : expandEnv(value, env, provider).replace(/\/+$/, "");
 };
 
@@ -101,9 +278,11 @@ const requireApiKey = (
     env: NodeJS.ProcessEnv,
     catalog: ProviderInfo,
 ): string => {
-    const names = configuredKeyNames(provider, env, catalog);
-    const key = firstSet(env, names);
-    if (key === undefined) throw new Error(`${provider} provider: ${names.join(" or ")} must be set`);
+    // {§provider-fact-authority} — a catalog `env` list mixes credentials with
+    // non-secret coordinates; the credential is the credential-named one.
+    const candidates = credentialCandidates(provider, env, catalog);
+    const key = firstSet(env, candidates);
+    if (key === undefined) throw new Error(`${provider} provider: ${candidates.join(" or ")} must be set`);
     return key;
 };
 
@@ -115,6 +294,10 @@ export const createSdkModel = (
 ): SdkModel | null => {
     const catalog = lookupProvider(provider) ?? configuredProviderInfo(provider, env);
     if (catalog === null) return null;
+    if (!supportedSdkPackages.has(catalog.npm)) {
+        throw new Error(`${provider} provider: Models.dev declares unsupported AI SDK package ${catalog.npm}`);
+    }
+    assertProviderReady(provider, env, baseUrlOverride);
     const url = baseUrl(provider, env, catalog, baseUrlOverride);
     const normalizeCost = providerCostNormalizer(catalog.npm);
 
@@ -192,7 +375,9 @@ export const createSdkModel = (
                     apiKey: env.AWS_BEARER_TOKEN_BEDROCK,
                     baseURL: url,
                 }).languageModel(model),
-                additiveReasoningProvider: "bedrock",
+                ...(model.includes("anthropic")
+                    ? { additiveReasoningProvider: "bedrock" as const }
+                    : {}),
                 catalog,
             };
         case "@openrouter/ai-sdk-provider":
@@ -200,10 +385,7 @@ export const createSdkModel = (
                 languageModel: createOpenRouter({
                     apiKey: requireApiKey(provider, env, catalog),
                     baseURL: url,
-                    headers: {
-                        ...(env.OPENROUTER_HTTP_REFERER === undefined ? {} : { "HTTP-Referer": env.OPENROUTER_HTTP_REFERER }),
-                        ...(env.OPENROUTER_X_TITLE === undefined ? {} : { "X-Title": env.OPENROUTER_X_TITLE }),
-                    },
+                    headers: openRouterHeaders(provider, env, catalog),
                 }).languageModel(model),
                 ...(catalog.id === "openrouter"
                     ? { cacheAffinity: { target: "header" as const, name: "x-session-id" } }

package/src/types.ts

@@ -12,6 +12,7 @@ import type {
 import type {
     ProviderCost,
     ProviderRequestAccounting,
+    ReasoningPolicy,
 } from "@plurnk/plurnk-contracts";
 
 export type {
@@ -19,8 +20,21 @@ export type {
     ProviderCost,
     ProviderRequestAccounting,
     ProviderUsage,
+    ReasoningPolicy,
 } from "@plurnk/plurnk-contracts";
 
+export class UnsupportedReasoningPolicyError extends Error {
+    readonly policy: ReasoningPolicy;
+    readonly supported: readonly ReasoningPolicy[];
+
+    constructor(source: string, policy: ReasoningPolicy, supported: readonly ReasoningPolicy[]) {
+        super(`${source}: reasoning policy '${policy}' is unsupported; supported policies: ${supported.join(", ")}`);
+        this.name = "UnsupportedReasoningPolicyError";
+        this.policy = policy;
+        this.supported = supported;
+    }
+}
+
 export interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
@@ -277,6 +291,8 @@ export interface Provider {
     readonly maxOutputTokens: number | null;
     readonly outputBudget: number | null;
     readonly reasoningBudget: number | null;
+    // Exact durable policies this adapter can represent without coercion.
+    readonly supportedReasoningPolicies: readonly ReasoningPolicy[];
     readonly inputCapacity: number | null;
     readonly model: string;
     // Optional: the backend's self-reported served model id, from a