@plurnk/plurnk-providers 1.2.0 → 1.3.0

package/src/discover.test.ts

@@ -0,0 +1,123 @@
+import test, { type TestContext } from "node:test";
+import { strict as assert } from "node:assert";
+import fs from "node:fs/promises";
+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
+// 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> => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+    t.after(() => fs.rm(dir, { recursive: true, force: true }));
+    return dir;
+};
+
+const buildModules = async (t: TestContext, packages: Record<string, unknown>): Promise<string> => {
+    const root = await tempDir(t, "providers-scan-");
+    for (const [rel, pkg] of Object.entries(packages)) {
+        const dir = path.join(root, "node_modules", rel);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, "package.json"), JSON.stringify(pkg), "utf-8");
+    }
+    return root;
+};
+
+test("discover: the node_modules scan is scope-agnostic — third-party scopes are found", async (t) => {
+    const root = await buildModules(t, {
+        "@plurnk/plurnk-providers-openrouter": { name: "@plurnk/plurnk-providers-openrouter", plurnk: { kind: "provider", name: "openrouter" } },
+        "@acme/acme-provider-foo": { name: "@acme/acme-provider-foo", plurnk: { kind: "provider", name: "foo" } },
+        "unscoped-provider-bar": { name: "unscoped-provider-bar", plurnk: { kind: "provider", name: "bar" } },
+        "left-pad": { name: "left-pad" },                                   // no plurnk block → ignored
+        "@plurnk/plurnk-execs-git": { name: "@plurnk/plurnk-execs-git", plurnk: { kind: "exec", runtimes: [] } }, // wrong kind → ignored
+    });
+    const { registry } = await discover({ cwd: root });
+    assert.deepEqual([...registry.keys()].sort(), ["bar", "foo", "openrouter"]);
+    assert.equal(registry.get("foo"), "@acme/acme-provider-foo");      // third-party scope resolves
+    assert.equal(registry.get("bar"), "unscoped-provider-bar");        // unscoped resolves
+});
+
+test("discover: a provider package missing plurnk.name is ignored, not crashed", async (t) => {
+    const root = await buildModules(t, {
+        "@acme/headless": { name: "@acme/headless", plurnk: { kind: "provider" } },          // no name
+        "@acme/named": { name: "@acme/named", plurnk: { kind: "provider", name: "named" } },
+    });
+    const { registry } = await discover({ cwd: root });
+    assert.deepEqual([...registry.keys()], ["named"]);
+});
+
+test("discover: a name claimed by two packages is a fail-hard collision", async (t) => {
+    const root = await buildModules(t, {
+        "@plurnk/plurnk-providers-xai": { name: "@plurnk/plurnk-providers-xai", plurnk: { kind: "provider", name: "xai" } },
+        "@acme/rival-xai": { name: "@acme/rival-xai", plurnk: { kind: "provider", name: "xai" } },
+    });
+    await assert.rejects(
+        () => discover({ cwd: root }),
+        /provider name collision: 'xai' claimed by both/,
+    );
+});
+
+test("discover: node_modules entries with no package.json or malformed JSON are skipped, not crashed", async (t) => {
+    const root = await tempDir(t, "providers-junk-");
+    const nm = path.join(root, "node_modules");
+    await fs.mkdir(path.join(nm, "no-manifest"), { recursive: true });                  // a dir, no package.json
+    await fs.mkdir(path.join(nm, "broken"), { recursive: true });
+    await fs.writeFile(path.join(nm, "broken", "package.json"), "{ not json", "utf-8");  // malformed
+    const good = path.join(nm, "@plurnk", "plurnk-providers-ollama");
+    await fs.mkdir(good, { recursive: true });
+    await fs.writeFile(path.join(good, "package.json"), JSON.stringify({ name: "@plurnk/plurnk-providers-ollama", plurnk: { kind: "provider", name: "ollama" } }), "utf-8");
+    const { registry } = await discover({ cwd: root });
+    assert.deepEqual([...registry.keys()], ["ollama"]); // only the well-formed provider survives
+});
+
+test("discover: surfaces plurnk.attribution (string or string[]) for registered providers (#21)", 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 });
+    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
+});
+
+test("discover: missing node_modules yields an empty registry, not an error", async (t) => {
+    const root = await tempDir(t, "providers-empty-");
+    const { registry } = await discover({ cwd: root });
+    assert.equal(registry.size, 0);
+});
+
+// — trust gate (PLURNK_PLUGINS_TRUSTED_ONLY, #15) —
+
+const trustFixture = (t: TestContext) => buildModules(t, {
+    "@plurnk/plurnk-providers-openrouter": { name: "@plurnk/plurnk-providers-openrouter", plurnk: { kind: "provider", name: "openrouter" } },
+    "@acme/acme-provider-foo": { name: "@acme/acme-provider-foo", plurnk: { kind: "provider", name: "foo" } },
+});
+
+test("trust gate OFF (unset/empty/0): every provider is trusted", async (t) => {
+    const root = await trustFixture(t);
+    for (const gate of [undefined, "", "0"]) {
+        const { registry, skipped } = await discover({ cwd: root, env: { PLURNK_PLUGINS_TRUSTED_ONLY: gate } as NodeJS.ProcessEnv });
+        assert.deepEqual([...registry.keys()].sort(), ["foo", "openrouter"]);
+        assert.equal(skipped.size, 0);
+    }
+});
+
+test("trust gate ON: @plurnk/* always trusted; third party declined → skipped, not registered", async (t) => {
+    const root = await trustFixture(t);
+    const { registry, skipped } = await discover({ cwd: root, env: { PLURNK_PLUGINS_TRUSTED_ONLY: "1" } as NodeJS.ProcessEnv });
+    assert.deepEqual([...registry.keys()], ["openrouter"]);          // @plurnk/* survives
+    assert.equal(registry.has("foo"), false);                        // third party not registered
+    assert.equal(skipped.get("foo"), "@acme/acme-provider-foo");     // …recorded for a precise error
+});
+
+test("trust gate ON with an allowlist: a named third-party package is trusted", async (t) => {
+    const root = await trustFixture(t);
+    const { registry, skipped } = await discover({ cwd: root, env: { PLURNK_PLUGINS_TRUSTED_ONLY: "@acme/acme-provider-foo" } as NodeJS.ProcessEnv });
+    assert.deepEqual([...registry.keys()].sort(), ["foo", "openrouter"]);
+    assert.equal(skipped.size, 0);
+});

