128D Dynamics Vector - Verified Contract And Caveats

128D Dynamics Vector - Verified Contract And Caveats

The old page described one universal "canonical vector." The source is more
complicated. There are several 128D-adjacent paths that overlap but are not
identical.

Verified Files

• `Desktop/Comp-Core/core/audio-media/cc-echelon/crates/cc-brain/src/lib.rs`
• `Desktop/Comp-Core/core/audio-media/cc-echelon/crates/cc-brain/src/ffi.rs`
• `Desktop/Comp-Core/core/audio-media/cc-echelon/crates/cc-brain/src/san/mod.rs`
• `Desktop/MotionMixApp/MotionMixApp/Services/EchelonBridge.swift`
• `Desktop/MotionMixApp/MotionMixApp/Services/MocopiFeatureExtractor.swift`
• `Desktop/MotionMixApp/MotionMixApp/Services/SANTrajectoryLogger.swift`
• `Desktop/MotionMixApp/MotionMixApp/Services/DiffusionService.swift`

The Three Important 128D Paths

1. Rust Echelon Dynamics

`cc-brain` exposes:

EchelonCore::dynamics_128() -> [f32; 128]

and FFI:

echelon_get_dynamics_128(core, out)

This is the Rust-side dynamics vector. It is the base source for several Swift
consumers.

2. Swift EchelonBridge Overlay

`EchelonBridge.getDynamics128()` calls `echelon_get_dynamics_128(...)`, then
overlays Swift-side state:

[63:69]    pose stats from mocopi or Vision cache
[75]       modality mask
[76:100]   mocopi 24D features
[100:102]  pocket IMU pitch/roll
[102:104]  watch HR/wrist energy
[104:128]  reserved

This helper is used by DiffusionService when `echelonBridge` is connected.

3. SAN Flat Input

`SANPipeline::step(...)` receives `core.latent()` and calls:

flatten_latent(latent, input_dim)

`flatten_latent(...)` writes a 128D vector from the Rust `LatentState` fields.
Its comments reserve `[76:104]` for Swift-filled sensor fusion, but that function
itself does not call `EchelonBridge.getDynamics128()`.

So do not blindly state that SAN consumes the same Swift-overlaid vector as
DiffusionService. Verify the specific source path first.

Practical Layout

The source-supported layout is:

[0:32]      z vector or core dynamics position slots
[32:64]     velocity slots
[64]        norm
[65]        speed
[66]        curvature
[67]        curvature_rate
[68]        jerk
[69]        internal_tempo / 200
[70]        phase
[71]        periodicity
[72]        grounding
[73]        verticality
[74]        rotation
[75]        coherence in Rust flattening; modality mask in Swift overlay
[76:100]    mocopi / sensor fusion area in Swift overlay
[100:102]   pocket IMU in Swift overlay
[102:104]   watch features in Swift overlay
[104:128]   expansion / reserved

Important conflict:

`[75]` is `coherence` in `SANPipeline::flatten_latent(...)`, but
`EchelonBridge.getDynamics128()` overwrites `[75]` with a normalized modality
mask. That means the slot's meaning depends on which vector path produced it.

Mocopi Compression

Source: `MocopiFeatureExtractor.swift`.

The 24D mocopi feature vector is:

[0:3]    COM velocity from hip
[3:6]    spine pitch/roll/twist proxy
[6:20]   seven key joints hip-relative, dx/dy each
[20:24]  joint velocity magnitudes for upper/lower/left/right groups

It also computes six pose stats:

meanX, meanY, stdX, stdY, rangeX, rangeY

Freshness:

• staleness threshold is 0.2 seconds;
• data decays exponentially when stale;
• `isFresh` allows about `stalenessThreshold * 3`.

DiffusionService Overlays

`DiffusionService.buildDynamicsVector(...)` can start from
`EchelonBridge.getDynamics128()`. Then it overlays:

[39:51] activations
[51:63] expressions

Those slots overlap the velocity area. That is intentional for the diffusion/
flow token-generation path, not a universal 128D contract.

ClaimBridge Caveat

In `EchelonBridge.step(dt:)`, ClaimBridge currently receives:

var dynBuf = [Float](repeating: 0, count: 128)
if echelon_get_dynamics_128(b, &dynBuf) == 0 {
    claimBridge.detect(latent: ptr.baseAddress!)
}

That path does not call `getDynamics128()`, so it may not include the Swift
pose/mocopi/watch overlays. If we intend ClaimBridge to use those overlays, this
is a concrete implementation item to fix, not something docs should assume.

SANTrajectoryLogger

`SANTrajectoryLogger` writes JSONL with:

schema_version = 2
dims = 128
input = san_get_flat_input(...)

So the logger records SAN's last flat input, not necessarily every overlay used
by DiffusionService.

CoreML Conditioning Boundary

`DiffusionService` builds a 128D vector, but the current CoreML
`ConditioningEncoder` accepts 104D. The source intentionally truncates:

dynamics[0:104] -> ConditioningEncoder

Correct wording:

> Runtime state is often assembled as 128D, but the current ConditioningEncoder
> path still consumes 104D.

Correct Wording

Use:

> The project has a 128D dynamics convention, but exact slot meanings depend on
> whether the vector came from Rust `dynamics_128`, Swift `getDynamics128()`, SAN
> `flatten_latent`, or DiffusionService's token-generation overlay.

Do not use:

> There is one canonical 128D vector that every subsystem consumes unchanged.

Current Action Item

Unify this contract in code. The clean target is:

one authoritative Dynamics128 builder
  -> SAN
  -> DiffusionService
  -> ClaimBridge
  -> logger

Until then, docs must name the exact producer and consumer for every 128D claim.