push from SNAPKITTYWEST/sovereign-engine-v2

.env.example

@@ -0,0 +1,12 @@
+# SOVEREIGN ENGINE CONFIGURATION
+# Copy this to .env and add your keys
+
+# OpenRouter API Key (free credits - rotate daily)
+# Get from: https://openrouter.ai/keys
+OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY_HERE
+
+# Ollama API Key (if using cloud Ollama, otherwise leave blank for local)
+OLLAMA_API_KEY=
+
+# Ollama Base URL (default: local)
+OLLAMA_BASE_URL=http://localhost:11434

.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.so
+*.o
+*.obj
+.env
+.env.local
+*.worm
+*.bin
+/checkpoints/
+/continuity/
+.vscode/
+.idea/
+sovereign_gate/authority_sk.pem
+sovereign_gate/.node_sk
+sovereign_gate/*.pem.backup

ARCHITECTURE.md

@@ -0,0 +1,206 @@
+# SOVEREIGN PYTHON LLM ENGINE
+
+**A production-grade LLM agent framework with custom MoE routing, binary WORM storage, four-paradigm continuity, and native IPC — generated from a single DSL prompt.**
+
+---
+
+## Origin
+
+This entire codebase was generated from scratch in a single prompt using the **HyperKittyConstraintDSL** — a deterministic constraint specification that orchestrates multi-agent code generation with proof-backed output.
+
+One DSL. One prompt. Three coordinated agents. **16,784 lines of machine code.**
+
+```xml
+<HyperKittyConstraintDSL version="1.0">
+  <Meta>
+    <System>HK-OS</System>
+    <Mode>DETERMINISTIC-CONSTRAINT-BUILD</Mode>
+    <Output>PROOF_BACKED_ARTIFACT</Output>
+  </Meta>
+
+  <BooleanKernel>
+    <Primitive name="NAND">NAND(a,b)=1-ab</Primitive>
+    <Derived name="NOT">NAND(x,x)</Derived>
+    <Derived name="AND">NAND(NAND(a,b),NAND(a,b))</Derived>
+    <Derived name="OR">NAND(NAND(a,a),NAND(b,b))</Derived>
+    <Derived name="IMPLIES">OR(NOT(a),b)</Derived>
+    <Derived name="EQUAL">AND(IMPLIES(a,b),IMPLIES(b,a))</Derived>
+  </BooleanKernel>
+
+  <GlyphTypeSystem>
+    <Unit symbol="🧠" name="Cognition"/>
+    <Unit symbol="📚" name="Knowledge"/>
+    <Unit symbol="🔍" name="Search"/>
+    <Unit symbol="⚙" name="Transformation"/>
+    <Unit symbol="⚖" name="Constraint"/>
+    <Unit symbol="🔐" name="Proof"/>
+    <Unit symbol="🌐" name="Interface"/>
+  </GlyphTypeSystem>
+
+  <AgentModel>
+    <Invariant>active(I) => trusted(I)</Invariant>
+    <Invariant>entropy(I) <= 0.20</Invariant>
+  </AgentModel>
+
+  <QuantumConstraintLayer>
+    <Entropy>
+      <Bound>H <= 0.20</Bound>
+    </Entropy>
+  </QuantumConstraintLayer>
+
+  <ProofOutput>
+    <ProofStatus>PROOF_TRUE</ProofStatus>
+  </ProofOutput>
+
+  <FinalState>
+    <Artifact>PYTHON_C_BRIDGE_IR</Artifact>
+    <BinaryOutput>BBSTRING_MACHINEC_CODE</BinaryOutput>
+    <Orchestration>THREE_AGENT_WORKFLOW</Orchestration>
+  </FinalState>
+</HyperKittyConstraintDSL>
+```
+
+The DSL defines:
+- **Boolean kernel** — All logic gates derived from NAND (universal gate)
+- **Glyph type system** — Semantic types for agent roles
+- **Agent invariants** — Trust and entropy constraints enforced at build time
+- **DAG structure** — Acyclic routing graph validated before code generation
+- **Proof output** — Cryptographic hash commitment over all artifacts
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   SOVEREIGN ENGINE                        │
+├──────────────┬──────────────┬───────────────────────────┤
+│  Routing     │  Continuity  │  Machine Code Layer        │
+│              │              │                            │
+│  RegexParser │  EnvState    │  BytecodeAssembler         │
+│  ASTBuilder  │  SeedChain   │  MarshalCodec              │
+│  SymbolicGr. │  InodeState  │  BinaryIR                  │
+│  JordanTrans │  SharedMem   │  VMExecutor                │
+│  JacobianLen │  Manager     │  MachineCodeGen (x86-64)   │
+│  Constraints │              │  CTypesBridge              │
+│  SparseActiv │              │  DSLValidator              │
+│  NANDFilter  │              │  SovereignMachine          │
+│  Dispatch    │              │                            │
+│  MergeOutput │              ├───────────────────────────┤
+│  JordanMoE   │              │  Native ASM (NASM x86-64) │
+│              │              │                            │
+├──────────────┤              │  sovereign_runtime.asm     │
+│  Tools (34)  │              │  qra_tensor.asm            │
+│              │              │  ipc_dispatcher.asm        │
+│  filesystem  │              │  nand_kernel.asm           │
+│  code        │              │  jordan_blocks.asm         │
+│  git         │              │  entropy_gate.asm          │
+│  database    │              │  sovereign_link.asm        │
+│  documents   ├──────────────┤                            │
+│  web         │  IPC Layer   │                            │
+│  embeddings  │              │                            │
+│  audio       │  OpcodeReg   │                            │
+│  pytorch     │  IPCRouter   │                            │
+│              │  ipc_core.c  │                            │
+├──────────────┼──────────────┼───────────────────────────┤
+│  Core        │  Agents      │  Daemon                    │
+│              │              │                            │
+│  WORMFile    │  ReActAgent  │  PythonDaemon (TCP 19002)  │
+│  Checkpoint  │  ShadowAgent │  Swarm (fan_out/race)      │
+│  Evidence    │  Supervisor  │                            │
+│  Storage     │              │                            │
+└──────────────┴──────────────┴───────────────────────────┘
+```
+
+---
+
+## Key Innovations
+
+### Jordan Algebraic MoE Routing
+
+Replaces softmax gating with Jordan algebra (Spin Factor) composition:
+
+- **Non-associative** — Agent grouping topology changes routing output mathematically
+- **Fixed-point convergence** — Jordan squaring converges to idempotents (stable routing attractors)
+- **Spectral decomposition** — Provably unique expert assignment via eigenvalue separation
+
+### Four-Paradigm Continuity
+
+Agent state survives daemon restarts, crashes, and hot-reloads:
+
+| Paradigm | Mechanism | Speed | Use Case |
+|----------|-----------|-------|----------|
+| Env bitmask | `os.environ` (64-bit) | Fast | Hot restart via `os.execv` |
+| Seed chain | Blake2b derivation (24 bytes) | Fast | Deterministic replay |
+| Inode flags | Zero-byte files (`stat()`) | Kernel | Boolean state gates |
+| Shared memory | `ctypes` (4KB block) | RAM | Cross-process realtime |
+
+### Binary WORM Storage
+
+Append-only binary struct format — no JSON, no injection surface:
+
+- 152-byte fixed headers (magic + version + type + timestamps + Blake2b hash + Ed25519 sig)
+- Chain verification (each record hashes the previous)
+- Zero text parsing — immune to JSONL injection, newline attacks, XXE
+
+### Inverted AST with Payload Elimination
+
+Routing tree is structurally inverted:
+- Structural nodes (routing_weight=1.0) drive all decisions
+- Payload leaves (routing_weight=0.0) cannot propagate upward
+- Blocklist + XXE pattern detection at parse boundary
+
+### Native IPC Multiplexer
+
+Memory-mapped shared buffer with O(1) opcode dispatch:
+
+- 34 static opcodes (tools) + dynamic assignment from 0x0100
+- 50us polling loop (C core) or Python asyncio fallback
+- Zero serialization — raw struct read/write via mmap
+
+---
+
+## Line Counts
+
+| Component | Lines |
+|-----------|-------|
+| Python machine code layer | 9,251 |
+| NASM x86-64 assembly | 7,019 |
+| Routing pipeline | 1,900 |
+| Continuity layer | 1,536 |
+| Tool registration + IPC | 1,935 |
+| Core (storage, evidence) | 570 |
+| Agents (ReAct, Shadow, Supervisor) | 1,500 |
+| Daemon + Retrieval | 1,500 |
+| Sovereign machine wiring | 514 |
+| **Total** | **~25,700** |
+
+---
+
+## Build Constraints
+
+Every artifact in this repository satisfies:
+
+```
+ACTIVE(I) => TRUSTED(I)    -- Trust axiom
+ENTROPY(I) <= 0.20         -- Shannon bound (nats)
+NAND truth table verified   -- Boolean kernel complete
+DAG acyclic                 -- No routing cycles
+Glyph mapping injective    -- No type collisions
+ProofStatus = PROOF_TRUE   -- All constraints pass
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- No external dependencies (pure stdlib)
+- Optional: NASM for native assembly compilation
+- Optional: C compiler for IPC core dispatcher
+
+---
+
+## License
+
+Proprietary. Copyright SnapKitty / SNAPKITTYWEST.

LICENSE.tri

@@ -0,0 +1,48 @@
+TRI-LICENSE STRUCTURE
+=====================
+
+This project is available under THREE licensing options:
+
+1. Business Source License 1.1 (BSL-1.1)
+   - Source-available with commercial restrictions
+   - No managed service offerings at enterprise scale
+   - Converts to AGPL-3.0 after transition period (Change Date: 2028-08-08)
+
+2. GNU Affero General Public License v3.0 (AGPL-3.0)
+   - Strong network copyleft
+   - SaaS/network distribution triggers source disclosure
+   - All modifications must be AGPL-3.0
+
+3. Mozilla Public License 2.0 (MPL-2.0) + Commercial Dual License
+   - Weak copyleft (file-level)
+   - Can combine with proprietary code
+   - Modified files must remain MPL-2.0
+   - Commercial license available for copyleft bypass
+
+================================================================================
+
+WHICH LICENSE APPLIES?
+
+Use this engine itself to determine:
+
+  swipl -q -t halt -f license_policy.pl -- select <your_use_case>
+
+Use cases:
+  - saas_wrapper → AGPL-3.0
+  - enterprise_restricted → BSL-1.1
+  - file_level_mod → MPL-2.0
+  - copyleft_bypass → Commercial
+  - open_source_redistribution → AGPL-3.0
+
+================================================================================
+
+COPYRIGHT HOLDER
+
+Copyright (C) 2026 Ahmad Ali Parr
+Bel Esprit D'Accord Irrevocable Trust
+SnapKitty Collective Limited (FLP)
+
+Contact: ahmedparr93@gmail.com
+Web: https://github.com/SNAPKITTYWEST
+
+================================================================================

PRODUCTION_HARDENING.md

@@ -0,0 +1,2149 @@
+# PRODUCTION HARDENING PLAN — SOVEREIGN PYTHON LLM ENGINE
+
+**Target Audience:** Codex AI assistant (code implementation agent)  
+**Purpose:** Specification for hardening the Sovereign engine for production deployment  
+**Scope:** 8 major sections, ~200 actionable items  
+**Timeline Estimate:** 4-6 weeks at standard velocity  
+**Status:** Requirement specification (pre-implementation)
+
+---
+
+## CRITICAL SUCCESS CRITERIA
+
+All work must preserve or enhance these invariants:
+
+```
+✓ ACTIVE(I) ⟹ TRUSTED(I)              — No untrusted agent execution
+✓ ENTROPY(I) ≤ 0.20 nats              — Determinism bound
+✓ WORM append-only + tamper-detect    — No log mutation
+✓ PathJail + SSRFGuard hold all I/O   — Zero filesystem/network escape
+✓ ReAct max_steps enforced            — Runaway prevention
+✓ Tool approval + rate limit gates    — Malicious tool calls blocked
+✓ Continuity 4-paradigm restart cycle — No state loss on crash
+```
+
+---
+
+## 1. TERMINAL ACCESS IDE
+
+### Goal
+Rich terminal UI (pure Python curses) that displays live agent execution with routing visualization, tool latency, and continuity status.
+
+### 1.1 Core Terminal UI (`src/terminal/ui.py` — ~500 lines)
+
+**Deliverables:**
+- Split-pane layout: left = agent output, right = tool/routing activity
+- Live update loop (async, non-blocking)
+- Event queue from agent → UI bridge
+
+**Function Signatures:**
+
+```python
+class TerminalUI:
+    """Rich terminal interface for Sovereign engine."""
+    
+    def __init__(self, width: int = 200, height: int = 50):
+        """Initialize curses screen and panes."""
+        pass
+    
+    async def run(self, agent: ReActAgent) -> None:
+        """Main loop: poll agent, update panes, handle input."""
+        pass
+    
+    def render_left_pane(self, trajectory: AgentTrajectory) -> None:
+        """
+        Display agent thought/action/observation stream.
+        
+        Format per step:
+          [STEP 3]
+          💭 Thought: "Need to search for recent frameworks..."
+          ⚙️  Action: tool_call(web_search, {"query": "LLM frameworks 2026"})
+          👁️  Observation: "Found 14 results..."
+          ✅ Reflection: "Progress made, continue"
+        """
+        pass
+    
+    def render_right_pane(
+        self,
+        routing_state: dict[str, float],
+        tool_latencies: dict[str, float],
+        continuity_status: dict[str, Any]
+    ) -> None:
+        """
+        Display routing tree, tool performance, continuity flags.
+        
+        Sections:
+          ▶ Jordan MoE Routing
+            [Expert 0] weight=0.45 ████████░░
+            [Expert 1] weight=0.30 ██████░░░░
+            ...
+          ▶ Tool Performance (last 10 calls)
+            web_search    avg=42ms   max=105ms  calls=8
+            db_query      avg=15ms   max=67ms   calls=3
+          ▶ Continuity Status
+            env_bitmask: 0x001f (seed restored)
+            shared_mem: OK (4095/4096 bytes)
+            worm_ledger: 127 records
+        """
+        pass
+    
+    def render_status_bar(self, current_step: int, max_steps: int) -> None:
+        """Bottom status line: step count, elapsed time, agent state."""
+        pass
+```
+
+**Implementation Notes:**
+- Use Python `curses` (stdlib, all platforms)
+- Non-blocking input via `timeout(100)` (100ms refresh)
+- Queue-based communication from agent to UI (thread-safe)
+- WORM ledger tail displayed as a compact scrollable log
+
+---
+
+### 1.2 Reusable Curses Widgets (`src/terminal/widgets.py` — ~250 lines)
+
+**Deliverables:**
+- Pane container (split layout)
+- Progress bar / bar chart
+- Text scroller / log viewer
+- Notification banner
+
+**Class Signatures:**
+
+```python
+class Panel:
+    """Named rectangular region with border and title."""
+    
+    def __init__(self, x: int, y: int, width: int, height: int, title: str = ""):
+        pass
+    
+    def write(self, x: int, y: int, text: str, color: int = 7) -> None:
+        """Write text at (x, y) relative to panel origin."""
+        pass
+    
+    def clear(self) -> None:
+        """Erase all content."""
+        pass
+    
+    def border(self, style: str = "box") -> None:
+        """Draw border (box | rounded | none)."""
+        pass
+    
+    def render(self, stdscr) -> None:
+        """Write to curses screen."""
+        pass
+
+
+class ProgressBar:
+    """Horizontal bar showing percentage (0–100)."""
+    
+    def __init__(self, width: int = 40, filled_char: str = "█", empty_char: str = "░"):
+        pass
+    
+    def set_progress(self, value: float) -> None:
+        """Update progress (0.0–1.0)."""
+        pass
+    
+    def render(self) -> str:
+        """Return string representation."""
+        pass
+
+
+class ScrollableLog:
+    """Scrollable text buffer (vim-style navigation)."""
+    
+    def __init__(self, max_lines: int = 1000):
+        pass
+    
+    def append(self, line: str) -> None:
+        """Add line to log."""
+        pass
+    
+    def scroll(self, offset: int) -> None:
+        """Scroll by offset lines (negative = up)."""
+        pass
+    
+    def render(self, height: int) -> list[str]:
+        """Return visible lines."""
+        pass
+```
+
+---
+
+### 1.3 Vim-Style Keybindings (`src/terminal/keybinds.py` — ~150 lines)
+
+**Deliverables:**
+- Command mode (`:` prefix)
+- Navigation (hjkl, Page Up/Down, gg/G)
+- Pause/resume agent
+
+**Function Signatures:**
+
+```python
+class KeybindRegistry:
+    """Map terminal input to actions."""
+    
+    def __init__(self):
+        self.bindings: dict[str, Callable] = {}
+    
+    def register(self, key: str, action: Callable, mode: str = "normal") -> None:
+        """
+        Register key binding.
+        
+        Args:
+            key: Key code (e.g., "j", "Page_Down", "C-c")
+            action: Callable to invoke
+            mode: "normal" or "command"
+        """
+        pass
+    
+    def handle_input(self, ch: int, mode: str = "normal") -> tuple[str, Callable | None]:
+        """
+        Convert curses input to action.
+        
+        Returns:
+            (mode, action_func) or (mode, None) if no binding
+        """
+        pass
+
+
+# Predefined bindings:
+BINDINGS = {
+    "j":           scroll_down,
+    "k":           scroll_up,
+    "Page_Down":   scroll_page_down,
+    "Page_Up":     scroll_page_up,
+    "g":           scroll_top,
+    "G":           scroll_bottom,
+    "q":           quit,
+    " ":           pause_agent,
+    "r":           resume_agent,
+    "C-c":         emergency_stop,
+}
+```
+
+---
+
+## 2. ACCESSIBILITY
+
+### Goal
+All output (terminal, logs, errors) must support screen readers, high-contrast mode, and dyslexia-friendly rendering. Keyboard-only navigation. No color dependency.
+
+### 2.1 Screen Reader Support (`src/accessibility/screen_reader.py` — ~200 lines)
+
+**Deliverables:**
+- Semantic text descriptions for all UI elements
+- Status change announcements
+- Error message plain English
+
+**Function Signatures:**
+
+```python
+class AccessibilityBridge:
+    """Convert UI events to screen-reader-friendly text."""
+    
+    def __init__(self, output_file: Path | None = None):
+        """
+        Args:
+            output_file: Optional file to log accessibility text.
+                         If None, print to stdout for screen reader capture.
+        """
+        pass
+    
+    def announce(self, text: str, priority: str = "normal") -> None:
+        """
+        Announce text immediately.
+        
+        Args:
+            text: Plain English description (no emoji, no color codes)
+            priority: "normal" (queue) | "alert" (immediate) | "polite" (deferred)
+        
+        Example:
+            announce("Agent entered THINKING state. Step 3 of 10.")
+            announce("ERROR: Database query timeout. Retry with longer timeout.", priority="alert")
+        """
+        pass
+    
+    def format_tool_call(self, tool_name: str, args: dict[str, Any]) -> str:
+        """
+        Convert tool call to descriptive text.
+        
+        Example output:
+            "Called web_search with query: 'LLM frameworks 2026', max_results: 10"
+        """
+        pass
+    
+    def format_routing_decision(self, experts: dict[str, float]) -> str:
+        """
+        Describe which experts were activated.
+        
+        Example output:
+            "Routing decision: Expert0 weighted 0.45, Expert1 weighted 0.30, others suppressed"
+        """
+        pass
+    
+    def format_error(self, error: Exception, recovery: str | None = None) -> str:
+        """
+        Convert exception to plain English with recovery steps.
+        
+        Example:
+            format_error(
+                PathJailError("Path escapes jail"),
+                recovery="Ensure file path is within /workspace"
+            )
+            # Output: "Error: Cannot access that file path. It is outside the allowed directory. 
+            #          Solution: Ensure file path is within /workspace"
+        """
+        pass
+```
+
+---
+
+### 2.2 Contrast & Dyslexia (`src/accessibility/contrast.py` — ~200 lines)
+
+**Deliverables:**
+- High-contrast color palette (WCAG AAA compatible)
+- Dyslexia-friendly fonts (monospace, anti-aliased)
+- No ambiguous characters (0/O, 1/l/I, 5/S confusion)
+
+**Function Signatures:**
+
+```python
+class ContrastManager:
+    """Ensure terminal colors meet accessibility standards."""
+    
+    def __init__(self, mode: str = "normal"):
+        """
+        Args:
+            mode: "normal" | "high_contrast" | "dyslexia_friendly"
+        """
+        self.mode = mode
+        self.palette = self._init_palette()
+    
+    def get_color_pair(self, role: str) -> tuple[int, int]:
+        """
+        Get foreground, background curses color indices.
+        
+        Roles:
+            "text"           -> (fg, bg) for normal text
+            "thought"        -> for agent thinking
+            "action"         -> for tool calls
+            "observation"    -> for tool results
+            "error"          -> for errors
+            "success"        -> for completed steps
+            "warning"        -> for warnings
+            "status_active"  -> for active components
+            "status_idle"    -> for idle components
+        
+        Returns:
+            (fg_color_code, bg_color_code) per curses
+        """
+        pass
+    
+    def sanitize_output(self, text: str) -> str:
+        """
+        Remove ambiguous characters, add spacing.
+        
+        Rules:
+            - Replace 0/O ambiguity: 0 → O (context-aware) or use distinct rendering
+            - Replace 1/l/I: use font distinguishing
+            - Increase line spacing in output
+            - Ensure monospace rendering
+        """
+        pass
+    
+    def validate_contrast(self, fg: int, bg: int) -> float:
+        """
+        Return contrast ratio (1–21, target ≥7 for WCAG AAA).
+        
+        Raises:
+            AccessibilityError if ratio < 7
+        """
+        pass
+```
+
+---
+
+### 2.3 Keyboard-Only Navigation
+
+**Requirements (no implementation, validation only):**
+- All UI features reachable via keyboard
+- Tab order documented
+- Vim keybindings supported (j/k/hjkl)
+- Emergency stop (Ctrl+C) always works
+- No mouse clicks required
+
+**Test Cases:**
+```python
+# tests/accessibility/test_keyboard_nav.py
+
+def test_tab_order():
+    """Verify Tab cycles through all interactive elements."""
+    pass
+
+def test_vim_navigation():
+    """Verify j/k/hjkl/gg/G work without vim mode enabled."""
+    pass
+
+def test_no_mouse_required():
+    """Verify all features work with keyboard only."""
+    pass
+```
+
+---
+
+## 3. EDGE CASES & ERROR HANDLING
+
+### Goal
+Gracefully handle all failure modes: disk full, corrupt files, path traversal attempts, DNS rebinding, hung tools, queue overflow, model timeouts, C frontend crash.
+
+### 3.1 PathJail Extensions (`src/core/path_jail.py` — extend by ~100 lines)
+
+**Add Functions:**
+
+```python
+def detect_junction(path: Path) -> bool:
+    """
+    Detect Windows NTFS junction points (directory symlinks).
+    
+    On Windows, junctions are not symlinks but still can escape jail.
+    Use Windows API reparse point detection.
+    
+    Returns:
+        True if path is a junction, False otherwise
+    """
+    pass
+
+def safe_open_nofollow(path: Path, mode: str = 'r') -> io.IOBase:
+    """
+    Open file with O_NOFOLLOW equivalent (no symlink dereference).
+    
+    On POSIX: Use os.open with os.O_NOFOLLOW
+    On Windows: Check is_symlink() before opening
+    
+    Raises:
+        PathJailError if file is a symlink
+    """
+    pass
+
+def prevent_toctou_race(path: Path, operation: Callable) -> Any:
+    """
+    Execute operation on path with TOCTOU race prevention.
+    
+    Pattern: Stat → resolve → stat-again → assert unchanged → execute
+    
+    Args:
+        path: Path to operate on
+        operation: Callable(path) to execute
+    
+    Returns:
+        Result of operation
+    
+    Raises:
+        PathJailError if file changed between checks
+    """
+    pass
+```
+
+**Add to PathJail class:**
+
+```python
+def set_max_file_size(self, max_bytes: int) -> None:
+    """
+    Enforce max read size per operation.
+    
+    Args:
+        max_bytes: Maximum bytes to read (e.g., 1GB)
+    
+    Prevents: DoS by huge file read
+    """
+    self.max_file_size = max_bytes
+
+def read_safe(self, path: str | Path, max_size: int | None = None) -> bytes:
+    """
+    Read file with size enforcement.
+    
+    Checks available space before read.
+    
+    Raises:
+        PathJailError if file exceeds max_size
+    """
+    pass
+```
+
+---
+
+### 3.2 SSRFGuard Extensions (`src/core/path_jail.py` — extend SSRFGuard by ~80 lines)
+
+**Add Method:**
+
+```python
+class SSRFGuard:
+    """Prevent Server-Side Request Forgery."""
+    
+    async def resolve_and_check(self, hostname: str, port: int = 443) -> str:
+        """
+        DNS rebinding prevention: resolve hostname, check IP, then connect.
+        
+        Algorithm:
+          1. Resolve hostname to IP
+          2. Check IP against blocklist (private ranges, metadata, etc)
+          3. If OK, return IP
+          4. Return IP (not hostname) to caller for actual connection
+          5. On connect, verify IP matches resolved value
+        
+        Args:
+            hostname: Domain name
+            port: Port (only used for validation, not connection)
+        
+        Returns:
+            Verified IP address
+        
+        Raises:
+            SSRFError if IP is blocked or doesn't resolve
+        
+        Prevents:
+          - DNS rebinding: resolve → check → rebind → connect-to-different-IP
+          - Time-of-check-time-of-use: re-resolve before connect
+        """
+        pass
+    
+    def add_blocked_ip(self, ip: str) -> None:
+        """Dynamically add blocked IP."""
+        pass
+    
+    def is_blocked(self, ip: str) -> bool:
+        """Check if IP is in blocklist."""
+        pass
+```
+
+---
+
+### 3.3 Storage: Disk Full Handling (`src/core/storage.py` — extend by ~60 lines)
+
+**Add Functions:**
+
+```python
+def check_disk_space_before_write(
+    file_path: Path,
+    estimated_size: int
+) -> bool:
+    """
+    Pre-check available disk space.
+    
+    Args:
+        file_path: Target file path
+        estimated_size: Bytes to write
+    
+    Returns:
+        True if space available, False if full
+    
+    Raises:
+        OSError if path invalid
+    """
+    pass
+
+def write_with_space_check(
+    file_path: Path,
+    data: bytes,
+    min_free_space: int = 1_000_000  # 1MB minimum free
+) -> None:
+    """
+    Write to file, abort if disk nearly full.
+    
+    Raises:
+        IOError if insufficient space
+    """
+    pass
+
+# Update WORMFile class:
+class WORMFile:
+    def append_safe(self, record: WORMRecord) -> None:
+        """
+        Append record with disk-full protection.
+        
+        - Check space before write
+        - Write atomically (temp file + rename)
+        - On failure, truncate corrupt tail (not head)
+        """
+        pass
+```
+
+---
+
+### 3.4 Continuity: Shared Memory Cleanup (`src/continuity/shared_mem.py` — extend by ~100 lines)
+
+**Add Functions:**
+
+```python
+def cleanup_stale_shm_segments(max_age_seconds: int = 3600) -> int:
+    """
+    Clean up shared memory segments from dead processes.
+    
+    Algorithm:
+      1. List all /dev/shm/* or Windows shared memory
+      2. Check mtime (modification time)
+      3. If older than max_age_seconds AND no process holding it, delete
+      4. Log deletion
+    
+    Args:
+        max_age_seconds: Time threshold (default 1 hour)
+    
+    Returns:
+        Number of segments cleaned
+    
+    Raises:
+        OSError if cannot read /dev/shm
+    """
+    pass
+
+def detect_orphaned_shm(agent_id: str) -> bool:
+    """
+    Detect if agent has orphaned shared memory from crash.
+    
+    Returns:
+        True if orphaned SHM found, False if clean or in use
+    """
+    pass
+
+# Update SharedMemory class:
+class SharedMemory:
+    def __init__(self, agent_id: str, size: int = 4096):
+        """
+        Initialize shared memory with crash-recovery.
+        
+        - Detect orphaned segment from prior crash
+        - Zero-out if corrupted
+        - Initialize checksum
+        """
+        pass
+    
+    def validate_checksum(self) -> bool:
+        """
+        Verify ring buffer header checksum.
+        
+        Returns:
+            True if checksum valid, False if corrupted
+        """
+        pass
+    
+    def recover_from_corruption(self) -> None:
+        """
+        Reset SHM to safe state if checksum fails.
+        
+        Logs recovery action.
+        """
+        pass
+```
+
+---
+
+### 3.5 IPC: Mmap Corruption Detection (`src/tools/ipc_router.py` — extend by ~80 lines)
+
+**Add Functions:**
+
+```python
+def validate_ring_buffer_header(mmap_obj: mmap.mmap) -> tuple[bool, str]:
+    """
+    Verify ring buffer header integrity.
+    
+    Returns:
+        (is_valid, error_message)
+    
+    Checks:
+      - Magic bytes at offset 0
+      - Version byte at offset 4
+      - CRC32 at offset 8
+      - Write pointer in valid range
+      - Read pointer in valid range
+    """
+    pass
+
+def repair_corrupted_ring_buffer(mmap_obj: mmap.mmap) -> None:
+    """
+    Reset ring buffer to safe state.
+    
+    - Zero-out entire header
+    - Reset pointers to 0
+    - Recalculate checksum
+    - Log repair event
+    """
+    pass
+
+# Update IPCRouter class:
+class IPCRouter:
+    async def dispatch_with_corruption_check(self, opcode: int, payload: bytes) -> Any:
+        """
+        Dispatch opcode, detecting and recovering from mmap corruption.
+        
+        Raises:
+            IPCCorruptionError if corruption detected and unrecoverable
+        """
+        pass
+```
+
+---
+
+### 3.6 Routing: All-Experts-Masked Fallback (`src/routing/jordan_moe.py` — extend by ~40 lines)
+
+**Add Method:**
+
+```python
+class JordanMoERouter:
+    def route_with_fallback(self, signal: dict[str, float]) -> dict[str, float]:
+        """
+        Route signal to experts, with fallback if all masked.
+        
+        Algorithm:
+          1. Compute routing normally
+          2. If all weights = 0 (all masked):
+             a. Log warning
+             b. Fall back to uniform random distribution
+             c. OR use prior distribution (if available)
+             d. Return fallback weights
+        
+        Returns:
+            Expert → weight mapping (always sums to 1.0)
+        """
+        pass
+    
+    def get_current_masks(self) -> dict[str, bool]:
+        """Return which experts are currently masked."""
+        pass
+    
+    def set_emergency_fallback_mode(self, enabled: bool) -> None:
+        """
+        Enable/disable emergency fallback routing.
+        
+        When enabled and all experts masked, use uniform random.
+        When disabled, raise RoutingError.
+        """
+        pass
+```
+
+---
+
+### 3.7 Agent: Model Timeout & Backoff (`src/agents/react.py` — extend by ~100 lines)
+
+**Add to ReActAgent:**
+
+```python
+class ReActAgent:
+    def __init__(self, ..., timeout_config: TimeoutConfig | None = None):
+        """
+        Args:
+            timeout_config: Timeout and retry strategy
+        """
+        self.timeout_config = timeout_config or TimeoutConfig()
+    
+    async def call_model_with_retry(
+        self,
+        prompt: str,
+        max_retries: int = 3
+    ) -> str:
+        """
+        Call LLM with exponential backoff on timeout/rate-limit.
+        
+        Algorithm:
+          - Attempt 1: 30s timeout
+          - Attempt 2: 60s timeout, wait 2s before retry
+          - Attempt 3: 90s timeout, wait 4s before retry
+          - Raise ModelTimeoutError if all attempts fail
+        
+        Detects:
+          - Timeout (socket/asyncio timeout)
+          - Rate limit (429 HTTP status)
+          - Server error (500–599 HTTP)
+        
+        Args:
+            prompt: Input to model
+            max_retries: Max attempts
+        
+        Returns:
+            Model output
+        
+        Raises:
+            ModelTimeoutError
+            ModelRateLimitError
+        """
+        pass
+```
+
+**Add TimeoutConfig dataclass:**
+
+```python
+@dataclass
+class TimeoutConfig:
+    initial_timeout_sec: float = 30
+    max_timeout_sec: float = 120
+    backoff_multiplier: float = 2.0
+    initial_retry_delay_sec: float = 2
+    max_retry_delay_sec: float = 60
+    jitter_enabled: bool = True  # Add random noise to prevent thundering herd
+```
+
+---
+
+### 3.8 Shadow: Queue Overflow (`src/agents/shadow.py` — extend by ~60 lines)
+
+**Add to ShadowAgent:**
+
+```python
+class ShadowAgent:
+    def __init__(self, ..., max_queue_size: int = 10000):
+        """
+        Args:
+            max_queue_size: Max observations in queue before dropping
+        """
+        self.max_queue_size = max_queue_size
+        self.queue_depth_warn_threshold = 0.8 * max_queue_size
+    
+    async def append_observation(self, obs: str) -> None:
+        """
+        Append observation, dropping oldest if queue full.
+        
+        - If queue at 80% capacity, log warning
+        - If queue at 100% capacity, drop oldest, log error
+        - Track drop count for metrics
+        """
+        pass
+    
+    def get_queue_stats(self) -> dict[str, int]:
+        """
+        Return queue stats.
+        
+        Returns:
+            {
+                "size": current_size,
+                "max": max_size,
+                "dropped": total_dropped,
+                "utilization_percent": 100 * size / max
+            }
+        """
+        pass
+```
+
+---
+
+### 3.9 Tools: Per-Tool Timeout (`src/tools/registry.py` — extend by ~50 lines)
+
+**Add to ToolDefinition:**
+
+```python
+@dataclass
+class ToolDefinition:
+    # ... existing fields ...
+    
+    timeout_sec: float = 60  # Default 60s per tool call
+    max_retries: int = 1
+    retry_backoff_sec: float = 2.0
+```
+
+**Add function:**
+
+```python
+async def call_tool_with_timeout(
+    tool: ToolDefinition,
+    args: dict[str, Any],
+    logger: logging.Logger
+) -> Any:
+    """
+    Call tool with per-tool timeout enforcement.
+    
+    - Set asyncio timeout to tool.timeout_sec
+    - If timeout, cancel task and log
+    - Raise ToolTimeoutError
+    
+    Raises:
+        ToolTimeoutError
+        asyncio.TimeoutError (caught and converted)
+    """
+    pass
+```
+
+---
+
+### 3.10 Bridge: C Frontend Heartbeat (`src/bridge/http_server.py` — extend by ~80 lines)
+
+**Add heartbeat mechanism:**
+
+```python
+class HTTPBridge:
+    def __init__(self, ..., heartbeat_interval_sec: float = 5.0):
+        """
+        Args:
+            heartbeat_interval_sec: Interval to send heartbeats to C frontend
+        """
+        self.heartbeat_interval = heartbeat_interval_sec
+        self.last_frontend_ping: float | None = None
+    
+    async def heartbeat_monitor(self) -> None:
+        """
+        Periodically send heartbeat to frontend.
+        
+        - Send HTTP GET /health every heartbeat_interval seconds
+        - If no response for 3x interval, assume frontend dead
+        - Clean up resources (close WebSocket, free memory)
+        - Log frontend crash
+        """
+        pass
+    
+    async def handle_frontend_disconnect(self) -> None:
+        """
+        Called when frontend heartbeat fails.
+        
+        - Cancel any in-progress requests
+        - Save agent state (WORM checkpoint)
+        - Release mmap/IPC resources
+        - Log event
+        """
+        pass
+    
+    @property
+    def frontend_alive(self) -> bool:
+        """True if frontend responded to recent heartbeat."""
+        pass
+```
+
+---
+
+## 4. SECURITY HARDENING
+
+### Goal
+Extend PathJail/SSRFGuard, add rate limiting, cost tracking, emergency kill switch, validate inputs, prevent regex DoS.
+
+### 4.1 PathJail & SSRFGuard (See Section 3.1–3.2)
+
+---
+
+### 4.2 Rate Limiting (`src/tools/approval.py` — extend by ~150 lines)
+
+**Add class:**
+
+```python
+@dataclass
+class RateLimitPolicy:
+    """Per-tool rate limiting configuration."""
+    tool_name: str
+    max_calls_per_minute: int
+    max_calls_per_hour: int
+    burst_allowed: int = 5  # Allow burst up to 5 calls
+    
+@dataclass
+class RateLimitViolation:
+    """Result of rate limit check."""
+    violated: bool
+    calls_made: int
+    calls_remaining: int
+    reset_time_sec: float
+
+
+class RateLimiter:
+    """Token bucket rate limiter per tool."""
+    
+    def __init__(self, policy: RateLimitPolicy):
+        pass
+    
+    def check_rate_limit(self) -> RateLimitViolation:
+        """
+        Check if tool call allowed.
+        
+        Uses token bucket algorithm:
+          - Bucket has capacity = max_calls_per_minute
+          - Tokens regenerate at rate = capacity / 60 per second
+          - Each call consumes 1 token
+          - Burst = allow 5 calls above steady-state
+        
+        Returns:
+            RateLimitViolation with status
+        """
+        pass
+    
+    def get_stats(self) -> dict[str, int]:
+        """Return current rate limit stats."""
+        pass
+
+
+# Update ApprovalEngine:
+class ApprovalEngine:
+    def __init__(self, ..., rate_limit_policies: dict[str, RateLimitPolicy] | None = None):
+        """
+        Args:
+            rate_limit_policies: Tool name → RateLimitPolicy mapping
+        """
+        self.rate_limiters = {
+            name: RateLimiter(policy)
+            for name, policy in (rate_limit_policies or {}).items()
+        }
+    
+    async def check_rate_limit(self, tool_name: str) -> RateLimitViolation:
+        """Check if tool call violates rate limit."""
+        if tool_name not in self.rate_limiters:
+            return RateLimitViolation(violated=False, ...)
+        return self.rate_limiters[tool_name].check_rate_limit()
+    
+    async def check_approval(self, ...) -> ApprovalResult:
+        """Extended to also check rate limit."""
+        # Check rate limit first
+        rate_check = await self.check_rate_limit(tool.name)
+        if rate_check.violated:
+            return ApprovalResult(
+                approved=False,
+                reason=f"Rate limit exceeded: {rate_check.calls_remaining} calls remaining",
+                ...
+            )
+        # Then check existing approval logic
+        pass
+```
+
+---
+
+### 4.3 Cost Tracking (`src/tools/approval.py` — extend by ~120 lines)
+
+**Add class:**
+
+```python
+@dataclass
+class ToolCost:
+    """Cost of a single tool call."""
+    tool_name: str
+    cost_usd: float
+    timestamp: str
+    actor: str
+    duration_sec: float
+    tokens_used: int | None = None  # For LLM calls
+
+
+class CostTracker:
+    """Track cumulative cost of tool calls."""
+    
+    def __init__(self, ledger: WORMLedger):
+        self.ledger = ledger
+    
+    def log_cost(self, cost: ToolCost) -> None:
+        """
+        Log tool call cost to WORM.
+        
+        Records:
+          - tool_name
+          - cost_usd (e.g., 0.0012)
+          - duration
+          - tokens (if applicable)
+          - timestamp
+        """
+        pass
+    
+    async def get_total_cost(self, actor: str | None = None, since: datetime | None = None) -> float:
+        """
+        Compute total cost incurred.
+        
+        Args:
+            actor: Filter by actor (None = all)
+            since: Filter by time (None = all time)
+        
+        Returns:
+            Total cost in USD
+        """
+        pass
+    
+    async def get_cost_by_tool(self) -> dict[str, float]:
+        """Break down cost by tool."""
+        pass
+    
+    def set_monthly_budget_usd(self, budget: float) -> None:
+        """Set max monthly spending."""
+        pass
+    
+    async def check_budget(self, actor: str) -> tuple[bool, str]:
+        """
+        Check if remaining budget allows next tool call.
+        
+        Returns:
+            (budget_ok, reason)
+        """
+        pass
+
+
+# Update ApprovalEngine:
+class ApprovalEngine:
+    def __init__(self, ..., cost_tracker: CostTracker | None = None):
+        self.cost_tracker = cost_tracker
+    
+    async def check_approval(self, tool: ToolDefinition, ...) -> ApprovalResult:
+        """Extended to check cost budget."""
+        if self.cost_tracker:
+            budget_ok, reason = await self.cost_tracker.check_budget(actor)
+            if not budget_ok:
+                return ApprovalResult(approved=False, reason=reason, ...)
+        # Continue with existing checks
+        pass
+```
+
+---
+
+### 4.4 Emergency Kill Switch (`src/tools/supervisor.py` — extend by ~80 lines)
+
+**Add class:**
+
+```python
+class EmergencyKillSwitch:
+    """
+    Emergency stop: disable all tools immediately.
+    """
+    
+    def __init__(self, approval_engine: ApprovalEngine):
+        self.approval_engine = approval_engine
+        self._kill_switch_engaged = False
+    
+    def engage(self, reason: str, actor: str) -> None:
+        """
+        Engage kill switch: disable all tool execution.
+        
+        Args:
+            reason: Why kill switch engaged (logged)
+            actor: Who engaged it (logged)
+        
+        Effect:
+          - All subsequent tool calls return ApprovalResult(approved=False)
+          - WORM record created
+          - Alert sent to admin
+        """
+        pass
+    
+    def disengage(self, reason: str, actor: str) -> None:
+        """Disable kill switch (requires auth)."""
+        pass
+    
+    def is_engaged(self) -> bool:
+        """Check current state."""
+        pass
+    
+    def force_stop_all_agents(self) -> int:
+        """
+        Stop all running agents immediately.
+        
+        Returns:
+            Number of agents stopped
+        """
+        pass
+
+
+# Add to main engine init:
+def __init__(self, ...):
+    self.kill_switch = EmergencyKillSwitch(self.approval_engine)
+```
+
+---
+
+### 4.5 Input Validation (`src/core/types.py` — new file, ~150 lines)
+
+**Add validators:**
+
+```python
+class InputValidator:
+    """Validate all untrusted input."""
+    
+    MAX_MESSAGE_LENGTH = 100_000  # 100KB
+    MAX_QUERY_LENGTH = 10_000     # 10KB
+    REGEX_TIMEOUT_MS = 100
+    
+    @staticmethod
+    def validate_message_length(msg: str) -> None:
+        """Enforce max message length."""
+        if len(msg) > InputValidator.MAX_MESSAGE_LENGTH:
+            raise ValueError(
+                f"Message exceeds max length: {len(msg)} > {InputValidator.MAX_MESSAGE_LENGTH}"
+            )
+    
+    @staticmethod
+    def validate_unicode_normalization(text: str) -> str:
+        """
+        Normalize Unicode to prevent homograph attacks.
+        
+        - Decompose combining characters
+        - Detect confusable scripts (Latin + Cyrillic)
+        - Raise error if mixing detected
+        
+        Returns:
+            Normalized text
+        """
+        import unicodedata
+        nfc = unicodedata.normalize('NFC', text)
+        # TODO: Homograph detection
+        return nfc
+    
+    @staticmethod
+    def validate_regex_safe(pattern: str) -> bool:
+        """
+        Check regex for potential DoS (catastrophic backtracking).
+        
+        Algorithm:
+          - Use timeout-based check: compile pattern with timeout
+          - Test against sample inputs
+          - Raise error if timeout
+        
+        Or: Require patterns to match RE2 spec (no backtracking).
+        
+        Returns:
+            True if safe
+        
+        Raises:
+            RegexDoSError if pattern dangerous
+        """
+        pass
+    
+    @staticmethod
+    def validate_json_safe(json_str: str) -> Any:
+        """
+        Parse JSON with size limits.
+        
+        - Enforce max nesting depth (10)
+        - Enforce max string length (1MB)
+        - Reject duplicate keys (potential collision attack)
+        """
+        pass
+    
+    @staticmethod
+    def sanitize_sql_parameter(param: str) -> str:
+        """
+        Sanitize SQL parameter (for parameterized queries).
+        
+        Note: Should use parameterized queries, not escaping!
+        This is fallback only.
+        """
+        pass
+```
+
+---
+
+### 4.6 Crypto Verification (`src/core/crypto.py` — extend by ~100 lines)
+
+**Verify existing functionality and extend:**
+
+```python
+class CryptoManager:
+    """Manage cryptographic keys and operations."""
+    
+    def __init__(self, master_secret: bytes | None = None):
+        """
+        Args:
+            master_secret: 32-byte master secret (or load from secure store)
+        """
+        self.master_secret = master_secret
+    
+    def derive_key(self, context: str, length: int = 32) -> bytes:
+        """
+        Derive key from master secret using HKDF.
+        
+        Args:
+            context: String context (e.g., "worm_signing", "aes_encryption")
+            length: Byte length of derived key
+        
+        Returns:
+            Derived key
+        
+        Algorithm:
+            HKDF-SHA256(master_secret, context.encode(), length)
+        """
+        pass
+    
+    def rotate_key(self, old_key_id: str) -> str:
+        """
+        Rotate signing key: generate new key, mark old as retired.
+        
+        Args:
+            old_key_id: ID of key to retire
+        
+        Returns:
+            ID of new key
+        
+        Records rotation in WORM for audit trail.
+        """
+        pass
+    
+    def verify_signature_on_read(self, data: bytes, signature: bytes, key_id: str) -> bool:
+        """
+        Verify Ed25519 signature on data read from storage.
+        
+        Args:
+            data: Data to verify
+            signature: Signature bytes
+            key_id: ID of key to use for verification
+        
+        Returns:
+            True if signature valid
+        
+        Raises:
+            CryptoError if key_id not found
+        """
+        pass
+    
+    def get_key_metadata(self, key_id: str) -> dict[str, Any]:
+        """Get metadata about a key (created_at, retired_at, etc)."""
+        pass
+```
+
+---
+
+## 5. TESTING
+
+### Goal
+Comprehensive pytest suite (~2000 lines) covering unit, integration, and property-based tests.
+
+### 5.1 Unit Tests
+
+#### `tests/test_routing.py` (~400 lines)
+
+```python
+"""Test Jordan algebra MoE routing properties."""
+
+import pytest
+from src.routing.jordan_moe import SpinFactor, JordanMoERouter
+
+class TestSpinFactorAlgebra:
+    """Verify Jordan algebra axioms."""
+    
+    def test_commutativity(self):
+        """A ∘ B = B ∘ A"""
+        a = SpinFactor(2.0, [1.0, 0.0])
+        b = SpinFactor(3.0, [0.0, 1.0])
+        assert a.compose(b) == b.compose(a)
+    
+    def test_non_associativity(self):
+        """(A ∘ B) ∘ C ≠ A ∘ (B ∘ C) in general"""
+        a = SpinFactor(1.0, [1.0, 0.0])
+        b = SpinFactor(1.0, [0.0, 1.0])
+        c = SpinFactor(1.0, [1.0, 1.0])
+        
+        left = a.compose(b).compose(c)
+        right = a.compose(b.compose(c))
+        # Should differ (non-associative)
+        assert left != right
+    
+    def test_idempotent_convergence(self):
+        """x ∘ x ∘ x... converges to idempotent e where e ∘ e = e"""
+        x = SpinFactor(0.5, [0.2, 0.3])
+        
+        for _ in range(100):
+            x_new = x.compose(x)
+            # Eventually x ≈ e and e ∘ e ≈ e
+            if abs(x_new.scalar - x.scalar) < 1e-6:
+                # Converged, verify idempotency
+                e_squared = x_new.compose(x_new)
+                assert abs(e_squared.scalar - x_new.scalar) < 1e-6
+                break
+            x = x_new
+```
+
+#### `tests/test_storage.py` (~300 lines)
+
+```python
+"""Test WORM append-only and tamper detection."""
+
+import pytest
+from src.core.storage import WORMFile, WORMRecord
+from pathlib import Path
+
+class TestWORMAppendOnly:
+    """WORM records cannot be modified."""
+    
+    def test_append_writes_record(self, tmp_path):
+        """Appending writes record correctly."""
+        worm = WORMFile(tmp_path / "test.worm")
+        rec = WORMRecord(event_type="test", payload=b"hello")
+        
+        worm.append(rec)
+        
+        records = list(worm.read())
+        assert len(records) == 1
+        assert records[0].payload == b"hello"
+    
+    def test_chain_verification(self, tmp_path):
+        """Each record hashes the previous."""
+        worm = WORMFile(tmp_path / "test.worm")
+        rec1 = WORMRecord(event_type="evt1", payload=b"data1")
+        rec2 = WORMRecord(event_type="evt2", payload=b"data2")
+        
+        worm.append(rec1)
+        worm.append(rec2)
+        
+        records = list(worm.read())
+        # rec2.prev_hash should match rec1's content hash
+        assert records[1].prev_hash == records[0].content_hash
+    
+    def test_tamper_detection(self, tmp_path):
+        """Corrupt file fails verification."""
+        worm = WORMFile(tmp_path / "test.worm")
+        rec = WORMRecord(event_type="test", payload=b"data")
+        worm.append(rec)
+        
+        # Corrupt payload byte
+        with open(worm.path, 'r+b') as f:
+            f.seek(152 + 10)  # Skip header
+            f.write(b'X')
+        
+        # Reading should detect corruption
+        with pytest.raises(Exception):  # WORM corruption error
+            list(worm.read())
+```
+
+#### `tests/test_continuity.py` (~250 lines)
+
+```python
+"""Test 4-paradigm state save/restore/restart."""
+
+import pytest
+import os
+from src.continuity.manager import ContinuityManager
+
+class TestContinuityRestart:
+    """Agent state survives restart."""
+    
+    def test_env_state_preserved(self, tmp_path, monkeypatch):
+        """Environment bitmask restored on hot restart."""
+        base_dir = tmp_path / "continuity"
+        
+        # First session
+        mgr1 = ContinuityManager(base_dir=base_dir, agent_id="agent1")
+        mgr1.set_env_bitmask(0x001f)
+        mgr1.checkpoint()
+        
+        # Simulate restart
+        monkeypatch.delenv("SOVEREIGN_STEP", raising=False)
+        
+        # Second session
+        mgr2 = ContinuityManager(base_dir=base_dir, agent_id="agent1")
+        assert mgr2.was_restarted
+        assert mgr2.get_env_bitmask() == 0x001f
+    
+    def test_seed_chain_deterministic_replay(self, tmp_path):
+        """Seed-derived randomness is deterministic."""
+        base_dir = tmp_path / "continuity"
+        
+        # Session 1: record sequence
+        mgr1 = ContinuityManager(base_dir=base_dir, agent_id="agent1")
+        mgr1.set_seed_chain(b'test_seed')
+        values1 = [mgr1.derive_random() for _ in range(5)]
+        
+        # Session 2: replay
+        mgr2 = ContinuityManager(base_dir=base_dir, agent_id="agent1")
+        mgr2.set_seed_chain(b'test_seed')
+        values2 = [mgr2.derive_random() for _ in range(5)]
+        
+        assert values1 == values2
+```
+
+#### `tests/test_path_jail.py` (~250 lines)
+
+```python
+"""Test PathJail directory traversal prevention."""
+
+import pytest
+from src.core.path_jail import PathJail, PathJailError
+
+class TestPathJail:
+    """Verify all escapes blocked."""
+    
+    def test_relative_traversal_blocked(self, tmp_path):
+        """../.. escapes rejected."""
+        jail = PathJail([tmp_path])
+        
+        with pytest.raises(PathJailError, match="escapes jail"):
+            jail.resolve(tmp_path / "subdir" / ".." / ".." / "etc" / "passwd")
+    
+    def test_symlink_escape_blocked(self, tmp_path):
+        """Symlink outside root rejected."""
+        jail = PathJail([tmp_path])
+        (tmp_path / "etc").mkdir()
+        (tmp_path / "workspace").mkdir()
+        
+        # Create symlink inside jail pointing outside
+        import os
+        os.symlink("/etc/passwd", tmp_path / "workspace" / "link")
+        
+        with pytest.raises(PathJailError, match="escapes jail"):
+            jail.resolve(tmp_path / "workspace" / "link")
+    
+    def test_null_byte_injection_blocked(self, tmp_path):
+        """Null byte in path rejected."""
+        jail = PathJail([tmp_path])
+        
+        with pytest.raises(PathJailError, match="Null byte"):
+            jail.resolve(str(tmp_path) + "\x00/etc/passwd")
+    
+    def test_safe_path_allowed(self, tmp_path):
+        """Valid path inside root allowed."""
+        jail = PathJail([tmp_path])
+        (tmp_path / "safe.txt").touch()
+        
+        result = jail.resolve(tmp_path / "safe.txt")
+        assert result.exists()
+```
+
+#### `tests/test_ipc.py` (~200 lines)
+
+```python
+"""Test IPC ring buffer and opcode dispatch."""
+
+import pytest
+from src.tools.ipc_router import IPCRouter
+
+class TestIPCDispatch:
+    """Verify opcode routing and concurrency."""
+    
+    async def test_opcode_dispatch(self):
+        """Opcode routes to correct handler."""
+        router = IPCRouter()
+        handler_called = False
+        
+        async def mock_handler(payload):
+            nonlocal handler_called
+            handler_called = True
+            return b"result"
+        
+        router.register_opcode(0x10, mock_handler)
+        result = await router.dispatch(0x10, b"test")
+        
+        assert handler_called
+        assert result == b"result"
+    
+    def test_ring_buffer_overflow(self):
+        """Ring buffer wraps at boundary."""
+        router = IPCRouter()
+        # Write beyond buffer size
+        # Verify wrap-around works correctly
+        pass
+    
+    async def test_concurrent_dispatch(self):
+        """Multiple concurrent dispatch calls work."""
+        import asyncio
+        router = IPCRouter()
+        
+        async def handler(payload):
+            await asyncio.sleep(0.01)
+            return payload
+        
+        router.register_opcode(0x20, handler)
+        
+        # Launch 10 concurrent calls
+        tasks = [router.dispatch(0x20, f"msg{i}".encode()) for i in range(10)]
+        results = await asyncio.gather(*tasks)
+        
+        assert len(results) == 10
+```
+
+#### `tests/test_agent.py` (~200 lines)
+
+```python
+"""Test ReAct agent loop and continuity."""
+
+import pytest
+from src.agents.react import ReActAgent, ReActConfig
+
+class TestReActLoop:
+    """Verify agent reasoning loop."""
+    
+    async def test_thought_action_observation_cycle(self, mock_model, mock_tool_registry):
+        """Agent loops through thought → action → observation."""
+        agent = ReActAgent(mock_model, mock_tool_registry)
+        trajectory = await agent.run(task="test task")
+        
+        assert len(trajectory.steps) > 0
+        assert any(step.action_type == "tool_call" for step in trajectory.steps)
+    
+    async def test_max_steps_enforced(self, mock_model, mock_tool_registry):
+        """Agent stops at max_steps."""
+        config = ReActConfig(max_steps=3)
+        agent = ReActAgent(mock_model, mock_tool_registry, config=config)
+        
+        trajectory = await agent.run(task="test task")
+        
+        assert len(trajectory.steps) <= 3
+    
+    async def test_error_reflection(self, mock_model, mock_tool_registry):
+        """Agent reflects on errors."""
+        # Configure mock to return error on first tool call
+        mock_tool_registry.get_tool("test").side_effect = Exception("Tool error")
+        
+        config = ReActConfig(reflection_on_error=True)
+        agent = ReActAgent(mock_model, mock_tool_registry, config=config)
+        
+        trajectory = await agent.run(task="test")
+        
+        # Should include reflection step after error
+        assert any("reflection" in str(step).lower() for step in trajectory.steps)
+```
+
+### 5.2 Integration Tests
+
+#### `tests/integration/test_full_pipeline.py` (~250 lines)
+
+```python
+"""End-to-end task execution."""
+
+import pytest
+
+class TestFullPipeline:
+    """Task → agent → tools → result."""
+    
+    async def test_simple_task_execution(self, engine_fixture):
+        """Execute simple task end-to-end."""
+        task = "Search for 'LLM frameworks' and summarize top 3 results"
+        
+        result = await engine_fixture.run_task(task)
+        
+        assert result is not None
+        assert "framework" in result.lower() or "llm" in result.lower()
+    
+    async def test_tool_chain_execution(self, engine_fixture):
+        """Execute multi-tool task."""
+        task = "Download paper from arXiv, summarize key findings"
+        
+        result = await engine_fixture.run_task(task)
+        
+        # Verify multiple tools were used
+        assert engine_fixture.tool_call_count > 1
+    
+    async def test_failure_recovery(self, engine_fixture):
+        """Agent handles tool failure gracefully."""
+        # Simulate tool failure
+        engine_fixture.tools["web_search"].fail_next_call()
+        
+        task = "Search for something"
+        result = await engine_fixture.run_task(task)
+        
+        # Should succeed despite failure (agent reflects and recovers)
+        assert result is not None
+```
+
+#### `tests/integration/test_bridge.py` (~200 lines)
+
+```python
+"""Test HTTP bridge request/response cycle."""
+
+import pytest
+from src.bridge.http_server import HTTPBridge
+
+class TestHTTPBridge:
+    """Bridge between C frontend and Python engine."""
+    
+    async def test_request_response_cycle(self, bridge_fixture):
+        """Send request, receive response."""
+        request = {
+            "method": "run_task",
+            "params": {"task": "test"}
+        }
+        
+        response = await bridge_fixture.send(request)
+        
+        assert "result" in response or "error" in response
+    
+    async def test_heartbeat_keeps_bridge_alive(self, bridge_fixture):
+        """Heartbeat prevents timeout."""
+        # Simulate frontend not sending requests
+        import asyncio
+        await asyncio.sleep(10)
+        
+        # Bridge should still be alive
+        assert bridge_fixture.is_alive()
+    
+    async def test_frontend_crash_cleanup(self, bridge_fixture):
+        """Frontend crash triggers cleanup."""
+        # Simulate frontend crash
+        bridge_fixture.frontend_connection.close()
+        
+        # Wait for heartbeat to detect
+        await asyncio.sleep(bridge_fixture.heartbeat_interval * 3)
+        
+        # Cleanup should have occurred
+        assert bridge_fixture.agent_state_saved()
+```
+
+### 5.3 Property-Based Tests (Hypothesis)
+
+#### `tests/property/test_jordan.py` (~150 lines)
+
+```python
+"""Property-based testing of Jordan algebra."""
+
+from hypothesis import given, strategies as st
+import pytest
+
+class TestJordanProperties:
+    """Verify Jordan axioms hold for random inputs."""
+    
+    @given(
+        scalar1=st.floats(min_value=-1e6, max_value=1e6),
+        vector1=st.lists(st.floats(min_value=-100, max_value=100), min_size=3, max_size=3),
+        scalar2=st.floats(min_value=-1e6, max_value=1e6),
+        vector2=st.lists(st.floats(min_value=-100, max_value=100), min_size=3, max_size=3),
+    )
+    def test_commutativity_holds(self, scalar1, vector1, scalar2, vector2):
+        """A ∘ B = B ∘ A for all A, B"""
+        from src.routing.jordan_moe import SpinFactor
+        
+        a = SpinFactor(scalar1, vector1)
+        b = SpinFactor(scalar2, vector2)
+        
+        assert a.compose(b) == b.compose(a)
+    
+    @given(
+        scalars=st.lists(st.floats(min_value=-10, max_value=10), min_size=3, max_size=5)
+    )
+    def test_convergence_to_idempotent(self, scalars):
+        """Repeated squaring converges to idempotent."""
+        # TODO: Implement
+        pass
+```
+
+#### `tests/property/test_worm.py` (~150 lines)
+
+```python
+"""Property-based testing of WORM append-only."""
+
+from hypothesis import given, strategies as st
+
+class TestWORMInvariants:
+    """WORM append-only invariant never violated."""
+    
+    @given(
+        payloads=st.lists(st.binary(min_size=1, max_size=1000), min_size=1, max_size=100)
+    )
+    def test_append_only_never_loses_data(self, payloads, tmp_path):
+        """Every appended record remains readable."""
+        from src.core.storage import WORMFile, WORMRecord
+        
+        worm = WORMFile(tmp_path / "test.worm")
+        
+        for i, payload in enumerate(payloads):
+            rec = WORMRecord(event_type=f"event_{i}", payload=payload)
+            worm.append(rec)
+        
+        # Read all and verify
+        records = list(worm.read())
+        
+        assert len(records) == len(payloads)
+        for i, rec in enumerate(records):
+            assert rec.payload == payloads[i]
+```
+
+---
+
+## 6. PERFORMANCE OPTIMIZATION
+
+### Goal
+Profile hot paths, optimize to targets, lazy-load modules, cache results, use memory-mapping for large files.
+
+### 6.1 Routing Latency (`src/routing/jordan_moe.py` — profile + optimize)
+
+**Target:** <10ms for 8 experts
+
+```python
+# Add to JordanMoERouter:
+
+def profile_routing_latency(self, iterations: int = 1000) -> dict[str, float]:
+    """
+    Profile routing latency.
+    
+    Returns:
+        {
+            "mean_ms": average latency,
+            "p50_ms": 50th percentile,
+            "p99_ms": 99th percentile,
+            "max_ms": maximum,
+        }
+    """
+    pass
+
+# Optimization: Cache fixed-point results
+class JordanMoERouterCached:
+    def __init__(self):
+        self.cache = {}  # signal_hash -> weights
+    
+    def route_cached(self, signal: dict[str, float]) -> dict[str, float]:
+        """Route with memoization."""
+        signal_hash = hash(frozenset(signal.items()))
+        
+        if signal_hash in self.cache:
+            return self.cache[signal_hash]
+        
+        result = self.route(signal)
+        self.cache[signal_hash] = result
+        return result
+```
+
+---
+
+### 6.2 IPC Round-Trip (`src/tools/ipc_router.py` — profile + optimize)
+
+**Target:** <100μs mmap, <1ms HTTP fallback
+
+```python
+async def profile_ipc_latency(router: IPCRouter) -> dict[str, float]:
+    """
+    Profile IPC round-trip latency.
+    
+    Returns:
+        {
+            "mmap_mean_us": microseconds,
+            "mmap_p99_us": 99th percentile,
+            "http_mean_ms": milliseconds,
+        }
+    """
+    pass
+```
+
+---
+
+### 6.3 Connection Pooling (`src/runtime/providers/*.py`)
+
+**Add to all providers:**
+
+```python
+class ModelProvider:
+    def __init__(self, pool_size: int = 10):
+        self.pool = asyncio.Queue(maxsize=pool_size)
+        # Pre-populate with connections
+        for _ in range(pool_size):
+            self.pool.put_nowait(self._create_connection())
+    
+    async def get_connection(self):
+        """Get connection from pool."""
+        return await self.pool.get()
+    
+    async def release_connection(self, conn):
+        """Return connection to pool."""
+        await self.pool.put(conn)
+```
+
+---
+
+### 6.4 Lazy Module Loading (`src/tools/loader.py` — new/extend)
+
+```python
+class ToolLoader:
+    """Lazy-load tools on demand."""
+    
+    def __init__(self):
+        self.loaded_tools = {}  # tool_name -> module
+        self.loading_lock = asyncio.Lock()
+    
+    async def load_tool(self, tool_name: str):
+        """Load tool module on first use."""
+        async with self.loading_lock:
+            if tool_name in self.loaded_tools:
+                return self.loaded_tools[tool_name]
+            
+            module = __import__(f"src.tools.{tool_name}")
+            self.loaded_tools[tool_name] = module
+            return module
+```
+
+---
+
+### 6.5 Binary IR Memory-Mapping (`src/runtime/machine/binary_ir.py` — extend)
+
+```python
+class BinaryIRExecutor:
+    def execute_large_file_with_mmap(self, file_path: Path) -> Any:
+        """
+        Load large binary files via mmap instead of full read.
+        
+        Benefit: O(1) memory regardless of file size.
+        """
+        import mmap
+        
+        with open(file_path, 'rb') as f:
+            with mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) as mm:
+                # Execute against mmap view
+                return self.execute_ir(mm)
+```
+
+---
+
+## 7. DOCUMENTATION
+
+### Goal
+Complete docstrings, architecture diagrams, API reference, deployment guide, configuration reference.
+
+### 7.1 Docstring Convention
+
+**All public methods must include:**
+
+```python
+def my_function(param1: str, param2: int) -> dict[str, Any]:
+    """
+    One-line summary of what this does.
+    
+    Longer description if needed. Mention any important side effects.
+    
+    Args:
+        param1: Description of param1
+        param2: Description of param2 (default: X)
+    
+    Returns:
+        Description of return value
+    
+    Raises:
+        MyError: When condition occurs
+        OtherError: When other condition occurs
+    
+    Example:
+        >>> result = my_function("test", 42)
+        >>> print(result)
+        {...}
+    """
+    pass
+```
+
+### 7.2 Architecture Diagram (in README)
+
+Mermaid diagram showing:
+- Routing pipeline (input → JordanMoE → expert selection)
+- Continuity layer (4 paradigms, checkpoint/restore)
+- Tool dispatch (opcode registry → IPC)
+- Agent loop (ReAct + Shadow)
+- Bridge (HTTP server + C frontend)
+
+---
+
+### 7.3 API Reference
+
+Auto-generated from docstrings:
+
+```
+src/routing/
+  - jordan_moe.py
+    - SpinFactor
+    - JordanMoERouter
+src/agents/
+  - react.py
+    - ReActAgent
+    - ReActConfig
+src/tools/
+  - registry.py
+    - ToolRegistry
+    - ToolDefinition
+  - approval.py
+    - ApprovalEngine
+    - RateLimiter
+...
+```
+
+### 7.4 Deployment Guide
+
+Sections:
+- Prerequisites (Python 3.11+)
+- Installation (pip, virtual env)
+- Configuration (EngineConfig options)
+- Starting daemon (systemd / Docker / bare metal)
+- Health checks (HTTP /health endpoint)
+- Monitoring (WORM ledger queries, metrics)
+- Troubleshooting (common errors + recovery)
+
+### 7.5 Configuration Reference
+
+```python
+# All options documented:
+@dataclass
+class EngineConfig:
+    """Complete engine configuration."""
+    
+    model_provider: str = "bedrock"  # Which model provider
+    model_name: str = "claude-opus"
+    
+    continuity_base_dir: Path = Path.home() / ".sovereign" / "continuity"
+    enable_continuity: bool = True
+    
+    worm_ledger_path: Path | None = None
+    
+    approval_required_for_risky: bool = True
+    rate_limit_policies: dict[str, RateLimitPolicy] = field(default_factory=dict)
+    
+    # ... all documented with explanations
+```
+
+---
+
+## 8. CI/CD PIPELINE
+
+### Goal
+GitHub Actions workflow with tests, type checking, security scan, coverage reporting.
+
+### 8.1 `.github/workflows/ci.yml` (~150 lines)
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install pytest pytest-cov pyright bandit
+      
+      - name: Run pytest
+        run: pytest tests/ --cov=src --cov-report=xml
+      
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+  
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      
+      - name: Install pyright
+        run: pip install pyright
+      
+      - name: Type check
+        run: pyright src/
+  
+  nasm_check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Install NASM
+        run: sudo apt-get install -y nasm
+      
+      - name: Syntax check
+        run: nasm -f elf64 -o /dev/null native/*.asm
+  
+  c_compile:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Compile C core
+        run: gcc -c -o /dev/null native/ipc_core.c -Wall -Wextra
+  
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      
+      - name: Bandit security scan
+        run: |
+          pip install bandit
+          bandit -r src/ -f json -o bandit-report.json
+      
+      - name: Upload security report
+        uses: actions/upload-artifact@v3
+        with:
+          name: bandit-report
+          path: bandit-report.json
+```
+
+### 8.2 Pre-Commit Hooks (`.pre-commit-config.yaml`)
+
+```yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+        language_version: python3.11
+  
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        args: [--profile=black]
+  
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.280
+    hooks:
+      - id: pyright
+```
+
+---
+
+## IMPLEMENTATION PRIORITY
+
+### Phase 1: Crash Prevention (Week 1–2)
+1. Edge cases (3.1–3.10) — all error handling
+2. Input validation (4.5)
+3. Unit tests (5.1) — at least 50% coverage
+
+### Phase 2: Security (Week 2–3)
+1. PathJail extensions (3.1)
+2. SSRFGuard extensions (3.2)
+3. Rate limiting (4.2)
+4. Cost tracking (4.3)
+5. Emergency kill switch (4.4)
+6. Security tests
+
+### Phase 3: Features (Week 3–4)
+1. Terminal IDE (1.1–1.3)
+2. Accessibility (2.1–2.3)
+3. Integration tests (5.2)
+
+### Phase 4: Polish (Week 4–6)
+1. Performance optimization (6)
+2. Property-based tests (5.3)
+3. Documentation (7)
+4. CI/CD pipeline (8)
+
+---
+
+## DEFINITION OF DONE
+
+- [ ] All code passes pytest (2000+ lines coverage)
+- [ ] All public methods have docstrings (format: § 7.1)
+- [ ] CI/CD pipeline green on all Python 3.11–3.13
+- [ ] Security scan (bandit) passes
+- [ ] Type check (pyright) passes with 0 errors
+- [ ] WORM append-only invariant holds (proven by tests)
+- [ ] Routing latency < 10ms (profiled)
+- [ ] PathJail blocks all 20 traversal attacks (test cases)
+- [ ] Terminal IDE renders without flicker
+- [ ] Accessibility complies with WCAG 2.1 AA (screen reader compatible)
+- [ ] No external dependencies beyond Python 3.11 stdlib
+- [ ] Deployment guide tested on 3 platforms (Linux/macOS/Windows)
+
+---
+
+## CRITICAL NOTES FOR CODEX
+
+1. **No external deps** — Use only Python stdlib. No pip packages except dev tools (pytest, pyright, etc).
+2. **WORM immutability** — Every test must verify chain integrity. If one byte changes, chain breaks.
+3. **Continuity restart** — Test that agent survives daemon restart and can resume from exact step.
+4. **PathJail escape** — Try 50+ creative escapes (UNC paths, drive letters, junctions on Windows). All must fail.
+5. **Async/await** — All I/O must be async. No blocking calls in agent loop.
+6. **Error messages** — Plain English. No jargon. Include recovery steps.
+7. **Performance** — Profile before optimizing. Targets are hard (10ms routing, 100us IPC).
+8. **Docstrings** — Non-negotiable. Every public function must be documented.
+
+---
+
+**End of Specification**
+
+Document version: 1.0  
+Generated: 2026-08-06  
+Scope: Full production hardening of Sovereign Python LLM Engine  
+Target audience: Codex AI code implementation agent

README.md

@@ -0,0 +1,511 @@
+```
+   ____                              _                ______            _
+  / ___|  _____   _____ _ __ ___(_) __ _ _ __   | ____| _ __   __ _(_)_ __   ___
+  \___ \ / _ \ \ / / _ \ '__/ _ \ |/ _` | '_ \  |  _| | '_ \ / _` | | '_ \ / _ \
+   ___) | (_) \ V /  __/ | |  __/ | (_| | | | | | |___| | | | (_| | | | | |  __/
+  |____/ \___/ \_/ \___|_|  \___|_|\__, |_| |_| |_____|_| |_|\__, |_|_| |_|\___|
+                                    |___/                      |___/          v2.0
+```
+
+![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue)
+![C Win32](https://img.shields.io/badge/C-Win32%20Native-orange)
+![Lines](https://img.shields.io/badge/Lines-50%2C444-green)
+![License](https://img.shields.io/badge/License-BSL%201.1-yellow)
+![Storage](https://img.shields.io/badge/Storage-Binary%20WORM-red)
+![Routing](https://img.shields.io/badge/Routing-Jordan%20Algebra-purple)
+
+---
+
+## What This Is
+
+A **complete LLM agent development environment**: native C desktop IDE connected to a Python inference engine via memory-mapped IPC.
+
+This is not a wrapper. Not a LangChain clone. Not vibe-coded. This is:
+
+- A **C Win32 IDE** with text editor, ConPTY terminal, LSP, DAP debugging, Direct2D rendering, git integration — 47 source files, 4,459 lines of C
+- A **Python LLM engine** with custom MoE routing, binary storage, four-paradigm continuity, 34 tools, ReAct agents — 87 modules, 38,576 lines
+- A **NASM x86-64 assembly layer** with native runtime, QRA tensor ops, Jordan block computation, NAND kernel, IPC dispatcher — 7 files, 7,019 lines
+- A **C IPC dispatcher** with mmap ring buffer, opcode jump table, 50μs polling — 390 lines
+
+**50,444 lines of production code. 142 source files. Pure stdlib Python + raw C + NASM.**
+
+---
+
+## Table of Contents
+
+- [The System](#the-system)
+- [Quick Start](#quick-start)
+- [The IDE](#the-ide)
+- [The Engine](#the-engine)
+- [Machine Code Layer](#machine-code-layer)
+- [Routing Pipeline](#routing-pipeline)
+- [Continuity Layer](#continuity-layer)
+- [Tool System](#tool-system)
+- [Security Architecture](#security-architecture)
+- [Configuration](#configuration)
+- [The Mathematics](#the-mathematics)
+- [Origin: The DSL](#origin-the-dsl)
+- [Papers](#papers)
+- [Line Count](#line-count)
+
+---
+
+## The System
+
+```mermaid
+graph TB
+    subgraph "C Win32 IDE (4,459 lines)"
+        EDITOR[Editor + Buffer]
+        TERM[ConPTY Terminal]
+        LSP[LSP Client]
+        DAP[DAP Debugger]
+        UI[UI Layout + Direct2D]
+        GIT[Git Integration]
+        FCL[FCL Evaluator]
+    end
+
+    subgraph "IPC Bridge"
+        HTTP[HTTP Bridge :19000]
+        MMAP[mmap Ring Buffer]
+        PIPE[Named Pipe Protocol]
+    end
+
+    subgraph "Python Engine (38,576 lines)"
+        ROUTE[11-Stage Routing Pipeline]
+        AGENT[ReAct Agent + Shadow Observer]
+        TOOLS[34 Tools x 9 Namespaces]
+        CONT[4-Paradigm Continuity]
+        WORM[Binary WORM Storage]
+        QRA[QRA Router - 6 Glyphs]
+    end
+
+    subgraph "Native Layer (7,409 lines)"
+        ASM[NASM x86-64 Runtime]
+        IPC_C[C IPC Dispatcher]
+        VM[Stack VM + NAND Opcodes]
+        JORDAN_ASM[Jordan Blocks SSE2/AVX2]
+    end
+
+    EDITOR --> HTTP
+    TERM --> PIPE
+    HTTP --> ROUTE
+    MMAP --> IPC_C
+    ROUTE --> AGENT
+    AGENT --> TOOLS
+    AGENT --> CONT
+    AGENT --> WORM
+    IPC_C --> ASM
+    ASM --> JORDAN_ASM
+```
+
+---
+
+## Quick Start
+
+```bash
+git clone https://github.com/SNAPKITTYWEST/sovereign-engine-v2.git
+cd sovereign-engine-v2
+
+# Run the engine (zero dependencies)
+python -c "
+import asyncio
+from src.sovereign import SovereignEngine, EngineConfig
+
+async def main():
+    engine = SovereignEngine(EngineConfig())
+    result = await engine.run('Write a fibonacci function')
+    print(result)
+    engine.shutdown()
+
+asyncio.run(main())
+"
+```
+
+```bash
+# Build the C IDE (Windows — requires CMake + MSVC)
+cd ide/native
+cmake -B build -G "Visual Studio 17 2022"
+cmake --build build --config Release
+./build/Release/sovereign-ide.exe
+```
+
+---
+
+## The IDE
+
+**Location:** `ide/native/` — 47 C source files, 4,459 lines
+
+This is a native Win32 application. No Electron. No JavaScript. No web view. Direct2D GPU rendering, ConPTY pseudo-terminal, Win32 message loop.
+
+| Directory | Purpose | Key Files |
+|-----------|---------|-----------|
+| `core/` | Memory arena, event system, strings | `arena.c` (pool allocator), `events.c` (pub/sub) |
+| `editor/` | Gap buffer text editor | `buffer.c` (insert/delete O(1)), `document.c` (file model) |
+| `terminal/` | Embedded terminal | `conpty.c` (Windows ConPTY API) |
+| `ui/` | Layout engine | `layout.c` (split panes), `status_bar.h`, `project_tree.h` |
+| `bridge/` | Engine connection | `bridge_http.c` (HTTP client to Python :19000) |
+| `chat/` | Agent interaction | `pipe_client.c` (named pipe), `protocol.c` (message framing) |
+| `lsp/` | Language intelligence | `client.c` (Language Server Protocol) |
+| `dap/` | Debugging | Debug Adapter Protocol integration |
+| `git/` | Version control | `repository.c` (status, diff, commit) |
+| `fcl/` | Command language | `evaluator.c` (Formal Command Language interpreter) |
+| `graphics/` | Rendering | `d2d_renderer.h` (Direct2D hardware-accelerated) |
+| `platform/windows/` | OS layer | `application.c`, `window.c`, `shell.c` |
+| `build/` | Build system | `cmake_runner.c` (invoke cmake from IDE) |
+
+### How the IDE Talks to the Engine
+
+```
+┌────────────────┐         ┌──────────────────┐        ┌─────────────────┐
+│  C IDE         │  HTTP   │  Python Bridge   │        │  Engine         │
+│                │────────>│  :19000          │───────>│  Routing        │
+│  bridge_http.c │  JSON   │  http_server.py  │        │  Agent          │
+│                │<────────│                  │<───────│  Tools          │
+└────────────────┘         └──────────────────┘        └─────────────────┘
+
+┌────────────────┐         ┌──────────────────┐
+│  C IDE         │  mmap   │  C IPC Core      │  (native tools — no HTTP, no JSON)
+│                │────────>│  ipc_core.c      │  Latency: ~100μs round trip
+│  (direct call) │<────────│  opcode dispatch │
+└────────────────┘         └──────────────────┘
+
+┌────────────────┐         ┌──────────────────┐
+│  C IDE         │  pipe   │  Agent Chat      │  (streaming agent responses)
+│  pipe_client.c │────────>│  python_daemon   │
+│                │<────────│  :19002 TCP      │
+└────────────────┘         └──────────────────┘
+```
+
+---
+
+## The Engine
+
+**Location:** `src/` — 87 Python modules, 38,576 lines
+
+Every module is **pure Python 3.11+ stdlib**. Zero external dependencies. No pip install needed.
+
+| Package | Lines | What It Does |
+|---------|-------|-------------|
+| `src/routing/` | 2,800 | 11-stage MoE pipeline: regex → AST → symbolic graph → Jordan transform → Jacobian → constraints → sparse activation → NAND filter → dispatch → merge |
+| `src/runtime/machine/` | 9,251 | CPython bytecode assembler, .pyc marshal codec, ctypes C bridge, SOVEREIGN_IR binary format, stack VM with NAND opcodes, x86-64 machine code generator |
+| `src/tools/` | 3,500 | 34 tools (filesystem, code, git, database, documents, web, embeddings, audio, pytorch), IPC router, opcode registry, approval engine, supervisor |
+| `src/continuity/` | 1,536 | Env bitmask, seed chain, inode flags, shared memory, unified manager |
+| `src/agents/` | 1,500 | ReAct loop (thought→action→observation→reflection), shadow observer, MCTS |
+| `src/retrieval/` | 1,500 | Semantic chunker (6 strategies), vector store, RAG pipeline, parallel ingest |
+| `src/daemon/` | 823 | Asyncio TCP daemon (:19002), swarm orchestration (fan_out, map_reduce, race) |
+| `src/bridge/` | 900 | HTTP server (:19000), stdio JSON-RPC, routing trace collector, key manager |
+| `src/core/` | 700 | Binary WORM storage, evidence ledger, Ed25519 crypto, path jail, SSRF guard |
+| `src/runtime/providers/` | 600 | Bedrock, OpenRouter, Ollama, Anthropic, OpenAI adapters + QRA router |
+| `src/models/` | 500 | Pydantic entities, state machines |
+| `src/scanner/` | 400 | AST analyzer, dependency graph builder |
+| `src/inference/` | 300 | Quantum MoE (SpinFactor composition) |
+| `src/mcp/` | 250 | Model Context Protocol server |
+| `src/cli/` | 200 | Command-line interface |
+
+---
+
+## Machine Code Layer
+
+**Location:** `src/runtime/machine/` (Python) + `native/asm/` (NASM)
+
+This is not a toy abstraction. These are real implementations:
+
+### Python Machine Code (`src/runtime/machine/` — 9,251 lines)
+
+| Module | Lines | What It Actually Does |
+|--------|-------|----------------------|
+| `bytecode_assembler.py` | 1,711 | Emits real CPython opcodes (LOAD_FAST, CALL_FUNCTION, etc). Produces executable code objects. |
+| `marshal_codec.py` | 1,435 | Reads and writes actual .pyc binary format (magic number, flags, code objects, consts table). |
+| `ctypes_bridge.py` | 970 | Builds C struct definitions from Python, manages MemoryArena for native allocations. |
+| `binary_ir.py` | 1,492 | SOVEREIGN_IR format: 32-byte fixed-width node records. Opcode + flags + operands + type tag. Scannable without parsing. |
+| `vm_executor.py` | 1,680 | Stack-based virtual machine. 40+ opcodes including custom NAND, JORDAN_MUL, ENTROPY_CHECK. Runs SOVEREIGN_IR bytecode. |
+| `machine_code_gen.py` | 1,104 | Emits raw x86-64 bytes. REX prefixes, ModR/M encoding, register allocation. Produces executable buffers via mmap+mprotect. |
+| `dsl_validator.py` | 658 | Validates all DSL constraints: Boolean kernel (NAND truth table), entropy ≤ 0.20, trust axiom, glyph injectivity, DAG acyclicity. Blake2b proof hash. |
+
+### NASM x86-64 Assembly (`native/asm/` — 7,019 lines)
+
+| File | Lines | What It Actually Does |
+|------|-------|----------------------|
+| `sovereign_runtime.asm` | 2,459 | Main runtime: WORM append (struct pack → write syscall), ring buffer management, signal handling, mmap allocation |
+| `ipc_dispatcher.asm` | 1,071 | Polls mmap region, reads 16-bit opcode, jump table dispatch (34 entries), writes response struct back |
+| `qra_tensor.asm` | 905 | 6x6 matrix multiply (packed SSE2), QLG balance check (x₀²+x₁²+x₂²=1 over ℤ), glyph classification |
+| `nand_kernel.asm` | 790 | NAND gate truth table in SIMD, builds NOT→AND→OR→IMPLIES→EQUAL per DSL BooleanKernel spec |
+| `jordan_blocks.asm` | 770 | SpinFactor product in SSE2/AVX2: scalar×scalar + dot product, scalar×vector + scalar×vector. Batch 4 elements. |
+| `entropy_gate.asm` | 552 | Shannon entropy H=-Σp·ln(p) via x87 FPU. Compare against 0.20 threshold. Set carry flag on violation. |
+| `sovereign_link.asm` | 472 | Public symbol table: exports all above as callable from C (System V ABI on Linux, MS x64 on Windows) |
+
+---
+
+## Routing Pipeline
+
+11 stages. Every stage has a mathematical role. This is not a prompt chain.
+
+```
+User Input
+    │
+    ├─── Stage 1: Regex Parser ──────── Tokenize. Strip dangerous patterns.
+    │                                    Blocklist: eval, exec, import, __,
+    │                                    base64, <script, <!ENTITY, SYSTEM
+    │
+    ├─── Stage 2: AST Builder ───────── Build INVERTED syntax tree.
+    │                                    Structural nodes: routing_weight=1.0
+    │                                    Payload leaves: routing_weight=0.0
+    │                                    Payloads CANNOT propagate upward.
+    │
+    ├─── Stage 3: Symbolic Graph ────── Adjacency matrix of signal flow.
+    │                                    Nodes = intent categories.
+    │                                    Edges = co-occurrence weights.
+    │
+    ├─── Stage 4: Jordan Transform ──── SpinFactor composition.
+    │                                    (α,v) ∘ (β,w) = (αβ+⟨v,w⟩, αw+βv)
+    │                                    Non-associative: topology matters.
+    │                                    Gershgorin eigenvalue bounds.
+    │
+    ├─── Stage 5: Jacobian Lens ─────── ∂routing/∂signal via finite diffs.
+    │                                    Sensitivity analysis: which input
+    │                                    features drive which expert weights.
+    │
+    ├─── Stage 6: Constraint Eval ───── Boolean expert mask.
+    │                                    Spectral radius must be < 10.
+    │                                    Entropy must be ≤ 0.20 nats.
+    │
+    ├─── Stage 7: Sparse Activation ─── Top-k expert selection.
+    │                                    Only k experts get nonzero weight.
+    │                                    Rest are zeroed (not softmaxed).
+    │
+    ├─── Stage 8: NAND Filter ──────── Conflict suppression.
+    │                                    NAND(A,B) = suppress lower-weight
+    │                                    when both experts claim same input.
+    │
+    ├─── Stage 9: Agent Dispatch ────── Concurrent asyncio execution.
+    │                                    Each active expert runs in parallel.
+    │                                    Timeout per expert (configurable).
+    │
+    ├─── Stage 10: Merge Output ─────── 4 strategies: concatenate, vote,
+    │                                    weighted_sum, first_success.
+    │
+    └─── Stage 11: WORM Seal ────────── Blake2b hash of routing decision.
+                                         Ed25519 signature. Append to chain.
+                                         Decision is now immutable.
+```
+
+---
+
+## Continuity Layer
+
+The agent doesn't lose state. Ever. Four independent persistence mechanisms sync on every state transition:
+
+| # | Paradigm | Storage | Speed | What Survives |
+|---|----------|---------|-------|---------------|
+| 1 | **Env bitmask** | `os.environ` (64-bit packed) | Instant | `os.execv` hot restart — same PID, new binary |
+| 2 | **Seed chain** | Blake2b derivation (24 bytes total) | Instant | Full history compressed to one hash. Deterministic replay from any point. |
+| 3 | **Inode flags** | Zero-byte files + `stat()` | Kernel cache | Process crash. Kernel dcache survives OOM kill. |
+| 4 | **Shared memory** | ctypes struct (4KB mmap block) | RAM speed | Cross-process visibility. No serialization. |
+
+If ANY of the four has state, the agent resumes. `ContinuityManager` unifies all four behind one API:
+
+```python
+cm = ContinuityManager(base_dir=Path("~/.sovereign"), agent_id="react_1")
+cm.transition("IDLE", "THINKING")       # updates all 4 backends
+cm.advance_op("THINK:plan task")        # advances seed chain
+cm.increment_step()                     # syncs step across all 4
+snapshot = cm.snapshot()                 # reads from fastest available
+```
+
+---
+
+## Tool System
+
+34 tools with native opcode dispatch:
+
+<details>
+<summary><strong>All 34 tools with opcodes (click to expand)</strong></summary>
+
+| Opcode | Namespace | Tool | Description |
+|--------|-----------|------|-------------|
+| `0x0001` | filesystem | read | Read file contents (PathJail enforced) |
+| `0x0002` | filesystem | write | Write file (PathJail enforced) |
+| `0x0003` | filesystem | list | List directory |
+| `0x0004` | filesystem | delete | Remove file |
+| `0x0005` | filesystem | move | Move/rename |
+| `0x0006` | filesystem | search | Pattern search (ripgrep-style) |
+| `0x0007` | code | execute | Run code in sandbox |
+| `0x0008` | code | analyze | AST analysis + symbol extraction |
+| `0x0009` | git | status | Repository status |
+| `0x000A` | git | diff | Show changes |
+| `0x000B` | git | commit | Create commit |
+| `0x000C` | git | log | Commit history |
+| `0x000D` | git | branch | Branch operations |
+| `0x000E` | git | checkout | Switch branch |
+| `0x000F` | git | merge | Merge branches |
+| `0x0010` | git | stash | Stash changes |
+| `0x0011` | git | remote | Remote operations |
+| `0x0012` | git | tag | Tag management |
+| `0x0013` | database | query | Execute SQL (parameterized) |
+| `0x0014` | database | schema | Schema introspection |
+| `0x0015` | database | migrate | Run migrations |
+| `0x0016` | documents | parse_pdf | Extract PDF text |
+| `0x0017` | documents | parse_docx | Extract DOCX content |
+| `0x0018` | documents | render_md | Render Markdown |
+| `0x0019` | documents | parse_html | Extract HTML text |
+| `0x001A` | web | search | Web search (SSRFGuard enforced) |
+| `0x001B` | web | fetch | HTTP fetch (SSRFGuard enforced) |
+| `0x001C` | web | scrape | Page scraping |
+| `0x001D` | embeddings | encode | Generate embeddings |
+| `0x001E` | embeddings | search | Similarity search |
+| `0x001F` | audio | transcribe | Speech-to-text |
+| `0x0020` | audio | synthesize | Text-to-speech |
+| `0x0021` | pytorch | inference | Model inference |
+| `0x0022` | pytorch | check_cuda | GPU availability |
+
+</details>
+
+**Two dispatch paths:**
+- **HTTP** (universal): IDE → JSON POST → parse → handler → JSON response (~5ms)
+- **Native mmap** (local): IDE → write opcode to ring buffer → C dispatcher reads → handler → write response (~100μs)
+
+The IPC ring buffer is a 64KB mmap region shared between the C IDE and the Python engine. The C dispatcher (`native/dispatcher/ipc_core.c`) polls at 50μs intervals and dispatches via a jump table indexed by the 16-bit opcode.
+
+---
+
+## Security Architecture
+
+| Layer | Threat | Defense |
+|-------|--------|---------|
+| **PathJail** | `../../etc/passwd`, symlink escape, null bytes | Resolve path → check against allowed roots → reject if outside |
+| **SSRFGuard** | `http://169.254.169.254/metadata`, `http://10.0.0.1` | Block all private IPs, link-local, metadata endpoints |
+| **Inverted AST** | Payload injection into routing decisions | Structural nodes (weight=1) route. Payload leaves (weight=0) can NEVER propagate upward. |
+| **NAND Filter** | Two experts both claiming same input (conflict) | NAND suppresses the lower-weight expert. Prevents split-brain. |
+| **Binary WORM** | JSONL injection, newline attacks, log corruption | 152-byte struct headers. No text parsing anywhere. Append-only file mode. |
+| **ERE Gates** | Secret leakage, eval injection, infinite loops, telemetry | P1: no hardcoded secrets. P2: no eval/exec/import. P3: no `while True` without break. P4: no analytics. P5: SHA-256 audit seal. |
+| **Approval Engine** | Unauthorized tool execution | Risk-level classification. High-risk tools require explicit approval. |
+| **Chain Verification** | Tampered ledger entries | Every WORM record hashes the previous record. Break one → break all downstream. |
+
+---
+
+## Configuration
+
+```python
+from src.sovereign import SovereignEngine, EngineConfig
+from pathlib import Path
+
+engine = SovereignEngine(EngineConfig(
+    allowed_roots=[Path.cwd(), Path("/data")],
+    ledger_path=Path("./sovereign.worm"),
+    continuity_dir=Path.home() / ".sovereign" / "continuity",
+    max_steps=15,
+    enable_shadow=True,
+    enable_ipc=True,
+    agent_id="my_agent",
+))
+```
+
+| Option | Type | Default | Effect |
+|--------|------|---------|--------|
+| `allowed_roots` | `list[Path]` | `[cwd()]` | PathJail boundaries — filesystem tools cannot access anything outside |
+| `ledger_path` | `Path` | `./sovereign.worm` | Binary WORM ledger location |
+| `continuity_dir` | `Path` | `~/.sovereign/continuity` | Where the 4 paradigms store state |
+| `max_steps` | `int` | `15` | Hard limit on agent steps (prevents runaway) |
+| `enable_shadow` | `bool` | `True` | Shadow observer watches for anomalies (cost spikes, loops, failures) |
+| `enable_ipc` | `bool` | `True` | Enable native mmap dispatch (disable for pure-HTTP mode) |
+| `agent_id` | `str` | `"sovereign_main"` | Identity for continuity (different IDs = separate state) |
+
+---
+
+## The Mathematics
+
+### Jordan Algebra — SpinFactor J(n)
+
+The routing gate uses Jordan algebra instead of softmax. This is the same algebra Pascual Jordan developed in 1933 to formalize quantum mechanics observables.
+
+**Elements:** `(α, v)` where `α ∈ ℝ` (scalar confidence), `v ∈ ℝⁿ` (signal vector)
+
+**Product:** `(α,v) ∘ (β,w) = (αβ + ⟨v,w⟩, αw + βv)`
+
+**Why this matters for routing:**
+
+1. **Non-associative composition**: `(A∘B)∘C ≠ A∘(B∘C)` — different agent grouping topologies produce mathematically different routing outcomes. We search over topologies.
+2. **Fixed-point convergence**: Iterating `x ↦ x∘x` converges to idempotents (`e∘e = e`). These ARE the stable routing attractors.
+3. **Spectral decomposition**: `x = λ₊c₊ + λ₋c₋` where `λ± = α ± ‖v‖`. Provably unique expert assignment.
+4. **Spectral gap** = `2‖v‖` = separation between top experts. Bigger gap = more decisive routing.
+
+### QRA Tensor — Quantum Routing Algebra
+
+6×6 deterministic tensor. Shannon entropy H = 0 nats. No randomness.
+
+| Glyph | Maps To | Signal |
+|-------|---------|--------|
+| Π (Pi) | Reasoning models | "explain", "why", "analyze" |
+| Γ (Gamma) | Fast generation | "write", "create", "draft" |
+| Δ (Delta) | Domain-specific | "sql", "medical", "legal" |
+| Λ (Lambda) | Code models | "function", "implement", "debug" |
+| Ω (Omega) | Orchestration | "plan", "coordinate", "multi-step" |
+| Ψ (Psi) | Verification | "prove", "verify", "test" |
+
+---
+
+## Origin: The DSL
+
+The Python engine (38,576 lines) + NASM assembly (7,019 lines) were generated from a single **HyperKittyConstraintDSL** prompt. Three agents coordinated by the DSL constraints. See [ARCHITECTURE.md](ARCHITECTURE.md) for the display template.
+
+The C IDE was hand-built separately.
+
+The DSL defines:
+- Boolean kernel (all gates from NAND)
+- Glyph type system (7 semantic types)
+- Agent invariants (trust + entropy bounds)
+- DAG structure (acyclic routing graph)
+- Proof output (Blake2b hash commitment)
+- Transformation engine (regex patterns + validation)
+
+---
+
+## Papers
+
+| DOI | Title |
+|-----|-------|
+| [10.5281/zenodo.20678420](https://doi.org/10.5281/zenodo.20678420) | Attention Exhaustion Attacks — 0% detection rate |
+| [10.5281/zenodo.21144425](https://doi.org/10.5281/zenodo.21144425) | Resonance Block Trust Deeds — capture spectrum |
+| [10.5281/zenodo.21132094](https://doi.org/10.5281/zenodo.21132094) | Sovereign Compute Architecture |
+| [10.5281/zenodo.21349277](https://doi.org/10.5281/zenodo.21349277) | Gates Normalization Constraint — simplex is structural |
+| [10.5281/zenodo.21351461](https://doi.org/10.5281/zenodo.21351461) | NAND Decomposition — attention is NAND-complete |
+| [10.5281/zenodo.21443609](https://doi.org/10.5281/zenodo.21443609) | Jordan Spectral Transformer — phi-weighted routing |
+| [10.5281/zenodo.21727363](https://doi.org/10.5281/zenodo.21727363) | PAR-011 Jacobian via Jordan Algebras |
+| [10.5281/zenodo.21268911](https://doi.org/10.5281/zenodo.21268911) | GKN I4 Quartic Invariant and E7 Symmetry |
+
+Unified: [The Sovereign Stack](https://snapkittywest.github.io/hyperkitty/papers/sovereign-stack-unified.pdf) — 26 pages, Lean 4.
+
+---
+
+## Line Count
+
+| Component | Language | Files | Lines |
+|-----------|----------|-------|-------|
+| Engine core | Python 3.11 | 87 | 38,576 |
+| NASM runtime | x86-64 Assembly | 7 | 7,019 |
+| C Win32 IDE | C (Win32 API) | 47 | 4,459 |
+| C IPC dispatcher | C | 1 | 390 |
+| **Total** | **3 languages** | **142** | **50,444** |
+
+---
+
+## Documentation
+
+| Guide | What You Learn |
+|-------|---------------|
+| [Architecture](ARCHITECTURE.md) | DSL proof-of-concept, how the engine was generated |
+| [Getting Started](docs/GETTING_STARTED.md) | Install, configure, first task |
+| [Configuration](docs/CONFIGURATION.md) | Every option explained with examples |
+| [Routing](docs/ROUTING.md) | 11-stage pipeline deep dive, tuning, custom experts |
+| [Tools](docs/TOOLS.md) | All 34 tools, custom registration, IPC opcodes |
+| [Continuity](docs/CONTINUITY.md) | 4 paradigms, crash recovery, replay |
+| [Security](docs/SECURITY.md) | PathJail, SSRF, WORM, ERE gates |
+| [Production Hardening](PRODUCTION_HARDENING.md) | Terminal IDE, accessibility, edge cases, testing, CI |
+
+---
+
+## License
+
+BSL 1.1 → MIT 2029-01-01
+
+SnapKitty / SNAPKITTYWEST / 2026

SPRINT_PLAN.md

@@ -0,0 +1,71 @@
+# 3-Phase Sprint Plan — Sovereign Engine v2
+
+## Current State (Audit)
+
+**Tracked:** 137 files on remote
+**Untracked (needs commit):** ide/, docs/, routing_trace.py, qra_router.py, tests/
+**Broken:** ere.py had syntax error (FIXED locally, not pushed)
+**Missing docs:** ROUTING.md, TOOLS.md, CONTINUITY.md, SECURITY.md
+
+---
+
+## PHASE 1: Structural Integrity (This Sprint)
+
+Goal: Every file compiles, imports resolve, repo structure is clean.
+
+- [x] Fix ere.py syntax error (smart quotes → ASCII)
+- [ ] Full syntax check — 0 errors across all .py files
+- [ ] Commit IDE (ide/native/ — 47 C files, 4,459 lines)
+- [ ] Commit Gap 2 (qra_router.py — QRA 6-glyph routing)
+- [ ] Commit Gap 5 (routing_trace.py — trace collector for IDE bridge)
+- [ ] Commit docs/ (GETTING_STARTED.md, CONFIGURATION.md)
+- [ ] Remove Codex planning artifacts (AGENT_BRIEF, gaps/, architecture/)
+- [ ] Verify all __init__.py exports resolve
+- [ ] Push to remote — single clean commit
+
+**Acceptance:** `python -c "from src import SovereignEngine"` works. Zero syntax errors. No stale files.
+
+---
+
+## PHASE 2: Documentation + User Guides (Next Sprint)
+
+Goal: Someone can clone this repo and understand + use it without asking.
+
+- [ ] docs/ROUTING.md — 11-stage pipeline explained, tuning, custom experts
+- [ ] docs/TOOLS.md — All 34 tools, registration, IPC, supervisor
+- [ ] docs/CONTINUITY.md — 4 paradigms, crash recovery, replay
+- [ ] docs/SECURITY.md — PathJail, SSRF, WORM, ERE, inverted AST
+- [ ] docs/IDE.md — How to build the C IDE, connect to engine, use ConPTY
+- [ ] docs/MACHINE_CODE.md — What the bytecode assembler / VM / x86 gen actually do
+- [ ] README cross-references all docs (already done in new README)
+- [ ] Each doc has runnable code examples
+
+**Acceptance:** A developer can read docs/ top-to-bottom and set up the full system.
+
+---
+
+## PHASE 3: Version Control + Release + Packaging (Final Sprint)
+
+Goal: Proper tagged release with installable package.
+
+- [ ] pyproject.toml verified (already exists)
+- [ ] `python -m build` produces .whl
+- [ ] GitHub Release v2.0.0 with changelog
+- [ ] Git tag v2.0.0
+- [ ] LICENSE file (BSL 1.1)
+- [ ] CHANGELOG.md
+- [ ] .github/workflows/ci.yml (Python 3.11-3.13 matrix, pytest, pyright)
+- [ ] requirements.txt is empty (stdlib only — but document optional deps)
+- [ ] Verify `pip install .` works from clean clone
+
+**Acceptance:** `pip install .` → `sovereign --help` works. Tagged release on GitHub.
+
+---
+
+## Rules
+
+1. No rushing. Every file gets syntax-checked before commit.
+2. No planning docs in the repo. Only code, docs, and config.
+3. Line counts in README must be verified (`wc -l`) not guessed.
+4. If an agent writes something broken, I fix it or rewrite it. No shipping broken code.
+5. One clean commit per phase. Not 50 micro-commits.

docs/CONFIGURATION.md

@@ -0,0 +1,391 @@
+# Configuration Reference
+
+Complete guide to all Sovereign Engine configuration options.
+
+## EngineConfig Dataclass
+
+The `EngineConfig` controls all engine behavior. Pass it to `SovereignEngine()`:
+
+```python
+from pathlib import Path
+from src.sovereign import EngineConfig, SovereignEngine
+
+config = EngineConfig(
+    allowed_roots=[Path("/safe/paths")],
+    ledger_path=Path("./sovereign.worm"),
+    continuity_dir=Path.home() / ".sovereign" / "continuity",
+    max_steps=15,
+    enable_shadow=True,
+    enable_ipc=True,
+    agent_id="sovereign_main"
+)
+engine = SovereignEngine(config)
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `allowed_roots` | `list[Path]` | `[Path.cwd()]` | Filesystem roots the engine can access. PathJail blocks all others. |
+| `ledger_path` | `Path` | `./sovereign.worm` | Binary WORM ledger file for cryptographic audit trail. |
+| `continuity_dir` | `Path` | `~/.sovereign/continuity` | Directory for all four continuity backends. Auto-created. |
+| `max_steps` | `int` | `15` | Max reasoning steps in ReActAgent loop before timeout. |
+| `enable_shadow` | `bool` | `True` | Enable ShadowAgent for non-blocking observation. |
+| `enable_ipc` | `bool` | `True` | Enable native IPC multiplexer (O(1) tool dispatch). |
+| `agent_id` | `str` | `"sovereign_main"` | Unique agent identifier (for multi-agent coordination). |
+
+## Environment Variables
+
+Override config via environment variables (prefixed with `SOVEREIGN_`):
+
+```bash
+export SOVEREIGN_ALLOWED_ROOTS="/home/user/projects:/tmp"
+export SOVEREIGN_MAX_STEPS=25
+export SOVEREIGN_ENABLE_SHADOW=false
+export SOVEREIGN_AGENT_ID="batch_processor_1"
+
+python your_script.py
+```
+
+Supported environment variables:
+
+| Variable | Type | Maps To |
+|----------|------|---------|
+| `SOVEREIGN_ALLOWED_ROOTS` | CSV paths | `allowed_roots` (split on `:` or `;`) |
+| `SOVEREIGN_LEDGER_PATH` | path | `ledger_path` |
+| `SOVEREIGN_CONTINUITY_DIR` | path | `continuity_dir` |
+| `SOVEREIGN_MAX_STEPS` | int | `max_steps` |
+| `SOVEREIGN_ENABLE_SHADOW` | bool | `enable_shadow` (true/false/1/0) |
+| `SOVEREIGN_ENABLE_IPC` | bool | `enable_ipc` |
+| `SOVEREIGN_AGENT_ID` | str | `agent_id` |
+
+Example:
+
+```python
+import os
+from src.sovereign import SovereignEngine
+
+# Environment variables take precedence
+if "SOVEREIGN_MAX_STEPS" in os.environ:
+    max_steps = int(os.environ["SOVEREIGN_MAX_STEPS"])
+else:
+    max_steps = 15
+```
+
+## ReActAgent Config
+
+The ReAct reasoning agent has its own config:
+
+```python
+from src.agents.react import ReActConfig, ReActAgent
+
+react_config = ReActConfig(
+    max_steps=20,
+    timeout_ms=60000,
+    model_provider="bedrock",  # bedrock, openrouter, ollama, anthropic
+    temperature=0.7,
+    top_p=0.9,
+)
+
+agent = ReActAgent(
+    agent_id="code_agent",
+    config=react_config,
+    registry=tool_registry,
+    ledger=worm_ledger,
+)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max_steps` | `int` | `15` | Max thinking/action loops. |
+| `timeout_ms` | `int` | `30000` | Total execution timeout. |
+| `model_provider` | `str` | `"bedrock"` | LLM backend: bedrock, openrouter, ollama, anthropic. |
+| `temperature` | `float` | `0.7` | Sampling temperature (0.0-1.0). |
+| `top_p` | `float` | `0.9` | Nucleus sampling parameter. |
+
+## Continuity Directory Structure
+
+The engine uses 4 paradigms for state recovery. Structure:
+
+```
+~/.sovereign/continuity/
+├── env_state.bin                # Paradigm 1: Env bitmask (for hot-restart)
+├── seed.bin                     # Paradigm 2: Seed for deterministic replay
+├── agent_id_seed.bin            # Paradigm 2 per-agent seed
+├── inode/
+│   ├── flags.db                 # Paradigm 3: File handles mapped to boolean gates
+│   ├── agent_id.lock
+│   └── agent_id.state
+├── shm/
+│   └── block_0.bin              # Paradigm 4: Shared memory block (4KB)
+└── checkpoints/
+    ├── checkpoint_001.ckpt      # Full state snapshot with signature
+    ├── checkpoint_002.ckpt
+    └── manifest.json
+```
+
+**Paradigm 1: Env State** — 64-bit bitmask in `os.environ["SOVEREIGN_STATE"]`:
+- Fastest (RAM)
+- Lost on process exit
+- Use for: hot-restart via `os.execv()`
+
+**Paradigm 2: Seed Chain** — Blake2b seed derivation:
+- Deterministic replay
+- Store operation log in binary
+- Use for: replay testing, timeline forking
+
+**Paradigm 3: Inode State** — Zero-byte files as gates:
+- Kernel-durable
+- Fast stat() reads
+- Use for: boolean flags, pause/resume
+
+**Paradigm 4: Shared Memory** — ctypes mmap block:
+- Cross-process coordination
+- 4KB block
+- Use for: multi-agent sync, realtime state
+
+## PathJail Configuration
+
+Restrict filesystem access to approved roots:
+
+```python
+from src.core.path_jail import PathJail
+from pathlib import Path
+
+jail = PathJail(roots=[
+    Path("/home/user/projects"),
+    Path("/tmp/scratch"),
+    Path.home() / "Downloads"
+])
+
+# This is OK
+jail.check("/home/user/projects/code.py")  # ✓
+
+# This is BLOCKED
+jail.check("/etc/passwd")                   # ✗ PathJailError
+jail.check("/root/.ssh/id_rsa")             # ✗ PathJailError
+```
+
+Pass to engine:
+
+```python
+config = EngineConfig(
+    allowed_roots=[
+        Path("/home/user/projects"),
+        Path("/tmp/scratch"),
+    ]
+)
+engine = SovereignEngine(config)
+```
+
+## Model Provider Configuration
+
+Choose which LLM backend to use. Defaults to **AWS Bedrock** (all models via unified API).
+
+### Bedrock (Recommended)
+
+```python
+from src.sovereign import EngineConfig
+from src.runtime.providers.bedrock import BedrockProvider
+
+config = EngineConfig()
+provider = BedrockProvider(
+    region="us-west-2",
+    model="anthropic.claude-3-opus-20240229-v1:0",
+)
+
+# Engine automatically uses it
+engine = SovereignEngine(config)
+```
+
+Requires `~/.aws/credentials`:
+```
+[default]
+aws_access_key_id = YOUR_KEY
+aws_secret_access_key = YOUR_SECRET
+region = us-west-2
+```
+
+### OpenRouter (Open-source + proprietary models)
+
+```python
+from src.runtime.providers.openrouter import OpenRouterProvider
+
+provider = OpenRouterProvider(api_key="sk-or-...")
+# Uses OpenRouter API for Mistral, Llama, Qwen, etc.
+```
+
+Requires `OPENROUTER_API_KEY` environment variable.
+
+### Ollama (Local models)
+
+```python
+from src.runtime.providers.ollama import OllamaProvider
+
+provider = OllamaProvider(base_url="http://localhost:11434")
+# Connect to local Ollama instance (ollama serve)
+```
+
+Run locally first:
+```bash
+ollama run mistral
+# or
+ollama run llama2
+```
+
+### Anthropic API (Direct)
+
+```python
+from src.runtime.providers.anthropic import AnthropicProvider
+
+provider = AnthropicProvider(api_key="sk-ant-...")
+```
+
+## Example Configurations
+
+### Development Mode
+
+Minimal logging, fast iteration:
+
+```python
+from src.sovereign import EngineConfig
+from pathlib import Path
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+
+config = EngineConfig(
+    allowed_roots=[Path.cwd()],
+    ledger_path=Path("/tmp/dev.worm"),
+    continuity_dir=Path("/tmp/continuity"),
+    max_steps=10,  # Fast iteration
+    enable_shadow=False,
+)
+```
+
+### Production Mode
+
+Full logging, durability, multi-agent:
+
+```python
+config = EngineConfig(
+    allowed_roots=[
+        Path("/var/app/data"),
+        Path("/var/app/cache"),
+    ],
+    ledger_path=Path("/var/lib/sovereign/ledger.worm"),
+    continuity_dir=Path("/var/lib/sovereign/continuity"),
+    max_steps=25,  # More thinking
+    enable_shadow=True,  # Async observation
+    enable_ipc=True,  # Native IPC
+    agent_id="prod_reactor_1",
+)
+```
+
+With Bedrock:
+
+```python
+from src.runtime.providers.bedrock import BedrockProvider
+
+provider = BedrockProvider(
+    region="us-east-1",
+    model="anthropic.claude-3-sonnet-20240229-v1:0",
+    timeout_ms=120000,
+)
+```
+
+### CI Testing Mode
+
+Fast, deterministic, no external calls:
+
+```python
+config = EngineConfig(
+    allowed_roots=[Path("/tmp/ci_test")],
+    ledger_path=Path("/tmp/ci.worm"),
+    continuity_dir=Path("/tmp/ci_continuity"),
+    max_steps=5,
+    enable_shadow=False,
+    enable_ipc=False,  # Use pure Python
+    agent_id=f"ci_test_{os.getenv('CI_BUILD_ID')}",
+)
+```
+
+Use mock provider for testing:
+
+```python
+from src.runtime.providers.multi import MultiProvider
+
+# Fallback chain: try each in order
+provider = MultiProvider([
+    MockProvider(),      # Return fixed responses
+    OllamaProvider(),   # Fall back to local if available
+])
+```
+
+## Logging Configuration
+
+Control verbosity via Python logging:
+
+```python
+import logging
+
+# Engine logs
+logging.getLogger("sovereign.engine").setLevel(logging.INFO)
+
+# Routing pipeline
+logging.getLogger("sovereign.routing").setLevel(logging.DEBUG)
+
+# Tool registry
+logging.getLogger("sovereign.tools").setLevel(logging.WARNING)
+
+# Everything
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+```
+
+## Dynamic Configuration Updates
+
+Update config without restarting:
+
+```python
+engine = SovereignEngine(config)
+
+# Update max_steps
+engine.config.max_steps = 25
+
+# Restart agent with new config
+from src.agents.react import ReActConfig
+engine.agent.config.max_steps = 25
+
+# Add a new allowed root
+engine.config.allowed_roots.append(Path("/new/path"))
+engine.path_jail = PathJail(roots=engine.config.allowed_roots)
+```
+
+## Configuration Validation
+
+Validate config before starting engine:
+
+```python
+from src.sovereign import EngineConfig
+from pathlib import Path
+
+config = EngineConfig(
+    allowed_roots=[Path("/tmp/test")],
+)
+
+# Check roots exist
+for root in config.allowed_roots:
+    if not root.exists():
+        root.mkdir(parents=True, exist_ok=True)
+
+# Check continuity dir writable
+try:
+    config.continuity_dir.mkdir(parents=True, exist_ok=True)
+    (config.continuity_dir / ".test").touch()
+    (config.continuity_dir / ".test").unlink()
+except PermissionError:
+    raise RuntimeError(f"Cannot write to {config.continuity_dir}")
+```

docs/GETTING_STARTED.md

@@ -0,0 +1,242 @@
+# Getting Started with Sovereign Engine
+
+Welcome! This guide will get you running your first agent task in under 10 minutes.
+
+## Prerequisites
+
+- **Python 3.11 or higher** — Check with: `python --version`
+- **No external dependencies** — Everything uses Python stdlib (struct, hashlib, asyncio, etc.)
+- Optional: NASM (for native assembly compilation)
+- Optional: C compiler (for IPC core dispatcher)
+
+## Installation
+
+### Option 1: From Source
+
+```bash
+git clone https://github.com/SNAPKITTYWEST/sovereign-reverse.git
+cd sovereign-reverse/engine
+python -m pip install -e .
+```
+
+### Option 2: Install Locally
+
+```bash
+cd /path/to/sovereign-reverse/engine
+python -m pip install -e .
+```
+
+### Verify Installation
+
+```bash
+python -c "from src.sovereign import SovereignEngine; print('OK')"
+```
+
+## First Run: Hello World
+
+Create a file `hello.py`:
+
+```python
+import asyncio
+from pathlib import Path
+from src.sovereign import SovereignEngine, EngineConfig
+
+async def main():
+    # Create engine with default config
+    config = EngineConfig(
+        allowed_roots=[Path.cwd()],
+        continuity_dir=Path.home() / ".sovereign" / "continuity"
+    )
+    engine = SovereignEngine(config)
+    
+    # Run a simple task
+    result = await engine.run("write a Python function to calculate fibonacci(5)")
+    print("\n" + "="*60)
+    print("RESULT:")
+    print("="*60)
+    print(result)
+    
+    # Clean up
+    engine.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Run it:
+
+```bash
+python hello.py
+```
+
+You should see output like:
+
+```
+2024-08-06 10:15:23,456 - sovereign.engine - INFO - SovereignEngine initialized
+2024-08-06 10:15:23,478 - sovereign.engine - INFO - Starting task: write a Python function to calculate fibonacci(5)
+...
+============================================================
+RESULT:
+============================================================
+def fibonacci(n):
+    if n <= 1:
+        return n
+    return fibonacci(n-1) + fibonacci(n-2)
+
+print(fibonacci(5))  # Output: 5
+```
+
+## Understanding the Output
+
+### WORM Seal
+
+Every task execution is sealed in a **Write-Once Read-Many (WORM)** cryptographic ledger:
+
+```
+sovereign.worm                    # Binary append-only file (no text, no injection surface)
+  └─ 152-byte header             # Magic + version + timestamps + Blake2b hash + Ed25519 sig
+  └─ payload                     # Your task result (binary encoded)
+  └─ metadata                    # Execution context (binary encoded)
+```
+
+Read the ledger:
+
+```python
+from src.core.storage import WORMFile
+from pathlib import Path
+
+wf = WORMFile(Path("sovereign.worm"))
+for record in wf.scan():
+    print(f"Event: {record.event_type}")
+    print(f"Timestamp: {record.timestamp_s}")
+    print(f"Hash: {record.content_hash.hex()}")
+```
+
+### Routing Weights
+
+The engine routes tasks to multiple **experts** (specialized agents). Output shows which experts fired and their contribution:
+
+```
+Routing Decision:
+  code_generation:    0.65        # 65% contribution
+  error_checking:     0.28        # 28% contribution  
+  documentation:      0.07        # 7% contribution
+```
+
+This is driven by **Jordan algebra**, not softmax:
+- Non-associative grouping — expert topology matters
+- Fixed-point convergence — stable routing attractors
+- Spectral decomposition — provably unique expert selection
+
+### Continuity Directory
+
+Agent state survives restarts across 4 paradigms:
+
+```
+~/.sovereign/continuity/
+  └─ env_state.bin                # Paradigm 1: 64-bit env bitmask (hot-restart)
+  └─ seed.bin                     # Paradigm 2: Blake2b seed for deterministic replay
+  └─ inode/
+  │   └─ agent_id.state           # Paradigm 3: Zero-byte files as boolean gates
+  │   └─ agent_id.lock
+  └─ shm_block.bin                # Paradigm 4: Shared memory (cross-process realtime)
+  └─ checkpoints/
+      └─ checkpoint_1.ckpt        # Full binary snapshot with signature
+      └─ checkpoint_2.ckpt
+```
+
+## Common First-Time Issues
+
+### Issue: "ModuleNotFoundError: No module named 'src.sovereign'"
+
+**Fix:** Make sure you're in the engine directory and have run `pip install -e .`:
+
+```bash
+cd /path/to/sovereign-reverse/engine
+python -m pip install -e .
+python hello.py
+```
+
+### Issue: "PermissionError: Cannot create continuity directory"
+
+**Fix:** The engine needs to write to `~/.sovereign/continuity`. Make sure it exists and is writable:
+
+```bash
+mkdir -p ~/.sovereign/continuity
+chmod 700 ~/.sovereign/continuity
+```
+
+Or use a custom path:
+
+```python
+config = EngineConfig(
+    continuity_dir=Path("/tmp/my_continuity")
+)
+```
+
+### Issue: "ValueError: no signature in WORM record"
+
+**Fix:** This is expected if no signing key is configured. The engine defaults to zero-signature (all bytes 0). To use real Ed25519 signing:
+
+```python
+from src.core.crypto import generate_signing_key
+
+key = generate_signing_key()
+engine = SovereignEngine(config)
+# engine will use key internally
+```
+
+### Issue: "Timeout: task exceeded 30 seconds"
+
+**Fix:** Increase the max step count or timeout in config:
+
+```python
+from src.agents.react import ReActConfig
+
+config = EngineConfig(
+    max_steps=25  # More thinking steps
+)
+engine = SovereignEngine(config)
+```
+
+Or in individual agent config:
+
+```python
+from src.agents.react import ReActAgent, ReActConfig
+
+react_config = ReActConfig(max_steps=25, timeout_ms=60000)
+```
+
+### Issue: "PathJail: denied /path/to/file"
+
+**Fix:** The engine restricts filesystem access to `allowed_roots`. Add your path:
+
+```python
+config = EngineConfig(
+    allowed_roots=[
+        Path("/home/user/projects"),
+        Path("/tmp/scratch")
+    ]
+)
+```
+
+## Next Steps
+
+- **[CONFIGURATION.md](CONFIGURATION.md)** — All EngineConfig options with defaults
+- **[ROUTING.md](ROUTING.md)** — How the 11-stage pipeline works
+- **[TOOLS.md](TOOLS.md)** — Complete tool inventory (34 tools)
+- **[CONTINUITY.md](CONTINUITY.md)** — State recovery and replay
+- **[SECURITY.md](SECURITY.md)** — PathJail, SSRFGuard, WORM verification
+
+## Production Checklist
+
+Before shipping to production:
+
+- [ ] Set up Ed25519 signing key (see [SECURITY.md](SECURITY.md))
+- [ ] Configure `allowed_roots` to restrict filesystem access
+- [ ] Enable WORM ledger integrity checks (script in [SECURITY.md](SECURITY.md))
+- [ ] Set up continuity directory with proper permissions
+- [ ] Test task recovery (kill agent mid-task, restart)
+- [ ] Configure rate limits on destructive tools (see [TOOLS.md](TOOLS.md))
+- [ ] Enable shadow agent for async observation: `enable_shadow=True`
+- [ ] Set appropriate model provider in config (Bedrock/OpenRouter/Ollama)

ide/CMakeLists.txt

@@ -0,0 +1,92 @@
+cmake_minimum_required(VERSION 3.24)
+project(sovereign-ide C CXX)
+
+set(CMAKE_C_STANDARD 17)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+if(NOT WIN32)
+    message(FATAL_ERROR "Sovereign IDE targets Windows only (Win32 + Direct2D)")
+endif()
+
+add_compile_definitions(_WIN32_WINNT=0x0A00 NTDDI_VERSION=0x0A000000)
+
+if(MSVC)
+    add_compile_options(/W4 /WX /utf-8)
+else()
+    add_compile_options(-Wall -Wextra -Werror -Wno-missing-field-initializers)
+endif()
+
+# --- Core library (pure C, no GUI deps) ---
+add_library(sov_core STATIC
+    native/core/arena.c
+    native/core/strings.c
+    native/core/events.c
+    native/editor/buffer.c
+    native/editor/document.c
+    native/chat/protocol.c
+    native/fcl/evaluator.c
+    native/git/repository.c
+    native/build/cmake_runner.c
+    native/lsp/client.c
+)
+target_include_directories(sov_core PUBLIC native)
+
+# --- Editor graphics (C++, Direct2D + DirectWrite) ---
+add_library(sov_editor STATIC
+    native/graphics/d2d_renderer.cpp
+    native/editor/editor_view.cpp
+)
+target_include_directories(sov_editor PUBLIC native)
+target_link_libraries(sov_editor PUBLIC sov_core d2d1 dwrite dxgi ole32)
+
+# --- UI widgets (C++, Direct2D + DirectWrite) ---
+add_library(sov_ui STATIC
+    native/ui/layout.c
+    native/ui/project_tree.cpp
+    native/ui/status_bar.cpp
+    native/ui/output_panel.cpp
+    native/terminal/conpty.c
+    native/terminal/terminal_view.cpp
+)
+target_include_directories(sov_ui PUBLIC native)
+target_link_libraries(sov_ui PUBLIC sov_core sov_editor d2d1 dwrite ole32)
+
+# --- Platform layer (C, Win32) ---
+add_library(sov_platform STATIC
+    native/platform/windows/application.c
+    native/platform/windows/shell.c
+    native/chat/pipe_client.c
+)
+target_include_directories(sov_platform PUBLIC native)
+target_link_libraries(sov_platform PUBLIC sov_core sov_editor sov_ui user32 gdi32 shcore comdlg32 shell32)
+
+# --- Main executable ---
+add_executable(sovereign-ide WIN32 native/main.c)
+target_link_libraries(sovereign-ide PRIVATE sov_core sov_platform sov_editor sov_ui)
+if(MINGW)
+    target_link_options(sovereign-ide PRIVATE -municode -static-libgcc -static-libstdc++ -static)
+endif()
+
+set_target_properties(sovereign-ide PROPERTIES
+    OUTPUT_NAME "sovereign-ide"
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
+)
+
+# --- Tests ---
+enable_testing()
+
+add_executable(test_core
+    tests/test_arena.c
+    tests/test_strings.c
+    tests/test_events.c
+    tests/test_buffer.c
+    tests/test_protocol.c
+    tests/test_fcl.c
+    tests/test_main.c
+)
+target_link_libraries(test_core PRIVATE sov_core)
+target_include_directories(test_core PRIVATE native)
+
+add_test(NAME core_tests COMMAND test_core)

ide/native/bridge/bridge.h

@@ -0,0 +1,140 @@
+/*
+ * Bridge Client — C → Python Engine
+ * Sovereign IDE Bridge Layer
+ *
+ * Communicates with Python sovereign-engine via stdio or HTTP.
+ */
+
+#ifndef BRIDGE_H
+#define BRIDGE_H
+
+#include <stddef.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Bridge transport types */
+typedef enum {
+    BRIDGE_TRANSPORT_STDIO,
+    BRIDGE_TRANSPORT_HTTP
+} BridgeTransport;
+
+/* Bridge result codes */
+typedef enum {
+    BRIDGE_OK = 0,
+    BRIDGE_ERROR_INIT = -1,
+    BRIDGE_ERROR_SEND = -2,
+    BRIDGE_ERROR_RECV = -3,
+    BRIDGE_ERROR_PARSE = -4,
+    BRIDGE_ERROR_TIMEOUT = -5
+} BridgeResult;
+
+/* Bridge handle (opaque) */
+typedef struct Bridge Bridge;
+
+/* Bridge configuration */
+typedef struct {
+    BridgeTransport transport;
+
+    /* HTTP config */
+    const char* http_host;
+    unsigned short http_port;
+
+    /* Stdio config */
+    const char* python_executable;
+    const char* bridge_script;
+
+    /* Timeouts (milliseconds) */
+    unsigned int request_timeout;
+} BridgeConfig;
+
+/* Response callback */
+typedef void (*BridgeCallback)(const char* response_json, void* user_data);
+
+/*
+ * Initialize bridge
+ * Returns bridge handle on success, NULL on failure
+ */
+Bridge* bridge_init(const BridgeConfig* config);
+
+/*
+ * Shutdown bridge
+ */
+void bridge_shutdown(Bridge* bridge);
+
+/*
+ * Check if bridge is ready
+ */
+bool bridge_is_ready(Bridge* bridge);
+
+/*
+ * Run agent task (blocking)
+ * Returns JSON response string (caller must free)
+ */
+char* bridge_agent_run(Bridge* bridge, const char* task);
+
+/*
+ * Run agent task (async)
+ */
+BridgeResult bridge_agent_run_async(
+    Bridge* bridge,
+    const char* task,
+    BridgeCallback callback,
+    void* user_data
+);
+
+/*
+ * Execute tool (blocking)
+ */
+char* bridge_tool_execute(
+    Bridge* bridge,
+    const char* tool_name,
+    const char* args_json
+);
+
+/*
+ * List available tools (blocking)
+ */
+char* bridge_tools_list(Bridge* bridge);
+
+/*
+ * Send chat message (blocking)
+ */
+char* bridge_chat_message(Bridge* bridge, const char* message);
+
+/*
+ * Health check (blocking)
+ */
+bool bridge_health_check(Bridge* bridge);
+
+/*
+ * Get last error message
+ */
+const char* bridge_get_error(Bridge* bridge);
+
+/*
+ * Set API key for provider
+ * provider: "openrouter" or "ollama"
+ * Returns JSON response (caller must free)
+ */
+char* bridge_set_key(Bridge* bridge, const char* provider, const char* api_key);
+
+/*
+ * Get API key status
+ * Returns JSON with all provider statuses (caller must free)
+ */
+char* bridge_get_key_status(Bridge* bridge);
+
+/*
+ * Delete API key for provider
+ * Returns JSON response (caller must free)
+ */
+char* bridge_delete_key(Bridge* bridge, const char* provider);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BRIDGE_H */

