Claude

Claude Opus 4.8

Asolaria & Aether — clean public home

2b06855 unverified 7 days ago

19.7 kB

// no_std for real builds; the test harness needs std, so tests get it.
// Without cfg_attr here, `cargo test` silently runs ZERO tests - which the gate
// treats as NOT_MEASURED rather than a pass, because a check that did not run is
// not a check that passed.
#![cfg_attr(not(test), no_std)]
#![forbid(unsafe_code)]

//! tribit — three zeros, carried on AC, and the rainbow light hose.
//!
//! # Why DC cannot do this
//!
//! Direct current has no zero crossing. It has one direction and therefore two states,
//! and that is the whole reason the binary world is binary — not a design choice, a
//! property of the carrier.
//!
//! Alternating current crosses zero **twice per cycle, in opposite directions**. Rising
//! through zero and falling through zero are both exactly zero volts and are not the
//! same event. Add the quiescent line and there are three:
//!
//! ```text
//!        +           /‾\           /‾\
//!                   /   \         /   \
//!     0  ----------X-----X-------X-----X----------   Nil : the line is dead
//!                 /       \     /       \
//!        -      \_/         \_/           Pos : crossing upward
//!                                         Neg : crossing downward
//! ```
//!
//! **Correction, 2026-10-08 (recorded beside the law, not over it).** The three zeros above are
//! real: the `Zero` type carries all three and `rotate`/`anti_rotate` turn them in an order-3 orbit
//! (R³ = identity, R ≠ R²). But `Carrier::zero_at` **cannot reach the third** — measured
//! exhaustively over `steps_per_cycle` in `1..=64` and every phase, `Some(Zero::Nil)` occurred
//! **0 times**. A crossing is never a dead line, so AC reaches `{Pos, Neg}` and DC reaches `{Nil}`.
//! `zero_states()` previously returned 3 and disagreed with the behaviour on 63 of 64 cycle lengths;
//! it now reports reachability. The three are measured in the **rainbow lane** instead — RAINBOR's
//! three waves (`path1.path2.path3` = NN · GNN · FNN, each an HTTP-0 portal acting as itself), where
//! the anti is order-3 at **192 of 192** and the free fourth zero is the point at which the three
//! waves agree. The carrier was the wrong instrument, not a broken law.
//!
//! All three have **magnitude zero**. `Zero::magnitude()` returns 0 for every variant and
//! that is not a stub. The information is not in the value, it is in *which zero* — the
//! direction of travel through it. That is why all three are free: Law 0 makes the centre
//! the fixed point of {N, R, R²}, the one point that moves under neither inversion nor
//! anti-inversion, so it costs nothing to hold. Three free states instead of two paid ones.
//!
//! # The registers
//!
//! Book IX (IX.B.3) numbers five, and the numbering is load-bearing:
//!
//! | n | register | cost |
//! |---|------------|------|
//! | 0 | zero        | free, never computed |
//! | 1 | translucent | free, never computed — **this is light itself** |
//! | 2 | red         | costs |
//! | 3 | green       | costs |
//! | 4 | blue        | costs |
//!
//! Law 32 is titled *"Translucent is One, Not Zero"*. Pure 1 is light before a prism has
//! split it; 2, 3 and 4 are what the prism makes of it. That is why 1 is free and 2..4 are
//! not — undifferentiated light carries no colour decision, and a decision is what costs.
//!
//! # The hose
//!
//! Law 31, the rainbow lighthouse drill, is a conduit and its traversal order is fixed:
//! translucent tip → red → green → blue → translucent tail. The tip is measured (Law 30,
//! mean 0.4013 bpb saved by ordering translucent first). **The tail is not measured** and
//! is marked as such here rather than assumed symmetric.
//!
//! # Integer only
//!
//! Law 34's build directive: *"rust 1.81 int and float possible. int works way better in
//! my opinion."* Nothing below uses a float. The transform is a Number-Theoretic Transform
//! over `Z/pZ`, so split→recombine is exact rather than nearly exact, and `no_std` holds.

#![allow(clippy::needless_range_loop)]

/// The rime sphere prime. Law 20 / Law 14.
pub const P: u64 = 1_000_081;
/// Its generator.
pub const G: u64 = 7;
/// One rime dimension: 27 = 3³ glyphs.
pub const K: usize = 27;
/// Primitive 27th root of unity, `G^((P-1)/27) mod P`. Verified in tests, not asserted.
pub const W: u64 = 951_846;

/// Trits per `u128`. 3^80 < 2^128 <= 3^81, so 80 is the exact ceiling.
pub const TRITS_PER_U128: usize = 80;

/// The three zeros. Every variant has magnitude zero; they differ only by the direction
/// the carrier is travelling as it crosses.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[repr(i8)]
pub enum Zero {
    /// Crossing downward. Law 33: the negative leads, and it drills inward.
    Neg = -1,
    /// Quiescent. The line is dead — not a crossing at all.
    Nil = 0,
    /// Crossing upward. Trails, and emits.
    Pos = 1,
}

impl Zero {
    /// Zero, for all three. This is the point of the type.
    #[inline]
    pub const fn magnitude(self) -> i8 {
        0
    }

