@plurnk/plurnk-providers 1.3.12 → 1.4.0

package/src/Mock.test.ts

@@ -7,7 +7,7 @@ import type { MockResponse } from "./Mock.ts";
 const build = (responses: MockResponse[] = [{ assistant: { content: "hi", reasoning: null } }]) =>
     new Mock({ contextWindow: 100000, responses });
 
-// — Identity (SPEC §10.2, §10.6) —
+// — Identity ({§provider-interface}) —
 
 test("Mock: contextWindow and model are stable across reads", () => {
     const m = build();
@@ -22,21 +22,24 @@ test("Mock: contextWindow passes null through", () => {
     assert.equal(m.contextWindow, null);
 });
 
-// — Tokenomics (SPEC §10.3, §10.4, §10.5) —
+// — Tokenomics ({§provider-interface}) —
 
-test("Mock: countTokens('') is 0; non-empty is a positive integer", () => {
+test("Mock: prompt counting is exact for its declared mock vocabulary", async () => {
     const m = build();
-    assert.equal(m.countTokens(""), 0);
-    const n = m.countTokens("four");
-    assert.ok(Number.isInteger(n) && n > 0);
+    assert.deepEqual(await m.countPromptTokens([]), {
+        kind: "exact", tokens: 0, source: "mock:chars2",
+    });
+    assert.deepEqual(await m.countPromptTokens([{ role: "user", content: "four" }]), {
+        kind: "exact", tokens: 2, source: "mock:chars2",
+    });
 });
 
-test("Mock: calculateCost zero usage is 0 (free)", () => {
+test("Mock: calculateCost returns its deliberate zero estimate", () => {
     const m = build();
-    assert.equal(m.calculateCost({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 0);
+    assert.equal(m.calculateCost({ prompt: 100, completion: 20, reasoning: 10, cached: 5, total: 130 }), 0);
 });
 
-// — Transport (SPEC §10.7, §10.10) —
+// — Transport ({§provider-interface}) —
 
 test("Mock: generate resolves a valid ProviderResponse shape", async () => {
     const m = build([{ assistant: { content: "hello", reasoning: "cot" } }]);
@@ -67,6 +70,18 @@ test("Mock: generate applies caller-supplied overrides", async () => {
     assert.deepEqual(assistantRaw, { wire: true });
 });
 
+test("Mock: a supplied grammar produces unsplit evidence unless the fixture supplies exact evidence", async () => {
+    const explicit = { input: "prefixx", contentStart: 6, transported: false } as const;
+    const m = build([
+        { assistant: { content: "x", reasoning: null } },
+        { assistant: { content: "x", reasoning: null }, grammarEvidence: explicit },
+    ]);
+    const inferred = await m.generate({ messages: [], grammar: 'root ::= "x"' });
+    const supplied = await m.generate({ messages: [], grammar: 'root ::= "prefixx"' });
+    assert.deepEqual(inferred.grammarEvidence, { input: "x", contentStart: 0, transported: true });
+    assert.deepEqual(supplied.grammarEvidence, explicit);
+});
+
 test("Mock: ops escape hatch passes through when provided", async () => {
     const ops = [{ kind: "send" }] as never;
     const m = build([{ assistant: { content: "x", reasoning: null, ops } }]);
@@ -80,7 +95,7 @@ test("Mock: ops absent when not provided", async () => {
     assert.equal("ops" in assistant, false);
 });
 
-// — Abort (SPEC §10.8) —
+// — Abort ({§provider-failure-normalization}) —
 
 test("Mock: generate with a pre-aborted signal rejects and consumes no response", async () => {
     const m = build([{ assistant: { content: "untouched", reasoning: null } }]);
@@ -106,9 +121,9 @@ test("Mock: exhausted queue throws a specific error", async () => {
     await assert.rejects(() => m.generate({ messages: [] }), /exhausted/);
 });
 
-// -- #507: the reserve surface lives on the Provider CONTRACT, and Mock drives core's partition suite --
+// -- {§provider-generation-envelope} --
 
-test("#507 the reserve getters are on the Provider interface (not just the concrete class)", () => {
+test("the reserve getters are on the Provider interface (not just the concrete class)", () => {
     // Typing against the contract catches a getter-only concrete surface.
     const prevR = process.env.PLURNK_PROVIDERS_REASONING_RESERVE;
     try {
@@ -120,7 +135,7 @@ test("#507 the reserve getters are on the Provider interface (not just the concr
     }
 });
 
-test("#507 Mock resolves reserves from PLURNK_PROVIDERS_*_RESERVE against its window (the service partition path)", () => {
+test("Mock resolves reserves from PLURNK_PROVIDERS_*_RESERVE against its window (the service partition path)", () => {
     const prevR = process.env.PLURNK_PROVIDERS_REASONING_RESERVE;
     const prevC = process.env.PLURNK_PROVIDERS_COMPLETION_RESERVE;
     try {
@@ -135,7 +150,7 @@ test("#507 Mock resolves reserves from PLURNK_PROVIDERS_*_RESERVE against its wi
     }
 });
 
-test("#507 no reserve env → null (the #421 no-cap path; the ~100 bare Mocks unaffected)", () => {
+test("no reserve env → null (the no-cap path; bare Mocks unaffected)", () => {
     const m = new Mock({ contextWindow: 49152, responses: [] });
     assert.equal(m.reasoningReserve, null);
     assert.equal(m.completionReserve, null);

package/src/Mock.ts

@@ -5,7 +5,8 @@
 // Provider contract. Production providers don't expose the `ops` escape
 // hatch — that's an intg-only convenience.
 
-import type { ChatMessage, FinishReason, Provider, ProviderAssistant, ProviderUsage } from "./types.ts";
+import type { ChatMessage, FinishReason, GrammarEvidence, PromptTokenMeasurement, Provider, ProviderAssistant, ProviderEncryptedReasoningItem, ProviderResponse, ProviderUsage } from "./types.ts";
+import type { ProviderCost } from "@plurnk/plurnk-contracts";
 import { resolveEnvelopeFromEnv } from "./env.ts";
 
 export type MockAssistant = {
@@ -15,11 +16,10 @@ export type MockAssistant = {
     usage?: Partial<ProviderUsage>;
     finishReason?: FinishReason;
     model?: string;
-    // #482: sealed relay reasoning items (id-keyed, widened per client), so core's
-    // sealed-reasoning conformance test can drive the shape through Mock.
-    reasoningEncrypted?: ReadonlyArray<{ id: string | null; subtype: string; encrypted: ReadonlyArray<{ data: string; format: string | null }> }>;
+    // Provider-normalized encrypted reasoning fixture.
+    reasoningEncrypted?: ReadonlyArray<ProviderEncryptedReasoningItem>;
     // Pre-parsed ops — intg-only escape hatch. Typed `unknown[]` so the
-    // framework carries NO @plurnk/plurnk-grammar dependency; plurnk-service
+    // framework carries no parser dependency; plurnk-service
     // casts these to PlurnkStatement[] on its side. Production providers never
     // include this field.
     ops?: unknown[];
@@ -28,10 +28,12 @@ export type MockAssistant = {
 export type MockResponse = {
     assistant: MockAssistant;
     assistantRaw?: unknown;
+    grammarEvidence?: GrammarEvidence;
 };
 
 // Returned shape: ProviderAssistant + pre-parsed ops visible for tests.
 export type MockReturnedAssistant = ProviderAssistant & { ops?: unknown[] };
+export type MockReturnedResponse = ProviderResponse & { assistant: MockReturnedAssistant };
 
 const DEFAULT_USAGE: ProviderUsage = { prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 };
 
@@ -41,8 +43,9 @@ export default class Mock implements Provider {
     #completionReserve: number | null;
     #queue: MockResponse[];
 
-    // #507: reserves resolve the SAME way a real provider's do — the TOLERANT env
-    // read (the service's partition/budget suite sets PLURNK_PROVIDERS_*_RESERVE
+    // {§provider-generation-envelope} Reserves resolve the same way a real
+    // provider's do — the tolerant env read (the service's partition/budget
+    // suite sets PLURNK_PROVIDERS_*_RESERVE
     // and Mock reflects it, resolved against contextWindow). Tolerant, NOT the
     // fail-hard envelopeFromEnv: Mock is the universal fixture, constructed
     // without the reserves in most base tests, so absent env → null → the
@@ -61,18 +64,25 @@ export default class Mock implements Provider {
     get completionReserve(): number | null { return this.#completionReserve; }
     get model(): string { return "mock"; }
 
-    // Heuristic tokenizer (chars/2 upper bound, matching the framework's
-    // fallback). Mock is test-only; real provider siblings ship exact counts.
-    countTokens(text: string): number {
-        return text.length === 0 ? 0 : Math.ceil(text.length / 2);
+    // Mock's deliberately simple vocabulary defines each two content code units
+    // as one token and has no hidden request framing. This is exact for the mock,
+    // unlike a production adapter applying the same arithmetic to an unknown model.
+    async countPromptTokens(messages: readonly ChatMessage[]): Promise<PromptTokenMeasurement> {
+        return {
+            kind: "exact",
+            tokens: messages.reduce((sum, { content }) => sum + Math.ceil(content.length / 2), 0),
+            source: "mock:chars2",
+        };
     }
 
     // Mock is free.
     calculateCost(_usage: ProviderUsage): number { return 0; }
+    calculateCharge(_usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }> { return { kind: "free", source: "mock provider" }; }
 
-    async generate({ signal }: { messages: ChatMessage[]; workerId?: string; signal?: AbortSignal }): Promise<{ assistant: MockReturnedAssistant; assistantRaw: unknown }> {
+    async generate({ signal, grammar }: { messages: ChatMessage[]; workerId?: string; signal?: AbortSignal; grammar?: string }): Promise<MockReturnedResponse> {
         // Honor abort before consuming the queue — an aborted call makes no
-        // "wire call" and must not exhaust a queued response (SPEC §10.8).
+        // "wire call" and must not exhaust a queued response
+        // ({§provider-failure-normalization}).
         signal?.throwIfAborted();
         const next = this.#queue.shift();
         if (next === undefined) throw new Error("Mock provider exhausted: no more queued responses");
@@ -81,12 +91,20 @@ export default class Mock implements Provider {
             content: a.content,
             reasoning: a.reasoning,
             usage: { ...DEFAULT_USAGE, ...a.usage },
-            ...(a.reasoningEncrypted !== undefined ? { reasoningEncrypted: a.reasoningEncrypted } : {}), // #482 — sealed blobs ride the contract through Mock too
+            ...(a.reasoningEncrypted !== undefined ? { reasoningEncrypted: a.reasoningEncrypted } : {}),
             finishReason: a.finishReason ?? "stop",
             model: a.model ?? "mock",
             ...(a.ops !== undefined ? { ops: a.ops } : {}),
         };
-        return { assistant, assistantRaw: next.assistantRaw ?? null };
+        const grammarEvidence = next.grammarEvidence
+            ?? (grammar === undefined
+                ? undefined
+                : { input: assistant.content, contentStart: 0, transported: true });
+        return {
+            assistant,
+            assistantRaw: next.assistantRaw ?? null,
+            ...(grammarEvidence !== undefined ? { grammarEvidence } : {}),
+        };
     }
 
     get remaining(): number { return this.#queue.length; }

package/src/Pool.test.ts

@@ -1,8 +1,8 @@
 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 { ProviderError } from "./errors.ts";
+import type { PromptTokenMeasurement, Provider, ProviderResponse } from "./types.ts";
 import { resetEmittedWarnings } from "./warnings.ts";
 
 test.afterEach(() => { resetEmittedWarnings(); });
@@ -14,6 +14,7 @@ type FakeOpts = {
     constrainsOutput?: boolean; requiresMaxTokens?: boolean;
     reasoningReserve?: number | null; completionReserve?: number | null;
     tokenize?: boolean; cost?: number; throws?: Error;
+    promptMeasurement?: PromptTokenMeasurement;
 };
 // A fake backend that records which workers it served, and optionally throws.
 const backend = (opts: FakeOpts = {}) => {
@@ -27,7 +28,11 @@ const backend = (opts: FakeOpts = {}) => {
         ...(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,
+        countPromptTokens: async (messages) => opts.promptMeasurement ?? ({
+            kind: "exact",
+            tokens: messages.reduce((sum, { content }) => sum + content.length, 0),
+            source: "test:exact",
+        }),
         calculateCost: () => opts.cost ?? 0,
         generate: async (args: Parameters<Provider["generate"]>[0]): Promise<ProviderResponse> => {
             served.push(args.workerId);
@@ -39,6 +44,7 @@ const backend = (opts: FakeOpts = {}) => {
 };
 const netErr = () => new ProviderError("provider:x", "network_failure", "down", { status: 503 });
 const authErr = () => new ProviderError("provider:x", "unauthorized", "no key", { status: 401 });
+const interruptedErr = () => new ProviderError("provider:x", "resource_interrupted", "generation interrupted");
 const gen = (p: Pool, workerId: string, extra: Record<string, unknown> = {}) =>
     p.generate({ messages: [], workerId, ...extra } as Parameters<Provider["generate"]>[0]);
 
@@ -58,7 +64,7 @@ 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)", () => {
+test("Pool: any unknown (null) window makes the pool null - no improvised cap", () => {
     assert.equal(new Pool([backend({ window: 48000 }).b, backend({ window: null }).b]).contextWindow, null);
 });
 
@@ -88,12 +94,32 @@ test("Pool: tokenize is exposed iff every backend has it", () => {
     assert.equal(new Pool([backend({ tokenize: true }).b, backend({ tokenize: false }).b]).tokenize, undefined);
 });
 
-test("Pool: countTokens + calculateCost delegate to a backend", () => {
+test("Pool: prompt counting + calculateCost delegate to a backend", async () => {
     const p = new Pool([backend({ cost: 42 }).b]);
-    assert.equal(p.countTokens("abcd"), 4);
+    assert.deepEqual(await p.countPromptTokens([{ role: "user", content: "abcd" }]), {
+        kind: "exact", tokens: 4, source: "pool:test:exact",
+    });
     assert.equal(p.calculateCost({ prompt: 0, completion: 0, reasoning: 0, cached: 0, total: 0 }), 42);
 });
 
+test("Pool: prompt evidence is conservative across every routable backend", async () => {
+    const exact = backend({ promptMeasurement: { kind: "exact", tokens: 8, source: "test:a" } }).b;
+    const larger = backend({ promptMeasurement: { kind: "exact", tokens: 11, source: "test:b" } }).b;
+    assert.deepEqual(await new Pool([exact, larger]).countPromptTokens([]), {
+        kind: "upper_bound", tokens: 11, source: "pool:test:a,test:b",
+    });
+
+    const estimate = backend({ promptMeasurement: {
+        kind: "estimate", tokens: 3, source: "heuristic:chars2", detail: "unknown framing",
+    } }).b;
+    assert.deepEqual(await new Pool([exact, estimate]).countPromptTokens([]), {
+        kind: "estimate",
+        tokens: 8,
+        source: "pool:test:a,heuristic:chars2",
+        detail: "at least one interchangeable backend has only an estimate: unknown framing",
+    });
+});
+
 // --- dispatch: round-robin + affinity ---
 
 test("Pool: NEW workers round-robin across backends", async () => {
@@ -134,6 +160,17 @@ test("Pool: a terminal (auth) failure does NOT overflow", async () => {
     assert.deepEqual(other.served, []);     // never tried - auth fails the same on a peer
 });
 
+test("#161: Pool does not overflow a resource-interrupted attempt and discard its evidence", async () => {
+    const interrupted = backend({ throws: interruptedErr() }), other = backend();
+    const pool = new Pool([interrupted.b, other.b]);
+    await assert.rejects(
+        () => gen(pool, "w1"),
+        (error: unknown) => error instanceof ProviderError && error.kind === "resource_interrupted",
+    );
+    assert.deepEqual(interrupted.served, ["w1"]);
+    assert.deepEqual(other.served, []);
+});
+
 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]);

package/src/Pool.ts

@@ -1,13 +1,20 @@
-import type { Provider, ProviderResponse, ProviderUsage, ChatMessage } from "./types.ts";
-import { ProviderError, type ProviderTelemetryKind } from "./telemetry.ts";
+import type { Provider, ProviderResponse, ProviderUsage, ChatMessage, PromptTokenMeasurement } from "./types.ts";
+import type { ProviderCost } from "@plurnk/plurnk-contracts";
+import { resolveProviderCost } from "./cost.ts";
+import { ProviderError, type ProviderErrorKind } from "./errors.ts";
 import { emitWarningOnce } from "./warnings.ts";
+import { assertPromptTokenMeasurement } from "./promptTokens.ts";
+import Meta, {
+    type PluginAttribution,
+    type PluginAttributionContext,
+} from "@plurnk/plurnk-meta";
 
 // A backend-AVAILABILITY failure: the sub-provider already exhausted its OWN
-// transient retries (#18) before throwing one of these, so re-hitting the same
+// transient retries 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"]);
+const OVERFLOW_KINDS: ReadonlySet<ProviderErrorKind> = 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
@@ -15,11 +22,12 @@ const OVERFLOW_KINDS: ReadonlySet<ProviderTelemetryKind> = new Set(["network_fai
 // 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).
+// honest Provider surface instead of pretending N models are one
+// ({§provider-capacity-pool}).
 //
 // 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
+// backends shreds the prefix cache. It is the same 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 {
@@ -29,9 +37,10 @@ export default class Pool implements Provider {
     #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
+    // Optional exact tokenizer: present iff every backend exposes one (same
     // vocab, since interchangeable). Delegated; absent when the fleet can't.
     readonly tokenize?: (text: string) => Promise<number[]>;
+    readonly attributions?: (context: PluginAttributionContext) => PluginAttribution;
 
     constructor(backends: readonly Provider[]) {
         if (backends.length === 0) throw new Error("Pool: at least one backend is required");
@@ -40,14 +49,15 @@ export default class Pool implements Provider {
         // 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)`);
+        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`);
         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).
+        // might route to it, and the consumer must not improvise a cap
+        // ({§model-fact-resolution}).
         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) {
@@ -59,6 +69,11 @@ export default class Pool implements Provider {
 
         // 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);
+        if (backends.some((backend) => typeof backend.attributions === "function")) {
+            this.attributions = (context) => Meta.composeAttributions(
+                ...backends.map((backend) => backend.attributions?.(context) ?? []),
+            );
+        }
     }
 
     // --- Provider surface: interchangeable backends collapse to one honest face ---
@@ -82,8 +97,39 @@ export default class Pool implements Provider {
         return this.#backends.some((b) => b.requiresMaxTokens === true) ? true : undefined;
     }
 
-    countTokens(text: string): number { return this.#backends[0].countTokens(text); }
+    async countPromptTokens(
+        messages: readonly ChatMessage[],
+        signal?: AbortSignal,
+    ): Promise<PromptTokenMeasurement> {
+        const measurements = await Promise.all(this.#backends.map(async (backend) =>
+            assertPromptTokenMeasurement(
+                await backend.countPromptTokens(messages, signal),
+                `Pool backend ${backend.model}`,
+            )));
+        const tokens = Math.max(...measurements.map((measurement) => measurement.tokens));
+        const sources = [...new Set(measurements.map(({ source }) => source))].join(",");
+        const estimate = measurements.find((measurement) => measurement.kind === "estimate");
+        if (estimate?.kind === "estimate") {
+            return {
+                kind: "estimate",
+                tokens,
+                source: `pool:${sources}`,
+                detail: `at least one interchangeable backend has only an estimate: ${estimate.detail}`,
+            };
+        }
+        const exact = measurements.every((measurement) => measurement.kind === "exact")
+            && measurements.every((measurement) => measurement.tokens === tokens);
+        return {
+            kind: exact ? "exact" : "upper_bound",
+            tokens,
+            source: `pool:${sources}`,
+        };
+    }
     calculateCost(usage: ProviderUsage): number { return this.#backends[0].calculateCost(usage); }
+    calculateCharge(usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }> {
+        const backend = this.#backends[0];
+        return resolveProviderCost(undefined, backend.calculateCharge?.(usage), () => backend.calculateCost(usage)) as Exclude<ProviderCost, { kind: "authoritative" }>;
+    }
 
     // --- dispatch ---