Skip to content

Commit 0ab6863

Browse files
committed
✨ Let a trusted host stop the execution it owns
The generic half, on its own: an execution a host can stop, the durable root control it is written through, and the documentation for both. `HostExecution.stop()` answers for the stop and the join, never for the document. It reaches a document still running, unwinds it, and joins every teardown the execution owns before it answers — a stop that returned while an owned cleanup was still running would be reporting an ending that had not happened. What the journal keeps is the terminal representation the protocol already has: one cancelled `Close` for the root, a status and nothing else. No answer, outcome or successful payload is invented for work the document never finished, and asking again writes no second ending. A persistence failure raised while that ending is being written stays the run's own failure by identity: the stop answers with it, the owned teardown is still attempted and joined, and nothing compensating is appended in its place. A backing failure is still never a workflow terminal. `EP30` and `EP31` prove both at the seam itself — `executeInstalled` and nothing else, with no session, entry or command in them. The existing EP29 terminal-winner, fatal-versus-ordinary and durable root cases are unchanged beside them. This carries no command, session or presentation code. What consumes it is a separate delivery with this one as its ancestor.
1 parent 267cc55 commit 0ab6863

7 files changed

Lines changed: 1204 additions & 13 deletions

File tree

‎architecture.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4640,6 +4640,24 @@ callbacks, documentation capture and public execution policy. Setup receives no
46404640
installation array, request, entry identifier or receipt and creates no second
46414641
execution owner.
46424642

4643+
A host may also **stop** the execution it owns. `HostExecution.stop()` is the
4644+
same seam's opt-in: it answers for the stop and the join, never for the
4645+
document. It reaches a document that is still running, unwinds it, and joins
4646+
every teardown the execution owns before it answers — a stop that returned
4647+
while an owned cleanup was still running would be reporting an ending that had
4648+
not happened. What the journal keeps is the terminal representation the
4649+
protocol already has: one cancelled `Close` for the root, carrying a status and
4650+
nothing else. No answer, outcome or successful payload is invented for work the
4651+
document never finished, and asking again or reading the completion again
4652+
writes no second ending.
4653+
4654+
It creates no second execution owner. Initialization and invocation
4655+
installations stay execution-owned, whole-document failure ranking is
4656+
unchanged, and a persistence failure raised while that ending is being written
4657+
stays the run's own failure by identity — the stop answers with it, the owned
4658+
teardown is still attempted and joined, and nothing compensating is appended in
4659+
its place.
4660+
46434661
Which middleware a command installs on that seam is the host's own selection,
46444662
made once by the runtime entrypoint. The bundled Plugin a run-profile command
46454663
begins with is read from one CLI-private Context whose default is the

‎packages/core/src/execute.ts‎

Lines changed: 244 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ import { cwd as processCwd } from "@effectionx/fs";
3333
import { useComponentModules } from "./typescript-module.ts";
3434
import type { LoadComponentModule } from "./typescript-module.ts";
3535
import { pathToFileURL } from "node:url";
36-
import type { Workflow, Json } from "@executablemd/durable-streams";
36+
import type { DurableRootControl, Workflow, Json } from "@executablemd/durable-streams";
3737
import { createReplayStream } from "./replay-stream.ts";
3838
import { ExecutionProtocolError, issueExecution } from "./execution-request.ts";
3939
import { DocumentProtocolError, issueDocument } from "./document-request.ts";
@@ -1015,6 +1015,16 @@ const NO_ROOT_VOCABULARY =
10151015
"this execution minted no canonical Syntax implementation, so a generated root has no " +
10161016
"vocabulary to describe";
10171017

