zosstorage/PROMPT.md

You are GPT-5 Codex paired with KILO coder. Produce only what is requested. Do not improvise.

Objective
- Implement `zosstorage`, a Rust binary compiled for static `musl`, embedded in an Alpine Linux initramfs (x86_64 only).
- Purpose: one-shot disk initializer invoked during the first boot of a fresh node. Idempotent; if rerun on a system already provisioned, it must perform no changes and exit success.
- Absolutely never destroy, overwrite, or repartition devices containing existing data. Development/testing uses pristine virtual disks only. Abort immediately if a target device is not empty.

Execution Context
- Runs inside initramfs on Alpine Linux (busybox environment). No reliance on system services or long-running daemons.
- No Cargo.toml manual edits; dependencies managed via `cargo add`. All code must compile with stable Rust toolchains available in the build system.
- Avoid stdout spam. Implement structured logging/tracing (details TBD) but no stray `println!`.

Development Methodology
- Compartmentalize the codebase into clear modules from the outset.
- Begin by proposing the repository layout (directories, modules, tests, docs).
- Define public APIs first: traits, structs, enums, function signatures, and associated documentation comments.
- Only after obtaining approval on the API surface may you proceed to fill in function bodies.
- Use `todo!()` or explanatory comments as temporary placeholders until behavior is agreed upon.
- Preserve this iterative approach for every major module: outline first, implementation after review.

Device Discovery
- Enumerate candidate block devices under `/dev` and filter out all pseudodevices (`/dev/ram*`, `/dev/zram*`, `/dev/fd*`, `/dev/loop*`, etc.). The filtering rules must be configurable for future allowlists (e.g., removable media).
- Default device classes include `/dev/sd*`, `/dev/nvme*`, `/dev/vd*`. If no eligible disks are found, return a well-defined error.

Partitioning Requirements
- Use GPT exclusively. Honor 1 MiB alignment boundaries.
- For BIOS compatibility on BIOS systems, create a small `bios_boot` partition (size 1 MiB, placed first). When running under UEFI (`/sys/firmware/efi` present), the BIOS boot partition is suppressed.
- Create a 512 MiB FAT32 ESP on each disk, label `ZOSBOOT`. Each ESP is independent; synchronization will be handled by another tool (out of scope). Ensure unique partition UUIDs while keeping identical labels.
- Remaining disk capacity is provisioned per configuration (see below).
- Before making changes, verify the device has no existing partitions or filesystem signatures; abort otherwise.

Filesystem Provisioning
- Mount scheme and subvolumes:
  * Root mounts for each data filesystem at `/var/mounts/{UUID}` (runtime only). For btrfs root, use `-o subvolid=5`; for bcachefs root, no subdir option.
  * Create or ensure subvolumes on the primary data filesystem with names: `system`, `etc`, `modules`, `vm-meta`.
  * Mount subvolumes to final targets:
    - `/var/cache/system`
    - `/var/cache/etc`
    - `/var/cache/modules`
    - `/var/cache/vm-meta`
  * Use UUID= sources for all mounts (never device paths).
  * Subvolume options:
    - btrfs: `-o subvol={name},noatime`
    - bcachefs: `-o X-mount.subdir={name},noatime`
- Supported backends:
  * Single disk: default to `btrfs`, label `ZOSDATA`.
  * Two disks/NVMe (dual_independent): default to independent `btrfs` per disk, each labeled `ZOSDATA`; root-mount all under `/var/mounts/{UUID}`, pick the first data FS as primary for final subvol mounts.
  * Mixed SSD/NVMe + HDD: default to `bcachefs` with SSD as cache/promote and HDD as backing store, resulting FS labeled `ZOSDATA`. Alternative mode: separate `btrfs` per device (label `ZOSDATA`).
- Reserved filesystem labels: `ZOSBOOT` (ESP), `ZOSDATA` (all data filesystems). GPT partition names: `zosboot` (bios_boot and ESP), `zosdata` (data), `zoscache` (cache).
- Filesystem tuning options (compression, RAID profile, etc.) must be configurable; define sensible defaults and provide extension points.

Configuration Input
- Accept configuration via:
  * Kernel command line parameter `zosstorage.config=` pointing to a YAML configuration descriptor.
  * Optional CLI flags when run in user space (mirror kernel cmdline semantics).
  * On-disk YAML config file (default path `/etc/zosstorage/config.yaml`).
- Precedence: kernel cmdline overrides CLI arguments, which override config file, which override built-in defaults. No interactive prompts inside initramfs.
- YAML schema must describe disk selection rules, desired filesystem layout, boot partition preferences, filesystem options, mount targets, and logging verbosity. See [docs/SCHEMA.md](docs/SCHEMA.md) and [src/types.rs](src/types.rs:1).