package/src/discover.ts

@@ -0,0 +1,112 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import Meta from "@plurnk/plurnk-meta";
+
+// Scope-agnostic discovery of installed provider packages (SPEC §5, #12/#14).
+// 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
+// PARTY can publish a provider under their own scope (`@acme/llm-provider-foo`)
+// and have it discovered with no involvement from us; first-party plugins
+// hoist flat via @plurnk/plurnk-providers-all so they land in the same scan.
+//
+// A provider package maps ONE name → its package specifier (unlike execs, whose
+// runtime tags are a per-package array). The name is the alias-cascade provider
+// segment (PLURNK_MODEL_<alias>=<name>/<model>). A name collision between two
+// installed packages is a FAIL-HARD ambiguity the operator must resolve.
+//
+// The standard-provider table (./standardProviders.ts) is a separate, closed
+// tier-1 resolved before this scan — discovery covers tier 2 (bespoke + third
+// party) only. Precedence and standard-name shadowing live in ProviderRegistry.
+//
+// Host plugin trust gate (PLURNK_PLUGINS_TRUSTED_ONLY, #15 / plurnk-service#229)
+// — 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.
+
+export type DiscoverOptions = {
+    cwd?: string;                  // defaults to process.cwd()
+    packageDirs?: string[];        // explicit dirs skip the node_modules scan (tests)
+    env?: NodeJS.ProcessEnv;       // trust-gate env; defaults to process.env
+};
+
+// name → package specifier, split by the trust decision.
+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.
+    attributions: Map<string, string | string[]>;
+};
+
+
+export const discover = async (options: DiscoverOptions = {}): Promise<Discovery> => {
+    const dirs = options.packageDirs ?? await defaultPackageDirs(options.cwd ?? process.cwd());
+    const env = options.env ?? process.env;
+
+    const registry = new Map<string, string>();
+    const skipped = new Map<string, string>();
+    const attributions = new Map<string, string | string[]>();
+    for (const dir of dirs) {
+        const info = await readProviderInfo(dir);
+        if (info === null) continue;
+        if (!Meta.isTrusted(info.packageName, env)) {
+            skipped.set(info.name, info.packageName); // declined — not a collision candidate
+            continue;
+        }
+        const existing = registry.get(info.name);
+        if (existing !== undefined) {
+            throw new Error(
+                `provider name collision: '${info.name}' claimed by both `
+                + `${existing} and ${info.packageName}`,
+            );
+        }
+        registry.set(info.name, info.packageName);
+        if (info.attribution !== undefined) attributions.set(info.name, info.attribution);
+    }
+    return { registry, skipped, attributions };
+};
+
+// Enumerate every installed package directory — scoped and unscoped — under
+// `<cwd>/node_modules`. Unreadable node_modules (e.g. nothing installed) → [].
+const defaultPackageDirs = async (cwd: string): Promise<string[]> => {
+    const nm = Meta.nearestNodeModules(cwd) ?? path.join(path.resolve(cwd), "node_modules");
+    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[] };
+
+const readProviderInfo = async (dir: string): Promise<ProviderInfo | null> => {
+    let raw: string;
+    try {
+        raw = await fs.readFile(path.join(dir, "package.json"), "utf-8");
+    } catch {
+        return null;
+    }
+    let pkg: unknown;
+    try {
+        pkg = JSON.parse(raw);
+    } catch {
+        return null;
+    }
+    if (typeof pkg !== "object" || pkg === null) return null;
+    const record = pkg as Record<string, unknown>;
+    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 (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 };
+};

