Persist bounded model-group routing observations

CHANGELOG.md

@@ -857,6 +857,10 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ### Added
 
+- An opt-in, time-window-only SQLite observation store for measured model-group
+  routing, configured with `--routing-observation-window-seconds` alongside
+  `--state-db`; it shares completed attempt evidence across gateway processes
+  without inventing decay or cross-model equivalence (ADR 0042).
 - Verbose/debug logging (ADR 0005): a new stdlib-only `debug_logging.py`
   module, a `--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}` CLI flag with a
   `--verbose`/`--debug` shorthand (default unchanged: `WARNING`), and new
@@ -982,6 +986,18 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ### Fixed
 
+- A blank-string `seed` or `top_logprobs` on `/v1/responses` no longer forces
+  the provider-only (non-streamed) execution path for `orchestrator/auto` /
+  `orchestrator/free`. Both omit-equivalence checks now pop the field instead
+  of leaving the raw blank string behind, matching the existing Chat
+  Completions convention and keeping the streamed-orchestration decision
+  (`_responses_virtual_requires_provider_path`) honest about what was
+  actually supplied.
+- The opt-in durable routing-observation store now prunes rows by the shared
+  database's largest registered routing-observation window, not by whichever
+  writer happens to have the shortest local window. Mixed-window gateway
+  processes therefore keep physically bounded storage without erasing active
+  evidence required by a longer-window peer.
 - `TaskOrchestrator._invoke`'s route/Conduct primary chat call now classifies
   a `ProviderUpstreamError` (5xx, 429, network) directly from its own
   already-computed `retryable` flag (`tool_fallback.classify_provider_transport_failure`)

README.md

@@ -81,6 +81,7 @@ HTTP serving is hardened for local lab use:
 - `/healthz` is a minimal unauthenticated process probe; use the administrator-authenticated `/readyz` endpoint for secret-free orchestration, sync-routing, and optional batch dependency status. Liveness stays available during optional dependency degradation.
 - Full orchestration traces are not returned by default. Set `include_orchestration_trace: true` per standard Chat request or start with `--expose-trace-by-default` when the caller is trusted. Requests that also use `tools` or `response_format` still fail with `unsupported_trace_disclosure`; remove the trace flag for structured or tool requests.
 - State is in-memory by default. Pass `--state-db PATH` (or `CONTEXTUAL_ORCHESTRATOR_STATE_DB`) to persist workflow runs, evaluation runs, audit, and analytics to a stdlib sqlite file so they survive a restart; without it, behavior is unchanged.
+- Model-group routing observations remain process-local unless an operator explicitly passes `--routing-observation-window-seconds SECONDS` with `--state-db PATH`. That opt-in SQLite store shares only completed success/failure and measured latency/token observations inside the selected time window; it applies no decay or cross-model quality weighting. Replay remains per-router by its configured window, while transactional pruning uses the shared database's largest registered routing-observation window so a short-window process does not delete evidence still required by a longer-window peer. Non-stream success-observation persistence errors fail closed; provider-failure recording preserves the original failure and logs the durable-evidence outage. If a stream has already emitted provider bytes, a write failure is logged and cannot change the completed response.
 - Response caching is off by default. Pass `--cache-ttl SECONDS` to serve identical requests (same messages + mode) from an in-memory TTL+LRU cache and skip the provider calls; `0` disables it.
 - `ModelClient.batch_chat(agent, {custom_id: messages})` runs many requests through the provider's Batch API (async, 24h completion window, typically ~50% cheaper) — suited to evaluation/benchmark workloads, not latency-sensitive chat. The mock path answers synchronously.
 

contextual_orchestrator/__init__.py

@@ -88,6 +88,11 @@
     ResponseCacheProvider,
     build_response_cache_key,
 )
+from .routing_observation_store import (
+    RoutingObservation,
+    RoutingObservationStore,
+    SqliteRoutingObservationStore,
+)
 from .tool_fallback import (
     MAX_TOOL_RETRY_ATTEMPTS,
     ToolExecutionError,
@@ -149,6 +154,9 @@
     "ResponseCacheProvider",
     "RedisResponseCacheProvider",
     "build_response_cache_key",
+    "RoutingObservation",
+    "RoutingObservationStore",
+    "SqliteRoutingObservationStore",
     # routing / batch
     "RoutingPolicy",
     "RoutingHints",

contextual_orchestrator/__main__.py

@@ -945,6 +945,12 @@ def main(argv: list[str] | None = None) -> None:
     parser.add_argument("--agents", default="examples/agents.mock.json", help="Agent config JSON.")
     parser.add_argument("--state-db", default=os.environ.get("CONTEXTUAL_ORCHESTRATOR_STATE_DB", "") or None,
                         help="Optional sqlite path to persist runs/audit/analytics across restarts (default: in-memory).")
+    parser.add_argument(
+        "--routing-observation-window-seconds",
+        type=_positive_int,
+        default=None,
+        help="Persist measured routing observations in state-db for this explicit time window; decay is not applied.",
+    )
     parser.add_argument("--mode", choices=["auto", "route", "conduct"], default="auto")
     parser.add_argument("--serve", action="store_true", help="Run the chat completions HTTP server.")
     parser.add_argument(
@@ -1056,6 +1062,8 @@ def main(argv: list[str] | None = None) -> None:
     )
     _add_log_level_arguments(parser)
     args = parser.parse_args(arguments)
+    if args.routing_observation_window_seconds is not None and not args.state_db:
+        parser.error("--routing-observation-window-seconds requires --state-db")
 
     client = ModelClient(
         ca_bundle=args.provider_ca_bundle,
@@ -1069,6 +1077,7 @@ def main(argv: list[str] | None = None) -> None:
         load_agents(args.agents),
         client=client,
         state_db=args.state_db,
+        routing_observation_window_seconds=args.routing_observation_window_seconds,
         agents_db=args.agents_db,
         budget_max_output_tokens=args.budget_max_output_tokens,
         budget_max_cost_usd=args.budget_max_cost_usd,