polyc-query-model 2026.9.3

//! The query protocol's own closed source-evidence vocabulary.
//!
//! A terminal frame reports the exact premises a query read. Those premises
//! originate in the state plane's audit types, but a client must not acquire
//! the state plane's component graph to read them. This module owns a
//! wire-neutral mirror instead: plain data, no transport, no engine, and no
//! dependency outside this crate.
//!
//! The inward composition layer converts between these types and the state
//! plane's own. That layer is the only place both vocabularies meet.
//!
//! # Canonical order
//!
//! [`SourceEvidence`] holds strictly ascending, duplicate-free pins under the
//! same identity rule the durable audit applies: a variant tag, then each
//! source's identity as length-prefixed bytes. Reproducing the rule here lets
//! the transport refuse a reordered or duplicated vector on its own, without
//! reaching for the state plane to do it.

use std::fmt;
use std::time::Duration;

use crate::ModelError;

/// Largest number of exact source premises one result may report.
pub const MAX_SOURCE_PINS: usize = 32;
/// Width of a partition incarnation.
pub const INCARNATION_BYTES: usize = 32;
/// Width of a content digest.
pub const DIGEST_BYTES: usize = 32;
/// Width of a journal commit root.
pub const COMMIT_ROOT_BYTES: usize = 32;
/// Width of a journal attestation signature.
pub const ATTESTATION_SIGNATURE_BYTES: usize = 64;
/// Width of a journal attestation signer key.
pub const ATTESTATION_SIGNER_BYTES: usize = 32;

fn push_len_prefixed(buffer: &mut Vec<u8>, bytes: &[u8]) {
    buffer.extend_from_slice(&u64::try_from(bytes.len()).unwrap_or(u64::MAX).to_be_bytes());
    buffer.extend_from_slice(bytes);
}

const fn non_empty(field: &'static str, value: &str) -> Result<(), ModelError> {
    if value.is_empty() {
        return Err(ModelError::Bounds(field));
    }
    Ok(())
}

/// One physical journal lineage.
#[derive(Clone, PartialEq, Eq)]
pub struct JournalSource {
    partition: String,
    incarnation: [u8; INCARNATION_BYTES],
}

impl JournalSource {
    /// Names one partition incarnation.
    ///
    /// # Errors
    ///
    /// Returns [`ModelError::Bounds`] for an empty partition.
    pub fn try_new(
        partition: String,
        incarnation: [u8; INCARNATION_BYTES],
    ) -> Result<Self, ModelError> {
        non_empty("partition", &partition)?;
        Ok(Self {
            partition,
            incarnation,
        })
    }

    /// Returns the partition this lineage belongs to.
    #[must_use]
    pub fn partition(&self) -> &str {
        &self.partition
    }

    /// Returns the exact incarnation bytes.
    #[must_use]
    pub const fn incarnation(&self) -> &[u8; INCARNATION_BYTES] {
        &self.incarnation
    }
}

/// A signed journal root covering one checkpoint.
#[derive(Clone, PartialEq, Eq)]
pub struct JournalAttestation {
    root: [u8; COMMIT_ROOT_BYTES],
    leaf_count: u64,
    signature: [u8; ATTESTATION_SIGNATURE_BYTES],
    signer: [u8; ATTESTATION_SIGNER_BYTES],
}

impl JournalAttestation {
    /// Records one covering attestation.
    #[must_use]
    pub const fn new(
        root: [u8; COMMIT_ROOT_BYTES],
        leaf_count: u64,
        signature: [u8; ATTESTATION_SIGNATURE_BYTES],
        signer: [u8; ATTESTATION_SIGNER_BYTES],
    ) -> Self {
        Self {
            root,
            leaf_count,
            signature,
            signer,
        }
    }

    /// Returns the attested commit root.
    #[must_use]
    pub const fn root(&self) -> &[u8; COMMIT_ROOT_BYTES] {
        &self.root
    }

    /// Returns how many leaves the root covers.
    #[must_use]
    pub const fn leaf_count(&self) -> u64 {
        self.leaf_count
    }

    /// Returns the signature over the root.
    #[must_use]
    pub const fn signature(&self) -> &[u8; ATTESTATION_SIGNATURE_BYTES] {
        &self.signature
    }

