Purpose

Axis is a system for building and operating immutable Linux-based Operating Systems. It comprises:

axis — development, build, and control tool. The primary developer interface for defining, building, running, testing, deploying, and inspecting Axis Projects. It also acts as a client for connecting to and controlling Devices running Axis-based systems, when authorized.
Base OS — Operating System model and runtime contract. Defines the common immutable system model, boot and filesystem contracts, runtime conventions, update model, and interfaces shared by Axis-based Operating Systems.
axisd — init process and system manager. Runs as PID 1 on an Axis-based Operating System, initializes and manages the running system, supervises its lifecycle and services, and exposes system management interfaces to authorized clients, including axis.

Scope

The Axis specifications define the architecture, interfaces, artifacts, and runtime behavior required to build and operate immutable Linux-based Operating Systems using Axis. The scope of Axis includes:

The axis development, build, deployment, and control tool.
The Project, Target, Dependency, Build, Artifact, Resolution, and caching models used by Axis.
The Base OS and the contracts required to boot, represent, update, and operate an Axis-based Operating System.
axisd, its responsibilities as PID 1 and system manager, and the system management interfaces it exposes to authorized clients.
The interfaces between Hosts, Artifacts, Platforms, Runners, and running Devices.

Terminology and Normative Language

Axis specifications are normative documents. Unless explicitly stated otherwise, definitions, relationships, constraints, and requirements expressed by a Specification form part of the Axis contract.

A Concept is a uniquely defined entity in the Axis specification model. Each Concept has exactly one canonical definition, owned by a single Specification, and may be referenced from any other Specification.

Concept names use canonical capitalization, such as Axis, Operating System, and Base OS. A lowercase use of the same words does not refer to the Concept unless the context unambiguously indicates otherwise.

Concepts whose canonical names are program or command names are written in lowercase monospace, such as axis and axisd.

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY express normative requirements when written in uppercase.

MUST and MUST NOT express requirements necessary for conformance.
SHOULD and SHOULD NOT express recommendations that may be departed from only when there is a valid reason to do so.
MAY expresses behavior that is permitted but not required.

System Model

Axis has two primary responsibilities: producing immutable Operating Systems and operating the Devices that run them.

Projects and Dependencies are resolved and built into immutable Artifacts, including Packages, Operating Systems, Platforms, and Runners. A Platform provides the target-side support required to boot and operate compatible Operating Systems on a class of physical or virtual Devices. A Runner allows axis to operate compatible Devices from a Host, while axisd manages the running Operating System.

A Project is a source-level unit understood by Axis. A Project declares its kind, Dependencies, supported Targets, and the information required to produce its Artifacts.

A Dependency is a declared requirement on another component. Resolution satisfies a Dependency with a compatible Artifact, either by reusing an existing binary Artifact or by obtaining its source and building it.

A Target is a declarative destination context for which a Project is built or prepared. A Target provides the properties required to select compatible Dependencies, Artifacts, and Platforms.

A Build transforms declared inputs into immutable Artifacts. Builds are evaluated only when required, allowing unchanged results to be reused.

An Artifact is an immutable binary value produced, distributed, stored, or consumed by Axis. The principal Artifact kinds are Package, Operating System, Platform, and Runner.


flowchart LR
    Project["Project"] -->|declares| Dependency["Dependency"]
    Project -->|supports| Target["Target"]

    Dependency --> Resolution["Resolution"]
    Resolution -->|resolves to| Artifact["Artifact"]
    Resolution -->|may require| Build["Build"]

    Project --> Build
    Target --> Build
    Build --> Artifact

A Package is a reusable Artifact that may participate in the construction of another Artifact.

An Operating System is the complete immutable system Artifact intended to run with a compatible Platform and conforming to the Base OS.

A Platform provides the target-side components and contracts required to boot and operate compatible Operating Systems on a class of physical or virtual machines.

A Runner provides host-side functionality for operating compatible Platforms. Runners are independent from the Platforms and Operating Systems they operate.

A Host is the environment in which axis executes. A Device is a concrete physical or virtual machine on which an Operating System may run; unlike a Target, a Device exists independently of any Project or Build.


