docs: add module documentation in AsciiDoc with PlantUML diagrams

Generated by per-group subagents covering all 52 modules across:
core (18), infrastructure (10), apps (5), interfaces (3),
plugins (7), testing (9)

Documentation format:
- AsciiDoc (.adoc) files in docs/modules/<group>/
- PlantUML (.puml) files in docs/diagrams/
- .adoc files reference diagrams via include:: directives

Each doc covers: purpose, responsibilities, non-responsibilities,
key types, event flow, integration points, invariants, PlantUML
diagram, known issues, and open questions.

docs/diagrams/app-cli.puml

@@ -0,0 +1,19 @@
+@startuml
+actor User
+participant CLI
+participant "Server\n(REST)" as REST
+participant "Server\n(WS)" as WS
+
+User -> CLI: correx run --workflow wf.toml
+CLI -> REST: POST /sessions {workflowId}
+REST --> CLI: sessionId
+CLI -> WS: ws /sessions/{id}/stream
+loop until SessionCompleted/Failed
+  WS --> CLI: StageStarted/Completed
+  WS --> CLI: ToolStarted/Completed/Failed
+  WS --> CLI: ApprovalRequired
+  User -> CLI: approve/reject/steer
+  CLI -> WS: ApprovalResponse
+end
+WS --> CLI: SessionCompleted/Failed
+@enduml

docs/diagrams/app-desktop.puml

@@ -0,0 +1,5 @@
+@startuml
+start
+:print "correx :: apps/desktop";
+stop
+@enduml

docs/diagrams/app-server.puml

@@ -0,0 +1,42 @@
+@startuml
+package "Server Module" {
+  [ServerModule] as SM
+  [GlobalStreamHandler] as GSH
+  [SessionStreamHandler] as SSH
+  [ApprovalCoordinator] as AC
+  [DomainEventMapper] as DEM
+  [LoggingEventStore] as LES
+  [SessionEventBridge] as SEB
+}
+
+package "Core Domain" {
+  [DefaultSessionOrchestrator] as DSO
+  [EventStore] as ES
+}
+
+package "Infrastructure" {
+  [DefaultProviderRegistry] as DPR
+  [ToolExecutor] as TE
+  [FileSystemWorkflowRegistry] as FSWR
+}
+
+SM --> LES : decorates
+SM --> DSO : orchestrator
+SM --> FSWR : workflowRegistry
+SM --> AC : creates
+SM --> ES : subscribeAll
+
+GSH --> SM : reads registries
+GSH --> DEM : map events
+GSH --> SEB : replaySnapshot
+
+SSH --> AC : registerClient
+SSH --> DEM : map events
+SSH --> DSO : cancel
+
+AC --> DSO : submitApprovalDecision
+AC --> SM.moduleScope : timeout jobs
+
+LES --> ES : delegates
+
+@enduml

docs/diagrams/app-tui.puml

@@ -0,0 +1,19 @@
+@startuml
+[KeyResolver] -> [RootReducer] : Action
+[WsClient.messages] -> [RootReducer] : ServerEventReceived
+[WsClient.connection] -> [RootReducer] : Connected/Disconnected/RetryScheduled
+
+[RootReducer] --> [SnapshotPhaseReducer]
+[RootReducer] --> [InputReducer]
+[RootReducer] --> [SessionsReducer]
+[RootReducer] --> [ConnectionReducer]
+[RootReducer] --> [ProviderReducer]
+
+[RootReducer] -> [EffectDispatcher] : List<Effect>
+[EffectDispatcher] -> [WsClient] : SendWs
+[EffectDispatcher] -> [System] : Quit
+
+clock over [WsClient] : exponential backoff reconnect
+
+[RootReducer] --> [Renderer] : TuiState
+@enduml

docs/diagrams/app-worker.puml

@@ -0,0 +1,5 @@
+@startuml
+start
+:print "correx :: apps/worker";
+stop
+@enduml

docs/diagrams/core-agents.puml

@@ -0,0 +1,3 @@
+@startuml
+note "core-agents: no source files" as N
+@enduml

docs/diagrams/core-approvals.puml

@@ -0,0 +1,46 @@
+@startuml
+interface ApprovalReducer
+interface ApprovalEngine
+interface Projection
+
+class DefaultApprovalReducer
+class DefaultApprovalEngine
+class NoOpApprovalEngine
+class ApprovalProjector
+class DefaultApprovalRepository
+class ApprovalState
+class DomainApprovalRequest
+class ApprovalDecision
+class ApprovalGrant
+class ApprovalContext
+
+ApprovalReducer <|.. DefaultApprovalReducer
+ApprovalEngine <|.. DefaultApprovalEngine
+ApprovalEngine <|.. NoOpApprovalEngine
+Projection <|.. ApprovalProjector
+ApprovalProjector --> ApprovalReducer
+DefaultApprovalRepository --> ApprovalProjector
+DefaultApprovalRepository ..> ApprovalState
+DefaultApprovalState --> "requests" DomainApprovalRequest
+DefaultApprovalState --> "decisions" ApprovalDecision
+DefaultApprovalState --> "grants" ApprovalGrant
+ApprovalDecision --> ApprovalContext
+DefaultApprovalEngine ..> ApprovalGrant
+DefaultApprovalEngine ..> ApprovalDecision
+DefaultApprovalEngine ..> ApprovalContext
+
+package "core:events" <<External>> {
+  [ApprovalRequestedEvent]
+  [ApprovalDecisionResolvedEvent]
+  [ApprovalGrantCreatedEvent]
+  [ApprovalGrantExpiredEvent]
+}
+package "core:sessions" <<External>> {
+  [Projection]
+  [EventReplayer]
+}
+DefaultApprovalReducer ..> "core:events"
+DefaultApprovalRepository ..> "core:events"
+DefaultApprovalRepository ..> "core:sessions"
+
+@enduml

