reddb_server/application/

ports.rs

//! Application ports that carry invariants not owned by transports.
//!
//! - Entity enforces collection contracts, normalization, uniqueness, and write policy.
//! - Schema and tree translate typed commands while preserving their structural rules.
//! - Admin and native guard lifecycle transitions and physical-authority operations.
//! - Graph resolves projections and applies traversal/analytics limits.
//! - VCS preserves repository, history, and conflict invariants.
//!
//! Query and catalog reads are deliberately absent: callers already own the runtime,
//! and an interface that only repeats its methods is not an application boundary.

use std::collections::BTreeMap;

use crate::application::entity::{
    apply_patch_operations_to_json, apply_patch_operations_to_storage_map,
    apply_patch_operations_to_vector_fields, json_to_metadata_value, json_to_storage_value,
    metadata_from_json, metadata_to_json, CreateDocumentInput, CreateEdgeInput, CreateEntityOutput,
    CreateKvInput, CreateNodeInput, CreateRowInput, CreateRowsBatchInput,
    CreateTimeSeriesPointInput, CreateVectorInput, DeleteEntityInput, DeleteEntityOutput,
    PatchEntityInput, PatchEntityOperation, PatchEntityOperationType,
};
use crate::application::schema::{
    CreateTableInput, CreateTimeSeriesInput, DropTableInput, DropTimeSeriesInput,
};
use crate::application::tree::{
    CreateTreeInput, DeleteTreeNodeInput, DropTreeInput, InsertTreeNodeInput, MoveTreeNodeInput,
    RebalanceTreeInput, ValidateTreeInput,
};
use crate::health::HealthProvider;
use crate::physical::{ExportDescriptor, ManifestEvent, PhysicalMetadataFile, SnapshotDescriptor};
use crate::runtime::{
    RedDBRuntime, RuntimeFilter, RuntimeGraphCentralityAlgorithm, RuntimeGraphCentralityResult,
    RuntimeGraphClusteringResult, RuntimeGraphCommunityResult, RuntimeGraphComponentsMode,
    RuntimeGraphComponentsResult, RuntimeGraphCyclesResult, RuntimeGraphDirection,
    RuntimeGraphHitsResult, RuntimeGraphNeighborhoodResult, RuntimeGraphPathAlgorithm,
    RuntimeGraphPathResult, RuntimeGraphPattern, RuntimeGraphProjection,
    RuntimeGraphPropertiesResult, RuntimeGraphTopologicalSortResult, RuntimeGraphTraversalResult,
    RuntimeGraphTraversalStrategy, RuntimeQueryResult,
};
use crate::storage::engine::PhysicalFileHeader;
use crate::storage::unified::devx::refs::{NodeRef, TableRef, VectorRef};
use crate::storage::unified::devx::{
    NativeVectorArtifactBatchInspection, NativeVectorArtifactInspection, PhysicalAuthorityStatus,
};
use crate::storage::unified::store::{
    NativeCatalogSummary, NativeManifestSummary, NativeMetadataStateSummary, NativePhysicalState,
    NativeRecoverySummary, NativeRegistrySummary, NativeVectorArtifactPageSummary,
};
use crate::RedDBResult;
use crate::{PhysicalAnalyticsJob, PhysicalGraphProjection, PhysicalIndexState};

