Files
road-compiler/.trellis/spec/backend/direct-edit-api.md
T

9.4 KiB
Raw Blame History

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

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

fs.writeFileSync(activeEdits, JSON.stringify(draft));

This permits half-written documents and allows a stale browser tab to overwrite newer edits.

Correct

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:

// 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.