docs(proposal): spec authorable message definitions

[ako]

Spec only — no code. Opens the design for review before anything is built.

Why this one

A mapping binds to one of four schema sources, and MDL can create exactly one.
Measured across all 327 import/export mappings in the nine demo apps:

source	mappings	authorable
JSON structure	250 (76.5%)	yes
message definition	74 (22.6%)	no
XML schema	3 (0.9%)	no
imported web service (SOAP)	0 in the corpus	no — now refused rather than dropped (#365)

Message definitions are the one remaining source that is both worth doing and
doable. An XML schema holds an imported .xsd and a WSDL holds its schema
entries inline — authoring either means a foreign parser. A message definition
holds nothing external: it is a selection over the domain model.

The measurement

All 36 collections / 56 definitions / 4,686 elements. Four element types,
every property present on every instance, no optional keys.

Almost everything is a constant or derived — MinOccurs=0, Nillable=true,
MaxLength/FractionDigits/TotalDigits=-1, all four text fields empty, in
4,686 of 4,686. The author chooses only the collection name, each definition's
name, its root entity, the members, and an optional rename.

Two findings that shape the syntax

MaxOccurs is not a function of the association's type. All 927 resolvable
associations are Reference, yet 526 carry 1 and 401 carry -1. It tracks the
direction of traversal, with zero counter-examples:

holder is	MaxOccurs	count
the association's FROM entity (child → parent)	1	496
the association's TO entity (parent → children)	-1	401

Get it backwards and the definition exposes a list as a single object — with no
build error behind it. So the statement names the target entity
(Assoc/Module.Entity, the shape import and export mappings already use) and
direction becomes explicit in the source rather than inferred.

Studio Pro pluralises a repeating element's ExposedName while keeping
ExposedItemName at the singular — 461/461. Reference→References (386),
Factory→Factories (71), Parts→Parts (4).

ExposedItemName is free; the plural is not. The proposal recommends not
implementing English inflection — default to OriginalName, as 'Orders' to
override — the same conclusion as #272's array-item naming and for the same
reason. The cost is stated rather than buried: without as, an mxcli-written
definition differs from a Studio-Pro one on every repeating element. Requiring
as instead is flagged as the reviewable alternative.

Proposed syntax

create message definition collection Sales.MD_Order (
  definition Order for Sales.Order as 'Orders' (
    OrderId,
    Total,
    Sales.Order_Line/Sales.Line as 'Lines' ( Sku, Quantity ),
    Sales.Order_Customer/Sales.Customer ( Name, Email )
  )
);

Plus DROP, DESCRIBE (re-executable) and SHOW — there is no listing today
at all. OR MODIFY preserves the UUID, because mappings reference the collection
by qualified name.

What a reviewer should push on

• Require as on a repeating element? It removes the silent divergence from
  Studio Pro at the cost of friction.
• Inherited attributes are scoped out pending measurement — the proposal says
  refuse rather than guess. Is that the right call, or should it block?
• Legacy engine: author it there too, or modelsdk-only like rules, menus and
  layouts?

Method note

The census was read through mprbson.units(), not by grepping the extracted
tree. Grep only sees units that are files — MPR v2 only — and an MPR v1
project keeps them in the SQLite Unit.Contents blob. That is exactly how an
earlier XML-schema count came back as zero when the answer was three (#259
follow-up, #363).

🤖 Generated with Claude Code