One chain of facts
Every command in this book reads or writes one chain: worktree → manifest → service → run → runtime facts. Each station has exactly one writer, and the next station reads only what the previous one published. There is no second source of state.
Five stations
| Station | Who writes it | What it publishes |
|---|---|---|
| Worktree | Git, observed by the engine | The checkout root path and the wt_… identity a run belongs to. |
| Manifest | A person | oberth.yaml: services, ports, dependencies, health checks, references. |
| Service | The engine at start | Which declaration was started, in which order, on which address. |
| Run | The engine's run registry | pid, start, end, exit code and the log path of one process. |
| Runtime facts | The observations of this round | Alive, listening, healthy, and the reason an earlier run ended. |
The order is the contract
A single “is it up?” flag would collapse the chain, and every reader would have to re-derive the rest. Instead each step is published before the next one is allowed to decide anything: attribution happens before lifecycle, lifecycle before observation, and observation before readiness.
That is why up can wait honestly, and why status can say a service is running while its port is unknown without contradicting itself.
A run belongs to the checkout that started it
Attribution uses this round's path observation, the manifest's content index and the run identity. Two worktrees of the same repository therefore never cross services: not a port, not a database name, not a stop.
Ports follow the same rule. port: auto is reserved per run and handed back on stop, so the second checkout asking for “the API port” gets its own answer instead of a collision.
Unknown is a fact
Failure, cancellation and an incomplete scan may not become “free”, “gone” or “healthy”. Absence from a listener table means the fact was not observed — never that the port is free. A successful signal means the signal was delivered; it does not mean the process exited.
Where each station is taught
- Declare what should run — the manifest, and the one thing a model may not do to it.
- up — dependency order, automatic ports and what readiness really proves.
- Worktrees and runs — attribution, data paths and leftover checkouts.
- logs — the run's own output, without reassembling a shell one-liner.
- status — the four runtime facts, and the honest “I cannot see”.