lix 0.18.0

Embeddable version control for apps and AI agents.
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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224

//! Public handles for every registered storage space.
//!
//! Benchmarks, qualification harnesses and adapter suites live outside this
//! crate but must still name the spaces the engine writes. Before this module
//! existed the only way to do that was to repeat the space *name* as a string
//! literal, and a space name carries the record encoding version, so it is
//! *expected* to churn: `branch.head_control.v10` became `v11` in `76834a1c9`
//! when `untracked_generation` left the packed record.
//!
//! A repeated literal turns that ordinary bump into a runtime break in
//! whichever code path happens to run, and the break is not always loud.
//! Measured against the 31 pinned literals that existed when this module was
//! added, a stale name had three outcomes:
//!
//! - it panicked (`storage_space_by_name`, `packed_history_scale::find_layout`);
//! - it silently disarmed a predicate, so a test passed vacuously or timed out
//!   somewhere unrelated (the server-protocol branch-control gate, which read
//!   as "the branch switch never issued its authoritative read");
//! - **it silently reported zero.** `small_blob_cas` looked its spaces up with
//!   `.find(..).map_or(0, ..)`, so a renamed space did not fail — the bench
//!   reported `0 rows / 0 bytes` as a measurement.
//!
//! Reading the handle instead of repeating the name removes the failure rather
//! than detecting it: there is no longer a second copy of the name to go stale,
//! so a rename propagates on rebuild and there is nothing to update.
//!
//! Prefer the handle's `.id` wherever the caller only needs *identity* — "is
//! this the branch-control space?". The id is the first four bytes of every
//! physical key and does not move across an encoding bump (`0x0004_0020`
//! survived `v10` -> `v11` untouched), whereas the name is versioned by design.
//!
//! This module is a *view* of [`crate::storage_spaces::ALL_STORAGE_SPACES`],
//! never a second authority for it:
//! [`tests::the_published_handles_are_exactly_the_registry`] pins the two to
//! each other, so a space added to the registry is unpublished until it is
//! added here, and a handle cannot drift from the row it re-exports.

use crate::storage_adapter::StorageSpace;

/// Historical opaque JSON bytes retained for layout migration and snapshots.
pub const RETIRED_JSON_SPACE: StorageSpace = crate::storage_spaces::RETIRED_JSON_SPACE;

pub const TRACKED_STATE_TREE_CHUNK_SPACE: StorageSpace =
    crate::tracked_state::TRACKED_STATE_TREE_CHUNK_SPACE;
pub const REPOSITORY_PROTOCOL_SPACE: StorageSpace = crate::init::REPOSITORY_PROTOCOL_SPACE;
pub const TRACKED_STATE_CHANGE_LOCATOR_SPACE: StorageSpace =
    crate::tracked_state::TRACKED_STATE_CHANGE_LOCATOR_SPACE;
pub const TRACKED_STATE_COMMIT_DELTA_SEGMENT_SPACE: StorageSpace =
    crate::tracked_state::TRACKED_STATE_COMMIT_DELTA_SEGMENT_SPACE;
pub const HOT_ROW_SPACE: StorageSpace = crate::hot_state::ROW_SPACE;
pub const HOT_FILE_SPACE: StorageSpace = crate::hot_state::FILE_SPACE;
pub const HOT_DIFF_SPACE: StorageSpace = crate::hot_state::DIFF_SPACE;
pub const TRACKED_WORKING_DIFF_MARKER_SPACE: StorageSpace =
    crate::hot_state::TRACKED_WORKING_DIFF_MARKER_SPACE;
pub const CERTIFIED_ROW_BATCH_SPACE: StorageSpace = crate::hot_state::CERTIFIED_ROW_BATCH_SPACE;
pub const BRANCH_HEAD_CONTROL_SPACE: StorageSpace = crate::branch::BRANCH_HEAD_CONTROL_SPACE;
pub const HOT_DETERMINISTIC_IDENTITY_WITNESS_SPACE: StorageSpace =
    crate::hot_state::DETERMINISTIC_IDENTITY_WITNESS_SPACE;
pub const HOT_COLLECTION_CONTROL_SPACE: StorageSpace = crate::hot_state::COLLECTION_CONTROL_SPACE;
pub const PACKED_CURRENT_BASE_SPACE: StorageSpace = crate::hot_state::PACKED_CURRENT_BASE_SPACE;
pub const PACKED_CURRENT_BASE_CONTROL_SPACE: StorageSpace =
    crate::hot_state::PACKED_CURRENT_BASE_CONTROL_SPACE;