    /// Returns the signer key that produced the signature.
    #[must_use]
    pub const fn signer(&self) -> &[u8; ATTESTATION_SIGNER_BYTES] {
        &self.signer
    }
}

/// The exact source frontier one projection generation covers.
#[derive(Clone, PartialEq, Eq)]
pub struct SourceCheckpoint {
    source: JournalSource,
    feed_position: u64,
    journal_position: u64,
    evidence_leaf: u64,
    covering_attestation: JournalAttestation,
}

impl SourceCheckpoint {
    /// Records one exact source frontier.
    #[must_use]
    pub const fn new(
        source: JournalSource,
        feed_position: u64,
        journal_position: u64,
        evidence_leaf: u64,
        covering_attestation: JournalAttestation,
    ) -> Self {
        Self {
            source,
            feed_position,
            journal_position,
            evidence_leaf,
            covering_attestation,
        }
    }

    /// Returns the lineage this checkpoint covers.
    #[must_use]
    pub const fn source(&self) -> &JournalSource {
        &self.source
    }

    /// Returns the feed position.
    #[must_use]
    pub const fn feed_position(&self) -> u64 {
        self.feed_position
    }

    /// Returns the journal position.
    #[must_use]
    pub const fn journal_position(&self) -> u64 {
        self.journal_position
    }

    /// Returns the evidence leaf index.
    #[must_use]
    pub const fn evidence_leaf(&self) -> u64 {
        self.evidence_leaf
    }

    /// Returns the attestation covering this checkpoint.
    #[must_use]
    pub const fn covering_attestation(&self) -> &JournalAttestation {
        &self.covering_attestation
    }
}

/// How long a stored object is retained.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Retention {
    /// Retained for a fixed duration.
    For(Duration),
    /// Retained until an explicit release.
    UntilReleased,
}

/// What protection a stored object's content requires.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Classification {
    /// Readable without restriction.
    Public,
    /// Internal to the deployment.
    Internal,
    /// Confidential tenant content.
    Confidential,
    /// The most restricted class.
    Restricted,
}

/// One immutable stored object generation.
#[derive(Clone, PartialEq, Eq)]
pub struct ObjectDescriptor {
    object: String,
    generation: u64,
    digest: [u8; DIGEST_BYTES],
    owner: String,
    classification: Classification,
    retention: Retention,
    byte_len: u64,
    content_reference: String,
}

impl ObjectDescriptor {
    /// Records one immutable object generation.
    ///
    /// # Errors
    ///
    /// Returns [`ModelError::Bounds`] for an empty object id, owner, or
    /// content reference.
    #[allow(
        clippy::too_many_arguments,
        reason = "every field of the signed descriptor is named explicitly"
    )]
    pub fn try_new(
        object: String,
        generation: u64,
        digest: [u8; DIGEST_BYTES],
        owner: String,
        classification: Classification,
        retention: Retention,
        byte_len: u64,
        content_reference: String,
    ) -> Result<Self, ModelError> {
        non_empty("object", &object)?;
        non_empty("owner", &owner)?;
        non_empty("content_reference", &content_reference)?;
        Ok(Self {
            object,
            generation,
            digest,
            owner,
            classification,
            retention,
            byte_len,
            content_reference,
        })
    }

    /// Returns the object id.
    #[must_use]
    pub fn object(&self) -> &str {
        &self.object
    }

    /// Returns the object generation.
    #[must_use]
    pub const fn generation(&self) -> u64 {
        self.generation
    }

    /// Returns the content digest.
    #[must_use]
    pub const fn digest(&self) -> &[u8; DIGEST_BYTES] {
        &self.digest
    }

    /// Returns the owner.
    #[must_use]
    pub fn owner(&self) -> &str {
        &self.owner
    }

    /// Returns the content classification.
    #[must_use]
    pub const fn classification(&self) -> Classification {
        self.classification
    }

    /// Returns the retention policy.
    #[must_use]
    pub const fn retention(&self) -> Retention {
        self.retention
    }

    /// Returns the stored byte length.
    #[must_use]
    pub const fn byte_len(&self) -> u64 {
        self.byte_len
    }

    /// Returns the content reference.
    #[must_use]
    pub fn content_reference(&self) -> &str {
        &self.content_reference
    }
}

/// One exact stored object in one namespace.
#[derive(Clone, PartialEq, Eq)]
pub struct ExactObjectRef {
    namespace: String,
    key: String,
    backend_generation: u64,
}

