# andrejksi/emi architecture

> Architecture diagram of the GitHub repository andrejksi/emi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andrejksi/emi
- Repository: https://github.com/andrejksi/emi

## Overview

EMI is a deterministic verification tool invoked when a coding agent says it is done. Its principal workflow compares baseline and candidate evidence, measures applicable checks, applies a fixed decision table, and returns an actionable receipt; hooks can invoke that workflow at an agent stop. The README documents the major verification capabilities and supported languages. Source excerpts are partial, so some stage-to-stage links are documented rather than confirmed from implementation; unsampled integrations are not expanded.

Main entry points: [`crates/emi-done/src/run.rs`](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/run.rs) (Done check), [`crates/emi-exec/src/lib.rs`](https://github.com/andrejksi/emi/blob/emi/crates/emi-exec/src/lib.rs) (Sandbox executor), [`crates/emi-driver/src/lib.rs`](https://github.com/andrejksi/emi/blob/emi/crates/emi-driver/src/lib.rs) (Driver interface), [`crates/emi-cli/src/main.rs`](https://github.com/andrejksi/emi/blob/emi/crates/emi-cli/src/main.rs) (EMI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and hooks"]
  node_cli["EMI commands<br/>[main.rs]"]
  node_setup["Project setup<br/>[setup.rs]"]
  node_hook_adapters["Harness adapters<br/>[claude.rs]"]
  node_hook_decision["Stop decisions<br/>[decision.rs]"]
end

subgraph group_check["Check orchestration"]
  node_done["Done check<br/>[run.rs]"]
  node_config["Check configuration<br/>[config.rs]"]
  node_baseline["Baseline snapshot<br/>[baseline.rs]"]
  node_candidate["Candidate changes<br/>[candidate.rs]"]
  node_oldtests["Changed old tests<br/>[oldtests.rs]"]
  node_state[("Check state<br/>[state.rs]")]
end

subgraph group_evidence["Verification stages"]
  node_regression["Regression checks<br/>[regression.rs]"]
  node_laws["Law checks<br/>[laws.rs]"]
  node_proving["Change proving<br/>[proving.rs]"]
  node_preserve["Behavior comparison<br/>[preserve.rs]"]
  node_adequacy["Mutation adequacy<br/>[adequacy.rs]"]
  node_receipt["Receipt and action<br/>[receipt.rs]"]
end

subgraph group_drivers["Language drivers"]
  node_driver_boundary["Driver interface<br/>[lib.rs]"]
  node_python_driver["Python checks<br/>[lib.rs]"]
  node_rust_driver["Rust checks<br/>[lib.rs]"]
  node_typescript_driver["TypeScript checks<br/>[lib.rs]"]
end

subgraph group_foundation["Execution and decisions"]
  node_executor["Sandbox executor<br/>[lib.rs]"]
  node_kernel["Fixed decision table<br/>[decide.rs]"]
end

node_engineer(("Engineer or agent"))

node_engineer -->|"runs commands"| node_cli
node_cli -->|"starts setup"| node_setup
node_cli -->|"starts check"| node_done
node_engineer -->|"signals done"| node_hook_adapters
node_hook_adapters -->|"translate events"| node_hook_decision
node_hook_decision -->|"invokes check"| node_done
node_done -->|"reads settings"| node_config
node_done -->|"resolves baseline"| node_baseline
node_done -.->|"freezes candidate"| node_candidate
node_done -->|"finds changed tests"| node_oldtests
node_done -->|"measures regressions"| node_regression
node_done -->|"runs laws"| node_laws
node_done -->|"measures new tests"| node_proving
node_done -->|"compares behavior"| node_preserve
node_done -->|"plants mutants"| node_adequacy
node_done -->|"uses language interface"| node_driver_boundary
node_driver_boundary -.->|"dispatches checks"| node_python_driver
node_driver_boundary -.->|"dispatches checks"| node_rust_driver
node_driver_boundary -.->|"dispatches checks"| node_typescript_driver
node_regression -.->|"runs test commands"| node_executor
node_laws -.->|"runs law commands"| node_executor
node_proving -.->|"runs proving tests"| node_executor
node_preserve -.->|"runs comparisons"| node_executor
node_adequacy -.->|"runs mutants"| node_executor
node_done -->|"classifies evidence"| node_kernel
node_done -->|"assembles findings"| node_receipt
node_kernel -->|"selects action"| node_receipt
node_done -.->|"records check state"| node_state
node_receipt -->|"reports outcome"| node_engineer

click node_cli "https://github.com/andrejksi/emi/blob/emi/crates/emi-cli/src/main.rs"
click node_setup "https://github.com/andrejksi/emi/blob/emi/crates/emi-cli/src/setup.rs"
click node_hook_adapters "https://github.com/andrejksi/emi/blob/emi/crates/emi-hook/src/claude.rs"
click node_hook_decision "https://github.com/andrejksi/emi/blob/emi/crates/emi-hook/src/decision.rs"
click node_done "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/run.rs"
click node_config "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/config.rs"
click node_baseline "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/baseline.rs"
click node_candidate "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/candidate.rs"
click node_oldtests "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/oldtests.rs"
click node_regression "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/regression.rs"
click node_laws "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/laws.rs"
click node_proving "https://github.com/andrejksi/emi/blob/emi/crates/emi-python/src/proving.rs"
click node_preserve "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/preserve.rs"
click node_adequacy "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/adequacy.rs"
click node_receipt "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/receipt.rs"
click node_driver_boundary "https://github.com/andrejksi/emi/blob/emi/crates/emi-driver/src/lib.rs"
click node_python_driver "https://github.com/andrejksi/emi/blob/emi/crates/emi-python/src/lib.rs"
click node_rust_driver "https://github.com/andrejksi/emi/blob/emi/crates/emi-rust/src/lib.rs"
click node_typescript_driver "https://github.com/andrejksi/emi/blob/emi/crates/emi-typescript/src/lib.rs"
click node_executor "https://github.com/andrejksi/emi/blob/emi/crates/emi-exec/src/lib.rs"
click node_kernel "https://github.com/andrejksi/emi/blob/emi/crates/emi-kernel/src/decide.rs"
click node_state "https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/state.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_setup,node_hook_adapters,node_hook_decision toneBlue
class node_done,node_config,node_baseline,node_candidate,node_oldtests,node_state toneAmber
class node_regression,node_laws,node_proving,node_preserve,node_adequacy,node_receipt toneMint
class node_driver_boundary,node_python_driver,node_rust_driver,node_typescript_driver toneRose
class node_executor,node_kernel,node_engineer toneIndigo
```

## Components

### CLI and hooks

- [EMI commands](https://github.com/andrejksi/emi/blob/emi/crates/emi-cli/src/main.rs): `crates/emi-cli/src/main.rs`
- [Project setup](https://github.com/andrejksi/emi/blob/emi/crates/emi-cli/src/setup.rs): `crates/emi-cli/src/setup.rs`
- [Harness adapters](https://github.com/andrejksi/emi/blob/emi/crates/emi-hook/src/claude.rs): `crates/emi-hook/src/claude.rs`
- [Stop decisions](https://github.com/andrejksi/emi/blob/emi/crates/emi-hook/src/decision.rs): `crates/emi-hook/src/decision.rs`

### Check orchestration

- [Done check](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/run.rs): `crates/emi-done/src/run.rs`
- [Check configuration](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/config.rs): `crates/emi-done/src/config.rs`
- [Baseline snapshot](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/baseline.rs): `crates/emi-done/src/baseline.rs`
- [Candidate changes](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/candidate.rs): `crates/emi-done/src/candidate.rs`
- [Changed old tests](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/oldtests.rs): `crates/emi-done/src/oldtests.rs`
- [Check state](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/state.rs): `crates/emi-done/src/state.rs`

### Verification stages

- [Regression checks](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/regression.rs): `crates/emi-done/src/regression.rs`
- [Law checks](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/laws.rs): `crates/emi-done/src/laws.rs`
- [Change proving](https://github.com/andrejksi/emi/blob/emi/crates/emi-python/src/proving.rs): `crates/emi-python/src/proving.rs`
- [Behavior comparison](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/preserve.rs): `crates/emi-done/src/preserve.rs`
- [Mutation adequacy](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/adequacy.rs): `crates/emi-done/src/adequacy.rs`
- [Receipt and action](https://github.com/andrejksi/emi/blob/emi/crates/emi-done/src/receipt.rs): `crates/emi-done/src/receipt.rs`

### Language drivers

- [Driver interface](https://github.com/andrejksi/emi/blob/emi/crates/emi-driver/src/lib.rs): `crates/emi-driver/src/lib.rs`
- [Python checks](https://github.com/andrejksi/emi/blob/emi/crates/emi-python/src/lib.rs): `crates/emi-python/src/lib.rs`
- [Rust checks](https://github.com/andrejksi/emi/blob/emi/crates/emi-rust/src/lib.rs): `crates/emi-rust/src/lib.rs`
- [TypeScript checks](https://github.com/andrejksi/emi/blob/emi/crates/emi-typescript/src/lib.rs): `crates/emi-typescript/src/lib.rs`

### Execution and decisions

- [Sandbox executor](https://github.com/andrejksi/emi/blob/emi/crates/emi-exec/src/lib.rs): `crates/emi-exec/src/lib.rs`
- [Fixed decision table](https://github.com/andrejksi/emi/blob/emi/crates/emi-kernel/src/decide.rs): `crates/emi-kernel/src/decide.rs`

### Other components

- **Engineer or agent**

## Connections

- Engineer or agent → EMI commands: runs commands (evidence: `README.md`)
- EMI commands → Project setup: starts setup (evidence: `crates/emi-cli/src/main.rs`)
- EMI commands → Done check: starts check (evidence: `crates/emi-cli/src/main.rs`)
- Engineer or agent → Harness adapters: signals done (evidence: `README.md`)
- Harness adapters → Stop decisions: translate events (evidence: `crates/emi-hook/src/claude.rs`)
- Stop decisions → Done check: invokes check (evidence: `README.md`)
- Done check → Check configuration: reads settings (evidence: `crates/emi-done/src/lib.rs`)
- Done check → Baseline snapshot: resolves baseline (evidence: `crates/emi-done/src/lib.rs`)
- Done check → Candidate changes: freezes candidate
- Done check → Changed old tests: finds changed tests (evidence: `crates/emi-done/src/lib.rs`)
- Done check → Regression checks: measures regressions (evidence: `crates/emi-done/src/lib.rs`)
- Done check → Law checks: runs laws (evidence: `README.md`)
- Done check → Change proving: measures new tests (evidence: `README.md`)
- Done check → Behavior comparison: compares behavior (evidence: `README.md`)
- Done check → Mutation adequacy: plants mutants (evidence: `README.md`)
- Done check → Driver interface: uses language interface (evidence: `crates/emi-driver/src/lib.rs`)
- Driver interface → Python checks: dispatches checks
- Driver interface → Rust checks: dispatches checks
- Driver interface → TypeScript checks: dispatches checks
- Regression checks → Sandbox executor: runs test commands
- Law checks → Sandbox executor: runs law commands
- Change proving → Sandbox executor: runs proving tests
- Behavior comparison → Sandbox executor: runs comparisons
- Mutation adequacy → Sandbox executor: runs mutants
- Done check → Fixed decision table: classifies evidence (evidence: `README.md`)
- Done check → Receipt and action: assembles findings (evidence: `crates/emi-done/src/lib.rs`)
- Fixed decision table → Receipt and action: selects action (evidence: `crates/emi-done/src/receipt.rs`)
- Done check → Check state: records check state
- Receipt and action → Engineer or agent: reports outcome (evidence: `README.md`)