Godstrument/RESONANCE_BRIEF.md

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' wlens 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 wlens 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).