From 5c89d92041be66b1d44538022ac55d2608fd11ac Mon Sep 17 00:00:00 2001 From: que01 Date: Mon, 31 Aug 2026 15:17:01 +0800 Subject: [PATCH] docs: record the two-road ambiguity and the range contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The directional-road trap cost two rounds in one session — once on the client, once in the solver — and both times produced a plausible number attached to the wrong object, which nothing but a segment with two of the thing will catch. Also tabulates what measuring three handle ranges turned up: one rejects past a third of its declared span, one goes silently inert over most of it, and one would happily place a stop line 126m from the junction it protects. Each was derived independently, and each was wrong in its own direction. Co-Authored-By: Claude Opus 5 (1M context) --- .trellis/spec/backend/direct-edit-api.md | 59 ++++++++++++++++++++++++ 1 file changed, 59 insertions(+) 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.