M1: Python/NumPy port, golden-tested against Miller's C++

[schmug]

Task

Build the Python/NumPy port of the biosim4 simulator, golden-tested against David Miller's C++ — vectorised over the population. This is SPEC §7's M1, with one correction: SPEC's M1 gate is wrong. It reads "golden-output test: matches TS port step-for-step under fixed seed", but the conformance audit (#26) proved the TS port diverges from Miller in 23 verified ways across all 14 modules. Golden-testing against it would faithfully reproduce a broken reference. Miller's C++ is the ground truth. (ISSUES.md §6 half-anticipated this: "the golden test may need to reproduce upstream, not the port.")

Context — why port instead of patch

The full-sweep audit (#26, data/audit/cpp_conformance_audit.md) found 23 distinct new defects: 4 CRITICAL, 10 MAJOR, 8 MINOR. Zero of 14 modules clean. Its recommendation is PORT, argued from three facts:

1. Patching's usual benefit is void. D3/D4/D10/D11/D12/D21 each change RNG draw counts or drawn values → every published baseline must be re-run under any option. The choice is not "cheap patch vs expensive rewrite"; it is "re-run on a substrate with 23 known defects and an unmeasured defect floor, vs re-run on one with dtypes and golden tests."
2. The dominant defect class is eliminated by a port, and only by a port. 7 of 23 defects share one root cause: JavaScript has no integer types. The port transliterated C++ arithmetic without modelling C++ types. A typed port makes D3, D4, D6, D9, D12, D15, D20 unrepresentable, not merely fixed. Patching leaves the generator running — bug #4 M0 predictability harness → GATE: FAIL #4's "fix" changed which bit randomBitFlip flips but left the int16_t store semantics that give bit 15 its meaning; D3 is its unfixed half.
3. The defect floor is NOT established. The single worst defect (D0 — 100% of GENETIC_SIM_FWD similarity scores wrong, live in both challenges, zero tests) survived a 14-module sweep with 28 adversarial skeptics, and was found only by asking "which files did nobody open?" SignalBeacon.ts, BeaconTrace.ts and HandGenome.ts (627 LOC, including the entire SIGNAL_BEACON challenge) still have zero coverage.

SPEC §4.2 independently requires this port: the TS sim's throughput "cannot support the experiment," and "the brain has to be a torch model anyway, so the JS/Python boundary is a problem regardless." Issue #25 is measuring the actual numbers.

Not STOP: the audit's own framing — "the science is sound; the substrate is not."

The six non-negotiables (from the audit, §5)

1. Port Miller's unit tests as golden tests FIRST. They are already written and sitting in the vendored tree — 389 LOC of free oracles, and the audit's own skeptics used them to find defects:
   • unitTestGridVisitNeighborhood.cpp (35 LOC) — pins D12 in 7 cases
   • unitTestBasicTypes.cpp (312 LOC) — pins D17
   • unitTestConnectNeuralNetWiringFromGenome.cpp (42 LOC) — pins the decode/wiring
2. Golden-test jaro_winkler_distance against the C++ on generated genome pairs. D0 is proof that an untested comparison function silently returns garbage forever. Reference artifact: data/audit/jw_verify.js (20,000/20,000 pairs diverge).
3. Adopt Miller's 1-based indexing with a reserved slot 0. Verified in the C++: peeps.cpp:21 — // Index 0 is reserved, so add one: — and simulator.cpp:149 — // multithreaded loop: index 0 is reserved, start at 1. The port's 0-based choice is the root of three findings (D10, D11, D21 — including agent 0 is never stepped yet still breeds).
4. Decide D2 explicitly and document it. Miller's neuron-array construction is itself buggy: he indexes by original key with std::map::operator[] default-insertion, pinning a subset of hidden neurons at a constant 0.5. The TS "fix" for known-bug #2 Seeded PRNG throughout #2 overshot — Miller does not drive them all; 57.5% of default brains differ in driven flags. Bug-for-bug fidelity means deliberately re-introducing frozen neurons. This directly touches the M0 question (how much usable recurrent state an agent has). Either choice is defensible; silence is not.
5. State the determinism invariant once, globally. Miller-stream identity is unreachable (seeded mulberry32 vs his thread-private Jenkins) — say so explicitly, and audit self-determinism per seed instead. Then cost appendEpochLog's ~1100 undrawn RNG calls/generation (called from inside spawnNewGeneration.cpp:177, before initializeNewGeneration) against that invariant. The audit found every auditor asked only "does my function draw RNG?" — locally correct, globally useless.
6. Re-run everything. Not optional under any option.

Typed-dtype requirements (the structural fix)

These are what make the dominant defect class unrepresentable:

• np.int16 connection weights — restores bit 15 as the sign bit (D3: sign currently frozen for life; |w| reaches 8.0 vs Miller's 4.0)
• makeRandomWeight over the full 0xffff range, not 0xefff (D4: birth weights currently 53.3% negative and capped at +3.4998)
• 7-bit masked sourceNum/sinkNum gene fields, 0..127 (D9)
• uint16 grid cells (the 0xffff barrier sentinel)
• // integer division everywhere the C++ uses int division or (int) casts (D6, D12, D15, D20) — including visitNeighborhood's two (int) truncations and Coord.length()'s (int)sqrt

Scope

Port, vectorised over the population where it pays: basicTypes, Grid (+ createBarrier, visitNeighborhood), Signals, Peeps, Genome (+ decode, mutation, reproduction), GenomeCompare, Individual (+ feedForward, getSensor), Sensor, ExecuteActions, SurvivalCriteria, SpawnNewGeneration, params, and the sim loop (simulator / endOfSimStep / endOfGeneration).

Suggested phasing (each phase independently landable):

• P1 — foundation + oracles: basicTypes, Grid, Signals + port Miller's 3 unit tests. Highest oracle density; pins D12/D17 immediately.
• P2 — genome: decode, mutation, reproduction, GenomeCompare + the jaro-winkler golden test. Most CRITICALs live here (D0, D3, D4).
• P3 — agent: Individual, feedForward, sensors, actions, survival.
• P4 — loop: Peeps, SpawnNewGeneration, the step/generation loop, throughput.

Reference: the C++ is vendored (davidrmiller/biosim4 @ 45e808c); ~5,055 LOC C++ / ~3,595 LOC TS. Clone it locally rather than fetching per-file (a prior agent run died because WebFetch depends on a permission classifier that was unavailable).

Constraints

• Do NOT golden-test against the TS port. SPEC §7's M1 gate is provably the wrong target (C++ conformance audit: 23 new defects, 4 critical, 0 clean modules — recommend PORT #26). Miller's C++ is ground truth.
• Do NOT port the TS port's bugs. Read the C++ for each function; use the TS only to understand slsim's deliberate additions.
• Preserve slsim's deliberate additions as first-class, and port them too: the seeded PRNG, env-var parameterisation, sensor-stream CSV logging, and the experiment levers (barrier dynamics, killEnable, the SIGNAL_BEACON challenge + beacon trace/scatter, genome injection). Note these are the 627 LOC the audit never reviewed — port them from their intent, and test them.
• Keep the TS port in-tree as a historical reference; it is no longer the source of truth. Do not delete it.
• Do NOT build the Brain interface / TransformerBrain / MLPBrain (M3/M4). This is the substrate only.
• Do NOT change the SPEC §2 gate criterion.

Acceptance criteria

• Miller's unitTestGridVisitNeighborhood.cpp, unitTestBasicTypes.cpp and unitTestConnectNeuralNetWiringFromGenome.cpp ported and passing against the Python port.
• jaro_winkler_distance golden-tested against the C++ on generated genome pairs — 0% divergence (vs the TS port's 100%).
• Each of the 23 audited defects is either structurally unrepresentable (state which dtype/design makes it so) or covered by a test pinning the C++ behaviour. A short table mapping D0–D22 → unrepresentable / tested / deliberately divergent (with rationale).
• Throughput ≥ 20× the TS port on the same config (ISSUES.md §6), or a documented reason, informed by Throughput spike: is the PoC computationally reachable? (M1/M4 feasibility) #25's measurement.
• Determinism: same seed → bit-identical output, with the invariant from non-negotiable Enrich the world to flip the M0 gate: barriers + Miller-level mutation #5 stated explicitly in the code and docs.
• D2 decided and documented (frozen-neuron fidelity: yes or no, and why).
• RESULTS.md updated to state that every pre-port result is superseded and why.

Out of scope

• The Brain interface, TransformerBrain, MLPBrain, ES training, lifetime learning (M3/M4/M5).
• Re-running the M0 corpus on the new port (a follow-up issue — but note acceptance requires the port to make it re-runnable).
• Patching the TS port further. Fix inverted selection as default + search-strength gate before M1 #24's search-strength question is undermined anyway (its injected target used a weight the search cannot produce — D4).

Reasoning guidance

This is a large, multi-session port; land it in phases, each with its golden tests green. Read the C++ for every function you port — do not translate the TS. The whole reason this issue exists is that transliterating without modelling types produced an open-ended bug generator; the antidote is types first, oracles first, then code. When the C++ itself looks wrong (D2), stop and flag it rather than silently choosing.

Cross-references

• #26 — the conformance audit and its PORT recommendation · data/audit/cpp_conformance_audit.md
• Throughput spike: is the PoC computationally reachable? (M1/M4 feasibility) #25 — throughput spike (is M1 mandatory, is M4 affordable): Throughput spike: is the PoC computationally reachable? (M1/M4 feasibility) #25
• Optimiser null-test: can the search find a proven 4-gene, 100% policy? #22/Optimiser null-test (#22): the proven 4-gene policy is expressible; the search barely finds it #23 — the optimiser null-test whose premise D3/D4 undermine: Optimiser null-test: can the search find a proven 4-gene, 100% policy? #22
• Fix genome→net decoding vs Miller's C++ — evolution is broken (M0 blocker) #8/Fix genome→net decoding vs Miller's C++; remove feedForward clamp (#8) #9 — the decode fix whose D3 half remains unfixed: Fix genome→net decoding vs Miller's C++ — evolution is broken (M0 blocker) #8
• SPEC.md §4.2 (why a torch brain forces Python), §7 (M1 — whose gate this issue corrects), ISSUES.md §6.

Labels

enhancement

[schmug]

Phase 1 landed — PR #28

Foundation + Miller's golden oracles. Ground truth is the C++; the TS port is not and was left
untouched. Types first, oracles first, then code.

Oracles ported and passing

Miller C++	Ported to	Result
unitTestBasicTypes.cpp (312 LOC)	pysim/tests/test_basic_types_oracle.py — 21 tests	✅
unitTestGridVisitNeighborhood.cpp (35 LOC, pins D12)	pysim/tests/test_golden_cpp.py::TestVisitNeighborhoodOracle	✅

Miller's grid test only prints, so its expected output is captured from his unmodified,
compiled C++ (pysim/tools/capture_golden.cpp → cpp_golden.json) — no simulator logic is transcribed into the harness, and his own unitTestBasicTypes passes under his compiler during capture.

D12 / D17 / D18 / D20 (+ sentinel) disposition

Defect	Sev	Disposition	Mechanism / test
D12 visitNeighborhood drops both (int) truncations	CRITICAL	Tested + contained	Both truncations restored (grid.cpp:37,40). Pinned by Miller's 7 cases + 11 sim-radius cases. Teeth verified: the real Grid.ts algorithm yields 15 / 8 / 22 cells at r = 2.0 / 1.5 / 2.5 where Miller and pysim yield 13 / 9 / 21 — matching the audit's "15 vs 13" and "8-cell skewed blob vs centred 3×3".
D17 asDir PI/16 not PI/8	minor	Unrepresentable + tested	Exact integer PI/8 form (tanN/tanD, int32 boundary tests) — no float angle to drift. 121×121 lattice golden.
D18 raySameness NaN on zero vector	minor	Tested	mag == 0 → 1.0 guard; 10⁴-case grid asserts no NaN anywhere.
D20 createBarrier case 3 float division	minor	Tested	Integer division; barrier-3 pinned at 645 cells (TS float division → 660).
0xffff sentinel (TS Uint8Array → 0xff)	root cause	Unrepresentable	np.uint16 cells; 0xffff round-trips by construction.

Also structurally handled though filed elsewhere: uint8 signal saturation (clamp-before-store) and
Coord.length()'s (int)sqrt round-down — the latter is why survival "within 32" is
floor(hypot) <= 32 (a 3405-cell disc, chance 0.2078), not π/16.

Conventions established (documented in pysim/README.md)

• 1-based agent indexing with reserved slot 0 — the root of D10/D11/D21. Phases 2-4 must
  index agents from 1 and size containers population + 1.
• Determinism = self-determinism per seed. Miller-stream identity is unreachable (thread-private
  Jenkins vs seeded PCG64) and explicitly not the target; we reproduce his modulo bias and pin draw
  order/count instead.
• C integer semantics live in one module (pysim/cints.py), making the "JS has no int types"
  defect class unrepresentable rather than merely fixed.
• Two C++ quirks flagged, not silently improved: createBarrier.cpp:74 sizeX/sizeY typo;
  barrier-5's discarded-but-RNG-drawing center1/center2.

Gates

pysim 107 · M0 gate 33 · tsc 0 errors · npm test 57. All green.

What Phase 2 inherits

The 1-based convention, cints.py, the seeded RNG, and the golden-capture pipeline. Phase 2 owes:

• port unitTestConnectNeuralNetWiringFromGenome.cpp; golden-test jaro_winkler_distance vs the
  C++ (D0 — 100% divergence, zero coverage, the audit's worst);
• typed dtypes: np.int16 weights (D3), full-0xffff makeRandomWeight (D4), 7-bit gene fields (D9);
• decide and document D2 (frozen-neuron fidelity — it touches the M0 question; silence is not an option).

Phase 4 still owes the appendEpochLog ~1100-draws/generation accounting and D22 extinction-restart.

[schmug]

Phase 2 (genome layer) — done. PR #33

The evolutionary-search substrate is ported from Miller's C++ @45e808c (read directly, never translated from the TS port) and golden-tested against his compiled output. All gates green: tsc 0 · npm test 70/70 · m0 gate 33/33 · pytest 146 (was 107) · Math.random in src/ = 0.

Oracles passing

Captured from Miller's unmodified genome.cpp + genome-compare.cpp via pysim/tools/capture_genome_golden.cpp (the Phase 1 harness pattern). The genome inputs are emitted alongside Miller's outputs, so Python feeds byte-identical genomes to its own code and compares.

• jaro_winkler_distance — 0/228 divergence (the acceptance bar for D0; the TS port is at 100%). Proven to have teeth: a faithful transcription of the TS algorithm's three bugs diverges on 88% of the same pairs (TestJaroOracleHasTeeth).
• createWiringFromGenome — 0/86 divergence, including Miller's own unitTestConnectNeuralNetWiringFromGenome.cpp genome, ported (Phase 1 left it for this phase).
• genesMatch — 0/60 divergence.

D0–D9 disposition

Defect	Disposition	Mechanism / test
D0 jaro (dropped !sflags[j], j=0 reset, float range)	tested	golden 0/228; TestJaroWinklerOracle + teeth
D2 neuron array operator[]-by-original-key	deliberately divergent — reproduce Miller bug-for-bug	golden + TestD2FrozenNeurons (see below)
D3 int16 weight	unrepresentable — np.int16 weight, bit 15 = sign, |w|≤4.0 + TestD3…
D4 0xffff weight range	unrepresentable — full-range draw + TestD4…
D5 cropLength keeps length	tested — TestD5… (trim-back keeps length, not size-length)
D6 integer crop	unrepresentable — total // 2 + TestD6… (never empties/throws)
D7 deletion [0,size-1]	tested — TestD7… (gene 0 deletable, 0 no-ops / 40k)
D8 insertion cap guard	unrepresentable — guarded + TestD8…
D9 7-bit source/sink	unrepresentable — masked fields + TestD9… (incl. bit-128 no-op)

Draw order/count pinned too, including the unused byteIndex draw in randomBitFlip.

The D2 decision (and its rationale)

Reproduce Miller's buggy neuron-array construction bug-for-bug — frozen and phantom neurons included. Miller fills the neuron array via std::map::operator[] indexed by the neuron's original (mod-maxNumberNeurons) key, not its remapped number; absent keys default-insert zeroed phantoms and grow the array to max(key)+1, so driven flags land on the wrong indices. The phantom_noncontiguous_keys case: two neurons survive on keys 2,4 and feed actions via remapped 0,1 — Miller's output is a 5-neuron array with driven = [F,F,T,F,T], i.e. the neurons the connections actually drive are frozen while the driven flags sit on unreferenced phantoms.

Why keep the bug rather than "fix" it (as the TS did):

1. Miller is the ground truth for this port. Every other Phase 2 defect is corrected because the TS diverges from Miller; D2 is the one case Miller is buggy, and the same standard means reproducing it. Choosing the TS behaviour would be the one place we golden-test against a non-Miller reference — which this issue forbids.
2. The golden forces it. The "fixed" array (2 neurons, both driven, indexed by remapped number) is a different object and fails the wiring golden; test_the_correct_fix_would_differ_here documents this so a silent future re-fix trips a red test.
3. It is exactly the M0 quantity under measurement. The frozen neurons reduce usable recurrent state; the TS fix silently increases it — so M0 measured on the TS substrate answers for a different amount of recurrent state than the reference this project compares against.

Pinned by TestD2FrozenNeurons and the 86-case wiring golden; full rationale in pysim/README.md §3c.

What Phase 3 inherits

The typed Gene; create_wiring_from_genome(genome, params) -> NeuralNet — feedForward must consume that array as-is (D2 frozen/phantom neurons; the array can be larger than the referenced-neuron set; connections already in Miller's two-pass order); the reproduction entry points SpawnNewGeneration calls; and genome_similarity backing GENETIC_SIM_FWD — Phase 3 owns D11's other half (gate the sensor on isOccupiedAt, resolve neighbours by the 1-based index so it never scores a phantom agent 0).

Out of scope here (unchanged): Individual/sensors/actions/survival (Phase 3); Peeps/spawn/sim-loop/throughput (Phase 4); the Brain interface / TransformerBrain / MLPBrain; re-running the M0 corpus.

Note on this phase's motivating question (from data/selection_fix.md / #29): #29 measured the corrected TS search under a frozen weight sign (D3) and an unreachable target weight (D4). Both are now corrected here (D3 → np.int16, D4 → full 0xffff), so a re-run on this substrate can finally distinguish "the landscape is genuinely hard" from "the search was crippled." That re-run is a follow-up, not this PR.

---

Generated by Claude Code

[schmug]

Phase 3 (agent layer) landed — PR #39

Ported the agent layer from Miller's unmodified C++ (@45e808c): Individual + feedForward, all 21 sensors + the 6 helpers, executeActions, and passedSurvivalCriterion (CENTER_WEIGHTED / M0). Read from the C++, never translated from the TS port. All changes confined to pysim/.

Oracles passing + teeth proof

pysim/tools/capture_agent_golden.{cpp,sh} follow Phase 2's capture_genome_golden pattern: compile Miller's agent TUs with a scripted RNG (draws emitted + replayed identically, since his thread-private Jenkins stream is unreachable by design) and observable Peeps queues, feeding byte-identical inputs to both sides. agent_golden.json holds 180+ sensor cases, 20 feedForward brains × 3 steps (960 action values), 27 executeActions cases, 9 survival sweeps (3249 cases). Every case matches within a last-ULP float32 tolerance.

Every new golden is shown to reject the TS algorithm where it diverges:

Defect	Teeth (golden rejects TS)
D11	with a clone planted in reserved slot 0, the TS algorithm returns 1.0 on an empty forward cell where Miller returns 0.0 — a full inversion of the gate sensor
D1	7 sink numbers (16,33,…,118) that mod-17 wires to the dead sink 16 are unreachable under the correct mod-16; kill block queues no death where the TS enum would
D10	a TS spawn without grid.set reads POPULATION = 0 where Miller reads a real density
D15	round() gives a different oscPeriod on >54% of the domain vs (int) truncation
D2 (consumed)	a "fixed" 2-neuron array changes the action-level outputs — proof fidelity is load-bearing for M0

D1 / D10 / D11 / D15 disposition

Defect	Sev	Disposition	Mechanism / test
D11 GENETIC_SIM_FWD → agent-0 on empty cells	CRITICAL	Tested (golden + teeth)	get_sensor gates on is_occupied_at (empty→0.0, getSensor.cpp:349), resolves via 1-based peeps.get_indiv. test_sensors_oracle.py::TestD11Teeth
D1 KILL_FORWARD before NUM_ACTIONS (mod 17)	MAJOR	Unrepresentable (enum) + tested	sensors_actions.py: KILL_FORWARD = 17 after NUM_ACTIONS = 16; is_action_enabled(KILL) False. test_sensors_actions.py, test_actions_oracle.py::TestD1KillTeeth
D10 constructor omits grid.set(loc, index)	MAJOR	Tested	initialize sets it unconditionally (indiv.cpp:18). test_indiv.py::TestD10
D15 Math.round vs (int) truncation	MAJOR	Unrepresentable (c_int_cast) + tested	actions.py: 1 + c_int_cast(1.5 + exp(…)). test_actions_oracle.py::TestD15Teeth

Also consumes D0 (Phase 2's corrected genome_similarity), D2 (frozen/phantom neuron array, honoured not "fixed"), and D12 (Phase 1's visit_neighborhood). Determinism: draw order/count pinned for initialize, the RANDOM sensor, and executeActions's conditional draw order.

Gates

pytest pysim/tests 184 passed (146 inherited + 38 new) · tsc 0 errors · npm test 70/70 · test_m0_gate.py 33/33 · grep Math.random src/ = 0.

What Phase 4 inherits

This agent layer — Individual/feed_forward/get_sensor, execute_actions (which enqueues via peeps.queue_for_move/death), passed_survival_criterion, SimContext, and the D1-correct action space. Phase 4 still owes the loop: full Peeps (drainMoveQueue/drainDeathQueue/cull/spawn — the minimal container here raises for those, and D16's "skip dead movers" guard lives there), SpawnNewGeneration, the step/generation loop (D21/D22), the appendEpochLog RNG accounting, throughput (#25: brain-bound, so this scalar layer is the right trade), and the 627 LOC of unaudited beacon additions. Running this layer is what makes #29's "genuinely hard landscape vs merely crippled search" question finally answerable.

Cross-refs: #26 (audit) · #28 (P1) · #33 (P2) · #29 (search-strength) · #34/#25 (throughput).

---

Generated by Claude Code