uqa_storage/mvcc/
occurrence.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Provider record codecs for the shared occurrence commit resolver.
8
9mod clusters;
10mod resolve;
11mod statistics;
12#[cfg(test)]
13mod tests;
14
15use crate::{inverted_index::IndexedFieldRevision, read_control::StorageReadControl};
16use uqa_core::memory::BudgetedVec;
17
18use super::VersionResult;
19
20/// Complete record identities eligible for an evaluated occurrence replacement.
21#[derive(Clone, Copy, Debug, PartialEq, Eq)]
22pub enum OccurrenceRecordKind {
23    Score(u64),
24    Positions,
25    Cluster(u64),
26    Statistics,
27    Format,
28    Cache,
29}
30
31/// Related records in the same stable index scope. Cache addresses are scan prefixes; all other addresses are complete keys.
32#[derive(Clone, Copy)]
33pub enum OccurrenceRelatedKey {
34    Structure,
35    Format,
36    Score,
37    Positions,
38    Skips,
39    BlockMax,
40}
41
42/// Borrowed column projections preserve provider payload ownership during decoding. Common storage owns cluster merging and checked field-counter arithmetic.
43pub enum OccurrenceRecordValue<'a> {
44    Score(&'a [u8]),
45    Positions(&'a [u8]),
46    Cluster {
47        score: &'a [u8],
48        positions: &'a [u8],
49    },
50    Statistics {
51        revision: IndexedFieldRevision,
52        doc_count: u64,
53        total_length: u64,
54    },
55    Format(&'a [u8]),
56}
57
58/// Physical addressing and row codecs only. Methods must validate complete keys, keep related addresses within the original object generation and charge temporary allocations to `control`. They perform no I/O, index algorithms or application callbacks.
59pub trait OccurrenceRecordLayout: Send + Sync {
60    fn kind(&self, key: &[u8], control: &StorageReadControl)
61        -> VersionResult<OccurrenceRecordKind>;
62
63    fn related_key(
64        &self,
65        key: &[u8],
66        related: OccurrenceRelatedKey,
67        control: &StorageReadControl,
68    ) -> VersionResult<BudgetedVec<u8>>;
69
70    fn decode<'a>(
71        &self,
72        key: &[u8],
73        value: &'a [u8],
74        control: &StorageReadControl,
75    ) -> VersionResult<OccurrenceRecordValue<'a>>;
76
77    /// Encode the merged value with the key and immutable row fields from an original, evaluated or current record. This may enforce narrower native scalar bounds before any publication occurs.
78    fn encode(
79        &self,
80        key: &[u8],
81        template: &[u8],
82        value: OccurrenceRecordValue<'_>,
83        control: &StorageReadControl,
84    ) -> VersionResult<BudgetedVec<u8>>;
85}
86
87pub(super) use resolve::resolve;
uqa_storage/mvcc/occurrence.rs

uqa_storage/mvcc/
occurrence.rs
