§39.4 completion + §39.5 retraction + §39.6: the usage namespace is NOT clean

Answering "are we clean". Generic namespace: yes. Usage namespace: no.

FINISH §39.4. The first sweep missed sites, found by a full re-grep:
graph.py's free-area budget, operators.py host-preference / keep-type /
repair-candidate, fitness.py's ("l","c","k") public-access test, bubble.py's
generic adjacency reference, and -- the important one -- cpsat.py, which was
still matching adjacency by raw startswith. graph.code_matches_requirement is
now the single public answer to "does this leaf count as the thing the
programme asked to be next to", shared by has_adjacency, has_vertical_connection
and cpsat.

RETRACT §39.5. It concluded 2g7.5's CP-SAT seeder win did not survive the
correction. That was wrong. The cause was the missed cpsat matcher above: the
exact solver was optimising a different relation than the scorer checked, so a
failing test reporting an incomplete sweep was misread as a baseline shift.
Re-measured over 6 seeds, cpsat now wins on both programmes (harbor 102/92,
maple 156/154). xfail removed.

REAL BUG UNDERNEATH: CP-SAT was never deterministic despite
num_search_workers=1 and a comment claiming it. neighbors[slot] is a set of
dom.Node, which hashes by id() -- a memory address -- so raw iteration made the
model-build order vary and CP-SAT returned a different equally-optimal
assignment each run (measured 194/180/171/182 over four identical aggregates).
sorted() on the slot indices fixes it. Also paired the wall-clock cap with
max_deterministic_time (solves run ~124ms against a 2s cap, so nothing was
timing out -- latent hazard, not the cause). solve_room_labels is now
reproducible on every captured instance; constructive_topology on the cpsat
path still is not, filed as homemaker-py-fdp (plausible contributor to b8g).

§39.6 THE SECOND NAMESPACE. Usage prefixes b/t/l/k (bedroom/toilet/living/
kitchen) classify programme codes by first letter and stay prefix-based by
design, but they are not inert: has_circulation deletes graph edges from them.
Four corpus rooms are misclassified by spelling -- la1 "Laundry Room" and li1
"Library Corner" as living, br1 "Staff Room" as bedroom, tr1 "Treatment Room"
as toilet. Measured on a health-centre seed: tr1 loses its edge to the adjacent
O, br1 loses its edge to t10 "Staff WC" -- both feed the connectivity fails §38
found persisting. Filed homemaker-py-sel; an explicit usage: key is the fix,
but it changes fitness for correctly-spelled programmes too so it needs its own
A/B.

DOCS. README gains a "Room codes and reserved names" section; CLAUDE.md and
AGENTS.md gain the same summary for agents. audit_programme_config.py now
reports the usage class each code picks up alongside the namespace and
satisfiability checks. DESIGN §37.2's note calling the c/o/s quirk "existing
product behaviour, not a bug" is annotated as superseded.

Corpus audit: zero generic-namespace violations across all ten example
programmes. 346 passed, same 7 pre-existing fixture failures, lint unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MJ84Feep79Hhm3E4zZJmnB

2026-08-26 10:09:14 +00:00

5.2 KiB

Raw Blame History

homemaker-layout

Programme-driven building-layout search over slicing trees. A clean-room Python successor to the Perl Urb project, intended to eventually be 100% Python.

Why a rewrite

Urb represents a building as a binary slicing tree where room sizes are derived top-down from division ratios. That makes room area an emergent property of every cut above it, which:

gives the genome low locality (a cut near the root rescales every descendant),
makes target room sizes nearly impossible to hit, so the gaussian size penalty dominates fitness, and
defeats crossover (transplanted subtrees lose their proportions).

homemaker inverts this: leaves carry target dimensions from the programme and division ratios are solved bottom-up for a fixed topology. The evolutionary search then only explores topology + types + adjacency.

Phase plan

