icydb-core 0.211.0

//! Module: db::schema::identity
//! Responsibility: durable schema identity primitives.
//! Does not own: generated model validation or persisted schema reconciliation.
//! Boundary: small copyable identifiers shared by schema proposal and live-schema code.

use std::num::NonZeroU32;

///
/// ConstraintId
///
/// Stable non-zero identity for one accepted constraint within an entity's
/// schema history.
///

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub(in crate::db) struct ConstraintId(NonZeroU32);

impl ConstraintId {
    /// Admit one non-zero persisted constraint identity.
    #[must_use]
    pub(in crate::db) const fn new(raw: u32) -> Option<Self> {
        match NonZeroU32::new(raw) {
            Some(raw) => Some(Self(raw)),
            None => None,
        }
    }

    /// Return the persisted integer identity.
    #[must_use]
    pub(in crate::db) const fn get(self) -> u32 {
        self.0.get()
    }
}

///
/// ConstraintIdAllocator
///
/// Persisted non-reusing high-water state for entity-local constraint IDs.
/// Dropping or aborting a constraint never lowers this value.
///

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub(in crate::db) struct ConstraintIdAllocator {
    high_water: Option<ConstraintId>,
}

impl ConstraintIdAllocator {
    /// Build allocator state from its trusted persisted high-water value.
    #[must_use]
    pub(in crate::db) const fn new(high_water: u32) -> Self {
        Self {
            high_water: ConstraintId::new(high_water),
        }
    }

    /// Return the greatest constraint ID ever reserved by this entity.
    #[must_use]
    pub(in crate::db) const fn high_water(self) -> u32 {
        match self.high_water {
            Some(high_water) => high_water.get(),
            None => 0,
        }
    }
}

///
/// SchemaIndexId
///
/// Stable non-zero logical identity for one accepted secondary-index
/// definition. Physical index keys continue to use dense runtime ordinals.
///

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub(in crate::db) struct SchemaIndexId(NonZeroU32);

impl SchemaIndexId {
    /// Admit one non-zero persisted logical index identity.
    #[must_use]
    pub(in crate::db) const fn new(raw: u32) -> Option<Self> {
        match NonZeroU32::new(raw) {
            Some(raw) => Some(Self(raw)),
            None => None,
        }
    }

    /// Return the persisted integer identity.
    #[must_use]
    pub(in crate::db) const fn get(self) -> u32 {
        self.0.get()
    }
}

///
/// RelationId
///
/// Stable non-zero logical identity for one accepted relation definition.
/// Relation key encoding remains owned by the existing relation contract.
///

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub(in crate::db) struct RelationId(NonZeroU32);

impl RelationId {
    /// Admit one non-zero persisted relation identity.
    #[must_use]
    pub(in crate::db) const fn new(raw: u32) -> Option<Self> {
        match NonZeroU32::new(raw) {
            Some(raw) => Some(Self(raw)),
            None => None,
        }
    }

    /// Return the persisted integer identity.
    #[must_use]
    pub(in crate::db) const fn get(self) -> u32 {
        self.0.get()
    }
}

///
/// FieldId
///
/// Durable identity for one logical schema field.
/// This ID is distinct from generated Rust field order and from executor slot
/// indexes so schema reconciliation can preserve identity across safe reorders
/// and renames.
///

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub(in crate::db) struct FieldId(u32);

impl FieldId {
    /// Build one field ID from a trusted persisted value.
    #[must_use]
    pub(in crate::db) const fn new(raw: u32) -> Self {
        Self(raw)
    }

    /// Return the raw persisted field identity.
    #[must_use]
    pub(in crate::db) const fn get(self) -> u32 {
        self.0
    }

    /// Assign the initial schema ID for a generated field slot.
    ///
    /// The first generated snapshot has no prior durable identity source, so it
    /// derives IDs deterministically from generated slot order. Reconciliation
    /// preserves stored IDs instead of recalculating them.
    #[must_use]
    pub(in crate::db) fn from_initial_slot(slot: usize) -> Self {
        let next = u32::try_from(slot)
            .expect("schema identity invariant")
            .checked_add(1)
            .expect("schema identity invariant");

        Self(next)
    }
}

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

    #[test]
    fn constraint_allocator_preserves_reserved_high_water_identity() {
        let empty = ConstraintIdAllocator::default();
        let reserved = ConstraintIdAllocator::new(7);

        assert_eq!(empty.high_water(), 0);
        assert_eq!(reserved.high_water(), 7);
    }

    #[test]
    fn logical_structural_ids_reject_zero() {
        assert_eq!(SchemaIndexId::new(0), None);
        assert_eq!(RelationId::new(0), None);
    }
}