Deterministic, score-aligned reaction placement (fixes 52.8% agreement regression)

[edkerk]

The placement master maximises a gene-localisation objective — it never mentions the per-reaction placement variable x. So each reaction's compartment is a free co-optimum: the solver returns whichever vertex it lands on. Pinning the solver (an earlier fix) made that reproducible, but still arbitrary — reaction agreement with curated yeast-GEM was 52.8 %, while an earlier un-pinned build happened to land ~72 %. Neither number reflected the localisation evidence; both were solver accidents.

The fix

A lexicographic second pass in _solve_placement_master:

1. Stage 1 solves the gene-localisation objective (unchanged) and pins the solver.
2. It then fixes the gene layout — each y binary set to its stage-1 value (fixing the solution, not the objective value, so there is no near-optimal tolerance to tune).
3. Stage 2 re-optimises x only, placing each reaction in the compartment its own enzymes are predicted to occupy: reward x[r, c] by the summed DeepLoc score of r's genes for c, with a small default_compartment prior so genes-free and score-tied reactions fall there deterministically.

The gene layout is untouched, so gene agreement and the multi-compartment consolidation are unchanged; only the reaction placement — which was free — becomes meaningful.

Result (yeast-GEM, re-verified; reproduced identically across independent runs)

metric	before (pinned, arbitrary)	this PR
reaction agreement	52.8 % (1026/1943)	72.5 % (1408/1943)
gene agreement	88.7 % (716/807)	88.7 % (716/807) — unchanged
transports added	1135	967 — fewer
materialised growth	0.1426	0.1426 — unchanged
blocked fraction	29.7 %	29.7 % — unchanged
placement wall	—	+~4 s (warm-started second solve)

Reaction agreement now rests on the localisation evidence, not a solver tie-break; coherent placement fragments fewer metabolites across compartments, so it needs fewer transports. The 1408/1943 placement matches the number the original (pre-pin) design doc recorded — this recovers it deterministically and by principle.

Docs

• yeast_validation.md: reaction agreement 72.0 % → 72.5 % (1408/1943), transports 1001 → 967, plus the deterministic-placement rationale.
• localization_redesign.md: its 72.5 % (1408/1943) already matched; added the tie-break explanation.
• multiorganism_validation.md: footnote — the reaction-agreement column predates the tie-break and awaits re-measurement (gene agreement / growth / blocked are unaffected). Re-measuring Human-GEM / AraCore / iCre1355 is follow-up (their models were not available in this environment).

Tests

Full suite green; ruff and mypy clean. Existing placement assertions (r1 == ["m"], default-compartment cases, multi-localisation) pass unchanged — the score-following secondary agrees with their intent.