Campaign map: structure-first deep modules v2 & subscription providers

[NOirBRight]

Notes

Campaign: Structure-first Deep Modules v2 & Subscription Providers.
Label: campaign:deep-modules-2.

Successor to the structural track of #441 (Gateway deep modules & Codex↔Chat). #441's Track 0 (0.1.9 closeout) and WP7 (Chat release gate) remain owned by #441; this map owns everything structural that #441's WP1–WP3 extraction did not finish, plus the subscription-provider work that rides on it.

Why a v2

The #413/#414 extraction moved code out but left three constraints that pin the monolith:

1. Test surface pins the facade — test_routing.py (30,372 lines) calls CodexProxyHandler private methods; the handler cannot change shape while a third of the test corpus does this.
2. Frozen re-export surface pins module boundaries — FROZEN_CODEX_PROXY_NAMES forces extracted modules to re-export through codex_proxy, with a late-import cycle workaround (~line 9704).
3. Rust side untouched — gateway.rs at 15,279 lines; only telemetry extracted; ADR-0004 cites it by line number.

Ordering principle: release the constraints, migrate the test surface, then slim the handler. Subscription providers are not a separate campaign: the credential seam lands during handler slimming, and XAI OAuth is its second adapter (the proof the seam is real).

Hard gates

1. Stage 1 → Stage 2 → Stage 3 are strictly serial (constraints must be released before migration; migration before slimming).
2. Stage 4 (Rust) may run parallel to Stages 2–3.
3. Stage 5 is closeout only (Stage 5B: Split runtime_tool_compatibility.py into dispositions core / V1 / V2 / contract tables #456 tool-compatibility split), blocked by Stage 1A (deferred_core is bypassed by runtime tool planning and expands namespace children #425).
4. codex_proxy.py stays the process entry. Extracted modules must not import it. Official passthrough unchanged. No hidden fallback (per Campaign map: Gateway deep modules & Codex↔Chat #441 / ADR-0002).
5. Anthropic Messages upstream (Implement and qualify Anthropic Messages as a Gateway upstream protocol #246) is out of this campaign and remains an independent ticket. Anthropic subscription OAuth is permanently out of product scope (ToS). Cursor is parked (ToS; only legit surface is an agent harness, conflicting with Gateway identity) — a note in the AgentProvider roadmap doc, no ticket.

Acceptance for "campaign done"

• codex_proxy.py is a process entry only (≤ ~1k lines); deletion test passes (removing the facade scatters no complexity back to callers).
• No module imports codex_proxy; FROZEN_CODEX_PROXY_NAMES is empty and its contract test deleted.
• Tests cross public interfaces only; test_routing.py no longer exists (fully migrated).
• gateway.rs decomposed so no ADR needs line-number references.
• Adding a Provider/credential type = adding one adapter; no enum-branch edits (XAI is the acceptance case).

Decisions-so-far

• Integration closeout merged to main at bd23c2e (integration/deep-modules-2). Repair list: catalog auth binds through provider_auth_mode (no provider_id == "xai" branch); xAI session is file-authoritative; tests/test_seam_discipline.py gates codex_proxy._* / CodexProxyHandler.__new__; tool_compatibility is bundled. Follow-ups: Adapterize remaining codex_auth identity-header branch in gateway transport #457 (codex_auth identity-header adapterization), Clear Linux-host Rust test failures and split config.rs past 3k lines #458 (Linux Rust host failures + config.rs size + clippy unused Windows items), Qualify live SuperGrok / xAI OAuth through the Gateway #459 (live SuperGrok qualification).
• Stage 3C (Stage 3C: XAI subscription provider — OAuth device-code adapter, login UI, qualification #454) finished at 89fe17d: XaiOauthAdapter is credential seam Fix Gateway client default model fallback ordering #2; xai provider + device-code UI; live SuperGrok CLI qualification still pending.
• Stage 2A (Stage 2A: Migrate test_routing.py to seam-level tests and shrink FROZEN_CODEX_PROXY_NAMES in lockstep #451) finished at c8033b0: test_routing.py and the frozen facade pin are deleted.
• Stage 3B (Stage 3B: SubscriptionCredential seam — generalize codex_auth behind one credential interface (ADR) #453) finished at 24b9dca: ADR-0005 + subscription_credential registry; codex_auth is adapter Add Windows auto-update support #1; upstream_headers dispatches through credential_for().
• Stage 5B (Stage 5B: Split runtime_tool_compatibility.py into dispositions core / V1 / V2 / contract tables #456) finished at 55eb3ed: tool_compatibility/ isolates V1 repair from V2 adaptation; package files stay under 2k lines.
• Stage 3A (Stage 3A: Reduce CodexProxyHandler to thin dispatch and remove the late-import cycle #452) finished at bfea444: codex_proxy.py is 242-line HTTP dispatch; admission in gateway_admission.py; late route_plan import removed. Python core 2003 passed / 109 skipped.
• Stage 4A (Stage 4A: Decompose gateway.rs along injection-descriptor seams #455) finished at 3376735: gateway.rs is now gateway/mod.rs plus inject/backup/isolated/tests; no gateway file exceeds 3k.
• CI note: GitHub Actions is disabled (verification-policy.md); "Linux parity" means the local verification matrix gains Linux full-suite commands, not a hosted CI job.
• Credential seam: SubscriptionCredential interface = access_token() / account headers / refresh() / persistence. codex_auth becomes adapter Add Windows auto-update support #1, XAI OAuth adapter Fix Gateway client default model fallback ordering #2. New ADR required.
• XAI upstream is Responses-compatible → zero protocol-translation work; known 403 OAuth allowlist gating → keep XAI_API_KEY fallback path.
• Test migration and frozen-surface shrinking are one motion: every migrated block deletes its re-exports from FROZEN_CODEX_PROXY_NAMES in the same PR.
• Implement and qualify Anthropic Messages as a Gateway upstream protocol #246 (Anthropic Messages upstream) is not a campaign child. Claude protocol work stays on its own ticket.

Fog

• Whether test_routing.py migration surfaces behavior that only exists via private-method setup (would need harness extensions).
• Exact tranche boundaries for Stage 2 (by handler topic vs by seam module).
• Whether proxy.rs platform layering lands in this campaign or is deferred to a Linux-hardening follow-up.
• Version number that ships the XAI provider.

Work packages

Stage 1 — release the constraints

• 1A. deferred_core is bypassed by runtime tool planning and expands namespace children #425 deferred_core bypass fix (existing P1 bug; ADR-0002 baseline)
• 1B. Stage 1B: HTTP-level black-box characterization harness for the Gateway #449 HTTP-level black-box characterization harness
• 1C. Stage 1C: Linux parity in the local verification matrix #450 Linux parity in the local verification matrix
• 1D. Verification-policy rule: new tests must not import handler privates (doc change, lands with Stage 1B: HTTP-level black-box characterization harness for the Gateway #449)

Stage 2 — test-surface migration + frozen-surface shrink

• 2A. Stage 2A: Migrate test_routing.py to seam-level tests and shrink FROZEN_CODEX_PROXY_NAMES in lockstep #451 Migrate test_routing.py to seam-level tests; shrink FROZEN_CODEX_PROXY_NAMES in lockstep

Stage 3 — handler slimming + credential seam (XAI rides here)

• 3A. Stage 3A: Reduce CodexProxyHandler to thin dispatch and remove the late-import cycle #452 CodexProxyHandler → thin dispatch; late-import cycle removed
• 3B. Stage 3B: SubscriptionCredential seam — generalize codex_auth behind one credential interface (ADR) #453 SubscriptionCredential seam + ADR; codex_auth as adapter Add Windows auto-update support #1
• 3C. Stage 3C: XAI subscription provider — OAuth device-code adapter, login UI, qualification #454 XAI subscription provider: OAuth device-code adapter Fix Gateway client default model fallback ordering #2 + UI + qualification

Stage 4 — Rust decomposition (parallel to 2–3)

• 4A. Stage 4A: Decompose gateway.rs along injection-descriptor seams #455 gateway.rs split along injection-descriptor seams (Declarative per-client injection descriptor (managed-client adapter seam) #432 direction)

Stage 5 — closeout

• 5B. Stage 5B: Split runtime_tool_compatibility.py into dispositions core / V1 / V2 / contract tables #456 runtime_tool_compatibility.py split: dispositions core / V1 / V2 / contract tables

Child tickets

• deferred_core is bypassed by runtime tool planning and expands namespace children #425 (existing)
• Stage 1B: HTTP-level black-box characterization harness for the Gateway #449, Stage 1C: Linux parity in the local verification matrix #450, Stage 2A: Migrate test_routing.py to seam-level tests and shrink FROZEN_CODEX_PROXY_NAMES in lockstep #451, Stage 3A: Reduce CodexProxyHandler to thin dispatch and remove the late-import cycle #452, Stage 3B: SubscriptionCredential seam — generalize codex_auth behind one credential interface (ADR) #453, Stage 3C: XAI subscription provider — OAuth device-code adapter, login UI, qualification #454, Stage 4A: Decompose gateway.rs along injection-descriptor seams #455, Stage 5B: Split runtime_tool_compatibility.py into dispositions core / V1 / V2 / contract tables #456 (created with this map)

Native blocked-by edges: #451←#449, #452←#451, #453←#451, #454←#453, #456←#425.

#246 was removed from this campaign on 2026-08-23 and remains independently open.

[NOirBRight]

Decision: #246 is out of this campaign. Stage 5 is closeout only (#456). Native blocked-by 246←452 deleted.