pub trait RuntimeEntityPort {
    fn create_row(&self, input: CreateRowInput) -> RedDBResult<CreateEntityOutput>;
    fn create_rows_batch(
        &self,
        input: CreateRowsBatchInput,
    ) -> RedDBResult<Vec<CreateEntityOutput>>;
    /// Pre-validated bulk insert — caller has already checked column
    /// types and uniqueness. Server skips
    /// `normalize_row_fields_for_contract`, `enforce_row_uniqueness`,
    /// and `enforce_row_batch_uniqueness`. Returns the row count.
    /// Used by `MSG_BULK_INSERT_PREVALIDATED`.
    fn create_rows_batch_prevalidated(&self, input: CreateRowsBatchInput) -> RedDBResult<usize>;
    /// Pre-validated bulk insert that also returns the persisted rows and assigned ids.
    fn create_rows_batch_prevalidated_with_outputs(
        &self,
        input: CreateRowsBatchInput,
    ) -> RedDBResult<Vec<CreateEntityOutput>>;
    /// Columnar pre-validated bulk insert — the wire handler
    /// decoded straight into `Vec<Vec<Value>>` + a shared column-
    /// name vector, no per-cell `(String, Value)` tuples allocated.
    /// Avoids ~N×ncols String clones vs the tuple path. The schema
    /// is shared across every row as a single `Arc<Vec<String>>`.
    fn create_rows_batch_prevalidated_columnar(
        &self,
        collection: String,
        column_names: std::sync::Arc<Vec<String>>,
        rows: Vec<Vec<reddb_types::Value>>,
    ) -> RedDBResult<usize>;
    /// Columnar bulk insert with full contract validation — wire
    /// handler shape (one `Arc<Vec<String>>` schema shared across
    /// every row, `Vec<Vec<Value>>` row payload). Equivalent to
    /// `create_rows_batch` semantically but skips the per-row
    /// `(String, Value)` tuple materialisation in the wire decoder.
    /// When the collection has no contract (or no declared columns)
    /// fast-paths to `create_rows_batch_prevalidated_columnar`;
    /// otherwise falls back to the tuple path so contract
    /// normalisation can run.
    fn create_rows_batch_columnar(
        &self,
        collection: String,
        column_names: std::sync::Arc<Vec<String>>,
        rows: Vec<Vec<reddb_types::Value>>,
    ) -> RedDBResult<usize>;
    /// Columnar bulk insert that also returns assigned entity ids.
    /// Kept separate from [`Self::create_rows_batch_columnar`] so bulk wire
    /// callers can retain their count-only contract.
    fn create_rows_batch_columnar_with_outputs(
        &self,
        collection: String,
        column_names: std::sync::Arc<Vec<String>>,
        rows: Vec<Vec<reddb_types::Value>>,
    ) -> RedDBResult<Vec<CreateEntityOutput>>;
    fn create_node(&self, input: CreateNodeInput) -> RedDBResult<CreateEntityOutput>;
    fn create_edge(&self, input: CreateEdgeInput) -> RedDBResult<CreateEntityOutput>;
    fn create_vector(&self, input: CreateVectorInput) -> RedDBResult<CreateEntityOutput>;
    fn create_document(&self, input: CreateDocumentInput) -> RedDBResult<CreateEntityOutput>;
    fn create_kv(&self, input: CreateKvInput) -> RedDBResult<CreateEntityOutput>;
    fn create_timeseries_point(
        &self,
        input: CreateTimeSeriesPointInput,
    ) -> RedDBResult<CreateEntityOutput>;
    fn get_kv(
        &self,
        collection: &str,
        key: &str,
    ) -> RedDBResult<Option<(reddb_types::Value, crate::storage::EntityId)>>;
    fn delete_kv(&self, collection: &str, key: &str) -> RedDBResult<bool>;
    fn patch_entity(&self, input: PatchEntityInput) -> RedDBResult<CreateEntityOutput>;
    fn delete_entity(&self, input: DeleteEntityInput) -> RedDBResult<DeleteEntityOutput>;
}

pub trait RuntimeSchemaPort {
    fn create_table(&self, input: CreateTableInput) -> RedDBResult<RuntimeQueryResult>;
    fn drop_table(&self, input: DropTableInput) -> RedDBResult<RuntimeQueryResult>;
    fn create_timeseries(&self, input: CreateTimeSeriesInput) -> RedDBResult<RuntimeQueryResult>;
    fn drop_timeseries(&self, input: DropTimeSeriesInput) -> RedDBResult<RuntimeQueryResult>;
}

pub trait RuntimeTreePort {
    fn create_tree(&self, input: CreateTreeInput) -> RedDBResult<RuntimeQueryResult>;
    fn drop_tree(&self, input: DropTreeInput) -> RedDBResult<RuntimeQueryResult>;
    fn insert_tree_node(&self, input: InsertTreeNodeInput) -> RedDBResult<RuntimeQueryResult>;
    fn move_tree_node(&self, input: MoveTreeNodeInput) -> RedDBResult<RuntimeQueryResult>;
    fn delete_tree_node(&self, input: DeleteTreeNodeInput) -> RedDBResult<RuntimeQueryResult>;
    fn validate_tree(&self, input: ValidateTreeInput) -> RedDBResult<RuntimeQueryResult>;
    fn rebalance_tree(&self, input: RebalanceTreeInput) -> RedDBResult<RuntimeQueryResult>;
}

