agent-nuvira 3.5.2 → 3.5.6

package/dist/learning/model-pricing.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Model pricing — the ONE price source of truth for what a call cost.
+ *
+ * THE DEFECT THIS REPLACES (measured on a real profile, 2026-10-15: a ledger of
+ * 9,405 calls reporting `Total Spent $7.21`). There were TWO price tables and
+ * neither knew what the account was actually billed:
+ *
+ *   1. `cost-tracker.ts` held a hardcoded five-entry `DEFAULT_PRICING` (groq,
+ *      nim, gemini, openrouter, local) with a `$0.00010/1K` fallback for every
+ *      OTHER provider, plus a three-entry `expensiveModels` hack. The ledger
+ *      priced from it and the dashboard printed the sum as **"Total Spent"**.
+ *   2. `provider-catalog.ts` held the real per-provider list prices (with 21
+ *      providers, not 5) and the ROUTER scored cost from THAT.
+ *
+ * The two disagreed in both directions, and every disagreement was invisible:
+ *
+ *   - `deepseek` was absent from the ledger table → priced at the generic
+ *     `$0.00010/1K` while the catalog declared `$0.00027/$0.00110`. The one
+ *     provider the user actually pays for was the one most mis-priced (≈$5.94
+ *     recorded where the catalog's own numbers give ≈$17.36).
+ *   - `omniroute` was absent too → invented $0.3995 of spend on a localhost
+ *     gateway the catalog itself declares `{0, 0}`.
+ *   - `openrouter` was 25×/100× lower in the ledger than in the catalog.
+ *   - a 7B toy (`allam-2-7b`) and a prompt-guard classifier were billed at the
+ *     provider's Llama-3.3-70B-class rate, because price was per PROVIDER.
+ *   - and "my Groq is a free tier" had nowhere to live, so free usage was
+ *     charged a stranger's list rate (the billing fact belongs to the KEY —
+ *     this is the same doctrine `inference/model-entitlement.ts` states: the
+ *     module may LABEL, never bill).
+ *
+ * ─── DOCTRINE (read before changing the order below) ────────────────────────
+ *
+ * 1. **Two numbers, never conflated.** `billedUsd` is money we have EVIDENCE
+ *    was charged. `listUsd` is what the same tokens would cost at the resolved
+ *    LIST price — the VALUE of a free call, never a charge. A single number
+ *    cannot express both, and calling the second "spend" is the whole bug.
+ * 2. **Evidence outranks inference, in this order.** Provider-reported cost for
+ *    THIS call > the account's own declared billing tier (a key fact) > a price
+ *    we can name a source for (config override, declared model price, catalog).
+ *    Nothing here guesses.
+ * 3. **No generic fallback. Ever.** An unknown provider has NO price: it is
+ *    `unpriced`, which is a first-class answer. The old `$0.00010/1K` default is
+ *    exactly how $0.40 of spend appeared on a free local gateway. (Unknown is
+ *    not zero either — that is the mirror-image lie, and `gemini`'s declared
+ *    `0/0` is why a zero price is deliberately NOT read as "free".)
+ * 4. **A zero catalog price is not free, and a keyless gateway is not free.**
+ *    A keyed provider with no listed price is `unpriced` (Gemini's paid models
+ *    403 without billing). A keyless pass-through gateway (`omniroute`,
+ *    `nuvira` sidecar) bills whatever its UPSTREAM charged, which this machine
+ *    cannot see — so it is `passthrough`: zero we can attribute, and explicitly
+ *    NOT claimed as either spend or saving.
+ * 5. **Per-model before per-provider, and say which one you used.**
+ *    `pricingBasis` names the evidence ("config override", "declared model
+ *    price", "catalog deepseek", "groq provider-level default (Llama-3.3-70B
+ *    class) — no per-model price for this id"). "Provider-level default" is
+ *    marked as such because that is precisely the number that used to bill a
+ *    7B toy at 70B rates.
+ * 6. **The router still gets a number.** `estimatedListCostUsd()` is the
+ *    scoring primitive (`calculateCost` keeps its signature for that reason); it
+ *    answers "what should this cost on the open market", which is the right
+ *    question for ranking and the WRONG question for accounting. Accounting uses
+ *    `resolveCallCost()`.
+ */
+/**
+ * What the user's ACCOUNT (key) is billed by this provider — the fact the
+ * ledger had no way to express. Declared per provider in config
+ * (`providers.<id>.billingTier`), because it is a property of the key, not of
+ * the model.
+ *
+ *   paid          — calls bill at list price. List-priced calls count as billed
+ *                   (still an estimate; only a provider-reported figure is exact).
+ *   free          — a free tier / free credits are absorbing the cost. Calls are
+ *                   $0 billed BY EVIDENCE, and their list price is reported as
+ *                   value (what the free tier saved).
+ *   subscription  — a flat-rate plan covers the calls. Same accounting as `free`
+ *                   (nothing is charged per call), different reason in the basis.
+ *   unknown       — nothing declared. NOT an assumption of paid: list-priced
+ *                   calls land in a separate `unverified` bucket that is never
+ *                   presented as spend, and the surfaces say how to declare it.
+ */
+export type BillingTier = 'paid' | 'free' | 'subscription' | 'unknown';
+export declare const BILLING_TIERS: readonly BillingTier[];
+/** True when the tier means "nothing is charged per call". */
+export declare function tierIsUnbilled(tier: BillingTier): boolean;
+/** Narrow an arbitrary config value to a tier. Anything unrecognised is `unknown`. */
+export declare function asBillingTier(value: unknown): BillingTier;
+/**
+ * The provenance of a call's cost. Six values, because they need different
+ * handling and a boolean would flatten them:
+ *
+ *   reported     the provider/gateway stated this call's exact charge.
+ *   catalog      list-priced from a named source (config override, declared
+ *                model price, or the provider catalog).
+ *   free         provably $0 per call: a local runtime, a provider-declared
+ *                `:free` id, or an account declared free/subscription.
+ *   passthrough  a keyless gateway to somewhere else — its upstream bill is not
+ *                visible here (see doctrine 4).
+ *   unknown      no price evidence at all — unpriced, never zero, never guessed.
+ */
+export type CostSource = 'reported' | 'catalog' | 'free' | 'passthrough' | 'unknown';
+/**
+ * Which accounting bucket an entry belongs to. Derived, so every surface
+ * (CLI, dashboard, reconciliation) buckets a call the same way.
+ *
+ *   billed-reported    exact, provider-stated money.
+ *   billed-listed      list-priced and the account is declared `paid` — a
+ *                      best estimate of money owed, labelled as an estimate.
+ *   unverified-listed  list-priced, account tier undeclared: shown, never as spend.
+ *   not-billed-value   free/subscription: $0 billed, list price is the value saved.
+ *   unpriced           unknown price, or a pass-through gateway: no dollars at all.
+ */
+export type CostBucket = 'billed-reported' | 'billed-listed' | 'unverified-listed' | 'not-billed-value' | 'unpriced';
+/** The bucket for one classified call. Pure. */
+export declare function bucketFor(source: CostSource, tier: BillingTier): CostBucket;
+/** A price we can name a source for. USD per 1K tokens. */
+export interface PriceQuote {
+    inputPer1K: number;
+    outputPer1K: number;
+    /** The evidence, one line — printed beside the number, never omitted. */
+    basis: string;
+}
+/**
+ * DECLARED per-model list prices, keyed `provider/model` OR a bare model id.
+ *
+ * These are the models whose real price differs materially from their
+ * provider's declared default — the entries that used to live as an ad-hoc
+ * `expensiveModels` map inside `cost-tracker.ts` (kept, so no accounting
+ * behaviour regresses silently, but now first-class and self-describing: each
+ * carries the id it applies to AND a basis string the surfaces print).
+ *
+ * A key with a `/` is matched against `${provider}/${model}` first, so the same
+ * model id can price differently on two providers. Nothing is inferred from a
+ * model's NAME here — a price is a fact about an offering, not a word.
+ */
+export declare const DECLARED_MODEL_PRICES: Record<string, PriceQuote>;
+/** True when a provider×model is provably $0 per call at the MODEL level. */
+export declare function isModelLevelFree(provider: string, model: string): boolean;
+/**
+ * A keyless provider that is NOT a local runtime: a gateway whose cost depends
+ * on whatever it forwards to. Its own price table says 0, and that zero means
+ * "not priced here", not "free here" (doctrine 4).
+ */
+export declare function isPassthroughGateway(provider: string): boolean;
+/**
+ * Resolve the LIST price for a call, or `undefined` when this machine has no
+ * price for the pair. Precedence, highest first:
+ *
+ *   1. the caller's config override (`pricing.<provider>` — the user's own number),
+ *   2. a declared per-model price (`DECLARED_MODEL_PRICES`),
+ *   3. the caller's per-model catalogue row (the live feed, when a host wires it),
+ *   4. the provider catalog's default, MARKED as provider-level.
+ *
+ * Step 4 is deliberately last and deliberately labelled: applying a provider
+ * average to every model is exactly how a 7B toy was billed at 70B rates.
+ */
+export declare function resolveListPrice(provider: string, model: string, opts?: {
+    configPricing?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+    };
+    /** A per-model price from a live catalogue (e.g. OpenRouter's own rows). */
+    catalogRow?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+        basis?: string;
+    };
+}): PriceQuote | undefined;
+/** The classified cost of ONE call. */
+export interface ResolvedCallCost {
+    /** Money we have evidence was charged, USD. 0 for free/unpriced/passthrough. */
+    billedUsd: number;
+    /** List-price value of the same tokens, when a price exists. Never "spend". */
+    listUsd?: number;
+    costSource: CostSource;
+    bucket: CostBucket;
+    billingTier: BillingTier;
+    /** One line naming the evidence behind both numbers. */
+    basis: string;
+    /** The resolved prices, when there is a quote (for display/aggregation). */
+    quote?: PriceQuote;
+}
+/**
+ * Classify one call's cost from the best available evidence.
+ *
+ * Total, never throws. `billedUsd` is 0 whenever we do not have evidence of a
+ * charge — which is the honest default, and the reason the headline can no
+ * longer be inflated by a provider average (doctrine 1, 3).
+ */
+export declare function resolveCallCost(input: {
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** The provider's exact figure for this call, when it gave one. */
+    reportedCostUsd?: number;
+    /** The account's declared billing tier for this provider. */
+    billingTier?: BillingTier;
+    configPricing?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+    };
+    catalogRow?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+        basis?: string;
+    };
+}): ResolvedCallCost;
+/**
+ * The LIST-priced estimate, for callers that need a number to RANK with
+ * (`auto-router`'s cost score, the fallback ladder, hybrid cost estimates).
+ *
+ * Deliberately returns the market price rather than the billed figure: ranking
+ * wants "what would this cost on the open market", while accounting wants "what
+ * did it cost ME". Conflating them is how the dashboard came to print an
+ * estimate under the word "spent".
+ */
+export declare function estimatedListCostUsd(provider: string, model: string, inputTokens: number, outputTokens: number, opts?: {
+    configPricing?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+    };
+    catalogRow?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+        basis?: string;
+    };
+}): number;
+/** Convenience for display surfaces: the price quote alone, or undefined. */
+export declare function priceQuoteFor(provider: string, model: string, opts?: {
+    configPricing?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+    };
+    catalogRow?: {
+        inputPer1K?: number;
+        outputPer1K?: number;
+        basis?: string;
+    };
+}): PriceQuote | undefined;
+//# sourceMappingURL=model-pricing.d.ts.map

