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:
1 parent
59e3dc2320
commit
5c89d92041
1 file changed
+59
@@ -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.
|
||||
Reference in new issue
Block a user