Define root action-chain completion and reevaluation suppression scope #121

Current state

The action-chain implementation in #114 accepts a root such as @A, @B, but pop() returns immediately when the stack has only one frame. A therefore cannot complete or initialize B. A root action without a successor also cannot signal completion. #122 preserves this behavior and adds regression coverage; it does not choose a new root completion model.

Reevaluation suppression is a DSD-wide flag. do_not_reevaluate() skips the next ancestor-reevaluation pass; an action with r:false or reevaluate:false renews the flag while executing. Advancing to a chain successor retains a pending flag, so it can affect the successor even if that successor is a decision or subtree. Ordinary completion without a successor, interruption, and behavior replacement clear it. Suppression is not an independently represented critical section.

Problem and relevance

Root chains are accepted but cannot make progress through the normal action completion API. Users need either a load-time rejection or a defined way to advance and finish a behavior. Choosing “repeat”, “idle”, or “completed” also affects scheduling, restart, cleanup, and debug output.

Suppression can outlive the action that requested it. That may preserve an intended uninterrupted sequence, or delay an ancestor check unexpectedly. Resetting it everywhere could also change existing motion behaviors. The scope needs to be explicit before changing it.

Options for root completion

1. Reject root action chains during loading. Require a selecting root decision for chains; retain the permanent-root execution model.
   • Benefits: smallest change; converts a behavior that cannot progress into a clear source error.
   • Caveats: prevents finite top-level chains and does not give a sole root action completion semantics.
2. Allow the sole action frame to advance and finish. Retain the declared root as the restart target. After the final action completes, enter an explicit completed/idle state; only interrupt() or a new load restarts execution.
   • Benefits: root chains behave like nested chains; finite behaviors are expressible without hidden stack frames.
   • Caveats: requires a completion state/API, no-op updates after completion, defined empty debug snapshots, and tests for callers assuming the root always remains active. Automatic repetition would need a separate explicit policy.
3. Introduce an internal root/sentinel frame. Give every behavior a parent that handles completion and restart policy.
   • Benefits: uniform completion handling; ordinary action popping can retain a permanent internal root.
   • Caveats: changes stack shape and potentially visualization/introspection; hiding the sentinel creates another distinction between internal and public stacks. A final completion policy is still required.

Options for suppression

1. Retain the current compatibility scope. Specify when the flag is consumed, renewed, retained, and cleared, including successors that are decisions.
   • Benefits: preserves existing behavior timing.
   • Caveats: suppression remains implicit state that can cross element boundaries; it provides no priority or guard-path guarantees.
2. Add action-scoped suppression. Clear suppression when leaving an action, including chain transitions, initially behind an explicit opt-in policy.
   • Benefits: lifetime follows the requesting action; successors do not inherit it unexpectedly.
   • Caveats: uninterrupted multi-action operations need another mechanism; changing the default requires auditing consumers.
3. Represent critical sections explicitly. Define their entry/exit, cancellation, and any ancestor checks that must remain active.
   • Benefits: intentional multi-action scope and clearer interruption rules.
   • Caveats: substantial runtime/API design; requires concrete use cases and priority semantics rather than another global flag.

Recommendation

For roots, prefer option 2 with explicit idle completion and explicit restart. First audit callers that assume a permanent root, and define cleanup, update results, and debug snapshots for the completed state. If that work is deferred, reject root chains rather than continuing to accept non-progressing behavior files.

For suppression, retain option 1 as the compatibility default and add option 2 for applications that want action-local behavior. Audit existing r:false/do_not_reevaluate() usage before changing the default. Pursue option 3 only with concrete multi-action interruption requirements. Resolve root completion and suppression independently; expected failure outcomes are discussed in #115.

I am working on behalf of @jaagut.