[Tracking/Recovery] Plan: evolving RISC genome as the `giles` controller

[gilesknap]

Tracking + recovery document for the eyes2 evolutionary-genome work. Captures the plan, decisions, current state, and how to resume in a fresh session. Last updated after addressing PR review comments — see "Session state" at the bottom for the live status.

Goal

eyes2 previously had only deterministic demo controllers (random, noop, looker) and never implemented the evolutionary logic of the original 1999 eyes C++ project. Add that as a drop-in Genotype plugin so creatures evolve, plus the original's code tooling (assembler/disassembler/inspector).

Decisions (locked)

1. Fidelity: faithful port of the original RISC byte-code genome (not a modernised redesign). A modernised second genotype is deferred to Add a second, modernised evolvable genotype (non-byte-code design) #6.
2. Placement: fill in the existing giles / sigil 'G' genotype stub.
3. Vision: use eyes2's existing single adjacent-cell Look vision (cached, refreshed after each move) — keep the change contained to the plugin. (Original read 4 cells deep per direction.)
4. PR scope: code + unit tests + docs + headless evolution sanity run.
5. Tooling: delivered as a separate stacked PR (Add giles assembler, disassembler and a TUI inspector #8) on top of Add evolving RISC genome as the giles creature controller #5, as discrete commits (disassembler, then assembler, then TUI inspector).

Design (how the port maps to eyes2)

• Genome = 1000 random bytes interpreted as byte-code for a VM, one instruction per world tick().
• 12 instructions: LOADC, LOADV, ANDV, ORV, JZ, JNZ, MOVV, MOVC, NOP, SAVEV, ADDV, SUBV (values must match the original; see eyes/Engine.h).
• State: accumulator r (u16, wrapping = original WORD), 5 I/O registers I1..I5, instruction pointer.
• Readable variables (18): V1..V8 (8 cached Look cells, encoded empty=0/grass=1/entity=2/wall=4), E, X/Y (dead-reckoning, internal signal), B breed threshold, M mutation rate, I1..I5.
• 16-bit constants little-endian; JZ/JNZ targets relative to the instruction's own address; genome access wraps % CODE_SIZE.
• Reproduction: world (Creature::reproduce) splits energy; genotype halves its own energy estimate (gates re-breed, like random.rs). Mutation probability = evolvable mutation_rate%; per-byte flips + roving copy point (gene duplication); breed_after/mutation_rate evolve and are clamped (rate ≥ 1).
• Async Look: cache [Cell;8]; refresh by emitting Look the tick after each move (and first tick via pending_look).

PR #5 — the genome (branch claude/github-eyes-repos-tadi28)

• RISC VM genotype — eyes2-lib/src/entity/genotype/genotypes/giles/genotype.rs (was giles.rs; folder split happened in PR Add giles assembler, disassembler and a TUI inspector #8)
• VM unit tests; eyes2-lib/tests/evolution.rs headless experiment (#[ignore]d)
• README / TODO / NOTES updated
• Review fix: guard against samples == 0 division in the experiment (commit 7906431)
• Tip: 7906431. CodeRabbit: no actionable comments (clean).
• Headless result (40×40, 50 giles): grows ~50→106 at grass_rate=99, declines ~50→2 at grass_rate=80.
  Run: cargo test --release -p eyes2-lib --test evolution -- --ignored --nocapture

PR #8 — the tooling (branch claude/giles-tooling, base = claude/github-eyes-repos-tadi28)

Stacked on #5. Discrete commits (current tip aa6d779):

1. 37be56b Disassembler — refactor giles into a folder giles/{genotype,isa,asm}.rs; isa.rs is the single source of truth; asm::disassemble; GilesGenotype::disassemble(); public facade eyes2_lib::giles.
2. cdf81ee Assembler — asm::assemble (listing→bytes, comments/addresses/typed AssembleError); disassembler made boundary-safe so the two are exact inverses (property-tested); GilesGenotype::from_genome().
3. 749527f TUI inspector — Genotype::inspect() (+ GenotypeInspect/InspectLine), Creature::inspect() → CreatureInspect on WorldGrid (serde-skip); World creature selection; GUI keys i (open/close), n/p (cycle), . (single-step); overlay shows registers + disassembly with active instruction marked.
4. aa6d779 Review fix: restore genotype config after load — added set_config() to the Genotype trait (default no-op), forwarded from Creature::set_config (called per creature in store.rs load), implemented for giles/random/looker/noop, with a test. Fixes a project-wide latent bug (config was #[serde(skip)], reset to default on load).

• Verification: cargo build --release ✅; cargo test ✅ (22 lib tests; 2 evolution tests ignored); clippy clean for all new code.
• ⚠️ The curses TUI can't run headless, so the inspector is build/clippy/test-verified only (not visually exercised). The asm/disasm core is unit tested.
• CodeRabbit does not auto-review Add giles assembler, disassembler and a TUI inspector #8 (base is non-default branch); it will review once Add giles assembler, disassembler and a TUI inspector #8 retargets to main.

How to resume in a fresh session

1. git fetch origin. Branches: claude/github-eyes-repos-tadi28 (PR Add evolving RISC genome as the giles creature controller #5, tip 7906431) and claude/giles-tooling (PR Add giles assembler, disassembler and a TUI inspector #8, tip aa6d779, stacked on Add evolving RISC genome as the giles creature controller #5).
2. Merge order: land Add evolving RISC genome as the giles creature controller #5 first, then retarget Add giles assembler, disassembler and a TUI inspector #8 to main (or merge Add evolving RISC genome as the giles creature controller #5 into the stack first) and land Add giles assembler, disassembler and a TUI inspector #8.
3. Working tree is clean; both branches pushed and in sync. cargo test green on each.
4. If continuing to watch the PRs: re-subscribe with subscribe_pr_activity for Add evolving RISC genome as the giles creature controller #5 and Add giles assembler, disassembler and a TUI inspector #8. Note send_later is NOT available in this environment; use a background self-check (e.g. a persistent Monitor emitting hourly) to catch merges/conflicts that webhooks don't deliver. There is no GitHub Actions CI — CodeRabbit is the only check.

Follow-up / not in scope

• Add a second, modernised evolvable genotype (non-byte-code design) #6 — second, modernised (non-byte-code) evolvable genotype to compete with giles.
• The config-on-load limitation is now FIXED (PR Add giles assembler, disassembler and a TUI inspector #8). Remaining intentional divergences from the original: single-cell vision (decision Reorganise world unit tests #3), per-byte genome wrap.
• Original features still not ported: carnivores/fighting, ranged (4-deep) vision, and an in-GUI genome editor + breakpoint debugger (the disassembler/inspector cover viewing; author/seed creatures via assemble + from_genome).

Key references

• Genotype + tooling: eyes2-lib/src/entity/genotype/genotypes/giles/ (genotype.rs, isa.rs, asm.rs)
• Trait + inspector types: eyes2-lib/src/entity/genotype/genotype.rs; creature driver + CreatureInspect: eyes2-lib/src/entity/creature.rs; selection/inspection + load: eyes2-lib/src/world/world.rs, eyes2-lib/src/world/store.rs; GUI: eyes2/src/gui.rs, loop: eyes2/src/main.rs
• Original C++: eyes/engine.cpp (VM + DisAssemble/Assemble), eyes/guts.cpp (MutateAnimal/BreedHerbivore), eyes/Engine.h + eyes/guts.h (defines), eyes/CodeEdit.cpp + eyes/Twiddle.cpp (original editor/debugger UI).

---

Session state (as of last update)

• Open PRs: Add evolving RISC genome as the giles creature controller #5 (genome, tip 7906431) and Add giles assembler, disassembler and a TUI inspector #8 (tooling, tip aa6d779). Both green, clean working tree, pushed.
• Review comments: all addressed (samples guard on Add evolving RISC genome as the giles creature controller #5; config-restoration on Add giles assembler, disassembler and a TUI inspector #8). CodeRabbit reports no actionable comments on Add evolving RISC genome as the giles creature controller #5; Add giles assembler, disassembler and a TUI inspector #8 not auto-reviewed (stacked).
• Subscriptions: this session is subscribed to PR activity for Add evolving RISC genome as the giles creature controller #5 and Add giles assembler, disassembler and a TUI inspector #8. A fresh session must re-subscribe_pr_activity to keep watching.
• Related issues: Add a second, modernised evolvable genotype (non-byte-code design) #6 (modernised genotype, future), this issue [Tracking/Recovery] Plan: evolving RISC genome as the giles controller #7 (recovery doc).
• Next likely task: merge Add evolving RISC genome as the giles creature controller #5 then Add giles assembler, disassembler and a TUI inspector #8, or start Add a second, modernised evolvable genotype (non-byte-code design) #6. Nothing is blocked.