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.
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:
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:
The rule (
preservescan point at it) and the report shape (nothing can) are fused into one prose statement.Possible shape
Optional
inputsandreportslists 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 areportsentry 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.