Skip to content

Commit 1833870

Browse files
committed
📝 Define reader-close cancellation commit boundary (#730)
1 parent eb92602 commit 1833870

3 files changed

Lines changed: 92 additions & 19 deletions

File tree

‎architecture.md‎

Lines changed: 50 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2917,16 +2917,48 @@ The grid runs as one structured scope:
29172917
6. Once attached, each pane settles independently and keeps its final status
29182918
visible while siblings continue. The composite remains present after all
29192919
panes settle until the reader closes or leaves it.
2920-
7. Closing begins an ordered teardown: prevent new pane launches, cancel live
2921-
pane scopes, await every child and finalizer, detach and destroy the exact
2922-
provider composite, restore the root terminal, and only then release the
2923-
foreground lease and settle the grid. The document never continues while an
2924-
observable pane child or provider-owned process can still act through the
2925-
grid.
2920+
7. Reader close first crosses a live close boundary, then begins an ordered
2921+
teardown: prevent new pane launches, ask live pane children to close, await
2922+
every child and finalizer, detach and destroy the exact provider composite,
2923+
restore the root terminal, and only then release the foreground lease and
2924+
settle the grid. The document never continues while an observable pane child
2925+
or provider-owned process can still act through the grid.
2926+
2927+
The provider's `closed()` settlement proposes the live close boundary. The
2928+
boundary is crossed when the grid owner has entered a cancellation-deferred
2929+
await of the grid's durable child and acknowledges that proposal; only then may
2930+
the child signal pane close. That await ends only when the task has settled and
2931+
its durable `Close` has been acknowledged, not when the grid body has merely
2932+
chosen an outcome. This handshake has no provider identity and is not itself
2933+
journaled.
2934+
2935+
Reader-close intent becomes durable only as that completed grid `Close`, after
2936+
pane and provider teardown. There is no standalone durable "closing" state. The
2937+
gap between observing close and committing it is safe because ordinary parent
2938+
cancellation is held pending across the whole gap. A cancellation that arrives
2939+
before the owner acknowledges the close boundary cancels the active grid. One that arrives
2940+
afterward does not rewrite grid or pane outcomes: panes already settled keep
2941+
their outcomes, each then-live pane completes its own scope and retains
2942+
`closed`, and the grid retains the same `reader` or `failed` result it would
2943+
have retained without the cancellation. Once the grid child is durably closed,
2944+
the pending cancellation is delivered to the parent, so no following document
2945+
sibling runs in that attempt. A fatal or cleanup failure still takes its
2946+
existing precedence over cancellation.
2947+
2948+
Pane work and every finalizer it installs live inside that pane's durable child
2949+
scope. Reader close is cooperative at the durable boundary: it asks the pane to
2950+
close and awaits it; it never halts the pane's durable task. The pane may stop
2951+
its live nested work as part of its own scope teardown, but its durable child
2952+
does not settle as `closed` or write `Close(ok)` until that work and its finalizers
2953+
have settled. This preserves the pane's ordinal-derived identity and never
2954+
turns a deliberate reader close into a caller-cancelled durable child that a
2955+
later run could revive or wait on forever.
29262956

29272957
Parent cancellation follows the same teardown from preparation, readiness, or
2928-
the active grid and remains cancellation. A provider or host failure cancels
2929-
the whole grid and is the grid's canonical failure. An ordinary pane failure
2958+
the active grid and remains cancellation. Once reader close has crossed its
2959+
live boundary, the close result is committed first and that cancellation is
2960+
observed by the parent afterward. A provider or host failure cancels the whole
2961+
grid and is the grid's canonical failure. An ordinary pane failure
29302962
after attachment is contained as that pane's status and does not cancel its
29312963
siblings. When the reader closes the grid, core fails it with the first failed
29322964
pane in authored order; cancellation initiated by grid teardown is not a pane
@@ -2977,6 +3009,16 @@ a terminal provider, starting a shell, expanding pane content, acquiring an
29773009
Agent session, or launching a native UI. The structured durable boundary owns
29783010
that short circuit; a public replay context does not.
29793011

3012+
The reader-close handshake makes cancellation during teardown a completed-grid
3013+
case rather than a new partial-replay state. When a pane finalizer delays close
3014+
and parent cancellation arrives, the first attempt still finishes every pane
3015+
and provider finalizer, writes the pane outcomes and completed grid `Close`, and
3016+
only then reports cancellation to its parent. A continuation claims that
3017+
completed child and resumes after it without recreating the provider or
3018+
re-entering pane work. A host loss can still interrupt the unjournaled live
3019+
teardown; panes whose `Close` was acknowledged remain complete, while any pane
3020+
and grid without a completed record follow the existing partial-replay rules.
3021+
29803022
Partial replay compares the **resolved** layout and refuses divergence before
29813023
provider work.
29823024

‎packages/durable-streams/specs/DECISIONS.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -567,11 +567,13 @@ Updated before completion of every phase and committed at the end of each phase.
567567
*awaits* a task it previously halted has diverged, and divergence is the
568568
honest answer there rather than a silent revival.
569569
- **Consequences:** Terminal grids get what they need without reviving anything
570-
deliberately stopped. A grid halts each pane task when the reader closes, so
571-
those panes retain `"caller"` — and the grid child completes, so a resumed run
572-
short-circuits the whole region and never reaches them. The case that must
573-
resume — the run interrupted while the grid is open — unwinds the grid and
574-
pane children, retains `"unwound"`, and continues.
570+
deliberately stopped. Reader close cooperatively closes each pane inside its
571+
durable child and waits for that child to retain `closed`; it does not halt
572+
the durable pane task. Once reader close takes effect, later parent
573+
cancellation is deferred through pane and grid completion, so a resumed run
574+
short-circuits the completed grid and never reaches those panes. The case that
575+
must resume — the run interrupted while the grid is still active — unwinds
576+
the grid and pane children, retains `"unwound"`, and continues.
575577
- **Scope:** The reason is retained evidence, not authority. Nothing reads it
576578
from outside `runDurableChild`, no public API exposes it, and no caller
577579
chooses a policy: the policy stays fixed at each combinator's call site.

‎specs/executable-mdx-spec.md‎

Lines changed: 35 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8682,11 +8682,23 @@ selects success or failure; a live pane cancelled only because the reader
86828682
closed the grid becomes `closed`. These states display core's result and never
86838683
author it.
86848684

8685-
Close first prevents new pane launches, then cancels live pane scopes, awaits
8686-
every child and provider finalizer, destroys the exact composite, restores the
8687-
root terminal, and releases the foreground lease. Only then does the element
8688-
settle and a later document sibling begin. There is no implicit timeout; parent
8689-
cancellation and an enclosing execution deadline use the same complete teardown.
8685+
The provider's `closed()` operation proposes reader close. Reader close takes
8686+
effect when the grid owner has entered a cancellation-deferred await of the
8687+
grid's durable child and acknowledges that proposal. Before that acknowledgement
8688+
reaches the child, no close signal reaches a pane. Close then prevents new pane
8689+
launches, asks every live pane child to close, awaits every child and provider
8690+
finalizer, destroys the exact composite, restores the root terminal, and
8691+
releases the foreground lease. The deferred await ends only after the durable
8692+
child has settled and its `Close` has been acknowledged. Only then does the
8693+
element settle and a later document sibling begin. There is no implicit timeout;
8694+
parent cancellation and an enclosing execution deadline use the same complete
8695+
teardown.
8696+
8697+
Pane work and the finalizers it installs are scoped inside that pane's durable
8698+
child. Reader close does not halt that durable child. It cooperatively closes
8699+
the pane's live work and the child retains `closed` only after its work and
8700+
finalizers have settled. A pane that had already succeeded or failed keeps that
8701+
outcome.
86908702

86918703
#### Native launch ownership inside a pane
86928704

@@ -8721,6 +8733,12 @@ continues.
87218733

87228734
A provider or host failure cancels the composite and is the grid failure.
87238735
Parent cancellation remains cancellation rather than becoming a pane failure.
8736+
If it arrives after reader close takes effect, reader close still decides the
8737+
grid and pane outcomes: then-live panes retain `closed`, already-settled panes
8738+
keep their outcomes, and the grid retains `reader` or `failed` under the normal
8739+
authored-order rule. The cancellation remains pending until complete teardown
8740+
and the grid's durable close, then reaches the parent before any following
8741+
document sibling runs. A fatal or cleanup failure keeps its existing precedence.
87248742
All acquired resources are finalized even when an earlier failure already
87258743
decides the result, and the existing fatal-infrastructure and cleanup precedence
87268744
still applies. Before the first cancellation signal, the provider snapshots
@@ -8758,6 +8776,16 @@ claims that whole region and restores its result without contacting a terminal
87588776
provider, creating a composite, starting a shell, expanding pane content,
87598777
resolving an Agent, taking session ownership, or launching a native UI.
87608778

8779+
Reader-close intent has no separate durable `closing` state. It becomes durable
8780+
as the completed grid `Close`, after all pane and provider teardown. The live
8781+
handshake described above holds later parent cancellation across that interval,
8782+
so cancellation during a blocked pane finalizer still produces completed pane
8783+
and grid records before it reaches the parent. A continuation therefore claims
8784+
the completed grid and proceeds without waiting on or re-entering a pane the
8785+
reader closed. If the host itself disappears before completion, the journal has
8786+
no completed grid close and the ordinary partial-replay rules apply; any pane
8787+
whose completed `Close` was acknowledged remains settled.
8788+
87618789
Partial replay compares the **resolved** layout first — the column count and
87628790
each pane's title — and refuses a change before the foreground lease is taken
87638791
and before any provider is contacted. It then builds a new live composite.
@@ -10768,7 +10796,8 @@ test derives a core result from a provider identifier.
1076810796
| TG15 | Completed replay | A completed successful or failed grid restores its exact result while contacting no terminal provider, shell, Agent provider, coordinator, pane content or native launcher |
1076910797
| TG16 | Partial replay | Exact layout rebuilds a fresh provider composite; completed pane children appear settled without effects, incomplete paired children follow their durable records, incomplete native launches preserve prepared/detached session identity, and an incomplete shell starts current host policy without terminal-history continuity |
1077010798
| TG17 | Replay divergence and retained shape | A resolved layout change — `columns` or a `title`, reached through a prop-borne value, because a continuation executes the retained root — refuses before the lease and before provider contact, with zero provider observation. Pane count, order and form cannot differ under a fixed retained root, so they are proved retained and honoured rather than refused: the complete authored structure appears in the record, and a continuation whose supplied file differs in count, order or form opens the retained structure rather than the file's. Retained layout, close kind and pane outcomes contain no provider command, socket, process, session, window or pane identifier, path, argv, environment or terminal bytes |
10771-
| TG18 | Provider neutrality | The controlled non-tmux provider passes TG1–TG17; the tmux adapter prepares one hidden invocation-private server with authenticated persistent pane workers, transmits exact child creation outside tmux parsing, applies explicit row-major layout, distinguishes visible detach from control loss and server stop, attaches only after runtime spawn readiness, and satisfies TG14 without leaking provider identifiers; Node and Bun validate the same document and refuse before pane start with no provider installed |
10799+
| TG18 | Provider neutrality | The controlled non-tmux provider passes TG1–TG17 and TG19; the tmux adapter prepares one hidden invocation-private server with authenticated persistent pane workers, transmits exact child creation outside tmux parsing, applies explicit row-major layout, distinguishes visible detach from control loss and server stop, attaches only after runtime spawn readiness, and satisfies TG14 without leaking provider identifiers; Node and Bun validate the same document and refuse before pane start with no provider installed |
10800+
| TG19 | Reader close crossed with parent cancellation | A controlled live pane enters a signal-held finalizer after reader close takes effect. Parent cancellation begins while teardown is blocked; releasing the finalizer lets pane and provider teardown complete, retains the pane as `closed` and the grid with its reader-close result, and only then delivers cancellation to the parent. A continuation neither contacts the provider nor enters pane work, does not hang, and proceeds from the retained grid outcome. Provider-resource and following-sibling observations prove both sides of the ordering; no elapsed duration is evidence |
1077210801

1077310802
### Tier CR — Component registration and resolution
1077410803

0 commit comments

Comments
 (0)