Partition supervisor contract

The partitions.<name>.init field in build.yaml lets a workload supply a custom partition init in place of the default pid1. Most workloads should keep the default. Replace it only when a flight-software framework, certification package, or partner bus integration already owns in-partition supervision.

The replacement boundary is limited to in-partition supervision. It does not provide a plugin API for host-side runner control.

Responsibilities

A custom partition init is responsible for the work that pid1 normally does inside the guest:

Responsibility	Contract
Boot input	Read the partition storage structures supplied by the host.
Service lifecycle	Start declared services in dependency order and report lifecycle state.
Health	Run the service healthchecks declared in build.yaml.
Relay access	Emit and receive Space_wire.Msg frames on the partition relay path.
State	Preserve parameter and event records using the space-wire codecs below.

The host still owns image admission, target signing, runner policy, and deployment state. A custom init does not get authority to admit new images or mutate the deploy record.

Wire codecs

The wire package is space-wire. A custom init uses these modules:

Module	Purpose
Space_wire.Msg	Fixed-size frame codec used for telemetry, telecommand, event, parameter, data-product, health, log, and error frames.
Space_wire.Superblock	Block-device header with magic, CRC, tenant id, total block count, and data-product region.
Space_wire.Param_entry	Parameter-store entry with parameter id, generation, value bytes, and CRC.
Space_wire.Event_log	Event-log record with timestamp, severity, event code, payload, and CRC.
Space_wire.Shared_mem	Shared-memory page accessors for heartbeat, mission time, health string, and host command acknowledgement. A custom init owns the guest half of this supervision page; the host half belongs to space-runner, which holds safe-mode authority.
Space_wire.Dp_payload	Data-product notification payload with block location, class, priority, name, and CRC.
Space_wire.Error_payload	Structured error-frame payload.

Use these module names exactly. Undocumented module names and host-side helper APIs are not part of the contract.

Minimal frame loop

A minimal frame loop reads and writes Space_wire.Msg values:

let read_msg reader =
  let data = Eio.Buf_read.take Space_wire.Msg.frame_size reader in
  Space_wire.Msg.decode (Bytes.of_string data) 0

let write_msg flow frame =
  let buf = Bytes.make Space_wire.Msg.frame_size '\x00' in
  Wire.Codec.encode Space_wire.Msg.codec frame buf 0;
  Eio.Flow.copy_string (Bytes.unsafe_to_string buf) flow

A real init also needs to decode its boot storage, spawn services, enforce the APID policy handed to it by the image, and publish lifecycle and health state. Those operations remain implementation details of the init package and do not form a host RPC interface.

Service plan

Service declarations in build.yaml include name, image or artifact, runtime, default isolation, optional CPU and memory defaults, interfaces, lifecycle, config, dependencies, and healthcheck.

Runtime placement comes from run.yaml: memory, APIDs, relay topology, ground endpoint, and per-service isolation / CPU / bridge overrides.

The concrete isolation values accepted by the parser are:

auto, runc, spt, hvt, firecracker, qemu, host

Each backend requires matching host features and target-profile support.

Partition-init authority

A custom init cannot control the host-side runner, acquire new deployment authority at runtime, or add a service through a live API. It does not require a debug shell or sidecar agent. Customer licensing, marketplace policy, and scheduler admission remain host responsibilities. A target that needs custom admission or host policy requires a target integration rather than a custom init feature.