ide/native/bridge/bridge_http.c

@@ -0,0 +1,485 @@
+/*
+ * Bridge HTTP Client Implementation
+ * Uses WinHTTP for HTTP communication with Python engine
+ */
+
+#include "bridge.h"
+#include <windows.h>
+#include <winhttp.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#pragma comment(lib, "winhttp.lib")
+
+/* Bridge internal structure */
+struct Bridge {
+    BridgeConfig config;
+    HINTERNET hSession;
+    HINTERNET hConnect;
+    char error_msg[512];
+    bool ready;
+};
+
+/* Helper: validate input length for JSON */
+static bool validate_input_length(Bridge* bridge, const char* input, const char* field_name) {
+    size_t len = strlen(input);
+    if (len > 4000) {  /* Max input: 4KB minus JSON overhead */
+        snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+            "%s too long: %lu chars (max 4000)", field_name, (unsigned long)len);
+        return false;
+    }
+    return true;
+}
+
+/* Helper: escape JSON special characters */
+static char* json_escape(const char* str) {
+    if (!str) return NULL;
+
+    size_t len = strlen(str);
+    /* Worst case: every char needs escaping (doubled length) */
+    char* escaped = (char*)malloc(len * 2 + 1);
+    if (!escaped) return NULL;
+
+    size_t j = 0;
+    for (size_t i = 0; i < len; i++) {
+        switch (str[i]) {
+            case '"':
+            case '\\':
+                escaped[j++] = '\\';
+                escaped[j++] = str[i];
+                break;
+            case '\n':
+                escaped[j++] = '\\';
+                escaped[j++] = 'n';
+                break;
+            case '\r':
+                escaped[j++] = '\\';
+                escaped[j++] = 'r';
+                break;
+            case '\t':
+                escaped[j++] = '\\';
+                escaped[j++] = 't';
+                break;
+            default:
+                escaped[j++] = str[i];
+                break;
+        }
+    }
+    escaped[j] = '\0';
+    return escaped;
+}
+
+/* Helper: HTTP POST request */
+static char* http_post(Bridge* bridge, const char* path, const char* body) {
+    if (!bridge || !bridge->hConnect) {
+        return NULL;
+    }
+
+    /* Convert path to wide string */
+    wchar_t wide_path[256];
+    MultiByteToWideChar(CP_UTF8, 0, path ? path : "/", -1, wide_path, 256);
+
+    /* Open request */
+    HINTERNET hRequest = WinHttpOpenRequest(
+        bridge->hConnect,
+        L"POST",
+        wide_path,
+        NULL,
+        WINHTTP_NO_REFERER,
+        WINHTTP_DEFAULT_ACCEPT_TYPES,
+        0
+    );
+
+    if (!hRequest) {
+        snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+            "Failed to open HTTP request");
+        return NULL;
+    }
+
+    /* Set headers */
+    LPCWSTR headers = L"Content-Type: application/json\r\n";
+    WinHttpAddRequestHeaders(hRequest, headers, -1, WINHTTP_ADDREQ_FLAG_ADD);
+
+    /* Send request */
+    DWORD body_len = (DWORD)strlen(body);
+    BOOL result = WinHttpSendRequest(
+        hRequest,
+        WINHTTP_NO_ADDITIONAL_HEADERS,
+        0,
+        (LPVOID)body,
+        body_len,
+        body_len,
+        0
+    );
+
+    if (!result) {
+        WinHttpCloseHandle(hRequest);
+        snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+            "Failed to send HTTP request");
+        return NULL;
+    }
+
+    /* Receive response */
+    result = WinHttpReceiveResponse(hRequest, NULL);
+    if (!result) {
+        WinHttpCloseHandle(hRequest);
+        snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+            "Failed to receive HTTP response");
+        return NULL;
+    }
+
+    /* Read response body */
+    DWORD bytes_available = 0;
+    DWORD bytes_read = 0;
+    char* response = NULL;
+    size_t response_len = 0;
+
+    do {
+        bytes_available = 0;
+        if (!WinHttpQueryDataAvailable(hRequest, &bytes_available)) {
+            break;
+        }
+
+        if (bytes_available == 0) {
+            break;
+        }
+
+        /* Allocate buffer */
+        char* buffer = (char*)malloc(bytes_available + 1);
+        if (!buffer) break;
+
+        /* Read data */
+        if (WinHttpReadData(hRequest, buffer, bytes_available, &bytes_read)) {
+            /* Append to response */
+            char* new_response = (char*)realloc(response, response_len + bytes_read + 1);
+            if (new_response) {
+                response = new_response;
+                memcpy(response + response_len, buffer, bytes_read);
+                response_len += bytes_read;
+                response[response_len] = '\0';
+            } else {
+                /* realloc failed - clean up */
+                free(response);
+                free(buffer);
+                WinHttpCloseHandle(hRequest);
+                snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+                    "Out of memory during HTTP response");
+                return NULL;
+            }
+        }
+
+        free(buffer);
+    } while (bytes_available > 0);
+
+    WinHttpCloseHandle(hRequest);
+    return response;
+}
+
+/* Helper: HTTP GET request */
+static char* http_get(Bridge* bridge, const char* path) {
+    if (!bridge || !bridge->hConnect) {
+        return NULL;
+    }
+
+    /* Convert path to wide string */
+    wchar_t wide_path[256];
+    MultiByteToWideChar(CP_UTF8, 0, path ? path : "/", -1, wide_path, 256);
+
+    /* Open request */
+    HINTERNET hRequest = WinHttpOpenRequest(
+        bridge->hConnect,
+        L"GET",
+        wide_path,
+        NULL,
+        WINHTTP_NO_REFERER,
+        WINHTTP_DEFAULT_ACCEPT_TYPES,
+        0
+    );
+
+    if (!hRequest) {
+        return NULL;
+    }
+
+    /* Send request */
+    BOOL result = WinHttpSendRequest(
+        hRequest,
+        WINHTTP_NO_ADDITIONAL_HEADERS,
+        0,
+        WINHTTP_NO_REQUEST_DATA,
+        0,
+        0,
+        0
+    );
+
+    if (!result) {
+        WinHttpCloseHandle(hRequest);
+        return NULL;
+    }
+
+    /* Receive response */
+    result = WinHttpReceiveResponse(hRequest, NULL);
+    if (!result) {
+        WinHttpCloseHandle(hRequest);
+        return NULL;
+    }
+
+    /* Read response (same as POST) */
+    DWORD bytes_available = 0;
+    DWORD bytes_read = 0;
+    char* response = NULL;
+    size_t response_len = 0;
+
+    do {
+        bytes_available = 0;
+        if (!WinHttpQueryDataAvailable(hRequest, &bytes_available)) {
+            break;
+        }
+
+        if (bytes_available == 0) {
+            break;
+        }
+
+        char* buffer = (char*)malloc(bytes_available + 1);
+        if (!buffer) {
+            free(response);
+            break;
+        }
+
+        if (WinHttpReadData(hRequest, buffer, bytes_available, &bytes_read)) {
+            char* new_response = (char*)realloc(response, response_len + bytes_read + 1);
+            if (new_response) {
+                response = new_response;
+                memcpy(response + response_len, buffer, bytes_read);
+                response_len += bytes_read;
+                response[response_len] = '\0';
+            } else {
+                /* realloc failed - clean up */
+                free(response);
+                free(buffer);
+                WinHttpCloseHandle(hRequest);
+                return NULL;
+            }
+        }
+
+        free(buffer);
+    } while (bytes_available > 0);
+
+    WinHttpCloseHandle(hRequest);
+    return response;
+}
+
+/* Public API */
+
+Bridge* bridge_init(const BridgeConfig* config) {
+    if (!config) return NULL;
+
+    Bridge* bridge = (Bridge*)calloc(1, sizeof(Bridge));
+    if (!bridge) return NULL;
+
+    /* Copy config */
+    memcpy(&bridge->config, config, sizeof(BridgeConfig));
+
+    if (config->transport == BRIDGE_TRANSPORT_HTTP) {
+        /* Initialize WinHTTP session */
+        bridge->hSession = WinHttpOpen(
+            L"SovereignIDE/1.0",
+            WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
+            WINHTTP_NO_PROXY_NAME,
+            WINHTTP_NO_PROXY_BYPASS,
+            0
+        );
+
+        if (!bridge->hSession) {
+            snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+                "Failed to initialize WinHTTP");
+            free(bridge);
+            return NULL;
+        }
+
+        /* Set timeout */
+        DWORD timeout = config->request_timeout ? config->request_timeout : 30000;
+        WinHttpSetTimeouts(bridge->hSession, timeout, timeout, timeout, timeout);
+
+        /* Connect to host */
+        wchar_t host[256];
+        MultiByteToWideChar(CP_UTF8, 0, config->http_host, -1, host, 256);
+
+        bridge->hConnect = WinHttpConnect(
+            bridge->hSession,
+            host,
+            config->http_port,
+            0
+        );
+
+        if (!bridge->hConnect) {
+            snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+                "Failed to connect to %s:%d", config->http_host, config->http_port);
+            WinHttpCloseHandle(bridge->hSession);
+            free(bridge);
+            return NULL;
+        }
+
+        bridge->ready = true;
+    }
+
+    return bridge;
+}
+
+void bridge_shutdown(Bridge* bridge) {
+    if (!bridge) return;
+
+    if (bridge->hConnect) {
+        WinHttpCloseHandle(bridge->hConnect);
+    }
+
+    if (bridge->hSession) {
+        WinHttpCloseHandle(bridge->hSession);
+    }
+
+    free(bridge);
+}
+
+bool bridge_is_ready(Bridge* bridge) {
+    return bridge && bridge->ready;
+}
+
+char* bridge_agent_run(Bridge* bridge, const char* task) {
+    if (!bridge || !task) return NULL;
+
+    /* Validate input length */
+    if (!validate_input_length(bridge, task, "Task")) {
+        return NULL;
+    }
+
+    /* Escape JSON special characters */
+    char* escaped_task = json_escape(task);
+    if (!escaped_task) {
+        snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+            "Out of memory during JSON escaping");
+        return NULL;
+    }
+
+    /* Build request JSON */
+    char request_body[4096];
+    snprintf(request_body, sizeof(request_body),
+        "{\"task\":\"%s\"}", escaped_task);
+
+    free(escaped_task);
+
+    /* POST to /agent/run */
+    return http_post(bridge, "/agent/run", request_body);
+}
+
+char* bridge_tool_execute(Bridge* bridge, const char* tool_name, const char* args_json) {
+    if (!bridge || !tool_name) return NULL;
+
+    /* Build request */
+    char request_body[4096];
+    snprintf(request_body, sizeof(request_body),
+        "{\"tool\":\"%s\",\"args\":%s}",
+        tool_name, args_json ? args_json : "{}");
+
+    return http_post(bridge, "/tool/execute", request_body);
+}
+
+char* bridge_tools_list(Bridge* bridge) {
+    if (!bridge) return NULL;
+    return http_get(bridge, "/tools");
+}
+
+char* bridge_chat_message(Bridge* bridge, const char* message) {
+    if (!bridge || !message) return NULL;
+
+    /* Validate input length */
+    if (!validate_input_length(bridge, message, "Message")) {
+        return NULL;
+    }
+
+    /* Escape JSON special characters */
+    char* escaped_message = json_escape(message);
+    if (!escaped_message) {
+        snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+            "Out of memory during JSON escaping");
+        return NULL;
+    }
+
+    char request_body[4096];
+    snprintf(request_body, sizeof(request_body),
+        "{\"message\":\"%s\"}", escaped_message);
+
+    free(escaped_message);
+
+    return http_post(bridge, "/chat", request_body);
+}
+
+bool bridge_health_check(Bridge* bridge) {
+    if (!bridge) return false;
+
+    char* response = http_get(bridge, "/health");
+    if (!response) return false;
+
+    /* Check for "ok" in response */
+    bool ok = strstr(response, "ok") != NULL;
+    free(response);
+
+    return ok;
+}
+
+const char* bridge_get_error(Bridge* bridge) {
+    return bridge ? bridge->error_msg : "Bridge is NULL";
+}
+
+char* bridge_set_key(Bridge* bridge, const char* provider, const char* api_key) {
+    if (!bridge || !provider || !api_key) return NULL;
+
+    /* Validate input lengths */
+    if (!validate_input_length(bridge, provider, "Provider")) {
+        return NULL;
+    }
+    if (!validate_input_length(bridge, api_key, "API key")) {
+        return NULL;
+    }
+
+    /* Escape JSON special characters */
+    char* escaped_provider = json_escape(provider);
+    char* escaped_key = json_escape(api_key);
+
+    if (!escaped_provider || !escaped_key) {
+        free(escaped_provider);
+        free(escaped_key);
+        snprintf(bridge->error_msg, sizeof(bridge->error_msg),
+            "Out of memory during JSON escaping");
+        return NULL;
+    }
+
+    /* Build request JSON */
+    char request_body[4096];
+    snprintf(request_body, sizeof(request_body),
+        "{\"provider\":\"%s\",\"key\":\"%s\"}",
+        escaped_provider, escaped_key);
+
+    free(escaped_provider);
+    free(escaped_key);
+
+    return http_post(bridge, "/keys/set", request_body);
+}
+
+char* bridge_get_key_status(Bridge* bridge) {
+    if (!bridge) return NULL;
+    return http_get(bridge, "/keys/status");
+}
+
+char* bridge_delete_key(Bridge* bridge, const char* provider) {
+    if (!bridge || !provider) return NULL;
+
+    /* Build path */
+    char path[256];
+    snprintf(path, sizeof(path), "/keys/%s", provider);
+
+    /* Need to implement DELETE - for now use POST with _method */
+    char request_body[256];
+    snprintf(request_body, sizeof(request_body), "{\"_method\":\"DELETE\"}");
+
+    return http_post(bridge, path, request_body);
+}