pub trait RuntimeAdminPort {
    fn set_index_enabled(&self, name: &str, enabled: bool) -> RedDBResult<PhysicalIndexState>;
    fn mark_index_building(&self, name: &str) -> RedDBResult<PhysicalIndexState>;
    fn fail_index(&self, name: &str) -> RedDBResult<PhysicalIndexState>;
    fn mark_index_stale(&self, name: &str) -> RedDBResult<PhysicalIndexState>;
    fn mark_index_ready(&self, name: &str) -> RedDBResult<PhysicalIndexState>;
    fn warmup_index_with_lifecycle(&self, name: &str) -> RedDBResult<PhysicalIndexState>;
    fn rebuild_indexes_with_lifecycle(
        &self,
        collection: Option<&str>,
    ) -> RedDBResult<Vec<PhysicalIndexState>>;
    fn save_graph_projection(
        &self,
        name: impl Into<String>,
        projection: RuntimeGraphProjection,
        source: Option<String>,
    ) -> RedDBResult<PhysicalGraphProjection>;
    fn mark_graph_projection_materializing(
        &self,
        name: &str,
    ) -> RedDBResult<PhysicalGraphProjection>;
    fn materialize_graph_projection(&self, name: &str) -> RedDBResult<PhysicalGraphProjection>;
    fn fail_graph_projection(&self, name: &str) -> RedDBResult<PhysicalGraphProjection>;
    fn mark_graph_projection_stale(&self, name: &str) -> RedDBResult<PhysicalGraphProjection>;
    fn save_analytics_job(
        &self,
        kind: impl Into<String>,
        projection_name: Option<String>,
        metadata: BTreeMap<String, String>,
    ) -> RedDBResult<PhysicalAnalyticsJob>;
    fn start_analytics_job(
        &self,
        kind: impl Into<String>,
        projection_name: Option<String>,
        metadata: BTreeMap<String, String>,
    ) -> RedDBResult<PhysicalAnalyticsJob>;
    fn queue_analytics_job(
        &self,
        kind: impl Into<String>,
        projection_name: Option<String>,
        metadata: BTreeMap<String, String>,
    ) -> RedDBResult<PhysicalAnalyticsJob>;
    fn fail_analytics_job(
        &self,
        kind: impl Into<String>,
        projection_name: Option<String>,
        metadata: BTreeMap<String, String>,
    ) -> RedDBResult<PhysicalAnalyticsJob>;
    fn mark_analytics_job_stale(
        &self,
        kind: impl Into<String>,
        projection_name: Option<String>,
        metadata: BTreeMap<String, String>,
    ) -> RedDBResult<PhysicalAnalyticsJob>;
    fn complete_analytics_job(
        &self,
        kind: impl Into<String>,
        projection_name: Option<String>,
        metadata: BTreeMap<String, String>,
    ) -> RedDBResult<PhysicalAnalyticsJob>;
}

