Snapshot(WIP): unification-of-request-processing

Author: Mateusz

…fication-of-request-processing/design.md …fication-of-request-processing/design.md.kiro/specs/unification-of-request-processing/design.md renamed to .kiro/specs/archive/unification-of-request-processing/design.md .kiro/specs/unification-of-request-processing/design.md renamed to .kiro/specs/archive/unification-of-request-processing/design.md

@@ -531,9 +531,9 @@ This matrix may evolve during implementation, but the classification dimensions
 |----------------|-------------------|-------------------------------------------|
 | Boundary compatibility | `tests/integration/transport/fastapi/test_response_adapters_integration.py`, `tests/unit/test_transport_adapters.py` | canonical-path boundary regressions for unchanged streaming and non-streaming contracts |
 | Dedup short-circuit and completion classification | `tests/unit/core/services/test_backend_request_manager_deduplication.py`, `tests/integration/test_backend_request_manager_e2e.py` | gate-enabled regressions that prove canonical adoption preserves the current classification rules |
-| Empty-response and empty-stream recovery | `tests/unit/core/services/test_backend_non_streaming_response_handler.py`, integration coverage, streaming-handler coverage | explicit canonical-path recovery regressions before Phase 1 or Phase 2 promotion |
-| Loop detection and cancel callback | `tests/unit/core/services/test_backend_streaming_response_handler.py`, `tests/integration/test_end_to_end_loop_detection.py` | canonical-path regressions for cancellation chunk emission and callback invocation |
-| Tool-call retry coordination | `tests/unit/core/services/test_backend_non_streaming_response_handler.py`, `tests/unit/core/services/test_tool_call_retry_coordinator.py` | adapter or canonical-path regressions proving retry limits and mode-correct behavior remain intact |
+| Empty-response and empty-stream recovery | `tests/unit/core/services/test_canonical_post_backend_response_pipeline.py`, `tests/unit/core/services/test_post_backend_single_stream_runtime.py`, `tests/unit/core/services/test_backend_streaming_failopen_terminal.py`, `tests/unit/core/services/test_backend_streaming_middleware_and_recovery.py`, `tests/integration/test_backend_request_manager_e2e.py` | explicit canonical-path recovery regressions before Phase 1 or Phase 2 promotion |
+| Loop detection and cancel callback | `tests/unit/core/services/test_backend_streaming_loop_quality_metadata.py`, `tests/unit/core/services/test_backend_streaming_middleware_and_recovery.py`, `tests/integration/test_end_to_end_loop_detection.py` | canonical-path regressions for cancellation chunk emission and callback invocation |
+| Tool-call retry coordination | `tests/unit/core/services/test_backend_streaming_middleware_and_recovery.py`, `tests/unit/core/services/test_tool_call_retry_coordinator.py`, `tests/integration/test_backend_request_manager_e2e.py` | adapter or canonical-path regressions proving retry limits and mode-correct behavior remain intact |
 | Quality verifier semantics | `tests/unit/core/services/test_quality_verifier_stream_verifier.py`, `tests/unit/core/services/test_response_processor_quality_verifier.py`, `tests/integration/test_quality_verifier_integration.py` | canonical-path validation for skip-verification, recall, and streaming decision flow |
 | Gate defaults and diagnostics | none dedicated yet | tests for config defaults, path-selection metadata, and stage diagnostics |
 

.kiro/specs/archive/unification-of-request-processing/feature_migration_exceptions.md

@@ -0,0 +1,28 @@
+# Canonical feature migration status and explicit exceptions
+
+This document records Wave 4.2 migration progress and the bounded exceptions
+that remain mode-sensitive during the transition.
+
+## Migrated priority features
+
+- `ResponseLoggingFeature`
+  - Uses `FeatureLifecycleContext` via compatibility bridge.
+  - Reads terminal state, finish reason, request id, backend, and model metadata.
+- `ContentFilterFeature`
+  - Uses `FeatureLifecycleContext` via compatibility bridge.
+  - Keeps behavior identical while adding typed lifecycle-aware diagnostics.
+
+## Explicit bounded exceptions (kept mode-sensitive for now)
+
+- `EmptyResponseFeature`
+  - Depends on stream terminal detection and retry budgets.
+  - Remains in existing safeguard path until connector migration fully stabilizes.
+- `ToolCallReactor` / swallowed-tool handling
+  - Requires terminal and retry-state coordination with request-level control flow.
+- Loop/cancellation guards in streaming handler
+  - Intentionally remain in the streaming safeguard layer.
+
+## Removal policy
+
+- Duplicated feature logic is removed only when canonical behavior is equivalence-tested.
+- Exception features stay isolated in current layers and are covered by regression tests.

