Enum ScaleError 

#[non_exhaustive]
pub enum ScaleError {
    InvalidFactor {
        factor: f64,
    },
    InvalidExpectedFactor {
        factor: f64,
    },
    FactorNotRepresentable {
        declared: f64,
        factor: f64,
        narrowed: f32,
    },
    InvalidRootSelector {
        source_root_node_index: usize,
    },
    InvalidSkinSelector {
        source_skin_index: usize,
    },
    IncompleteCapability,
    IncompleteSourceSkeleton,
    SourceNodeNotNormalized {
        source_node_index: usize,
    },
    NonFiniteSourceTransform {
        source_node_index: usize,
    },
    NonFiniteTransform {
        node: BoneId,
    },
    InvalidParent {
        node: BoneId,
        parent: BoneId,
    },
    BoneIndexOutOfRange {
        index: usize,
    },
    PlanDocumentMismatch {
        reason: &'static str,
    },
    IncompleteClosure {
        reason: &'static str,
    },
    UnsupportedUnskinnedGeometry {
        node: BoneId,
    },
    InvalidAffineDomain {
        node: BoneId,
        reason: AffineDomainViolation,
    },
    FactorMismatch {
        expected: f64,
        observed: f64,
    },
    MixedFactor {
        expected: f64,
        observed: f64,
        node: BoneId,
    },
    ProofResidualExceeded {
        kind: ProofResidualKind,
        observed: f64,
        tolerance: f64,
    },
    ProofSamplingBudgetExceeded {
        policy_id: &'static str,
        sample_times: u64,
        per_sample_cost: u64,
        work: u64,
        budget: u64,
    },
    MissingProofEvidence {
        kind: ProofResidualKind,
        detail: &'static str,
    },
    InvalidDocumentShape(DocumentShapeError),
    MissingInverseBind {
        node: BoneId,
    },
    InvalidMeshPrimitive {
        mesh_index: usize,
        primitive_index: usize,
        reason: &'static str,
    },
    NegativeSkinWeight {
        mesh_index: usize,
        primitive_index: usize,
        vertex_index: usize,
        influence_index: usize,
    },
    InvalidSkinnedPrimitive {
        instance_index: usize,
        primitive_index: usize,
        reason: &'static str,
    },
    CandidateStructureMismatch {
        reason: &'static str,
    },
}

Typed, fail-closed rejection from plan_scale, reference candidate construction, or prove_scale.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

InvalidFactor

The whole-document conversion factor is not finite and positive.

Fields

factor: f64

The rejected factor.

InvalidExpectedFactor

The declared rest/bind expected factor is not finite and positive.

Fields

factor: f64

The rejected factor.

FactorNotRepresentable

A declared factor (or a factor derived from it, such as the rest/bind reciprocal 1 / expected_factor) is finite and positive in f64 but has no usable f32 image at the writer model boundary: it either overflows to infinity or flushes a nonzero factor to zero.

This is deliberately a distinct variant from ScaleError::InvalidFactor / ScaleError::InvalidExpectedFactor, whose message would be an outright lie here — 1e-50 is finite and positive; what it is not is representable once the model narrows to f32. Rejecting it at plan time is what stops a build from silently multiplying every translation, mesh POSITION, and inverse-bind translation by 0.0f32 and handing the annihilated document to a proof that then signs off on it, because 0 == 0 * 0 within any tolerance.

Fields

declared: f64

The declared factor the caller supplied.

factor: f64

The declared factor, or the reciprocal derived from it, that failed to narrow. Equal to declared when the declared factor itself failed.

narrowed: f32

The unusable f32 image of factor.

InvalidRootSelector

source_root_node_index is not a source node in the document’s source skeleton.

Fields

source_root_node_index: usize

The rejected source-node index.

InvalidSkinSelector

source_skin_index is not a skin in the document’s source skeleton, or the skin declares no joints.

Fields

source_skin_index: usize

The rejected source-skin index.

IncompleteCapability

The capability projection is unavailable or declares an unsupported domain.

IncompleteSourceSkeleton

