Etch

Verification-first hardware design from intent to evidence.

Etch is a local hardware-design cockpit that turns a natural-language requirement into a typed design spec, candidate RTL, independent verification artifacts, EDA gate results, correctness-first ranking, physical/readiness records, and a proof dossier.

The project is built around one principle: generating RTL is not enough. Etch tracks why a candidate should be trusted, what evidence exists, what failed, which tools were missing, and which claims are still out of bounds.

Current Shape

Etch's polished vertical slice is a synchronous FIFO design loop, backed by a FastAPI service, a React/Vite workbench, an Electron desktop shell, local run workspaces, deterministic demo artifacts, optional LLM proposal paths, and tool adapters for open EDA flows.

Recent work added the autonomy and factory-planning spine around that loop:

Surface	Current behavior
Workbench cockpit	Overview, Runs, Active Run, Chip, Candidates, Frontier, Artifacts, Trust, and Diagnostics views with status-aware navigation, a focus-oriented inspector, narrative/raw event console modes, recommended command palette actions, desktop-native copy commands, run controls, and steering actions.
Correctness gates	Simulation, bounded formal, synthesis, equivalence/profile records, scoring, finalist checkpoints, and proof dossiers.
Physical path	Macro strategy, proxy floorplan/macro placement, PlaceRoute/Routing records, reliability floors, DRC/LVS/signoff records, and explicit missing-tool states.
Benchmark ladder	FIFO through arbiter, AXI-lite, DMA, cache, RV32I, accelerator tile, and SoC integration milestones.
CPU ladder v2	Planning records and local execution plans for CoreMark/Dhrystone, ISA compliance, interrupts/exceptions, cache/memory stress, branch-heavy workloads, Linux boot, and small application workloads.
Tournament engine	Deterministic correctness-first benchmark tournament planning with blocked-round handling, next actions, durable memory lessons, and review finding gates.
SoC bridge	Generator execution bridge v2 for configured Chipyard/Rocket-style roots, generated RTL import into Etch candidates, CPU validation farm records, OpenROAD blocker attempts, and FireSim readiness hooks.
Industrial program	CPU-program readiness, differential reference-trace verification plans, comparative open-core harness records, microarchitecture experiment-loop planners, validation-farm scheduler policy, physical-aware search scoring, Hammer-style flow abstraction, platform bring-up checks, closure recipe checks, PDK truth profiles, and explicit external-evidence requirements.
Scalable factory V1	Persisted context bundles, versioned domain-pack binding, durable local job queue visibility, one-generation search expansion, evidence-first ranking snapshots, and steering provenance across API and cockpit surfaces.
Desktop packaging	A macOS DMG path that bundles the cockpit and frozen Python backend; Windows helper scripts are present for setup/dev/build flows.

Etch does not claim production foundry signoff. Missing binaries, unpinned PDKs, proxy-only analyses, unavailable rule decks, and incomplete verification profiles remain visible as missing or blocked evidence.

Quickstart

Install locked Python, web, and desktop dependencies:

make install

Start the API and web cockpit in separate terminals:

make backend-dev
make frontend-dev

Open the URL printed by Vite. In the Runs view, paste this prompt and start a run:

Design a synchronous FIFO with 8-bit data, depth 16, ready/valid-style ports, overflow/underflow protection, and a preference for small area.

CLI shortcuts:

make demo-live      # fresh deterministic FIFO pipeline with local tool discovery
make demo-backup    # load the committed, integrity-checked saved run
make desktop-dev    # Electron shell hosting the cockpit
make dmg            # macOS packaged app with bundled backend

For a line-by-line operator guide, see RUN.md. For a two-minute judge walkthrough, see DEMO_SCRIPT.md.

What The Demo Proves

The FIFO demo is intentionally small, because the point is evidence quality rather than prompt size.

1. A natural-language requirement becomes a validated DesignSpec.
2. The deterministic demo creates three candidate implementations.
3. Candidate B contains an intentional underflow defect.
4. Independent oracle artifacts define simulation and formal gates.
5. Local tools run when installed; missing tools become tool_missing.
6. Failed, missing, or inconclusive evidence cannot become a proven winner.
7. The cockpit shows candidates, stage history, events, artifacts, physical status, trust posture, and proof limits.
8. Markdown and JSON proof dossiers preserve the final evidence story.

