kami
9734eec63c
Generated by per-group subagents covering all 52 modules across: core (18), infrastructure (10), apps (5), interfaces (3), plugins (7), testing (9) Documentation format: - AsciiDoc (.adoc) files in docs/modules/<group>/ - PlantUML (.puml) files in docs/diagrams/ - .adoc files reference diagrams via include:: directives Each doc covers: purpose, responsibilities, non-responsibilities, key types, event flow, integration points, invariants, PlantUML diagram, known issues, and open questions.
105 lines
4.9 KiB
Plaintext
105 lines
4.9 KiB
Plaintext
= 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?
|