v0.3.6-pre.008

crates/ksp-job-backfill-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-job-backfill-lib/src/lib.rs
-// version: 3
+// version: 4
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -10,16 +10,21 @@
 //! This tranche owns explicit admission, network-scoped candidate identity, deterministic
 //! `getSignaturesForAddress` pagination and canonical RAW v1 conversion through observed
 //! `getTransaction`. Transport retains provider/endpoint selection and retry; Store retains
-//! durable idempotence through the atomic Store facade. Concurrency, checkpointing, cancellation
-//! and concrete latest-value snapshots are added by later v0.3.6 tranches.
+//! durable idempotence through the atomic Store facade. This tranche also owns bounded concurrent
+//! candidate execution and caller-owned contiguous checkpoints. Cancellation and concrete latest-value
+//! snapshots are added by later v0.3.6 tranches.
 
+mod checkpoint;
 mod constants;
 mod conversion;
 mod discovery;
 mod error;
+mod execution;
 mod persistence;
 mod request;
 
+/// Opaque caller-owned checkpoint for one controlled Backfill resumption.
+pub use self::checkpoint::BackfillCheckpoint;
 /// Result of hydrating one deterministic candidate through observed `getTransaction`.
 pub use self::conversion::BackfillHydrationOutcome;
 /// Complete in-memory RAW transaction acquisition ready for later Store persistence.
@@ -40,10 +45,14 @@ pub use self::discovery::BackfillDiscovery;
 pub use self::discovery::BackfillDiscoveryBoundary;
 /// Discovers one bounded deterministic candidate set through the typed KSP Transport wrapper.
 pub use self::discovery::discover_backfill_candidates;
+/// Error code used when one checkpoint/frontier is incompatible with the current Job or semantic scope.
+pub use self::error::ERROR_CODE_BACKFILL_CHECKPOINT_INVALID;
 /// Error code used when a signature page violates a bounded discovery invariant.
 pub use self::error::ERROR_CODE_BACKFILL_DISCOVERY_INVALID;
 /// Error code used when paginated discovery cannot advance its exclusive RPC cursor safely.
 pub use self::error::ERROR_CODE_BACKFILL_DISCOVERY_STALLED;
+/// Error code used when bounded concurrent execution violates an internal admission or clock invariant.
+pub use self::error::ERROR_CODE_BACKFILL_EXECUTION_INVALID;
 /// Error code used when Store persistence returns an impossible Backfill state or targets a different network.
 pub use self::error::ERROR_CODE_BACKFILL_PERSISTENCE_INVALID;
 /// Error code used when deterministic Transport-to-RAW conversion violates the v1 contract.
@@ -52,6 +61,10 @@ pub use self::error::ERROR_CODE_BACKFILL_RAW_CONVERSION_INVALID;
 pub use self::error::ERROR_CODE_BACKFILL_REQUEST_INVALID;
 /// Error code used when one transaction signature text violates the bounded Base58-shape contract.
 pub use self::error::ERROR_CODE_BACKFILL_SIGNATURE_INVALID;
+/// Bounded result of one concurrent Backfill candidate execution pass.
+pub use self::execution::BackfillExecutionBatch;
+/// Executes one bounded discovered candidate set with request-owned hydration concurrency.
+pub use self::execution::execute_backfill_discovery;
 /// Canonical entity disposition produced by one Backfill Store persistence attempt.
 pub use self::persistence::BackfillEntityPersistence;
 /// Observation disposition produced by one Backfill Store persistence attempt.
@@ -85,6 +98,18 @@ pub use self::request::MAX_BACKFILL_SIGNATURE_TEXT_BYTES;
 /// Minimum Base58 text length possible for one canonical 64-byte Solana signature.
 pub use self::request::MIN_BACKFILL_SIGNATURE_TEXT_BYTES;
 
+/// Internal contiguous completion frontier used by bounded execution.
+pub(crate) use self::checkpoint::CompletionFrontier;
+/// Builds one safe caller-owned checkpoint from the current contiguous frontier.
+pub(crate) use self::checkpoint::checkpoint_from_frontier;
+/// Resolves the candidate offset skipped by one validated replay checkpoint.
+pub(crate) use self::checkpoint::execution_resume_offset;
+/// Resolves the internal exclusive Before cursor for discovery resumption.
+pub(crate) use self::checkpoint::resume_before_cursor;
+/// Validates that one discovery result belongs to the current request identity.
+pub(crate) use self::checkpoint::validate_discovery_identity;
+/// Validates one caller-owned checkpoint against Job and semantic scope identity.
+pub(crate) use self::checkpoint::validate_request_checkpoint;
 /// Owning tracing target used by the concrete Backfill runtime.
 pub(crate) use self::constants::TRACING_TARGET;
 /// Exact private Base58 decoder shared by the public signature wrapper and hydration path.