Skip to content

Commit b14a2ba

Browse files
committed
✨ Run spawned document work concurrently with <All>
`<All>` runs its direct `<Spawn>` children at the same time and waits for all of them. Both names are engine structural syntax, so no repository file, registration, bundle or Plugin can supply either, and they work in ordinary and admitted generated XMD alike. One shared pure rule decides the whole structure from source — paired forms, no props, at least two spawns, blank text only between them, no `<Spawn>` outside its `<All>`, and no `<Return>` or `<Break>` reaching past a spawn — and expansion, non-executing validation and the whole-fragment preflight read the same result, so a malformed construct starts no child anywhere. Each child is a durable coroutine of the one that reached the `<All>`, allocated in source order by the existing `durableAll()` join, with its own binding environment, live overlay, eval scope, block counter, output buffer, failure ledger, hide set and expansion path. Nothing merges back. `<All>` appends the renderings in authored order only after every child succeeds, so completion order may decide when records append and never what the document renders. The first failure cancels and joins the rest, publishes nothing, and fabricates no completion. Capability-backed identity becomes branch-local, which is what the Story's own `<All><Spawn><Session>` example needs. Canonical import frames and provider answer windows were kept as one execution-wide last-open stack, so two children resolving at once could have one child's selection land in the other's frame — an ordinary `<Session>` in each branch then named no durable identity at all. Both stacks are now owned per Effection scope: nesting inside one scope still hides its parent until it closes, sibling branches have independent tops, closing or cancelling one neither clears nor authorizes the other, and a provider installation may answer in two open windows while a second, different answer in either still refuses. The scope is a private key and reaches no document, component or provider. `All` and `Spawn` join the two frozen complete structural-vocabulary expectations, which is what failed the earlier weights run.
1 parent a403cc5 commit b14a2ba

18 files changed

Lines changed: 3093 additions & 278 deletions

‎architecture.md‎

Lines changed: 91 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1743,8 +1743,8 @@ component neither imports it nor grants its effects.
17431743
Bindings and structural constructs are engine-owned language syntax and require
17441744
no profile entry. Every built-in construct is available inside a generated
17451745
fragment with its ordinary semantics — `Content`, `Output`, `Return`, `Let`,
1746-
`Each`, `If`, `Else`, `Switch`, `Case`, `Loop`, `Break`, `PrintErrors`,
1747-
`Answers` and `Answer` — decided by the same source rules ordinary validation
1746+
`Each`, `If`, `Else`, `Switch`, `Case`, `Loop`, `Break`, `All`, `Spawn`,
1747+
`PrintErrors`, `Answers` and `Answer` — decided by the same source rules ordinary validation
17481748
and expansion read, so a construct means one thing whether a person or an Agent
17491749
wrote it. Preflight dispatches a reserved name to those rules before the
17501750
admitted table is consulted, which is why a construct is never reported as a
@@ -1766,8 +1766,10 @@ nothing it binds survives it, because that body may run no times at all — only
17661766
`<Case>` branches of a `<Switch>` are checked from one incoming snapshot, so no
17671767
alternative supplies a binding to another; the union of what they can produce
17681768
becomes visible afterwards, which keeps reading a binding only one arm makes a
1769-
runtime failure rather than a preflight refusal. `<Loop>`, `<PrintErrors>` and
1770-
`<Let>` bodies read and write the enclosing environment. Constructs keep their
1769+
runtime failure rather than a preflight refusal. Each `<Spawn>` under an `<All>`
1770+
is checked from that same incoming snapshot and contributes nothing back, which
1771+
is the binding contract the children actually run under. `<Loop>`,
1772+
`<PrintErrors>` and `<Let>` bodies read and write the enclosing environment. Constructs keep their
17711773
exact spelling in the retained source, never join the retained named-component
17721774
list, and change no record version.
17731775

@@ -3197,6 +3199,9 @@ for the loop it exits.
31973199
One state exists per execution of one value body. `<If>`, `<Switch>`, `<Loop>`,
31983200
`<Each>` and `<Let>` keep the ambient one; a component invocation hides the caller's from the
31993201
invoked body, so a component's own `<Return>` satisfies its own declaration; a
3202+
`<Spawn>` passes none either, and the shared rule refuses the `<Return>` that
3203+
would have reached for one, so concurrent children cannot race to claim a value
3204+
owned outside their `<All>`; a
32003205
nested value body installs a separate one, and both executions stand; and
32013206
content the caller projected restores the caller's, through a Markdown
32023207
`<Content />` and a function component's `content()` alike, with every
@@ -3279,6 +3284,60 @@ partial replay rebuilds the selection through ordinary expansion while completed
32793284
effects in the chosen branch replay from their own records, and a completed
32803285
document replay reuses the retained result without expanding anything.
32813286

