ADR-0006: Host capabilities are versioned contracts described as data, published in a manifest

Status: accepted (2026-10-09)

Context#

The compiler must type-check calls to host operations without knowing every host; the runtime must invoke them; the host must dispatch them; tooling and Fathom must discover them. Four parties, one definition.

Decision#

• t0-contract defines the contract model: ContractDesc { id, version, types, operations }, OperationDesc { name, params, returns, effect, permission, execution, kind, cancellable, … }, TypeDesc (the contract type language), and HostManifest { host, api_version, language, ir, contracts, status }.
• The host builds its manifest from the same Rust values that dispatch the calls (t0-host registers each operation once, with its descriptor and its handler).
• The compiler takes a manifest (the live one in TTT, or a JSON file for the CLI); a call to contract.op is checked against that descriptor. The IR records the contract id, the version it was checked against, and the operation; the runtime refuses to run an artifact whose recorded versions the current host does not satisfy.
• The manifest TTT publishes is snapshot-tested against t0-lang/contracts/ttt-host-<api>.json (committed). Changing a contract without updating the snapshot fails a test, which is where a compatibility review happens.
• Status is kept separately from the contract: what the build supports, what is available now (e.g. no dataset catalogue configured), and what the session is permitted (docs/api/capability-system.md).

Alternatives#

• Declarations in .tz "header files" shipped with TTT -- needs a contract parser in the host and keeps two formats.
• Hard-coded host functions in the compiler -- forbidden by the brief.

Consequences#

• The language core does not know which host it runs in; the CLI compiles against any manifest file.