uor-foundation 0.2.0

// @generated by uor-crate from uor-ontology — do not edit manually

//! `resolver/` namespace — Type resolution strategies implementing the partition map Π : T_n → Part(R_n). Resolvers transform type declarations into ring partitions..
//!
//! Space: Bridge

use crate::enums::ComplexityClass;
use crate::enums::MetricAxis;
use crate::enums::WittLevel;
use crate::Primitives;

/// A strategy for resolving a type declaration into a partition of the ring. The kernel dispatches to a specific resolver based on the type's structure.
/// Disjoint with: ResolutionState, RefinementSuggestion.
pub trait Resolver<P: Primitives> {
    /// Associated type for `TypeDefinition`.
    type TypeDefinition: crate::user::type_::TypeDefinition<P>;
    /// The type of input this resolver accepts.
    fn input_type(&self) -> &Self::TypeDefinition;
    /// Associated type for `Partition`.
    type Partition: crate::bridge::partition::Partition<P>;
    /// The type of output this resolver produces. For all UOR resolvers, the output is a partition:Partition.
    fn output_type(&self) -> &Self::Partition;
    /// Associated type for `TermExpression`.
    type TermExpression: crate::kernel::schema::TermExpression<P>;
    /// A human-readable description of the resolution strategy this resolver implements.
    fn strategy(&self) -> &Self::TermExpression;
    /// Associated type for `ResolutionState`.
    type ResolutionState: ResolutionState<P>;
    /// The current resolution state of this resolver.
    fn resolution_state(&self) -> &Self::ResolutionState;
    /// The computational complexity class of this resolver. Replaces the string-valued resolver:complexity property.
    fn has_complexity_class(&self) -> ComplexityClass;
    /// Associated type for `DispatchTable`.
    type DispatchTable: crate::kernel::predicate::DispatchTable<P>;
    /// The dispatch table governing resolver selection for this resolver class.
    fn dispatch_table(&self) -> &Self::DispatchTable;
    /// Associated type for `TypePredicate`.
    type TypePredicate: crate::kernel::predicate::TypePredicate<P>;
    /// The predicate that selects this specific resolver. When the predicate evaluates to true on an input type, this resolver is chosen.
    fn resolver_predicate(&self) -> &Self::TypePredicate;
}

/// Resolves types by factoring the ring under dihedral group action. Identifies orbits under D_{2^n} to determine irreducibility boundaries.
pub trait DihedralFactorizationResolver<P: Primitives>: Resolver<P> {}

/// Resolves types by computing canonical forms via term rewriting. Applies the critical identity and normalization rules to reduce terms to unique canonical representatives.
pub trait CanonicalFormResolver<P: Primitives>: Resolver<P> {}

/// Resolves types by direct evaluation: applies operations to enumerate ring elements and classify them as irreducible, reducible, unit, or exterior.
pub trait EvaluationResolver<P: Primitives>: Resolver<P> {}

/// The current state of an iterative resolution: tracks how many iterations have been performed, whether the resolution is complete, and the current site deficit.
/// Disjoint with: Resolver, RefinementSuggestion.
pub trait ResolutionState<P: Primitives> {
    /// Whether this resolution is complete: all sites are pinned and the partition is fully determined.
    fn is_complete(&self) -> P::Boolean;
    /// The number of refinement iterations performed so far.
    fn iteration_count(&self) -> P::NonNegativeInteger;
    /// Associated type for `FreeRank`.
    type FreeRank: crate::bridge::partition::FreeRank<P>;
    /// The site budget showing the remaining unpinned sites. When all sites are pinned, the deficit is zero and resolution is complete.
    fn site_deficit(&self) -> &Self::FreeRank;
    /// Associated type for `RefinementSuggestion`.
    type RefinementSuggestion: RefinementSuggestion<P>;
    /// A refinement suggestion for advancing this resolution.
    fn suggestion(&self) -> &[Self::RefinementSuggestion];
    /// The rate at which sites are being pinned per iteration. A higher rate indicates faster convergence toward a complete resolution.
    fn convergence_rate(&self) -> P::Decimal;
    /// Associated type for `CechNerve`.
    type CechNerve: CechNerve<P>;
    /// The constraint nerve associated with this resolution state.
    fn cech_nerve(&self) -> &Self::CechNerve;
    /// The residual Shannon entropy of the resolution state: S = freeRank × ln 2. Measures remaining uncertainty.
    fn residual_entropy(&self) -> P::Decimal;
    /// Whether all Betti numbers of the constraint nerve are zero, indicating no topological obstructions to resolution.
    fn topologically_complete(&self) -> P::Boolean;
    /// The Euler characteristic χ(N(C)) of the active constraint nerve at this resolution state. IT_7d requires this value to equal n (the quantum level) for resolution to be complete. Cached here to avoid recomputing the full ψ pipeline on each iteration check.
    fn nerve_euler_characteristic(&self) -> P::Integer;
    /// Associated type for `Jacobian`.
    type Jacobian: crate::bridge::observable::Jacobian<P>;
    /// The Jacobian observable guiding constraint selection at this resolution state (DC_10).
    fn guiding_jacobian(&self) -> &Self::Jacobian;
}

