quality: audit and harden router code quality, security, and API boundaries

Summary

Create an H2 roadmap track for a deep router code-quality, security, resource-safety, and API-boundary audit, followed by prioritized hardening work.

Parent roadmap: #2287 Related: #2357, #2326, #2330, #2331, #2355, #2200, #1510 Related code: src/semantic-router/pkg/config, src/semantic-router/pkg/extproc, src/semantic-router/pkg/routerruntime, src/semantic-router/pkg/services, src/semantic-router/pkg/selection, src/semantic-router/pkg/modelselection, src/semantic-router/pkg/modelruntime, src/semantic-router/pkg/looper, src/semantic-router/pkg/memory, src/semantic-router/pkg/vectorstore, src/semantic-router/pkg/openai, src/semantic-router/pkg/anthropic, src/semantic-router/pkg/headers, src/semantic-router/pkg/responseapi, src/vllm-sr/cli, deploy/operator/api/v1alpha1, deploy/operator/controllers, dashboard/backend/router

Motivation

H2 adds larger config contracts, multiple recipes, custom signals, inference-aware backends, Router Memory/Learning, Looper-family algorithms, dashboard/control-plane surfaces, and edge deployments. These features increase the number of runtime seams and security-sensitive paths.

Before the router grows further, we need a focused quality pass that identifies and prioritizes risks in:

• security-sensitive request, response, feedback, identity, header, plugin, Looper, and memory paths;
• potential resource leaks around goroutines, contexts, timers, streams, HTTP clients, native bindings, model runtimes, vector stores, replay stores, and cache stores;
• weak or duplicated structs, untyped payloads, and ad hoc maps where versioned contracts or SDK/public types should own the API;
• inconsistent API ownership across router core, CLI, dashboard backend, operator, config schemas, and response headers;
• design-pattern drift in hotspots such as config loading/validation, extproc request and response processing, classification runtime, model selection, and service lifecycle wiring.

This is broader than #2357. #2357 tracks known security hardening items across auth, feedback, and Looper paths. This issue should produce a systematic audit and remediation plan across router code quality, API contracts, resource safety, and module boundaries.

Scope

Audit and prioritize:

• Security analysis

  • request/response header trust boundaries;
  • identity/authz/tenant-sensitive assumptions;
  • feedback and replay mutation paths;
  • Looper, plugin, tool, memory, and model-selection bypass risks;
  • external provider, vector-store, and model-runtime inputs;
  • redaction and diagnostics leakage risks.

• Resource and memory safety

  • goroutine lifecycle, context.Context propagation, timers/tickers, channels, locks, and cancellation;
  • streaming request/response finalization and error paths;
  • HTTP clients, response bodies, file handles, model/runtime handles, native binding lifecycle, cache/vector-store clients;
  • race-prone shared state in config reload, service runtime, learning/memory, replay, cache, and inflight tracking.

• API and type contracts

  • duplicated OpenAI/Anthropic-shaped request or response structs that should use official/public SDK types or narrow adapter types;
  • weak structs, loosely typed maps, and implicit schema coupling;
  • config/API/header/diagnostic contracts that are not centrally owned or versioned;
  • drift between router core, CLI, dashboard backend, operator CRDs, examples, and docs;
  • public API field naming and lifecycle consistency across modules.

• Design patterns and module boundaries

  • giant managers, large orchestration files, and hotspot growth;
  • mixed responsibilities across signal, decision, algorithm, plugin, and global layers;
  • lifecycle code duplicated across backends or services;
  • unclear factory/adapter/strategy boundaries for runtime construction and provider/model integrations;
  • places where extraction-first refactors should precede new H2 features.

Deliverables

• A documented audit with severity, affected code surfaces, concrete risks, and recommended fixes.
• A prioritized child-issue list for remediation, split by risk and subsystem.
• At least one small hardening PR or proof-of-fix PR for a high-confidence finding, if the audit identifies one.
• A recommendation for static/dynamic checks that should become regular gates, such as targeted race tests, vulnerability scanning, fuzz tests, or structural lint rules.

Non-goals

• Do not turn this into a full rewrite of router core.
• Do not disclose exploit details beyond what is necessary for maintainers to triage and fix safely.
• Do not change user-facing routing behavior without compatibility notes, tests, and migration guidance.
• Do not merge unrelated cleanup just because it is found during the audit.

Acceptance criteria

• The audit covers at least config, extproc, router runtime/service composition, model selection, model runtime, Looper, memory/learning, vector/cache/replay stores, API/header contracts, CLI/dashboard/operator control-plane seams, and native binding lifecycle touchpoints.
• Findings are grouped by severity and subsystem, with clear owner surfaces and suggested validation for each finding.
• Duplicated or weak API structs are inventoried, with a recommendation to keep, replace with official SDK/public types, or move behind a versioned adapter contract.
• Resource lifecycle risks are inventoried, including context/cancellation, streaming finalization, response-body closing, goroutine/timer cleanup, native runtime handles, and backend clients.
• Security-sensitive paths are cross-linked to #2357 or new child issues, without leaking unnecessary exploit detail.
• At least one concrete child issue or PR is created for each high-priority risk class discovered.
• Proposed checks are mapped to repo-native gates or explicit follow-up work.

Validation

Use the repo harness to scope and validate follow-up PRs:

make agent-report ENV=cpu CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/extproc src/semantic-router/pkg/routerruntime src/semantic-router/pkg/services src/semantic-router/pkg/selection src/semantic-router/pkg/modelselection src/semantic-router/pkg/modelruntime src/semantic-router/pkg/looper src/semantic-router/pkg/memory src/semantic-router/pkg/vectorstore src/vllm-sr/cli deploy/operator dashboard/backend/router"
make agent-lint CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/extproc src/semantic-router/pkg/routerruntime src/semantic-router/pkg/services src/semantic-router/pkg/selection src/semantic-router/pkg/modelselection src/semantic-router/pkg/modelruntime src/semantic-router/pkg/looper src/semantic-router/pkg/memory src/semantic-router/pkg/vectorstore src/vllm-sr/cli deploy/operator dashboard/backend/router"
make agent-ci-gate CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/extproc src/semantic-router/pkg/routerruntime src/semantic-router/pkg/services src/semantic-router/pkg/selection src/semantic-router/pkg/modelselection src/semantic-router/pkg/modelruntime src/semantic-router/pkg/looper src/semantic-router/pkg/memory src/semantic-router/pkg/vectorstore src/vllm-sr/cli deploy/operator dashboard/backend/router"

For specific findings, add targeted package tests, race tests, fuzz tests, or security scans when the toolchain and environment support them.