JevPlays/ARCHITECTURE.md

JevPlayer Architecture Specification

JevPlayer is a client-side Fabric mod designed for autonomous Minecraft survival gameplay. It integrates TypeSafe AI's Jev (a fast, calibrated System-One decision engine) with Baritone (the industry-standard pathing and mining actuator) via a zero-allocation, modular architecture.

---

1. System Overview & Sense-Decide-Act Cycle

The core runtime operates on an asynchronous Sense \to Decide \to Act cycle designed to maintain client-thread responsiveness without dropping frames.

flowchart TD
    subgraph Minecraft_Client_Thread ["Minecraft Client Thread (~20 TPS)"]
        A["Client Tick Event"] --> B["Sense: World Sensor"]
        B --> C["State Snapshot Created"]
        C --> D{"Reflex Engine Emergency?"}
        D -- Yes --> E["Immediate Reflex Actuation (Lava/Drown/Flee)"]
        D -- No --> F{"Watchdog Alert?"}
        F -- Yes --> G["Watchdog Recovery (Stuck/Loop Reset)"]
        F -- No --> H["Check Pending Asynchronous Decision"]
        H --> I["Act: Baritone Action Executor"]
    end

    subgraph Async_Decision_Worker ["Async Decision Worker (Daemon Thread)"]
        C -. Post State .-> J["Legal Actions Filter"]
        J --> K["Format Concise JSON Prompt"]
        K --> L{"Provider Mode"}
        L -- Real API --> M["HTTP/2 POST to api.typesafe.ai (70-500ms)"]
        L -- Mock Mode --> N["Calibrated Heuristic Decision (<1ms)"]
        L -- Replay --> O["Recorded JSONL Decision Log"]
        M --> P["Parse Typed Jev Decision"]
        N --> P
        O --> P
        P -. Deliver Decision .-> H
    end

    subgraph Logging_Worker ["Background Logger Thread"]
        C -. Log Snapshot .-> Q["decision_log.jsonl"]
        P -. Log Decision .-> Q
        I -. Log Milestone/Event .-> R["episode_events.json"]
    end

---

2. Multi-Module Project Structure

To decouple Minecraft dependencies and allow cross-version support, the repository is partitioned into a zero-dependency core module and thin versioned adapters:

JevPlays/
├── core/                           # Pure Java 21/25, ZERO Minecraft dependencies
│   ├── src/main/java/com/typesafe/jevplayer/core/
│   │   ├── action/                 # Action catalog (14 actions) & legal action generator
│   │   ├── bridge/                 # Abstract sensor & actuator bridge interfaces
│   │   ├── config/                 # Configuration model & secure key redaction
│   │   ├── decision/               # TypeSafe HTTP/2 client, MockProvider, DecisionReplay
│   │   ├── director/               # 9-stage milestone ladder & episode pacing
│   │   ├── reflex/                 # Zero-latency emergency reflexes (lava, air, combat)
│   │   ├── sim/                    # Headless simulated world adapter for unit tests
│   │   ├── state/                  # Zero-allocation state snapshots & hash generators
│   │   └── watchdog/               # Stuck detection, loop breaker, death watchdogs
│   └── src/test/java/              # 100% deterministic unit tests (JUnit 5)
├── adapter-1_21_11/                # Fabric Loom module for Minecraft 1.21.11
│   ├── src/main/java/.../          # Concrete WorldSensor, ActionExecutor, InputBridge, HUD
│   └── src/main/resources/         # fabric.mod.json for 1.21.11
├── adapter-26_1/                   # Thin adapter for Minecraft 26.1 (unobfuscated)
│   └── src/main/java/.../          # ClientModInitializer & Baritone 1.18.0 bridge
├── adapter-26_2/                   # Thin adapter for Minecraft 26.2 (unobfuscated)
│   └── src/main/java/.../          # ClientModInitializer & Baritone 1.19.0 bridge
└── libs/                           # Official Baritone public API jars

Why Multi-Module?