docs/diagrams/core-artifacts-store.puml

@@ -0,0 +1,10 @@
+@startuml
+interface ArtifactStore
+
+package "core:events" <<External>> {
+  [ArtifactId]
+}
+
+ArtifactStore ..> "core:events"
+
+@enduml

docs/diagrams/core-artifacts.puml

@@ -0,0 +1,57 @@
+@startuml
+interface Artifact
+interface ArtifactReducer
+interface ArtifactKind
+interface ArtifactKindRegistry
+interface ArtifactRepository
+interface MaterializingArtifactWriter
+interface Projection
+
+class DefaultArtifactReducer
+class DefaultArtifactKindRegistry
+class ArtifactProjector
+
+class ArtifactState
+class ArtifactLineage
+class ArtifactRelationship
+class FileWrittenKind
+class ProcessResultKind
+class FileWrittenPayload
+class FileWrittenArtifact
+class ProcessResultArtifact
+class TypedArtifactSlot
+
+ArtifactReducer <|.. DefaultArtifactReducer
+ArtifactKindRegistry <|.. DefaultArtifactKindRegistry
+ArtifactKind <|.. FileWrittenKind
+ArtifactKind <|.. ProcessResultKind
+Projection <|.. ArtifactProjector
+ArtifactProjector --> ArtifactReducer
+
+DefaultArtifactKindRegistry --> ArtifactKind
+DefaultArtifactReducer ..> ArtifactState
+ArtifactState --> ArtifactLineage
+ArtifactLineage --> "relationships" ArtifactRelationship
+
+FileWrittenKind ..> FileWrittenPayload
+FileWrittenKind ..> FileWrittenArtifact
+ProcessResultKind ..> ProcessResultArtifact
+
+package "core:events" <<External>> {
+  [ArtifactCreatedEvent]
+  [ArtifactValidatingEvent]
+  [ArtifactValidatedEvent]
+  [ArtifactRejectedEvent]
+  [ArtifactSupersededEvent]
+  [ArtifactArchivedEvent]
+  [ArtifactRelationshipAddedEvent]
+}
+package "core:artifacts-store" <<External>> {
+  [ArtifactStore]
+}
+
+DefaultArtifactReducer ..> "core:events"
+ArtifactProjector ..> "core:events"
+MaterializingArtifactWriter ..> "core:artifacts-store"
+
+@enduml

docs/diagrams/core-config.puml

@@ -0,0 +1,18 @@
+@startuml
+!theme plain
+package "core-config" {
+  object ConfigLoader
+  class CorrexConfig
+  class ServerConfig
+  class TuiConfig
+  class CliConfig
+  class ApprovalConfig
+  class ToolsConfig
+}
+ConfigLoader --> CorrexConfig : loads
+CorrexConfig *--> ServerConfig
+CorrexConfig *--> TuiConfig
+CorrexConfig *--> CliConfig
+CorrexConfig *--> ApprovalConfig
+CorrexConfig *--> ToolsConfig
+@enduml

docs/diagrams/core-context.puml

@@ -0,0 +1,58 @@
+@startuml
+interface ContextPackBuilder
+interface DecisionPointBuilder
+interface ContextCompressor
+interface ContextReducer
+interface Projection
+
+class DefaultContextPackBuilder
+class DefaultDecisionPointBuilder
+class DefaultContextCompressor
+class DefaultContextReducer
+class ContextProjector
+class DefaultContextRepository
+
+class ContextPack
+class ContextEntry
+class ContextLayer
+class TokenBudget
+class CompressionMetadata
+class CompressionStrategy
+class SteeringNote
+class ContextState
+
+ContextPackBuilder <|.. DefaultContextPackBuilder
+DecisionPointBuilder <|.. DefaultDecisionPointBuilder
+ContextCompressor <|.. DefaultContextCompressor
+ContextReducer <|.. DefaultContextReducer
+Projection <|.. ContextProjector
+ContextProjector --> ContextReducer
+DefaultContextRepository --> ContextProjector
+
+DefaultContextPackBuilder --> ContextCompressor
+DefaultContextPackBuilder ..> ContextPack
+DefaultContextPackBuilder --> TokenBudget
+ContextPack --> "layers" ContextLayer
+ContextPack --> "entries" ContextEntry
+ContextPack --> CompressionMetadata
+DefaultContextCompressor --> CompressionStrategy
+DefaultContextCompressor --> TokenBudget
+DefaultDecisionPointBuilder ..> ContextPack
+DefaultDecisionPointBuilder --> ContextEntry
+
+package "core:events" <<External>> {
+  [ContextBuildingStartedEvent]
+  [ContextPackBuiltEvent]
+  [ContextBuildingFailedEvent]
+  [ContextBuildingInterruptedEvent]
+}
+package "core:sessions" <<External>> {
+  [Projection]
+  [EventReplayer]
+}
+
+DefaultContextReducer ..> "core:events"
+DefaultContextRepository ..> "core:events"
+DefaultContextRepository ..> "core:sessions"
+
+@enduml

docs/diagrams/core-events.puml

