Skip to content

Commit bb5c125

Browse files
committed
♻️ Give one owner the grids a terminal installation issued (#730)
The registry was a Set the authority searched. Two things have to meet before a grid exists — the document submits the authored request and its pane work, a provider presents a composite for that exact object — and nothing held both sides or decided when they had met. The supervisor does: it keeps the entries, converges them by object identity and installation generation, and is where every refusal a presentation can meet now lives. Each grid runs as a task the supervisor keeps, in a scope of its own beneath the operation that submitted it. Beneath, and not beneath the supervisor, because a pane's durable identity and the bindings its content reads are the expansion's: parenting grids to the supervisor's own scope loses both, and the suite says so loudly — pane durable order, pane bindings, the startup-failure paths and the provider-failure path all fail together. That parentage is also what makes a grid impossible to strand, which is worth stating plainly: removing either finalizer the supervisor registers changes no test, because the submitting operation unwinds whenever the call that routed it does and takes the grid with it. They are kept as the supervisor saying what it owns rather than as the thing that makes it true, and the comments say which. Six rows drive the ownership directly, each one finite and signalled rather than timed: a provider that answers without presenting opens nothing, one request opens one grid however often it is presented, a settled grid is gone while the next still opens and its composite was destroyed first, a presenting call that is cancelled leaves no pane and no composite behind, an installation teardown stops the grid still live and waits for it, and a second grid cannot be live beside the first — which is why "every remaining grid" is one grid: the foreground-terminal lease admits a single grid at a time. Everything the refactor was meant to preserve is unchanged and still proven by the rows that already existed: readiness and attachment, per-pane exclusivity, close admission, reader close distinct from cancellation, completed and incomplete replay, exact-request and generation refusals, and pane work that still receives only its PaneTerminal. No document names a registry, a live-grid holder or a supervisor, so no stated contract moved with this.
1 parent 4b1bf53 commit bb5c125

3 files changed

Lines changed: 489 additions & 63 deletions

File tree

‎packages/core/src/terminal/authority.ts‎

Lines changed: 175 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@
2222
* lifecycle owns that, and hands each pane the one `PaneTerminal` it runs on.
2323
*/
2424

25-
import { createContext } from "effection";
26-
import type { Context, Operation } from "effection";
25+
import { createContext, createScope, ensure, resource, until } from "effection";
26+
import type { Context, Operation, Scope, Task } from "effection";
2727
import type { TerminalComposite, TerminalGridRequest } from "@executablemd/runtime";
2828

2929
export class TerminalAuthorityError extends Error {
@@ -44,79 +44,202 @@ export interface TerminalGridAuthority {
4444
present(request: TerminalGridRequest, composite: TerminalComposite): Operation<void>;
4545
}
4646

47-
/** One grid this execution issued, from the authority's side. */
48-
export interface LiveGrid {
47+
/**
48+
* One grid the supervisor has been asked to run, before a composite exists.
49+
*
50+
* The scope is the submitting operation's own. A grid keeps the contexts of the
51+
* expansion that wrote it — its durable child above all, which is what gives its
52+
* panes their identities — so the supervisor owns when a grid stops, never what
53+
* it runs under.
54+
*/
55+
export interface SubmittedGrid {
4956
/** The exact request object core issued. Compared by identity, never shape. */
5057
readonly request: TerminalGridRequest;
5158
/** The installation this grid belongs to. */
5259
readonly generation: object;
53-
/** Run the grid on a presented composite, and keep what it settled to. */
60+
/** Where the grid runs: a scope of its own, beneath the submitter's. */
61+
readonly scope: Scope;
62+
/** Run the grid on a presented composite. */
5463
run(composite: TerminalComposite): Operation<void>;
55-
/** Whether this request has already been presented. */
56-
used: boolean;
57-
/** Whether the grid actually ran to a settlement. */
64+
}
65+
66+
/** What the submitting operation can ask about its own grid afterwards. */
67+
export interface GridSubmission {
68+
/** Whether a provider presented for this request and the grid ran through. */
69+
readonly settled: boolean;
70+
}
71+
72+
/** One submitted grid, and whatever of it is currently live. */
73+
interface Entry extends SubmittedGrid, GridSubmission {
74+
presented: boolean;
5875
settled: boolean;
76+
task?: Task<void>;
77+
destroy?: () => Promise<void>;
5978
}
6079

61-
/** Every grid this execution has issued and not yet finished. */
62-
export interface GridRegistry {
63-
live(): readonly LiveGrid[];
64-
add(grid: LiveGrid): void;
65-
remove(grid: LiveGrid): void;
80+
/**
81+
* Who owns the grids one terminal installation has issued.
82+
*
83+
* Two things have to meet before a grid exists: the document submits the
84+
* authored request and the work its panes do, and a provider presents a
85+
* composite for that exact request. Neither alone starts anything — a
86+
* registration that never routes and a presentation of a request nobody
87+
* submitted both open nothing — and the supervisor is what makes them converge
88+
* by object identity and installation generation rather than by shape.
89+
*
90+
* It holds what it starts. Each grid runs as a task the supervisor keeps, in a
91+
* scope of its own beneath the operation that submitted it — beneath, because a
92+
* pane's durable identity and the bindings its content reads are the
93+
* expansion's, and a grid parented anywhere else is a grid whose panes belong
94+
* to nobody in particular.
95+
*
96+
* That parentage is also what makes a grid impossible to strand: the submitting
97+
* operation unwinds whenever the call that routed it does, and takes the grid
98+
* with it. The supervisor stopping its own entries at installation teardown,
99+
* and stopping one whose presenting call was cancelled, is therefore belt and
100+
* braces rather than the mechanism — deliberately so, because the mechanism is
101+
* a structural property nobody reading this file can see.
102+
*
103+
* Private to core: nothing reachable by importing this package can submit a
104+
* grid, present for one, or ask what is live.
105+
*/
106+
export interface GridSupervisor {
107+
/**
108+
* Register one authored request and its work.
109+
*
110+
* The entry is removed when the submitting operation unwinds — after that
111+
* operation's own finalizers, so the foreground-terminal lease is released
112+
* before the grid stops being something a provider could present for.
113+
*/
114+
submit(grid: SubmittedGrid): Operation<GridSubmission>;
115+
/** Run the grid this exact request names, under this exact generation. */
116+
present(
117+
request: TerminalGridRequest,
118+
composite: TerminalComposite,
119+
generation: object,
120+
): Operation<void>;
66121
}
67122

68-
export function createGridRegistry(): GridRegistry {
69-
const grids = new Set<LiveGrid>();
70-
return {
71-
live: () => [...grids],
72-
add: (grid) => {
73-
grids.add(grid);
74-
},
75-
remove: (grid) => {
76-
grids.delete(grid);
77-
},
78-
};
123+
/**
124+
* Stop one grid and wait for all of it.
125+
*
126+
* Halting the task settles its panes, runs their finalizers and destroys the
127+
* composite; destroying the scope is what releases everything the grid itself
128+
* established. Both are idempotent here, because a grid may be stopped by the
129+
* presenting call that was cancelled, by installation teardown, or by neither.
130+
*/
131+
function* stopGrid(entry: Entry): Operation<void> {
132+
const task = entry.task;
133+
entry.task = undefined;
134+
if (task !== undefined) {
135+
yield* task.halt();
136+
}
137+
const destroy = entry.destroy;
138+
entry.destroy = undefined;
139+
if (destroy !== undefined) {
140+
yield* until(destroy());
141+
}
142+
}
143+
144+
/** Open the supervisor one execution's grids belong to. */
145+
export function useGridSupervisor(): Operation<GridSupervisor> {
146+
return resource(function* (provide) {
147+
const entries = new Set<Entry>();
148+
149+
// Installation teardown. Every grid still live is stopped here and waited
150+
// for. Scope parentage already reaches each one, so this is the supervisor
151+
// saying so itself rather than the only thing that says it.
152+
yield* ensure(function* () {
153+
for (const entry of [...entries]) {
154+
yield* stopGrid(entry);
155+
}
156+
});
157+
158+
yield* provide({
159+
*submit(grid: SubmittedGrid): Operation<GridSubmission> {
160+
const entry: Entry = { ...grid, presented: false, settled: false };
161+
entries.add(entry);
162+
yield* ensure(() => {
163+
entries.delete(entry);
164+
});
165+
return entry;
166+
},
167+
*present(
168+
request: TerminalGridRequest,
169+
composite: TerminalComposite,
170+
generation: object,
171+
): Operation<void> {
172+
const entry = [...entries].find((candidate) => Object.is(candidate.request, request));
173+
if (entry === undefined) {
174+
throw new TerminalAuthorityError(
175+
"this grid request is not live: it was copied, rebuilt, kept from another grid, or " +
176+
"belongs to an execution that has finished",
177+
);
178+
}
179+
if (!Object.is(entry.generation, generation)) {
180+
throw new TerminalAuthorityError(
181+
"this grid request belongs to another terminal provider installation",
182+
);
183+
}
184+
if (entry.presented) {
185+
throw new TerminalAuthorityError(
186+
"this grid request has already been presented — one request opens one grid",
187+
);
188+
}
189+
entry.presented = true;
190+
191+
// A scope of its own beneath the submitter's: the grid inherits the
192+
// expansion's contexts, and the supervisor still holds the task.
193+
const [scope, destroy] = createScope(entry.scope);
194+
entry.destroy = destroy;
195+
entry.task = scope.run(() => entry.run(composite));
196+
197+
// A presenting call that unwinds takes its grid with it. The submitter
198+
// unwinding would too, which is why removing this changes no test —
199+
// it is here so the supervisor's ownership does not depend on a
200+
// structural coincidence holding forever.
201+
yield* ensure(function* () {
202+
yield* stopGrid(entry);
203+
});
204+
205+
yield* entry.task;
206+
entry.settled = true;
207+
// Settled, so nothing is owed: the scope goes now rather than waiting
208+
// for the provider's own call to end.
209+
entry.task = undefined;
210+
yield* until(destroy());
211+
entry.destroy = undefined;
212+
},
213+
});
214+
});
79215
}
80216

81217
/**
82218
* Build the authority one provider installation is given.
83219
*
84-
* It closes over the installation's generation and its registry, so a factory
85-
* that kept an authority from a superseded installation presents into a
86-
* generation that no longer has the grid it names.
220+
* It closes over the installation's generation, so a factory that kept an
221+
* authority from a superseded installation presents under a generation the
222+
* supervisor no longer has the grid for. Deciding that is the supervisor's, and
223+
* this is the seam that carries the generation to it.
87224
*/
88225
export function createTerminalAuthority(
89226
generation: object,
90-
live: () => readonly LiveGrid[],
227+
present: (
228+
request: TerminalGridRequest,
229+
composite: TerminalComposite,
230+
generation: object,
231+
) => Operation<void>,
91232
): TerminalGridAuthority {
92233
return {
93234
*present(request, composite) {
94-
const grid = live().find((candidate) => Object.is(candidate.request, request));
95-
if (grid === undefined) {
96-
throw new TerminalAuthorityError(
97-
"this grid request is not live: it was copied, rebuilt, kept from another grid, or " +
98-
"belongs to an execution that has finished",
99-
);
100-
}
101-
if (!Object.is(grid.generation, generation)) {
102-
throw new TerminalAuthorityError(
103-
"this grid request belongs to another terminal provider installation",
104-
);
105-
}
106-
if (grid.used) {
107-
throw new TerminalAuthorityError(
108-
"this grid request has already been presented — one request opens one grid",
109-
);
110-
}
111-
grid.used = true;
112-
yield* grid.run(composite);
235+
yield* present(request, composite, generation);
113236
},
114237
};
115238
}
116239

117-
/** One execution's terminal installation: its registry and its generation. */
240+
/** One execution's terminal installation: its supervisor and its generation. */
118241
export interface TerminalInstallation {
119-
readonly registry: GridRegistry;
242+
readonly supervisor: GridSupervisor;
120243
/** Identifies this execution's provider installation, and nothing else. */
121244
readonly generation: object;
122245
}
@@ -136,10 +259,10 @@ const Installation: Context<TerminalInstallation | undefined> = createContext<
136259
* refusal rather than a way in.
137260
*/
138261
export function* useTerminalInstallation(): Operation<TerminalGridAuthority> {
139-
const registry = createGridRegistry();
262+
const supervisor = yield* useGridSupervisor();
140263
const generation = {};
141-
yield* Installation.set({ registry, generation });
142-
return createTerminalAuthority(generation, () => registry.live());
264+
yield* Installation.set({ supervisor, generation });
265+
return createTerminalAuthority(generation, supervisor.present);
143266
}
144267

145268
/** This execution's terminal installation, or `undefined` outside one. */

‎packages/core/src/terminal/grid.ts‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,6 @@ import { flushOutput, reserveTerminal, TerminalGrids } from "@executablemd/runti
4747
import type { TerminalComposite, TerminalGridRequest } from "@executablemd/runtime";
4848

4949
import { TerminalAuthorityError, terminalInstallation } from "./authority.ts";
50-
import type { LiveGrid } from "./authority.ts";
5150
import type { PaneTerminal } from "./pane.ts";
5251
import type { TerminalGridLayout } from "../terminal-grid.ts";
5352

@@ -346,19 +345,17 @@ export function openTerminalGrid(
346345
const request = toRequest(layout);
347346
let settled: RetainedGrid | undefined;
348347

349-
const grid: LiveGrid = {
348+
// Submitted, not started. The supervisor holds the request and this work
349+
// until a provider presents a composite for this exact object, and the grid
350+
// runs beneath this operation's own scope so its panes keep the durable
351+
// identity of the expansion that wrote them.
352+
const submission = yield* installation.supervisor.submit({
350353
request,
351354
generation: installation.generation,
352-
used: false,
353-
settled: false,
355+
scope: yield* useScope(),
354356
*run(composite) {
355357
settled = yield* presentGrid(request, composite, work, boundary);
356-
grid.settled = true;
357358
},
358-
};
359-
installation.registry.add(grid);
360-
yield* ensure(() => {
361-
installation.registry.remove(grid);
362359
});
363360

364361
// The one foreground-terminal lease, taken before any provider is asked for
@@ -372,7 +369,7 @@ export function openTerminalGrid(
372369
// Routed, and the answer thrown away.
373370
yield* TerminalGrids.operations.open(request);
374371

375-
if (!grid.settled || settled === undefined) {
372+
if (!submission.settled || settled === undefined) {
376373
throw new TerminalAuthorityError(
377374
"no terminal provider opened this grid — a handler answered without delivering the " +
378375
"request to a registered provider",

0 commit comments

Comments
 (0)