// file: crates/ksp-job-api/src/notification.rs
// version: 2

/// Monotone sequence attached to one latest-value Job notification stream.
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct JobNotificationSequence(u64);

impl JobNotificationSequence {
    /// Creates the initial sequence position for one Job snapshot stream.
    #[must_use]
    pub const fn initial() -> Self {
        return Self(0);
    }

    /// Returns the opaque numeric position carried by this sequence.
    #[must_use]
    pub const fn value(&self) -> u64 {
        return self.0;
    }

    /// Advances the sequence exactly once or reports exhaustion without wrapping.
    pub fn next(&self) -> crate::Result<Self> {
        let next = match self.0.checked_add(1) {
            std::option::Option::Some(value) => value,
            std::option::Option::None => {
                return std::result::Result::Err(
                    crate::Error::new(crate::ERROR_CODE_JOB_NOTIFICATION_SEQUENCE_EXHAUSTED, "Job notification sequence exhausted")
                        .with_context("sequence", self.0.to_string()),
                );
            },
        };
        return std::result::Result::Ok(Self(next));
    }

    /// Reports whether this sequence is strictly newer than an observed sequence.
    #[must_use]
    pub const fn is_after(&self, observed: Self) -> bool {
        return self.0 > observed.0;
    }
}

/// Latest complete observable value for one Job at a monotone sequence position.
#[derive(Clone, Eq, PartialEq)]
pub struct JobNotification<S> {
    id: crate::JobId,
    kind: crate::JobKindCode,
    sequence: crate::JobNotificationSequence,
    snapshot: S,
    state: crate::JobState,
}

impl<S> JobNotification<S> {
    /// Creates one immutable latest-value notification from an already validated Job identity and snapshot.
    #[must_use]
    pub const fn new(id: crate::JobId, kind: crate::JobKindCode, sequence: crate::JobNotificationSequence, state: crate::JobState, snapshot: S) -> Self {
        return Self { id, kind, sequence, snapshot, state };
    }

    /// Returns the logical Job identity.
    #[must_use]
    pub const fn id(&self) -> &crate::JobId {
        return &self.id;
    }

    /// Returns the stable Job family code.
    #[must_use]
    pub const fn kind(&self) -> &crate::JobKindCode {
        return &self.kind;
    }

    /// Returns the monotone sequence of this latest value.
    #[must_use]
    pub const fn sequence(&self) -> crate::JobNotificationSequence {
        return self.sequence;
    }

    /// Returns the complete safe snapshot owned by the concrete Job contract.
    #[must_use]
    pub const fn snapshot(&self) -> &S {
        return &self.snapshot;
    }

    /// Returns the lifecycle state represented by this snapshot.
    #[must_use]
    pub const fn state(&self) -> crate::JobState {
        return self.state;
    }
}

impl<S> std::fmt::Debug for JobNotification<S> {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return formatter
            .debug_struct("JobNotification")
            .field("id", &self.id)
            .field("kind", &self.kind)
            .field("sequence", &self.sequence)
            .field("state", &self.state)
            .field("snapshot", &"<redacted>")
            .finish();
    }
}

/// Runtime-neutral future returned while observing a latest-value Job snapshot source.
pub type JobSnapshotFuture<'a, S> = std::pin::Pin<std::boxed::Box<dyn std::future::Future<Output = crate::JobNotification<S>> + std::marker::Send + 'a>>;

/// Runtime-neutral read and change-wait contract for one latest-value Job snapshot stream.
pub trait JobSnapshotSource: std::marker::Send + std::marker::Sync {
    /// Complete snapshot type retained by the concrete source.
    type Snapshot: std::clone::Clone + std::marker::Send + std::marker::Sync + 'static;

    /// Returns the complete current value without requiring replay of prior notifications.
    #[must_use]
    fn current(&self) -> crate::JobNotification<Self::Snapshot>;

    /// Waits for a value newer than `observed`, returning the complete current snapshot after coalescing any intermediate updates.
    fn wait_for_change(&self, observed: crate::JobNotificationSequence) -> crate::JobSnapshotFuture<'_, Self::Snapshot>;
}

#[cfg(test)]
fn exhausted_notification_sequence() -> crate::JobNotificationSequence {
    return JobNotificationSequence(u64::MAX);
}

#[cfg(test)]
#[path = "../unit_tests/notification.rs"]
mod tests;