Comp-Core Source Of Truth

Comp-Core Source Of Truth

This is the current grounding document for computational choreography. It follows
the code and separates implemented runtime from research vocabulary.

Current Runtime Authority

The implemented stack is not a single monolithic "model." It is a set of runtime
bridges and crates:

MotionMixApp
  Services/EchelonBridge.swift
  Services/SANService.swift
  Services/SANTrajectoryLogger.swift
  Services/MocopiReceiver.swift
  Services/MocopiFeatureExtractor.swift
  Services/ClaimBridgeService.swift

Comp-Core / cc-echelon
  crates/cc-brain/src/lib.rs
  crates/cc-brain/src/types.rs
  crates/cc-brain/src/latent/*
  crates/cc-brain/src/san/*
  crates/cc-brain/src/san/claim_bridge.rs
  crates/cc-brain/src/ffi.rs
  crates/audio-engine/src/*
  crates/motion-bridge/src/*

Comp-Core / semantics
  core/semantic/cc-inscription
  core/semantic/cc-semantic-language
  apps/convex-memory/convex/inscriptions.ts

The correct high-level sentence is:

> MotionMixApp gathers body and device signals, feeds them through the Rust
> EchelonCore, reads latent/dynamics output, runs SAN and ClaimBridge, and uses
> those outputs for audio, camera, training capture, and N'Ko motion inscriptions.

Verified Runtime Loop

Source: `MotionMixApp/Services/EchelonBridge.swift`.

CoreMotion frames
  -> EchelonBridge.updateSensor(...)
  -> pendingSensorFrames
  -> EchelonBridge.step(dt)
  -> echelon_update_sensor(...)
  -> echelon_step(...)
  -> echelon_bridge_brain_to_audio(...)
  -> echelon_get_latent(...)
  -> echelon_get_section_state(...)
  -> echelon_get_lexicon(...)
  -> echelon_get_ui_state(...)
  -> SANService.step(core:)
  -> echelon_get_dynamics_128(...)
  -> ClaimBridgeService.detect(latent:)

Important details:

• `EchelonBridge` is `@MainActor`.
• Brain access is single-threaded by design.
• Audio uses a separate `AudioHandle`.
• `isEnabled` must be true or `step(dt)` returns immediately.
• `SANService` is owned by `EchelonBridge`.
• `ClaimBridgeService` runs after `echelon_get_dynamics_128`.

EchelonCore

Source: `cc-brain/src/lib.rs`, `cc-brain/src/types.rs`.

`EchelonCore` is the Rust brain object. It owns:

• a pluggable `LatentUpdater`;
• `SectionStateMachine`;
• `LexiconController`;
• sensor frame buffer;
• current `LatentState`;
• current `SectionState`;
• current `Lexicon`;
• current `UIState`;
• `WindowAligner`;
• `AnticipationAdapter`;
• pose/gesture caches;
• temporal integrator;
• pocket FFT tempo source;
• Femto skeleton encoder.

The public source wording in `cc-brain/src/lib.rs` is:

SensorFrame -> LatentUpdater -> LatentState -> StateMachine -> SectionState
                                   |                            |
                              LexiconController <---------------
                                   |
                                Lexicon

LatentUpdater Reality

Source: `cc-brain/src/latent/mod.rs`.

The code defines a trait named `LatentUpdater` and three implementations:

• `SimpleLatentUpdater`: non-learned baseline.
• `LearnedLatentUpdater`: trained-weight path.
• `DellLatentUpdater`: dual-equilibrium path.

The term "LIM-RPS" appears in comments and in `motion-bridge/src/lim_rps.rs`,
but it should not be used as the current canonical name for the whole system.
When documenting implemented code, use the concrete source names:

• `EchelonCore`
• `LatentUpdater`
• `SimpleLatentUpdater`
• `LearnedLatentUpdater`
• `DellLatentUpdater`
• `LatentState`
• `dynamics_128`

DELL Reality

Source: `cc-brain/src/latent/dell.rs`.

`DellLatentUpdater` exists. It is a simplified dual-equilibrium latent updater
with:

• fast equilibrium state `x_fast`;
• slow equilibrium state `y_slow`;
• beat phase;
• `k_fast = 4`;
• `k_slow = 6`;
• default latent `dim = 32`;
• synthetic limb embeddings from sensor data in the current implementation.

That last point matters. The code says:

For now, we create synthetic embeddings from available sensor data.
In production, this would come from the sensor fusion pipeline.

So docs must not imply a fully trained full-body DELL model unless a specific
trained artifact and code path are identified.

128D Dynamics Contract

Sources:

• `cc-brain/src/lib.rs` for `dynamics_128()`.
• `cc-brain/src/ffi.rs` for `echelon_get_dynamics_128`.
• `MotionMixApp/Services/EchelonBridge.swift` for Swift overlays.
• `MotionMixApp/Services/MocopiFeatureExtractor.swift` for mocopi compression.

The practical contract is:

Rust fills core dynamics.
Swift overlays pose/mocopi/pocket/watch data in getDynamics128().
SAN reads the SANPipeline flat input.
SANTrajectoryLogger writes 128D JSONL.
ClaimBridge reads the 128D dynamics vector from EchelonBridge.step().

Do not claim every consumer reads the same Swift-overlaid vector unless the source
shows that exact call path. In particular:

- `SANPipeline::flatten_latent(...)` flattens Rust `LatentState`.
- `EchelonBridge.getDynamics128()` overlays Swift-side pose/mocopi/watch features.
- `EchelonBridge.step()` currently sends raw `echelon_get_dynamics_128(...)` output
to `ClaimBridgeService.detect(...)` directly, without calling the Swift overlay
helper.

That is an important integration gap to keep visible.

SAN Reality

Sources:

• `MotionMixApp/Services/SANService.swift`
• `MotionMixApp/Services/SANTrajectoryLogger.swift`
• `cc-brain/src/san/mod.rs`
• `cc-brain/src/san/config.rs`
• `cc-brain/src/ffi.rs`
• `MotionMixApp/MotionMixApp/Resources/san_weights.bin`
• `MotionMixApp/MotionMixApp/Resources/san_manifest.json`

Verified:

- `SANPipeline` exists in Rust.
- `SANService` exists in Swift and owns a `SANHandle`.
- `san_create_default()` and `san_create()` call `init_all()`.
- The active layer names are FAN, FuseMoE, NHA, TTT, and output heads.
- `SANService.loadWeights()` looks for `san_weights.bin` and `san_manifest.json`.
- The current local manifest has 76 entries and 164,248 parameters.
- The local weight binary is 656,992 bytes.
- `SANTrajectoryLogger` writes schema version 2, dims 128 JSONL.
- `SANTrajectoryLogger` has a remote endpoint:
`http://[ip]:9471/san-frame`.

Must be phrased carefully:

- The Rust comments call several SAN layers "Phase 3 stub" or "Phase 4 stub."
- `SANConfig.default().mix_factor` is `0.0`.
- `SANService.mixFactor` also defaults to `0.0`.
- Consumer services blend SAN output with heuristic output. SAN may be live and
logged while still having no behavioral influence if mix factor remains zero.
- Existing documentation claiming "135K parameters" is not aligned with the
current local manifest; use 164,248 loaded parameters for this snapshot.

Do not repeat unverified claims like "5,408 pairs" or "val loss 0.028" unless the
training artifact is located and cited.

DiffusionService / One-Step Flow Reality

Sources:

• `MotionMixApp/Services/DiffusionService.swift`
• `MotionMixApp/MLModels/ConditioningEncoder.mlpackage`
• `MotionMixApp/MLModels/FlowGenerator1Step.mlpackage`
• `MotionMixApp/MASTER-TASKS.md`
• `MotionMixApp/CLAUDE.md`

Verified:

- `DiffusionService` exists.
- It has three generation paths: phone hub, CoreML, and rule-based fallback.
- The CoreML path uses `ConditioningEncoder` to produce a conditioning embedding.
- The CoreML path then calls `FlowGenerator1Step`.
- The app builds a larger dynamics vector but truncates to the 104D input expected
by the current `ConditioningEncoder`.
- The flow generator name and Swift path indicate one-step token/logit generation,
not an in-app multi-step DDPM/DDIM sampler.

Current caveat:

`MASTER-TASKS.md` marks `ConditioningEncoder` and `FlowGenerator1Step` as shell /
wired / not trained at the checkpoint it documents. Until newer training evidence
is found, docs must separate "artifact exists and loads" from "artifact is trained
and musically good."

Correct wording:

DiffusionService contains a conditioned one-step flow/token generation path with
phone-hub and rule-based fallbacks.

Incorrect wording:

The deployed app uses a full multi-step diffusion sampler conditioned on the full
128D body state.

ClaimBridge / N'Ko Motion Inscription Reality

Sources:

• `MotionMixApp/Services/ClaimBridgeService.swift`
• `cc-brain/src/san/claim_bridge.rs`
• `cc-brain/src/ffi.rs`
• `core/semantic/cc-inscription/README.md`
• `core/semantic/cc-semantic-language`
• `apps/convex-memory/convex/inscriptions.ts`

Verified:

• `ClaimBridgeService` is implemented.
• It wraps Rust `claim_bridge_*` FFI.
• It detects N'Ko inscription claims from Echelon latent/dynamics.
• It posts to a Convex endpoint when confidence passes the Swift threshold.
• Rust `ClaimBridge` maps latent dynamics to ten N'Ko claim signals.
• `cc-inscription` provides typed claim IR and N'Ko surface rendering.
• Convex mutations include motion/speech/conversation inscription writes.

Correct wording:

body dynamics -> ClaimBridge -> controlled N'Ko claim sigil

Incorrect wording:

body dynamics -> arbitrary natural-language N'Ko sentence

The current system turns motion into controlled claims, not full free-form prose.

N'Ko Audio / ASR Reality

Sources:

• `Desktop/nko-brain-scanner/asr/trajectory_asr.py`
• `Desktop/nko-brain-scanner/constrained/trajectory_bias.py`
• `Desktop/MAOE-NKo-Technical-Architecture.md`
• `Desktop/Comp-Core/experiments/agp_mlx/asr_bridge`

Correct wording:

• The verified ASR anchor is trajectory-biased Transformer CTC.
• MAOE-N'Ko is a correction/admissibility/routing layer around ASR output.
• MAOE is not the trained acoustic core unless a future experiment proves it.

DJ / AirDeck Reality

Sources:

• `Comp-Core/core/audio-media/cc-dj`
• `Comp-Core/core/audio-media/cc-echelon/tools/lume-rekordbox-bridge`
• K11 runtime scripts and Rekordbox keyboard mappings.

Correct architecture:

camera/pose/body truth
  -> gesture detector
  -> K11 safety bridge
  -> Rekordbox keyboard/MIDI command

Do not send Rekordbox commands directly from Unity, Mac4, mocopi, or raw sensors.
K11 remains the command safety gate.

Terms To Demote

Use these only as historical or research language unless a current source file
requires the exact term:

- LIM-RPS as the whole architecture.
- "the 16 dimensions are the heart" as if all current paths are 16D.
- SAN replacing every heuristic unconditionally.
- DELL as a fully trained full-body model.
- V5/V6 training numbers without artifacts.
- "diffusion" as implemented motion-to-audio generation unless the current code
path and model artifact are named.
- "learning from the body" without specifying whether this means JSONL capture,
SAN weights, ClaimBridge statistics, or a separate training run.

Current Hard Invariants

1. Source names beat invented vocabulary.
2. Runtime behavior beats architecture diagrams.
3. Training claims require artifacts.
4. N'Ko motion inscription is real, but controlled.
5. N'Ko ASR is separate from motion inscription.
6. K11 is the DJ command safety gate.
7. MotionMixApp can log data continuously without that meaning the model has
retrained itself.
8. If `mixFactor = 0.0`, SAN output exists but does not drive blended consumers.