Schema: action parameters and results

The gap

An action is {name, actor, preserves, description}. There is no way to declare what an action takes or what it reports back, so any contract about an action's output lives in freeform description text.

Motivating example, from modeling a diagram tool. Three separate decisions in one modeling session turned out to be about action results, and none of them was declarable:

• Deleting a container recurses, and the result lists every node removed.
• Deleting a shape converts bound arrow endpoints to free points, and the result warns about each conversion.
• Dropping a stored overlap expectation as a side effect of a delete is reported in the result.

Each is a "no surprises" contract: the caller learns everything the operation did. Today each is a sentence inside an invariant or a description, for example:

- id: container-delete-recurses
  statement: >-
    Deleting a `Container` deletes its whole subtree. The
    operation's result lists every node removed.

The rule (preserves can point at it) and the report shape (nothing can) are fused into one prose statement.

Possible shape

Optional inputs and reports lists on the structured action form, each entry a name plus a type (primitive, enum, or entity name). This is deliberately short of a full signature language; the value is that the report contract becomes a checkable, renderable part of the model rather than prose. Lint could warn when a reports entry names an unknown entity, matching existing reference checks.

This may be over the line of what a plain-language modeling tool wants to carry; filing it as a data point from real usage rather than a firm request.

Workaround today

Prose in invariant statements and action descriptions.

Start by reading the existing structured action schema and reference-checking or lint paths; the issue names no files or tests. Compare how action fields are modeled and rendered, then clarify whether inputs and reports belong in scope, including unknown-entity validation. Done means the agreed contract is represented and checked without relying on prose.