# Suspension engineering metrics and comparison qualification

New contracts: `vehiclelab.suspension-engineering.v1`,
`vehiclelab.suspension-comparison.v1`,
`vehiclelab.suspension-comparison-report.v1`.
Evidence: `vehiclelab.suspension-comparison-evidence@1.0.0`.

## Physical frame and projections

The chassis-aligned inspection frame has +X forward, +Y vehicle-left and +Z up,
at the nominal front axle design datum (generic origin at midpoint/wheel-centre
height). Entered geometry edits retain that fixed datum; points are never
automatically recentered. It is not a moving road frame. Existing physically steered Double Wishbone and MacPherson solvers
remain authoritative; passive fixed-heading Double Wishbone is not an adapter.

Let side sign s=+1 left, -1 right. The actual wheel spin axis is the solved
spindle-reference point minus wheel centre, normalized and oriented outward.
For unit outward spindle n on the transverse branch, s*n_y>0:

`camber = atan2(-n_z, s*n_y)`.

The front-view wheel plane satisfies n_y*y+n_z*z=0. Its top with positive z
therefore has outward tilt s*y/z=-s*n_z/n_y. This gives positive camber for
wheel top outward, consistently on both sides, including a steered carrier.
The Y-Z projection must be well defined; a vanishing transverse component
rejects the metric rather than supplying zero or wrapping through a singularity.
Axis reversal or changing the spindle-reference distance changes no physical angle.

For world spatial angular response omega_j, n_j=omega_j cross n. With
u=-n_z, v=s*n_y, the signed analytic derivative is
`camber_j = (v*u_j - u*v_j)/(u*u+v*v)`, in rad/m. The same expression uses
the carrier's rack angular response for camber/rack sensitivity. No finite
difference replaces the released primary derivative.

Heading/toe and their analytic derivatives map the existing physically solved
spindle outputs, with toe-in=-left heading and +right heading. Total axle toe
is their sum. Design-relative quantities use j=0,rack=0. Fixed-current-rack
bump toe uses toe(j,rho)-toe(0,rho); these baselines are explicitly distinct.

For upward unit geometric reference a, Double Wishbone uses lower-to-upper
ball joints; MacPherson uses lower ball joint to chassis top mount:

`caster_reference = atan2(-a_x,a_z)`;
`SAI_reference = atan2(-s*a_y,a_z)`.

Positive caster means upper rearward. Positive SAI means upper toward the
centreline. A horizontal reference is rejected. The line is a geometric
reference, not a complete instantaneous screw axis. Angular rack sensitivity
alone does not establish axis location or pitch; compatible translation and
an independently qualified velocity convention would be required. This
release deliberately does not extract that more ambitious quantity.

Spring/damper length, design compression and signed motion ratio come directly
from the authoritative solvers. MR=d(compression)/dj at fixed rack. The current
MacPherson coaxial constant-seat-offset installation has equal incremental
spring/damper MRs despite distinct installed lengths. Double Wishbone's separate
lower-arm mounts need not have equal MRs. Independent compression perturbations
verify fixed-rack virtual work Q_j=F_compression*MR; no new Full-Car force map exists.

The shared carrier orientation is the **design-relative rigid rotation in axle
coordinates**, not either solver's differently defined basis field. For physically
steered Double Wishbone, use the actual rigid joint-frame rotation composed with
its design transpose; the spindle-derived `carrierBasis` in that solver is a
wheel frame and is not substituted. MacPherson already supplies the rigid
rotation of design axle vectors. Both shared design matrices are identity, and
`p-W = R_delta (p_design-W_design)` holds for carrier-fixed points. Independent
spatial references and rigid-offset transformation tests qualify this mapping,
including nonzero design camber/toe. Camber derivatives use the actual rigid
carrier angular sensitivities; their spin-axis gauge does not enter the metric.

## Independent reference and numerical budgets

The metric reference imports no production metric, solver, derivative or frame
routine. It uses the earlier independent geometric pose references. Camber
comes from a separately constructed wheel-plane/front-plane intersection and
an asin inclination of its upward direction. Caster and SAI use independent
Cartesian projected lengths and asin signs. Wheel heading uses its geometric
horizontal forward vector. Known positive/negative/zero camber and caster,
inward/outward SAI, nonzero toe and combined steered spindle cases verify signs.

Eight source fixtures cover planar, generic and skew spatial forms of both
mechanisms plus independently mirrored nonzero camber/toe spindle definitions.
Each covers j=-40/0/+40 mm and rack=-15/0/+15 mm, independently on both sides:
72 axle states / 144 corners. Three fourth-order central stencils (1/0.1/0.01 mm)
verify camber/jounce, camber/rack, toe/jounce, heading/rack and both MRs.
The larger step diagnoses truncation; the smaller steps expose geometric
reference roundoff. Each recorded step is retained, with convergence checks.

New acceptance limits: position 2e-10 m; carrier basis 3e-9; angular metrics
2e-9 rad; compression 2e-10 m; angular derivatives 1e-7 rad/m; MR 1e-8.
The derivative budget corresponds to 5.7e-9 deg/mm, and accommodates reference
closure error differentiated over 10 micrometres. Budgets apply to qualified
regular fixtures, not arbitrary near-singular geometry. Production closure
remains 1e-11 m, and existing rank/tolerance policies remain unchanged.
Singular or undefined metrics are rejected, never fabricated as zero.

## Comparison and immutable evidence

A session owns two independently validated physical definitions. Both mechanisms
receive exactly the same ordered jounce values, fixed rack and frame conventions.
Grid bounds are finite, increasing and within +/-250 mm, rack within +/-100 mm,
with 3-101 samples. These are request bounds; stricter mechanism/entered rack
limits can reject individual points. No clamping or extrapolation occurs.

Every row records separate accepted/rejected mechanism evaluations and diagnostics.
Only two accepted axle results produce a paired row and signed B-A metrics.
Per-mechanism and common contiguous _sampled_ segments preserve gaps; they do not
prove a continuously reachable interval. Common-range extrema exclude rejected
points. Plots use explicit gaps, so no line bridges rejected samples.

Definitions, design values, grid, results, evidence identity, execution description,
conditioning and provenance are deeply owned and frozen. Cooperative scheduling
yields between sample batches and aborts obsolete studies. A session retains at
most four completed study snapshots; authoritative mechanism caches retain their
existing bounds. Changes invalidate the completed snapshot and block exports.

CSV uses deterministic SI column order and 17-digit numeric strings, retaining
inputs/diagnostics but empty observation cells for rejected rows. User text is
escaped and formula-leading strings are neutralized. The companion JSON manifest
owns the exact complete snapshot and both full geometry definitions.
PDF uses a separate honest kinematic-report contract and existing VehicleLab
layout/plot utilities, with searchable text, geometry, numeric summaries,
four engineering plots, rejection reasons and provenance. It does not fabricate
legacy project runs or Web Worker execution. Both exports are checked against
the same approved snapshot, including an identity check after async PDF generation.

Ideal rigid kinematics excludes compliant K&C, structural loads, measured vehicle
correlation, tire lateral forces, handling and MacPherson Full-Car dynamics.
Numerical domain boundaries are not physical stops.