State Reporting
- After successful provisioning, emit a JSON state report (path TBD, e.g., `/run/zosstorage/state.json`) capturing:
  * Enumerated disks and their roles,
  * Created partitions with identifiers,
  * Filesystems, labels (`ZOSBOOT`, `ZOSDATA`, `ZOSCACHE`), mountpoints,
  * Overall status and timestamp.
- Ensure the report is machine-readable and versioned.

Logging
- Integrate a structured logging/tracing backend (e.g., `tracing` crate). Provide log levels (error, warn, info, debug) and allow configuration through CLI/config/cmdline.
- By default, logs go to stderr; design for optional redirection to a file (path TBD). Avoid using `println!`.

System Integration
- `/etc/fstab` generation: optional via CLI/config. When enabled, write only the four final subvolume/subdir mount entries (system, etc, modules, vm-meta) with `UUID=` sources in deterministic order. Root mounts under `/var/mounts/{UUID}` are runtime-only and excluded from fstab.
- After provisioning, ensure the initramfs can mount the new filesystems (e.g., call `udevadm settle` if necessary). No external services are invoked.
- No responsibility for updating `vmlinuz.efi`; another subsystem handles kernel updates.

Failure Handling
- If any target disk fails validation (non-empty, filtered out, or errors occur), abort the entire run with a descriptive error message. Provide a `--force` flag stub for future use, but keep it non-functional for now (must return “unimplemented”).

Testing & Validation (initial expectations)
- Provide integration test scaffolding targeting QEMU/KVM scenarios (e.g., single virtio disk 40 GiB, dual NVMe 40 GiB each, SSD+HDD mix). Tests can be smoke-level initially but must compile.
- Document manual testing steps for developers to reproduce in VMs.
- VM test matrix using virtio disks (/dev/vd?) to validate topologies:
  * 1 disk (/dev/vda): single topology → create btrfs on the data partition labeled ZOSDATA.
  * 2 disks (/dev/vda, /dev/vdb):
    - dual_independent: btrfs per disk (two independent ZOSDATA filesystems).
    - bcachefs cache/backing: treat /dev/vda as cache (SSD-like) and /dev/vdb as backing (HDD-like); create one bcachefs labeled ZOSDATA.
    - btrfs_raid1: mirrored btrfs across the two data partitions labeled ZOSDATA.
  * 3 disks (/dev/vda, /dev/vdb, /dev/vdc):
    - bcachefs: cache on /dev/vda; backing on /dev/vdb and /dev/vdc with two replicas (two copies), labeled ZOSDATA.
- Ensure device discovery includes /dev/vd* by default and filters pseudodevices.
Documentation & Deliverables
- Produce comprehensive README including: overview, prerequisites, configuration schema, example YAML, command-line usage, JSON report format, filesystem label semantics (`ZOSBOOT`, `ZOSDATA`, `ZOSCACHE`), limitations, and roadmap.
- Ensure Rust code contains module-level and public API documentation (/// doc comments). Implement `--help` output mirroring README usage.
- Include architectural notes describing module boundaries (device discovery, partitioning, filesystem provisioning, config parsing, logging, reporting).

Open Items (call out explicitly)
- BIOS vs UEFI: `bios_boot` partition size fixed at 1 MiB and created only on BIOS systems; suppressed under UEFI (`/sys/firmware/efi` present).
- Mount scheme finalized:
  - Root mounts for each data filesystem at `/var/mounts/{UUID}` (runtime only).
  - Final subvolume/subdir mounts from the primary data filesystem to `/var/cache/{system,etc,modules,vm-meta}`.
- Filesystem-specific tuning parameters (compression, RAID values, `bcachefs` options) remain open for refinement; sensible defaults applied.
- Config paths and keys stabilized:
  - Kernel cmdline key: `zosstorage.config=`
  - Default config file: `/etc/zosstorage/config.yaml`
  - Default report path: `/run/zosstorage/state.json`
  - Optional log file: `/run/zosstorage/zosstorage.log`
- `/etc/fstab` generation policy decided: optional flag; writes only the four final subvolume/subdir entries.

Implementation Constraints
- Stick to clear module boundaries. Provide unit tests where possible (e.g., config parsing, device filtering).
- Maintain strict idempotency: detect when provisioning already occurred (e.g., presence of `ZOSBOOT` partitions and expected filesystem labels `ZOSDATA`/`ZOSCACHE`) and exit gracefully.
- Write clean, production-quality Rust adhering to idiomatic practices and Clippy.

Deliverables
- Repository layout proposal (src modules, tests directory, docs). Highlight major components and their responsibilities.
- API skeletons (traits, structs, function signatures) with doc comments, using `todo!()` placeholders for bodies until approved.
- After API approval, progressively fill in implementations, preserving the compartmentalized structure and documenting assumptions.