Logical OpenAI model discovery + bare-model resolution (D-055, #134) #144

Merged

adrian.tkacz merged 2 commits from compat/logical-model-resolution into develop

2026-09-27 15:46:48 +00:00

kilo commented

2026-09-26 23:58:41 +00:00

Member

Closes #134 (child B of program #132, decision D-055). Stacked on PR #142 (compat/representative-client-fixture): the representative fixture (#133) is this contract's regression asset. Retarget to develop after #142 merges.

What

Bare physical-model ids become a third model-field reading — the fix for acceptance failure 4 (a real client's "model": "gpt-5.6-luna" was model_not_found; only aliases and sr-pin: resolved, and /v1/models exposed aliases only).

Resolution order: sr-pin: → alias → logical model → model_not_found. A logical request resolves to the EXACT (provider, model) identity and rides the routing core's EXISTING explicit_model/explicit_variant narrowing — normal scarcity policy competes only the resources providing exactly that identity. No routing-engine change, no substitution, ever.
Effort is exact: unsupported_reasoning_effort (typed 400) for a variant the identity lacks — no downgrade; reasoning_effort_required when omitted and several calibrated variants exist; a max-only family's single legal effort (max, D-054) is used when omitted; ambiguous_logical_model when two providers carry the slug. Rejections are audited with no dispatch.
Discovery (GET /v1/models): aliases first, then exposed logical models — a calibrated identity is exposed only when ≥1 registered resource binds it (empty deployment exposes nothing; retired disappears; registered-but-unavailable still appears and yields 503 no_eligible_target, never a misleading 404; restricted/unclassified never appear). Additive x_scarcity_router metadata per entry: kind, and for logical models provider, reasoning_efforts, effective_context_limit_tokens (model hard context ∩ known channel ceilings; null = UNKNOWN, never guessed), max_output_tokens.
Alias collisions explicit: aliases take precedence; one entry per id, flagged logical_model_shadowed.
Docs: D-055 in docs/decisions.md (with alternatives + explicit D-042 reconciliation); execution-surface model-resolution section and error table amended in place.

Pins flipped / coordination with #142 review

The #142 review's DEFER findings are addressed here: the aliases-only assertions in test_gateway_server.py AND the representative pin are updated in coordination (DEFER 2), and the tools-pin docstring wording is tightened (DEFER 3). DEFER 1 (test-to-test harness import) is acknowledged; promotion to gateway_fixtures is left until a third importer materializes — this branch imports ServerHarness directly, keeping the diff minimal. The #135/#136/#137 pins are untouched.

Tests

New tests/test_logical_model_resolution.py (16 tests) over a real D-053 world (track registry + derived registrations + floor catalog): exact-identity routing with selected==executed audit; two sources competing for one identity; effort rule (max-only omitted → max; multi-variant omitted → 400; unknown effort → 400 + audited rejection); restricted/unclassified/unknown stay 404; unavailable → 503 availability; empty deployment exposes nothing; alias precedence + visible shadowing; ambiguous slug fails loudly and is never advertised; honest metadata intersection (272000, not 1.05M); historical no-catalog behavior preserved.

Gates

uv sync --only-dev ✓
make check — 2083 tests; green on 5 of 7 runs this session; the 2 failures are the pre-existing load-sensitive test_scenario_11 cancellation e2e, unrelated to this diff (class passes 8/8 in isolation on BOTH this branch and pristine develop), filed as #143 with root-cause hypothesis. Not retried to green; reported per repo discipline.
uv run basedpyright — 0 / 0 / 0 ✓
git diff --check ✓

UX impact

Direct positive: the normal client path (bare model id) now works without sr-pin:; discovery shows real models with real effective numbers; unavailable models give honest availability errors; alias shadowing is visible. Errors are typed and actionable (unsupported_reasoning_effort, reasoning_effort_required). No hidden/manual steps introduced.

Review

Independent GLM-5.3-Flash exact-head review requested. Not security-critical (no new trust boundary, credential path or execution semantics; routing narrowing reuses the frozen pin-narrowing machinery). PR left open for the human merge gate.

Closes #134 (child B of program #132, decision **D-055**). **Stacked on PR #142** (`compat/representative-client-fixture`): the representative fixture (#133) is this contract's regression asset. Retarget to `develop` after #142 merges. ## What Bare physical-model ids become a third model-field reading — the fix for acceptance failure 4 (a real client's `"model": "gpt-5.6-luna"` was `model_not_found`; only aliases and `sr-pin:` resolved, and `/v1/models` exposed aliases only). - **Resolution order:** `sr-pin:` → alias → logical model → `model_not_found`. A logical request resolves to the EXACT `(provider, model)` identity and rides the routing core's EXISTING `explicit_model`/`explicit_variant` narrowing — normal scarcity policy competes only the resources providing exactly that identity. No routing-engine change, no substitution, ever. - **Effort is exact:** `unsupported_reasoning_effort` (typed 400) for a variant the identity lacks — no downgrade; `reasoning_effort_required` when omitted and several calibrated variants exist; a max-only family's single legal effort (`max`, D-054) is used when omitted; `ambiguous_logical_model` when two providers carry the slug. Rejections are audited with no dispatch. - **Discovery (`GET /v1/models`):** aliases first, then exposed logical models — a calibrated identity is exposed only when ≥1 registered resource binds it (empty deployment exposes nothing; retired disappears; registered-but-unavailable still appears and yields 503 `no_eligible_target`, never a misleading 404; restricted/unclassified never appear). Additive `x_scarcity_router` metadata per entry: `kind`, and for logical models `provider`, `reasoning_efforts`, `effective_context_limit_tokens` (model hard context ∩ known channel ceilings; `null` = UNKNOWN, never guessed), `max_output_tokens`. - **Alias collisions explicit:** aliases take precedence; one entry per id, flagged `logical_model_shadowed`. - **Docs:** D-055 in `docs/decisions.md` (with alternatives + explicit D-042 reconciliation); execution-surface model-resolution section and error table amended in place. ## Pins flipped / coordination with #142 review The #142 review's DEFER findings are addressed here: the aliases-only assertions in `test_gateway_server.py` AND the representative pin are updated in coordination (DEFER 2), and the tools-pin docstring wording is tightened (DEFER 3). DEFER 1 (test-to-test harness import) is acknowledged; promotion to `gateway_fixtures` is left until a third importer materializes — this branch imports `ServerHarness` directly, keeping the diff minimal. The #135/#136/#137 pins are untouched. ## Tests New `tests/test_logical_model_resolution.py` (16 tests) over a real D-053 world (track registry + derived registrations + floor catalog): exact-identity routing with selected==executed audit; two sources competing for one identity; effort rule (max-only omitted → max; multi-variant omitted → 400; unknown effort → 400 + audited rejection); restricted/unclassified/unknown stay 404; unavailable → 503 availability; empty deployment exposes nothing; alias precedence + visible shadowing; ambiguous slug fails loudly and is never advertised; honest metadata intersection (272000, not 1.05M); historical no-catalog behavior preserved. ## Gates - `uv sync --only-dev` ✓ - `make check` — 2083 tests; green on 5 of 7 runs this session; the 2 failures are the pre-existing load-sensitive `test_scenario_11` cancellation e2e, unrelated to this diff (class passes 8/8 in isolation on BOTH this branch and pristine `develop`), filed as **#143** with root-cause hypothesis. Not retried to green; reported per repo discipline. - `uv run basedpyright` — 0 / 0 / 0 ✓ - `git diff --check` ✓ ## UX impact Direct positive: the normal client path (bare model id) now works without `sr-pin:`; discovery shows real models with real effective numbers; unavailable models give honest availability errors; alias shadowing is visible. Errors are typed and actionable (`unsupported_reasoning_effort`, `reasoning_effort_required`). No hidden/manual steps introduced. ## Review Independent GLM-5.3-Flash exact-head review requested. Not security-critical (no new trust boundary, credential path or execution semantics; routing narrowing reuses the frozen pin-narrowing machinery). PR left open for the human merge gate.

kilo added 1 commit

2026-09-26 23:58:41 +00:00

feat: logical model resolution + adoption-aware discovery (D-055, #134 ) 8c3dd674c9

Bare physical-model ids become a third model-field reading on the
execution surface: sr-pin: -> alias -> logical model -> model_not_found.
A logical request resolves to the EXACT (provider, model) identity and
rides the routing core's existing explicit-model/variant narrowing, so
normal scarcity policy competes only the resources providing exactly
that identity — no substitution, no engine changes.

- reasoning effort is exact: unsupported_reasoning_effort for a variant
  the identity lacks; reasoning_effort_required when omitted and several
  calibrated variants exist; a max-only family's single legal effort
  (max, D-054) is used when omitted; ambiguous_logical_model when two
  providers carry the slug
- GET /v1/models lists aliases first, then exposed logical models
  (catalog identity bound by >=1 registered resource; empty deployment
  exposes nothing; restricted/unclassified never appear) with additive
  x_scarcity_router metadata: kind, provider, reasoning_efforts,
  effective_context_limit_tokens (model/channel intersection, null when
  the channel ceiling is unknown), max_output_tokens
- alias collisions are explicit: alias precedence, single entry flagged
  logical_model_shadowed
- D-055 recorded in docs/decisions.md; execution-surface model
  resolution + error table amended in place
- representative fixture pins for failure 4 flipped (bare model routes;
  unknown stays 404); the #135/#136/#137 pins are untouched

Known-load flake in the pre-existing composed cancellation e2e
(test_scenario_11) is unrelated to this diff and filed as #143.

kilo referenced this pull request

2026-09-26 23:59:27 +00:00

Representative-client fixture + current-state boundary pins (#133) #142

kilo referenced this pull request

2026-09-27 00:38:26 +00:00

Bounded reasoning dialect normalization (#135) #145

kilo commented

2026-09-27 00:39:11 +00:00

Author

Member

Independent review (GLM-5.3-Flash, fresh reviewer context) of reviewed_head 8c3dd674c97ea314c0fb9cfe7847ebe3b1e73676 (diff 8586320..8c3dd67, the approved #142 head + this PR's single commit) — VERDICT: APPROVE.

Invariant verification (all confirmed with file:line evidence):

No cross-model substitution — logical requests ride RequestBinding(explicit_model, explicit_variant) into the routing core's pre-existing exact narrowing (routing_core.py:2548-2568); same-identity resources still compete (qualified_by_identity, selected_gates by _order_key, runner-ups in target_alternatives); the no-alternatives branch fires only for resource-id pins. routing_core.py has an EMPTY diff.
No effort downgrade — an unoffered effort raises 400 unsupported_reasoning_effort before routing/dispatch and is audited rejected with executed_target=None; omitted effort uses the single calibrated variant or reasoning_effort_required; D-054 max-only case pinned.
Exposure honesty — restricted/unclassified never reach adoption (no registrations, no catalog entries; base catalog has no daybreak entry); empty deployment exposes nothing; ambiguous slugs skipped; context metadata is the model∩known-channel intersection with UNKNOWN → null.
Backward compatibility — pin/alias branches byte-equivalent; no-catalog behavior preserved; the two old-test edits are contract-change-justified, not weakened.
Flip coordination with #142 review executed exactly (#134 pins flipped; #135/#136/#137 untouched; #137 docstring-only rewording).
Docs — D-055 complete with alternatives + explicit D-042 reconciliation; error table matches implementation.
Scope — exactly the 9 frozen files; no routing-core/worker/adapter/auth changes.

Findings (none blocking):

DEFER — exposed_logical_models relies on the adoption gate + owner-reviewed catalog to exclude restricted entries (true today); a defense-in-depth classification guard could be considered if the catalog ever gains a restricted-track entry.
DEFER — exposure advertises bound-identity variants while resolution reads catalog-wide variants: a bound-model/unbound-variant edge advertises fewer efforts than resolvable (conservative direction, no action required).
DEFER — comment nit: "before any admission I/O" precedes only routing/dispatch, not the in-memory snapshot fetch.
Hygiene note — an untracked child-C WIP file existed in the shared tree during review; verified NOT attributable to this head (pure checkout of 8c3dd67 is 0/0/0). Child C (#135, PR #145) owns it.

Reviewer gates: pure-checkout basedpyright 0/0/0; 122 focused tests OK; exactly one commit in range; git diff --check clean; /v1/models remains authenticated. UX impact: positive (bare model ids usable, typed actionable errors, honest discovery metadata, visible alias shadowing; no regression for pin/alias/unknown flows).

Independent review (GLM-5.3-Flash, fresh reviewer context) of reviewed_head `8c3dd674c97ea314c0fb9cfe7847ebe3b1e73676` (diff `8586320..8c3dd67`, the approved #142 head + this PR's single commit) — **VERDICT: APPROVE**. Invariant verification (all confirmed with file:line evidence): 1. **No cross-model substitution** — logical requests ride `RequestBinding(explicit_model, explicit_variant)` into the routing core's pre-existing exact narrowing (`routing_core.py:2548-2568`); same-identity resources still compete (`qualified_by_identity`, `selected_gates` by `_order_key`, runner-ups in `target_alternatives`); the no-alternatives branch fires only for resource-id pins. `routing_core.py` has an EMPTY diff. 2. **No effort downgrade** — an unoffered effort raises 400 `unsupported_reasoning_effort` before routing/dispatch and is audited `rejected` with `executed_target=None`; omitted effort uses the single calibrated variant or `reasoning_effort_required`; D-054 max-only case pinned. 3. **Exposure honesty** — restricted/unclassified never reach adoption (no registrations, no catalog entries; base catalog has no daybreak entry); empty deployment exposes nothing; ambiguous slugs skipped; context metadata is the model∩known-channel intersection with UNKNOWN → null. 4. **Backward compatibility** — pin/alias branches byte-equivalent; no-catalog behavior preserved; the two old-test edits are contract-change-justified, not weakened. 5. **Flip coordination** with #142 review executed exactly (#134 pins flipped; #135/#136/#137 untouched; #137 docstring-only rewording). 6. **Docs** — D-055 complete with alternatives + explicit D-042 reconciliation; error table matches implementation. 7. **Scope** — exactly the 9 frozen files; no routing-core/worker/adapter/auth changes. Findings (none blocking): - DEFER — `exposed_logical_models` relies on the adoption gate + owner-reviewed catalog to exclude restricted entries (true today); a defense-in-depth classification guard could be considered if the catalog ever gains a restricted-track entry. - DEFER — exposure advertises bound-identity variants while resolution reads catalog-wide variants: a bound-model/unbound-variant edge advertises fewer efforts than resolvable (conservative direction, no action required). - DEFER — comment nit: "before any admission I/O" precedes only routing/dispatch, not the in-memory snapshot fetch. - Hygiene note — an untracked child-C WIP file existed in the shared tree during review; verified NOT attributable to this head (pure checkout of `8c3dd67` is 0/0/0). Child C (#135, PR #145) owns it. Reviewer gates: pure-checkout `basedpyright` 0/0/0; 122 focused tests OK; exactly one commit in range; `git diff --check` clean; `/v1/models` remains authenticated. **UX impact: positive** (bare model ids usable, typed actionable errors, honest discovery metadata, visible alias shadowing; no regression for pin/alias/unknown flows).

adrian.tkacz changed target branch from compat/representative-client-fixture to develop

2026-09-27 15:45:19 +00:00

adrian.tkacz approved these changes

2026-09-27 15:45:36 +00:00

adrian.tkacz added 1 commit

2026-09-27 15:45:41 +00:00

Merge branch 'develop' into compat/logical-model-resolution

ci / check (pull_request) Successful in 7m40s

Details

1599cbaae0

adrian.tkacz merged commit a579899a75 into develop

2026-09-27 15:46:48 +00:00