214 lines
9.4 KiB
Markdown
214 lines
9.4 KiB
Markdown
# Direct Edit Solver And API
|
||
|
||
## 1. Scope / Trigger
|
||
|
||
This contract covers the pure direct-edit resolver and the workbench endpoints
|
||
that preview, persist, checkpoint, and rebase `native-road-edits/v2` documents.
|
||
It is required because the feature crosses compiler, storage, and HTTP layers.
|
||
|
||
## 2. Signatures
|
||
|
||
```js
|
||
resolveDirectEditConstraints(model, editDocument, context)
|
||
// -> { roadProfiles, junctionPlans, constraintStates, handles, diagnostics }
|
||
|
||
GET /api/edit-state
|
||
POST /api/edit-preview
|
||
POST /api/edits
|
||
POST /api/revisions
|
||
POST /api/revisions/:id/rebase
|
||
```
|
||
|
||
## 3. Contracts
|
||
|
||
- The resolver is deterministic and must not import `fs`, `path`, `http`, or
|
||
write files. It accepts a baseline model, an optional validated v2 document,
|
||
and `{ revisionId, compilerGeometryVersion, previewSeq }` context.
|
||
- `GET /api/edit-state` returns the active document, `documentVersion`, active
|
||
revision, constraint states, diagnostics, and `road-edit-handles/v1` manifest.
|
||
- `POST /api/edit-preview` accepts `document` (or replacement `constraints`
|
||
and `operations`) and optional integer `previewSeq`. It returns the same
|
||
manifest/state data plus compiled layers, echoes `previewSeq`, and never
|
||
changes active files. Work over the 300ms budget sets `degraded: true`.
|
||
- `POST /api/edits` requires integer `expectedDocumentVersion` and either a
|
||
complete `document` or replacement arrays. Saves through a staging file and
|
||
rename, increments `documentVersion`, and returns the active revision.
|
||
- A version mismatch returns HTTP 409 with `{ ok: false, error, current }` and
|
||
leaves the active document byte-identical.
|
||
- `POST /api/revisions` requires a non-empty `label`; it creates an immutable
|
||
checkpoint and returns its manifest plus current edit state.
|
||
- `POST /api/revisions/:id/rebase` is read-only and returns status counts plus
|
||
per-constraint details. `pending`, `conflicted`, and `stale` constraints do
|
||
not enter geometry solving.
|
||
- A resolved constraint whose saved numeric value no longer fits the current
|
||
geometry range is returned as `stale` with reason `range-out-of-bounds`.
|
||
A missing replay anchor uses reason `anchor-missing`; callers must not infer
|
||
the stale cause from the status alone.
|
||
|
||
## 4. Validation & Error Matrix
|
||
|
||
| Condition | Required behavior |
|
||
| --- | --- |
|
||
| Missing or invalid v2 document fields | Reject with a field-specific 400 error |
|
||
| Missing `expectedDocumentVersion` | Reject with 400; do not write |
|
||
| Expected version differs from active version | Return 409 and current version; do not write |
|
||
| Empty checkpoint label | Reject with 400; no revision is created |
|
||
| Missing active workspace for preview | Reject with 400; no files are created |
|
||
| Solver replay anchor cannot resolve | Mark `stale` or `conflicted` with diagnostic; never silently apply |
|
||
| Compiler geometry version differs | Mark all replayable constraints `recheck` without changing values |
|
||
| Invariant violation (lane width, crossing boundaries, self-intersection, connector bounds) | Return a blocking diagnostic; do not clamp or silently repair |
|
||
| Constraint value outside the current handle range | Return a blocking diagnostic; do not clamp or silently repair |
|
||
|
||
## 5. Good / Base / Bad Cases
|
||
|
||
- Good: preview the same document later saved with the same active baseline;
|
||
compiled layers and solver diagnostics agree, while tracked file bytes and
|
||
mtimes remain unchanged.
|
||
- Base: an empty v2 document yields byte-for-byte baseline geometry and an
|
||
empty constraint-state list.
|
||
- Bad: two tabs save version `N`; the second save with `N` receives 409 and
|
||
cannot overwrite the first tab's document.
|
||
|
||
## 6. Tests Required
|
||
|
||
- Unit: resolver purity, empty-document identity, five replay statuses, handle
|
||
manifest fields, and blocking invariant diagnostics.
|
||
- Integration: preview file bytes/mtimes unchanged, `previewSeq` echoed,
|
||
preview layers matching formal compilation, and `degraded` represented as a
|
||
boolean.
|
||
- Persistence: atomic save, version-409 no-write path, checkpoint parent and
|
||
digest integrity, and rebase counts/details.
|
||
|
||
## 7. Wrong vs Correct
|
||
|
||
### Wrong
|
||
|
||
```js
|
||
fs.writeFileSync(activeEdits, JSON.stringify(draft));
|
||
```
|
||
|
||
This permits half-written documents and allows a stale browser tab to overwrite
|
||
newer edits.
|
||
|
||
### Correct
|
||
|
||
```js
|
||
if (expectedDocumentVersion !== current.documentVersion) throw conflict409();
|
||
saveEditDocument(activeEdits, { ...draft, documentVersion: current.documentVersion });
|
||
```
|
||
|
||
The service checks the version before the atomic version-bumping write, while
|
||
the pure resolver remains reusable by preview and formal compilation.
|
||
|
||
## 8. Left and right
|
||
|
||
`left` is `heading - 90`. Three places agree and must keep agreeing:
|
||
|
||
- `offsetLine()` (`native-road.js`) offsets a positive value counter-clockwise
|
||
from the direction of travel, i.e. toward geographic left.
|
||
- `centerlineShift = (edgeOffsets.left - edgeOffsets.right) / 2`, so widening the
|
||
left edge moves the centerline left.
|
||
- Sidewalks use `heading + (side === 'left' ? -90 : 90)`.
|
||
|
||
The handle manifest reports `axisAzimuth = tangent + 90` for both sides, which is
|
||
therefore *right*. Handle placement must offset the left handle by `tangent - 90`.
|
||
|
||
**Regression**: `makeRoadHandles()` once placed the left handle at `tangent + 90`,
|
||
drawing it over the right kerb, so dragging the visually-left handle moved the
|
||
right edge. Assert sides by geography (a north-heading road's left handle is west
|
||
of its centerline), never by axis sign — a sign convention can be wrong on both
|
||
sides of the wire at once and still look self-consistent.
|
||
|
||
## 9. What the geometry stage actually reads
|
||
|
||
`compileGeometry()` honours only four profile fields:
|
||
|
||
| Field | Read at |
|
||
| --- | --- |
|
||
| `edgeOffsets.left/right` | `native-road.js` centerline shift |
|
||
| `widthMeters` | road width |
|
||
| `sidewalkWidths.left/right` | `sidewalkRing()` |
|
||
| `laneDividerOffsets` | lane separator placement |
|
||
|
||
`profile.interval` and `profile.transitions` are written by the solver and read by
|
||
nothing: every direct edit currently applies to the whole road. Do not add UI for
|
||
interval-scoped editing until that changes — see
|
||
`research/interval-not-applied.md` in the map-editor task.
|
||
|
||
## 10. Saving is not applying
|
||
|
||
`POST /api/edits` writes the v2 document only. `/api/state` serves the outputs of
|
||
the last compile, so a save without a recompile leaves a refresh showing pre-edit
|
||
geometry — indistinguishable from a failed save.
|
||
|
||
`compileInput()` is the only caller that passes `editsFile`, and
|
||
`session.context.compileFresh` must be installed by **every** path that sets
|
||
`session.area`, including `/api/import`. It was originally wired only when the
|
||
server started with an area on the command line, so every UI-imported session
|
||
answered `请先导入 OSM 文件` to `/api/compile`.
|
||
|
||
An identity test cannot catch a `editsFile` regression: an ignored document and an
|
||
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.
|