hawdb-storage 0.14.0

// Copyright 2026 Nowledge
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Inward read contract for the graph engine.
//!
//! The embedded facade may depend on this observability surface instead of the
//! concrete `GraphStore`. Execution-time store contracts already live in
//! `hawdb_executor::store` (`GraphExecutionRead` / `GraphExecutionWrite`), so
//! this trait deliberately covers only the read/observability surface the
//! facade itself consumes.

use crate::{
    append_table::{AppendSegmentReadOutput, AppendTableSchema},
    cache::SegmentCacheSnapshot,
    projection::StorageRecoveryReport,
    read_view::PublishedReadView,
    relational::RelationalKey,
    residency::StorageResidencyReport,
};
use hawdb_core::{BasicGraphStatistics, Catalog, GraphStatistics, Result};

/// Read-only observability surface consumed by the embedded facade.
pub trait GraphReadEngine {
    fn storage_version(&self) -> &'static str;

    fn commit_epoch(&self) -> u64;

    fn storage_handle_poisoned(&self) -> bool;

    fn published_read_view(&self) -> PublishedReadView;

    fn basic_statistics(&self) -> BasicGraphStatistics;

    fn statistics(&self, catalog: &Catalog) -> GraphStatistics;

    /// Whether a declared range index delivers ascending `Value::cmp` order
    /// through both full and projected execution visitors on this read view.
    /// A descriptor alone is not sufficient: an out-of-core base needs a
    /// complete backing projection. External engines opt in explicitly.
    fn supports_ordered_node_range(&self, _label: hawdb_core::LabelId, _property: &str) -> bool {
        false
    }

    fn storage_recovery_report(&self) -> StorageRecoveryReport;

    fn segment_cache_snapshot(&self) -> Option<SegmentCacheSnapshot>;

    fn storage_residency_report(&self) -> StorageResidencyReport;

    fn adjacency_consistency_report(&self) -> crate::consistency::AdjacencyConsistencyReport;

    fn adjacency_consolidation_plan(&self) -> crate::consistency::AdjacencyConsolidationPlan;

    fn degree_statistics_consistency_report(
        &self,
    ) -> crate::consistency::DegreeStatisticsConsistencyReport;

    fn property_index_consistency_report(
        &self,
        catalog: &Catalog,
    ) -> crate::consistency::PropertyIndexConsistencyReport;

    fn columnar_shadow_checkpoint_report(
        &self,
    ) -> Option<crate::column_group::shadow::ColumnarShadowCheckpointReport>;

    fn columnar_shadow_recovery_status(
        &self,
    ) -> crate::column_group::shadow::ColumnarShadowRecoveryStatus;

    fn projected_graph_statuses(&self) -> Vec<crate::projection::ProjectedGraphStatus>;

    fn storage_pressure_snapshot(
        &self,
        oldest_reader_commit_epoch: Option<u64>,
    ) -> crate::pressure::StoragePressureSnapshot;

    fn append_storage_residency_report(&self) -> crate::append_table::AppendStorageResidencyReport;

    fn columnar_shadow_admission_bytes(&self) -> u64;

    fn relational_index_recovery_report(
        &self,
    ) -> Option<&crate::relational::RelationalIndexRecoveryReport>;

    fn relational_index_shadow_checkpoint_report(
        &self,
    ) -> Option<&crate::relational::RelationalIndexShadowCheckpointReport>;

    fn relational_index_shadow_recovery_status(
        &self,
    ) -> &crate::relational::RelationalIndexShadowRecoveryStatus;

    fn search_projection_changefeed_status(
        &self,
    ) -> crate::projection::SearchProjectionChangefeedStatus;

    fn append_table_schema(&self, table: &str) -> Option<&AppendTableSchema>;

    fn initial_import_source_fingerprint(&self) -> Option<&str>;

    fn read_append_partition_bounded(
        &self,
        table: &str,
        partition: &RelationalKey,
        after: Option<&RelationalKey>,
        max_rows: usize,
        max_payload_bytes: usize,
    ) -> Result<AppendSegmentReadOutput>;

    fn node_records_owned(&self) -> crate::graph_overlay::GraphNodeIterator;

    fn relationship_records_owned(&self) -> crate::graph_overlay::GraphRelationshipIterator;
}

/// Maintenance/commit surface the embedded facade drives itself.
///
/// This deliberately does not restate the execution write contract: statement
/// execution goes through `hawdb_executor::store::GraphExecutionWrite`
/// (`commit_mutation_with_limits` and friends). These are the storage-lifecycle
/// operations the facade schedules directly.
pub trait GraphMutationEngine {
    fn plan_schema_maintenance(
        &self,
        catalog: &Catalog,
    ) -> Vec<crate::projection::SchemaMaintenancePlanItem>;

    fn run_schema_maintenance(
        &mut self,
        catalog: &mut Catalog,
    ) -> Result<Vec<crate::projection::SchemaMaintenanceAction>>;

    fn rebuild_projected_graph_artifacts(&mut self, catalog: &Catalog) -> Result<()>;

    fn rebuild_bounded_property_index_projections(
        &mut self,
        catalog: &Catalog,
        max_estimated_operations: usize,
    ) -> Vec<crate::projection::PropertyIndexProjectionRebuildAction>;

    fn scrub_storage(&mut self) -> Result<crate::backup::StorageScrubReport>;

    fn backup_to(
        &mut self,
        catalog: &Catalog,
        destination: impl AsRef<std::path::Path>,
    ) -> Result<crate::backup::StorageBackupReport>;

    fn register_projected_graph(
        &mut self,
        name: &str,
        definition: crate::projection::ProjectedGraphDefinition,
    ) -> Result<()>;
}