/// A suggestion from the resolver for how to refine an incomplete resolution: which metric axis to explore, which class to narrow to, and which sites to target.
/// Disjoint with: Resolver, ResolutionState.
pub trait RefinementSuggestion<P: Primitives> {
    /// The metric axis this suggestion recommends exploring.
    fn suggested_axis(&self) -> MetricAxis;
    /// The constraint class this suggestion recommends applying.
    fn suggested_class(&self) -> &P::String;
    /// Associated type for `SiteIndex`.
    type SiteIndex: crate::bridge::partition::SiteIndex<P>;
    /// The site coordinates this suggestion targets for pinning.
    fn target_sites(&self) -> &[Self::SiteIndex];
}

/// The simplicial complex whose vertices are constraints and where a k-simplex exists iff the corresponding k+1 constraints have nonempty intersection. The nerve's topology governs resolution convergence: trivial homology ↔ smooth convergence, non-trivial homology ↔ potential stalls.
pub trait CechNerve<P: Primitives>:
    crate::bridge::homology::SimplicialComplex<P> + crate::bridge::homology::KanComplex<P>
{
}

/// A specialisation of Resolver driving the completeness certification loop. Accepts a CompletenessCandidate, runs the ψ-pipeline (reading nerveEulerCharacteristic from ResolutionState), and either issues a CompletenessCertificate or produces a RefinementSuggestion.
pub trait CompletenessResolver<P: Primitives>: Resolver<P> {
    /// Associated type for `CompletenessCandidate`.
    type CompletenessCandidate: crate::user::type_::CompletenessCandidate<P>;
    /// The CompletenessCandidate this resolver is certifying.
    fn completeness_target(&self) -> &Self::CompletenessCandidate;
}

/// A Resolver parameterised by quantum level. The same resolver strategy runs at any quantum level n ≥ 1 by substituting the appropriate R_n ring.
pub trait WittLevelResolver<P: Primitives>: Resolver<P> {
    /// The quantum level this resolver instance is configured for.
    fn quantum_level(&self) -> WittLevel;
}

/// A Resolver that maintains a BindingAccumulator across multiple RelationQuery evaluations. The top-level resolver for multi-turn Prism deployments.
pub trait SessionResolver<P: Primitives>: Resolver<P> {
    /// Associated type for `BindingAccumulator`.
    type BindingAccumulator: crate::user::state::BindingAccumulator<P>;
    /// The BindingAccumulator this session resolver maintains across multiple RelationQuery evaluations.
    fn session_accumulator(&self) -> &Self::BindingAccumulator;
    /// Associated type for `ExecutionPolicy`.
    type ExecutionPolicy: ExecutionPolicy<P>;
    /// The ordering strategy this resolver applies to pending queries. Defaults to FifoPolicy if unset.
    fn execution_policy(&self) -> &Self::ExecutionPolicy;
}

/// A Resolver that runs the ψ-pipeline in inverse mode. Accepts a TypeSynthesisGoal and returns a TypeSynthesisResult. Internally maintains a ConstraintSearchState tracking which constraint combinations have been explored and which Betti profiles they realise.
pub trait TypeSynthesisResolver<P: Primitives>: Resolver<P> {
    /// Associated type for `TypeSynthesisGoal`.
    type TypeSynthesisGoal: crate::user::type_::TypeSynthesisGoal<P>;
    /// The goal this type synthesis resolver is working to achieve.
    fn synthesis_goal(&self) -> &Self::TypeSynthesisGoal;
}

