houseplan-card/docs/adr/282-wall-geometry-representation.md

ADR #282 — Wall geometry representation

• Issue: https://github.com/Matysh/houseplan-card/issues/282
• Status: accepted; Stage 1 stored identity implemented, Stages 2–3 deferred
• Date: 2026-08-24
• Related: #34 (frontend decomposition), #264 (resize controller slice), docs/WALL-THICKNESS.md, docs/ARCHITECTURE.md

Context

Nine of the last ten specifications are the same class of defect: #271, #272, #273, #275, #276, #277, #278, #279, #280, preceded by #249, #250, #253, #258 and #261. Over thirty days the wall geometry took 23 fix commits and src/wall-thickness.ts alone took 46. The ten geometry modules contain 595 mentions of a tolerance or an epsilon; src/resize.ts has 154 in 1017 lines, one every seventh line. The specs rate their own risk at 9 and 10 out of 10.

Two titles show where this has arrived. #279 is "a nearly orthogonal T junction" — a defect caused by a deviation no one can see. #278 is "a local extra-body union failure must not blank the whole masonry" — a specification written not to stop polygon unions from failing but to reduce the damage when they do.

Three properties of the representation produce that stream. They are properties of the data model, not of any algorithm, and no amount of care in the algorithms removes them.

A coordinate is a float in 0..1 with a step of 1/240. A lattice node is k/240, which has no exact binary representation. A round trip through storage, a multiplication by NORM_W for rendering and a midpoint computation each introduce a difference in the last bits. #258 and #279 are that. So is the ever-recurring non-idempotence of Optimize (#248): it looks for noise it cannot remove, because the exact value it would write does not exist.

A wall's identity is derived rather than stored. wallKey is a quantised midpoint plus an angle bucket, joined into a string. For a wall whose length is an odd number of steps the midpoint lands exactly on a rounding tie — measured in #258. The worse consequence is structural: because identity is derived from geometry, every editing operation must re-key its records (rekeyWallsAfterMove). One path that forgets loses a thickness record (#253); an import that forgets leaves a dangling reference (#244, #252).

A wall exists in two representations at once. A room polygon edge, and a separate thickness record addressed by key; an independent partition is a third form of the same thing. "Is this edge part of a contour" is therefore computed (edgeKinds, sharedSegsOf, atomicPolyForRoom) rather than stored. The junction is drawn by boolean operations over offset polygons — the most float-sensitive construction available. #197, #249, #261, #270, #272, #275 and #278 all live there.

The owner states the target model in one sentence: a segment with endpoints on grid nodes and a thickness; either part of a contour or not; openings lie on it. That is exactly the model which removes the first two properties by construction — a deviation from vertical becomes inexpressible rather than caught by a tolerance.

It hides one thing that matters. Thickness belongs to the edge between two rooms, and at a node where three walls of different thickness meet the shape of the junction does not follow from any one segment: the node has to be an object in its own right. Separately, a diagonal between two lattice nodes is legal while its offset contour has irrational vertices — integers remove identity and topology problems, not the arithmetic of mitres.

Decision

Change the representation in four independently shippable stages. Each stage removes a named class of defect and is worthless as a partial migration, so each must land whole. Only stage 0 is accepted for implementation now; stages 1 to 4 are accepted as direction, in the same sense as #34 — a target, not a mandate to create the files up front.

Stage 0 — a representation invariant

Measure what is actually stored: for every coordinate in the model, how far it is from the nearest lattice node, in steps. Report three populations separately, because they are different problems:

• exactly on a node — nothing to do;
• near a node but not exact (deviation far below a step) — this is the noise class, the one that produces #258 and #279, and the one Optimize claims to remove and cannot;
• far from a node — geometry the current model legitimately allows, since nothing forbids an off-grid vertex today.

Stage 0 fixes nothing. It converts a silent property into a measured one and answers a question nobody can answer today: how much of a real plan is in the noise class, and where it comes from. It also gives Optimize a convergence criterion that can be checked instead of asserted.

Deliberately not a red gate. The shipped fixtures contain authored coordinates such as 0.06 and 0.2875, which are 14.4 and 69 steps from a node — legal today. A check that fails on them would be switched off in a week.

Stage 1 — stored identity

Give every wall segment a stable id. Rooms reference segment ids; thickness lives on the segment. Re-keying stops being a thing that exists, which removes #253, #258 and half of #248 as possible defects. The schema gains a field, old keys stay readable, and nothing in the renderer changes. This is the largest reduction in risk per unit of work in the whole plan, and it does not depend on any other stage.

Stage 2 — an integer lattice in storage

Endpoints become node indices rather than floats. Equality is exact, midpoints are exact when kept in doubled indices, and orthogonality is a comparison rather than a tolerance. A single migration with a report replaces Optimize's endless attempt at the same thing. The honest cost: a STORAGE_VERSION change, a migration, and matching edits to backend validation and to import/export.

Stage 3 — one planar graph

Nodes, edges carrying thickness and kind, rooms as cycles of edges. A shared wall becomes one object instead of two coincident polygon edges, and "part of a contour" becomes a stored fact. This is the owner's sentence expressed as a model.

Stage 4 — junctions in closed form

At a node of degree n with known thicknesses, sort the rays by angle and compute the junction outline directly. No polygon booleans, therefore no slivers, no "retained versus discarded wedge" ambiguity and no failure mode where one union blanks the masonry.

Consequences

Data already off the lattice does not fix itself. What to do with a vertex 3·10⁻⁷ from a node is a product decision for the owner, not a technical one, and stage 0 exists to size it before that decision is taken.

Diagonals keep irrational offsets. Stage 4 must be tolerant there by design rather than by accident, and that tolerance is legitimate — unlike the tolerances that currently stand in for exact identity.

None of this cancels an open P1. The owner's installation has to work now, so the visible defects still get fixed on the current representation, and the stages proceed alongside.

The process consequence is immediate and independent of the code. Nine parallel specifications currently edit one subsystem, each rating its own risk at 9 or 10 out of 10, and they list each other as related (#277 → #276, #278; #278 → #276, #277). That is one task cut into nine branches which will conflict on merge. #279 has already been accepted by self-review under an owner decision, which is the process yielding to the throughput of the defect stream. The recommendation recorded here: admit no new specification in this subsystem except one that fixes something visible on a live installation, and spend the freed capacity on stages 0 and 1.