epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,101 @@
+---
+name: "System Overview"
+description: "System overview and core metaphor of Correx"
+depth: 2
+links:
+  - "../index.md"
+  - "./event-model.md"
+  - "./replay-model.md"
+  - "./context-layers.md"
+  - "./security-boundaries.md"
+---
+
+# system overview
+
+**version:** 0.1-draft  
+**status:** architectural narrative
+
+---
+
+## 1. what is correx?
+
+Correx is a **local‑first orchestration runtime** for structured LLM workflows. It provides a deterministic shell around probabilistic cognition, treating language models as interchangeable execution engines while owning memory, state, validation, and permissions.
+
+The system is not a chatbot framework. It is a config‑driven workflow orchestrator that treats every model output as an untrusted proposal and only advances state after multiple layers of validation and approval.
+
+---
+
+## 2. core metaphor
+
+**Harness is the brain, models are the muscles, Router is the face.**
+
+* **Harness (core kernel):** orchestrates workflow, owns lifecycle, validates everything, maintains event‑sourced state.
+* **Router:** conversational façade that chit‑chats with the user, provides summaries, and interprets steering; always available but never persists in execution context.
+* **Agents:** ephemeral, stateless workers that consume synthesized context and emit structured artifacts.
+* **Models:** stateless inference engines; they receive only a tightly compressed context pack and produce a single response.
+
+---
+
+## 3. key architectural properties
+
+| property | implementation |
+|----------|----------------|
+| event‑sourced | all state is derivable from immutable events |
+| deterministic‑enough | orchestration logic is deterministic; inference randomness is contained |
+| replayable | full session replay without original models or live tools |
+| provider‑agnostic | local GGUF and remote OpenAI‑compatible models are interchangeable |
+| context‑efficient | aggressive compression, budgeting, and layering prevents context bloat |
+| bounded autonomy | explicit tiers, approval gates, and cancellation boundaries |
+| validation‑first | every artifact passes routing → schema → semantic → approval validation |
+
+---
+
+## 4. system layers
+
+```
+┌─────────────────┐
+│     user        │
+└───────┬─────────┘
+        │
+        ▼
+┌─────────────────┐
+│   interfaces    │  cli, api, websocket, frontend
+└───────┬─────────┘
+        │
+        ▼
+┌─────────────────┐
+│   orchestration │  session life, stage scheduling, retry, coordination
+└───────┬─────────┘
+        │
+        ▼
+┌─────────────────┐
+│    core domain  │  events, transitions, validation, approvals, context, artifacts
+└───────┬─────────┘
+        │
+        ▼
+┌─────────────────┐
+│  infrastructure │  persistence, inference providers, tool runtime, sandboxing
+└─────────────────┘
+```
+
+Core never depends on infrastructure. Infrastructure implements contracts defined by core.
+
+---
+
+## 5. execution flow (simplified)
+
+1. User input arrives via Router.
+2. Session is created or resumed; projection rebuilt from events.
+3. Orchestrator determines next stage (from transition graph).
+4. Context Processor synthesises a ContextPack from L0–L2 layers.
+5. Inference module selects and calls the appropriate model.
+6. Model output is parsed into an artifact.
+7. Validation pipeline checks artifact (routing, schema, semantic, approval).
+8. If approved, transition engine evaluates conditions and moves to next stage.
+9. All steps are recorded as events.
+
+---
+
+## 6. design philosophy
+
+Correx is an **orchestration kernel** that enforces strict separation of concerns, immutability, and replayability. Reliability comes from explicit constraints, not from trusting model intelligence.