import { VecN } from '@holotope/core';
import { XpbdIncrementalPotentialProblemN, type XpbdPackedIncrementalPotentialEvaluationN } from './xpbd-incremental-potential-problem.js';
import { XpbdParticleN, type XpbdConservativeForceProviderEvaluationN, type XpbdConservativeForceProviderN, type XpbdParticlePositionQueryN } from './xpbd-world.js';
import type { XpbdConservativeCurvatureApplicationN, XpbdConservativePsdBlockApplicationN, XpbdIncrementalPotentialCurvaturePolicyKindN, XpbdIncrementalPotentialCurvaturePolicyN, XpbdProviderBlockPsdCurvaturePolicyN, XpbdProviderLocalPsdCurvaturePolicyN } from './xpbd-incremental-potential-curvature-policy.js';
declare const METHOD: "analytic-provider-composition";
declare const COMPILED_METHOD: "compiled-analytic-provider-composition";
/** Candidate-direction lookup paired with a particle-identity query. */
export type XpbdParticleDirectionQueryN = (particle: XpbdParticleN) => VecN;
/** Mathematical potential Hessian-vector products in provider particle order. */
export interface XpbdConservativeHessianVectorEvaluationN {
    /** `products[i] = Hessian(U) * direction` for `particles[i]`. */
    readonly products: readonly VecN[];
}
/** Optional exact curvature capability of a conservative RN provider. */
export interface XpbdConservativeHessianVectorProviderN extends XpbdConservativeForceProviderN {
    /** Stable identity shared by force and curvature evidence. */
    readonly id: string;
    /** Ambient Euclidean dimension of every provider vector. */
    readonly dimension: number;
    /** Authored particle order shared by forces and curvature products. */
    readonly particles: readonly XpbdParticleN[];
    /** Evaluates live-state energy and forces through the base provider seam. */
    evaluate(): XpbdConservativeForceProviderEvaluationN;
    /** Evaluates candidate-state energy and forces without live-state writes. */
    evaluateAt(positionOf: XpbdParticlePositionQueryN): XpbdConservativeForceProviderEvaluationN;
    /**
     * Evaluates the mathematical potential Hessian along one candidate direction.
     *
     * The returned sign is `Hessian(U) * direction`, not the derivative of the
     * provider force `-gradient(U)`.
     */
    evaluatePotentialHessianVectorAt(positionOf: XpbdParticlePositionQueryN, directionOf: XpbdParticleDirectionQueryN): XpbdConservativeHessianVectorEvaluationN;
}
/** One exact additive block of a conservative provider Hessian. */
export interface XpbdConservativeHessianBlockN {
    /** Stable identity unique within the owning provider. */
    readonly id: string;
    /** Non-empty provider-particle subset in block product order. */
    readonly particles: readonly XpbdParticleN[];
}
/**
 * Optional exact additive decomposition of one analytic provider Hessian.
 *
 * The aggregate HVP remains authoritative. Block products must sum to it by
 * particle identity; blocks may overlap in particles.
 */
