alma 0.1.1

//! Workspace I/O execution reports and guest projections.

use super::{PluginWorkspaceReadError, PluginWorkspaceWriteError, WorkspaceAccessKind};
use crate::{
    fs_utils::EscapedDisplayText,
    plugin::{PluginIdentity, WorkspacePath, WorkspacePathRef},
};
use std::fmt::{Debug, Display, Formatter};

/// Report from executing sealed workspace I/O through filesystem policy.
#[derive(Debug)]
pub struct PluginWorkspaceIoReport {
    /// Stable plugin identity for diagnostics.
    identity: PluginIdentity,
    /// Ordered request completions.
    completions: Vec<PluginWorkspaceIoCompletion>,
}

impl PluginWorkspaceIoReport {
    /// Creates an execution report.
    pub(super) const fn new(
        identity: PluginIdentity,
        completions: Vec<PluginWorkspaceIoCompletion>,
    ) -> Self {
        Self {
            identity,
            completions,
        }
    }

    /// Returns the plugin identity for display and serialization.
    #[must_use]
    pub fn identity(&self) -> &str {
        self.identity_proof().as_str()
    }

    /// Returns the validated identity retained by the execution report.
    #[must_use]
    pub const fn identity_proof(&self) -> &PluginIdentity {
        &self.identity
    }

    /// Returns ordered workspace I/O completions.
    #[must_use]
    pub fn completions(&self) -> &[PluginWorkspaceIoCompletion] {
        &self.completions
    }
}

/// One completed workspace I/O request.
pub enum PluginWorkspaceIoCompletion {
    /// Completed workspace read.
    Read(PluginWorkspaceReadCompletion),
    /// Completed workspace write.
    Write(PluginWorkspaceWriteCompletion),
}

impl PluginWorkspaceIoCompletion {
    /// Returns the completed operation kind.
    #[must_use]
    pub const fn kind(&self) -> WorkspaceAccessKind {
        match self {
            Self::Read(_) => WorkspaceAccessKind::Read,
            Self::Write(_) => WorkspaceAccessKind::Write,
        }
    }

    /// Returns the normalized workspace-relative path proof.
    #[must_use]
    pub const fn workspace_path(&self) -> WorkspacePathRef<'_> {
        match self {
            Self::Read(completion) => completion.workspace_path(),
            Self::Write(completion) => completion.workspace_path(),
        }
    }

    /// Returns the normalized workspace-relative path string.
    #[must_use]
    pub fn workspace_relative_path(&self) -> &str {
        match self {
            Self::Read(completion) => completion.workspace_relative_path(),
            Self::Write(completion) => completion.workspace_relative_path(),
        }
    }

    /// Returns whether the operation succeeded.
    #[must_use]
    pub const fn is_ok(&self) -> bool {
        match self {
            Self::Read(completion) => completion.outcome().is_ok(),
            Self::Write(completion) => completion.outcome().is_ok(),
        }
    }

    /// Returns this completion as a read, if it came from a read request.
    #[must_use]
    pub const fn as_read(&self) -> Option<&PluginWorkspaceReadCompletion> {
        match self {
            Self::Read(completion) => Some(completion),
            Self::Write(_) => None,
        }
    }

    /// Returns this completion as a write, if it came from a write request.
    #[must_use]
    pub const fn as_write(&self) -> Option<&PluginWorkspaceWriteCompletion> {
        match self {
            Self::Read(_) => None,
            Self::Write(completion) => Some(completion),
        }
    }
}

impl Debug for PluginWorkspaceIoCompletion {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Read(completion) => completion.fmt(formatter),
            Self::Write(completion) => completion.fmt(formatter),
        }
    }
}

/// Completed workspace read.
pub struct PluginWorkspaceReadCompletion {
    /// Normalized workspace-relative path proof.
    workspace_path: WorkspacePath,
    /// Filesystem-policy read result.
    outcome: Result<PluginWorkspaceReadSuccess, PluginWorkspaceReadError>,
}

impl PluginWorkspaceReadCompletion {
    /// Creates a read completion.
    pub(super) const fn new(
        workspace_path: WorkspacePath,
        outcome: Result<PluginWorkspaceReadSuccess, PluginWorkspaceReadError>,
    ) -> Self {
        Self {
            workspace_path,
            outcome,
        }
    }

    /// Returns the normalized workspace-relative path proof.
    #[must_use]
    pub const fn workspace_path(&self) -> WorkspacePathRef<'_> {
        self.workspace_path.as_ref()
    }

    /// Returns the normalized workspace-relative path string.
    #[must_use]
    pub fn workspace_relative_path(&self) -> &str {
        self.workspace_path.as_str()
    }

    /// Returns the read outcome.
    pub const fn outcome(&self) -> &Result<PluginWorkspaceReadSuccess, PluginWorkspaceReadError> {
        &self.outcome
    }
}

