Metabolism: rule program, song-driven life, tribe VMs; M2.7 design (strains & allegiances, living wells)

metabolism/DESIGN.md

@@ -99,18 +99,36 @@ the angle (12 semitones → 12 sectors), strength picks how much food and how
 wide. The track's rhythm is literally folded into the geometry of the food.
 
 ### Field — food
-Events splat resource onto a 128×128 grid. On top of that, **wells** — slow,
-permanent fertile places — are placed by the track's own harmony: one well per
-strong pitch class, on two rings, with richness proportional to the chroma
-and the band balance. The chord is the map. Wells recharge slowly to a
-ceiling, so a place has a carrying capacity, not an infinite tap.
+Events splat resource onto a 128×128 grid. On top of that, **wells** — small,
+fertile places with a life of their own. There are many of them (8–16) and
+each is small and weak: a tight kernel, a modest recharge rate, no single well
+rich enough to carry a world — the same total fertility budget the old
+permanent springs had, spread thin. Where wells come from and when they go is
+the track's own harmony:
+
+- **birth** — a well sprouts where a pitch class enters the music and *holds*
+  (sustained chroma energy, seeded by the events that already landed there);
+- **drift** — a well wanders slowly with its harmony, pulled along the
+  smoothed pitch/centroid path, and the creatures anchored to it follow;
+- **death** — when a pitch class leaves the song, its well starves: the
+  recharge fades, the kernel decays, the colony must abandon it.
+
+The chord does not just draw the map — it runs the map's *history*. Wells are
+the story's spine: founding, settlement, exodus, migration, collapse. Each has
+an audible cause and a visible one, and each lasts long enough to be followed.
+The whole lifecycle is compiled at analysis time into a deterministic **well
+timeline** (birth, path, death per well); the sim only plays it back. Wells
+are also where bodies meet: everyone needs them, so a well is the natural
+front between macro-organisms — and its death is a retreat, its birth a
+land-rush.
 
 ### Graph — relations
-The 3×3 correlation matrix of the three band envelopes becomes the species'
-*interaction matrix*: bands that move together attract; a band that lives its
-own life repels the others. For a bass line that locks with the kick, the
-builders court the foragers; for a high band that does its own thing, the
-sparks are ostracised. Society is a property of the mix.
+The band-envelope correlation matrix now works at two scales. It decides the
+**division of labour** — which strain motifs complement which, so a bass line
+locked with the kick pairs diggers with haulers — and it feeds the
+**diplomacy**: the harmony the track sustains maps to how bodies treat each
+other, truce and trade versus skirmish and siege. Society is a property of
+the mix, at both scales.
 
 ### Law — regime per section
 Section boundaries are found where the 4 Hz feature cloud changes its mind
@@ -132,39 +150,60 @@ The genome maps the summary statistics to *kinds of behaviour*:
 | flatness ↑ | jitter ↑ | noisy track = jittery creatures |
 | flatness ↓ | trail half-life ↑, deposit ↑ | tonal track = heavy ground markings |
 | beat strength | alignment and pace | a pulse makes them march |
-| band correlations | interaction matrix | correlated bands attract |
+| band correlations | division of labour | complementary voices breed complementary strains |
 | onset density | separation, split cost | dense track = thronged dish but crowded apart |
 | spectral tilt | hue | bright mixes warm, dark mixes cold |
 
-There are three castes, derived from the three voices:
+There are no castes and no tribes. There is **one population** — a single
+density field — and every organism in it carries two properties:
 
-- **builder** — slow, heavy, deposits a lot, keeps near its well. It is the
-  ink-dropper of the world: it paints the structure the synth earned.
-- **forager** — commutes between wells and draws the roads. Direction lives
-  in its streaks.
-- **spark** — small, fast, orbits wide, deposits almost nothing. The counter-
-  melody: it makes the film read as inhabited rather than decorated.
+**Personality — the strain.** The song decides how many kinds of minds its
+world needs (*m*, read from how many independent voices the mix resolves
+into, bounded by arrangement depth, jittered by the seed) and compiles a
+**LittleVM program for each strain**: grazer, builder, sentinel, scout,
+breeder — each with its own senses (food, densities, trail, law, hunger, rim,
+well proximity and liveliness, body presence), registers as memory, real
+branching, and actions (move, graze, excrete, hit, spawn, follow, patrol).
+The population is a *mix* of strains the way a biofilm is: specialists
+working the same ground. And the mix is itself alive — strains that eat and
+grow where they are propagate locally; proportions shift district by
+district. The film shows specialisation *evolving* inside one species.
+
+**Allegiance — the body.** Every organism also belongs to a macro-organism —
+its **body** — a polity of mixed strains that builds, defends and expands as
+one. Allegiance is a *field*: the population's composition per cell, advected
+frozen-in with the organisms as they move. And it changes:
+
+- **conversion** — at a contested front the stronger body captures ground and
+  converts the locals;
+- **defection** — when a body's presence collapses (its food gone, its ground
+  lost), its members flip to the neighbouring body;
+- **fission** — a coherent splinter cut off from its body, blessed by a strong
+  onset, is founded as a new body with a new colour;
+- **merger** — two bodies whose members fully intermix under a cooperative
+  regime become one.
+
+Bodies are few — the song opens 2–4, capped at ~8 so colour stays legible —
+and they are the drama. The film is the story of macro-organisms **fighting
+and cooperating**: skirmish lines at fronts, truces in consonant sections,
+symbiosis where one body's waste is another's food. The song sets the terms
+of diplomacy: consonant, harmonically locked material breeds symbiosis;
+dissonant, decorrelated material breeds rivalry; drops are expansion wars;
+breakdowns are truces and mutual building.
 
 A species name like "fast tonal weaver" falls out of the genome, so the report
 can talk about the world and not the track.
 
 ## The world
 
-A fixed-step simulation (~2600 typed, garbage-free agents; spatial hash for
-neighbourhood; every RNG stream seeded). Per frame:
-
-1. inject this frame's events — food is placed, and strong events also
-   *spawn* life and leave a **ring** on the ground (the clearest causality in
-   the film);
-2. decay field and trails; recharge wells (rate set by the section's law);
-3. each agent: smell the food gradient, obey its caste's relation to its well,
-   feel its neighbours (separate / align / cohere / inter-caste attraction),
-   wander with jitter, hit soft walls, eat, move, lay ink, split on
-   accumulation, die on starvation;
-4. compact.
-
-There is no player, no realtime budget, no entity objects — only typed arrays,
-a step function, and a history we can regress against the song.
+A fixed-step, garbage-free simulation over typed arrays: every RNG stream
+seeded, every update a pure function of the previous substep. The course
+correction (**EVOLUTION.md**) replaces the entity ecology with a
+**population-field** ecology — the same front-end (events place food, wells
+born from and living by the chord, laws at section boundaries) feeding
+*density* instead of discrete agents, stepped several times per rendered frame so macro patterns
+form. Nothing here is realtime: no player, no clock, no allocation — typed
+arrays, a step function, and a history we can regress against the song.
 
 ## The lens
 
@@ -228,6 +267,10 @@ What will be previewed is exactly what will be exported.
 
 ## Build order & status
 
+*Course-corrected in **EVOLUTION.md** — read it before touching the world or the
+rules. The front-end (analysis → events → field → laws → palette) stands; the
+world behind the `Run` is being rebuilt.*
+
 - **v0 — substrate** ✔ one song, one species, alive on the dish.
   *Built:* analysis → structures → world → renderer → filmstrips, metrics,
   15 tests green.
@@ -237,14 +280,33 @@ What will be previewed is exactly what will be exported.
 - **v2 — story** laws switch at section boundaries (done in the world);
   event-reactive camera cutting (done in camera.js); filmstrip + report tools
   wired.
-- **v3 — search** rule-space search with the coupling × residual fitness —
-  only after the substrate exists, and only as a sampling tool, never as a
-  user-facing knob.
+- **M1 — macro world** (EVOLUTION.md) replacing the entity sim with a
+  population-field sim: `FIELD=128` density grid (rendered at 256² texture),
+  `SUBSTEPS` per frame, coarse-grid forces, home basins, speck-swarm rendering
+  ("billions" as texture), song-specific openings. The invariants, determinism
+  and the `Run` interface survive.
+- **M2 — rule program** ✔ the genome/laws become a compiled, declarative
+  per-song rule program: castes as rule entries (mutualism, social floors),
+  interaction rules, per-section operator regimes (structural section
+  changes), the event→response mapping, and a shared carrying capacity.
+- **M2.7 — one species, many minds** *(designed, not yet built — see
+  EVOLUTION.md)*: tribes/castes are dissolved into a single population field
+  with two live properties — a **strain mix** of song-compiled LittleVM
+  personalities evolving by local selection, and an **allegiance field**
+  whose macro-organisms ("bodies") convert, defect, fission and merge,
+  fighting or cooperating as the song's harmony and sections dictate — on top
+  of the living well timeline.
+- **M3 — lens** the camera travels (track / reveal / establish) and reserves
+  cuts for musical punctuation.
+- **M4 — film** mux frames + PCM to video.
 
 ## Current state, honestly
 
 The world is alive and the songs diverge on the metrics, but it is not yet a
-*film*: the camera and the soundtrack are not muxed, the renderer is a proof
-at 480p, and the three reference tracks are synthetic test signals rather than
-music. The next milestone is three videos — one per song — that a person can
-sit through and tell apart without the report.
+*film*: the renderer is a software-framebuffer proof, the reference tracks are
+synthetic test signals, the ground the population stands on is still furniture
+(four permanent springs), and the population itself is still three fixed
+castes instead of one evolving mix of minds. M2.7 (EVOLUTION.md) fixes both:
+wells that are born, drift and die; strains — song-compiled LittleVM
+personalities — whose mix adapts by local selection; and allegiances —
+macro-organisms that fight, cooperate, and change membership over time.