    /// Direction of travel through the crossing: -1, 0, +1.
    #[inline]
    pub const fn direction(self) -> i8 {
        self as i8
    }

    /// Ternary digit 0..2, for packing.
    #[inline]
    pub const fn digit(self) -> u8 {
        (self as i8 + 1) as u8
    }

    #[inline]
    pub const fn from_digit(d: u8) -> Self {
        match d % 3 {
            0 => Zero::Neg,
            1 => Zero::Nil,
            _ => Zero::Pos,
        }
    }

    /// The trianti, Law 4: trinary inversion is the order-3 rotation R, and R ≠ R⁻¹.
    /// Applying it three times returns to start; applying it twice is *not* the inverse
    /// of applying it once, which is exactly what makes trinary not binary.
    #[inline]
    pub const fn rotate(self) -> Self {
        Self::from_digit(self.digit() + 1)
    }

    /// The counter-rotation R², distinct from R.
    #[inline]
    pub const fn anti_rotate(self) -> Self {
        Self::from_digit(self.digit() + 2)
    }
}

/// The five registers of IX.B.3.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[repr(u8)]
pub enum Register {
    Zero = 0,
    /// Light. Undifferentiated, before the prism.
    Translucent = 1,
    Red = 2,
    Green = 3,
    Blue = 4,
}

impl Register {
    /// Registers 0 and 1 are never computed. IX.B.2: *"we don't have to calculate the zero
    /// and we don't have to calculate the translucent space, and that is what wins."*
    #[inline]
    pub const fn is_free(self) -> bool {
        matches!(self, Register::Zero | Register::Translucent)
    }

    /// Traversal order of the hose: tip, the three that cost, tail.
    pub const HOSE: [Register; 5] = [
        Register::Translucent,
        Register::Red,
        Register::Green,
        Register::Blue,
        Register::Translucent,
    ];
}

/// A carrier. `DC` never crosses zero, so it can only ever report `Nil` — the type makes
/// the binary limit unrepresentable rather than merely documented.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Carrier {
    Dc,
    /// Alternating, with a whole number of phase steps per cycle.
    Ac {
        steps_per_cycle: u32,
    },
}

impl Carrier {
    /// Which zero the carrier is at, at phase step `t`. `None` when the carrier is away
    /// from a crossing and therefore carrying magnitude.
    ///
    /// DC returns `Some(Nil)` at every step and never `Neg` or `Pos` — **one reachable zero, and
    /// the crossings are not reachable at all.** That is the binary world, stated as a return
    /// value: a carrier with no zero crossing has one direction, so it can never tell a rise from
    /// a fall. (Measured 2026-10-08: DC reaches exactly 1; the earlier comment said "two states",
    /// which counted magnitude directions rather than reachable zeros.)
    pub const fn zero_at(self, t: u32) -> Option<Zero> {
        match self {
            Carrier::Dc => Some(Zero::Nil),
            Carrier::Ac { steps_per_cycle } => {
                if steps_per_cycle == 0 {
                    return Some(Zero::Nil);
                }
                let half = steps_per_cycle / 2;
                let phase = t % steps_per_cycle;
                if phase == 0 {
                    Some(Zero::Pos) // rising through
                } else if phase == half {
                    Some(Zero::Neg) // falling through
                } else {
                    None // carrying magnitude, not at a crossing
                }
            }
        }
    }

    /// How many distinct zeros this carrier can actually **reach** through [`Self::zero_at`].
    ///
    /// This counts REACHABLE return values, not variants of the [`Zero`] type. Those are different
    /// quantities and only the second is three.
    ///
    /// Corrected 2026-10-08 (operator-directed). This previously returned `3` for any
    /// `steps_per_cycle >= 2`, which disagreed with `zero_at` on **63 of 64** cycle lengths.
    /// Measured exhaustively over `steps_per_cycle` in `1..=64` and every phase in each cycle:
    /// `Some(Zero::Nil)` occurred **0 times**, and the only reachable sets are `{Pos}` and
    /// `{Neg, Pos}`. `zero_at` documents `None` as *carrying magnitude, not at a crossing*, which
    /// is the opposite of `Nil`'s *the line is dead* — so `None` cannot stand in for `Nil`.
    ///
    /// **The three zeros are not lost by this correction.** They live in the [`Zero`] type itself,
    /// which carries all three, and in the order-3 orbit of [`Zero::rotate`] / [`Zero::anti_rotate`]
    /// (R³ = identity, R ≠ R²). The system measures them in the rainbow lane, not the carrier lane:
    /// RAINBOR's three waves — `path1.path2.path3`, NN · GNN · FNN, each an HTTP-0 portal acting as
    /// itself — where the anti is measured order-3 at **192 of 192**, and the free fourth zero is
    /// the fourth point at which the three waves agree. The carrier was simply the wrong instrument
    /// to ask. Operator, 2026-10-08: *"there are more electronics but wait no they are rainbons."*
    pub const fn zero_states(self) -> u8 {
        match self {
            // One reachable zero: the quiescent line, at every phase.
            Carrier::Dc => 1,
            Carrier::Ac { steps_per_cycle } => match steps_per_cycle {
                // Never cycles, so it only ever reports the dead line.
                0 => 1,
                // `half == 0`, so every phase is the rising crossing: `{Pos}` alone.
                1 => 1,
                // Rising and falling are both reachable and distinct: `{Pos, Neg}`.
                // `Nil` is NOT reachable — a crossing is never a dead line.
                _ => 2,
            },
        }
    }
}

