Versioning and deprecation

AxiomCore has several independent compatibility boundaries: the CLI, the Acore source schema, contract releases, artifacts, packages, UI hosts, and machine-readable output. Changing the version of one does not upgrade the others. Use this page to find each boundary, pin it, and upgrade safely.

Version boundaries

Published component versions

These are the latest public releases on GitHub as of October 15, 2026.

The local walkthroughs were first checked with CLI 0.149.0 and the signed web host 0.6.12 on macOS arm64. The existing-stack samples pin atmx-cli 0.146.7 and atmx-web 0.147.5, because CLI 0.149.0's matching automatic npm companion was not published. That combination qualifies those sample contracts, not all advanced metadata or other targets. See Install the Axiom CLI and the FastAPI guide.

Choose release versions

A contract release version can contain letters, numbers, ., _, -, and +. The CLI does not require semantic versioning, so choose a scheme your team understands, such as 0.8.2 or 2026.09.16.1. A Cloud project and version pair is immutable: retrying the same bytes is allowed; different bytes need a new version.

Never overwrite an accepted artifact to keep a version number. Create a new version, keep the old artifact and lock, and review the change:

axiom diff previous.acore candidate.acore --format semantic
axiom test candidate.acore
axiom build candidate.acore --out candidate.axiom

The semantic classifier is review evidence, not proof of consumer compatibility. Field projections, authorization, validation, defaults, errors, streams, caching, and target behavior still need owner review.

Database contract versions

Database migrations use a different, stricter rule:

• Declare the identity in the source: project(id: "...", version: "1.0.0"). Database contracts need no profile header; the manifest selects the contract type.
• The version must be numeric MAJOR.MINOR.PATCH without leading zeros (ADB1100 otherwise).
• Each managed transition binds an immutable identity, version, content, and parent. Schema, private typed data intent, and provenance have separate digests.
• Reusing a version for changed content is a conflict (ADB1103) with a suggested next version: a major bump for a breaking change, otherwise a patch bump. Unchanged content is reported as current. Metadata-only releases are shown explicitly.
• Accepting the suggestion interactively (Enter) edits the version in your source. In CI, opt in with --auto-version while preparing; frozen promotion (--frozen) then keeps the exact release and version across targets.
• A compensating rollback creates a new version and keeps older history.

These rules apply from CLI 0.149.0. Backend and project releases outside the database migration profile keep their own version rules above. See Database contracts.

Deprecate before removing

Acore accepts @deprecated metadata on declarations. Use it to record intent next to the authored surface:

@deprecated { replacement = "currentName" }
legacyName = "compatibility-value"

A useful deprecation includes:

1. the replacement and migration path;
2. the first release that carries the notice;
3. known consumers, or a statement that discovery is incomplete;
4. a test that proves old and new behavior during the overlap; and
5. a later, separately reviewed removal diff.

There is no platform-wide deprecation period. Your team sets and communicates its own removal window. The annotation does not force every runtime or generated client to show a warning; check the output of your toolchain.

Upgrade safely

Upgrade one boundary at a time where you can:

1. Record the current CLI, extractor, runtime, host, and client versions.
2. Keep the accepted source, artifacts, and dependency locks.
3. Update one tool or dependency and resolve deliberately.
4. Inspect the semantic and lock changes.
5. Run local contract and security tests and real consumer tests.
6. Promote a new immutable release only after you keep the rollback input.

See Releases and upgrades for the artifact lifecycle.

Format and reader versions

Advanced language features add metadata that older readers cannot interpret. Readers reject unknown required capabilities before activation instead of guessing.

What these rules mean in practice:

• Matching hosts. UI builders keep each contract's minRuntimeVersion. Browser and native facades reject a newer required reader before loading contracts or acquiring request owners. A legacy host without this capability reports reader 1. Use the matching host when a locked operation selects inherited validation, typed failures, or logical-submission metadata.
• Matching toolchain. Build and test advanced frontends with the matching toolchain. A source change alone does not promote a release channel.
• Cache partitions. Read caches bind the plan, contract, schema, codec, deployment authority, and verified identity. Changing any of them creates a different cache partition.
• Batches and sinks. Batch descriptors need a provider that explicitly attests the derived correlation envelope and read safety. Sink mappings need their qualified transaction and receipt profile. Unknown required features reject activation.
• Extensions. Generated extension interfaces use the checked schema and SDK profile recorded in the package and build lock. A structural interface match does not establish module identity, grants, or kernel compatibility. Keep named guest resume state, bounded codecs, and module and authority digests in the same toolchain. TypeScript and Python live subscription handles are not supported.
• Execution evidence. The evidence envelope identifies the actual runner, profile, artifact hashes, executed assertion count, and cleanup result. A compiler smoke report with zero application assertions cannot qualify a behavior scenario, guest, durable provider, or mounted target. Native scenarios accept only the explicitly supported development fixture profiles and reject unavailable controls.

Editor and compiler compatibility

Advanced metadata needs a compatible compiler, CLI, host, SDK, and editor server. Installing a grammar does not update artifact readers or runtime capabilities. Check both editor entry points when both are installed:

axiom lsp --version-json
acore-lsp --version-json

{"compilerVersion":"062cd6cd...","editorFeatures":{"virtualDocumentNavigationOptOut":true},"protocolVersion":"axiom-editor/v1","serverVersion":"acore/0.1.4 (CLI 0.149.1)"}

compilerVersion and protocolVersion must match between the two. The serverVersion labels can differ. Point explicit editor tasks at the same CLI. Offline editing and tests use prepared local contracts and locks; real serving separately needs reviewed identities, deployment grants, database readiness, and compatible providers.