v0.3.5-pre.002

crates/ksp-interface-lib/src/lib.rs

@@ -1,20 +1,21 @@
 // file: crates/ksp-interface-lib/src/lib.rs
-// version: 3
+// version: 4
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
 #![forbid(unsafe_code)]
 
-//! Passive wire contracts shared by KSP Program implementations.
+//! Passive contracts shared across KSP component boundaries.
 //!
-//! The foundation reuses the canonical Solana [`Pubkey`] owned by
-//! `ksp-core-lib` and exposes only bounded, passive Program-facing structures.
-//! Runtime, transport, persistence and Program behavior remain outside this
-//! crate.
+//! The crate reuses canonical Solana primitives owned by `ksp-core-lib` and
+//! exposes only bounded, passive Program-facing and provider-neutral
+//! acquisition structures. Runtime, transport, persistence and Program
+//! behavior remain outside this crate.
 
 mod error;
 mod program_account_meta;
 mod program_instruction;
+mod slot_lifecycle;
 
 /// Error code used when an Interface-owned Program instruction admission limit is exceeded.
 pub use self::error::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED;
@@ -26,5 +27,9 @@ pub use self::program_account_meta::ProgramAccountMeta;
 pub use self::program_instruction::MAX_PROGRAM_INSTRUCTION_DATA_LEN;
 /// Passive, bounded Program instruction wire contract.
 pub use self::program_instruction::ProgramInstruction;
+/// Passive provider-neutral occurrence of one slot lifecycle stage.
+pub use self::slot_lifecycle::SlotLifecycleEvent;
+/// Provider-neutral stage in the lifecycle of an observed Solana slot.
+pub use self::slot_lifecycle::SlotLifecycleStage;
 /// Canonical Solana account address primitive owned by `ksp-core-lib`.
 pub use ksp_core_lib::Pubkey;

crates/ksp-interface-lib/src/slot_lifecycle.rs