@@ -0,0 +1,114 @@
+@startuml
+package "core:events" {
+  interface EventPayload
+
+  abstract class NewEvent {
+    + metadata: EventMetadata
+    + payload: EventPayload
+  }
+
+  abstract class StoredEvent {
+    + metadata: EventMetadata
+    + sequence: Long
+    + sessionSequence: Long
+    + payload: EventPayload
+  }
+
+  class EventMetadata {
+    + eventId: EventId
+    + sessionId: SessionId
+    + timestamp: Instant
+    + schemaVersion: Int
+    + causationId: CausationId?
+    + correlationId: CorrelationId?
+  }
+
+  interface EventStore {
+    + append(NewEvent): StoredEvent
+    + read(SessionId): List<StoredEvent>
+    + subscribe(SessionId): Flow<StoredEvent>
+  }
+
+  class EventDispatcher {
+    + emit(EventPayload, SessionId, ...)
+  }
+
+  interface EventSerializer {
+    + serialize(EventPayload): String
+    + deserialize(String): EventPayload
+  }
+
+  class JsonEventSerializer
+
+  interface Projection<S> {
+    + initial(): S
+    + apply(S, StoredEvent): S
+  }
+
+  interface StateBuilder<S> {
+    + build(List<StoredEvent>): S
+  }
+
+  class DefaultStateBuilder<S>
+
+  interface EventReplayer<S> {
+    + rebuild(SessionId): S
+  }
+
+  class DefaultEventReplayer<S>
+
+  EventPayload <|.. SessionStartedEvent
+  EventPayload <|.. SessionPausedEvent
+  EventPayload <|.. WorkflowStartedEvent
+  EventPayload <|.. WorkflowCompletedEvent
+  EventPayload <|.. StageStartedEvent
+  EventPayload <|.. StageCompletedEvent
+  EventPayload <|.. TransitionExecutedEvent
+  EventPayload <|.. InferenceStartedEvent
+  EventPayload <|.. InferenceCompletedEvent
+  EventPayload <|.. ToolInvocationRequestedEvent
+  EventPayload <|.. ApprovalRequestedEvent
+  EventPayload <|.. ApprovalDecisionResolvedEvent
+  EventPayload <|.. ArtifactCreatedEvent
+  EventPayload <|.. ArtifactValidatedEvent
+  EventPayload <|.. RiskAssessedEvent
+  EventPayload <|.. ContextPackBuiltEvent
+  EventPayload <|.. OrchestrationPausedEvent
+  EventPayload <|.. OrchestrationResumedEvent
+  EventPayload <|.. RetryAttemptedEvent
+
+  NewEvent *-- EventMetadata
+  NewEvent *-- EventPayload
+  StoredEvent *-- EventMetadata
+  StoredEvent *-- EventPayload
+  EventDispatcher --> EventStore
+  EventDispatcher ..> NewEvent : creates
+
+  DefaultStateBuilder --> Projection
+  DefaultEventReplayer --> EventStore
+  DefaultEventReplayer --> DefaultStateBuilder
+
+  JsonEventSerializer ..|> EventSerializer
+  JsonEventSerializer --> eventJson
+
+  note right of EventPayload : 35+ concrete subtypes\nregistered in polymorphic block
+}
+
+package "shared types" {
+  value class TypeId
+  enum Tier
+  enum RiskLevel
+  enum RiskAction
+  sealed interface ApprovalStatus
+  enum ApprovalOutcome
+  sealed interface GrantScope
+  data class RetryPolicy
+  data class TokenUsage
+}
+
+TypeId <|.. SessionId
+TypeId <|.. StageId
+TypeId <|.. EventId
+TypeId <|.. ArtifactId
+
+@enduml

docs/diagrams/core-inference.puml

@@ -0,0 +1,73 @@
+@startuml
+interface InferenceProvider
+interface ProviderRegistry
+interface InferenceRouter
+interface RoutingStrategy
+interface InferenceCancellationToken
+interface Tokenizer
+interface InferenceReducer
+interface Projection
+
+class DefaultInferenceRouter
+class DefaultInferenceReducer
+class InferenceProjector
+class InferenceRepository
+
+class InferenceRequest
+class InferenceResponse
+class InferenceState
+class InferenceRecord
+class GenerationConfig
+class ToolCallRequest
+class ToolDefinition
+class ModelCapability
+class CapabilityScore
+class ProviderHealth
+class FinishReason
+class ResponseFormat
+
+enum InferenceStatus
+
+InferenceRouter <|.. DefaultInferenceRouter
+RoutingStrategy <|-- (DefaultInferenceRouter uses)
+InferenceProvider <|-- (DefaultInferenceRouter uses)
+ProviderRegistry <|-- (DefaultInferenceRouter uses)
+InferenceReducer <|.. DefaultInferenceReducer
+Projection <|.. InferenceProjector
+InferenceProjector --> InferenceReducer
+InferenceRepository --> InferenceProjector
+
+DefaultInferenceRouter --> RoutingStrategy
+DefaultInferenceRouter --> ProviderRegistry
+InferenceRequest --> GenerationConfig
+InferenceRequest --> "contextPack" ContextPack
+InferenceRequest --> "tools" ToolDefinition
+InferenceResponse --> "toolCalls" ToolCallRequest
+InferenceResponse --> FinishReason
+InferenceProvider --> Tokenizer
+InferenceRecord --> InferenceStatus
+
+package "core:events" <<External>> {
+  [InferenceStartedEvent]
+  [InferenceCompletedEvent]
+  [InferenceFailedEvent]
+  [InferenceTimeoutEvent]
+}
+package "core:context" <<External>> {
+  [ContextPack]
+}
+package "core:artifacts" <<External>> {
+  [JsonSchema]
+}
+package "core:sessions" <<External>> {
+  [Projection]
+  [EventReplayer]
+}
+
+DefaultInferenceReducer ..> "core:events"
+InferenceRepository ..> "core:events"
+InferenceRepository ..> "core:sessions"
+InferenceRequest ..> "core:context"
+ResponseFormat.Json ..> "core:artifacts"
+
+@enduml

docs/diagrams/core-kernel.puml

