> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eucaengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forks & counterfactuals

> Fork the live world, intervene on the copy, diff the outcome against the original, and drop it — what-ifs that never touch the real run.

A **fork** is a deep copy of the live world. The same systems — physics, combat, rules —
run on the fork as on the main world, so a fork evolves exactly as the original would have,
until you intervene on it. That is what makes a fork a genuine counterfactual: any
divergence you observe is caused by your intervention, not by drift.

```mermaid theme={null}
flowchart LR
    M[("Main world<br/>(untouched)")] -->|"fork"| F[("Fork")]
    F -->|"intervene<br/>step · edit"| F2[("Fork after what-if")]
    F2 -->|"diff vs main"| R{{"what your change caused"}}
    F2 -->|"drop"| G["discarded"]
```

The pattern is always the same four moves:

<Steps>
  <Step title="Fork">
    `POST /fork` deep-clones the main world into a named fork at the current tick.
  </Step>

  <Step title="Intervene">
    Change the fork — step it further, edit components, apply a scenario — without
    touching the main world.
  </Step>

  <Step title="Diff">
    Compare the fork's outcome against the original to read off exactly what your
    intervention changed.
  </Step>

  <Step title="Drop">
    `DELETE /fork/{id}` discards the copy. The main run is untouched throughout.
  </Step>
</Steps>

## A what-if run

```bash theme={null}
# Snapshot the main world so we have a baseline to diff against.
curl -s -X POST http://localhost:3917/snapshot \
  -H 'content-type: application/json' -d '{"label":"before"}'

# Fork the world at the current tick.
curl -s -X POST http://localhost:3917/fork \
  -H 'content-type: application/json' -d '{"fork_id":"what-if"}'

# Run the counterfactual *only on the fork* — the main world does not advance.
curl -s -X POST http://localhost:3917/fork/what-if/step \
  -H 'content-type: application/json' -d '{"ticks":100}'

# Read the fork's diverged state.
curl -s -X GET http://localhost:3917/fork/what-if/observe

# Drop the fork. Nothing about the main run changed.
curl -s -X DELETE http://localhost:3917/fork/what-if
```

<Note>
  `POST /observe` on the main world and `GET /fork/{id}/observe` return the same shape of
  world dump, at different ticks — so the divergence between a fork and its parent is just
  a comparison of two tables.
</Note>

## Forks vs. snapshots

The two tools answer different questions:

|              | Captures                       | Reads back                             | Use it to                                         |
| ------------ | ------------------------------ | -------------------------------------- | ------------------------------------------------- |
| **Fork**     | A full, live copy of the world | A complete world you can keep stepping | Run a what-if forward and compare outcomes        |
| **Snapshot** | A labeled summary at a tick    | A diff against another snapshot        | Track what changed between two moments of one run |

## Counterfactuals as the answer key

Forking is also how Euca answers *action-conditioned* questions exactly. To compute "what
would the next state be if the agent took action **a**," the engine forks the world,
applies **a** on the copy, and reads the resulting next-step distribution — without
disturbing the real run or consuming the canonical RNG. That operation is the backbone of
[world-model evaluation](/evaluation/overview): the exact post-action ground truth a model
is graded against.