Findings: routing-adapters-models (8, health: adequate) — system review 2026-05-31

[williamzujkowski]

Findings catalog — routing-adapters-models

From the 2026-05-31 full-codebase review (epic #3143). Domain health: adequate. This issue is the durable, individually-trackable list of findings for this domain; thematic work is tracked under epic #3143 (related phase: #3150).

Findings

• [HIGH][architecture] Two disconnected adapter hierarchies (IModelAdapter vs ICliAdapter) without bridge — ✅ RESOLVED via routing: Two disconnected adapter hierarchies (IModelAdapter vs ICliAdapter) without bridge #3183 (chore: reconcile the 12 system-review finding catalogs — tick resolved sub-findings / split residuals #3696 reconciliation 2026-06-09)
  • Evidence: /src/adapters/resilient-adapter.ts:70 (IModelAdapter plane) vs /src/cli-adapters/composite-router.ts:163 (ICliAdapter plane)
  • Fix: Define a unified adapter interface that supports both model-level (provider) and CLI-level (subprocess) dispatch. Implement adapter composition layer so routing decisions can express model preferences, not just CLI choices. Unifies the two planes into a single routing→model→execute pipeline.
• [HIGH][modularity] UnifiedAdapterRegistry not exported; building-block vision unrealized
  • Evidence: /src/adapters/index.ts:172-180 exports UnifiedAdapterRegistry, but /src/exports/adapters.ts does not; only internal code (cli-server.ts) imports it
  • Fix: Export UnifiedAdapterRegistry from main entry points (src/index.ts, src/exports/adapters.ts). Add public factory function createUnifiedRegistry(). Document as a reusable primitive for custom routing logic. Enables operators to build domain-specific routing strategies without reaching into internals.
• [HIGH][correctness] Model registry is static at initialization; overlay updates never propagate to routing — ✅ RESOLVED via routing: Model registry is static at initialization; overlay updates never propagate to routing #3185 (PR feat(registry): propagate overlay updates to routing without restart (#3185) #3706; the refresh→loader path mismatch found during it fixed via registry: 'registry refresh' writes to data dir but the generated loader reads the package dir #3707/PR fix(registry): generated-registry loader reads the refreshed data-dir file (#3707) #3818) (chore: reconcile the 12 system-review finding catalogs — tick resolved sub-findings / split residuals #3696 reconciliation 2026-06-09)
  • Evidence: /src/adapters/unified-registry.ts:299-311 (buildTaskRouting called once in constructor); /src/config/model-registry.ts:292-314 (lazy singleton built once, never refreshed)
  • Fix: Implement hot-reload for model registry: either subscription-based (routing subscribes to registry change events) or polling-based (periodic re-check of task specialization matrix). Ensure manifest overlays applied post-startup (e.g., via NEXUS_MODELS_OVERLAY_PATH update) propagate to routing decisions within bounded time.
• [MED][correctness] ResilientAdapter.refresh() is not atomic; concurrent requests can race state clears — ✅ RESOLVED via routing: ResilientAdapter.refresh() is not atomic; concurrent requests can race state clears #3186 (chore: reconcile the 12 system-review finding catalogs — tick resolved sub-findings / split residuals #3696 reconciliation 2026-06-09)
  • Evidence: /src/adapters/resilient-adapter.ts:162-167 (clears currentAdapter synchronously without quiescing inflight); line 196-200 (dispose does not block or drain pending work)
  • Fix: Implement quiescence tracking: before clearing cached adapter, wait for ongoing requests to drain (with timeout). Add onFailover callback guarantee—either all callbacks complete or log which failed. Consider async dispose() signature instead of void. Prevents mid-request adapter swap from corrupting streaming state.
• [MED][user-journey] MODEL_NOT_FOUND fallback is silent; retirement events invisible to operators — ✅ RESOLVED via routing: MODEL_NOT_FOUND fallback is silent; retirement events invisible to operators #3187 (chore: reconcile the 12 system-review finding catalogs — tick resolved sub-findings / split residuals #3696 reconciliation 2026-06-09)
  • Evidence: /src/adapters/model-not-found-fallback.ts:135-150 (completeWithFallback detects 404, picks fallback, retries, surfaces second error with no retirement indicator); onRetirement callback defined but never wired in production code
  • Fix: Wire onRetirement callback through adapter construction path. Log retirement decision with modelId, fallback id, and reason (e.g., vendor 404). Emit event to orchestration observer for telemetry/alerting. Helps operators detect vendor model churn and adjust task specialization matrix before outages.
• [MED][user-journey] AvailableModelsCache filtering is best-effort; missing cache hides model unavailability — ✅ RESOLVED via routing: AvailableModelsCache filtering is best-effort; missing cache hides model unavailability #3188 (PR fix(routing): log INFO when the model-availability cache falls back to all CLIs (#3188) #3501) (chore: reconcile the 12 system-review finding catalogs — tick resolved sub-findings / split residuals #3696 reconciliation 2026-06-09)
  • Evidence: /src/cli-adapters/composite-router.ts:639-653 (getCandidateCliNames silently falls back to all CLIs if cache is undefined or returns empty)
  • Fix: Make cache wiring explicit: warn at router construction time if cache is undefined but would be useful (e.g., in multi-tenant mode). Log cache misses / fallback-to-all events at INFO level. Optionally fail routing if cache is configured but returns empty (strict mode for operators who depend on it).
• [MED][correctness] CompositeRouter never observes which model the CLI adapter will actually use — ✅ RESOLVED via routing: CompositeRouter never observes which model the CLI adapter will actually use #3189 (P4: routing returns (CLI, model) + cost-enforcement stage (epic #3143) #3150 phase 4) (chore: reconcile the 12 system-review finding catalogs — tick resolved sub-findings / split residuals #3696 reconciliation 2026-06-09)
  • Evidence: /src/cli-adapters/composite-router.ts:601-607 (route picks CLI, builds CliTask); /src/cli-adapters/types-capability.ts:70-85 (CliTask.model is optional); subprocess adapter then selects default model or task.model override
  • Fix: Elevate model selection to routing tier: add required model field to CliTask, compute it in routing pipeline (not deferred to subprocess). Route returns (CLI, Model) pair explicitly. Allows routing stages to see full decision and enables per-model quality scores, cost estimates, and capability matching.
• [LOW][modularity] AdapterFactory pattern defined but not used; CLI adapters use hardcoded switch — ✅ RESOLVED via routing: AdapterFactory pattern defined but not used; CLI adapters use hardcoded switch #3190 (chore: reconcile the 12 system-review finding catalogs — tick resolved sub-findings / split residuals #3696 reconciliation 2026-06-09)
  • Evidence: /src/adapters/factory.ts:79-195 (extensible factory with registry) vs /src/cli-adapters/factory.ts:51-75 (createCliAdapter is switch statement, not composable)
  • Fix: Implement factory registry for CLI adapters: registerCliAdapterCreator(cli, creator). Swap hardcoded switch for factory.get(). Enables operators to plug in custom CLI implementations (e.g., OpenCode variant, internal tool bridge) without modifying core code.

Composability notes

The domain is currently adequate for the CLI orchestrator use case (cli/orchestrate-command.ts) but NOT composable as building blocks. UnifiedAdapterRegistry, model registry, and adapter factories are internal primitives. External pipelines cannot import registry to implement custom routing, observe model fallback/retirement events, hot-reload model metadata post-startup, or implement custom adapters via factory pattern. To enable building-blocks→pipelines vision: export UnifiedAdapterRegistry and factories as public API, implement subscription-based model registry updates, define adapter lifecycle event contracts, and replace hardcoded CLI switch with extensible factory."

Mission gaps

• Routing decisions express CLI choice only, not model preference; decouples model selection from task requirements
• UnifiedAdapterRegistry is not publicly composable; operators cannot implement domain-specific routing strategies
• Model metadata changes post-startup (manifest overlays) do not propagate to cached routing decisions
• Adapter lifecycle events (failover, retirement, disposal) are not observable to external systems for telemetry and orchestration
• CLI adapters hardcoded in switch statement; no plugin/extensibility path for custom CLI implementations

---

Part of epic #3143. Full review record: docs/archive/system-review-2026-05-31.md.