package/src/env.test.ts

@@ -0,0 +1,190 @@
+import test from "node:test";
+import { strict as assert } from "node:assert";
+import { parseRequiredInt, parseOptionalInt, requireEnv, reasoningFromEnv } from "./env.ts";
+
+test("parseRequiredInt: parses a non-negative integer", () => {
+    assert.equal(parseRequiredInt("600000", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), 600000);
+    assert.equal(parseRequiredInt("0", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), 0);
+});
+
+test("parseRequiredInt: missing value names the env var and provider", () => {
+    assert.throws(() => parseRequiredInt(undefined, "PLURNK_PROVIDERS_FETCH_TIMEOUT", "groq"), /groq provider: PLURNK_PROVIDERS_FETCH_TIMEOUT must be set/);
+    assert.throws(() => parseRequiredInt("", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "groq"), /must be set/);
+});
+
+test("parseRequiredInt: rejects non-numeric, fractional, and negative values", () => {
+    assert.throws(() => parseRequiredInt("abc", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), /must be a non-negative integer \(got "abc"\)/);
+    assert.throws(() => parseRequiredInt("1.5", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), /must be a non-negative integer \(got "1\.5"\)/);
+    assert.throws(() => parseRequiredInt("-1", "PLURNK_PROVIDERS_FETCH_TIMEOUT", "openai"), /must be a non-negative integer \(got "-1"\)/);
+});
+
+test("parseOptionalInt: absent → null, present → integer", () => {
+    assert.equal(parseOptionalInt(undefined, "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), null);
+    assert.equal(parseOptionalInt("", "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), null);
+    assert.equal(parseOptionalInt("131072", "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), 131072);
+});
+
+test("parseOptionalInt: rejects fractional and negative values", () => {
+    assert.throws(() => parseOptionalInt("3.14", "PLURNK_PROVIDERS_CONTEXT_WINDOW", "openai"), /must be a non-negative integer/);
+    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)", () => {
+    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 });
+    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: "on" }, "openai"), /PLURNK_PROVIDERS_REASONING_BUDGET must be set when/);
+    assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "0" }, "openai"), /positive integer/);
+    assert.throws(() => reasoningFromEnv({ PLURNK_PROVIDERS_REASONING: "on", PLURNK_PROVIDERS_REASONING_BUDGET: "1.5" }, "openai"), /positive integer/);
+});
+
+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/);
+});
+
+// — 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 () => {
+    const { scopeEnvToAlias } = await import("./env.ts");
+    const env = {
+        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_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(scopeEnvToAlias(env, "plain").PLURNK_PROVIDERS_REASONING, "off"); // fallback intact
+});
+
+test("scopeEnvToAlias: aliases with underscores resolve; a bare knob is never mistaken for a suffix", async () => {
+    const { scopeEnvToAlias } = await import("./env.ts");
+    const env = {
+        PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000",
+        PLURNK_PROVIDERS_FETCH_TIMEOUT_my_box: "5000",
+        PLURNK_PROVIDERS_REASONING: "off",
+        PLURNK_PROVIDERS_REASONING_BUDGET: "4096", // bare budget — NOT a "_capacity" alias override of REASONING
+    } as NodeJS.ProcessEnv;
+    assert.equal(scopeEnvToAlias(env, "my_box").PLURNK_PROVIDERS_FETCH_TIMEOUT, "5000");
+    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 () => {
+    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 });
+    assert.deepEqual(dataCaptureFromEnv({ PLURNK_PROVIDERS_TOP_LOGPROBS: "3", PLURNK_PROVIDERS_RAWBODY: "1" } as NodeJS.ProcessEnv, "x"), { topLogprobs: 3, rawBody: true });
+    assert.deepEqual(dataCaptureFromEnv({ PLURNK_PROVIDERS_TOP_LOGPROBS: "0" } as NodeJS.ProcessEnv, "x"), { topLogprobs: 0, rawBody: false }); // set-to-0 = on, chosen-token only
+});
+
+test("OpenAI-lexicon shed: a still-set PLURNK_PROVIDERS_LOGPROB fails hard with the rename pointer", async () => {
+    const { dataCaptureFromEnv } = await import("./env.ts");
+    assert.throws(
+        () => dataCaptureFromEnv({ PLURNK_PROVIDERS_LOGPROB: "3" } as NodeJS.ProcessEnv, "openai"),
+        /PLURNK_PROVIDERS_LOGPROB was renamed to PLURNK_PROVIDERS_TOP_LOGPROBS/,
+    );
+});
+
+test("#472 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);
+    assert.throws(
+        () => contextWindowFromEnv({ PLURNK_PROVIDERS_CONTEXT_SIZE: "131072" } as NodeJS.ProcessEnv, "openai"),
+        /PLURNK_PROVIDERS_CONTEXT_SIZE was renamed to PLURNK_PROVIDERS_CONTEXT_WINDOW/,
+    );
+});
+
+test("scopeEnvToAlias: a caller-supplied knob list scopes CONSUMER vars (service window partition)", 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 = {
+        PLURNK_SERVICE_MAX_TURNS: "163840", PLURNK_SERVICE_LOOP_TIMEOUT: "16384", PLURNK_SERVICE_EXEC_HOLD_MS: "49152", PLURNK_SERVICE_SAFETY: "1024",
+        PLURNK_SERVICE_MAX_TURNS_turboderp: "78848", PLURNK_SERVICE_LOOP_TIMEOUT_turboderp: "4096", PLURNK_SERVICE_EXEC_HOLD_MS_TURBODERP: "8192", // case-folds
+    } as NodeJS.ProcessEnv;
+    const gemma = scopeEnvToAlias(env, "turboderp", SERVICE_KNOBS);
+    assert.equal(gemma.PLURNK_SERVICE_MAX_TURNS, "78848");
+    assert.equal(gemma.PLURNK_SERVICE_LOOP_TIMEOUT, "4096");
+    assert.equal(gemma.PLURNK_SERVICE_EXEC_HOLD_MS, "8192");
+    assert.equal(gemma.PLURNK_SERVICE_SAFETY, "1024"); // bare fallback intact
+    const cloud = scopeEnvToAlias(env, "fireslow", SERVICE_KNOBS);
+    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);
+    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 () => {
+    const { scopeEnvToAlias, dataCaptureFromEnv } = await import("./env.ts");
+    const env = {
+        PLURNK_PROVIDERS_TOP_LOGPROBS_fireslow: "3",
+        PLURNK_PROVIDERS_RAWBODY_fireslow: "1",
+    } as NodeJS.ProcessEnv;
+    assert.deepEqual(dataCaptureFromEnv(scopeEnvToAlias(env, "fireslow"), "x"), { topLogprobs: 3, rawBody: true });
+    assert.deepEqual(dataCaptureFromEnv(scopeEnvToAlias(env, "grokfast"), "x"), { topLogprobs: null, rawBody: false });
+});
+
+// Reader-declares (#44 ecosystem standard): 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 () => {
+    const { readFileSync } = await import("node:fs");
+    const { PROVIDERS_KNOBS } = await import("./env.ts");
+    const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
+    const missing = PROVIDERS_KNOBS.filter((k) => !defaults.includes(k));
+    assert.deepEqual([...missing], [], "knobs read by code but undeclared in .env.defaults");
+    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
+// with the migration pointer — never silently coexist with the new floor.
+test("#399: 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\)/,
+    );
+    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\)/,
+    );
+});
+
+test("#399: the shipped floor activates reasoning by default (adaptive — owner ruling)", 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");
+});
+
+// -- #507: envelope reserves (owner-ruled migration from PLURNK_SERVICE_*) --
+
+test("#507 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"),
+        { reasoningReserve: { percent: 0.1 }, completionReserve: { tokens: 4096 } },
+    );
+    assert.throws(() => envelopeFromEnv({ PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%" } as NodeJS.ProcessEnv, "x"), /PLURNK_PROVIDERS_REASONING_RESERVE must be set/);
+    assert.throws(() => envelopeFromEnv({ PLURNK_PROVIDERS_REASONING_RESERVE: "150%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%" } as NodeJS.ProcessEnv, "x"), /percentage must be in \(0, 100\)/);
+    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 () => {
+    const { scopeEnvToAlias, envelopeFromEnv } = await import("./env.ts");
+    const env = {
+        PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%",
+        PLURNK_PROVIDERS_REASONING_RESERVE_turboderp: "4096", PLURNK_PROVIDERS_COMPLETION_RESERVE_turboderp: "8192",
+    } as NodeJS.ProcessEnv;
+    assert.deepEqual(envelopeFromEnv(scopeEnvToAlias(env, "turboderp"), "x"), { reasoningReserve: { tokens: 4096 }, completionReserve: { tokens: 8192 } });
+    assert.deepEqual(envelopeFromEnv(scopeEnvToAlias(env, "jennifer"), "x"), { reasoningReserve: { percent: 0.1 }, completionReserve: { percent: 0.25 } });
+});

package/src/env.ts

@@ -0,0 +1,211 @@
+// Env-parsing helpers shared by every provider's fromEnv factory. Each was
+// copy-pasted per sibling with only the error-message prefix differing; the
+// `label` parameter (the provider name) restores that prefix from one source.
+
+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);
+    if (!Number.isInteger(n) || n < 0) throw new Error(`${label} provider: ${name} must be a non-negative integer (got "${raw}")`);
+    return n;
+};
+
+export const parseOptionalInt = (raw: string | undefined, name: string, label: string): number | null => {
+    if (raw === undefined || raw.length === 0) return null;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0) throw new Error(`${label} provider: ${name} must be a non-negative integer (got "${raw}")`);
+    return n;
+};
+
+export const parseRequiredFloat = (raw: string | undefined, name: string, label: string, min: number): number => {
+    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set`);
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < min) throw new Error(`${label} provider: ${name} must be a finite number >= ${min} (got "${raw}")`);
+    return n;
+};
+
+export const parseOptionalFloat = (raw: string | undefined, name: string, label: string, min: number): number | null => {
+    if (raw === undefined || raw.length === 0) return null;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < min) throw new Error(`${label} provider: ${name} must be a finite number >= ${min} (got "${raw}")`);
+    return n;
+};
+
+export const requireEnv = (raw: string | undefined, name: string, label: string): string => {
+    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set`);
+    return raw;
+};
+
+// Old-name shed (the #399/#472 lexicon renames): 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.
+const shedRenamed = (env: NodeJS.ProcessEnv, oldName: string, newName: string, label: string, ref: string): void => {
+    const stale = env[oldName];
+    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
+// 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   non-negative int = the OpenAI `top_logprobs`
+//     count (set -> request per-token logprobs; unset -> off). Per-alias-scopable.
+//   PLURNK_PROVIDERS_RAWBODY   truthy (not ""/"0") → attach the verbatim wire
+//     body to response.rawBody. Per-alias-scopable.
+export const dataCaptureFromEnv = (env: NodeJS.ProcessEnv, label: string): { topLogprobs: number | null; rawBody: boolean } => {
+    shedRenamed(env, "PLURNK_PROVIDERS_LOGPROB", "PLURNK_PROVIDERS_TOP_LOGPROBS", label, "the OpenAI wire term"); // lexicon-allow
+    return {
+        topLogprobs: parseOptionalInt(env.PLURNK_PROVIDERS_TOP_LOGPROBS, "PLURNK_PROVIDERS_TOP_LOGPROBS", label),
+        rawBody: env.PLURNK_PROVIDERS_RAWBODY !== undefined && env.PLURNK_PROVIDERS_RAWBODY !== "" && env.PLURNK_PROVIDERS_RAWBODY !== "0",
+    };
+};
+
+// 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.
+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
+    return parseOptionalInt(env.PLURNK_PROVIDERS_CONTEXT_WINDOW, "PLURNK_PROVIDERS_CONTEXT_WINDOW", label);
+};
+
+// The generation-envelope reserves (#507, owner-ruled migration): 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
+// ("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.
+// Per-alias suffixes override for measured envelopes; absolutes win over the
+// window derivation entirely.
+export type ReserveSpec = { percent: number } | { tokens: number };
+
+const parseReserve = (raw: string | undefined, name: string, label: string): ReserveSpec => {
+    if (raw === undefined || raw.length === 0) throw new Error(`${label} provider: ${name} must be set (a percentage of the window like "10%", or an absolute token count)`);
+    const pct = /^([0-9]+(?:\.[0-9]+)?)%$/.exec(raw);
+    if (pct !== null) {
+        const p = Number(pct[1]);
+        if (!Number.isFinite(p) || p <= 0 || p >= 100) throw new Error(`${label} provider: ${name} percentage must be in (0, 100) (got "${raw}")`);
+        return { percent: p / 100 };
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) throw new Error(`${label} provider: ${name} must be "<pct>%" or a positive integer token count (got "${raw}")`);
+    return { tokens: n };
+};
+
+export const envelopeFromEnv = (env: NodeJS.ProcessEnv, label: string): { reasoningReserve: ReserveSpec; completionReserve: ReserveSpec } => ({
+    reasoningReserve: parseReserve(env.PLURNK_PROVIDERS_REASONING_RESERVE, "PLURNK_PROVIDERS_REASONING_RESERVE", label),
+    completionReserve: parseReserve(env.PLURNK_PROVIDERS_COMPLETION_RESERVE, "PLURNK_PROVIDERS_COMPLETION_RESERVE", label),
+});
+
+// Resolve a ReserveSpec against a known window: absolutes stand alone; a
+// percentage needs the window (null when unknown — the underivable/no-cap case).
+export const resolveReserve = (spec: ReserveSpec, window: number | null): number | null =>
+    "tokens" in spec ? spec.tokens : window === null ? null : Math.round(spec.percent * window);
+
+// TOLERANT envelope read for fixtures + consumers that resolve reserves against
+// a known window and treat ABSENCE as "no claim" (null), never fail-hard —
+// unlike envelopeFromEnv (the REQUIRED provider path, fed by the shipped floor).
+// Mock uses this so the service's partition/budget suite drives the SAME
+// env→reserve resolution a real provider does, without the floor. An invalid
+// value still throws (a malformed reserve is an error, not an absence).
+export const resolveEnvelopeFromEnv = (env: NodeJS.ProcessEnv, window: number | null): { reasoningReserve: number | null; completionReserve: number | null } => {
+    const one = (raw: string | undefined, name: string): number | null =>
+        raw === undefined || raw.length === 0 ? null : resolveReserve(parseReserve(raw, name, "mock"), window);
+    return {
+        reasoningReserve: one(env.PLURNK_PROVIDERS_REASONING_RESERVE, "PLURNK_PROVIDERS_REASONING_RESERVE"),
+        completionReserve: one(env.PLURNK_PROVIDERS_COMPLETION_RESERVE, "PLURNK_PROVIDERS_COMPLETION_RESERVE"),
+    };
+};
+
+// The side-channel reasoning knobs (SPEC §4, #32/#33) — 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 provider maps intent to the backend's mechanism; the consumer states
+// intent, never mechanism. (In-DSL PLAN reasoning is a grammar concern.)
+export type ReasoningMode = "off" | "adaptive" | "on";
+export type Reasoning = { mode: ReasoningMode; budget: number | null };
+
+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
+    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}")`);
+    if (raw !== "on") return { mode: raw, budget: null };
+    const capName = "PLURNK_PROVIDERS_REASONING_BUDGET";
+    const capRaw = env[capName];
+    if (capRaw === undefined || capRaw.length === 0) throw new Error(`${label} provider: ${capName} must be set when ${name}=on`);
+    const n = Number(capRaw);
+    if (!Number.isInteger(n) || n <= 0) throw new Error(`${label} provider: ${capName} must be a positive integer (got "${capRaw}")`);
+    return { mode: "on", budget: n };
+};
+
+// ── Per-alias knob scoping (per-alias scoping doctrine, user 2026-07-03): PLURNK_PROVIDERS_<KNOB>[_<alias>] ──
+// Every plurnk-owned knob accepts a per-alias override — the suffixed form wins,
+// the bare form is the fallback — so two aliases on one provider name (two boxes,
+// two models) stop sharing one global setting. The knob list is CLOSED and parsed
+// exact-prefix-first, so aliases containing underscores stay unambiguous. Vendor
+// facts (API keys, canonical endpoints) remain vendor-named; the per-alias
+// endpoint override stays PLURNK_BASEURL_<alias> (its existing precedent).
+export const PROVIDERS_KNOBS = Object.freeze([
+    "PLURNK_PROVIDERS_REASONING_RESERVE",
+    "PLURNK_PROVIDERS_COMPLETION_RESERVE",
+    "PLURNK_PROVIDERS_REASONING_BUDGET",
+    "PLURNK_PROVIDERS_REASONING",
+    "PLURNK_PROVIDERS_CONTEXT_WINDOW",
+    "PLURNK_PROVIDERS_RETRY_ATTEMPTS",
+    "PLURNK_PROVIDERS_FETCH_TIMEOUT",
+    "PLURNK_PROVIDERS_LLAMA_SERVER",
+    "PLURNK_PROVIDERS_TEMPERATURE",
+    "PLURNK_PROVIDERS_REPEAT_PENALTY",
+    "PLURNK_PROVIDERS_FREQUENCY_PENALTY",
+    "PLURNK_PROVIDERS_REPEAT_LAST_N",
+    "PLURNK_PROVIDERS_DRY_MULTIPLIER",
+    "PLURNK_PROVIDERS_DRY_BASE",
+    "PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH",
+    "PLURNK_PROVIDERS_RETRY_DELAY",
+    "PLURNK_PROVIDERS_PROBE_ATTEMPTS",
+    "PLURNK_PROVIDERS_PROBE_DELAY",
+    "PLURNK_PROVIDERS_GBNF_DEBUG",
+    "PLURNK_PROVIDERS_TOP_LOGPROBS",
+    "PLURNK_PROVIDERS_RAWBODY",
+]);
+
+// Materialize an alias-scoped VIEW of env: for each known knob with a
+// `_<alias>`-suffixed key (suffix case-folds to the alias, matching the
+// PLURNK_MODEL_/PLURNK_BASEURL_ convention), overlay it onto the bare name.
+// Providers keep reading plain vars — scoping is entirely the caller's overlay,
+// so fromEnv implementations (and plugins) need zero changes.
+//
+// `knobs` (optional) lets a CONSUMER scope its OWN closed knob list with this
+// same parser — e.g. the service's window-partition vars (PLURNK_SERVICE_CONTEXT_WINDOW/
+// MAX_TURNS/...), so a 64k cloud envelope and a 12k gemma envelope
+// coexist per-alias without the service reimplementing the suffix/collision
+// rules. Default stays the providers-family list; my call sites pass nothing.
+export const scopeEnvToAlias = (env: NodeJS.ProcessEnv, alias: string, knobs: readonly string[] = PROVIDERS_KNOBS): NodeJS.ProcessEnv => {
+    const folded = alias.toLowerCase();
+    const out: NodeJS.ProcessEnv = { ...env };
+    for (const knob of knobs) {
+        for (const [key, value] of Object.entries(env)) {
+            if (value === undefined || value.length === 0) continue;
+            if (!key.startsWith(knob + "_")) continue;
+            // A bare knob can prefix another bare knob (_REASONING prefixes
+            // _REASONING_BUDGET, _CONTEXT prefixes a hypothetical _CONTEXT_WINDOW): a key
+            // that IS a known knob is never a suffixed override, whatever the
+            // alias is named.
+            if (knobs.includes(key)) continue;
+            if (key.slice(knob.length + 1).toLowerCase() !== folded) continue;
+            out[knob] = value;
+            break;
+        }
+    }
+    return out;
+};