= test-integration

== purpose

Integration tests that exercise end-to-end workflows spanning multiple core modules and infrastructure components. Verifies that components wire together correctly and produce the expected outcomes across subsystem boundaries.

== responsibilities

* Test the `SessionOrchestrator` end-to-end: from session start through stage transitions, tool execution, and completion
* Test the `ValidationPipeline` end-to-end: from payload submission through all validators to final validation report
* Verify that events flow correctly between subsystems (reducer -> store -> projector -> repository)

== non-responsibilities

* Does not test with a real SQLite/Postgres event store (uses in-memory store)
* Does not test real inference providers or tool executors
* Does not test UI or application layers
* Does not test network-level integration (HTTP, WebSocket)

== key types

=== SessionOrchestratorIntegrationTest
* **kind**: JUnit 5 test class
* **purpose**: Tests full orchestration lifecycle: creates a `WorkflowGraph`, starts a session via `DefaultSessionOrchestrator`, verifies stage progression, tool invocation events, and session completion.

=== ValidationPipelineIntegrationTest
* **kind**: JUnit 5 test class
* **purpose**: Tests the validation pipeline with multiple validators, verifying that each validator is invoked and that the aggregated validation report is correct.

== event flow

*inbound:* Constructed `NewEvent` instances and orchestration commands submitted to the orchestrator or validation pipeline.

*outbound:* Assertions on `StoredEvent` sequences emitted to the event store, final state from projections, and validation reports.

== integration points

* `:core:kernel` — `DefaultSessionOrchestrator`, `OrchestrationConfig`, `OrchestratorEngines`
* `:core:events` — `EventStore`, event payload types
* `:core:validation` — `ValidationPipeline`, `Validator`, validation model types
* `:core:sessions` — `DefaultSessionRepository`, `SessionProjector`
* `:core:transitions` — `DefaultTransitionResolver`, `WorkflowGraph`
* `:testing:fixtures` — mock providers, tools, compressors, repositories, and event replayers

== invariants

* Orchestrator follows the configured workflow graph — stages execute in declared order
* The event store contains all events produced during orchestration
* Validation pipeline evaluates all registered validators

== PlantUML diagram

[plantuml, test-integration, "png"]
----
include::../../diagrams/test-integration.puml[]
----




== known issues

* Tests use mocked engines, not real inference or tool execution — real end-to-end behavior is not validated
* In-memory event store may not surface ordering or persistence bugs present in production stores

== open questions

* Should integration tests include a real SQLite event store to verify write/read ordering?
* Should there be a separate integration test for the server module's HTTP and WebSocket routing?