@@ -0,0 +1,130 @@
+@startuml
+package "core:kernel" {
+  abstract class SessionOrchestrator {
+    # emit()
+    # executeStage()
+    # runInference()
+    # resolveTransition()
+    + abstract run()
+    + abstract cancel()
+  }
+
+  class DefaultSessionOrchestrator {
+    + run()
+    + cancel()
+    + submitApprovalDecision()
+  }
+
+  class ReplayOrchestrator {
+    + run()
+    + cancel()
+    # runInference()
+    # mapValidationOutcome()
+  }
+
+  interface ApprovalGateway {
+    + submitApprovalDecision()
+  }
+
+  interface RetryCoordinator
+  class DefaultRetryCoordinator
+
+  data class OrchestratorRepositories
+  data class OrchestratorEngines
+
+  data class OrchestrationConfig
+  sealed interface WorkflowResult
+  sealed interface ReplayStrategy
+  sealed interface StageOutcome
+  interface OrchestrationReducer
+  class DefaultOrchestrationReducer
+  class OrchestrationProjector
+  class OrchestrationRepository
+
+  class ReplayInferenceProvider
+  class ReplayArtifactMissingException
+
+  DefaultSessionOrchestrator --|> SessionOrchestrator
+  DefaultSessionOrchestrator ..|> ApprovalGateway
+  ReplayOrchestrator --|> SessionOrchestrator
+
+  SessionOrchestrator *-- OrchestratorRepositories
+  SessionOrchestrator *-- OrchestratorEngines
+  SessionOrchestrator --> RetryCoordinator
+
+  DefaultRetryCoordinator ..|> RetryCoordinator
+  DefaultRetryCoordinator --> EventStore
+
+  ReplayOrchestrator --> ReplayInferenceProvider
+
+  OrchestrationProjector --> OrchestrationReducer
+  OrchestrationRepository --> EventReplayer
+}
+
+package "external modules" as EXT {
+  package ":core:events" as EV {
+    interface EventStore
+    interface EventReplayer
+    interface Projection
+  }
+
+  package ":core:sessions" as SES {
+    class DefaultSessionRepository
+    data class Session
+  }
+
+  package ":core:transitions" as TR {
+    interface TransitionResolver
+    data class WorkflowGraph
+    data class StageExecutionResult
+  }
+
+  package ":core:inference" as INF {
+    interface InferenceRouter
+    interface InferenceRepository
+    data class InferenceResponse
+  }
+
+  package ":core:context" as CTX {
+    interface ContextPackBuilder
+  }
+
+  package ":core:validation" as VAL {
+    interface ValidationPipeline
+  }
+
+  package ":core:approvals" as APR {
+    class DefaultApprovalRepository
+  }
+
+  package ":core:risk" as RSK {
+    interface RiskAssessor
+  }
+
+  package ":core:tools" as TOL {
+    interface ToolExecutor
+    interface ToolRegistry
+  }
+
+  package ":core:artifacts-store" as AST {
+    interface ArtifactStore
+  }
+}
+
+SessionOrchestrator --> EV
+SessionOrchestrator --> SES
+SessionOrchestrator --> TR
+SessionOrchestrator --> INF
+SessionOrchestrator --> CTX
+SessionOrchestrator --> VAL
+SessionOrchestrator --> APR
+SessionOrchestrator --> RSK
+SessionOrchestrator --> TOL
+SessionOrchestrator --> AST
+
+ReplayOrchestrator --> EXT
+
+note top of DefaultSessionOrchestrator : Live execution with\nreal inference, validation,\nrisk assessment, approvals
+note top of ReplayOrchestrator : Deterministic replay from\nevent log only
+
+@enduml

docs/diagrams/core-observability.puml

@@ -0,0 +1,6 @@
+@startuml
+!theme plain
+package "core-observability" {
+  object Module
+}
+@enduml

docs/diagrams/core-policies.puml

@@ -0,0 +1,6 @@
+@startuml
+!theme plain
+package "core-policies" {
+  object Module
+}
+@enduml

docs/diagrams/core-risk.puml

@@ -0,0 +1,18 @@
+@startuml
+!theme plain
+package "core-risk" {
+  interface RiskAssessor
+  class DefaultRiskAssessor
+  class NoOpRiskAssessor
+  class RiskContext
+  class TierMapping {
+    +toApprovalTier()
+    +toRiskAction()
+  }
+}
+RiskAssessor <|.. DefaultRiskAssessor
+RiskAssessor <|.. NoOpRiskAssessor
+DefaultRiskAssessor --> RiskContext : assess()
+NoOpRiskAssessor --> RiskContext : assess()
+TierMapping --> RiskAssessor : used by
+@enduml

docs/diagrams/core-router.puml

@@ -0,0 +1,78 @@
+@startuml
+interface RouterFacade
+interface RouterRepository
+interface RouterContextBuilder
+interface RouterReducer
+interface Projection
+
+class DefaultRouterFacade
+class DefaultRouterRepository
+class DefaultRouterContextBuilder
+class DefaultRouterReducer
+class RouterProjector
+
+class RouterState
+class RouterConfig
+class RouterResponse
+class RouterL2Entry
+class RouterTurn
+enum WorkflowStatus
+enum StageOutcomeKind
+enum TurnRole
+enum ChatMode
+
+RouterFacade <|.. DefaultRouterFacade
+RouterRepository <|.. DefaultRouterRepository
+RouterContextBuilder <|.. DefaultRouterContextBuilder
+RouterReducer <|.. DefaultRouterReducer
+Projection <|.. RouterProjector
+RouterProjector --> RouterReducer
+DefaultRouterRepository --> RouterProjector
+DefaultRouterRepository ..> RouterState
+
+DefaultRouterFacade --> RouterRepository
+DefaultRouterFacade --> RouterContextBuilder
+DefaultRouterFacade --> RouterConfig
+DefaultRouterFacade ..> RouterResponse
+DefaultRouterContextBuilder --> RouterConfig
+DefaultRouterContextBuilder --> RouterState
+DefaultRouterContextBuilder ..> "ContextPack"
+
+RouterState --> "l2Memory" RouterL2Entry
+RouterState --> "conversationHistory" RouterTurn
+RouterState --> WorkflowStatus
+RouterL2Entry --> StageOutcomeKind
+RouterTurn --> TurnRole
+
+package "core:events" <<External>> {
+  [EventStore]
+  [SteeringNoteAddedEvent]
+  [WorkflowStartedEvent]
+  [WorkflowCompletedEvent]
+  [WorkflowFailedEvent]
+  [OrchestrationPausedEvent]
+  [OrchestrationResumedEvent]
+  [StageCompletedEvent]
+  [StageFailedEvent]
+}
+package "core:inference" <<External>> {
+  [InferenceRouter]
+  [InferenceProvider]
+  [InferenceRequest]
+}
+package "core:context" <<External>> {
+  [ContextPack]
+}
+package "core:sessions" <<External>> {
+  [Projection]
+  [EventReplayer]
+}
+
+DefaultRouterFacade ..> "core:events"
+DefaultRouterFacade ..> "core:inference"
+DefaultRouterContextBuilder ..> "core:context"
+DefaultRouterRepository ..> "core:events"
+DefaultRouterRepository ..> "core:sessions"
+DefaultRouterReducer ..> "core:events"
+
+@enduml

