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

#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]

//! Passive runtime-neutral lifecycle contracts for bounded KSP Jobs.
//!
//! This foundation owns validated Job identity, explicit lifecycle transitions
//! cooperative cancellation intent and runtime-neutral latest-value observation.
//! Concrete Job behavior, runtime spawning, Transport, Store and Worker contracts
//! remain outside this crate.

mod cancellation;
mod error;
mod identity;
mod lifecycle;
mod notification;

/// Runtime-neutral cloneable token carrying cooperative cancellation intent.
pub use self::cancellation::JobCancellationToken;
/// Error code used when a Job identifier violates its bounded safe-code contract.
pub use self::error::ERROR_CODE_JOB_ID_INVALID;
/// Error code used when a Job kind code violates its bounded safe-code contract.
pub use self::error::ERROR_CODE_JOB_KIND_INVALID;
/// Error code used when a Job notification sequence cannot advance without wrapping.
pub use self::error::ERROR_CODE_JOB_NOTIFICATION_SEQUENCE_EXHAUSTED;
/// Error code used when a requested Job lifecycle transition is not allowed.
pub use self::error::ERROR_CODE_JOB_TRANSITION_INVALID;
/// Bounded caller-supplied identity of one logical Job and its controlled resumptions.
pub use self::identity::JobId;
/// Bounded stable code identifying one concrete family of Jobs.
pub use self::identity::JobKindCode;
/// Maximum UTF-8 byte length admitted for one Job identifier.
pub use self::identity::MAX_JOB_ID_BYTES;
/// Maximum UTF-8 byte length admitted for one Job kind code.
pub use self::identity::MAX_JOB_KIND_CODE_BYTES;
/// Completion classification of a Job that reached its normal terminal state.
pub use self::lifecycle::JobCompletion;
/// Passive owner of one Job identity and its validated lifecycle state.
pub use self::lifecycle::JobLifecycle;
/// Current lifecycle state of one bounded Job.
pub use self::lifecycle::JobState;
/// Latest complete observable value for one Job at a monotone sequence position.
pub use self::notification::JobNotification;
/// Monotone sequence attached to one latest-value Job notification stream.
pub use self::notification::JobNotificationSequence;
/// Runtime-neutral future returned while observing a latest-value Job snapshot source.
pub use self::notification::JobSnapshotFuture;
/// Runtime-neutral read and change-wait contract for one latest-value Job snapshot stream.
pub use self::notification::JobSnapshotSource;
/// Common KSP error type used by Job-facing contracts.
pub use ksp_core_lib::Error;
/// Stable structured code identifying a KSP error category and condition.
pub use ksp_core_lib::ErrorCode;
/// Structured contextual field attached to a KSP error.
pub use ksp_core_lib::ErrorContext;
/// Common KSP result alias using [`Error`].
pub use ksp_core_lib::Result;