uqa_storage/mvcc/
populations.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Canonical population reconciliation belongs to common MVCC; providers supply addressing, codecs and fixed-view canonical adapters.
8
9mod effects;
10mod reconcile;
11mod resolve;
12mod structural;
13
14pub(super) use effects::{OwnedPopulationMutation, PopulationEffects};
15pub(super) use resolve::{resolve, stage};
16
17use super::{DatabaseId, MergedRecordSnapshot, VersionResult};
18use crate::diskann_index::{
19    format::DiskANNCanonicalOrigin, DiskANNPopulationState, DiskANNPopulationWitness,
20    DiskANNQueryRead,
21};
22use crate::read_control::StorageReadControl;
23use uqa_core::{memory::BudgetedVec, DocId};
24
25/// An evaluated origin and its provider-owned canonical field address.
26pub struct DiskANNPopulationOrigin {
27    pub field: BudgetedVec<u8>,
28    pub document: DocId,
29    pub origin: DiskANNCanonicalOrigin,
30}
31
32/// A validated population header with its provider-owned canonical field address.
33pub struct DiskANNPopulationHeader {
34    pub field: BudgetedVec<u8>,
35    pub state: DiskANNPopulationState,
36}
37
38/// Only physical mapping and retained canonical adapters. Common storage owns census, replacement arithmetic, concurrency, private previews and lifecycle resolution.
39pub trait DiskANNPopulationRecordLayout: Send + Sync {
40    fn origin(
41        &self,
42        key: &[u8],
43        value: &[u8],
44        control: &StorageReadControl,
45    ) -> VersionResult<DiskANNPopulationOrigin>;
46
47    /// Select origin records for this exact canonical field, excluding neighboring field identities.
48    fn origin_prefix(
49        &self,
50        field: &[u8],
51        control: &StorageReadControl,
52    ) -> VersionResult<BudgetedVec<u8>>;
53
54    /// Resolve a raw invalidation's owning field without requiring an existing origin value.
55    fn origin_header_prefix(
56        &self,
57        key: &[u8],
58        control: &StorageReadControl,
59    ) -> VersionResult<BudgetedVec<u8>>;
60
61    /// Select headers only, for every active generation associated with this exact field.
62    fn header_prefix(
63        &self,
64        field: &[u8],
65        control: &StorageReadControl,
66    ) -> VersionResult<BudgetedVec<u8>>;
67
68    fn header(
69        &self,
70        key: &[u8],
71        value: &[u8],
72        control: &StorageReadControl,
73    ) -> VersionResult<DiskANNPopulationHeader>;
74
75    fn witness_prefix(
76        &self,
77        header: &[u8],
78        control: &StorageReadControl,
79    ) -> VersionResult<BudgetedVec<u8>>;
80
81    /// Map a header or witness key back to its owning generation's header; reject unrelated records.
82    fn preview_header(
83        &self,
84        key: &[u8],
85        control: &StorageReadControl,
86    ) -> VersionResult<BudgetedVec<u8>>;
87
88    fn witness_key(
89        &self,
90        header: &[u8],
91        document: DocId,
92        control: &StorageReadControl,
93    ) -> VersionResult<BudgetedVec<u8>>;
94
95    fn witness(
96        &self,
97        key: &[u8],
98        value: &[u8],
99        state: DiskANNPopulationState,
100        document: DocId,
101        origin: DiskANNCanonicalOrigin,
102        control: &StorageReadControl,
103    ) -> VersionResult<DiskANNPopulationWitness>;
104
105    fn encode_header(
106        &self,
107        key: &[u8],
108        template: &[u8],
109        state: DiskANNPopulationState,
110        control: &StorageReadControl,
111    ) -> VersionResult<BudgetedVec<u8>>;
112
113    fn encode_witness(
114        &self,
115        key: &[u8],
116        header_template: &[u8],
117        witness: DiskANNPopulationWitness,
118        control: &StorageReadControl,
119    ) -> VersionResult<BudgetedVec<u8>>;
120
121    /// Invoke exactly once, outside provider locks, with the existing complete-origin/ordinal validator on this fixed view. Do not reconstruct coordinates or advance a session.
122    fn with_canonical(
123        &self,
124        field: &[u8],
125        dimensions: u32,
126        view: &MergedRecordSnapshot,
127        history: DatabaseId,
128        control: &StorageReadControl,
129        visit: &mut dyn FnMut(&dyn DiskANNQueryRead) -> VersionResult<()>,
130    ) -> VersionResult<()>;
131}
uqa_storage/mvcc/populations.rs

uqa_storage/mvcc/
populations.rs
