docs: add BraidTree-Octree-COUCH synthesis spec

Unified spatial-topological-dynamic system combining octree spatial
subdivision (Euclidean), BraidTree interaction topology (Artin B8),
and COUCH chaotic oscillator dynamics into a single formal framework.

Includes Lean structure definitions, adaptive refinement strategy,
rendering pipeline, subdivision theorem, and FAMM gate boundary
checker. All Q16_16 fixed-point, no floats.

specs/braidtree_octree_couch_synthesis.md

@@ -0,0 +1,223 @@
+# BraidTree-Octree-COUCH Synthesis
+
+Spatial-Topological-Dynamic System = (Octree, BraidTree, COUCH, Φ)
+
+Where:
+- **Octree**: Spatial subdivision (Euclidean)
+- **BraidTree**: Topological interaction hierarchy (Artin B₈)
+- **COUCH**: Chaotic coupled oscillator dynamics
+- **Φ**: Composition law mapping between layers
+
+---
+
+## 1. Layer 1: Octree Spatial Base
+
+Standard octree structure:
+
+    Octree node = (cube: ℝ³, children: 8 × OctreeNode ∪ Leaf)
+
+Leaf node contents (enhanced from PlenOctrees):
+
+    Leaf = {
+      spatial_bound: ℝ³,           -- Cube volume
+      density: Q16_16,             -- Density field
+      fourier_coeffs: List Q16_16, -- Spectral basis
+      couch_state: COUCHState,     -- Oscillator dynamics
+      braid_address: BraidNodeRef  -- Topological mapping
+    }
+
+Key enhancement: Each octree leaf carries both Fourier coefficients AND a COUCH oscillator state.
+
+---
+
+## 2. Layer 2: BraidTree Topological Overlay
+
+BraidTree as interaction graph over octree leaves:
+
+    BraidNode = {
+      spatial_leaves: Set OctreeLeaf,  -- Leaves in this topological cluster
+      dual_quaternion: DQ,             -- Rigid motion frame
+      phase_vec: PhaseVec,             -- Q0_2 phase state
+      coupling_regime: CouchCouplingRegime,  -- κ parameter
+      children: 4 × BraidNode ∪ Leaf   -- Hierarchical topology
+    }
+
+**Mapping rule:** Spatially adjacent octree leaves with similar COUCH dynamics get grouped into the same braid node.
+
+Why this matters: Instead of subdividing purely by geometry ("this cube is too complex"), you subdivide by topology ("these oscillators have different interaction patterns").
+
+---
+
+## 3. Layer 3: COUCH Dynamics per Braid Cluster
+
+COUCH equation at braid node level:
+
+    ẍ_i + γẋ_i + ω_i²x_i + Σ_j κ_ij(x_i - x_j) = F(t)
+
+Discretized for hardware:
+
+```lean
+structure BraidCOUCHState where
+  oscillators : Fin 8 → DQ           -- Oscillator frames as dual quaternions
+  coupling    : Fin 8 → Fin 8 → Q0_2 -- Discretized coupling matrix
+  phase       : PhaseVec              -- Q0_2 phase state
+  apartment_bound : Q16_16            -- R_wall constraint
+  hysteresis_H   : Q16_16            -- Path-dependent memory
+```
+
+Key insight: Each braid node represents a cluster of coupled oscillators that share similar dynamics. The octree tells you where they are; the braid tree tells you how they interact.
+
+---
+
+## 4. Composition Law: Φ
+
+The mapping between layers:
+
+    Φ: Octree × BraidTree × COUCH → UnifiedState
+
+### Spatial-to-Topological mapping
+
+    Φ_spatial_to_braid(leaf: OctreeLeaf): BraidNodeRef =
+      -- Find braid node containing this leaf
+      -- Based on interaction topology, not spatial proximity
+
+### Topological-to-Dynamic mapping
+
+    Φ_braid_to_couch(node: BraidNode): COUCHState =
+      -- Extract oscillator states from braid node
+      -- Compute coupling matrix from braid crossings
+      -- Apply apartment boundary constraints
+
+### Dynamic-to-Spectral mapping
+
+    Φ_couch_to_fourier(state: COUCHState): List Q16_16 =
+      -- Factor out rigid motion via dual quaternions
+      -- Residual signal → Fourier coefficients
+      -- Update spectral basis based on hysteresis H
+
+---
+
+## 5. Adaptive Refinement Strategy
+
+**Standard octree refinement:**
+
+    if fourier_error > threshold:
+      subdivide_spatially()
+
+**BraidTree-enhanced refinement:**
+
+    if fourier_error > threshold OR couch_coupling_regime_changed():
+      if topological_interaction_changed():
+        subdivide_braid_node()  -- New interaction pattern
+      else:
+        subdivide_octree_leaf()  -- Same topology, more spatial detail
+
+### Why this is better
+
+| Scenario | Behavior |
+|----------|----------|
+| Cloth moving | Same interaction topology → refine octree only |
+| Cloth tearing | Topology changes → refine braid tree first |
+| Smoke dissipating | Coupling strength κ changes → update COUCH regime |
+
+---
+
+## 6. Rendering Pipeline
+
+Ray marching through the unified structure:
+
+    Ray traversal:
+      1. Enter octree node (spatial query)
+      2. Lookup braid node (topological context)
+      3. Retrieve COUCH state (dynamics)
+      4. Compute radiance:
+         a. Apply dual quaternion transform (rigid motion)
+         b. Evaluate Fourier basis (appearance)
+         c. Modulate by density (from COUCH)
+      5. Check apartment boundary (FAMM gate)
+      6. If boundary hit, apply hysteresis correction
+      7. Accumulate sample
+
+Key advantage: The ray carries both spatial and topological context, enabling richer appearance modeling.
+
+---
+
+## 7. Concrete Lean Structure
+
+```lean
+structure UnifiedBraidOctreeCouch where
+  octree_root : OctreeNode
+  braid_root  : BraidNode
+  couch_states : BraidNodeRef → COUCHState
+  spatial_to_braid : OctreeLeaf → BraidNodeRef
+  braid_to_couch   : BraidNode → COUCHState
+  couch_to_fourier : COUCHState → FourierBasis
+  compose : OctreeNode → BraidNode → COUCHState → UnifiedNode
+
+structure UnifiedNode where
+  spatial_bound    : ℝ³
+  dual_quaternion  : DQ
+  phase_vec        : PhaseVec
+  fourier_coeffs   : List Q16_16
+  density          : Q16_16
+  coupling_regime  : CouchCouplingRegime
+  hysteresis_H     : Q16_16
+```
+
+---
+
+## 8. Adaptive Subdivision Theorem
+
+**Theorem:** For any dynamic scene with motion topology T, there exists a braid-enhanced octree that achieves rendering accuracy ε with fewer nodes than a pure spatial octree.
+
+*Proof sketch:*
+1. Group regions by interaction topology (braid clustering)
+2. Within each topological cluster, use Fourier basis for appearance
+3. Only subdivide spatially when topology changes
+4. Topology changes are rarer than spatial complexity changes
+5. Therefore, fewer total nodes needed
+
+---
+
+## 9. FAMM Gate as Unified Boundary Checker
+
+```lean
+def unifiedFammGate (node : UnifiedNode) : Bool :=
+  -- Spatial boundary
+  let spatial_ok := node.spatial_bound.within_apartment()
+  -- Topological boundary
+  let topological_ok := node.phase_vec.kappa_raw ≤ 49152
+  -- Dynamic boundary (COUCH apartment constraint)
+  let dynamic_ok := node.dual_quaternion.translationDistance() < node.apartment_radius
+  -- Hysteresis check
+  let hysteresis_ok := node.hysteresis_H < H_critical
+  spatial_ok && topological_ok && dynamic_ok && hysteresis_ok
+```
+
+---
+
+## 10. Benefits of Synthesis
+
+| Aspect | Pure PlenOctree | Pure BraidTree | Pure COUCH | Unified |
+|--------|----------------|----------------|------------|---------|
+| Spatial locality | ✅ | ❌ | ❌ | ✅ |
+| Topology awareness | ❌ | ✅ | ❌ | ✅ |
+| Motion history | ❌ | ✅ | ❌ | ✅ |
+| GPU-friendly layout | ✅ | ❌ | ❌ | ✅ |
+| Spectral compression | ✅ | ❌ | ❌ | ✅ |
+| Chaos dynamics | ❌ | ❌ | ✅ | ✅ |
+| Formal verification | ❌ | ❌ | ❌ | ✅ |
+| Hardware discretization | ❌ | ✅ | ❌ | ✅ |
+
+### Summary
+
+BraidTree-Octree-COUCH System = A hierarchical spatial-topological-dynamic structure where:
+
+- **Octree** provides Euclidean spatial subdivision
+- **BraidTree** organizes regions by interaction topology (Artin B₈ with dual quaternions)
+- **COUCH** models chaotic coupled oscillator dynamics per topological cluster
+- **Fourier basis** represents appearance within each cluster
+- **FAMM gate** enforces unified boundary constraints (spatial + topological + dynamic)
+- **Adaptive refinement** responds to both spatial complexity AND topological changes
+
+The result is a topology-aware Fourier radiance field where subdivision is driven by interaction patterns rather than just geometry, with rigorous mathematical foundations from all three systems. The braid group handles the *how things move* question, the octree handles the *where things are* question, and COUCH handles the *how they behave chaotically* question — all unified in a single formal framework.