pub trait RuntimeNativePort {
    fn health_report(&self) -> crate::health::HealthReport;
    fn health_report_from_catalog(
        &self,
        _catalog: &crate::catalog::CatalogModelSnapshot,
    ) -> crate::health::HealthReport {
        self.health_report()
    }
    /// Derive all readiness flags from one caller-owned health observation.
    /// The default preserves compatibility with ports implementing scalar checks.
    fn readiness_from_health(
        &self,
        _report: &crate::health::HealthReport,
    ) -> crate::application::native::RuntimeReadiness {
        crate::application::native::RuntimeReadiness {
            query: self.readiness_for_query(),
            query_serverless: self.readiness_for_query_serverless(),
            write: self.readiness_for_write(),
            write_serverless: self.readiness_for_write_serverless(),
            repair: self.readiness_for_repair(),
            repair_serverless: self.readiness_for_repair_serverless(),
        }
    }
    fn collection_roots(&self) -> RedDBResult<BTreeMap<String, u64>>;
    fn snapshots(&self) -> RedDBResult<Vec<SnapshotDescriptor>>;
    fn exports(&self) -> RedDBResult<Vec<ExportDescriptor>>;
    fn physical_metadata(&self) -> RedDBResult<PhysicalMetadataFile>;
    fn manifest_events_filtered(
        &self,
        collection: Option<&str>,
        kind: Option<&str>,
        since_snapshot: Option<u64>,
    ) -> RedDBResult<Vec<ManifestEvent>>;
    fn create_snapshot(&self) -> RedDBResult<SnapshotDescriptor>;
    fn create_export(&self, name: String) -> RedDBResult<ExportDescriptor>;
    fn checkpoint(&self) -> RedDBResult<()>;
    fn apply_retention_policy(&self) -> RedDBResult<()>;
    fn run_maintenance(&self) -> RedDBResult<()>;
    fn native_header(&self) -> RedDBResult<PhysicalFileHeader>;
    fn native_collection_roots(&self) -> RedDBResult<BTreeMap<String, u64>>;
    fn native_manifest_summary(&self) -> RedDBResult<NativeManifestSummary>;
    fn native_registry_summary(&self) -> RedDBResult<NativeRegistrySummary>;
    fn native_recovery_summary(&self) -> RedDBResult<NativeRecoverySummary>;
    fn native_catalog_summary(&self) -> RedDBResult<NativeCatalogSummary>;
    fn native_physical_state(&self) -> RedDBResult<NativePhysicalState>;
    fn native_vector_artifact_pages(&self) -> RedDBResult<Vec<NativeVectorArtifactPageSummary>>;
    fn inspect_native_vector_artifact(
        &self,
        collection: &str,
        artifact_kind: Option<&str>,
    ) -> RedDBResult<NativeVectorArtifactInspection>;
    fn warmup_native_vector_artifact(
        &self,
        collection: &str,
        artifact_kind: Option<&str>,
    ) -> RedDBResult<NativeVectorArtifactInspection>;
    fn inspect_native_vector_artifacts(&self) -> RedDBResult<NativeVectorArtifactBatchInspection>;
    fn warmup_native_vector_artifacts(&self) -> RedDBResult<NativeVectorArtifactBatchInspection>;
    fn native_header_repair_policy(&self) -> RedDBResult<String>;
    fn repair_native_header_from_metadata(&self) -> RedDBResult<String>;
    fn rebuild_physical_metadata_from_native_state(&self) -> RedDBResult<bool>;
    fn repair_native_physical_state_from_metadata(&self) -> RedDBResult<bool>;
    fn native_metadata_state_summary(&self) -> RedDBResult<NativeMetadataStateSummary>;
    fn physical_authority_status(&self) -> PhysicalAuthorityStatus;
    fn validate_current_serverless_generation(&self) -> RedDBResult<()>;
    fn readiness_for_query(&self) -> bool;
    fn readiness_for_query_serverless(&self) -> bool;
    fn readiness_for_write(&self) -> bool;
    fn readiness_for_write_serverless(&self) -> bool;
    fn readiness_for_repair(&self) -> bool;
    fn readiness_for_repair_serverless(&self) -> bool;
}

