fix(proxy): enforce OpenSpec architecture ratchets

[mastertyko]

Summary

Restore the normative proxy architecture ratchets and make OpenSpec the single source of truth for every numeric limit enforced by the architecture checker. The runtime refactor is behavior-neutral: it moves cohesive service and model-eligibility helpers behind existing compatibility façades so service.py and load_balancer.py fit their accepted limits again.

Type of change

• fix: — bug fix (no behavior change beyond the bug)
• feat: — new user-facing feature or capability
• refactor: — internal refactor (no behavior change, no API change)
• docs: — documentation only
• chore: / ci: / build: — tooling, CI, packaging
• test: — test-only change
• Breaking change

Linked issue: None; this does not claim to resolve an existing issue. Related PRs are documented below.

OpenSpec

• This PR includes / updates an OpenSpec change
• Not applicable — bug fix that matches the existing spec
• Not applicable — docs / CI / chore only
• This PR touches a codex-faithful path and preserves upstream-equivalent behavior

Change directory: openspec/changes/archive/2026-08-23-enforce-proxy-architecture-ssot/

Changes

• Define all six proxy architecture ratchets once in a marked TOML block in the normative proxy-architecture spec, and load that block with strict fail-closed validation.
• Restore service.py to 2,594 lines and load_balancer.py to 3,008 lines while keeping LoadBalancer.select_account() at 478 lines.
• Move API-key lease estimates and model/additional-quota eligibility into focused private modules while preserving façade imports and registry monkeypatch seams.
• Add regressions for OpenSpec-owned thresholds, malformed or invalid definitions, deterministic multi-failure reporting, and service façade compatibility.

Related work

• refactor(proxy): restore architecture ratchets #1430 previously restored the intended ratchets; ci(proxy): realign architecture ratchets with main #1435 later raised checker-only values while the normative spec stayed unchanged.
• fix(db): persist security lineage markers #1183 proposes raising the checker limits further. This PR instead enforces the existing normative contract, so it is not a prerequisite and points in an incompatible direction.
• feat(accounts): add per-account usage limits #1528 changes broader load-balancer behavior. It overlaps the file but not this PR's behavior-neutral eligibility extraction, so the concerns remain independently reviewable.
• test(sim): deterministic proxy turn-lifecycle simulation harness #1647, fix(proxy): stop hard bridge keys wedging on a leaked half-open probe and a rejected continuity anchor #1857, fix(proxy): settle keyed mid-loop health after reservation #1861, and fix(proxy): recover stale previous response anchors #1863 overlap touched files but not the extracted symbols or the OpenSpec/checker contract.

Test plan

Passed:

uv run python scripts/check_proxy_architecture.py
# proxy architecture checks passed

uv run pytest -q tests/unit/test_check_proxy_architecture.py tests/unit/test_proxy_api_key_usage.py tests/unit/test_http_bridge_idle_leases.py
# 43 passed

uv run pytest -q tests/unit/test_load_balancer.py
# 257 passed

uv run pytest -q tests/unit/test_proxy_load_balancer_refresh.py
# 87 passed, 3 skipped

uv run pytest -q tests/unit/test_load_balancer_concurrency.py
# 121 passed

uv run pytest -q tests/integration/test_http_responses_bridge.py::test_v1_responses_http_bridge_reuses_quota_admitted_spark_then_rejects_current_plan_change
# 1 passed

openspec validate enforce-proxy-architecture-ssot --type change --strict --no-interactive
openspec validate proxy-architecture --type spec --strict --no-interactive
# both valid before archiving the completed change

git diff --check
# passed

Ruff check and format --check, plus ty check, passed for model_eligibility.py, load_balancer.py, _service/api_key_usage.py, service.py, check_proxy_architecture.py, test_check_proxy_architecture.py, and test_proxy_api_key_usage.py.

The repository-wide openspec validate --specs --no-interactive sweep was also run. The affected proxy-architecture spec passes, while the sweep still reports seven failures in unchanged specs: database-backends, frontend-architecture, model-catalog-compat, query-caching, responses-api-compat, usage-error-metrics, and usage-refresh-policy.

Full local CI was intentionally not run; required GitHub CI is the integration gate for this focused routing-sensitive change.

