Skip to content

feat(golden): DSL golden scenarios and an XML/DSL parity pair (p8-s4) - #112

Merged
JArmandoAnaya merged 1 commit into
mainfrom
feat/p8-s4-parity
Aug 2, 2026
Merged

feat(golden): DSL golden scenarios and an XML/DSL parity pair (p8-s4)#112
JArmandoAnaya merged 1 commit into
mainfrom
feat/p8-s4-parity

Conversation

@JArmandoAnaya

Copy link
Copy Markdown
Contributor

The architecture's central claim is that two frontends compile into one IR and
that one runtime executes it. This turns the claim into a test.

The parity pair

gs12-dsl-cruise.osc and gs12-xml-cruise.xosc say the same thing in the two
languages. Run both and the traces are equal byte for byte — not close,
equal:

python scripts/golden.py compare-pair gs12
ok   gs12 pair  (gs12-dsl-cruise.osc == gs12-xml-cruise.xosc, byte for byte)

The pair is part of check-all, so the golden CI job asserts it on macOS, Linux
and Windows on every push. If a change made one frontend drift from the other,
this is what would say so.

Two things it took to make them identical, both worth recording because they
are asymmetries rather than bugs:

  • The XML twin sets its Performance limits to zero. §8.7 declares no
    performance limits at all, so a DSL vehicle is unconstrained; an unstated
    clamp on the XML side would diverge the traces.
  • The XML twin carries a Storyboard stop trigger at t = 9. §7.6.2 says a DSL
    scenario ends when its do directive does, and the Storyboard is the only
    place XML can say that. Without it the DSL ramp freezes at 19.975 m/s while
    the XML one runs on to 20 — which is exactly the divergence the pair exists to
    catch, and it caught it.

GS-13 — what has no XML counterpart

A parallel nested in a serial, a position(ahead_of:) placement, a
slower_than relative-speed modifier, and a one_of whose alternative is an
input rather than a draw. --select brake changes what runs and nothing else.

Why the pair is GS-1's shape and not the planned GS-2 cut-in

golden-scenarios.md planned GS-12 as a DSL twin of GS-2. A byte-identical pair
needs both files to denote the same IR actions, and GS-2's lane change does
not survive that: §8.9's lateral modifier lowers to a LaneOffsetAction while
GS-2's XML uses a LaneChangeAction, whose transition time is derived from
maxLateralAcc rather than from a duration (ADR-0016). Two different actions
with two different timing laws — a pair built on them would compare things that
were never claimed to be equal.

GS-1's longitudinal shape is expressible identically in both languages, so
that is what the parity claim is made on. The plan document now says this rather
than leaving the substitution unexplained.

The user-guide page the pillar owes

docs/user-guide/one-scenario-two-languages.md: the claim as a test, a table of
how each language reaches the same IR, and — the part that matters — every place
the two standards genuinely differ, with the choice Scena made and where it
is recorded:

  • the DSL declares no performance limits at all (§8.7);
  • animal has no taxonomy counterpart and stays unclassified (§8.7.10);
  • entry-point selection is implementation-defined (§7.7.2);
  • one_of has no XML counterpart, and its alternative is an input not a draw;
  • three §8.8/§8.9 names collide in the standard and take the unassociated form;
  • two §8.15 contradictions, each resolved by what the rest of the chapter
    corroborates;
  • DSL: an overloaded enum literal should resolve by the expected type (§7.3.3) #110, the overloaded-enum-literal gap, stated plainly as a known limitation.

Suite

13 golden scenarios, 47 checkpoints (was 11/39). gtest and pytest counts
unchanged at 1392 + 194 — this sprint's assertions live in the golden harness,
which is where an end-to-end claim belongs.

Closes #47

The architecture's central claim is that two frontends compile into one IR and
that one runtime executes it. This turns the claim into a test.

GS-12 is a concrete DSL scenario with an XML twin that says the same thing.
`golden.py compare-pair` runs both and asserts the traces are equal byte for
byte — not close, equal — and the check is part of check-all, so CI verifies it
on macOS, Linux and Windows on every push.

Making the pair identical took two things worth recording. The XML twin sets its
Performance limits to zero, because §8.7 declares no performance limits at all
and an unstated clamp on one side would diverge the traces. And it carries a
Storyboard stop trigger at t = 9, because §7.6.2 says a DSL scenario ends when
its `do` directive does — the XML twin has to say the same thing, and the
Storyboard is the only place XML can say it.

GS-13 covers what has no XML counterpart at all: a parallel nested in a serial,
a placement modifier, a relative-speed modifier, and a `one_of` whose
alternative is an input rather than a draw.

The parity claim is made on GS-1's longitudinal shape rather than the planned
GS-2 cut-in, and golden-scenarios.md now says why: §8.9's `lateral` modifier
lowers to a LaneOffsetAction while GS-2's XML uses a LaneChangeAction, whose
transition time comes from maxLateralAcc rather than a duration (ADR-0016). A
pair built on those would compare two things never claimed to be equal.

Adds the user-guide page the pillar owes: how each language reaches the same IR,
and every place the two standards genuinely differ — the absent performance
limits, `animal`, implementation-defined entry points, `one_of`, the three
§8.8/§8.9 name collisions, the two §8.15 contradictions, and #110.

13 golden scenarios, 47 checkpoints. 1392 gtest + 194 pytest unchanged.
@JArmandoAnaya
JArmandoAnaya merged commit 9c5427c into main Aug 2, 2026
12 checks passed
@JArmandoAnaya
JArmandoAnaya deleted the feat/p8-s4-parity branch August 2, 2026 14:56
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.

[p8-s4] XML-DSL parity & DSL golden scenarios

1 participant