// 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")
}