Skip to content

feat(dsl): standard library — the map actor & traffic lights (p7-s5) - #101

Merged
JArmandoAnaya merged 1 commit into
mainfrom
feat/p7-s5-map-traffic-lights
Aug 2, 2026
Merged

feat(dsl): standard library — the map actor & traffic lights (p7-s5)#101
JArmandoAnaya merged 1 commit into
mainfrom
feat/p7-s5-map-traffic-lights

Conversation

@JArmandoAnaya

Copy link
Copy Markdown
Contributor

Slices 43e + 43h of #43, paired: the map actor's traffic_light_groups and
traffic_light_control fields are §8.15 types, so landing the two chapters
together removes a deferral seam rather than creating one.

What lands

§8.12.2 — the map actor. The top-level holder of the abstract road
network: six fields, the 18 conversion and creation methods §8.12.2.1 prints as
extend map: prototypes, and the 12 search-space modifiers of §8.12.2.2 in the
§7.2.2.2.9 prefixed form.

§8.15 — traffic lights. traffic_light_bulb, traffic_light and
traffic_light_group with their state and semantic-state methods,
traffic_light_stop_line as a route_element, traffic_light_phase and
traffic_light_cycle, the traffic_light_controller actor with its seven
§8.15.9 actions, and five enums including the 45-member bulb_icon.

Translation worksheets

New: docs/dev/stdlib-worksheets/. One file per translated chapter, one line
per declaration — kind, name, base, fields with types, plus a note wherever
the printed text needed a judgement call.

Most of §8 is printed as parameter tables, so turning a chapter into library
source is a translation and the expensive part is the reading, not the writing.
A worksheet captures that reading once. It is committed because it is the record
a reviewer can check against the specification without re-deriving the mapping,
and because re-reading a worksheet is much cheaper than re-reading a chapter.

Two places the standard contradicts itself

Resolved by asking which surface the rest of the chapter corroborates:

  • §8.15.4.2.1 prints extend traffic_light: for the group's
    state_equal, while its heading, its prose and Table 319 all place the method
    on traffic_light_group. The lone printed receiver loses.
  • Table 337 names set_group_bulb_state's first parameter traffic_light
    of type traffic_light, though its description says "the traffic light
    group affected". Here the parameter table is the surface a conforming
    scenario is written against, so the printed name and type are carried
    verbatim — the same rule that keeps §8.14.1.3's rounded conversion factors
    (ADR-0029).

A new qualification an author will meet

Adding the map made left reachable from ordinary scenario text, where it is a
member of both side_left_right (§8.12.14) and junction_direction (§8.12.22).
§7.3.3 therefore requires side_left_right!left. Same rule as
lane_type!driving, on a word an author is far more likely to reach for; both
halves are pinned.

Reported, not fixed: #100

Probing the new surface surfaced a resolver defect: an actor-associated modifier
cannot be applied. my_map.lane_side(...) reports "unknown modifier
'lane_side'", because the parser keeps the actor prefix in the declared name
(map.lane_side) while check_modifier_application looks up the bare name.
Unassociated modifiers are unaffected.

It predates this chapter — §8.7's stationary_object.location and
vehicle.tow_trailer have it too — and it is what §8.9's movement modifiers
(p8-s3, #46) will need fixed first. Filed as #100 rather than folded into a
translation PR. The declarations are well-formed and are pinned by
TheMapModifiersAreAssociatedWithTheMap; nothing pins the broken application,
because that is not the behaviour we want to keep.

Tests

frontends/dsl/tests/dsl_stdlib_test.cpp, +11 cases: the traffic-light enums,
structs, methods and actions; the stop line's route_element parentage; the map
actor's fields, its 18 method signatures and its 12 modifiers; a field sharing
its name with its type; the left ambiguity in both directions; and an
end-to-end scenario in the shape of §8.15.10's examples.

1270 gtest (+11), 184 pytest. TheBundledLibraryChecksClean still asserts
zero diagnostics of any severity — not zero errors, because a warning inside the
library would appear in every user's output.

Docs: osc-dsl-coverage.md (the §8.12.2 and §8.15 sub-module rows),
frontends/dsl/README.md, and the two worksheets.

Refs #43

Translates two more chapters of the §8 standard library into bundled DSL
source: §8.12.2's `map` actor and all of §8.15's traffic lights. They land
together because `map.traffic_light_groups` and `map.traffic_light_control`
are §8.15 types, so pairing the chapters removes a deferral seam.

§8.12.2 — the top-level road-network actor with its six fields, the 18
conversion and creation methods §8.12.2.1 prints as `extend map:` prototypes,
and the 12 search-space modifiers of §8.12.2.2 in the §7.2.2.2.9 prefixed
form.

§8.15 — `traffic_light_bulb`, `traffic_light` and `traffic_light_group` with
their state and semantic-state methods, `traffic_light_stop_line` as a
`route_element`, `traffic_light_phase`/`traffic_light_cycle`, the
`traffic_light_controller` actor with its seven §8.15.9 actions, and five
enums including the 45-member `bulb_icon`.

Adds translation worksheets under docs/dev/stdlib-worksheets/: one line per
declaration with the DSL spelling it produced and a note wherever the printed
text needed a judgement call. Reading a worksheet is far cheaper than
re-reading a chapter, and it is the record a reviewer can check against the
specification.

Two places where the standard contradicts itself, resolved by asking which
surface the rest of the chapter corroborates:

- §8.15.4.2.1 prints `extend traffic_light:` for the *group's* `state_equal`,
  while its heading, its prose and Table 319 all place the method on the
  group. The lone printed receiver loses.
- Table 337 names `set_group_bulb_state`'s first parameter `traffic_light` of
  type `traffic_light` though its description says "group". The parameter
  table is what a conforming scenario is written against, so the printed name
  and type are carried verbatim — the same rule that keeps §8.14.1.3's
  rounded conversion factors (ADR-0029).

Adding the map made `left` reachable from ordinary scenario text, where it is
a member of both `side_left_right` and `junction_direction`; §7.3.3's
`side_left_right!left` is now required and is pinned.

Found while probing the new surface, reported as #100 rather than fixed here:
an actor-associated modifier cannot be *applied*, because the parser keeps the
actor prefix in the declared name while the application site looks up the bare
name. The defect predates this chapter — §8.7's two modifiers have it too —
and it is what §8.9's movement modifiers (#46) need fixed first. The
declarations are well-formed and are pinned; the broken application is not.

1270 gtest (+11), 184 pytest. The library still checks with zero diagnostics
of any severity.

Refs #43
@JArmandoAnaya
JArmandoAnaya merged commit e177772 into main Aug 2, 2026
12 checks passed
@JArmandoAnaya
JArmandoAnaya deleted the feat/p7-s5-map-traffic-lights branch August 2, 2026 04:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[dsl] Actor-associated modifiers cannot be applied — the actor prefix stays in the declared name

1 participant