Invariants — Rules That Must Never Be Violated

Invariants — Rules That Must Never Be Violated

These constraints are drawn from all three documentation sets (Set A implementation,
Set B AirDeck/camera-first, Set C Mac4 manuscript). Violation causes either
system failure, safety risk, or loss of artistic integrity.

---

Safety Invariants (Breaking These Affects Live Performance)

I-1: Only K11 sends Rekordbox commands.
Unity, mocopi, Mac4 browser, MotionMix, iPhones, and Watch must not directly
dispatch Rekordbox keyboard or MIDI events. K11's command gate is the sole authority.

I-2: No gesture becomes live without promotion.
A newly detected gesture cannot fire a Rekordbox command without passing through
the full promotion pipeline (physical capture → capture gate → self-play →
proof matrix → promotion manifest loaded by K11 bridge).
Exception: left hand raise (deck 1) and right hand raise (deck 2) are baseline
proven gestures and may remain live.

I-3: EchelonHandle is MainActor-only.
The Rust FFI handle must only be accessed from Swift's MainActor. Any other thread
produces undefined behavior in the Rust core.

I-4: AudioHandle is audio-thread-only.
`renderAudio()` must never be called from MainActor. The audio thread is real-time;
any allocation or GC pause causes audible glitches.

---

Architecture Invariants (Breaking These Breaks System Behavior)

I-5: Camera-first baseline for all gestures.
Every gesture in the system must have a tested camera-only path. Mocopi absence
must not reduce a gesture from "working" to "not working." Only from "high
confidence" to "lower confidence."

I-6: SANService is owned by EchelonBridge.
Never use `@StateObject` for SANService. It must be instantiated as `let san =
SANService()` inside EchelonBridge. This was a production bug (zero-KB training
files) — SANService initialized twice meant the logger's file handle was orphaned.

I-7: Camera nodes set isEnabled = false.
An iPhone acting as a camera node must never run the SAN or open training file
handles. The guard lives in MotionMixApp.swift. A camera node is not a SAN host.

I-8: Name the exact 128D producer and consumer.
Some paths use Rust `dynamics_128`; some Swift helpers overlay pose/mocopi/watch
features; the CoreML path currently truncates to 104D. Never claim "the 128D
vector" without naming the exact call path.

I-9: SAN weight format must match Rust architecture.
The manifest JSON defines shapes and byte offsets. Any architecture change requires
a new manifest + new weights. Never load V5 weights with a V6 architecture.

---

Aesthetic Invariants (Breaking These Loses the Creative Direction)

I-10: The real body is the canvas.
The Femto/Mega depth body is the visual material for the visual path. Do not
replace it with a mocopi avatar, a stick figure, or a generic geometric body.
Motion may persist without the depth body; the performer must not be fabricated.

I-11: bounded rate limits apply to all visual outputs.
No visual element may change discontinuously when a sensor value crosses a
threshold. Attack and release rates must be bounded. Sensor dropout does not
blank a visual — it decays it.

I-12: false_reactive gates all visual responses.
When false_reactive ≥ 0.5 or body_confidence < 0.35, all template-driven
visuals and effect outputs are damped. The system does not respond to noise.

---

Training Invariants (Breaking These Corrupts the Corpus)

I-13: Template review before training.
Movement primitives and gesture templates must be validated against labeled
rehearsal sessions before any neural classifier is trained on them. Training on
uncorrected templates teaches the system to be wrong consistently.

I-14: V6 claims require a new artifact chain.
Any claim that V6 uses full 128D, new modalities, retrained SAN weights, or a
new CoreML generator must point to the training data, script, checkpoint,
exported artifacts, metrics, and on-device load proof.

I-15: SANTrajectoryLogger protected by NSLock.
Training data writes happen on a background thread. The NSLock in
SANTrajectoryLogger must not be removed. Concurrent writes without the lock
produce corrupted or truncated training files.

---

Vocabulary Invariants (Breaking These Creates Confusion)

I-16: "phrase" means musical phrase lifecycle in the SAN context.
The SAN output dims `phraseForming / phraseGrowing / phraseStable / phraseDissolving`
describe a musical phrase arc. "Phrase" in SAN output docs never means a movement
command.

I-17: "choreography phrase" means an input movement command.
`left_hand_raise_play`, `airdeck_platter_scratch_left` — these are input
command specifications. The body performs a choreography phrase; the SAN assigns
a motion regime.

I-18: "motion regime" means an SAN output classification.
Grounded, Ecstatic, Ascending, Turbulent — these are clusters in z*-space that
route music generation. They are what the SAN produces, not what the body does.