@plurnk/plurnk-providers 1.1.1 → 1.3.0

package/src/Pool.test.ts

@@ -0,0 +1,155 @@
+import test from "node:test";
+import { strict as assert } from "node:assert";
+import Pool from "./Pool.ts";
+import { ProviderError } from "./telemetry.ts";
+import type { Provider, ProviderResponse } from "./types.ts";
+import { resetEmittedWarnings } from "./warnings.ts";
+
+test.afterEach(() => { resetEmittedWarnings(); });
+
+const RESP = { assistant: { usage: { prompt: 1, completion: 1, reasoning: 0, cached: 0, total: 2 } }, assistantRaw: null } as unknown as ProviderResponse;
+
+type FakeOpts = {
+    model?: string; window?: number | null; servedModel?: string;
+    constrainsOutput?: boolean; requiresMaxTokens?: boolean;
+    reasoningReserve?: number | null; completionReserve?: number | null;
+    tokenize?: boolean; cost?: number; throws?: Error;
+};
+// A fake backend that records which workers it served, and optionally throws.
+const backend = (opts: FakeOpts = {}) => {
+    const served: string[] = [];
+    const b: Provider = {
+        model: opts.model ?? "gemma",
+        contextWindow: opts.window === undefined ? 48000 : opts.window,
+        ...(opts.servedModel !== undefined ? { servedModel: opts.servedModel } : {}),
+        ...(opts.constrainsOutput !== undefined ? { constrainsOutput: opts.constrainsOutput } : {}),
+        ...(opts.requiresMaxTokens !== undefined ? { requiresMaxTokens: opts.requiresMaxTokens } : {}),
+        ...(opts.reasoningReserve !== undefined ? { reasoningReserve: opts.reasoningReserve } : {}),
+        ...(opts.completionReserve !== undefined ? { completionReserve: opts.completionReserve } : {}),
+        ...(opts.tokenize ? { tokenize: async (t: string) => [t.length] } : {}),
+        countTokens: (t: string) => t.length,
+        costFor: () => opts.cost ?? 0,
+        generate: async (args: Parameters<Provider["generate"]>[0]): Promise<ProviderResponse> => {
+            served.push(args.workerId);
+            if (opts.throws !== undefined) throw opts.throws;
+            return RESP;
+        },
+    };
+    return { b, served };
+};
+const netErr = () => new ProviderError("provider:x", "network_failure", "down", { status: 503 });
+const authErr = () => new ProviderError("provider:x", "unauthorized", "no key", { status: 401 });
+const gen = (p: Pool, workerId: string, extra: Record<string, unknown> = {}) =>
+    p.generate({ messages: [], workerId, ...extra } as Parameters<Provider["generate"]>[0]);
+
+// --- construction / homogeneity ---
+
+test("Pool: empty backend list is rejected", () => {
+    assert.throws(() => new Pool([]), /at least one backend/);
+});
+
+test("Pool: mixed models are rejected at construction (heterogeneous blend is not a pool)", () => {
+    assert.throws(() => new Pool([backend({ model: "gemma" }).b, backend({ model: "grok" }).b]), /interchangeable/);
+});
+
+// --- surface aggregation ---
+
+test("Pool: contextWindow is the safe floor (min) across backends", () => {
+    assert.equal(new Pool([backend({ window: 48000 }).b, backend({ window: 32000 }).b]).contextWindow, 32000);
+});
+
+test("Pool: any unknown (null) window makes the pool null - no improvised cap (#421)", () => {
+    assert.equal(new Pool([backend({ window: 48000 }).b, backend({ window: null }).b]).contextWindow, null);
+});
+
+test("Pool: reserves travel with the floor window", () => {
+    const big = backend({ window: 48000, reasoningReserve: 4800, completionReserve: 12000 }).b;
+    const small = backend({ window: 32000, reasoningReserve: 3200, completionReserve: 8000 }).b;
+    const p = new Pool([big, small]);
+    assert.equal(p.contextWindow, 32000);
+    assert.equal(p.reasoningReserve, 3200);   // the floor backend's, not the larger one's
+    assert.equal(p.completionReserve, 8000);
+});
+
+test("Pool: capabilities aggregate conservatively (constrainsOutput all-true, requiresMaxTokens any-true)", () => {
+    assert.equal(new Pool([backend({ constrainsOutput: true }).b, backend({ constrainsOutput: true }).b]).constrainsOutput, true);
+    assert.equal(new Pool([backend({ constrainsOutput: true }).b, backend({ constrainsOutput: false }).b]).constrainsOutput, undefined);
+    assert.equal(new Pool([backend({ requiresMaxTokens: false }).b, backend({ requiresMaxTokens: true }).b]).requiresMaxTokens, true);
+    assert.equal(new Pool([backend({}).b]).requiresMaxTokens, undefined);
+});
+
+test("Pool: servedModel is the common id, undefined when they differ", () => {
+    assert.equal(new Pool([backend({ servedModel: "g.gguf" }).b, backend({ servedModel: "g.gguf" }).b]).servedModel, "g.gguf");
+    assert.equal(new Pool([backend({ servedModel: "g.gguf" }).b, backend({ servedModel: "h.gguf" }).b]).servedModel, undefined);
+});
+
+test("Pool: tokenize is exposed iff every backend has it", () => {
+    assert.equal(typeof new Pool([backend({ tokenize: true }).b, backend({ tokenize: true }).b]).tokenize, "function");
+    assert.equal(new Pool([backend({ tokenize: true }).b, backend({ tokenize: false }).b]).tokenize, undefined);
+});
+
+test("Pool: countTokens + costFor delegate to a backend", () => {
+    const p = new Pool([backend({ cost: 42 }).b]);
+    assert.equal(p.countTokens("abcd"), 4);
+    assert.equal(p.costFor({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 42);
+});
+
+// --- dispatch: round-robin + affinity ---
+
+test("Pool: NEW workers round-robin across backends", async () => {
+    const b0 = backend(), b1 = backend(), b2 = backend();
+    const p = new Pool([b0.b, b1.b, b2.b]);
+    await gen(p, "w1"); await gen(p, "w2"); await gen(p, "w3"); await gen(p, "w4");
+    assert.deepEqual(b0.served, ["w1", "w4"]); // 0, then wraps at 3 % 3
+    assert.deepEqual(b1.served, ["w2"]);
+    assert.deepEqual(b2.served, ["w3"]);
+});
+
+test("Pool: a worker STICKS to its backend across turns (KV-cache affinity)", async () => {
+    const b0 = backend(), b1 = backend();
+    const p = new Pool([b0.b, b1.b]);
+    await gen(p, "w1"); await gen(p, "w2"); await gen(p, "w1"); await gen(p, "w1");
+    assert.deepEqual(b0.served, ["w1", "w1", "w1"]); // w1 always backend 0
+    assert.deepEqual(b1.served, ["w2"]);
+});
+
+// --- dispatch: overflow ---
+
+test("Pool: a backend-availability failure overflows to a healthy sibling and re-sticks", async () => {
+    const down = backend({ throws: netErr() }), up = backend();
+    const p = new Pool([down.b, up.b]);
+    await gen(p, "w1");                     // w1 -> backend 0 (down) -> overflow to backend 1 (up)
+    assert.deepEqual(down.served, ["w1"]);
+    assert.deepEqual(up.served, ["w1"]);
+    await gen(p, "w1");                     // re-stuck: w1 now routes straight to backend 1
+    assert.deepEqual(down.served, ["w1"]);  // NOT hit again
+    assert.deepEqual(up.served, ["w1", "w1"]);
+});
+
+test("Pool: a terminal (auth) failure does NOT overflow", async () => {
+    const bad = backend({ throws: authErr() }), other = backend();
+    const p = new Pool([bad.b, other.b]);
+    await assert.rejects(() => gen(p, "w1"), /no key/);
+    assert.deepEqual(bad.served, ["w1"]);
+    assert.deepEqual(other.served, []);     // never tried - auth fails the same on a peer
+});
+
+test("Pool: whole fleet unavailable throws the last error, each backend tried once", async () => {
+    const a = backend({ throws: netErr() }), b = backend({ throws: netErr() });
+    const p = new Pool([a.b, b.b]);
+    await assert.rejects(() => gen(p, "w1"), (e: unknown) => e instanceof ProviderError && e.kind === "network_failure");
+    assert.deepEqual(a.served, ["w1"]);
+    assert.deepEqual(b.served, ["w1"]);
+});
+
+test("Pool: an aborted signal propagates, never overflows", async () => {
+    const down = backend({ throws: netErr() }), up = backend();
+    const p = new Pool([down.b, up.b]);
+    const ac = new AbortController(); ac.abort();
+    await assert.rejects(() => gen(p, "w1", { signal: ac.signal }), /down/);
+    assert.deepEqual(up.served, []);        // cancellation is not a failover
+});
+
+test("Pool: generate requires a workerId (affinity keys on it)", async () => {
+    await assert.rejects(() => gen(new Pool([backend().b]), ""), /workerId is required/);
+});

package/src/Pool.ts

@@ -0,0 +1,134 @@
+import type { Provider, ProviderResponse, ProviderUsage, ChatMessage } from "./types.ts";
+import { ProviderError, type ProviderTelemetryKind } from "./telemetry.ts";
+import { emitWarningOnce } from "./warnings.ts";
+
+// A backend-AVAILABILITY failure: the sub-provider already exhausted its OWN
+// transient retries (#18) before throwing one of these, so re-hitting the same
+// backend is pointless - a sibling may still serve, so the pool overflows to it.
+// Auth/quota/content kinds are deliberately absent: a peer backend fails them
+// identically, and failing over would only multiply the damage (and the spend).
+const OVERFLOW_KINDS: ReadonlySet<ProviderTelemetryKind> = new Set(["network_failure", "rate_limit"]);
+
+// Pool - fronts N INTERCHANGEABLE backends as one Provider. This is CAPACITY, not
+// blend: the mechanism (round-robin across workers, sticky within a worker for
+// KV-cache reuse, overflow to a healthy sibling) is public and lives here; the
+// blend/escalation DECISION (which SKU, when to switch models) stays the
+// consumer's, one level up, by choosing WHICH pool to call. Backends MUST be
+// interchangeable - same served model, compatible window - so the pool presents ONE
+// honest Provider surface instead of pretending N models are one (#533).
+//
+// Affinity is the load-bearing part. A worker's turns stick to one backend so its
+// stable prompt prefix keeps hitting the same KV cache; scattering a worker across
+// backends shreds the prefix cache (#531). It is the #11 slot-affinity pattern one
+// level up: worker -> slot within a llama-server becomes worker -> backend across a
+// fleet - round-robin ACROSS workers, sticky WITHIN one.
+export default class Pool implements Provider {
+    readonly #backends: readonly Provider[];
+    readonly #affinity = new Map<string, number>(); // workerId -> backend index; sticky, LRU-bounded
+    readonly #cap: number;                            // LRU ceiling on the affinity map
+    #next = 0;                                        // round-robin cursor for NEW workers
+    readonly #floor: Provider;                        // the min-window backend: the safe budget floor
+
+    // OPTIONAL exact tokenizer (#37): present iff EVERY backend exposes one (same
+    // vocab, since interchangeable). Delegated; absent when the fleet can't.
+    readonly tokenize?: (text: string) => Promise<number[]>;
+
+    constructor(backends: readonly Provider[]) {
+        if (backends.length === 0) throw new Error("Pool: at least one backend is required");
+        // Homogeneity is a CONTRACT, not a hope: interchangeable backends share a
+        // served identity. A heterogeneous "pool" is the consumer's per-turn
+        // SELECTION job, not this primitive - fail at construction, never mid-turn.
+        const model = backends[0].model;
+        const mixed = backends.find((b) => b.model !== model);
+        if (mixed !== undefined) throw new Error(`Pool: backends must be interchangeable, got mixed models "${model}" and "${mixed.model}" - heterogeneous blend is the consumer's selection, not a pool (#533)`);
+        this.#backends = backends;
+        this.#cap = backends.length * 8;
+
+        // The exposed window is the SAFE FLOOR across backends (a packet that fits the
+        // smallest fits all); its reserves travel with it so the budget stays
+        // self-consistent. ANY unknown (null) window makes the pool null - a worker
+        // might route to it, and the consumer must not improvise a cap (#421).
+        const anyUnknown = backends.find((b) => b.contextWindow === null);
+        this.#floor = anyUnknown ?? backends.reduce((lo, b) => (b.contextWindow! < lo.contextWindow! ? b : lo));
+        if (new Set(backends.map((b) => b.contextWindow)).size > 1) {
+            emitWarningOnce(
+                `Pool: backends report different context windows (${backends.map((b) => b.contextWindow).join(", ")}); using the safe floor ${this.#floor.contextWindow}. Interchangeable backends should match.`,
+                "PLURNK_POOL_WINDOW_DRIFT",
+            );
+        }
+
+        // tokenize is a per-instance optional method; expose it iff the whole fleet has it.
+        if (backends.every((b) => typeof b.tokenize === "function")) this.tokenize = (text) => this.#backends[0].tokenize!(text);
+    }
+
+    // --- Provider surface: interchangeable backends collapse to one honest face ---
+
+    get model(): string { return this.#backends[0].model; }
+    get contextWindow(): number | null { return this.#floor.contextWindow; }
+    get reasoningReserve(): number | null | undefined { return this.#floor.reasoningReserve; }
+    get completionReserve(): number | null | undefined { return this.#floor.completionReserve; }
+
+    // Served id / capabilities aggregate CONSERVATIVELY: a worker could land on any
+    // backend, so claim `constrainsOutput` only if EVERY backend does, and
+    // `requiresMaxTokens` if ANY does (bring a cap if even one backend needs it).
+    get servedModel(): string | undefined {
+        const s = this.#backends[0].servedModel;
+        return this.#backends.every((b) => b.servedModel === s) ? s : undefined;
+    }
+    get constrainsOutput(): boolean | undefined {
+        return this.#backends.every((b) => b.constrainsOutput === true) ? true : undefined;
+    }
+    get requiresMaxTokens(): boolean | undefined {
+        return this.#backends.some((b) => b.requiresMaxTokens === true) ? true : undefined;
+    }
+
+    countTokens(text: string): number { return this.#backends[0].countTokens(text); }
+    costFor(usage: ProviderUsage): number { return this.#backends[0].costFor(usage); }
+
+    // --- dispatch ---
+
+    async generate(args: { messages: ChatMessage[]; workerId: string; primaryWorkerId?: string; signal?: AbortSignal; grammar?: string; maxTokens?: number; attributions?: string[]; client?: string; strikes?: number; workspaceId?: string; loop?: number; turn?: number; sampling?: Record<string, unknown> }): Promise<ProviderResponse> {
+        const { workerId, signal } = args;
+        if (workerId === undefined || workerId.length === 0) throw new Error("Pool.generate: workerId is required - affinity keys on it");
+        const tried = new Set<number>();
+        let idx = this.#route(workerId);
+        let lastErr: unknown;
+        for (;;) {
+            tried.add(idx);
+            try {
+                return await this.#backends[idx].generate(args);
+            } catch (err) {
+                lastErr = err;
+                if (signal?.aborted) throw err; // caller cancellation is never a failover
+                // Only a backend-AVAILABILITY failure overflows; auth/quota/content/
+                // malformed fail the same on a peer, so they propagate.
+                if (!(err instanceof ProviderError) || !OVERFLOW_KINDS.has(err.kind)) throw err;
+                const next = this.#nextUntried(tried);
+                if (next === null) throw lastErr; // the whole fleet is unavailable
+                this.#affinity.set(workerId, next); // re-stick: the worker's cache moves with it
+                idx = next;
+            }
+        }
+    }
+
+    // Route a worker to its affine backend, assigning a fresh one round-robin on
+    // first sight. LRU-bounded so a long-lived daemon's map never grows unbounded -
+    // an evicted-and-returning worker simply re-pins (one cold prefill, worst case).
+    #route(workerId: string): number {
+        const pinned = this.#affinity.get(workerId);
+        if (pinned !== undefined) {
+            this.#affinity.delete(workerId); // refresh LRU recency
+            this.#affinity.set(workerId, pinned);
+            return pinned;
+        }
+        const idx = this.#next++ % this.#backends.length;
+        if (this.#affinity.size >= this.#cap) this.#affinity.delete(this.#affinity.keys().next().value as string);
+        this.#affinity.set(workerId, idx);
+        return idx;
+    }
+
+    #nextUntried(tried: Set<number>): number | null {
+        for (let i = 0; i < this.#backends.length; i++) if (!tried.has(i)) return i;
+        return null;
+    }
+}

package/src/ProviderRegistry.test.ts

@@ -0,0 +1,176 @@
+import test, { mock } from "node:test";
+import { strict as assert } from "node:assert";
+import { instantiateProvider, loadActiveProvider, resetDiscoveryCache } from "./ProviderRegistry.ts";
+
+const fakeProvider = { contextWindow: 1, model: "m", countTokens: () => 0, costFor: () => 0, generate: async () => { throw new Error("unused"); } };
+const mapOf = (entries: Record<string, string>, skipped: Record<string, string> = {}) =>
+    async () => ({ registry: new Map(Object.entries(entries)), skipped: new Map(Object.entries(skipped)), attributions: new Map<string, string | string[]>() });
+
+// Alias PARSING is tested in @plurnk/plurnk-aliases (its owner, #27). Here we
+// exercise the resolution + two-tier instantiation this module owns; the active
+// alias is driven end-to-end by loadActiveProvider below.
+
+// — two-tier instantiation (SPEC §5) —
+
+const fullEnv = Object.freeze({
+    PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000",
+    PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_RETRY_DELAY: "1", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    OPENAI_BASE_URL: "http://x",
+});
+
+test("instantiateProvider: standard name resolves in-framework, no scan, no import", async () => {
+    resetDiscoveryCache();
+    mock.method(globalThis, "fetch", async (url: string) => {
+        if (String(url).endsWith("/models")) return new Response(JSON.stringify({ data: [] }), { status: 200 });
+        throw new Error("unexpected fetch");
+    });
+    const imports: string[] = [];
+    let scanned = false;
+    const p = await instantiateProvider("openai", { ...fullEnv }, "m",
+        async (s) => { imports.push(s); return {}; },
+        async () => { scanned = true; return { registry: new Map(), skipped: new Map(), attributions: new Map() }; });
+    assert.equal(p.model, "m");
+    assert.deepEqual(imports, []); // tier 1 never touches the importer…
+    assert.equal(scanned, false); // …nor the scan
+    mock.restoreAll();
+});
+
+test("instantiateProvider: bespoke name resolves via the scan and imports the discovered package", async () => {
+    resetDiscoveryCache();
+    const calls: unknown[] = [];
+    const p = await instantiateProvider("openrouter", { ...fullEnv }, "anthropic/claude-opus-latest",
+        async (specifier) => { calls.push(specifier); return { default: { fromEnv: async (_e: NodeJS.ProcessEnv, model: string) => { calls.push(model); return fakeProvider; } } }; },
+        mapOf({ openrouter: "@plurnk/plurnk-providers-openrouter" }));
+    assert.equal(p, fakeProvider);
+    assert.deepEqual(calls, ["@plurnk/plurnk-providers-openrouter", "anthropic/claude-opus-latest"]);
+});
+
+test("instantiateProvider: a per-alias baseUrl is passed to a bespoke factory as the 3rd-arg option", async () => {
+    resetDiscoveryCache();
+    let received: unknown;
+    await instantiateProvider("ollama", { ...fullEnv }, "qwen2.5-coder",
+        async () => ({ default: { fromEnv: async (_e: NodeJS.ProcessEnv, _m: string, options?: unknown) => { received = options; return fakeProvider; } } }),
+        mapOf({ ollama: "@plurnk/plurnk-providers-ollama" }),
+        "http://nook:11434");
+    assert.deepEqual(received, { baseUrl: "http://nook:11434" });
+});
+
+test("instantiateProvider: a per-alias baseUrl drives the standard openai probe to the override host", async () => {
+    resetDiscoveryCache();
+    const probed: string[] = [];
+    mock.method(globalThis, "fetch", async (url: string) => {
+        probed.push(String(url));
+        return new Response(JSON.stringify({ data: [] }), { status: 200 });
+    });
+    await instantiateProvider("openai", { ...fullEnv }, "m", // fullEnv.OPENAI_BASE_URL is http://x — the override must win
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        "http://hazel2:8080/v1");
+    assert.ok(probed.some((u) => u === "http://hazel2:8080/v1/models"), `probe hit the override host; saw ${probed.join(", ")}`);
+    assert.equal(probed.some((u) => u.startsWith("http://x")), false); // never the per-name OPENAI_BASE_URL
+    mock.restoreAll();
+});
+
+test("instantiateProvider: a THIRD-PARTY scope is discovered — name maps to its package", async () => {
+    resetDiscoveryCache();
+    const imports: string[] = [];
+    const p = await instantiateProvider("foo", { ...fullEnv }, "m",
+        async (specifier) => { imports.push(specifier); return { default: { fromEnv: async () => fakeProvider } }; },
+        mapOf({ foo: "@acme/acme-provider-foo" }));
+    assert.equal(p, fakeProvider);
+    assert.deepEqual(imports, ["@acme/acme-provider-foo"]); // not an @plurnk/ specifier
+});
+
+test("instantiateProvider: a standard name is authoritative — a scanned package of the same name is shadowed", async () => {
+    resetDiscoveryCache();
+    mock.method(globalThis, "fetch", async (url: string) => {
+        if (String(url).endsWith("/models")) return new Response(JSON.stringify({ data: [] }), { status: 200 });
+        throw new Error("unexpected fetch");
+    });
+    const imports: string[] = [];
+    const p = await instantiateProvider("openai", { ...fullEnv }, "m",
+        async (s) => { imports.push(s); return {}; },
+        mapOf({ openai: "@acme/acme-provider-openai" })); // shadowed by tier 1
+    assert.equal(p.model, "m");
+    assert.deepEqual(imports, []); // the scanned same-name package is never imported
+    mock.restoreAll();
+});
+
+test("instantiateProvider: unknown provider throws — no standard, no discovered package", async () => {
+    resetDiscoveryCache();
+    await assert.rejects(
+        () => instantiateProvider("nope", { ...fullEnv }, "m", async () => ({}), mapOf({})),
+        /unknown provider "nope": not a standard provider, and no installed package declares plurnk\.kind:"provider" with name "nope"/,
+    );
+});
+
+test("instantiateProvider: an untrusted (skipped) provider gives a precise error, not 'unknown' (#15)", async () => {
+    resetDiscoveryCache();
+    const imports: string[] = [];
+    await assert.rejects(
+        () => instantiateProvider("foo", { ...fullEnv }, "m",
+            async (s) => { imports.push(s); return {}; },
+            mapOf({}, { foo: "@acme/acme-provider-foo" })), // discovered but trust-declined
+        /provider "foo" resolves to @acme\/acme-provider-foo, but it is untrusted under PLURNK_PLUGINS_TRUSTED_ONLY/,
+    );
+    assert.deepEqual(imports, []); // never imported an untrusted package
+});
+
+test("instantiateProvider: discovered package without a fromEnv factory throws (factory shape, SPEC )", async () => {
+    resetDiscoveryCache();
+    await assert.rejects(
+        () => instantiateProvider("broken", { ...fullEnv }, "m",
+            async () => ({ default: {} }),
+            mapOf({ broken: "@acme/acme-provider-broken" })),
+        /@acme\/acme-provider-broken default export is not a Provider factory/,
+    );
+});
+
+test("instantiateProvider: a discovered package whose import throws fails hard, naming the specifier and preserving the cause", async () => {
+    resetDiscoveryCache();
+    const cause = new Error("ERR_MODULE_NOT_FOUND");
+    await assert.rejects(
+        () => instantiateProvider("foo", { ...fullEnv }, "m",
+            async () => { throw cause; },
+            mapOf({ foo: "@acme/acme-provider-foo" })),
+        (err: Error) => {
+            assert.match(err.message, /provider "foo" resolves to @acme\/acme-provider-foo, but importing it failed/);
+            assert.equal(err.cause, cause); // original error preserved
+            return true;
+        },
+    );
+});
+
+test("instantiateProvider: per-alias knobs scope through to the provider (per-alias scoping doctrine, user 2026-07-03)", async () => {
+    resetDiscoveryCache();
+    mock.method(globalThis, "fetch", async (url: string) => {
+        if (String(url).endsWith("/models")) return new Response(JSON.stringify({ data: [] }), { status: 200 });
+        if (String(url).endsWith("/props")) return new Response(JSON.stringify({ total_slots: 1 }), { status: 200 });
+        return new Response(JSON.stringify({ data: [] }), { status: 200 });
+    });
+    const env = { ...fullEnv, PLURNK_PROVIDERS_CONTEXT_WINDOW_turbo: "12345", PLURNK_PROVIDERS_LLAMA_SERVER_turbo: "1" };
+    const p = await instantiateProvider("openai", env, "m",
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        undefined, "turbo");
+    assert.equal(p.contextWindow, 12345); // _turbo CONTEXT_WINDOW reached the provider
+    assert.equal(p.constrainsOutput, true); // _turbo LLAMA_SERVER pin reached it too
+    // same env, DIFFERENT alias: neither override applies
+    const q = await instantiateProvider("openai", env, "m",
+        async () => ({}), async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() }),
+        undefined, "plain");
+    assert.equal(q.contextWindow, null);
+    assert.equal(q.constrainsOutput, false);
+    mock.restoreAll();
+});
+
+test("loadActiveProvider: resolves the alias cascade end-to-end via the scan", async () => {
+    resetDiscoveryCache();
+    const env = { ...fullEnv, PLURNK_MODEL: "opus", PLURNK_MODEL_opus: "openrouter/anthropic/claude-opus-latest" } as NodeJS.ProcessEnv;
+    const p = await loadActiveProvider(env,
+        async () => ({ default: { fromEnv: async () => fakeProvider } }),
+        mapOf({ openrouter: "@plurnk/plurnk-providers-openrouter" }));
+    assert.equal(p, fakeProvider);
+});
+
+test("loadActiveProvider: throws a named error when no alias is active", async () => {
+    await assert.rejects(() => loadActiveProvider({ ...fullEnv }), /set PLURNK_MODEL to an alias/);
+});

package/src/ProviderRegistry.ts

@@ -0,0 +1,93 @@
+// Provider instantiation + active-alias resolution. Alias PARSING (the
+// PLURNK_MODEL_<alias>=<provider>/<model> cascade + PLURNK_BASEURL_<alias>
+// overrides) lives in @plurnk/plurnk-aliases — the zero-dep parser shared with
+// thin clients (#27); this module resolves the active alias to a Provider.
+//
+// Two-tier resolution (SPEC §5): tier 1 is the closed standard-provider table;
+// tier 2 is a SCOPE-AGNOSTIC node_modules scan (discover()) for packages
+// declaring `plurnk.kind:"provider"` — first-party plugins (installed flat
+// via @plurnk/plurnk-providers-all) AND third-party providers under any scope.
+// The framework is contract-only — it does NOT depend on its plugins; the
+// scan is what surfaces them (#12/#14).
+
+import type { Provider, ProviderFactory } from "./types.ts";
+import { isStandardProvider, standardProviderFromEnv } from "./standardProviders.ts";
+import { discover, type DiscoverOptions, type Discovery } from "./discover.ts";
+import { resolveActiveAlias } from "@plurnk/plurnk-aliases";
+import { scopeEnvToAlias } from "./env.ts";
+
+// Two injectable seams, both defaulting to production behavior and never passed
+// by real callers: the module importer (tests exercise the bespoke path without
+// a real package on disk) and the discovery scan (tests inject a fixed map).
+type ImportModule = (specifier: string) => Promise<unknown>;
+const importModule: ImportModule = (specifier) => import(specifier);
+type DiscoverFn = (options?: DiscoverOptions) => Promise<Discovery>;
+
+// The node_modules scan is filesystem work that never changes within a process,
+// so it runs once and the result is memoized. A long-lived daemon pays one scan
+// at first bespoke instantiation; every later run reuses it. The trust gate is
+// boot config, so the env from the first scan stands for the process.
+let discoveredCache: Discovery | null = null;
+const providerPackages = async (discoverFn: DiscoverFn, env: NodeJS.ProcessEnv): Promise<Discovery> => {
+    discoveredCache ??= await discoverFn({ env });
+    return discoveredCache;
+};
+
+// Two-tier resolution (SPEC §5): tier 1 standard table → tier 2 discovered
+// package (scope-agnostic scan, trust-gated) → fail-hard. The standard table is
+// authoritative — a scanned package whose name duplicates a standard one is
+// shadowed here (never reached), since tier 1 returns first.
+export const instantiateProvider = async (
+    name: string,
+    env: NodeJS.ProcessEnv,
+    model: string,
+    importImpl: ImportModule = importModule,
+    discoverFn: DiscoverFn = discover,
+    baseUrl?: string, // per-alias endpoint override (PLURNK_BASEURL_<alias>); threaded to both tiers
+    alias?: string, // the alias this instantiation serves — scopes PLURNK_PROVIDERS_<KNOB>_<alias> overrides
+): Promise<Provider> => {
+    // Per-alias knob scoping: overlay any _<alias>-suffixed knob onto its bare
+    // name so both tiers (and every fromEnv) read plain vars, per-alias-resolved.
+    if (alias !== undefined) env = scopeEnvToAlias(env, alias);
+    if (isStandardProvider(name)) {
+        const standard = await standardProviderFromEnv(name, env, model, baseUrl);
+        if (standard === null) throw new Error(`provider "${name}": standard registry resolution failed`);
+        return standard;
+    }
+    const { registry, skipped } = await providerPackages(discoverFn, env);
+    const specifier = registry.get(name);
+    if (specifier === undefined) {
+        const declined = skipped.get(name);
+        if (declined !== undefined) {
+            throw new Error(`provider "${name}" resolves to ${declined}, but it is untrusted under PLURNK_PLUGINS_TRUSTED_ONLY — add it to the allowlist (or publish under @plurnk/)`);
+        }
+        throw new Error(`unknown provider "${name}": not a standard provider, and no installed package declares plurnk.kind:"provider" with name "${name}"`);
+    }
+    let mod: unknown;
+    try {
+        mod = await importImpl(specifier);
+    } catch (cause) {
+        throw new Error(`provider "${name}" resolves to ${specifier}, but importing it failed`, { cause });
+    }
+    const factory = (mod as { default?: ProviderFactory }).default;
+    if (factory === undefined || typeof factory.fromEnv !== "function") {
+        throw new Error(`${specifier} default export is not a Provider factory (missing static fromEnv)`);
+    }
+    return await factory.fromEnv(env, model, baseUrl !== undefined ? { baseUrl } : undefined);
+};
+
+// Test-only: drop the memoized discovery so a fresh scan/injection runs next.
+export const resetDiscoveryCache = (): void => { discoveredCache = null; };
+
+// Boot convenience: resolve the active alias cascade and instantiate it.
+export const loadActiveProvider = async (
+    env: NodeJS.ProcessEnv = process.env,
+    importImpl: ImportModule = importModule,
+    discoverFn: DiscoverFn = discover,
+): Promise<Provider> => {
+    const alias = resolveActiveAlias(env);
+    if (alias === null) {
+        throw new Error("no active provider: set PLURNK_MODEL to an alias declared via PLURNK_MODEL_<alias>=<provider>/<model>");
+    }
+    return instantiateProvider(alias.provider, env, alias.model, importImpl, discoverFn, alias.baseUrl, alias.alias);
+};

package/src/boundaries.test.ts

@@ -0,0 +1,24 @@
+import test from "node:test";
+import { strict as assert } from "node:assert";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "src");
+const sourceFiles = (): string[] =>
+    readdirSync(root).filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"));
+
+test("provider source does not import the service or database", () => {
+    for (const file of sourceFiles()) {
+        const source = readFileSync(join(root, file), "utf8");
+        assert.ok(!/from\s+["']@plurnk\/plurnk-service/.test(source), `${file} imports the service`);
+        assert.ok(!/from\s+["']node:sqlite/.test(source), `${file} imports node:sqlite`);
+    }
+});
+
+test("provider source does not import the PLURNK parser", () => {
+    for (const file of sourceFiles()) {
+        const source = readFileSync(join(root, file), "utf8");
+        assert.ok(!/from\s+["']@plurnk\/plurnk-grammar/.test(source), `${file} imports the parser`);
+    }
+});