v0.3.14-pre.005

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

@@ -1,6 +1,8 @@
 // file: crates/ksp-worker-raw-transaction-ingest-lib/src/continuity.rs
-// version: 4
+// version: 5
 
+/// Maximum number of proven redundant coverage epochs retained by one run-local continuity contract.
+const MAX_RAW_TRANSACTION_INGEST_COVERAGE_EPOCHS: usize = 256;
 /// Maximum number of simultaneously retained non-repaired run-local gaps.
 const MAX_RAW_TRANSACTION_INGEST_OPEN_REPAIR_GAPS: usize = 64;
 /// Maximum number of run-local gaps that may actively repair at once.
@@ -23,6 +25,12 @@ pub(crate) enum RawTransactionIngestCoverageScope {
     KnownReferences([u8; 32]),
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum RawTransactionIngestCoverageRelation {
+    Exact,
+    Superset,
+}
+
 impl crate::RawTransactionIngestCoverageScope {
     /// Creates one provider-neutral exact source scope from a stable family code and semantic fingerprint.
     pub(crate) const fn exact_source_scope(family_code: &'static str, fingerprint: [u8; 32]) -> Self {
@@ -54,6 +62,19 @@ impl crate::RawTransactionIngestCoverageScope {
     fn is_known_references(&self) -> bool {
         return matches!(self, Self::KnownReferences(_));
     }
+
+    fn relation_to(&self, requirement: &Self) -> std::option::Option<RawTransactionIngestCoverageRelation> {
+        return match (self, requirement) {
+            (Self::FullLedgerTransactions, Self::FullLedgerTransactions) => std::option::Option::Some(RawTransactionIngestCoverageRelation::Exact),
+            (Self::FullLedgerTransactions, Self::ExactSourceScope(_, _)) => std::option::Option::Some(RawTransactionIngestCoverageRelation::Superset),
+            (Self::ExactSourceScope(family_code, fingerprint), Self::ExactSourceScope(required_family_code, required_fingerprint))
+                if family_code == required_family_code && fingerprint == required_fingerprint =>
+            {
+                std::option::Option::Some(RawTransactionIngestCoverageRelation::Exact)
+            },
+            _ => std::option::Option::None,
+        };
+    }
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -424,14 +445,14 @@ impl RawTransactionIngestTargetCoverage {
         if scope.is_known_references() {
             return std::result::Result::Err(crate::runtime_error("continuity.known_references_not_target_scope"));
         }
-        if matches!(&scope, crate::RawTransactionIngestCoverageScope::FullLedgerTransactions) {
-            self.requirements.retain(|requirement| return requirement.commitment != commitment);
-            self.requirements.push(RawTransactionIngestCoverageRequirement { commitment, scope });
-            return std::result::Result::Ok(());
-        }
+        self.requirements.retain(|requirement| {
+            if requirement.commitment != commitment {
+                return true;
+            }
+            return scope.relation_to(&requirement.scope) != std::option::Option::Some(RawTransactionIngestCoverageRelation::Superset);
+        });
         if self.requirements.iter().any(|requirement| {
-            return requirement.commitment == commitment
-                && (requirement.scope == crate::RawTransactionIngestCoverageScope::FullLedgerTransactions || requirement.scope == scope);
+            return requirement.commitment == commitment && requirement.scope.relation_to(&scope).is_some();
         }) {
             return std::result::Result::Ok(());
         }
@@ -440,9 +461,133 @@ impl RawTransactionIngestTargetCoverage {
     }
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+struct RawTransactionIngestCoverageRange {
+    end_slot: u64,
+    start_slot: u64,
+}
+
+impl RawTransactionIngestCoverageRange {
+    fn new(start_slot: u64, end_slot: u64) -> ksp_core_lib::Result<Self> {
+        if end_slot < start_slot {
+            return std::result::Result::Err(crate::runtime_error("continuity.coverage_range_reversed"));
+        }
+        return std::result::Result::Ok(Self { end_slot, start_slot });
+    }
+
+    const fn contains_gap(self, gap: RawTransactionIngestGapRange) -> bool {
+        return self.start_slot <= gap.start_slot() && self.end_slot >= gap.end_slot();
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct RawTransactionIngestCoverageEpoch {
+    commitment: ksp_onchain_transport_lib::SolanaCommitment,
+    epoch_id: u64,
+    range: RawTransactionIngestCoverageRange,
+    scope: crate::RawTransactionIngestCoverageScope,
+    source_key: [u8; 32],
+}
+
+impl RawTransactionIngestCoverageEpoch {
+    fn new(
+        epoch_id: u64,
+        source_key: [u8; 32],
+        commitment: ksp_onchain_transport_lib::SolanaCommitment,
+        scope: crate::RawTransactionIngestCoverageScope,
+        range: RawTransactionIngestCoverageRange,
+    ) -> ksp_core_lib::Result<Self> {
+        if epoch_id == 0 {
+            return std::result::Result::Err(crate::runtime_error("continuity.coverage_epoch_id_invalid"));
+        }
+        if let std::result::Result::Err(error) = scope.validate_configured_target_scope() {
+            return std::result::Result::Err(error);
+        }
+        return std::result::Result::Ok(Self { commitment, epoch_id, range, scope, source_key });
+    }
+
+    fn relation_to_requirement(
+        &self,
+        target_source_key: [u8; 32],
+        requirement: &RawTransactionIngestCoverageRequirement,
+        gap: RawTransactionIngestGapRange,
+    ) -> std::option::Option<RawTransactionIngestCoverageRelation> {
+        if self.source_key == target_source_key || self.commitment != requirement.commitment || !self.range.contains_gap(gap) {
+            return std::option::Option::None;
+        }
+        return self.scope.relation_to(&requirement.scope);
+    }
+}
+
+struct RawTransactionIngestCoverageEpochLedger {
+    epochs: std::vec::Vec<RawTransactionIngestCoverageEpoch>,
+    next_epoch_id: u64,
+}
+
+impl RawTransactionIngestCoverageEpochLedger {
+    fn new() -> Self {
+        return Self { epochs: std::vec::Vec::new(), next_epoch_id: 1 };
+    }
+
+    fn redundant_relation_for_gap(
+        &self,
+        target_source_key: [u8; 32],
+        requirement: &RawTransactionIngestCoverageRequirement,
+        gap: RawTransactionIngestGapRange,
+    ) -> std::option::Option<RawTransactionIngestCoverageRelation> {
+        let mut exact = false;
+        for epoch in &self.epochs {
+            match epoch.relation_to_requirement(target_source_key, requirement, gap) {
+                std::option::Option::Some(RawTransactionIngestCoverageRelation::Superset) => {
+                    return std::option::Option::Some(RawTransactionIngestCoverageRelation::Superset);
+                },
+                std::option::Option::Some(RawTransactionIngestCoverageRelation::Exact) => exact = true,
+                std::option::Option::None => {},
+            }
+        }
+        if exact {
+            return std::option::Option::Some(RawTransactionIngestCoverageRelation::Exact);
+        }
+        return std::option::Option::None;
+    }
+
+    fn validate_invariants(&self, capabilities: &[crate::RawTransactionIngestContinuityCapabilityDescriptor]) -> ksp_core_lib::Result<()> {
+        if self.next_epoch_id == 0 || self.epochs.len() > MAX_RAW_TRANSACTION_INGEST_COVERAGE_EPOCHS {
+            return std::result::Result::Err(crate::runtime_error("continuity.coverage_epoch_inventory_invalid"));
+        }
+        let mut ids = std::collections::BTreeSet::new();
+        let mut highest_epoch_id = 0_u64;
+        for epoch in &self.epochs {
+            if epoch.epoch_id == 0 || !ids.insert(epoch.epoch_id) {
+                return std::result::Result::Err(crate::runtime_error("continuity.coverage_epoch_id_invalid"));
+            }
+            highest_epoch_id = highest_epoch_id.max(epoch.epoch_id);
+            if let std::result::Result::Err(error) = epoch.scope.validate_configured_target_scope() {
+                return std::result::Result::Err(error);
+            }
+            if RawTransactionIngestCoverageRange::new(epoch.range.start_slot, epoch.range.end_slot).is_err() {
+                return std::result::Result::Err(crate::runtime_error("continuity.coverage_epoch_range_invalid"));
+            }
+            let matching_capability = capabilities.iter().find(|capability| return capability.source_key == epoch.source_key);
+            let matching_capability = match matching_capability {
+                std::option::Option::Some(value) => value,
+                std::option::Option::None => return std::result::Result::Err(crate::runtime_error("continuity.coverage_epoch_source_unknown")),
+            };
+            if matching_capability.commitment != epoch.commitment || matching_capability.source_scope != epoch.scope {
+                return std::result::Result::Err(crate::runtime_error("continuity.coverage_epoch_capability_mismatch"));
+            }
+        }
+        if !self.epochs.is_empty() && self.next_epoch_id <= highest_epoch_id {
+            return std::result::Result::Err(crate::runtime_error("continuity.coverage_epoch_next_id_invalid"));
+        }
+        return std::result::Result::Ok(());
+    }
+}
+
 /// Run-local continuity contracts prepared from the exact caller-composed live-source aggregate before productive source execution.
 pub(crate) struct RawTransactionIngestContinuityContracts {
     capabilities: std::vec::Vec<crate::RawTransactionIngestContinuityCapabilityDescriptor>,
+    coverage_epochs: RawTransactionIngestCoverageEpochLedger,
     gap_ledger: RawTransactionIngestGapLedger,
     target_coverage: RawTransactionIngestTargetCoverage,
 }
@@ -470,11 +615,15 @@ impl crate::RawTransactionIngestContinuityContracts {
             std::result::Result::Ok(value) => value,
             std::result::Result::Err(error) => return std::result::Result::Err(error),
         };
+        let coverage_epochs = RawTransactionIngestCoverageEpochLedger::new();
+        if let std::result::Result::Err(error) = coverage_epochs.validate_invariants(capabilities.as_slice()) {
+            return std::result::Result::Err(error);
+        }
         let gap_ledger = RawTransactionIngestGapLedger::new(network);
         if let std::result::Result::Err(error) = gap_ledger.validate_invariants() {
             return std::result::Result::Err(error);
         }
-        if !coverage_scope_catalog_is_complete() {
+        if !coverage_scope_catalog_is_complete() || !coverage_relation_catalog_is_complete() {
             return std::result::Result::Err(crate::runtime_error("continuity.coverage_scope_catalog_invalid"));
         }
         if MAX_RAW_TRANSACTION_INGEST_REPAIR_BLOCK_FETCH_IN_FLIGHT == 0
@@ -483,7 +632,7 @@ impl crate::RawTransactionIngestContinuityContracts {
         {
             return std::result::Result::Err(crate::runtime_error("continuity.repair_bounds_invalid"));
         }
-        return std::result::Result::Ok(Self { capabilities, gap_ledger, target_coverage });
+        return std::result::Result::Ok(Self { capabilities, coverage_epochs, gap_ledger, target_coverage });
     }
 
     /// Revalidates that the run-local contracts still correspond exactly to the caller-composed source count before tasks are spawned.
@@ -491,6 +640,9 @@ impl crate::RawTransactionIngestContinuityContracts {
         if self.capabilities.len() != expected_source_count || self.target_coverage.requirements.is_empty() {
             return std::result::Result::Err(crate::runtime_error("continuity.source_inventory_mismatch"));
         }
+        if let std::result::Result::Err(error) = self.coverage_epochs.validate_invariants(self.capabilities.as_slice()) {
+            return std::result::Result::Err(error);
+        }
         if let std::result::Result::Err(error) = self.gap_ledger.validate_invariants() {
             return std::result::Result::Err(error);
         }
@@ -510,6 +662,68 @@ fn coverage_scope_catalog_is_complete() -> bool {
         && known.is_known_references();
 }
 
+fn coverage_relation_catalog_is_complete() -> bool {
+    let target_scope = crate::RawTransactionIngestCoverageScope::ExactSourceScope("standard_logs", [7_u8; 32]);
+    let target_requirement =
+        RawTransactionIngestCoverageRequirement { commitment: ksp_onchain_transport_lib::SolanaCommitment::Confirmed, scope: target_scope.clone() };
+    let gap = match RawTransactionIngestGapRange::new(100, 110) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return false,
+    };
+    let full_range = match RawTransactionIngestCoverageRange::new(90, 120) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return false,
+    };
+    let partial_range = match RawTransactionIngestCoverageRange::new(100, 109) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return false,
+    };
+    let exact_epoch =
+        match RawTransactionIngestCoverageEpoch::new(1, [2_u8; 32], ksp_onchain_transport_lib::SolanaCommitment::Confirmed, target_scope, full_range) {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(_) => return false,
+        };
+    let full_epoch = match RawTransactionIngestCoverageEpoch::new(
+        2,
+        [3_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        crate::RawTransactionIngestCoverageScope::FullLedgerTransactions,
+        full_range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return false,
+    };
+    let cross_family_epoch = match RawTransactionIngestCoverageEpoch::new(
+        3,
+        [4_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        crate::RawTransactionIngestCoverageScope::ExactSourceScope("helius_transaction", [7_u8; 32]),
+        full_range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return false,
+    };
+    let partial_epoch = match RawTransactionIngestCoverageEpoch::new(
+        4,
+        [5_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        crate::RawTransactionIngestCoverageScope::FullLedgerTransactions,
+        partial_range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return false,
+    };
+    let ledger = RawTransactionIngestCoverageEpochLedger {
+        epochs: std::vec![exact_epoch.clone(), full_epoch.clone(), cross_family_epoch.clone(), partial_epoch.clone()],
+        next_epoch_id: 5,
+    };
+    return ledger.redundant_relation_for_gap([1_u8; 32], &target_requirement, gap)
+        == std::option::Option::Some(RawTransactionIngestCoverageRelation::Superset)
+        && exact_epoch.relation_to_requirement([2_u8; 32], &target_requirement, gap).is_none()
+        && cross_family_epoch.relation_to_requirement([1_u8; 32], &target_requirement, gap).is_none()
+        && partial_epoch.relation_to_requirement([1_u8; 32], &target_requirement, gap).is_none();
+}
+
 #[cfg(test)]
 #[path = "../unit_tests/continuity.rs"]
 mod tests;

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

@@ -1,7 +1,7 @@
 // file: crates/ksp-worker-raw-transaction-ingest-lib/tests/hardening.rs
-// version: 28
+// version: 29
 
-//! External public, security, redaction and release-boundary hardening canaries through `v0.3.14-pre.004`.
+//! External public, security, redaction and release-boundary hardening canaries through `v0.3.14-pre.005`.
 
 fn network(value: &'static str) -> std::option::Option<ksp_store_lib::RawNetworkId> {
     let result = ksp_store_lib::RawNetworkId::new(value);
@@ -1054,3 +1054,39 @@ fn v0_3_14_pre_004_yellowstone_replay_evidence_is_transport_owned_and_fail_close
     assert!(!transport.contains("replay_coverage_proven_count"));
     return;
 }
+
+#[test]
+fn v0_3_14_pre_005_redundant_coverage_requires_exact_or_superset_proof_over_full_range() {
+    let continuity = include_str!("../src/continuity.rs");
+    let root = include_str!("../src/lib.rs");
+    for required in [
+        "RawTransactionIngestCoverageRelation",
+        "RawTransactionIngestCoverageEpoch",
+        "RawTransactionIngestCoverageEpochLedger",
+        "MAX_RAW_TRANSACTION_INGEST_COVERAGE_EPOCHS",
+        "self.source_key == target_source_key",
+        "self.commitment != requirement.commitment",
+        "!self.range.contains_gap(gap)",
+        "family_code == required_family_code && fingerprint == required_fingerprint",
+        "RawTransactionIngestCoverageRelation::Superset",
+    ] {
+        assert!(continuity.contains(required), "required pre.005 conservative coverage guard missing: {required}");
+    }
+    for forbidden in [
+        "standard_logs\", \"helius_transaction",
+        "helius_transaction\", \"standard_logs",
+        "commitment >= requirement.commitment",
+        "commitment <= requirement.commitment",
+        "source_key == target_source_key &&",
+    ] {
+        assert!(!continuity.contains(forbidden), "pre.005 introduced opportunistic coverage equivalence: {forbidden}");
+    }
+    for forbidden_public in [
+        "pub use self::continuity::RawTransactionIngestCoverageRelation",
+        "pub use self::continuity::RawTransactionIngestCoverageEpoch",
+        "pub use self::continuity::RawTransactionIngestTargetCoverage",
+    ] {
+        assert!(!root.contains(forbidden_public), "pre.005 leaked private continuity proof type: {forbidden_public}");
+    }
+    return;
+}

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

@@ -1,7 +1,7 @@
 // file: crates/ksp-worker-raw-transaction-ingest-lib/tests/release_completeness.rs
-// version: 23
+// version: 24
 
-//! Release-completeness canaries through the `v0.3.14-pre.004` Yellowstone native replay-evidence tranche.
+//! Release-completeness canaries through the `v0.3.14-pre.005` redundant-coverage proof tranche.
 
 #[test]
 fn pre_010_production_module_inventory_is_exact() -> std::io::Result<()> {
@@ -263,3 +263,22 @@ fn v0_3_14_pre_004_native_replay_evidence_canaries_are_present_without_public_re
     assert!(!root.contains("set_from_slot"));
     return;
 }
+
+#[test]
+fn v0_3_14_pre_005_redundant_coverage_canaries_are_present_without_public_surface_growth() {
+    let continuity_tests = include_str!("../unit_tests/continuity.rs");
+    let hardening = include_str!("hardening.rs");
+    let root = include_str!("../src/lib.rs");
+    for required in [
+        "pre_005_scope_relations_are_exact_superset_and_cross_family_conservative",
+        "pre_005_coverage_epoch_requires_distinct_source_same_commitment_and_full_range",
+        "pre_005_cross_family_exact_scopes_never_become_redundant_by_fingerprint_alone",
+        "pre_005_coverage_epoch_ledger_is_bounded_monotone_and_capability_bound",
+    ] {
+        assert!(continuity_tests.contains(required), "required pre.005 continuity proof canary missing: {required}");
+    }
+    assert!(hardening.contains("v0_3_14_pre_005_redundant_coverage_requires_exact_or_superset_proof_over_full_range"));
+    assert!(!root.contains("pub use self::continuity::RawTransactionIngestCoverageEpoch"));
+    assert!(!root.contains("pub use self::continuity::RawTransactionIngestCoverageRelation"));
+    return;
+}

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

@@ -1,5 +1,5 @@
 // file: crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/continuity.rs
-// version: 3
+// version: 4
 
 fn network() -> std::option::Option<ksp_store_lib::RawNetworkId> {
     return match ksp_store_lib::RawNetworkId::new("mainnet") {
@@ -275,3 +275,181 @@ fn pre_003_websocket_incident_anchor_rejects_missing_reason_reversal_and_oversiz
     assert!(oversized.close_at(100 + super::MAX_RAW_TRANSACTION_INGEST_REPAIR_RANGE_SLOTS).is_err());
     return;
 }
+
+#[test]
+fn pre_005_scope_relations_are_exact_superset_and_cross_family_conservative() {
+    let exact = exact_scope("standard_logs", 7);
+    let same = exact_scope("standard_logs", 7);
+    let different_filter = exact_scope("standard_logs", 8);
+    let different_family = exact_scope("helius_transaction", 7);
+    let full = crate::RawTransactionIngestCoverageScope::full_ledger_transactions();
+    assert_eq!(exact.relation_to(&same), std::option::Option::Some(super::RawTransactionIngestCoverageRelation::Exact));
+    assert_eq!(full.relation_to(&exact), std::option::Option::Some(super::RawTransactionIngestCoverageRelation::Superset));
+    assert_eq!(full.relation_to(&full), std::option::Option::Some(super::RawTransactionIngestCoverageRelation::Exact));
+    assert!(exact.relation_to(&full).is_none());
+    assert!(exact.relation_to(&different_filter).is_none());
+    assert!(exact.relation_to(&different_family).is_none());
+    assert!(crate::RawTransactionIngestCoverageScope::KnownReferences([7_u8; 32]).relation_to(&exact).is_none());
+    return;
+}
+
+#[test]
+fn pre_005_coverage_epoch_requires_distinct_source_same_commitment_and_full_range() {
+    let target_requirement = super::RawTransactionIngestCoverageRequirement {
+        commitment: ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        scope: exact_scope("standard_logs", 9),
+    };
+    let gap = match super::RawTransactionIngestGapRange::new(100, 110) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected gap fixture failure: {error}"),
+    };
+    let full_range = match super::RawTransactionIngestCoverageRange::new(90, 120) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected coverage range failure: {error}"),
+    };
+    let partial_range = match super::RawTransactionIngestCoverageRange::new(100, 109) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected partial coverage range failure: {error}"),
+    };
+    let exact_epoch = match super::RawTransactionIngestCoverageEpoch::new(
+        1,
+        [2_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        exact_scope("standard_logs", 9),
+        full_range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected exact epoch failure: {error}"),
+    };
+    let full_epoch = match super::RawTransactionIngestCoverageEpoch::new(
+        2,
+        [3_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        crate::RawTransactionIngestCoverageScope::full_ledger_transactions(),
+        full_range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected full epoch failure: {error}"),
+    };
+    let partial_epoch = match super::RawTransactionIngestCoverageEpoch::new(
+        3,
+        [4_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        crate::RawTransactionIngestCoverageScope::full_ledger_transactions(),
+        partial_range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected partial epoch failure: {error}"),
+    };
+    let finalized_epoch = match super::RawTransactionIngestCoverageEpoch::new(
+        4,
+        [5_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Finalized,
+        crate::RawTransactionIngestCoverageScope::full_ledger_transactions(),
+        full_range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected finalized epoch failure: {error}"),
+    };
+    assert_eq!(
+        exact_epoch.relation_to_requirement([1_u8; 32], &target_requirement, gap),
+        std::option::Option::Some(super::RawTransactionIngestCoverageRelation::Exact),
+    );
+    assert_eq!(
+        full_epoch.relation_to_requirement([1_u8; 32], &target_requirement, gap),
+        std::option::Option::Some(super::RawTransactionIngestCoverageRelation::Superset),
+    );
+    assert!(exact_epoch.relation_to_requirement([2_u8; 32], &target_requirement, gap).is_none());
+    assert!(partial_epoch.relation_to_requirement([1_u8; 32], &target_requirement, gap).is_none());
+    assert!(finalized_epoch.relation_to_requirement([1_u8; 32], &target_requirement, gap).is_none());
+    return;
+}
+
+#[test]
+fn pre_005_cross_family_exact_scopes_never_become_redundant_by_fingerprint_alone() {
+    let target_requirement = super::RawTransactionIngestCoverageRequirement {
+        commitment: ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        scope: exact_scope("standard_logs", 11),
+    };
+    let gap = match super::RawTransactionIngestGapRange::new(500, 510) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected gap fixture failure: {error}"),
+    };
+    let range = match super::RawTransactionIngestCoverageRange::new(490, 520) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected coverage range failure: {error}"),
+    };
+    let epoch = match super::RawTransactionIngestCoverageEpoch::new(
+        1,
+        [2_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        exact_scope("helius_transaction", 11),
+        range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected epoch failure: {error}"),
+    };
+    assert!(epoch.relation_to_requirement([1_u8; 32], &target_requirement, gap).is_none());
+    return;
+}
+
+#[test]
+fn pre_005_coverage_epoch_ledger_is_bounded_monotone_and_capability_bound() {
+    assert_eq!(super::MAX_RAW_TRANSACTION_INGEST_COVERAGE_EPOCHS, 256);
+    let matching = match capability(2, ksp_onchain_transport_lib::SolanaCommitment::Confirmed, exact_scope("standard_logs", 5)) {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => panic!("matching capability fixture unavailable"),
+    };
+    let range = match super::RawTransactionIngestCoverageRange::new(100, 200) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected coverage range failure: {error}"),
+    };
+    let epoch = match super::RawTransactionIngestCoverageEpoch::new(
+        1,
+        [2_u8; 32],
+        ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        exact_scope("standard_logs", 5),
+        range,
+    ) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected coverage epoch failure: {error}"),
+    };
+    let valid = super::RawTransactionIngestCoverageEpochLedger { epochs: std::vec![epoch.clone()], next_epoch_id: 2 };
+    assert!(valid.validate_invariants(std::slice::from_ref(&matching)).is_ok());
+    let requirement = super::RawTransactionIngestCoverageRequirement {
+        commitment: ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+        scope: exact_scope("standard_logs", 5),
+    };
+    let gap = match super::RawTransactionIngestGapRange::new(120, 130) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => panic!("unexpected ledger gap failure: {error}"),
+    };
+    assert_eq!(
+        valid.redundant_relation_for_gap([1_u8; 32], &requirement, gap),
+        std::option::Option::Some(super::RawTransactionIngestCoverageRelation::Exact),
+    );
+    assert!(valid.redundant_relation_for_gap([2_u8; 32], &requirement, gap).is_none());
+    let stale = super::RawTransactionIngestCoverageEpochLedger { epochs: std::vec![epoch.clone()], next_epoch_id: 1 };
+    assert!(stale.validate_invariants(std::slice::from_ref(&matching)).is_err());
+    let unknown = super::RawTransactionIngestCoverageEpochLedger { epochs: std::vec![epoch], next_epoch_id: 2 };
+    assert!(unknown.validate_invariants(&[]).is_err());
+    let mut too_many = std::vec::Vec::new();
+    for index in 0..=super::MAX_RAW_TRANSACTION_INGEST_COVERAGE_EPOCHS {
+        let epoch_id = (index as u64) + 1;
+        let epoch = match super::RawTransactionIngestCoverageEpoch::new(
+            epoch_id,
+            [2_u8; 32],
+            ksp_onchain_transport_lib::SolanaCommitment::Confirmed,
+            exact_scope("standard_logs", 5),
+            range,
+        ) {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => panic!("unexpected bounded epoch failure: {error}"),
+        };
+        too_many.push(epoch);
+    }
+    let overflow =
+        super::RawTransactionIngestCoverageEpochLedger { epochs: too_many, next_epoch_id: (super::MAX_RAW_TRANSACTION_INGEST_COVERAGE_EPOCHS as u64) + 2 };
+    assert!(overflow.validate_invariants(std::slice::from_ref(&matching)).is_err());
+    return;
+}