The canonical saved run is:

run_01KV7E5MAB8GYA321BJMQ1PTTS

That saved run was produced with real open-source tools: Yosys 0.66, Verilator, Icarus/VVP, SymbiYosys, yosys-smtbmc, Z3, and sky130 data. Candidate A (candidate_a_pointer_fifo, about 5485 square microns) is the proven correctness winner. Candidate C is proven but larger. Candidate B is falsified by formal property no_underflow and diverges in simulation at cycle 1.

OpenROAD, Magic, KLayout, and Netgen were not installed for that saved run, so place-and-route, DRC, and LVS are recorded as tool_missing or skipped. Physical signoff is pending; the correctness claim stands on its own.

Saved dossier: examples/saved_runs/fifo_backup/run_01KV7E5MAB8GYA321BJMQ1PTTS/results/proof_dossier.md

Architecture

flowchart LR
    Prompt["Prompt"] --> Intake["Agent intake"]
    Intake --> Spec["Typed DesignSpec"]
    Spec --> Candidates["RTL candidates"]
    Spec --> Oracle["Independent oracle"]
    Candidates --> Gates["Simulation, formal, synthesis"]
    Oracle --> Gates
    Gates --> Score["Correctness-first scoring"]
    Score --> Physical["Frontier, macro, physical, signoff records"]
    Physical --> Dossier["Proof dossier"]
    Dossier --> Workspace[("Run workspace")]
    Workspace --> API["FastAPI"]
    API --> UI["React/Electron cockpit"]

Loading

The file-backed run workspace is the system of record:

runs/{run_id}/
  run.json
  events.jsonl
  artifacts.json
  prompt_metadata.json
  design_spec.json
  candidates/
  oracle/
  simulation/
  formal/
  synthesis/
  physical/
  evolution/
  context/
  results/
  logs/

More detail lives in ARCHITECTURE.md, including component boundaries, data flow, trust boundaries, and the "more than a model wrapper" argument.

Trust Model

AI can propose artifacts; it cannot award trust.

When configured, Gemini, OpenAI, or Anthropic can propose typed specs, candidate RTL, verification artifacts, and one repair candidate. Etch then applies schema validation, interface checks, tool execution, persisted stdout/stderr, gate records, deterministic scoring, and dossier generation.

The deterministic three-candidate FIFO demo is not described as live model output. It is the reliable evidence path used for demos, tests, and cached fallbacks.

What Is Real

Capability	Status
Run persistence	Real local files, append-only events, content hashes, artifact manifests, and workspace storage helpers.
API	Real FastAPI endpoints under /api/v1, plus compatibility root run routes.
Cockpit	Real React workbench reading persisted API state, with WebSocket polling, command palette, run controls, evidence viewers, artifact diff, and desktop bridge support.
Desktop	Real Electron main/preload shell, security tests, production asset copy, and macOS DMG packaging.
Candidate/oracle generation	Deterministic FIFO artifacts by default; optional LLM-assisted proposal paths.
Simulation	Verilator+cocotb when available and appropriate; Icarus iverilog/vvp fallback.
Formal	SymbiYosys bounded checks when sby and solver binaries are installed.
Synthesis	Yosys execution and parsed metrics when installed.
Physical/signoff	Macro/floorplan/routing/reliability/signoff records with adapter hooks and parser-tested status models.
Durable scheduler primitives	SQLite-backed PipelineJob records with dependencies, worker leases, heartbeats, retry/resume state, cancellation flags, evidence artifact ids, output refs, and run summaries. The synchronous API path still remains available.
Typed external adapters	Conservative adapter registry for OpenROAD, OpenROAD Flow Scripts, Chipyard, FireSim, RISCV-DV, Spike/Sail/QEMU, Verilator, Yosys, and commercial signoff placeholders. Each adapter reports readiness, command plan, required inputs, expected outputs, parser, evidence strength, and failure taxonomy.
Verification farm records	Seed corpora, replay/randomized jobs, coverage reports, waiver registers, regression history, and flaky-test flags are modeled as persisted-ready records with no production signoff claim.
Claims ledger	Finalized runs persist results/claims_ledger.json, mapping claims to evidence classes from prompt-derived through silicon-measured and blocking production claims unless signoff-clean or measured-silicon evidence exists.
Benchmark tournament	Deterministic planning and memory records; it does not execute tools or bypass gates.
SoC/factory bridge	Manifests, executable invocation plans, command provenance, generated-file import records, validation-farm hooks, and missing-input blockers; not a hidden production flow.
Scalable factory V1	Context bundles, domain-pack bindings, durable local job records, search-tree snapshots, ranking snapshots, and steering directives are persisted and exposed through the API/cockpit.
CPU program v2	Real milestone definitions, command planners, trace comparison, open-core harness normalization, architecture experiment proposal, validation-farm job scheduling, physical-aware score penalties, Hammer-style flow planning, and platform bring-up input checks. External execution remains blocked until the required tools, roots, images, traces, and reports exist.
Observability	Local JSONL logs, command failure records, optional local trace export, and explicit cached-demo labels.

