Skip to main content

uqa_storage/read_only_snapshot/
canonical_vectors.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Immutable vector facets share captured data, allocation leases and one snapshot identity.
8
9use super::ReadOnlySnapshot;
10use crate::{read_control::StorageReadControl, vector_index::VectorRead, StorageBackendResult};
11use sha2::{Digest, Sha256};
12use std::sync::Arc;
13use uqa_core::{
14    memory::{Budgeted, BudgetedVec},
15    DocId,
16};
17
18struct CanonicalVectors<T: ?Sized> {
19    owner: ReadOnlySnapshot<T>,
20    fingerprint: [u8; 32],
21}
22
23impl<T: VectorRead + 'static> ReadOnlySnapshot<T> {
24    /// Expose canonical values from an already captured immutable owner without copying coordinates or its directory. Cache owners may remain unbound; each reader later binds its own cancellation. A supplied control admits the facet header, while None preserves the existing uncontrolled snapshot API. The unique view identity is conservative across independently captured equal corpora and stable across shared/nested readers.
25    pub fn with_canonical_vectors(
26        self,
27        control: Option<&StorageReadControl>,
28    ) -> StorageBackendResult<Self> {
29        if let Some(control) = control {
30            control.check()?;
31        }
32        if self.3.is_some() {
33            return Ok(self);
34        }
35        let identity =
36            crate::catalog::new_nonzero_catalog_identity("vector snapshot", "canonical values")?;
37        let mut digest = Sha256::new();
38        digest.update(b"uqa-immutable-vector-view-v1\0");
39        digest.update(identity);
40        self.with_canonical_fingerprint(digest.finalize().into(), control)
41    }
42
43    /// Keep an existing content identity from an already captured owner. This does not accept user-supplied or physical-index lineage labels.
44    pub(crate) fn with_canonical_fingerprint(
45        mut self,
46        fingerprint: [u8; 32],
47        control: Option<&StorageReadControl>,
48    ) -> StorageBackendResult<Self> {
49        if let Some(control) = control {
50            control.check()?;
51        }
52        if self.3.is_some() {
53            return Ok(self);
54        }
55        // This clone has no canonical facet yet: the ownership graph remains acyclic.
56        let source = CanonicalVectors {
57            owner: self.clone(),
58            fingerprint,
59        };
60        self.3 = Some(match control {
61            Some(control) => {
62                Budgeted::new(source, control.memory().empty_reservation()).into_shared()?
63            }
64            None => Arc::new(source),
65        });
66        Ok(self)
67    }
68}
69
70impl<T: VectorRead + ?Sized> VectorRead for CanonicalVectors<T> {
71    fn check_control(&self, control: &StorageReadControl) -> StorageBackendResult<()> {
72        self.owner.check_control(control)
73    }
74    fn dimensions(&self) -> u32 {
75        self.owner.dimensions()
76    }
77    fn corpus_fingerprint(
78        &self,
79        control: &StorageReadControl,
80    ) -> StorageBackendResult<Option<[u8; 32]>> {
81        self.check_control(control)?;
82        Ok(Some(self.fingerprint))
83    }
84    fn next_document_after(
85        &self,
86        after: Option<DocId>,
87        control: &StorageReadControl,
88    ) -> StorageBackendResult<Option<DocId>> {
89        self.owner.next_document_after(after, control)
90    }
91    fn document_vector_count(
92        &self,
93        document: DocId,
94        control: &StorageReadControl,
95    ) -> StorageBackendResult<u64> {
96        self.owner.document_vector_count(document, control)
97    }
98    fn read_vector(
99        &self,
100        document: DocId,
101        ordinal: u32,
102        control: &StorageReadControl,
103    ) -> StorageBackendResult<Option<BudgetedVec<f32>>> {
104        self.owner.read_vector(document, ordinal, control)
105    }
106}