import { XpbdIncrementalPotentialProblemN } from './xpbd-incremental-potential-problem.js';
import { type XpbdIncrementalPotentialDirectionEvidenceN, type XpbdIncrementalPotentialDirectionPolicyN, type XpbdIncrementalPotentialDirectionValuePolicyN } from './xpbd-incremental-potential-direction.js';
import { type XpbdIncrementalPotentialNewtonDirectionResultN, type XpbdIncrementalPotentialNewtonPreconditionerN } from './xpbd-incremental-potential-newton-direction.js';
import type { XpbdIncrementalPotentialCurvaturePolicyN } from './xpbd-incremental-potential-curvature-policy.js';
declare const KIND: "newton-cg";
/**
 * P37 outcomes an authored first-order fallback may be attached to.
 *
 * Armijo's `'not-descent'` verdict is deliberately absent: the policy never
 * sees it, and a Newton direction that fails sufficient decrease surfaces as
 * the minimizer's existing `stalled/not-descent` terminal with this policy's
 * evidence attached, rather than as a second chance at choosing a direction.
 */
export type XpbdNewtonDirectionFallbackTriggerN = 'unsupported-provider' | 'non-positive-curvature' | 'empty-iteration-limit';
/** An explicitly authored first-order policy and the outcomes it answers for. */
export interface XpbdNewtonDirectionFallbackN {
    /** Plain first-order policy; the type forbids it refusing. */
    readonly policy: XpbdIncrementalPotentialDirectionValuePolicyN;
    /** Non-empty, unique triggers this fallback is authored for. */
    readonly on: readonly XpbdNewtonDirectionFallbackTriggerN[];
}
/** Construction options for one globalized Newton direction policy. */
export interface XpbdNewtonDirectionPolicyNOptions {
    /** The same compiled problem later passed to the minimizer. */
    readonly problem: XpbdIncrementalPotentialProblemN;
    /** Forwarded to the P37 solve; default `mass-diagonal`. */
    readonly preconditioner?: XpbdIncrementalPotentialNewtonPreconditionerN;
    /** Exact provider Hessians by default, or an explicit PSD block policy. */
    readonly curvaturePolicy?: XpbdIncrementalPotentialCurvaturePolicyN;
    /** Residual tolerance relative to the initial gradient norm. */
    readonly relativeResidualTolerance?: number;
    /** Absolute packed residual tolerance. */
    readonly absoluteResidualTolerance?: number;
    /** Relative positive-curvature threshold against `||d|| ||H d||`. */
    readonly relativeCurvatureTolerance?: number;
    /** Krylov iteration budget. */
    readonly maximumIterations?: number;
    /**
     * Explicit opt-in to first-order continuation.
     *
     * Absent means the triggers above end the minimization with typed refusal
     * evidence. A fallback is never selected implicitly: continuing past a
     * refused curvature ray is a modelling decision the author makes, not a
     * convenience the policy grants itself.
     */
    readonly fallback?: XpbdNewtonDirectionFallbackN;
}
/** How one linearization point was resolved into a direction, or refused. */
export type XpbdNewtonDirectionOutcomeN = 'newton' | 'truncated-newton' | 'fallback' | 'refused';
/** Complete auditable evidence for one Newton direction attempt. */
export interface XpbdNewtonDirectionPolicyEvidenceN extends XpbdIncrementalPotentialDirectionEvidenceN {
    /** Stable discriminator for evidence produced by this policy. */
    readonly kind: typeof KIND;
    /** Complete frozen P37 result for this linearization point. */
    readonly newton: XpbdIncrementalPotentialNewtonDirectionResultN;
    /** Which construction supplied the returned direction, if any. */
    readonly outcome: XpbdNewtonDirectionOutcomeN;
    /** Identity of the engaged fallback policy, or null when none was. */
    readonly fallbackPolicyId: string | null;
}
/**
 * Composes P37's Newton-direction solve into the P33 direction-policy seam.
 *
 * This is a direction policy, not a minimizer. Step filters still certify the
 * requested segment, Armijo still owns acceptance and backtracking, and the
 * gradient norm still owns convergence. What the policy adds is the direction
 * and the evidence for it.
 *
 * The factory closes over the compiled problem because the policy context
 * deliberately carries defensive copies and no problem object — a
 * problem-aware policy cannot be written against the context alone, and
 * widening the context for one policy would hand every policy a mutable
 * handle on the objective.
 *
 * The linearization is fresh at every accepted iterate: the solve runs at the
 * coordinates it is given, never at a remembered point.
 *
 * @param options - Compiled problem, forwarded P37 tolerances, and the
 * optional authored fallback.
 * @returns An ordinary direction policy, usable anywhere `mass-diagonal` is.
 *
 * @example
 * Refusal is the default. Without an authored fallback, indefinite curvature
 * ends the minimization with the rejected ray retained rather than being
 * silently repaired:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.3, 0])],
 *   deltaTime: 1 / 60,
 *   providers: []
 * });
 *
 * const policy = xpbdNewtonDirectionPolicyN({ problem });
 * const result = minimizeXpbdIncrementalPotentialN({
 *   problem,
 *   initialCoordinates: [0, 0.3, 0],
 *   directionPolicy: policy
 * });
 *
 * policy.id; // 'newton-cg'
 * result.status; // 'direction-refused' at an indefinite linearization
 * ```
 *
 * @example
 * Continuing first-order past a refusal is authored, naming both the policy
 * and the exact outcomes it answers for:
 * ```ts
 * const particle = new XpbdParticleN({ id: 'p', position: new VecN([0, 0.3, 0]) });
 * const problem = compileXpbdIncrementalPotentialProblemN({
 *   dimension: 3,
 *   particles: [particle],
 *   predictedPositions: [new VecN([0, 0.3, 0])],
 *   deltaTime: 1 / 60,
 *   providers: []
 * });
 *
 * const policy = xpbdNewtonDirectionPolicyN({
 *   problem,
 *   fallback: {
 *     policy: xpbdMassPreconditionedDirectionN,
 *     on: ['non-positive-curvature']
 *   }
 * });
 *
 * policy.id; // 'newton-cg+fallback:mass-diagonal'
 * ```
 */
export declare function xpbdNewtonDirectionPolicyN(options: XpbdNewtonDirectionPolicyNOptions): XpbdIncrementalPotentialDirectionPolicyN;
export {};
//# sourceMappingURL=xpbd-incremental-potential-newton-policy.d.ts.map