retrieve … first is the object; limit 1 is a list of one under mdl 1 (#734)

[ako]

Closes #734 (plan item 2.5 of PROPOSAL_mdl_beta_syntax_freeze.md, §5 item 2; ADR-0011).

What changes

• retrieve … first is Mendix's "First object" range (ConstantRange, SingleObject) in every language version.
• Under mdl 1;, a bare retrieve … limit 1 is a Custom range: a list of one.
• Without the header (mdl 0), limit 1 keeps its alpha meaning, the object. check/exec warn MDL-V1-LIMIT1, a langver.Change declared in mdl/visitor/visitor_retrieve_range.go.
• describe prints the object range as first. That text means the same under any header.
• The visitor resolves the meaning into the new RetrieveStmt.First. The writer, the flow builder's variable typing, the validator's typing and MDL-RETRIEVE01 all read that field and never read limit text.
• MDL-RETRIEVE01 is adjusted, not retired. It keys on the object range, whichever spelling produced it. It stays because treating an object as a list is still a build error that check --references does not otherwise catch. The message now says CE0100 for a loop: mx check 11.13 reports a loop over an object as CE0100, not CE0097.
• Docs: CLAUDE.md idiom 5, the quick reference, the syntax topic, the skills and the docs-site pages now teach first for an object. There is also a CHANGELOG entry.

Design choices the ADRs did not settle

• first does not combine with limit or offset. The grammar is first | [limit n] [offset n], because Mendix's object range has no offset.
• first on an association retrieve is refused (a new construct, so this is no new rejection of an existing script). Mendix gives that source no range, so the keyword would be dropped.
• Which texts count as "bare limit 1" is the exact condition the alpha writer used: limit text 1 and no offset. limit (1), limit $One and limit 1 offset n were already lists, and they neither change nor warn.
• Variable typing fix. The builder typed limit 1 offset n as an object while the writer stored a list. It now follows the stored range (a list), because it reads First.
• Remaining gap under mdl 0: a Studio Pro Custom range with limit 1 and no offset still describes as limit 1. Re-running that output without a header therefore turns it into an object, as it did before. The difference now is that the run warns MDL-V1-LIMIT1. mdl 0 has no spelling for that range. It round-trips once describe emits the mdl 1; header at beta (langver.Frozen).
• Version lookup: the statement builders are free functions, so languageVersionOf(tree) reads the header from the parse-tree root. This is the same approach as MDL list operations as one statement per Studio Pro activity; set mandatory under mdl 1 (#733) #737's scriptLanguageVersion. Whichever PR merges second should fold one into the other.

Test plan (what I ran)

• make build; make lint (Go + TS) passed.
• go test -count=1 ./mdl/visitor/ ./mdl/executor/ ./mdl/ast/ ./mdl/grammar/... ./mdl/formatter/ ./mdl/linter/... ./cmd/mxcli/... passed.
• go test -tags integration ./mdl/roundtrip/ passed. The allowlist is unchanged: PopulateUserAttributes stays getput-allowlisted for Round-trip harness: untracked describe → exec losses on the Studio Pro fixture (microflows, entities, pages, snippets, menus, roles, JS actions) #721.
• go test -tags integration ./mdl/executor/ -run TestRoundtripMicroflow_RetrieveWith passed. Its expectation was updated to first.
• New tests:
  • mdl/visitor/retrieve_first_test.go: each spelling under both versions, plus the refusals.
  • mdl/executor/cmd_microflows_retrieve_first_test.go: the stored range and variable type per version, the describe spelling, and check (MDL-V1-LIMIT1 / MDL-RETRIEVE01) per version.
  • mdl/roundtrip/retrieve_range_test.go on the Studio Pro-authored PedApp (FeedbackModule.PopulateUserAttributes):
    • The object form: describe prints first, and exec under both headers keeps the ConstantRange and PutGet.
    • The list form: exec under mdl 1 stores a CustomRange with limit 1, and its describe → exec under mdl 1 keeps it (PutGet).
    • Control: the same text run without the header stores the object range and warns once.
• Revert checks (each revert made the named tests fail):
  1. Ignoring the version in the visitor (limit 1 is always the object) failed TestRetrieveLimitOne_Mdl1IsAListOfOne.
  2. Making describe print limit 1 for the object range failed TestFormatAction_Retrieve_RangeSpelling and TestPedAppRoundTrip_RetrieveRange.
  3. Restoring the builder's old limit-text logic failed four cases of TestRetrieveRange_WrittenPerLanguageVersion.
• Mendix validation (mxcli docker check, mxbuild 11.13.0) on a copy of the Studio Pro project TestApp (baseline: 0 errors):
  • An mdl 1; script with a loop over limit 1 and a first object gave 0 errors.
  • The same script without the header is refused by check/exec (MDL-RETRIEVE01). Forced with --no-check, mx reports CE0100 'Users' is of type System.User, but should be of type List.

🤖 Generated with Claude Code