What Is Optional Or Not Yet Claimed

Area	Boundary
LLM providers	Optional. Configure Gemini, OpenAI, or Anthropic keys to use assisted proposal paths.
EDA binaries	Optional. Missing tools are reported as tool_missing; they never become passes.
PDK/rule decks	Optional external inputs. Unpinned or absent decks block physical truth and signoff claims.
Sentry	Optional via the observability extra and DSN environment variables.
Arize/Phoenix	Not implemented. Etch does not emit fake Phoenix telemetry.
Production deployment	Local-first. Full SQLite persistence and multi-user deployment remain future engineering work.
Scheduler execution	Durable local job state exists, but there is no distributed remote worker fleet, multi-user scheduler, or production queue service yet.
Scalable factory V1	The first scalable slice is local and conservative. Remote workers, multi-user tenancy, secret vaulting, remote artifact storage, and production signoff remain future work.
Industrial CPU claims	Planning/readiness only until configured IP, PDKs, commercial signoff, validation farms, package evidence, and long-running regression evidence exist.
CPU ladder v2 execution	Milestones are exposed as required-evidence contracts and local command plans. Etch does not claim CoreMark/Dhrystone scores, ISA compliance, Linux boot, differential trace success, or application workload results without persisted run artifacts.
Generator execution	Real subprocess execution only when roots, markers, and tools are configured. Logs, generated files, provenance, and blockers are persisted; failures do not become pass/fail shortcuts.
FireSim bridge	Readiness and command planning only until ETCH_FIRESIM_ROOT/FIRESIM_ROOT and manager entrypoints exist; generated software RTL must still pass Etch gates first.

Requirements

Required:

• Python 3.12+
• uv
• Node.js 20.19+ and npm

Optional EDA tools:

• yosys
• sby
• z3
• verilator plus cocotb
• iverilog and vvp
• openroad or librelane
• magic, klayout, and netgen
• OpenSTA/Yosys-related timing and equivalence tools

Commands

make install        # locked Python, web, and desktop dependencies
make test           # quality + API/core/agent/EDA + web tests + web build
make quality        # Python syntax/bytecode compilation check
make test-api       # backend/core/agent/EDA Python tests
make test-web       # web cockpit vitest suite
make test-parsers   # fast SBY/Yosys fixture parser tests
make build-web      # TypeScript + Vite production build
make demo-live      # fresh FIFO pipeline with real local tool discovery
make demo-backup    # load the committed cached run
make backend-dev    # FastAPI development server
make frontend-dev   # Vite development server
make desktop-dev    # Electron desktop shell
make build-desktop  # build packaged desktop assets
make dmg            # macOS .dmg with bundled backend

Script equivalents live in scripts/, including PowerShell helpers for setup, API/web development, and desktop build flows.

Environment

