= test-contracts

== purpose

Contract tests that validate the behavioral guarantees of core domain types. Ensures that value objects, model classes, and domain interfaces conform to their documented contracts across serialization, equality, and behavior.

== responsibilities

* Validate `WorkflowGraph`, `StageId`, `TransitionId` construction and invariants
* Test `InferenceProvider` contract (routing, health check, caching)
* Test `ValidationReport` contract and serialization
* Test `ContextSnapshot` construction and serialization
* Test orchestration model types (`OrchestrationConfig`, `WorkflowResult`, `StageOutcome`, `RetryPolicy`)
* Provide concurrent testing utilities (`ConcurrencyRunner`, `DeterministicBarrier`)

== non-responsibilities

* Does not test full integration between modules
* Does not test infrastructure adapters
* Does not test UI or application layers

== key types (test utilities)

=== ConcurrencyRunner
* **kind**: object
* **purpose**: Runs a block concurrently across N threads for M iterations using a `CountDownLatch` for synchronized start. Used for concurrency safety contract tests.

=== DeterministicBarrier
* **kind**: class
* **purpose**: Thin wrapper over `java.util.concurrent.CyclicBarrier` for synchronizing test threads at known points.

=== WorkflowGraphTest
* **kind**: JUnit 5 test class
* **purpose**: Tests `WorkflowGraph` construction, stage lookup, transition validation, and serialization round-trips.

=== InferenceProviderContractTest
* **kind**: JUnit 5 test class
* **purpose**: Defines the contract that all `InferenceProvider` implementations must satisfy (request handling, health check, capability reporting).

=== DefaultInferenceRouterTest / DefaultInferenceRouterCacheTest
* **kind**: JUnit 5 test classes
* **purpose**: Tests routing strategy, provider selection, and cache invalidation behavior.

=== EventsTest
* **kind**: JUnit 5 test class
* **purpose**: Tests event payload construction, metadata, and serialization contracts.

== event flow

*inbound:* Constructed domain objects and serialized JSON strings.

*outbound:* Assertions on equality, serialization round-trips, exception types, and behavioral contracts.

== integration points

* `:core:transitions` — `WorkflowGraph`, `StageConfig`, `TransitionEdge`
* `:core:inference` — `InferenceProvider`, `DefaultInferenceRouter`, `ProviderHealth`
* `:core:validation` — `ValidationReport`, validation model types
* `:core:events` — event payload types, `EventMetadata`
* `:core:context` — `ContextSnapshot`
* `:core:kernel` — orchestration config and result types

== invariants

* All serializable types survive a JSON encode/decode round-trip without data loss
* `StageId` and `TransitionId` are valid when non-blank
* `InferenceProvider.healthCheck()` never throws for healthy providers

== PlantUML diagram

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




== known issues

* `ConcurrencyRunner` does not assert on thread safety — it only provides concurrent execution scaffolding; the test must supply assertions
* `DeterministicBarrier` does not have a timeout — a stalled test thread will hang indefinitely

== open questions

* Should contract tests be parameterized to run against all implementations of each interface?
* Should JSON schema validation be added to serialization contract tests?