docs/reference/SIMULATION.md

# What's Simulated, What's Real, and What the Physical World Needs

The Chief Engineer's value is a **closed learning loop**: propose settings →
observe the outcome → learn → do better next time. To demo that loop without a
printer farm — and to keep it reproducible for judges — the *outcome* step runs
in a deterministic simulator. Everything else is real.

## Honest-claims table

| Component | Status | Notes |
|-----------|--------|-------|
| Environment-keyed retrieval (RAG) | **Real** | `core/ledger.py` — exact match + normalized env-distance |
| Chief Engineer reasoning (LLM) | **Real** | `core/chief_engineer.py` — real Ollama (gemma4), with deterministic fallback |
| Learned policy (parametric) | **Real** | `learn/policy.py` — offsets per (material, geometry, env-bucket), persisted |
| Spine safety veto | **Real** | `core/spine.py` — clamps unsafe settings; LLM proposes, code decides |
| Knowledge ingestion | **Real** | `ingest/` — slicer/firmware configs → references; research → lessons |
| **Print outcome** | **Simulated** | `sim/outcome.py` — physics-lite stand-in for the printer + sensors |
| Capability mesh (6 nodes) | **Context** | one node's logic is real; the others render as available capacity |
| Weight-level fine-tuning | **Framed frontier** | `ingest/modal_app.py` stub; the ledger becomes training data |

## The one simulated boundary

`sim/outcome.py` is the **only** stand-in for physical reality. It models the
same physics the seed lessons describe (cooling vs. overhang sag, humidity →
stringing, ABS warp, bed temp → adhesion, and **build-plate position** — edges/
corners of a heated bed run cooler + draftier, so warp/adhesion suffer there,
worst for high-shrink materials) and returns an outcome + a 0–1 quality score.
It is deterministic, so the learning curve is reproducible.

Critically, this is **not the model grading its own work**. The Chief Engineer
proposes; this separate world returns an outcome the model never sees in
advance — exactly the role a printer and its sensors play.

## Swapping in the physical world

Replace `sim.outcome.simulate(settings, job, env)` with a real adapter that
returns the same `SimResult`. Three interfaces are needed:

1. **Actuation — stream settings to the printer.** Generate g-code from the
   proposed `PrintSettings` (the readout in `viewer.gcode_readout` is the seed
   of this) and stream over USB/serial (Marlin) or the Moonraker/Klipper API.
   *Frontier on the roadmap: node → Ender serial control.*
2. **Sensing — read the environment.** A temp/humidity sensor (e.g. a BME280 on
   a Pi) feeds the `Environment` that today comes from the sliders.
3. **Outcome detection — judge the print.** A camera + a defect classifier
   (the **3D-ADAM** taxonomy already encoded in `ingest/distill.py`) maps an
   image to `outcome` + `quality`. This replaces the simulator's scoring.

Each is a clean substitution behind the existing types — the loop, the policy,
the ledger, and the UI do not change. That is the point of keeping the
simulated boundary this narrow.