Core concepts
Ato describes a computation by what it can still do, and keeps a sealed point of that computation separate from the way the point is physically produced again. The terms below are the vocabulary the rest of the developer guides use.
Keep the distinctions: a continuation is not a Capsule, a Capsule is not a Run, a Record is not the computation it describes, and a Materialization is not the identity of anything.
Computation
A Computation is the work remaining from a current point. It is not a transcript of everything that happened before that point: completed steps are gone, and what matters is what can still happen from here.
An interaction evolves one Computation into the next:
C ──α──▶ C'
Interactions include a process writing to its standard output, a user typing a command, or a network request arriving. Composition builds a larger Computation from smaller ones wired together through Ports.
Contract
A Contract is an observable condition on a Computation: "the build succeeded", "the compiler error is reproduced", "the server answers GET /health with 200".
C ⊨ K
A Contract says what must hold for a future Computation to count as the same kind of point. It is a predicate, not an artifact. A Record can show that a Contract held at one observation, but the Record does not become the Contract.
Capsule
A Capsule is a sealed, immutable, addressable point in a computation — a persistent open continuation that can be preserved, passed, resumed, composed, and forked.
Computation-root wire v2 identifies a Capsule by ComputationRef. Portable Application wire v3 and v4 instead use ContractRef; the two references are not interchangeable. See Portable Capsules.
Run
A Run is a live evaluation resumed from a Capsule. Sealing is immutable; a Run advances as interactions occur.
Capsule immutable
Run evolving
Record evidence
Two Runs resumed from the same Capsule develop separately without changing the point they started from.
Record
A Record is durable evidence that an interaction was observed. Records are how a Run's history is kept, and how replay reconstructs a point on another machine.
A Record explains how a Run reached a point. It is not the point itself, and it does not redefine the Capsule.
Materialization
A Materialization is a physical way to realize a logical Capsule on a specific host. The Capsule answers "where should I continue from?"; the Materialization answers "how do I get back there on this machine?".
logical continuation != physical realization
Adding, replacing, or removing a compatible Materialization does not create a new Capsule.
Current status:
- Computation-root wire v2 can use Replay (
ato.replay@1) to reconstruct a point through the available Adapters. Portable Application v3/v4 use their selected Derivation instead. - A workspace snapshot (
ato.snapshot@1) can be captured and verified, but it cannot restore a point on its own yet. - A VM snapshot materializer has a restore-capable interface, but restoration requires an appropriate backend and compatible host; it does not promise arbitrary cross-host resume.
Binding
A Binding maps a logical requirement to a concrete runtime resource. A Port that needs a terminal is bound to an actual PTY; a workspace Port is bound to an actual directory on disk.
Bindings are resolved per run. They do not enter the identity of the Capsule.
Ports and Protocol
A Port is a typed boundary for interaction on a Computation. Its Protocol and role decide which interactions are valid. Composition wires Ports together; a runtime connects a Port to a physical endpoint through a Binding.
Where the model stops
The model is broader than the implementation. Cross-host execution is available only for supported routes and environments; it is not a universal guarantee. See Portable Capsules and the CLI quickstart.