flowchart LR
    Host["Host"] --> Axis["axis"]

    Axis -->|uses| Runner["Runner"]
    Runner -->|operates| Device["Device"]

    Platform["Platform"] -->|supports| Device
    Platform -->|boots and supports| OS["Operating System"]
    Device -->|runs| OS

    OS --> Axisd["axisd"]
    Axis -->|controls| Axisd

    class Axis,Axisd program

axis is the developer-facing interface to both sides of the model. It builds and resolves Projects and Artifacts, and may also interact with Devices running Axis-based Operating Systems independently of any Project or Build context.

axisd runs as part of an Axis-based Operating System and provides runtime management and system interfaces to authorized clients.

The core relationships of the Axis model are:

Projects describe source and build intent.
Dependencies are satisfied through Resolution.
Builds produce immutable Artifacts.
Targets describe declarative destination contexts.
Packages may participate in the construction of larger Artifacts.
Platforms provide the target-side support required to boot and operate compatible Operating Systems.
Runners allow axis to operate Devices from a Host.
Devices are concrete runtime instances and are independent from Projects.
axisd manages an Axis-based Operating System at runtime and exposes system management interfaces to authorized clients.

Fundamental Invariants

The following properties are fundamental to Axis. More specific Specifications may refine these requirements but MUST NOT contradict them.

Artifacts are immutable. Once produced, an Artifact does not change. A different result is a different Artifact.
Projects and Artifacts are distinct. A Project describes how Artifacts may be produced; an Artifact is a concrete immutable result and may exist independently of the Project that produced it.
Builds depend only on declared inputs. A Build MUST NOT depend on undeclared Host state. A Build result may be reused whenever its effective inputs are unchanged.
Dependencies resolve to Artifacts. A Dependency is satisfied by a compatible Artifact regardless of whether that Artifact is obtained as an existing binary or built from source.
OS Artifacts are independent of particular Platforms and Runners. An OS Artifact MUST NOT require modification or repackaging solely because it is used with a different compatible Platform or operated through a different Runner.
Platform-specific support remains outside the OS Artifact. A Platform MAY provide boot and runtime components required to operate an Operating System on its Devices without those components becoming part of the OS Artifact.
Platforms and Runners have separate responsibilities. A Platform provides target-side support required to boot and operate compatible Operating Systems. A Runner provides Host-side functionality for operating compatible Platforms and Devices.
Targets and Devices are distinct. A Target is declarative configuration used to evaluate a Project or Build. A Device is a concrete physical or virtual machine and may exist and be operated independently of any Project or Build context.
The same OS Artifact may be used across compatible environments. Changing how or where an Operating System is booted MUST NOT require rebuilding or repackaging that Operating System when the existing Artifact is compatible.
The OS Artifact is the root filesystem image itself. It MUST NOT be a wrapper or container around a second root filesystem image.
The OS Artifact does not contain the Platform boot environment. Kernels, initramfs images, boot loaders, and other Platform-specific boot components are not part of the OS Artifact.
axisd is PID 1 of the Base OS runtime. Once the OS Artifact has become the root filesystem, execution MUST be transferred to /sbin/axisd as PID 1.

Concept Ownership

Every Concept defined by the Axis specifications has exactly one owning Specification. The owning Specification contains the Concept's canonical definition and is the authoritative source for its meaning.

A Concept MUST be owned by the highest Specification in the specification tree that can define it completely without depending on details delegated to a child Specification.

A child Specification may refine a Concept owned by one of its ancestors by defining more specific behavior, constraints, interfaces, or representations. Such refinements MUST NOT contradict or redefine the Concept established by its owner.

A Specification SHOULD NOT define normative meaning for a Concept owned by another Specification. It may reference that Concept and state requirements concerning its interaction with Concepts that it owns.

When a Concept cannot be defined completely without introducing a separately refinable abstraction, that abstraction SHOULD be defined as a distinct Concept and delegated to an appropriate child Specification.

Changes to the canonical definition of a Concept require review of the Specifications that refine or depend on it.