Pause XMD expansion in one REPL execution without cancelling it

[taras]

Story

As a person inspecting live XMD execution, I want Pause to stop further XMD expansion in one visible execution subtree without cancelling it, so I can inspect earlier History checkpoints and then continue the same in-memory work.

Example

A document is expanding while a background provider request and an independent sibling execution are still running. Pause changes the selected execution from playing to pausing. It becomes EXPANSION PAUSED once every active XMD expansion walk in that subtree is held at an existing expansion boundary or has settled.

The background request may finish and append its durable outcome to the Journal while expansion remains paused. The expansion pause point stays fixed even though the live History head advances. Continue releases the held expansion continuations exactly once; it does not replay the recorded outcome or reconstruct the execution.

Current gap

The REPL does not yet install a production pause controller around XMD execution. Effection provides the runtime and continues running ordinary tasks, but the REPL needs a cooperative boundary that can stop XMD expansion, preserve cleanup and keep unrelated UI and execution work responsive.

The experiment establishes that the existing execution, component, output and REPL-owned expansion surfaces provide that boundary. It does not require a new XMD API, Effection scheduler decoration or runtime-quiescence query.

Contract

• The REPL installs its pause middleware before starting one REPL execution. The controller and retained continuations live for that execution and are inherited by its XMD expansion work.
• While execution is playing, the middleware delegates immediately and produces the same output and Journal records as unmediated execution.
• Pause is cooperative. Requesting it changes the controller to pausing synchronously. Work already between expansion boundaries may continue until it reaches the next controlled boundary or settles.
• An active expansion walk is one bracketed unit of XMD expansion. The root document, projected component content and REPL-owned expansion regions create walks; component, code-block and output operations provide step gates inside them.
• The controller reports paused only when every active expansion walk in the selected subtree is held at a controlled boundary or has settled. Concurrent child walks are included before their parent is considered paused.
• paused means XMD expansion is stopped. It does not mean Effection is quiescent, external systems are frozen or the durable Journal head is stationary.
• Ordinary Effection tasks continue normally and are not pause obligations. Work that produces a durable outcome appends it to the Journal normally while expansion is paused.
• No later XMD element or rendered output expands until Continue, including work triggered by a background outcome.
• Sibling executions outside the selected subtree remain live and may continue expanding and recording.
• Continue releases the same retained expansion continuations exactly once. It does not halt, replay or reconstruct them, and it does not append an already-recorded background outcome again.
• Completion, failure, explicit interruption and CLI shutdown while pausing or paused unwind every owned child and resource. Interruption and shutdown unwind a hold instead of releasing it into ordinary execution.
• The controller and retained continuations are ephemeral REPL state and never enter the durable Journal. The UI may project their status without owning the gate.
• The expansion pause point and the live History head are separate positions. The interface calls the mode EXPANSION PAUSED, never paused at head.
• Process restart is not Continue: the in-memory continuation is gone and Journal replay owns later resumption.
• Pause remains a REPL concern. Production adds no public or core XMD pause API and does not reach into Effection reducer or scheduler internals.

Acceptance

• A real XMD execution reaches EXPANSION PAUSED while ordinary descendant Effection work continues.
• Every active concurrent expansion walk is held or settled before paused; allowing one walk to keep expanding makes the test fail.
• Removing the middleware restores byte-identical pass-through output and Journal records.
• A background operation finishes while expansion is paused, appends one durable Journal event, and does not advance the expansion pause point.
• Continue resumes every held expansion continuation exactly once and never duplicates the background event.
• An execution outside the selected subtree continues expanding and recording throughout the paused interval.
• Explicit interruption from paused produces a terminal interrupted outcome and complete teardown without releasing held work.
• CLI-style owner shutdown from paused unwinds holds and retained resources without reporting successful completion.
• Failure during coordination propagates to the execution owner.
• A boundary inventory covers every exercised route by which the representative document can expand, including rendered prose and output.
• Restoring descendant-Effection-scope completeness leaves the real execution stuck in pausing, proving runtime quiescence is not the contract.

Evidence

• Decision: RETAIN.
• Feedback commit: 380e02c4, based on 935ec987, in draft PR 🧪 POC stack: render, route, compose, pause, and reconstruct the XMD REPL (#838–#842) #844.
• Focused test: deno task test scripts/tests/repl-pause-gate.test.ts.
• The test includes negative controls for premature pause, an ungated expansion path, suppressed and duplicated Journal appends, descendant-scope completeness and releasing holds during unwind.

Dependencies

• Parent: Quest: Run, inspect, and resume XMD execution in the REPL #827
• Production sequencing begins after the non-merging POC stack has settled.

Out of scope

• Terminal rendering, routing and StarFX.
• Durable process-restart replay.
• Automatically reconciling external environment changes.
• Production integration with XMD components or Agent providers.
• Pausing arbitrary Effection continuations or external systems.
• A new public or core XMD pause API.

[taras]

Experiment conclusion: RETAIN

A REPL-installed, pass-through middleware controller can pause and resume one real XMD expansion using existing XMD surfaces. It needs no new core XMD API and does not control Effection scheduling.

Retain these production contracts:

• The REPL installs the controller before starting the execution. While playing, the middleware is transparent.
• Existing expansion brackets identify active walks: Execution.document, Component.content, Component.tryContent and the REPL profile's expand handler. Existing mediated operations are step gates within those walks.
• A walk is satisfied when it holds a continuation or delegates to active child walks, and every active child is satisfied. The controller reports paused only when at least one walk is active and every active walk is satisfied.
• Ordinary Effection scopes and tasks are not pause obligations. Timers, subprocesses and background work continue normally.
• The mode is EXPANSION PAUSED, not “paused at head.” The expansion pause point stays fixed while already-running work may append durable outcomes and advance the live Journal head.
• Continue releases the same held continuations exactly once and never replays work. Interruption and owner shutdown unwind holds instead of releasing them into ordinary execution.
• The controller and held continuations are process-local. Restart is not Continue; durable replay owns resumption after process loss.
• A production boundary-inventory test must fail when a new XMD expansion path bypasses the controlled surfaces.

The representative real execution reached EXPANSION PAUSED while 25 Effection scopes remained live, ordinary component children advanced and a background result appended exactly once. Expansion emitted no further element or output until Continue.

Production starts afresh from main; the POC implementation is not merged or cherry-picked. The full evidence remains in draft PR #844 and its scripts/repl-pause/RESULT.md record.