kami
d26f20c316
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.
44 lines
2.5 KiB
Markdown
44 lines
2.5 KiB
Markdown
# 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).
|