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    /// Resolve a raw invalidation's owning field without requiring an existing origin value.
48    fn origin_header_prefix(
49        &self,
50        key: &[u8],
51        control: &StorageReadControl,
52    ) -> VersionResult<BudgetedVec<u8>>;
53
54    /// Select headers only, for every active generation associated with this exact field.
55    fn header_prefix(
56        &self,
57        field: &[u8],
58        control: &StorageReadControl,
59    ) -> VersionResult<BudgetedVec<u8>>;
60
61    fn header(
62        &self,
63        key: &[u8],
64        value: &[u8],
65        control: &StorageReadControl,
66    ) -> VersionResult<DiskANNPopulationHeader>;
67
68    fn witness_prefix(
69        &self,
70        header: &[u8],
71        control: &StorageReadControl,
72    ) -> VersionResult<BudgetedVec<u8>>;
73
74    /// Map a header or witness key back to its owning generation's header; reject unrelated records.
75    fn preview_header(
76        &self,
77        key: &[u8],
78        control: &StorageReadControl,
79    ) -> VersionResult<BudgetedVec<u8>>;
80
81    fn witness_key(
82        &self,
83        header: &[u8],
84        document: DocId,
85        control: &StorageReadControl,
86    ) -> VersionResult<BudgetedVec<u8>>;
87
88    fn witness(
89        &self,
90        key: &[u8],
91        value: &[u8],
92        state: DiskANNPopulationState,
93        document: DocId,
94        origin: DiskANNCanonicalOrigin,
95        control: &StorageReadControl,
96    ) -> VersionResult<DiskANNPopulationWitness>;
97
98    fn encode_header(
99        &self,
100        key: &[u8],
101        template: &[u8],
102        state: DiskANNPopulationState,
103        control: &StorageReadControl,
104    ) -> VersionResult<BudgetedVec<u8>>;
105
106    fn encode_witness(
107        &self,
108        key: &[u8],
109        header_template: &[u8],
110        witness: DiskANNPopulationWitness,
111        control: &StorageReadControl,
112    ) -> VersionResult<BudgetedVec<u8>>;
113
114    /// 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.
115    fn with_canonical(
116        &self,
117        field: &[u8],
118        dimensions: u32,
119        view: &MergedRecordSnapshot,
120        history: DatabaseId,
121        control: &StorageReadControl,
122        visit: &mut dyn FnMut(&dyn DiskANNQueryRead) -> VersionResult<()>,
123    ) -> VersionResult<()>;
124}
uqa_storage/mvcc/populations.rs

uqa_storage/mvcc/
populations.rs
