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;
12
13pub(super) use effects::{OwnedPopulationMutation, PopulationEffects};
14pub(super) use resolve::{resolve, stage};
15
16use super::{DatabaseId, MergedRecordSnapshot, VersionResult};
17use crate::diskann_index::{
18    format::DiskANNCanonicalOrigin, DiskANNPopulationState, DiskANNPopulationWitness,
19    DiskANNQueryRead,
20};
21use crate::read_control::StorageReadControl;
22use uqa_core::{memory::BudgetedVec, DocId};
23
24/// An evaluated origin and its provider-owned canonical field address.
25pub struct DiskANNPopulationOrigin {
26    pub field: BudgetedVec<u8>,
27    pub document: DocId,
28    pub origin: DiskANNCanonicalOrigin,
29}
30
31/// A validated population header with its provider-owned canonical field address.
32pub struct DiskANNPopulationHeader {
33    pub field: BudgetedVec<u8>,
34    pub state: DiskANNPopulationState,
35}
36
37/// Only physical mapping and retained canonical adapters. Common storage owns census, replacement arithmetic, concurrency, private previews and lifecycle resolution.
38pub trait DiskANNPopulationRecordLayout: Send + Sync {
39    fn origin(
40        &self,
41        key: &[u8],
42        value: &[u8],
43        control: &StorageReadControl,
44    ) -> VersionResult<DiskANNPopulationOrigin>;
45
46    /// Resolve a raw invalidation's owning field without requiring an existing origin value.
47    fn origin_header_prefix(
48        &self,
49        key: &[u8],
50        control: &StorageReadControl,
51    ) -> VersionResult<BudgetedVec<u8>>;
52
53    /// Select headers only, for every active generation associated with this exact field.
54    fn header_prefix(
55        &self,
56        field: &[u8],
57        control: &StorageReadControl,
58    ) -> VersionResult<BudgetedVec<u8>>;
59
60    fn header(
61        &self,
62        key: &[u8],
63        value: &[u8],
64        control: &StorageReadControl,
65    ) -> VersionResult<DiskANNPopulationHeader>;
66
67    fn witness_prefix(
68        &self,
69        header: &[u8],
70        control: &StorageReadControl,
71    ) -> VersionResult<BudgetedVec<u8>>;
72
73    /// Map a header or witness key back to its owning generation's header; reject unrelated records.
74    fn preview_header(
75        &self,
76        key: &[u8],
77        control: &StorageReadControl,
78    ) -> VersionResult<BudgetedVec<u8>>;
79
80    fn witness_key(
81        &self,
82        header: &[u8],
83        document: DocId,
84        control: &StorageReadControl,
85    ) -> VersionResult<BudgetedVec<u8>>;
86
87    fn witness(
88        &self,
89        key: &[u8],
90        value: &[u8],
91        state: DiskANNPopulationState,
92        document: DocId,
93        origin: DiskANNCanonicalOrigin,
94        control: &StorageReadControl,
95    ) -> VersionResult<DiskANNPopulationWitness>;
96
97    fn encode_header(
98        &self,
99        key: &[u8],
100        template: &[u8],
101        state: DiskANNPopulationState,
102        control: &StorageReadControl,
103    ) -> VersionResult<BudgetedVec<u8>>;
104
105    fn encode_witness(
106        &self,
107        key: &[u8],
108        header_template: &[u8],
109        witness: DiskANNPopulationWitness,
110        control: &StorageReadControl,
111    ) -> VersionResult<BudgetedVec<u8>>;
112
113    /// 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.
114    fn with_canonical(
115        &self,
116        field: &[u8],
117        dimensions: u32,
118        view: &MergedRecordSnapshot,
119        history: DatabaseId,
120        control: &StorageReadControl,
121        visit: &mut dyn FnMut(&dyn DiskANNQueryRead) -> VersionResult<()>,
122    ) -> VersionResult<()>;
123}
uqa_storage/mvcc/populations.rs

uqa_storage/mvcc/
populations.rs