ide/native/bridge/example.c

@@ -0,0 +1,86 @@
+/*
+ * Bridge Usage Example
+ * Demonstrates how to use the C → Python bridge
+ */
+
+#include "bridge.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(int argc, char** argv) {
+    /* Configure HTTP bridge */
+    BridgeConfig config = {
+        .transport = BRIDGE_TRANSPORT_HTTP,
+        .http_host = "127.0.0.1",
+        .http_port = 19000,
+        .request_timeout = 30000  /* 30 seconds */
+    };
+
+    /* Initialize bridge */
+    printf("Initializing bridge...\n");
+    Bridge* bridge = bridge_init(&config);
+    if (!bridge) {
+        fprintf(stderr, "Failed to initialize bridge\n");
+        return 1;
+    }
+
+    /* Health check */
+    printf("Health check...\n");
+    if (bridge_health_check(bridge)) {
+        printf("✓ Bridge is healthy\n\n");
+    } else {
+        fprintf(stderr, "✗ Bridge health check failed: %s\n",
+            bridge_get_error(bridge));
+        bridge_shutdown(bridge);
+        return 1;
+    }
+
+    /* List tools */
+    printf("Listing available tools...\n");
+    char* tools = bridge_tools_list(bridge);
+    if (tools) {
+        printf("Tools: %s\n\n", tools);
+        free(tools);
+    }
+
+    /* Send chat message */
+    printf("Sending chat message...\n");
+    char* chat_response = bridge_chat_message(bridge, "Hello from C!");
+    if (chat_response) {
+        printf("Response: %s\n\n", chat_response);
+        free(chat_response);
+    }
+
+    /* Run agent task */
+    printf("Running agent task...\n");
+    char* agent_result = bridge_agent_run(
+        bridge,
+        "List all files in the current directory"
+    );
+
+    if (agent_result) {
+        printf("Agent result: %s\n\n", agent_result);
+        free(agent_result);
+    } else {
+        fprintf(stderr, "Agent failed: %s\n", bridge_get_error(bridge));
+    }
+
+    /* Execute tool */
+    printf("Executing tool...\n");
+    char* tool_result = bridge_tool_execute(
+        bridge,
+        "filesystem.read",
+        "{\"path\":\"README.md\"}"
+    );
+
+    if (tool_result) {
+        printf("Tool result: %s\n\n", tool_result);
+        free(tool_result);
+    }
+
+    /* Cleanup */
+    bridge_shutdown(bridge);
+    printf("Bridge shutdown complete\n");
+
+    return 0;
+}

