CC Window Aligner: Assumptions & Invariants Ledger

CC Window Aligner: Assumptions & Invariants Ledger

Version: 0.1.0
Status: DRAFT
Last Updated: 2025-12-27

---

1. Assumptions

Assumptions are conditions the system relies on that could be false. Each assumption includes detection and mitigation strategies.

---

ASM-001: Clock Stability

Assumption: Device clocks have bounded drift (< 1ms/second) and do not jump discontinuously during a session.

What breaks if false: Clock mapping becomes invalid. Canonical timestamps lose meaning. Resampling produces incorrect values.

Detection:
- Monitor clock mapping residuals over time
- Detect if drift estimate changes by > 0.1ms/s within a window
- Flag sessions where clock jumps are detected

Mitigation:
- Re-estimate clock mapping when drift exceeds threshold
- Insert discontinuity marker and start new alignment epoch
- Warn downstream consumers

---

ASM-002: Network Ordering Boundedness

Assumption: Out-of-order packets arrive within a bounded delay window (configurable, default 200ms).

What breaks if false: Watermark advances too early. Frames are emitted missing late-arriving data. Determinism is violated.

Detection:
- Track maximum observed out-of-order delay per stream
- Alert if observed delay exceeds configured bound

Mitigation:
- Increase reordering buffer size for affected streams
- In strict mode, wait longer before emitting

---

ASM-003: Device Mounting Consistency

Assumption: Devices are mounted in known locations (mocopi as specified, phone in pocket, watch on wrist) with consistent orientation.

What breaks if false: Coordinate transformation produces incorrect body frame. Fusion combines incompatible data.

Detection:
- Cross-validate inferred pose across devices
- Detect if device contributions are geometrically inconsistent

Mitigation:
- Allow per-session mounting offset overrides
- Flag sessions with detected mounting anomalies

---

ASM-004: Skeleton Definition Stability

Assumption: The mocopi 27-bone skeleton definition matches the canonical CC skeleton.

What breaks if false: Bone indices are misaligned. Parent-child relationships break. Forward kinematics fails.

Detection:
- Validate incoming skeleton against expected bone count and hierarchy
- Reject packets with unexpected structure

Mitigation:
- Mapping layer can transform between skeleton definitions if needed
- Version the skeleton definition

---

ASM-005: Interpolation Validity

Assumption: Linear/slerp interpolation over gaps ≤ 100ms produces physically plausible intermediate values.

What breaks if false: Interpolated frames contain impossible poses. Downstream models receive invalid inputs.

Detection:
- Track gap durations before interpolation
- Flag frames where interpolation spans exceed threshold

Mitigation:
- Mark large-gap interpolations with uncertainty
- Increase coverage penalty for long interpolations

---

2. Invariants

Invariants are conditions that must never be violated. Each invariant includes detection (canary) and consequences.

---

INV-001: Determinism

Statement: Given identical raw input packets and identical configuration, the aligner produces bit-identical MotionWindows.

Why it exists: Replay stability. Training reproducibility. RAG++ embedding consistency. Scientific validity.

What breaks if violated:
- Training cannot be reproduced
- MotionPhrase library becomes inconsistent
- RAG++ retrieval drifts silently
- Debugging becomes impossible

Canary (detection):
- Checksum verification: `hash(MotionWindow) == expected_hash`
- Run reference sessions through aligner on different machines
- Compare output byte-by-byte

Enforcement:
- No floating-point non-determinism (fixed rounding, ordered operations)
- No randomness without explicit seed
- No time-dependent behavior (use canonical time only)
- Frozen interpolation policies

---

INV-002: Boundedness

Statement: Every emitted MotionWindow has exactly `config.frames_per_window` frames, spanning exactly `(frames_per_window - 1) / config.canonical_fps` seconds.

Why it exists: Downstream modules assume fixed window size. Variable windows break batching, indexing, and model inputs.

What breaks if violated:
- cc-anticipation receives unexpected input shape
- RAG++ embeddings have inconsistent dimensions
- Training batches fail

Canary (detection):
- Assert `window.frames.len() == config.frames_per_window` on every emission
- Assert `window.t_end - window.t_start == expected_duration` within epsilon

Enforcement:
- Never emit partial windows
- Pad with interpolated frames if necessary (marked as interpolated)
- Validate at emission point

---

INV-003: Explicit Missingness

Statement: If raw data is missing or interpolated, this is explicitly marked in the output. No silent gap-filling.

Why it exists: Downstream modules need to know data quality. Silent interpolation causes hidden model drift.

