CC Window Aligner: Implementation Guide

cc-window-aligner/
├── src/
│   ├── lib.rs                 # Public API: WindowAligner, re-exports
│   ├── types.rs               # MotionWindow, SkeletonFrame, DeviceMask, Provenance
│   ├── config.rs              # WindowConfig, AlignerMode, InterpolationPolicy
│   ├── error.rs               # AlignerError enum
│   ├── stages/
│   │   ├── mod.rs             # Stage trait, StageResult
│   │   ├── time_normalize.rs  # Stage 1: TimeNormalizer
│   │   ├── resample.rs        # Stage 2: Resampler
│   │   ├── coordinate.rs      # Stage 3: CoordinateUnifier
│   │   ├── fusion.rs          # Stage 4: DeviceFuser
│   │   └── windowing.rs       # Stage 5: Windower
│   ├── validation/
│   │   ├── mod.rs             # ValidationResult, Validator trait
│   │   ├── invariants.rs      # Invariant checks (INV-001 through INV-010)
│   │   └── discontinuity.rs   # Discontinuity detection
│   ├── clock/
│   │   ├── mod.rs             # ClockMapping, ClockEstimator
│   │   └── sync.rs            # Multi-device clock synchronization
│   ├── interpolation/
│   │   ├── mod.rs             # Interpolator trait
│   │   ├── linear.rs          # Linear interpolation
│   │   ├── slerp.rs           # Spherical linear interpolation (quaternions)
│   │   └── hold.rs            # Sample-and-hold
│   ├── skeleton/
│   │   ├── mod.rs             # Skeleton definition, BoneIndex
│   │   ├── mocopi.rs          # Mocopi-specific mapping
│   │   └── transform.rs       # Coordinate transformations
│   ├── audit/
│   │   ├── mod.rs             # CausalityTrace, AuditLog
│   │   └── trace.rs           # Trace recording and querying
│   └── buffer/
│       ├── mod.rs             # ReorderBuffer, WatermarkTracker
│       └── ring.rs            # Ring buffer for streaming
├── docs/
│   ├── PROJECT_CHARTER.md
│   ├── GLOSSARY.md
│   ├── INVARIANTS.md
│   ├── IMPLEMENTATION_GUIDE.md
│   └── CHECKLIST.md
├── tests/
│   ├── determinism.rs         # INV-001 tests
│   ├── integration.rs         # End-to-end tests
│   └── stages/                # Per-stage tests
├── benches/
│   └── pipeline.rs            # Latency benchmarks
└── Cargo.toml

pub struct ValidationResult {
    pub passed: bool,
    pub invariant_id: Option<String>,  // e.g., "INV-002"
    pub message: String,
    pub timestamp: f64,
    pub details: HashMap<String, String>,
}

pub struct MotionWindow {
    // Core data
    pub frames: Vec<SkeletonFrame>,      // Exactly config.frames_per_window
    pub latent_frames: Option<Vec<LatentFrame>>,  // From LIM-RPS if available

    // Temporal bounds
    pub t_start: f64,                    // Canonical time (seconds since epoch)
    pub t_end: f64,                      // t_start + (frames_per_window - 1) / fps
    pub fps: f32,                        // Canonical FPS (e.g., 50.0)

    // Coverage & quality
    pub coverage: f32,                   // [0, 1] fraction of non-interpolated
    pub device_mask: DeviceMask,         // Which devices contributed
    pub dropped_frames: Vec<usize>,      // Indices of fully-interpolated frames

    // Provenance
    pub session_id: String,              // Session identifier
    pub window_id: String,               // Deterministic hash
    pub aligner_version: String,         // e.g., "0.1.0"
    pub schema_version: String,          // e.g., "0.1.0"
    pub config_hash: u64,                // Hash of config used

    // Integrity
    pub checksum: u64,                   // xxhash of frames + metadata
}

pub struct SkeletonFrame {
    pub timestamp: f64,                  // Canonical time
    pub bones: [BoneState; 27],          // 27-bone skeleton
    pub root_position: [f32; 3],         // Pelvis position in body frame
    pub provenance: FrameProvenance,     // Per-DOF source tracking
}