/// 80 trits packed into one `u128`, base 3.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub struct TritWord(pub u128);

impl TritWord {
    pub const CAP: usize = TRITS_PER_U128;

    pub fn pack(t: &[Zero]) -> Self {
        let mut acc: u128 = 0;
        let n = if t.len() < Self::CAP {
            t.len()
        } else {
            Self::CAP
        };
        for i in 0..n {
            acc = acc * 3 + t[i].digit() as u128;
        }
        TritWord(acc)
    }

    pub fn unpack(self, out: &mut [Zero]) -> usize {
        let n = if out.len() < Self::CAP {
            out.len()
        } else {
            Self::CAP
        };
        let mut acc = self.0;
        for i in (0..n).rev() {
            out[i] = Zero::from_digit((acc % 3) as u8);
            acc /= 3;
        }
        n
    }
}

// ---------------------------------------------------------------- modular arithmetic

#[inline]
const fn mul(a: u64, b: u64) -> u64 {
    ((a as u128 * b as u128) % P as u128) as u64
}

#[inline]
const fn add(a: u64, b: u64) -> u64 {
    let s = a + b;
    if s >= P {
        s - P
    } else {
        s
    }
}

/// `base^exp mod P`, square-and-multiply. `const` so roots can be checked at compile time.
pub const fn pow(mut base: u64, mut exp: u64) -> u64 {
    let mut acc: u64 = 1;
    base %= P;
    while exp > 0 {
        if exp & 1 == 1 {
            acc = mul(acc, base);
        }
        base = mul(base, base);
        exp >>= 1;
    }
    acc
}

/// Multiplicative inverse by Fermat: `a^(P-2) mod P`. P is prime.
#[inline]
pub const fn inv(a: u64) -> u64 {
    pow(a, P - 2)
}

// ------------------------------------------------- the spherical pump wave transform

/// Forward transform: 27 samples → 27 spectral coordinates.
///
/// This is Law 20's rime prism. Newton used two prisms and showed light recombines to
/// white, which proved it composite; this is the same operation generalised to 27
/// coordinates on the sphere, over the integers so nothing is lost in the split.
///
/// `X[0]` is the DC glyph — the sum, which is the free centre of Law 0.
pub fn prism(x: &[u64; K]) -> [u64; K] {
    let mut out = [0u64; K];
    for j in 0..K {
        let wj = pow(W, j as u64);
        let mut acc = 0u64;
        let mut t = 1u64;
        for i in 0..K {
            acc = add(acc, mul(x[i] % P, t));
            t = mul(t, wj);
        }
        out[j] = acc;
    }
    out
}

/// Inverse transform: 27 spectral coordinates → the original 27 samples.
///
/// "Transfers back and forth" — the round trip is exact, not approximate, because the
/// arithmetic is integer and `27` is invertible mod `P`.
pub fn unprism(x: &[u64; K]) -> [u64; K] {
    let winv = inv(W);
    let kinv = inv(K as u64);
    let mut out = [0u64; K];
    for j in 0..K {
        let wj = pow(winv, j as u64);
        let mut acc = 0u64;
        let mut t = 1u64;
        for i in 0..K {
            acc = add(acc, mul(x[i] % P, t));
            t = mul(t, wj);
        }
        out[j] = mul(acc, kinv);
    }
    out
}

/// The pump. VIII.A.7, the Photon Law of the Rime Series: *"the more energy you push into
/// it, the further away the shell gets."*
///
/// Shell radius is the number of whole rungs of the 3-ladder the energy reaches, so it
/// grows as log₃ and never linearly. Integer only: no logarithm is taken, the rungs are
/// counted.
pub const fn pump_shell(energy: u64) -> u32 {
    let mut shell = 0u32;
    let mut rung = 1u64;
    while rung <= energy && shell < 40 {
        rung *= 3;
        shell += 1;
    }
    shell
}