What breaks if violated:
- LIM-RPS updates on hallucinated data
- Conductor makes decisions on uncertain information
- Training on synthetic data without knowing it

Canary (detection):
- Inject known dropouts in test sessions
- Verify provenance reflects the dropout
- Verify coverage reflects the gap

Enforcement:
- Provenance per frame is mandatory
- Interpolation flag is mandatory for non-raw frames
- Coverage computation is deterministic

---

INV-004: Temporal Monotonicity

Statement: Frame timestamps within a MotionWindow are strictly increasing: `t[i] < t[i+1]` for all consecutive frames.

Why it exists: Physics requires causality. Derivatives assume ordered time.

What breaks if violated:
- Velocity/acceleration computation produces garbage
- LIM-RPS dynamics become unstable
- Replay desynchronizes

Canary (detection):
- Assert `window.frames[i].timestamp < window.frames[i+1].timestamp` for all i

Enforcement:
- Resampler produces frames at deterministic, increasing canonical times
- Never reorder frames after resampling

---

INV-005: Coordinate Consistency

Statement: All skeletal data in a MotionWindow is expressed in the canonical BodyFrame with consistent bone indexing and quaternion conventions.

Why it exists: Downstream modules assume consistent coordinates. Mixed conventions cause silent geometric errors.

What breaks if violated:
- Poses appear mirrored, rotated, or scaled incorrectly
- Joint angles are inverted
- Trained models fail on live data

Canary (detection):
- Validate quaternion hemisphere consistency
- Cross-check against known reference poses
- Verify bone hierarchy produces expected FK results

Enforcement:
- Explicit coordinate transformation stage
- Quaternion hemisphere normalization
- Skeleton mapping validation

---

INV-006: Schema Version Match

Statement: MotionWindow `schema_version` must match the consuming module's expected version.

Why it exists: Schema changes can silently break consumers. Version mismatch must be loud.

What breaks if violated:
- Consumers parse fields incorrectly
- Missing fields cause crashes
- Semantic changes cause silent bugs

Canary (detection):
- Consumer checks `window.schema_version` before processing
- Reject windows with unknown versions

Enforcement:
- `schema_version` is mandatory, non-optional
- Major version changes are breaking
- Consumers validate on receipt

---

INV-007: Checksum Validity

Statement: `window.checksum == hash(window.frames + window.metadata)` for all emitted windows.

Why it exists: Detects corruption in storage, transmission, or processing.

What breaks if violated:
- Corrupted windows enter the pipeline undetected
- Training on corrupted data
- Replay produces different results

Canary (detection):
- Recompute checksum on load
- Compare to stored checksum

Enforcement:
- Compute checksum deterministically at emission
- Include in window metadata

---

INV-008: Provenance Completeness

Statement: Every frame in a MotionWindow has complete provenance metadata indicating source devices and interpolation status for all degrees of freedom.

Why it exists: Enables quality-aware downstream processing. Required for coverage computation.

What breaks if violated:
- Cannot distinguish real from interpolated data
- Coverage is incorrect
- Quality-weighted decisions fail

Canary (detection):
- Assert `frame.provenance.is_complete()` for all frames
- Validate provenance device mask matches expected devices

Enforcement:
- Fusion stage populates provenance for all outputs
- Provenance is non-optional

---

INV-009: No Future Data

Statement: Frame F at canonical time T never incorporates raw data from any device with canonical timestamp > T.

Why it exists: Causality. Real-time operation. Prevents non-causal filtering.

What breaks if violated:
- Real-time mode is impossible
- Replay differs from live
- Anticipation becomes cheating

Canary (detection):
- Log raw packet timestamps contributing to each frame
- Verify all contributors have timestamp ≤ frame timestamp

Enforcement:
- Interpolation uses only past and present samples
- Resampling is causal (lookback only for live mode)

---

INV-010: Window ID Determinism

Statement: `window.window_id` is a deterministic hash of (session_id, t_start, config_version). Same inputs produce same ID.

Why it exists: Enables deduplication. Enables causality tracing. Enables replay verification.

What breaks if violated:
- Same window gets different IDs on replay
- Causality trace becomes unreliable
- Deduplication fails

Canary (detection):
- Replay session, verify same window IDs

Enforcement:
- ID computation is deterministic function of invariant inputs
- No randomness, no wall-clock time

---

3. Invariant Validation Summary

---

Document ID: CC-WA-INVARIANTS-001
Previous Document: GLOSSARY.md
Next Document: IMPLEMENTATION_GUIDE.md