//! Per-device measured capability.
//!
//! The same struct is the scheduler's routing input and the appraisal
//! report's payload. Every field is *measured on this card during this
//! probe run*; none is looked up from a SKU table. A card with no
//! recognizable identity is appraised on its probes alone.

/// A numeric regime the device executes matrix or vector ops in.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum Precision {
    Fp32,
    Tf32,
    Fp16,
    Bf16,
    Fp8E4M3,
    Fp8E5M2,
    Int8,
    Int4,
}

/// Sustained throughput at one precision, after thermal steady state.
/// Peak / burst numbers do not belong here.
#[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
pub struct PrecisionThroughput {
    pub precision: Precision,
    /// Tera-ops per second observed during the probe window.
    pub tops: f64,
    /// True if the figure came from the device's matrix engine (tensor
    /// cores, MFMA, AMX, ANE, Vulkan cooperative-matrix). False means
    /// vector ALUs only — the honest fallback when no matrix path was
    /// reachable.
    pub matrix_engine: bool,
}

/// Memory subsystem capability.
#[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
pub struct Memory {
    /// Bytes physically present on the device.
    pub physical_bytes: u64,
    /// Bytes the runtime can actually allocate after driver and OS
    /// reservation and a fragmentation budget. This is the figure the
    /// scheduler routes on.
    pub usable_bytes: u64,
    pub bandwidth_read_bps: f64,
    pub bandwidth_write_bps: f64,
    /// Errors observed during the integrity probe — ECC-reported on
    /// cards that expose ECC, memtest-detected otherwise.
    pub errors_observed: u64,
}

/// Bandwidth to host and to peer devices.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Interconnect {
    /// Measured host bandwidth (PCIe) in bytes/sec.
    pub host_bps: f64,
    /// Full pairwise peer measurements, directed. One entry per ordered
    /// pair (this -> peer). Empty when no peer was reachable. Link kind
    /// is deliberately not recorded; that would be classification, and
    /// the report stays purely measured.
    pub peers: Vec<PeerLink>,
}

/// One directed peer-bandwidth measurement.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct PeerLink {
    /// Bus address of the peer device. Identity only; not interpreted.
    pub peer_bus_address: String,
    /// Sustained bandwidth in bytes/sec from this device to the peer.
    pub bps: f64,
}

/// Cost of issuing work to the device.
#[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
pub struct LaunchOverhead {
    pub null_launch_ns: f64,
    pub memcpy_1mib_ns: f64,
}

/// Thermal envelope under sustained matrix-engine load.
#[derive(Clone, Copy, Debug, serde::Serialize, serde::Deserialize)]
pub struct ThermalEnvelope {
    /// Seconds from cold start to the first observed clock throttle.
    /// `None` means the probe ran to completion without throttling at
    /// its load level.
    pub time_to_throttle_s: Option<f64>,
    /// Throttled sustained throughput as a fraction of cold throughput
    /// at the same precision. `1.0` means no observable thermal derate.
    pub throttled_ratio: f64,
    pub sustained_power_w: f64,
}

/// Identity bound into the signed report for anti-fraud only.
///
/// These fields anchor "this is the same physical card across time."
/// They are never input to scoring or routing. No SKU table is consulted.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct DeviceIdentity {
    pub bus_address: String,
    /// Vendor:device:subsystem IDs joined with ':'. Informational.
    pub pci_ids: String,
    /// VBIOS / firmware hash where readable.
    pub vbios_hash: Option<[u8; 32]>,
    /// Manufacturer serial where exposed. Many consumer cards omit it.
    pub serial: Option<String>,
}

/// Conditions under which a probe was run.
///
/// Two reports are only directly comparable if their environments agree
/// — driver version and ambient temperature both move the numbers.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct ProbeEnvironment {
    pub driver_version: String,
    pub ambient_c: f32,
    pub duration_s: f64,
    pub probe_version: String,
}

/// Per-device measured capability. Scheduler input and report payload.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct CapabilityVector {
    pub identity: DeviceIdentity,
    pub environment: ProbeEnvironment,
    pub throughput: Vec<PrecisionThroughput>,
    pub memory: Memory,
    pub interconnect: Interconnect,
    pub launch: LaunchOverhead,
    pub thermal: ThermalEnvelope,
}

/// Signed envelope for one card's appraisal report.
///
/// The unit of transfer. Each card gets one of these; a fleet is a
/// directory of them plus the box report they all reference.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct CardReport {
    pub payload: CardReportPayload,
    pub signature: Signature,
}

/// The payload signed inside a `CardReport`.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct CardReportPayload {
    /// Format version of the envelope itself. Currently "1".
    pub report_version: String,
    /// RFC 3339 timestamp at probe start.
    pub probed_at: String,
    /// Hex-encoded SHA-256 of the canonical box-report payload bytes.
    /// Links this card report to the topology context it was measured in.
    pub box_report: String,
    pub capability: CapabilityVector,
}

/// Signed envelope for a probe run's box-level context.
///
/// The box report carries the topology the cards were measured in.
/// Card reports reference it by content hash, so anomalies in peer
/// measurements can be traced back to the run that produced them.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct BoxReport {
    pub payload: BoxReportPayload,
    pub signature: Signature,
}

/// The payload signed inside a `BoxReport`.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct BoxReportPayload {
    pub report_version: String,
    pub probed_at: String,
    pub host: HostIdentity,
    /// Bus addresses of every device present at probe time. Lets peer
    /// references in card reports resolve to something concrete.
    pub present_devices: Vec<String>,
    /// Per-device driver version bound at probe time.
    pub driver_versions: Vec<DriverBinding>,
    pub ambient_c: f32,
    pub probe_suite_version: String,
}

/// Identity of the host the probe ran on. Metadata only; never input
/// to scoring.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct HostIdentity {
    pub hostname: String,
    /// DMI / SMBIOS system identifier where available.
    pub dmi_string: Option<String>,
    /// CPU model string. Informational; not looked up.
    pub cpu_model: String,
}

/// Driver version bound to one device at probe time.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct DriverBinding {
    pub bus_address: String,
    pub driver_version: String,
}

/// Per-tenant Ed25519 signature over a canonical payload encoding.
///
/// The canonical encoding rule (stable key order, UTF-8, no
/// insignificant whitespace) lives with the writer/verifier code, not
/// in this schema crate.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
pub struct Signature {
    /// Algorithm identifier. Currently "ed25519".
    pub alg: String,
    /// Operator-chosen identity string for the signing key.
    pub tenant_identity: String,
    /// Base64-encoded Ed25519 public key.
    pub tenant_pubkey: String,
    /// Base64-encoded signature over the canonical payload bytes.
    pub sig: String,
}