Extension dependencies

Extension dependencies are third-party packages compiled into an extension: Rust crates, npm packages or pure Python wheels. They are build inputs, not runtime capabilities, so a package never grants an extension any authority. Like the rest of the extension workflow, this surface is Experimental.

You declare packages under one extension in AxiomDeps.toml. Axiom resolves the complete graph once per compatible environment, verifies immutable bytes, writes a canonical lock and materializes a content-addressed build view. Sharing bytes between extensions never shares guest memory, instances, permissions, handles or audit streams.

Diagram source

flowchart LR
  A[AxiomDeps.toml] --> B[axiom dependencies check]
  B --> C[axiom dependencies resolve]
  D[HTTPS registry index] --> C
  C --> E[Content-addressed cache]
  C --> F[.axiom/AxiomDeps.lock]
  E --> G[.axiom/dependencies build view]
  F --> G
  G --> H[Offline extension build]

check validates the manifest without network access. resolve reads each declared registry index, downloads the exact versions, verifies their digests and writes the lock. Source builds then use only the verified, locked bytes and never fetch.

Example

type = "frontend"
targets = ["web", "server"]

[dependencyEnvironments.rust-release]
language = "rust"
profile = "release"
runtimeVersion = "1.82.0"
toolchainSha256 = "<64 lowercase hex characters>"
engine = "cargo"
engineSha256 = "<64 lowercase hex characters>"
abi = "axiom-extension-abi@1.0.0"
sdk = "axiom-extension-sdk@0.1.0"
bindingSchema = "axiom-sdk-interface-ir/v1"
targetFamily = "wasm32"

[dependencyRegistries.crates]
language = "rust"
index = "https://packages.example/rust-index.json"
allowedHosts = ["packages.example"]

[dependencyPolicy]
approvedRegistries = ["crates"]
forbiddenLicenses = ["AGPL-3.0-only", "GPL-3.0-only"]
allowedAdvisories = []
allowPackageScripts = false
allowDuplicateVersions = false
allowUnsupportedPackageForms = false

[extensions.pricing]
language = "rust"
source = "logic/pricing.rs"
exports = ["apply_discount"]
targets = ["web", "server"]
environment = "rust-release"

[extensions.pricing.packages.portable-money]
version = "1.0.0"
registry = "crates"

Replace each placeholder with a real lowercase 64-digit SHA-256; check rejects anything else. The registry URL is illustrative.

Manifest sections

[dependencyEnvironments.<name>]

A named, reproducible compiler and runtime environment. All fields except options are required.

Source builds in CLI 0.149.1 also require:

[dependencyRegistries.<alias>]

The index lists, for each package version, the artifact URL, SHA-256, byte length, dependencies, licenses, advisories and scripts. The alias (for example crates) is only a name; it does not point at a public registry by itself.

[extensions.<alias>.packages.<name>]

The extension must also set environment to a declared environment of the same language. A Rust extension that declares packages fails to build until axiom dependencies resolve has written the lock.

[dependencyPolicy]

Policy is checked offline. Declaring it never installs packages or runs scripts.

Every list in AxiomDeps.toml must be sorted and unique, for example forbiddenLicenses = ["AGPL-3.0-only", "GPL-3.0-only"].

Versions and conflicts

Versions are exact. If two extensions in one compatible environment request different exact versions of the same package, resolution fails and names both extensions. Axiom never picks a winner or creates a second environment by accident. Two extensions that request the same exact version share the verified bytes and keep separate instances, permissions and audit identities.

Supported package forms

Archives with path traversal, unsafe links, the wrong identity, length or digest fail before compilation. Package scripts are recorded for review and never run. Python wheels are parsed, never installed or executed.

Commands

The cache defaults to axiom/dependencies/v1 inside your user cache directory (for example ~/Library/Caches on macOS or ~/.cache on Linux). Pass --cache to use another location.

Resolution modes

axiom dependencies check
axiom dependencies resolve
axiom dependencies resolve --locked
axiom dependencies resolve --offline
axiom dependencies verify
axiom dependencies inspect

Locked and offline modes fail if the lock is missing, for example --offline requires an existing canonical AxiomDeps.lock. Missing or corrupt locked content fails closed; recover it explicitly with axiom dependencies cache recover.

Release review with Inspector

axiom inspect dependencies .
axiom inspect security .
axiom inspect provenance portable-money .
axiom inspect impact portable-money . --against release.snapshot.json
axiom inspect release-check . --enforce

Inspector shows the package graph, environment, compiler or interpreter engine, SDK, ABI, hashes, licenses, advisories, scripts, the extensions that introduce each package, authority consequences, targets, artifacts and releases. Findings have stable rule codes and evidence; there is no opaque security score. See Changes and impact.

Examples

The public examples repository has two resolver cases in axiom-extension-language-samples/dependencies: shared, where two extensions share portable-money@1.0.0, and conflict, where they request 1.0.0 and 2.0.0 in one environment and resolution fails. Their registry URLs are illustrative, not live endpoints.

git clone --depth 1 https://github.com/AxiomCore/examples.git
cd examples/axiom-extension-language-samples/dependencies/shared
axiom dependencies check

Valid AxiomDeps.toml v2: AxiomDeps.toml
Canonical manifest: <sha256>
0 contract(s), 0 Axiom package(s), 2 extension(s), 1 build environment(s).