How It All Fits

How It All Fits

This page is the architecture decision map after auditing the source. It replaces
the older explanation that treated `LIM-RPS`, SAN, and diffusion as one completed
trained stack.

Design Choice

The system is built around an intermediate body state, not around raw sensors and
not around a single opaque model.

raw sensors
  -> body/state extraction
  -> EchelonCore latent + lexicon
  -> SAN / audio / visuals / ClaimBridge / AirDeck

This is still the right direction. The correction is that the current source does
not prove one fully trained, end-to-end architecture. It proves several connected
runtime pieces with different maturity levels.

Where Intelligence Lives

Verified runtime layers:

- `EchelonCore`: Rust real-time brain state and latent/lexicon generation.
- `LatentUpdater`: selectable update backend inside `cc-brain`.
- `SANPipeline`: Rust neural pipeline exposed through FFI and wrapped by
`SANService`.
- `DiffusionService`: Swift/CoreML generation service with phone hub, CoreML,
and rule-based fallback paths.
- `ClaimBridge`: Rust/Swift bridge from dynamics to N'Ko-style motion claims.
- MotionMix BodyTruth: shared body-state bus being stabilized for Mac4/K11.

The docs should say "these layers coordinate" rather than "one model learned the
whole body-to-music system."

Why Rust For The Core, Swift For The Shell

This part is source-grounded.

Rust owns the real-time core:

• `cc-brain`
• `echelon-audio`
• `motion-bridge`
• FFI functions used by MotionMixApp
• SAN FFI
• ClaimBridge FFI

Swift owns app orchestration:

• sensor callbacks;
• camera and UI;
• CoreML service loading;
• `EchelonBridge` step loop;
• local logging and HTTP push clients.

The important caveat is that not every Rust module is equally mature. Some
modules are runtime-critical, while some are research or partially wired.

Backend Selection

`EchelonBridge.Backend` defines:

The initializer default is `.simple`. Therefore docs must not say DELL is the
current default unless a call site explicitly selects `.dell`.

SAN Reality

`SANService.swift` wraps a Rust `SANHandle`.

Verified facts:

- The name in source is Somatic Adaptive Network.
- `mixFactor` defaults to `0.0`.
- Weights load from `san_weights.bin` plus `san_manifest.json`.
- `SANTrajectoryLogger` records schema-v2 JSONL under
`Documents/san-training/<session-id>.jsonl`.
- The logger can push NDJSON to `http://[ip]:9471/san-frame`.

The current local manifest contains 76 tensors and 164,248 parameters. Older
numbers such as 135K, 280K, 5,408 examples, or validation loss 0.028 must be
treated as stale unless tied to a checked-in training report.

Diffusion / One-Step Flow Reality

`DiffusionService.swift` is not a verified full multi-step diffusion sampler.

The implemented CoreML path is:

buildDynamicsVector()
  -> ConditioningEncoder input [1,104]
  -> embedding [768]
  -> optional TTTAdaptationLayer
  -> FlowGenerator1Step(noise [1,384,81], conditioning [1,768])
  -> logits -> TokenGrid

The source includes an explicit temporary shim that truncates the larger dynamics
vector to 104 dimensions for the encoder. So the current path is a conditioned
one-step flow/token generator, with fallbacks, not a completed full 128D
diffusion stack.

Why Distributed

The distributed split is still correct:

• Mac4: Unity visuals, Sony/mocopi sidecar, local Unity skeleton feed.
• K11: Rekordbox, AirDeck, pose viewer, keyboard/MIDI safety gate.
• MotionMix hub: shared body-state bus and BodyTruth endpoint.
• iPhones/watches: sensor and camera sources.

The reason is safety and latency. Unity can visualize; K11 decides whether DJ
commands reach Rekordbox.

Known Limitations

- MotionMix BodyTruth has shown hub timeouts under sustained mocopi relay.
- Camera-only gestures must remain available when mocopi is off.
- The 128D vector is not yet a single invariant contract across all consumers.
- ClaimBridge in `EchelonBridge.step()` reads raw Rust dynamics, not the Swift
`getDynamics128()` overlay helper.
- The CoreML conditioning encoder is currently 104D, not full 128D.
- Training provenance for current SAN weights needs a verifiable local report.

Correct Mental Model

Use this language:

EchelonCore produces real-time body state.
SAN maps body state into adaptive output parameters.
DiffusionService is an experimental conditioned one-step flow/token generation path.
ClaimBridge converts motion dynamics into controlled N'Ko claim inscriptions.
MotionMix BodyTruth should become the shared authority once stable.
K11 remains the final DJ safety gate.