Contracts

What is the contract lifecycle in Traverse?

Q: What is the contract lifecycle in Traverse?

A Traverse contract lifecycle runs from authoring through registration, active use, versioned updates, and eventual retirement. Each stage has specific actions: you write the contract TOML, register it with a WASM binary, callers use it, you register new versions as requirements change, and you remove old versions when no callers depend on them.

A Traverse contract starts as a TOML file and ends when you remove the last version from the registry. Between those two points it goes through five stages: authoring, registration, active use, versioned updates, and retirement.

1. Authoring

You write the contract TOML alongside your Rust implementation. The contract defines what the capability accepts, what it returns, and what conditions hold. You iterate on both the contract and the code together. The contract is the spec — write it first if possible.

2. Registration

Once the implementation compiles to WASM, you register the contract and the binary together with the CLI. The registry validates the contract schema and rejects invalid contracts before storing anything. A successful registration makes the capability available to callers.

3. Active use

Callers — applications, AI agents via MCP, other services — discover and call the capability. The runtime enforces the contract on every call. Trace artifacts accumulate as evidence of every execution.

4. Versioned updates

Requirements change. You register a new version: update the TOML version string, update the Rust implementation, compile, register. The old version stays available. Callers migrate on their own schedule. See contract versioning for how to manage breaking vs. non-breaking changes.

5. Retirement

When no active callers pin to an old version, you remove it from the registry. Any caller that still references it will fail at discovery time with a clear registry error — not a silent behavior change. That is intentional: retirement forces callers to migrate explicitly.

The governing spec — the document behind the contract — lives outside the registry and evolves independently. See what is a governing spec for how those two relate.