icydb-core 0.74.7

IcyDB — A type-safe, embedded ORM and schema system for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Module: db::executor::continuation::capabilities
//! Responsibility: module-local ownership and contracts for db::executor::continuation::capabilities.
//! Does not own: cross-module orchestration outside this module.
//! Boundary: exposes this module API while keeping implementation details internal.

use crate::db::{executor::ContinuationMode, query::plan::ContinuationPolicy};

///
/// ContinuationCapabilities
///
/// Immutable continuation capability projection derived once from scalar
/// continuation runtime shape plus planner continuation policy.
/// Route/load consumers read this contract instead of re-deriving policy gates.
///

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[expect(clippy::struct_excessive_bools)]
pub(in crate::db::executor) struct ContinuationCapabilities {
    #[cfg_attr(not(test), allow(dead_code))]
    mode: ContinuationMode,
    applied: bool,
    strict_advance_required_when_applied: bool,
    grouped_safe_when_applied: bool,
    index_range_limit_pushdown_allowed: bool,
}

impl ContinuationCapabilities {
    /// Construct one immutable continuation capability projection.
    #[must_use]
    pub(in crate::db::executor) const fn new(
        mode: ContinuationMode,
        continuation_policy: ContinuationPolicy,
    ) -> Self {
        let applied = !matches!(mode, ContinuationMode::Initial);

        Self {
            mode,
            applied,
            strict_advance_required_when_applied: !applied
                || continuation_policy.requires_strict_advance(),
            grouped_safe_when_applied: !applied || continuation_policy.is_grouped_safe(),
            index_range_limit_pushdown_allowed: !continuation_policy.requires_anchor()
                || !matches!(mode, ContinuationMode::CursorBoundary),
        }
    }

    /// Return route continuation mode projected by this capability snapshot.
    #[must_use]
    pub(in crate::db::executor) const fn mode(self) -> ContinuationMode {
        self.mode
    }

    /// Return whether continuation is applied for this execution.
    #[must_use]
    pub(in crate::db::executor) const fn applied(self) -> bool {
        self.applied
    }

    /// Return whether strict advancement is required under continuation.
    #[must_use]
    pub(in crate::db::executor) const fn strict_advance_required_when_applied(self) -> bool {
        self.strict_advance_required_when_applied
    }

    /// Return whether grouped continuation remains safe under this policy.
    #[must_use]
    pub(in crate::db::executor) const fn grouped_safe_when_applied(self) -> bool {
        self.grouped_safe_when_applied
    }

    /// Return whether index-range limit pushdown can remain enabled.
    #[must_use]
    pub(in crate::db::executor) const fn index_range_limit_pushdown_allowed(self) -> bool {
        self.index_range_limit_pushdown_allowed
    }
}

///
/// TESTS
///

#[cfg(test)]
mod tests {
    use crate::db::{
        executor::{ContinuationCapabilities, ContinuationMode},
        query::plan::ContinuationPolicy,
    };

    #[test]
    fn continuation_capabilities_apply_policy_for_initial_mode() {
        let capabilities = ContinuationCapabilities::new(
            ContinuationMode::Initial,
            ContinuationPolicy::new(true, false, false),
        );

        assert!(!capabilities.applied());
        assert!(
            capabilities.strict_advance_required_when_applied(),
            "initial mode must satisfy strict-advance invariants unconditionally",
        );
        assert!(
            capabilities.grouped_safe_when_applied(),
            "initial mode must satisfy grouped safety invariants unconditionally",
        );
        assert!(
            capabilities.index_range_limit_pushdown_allowed(),
            "initial mode must not disable index-range limit pushdown",
        );
    }

    #[test]
    fn continuation_capabilities_disable_index_range_pushdown_for_cursor_boundary_anchor_policy() {
        let capabilities = ContinuationCapabilities::new(
            ContinuationMode::CursorBoundary,
            ContinuationPolicy::new(true, true, true),
        );

        assert!(capabilities.applied());
        assert!(capabilities.strict_advance_required_when_applied());
        assert!(capabilities.grouped_safe_when_applied());
        assert!(
            !capabilities.index_range_limit_pushdown_allowed(),
            "cursor-boundary mode with anchor-required policy must disable index-range pushdown",
        );
    }

    #[test]
    fn continuation_capabilities_keep_index_range_pushdown_for_anchor_mode() {
        let capabilities = ContinuationCapabilities::new(
            ContinuationMode::IndexRangeAnchor,
            ContinuationPolicy::new(true, true, true),
        );

        assert_eq!(capabilities.mode(), ContinuationMode::IndexRangeAnchor);
        assert!(capabilities.applied());
        assert!(capabilities.index_range_limit_pushdown_allowed());
    }
}