@plurnk/plurnk-providers 1.7.0 → 1.8.0

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/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);
+});

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,