…on-of-request-processing/gap-analysis.md …on-of-request-processing/gap-analysis.md.kiro/specs/unification-of-request-processing/gap-analysis.md renamed to .kiro/specs/archive/unification-of-request-processing/gap-analysis.md .kiro/specs/unification-of-request-processing/gap-analysis.md renamed to .kiro/specs/archive/unification-of-request-processing/gap-analysis.md

@@ -33,8 +33,10 @@
 
 **Representative existing verification surface**
 - `tests/unit/core/services/test_backend_request_manager_deduplication.py`
-- `tests/unit/core/services/test_backend_non_streaming_response_handler.py`
-- `tests/unit/core/services/test_backend_streaming_response_handler.py`
+- `tests/unit/core/services/test_canonical_post_backend_response_pipeline.py`
+- `tests/unit/core/services/test_post_backend_single_stream_runtime.py`
+- `tests/unit/core/services/test_backend_streaming_failopen_terminal.py`
+- `tests/unit/core/services/test_backend_streaming_middleware_and_recovery.py`
 - `tests/unit/core/services/test_quality_verifier_stream_verifier.py`
 - `tests/unit/core/services/test_response_processor_quality_verifier.py`
 - `tests/integration/test_backend_request_manager_e2e.py`

.kiro/specs/archive/unification-of-request-processing/implementation-orchestration.md

@@ -0,0 +1,40 @@
+# Implementation Orchestration Contract
+
+This file defines the lead/specialist split used for `unification-of-request-processing` execution waves.
+
+## Agent Roles
+
+- **Lead orchestrator**
+  - Owns wave admission/exit criteria.
+  - Decides sequencing and rollback actions.
+  - Approves `tasks.md` checkbox updates after evidence is complete.
+- **Traceability specialist**
+  - Maps each task to requirement IDs and design invariants.
+  - Flags out-of-scope edits before coding starts.
+- **RED specialist**
+  - Adds failing tests first for each wave/task.
+  - Confirms failures represent missing behavior rather than test defects.
+- **GREEN specialist**
+  - Implements minimum code required to pass the new tests.
+  - Keeps migration gates default-off unless a task explicitly requires stage enablement.
+- **Refactor specialist**
+  - Improves structure after green without changing behavior.
+- **Verification specialist**
+  - Runs per-file QA (`ruff`, `black`, `mypy`), targeted tests, then broader suites.
+  - Provides pass/fail evidence for wave closure.
+
+## Handoff Checklist (Per Task)
+
+1. Traceability map recorded (requirements + invariants).
+2. RED test added and failing.
+3. GREEN implementation merged.
+4. Refactor completed (if needed).
+5. QA commands and tests are green.
+6. Lead updates `tasks.md` checkbox.
+
+## Failure Handling Contract
+
+- Freeze next-wave work on broad regression.
+- Keep migration gates default-off.
+- Reproduce with minimal targeted tests.
+- Resume only after the current wave gate turns green again.

.kiro/specs/archive/unification-of-request-processing/migration_retirement.md

@@ -0,0 +1,17 @@
+# Migration retirement notes (request-processing unification)
+
+## Retired from production startup
+
+- **Feature parity registry initialization** no longer runs from `post_build_hooks`. The global parity registry and `initialize_feature_parity_registry` remain as an **optional** helper for tests, audits, and local diagnostics (see `post_build_actions.initialize_feature_parity_registry` docstring).
+- **CI parity enforcement** no longer assumes registry population via `get_or_build_service_provider`. Quality tests seed the registry explicitly when they need `verify_parity()`, and assert typed `FeatureLifecycleContext` coverage where appropriate.
+
+## Runtime shape (post-retirement)
+
+- `BackendRequestManager` always uses the canonical post-backend pipeline (`PostBackendResponseCoordinator` + `EnvelopeCompatibilityAdapter`) for both requested modes.
+- `enable_core_canonical_path` is retained for compatibility/validation semantics but no longer switches execution to a legacy split-handler branch.
+- `CorePathDecision.retire_legacy_dual_path` remains a configuration snapshot in diagnostics when `emit_path_selection_metadata` is enabled.
+
+## Compatibility shims retained
+
+- `initialize_feature_parity_registry` and `src.core.interfaces.feature_parity` registry APIs unchanged for callers that opt in explicitly.
+- **Current runtime**: `BackendRequestManager` always selects the canonical post-backend path; transport adaptation to streaming/non-streaming happens only at the boundary via `EnvelopeCompatibilityAdapter`.