3287+
### Concurrent spawned children
3288+
3289+
`<All>` and `<Spawn>` are the engine's own syntax, not components, so core owns
3290+
what they mean and no repository file, registration, bundle or Plugin can supply
3291+
either name. `<All>` runs its direct `<Spawn>` children at the same time and
3292+
waits for all of them. It takes no props, produces no value, and requires at
3293+
least two spawns — one alone is the sequential document it was already written
3294+
as.
3295+
3296+
The whole structure is decided from source before a child is constructed: the
3297+
paired forms, the absent props, the two-spawn minimum, that only blank text sits
3298+
between the spawns, that no `<Spawn>` is written outside its direct `<All>`, and
3299+
that no `<Return>` or `<Break>` inside a spawn reaches for an owner outside it.
3300+
One shared rule states all of it, and expansion, non-executing validation and
3301+
the generated-fragment preflight read the same result — so a malformed construct
3302+
starts no child anywhere, including in a fragment an Agent generated.
3303+
3304+
**Concurrent expansion shares immutable inputs and nothing else.** Every child
3305+
gets a binding environment and live overlay snapshotted from the one that
3306+
reached the `<All>`, an eval scope of its own, a fresh block counter, a private
3307+
output buffer, its own checked-failure ledger, a copied hide set and an
3308+
expansion path extended by its authored ordinal. Nothing merges back, so a name
3309+
one child binds or rebinds is invisible to its siblings and to the work after
3310+
`</All>`, and a resource it retains is released when it ends. The outer
3311+
`<Return>` and `<Loop>` owners are cleared at the boundary; a loop or value
3312+
component created wholly inside a child establishes its own.
3313+
3314+
**Durable identity comes from the source, never from the schedule.** The
3315+
existing durable structured-concurrency substrate is the implementation: in
3316+
source order, before any child starts, each `<Spawn>` receives one child
3317+
coroutine of the one that reached the `<All>`, and nesting produces the existing
3318+
hierarchical identity. Effects inside a child keep their ordinary descriptions
3319+
under that coroutine, so two children may derive the same local block id without
3320+
colliding, and work after `</All>` continues on the parent counter it would have
3321+
had without any child. Each successful child closes with its rendered string.
3322+
3323+
**Output is authored order; the journal is completion order.** A child emits
3324+
into its private buffer, and `<All>` appends the renderings to its caller's
3325+
region only after every child has succeeded. Which child finished first may
3326+
decide when its records append and never what the document renders. A complete
3327+
replay reads the child closes and runs no spawned work; a partial replay
3328+
restores the children that closed and resumes only the unrecorded ones under the
3329+
same identities. Inserting, removing or reordering spawns is a definition change
3330+
and takes the existing divergence path rather than being reassigned by position
3331+
or completion time.
3332+
3333+
**Failure is the existing fail-fast join.** The first child failure fails the
3334+
`<All>`, cancels every unfinished sibling and does not return until all of them
3335+
have finished tearing down. No private buffer is emitted, records acknowledged
3336+
before the failure stay durable, and interrupted work is never recorded as
3337+
complete. Cancelling the parent takes the same ownership path, and no task,
3338+
subscription, retained resource or buffer survives its spawn. No scheduler, no
3339+
new record family and no document-visible concurrency control is introduced.
3340+
32823341
## Foreground commands
32833342

32843343
An executable block is a foreground child process. Its output reaches the reader
@@ -3930,7 +3989,7 @@ matching name says nothing about which registration answered. What settles it is
39303989
the selection itself, recorded where it is made:
39313990

39323991
- expansion opens an **execution-private import frame** before it asks the
3933-
public import chain anything;
3992+
public import chain anything, in the Effection scope that is asking;
39343993
- canonical core resolution records, inside that frame, the exact name it was
39353994
asked for and the exact implementation it selected — the function object this
39363995
execution built from the host's factory, by identity;
@@ -3947,10 +4006,33 @@ provenance and no permission: what a handler decides is which implementation
39474006
runs, and an implementation running where canonical resolution did not select it
39484007
names nothing. Nested and re-entrant frames stay contained, because a frame is
39494008
opened per import and settled the moment that import answers, however it
3950-
answered; concurrent interleaving leaves more than one selection in a frame and
3951-
so yields no domain, which is the safe direction; and a replay decides the same
3952-
way, against this execution's own factory-created implementation rather than
3953-
against anything a previous run recorded.
4009+
answered; and a replay decides the same way, against this execution's own
4010+
factory-created implementation rather than against anything a previous run
4011+
recorded.
4012+
4013+
**Frames are owned per Effection scope, not per execution.** `<All>` gives two
4014+
`<Spawn>` children imports in flight at the same time, so "the frame this
4015+
selection belongs to" can no longer mean "the last one anybody opened". Each
4016+
scope keeps its own LIFO stack of open frames, and a canonical selection is
4017+
recorded into the top frame of the scope that is resolving:
4018+
4019+
- nesting inside one scope is unchanged — an inner import owns the top until it
4020+
closes, and the outer one may be selected into again afterwards;
4021+
- sibling branches have independent tops, so one child's selection can never
4022+
land in another's frame, and closing or cancelling one branch neither clears
4023+
nor authorizes the other;
4024+
- a frame is removed only by the settle that opened it, from the scope that
4025+
opened it, and teardown discards every remaining stack; and
4026+
- two selections in *one* frame — a handler delegating twice — still yield no
4027+
domain, which remains the safe direction.
4028+
4029+
The scope object is a private key. It is never published, never read from, and
4030+
never reaches a document, a component, a provider or a handler: two frames
4031+
belong together because they were opened under the same engine scope, not
4032+
because of anything either of them says. The same ownership governs the
4033+
canonical answer windows a provider claims through, where one installation may
4034+
hold an answer open in two branches at once and a second, different answer in
4035+
either still refuses.
39544036