package/dist/learning/model-pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-pricing.d.ts","sourceRoot":"","sources":["../../src/learning/model-pricing.ts"],"names":[],"mappings":"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"}

package/dist/learning/model-pricing.js

@@ -0,0 +1,309 @@
+/**
+ * Model pricing — the ONE price source of truth for what a call cost.
+ *
+ * THE DEFECT THIS REPLACES (measured on a real profile, 2026-10-15: a ledger of
+ * 9,405 calls reporting `Total Spent $7.21`). There were TWO price tables and
+ * neither knew what the account was actually billed:
+ *
+ *   1. `cost-tracker.ts` held a hardcoded five-entry `DEFAULT_PRICING` (groq,
+ *      nim, gemini, openrouter, local) with a `$0.00010/1K` fallback for every
+ *      OTHER provider, plus a three-entry `expensiveModels` hack. The ledger
+ *      priced from it and the dashboard printed the sum as **"Total Spent"**.
+ *   2. `provider-catalog.ts` held the real per-provider list prices (with 21
+ *      providers, not 5) and the ROUTER scored cost from THAT.
+ *
+ * The two disagreed in both directions, and every disagreement was invisible:
+ *
+ *   - `deepseek` was absent from the ledger table → priced at the generic
+ *     `$0.00010/1K` while the catalog declared `$0.00027/$0.00110`. The one
+ *     provider the user actually pays for was the one most mis-priced (≈$5.94
+ *     recorded where the catalog's own numbers give ≈$17.36).
+ *   - `omniroute` was absent too → invented $0.3995 of spend on a localhost
+ *     gateway the catalog itself declares `{0, 0}`.
+ *   - `openrouter` was 25×/100× lower in the ledger than in the catalog.
+ *   - a 7B toy (`allam-2-7b`) and a prompt-guard classifier were billed at the
+ *     provider's Llama-3.3-70B-class rate, because price was per PROVIDER.
+ *   - and "my Groq is a free tier" had nowhere to live, so free usage was
+ *     charged a stranger's list rate (the billing fact belongs to the KEY —
+ *     this is the same doctrine `inference/model-entitlement.ts` states: the
+ *     module may LABEL, never bill).
+ *
+ * ─── DOCTRINE (read before changing the order below) ────────────────────────
+ *
+ * 1. **Two numbers, never conflated.** `billedUsd` is money we have EVIDENCE
+ *    was charged. `listUsd` is what the same tokens would cost at the resolved
+ *    LIST price — the VALUE of a free call, never a charge. A single number
+ *    cannot express both, and calling the second "spend" is the whole bug.
+ * 2. **Evidence outranks inference, in this order.** Provider-reported cost for
+ *    THIS call > the account's own declared billing tier (a key fact) > a price
+ *    we can name a source for (config override, declared model price, catalog).
+ *    Nothing here guesses.
+ * 3. **No generic fallback. Ever.** An unknown provider has NO price: it is
+ *    `unpriced`, which is a first-class answer. The old `$0.00010/1K` default is
+ *    exactly how $0.40 of spend appeared on a free local gateway. (Unknown is
+ *    not zero either — that is the mirror-image lie, and `gemini`'s declared
+ *    `0/0` is why a zero price is deliberately NOT read as "free".)
+ * 4. **A zero catalog price is not free, and a keyless gateway is not free.**
+ *    A keyed provider with no listed price is `unpriced` (Gemini's paid models
+ *    403 without billing). A keyless pass-through gateway (`omniroute`,
+ *    `nuvira` sidecar) bills whatever its UPSTREAM charged, which this machine
+ *    cannot see — so it is `passthrough`: zero we can attribute, and explicitly
+ *    NOT claimed as either spend or saving.
+ * 5. **Per-model before per-provider, and say which one you used.**
+ *    `pricingBasis` names the evidence ("config override", "declared model
+ *    price", "catalog deepseek", "groq provider-level default (Llama-3.3-70B
+ *    class) — no per-model price for this id"). "Provider-level default" is
+ *    marked as such because that is precisely the number that used to bill a
+ *    7B toy at 70B rates.
+ * 6. **The router still gets a number.** `estimatedListCostUsd()` is the
+ *    scoring primitive (`calculateCost` keeps its signature for that reason); it
+ *    answers "what should this cost on the open market", which is the right
+ *    question for ranking and the WRONG question for accounting. Accounting uses
+ *    `resolveCallCost()`.
+ */
+import { catalogPricing, isCatalogKeyless, getCatalogProvider } from '../inference/provider-catalog.js';
+import { LOCAL_RUNTIME_IDS } from '../inference/model-entitlement.js';
+export const BILLING_TIERS = ['paid', 'free', 'subscription', 'unknown'];
+/** True when the tier means "nothing is charged per call". */
+export function tierIsUnbilled(tier) {
+    return tier === 'free' || tier === 'subscription';
+}
+/** Narrow an arbitrary config value to a tier. Anything unrecognised is `unknown`. */
+export function asBillingTier(value) {
+    return typeof value === 'string' && BILLING_TIERS.includes(value)
+        ? value
+        : 'unknown';
+}
+/** The bucket for one classified call. Pure. */
+export function bucketFor(source, tier) {
+    switch (source) {
+        case 'reported':
+            return 'billed-reported';
+        case 'free':
+            return 'not-billed-value';
+        case 'passthrough':
+        case 'unknown':
+            return 'unpriced';
+        case 'catalog':
+            return tier === 'paid' ? 'billed-listed' : 'unverified-listed';
+    }
+}
+// ─── Model-level facts ──────────────────────────────────────────────────────
+const PROVIDER_FREE_SUFFIX = ':free';
+/**
+ * DECLARED per-model list prices, keyed `provider/model` OR a bare model id.
+ *
+ * These are the models whose real price differs materially from their
+ * provider's declared default — the entries that used to live as an ad-hoc
+ * `expensiveModels` map inside `cost-tracker.ts` (kept, so no accounting
+ * behaviour regresses silently, but now first-class and self-describing: each
+ * carries the id it applies to AND a basis string the surfaces print).
+ *
+ * A key with a `/` is matched against `${provider}/${model}` first, so the same
+ * model id can price differently on two providers. Nothing is inferred from a
+ * model's NAME here — a price is a fact about an offering, not a word.
+ */
+export const DECLARED_MODEL_PRICES = {
+    'openai/gpt-oss-120b': {
+        inputPer1K: 0.00015,
+        outputPer1K: 0.0006,
+        basis: 'declared model price (gpt-oss-120b)',
+    },
+    'openai/gpt-oss-20b': {
+        inputPer1K: 0.000075,
+        outputPer1K: 0.0003,
+        basis: 'declared model price (gpt-oss-20b)',
+    },
+    'qwen/qwen3.6-27b': {
+        inputPer1K: 0.0006,
+        outputPer1K: 0.003,
+        basis: 'declared model price (qwen3.6-27b)',
+    },
+};
+/** True when a provider×model is provably $0 per call at the MODEL level. */
+export function isModelLevelFree(provider, model) {
+    const id = (model ?? '').trim();
+    if (id.endsWith(PROVIDER_FREE_SUFFIX))
+        return true;
+    return LOCAL_RUNTIME_IDS.includes(provider);
+}
+/**
+ * A keyless provider that is NOT a local runtime: a gateway whose cost depends
+ * on whatever it forwards to. Its own price table says 0, and that zero means
+ * "not priced here", not "free here" (doctrine 4).
+ */
+export function isPassthroughGateway(provider) {
+    if (LOCAL_RUNTIME_IDS.includes(provider))
+        return false;
+    return isCatalogKeyless(provider);
+}
+/**
+ * Resolve the LIST price for a call, or `undefined` when this machine has no
+ * price for the pair. Precedence, highest first:
+ *
+ *   1. the caller's config override (`pricing.<provider>` — the user's own number),
+ *   2. a declared per-model price (`DECLARED_MODEL_PRICES`),
+ *   3. the caller's per-model catalogue row (the live feed, when a host wires it),
+ *   4. the provider catalog's default, MARKED as provider-level.
+ *
+ * Step 4 is deliberately last and deliberately labelled: applying a provider
+ * average to every model is exactly how a 7B toy was billed at 70B rates.
+ */
+export function resolveListPrice(provider, model, opts = {}) {
+    const usable = (q) => !!q &&
+        typeof q.inputPer1K === 'number' &&
+        typeof q.outputPer1K === 'number' &&
+        Number.isFinite(q.inputPer1K) &&
+        Number.isFinite(q.outputPer1K) &&
+        q.inputPer1K >= 0 &&
+        q.outputPer1K >= 0;
+    // 1. The user's own declared price for this provider wins over every builtin.
+    if (usable(opts.configPricing)) {
+        return {
+            inputPer1K: opts.configPricing.inputPer1K,
+            outputPer1K: opts.configPricing.outputPer1K,
+            basis: `your config override (pricing.${provider})`,
+        };
+    }
+    // 2. A declared per-model price, matched `provider/model` then bare id.
+    const declared = DECLARED_MODEL_PRICES[`${provider}/${model}`] ?? DECLARED_MODEL_PRICES[model];
+    if (declared)
+        return { ...declared };
+    // 3. A live catalogue row for this exact model, when the host supplied one.
+    if (usable(opts.catalogRow)) {
+        return {
+            inputPer1K: opts.catalogRow.inputPer1K,
+            outputPer1K: opts.catalogRow.outputPer1K,
+            basis: opts.catalogRow.basis ?? `catalogue price for ${model}`,
+        };
+    }
+    // 4. The provider catalog's default — only when it is a real (>0) price.
+    const entry = getCatalogProvider(provider);
+    const catalog = catalogPricing(provider);
+    if (catalog && (catalog.inputPer1K > 0 || catalog.outputPer1K > 0)) {
+        return {
+            inputPer1K: catalog.inputPer1K,
+            outputPer1K: catalog.outputPer1K,
+            basis: `${provider} provider-level default (${entry?.defaultModel ?? 'unknown default'} class) — no per-model price for this id`,
+        };
+    }
+    // A keyed provider with no positive price has NO price we can name (doctrine 4).
+    return undefined;
+}
+function round6(usd) {
+    return Math.round(usd * 100000) / 100000;
+}
+function costOf(quote, inputTokens, outputTokens) {
+    return (inputTokens / 1000) * quote.inputPer1K + (outputTokens / 1000) * quote.outputPer1K;
+}
+/**
+ * Classify one call's cost from the best available evidence.
+ *
+ * Total, never throws. `billedUsd` is 0 whenever we do not have evidence of a
+ * charge — which is the honest default, and the reason the headline can no
+ * longer be inflated by a provider average (doctrine 1, 3).
+ */
+export function resolveCallCost(input) {
+    const tier = input.billingTier ?? 'unknown';
+    const quote = resolveListPrice(input.provider, input.model, {
+        configPricing: input.configPricing,
+        catalogRow: input.catalogRow,
+    });
+    const listUsd = quote ? round6(costOf(quote, input.inputTokens, input.outputTokens)) : undefined;
+    // 1. The provider's own accounting is exact, and it is exact about ZERO too.
+    if (typeof input.reportedCostUsd === 'number' && Number.isFinite(input.reportedCostUsd)) {
+        return {
+            billedUsd: round6(Math.max(0, input.reportedCostUsd)),
+            ...(listUsd !== undefined ? { listUsd } : {}),
+            costSource: 'reported',
+            bucket: 'billed-reported',
+            billingTier: tier,
+            basis: 'provider-reported cost for this call (exact)',
+            ...(quote ? { quote } : {}),
+        };
+    }
+    // 2. Provably nothing per call — a local runtime, a provider-declared free id,
+    //    or an account the user has declared free/subscription. The list price
+    //    becomes VALUE (what the tier saved), never spend.
+    if (isModelLevelFree(input.provider, input.model)) {
+        return {
+            billedUsd: 0,
+            ...(listUsd !== undefined ? { listUsd } : {}),
+            costSource: 'free',
+            bucket: 'not-billed-value',
+            billingTier: tier,
+            basis: LOCAL_RUNTIME_IDS.includes(input.provider)
+                ? 'runs on this machine — no per-call charge'
+                : `provider declares this id free ("${PROVIDER_FREE_SUFFIX}")`,
+            ...(quote ? { quote } : {}),
+        };
+    }
+    if (tierIsUnbilled(tier)) {
+        return {
+            billedUsd: 0,
+            ...(listUsd !== undefined ? { listUsd } : {}),
+            costSource: 'free',
+            bucket: 'not-billed-value',
+            billingTier: tier,
+            basis: tier === 'subscription'
+                ? 'your account is on a flat-rate plan — nothing is charged per call'
+                : 'your account is declared a free tier — nothing is charged per call',
+            ...(quote ? { quote } : {}),
+        };
+    }
+    // 3. A pass-through gateway: the upstream bill is not visible from here.
+    if (isPassthroughGateway(input.provider)) {
+        return {
+            billedUsd: 0,
+            costSource: 'passthrough',
+            bucket: 'unpriced',
+            billingTier: tier,
+            basis: `${input.provider} is a keyless pass-through gateway — its upstream charge is not visible here`,
+        };
+    }
+    // 4. No price we can name: UNPRICED. Not zero, not an invented rate.
+    if (!quote || listUsd === undefined) {
+        return {
+            billedUsd: 0,
+            costSource: 'unknown',
+            bucket: 'unpriced',
+            billingTier: tier,
+            basis: `no price evidence for ${input.provider}/${input.model} — set pricing.${input.provider}.inputPer1K/outputPer1K or declare providers.${input.provider}.billingTier`,
+        };
+    }
+    // 5. A real list price. Whether it counts as BILLED depends on the one fact
+    //    only the user has: what their key is billed.
+    return {
+        billedUsd: tier === 'paid' ? listUsd : 0,
+        listUsd,
+        costSource: 'catalog',
+        bucket: tier === 'paid' ? 'billed-listed' : 'unverified-listed',
+        billingTier: tier,
+        basis: tier === 'paid'
+            ? `${quote.basis} — account declared paid, so this is an estimated bill`
+            : `${quote.basis} — account tier undeclared, so this is NOT counted as spend (set providers.${input.provider}.billingTier)`,
+        quote,
+    };
+}
+/**
+ * The LIST-priced estimate, for callers that need a number to RANK with
+ * (`auto-router`'s cost score, the fallback ladder, hybrid cost estimates).
+ *
+ * Deliberately returns the market price rather than the billed figure: ranking
+ * wants "what would this cost on the open market", while accounting wants "what
+ * did it cost ME". Conflating them is how the dashboard came to print an
+ * estimate under the word "spent".
+ */
+export function estimatedListCostUsd(provider, model, inputTokens, outputTokens, opts = {}) {
+    if (isModelLevelFree(provider, model))
+        return 0;
+    const quote = resolveListPrice(provider, model, opts);
+    if (!quote)
+        return 0;
+    return round6(costOf(quote, inputTokens, outputTokens));
+}
+/** Convenience for display surfaces: the price quote alone, or undefined. */
+export function priceQuoteFor(provider, model, opts = {}) {
+    return resolveListPrice(provider, model, opts);
+}
+//# sourceMappingURL=model-pricing.js.map