docs/diagrams/core-sessions.puml

@@ -0,0 +1,65 @@
+@startuml
+package "core:sessions" {
+  enum SessionStatus {
+    CREATED
+    ACTIVE
+    PAUSED
+    COMPLETED
+    FAILED
+  }
+
+  data class SessionState {
+    + status: SessionStatus
+    + createdAt: Instant?
+    + updatedAt: Instant?
+  }
+
+  data class Session {
+    + sessionId: SessionId
+    + state: SessionState
+  }
+
+  interface SessionReducer {
+    + reduce(SessionState, StoredEvent): SessionState
+  }
+
+  class DefaultSessionReducer
+
+  class SessionProjector
+
+  class DefaultSessionRepository {
+    + getSession(SessionId): Session
+  }
+
+  sealed interface TransitionResult {
+    data class Applied
+    data object Rejected
+  }
+
+  enum ApprovalMode {
+    DENY
+    PROMPT
+    AUTO
+    YOLO
+  }
+
+  DefaultSessionReducer ..|> SessionReducer
+  SessionProjector --> SessionReducer
+  SessionProjector ..|> Projection
+
+  DefaultSessionRepository --> EventReplayer
+  DefaultSessionRepository ..> Session : creates
+  Session *-- SessionState
+}
+
+package ":core:events" as EVENTS {
+  interface Projection
+  interface EventReplayer
+  interface EventStore
+  enum SessionStatus as SES
+}
+
+DefaultSessionRepository --> EVENTS
+SessionProjector --> EVENTS
+
+@enduml

docs/diagrams/core-tools.puml

@@ -0,0 +1,51 @@
+@startuml
+interface Tool
+interface FileAffectingTool
+interface ToolExecutor
+interface ToolRegistry
+interface ToolReducer
+interface Projection
+
+class DefaultToolReducer
+class ToolProjector
+class DefaultToolRepository
+
+class ToolState
+class ToolInvocationRecord
+class ValidationResult
+enum ToolInvocationStatus
+enum ToolCapability
+
+Tool <|-- FileAffectingTool
+ToolReducer <|.. DefaultToolReducer
+Projection <|.. ToolProjector
+ToolProjector --> ToolReducer
+DefaultToolRepository --> ToolProjector
+DefaultToolRepository ..> ToolState
+ToolState --> "invocations" ToolInvocationRecord
+ToolInvocationRecord --> ToolInvocationStatus
+
+package "core:events" <<External>> {
+  [ToolInvocationRequestedEvent]
+  [ToolExecutionStartedEvent]
+  [ToolExecutionCompletedEvent]
+  [ToolExecutionFailedEvent]
+  [ToolExecutionRejectedEvent]
+  [ToolRequest]
+  [ToolReceipt]
+}
+package "core:approvals" <<External>> {
+  [Tier]
+}
+package "core:sessions" <<External>> {
+  [Projection]
+  [EventReplayer]
+}
+
+DefaultToolReducer ..> "core:events"
+DefaultToolRepository ..> "core:events"
+DefaultToolRepository ..> "core:sessions"
+Tool ..> "core:events"
+Tool ..> "core:approvals"
+
+@enduml

docs/diagrams/core-transitions.puml

