# 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).