pub trait RuntimeGraphPort {
    fn resolve_graph_projection(
        &self,
        name: Option<&str>,
        inline: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<Option<RuntimeGraphProjection>>;
    fn graph_neighborhood(
        &self,
        node: &str,
        direction: RuntimeGraphDirection,
        max_depth: usize,
        edge_labels: Option<Vec<String>>,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphNeighborhoodResult>;
    fn graph_traverse(
        &self,
        source: &str,
        direction: RuntimeGraphDirection,
        max_depth: usize,
        strategy: RuntimeGraphTraversalStrategy,
        edge_labels: Option<Vec<String>>,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphTraversalResult>;
    fn graph_shortest_path(
        &self,
        source: &str,
        target: &str,
        direction: RuntimeGraphDirection,
        algorithm: RuntimeGraphPathAlgorithm,
        edge_labels: Option<Vec<String>>,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphPathResult>;
    fn graph_components(
        &self,
        mode: RuntimeGraphComponentsMode,
        min_size: usize,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphComponentsResult>;
    fn graph_centrality(
        &self,
        algorithm: RuntimeGraphCentralityAlgorithm,
        top_k: usize,
        normalize: bool,
        max_iterations: Option<usize>,
        epsilon: Option<f64>,
        alpha: Option<f64>,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphCentralityResult>;
    fn graph_communities(
        &self,
        algorithm: crate::runtime::RuntimeGraphCommunityAlgorithm,
        min_size: usize,
        max_iterations: Option<usize>,
        resolution: Option<f64>,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphCommunityResult>;
    fn graph_clustering(
        &self,
        top_k: usize,
        include_triangles: bool,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphClusteringResult>;
    fn graph_personalized_pagerank(
        &self,
        seeds: Vec<String>,
        top_k: usize,
        alpha: Option<f64>,
        epsilon: Option<f64>,
        max_iterations: Option<usize>,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphCentralityResult>;
    fn graph_hits(
        &self,
        top_k: usize,
        epsilon: Option<f64>,
        max_iterations: Option<usize>,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphHitsResult>;
    fn graph_cycles(
        &self,
        max_length: usize,
        max_cycles: usize,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphCyclesResult>;
    fn graph_topological_sort(
        &self,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphTopologicalSortResult>;
    fn graph_properties(
        &self,
        projection: Option<RuntimeGraphProjection>,
    ) -> RedDBResult<RuntimeGraphPropertiesResult>;
}

pub trait RuntimeVcsPort {
    fn vcs_commit(
        &self,
        input: crate::application::vcs::CreateCommitInput,
    ) -> RedDBResult<crate::application::vcs::Commit>;

    fn vcs_branch_create(
        &self,
        input: crate::application::vcs::CreateBranchInput,
    ) -> RedDBResult<crate::application::vcs::Ref>;

    fn vcs_branch_delete(&self, name: &str) -> RedDBResult<()>;

    fn vcs_tag_create(
        &self,
        input: crate::application::vcs::CreateTagInput,
    ) -> RedDBResult<crate::application::vcs::Ref>;

    fn vcs_tag_delete(&self, name: &str) -> RedDBResult<()>;

    fn vcs_list_refs(&self, prefix: Option<&str>)
        -> RedDBResult<Vec<crate::application::vcs::Ref>>;

    fn vcs_checkout(
        &self,
        input: crate::application::vcs::CheckoutInput,
    ) -> RedDBResult<crate::application::vcs::Ref>;

    fn vcs_merge(
        &self,
        input: crate::application::vcs::MergeInput,
    ) -> RedDBResult<crate::application::vcs::MergeOutcome>;

    fn vcs_cherry_pick(
        &self,
        connection_id: u64,
        commit: &str,
        author: crate::application::vcs::Author,
    ) -> RedDBResult<crate::application::vcs::MergeOutcome>;

    fn vcs_revert(
        &self,
        connection_id: u64,
        commit: &str,
        author: crate::application::vcs::Author,
    ) -> RedDBResult<crate::application::vcs::Commit>;

    fn vcs_reset(&self, input: crate::application::vcs::ResetInput) -> RedDBResult<()>;

    fn vcs_log(
        &self,
        input: crate::application::vcs::LogInput,
    ) -> RedDBResult<Vec<crate::application::vcs::Commit>>;

    fn vcs_diff(
        &self,
        input: crate::application::vcs::DiffInput,
    ) -> RedDBResult<crate::application::vcs::Diff>;

    fn vcs_status(
        &self,
        input: crate::application::vcs::StatusInput,
    ) -> RedDBResult<crate::application::vcs::Status>;

    fn vcs_lca(&self, a: &str, b: &str)
        -> RedDBResult<Option<crate::application::vcs::CommitHash>>;

    fn vcs_conflicts_list(
        &self,
        merge_state_id: &str,
    ) -> RedDBResult<Vec<crate::application::vcs::Conflict>>;

    fn vcs_conflict_resolve(
        &self,
        conflict_id: &str,
        resolved: crate::json::Value,
    ) -> RedDBResult<()>;

    fn vcs_resolve_as_of(
        &self,
        spec: crate::application::vcs::AsOfSpec,
    ) -> RedDBResult<crate::storage::transaction::snapshot::Xid>;

    fn vcs_resolve_commitish(&self, spec: &str)
        -> RedDBResult<crate::application::vcs::CommitHash>;

    fn vcs_set_versioned(&self, collection: &str, enabled: bool) -> RedDBResult<()>;
    fn vcs_list_versioned(&self) -> RedDBResult<Vec<String>>;
    fn vcs_is_versioned(&self, collection: &str) -> RedDBResult<bool>;
}

/// Context-aware extension trait that mirrors `RuntimeEntityPort`
/// with `&OperationContext` threaded through every method.
///
/// This is the migration runway for the `OperationContext` deepening
/// (PLAN cluster 6). Each default implementation forwards to the
/// existing context-less method, so today the trait is a pure
/// pass-through — but new callers can already adopt the
/// context-passing surface, and a future PR will replace the
/// defaults with real impls that read `ctx.xid` / `ctx.write_consent`.
///
/// Hidden behind the `ctx-ports` feature flag during the migration
/// window so the impl bloat doesn't burden default builds. Once
/// every port is migrated, the flag goes away and these traits
/// become the only surface.
pub trait RuntimeEntityPortCtx: RuntimeEntityPort {
    fn create_row_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateRowInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.create_row(input)
    }
    fn create_node_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateNodeInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.create_node(input)
    }
    fn create_edge_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateEdgeInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.create_edge(input)
    }
    fn create_vector_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateVectorInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.create_vector(input)
    }
    fn create_document_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateDocumentInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.create_document(input)
    }
    fn create_kv_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateKvInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.create_kv(input)
    }
    fn create_timeseries_point_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateTimeSeriesPointInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.create_timeseries_point(input)
    }
    fn get_kv_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        collection: &str,
        key: &str,
    ) -> RedDBResult<Option<(reddb_types::Value, crate::storage::EntityId)>> {
        let _ = ctx;
        self.get_kv(collection, key)
    }
    fn delete_kv_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        collection: &str,
        key: &str,
    ) -> RedDBResult<bool> {
        let _ = ctx;
        self.delete_kv(collection, key)
    }
    fn patch_entity_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: PatchEntityInput,
    ) -> RedDBResult<CreateEntityOutput> {
        let _ = ctx;
        self.patch_entity(input)
    }
    fn delete_entity_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: DeleteEntityInput,
    ) -> RedDBResult<DeleteEntityOutput> {
        let _ = ctx;
        self.delete_entity(input)
    }
}

/// Blanket impl: every concrete `RuntimeEntityPort` automatically
/// gains the context-aware surface via the default forwards above.
impl<T: RuntimeEntityPort + ?Sized> RuntimeEntityPortCtx for T {}

// ─── ctx extension traits for the remaining mutating ports ───
//
// Same pattern as RuntimeEntityPortCtx: methods take
// `&OperationContext` first, default-forward to the existing
// context-less call. Blanket impls give every concrete port
// the new surface for free. Future PRs replace the forwards
// with real `ctx.write_consent` / `ctx.xid` handling.
//
// Read-only ports (RuntimeGraphPort) and the
// read-only methods of mutating ports are intentionally absent —
// `OperationContext` adds no locality there until the snapshot-
// xid migration also lands.

pub trait RuntimeSchemaPortCtx: RuntimeSchemaPort {
    fn create_table_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateTableInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.create_table(input)
    }
    fn drop_table_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: DropTableInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.drop_table(input)
    }
    fn create_timeseries_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateTimeSeriesInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.create_timeseries(input)
    }
    fn drop_timeseries_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: DropTimeSeriesInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.drop_timeseries(input)
    }
}
impl<T: RuntimeSchemaPort + ?Sized> RuntimeSchemaPortCtx for T {}