@@ -0,0 +1,113 @@
+@startuml
+package "core:transitions" {
+  data class WorkflowGraph {
+    + id: String
+    + stages: Map
+    + transitions: Set
+    + start: StageId
+  }
+
+  data class StageConfig {
+    + requiredCapabilities
+    + tokenBudget
+    + generationConfig
+    + allowedTools
+    + produces
+  }
+
+  data class TransitionEdge {
+    + id: TransitionId
+    + from: StageId
+    + to: StageId
+    + condition: TransitionCondition
+  }
+
+  fun interface TransitionCondition {
+    + evaluate(EvaluationContext): Boolean
+  }
+
+  interface TransitionResolver {
+    + resolve(WorkflowGraph, EvaluationContext): TransitionDecision
+  }
+
+  class DefaultTransitionResolver
+
+  sealed interface TransitionDecision {
+    data class Move
+    data object Stay
+    data class Blocked
+    data object NoMatch
+  }
+
+  data class EvaluationContext {
+    + sessionId
+    + currentStage
+    + artifacts
+    + variables
+  }
+
+  fun interface TransitionConditionEvaluator
+  fun interface PromptResolver
+
+  interface StageExecutor
+  interface StageExecutionEventMapper
+
+  data class StageExecutionRequest
+  sealed interface StageExecutionResult {
+    data class Success
+    data class Failure
+  }
+
+  DefaultTransitionResolver ..|> TransitionResolver
+  DefaultTransitionResolver --> TransitionConditionEvaluator
+  DefaultTransitionResolver --> TransitionOrdering
+
+  WorkflowGraph *-- StageConfig
+  WorkflowGraph *-- TransitionEdge
+  TransitionEdge *-- TransitionCondition
+
+  TransitionResolver --> TransitionDecision
+  TransitionResolver --> EvaluationContext
+
+  StageExecutionEventMapper --> StageExecutionRequest
+  StageExecutionEventMapper --> StageExecutionResult
+  StageExecutionEventMapper --> EventPayload
+
+  package "conditions" {
+    class AlwaysTrue
+    class VariableEquals
+    class ArtifactPresent
+    class ArtifactAbsent
+    class ArtifactValidated
+    class AllOf
+    class AnyOf
+    class Not
+  }
+
+  AlwaysTrue ..|> TransitionCondition
+  VariableEquals ..|> TransitionCondition
+  ArtifactPresent ..|> TransitionCondition
+  AllOf ..|> TransitionCondition
+
+  package "cycle detection" {
+    class CycleExtractor
+    class CycleDfs
+    class DeterministicAdjacencyBuilder
+    object CycleCanonicalizer
+    data class DetectedCycle
+  }
+
+  package "cycle policy" {
+    sealed interface CyclePolicy {
+      data class Retry
+      data class Refinement
+      data class Approval
+    }
+    data class CycleSignature
+    data class CyclePolicyBinding
+    class CyclePolicyResolver
+    class PolicyValidation
+  }
+}
+
+@enduml

docs/diagrams/core-validation.puml

@@ -0,0 +1,60 @@
+@startuml
+interface Validator
+interface SemanticRule
+
+class ValidationPipeline
+class GraphValidator
+class TransitionValidator
+class SessionValidator
+class SemanticValidator
+class CyclePolicyBindingRule
+class ArtifactPayloadValidator
+class ApprovalTrigger
+
+class ValidationOutcome
+class ValidationReport
+class ValidationSection
+class ValidationIssue
+class ValidationContext
+
+package "core:transitions" <<External>> {
+  [WorkflowGraph]
+  [DetectedCycle]
+  [CyclePolicyBinding]
+  [TransitionEdge]
+}
+package "core:artifacts" <<External>> {
+  [FileWrittenArtifact]
+  [ProcessResultArtifact]
+}
+package "core:artifacts-store" <<External>> {
+  [ArtifactStore]
+}
+
+Validator <|.. GraphValidator
+Validator <|.. TransitionValidator
+Validator <|.. SessionValidator
+Validator <|.. SemanticValidator
+Validator <|.. ArtifactPayloadValidator
+SemanticValidator --> "rules" SemanticRule
+SemanticRule <|.. CyclePolicyBindingRule
+ValidationPipeline --> "validators" Validator
+ValidationPipeline --> ApprovalTrigger
+ValidationPipeline ..> ValidationOutcome
+ValidationOutcome --> ValidationReport
+ValidationOutcome ..> ApprovalRequest
+ValidationReport --> "sections" ValidationSection
+ValidationSection --> "issues" ValidationIssue
+ValidationIssue --> ValidationSeverity
+ValidationIssue --> ValidationLocation
+
+GraphValidator ..> "core:transitions"
+TransitionValidator ..> "core:transitions"
+SessionValidator ..> "core:sessions"
+CyclePolicyBindingRule ..> "core:transitions"
+ArtifactPayloadValidator ..> "core:artifacts"
+ArtifactPayloadValidator ..> "core:artifacts-store"
+ValidationContext ..> "core:transitions"
+ValidationContext ..> "core:sessions"
+
+@enduml

docs/diagrams/infra-artifacts-cas.puml

@@ -0,0 +1,36 @@
+@startuml
+!theme plain
+package "infra-artifacts-cas" {
+  class CasArtifactStore
+  class CasConfig
+  interface ArtifactIndex
+  class SqliteArtifactIndex
+  class SegmentLayout
+  class SegmentWriter
+  class SegmentReader
+  class Location
+  class TailScanner
+  class LivenessScanner
+  class Compactor
+  class Evictor
+  class DefaultMaterializingArtifactWriter
+}
+interface ArtifactStore <<core:artifactstore>>
+interface MaterializingArtifactWriter <<core:artifacts>>
+ArtifactStore <|.. CasArtifactStore
+MaterializingArtifactWriter <|.. DefaultMaterializingArtifactWriter
+CasArtifactStore *--> CasConfig
+CasArtifactStore *--> ArtifactIndex
+CasArtifactStore *--> SegmentWriter
+CasArtifactStore *--> SegmentReader
+ArtifactIndex <|.. SqliteArtifactIndex
+CasArtifactStore --> TailScanner : recover()
+CasArtifactStore --> Compactor : compact()
+CasArtifactStore --> Evictor : evict()
+Compactor --> LivenessScanner
+Evictor --> LivenessScanner
+TailScanner --> ArtifactIndex : uses
+TailScanner --> SegmentLayout : uses
+SegmentWriter --> SegmentLayout : uses
+SegmentReader --> SegmentLayout : uses
+@enduml

docs/diagrams/infra-inference-commons.puml

@@ -0,0 +1,15 @@
+@startuml
+!theme plain
+package "infra-inference-commons" {
+  interface ModelManager
+  interface ManagedInferenceProvider
+  class ModelDescriptor
+  enum ResidencyMode
+  class ModelLoadException
+}
+interface InferenceProvider <<core:inference>>
+ManagedInferenceProvider --|> InferenceProvider
+ModelManager --> ModelDescriptor : load()
+ManagedInferenceProvider --> ModelDescriptor : load()
+ModelDescriptor --> ResidencyMode
+@enduml