Variable	Purpose	Default
ETCH_LLM_PROVIDER	gemini, openai, anthropic, or mock for tests	gemini
ETCH_LLM_API_KEY	Provider-neutral LLM key	unset
GEMINI_API_KEY	Gemini fallback key	unset
OPENAI_API_KEY	OpenAI fallback key	unset
ANTHROPIC_API_KEY	Anthropic fallback key	unset
ETCH_LLM_MODEL	Provider model override	provider-specific
ETCH_TIMEOUT_S	LLM HTTP timeout	30.0
ETCH_RETRY_LIMIT	LLM request attempts	3
ETCH_SENTRY_DSN / SENTRY_DSN	Optional Sentry DSN	unset
ETCH_ENVIRONMENT	Sentry environment label	development
ETCH_TRACE_EXPORT	Enable local per-run trace JSON with 1, true, yes, or on	disabled
ETCH_TRACE_EXPORT_PATH	Custom trace path; supports {run_id}	logs/trace.json

Install optional Sentry support:

uv sync --extra observability

Repository Map

apps/api/       FastAPI app, run endpoints, capabilities, WebSocket event stream
apps/web/       React/Vite cockpit shared by browser and desktop renderer
apps/desktop/   Electron main/preload shell and packaged desktop assets
packages/agent/ LLM/deterministic spec, candidate, oracle, repair boundaries
packages/core/  Contracts, workspace, pipeline, scoring, memory, generators
packages/eda/   Tool harness, simulation, formal, synthesis, physical adapters
examples/       FIFO prompt, demo inputs, saved run, expected manifests
scripts/        Setup, dev servers, demos, parser/synthesis helpers, packaging
Specs/          Subsystem specs and project synthesis docs
docs/           Re-architecture milestones, plans, and design notes
assets/         README and product visuals

Useful product docs:

• PRODUCT.md - audience, product purpose, design personality, anti-references
• ARCHITECTURE.md - system components and trust boundaries
• RUN.md - copy-paste run guide
• DEMO_SCRIPT.md - concise demo narration
• LIMITATIONS.md - honest current limits
• IMPLEMENTATION_STATUS.md - implementation coverage
• SPEC_COMPLETION_MATRIX.md - spec progress matrix

API Surface

Primary cockpit endpoints are under /api/v1:

Method	Path	Purpose
GET	/health	API health and contracts version
GET	/api/v1/capabilities	Local EDA, agent, benchmark, generator, tournament, and industrial readiness metadata
GET	/api/v1/domain-packs	Read built-in domain packs and mutation operators
POST	/api/v1/runs	Create a run
POST	/api/v1/runs/import-rtl	Import a SystemVerilog file as a baseline candidate
GET	/api/v1/runs	List runs
GET	/api/v1/runs/{run_id}	Read a run
GET	/api/v1/runs/{run_id}/events	Read event history
POST	/api/v1/runs/{run_id}/context-bundles	Attach structured specs, RTL, constraints, and verification context
GET	/api/v1/runs/{run_id}/context-bundles	Read persisted context ingestion reports
POST	/api/v1/runs/{run_id}/domain-binding	Bind the run to a versioned domain pack
GET	/api/v1/runs/{run_id}/domain-binding	Read the active domain-pack binding
GET	/api/v1/runs/{run_id}/candidates	Read candidates
GET	/api/v1/runs/{run_id}/correctness	Read correctness gate records
GET	/api/v1/runs/{run_id}/physical	Read synthesis/frontier/macro/floorplan/route/reliability records
GET	/api/v1/runs/{run_id}/signoff	Read DRC/LVS/signoff records
GET	/api/v1/runs/{run_id}/dossier	Read proof dossier content
GET	/api/v1/runs/{run_id}/finalists	Read finalist checkpoint
POST	/api/v1/runs/{run_id}/finalists	Select finalist candidates
GET	/api/v1/runs/{run_id}/artifacts	Read artifact references
GET	/api/v1/runs/{run_id}/artifacts/diff	Diff two RTL artifacts
GET	/api/v1/runs/{run_id}/artifacts/{artifact_id}	Open artifact content
GET	/api/v1/pipeline/stages	Read the stage graph
POST	/api/v1/runs/{run_id}/execute	Execute a queued run
GET	/api/v1/runs/{run_id}/jobs	Inspect durable local jobs and queue summary
POST	/api/v1/runs/{run_id}/execute-async	Plan/enqueue durable local work
POST	/api/v1/runs/{run_id}/workers/local-step	Run a bounded local worker step
GET	/api/v1/runs/{run_id}/search-tree	Read persisted attempt DAG state
POST	/api/v1/runs/{run_id}/search/expand	Expand the next search cohort from existing evidence
GET	/api/v1/runs/{run_id}/ranking-snapshots	Read evidence-first ranking history
POST	/api/v1/runs/{run_id}/ranking-snapshots	Create a new evidence-first ranking snapshot
POST	/api/v1/runs/{run_id}/pause	Request pause
POST	/api/v1/runs/{run_id}/resume	Request resume
POST	/api/v1/runs/{run_id}/cancel	Request cancel
POST	/api/v1/runs/{run_id}/experiments	Inject a steering experiment
POST	/api/v1/runs/{run_id}/followup	Apply a follow-up prompt
WS	/api/v1/ws/runs/{run_id}/events	Stream poll-backed run events