pub trait RuntimeTreePortCtx: RuntimeTreePort {
    fn create_tree_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: CreateTreeInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.create_tree(input)
    }
    fn drop_tree_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: DropTreeInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.drop_tree(input)
    }
    fn insert_tree_node_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: InsertTreeNodeInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.insert_tree_node(input)
    }
    fn move_tree_node_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: MoveTreeNodeInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.move_tree_node(input)
    }
    fn delete_tree_node_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: DeleteTreeNodeInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.delete_tree_node(input)
    }
    fn rebalance_tree_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: RebalanceTreeInput,
    ) -> RedDBResult<RuntimeQueryResult> {
        let _ = ctx;
        self.rebalance_tree(input)
    }
}
impl<T: RuntimeTreePort + ?Sized> RuntimeTreePortCtx for T {}

pub trait RuntimeNativePortCtx: RuntimeNativePort {
    fn create_snapshot_ctx(
        &self,
        ctx: &crate::application::OperationContext,
    ) -> RedDBResult<SnapshotDescriptor> {
        let _ = ctx;
        self.create_snapshot()
    }
    fn create_export_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        name: String,
    ) -> RedDBResult<ExportDescriptor> {
        let _ = ctx;
        self.create_export(name)
    }
    fn checkpoint_ctx(&self, ctx: &crate::application::OperationContext) -> RedDBResult<()> {
        let _ = ctx;
        self.checkpoint()
    }
    fn apply_retention_policy_ctx(
        &self,
        ctx: &crate::application::OperationContext,
    ) -> RedDBResult<()> {
        let _ = ctx;
        self.apply_retention_policy()
    }
    fn run_maintenance_ctx(&self, ctx: &crate::application::OperationContext) -> RedDBResult<()> {
        let _ = ctx;
        self.run_maintenance()
    }
    fn repair_native_header_from_metadata_ctx(
        &self,
        ctx: &crate::application::OperationContext,
    ) -> RedDBResult<String> {
        let _ = ctx;
        self.repair_native_header_from_metadata()
    }
    fn rebuild_physical_metadata_from_native_state_ctx(
        &self,
        ctx: &crate::application::OperationContext,
    ) -> RedDBResult<bool> {
        let _ = ctx;
        self.rebuild_physical_metadata_from_native_state()
    }
}
impl<T: RuntimeNativePort + ?Sized> RuntimeNativePortCtx for T {}

