docs: record the two-road ambiguity and the range contract

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) <noreply@anthropic.com>
This commit is contained in:
que01andClaude Opus 5 committed 2026-08-31 15:17:01 +08:00
1 parent 59e3dc2320
commit 5c89d92041
1 file changed
+59
+59
View File
@@ -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.