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.
2026-06-28 20:43:27 +04:00
parent 1cb7fec677
commit d26f20c316
48 changed files with 1783 additions and 0 deletions
@@ -0,0 +1,43 @@
+# core/router — AGENTS.md
+
+## Purpose
+
+Router facade and context assembly: builds the context pack delivered to each inference call, manages L3 cross-session memory retrieval, captures ideas from rubber-ducking sessions, and exposes `RouterFacade` as the primary entry point for the routing pipeline.
+
+## Ownership
+
+CORREX kernel team.
+
+## Local Contracts
+
+- `RouterFacade` — primary entry point; orchestrates `RouterContextBuilder`, L3 retrieval, and narration trigger evaluation.
+- `RouterContextBuilder` — assembles `ContextPack` from active session state, L3 memory hits, repo knowledge, ideas, and steering entries.
+- `RouterState` rebuilt from `RouterEvents` via `RouterReducer` + `RouterProjector`.
+- `RouterRepository` wraps `EventReplayer<RouterState>`.
+- `RouterResponse` — output from `RouterFacade`: rendered context + routing metadata.
+- `RouterConfig` — per-session router configuration (narration mode, L3 enabled, etc.).
+- `L3MemoryStore` / `RehydratableL3MemoryStore` / `InMemoryL3MemoryStore` — L3 cross-session memory interfaces. `RehydratableL3MemoryStore` uses `L3MetadataRehydrator` to restore from recorded events (Hard Invariant #9: L3 queries are recorded as events; replay reads the recorded hits, not the live index).
+- `L3Hit` / `L3MemoryEntry` / `L3Query` — L3 retrieval types.
+- `IdeaReader` / `Idea` / `Ideas` — reads `IdeaCaptured`/`IdeaDiscarded` events to surface idea state as a context feed.
+- `WorkflowProposals` / `WorkflowSummary` — proposal types for the workflow-propose panel.
+- `NarrationTrigger` — evaluates whether narration should be emitted on this turn.
+- Hard Invariant #9: L3 retrieval queries are recorded as events at query time. During replay, `L3MetadataRehydrator` restores the recorded hits — the live ANN index is never queried.
+
+## Work Guidance
+
+- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
+- `RouterReducer` only does `state.copy(...)`.
+- L3 memory is non-deterministic at query time (ANN search). Always record the hits as events immediately and read those recorded events in all downstream/replay paths.
+- `InMemoryL3MemoryStore` is for tests only; production wiring uses `RehydratableL3MemoryStore`.
+
+## Verification
+
+```bash
+./gradlew :core:router:test --rerun-tasks
+```
+
+Tests in `testing/deterministic/` (RouterContextBuilderTest, RouterFacadeTest, RouterNarrationTest, RouterProjectorTest, L3MetadataRehydratorTest).
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).