fix: resolve free routing from live provider economics

Author: Hermes Freebrain

docs/routing/STRICT_ZERO_COST.md

@@ -1,7 +1,7 @@
 ---
 title: "STRICT_ZERO_COST"
-version: 3.8.50
-lastUpdated: 2026-08-20
+version: 3.8.51
+lastUpdated: 2026-09-04
 ---
 
 # STRICT_ZERO_COST
@@ -13,9 +13,9 @@ lastUpdated: 2026-08-20
 
 ## Why this exists, and why `hidePaidModels` alone isn't enough
 
-`hidePaidModels` answers "is this model classified free in `FREE_MODEL_BUDGETS` right now?" —
-a point-in-time catalog fact, checked via `isFreeModel()`/`providerHasFreeModels()`
-(`src/shared/utils/freeModels.ts`). It says nothing about two real risks:
+`hidePaidModels` answers "is this candidate classified free?" using the shared free-model
+classifier plus connection-scoped discovery evidence and explicit local tier policy. It is still
+a classification filter, not a current-spend proof, and says nothing about two real risks:
 
 1. A `recurring-*`/`one-time-initial` free tier's allowance can be **exhausted** — the catalog
    still lists the model as free, but the account behind it has no headroom left.
@@ -32,20 +32,29 @@ dispatch — never after a request has already gone out.
 For every candidate in the pool (`open-sse/services/autoCombo/virtualFactory.ts::buildPreparedPool`,
 right after `filterPaidOnlyCandidates`):
 
-1. **Not in `FREE_MODEL_BUDGETS` at all** → excluded. This covers genuinely paid models and any
-   provider/model OmniRoute hasn't classified yet — new candidates start excluded, not included.
-2. **`freeType: "keyless"`** → passes immediately, **but only for a candidate that genuinely
+1. **Explicit local tier policy** is highest precedence. `free` admits the real connection set;
+   `cheap`/`premium` excludes even when lower-precedence catalog or discovery evidence says free.
+2. **Fresh connection-scoped discovery evidence** (`isFree`, a `:free` id, or exact zero pricing
+   observed in that provider response) admits only the connections that reported it free. The
+   successful discovery must be newer than `autoRefreshProviderQuotaInterval`; after restart or
+   expiry it becomes `state-unknown`, while the ordinary non-strict router may still use the LKG.
+3. **Nous Portal `:free` variants** are provider-owned no-cost variants and may pass without a
+   static catalog row. Other Nous models do not get this shortcut; Portal recommendations/pricing
+   determine their tier dynamically.
+4. **Not in `FREE_MODEL_BUDGETS` after those higher-precedence checks** → excluded. This covers
+   genuinely paid models and candidates OmniRoute still cannot prove zero-cost.
+5. **`freeType: "keyless"`** → passes immediately, **but only for a candidate that genuinely
    arrived via the no-auth path** (`connectionId === SYNTHETIC_NOAUTH_CONNECTION_ID`,
    `open-sse/services/autoCombo/resilienceCandidateFilter.ts`). No credential exists for that
    candidate, so no request against it can ever be billed — no runtime check is needed or
    possible. The same catalogued `keyless` provider/model reached through a **real** DB
    connection (`connectionId` is an actual connection id, or the candidate carries
    `allowedConnectionIds`) does **not** get this shortcut — `keyless` metadata describes the
    no-auth path specifically, not the provider in general, and never authorizes a real,
-   credentialed account. Such a candidate falls through to check 3 like any other, where it is
+   credentialed account. Such a candidate falls through to check 6 like any other, where it is
    excluded unless the catalog entry separately carries `hardStopGuaranteed: true` (real
    `keyless` entries never do — the shortcut was their only path to safety).