For Future Agents

Start with the narrowest useful context:

1. Check local agent instructions first if your workspace provides them.
2. Read this README, then ARCHITECTURE.md for trust and data flow.
3. Use PRODUCT.md before changing cockpit UI or demo language.
4. Check recent commits with git log --oneline --decorate --max-count=30.
5. Prefer targeted reads with rg, sed -n, and git diff --stat.
6. Do not broaden claims unless code, tests, and artifacts support them.

High-signal entry points:

Task	Files
API/run behavior	apps/api/src/etch_api/, especially runs_router.py, runs/, meta_router.py, and tests in apps/api/tests/
Pipeline stages	packages/core/src/pipeline/, especially executor.py, planner.py, stage_graph.py, and stage-specific modules
Contracts	packages/core/src/contracts/
Workspace/artifacts	packages/core/src/workspace/
Scoring/finalists/dossier	packages/core/src/selection/
Benchmark tournament	packages/core/src/selection/benchmark_tournament.py, selection/tournament.py, and pipeline/intake/benchmarks.py
SoC/industrial bridge	packages/core/src/generators/, packages/core/src/pipeline/import_rtl.py, packages/eda/src/eda_capabilities/, and physical OpenROAD records
EDA tools	packages/eda/src/toolkit/, packages/eda/src/gates/, packages/eda/src/physical/
Web cockpit	apps/web/src/App.tsx, components/views/, components/workspace/, hooks/, lib/, scene/, styles.css
Desktop shell	apps/desktop/src/main/, apps/desktop/src/preload/, apps/desktop/test/security.test.mjs

Suggested validation:

make quality
make test-api
make test-web
npm --prefix apps/desktop test
make build-web

For README-only edits, at minimum run a Markdown/link sanity check manually and inspect git diff -- README.md. For code touching shared contracts, run the targeted tests first, then make test before handoff.

Continuous Integration

GitHub Actions runs .github/workflows/ci.yml on pushes to main and on pull requests.

CI checks:

• locked Python dependency installation
• package import verification
• Python syntax compilation
• backend/core/agent/EDA tests
• explicit live-EDA integration skip behavior
• locked frontend installation
• frontend vitest suite
• TypeScript/Vite production build
• desktop dependency installation
• desktop security/unit tests
• desktop TypeScript build

CI does not install heavyweight EDA tools. Tool-dependent integration tests skip honestly when binaries are absent.

Verification Snapshot

Last documented full local gate before this README refresh:

• Python: 156 passed, 3 live-tool tests skipped when sby was unavailable
• Web cockpit: 46 passed across 17 files
• Desktop shell security tests: 2 passed
• TypeScript/Vite production build: passed

Run the current core gate with:

make test

Screenshots

Screenshots have not yet been committed. The completed desktop/mobile inspection notes live in UI_INSPECTION.md.

Useful future captures:

• completed cockpit overview
• Candidate B failure and counterexample evidence
• correctness scoreboard and finalist state
• proof dossier and trust statement
• cached-demo banner