Contracts and artifacts

AxiomCore keeps four things separate: editable source, distributable packages, dependency decisions and runnable applications. The separation makes each change reviewable and stops a dependency from silently becoming new source code in your build.

Artifact map

Diagram source

flowchart TD
  A[Acore source] --> B[Canonical .axiom package]
  B --> C[Resolve with manifest and lock]
  B --> D[Inspect, diff, test or mock]
  C --> E[Existing client or Acore UI build]
  E --> F[Framework integration or .axiomapp]

A manifest declares what a consumer depends on. Resolution pins the selected package in a lock. A client consumes that contract, and an Acore UI build can package the application as .axiomapp.

.acore: authoring source

A .acore file is editable declarative source. It can import trusted source, amend supported build inputs, declare behavior and policy, or describe an Acore UI tree. Source stays on the authoring side of a package boundary: consumers receive the evaluated package, not your .acore files.

.axiom: contract and package

A .axiom file is a canonical, versioned package. axiom build writes a backend contract to .axiom/contracts/ by default, or to the path you pass with --out. It also writes the private server plan (<name>.server.json) beside the artifact; keep that plan out of client bundles.

Declarative packages cannot contain executable package-author code. An extension package only identifies separately distributed WebAssembly bytes, which need their own capability grant and sandbox review. The extension payload schemas are axiom-extension/v2, and axiom-extension/v3 for selected typed packages; both record the exact module digest, interface, SDK, limits, provenance and requested authority. Extensions are Experimental; see Extensions.

Manifests and locks

A manifest states dependency intent. A committed lock records the exact artifact, version, digest, kind and selection a build used. A consumer imports through a stable alias, and resolution never falls back to live backend discovery or package-author source.

axiom contract verify recomputes every lock input without changing files. It reports how many locked aliases are signed and warns about unsigned local artifacts.

.axiomapp: built application

An .axiomapp is a deterministic Acore UI application artifact. It carries the lowered UI payload and the build metadata a UI host needs. It is not a .axiom package, and it does not imply app-store signing or distribution.

See App lifecycle and targets for the full workflow.

Semantic change review

Byte changes alone cannot explain contract impact. AxiomCore compares meaning instead:

• axiom diff compares two .acore sources, or one source against its build baseline.
• axiom packages diff BEFORE AFTER classifies package changes and requires an explicit --approve value for breaking-change, target-reduction, new-required-theme-role or permission-increase.
• axiom inspect diff compares whole-application evidence snapshots. See Changes and impact.

Next steps

• The contract pipeline
• Artifact trust
• Imports, amends and variants
• Contract, package and security commands