feat(trinity_loss): L-S51 — φ-prior-aware ternary contrastive loss (Trinity Loss)

[gHashTag]

Closes #809

Summary

Implements the Trinity Loss — a φ-prior-aware ternary contrastive loss function for JEPA-T training (L-S51).

Formula

sim(a, b)     = dot_ternary(a, b) / 64
L_triplet     = max(0, margin + sim(a, n) - sim(a, p))   [margin = 0.5]
L_phi_prior   = φ⁻² · (||a||₀ + ||p||₀ + ||n||₀) / 192  [φ⁻² ≈ 0.382]
L_total       = L_triplet + λ · L_phi_prior               [λ = 0.1]

where ||x||₀ counts zero entries in the ternary vector x.

Files Changed

Path	Description
crates/trinity_loss/Cargo.toml	Crate manifest (Apache-2.0)
crates/trinity_loss/src/lib.rs	dot_ternary, sim, zero_count, phi_prior_term, trinity_loss
crates/trinity_loss/tests/loss.rs	10 hand-computed triplets (±1e-4) + 50 LFSR stability tests
crates/trinity_loss/python_ref/trinity_loss_ref.py	NumPy reference — informational only, NOT in cargo build
crates/trinity_loss/README.md	Usage docs and formula explanation

Test Results

cargo test -p trinity_loss

running 5 tests  [unit_tests in lib.rs]     → 5 passed
running 16 tests [tests/loss.rs]            → 16 passed
running 5 tests  [doc-tests]                → 5 passed
Total: 26 passed, 0 failed

Constraints Satisfied

• R1 CROWN: Rust ONLY in cargo build/cargo test. Python file is reference docs only (not listed in Cargo.toml).
• Deterministic: all functions produce identical output for identical inputs.
• Allocation-free: no heap allocation beyond constant-size stack frames.
• No std::time: safe for embedded-adjacent usage.
• Author: Dmitrii Vasilev admin@t27.ai
• License: Apache-2.0
• DOI: 10.5281/zenodo.19227877
• Anchor: φ² + φ⁻² = 3; φ⁻² ≈ 0.382 as soft margin anchor.