Architecture

🏗️ Architecture

🇬🇧 English | 🇧🇷 Português

---

Overview

jev-harness implements a tri-runtime architecture providing strict semantic parity across Python, TypeScript, and Rust. Every gate, every CLI subcommand, and every exit code behaves identically regardless of which runtime your agent or CI environment uses.

---

Tri-Runtime Layout

jev-harness/
├── src/jev_harness/          # Python Core (PyPI: jev-harness)
│   ├── client.py             # Ultra-resilient HTTP client (pure urllib)
│   ├── gates.py              # 5 semantic decision gates
│   ├── mcp_server.py         # Universal stdio MCP server
│   ├── cli.py                # UNIX CLI (jev-harness / jev-mcp)
│   └── session.py            # Telemetry, ROI, cache protection
│
├── packages/
│   ├── ts/                   # TypeScript Package (npm: @ismaelsoilet/jev-harness)
│   │   ├── src/
│   │   │   ├── client.ts     # HTTP client (zero runtime deps)
│   │   │   ├── gates.ts      # 5 semantic gates (Node / Bun / Deno)
│   │   │   ├── mcp.ts        # MCP stdio server
│   │   │   └── cli.ts        # npx CLI entry point
│   │   └── package.json      # Zero runtime dependencies
│   │
│   └── rust/                 # Rust Crate (crates.io: jev-harness)
│       ├── src/
│       │   ├── client.rs     # Tokio-based async HTTP client
│       │   ├── gates.rs      # 5 semantic gates (Serde typed)
│       │   └── main.rs       # Standalone CLI binary (jev / jev-harness)
│       └── Cargo.toml        # Tokio + Serde only (no heavy deps)
│
├── tests/                    # 122-test battery (73 Python, 25 Rust, 24 TS)
├── scripts/release.sh        # Quad-sync release automation
└── .github/workflows/        # GitHub Actions CD pipeline

---

Data Flow: Complete Decision Pipeline

┌──────────────────────────────────────────────────────────────────────────────┐
│                            Agent Execution Context                           │
│  (Claude Code, Cursor, Antigravity, Pi, OpenCode, CI/CD, Custom SDK Loop)    │
└─────────────────────────────────┬────────────────────────────────────────────┘
                                  │
                    Test / Build / Step Execution
                                  │
                          [Error Output / Log]
                                  │
              ┌───────────────────┼────────────────────────┐
              ▼                   ▼                        ▼
    [Mode: MCP Tool]       [Mode: CLI Pipe]        [Mode: Native SDK]
  jev_triage_test_failure  pytest | jev-harness    triage_test_failure()
  (JSON structured)        (stdio + exit code)     (Python/TS/Rust call)
              │                   │                        │
              └───────────────────┴────────────────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────┐
                    │   JevClient.request()   │
                    │  (client.py / client.ts │
                    │   / client.rs)          │
                    └────────────┬────────────┘
                                 │
          ┌──────────────────────┼─────────────────────────┐
          ▼                      ▼                         ▼
  [TypeSafe AI Direct]  [OpenCode Zen (Free)]    [OpenRouter Adapter]
  api.typesafe.ai       opencode.ai/zen/v1       openrouter.ai/api
  $0.042/1M tokens      $0.00 (Free Tier)        By model pricing
          │                      │                         │
          └──────────────────────┴─────────────────────────┘
                                 │
                         [HTTP 400ms avg]
                         [< 500µs if offline]
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │   Jev System One        │
                    │   Non-autoregressive    │
                    │   Typed Decision Engine │
                    └────────────┬────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
              [category]   [confidence]  [skip_llm]
              [severity]   [action_rec]  [provider_params]
                    │
                    ▼
          ┌──────────────────┐
          │  Response Object │  (dataclass / typed interface / Serde struct)
          └────────┬─────────┘
                   │
         ┌─────────┴──────────┐
         ▼                    ▼
  [skip_llm = true]    [skip_llm = false]
  exit code: 0         exit code: 1
  Deterministic fix    Forward to Frontier LLM

---

The 5 Semantic Decision Gates

Each gate is a typed, non-autoregressive decision function exposed via CLI, MCP tool, and native SDK:

