v0.3.9-pre.002

crates/ksp-worker-api/src/lib.rs

@@ -0,0 +1,62 @@
+// file: crates/ksp-worker-api/src/lib.rs
+// version: 1
+
+#![warn(missing_docs)]
+#![deny(unreachable_pub)]
+#![forbid(unsafe_code)]
+
+//! Passive runtime-neutral lifecycle contracts for continuous KSP Workers.
+//!
+//! This foundation owns bounded Worker identity, explicit continuous lifecycle
+//! transitions, cooperative stop intent and a fixed latest-value observation
+//! contract. Concrete runtimes, restart policy, Transport, Store, Config, Jobs
+//! and domain-specific Worker behavior remain outside this crate.
+
+mod error;
+mod identity;
+mod lifecycle;
+mod snapshot;
+mod stop;
+
+/// Error code used when a Worker identifier violates its bounded safe-code contract.
+pub use self::error::ERROR_CODE_WORKER_ID_INVALID;
+/// Error code used when a Worker kind code violates its bounded safe-code contract.
+pub use self::error::ERROR_CODE_WORKER_KIND_INVALID;
+/// Error code used when a Worker snapshot sequence cannot advance without wrapping.
+pub use self::error::ERROR_CODE_WORKER_SNAPSHOT_SEQUENCE_EXHAUSTED;
+/// Error code used when a requested Worker lifecycle transition is not allowed.
+pub use self::error::ERROR_CODE_WORKER_TRANSITION_INVALID;
+/// Maximum UTF-8 byte length admitted for one Worker identifier.
+pub use self::identity::MAX_WORKER_ID_BYTES;
+/// Maximum UTF-8 byte length admitted for one Worker kind code.
+pub use self::identity::MAX_WORKER_KIND_CODE_BYTES;
+/// Bounded caller-supplied identity of one logical Worker instance.
+pub use self::identity::WorkerId;
+/// Bounded stable code identifying one concrete family of Workers.
+pub use self::identity::WorkerKindCode;
+/// Minimal generic activity classification for a continuous Worker.
+pub use self::lifecycle::WorkerActivity;
+/// Operational health classification independent from Worker lifecycle phase.
+pub use self::lifecycle::WorkerHealth;
+/// Passive owner of one Worker identity and its validated lifecycle state.
+pub use self::lifecycle::WorkerLifecycle;
+/// Current lifecycle state of one continuous Worker.
+pub use self::lifecycle::WorkerState;
+/// Fixed common latest-value snapshot exposed by every Worker implementation.
+pub use self::snapshot::WorkerSnapshot;
+/// Runtime-neutral future returned while observing a latest-value Worker snapshot source.
+pub use self::snapshot::WorkerSnapshotFuture;
+/// Monotone sequence attached to one latest-value Worker snapshot stream.
+pub use self::snapshot::WorkerSnapshotSequence;
+/// Runtime-neutral read and change-wait contract for one latest-value Worker snapshot stream.
+pub use self::snapshot::WorkerSnapshotSource;
+/// Runtime-neutral cloneable token carrying cooperative Worker stop intent.
+pub use self::stop::WorkerStopToken;
+/// Common KSP error type used by Worker-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;