document.assets.source_skeleton does not declare complete coverage.

SourceNodeNotNormalized

A selected root, selected skin joint, or terminal affected source row did not normalize to a document skeleton bone. Unprojected rows are otherwise accepted only when they are strict connectors between projected rows.

Fields

source_node_index: usize

The unnormalized source-node index.

NonFiniteSourceTransform

A raw source-node rest transform is non-finite.

Fields

source_node_index: usize

The source node with the non-finite transform.

NonFiniteTransform

A transform composed during scale planning, candidate construction, or proof is non-finite. Entry-time skeleton rest failures are reported through ScaleError::InvalidDocumentShape.

Fields

node: BoneId

The node with the non-finite transform.

InvalidParent

A runtime scale walk encountered a parent that cannot be resolved. Entry-time skeleton topology failures are reported through ScaleError::InvalidDocumentShape.

Fields

node: BoneId

The node with an invalid parent.

parent: BoneId

The invalid parent index.

BoneIndexOutOfRange

A plan or document reference a bone index outside document.skeleton.bones for the document actually supplied.

This guards every boundary where a ScalePlan built from one document could be replayed against a different one: ScalePlan has no public constructor other than plan_scale, but reference candidate construction and prove_scale each take the document to operate on as a separate argument and must not trust that it still matches the plan’s shape.

Fields

index: usize

The out-of-range index.

PlanDocumentMismatch

A plan replayed against a document derives a different write or proof inventory than it did when planned.

Plans may be reused across numerically different documents, but only while re-deriving the supplied source’s structural planning inventory selects the same complete domain. Otherwise a stale affected-node list or evidence flag could leave newly introduced payload outside every proof walk.

Fields

reason: &'static str

Stable machine-readable mismatch kind.

IncompleteClosure

The affected closure could not be completed.

Fields

reason: &'static str

Stable machine-readable reason.

UnsupportedUnskinnedGeometry

Unskinned geometry is attached inside the affected closure.

Fields

node: BoneId

The node carrying unskinned geometry.

InvalidAffineDomain

A node’s rest-world linear part is outside the supported affine class.

Fields

node: BoneId

The rejected node.

reason: AffineDomainViolation

Stable machine-readable violation kind.

FactorMismatch

The declared expected_factor does not match the source’s observed common factor.

Fields

expected: f64

Declared expected factor.

observed: f64

Observed source factor.

MixedFactor

One node’s effective factor differs from the domain’s common factor.

Fields

expected: f64

The domain’s common factor.

observed: f64

The node’s observed factor.

node: BoneId

The node with the mismatched factor.

ProofResidualExceeded

A proof residual exceeded the fixed tolerance policy.

Fields

kind: ProofResidualKind

Which proof obligation failed.

observed: f64

Observed residual.

tolerance: f64

Tolerance the residual exceeded.

ProofSamplingBudgetExceeded

The document’s sampled proof work exceeds ScaleTolerancePolicy::proof_sample_work_budget.

Raised by prove_scale before any sample time is evaluated, so a document whose key count and vertex count multiply out beyond the versioned policy’s budget is refused outright rather than proved against a silently truncated subset of its sample times. The budget is a property of the policy identity recorded in evidence, not a per-run flag.

Fields

policy_id: &'static str

The tolerance-policy identity whose budget was exceeded.

sample_times: u64

Distinct sample times the plan’s obligations would evaluate, summed over every clip.

per_sample_cost: u64

Work units one sample time costs: bone_count plus the vertex count of every skinned instance inside the affected closure.

work: u64

sample_times * per_sample_cost, saturating.

budget: u64

The policy’s ScaleTolerancePolicy::proof_sample_work_budget.

MissingProofEvidence

The plan’s typed obligation ledger declared a claim provable, but prove_scale could not find the evidence to check it (for example a clip or track present in source with no counterpart in candidate). This is a distinct failure from ScaleError::ProofResidualExceeded: the claim was never checked at all, so proof must fail rather than silently report a zero residual.

Fields

kind: ProofResidualKind

Which proof obligation was left unchecked.

