Module solver_contract 

Outer-objective contract (lower shared layer)

The interface types that the families layer must name, implement, and return to participate in outer smoothing-parameter optimization, hosted below both families and solver so families stop importing up into crate::solver::rho_optimizer (#1135).

What lives here is exactly the family ↔ solver contract: the matrix-free HessianOperator trait that families implement, the OuterEval result they return, the EfsEval step bundle, and the capability enums (Derivative, DeclaredHessianForm, HessianMaterialization) plus GAM-specific outer-strategy errors (OuterStrategyError). The generic Hessian contract and payload are owned by opt and re-exported here.

What does not live here is the solver’s use of the contract — the outer runner, ARC/trust-region planning, seeding, caching, barrier configuration, and OuterProblem — all of which stay in crate::solver::rho_optimizer and depend downward on this module. crate::solver::rho_optimizer re-exports these names so existing crate::solver::rho_optimizer::* paths keep working.

Structs

EfsEval

Result bundle returned by the EFS (extended Fellner–Schall) evaluation path. Pure data: families compute the additive step and the optional curvature/gradient diagnostics; the solver consumes them.

FixedPointCertificateEval

Objective-owned proof sample used only for final fixed-point certification.

OuterEval

Shared outer-objective result used by optimizer-facing objective implementations.

Enums

DeclaredHessianForm

Capability-time declaration of what shape the outer Hessian takes. Replaces the binary Derivative for the Hessian field on OuterCapability: callers that know the shape upfront declare it here, and the planner routes between dense ARC and matrix-free trust-region before seed evaluation rather than dynamically branching on seed_eval.hessian at runtime.

Derivative

Whether an analytic derivative is available for a given order.

FixedPointCoordinateCertificate

One coordinate of an objective-supplied final fixed-point certificate.

HessianMaterialization

How (and whether) a HessianOperator can produce a dense materialized Hessian. Reported by HessianOperator::materialization() so a trust-region or ARC solver can decide between calling materialize_dense once and falling back to repeated Hessian-vector products through apply_into.

HessianValue

Exact Hessian payload used by operator-aware optimizers and objective contracts.

ObjectiveEvalError

OuterStrategyError

Typed error for the outer-strategy Hessian-operator surface.

Traits

HessianOperator

An exact analytic Hessian-vector product (and optional materialization).