operations-boot-media

Compiles a declarative TargetSpec into bootable media. Two rootfs sources -- unwrap-and-rewrap an official layered image, or build a minimal system from a mirror -- crossed with the medium it lands on, so a new appliance is a config rather than a fifth build script. Every refusal this crate makes was a real failure first.

Tier	operations
Role	pipeline
Path	`crates/operations/boot-media`
Edition	2021
Targets	rebuild-ir3001, operations_boot_media, artifact, build, plan, write
Public items	19 across 0 modules
Tests	49

What it is for

operations-boot-media — a declarative spec compiled into bootable media.

The ir3001 stick was built by hand twice on 2026-08-18: once, and then again because a single package was missing from the first. A procedure carried out twice by hand is one that should have been a program, so this is that program (rule 14), and every refusal below is a failure that actually happened rather than one that was imagined.

Two rootfs sources, neither privileged:

RootfsSource::RemasterLayered — unwrap an official image's layers, modify, repack.

Inherits the vendor's kernel, firmware and installer, which is what a stick booting unknown hardware needs.

RootfsSource::Debootstrap — build a minimal system from a mirror. Inherits

nothing, which is what a fixed-hardware appliance wants. bootusb has used it four times over.

Crossed with the Medium it lands on, because source and medium are independent — and every hand-written build script in the estate fixes both, which is why there are four of them.

The pure planning here is separated from the subprocess edge on purpose: the decisions are what is worth testing, and they are testable without a disk, a mirror, or an hour.

Capabilities

`crate root`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub const FAT32_MAX_FILE_BYTES: u64`
`fn plan(spec : & TargetSpec) -> Result <BuildPlan, BootMediaError>`
`fn build <S : CommandSink + ? Sized>(plan : & BuildPlan, work_dir : & str, sink : & mut S,) -> Result <(), BootMediaError>`
`fn parse_boot_params(report : & str) -> Vec <String>`
`fn verify_built_rootfs(spec : & TargetSpec, listing : & str) -> Result <(), BootMediaError>`

`BootMediaError`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub enum BootMediaError`

`BuildPlan`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub struct BuildPlan`
`BuildPlan :: fn top_layer_name(& self) -> String`

`BuildStep`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub enum BuildStep`

`CommandSink`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub trait CommandSink`

`DestinationFs`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub enum DestinationFs`
`DestinationFs :: fn can_hold_rootfs(self) -> bool`

`InjectedFile`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub struct InjectedFile`

`Medium`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub enum Medium`

`PackageProof`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub struct PackageProof`
`PackageProof :: fn new(package : & str, proof_path : & str) -> Self`

`RootfsSource`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub enum RootfsSource`

`TargetSpec`

operations-boot-media — a declarative spec compiled into bootable media.

Item
`pub struct TargetSpec`
`fn extraction_order(spec : & TargetSpec) -> Option <Vec <String>>`

How to use it

From `examples/rebuild-ir3001.rs`:


use operations_boot_media::{
    build, plan, verify_built_rootfs, DestinationFs, DriveIdentity, InjectedFile, Medium,
    PackageProof, ProcessSink, RootfsSource, TargetSpec,
};