export interface XpbdConservativeHessianBlockProviderN extends XpbdConservativeHessianVectorProviderN {
    /** Deterministic authored block order. */
    readonly potentialHessianBlocks: readonly XpbdConservativeHessianBlockN[];
    /** Evaluates one exact block contribution at a candidate state. */
    evaluatePotentialHessianBlockVectorAt(block: XpbdConservativeHessianBlockN, positionOf: XpbdParticlePositionQueryN, directionOf: XpbdParticleDirectionQueryN): XpbdConservativeHessianVectorEvaluationN;
}
/** One validated provider contribution to an analytic global product. */
export interface XpbdConservativeHessianVectorProviderResultN {
    /** Analytic-capable provider that produced the local products. */
    readonly provider: XpbdConservativeHessianVectorProviderN;
    /** Defensive finite copy of the selected local product. */
    readonly evaluation: XpbdConservativeHessianVectorEvaluationN;
    /** Whether exact or explicitly projected curvature supplied the product. */
    readonly curvature: XpbdConservativeCurvatureApplicationN;
}
/** Options for analytic composition over a compiled incremental objective. */
export interface EvaluateXpbdIncrementalPotentialAnalyticHessianVectorNOptions {
    /** Compiled objective whose provider set defines analytic completeness. */
    readonly problem: XpbdIncrementalPotentialProblemN;
    /** Packed free-particle coordinates at the evaluation point. */
    readonly coordinates: ArrayLike<number>;
    /** Packed free-particle direction multiplied by the objective Hessian. */
    readonly direction: ArrayLike<number>;
    /**
     * Exact Hessians by default, or an explicit dense PSD projection boundary.
     *
     * Provider-local PSD uses one complete provider block. Provider-block PSD
     * uses exact declared blocks where available and an evidenced implicit
     * provider block otherwise. Both are auditable CPU references with cubic
     * block-local cost.
     */
    readonly curvaturePolicy?: XpbdIncrementalPotentialCurvaturePolicyN;
}
interface XpbdIncrementalPotentialAnalyticHessianVectorBaseN {
    /** Exact construction attempted by this result. */
    readonly method: typeof METHOD;
    /** Valid complete objective evidence at the unperturbed coordinates. */
    readonly base: XpbdPackedIncrementalPotentialEvaluationN;
    /** Defensive copy of the packed direction. */
    readonly direction: Float64Array;
    /** Normalized exact or explicitly projected policy used by this query. */
    readonly curvaturePolicy: XpbdIncrementalPotentialCurvaturePolicyKindN;
}
/** Complete analytic product for the compiled provider mixture. */
export interface XpbdIncrementalPotentialAnalyticHessianVectorEvaluatedN extends XpbdIncrementalPotentialAnalyticHessianVectorBaseN {
    /** Confirms that every conservative provider supplied analytic products. */
    readonly status: 'evaluated';
    /** Packed exact mass-block product before conservative curvature. */
    readonly inertialProduct: Float64Array;
    /**
     * Unscaled potential products in complete authored particle order.
     *
     * Fixed-particle entries retain reaction curvature even though they occupy
     * no packed free coordinate.
     */
    readonly potentialProducts: readonly VecN[];
    /** Packed free potential product after multiplication by `deltaTime²`. */
    readonly scaledPotentialProduct: Float64Array;
    /** Complete packed incremental-objective Hessian-vector product. */
    readonly product: Float64Array;
    /** Directional curvature `directionᵀ * product`. */
    readonly quadraticForm: number;
    /** Provider product and curvature-policy evidence in authored order. */
    readonly providers: readonly XpbdConservativeHessianVectorProviderResultN[];
}
/** Exact zero product that requires no provider curvature capability. */
export interface XpbdIncrementalPotentialAnalyticHessianVectorZeroDirectionN extends XpbdIncrementalPotentialAnalyticHessianVectorBaseN {
    /** Confirms that the packed direction is exactly zero. */
    readonly status: 'zero-direction';
    /** Exact all-zero product with the compiled packed length. */
    readonly product: Float64Array;
    /** Exact zero directional curvature. */
    readonly quadraticForm: 0;
}
/** Explicit refusal when a nonzero query has incomplete analytic coverage. */
export interface XpbdIncrementalPotentialAnalyticHessianVectorUnsupportedN extends XpbdIncrementalPotentialAnalyticHessianVectorBaseN {
    /** Distinguishes absent provider capability from arithmetic failure. */
    readonly status: 'unsupported-provider';
    /** Every incapable provider id in authored provider order. */
    readonly providerIds: readonly string[];
}
/** Evidence from exact analytic curvature composition or explicit refusal. */
export type XpbdIncrementalPotentialAnalyticHessianVectorResultN = XpbdIncrementalPotentialAnalyticHessianVectorEvaluatedN | XpbdIncrementalPotentialAnalyticHessianVectorZeroDirectionN | XpbdIncrementalPotentialAnalyticHessianVectorUnsupportedN;
/** Options for compiling one fixed-coordinate analytic Hessian operator. */
export interface CompileXpbdIncrementalPotentialAnalyticHessianOperatorNOptions {
    /** Compiled objective whose provider set defines analytic completeness. */
    readonly problem: XpbdIncrementalPotentialProblemN;
    /** Packed free-particle coordinates fixed by the returned operator. */
    readonly coordinates: ArrayLike<number>;
    /** Exact Hessians by default, or an explicit dense PSD block policy. */
    readonly curvaturePolicy?: XpbdIncrementalPotentialCurvaturePolicyN;
}
/**
 * Fixed provider-curvature construction retained by a compiled operator.
 *
 * `constructionOperatorEvaluations` are paid once. The per-product count is
 * zero for stored provider-local matrices, one for exact matrix-free products,
 * and one for the authoritative audit of a stored provider-block sum.
 */
