OmniRoute/docs/routing/STRICT_ZERO_COST.md

title, version, lastUpdated

title	version	lastUpdated
STRICT_ZERO_COST	3.8.50	2026-08-23

STRICT_ZERO_COST

Opt-in, off by default (settings.freeAccessPolicy !== "strict" leaves every auto/* candidate pool byte-identical). A stricter sibling of hidePaidModels (open-sse/services/autoCombo/paidModelFilter.ts, #6512) for operators who need a hard guarantee against ANY incremental monetary spend, not just "documented as free".

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:

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.
2. Exceeding a free tier is not always a hard stop. Some providers document explicitly that no payment method can ever be attached ("no credit card required"); others don't say, and a handful bill automatically past the free allowance.

hidePaidModels cannot distinguish these — it was never meant to. STRICT_ZERO_COST adds exactly these two checks, evaluated per candidate, before category/tier ranking and before dispatch — never after a request has already gone out.

Candidate classification

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 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 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, 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, open-sse/config/freeModelCatalog.ts) — a curated, hand-set fact about the provider's own published terms (e.g. an explicit "no credit card required" claim), never derived from freeType or from a live API response. Unset (undefined) and false are both treated as "not guaranteed".
   • A usage adapter exists for the provider in USAGE_FETCHER_PROVIDERS (open-sse/services/usage.ts) — the same registry that already backs the quota dashboard and getUsageForProvider(). No adapter → excluded, permanently, until one is added.
   • The live, cached FreeAccessState for the specific connection actually being 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.

Connection safety (per-connection verification, never per-candidate)

A candidate in the auto-combo pool is not always tied to one connection. A "logical" candidate (connectionId: null) carries an allowedConnectionIds allowlist — one or more actual provider connections/accounts any of which could serve the request — and the account actually used is decided later, at dispatch time, by open-sse/services/combo/autoStrategy.ts (intersecting allowedConnectionIds against its own connection-selection logic, ~line 315-331).

STRICT_ZERO_COST verifies the free-access state of each connection in that allowlist individually (evaluateCandidateConnections() in strictZeroCostFilter.ts) and rewrites allowedConnectionIds down to exactly the subset that came back SAFE — never the full original list, and never a single arbitrarily-chosen member. Concretely:

• Account A SAFE, account B UNKNOWN/exhausted/billable → only A remains selectable.
• All accounts UNKNOWN → the candidate is dropped entirely (empty safe set).
• A single-connection candidate (connectionId set directly, no allowlist) that fails is dropped outright, never returned with an empty allowedConnectionIds.

Because autoStrategy.ts already enforces allowedConnectionIds as a hard allowlist before selecting a connection to dispatch to, rewriting it to the verified-SAFE subset is sufficient to guarantee the connection actually used at dispatch is always one this filter itself verified — never a different, unverified account on the same candidate. See tests/unit/autoCombo/strict-zero-cost-connection-safety.test.ts for the regression proof (keyless-bypass cases A/B/C, multi-account cases 1-5).

discovered automatically: a provider/model shipped tomorrow with the right metadata (in the catalog, with a usage adapter, hardStopGuaranteed: true) is usable the moment OmniRoute knows about it — no code change, no whitelist entry, nothing to edit in this module. One removed from the catalog disappears the same way. See tests/unit/autoCombo/strict-zero-cost-autodiscovery.test.ts for the regression proof (via injectable fixtures, not by mutating the real catalog).

Quota caching (open-sse/services/autoCombo/freeAccessQuota.ts)

Reuses getUsageForProvider() — no second quota system. A short, in-memory, process-lifetime cache sits in front of it (TTL equal to the default autoRefreshProviderQuotaInterval) so a Telegram-scale request rate never triggers a live billing-API call per candidate per request. Reads are synchronous: a cache miss returns undefined (→ excluded, fail-closed) and kicks off a background refresh for the next read — nothing in the candidate-pool build path ever awaits a network call.

invalidateFreeAccessState(provider, connectionId) is called from src/sse/services/auth.ts::markAccountUnavailable() the moment a connection fails for any reason, so the very next pool build reads a clean cache miss instead of a stale SAFE entry — no waiting out the TTL after a 402/403/quota-exhausted response.

ToS guard (independent of economic safety)

excludeTosAvoid (default false) drops any candidate whose curated tos verdict (FreeModelBudget.tos) is "avoid" — reuses the same field hidePaidModels's sibling docs (docs/reference/FREE_TIERS.md) already populate. Deliberately separate from freeAccessPolicy: a candidate can be economically SAFE and still excluded here for contractual reasons, or left in when this guard is off even with freeAccessPolicy: "strict" on.

Current catalog eligibility

Run npx tsx scripts/ad-hoc/dry-run-strict-zero-cost.ts against a live instance's GET /v1/auto-combo/{channel}/candidates output for a real before/after. The script reads each candidate's actual connectionId, so it verifies connection safety rather than inferring it from the static catalog.

The v3.8.50 catalog snapshot on 2026-08-23 contains 19 keyless model entries whose provider also has a no-auth catalog path: aihorde (3), duckduckgo-web (6), opencode (7), and uncloseai (3). This is a static eligibility ceiling, not a claim that all 19 will appear or pass on a particular installation: health, model discovery, candidate construction, and the synthetic no-auth connectionId are still checked at runtime. No current quota-based entry can bypass the independent usage-adapter, hard-stop, freshness, and remaining-allowance checks described above.

With excludeTosAvoid: true, the static no-auth/keyless ceiling becomes 6 entries: the three aihorde models (tos: "ok") and three uncloseai models (tos: "caution"). The 13 duckduckgo-web/opencode entries are curated tos: "avoid". The guard remains false by default because economic safety and contractual policy are intentionally independent.

Enabling

PUT /api/settings
{ "freeAccessPolicy": "strict", "excludeTosAvoid": false }

Both new settings default to their pre-feature values ("off" / false) — enabling neither changes any existing auto/* routing behavior.