ide/native/bridge/test_keys.c

@@ -0,0 +1,90 @@
+/*
+ * API Key Management Test
+ * Demonstrates setting keys via bridge
+ */
+
+#include "bridge.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+void print_status(Bridge* bridge) {
+    printf("\n=== API Key Status ===\n");
+    char* status = bridge_get_key_status(bridge);
+    if (status) {
+        printf("%s\n", status);
+        free(status);
+    } else {
+        printf("Failed to get status\n");
+    }
+}
+
+int main(int argc, char** argv) {
+    /* Configure bridge */
+    BridgeConfig config = {
+        .transport = BRIDGE_TRANSPORT_HTTP,
+        .http_host = "127.0.0.1",
+        .http_port = 19000,
+        .request_timeout = 30000
+    };
+
+    /* Initialize */
+    printf("Initializing bridge...\n");
+    Bridge* bridge = bridge_init(&config);
+    if (!bridge) {
+        fprintf(stderr, "Failed to initialize bridge\n");
+        return 1;
+    }
+
+    /* Health check */
+    if (!bridge_health_check(bridge)) {
+        fprintf(stderr, "Bridge not healthy\n");
+        bridge_shutdown(bridge);
+        return 1;
+    }
+    printf("OK: Bridge healthy\n");
+
+    /* Get initial status */
+    print_status(bridge);
+
+    /* Simulate UI - set OpenRouter key */
+    printf("\n--- Setting OpenRouter Key ---\n");
+    printf("(In real UI, user would paste their key here)\n");
+
+    const char* demo_key = "sk-or-v1-demo-key-12345";  /* Demo key */
+    char* set_result = bridge_set_key(bridge, "openrouter", demo_key);
+    if (set_result) {
+        printf("Result: %s\n", set_result);
+        free(set_result);
+    }
+
+    /* Get updated status */
+    print_status(bridge);
+
+    /* Test chat with key set */
+    printf("\n--- Testing Chat (should use OpenRouter) ---\n");
+    char* chat_reply = bridge_chat_message(bridge, "Hello! Test message.");
+    if (chat_reply) {
+        printf("Reply: %s\n", chat_reply);
+        free(chat_reply);
+    } else {
+        printf("Chat failed (expected - demo key not real)\n");
+    }
+
+    /* Delete key */
+    printf("\n--- Deleting OpenRouter Key ---\n");
+    char* delete_result = bridge_delete_key(bridge, "openrouter");
+    if (delete_result) {
+        printf("Result: %s\n", delete_result);
+        free(delete_result);
+    }
+
+    /* Final status */
+    print_status(bridge);
+
+    /* Cleanup */
+    bridge_shutdown(bridge);
+    printf("\nDone\n");
+
+    return 0;
+}

ide/native/bridge/test_tools.c

@@ -0,0 +1,84 @@
+/*
+ * Tool Execution Test
+ * Tests filesystem and code tools
+ */
+
+#include "bridge.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(int argc, char** argv) {
+    /* Configure bridge */
+    BridgeConfig config = {
+        .transport = BRIDGE_TRANSPORT_HTTP,
+        .http_host = "127.0.0.1",
+        .http_port = 19000,
+        .request_timeout = 30000
+    };
+
+    /* Initialize */
+    printf("Initializing bridge...\n");
+    Bridge* bridge = bridge_init(&config);
+    if (!bridge) {
+        fprintf(stderr, "Failed to initialize bridge\n");
+        return 1;
+    }
+
+    /* Health check */
+    if (!bridge_health_check(bridge)) {
+        fprintf(stderr, "Bridge not healthy\n");
+        bridge_shutdown(bridge);
+        return 1;
+    }
+    printf("OK: Bridge healthy\n\n");
+
+    /* List available tools */
+    printf("=== Available Tools ===\n");
+    char* tools = bridge_tools_list(bridge);
+    if (tools) {
+        printf("%s\n\n", tools);
+        free(tools);
+    }
+
+    /* Test filesystem.read */
+    printf("=== Test: filesystem.read ===\n");
+    char* read_result = bridge_tool_execute(
+        bridge,
+        "filesystem.read",
+        "{\"path\":\"README.md\"}"
+    );
+    if (read_result) {
+        printf("Result: %s\n\n", read_result);
+        free(read_result);
+    }
+
+    /* Test filesystem.write */
+    printf("=== Test: filesystem.write ===\n");
+    char* write_result = bridge_tool_execute(
+        bridge,
+        "filesystem.write",
+        "{\"path\":\"test_output.txt\",\"content\":\"Hello from C!\\nBridge is working.\"}"
+    );
+    if (write_result) {
+        printf("Result: %s\n\n", write_result);
+        free(write_result);
+    }
+
+    /* Test filesystem.list */
+    printf("=== Test: filesystem.list ===\n");
+    char* list_result = bridge_tool_execute(
+        bridge,
+        "filesystem.list",
+        "{\"path\":\".\"}"
+    );
+    if (list_result) {
+        printf("Result: %s\n\n", list_result);
+        free(list_result);
+    }
+
+    /* Cleanup */
+    bridge_shutdown(bridge);
+    printf("Done\n");
+
+    return 0;
+}

ide/native/chat/pipe_client.c

