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
|
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
|
a regression test is only trustworthy once you have watched it fail without the
|
||||||
fix.
|
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