/// Internal resolver state tracking the boundary of explored constraint combinations during synthesis. Carries exploredCount, currentCandidate, and a link to the best SynthesisSignature achieved so far.
pub trait ConstraintSearchState<P: Primitives> {
    /// Number of constraint combinations evaluated so far during synthesis.
    fn explored_count(&self) -> P::NonNegativeInteger;
    /// Associated type for `ConstrainedType`.
    type ConstrainedType: crate::user::type_::ConstrainedType<P>;
    /// The type candidate currently being evaluated during synthesis.
    fn current_candidate(&self) -> &Self::ConstrainedType;
}

/// A Resolver that determines whether a CompleteType T at Q_n lifts to a CompleteType at Q_{n+1} without re-running the full ψ-pipeline from scratch. It computes the SpectralSequencePage sequence, reads the LiftObstruction, and either confirms the lift or returns a LiftRefinementSuggestion.
pub trait IncrementalCompletenessResolver<P: Primitives>: Resolver<P> {
    /// Associated type for `WittLift`.
    type WittLift: crate::user::type_::WittLift<P>;
    /// The WittLift this incremental completeness resolver is evaluating.
    fn lift_target(&self) -> &Self::WittLift;
}

/// A RefinementSuggestion produced when a WittLift has a non-trivial LiftObstruction. Specialises RefinementSuggestion with liftSitePosition (the new bit position n+1) and obstructionClass.
pub trait LiftRefinementSuggestion<P: Primitives>: RefinementSuggestion<P> {
    /// The new site position at Q_{n+1} that the lift refinement suggestion targets.
    fn lift_site_position(&self) -> &Self::SiteIndex;
    /// Associated type for `LiftObstructionClass`.
    type LiftObstructionClass: crate::bridge::observable::LiftObstructionClass<P>;
    /// The obstruction class this lift refinement suggestion is designed to kill.
    fn obstruction_class(&self) -> &Self::LiftObstructionClass;
}

/// A Resolver that computes the HolonomyGroup of a ConstrainedType by enumerating closed paths in the constraint nerve and accumulating DihedralElement values. Outputs a MonodromyClass and classifies the type as FlatType or TwistedType.
pub trait MonodromyResolver<P: Primitives>: Resolver<P> {
    /// Associated type for `ConstrainedType`.
    type ConstrainedType: crate::user::type_::ConstrainedType<P>;
    /// The type whose holonomy this monodromy resolver is computing.
    fn monodromy_target(&self) -> &Self::ConstrainedType;
    /// Associated type for `HolonomyGroup`.
    type HolonomyGroup: crate::bridge::observable::HolonomyGroup<P>;
    /// The HolonomyGroup produced by this monodromy resolver run.
    fn holonomy_result(&self) -> &Self::HolonomyGroup;
}

/// A resolver that uses the Jacobian matrix to guide constraint selection, implementing DC_10: select the constraint that maximises total curvature reduction.
pub trait JacobianGuidedResolver<P: Primitives>: Resolver<P> {}

/// A resolver that handles superposed site states, computing amplitudes and determining when superposition collapses to a classical site assignment (Amendment 32).
pub trait SuperpositionResolver<P: Primitives>: Resolver<P> {
    /// The amplitude vector of all branches maintained by this SuperpositionResolver during ψ-pipeline traversal. Encoded as a comma-separated list of decimal amplitudes. Must satisfy Σ|αᵢ|² = 1 (QM_5) after normalization.
    fn amplitude_vector(&self) -> P::Decimal;
}

/// A resolver that exploits accumulated session bindings at full saturation (σ = 1) to provide O(1) resolution via direct coordinate reads (SC_5).
pub trait GroundingAwareResolver<P: Primitives>: Resolver<P> {
    /// Whether this resolver used the saturation shortcut (SC_5) to bypass the ψ-pipeline and return a direct coordinate read.
    fn used_grounding(&self) -> P::Boolean;
}

/// A resolver that validates whether a ComputationTrace satisfies the dual geodesic condition (AR_1-ordered and DC_10-selected). Produces GeodesicViolation individuals on failure.
pub trait GeodesicValidator<P: Primitives>: Resolver<P> {
    /// Associated type for `GeodesicTrace`.
    type GeodesicTrace: crate::bridge::trace::GeodesicTrace<P>;
    /// The GeodesicTrace being validated by this GeodesicValidator.
    fn validate_geodesic(&self) -> &Self::GeodesicTrace;
}

