Skip to content

feat(life-cycle): sexes, eggs, ageing and mate choice (ADR 0027) - #145

Merged
CodeByBryant merged 12 commits into
mainfrom
feature/eggs
Nov 13, 2026
Merged

CodeByBryant merged 12 commits into
mainfrom
feature/eggs

Conversation

@CodeByBryant

Copy link
Copy Markdown
Owner

Summary

A real life cycle (ADR 0027), as one PR at the owner's request: two sexes, a carried clutch, eggs that hatch, parents that guard eggs and jaws that eat them, ageing as decline plus a rising chance of dying, and mate choice with heritable tastes and mutual acceptance. Each part has its own switch, was built and tested with its switch off, then measured and turned on together. Before this a child was fully formed in the tick the pair met, the partner had no say and death of old age was a hard cutoff.

  • Sexes / eggs: founders alternate sex, a newborn's sex is one reproduction draw; only a female and a male mate. Conception recombines the child's genome at once, the female carries it (incubation, a carry cost, the clutch is lost if she dies), lays an egg, and it hatches after hatch into a creature with the stored genome and the mother's species. Eggs and clutches count against maxPopulation.
  • Guarding / egg predation: a parent within guardRadius guards its egg (costs energy; a bite at it is stopped and hurts the biter). An unguarded egg is eaten whole by any flesh-yield mouth (a jaw), never by a mandible or a parent. Eggs are prey in the senses; a parent senses the way back to its egg through the existing home inputs, so no observation or weight changes.
  • Ageing: past its own senescenceAge a creature burns more, is slower and needs more energy to breed, and faces a chance of dying that rises with age instead of a cutoff at maxAge (one draw per old creature per tick, none in prime). Also fixes the snapshot's lifeStage using the world baseline instead of the creature's own genes.
  • Mate choice: two new genes (choosiness, preference); an initiator looks at the nearest few ready partners and takes the first both accept; refusing costs energy and a wait.
  • UI: eggs drawn as flat discs (a ring when guarded) on an Eggs layer, egg totals in Statistics, eggs count as flesh intake in the observatory.

Type of change

  • Feature

Simulation impact

  • Changes organism behavior
  • Changes genetics or inheritance
  • Changes determinism

Determinism

  • Uses the seeded random source
  • Does not use Math.random() in simulation code
  • Does not use wall-clock time for simulation behavior
  • Determinism tests were added or updated

Hash schema 12 to 13 (egg counters, each creature's sex and carried clutch, the egg store appended after the version 12 tail; an egg's species is not hashed, because species are a derived view: the species-off hash test caught that) and genome version 5 (two genes appended). Header and sample digests match the independent Python hasher. Switch-off proof: with sexes, eggs, mate choice and ageing off, nine scenarios (field, instant eating, noise food, one cluster, lush, no predation, no ecology, reflex; founder brains equal to the prior, mutation frozen) give snapshots, events and records identical to the code before this PR; a multi-cluster layout differs only through the shifted genetics stream (the two new genes), as in ADR 0025. Goldens: regenerated in the commits that caused it (schema 13; the two genes); the flip is config only: every older entry now pins what it was measured with and all 50 reproduce their hashes unchanged; three new entries pin the new default world.

Testing

Commands run (fresh clone of this branch):

