feat(selection): execution-eligibility contract and pre-routing provider exclusion (D-039, issue #82) #83

Merged

adrian.tkacz merged 1 commit from feat/openai-subscription-eligibility into develop

2026-09-16 13:29:45 +00:00

kilo commented

2026-09-16 01:00:00 +00:00

Member

Implements BioMedical-IT/scarcity-router#82 (M4.1, decision D-039).

What

New provider-generic ExecutionEligibility contract (own schema_version: 1, closed state + reason-code vocabularies, strict exact-shape serialization) — deliberately separate from the frozen capacity v3 contract and never collapsed with it.
OpenAI eligibility parser over the same decoded account/rateLimits/read result as the capacity parser: hasCredits must be explicitly false (true → policy_blocked), ordinaryUsageAllowed must be explicitly true (false/null/legacy-absent → blocked/fail-closed), spendControlReached explicitly false, plus reached-type / exhausted individual limit / upsell / 100%-main-window blockers. Unknown == unsafe.
Acquisition pairs snapshot + eligibility in one app-server session (OpenAICodexObservation); operational failures pair safe failure snapshots with fail-closed unknown reports.
Selector gains a first-class execution exclusion stage (first in EXCLUSION_STAGES) with per-state primary reason codes; select_model(..., eligibility_reports=...) (≤1 per provider); excluded candidates carry the paired report. Absence of a report = stage never applies (never "eligible").
/v1/status + scarcity_status gain an additive optional eligibility envelope field (machine-interface v1 additive-domain rule; CLI --json byte-shape unchanged). Selection decisions carry the same data via execution_eligibility.
Discovery: explicit validated binary_path (SCARCITY_ROUTER_CODEX_BIN env hook) for the production pinned standalone Codex install; VS Code extension discovery stays default.
Decision record D-039 in docs/decisions.md; machine-interfaces.md contract table + status envelope updated.

Why

M4.1 owner policy: subscription allowance allowed, purchased credits forbidden, API PAYG forbidden. Today a hasCredits=true account still yields status="ok" capacity — the router would select a forbidden billing state and the caller would have to reject after selection. Unsafe OpenAI is now excluded BEFORE routing so the selector picks the next safe candidate (e.g. Z.ai); no caller-side fallback exists.

Verification

Full suite green: 1045 tests (33 new: contract round-trips, parser classifications, precedence, selector gate scenarios, envelope/parity); make check (unittest + basedpyright recommended, 0 errors/0 warnings) and git diff --check clean.
All tests deterministic and quota-free (redacted fixtures, injected collectors).
Billing model re-verified 2026-09-16 from first-party docs (help.openai.com 12642688, 11369540).

Links

Autonomy milestone: Infrastructure/creatidy-autonomy#15 → PR to follow
Production runtime: Infrastructure/creatidy-onprem#16 → PR to follow
Merge order: this PR first, then autonomy, then onprem. Nothing merged by the agent.

Implements [BioMedical-IT/scarcity-router#82](https://forgejo.creatidy.com/BioMedical-IT/scarcity-router/issues/82) (M4.1, decision **D-039**). ## What - New provider-generic **`ExecutionEligibility`** contract (own `schema_version: 1`, closed state + reason-code vocabularies, strict exact-shape serialization) — deliberately separate from the frozen capacity v3 contract and never collapsed with it. - **OpenAI eligibility parser** over the same decoded `account/rateLimits/read` result as the capacity parser: `hasCredits` must be explicitly false (`true` → `policy_blocked`), `ordinaryUsageAllowed` must be explicitly true (false/null/legacy-absent → blocked/fail-closed), `spendControlReached` explicitly false, plus reached-type / exhausted individual limit / upsell / 100%-main-window blockers. Unknown == unsafe. - Acquisition pairs **snapshot + eligibility in one app-server session** (`OpenAICodexObservation`); operational failures pair safe failure snapshots with fail-closed `unknown` reports. - Selector gains a first-class **`execution` exclusion stage** (first in `EXCLUSION_STAGES`) with per-state primary reason codes; `select_model(..., eligibility_reports=...)` (≤1 per provider); excluded candidates carry the paired report. Absence of a report = stage never applies (never "eligible"). - `/v1/status` + `scarcity_status` gain an **additive optional `eligibility` envelope field** (machine-interface v1 additive-domain rule; CLI `--json` byte-shape unchanged). Selection decisions carry the same data via `execution_eligibility`. - Discovery: explicit validated `binary_path` (`SCARCITY_ROUTER_CODEX_BIN` env hook) for the production pinned standalone Codex install; VS Code extension discovery stays default. - Decision record **D-039** in docs/decisions.md; machine-interfaces.md contract table + status envelope updated. ## Why M4.1 owner policy: subscription allowance allowed, purchased credits forbidden, API PAYG forbidden. Today a `hasCredits=true` account still yields `status="ok"` capacity — the router would select a forbidden billing state and the caller would have to reject after selection. Unsafe OpenAI is now excluded BEFORE routing so the selector picks the next safe candidate (e.g. Z.ai); no caller-side fallback exists. ## Verification - Full suite green: 1045 tests (33 new: contract round-trips, parser classifications, precedence, selector gate scenarios, envelope/parity); `make check` (unittest + basedpyright recommended, 0 errors/0 warnings) and `git diff --check` clean. - All tests deterministic and quota-free (redacted fixtures, injected collectors). - Billing model re-verified 2026-09-16 from first-party docs (help.openai.com 12642688, 11369540). ## Links - Autonomy milestone: Infrastructure/creatidy-autonomy#15 → PR to follow - Production runtime: Infrastructure/creatidy-onprem#16 → PR to follow - Merge order: **this PR first**, then autonomy, then onprem. Nothing merged by the agent.

kilo added 1 commit

2026-09-16 01:00:00 +00:00

feat(selection): execution-eligibility contract and pre-routing provider exclusion (D-039, issue #82 ) 761601d836

- new provider-generic ExecutionEligibility contract (schema v1) with closed
  state/reason vocabularies; unknown == unsafe; never collapsed with capacity v3
- Codex collector pairs the snapshot with an eligibility report parsed from the
  same app-server result; failures pair fail-closed unknown reports
- selector gains the first-class 'execution' exclusion stage with per-state
  primary reason codes; eligibility_reports input (<=1 per provider)
- /v1/status + scarcity_status expose an additive 'eligibility' envelope field;
  CLI status --json unchanged
- discovery binary_path override (SCARCITY_ROUTER_CODEX_BIN) for a pinned
  production Codex install
- D-039 decision record; machine-interface contract documented; 33 new tests

adrian.tkacz approved these changes

2026-09-16 13:29:37 +00:00

adrian.tkacz merged commit fce4311b93 into develop

2026-09-16 13:29:45 +00:00

adrian.tkacz deleted branch feat/openai-subscription-eligibility

2026-09-16 13:29:45 +00:00

adrian.tkacz referenced this pull request from a commit

2026-09-16 13:29:46 +00:00

Merge pull request 'feat(selection): execution-eligibility contract and pre-routing provider exclusion (D-039, issue #82)' (#83) from feat/openai-subscription-eligibility into develop