@@ -0,0 +1,53 @@
+// file: crates/ksp-interface-lib/src/slot_lifecycle.rs
+// version: 1
+
+/// Provider-neutral stage in the lifecycle of an observed Solana slot.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum SlotLifecycleStage {
+    /// The slot has been processed.
+    Processed,
+    /// The first shred for the slot has been received.
+    FirstShredReceived,
+    /// Slot ingestion has completed.
+    Completed,
+    /// A bank has been created for the slot.
+    CreatedBank,
+    /// The slot has been marked dead.
+    Dead,
+    /// The slot has reached optimistic confirmation.
+    OptimisticallyConfirmed,
+    /// The slot has become rooted.
+    Rooted,
+}
+
+/// Passive provider-neutral occurrence of one slot lifecycle stage.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct SlotLifecycleEvent {
+    slot: u64,
+    stage: SlotLifecycleStage,
+}
+
+impl SlotLifecycleEvent {
+    /// Creates a lifecycle event for `slot` and `stage`.
+    #[must_use]
+    pub const fn new(slot: u64, stage: SlotLifecycleStage) -> Self {
+        return Self { slot, stage };
+    }
+
+    /// Returns the observed slot exactly as supplied.
+    #[must_use]
+    pub const fn slot(&self) -> u64 {
+        return self.slot;
+    }
+
+    /// Returns the provider-neutral lifecycle stage.
+    #[must_use]
+    pub const fn stage(&self) -> SlotLifecycleStage {
+        return self.stage;
+    }
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/slot_lifecycle.rs"]
+mod tests;

crates/ksp-interface-lib/tests/release_completeness.rs

@@ -1,75 +1,56 @@
 // file: crates/ksp-interface-lib/tests/release_completeness.rs
-// version: 1
+// version: 2
 
-//! Release-level completeness canaries for the `0.2.13` Interface foundation.
-
-#[test]
-fn pre_005_exact_crate_root_export_inventory_is_stable() {
-    let crate_root = include_str!("../src/lib.rs");
-    let mut actual = std::vec::Vec::new();
-    for line in crate_root.lines() {
-        let trimmed = line.trim();
-        if trimmed.starts_with("pub use ") {
-            actual.push(trimmed);
-        }
-    }
-    actual.sort_unstable();
-    let mut expected = std::vec![
-        "pub use self::error::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED;",
-        "pub use self::program_account_meta::MAX_PROGRAM_INSTRUCTION_ACCOUNTS;",
-        "pub use self::program_account_meta::ProgramAccountMeta;",
-        "pub use self::program_instruction::MAX_PROGRAM_INSTRUCTION_DATA_LEN;",
-        "pub use self::program_instruction::ProgramInstruction;",
-        "pub use ksp_core_lib::Pubkey;",
-    ];
-    expected.sort_unstable();
-    assert_eq!(actual, expected);
-    assert!(!crate_root.contains("pub mod "));
-    return;
+fn crate_root_source() -> std::result::Result<std::string::String, std::io::Error> {
+    let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/lib.rs");
+    return std::fs::read_to_string(path);
 }
 
 #[test]
-fn pre_005_production_module_inventory_contains_no_second_wire_domain() -> std::io::Result<()> {
-    let source_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
-    let entries = match std::fs::read_dir(source_root) {
-        std::result::Result::Ok(value) => value,
-        std::result::Result::Err(error) => return std::result::Result::Err(error),
-    };
-    let mut names = std::vec::Vec::new();
-    for entry in entries {
-        let entry = match entry {
-            std::result::Result::Ok(value) => value,
-            std::result::Result::Err(error) => return std::result::Result::Err(error),
-        };
-        let file_type = match entry.file_type() {
-            std::result::Result::Ok(value) => value,
-            std::result::Result::Err(error) => return std::result::Result::Err(error),
-        };
-        if !file_type.is_file() {
-            continue;
-        }
-        let name = match entry.file_name().into_string() {
-            std::result::Result::Ok(value) => value,
-            std::result::Result::Err(_) => continue,
-        };
-        if name.ends_with(".rs") {
-            names.push(name);
-        }
-    }
-    names.sort_unstable();
-    assert_eq!(names, std::vec!["error.rs", "lib.rs", "program_account_meta.rs", "program_instruction.rs"]);
-    return std::result::Result::Ok(());
-}
-
-#[test]
-fn pre_005_foundation_has_one_error_code_and_two_bounded_passive_types() {
+fn v0_3_5_pre_002_foundation_keeps_one_error_code_and_adds_one_passive_acquisition_family() {
     assert_eq!(ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.domain(), "interface");
     assert_eq!(ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.code(), "program_instruction_limit_exceeded");
     assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_ACCOUNTS, 255);
     assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_DATA_LEN, 10_240);
+
     let program_id = ksp_interface_lib::Pubkey::new_from_array([0xB1_u8; 32]);
     let account = ksp_interface_lib::ProgramAccountMeta::readonly(ksp_interface_lib::Pubkey::new_from_array([0xB2_u8; 32]), false);
-    let instruction = ksp_interface_lib::ProgramInstruction::try_new(program_id, std::vec![account], std::vec![0xB3_u8]);
-    assert!(instruction.is_ok());
-    return;
+    let instruction_result = ksp_interface_lib::ProgramInstruction::try_new(program_id, std::vec![account], std::vec![0xB3_u8]);
+    assert!(instruction_result.is_ok());
+
+    let lifecycle = ksp_interface_lib::SlotLifecycleEvent::new(u64::MAX, ksp_interface_lib::SlotLifecycleStage::Rooted);
+    assert_eq!(lifecycle.slot(), u64::MAX);
+    assert_eq!(lifecycle.stage(), ksp_interface_lib::SlotLifecycleStage::Rooted);
+}
+
+#[test]
+fn v0_3_5_pre_002_exact_crate_root_export_inventory_includes_slot_lifecycle() -> std::result::Result<(), std::io::Error> {
+    let source = crate_root_source()?;
+    let public_use_count = source.lines().filter(|line| line.starts_with("pub use ")).count();
+
+    assert_eq!(public_use_count, 8);
+    assert!(source.contains("pub use self::error::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED;"));
+    assert!(source.contains("pub use self::program_account_meta::MAX_PROGRAM_INSTRUCTION_ACCOUNTS;"));
+    assert!(source.contains("pub use self::program_account_meta::ProgramAccountMeta;"));
+    assert!(source.contains("pub use self::program_instruction::MAX_PROGRAM_INSTRUCTION_DATA_LEN;"));
+    assert!(source.contains("pub use self::program_instruction::ProgramInstruction;"));
+    assert!(source.contains("pub use self::slot_lifecycle::SlotLifecycleEvent;"));
+    assert!(source.contains("pub use self::slot_lifecycle::SlotLifecycleStage;"));
+    assert!(source.contains("pub use ksp_core_lib::Pubkey;"));
+
+    return Ok(());
+}
+
+#[test]
+fn v0_3_5_pre_002_production_module_inventory_adds_only_slot_lifecycle() -> std::result::Result<(), std::io::Error> {
+    let source = crate_root_source()?;
+    let modules = source.lines().filter_map(|line| line.strip_prefix("mod ").and_then(|module| module.strip_suffix(';'))).collect::<std::vec::Vec<_>>();
+
+    assert_eq!(modules, std::vec!["error", "program_account_meta", "program_instruction", "slot_lifecycle"]);
+    assert!(!source.contains("serde"));
+    assert!(!source.contains("tracing"));
+    assert!(!source.contains("ksp_onchain_transport"));
+    assert!(!source.contains("ksp_store"));
+
+    return Ok(());
 }

crates/ksp-interface-lib/tests/slot_lifecycle_public_api.rs

@@ -0,0 +1,29 @@
+// file: crates/ksp-interface-lib/tests/slot_lifecycle_public_api.rs
+// version: 1
+
+#[test]
+fn public_v0_3_5_pre_002_slot_lifecycle_contract_is_available_from_crate_root() {
+    let event = ksp_interface_lib::SlotLifecycleEvent::new(u64::MAX, ksp_interface_lib::SlotLifecycleStage::Rooted);
+
+    assert_eq!(event.slot(), u64::MAX);
+    assert_eq!(event.stage(), ksp_interface_lib::SlotLifecycleStage::Rooted);
+}
+
+#[test]
+fn public_v0_3_5_pre_002_slot_lifecycle_stage_remains_downstream_evolvable() {
+    fn stage_label(stage: ksp_interface_lib::SlotLifecycleStage) -> &'static str {
+        return match stage {
+            ksp_interface_lib::SlotLifecycleStage::Processed => "processed",
+            ksp_interface_lib::SlotLifecycleStage::FirstShredReceived => "first_shred_received",
+            ksp_interface_lib::SlotLifecycleStage::Completed => "completed",
+            ksp_interface_lib::SlotLifecycleStage::CreatedBank => "created_bank",
+            ksp_interface_lib::SlotLifecycleStage::Dead => "dead",
+            ksp_interface_lib::SlotLifecycleStage::OptimisticallyConfirmed => "optimistically_confirmed",
+            ksp_interface_lib::SlotLifecycleStage::Rooted => "rooted",
+            _ => "future",
+        };
+    }
+
+    assert_eq!(stage_label(ksp_interface_lib::SlotLifecycleStage::Processed), "processed");
+    assert_eq!(stage_label(ksp_interface_lib::SlotLifecycleStage::Rooted), "rooted");
+}

