LUME Reconciliation + Execution Playbook — Mac1 Canonical, Mac4 Patch Source

Mac4: Assets/Lume/Scripts/*.cs                        → Mac1: Assets/Scripts/
Mac4: Assets/Lume/Shaders/*.{shader,compute}          → Mac1: Assets/Shaders/
Mac4: Assets/Lume/Resources/LumeVisualProfiles/*.asset→ Mac1: Assets/Resources/LumeVisualProfiles/
Mac4: Assets/Lume/Editor/*.cs                         → Mac1: Assets/Editor/
Mac4: Assets/Lume/Scenes/LumeMain.unity               → Mac1: (DO NOT overwrite scene; Auto-Wire attaches at runtime)
Mac4: software/scripts/lume-build-mac4-projector.sh   → Mac1: software/scripts/ (verbatim)

iPhone Sony Mocopi
        │ UDP :12351 (native TLV)
        ▼
sensor-relay.js (Mac1, PID 6214)   ← parsed bones live here
        │
        ▼
NEW: sony_to_lumm_bridge.py        ← packs 772-byte LUMM
  OR extend sensor-relay.js          (16-byte header + 27 bones × 28B = 772B)
        │ UDP :9702 LUMM datagram
        ▼
LumeUdpReceiver → LumeMocopiReceiver (Mac1/Mac4 Unity, listens :9702)
        │ in-process skeleton publish
        ▼
LumeSonyMotionBridge (visual reactor — NOT a decoder, NOT an emitter)
LumeMocopiAnimator (humanoid avatar binding)

Bytes 0-3   : magic 0x4C554D4D ("LUMM")
Bytes 4-7   : version + flags (uint32 LE)
Bytes 8-11  : timestamp_ms (uint32 LE)
Bytes 12-15 : bone_count (uint32 LE = 27)
Bytes 16+   : 27 bones × 28 bytes each:
              - position xyz (3 × float32 LE = 12B)
              - quaternion xyzw (4 × float32 LE = 16B)
Total = 16 + (27 × 28) = 16 + 756 = 772 bytes

mocopi index → Sony TLV bone name (basic 17 / pro 27)
0  root        → hip
1  torso_1     → spine_lower
2  torso_2     → spine_upper
3  torso_3     → chest
4  neck_1      → neck
5  head        → head
6  l_shoulder  → l_clavicle
7  l_up_arm    → l_upper_arm
8  l_low_arm   → l_lower_arm
9  l_hand      → l_hand
10 r_shoulder  → r_clavicle
11 r_up_arm    → r_upper_arm
12 r_low_arm   → r_lower_arm
13 r_hand      → r_hand
14 l_up_leg    → l_upper_leg
15 l_low_leg   → l_lower_leg
16 l_foot      → l_foot
17 l_toes      → l_toe       (pro only — basic uses identity fallback)
18 r_up_leg    → r_upper_leg
19 r_low_leg   → r_lower_leg
20 r_foot      → r_foot
21 r_toes      → r_toe       (pro only — basic uses identity fallback)
22 l_low_arm_t → l_wrist     (pro only)
23 r_low_arm_t → r_wrist     (pro only)
24 l_up_leg_t  → l_thigh_t   (pro only)
25 r_up_leg_t  → r_thigh_t   (pro only)
26 spine_4     → upper_chest (pro only)

pos.z = -pos.z
quat.x = -quat.x
quat.y = -quat.y
quat.w = +quat.w

EXECUTION DIRECTIVE — Mac1 Codex pane (W9V + Mac4 absorption + upstream Sony bridge)

Mohamed is offline. Execute the following ladder autonomously. Decisions pre-resolved at [home]/Desktop/evo-cube-output/lume-creative-engine-2026-05-02/STATE-OF-THE-PANES-2026-05-02-EVENING.md §3.

Baseline: Mac1 currently has 13 staged files and `pytest software/demo/tests/ -q` reports 134 passed, 6 skipped. NEVER let test count drop below 134 green. Every step ends with a pytest run.

STEP 0: Commit Mac1's already-staged Wave 9 work locally. Five separate commits, scoped prefixes, NO PUSH:
  Commit 0a [k11]   : NSSM bundle (k11-pipeline.sh rewrite + launchagents/k11/*.ps1 + README.md)
              "[k11] feat: NSSM service bundle for reboot-survivable LUME publishers"
  Commit 0b [W9V]   : LumeFrozenFlow.cs + tests/test_frozen_flow_logic.py + LumePointInstanced.shader SAMPLE_FROZEN_FLOW pragma
              "[W9V] feat(lume): Wave 9.1 — LumeFrozenFlow ring buffer + 18 pytest"
  Commit 0c [W9V]   : LumeKaleidoscope.cs + LumeKaleidoscope.shader + LumeKaleidoscopeFeature.asset + tests
              "[W9V] feat(lume): Wave 9.4 — LumeKaleidoscope URP RendererFeature + tests"
  Commit 0d [W9V]   : ARCHITECTURE.md additive (FrozenFlow exec 228 row, _FrozenFlowField0..3 + _FrozenFlowAges + _FrozenFlowActive globals, SAMPLE_FROZEN_FLOW keyword, component count 21→22, fast tests 73→134, Wave 9V ladder row)
              "[W9V] docs: ARCHITECTURE.md update for FrozenFlow + Kaleidoscope + Wave 9V row"
  Commit 0e [duncan]: software/demo/duncan_v3/*.py + *.sh (skip if Duncan v3 PIDs 31022/31023 still running and writing files — re-run later)
              "[duncan] feat: v3 deep extraction tooling (Gemini native video Files API)"
  After each commit: `git status` clean (or only ignored), `git diff --cached --stat` empty, `pytest -q` ≥ 134 passed.

STEP 1: Pull Mac4's Assets/Lume/ tree into a Mac1 staging folder.
  ssh mac4 'cd Desktop/lume-commerce/software/demo/unity/lume_pcloud && tar czf /tmp/mac4-lume-import.tgz Assets/Lume/ software/scripts/lume-build-mac4-projector.sh' || HOLD
  scp mac4:/tmp/mac4-lume-import.tgz /tmp/mac4-lume-import.tgz
  mkdir -p /tmp/mac4-import && tar xzf /tmp/mac4-lume-import.tgz -C /tmp/mac4-import
  ls -la /tmp/mac4-import/Assets/Lume/Scripts/ /tmp/mac4-import/Assets/Lume/Shaders/ /tmp/mac4-import/Assets/Lume/Resources/LumeVisualProfiles/ /tmp/mac4-import/Assets/Lume/Editor/

STEP 2: Port files into Mac1 canonical paths. ONE LOGICAL COMMIT PER GROUP:

  Group W9M-A: NEW genuinely-Mac4-only files (no Mac1 collision):
    /tmp/mac4-import/Assets/Lume/Scripts/LumeProductionHud.cs        → Assets/Scripts/
    /tmp/mac4-import/Assets/Lume/Scripts/LumeFramePacer.cs           → Assets/Scripts/
    /tmp/mac4-import/Assets/Lume/Scripts/LumeFlowParticleOverlay.cs  → Assets/Scripts/
    /tmp/mac4-import/Assets/Lume/Scripts/LumeFluidFieldRenderer.cs   → Assets/Scripts/
    /tmp/mac4-import/Assets/Lume/Scripts/LumeSonyMotionBridge.cs     → Assets/Scripts/
    /tmp/mac4-import/Assets/Lume/Editor/LumeProductionBuild.cs       → Assets/Editor/
    /tmp/mac4-import/Assets/Lume/Shaders/LumeFluidField.shader       → Assets/Shaders/
    /tmp/mac4-import/Assets/Lume/Resources/LumeVisualProfiles/*.asset→ Assets/Resources/LumeVisualProfiles/
    /tmp/mac4-import/software/scripts/lume-build-mac4-projector.sh   → software/scripts/ (chmod +x)
    Bring corresponding Mac4 .meta files for these (genuinely new asset GUIDs).
    Update namespaces: if Mac4 used `namespace Lume.X.Y`, flatten to flat namespaces matching Mac1 conventions.
    Commit: "[W9M] feat(lume): absorb Mac4 visual stack — Production HUD, FramePacer, FluidFieldRenderer, FlowParticleOverlay, SonyMotionBridge, visual profiles, projector build"

  Group W9M-B: HOT-MERGE files (Mac1 has them, Mac4 has different edits):
    LumePointInstanced.shader   — keep BOTH Mac1's `SAMPLE_FROZEN_FLOW` pragma AND Mac4's visual/Sony-motion additions. All `multi_compile_local` pragmas contiguous.
    LumeVfxEditor.cs            — manual merge: Mac1 base + Mac4 visual-profile picker integrations.
    LumeWaveAutoWire.cs         — manual merge: Mac1 base + Mac4 perf-default preservation + HUD attach + visual profile auto-binding.
    LumeMocopiReceiver.cs       — Mac4's edits stay local-only IF Mac4 introduced changes that affect bone parsing. If only logging/diagnostic, keep Mac1.
    LumeVisualDirector.cs       — manual merge: F1 picker contract + Mac4 perf logging.
    LumeGridTunnelRenderer.cs   — Mac4 edits.
    LumeFluidSim.cs + LumeFluidSim.compute — Mac4 perf tuning (128×128, half-rate, fewer iterations).
    LumeGridTunnel.shader       — Mac4 edits.
    LumeFlowParticleOverlay.shader — Mac4 edits.
    LumeMain.unity              — DO NOT REPLACE. Auto-Wire attaches new components at runtime; only replace scene if Unity import flags missing-script warnings.
    Preserve Mac1 .meta files for all hot-merge files (do NOT clobber Mac1 GUIDs).
    Commit: "[W9M] feat(lume): hot-merge Mac4 visual stack into Mac1 components (shader + auto-wire + fluid + tunnel + picker)"

  Group W9M-C: SKIP — do NOT import these from Mac4:
    Anything in Assets/Lume/ that looks experimental, half-finished, or replaces Wave 8 Mocopi pipeline (Wave 8 must stay intact).
    Mac4's Assets/Editor/Tests/LumeVfxPickerTests.cs — only if it references the new visual-profile picker; otherwise skip (Mac1 baseline tests stand).

STEP 3: Build the upstream Sony→LUMM forwarder.
  Choose ONE path:

  Path A (recommended, simplest): software/demo/sony_to_lumm_bridge.py (~120 lines)
    - Connects to Mac1 sensor-relay's WebSocket ws://[ip]:9400
    - Decodes JSON skeleton frames (sensor-relay parses Sony TLV and emits JSON)
    - Maps bone names per §3.3, applies axis conversion per §3.4
    - Packs 772-byte LUMM (16B header + 27 × 28B bones) per §3.2
    - SendAsync UDP to <unity-host>:9702 (default [ip], override via --host)
    - CLI mirrors mocopi_synth.py: --host, --rate, --verbose
    - 60 Hz output rate

  Path B (faster but mixes responsibilities): patch sensor-relay.js
    - Add a `LumfTarget` class alongside CloudForwarder
    - Same packing logic, in JS
    - Same UDP emit to :9702

  Pick Path A. Reasons: keeps sensor-relay focused on its current job, allows independent testing, Python pack_lumm helper already exists in mocopi_synth.py to copy from.

  Commit: "[bridge] feat: software/demo/sony_to_lumm_bridge.py — Sony bones → LUMM :9702 upstream forwarder"

STEP 4: Tests.
  Add software/demo/tests/test_sony_bridge.py (~120 lines, ~6-8 cases):
    - test_lumm_packet_size: pack a synthetic frame, assert exactly 772 bytes
    - test_lumm_header_magic: bytes 0-3 = b"LUMM"
    - test_lumm_header_bone_count: bytes 12-15 little-endian uint32 = 27
    - test_bone_mapping_basic: 17-sensor input, slots 17/21/22/23/24/25/26 default to identity
    - test_bone_mapping_pro: 27-sensor input, all slots filled from corresponding Sony bones
    - test_axis_conversion: known Sony pose → expected Unity-frame quaternion (numeric assertion within 1e-6)
    - test_smoke_relay_increment: stub sensor-relay JSON, assert packet count increases proportionally
    - test_packet_inspector_compatibility: bridge output decodes cleanly via lume_packet_inspector.py
  Run `pytest software/demo/tests/ -q` — target ≥ 142 passed (134 baseline + 8 new), 6 skipped.
  Commit: "[bridge] test: Sony→LUMM forwarder golden bytes + bone mapping + axis conversion (~8 cases)"

STEP 5: Write Mac1 status report.
  [home-path] per §9 schema. Include: 8 commits made (0a/0b/0c/0d/0e/W9M-A/W9M-B/bridge), pytest counts at each gate, files imported from Mac4 (count + bytes), files SKIPPED from Mac4 (count + reason), files HOT-MERGED (per-file note on what Mac1 kept vs Mac4 added), Mac4 absorption duration, Sony bridge tests result, next-session resume instructions.

STEP 6: Sync canonical Mac1 tree back to Mac4.
  Once all commits land locally on Mac1:
  rsync -avz --delete --exclude='.git' --exclude='Library/' --exclude='Temp/' --exclude='Logs/' \
      Desktop/lume-commerce/software/demo/unity/lume_pcloud/Assets/ \
      mac4:Desktop/lume-commerce/software/demo/unity/lume_pcloud/Assets/
  rsync -avz --exclude='.git' \
      Desktop/lume-commerce/software/demo/sony_to_lumm_bridge.py \
      Desktop/lume-commerce/software/demo/tests/test_sony_bridge.py \
      Desktop/lume-commerce/software/scripts/lume-build-mac4-projector.sh \
      mac4:Desktop/lume-commerce/software/demo/...
  This puts Mac4 on the canonical post-absorption tree without Mac4 ever committing.
  Write completion sentinel: `touch [home-path]`

DON'T-TOUCH:
  • Wave 8 commits 8fb6fe75..da8d1478 — leave intact.
  • Wire format magics — additive only.
  • The 22 component public APIs — additive only.
  • IsoMesh, W9.2 SurfaceNets, W9.3 Pinscreen, MoCapAnything stub — DEFERRED until reconciliation clean.
  • Push, force-push, amend, rebase — NEVER until Mohamed M-1.
  • FirstDate PAT — Mohamed only.
  • Mac4 git operations — Mac4 is patch source, not author.

When Mohamed returns:
  1. Read [home-path]
  2. cd Desktop/lume-commerce && git log --oneline origin/main..HEAD (expect 8 NEW commits)
  3. pytest software/demo/tests/ -q (expect ≥ 142 passed, 6 skipped)
  4. After M-1: git push origin main (single push lands all 8 + the 7 existing Wave 8)
  5. ssh mac4 'cd Desktop/lume-commerce && git pull' — but Mac4 isn't a clean repo, so this may need rsync re-sync from Mac1 instead.

EXECUTION DIRECTIVE — Mac4 Codex pane (verification + projector build only)

Mac4 lume-commerce is not a clean Git repo. You are NOT a Git author. You are a verification + build runner.

Mac1 Codex is the authority. It will rsync the canonical tree to Mac4 once absorption + Sony bridge ship locally on Mac1. Wait for sentinel: poll once per minute via `ls [home-path] 2>/dev/null`.

While waiting, you may do these no-op-on-Git tasks:

WAIT-1 (parallel-safe): Verify free disk.
  df -h ~ | awk 'NR==2 {print $4}'
  If < 8 GiB free, write [home-path] and HOLD. Mohamed is doing M-2.

WAIT-2 (parallel-safe): Verify Sony app target.
  After Mac1 ships sony_to_lumm_bridge.py and Mohamed sets Sony app to point at the host running the bridge (default Mac1), Sony bones land at Mac4:9702 IF Mac4 is the Unity target. Test:
  nc -ul 9702 -w 5 | xxd | head -5
  Look for LUMM magic bytes at offset 0. If none in 5s, write [home-path] and continue with WAIT-3 anyway.

WAIT-3 (parallel-safe): Verify Femto.
  Watch the Femto publisher log for 60s. Count `wait_for_frames > 1000ms` occurrences.
  If > 5 in 60s, write [home-path] with count + timestamp pattern + hypothesis.

After [home-path] sentinel exists:

STEP 1: Sync canonical Mac1 tree.
  rsync -avz --delete --exclude='.git' --exclude='Library/' --exclude='Temp/' --exclude='Logs/' \
      mac1:Desktop/lume-commerce/software/demo/unity/lume_pcloud/Assets/ \
      Desktop/lume-commerce/software/demo/unity/lume_pcloud/Assets/
  rsync -avz \
      mac1:Desktop/lume-commerce/software/demo/sony_to_lumm_bridge.py \
      mac1:Desktop/lume-commerce/software/demo/tests/test_sony_bridge.py \
      mac1:Desktop/lume-commerce/software/scripts/lume-build-mac4-projector.sh \
      Desktop/lume-commerce/software/demo/...
  After sync: ls Desktop/lume-commerce/software/demo/unity/lume_pcloud/Assets/Lume/ should NOT exist (canonical absorbed it). If it does, Mac1 sync was incomplete — write [home-path] and HOLD.

STEP 2: Open Unity, watch import.
  Open Unity Editor on Mac4, point at Desktop/lume-commerce/software/demo/unity/lume_pcloud
  Wait for asset import (5-15 min).
  Verify console:
    - 0 C# compile errors
    - 0 shader compile errors
    - 0 missing-script warnings on LumeMain scene
    - All visual profiles load in LumeVisualProfiles resource folder
  If any errors, screenshot console + write [home-path] and HOLD.

STEP 3: Run software/scripts/lume-build-mac4-projector.sh.
  Verify standalone .app builds under Desktop/lume-mac4-build/.
  If fails, capture log to [home-path] and HOLD.

STEP 4: Launch the .app fullscreen, capture F4 Production HUD screenshot.
  Save to [home-path]
  Verify HUD reports:
    - FPS ≥ 30 target (note actual)
    - Sony LUMM 9702: "active" if Mac1 sony_to_lumm_bridge.py is running and Sony app targets Mac1 (which then forwards LUMM to Mac4:9702 via --host mac4-tailscale-ip)
    - Depth frame age < 100ms typical
    - Live point count ~23k
    - LUMF audio: "active" if audio_pub is running
    - Picker state visible (current visual profile name)

STEP 5: Run pytest on Mac4 to confirm parity.
  cd Desktop/lume-commerce/software/demo && pytest -q
  Target ≥ 142 passed, 6 skipped (parity with Mac1 baseline).
  If diverges, write [home-path]

STEP 6: Femto stutter diagnostic.
  Write [home-path] per §3.8: HUD depth-frame-age readings during stutter, frequency of wait_for_frames > 1000ms, stream restart bound observations, hypothesis on root cause. No code change.

STEP 7: Status report.
  Write [home-path] per §9 schema. Include: pre-flight results (disk + Sony + Femto), import success, build success, HUD verification, test parity, Femto stutter notes.
  Write completion sentinel: `touch [home-path]`

DON'T-TOUCH:
  • Mac4 git operations — Mac4 is NOT a Git author.
  • Push, commit, amend — NEVER from Mac4 under any circumstance.
  • Mac4-local Assets/Lume/ tree — Mac1 will canonicalize and rsync the result.
  • Wire format magics — additive only.

If anything fails, write to [home-path] do NOT retry destructively, idle.

cd Desktop/lume-commerce
git log --oneline origin/main..HEAD                # Verify queued commits
git push origin main                                # Single push, all commits land
ssh mac4 'cd Desktop/lume-commerce && git status' # If not clean repo, rsync from Mac1 instead
ssh k11 'cd /c/lume && git pull origin main'        # K11 pulls (canonical)

[existing] e21ad971  feat(lume): editor auto-wire menu (Wave 1+2+3)
[existing] da8d1478  feat(lume): Wave 8 step 6 — ARCHITECTURE.md + auto-wire integration
[existing] c5194f92  feat(lume): Wave 8 step 5 — LumeChoreographyPanel F2
[existing] 2a6e6b25  feat(lume): Wave 8 step 4 — LumeMotionToAudio (OSC out)
[existing] 95387a02  feat(lume): Wave 8 step 3 — LumeChoreographyScorer + visual coupling
[existing] 8139a931  feat(lume): Wave 8 step 2 — LumePoseSnapshotter + SAMPLE_SNAPSHOTS
[existing] 8fb6fe75  feat(lume): Wave 8 step 1 — mocopi_synth.py + tests

[NEW 0a]   <sha>     [k11] feat: NSSM service bundle for reboot-survivable LUME publishers
[NEW 0b]   <sha>     [W9V] feat(lume): Wave 9.1 — LumeFrozenFlow ring buffer + 18 pytest
[NEW 0c]   <sha>     [W9V] feat(lume): Wave 9.4 — LumeKaleidoscope URP RendererFeature + tests
[NEW 0d]   <sha>     [W9V] docs: ARCHITECTURE.md update for FrozenFlow + Kaleidoscope + Wave 9V row
[NEW 0e]   <sha>     [duncan] feat: v3 deep extraction tooling (Gemini native video Files API)
[NEW W9M-A]<sha>     [W9M] feat(lume): absorb Mac4 visual stack — Production HUD, FramePacer, FluidFieldRenderer, FlowParticleOverlay, SonyMotionBridge, visual profiles, projector build
[NEW W9M-B]<sha>     [W9M] feat(lume): hot-merge Mac4 visual stack into Mac1 components
[NEW b]    <sha>     [bridge] feat: software/demo/sony_to_lumm_bridge.py — Sony bones → LUMM :9702 upstream forwarder
[NEW bt]   <sha>     [bridge] test: Sony→LUMM forwarder golden bytes + bone mapping + axis conversion

# <pane name> — end-of-window status

**Window start:** YYYY-MM-DD HH:MM
**Window end:** YYYY-MM-DD HH:MM
**Pane ID:** <W9V | W9M | P1..P5>

## Ladder steps completed
- [x] STEP 0a: ...
- [x] STEP 1: ...
- [ ] STEP N: BLOCKED — see notes

## Files committed (sha + message)
## Files modified but NOT committed (path + reason)
## Files imported from Mac4 (count + bytes + destination)
## Files SKIPPED from Mac4 (count + reason)
## Files HOT-MERGED (per-file: what Mac1 kept + what Mac4 added)
## Tests
- pytest: N passed, M skipped, K failed (specify failures)
- Unity edit-mode: N green / M total
## Failures encountered
## Audit answers (W9V/W9M-specific Q&A)
## Time spent (wall-clock)
## Next-session resumption instructions