/// A resolver that handles projective collapse of SuperposedSiteState components. Issues MeasurementCertificate upon successful collapse with QM_1 verification.
pub trait MeasurementResolver<P: Primitives>: Resolver<P> {
    /// The amplitude of the SuperposedSiteState prior to projective collapse by this MeasurementResolver.
    fn collapse_amplitude(&self) -> P::Decimal;
    /// The site index that was collapsed (pinned to a classical value) by the projective measurement.
    fn collapsed_site(&self) -> P::NonNegativeInteger;
    /// The classical value obtained from the projective collapse. Either 0 or 1 for a single-site measurement.
    fn measurement_outcome(&self) -> P::NonNegativeInteger;
    /// The full vector of all branch amplitudes before projective collapse. Recorded by the MeasurementResolver to enable Born rule verification (QM_5): P(outcome k) = |α_k|².
    fn prior_amplitude_vector(&self) -> P::Decimal;
}

/// A Resolver that constructs a LiftChain from liftSourceLevel to an arbitrary liftTargetLevel Q_k by iterating IncrementalCompletenessResolver step by step.
pub trait TowerCompletenessResolver<P: Primitives>: Resolver<P> {
    /// The level at which the tower starts.
    fn tower_source_level(&self) -> WittLevel;
    /// The level to which the tower is being built.
    fn tower_target_level(&self) -> WittLevel;
    /// Associated type for `LiftChain`.
    type LiftChain: crate::user::type_::LiftChain<P>;
    /// The LiftChain under construction.
    fn current_chain(&self) -> &Self::LiftChain;
    /// Associated type for `IncrementalCompletenessResolver`.
    type IncrementalCompletenessResolver: IncrementalCompletenessResolver<P>;
    /// The IncrementalCompletenessResolver used for each single-step lift.
    fn tower_step_resolver(&self) -> &Self::IncrementalCompletenessResolver;
}

/// A strategy class that defines how a SessionResolver orders pending RelationQuery instances for dispatch. The policy reads the targetSite.freeRank of each pending query and applies an ordering function.
/// Disjoint with: Resolver, ResolutionState, RefinementSuggestion.
pub trait ExecutionPolicy<P: Primitives> {}

/// A resolver that runs the extended ψ-pipeline (ψ_7–ψ_9) to compute the full homotopy type of a CechNerve. Returns HomotopyGroup observables and PostnikovTruncation records.
pub trait HomotopyResolver<P: Primitives>: Resolver<P> {
    /// Associated type for `CechNerve`.
    type CechNerve: CechNerve<P>;
    /// The CechNerve whose homotopy type this resolver computes.
    fn homotopy_target(&self) -> &Self::CechNerve;
    /// Associated type for `HomotopyGroup`.
    type HomotopyGroup: crate::bridge::observable::HomotopyGroup<P>;
    /// A HomotopyGroup observable produced by this resolver.
    fn homotopy_result(&self) -> &[Self::HomotopyGroup];
}

/// A resolver that computes the local structure of the moduli space at a given CompleteType: constructs the DeformationComplex, determines the HolonomyStratum, and computes tangent/obstruction dimensions.
pub trait ModuliResolver<P: Primitives>: Resolver<P> {
    /// Associated type for `CompleteType`.
    type CompleteType: crate::user::type_::CompleteType<P>;
    /// The CompleteType whose local moduli structure this resolver computes.
    fn moduli_target(&self) -> &Self::CompleteType;
    /// Associated type for `DeformationComplex`.
    type DeformationComplex: crate::bridge::homology::DeformationComplex<P>;
    /// The DeformationComplex constructed by this resolver.
    fn moduli_deformation(&self) -> &Self::DeformationComplex;
}

/// O(1) complexity — the resolver runs in constant time regardless of ring size.
pub mod constant_time {}

/// O(log n) complexity — the resolver runs in logarithmic time in the quantum level.
pub mod logarithmic_time {}

/// O(n) complexity — the resolver runs in time linear in the quantum level.
pub mod linear_time {}

/// O(2^n) complexity — the resolver runs in time exponential in the quantum level.
pub mod exponential_time {}

/// Process queries in arrival order. The implicit pre-Amendment 48 behavior.
pub mod fifo_policy {}

/// Process the query with the smallest targetSite.freeRank first. Favors cheapest resolutions, accelerating early grounding gain.
pub mod min_free_count_first {}

/// Process the query with the largest targetSite.freeRank first. Favors hardest resolutions, maximizing information gain per step.
pub mod max_free_count_first {}

/// Process queries whose targetSite is disjoint from all other pending queries' site sets first. Minimizes contention when operating against a SharedContext.
pub mod disjoint_first {}