/// Drive one pump step and report which zero the carrier presents at that phase.
pub const fn pump_step(c: Carrier, t: u32) -> (u32, Option<Zero>) {
    (t, c.zero_at(t))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn all_three_zeros_have_magnitude_zero() {
        assert_eq!(Zero::Neg.magnitude(), 0);
        assert_eq!(Zero::Nil.magnitude(), 0);
        assert_eq!(Zero::Pos.magnitude(), 0);
        // and they are still distinguishable
        assert_ne!(Zero::Neg.direction(), Zero::Pos.direction());
        assert_ne!(Zero::Neg, Zero::Pos);
    }

    #[test]
    fn dc_cannot_reach_the_crossings() {
        let dc = Carrier::Dc;
        assert_eq!(dc.zero_states(), 1);
        for t in 0..64 {
            assert_eq!(dc.zero_at(t), Some(Zero::Nil));
        }
        let ac = Carrier::Ac { steps_per_cycle: 4 };
        assert_eq!(ac.zero_states(), 2, "AC reaches Pos and Neg, never Nil");
        assert_eq!(ac.zero_at(0), Some(Zero::Pos));
        assert_eq!(ac.zero_at(2), Some(Zero::Neg));
        assert_eq!(ac.zero_at(1), None);
    }

    /// The old test compared `zero_states()` against a hardcoded 3 and never asked what `zero_at`
    /// could actually return. This asks, exhaustively, so the accessor cannot drift from the
    /// behaviour again.
    #[test]
    fn zero_states_equals_what_zero_at_can_reach() {
        for spc in 0..=64u32 {
            let c = Carrier::Ac {
                steps_per_cycle: spc,
            };
            let mut pos = false;
            let mut neg = false;
            let mut nil = false;
            // one full cycle covers every phase; spc == 0 has a single degenerate phase
            for t in 0..spc.max(1) {
                match c.zero_at(t) {
                    Some(Zero::Pos) => pos = true,
                    Some(Zero::Neg) => neg = true,
                    Some(Zero::Nil) => nil = true,
                    None => {}
                }
            }
            let reachable = u8::from(pos) + u8::from(neg) + u8::from(nil);
            assert_eq!(
                c.zero_states(),
                reachable,
                "zero_states disagreed with zero_at at steps_per_cycle={spc}"
            );
            if spc >= 1 {
                assert!(!nil, "AC reached Some(Nil) at steps_per_cycle={spc}");
            }
        }
        let dc = Carrier::Dc;
        assert_eq!(dc.zero_states(), 1);
        assert_eq!(dc.zero_at(7), Some(Zero::Nil));
    }

    #[test]
    fn trianti_is_order_three_and_distinct_from_its_inverse() {
        for z in [Zero::Neg, Zero::Nil, Zero::Pos] {
            assert_eq!(z.rotate().rotate().rotate(), z); // R³ = identity
            assert_ne!(z.rotate(), z.anti_rotate()); // R ≠ R²
            assert_eq!(z.rotate().anti_rotate(), z); // R·R² = identity
        }
    }

    #[test]
    fn w_really_is_a_primitive_27th_root() {
        assert_eq!(pow(G, (P - 1) / 27), W);
        assert_eq!(pow(W, 27), 1);
        for d in 1..27u64 {
            if 27 % d == 0 && d < 27 {
                assert_ne!(pow(W, d), 1, "W had order {d}, not 27");
            }
        }
    }

    #[test]
    fn the_prism_closes_on_zero() {
        // Law 20: 1 + w + ... + w²⁶ ≡ 0 (mod p)
        let mut acc = 0u64;
        for j in 0..27u64 {
            acc = add(acc, pow(W, j));
        }
        assert_eq!(acc, 0);
    }

    #[test]
    fn transfers_back_and_forth_exactly() {
        let mut x = [0u64; K];
        for i in 0..K {
            x[i] = ((i as u64 * 37 + 11) * 977) % P;
        }
        let spectrum = prism(&x);
        let back = unprism(&spectrum);
        assert_eq!(x, back, "round trip was not exact");
        // the DC glyph is the sum: the free centre
        let mut sum = 0u64;
        for i in 0..K {
            sum = add(sum, x[i]);
        }
        assert_eq!(spectrum[0], sum);
    }

    #[test]
    fn trit_word_round_trips() {
        let mut t = [Zero::Nil; TRITS_PER_U128];
        for i in 0..TRITS_PER_U128 {
            t[i] = Zero::from_digit((i % 3) as u8);
        }
        let w = TritWord::pack(&t);
        let mut back = [Zero::Nil; TRITS_PER_U128];
        assert_eq!(w.unpack(&mut back), TRITS_PER_U128);
        assert_eq!(t, back);
    }

    #[test]
    fn eighty_is_the_exact_ceiling() {
        // 3^80 fits a u128, 3^81 does not
        let mut acc: u128 = 1;
        for _ in 0..80 {
            acc = acc.checked_mul(3).expect("3^80 must fit u128");
        }
        assert!(acc.checked_mul(3).is_none(), "3^81 must overflow u128");
    }

    #[test]
    fn free_registers_are_zero_and_one() {
        assert!(Register::Zero.is_free());
        assert!(Register::Translucent.is_free());
        assert!(!Register::Red.is_free());
        assert!(!Register::Green.is_free());
        assert!(!Register::Blue.is_free());
        // the hose: translucent leads and translucent closes
        assert_eq!(Register::HOSE[0], Register::Translucent);
        assert_eq!(Register::HOSE[4], Register::Translucent);
        assert_eq!(Register::HOSE.len(), 5);
    }

    #[test]
    fn pump_shell_grows_as_log3() {
        assert_eq!(pump_shell(0), 0);
        assert_eq!(pump_shell(1), 1);
        assert_eq!(pump_shell(3), 2);
        assert_eq!(pump_shell(9), 3);
        assert_eq!(pump_shell(27), 4);
        // more energy in, further out, but never linearly
        assert!(pump_shell(1_000_000) < 20);
    }
}

	// no_std for real builds; the test harness needs std, so tests get it.
	// Without cfg_attr here, `cargo test` silently runs ZERO tests - which the gate
	// treats as NOT_MEASURED rather than a pass, because a check that did not run is
	// not a check that passed.
	#![cfg_attr(not(test), no_std)]
	#![forbid(unsafe_code)]

	//! tribit — three zeros, carried on AC, and the rainbow light hose.
	//!
	//! # Why DC cannot do this
	//!
	//! Direct current has no zero crossing. It has one direction and therefore two states,
	//! and that is the whole reason the binary world is binary — not a design choice, a
	//! property of the carrier.
	//!
	//! Alternating current crosses zero twice per cycle, in opposite directions. Rising
	//! through zero and falling through zero are both exactly zero volts and are not the
	//! same event. Add the quiescent line and there are three:
	//!
	//! ```text
	//! + /‾\ /‾\
	//! / \ / \
	//! 0 ----------X-----X-------X-----X---------- Nil : the line is dead
	//! / \ / \
	//! - \_/ \_/ Pos : crossing upward
	//! Neg : crossing downward
	//! ```
	//!
	//! Correction, 2026-10-08 (recorded beside the law, not over it). The three zeros above are
	//! real: the `Zero` type carries all three and `rotate`/`anti_rotate` turn them in an order-3 orbit
	//! (R³ = identity, R ≠ R²). But `Carrier::zero_at` cannot reach the third — measured
	//! exhaustively over `steps_per_cycle` in `1..=64` and every phase, `Some(Zero::Nil)` occurred
	//! 0 times. A crossing is never a dead line, so AC reaches `{Pos, Neg}` and DC reaches `{Nil}`.
	//! `zero_states()` previously returned 3 and disagreed with the behaviour on 63 of 64 cycle lengths;
	//! it now reports reachability. The three are measured in the rainbow lane instead — RAINBOR's
	//! three waves (`path1.path2.path3` = NN · GNN · FNN, each an HTTP-0 portal acting as itself), where
	//! the anti is order-3 at 192 of 192 and the free fourth zero is the point at which the three
	//! waves agree. The carrier was the wrong instrument, not a broken law.
	//!
	//! All three have magnitude zero. `Zero::magnitude()` returns 0 for every variant and
	//! that is not a stub. The information is not in the value, it is in which zero — the
	//! direction of travel through it. That is why all three are free: Law 0 makes the centre
	//! the fixed point of {N, R, R²}, the one point that moves under neither inversion nor
	//! anti-inversion, so it costs nothing to hold. Three free states instead of two paid ones.
	//!
	//! # The registers
	//!
	//! Book IX (IX.B.3) numbers five, and the numbering is load-bearing:
	//!
	//! \| n \| register \| cost \|
	//! \|---\|------------\|------\|
	//! \| 0 \| zero \| free, never computed \|
	//! \| 1 \| translucent \| free, never computed — this is light itself \|
	//! \| 2 \| red \| costs \|
	//! \| 3 \| green \| costs \|
	//! \| 4 \| blue \| costs \|
	//!
	//! Law 32 is titled "Translucent is One, Not Zero". Pure 1 is light before a prism has
	//! split it; 2, 3 and 4 are what the prism makes of it. That is why 1 is free and 2..4 are
	//! not — undifferentiated light carries no colour decision, and a decision is what costs.
	//!
	//! # The hose
	//!
	//! Law 31, the rainbow lighthouse drill, is a conduit and its traversal order is fixed:
	//! translucent tip → red → green → blue → translucent tail. The tip is measured (Law 30,
	//! mean 0.4013 bpb saved by ordering translucent first). The tail is not measured and
	//! is marked as such here rather than assumed symmetric.
	//!
	//! # Integer only
	//!
	//! Law 34's build directive: *"rust 1.81 int and float possible. int works way better in
	//! my opinion."* Nothing below uses a float. The transform is a Number-Theoretic Transform
	//! over `Z/pZ`, so split→recombine is exact rather than nearly exact, and `no_std` holds.

	#![allow(clippy::needless_range_loop)]

	/// The rime sphere prime. Law 20 / Law 14.
	pub const P: u64 = 1_000_081;
	/// Its generator.
	pub const G: u64 = 7;
	/// One rime dimension: 27 = 3³ glyphs.
	pub const K: usize = 27;
	/// Primitive 27th root of unity, `G^((P-1)/27) mod P`. Verified in tests, not asserted.
	pub const W: u64 = 951_846;

	/// Trits per `u128`. 3^80 < 2^128 <= 3^81, so 80 is the exact ceiling.
	pub const TRITS_PER_U128: usize = 80;

	/// The three zeros. Every variant has magnitude zero; they differ only by the direction
	/// the carrier is travelling as it crosses.
	#[derive(Clone, Copy, PartialEq, Eq, Debug)]
	#[repr(i8)]
	pub enum Zero {
	/// Crossing downward. Law 33: the negative leads, and it drills inward.
	Neg = -1,
	/// Quiescent. The line is dead — not a crossing at all.
	Nil = 0,
	/// Crossing upward. Trails, and emits.
	Pos = 1,
	}

	impl Zero {
	/// Zero, for all three. This is the point of the type.
	#[inline]
	pub const fn magnitude(self) -> i8 {
	0
	}

	/// Direction of travel through the crossing: -1, 0, +1.
	#[inline]
	pub const fn direction(self) -> i8 {
	self as i8
	}

	/// Ternary digit 0..2, for packing.
	#[inline]
	pub const fn digit(self) -> u8 {
	(self as i8 + 1) as u8
	}

	#[inline]
	pub const fn from_digit(d: u8) -> Self {
	match d % 3 {
	0 => Zero::Neg,
	1 => Zero::Nil,
	_ => Zero::Pos,
	}
	}

	/// The trianti, Law 4: trinary inversion is the order-3 rotation R, and R ≠ R⁻¹.
	/// Applying it three times returns to start; applying it twice is not the inverse
	/// of applying it once, which is exactly what makes trinary not binary.
	#[inline]
	pub const fn rotate(self) -> Self {
	Self::from_digit(self.digit() + 1)
	}

	/// The counter-rotation R², distinct from R.
	#[inline]
	pub const fn anti_rotate(self) -> Self {
	Self::from_digit(self.digit() + 2)
	}
	}

	/// The five registers of IX.B.3.
	#[derive(Clone, Copy, PartialEq, Eq, Debug)]
	#[repr(u8)]
	pub enum Register {
	Zero = 0,
	/// Light. Undifferentiated, before the prism.
	Translucent = 1,
	Red = 2,
	Green = 3,
	Blue = 4,
	}

	impl Register {
	/// Registers 0 and 1 are never computed. IX.B.2: *"we don't have to calculate the zero
	/// and we don't have to calculate the translucent space, and that is what wins."*
	#[inline]
	pub const fn is_free(self) -> bool {
	matches!(self, Register::Zero \| Register::Translucent)
	}

	/// Traversal order of the hose: tip, the three that cost, tail.
	pub const HOSE: [Register; 5] = [
	Register::Translucent,
	Register::Red,
	Register::Green,
	Register::Blue,
	Register::Translucent,
	];
	}

	/// A carrier. `DC` never crosses zero, so it can only ever report `Nil` — the type makes
	/// the binary limit unrepresentable rather than merely documented.
	#[derive(Clone, Copy, PartialEq, Eq, Debug)]
	pub enum Carrier {
	Dc,
	/// Alternating, with a whole number of phase steps per cycle.
	Ac {
	steps_per_cycle: u32,
	},
	}

	impl Carrier {
	/// Which zero the carrier is at, at phase step `t`. `None` when the carrier is away
	/// from a crossing and therefore carrying magnitude.
	///
	/// DC returns `Some(Nil)` at every step and never `Neg` or `Pos` — **one reachable zero, and
	/// the crossings are not reachable at all.** That is the binary world, stated as a return
	/// value: a carrier with no zero crossing has one direction, so it can never tell a rise from
	/// a fall. (Measured 2026-10-08: DC reaches exactly 1; the earlier comment said "two states",
	/// which counted magnitude directions rather than reachable zeros.)
	pub const fn zero_at(self, t: u32) -> Option<Zero> {
	match self {
	Carrier::Dc => Some(Zero::Nil),
	Carrier::Ac { steps_per_cycle } => {
	if steps_per_cycle == 0 {
	return Some(Zero::Nil);
	}
	let half = steps_per_cycle / 2;
	let phase = t % steps_per_cycle;
	if phase == 0 {
	Some(Zero::Pos) // rising through
	} else if phase == half {
	Some(Zero::Neg) // falling through
	} else {
	None // carrying magnitude, not at a crossing
	}
	}
	}
	}

	/// How many distinct zeros this carrier can actually reach through [`Self::zero_at`].
	///
	/// This counts REACHABLE return values, not variants of the [`Zero`] type. Those are different
	/// quantities and only the second is three.
	///
	/// Corrected 2026-10-08 (operator-directed). This previously returned `3` for any
	/// `steps_per_cycle >= 2`, which disagreed with `zero_at` on 63 of 64 cycle lengths.
	/// Measured exhaustively over `steps_per_cycle` in `1..=64` and every phase in each cycle:
	/// `Some(Zero::Nil)` occurred 0 times, and the only reachable sets are `{Pos}` and
	/// `{Neg, Pos}`. `zero_at` documents `None` as carrying magnitude, not at a crossing, which
	/// is the opposite of `Nil`'s the line is dead — so `None` cannot stand in for `Nil`.
	///
	/// The three zeros are not lost by this correction. They live in the [`Zero`] type itself,
	/// which carries all three, and in the order-3 orbit of [`Zero::rotate`] / [`Zero::anti_rotate`]
	/// (R³ = identity, R ≠ R²). The system measures them in the rainbow lane, not the carrier lane:
	/// RAINBOR's three waves — `path1.path2.path3`, NN · GNN · FNN, each an HTTP-0 portal acting as
	/// itself — where the anti is measured order-3 at 192 of 192, and the free fourth zero is
	/// the fourth point at which the three waves agree. The carrier was simply the wrong instrument
	/// to ask. Operator, 2026-10-08: "there are more electronics but wait no they are rainbons."
	pub const fn zero_states(self) -> u8 {
	match self {
	// One reachable zero: the quiescent line, at every phase.
	Carrier::Dc => 1,
	Carrier::Ac { steps_per_cycle } => match steps_per_cycle {
	// Never cycles, so it only ever reports the dead line.
	0 => 1,
	// `half == 0`, so every phase is the rising crossing: `{Pos}` alone.
	1 => 1,
	// Rising and falling are both reachable and distinct: `{Pos, Neg}`.
	// `Nil` is NOT reachable — a crossing is never a dead line.
	_ => 2,
	},
	}
	}
	}

	/// 80 trits packed into one `u128`, base 3.
	#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
	pub struct TritWord(pub u128);

	impl TritWord {
	pub const CAP: usize = TRITS_PER_U128;

	pub fn pack(t: &[Zero]) -> Self {
	let mut acc: u128 = 0;
	let n = if t.len() < Self::CAP {
	t.len()
	} else {
	Self::CAP
	};
	for i in 0..n {
	acc = acc * 3 + t[i].digit() as u128;
	}
	TritWord(acc)
	}

	pub fn unpack(self, out: &mut [Zero]) -> usize {
	let n = if out.len() < Self::CAP {
	out.len()
	} else {
	Self::CAP
	};
	let mut acc = self.0;
	for i in (0..n).rev() {
	out[i] = Zero::from_digit((acc % 3) as u8);
	acc /= 3;
	}
	n
	}
	}

	// ---------------------------------------------------------------- modular arithmetic

	#[inline]
	const fn mul(a: u64, b: u64) -> u64 {
	((a as u128 * b as u128) % P as u128) as u64
	}

	#[inline]
	const fn add(a: u64, b: u64) -> u64 {
	let s = a + b;
	if s >= P {
	s - P
	} else {
	s
	}
	}

	/// `base^exp mod P`, square-and-multiply. `const` so roots can be checked at compile time.
	pub const fn pow(mut base: u64, mut exp: u64) -> u64 {
	let mut acc: u64 = 1;
	base %= P;
	while exp > 0 {
	if exp & 1 == 1 {
	acc = mul(acc, base);
	}
	base = mul(base, base);
	exp >>= 1;
	}
	acc
	}

	/// Multiplicative inverse by Fermat: `a^(P-2) mod P`. P is prime.
	#[inline]
	pub const fn inv(a: u64) -> u64 {
	pow(a, P - 2)
	}

	// ------------------------------------------------- the spherical pump wave transform

	/// Forward transform: 27 samples → 27 spectral coordinates.
	///
	/// This is Law 20's rime prism. Newton used two prisms and showed light recombines to
	/// white, which proved it composite; this is the same operation generalised to 27
	/// coordinates on the sphere, over the integers so nothing is lost in the split.
	///
	/// `X[0]` is the DC glyph — the sum, which is the free centre of Law 0.
	pub fn prism(x: &[u64; K]) -> [u64; K] {
	let mut out = [0u64; K];
	for j in 0..K {
	let wj = pow(W, j as u64);
	let mut acc = 0u64;
	let mut t = 1u64;
	for i in 0..K {
	acc = add(acc, mul(x[i] % P, t));
	t = mul(t, wj);
	}
	out[j] = acc;
	}
	out
	}

	/// Inverse transform: 27 spectral coordinates → the original 27 samples.
	///
	/// "Transfers back and forth" — the round trip is exact, not approximate, because the
	/// arithmetic is integer and `27` is invertible mod `P`.
	pub fn unprism(x: &[u64; K]) -> [u64; K] {
	let winv = inv(W);
	let kinv = inv(K as u64);
	let mut out = [0u64; K];
	for j in 0..K {
	let wj = pow(winv, j as u64);
	let mut acc = 0u64;
	let mut t = 1u64;
	for i in 0..K {
	acc = add(acc, mul(x[i] % P, t));
	t = mul(t, wj);
	}
	out[j] = mul(acc, kinv);
	}
	out
	}

	/// The pump. VIII.A.7, the Photon Law of the Rime Series: *"the more energy you push into
	/// it, the further away the shell gets."*
	///
	/// Shell radius is the number of whole rungs of the 3-ladder the energy reaches, so it
	/// grows as log₃ and never linearly. Integer only: no logarithm is taken, the rungs are
	/// counted.
	pub const fn pump_shell(energy: u64) -> u32 {
	let mut shell = 0u32;
	let mut rung = 1u64;
	while rung <= energy && shell < 40 {
	rung *= 3;
	shell += 1;
	}
	shell
	}

	/// Drive one pump step and report which zero the carrier presents at that phase.
	pub const fn pump_step(c: Carrier, t: u32) -> (u32, Option<Zero>) {
	(t, c.zero_at(t))
	}

	#[cfg(test)]
	mod tests {
	use super::*;

	#[test]
	fn all_three_zeros_have_magnitude_zero() {
	assert_eq!(Zero::Neg.magnitude(), 0);
	assert_eq!(Zero::Nil.magnitude(), 0);
	assert_eq!(Zero::Pos.magnitude(), 0);
	// and they are still distinguishable
	assert_ne!(Zero::Neg.direction(), Zero::Pos.direction());
	assert_ne!(Zero::Neg, Zero::Pos);
	}

	#[test]
	fn dc_cannot_reach_the_crossings() {
	let dc = Carrier::Dc;
	assert_eq!(dc.zero_states(), 1);
	for t in 0..64 {
	assert_eq!(dc.zero_at(t), Some(Zero::Nil));
	}
	let ac = Carrier::Ac { steps_per_cycle: 4 };
	assert_eq!(ac.zero_states(), 2, "AC reaches Pos and Neg, never Nil");
	assert_eq!(ac.zero_at(0), Some(Zero::Pos));
	assert_eq!(ac.zero_at(2), Some(Zero::Neg));
	assert_eq!(ac.zero_at(1), None);
	}

	/// The old test compared `zero_states()` against a hardcoded 3 and never asked what `zero_at`
	/// could actually return. This asks, exhaustively, so the accessor cannot drift from the
	/// behaviour again.
	#[test]
	fn zero_states_equals_what_zero_at_can_reach() {
	for spc in 0..=64u32 {
	let c = Carrier::Ac {
	steps_per_cycle: spc,
	};
	let mut pos = false;
	let mut neg = false;
	let mut nil = false;
	// one full cycle covers every phase; spc == 0 has a single degenerate phase
	for t in 0..spc.max(1) {
	match c.zero_at(t) {
	Some(Zero::Pos) => pos = true,
	Some(Zero::Neg) => neg = true,
	Some(Zero::Nil) => nil = true,
	None => {}
	}
	}
	let reachable = u8::from(pos) + u8::from(neg) + u8::from(nil);
	assert_eq!(
	c.zero_states(),
	reachable,
	"zero_states disagreed with zero_at at steps_per_cycle={spc}"
	);
	if spc >= 1 {
	assert!(!nil, "AC reached Some(Nil) at steps_per_cycle={spc}");
	}
	}
	let dc = Carrier::Dc;
	assert_eq!(dc.zero_states(), 1);
	assert_eq!(dc.zero_at(7), Some(Zero::Nil));
	}

	#[test]
	fn trianti_is_order_three_and_distinct_from_its_inverse() {
	for z in [Zero::Neg, Zero::Nil, Zero::Pos] {
	assert_eq!(z.rotate().rotate().rotate(), z); // R³ = identity
	assert_ne!(z.rotate(), z.anti_rotate()); // R ≠ R²
	assert_eq!(z.rotate().anti_rotate(), z); // R·R² = identity
	}
	}

	#[test]
	fn w_really_is_a_primitive_27th_root() {
	assert_eq!(pow(G, (P - 1) / 27), W);
	assert_eq!(pow(W, 27), 1);
	for d in 1..27u64 {
	if 27 % d == 0 && d < 27 {
	assert_ne!(pow(W, d), 1, "W had order {d}, not 27");
	}
	}
	}

	#[test]
	fn the_prism_closes_on_zero() {
	// Law 20: 1 + w + ... + w²⁶ ≡ 0 (mod p)
	let mut acc = 0u64;
	for j in 0..27u64 {
	acc = add(acc, pow(W, j));
	}
	assert_eq!(acc, 0);
	}

	#[test]
	fn transfers_back_and_forth_exactly() {
	let mut x = [0u64; K];
	for i in 0..K {
	x[i] = ((i as u64 * 37 + 11) * 977) % P;
	}
	let spectrum = prism(&x);
	let back = unprism(&spectrum);
	assert_eq!(x, back, "round trip was not exact");
	// the DC glyph is the sum: the free centre
	let mut sum = 0u64;
	for i in 0..K {
	sum = add(sum, x[i]);
	}
	assert_eq!(spectrum[0], sum);
	}

	#[test]
	fn trit_word_round_trips() {
	let mut t = [Zero::Nil; TRITS_PER_U128];
	for i in 0..TRITS_PER_U128 {
	t[i] = Zero::from_digit((i % 3) as u8);
	}
	let w = TritWord::pack(&t);
	let mut back = [Zero::Nil; TRITS_PER_U128];
	assert_eq!(w.unpack(&mut back), TRITS_PER_U128);
	assert_eq!(t, back);
	}

	#[test]
	fn eighty_is_the_exact_ceiling() {
	// 3^80 fits a u128, 3^81 does not
	let mut acc: u128 = 1;
	for _ in 0..80 {
	acc = acc.checked_mul(3).expect("3^80 must fit u128");
	}
	assert!(acc.checked_mul(3).is_none(), "3^81 must overflow u128");
	}

	#[test]
	fn free_registers_are_zero_and_one() {
	assert!(Register::Zero.is_free());
	assert!(Register::Translucent.is_free());
	assert!(!Register::Red.is_free());
	assert!(!Register::Green.is_free());
	assert!(!Register::Blue.is_free());
	// the hose: translucent leads and translucent closes
	assert_eq!(Register::HOSE[0], Register::Translucent);
	assert_eq!(Register::HOSE[4], Register::Translucent);
	assert_eq!(Register::HOSE.len(), 5);
	}

	#[test]
	fn pump_shell_grows_as_log3() {
	assert_eq!(pump_shell(0), 0);
	assert_eq!(pump_shell(1), 1);
	assert_eq!(pump_shell(3), 2);
	assert_eq!(pump_shell(9), 3);
	assert_eq!(pump_shell(27), 4);
	// more energy in, further out, but never linearly
	assert!(pump_shell(1_000_000) < 20);
	}
	}