.kiro/specs/archive/unification-of-request-processing/phase0_audit.md

@@ -0,0 +1,67 @@
+# Phase 0 Audit - Manager Cut Line and Feature Classification
+
+This document records the Phase 0 audit required before canonical convergence work.
+
+## 1.1 Manager/Handler Cut-Line Characterization
+
+## Scope Baseline
+
+- The canonicalization cut line starts in `BackendRequestManager.process_backend_request()` **after** `IBackendProcessor.process_backend_request()` returns.
+- Dedup short-circuit and preflight retry-limit checks remain above the cut line.
+- Transport adaptation remains below the cut line (`response_adapters` layer).
+
+## Current Responsibility Inventory
+
+| Area | Current owner | Notes for migration |
+|---|---|---|
+| Dedup registration + duplicate short-circuit | `BackendRequestManager` | Must remain pre-backend and pre-gate. |
+| Streaming completion classification (disconnect/terminal/error) | `BackendRequestManager` stream wrapper | Must remain preserved until canonical equivalent is proven. |
+| Non-streaming post-processing and retry orchestration | `BackendNonStreamingResponseHandler` | Candidate for coordinator convergence. |
+| Streaming post-processing, loop controls, verifier buffering | `BackendStreamingResponseHandler` | Candidate for coordinator convergence with explicit safeguards. |
+| Tool-call retry coordination | `ToolCallRetryCoordinator` + handlers | Mode-sensitive cases must remain explicit until unified safely. |
+| Empty-response/empty-stream recovery | `EmptyResponseFeature` + handlers | Cannot be treated as generic chunk logic during migration. |
+| Quality-verifier control flow | request processor + streaming verifier + handlers | Keep parity-sensitive behavior pinned with tests. |
+
+## Phase 1 Boundary Decision
+
+- **In scope for first convergence:** post-backend-response handling branch currently split by requested mode.
+- **Out of scope for Phase 1:** backend processor contract replacement, connector stream-first bridge, transport response object changes.
+- **Fallback policy:** legacy split handlers stay available for rollback while gate is default-off.
+
+## Explicit Migration Exceptions (Phase 0)
+
+- Tool-call retry and empty-response recovery remain mode-sensitive until canonical feature/context migration.
+- Completion-state classification remains in existing stream wrapper until tested canonical equivalent exists.
+
+## 1.2 Response-Processing Feature Audit and Migration Classification
+
+## Classification Rules
+
+- `chunk-safe`: can run on canonical chunk stream with no end-of-stream assumptions.
+- `terminal-sensitive`: depends on terminal chunk markers or finish reason.
+- `full-response-sensitive`: requires accumulated response materialization.
+- `explicit-exception`: temporary bounded mode-specific behavior during migration.
+
+## Feature Inventory and Strategy
+
+| Feature / behavior | Classification | Canonical strategy |
+|---|---|---|
+| Response logging / content filtering | chunk-safe | Bridge through canonical stream-first feature pipeline. |
+| Empty-response recovery | terminal-sensitive | Keep explicit safeguard path until canonical coordinator feature parity is proven. |
+| Tool-call retry coordination | terminal-sensitive | Keep explicit collaborator; migrate only with dedicated adapter coverage. |
+| Loop detection / cancellation chunk emission | terminal-sensitive | Preserve dedicated streaming behavior; migrate with explicit tests. |
+| Structured output enforcement | full-response-sensitive | Use canonical adapter path for non-streaming accumulation context. |
+| Quality-verifier stream verification and recall behavior | terminal-sensitive | Keep dedicated verifier collaborator during early migration. |
+| Usage/metadata propagation | full-response-sensitive | Preserve envelope metadata via canonical handle before adapter conversion. |
+
+## Bridge Eligibility Summary
+
+- **Bridge-safe now:** response logging, content filtering (chunk-safe).
+- **Dedicated canonical adapter required:** structured output enforcement.
+- **Explicit temporary exception required:** empty-response recovery, loop detection, tool-call retry, quality-verifier flow.
+
+## Phase 0 Exit Preconditions
+
+- Cut line is fixed at manager post-backend-response branch.
+- Feature classifications above are treated as migration constraints for tasks `4.1` and `4.2`.
+- New gate defaults remain off; diagnostics expose active path and stage (`migration_stage`, `canonical_path_used`, `feature_canonical_used`, `connector_stream_first_used`).