docs/diagrams/infra-inference-llama-cpp.puml

@@ -0,0 +1,28 @@
+@startuml
+!theme plain
+package "infra-inference-llama-cpp" {
+  class LlamaCppInferenceProvider
+  class DefaultModelManager
+  class DefaultManagedInferenceProvider
+  class LlamaProcess
+  class LlamaCppTokenizer
+  class GbnfGrammarConverter
+  package "LlamaCppApiModels" {
+    class ChatCompletionRequest
+    class ChatCompletionResponse
+    class ChatMessage
+  }
+}
+interface InferenceProvider <<core:inference>>
+interface ModelManager <<infra-inference-commons>>
+interface ManagedInferenceProvider <<infra-inference-commons>>
+InferenceProvider <|.. LlamaCppInferenceProvider
+ManagedInferenceProvider <|.. DefaultManagedInferenceProvider
+DefaultManagedInferenceProvider --> LlamaCppInferenceProvider : delegates to
+ModelManager <|.. DefaultModelManager
+DefaultModelManager *--> LlamaProcess : manages
+LlamaCppInferenceProvider --> LlamaCppTokenizer : uses
+LlamaCppInferenceProvider --> GbnfGrammarConverter : uses
+DefaultModelManager --> LlamaCppInferenceProvider : creates
+GbnfGrammarConverter --> ChatCompletionRequest : generates grammar for
+@enduml

docs/diagrams/infra-persistence.puml

@@ -0,0 +1,16 @@
+@startuml
+!theme plain
+package "infra-persistence" {
+  class InMemoryEventStore
+  class SqliteEventStore
+  class LiveArtifactRepository
+  class JDBCHelper
+}
+interface EventStore <<core:events>>
+ArtifactRepository <<core:artifacts>>
+EventStore <|.. InMemoryEventStore
+EventStore <|.. SqliteEventStore
+ArtifactRepository <|.. LiveArtifactRepository
+LiveArtifactRepository --> EventStore : subscribes
+SqliteEventStore --> JDBCHelper : uses
+@enduml

docs/diagrams/infra-scheduler.puml

@@ -0,0 +1,6 @@
+@startuml
+!theme plain
+package "infra-scheduler" {
+  object Module
+}
+@enduml

docs/diagrams/infra-security.puml

@@ -0,0 +1,6 @@
+@startuml
+!theme plain
+package "infra-security" {
+  object Module
+}
+@enduml

docs/diagrams/infra-telemetry.puml

@@ -0,0 +1,6 @@
+@startuml
+!theme plain
+package "infra-telemetry" {
+  object Module
+}
+@enduml

docs/diagrams/infra-tools-filesystem.puml

@@ -0,0 +1,19 @@
+@startuml
+!theme plain
+package "infra-tools-filesystem" {
+  class FileReadTool
+  class FileWriteTool
+  class FileEditTool
+}
+interface Tool <<core:tools>>
+interface ToolExecutor <<core:tools>>
+interface FileAffectingTool <<core:tools>>
+Tool <|.. FileReadTool
+Tool <|.. FileWriteTool
+Tool <|.. FileEditTool
+ToolExecutor <|.. FileReadTool
+ToolExecutor <|.. FileWriteTool
+ToolExecutor <|.. FileEditTool
+FileAffectingTool <|.. FileWriteTool
+FileAffectingTool <|.. FileEditTool
+@enduml

docs/diagrams/infra-tools.puml

@@ -0,0 +1,31 @@
+@startuml
+!theme plain
+package "infra-tools" {
+  class SandboxedToolExecutor
+  class DispatchingToolExecutor
+  class DefaultToolRegistry
+  class ShellTool
+  class DiffUtil
+  class ToolConfig
+  class ShellConfig
+  class FileReadConfig
+  class FileWriteConfig
+  class FileEditConfig
+}
+interface ToolExecutor <<core:tools>>
+interface ToolRegistry <<core:tools>>
+interface Tool <<core:tools>>
+ToolExecutor <|.. SandboxedToolExecutor
+ToolExecutor <|.. DispatchingToolExecutor
+ToolExecutor <|.. ShellTool
+ToolRegistry <|.. DefaultToolRegistry
+Tool <|.. ShellTool
+SandboxedToolExecutor --> ToolRegistry : resolves
+SandboxedToolExecutor --> ToolExecutor : delegates to
+DispatchingToolExecutor --> ToolRegistry : resolves
+SandboxedToolExecutor --> DiffUtil : uses
+ToolConfig --> ShellConfig
+ToolConfig --> FileReadConfig
+ToolConfig --> FileWriteConfig
+ToolConfig --> FileEditConfig
+@enduml

docs/diagrams/infra-workflow.puml

@@ -0,0 +1,22 @@
+@startuml
+!theme plain
+package "infra-workflow" {
+  interface WorkflowLoader
+  class TomlWorkflowLoader
+  class ConditionSpec
+  class ConditionFactory
+  interface PromptLoader
+  class FileSystemPromptLoader
+  class PromptNotFoundException
+  class WorkflowValidationException
+}
+interface WorkflowGraph <<core:transitions>>
+WorkflowLoader --> WorkflowGraph : load()
+WorkflowLoader <|.. TomlWorkflowLoader
+TomlWorkflowLoader --> ConditionSpec : parses
+TomlWorkflowLoader --> ConditionFactory : uses
+ConditionFactory --> ConditionSpec : converts
+PromptLoader <|.. FileSystemPromptLoader
+TommWorkflowLoader --> WorkflowValidationException : throws
+FileSystemPromptLoader --> PromptNotFoundException : throws
+@enduml