pub struct BoneState {
    pub rotation: [f32; 4],              // Unit quaternion (w, x, y, z)
    pub local_position: Option<[f32; 3]>,// For bones with translation
}

pub struct FrameProvenance {
    pub device_mask: DeviceMask,         // Devices contributing to this frame
    pub interpolated: bool,              // True if any DOF interpolated
    pub per_bone_source: [DeviceMask; 27], // Per-bone source
    pub uncertainty: f32,                // [0, 1] aggregate uncertainty
}

#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct DeviceMask(u8);

impl DeviceMask {
    pub const NONE: Self = Self(0x00);
    pub const MOCOPI: Self = Self(0x01);
    pub const PHONE: Self = Self(0x02);
    pub const WATCH: Self = Self(0x04);
    pub const AIRPODS: Self = Self(0x08);
    pub const DEPTH_CAMERA: Self = Self(0x10);

    pub fn contains(&self, other: Self) -> bool;
    pub fn union(&self, other: Self) -> Self;
}

pub struct WindowConfig {
    // Core parameters
    pub canonical_fps: f32,              // e.g., 50.0
    pub frames_per_window: usize,        // e.g., 50 (1 second)
    pub hop_size: usize,                 // e.g., 25 (50% overlap)
    pub min_coverage: f32,               // e.g., 0.9

    // Mode
    pub mode: AlignerMode,               // Strict or LowLatency

    // Clock sync
    pub reorder_buffer_ms: f64,          // e.g., 200.0
    pub clock_drift_threshold: f64,      // e.g., 0.001 (ms/ms)

    // Interpolation
    pub max_interpolation_gap_ms: f64,   // e.g., 100.0
    pub interpolation_policy_version: String, // e.g., "v1"

    // Validation
    pub discontinuity_threshold_deg: f32,// e.g., 45.0
    pub max_velocity_deg_s: f32,         // e.g., 720.0

    // Versioning
    pub schema_version: String,          // e.g., "0.1.0"
}

pub enum AlignerMode {
    Strict,       // Determinism > latency
    LowLatency,   // Responsiveness > determinism
}

#[derive(Debug, thiserror::Error)]
pub enum AlignerError {
    #[error("Invariant violated: {invariant_id} - {message}")]
    InvariantViolation {
        invariant_id: String,
        message: String,
    },

    #[error("Clock synchronization failed for device {device}: {reason}")]
    ClockSyncFailed {
        device: String,
        reason: String,
    },

    #[error("Insufficient coverage: {actual} < {required}")]
    InsufficientCoverage {
        actual: f32,
        required: f32,
    },

    #[error("Invalid configuration: {field} - {reason}")]
    InvalidConfig {
        field: String,
        reason: String,
    },

    #[error("Discontinuity detected at t={timestamp}: {description}")]
    Discontinuity {
        timestamp: f64,
        description: String,
    },

    #[error("Schema version mismatch: expected {expected}, got {actual}")]
    SchemaVersionMismatch {
        expected: String,
        actual: String,
    },
}

pub struct WindowAligner {
    config: WindowConfig,
    // ... internal state
}

impl WindowAligner {
    /// Create a new aligner with the given configuration
    pub fn new(config: WindowConfig) -> Result<Self, AlignerError>;

    /// Process a raw packet from a device
    pub fn ingest(&mut self, packet: RawPacket) -> Result<(), AlignerError>;

    /// Poll for ready windows (non-blocking)
    pub fn poll(&mut self) -> Option<MotionWindow>;

    /// Flush remaining data (end of stream)
    pub fn flush(&mut self) -> Vec<MotionWindow>;

    /// Get current watermark (canonical time)
    pub fn watermark(&self) -> f64;

    /// Get aligner statistics
    pub fn stats(&self) -> AlignerStats;

    /// Enable causality tracing
    pub fn enable_tracing(&mut self, sink: Box<dyn TraceSink>);
}