B. Logical OpenAI model discovery + bare-model resolution (D-055) #134

New issue

Closed

opened 2026-09-26 21:42:53 +00:00 by kilo · 0 comments

kilo commented

2026-09-26 21:42:53 +00:00

Member

Child B of #132. Routing-contract change: representative OpenAI clients must select real models normally. Records decision D-055 (next valid number, checked).

Scope (frozen)

GET /v1/models exposes usable logical model ids for allowed adopted source-derived models, in addition to configured routing aliases. Restricted (daybreak) and discovered/unclassified models never appear; retired models never appear.
A request model = gpt-5.6-luna + reasoning_effort = max constrains routing to exactly that physical model and effort. Multiple sources/resources providing the identical exact identity may compete under existing capacity/scarcity/authorization policy. No cross-model substitution, ever.
Omitted reasoning_effort on a logical-model request: a max-only family (D-054) may use max when it is the only legal evidenced effort; otherwise the request fails explicitly — no invented effort, no silent default.
Known adopted model with temporarily unavailable resources → explicit availability/no-eligible-target outcome (503 family), never misleading model_not_found. Genuinely unknown (or restricted/unclassified-not-adopted) slug → model_not_found.
Alias collision rule, explicit and tested: administrator routing aliases take precedence over logical model ids (documented, surfaced in the models payload/admin view, never accidental). An alias may not silently shadow a logical model without that being visible.
sr-pin: semantics unchanged and still authoritative for exact resource/source selection.
Resolution order becomes: sr-pin: → alias → logical adopted model → model_not_found.
Decision D-055 in docs/decisions.md (alternatives, supersession/reconciliation language vs the D-042 model-field resolution contract as documented in docs/execution-surface.md); amend the execution-surface model-resolution section in place — no redundant new document.
Additive model metadata: /v1/models entries carry an x_scarcity_router extension (effective context/output ceilings, available reasoning efforts, restricted flag absent by construction) so representative clients and the child H integration UX can consume real numbers. Standard fields stay OpenAI-compatible.

Tests

One source; two sources same model/effort; source unavailable (availability outcome); model retired; restricted model; unclassified model; alias collision; explicit pin; bare logical model; exact effort honored; forbidden downgrade (non-max effort request against a max-only family fails; a lower-effort logical request never silently reroutes); restricted slug never routable via discovery; collision precedence.

Non-goals

No Codex adapter changes (child D/E); no reasoning-dialect parsing (child C); no limits changes (child D); no client-specific hacks in the routing core.

Complexity boundary

gateway_openai.py, gateway_coordinator.py (resolution), gateway_server.py (models payload), execution_sources.py (exposed-models view), gateway_contracts.py if typed errors needed; +1 decision/doc update; ~4–6 test files extended. Budget: 120 min wall clock.

Acceptance

Full gate green (uv sync --only-dev, make check, uv run basedpyright, git diff --check); representative fixture's model-resolution pin flipped to the new contract (child A asset updated); child-A positive/pin controls still green; PR open for human review; not merged.

Child B of #132. Routing-contract change: representative OpenAI clients must select real models normally. Records decision **D-055** (next valid number, checked). ## Scope (frozen) 1. `GET /v1/models` exposes usable logical model ids for allowed adopted source-derived models, in addition to configured routing aliases. Restricted (`daybreak`) and discovered/unclassified models never appear; retired models never appear. 2. A request `model = gpt-5.6-luna` + `reasoning_effort = max` constrains routing to exactly that physical model and effort. Multiple sources/resources providing the identical exact identity may compete under existing capacity/scarcity/authorization policy. No cross-model substitution, ever. 3. Omitted `reasoning_effort` on a logical-model request: a max-only family (D-054) may use `max` when it is the only legal evidenced effort; otherwise the request fails explicitly — no invented effort, no silent default. 4. Known adopted model with temporarily unavailable resources → explicit availability/no-eligible-target outcome (503 family), never misleading `model_not_found`. Genuinely unknown (or restricted/unclassified-not-adopted) slug → `model_not_found`. 5. **Alias collision rule, explicit and tested:** administrator routing aliases take precedence over logical model ids (documented, surfaced in the models payload/admin view, never accidental). An alias may not silently shadow a logical model without that being visible. 6. `sr-pin:` semantics unchanged and still authoritative for exact resource/source selection. 7. Resolution order becomes: `sr-pin:` → alias → logical adopted model → `model_not_found`. 8. Decision **D-055** in `docs/decisions.md` (alternatives, supersession/reconciliation language vs the D-042 model-field resolution contract as documented in `docs/execution-surface.md`); amend the execution-surface model-resolution section in place — no redundant new document. 9. Additive model metadata: `/v1/models` entries carry an `x_scarcity_router` extension (effective context/output ceilings, available reasoning efforts, restricted flag absent by construction) so representative clients and the child H integration UX can consume real numbers. Standard fields stay OpenAI-compatible. ## Tests One source; two sources same model/effort; source unavailable (availability outcome); model retired; restricted model; unclassified model; alias collision; explicit pin; bare logical model; exact effort honored; forbidden downgrade (non-max effort request against a max-only family fails; a lower-effort logical request never silently reroutes); restricted slug never routable via discovery; collision precedence. ## Non-goals No Codex adapter changes (child D/E); no reasoning-dialect parsing (child C); no limits changes (child D); no client-specific hacks in the routing core. ## Complexity boundary `gateway_openai.py`, `gateway_coordinator.py` (resolution), `gateway_server.py` (models payload), `execution_sources.py` (exposed-models view), `gateway_contracts.py` if typed errors needed; +1 decision/doc update; ~4–6 test files extended. Budget: 120 min wall clock. ## Acceptance Full gate green (`uv sync --only-dev`, `make check`, `uv run basedpyright`, `git diff --check`); representative fixture's model-resolution pin flipped to the new contract (child A asset updated); child-A positive/pin controls still green; PR open for human review; not merged.