fn main() {
    let work = std::env::args().nth(1).unwrap_or_else(|| {
        eprintln!("usage: rebuild-ir3001 <work-dir>");
        std::process::exit(2);
    });

    let src = std::env::var("BOOT_MEDIA_SRC_ISO").unwrap_or_else(|_| {
        format!(
            "{}/ir3001-preserve/xubuntu-24.04.4-desktop-amd64.iso",
            std::env::var("HOME").unwrap_or_default()
        )
    });

Module structure

No public modules: the crate root is its whole surface.

Public surface

`crate root`

Item	What it is
`pub enum RootfsSource`	Where a root filesystem comes from.
`pub enum Medium`	What the built filesystem is written onto.
`pub enum DestinationFs`	The filesystem the build's working tree is assembled on
`DestinationFs :: fn can_hold_rootfs(self) -> bool`	Whether a Linux root filesystem can be represented here at all.
`pub struct InjectedFile`	One file placed into the built tree.
`pub struct PackageProof`	A package, and the one path whose presence in the built tree proves it arrived.
`PackageProof :: fn new(package : & str, proof_path : & str) -> Self`	Declare a package and its proof together.
`pub struct TargetSpec`	What to build.
`pub struct BuildPlan`	A validated plan
`BuildPlan :: fn top_layer_name(& self) -> String`	The layer the repack replaces — the top of the stack, which is the live layer
`pub const FAT32_MAX_FILE_BYTES: u64`	FAT32's file-size ceiling: 4 GiB minus one byte
`pub enum BuildStep`	Which stage of the build a failure came from.
`pub trait CommandSink`	Runs one command, given as an argument vector
`pub enum BootMediaError`	Why a spec is not buildable.
`fn plan(spec : & TargetSpec) -> Result <BuildPlan, BootMediaError>`	Validate a spec into a `BuildPlan`, or say precisely why it cannot be built
`fn build <S : CommandSink + ? Sized>(plan : & BuildPlan, work_dir : & str, sink : & mut S,) -> Result <(), BootMediaError>`	Execute a validated plan, issuing one command per step through `sink`
`fn parse_boot_params(report : & str) -> Vec <String>`	Turn `xorriso -indev <image> -report_el_torito as_mkisofs` output into argv elements
`fn extraction_order(spec : & TargetSpec) -> Option <Vec <String>>`	The order layers must be extracted in, or `None` when the source has no layers
`fn verify_built_rootfs(spec : & TargetSpec, listing : & str) -> Result <(), BootMediaError>`	Check that the rootfs the build produced contains what the spec promised

Re-exports. Exported here, defined elsewhere.

Export	Defined in
`ProcessSink`	`exec::ProcessSink`
`{DriveIdentity,IdentityError,IR_PORT_RANGE}`	`identity::{DriveIdentity,IdentityError,IR_PORT_RANGE}`
`{plan_drive_write,DriveWriteError,DriveWriteSpec}`	`write::{plan_drive_write,DriveWriteError,DriveWriteSpec}`

Boundary

Reaches into foundation.

Shares tier operations with 40 other crates: operations-approval-workflow, operations-assessments, operations-block-imaging, operations-browser-agent-worker, operations-camera-discovery, operations-camera-liveview, operations-camera-registry, operations-compliance, … (40 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`operations`
Architectural role (taxonomy)	`pipeline`
Location	`crates/operations/boot-media`
Vocabulary in force (lexicon)	`current`

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_operations["operations"] --> n_foundation["foundation"]

Dependencies

Runtime, in this workspace.

Crate	Tier	Optional	Only on
`foundation-bounded-io`	foundation	no	always
`operations-device-safety`	operations	no	always

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`thiserror`	`^2`	—	no	always

Development. None.

Build. None.

Depended on by. Nothing in this workspace.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  SELF["operations-boot-media"]
  SELF -->|runtime| n_foundation_bounded_io["foundation-bounded-io"]
  SELF -->|runtime| n_operations_device_safety["operations-device-safety"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
example	`rebuild-ir3001`	`examples/rebuild-ir3001.rs`
lib	`operations_boot_media`	`src/lib.rs`
test	`artifact`	`tests/artifact.rs`
test	`build`	`tests/build.rs`
test	`plan`	`tests/plan.rs`
test	`write`	`tests/write.rs`

Error model

Error type	Named by
`BootMediaError`	`build`, `plan`, `verify_built_rootfs`

Operational characteristics

Property	Evidence
async public surface	none detected
async runtime	none detected
database access	none detected
network I/O	none detected
unsafe code	none detected
environment variables	none detected

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

No workspace crate depends on this one.

Verification

Kind	Count
Unit tests	7
Integration tests	42
Examples	1
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Examples	Consumers
`crate root`	16	12	0

What the tests establish, by name:

a_near_miss_path_does_not_count_as_the_server — tests/artifact.rs
a_promised_server_that_is_not_in_the_built_image_is_refused — tests/artifact.rs
a_spec_that_promises_nothing_remote_needs_no_server_in_the_artifact — tests/artifact.rs
a_unit_enabled_in_the_wants_directory_passes — tests/artifact.rs
a_unit_file_that_merely_exists_is_not_an_enabled_unit — tests/artifact.rs
a_unit_that_is_never_enabled_is_refused_by_the_artifact_check — tests/artifact.rs
an_authorized_keys_present_in_the_tree_passes — tests/artifact.rs
an_authorized_keys_that_never_landed_in_the_tree_is_refused — tests/artifact.rs
an_empty_listing_is_a_refusal_and_never_a_pass — tests/artifact.rs
the_same_image_with_sshd_present_passes — tests/artifact.rs
a_refused_plan_issues_no_commands_at_all — tests/build.rs
a_step_that_fails_stops_the_sequence_rather_than_carrying_on — tests/build.rs
a_usb_medium_builds_a_writable_stick_whose_image_can_be_replaced — tests/build.rs
every_command_is_an_argv_never_a_shell_string — tests/build.rs
injected_files_land_in_the_tree_before_it_is_repacked — tests/build.rs
package_lists_are_refreshed_before_anything_is_installed — tests/build.rs
packages_are_installed_then_repacked_then_the_medium_is_written — tests/build.rs
the_chroot_is_prepared_before_apt_runs_and_torn_down_after — tests/build.rs
the_layers_are_extracted_in_declared_order_before_anything_else_happens — tests/build.rs
the_medium_tree_is_staged_from_the_source_image_before_it_is_packed — tests/build.rs
the_packages_asked_for_actually_appear_in_the_install_command — tests/build.rs
a_bootable_medium_without_boot_parameters_is_refused — tests/plan.rs
a_build_filesystem_that_cannot_hold_a_rootfs_is_refused_before_anything_is_extracted — tests/plan.rs
a_drive_that_starts_a_server_and_authorizes_nobody_is_refused — tests/plan.rs
a_drive_that_starts_no_server_owes_no_key — tests/plan.rs
a_layer_too_large_for_the_stick_filesystem_is_refused_before_the_build — tests/plan.rs
a_layered_source_with_no_layers_is_refused_rather_than_producing_an_empty_rootfs — tests/plan.rs
a_minimal_build_needs_no_layers_and_says_so — tests/plan.rs
a_remaster_onto_a_hybrid_iso_is_a_legal_plan — tests/plan.rs
a_remote_access_medium_must_carry_the_server_that_serves_it — tests/plan.rs
_… 19 more_

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	19	19
Public modules with a `//!` block	0	0

pie showData
    title Public items with rustdoc
    "Documented" : 19
    "No rustdoc detected" : 0

Metrics

Metric	Value
Rust source files	4
Source lines	1382
Code lines	920
Public API items	19
Public modules	0
Tests	49
Examples	1
Cargo features	0
Direct runtime dependencies	3
Workspace reverse dependencies	0

pie showData
    title Public API by kind
    "constant" : 1
    "enum" : 5
    "function" : 5
    "method" : 3
    "struct" : 4
    "trait" : 1

pie showData
    title Rust source composition
    "Code" : 920
    "Blank or comment" : 462

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

What it is for

Capabilities

crate root

BootMediaError

BuildPlan

BuildStep

CommandSink

DestinationFs

InjectedFile

Medium

PackageProof

RootfsSource

TargetSpec

How to use it

Module structure

Public surface

Boundary

Where it sits

Dependencies

Feature flags

Targets

Error model

Operational characteristics

Configuration

Related capabilities

Verification

Documentation coverage

Metrics

Generation

`crate root`

`BootMediaError`

`BuildPlan`

`BuildStep`

`CommandSink`

`DestinationFs`

`InjectedFile`

`Medium`

`PackageProof`

`RootfsSource`

`TargetSpec`