@@ -0,0 +1,105 @@
+/*
+ * Sovereign IDE — Named Pipe Client
+ * Connects to the Elixir SovereignChat process via \\.\pipe\sovereign-ide-chat.
+ * Framed binary protocol per contract section 8.
+ */
+
+#include "pipe_client.h"
+#include "protocol.h"
+#include "../core/errors.h"
+#include "../core/arena.h"
+
+#include <string.h>
+
+#define PIPE_NAME L"\\\\.\\pipe\\sovereign-ide-chat"
+#define PIPE_BUFFER_SIZE (64 * 1024)
+#define RECONNECT_DELAY_MS 1000
+#define MAX_RECONNECT_ATTEMPTS 10
+
+static struct {
+    HANDLE pipe;
+    bool   connected;
+    Arena  recv_arena;
+    uint8_t recv_buf[PIPE_BUFFER_SIZE];
+} g_pipe;
+
+SovResult pipe_client_init(void) {
+    g_pipe.pipe = INVALID_HANDLE_VALUE;
+    g_pipe.connected = false;
+    arena_init(&g_pipe.recv_arena, 256 * 1024);
+    return SOV_OK;
+}
+
+SovResult pipe_client_connect(void) {
+    for (int attempt = 0; attempt < MAX_RECONNECT_ATTEMPTS; attempt++) {
+        g_pipe.pipe = CreateFileW(
+            PIPE_NAME,
+            GENERIC_READ | GENERIC_WRITE,
+            0, NULL,
+            OPEN_EXISTING,
+            FILE_FLAG_OVERLAPPED,
+            NULL
+        );
+
+        if (g_pipe.pipe != INVALID_HANDLE_VALUE) {
+            DWORD mode = PIPE_READMODE_MESSAGE;
+            SetNamedPipeHandleState(g_pipe.pipe, &mode, NULL, NULL);
+            g_pipe.connected = true;
+            return SOV_OK;
+        }
+
+        if (GetLastError() != ERROR_PIPE_BUSY) {
+            Sleep(RECONNECT_DELAY_MS);
+        } else {
+            WaitNamedPipeW(PIPE_NAME, RECONNECT_DELAY_MS);
+        }
+    }
+
+    return SOV_ERR_PIPE;
+}
+
+SovResult pipe_client_send(const uint8_t *data, size_t len) {
+    if (!g_pipe.connected) return SOV_ERR_PIPE;
+
+    DWORD written;
+    BOOL ok = WriteFile(g_pipe.pipe, data, (DWORD)len, &written, NULL);
+    if (!ok || written != (DWORD)len) return SOV_ERR_PIPE;
+
+    return SOV_OK;
+}
+
+SovResult pipe_client_recv(uint8_t *out, size_t max_len, size_t *out_len) {
+    if (!g_pipe.connected) return SOV_ERR_PIPE;
+
+    DWORD read;
+    BOOL ok = ReadFile(g_pipe.pipe, out, (DWORD)max_len, &read, NULL);
+    if (!ok) {
+        DWORD err = GetLastError();
+        if (err == ERROR_MORE_DATA) {
+            *out_len = read;
+            return SOV_OK;
+        }
+        g_pipe.connected = false;
+        return SOV_ERR_PIPE;
+    }
+
+    *out_len = read;
+    return SOV_OK;
+}
+
+bool pipe_client_is_connected(void) {
+    return g_pipe.connected;
+}
+
+void pipe_client_disconnect(void) {
+    if (g_pipe.pipe != INVALID_HANDLE_VALUE) {
+        CloseHandle(g_pipe.pipe);
+        g_pipe.pipe = INVALID_HANDLE_VALUE;
+    }
+    g_pipe.connected = false;
+}
+
+void pipe_client_shutdown(void) {
+    pipe_client_disconnect();
+    arena_destroy(&g_pipe.recv_arena);
+}

ide/native/chat/pipe_client.h

@@ -0,0 +1,18 @@
+#ifndef SOVEREIGN_PIPE_CLIENT_H
+#define SOVEREIGN_PIPE_CLIENT_H
+
+#include <windows.h>
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+#include "../core/errors.h"
+
+SovResult pipe_client_init(void);
+SovResult pipe_client_connect(void);
+SovResult pipe_client_send(const uint8_t *data, size_t len);
+SovResult pipe_client_recv(uint8_t *out, size_t max_len, size_t *out_len);
+bool      pipe_client_is_connected(void);
+void      pipe_client_disconnect(void);
+void      pipe_client_shutdown(void);
+
+#endif /* SOVEREIGN_PIPE_CLIENT_H */

ide/native/chat/protocol.c

@@ -0,0 +1,17 @@
+/*
+ * Sovereign IDE — IPC Protocol
+ * CRC32 checksum for frame validation.
+ */
+
+#include "protocol.h"
+
+uint32_t protocol_checksum(const uint8_t *data, size_t len) {
+    uint32_t crc = 0xFFFFFFFF;
+    for (size_t i = 0; i < len; i++) {
+        crc ^= data[i];
+        for (int j = 0; j < 8; j++) {
+            crc = (crc >> 1) ^ (0xEDB88320 & -(crc & 1));
+        }
+    }
+    return ~crc;
+}

ide/native/chat/protocol.h

@@ -0,0 +1,42 @@
+#ifndef SOVEREIGN_PROTOCOL_H
+#define SOVEREIGN_PROTOCOL_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#define PROTOCOL_VERSION 1
+#define MAX_MESSAGE_SIZE (4 * 1024 * 1024)
+
+typedef enum MsgType {
+    MSG_HANDSHAKE           = 0x01,
+    MSG_CONVERSATION_CREATE = 0x10,
+    MSG_CONVERSATION_MSG    = 0x11,
+    MSG_CONVERSATION_CANCEL = 0x12,
+    MSG_STREAM_STARTED      = 0x20,
+    MSG_STREAM_DELTA        = 0x21,
+    MSG_STREAM_COMPLETED    = 0x22,
+    MSG_TOOL_STARTED        = 0x30,
+    MSG_TOOL_COMPLETED      = 0x31,
+    MSG_APPROVAL_REQUESTED  = 0x40,
+    MSG_APPROVAL_RESOLVED   = 0x41,
+    MSG_AGENT_STATE         = 0x50,
+    MSG_ERROR               = 0xFF,
+} MsgType;
+
+#pragma pack(push, 1)
+typedef struct FrameHeader {
+    uint8_t  protocol_version;
+    uint8_t  message_type;
+    uint32_t request_id;
+    uint32_t workspace_id;
+    uint32_t conversation_id;
+    uint32_t payload_length;
+    uint32_t checksum;
+} FrameHeader;
+#pragma pack(pop)
+
+#define FRAME_HEADER_SIZE sizeof(FrameHeader)
+
+uint32_t protocol_checksum(const uint8_t *data, size_t len);
+
+#endif /* SOVEREIGN_PROTOCOL_H */

ide/native/core/arena.c

@@ -0,0 +1,68 @@
+/*
+ * Sovereign IDE — Arena Allocator
+ * Bump-pointer allocator for frame-scoped allocations.
+ * No individual frees. Reset the arena to reclaim all memory at once.
+ */
+
+#include "arena.h"
+#include <string.h>
+#include <assert.h>
+
+#ifndef ARENA_DEFAULT_CAPACITY
+#define ARENA_DEFAULT_CAPACITY (1024 * 1024) /* 1 MiB */
+#endif
+
+#define ARENA_ALIGN 16
+
+static size_t align_up(size_t n, size_t align) {
+    return (n + align - 1) & ~(align - 1);
+}
+
+void arena_init(Arena *a, size_t capacity) {
+    a->base = (uint8_t *)VirtualAlloc(NULL, capacity,
+                                       MEM_RESERVE | MEM_COMMIT,
+                                       PAGE_READWRITE);
+    assert(a->base != NULL);
+    a->capacity = capacity;
+    a->offset = 0;
+}
+
+void arena_init_default(Arena *a) {
+    arena_init(a, ARENA_DEFAULT_CAPACITY);
+}
+
+void *arena_alloc(Arena *a, size_t size) {
+    size_t aligned = align_up(size, ARENA_ALIGN);
+    assert(a->offset + aligned <= a->capacity);
+    void *ptr = a->base + a->offset;
+    a->offset += aligned;
+    return ptr;
+}
+
+void *arena_alloc_zero(Arena *a, size_t size) {
+    void *ptr = arena_alloc(a, size);
+    memset(ptr, 0, size);
+    return ptr;
+}
+
+void arena_reset(Arena *a) {
+    a->offset = 0;
+}
+
+void arena_destroy(Arena *a) {
+    if (a->base) {
+        VirtualFree(a->base, 0, MEM_RELEASE);
+        a->base = NULL;
+    }
+    a->capacity = 0;
+    a->offset = 0;
+}
+
+ArenaMark arena_mark(Arena *a) {
+    return (ArenaMark){ .offset = a->offset };
+}
+
+void arena_restore(Arena *a, ArenaMark mark) {
+    assert(mark.offset <= a->offset);
+    a->offset = mark.offset;
+}

ide/native/core/arena.h

@@ -0,0 +1,28 @@
+#ifndef SOVEREIGN_ARENA_H
+#define SOVEREIGN_ARENA_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <windows.h>
+
+typedef struct Arena {
+    uint8_t *base;
+    size_t   capacity;
+    size_t   offset;
+} Arena;
+
+typedef struct ArenaMark {
+    size_t offset;
+} ArenaMark;
+
+void  arena_init(Arena *a, size_t capacity);
+void  arena_init_default(Arena *a);
+void *arena_alloc(Arena *a, size_t size);
+void *arena_alloc_zero(Arena *a, size_t size);
+void  arena_reset(Arena *a);
+void  arena_destroy(Arena *a);
+
+ArenaMark arena_mark(Arena *a);
+void      arena_restore(Arena *a, ArenaMark mark);
+
+#endif /* SOVEREIGN_ARENA_H */

ide/native/core/errors.h

@@ -0,0 +1,27 @@
+#ifndef SOVEREIGN_ERRORS_H
+#define SOVEREIGN_ERRORS_H
+
+#include <stdio.h>
+#include <stdlib.h>
+
+typedef enum SovResult {
+    SOV_OK = 0,
+    SOV_ERR_ALLOC,
+    SOV_ERR_IO,
+    SOV_ERR_PARSE,
+    SOV_ERR_PROTOCOL,
+    SOV_ERR_PIPE,
+    SOV_ERR_FCL_DENIED,
+    SOV_ERR_FCL_INVALID,
+    SOV_ERR_LSP,
+    SOV_ERR_GIT,
+    SOV_ERR_BUILD,
+} SovResult;
+
+#define SOV_ASSERT(cond, msg) \
+    do { (void)(cond); (void)(msg); } while(0)
+
+#define SOV_TRY(expr) \
+    do { SovResult _r = (expr); if (_r != SOV_OK) return _r; } while(0)
+
+#endif /* SOVEREIGN_ERRORS_H */

ide/native/core/events.c

@@ -0,0 +1,51 @@
+/*
+ * Sovereign IDE — Event System
+ * Lock-free SPSC ring buffer for inter-module communication.
+ * C native modules post events; consumers drain per frame.
+ */
+
+#include "events.h"
+#include <string.h>
+#include <assert.h>
+
+#define EVENT_QUEUE_CAPACITY 4096
+
+static struct {
+    Event    ring[EVENT_QUEUE_CAPACITY];
+    volatile LONG write_pos;
+    volatile LONG read_pos;
+} g_events;
+
+void events_init(void) {
+    memset(&g_events, 0, sizeof(g_events));
+}
+
+bool event_post(Event ev) {
+    LONG w = g_events.write_pos;
+    LONG next = (w + 1) % EVENT_QUEUE_CAPACITY;
+    if (next == g_events.read_pos) {
+        return false; /* queue full */
+    }
+    g_events.ring[w] = ev;
+    MemoryBarrier();
+    InterlockedExchange(&g_events.write_pos, next);
+    return true;
+}
+
+bool event_poll(Event *out) {
+    LONG r = g_events.read_pos;
+    if (r == g_events.write_pos) {
+        return false; /* empty */
+    }
+    *out = g_events.ring[r];
+    MemoryBarrier();
+    InterlockedExchange(&g_events.read_pos, (r + 1) % EVENT_QUEUE_CAPACITY);
+    return true;
+}
+
+void events_drain(EventHandler handler, void *ctx) {
+    Event ev;
+    while (event_poll(&ev)) {
+        handler(&ev, ctx);
+    }
+}

ide/native/core/events.h

@@ -0,0 +1,49 @@
+#ifndef SOVEREIGN_EVENTS_H
+#define SOVEREIGN_EVENTS_H
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <windows.h>
+
+typedef enum EventKind {
+    EVENT_NONE = 0,
+    EVENT_KEY_DOWN,
+    EVENT_KEY_UP,
+    EVENT_CHAR_INPUT,
+    EVENT_MOUSE_MOVE,
+    EVENT_MOUSE_DOWN,
+    EVENT_MOUSE_UP,
+    EVENT_MOUSE_WHEEL,
+    EVENT_RESIZE,
+    EVENT_FOCUS_GAINED,
+    EVENT_FOCUS_LOST,
+    EVENT_FILE_CHANGED,
+    EVENT_CHAT_MESSAGE,
+    EVENT_TOOL_RESULT,
+    EVENT_APPROVAL_REQUEST,
+    EVENT_BUILD_OUTPUT,
+    EVENT_DIAGNOSTIC,
+    EVENT_QUIT,
+} EventKind;
+
+typedef struct Event {
+    EventKind kind;
+    uint64_t  timestamp;
+    union {
+        struct { uint32_t vk; uint32_t scancode; uint32_t mods; }  key;
+        struct { uint32_t codepoint; }                              ch;
+        struct { int32_t x; int32_t y; uint32_t buttons; }         mouse;
+        struct { int32_t delta; }                                   wheel;
+        struct { uint32_t width; uint32_t height; }                 resize;
+        struct { uint64_t id; }                                     message;
+    };
+} Event;
+
+typedef void (*EventHandler)(const Event *ev, void *ctx);
+
+void events_init(void);
+bool event_post(Event ev);
+bool event_poll(Event *out);
+void events_drain(EventHandler handler, void *ctx);
+
+#endif /* SOVEREIGN_EVENTS_H */

ide/native/core/strings.c

@@ -0,0 +1,73 @@
+/*
+ * Sovereign IDE — Interned Strings
+ * All strings in the IDE are length-prefixed, immutable, arena-allocated.
+ * Interning deduplicates identical strings via FNV-1a hash table.
+ */
+
+#include "strings.h"
+#include "arena.h"
+#include <string.h>
+
+#define INTERN_BUCKET_COUNT 4096
+
+static uint64_t fnv1a(const char *data, size_t len) {
+    uint64_t h = 0xcbf29ce484222325ULL;
+    for (size_t i = 0; i < len; i++) {
+        h ^= (uint8_t)data[i];
+        h *= 0x100000001b3ULL;
+    }
+    return h;
+}
+
+typedef struct InternEntry {
+    Str                  str;
+    struct InternEntry  *next;
+} InternEntry;
+
+static struct {
+    Arena        arena;
+    InternEntry *buckets[INTERN_BUCKET_COUNT];
+    size_t       count;
+} g_intern;
+
+void strings_init(void) {
+    arena_init_default(&g_intern.arena);
+    memset(g_intern.buckets, 0, sizeof(g_intern.buckets));
+    g_intern.count = 0;
+}
+
+void strings_shutdown(void) {
+    arena_destroy(&g_intern.arena);
+}
+
+Str str_intern_len(const char *data, size_t len) {
+    uint64_t hash = fnv1a(data, len);
+    size_t bucket = hash % INTERN_BUCKET_COUNT;
+
+    for (InternEntry *e = g_intern.buckets[bucket]; e; e = e->next) {
+        if (e->str.len == len && memcmp(e->str.ptr, data, len) == 0) {
+            return e->str;
+        }
+    }
+
+    char *copy = (char *)arena_alloc(&g_intern.arena, len + 1);
+    memcpy(copy, data, len);
+    copy[len] = '\0';
+
+    InternEntry *entry = (InternEntry *)arena_alloc(&g_intern.arena, sizeof(InternEntry));
+    entry->str.ptr = copy;
+    entry->str.len = len;
+    entry->next = g_intern.buckets[bucket];
+    g_intern.buckets[bucket] = entry;
+    g_intern.count++;
+
+    return entry->str;
+}
+
+Str str_intern(const char *cstr) {
+    return str_intern_len(cstr, strlen(cstr));
+}
+
+bool str_eq(Str a, Str b) {
+    return a.ptr == b.ptr;
+}

ide/native/core/strings.h

@@ -0,0 +1,22 @@
+#ifndef SOVEREIGN_STRINGS_H
+#define SOVEREIGN_STRINGS_H
+
+#include <stddef.h>
+#include <stdbool.h>
+
+typedef struct Str {
+    const char *ptr;
+    size_t      len;
+} Str;
+
+void strings_init(void);
+void strings_shutdown(void);
+
+Str  str_intern(const char *cstr);
+Str  str_intern_len(const char *data, size_t len);
+bool str_eq(Str a, Str b);
+
+#define STR_FMT "%.*s"
+#define STR_ARG(s) (int)(s).len, (s).ptr
+
+#endif /* SOVEREIGN_STRINGS_H */

ide/native/core/threading.h

@@ -0,0 +1,31 @@
+#ifndef SOVEREIGN_THREADING_H
+#define SOVEREIGN_THREADING_H
+
+#include <windows.h>
+#include <stdint.h>
+
+typedef struct SovThread {
+    HANDLE   handle;
+    DWORD    id;
+    void   (*entry)(void *);
+    void    *arg;
+} SovThread;
+
+typedef struct SovMutex {
+    SRWLOCK lock;
+} SovMutex;
+
+typedef struct SovCondVar {
+    CONDITION_VARIABLE cv;
+} SovCondVar;
+
+static inline void sov_mutex_init(SovMutex *m)    { InitializeSRWLock(&m->lock); }
+static inline void sov_mutex_lock(SovMutex *m)    { AcquireSRWLockExclusive(&m->lock); }
+static inline void sov_mutex_unlock(SovMutex *m)  { ReleaseSRWLockExclusive(&m->lock); }
+
+static inline void sov_condvar_init(SovCondVar *cv)              { InitializeConditionVariable(&cv->cv); }
+static inline void sov_condvar_wait(SovCondVar *cv, SovMutex *m) { SleepConditionVariableSRW(&cv->cv, &m->lock, INFINITE, 0); }
+static inline void sov_condvar_signal(SovCondVar *cv)            { WakeConditionVariable(&cv->cv); }
+static inline void sov_condvar_broadcast(SovCondVar *cv)         { WakeAllConditionVariable(&cv->cv); }
+
+#endif /* SOVEREIGN_THREADING_H */

ide/native/editor/buffer.c

@@ -0,0 +1,482 @@
+/*
+ * Sovereign IDE — Piece Table Buffer
+ * Supports insert, delete, undo/redo, line indexing.
+ */
+
+#include "buffer.h"
+#include "../core/arena.h"
+#include <string.h>
+#include <assert.h>
+#include <stdlib.h>
+
+#define ADD_BUFFER_INITIAL_CAP (256 * 1024)
+#define UNDO_STACK_CAP 1024
+
+typedef enum PieceSource { PIECE_ORIGINAL, PIECE_ADD } PieceSource;
+
+typedef struct Piece {
+    PieceSource    source;
+    size_t         start;
+    size_t         length;
+    struct Piece  *prev;
+    struct Piece  *next;
+} Piece;
+
+typedef enum UndoKind { UNDO_INSERT, UNDO_DELETE } UndoKind;
+
+typedef struct UndoEntry {
+    UndoKind kind;
+    size_t   offset;
+    size_t   len;
+    char    *deleted_text;
+} UndoEntry;
+
+struct Buffer {
+    Arena   arena;
+
+    char   *original;
+    size_t  original_len;
+
+    char   *add_buf;
+    size_t  add_len;
+    size_t  add_cap;
+
+    Piece   sentinel;
+    size_t  total_len;
+    size_t  line_count;
+
+    UndoEntry undo_stack[UNDO_STACK_CAP];
+    int       undo_top;
+    int       redo_top;
+    bool      dirty;
+};
+
+static const char *piece_data(const Buffer *b, const Piece *p) {
+    return (p->source == PIECE_ORIGINAL)
+        ? b->original + p->start
+        : b->add_buf + p->start;
+}
+
+static size_t count_newlines(const char *text, size_t len) {
+    size_t n = 0;
+    for (size_t i = 0; i < len; i++) {
+        if (text[i] == '\n') n++;
+    }
+    return n;
+}
+
+static void append_to_add(Buffer *b, const char *text, size_t len) {
+    if (b->add_len + len > b->add_cap) {
+        size_t new_cap = b->add_cap * 2;
+        while (new_cap < b->add_len + len) new_cap *= 2;
+        char *new_buf = (char *)arena_alloc(&b->arena, new_cap);
+        memcpy(new_buf, b->add_buf, b->add_len);
+        b->add_buf = new_buf;
+        b->add_cap = new_cap;
+    }
+    memcpy(b->add_buf + b->add_len, text, len);
+    b->add_len += len;
+}
+
+static Piece *alloc_piece(Buffer *b) {
+    return (Piece *)arena_alloc(&b->arena, sizeof(Piece));
+}
+
+static void find_piece_at(Buffer *b, size_t offset, Piece **out_piece, size_t *out_local) {
+    Piece *p = b->sentinel.next;
+    size_t pos = 0;
+    while (p != &b->sentinel && pos + p->length <= offset) {
+        pos += p->length;
+        p = p->next;
+    }
+    *out_piece = p;
+    *out_local = offset - pos;
+}
+
+Buffer *buffer_create(const char *text, size_t len) {
+    Arena a;
+    arena_init(&a, 8 * 1024 * 1024);
+
+    Buffer *b = (Buffer *)arena_alloc_zero(&a, sizeof(Buffer));
+    b->arena = a;
+
+    b->original = (char *)arena_alloc(&b->arena, len + 1);
+    memcpy(b->original, text, len);
+    b->original[len] = '\0';
+    b->original_len = len;
+
+    b->add_cap = ADD_BUFFER_INITIAL_CAP;
+    b->add_buf = (char *)arena_alloc(&b->arena, b->add_cap);
+    b->add_len = 0;
+
+    if (len > 0) {
+        Piece *first = alloc_piece(b);
+        first->source = PIECE_ORIGINAL;
+        first->start  = 0;
+        first->length = len;
+        b->sentinel.next = first;
+        b->sentinel.prev = first;
+        first->prev = &b->sentinel;
+        first->next = &b->sentinel;
+    } else {
+        b->sentinel.next = &b->sentinel;
+        b->sentinel.prev = &b->sentinel;
+    }
+
+    b->total_len = len;
+    b->line_count = 1 + count_newlines(text, len);
+    b->undo_top = 0;
+    b->redo_top = 0;
+    b->dirty = false;
+
+    return b;
+}
+
+void buffer_destroy(Buffer *b) {
+    for (int i = 0; i < b->undo_top; i++) {
+        free(b->undo_stack[i].deleted_text);
+    }
+    Arena a = b->arena;
+    arena_destroy(&a);
+}
+
+size_t buffer_length(const Buffer *b) {
+    return b->total_len;
+}
+
+size_t buffer_line_count(const Buffer *b) {
+    return b->line_count;
+}
+
+bool buffer_is_dirty(const Buffer *b) {
+    return b->dirty;
+}
+
+void buffer_mark_clean(Buffer *b) {
+    b->dirty = false;
+}
+
+bool buffer_can_undo(const Buffer *b) {
+    return b->undo_top > 0;
+}
+
+bool buffer_can_redo(const Buffer *b) {
+    return b->redo_top > 0;
+}
+
+static void push_undo(Buffer *b, UndoKind kind, size_t offset, size_t len, const char *text) {
+    if (b->undo_top >= UNDO_STACK_CAP) {
+        free(b->undo_stack[0].deleted_text);
+        memmove(&b->undo_stack[0], &b->undo_stack[1], (UNDO_STACK_CAP - 1) * sizeof(UndoEntry));
+        b->undo_top--;
+    }
+    /* discard redo stack on new edit */
+    for (int i = b->undo_top; i < b->undo_top + b->redo_top; i++) {
+        if (i < UNDO_STACK_CAP) free(b->undo_stack[i].deleted_text);
+    }
+    b->redo_top = 0;
+
+    UndoEntry *e = &b->undo_stack[b->undo_top++];
+    e->kind = kind;
+    e->offset = offset;
+    e->len = len;
+    /* always copy the text — inserts need it for redo, deletes need it for undo */
+    if (text && len > 0) {
+        e->deleted_text = (char *)malloc(len);
+        memcpy(e->deleted_text, text, len);
+    } else {
+        e->deleted_text = NULL;
+    }
+}
+
+void buffer_insert(Buffer *b, size_t offset, const char *text, size_t len) {
+    if (len == 0) return;
+    if (offset > b->total_len) offset = b->total_len;
+
+    size_t add_start = b->add_len;
+    append_to_add(b, text, len);
+
+    Piece *p;
+    size_t local;
+    find_piece_at(b, offset, &p, &local);
+
+    Piece *new_piece = alloc_piece(b);
+    new_piece->source = PIECE_ADD;
+    new_piece->start  = add_start;
+    new_piece->length = len;
+
+    if (p == &b->sentinel || local == 0) {
+        new_piece->prev = p->prev;
+        new_piece->next = p;
+        p->prev->next = new_piece;
+        p->prev = new_piece;
+    } else if (local == p->length) {
+        new_piece->prev = p;
+        new_piece->next = p->next;
+        p->next->prev = new_piece;
+        p->next = new_piece;
+    } else {
+        Piece *right = alloc_piece(b);
+        right->source = p->source;
+        right->start  = p->start + local;
+        right->length = p->length - local;
+        p->length = local;
+
+        new_piece->prev = p;
+        new_piece->next = right;
+        right->prev = new_piece;
+        right->next = p->next;
+        p->next->prev = right;
+        p->next = new_piece;
+    }
+
+    b->total_len += len;
+    b->line_count += count_newlines(text, len);
+    b->dirty = true;
+
+    push_undo(b, UNDO_INSERT, offset, len, text);
+}
+
+void buffer_delete(Buffer *b, size_t offset, size_t len) {
+    if (len == 0 || offset >= b->total_len) return;
+    if (offset + len > b->total_len) len = b->total_len - offset;
+
+    /* save deleted text for undo */
+    char *deleted = (char *)malloc(len);
+    buffer_read(b, offset, deleted, len);
+    b->line_count -= count_newlines(deleted, len);
+
+    size_t remaining = len;
+    Piece *p;
+    size_t local;
+    find_piece_at(b, offset, &p, &local);
+
+    while (remaining > 0 && p != &b->sentinel) {
+        if (local == 0 && remaining >= p->length) {
+            /* remove entire piece */
+            Piece *next = p->next;
+            p->prev->next = p->next;
+            p->next->prev = p->prev;
+            remaining -= p->length;
+            p = next;
+            local = 0;
+        } else if (local == 0) {
+            /* trim from start */
+            p->start += remaining;
+            p->length -= remaining;
+            remaining = 0;
+        } else if (local + remaining >= p->length) {
+            /* trim from end */
+            size_t removed = p->length - local;
+            p->length = local;
+            remaining -= removed;
+            p = p->next;
+            local = 0;
+        } else {
+            /* split: remove middle */
+            Piece *right = alloc_piece(b);
+            right->source = p->source;
+            right->start  = p->start + local + remaining;
+            right->length = p->length - local - remaining;
+            p->length = local;
+
+            right->next = p->next;
+            right->prev = p;
+            p->next->prev = right;
+            p->next = right;
+            remaining = 0;
+        }
+    }
+
+    b->total_len -= len;
+    b->dirty = true;
+
+    push_undo(b, UNDO_DELETE, offset, len, deleted);
+    free(deleted);
+}
+
+static void raw_insert(Buffer *b, size_t offset, const char *text, size_t len) {
+    size_t add_start = b->add_len;
+    append_to_add(b, text, len);
+
+    Piece *p;
+    size_t local;
+    find_piece_at(b, offset, &p, &local);
+
+    Piece *new_piece = alloc_piece(b);
+    new_piece->source = PIECE_ADD;
+    new_piece->start  = add_start;
+    new_piece->length = len;
+
+    if (p == &b->sentinel || local == 0) {
+        new_piece->prev = p->prev;
+        new_piece->next = p;
+        p->prev->next = new_piece;
+        p->prev = new_piece;
+    } else if (local == p->length) {
+        new_piece->prev = p;
+        new_piece->next = p->next;
+        p->next->prev = new_piece;
+        p->next = new_piece;
+    } else {
+        Piece *right = alloc_piece(b);
+        right->source = p->source;
+        right->start  = p->start + local;
+        right->length = p->length - local;
+        p->length = local;
+        new_piece->prev = p;
+        new_piece->next = right;
+        right->prev = new_piece;
+        right->next = p->next;
+        p->next->prev = right;
+        p->next = new_piece;
+    }
+
+    b->total_len += len;
+    b->line_count += count_newlines(text, len);
+}
+
+static void raw_delete(Buffer *b, size_t offset, size_t len) {
+    if (len == 0) return;
+    char *tmp = (char *)malloc(len);
+    buffer_read(b, offset, tmp, len);
+    b->line_count -= count_newlines(tmp, len);
+    free(tmp);
+
+    size_t remaining = len;
+    Piece *p;
+    size_t local;
+    find_piece_at(b, offset, &p, &local);
+
+    while (remaining > 0 && p != &b->sentinel) {
+        if (local == 0 && remaining >= p->length) {
+            Piece *next = p->next;
+            p->prev->next = p->next;
+            p->next->prev = p->prev;
+            remaining -= p->length;
+            p = next;
+            local = 0;
+        } else if (local == 0) {
+            p->start += remaining;
+            p->length -= remaining;
+            remaining = 0;
+        } else if (local + remaining >= p->length) {
+            size_t removed = p->length - local;
+            p->length = local;
+            remaining -= removed;
+            p = p->next;
+            local = 0;
+        } else {
+            Piece *right = alloc_piece(b);
+            right->source = p->source;
+            right->start  = p->start + local + remaining;
+            right->length = p->length - local - remaining;
+            p->length = local;
+            right->next = p->next;
+            right->prev = p;
+            p->next->prev = right;
+            p->next = right;
+            remaining = 0;
+        }
+    }
+    b->total_len -= len;
+}
+
+void buffer_undo(Buffer *b) {
+    if (b->undo_top == 0) return;
+    b->undo_top--;
+    UndoEntry *e = &b->undo_stack[b->undo_top];
+    b->redo_top++;
+
+    if (e->kind == UNDO_INSERT) {
+        raw_delete(b, e->offset, e->len);
+    } else {
+        raw_insert(b, e->offset, e->deleted_text, e->len);
+    }
+    b->dirty = true;
+}
+
+void buffer_redo(Buffer *b) {
+    if (b->redo_top == 0) return;
+    UndoEntry *e = &b->undo_stack[b->undo_top];
+    b->undo_top++;
+    b->redo_top--;
+
+    if (e->kind == UNDO_INSERT) {
+        raw_insert(b, e->offset, e->deleted_text, e->len);
+    } else {
+        raw_delete(b, e->offset, e->len);
+    }
+    b->dirty = true;
+}
+
+size_t buffer_read(const Buffer *b, size_t offset, char *out, size_t max_len) {
+    size_t copied = 0;
+    size_t pos = 0;
+    const Piece *p = b->sentinel.next;
+
+    while (p != &b->sentinel && pos + p->length <= offset) {
+        pos += p->length;
+        p = p->next;
+    }
+
+    size_t skip = offset - pos;
+    while (p != &b->sentinel && copied < max_len) {
+        const char *data = piece_data(b, p) + skip;
+        size_t avail = p->length - skip;
+        size_t to_copy = (avail < max_len - copied) ? avail : (max_len - copied);
+        memcpy(out + copied, data, to_copy);
+        copied += to_copy;
+        skip = 0;
+        p = p->next;
+    }
+
+    return copied;
+}
+
+size_t buffer_line_start(const Buffer *b, size_t line) {
+    if (line == 0) return 0;
+    size_t current_line = 0;
+    size_t pos = 0;
+    const Piece *p = b->sentinel.next;
+
+    while (p != &b->sentinel) {
+        const char *data = piece_data(b, p);
+        for (size_t i = 0; i < p->length; i++) {
+            if (data[i] == '\n') {
+                current_line++;
+                if (current_line == line) return pos + i + 1;
+            }
+        }
+        pos += p->length;
+        p = p->next;
+    }
+    return b->total_len;
+}
+
+size_t buffer_line_length(const Buffer *b, size_t line) {
+    size_t start = buffer_line_start(b, line);
+    if (start >= b->total_len) return 0;
+
+    size_t pos = start;
+    const Piece *p = b->sentinel.next;
+    size_t piece_pos = 0;
+
+    while (p != &b->sentinel && piece_pos + p->length <= start) {
+        piece_pos += p->length;
+        p = p->next;
+    }
+
+    size_t skip = start - piece_pos;
+    while (p != &b->sentinel) {
+        const char *data = piece_data(b, p) + skip;
+        size_t avail = p->length - skip;
+        for (size_t i = 0; i < avail; i++) {
+            if (data[i] == '\n') return pos - start;
+            pos++;
+        }
+        skip = 0;
+        p = p->next;
+    }
+    return pos - start;
+}

ide/native/editor/buffer.h

@@ -0,0 +1,27 @@
+#ifndef SOVEREIGN_BUFFER_H
+#define SOVEREIGN_BUFFER_H
+
+#include <stddef.h>
+#include <stdbool.h>
+
+typedef struct Buffer Buffer;
+
+Buffer *buffer_create(const char *text, size_t len);
+void    buffer_destroy(Buffer *b);
+size_t  buffer_length(const Buffer *b);
+size_t  buffer_line_count(const Buffer *b);
+void    buffer_insert(Buffer *b, size_t offset, const char *text, size_t len);
+void    buffer_delete(Buffer *b, size_t offset, size_t len);
+size_t  buffer_read(const Buffer *b, size_t offset, char *out, size_t max_len);
+
+void    buffer_undo(Buffer *b);
+void    buffer_redo(Buffer *b);
+bool    buffer_can_undo(const Buffer *b);
+bool    buffer_can_redo(const Buffer *b);
+bool    buffer_is_dirty(const Buffer *b);
+void    buffer_mark_clean(Buffer *b);
+
+size_t  buffer_line_start(const Buffer *b, size_t line);
+size_t  buffer_line_length(const Buffer *b, size_t line);
+
+#endif /* SOVEREIGN_BUFFER_H */

ide/native/editor/document.c

