Skip to main content

uqa_storage_sqlite/mvcc/native/
field_guards.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Native field-guard identities adapt common empty-field maintenance without bypassing row projection.
8
9use rusqlite::types::ValueRef;
10use uqa_core::memory::BudgetedVec;
11use uqa_storage::mvcc::{VectorFieldGuard, VectorFieldGuardLayout, VersionResult};
12use uqa_storage::read_control::StorageReadControl;
13
14use super::{
15    invalid, NativeRecord, NativeRecordFamily as Family, NativeRecordIdentity, NativeRecordOwner,
16};
17use crate::mvcc::SQLiteRecordStore;
18
19pub(crate) const VECTOR_FIELD_GUARD_PREFIX: &str = "vector_field_guard::";
20
21impl VectorFieldGuardLayout for SQLiteRecordStore {
22    fn prefix(&self, control: &StorageReadControl) -> VersionResult<BudgetedVec<u8>> {
23        let Some(namespace) = self.native else {
24            return uqa_storage::key_value::KeyValueVectorFieldGuards.prefix(control);
25        };
26        NativeRecordIdentity::new(Family::Metadata, NativeRecordOwner::Database(namespace.0))?
27            .encode_text_prefix(VECTOR_FIELD_GUARD_PREFIX.as_bytes(), control)
28    }
29
30    fn reference(
31        &self,
32        key: &[u8],
33        control: &StorageReadControl,
34    ) -> VersionResult<Option<VectorFieldGuard>> {
35        let Some(namespace) = self.native else {
36            return uqa_storage::key_value::KeyValueVectorFieldGuards.reference(key, control);
37        };
38        let mut result = None;
39        let identity = NativeRecordIdentity::visit_key_components(key, control, |_, component| {
40            let name = component
41                .as_str()
42                .map_err(|_| invalid("vector field guard is not TEXT"))?;
43            let suffix = name
44                .strip_prefix(VECTOR_FIELD_GUARD_PREFIX)
45                .ok_or_else(|| invalid("foreign vector field guard"))?;
46            let (hex, reference) = if let Some(hex) = suffix.strip_suffix("::references") {
47                (hex, true)
48            } else if let Some(hex) = suffix.strip_suffix("::lifetime") {
49                (hex, false)
50            } else {
51                return Err(invalid("invalid vector field guard suffix"));
52            };
53            if hex.len() % 2 != 0 {
54                return Err(invalid("invalid vector field guard encoding"));
55            }
56            let mut vectors = BudgetedVec::new(control.memory());
57            for pair in hex.as_bytes().as_chunks::<2>().0 {
58                control.check()?;
59                let digit = |byte| match byte {
60                    b'0'..=b'9' => Ok(byte - b'0'),
61                    b'a'..=b'f' => Ok(byte - b'a' + 10),
62                    _ => Err(invalid("invalid vector field guard hexadecimal digit")),
63                };
64                vectors.push((digit(pair[0])? << 4) | digit(pair[1])?)?;
65            }
66            let field =
67                NativeRecordIdentity::visit_prefix_components(&vectors, 1, control, |_, _| Ok(()))?;
68            if field.family() != Family::Vectors
69                || !matches!(field.owner(), NativeRecordOwner::Object { .. })
70            {
71                return Err(invalid("vector field guard does not name a vector field"));
72            }
73            if !reference {
74                return Ok(());
75            }
76            let owner = NativeRecordOwner::Database(namespace.0);
77            let references = NativeRecord::encode(
78                Family::Metadata,
79                owner,
80                &[ValueRef::Text(name.as_bytes()), ValueRef::Text(b"1")],
81                control,
82            )?;
83            let mut lifetime = BudgetedVec::new(control.memory());
84            lifetime.extend_from_slice(&name.as_bytes()[..name.len() - "::references".len()])?;
85            lifetime.extend_from_slice(b"::lifetime")?;
86            let lifetime = NativeRecord::encode(
87                Family::Metadata,
88                owner,
89                &[ValueRef::Text(&lifetime), ValueRef::Text(b"1")],
90                control,
91            )?;
92            result = Some(VectorFieldGuard {
93                lifetime: lifetime.key,
94                references: references.key,
95                reference_value: references.row,
96                vectors,
97            });
98            Ok(())
99        })?;
100        if identity.family() != Family::Metadata
101            || identity.owner() != NativeRecordOwner::Database(namespace.0)
102        {
103            return Err(invalid("foreign vector field guard owner"));
104        }
105        Ok(result)
106    }
107}