1. Deterministic Testing: The core module compiles with pure Java and runs entire 10,000-tick simulations in headless unit tests without launching Minecraft or loading native libraries.
2. Version Independence: Changes to Minecraft versions (such as the un-obfuscated architecture in 26.x) do not require altering core decision logic, reflex trees, or watchdog rules.
3. No Code Duplication: Adapters remain thin shims (typically < 300 LOC) that map Minecraft entities, blocks, and keys to core POJOs.

---

3. Concurrency & Thread Synchronization

Minecraft runs rendering and client entity updates synchronously on the main thread. Network I/O or blocking waits on that thread cause immediate frame stutter.

Lock-Free Reference Exchange

sequenceDiagram
    participant Main as Client Tick Thread
    participant StateRef as AtomicReference<StateSnapshot>
    participant DecRef as AtomicReference<JevDecision>
    participant Worker as Decision Daemon Worker
    participant Jev as TypeSafe AI (System One)

    Main->>Main: Sense environment & calculate legal actions
    Main->>StateRef: set(latestSnapshot)
    StateRef-->>Worker: Poll state
    Worker->>Jev: HTTP/2 POST /v1/systemone (70-500ms)
    Note over Main: Client renders smoothly at 60+ FPS<br/>Reflexes actively guard player
    Jev-->>Worker: HTTP 200 {choice, confidence, urgency}
    Worker->>DecRef: set(decision)
    DecRef-->>Main: getAndSet(null)
    Main->>Main: Actuate Baritone goal

• Thread Confinement: State reading occurs only on the client thread.
• Reference Passing: The decision worker takes an immutable StateSnapshot.
• Preemption: If an emergency reflex fires while a network query is pending, the reflex takes precedence immediately. When the delayed HTTP response returns, the main thread discards it if the game state has transitioned.

---

4. Reflex Engine vs. System-One Jev

Feature	Reflex Engine (System 0)	TypeSafe Jev (System 1)
Execution Thread	Client tick thread (synchronous)	Background daemon thread (asynchronous)
Latency	< 0.05 \text{ ms}	70 \text{ -- } 500 \text{ ms}
Trigger Criteria	Lava, drowning, fire, point-blank combat, starving	Strategic choices (mining, crafting, exploring, sleeping)
Preemption Power	Can cancel any active Baritone goal instantly	Subordinate to active reflexes and watchdogs
Failure Mode	Fail-safe: immediate protective action	Fail-soft: fallback to heuristic rule if confidence < 0.65

---

5. Actuation via Baritone (LGPL-3.0 Compliance)

JevPlayer never modifies, forks, or bundles Baritone source code. All actuation interfaces through baritone.api.BaritoneAPI:

• Pathing: BaritoneAPI.getProvider().getPrimaryBaritone().getCustomGoalProcess().setGoalAndPath(new GoalBlock(pos))
• Mining: BaritoneAPI.getProvider().getPrimaryBaritone().getMineProcess().mineByName(blockName)
• Exploration: BaritoneAPI.getProvider().getPrimaryBaritone().getExploreProcess().explore(originX, originZ)
• Inventory/Crafting: Executed via standard Minecraft ClientPlayerInteractionManager window click packets or Baritone builder process.

---

6. Watchdog & Failure Recovery Matrix

stateDiagram-v2
    [*] --> Healthy
    Healthy --> ReflexActive: Lava / Low Air / Under Attack
    ReflexActive --> Healthy: Danger Cleared

    Healthy --> StuckDetected: Stationary > 45s without inventory change
    StuckDetected --> ClearingPath: Cancel Goal + Step Aside + Blacklist
    ClearingPath --> Healthy: Movement Resumed

    Healthy --> ActionLoopDetected: Same Action Failed 3 Times
    ActionLoopDetected --> BlacklistingAction: Suppress Action for 60s
    BlacklistingAction --> Healthy: Shift to Alternative Action

    Healthy --> Dead: Player Health <= 0
    Dead --> Respawning: Auto-Respawn Click
    Respawning --> Healthy: Reset Ladder to Milestone 1 (Wood)

    Healthy --> Disabled: Kill Switch (F9) Pressed
    Disabled --> [*]