Checklist

• Title is in Conventional Commits format (<type>(<scope>)?: <subject>).
• Related issues and PRs are documented above; no issue closure is claimed.
• Added or updated tests covering the change.
• Ran the relevant lint, type, architecture, unit, and focused integration subsets locally.
• The scoped OpenSpec change and affected main spec pass strict validation; verification is clean and the change is archived.
• Repository-wide openspec validate --specs passes (seven unchanged specs still fail, as documented above).
• Simplicity gates reviewed: no setting, default, setup step, README section, .env.example, dashboard navigation, or user-visible surface changed.
• CHANGELOG.md is not edited by hand.
• Screenshots are not applicable because there is no dashboard-visible change.

Summary by CodeRabbit

• New Features

  • Improved model eligibility and quota-aware account selection.
  • Added request-based API-key usage estimation with sensible defaults and maximum limits.
  • Centralized proxy architecture thresholds in the specification.

• Bug Fixes

  • Architecture checks now validate threshold definitions and fail safely when they are invalid.
  • Preserved existing proxy service compatibility while reorganizing eligibility and usage logic.

• Tests

  • Expanded coverage for quota eligibility, usage estimation, threshold validation, and compatibility behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9daf6341-8103-46e6-9b82-90677375d24d

📥 Commits

Reviewing files that changed from the base of the PR and between d4b00fd and ac1300d.

📒 Files selected for processing (14)

• app/modules/proxy/_load_balancer/model_eligibility.py
• app/modules/proxy/_service/api_key_usage.py
• app/modules/proxy/load_balancer.py
• app/modules/proxy/service.py
• openspec/changes/archive/2026-08-23-enforce-proxy-architecture-ssot/.openspec.yaml
• openspec/changes/archive/2026-08-23-enforce-proxy-architecture-ssot/design.md
• openspec/changes/archive/2026-08-23-enforce-proxy-architecture-ssot/proposal.md
• openspec/changes/archive/2026-08-23-enforce-proxy-architecture-ssot/specs/proxy-architecture/spec.md
• openspec/changes/archive/2026-08-23-enforce-proxy-architecture-ssot/tasks.md
• openspec/specs/proxy-architecture/context.md
• openspec/specs/proxy-architecture/spec.md
• scripts/check_proxy_architecture.py
• tests/unit/test_check_proxy_architecture.py
• tests/unit/test_proxy_api_key_usage.py

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change extracts proxy eligibility and lease-estimation helpers, preserves façade delegation, and moves architecture thresholds into validated OpenSpec TOML consumed by the architecture checker.

Changes

Proxy runtime helper extraction

Layer / File(s)	Summary
Model and quota eligibility module app/modules/proxy/_load_balancer/model_eligibility.py	Adds model and tier normalization, catalog-aware account filtering, catalog-omission admission, registry detection, quota-history retrieval, plan applicability, freshness handling, and exhaustion evaluation.
Facade delegation and lease estimation app/modules/proxy/load_balancer.py, app/modules/proxy/_service/api_key_usage.py, app/modules/proxy/service.py, tests/unit/test_proxy_api_key_usage.py	Delegates load-balancer eligibility operations to the new module. Adds bounded lease-token estimation helpers and tests while preserving service façade access.

Architecture threshold source of truth

Layer / File(s)	Summary
Normative threshold policy openspec/changes/archive/2026-08-23-enforce-proxy-architecture-ssot/*, openspec/specs/proxy-architecture/*	Defines the OpenSpec-owned threshold block, validation rules, compatibility requirements, implementation plan, and verification scenarios.
Threshold loading and checker integration scripts/check_proxy_architecture.py	Loads and validates six positive-integer thresholds from the specification. Uses valid values for size checks and reports loading failures.
Threshold validation coverage tests/unit/test_check_proxy_architecture.py	Tests threshold binding, invalid definitions, malformed TOML, duplicate markers, encoding failures, and continued unrelated checks.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to ac130

The PR restores documented proxy architecture limits and preserves runtime compatibility, with the affected validations and focused tests passing. No actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: soju06

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: enforcing proxy architecture ratchets from the OpenSpec specification.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[mastertyko]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: ac1300d210

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".