v0.3.11-pre.003

crates/ksp-worker-raw-transaction-ingest-lib/src/error.rs

@@ -0,0 +1,12 @@
+// file: crates/ksp-worker-raw-transaction-ingest-lib/src/error.rs
+// version: 2
+
+/// Error code used when RAW transaction ingest Worker settings violate one bounded runtime invariant.
+pub const ERROR_CODE_RAW_TRANSACTION_INGEST_SETTINGS_INVALID: ksp_core_lib::ErrorCode =
+    ksp_core_lib::ErrorCode::new("worker_raw_transaction_ingest", "settings_invalid");
+
+/// Creates one settings-domain error carrying only the stable invalid field name.
+pub(crate) fn settings_error(field: &'static str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_RAW_TRANSACTION_INGEST_SETTINGS_INVALID, "invalid RAW transaction ingest Worker settings")
+        .with_context("field", field);
+}

crates/ksp-worker-raw-transaction-ingest-lib/src/identity.rs

@@ -0,0 +1,5 @@
+// file: crates/ksp-worker-raw-transaction-ingest-lib/src/identity.rs
+// version: 1
+
+/// Stable Worker kind code used by the continuous RAW transaction ingest vertical.
+pub const RAW_TRANSACTION_INGEST_WORKER_KIND_CODE: &str = "raw_transaction_ingest";

crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs
-// version: 1
+// version: 2
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -7,6 +7,38 @@
 
 //! Source-neutral runtime foundation for continuous KSP RAW transaction ingestion.
 //!
-//! The crate is intentionally limited to its dependency skeleton in this tranche.
-//! Worker identity, settings, lifecycle, tasks, admission, persistence and snapshots
-//! are introduced only by their dedicated prereleases.
+//! This tranche owns only the concrete Worker family identity and validated technical
+//! settings. Lifecycle, tasks, admission, persistence and snapshots are introduced only
+//! by their dedicated prereleases; no live source or Transport dependency exists here.
+
+mod error;
+mod identity;
+mod settings;
+
+/// Error code used when RAW transaction ingest Worker settings violate one bounded runtime invariant.
+pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_SETTINGS_INVALID;
+/// Stable Worker kind code used by the continuous RAW transaction ingest vertical.
+pub use self::identity::RAW_TRANSACTION_INGEST_WORKER_KIND_CODE;
+/// Default bounded admission queue capacity for one RAW transaction ingest Worker.
+pub use self::settings::DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY;
+/// Default number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub use self::settings::DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY;
+/// Default cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub use self::settings::DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT;
+/// Maximum bounded admission queue capacity for one RAW transaction ingest Worker.
+pub use self::settings::MAX_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY;
+/// Maximum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub use self::settings::MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY;
+/// Maximum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub use self::settings::MAX_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT;
+/// Minimum bounded admission queue capacity for one RAW transaction ingest Worker.
+pub use self::settings::MIN_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY;
+/// Minimum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub use self::settings::MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY;
+/// Minimum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub use self::settings::MIN_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT;
+/// Validated source-neutral runtime settings for one continuous RAW transaction ingest Worker.
+pub use self::settings::RawTransactionIngestSettings;
+
+/// Creates one settings-domain error without copying caller-supplied values into diagnostics.
+pub(crate) use self::error::settings_error;

crates/ksp-worker-raw-transaction-ingest-lib/src/settings.rs

