Purpose

This Specification defines an OS Artifact, the immutable filesystem image containing an Operating System's userspace and used directly as the root filesystem of the Base OS runtime.

This Specification defines the representation, required contents, filesystem properties, Platform independence, compatibility relationship, and identity of an OS Artifact.

Scope

This Specification defines the binary representation of an OS Artifact, the files and components it may contain, its relationship to Platforms and Runners, and the requirement that the same Artifact may be used without transformation across compatible environments.

This Specification does not define how an OSArtifact is built, resolved, distributed, installed, discovered, verified, physically stored, selected for Boot, or made accessible to the Platform boot environment. Those behaviors are defined by the applicable Build, Platform, Boot, and update Specifications.

Representation

An OS Artifact is exactly one EROFS filesystem image. The bytes of the Artifact are the bytes of the EROFS filesystem itself.

An OS Artifact MUST NOT be an archive, package, disk image, partition image, container, or wrapper containing another root filesystem image.

The conventional filename extension for an OS Artifact is .os. The filename and extension are not part of the Artifact's identity.


flowchart LR
    Artifact["system.os"] --- EROFS["EROFS filesystem"]
    EROFS -->|becomes| Root["Base OS /"]

    class Artifact,Root program

An OS Artifact contains the complete immutable userspace filesystem required to initialize and operate the Base OS once Platform-specific boot has established the Artifact as the root filesystem.

The Artifact MUST contain /sbin/axisd, which becomes PID 1 when the Platform boot environment transfers execution to the Base OS runtime.

The Artifact MAY contain Packages, configuration, libraries, executables, firmware intended for userspace consumption, and other immutable files required by the Operating System.

The Artifact MUST NOT contain the kernel, an initramfs, a boot loader, a partition table, Platform-specific boot assets, or a Runner.

Filesystem Properties

The EROFS filesystem represented by an OS Artifact is immutable and MUST be used read-only as the root filesystem of the Base OS runtime.

The Artifact MUST NOT require modification before a compatible Platform can use it as the root filesystem.

Files whose contents are expected to change during normal system operation MUST NOT require modification of the OS Artifact.

Platform Independence

An OS Artifact is built independently of any particular Platform and MUST NOT require modification or repackaging for use with a compatible Platform.

The same byte-for-byte OS Artifact MAY be used by multiple compatible Platforms and Devices.

A Platform MAY provide Platform-specific components required to boot or operate the Operating System on its Devices. Such components are not part of the OS Artifact.

Platform-specific boot components, kernel components, firmware, kernel modules, userspace services, and other Platform-specific runtime support MUST NOT be embedded into the OS Artifact solely to support a particular Platform.

The use of Platform-specific support does not alter the identity or bytes of the OS Artifact.

Compatibility

An OS Artifact may only be used with a Platform compatible with that Artifact.

Compatibility determines whether a Platform can provide the boot and runtime environment required by an OS Artifact without modifying or repackaging that Artifact.

The criteria and matching rules used to determine compatibility between OS Artifacts and Platforms are defined by the Platform Compatibility Specification.

Identity

An OS Artifact is an immutable Artifact. Any change to its filesystem bytes produces a different Artifact.

Artifact identity, derivation identity, integrity metadata, signatures, and publication metadata are defined by the applicable Artifact and Build Specifications and are not encoded by wrapping or modifying the EROFS image.

Conformance

An Artifact conforms to this Specification when it is a valid EROFS filesystem image, satisfies the required Base OS filesystem contents, contains /sbin/axisd, and can be used without transformation as the Base OS root filesystem by a compatible Platform.