📋 resonance: music-of-the-spheres brief — gated on revelation-ω (fable)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

RESONANCE_BRIEF.md

@@ -0,0 +1,105 @@
+# RESONANCE — build brief · 🪐 music of the spheres
+
+> **You are an execution agent (Opus).** Single lane. Read Part 0 of
+> `GODRUM_BRIEF.md` (process root: worktrees, commit style, §0.7 regression,
+> §0.8 report, never-deploy) and the REVELATION amendments — then this file.
+> Fable reviews before merge.
+
+## ⚠ HARD GATE
+
+**Do not branch until the full REVELATION wave (lanes T, W, P, C AND the ω
+closer) has merged to `main`.** This lane edits app-scope `viz/index.html`
+(mod sources, a panel, godspeak grammar) and WOULD COLLIDE with all of them.
+Confirm: `git log --oneline` shows the ω/closer merge; `grep -c wlen
+viz/index.html` ≥ 1 (WHEELS landed); `grep -c testament viz/index.html` ≥ 1.
+If not, STOP and report. All anchors below are names, never line numbers.
+
+Branch: `resonance/spheres` in a worktree (`../godstrument-resonance`).
+
+## R.0 The idea
+
+The Godstrument gains the solar system as a modulation source. SOLARGOD
+(`/Users/m3ultra/Documents/SOLARGOD`, read-only sibling) proved a ~250-line
+dependency-free ephemeris (JPL Standish elements → heliocentric positions,
+verified against Horizons to ~3e-4 AU). Planets become LFOs with periods of
+months to centuries, compressed into musical time. No network, no server
+bridge, no sockets — **the design is vendoring, not streaming**: godstrument
+computes the sky itself, deterministically, at its own clock.
+
+## R.1 The vendored engine — `viz/spheres.js`
+
+Create ONE new file by merging, from SOLARGOD **pinned @ `6391273`**:
+`js/ephem.js` (whole: tables, solver, `helioEcl`) + the minimal `lib.js`
+subset it imports (`centuriesSinceJ2000`, `normDegPM180`, `DEG`, `J2000_JD`,
+`jdFromUnixMs`). Header comment: `// vendored from SOLARGOD@6391273 — do not
+edit; re-vendor to update`. Keep it an ES module; load it from index.html the
+same way the app loads (if the app is one inline IIFE with no module imports —
+it is — add a `<script type="module">` that imports spheres.js and hangs a
+frozen `window.SPHERES = { helioEcl, … }` for the IIFE to consume; guard every
+consumer with `window.SPHERES && …` so the app still boots if the file is
+missing). **Self-check on load** (house style, like `migrateSeq`'s): Mars @ JD
+2461236.5 must be within 0.005 AU of `(1.05351, 1.00863, -0.00470)` — the
+wave-1 Horizons ground truth — else log one console error and disable the
+feature flag.
+
+## R.2 The sources — planets as modulators
+
+New computed dests (study `computeDests` and the existing S&H/mod plumbing
+FIRST; mirror its conventions exactly). For each planet p of the 8 (+ configurable
+Earth-relative pairs), at the CURRENT musical time (see R.3), expose normalized
+0..1 signals:
+
+- `sphere.<p>.phase` — heliocentric longitude λp / 360 (a sawtooth with the
+  planet's year as its period).
+- `sphere.<p>.dist` — (r − r_min)/(r_max − r_min) over that planet's own
+  perihelion..aphelion (eccentricity breathing; Mercury and Mars breathe hard,
+  Venus barely).
+- `sphere.<p>.beat` — 0.5 + 0.5·sin(2π·(λp − λe)/360) — the synodic beat
+  against Earth (Venus–Earth: the 583.9-day pentagram cycle).
+
+Routable exactly like existing mod sources — whatever mechanism computeDests
+uses for its S&H-style sources, spheres are more of the same, not a new
+subsystem.
+
+## R.3 The great-year clock
+
+Real planets are too slow for music. One knob, `spheres.rate`: **1 bar = N
+days** of sky time, log-scaled N ∈ [1, 3650], default 30. Sky JD =
+`J2000_JD + (godtime bars elapsed) · N`, derived ONLY from the master clock
+(`godtime`/`seqPhase` machinery), so scrubbing/tempo changes stay deterministic
+and patch reload reproduces the same sky. At default: Venus' year ≈ 7.5 bars,
+Jupiter's ≈ 144 bars, the Venus–Earth beat ≈ 19.5 bars — slow-arc territory,
+exactly right.
+
+## R.4 The wheel of heaven — WHEELS tie-in
+
+One button in the panel: **"orbital ratios"** — sets the drum lanes'
+`wlen`s to the nearest-integer resonance set 4 : 8 : 16 (Io:Europa:Ganymede's
+1:2:4) and, if ≥5 lanes exist, 8 : 13 (the Venus:Earth orbit ratio — the
+pentagram, in wheel form). Uses WHEELS' shipped API/fields (`wlen`, clamped
+1–16) — pure data pokes + `ungodlyMark` before mutating (UNGODLY convention).
+
+## R.5 The panel & the voice
+
+- Panel `🪐 spheres` (ctxItem + keyboard key if any letter is still free —
+  check the handler; if none, ctxItem only): per-planet row (phase · dist ·
+  beat as live meters), the rate knob, the ratios button, on/off. House style:
+  study `openBeat`/arranger before building.
+- godspeak grammar (post-ε `handleMessage`): `spheres on/off`,
+  `spheres faster/slower`, `<planet> drive <dest>` → route that planet's
+  `.phase` to a dest by the existing routing verb conventions. Follow ε's
+  grammar-table pattern; do not restructure it.
+- Grimoire: ONE short chapter (the manual regenerates via `build_manual.py` —
+  run it, commit both).
+
+## R.6 Verify (§0.7 regression + these)
+
+- Self-check gate green (R.1's Mars check) in console on load.
+- Determinism: set rate N=365, note `sphere.jupiter.phase` at bar 16, reload
+  the patch, re-run → identical to 1e-6.
+- Pentagram: with N=365, measure the `sphere.venus.beat` period in bars —
+  must be 583.9/365 ≈ 1.6 bars ±2%.
+- The ratios button sets the exact `wlen`s and survives `migrateSeq`
+  round-trip; ⌘Z (UNGODLY) reverts it.
+- Zero console errors; `♪ T O B G` + ⌘Z all still work; a patch saved before
+  this feature loads clean (spheres default off).