alma 0.1.1

//! Workspace observation task result vocabulary.

use super::PluginWorkspaceObserveOutcomeShape;
use crate::plugin::{PluginIdentity, PluginWorkspaceObserveOutcome};
use std::{
    fmt::{Debug, Display, Formatter},
    num::NonZeroU64,
};

/// Host-owned identifier for a workspace observation task.
///
/// The id is inert. Callers that need to retain task authority should carry a
/// [`PluginWorkspaceObserveTaskHandle`].
#[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct PluginWorkspaceObserveTaskId(NonZeroU64);

impl PluginWorkspaceObserveTaskId {
    /// Creates a task id from a non-zero raw value.
    ///
    /// # Errors
    ///
    /// Returns [`PluginWorkspaceObserveTaskIdError::Zero`] when `value` is zero.
    pub const fn try_new(value: u64) -> Result<Self, PluginWorkspaceObserveTaskIdError> {
        match NonZeroU64::new(value) {
            Some(value) => Ok(Self(value)),
            None => Err(PluginWorkspaceObserveTaskIdError::Zero),
        }
    }

    /// Returns the raw non-zero id.
    #[must_use]
    pub const fn get(self) -> u64 {
        self.0.get()
    }

    /// Returns the first generated id.
    pub(in crate::plugin::host::workspace_io) const fn first() -> Self {
        Self(NonZeroU64::MIN)
    }

    /// Returns the next id, or `None` after `u64::MAX`.
    pub(in crate::plugin::host::workspace_io) const fn next(self) -> Option<Self> {
        match self.0.get().checked_add(1) {
            Some(next) => match NonZeroU64::new(next) {
                Some(next) => Some(Self(next)),
                None => None,
            },
            None => None,
        }
    }
}

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

impl Display for PluginWorkspaceObserveTaskId {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        write!(formatter, "{}", self.get())
    }
}

/// Owned identity-scoped workspace observation task handle.
///
/// This is the adapter-facing owned pair. Queue observation still requires a
/// lookup borrowed from this handle.
#[derive(Clone, Eq, Hash, PartialEq)]
pub struct PluginWorkspaceObserveTaskHandle {
    /// Plugin that owns this task id.
    identity: PluginIdentity,
    /// Host-owned inert lookup key.
    task_id: PluginWorkspaceObserveTaskId,
}

impl PluginWorkspaceObserveTaskHandle {
    /// Pairs an allocated task id with the plugin identity allowed to observe it.
    #[must_use]
    pub(in crate::plugin) const fn new(
        identity: PluginIdentity,
        task_id: PluginWorkspaceObserveTaskId,
    ) -> Self {
        Self { identity, task_id }
    }

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

    /// Returns the identity that owns this task id.
    #[must_use]
    pub const fn identity_proof(&self) -> &PluginIdentity {
        &self.identity
    }

    /// Returns the inert host task id.
    #[must_use]
    pub const fn task_id(&self) -> PluginWorkspaceObserveTaskId {
        self.task_id
    }

    /// Borrows this handle as the lookup proof accepted by a task queue.
    #[must_use]
    pub(in crate::plugin::host::workspace_io) const fn lookup(
        &self,
    ) -> PluginWorkspaceObserveTaskLookup<'_> {
        PluginWorkspaceObserveTaskLookup::new(self.identity_proof(), self.task_id)
    }
}

impl Display for PluginWorkspaceObserveTaskHandle {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        let identity = self.identity();
        write!(formatter, "identity={identity:?} task_id={}", self.task_id)
    }
}

impl Debug for PluginWorkspaceObserveTaskHandle {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(self, formatter)
    }
}

/// Queue-owned identity-scoped task key.
///
/// Task ids are inert. Queue records retain this owned pair so internal state
/// cannot carry a task id without its plugin owner.
#[derive(Clone, Eq, PartialEq)]
pub(in crate::plugin::host::workspace_io) struct PluginWorkspaceObserveTaskKey {
    /// Identity-scoped task handle.
    handle: PluginWorkspaceObserveTaskHandle,
}

impl PluginWorkspaceObserveTaskKey {
    /// Pairs an allocated task id with the plugin identity that may observe it.
    #[must_use]
    pub(in crate::plugin::host::workspace_io) const fn new(
        identity: PluginIdentity,
        task_id: PluginWorkspaceObserveTaskId,
    ) -> Self {
        Self {
            handle: PluginWorkspaceObserveTaskHandle::new(identity, task_id),
        }
    }

    /// Returns the owning plugin identity.
    #[must_use]
    pub(in crate::plugin::host::workspace_io) const fn identity_proof(&self) -> &PluginIdentity {
        self.handle.identity_proof()
    }