Gate	CLI Command	MCP Tool	Purpose
Triage Test Failure	test-gate / triage	jev_triage_test_failure	Classify error → deterministic fix or LLM dispatch
Should Abort Trajectory	abort-check / abort	jev_should_abort_trajectory	Detect doom loops and dead-end repetitions
Route Model Tier	route	jev_route_model_tier	Select cheapest capable model for task
Verify Step Completion	verify	jev_verify_step_completion	Calibrated evidence-to-criteria matching
Modulate Reasoning Effort	reasoning-effort / astra-jev	jev_modulate_reasoning_effort	Dynamic per-generation reasoning effort governance

→ See Gates Reference for full input/output/exit code documentation.

---

Zero-Dependency Contract (Anti-Frankenstein Principle)

This is non-negotiable across all three runtimes:

Runtime	Prohibited	Allowed
Python	requests, pydantic, httpx, aiohttp	Pure stdlib only (urllib.request, json, dataclasses, subprocess)
TypeScript	ANY runtime dependencies in package.json	devDependencies for build/test tooling only
Rust	Heavy HTTP frameworks, reqwest feature bloat	tokio (async runtime) + serde / serde_json (serialization)

Why: A token optimizer that requires heavy dependencies to install is self-defeating. The harness must be available instantly in any environment, including minimal CI images and offline air-gapped machines.

---

Autonomous Simulation Fallback

If no API key is set or the network is unavailable, the heuristic engine activates automatically:

API Request → [Connection Error / No Key]
                      │
                      ▼
         ┌────────────────────────────────┐
         │   Local Heuristic Engine       │
         │   (< 500µs — pure regex)       │
         │                                │
         │  Patterns matched:             │
         │  • ModuleNotFoundError         │
         │  • Cannot find module          │
         │  • E0463 (Rust crate missing)  │
         │  • ECONNREFUSED / timeout      │
         │  • AssertionError patterns     │
         │  • Circular attempt history    │
         └──────────────┬─────────────────┘
                        │
               [Heuristic Decision]
               (conservative fallback:
                prefers skip_llm=false
                for unknown patterns)

The heuristic uses conservative defaults: unknown patterns return skip_llm=false to never block an agent that needs LLM assistance on genuine logic bugs.

---

Session Telemetry & ROI Tracking

session.py tracks cumulative metrics across an agent session:

# Tracked per-session:
{
  "total_triage_calls": int,
  "llm_calls_skipped": int,       # skip_llm=true count
  "abort_stops_triggered": int,   # doom loops intercepted
  "deterministic_routes": int,    # route → DETERMINISTIC
  "reasoning_modulations": int,   # Astra-Jev invocations
  "tokens_saved_estimate": int,   # conservative estimate
  "dollars_saved_estimate": float # at frontier pricing
}

View at any time: jev-harness metrics

---

Semantic Exit Codes (UNIX Philosophy)

All CLI commands and pipe operations return consistent exit codes:

Code	Meaning	Agent Action
0	Safe — skip_llm=true, deterministic fix identified	Execute action_recommendation directly. No LLM call.
1	Deep logic defect — skip_llm=false, OR trajectory abort recommended	Forward targeted error to frontier LLM, or halt and notify user
2	Syntax error — invalid CLI arguments or malformed input	Fix invocation. Not an error in the codebase.

These codes enable clean composition with any shell scripting, CI system, or agent framework:

pytest 2>&1 | jev-harness test-gate
if [ $? -eq 0 ]; then
  echo "Deterministic fix applied. No LLM call needed."
elif [ $? -eq 1 ]; then
  echo "Forwarding to frontier LLM..."
fi

---

Release & Synchronization Pipeline

All four registries must stay synchronized at all times:

[Code Change]
     │
     ▼
[1. ./scripts/release.sh --check]   ← 122 tests across all 3 runtimes
     │ (100% pass)
     ▼
[2. ./scripts/release.sh --bump X.Y.Z]  ← bumps pyproject.toml, package.json, Cargo.toml, __init__.py
     │
     ▼
[3. Rebuild artifacts]              ← npm run build (TS) & cargo build --release (Rust)
     │
     ▼
[4. ./scripts/release.sh --verify-sync]  ← parity check across all 4 manifests
     │ (100% sync)
     ▼
[5. git tag vX.Y.Z && git push origin main --tags]
     │
     ▼
[6. GitHub Actions release.yml]     ← auto-publishes to PyPI + npm + crates.io

INVIOLABLE RULE: Never run git push without first running ./scripts/release.sh --verify-sync. Version divergence between registries is strictly prohibited.