export interface XpbdConservativeCurvatureOperatorProviderN {
    /** Analytic provider whose fixed-coordinate curvature was compiled. */
    readonly provider: XpbdConservativeHessianVectorProviderN;
    /** Normalized curvature construction selected for this provider. */
    readonly kind: XpbdIncrementalPotentialCurvaturePolicyKindN;
    /** Exact structural boundary of the compiled provider operator. */
    readonly decomposition: 'exact-matrix-free' | 'provider' | 'declared' | 'implicit-provider';
    /** Provider or block basis HVPs paid once during compilation. */
    readonly constructionOperatorEvaluations: number;
    /** Aggregate provider HVPs required by each nonzero application. */
    readonly applicationOperatorEvaluationsPerNonzeroProduct: number;
    /** Source-ordered projected-block spectra; empty in exact mode. */
    readonly blocks: readonly XpbdConservativePsdBlockApplicationN[];
}
interface XpbdIncrementalPotentialAnalyticHessianOperatorCompilationBaseN {
    /** Fixed-coordinate construction attempted by this result. */
    readonly method: typeof COMPILED_METHOD;
    /** Valid complete objective evidence at the fixed coordinate. */
    readonly base: XpbdPackedIncrementalPotentialEvaluationN;
    /** Defensive packed coordinate copy retained by the operator. */
    readonly coordinates: Float64Array;
    /** Normalized exact or explicitly projected curvature policy. */
    readonly curvaturePolicy: XpbdIncrementalPotentialCurvaturePolicyKindN;
}
/** Reusable analytic objective Hessian at one fixed candidate coordinate. */
export interface XpbdIncrementalPotentialAnalyticHessianOperatorN extends XpbdIncrementalPotentialAnalyticHessianOperatorCompilationBaseN {
    /** Confirms complete analytic coverage and successful construction. */
    readonly status: 'compiled';
    /** Provider basis HVPs paid once to construct projected curvature. */
    readonly constructionOperatorEvaluations: number;
    /** Provider HVPs paid for every nonzero complete packed product. */
    readonly applicationOperatorEvaluationsPerNonzeroProduct: number;
    /** Fixed provider constructions in authored provider order. */
    readonly providers: readonly XpbdConservativeCurvatureOperatorProviderN[];
    /**
     * Applies the fixed operator without changing its coordinate or live state.
     */
    apply(direction: ArrayLike<number>): XpbdIncrementalPotentialAnalyticHessianVectorEvaluatedN | XpbdIncrementalPotentialAnalyticHessianVectorZeroDirectionN;
}
/** Typed compilation refusal for an incomplete analytic provider mixture. */
export interface XpbdIncrementalPotentialAnalyticHessianOperatorUnsupportedN extends XpbdIncrementalPotentialAnalyticHessianOperatorCompilationBaseN {
    /** Distinguishes absent provider capability from construction failure. */
    readonly status: 'unsupported-provider';
    /** Every incapable provider id in authored provider order. */
    readonly providerIds: readonly string[];
}
/** Fixed-coordinate analytic operator or explicit capability refusal. */
export type XpbdIncrementalPotentialAnalyticHessianOperatorCompilationN = XpbdIncrementalPotentialAnalyticHessianOperatorN | XpbdIncrementalPotentialAnalyticHessianOperatorUnsupportedN;
/**
 * Compiles the analytic objective Hessian at one fixed candidate coordinate.
 *
 * Exact curvature remains matrix-free. Explicit PSD policies reconstruct and
 * diagonalize their dense provider or provider-authored blocks once; repeated
 * `apply()` calls then reuse those matrices. Provider-block products retain
 * one aggregate HVP audit per nonzero direction.
 *
 * @example
 * Compile once at a fixed coordinate, then ask several directional questions:
 * ```ts
 * const particle = new XpbdParticleN({
 *   id: 'p',
 *   position: new VecN([0.2, -0.1]),
 *   inverseMass: 0.5
 * });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 2,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0])],
 *   deltaTime: 1 / 60,
 *   providers: []
 * });
 * const operator =
 *   compileXpbdIncrementalPotentialAnalyticHessianOperatorN({
 *     problem,
 *     coordinates: [0.2, -0.1]
 *   });
 *
 * if (operator.status === 'compiled') {
 *   const xProduct = operator.apply([1, 0]);
 *   if (xProduct.status === 'evaluated') {
 *     xProduct.potentialProducts[0]?.data.length; // 2, authored particle order
 *   }
 *   operator.apply([0, 1]).status; // 'evaluated', same fixed operator
 * }
 * ```
 */