pnpm install --frozen-lockfile
pnpm format:check
pnpm check        # typecheck + lint + every package's tests
pnpm build
node tools/check-pages-artifact.mjs apps/web/dist
node --test tools/*.test.mjs

Additional tests:

Full determinism suite run to completion (3 shards locally): species-long-run caught the species-in-hash bug (fixed);
two Phase 3 pins re-pinned with measurements because the two new genes shift every mutation draw
(long-run-extinction seed 6: 19,582 -> 27,182; long-run-population seed 1 back half 25-46 -> 55-89, limit 100).
New tests with negatives: lifecycle (sexes, incubation, laying, hatching, cap, clutch loss, hash, chunking), egg predation and
guarding, ageing (senescence, decline factors, death chance, cutoff gone), mate choice (acceptance, mutuality, taste, search cost,
candidate limit, config), egg statistics UI.

Measured (tests/probe/life.probe.ts), default world:
  16 seeds x 30,000 ticks: 0 extinct, mean population 48-53, lowest 16-21, starved 60-64%, old age ~35%, 98-99% of eggs hatch, jaws alive in 7/16.
  8 seeds x 100,000 ticks (incl. 3246115366): 0 extinct, mean 55, lowest 19-25, starved 61-70%, old age 28-31%, 92-99% hatch,
  jaw lineage alive in 4 of 8 (was 1-2 of 8), tastes stay (choosiness 0.73-0.88).

Performance impact

  • No expected performance impact

Ticks per second 450 to 510 with four runs in parallel against 509 for the control (life cycle off); one egg pass and a few scans per tick.

Save compatibility

  • No save-format impact

Screenshots or recordings

Egg close-up and the Eggs layer toggle checked with Playwright at 1440 x 900 (a guarded egg is drawn, the Eggs toggle hides them, console clean).

Review notes

  • It took breeding retuning, not just the mechanism. The first flip lost 2 of 8 worlds (half the creatures are the wrong sex): minEnergy 75 to 65, cooldown 45 to 30, search radius 50 to 75, mating signal 250 to 350, found one lever at a time (ADR 0027 has the tables). Ageing hazard 0.04 cost a world; 0.02 did not. Mate choice at tastes of 0.3 turned nobody down; 0.8 and 0.5 turn down 12 to 28 percent of attempts that found a partner.
  • Honest limits: mate choice rarely decides anything (most attempts fail for lack of a partner in reach) and nothing pays a choosy creature directly, so tastes stay where they start. Guarding rests on the innate prior steering toward home; the reflex controller does not guard. Eggs help jaw lineages persist (4 of 8 worlds, from 1-2) but in seed 1 they became a jaw monoculture (40 of 41 creatures), which breaks the earlier 40 percent bar in that world: a lead for the multiple-mouths work, not hidden.
  • Classic and Clusters presets keep one sex, an instant birth and a hard lifespan.

Generated by Claude Code

…hat go with it (ADR 0026)

PR #143 merged with the one-line carcass change from the Copilot bot but without
the parts that make it pass: 4 predation goldens regenerated, the ecology-stability
floor 15 to 8 (measured over 12 held-out seeds: means 37.7-77.2, minimum 10 on seed
6, maximum 118, none extinct), tests with negatives (only the jaw bites or sees
carrion, a mandible does neither, the old table is still expressible) and the doc
updates. Main's determinism shards 1 and 2 failed on both OSes at aed927b for exactly
this reason (stale goldens; seed 6 under the floor).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
…witches, hash schema 13 (ADR 0027)

Two sexes (founders alternate, a newborn's sex is one reproduction draw), a female carries a
conceived clutch for reproduction.eggs.incubation and pays carryCost, lays an egg, and the egg
hatches after reproduction.eggs.hatch into a creature that keeps the stored genome, parents and
the mother's species. Eggs and clutches count against maxPopulation; a carrying mother who dies
loses the clutch (clutch-lost). Everything is off by default: sexes.enabled and eggs.enabled
false take the old code path exactly.

Hash schema 13 appends the egg counters, each creature's sex and carried clutch and the egg store
after the version 12 tail. Switch-off proof: nine scenarios (field, instant eating, noise food,
clusters, one cluster, lush, no predation, no ecology, reflex) with founder brains equal to the
prior and mutation frozen give snapshots, events and records identical to the previous commit; the
header and sample digests match the independent Python hasher. All 50 golden entries regenerated
here only (the header carries the new version).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
A parent within reproduction.eggs.guardRadius of its egg guards it and pays guardCost a second
per egg. A bite at a guarded egg is stopped: the egg stays and the biter takes guardDamage,
counted as the guard's bite for the death label. An unguarded egg is eaten whole by any mouth
with a flesh yield (the gut takes what it can, at the trophic yield; a full gut refuses it), never
by a mandible or a parent. Eggs are prey in the senses of a body that bites creatures, and a parent
senses the way back to its own egg through the existing home inputs (present beyond the guard
radius, full at three times it), so no observation or weight changes. Switches are still off.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
… drawn, life probe (ADR 0027)

Ageing, off by default (ageing.enabled): past its own senescenceAge a creature burns more
(metabolismRise), is slower (speedLoss) and needs more energy to breed (fertilityLoss), and instead
of the hard cutoff at maxAge it faces a chance of dying per second that rises with how far past
senescenceAge it is (hazard x s), with certain death at ceiling x maxAge. One draw per old creature
per tick from the world stream, none in prime or with ageing off. The snapshot's lifeStage now uses
the creature's own senescence genes instead of the world's baseline.

Eggs are drawn as flat pale discs that fill as they near hatching, with a ring when a parent
guards them, on an Eggs layer (default on); tests/probe/life.probe.ts measures the life cycle.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
…nce (ADR 0027)

reproduction.mateChoice (off by default, needs two sexes): a creature looks at the nearest few ready
partners of the other sex and takes the first that both accept. It scores a candidate
(1 - preference) x condition + preference x difference (condition: spare energy over what the
candidate needs to be ready; difference: genomic distance against the species threshold) and
accepts if the score reaches choosiness x threshold; turning every candidate down costs searchCost
energy and a retryDelay wait (failure reason 'rejected'). choosiness and preference are two new
reproduction genes appended to the table (Genome.version 5), so they mutate and recombine like any
other. A creature with choosiness 0 accepts anyone and the world is bit for bit the one without mate
choice (tested).

The gene table grows by two, so every founder's later genetics draws shift and every golden entry is
regenerated here. With the life cycle off, nine scenarios (field, instant eating, noise food, one
cluster, lush, no predation, no ecology, reflex) give snapshots identical to the code before the
life-cycle work; a multi-cluster layout differs only through the shifted genetics stream (its
founders differ, so the blend of their children depends on the draws).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
…0027)

Sexes, eggs, mate choice and ageing are on in the default world. 16 seeds x 30,000 ticks: no
extinct world, mean population 51 (lowest 16 to 21), starved 60 to 64 percent of deaths, old age
about a third, 98 to 99 percent of eggs hatch, a jaw lineage alive in 7 of 16 worlds. Reaching it
took four breeding numbers: minEnergy 75 to 65, cooldown 45 to 30, search radius 50 to 75 and
mating signal 250 to 350 (with half the creatures the wrong sex, the old values let 2 of 8 worlds
go extinct); ageing hazard 0.02 (0.04 cost a world) and mate choice choosiness 0.8, preference 0.5,
threshold 0.4, search cost 0.2 (the 0.3 tastes never turned anyone down).

Every pinned golden entry now says what it was measured with (one sex, an instant birth, the old
breeding numbers and gene baselines, ageing off) and all 50 reproduce their hashes unchanged: the
proof that the flip is config only. Three new entries pin the new default world. The Classic and
Clusters presets keep the old breeding and a hard lifespan; tests that pin numbers measured before
the life cycle use the BEFORE_LIFE helper. The Statistics panel shows the egg totals once an egg
has been laid, and the observatory counts an egg as flesh intake.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
…shed; re-pin two Phase 3 gates (ADR 0027)

An egg and a carried clutch kept the mother's species, and the hash covered it, which made species
part of the state: turning species off changed the 50,000-tick hash (species-long-run caught it).
The species an egg will hatch into is still stored, and no longer hashed, as for every other use of
species. The three golden entries of the new default world are regenerated for it; the 50 older
entries never carried an egg and are unchanged.

Two Phase 3 pins moved only because mate choice added two genes (every later mutation draw
shifts): the scarce world of long-run-extinction goes extinct at 27,182 (was 19,582, seed 6), and
long-run-population's seed 1 back half is 55 to 89 (was 25 to 46; seeds 2 to 6 stay at 25 to 48),
so its limit is 100 against a maxPopulation of 1,000.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
…and 0010

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8

# Conflicts:
#	docs/simulation/configuration.md
#	packages/simulation/tests/golden/state-hashes.json
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp4xBHxLnTrwReNXcf8
Copilot AI balanced review requested due to automatic review settings November 13, 2026 21:37

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@CodeByBryant
CodeByBryant merged commit d8f4e95 into main Nov 13, 2026
20 of 21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants