106 lines
5.4 KiB
Markdown
106 lines
5.4 KiB
Markdown
# 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).
|