-3. **Any other `freeType`** (`recurring-daily`, `recurring-monthly`, `recurring-credit`,
+6. **Any other `freeType`** (`recurring-daily`, `recurring-monthly`, `recurring-credit`,
    `recurring-uncapped`, `one-time-initial`, and any future type this module doesn't
    special-case) → passes only if **all** of the following hold:
    - `hardStopGuaranteed: true` is set on the catalog entry (`FreeModelBudget.hardStopGuaranteed`,
@@ -60,7 +69,7 @@ right after `filterPaidOnlyCandidates`):
      evaluated** is `status: "SAFE"`, was checked within
      `settings.autoRefreshProviderQuotaInterval` (default 180s — the existing setting, not a new
      number), and reports `remainingFreeAllowance` above a small safety margin.
-4. **`freeType: "discontinued"`** → always excluded.
+7. **`freeType: "discontinued"`** → always excluded.
 
 ## Connection safety (per-connection verification, never per-candidate)
 
@@ -125,17 +134,18 @@ leaves the field `null` everywhere and costs nothing.
 
 | `freeAccessExclusion`  | What it means                                                                                                 | What to do about it                                                                                                                 |
 | :--------------------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |
-| `not-in-catalog`       | The provider/model pair is absent from `FREE_MODEL_BUDGETS`.                                                  | Add a curated entry, or accept that new pairs start excluded — that is the design.                                                  |
+| `operator-non-free`    | Local tier policy explicitly marks this provider/model `cheap` or `premium`.                                  | Change/remove the local override only if that policy is no longer intended.                                                         |
+| `not-in-catalog`       | No higher-precedence free proof exists and the pair is absent from `FREE_MODEL_BUDGETS`.                      | Add a curated entry or obtain live/explicit zero-cost evidence; unknown pairs fail closed.                                          |
 | `regime-not-free`      | Catalogued, but its `freeType` is not one that grants free access (a discontinued tier, for instance).        | Nothing to fix. The model costs money.                                                                                              |
 | `no-hard-stop`         | Free regime, but `hardStopGuaranteed` is not `true`, so exceeding the allowance might silently start billing. | Verify the provider's terms and set the flag with the source in a comment — never to grow the catalog.                              |
 | `contradictory-noauth` | A no-auth candidate whose catalog entry is not `keyless`. Fail-closed on inconsistent metadata.               | Fix the catalog entry; the two facts disagree.                                                                                      |
 | `exhausted`            | A fresh reading says the allowance is used up.                                                                | Wait for the reset. This one resolves itself.                                                                                       |
-| `state-unknown`        | No quota reading, or one too old to trust.                                                                    | Go look: the provider may have no usage adapter registered, or the quota fetch is failing.                                          |
+| `state-unknown`        | No fresh quota or live-discovery proof exists for this account.                                               | Refresh discovery/quota state; missing adapters or expired process-local evidence stay fail-closed.                                |
 | `no-connection`        | The candidate carries no account to check at all.                                                             | Not a quota problem: the candidate was built without a connection, so nothing was ever looked up. Check how the pool was assembled. |
 
-The last two are the pair worth separating. An exhausted allowance resets on its own; a reading
-that never arrives means the lookup itself is broken, and until now both looked identical from
-outside — the candidate simply vanished.
+The `exhausted` / `state-unknown` pair is worth separating. An exhausted allowance resets on its
+own; a reading that never arrives or live-discovery proof that expires means current safety is
+unknown, and until now both looked identical from outside — the candidate simply vanished.
 
 **One gap remains, and it is deliberate.** `excludeTosAvoid` still removes candidates before the
 listing is built, so a model curated `tos: "avoid"` is absent with no reason given — the same

open-sse/services/__tests__/tierResolver.test.ts

@@ -125,6 +125,13 @@ describe("TierResolver", () => {
       expect(result.reason.includes("override")).toBe(true);
     });
 
+    it("lets an explicit non-free override beat default free-provider classification", () => {
+      setTierConfig({ providerOverrides: [{ provider: "groq", tier: "premium" }] });
+      const result = classifyTier("groq", "openai/gpt-oss-120b");
+      expect(result.tier).toBe(PROVIDER_TIER.PREMIUM);
+      expect(result.hasFreeTier).toBe(false);
+    });
+
     it("respects model-level glob pattern override", () => {
       setTierConfig({
         modelOverrides: [{ provider: "openai", modelPattern: "gpt-4o-mini*", tier: "cheap" }],

open-sse/services/autoCombo/freeAccessQuota.ts

@@ -20,6 +20,7 @@ import {
   type UsageFetcherProvider,
 } from "./../usage.ts";
 import { getCachedProviderConnections } from "@/lib/db/readCache";
+import { invalidateProviderModelDiscoveryFreshness } from "@/lib/providerModels/discoveryFreshness";
 import { defaultLogger as log } from "@omniroute/open-sse/utils/logger";
 import type { FreeAccessState } from "./strictZeroCostFilter";
 import { isStateStaleForReset } from "./subscriptionLadder";
@@ -211,6 +212,7 @@ export function resolveFreeAccessState(
  * build reads a clean cache miss (UNKNOWN) rather than a stale SAFE. */
 export function invalidateFreeAccessState(provider: string, connectionId: string): void {
   cache.delete(cacheKey(provider, connectionId));
+  invalidateProviderModelDiscoveryFreshness(provider, connectionId);
 }
 
 export const __testing = { cache, extractRemainingAllowance, sweepIfDue };

open-sse/services/autoCombo/freeCandidateEconomics.ts

@@ -0,0 +1,13 @@
+type SyncedFreeEvidence = Record<string, Array<{ id: string; isFree?: boolean }>>;
+
+/** Convert per-connection discovery evidence into a candidate field without widening scope. */
+export function discoveredFreeConnectionScope(
+  allowedConnectionIds: string[],
+  syncedByConnection: SyncedFreeEvidence,
+  modelId: string
+): { freeConnectionIds?: string[] } {
+  const freeConnectionIds = allowedConnectionIds.filter((connectionId) =>
+    (syncedByConnection[connectionId] ?? []).some((m) => m.id === modelId && m.isFree === true)
+  );
+  return freeConnectionIds.length > 0 ? { freeConnectionIds } : {};
+}

open-sse/services/autoCombo/paidModelFilter.ts

@@ -11,34 +11,52 @@
  * Kept as a pure, dependency-light function so the filter is unit-testable in
  * isolation without seeding the DB-backed virtual factory.
  */
-import { isFreeModel, providerHasFreeModels } from "@/shared/utils/freeModels";
+import { isFreeModel } from "@/shared/utils/freeModels";
 
 interface PaidFilterCandidate {
   provider: string;
   model: string;
-}
-
-/** A candidate is kept only when its provider has documented free models AND the
- * selected model itself qualifies as free — mirrors `shouldHidePaid` in
- * `src/app/api/v1/models/catalog.ts`. */
-function isFreeCandidate(candidate: PaidFilterCandidate): boolean {
-  return (
-    providerHasFreeModels(candidate.provider) &&
-    isFreeModel(candidate.provider, { id: candidate.model })
-  );
+  allowedConnectionIds?: string[];
+  freeConnectionIds?: string[];
 }
 
 /**
  * Return the candidate pool filtered to free-only backends when
  * `hidePaidModels` is on; otherwise return the pool unchanged (identity — the
- * default, opt-in-off path). If every candidate is paid the result is empty, and
- * the caller's existing graceful empty-pool path handles it (consistent with the
- * opt-in intent — the operator asked not to route to paid models).
+ * default, opt-in-off path). Connection-scoped discovery is honored without
+ * widening it: when only some credentials reported this model free, the
+ * candidate's dispatch allowlist is narrowed to exactly those connections.
  */
 export function filterPaidOnlyCandidates<T extends PaidFilterCandidate>(
   pool: T[],
-  hidePaidModels: boolean
+  hidePaidModels: boolean,
+  resolveOperatorTier: (
+    provider: string,
+    model: string
+  ) => "free" | "cheap" | "premium" | undefined = () => undefined
 ): T[] {
   if (!hidePaidModels) return pool;
-  return pool.filter(isFreeCandidate);
+
+  const kept: T[] = [];
+  for (const candidate of pool) {
+    const override = resolveOperatorTier(candidate.provider, candidate.model);
+    if (override !== undefined) {
+      if (override === "free") kept.push(candidate);
+      continue;
+    }
+    if (isFreeModel(candidate.provider, { id: candidate.model })) {
+      kept.push(candidate);
+      continue;
+    }
+
+    const freeConnections = candidate.freeConnectionIds ?? [];
+    if (freeConnections.length === 0) continue;
+    const allowed = candidate.allowedConnectionIds ?? [];
+    const narrowed = freeConnections.filter((id) => allowed.includes(id));
+    if (narrowed.length === 0) continue;
+    const same =
+      allowed.length === narrowed.length && narrowed.every((id) => allowed.includes(id));
+    kept.push(same ? candidate : ({ ...candidate, allowedConnectionIds: narrowed } as T));
+  }
+  return kept;
 }

open-sse/services/autoCombo/strictZeroCostFilter.ts

@@ -16,11 +16,11 @@
  * lives in `freeAccessQuota.ts` and is injected here as a plain function —
  * this file never imports the DB or makes a network call itself.
  *
- * No provider or model name appears anywhere in this file. A candidate passes
- * or fails purely on the metadata it carries (`freeType`, `tos`,
- * `hardStopGuaranteed`) plus, for quota-based types, a `FreeAccessState`
- * resolved elsewhere. A future provider that ships correct metadata is
- * handled automatically; one that doesn't is excluded automatically — see
+ * The normal path is provider-agnostic: a candidate passes or fails on catalog
+ * metadata (`freeType`, `tos`, `hardStopGuaranteed`) plus, for quota-based
+ * types, a `FreeAccessState` resolved elsewhere. Higher-precedence facts are
+ * admitted before that path: local operator policy, connection-scoped live free
+ * evidence, and Nous Portal's provider-owned `:free` variants. Everything else fails closed — see
  * `docs/routing/STRICT_ZERO_COST.md`.
  *
  * ## Connection safety (fixed after code review, see `docs/routing/STRICT_ZERO_COST.md`)
@@ -81,6 +81,7 @@ export interface StrictZeroCostCandidate {
   model: string;
   connectionId: string | null;
   allowedConnectionIds?: string[];
+  freeConnectionIds?: string[];
 }
 
 export interface StrictZeroCostOptions {
@@ -109,6 +110,13 @@ export interface StrictZeroCostOptions {
   maxStateAgeMs: number;
   /** `now` injection for deterministic tests; defaults to `Date.now`. */
   now?: () => number;
+  /** Explicit local policy wins over catalog/live inference in either direction. */
+  resolveOperatorTier?: (
+    provider: string,
+    model: string
+  ) => "free" | "cheap" | "premium" | undefined;
+  /** Whether this connection's model discovery was live-verified recently enough. */
+  isDiscoveryEvidenceFresh?: (provider: string, connectionId: string, maxAgeMs: number) => boolean;
   /**
    * The free-model catalog to look candidates up against. Defaults to the
    * real, live `FREE_MODEL_BUDGETS` — overridable so tests can prove the
@@ -129,9 +137,19 @@ export function findBudgetEntry(
   return catalog.find((m) => m.provider === candidate.provider && m.modelId === candidate.model);
 }
 
+function candidateConnectionIds(candidate: StrictZeroCostCandidate): string[] {
+  return candidate.connectionId ? [candidate.connectionId] : (candidate.allowedConnectionIds ?? []);
+}
+
+/** Nous Portal rotates price-locked free variants independently of releases. */
+function isNousPortalFreeVariant(candidate: StrictZeroCostCandidate): boolean {
+  return candidate.provider === "nous-research" && candidate.model.toLowerCase().endsWith(":free");
+}
+
 /** Why the guard cannot trust a candidate right now. */
 export type StrictZeroCostExclusionReason =
   | "not-in-catalog"
+  | "operator-non-free"
   | "regime-not-free"
   | "no-hard-stop"
   | "contradictory-noauth"
@@ -193,7 +211,14 @@ export function evaluateCandidateConnections(
   candidate: StrictZeroCostCandidate,
   budgetEntry: FreeModelBudget | undefined,
   resolveFreeAccessState: StrictZeroCostOptions["resolveFreeAccessState"],
-  options: Pick<StrictZeroCostOptions, "minRemainingAllowance" | "maxStateAgeMs" | "now">
+  options: Pick<
+    StrictZeroCostOptions,
+    | "minRemainingAllowance"
+    | "maxStateAgeMs"
+    | "now"
+    | "resolveOperatorTier"
+    | "isDiscoveryEvidenceFresh"
+  >
 ): string[] {
   const verdict = classifyStrictZeroCostCandidate(
     candidate,
@@ -214,9 +239,43 @@ export function classifyStrictZeroCostCandidate(
   candidate: StrictZeroCostCandidate,
   budgetEntry: FreeModelBudget | undefined,
   resolveFreeAccessState: StrictZeroCostOptions["resolveFreeAccessState"],
-  options: Pick<StrictZeroCostOptions, "minRemainingAllowance" | "maxStateAgeMs" | "now">
+  options: Pick<
+    StrictZeroCostOptions,
+    | "minRemainingAllowance"
+    | "maxStateAgeMs"
+    | "now"
+    | "resolveOperatorTier"
+    | "isDiscoveryEvidenceFresh"
+  >
 ): StrictZeroCostVerdict {
-  if (!budgetEntry) return { outcome: "not-in-catalog" }; // paid, or genuinely unknown
+  const directConnectionIds = candidateConnectionIds(candidate).filter(
+    (connectionId) => connectionId !== SYNTHETIC_NOAUTH_CONNECTION_ID
+  );
+  const operatorTier = options.resolveOperatorTier?.(candidate.provider, candidate.model);
+  if (operatorTier !== undefined) {
+    if (operatorTier !== "free") return { outcome: "operator-non-free" };
+    return directConnectionIds.length > 0
+      ? { outcome: "safe", safeConnectionIds: directConnectionIds }
+      : { outcome: "no-connection" };
+  }
+  let hasStaleDiscoveryFreeEvidence = false;
+  if ((candidate.freeConnectionIds?.length ?? 0) > 0) {
+    const liveFree = directConnectionIds.filter(
+      (id) =>
+        candidate.freeConnectionIds!.includes(id) &&
+        options.isDiscoveryEvidenceFresh?.(candidate.provider, id, options.maxStateAgeMs) === true
+    );
+    if (liveFree.length > 0) return { outcome: "safe", safeConnectionIds: liveFree };
+    hasStaleDiscoveryFreeEvidence = true;
+  }
+  if (isNousPortalFreeVariant(candidate)) {
+    return directConnectionIds.length > 0
+      ? { outcome: "safe", safeConnectionIds: directConnectionIds }
+      : { outcome: "no-connection" };
+  }
+
+  if (!budgetEntry)
+    return { outcome: hasStaleDiscoveryFreeEvidence ? "state-unknown" : "not-in-catalog" };
 
   const isGenuineNoAuthCandidate = candidate.connectionId === SYNTHETIC_NOAUTH_CONNECTION_ID;
   if (allowsNoAuthShortcut(budgetEntry.freeType)) {
@@ -242,21 +301,19 @@ export function classifyStrictZeroCostCandidate(
   // trust regardless of its answer.
   if (budgetEntry.hardStopGuaranteed !== true) return { outcome: "no-hard-stop" };
 
-  const candidateConnectionIds = candidate.connectionId
-    ? [candidate.connectionId]
-    : (candidate.allowedConnectionIds ?? []);
+  const connectionIds = candidateConnectionIds(candidate);
 
   // No account at all to check. Reporting `state-unknown` here would send the
   // operator hunting a quota lookup that was never attempted; this is a wiring
   // problem, not a quota one.
-  if (candidateConnectionIds.length === 0) return { outcome: "no-connection" };
+  if (connectionIds.length === 0) return { outcome: "no-connection" };
 
   const safe: string[] = [];
   // An observed exhaustion outranks a missing reading: one is a fact, the other
   // is the absence of one, and the operator needs the fact. Without this rule the
   // reason would depend on the order the connections happen to be listed in.
   let sawExhausted = false;
-  for (const connectionId of candidateConnectionIds) {
+  for (const connectionId of connectionIds) {
     if (connectionId === SYNTHETIC_NOAUTH_CONNECTION_ID) continue; // never reachable here, defensive
     const state = classifyConnectionState(
       candidate.provider,