impl Debug for PluginWorkspaceReadCompletion {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("PluginWorkspaceReadCompletion")
            .field("kind", &WorkspaceAccessKind::Read)
            .field("path_byte_len", &self.workspace_path.as_str().len())
            .field("outcome", &self.outcome)
            .finish()
    }
}

/// Completed workspace write.
pub struct PluginWorkspaceWriteCompletion {
    /// Normalized workspace-relative path proof.
    workspace_path: WorkspacePath,
    /// Filesystem-policy write result.
    outcome: Result<PluginWorkspaceWriteSuccess, PluginWorkspaceWriteError>,
}

impl PluginWorkspaceWriteCompletion {
    /// Creates a write completion.
    pub(super) const fn new(
        workspace_path: WorkspacePath,
        outcome: Result<PluginWorkspaceWriteSuccess, PluginWorkspaceWriteError>,
    ) -> Self {
        Self {
            workspace_path,
            outcome,
        }
    }

    /// Returns the normalized workspace-relative path proof.
    #[must_use]
    pub const fn workspace_path(&self) -> WorkspacePathRef<'_> {
        self.workspace_path.as_ref()
    }

    /// Returns the normalized workspace-relative path string.
    #[must_use]
    pub fn workspace_relative_path(&self) -> &str {
        self.workspace_path.as_str()
    }

    /// Returns the write outcome.
    pub const fn outcome(&self) -> &Result<PluginWorkspaceWriteSuccess, PluginWorkspaceWriteError> {
        &self.outcome
    }
}

impl Debug for PluginWorkspaceWriteCompletion {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("PluginWorkspaceWriteCompletion")
            .field("kind", &WorkspaceAccessKind::Write)
            .field("path_byte_len", &self.workspace_path.as_str().len())
            .field("outcome", &self.outcome)
            .finish()
    }
}

/// Successful workspace read result.
#[derive(Eq, PartialEq)]
pub struct PluginWorkspaceReadSuccess {
    /// Escaped one-line display path.
    display_path: EscapedDisplayText,
    /// Bounded file bytes.
    bytes: Vec<u8>,
}

impl PluginWorkspaceReadSuccess {
    /// Creates a read success from filesystem-policy output.
    pub(super) const fn new(display_path: EscapedDisplayText, bytes: Vec<u8>) -> Self {
        Self {
            display_path,
            bytes,
        }
    }

    /// Returns the escaped one-line display path.
    #[must_use]
    pub const fn display_path(&self) -> &EscapedDisplayText {
        &self.display_path
    }

    /// Returns the bounded file bytes.
    #[must_use]
    pub fn bytes(&self) -> &[u8] {
        &self.bytes
    }
}

impl Debug for PluginWorkspaceReadSuccess {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("PluginWorkspaceReadSuccess")
            .field("display_path_byte_len", &self.display_path.as_str().len())
            .field("byte_len", &self.bytes.len())
            .finish()
    }
}

/// Guest-deliverable `workspace.observe` result.
#[derive(Clone, Eq, PartialEq)]
pub enum PluginWorkspaceObserveOutcome {
    /// Bounded file bytes, with path and display metadata stripped.
    Bytes(PluginWorkspaceObserveBytes),
    /// Closed read rejection safe for guest-visible results.
    Rejected,
}

impl PluginWorkspaceObserveOutcome {
    /// Projects a borrowed filesystem read outcome into the guest-visible shape.
    #[must_use]
    pub fn from_read_outcome(
        outcome: &Result<PluginWorkspaceReadSuccess, PluginWorkspaceReadError>,
    ) -> Self {
        match outcome {
            Ok(success) => Self::Bytes(PluginWorkspaceObserveBytes {
                bytes: success.bytes.clone(),
            }),
            Err(_source) => Self::Rejected,
        }
    }

    /// Projects an owned filesystem read outcome into the guest-visible shape.
    #[must_use]
    pub(super) fn from_read_result(
        outcome: Result<PluginWorkspaceReadSuccess, PluginWorkspaceReadError>,
    ) -> Self {
        match outcome {
            Ok(success) => Self::Bytes(PluginWorkspaceObserveBytes {
                bytes: success.bytes,
            }),
            Err(_source) => Self::Rejected,
        }
    }

    /// Returns whether the observation produced bytes.
    #[must_use]
    pub const fn is_ok(&self) -> bool {
        matches!(self, Self::Bytes(_))
    }

    /// Returns the redacted guest-delivery shape.
    #[must_use]
    pub const fn shape(&self) -> PluginWorkspaceObserveOutcomeShape {
        match self {
            Self::Bytes(bytes) => PluginWorkspaceObserveOutcomeShape::Bytes {
                byte_len: bytes.len(),
            },
            Self::Rejected => PluginWorkspaceObserveOutcomeShape::Rejected,
        }
    }

