Skip to main content

uqa_storage_sqlite/mvcc/native/
mod.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Native `SQLite` row mapping, atomic baseline conversion and evaluated commit materialization. The record adapter preserves existing physical tables while shared storage owns private changes and visibility; native catalog/store session routing remains separate.
8
9mod capture;
10mod diskann;
11pub(crate) use row::{binary_pair_limit, variable_fields_limit, vector_row_limit};
12mod family;
13mod field_guards;
14pub(crate) use field_guards::VECTOR_FIELD_GUARD_PREFIX;
15mod format;
16mod graph_cache;
17mod graph_guards;
18mod graph_lifetimes;
19mod graph_lookup;
20mod key;
21mod layout;
22mod maintenance;
23mod notifications;
24pub(super) use maintenance::NativeMaintenanceRecords;
25mod occurrence_guards;
26mod owners;
27mod physical;
28pub(crate) mod populations;
29mod projection;
30mod queue;
31mod row;
32mod sequences;
33mod session;
34mod standalone_graph;
35mod vector_guards;
36
37pub(crate) use session::NativeSnapshot;
38
39pub(super) use format::{check_mapping, initialize, initialize_in, present, reject_mapped};
40pub(super) use format::{initialize_restoration, validate_restoration};
41pub(super) use projection::materialize;
42
43#[cfg(test)]
44mod tests;
45
46pub use family::NativeRecordFamily;
47pub use key::{NativeRecordIdentity, NativeRecordOwner};
48pub use layout::{NativeColumnType, NativeRecordLayout};
49pub use row::{decode_row, encode_row};
50
51use rusqlite::types::ValueRef;
52use uqa_core::memory::BudgetedVec;
53use uqa_storage::mvcc::{CommitSequence, DatabaseId, RecordWrite, VersionError, VersionResult};
54use uqa_storage::read_control::StorageReadControl;
55
56/// Stable data addressing, independent of the transaction history incarnation.
57#[derive(Clone, Copy, Debug, PartialEq, Eq)]
58pub(super) struct NativeRecordNamespace(pub(super) DatabaseId);
59
60pub(super) struct NativeMapping {
61    pub(super) identity: DatabaseId,
62    pub(super) namespace: NativeRecordNamespace,
63}
64
65/// One evaluated native row in the provider's record encoding. Its charged buffers can be borrowed by common storage's conditional commit preparation.
66#[derive(Debug)]
67pub struct NativeRecord {
68    key: BudgetedVec<u8>,
69    row: BudgetedVec<u8>,
70}
71
72impl NativeRecord {
73    pub fn encode(
74        family: NativeRecordFamily,
75        owner: NativeRecordOwner,
76        values: &[ValueRef<'_>],
77        control: &StorageReadControl,
78    ) -> VersionResult<Self> {
79        control.cancellation().check()?;
80        let layout = family.layout();
81        let identity = NativeRecordIdentity::new(family, owner)?;
82        identity.validate_row(values)?;
83        let mut components = BudgetedVec::new(control.memory());
84        for &column in layout.identity_columns {
85            components.push(values[column])?;
86        }
87        let key = identity.encode_key(&components, control)?;
88        let row = encode_row(values, control)?;
89        Ok(Self { key, row })
90    }
91
92    pub fn key(&self) -> &[u8] {
93        &self.key
94    }
95
96    pub fn row(&self) -> &[u8] {
97        &self.row
98    }
99
100    pub fn write(&self, expected: Option<CommitSequence>) -> RecordWrite<'_> {
101        RecordWrite {
102            key: self.key(),
103            expected,
104            value: Some(self.row()),
105        }
106    }
107}
108
109/// Validate a retained row against its full native key and return borrowed column values. This rejects a correct-looking payload addressed to a different tuple or family before physical materialization.
110pub fn decode_record<'a>(
111    key: &[u8],
112    row: &'a [u8],
113    control: &StorageReadControl,
114) -> VersionResult<(NativeRecordIdentity, BudgetedVec<ValueRef<'a>>)> {
115    control.cancellation().check()?;
116    let identity = NativeRecordIdentity::decode(key)?;
117    let layout = identity.family().layout();
118    let values = decode_row(row, layout.columns.len(), control)?;
119    identity.validate_row(&values)?;
120    let mut components = BudgetedVec::new(control.memory());
121    for &column in layout.identity_columns {
122        components.push(values[column])?;
123    }
124    if identity.encode_key(&components, control)?.as_ref() != key {
125        return Err(invalid("native row does not match its record key"));
126    }
127    Ok((identity, values))
128}
129
130fn invalid(message: &'static str) -> VersionError {
131    VersionError::InvalidEncoding(message)
132}