docs(proposal): add targeted ALTER for message definitions, and the nesting measurement that requires it

[ako]

Follow-up to #371, which merged the first draft of this proposal. Docs only.

What changed and why

The first draft had only collection-level CREATE / DROP / DESCRIBE /
SHOW, resting on an unstated assumption that a message definition is a flat
field list. Measuring the corpus shows it is not. Definitions nest to
depth 7:

depth	0	1	2	3	4	5	6	7
elements	56	356	265	142	208	477	974	2,208

Most elements sit at depths 5–7. Object elements carry a mean of 4.7 members,
with a tail out to 22.

So a whole-document CREATE OR MODIFY is a poor tool for "expose one more
attribute": restating a seven-level document to add a leaf is exactly the
diff-unfriendliness ADR-0003
argues against, and is why ALTER ENTITY ADD ATTRIBUTE exists rather than only
CREATE OR MODIFY ENTITY.

Added

alter message definition collection Sales.MD_Order
  add definition Line for Sales.Line as 'Lines' ( Sku, Quantity );
alter message definition collection Sales.MD_Order drop definition Line;
alter message definition collection Sales.MD_Order rename definition Line to OrderLine;

alter message definition Sales.MD_Order.Order add member Total;
alter message definition Sales.MD_Order.Order drop member Sku in Lines;
alter message definition Sales.MD_Order.Order set member Total as 'GrandTotal';

Collection-level ALTER matters for the 8 collections holding more than one
definition; member-level ALTER applies to all 36.

Three choices a reviewer should push on

• Module.Collection.Definition as the address — the same three-part
  reference WITH MESSAGE DEFINITION already takes, so the two cannot drift
  apart.
• SET member … AS, not RENAME … TO. ALTER ENTITY RENAME ATTRIBUTE
  renames in the model and rewrites every reference to it; this changes only the
  element's ExposedName and touches nothing else. Borrowing the verb would
  promise something far larger than it delivers.
• in <path> for a nested member, written in exposed names, rather than a
  /-joined name — / already means "association to entity" inside a member
  (Sales.Order_Line/Sales.Line), and overloading it in the same clause would be
  ambiguous to a reader even where the grammar could tell them apart.

Deliberately not designed

A wildcard member (( * ) for "expose every attribute"). Studio Pro's UI is a
checkbox tree, so it is a natural thing to want, and with a tail out to 22
members it would save real typing — but * appears nowhere else in MDL and
nothing in the corpus says anyone wants it. Raised as an open question instead
of proposed, on the same principle that killed the import group = node.

Also

The verification plan gains the control that matters for ALTER specifically: add
one member and assert every other element is byte-identical — that is what
separates a targeted edit from a rebuild that happened to produce the same
result.

🤖 Generated with Claude Code