39554037
The engine then mints one issuance per invocation, carrying that domain — or
39564038
none — the authored name for what a refusal says, and the frame the body is

‎packages/cli/tests/syntax-cli.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,7 @@ describe("Tier SX — the run profile the command describes", () => {
326326
// The whole structural vocabulary this profile publishes, so a construct
327327
// returning to it has to be written down here.
328328
expect([...names(structural.entries)].sort()).toEqual([
329+
"All",
329330
"Answer",
330331
"Answers",
331332
"Break",
@@ -339,6 +340,7 @@ describe("Tier SX — the run profile the command describes", () => {
339340
"Output",
340341
"PrintErrors",
341342
"Return",
343+
"Spawn",
342344
"Switch",
343345
]);
344346
for (const name of ["Terminal.Grid", "Terminal"]) {

‎packages/core/src/body-structure.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,13 +81,20 @@ function collectOutputs(bodySegments: Segment[], minimumDepth: number): Componen
8181
* this walk does not see is the only thing that still cannot declare one —
8282
* another component's definition, and markdown produced at runtime — because
8383
* it reads this body's source AST and nothing else.
84+
*
85+
* A `<Spawn>` is the one region of this body's own source the walk stops at.
86+
* The spawned child owns no value body, so a `<Return>` inside one neither
87+
* satisfies this body's declaration nor is an undeclared return of it: the
88+
* `<All>` rule owns that diagnostic, and counting it here would report one
89+
* mistake as two while letting a spawn stand in for the return the body still
90+
* has to write.
8491
*/
8592
function collectReturns(bodySegments: Segment[]): ComponentElement[] {
8693
const declared: ComponentElement[] = [];
8794

8895
const walk = (segments: Segment[]): void => {
8996
for (const segment of segments) {
90-
if (segment.type !== "component") {
97+
if (segment.type !== "component" || segment.name === "Spawn") {
9198
continue;
9299
}
93100
if (segment.name === "Return") {

‎packages/core/src/component-answers.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
* do is enter an admitted fragment.
4040
*/
4141

42+
import { useScope } from "effection";
4243
import type { Operation } from "effection";
4344

4445
import { Component } from "./component-api.ts";
@@ -114,7 +115,11 @@ export function componentAnswerRegistrar(
114115
*around(handler: ComponentAnswerHandler): Operation<void> {
115116
yield* Component.around({
116117
*importComponent([name, position], next) {
117-
const asked = installation.open(name, position);
118+
// The scope this invocation is running in, which is the branch whose
119+
// resolution this request answers. Read here rather than carried on
120+
// the installation: one installation serves every branch, and two of
121+
// them may be resolving at the same time.
122+
const asked = installation.open(yield* useScope(), name, position);
118123
try {
119124
return yield* handler(
120125
asked.request,

‎packages/core/src/component-failures.ts‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
*/
2121

2222
import { Component, raise } from "./component-api.ts";
23-
import { attributeCause, ErrorMode } from "./errors.ts";
23+
import { attributeCause, documentationError, ErrorMode } from "./errors.ts";
2424
import type { ComponentFailure, ErrorSegment, FunctionComponent } from "./types.ts";
2525
import type { Operation } from "effection";
2626

@@ -92,6 +92,27 @@ export function containedLedger(inherited: CheckedFailures | undefined): Checked
9292
return { authorized: inherited?.authorized ?? false };
9393
}
9494

95+
/**
96+
* Refuse a successful outcome for work that suffered an unauthorized checked
97+
* command failure.
98+
*
99+
* The failure was already raised where the command ran, and something enclosing
100+
* it — a `printErrors(fn)` component like `<TempDir>`, or one that caught the
101+
* `ContentError` its projected content raised — printed it and returned. Those
102+
* boundaries decide how a failure of their own is reported. Whether a command
103+
* that exited nonzero failed the run is not theirs to decide (#441).
104+
*
105+
* Whoever owns the ledger says so: the execution for the run's own, and a
106+
* spawned child for the one it keeps to itself, which is how a checked failure
107+
* inside one `<Spawn>` fails that child rather than stopping a sibling's walk.
108+
*/
109+
export function* refuseCheckedFailure(checkedFailures: CheckedFailures): Operation<void> {
110+
const segment = checkedFailures.failure;
111+
if (segment !== undefined) {
112+
throw yield* documentationError(segment, "output");
113+
}
114+
}
115+
95116
/**
96117
* Continue after this component fails, reporting the failure as a printed error.
97118
*

0 commit comments

Comments
 (0)