@plurnk/plurnk-providers 1.3.12 → 1.5.0

package/src/discover.test.ts

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { discover } from "./discover.ts";
 
-// #551: create a temp dir AND register its removal on the test context, so it's
+// Create a temp dir and register its removal on the test context, so it is
 // cleaned on a GREEN or RED run. A trailing rm after the assertions leaks the dir
 // whenever one throws — thousands accumulate on a shared box at drill frequency.
 const tempDir = async (t: TestContext, prefix: string): Promise<string> => {
@@ -47,6 +47,17 @@ test("discover: a provider package missing plurnk.name is ignored, not crashed",
     assert.deepEqual([...registry.keys()], ["named"]);
 });
 
+test("discover: an array kind claims no provider family", async (t) => {
+    const root = await buildModules(t, {
+        "@acme/dual": {
+            name: "@acme/dual",
+            plurnk: { kind: ["provider", "scheme"], name: "dual" },
+        },
+    });
+    const { registry } = await discover({ cwd: root });
+    assert.equal(registry.size, 0);
+});
+
 test("discover: a name claimed by two packages is a fail-hard collision", async (t) => {
     const root = await buildModules(t, {
         "@plurnk/plurnk-provider-native": { name: "@plurnk/plurnk-provider-native", plurnk: { kind: "provider", name: "native" } },
@@ -71,18 +82,48 @@ test("discover: node_modules entries with no package.json or malformed JSON are
     assert.deepEqual([...registry.keys()], ["native"]); // only the well-formed provider survives
 });
 
-test("discover: surfaces plurnk.attribution (string or string[]) for registered providers (#21)", async (t) => {
+test("discover: normalizes attribution per package and preserves the published provider projection", async (t) => {
     const root = await buildModules(t, {
         "@acme/provider-solo": { name: "@acme/provider-solo", plurnk: { kind: "provider", name: "solo", attribution: "@acme/solo" } },
         "@acme/provider-multi": { name: "@acme/provider-multi", plurnk: { kind: "provider", name: "multi", attribution: ["@acme/a", "@acme/b"] } },
         "@acme/provider-none": { name: "@acme/provider-none", plurnk: { kind: "provider", name: "none" } },
-        "@acme/provider-bad": { name: "@acme/provider-bad", plurnk: { kind: "provider", name: "bad", attribution: 42 } }, // non-string/array
     });
-    const { attributions } = await discover({ cwd: root });
+    const { attributions, packageAttributions } = await discover({ cwd: root });
     assert.equal(attributions.get("solo"), "@acme/solo");
     assert.deepEqual(attributions.get("multi"), ["@acme/a", "@acme/b"]);
-    assert.equal(attributions.has("none"), false); // declared none → absent
-    assert.equal(attributions.has("bad"), false);  // non-string/array ignored, not surfaced
+    assert.equal(attributions.has("none"), false);
+    assert.deepEqual([...packageAttributions], [
+        ["@acme/provider-multi", ["@acme/a", "@acme/b"]],
+        ["@acme/provider-solo", ["@acme/solo"]],
+    ]);
+});
+
+test("discover: validates trusted attribution before provider admission", async (t) => {
+    const root = await buildModules(t, {
+        "@acme/provider-bad": { name: "@acme/provider-bad", plurnk: { kind: "provider", name: "bad", attribution: 42 } },
+    });
+    await assert.rejects(
+        discover({ cwd: root }),
+        /plugin '@acme\/provider-bad': plurnk\.attribution must be a non-empty string or string\[\]/,
+    );
+
+    const reservedRoot = await buildModules(t, {
+        "@acme/provider-reserved": { name: "@acme/provider-reserved", plurnk: { kind: "provider", name: "reserved", attribution: "@plurnk/staff" } },
+    });
+    await assert.rejects(discover({ cwd: reservedRoot }), /'@plurnk\/' is reserved/);
+});
+
+test("discover: an untrusted malformed attribution is withheld before validation", async (t) => {
+    const root = await buildModules(t, {
+        "@acme/provider-bad": { name: "@acme/provider-bad", plurnk: { kind: "provider", name: "bad", attribution: ["ok", 42] } },
+    });
+    const result = await discover({
+        cwd: root,
+        env: { PLURNK_PLUGINS_TRUSTED_ONLY: "1" } as NodeJS.ProcessEnv,
+    });
+    assert.equal(result.registry.size, 0);
+    assert.equal(result.skipped.get("bad"), "@acme/provider-bad");
+    assert.equal(result.packageAttributions.size, 0);
 });
 
 test("discover: missing node_modules yields an empty registry, not an error", async (t) => {
@@ -91,7 +132,7 @@ test("discover: missing node_modules yields an empty registry, not an error", as
     assert.equal(registry.size, 0);
 });
 
-// — trust gate (PLURNK_PLUGINS_TRUSTED_ONLY, #15) —
+// — trust gate ({§plugin-trust-boundary}) —
 
 const trustFixture = (t: TestContext) => buildModules(t, {
     "@plurnk/plurnk-provider-native": { name: "@plurnk/plurnk-provider-native", plurnk: { kind: "provider", name: "native" } },

package/src/discover.ts

@@ -1,8 +1,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import Meta from "@plurnk/plurnk-meta";
+import type {
+    PackageAttributions,
+    PluginAttribution,
+    PluginAttributionDeclaration,
+} from "@plurnk/plurnk-meta";
 
-// Scope-agnostic discovery of installed AI SDK provider packages (SPEC §5).
+// Scope-agnostic discovery of installed AI SDK provider packages
+// ({§plugin-family-kind}).
 // Parallel to @plurnk/plurnk-execs' discover(): scan every installed package
 // under `<cwd>/node_modules` — scoped (`@scope/name`) and unscoped — and keep
 // the ones declaring `plurnk.kind === "provider"`. Scope-agnostic so a THIRD
@@ -16,7 +22,7 @@ import Meta from "@plurnk/plurnk-meta";
 //
 // Cataloged and operator-declared providers resolve before this scan.
 //
-// Host plugin trust gate (PLURNK_PLUGINS_TRUSTED_ONLY, #15 / plurnk-service#229)
+// {§plugin-trust-boundary} Host plugin trust gate (PLURNK_PLUGINS_TRUSTED_ONLY)
 // — enforced uniformly across the four scope-agnostic families. An untrusted
 // package is discovered-but-declined (recorded in `skipped`, never registered,
 // never thrown), so the consumer can name it in a precise error.
@@ -31,12 +37,9 @@ export type DiscoverOptions = {
 export type Discovery = {
     registry: Map<string, string>; // trusted providers, eligible to instantiate
     skipped: Map<string, string>;  // declined by the trust gate (untrusted)
-    // name → raw `plurnk.attribution` (string | string[]) declared by a registered
-    // provider package's manifest, for crediting the provider's author (#21,
-    // plurnk-service#249). Surfaced verbatim — the consumer applies the reservation
-    // policy (`@plurnk/` tags only from `@plurnk/`-scoped packages). Absent for
-    // providers that declare none.
+    // Published name-keyed projection retained for 1.x consumers.
     attributions: Map<string, string | string[]>;
+    packageAttributions: PackageAttributions;
 };
 
 
@@ -46,7 +49,8 @@ export const discover = async (options: DiscoverOptions = {}): Promise<Discovery
 
     const registry = new Map<string, string>();
     const skipped = new Map<string, string>();
-    const attributions = new Map<string, string | string[]>();
+    const attributions = new Map<string, PluginAttributionDeclaration>();
+    const packageAttributions = new Map<string, PluginAttribution>();
     for (const dir of dirs) {
         const info = await readProviderInfo(dir);
         if (info === null) continue;
@@ -61,10 +65,13 @@ export const discover = async (options: DiscoverOptions = {}): Promise<Discovery
                 + `${existing} and ${info.packageName}`,
             );
         }
+        const tags = Meta.normalizeAttribution(info.attribution, info.packageName);
         registry.set(info.name, info.packageName);
-        if (info.attribution !== undefined) attributions.set(info.name, info.attribution);
+        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 };
+    return { registry, skipped, attributions, packageAttributions };
 };
 
 // Enumerate every installed package directory — scoped and unscoped — under
@@ -74,11 +81,10 @@ const defaultPackageDirs = async (cwd: string): Promise<string[]> => {
     return (await Meta.packageDirs(nm)).map((c) => c.dir).toSorted();
 };
 
-// One { name, packageName, attribution? } for a provider package, or null for
-// anything that isn't one (missing/invalid package.json, no plurnk block, wrong
-// kind, no name). `attribution` mirrors `plurnk.attribution` when it's a string
-// or string[] (anything else is ignored).
-type ProviderInfo = { name: string; packageName: string; attribution?: string | 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 };
 
 const readProviderInfo = async (dir: string): Promise<ProviderInfo | null> => {
     let raw: string;
@@ -98,12 +104,16 @@ const readProviderInfo = async (dir: string): Promise<ProviderInfo | null> => {
     const plurnk = record.plurnk;
     if (typeof plurnk !== "object" || plurnk === null) return null;
     const plurnkRec = plurnk as Record<string, unknown>;
-    if (plurnkRec.kind !== "provider") return 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;
-    const attr = plurnkRec.attribution;
-    const attribution = typeof attr === "string" ? attr
-        : Array.isArray(attr) && attr.every((x) => typeof x === "string") ? (attr as string[])
-        : undefined;
-    return { name: plurnkRec.name, packageName: record.name, attribution };
+    return { name: plurnkRec.name, packageName: record.name, attribution: plurnkRec.attribution };
+};
+
+const attributionProjection = (
+    raw: unknown,
+    tags: PluginAttribution,
+): PluginAttributionDeclaration | undefined => {
+    if (raw === undefined || raw === null) return undefined;
+    return typeof raw === "string" ? raw : [...tags];
 };

package/src/env.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import { strict as assert } from "node:assert";
-import { parseRequiredInt, parseOptionalInt, requireEnv, reasoningFromEnv, tokenRatesFromEnv } from "./env.ts";
+import { parseRequiredInt, parseOptionalInt, requireEnv, reasoningFromEnv, reasoningResponseStyleFromEnv } from "./env.ts";
 
 test("parseRequiredInt: parses a non-negative integer", () => {
     assert.equal(parseRequiredInt("600000", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), 600000);
@@ -29,7 +29,7 @@ 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 modes parse; budget required IFF on; fail-hard on everything else (#33)", () => {
+test("reasoningFromEnv: activation modes parse; budget required IFF on; fail-hard on everything else", () => {
     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", PLURNK_PROVIDERS_REASONING_BUDGET: "4096" }, "openai"), { mode: "on", budget: 4096 });
@@ -40,37 +40,25 @@ test("reasoningFromEnv: activation modes parse; budget required IFF on; fail-har
     assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "1.5" }, "openai"), /positive integer/);
 });
 
+test("{§provider-tagged-reasoning} response style is explicit and invalid values fail at the provider boundary", () => {
+    assert.equal(reasoningResponseStyleFromEnv({}, "cloudflare"), "verbatim");
+    assert.equal(reasoningResponseStyleFromEnv({
+        PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "think-tags",
+    }, "cloudflare"), "think-tags");
+    assert.throws(
+        () => reasoningResponseStyleFromEnv({
+            PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE: "auto",
+        }, "cloudflare"),
+        /cloudflare provider: PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE must be "verbatim" or "think-tags" \(got "auto"\)/,
+    );
+});
+
 test("requireEnv: returns the value or throws a named error", () => {
     assert.equal(requireEnv("sk-x", "OPENAI_API_KEY", "openai"), "sk-x");
     assert.throws(() => requireEnv(undefined, "GROQ_API_KEY", "groq"), /groq provider: GROQ_API_KEY must be set/);
     assert.throws(() => requireEnv("", "GROQ_API_KEY", "groq"), /must be set/);
 });
 
-test("tokenRatesFromEnv is all-or-nothing, with cached input defaulting to input", () => {
-    assert.equal(tokenRatesFromEnv({}, "cloudflare"), null);
-    assert.deepEqual(tokenRatesFromEnv({
-        PLURNK_PROVIDERS_INPUT_USD_PER_MILLION: "0.435",
-        PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION: "0.87",
-    }, "cloudflare"), {
-        input: 0.435,
-        cached: 0.435,
-        output: 0.87,
-    });
-    assert.deepEqual(tokenRatesFromEnv({
-        PLURNK_PROVIDERS_INPUT_USD_PER_MILLION: "3",
-        PLURNK_PROVIDERS_CACHE_READ_USD_PER_MILLION: "0.3",
-        PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION: "15",
-    }, "cloudflare"), {
-        input: 3,
-        cached: 0.3,
-        output: 15,
-    });
-    assert.throws(
-        () => tokenRatesFromEnv({ PLURNK_PROVIDERS_INPUT_USD_PER_MILLION: "1" }, "cloudflare"),
-        /PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION must be set/,
-    );
-});
-
 // — per-alias knob scoping (per-alias scoping doctrine, user 2026-07-03) —
 
 test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases ignored", async () => {
@@ -79,15 +67,17 @@ test("scopeEnvToAlias: suffixed knob wins, bare is the fallback, other aliases i
         PLURNK_PROVIDERS_REASONING: "off",
         PLURNK_PROVIDERS_REASONING_turboderp: "on",
         PLURNK_PROVIDERS_REASONING_BUDGET_TURBODERP: "4096", // case-folds like PLURNK_MODEL_ keys
-        PLURNK_PROVIDERS_CONTEXT_WINDOW_turboderp: "8000", // #525 gate knob — the client window cap
+        PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_TURBODERP: "think-tags",
+        PLURNK_PROVIDERS_CONTEXT_WINDOW_turboderp: "8000",
         PLURNK_PROVIDERS_COMPLETION_RESERVE_turboderp: "4096",
         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_BUDGET, "4096");
-    assert.equal(scoped.PLURNK_PROVIDERS_CONTEXT_WINDOW, "8000"); // #525: the alias-scoped window cap promotes to bare (the release-gate knob)
-    assert.equal(scoped.PLURNK_PROVIDERS_COMPLETION_RESERVE, "4096"); // the #507 reserves promote too
+    assert.equal(scoped.PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE, "think-tags");
+    assert.equal(scoped.PLURNK_PROVIDERS_CONTEXT_WINDOW, "8000");
+    assert.equal(scoped.PLURNK_PROVIDERS_COMPLETION_RESERVE, "4096");
     assert.equal(scopeEnvToAlias(env, "plain").PLURNK_PROVIDERS_REASONING, "off"); // fallback intact
 });
 
@@ -103,7 +93,7 @@ test("scopeEnvToAlias: aliases with underscores resolve; a bare knob is never mi
     assert.equal(scopeEnvToAlias(env, "budget").PLURNK_PROVIDERS_REASONING, "off"); // collision guard
 });
 
-test("#36 dataCaptureFromEnv: both knobs OFF by default, ON when set (TOP_LOGPROBS = the OpenAI top_logprobs count)", async () => {
+test("dataCaptureFromEnv: both knobs OFF by default, ON when set (TOP_LOGPROBS = the OpenAI top_logprobs count)", async () => {
     const { dataCaptureFromEnv } = await import("./env.ts");
     assert.deepEqual(dataCaptureFromEnv({} as NodeJS.ProcessEnv, "x"), { topLogprobs: null, rawBody: false });
     assert.deepEqual(dataCaptureFromEnv({ PLURNK_PROVIDERS_RAWBODY: "0" } as NodeJS.ProcessEnv, "x"), { topLogprobs: null, rawBody: false });
@@ -120,7 +110,7 @@ test("OpenAI-lexicon shed: a still-set PLURNK_PROVIDERS_LOGPROB fails hard with
     );
 });
 
-test("#472 contextWindowFromEnv: reads the new name, sheds CONTEXT_SIZE hard, null when unset", async () => {
+test("contextWindowFromEnv: reads the new name, sheds CONTEXT_SIZE hard, null when unset", async () => {
     const { contextWindowFromEnv } = await import("./env.ts");
     assert.equal(contextWindowFromEnv({ PLURNK_PROVIDERS_CONTEXT_WINDOW: "131072" } as NodeJS.ProcessEnv, "openai"), 131072);
     assert.equal(contextWindowFromEnv({} as NodeJS.ProcessEnv, "openai"), null);
@@ -130,7 +120,7 @@ test("#472 contextWindowFromEnv: reads the new name, sheds CONTEXT_SIZE hard, nu
     );
 });
 
-test("scopeEnvToAlias: a caller-supplied knob list scopes CONSUMER vars (service window partition)", async () => {
+test("scopeEnvToAlias: a caller-supplied knob list scopes consumer-owned vars", async () => {
     const { scopeEnvToAlias } = await import("./env.ts");
     const SERVICE_KNOBS = ["PLURNK_SERVICE_MAX_TURNS", "PLURNK_SERVICE_LOOP_TIMEOUT", "PLURNK_SERVICE_EXEC_HOLD_MS", "PLURNK_SERVICE_SAFETY"];
     const env = {
@@ -150,7 +140,7 @@ test("scopeEnvToAlias: a caller-supplied knob list scopes CONSUMER vars (service
     assert.equal(mixed.PLURNK_PROVIDERS_REASONING, "off");
 });
 
-test("#36 capture knobs are per-alias scopable: enable on a scraping alias, serving alias stays clean", async () => {
+test("capture knobs are per-alias scopable: enable on a scraping alias, serving alias stays clean", async () => {
     const { scopeEnvToAlias, dataCaptureFromEnv } = await import("./env.ts");
     const env = {
         PLURNK_PROVIDERS_TOP_LOGPROBS_fireslow: "3",
@@ -160,10 +150,10 @@ test("#36 capture knobs are per-alias scopable: enable on a scraping alias, serv
     assert.deepEqual(dataCaptureFromEnv(scopeEnvToAlias(env, "grokfast"), "x"), { topLogprobs: null, rawBody: false });
 });
 
-// Reader-declares (#44 ecosystem standard): every knob the code reads appears in
+// Every knob the code reads appears in
 // the shipped .env.defaults — set (the floor) or commented (documented optional).
 // The file IS the operator documentation; this keeps it from drifting off the code.
-test("#44: every PROVIDERS_KNOBS entry appears in the shipped .env.defaults", async () => {
+test("every PROVIDERS_KNOBS entry appears in the shipped .env.defaults", async () => {
     const { readFileSync } = await import("node:fs");
     const { PROVIDERS_KNOBS } = await import("./env.ts");
     const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
@@ -172,37 +162,37 @@ test("#44: every PROVIDERS_KNOBS entry appears in the shipped .env.defaults", as
     assert.ok(defaults.includes("PLURNK_PROVIDERS_GBNF="), "GBNF (service-read, providers-namespace) must be declared with its default");
 });
 
-// #399: the family word is REASONING (industry standard). Old names fail hard
+// The family word is REASONING (industry standard). Old names fail hard
 // with the migration pointer — never silently coexist with the new floor.
-test("#399: still-set old THINKING names fail hard with the rename pointer", () => {
+test("still-set old THINKING names fail hard with the rename pointer", () => {
     assert.throws(
         () => reasoningFromEnv({ PLURNK_PROVIDERS_THINKING: "on", PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai"),
-        /PLURNK_PROVIDERS_THINKING was renamed to PLURNK_PROVIDERS_REASONING \(#399\)/,
+        /PLURNK_PROVIDERS_THINKING was renamed to PLURNK_PROVIDERS_REASONING \(provider configuration contract\)/,
     );
     assert.throws(
         () => reasoningFromEnv({ PLURNK_PROVIDERS_THINKING_CAPACITY: "4096", PLURNK_PROVIDERS_REASONING: "adaptive" }, "openai"),
-        /PLURNK_PROVIDERS_THINKING_CAPACITY was renamed to PLURNK_PROVIDERS_REASONING_BUDGET \(#399\)/,
+        /PLURNK_PROVIDERS_THINKING_CAPACITY was renamed to PLURNK_PROVIDERS_REASONING_BUDGET \(provider configuration contract\)/,
     );
 });
 
-test("#399: the shipped floor activates reasoning by default (adaptive — owner ruling)", async () => {
+test("the shipped floor activates reasoning 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 — budget is on-mode only");
 });
 
-test("#567: the shipped DRY floor stays off while retaining the measured alias-safe shape", async () => {
+test("the shipped DRY floor is off and claims no universally safe shape", async () => {
     const { readFileSync } = await import("node:fs");
     const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
-    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_MULTIPLIER=0$/m, "one-model tuning is not a universal sampler floor");
-    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_BASE=1\.75$/m);
-    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=32$/m, "the measured identifier-safe shape remains available for alias opt-in");
+    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_MULTIPLIER=0$/m, "a fidelity-corrupting sampler cannot be a portable floor");
+    assert.doesNotMatch(defaults, /^PLURNK_PROVIDERS_DRY_BASE=/m);
+    assert.doesNotMatch(defaults, /^PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=/m);
 });
 
-// -- #507: envelope reserves (owner-ruled migration from PLURNK_SERVICE_*) --
+// -- {§provider-generation-envelope} --
 
-test("#507 envelopeFromEnv: percentages and absolutes parse; missing/invalid fail hard", async () => {
+test("envelopeFromEnv: percentages and absolutes parse; missing/invalid fail hard", async () => {
     const { envelopeFromEnv } = await import("./env.ts");
     assert.deepEqual(
         envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "4096" } as NodeJS.ProcessEnv, "x"),
@@ -213,7 +203,7 @@ test("#507 envelopeFromEnv: percentages and absolutes parse; missing/invalid fai
     assert.throws(() => envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "-5", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%" } as NodeJS.ProcessEnv, "x"), /positive integer token count/);
 });
 
-test("#507 envelope knobs are per-alias scopable (measured envelope per box)", async () => {
+test("envelope knobs are per-alias scopable (measured envelope per box)", async () => {
     const { scopeEnvToAlias, envelopeFromEnv } = await import("./env.ts");
     const env = {
         PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",

package/src/env.ts

@@ -43,7 +43,7 @@ export const promptCacheKeyFromEnv = (env: NodeJS.ProcessEnv, label: string): bo
     return value === "1";
 };
 
-// Old-name shed (the #399/#472 lexicon renames): a still-set retired knob fails
+// {§provider-configuration} A still-set retired knob fails
 // hard pointing at its successor — never silently coexists with the new floor.
 // The retired names appear ONLY as this function's ARGUMENTS at the call sites
 // (each lexicon-allow), never as a live identifier.
@@ -52,7 +52,8 @@ const shedRenamed = (env: NodeJS.ProcessEnv, oldName: string, newName: string, l
     if (stale !== undefined && stale.length > 0) throw new Error(`${label} provider: ${oldName} was renamed to ${newName} (${ref}); update the env`);
 };
 
-// Data-capture knobs (#36), read identically by every provider (standard AND
+// {§provider-evidence} Data-capture knobs are read identically by every provider
+// (standard AND
 // plugin) so the opt-in surface is one source of truth. Both OFF by default —
 // the flag is the isolation, so serving turns request and carry nothing.
 //   PLURNK_PROVIDERS_TOP_LOGPROBS   "off" or a non-negative int = the OpenAI
@@ -71,41 +72,30 @@ export const dataCaptureFromEnv = (env: NodeJS.ProcessEnv, label: string): { top
     };
 };
 
-// The context-window pin (SPEC §4) under its OpenAI-lexicon name (#472) — the
-// industry term is "context window" (OpenAI/Anthropic docs, models.dev
-// contextWindow); CONTEXT_SIZE was home-grown. One reader for base AND
-// plugins, so the shed fires everywhere the knob is honored.
+// {§model-fact-resolution} — one context-window reader for every provider path;
+// the retired CONTEXT_SIZE spelling fails visibly at the same boundary.
 export const contextWindowFromEnv = (env: NodeJS.ProcessEnv, label: string): number | null => {
-    shedRenamed(env, "PLURNK_PROVIDERS_CONTEXT_SIZE", "PLURNK_PROVIDERS_CONTEXT_WINDOW", label, "the industry term, #472"); // lexicon-allow
+    shedRenamed(env, "PLURNK_PROVIDERS_CONTEXT_SIZE", "PLURNK_PROVIDERS_CONTEXT_WINDOW", label, "{§model-fact-resolution}"); // lexicon-allow
     return parseOptionalInt(env.PLURNK_PROVIDERS_CONTEXT_WINDOW, "PLURNK_PROVIDERS_CONTEXT_WINDOW", label);
 };
 
-export type ProviderTokenRates = { input: number; cached: number; output: number };
-
-export const tokenRatesFromEnv = (env: NodeJS.ProcessEnv, label: string): ProviderTokenRates | null => {
-    const inputName = "PLURNK_PROVIDERS_INPUT_USD_PER_MILLION";
-    const cachedName = "PLURNK_PROVIDERS_CACHE_READ_USD_PER_MILLION";
-    const outputName = "PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION";
-    const configured = [inputName, cachedName, outputName]
-        .some((name) => env[name] !== undefined && env[name] !== "");
-    if (!configured) return null;
-    const input = parseRequiredFloat(env[inputName], inputName, label, 0);
-    return {
-        input,
-        cached: env[cachedName] === undefined || env[cachedName] === ""
-            ? input
-            : parseRequiredFloat(env[cachedName], cachedName, label, 0),
-        output: parseRequiredFloat(env[outputName], outputName, label, 0),
-    };
-};
-
-// The generation-envelope reserves (#507, owner-ruled migration): how much of a
+// {§model-fact-resolution} — an operator value caps known model physics and
+// declares the window only when no natural value is known.
+export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number): number;
+export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number | null): number | null;
+export function effectiveContextWindow(operatorCap: number | null, naturalWindow: number | null): number | null {
+    return operatorCap === null
+        ? naturalWindow
+        : naturalWindow === null
+            ? operatorCap
+            : Math.min(operatorCap, naturalWindow);
+}
+
+// {§provider-generation-envelope} How much of a
 // DETECTED context window is reserved for reasoning and for completion — the
 // remainder (minus the consumer's own packing-safety margin) is the prompt
 // budget. Provider-owned: the window is a provider fact and these are amounts OF
-// it; the former PLURNK_SERVICE_{CONTEXT_WINDOW,REASONING,COMPLETION} knobs were
-// provider quantities wearing a service prefix (born as #352 packet parameters
-// before this surface existed). Each knob accepts a percentage of the window
+// it. Each knob accepts a percentage of the window
 // ("10%") or an absolute token count ("4096"); the floor ships percentages so
 // every window-advertising endpoint (llama-server n_ctx, the plurnk.ai router,
 // a cataloged cloud model) arrives at sane defaults with ZERO operator tuning.
@@ -151,21 +141,35 @@ export const resolveEnvelopeFromEnv = (env: NodeJS.ProcessEnv, window: number |
     };
 };
 
-// The side-channel reasoning knobs (SPEC §4, #32/#33) — ACTIVATION and BUDGET
+// {§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)
 //   PLURNK_PROVIDERS_REASONING_BUDGET  positive int, REQUIRED iff REASONING=on —
-//     the magnitude for tier/budget mapping. On llama.cpp the ENFORCEMENT is the
-//     box's --reasoning-budget launch flag (per-request numerics are ignored):
-//     env budget and launch flag are the same number, changed together.
+//     the magnitude for tier/budget mapping. On llama-server it is the explicit
+//     request-scoped allowance and cannot exceed the physical reasoning reserve.
 // The provider maps intent to the backend's mechanism; the consumer states
-// intent, never mechanism. (In-DSL PLAN reasoning is a grammar concern.)
+// 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 ReasoningResponseStyle = "verbatim" | "think-tags";
+
+export const reasoningResponseStyleFromEnv = (
+    env: NodeJS.ProcessEnv,
+    label: string,
+): ReasoningResponseStyle => {
+    const name = "PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE";
+    const raw = env[name];
+    if (raw === undefined || raw.length === 0) return "verbatim";
+    if (raw !== "verbatim" && raw !== "think-tags") {
+        throw new Error(`${label} provider: ${name} must be "verbatim" or "think-tags" (got "${raw}")`);
+    }
+    return raw;
+};
+
 export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoning => {
-    shedRenamed(env, "PLURNK_PROVIDERS_THINKING", "PLURNK_PROVIDERS_REASONING", label, "#399"); // lexicon-allow
-    shedRenamed(env, "PLURNK_PROVIDERS_THINKING_CAPACITY", "PLURNK_PROVIDERS_REASONING_BUDGET", label, "#399"); // lexicon-allow
+    shedRenamed(env, "PLURNK_PROVIDERS_THINKING", "PLURNK_PROVIDERS_REASONING", label, "provider configuration contract"); // lexicon-allow
+    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)`);
@@ -189,13 +193,12 @@ export const reasoningFromEnv = (env: NodeJS.ProcessEnv, label: string): Reasoni
 export const PROVIDERS_KNOBS = Object.freeze([
     "PLURNK_PROVIDERS_REASONING_RESERVE",
     "PLURNK_PROVIDERS_COMPLETION_RESERVE",
+    "PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE",
     "PLURNK_PROVIDERS_REASONING_BUDGET",
     "PLURNK_PROVIDERS_REASONING",
     "PLURNK_PROVIDERS_CONTEXT_WINDOW",
-    "PLURNK_PROVIDERS_INPUT_USD_PER_MILLION",
-    "PLURNK_PROVIDERS_CACHE_READ_USD_PER_MILLION",
-    "PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION",
     "PLURNK_PROVIDERS_RETRY_ATTEMPTS",
+    "PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT",
     "PLURNK_PROVIDERS_FETCH_TIMEOUT",
     "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT",
     "PLURNK_PROVIDERS_LLAMA_SERVER",