crates/ksp-interface-lib/unit_tests/slot_lifecycle.rs

@@ -0,0 +1,52 @@
+// file: crates/ksp-interface-lib/unit_tests/slot_lifecycle.rs
+// version: 1
+
+#[test]
+fn slot_lifecycle_stages_are_distinct_copy_and_complete_for_the_admitted_family() {
+    fn assert_copy<T: Copy>() {}
+
+    assert_copy::<crate::SlotLifecycleStage>();
+
+    let stages = [
+        crate::SlotLifecycleStage::Processed,
+        crate::SlotLifecycleStage::FirstShredReceived,
+        crate::SlotLifecycleStage::Completed,
+        crate::SlotLifecycleStage::CreatedBank,
+        crate::SlotLifecycleStage::Dead,
+        crate::SlotLifecycleStage::OptimisticallyConfirmed,
+        crate::SlotLifecycleStage::Rooted,
+    ];
+
+    for (index, stage) in stages.iter().enumerate() {
+        for other in stages.iter().skip(index + 1) {
+            assert_ne!(stage, other);
+        }
+    }
+}
+
+#[test]
+fn slot_lifecycle_event_preserves_full_u64_slot_and_stage() {
+    fn assert_copy<T: Copy>() {}
+
+    assert_copy::<crate::SlotLifecycleEvent>();
+
+    let event = crate::SlotLifecycleEvent::new(u64::MAX, crate::SlotLifecycleStage::Rooted);
+
+    assert_eq!(event.slot(), u64::MAX);
+    assert_eq!(event.stage(), crate::SlotLifecycleStage::Rooted);
+    let copied = event;
+    assert_eq!(event, copied);
+}
+
+#[test]
+fn slot_lifecycle_debug_is_bounded_and_contains_only_shared_fields() {
+    let event = crate::SlotLifecycleEvent::new(42, crate::SlotLifecycleStage::OptimisticallyConfirmed);
+    let debug = std::format!("{event:?}");
+
+    assert!(debug.len() <= 128);
+    assert!(debug.contains("slot: 42"));
+    assert!(debug.contains("OptimisticallyConfirmed"));
+    assert!(!debug.contains("provider"));
+    assert!(!debug.contains("yellowstone"));
+    assert!(!debug.contains("websocket"));
+}