capsule.toml is an authoring format for a Contract and a Derivation

capsule.toml is one of two frontends that write the same pair: an author-written document, or a Preset synthesized from plain sources. Either way the compiler produces Contract and Derivation drafts, and nothing downstream can tell which door a draft came through.

Be explicit about what it is not:

capsule.toml != package manifest
capsule.toml != lockfile
capsule.toml != Capsule identity (identity is the bound Contract K)
capsule.toml != execution success guarantee

Precedence

capsule.toml present
→ parsed strictly
→ invalid or unsupported content fails the Formation (no silent fallback)

capsule.toml absent
→ supported Preset synthesis allowed
   (single-html/v1, static-files/v1, node-static/v1, single-jsx/v1)
→ sources no Preset honestly fits end with no verified route

An authored document that fails to parse stops the whole Formation — substituting a guess for a route somebody wrote is the one failure mode the strict rule exists to prevent.

Shape

Authored documents use schema ato.capsule/1: workspace inputs, the runtimes they need, derivation steps, exposed ports, and contract requirements with expectations. The example below is a shape reference (executable paths depend on the Runtime; see the Concepts page for what each part means):

schema = "ato.capsule/1"

[[input]]
id = "workspace"
use = "ato.workspace@1"
path = "."

[[runtime]]
name = "python"
version = "3.12.7"

[[derive.step]]
id = "app"
use = "ato.process@1"
op = "serve"
argv = ["/opt/ato/toolchains/python/3.12.7/bin/python3", "-B", "/app/server.py"]

[[port]]
id = "app.http"
use = "ato.http@1"
from = "app"
guest_port = 8000

[[contract.require]]
id = "app-responds"
use = "ato.contract.http@1"
port = "app.http"
method = "GET"
path = "/health"

[contract.require.expect]
status = 200

Form a directory the same way as in Getting started: with this file present, exactly the authored route is attempted; without it, Presets are tried.