Boot Artifact Manifest Schema

Schema owner: Boot Artifact Matrix and Manifest Format. Production pipeline owner: Disk Image, USB & Release Artifacts. Bootloader-side verification owner: Artifact Signing and Manifest Verification. Offline inspector owner: Offline Artifact Inspector.

This document is the canonical schema for the boot artifact manifest -- a JSON file every Impossible OS release artifact (raw / USB / VHD / VHDX / VDI / ISO / qcow2 / OVA / recovery / installer) ships alongside. The manifest pins the contents the bootloader must verify at load: file hashes, partition map, ABI version, Secure Boot status, media role, and an artifact UUID. The release-pipeline tooling produces it; the bootloader-side verifier consumes it; the offline inspector round-trips it.

Supported artifact formats

Required fields

The bootloader verifier and packaging gate REJECT manifests missing any of the following top-level fields. Each field maps directly to a check the bootloader performs before kernel jump.

The bootloader_sha256 and kernel_sha256 fields are denormalized so the verifier does not need to walk entries[] for the two most-common-checked artifacts. The packaging gate enforces that they match the corresponding entries[] row before producing the manifest.

Partition Map

Each partition_map[i] object describes one logical partition the bootloader expects. The map's semantics depend on artifact_format:

• GPT-backed disk formats (raw, usb, vhd, vhdx, vdi, qcow2, ova, installer, recovery): partition_map[] carries the full ESP + BlackBox + IXFS layout (3 entries today). Mismatch against the on-disk GPT triggers boot_fatal() under require_manifest=1. The bootloader-side verifier owns the cross-check against the on-disk GPT (it is the only consumer with access to the raw disk at load time); the packaging gate validates structural shape only.
• iso format: partition_map[] carries a single ESP row describing the El Torito UEFI boot image embedded in the ISO9660 volume (the ISO has no GPT at the medium level). Bootloader-side GPT cross-check is skipped for ISO; the verifier instead reads the El Torito boot image's FAT directly. The packaging gate still validates the row's structural shape.

Entries

Each entries[i] object describes one boot-platform-relevant file inside the artifact. Required entries vary by artifact_format:

• All formats: bootloader, kernel (each appears exactly once with optional: false).
• ESP-bearing disk formats (raw, usb, vhd, vhdx, vdi, qcow2, ova, installer, recovery): also boot_config (the ESP boot.conf; both verify-esp.sh --manifest and build-manifest.sh check fail closed when this row is absent for these formats).
• iso: boot_config is recommended but not required at the manifest level (the El Torito UEFI image inside the ISO carries its own boot.conf path; cross-check is owned by §4 Hybrid ISO / El Torito UEFI Boot).

Optional entries (included when the subsystem is shipped): boot_entries, blackbox_skeleton, recovery_payloads.

Failure modes

The packaging gate (scripts/release/build-manifest.sh check <manifest>) is structural-only -- it validates the JSON shape against this schema without access to the build tree. It exits non-zero on any of:

• A required field above is missing from the JSON.
• bootloader_sha256 or kernel_sha256 is empty or not 64 hex chars.
• partition_map[] is empty.
• entries[] is missing the required bootloader or kernel row, or (for ESP-bearing formats) the required boot_config row, or a non-optional row carries an unknown name.
• An enum field (artifact_format, secure_boot_status, media_role, filesystem) carries a value outside its allowed set.
• An integer field falls outside its documented range, or a UUID/GUID field violates its 8-4-4-4-12 form.
• artifact_uuid does not equal the deterministic UUID v5 reconstructed from the on-disk seed (format|bootloader_sha256|kernel_sha256|boot_info_version).
• A cross-field invariant is violated (e.g. artifact_format=installer with media_role!=installer).

Stderr message names the failed field by name, prefixed with [ERROR].

The kernel/bootloader-vs-boot_info_version semantic binding is enforced upstream by build mode, not by check: build refuses to emit a manifest when build/boot-info-abi.kernel.json (the binary-derived ABI mirror produced by tools/boot-info-manifest/dump-kernel) is older than either BOOTX64.EFI or kernel.exe. That staleness assertion ties boot_info_version to the exact artifact pair being hashed at build time. The bootloader-side verifier closes the loop at load time by re-checking the manifest against the running ABI version in boot_info.

Bootloader-side verification

Owned by Artifact Signing and Manifest Verification. When boot.conf:require_manifest=1, the bootloader:

1. Reads \IPOS\manifest.json from the ESP (or /IPOS/manifest.json from an ISO).
2. Verifies the detached signature manifest.json.sig against the release public key.
3. Cross-checks every entries[] sha256 against the on-disk file.
4. Cross-checks partition_map[] against the GPT (GPT-backed formats only; skipped for iso).
5. Populates boot_info.boot_artifact_id and boot_info.boot_manifest_digest from the manifest before kernel jump.

Schema version policy

manifest_version is bumped when:

• A required field is added, removed, or renamed.
• An enum value is added to artifact_format, secure_boot_status, or media_role.
• The semantic meaning of any field changes (e.g. boot_info_version becomes a string).

manifest_version is not bumped when:

• A new optional entries[] row name is added (the verifier skips unknown optional entries).
• A new optional top-level field is added with documented ignore semantics (older v1 consumers that don't recognize the field MUST skip it without erroring; the field carries no required-by-default consumer contract). Examples: toolchain_version, source_sha, manifest_seed, vm_image_metadata. Adding such a field becomes a manifest_version bump only when the new field gains a required-by-default consumer contract.
• Documentation prose is rewritten without changing the on-disk shape.

The bootloader verifier handles manifest_version > 1 by refusing the boot under require_manifest=1 (forward-incompatible). Backward-compatible reads of manifest_version=1 from a manifest_version=2-aware bootloader land via explicit migration code at the bump time.

Example (manifest_version=1, raw image)

{
  "manifest_version": 1,
  "artifact_format": "raw",
  "artifact_uuid": "12345678-1234-4abc-9def-0123456789ab",
  "boot_target": "uefi-x86_64",
  "boot_info_version": 16,
  "secure_boot_status": "unsigned",
  "media_role": "normal",
  "partition_map": [
    { "index": 1, "name": "ESP", "type_guid": "C12A7328-F81F-11D2-BA4B-00A0C93EC93B", "size_mib": 64, "filesystem": "fat32" },
    { "index": 2, "name": "BlackBox", "type_guid": "00000000-0000-0000-0000-000000000000", "size_mib": 128, "filesystem": "fat32" },
    { "index": 3, "name": "IXFS-System", "type_guid": "00000000-0000-0000-0000-000000000000", "size_mib": 4096, "filesystem": "ixfs" }
  ],
  "entries": [
    { "name": "bootloader",  "path": "\\EFI\\BOOT\\BOOTX64.EFI",            "sha256": "<64-hex>", "size_bytes": 124928,  "optional": false },
    { "name": "kernel",      "path": "\\boot\\kernel.exe",                  "sha256": "<64-hex>", "size_bytes": 5242880, "optional": false },
    { "name": "boot_config", "path": "\\EFI\\ImpossibleOS\\boot.conf",      "sha256": "<64-hex>", "size_bytes": 512,     "optional": false }
  ],
  "bootloader_sha256": "<64-hex>",
  "kernel_sha256": "<64-hex>"
}