per-vertex annotation data — OpenLane's visible/occluded, which PolylineGeometry cannot carry

[JArmandoAnaya]

The decision

OpenLane 2D marks each vertex of a lane as visible or occluded. PolylineGeometry.points is
list[tuple[float, float]] — coordinates and nothing else — so VisionSet has nowhere to carry
that information.

The lanes-format port (#223) ships the conservative default: the visibility array is written
all-visible, and the loss is documented rather than hidden. Whether to extend the annotation
model with per-vertex data is a domain decision, and that port deliberately did not take it.

Where the current behaviour is written down

At HEAD 47dc1f0:

• src/visionset/formats/lanes/__init__.py — the module docstring, in the paragraph beginning
  "The loss worth naming out loud is OpenLane's per-point visibility."
• src/visionset/formats/lanes/__init__.py:367 — "visibility": [1] * len(lane.points), the
  line that actually writes it
• src/visionset/formats/lanes/README.md:33 — the package's own statement of what is not carried
• tests/formats/test_lanes.py:617 —
  test_openlane_writes_every_point_visible_because_the_domain_has_no_other_answer, which pins
  the default so that changing it has to be deliberate

Why this was not a stop-and-flag during the port

The brief for #223 set its halt condition at per-annotation data that no exporter could do
without. Per-vertex visibility is neither: it is per-vertex, and no exporter requires it —
v1's own _get_point_visibility defaults to "visible", so OpenLane ran and emitted an
all-visible array there too. Nothing was blocked, so the model was left alone and the decision
left open.

What extending the model would cost

Not a small change, which is the argument for deciding it rather than drifting into it:

• a domain change — PolylineGeometry.points is currently a flat coordinate list, so
  per-vertex attributes mean either a parallel array or a richer point type. A parallel array can
  disagree in length with the points it describes, so it needs a validator; a richer point type
  changes the shape every existing caller reads;
• a wire change behind it, reaching openapi.json, the generated TypeScript client,
  tests/fixtures/wire_annotations.json, and the annotator's hand-written mirror in
  frontend/annotator/src/core/wire.ts;
• no migration — geometry rides in the annotation's JSON column — but every stored polyline
  predates the field, so reading has to tolerate its absence for good;
• a question the domain has so far refused to answer: what per-vertex data means in general.
  "Visible / occluded" is one format's vocabulary. A generic per-vertex attribute map is the
  honest generalisation, and it is a much larger change than the one format that wants it.

Likely pairing

This probably pairs with the 0.2 polyline drawing tool (#342). If per-vertex visibility exists, a
person has to be able to see and set it — which is a rendering decision, an occluded run drawn
differently, and an interaction decision, how a vertex is toggled, on top of the domain change.
The two are probably one workstream, and doing the domain half first with no way to author the
data would ship a field only an SDK caller can reach.

What a decision looks like

One of:

1. Leave it. All-visible stays, the declaration stays truthful, and OpenLane consumers get a
   usable file. This issue then ends.
2. A generic per-vertex attribute map, decided together with the polyline drawing tool — lanes are writable and reviewable, not yet drawable #342 so the tool can author it.
3. A visibility array specific to PolylineGeometry — the cheapest and least general
   option, and the one that invites the next format-specific field.

[JArmandoAnaya]

The HEAD reference has been updated from 9844c75 to 47dc1f0, following the 2026-08-05 backlog audit. All four citations were re-verified before the edit and still hold exactly: formats/lanes/__init__.py:367 with its "visibility": [1] * len(lane.points), the module docstring's "loss worth naming out loud" paragraph, formats/lanes/README.md:33, and tests/formats/test_lanes.py:617. Nothing else changed, and the decision itself is untouched.

[JArmandoAnaya]

A re-triage trigger has been added: this issue is re-examined at the 0.1.0 close-out, alongside the AI-assist substrate work (#81), annotation versioning (#127), the missing domain concept for assigning frames (#282), and the untyped batch-action roster in the e2e wire fixture (#358). At that point it is split, decided, or parked explicitly.

The trigger was added on 2026-08-06 because this issue previously named none at all, so nothing would have surfaced it (cf. the 2026-08-06 close-out brief, §5.5).

[JArmandoAnaya]

Decision (Armando, 2026-08-06): #352 stays in 0.1.0, paired with #342 under the "Robotics and AD" category (cf. #375). Supersedes the 0.2.0 candidacy floated in #363's cross-reference — per-vertex data lands with the drawing tool, not with 3D.

[JArmandoAnaya]

Status correction (2026-08-07): the body's framing of the polyline drawing tool as a 0.2 item is superseded. The founder decided on 2026-08-06 that the tool ships in 0.1.0, and it has since shipped and merged — the drawing tool, hit testing and vertex editing are all live.

The consequence falls on the "likely pairing" paragraph. The option of deciding per-vertex data together with the tool is spent, because the tool now exists without it. The options therefore read as: leave the all-visible default; extend the model generically; or extend it polyline-specifically and retrofit the tool to display and set the data. The options themselves and the decision remain exactly as the body states them, and remain the founder's to make.

The title's post-beta: prefix has been dropped for the same reason.

[JArmandoAnaya]

Decision (Armando, 2026-08-07): option 1 — the all-visible default stays, and the
annotation model is not extended now. PolylineGeometry carries coordinates only;
the OpenLane visibility array continues to be written all-visible with the loss
documented, exactly as the port shipped it.

Revisit is dated, not open-ended: this decision is re-examined at the start of the
0.2.0 cycle, when the 3D members (cuboid_3d, polyline_3d) put real per-point data
cases on the table and the generic-attribute-map vs. geometry-specific-field
question can be answered from concrete formats instead of speculation. Until then,
any extension would also mean retrofitting the shipped drawing tool, and neither
the generic nor the specific shape can be validated against a single 2D case.

The issue stays open with this decision recorded; milestone moves off 0.1.0 to the
0.2.0 line (the decision above is the 0.1.0 resolution). deferred-needs-input
stays — the 0.2 re-examination is also the founder's.