    /// Returns the inert task id.
    #[must_use]
    pub(in crate::plugin::host::workspace_io) const fn task_id(
        &self,
    ) -> PluginWorkspaceObserveTaskId {
        self.handle.task_id()
    }

    /// Returns the owned identity-scoped task handle.
    #[must_use]
    pub(in crate::plugin::host::workspace_io) const fn handle(
        &self,
    ) -> &PluginWorkspaceObserveTaskHandle {
        &self.handle
    }

    /// Returns whether a lookup matches this owned task key.
    pub(in crate::plugin::host::workspace_io) fn matches_lookup(
        &self,
        lookup: PluginWorkspaceObserveTaskLookup<'_>,
    ) -> bool {
        lookup.matches_handle(&self.handle)
    }
}

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

/// Invalid workspace observation task id.
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
#[non_exhaustive]
pub enum PluginWorkspaceObserveTaskIdError {
    /// Task ids are one-based.
    #[error("plugin workspace observe task id must be non-zero")]
    Zero,
}

/// Handle-borrowed workspace observation task lookup.
///
/// Queue adapters derive this from an owned task handle, so public callers
/// cannot mint arbitrary identity/id pairs.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(in crate::plugin::host::workspace_io) struct PluginWorkspaceObserveTaskLookup<'identity> {
    /// Plugin allowed to observe the task state.
    identity: &'identity PluginIdentity,
    /// Host-owned inert lookup key.
    task_id: PluginWorkspaceObserveTaskId,
}

impl<'identity> PluginWorkspaceObserveTaskLookup<'identity> {
    /// Pairs a task id with the identity required to observe it.
    #[must_use]
    pub(in crate::plugin::host::workspace_io) const fn new(
        identity: &'identity PluginIdentity,
        task_id: PluginWorkspaceObserveTaskId,
    ) -> Self {
        Self { identity, task_id }
    }

    /// Returns whether this lookup matches an identity-scoped task record.
    pub(in crate::plugin::host::workspace_io) fn matches_task(
        self,
        identity: &PluginIdentity,
        task_id: PluginWorkspaceObserveTaskId,
    ) -> bool {
        identity == self.identity && task_id == self.task_id
    }

    /// Returns whether this lookup matches an owned task key.
    pub(in crate::plugin::host::workspace_io) fn matches_key(
        self,
        key: &PluginWorkspaceObserveTaskKey,
    ) -> bool {
        key.matches_lookup(self)
    }

    /// Returns whether this lookup matches an owned task handle.
    pub(in crate::plugin::host::workspace_io) fn matches_handle(
        self,
        handle: &PluginWorkspaceObserveTaskHandle,
    ) -> bool {
        self.matches_task(handle.identity_proof(), handle.task_id())
    }

    /// Returns whether a retained completion belongs to this lookup.
    pub(in crate::plugin::host::workspace_io) fn matches_completion(
        self,
        completion: &PluginWorkspaceObserveTaskCompletion,
    ) -> bool {
        self.matches_key(&completion.key)
    }
}

/// Closed workspace observation task state.
#[derive(Clone, Copy, Eq, PartialEq)]
pub enum PluginWorkspaceObserveTaskState {
    /// Filesystem policy has not executed the task yet.
    Pending,
    /// A retained guest-delivery outcome is available.
    Completed,
    /// The task is unknown, already taken, evicted, or owned by another identity.
    Unknown,
}

impl PluginWorkspaceObserveTaskState {
    /// Stable state text for adapter diagnostics.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Pending => "pending",
            Self::Completed => "completed",
            Self::Unknown => "unknown",
        }
    }

    /// Returns whether the task is still pending.
    #[must_use]
    pub const fn is_pending(self) -> bool {
        matches!(self, Self::Pending)
    }

    /// Returns whether a retained outcome is available.
    #[must_use]
    pub const fn is_completed(self) -> bool {
        matches!(self, Self::Completed)
    }

    /// Returns whether the task is unknown at this boundary.
    #[must_use]
    pub const fn is_unknown(self) -> bool {
        matches!(self, Self::Unknown)
    }
}

impl Display for PluginWorkspaceObserveTaskState {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl Debug for PluginWorkspaceObserveTaskState {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

/// Redacted shape for a workspace observation task poll or take result.
#[derive(Clone, Copy, Eq, PartialEq)]
pub enum PluginWorkspaceObserveTaskResultShape {
    /// Filesystem policy has not executed the task yet.
    Pending,
    /// A retained guest-delivery outcome is available.
    Completed {
        /// Redacted guest-delivery outcome shape.
        outcome: PluginWorkspaceObserveOutcomeShape,
    },
    /// The task is unknown, already taken, evicted, or owned by another identity.
    Unknown,
}

impl PluginWorkspaceObserveTaskResultShape {
    /// Returns the closed task state without exposing bytes.
    #[must_use]
    pub const fn state(self) -> PluginWorkspaceObserveTaskState {
        match self {
            Self::Pending => PluginWorkspaceObserveTaskState::Pending,
            Self::Completed { .. } => PluginWorkspaceObserveTaskState::Completed,
            Self::Unknown => PluginWorkspaceObserveTaskState::Unknown,
        }
    }

