correx/docs/specs/2026-05-20-router/spec.md

spec

objective

Add :core:router — a resident conversational facade that maintains isolated L2 memory, routes inference requests to an LLM provider, and emits steering notes, while exposing a WebSocket-protocol interface for chat and steering interaction.

scope

in

• SteeringNote domain object and SteeringNoteAddedEvent in :core:context / :core:events (Task 0)
• RouterState, RouterReducer, RouterProjector, RouterRepository in :core:router (Tasks 1-2)
• RouterContextBuilder that assembles a budget-constrained ContextPack from L2 memory, workflow status, and conversation history (Task 3)
• RouterFacade that orchestrates state loading, context building, inference routing, and steering emission (Task 4)
• RouterConfig and RouterResponse types in :core:router (Task 4)
• Protocol layer additions: ClientMessage.ChatInput, ServerMessage.RouterResponseMessage, and ChatMode enum (Task 5)
• Infrastructure wiring: createRouterFacade() in InfrastructureModule and server WebSocket message routing (Task 5)
• Deterministic tests for reducer, projector, context builder, and facade

out

• L3 persistence (cross-session memory)
• Streaming inference responses
• Router-initiated workflow control (pause/cancel)
• Router system prompt configuration via harness.yaml
• Multiple concurrent router instances
• TUI changes (handled separately by the TUI module)
• GPU residency scheduling
• Context compression beyond the router's own L2 entries

invariants

• RouterState is always rebuilt from the event log — never persisted independently
• RouterContextPack never contains raw EventPayload objects, artifact content, or tool outputs
• The router emits only SteeringNoteAddedEvent to the event store — it never emits events that mutate workflow state
• In-memory conversation history is session-scoped (ConcurrentHashMap<SessionId, ...>) — no cross-session leakage
• L0 entries in the router ContextPack (system prompt, workflow status) are never dropped under budget pressure
• L2 entries (stage summaries) are evicted oldest-first under budget pressure
• Replay is environment-independent — no external service calls required for deterministic projection
• :core:router does not depend on :core:orchestration or :core:kernel — it reads state from events only
• Every new EventPayload must be registered in the eventModule polymorphic serialization block
• Inference requests from the router use the same cancellation semantics as orchestrator inference

inputs

• User chat messages via ClientMessage.ChatInput on WebSocket (sessionId, text, mode)
• Domain events on the event log: WorkflowStartedEvent, WorkflowCompletedEvent, WorkflowFailedEvent, OrchestrationPausedEvent, OrchestrationResumedEvent, StageCompletedEvent, StageFailedEvent
• RouterConfig — conversation keep-last count and token budget

outputs

• ServerMessage.RouterResponseMessage sent back over WebSocket (content, steeringEmitted flag)
• SteeringNoteAddedEvent appended to the event store when mode == ChatMode.STEERING
• RouterState — observable projection of router knowledge (L2 memory, workflow status, conversation history)

dependencies

• :core:events — event primitives, StoredEvent, EventPayload, EventStore, EventReplayer, serialization
• :core:context — TokenBudget, ContextPack, CompressionStrategy
• :core:inference — InferenceRouter, inference provider contract, cancellation semantics
• :core:sessions — SessionId, StageId, workflow type primitives
• Server WebSocket handler (existing infrastructure) for message dispatch
• TUI protocol types (existing) — PauseReason referenced by server message routing

assumptions

• InferenceRouter.route() returns an inference provider instance that can be called with a ContextPack
• EventStore supports both reading events (for replay) and writing events (for SteeringNoteAddedEvent) within the same module
• ContextPack already supports layered priority with L0/L1/L2 classification and budget-aware eviction
• The SessionConfigDto type referenced by ClientMessage.StartSession already exists and is shared across modules
• A Clock abstraction (or Clock.System) is available for deterministic timestamping
• The server WebSocket message router can be extended with a new when branch to dispatch ChatInput without breaking existing branches
• The server already has access to the InfrastructureModule component graph where RouterFacade will be injected

open questions

• Should ChatInput.sessionId be a SessionId domain type or remain a String? The existing protocol types (ServerMessage, ClientMessage) already use domain types like SessionId, StageId — consistency suggests SessionId would be preferred
• The existing InputMode enum in apps:tui has variants ROUTER, NAVIGATE, FILTER, STEER. Should the new ChatMode protocol enum mirror these exactly (e.g. ROUTER, STEER), or use a simpler two-variant enum (CHAT, STEERING)?
• Task 0 adds types to :core:context and :core:events — are these to be merged before task 1 starts, or is a single PR acceptable? The epic states "complete and merge before starting task 1."
• Does the server's CorrexServer.kt already have a WebSocket handler structure that can accommodate a ChatInput branch, or does the handler file need review to confirm the extension point?