@@ -0,0 +1,151 @@
+/*
+ * Sovereign IDE — Document
+ * File open/save with UTF-8 + CRLF normalization.
+ */
+
+#include "document.h"
+#include <windows.h>
+#include <stdlib.h>
+#include <string.h>
+
+void document_new(Document *doc) {
+    doc->buffer = buffer_create("", 0);
+    doc->path[0] = L'\0';
+    doc->has_path = false;
+    doc->line_ending = LE_LF;
+}
+
+static LineEnding detect_line_ending(const char *text, size_t len) {
+    for (size_t i = 0; i + 1 < len; i++) {
+        if (text[i] == '\r' && text[i+1] == '\n') return LE_CRLF;
+    }
+    for (size_t i = 0; i < len; i++) {
+        if (text[i] == '\r') return LE_CR;
+    }
+    return LE_LF;
+}
+
+/* Normalize CRLF/CR to LF for internal storage */
+static char *normalize_to_lf(const char *src, size_t src_len, size_t *out_len) {
+    char *dst = (char *)malloc(src_len + 1);
+    size_t j = 0;
+    for (size_t i = 0; i < src_len; i++) {
+        if (src[i] == '\r') {
+            dst[j++] = '\n';
+            if (i + 1 < src_len && src[i+1] == '\n') i++;
+        } else {
+            dst[j++] = src[i];
+        }
+    }
+    dst[j] = '\0';
+    *out_len = j;
+    return dst;
+}
+
+SovResult document_open(Document *doc, const wchar_t *path) {
+    HANDLE h = CreateFileW(path, GENERIC_READ, FILE_SHARE_READ, NULL,
+                           OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
+    if (h == INVALID_HANDLE_VALUE) return SOV_ERR_IO;
+
+    LARGE_INTEGER file_size;
+    GetFileSizeEx(h, &file_size);
+    if (file_size.QuadPart > 256 * 1024 * 1024) {
+        CloseHandle(h);
+        return SOV_ERR_IO;
+    }
+
+    size_t sz = (size_t)file_size.QuadPart;
+    char *raw = (char *)malloc(sz + 1);
+    DWORD nread = 0;
+    ReadFile(h, raw, (DWORD)sz, &nread, NULL);
+    CloseHandle(h);
+    raw[nread] = '\0';
+
+    /* Skip UTF-8 BOM if present */
+    const char *text = raw;
+    size_t text_len = nread;
+    if (text_len >= 3 &&
+        (unsigned char)text[0] == 0xEF &&
+        (unsigned char)text[1] == 0xBB &&
+        (unsigned char)text[2] == 0xBF) {
+        text += 3;
+        text_len -= 3;
+    }
+
+    doc->line_ending = detect_line_ending(text, text_len);
+
+    size_t norm_len;
+    char *norm = normalize_to_lf(text, text_len, &norm_len);
+    free(raw);
+
+    doc->buffer = buffer_create(norm, norm_len);
+    free(norm);
+
+    wcscpy_s(doc->path, MAX_PATH, path);
+    doc->has_path = true;
+    return SOV_OK;
+}
+
+SovResult document_save(Document *doc) {
+    if (!doc->has_path) return SOV_ERR_IO;
+    SovResult r = document_save_as(doc, doc->path);
+    return r;
+}
+
+SovResult document_save_as(Document *doc, const wchar_t *path) {
+    size_t len = buffer_length(doc->buffer);
+    char *content = (char *)malloc(len + 1);
+    buffer_read(doc->buffer, 0, content, len);
+    content[len] = '\0';
+
+    /* Re-apply original line endings */
+    char *output = content;
+    size_t out_len = len;
+    char *crlf_buf = NULL;
+
+    if (doc->line_ending == LE_CRLF) {
+        /* count newlines to allocate */
+        size_t nl = 0;
+        for (size_t i = 0; i < len; i++) if (content[i] == '\n') nl++;
+        crlf_buf = (char *)malloc(len + nl + 1);
+        size_t j = 0;
+        for (size_t i = 0; i < len; i++) {
+            if (content[i] == '\n') crlf_buf[j++] = '\r';
+            crlf_buf[j++] = content[i];
+        }
+        crlf_buf[j] = '\0';
+        output = crlf_buf;
+        out_len = j;
+    }
+
+    HANDLE h = CreateFileW(path, GENERIC_WRITE, 0, NULL,
+                           CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
+    if (h == INVALID_HANDLE_VALUE) {
+        free(content);
+        free(crlf_buf);
+        return SOV_ERR_IO;
+    }
+
+    DWORD written;
+    WriteFile(h, output, (DWORD)out_len, &written, NULL);
+    CloseHandle(h);
+
+    free(content);
+    free(crlf_buf);
+
+    wcscpy_s(doc->path, MAX_PATH, path);
+    doc->has_path = true;
+    buffer_mark_clean(doc->buffer);
+    return SOV_OK;
+}
+
+bool document_is_dirty(const Document *doc) {
+    return buffer_is_dirty(doc->buffer);
+}
+
+void document_destroy(Document *doc) {
+    if (doc->buffer) {
+        buffer_destroy(doc->buffer);
+        doc->buffer = NULL;
+    }
+}

ide/native/editor/document.h

@@ -0,0 +1,26 @@
+#ifndef SOVEREIGN_DOCUMENT_H
+#define SOVEREIGN_DOCUMENT_H
+
+#include <windows.h>
+#include "buffer.h"
+#include "../core/errors.h"
+#include <stdbool.h>
+#include <stddef.h>
+
+typedef enum LineEnding { LE_LF, LE_CRLF, LE_CR } LineEnding;
+
+typedef struct Document {
+    Buffer     *buffer;
+    wchar_t     path[MAX_PATH];
+    LineEnding  line_ending;
+    bool        has_path;
+} Document;
+
+SovResult document_open(Document *doc, const wchar_t *path);
+SovResult document_save(Document *doc);
+SovResult document_save_as(Document *doc, const wchar_t *path);
+void      document_new(Document *doc);
+void      document_destroy(Document *doc);
+bool      document_is_dirty(const Document *doc);
+
+#endif

ide/native/editor/editor_view.cpp

@@ -0,0 +1,613 @@
+/*
+ * Sovereign IDE — Editor View
+ * DirectWrite text rendering, visible caret, selection, keyboard navigation.
+ * C++ for COM vtable calls; all public functions are extern "C".
+ */
+
+#include <windows.h>
+#include <d2d1.h>
+#include <dwrite.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include <wchar.h>
+
+extern "C" {
+#include "editor_view.h"
+#include "document.h"
+#include "buffer.h"
+#include "../lsp/client.h"
+}
+
+#define FONT_SIZE     14.0f
+#define LINE_HEIGHT   20.0f
+#define GUTTER_WIDTH  48.0f
+#define PADDING_LEFT   4.0f
+#define CARET_WIDTH    2.0f
+#define SCROLL_LINES   3
+
+/* Colors (dark theme) */
+static const D2D1_COLOR_F C_BG         = { 0.122f, 0.122f, 0.141f, 1.0f };
+static const D2D1_COLOR_F C_GUTTER     = { 0.098f, 0.098f, 0.118f, 1.0f };
+static const D2D1_COLOR_F C_GUTTER_FG  = { 0.420f, 0.420f, 0.520f, 1.0f };
+static const D2D1_COLOR_F C_TEXT       = { 0.859f, 0.859f, 0.859f, 1.0f };
+static const D2D1_COLOR_F C_CARET      = { 1.000f, 1.000f, 1.000f, 1.0f };
+static const D2D1_COLOR_F C_SEL        = { 0.173f, 0.369f, 0.529f, 0.6f };
+static const D2D1_COLOR_F C_ACTIVE_LINE= { 1.000f, 1.000f, 1.000f, 0.04f };
+static const D2D1_COLOR_F C_SQUIGGLE_E = { 1.000f, 0.260f, 0.260f, 1.0f }; /* error   */
+static const D2D1_COLOR_F C_SQUIGGLE_W = { 1.000f, 0.780f, 0.200f, 1.0f }; /* warning */
+
+struct EditorView {
+    HWND                    hwnd;
+    Document               *doc;
+
+    ID2D1Factory           *d2d_factory;
+    ID2D1HwndRenderTarget  *rt;
+    IDWriteFactory         *dw_factory;
+    IDWriteTextFormat      *text_format;
+    IDWriteTextFormat      *gutter_format;
+
+    ID2D1SolidColorBrush   *br_text;
+    ID2D1SolidColorBrush   *br_gutter_fg;
+    ID2D1SolidColorBrush   *br_caret;
+    ID2D1SolidColorBrush   *br_sel;
+    ID2D1SolidColorBrush   *br_active_line;
+    ID2D1SolidColorBrush   *br_gutter_bg;
+    ID2D1SolidColorBrush   *br_squiggle_e;
+    ID2D1SolidColorBrush   *br_squiggle_w;
+
+    uint32_t    width;
+    uint32_t    height;
+    float       scroll_y;       /* in lines */
+
+    size_t      caret;          /* byte offset in buffer */
+    size_t      sel_anchor;     /* selection start; equals caret = no selection */
+    bool        has_sel;
+
+    bool        caret_visible;  /* blink state */
+    DWORD       caret_tick;
+
+    /* LSP diagnostics for current file */
+    LspDiagList diags;
+    bool        has_diags;
+};
+
+static HRESULT create_brushes(EditorView *ev) {
+    HRESULT hr;
+    hr = ev->rt->CreateSolidColorBrush(C_TEXT,        &ev->br_text);         if (FAILED(hr)) return hr;
+    hr = ev->rt->CreateSolidColorBrush(C_GUTTER_FG,   &ev->br_gutter_fg);    if (FAILED(hr)) return hr;
+    hr = ev->rt->CreateSolidColorBrush(C_CARET,       &ev->br_caret);        if (FAILED(hr)) return hr;
+    hr = ev->rt->CreateSolidColorBrush(C_SEL,         &ev->br_sel);          if (FAILED(hr)) return hr;
+    hr = ev->rt->CreateSolidColorBrush(C_ACTIVE_LINE, &ev->br_active_line);  if (FAILED(hr)) return hr;
+    hr = ev->rt->CreateSolidColorBrush(C_GUTTER,      &ev->br_gutter_bg);    if (FAILED(hr)) return hr;
+    hr = ev->rt->CreateSolidColorBrush(C_SQUIGGLE_E,  &ev->br_squiggle_e);   if (FAILED(hr)) return hr;
+    hr = ev->rt->CreateSolidColorBrush(C_SQUIGGLE_W,  &ev->br_squiggle_w);   if (FAILED(hr)) return hr;
+    return S_OK;
+}
+
+static void release_brushes(EditorView *ev) {
+    auto safe = [](IUnknown *p) { if (p) p->Release(); };
+    safe(ev->br_text);        ev->br_text        = nullptr;
+    safe(ev->br_gutter_fg);   ev->br_gutter_fg   = nullptr;
+    safe(ev->br_caret);       ev->br_caret       = nullptr;
+    safe(ev->br_sel);         ev->br_sel         = nullptr;
+    safe(ev->br_active_line); ev->br_active_line = nullptr;
+    safe(ev->br_gutter_bg);   ev->br_gutter_bg   = nullptr;
+    safe(ev->br_squiggle_e);  ev->br_squiggle_e  = nullptr;
+    safe(ev->br_squiggle_w);  ev->br_squiggle_w  = nullptr;
+}
+
+extern "C" SovResult editor_view_create(EditorView **out, HWND hwnd) {
+    EditorView *ev = (EditorView *)calloc(1, sizeof(EditorView));
+    if (!ev) return SOV_ERR_ALLOC;
+
+    ev->hwnd = hwnd;
+    ev->caret_visible = true;
+    ev->caret_tick = GetTickCount();
+
+    HRESULT hr;
+    hr = D2D1CreateFactory(D2D1_FACTORY_TYPE_SINGLE_THREADED, &ev->d2d_factory);
+    if (FAILED(hr)) { free(ev); return SOV_ERR_ALLOC; }
+
+    hr = DWriteCreateFactory(DWRITE_FACTORY_TYPE_SHARED,
+        __uuidof(IDWriteFactory),
+        reinterpret_cast<IUnknown **>(&ev->dw_factory));
+    if (FAILED(hr)) { free(ev); return SOV_ERR_ALLOC; }
+
+    hr = ev->dw_factory->CreateTextFormat(
+        L"Consolas", nullptr,
+        DWRITE_FONT_WEIGHT_NORMAL, DWRITE_FONT_STYLE_NORMAL, DWRITE_FONT_STRETCH_NORMAL,
+        FONT_SIZE, L"en-us", &ev->text_format);
+    if (FAILED(hr)) { free(ev); return SOV_ERR_ALLOC; }
+
+    hr = ev->dw_factory->CreateTextFormat(
+        L"Consolas", nullptr,
+        DWRITE_FONT_WEIGHT_NORMAL, DWRITE_FONT_STYLE_NORMAL, DWRITE_FONT_STRETCH_NORMAL,
+        11.0f, L"en-us", &ev->gutter_format);
+    if (FAILED(hr)) { free(ev); return SOV_ERR_ALLOC; }
+    ev->gutter_format->SetTextAlignment(DWRITE_TEXT_ALIGNMENT_TRAILING);
+
+    RECT rc;
+    GetClientRect(hwnd, &rc);
+    ev->width  = (uint32_t)(rc.right - rc.left);
+    ev->height = (uint32_t)(rc.bottom - rc.top);
+
+    D2D1_RENDER_TARGET_PROPERTIES rtp = D2D1::RenderTargetProperties();
+    D2D1_HWND_RENDER_TARGET_PROPERTIES hwp = D2D1::HwndRenderTargetProperties(
+        hwnd, D2D1::SizeU(ev->width, ev->height));
+    hr = ev->d2d_factory->CreateHwndRenderTarget(rtp, hwp, &ev->rt);
+    if (FAILED(hr)) { free(ev); return SOV_ERR_ALLOC; }
+
+    if (FAILED(create_brushes(ev))) { free(ev); return SOV_ERR_ALLOC; }
+
+    *out = ev;
+    return SOV_OK;
+}
+
+extern "C" void editor_view_destroy(EditorView *ev) {
+    if (!ev) return;
+    release_brushes(ev);
+    if (ev->text_format)   { ev->text_format->Release(); }
+    if (ev->gutter_format) { ev->gutter_format->Release(); }
+    if (ev->rt)            { ev->rt->Release(); }
+    if (ev->d2d_factory)   { ev->d2d_factory->Release(); }
+    if (ev->dw_factory)    { ev->dw_factory->Release(); }
+    free(ev);
+}
+
+extern "C" void editor_view_set_document(EditorView *ev, Document *doc) {
+    ev->doc    = doc;
+    ev->caret  = 0;
+    ev->sel_anchor = 0;
+    ev->has_sel    = false;
+    ev->scroll_y   = 0.0f;
+}
+
+extern "C" void editor_view_set_diagnostics(EditorView *ev, const LspDiagList *list) {
+    if (!ev) return;
+    if (list) {
+        ev->diags    = *list;
+        ev->has_diags = (list->count > 0);
+    } else {
+        ev->has_diags = false;
+    }
+    InvalidateRect(ev->hwnd, nullptr, FALSE);
+}
+
+extern "C" void editor_view_resize(EditorView *ev, uint32_t w, uint32_t h) {
+    ev->width  = w;
+    ev->height = h;
+    if (ev->rt) ev->rt->Resize(D2D1::SizeU(w, h));
+}
+
+/* Convert byte offset → (line, col) */
+static void offset_to_line_col(Document *doc, size_t offset, size_t *line, size_t *col) {
+    char tmp[4096];
+    size_t pos = 0;
+    *line = 0;
+    *col  = 0;
+    size_t buf_len = buffer_length(doc->buffer);
+    while (pos < offset && pos < buf_len) {
+        size_t chunk = offset - pos;
+        if (chunk > sizeof(tmp)) chunk = sizeof(tmp);
+        size_t n = buffer_read(doc->buffer, pos, tmp, chunk);
+        if (n == 0) break;
+        for (size_t i = 0; i < n && pos < offset; i++, pos++) {
+            if (tmp[i] == '\n') { (*line)++; *col = 0; }
+            else                { (*col)++; }
+        }
+    }
+}
+
+/* Render one line of text using DirectWrite */
+static void draw_line(EditorView *ev, size_t line_idx, float y,
+                      size_t caret_line, size_t sel_start, size_t sel_end, bool has_sel) {
+    if (!ev->doc) return;
+    float x0 = GUTTER_WIDTH + PADDING_LEFT;
+    float view_w = (float)ev->width - x0;
+    if (view_w <= 0) return;
+
+    /* Active line highlight */
+    if (line_idx == caret_line) {
+        D2D1_RECT_F lr = D2D1::RectF(GUTTER_WIDTH, y, (float)ev->width, y + LINE_HEIGHT);
+        ev->rt->FillRectangle(lr, ev->br_active_line);
+    }
+
+    /* Gutter line number */
+    wchar_t num[16];
+    swprintf_s(num, 16, L"%zu", line_idx + 1);
+    D2D1_RECT_F gr = D2D1::RectF(0, y + 2.0f, GUTTER_WIDTH - 6.0f, y + LINE_HEIGHT);
+    ev->rt->DrawText(num, (UINT32)wcslen(num), ev->gutter_format, gr, ev->br_gutter_fg);
+
+    /* Read line text */
+    size_t line_start = buffer_line_start(ev->doc->buffer, line_idx);
+    size_t line_len   = buffer_line_length(ev->doc->buffer, line_idx);
+    if (line_len == 0) return;
+
+    char  utf8[4096];
+    size_t n = buffer_read(ev->doc->buffer, line_start, utf8, line_len < 4095 ? line_len : 4095);
+
+    /* UTF-8 → UTF-16 */
+    wchar_t wide[4096];
+    int wlen = MultiByteToWideChar(CP_UTF8, 0, utf8, (int)n, wide, 4095);
+    if (wlen <= 0) return;
+
+    /* Selection highlight */
+    if (has_sel && sel_start < line_start + line_len && sel_end > line_start) {
+        size_t s = sel_start > line_start ? sel_start - line_start : 0;
+        size_t e = sel_end   < line_start + line_len ? sel_end - line_start : line_len;
+        IDWriteTextLayout *layout = nullptr;
+        ev->dw_factory->CreateTextLayout(wide, (UINT32)wlen,
+            ev->text_format, view_w, LINE_HEIGHT, &layout);
+        if (layout) {
+            DWRITE_HIT_TEST_METRICS m;
+            float xs, dummy;
+            layout->HitTestTextPosition((UINT32)s, FALSE, &xs, &dummy, &m);
+            float xe;
+            layout->HitTestTextPosition((UINT32)(e < (size_t)wlen ? e : wlen), FALSE, &xe, &dummy, &m);
+            D2D1_RECT_F sr = D2D1::RectF(x0 + xs, y, x0 + xe, y + LINE_HEIGHT);
+            ev->rt->FillRectangle(sr, ev->br_sel);
+            layout->Release();
+        }
+    }
+
+    /* Draw text */
+    D2D1_RECT_F tr = D2D1::RectF(x0, y, x0 + view_w, y + LINE_HEIGHT);
+    ev->rt->DrawText(wide, (UINT32)wlen, ev->text_format, tr, ev->br_text);
+
+    /* LSP squiggles */
+    if (ev->has_diags) {
+        for (int di = 0; di < ev->diags.count; di++) {
+            const LspDiagnostic *d = &ev->diags.entries[di];
+            if (d->line != (uint32_t)line_idx) continue;
+
+            ID2D1SolidColorBrush *br = (d->severity == 1) ? ev->br_squiggle_e : ev->br_squiggle_w;
+
+            /* Compute x start from col via layout hit-test */
+            float sq_x = x0;
+            if (d->col > 0) {
+                IDWriteTextLayout *lay = nullptr;
+                ev->dw_factory->CreateTextLayout(wide, (UINT32)wlen,
+                    ev->text_format, view_w, LINE_HEIGHT, &lay);
+                if (lay) {
+                    DWRITE_HIT_TEST_METRICS m;
+                    float dummy;
+                    UINT32 col_clamped = (d->col < (UINT32)wlen) ? d->col : (UINT32)wlen;
+                    lay->HitTestTextPosition(col_clamped, FALSE, &sq_x, &dummy, &m);
+                    sq_x += x0;
+                    lay->Release();
+                }
+            }
+
+            float sq_y = y + LINE_HEIGHT - 3.0f;
+            float sq_end = x0 + view_w;
+            float step = 4.0f;
+            bool up = true;
+            for (float sx = sq_x; sx < sq_end - step; sx += step, up = !up) {
+                float sy0 = up ? sq_y      : sq_y + 2.0f;
+                float sy1 = up ? sq_y + 2.0f : sq_y;
+                ev->rt->DrawLine(D2D1::Point2F(sx, sy0),
+                                 D2D1::Point2F(sx + step, sy1), br, 1.2f);
+            }
+        }
+    }
+}
+
+extern "C" void editor_view_paint(EditorView *ev, RECT client) {
+    if (!ev || !ev->rt) return;
+
+    /* Caret blink */
+    DWORD now = GetTickCount();
+    if (now - ev->caret_tick > 530) {
+        ev->caret_visible = !ev->caret_visible;
+        ev->caret_tick = now;
+    }
+
+    ev->rt->BeginDraw();
+    ev->rt->Clear(&C_BG);
+
+    /* Gutter background */
+    D2D1_RECT_F gutter_rect = D2D1::RectF(0, 0, GUTTER_WIDTH, (float)client.bottom);
+    ev->rt->FillRectangle(gutter_rect, ev->br_gutter_bg);
+
+    if (!ev->doc) {
+        ev->rt->EndDraw(nullptr, nullptr);
+        return;
+    }
+
+    size_t caret_line, caret_col;
+    offset_to_line_col(ev->doc, ev->caret, &caret_line, &caret_col);
+
+    size_t sel_start = ev->has_sel ? (ev->sel_anchor < ev->caret ? ev->sel_anchor : ev->caret) : 0;
+    size_t sel_end   = ev->has_sel ? (ev->sel_anchor > ev->caret ? ev->sel_anchor : ev->caret) : 0;
+
+    size_t total_lines = buffer_line_count(ev->doc->buffer);
+    size_t first_line  = (size_t)ev->scroll_y;
+    size_t visible     = (size_t)((float)ev->height / LINE_HEIGHT) + 2;
+
+    for (size_t i = first_line; i < total_lines && i < first_line + visible; i++) {
+        float y = (float)(i - first_line) * LINE_HEIGHT;
+        draw_line(ev, i, y, caret_line, sel_start, sel_end, ev->has_sel);
+    }
+
+    /* Draw caret */
+    if (ev->caret_visible) {
+        size_t line_start = buffer_line_start(ev->doc->buffer, caret_line);
+        size_t char_in_line = ev->caret - line_start;
+
+        float caret_x = GUTTER_WIDTH + PADDING_LEFT;
+        if (char_in_line > 0) {
+            char utf8[1024];
+            size_t n = buffer_read(ev->doc->buffer, line_start, utf8, char_in_line < 1023 ? char_in_line : 1023);
+            wchar_t wide[1024];
+            int wlen = MultiByteToWideChar(CP_UTF8, 0, utf8, (int)n, wide, 1023);
+            if (wlen > 0) {
+                IDWriteTextLayout *layout = nullptr;
+                ev->dw_factory->CreateTextLayout(wide, (UINT32)wlen,
+                    ev->text_format, 9999.0f, LINE_HEIGHT, &layout);
+                if (layout) {
+                    DWRITE_TEXT_METRICS tm;
+                    layout->GetMetrics(&tm);
+                    caret_x += tm.width;
+                    layout->Release();
+                }
+            }
+        }
+        float caret_y = (float)(caret_line - first_line) * LINE_HEIGHT;
+        D2D1_RECT_F cr = D2D1::RectF(caret_x, caret_y + 2.0f, caret_x + CARET_WIDTH, caret_y + LINE_HEIGHT - 2.0f);
+        ev->rt->FillRectangle(cr, ev->br_caret);
+    }
+
+    HRESULT hr = ev->rt->EndDraw(nullptr, nullptr);
+    if (hr == (HRESULT)D2DERR_RECREATE_TARGET) {
+        /* Device lost — recreate */
+        release_brushes(ev);
+        ev->rt->Release(); ev->rt = nullptr;
+        RECT rc; GetClientRect(ev->hwnd, &rc);
+        D2D1_RENDER_TARGET_PROPERTIES rtp = D2D1::RenderTargetProperties();
+        D2D1_HWND_RENDER_TARGET_PROPERTIES hwp = D2D1::HwndRenderTargetProperties(
+            ev->hwnd, D2D1::SizeU(rc.right - rc.left, rc.bottom - rc.top));
+        ev->d2d_factory->CreateHwndRenderTarget(rtp, hwp, &ev->rt);
+        create_brushes(ev);
+    }
+}
+
+/* Clamp caret into buffer */
+static void clamp_caret(EditorView *ev) {
+    if (!ev->doc) return;
+    size_t len = buffer_length(ev->doc->buffer);
+    if (ev->caret > len) ev->caret = len;
+}
+
+/* Move caret left/right by one byte (UTF-8 aware would need more work) */
+static void caret_move_left(EditorView *ev) {
+    if (ev->caret > 0) ev->caret--;
+}
+
+static void caret_move_right(EditorView *ev) {
+    if (!ev->doc) return;
+    if (ev->caret < buffer_length(ev->doc->buffer)) ev->caret++;
+}
+
+static void caret_move_up(EditorView *ev) {
+    if (!ev->doc) return;
+    size_t line, col;
+    offset_to_line_col(ev->doc, ev->caret, &line, &col);
+    if (line == 0) { ev->caret = 0; return; }
+    size_t prev_start = buffer_line_start(ev->doc->buffer, line - 1);
+    size_t prev_len   = buffer_line_length(ev->doc->buffer, line - 1);
+    ev->caret = prev_start + (col < prev_len ? col : prev_len);
+}
+
+static void caret_move_down(EditorView *ev) {
+    if (!ev->doc) return;
+    size_t line, col;
+    offset_to_line_col(ev->doc, ev->caret, &line, &col);
+    size_t total = buffer_line_count(ev->doc->buffer);
+    if (line + 1 >= total) return;
+    size_t next_start = buffer_line_start(ev->doc->buffer, line + 1);
+    size_t next_len   = buffer_line_length(ev->doc->buffer, line + 1);
+    ev->caret = next_start + (col < next_len ? col : next_len);
+}
+
+static void caret_home(EditorView *ev) {
+    if (!ev->doc) return;
+    size_t line, col; (void)col;
+    offset_to_line_col(ev->doc, ev->caret, &line, &col);
+    ev->caret = buffer_line_start(ev->doc->buffer, line);
+}
+
+static void caret_end(EditorView *ev) {
+    if (!ev->doc) return;
+    size_t line, col; (void)col;
+    offset_to_line_col(ev->doc, ev->caret, &line, &col);
+    ev->caret = buffer_line_start(ev->doc->buffer, line)
+              + buffer_line_length(ev->doc->buffer, line);
+}
+
+static void ensure_caret_visible(EditorView *ev) {
+    if (!ev->doc) return;
+    size_t line, col; (void)col;
+    offset_to_line_col(ev->doc, ev->caret, &line, &col);
+    float visible_lines = (float)ev->height / LINE_HEIGHT;
+    if ((float)line < ev->scroll_y) {
+        ev->scroll_y = (float)line;
+    } else if ((float)line >= ev->scroll_y + visible_lines - 1) {
+        ev->scroll_y = (float)line - visible_lines + 2.0f;
+        if (ev->scroll_y < 0) ev->scroll_y = 0;
+    }
+}
+
+extern "C" void editor_view_key_down(EditorView *ev, UINT vk, UINT mods) {
+    if (!ev->doc) return;
+
+    bool shift = (mods & 1) != 0;
+    bool ctrl  = (mods & 2) != 0;
+
+    if (shift && !ev->has_sel) {
+        ev->sel_anchor = ev->caret;
+        ev->has_sel = true;
+    }
+
+    switch (vk) {
+    case VK_LEFT:
+        if (!shift && ev->has_sel) { ev->caret = ev->sel_anchor < ev->caret ? ev->sel_anchor : ev->caret; ev->has_sel = false; }
+        else caret_move_left(ev);
+        break;
+    case VK_RIGHT:
+        if (!shift && ev->has_sel) { ev->caret = ev->sel_anchor > ev->caret ? ev->sel_anchor : ev->caret; ev->has_sel = false; }
+        else caret_move_right(ev);
+        break;
+    case VK_UP:    caret_move_up(ev);   break;
+    case VK_DOWN:  caret_move_down(ev); break;
+    case VK_HOME:  caret_home(ev); break;
+    case VK_END:   caret_end(ev);  break;
+    case VK_PRIOR: /* Page Up */
+        for (int i = 0; i < 20; i++) caret_move_up(ev);
+        break;
+    case VK_NEXT:  /* Page Down */
+        for (int i = 0; i < 20; i++) caret_move_down(ev);
+        break;
+    case VK_DELETE: {
+        if (ev->has_sel) {
+            size_t s = ev->sel_anchor < ev->caret ? ev->sel_anchor : ev->caret;
+            size_t e = ev->sel_anchor > ev->caret ? ev->sel_anchor : ev->caret;
+            buffer_delete(ev->doc->buffer, s, e - s);
+            ev->caret = s; ev->has_sel = false;
+        } else {
+            buffer_delete(ev->doc->buffer, ev->caret, 1);
+        }
+        break;
+    }
+    case VK_BACK: {
+        if (ev->has_sel) {
+            size_t s = ev->sel_anchor < ev->caret ? ev->sel_anchor : ev->caret;
+            size_t e = ev->sel_anchor > ev->caret ? ev->sel_anchor : ev->caret;
+            buffer_delete(ev->doc->buffer, s, e - s);
+            ev->caret = s; ev->has_sel = false;
+        } else if (ev->caret > 0) {
+            ev->caret--;
+            buffer_delete(ev->doc->buffer, ev->caret, 1);
+        }
+        break;
+    }
+    case 'Z':
+        if (ctrl) {
+            if (buffer_can_undo(ev->doc->buffer)) {
+                buffer_undo(ev->doc->buffer);
+                clamp_caret(ev);
+            }
+        }
+        break;
+    case 'Y':
+        if (ctrl) {
+            if (buffer_can_redo(ev->doc->buffer)) {
+                buffer_redo(ev->doc->buffer);
+                clamp_caret(ev);
+            }
+        }
+        break;
+    case 'A':
+        if (ctrl) {
+            ev->sel_anchor = 0;
+            ev->caret = buffer_length(ev->doc->buffer);
+            ev->has_sel = true;
+        }
+        break;
+    case 'S':
+        if (ctrl) document_save(ev->doc);
+        break;
+    }
+
+    if (!shift) ev->has_sel = false;
+    clamp_caret(ev);
+    ensure_caret_visible(ev);
+    ev->caret_visible = true;
+    ev->caret_tick = GetTickCount();
+
+    InvalidateRect(ev->hwnd, NULL, FALSE);
+}
+
+extern "C" void editor_view_char(EditorView *ev, wchar_t ch) {
+    if (!ev->doc) return;
+    if (ch < 0x20 && ch != '\t' && ch != '\n' && ch != '\r') return;
+    if (ch == '\r') ch = '\n';
+
+    if (ev->has_sel) {
+        size_t s = ev->sel_anchor < ev->caret ? ev->sel_anchor : ev->caret;
+        size_t e = ev->sel_anchor > ev->caret ? ev->sel_anchor : ev->caret;
+        buffer_delete(ev->doc->buffer, s, e - s);
+        ev->caret = s; ev->has_sel = false;
+    }
+
+    /* UTF-16 → UTF-8 */
+    char utf8[4];
+    int utf8_len = WideCharToMultiByte(CP_UTF8, 0, &ch, 1, utf8, 4, NULL, NULL);
+    if (utf8_len > 0) {
+        buffer_insert(ev->doc->buffer, ev->caret, utf8, (size_t)utf8_len);
+        ev->caret += (size_t)utf8_len;
+    }
+
+    ensure_caret_visible(ev);
+    ev->caret_visible = true;
+    ev->caret_tick = GetTickCount();
+    InvalidateRect(ev->hwnd, NULL, FALSE);
+}
+
+/* Hit test: pixel (x, y) → buffer offset */
+static size_t hit_test(EditorView *ev, int px, int py) {
+    if (!ev->doc) return 0;
+
+    size_t line = (size_t)(ev->scroll_y + (float)py / LINE_HEIGHT);
+    size_t total = buffer_line_count(ev->doc->buffer);
+    if (line >= total) line = total - 1;
+
+    size_t line_start = buffer_line_start(ev->doc->buffer, line);
+    size_t line_len   = buffer_line_length(ev->doc->buffer, line);
+    if (line_len == 0) return line_start;
+
+    float text_x = (float)px - (GUTTER_WIDTH + PADDING_LEFT);
+    if (text_x <= 0) return line_start;
+
+    char utf8[4096];
+    size_t n = buffer_read(ev->doc->buffer, line_start, utf8, line_len < 4095 ? line_len : 4095);
+    wchar_t wide[4096];
+    int wlen = MultiByteToWideChar(CP_UTF8, 0, utf8, (int)n, wide, 4095);
+    if (wlen <= 0) return line_start;
+
+    IDWriteTextLayout *layout = nullptr;
+    ev->dw_factory->CreateTextLayout(wide, (UINT32)wlen,
+        ev->text_format, 9999.0f, LINE_HEIGHT, &layout);
+    if (!layout) return line_start;
+
+    BOOL trailing, inside;
+    DWRITE_HIT_TEST_METRICS m;
+    layout->HitTestPoint(text_x, LINE_HEIGHT / 2.0f, &trailing, &inside, &m);
+    layout->Release();
+
+    size_t char_pos = m.textPosition + (trailing ? 1 : 0);
+    return line_start + (char_pos < line_len ? char_pos : line_len);
+}
+
+extern "C" void editor_view_mouse_down(EditorView *ev, int x, int y) {
+    ev->caret    = hit_test(ev, x, y);
+    ev->sel_anchor = ev->caret;
+    ev->has_sel  = false;
+    ev->caret_visible = true;
+    ev->caret_tick = GetTickCount();
+    InvalidateRect(ev->hwnd, NULL, FALSE);
+}
+
+extern "C" void editor_view_mouse_move(EditorView *ev, int x, int y, bool btn) {
+    if (!btn) return;
+    size_t new_pos = hit_test(ev, x, y);
+    if (new_pos != ev->caret) {
+        ev->caret = new_pos;
+        ev->has_sel = (ev->caret != ev->sel_anchor);
+        InvalidateRect(ev->hwnd, NULL, FALSE);
+    }
+}
+
+extern "C" size_t editor_view_caret_offset(const EditorView *ev) {
+    return ev->caret;
+}

ide/native/editor/editor_view.h

@@ -0,0 +1,27 @@
+#ifndef SOVEREIGN_EDITOR_VIEW_H
+#define SOVEREIGN_EDITOR_VIEW_H
+
+#include "document.h"
+#include "../core/errors.h"
+#include "../lsp/client.h"
+#include <windows.h>
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef struct EditorView EditorView;
+
+SovResult editor_view_create(EditorView **out, HWND hwnd);
+void      editor_view_destroy(EditorView *ev);
+void      editor_view_set_document(EditorView *ev, Document *doc);
+void      editor_view_set_diagnostics(EditorView *ev, const LspDiagList *list);
+void      editor_view_paint(EditorView *ev, RECT client);
+void      editor_view_resize(EditorView *ev, uint32_t w, uint32_t h);
+
+void      editor_view_key_down(EditorView *ev, UINT vk, UINT mods);
+void      editor_view_char(EditorView *ev, wchar_t ch);
+void      editor_view_mouse_down(EditorView *ev, int x, int y);
+void      editor_view_mouse_move(EditorView *ev, int x, int y, bool btn);
+
+size_t    editor_view_caret_offset(const EditorView *ev);
+
+#endif

ide/native/fcl/evaluator.c

@@ -0,0 +1,54 @@
+/*
+ * Sovereign IDE — FCL Evaluator
+ * Default-deny. Rules evaluated in order; first match wins.
+ */
+
+#include "evaluator.h"
+#include <string.h>
+
+static bool path_matches(Str pattern, Str target) {
+    if (pattern.len == 1 && pattern.ptr[0] == '*') return true;
+    if (pattern.len == target.len && memcmp(pattern.ptr, target.ptr, pattern.len) == 0) return true;
+
+    if (pattern.len >= 2 && pattern.ptr[pattern.len - 1] == '*') {
+        /* prefix glob: "src/ STAR" matches "src/foo.c" */
+        size_t prefix_len = pattern.len - 1;
+        if (target.len >= prefix_len && memcmp(pattern.ptr, target.ptr, prefix_len) == 0) {
+            return true;
+        }
+    }
+
+    if (pattern.len >= 2 && pattern.ptr[0] == '*') {
+        /* suffix glob: "*.exe" matches "virus.exe" */
+        size_t suffix_len = pattern.len - 1;
+        const char *suffix = pattern.ptr + 1;
+        if (target.len >= suffix_len &&
+            memcmp(target.ptr + target.len - suffix_len, suffix, suffix_len) == 0) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+FclVerdict fcl_evaluate(const FclRuleSet *rules, const FclRequest *req) {
+    for (size_t i = 0; i < rules->count; i++) {
+        const FclRule *r = &rules->rules[i];
+
+        if (r->action != req->action) continue;
+        if (!path_matches(r->subject, req->target)) continue;
+        if (r->agent.ptr && !str_eq(r->agent, req->agent)) continue;
+
+        switch (r->kind) {
+        case FCL_PERMIT:
+            if (r->requires_approval) return FCL_AWAIT_APPROVAL;
+            return FCL_ALLOW;
+        case FCL_DENY:
+            return FCL_DENY_RULE;
+        default:
+            continue;
+        }
+    }
+
+    return FCL_DENY_NO_RULE; /* default deny */
+}

ide/native/fcl/evaluator.h

@@ -0,0 +1,22 @@
+#ifndef SOVEREIGN_FCL_EVALUATOR_H
+#define SOVEREIGN_FCL_EVALUATOR_H
+
+#include "parser.h"
+#include <stdbool.h>
+
+typedef enum FclVerdict {
+    FCL_ALLOW,
+    FCL_DENY_RULE,
+    FCL_DENY_NO_RULE,
+    FCL_AWAIT_APPROVAL,
+} FclVerdict;
+
+typedef struct FclRequest {
+    FclAction action;
+    Str       target;
+    Str       agent;
+} FclRequest;
+
+FclVerdict fcl_evaluate(const FclRuleSet *rules, const FclRequest *req);
+
+#endif /* SOVEREIGN_FCL_EVALUATOR_H */

ide/native/fcl/parser.h

@@ -0,0 +1,44 @@
+#ifndef SOVEREIGN_FCL_PARSER_H
+#define SOVEREIGN_FCL_PARSER_H
+
+#include "../core/errors.h"
+#include "../core/strings.h"
+#include <stdbool.h>
+
+typedef enum FclNodeKind {
+    FCL_PERMIT,
+    FCL_DENY,
+    FCL_REQUIRE,
+    FCL_CONSTRAIN,
+    FCL_BOUNDARY,
+} FclNodeKind;
+
+typedef enum FclAction {
+    FCL_ACT_READ,
+    FCL_ACT_WRITE,
+    FCL_ACT_EXECUTE,
+    FCL_ACT_GIT_READ,
+    FCL_ACT_GIT_MUTATE,
+    FCL_ACT_BUILD,
+    FCL_ACT_DEPLOY,
+    FCL_ACT_MODEL,
+} FclAction;
+
+typedef struct FclRule {
+    FclNodeKind  kind;
+    FclAction    action;
+    Str          subject;    /* file path or tool name */
+    Str          agent;      /* which agent requested */
+    bool         requires_approval;
+} FclRule;
+
+typedef struct FclRuleSet {
+    FclRule *rules;
+    size_t   count;
+    size_t   capacity;
+} FclRuleSet;
+
+SovResult fcl_parse(const char *source, size_t len, FclRuleSet *out);
+void      fcl_ruleset_free(FclRuleSet *rs);
+
+#endif /* SOVEREIGN_FCL_PARSER_H */

ide/native/git/repository.c

@@ -0,0 +1,101 @@
+/*
+ * Sovereign IDE — Git repository helpers
+ * Reads .git/HEAD and .git/index mtime for branch + dirty detection.
+ * No libgit2 — pure Win32 file I/O.
+ */
+
+#include "repository.h"
+#include <stdlib.h>
+#include <string.h>
+#include <stdio.h>
+
+/* Walk up from path looking for a .git directory/file */
+static bool find_git_root(const wchar_t *start, wchar_t *root_out, size_t root_cap) {
+    wchar_t cur[MAX_PATH];
+    wcscpy_s(cur, MAX_PATH, start);
+
+    for (int depth = 0; depth < 32; depth++) {
+        wchar_t candidate[MAX_PATH];
+        swprintf_s(candidate, MAX_PATH, L"%s\\.git", cur);
+
+        DWORD attr = GetFileAttributesW(candidate);
+        if (attr != INVALID_FILE_ATTRIBUTES) {
+            wcscpy_s(root_out, root_cap, cur);
+            return true;
+        }
+
+        /* Go up one level */
+        wchar_t *last = wcsrchr(cur, L'\\');
+        if (!last || last == cur) break;
+        *last = L'\0';
+    }
+    return false;
+}
+
+SovResult git_repo_open(GitRepo *repo, const wchar_t *path) {
+    memset(repo, 0, sizeof(*repo));
+
+    if (!find_git_root(path, repo->root, MAX_PATH))
+        return SOV_ERR_IO;
+
+    swprintf_s(repo->git_dir, MAX_PATH, L"%s\\.git", repo->root);
+    repo->valid = true;
+    return git_repo_refresh(repo);
+}
+
+SovResult git_repo_refresh(GitRepo *repo) {
+    if (!repo->valid) return SOV_ERR_IO;
+
+    /* Read HEAD → branch name */
+    wchar_t head_path[MAX_PATH];
+    swprintf_s(head_path, MAX_PATH, L"%s\\HEAD", repo->git_dir);
+
+    HANDLE hf = CreateFileW(head_path, GENERIC_READ, FILE_SHARE_READ,
+                            NULL, OPEN_EXISTING, 0, NULL);
+    if (hf == INVALID_HANDLE_VALUE) return SOV_ERR_IO;
+
+    char buf[256] = {0};
+    DWORD nread = 0;
+    ReadFile(hf, buf, sizeof(buf) - 1, &nread, NULL);
+    CloseHandle(hf);
+
+    /* "ref: refs/heads/main\n"  or  detached SHA */
+    static const char prefix[] = "ref: refs/heads/";
+    if (strncmp(buf, prefix, sizeof(prefix) - 1) == 0) {
+        const char *branch = buf + sizeof(prefix) - 1;
+        size_t len = strcspn(branch, "\r\n");
+        if (len >= 128) len = 127;
+        MultiByteToWideChar(CP_UTF8, 0, branch, (int)len,
+                            repo->branch, 128);
+        repo->branch[len] = L'\0';
+        repo->detached = false;
+    } else {
+        /* Detached HEAD — show short SHA */
+        size_t len = strcspn(buf, "\r\n");
+        if (len > 8) len = 8;
+        MultiByteToWideChar(CP_UTF8, 0, buf, (int)len,
+                            repo->branch, 128);
+        repo->branch[len] = L'\0';
+        repo->detached = true;
+    }
+
+    /* Dirty detection: compare index mtime to HEAD mtime.
+     * If index is newer → working tree likely has staged changes.
+     * Good enough for status bar; not a full diff. */
+    wchar_t index_path[MAX_PATH];
+    swprintf_s(index_path, MAX_PATH, L"%s\\index", repo->git_dir);
+
+    WIN32_FILE_ATTRIBUTE_DATA fa_index = {0}, fa_head = {0};
+    bool has_index = GetFileAttributesExW(index_path, GetFileExInfoStandard, &fa_index);
+    bool has_head  = GetFileAttributesExW(head_path,  GetFileExInfoStandard, &fa_head);
+
+    if (has_index && has_head) {
+        LONG cmp = CompareFileTime(&fa_index.ftLastWriteTime,
+                                   &fa_head.ftLastWriteTime);
+        repo->dirty = (cmp > 0);
+    } else {
+        repo->dirty = false;
+    }
+
+    return SOV_OK;
+}

ide/native/git/repository.h

@@ -0,0 +1,20 @@
+#ifndef SOVEREIGN_GIT_REPOSITORY_H
+#define SOVEREIGN_GIT_REPOSITORY_H
+
+#include <windows.h>
+#include <stdbool.h>
+#include "../core/errors.h"
+
+typedef struct GitRepo {
+    wchar_t root[MAX_PATH];
+    wchar_t git_dir[MAX_PATH];
+    wchar_t branch[128];
+    bool    detached;
+    bool    dirty;
+    bool    valid;
+} GitRepo;
+
+SovResult git_repo_open(GitRepo *repo, const wchar_t *path);
+SovResult git_repo_refresh(GitRepo *repo);
+
+#endif

ide/native/graphics/d2d_renderer.cpp

@@ -0,0 +1,90 @@
+/*
+ * Sovereign IDE — Direct2D Renderer (C++ for COM vtable calls)
+ */
+
+#include <windows.h>
+#include <d2d1_1.h>
+#include <dwrite.h>
+#include <stdint.h>
+
+extern "C" {
+#include "d2d_renderer.h"
+}
+
+static struct {
+    ID2D1Factory           *factory;
+    ID2D1HwndRenderTarget  *target;
+    IDWriteFactory         *dwrite_factory;
+    bool                    initialized;
+} g_renderer;
+
+extern "C" SovResult renderer_init(HWND hwnd) {
+    HRESULT hr = D2D1CreateFactory(
+        D2D1_FACTORY_TYPE_SINGLE_THREADED,
+        &g_renderer.factory
+    );
+    if (FAILED(hr)) return SOV_ERR_ALLOC;
+
+    RECT rc;
+    GetClientRect(hwnd, &rc);
+
+    D2D1_SIZE_U size = D2D1::SizeU(
+        (UINT32)(rc.right - rc.left),
+        (UINT32)(rc.bottom - rc.top)
+    );
+
+    D2D1_RENDER_TARGET_PROPERTIES rtprops = D2D1::RenderTargetProperties();
+    D2D1_HWND_RENDER_TARGET_PROPERTIES hwndprops =
+        D2D1::HwndRenderTargetProperties(hwnd, size);
+
+    hr = g_renderer.factory->CreateHwndRenderTarget(
+        rtprops, hwndprops, &g_renderer.target
+    );
+    if (FAILED(hr)) return SOV_ERR_ALLOC;
+
+    hr = DWriteCreateFactory(
+        DWRITE_FACTORY_TYPE_SHARED,
+        __uuidof(IDWriteFactory),
+        reinterpret_cast<IUnknown **>(&g_renderer.dwrite_factory)
+    );
+    if (FAILED(hr)) return SOV_ERR_ALLOC;
+
+    g_renderer.initialized = true;
+    return SOV_OK;
+}
+
+extern "C" void renderer_begin_frame(void) {
+    if (!g_renderer.initialized) return;
+    g_renderer.target->BeginDraw();
+    D2D1_COLOR_F bg = { 0.12f, 0.12f, 0.14f, 1.0f };
+    g_renderer.target->Clear(&bg);
+}
+
+extern "C" void renderer_end_frame(void) {
+    if (!g_renderer.initialized) return;
+    HRESULT hr = g_renderer.target->EndDraw();
+    if (hr == (HRESULT)D2DERR_RECREATE_TARGET) {
+        g_renderer.initialized = false;
+    }
+}
+
+extern "C" void renderer_resize(uint32_t width, uint32_t height) {
+    if (!g_renderer.initialized) return;
+    D2D1_SIZE_U s = D2D1::SizeU(width, height);
+    g_renderer.target->Resize(s);
+}
+
+extern "C" void renderer_shutdown(void) {
+    if (g_renderer.target) { g_renderer.target->Release(); g_renderer.target = NULL; }
+    if (g_renderer.factory) { g_renderer.factory->Release(); g_renderer.factory = NULL; }
+    if (g_renderer.dwrite_factory) { g_renderer.dwrite_factory->Release(); g_renderer.dwrite_factory = NULL; }
+    g_renderer.initialized = false;
+}
+
+extern "C" void *renderer_get_target(void) {
+    return g_renderer.target;
+}
+
+extern "C" void *renderer_get_dwrite(void) {
+    return g_renderer.dwrite_factory;
+}

ide/native/graphics/d2d_renderer.h

@@ -0,0 +1,17 @@
+#ifndef SOVEREIGN_D2D_RENDERER_H
+#define SOVEREIGN_D2D_RENDERER_H
+
+#include <windows.h>
+#include <stdint.h>
+#include "../core/errors.h"
+
+SovResult renderer_init(HWND hwnd);
+void      renderer_begin_frame(void);
+void      renderer_end_frame(void);
+void      renderer_resize(uint32_t width, uint32_t height);
+void      renderer_shutdown(void);
+
+void *renderer_get_target(void);
+void *renderer_get_dwrite(void);
+
+#endif /* SOVEREIGN_D2D_RENDERER_H */

ide/native/lsp/client.c

@@ -0,0 +1,422 @@
+/*
+ * Sovereign IDE — LSP Client
+ * JSON-RPC 2.0 over stdio pipes to clangd (or any LSP server).
+ * Handles: initialize, initialized, textDocument/didOpen, didChange,
+ * shutdown, and inbound publishDiagnostics notifications.
+ *
+ * JSON is hand-built (no external lib). Parsing is minimal: we walk
+ * the response bytes looking for the fields we need.
+ */
+
+#include "client.h"
+#include <stdlib.h>
+#include <string.h>
+#include <stdio.h>
+
+/* ── JSON helpers ────────────────────────────────────────────── */
+
+/* Escape a UTF-8 string into a JSON string (caller provides buf). */
+static int json_escape(const char *src, char *dst, int cap) {
+    int n = 0;
+    for (; *src && n < cap - 2; src++) {
+        unsigned char c = (unsigned char)*src;
+        if      (c == '"')  { dst[n++]='\\'; dst[n++]='"'; }
+        else if (c == '\\') { dst[n++]='\\'; dst[n++]='\\'; }
+        else if (c == '\n') { dst[n++]='\\'; dst[n++]='n'; }
+        else if (c == '\r') { dst[n++]='\\'; dst[n++]='r'; }
+        else if (c == '\t') { dst[n++]='\\'; dst[n++]='t'; }
+        else                { dst[n++]=(char)c; }
+    }
+    dst[n] = '\0';
+    return n;
+}
+
+/* Wide path → file:/// URI in UTF-8 */
+static void path_to_uri(const wchar_t *path, char *uri, int cap) {
+    char narrow[MAX_PATH * 2];
+    WideCharToMultiByte(CP_UTF8, 0, path, -1, narrow, sizeof(narrow), NULL, NULL);
+    /* Replace backslashes */
+    for (char *p = narrow; *p; p++) if (*p == '\\') *p = '/';
+    snprintf(uri, (size_t)cap, "file:///%s", narrow);
+}
+
+/* ── Minimal JSON parser helpers ─────────────────────────────── */
+
+static const char *json_find_key(const char *json, const char *key) {
+    char needle[128];
+    snprintf(needle, sizeof(needle), "\"%s\"", key);
+    return strstr(json, needle);
+}
+
+static int json_int_after_key(const char *json, const char *key, int def) {
+    const char *p = json_find_key(json, key);
+    if (!p) return def;
+    p += strlen(key) + 2;
+    while (*p == ' ' || *p == ':' || *p == '"') p++;
+    if (*p == '\0') return def;
+    return atoi(p);
+}
+
+static bool json_str_after_key(const char *json, const char *key,
+                                char *out, int cap) {
+    const char *p = json_find_key(json, key);
+    if (!p) return false;
+    p += strlen(key) + 2;
+    while (*p == ' ' || *p == ':') p++;
+    if (*p != '"') return false;
+    p++;
+    int n = 0;
+    while (*p && *p != '"' && n < cap - 1) {
+        if (*p == '\\' && *(p+1)) { p++; }
+        out[n++] = *p++;
+    }
+    out[n] = '\0';
+    return true;
+}
+
+/* ── RPC framing ─────────────────────────────────────────────── */
+
+struct LspClient {
+    HANDLE  pipe_stdin;   /* write to child stdin  */
+    HANDLE  pipe_stdout;  /* read from child stdout */
+    PROCESS_INFORMATION pi;
+    bool    alive;
+
+    int          next_id;
+    lsp_diag_cb  on_diag;
+    void        *cb_ctx;
+
+    /* Read buffer for partial Content-Length frames */
+    char   rbuf[1 << 20];   /* 1 MB */
+    int    rbuf_len;
+};
+
+static SovResult lsp_send(LspClient *c, const char *body, int body_len) {
+    char header[64];
+    int hlen = snprintf(header, sizeof(header),
+                        "Content-Length: %d\r\n\r\n", body_len);
+    DWORD written;
+    if (!WriteFile(c->pipe_stdin, header, (DWORD)hlen, &written, NULL))
+        return SOV_ERR_IO;
+    if (!WriteFile(c->pipe_stdin, body, (DWORD)body_len, &written, NULL))
+        return SOV_ERR_IO;
+    return SOV_OK;
+}
+
+/* Build a JSON-RPC request and send it */
+static SovResult lsp_request(LspClient *c, const char *method,
+                              const char *params_json) {
+    char body[1 << 18];
+    int n = snprintf(body, sizeof(body),
+        "{\"jsonrpc\":\"2.0\",\"id\":%d,\"method\":\"%s\",\"params\":%s}",
+        c->next_id++, method, params_json ? params_json : "null");
+    return lsp_send(c, body, n);
+}
+
+/* Build a JSON-RPC notification (no id) and send it */
+static SovResult lsp_notify(LspClient *c, const char *method,
+                             const char *params_json) {
+    char body[1 << 18];
+    int n = snprintf(body, sizeof(body),
+        "{\"jsonrpc\":\"2.0\",\"method\":\"%s\",\"params\":%s}",
+        method, params_json ? params_json : "{}");
+    return lsp_send(c, body, n);
+}
+
+/* ── Diagnostics parser ──────────────────────────────────────── */
+
+static void parse_diagnostics(LspClient *c, const char *json) {
+    LspDiagList list;
+    memset(&list, 0, sizeof(list));
+
+    /* Extract URI */
+    char uri[MAX_PATH * 2] = {0};
+    json_str_after_key(json, "uri", uri, sizeof(uri));
+    /* Strip file:/// prefix */
+    const char *path = uri;
+    if (strncmp(path, "file:///", 8) == 0) path += 8;
+    MultiByteToWideChar(CP_UTF8, 0, path, -1, list.uri, MAX_PATH);
+    /* Restore backslashes on Windows */
+    for (wchar_t *p = list.uri; *p; p++) if (*p == L'/') *p = L'\\';
+
+    /* Walk diagnostics array */
+    const char *p = strstr(json, "\"diagnostics\"");
+    if (!p) goto done;
+    p = strchr(p, '[');
+    if (!p) goto done;
+    p++;
+
+    while (*p && list.count < LSP_MAX_DIAG) {
+        /* Find next object */
+        const char *obj = strchr(p, '{');
+        if (!obj) break;
+        /* Find matching } — naive single-level scan */
+        const char *end = obj + 1;
+        int depth = 1;
+        while (*end && depth > 0) {
+            if (*end == '{') depth++;
+            else if (*end == '}') depth--;
+            end++;
+        }
+        if (depth != 0) break;
+
+        /* Extract a diagnostic object [obj, end) */
+        char obj_buf[2048];
+        int obj_len = (int)(end - obj);
+        if (obj_len > (int)sizeof(obj_buf) - 1) obj_len = (int)sizeof(obj_buf) - 1;
+        memcpy(obj_buf, obj, (size_t)obj_len);
+        obj_buf[obj_len] = '\0';
+
+        LspDiagnostic *d = &list.entries[list.count];
+
+        /* line/character from "start" */
+        const char *rng = strstr(obj_buf, "\"range\"");
+        if (rng) {
+            const char *start = strstr(rng, "\"start\"");
+            if (start) {
+                d->line = (uint32_t)json_int_after_key(start, "line", 0);
+                d->col  = (uint32_t)json_int_after_key(start, "character", 0);
+            }
+        }
+        d->severity = (uint32_t)json_int_after_key(obj_buf, "severity", 1);
+        json_str_after_key(obj_buf, "message", d->message, 512);
+        wcscpy_s(d->file, MAX_PATH, list.uri);
+
+        list.count++;
+        p = end;
+    }
+
+done:
+    if (c->on_diag) c->on_diag(&list, c->cb_ctx);
+}
+
+/* ── Dispatch one complete JSON message ──────────────────────── */
+
+static void dispatch_message(LspClient *c, const char *json) {
+    /* Only care about notifications right now */
+    const char *method_pos = strstr(json, "\"method\"");
+    if (!method_pos) return;
+
+    char method[128] = {0};
+    json_str_after_key(json, "method", method, sizeof(method));
+
+    if (strcmp(method, "textDocument/publishDiagnostics") == 0) {
+        parse_diagnostics(c, json);
+    }
+    /* Other notifications (window/logMessage, $/progress, etc.) ignored */
+}
+
+/* ── Public API ──────────────────────────────────────────────── */
+
+SovResult lsp_client_start(LspClient **out, const wchar_t *server_cmd,
+                            lsp_diag_cb on_diag, void *cb_ctx) {
+    LspClient *c = (LspClient *)calloc(1, sizeof(LspClient));
+    if (!c) return SOV_ERR_ALLOC;
+    c->on_diag  = on_diag;
+    c->cb_ctx   = cb_ctx;
+    c->next_id  = 1;
+    c->alive    = false;
+
+    SECURITY_ATTRIBUTES sa = { sizeof(sa), NULL, TRUE };
+
+    HANDLE child_stdin_rd, child_stdin_wr;
+    HANDLE child_stdout_rd, child_stdout_wr;
+
+    if (!CreatePipe(&child_stdin_rd,  &child_stdin_wr,  &sa, 0)) goto fail;
+    if (!CreatePipe(&child_stdout_rd, &child_stdout_wr, &sa, 0)) {
+        CloseHandle(child_stdin_rd); CloseHandle(child_stdin_wr); goto fail;
+    }
+    SetHandleInformation(child_stdin_wr,  HANDLE_FLAG_INHERIT, 0);
+    SetHandleInformation(child_stdout_rd, HANDLE_FLAG_INHERIT, 0);
+
+    c->pipe_stdin  = child_stdin_wr;
+    c->pipe_stdout = child_stdout_rd;
+
+    STARTUPINFOW si = {0};
+    si.cb         = sizeof(si);
+    si.dwFlags    = STARTF_USESTDHANDLES;
+    si.hStdInput  = child_stdin_rd;
+    si.hStdOutput = child_stdout_wr;
+    si.hStdError  = GetStdHandle(STD_ERROR_HANDLE);
+
+    wchar_t cmd[MAX_PATH + 64];
+    wcscpy_s(cmd, MAX_PATH + 64, server_cmd);
+
+    BOOL ok = CreateProcessW(NULL, cmd, NULL, NULL, TRUE,
+                             CREATE_NO_WINDOW, NULL, NULL, &si, &c->pi);
+
+    CloseHandle(child_stdin_rd);
+    CloseHandle(child_stdout_wr);
+
+    if (!ok) goto fail;
+
+    c->alive = true;
+    *out = c;
+    return SOV_OK;
+
+fail:
+    free(c);
+    return SOV_ERR_IO;
+}
+
+SovResult lsp_client_initialize(LspClient *c, const wchar_t *root_path) {
+    if (!c->alive) return SOV_ERR_IO;
+
+    char root_uri[MAX_PATH * 3];
+    path_to_uri(root_path, root_uri, sizeof(root_uri));
+
+    char params[MAX_PATH * 3 + 256];
+    snprintf(params, sizeof(params),
+        "{\"processId\":%lu,"
+        "\"rootUri\":\"%s\","
+        "\"capabilities\":{"
+            "\"textDocument\":{"
+                "\"publishDiagnostics\":{\"relatedInformation\":false}"
+            "}"
+        "}}",
+        (unsigned long)GetCurrentProcessId(), root_uri);
+
+    SovResult r = lsp_request(c, "initialize", params);
+    if (r != SOV_OK) return r;
+
+    /* Send initialized after a tick (clangd expects response first,
+     * but we're async — send immediately, clangd handles it fine) */
+    return lsp_notify(c, "initialized", "{}");
+}
+
+SovResult lsp_client_open(LspClient *c, const wchar_t *path,
+                           const char *text, size_t len) {
+    if (!c->alive) return SOV_ERR_IO;
+
+    char uri[MAX_PATH * 3];
+    path_to_uri(path, uri, sizeof(uri));
+
+    /* Detect language from extension */
+    const char *lang = "c";
+    const wchar_t *ext = wcsrchr(path, L'.');
+    if (ext) {
+        if (_wcsicmp(ext, L".cpp") == 0 || _wcsicmp(ext, L".hpp") == 0 ||
+            _wcsicmp(ext, L".cc")  == 0 || _wcsicmp(ext, L".cxx") == 0)
+            lang = "cpp";
+    }
+
+    /* Escape text into JSON string */
+    char *esc = (char *)malloc(len * 2 + 8);
+    if (!esc) return SOV_ERR_ALLOC;
+    json_escape(text, esc, (int)(len * 2 + 8));
+
+    char *params = (char *)malloc(len * 2 + 512);
+    if (!params) { free(esc); return SOV_ERR_ALLOC; }
+    snprintf(params, len * 2 + 512,
+        "{\"textDocument\":{"
+            "\"uri\":\"%s\","
+            "\"languageId\":\"%s\","
+            "\"version\":1,"
+            "\"text\":\"%s\""
+        "}}",
+        uri, lang, esc);
+
+    SovResult r = lsp_notify(c, "textDocument/didOpen", params);
+    free(esc);
+    free(params);
+    return r;
+}
+
+SovResult lsp_client_change(LspClient *c, const wchar_t *path,
+                             const char *text, size_t len, int version) {
+    if (!c->alive) return SOV_ERR_IO;
+
+    char uri[MAX_PATH * 3];
+    path_to_uri(path, uri, sizeof(uri));
+
+    char *esc = (char *)malloc(len * 2 + 8);
+    if (!esc) return SOV_ERR_ALLOC;
+    json_escape(text, esc, (int)(len * 2 + 8));
+
+    char *params = (char *)malloc(len * 2 + 512);
+    if (!params) { free(esc); return SOV_ERR_ALLOC; }
+    snprintf(params, len * 2 + 512,
+        "{\"textDocument\":{"
+            "\"uri\":\"%s\","
+            "\"version\":%d"
+        "},"
+        "\"contentChanges\":[{\"text\":\"%s\"}]}",
+        uri, version, esc);
+
+    SovResult r = lsp_notify(c, "textDocument/didChange", params);
+    free(esc);
+    free(params);
+    return r;
+}
+
+void lsp_client_tick(LspClient *c) {
+    if (!c->alive) return;
+
+    /* Non-blocking drain of stdout pipe */
+    DWORD avail = 0;
+    while (PeekNamedPipe(c->pipe_stdout, NULL, 0, NULL, &avail, NULL) && avail > 0) {
+        int space = (int)sizeof(c->rbuf) - c->rbuf_len - 1;
+        if (space <= 0) { c->rbuf_len = 0; break; }  /* overflow: reset */
+        DWORD to_read = (avail < (DWORD)space) ? avail : (DWORD)space;
+        DWORD nread = 0;
+        if (!ReadFile(c->pipe_stdout, c->rbuf + c->rbuf_len, to_read, &nread, NULL))
+            break;
+        c->rbuf_len += (int)nread;
+        c->rbuf[c->rbuf_len] = '\0';
+    }
+
+    /* Parse complete Content-Length frames */
+    char *p = c->rbuf;
+    int remaining = c->rbuf_len;
+
+    while (remaining > 0) {
+        /* Look for "Content-Length: N\r\n\r\n" */
+        /* strnstr not in MinGW — manual search with length guard */
+        char *hdr = NULL;
+        for (int si = 0; si <= remaining - 16; si++) {
+            if (memcmp(p + si, "Content-Length: ", 16) == 0) {
+                hdr = p + si; break;
+            }
+        }
+        if (!hdr) break;
+
+        int content_len = atoi(hdr + 16);
+        if (content_len <= 0) { remaining = 0; break; }
+
+        /* Find end of header (\r\n\r\n) */
+        char *body = strstr(hdr, "\r\n\r\n");
+        if (!body) break;
+        body += 4;
+
+        int consumed = (int)(body - p);
+        int body_avail = remaining - consumed;
+        if (body_avail < content_len) break;  /* incomplete body, wait */
+
+        /* Process this message */
+        body[content_len] = '\0';
+        dispatch_message(c, body);
+
+        p         = body + content_len;
+        remaining = remaining - consumed - content_len;
+    }
+
+    /* Compact buffer */
+    if (remaining > 0 && p != c->rbuf)
+        memmove(c->rbuf, p, (size_t)remaining);
+    c->rbuf_len = remaining;
+}
+
+void lsp_client_shutdown(LspClient *c) {
+    if (!c) return;
+    if (c->alive) {
+        lsp_request(c, "shutdown", NULL);
+        lsp_notify(c, "exit", NULL);
+        WaitForSingleObject(c->pi.hProcess, 2000);
+        TerminateProcess(c->pi.hProcess, 0);
+        CloseHandle(c->pi.hProcess);
+        CloseHandle(c->pi.hThread);
+    }
+    CloseHandle(c->pipe_stdin);
+    CloseHandle(c->pipe_stdout);
+    free(c);
+}

ide/native/lsp/client.h

@@ -0,0 +1,40 @@
+#ifndef SOVEREIGN_LSP_CLIENT_H
+#define SOVEREIGN_LSP_CLIENT_H
+
+#include <windows.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include "../core/errors.h"
+
+typedef struct LspClient LspClient;
+
+typedef struct LspDiagnostic {
+    wchar_t  file[MAX_PATH];
+    uint32_t line;        /* 0-based */
+    uint32_t col;         /* 0-based */
+    uint32_t severity;    /* 1=error 2=warning 3=info 4=hint */
+    char     message[512];
+} LspDiagnostic;
+
+#define LSP_MAX_DIAG 256
+
+typedef struct LspDiagList {
+    LspDiagnostic entries[LSP_MAX_DIAG];
+    int           count;
+    wchar_t       uri[MAX_PATH];   /* file these diags belong to */
+} LspDiagList;
+
+/* Called on UI thread after each publishDiagnostics notification */
+typedef void (*lsp_diag_cb)(const LspDiagList *diags, void *ctx);
+
+SovResult lsp_client_start(LspClient **out, const wchar_t *server_cmd,
+                            lsp_diag_cb on_diag, void *cb_ctx);
+SovResult lsp_client_initialize(LspClient *c, const wchar_t *root_path);
+SovResult lsp_client_open(LspClient *c, const wchar_t *path,
+                           const char *text, size_t len);
+SovResult lsp_client_change(LspClient *c, const wchar_t *path,
+                             const char *text, size_t len, int version);
+void      lsp_client_tick(LspClient *c);   /* pump: call from message loop */
+void      lsp_client_shutdown(LspClient *c);
+
+#endif

ide/native/main.c

@@ -0,0 +1,25 @@
+/*
+ * Sovereign IDE — Entry Point
+ * Win32 wWinMain: init → window → message loop → shutdown.
+ */
+
+#include "platform/windows/application.h"
+#include "platform/windows/shell.h"
+#include "core/errors.h"
+
+#define INITIAL_WIDTH  1280
+#define INITIAL_HEIGHT  800
+
+int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrev, LPWSTR cmdLine, int nCmdShow) {
+    (void)hPrev; (void)cmdLine; (void)nCmdShow;
+
+    app_init(hInstance);
+
+    SovResult r = shell_create(hInstance, INITIAL_WIDTH, INITIAL_HEIGHT);
+    SOV_ASSERT(r == SOV_OK, "Failed to create shell window");
+
+    int exit_code = app_run();
+
+    app_shutdown();
+    return exit_code;
+}

ide/native/platform/windows/application.c

@@ -0,0 +1,70 @@
+/*
+ * Sovereign IDE — Win32 Application Entry
+ * Owns the message loop, DPI awareness, and top-level window creation.
+ */
+
+#include "application.h"
+#include "window.h"
+#include "../../core/events.h"
+#include "../../core/arena.h"
+#include "../../core/strings.h"
+
+#include <shellscalingapi.h>
+
+static struct {
+    HINSTANCE hinstance;
+    bool      running;
+    Arena     frame_arena;
+} g_app;
+
+static void app_set_dpi_awareness(void) {
+    SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE);
+}
+
+void app_init(HINSTANCE hinstance) {
+    g_app.hinstance = hinstance;
+    g_app.running = true;
+
+    CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE);
+    app_set_dpi_awareness();
+    arena_init_default(&g_app.frame_arena);
+    strings_init();
+    events_init();
+}
+
+int app_run(void) {
+    MSG msg = {0};
+    while (g_app.running) {
+        while (PeekMessageW(&msg, NULL, 0, 0, PM_REMOVE)) {
+            if (msg.message == WM_QUIT) {
+                g_app.running = false;
+                break;
+            }
+            TranslateMessage(&msg);
+            DispatchMessageW(&msg);
+        }
+
+        arena_reset(&g_app.frame_arena);
+    }
+
+    return (int)msg.wParam;
+}
+
+void app_request_quit(void) {
+    PostQuitMessage(0);
+    g_app.running = false;
+}
+
+void app_shutdown(void) {
+    strings_shutdown();
+    arena_destroy(&g_app.frame_arena);
+    CoUninitialize();
+}
+
+HINSTANCE app_get_hinstance(void) {
+    return g_app.hinstance;
+}
+
+Arena *app_frame_arena(void) {
+    return &g_app.frame_arena;
+}

ide/native/platform/windows/application.h

@@ -0,0 +1,15 @@
+#ifndef SOVEREIGN_APPLICATION_H
+#define SOVEREIGN_APPLICATION_H
+
+#include <windows.h>
+#include <stdbool.h>
+#include "../../core/arena.h"
+
+void       app_init(HINSTANCE hinstance);
+int        app_run(void);
+void       app_request_quit(void);
+void       app_shutdown(void);
+HINSTANCE  app_get_hinstance(void);
+Arena     *app_frame_arena(void);
+
+#endif /* SOVEREIGN_APPLICATION_H */

ide/native/platform/windows/shell.c

@@ -0,0 +1,681 @@
+/*
+ * Sovereign IDE — Application Shell
+ * Top-level window + child panel HWNDs + layout engine.
+ * This replaces window.c as the orchestrator.
+ */
+
+#include "shell.h"
+#include "application.h"
+#include "../../ui/layout.h"
+#include "../../ui/project_tree.h"
+#include "../../ui/status_bar.h"
+#include "../../ui/output_panel.h"
+#include "../../editor/editor_view.h"
+#include "../../editor/document.h"
+#include "../../terminal/terminal_view.h"
+#include "../../git/repository.h"
+#include "../../build/cmake_runner.h"
+#include "../../lsp/client.h"
+#include "../../core/events.h"
+#include <commdlg.h>
+#include <shlobj.h>
+
+#define TIMER_CARET  1
+#define TIMER_PTY    2
+#define TIMER_GIT    3
+
+/* Child window IDs */
+#define IDC_SIDEBAR   101
+#define IDC_EDITOR    102
+#define IDC_BOTTOM    103
+#define IDC_STATUSBAR 104
+
+#define SHELL_CLASS   L"SovShell"
+#define PANEL_CLASS   L"SovPanel"
+#define SHELL_TITLE   L"Sovereign IDE"
+
+static struct {
+    HWND frame;
+    HWND wnd_sidebar;
+    HWND wnd_editor;
+    HWND wnd_bottom;    /* container only — no D2D on this one */
+    HWND wnd_output;    /* OutputPanel lives here */
+    HWND wnd_terminal;  /* TerminalView lives here */
+    HWND wnd_status;
+
+    Layout        layout;
+    ProjectTree  *tree;
+    EditorView   *editor;
+    OutputPanel  *output;
+    TerminalView *terminal;
+    StatusBar    *status;
+
+    GitRepo       git;
+    CmakeRunner  *builder;
+    LspClient    *lsp;
+    int           lsp_version;
+
+    Document      doc;
+    int           client_w;
+    int           client_h;
+    bool          terminal_focused;
+} g_shell;
+
+/* -----------------------------------------------------------
+ * Build runner callbacks
+ * ----------------------------------------------------------- */
+static void on_build_line(const char *text, bool is_err, void *ctx) {
+    (void)ctx; (void)is_err;
+    if (!g_shell.output) return;
+    /* Convert UTF-8 line to wide */
+    wchar_t wbuf[2048];
+    MultiByteToWideChar(CP_UTF8, 0, text, -1, wbuf, 2048);
+    output_panel_append(g_shell.output, wbuf);
+    output_panel_append(g_shell.output, L"\n");
+    /* Show output panel while building */
+    g_shell.terminal_focused = false;
+    ShowWindow(g_shell.wnd_output,   SW_SHOW);
+    ShowWindow(g_shell.wnd_terminal, SW_HIDE);
+}
+
+static void on_build_done(int exit_code, void *ctx) {
+    (void)ctx;
+    if (!g_shell.output) return;
+    wchar_t msg[64];
+    if (exit_code == 0)
+        swprintf_s(msg, 64, L"✔ Build succeeded\n");
+    else
+        swprintf_s(msg, 64, L"✘ Build failed (exit %d)\n", exit_code);
+    output_panel_append(g_shell.output, msg);
+    if (g_shell.status)
+        status_bar_set_message(g_shell.status,
+            exit_code == 0 ? L"Build OK" : L"Build FAILED");
+    InvalidateRect(g_shell.wnd_bottom,  NULL, FALSE);
+    InvalidateRect(g_shell.wnd_status,  NULL, FALSE);
+}
+
+/* -----------------------------------------------------------
+ * LSP diagnostics callback
+ * ----------------------------------------------------------- */
+static void on_lsp_diag(const LspDiagList *list, void *ctx) {
+    (void)ctx;
+    if (!g_shell.editor) return;
+    /* Only apply diags that match the current open file */
+    if (g_shell.doc.has_path &&
+        _wcsicmp(list->uri, g_shell.doc.path) == 0)
+    {
+        editor_view_set_diagnostics(g_shell.editor, list);
+    }
+}
+
+/* -----------------------------------------------------------
+ * File open callback (from project tree click)
+ * ----------------------------------------------------------- */
+static void on_open_file(const wchar_t *path, void *ctx) {
+    (void)ctx;
+    document_destroy(&g_shell.doc);
+    if (document_open(&g_shell.doc, path) == SOV_OK) {
+        editor_view_set_document(g_shell.editor, &g_shell.doc);
+        editor_view_set_diagnostics(g_shell.editor, NULL);
+
+        /* Notify LSP of the new file */
+        if (g_shell.lsp) {
+            char utf8[1 << 20];
+            size_t blen = buffer_length(g_shell.doc.buffer);
+            if (blen > sizeof(utf8) - 1) blen = sizeof(utf8) - 1;
+            buffer_read(g_shell.doc.buffer, 0, utf8, blen);
+            utf8[blen] = '\0';
+            g_shell.lsp_version = 1;
+            lsp_client_open(g_shell.lsp, path, utf8, blen);
+        }
+
+        /* extract filename for status bar */
+        const wchar_t *name = wcsrchr(path, L'\\');
+        status_bar_set_file(g_shell.status, name ? name + 1 : path, false);
+
+        output_panel_append(g_shell.output, L"Opened: ");
+        output_panel_append(g_shell.output, path);
+        output_panel_append(g_shell.output, L"\n");
+    } else {
+        output_panel_append(g_shell.output, L"Failed to open file\n");
+    }
+    InvalidateRect(g_shell.wnd_editor, NULL, FALSE);
+}
+
+/* -----------------------------------------------------------
+ * Reposition all child windows from layout
+ * ----------------------------------------------------------- */
+static void apply_layout(void) {
+    PanelRect rects[PANEL_COUNT];
+    layout_compute(&g_shell.layout, g_shell.client_w, g_shell.client_h, rects);
+
+    SetWindowPos(g_shell.wnd_sidebar, NULL,
+        rects[PANEL_SIDEBAR].x, rects[PANEL_SIDEBAR].y,
+        rects[PANEL_SIDEBAR].w, rects[PANEL_SIDEBAR].h,
+        SWP_NOZORDER | SWP_NOACTIVATE);
+
+    SetWindowPos(g_shell.wnd_editor, NULL,
+        rects[PANEL_EDITOR].x, rects[PANEL_EDITOR].y,
+        rects[PANEL_EDITOR].w, rects[PANEL_EDITOR].h,
+        SWP_NOZORDER | SWP_NOACTIVATE);
+
+    SetWindowPos(g_shell.wnd_bottom, NULL,
+        rects[PANEL_BOTTOM].x, rects[PANEL_BOTTOM].y,
+        rects[PANEL_BOTTOM].w, rects[PANEL_BOTTOM].h,
+        SWP_NOZORDER | SWP_NOACTIVATE);
+
+    SetWindowPos(g_shell.wnd_status, NULL,
+        rects[PANEL_STATUSBAR].x, rects[PANEL_STATUSBAR].y,
+        rects[PANEL_STATUSBAR].w, rects[PANEL_STATUSBAR].h,
+        SWP_NOZORDER | SWP_NOACTIVATE);
+
+    if (g_shell.editor)
+        editor_view_resize(g_shell.editor,
+            (uint32_t)rects[PANEL_EDITOR].w, (uint32_t)rects[PANEL_EDITOR].h);
+    if (g_shell.tree)
+        project_tree_resize(g_shell.tree,
+            rects[PANEL_SIDEBAR].w, rects[PANEL_SIDEBAR].h);
+    /* Resize output+terminal sub-windows to fill wnd_bottom */
+    if (g_shell.wnd_output)
+        SetWindowPos(g_shell.wnd_output, NULL, 0, 0,
+            rects[PANEL_BOTTOM].w, rects[PANEL_BOTTOM].h, SWP_NOZORDER | SWP_NOACTIVATE);
+    if (g_shell.wnd_terminal)
+        SetWindowPos(g_shell.wnd_terminal, NULL, 0, 0,
+            rects[PANEL_BOTTOM].w, rects[PANEL_BOTTOM].h, SWP_NOZORDER | SWP_NOACTIVATE);
+    if (g_shell.output)
+        output_panel_resize(g_shell.output,
+            rects[PANEL_BOTTOM].w, rects[PANEL_BOTTOM].h);
+    if (g_shell.terminal)
+        terminal_view_resize(g_shell.terminal,
+            rects[PANEL_BOTTOM].w, rects[PANEL_BOTTOM].h);
+    if (g_shell.status)
+        status_bar_resize(g_shell.status,
+            rects[PANEL_STATUSBAR].w, rects[PANEL_STATUSBAR].h);
+}
+
+/* -----------------------------------------------------------
+ * Panel child window proc (sidebar / editor / bottom / status)
+ * ----------------------------------------------------------- */
+static LRESULT CALLBACK panel_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) {
+    switch (msg) {
+    case WM_PAINT: {
+        PAINTSTRUCT ps;
+        BeginPaint(hwnd, &ps);
+        if (hwnd == g_shell.wnd_sidebar && g_shell.tree)
+            project_tree_paint(g_shell.tree);
+        else if (hwnd == g_shell.wnd_editor && g_shell.editor) {
+            RECT rc; GetClientRect(hwnd, &rc);
+            editor_view_paint(g_shell.editor, rc);
+        }
+        else if (hwnd == g_shell.wnd_output && g_shell.output)
+            output_panel_paint(g_shell.output);
+        else if (hwnd == g_shell.wnd_terminal && g_shell.terminal)
+            terminal_view_paint(g_shell.terminal);
+        else if (hwnd == g_shell.wnd_status && g_shell.status)
+            status_bar_paint(g_shell.status);
+        EndPaint(hwnd, &ps);
+        return 0;
+    }
+
+    case WM_LBUTTONDOWN: {
+        int x = (int)(short)LOWORD(lp), y = (int)(short)HIWORD(lp);
+        if (hwnd == g_shell.wnd_sidebar && g_shell.tree)
+            project_tree_mouse_down(g_shell.tree, x, y);
+        else if (hwnd == g_shell.wnd_editor && g_shell.editor) {
+            SetFocus(hwnd);
+            g_shell.terminal_focused = false;
+            editor_view_mouse_down(g_shell.editor, x, y);
+        }
+        else if (hwnd == g_shell.wnd_terminal || hwnd == g_shell.wnd_output) {
+            SetFocus(hwnd);
+            g_shell.terminal_focused = (hwnd == g_shell.wnd_terminal);
+        }
+        return 0;
+    }
+
+    case WM_MOUSEMOVE: {
+        if (hwnd == g_shell.wnd_editor && g_shell.editor) {
+            bool btn = (wp & MK_LBUTTON) != 0;
+            editor_view_mouse_move(g_shell.editor,
+                (int)(short)LOWORD(lp), (int)(short)HIWORD(lp), btn);
+        }
+        return 0;
+    }
+
+    case WM_KEYDOWN:
+    case WM_SYSKEYDOWN: {
+        if (hwnd == g_shell.wnd_terminal && g_shell.terminal) {
+            UINT mods = 0;
+            if (GetKeyState(VK_CONTROL) & 0x8000) mods |= 2;
+            terminal_view_key_down(g_shell.terminal, (UINT)wp, mods);
+            return 0;
+        }
+        if (hwnd == g_shell.wnd_editor && g_shell.editor) {
+            UINT mods = 0;
+            if (GetKeyState(VK_SHIFT)   & 0x8000) mods |= 1;
+            if (GetKeyState(VK_CONTROL) & 0x8000) mods |= 2;
+            if (GetKeyState(VK_MENU)    & 0x8000) mods |= 4;
+            editor_view_key_down(g_shell.editor, (UINT)wp, mods);
+
+            /* Update status bar line/col after navigation */
+            if (g_shell.status && g_shell.doc.buffer) {
+                size_t off = editor_view_caret_offset(g_shell.editor);
+                char tmp[1];
+                /* count lines up to offset */
+                size_t line = 1, col = 1;
+                for (size_t i = 0; i < off; i++) {
+                    size_t n = buffer_read(g_shell.doc.buffer, i, tmp, 1);
+                    if (n && tmp[0] == '\n') { line++; col = 1; } else col++;
+                }
+                status_bar_set_pos(g_shell.status, (int)line, (int)col);
+                status_bar_set_file(g_shell.status,
+                    g_shell.doc.has_path ? wcsrchr(g_shell.doc.path, L'\\') + 1 : L"untitled",
+                    document_is_dirty(&g_shell.doc));
+            }
+        } else if (hwnd == g_shell.wnd_sidebar && g_shell.tree) {
+            project_tree_key_down(g_shell.tree, (UINT)wp);
+        }
+        return 0;
+    }
+
+    case WM_CHAR: {
+        if (hwnd == g_shell.wnd_terminal && g_shell.terminal) {
+            terminal_view_char(g_shell.terminal, (wchar_t)wp);
+        } else if (hwnd == g_shell.wnd_editor && g_shell.editor) {
+            editor_view_char(g_shell.editor, (wchar_t)wp);
+            /* Notify LSP of change */
+            if (g_shell.lsp && g_shell.doc.has_path && g_shell.doc.buffer) {
+                char utf8[1 << 20];
+                size_t blen = buffer_length(g_shell.doc.buffer);
+                if (blen < sizeof(utf8)) {
+                    buffer_read(g_shell.doc.buffer, 0, utf8, blen);
+                    utf8[blen] = '\0';
+                    lsp_client_change(g_shell.lsp, g_shell.doc.path,
+                                      utf8, blen, ++g_shell.lsp_version);
+                }
+            }
+        }
+        return 0;
+    }
+
+    case WM_MOUSEWHEEL: {
+        if (hwnd == g_shell.wnd_bottom && g_shell.output)
+            output_panel_scroll(g_shell.output, GET_WHEEL_DELTA_WPARAM(wp) / 40);
+        return 0;
+    }
+
+    case WM_TIMER:
+        if (wp == TIMER_PTY && hwnd == g_shell.wnd_terminal) {
+            terminal_view_tick(g_shell.terminal);
+            InvalidateRect(g_shell.wnd_terminal, NULL, FALSE);
+        } else {
+            InvalidateRect(hwnd, NULL, FALSE);
+        }
+        return 0;
+    }
+
+    return DefWindowProcW(hwnd, msg, wp, lp);
+}
+
+/* -----------------------------------------------------------
+ * Frame window proc (top-level)
+ * ----------------------------------------------------------- */
+static LRESULT CALLBACK shell_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) {
+    switch (msg) {
+
+    case WM_CREATE: {
+        layout_init(&g_shell.layout);
+
+        /* Measure initial client area so D2D render targets get real dimensions */
+        RECT cr;
+        GetClientRect(hwnd, &cr);
+        g_shell.client_w = cr.right  - cr.left;
+        g_shell.client_h = cr.bottom - cr.top;
+        if (g_shell.client_w < 1) g_shell.client_w = 1280;
+        if (g_shell.client_h < 1) g_shell.client_h = 800;
+
+        /* Compute layout so child panels get non-zero sizes */
+        PanelRect rects[PANEL_COUNT];
+        layout_compute(&g_shell.layout, g_shell.client_w, g_shell.client_h, rects);
+
+        /* Create child panels at their real positions */
+        HINSTANCE hi = app_get_hinstance();
+        g_shell.wnd_sidebar  = CreateWindowExW(0, PANEL_CLASS, NULL,
+            WS_CHILD | WS_VISIBLE,
+            rects[PANEL_SIDEBAR].x,  rects[PANEL_SIDEBAR].y,
+            rects[PANEL_SIDEBAR].w,  rects[PANEL_SIDEBAR].h,
+            hwnd, (HMENU)IDC_SIDEBAR, hi, NULL);
+        g_shell.wnd_editor   = CreateWindowExW(0, PANEL_CLASS, NULL,
+            WS_CHILD | WS_VISIBLE,
+            rects[PANEL_EDITOR].x,   rects[PANEL_EDITOR].y,
+            rects[PANEL_EDITOR].w,   rects[PANEL_EDITOR].h,
+            hwnd, (HMENU)IDC_EDITOR,  hi, NULL);
+        g_shell.wnd_bottom   = CreateWindowExW(0, PANEL_CLASS, NULL,
+            WS_CHILD | WS_VISIBLE,
+            rects[PANEL_BOTTOM].x,   rects[PANEL_BOTTOM].y,
+            rects[PANEL_BOTTOM].w,   rects[PANEL_BOTTOM].h,
+            hwnd, (HMENU)IDC_BOTTOM,  hi, NULL);
+        g_shell.wnd_status   = CreateWindowExW(0, PANEL_CLASS, NULL,
+            WS_CHILD | WS_VISIBLE,
+            rects[PANEL_STATUSBAR].x, rects[PANEL_STATUSBAR].y,
+            rects[PANEL_STATUSBAR].w, rects[PANEL_STATUSBAR].h,
+            hwnd, (HMENU)IDC_STATUSBAR, hi, NULL);
+
+        /* Output and terminal need separate HWNDs (each owns one D2D RT) */
+        int bw = rects[PANEL_BOTTOM].w;
+        int bh = rects[PANEL_BOTTOM].h;
+        g_shell.wnd_output   = CreateWindowExW(0, PANEL_CLASS, NULL,
+            WS_CHILD | WS_VISIBLE, 0, 0, bw, bh,
+            g_shell.wnd_bottom, NULL, hi, NULL);
+        g_shell.wnd_terminal = CreateWindowExW(0, PANEL_CLASS, NULL,
+            WS_CHILD, 0, 0, bw, bh,
+            g_shell.wnd_bottom, NULL, hi, NULL);
+
+        /* Init subsystems — each on its own HWND */
+        #define DBGINIT(call, name) do { \
+            SovResult _r = (call); \
+            if (_r != SOV_OK) MessageBoxW(NULL, L##name L" FAILED", L"Init Error", MB_OK); \
+        } while(0)
+        project_tree_create(&g_shell.tree, g_shell.wnd_sidebar);
+        editor_view_create(&g_shell.editor, g_shell.wnd_editor);
+        output_panel_create(&g_shell.output, g_shell.wnd_output);
+        terminal_view_create(&g_shell.terminal, g_shell.wnd_terminal);
+        status_bar_create(&g_shell.status, g_shell.wnd_status);
+        #undef DBGINIT
+        g_shell.terminal_focused = false;  /* default: show output panel */
+        /* wnd_output visible, wnd_terminal hidden until user toggles */
+        ShowWindow(g_shell.wnd_output,   SW_SHOW);
+        ShowWindow(g_shell.wnd_terminal, SW_HIDE);
+
+        /* Wire callbacks */
+        if (g_shell.tree) {
+            project_tree_set_callback(g_shell.tree, on_open_file, NULL);
+        }
+
+        /* Default document */
+        document_new(&g_shell.doc);
+        buffer_insert(g_shell.doc.buffer, 0,
+            "#include <stdio.h>\n\nint main(void) {\n    printf(\"Sovereign IDE\\n\");\n    return 0;\n}\n",
+            88);
+        buffer_mark_clean(g_shell.doc.buffer);
+        if (g_shell.editor)
+            editor_view_set_document(g_shell.editor, &g_shell.doc);
+
+        /* Open current working directory in project tree */
+        wchar_t cwd[MAX_PATH];
+        GetCurrentDirectoryW(MAX_PATH, cwd);
+        if (g_shell.tree)
+            project_tree_open(g_shell.tree, cwd);
+
+        if (g_shell.status) {
+            status_bar_set_file(g_shell.status, L"main.c", false);
+            status_bar_set_pos(g_shell.status, 1, 1);
+            status_bar_set_branch(g_shell.status, L"master");
+            status_bar_set_message(g_shell.status, L"GCC 13.2");
+        }
+
+        /* Output welcome */
+        if (g_shell.output) {
+            output_panel_append(g_shell.output, L"Sovereign IDE ready.\n");
+            output_panel_append(g_shell.output, L"Project: ");
+            output_panel_append(g_shell.output, cwd);
+            output_panel_append(g_shell.output, L"\n");
+        }
+
+        /* Git branch detection */
+        if (git_repo_open(&g_shell.git, cwd) == SOV_OK && g_shell.status) {
+            wchar_t branch_disp[136];
+            swprintf_s(branch_disp, 136, L"%s%s",
+                g_shell.git.detached ? L"detached:" : L"",
+                g_shell.git.branch);
+            status_bar_set_branch(g_shell.status, branch_disp);
+        }
+
+        /* CMake build runner */
+        wchar_t build_dir[MAX_PATH];
+        swprintf_s(build_dir, MAX_PATH, L"%s\\build", cwd);
+        cmake_runner_create(&g_shell.builder, build_dir,
+                            on_build_line, on_build_done, NULL);
+
+        /* Start LSP server (clangd must be on PATH) */
+        g_shell.lsp = NULL;
+        g_shell.lsp_version = 1;
+        if (lsp_client_start(&g_shell.lsp, L"clangd",
+                             on_lsp_diag, NULL) == SOV_OK) {
+            lsp_client_initialize(g_shell.lsp, cwd);
+            output_panel_append(g_shell.output, L"LSP: clangd started.\n");
+        } else {
+            output_panel_append(g_shell.output, L"LSP: clangd not found — install LLVM.\n");
+            g_shell.lsp = NULL;
+        }
+
+        SetTimer(g_shell.wnd_editor,   TIMER_CARET, 530, NULL);
+        SetTimer(g_shell.wnd_terminal, TIMER_PTY,   16,  NULL);  /* ~60fps PTY poll */
+        SetTimer(hwnd, TIMER_GIT, 3000, NULL);                /* git refresh every 3s */
+        return 0;
+    }
+
+    case WM_SIZE: {
+        g_shell.client_w = (int)(short)LOWORD(lp);
+        g_shell.client_h = (int)(short)HIWORD(lp);
+        apply_layout();
+        return 0;
+    }
+
+    case WM_MOUSEMOVE: {
+        int mx = (int)(short)LOWORD(lp);
+        int my = (int)(short)HIWORD(lp);
+        if (g_shell.layout.dragging) {
+            layout_update_drag(&g_shell.layout, mx, my);
+            apply_layout();
+            return 0;
+        }
+        int spl = layout_hit_splitter(&g_shell.layout, g_shell.client_w, g_shell.client_h, mx, my);
+        if (spl == 0 || spl == 1)
+            SetCursor(LoadCursorW(NULL, (LPCWSTR)IDC_SIZEWE));
+        else if (spl == 2)
+            SetCursor(LoadCursorW(NULL, (LPCWSTR)IDC_SIZENS));
+        else
+            SetCursor(LoadCursorW(NULL, (LPCWSTR)IDC_ARROW));
+        return 0;
+    }
+
+    case WM_LBUTTONDOWN: {
+        int mx = (int)(short)LOWORD(lp);
+        int my = (int)(short)HIWORD(lp);
+        int spl = layout_hit_splitter(&g_shell.layout, g_shell.client_w, g_shell.client_h, mx, my);
+        if (spl >= 0) {
+            layout_begin_drag(&g_shell.layout, spl, mx, my);
+            SetCapture(hwnd);
+        }
+        return 0;
+    }
+
+    case WM_LBUTTONUP:
+        layout_end_drag(&g_shell.layout);
+        ReleaseCapture();
+        return 0;
+
+    case WM_COMMAND: {
+        switch (LOWORD(wp)) {
+        case 1001: /* File > Open Folder */
+        {
+            /* Use SHBrowseForFolder for folder selection */
+            BROWSEINFOW bi = {0};
+            bi.hwndOwner = hwnd;
+            bi.lpszTitle = L"Open Project Folder";
+            bi.ulFlags = BIF_RETURNONLYFSDIRS | BIF_NEWDIALOGSTYLE;
+            LPITEMIDLIST pidl = SHBrowseForFolderW(&bi);
+            if (pidl) {
+                wchar_t path[MAX_PATH];
+                SHGetPathFromIDListW(pidl, path);
+                CoTaskMemFree(pidl);
+                if (g_shell.tree) project_tree_open(g_shell.tree, path);
+                output_panel_append(g_shell.output, L"Opened folder: ");
+                output_panel_append(g_shell.output, path);
+                output_panel_append(g_shell.output, L"\n");
+            }
+            break;
+        }
+        case 1002: /* File > Open File */
+        {
+            OPENFILENAMEW ofn = {0};
+            wchar_t file[MAX_PATH] = {0};
+            ofn.lStructSize = sizeof(ofn);
+            ofn.hwndOwner   = hwnd;
+            ofn.lpstrFile   = file;
+            ofn.nMaxFile    = MAX_PATH;
+            ofn.lpstrFilter = L"C/C++ Files\0*.c;*.cpp;*.h;*.hpp\0All Files\0*.*\0";
+            ofn.Flags       = OFN_FILEMUSTEXIST | OFN_PATHMUSTEXIST;
+            if (GetOpenFileNameW(&ofn)) {
+                on_open_file(file, NULL);
+            }
+            break;
+        }
+        case 1003: /* File > Save */
+            if (g_shell.doc.has_path) {
+                document_save(&g_shell.doc);
+                output_panel_append(g_shell.output, L"Saved.\n");
+            }
+            break;
+        case 1010: /* View > Toggle Sidebar */
+            g_shell.layout.sidebar_visible = !g_shell.layout.sidebar_visible;
+            apply_layout();
+            break;
+        case 1011: /* View > Toggle Bottom */
+            g_shell.layout.bottom_visible = !g_shell.layout.bottom_visible;
+            apply_layout();
+            break;
+        case 1020: /* Run > Build (Ctrl+B) */
+            if (g_shell.builder && !cmake_runner_is_running(g_shell.builder)) {
+                output_panel_clear(g_shell.output);
+                output_panel_append(g_shell.output, L"Building...\n");
+                g_shell.terminal_focused = false;
+                ShowWindow(g_shell.wnd_output,   SW_SHOW);
+                ShowWindow(g_shell.wnd_terminal, SW_HIDE);
+                if (cmake_runner_build(g_shell.builder) != SOV_OK)
+                    output_panel_append(g_shell.output, L"cmake not found — is it on PATH?\n");
+            }
+            break;
+        case 1021: /* View > Toggle Terminal/Output */
+            g_shell.terminal_focused = !g_shell.terminal_focused;
+            ShowWindow(g_shell.wnd_output,   g_shell.terminal_focused ? SW_HIDE : SW_SHOW);
+            ShowWindow(g_shell.wnd_terminal, g_shell.terminal_focused ? SW_SHOW : SW_HIDE);
+            break;
+        case 9999: /* File > Exit */
+            PostMessageW(hwnd, WM_CLOSE, 0, 0);
+            break;
+        }
+        return 0;
+    }
+
+    case WM_TIMER: {
+        if (wp == TIMER_GIT) {
+            if (git_repo_refresh(&g_shell.git) == SOV_OK && g_shell.status) {
+                wchar_t branch_disp[136];
+                swprintf_s(branch_disp, 136, L"%s%s",
+                    g_shell.git.detached ? L"detached:" : L"",
+                    g_shell.git.branch);
+                status_bar_set_branch(g_shell.status, branch_disp);
+                InvalidateRect(g_shell.wnd_status, NULL, FALSE);
+            }
+            if (g_shell.builder) cmake_runner_tick(g_shell.builder);
+            if (g_shell.lsp)     lsp_client_tick(g_shell.lsp);
+        }
+        return 0;
+    }
+
+    case WM_DPICHANGED: {
+        RECT *r = (RECT *)lp;
+        SetWindowPos(hwnd, NULL, r->left, r->top,
+                     r->right - r->left, r->bottom - r->top,
+                     SWP_NOZORDER | SWP_NOACTIVATE);
+        return 0;
+    }
+
+    case WM_CLOSE:
+        KillTimer(hwnd, TIMER_GIT);
+        KillTimer(g_shell.wnd_editor,   TIMER_CARET);
+        KillTimer(g_shell.wnd_terminal, TIMER_PTY);
+        if (g_shell.lsp)      { lsp_client_shutdown(g_shell.lsp);          g_shell.lsp      = NULL; }
+        if (g_shell.builder)  { cmake_runner_destroy(g_shell.builder);    g_shell.builder  = NULL; }
+        if (g_shell.editor)   { editor_view_destroy(g_shell.editor);      g_shell.editor   = NULL; }
+        if (g_shell.tree)     { project_tree_destroy(g_shell.tree);        g_shell.tree     = NULL; }
+        if (g_shell.terminal) { terminal_view_destroy(g_shell.terminal);   g_shell.terminal = NULL; }
+        if (g_shell.output)   { output_panel_destroy(g_shell.output);      g_shell.output   = NULL; }
+        if (g_shell.status)   { status_bar_destroy(g_shell.status);        g_shell.status   = NULL; }
+        document_destroy(&g_shell.doc);
+        DestroyWindow(hwnd);
+        return 0;
+
+    case WM_DESTROY:
+        app_request_quit();
+        PostQuitMessage(0);
+        return 0;
+    }
+
+    return DefWindowProcW(hwnd, msg, wp, lp);
+}
+
+/* Build the native menu */
+static void build_menu(HWND hwnd) {
+    HMENU bar  = CreateMenu();
+    HMENU file = CreatePopupMenu();
+    HMENU view = CreatePopupMenu();
+    HMENU run  = CreatePopupMenu();
+
+    AppendMenuW(file, MF_STRING, 1001, L"Open &Folder…\tCtrl+Shift+O");
+    AppendMenuW(file, MF_STRING, 1002, L"Open &File…\tCtrl+O");
+    AppendMenuW(file, MF_SEPARATOR, 0, NULL);
+    AppendMenuW(file, MF_STRING, 1003, L"&Save\tCtrl+S");
+    AppendMenuW(file, MF_SEPARATOR, 0, NULL);
+    AppendMenuW(file, MF_STRING, 9999, L"E&xit");
+
+    AppendMenuW(view, MF_STRING, 1010, L"Toggle &Sidebar\tCtrl+\\");
+    AppendMenuW(view, MF_STRING, 1011, L"Toggle &Output\tCtrl+J");
+    AppendMenuW(view, MF_STRING, 1021, L"Toggle &Terminal\tCtrl+`");
+
+    AppendMenuW(run,  MF_STRING, 1020, L"&Build\tCtrl+B");
+
+    AppendMenuW(bar, MF_POPUP, (UINT_PTR)file, L"&File");
+    AppendMenuW(bar, MF_POPUP, (UINT_PTR)view, L"&View");
+    AppendMenuW(bar, MF_POPUP, (UINT_PTR)run,  L"&Run");
+    SetMenu(hwnd, bar);
+}
+
+SovResult shell_create(HINSTANCE hinstance, int width, int height) {
+    /* Register panel class */
+    WNDCLASSEXW pc = {0};
+    pc.cbSize        = sizeof(pc);
+    pc.style         = CS_HREDRAW | CS_VREDRAW;
+    pc.lpfnWndProc   = panel_proc;
+    pc.hInstance     = hinstance;
+    pc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH);
+    pc.lpszClassName = PANEL_CLASS;
+    RegisterClassExW(&pc);
+
+    /* Register shell class */
+    WNDCLASSEXW sc = {0};
+    sc.cbSize        = sizeof(sc);
+    sc.style         = CS_HREDRAW | CS_VREDRAW;
+    sc.lpfnWndProc   = shell_proc;
+    sc.hInstance     = hinstance;
+    sc.hCursor       = LoadCursorW(NULL, (LPCWSTR)IDC_ARROW);
+    sc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH);
+    sc.lpszClassName = SHELL_CLASS;
+    RegisterClassExW(&sc);
+
+    g_shell.frame = CreateWindowExW(
+        0, SHELL_CLASS, SHELL_TITLE,
+        WS_OVERLAPPEDWINDOW,
+        CW_USEDEFAULT, CW_USEDEFAULT, width, height,
+        NULL, NULL, hinstance, NULL
+    );
+
+    if (!g_shell.frame) return SOV_ERR_IO;
+
+    build_menu(g_shell.frame);
+    ShowWindow(g_shell.frame, SW_SHOW);
+    UpdateWindow(g_shell.frame);
+    return SOV_OK;
+}