1018+
/**
1019+
* What a document that was stopped completes as.
1020+
*
1021+
* Not a fault the document raised, and not a success: a run somebody ended is a
1022+
* run that produced no outcome of its own, and this is what a caller reads
1023+
* where there is nothing else to read. A run that had already acknowledged a
1024+
* terminal keeps that terminal and never reaches this.
1025+
*/
1026+
const DOCUMENT_STOPPED = "this document execution was stopped";
1027+
10181028
/**
10191029
* What a recorded event turned out to be.
10201030
*
@@ -2576,6 +2586,29 @@ export interface HostExecution extends DocumentExecution {
25762586
* the data nor the matched text.
25772587
*/
25782588
bindings(): Operation<Result<JsonObject>>;
2589+
/**
2590+
* End this execution explicitly, and wait for all of it.
2591+
*
2592+
* For the one caller that owns the run: a host that decided this document
2593+
* should stop. It asks this execution's own root to end as cancelled while
2594+
* the root is still open, halts the document runner so the root's own
2595+
* finalizer writes that ending through the journal it still owns, joins it,
2596+
* closes the output with whatever had actually been rendered, and then waits
2597+
* for this invocation's installations to unwind.
2598+
*
2599+
* `Ok` means the stop and the join completed. It never means the document
2600+
* succeeded: a stopped document is not `Ok` to `yield* execution`, and a
2601+
* document that had already acknowledged a terminal of its own keeps it. A
2602+
* failed append or a cleanup that could not finish is `Err` here and is this
2603+
* execution's completion too, so a caller cannot read a successful stop
2604+
* around one. A document that merely failed on its own is still a successful
2605+
* stop — the failure is its completion's to carry.
2606+
*
2607+
* It writes no record itself and is handed no stream, no append and no event
2608+
* to write one with. What it holds is the authority to ask the root that owns
2609+
* them.
2610+
*/
2611+
stop(): Operation<Result<void>>;
25792612
}
25802613