.kiro/specs/archive/unification-of-request-processing/provider_capability_matrix.md

@@ -0,0 +1,40 @@
+# Provider capability matrix (request-processing unification)
+
+This artifact supports Wave **6.1** (connector stream-first cohort planning). It describes how each **backend connector** relates to the **canonical internal handle** and the **stream-first migration framework** (`request_processing_unification.connector_stream_first`), not full connector audits.
+
+## Legend
+
+| Capability | Meaning |
+|------------|---------|
+| **Native HTTP streaming** | Connector can call upstream with streamed HTTP and expose `StreamingResponseEnvelope`. |
+| **Non-stream HTTP** | Connector supports blocking JSON (`ResponseEnvelope`) for `stream=false`. |
+| **Stream-first eligible** | Suitable for cohort opt-in under canonical path: manager may set `stream=true` upstream for a non-streaming client when the backend key is listed in `connector_stream_first`; unlisted backends are not implicitly forced. |
+| **Framework status** | Whether stream-first is implemented only at the **manager/gate** boundary (current incremental rollout) vs connector-native stream-first return. |
+
+## Matrix
+
+| Backend key (config / routing) | Native HTTP streaming | Non-stream HTTP | Stream-first eligible (cohort) | Framework notes |
+|-------------------------------|----------------------|-----------------|-------------------------------|-------------------|
+| `openai` | Yes | Yes | Cohort-gated | Boundary framework: forced upstream `stream` only when this backend key is explicitly opted into the cohort (canonical path is always selected). |
+| `anthropic` | Yes | Yes | Cohort-gated | Same boundary contract; provider-specific parsing stays in connector/handler layers. |
+| `gemini` | Yes | Yes | Cohort-gated | Same. |
+| `azure_openai` | Yes | Yes | Cohort-gated | Same. |
+| `groq` | Yes | Yes | Cohort-gated | Same. |
+| `cohere` | Yes | Yes | Cohort-gated | Same. |
+| `mistral` | Yes | Yes | Cohort-gated | Same. |
+| `deepseek` | Yes | Yes | Cohort-gated | Same. |
+| `xai` | Yes | Yes | Cohort-gated | Same. |
+| `ollama` | Yes | Yes | Cohort-gated | Same. |
+| `vertex` / `google` | Yes | Yes | Cohort-gated | Same. |
+| `bedrock` | Yes | Yes | Cohort-gated | Same. |
+| `other / custom` | Varies | Varies | **Off by default** | Opt in per routed `backend` string only when validated for the deployment; otherwise no implicit stream forcing occurs. |
+
+## Connector entry contract (target)
+
+- Upstream transport may be streaming or blocking; the **manager** selects canonical post-processing using explicit `PostBackendProcessingMode`.
+- Cohort opt-in is **config-only** and **default off**; absent an explicit backend key entry, stream-first stays disabled. The manager always uses the canonical post-backend path.
+- Provider-specific metadata remains on `StreamingResponseEnvelope` / handler metadata until fully absorbed by canonical handles (future waves).
+
+## Maintenance
+
+Update this matrix when a connector is **validated** for stream-first cohort promotion or when native capabilities change.

…on-of-request-processing/requirements.md …on-of-request-processing/requirements.md.kiro/specs/unification-of-request-processing/requirements.md renamed to .kiro/specs/archive/unification-of-request-processing/requirements.md .kiro/specs/unification-of-request-processing/requirements.md renamed to .kiro/specs/archive/unification-of-request-processing/requirements.md

@@ -43,10 +43,10 @@
 ### Handler asymmetry is the main migration challenge
 - **Context**: Determine whether the two handlers can be trivially merged into one stream-first coordinator.
 - **Sources Consulted**:
-  - `src/core/services/backend_non_streaming_response_handler.py`
+  - `src/core/services/post_backend_response_coordinator.py`
   - `src/core/services/backend_request_manager/streaming_response_handler.py`
-  - `tests/unit/core/services/test_backend_non_streaming_response_handler.py`
-  - `tests/unit/core/services/test_backend_streaming_response_handler.py`
+  - `tests/unit/core/services/test_canonical_post_backend_response_pipeline.py`
+  - `tests/unit/core/services/test_backend_streaming_middleware_and_recovery.py`
 - **Findings**:
   - The non-streaming handler owns empty-response retry, structured-output enforcement, metadata filtering, and non-stream tool-call retry coordination.
   - The streaming handler owns middleware wrapping, quality-verifier buffering, loop detection, empty-stream recovery, tool-call retry coordination, status extraction, and stream lifecycle behavior.
@@ -121,8 +121,9 @@
 - **Context**: Determine whether the codebase already has enough behavioral evidence to support characterization-first migration.
 - **Sources Consulted**:
   - `tests/unit/core/services/test_backend_request_manager_deduplication.py`
-  - `tests/unit/core/services/test_backend_non_streaming_response_handler.py`
-  - `tests/unit/core/services/test_backend_streaming_response_handler.py`
+  - `tests/unit/core/services/test_canonical_post_backend_response_pipeline.py`
+  - `tests/unit/core/services/test_backend_streaming_failopen_terminal.py`
+  - `tests/unit/core/services/test_backend_streaming_middleware_and_recovery.py`
   - `tests/unit/core/services/test_quality_verifier_stream_verifier.py`
   - `tests/unit/core/services/test_response_processor_quality_verifier.py`
   - `tests/integration/test_backend_request_manager_e2e.py`
@@ -181,13 +182,14 @@
 
 ## References
 - `src/core/services/backend_request_manager_service.py` — current split branch and dedup completion wrapper
-- `src/core/services/backend_non_streaming_response_handler.py` — non-stream safeguard ownership
+- `src/core/services/post_backend_response_coordinator.py` — canonical post-backend safeguard orchestration
 - `src/core/services/backend_request_manager/streaming_response_handler.py` — streaming safeguard ownership
 - `src/core/services/response_pipeline.py` — existing internal stream-first unification precedent
 - `src/core/services/streaming/non_streaming_adapter.py` — non-stream-as-stream adaptation precedent
 - `src/core/transport/fastapi/response_adapters.py` — transport boundary behavior and disconnect cleanup
 - `src/connectors/gemini_base/orchestrator.py` — proven stream-first accumulation example in connectors
 - `tests/unit/core/services/test_backend_request_manager_deduplication.py` — streaming dedup and completion tracking invariants
-- `tests/unit/core/services/test_backend_non_streaming_response_handler.py` — non-stream retry and validation invariants
-- `tests/unit/core/services/test_backend_streaming_response_handler.py` — loop detection, cancel callback, and streaming safeguard invariants
+- `tests/unit/core/services/test_canonical_post_backend_response_pipeline.py` — canonical post-backend pipeline invariants
+- `tests/unit/core/services/test_backend_streaming_failopen_terminal.py` — streaming fail-open and terminal error semantics
+- `tests/unit/core/services/test_backend_streaming_middleware_and_recovery.py` — streaming safeguards, loop metadata, and recovery paths
 - `tests/integration/transport/fastapi/test_response_adapters_integration.py` — boundary compatibility coverage

…cation-of-request-processing/research.md …cation-of-request-processing/research.md.kiro/specs/unification-of-request-processing/research.md renamed to .kiro/specs/archive/unification-of-request-processing/research.md .kiro/specs/unification-of-request-processing/research.md renamed to .kiro/specs/archive/unification-of-request-processing/research.md

@@ -1,9 +1,9 @@
 {
   "feature_name": "unification-of-request-processing",
   "created_at": "2026-04-10T12:00:00Z",
-  "updated_at": "2026-04-10T18:05:00Z",
+  "updated_at": "2026-04-12T19:15:00Z",
   "language": "en",
-  "phase": "tasks-approved",
+  "phase": "implementation-complete",
   "approvals": {
     "requirements": {
       "generated": true,