export declare function compileXpbdIncrementalPotentialAnalyticHessianOperatorN(options: CompileXpbdIncrementalPotentialAnalyticHessianOperatorNOptions): XpbdIncrementalPotentialAnalyticHessianOperatorCompilationN;
/** @internal Reuses an already validated base evaluation inside the solver. */
export declare function compileXpbdIncrementalPotentialAnalyticHessianOperatorFromBaseN(options: {
    readonly problem: XpbdIncrementalPotentialProblemN;
    readonly coordinates: Float64Array;
    readonly base: XpbdPackedIncrementalPotentialEvaluationN;
    readonly curvaturePolicy?: XpbdIncrementalPotentialCurvaturePolicyN;
    readonly caller: string;
}): XpbdIncrementalPotentialAnalyticHessianOperatorCompilationN;
/**
 * Composes an analytic incremental-potential Hessian-vector product.
 *
 * The inertial contribution is the exact diagonal mass block. Conservative
 * products are assembled by particle identity and scaled by `deltaTime²`.
 * A nonzero query is evaluated only when every provider implements
 * `XpbdConservativeHessianVectorProviderN`; otherwise all missing provider ids
 * are returned before any partial analytic product is requested.
 *
 * Exact curvature is the default and neither modifies definiteness nor
 * constructs a matrix. Explicit PSD policies reconstruct either one complete
 * provider matrix or provider-declared additive blocks, audit them, and clamp
 * negative eigenvalues to zero. These are auditable CPU modified-Newton
 * references, not sparse production paths.
 *
 * Invalid base states, malformed provider evidence, ordinary provider
 * failures, asymmetric claimed Hessians, and Float64 overflow remain errors.
 *
 * `estimateXpbdIncrementalPotentialHessianVectorN` computes the same product
 * by differencing the gradient, and is the oracle this path is checked
 * against: it needs no provider capability and so is always available, while
 * this one is exact but only when every provider can answer.
 *
 * @example
 * The same product, both ways. The analytic composition and the centered
 * difference agree to differencing accuracy, which is what makes either
 * usable as a check on the other:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const barrier = new XpbdParticleHyperplaneBarrierN({
 *   id: 'floor',
 *   particle,
 *   plane: new HyperplaneColliderN(new VecN([0, 1, 0]), 0),
 *   activationDistance: 0.5,
 *   stiffness: 1
 * });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.3, 0])],
 *   deltaTime: 1 / 60,
 *   providers: [barrier]
 * });
 * const coordinates = [0, 0.3, 0];
 * const direction = [0, 1, 0];
 *
 * const exact = evaluateXpbdIncrementalPotentialAnalyticHessianVectorN({
 *   problem, coordinates, direction
 * });
 * const oracle = estimateXpbdIncrementalPotentialHessianVectorN({
 *   problem, coordinates, direction
 * });
 *
 * exact.method; // 'analytic-provider-composition'
 * oracle.method; // 'centered-gradient-difference'
 * // vᵀHv: 1.0011479895440676 against 1.0011479895405937 — 3.5e-12 apart
 * ```
 *
 * @example
 * The evidence separates where the curvature came from. At a sixtieth of a
 * second the mass block dominates, and the barrier enters scaled by
 * `deltaTime²` — which is why the total sits just above one rather than
 * being of the barrier's own magnitude:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const barrier = new XpbdParticleHyperplaneBarrierN({
 *   id: 'floor',
 *   particle,
 *   plane: new HyperplaneColliderN(new VecN([0, 1, 0]), 0),
 *   activationDistance: 0.5,
 *   stiffness: 1
 * });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.3, 0])],
 *   deltaTime: 1 / 60,
 *   providers: [barrier]
 * });
 *
 * const result = evaluateXpbdIncrementalPotentialAnalyticHessianVectorN({
 *   problem, coordinates: [0, 0.3, 0], direction: [0, 1, 0]
 * });
 *
 * if (result.status === 'evaluated') {
 *   Array.from(result.inertialProduct); // [0, 1, 0] — the exact mass block
 *   Array.from(result.scaledPotentialProduct); // [0, 1.14799e-3, 0]
 *   Array.from(result.product); // their sum, to the last bit
 * }
 * ```
 */
export declare function evaluateXpbdIncrementalPotentialAnalyticHessianVectorN(options: EvaluateXpbdIncrementalPotentialAnalyticHessianVectorNOptions): XpbdIncrementalPotentialAnalyticHessianVectorResultN;
interface NormalizedExactCurvaturePolicyN {
    readonly kind: 'exact';
}
type NormalizedProviderLocalPsdCurvaturePolicyN = Required<XpbdProviderLocalPsdCurvaturePolicyN>;
type NormalizedProviderBlockPsdCurvaturePolicyN = Required<XpbdProviderBlockPsdCurvaturePolicyN>;
type NormalizedXpbdIncrementalPotentialCurvaturePolicyN = NormalizedExactCurvaturePolicyN | NormalizedProviderLocalPsdCurvaturePolicyN | NormalizedProviderBlockPsdCurvaturePolicyN;
export declare function normalizeXpbdIncrementalPotentialCurvaturePolicyN(policy: XpbdIncrementalPotentialCurvaturePolicyN | undefined, caller: string): NormalizedXpbdIncrementalPotentialCurvaturePolicyN;
export {};
//# sourceMappingURL=xpbd-incremental-potential-analytic-curvature.d.ts.map