pub const PACKED_CURRENT_EXCLUSIVE_SCHEMA_BASE_SPACE: StorageSpace =
    crate::hot_state::PACKED_CURRENT_EXCLUSIVE_SCHEMA_BASE_SPACE;
pub const ROOT_CURRENT_BASE_SPACE: StorageSpace = crate::hot_state::ROOT_CURRENT_BASE_SPACE;
pub const ROW_GROUP_MANIFEST_SPACE: StorageSpace =
    crate::columnar_row_group::ROW_GROUP_MANIFEST_SPACE;
pub const ROW_GROUP_COLUMN_SPACE: StorageSpace = crate::columnar_row_group::ROW_GROUP_COLUMN_SPACE;
pub const TRACKED_STATE_COMMIT_STATE_MANIFEST_SPACE: StorageSpace =
    crate::tracked_state::TRACKED_STATE_COMMIT_STATE_MANIFEST_SPACE;
pub const TRACKED_STATE_COMMIT_MUTATION_INVENTORY_SPACE: StorageSpace =
    crate::tracked_state::TRACKED_STATE_COMMIT_MUTATION_INVENTORY_SPACE;
pub const MUTATION_DIRECTORY_NODE_SPACE: StorageSpace =
    crate::tracked_state::MUTATION_DIRECTORY_NODE_SPACE;
pub const TRACKED_STATE_COMMIT_HISTORY_DEFERRED_SPACE: StorageSpace =
    crate::tracked_state::TRACKED_STATE_COMMIT_HISTORY_DEFERRED_SPACE;
pub const CURRENT_STATE_DATA_PART_SPACE: StorageSpace =
    crate::tracked_state::CURRENT_STATE_DATA_PART_SPACE;
pub const SCOPED_RANGE_NODE_SPACE: StorageSpace = crate::tracked_state::SCOPED_RANGE_NODE_SPACE;
/// Declared scalar and composite equality access paths over current HOT rows.
/// Forward entries, per-lane reverse membership, and completeness witnesses
/// share the generation prefix and retire together. Validation extracts values
/// for normal publication; repository migration rebuilds this derived plane
/// from authoritative materialized rows. Tombstones retire prior membership.
pub const HOT_INDEX_SPACE: StorageSpace = crate::hot_state::INDEX_SPACE;
pub const BINARY_CAS_MANIFEST_SPACE: StorageSpace = crate::binary_cas::BINARY_CAS_MANIFEST_SPACE;
pub const BINARY_CAS_MANIFEST_CHUNK_SPACE: StorageSpace =
    crate::binary_cas::BINARY_CAS_MANIFEST_CHUNK_SPACE;
pub const BINARY_CAS_CHUNK_SPACE: StorageSpace = crate::binary_cas::BINARY_CAS_CHUNK_SPACE;
pub const BINARY_CAS_CHUNK_PRESENCE_SPACE: StorageSpace =
    crate::binary_cas::BINARY_CAS_CHUNK_PRESENCE_SPACE;
pub const BINARY_CAS_CHUNK_DEMAND_SPACE: StorageSpace =
    crate::binary_cas::BINARY_CAS_CHUNK_DEMAND_SPACE;
pub const COMMIT_SPACE: StorageSpace = crate::changelog::COMMIT_SPACE;
pub const CHANGE_SPACE: StorageSpace = crate::changelog::CHANGE_SPACE;
pub const REVISION_SPACE: StorageSpace = crate::storage_adapter::REVISION_SPACE;
pub const EXECUTE_IDEMPOTENCY_RECEIPT_SPACE: StorageSpace =
    crate::session::EXECUTE_IDEMPOTENCY_RECEIPT_SPACE;