~~Solver experiment: port Urb's geometry, re-solve ratios from programme targets, score the result against the original via the Perl oracle.~~ ✓
~~Native Python fitness (retire the Perl oracle).~~ ✓
~~Memetic search: canonical slicing genome + high-locality operators + Nelder-Mead inner loop.~~ ✓
~~Penalty reshaping: lexicographic (-n_fails, fitness) outer-search comparison.~~ ✓
~~Representation upgrade: canonical slicing encoding + bottom-up shape feasibility, scaled to larger programmes.~~ ✓
Search-quality experiments (current): a long running series of opt-in levers tried against the harbor-house, health-centre, and programme-house example corpora — leaf-sharing, finish-time cell→room collapse, ruin-and-recreate LNS, 2-opt polish, multi-use/co-located leaves, adjacency-graph and bubble-diagram fitness signals, and more. Most of these are negative/null results kept as opt-in flags or reference code rather than defaults. See DESIGN.md §11 onward for the full, numbered experiment log with methodology and results for each.

Layout

src/homemaker_layout/dom.py — read/write Urb .dom YAML into a Node tree.
src/homemaker_layout/geometry.py — faithful port of Urb's top-down geometry.
src/homemaker_layout/programme.py — parse patterns.config space requirements.
src/homemaker_layout/solver.py — bottom-up ratio solve (scipy).
src/homemaker_layout/fitness.py — native Python fitness evaluator.
src/homemaker_layout/fitness_cmd.py — homemaker-fitness CLI (drop-in for urb-fitness.pl).
src/homemaker_layout/collapse_cmd.py — homemaker-collapse CLI: finish-time global cell→room relabel of a .dom.
src/homemaker_layout/graph.py — leaf-adjacency graph for programme-driven checks.
src/homemaker_layout/genome.py — topology genome: base-floor tree + per-storey deltas.
src/homemaker_layout/operators.py — high-locality mutation and subtree crossover.
src/homemaker_layout/innerloop.py — ratio optimisation inner loop (Nelder-Mead / CMA-ES).
src/homemaker_layout/driver.py — memetic search outer loop.
src/homemaker_layout/evolve.py — homemaker-evolve CLI entry point.
src/homemaker_layout/oracle.py — legacy Perl shim, kept for cross-validation only.
src/homemaker_layout/bubble.py — 3D bubble-diagram adjacency fitness-signal prototype (DESIGN.md §27); validated null, not wired into fitness.py — reference only.

Room codes and reserved names

Leaf types live in three namespaces that share a first character. Only the first is enforced; the other two are conventions the fitness function reads, so a room's spelling can change how it is scored.

1. Generic structural types — C, O, S (reserved). The leaves the search itself creates: C circulation, O outside, S sahn (an outside court that also serves as circulation). Always uppercase. A programme code spelled exactly C, O or S is rejected at load.

2. Programme room codes — anything else, lowercase. k1, b1, cr1, of, and single-character codes like r or t. These may start with any letter: since DESIGN.md §39.4 the generic tests match C/O/S exactly, so naming a room cr1 no longer makes it circulation. (Before that fix it did — and silently dropped it from the required-space check entirely.)

3. Usage prefixes — b bedroom, t toilet, l living, k kitchen. Still matched by first letter, deliberately: this is how Urb encodes room usage. graph.has_circulation deletes graph edges based on them (a "bedroom" loses its edges to living/kitchen/bedroom/toilet; a "toilet" loses its edges to outside/living/kitchen/toilet), and the access and public-access checks read them too.

So a code beginning with b/t/l/k inherits that room's connectivity rules whether or not you meant it — la1 "Laundry Room" is treated as a living room, tr1 "Treatment Room" as a toilet. This is a known wart (homemaker-py-sel, DESIGN.md §39.6); an explicit usage: key is the planned fix. Until then, check any new programme with:

python experiments/audit_programme_config.py

which reports reserved-name collisions, the usage class each code picks up, and whether each room's size/width/proportion/crinkliness targets are mutually satisfiable at all.