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

368 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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, clusterPlans, 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.
## 13. Complex junction shape summary
### 1. Scope / Trigger
Complex-junction compilation publishes a structural classification which the
JunctionTools page displays. This crosses the compiler, the persisted GeoJSON
layer, `/api/state`, and the typed browser state.
### 2. Signatures
```js
GET /api/state?debug=1
// debug.junctionShapes?: Array<{
// clusterId: string, kind: string, label: string,
// armCount: number, throughPairCount: number
// }>
```
### 3. Contracts
- `complex-core` is published in `layers/road_surface.geojson`, not
`intersection_surface.geojson`.
- Its `shape_kind`, `shape_label`, `arm_count`, and `through_pair_count`
properties are the compiler authority. The service must project them without
reclassifying from node count.
- `debug.junctionShapes` is present only for debug state. An absent matching
entry means the client shows its ordinary cluster context, not an invented
shape.
### 4. Validation & Error Matrix
| Condition | Required behavior |
| --- | --- |
| No complex core for a configured cluster | Omit its summary; do not emit a false shape |
| Shape is unsupported | Compiler emits a normal-junction fallback diagnostic and no `complex-core` |
| GeoJSON properties are missing | Use `unsupported` and the readable fallback label only while projecting an existing core |
### 5. Good / Base / Bad Cases
- Good: a five-node cluster with five external arms returns `5 臂非规则路口`.
- Base: debug is off, so no shape summaries are returned.
- Bad: reading `intersection_surface.geojson` returns no complex cores and makes
the UI falsely appear to lack classification.
### 6. Tests Required
- Compiler: assert `complex-core` has the expected shape kind and arm count for
a real OSM cluster.
- Service/UI: assert debug state reads the road-surface core and the workspace
renders the received label without node-count inference.
### 7. Wrong vs Correct
```js
// Wrong: complex cores are not stored in this layer.
readLayer('layers/intersection_surface.geojson')
// Correct: project compiler-owned properties from their published layer.
readLayer('layers/road_surface.geojson')
```
## 14. Junction structure and standards profile
Stage-0 JunctionTools structure is compiler-owned and versioned independently
of the direct-edit document. `buildJunctionStructure(input)` must return
`junction-structure/v1` with unique stable object keys, readable labels, and
explicit arm/corner/facility references; it must reject duplicate keys,
unknown references, and an effective arm count that differs from the supplied
arms. It must not infer missing arms from an internal `2x1`/`2x2` layout.
`CN_URBAN_DEFAULT_PROFILE` is the immutable `cn-urban-default` profile. Use
`cloneProfile()` before applying project-specific changes and
`validateStandardsProfile()` at the boundary. Rules distinguish recommended,
warning, and blocking/invariant fields; a profile is metadata and rule
configuration, not a client-side save decision. Keep the compiler as the sole
producer of structure and diagnostics so the client cannot reclassify a
junction from node counts.
## 15. Save-time geometry validation
`saveEdits()` must run the same `resolveDirectEditConstraints()` used by
`editPreview()` after validating the candidate document and before writing it.
Any diagnostic with `severity: 'error'` returns HTTP 400 and leaves the active
document byte-identical; warnings remain saveable. This prevents a client from
skipping preview and persisting a width, corner radius, crossing offset, or
stop-line value that the compiler rejects. Version conflicts are checked first
and continue to return HTTP 409 without invoking geometry validation writes.
## 16. Scoped complex junction identity
### Scope and signatures
Stage 1 establishes the read model consumed by later cluster editing. Use
`resolveComplexJunctionTopology(model, cluster, helpers)` in complex geometry,
then `structureFromTopology(topology, shape, center, features)`. Projection is
`projectJunctionStructure({ model, layers, trafficSignals, junctionRef })`.
### Contracts
- `junctionRef` is `{ type: 'node' | 'cluster', id }`. Explicit `null` means no
junction projection; unknown references return `null`, never the first core.
- `GET /api/state` returns `junctionStructures`, keyed by `node:<id>` and
`cluster:<id>`. The legacy singular field is null at this unscoped entry point.
- `GET /api/edit-state?junction=<node>` preserves the node selection contract;
`?cluster=<id>` selects a cluster. Preview uses the equivalent `selection`
object. A selected editable cluster publishes only `cluster-carriageway-width`
handles for its external carriageways.
- A `cluster-carriageway-width` anchor contains `clusterId`, stable
`carriagewayKey`, `sourceNodeIds`, and `sourceRoadIds`. Replay matches all
source identity; a missing or changed source is stale with `anchor-missing`.
The solver stores accepted values in `clusterPlans`, and `compileGeometry()`
applies them to the matching complex-junction approach before geometry is
generated. It must not widen unrelated member-node approaches.
- Preview and save both evaluate the same candidate through the resolver and
`compileGeometry()`. Save rejects every `severity: error` diagnostic before
writing the edit document.
- Complex road-surface features carry `junction_key`, `object_key` and relevant
`arm_key`, `carriageway_key`, `corner_key`. Core (or the first remaining
approach when the core fails) carries `junction_structure` for persisted reads.
- Stable keys derive from cluster and sorted source node/segment/road IDs, with
corner keys derived from adjacent arms. Display indices and headings are not
object identities. `topologyFingerprint` detects source topology changes.
- Root provenance lists member nodes and external road/segment IDs. Arms point
to carriageways, corners to arms, facilities to feature IDs; normalizers must
preserve these fields and readonly capabilities across JSON round trips.
- Signal projection joins exact member `node_id` / `control_id`, retaining the
existing `signal_uid` as `geometryRef` and `provenance.featureIds`. It does not
rewrite the separately persisted signal document or guess from UID substrings.
### Validation matrix
| Input | Result |
| --- | --- |
| Multiple selection keys or repeated query keys | 400, no implicit priority |
| Empty/object-valued ID | 400 |
| Unknown node/cluster or missing compiled complex structure | null structure, empty diagnostics |
| Missing/ambiguous object source | readonly capability with reason |
| Explicit cluster selection | empty handles; never all-area or member-node handles |
### Cases and tests
Good: reorder member/road arrays and retain semantic IDs; delete a source and
change its identity/fingerprint. Base: legacy node editing still works. Bad:
opening cluster B while rendering cluster A's first core. Test the 3/4/offset/5+
arm matrix, two-cluster isolation, internal-link exclusion, grouped crossings,
scoped signals, JSON round trips, and persisted/preview projection equality.
```js
// Wrong: chooses an arbitrary junction and loses the selected scope.
projectJunctionStructure({ model, layers });
// Correct for a scoped editor:
projectJunctionStructure({ model, layers, trafficSignals,
junctionRef: { type: 'cluster', id: selectedClusterId } });
```