Module quantity 

Quantities: an exact magnitude carrying a physical Dimension and a unit.

A quantity is a number with a unit — 2 inches, 5 kilograms, 9.8 m/s². Internally a Quantity stores its magnitude in the SI base unit for its dimension (metres, kilograms, seconds, …) as an exact Rational, so:

• addition/subtraction require the SAME dimension and just add magnitudes,
• multiplication/division combine dimensions (Length × Length = Area),
• conversion to another unit of the same dimension is exact (÷ scale, offset-aware), and
• converting across dimensions (Length → Mass) is impossible — the forbidden cast.

Because every unit’s scale to the SI base is an exact rational (1 inch = 127/5000 m exactly), the whole thing is lossless: 2 inches + 5 centimetres is 63/625 m, which in feet is exactly 42/127. A Unit may be affine (a nonzero offset, like °C/°F), so a temperature converts with scale AND offset; linear units have offset = 0.

Modules

constants

Physical constants as first-class Quantity values — each carries its dimension, so they compose with units under the same dimensional algebra (E = m·c² type-checks, and c can be asked for in kilometres_per_hour). The post-2019-SI defining constants are EXACT rationals (the SI fixes their numeric values); measured constants (G) use their CODATA value.

units

The unit catalog — every scale an EXACT rational to the SI base. Organized by dimension. (Irrational-scaled units like parsec (648000/π·AU) and mach are intentionally omitted until a float-backed quantity exists; everything here is lossless.) A later wave moves this to a growable data file; the math and the names are settled here first.

Structs

Position

A point in 3-D space, coordinates in metres (an inertial frame’s axes). Euclidean distance is transcendental (a square root), so positions are f64 — the one place the time tower leaves the exact-rational world, because the geometry of spacetime demands it.

Quantity

An exact quantity: a magnitude in the SI base unit, tagged with its dimension.

SpacetimeStamp

A space-aware timestamp — when (a SmoothUTC instant, nanoseconds) AND where (a position in space). This is the heart of the light-cone model: two events can only be causally ordered if their time separation is at least the light-travel time between their positions. Closer in time than that and they are spacelike-separated — genuinely concurrent, no signal could connect them, which is exactly where CRDTs (conflict-free, order-free merge) are the right tool.

Unit

A unit of measurement: its dimension and how to map a value in this unit to the SI base. si = value · scale + offset. Linear units have offset = 0; affine units (°C, °F) do not.

Enums

CausalRelation

How two SpacetimeStamps relate causally. Before: self is in the past light cone of the other (a signal from self could reach it). After: the reverse. Concurrent: spacelike — neither can have affected the other.

Functions

light_travel_time

The light-travel time across a distance — distance / c, exact. Returns a Time quantity, or None if distance is not a length (the dimensional guard). This is the core of “universal / space-travel time”: the delay before an event at distance d is observed elsewhere (Earth↔Sun ≈ 499 s, Earth↔Mars ≈ 3–22 min). The result rides the exact rational tower, so it never drifts.

lorentz_factor

The special-relativistic Lorentz factor γ = 1/√(1 − β²) for a speed β as a fraction of c. None for |β| ≥ 1 (or NaN) — nothing reaches or exceeds light speed. Inherently a float (relativity is transcendental), unlike the exact-rational quantity arithmetic.

observed_arrival_nanos

The instant (nanoseconds since the epoch) at which an event happening at event_nanos is observed by someone a distance away — event + distance/c. The relativistic light-delay the space-travel time model is built on. None if distance is not a length or the result overflows.

proper_time_seconds

The proper time (in seconds) a clock experiences over coordinate_seconds of coordinate time while moving at speed β (fraction of c): coordinate / γ. A moving clock ticks slow — this is the space-traveller’s “time attenuation”. None for |β| ≥ 1.

time_dilation_factor

The time-dilation factor γ for a velocity given as a speed Quantity (β derived as v/c). None if velocity is not a speed or is ≥ c.

time_quantity_to_nanos

Convert a Time-dimensioned quantity to a whole number of nanoseconds (rounded to the nearest), the bridge from the exact Quantity world to the instant model. None if q is not a time, or the result does not fit i64.