kvbm-logical 1.3.0-dev.1

// SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! Logical block lifecycle management for KVBM.
//!
//! This crate provides the core block lifecycle system:
//! - Type-safe state transitions (Reset -> Complete -> Registered)
//! - Block registry with deduplication and attachments
//! - Active/inactive/reset pool management
//! - Event pipeline for distributed coordination
//! - Block manager orchestration

pub mod blocks;
pub mod events;
pub mod integrations;
pub mod manager;
pub mod metrics;
pub mod pools;
pub mod pubsub;
pub mod registry;
pub mod sequence;
pub mod tinylfu;

#[cfg(any(test, feature = "testing"))]
pub mod testing;

use std::sync::atomic::{AtomicU64, Ordering};

use bincode::{Decode, Encode};
use serde::{Deserialize, Serialize};

// Re-export common types and traits
pub use blocks::{
    BlockError, BlockMetadata, CompleteBlock, ImmutableBlock, LifecyclePin, LifecyclePinRef,
    MutableBlock, WeakBlock,
};
pub use integrations::{
    ApplyError, DecodeOutcome, NoopDelegate, RequestSequence, SchedulableSequence,
    SchedulableSequenceBuilder, ScheduleError, SequenceDelegate, SequenceEvent, SequenceState,
};
pub use manager::BlockManager;
pub use registry::BlockRegistry;
pub use sequence::{
    BlockSequence, BlockSequenceError, ExternalBlockAssignments, LogicalBlockAssignmentError,
    LogicalBlockAssignments, zip_assigned, zip_assigned_pending,
};

pub type BlockId = usize;
pub type SequenceHash = dynamo_tokens::PositionalLineageHash;

/// Stable, process-unique identifier for a `BlockManager`'s underlying
/// `BlockStore`.
///
/// Generated by an atomic counter at `BlockStore` construction; never
/// reused. Two [`LifecyclePinRef`]s with the same `ManagerId` come from
/// the same physical pool; together with [`BlockId`] this disambiguates
/// a slot's logical address after policy-type erasure (downstream callers
/// that hold `Arc<dyn LifecyclePin>` lose the manager type parameter but
/// keep the runtime address).
///
/// The reserved value [`ManagerId::NULL`] is never assigned to a real
/// store — callers may use it as a null/test sentinel.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Encode, Decode, Serialize, Deserialize)]
pub struct ManagerId(pub u64);

impl ManagerId {
    /// Sentinel never assigned to a real `BlockStore`.
    pub const NULL: Self = Self(0);

    /// Allocate the next process-unique `ManagerId`.  Atomic counter,
    /// `Relaxed` ordering — uniqueness is guaranteed by `fetch_add`,
    /// happens-before is not needed for an opaque scalar id.
    pub(crate) fn next() -> Self {
        static NEXT: AtomicU64 = AtomicU64::new(1);
        Self(NEXT.fetch_add(1, Ordering::Relaxed))
    }
}

pub trait KvbmSequenceHashProvider {
    fn kvbm_sequence_hash(&self) -> SequenceHash;
}

impl KvbmSequenceHashProvider for dynamo_tokens::TokenBlock {
    fn kvbm_sequence_hash(&self) -> SequenceHash {
        self.positional_lineage_hash()
    }
}

/// Logical layout handle type encoding the layout ID.
///
/// KVBM manages G1, G2 and G3 layouts directly. G4 is managed by an external service.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Encode, Decode, Serialize, Deserialize)]
pub enum LogicalLayoutHandle {
    /// Representation of GPU / Device Memory
    G1,
    /// Representation of CPU / Host Memory
    G2,
    /// Representation of Disk Storage
    G3,
    /// Representation of Blocks held in an external service
    /// outside the control of the KVBM system.
    G4,
}