pub trait RuntimeVcsPortCtx: RuntimeVcsPort {
    fn vcs_branch_delete_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        name: &str,
    ) -> RedDBResult<()> {
        let _ = ctx;
        self.vcs_branch_delete(name)
    }
    fn vcs_reset_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        input: crate::application::vcs::ResetInput,
    ) -> RedDBResult<()> {
        let _ = ctx;
        self.vcs_reset(input)
    }
    fn vcs_set_versioned_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        collection: &str,
        enabled: bool,
    ) -> RedDBResult<()> {
        let _ = ctx;
        self.vcs_set_versioned(collection, enabled)
    }
    fn vcs_conflict_resolve_ctx(
        &self,
        ctx: &crate::application::OperationContext,
        conflict_id: &str,
        resolved: crate::json::Value,
    ) -> RedDBResult<()> {
        let _ = ctx;
        self.vcs_conflict_resolve(conflict_id, resolved)
    }
}
impl<T: RuntimeVcsPort + ?Sized> RuntimeVcsPortCtx for T {}

/// Port for native migration operations.
///
/// Stub methods — full implementations land in subsequent slices.
pub trait RuntimeMigrationPort {
    /// Register a new migration definition (status = pending).
    fn migration_create(&self, input: MigrationCreateInput) -> RedDBResult<RuntimeQueryResult>;
    /// Apply a named migration (or `*` for all pending).
    fn migration_apply(&self, name: &str) -> RedDBResult<RuntimeQueryResult>;
    /// Roll back an applied migration.
    fn migration_rollback(&self, name: &str) -> RedDBResult<RuntimeQueryResult>;
    /// Explain a migration without executing it.
    fn migration_explain(&self, name: &str) -> RedDBResult<RuntimeQueryResult>;
    /// List migrations, optionally filtered by status.
    fn migration_list(&self, status: Option<&str>) -> RedDBResult<RuntimeQueryResult>;
}

/// Minimal input type for `migration_create`. Expanded in later slices.
#[derive(Debug, Clone)]
pub struct MigrationCreateInput {
    pub name: String,
    pub kind: MigrationKind,
    pub body: String,
    pub author: String,
    pub depends_on: Vec<String>,
    pub batch_size: Option<u64>,
    pub no_rollback: bool,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MigrationKind {
    Ddl,
    Data,
}

#[path = "ports_impls.rs"]
mod ports_impls;
pub(crate) use ports_impls::build_row_update_contract_plan;
pub(crate) use ports_impls::entity_row_fields_snapshot;
pub(crate) use ports_impls::normalize_row_update_assignment_with_plan;
pub(crate) use ports_impls::normalize_row_update_value_for_rule;