ide/native/platform/windows/shell.h

@@ -0,0 +1,9 @@
+#ifndef SOVEREIGN_SHELL_H
+#define SOVEREIGN_SHELL_H
+
+#include <windows.h>
+#include "../../core/errors.h"
+
+SovResult shell_create(HINSTANCE hinstance, int width, int height);
+
+#endif

ide/native/platform/windows/window.c

@@ -0,0 +1,175 @@
+/*
+ * Sovereign IDE — Win32 Window
+ * Main window proc. Owns editor view lifecycle, keyboard, mouse, paint.
+ */
+
+#include "window.h"
+#include "application.h"
+#include "../../core/events.h"
+#include "../../editor/editor_view.h"
+#include "../../editor/document.h"
+
+#define WINDOW_CLASS_NAME L"SovereignIDE"
+#define WINDOW_TITLE      L"Sovereign IDE"
+
+static EditorView *g_editor_view = NULL;
+static Document    g_doc;
+
+static LRESULT CALLBACK window_proc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) {
+    switch (msg) {
+
+    case WM_CREATE: {
+        document_new(&g_doc);
+        buffer_insert(g_doc.buffer, 0,
+            "// Sovereign IDE\n// Type here to start editing.\n\nint main(void) {\n    return 0;\n}\n",
+            81);
+        buffer_mark_clean(g_doc.buffer);
+
+        if (editor_view_create(&g_editor_view, hwnd) == SOV_OK) {
+            editor_view_set_document(g_editor_view, &g_doc);
+        }
+
+        /* 530ms timer for caret blink */
+        SetTimer(hwnd, 1, 530, NULL);
+        return 0;
+    }
+
+    case WM_TIMER:
+        InvalidateRect(hwnd, NULL, FALSE);
+        return 0;
+
+    case WM_PAINT: {
+        PAINTSTRUCT ps;
+        BeginPaint(hwnd, &ps);
+        if (g_editor_view) {
+            RECT rc;
+            GetClientRect(hwnd, &rc);
+            editor_view_paint(g_editor_view, rc);
+        }
+        EndPaint(hwnd, &ps);
+        return 0;
+    }
+
+    case WM_SIZE: {
+        uint32_t w = LOWORD(lp);
+        uint32_t h = HIWORD(lp);
+        if (g_editor_view) editor_view_resize(g_editor_view, w, h);
+        Event ev = { .kind = EVENT_RESIZE };
+        ev.resize.width = w; ev.resize.height = h;
+        event_post(ev);
+        return 0;
+    }
+
+    case WM_KEYDOWN:
+    case WM_SYSKEYDOWN: {
+        if (g_editor_view) {
+            UINT mods = 0;
+            if (GetKeyState(VK_SHIFT)   & 0x8000) mods |= 1;
+            if (GetKeyState(VK_CONTROL) & 0x8000) mods |= 2;
+            if (GetKeyState(VK_MENU)    & 0x8000) mods |= 4;
+            editor_view_key_down(g_editor_view, (UINT)wp, mods);
+        }
+        return 0;
+    }
+
+    case WM_CHAR: {
+        if (g_editor_view) {
+            editor_view_char(g_editor_view, (wchar_t)wp);
+        }
+        return 0;
+    }
+
+    case WM_LBUTTONDOWN: {
+        SetCapture(hwnd);
+        if (g_editor_view) {
+            editor_view_mouse_down(g_editor_view,
+                (int)(short)LOWORD(lp), (int)(short)HIWORD(lp));
+        }
+        return 0;
+    }
+
+    case WM_LBUTTONUP:
+        ReleaseCapture();
+        return 0;
+
+    case WM_MOUSEMOVE: {
+        if (g_editor_view) {
+            bool btn = (wp & MK_LBUTTON) != 0;
+            editor_view_mouse_move(g_editor_view,
+                (int)(short)LOWORD(lp), (int)(short)HIWORD(lp), btn);
+        }
+        return 0;
+    }
+
+    case WM_MOUSEWHEEL: {
+        if (g_editor_view) {
+            int delta = GET_WHEEL_DELTA_WPARAM(wp);
+            /* Forward as key events for scroll */
+            UINT vk = (delta > 0) ? VK_UP : VK_DOWN;
+            for (int i = 0; i < SCROLL_LINES; i++) {
+                event_post((Event){ .kind = EVENT_MOUSE_WHEEL });
+            }
+            (void)vk;
+        }
+        return 0;
+    }
+
+    case WM_SETFOCUS:
+        event_post((Event){ .kind = EVENT_FOCUS_GAINED });
+        return 0;
+
+    case WM_KILLFOCUS:
+        event_post((Event){ .kind = EVENT_FOCUS_LOST });
+        return 0;
+
+    case WM_DPICHANGED: {
+        RECT *r = (RECT *)lp;
+        SetWindowPos(hwnd, NULL, r->left, r->top,
+                     r->right - r->left, r->bottom - r->top,
+                     SWP_NOZORDER | SWP_NOACTIVATE);
+        return 0;
+    }
+
+    case WM_CLOSE:
+        KillTimer(hwnd, 1);
+        if (g_editor_view) { editor_view_destroy(g_editor_view); g_editor_view = NULL; }
+        document_destroy(&g_doc);
+        event_post((Event){ .kind = EVENT_QUIT });
+        app_request_quit();
+        return 0;
+
+    case WM_DESTROY:
+        PostQuitMessage(0);
+        return 0;
+    }
+
+    return DefWindowProcW(hwnd, msg, wp, lp);
+}
+
+HWND window_create(int width, int height) {
+    WNDCLASSEXW wc = {0};
+    wc.cbSize        = sizeof(wc);
+    wc.style         = CS_HREDRAW | CS_VREDRAW;
+    wc.lpfnWndProc   = window_proc;
+    wc.hInstance     = app_get_hinstance();
+    wc.hCursor       = LoadCursorW(NULL, (LPCWSTR)IDC_ARROW);
+    wc.hbrBackground = (HBRUSH)(COLOR_WINDOW + 1);
+    wc.lpszClassName = WINDOW_CLASS_NAME;
+    RegisterClassExW(&wc);
+
+    HWND hwnd = CreateWindowExW(
+        0,
+        WINDOW_CLASS_NAME,
+        WINDOW_TITLE,
+        WS_OVERLAPPEDWINDOW,
+        CW_USEDEFAULT, CW_USEDEFAULT,
+        width, height,
+        NULL, NULL,
+        app_get_hinstance(),
+        NULL
+    );
+
+    ShowWindow(hwnd, SW_SHOW);
+    UpdateWindow(hwnd);
+    return hwnd;
+}

