QF Solver 0.2.5a0 failure-mode plan

Required failure contract

Every failure returns or raises a structured reason consistent with the public API, sets converged=false, records the increment/iteration and diagnostics, rolls back unaccepted material/contact state, and never exposes a partial result as accepted equilibrium.

Failure ID	Trigger	Expected classification	State assertion	Gate
FM-01	Newton iteration limit	MAX_ITERATIONS	committed state unchanged	G09
FM-02	repeated cutback reaches minimum	MIN_INCREMENT_REACHED	last accepted increment retained	G09
FM-03	backend solve error	LINEAR_SOLVER_FAILURE	current trial rejected	G09
FM-04	singular/ill-conditioned tangent	SINGULAR_TANGENT	current trial rejected	G09
FM-05	NaN in residual/tangent/state	NAN_DETECTED	no NaN committed	G09
FM-06	Inf in residual/tangent/state/correction	INF_DETECTED	no Inf committed	G09
FM-07	constitutive return-map failure	MATERIAL_UPDATE_FAILURE	all integration-point trials rolled back	G09
FM-08	inverted/degenerate element	INVALID_ELEMENT	no assembly accepted	G02/G09
FM-09	transaction mismatch/corruption	STATE_CORRUPTION	fail closed	G09
FM-10	line-search exhaustion	LINE_SEARCH_FAILURE	pre-attempt state restored	G09
FM-11	excessive/unresolved penetration	CONTACT_PENETRATION_EXCESSIVE when contact_max_penetration is configured	contact/material state restored	G05/G09
FM-12	contact projection/search failure	contact-specific structured reason	active state restored	G05/G09
FM-13	arc-length constraint divergence	continuation-specific reason	load factor/state restored	G04/G09
FM-14	wrong/ambiguous branch direction	continuation-specific reason or explicit stop	no hidden branch switch	G04/G09
FM-15	checkpoint mismatch/corruption	checkpoint validation reason	in-memory accepted state unchanged	G09

Adversarial construction rules

• Failures must be generated by controlled options, inputs or injected backend doubles; do not rely on random instability.
• At least one case must fail after multiple successful trial updates to exercise true rollback depth.
• Retry cases compare final displacement, reactions and all state variables with a direct small-step reference.
• Tests inspect structured data, not console text alone.
• Contact/arc-length failures are added to the common taxonomy rather than creating incompatible result conventions.

Current internal evidence

The controlled campaign at results/vnv_0_2_5/g09_latest/ exercises the full Newton failure set, NaN/Inf correction payloads, an injected contact assembly failure with cutback/rollback, sparse backend failure, an arc-length step-cap failure classified as ARC_LENGTH_FAILURE, and an unbracketed sparse buckling path classified as BUCKLING_FAILURE. The final-SHA manifest records 22/22 passing cases with converged=false for every intentional failure and dirty=false. This closes 025-G09 only; it does not close the functional contact, continuation or buckling gates.

It also injects a failure at adaptive step 2 after step 1 has converged. The campaign records the committed prefix [0.5], the cutback 0.5 -> 0.25, the retry path [0.5, 0.75, 1.0] and the final converged state. This is VV-051 internal evidence; it does not replace contact/path-dependent multi-step failures or the full regression gate.

The campaign also contains a non-injected VV-068 contact guard case. A regular multi-element TET4 block is solved with a bounded contact_max_penetration; two transient Newton trials exceed the guard and are classified as CONTACT_PENETRATION_EXCESSIVE, then cut back to factors [0.5, 0.75, 1.0]. The final displacement, reaction norm and contact gap agree with a reference run using eight fixed small increments. This remains an internal frictionless penalty contract, not a general contact qualification or closure of G05/G09.

STOP condition

Any false convergence, unclassified important failure or committed-state contamination blocks the corresponding functional gate and 025-G09.