docs/diagrams/interface-api.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/interface-cli.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/interface-sdk.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/plugin-compressors.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/plugin-policies.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/plugin-providers.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/plugin-stages.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/plugin-tools.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/plugin-transitions.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/plugin-validators.puml

@@ -0,0 +1,3 @@
+@startuml
+note "No source files" as N
+@enduml

docs/diagrams/test-approvals.puml

@@ -0,0 +1,19 @@
+@startuml
+package "test-approvals" {
+  [TierImmutabilityTest]
+  [GrantSemanticsTest]
+  [ModeApprovalTest]
+  [ApprovalEngineEdgeCasesTest]
+  [NoExecutionCouplingTest]
+  [ApprovalTriggerTest]
+}
+
+[TierImmutabilityTest] --> [Tier]
+[GrantSemanticsTest] --> [DefaultApprovalEngine]
+[ModeApprovalTest] --> [DefaultApprovalEngine]
+[ApprovalEngineEdgeCasesTest] --> [DefaultApprovalEngine]
+[NoExecutionCouplingTest] --> [DefaultApprovalEngine]
+[ApprovalTriggerTest] --> [ApprovalTrigger]
+
+[Tests] --> [ApprovalFixtures] : test data
+@enduml

docs/diagrams/test-contracts.puml

@@ -0,0 +1,6 @@
+@startuml
+[Contract Tests] -> [Domain Types] : construct
+[Contract Tests] -> [kotlinx.serialization] : encode/decode
+[Domain Types] --> [Contract Tests] : value
+[Contract Tests] --> [Assertions] : verify contract
+@enduml

docs/diagrams/test-deterministic.puml

@@ -0,0 +1,21 @@
+@startuml
+package "test-deterministic" {
+  [SessionReplayDeterminismTest]
+  [ContextCompressionDeterminismTest]
+  [ApprovalEngineDeterminismTest]
+  [RouterProjectorTest]
+  [RouterFacadeTest]
+  [GraphValidatorTest]
+  [ValidationPipelineShortCircuitTest]
+  [DefaultContextPackBuilderTest]
+  [TokenBudgetEnforcementTest]
+}
+
+[SessionReplayDeterminismTest] --> [EventReplayer] : replay N times
+[ContextCompressionDeterminismTest] --> [ContextCompressor] : compress N times
+[ApprovalEngineDeterminismTest] --> [ApprovalEngine] : decide N times
+
+note right of [SessionReplayDeterminismTest]
+  assert: state == state == state
+end note
+@enduml

docs/diagrams/test-fixtures.puml

@@ -0,0 +1,20 @@
+@startuml
+package "test-fixtures" {
+  [EventFixtures]
+  [InferenceFixtures]
+  [ApprovalFixtures]
+  [WorkflowFixtures]
+  [TransitionFixtures]
+  [CycleFixtures]
+  [ContextFixtures]
+  [MockInferenceProvider]
+  [MockTokenizer]
+  [EchoTool]
+  [FailingTool]
+  [RejectedTool]
+  [MockEventReplayer]
+  [MockSessionRepository]
+}
+
+[Testing Modules] --> [test-fixtures] : reuse in tests
+@enduml

docs/diagrams/test-integration.puml

@@ -0,0 +1,13 @@
+@startuml
+[SessionOrchestratorIntegrationTest] -> [DefaultSessionOrchestrator] : run(sessionId, graph, config)
+[DefaultSessionOrchestrator] --> [EventStore] : append events
+[DefaultSessionOrchestrator] --> [MockEngines] : resolve/infer/validate/approve
+[Test] <- [EventStore] : read events
+[Test] <- [SessionRepository] : get session state
+
+[ValidationPipelineIntegrationTest] -> [ValidationPipeline] : validate(payload)
+[ValidationPipeline] -> [MockValidator1] : validate
+[ValidationPipeline] -> [MockValidator2] : validate
+[MockValidator*] --> [ValidationPipeline] : ValidationSection
+[Test] <- [ValidationPipeline] : ValidationReport
+@enduml

docs/diagrams/test-kernel.puml

@@ -0,0 +1,12 @@
+@startuml
+package "test-kernel" {
+  [DefaultRetryCoordinatorTest]
+  [ReplayInferenceProviderTest]
+  [MockOrchestrationEventReplayer]
+  [MockSessionEventReplayer]
+}
+
+[DefaultRetryCoordinatorTest] --> [DefaultRetryCoordinator]
+[ReplayInferenceProviderTest] --> [InferenceProjector]
+[ReplayInferenceProviderTest] --> [MockOrchestrationEventReplayer]
+@enduml

docs/diagrams/test-projections.puml

@@ -0,0 +1,8 @@
+@startuml
+[Test] -> [EventFixtures] : create event sequence
+[Test] -> [Projection] : project(events)
+[Projection] -> [Reducer] : reduce(state, event)
+[Reducer] --> [Projection] : new state
+[Projection] --> [Test] : final state
+[Test] --> [Assertions] : verify fields
+@enduml

docs/diagrams/test-replay.puml

@@ -0,0 +1,8 @@
+@startuml
+[Test] -> [EventFixtures] : create events
+[Test] -> [InMemoryEventStore] : append events
+[Test] -> [EventReplayer] : rebuild(sessionId)
+[EventReplayer] --> [Projection] : reduce events
+[Projection] --> [EventReplayer] : final state
+[Test] <-- [EventReplayer] : assert state matches expectation
+@enduml

docs/diagrams/test-transitions.puml

@@ -0,0 +1,7 @@
+@startuml
+[Test] -> [WorkflowFixtures] : graph
+[Test] -> [TransitionFixtures] : condition evaluator
+[Test] -> [DefaultTransitionResolver] : resolve(from, graph)
+[DefaultTransitionResolver] --> [Test] : next stage
+[Test] --> [Assertions]
+@enduml