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 family;
11mod format;
12mod graph_cache;
13mod graph_guards;
14mod graph_lifetimes;
15mod graph_lookup;
16mod key;
17mod layout;
18mod maintenance;
19mod notifications;
20pub(super) use maintenance::NativeMaintenanceRecords;
21mod occurrence_guards;
22mod owners;
23mod physical;
24mod projection;
25mod queue;
26mod row;
27mod sequences;
28mod session;
29mod standalone_graph;
30mod vector_guards;
31
32pub(crate) use session::NativeSnapshot;
33
34pub(super) use format::validate_restoration;
35pub(super) use format::{check_mapping, initialize, initialize_in, present, reject_mapped};
36pub(super) use projection::materialize;
37
38#[cfg(test)]
39mod tests;
40
41pub use family::NativeRecordFamily;
42pub use key::{NativeRecordIdentity, NativeRecordOwner};
43pub use layout::{NativeColumnType, NativeRecordLayout};
44pub use row::{decode_row, encode_row};
45
46use rusqlite::types::ValueRef;
47use uqa_core::memory::BudgetedVec;
48use uqa_storage::mvcc::{CommitSequence, DatabaseId, RecordWrite, VersionError, VersionResult};
49use uqa_storage::read_control::StorageReadControl;
50
51/// Stable data addressing, independent of the transaction history incarnation.
52#[derive(Clone, Copy, Debug, PartialEq, Eq)]
53pub(super) struct NativeRecordNamespace(pub(super) DatabaseId);
54
55pub(super) struct NativeMapping {
56    pub(super) identity: DatabaseId,
57    pub(super) namespace: NativeRecordNamespace,
58}
59
60/// One evaluated native row in the provider's record encoding. Its charged buffers can be borrowed by common storage's conditional commit preparation.
61#[derive(Debug)]
62pub struct NativeRecord {
63    key: BudgetedVec<u8>,
64    row: BudgetedVec<u8>,
65}
66
67impl NativeRecord {
68    pub fn encode(
69        family: NativeRecordFamily,
70        owner: NativeRecordOwner,
71        values: &[ValueRef<'_>],
72        control: &StorageReadControl,
73    ) -> VersionResult<Self> {
74        control.cancellation().check()?;
75        let layout = family.layout();
76        let identity = NativeRecordIdentity::new(family, owner)?;
77        identity.validate_row(values)?;
78        let mut components = BudgetedVec::new(control.memory());
79        for &column in layout.identity_columns {
80            components.push(values[column])?;
81        }
82        let key = identity.encode_key(&components, control)?;
83        let row = encode_row(values, control)?;
84        Ok(Self { key, row })
85    }
86
87    pub fn key(&self) -> &[u8] {
88        &self.key
89    }
90
91    pub fn row(&self) -> &[u8] {
92        &self.row
93    }
94
95    pub fn write(&self, expected: Option<CommitSequence>) -> RecordWrite<'_> {
96        RecordWrite {
97            key: self.key(),
98            expected,
99            value: Some(self.row()),
100        }
101    }
102}
103
104/// 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.
105pub fn decode_record<'a>(
106    key: &[u8],
107    row: &'a [u8],
108    control: &StorageReadControl,
109) -> VersionResult<(NativeRecordIdentity, BudgetedVec<ValueRef<'a>>)> {
110    control.cancellation().check()?;
111    let identity = NativeRecordIdentity::decode(key)?;
112    let layout = identity.family().layout();
113    let values = decode_row(row, layout.columns.len(), control)?;
114    identity.validate_row(&values)?;
115    let mut components = BudgetedVec::new(control.memory());
116    for &column in layout.identity_columns {
117        components.push(values[column])?;
118    }
119    if identity.encode_key(&components, control)?.as_ref() != key {
120        return Err(invalid("native row does not match its record key"));
121    }
122    Ok((identity, values))
123}
124
125fn invalid(message: &'static str) -> VersionError {
126    VersionError::InvalidEncoding(message)
127}