Releases and upgrades

Use this guide to release a new contract version to Axiom Cloud, move consumers to it, release application artifacts and roll back. Every release is immutable: once a version exists, its bytes never change. You fix or roll back by choosing another version.

Contract releases and Cloud channels are Alpha and need an Axiom Cloud account and a linked project. See Workspaces and projects.

Release a contract

1. Build the contract to a file you can inspect:

   axiom build axiom.acore --out backend.axiom

2. Run the checks that apply to the project, such as axiom test, axiom security check and axiom domain validate.

3. Review the semantic diff from the previous accepted version.

4. Release the artifact with an explicit version:

   axiom release backend.axiom --version 1.2.0

   You can also build and release in one step with axiom build --release --version 1.2.0.

5. When your team requires approval, open a contract pull request between the previous release and this one.

Axiom Cloud then verifies, signs and tests the release and decides whether it can become latest. See Releases and environments.

How axiom release picks the project and version

Use a semantic version such as 1.2.0. When the CLI rewrites a version, it accepts only letters, digits, ., _, - and +, and axiom pull references accept only semantic versions. Each release run also links the current directory to the project it resolved.

Upgrade consumers

1. Change the contract or package source to the exact candidate version.
2. Resolve a new lock, for example axiom contract resolve or axiom packages resolve.
3. Diff the locked artifacts with axiom contract diff or axiom packages diff, and inspect the result.
4. Run the existing frontend or Acore UI consumer tests.
5. Commit the source change and the lock together.

To fetch a released contract directly, pass a reference in the form organization/project[/version], where organization is the workspace slug:

axiom pull acme/payments-api/1.2.0

Leave out the version to pull the release that latest points to. Until a release has been activated on latest, there is nothing to pull without a version.

Release an application

Build an .axiomapp once for each target, inspect each artifact, and combine them with axiom package only after each target is validated. Application artifacts do not include Apple or Google signing, store submission or physical-device certification.

Roll back

Roll back by selecting a previously reviewed immutable release, or by rebuilding from a reviewed source and lock pair. In Axiom Cloud, an owner moves the latest channel back to an earlier eligible release. For server bundles, check the pair with axiom server rollback-check first. See Release a backend.

Never rewrite an existing version. That would separate the audit evidence from the bytes it approved.

Upgrade a legacy backend contract

Experimental Managed execution is Experimental.

Before you switch a legacy backend to managed Acore, keep the old source, public contracts, private plans, locks, SDK build outputs and a compatible host, so you can return to them.

1. Create a migrated copy. The original source is not changed:

   axiom migrate OLD.acore --output NEW.acore

   A supported finite legacy action rewrite can keep endpoint identities and public codecs while introducing checked managed execution. A computed rewrite that is not supported keeps its legacy form. Migration never invents an equivalent managed body.

2. Build both versions, then compare public contracts and private behavior:

   axiom server diff old.axiom old.server.json new.axiom new.server.json

   The report separates a verified representation change from a behavior change. New validation, failure exposure, authority, batch or cache policy, or stream semantics need consumer review.

3. Rebuild and inspect the public contract, prepare its private resources, then run the application and provider test suites for each enabled target. Generated mobile tests and mounted web tests are separate evidence.

Other behavior to expect after the upgrade:

• Development reload keeps the last good application after an invalid edit. A compatible replacement rechecks artifacts and ownership before it transfers eligible in-flight submissions. Incompatible contracts, descriptors or session identities reject the transfer.
• Rollback uses the retained immutable inputs. It does not reuse stale grants or claim that an unknown write was rolled back.
• Application telemetry fields can be classified. A telemetry policy is private, and changing it never adds user values to metric labels.
• Scenario environment files are test inputs bound to the scenario. They cannot enable credential expiry in a deployed server.
• Use matching Axiom CLI and language server versions so the editor and compiler agree.

The browser playground includes task and inventory database examples. Its store is a checked preview, not production database preparation. See Browser preview.

Next steps

• Review a release in a contract pull request
• Understand the Cloud release pipeline and latest channel
• Work through the production-readiness checklist