diff --git a/changes/unreleased/execution-choice-points.added.md b/changes/unreleased/execution-choice-points.added.md new file mode 100644 index 000000000..225bfe1f9 --- /dev/null +++ b/changes/unreleased/execution-choice-points.added.md @@ -0,0 +1,18 @@ +- **The executors report every choice point: a pick among alternatives the library leaves + unordered.** Several steppable tokens in one action step, several holding guards at a decision + node, several enabled transitions out of one state for one event or one change, and several + tokens writing one feature in one step are each recorded as a `choice` trace line naming the alternatives and the + one taken (`choice step 3: tokens 2@left, 3@right (unordered; took 3@right first)`), as an + informational diagnostic on `ExecuteAction`, `ExecuteState` and `RunAnalysis` responses, and as + one summary line after `%step`, `%continue` and `%advance` (`2 choice points; %trace on to see + them`). What the executor does is unchanged — reverse token order, first holding guard, first + declared transition — so every existing result and trace is the same: the guards and + transitions after the first that holds are read in a preview that is undone, and one that + cannot be evaluated there is not an alternative and not an error but an informational + `guard-unevaluable` diagnostic, an `unevaluable guard` trace line and a count in the summary + (`1 guard not evaluable`). Writes to the performing part and through a feature chain count as + the object's, so two chains reaching one object in one step are one conflict, as are a feature + and one redefining it; a step's writes to one feature are one choice listing every token's last + write, recorded once the step is complete. The + innermost-transition-wins rule between a substate and the state enclosing it is spec-defined + order and is not reported. diff --git a/docs/guide/06-behavior.md b/docs/guide/06-behavior.md index 55e791bbb..e929fa9df 100644 --- a/docs/guide/06-behavior.md +++ b/docs/guide/06-behavior.md @@ -187,6 +187,27 @@ the state or the data a guard reads changes between the send and the dispatch, t - `%advance