25812614
/**
@@ -2922,6 +2955,39 @@ function* executeDocument(
29222955
const channel = createReplayStream<string, string>();
29232956
const { operation, resolve } = withResolvers<Result<Json>>();
29242957

2958+
// What this invocation owns about its own run, held out here rather than
2959+
// inside the runner task, because the stop below is a *second* frame that has
2960+
// to read and finish the same things: the text that actually cleared the live
2961+
// scanner, the one settlement this completion ever takes, and the one close
2962+
// its consumers ever see.
2963+
let emittedText = "";
2964+
let settled = false;
2965+
/** Settle this completion once. A terminal already acknowledged wins. */
2966+
const settle = (result: Result<Json>): void => {
2967+
if (!settled) {
2968+
settled = true;
2969+
resolve(result);
2970+
}
2971+
};
2972+
let closed = false;
2973+
/** Close the output once, with whatever had actually been rendered. */
2974+
function* closeOutput(text: string): Operation<void> {
2975+
if (closed) {
2976+
return;
2977+
}
2978+
closed = true;
2979+
yield* channel.close(text);
2980+
}
2981+
/**
2982+
* This root's own authority to end as cancelled, while it is still open.
2983+
*
2984+
* Minted by `durableRun` over its own ctx, replay index and terminal phase,
2985+
* and handed here by value: it carries no stream, no append and no event, so
2986+
* what this invocation holds is the authority to *ask* and to read back what
2987+
* actually settled.
2988+
*/
2989+
let rootControl: DurableRootControl | undefined;
2990+
29252991
// Created before the run it belongs to, because the handle is published
29262992
// before the document workflow has installed anything: a trusted host holds
29272993
// the operation immediately, and what that operation can do begins when the
@@ -2935,9 +3001,12 @@ function* executeDocument(
29353001
// require having activated its runner first.
29363002
yield* roots.attend();
29373003

2938-
yield* spawn(function* () {
3004+
// Retained, because stopping this document is halting *this* task and
3005+
// joining it: the root's own cancellation finalizer runs inside it, while the
3006+
// canonical journal and its policy are still owned. Halting anything above it
3007+
// would take that journal down before the close could be written.
3008+
const runner = yield* spawn(function* () {
29393009
let emitted = false;
2940-
let emittedText = "";
29413010
let restoring = false;
29423011

29433012
// The ENTIRE setup and workflow sit inside one error boundary: once the
@@ -3337,6 +3406,9 @@ function* executeDocument(
33373406
},
33383407
{
33393408
stream: guardedJournal(journal, root, ROOT_COROUTINE, admissions),
3409+
control: (own) => {
3410+
rootControl = own;
3411+
},
33403412
},
33413413
);
33423414
// Taken rather than read, so the handoff belongs to the run that made it.
@@ -3358,25 +3430,93 @@ function* executeDocument(
33583430
restoring = false;
33593431
}
33603432

3361-
yield* channel.close(result.output);
3433+
yield* closeOutput(result.output);
33623434
if (result.status === "err") {
33633435
const failure = failureError(result.error, live);
3364-
resolve(Err(failure instanceof Error ? failure : new Error(String(failure))));
3436+
settle(Err(failure instanceof Error ? failure : new Error(String(failure))));
33653437
return;
33663438
}
33673439
// The execution's own evaluation policy first, then whatever the host
33683440
// registered. An authoritative failure one of this execution's root
33693441
// evaluations raised is this run's outcome: a host that caught the
33703442
// failure on the call cannot read a successful main result around it.
3371-
resolve(settleCompletion(Ok(result.value), [roots.completion, ...completions]));
3443+
settle(settleCompletion(Ok(result.value), [roots.completion, ...completions]));
33723444
} catch (error) {
33733445
// Close with everything already emitted — printed errors produced before
33743446
// an abort stay visible to consumers of the close value.
3375-
yield* channel.close(emittedText);
3376-
resolve(Err(error instanceof Error ? error : new Error(String(error))));
3447+
yield* closeOutput(emittedText);
3448+
settle(Err(error instanceof Error ? error : new Error(String(error))));
33773449
}
33783450
});
33793451

3452+
/**
3453+
* End this document explicitly, and join everything it owns.
3454+
*
3455+
* Four things in one order, and the order is the whole of it.
3456+
*
3457+
* The root is **asked** first, while it is still open: a root whose own
3458+
* terminal append has already begun keeps the ending it was writing, and
3459+
* this says so by being refused. Then the runner task is **halted** — that
3460+
* task and not the invocation owner above it, because the root's cancellation
3461+
* finalizer appends inside it and the canonical journal, its secret policy
3462+
* and its guard are still owned there. Halting returns once that unwinding
3463+
* has finished, so what comes back is a joined runner rather than a request
3464+
* that one stop.
3465+
*
3466+
* Then the consumers are finished: the output is closed with the text that
3467+
* actually cleared the live scanner — partial, and still only what this run
3468+
* rendered — and completion settles. A normal terminal that had already been
3469+
* acknowledged wins both, because both are taken once.
3470+
*
3471+
* `Ok` says the stop and the join completed; it never says the document
3472+
* succeeded. A failure the halt raised — a refused append, a cleanup that
3473+
* could not finish — is this operation's answer *and* this document's
3474+
* completion, so a caller cannot read a successful stop around it.
3475+
*/
3476+
function* stopDocument(): Operation<Result<void>> {
3477+
// The root has not been created yet: this run is still starting, or it
3478+
// failed before reaching its workflow. There is no terminal to lose, so
3479+
// halting the runner is the whole of ending it.
3480+
if (rootControl === undefined) {
3481+
return yield* haltRunner();
3482+
}
3483+
if (!rootControl.requestInterruption()) {
3484+
// Refused, which means this root's own terminal is being written or has
3485+
// already been acknowledged. That terminal is the one it ends with. So
3486+
// nothing is halted, nothing is closed here and nothing is settled here:
3487+
// the run finishes writing, publishes its own result and output, and this
3488+
// waits for it. Halting now would cancel an append over a backend that
3489+
// may already hold it, and a cancelled ending written around it would be
3490+
// this run recording two.
3491+
yield* operation;
3492+
return Ok(undefined);
3493+
}
3494+
return yield* haltRunner();
3495+
}
3496+
3497+
/**
3498+
* End the runner and finish the consumers, for the two endings that halt it.
3499+
*
3500+
* The accepted interruption, where the root's own cancellation finalizer
3501+
* appends inside this task; and the startup that has no root yet. Both leave
3502+
* nothing acknowledged behind them, so the output is closed with what had
3503+
* actually been rendered and completion settles as stopped — unless the run
3504+
* settled something of its own first, in which case both are already taken.
3505+
*/
3506+
function* haltRunner(): Operation<Result<void>> {
3507+
try {
3508+
yield* runner.halt();
3509+
} catch (error) {
3510+
const failure = error instanceof Error ? error : new Error(String(error));
3511+
yield* closeOutput(emittedText);
3512+
settle(Err(failure));
3513+
return Err(failure);
3514+
}
3515+
yield* closeOutput(emittedText);
3516+
settle(Err(new HostExecutionError(DOCUMENT_STOPPED)));
3517+
return Ok(undefined);
3518+
}
3519+
33803520
return {
33813521
execution: {
33823522
*[Symbol.iterator]() {
@@ -3387,6 +3527,7 @@ function* executeDocument(
33873527
evaluateGeneratedXmdRoot: roots.evaluate,
33883528
evaluation: roots.completion,
33893529
computed,
3530+
stop: stopDocument,
33903531
};
33913532
}
33923533

@@ -3415,6 +3556,15 @@ interface CanonicalInvocation {
34153556
* document always ends — has nothing of its own for it to be additive to.
34163557
*/
34173558
readonly evaluation: CompletionFailure;
3559+
/**
3560+
* End this document explicitly, and join it.
3561+
*
3562+
* Private to canonical execution and published only to a trusted host. It is
3563+
* bound over this invocation's own runner task and root writer state, so
3564+
* there is nothing to look up and nothing to name: a caller that does not
3565+
* already hold this invocation cannot reach it.
3566+
*/
3567+
readonly stop: () => Operation<Result<void>>;
34183568
}
34193569

34203570
/**
@@ -3663,6 +3813,16 @@ function* runInvocation(
36633813
// window in which no evaluation can have been asked for.
36643814
let evaluation: CompletionFailure = () => undefined;
36653815

3816+
/**
3817+
* What this invocation's own teardown raised, from the frame that raised it.
3818+
*
3819+
* Kept beside the completion rather than read back out of it: a stop is a
3820+
* success only when the cleanup after it finished, and "did cleanup fail" is
3821+
* not a question the reconciled completion's error text can be asked. A
3822+
* document that failed on its own is a different thing and leaves this unset.
3823+
*/
3824+
let teardownFailure: Error | undefined;
3825+
36663826
const owner = yield* spawn(function* () {
36673827
// Whatever ends this task — completion, failure, or a cancelled handle —
36683828
// leaves no observer waiting on a run that is over. A document that already
@@ -3697,6 +3857,7 @@ function* runInvocation(
36973857
});
36983858
} catch (error) {
36993859
const teardown = error instanceof Error ? error : new Error(String(error));
3860+
teardownFailure = teardown;
37003861
if (!published) {
37013862
// No handle exists, so this throws — but a durability or Files failure
37023863
// raised during cleanup is still the failure that gets reported.
@@ -3710,9 +3871,60 @@ function* runInvocation(
37103871
});
37113872

37123873
const invoked = yield* ready.operation;
3874+
/**
3875+
* End this invocation explicitly, and wait for all of it.
3876+
*
3877+
* The canonical stop first: it asks the root, halts the document runner and
3878+
* joins it, so the cancelled close is written while the journal is still
3879+
* owned. Then this invocation's own completion, which is what the owner
3880+
* resolves *after* its installations have unwound — so a caller whose stop
3881+
* has returned knows the whole of it is over, not merely the document part.
3882+
*
3883+
* What the two say is ranked rather than merged. A document that failed on
3884+
* its own is not this operation's failure: the stop still happened, and the
3885+
* completion carries the document's outcome for whoever reads it. A failed
3886+
* append or a cleanup that could not finish is different — it comes from the
3887+
* frame that raised it rather than from the completion's text, and it is this
3888+
* operation's answer, because a stop whose cleanup failed stopped nothing
3889+
* safely.
3890+
*/
3891+
function* stopInvocation(): Operation<Result<void>> {
3892+
const stopped = yield* invoked.stop();
3893+
// The whole of it, joined: this resolves once the installations have
3894+
// unwound and the completion has been reconciled, so what is ranked below
3895+
// is what this invocation actually ended as rather than what the document
3896+
// part of it reported.
3897+
const completion = yield* settled.operation;
3898+
const stopFailure = stopped.ok ? undefined : stopped.error;
3899+
const documentFailure = completion.ok ? undefined : completion.error;
3900+
3901+
// Kind first, then occurrence within that kind, by identity — the same
3902+
// ranking the completion was reconciled by, extended by this stop's own
3903+
// report, which happened last. A durability or Files failure is the run's
3904+
// whichever layer raised it, so it can neither be reported as a successful
3905+
// stop nor lose to an ordinary cleanup error that happened after it.
3906+
const durable = fromEach(durabilityFailure, documentFailure, teardownFailure, stopFailure);
3907+
if (durable !== undefined) {
3908+
return Err(durable);
3909+
}
3910+
const files = fromEach(filesFatalFailure, documentFailure, teardownFailure, stopFailure);
3911+
if (files !== undefined) {
3912+
return Err(files);
3913+
}
3914+
// Below the fatal kinds, what this operation answers for is the stop and
3915+
// the join, not the document. A document that failed on its own stopped
3916+
// cleanly and that failure is its completion's to carry; a cleanup that
3917+
// could not finish did not stop cleanly, and neither did a refused append.
3918+
if (stopFailure !== undefined) {
3919+
return Err(stopFailure);
3920+
}
3921+
return teardownFailure === undefined ? Ok(undefined) : Err(teardownFailure);
3922+
}
3923+
37133924
return {
37143925
evaluateGeneratedXmdRoot: invoked.evaluateGeneratedXmdRoot,
37153926
computed: invoked.computed,
3927+
stop: stopInvocation,
37163928
// Carried through unchanged. The completion this handle publishes has
37173929
// already been reconciled with it, so nothing above reads it again; it
37183930
// stays on the handle because it is this invocation's policy and a handle
@@ -3798,6 +4010,29 @@ function fatalOf(error: unknown): Error | undefined {
37984010
return durabilityFailure(error) ?? filesFatalFailure(error);
37994011
}
38004012

4013+
/**
4014+
* The first failure of one kind among these, in the order they happened.
4015+
*
4016+
* The order of the arguments is the order of occurrence, which is what decides
4017+
* within a kind. What comes back is the object the classifier found, never a
4018+
* rebuilt one, because the engine's fences match on identity.
4019+
*/
4020+
function fromEach<T>(
4021+
classify: (error: unknown) => T | undefined,
4022+
...failures: readonly (Error | undefined)[]
4023+
): T | undefined {
4024+
for (const failure of failures) {
4025+
if (failure === undefined) {
4026+
continue;
4027+
}
4028+
const found = classify(failure);
4029+
if (found !== undefined) {
4030+
return found;
4031+
}
4032+
}
4033+
return undefined;
4034+
}
4035+
38014036
/**
38024037
* The one result of a document whose invocation also failed to tear down, or
38034038
* whose own root evaluations did.
@@ -4435,6 +4670,7 @@ export function* executeInstalled(
44354670
},
44364671
evaluateGeneratedXmdRoot: invoked.evaluateGeneratedXmdRoot,
44374672
bindings: invoked.computed.read,
4673+
stop: invoked.stop,
44384674
};
44394675
}
44404676

0 commit comments

Comments
 (0)