pub const UPLOAD_STATE_SPACE: StorageSpace = crate::session::UPLOAD_STATE_SPACE;
pub const UPLOAD_MANIFEST_LEAF_SPACE: StorageSpace = crate::session::UPLOAD_MANIFEST_LEAF_SPACE;
pub const SYNC_SEQUENCE_SPACE: StorageSpace = crate::sync::SYNC_SEQUENCE_SPACE;
pub const SYNC_REPOSITORY_EVENT_SPACE: StorageSpace = crate::sync::SYNC_REPOSITORY_EVENT_SPACE;
pub const SYNC_REPLICA_RETIREMENT_SPACE: StorageSpace = crate::sync::SYNC_REPLICA_RETIREMENT_SPACE;
pub const SYNC_REPLICA_STATE_SPACE: StorageSpace = crate::sync::SYNC_REPLICA_STATE_SPACE;
pub const SYNC_MATERIALIZED_STATE_ALIAS_SPACE: StorageSpace =
    crate::sync::SYNC_MATERIALIZED_STATE_ALIAS_SPACE;
pub const SYNC_CHECKPOINT_SOURCE_SPACE: StorageSpace = crate::sync::SYNC_CHECKPOINT_SOURCE_SPACE;
pub const SYNC_UPLOAD_GENERATION_SPACE: StorageSpace = crate::sync::SYNC_UPLOAD_GENERATION_SPACE;
pub const SYNC_UPLOAD_PROOF_SPACE: StorageSpace = crate::sync::SYNC_UPLOAD_PROOF_SPACE;
pub const PARTIAL_REPLICA_STATE_SPACE: StorageSpace = crate::sync::PARTIAL_REPLICA_STATE_SPACE;
pub const PARTIAL_BRANCH_PUSH_SPACE: StorageSpace = crate::sync::PARTIAL_BRANCH_PUSH_SPACE;
pub const PARTIAL_BRANCH_MERGE_SPACE: StorageSpace = crate::sync::PARTIAL_BRANCH_MERGE_SPACE;
pub const PARTIAL_ATTEMPT_RESTART_SPACE: StorageSpace = crate::sync::PARTIAL_ATTEMPT_RESTART_SPACE;
pub const PARTIAL_AUTHORITY_MERGE_RECEIPT_SPACE: StorageSpace =
    crate::sync::PARTIAL_AUTHORITY_MERGE_RECEIPT_SPACE;
pub const PARTIAL_GLOBAL_MERGE_SPACE: StorageSpace = crate::sync::PARTIAL_GLOBAL_MERGE_SPACE;
pub const NATIVE_GLOBAL_MIGRATION_RECEIPT_SPACE: StorageSpace =
    crate::sync::NATIVE_GLOBAL_MIGRATION_RECEIPT_SPACE;
pub const NATIVE_GLOBAL_RETENTION_SPACE: StorageSpace = crate::gc::NATIVE_GLOBAL_RETENTION_SPACE;
pub const NATIVE_UPLOAD_ATTEMPT_SPACE: StorageSpace = crate::gc::NATIVE_UPLOAD_ATTEMPT_SPACE;
pub const PARTIAL_READ_INTEREST_SPACE: StorageSpace = crate::sync::PARTIAL_READ_INTEREST_SPACE;
pub const CHECKPOINT_RECOVERY_REF_SPACE: StorageSpace = crate::gc::CHECKPOINT_RECOVERY_REF_SPACE;
pub const CHECKPOINT_GC_STATE_SPACE: StorageSpace = crate::gc::CHECKPOINT_GC_STATE_SPACE;
pub const COMMIT_RETIREMENT_INTENT_SPACE: StorageSpace = crate::gc::COMMIT_RETIREMENT_INTENT_SPACE;
pub const NATIVE_BASELINE_LEASE_SPACE: StorageSpace = crate::gc::NATIVE_BASELINE_LEASE_SPACE;
/// Stable, unbanked control row selecting the active physical repository epoch.
pub const REPOSITORY_EPOCH_SPACE: StorageSpace = crate::storage_adapter::REPOSITORY_EPOCH_SPACE;

/// Every registered storage space in physical-id order.
///
/// Adapter qualification and capacity profiles use this to inspect or copy a
/// complete repository without duplicating the engine's storage registry. The
/// list includes the unbanked repository-epoch control space.
pub const ALL_STORAGE_SPACES: &[StorageSpace] = crate::storage_spaces::ALL_STORAGE_SPACES;

#[cfg(test)]
mod tests {
    use super::*;