    /// Returns observed bytes when the read succeeded.
    #[must_use]
    pub fn bytes(&self) -> Option<&[u8]> {
        match self {
            Self::Bytes(bytes) => Some(bytes.as_slice()),
            Self::Rejected => None,
        }
    }

    /// Consumes observed bytes when the read succeeded.
    #[must_use]
    pub fn into_bytes(self) -> Option<Vec<u8>> {
        match self {
            Self::Bytes(bytes) => Some(bytes.into_vec()),
            Self::Rejected => None,
        }
    }
}

impl Debug for PluginWorkspaceObserveOutcome {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("PluginWorkspaceObserveOutcome")
            .field("shape", &self.shape())
            .finish()
    }
}

impl From<&PluginWorkspaceReadCompletion> for PluginWorkspaceObserveOutcome {
    fn from(completion: &PluginWorkspaceReadCompletion) -> Self {
        Self::from_read_outcome(completion.outcome())
    }
}

impl TryFrom<&PluginWorkspaceIoCompletion> for PluginWorkspaceObserveOutcome {
    type Error = PluginWorkspaceObserveProjectionError;

    fn try_from(completion: &PluginWorkspaceIoCompletion) -> Result<Self, Self::Error> {
        match completion {
            PluginWorkspaceIoCompletion::Read(completion) => Ok(Self::from(completion)),
            PluginWorkspaceIoCompletion::Write(_completion) => {
                Err(PluginWorkspaceObserveProjectionError::WrongOperation {
                    kind: WorkspaceAccessKind::Write,
                })
            }
        }
    }
}

/// Redacted `workspace.observe` guest-delivery shape.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PluginWorkspaceObserveOutcomeShape {
    /// Observation returned bounded bytes.
    Bytes {
        /// Bounded file byte length.
        byte_len: usize,
    },
    /// Filesystem policy or I/O rejected the observation.
    Rejected,
}

impl PluginWorkspaceObserveOutcomeShape {
    /// Returns whether the observation produced bytes.
    #[must_use]
    pub const fn is_ok(self) -> bool {
        matches!(self, Self::Bytes { .. })
    }
}

impl Display for PluginWorkspaceObserveOutcomeShape {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Bytes { byte_len } => write!(formatter, "bytes byte_len={byte_len}"),
            Self::Rejected => formatter.write_str("rejected"),
        }
    }
}

/// Bounded workspace bytes safe to return to a guest.
#[derive(Clone, Eq, PartialEq)]
pub struct PluginWorkspaceObserveBytes {
    /// Bounded file bytes.
    bytes: Vec<u8>,
}

impl PluginWorkspaceObserveBytes {
    /// Returns the bounded observed bytes.
    #[must_use]
    pub fn as_slice(&self) -> &[u8] {
        &self.bytes
    }

    /// Returns the observed byte length.
    #[must_use]
    pub const fn len(&self) -> usize {
        self.bytes.len()
    }

    /// Returns whether no bytes were observed.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.bytes.is_empty()
    }

    /// Consumes the proof into bounded bytes.
    #[must_use]
    pub fn into_vec(self) -> Vec<u8> {
        self.bytes
    }
}

impl Debug for PluginWorkspaceObserveBytes {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("PluginWorkspaceObserveBytes")
            .field("byte_len", &self.bytes.len())
            .finish()
    }
}

/// Rejection while projecting owner-facing workspace I/O into `workspace.observe`.
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
#[non_exhaustive]
pub enum PluginWorkspaceObserveProjectionError {
    /// A non-read completion was projected as a workspace observation.
    #[error("workspace observe projection requires read completion, got {kind}")]
    WrongOperation {
        /// Rejected operation kind.
        kind: WorkspaceAccessKind,
    },
}

impl PluginWorkspaceObserveProjectionError {
    /// Returns the rejected operation kind.
    #[must_use]
    pub const fn kind(self) -> WorkspaceAccessKind {
        match self {
            Self::WrongOperation { kind } => kind,
        }
    }
}

/// Successful workspace write result.
#[derive(Eq, PartialEq)]
pub struct PluginWorkspaceWriteSuccess {
    /// Escaped one-line display path.
    display_path: EscapedDisplayText,
}

impl PluginWorkspaceWriteSuccess {
    /// Creates a write success from filesystem-policy output.
    pub(super) const fn new(display_path: EscapedDisplayText) -> Self {
        Self { display_path }
    }

    /// Returns the escaped one-line display path.
    #[must_use]
    pub const fn display_path(&self) -> &EscapedDisplayText {
        &self.display_path
    }
}

impl Debug for PluginWorkspaceWriteSuccess {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("PluginWorkspaceWriteSuccess")
            .field("display_path_byte_len", &self.display_path.as_str().len())
            .finish()
    }
}