feat(sse): add STRICT_ZERO_COST opt-in free-access policy - #10965
Merged
diegosouzapw merged 5 commits intoAug 21, 2026
Merged
diegosouzapw merged 5 commits into
diegosouzapw merged 5 commits into
Conversation
hidePaidModels only checks whether a model is documented free in FREE_MODEL_BUDGETS at catalog-curation time; it says nothing about whether a recurring/one-time free allowance has since been exhausted, or whether exceeding it is a guaranteed hard stop versus silent pay-as-you-go billing. STRICT_ZERO_COST (settings.freeAccessPolicy, default "off") adds both checks per candidate, before ranking and before dispatch: keyless candidates pass immediately (no credential exists to bill), every other freeType requires a curated hardStopGuaranteed:true declaration plus a live, cached, fresh SAFE quota state from the existing getUsageForProvider()/ USAGE_FETCHER_PROVIDERS registry. Unknown metadata always excludes, never defaults to safe. Also adds excludeTosAvoid, independent of economic safety, reusing the existing curated `tos` field. No provider or model name is hardcoded anywhere in the filter; a future provider with correct metadata is picked up automatically (see the autodiscovery test suite using injectable catalog fixtures).
Two gaps found reviewing 5d4f881 as if it were an incoming PR: - The `keyless` shortcut matched on catalog freeType alone, so a catalogued-keyless provider/model reached through a real DB connection (not the no-auth sentinel) would incorrectly bypass all quota checks. `evaluateCandidateConnections()` now requires `connectionId === SYNTHETIC_NOAUTH_CONNECTION_ID` for the shortcut; any other connection falls through to the normal hardStopGuaranteed+quota path, where real `keyless` catalog rows (which never set hardStopGuaranteed) correctly fail closed. - A multi-account candidate's economic safety was checked against one connection while `allowedConnectionIds` still exposed every account to dispatch, so a verified-SAFE account could authorize traffic that actually lands on a different, unverified one. The filter now checks every connection in the allowlist independently and rewrites `allowedConnectionIds` to exactly the SAFE subset, relying on the existing allowlist intersection in autoStrategy.ts to guarantee dispatch never selects a connection this filter didn't itself verify. Also drops the dead `catalog` field from `StrictZeroCostOptions` (was never read; `findBudgetEntry()` already takes its own catalog override) and threads the real per-connection resolver into virtualFactory.ts instead of a candidate-level closure that collapsed multi-account candidates onto one arbitrary connection.
- Cap concurrent background quota refreshes (MAX_CONCURRENT_REFRESHES=4): a cold cache after a process restart previously fired one getUsageForProvider() call per distinct (provider, connection) pair in the same tick. A skipped refresh just leaves that candidate UNKNOWN (excluded, fail-closed) until a later pool build retries. - Add a hard eviction sweep (piggybacked on resolveFreeAccessState calls, not a timer) for cache entries whose connection was removed and never gets a normal stale-triggered refresh again.
…idates Reads each live candidate's real connectionId (previously ignored) and uses the updated evaluateCandidateConnections() API, so the ad-hoc before/after report also exercises the connection-safety fix against live data — a keyless-catalogued model reached via a real connection is now reported as its own distinct exclusion reason.
Update STRICT_ZERO_COST.md with the keyless-shortcut connection requirement and the new "Connection safety" section describing how multi-account candidates are verified per-connection and their allowedConnectionIds narrowed to the SAFE subset. Refresh "What passes today" with current live numbers (7 candidates strict+ToS=false, 0 strict+ToS=true) confirmed against real connectionIds. Add the Unreleased CHANGELOG entry for the feature.
Sa3id23
pushed a commit
to Sa3id23/OmniRoute
that referenced
this pull request
Aug 21, 2026
…pw#10965) ⭐5 — freeAccessPolicy "strict" opt-in (default off): verifica candidatos de auto-combo contra estado de quota ao vivo + segurança econômica por conexão antes do dispatch (fail-closed — estado desconhecido/stale/incompleto é excluído). Zero mudança de comportamento com o default "off". 82 testes focados, eslint/prettier/typecheck limpos, docs em docs/routing/STRICT_ZERO_COST.md.
jonlwheat2-gif
added a commit
to jonlwheat2-gif/OmniRoute
that referenced
this pull request
Aug 21, 2026
…e test - open-sse-typecheck: sync frozen baseline to the merged-tree reality — clientUsageBuffer/stream.ts errors no longer exist, and virtualFactory TS2362 is inherited from base diegosouzapw#10965 (STRICT_ZERO_COST block lands after this branch's fork point; maintainers reverted the block on their newer base, so this is base-owned drift, not a PR regression) - systemd-notify: messages travel over a dgram socket so arrival order is racy (STOPPING=1 can beat WATCHDOG=1 under load); compare order-free
jonlwheat2-gif
added a commit
to jonlwheat2-gif/OmniRoute
that referenced
this pull request
Aug 21, 2026
…e test - open-sse-typecheck: sync frozen baseline to the merged-tree reality — clientUsageBuffer/stream.ts errors no longer exist, and virtualFactory TS2362 is inherited from base diegosouzapw#10965 (STRICT_ZERO_COST block lands after this branch's fork point; maintainers reverted the block on their newer base, so this is base-owned drift, not a PR regression) - systemd-notify: messages travel over a dgram socket so arrival order is racy (STOPPING=1 can beat WATCHDOG=1 under load); compare order-free
Merged
muhamadgalihsaputra
pushed a commit
to niyatna/NiyatnaRoute
that referenced
this pull request
Sep 27, 2026
…pw#10965) ⭐5 — freeAccessPolicy "strict" opt-in (default off): verifica candidatos de auto-combo contra estado de quota ao vivo + segurança econômica por conexão antes do dispatch (fail-closed — estado desconhecido/stale/incompleto é excluído). Zero mudança de comportamento com o default "off". 82 testes focados, eslint/prettier/typecheck limpos, docs em docs/routing/STRICT_ZERO_COST.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an opt-in, off-by-default
freeAccessPolicy: "strict"that verifies auto-combo candidates against live quota state and per-connection economic safety before dispatch.This goes beyond
hidePaidModels, which is based on static catalog classification.The policy is fail-closed: candidates are excluded when their free-access state cannot be verified safely.
Safety guarantees
allowedConnectionIdsthat were independently verified as SAFE.hardStopGuaranteedmetadata is treated as unsafe.excludeTosAvoidis provided as a separate opt-in guard for models/providers whose curated ToS metadata is markedavoid.Backward compatibility
The feature is disabled by default:
freeAccessPolicy: "off"Therefore existing OmniRoute behavior is unchanged unless the policy is explicitly enabled.
Design
The policy uses existing OmniRoute catalog and usage infrastructure:
hardStopGuaranteedFuture providers/models can become eligible automatically when OmniRoute has enough metadata to verify them safely.
See:
docs/routing/STRICT_ZERO_COST.mdTests
82 targeted tests passing, including:
Also verified:
npm run typecheck:corepassingKnown limitation
Quota-based providers without both:
hardStopGuaranteed: trueremain
UNKNOWNand are excluded.This is intentional fail-closed behavior rather than a fallback to potentially billable traffic.