@@ -0,0 +1,127 @@
+// file: crates/ksp-worker-raw-transaction-ingest-lib/src/settings.rs
+// version: 3
+
+/// Default bounded admission queue capacity for one RAW transaction ingest Worker.
+pub const DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY: usize = 256;
+/// Default number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub const DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY: usize = 8;
+/// Default cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub const DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
+/// Maximum bounded admission queue capacity for one RAW transaction ingest Worker.
+pub const MAX_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY: usize = 65_536;
+/// Maximum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub const MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY: usize = 64;
+/// Maximum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub const MAX_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
+/// Minimum bounded admission queue capacity for one RAW transaction ingest Worker.
+pub const MIN_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY: usize = 1;
+/// Minimum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
+pub const MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY: usize = 1;
+/// Minimum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
+pub const MIN_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT: std::time::Duration = std::time::Duration::from_millis(100);
+
+/// Validated source-neutral runtime settings for one continuous RAW transaction ingest Worker.
+#[derive(Clone, Eq, PartialEq)]
+pub struct RawTransactionIngestSettings {
+    network: ksp_store_lib::RawNetworkId,
+    worker_id: ksp_worker_api::WorkerId,
+    admission_queue_capacity: usize,
+    persistence_concurrency: usize,
+    shutdown_drain_timeout: std::time::Duration,
+}
+
+impl crate::RawTransactionIngestSettings {
+    /// Creates settings from validated network/Worker identities and explicit bounded runtime limits.
+    pub fn new(
+        network: ksp_store_lib::RawNetworkId,
+        worker_id: ksp_worker_api::WorkerId,
+        admission_queue_capacity: usize,
+        persistence_concurrency: usize,
+        shutdown_drain_timeout: std::time::Duration,
+    ) -> ksp_core_lib::Result<Self> {
+        validate_inclusive_usize(
+            admission_queue_capacity,
+            crate::MIN_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            crate::MAX_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            "admission_queue_capacity",
+        )?;
+        validate_inclusive_usize(
+            persistence_concurrency,
+            crate::MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            crate::MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            "persistence_concurrency",
+        )?;
+        if !(crate::MIN_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT..=crate::MAX_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT)
+            .contains(&shutdown_drain_timeout)
+        {
+            return std::result::Result::Err(crate::settings_error("shutdown_drain_timeout"));
+        }
+        return std::result::Result::Ok(Self { network, worker_id, admission_queue_capacity, persistence_concurrency, shutdown_drain_timeout });
+    }
+
+    /// Creates settings using the stable V1 runtime defaults for one validated network and Worker identity.
+    #[must_use]
+    pub fn with_defaults(network: ksp_store_lib::RawNetworkId, worker_id: ksp_worker_api::WorkerId) -> Self {
+        return Self {
+            network,
+            worker_id,
+            admission_queue_capacity: crate::DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            persistence_concurrency: crate::DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            shutdown_drain_timeout: crate::DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT,
+        };
+    }
+
+    /// Returns the Store-compatible logical network binding.
+    #[must_use]
+    pub const fn network(&self) -> &ksp_store_lib::RawNetworkId {
+        return &self.network;
+    }
+
+    /// Returns the validated logical identity of this Worker instance.
+    #[must_use]
+    pub const fn worker_id(&self) -> &ksp_worker_api::WorkerId {
+        return &self.worker_id;
+    }
+
+    /// Returns the bounded central admission queue capacity.
+    #[must_use]
+    pub const fn admission_queue_capacity(&self) -> usize {
+        return self.admission_queue_capacity;
+    }
+
+    /// Returns the bounded maximum number of concurrent Store persistence operations.
+    #[must_use]
+    pub const fn persistence_concurrency(&self) -> usize {
+        return self.persistence_concurrency;
+    }
+
+    /// Returns the bounded cooperative shutdown drain deadline.
+    #[must_use]
+    pub const fn shutdown_drain_timeout(&self) -> std::time::Duration {
+        return self.shutdown_drain_timeout;
+    }
+}
+
+impl std::fmt::Debug for crate::RawTransactionIngestSettings {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter
+            .debug_struct("RawTransactionIngestSettings")
+            .field("network", &self.network)
+            .field("worker_id", &self.worker_id)
+            .field("admission_queue_capacity", &self.admission_queue_capacity)
+            .field("persistence_concurrency", &self.persistence_concurrency)
+            .field("shutdown_drain_timeout", &self.shutdown_drain_timeout)
+            .finish();
+    }
+}
+
+fn validate_inclusive_usize(value: usize, minimum: usize, maximum: usize, field: &'static str) -> ksp_core_lib::Result<()> {
+    if !(minimum..=maximum).contains(&value) {
+        return std::result::Result::Err(crate::settings_error(field));
+    }
+    return std::result::Result::Ok(());
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/settings.rs"]
+mod tests;

crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs

@@ -1,7 +1,7 @@
 // file: crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs
-// version: 1
+// version: 2
 
-//! Dependency firewall canaries for the RAW transaction ingest Worker skeleton.
+//! Dependency firewall canaries for the RAW transaction ingest Worker foundation.
 
 #[test]
 fn pre_002_manifest_dependency_surface_is_exact() {
@@ -46,28 +46,26 @@ fn pre_002_manifest_keeps_forbidden_layers_and_live_sources_out() {
     ] {
         assert!(!dependencies.contains(forbidden), "forbidden Worker dependency present: {forbidden}");
     }
-    assert!(!manifest.contains("[dev-dependencies]"), "pre.002 requires no test-only dependency");
-    assert!(!manifest.contains("[build-dependencies]"), "pre.002 requires no build dependency");
+    assert!(!manifest.contains("[dev-dependencies]"), "foundation requires no test-only dependency");
+    assert!(!manifest.contains("[build-dependencies]"), "foundation requires no build dependency");
     return;
 }
 
 #[test]
-fn pre_002_crate_root_contains_no_runtime_behavior_or_public_contract_yet() {
+fn pre_003_source_surface_opens_identity_and_settings_without_runtime_behavior() {
     let root = include_str!("../src/lib.rs");
-    for forbidden in [
-        "pub mod ",
-        "pub struct ",
-        "pub enum ",
-        "pub trait ",
-        "pub fn ",
-        "tokio::",
-        "ksp_store_lib::",
-        "ksp_raw_transaction_lib::",
-        "ksp_worker_api::",
-        "start(",
-        "spawn(",
+    for required in [
+        "mod error;",
+        "mod identity;",
+        "mod settings;",
+        "pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_SETTINGS_INVALID;",
+        "pub use self::identity::RAW_TRANSACTION_INGEST_WORKER_KIND_CODE;",
+        "pub use self::settings::RawTransactionIngestSettings;",
     ] {
-        assert!(!root.contains(forbidden), "pre.002 crate root opened behavior too early: {forbidden}");
+        assert!(root.contains(required), "required pre.003 crate-root contract missing: {required}");
+    }
+    for forbidden in ["pub mod ", "tokio::", "start(", "spawn(", "JoinHandle", "JoinSet", "mpsc::", "watch::", "ksp_onchain_transport_lib::"] {
+        assert!(!root.contains(forbidden), "pre.003 opened runtime behavior too early: {forbidden}");
     }
     return;
 }

crates/ksp-worker-raw-transaction-ingest-lib/tests/public_api.rs

@@ -0,0 +1,74 @@
+// file: crates/ksp-worker-raw-transaction-ingest-lib/tests/public_api.rs
+// version: 4
+
+//! External public-surface proofs for the RAW transaction ingest Worker identity and settings foundation.
+
+#[test]
+fn pre_003_kind_code_and_settings_are_consumable_from_crate_root() {
+    assert_eq!(ksp_worker_raw_transaction_ingest_lib::RAW_TRANSACTION_INGEST_WORKER_KIND_CODE, "raw_transaction_ingest");
+    let kind_result = ksp_worker_api::WorkerKindCode::new(ksp_worker_raw_transaction_ingest_lib::RAW_TRANSACTION_INGEST_WORKER_KIND_CODE);
+    assert!(kind_result.is_ok());
+    let kind = match kind_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    assert_eq!(kind.as_str(), "raw_transaction_ingest");
+    let network = match ksp_store_lib::RawNetworkId::new("mainnet") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    let worker_id = match ksp_worker_api::WorkerId::new("raw-ingest-mainnet-001") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    let settings = ksp_worker_raw_transaction_ingest_lib::RawTransactionIngestSettings::with_defaults(network, worker_id);
+    assert_eq!(settings.network().as_str(), "mainnet");
+    assert_eq!(settings.worker_id().as_str(), "raw-ingest-mainnet-001");
+    assert_eq!(settings.admission_queue_capacity(), ksp_worker_raw_transaction_ingest_lib::DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY);
+    assert_eq!(settings.persistence_concurrency(), ksp_worker_raw_transaction_ingest_lib::DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY);
+    assert_eq!(settings.shutdown_drain_timeout(), ksp_worker_raw_transaction_ingest_lib::DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT);
+    return;
+}
+
+#[test]
+fn pre_003_invalid_network_and_worker_identity_remain_owned_by_lower_contracts() {
+    let network = ksp_store_lib::RawNetworkId::new("");
+    let worker_id = ksp_worker_api::WorkerId::new("invalid worker id");
+    assert!(network.is_err());
+    assert!(worker_id.is_err());
+    let network_error = match network {
+        std::result::Result::Ok(_) => return,
+        std::result::Result::Err(value) => value,
+    };
+    assert_eq!(network_error.code(), ksp_store_lib::ERROR_CODE_RAW_MODEL_INVALID);
+    let worker_error = match worker_id {
+        std::result::Result::Ok(_) => return,
+        std::result::Result::Err(value) => value,
+    };
+    assert_eq!(worker_error.code(), ksp_worker_api::ERROR_CODE_WORKER_ID_INVALID);
+    return;
+}
+
+#[test]
+fn pre_003_runtime_bound_errors_are_stable_and_do_not_echo_values() {
+    let network = match ksp_store_lib::RawNetworkId::new("mainnet") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    let worker_id = match ksp_worker_api::WorkerId::new("raw-ingest-mainnet-001") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    let result = ksp_worker_raw_transaction_ingest_lib::RawTransactionIngestSettings::new(network, worker_id, 0, 8, std::time::Duration::from_secs(5));
+    assert!(result.is_err());
+    let error = match result {
+        std::result::Result::Ok(_) => return,
+        std::result::Result::Err(value) => value,
+    };
+    assert_eq!(error.code(), ksp_worker_raw_transaction_ingest_lib::ERROR_CODE_RAW_TRANSACTION_INGEST_SETTINGS_INVALID);
+    assert_eq!(error.message(), "invalid RAW transaction ingest Worker settings");
+    assert_eq!(error.context().len(), 1);
+    assert_eq!(error.context()[0].value(), "admission_queue_capacity");
+    assert!(!std::format!("{error:?}").contains("raw-ingest-mainnet-001"));
+    return;
+}

crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/settings.rs

@@ -0,0 +1,105 @@
+// file: crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/settings.rs
+// version: 2
+
+fn identities() -> std::option::Option<(ksp_store_lib::RawNetworkId, ksp_worker_api::WorkerId)> {
+    let network_result = ksp_store_lib::RawNetworkId::new("mainnet");
+    assert!(network_result.is_ok());
+    let network = match network_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::option::Option::None,
+    };
+    let worker_id_result = ksp_worker_api::WorkerId::new("raw-ingest-mainnet-001");
+    assert!(worker_id_result.is_ok());
+    let worker_id = match worker_id_result {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return std::option::Option::None,
+    };
+    return std::option::Option::Some((network, worker_id));
+}
+
+#[test]
+fn pre_003_defaults_are_exact_and_preserve_typed_identity() {
+    let (network, worker_id) = match identities() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let settings = crate::RawTransactionIngestSettings::with_defaults(network.clone(), worker_id.clone());
+    assert_eq!(settings.network(), &network);
+    assert_eq!(settings.worker_id(), &worker_id);
+    assert_eq!(settings.admission_queue_capacity(), 256);
+    assert_eq!(settings.persistence_concurrency(), 8);
+    assert_eq!(settings.shutdown_drain_timeout(), std::time::Duration::from_secs(5));
+    assert_eq!(crate::DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY, 256);
+    assert_eq!(crate::DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY, 8);
+    assert_eq!(crate::DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT, std::time::Duration::from_secs(5));
+    return;
+}
+
+#[test]
+fn pre_003_inclusive_bounds_accept_exact_minimum_and_maximum() {
+    for (queue, concurrency, drain) in [
+        (
+            crate::MIN_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            crate::MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            crate::MIN_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT,
+        ),
+        (
+            crate::MAX_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY,
+            crate::MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY,
+            crate::MAX_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT,
+        ),
+    ] {
+        let (network, worker_id) = match identities() {
+            std::option::Option::Some(value) => value,
+            std::option::Option::None => return,
+        };
+        let settings = crate::RawTransactionIngestSettings::new(network, worker_id, queue, concurrency, drain);
+        assert!(settings.is_ok());
+    }
+    return;
+}
+
+#[test]
+fn pre_003_invalid_runtime_bounds_return_stable_field_scoped_error() {
+    let invalid = [
+        (0, 8, std::time::Duration::from_secs(5), "admission_queue_capacity"),
+        (65_537, 8, std::time::Duration::from_secs(5), "admission_queue_capacity"),
+        (256, 0, std::time::Duration::from_secs(5), "persistence_concurrency"),
+        (256, 65, std::time::Duration::from_secs(5), "persistence_concurrency"),
+        (256, 8, std::time::Duration::from_millis(99), "shutdown_drain_timeout"),
+        (256, 8, std::time::Duration::from_millis(30_001), "shutdown_drain_timeout"),
+    ];
+    for (queue, concurrency, drain, field) in invalid {
+        let (network, worker_id) = match identities() {
+            std::option::Option::Some(value) => value,
+            std::option::Option::None => return,
+        };
+        let result = crate::RawTransactionIngestSettings::new(network, worker_id, queue, concurrency, drain);
+        assert!(result.is_err());
+        let error = match result {
+            std::result::Result::Ok(_) => continue,
+            std::result::Result::Err(value) => value,
+        };
+        assert_eq!(error.code(), crate::ERROR_CODE_RAW_TRANSACTION_INGEST_SETTINGS_INVALID);
+        assert_eq!(error.code().domain(), "worker_raw_transaction_ingest");
+        assert_eq!(error.code().code(), "settings_invalid");
+        assert_eq!(error.context().len(), 1);
+        assert_eq!(error.context()[0].key(), "field");
+        assert_eq!(error.context()[0].value(), field);
+    }
+    return;
+}
+
+#[test]
+fn pre_003_debug_keeps_worker_identity_redacted() {
+    let (network, worker_id) = match identities() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return,
+    };
+    let settings = crate::RawTransactionIngestSettings::with_defaults(network, worker_id);
+    let rendered = std::format!("{settings:?}");
+    assert!(rendered.contains("mainnet"));
+    assert!(rendered.contains("WorkerId(..)"));
+    assert!(!rendered.contains("raw-ingest-mainnet-001"));
+    return;
+}