ide/native/platform/windows/window.h

@@ -0,0 +1,10 @@
+#ifndef SOVEREIGN_WINDOW_H
+#define SOVEREIGN_WINDOW_H
+
+#include <windows.h>
+
+#define SCROLL_LINES 3
+
+HWND window_create(int width, int height);
+
+#endif

ide/native/terminal/conpty.c

@@ -0,0 +1,149 @@
+/*
+ * Sovereign IDE — ConPTY Terminal
+ * Windows Pseudo Console for embedded terminal.
+ * ConPTY APIs are loaded dynamically since MinGW headers may lack them.
+ */
+
+#include "conpty.h"
+#include "../core/arena.h"
+#include <stdlib.h>
+#include <string.h>
+
+/* ConPTY types and dynamic loading (Win10 1809+) */
+typedef void *HPCON;
+
+typedef HRESULT (WINAPI *PFN_CreatePseudoConsole)(COORD, HANDLE, HANDLE, DWORD, HPCON *);
+typedef HRESULT (WINAPI *PFN_ResizePseudoConsole)(HPCON, COORD);
+typedef void    (WINAPI *PFN_ClosePseudoConsole)(HPCON);
+
+#ifndef PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE
+#define PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE 0x00020016
+#endif
+
+static PFN_CreatePseudoConsole pfnCreatePseudoConsole;
+static PFN_ResizePseudoConsole pfnResizePseudoConsole;
+static PFN_ClosePseudoConsole  pfnClosePseudoConsole;
+static bool conpty_loaded = false;
+
+static bool conpty_load(void) {
+    if (conpty_loaded) return pfnCreatePseudoConsole != NULL;
+    conpty_loaded = true;
+    HMODULE k32 = GetModuleHandleW(L"kernel32.dll");
+    if (!k32) return false;
+    pfnCreatePseudoConsole = (PFN_CreatePseudoConsole)(void *)GetProcAddress(k32, "CreatePseudoConsole");
+    pfnResizePseudoConsole = (PFN_ResizePseudoConsole)(void *)GetProcAddress(k32, "ResizePseudoConsole");
+    pfnClosePseudoConsole  = (PFN_ClosePseudoConsole)(void *)GetProcAddress(k32, "ClosePseudoConsole");
+    return pfnCreatePseudoConsole != NULL;
+}
+
+struct Terminal {
+    HPCON               hpc;
+    HANDLE              pipe_in;
+    HANDLE              pipe_out;
+    HANDLE              pipe_pty_in;
+    HANDLE              pipe_pty_out;
+    PROCESS_INFORMATION pi;
+    bool                alive;
+};
+
+SovResult terminal_create(Terminal **out, uint16_t cols, uint16_t rows) {
+    if (!conpty_load()) return SOV_ERR_ALLOC;
+
+    Terminal *t = (Terminal *)calloc(1, sizeof(Terminal));
+    if (!t) return SOV_ERR_ALLOC;
+
+    HANDLE pipe_pty_in, pipe_in;
+    HANDLE pipe_pty_out, pipe_out;
+    CreatePipe(&pipe_pty_in, &pipe_in, NULL, 0);
+    CreatePipe(&pipe_out, &pipe_pty_out, NULL, 0);
+
+    COORD size = { .X = (SHORT)cols, .Y = (SHORT)rows };
+    HRESULT hr = pfnCreatePseudoConsole(size, pipe_pty_in, pipe_pty_out, 0, &t->hpc);
+    if (FAILED(hr)) {
+        CloseHandle(pipe_pty_in);
+        CloseHandle(pipe_in);
+        CloseHandle(pipe_pty_out);
+        CloseHandle(pipe_out);
+        free(t);
+        return SOV_ERR_ALLOC;
+    }
+
+    t->pipe_in = pipe_in;
+    t->pipe_out = pipe_out;
+    t->pipe_pty_in = pipe_pty_in;
+    t->pipe_pty_out = pipe_pty_out;
+
+    STARTUPINFOEXW si;
+    memset(&si, 0, sizeof(si));
+    si.StartupInfo.cb = sizeof(si);
+
+    SIZE_T attr_size = 0;
+    InitializeProcThreadAttributeList(NULL, 1, 0, &attr_size);
+    si.lpAttributeList = (PPROC_THREAD_ATTRIBUTE_LIST)malloc(attr_size);
+    InitializeProcThreadAttributeList(si.lpAttributeList, 1, 0, &attr_size);
+    UpdateProcThreadAttribute(si.lpAttributeList, 0,
+        PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE, t->hpc, sizeof(HPCON), NULL, NULL);
+
+    wchar_t cmd[] = L"cmd.exe";
+    CreateProcessW(NULL, cmd, NULL, NULL, FALSE,
+        EXTENDED_STARTUPINFO_PRESENT, NULL, NULL,
+        &si.StartupInfo, &t->pi);
+
+    DeleteProcThreadAttributeList(si.lpAttributeList);
+    free(si.lpAttributeList);
+
+    CloseHandle(pipe_pty_in);
+    CloseHandle(pipe_pty_out);
+
+    t->alive = true;
+    *out = t;
+    return SOV_OK;
+}
+
+SovResult terminal_write(Terminal *t, const char *data, size_t len) {
+    DWORD written;
+    if (!WriteFile(t->pipe_in, data, (DWORD)len, &written, NULL))
+        return SOV_ERR_IO;
+    return SOV_OK;
+}
+
+SovResult terminal_read(Terminal *t, char *buf, size_t max_len, size_t *out_len) {
+    DWORD available = 0;
+    if (!PeekNamedPipe(t->pipe_out, NULL, 0, NULL, &available, NULL) || available == 0) {
+        *out_len = 0;
+        return SOV_OK;
+    }
+
+    DWORD to_read = (available < (DWORD)max_len) ? available : (DWORD)max_len;
+    DWORD nread = 0;
+    if (!ReadFile(t->pipe_out, buf, to_read, &nread, NULL))
+        return SOV_ERR_IO;
+
+    *out_len = nread;
+    return SOV_OK;
+}
+
+void terminal_resize(Terminal *t, uint16_t cols, uint16_t rows) {
+    if (pfnResizePseudoConsole) {
+        COORD size = { .X = (SHORT)cols, .Y = (SHORT)rows };
+        pfnResizePseudoConsole(t->hpc, size);
+    }
+}
+
+bool terminal_is_alive(const Terminal *t) {
+    if (!t->alive) return false;
+    DWORD exit_code;
+    GetExitCodeProcess(t->pi.hProcess, &exit_code);
+    return exit_code == STILL_ACTIVE;
+}
+
+void terminal_destroy(Terminal *t) {
+    if (!t) return;
+    if (pfnClosePseudoConsole) pfnClosePseudoConsole(t->hpc);
+    CloseHandle(t->pipe_in);
+    CloseHandle(t->pipe_out);
+    TerminateProcess(t->pi.hProcess, 0);
+    CloseHandle(t->pi.hProcess);
+    CloseHandle(t->pi.hThread);
+    free(t);
+}