    /// Every handle above, in registry order.
    ///
    /// Stated a second time on purpose: this is the list the test compares
    /// against the registry, and writing it out is what makes "the module
    /// publishes the whole registry" a checked claim rather than a comment.
    const PUBLISHED: &[StorageSpace] = &[
        RETIRED_JSON_SPACE,
        TRACKED_STATE_TREE_CHUNK_SPACE,
        REPOSITORY_PROTOCOL_SPACE,
        TRACKED_STATE_CHANGE_LOCATOR_SPACE,
        TRACKED_STATE_COMMIT_DELTA_SEGMENT_SPACE,
        HOT_ROW_SPACE,
        HOT_FILE_SPACE,
        HOT_DIFF_SPACE,
        TRACKED_WORKING_DIFF_MARKER_SPACE,
        BRANCH_HEAD_CONTROL_SPACE,
        HOT_COLLECTION_CONTROL_SPACE,
        PACKED_CURRENT_BASE_SPACE,
        PACKED_CURRENT_BASE_CONTROL_SPACE,
        PACKED_CURRENT_EXCLUSIVE_SCHEMA_BASE_SPACE,
        ROOT_CURRENT_BASE_SPACE,
        ROW_GROUP_MANIFEST_SPACE,
        ROW_GROUP_COLUMN_SPACE,
        TRACKED_STATE_COMMIT_STATE_MANIFEST_SPACE,
        TRACKED_STATE_COMMIT_MUTATION_INVENTORY_SPACE,
        MUTATION_DIRECTORY_NODE_SPACE,
        TRACKED_STATE_COMMIT_HISTORY_DEFERRED_SPACE,
        CURRENT_STATE_DATA_PART_SPACE,
        SCOPED_RANGE_NODE_SPACE,
        HOT_INDEX_SPACE,
        HOT_DETERMINISTIC_IDENTITY_WITNESS_SPACE,
        BINARY_CAS_MANIFEST_SPACE,
        BINARY_CAS_MANIFEST_CHUNK_SPACE,
        BINARY_CAS_CHUNK_SPACE,
        BINARY_CAS_CHUNK_PRESENCE_SPACE,
        BINARY_CAS_CHUNK_DEMAND_SPACE,
        COMMIT_SPACE,
        CHANGE_SPACE,
        REVISION_SPACE,
        EXECUTE_IDEMPOTENCY_RECEIPT_SPACE,
        UPLOAD_STATE_SPACE,
        UPLOAD_MANIFEST_LEAF_SPACE,
        SYNC_SEQUENCE_SPACE,
        SYNC_REPOSITORY_EVENT_SPACE,
        SYNC_REPLICA_STATE_SPACE,
        SYNC_MATERIALIZED_STATE_ALIAS_SPACE,
        SYNC_CHECKPOINT_SOURCE_SPACE,
        SYNC_UPLOAD_GENERATION_SPACE,
        SYNC_UPLOAD_PROOF_SPACE,
        PARTIAL_REPLICA_STATE_SPACE,
        PARTIAL_BRANCH_PUSH_SPACE,
        PARTIAL_READ_INTEREST_SPACE,
        PARTIAL_BRANCH_MERGE_SPACE,
        PARTIAL_AUTHORITY_MERGE_RECEIPT_SPACE,
        PARTIAL_ATTEMPT_RESTART_SPACE,
        NATIVE_GLOBAL_MIGRATION_RECEIPT_SPACE,
        PARTIAL_GLOBAL_MERGE_SPACE,
        SYNC_REPLICA_RETIREMENT_SPACE,
        CHECKPOINT_RECOVERY_REF_SPACE,
        CHECKPOINT_GC_STATE_SPACE,
        COMMIT_RETIREMENT_INTENT_SPACE,
        crate::checkpoint::CHECKPOINT_INVENTORY_SPACE,
        NATIVE_BASELINE_LEASE_SPACE,
        NATIVE_UPLOAD_ATTEMPT_SPACE,
        NATIVE_GLOBAL_RETENTION_SPACE,
        REPOSITORY_EPOCH_SPACE,
    ];

    /// The published handles must be the registry, exactly and in order.
    ///
    /// A partial re-export would recreate the failure `storage_spaces.rs` was
    /// written to end: a hand-maintained subset that drifts from the registry
    /// on its own schedule. Comparing the whole slice also catches a handle
    /// pointed at the wrong constant, because the row carries the id, name and
    /// value semantics together.
    #[test]
    fn the_published_handles_are_exactly_the_registry() {
        assert_eq!(
            PUBLISHED, ALL_STORAGE_SPACES,
            "the published space handles drifted from ALL_STORAGE_SPACES; \
             add the new space here, or point the stale handle back at its \
             registry row",
        );
    }
}