diff --git a/.trellis/spec/backend/direct-edit-api.md b/.trellis/spec/backend/direct-edit-api.md index 1dc9b80..94d3fb0 100644 --- a/.trellis/spec/backend/direct-edit-api.md +++ b/.trellis/spec/backend/direct-edit-api.md @@ -147,3 +147,62 @@ empty one produce identical output. Assert that a **non-empty** document changes the compiled output. Wiring gaps between two handlers need an HTTP-level test, and a regression test is only trustworthy once you have watched it fail without the fix. + +--- + +## 11. One segment, two directional roads, two junctions + +A segment's forward and backward roads can both reach the same junction while +serving different objects. Anything that resolves "the thing at this approach" by +taking the first match will therefore publish one road's answer on the other's +handle. + +Measured: 15 of 23 segments carried two `junction-crosswalk-inset` handles, and +one segment carried two crosswalk groups. + +The discriminator is the road whose **last source node** is this junction — +`road.sourceNodeIds.at(-1)` — which is the rule `crossingJunctionInset()` already +applies to find its junction plan: + +```js +// WRONG — whichever direction comes first in `items` wins +const crossing = approach.items.map((i) => crossingByRoadId.get(i.road.id)).find(Boolean); + +// RIGHT — the road that actually ends here +const crossing = approach.items + .filter((i) => String(i.road.sourceNodeIds?.at(-1)) === String(nodeId)) + .map((i) => crossingByRoadId.get(i.road.id)) + .find(Boolean); +``` + +**Mistake made, twice in one session**: once on the client picking a handle for a +selected element, once in the solver computing that handle's bound. Both produced +plausible values on the wrong object, which no type check and no smoke test +catches — only asserting against a segment that genuinely has two. + +--- + +## 12. A handle's range is part of its contract + +`value.min` / `value.max` say "drag here and something happens". Each kind +currently derives them independently, and every one measured was wrong in a +different direction: + +| kind | declared | measured | failure | +| --- | --- | --- | --- | +| `road-edge-offset` | ±2.925 | rejected past ~±1 | blocking diagnostic mid-drag | +| `junction-crosswalk-inset` | 0–8 | inert past 1.0–4.5 | **silent**, 44–88% dead | +| `junction-stop-line-offset` | 0.5–126.28 | fully linear | no meaningful ceiling at all | + +The silent case is the worst: a drag that does nothing is indistinguishable from +a broken control, and it is what `flag.ts` blocks whole features for. + +Rules: + +- Derive the ceiling from the geometry that consumes the value, not from a + constant. `effectiveCrosswalkInsetMax()` is the worked example: read where the + consuming function saturates and solve for it. +- Never publish a `max` below the current value — a manifest that contradicts + itself. Equal is fine and honest: it says there is no headroom. +- A range wide enough to produce nonsense (a stop line 126m from its junction) is + as much a defect as one that is dead.