Quaternion Order Guard

Catch the QUATERNION COMPONENT-ORDER MISMATCH before it rotates something the wrong way.

THE SILENT FAILURE. A quaternion is four numbers, and two conventions are in wide use that order those four numbers differently:

    scalar-last   (x, y, z, w)   -- ROS, scipy, Unity
    scalar-first  (w, x, y, z)   -- Eigen's constructor, Blender

THE SAME FOUR NUMBERS, READ IN THE WRONG ORDER, ARE STILL A VALID UNIT QUATERNION. They still normalize to length 1. They still compose. Every validity check you could write passes, because nothing about the values is invalid -- only the interpretation is. There is no exception to catch and no assertion that fires.

What you get instead is an object rotated to a plausible but wrong orientation, which reads as a calibration problem, a sign error, or a bad sensor. Teams chase it in the wrong layer for days because the numbers themselves look completely fine.

This makes the convention EXPLICIT at the boundary and converts between them, refusing rather than guessing when the source convention was never declared -- because the guess that feels safe is 'it is probably the one we use', and the whole failure exists at the seam between two libraries that each assumed that.

VERIFIED: 53 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function diagnoseOrder( values: readonly [number, number, number, number], claimedOrder: QuaternionOrder, observation: ReferenceObservation ): GuardResult<OrderDiagnosis>;
  export function angularDistance(a: OrderedQuaternion, b: OrderedQuaternion): GuardResult<number>;
  export function sameRotation( a: OrderedQuaternion, b: OrderedQuaternion, angleTolerance: number ): GuardResult<boolean>;
  export function declareOrder( values: readonly [number, number, number, number], order: QuaternionOrder ): GuardResult<OrderedQuaternion>;
  export function toComponents(q: OrderedQuaternion): GuardResult<QuaternionComponents>;
  export function fromComponents( c: QuaternionComponents, order: QuaternionOrder ): GuardResult<OrderedQuaternion>;
  export function convert( q: OrderedQuaternion, targetOrder: QuaternionOrder ): GuardResult<OrderedQuaternion>;
  export function fromAxisAngle( axis: Vec3, angleRadians: number, order: QuaternionOrder ): GuardResult<OrderedQuaternion>;
  export function rotateVector(q: OrderedQuaternion, v: Vec3): GuardResult<Vec3>;
  export function ok<T>(value: T): GuardResult<T>;
  export function fail<T>(reason: string): GuardResult<T>;
  export function isValidOrder(order: unknown): order is QuaternionOrder;

  export type ReferenceObservation = VectorObservation | AxisAngleObservation;
  export type OrderVerdict = "confirmed" | "contradicted" | "ambiguous" | "unexplained";
  export type QuaternionOrder = "xyzw" | "wxyz";
  export type Vec3 = readonly [number, number, number];
  export type GuardResult<T> = | { readonly ok: true;