cc-anticipation: Project Charter

cc-anticipation: Project Charter

Document Version: 0.1.0
Created: 2025-12-26
Status: Phase Zero - Active
Canonical Input: [Anchor.md](../../../../docs/Anchor.md)

---

1. Mission Statement

cc-anticipation converts stabilized motion state into actionable anticipatory signals. It answers one question: "What futures are cheap vs expensive given what's happening now?"

It does not generate motion. It does not generate sound. It does not decide policy.
It measures the geometry of possibility around the present moment.

---

2. Scope Boundaries

2.1 In Scope

2.2 Out of Scope

2.3 Interface Contracts

INPUT:  MotionWindow (from cc-window-aligner)
        ├── SkeletonFrame[] (optional)
        ├── LatentFrame[] (optional)
        ├── fps, window_length, coverage
        └── window_id (deterministic hash)

OUTPUT: AnticipationPacket
        ├── scalars: commitment, uncertainty, transition_pressure,
        │            recovery_margin, phase_stiffness, novelty, stability
        ├── vectors: regime_embedding, constraint_vector, derivative_summary
        └── debug: raw_features, neighbor_ids, intermediate_scores

---

3. Success Criteria

3.1 Determinism (Non-Negotiable)

• [ ] Same MotionWindow + same config → identical AnticipationPacket bytes
• [ ] Replay of recorded session produces checksum-identical packets
• [ ] No floating-point nondeterminism in feature computation

3.2 Behavioral Tests

3.3 Integration Tests

• [ ] AnticipationPacket feeds Conductor policy signals correctly
• [ ] regime_embedding queries RAG++ MotionPhrase index successfully
• [ ] coverage < threshold → packet refused or marked degraded

---

4. Architecture Position

Sensors → cc-mcs-headless → cc-window-aligner → [cc-anticipation] → Conductor
                                     ↓                    ↓
                              (MotionWindow)      (AnticipationPacket)
                                                         ↓
                                               RAG++ / MotionGen / MotionStrudel

4.1 Upstream Dependencies

4.2 Downstream Consumers

---

5. Implementation Phases

### Phase v0: Deterministic Rule-Grounded Anticipator
- Kinematic features from skeleton (FK, keypoints, derivatives)
- Latent dynamics from LIM-RPS (dz/dt, d²z/dt²)
- Fixed projection for regime_embedding (no learning)
- Heuristic-based scalar computation
- Full replay determinism
- Behavioral test suite

### Phase v1: Learned Residuals
- Train encoder on MotionPhrase library
- Learn continuation dispersion → uncertainty
- Personalized "tells" from user's movement vocabulary
- Same packet schema, improved accuracy

### Phase v2: RAG++ Integration
- Query MotionPhrase neighbors using regime_embedding
- Retrieved continuation statistics sharpen priors
- Memory-augmented anticipation

---

6. Frozen Schemas

These schemas are immutable once defined. Changes require version bump.

6.1 MotionWindow (Input)

interface MotionWindow {
  window_id: string;           // deterministic hash
  t_start: number;             // canonical time
  t_end: number;
  fps: number;                 // e.g., 50
  frames: (SkeletonFrame | LatentFrame)[];
  coverage: number;            // 0-1
  device_offset: Record<string, number>;
  dropped_reason?: string;
}

6.2 AnticipationPacket (Output)

interface AnticipationPacket {
  // Scalars (control-ready)
  commitment: number;          // 0-1, irreversibility
  uncertainty: number;         // 0-1, continuation dispersion
  transition_pressure: number; // d(commitment)/dt - d(uncertainty)/dt
  recovery_margin: number;     // distance to balance/attractor loss
  phase_stiffness: number;     // how locked to internal metronome
  novelty: number;             // distance from recent regimes
  stability: number;           // local stationarity

  // Vectors (query/conditioning)
  regime_embedding: Float32Array;  // 64-256 dims
  constraint_vector: Float32Array; // ~8 dims
  derivative_summary: Float32Array; // ~8 dims

  // Debug/Telemetry
  debug: {
    raw_features: Record<string, number>;
    neighbor_ids?: string[];
    intermediate_scores: Record<string, number>;
  };

  // Provenance
  window_id: string;
  timestamp: number;
  schema_version: string;
}

---

7. Technology Decisions

---

8. Risk Register

---

9. References

• [Anchor.md](../../../../docs/Anchor.md) - Canonical specification
• [cc-core-rs](../../cc-core-rs/) - Ring buffers, filters, equilibrium solvers
• [rag_plusplus](../../rag_plusplus/) - HNSW index, OutcomeStats
• [RAG_PLUS_PLUS.md](../../cc-trajectory/docs/guides/RAG_PLUS_PLUS.md) - RAG++ architecture

---

Next Document: [GLOSSARY.md](./GLOSSARY.md)