= test-deterministic

== purpose

Tests verifying the determinism invariants of the Correx system: that event replay, context compression, approval decisions, router state, and validation pipelines produce identical results given identical inputs, independent of timing, execution order, or environment.

== responsibilities

* Verify that session replay is deterministic — identical event streams produce identical state
* Verify that context compression is deterministic — identical inputs produce identical compressed outputs
* Verify that the approval engine produces deterministic outcomes — same request + same config = same decision
* Verify that the router facade, projector, and reducer produce deterministic state
* Verify that the context pack builder produces deterministic results given the same inputs
* Verify token budget enforcement — requests exceeding the budget are rejected consistently
* Verify graph validation determinism — same graph produces same validation errors
* Verify validation pipeline short-circuit behavior — short-circuit outcomes are consistent and deterministic

== non-responsibilities

* Does not test performance or timing characteristics
* Does not test non-deterministic components (real inference providers, network I/O)
* Does not test application layers or UI

== key types

=== SessionReplayDeterminismTest
* **kind**: JUnit 5 test class
* **purpose**: Verifies that replaying the same event stream multiple times produces identical session state each time.

=== ContextCompressionDeterminismTest
* **kind**: JUnit 5 test class
* **purpose**: Verifies that the context compressor produces identical output when run multiple times with the same inputs and budget.

=== ApprovalEngineDeterminismTest
* **kind**: JUnit 5 test class
* **purpose**: Verifies that the approval engine returns the same decision given the same request and configuration across multiple invocations.

=== RouterFacadeTest
* **kind**: JUnit 5 test class
* **purpose**: Tests the router facade for deterministic behavior — identical user inputs produce identical router responses (when router is mocked).

=== RouterProjectorTest / RouterReducerTest / RouterContextBuilderTest
* **kind**: JUnit 5 test classes
* **purpose**: Test router projection, reduction, and context building determinism.

=== GraphValidatorTest
* **kind**: JUnit 5 test class
* **purpose**: Verifies that workflow graph validation produces consistent results for the same graph topology.

=== ValidationPipelineShortCircuitTest
* **kind**: JUnit 5 test class
* **purpose**: Verifies that validation pipeline short-circuiting behaves consistently — a fatal validator always stops the pipeline regardless of invocation order.

=== DefaultContextPackBuilderTest
* **kind**: JUnit 5 test class
* **purpose**: Verifies that the context pack builder produces identical context packs given identical input events and budgets.

=== TokenBudgetEnforcementTest
* **kind**: JUnit 5 test class
* **purpose**: Verifies that token budget enforcement is deterministic — requests over budget are consistently rejected or truncated.

== event flow

*inbound:* Constructed events, configurations, and inputs that are fed through the component under test multiple times.

*outbound:* Assertions that identical outputs are produced for each invocation.

== integration points

* `:core:sessions` — `DefaultSessionReducer`, `SessionProjector`, `EventReplayer`
* `:core:context` — `DefaultContextPackBuilder`, `DefaultContextCompressor`, `TokenBudget`
* `:core:approvals` — `DefaultApprovalEngine`
* `:core:router` — `RouterFacade`, `RouterProjector`, `RouterReducer`
* `:core:transitions` — `GraphValidator`
* `:core:validation` — `ValidationPipeline`, `Validator`
* `:testing:fixtures` — `EventFixtures`, `InferenceFixtures`, `ApprovalFixtures`, `ContextFixtures`

== invariants

* All projected state is deterministic — given the same event stream, the output is always identical
* All compression operations are deterministic — given the same entries and budget, the output is always the same
* The approval engine is deterministic — given the same input, the decision is always the same
* Token budget enforcement produces deterministic pass/fail outcomes per request
* Validation pipeline short-circuit is deterministic — the order of validators does not affect the short-circuit outcome

== PlantUML diagram

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




== known issues

* Determinism tests rely on mocked components — they verify the mock's determinism, not the real runtime's
* Some tests may pass with mocks but fail with real implementations (e.g., real tokenizer adds nondeterminism)

== open questions

* Should there be a dedicated determinism test that runs against the full production stack (minus network)?
* Should CI run determinism tests with multiple seed values to increase coverage?