feat: first-draft preview-capable zosstorage

- CLI: add topology selection (-t/--topology), preview flags (--show/--report), and removable policy override (--allow-removable) (src/cli/args.rs)
- Config: built-in sensible defaults; deterministic overlays for logging, fstab, removable, topology (src/config/loader.rs)
- Device: discovery via /proc + /sys with include/exclude regex and removable policy (src/device/discovery.rs)
- Idempotency: detection via blkid; safe emptiness checks (src/idempotency/mod.rs)
- Partition: topology-driven planning (Single, DualIndependent, BtrfsRaid1, SsdHddBcachefs) (src/partition/plan.rs)
- FS: planning + creation (mkfs.vfat, mkfs.btrfs, bcachefs format) and UUID capture via blkid (src/fs/plan.rs)
- Orchestrator: pre-flight with preview JSON (disks, partition_plan, filesystems_planned, mount scheme). Skips emptiness in preview; supports stdout+file (src/orchestrator/run.rs)
- Util/Logging/Types/Errors: process execution, tracing, shared types (src/util/mod.rs, src/logging/mod.rs, src/types.rs, src/errors.rs)
- Docs: add README with exhaustive usage and preview JSON shape (README.md)

Builds and unit tests pass: discovery, util, idempotency helpers, and fs parser tests.

src/report/state.rs

@@ -0,0 +1,80 @@
+// REGION: API
+// api: report::REPORT_VERSION: &str
+// api: report::StateReport { version: String, timestamp: String, status: String, disks: Vec<serde_json::Value>, partitions: Vec<serde_json::Value>, filesystems: Vec<serde_json::Value>, mounts: Vec<serde_json::Value>, error: Option<String> }
+// api: report::build_report(disks: &[serde_json::Value], parts: &[serde_json::Value], fs: &[serde_json::Value], mounts: &[serde_json::Value], status: &str) -> StateReport
+// api: report::write_report(report: &StateReport, path: &str) -> crate::Result<()>
+// REGION: API-END
+//
+// REGION: RESPONSIBILITIES
+// - Construct and persist a machine-readable JSON describing the provisioning outcome.
+// - Maintain a versioned schema via REPORT_VERSION and ensure forward compatibility guidance.
+// Non-goals: orchestrating actions or mutating system state beyond writing the report file.
+// REGION: RESPONSIBILITIES-END
+//
+// REGION: EXTENSION_POINTS
+// ext: add typed sub-structures for disks/partitions/filesystems/mounts when schema stabilizes.
+// ext: emit an additional compact/summary report for boot logs.
+// REGION: EXTENSION_POINTS-END
+//
+// REGION: SAFETY
+// safety: write atomically (tempfile + rename) to avoid partial report reads.
+// REGION: SAFETY-END
+//
+// REGION: ERROR_MAPPING
+// errmap: IO/serialization errors -> crate::Error::Report with clear path/context.
+// REGION: ERROR_MAPPING-END
+//
+// REGION: TODO
+// todo: implement atomic write using tempfile and fs::rename.
+// todo: include monotonic timestamps or sequence numbers if required.
+// REGION: TODO-END
+//! Machine-readable state reporting for zosstorage.
+//!
+//! Emits a JSON report describing discovered disks, partitions, filesystems,
+//! mounts, overall status, and timestamp. The schema is versioned.
+
+use crate::Result;
+use serde::{Deserialize, Serialize};
+
+/// Report payload version string.
+pub const REPORT_VERSION: &str = "v1";
+
+/// State report structure (versioned).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StateReport {
+    /// Payload version (e.g., "v1").
+    pub version: String,
+    /// RFC3339 timestamp.
+    pub timestamp: String,
+    /// "success" | "already_provisioned" | "error"
+    pub status: String,
+    /// Disks (shape defined by implementation; kept flexible for now).
+    pub disks: Vec<serde_json::Value>,
+    /// Partitions (shape defined by implementation; kept flexible for now).
+    pub partitions: Vec<serde_json::Value>,
+    /// Filesystems (shape defined by implementation; kept flexible for now).
+    pub filesystems: Vec<serde_json::Value>,
+    /// Mounts (shape defined by implementation; kept flexible for now).
+    pub mounts: Vec<serde_json::Value>,
+    /// Optional error message when status == "error".
+    pub error: Option<String>,
+}
+
+/// Build the machine-readable state report from inputs.
+///
+/// The concrete shapes for disks/partitions/filesystems/mounts are intentionally
+/// flexible (serde_json::Value) in this skeleton and will be formalized later.
+pub fn build_report(
+    _disks: &[serde_json::Value],
+    _parts: &[serde_json::Value],
+    _fs: &[serde_json::Value],
+    _mounts: &[serde_json::Value],
+    _status: &str,
+) -> StateReport {
+    todo!("assemble structured report in v1 format with timestamp and inputs")
+}
+
+/// Write the state report JSON to disk (default path in config: /run/zosstorage/state.json).
+pub fn write_report(_report: &StateReport, _path: &str) -> Result<()> {
+    todo!("serialize to JSON and persist atomically via tempfile and rename")
+}