docs(dox): build out the DOX AGENTS.md hierarchy
Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
This commit is contained in:
@@ -0,0 +1,40 @@
|
||||
# testing/
|
||||
|
||||
## Purpose
|
||||
|
||||
Dedicated test submodules for the correx kernel. Tests here are NOT co-located with production code — each submodule targets a specific verification concern (approval gates, projection correctness, replay determinism, cross-module contracts, integration flows, etc.).
|
||||
|
||||
## Ownership
|
||||
|
||||
All test submodules in this subtree. Production source is in `core/` and `infrastructure/`; nothing here is deployed.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Tests must not assert on persisted State — only on event-derived state rebuilt by projectors/reducers.
|
||||
- No test submodule may import a sibling `testing/*` module except `testing:fixtures`, `testing:kernel`, and `testing:contracts` (shared helpers only).
|
||||
- `./gradlew check` applies detekt with `ignoreFailures = false` across all submodules.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Always run tests with `--rerun-tasks` to bypass Gradle cache: `./gradlew :testing:<module>:test --rerun-tasks`
|
||||
- Suspend functions in tests use `runBlocking { ... }` — no test coroutine framework needed.
|
||||
- Detekt `maxIssues: 120` — do not introduce new rule violations.
|
||||
- New `EventPayload` subclass used in tests? Register it in `core/events/.../serialization/Serialization.kt` or deserialization silently fails.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew check # all submodules: test + detekt + koverVerify
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
- `testing/approvals` — approval gate logic: grant semantics, security, trigger rules, tier immutability, fuzz
|
||||
- `testing/contracts` — cross-module interface contracts and reusable contract test fixtures (projection, replay, inference)
|
||||
- `testing/deterministic` — determinism checks: router, session replay, context compression, prompt rendering, validation pipeline
|
||||
- `testing/fixtures` — shared test data library: mock implementations, fixture builders, deterministic harness (not a test runner)
|
||||
- `testing/integration` — end-to-end flows: orchestrator, tool-call gate, freestyle approval, clarification loop, steering, rehydration
|
||||
- `testing/kernel` — core:kernel internals: retry coordinator, approval-before-emit ordering, replay inference provider, context feedback
|
||||
- `testing/projections` — reducer and projector correctness for sessions, context, inference, artifacts, router, and journal
|
||||
- `testing/replay` — replay determinism: session, approval, validation, transition, decision journal, and repo-knowledge replays
|
||||
- `testing/transitions` — FSM/workflow graph: transition resolver, event serialization, fuzz coverage
|
||||
@@ -0,0 +1,31 @@
|
||||
# testing/approvals
|
||||
|
||||
## Purpose
|
||||
|
||||
Verifies the approval gate subsystem: grant semantics, security properties, trigger rules, tier immutability, mode-based approval, and fuzz coverage. Exercises `core:approvals` in isolation and against real event/session plumbing.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests in this submodule. Production code lives in `core:approvals`, `core:events`, `core:sessions`, `core:transitions`, `core:validation`, `infrastructure:persistence`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Approval grants must never couple to tool execution — `NoExecutionCouplingTest` pins this boundary.
|
||||
- Tier values are immutable after assignment — `TierImmutabilityTest` pins this.
|
||||
- Grant security properties (escalation, scope leakage) pinned by `GrantSecurityTest`.
|
||||
- Approval triggers fire on the correct event sequence — `ApprovalTriggerTest` pins this.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- `ApprovalFuzzTest` generates random event sequences; seed is fixed for reproducibility — do not change the seed without a clear reason.
|
||||
- Suspend tests use `runBlocking { ... }`.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:approvals:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,31 @@
|
||||
# testing/contracts
|
||||
|
||||
## Purpose
|
||||
|
||||
Cross-module interface contracts and shared contract test fixtures. Two responsibilities:
|
||||
1. **Contract tests** — verify that model types (`StageId`, `TransitionId`, `WorkflowGraph`, `ContextSnapshot`, `ValidationReport`) and provider implementations (`InferenceProvider`, inference router, resource probes) satisfy their declared interfaces.
|
||||
2. **Reusable fixtures** — `testFixtures` source set exports `ProjectionContractTest`, `ReplayContractTest`, `SessionReplayContractTest`, `CountingProjectionContractTest`, and `NoopArtifactStore` for use by other test submodules.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests and test fixtures here. Production modules exercised: `core:events`, `core:transitions`, `core:sessions`, `core:validation`, `core:approvals`, `core:artifacts`, `core:kernel`, `core:inference`, `core:context`, `infrastructure:inference:commons`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Contract test fixtures in `testFixtures/` are the canonical base for projection and replay contract verification — other submodules inherit from them.
|
||||
- `koverVerify` is disabled for this submodule (fixture code is not independently measurable).
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Suspend tests use `runBlocking { ... }`.
|
||||
- `ConcurrencyRunner` and `DeterministicBarrier` in `main/` are utilities for concurrency contracts — do not add state to them.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:contracts:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,30 @@
|
||||
# testing/deterministic
|
||||
|
||||
## Purpose
|
||||
|
||||
Pins determinism invariants across the core. Every test here asserts that a given computation produces identical output for identical event input — no randomness, no external I/O. Covers: router reducer and projector, session replay, context compression, prompt renderer ordering, token budget enforcement, approval engine, validation pipeline short-circuit, context pack builder, and L3 metadata rehydration.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests in this submodule. Production modules exercised: `core:events`, `core:router`, `core:sessions`, `core:transitions`, `core:validation`, `core:approvals`, `core:context`, `core:inference`, `infrastructure:persistence`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- No test in this submodule may call an external service or live LLM — hard invariant #8 (replay is environment-independent).
|
||||
- Every tested path must produce byte-identical state for the same event log on repeated runs.
|
||||
- `PromptRendererOrderingTest` pins the rule that all SYSTEM-role entries fold into the leading system message; non-system messages order by `ContextEntry.ordinal`.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Suspend tests use `runBlocking { ... }`.
|
||||
- If a new deterministic component is added to `core:router` or `core:context`, add a matching test here.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:deterministic:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,30 @@
|
||||
# testing/fixtures
|
||||
|
||||
## Purpose
|
||||
|
||||
Shared test data library. Not a test runner — contains no test classes of its own (except `MockToolsTest` which validates the mocks themselves). Provides: mock implementations (`MockInferenceProvider`, `MockTokenizer`, `MockEventReplayer`, `MockSessionRepository`), stub tools (`EchoTool`, `FailingTool`, `RejectedTool`), fixture builders (`EventFixtures`, `InferenceFixtures`, `WorkflowFixtures`, `ApprovalFixtures`, `CycleFixtures`, `ContextFixtures`, `TransitionFixtures`), and `DeterministicHarness`.
|
||||
|
||||
## Ownership
|
||||
|
||||
This submodule is a library dependency for other `testing/*` submodules. Production modules it wraps: `core:events`, `core:transitions`, `core:approvals`, `core:sessions`, `core:tools`, `core:inference`, `core:context`, `core:kernel`, `core:validation`, `infrastructure:persistence`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- All mocks must remain stateless or explicitly reset between uses — callers cannot assume shared state across tests.
|
||||
- `DeterministicHarness` must not make live LLM or network calls.
|
||||
- `koverVerify` is disabled (library code, not independently measurable coverage).
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Add fixtures here only when two or more `testing/*` submodules need the same setup. Single-use helpers stay local to the submodule that needs them.
|
||||
- No domain logic in fixtures — only wiring and canned data.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:fixtures:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,30 @@
|
||||
# testing/integration
|
||||
|
||||
## Purpose
|
||||
|
||||
End-to-end integration tests that wire multiple core modules together without live LLM or network. Covers: `SessionOrchestrator` full flows, tool-call gate, freestyle approval gate, clarification loop, steering preemption, graph reroute, artifact injection, workspace-scoped tool registry, validation pipeline integration, critique calibration wiring, session rehydration, repo-map reuse, and subagent runner seam.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests in this submodule. Production modules exercised: `core:events`, `core:sessions`, `core:transitions`, `core:validation`, `core:approvals`, `core:context`, `core:inference`, `core:kernel`, `core:journal`, `core:risk`, `core:tools`, `core:toolintent`, `core:artifacts`, `core:artifacts-store`, `core:router`, `core:config`, `infrastructure:persistence`, `infrastructure:tools`, `infrastructure:tools:filesystem`, `apps:server`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Tests use mock inference (`MockInferenceProvider` from `testing:fixtures`) — no live LLM.
|
||||
- `apps:server` is imported for Ktor wiring tests only; no external HTTP calls.
|
||||
- Two-plane validation (Plane 2 / `core:toolintent`) must be exercised by at least one test here — `ToolCallGateTest` covers this.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Suspend tests use `runBlocking { ... }` or `kotlinx-coroutines-test`.
|
||||
- These are the slowest tests; run targeted with `:testing:integration:test --tests "ClassName"` during development.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:integration:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,30 @@
|
||||
# testing/kernel
|
||||
|
||||
## Purpose
|
||||
|
||||
Focused tests for `core:kernel` internals that require real event-store plumbing. Covers: approval-before-emit ordering race, retry coordinator behavior, replay inference provider, launch registration race conditions, workspace derivation from replay, and context feedback propagation.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests and `MockEventReplayer` helper in this submodule. Production modules exercised: `core:kernel`, `core:events`, `core:sessions`, `core:inference`, `core:approvals`, `core:context`, `core:transitions`, `core:validation`, `core:risk`, `core:tools`, `core:artifacts`, `core:artifacts-store`, `infrastructure:persistence`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `ApprovalRegisterBeforeEmitTest` pins the ordering invariant: approval listener must be registered before the event is emitted or the gate is missed.
|
||||
- `LaunchRegistrationRaceTest` pins that concurrent session launches do not corrupt registration state.
|
||||
- `koverVerify` is disabled for this submodule.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Suspend tests use `runBlocking { ... }` or `kotlinx-coroutines-test`.
|
||||
- Race tests (`LaunchRegistrationRaceTest`) must not use `Thread.sleep()` — use coroutine barriers.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:kernel:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,30 @@
|
||||
# testing/projections
|
||||
|
||||
## Purpose
|
||||
|
||||
Verifies that reducers and projectors rebuild state correctly from event sequences. Covers: `DefaultSessionReducer`, `OrchestrationReducer`/`Projector`, `InferenceReducer`/`Projector`, `ArtifactReducer`, `ContextReducer`/`Projector`, `RouterProjector`, `DecisionJournalProjector`, `SessionProjector`, `ProjectMemoryDistiller`, and `PreemptSteeringJournal`.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests in this submodule. Production modules exercised: `core:events`, `core:sessions`, `core:transitions`, `core:context`, `core:inference`, `core:kernel`, `core:artifacts`, `core:router`, `core:journal`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Projections must be rebuilt from events only — no test may assert on a persisted State object.
|
||||
- Reducers are pure functions: same events → same state, always. Tests must verify this property explicitly (run twice, compare).
|
||||
- Any new reducer or projector added to a `core:*` module needs a corresponding test here.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Suspend tests use `runBlocking { ... }`.
|
||||
- Keep event sequences in tests minimal — use `testing:fixtures` builders rather than raw event construction.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:projections:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,30 @@
|
||||
# testing/replay
|
||||
|
||||
## Purpose
|
||||
|
||||
Pins replay determinism end-to-end: feeds a recorded event log through the full replay stack and asserts the resulting state is identical to what was produced during original execution. Covers: session replay, approval replay, validation replay, decision journal replay, refinement iteration replay, execution-plan-locked replay, repo-map replay, repo-knowledge replay, transition replay integration, and empty-session edge cases. Also exercises `DeterministicHarness` directly.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests in this submodule. Production modules exercised: `core:events`, `core:journal`, `core:kernel`, `core:context`, `core:sessions`, `core:transitions`, `core:validation`, `core:approvals`, `core:artifacts`, `infrastructure:persistence`, `infrastructure:workflow`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Hard invariant #8: replay must complete without any external service calls, live LLM, or network.
|
||||
- Hard invariant #9: environment observations (filesystem, clock, embedder) must be read from recorded events — replay tests must not re-query the environment.
|
||||
- Every replay test must compare final state byte-for-byte (or field-for-field) against a known-good fixture.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Suspend tests use `runBlocking { ... }`.
|
||||
- Do not add `Thread.sleep()` or timing-sensitive assertions — replay is synchronous over a fixed event log.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:replay:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,29 @@
|
||||
# testing/transitions
|
||||
|
||||
## Purpose
|
||||
|
||||
Verifies `core:transitions` — the FSM/workflow graph layer. Covers: `DefaultTransitionResolver` correctness, transition event serialization round-trips, and fuzz coverage over random graph topologies.
|
||||
|
||||
## Ownership
|
||||
|
||||
Tests in this submodule. Production modules exercised: `core:transitions`, `core:events`, `core:inference`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `TransitionEventSerializationTest` pins that every transition event survives a serialize → deserialize round-trip without data loss; must be updated when new transition event types are added.
|
||||
- `TransitionFuzzTest` generates random graphs; add new resolver logic → extend the fuzz domain.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Suspend tests use `runBlocking { ... }`.
|
||||
- This is a narrow module — keep tests focused on graph resolution and serialization; cross-cutting concerns belong in `testing:integration` or `testing:deterministic`.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :testing:transitions:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
Reference in New Issue
Block a user