package/dist/learning/model-pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-pricing.js","sourceRoot":"","sources":["../../src/learning/model-pricing.ts"],"names":[],"mappings":"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"}

package/dist/learning/model-selection.d.ts

@@ -52,6 +52,21 @@ export declare function hasCredentials(configManager: ConfigManager, provider: s
  * failed outright.
  */
 export declare const MODEL_HEALTH_CEILING = 0.6;
+/**
+ * Could this model id ONLY have come from a test harness?
+ *
+ * The one definition of that question, because two callers need it and they
+ * must not drift: the router uses it to keep stub ids out of the routable pool
+ * (`isPairPlausible`, below), and `learning/cost-ledger-maintenance.ts` uses it
+ * to find the ledger rows a test run wrote into a real profile — MEASURED: 747
+ * rows of `local/wire-stub-model` sit in `~/.nuvira/memory/cost-tracker.json`
+ * from the provider-WIRE harness, and they were counted as real usage.
+ *
+ * Deliberately narrow, and a NAME SHAPE rather than a substring: `…-latest`
+ * aliases (`gemini-flash-latest`, `deepseek-coder:latest`) are real provider
+ * models, and a looser rule once flagged 25 real OpenRouter ids.
+ */
+export declare function isFixtureModelId(model: string): boolean;
 /**
  * POOL HYGIENE: could this provider really serve this model id?
  *

package/dist/learning/model-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-selection.d.ts","sourceRoot":"","sources":["../../src/learning/model-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAU1D,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,qEAAsE,CAAC;AAErG;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,CAAC;AAMnE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA6B,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOtF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAyDxC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAWxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAwD7D;AAcD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,cAAc,EAAE,CAuErF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAE3E;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE,aAAa,GAC5B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA0BjD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAS1F;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAa5E"}
+{"version":3,"file":"model-selection.d.ts","sourceRoot":"","sources":["../../src/learning/model-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAU1D,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,qEAAsE,CAAC;AAErG;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,CAAC;AAMnE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA6B,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOtF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAyDxC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAaxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAwD7D;AAcD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,cAAc,EAAE,CAuErF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAE3E;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE,aAAa,GAC5B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA0BjD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAS1F;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,CAa5E"}

package/dist/learning/model-selection.js

@@ -121,6 +121,24 @@ function definitivelyMissing(entry) {
         text.includes('not found') ||
         text.includes('no such model'));
 }
+/**
+ * Could this model id ONLY have come from a test harness?
+ *
+ * The one definition of that question, because two callers need it and they
+ * must not drift: the router uses it to keep stub ids out of the routable pool
+ * (`isPairPlausible`, below), and `learning/cost-ledger-maintenance.ts` uses it
+ * to find the ledger rows a test run wrote into a real profile — MEASURED: 747
+ * rows of `local/wire-stub-model` sit in `~/.nuvira/memory/cost-tracker.json`
+ * from the provider-WIRE harness, and they were counted as real usage.
+ *
+ * Deliberately narrow, and a NAME SHAPE rather than a substring: `…-latest`
+ * aliases (`gemini-flash-latest`, `deepseek-coder:latest`) are real provider
+ * models, and a looser rule once flagged 25 real OpenRouter ids.
+ */
+export function isFixtureModelId(model) {
+    const id = (model ?? '').trim().toLowerCase();
+    return /^(wire-|test-|fixture-|stub-)/.test(id) || /-stub(-|$)|\.stub\./.test(id);
+}
 /**
  * POOL HYGIENE: could this provider really serve this model id?
  *
@@ -151,8 +169,10 @@ export function isPairPlausible(provider, model) {
     const id = (model ?? '').trim().toLowerCase();
     if (!id)
         return false;
-    // 1. Fixture/stub ids.
-    if (/^(wire-|test-|fixture-|stub-)/.test(id) || /-stub(-|$)|\.stub\./.test(id))
+    // 1. Fixture/stub ids — the SAME predicate the cost-ledger pruner uses, so
+    //    "this id came from a test harness" has one definition (see
+    //    `isFixtureModelId`).
+    if (isFixtureModelId(id))
         return false;
     // 2. Ollama-style tags only on a local runner.
     if (id.includes(':')) {