impl ExactObjectRef {
    /// Names one exact stored generation.
    ///
    /// # Errors
    ///
    /// Returns [`ModelError::Bounds`] for an empty namespace or key.
    pub fn try_new(
        namespace: String,
        key: String,
        backend_generation: u64,
    ) -> Result<Self, ModelError> {
        non_empty("namespace", &namespace)?;
        non_empty("key", &key)?;
        Ok(Self {
            namespace,
            key,
            backend_generation,
        })
    }

    /// Returns the object namespace.
    #[must_use]
    pub fn namespace(&self) -> &str {
        &self.namespace
    }

    /// Returns the object key.
    #[must_use]
    pub fn key(&self) -> &str {
        &self.key
    }

    /// Returns the backend generation.
    #[must_use]
    pub const fn backend_generation(&self) -> u64 {
        self.backend_generation
    }
}

/// One projection family bound to one source partition.
#[derive(Clone, PartialEq, Eq)]
pub struct ProjectionKey {
    family: String,
    source_partition: String,
}

impl ProjectionKey {
    /// Names one projection key.
    ///
    /// # Errors
    ///
    /// Returns [`ModelError::Bounds`] for an empty family or partition.
    pub fn try_new(family: String, source_partition: String) -> Result<Self, ModelError> {
        non_empty("family", &family)?;
        non_empty("source_partition", &source_partition)?;
        Ok(Self {
            family,
            source_partition,
        })
    }

    /// Returns the family name.
    #[must_use]
    pub fn family(&self) -> &str {
        &self.family
    }

    /// Returns the source partition.
    #[must_use]
    pub fn source_partition(&self) -> &str {
        &self.source_partition
    }
}

/// The publisher term that produced one generation.
#[derive(Clone, PartialEq, Eq)]
pub struct PublisherFence {
    key: ProjectionKey,
    source_incarnation: [u8; INCARNATION_BYTES],
    term: u64,
}

impl PublisherFence {
    /// Records one publisher term.
    ///
    /// # Errors
    ///
    /// Returns [`ModelError::Bounds`] for a zero term.
    pub fn try_new(
        key: ProjectionKey,
        source_incarnation: [u8; INCARNATION_BYTES],
        term: u64,
    ) -> Result<Self, ModelError> {
        if term == 0 {
            return Err(ModelError::Bounds("term"));
        }
        Ok(Self {
            key,
            source_incarnation,
            term,
        })
    }

    /// Returns the fenced projection key.
    #[must_use]
    pub const fn key(&self) -> &ProjectionKey {
        &self.key
    }

    /// Returns the fenced source incarnation.
    #[must_use]
    pub const fn source_incarnation(&self) -> &[u8; INCARNATION_BYTES] {
        &self.source_incarnation
    }

    /// Returns the publisher term.
    #[must_use]
    pub const fn term(&self) -> u64 {
        self.term
    }
}

/// One published projection generation, described exactly.
#[derive(Clone, PartialEq, Eq)]
pub struct ProjectionManifest {
    key: ProjectionKey,
    generation: u64,
    checkpoint: SourceCheckpoint,
    schema_version: u32,
    fact_version: u32,
    object: ObjectDescriptor,
    artifact_object: ExactObjectRef,
    publisher: String,
    fence: PublisherFence,
}

