# Journal

Each run is `<state-root>/runs/<run-id>/journal.json`, written by a same-directory replace so readers see a complete file. The generation directory is `<state-root>/generations/<run-id>`.

## Schema

| Schema | Meaning |
| --- | --- |
| 2 | Directory swap. Stable path, staged path, and retired sibling are recorded. Retire journals are stored as schema 2 with `kind` set to `retire`. |
| 4 | Directory swap whose ledger policy is frozen. `publication` is `directory-swap` and `ledger_policy` is an object. |
| 1 | Generation-pointer journal. Refused. |
| 3 | Generation-pointer journal with that line's ledger policy. Refused. |

`load_journal` raises `NeedsIntervention` for schema 1 and schema 3. This program publishes by directory swap and does not apply a generation-pointer plan.

Run ids from the clock use UTC `YYYYMMDD-HHMMSS` plus the process id. `--run-id` replaces that. A second run with the same id is refused.

## States

| State | What it means |
| --- | --- |
| `created` | The journal exists and the build has not been recorded as finished. |
| `building` | EasyBuild has been started for this attempt. |
| `built` | The generation is planned and has not been published. |
| `publishing` | Directory exchange is in progress. |
| `complete` | Every planned module was published. |
| `failed` | The build exited non-zero, the live tree changed during the build, or planning refused the generation. Live modules were not changed. |
| `rolled_back` | Rollback finished, or a retire rollback finished. |

`resume` rebuilds from `created`, `building`, and `failed` when no module is `published`. It publishes from `built` and `publishing`. A crash during planning can leave prepared module files while the journal still says `building`; `resume` from `building` rebuilds that generation.

Retire journals use `retiring`, then `retired`, then `rolled_back`.

## What a directory-swap plan records

Each entry of `modules_plan` includes `rel`, `live_module`, `prepared`, `staged`, `live_software`, `retired`, `backup`, `new_hash`, `old_hash`, `status`, `swap_method`, and `published_at`. `links_plan` records class links. `manifests` is a content record of each live install taken before the build, unless `--skip-live-check` was set. Publish refuses when that record no longer matches, so a live tree that changed during the build is not exchanged.

The `demo-run` journal after rollback has `"schema": 2`, `"publication": "directory-swap"`, `"state": "rolled_back"`, `"backend": "installpath"`, and `"module_rels": ["demo/1"]`. The plan's `rel` is `all/demo/1.lua`, `live_software` ends in `software/demo/1`, and `retired` ends in `software/demo/.1.demo-run`.

`status` prints one line per journal and one line per module. A retire journal prints the software directory it left in place. There is no partial listing: the first journal that cannot be read stops the command.