    /// Returns a redacted completed outcome shape.
    #[must_use]
    pub const fn outcome_shape(self) -> Option<PluginWorkspaceObserveOutcomeShape> {
        match self {
            Self::Completed { outcome } => Some(outcome),
            Self::Pending | Self::Unknown => None,
        }
    }
}

impl Display for PluginWorkspaceObserveTaskResultShape {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Pending | Self::Unknown => write!(formatter, "{}", self.state()),
            Self::Completed { outcome } => write!(formatter, "completed outcome={outcome}"),
        }
    }
}

impl Debug for PluginWorkspaceObserveTaskResultShape {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(self, formatter)
    }
}

/// Payload-free poll result for a workspace observation task.
#[derive(Clone, Copy, Eq, PartialEq)]
pub enum PluginWorkspaceObserveTaskPoll {
    /// Filesystem policy has not executed the task yet.
    Pending,
    /// A retained guest-delivery outcome is available.
    Completed {
        /// Redacted guest-delivery outcome shape.
        outcome: PluginWorkspaceObserveOutcomeShape,
    },
    /// The task is unknown, already taken, evicted, or owned by another identity.
    Unknown,
}

impl PluginWorkspaceObserveTaskPoll {
    /// Returns the closed task state without exposing bytes.
    #[must_use]
    pub const fn state(&self) -> PluginWorkspaceObserveTaskState {
        self.shape().state()
    }

    /// Returns the redacted poll result shape.
    #[must_use]
    pub const fn shape(&self) -> PluginWorkspaceObserveTaskResultShape {
        match self {
            Self::Pending => PluginWorkspaceObserveTaskResultShape::Pending,
            Self::Completed { outcome } => {
                PluginWorkspaceObserveTaskResultShape::Completed { outcome: *outcome }
            }
            Self::Unknown => PluginWorkspaceObserveTaskResultShape::Unknown,
        }
    }

    /// Returns whether the task is still pending.
    #[must_use]
    pub const fn is_pending(&self) -> bool {
        self.state().is_pending()
    }

    /// Returns whether the task has a retained outcome.
    #[must_use]
    pub const fn is_completed(&self) -> bool {
        self.state().is_completed()
    }

    /// Returns whether the task is unknown at this boundary.
    #[must_use]
    pub const fn is_unknown(&self) -> bool {
        self.state().is_unknown()
    }

    /// Returns a redacted completed outcome shape.
    #[must_use]
    pub const fn outcome_shape(&self) -> Option<PluginWorkspaceObserveOutcomeShape> {
        match self {
            Self::Completed { outcome } => Some(*outcome),
            Self::Pending | Self::Unknown => None,
        }
    }
}

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

impl Display for PluginWorkspaceObserveTaskPoll {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(&self.shape(), formatter)
    }
}

/// Consuming result for a workspace observation task.
#[derive(Clone, Eq, PartialEq)]
pub enum PluginWorkspaceObserveTaskTake {
    /// Filesystem policy has not executed the task yet.
    Pending,
    /// A retained guest-delivery outcome was consumed.
    Completed(PluginWorkspaceObserveOutcome),
    /// The task is unknown, already taken, evicted, or owned by another identity.
    Unknown,
}

impl PluginWorkspaceObserveTaskTake {
    /// Returns the closed task state without exposing bytes.
    #[must_use]
    pub const fn state(&self) -> PluginWorkspaceObserveTaskState {
        self.shape().state()
    }

    /// Returns the redacted take result shape.
    #[must_use]
    pub const fn shape(&self) -> PluginWorkspaceObserveTaskResultShape {
        match self {
            Self::Pending => PluginWorkspaceObserveTaskResultShape::Pending,
            Self::Completed(outcome) => PluginWorkspaceObserveTaskResultShape::Completed {
                outcome: outcome.shape(),
            },
            Self::Unknown => PluginWorkspaceObserveTaskResultShape::Unknown,
        }
    }

    /// Returns whether the task is still pending.
    #[must_use]
    pub const fn is_pending(&self) -> bool {
        self.state().is_pending()
    }

    /// Returns whether this result consumed a completed outcome.
    #[must_use]
    pub const fn is_completed(&self) -> bool {
        self.state().is_completed()
    }

