uqa_storage/diskann_index/
metadata.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Metadata describes the actual retained physical and canonical selection.
8
9use super::{
10    format::DiskANNManifest,
11    pages::{read_manifest, DiskANNPageSource, DiskANNReadCapabilities, DiskANNReadLimits},
12    DiskANNCanonicalCounts, DiskANNCanonicalRead,
13};
14use crate::{
15    read_control::StorageReadControl, vector_index::DiskANNIndexParams, StorageBackendResult,
16};
17use sha2::{Digest, Sha256};
18
19mod statistics;
20
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub struct DiskANNQueryMetadata {
23    pub manifest: DiskANNManifest,
24    /// None is an unverifiable canonical selection, never permission to trust a caller's version label.
25    pub corpus_fingerprint: Option<[u8; 32]>,
26    /// Exact selected-view populations when maintained by the canonical owner; absence is not a measured zero.
27    pub canonical_counts: Option<DiskANNCanonicalCounts>,
28    pub read_limits: DiskANNReadLimits,
29    pub read_capabilities: DiskANNReadCapabilities,
30}
31
32impl DiskANNQueryMetadata {
33    /// Read the bounded manifest, canonical identity and maintained counts from an already associated provider view. This validates the selected definition, not graph/PQ/origin bodies; opening an executable reader retains its complete validation. No vector query or logical observation is performed.
34    pub fn capture(
35        canonical: &dyn DiskANNCanonicalRead,
36        source: &dyn DiskANNPageSource,
37        parameters: DiskANNIndexParams,
38        limits: DiskANNReadLimits,
39        control: &StorageReadControl,
40    ) -> StorageBackendResult<Self> {
41        canonical.check_control(control)?;
42        let manifest = read_manifest(
43            source,
44            canonical.dimensions(),
45            parameters,
46            limits.max_record_bytes,
47            control,
48        )?;
49        let corpus_fingerprint = canonical.corpus_fingerprint(control)?;
50        let canonical_counts = canonical.population_counts(manifest.input().generation, control)?;
51        canonical.check_control(control)?;
52        Ok(Self {
53            manifest,
54            corpus_fingerprint,
55            canonical_counts,
56            read_limits: limits,
57            read_capabilities: source.capabilities(),
58        })
59    }
60
61    /// Versioned SHA-256 of the complete validated manifest, including physical incarnations, graph/PQ generation, build revisions and effective candidate-selection settings.
62    pub fn index_fingerprint(
63        &self,
64        control: &StorageReadControl,
65    ) -> StorageBackendResult<[u8; 32]> {
66        control.check()?;
67        let mut digest = Sha256::new();
68        digest.update(b"uqa-diskann-index-v1\0");
69        digest.update(&*self.manifest.encode(control)?);
70        control.check()?;
71        Ok(digest.finalize().into())
72    }
73}
uqa_storage/diskann_index/metadata.rs

uqa_storage/diskann_index/
metadata.rs
