D. Gateway effective limits + Codex output-token semantics

kilo commented

2026-09-26 21:43:45 +00:00

Member

Child D of #132. Fix the product problem where a normal supported model is unusable because an invisible generic ceiling sits far below evidenced capability — without removing safeguards. Covers program workstreams "gateway/effective limits" and "Codex output-token semantics" (#132 items 3 and 6).

Scope (frozen)

Effective capability model: effective = intersection(model hard capability, execution-channel capability, administrator ceiling). Administrator ceilings stay authoritative and bounded; no client request may increase any limit; enforcement stays rejection-based (never silent clipping).
Honest defaults for the supported coding-agent workload, chosen with evidence and documented: max_output_tokens 16384 cripples 128k-output models; max_input_context_tokens 131072 and the 1 MiB body cap strangle real agent conversations; 300 s execution time is tight for max-effort reasoning turns. New defaults must not silently cripple evidenced capability without the operator knowingly choosing that policy — and the operator must be able to SEE the effective numbers.
Codex output-token semantics (honest): first inspect the CURRENT Codex App Server contract for a supported output-limit control (do not assume the 2026-09-20 evidence). If a supported control exists — map, verify, record evidence. If not: a requested output limit may be normalized away ONLY when it is ≥ the proven hard maximum of the exact selected model (catalog hard_properties.output_tokens); a smaller requested limit must fail closed (output_limit_unenforceable-class typed error) rather than be silently ignored; UNKNOWN hard max means no normalization. Arbitrary generation_params stay fail-closed.
Context re-evidence: re-evidence the CURRENT Codex channel context ceiling before touching the 272000 claim. The client-visible effective context is the real intersection; never advertise what the path cannot execute.
Limits visibility: limits and effective per-model numbers are visible to the operator (child H builds the full surface; this child exposes the data) and inside x_scarcity_router model metadata (child B). Configuration export represents non-default limits honestly; changes validated before persistence.

Tests

Default supported-model request accepted; explicit lower administrator ceiling enforced; large-but-bounded request accepted; over-limit rejection unchanged; channel capability < model capability → effective value enforced and advertised; non-binding normalization above proven hard max (normalized + audited); binding-below-hard-max rejected closed; UNKNOWN hard max never normalized; body/limit boundary tests; export honesty.

Non-goals

No limits removed; no unbounded values; no tool-call work (child E); no admin UI redesign (child H consumes this).

Complexity boundary

gateway_contracts.py, gateway_coordinator.py, execution_sources.py/resource_state.py (capability plumbing), worker_codex_adapter.py (output-limit semantics only), defaults + config validation; evidence notes in the Codex evidence doc; ~3–5 test files. Budget: 120 min wall clock. Reuses child E's App-Server inspection where it covers output limits.

Acceptance

Full gate green; child-A output-limit pin flipped to the new contract; representative request passes the limits gate; PR open for human review; not merged.

Child D of #132. Fix the product problem where a normal supported model is unusable because an invisible generic ceiling sits far below evidenced capability — without removing safeguards. Covers program workstreams "gateway/effective limits" and "Codex output-token semantics" (#132 items 3 and 6). ## Scope (frozen) 1. **Effective capability model:** `effective = intersection(model hard capability, execution-channel capability, administrator ceiling)`. Administrator ceilings stay authoritative and bounded; no client request may increase any limit; enforcement stays rejection-based (never silent clipping). 2. **Honest defaults** for the supported coding-agent workload, chosen with evidence and documented: `max_output_tokens` 16384 cripples 128k-output models; `max_input_context_tokens` 131072 and the 1 MiB body cap strangle real agent conversations; 300 s execution time is tight for max-effort reasoning turns. New defaults must not silently cripple evidenced capability without the operator knowingly choosing that policy — and the operator must be able to SEE the effective numbers. 3. **Codex output-token semantics (honest):** first inspect the CURRENT Codex App Server contract for a supported output-limit control (do not assume the 2026-09-20 evidence). If a supported control exists — map, verify, record evidence. If not: a requested output limit may be normalized away ONLY when it is ≥ the proven hard maximum of the exact selected model (catalog `hard_properties.output_tokens`); a smaller requested limit must fail closed (`output_limit_unenforceable`-class typed error) rather than be silently ignored; UNKNOWN hard max means no normalization. Arbitrary `generation_params` stay fail-closed. 4. **Context re-evidence:** re-evidence the CURRENT Codex channel context ceiling before touching the 272000 claim. The client-visible effective context is the real intersection; never advertise what the path cannot execute. 5. **Limits visibility:** limits and effective per-model numbers are visible to the operator (child H builds the full surface; this child exposes the data) and inside `x_scarcity_router` model metadata (child B). Configuration export represents non-default limits honestly; changes validated before persistence. ## Tests Default supported-model request accepted; explicit lower administrator ceiling enforced; large-but-bounded request accepted; over-limit rejection unchanged; channel capability < model capability → effective value enforced and advertised; non-binding normalization above proven hard max (normalized + audited); binding-below-hard-max rejected closed; UNKNOWN hard max never normalized; body/limit boundary tests; export honesty. ## Non-goals No limits removed; no unbounded values; no tool-call work (child E); no admin UI redesign (child H consumes this). ## Complexity boundary `gateway_contracts.py`, `gateway_coordinator.py`, `execution_sources.py`/`resource_state.py` (capability plumbing), `worker_codex_adapter.py` (output-limit semantics only), defaults + config validation; evidence notes in the Codex evidence doc; ~3–5 test files. Budget: 120 min wall clock. Reuses child E's App-Server inspection where it covers output limits. ## Acceptance Full gate green; child-A output-limit pin flipped to the new contract; representative request passes the limits gate; PR open for human review; not merged.

