[ AxiomCore · Documentation ]
The contract pipeline
The six stages that turn source declarations into reviewed artifacts, generated clients and runtime behavior.
The contract pipeline turns Acore declarations, or declarations extracted from an existing backend, into a versioned contract that clients and runtimes consume. It is a sequence of separate stages with review points, not one indivisible build step.
Choose what enters the contract.
Author Acore, extract a supported backend, or bootstrap a domain model. Each source path has its own execution and availability boundary.
Source boundary1. Establish the source boundary
Choose what enters the contract. Each path has its own support level:
| Source path | Status | Boundary |
|---|---|---|
| Author a service contract in Acore | Alpha | You own every declaration |
| Extract a FastAPI backend | Available | Imports the application's own modules, so import-time code must be safe in a build environment. The extractor bundles FastAPI, Starlette and Pydantic; other third-party imports become placeholders |
| Extract a Go backend | Alpha | Supported router and type patterns only |
| Bootstrap from OpenAPI JSON or SQL DDL | Experimental | A reviewable domain draft, not a full import |
See How extraction works for what each extractor reads and executes.
2. Evaluate and validate Acore
Evaluation resolves declarations, imports and amends, then checks types and
validation rules. amends composes extracted or imported input with your
declarations; it does not make the imported source trusted. Run the checks your
repository requires before building:
axiom check axiom.acore
axiom domain validate axiom.acore
axiom security check axiom.acore
axiom test axiom.acoreEach command defaults to axiom.acore when you omit the file.
3. Build the contract artifact
axiom build writes a .axiom artifact and a build baseline. Without --out
the artifact goes to .axiom/contracts/. A backend build also writes the
private server plan (<name>.server.json) beside the artifact. The artifact is
evaluated contract data, not a bundle of backend author code.
axiom build axiom.acore --out backend.axiom
axiom inspect overview .axiom inspect overview . summarizes the workspace, including .axiom
artifacts stored outside .axiom/ directories. axiom inspect backend.axiom
opens an interactive terminal browser for one contract instead.
A local build can be unsigned. A Cloud release adds provenance and durable release evidence; it does not turn an unchecked source change into a trusted release by itself.
4. Review change and provenance
Review the semantic change before you update consumers:
axiom diff previous.acore candidate.acore --format semanticWith one file, axiom diff compares the source against its last build baseline.
Formats are changelog (default), text, semantic and atom. On the
consumer side, verify that every locked contract still matches its pinned bytes:
axiom contract verify --deps AxiomDeps.toml --lock .axiom/axiom.ui.lock.jsonArtifact digests bind a lock to exact bytes; a paired Ed25519 signature and public key prove Cloud provenance. See Artifact trust.
5. Pull a client surface
axiom pull resolves a local artifact, an AxiomDeps.toml configuration, an
AxiomCore share URL or an organization/project[/version] release reference,
then generates the selected framework surface. Supported --framework values
are atmx-web, atmx-react, flutter and dart.
axiom pull --contract organization/project/1.2.0 --framework atmx-webGenerated code carries endpoint identity and typed models. The runtime still owns contract loading, validation, transport policy, caching and structured events for the capabilities each target implements.
6. Execute on the selected target
Native clients use their platform binding. Browser clients use the WebAssembly runtime and the ATMX JavaScript layer. They consume the same contract model, but storage, network APIs, initialization and framework lifecycle differ by platform. Test those boundaries in the real application. See The contract runtime.