@@ -33,7 +33,7 @@ import { cwd as processCwd } from "@effectionx/fs";
3333import { useComponentModules } from "./typescript-module.ts" ;
3434import type { LoadComponentModule } from "./typescript-module.ts" ;
3535import { pathToFileURL } from "node:url" ;
36- import type { Workflow , Json } from "@executablemd/durable-streams" ;
36+ import type { DurableRootControl , Workflow , Json } from "@executablemd/durable-streams" ;
3737import { createReplayStream } from "./replay-stream.ts" ;
3838import { ExecutionProtocolError , issueExecution } from "./execution-request.ts" ;
3939import { 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