detail: &'static str

Stable machine-readable reason.

InvalidDocumentShape(DocumentShapeError)

The shared model shape required by strict mutating operations is malformed. Document is publicly mutable, so planning, building, and proof validate each supplied snapshot independently.

MissingInverseBind

No inverse-bind evidence exists for a skin joint: the owning mesh instance declares an empty skin_ibms (falling back to the bone’s own crate::model::Bone::inverse_bind) and that bone also has no inverse-bind matrix. Identity is never substituted for genuinely missing evidence — only for a source skin whose complete-coverage crate::model::SourceSkinAsset::inverse_bind_accessor proves the format-defined identity default with crate::model::SourceInverseBindAccessorStatus::Absent (checked internally by this module’s private inverse-bind resolution).

Fields

node: BoneId

The joint with no inverse-bind evidence.

InvalidMeshPrimitive

A mesh primitive is malformed independently of any skin: a non-finite base POSITION.

Checked at every public entry point, on the candidate as well as the input, because base POSITION is a rewritten domain: without it a whole-document build with an overflowing factor returns a document full of non-finite vertices as Ok.

Fields

mesh_index: usize

Index into document.assets.meshes of the offending mesh.

primitive_index: usize

Index into that mesh’s primitives of the offending primitive.

reason: &'static str

Stable machine-readable reason.

NegativeSkinWeight

A primary skin-weight attribute contains a finite negative value.

Skin weights are coefficients of a convex blend, never signed affine coefficients. Refusing this at the shared scale-input boundary keeps planning, candidate construction, and proof on that one semantic domain and gives evidence consumers a stable kind without requiring them to parse a ScaleError::InvalidMeshPrimitive reason string.

Fields

mesh_index: usize

Index into document.assets.meshes.

primitive_index: usize

Index into that mesh’s primitives.

vertex_index: usize

Vertex carrying the rejected weight tuple.

influence_index: usize

Component within the primary four-influence tuple.

InvalidSkinnedPrimitive

A skinned primitive is malformed: joints/weights shorter than positions, a non-finite position or weight, a joint-influence slot outside the owning instance’s skin_joints, or a skinned result that is not finite.

The last case reports two distinct reasons. A skinned position that left the f32 range is "skinned_magnitude_overflow": the document’s geometry does not fit the arithmetic this proof runs in. A NaN is "non_finite_result": an input that survived every finiteness check above is degenerate in some other way. Both fail closed; neither is bounded by a magnitude domain, because skinning accumulates a dot product per axis and where that overflows depends on the rotation rather than on the magnitude of the result.

Fields

instance_index: usize

Index into document.assets.instances of the owning instance.

primitive_index: usize

Index into the owning mesh’s primitives of the offending primitive.

reason: &'static str

Stable machine-readable reason.

CandidateStructureMismatch

candidate’s skeleton/source-projection, clip/track/instance/mesh/ primitive structure does not match source’s, or an exact unchanged semantic value differs. This includes a changed parent or source-node projection, a changed world-rest affine outside a rest/bind closure, a missing or extra clip, track, instance, mesh, or primitive, a track whose identity, interpolation, times, or value shape disagrees with its source counterpart, or a mesh instance whose identity — the node it hangs off, the source node it came from, the mesh it draws, or the joints it binds — disagrees with its source counterpart. Proof pairs source and candidate structure by identity or index, which requires this parity to hold. For rest/bind this also covers an admitted static connector local that changed bits or a projected successor whose raw local is not the independently derived bridged rebase. An extra, missing, re-parented, relocated, or otherwise rewritten unchanged value is never silently ignored.

Fields

reason: &'static str

Stable machine-readable reason.

Trait Implementations

impl Clone for ScaleError

fn clone(&self) -> ScaleError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for ScaleError

impl Debug for ScaleError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ScaleError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ScaleError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<DocumentShapeError> for ScaleError

fn from(source: DocumentShapeError) -> Self

Converts to this type from the input type.

impl PartialEq for ScaleError

fn eq(&self, other: &ScaleError) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ScaleError