C. Bounded reasoning dialect normalization #135

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

Scope (frozen)

Accept, normalize once into the canonical request representation, and document:

reasoning_effort: "<effort>" (existing; vocabulary minimal|low|medium|high|xhigh|max|ultra unchanged);
reasoning: {"effort": "<effort>"} — closed object: effort only; unknown keys inside rejected;
thinking: {"type": "enabled"|"disabled"} — closed object: type only;
enable_thinking: true|false.

Semantics:

Direct effort-bearing forms (reasoning_effort, reasoning.effort) must agree when more than one is present; contradiction → typed 400 with an explicit conflict code (additive to the closed error vocabulary; documented).
Enable/disable forms are consistency assertions, not effort selectors: enabled + explicit effort is consistent; a disabled flag plus a present effort is a conflict (typed 400); contradictory flags between themselves are a conflict.
Only a generic enabled flag and no effort → fail explicitly (cannot determine effort without guessing); no guessing, ever.
Routing and adapters see ONE canonical reasoning intent (reasoning_effort); requires_reasoning_controls follows the normalized intent; normalization is model-independent (pure on the request).
D-054 intact: nothing here reintroduces non-max efforts for max-only light families; a normalized max for Luna flows exactly as reasoning_effort: "max" does today.
Unknown top-level keys remain unknown_parameter; arbitrary nested provider objects remain rejected.

Reconcile stale execution-surface documentation with the current effort vocabulary in code (docs say minimal..high; code accepts ..xhigh|max|ultra) in the same PR — docs must not lag the contract.

Tests

Exact real ZCode dialect (all four forms, effort=max) normalizes to max; each supported individual dialect; agreeing duplicates; conflicting efforts; disabled-vs-effort conflicts; conflicting flags; enabled-only (explicit failure); unknown nested keys rejected; non-max dialect on a max-only family still fails at the family boundary (no new leak); malformed shapes (wrong types) rejected; requires_reasoning_controls still set for the representative request.

Non-goals

No new dialect families beyond the evidenced set; no provider-passthrough; no limits/model-resolution changes; no adapter changes.

Complexity boundary

gateway_openai.py (parse + normalization), gateway_contracts.py (error code), docs/execution-surface.md; test files: test_gateway_contracts.py/new focused file + child-A fixture flip. Budget: 90 min wall clock.

Acceptance

Full gate green; representative fixture's reasoning-dialect pin flipped to the new contract; other child-A pins untouched; PR open for human review; not merged.

Child C of #132. Keep strict parsing; add an explicit, bounded compatibility normalization layer for a small evidenced set of reasoning representations (observed verbatim in the 2026-09-26 ZCode capture). ## Scope (frozen) Accept, normalize once into the canonical request representation, and document: - `reasoning_effort: "<effort>"` (existing; vocabulary `minimal|low|medium|high|xhigh|max|ultra` unchanged); - `reasoning: {"effort": "<effort>"}` — closed object: `effort` only; unknown keys inside rejected; - `thinking: {"type": "enabled"|"disabled"}` — closed object: `type` only; - `enable_thinking: true|false`. Semantics: - Direct effort-bearing forms (`reasoning_effort`, `reasoning.effort`) must agree when more than one is present; contradiction → typed 400 with an explicit conflict code (additive to the closed error vocabulary; documented). - Enable/disable forms are consistency assertions, not effort selectors: `enabled` + explicit effort is consistent; a disabled flag plus a present effort is a conflict (typed 400); contradictory flags between themselves are a conflict. - Only a generic enabled flag and no effort → fail explicitly (cannot determine effort without guessing); no guessing, ever. - Routing and adapters see ONE canonical reasoning intent (`reasoning_effort`); `requires_reasoning_controls` follows the normalized intent; normalization is model-independent (pure on the request). - **D-054 intact:** nothing here reintroduces non-max efforts for max-only light families; a normalized `max` for Luna flows exactly as `reasoning_effort: "max"` does today. - Unknown top-level keys remain `unknown_parameter`; arbitrary nested provider objects remain rejected. Reconcile stale execution-surface documentation with the current effort vocabulary in code (docs say `minimal..high`; code accepts `..xhigh|max|ultra`) in the same PR — docs must not lag the contract. ## Tests Exact real ZCode dialect (all four forms, effort=max) normalizes to `max`; each supported individual dialect; agreeing duplicates; conflicting efforts; disabled-vs-effort conflicts; conflicting flags; enabled-only (explicit failure); unknown nested keys rejected; non-`max` dialect on a max-only family still fails at the family boundary (no new leak); malformed shapes (wrong types) rejected; `requires_reasoning_controls` still set for the representative request. ## Non-goals No new dialect families beyond the evidenced set; no provider-passthrough; no limits/model-resolution changes; no adapter changes. ## Complexity boundary `gateway_openai.py` (parse + normalization), `gateway_contracts.py` (error code), `docs/execution-surface.md`; test files: `test_gateway_contracts.py`/new focused file + child-A fixture flip. Budget: 90 min wall clock. ## Acceptance Full gate green; representative fixture's reasoning-dialect pin flipped to the new contract; other child-A pins untouched; PR open for human review; not merged.