impl ProjectionManifest {
    /// Records one exact published generation.
    ///
    /// # Errors
    ///
    /// Returns [`ModelError::Bounds`] for a zero generation, a zero schema or
    /// fact version, or an empty publisher.
    #[allow(
        clippy::too_many_arguments,
        reason = "every field of the signed manifest is named explicitly"
    )]
    pub fn try_new(
        key: ProjectionKey,
        generation: u64,
        checkpoint: SourceCheckpoint,
        schema_version: u32,
        fact_version: u32,
        object: ObjectDescriptor,
        artifact_object: ExactObjectRef,
        publisher: String,
        fence: PublisherFence,
    ) -> Result<Self, ModelError> {
        if generation == 0 {
            return Err(ModelError::Bounds("generation"));
        }
        if schema_version == 0 {
            return Err(ModelError::Bounds("schema_version"));
        }
        if fact_version == 0 {
            return Err(ModelError::Bounds("fact_version"));
        }
        non_empty("publisher", &publisher)?;
        Ok(Self {
            key,
            generation,
            checkpoint,
            schema_version,
            fact_version,
            object,
            artifact_object,
            publisher,
            fence,
        })
    }

    /// Returns the projection key.
    #[must_use]
    pub const fn key(&self) -> &ProjectionKey {
        &self.key
    }

    /// Returns the projection generation.
    #[must_use]
    pub const fn generation(&self) -> u64 {
        self.generation
    }

    /// Returns the source checkpoint.
    #[must_use]
    pub const fn checkpoint(&self) -> &SourceCheckpoint {
        &self.checkpoint
    }

    /// Returns the schema version.
    #[must_use]
    pub const fn schema_version(&self) -> u32 {
        self.schema_version
    }

    /// Returns the fact version.
    #[must_use]
    pub const fn fact_version(&self) -> u32 {
        self.fact_version
    }

    /// Returns the manifest's own object descriptor.
    #[must_use]
    pub const fn object(&self) -> &ObjectDescriptor {
        &self.object
    }

    /// Returns the exact artifact object reference.
    #[must_use]
    pub const fn artifact_object(&self) -> &ExactObjectRef {
        &self.artifact_object
    }

    /// Returns the publisher identity.
    #[must_use]
    pub fn publisher(&self) -> &str {
        &self.publisher
    }

    /// Returns the publisher fence.
    #[must_use]
    pub const fn fence(&self) -> &PublisherFence {
        &self.fence
    }
}

/// One anchored journal prefix.
#[derive(Clone, PartialEq, Eq)]
pub struct JournalAnchor {
    source: JournalSource,
    head: u64,
}

impl JournalAnchor {
    /// Records one anchored journal prefix.
    #[must_use]
    pub const fn new(source: JournalSource, head: u64) -> Self {
        Self { source, head }
    }

    /// Returns the anchored lineage.
    #[must_use]
    pub const fn source(&self) -> &JournalSource {
        &self.source
    }

    /// Returns the anchored head position.
    #[must_use]
    pub const fn head(&self) -> u64 {
        self.head
    }
}

/// One exact source premise a result read.
#[derive(Clone, PartialEq, Eq)]
pub enum SourcePin {
    /// An exact published projection generation.
    ///
    /// Boxed: a manifest is far larger than the other two premises, and an
    /// unboxed variant would make every pin in a thirty-two-pin vector that
    /// size.
    Projected(Box<ProjectionManifest>),
    /// An exact anchored journal prefix.
    Journal(JournalAnchor),
    /// An authoritative revision.
    Authoritative(u64),
}

impl SourcePin {
    /// Returns the canonical identity this pin sorts by.
    ///
    /// The rule matches the durable audit's own: a variant tag, then each
    /// source's identity as length-prefixed bytes. Two projected descriptors
    /// for one key, two anchors for one partition, and two authoritative
    /// revisions therefore compare equal and are refused rather than
    /// collapsed.
    #[must_use]
    pub fn identity_bytes(&self) -> Vec<u8> {
        let mut bytes = Vec::new();
        match self {
            Self::Projected(manifest) => {
                bytes.push(0);
                push_len_prefixed(&mut bytes, manifest.key().family().as_bytes());
                push_len_prefixed(&mut bytes, manifest.key().source_partition().as_bytes());
            }
            Self::Journal(anchor) => {
                bytes.push(1);
                push_len_prefixed(&mut bytes, anchor.source().partition().as_bytes());
            }
            Self::Authoritative(_) => bytes.push(2),
        }
        bytes
    }
}

/// The bounded, canonical source premises one result reports.
#[derive(Clone, PartialEq, Eq)]
pub struct SourceEvidence {
    pins: Vec<SourcePin>,
}

impl SourceEvidence {
    /// Bounds and canonicalizes one complete source vector.
    ///
    /// # Errors
    ///
    /// Returns [`ModelError::Bounds`] past [`MAX_SOURCE_PINS`], and
    /// [`ModelError::Order`] when the pins are not strictly ascending by
    /// identity. A duplicate source is an out-of-order pin, never a silent
    /// collapse.
    pub fn try_new(pins: Vec<SourcePin>) -> Result<Self, ModelError> {
        if pins.len() > MAX_SOURCE_PINS {
            return Err(ModelError::Bounds("source_pins"));
        }
        for pair in pins.windows(2) {
            if pair[0].identity_bytes() >= pair[1].identity_bytes() {
                return Err(ModelError::Order("source_pins"));
            }
        }
        Ok(Self { pins })
    }