adrian.tkacz referenced this issue from a commit

2026-09-26 22:01:07 +00:00

test: representative-client fixture + current-state boundary pins (#133)

kilo referenced this issue

2026-09-26 22:01:25 +00:00

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

kilo referenced this issue

2026-09-27 16:21:42 +00:00

Harness-independent execution backend: architecture boundary, semantic harness contract and local-transport policy (D-056, program #132) #146

kilo referenced this issue

2026-09-27 16:35:19 +00:00

Harness-independent execution backend architecture (D-056, #146) #147

adrian.tkacz referenced this issue from a commit

2026-09-27 18:08:57 +00:00

docs: remediate D-056 review findings (PR #147)

kilo referenced this issue

2026-09-27 18:19:40 +00:00

Harness-independent execution backend architecture (D-056, #146) #147

kilo referenced this issue

2026-09-27 21:01:22 +00:00

Representative-client compatibility + operations hardening program (ZCode acceptance follow-up) #132

kilo commented

2026-09-27 21:01:48 +00:00

Author

Member

Additive scope note (D-056, PR #147 — frozen scope text above unchanged):

D-056 pt 6 names this child as the implementer of the effective-capability intersection's limits dimensions and assigns it one question the frozen scope above does not yet cover:

Per-route facts vs model-level advertising. effective(route) = model hard capability ∩ execution-source/channel capability ∩ administrator allowance is a per-route fact, and admission stays route-specific — but multiple routes serving the SAME logical model may have different effective context or output ceilings. This child must settle how those per-route facts are represented honestly at model-discovery level (GET /v1/models / x_scarcity_router metadata, consumed by child H), without: advertising the strongest route's ceiling as if every route supports it; unnecessarily constraining a request that a stronger route could satisfy (aggregating to the weakest route is not automatically correct); or converting UNKNOWN evidence into a known value (UNKNOWN → null in metadata, fail-closed in admission — D-055's effective_context_limit_tokens is the precedent).
The client-request requirement layer may only narrow eligibility, never expand capability (D-042); a model-catalog maximum is never evidence that an execution source provides it.

Authoritative text: D-056 pt 6 in docs/decisions.md; "Effective capability (D-056; architecture for #136)" in docs/execution-surface.md and docs/architecture.md.

Additive scope note (D-056, PR #147 — frozen scope text above unchanged): D-056 pt 6 names this child as the implementer of the effective-capability intersection's limits dimensions and assigns it one question the frozen scope above does not yet cover: - **Per-route facts vs model-level advertising.** `effective(route) = model hard capability ∩ execution-source/channel capability ∩ administrator allowance` is a per-route fact, and admission stays route-specific — but multiple routes serving the SAME logical model may have different effective context or output ceilings. This child must settle how those per-route facts are represented honestly at model-discovery level (`GET /v1/models` / `x_scarcity_router` metadata, consumed by child H), without: advertising the strongest route's ceiling as if every route supports it; unnecessarily constraining a request that a stronger route could satisfy (aggregating to the weakest route is not automatically correct); or converting UNKNOWN evidence into a known value (UNKNOWN → `null` in metadata, fail-closed in admission — D-055's `effective_context_limit_tokens` is the precedent). - The client-request requirement layer may only narrow eligibility, never expand capability (D-042); a model-catalog maximum is never evidence that an execution source provides it. Authoritative text: D-056 pt 6 in `docs/decisions.md`; "Effective capability (D-056; architecture for #136)" in `docs/execution-surface.md` and `docs/architecture.md`.

kilo referenced this issue

2026-09-27 21:01:49 +00:00

H. Administrator UX cleanup (derived resources, honest counters, revoked-worker deletion, limits + client integration) #140

kilo referenced this issue

2026-09-28 00:12:18 +00:00

Reuse-first reconstruction program: refreshed audit matrix (Stage A) #150

adrian.tkacz referenced this issue from a commit

2026-09-28 00:31:32 +00:00

feat: gateway effective limits + Codex output-token semantics (D-057, #136)

kilo referenced this issue from a pull request that will close it,

2026-09-28 00:31:54 +00:00

Gateway effective limits + Codex output-token semantics (D-058, #136) #152