Module scale 

Format-neutral scale plan and proof contracts (DESIGN.md Appendix D).

This module owns the two distinct scale operations Appendix D defines — ScaleOperation::WholeDocumentLinearUnits and ScaleOperation::RestBindUniformScale — plus their shared pure planning, candidate construction, and proof layer. It deliberately consumes and returns only format-neutral facts: an already-loaded Document and a ScaleCapabilityFacts projection that a format frontend (for example animsmith-gltf’s raw capability preflight) builds from its own source-specific inventory. This module does not accept paths, glTF/ufbx types, config parsers, or publication policy, and it does not itself decide CLI selectors, evidence schemas, or artifact/evidence publication — those are producer concerns layered on top.

The public vocabulary and entrypoints continue to resolve through this facade. Private implementation modules own numeric leaves, validation, planning/replay, reference construction, and proof respectively; proof’s residual recorder is nested under proof so its paired maximum/count state cannot be mutated outside that implementation boundary.

ScaleOperation::RestBindUniformScale selects by raw, format-neutral source identity — source_skin_index and source_root_node_index — not by normalized crate::model::BoneId or mesh-instance ordinal. Resolving those selectors, and classifying the affected domain’s affine shape, walks crate::model::SceneAssets::source_skeleton: the only place a full (possibly sheared) authored local matrix survives, since crate::model::Bone::rest is a lossy TRS decomposition that can never look sheared even when the source was.

plan_scale is pure and fail-closed: it never mutates its input and returns a typed ScaleError for every unsupported affine domain, incomplete closure, incomplete capability, invalid selector, invalid factor. An internal reference builder constructs analytic candidates for fixtures and calibration; production format frontends instead rewrite exact source bytes and wrap the emitted reload with ScaleCandidate::from_document. prove_scale independently re-derives the plan’s claims from the source and candidate documents and reports the observed residual maxima against the fixed ScaleTolerancePolicy::APPENDIX_D_V6 tolerance identity.

Those residuals are the producer evidence record of §D.6, which is why two properties of this module are contracts rather than implementation details. Every typed ScaleProofObligation is declared only when the planned document carries the evidence for it. Candidate construction and proof re-derive that structural inventory and report a stale plan as ScaleError::PlanDocumentMismatch; a counterpart missing inside an inventory-matched walk is ScaleError::MissingProofEvidence. Neither case becomes a zero residual — a record asserting 0.0 for something nothing checked would be false, not merely incomplete. The two observed-factor fields §D.6 asks for are both recorded, together with ScaleProof::observed_factor_divergence between them, so the record states their relationship instead of leaving a consumer to guess which to trust. Rest/bind derives them independently from raw and normalized state; whole-document conversion records its declared factor in both because it has no source factor to measure.

Structs

AssemblyScaleBasis

Complete versioned semantic basis for one assembly input.

AssemblyScaleCompatibilityBasis

One assembly basis paired with core-validated selector identity.

AssemblyScaleCompatibilityError

Why two independently supplied assembly inputs do not share one basis.

AssemblyScaleNamedNode

One named normalized node and its exact authored rest basis.

AssemblyScaleSourceNode

One raw source node, including projected/helper layout.

AssemblyScaleTargetPath

One animation channel target and the plan-owned effective multiplier.

ScaleCandidate

A candidate document supplied to super::prove_scale.

ScaleCapabilityFacts

Format-neutral capability facts a frontend projects from its raw source inventory before any scale plan or candidate exists.

ScaleFieldPlan

One exact semantic field row in a compiled scale plan.

ScalePlan

Pure, typed plan returned by plan_scale.

ScalePlanLedger

Read-only view of one compiled plan’s exact domain, field, topology, and proof-obligation ledger.

ScaleProof

Observed residual maxima from prove_scale, reported against ScalePlan::tolerance_policy, each paired with the number of comparisons that produced it.

ScaleProofResidual

One proof claim’s maximum residual and the comparisons behind it.

ScaleRequest

Pure planning input: the operation, the document to plan against, and a format-neutral capability projection of the raw source.

ScaleSourceTopologyRow

One row in the canonical source-keyed rest/bind topology.

ScaleTolerancePolicy

Fixed Appendix D tolerance identity and thresholds. Classification and proof share this one versioned policy and compute in f64, narrowing only at the writer model boundary. There is exactly one supported instance, ScaleTolerancePolicy::APPENDIX_D_V6: a policy change is a new policy identity, not a runtime knob.

Enums

AssemblyScaleSelectorRequest

Selector mode requested while deriving an assembly compatibility basis.

AssemblyScaleSourceRest

Authored raw source-node rest representation retained by a basis.

ProofResidualKind

Which proof obligation produced a ScaleError::ProofResidualExceeded or ScaleError::MissingProofEvidence.

ScaleBoneRestField

One normalized bone-rest field.

ScaleCapabilityCoverage

Whether a format-neutral capability projection covers the whole source.

ScaleError

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

ScaleFieldDisposition

Whether a modeled field is preserved exactly or analytically rewritten.

ScaleFieldTarget

The exact container-level target of one field disposition.

ScaleOperation

The two distinct scale operations DESIGN.md Appendix D §D.1 defines.

ScalePayloadShapeRow

One numeric-value-free payload-shape row used by stale-plan replay.

ScaleProjectedRole

A projected source row’s role in a rest/bind topology.

ScaleProofObligation

One typed proof claim kind derived from the plan’s validated inventory.

ScaleRewriteRule

The structural semantic operation a rewritten field receives.

ScaleSourceNodeKind

The typed kind of one canonical rest/bind source-topology row.

ScaleSourceRestField

One authored source-node rest field or component group.

Constants

ASSEMBLY_SCALE_BASIS_VERSION

Stable semantic version of AssemblyScaleBasis.

Functions

assembly_scale_basis

Project an accepted rest/bind plan into the versioned assembly basis.

assembly_scale_compatibility_basis

Project one accepted plan and pair it with selector identity derived from the same document.

plan_scale

Plan the caller-selected ScaleOperation against request.document.

prove_scale

Independently re-derive and check every claim ScalePlan makes.

require_assembly_scale_compatibility

Require two bases to agree on every static semantic field.

require_assembly_scale_compatibility_with_selectors

Require two core-validated compatibility bases to agree.