    /// Returns every exact source premise in canonical order.
    #[must_use]
    pub fn pins(&self) -> &[SourcePin] {
        &self.pins
    }
}

// ---------------------------------------------------------------------------
// Shape-only formatting
// ---------------------------------------------------------------------------
//
// Source evidence names partitions, object keys, namespaces, publishers,
// signer keys, and signatures. `Debug` is what a `tracing` field and an
// `#[instrument]` attribute render, so every type here formats its shape and
// nothing that addresses tenant content. The typed getters above remain the
// way a mechanism reads the values it genuinely needs.

impl fmt::Debug for JournalSource {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("JournalSource")
    }
}

impl fmt::Debug for JournalAttestation {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("JournalAttestation")
            .field("leaf_count", &self.leaf_count)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for SourceCheckpoint {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("SourceCheckpoint")
            .field("feed_position", &self.feed_position)
            .field("journal_position", &self.journal_position)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for ObjectDescriptor {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ObjectDescriptor")
            .field("generation", &self.generation)
            .field("classification", &self.classification)
            .field("byte_len", &self.byte_len)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for ExactObjectRef {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ExactObjectRef")
            .field("backend_generation", &self.backend_generation)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for ProjectionKey {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("ProjectionKey")
    }
}

impl fmt::Debug for PublisherFence {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("PublisherFence")
            .field("term", &self.term)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for ProjectionManifest {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ProjectionManifest")
            .field("generation", &self.generation)
            .field("schema_version", &self.schema_version)
            .field("fact_version", &self.fact_version)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for JournalAnchor {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("JournalAnchor")
            .field("head", &self.head)
            .finish_non_exhaustive()
    }
}

impl fmt::Debug for SourcePin {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(match self {
            Self::Projected(_) => "projected",
            Self::Journal(_) => "journal",
            Self::Authoritative(_) => "authoritative",
        })
    }
}

impl fmt::Debug for SourceEvidence {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("SourceEvidence")
            .field("pins", &self.pins.len())
            .finish()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn journal(partition: &str) -> SourcePin {
        SourcePin::Journal(JournalAnchor::new(
            JournalSource::try_new(partition.to_owned(), [7; INCARNATION_BYTES]).unwrap(),
            4,
        ))
    }

    #[test]
    fn pins_must_be_strictly_ascending_and_bounded() {
        assert!(SourceEvidence::try_new(vec![journal("a"), journal("b")]).is_ok());
        assert_eq!(
            SourceEvidence::try_new(vec![journal("b"), journal("a")]),
            Err(ModelError::Order("source_pins"))
        );
        assert_eq!(
            SourceEvidence::try_new(vec![journal("a"), journal("a")]),
            Err(ModelError::Order("source_pins")),
            "one partition may be anchored once"
        );

        let overflowing = (0..=MAX_SOURCE_PINS)
            .map(|index| journal(&format!("p{index:04}")))
            .collect();
        assert_eq!(
            SourceEvidence::try_new(overflowing),
            Err(ModelError::Bounds("source_pins"))
        );
    }

    #[test]
    fn identity_ignores_everything_except_the_source_it_names() {
        let first = SourcePin::Journal(JournalAnchor::new(
            JournalSource::try_new("a".to_owned(), [1; INCARNATION_BYTES]).unwrap(),
            1,
        ));
        let second = SourcePin::Journal(JournalAnchor::new(
            JournalSource::try_new("a".to_owned(), [2; INCARNATION_BYTES]).unwrap(),
            9,
        ));
        assert_eq!(first.identity_bytes(), second.identity_bytes());
    }

    #[test]
    fn structural_bounds_refuse_empty_identifiers() {
        assert_eq!(
            JournalSource::try_new(String::new(), [0; INCARNATION_BYTES]),
            Err(ModelError::Bounds("partition"))
        );
        assert_eq!(
            ProjectionKey::try_new(String::new(), "p".to_owned()),
            Err(ModelError::Bounds("family"))
        );
        assert_eq!(
            ExactObjectRef::try_new("ns".to_owned(), String::new(), 1),
            Err(ModelError::Bounds("key"))
        );
    }
}