    /// Returns whether the task is unknown at this boundary.
    #[must_use]
    pub const fn is_unknown(&self) -> bool {
        self.state().is_unknown()
    }

    /// Returns a borrowed completed outcome.
    #[must_use]
    pub const fn outcome(&self) -> Option<&PluginWorkspaceObserveOutcome> {
        match self {
            Self::Completed(outcome) => Some(outcome),
            Self::Pending | Self::Unknown => None,
        }
    }

    /// Consumes the result into a completed outcome.
    #[must_use]
    pub fn into_outcome(self) -> Option<PluginWorkspaceObserveOutcome> {
        match self {
            Self::Completed(outcome) => Some(outcome),
            Self::Pending | Self::Unknown => None,
        }
    }
}

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

impl Display for PluginWorkspaceObserveTaskTake {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(&self.shape(), formatter)
    }
}

/// Redacted identity-scoped shape for a retained workspace observation task completion.
#[derive(Clone, Eq, PartialEq)]
pub struct PluginWorkspaceObserveTaskCompletionShape {
    /// Identity-scoped task handle.
    handle: PluginWorkspaceObserveTaskHandle,
    /// Guest-delivery outcome shape.
    outcome_shape: PluginWorkspaceObserveOutcomeShape,
}

impl PluginWorkspaceObserveTaskCompletionShape {
    /// Builds a redacted completion shape from an identity-scoped handle and outcome shape.
    #[must_use]
    pub(in crate::plugin) const fn new(
        handle: PluginWorkspaceObserveTaskHandle,
        outcome_shape: PluginWorkspaceObserveOutcomeShape,
    ) -> Self {
        Self {
            handle,
            outcome_shape,
        }
    }

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

    /// Returns the identity that owns this task result shape.
    #[must_use]
    pub const fn identity_proof(&self) -> &PluginIdentity {
        self.handle.identity_proof()
    }

    /// Returns the inert host task id.
    #[must_use]
    pub const fn task_id(&self) -> PluginWorkspaceObserveTaskId {
        self.handle.task_id()
    }

    /// Returns the identity-scoped task handle.
    #[must_use]
    pub const fn handle(&self) -> &PluginWorkspaceObserveTaskHandle {
        &self.handle
    }

    /// Returns the redacted guest-delivery outcome shape.
    #[must_use]
    pub const fn outcome_shape(&self) -> PluginWorkspaceObserveOutcomeShape {
        self.outcome_shape
    }

    /// Returns whether the completed task produced bytes.
    #[must_use]
    pub const fn is_ok(&self) -> bool {
        self.outcome_shape.is_ok()
    }
}

impl Display for PluginWorkspaceObserveTaskCompletionShape {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        write!(formatter, "{} outcome={}", self.handle, self.outcome_shape)
    }
}

impl Debug for PluginWorkspaceObserveTaskCompletionShape {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(self, formatter)
    }
}

/// Completed workspace observation task retained for guest polling.
#[derive(Clone, Eq, PartialEq)]
pub struct PluginWorkspaceObserveTaskCompletion {
    /// Queue-owned identity and task-id pair.
    key: PluginWorkspaceObserveTaskKey,
    /// Guest-delivery result.
    outcome: PluginWorkspaceObserveOutcome,
}

impl PluginWorkspaceObserveTaskCompletion {
    /// Creates a retained task completion.
    pub(in crate::plugin::host::workspace_io) const fn new(
        key: PluginWorkspaceObserveTaskKey,
        outcome: PluginWorkspaceObserveOutcome,
    ) -> Self {
        Self { key, outcome }
    }

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

    /// Returns the validated plugin identity proof.
    #[must_use]
    pub const fn identity_proof(&self) -> &PluginIdentity {
        self.key.identity_proof()
    }

    /// Returns the task id.
    #[must_use]
    pub const fn task_id(&self) -> PluginWorkspaceObserveTaskId {
        self.key.task_id()
    }

    /// Returns the identity-scoped task handle.
    #[must_use]
    pub const fn handle(&self) -> &PluginWorkspaceObserveTaskHandle {
        self.key.handle()
    }

    /// Returns the guest-delivery outcome.
    #[must_use]
    pub const fn outcome(&self) -> &PluginWorkspaceObserveOutcome {
        &self.outcome
    }

    /// Returns the redacted identity-scoped completion shape for diagnostics and adapters.
    #[must_use]
    pub fn shape(&self) -> PluginWorkspaceObserveTaskCompletionShape {
        PluginWorkspaceObserveTaskCompletionShape::new(self.handle().clone(), self.outcome.shape())
    }

    /// Consumes the completion into its guest-delivery outcome.
    #[must_use]
    pub fn into_outcome(self) -> PluginWorkspaceObserveOutcome {
        self.outcome
    }
}

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