diff --git a/architecture.md b/architecture.md
index fa26f8e2..12e45b4b 100644
--- a/architecture.md
+++ b/architecture.md
@@ -136,7 +136,7 @@ and categorization rather than clarify them, so both stay exactly as written.
| `JournalProvenance` | a non-operational, equality-only witness that a live publication stream descends from the exact journal backend a provider selected for one workflow run; it grants no append, read, execution, publication or reconciliation capability, and is meaningful only because the provider retains the witness it established and later requires exact equality |
| result object | the value a component binds instead of failing: `{ok: true, value}` or `{ok: false, …}`, whose failure members the component declares |
| syntax symbols | the complete, versioned description of what a document may write in one directory under one host profile: every structural construct the engine reserves, and the one implementation selection chooses for every other name. It is observation — describing an environment installs no operational state, runs nothing and journals nothing — and it is produced once per request and projected, never rediscovered per format. `xmd syntax` prints one for an environment nobody is running; canonical `` renders one for the site an element was written at, from the same construction and the same Markdown renderer |
-| execution environment | the private bundle of services and records one execution supplies while its document expands: what resolves a name, what routes it to a retained implementation, what the execution declared, and the records it keeps about its own identities, forms, vocabulary and source output. The execution builds it from what it captured and admitted, owns it, and passes it by value through canonical expansion — never through a context, because a context resolves by name and a name is not a secret. An expansion driven directly is handed none at all, which is what "nothing is installed here" means; there is no partial one. Its shape is an architecture and product boundary |
+| execution environment | the private bundle of services and records one execution supplies while its document expands: what resolves a name, what routes it to a retained implementation, what the execution declared, and the records it keeps about its own identities, forms, vocabulary and source output. The execution builds it from what it captured and admitted, owns it, and passes it by value through canonical expansion — never through a context, because a context resolves by name and a name is not a secret. An expansion driven directly is handed none at all, which is what "nothing is installed here" means; there is no partial one. Its shape is an architecture and product boundary, which is why the resolution an execution performs for one *import* is not on it: that terminal is handed to expansion by hand, as an internal argument beside this bundle, named by no entry point and reachable only by having been given it |
| syntax reference | the engine-owned lexical answer to "what may a document write here", carried by value on canonical core's execution environment beside what resolves an import. The execution builds one at its root from the selection inputs it captured before any installation, middleware or document code ran, or from the one set of symbols a trusted host stated for its profile; a trusted canonical evaluation boundary replaces it for the subtree it evaluates. It answers with text and decides nothing: a component the symbols name is not a component anything may run |
| run profile declarations | the component registrations a first-party package makes, held as plain values apart from the middleware, providers, activation and launchers its installer also arranges. The installer registers exactly those values and inspection reads exactly those values, so what a run installs and what the symbols report cannot drift |
| Plugin | trusted code installed once before an execution imports a root document. XMD bundles exactly one — `@executablemd/git` — and activates it for the run-profile commands: `run`, `plan`, `syntax`, and `workflow start`, `resume` and `fork`. The `xmd test` root is not one of them, because a harness that quietly gained the repository vocabulary would be claiming names its children are entitled to shadow; a nested `` child assembles the profile for itself rather than inheriting what its parent declined. Everything else an operator selects with `--plugin`, and a package that happens to be installed stays inert until it is named. A plain structural value carrying a name and one optional `install`; what it contributes is the existing `ExecutionInstallation` members, and what it composes through are the three stable contextual APIs below. Selecting one runs its module, and selected Plugin code can execute whatever the surrounding runtime permits: it is trusted, and it is not sandboxed |
@@ -1743,8 +1743,8 @@ component neither imports it nor grants its effects.
Bindings and structural constructs are engine-owned language syntax and require
no profile entry. Every built-in construct is available inside a generated
fragment with its ordinary semantics — `Content`, `Output`, `Return`, `Let`,
-`Each`, `If`, `Else`, `Switch`, `Case`, `Loop`, `Break`, `PrintErrors`,
-`Answers` and `Answer` — decided by the same source rules ordinary validation
+`Each`, `If`, `Else`, `Switch`, `Case`, `Loop`, `Break`, `All`, `Spawn`,
+`PrintErrors`, `Answers` and `Answer` — decided by the same source rules ordinary validation
and expansion read, so a construct means one thing whether a person or an Agent
wrote it. Preflight dispatches a reserved name to those rules before the
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
`` branches of a `` are checked from one incoming snapshot, so no
alternative supplies a binding to another; the union of what they can produce
becomes visible afterwards, which keeps reading a binding only one arm makes a
-runtime failure rather than a preflight refusal. ``, `` and
-`` bodies read and write the enclosing environment. Constructs keep their
+runtime failure rather than a preflight refusal. Each `` under an ``
+is checked from that same incoming snapshot and contributes nothing back, which
+is the binding contract the children actually run under. ``,
+`` and `` bodies read and write the enclosing environment. Constructs keep their
exact spelling in the retained source, never join the retained named-component
list, and change no record version.
@@ -3197,6 +3199,9 @@ for the loop it exits.
One state exists per execution of one value body. ``, ``, ``,
`` and `` keep the ambient one; a component invocation hides the caller's from the
invoked body, so a component's own `` satisfies its own declaration; a
+`` passes none either, and the shared rule refuses the `` that
+would have reached for one, so concurrent children cannot race to claim a value
+owned outside their ``; a
nested value body installs a separate one, and both executions stand; and
content the caller projected restores the caller's, through a Markdown
`` and a function component's `content()` alike, with every
@@ -3279,6 +3284,64 @@ partial replay rebuilds the selection through ordinary expansion while completed
effects in the chosen branch replay from their own records, and a completed
document replay reuses the retained result without expanding anything.
+### Concurrent spawned children
+
+`` and `` are the engine's own syntax, not components, so core owns
+what they mean and no repository file, registration, bundle or Plugin can supply
+either name. `` runs its direct `` children at the same time and
+waits for all of them. It takes no props, produces no value, and requires at
+least two spawns — one alone is the sequential document it was already written
+as.
+
+The whole structure is decided from source before a child is constructed: the
+paired forms, the absent props, the two-spawn minimum, that only blank text sits
+between the spawns, that no `` is written outside its direct ``, and
+that no `` or `` inside a spawn reaches for an owner outside it.
+One shared rule states all of it, and expansion, non-executing validation and
+the generated-fragment preflight read the same result — so a malformed construct
+starts no child anywhere, including in a fragment an Agent generated.
+
+**Concurrent expansion shares immutable inputs and nothing else.** Every child
+gets a binding environment and live overlay snapshotted from the one that
+reached the ``, an eval scope of its own, a fresh block counter, a private
+output buffer, its own checked-failure ledger, a copied hide set and an
+expansion path extended by its authored ordinal. Nothing merges back, so a name
+one child binds or rebinds is invisible to its siblings and to the work after
+``, and a resource it retains is released when it ends. The outer
+`` and `` owners are cleared at the boundary; a loop or value
+component created wholly inside a child establishes its own.
+
+**Durable identity comes from the source, never from the schedule.** The
+existing durable structured-concurrency substrate is the implementation: in
+source order, before any child starts, each `` receives one child
+coroutine of the one that reached the ``, and nesting produces the existing
+hierarchical identity. Effects inside a child keep their ordinary descriptions
+under that coroutine, so two children may derive the same local block id without
+colliding, and work after `` continues on the parent counter it would have
+had without any child. Each successful child closes with the ordered `{ text, exact }` runs it
+rendered. Exact presentation is a provenance recorded against the segment
+objects expansion marked, and those segments do not cross the join — so the runs
+are what carries it, live and on replay alike, and a retained close that does
+not read as that shape fails the run instead of rebuilding part of a document.
+
+**Output is authored order; the journal is completion order.** A child emits
+into its private buffer, and `` appends the renderings to its caller's
+region only after every child has succeeded. Which child finished first may
+decide when its records append and never what the document renders. A complete
+replay reads the child closes and runs no spawned work; a partial replay
+restores the children that closed and resumes only the unrecorded ones under the
+same identities. Inserting, removing or reordering spawns is a definition change
+and takes the existing divergence path rather than being reassigned by position
+or completion time.
+
+**Failure is the existing fail-fast join.** The first child failure fails the
+``, cancels every unfinished sibling and does not return until all of them
+have finished tearing down. No private buffer is emitted, records acknowledged
+before the failure stay durable, and interrupted work is never recorded as
+complete. Cancelling the parent takes the same ownership path, and no task,
+subscription, retained resource or buffer survives its spawn. No scheduler, no
+new record family and no document-visible concurrency control is introduced.
+
## Foreground commands
An executable block is a foreground child process. Its output reaches the reader
@@ -3930,7 +3993,8 @@ matching name says nothing about which registration answered. What settles it is
the selection itself, recorded where it is made:
- expansion opens an **execution-private import frame** before it asks the
- public import chain anything;
+ public import chain anything, and hands it to the terminal it builds for that
+ one import;
- canonical core resolution records, inside that frame, the exact name it was
asked for and the exact implementation it selected — the function object this
execution built from the host's factory, by identity;
@@ -3947,10 +4011,62 @@ provenance and no permission: what a handler decides is which implementation
runs, and an implementation running where canonical resolution did not select it
names nothing. Nested and re-entrant frames stay contained, because a frame is
opened per import and settled the moment that import answers, however it
-answered; concurrent interleaving leaves more than one selection in a frame and
-so yields no domain, which is the safe direction; and a replay decides the same
-way, against this execution's own factory-created implementation rather than
-against anything a previous run recorded.
+answered; and a replay decides the same way, against this execution's own
+factory-created implementation rather than against anything a previous run
+recorded.
+
+**A frame is owned by the import's own terminal, not by an Effection scope and
+not by the execution.** `` gives two `` children imports in flight at
+the same time, so "the frame this selection belongs to" can be neither "the last
+one anybody opened" nor "the one opened where this code happens to be running".
+Each import creates its own frame and its own `Component` Api descriptor whose
+core `importComponent` handler closes over that frame; the engine asks through
+that descriptor, and the selection is recorded by the terminal `next` reaches:
+
+- the descriptor carries the same stable Api name as the public one, so it
+ receives the same installed middleware in the same order — **a stable name
+ shares middleware, and shares no terminal authority**;
+- the resolution that terminal performs is the execution's own, handed to
+ expansion as an internal argument beside the execution environment rather than
+ on it, and carried by every recursion that can invoke a component — so a
+ component body, a branch and a spawned child resolve the way their execution
+ does, while an expansion driven directly and a generated fragment are handed
+ none and answer through the ordinary public chain;
+- middleware may observe, delegate, replace or refuse the answer, and may run
+ `next` in any descendant scope: `next` still terminates in the terminal that
+ dispatch was created with, so delegating through a scope of its own keeps the
+ identity;
+- sibling spawns resolve through different descriptors, so one spawned child's
+ selection cannot land in another's frame, and closing or cancelling one
+ neither clears nor authorizes the other;
+- nesting is unchanged and needs no stack: an inner authored import is its own
+ dispatch with its own terminal, so the outer one is neither shadowed nor
+ inferred from scheduling;
+- a handler that starts an import of its own by calling the public operation is
+ making a **separate** import, not delegating the authored one — it may resolve
+ normally, and it grants the authored import no identity; and
+- two selections in *one* frame — a handler delegating twice — still yield no
+ domain, which remains the safe direction.
+
+The frame is a closure and nothing else: it is in no map, under no key, and
+reachable only from the dispatch that opened it. Nothing is published, keyed or
+read from — not a scope, not a context, not a token, and not a durable coroutine
+id, which non-journaled expansion does not have. A counterfeit descriptor made
+with the same Api name changes only what is asked through that counterfeit; it
+cannot become the terminal of the engine's own call. Live expansion and replay
+decide this the same way.
+
+Canonical answer windows are owned the same way and by the same kind of value —
+an explicit object rather than a scope — but serially: component answers are
+resolved in one capture phase before any document expands, so one window is open
+at a time. Each provider request captures that window object before its handler
+runs, a claim states it back explicitly, and a handler delegating through a
+descendant scope answers the resolution it was opened in. One installation may
+answer more than one import with the same definition — a reusable provider owns
+one object and a claim is per window — and a second, *different* answer in
+either still refuses. Concurrent document imports happen after capture, with no
+window open at all: such an import may be answered as ordinary middleware, and
+acquires no profile identity.
The engine then mints one issuance per invocation, carrying that domain — or
none — the authored name for what a refusal says, and the frame the body is
diff --git a/packages/cli/tests/syntax-cli.test.ts b/packages/cli/tests/syntax-cli.test.ts
index 957363ea..6967d450 100644
--- a/packages/cli/tests/syntax-cli.test.ts
+++ b/packages/cli/tests/syntax-cli.test.ts
@@ -326,6 +326,7 @@ describe("Tier SX — the run profile the command describes", () => {
// The whole structural vocabulary this profile publishes, so a construct
// returning to it has to be written down here.
expect([...names(structural.entries)].sort()).toEqual([
+ "All",
"Answer",
"Answers",
"Break",
@@ -339,6 +340,7 @@ describe("Tier SX — the run profile the command describes", () => {
"Output",
"PrintErrors",
"Return",
+ "Spawn",
"Switch",
]);
for (const name of ["Terminal.Grid", "Terminal"]) {
diff --git a/packages/core/src/body-structure.ts b/packages/core/src/body-structure.ts
index c0ff0c68..99e24142 100644
--- a/packages/core/src/body-structure.ts
+++ b/packages/core/src/body-structure.ts
@@ -81,13 +81,20 @@ function collectOutputs(bodySegments: Segment[], minimumDepth: number): Componen
* this walk does not see is the only thing that still cannot declare one —
* another component's definition, and markdown produced at runtime — because
* it reads this body's source AST and nothing else.
+ *
+ * A `` is the one region of this body's own source the walk stops at.
+ * The spawned child owns no value body, so a `` inside one neither
+ * satisfies this body's declaration nor is an undeclared return of it: the
+ * `` rule owns that diagnostic, and counting it here would report one
+ * mistake as two while letting a spawn stand in for the return the body still
+ * has to write.
*/
function collectReturns(bodySegments: Segment[]): ComponentElement[] {
const declared: ComponentElement[] = [];
const walk = (segments: Segment[]): void => {
for (const segment of segments) {
- if (segment.type !== "component") {
+ if (segment.type !== "component" || segment.name === "Spawn") {
continue;
}
if (segment.name === "Return") {
diff --git a/packages/core/src/component-answers.ts b/packages/core/src/component-answers.ts
index 3ce4d1a2..05ba2a83 100644
--- a/packages/core/src/component-answers.ts
+++ b/packages/core/src/component-answers.ts
@@ -114,6 +114,11 @@ export function componentAnswerRegistrar(
*around(handler: ComponentAnswerHandler): Operation {
yield* Component.around({
*importComponent([name, position], next) {
+ // One request for this handler invocation, capturing the resolution
+ // window that is open right now. Minted here rather than carried on
+ // the installation: one installation serves every name it registered,
+ // and a retained handle states nothing about which resolution is
+ // being decided.
const asked = installation.open(name, position);
try {
return yield* handler(
diff --git a/packages/core/src/component-api.ts b/packages/core/src/component-api.ts
index 9ce938c3..f65dd7f9 100644
--- a/packages/core/src/component-api.ts
+++ b/packages/core/src/component-api.ts
@@ -175,16 +175,92 @@ export interface ComponentApi {
registry: ComponentRegistry;
}
-export const Component: Api = createApi("Component", {
+/**
+ * The mark an empty public terminal puts on what it raises: a namespaced,
+ * non-enumerable own property carrying the name that was asked for.
+ *
+ * A property rather than a class, because the readers are in a different copy of
+ * this module than the writer as often as not. A component loaded from disk with
+ * `--include`, and a middleware package holding its own copy of core, each build
+ * their own `Component` descriptor with their own empty terminal and their own
+ * error class — and an execution has to recognize "nothing answered this" across
+ * exactly that seam, which `instanceof` cannot do. The name is namespaced so it
+ * collides with nothing, and non-enumerable so it does not travel into whatever
+ * a reporter serializes.
+ *
+ * It conveys one fact — *this call reached an empty public terminal, asking for
+ * this name* — and no authority. Anything may put it on anything; all it can
+ * cause is the ordinary resolution an unanswered import gets anyway.
+ */
+const MISSING_IMPORT_PROVIDER = "@executablemd/core/missing-import-provider";
+
+/**
+ * What the public descriptor's own terminal raises when nothing answered.
+ *
+ * An execution's provider delegates to `next` first and performs its ordinary
+ * resolution only for this, so a descriptor that supplied a terminal of its own
+ * is answered by that terminal and never resolved twice. Exported for core,
+ * published from no package entry point, and carrying nothing but the name that
+ * was asked.
+ */
+export class MissingImportProvider extends Error {
+ override name = "MissingImportProvider";
+ constructor(asked: string) {
+ super(
+ `Component.importComponent("${asked}") has no provider. Install one with ` +
+ `Component.around({ importComponent }, { at: "min" }) before expansion.`,
+ );
+ Object.defineProperty(this, MISSING_IMPORT_PROVIDER, {
+ value: { asked },
+ enumerable: false,
+ writable: false,
+ configurable: false,
+ });
+ }
+}
+
+/**
+ * Whether `error` is an empty public terminal reporting that nothing answered an
+ * import of exactly `asked`.
+ *
+ * The whole mark is parsed rather than trusted: an own, non-enumerable property
+ * under the namespaced name, holding an object whose complete own-key set is one
+ * member, `asked`, whose value is the name this call asked for. Nothing is cast;
+ * a payload carrying anything besides that member, however hidden, is not the
+ * mark; and a mark that names another component — a foreign terminal's report
+ * about a *different* import, arriving here on some other failure — is not this
+ * call's.
+ */
+export function isMissingImportProvider(error: unknown, asked: string): boolean {
+ if (typeof error !== "object" || error === null) {
+ return false;
+ }
+ const mark = Object.getOwnPropertyDescriptor(error, MISSING_IMPORT_PROVIDER);
+ if (mark === undefined || mark.enumerable) {
+ return false;
+ }
+ const value: unknown = mark.value;
+ // The complete own-key set, so "one member" means one: `Object.keys()` would
+ // report a payload carrying hidden extras — a non-enumerable member, a symbol —
+ // as the single-member mark it is not.
+ if (typeof value !== "object" || value === null || Reflect.ownKeys(value).length !== 1) {
+ return false;
+ }
+ return Object.getOwnPropertyDescriptor(value, "asked")?.value === asked;
+}
+
+/**
+ * Every default but the registry, which each descriptor is given its own of:
+ * a `Map` living at module scope would be one table shared by every run in the
+ * process, and the lint rule that says so is right.
+ */
+const COMPONENT_DEFAULTS: Omit = {
// deno-lint-ignore require-yield
*importComponent(
name: string,
_position?: Readonly,
): Operation {
- throw new Error(
- `Component.importComponent("${name}") has no provider. Install one with ` +
- `Component.around({ importComponent }, { at: "min" }) before expansion.`,
- );
+ throw new MissingImportProvider(name);
},
// deno-lint-ignore require-yield
*applyModifiers(_modifiers: Modifier[], block: CodeBlockContext): Operation {
@@ -259,9 +335,52 @@ export const Component: Api = createApi("Component",
*handleFailure(failure: ComponentFailure): Operation {
throw failure.error;
},
+};
+
+export const Component: Api = createApi("Component", {
+ ...COMPONENT_DEFAULTS,
registry: new Map(),
});
+/**
+ * Ask one import through a descriptor whose terminal belongs to that import.
+ *
+ * The name is what shares middleware: a descriptor created with the stable
+ * `Component` name receives every handler installed anywhere, in the order they
+ * were installed, exactly as the public descriptor does. What a name does not
+ * share is the default handler — each `createApi()` instance owns its own — so
+ * the chain composed here terminates in the continuation this caller passed and
+ * in nothing a handler can reach, replace or reorder.
+ *
+ * That is the whole of the correlation. A middleware may delegate `next` through
+ * any descendant Effection scope and still arrive here; two imports asking at
+ * the same time have two descriptors and two terminals; and a counterfeit
+ * descriptor built with the same name changes only the calls made through it.
+ */
+export function importThroughTerminal(
+ name: string,
+ position: Readonly | undefined,
+ terminal: (
+ asked: string,
+ at: Readonly | undefined,
+ ) => Operation,
+): Operation {
+ const owned = createApi("Component", {
+ ...COMPONENT_DEFAULTS,
+ // Its own, and empty: what a registration installed is middleware, which
+ // this descriptor shares by name, so a registry asked through it is answered
+ // there exactly as it is through the public one.
+ registry: new Map(),
+ *importComponent(
+ asked: string,
+ at?: Readonly,
+ ): Operation {
+ return yield* terminal(asked, at);
+ },
+ });
+ return owned.operations.importComponent(name, position);
+}
+
export const importComponent: Operations["importComponent"] =
Component.operations.importComponent;
export const applyModifiers: Operations["applyModifiers"] =
diff --git a/packages/core/src/component-failures.ts b/packages/core/src/component-failures.ts
index fb8bc2c3..9db405ed 100644
--- a/packages/core/src/component-failures.ts
+++ b/packages/core/src/component-failures.ts
@@ -20,7 +20,7 @@
*/
import { Component, raise } from "./component-api.ts";
-import { attributeCause, ErrorMode } from "./errors.ts";
+import { attributeCause, documentationError, ErrorMode } from "./errors.ts";
import type { ComponentFailure, ErrorSegment, FunctionComponent } from "./types.ts";
import type { Operation } from "effection";
@@ -92,6 +92,27 @@ export function containedLedger(inherited: CheckedFailures | undefined): Checked
return { authorized: inherited?.authorized ?? false };
}
+/**
+ * Refuse a successful outcome for work that suffered an unauthorized checked
+ * command failure.
+ *
+ * The failure was already raised where the command ran, and something enclosing
+ * it — a `printErrors(fn)` component like ``, or one that caught the
+ * `ContentError` its projected content raised — printed it and returned. Those
+ * boundaries decide how a failure of their own is reported. Whether a command
+ * that exited nonzero failed the run is not theirs to decide (#441).
+ *
+ * Whoever owns the ledger says so: the execution for the run's own, and a
+ * spawned child for the one it keeps to itself, which is how a checked failure
+ * inside one `` fails that child rather than stopping a sibling's walk.
+ */
+export function* refuseCheckedFailure(checkedFailures: CheckedFailures): Operation {
+ const segment = checkedFailures.failure;
+ if (segment !== undefined) {
+ throw yield* documentationError(segment, "output");
+ }
+}
+
/**
* Continue after this component fails, reporting the failure as a printed error.
*
diff --git a/packages/core/src/components/component-resolution.ts b/packages/core/src/components/component-resolution.ts
index e46a6c1f..39393220 100644
--- a/packages/core/src/components/component-resolution.ts
+++ b/packages/core/src/components/component-resolution.ts
@@ -199,25 +199,54 @@ export interface IdentifiedAnswer {
readonly definition: ImportedDefinition;
}
-/** One claim this owner recorded, with core's own copy of what was claimed. */
+/**
+ * What one answer object was claimed to be, and which resolutions claimed it.
+ *
+ * One implementation says what it is once, so the name, the identity and the
+ * installation belong to the object: a new resolution cannot rename it, restate
+ * its origin or revision, or take it for another provider.
+ *
+ * Which import it answered is a different question, and the answer to it is per
+ * resolution — so the copies are keyed by the window *object*, not by a number
+ * describing one. A caller asking about provenance presents the window it is
+ * holding, so the comparison is between two references to one thing rather than
+ * between a record and whatever the owner's mutable current state happens to
+ * say. A number would have to be trusted against that mutable state; an object
+ * cannot be forged into being the one the caller opened.
+ *
+ * A reusable provider returns one immutable definition to every import it
+ * answers. Keying the claim by the object alone made the first resolution part
+ * of the object's permanent identity and refused the same definition the second
+ * time, which is a provider being punished for not copying itself.
+ */
interface Claim {
readonly name: string;
readonly identity: AnswerIdentity;
/** Which provider installation stated it, so a second cannot overwrite. */
readonly installation: object;
/**
- * The exact resolution this was an answer to.
+ * Core's copy of the definition the first claim described.
+ *
+ * The identity above is a statement about *this* definition, so a later claim
+ * of the same object has to be a claim about the same definition. Without this
+ * baseline, a provider could claim an object, edit it, and have the next window
+ * retain the edited version under the identity and revision that described the
+ * original — a different implementation wearing the first one's name.
*
- * The window *object*, not a number describing one. Provenance is a question
- * about which import a statement answered, and a caller asking it presents
- * the window it is holding — so the comparison is between two references to
- * one thing rather than between a record and whatever the owner's mutable
- * current state happens to say. A number would have to be trusted against
- * that mutable state; an object cannot be forged into being the one the
- * caller opened.
+ * Absent when the first claim could not be copied at all, which is not a state
+ * a later claim can improve: an answer core could not retain is not one it can
+ * start vouching for because the object has since changed.
*/
- readonly window: ResolutionWindow;
- readonly canonical: ImportedDefinition | undefined;
+ readonly baseline: ImportedDefinition | undefined;
+ /**
+ * One retained copy per resolution this answer was claimed in.
+ *
+ * Weak on the window, so a claim lasts exactly as long as somebody still holds
+ * the resolution it belongs to. Presence is the provenance check: a window
+ * that never claimed this answer has no entry, and `identify` answers nothing
+ * for it however many other windows did.
+ */
+ readonly copies: WeakMap;
}
/** A provider request used after its execution ended. */
@@ -300,7 +329,14 @@ export interface OpenAnswerRequest {
* cannot revive a settled one or reach another provider's.
*/
export interface ProviderInstallation {
- /** Begin one handler invocation's request for one asked name. */
+ /**
+ * Begin one handler invocation's request for one asked name.
+ *
+ * The request captures the resolution that is open when it is minted, by
+ * identity, which is how it finds the asking it answers. Nothing about where
+ * the handler runs takes part in that, and nothing about it reaches the
+ * provider.
+ */
open(name: string, position?: Readonly): OpenAnswerRequest;
}
@@ -335,7 +371,7 @@ export class CanonicalImports {
*/
#active = false;
/**
- * The one resolution a claim may be stated during, when one is open.
+ * The one resolution this owner has open, if it has one.
*
* A provider installation outlives every resolution it takes part in, while a
* fresh request belongs to one handler invocation. Canonical execution asks
@@ -348,25 +384,36 @@ export class CanonicalImports {
* belonging to a resolution other than the live one, and the name keeps a
* handler settled for one name from recording under it while a different
* name is being resolved.
+ *
+ * One window at a time, because component answers are resolved in one serial
+ * capture phase before any document expands: the execution asks for each
+ * admitted name in turn, and nothing concurrent is resolving beside it. A
+ * request captures the window object itself before its handler runs, so a
+ * handler delegating through any number of descendant scopes still answers the
+ * resolution it was opened in — no scope takes part in this at all.
*/
#window: ResolutionWindow | undefined;
/** How many resolutions this owner has opened, so each one is its own. */
#occurrences = 0;
/**
- * The resolution each installation last stated an answer for.
+ * The resolutions each installation has already stated an answer for.
*
* Secondary. What proves a statement belongs to an import is the request's
* captured window, not this; this only keeps one provider from naming two
* different implementations for one import, where only one of them could be
* what it resolved to.
*
- * Keyed by the installation's own frozen token and holding the window object,
- * so an installation stays reusable: it answers several admitted names and
- * the same name resolved more than once, because each of those is a different
- * window. Spending the installation itself would break a valid multi-name
- * provider, which the contract does not ask a host to split up.
+ * A set of windows per installation rather than the last one it answered.
+ * Windows follow one another, and one installation may legitimately answer in
+ * window A and then in window B — while a request kept from A may still try to
+ * state a second, different answer for A after B was answered. Remembering only
+ * the most recent window would have let that one through.
+ *
+ * Keyed by the installation's own frozen token, so an installation stays
+ * reusable: it answers several admitted names and the same name resolved more
+ * than once, because each of those is a different window.
*/
- readonly #spent = new WeakMap();
+ readonly #spent = new WeakMap>();
/** Begin identifying. Called after teardown is registered. */
activate(): void {
@@ -376,6 +423,8 @@ export class CanonicalImports {
/** Stop. Called at teardown, on completion, failure or cancellation. */
revoke(): void {
this.#active = false;
+ // Whatever was open goes with it: an execution torn down mid-resolution
+ // leaves nothing claimable.
this.#window = undefined;
}
@@ -403,10 +452,8 @@ export class CanonicalImports {
name,
occurrence,
close(): void {
- // Only this window is closed. A nested resolution that already replaced
- // it has its own close, and clearing another one here would settle a
- // decision still being made. Compared by identity, so no bookkeeping
- // value has to be trusted to say which window this is.
+ // By identity, and idempotent: a close that ran twice must not clear a
+ // window somebody else opened afterwards.
if (owner.#window === window) {
owner.#window = undefined;
}
@@ -438,7 +485,8 @@ export class CanonicalImports {
// Captured by identity, here, at the moment this invocation begins. A
// request minted while resolution N is open answers resolution N or
// nothing: it holds the object, so it cannot be made to describe
- // whichever window is open later.
+ // whichever window is open later, and running its handler in a
+ // descendant scope changes nothing about which window it captured.
const opened = owner.#window;
let live = true;
const request: ComponentAnswerRequest = Object.freeze({
@@ -471,7 +519,11 @@ export class CanonicalImports {
#record(
installation: object,
origin: string,
- asked: { name: string; window: ResolutionWindow | undefined; live: () => boolean },
+ asked: {
+ name: string;
+ window: ResolutionWindow | undefined;
+ live: () => boolean;
+ },
answer: ImportedDefinition,
stated: ClaimedIdentity,
): ImportedDefinition {
@@ -480,9 +532,9 @@ export class CanonicalImports {
}
// Four questions, and each of them is about the invocation rather than
// about the provider: is this handler still deciding; is the resolution it
- // was asked in the one still open, by identity; and is the name it was
- // asked the name that resolution is deciding. A stable installation handle
- // answers none of them, which is why it does not claim.
+ // was asked in the one still open, by identity; and is the name it was asked
+ // the name that resolution is deciding. A stable installation handle answers
+ // none of them, which is why it does not claim.
const open = asked.window;
if (!asked.live() || open === undefined || open !== this.#window || open.name !== asked.name) {
throw new AnswerIdentityError(SETTLED_CLAIM);
@@ -491,14 +543,13 @@ export class CanonicalImports {
const held =
typeof answer === "object" && answer !== null ? this.#claims.get(answer) : undefined;
if (held !== undefined) {
- // Restating exactly what is already there is what a provider installed
- // twice does, and it is not a conflict. Anything else is two providers
- // disagreeing about one object, and the first statement stands: a later
- // claim that overwrote it would let a second provider rename the first's
- // implementation.
+ // What this object is was settled by its first claim. Restating it is what
+ // a provider installed twice does, and what a reusable one does for every
+ // import it answers; anything else is two providers disagreeing about one
+ // object, and the first statement stands — a later claim that overwrote it
+ // would let a second provider rename the first's implementation.
if (
held.installation !== installation ||
- held.window !== open ||
held.name !== asked.name ||
held.identity.origin !== identity.origin ||
held.identity.key !== identity.key ||
@@ -509,30 +560,77 @@ export class CanonicalImports {
"implementation states what it is once.",
);
}
+ if (held.copies.has(open)) {
+ // Already recorded for this exact resolution, so there is nothing to
+ // add: one import is one implementation, and this is that one again.
+ return answer;
+ }
+ // Retained once before it is compared: the answer may run user-controlled
+ // machinery when read, so comparing it and then retaining it would leave
+ // a gap in which those two reads could describe different definitions.
+ // Asked before anything is recorded and before the window is spent, so a
+ // refusal leaves both untouched.
+ const copy = retain(answer);
+ if (
+ held.baseline === undefined ||
+ copy === undefined ||
+ !stillDescribes(held.baseline, copy)
+ ) {
+ throw new AnswerIdentityError(
+ "this answer no longer describes the implementation its identity was stated about, so a " +
+ "further import cannot be answered with it. One implementation states what it is " +
+ "once, and stays that.",
+ );
+ }
+ // The same definition answering a different import. That is one provider
+ // reused, not a second answer — but it still spends *this* resolution, so
+ // a different answer afterwards refuses as it always did.
+ if (this.#spent.get(installation)?.has(open) === true) {
+ throw new AnswerIdentityError(SPENT_OPPORTUNITY);
+ }
+ held.copies.set(open, copy);
+ this.#spend(installation, open);
return answer;
}
// Secondary, and about the provider rather than the invocation: naming a
// *different* implementation for an import this provider already answered
// is two answers where only one could be what it resolved to.
- if (this.#spent.get(installation) === open) {
+ if (this.#spent.get(installation)?.has(open) === true) {
throw new AnswerIdentityError(SPENT_OPPORTUNITY);
}
// Copied on the way in, so a later edit of the claimed object is visible as
// the change it is.
+ const baseline = retain(answer);
+ const copies = new WeakMap();
+ copies.set(open, baseline);
this.#claims.set(answer, {
name: asked.name,
identity,
installation,
- window: open,
- canonical: retain(answer),
+ baseline,
+ copies,
});
- // Spent for this window and no other: the next import is a different
- // window, which is what lets one installation answer several admitted
- // names and the same name resolved twice.
- this.#spent.set(installation, open);
+ this.#spend(installation, open);
return answer;
}
+ /**
+ * Record that this installation has answered this resolution.
+ *
+ * Spent for this window and no other: another import is a different window,
+ * which is what lets one installation answer several admitted names, the same
+ * name resolved twice, and sibling spawns resolving at the same time — while a
+ * second answer in a window it already spent still refuses.
+ */
+ #spend(installation: object, open: ResolutionWindow): void {
+ const spent = this.#spent.get(installation);
+ if (spent === undefined) {
+ this.#spent.set(installation, new WeakSet([open]));
+ } else {
+ spent.add(open);
+ }
+ }
+
/**
* The identity stated for this exact answer, and core's own copy of it.
*
@@ -558,21 +656,24 @@ export class CanonicalImports {
if (claim === undefined) {
return undefined;
}
- // The caller presents the resolution it opened, and the claim has to be an
- // answer to *that* one, by object identity and under the name it decides.
- // Nothing here consults the owner's current window: provenance read out of
- // mutable state would be a claim about whenever the question was asked
- // rather than about which import the statement answered.
- if (claim.window !== resolution || claim.name !== resolution.name) {
+ // The caller presents the resolution it opened, and this answer has to have
+ // been claimed in *that* one, under the name it decides. Nothing here
+ // consults the owner's current window: provenance read out of mutable state
+ // would be a claim about whenever the question was asked rather than about
+ // which import the statement answered. A window that never claimed this
+ // answer holds no copy of it, whatever its siblings did.
+ if (claim.name !== resolution.name || !claim.copies.has(resolution)) {
return undefined;
}
- // A claimed object the chain went on to edit is not the thing that was
- // claimed. Reading it runs whatever it is made of, and a value that refuses
- // to be compared has failed the comparison.
- if (claim.canonical === undefined || !stillDescribes(claim.canonical, answer)) {
+ // This window's own copy, taken when it claimed. A claimed object the chain
+ // went on to edit is not the thing that was claimed: reading it runs
+ // whatever it is made of, and a value that refuses to be compared has
+ // failed the comparison.
+ const canonical = claim.copies.get(resolution);
+ if (canonical === undefined || !stillDescribes(canonical, answer)) {
return undefined;
}
- return Object.freeze({ identity: claim.identity, definition: claim.canonical });
+ return Object.freeze({ identity: claim.identity, definition: canonical });
}
/**
diff --git a/packages/core/src/document-validation.ts b/packages/core/src/document-validation.ts
index 43188604..2090ca02 100644
--- a/packages/core/src/document-validation.ts
+++ b/packages/core/src/document-validation.ts
@@ -61,6 +61,7 @@ import { readRootSource, rootSourcePath } from "./root-source.ts";
import { composeRootDefinition } from "./root-composition.ts";
import type { RootDocumentSource } from "./root-source.ts";
import {
+ allStructure,
answersViolations,
answerViolations,
breakViolations,
@@ -74,6 +75,7 @@ import {
strayAnswerMessage,
strayCaseMessage,
strayElseMessage,
+ straySpawnMessage,
strayStructuralMessage,
switchStructure,
} from "./structural-rules.ts";
@@ -315,6 +317,26 @@ interface LexicalContext {
readonly insideIf: boolean;
/** Whether a `` in this source lexically encloses this point. */
readonly insideSwitch: boolean;
+ /**
+ * Whether an `` in this source lexically encloses this point.
+ *
+ * Not the immediate parent: a `` written anywhere below an `` is
+ * that ``'s to report, because the shared structure analysis walks the
+ * whole region and anchors the diagnostic at the element. This is what tells
+ * such a spawn from one written with no `` above it at all, which is the
+ * only case the element's own rule owns.
+ */
+ readonly insideAll: boolean;
+ /**
+ * Whether a `` in this source lexically encloses this point.
+ *
+ * A spawned child owns no value body and no loop it did not open itself, so
+ * this is what tells a `` written inside one from the ordinary
+ * `` of the body it was written in. It never clears again within one
+ * source: a definition invoked inside the child is its own source and starts
+ * the walk over.
+ */
+ readonly insideSpawn: boolean;
/** Whether the immediate parent is an ``. */
readonly underAnswers: boolean;
/**
@@ -498,8 +520,10 @@ class ValidationState {
entry,
isRoot: entry.ordinal === 0,
insideLoop: false,
+ insideAll: false,
insideIf: false,
insideSwitch: false,
+ insideSpawn: false,
underAnswers: false,
enclosing: undefined,
});
@@ -1144,8 +1168,27 @@ class ValidationState {
return switchStructure(segment).violations;
case "Loop":
return loopViolations(segment);
+ case "All":
+ // Every child's own source is decided here too, so a malformed
+ // `` — and a `` or `` that would leave one — is
+ // reported wherever it was written, before any child could start.
+ return allStructure(segment).violations;
+ case "Spawn":
+ // Every `` below an `` belongs to that ``, wherever it
+ // was written: `allStructure()` walks the whole region and reports a
+ // misplaced one at the element it found, so a second report here would
+ // be the same sentence twice about one mistake. What is left is a
+ // `` with no `` above it at all.
+ return context.insideAll
+ ? []
+ : [{ code: "structural-usage-invalid", source: "Spawn", message: straySpawnMessage() }];
case "Break":
- return breakViolations(segment, context.insideLoop);
+ // A `` reaching past its spawn is already reported by that
+ // spawn's ``, which says what is actually wrong with it — the loop
+ // it reached for is outside the child — rather than that no loop exists.
+ return context.insideSpawn && !context.insideLoop
+ ? []
+ : breakViolations(segment, context.insideLoop);
case "PrintErrors":
return printErrorsViolations(segment);
case "Answers":
@@ -1195,7 +1238,8 @@ class ValidationState {
default:
// `` is the remaining case, and its whole contract belongs to
// the body that declares — or fails to declare — `returns`, which the
- // source's own facts already stated.
+ // source's own facts already stated. One written inside a ``
+ // belongs to no such body, and is reported by that spawn's ``.
return [];
}
}
@@ -1331,12 +1375,20 @@ function hasDynamicOperand(segment: ComponentElement): boolean {
/** The lexical facts one element's children are written under. */
function childContext(segment: ComponentElement, context: LexicalContext): LexicalContext {
+ const spawned = segment.name === "Spawn";
return {
entry: context.entry,
isRoot: context.isRoot,
- insideLoop: context.insideLoop || segment.name === "Loop",
+ // A spawn is a control-flow boundary: the loop that encloses the `` is
+ // not a loop its children may break, so the outer fact stops here and only
+ // a `` written inside the spawn opens a new one.
+ insideLoop: !spawned && (context.insideLoop || segment.name === "Loop"),
insideIf: context.insideIf || segment.name === "If",
insideSwitch: context.insideSwitch || segment.name === "Switch",
+ // Never cleared by a spawn: a nested `` owns its own descendants, and
+ // everything below the outermost one already has an owner.
+ insideAll: context.insideAll || segment.name === "All",
+ insideSpawn: context.insideSpawn || spawned,
underAnswers: segment.name === "Answers",
enclosing: segment.name,
};
diff --git a/packages/core/src/execute.ts b/packages/core/src/execute.ts
index 1964e858..f205bdea 100644
--- a/packages/core/src/execute.ts
+++ b/packages/core/src/execute.ts
@@ -10,7 +10,7 @@
* See DEC-005 in specs/decisions.md.
*/
-import { Err, Ok, ensure, scoped, spawn, withResolvers, until } from "effection";
+import { Err, Ok, ensure, scoped, spawn, useScope, withResolvers, until } from "effection";
import type { Operation, Result, Stream } from "effection";
import { type Api, createApi, type Operations } from "@effectionx/context-api";
import {
@@ -83,7 +83,7 @@ import {
createBlockCounter,
} from "./expand.ts";
import { createReturnBody, missingReturnMessage } from "./return-flow.ts";
-import type { BlockCounter } from "./expand.ts";
+import type { BlockCounter, ComponentImportTerminal } from "./expand.ts";
import {
DocumentationError,
documentationError,
@@ -93,7 +93,7 @@ import {
filesFatalFailure,
useSegmentCauses,
} from "./errors.ts";
-import { Component, importComponent, raise } from "./component-api.ts";
+import { Component, importComponent, isMissingImportProvider, raise } from "./component-api.ts";
import { sourceDescription } from "./source-position.ts";
import { emissions, exactly, renderSegment } from "./render.ts";
import { createExactSource } from "./output/exact-source.ts";
@@ -142,7 +142,7 @@ import {
installIdentities,
parseFormDeclaration,
} from "./invocation-identity.ts";
-import type { IdentityComponent } from "./invocation-identity.ts";
+import type { IdentityComponent, ImportSelection } from "./invocation-identity.ts";
import {
CanonicalImports,
ExecutionImports,
@@ -181,7 +181,7 @@ import type { RootDocumentSource } from "./root-source.ts";
import { useEvalScope } from "@effectionx/scope-eval";
import { declaredRouting, FOREGROUND, route, withRouting } from "./foreground.ts";
import type { ForegroundRouting } from "./foreground.ts";
-import { checkedFailureLedger } from "./component-failures.ts";
+import { checkedFailureLedger, refuseCheckedFailure } from "./component-failures.ts";
import { provideTestHarnessInstallers } from "./test-harness.ts";
import type { TestHarnessInstaller } from "./test-harness.ts";
import type { CheckedFailures } from "./component-failures.ts";
@@ -2022,6 +2022,8 @@ function* runValueRoot(
/** This run's record of an unauthorized checked command failure (#441). */
checkedFailures: CheckedFailures,
environment: ExecutionEnvironment,
+ /** This execution's own import resolution, for the expansions below. */
+ importTerminal: ComponentImportTerminal,
): Operation {
// Created outside the scope the body runs in, so the value it selected is
// still readable after that scope — and its teardown — has finished.
@@ -2051,6 +2053,7 @@ function* runValueRoot(
0,
checkedFailures,
environment,
+ importTerminal,
ownBody,
);
const exactRecord = environment.sourceSegments;
@@ -2073,27 +2076,19 @@ function* runValueRoot(
return { status: "ok", output: chunks.join(""), value: selected.value };
}
-/**
- * Refuse a successful outcome for a run that suffered an unauthorized checked
- * command failure.
- *
- * The failure was already raised where the command ran, and something enclosing
- * it — a `printErrors(fn)` component like ``, or one that caught the
- * `ContentError` its projected content raised — printed it and returned. Those
- * boundaries decide how a failure of their own is reported. Whether a command
- * that exited nonzero failed the run is not theirs to decide, and this is where
- * the run says so (#441).
- */
-function* refuseCheckedFailure(checkedFailures: CheckedFailures): Operation {
- const segment = checkedFailures.failure;
- if (segment !== undefined) {
- throw yield* documentationError(segment, "output");
- }
-}
-
function* documentWorkflow(
props: Record,
environment: ExecutionEnvironment,
+ /**
+ * How this execution resolves one component import, handed to every expansion
+ * this root causes.
+ *
+ * By hand, beside the environment rather than on it: what a host installed and
+ * what a fragment narrowed are described by the environment, and this is
+ * neither — it is the execution's own resolution, reachable only by having been
+ * given it (`expand.ts`).
+ */
+ importTerminal: ComponentImportTerminal,
): Workflow {
// This run's memory of a checked command failure it never authorized. Passed
// by value into core's own expansion and reachable from nowhere else, so no
@@ -2203,6 +2198,7 @@ function* documentWorkflow(
rootPath,
checkedFailures,
environment,
+ importTerminal,
);
}
@@ -2226,6 +2222,7 @@ function* documentWorkflow(
rootPath,
checkedFailures,
environment,
+ importTerminal,
undefined,
);
// An empty buffered root emits no output event.
@@ -2254,6 +2251,7 @@ function* documentWorkflow(
0,
checkedFailures,
environment,
+ importTerminal,
undefined,
);
@@ -2591,6 +2589,59 @@ function* executeDocument(
identity.componentRouting.project,
);
+ /**
+ * Resolve one component import the way this execution resolves them, and
+ * the only thing that puts an invocation in one of its identity domains.
+ *
+ * Owned by the execution and handed to expansion **as an argument**, never
+ * on the environment: `ExecutionEnvironment` is the boundary a host's
+ * installation and a fragment's narrowed table are described against, and
+ * an execution-private terminal belongs in neither. Expansion calls this as
+ * the terminal of a descriptor it created for one authored import, passing
+ * that import's own frame; the ordinary provider below calls it with no
+ * frame, for a direct `importComponent()` an invocation started itself.
+ * Neither path publishes the frame, and nothing outside core can name this
+ * operation.
+ */
+ function* resolveComponentImport(
+ name: string,
+ position: Readonly | undefined,
+ selection: ImportSelection | undefined,
+ ): Operation {
+ // Read per import, in the invoking scope, so a component registered
+ // by a nested scope is visible to what that scope expands.
+ const registered = yield* Component.operations.registry;
+ const definition = yield* durableImportComponent(
+ name,
+ name === "__root__" ? root : undefined,
+ position,
+ {
+ searchPaths: includes,
+ registry: registered,
+ bundle,
+ declared: installedComponents,
+ catalog,
+ guarded: identity.protected,
+ },
+ );
+ // Canonical selection, recorded into the frame of the import that asked
+ // for it. This is the only thing that puts an invocation in one of this
+ // execution's identity domains: not the name, not the answer that comes
+ // back, and nothing a handler above this can hold
+ // (`invocation-identity.ts`).
+ if (definition.kind === "function") {
+ selection?.select(name, definition);
+ // The same record, for the other thing canonical resolution decides
+ // here: which dispatcher — if any — this import selected. A dispatcher
+ // a handler kept from another import reaches no body without it.
+ forms.select(name, definition);
+ }
+ // The witness for this answer. It is issued where the answer is
+ // produced and verified where it is invoked, so what a handler does to
+ // the value in between is visible rather than authoritative.
+ return imports === undefined ? definition : imports.issue(name, definition);
+ }
+
const environment: ExecutionEnvironment = {
componentResolution: imports,
// Everything this host declared, admitted above. Expansion asks it
@@ -2631,39 +2682,31 @@ function* executeDocument(
// and the root eval scope.
yield* Component.around(
{
- *importComponent([name, position], _next) {
- // Read per import, in the invoking scope, so a component registered
- // by a nested scope is visible to what that scope expands.
- const registered = yield* Component.operations.registry;
- const definition = yield* durableImportComponent(
- name,
- name === "__root__" ? root : undefined,
- position,
- {
- searchPaths: includes,
- registry: registered,
- bundle,
- declared: installedComponents,
- catalog,
- guarded: identity.protected,
- },
- );
- // Canonical selection, recorded where it is made. This is the only
- // thing that puts an invocation in one of this execution's identity
- // domains: not the name, not the answer that comes back, and
- // nothing a handler above this can hold (`invocation-identity.ts`).
- if (definition.kind === "function") {
- identity.identities.select(name, definition);
- // The same record, for the other thing canonical resolution
- // decides here: which dispatcher — if any — this import selected.
- // A dispatcher a handler kept from another import reaches no body
- // without it.
- forms.select(name, definition);
+ *importComponent([name, position], next) {
+ // Delegation first. An authored import is asked through a descriptor
+ // that supplied a terminal of its own, so `next` answers it there —
+ // in that import's frame — and this provider is the middleware it
+ // composed through rather than the thing that resolved it.
+ try {
+ return yield* next(name, position);
+ } catch (error) {
+ // Only an empty public terminal reporting *this* name: nothing
+ // answered this call, so it is a direct `importComponent()` an
+ // invocation started for itself. It resolves ordinarily and names
+ // no frame, which is what makes it a separate import rather than a
+ // delegation of the authored one. Every other failure is somebody
+ // else's and propagates unchanged.
+ //
+ // The mark is parsed rather than the class compared: the terminal
+ // that raised it belongs to whichever copy of core built the
+ // descriptor that was asked, and a component loaded with
+ // `--include` or a middleware package holding its own copy is an
+ // ordinary arrangement, not a hypothetical.
+ if (!isMissingImportProvider(error, name)) {
+ throw error;
+ }
+ return yield* resolveComponentImport(name, position, undefined);
}
- // The witness for this answer. It is issued where the answer is
- // produced and verified where it is invoked, so what a handler does
- // to the value in between is visible rather than authoritative.
- return imports === undefined ? definition : imports.issue(name, definition);
},
*applyModifiers([modifiers, context], _next) {
const chain = composeModifierChain(modifiers, context, registry);
@@ -2699,7 +2742,7 @@ function* executeDocument(
const returned = yield* durableRun(
function* (): Operation {
const issued = issueDocument(props, (claimed) =>
- documentWorkflow(claimed, environment),
+ documentWorkflow(claimed, environment, resolveComponentImport),
);
try {
return yield* beforeAnyImport(issued);
diff --git a/packages/core/src/expand.ts b/packages/core/src/expand.ts
index 2b96bf92..1ba20ed2 100644
--- a/packages/core/src/expand.ts
+++ b/packages/core/src/expand.ts
@@ -13,7 +13,7 @@
* middleware installation) execute before children's code blocks.
*/
-import { ensure, Err, Ok, scoped, useScope, withResolvers } from "effection";
+import { all, ensure, Err, Ok, scoped, useScope, withResolvers } from "effection";
import type { Operation, Result, Stream } from "effection";
import type {
FunctionComponent,
@@ -39,6 +39,7 @@ import {
validateOutputPlacement,
} from "./body-structure.ts";
import {
+ allStructure,
breakElementViolations,
eachCaptureBinding,
eachItemBinding,
@@ -56,10 +57,11 @@ import {
strayBreakMessage,
strayCaseMessage,
strayElseMessage,
+ straySpawnMessage,
strayStructuralMessage,
switchStructure,
} from "./structural-rules.ts";
-import type { StructuralViolation, SwitchCase } from "./structural-rules.ts";
+import type { SpawnRegion, StructuralViolation, SwitchCase } from "./structural-rules.ts";
import {
asBindingViolation,
asExpressionViolation,
@@ -77,6 +79,7 @@ import {
evalScope,
handleFailure,
importComponent,
+ importThroughTerminal,
raise,
} from "./component-api.ts";
import {
@@ -92,7 +95,7 @@ import {
SegmentCauses,
useSegmentCauses,
} from "./errors.ts";
-import type { InvocationForm } from "./invocation-identity.ts";
+import type { ImportSelection, InvocationForm } from "./invocation-identity.ts";
import { structuralPlacement } from "./execution-declarations.ts";
import type {
AdmittedStructural,
@@ -102,8 +105,9 @@ import type {
} from "./execution-declarations.ts";
import { regionStream } from "./expansion-region.ts";
import { emissions } from "./render.ts";
+import type { Emission } from "./render.ts";
import { printsErrors, usePrintErrors } from "./component-failures.ts";
-import { containedLedger, recoveringLedger } from "./component-failures.ts";
+import { containedLedger, recoveringLedger, refuseCheckedFailure } from "./component-failures.ts";
import type { CheckedFailures } from "./component-failures.ts";
import type { ImportedDefinition } from "./components/component-resolution.ts";
import type { ExecutionEnvironment } from "./execution-environment.ts";
@@ -129,8 +133,15 @@ import { createReturnBody, missingReturnMessage } from "./return-flow.ts";
import type { ReturnBody } from "./return-flow.ts";
import { unbox, useEvalScope } from "@effectionx/scope-eval";
import type { EvalScope } from "@effectionx/scope-eval";
+import {
+ DurableContext,
+ durableAll,
+ ephemeral,
+ StaleInputError,
+} from "@executablemd/durable-streams";
+import type { Workflow } from "@executablemd/durable-streams";
import { SchemaValidationError, validateProps, validateReturnValue } from "./validate.ts";
-import { parseJson } from "./json.ts";
+import { isJsonObject, parseJson } from "./json.ts";
import { healSegment } from "./heal.ts";
import { scanSegments } from "./scanner.ts";
import { declareChildAnswers, expandAnswers, strayAnswerError } from "./answers.ts";
@@ -161,6 +172,35 @@ export interface BlockCounter {
next(): number;
}
+/**
+ * How expansion reaches the resolution its execution performs for one import.
+ *
+ * Execution owns the resolver and hands it to expansion by hand, as an argument
+ * beside the environment and never on it: the environment is the architecture
+ * boundary a host's installation and a fragment's narrowed table are described
+ * against, and an execution-private terminal belongs in neither. It is not
+ * exported from a package entry point, installed in no Context or contextual Api,
+ * and stored in no module-scoped table — the only way to have it is to be handed
+ * it.
+ *
+ * Every internal expansion function carries it beside the environment, so a
+ * recursion that forgot it would fail to compile rather than quietly expanding a
+ * component body, a branch or a spawned child without the execution's resolution.
+ * Two callers legitimately pass none: expansion driven directly, which resolves
+ * through the ordinary public Component Api, and a generated fragment, whose
+ * narrowed provider answers its imports and which inherits nothing from the
+ * document execution that admitted it.
+ *
+ * The `selection` is the asking import's own frame (`invocation-identity.ts`).
+ * Resolution records what it selected there, which is what makes the answer this
+ * element's rather than whichever import resolved last.
+ */
+export type ComponentImportTerminal = (
+ name: string,
+ position: Readonly | undefined,
+ selection: ImportSelection | undefined,
+) => Operation;
+
export function createBlockCounter(): BlockCounter {
let id = 0;
return { next: () => id++ };
@@ -246,6 +286,7 @@ function expandChildrenScoped(
/** Whether the region that caused this expansion grants recovery (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
return scoped(function* () {
@@ -269,6 +310,7 @@ function expandChildrenScoped(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
});
@@ -325,6 +367,7 @@ interface ProjectionState {
*/
checkedFailures: CheckedFailures | undefined;
environment: ExecutionEnvironment | undefined;
+ imports: ComponentImportTerminal | undefined;
}
interface ProjectionFrame {
@@ -469,6 +512,7 @@ function createProjectionHandle(state: ProjectionState): ProjectionHandle {
0,
state.checkedFailures,
state.environment,
+ state.imports,
options.returnFrame,
);
outcome.resolve({ segments: rendered });
@@ -578,6 +622,7 @@ function createProjectionHandle(state: ProjectionState): ProjectionHandle {
0,
state.checkedFailures,
state.environment,
+ state.imports,
request.kind === "markdown" ? undefined : state.callerReturn,
);
outcome.resolve({ segments: [...errors, ...rendered] });
@@ -783,6 +828,9 @@ export function expandSegments(
indexBase,
checkedFailures,
environment,
+ // No execution terminal: an expansion driven directly resolves its imports
+ // through the ordinary public Component Api, exactly as it always has.
+ undefined,
undefined,
);
}
@@ -862,6 +910,7 @@ function* expandListSegments(
*/
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
// An execution opens the table its printed errors record their causes in.
@@ -885,6 +934,7 @@ function* expandListSegments(
indexBase,
checkedFailures,
environment,
+ imports,
returnBody,
);
});
@@ -1006,6 +1056,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
)),
);
@@ -1026,6 +1077,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
)),
);
@@ -1047,6 +1099,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
);
break;
@@ -1080,6 +1133,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
);
break;
@@ -1098,6 +1152,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
);
break;
@@ -1119,6 +1174,7 @@ function* expandListSegments(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
// Which placement this is, answered by identity rather than by name:
@@ -1165,6 +1221,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
);
break;
@@ -1190,6 +1247,38 @@ function* expandListSegments(
break;
}
+ if (segment.name === "All") {
+ // No raise() here, like the branches above: expandAll reports the
+ // errors it creates, and each child settled its own (§6.9).
+ yield* expandAll(
+ segment,
+ parentMeta,
+ parentProps,
+ hideSet,
+ result,
+ elementPath,
+ checkedFailures,
+ environment,
+ imports,
+ );
+ break;
+ }
+
+ if (segment.name === "Spawn") {
+ // A well-placed is consumed by its and never expanded on
+ // its own. Reaching this branch means the element sits outside any
+ // , so it names no component and is diagnosed rather than
+ // resolved from the filesystem.
+ result.push(
+ yield* raise({
+ type: "error",
+ message: positioned(straySpawnMessage(), segment),
+ source: "Spawn",
+ }),
+ );
+ break;
+ }
+
if (RESERVED_STRUCTURAL.has(segment.name)) {
// Every other structural name is consumed above; reaching here means
// one was written where the construct that gives it meaning is not.
@@ -1223,6 +1312,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
);
break;
@@ -1245,6 +1335,7 @@ function* expandListSegments(
elementPath,
checkedFailures,
environment,
+ imports,
returnBody,
);
// A printed error the callee produced is data, and stays data here: it
@@ -1389,6 +1480,7 @@ function* expandListSegments(
},
checkedFailures,
environment,
+ imports,
returnBody,
),
);
@@ -1451,6 +1543,7 @@ function* checkedCommandFailure(
segment: ErrorSegment,
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
// Written down before it is raised or projected, and before the error mode is
@@ -1556,6 +1649,7 @@ function* expandLet(
/** Whether the enclosing region grants checked-failure recovery (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
// Every one of these is decided from what the author wrote, so the whole
@@ -1588,6 +1682,7 @@ function* expandLet(
0,
checkedFailures,
environment,
+ imports,
returnBody,
),
);
@@ -1699,6 +1794,7 @@ function* expandEach(
/** Whether the region that caused this expansion grants recovery (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
// Decided from source alone, so the catalog is shared with validation. A
@@ -1758,6 +1854,7 @@ function* expandEach(
extendPath(path, { f: "item", i: iteration }),
checkedFailures,
environment,
+ imports,
returnBody,
);
// A `` in the body exits the enclosing ``, so the remaining
@@ -1853,6 +1950,7 @@ function* expandIf(
/** Whether the enclosing region grants checked-failure recovery (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
// Decided from source alone and shared with validation: which props were
@@ -1924,6 +2022,7 @@ function* expandIf(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
}
@@ -1993,6 +2092,7 @@ function* expandSwitch(
/** Whether the enclosing region grants checked-failure recovery (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
// Decided from source alone and shared with validation: which props were
@@ -2059,6 +2159,7 @@ function* expandSwitch(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
}
@@ -2134,6 +2235,7 @@ function* expandLoop(
/** Whether the enclosing region grants checked-failure recovery (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
const unknownProp = loopPropsViolation(segment);
@@ -2191,6 +2293,7 @@ function* expandLoop(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
if (frame.broken) {
@@ -2270,6 +2373,222 @@ function* expandBreak(
return reported;
}
+/**
+ * The environment one spawned child starts from (spec §6.5 ``).
+ *
+ * Shallow snapshots of both maps: the durable values the `` was reached
+ * with, and the private live overlay beside them. Ordinary binding values are
+ * carried by identity — isolating what an author deliberately bound inside an
+ * object is not this construct's business — while the maps themselves are the
+ * child's own, so a name one child binds or rebinds is invisible to its
+ * siblings and to the work after ``.
+ */
+function spawnEnvironment(incoming: EvalEnv | undefined): EvalEnv {
+ const child: EvalEnv = { values: { ...(incoming?.values ?? {}) } };
+ const overlay = liveEnvironment(child);
+ if (incoming !== undefined) {
+ Object.assign(overlay.values, liveEnvironment(incoming).values);
+ }
+ return child;
+}
+
+/**
+ * Expand one `` body into the emission runs its child closes with.
+ *
+ * Everything mutable the ordinary walk threads is allocated here rather than
+ * inherited: the binding environment and its live overlay, an eval scope the
+ * child owns and whose resources die with it, a block counter, a private
+ * segment buffer, a checked-failure ledger and a copy of the hide set.
+ * Concurrent children therefore share immutable inputs and nothing else.
+ *
+ * The outer `` and `` owners are cleared: several children
+ * running at once may not race to select one enclosing value or decide one
+ * enclosing loop, and the structural rule already refused the elements that
+ * would try. A `` or value component created wholly inside the child
+ * establishes its own owner exactly as it does anywhere else.
+ */
+function spawnChild(
+ spawn: SpawnRegion,
+ incoming: EvalEnv | undefined,
+ parentMeta: Record,
+ parentProps: Record,
+ hideSet: Set,
+ path: string,
+ inherited: CheckedFailures | undefined,
+ environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
+): Operation {
+ return scoped(function* () {
+ yield* provideEnv(spawnEnvironment(incoming));
+ yield* provideEvalScope(yield* useEvalScope());
+ yield* ActiveLoop.set(undefined);
+ // The `` is consumed by its `` and never reaches dispatch, so
+ // its frame is added here — otherwise every child of one `` would
+ // expand under one path (§5.6).
+ const childPath = extendPath(
+ path,
+ elementFrame(spawn.element.name, elementSite(spawn.element.position, spawn.ordinal)),
+ );
+ const segments: Segment[] = [];
+ // A fresh record with the inherited recovery, like a contained invocation's:
+ // a checked command failure inside one child fails that child, and a
+ // sibling's walk is not stopped by a ledger it does not own.
+ const ledger = containedLedger(inherited);
+ yield* expandSegmentsWithin(
+ spawn.element.children,
+ parentMeta,
+ parentProps,
+ new Set(hideSet),
+ createBlockCounter(),
+ segments,
+ childPath,
+ 0,
+ ledger,
+ environment,
+ imports,
+ undefined,
+ );
+ yield* refuseCheckedFailure(ledger);
+ // Runs rather than one joined string. What a child produced is prose, or a
+ // program's approved source, or both in order — and exact presentation is a
+ // provenance this execution recorded against the segments it marked. Those
+ // segments do not leave the child, so the child states what they were: a
+ // string would arrive in the caller as prose, and a durable close holding
+ // one could not say otherwise on a replay either.
+ return emissions(environment?.sourceSegments, segments);
+ });
+}
+
+/**
+ * Run the children of an `` at the same time (spec §6.5 ``).
+ *
+ * The children are durable coroutines of the one that reached the ``,
+ * allocated in source order before any of them starts, so identity comes from
+ * where a `` was written and never from the order work was scheduled in.
+ * `durableAll()` is the whole join: it allocates those identities, returns the
+ * results in input order, reuses a completed child's recorded close on replay,
+ * and cancels unfinished siblings when one fails.
+ *
+ * Nothing is appended until the join succeeds. Each child renders into a buffer
+ * of its own, and the strings are written to the caller's region in authored
+ * order afterwards — so which child finished first may decide when its durable
+ * records append, and never what the document renders. A failed or cancelled
+ * join appends none of them.
+ *
+ * Expansion driven without a journal — a test, a tool describing a document —
+ * runs the same children on the same join without durable identities, exactly
+ * as `` records nothing there and behaves identically otherwise.
+ */
+function* expandAll(
+ segment: ComponentElement,
+ parentMeta: Record,
+ parentProps: Record,
+ hideSet: Set,
+ /** The region this renders into, once every child has succeeded. */
+ owner: Segment[],
+ path: string,
+ /** Whether the enclosing region grants checked-failure recovery (§3.6). */
+ checkedFailures: CheckedFailures | undefined,
+ environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
+): Operation {
+ // Decided from source alone and shared with validation, completely, before a
+ // child is constructed: a malformed `` starts none of them.
+ const structure = allStructure(segment);
+ if (structure.violations.length > 0) {
+ for (const violation of structure.violations) {
+ owner.push(yield* raise(structuralErrorSegment(violation, segment)));
+ }
+ return;
+ }
+
+ // Read once, here: every child starts from the same incoming snapshot, and
+ // reading it inside a child would let whichever ran first decide what the
+ // others saw.
+ const incoming = yield* env;
+ const children = structure.spawns.map(
+ (spawn) => () =>
+ spawnChild(
+ spawn,
+ incoming,
+ parentMeta,
+ parentProps,
+ hideSet,
+ path,
+ checkedFailures,
+ environment,
+ imports,
+ ),
+ );
+
+ const scope = yield* useScope();
+ const rendered =
+ scope.get(DurableContext) === undefined
+ ? yield* all(children.map((child) => child()))
+ : (yield* durableAll(
+ children.map((child) => (): Workflow => ephemeral(retained(child()))),
+ )).map(readEmissions);
+
+ for (const runs of rendered) {
+ for (const run of runs) {
+ if (run.text === "") {
+ continue;
+ }
+ // One segment per run, and the exact ones are marked again here: the
+ // record is keyed by segment identity, and these segments are this
+ // region's, not the child's. A child that ran on a previous attempt says
+ // what its runs were through its own durable close, so a replay marks
+ // exactly what the live run marked.
+ const segment: Segment = { type: "text", content: run.text };
+ owner.push(segment);
+ if (run.exact) {
+ markExactSource(environment?.sourceSegments, [segment]);
+ }
+ }
+ }
+}
+
+/** One child's runs, as its durable close retains them. */
+function retained(child: Operation): Operation {
+ return (function* (): Operation {
+ return (yield* child).map((run) => ({ text: run.text, exact: run.exact }));
+ })();
+}
+
+/** What a child's retained close is refused with when it will not read. */
+const UNREADABLE_RUNS =
+ "a spawned child's retained close cannot be read as what it rendered, so this run cannot " +
+ "rebuild the document that child produced. A history is read whole or not at all.";
+
+/**
+ * The runs a child closed with, read back from what the journal holds.
+ *
+ * Parsed whole, and refused whole. A replay hands back whatever the history has;
+ * skipping a member it cannot read, or reading a value that is not a list of
+ * runs as an empty one, would publish a document missing exactly the part that
+ * could not be read — and it would look like a document that rendered nothing
+ * there. So every member is checked, the shape is closed at the two members a
+ * run has, and anything else fails this run rather than shortening its output.
+ */
+function readEmissions(value: Json): Emission[] {
+ if (!Array.isArray(value)) {
+ throw new StaleInputError(UNREADABLE_RUNS);
+ }
+ const runs: Emission[] = [];
+ for (const entry of value) {
+ if (!isJsonObject(entry)) {
+ throw new StaleInputError(UNREADABLE_RUNS);
+ }
+ const text = entry["text"];
+ const exact = entry["exact"];
+ if (Object.keys(entry).length !== 2 || typeof text !== "string" || typeof exact !== "boolean") {
+ throw new StaleInputError(UNREADABLE_RUNS);
+ }
+ runs.push({ text, exact });
+ }
+ return runs;
+}
+
function printErrorsPropError(segment: ComponentElement, message: string): ErrorSegment {
return { type: "error", message: positioned(message, segment), source: "PrintErrors" };
}
@@ -2300,6 +2619,7 @@ function* expandPrintErrors(
/** The ledger this region grants recovery on top of (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
const refusal = printErrorsViolations(segment)[0];
@@ -2326,6 +2646,7 @@ function* expandPrintErrors(
// recovers is not one the run suffered.
recoveringLedger(),
environment,
+ imports,
returnBody,
);
});
@@ -2364,6 +2685,7 @@ function* expandComponent(
*/
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
// Cycle detection — Prosser's algorithm
@@ -2392,6 +2714,12 @@ function* expandComponent(
// answered: what canonical resolution selected here is what decides whether
// this invocation is in one of this execution's identity domains, and nothing
// on the answer or in the chain carries it (`invocation-identity.ts`).
+ //
+ // The frame is this dispatch's closure, and the terminal built for this one
+ // import is the only thing that can select into it. That is what makes it this
+ // invocation's own: a sibling `` resolving the same name at the same
+ // time has its own frame behind its own terminal, and a handler delegating
+ // through any number of descendant scopes still arrives at this one.
const selection = environment?.componentIdentity?.beginImport(name);
let selected: IdentityDomain | undefined;
let dispatcher: FunctionComponent | undefined;
@@ -2418,7 +2746,18 @@ function* expandComponent(
const offered = environment?.installedComponents?.offer(environment.componentBodyScope, name);
let answered: ImportedDefinition;
try {
- answered = yield* importComponent(name, position);
+ // Through this import's own terminal when the execution handed expansion
+ // one: the public middleware chain composes around it by name, and `next`
+ // terminates in the continuation that carries this frame. Where expansion
+ // was handed none — driven directly, or a generated fragment answering
+ // through its own narrowed provider — the ordinary public operation answers
+ // exactly as it always did.
+ answered =
+ imports === undefined
+ ? yield* importComponent(name, position)
+ : yield* importThroughTerminal(name, position, (asked, at) =>
+ imports(asked, at, selection),
+ );
} finally {
offered?.close();
}
@@ -2516,6 +2855,7 @@ function* expandComponent(
path,
checkedFailures,
environment,
+ imports,
returnBody,
selected,
dispatcher,
@@ -2662,6 +3002,7 @@ function* expandComponent(
printedErrors: bodyContentErrors,
checkedFailures,
environment,
+ imports,
});
// Published on the eval scope, which every task the invocation owns
// descends from — including its persist-eval blocks and its content.
@@ -2736,6 +3077,7 @@ function* expandComponent(
path,
checkedFailures,
bodyEnvironment,
+ imports,
returnBody,
);
});
@@ -2784,6 +3126,7 @@ function* expandComponent(
path,
checkedFailures,
bodyEnvironment,
+ imports,
returnBody,
);
});
@@ -2953,6 +3296,7 @@ function* expandFunctionComponent(
/** This work's checked-failure ledger, inherited from the invoking element. */
inherited: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
/**
* The identity domain canonical resolution selected for this invocation.
@@ -3166,6 +3510,7 @@ function* expandFunctionComponent(
ownPath: path,
checkedFailures,
environment,
+ imports,
};
// Only the ordinary handle is published. The richer projection a
// protected body may reach stays a closure at the dispatch below, so
@@ -4026,6 +4371,7 @@ export function* expandBody(
/** Whether the invoking element sits inside a `` region. */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
if (!bodyHasOutput(bodySegments)) {
@@ -4041,6 +4387,7 @@ export function* expandBody(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
}
@@ -4063,6 +4410,7 @@ export function* expandBody(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
} else if (chunk.output) {
@@ -4079,6 +4427,7 @@ export function* expandBody(
0,
checkedFailures,
environment,
+ imports,
returnBody,
);
});
@@ -4097,6 +4446,7 @@ export function* expandBody(
chunkBase,
checkedFailures,
environment,
+ imports,
returnBody,
);
});
@@ -4125,6 +4475,7 @@ function runDocumentation(
/** Whether the region that caused this expansion grants recovery (§3.6). */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
return scoped(function* () {
@@ -4140,6 +4491,7 @@ function runDocumentation(
indexBase,
checkedFailures,
environment,
+ imports,
returnBody,
);
});
@@ -4192,6 +4544,7 @@ function* expandValueBody(
/** Whether the invoking element sits inside a `` region. */
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment | undefined,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
const slots = partitionBySlot(children);
@@ -4218,6 +4571,7 @@ function* expandValueBody(
index,
checkedFailures,
environment,
+ imports,
ownBody,
);
}
@@ -4259,6 +4613,7 @@ function* expandInstalledStructural(
path: string,
checkedFailures: CheckedFailures | undefined,
environment: ExecutionEnvironment,
+ imports: ComponentImportTerminal | undefined,
returnBody: ReturnBody | undefined,
): Operation {
const name = segment.name;
@@ -4360,6 +4715,7 @@ function* expandInstalledStructural(
path,
checkedFailures,
environment,
+ imports,
returnBody,
children: segment.children,
});
@@ -4412,6 +4768,7 @@ interface RegionContext {
readonly path: string;
readonly checkedFailures: CheckedFailures | undefined;
readonly environment: ExecutionEnvironment;
+ readonly imports: ComponentImportTerminal | undefined;
readonly returnBody: ReturnBody | undefined;
readonly children: Segment[];
}
@@ -4576,6 +4933,7 @@ function* produceRegion(
index,
context.checkedFailures,
context.environment,
+ context.imports,
context.returnBody,
);
} catch (error) {
diff --git a/packages/core/src/generated-xmd.ts b/packages/core/src/generated-xmd.ts
index da91d105..91778dc4 100644
--- a/packages/core/src/generated-xmd.ts
+++ b/packages/core/src/generated-xmd.ts
@@ -134,6 +134,7 @@ import { RESERVED_STRUCTURAL } from "./structural.ts";
// The ordinary source rules, read rather than reimplemented: a construct means
// one thing whether a person wrote it or an Agent did.
import {
+ allStructure,
answersViolations,
answerViolations,
breakViolations,
@@ -2003,7 +2004,7 @@ function stated(segment: ComponentElement, scope: ReadonlySet): void {
}
/** The structural names that only their own parent may consume. */
-const CONSUMED_BY_PARENT: ReadonlySet = new Set(["Else", "Case", "Answer"]);
+const CONSUMED_BY_PARENT: ReadonlySet = new Set(["Else", "Case", "Answer", "Spawn"]);
/**
* The structural names the generated root supplies no context for.
@@ -2105,6 +2106,22 @@ function* structural(
return;
}
+ if (name === "All") {
+ const structure = allStructure(segment);
+ refuseStructure(structure.violations);
+ // Every child, before the fragment's first effect, and each from the
+ // bindings that reach the ``: the children run at the same time and
+ // merge nothing back, so none of them may be proved against a binding
+ // another one makes, and nothing any of them binds is visible afterwards.
+ // The lexical facts reset with the boundary, exactly as the shared rule
+ // above already refused a `` or `` that would cross it.
+ const incoming: ReadonlySet = new Set(scope);
+ for (const spawn of structure.spawns) {
+ yield* walk(spawn.element.children, table, ceilings, named, new Set(incoming), ROOT_LEXICAL);
+ }
+ return;
+ }
+
if (name === "PrintErrors") {
refuseStructure(printErrorsViolations(segment));
yield* transparent(segment.children, table, ceilings, named, scope, lexical);
@@ -2458,6 +2475,10 @@ function expand(
...(componentRouting === undefined ? {} : { componentRouting }),
...(syntax === undefined ? {} : { syntax }),
},
+ // No execution terminal: this fragment's imports are answered by the
+ // narrowed provider installed above, and it inherits nothing of the
+ // document execution that admitted it.
+ undefined,
// A generated fragment is the engine's own text, so it owns no value body
// and a written into it satisfies no declaration.
undefined,
diff --git a/packages/core/src/invocation-identity.ts b/packages/core/src/invocation-identity.ts
index 884813fe..17432fd2 100644
--- a/packages/core/src/invocation-identity.ts
+++ b/packages/core/src/invocation-identity.ts
@@ -393,28 +393,39 @@ export interface InvocationIdentities {
/**
* Open the frame for one import the engine is about to ask for.
*
- * The engine settles it as soon as that import answers, whatever the answer
- * was, so nothing a handler does in between decides what the frame holds.
+ * The frame is a closure and nothing else: it is in no collection, under no
+ * key, and reachable only through the object this returns. The engine hands
+ * that object to the terminal it builds for this one import and settles it as
+ * soon as the import answers, however it answered — so nothing a handler does
+ * in between decides what the frame holds, and an import a sibling spawn
+ * opened at the same time is a different closure with a different terminal.
*/
beginImport(name: string): ImportSelection;
- /**
- * Record what canonical resolution selected. Only core's own resolver calls
- * this, from inside the import the frame above was opened for.
- */
- select(name: string, definition: object, dispatcher?: unknown): void;
/** Answer for nothing, from here on. Called when the execution is torn down. */
revoke(): void;
}
/** One import's frame: what canonical resolution selected, once. */
export interface ImportSelection {
+ /**
+ * Record what canonical resolution selected for this import.
+ *
+ * Reachable only by holding this frame, which only the engine does: the
+ * terminal it builds for this import closes over it, and that terminal is
+ * what `next` reaches however many scopes a handler delegates through. A
+ * second selection in one frame is ambiguity rather than a correction, and
+ * settles to nothing.
+ */
+ select(name: string, definition: object): void;
/**
* The domain of the registration canonical resolution selected here, if it
* selected one of this execution's own.
*
* Answers `undefined` unless exactly one canonical resolution happened inside
- * this frame, for the name the engine asked, selecting the implementation
- * this execution built for that domain.
+ * this frame, for the name the engine asked, selecting the implementation this
+ * execution built for that domain. Idempotent: the frame closes the first time
+ * it is settled, and a selection after that is not one that happened inside
+ * it.
*/
settle(): IdentityDomain | undefined;
}
@@ -1138,53 +1149,60 @@ export function installIdentities(
});
}
- /**
- * The import frames the engine has open, innermost last.
- *
- * A stack rather than a slot, because a handler may expand something of its
- * own while an import is in flight. Anything that leaves two selections in
- * one frame — a handler delegating twice, or two expansions interleaving —
- * settles to nothing, which is the safe direction.
- */
- const frames: { asked: string; selected: Minted | undefined; count: number }[] = [];
-
return {
identities: {
+ /**
+ * One import's frame, and the terminal that will select into it.
+ *
+ * No collection, no key, no stack: the frame is this closure, and the only
+ * way to select into it is to hold the object returned here. The engine
+ * hands it to the terminal it builds for this exact import, so a handler
+ * delegating through any number of descendant scopes still reaches *this*
+ * frame, and a sibling spawn resolving the same name at the same time
+ * reaches its own. Nothing about either frame is inferred from where it
+ * was opened or from what it resolved to.
+ */
beginImport(asked: string): ImportSelection {
- const frame = { asked, selected: undefined as Minted | undefined, count: 0 };
- frames.push(frame);
+ let selected: Minted | undefined;
+ let count = 0;
+ let closed = false;
return {
+ select(name: string, definition: FunctionComponentDefinition): void {
+ // A frame the engine has already settled records nothing: the
+ // invocation it belonged to has its answer, and a selection arriving
+ // afterwards is another call's.
+ if (closed) {
+ return;
+ }
+ count += 1;
+ // The name canonical resolution answered for has to be the one the
+ // engine asked: a handler that delegates a different name selects a
+ // registration the element never named.
+ const domain = asked === name ? minted.get(name) : undefined;
+ // And the implementation has to be the one this execution built. A
+ // repository file, a nested registration and another execution's
+ // component all resolve to a different function.
+ selected =
+ domain !== undefined && domain.implementation === definition.fn ? domain : undefined;
+ },
settle(): IdentityDomain | undefined {
- const index = frames.lastIndexOf(frame);
- if (index >= 0) {
- frames.splice(index, 1);
+ if (closed) {
+ return undefined;
}
- return frame.count === 1 && frame.selected !== undefined
- ? frame.selected.domain
- : undefined;
+ closed = true;
+ return count === 1 && selected !== undefined ? selected.domain : undefined;
},
};
},
- select(name: string, definition: FunctionComponentDefinition): void {
- const frame = frames.at(-1);
- if (frame === undefined) {
- return;
- }
- frame.count += 1;
- // The name canonical resolution answered for has to be the one the
- // engine asked: a handler that delegates a different name selects a
- // registration the element never named.
- const domain = frame.asked === name ? minted.get(name) : undefined;
- // And the implementation has to be the one this execution built. A
- // repository file, a nested registration and another execution's
- // component all resolve to a different function.
- frame.selected =
- domain !== undefined && domain.implementation === definition.fn ? domain : undefined;
- },
revoke: () => {
for (const domain of minted.values()) {
domain.revoke();
}
+ // There is no frame registry to clear. An execution torn down while a
+ // spawn still had an import open leaves that frame reachable only from
+ // the dispatch that owns it, and its domains answer for nothing from
+ // here — so a frame still in flight settles to nothing of its own
+ // accord.
// The route goes with the domains: a wrapper projected into it, or a
// route narrowed from it, answers for nothing once the execution that
// minted the bodies is gone.
diff --git a/packages/core/src/structural-rules.ts b/packages/core/src/structural-rules.ts
index e343ad87..de6b9afd 100644
--- a/packages/core/src/structural-rules.ts
+++ b/packages/core/src/structural-rules.ts
@@ -716,6 +716,207 @@ export function switchStructure(segment: ComponentElement): SwitchStructure {
return { violations, matching, ...(fallback === undefined ? {} : { fallback }) };
}
+/** What a `` written outside the `` that runs it says. */
+export function straySpawnMessage(): string {
+ return (
+ " must be a direct child of . is reserved: it never resolves a " +
+ "component, and only the it belongs to can run it."
+ );
+}
+
+/** What a `` written inside a spawned child says. */
+export function spawnReturnMessage(): string {
+ return (
+ " cannot cross . A spawned child owns no value body, so a " +
+ "written inside one would have to select a value owned outside — which several " +
+ "children running at once may not race to claim. A component invoked inside the spawn " +
+ "still owns its own ."
+ );
+}
+
+/** What a `` written inside a spawned child with no loop of its own says. */
+export function spawnBreakMessage(): string {
+ return (
+ " cannot cross . A spawned child cannot exit a written outside " +
+ ", because several children running at once may not race to decide one loop. A " +
+ " written wholly inside the spawn is broken by its own as usual."
+ );
+}
+
+/**
+ * One `` `` runs, and where it was written.
+ *
+ * `index` is the child index the element sits at, which is what its expansion
+ * frame is derived from (§5.6); `ordinal` is its place among the spawns, which
+ * is the order its durable child identity and its rendered output follow.
+ */
+export interface SpawnRegion {
+ readonly element: ComponentElement;
+ readonly index: number;
+ readonly ordinal: number;
+}
+
+/** How an `` body divides into spawned children, and what it got wrong. */
+export interface AllStructure {
+ readonly violations: StructuralViolation[];
+ /** The direct `` children, in authored order. */
+ readonly spawns: SpawnRegion[];
+}
+
+/** Everything one `` element decides from what the author wrote. */
+function spawnElementViolations(segment: ComponentElement): StructuralViolation[] {
+ const found: StructuralViolation[] = [];
+ const names = authoredPropNames(segment);
+ if (names.length > 0) {
+ found.push(
+ violation(
+ "structural-usage-invalid",
+ "Spawn",
+ ` accepts no props. Got: "${names[0]}".`,
+ segment,
+ ),
+ );
+ }
+ if (segment.selfClosing) {
+ found.push(
+ violation(
+ "structural-usage-invalid",
+ "Spawn",
+ " holds the markdown its child expands, so it is written paired: " +
+ "....",
+ segment,
+ ),
+ );
+ }
+ return found;
+}
+
+/**
+ * Every `` below an `` that is not one of its direct children. The
+ * walk stops at a nested ``, which owns the spawns beneath it.
+ */
+function misplacedSpawnViolations(children: Segment[]): StructuralViolation[] {
+ const found: StructuralViolation[] = [];
+
+ const walk = (segments: Segment[], depth: number): void => {
+ for (const segment of segments) {
+ if (segment.type !== "component" || segment.name === "All") {
+ continue;
+ }
+ if (segment.name === "Spawn" && depth > 0) {
+ found.push(violation("structural-usage-invalid", "Spawn", straySpawnMessage(), segment));
+ }
+ walk(segment.children, depth + 1);
+ }
+ };
+
+ walk(children, 0);
+ return found;
+}
+
+/**
+ * What one spawned child's own body says about control flow leaving it.
+ *
+ * Lexical, like every other placement rule here: a `` is legal because a
+ * `` written inside the same spawn encloses it, and a `` has no
+ * owner to select at all, because `` produces no value and a spawn is not
+ * a value body. A definition invoked inside the child is its own source and is
+ * not reached from here, so its `` keeps its ordinary meaning.
+ *
+ * The walk stops at a nested ``, whose own structure owns the spawns
+ * beneath it, so one misplaced element is reported once.
+ */
+function spawnFlowViolations(spawn: ComponentElement): StructuralViolation[] {
+ const found: StructuralViolation[] = [];
+
+ const walk = (segments: Segment[], insideLoop: boolean): void => {
+ for (const segment of segments) {
+ if (segment.type !== "component" || segment.name === "All") {
+ continue;
+ }
+ if (segment.name === "Return") {
+ found.push(violation("return-usage-invalid", "Return", spawnReturnMessage(), segment));
+ continue;
+ }
+ if (segment.name === "Break" && !insideLoop) {
+ found.push(violation("structural-usage-invalid", "Break", spawnBreakMessage(), segment));
+ continue;
+ }
+ walk(segment.children, insideLoop || segment.name === "Loop");
+ }
+ };
+
+ walk(spawn.children, false);
+ return found;
+}
+
+/**
+ * Divide an `` body into the children it runs and validate the division
+ * (spec §6.5). Everything here is read from source, before any child starts, so
+ * a malformed construct refuses the whole `` rather than being discovered
+ * once one child is already running.
+ *
+ * Two spawns is the smallest thing worth running at the same time: one alone is
+ * the sequential document it was already written as, and saying so is a fact
+ * about the source rather than a scheduling decision.
+ */
+export function allStructure(segment: ComponentElement): AllStructure {
+ const violations: StructuralViolation[] = [];
+ const spawns: SpawnRegion[] = [];
+
+ const names = authoredPropNames(segment);
+ if (names.length > 0) {
+ violations.push(
+ violation("structural-usage-invalid", "All", ` accepts no props. Got: "${names[0]}".`),
+ );
+ }
+ if (segment.selfClosing) {
+ violations.push(
+ violation(
+ "structural-usage-invalid",
+ "All",
+ " holds the children it runs, so it is written paired: " +
+ ".......",
+ ),
+ );
+ }
+
+ for (const [index, child] of segment.children.entries()) {
+ if (isBlankText(child)) {
+ continue;
+ }
+ if (child.type !== "component" || child.name !== "Spawn") {
+ violations.push(
+ violation(
+ "structural-usage-invalid",
+ "All",
+ ` holds only children. Found ${describeSegment(child)} directly inside ` +
+ "it.",
+ child.type === "component" ? child : undefined,
+ ),
+ );
+ continue;
+ }
+ violations.push(...spawnElementViolations(child));
+ violations.push(...spawnFlowViolations(child));
+ spawns.push({ element: child, index, ordinal: spawns.length });
+ }
+
+ if (!segment.selfClosing && spawns.length < 2) {
+ violations.push(
+ violation(
+ "structural-usage-invalid",
+ "All",
+ " runs at least two children at the same time. Write the second one, " +
+ `or write the work inline. Found ${spawns.length}.`,
+ ),
+ );
+ }
+
+ violations.push(...misplacedSpawnViolations(segment.children));
+ return { violations, spawns };
+}
+
const LOOP_PROPS = new Set(["max", "name"]);
/** How a `` names itself in its own printed errors. */
diff --git a/packages/core/src/structural.ts b/packages/core/src/structural.ts
index 5a375f3a..afc5c21f 100644
--- a/packages/core/src/structural.ts
+++ b/packages/core/src/structural.ts
@@ -143,6 +143,28 @@ export const STRUCTURAL_DECLARATIONS: readonly EngineStructuralDeclaration[] = [
as: null,
context: null,
},
+ {
+ name: "All",
+ syntax: ["……"],
+ description:
+ "Run tasks in parallel. " +
+ "`firstsecond` expands every task at the same " +
+ "time, waits for them all to succeed, and preserves their Markdown order. Write at least " +
+ "two `` children directly inside it; if one fails, unfinished tasks are cancelled " +
+ "and `` produces no output.",
+ as: null,
+ context: "The `` children this runs at the same time.",
+ },
+ {
+ name: "Spawn",
+ syntax: ["…"],
+ description:
+ "Run a task in parallel inside of ``. Write `…` directly inside " +
+ "``; bindings made in its content stay with that task, and `` or `` " +
+ "cannot affect work outside it.",
+ as: null,
+ context: "Markdown expanded in its own child, beside its siblings.",
+ },
{
name: "PrintErrors",
syntax: ["…"],
diff --git a/packages/core/tests/all.test.ts b/packages/core/tests/all.test.ts
new file mode 100644
index 00000000..eeb35108
--- /dev/null
+++ b/packages/core/tests/all.test.ts
@@ -0,0 +1,1683 @@
+/**
+ * Tier ALL — spawned document work running at the same time
+ * (spec §6.5 `` and ``).
+ *
+ * Every case here drives the ordinary scanner, the structural rules, the
+ * expansion engine and the durable stream. Concurrency is established with
+ * signals the children and the journal publish — never with a sleep — and the
+ * releases are ordered so that the child which finishes *second* is the one the
+ * document renders *first*. Calling the durable substrate directly would prove
+ * the substrate rather than the language, so nothing here does.
+ *
+ * Each test names the defect it kills: expanding the children in sequence,
+ * emitting them in completion order, running them on the parent coroutine,
+ * sharing one block counter, sharing the binding environment, leaving a held
+ * sibling alive after a failure, publishing one child's output before the join,
+ * and letting a `` or `` claim an owner outside the spawn.
+ */
+
+import { beforeAll, describe, it } from "@executablemd/test-support/bdd";
+import { expect } from "@executablemd/test-support/expect";
+import { race, resource, scoped, sleep, spawn, withResolvers } from "effection";
+import type { Operation } from "effection";
+import { createDurableOperation, ephemeral, InMemoryStream } from "@executablemd/durable-streams";
+import type {
+ DurableEvent,
+ EffectDescription,
+ Json,
+ Workflow,
+} from "@executablemd/durable-streams";
+import { useHostFiles } from "@executablemd/runtime";
+import { useEchoExec, useStubFs } from "@executablemd/runtime/test";
+import { execute } from "../src/execute.ts";
+import { executeInstalled } from "../host.ts";
+import { evaluateGeneratedXmd, pinnedComponent } from "../host.ts";
+import type {
+ DurablePreparation,
+ ExecutionInstallation,
+ GeneratedObservation,
+ GeneratedXmdRequest,
+ RetainedFragmentIdentity,
+} from "../host.ts";
+import { forEach } from "@effectionx/stream-helpers";
+import { collect } from "../src/collect.ts";
+import { Component, retain } from "../src/component-api.ts";
+import { getExpansion } from "../src/expansion.ts";
+import { retainedSource } from "../src/root-source.ts";
+import { registerComponents } from "../src/components/registration.ts";
+import { Agent } from "../src/agent/agent-api.ts";
+import type { AgentPromptEvent } from "../src/agent/agent-api.ts";
+import { agentIdentityComponents, installAgentComponents } from "../src/agent/components.ts";
+import { useTempFileCompiler } from "../src/temp-file-compiler.ts";
+import { inspectSyntax } from "../src/inspect.ts";
+import { RESERVED_STRUCTURAL } from "../src/structural.ts";
+import { validateDocument } from "../src/document-validation.ts";
+import { inlineSource } from "../src/root-source.ts";
+import type { FunctionComponentDefinition, JsonObject } from "../src/types.ts";
+
+const NO_PROPS = { type: "object", properties: {}, additionalProperties: false };
+const NAMED = {
+ type: "object",
+ properties: { name: { type: "string" } },
+ required: ["name"],
+ additionalProperties: false,
+};
+
+/**
+ * How long a signal that a correct engine publishes immediately may go
+ * unpublished before the wait is called a deadlock.
+ *
+ * Never reached by a passing run: every barrier below is opened by the children
+ * themselves or by the journal, so this bounds only the failure mode. A
+ * sequential expansion would otherwise hold its first child at a barrier its
+ * sibling can no longer reach, and the suite would hang instead of saying what
+ * went wrong.
+ */
+const DEADLOCK_MS = 10_000;
+
+/** A one-shot signal two operations coordinate through. */
+interface Signal {
+ publish(): void;
+ readonly published: Operation;
+}
+
+function signal(): Signal {
+ const resolvers = withResolvers();
+ let settled = false;
+ return {
+ publish() {
+ if (!settled) {
+ settled = true;
+ resolvers.resolve(true);
+ }
+ },
+ get published() {
+ return resolvers.operation;
+ },
+ };
+}
+
+/** Wait for a signal, reporting a deadlock rather than hanging on one. */
+function* awaiting(what: string, waited: Operation): Operation {
+ const reached = yield* race([
+ waited,
+ (function* (): Operation {
+ yield* sleep(DEADLOCK_MS);
+ return false;
+ })(),
+ ]);
+ if (!reached) {
+ throw new Error(`${what} never happened: the spawned children did not run at the same time`);
+ }
+}
+
+/**
+ * The gates, tripwires and timelines one document's registered components
+ * share.
+ *
+ * Three facts about one child are kept apart on purpose: that it reached its
+ * barrier, that it was let go, and that its own durable record landed. A
+ * driver that could only see the last of them could not tell a document whose
+ * children ran together from one whose children ran in turn.
+ */
+class Harness {
+ /** Every `` and `` that reached its barrier, in arrival order. */
+ readonly arrived: string[] = [];
+ /** Every registered component invocation, in order. */
+ readonly ran: string[] = [];
+ /** The expansion identifier each `` saw, by its name. */
+ readonly identities = new Map();
+ /** `start:`/`stop:` marks the retained resources published. */
+ readonly timeline: string[] = [];
+ /** What each `` saw of a retained resource. */
+ readonly observed: string[] = [];
+
+ readonly #arrivals = new Map();
+ readonly #releases = new Map();
+ readonly #records = new Map();
+
+ static #slot(map: Map, name: string): Signal {
+ const existing = map.get(name);
+ if (existing !== undefined) {
+ return existing;
+ }
+ const created = signal();
+ map.set(name, created);
+ return created;
+ }
+
+ announce(name: string): void {
+ this.arrived.push(name);
+ Harness.#slot(this.#arrivals, name).publish();
+ }
+
+ held(name: string): Operation {
+ return awaiting(`<${name}> being released`, Harness.#slot(this.#releases, name).published);
+ }
+
+ recorded(name: string): void {
+ Harness.#slot(this.#records, name).publish();
+ }
+
+ arrival(name: string): Operation {
+ return awaiting(`${name} arriving`, Harness.#slot(this.#arrivals, name).published);
+ }
+
+ append(name: string): Operation {
+ return awaiting(`${name} recording its work`, Harness.#slot(this.#records, name).published);
+ }
+
+ release(name: string): void {
+ Harness.#slot(this.#releases, name).publish();
+ }
+}
+
+function harness(): Harness {
+ return new Harness();
+}
+
+type Gated = Harness;
+
+/** Append one entry to the journal, the way any durable operation does. */
+function* mark(description: EffectDescription, value: Json): Workflow {
+ return yield createDurableOperation(description, function* () {
+ return value;
+ });
+}
+
+/** A resource whose start and stop are both on the record. */
+function useWatch(timeline: string[], label: string): Operation {
+ return resource(function* (provide) {
+ timeline.push(`start:${label}`);
+ try {
+ yield* provide(`held:${label}`);
+ } finally {
+ timeline.push(`stop:${label}`);
+ }
+ });
+}
+
+/**
+ * The components every document below is written against.
+ *
+ * `` is the barrier: it announces that it is live, waits to be released,
+ * and only then appends its own durable record — so which child reached the
+ * document first, which was released first and which appended first are three
+ * separately observable facts.
+ */
+function* useComponents(shared: Gated): Operation {
+ yield* registerComponents([
+ {
+ name: "Gate",
+ origin: "tier-all",
+ props: NAMED,
+ *fn(props) {
+ const name = String(props.name);
+ shared.ran.push(`gate:${name}`);
+ shared.announce(name);
+ yield* shared.held(name);
+ yield* mark({ type: "gate", name: `gate:${name}` }, name);
+ shared.recorded(name);
+ return `[${name}]`;
+ },
+ },
+ {
+ name: "Probe",
+ origin: "tier-all",
+ props: NAMED,
+ *fn(props) {
+ const name = String(props.name);
+ shared.ran.push(`probe:${name}`);
+ shared.identities.set(name, (yield* getExpansion()).id);
+ return `(${name})`;
+ },
+ },
+ {
+ name: "Keep",
+ origin: "tier-all",
+ props: NAMED,
+ *fn(props) {
+ const name = String(props.name);
+ shared.ran.push(`keep:${name}`);
+ return yield* retain(() => useWatch(shared.timeline, name));
+ },
+ },
+ {
+ name: "Observe",
+ origin: "tier-all",
+ props: NAMED,
+ // deno-lint-ignore require-yield
+ *fn(props) {
+ const name = String(props.name);
+ shared.observed.push(
+ `${name}:${shared.timeline.includes("stop:kept") ? "released" : "live"}`,
+ );
+ return "";
+ },
+ },
+ {
+ name: "Fail",
+ origin: "tier-all",
+ props: NAMED,
+ *fn(props) {
+ const name = String(props.name);
+ shared.ran.push(`fail:${name}`);
+ shared.announce(name);
+ yield* shared.held(name);
+ throw new Error(`FAILED:${name}`);
+ },
+ },
+ ]);
+}
+
+/** What one document run produced. */
+interface Run {
+ readonly ok: boolean;
+ readonly output: string;
+ readonly failure: string;
+ readonly events: DurableEvent[];
+}
+
+/**
+ * Run one document to completion, with the gate components registered and a
+ * driver task free to open the barriers while the run is still live.
+ */
+function run(
+ source: string,
+ options: {
+ shared?: Gated;
+ stream?: InMemoryStream;
+ files?: Record;
+ drive?: (shared: Gated, stream: InMemoryStream) => Operation;
+ install?: () => Operation;
+ } = {},
+): Operation {
+ return scoped(function* () {
+ const shared = options.shared ?? harness();
+ const stream = options.stream ?? new InMemoryStream();
+ yield* useHostFiles();
+ yield* useStubFs({ "test.md": source, ...options.files });
+ yield* useEchoExec();
+ yield* useComponents(shared);
+ if (options.install) {
+ yield* options.install();
+ }
+ if (options.drive) {
+ yield* spawn(() => options.drive!(shared, stream));
+ }
+ // Drained chunk by chunk rather than collected: a run that fails still
+ // emitted whatever it emitted, and a test asking whether `` published
+ // a child early has to be able to see it.
+ const chunks: string[] = [];
+ const result = yield* scoped(function* () {
+ const execution = yield* execute({ path: "test.md", stream });
+ try {
+ yield* forEach(function* (chunk: string) {
+ chunks.push(chunk);
+ }, execution.output);
+ } catch {
+ // The execution's own outcome below says why the stream stopped.
+ }
+ return yield* execution;
+ });
+ return {
+ ok: result.ok,
+ output: chunks.join(""),
+ failure: result.ok ? "" : result.error.message,
+ events: stream.snapshot(),
+ };
+ });
+}
+
+/** The name one durable record settled with, or `undefined` for anything else. */
+function recordedName(event: DurableEvent): string | undefined {
+ if (event.type !== "yield" || event.description.type !== "gate") {
+ return undefined;
+ }
+ return event.result.status === "ok" ? String(event.result.value ?? "") : undefined;
+}
+
+/** Every durable record one gate appended, in journal order. */
+function gateOrder(events: DurableEvent[]): string[] {
+ const found: string[] = [];
+ for (const event of events) {
+ const name = recordedName(event);
+ if (name !== undefined) {
+ found.push(name);
+ }
+ }
+ return found;
+}
+
+/** The coroutine each gate record was written under, by gate name. */
+function gateCoroutines(events: DurableEvent[]): Map {
+ const found = new Map();
+ for (const event of events) {
+ const name = recordedName(event);
+ if (name !== undefined) {
+ found.set(name, event.coroutineId);
+ }
+ }
+ return found;
+}
+
+interface EvalEntry {
+ readonly name: string;
+ readonly coroutineId: string;
+}
+
+function evalEntries(events: DurableEvent[]): EvalEntry[] {
+ return events
+ .filter((event) => event.type === "yield" && event.description.type === "eval")
+ .map((event) => ({
+ name: event.type === "yield" ? event.description.name : "",
+ coroutineId: event.coroutineId,
+ }));
+}
+
+/** Every coroutine this run closed, with the status it closed under. */
+function closes(events: DurableEvent[]): Array<{ id: string; status: string }> {
+ return events
+ .filter((event) => event.type === "close")
+ .map((event) => ({ id: event.coroutineId, status: event.result.status }));
+}
+
+/** The value each closed child coroutine settled with, in journal order. */
+function childCloseValues(events: DurableEvent[]): Array<[string, Json]> {
+ const found: Array<[string, Json]> = [];
+ for (const event of events) {
+ if (event.type === "close" && event.coroutineId.includes(".") && event.result.status === "ok") {
+ found.push([event.coroutineId, event.result.value ?? null]);
+ }
+ }
+ return found;
+}
+
+const TWO_GATES = [
+ "",
+ '',
+ '',
+ "",
+].join("\n");
+
+describe("Tier ALL — PA1: both children are live, and output follows the source", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ it("ALL1: releasing the second child first appends it first and renders it second", function* () {
+ const result = yield* run(TWO_GATES, {
+ *drive(shared) {
+ // Both children have to be live at once before either is released:
+ // a sequential expansion can never satisfy this, because the second
+ // child would not start until the first had finished.
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ expect(shared.arrived).toEqual(["one", "two"]);
+ shared.release("two");
+ yield* shared.append("two");
+ shared.release("one");
+ },
+ });
+
+ expect(result.ok).toBe(true);
+ // Completion order decided the journal; it did not decide the document.
+ expect(gateOrder(result.events)).toEqual(["two", "one"]);
+ expect(result.output).toContain("[one][two]");
+ expect(result.output).not.toContain("[two][one]");
+ });
+
+ it("ALL2: no child output is published before the join succeeds", function* () {
+ const emitted: string[] = [];
+ const result = yield* run(TWO_GATES, {
+ *drive(shared, stream) {
+ stream.onAppend = (event) => {
+ const name = recordedName(event);
+ if (name !== undefined) {
+ // What the document has emitted at the moment one child's own
+ // durable work lands: nothing of either child's, because the join
+ // has not returned.
+ emitted.push(`append:${name}`);
+ }
+ };
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ shared.release("two");
+ shared.release("one");
+ },
+ });
+
+ expect(result.ok).toBe(true);
+ expect(emitted).toHaveLength(2);
+ expect(result.output).toContain("[one][two]");
+ });
+});
+
+describe("Tier ALL — PA2: durable identity follows the source", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ it("ALL3: children close on source-ordered coroutines under the one that reached ", function* () {
+ const result = yield* run(TWO_GATES, {
+ *drive(shared) {
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ shared.release("two");
+ yield* shared.append("two");
+ shared.release("one");
+ },
+ });
+
+ expect(result.ok).toBe(true);
+ const coroutines = gateCoroutines(result.events);
+ // Source order, not completion order: "two" finished first and is still
+ // the second child.
+ expect(coroutines.get("one")).toBe("root.0");
+ expect(coroutines.get("two")).toBe("root.1");
+ expect(closes(result.events)).toEqual([
+ { id: "root.1", status: "ok" },
+ { id: "root.0", status: "ok" },
+ { id: "root", status: "ok" },
+ ]);
+ // Each child closes with exactly the markdown it rendered, and with what
+ // that markdown is: a run says whether those bytes are prose or a program's
+ // approved source, because the segments they came from do not leave the
+ // child and a replay has nothing else to read the disposition from.
+ expect(new Map(childCloseValues(result.events))).toEqual(
+ new Map([
+ ["root.1", [{ text: "[two]", exact: false }]],
+ ["root.0", [{ text: "[one]", exact: false }]],
+ ]),
+ );
+ });
+
+ it("ALL4: nesting produces hierarchical child identities", function* () {
+ const result = yield* run(
+ [
+ "",
+ "",
+ "",
+ '',
+ '',
+ "",
+ "",
+ '',
+ "",
+ ].join("\n"),
+ {
+ *drive(shared) {
+ yield* shared.arrival("inner-a");
+ yield* shared.arrival("inner-b");
+ yield* shared.arrival("outer");
+ shared.release("inner-a");
+ shared.release("inner-b");
+ shared.release("outer");
+ },
+ },
+ );
+
+ expect(result.ok).toBe(true);
+ const coroutines = gateCoroutines(result.events);
+ expect(coroutines.get("inner-a")).toBe("root.0.0");
+ expect(coroutines.get("inner-b")).toBe("root.0.1");
+ expect(coroutines.get("outer")).toBe("root.1");
+ });
+
+ it("ALL5: a complete replay runs no spawned work at all", function* () {
+ const stream = new InMemoryStream();
+ const live = harness();
+ const first = yield* run(TWO_GATES, {
+ shared: live,
+ stream,
+ *drive(shared) {
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ shared.release("two");
+ shared.release("one");
+ },
+ });
+ expect(first.ok).toBe(true);
+ expect(live.ran).toEqual(["gate:one", "gate:two"]);
+
+ const replayed = yield* run(TWO_GATES, { stream: new InMemoryStream(first.events) });
+ expect(replayed.ok).toBe(true);
+ expect(replayed.output).toBe(first.output);
+ // Nothing spawned ran, so no barrier had to be opened for the replay.
+ expect(gateOrder(replayed.events)).toEqual(gateOrder(first.events));
+ });
+});
+
+const COUNTER_DOC = [
+ "```js eval",
+ "output('BEFORE');",
+ "```",
+ "",
+ "",
+ "",
+ "",
+ "```js eval",
+ "output('S1');",
+ "```",
+ "",
+ '',
+ "",
+ "",
+ "",
+ "",
+ "```js eval",
+ "output('S2');",
+ "```",
+ "",
+ '',
+ "",
+ "",
+ "",
+ "",
+ "```js eval",
+ "output('AFTER');",
+ "```",
+].join("\n");
+
+/**
+ * Hold every import of `component` until `width` of them are live, then release
+ * them in `order`.
+ *
+ * The barrier is inside `importComponent` deliberately. `` holds a child in
+ * its component *body*, which its import has already finished by then — so two
+ * gated children prove the bodies overlapped, not the imports. Only a wait
+ * inside the import puts two of them in flight together, which is the one
+ * arrangement in which an import could take a sibling's canonical selection.
+ */
+function heldImports(
+ component: string,
+ width: number,
+ order: readonly number[],
+): () => Operation {
+ const arrivals = Array.from({ length: width }, () => signal());
+ const releases = Array.from({ length: width }, () => signal());
+ let seen = 0;
+ return function* () {
+ yield* spawn(function* () {
+ for (const [index, arrival] of arrivals.entries()) {
+ yield* awaiting(
+ `the import of <${component}> number ${index + 1} starting`,
+ arrival.published,
+ );
+ }
+ for (const index of order) {
+ releases[index].publish();
+ }
+ });
+ yield* Component.around(
+ {
+ *importComponent([name, position], next) {
+ if (name !== component || seen >= width) {
+ return yield* next(name, position);
+ }
+ const index = seen++;
+ arrivals[index].publish();
+ yield* awaiting(
+ `the import of <${component}> number ${index + 1} being released`,
+ releases[index].published,
+ );
+ return yield* next(name, position);
+ },
+ },
+ { at: "max" },
+ );
+ };
+}
+
+/** Two spawns, each held at its own gate and then naming its own identity. */
+const GATED_PROBES = [
+ "",
+ '',
+ '',
+ "",
+ "",
+].join("\n");
+
+describe("Tier ALL — PA2: each concurrent site owns its own identity", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ it("ALL3b: two concurrent authored sites each name their own identity, in either release order", function* () {
+ // Both children are held at their gates and then inside their own import, so
+ // the two imports are live at the same time. What this row holds is what the
+ // *document* decides under that overlap: which authored site each expansion
+ // identity belongs to, and that each site's component ran once. Where the
+ // canonical selection landed is CIV27's row, over declared components.
+ const first = harness();
+ const forwards = yield* run(GATED_PROBES, {
+ shared: first,
+ // Both gates open first, and then both children suspend inside their own
+ // import until the other one is there too.
+ install: heldImports("Probe", 2, [0, 1]),
+ *drive(shared) {
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ shared.release("one");
+ shared.release("two");
+ },
+ });
+ expect(forwards.ok).toBe(true);
+
+ const p1 = first.identities.get("p1");
+ const p2 = first.identities.get("p2");
+ expect(typeof p1).toBe("string");
+ expect(typeof p2).toBe("string");
+ expect(p1).not.toBe(p2);
+ // Each site claimed once. A frame that received a second selection would
+ // have settled to nothing and the invocation would name no identity at all.
+ expect(first.ran.filter((one) => one.startsWith("probe:"))).toEqual(["probe:p1", "probe:p2"]);
+
+ // The same document, released in the opposite order. Ownership is the
+ // authored element's, so scheduling decides nothing about it.
+ const second = harness();
+ const backwards = yield* run(GATED_PROBES, {
+ shared: second,
+ install: heldImports("Probe", 2, [1, 0]),
+ *drive(shared) {
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ shared.release("two");
+ shared.release("one");
+ },
+ });
+ expect(backwards.ok).toBe(true);
+ expect(second.identities.get("p1")).toBe(p1);
+ expect(second.identities.get("p2")).toBe(p2);
+ });
+
+ it("ALL3c: one child failing leaves the surviving sibling's own identity intact", function* () {
+ // One import is cancelled while the other is still live. There is no frame
+ // registry for a cancelled branch to leave behind, so the sibling that
+ // already claimed keeps exactly what it claimed.
+ const shared = harness();
+ const result = yield* run(
+ [
+ "",
+ '',
+ '',
+ "",
+ "",
+ ].join("\n"),
+ {
+ shared,
+ *drive(inner) {
+ yield* inner.arrival("one");
+ yield* inner.arrival("two");
+ // The survivor runs first, then the sibling fails under it.
+ inner.release("one");
+ yield* inner.append("one");
+ inner.release("two");
+ },
+ },
+ );
+
+ expect(result.ok).toBe(false);
+ // The join published nothing, and the child that did run named its own
+ // identity rather than nothing or its sibling's.
+ const p1 = shared.identities.get("p1");
+ expect(typeof p1).toBe("string");
+ // The same identity that site names when nothing fails beside it: what the
+ // element is called its work after does not depend on a sibling at all.
+ const alone = harness();
+ const quiet = yield* run(GATED_PROBES, {
+ shared: alone,
+ *drive(inner) {
+ inner.release("one");
+ inner.release("two");
+ },
+ });
+ expect(quiet.ok).toBe(true);
+ expect(p1).toBe(alone.identities.get("p1"));
+ });
+});
+
+describe("Tier ALL — PA3: counters, paths and the parent's own numbering", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ it("ALL6: children reuse local block ids, and later parent work keeps its own", function* () {
+ const shared = harness();
+ const result = yield* run(COUNTER_DOC, { shared });
+
+ expect(result.ok).toBe(true);
+ const entries = evalEntries(result.events);
+ const onParent = entries.filter((entry) => entry.coroutineId === "root");
+ // The parent's counter never saw the children: the block after `` is
+ // numbered as though no child had run.
+ expect(onParent.map((entry) => entry.name)).toEqual(["eval:eval:root:0", "eval:eval:root:1"]);
+
+ const inChildren = entries.filter((entry) => entry.coroutineId !== "root");
+ // `sort()` rather than `toSorted()`: the Node typecheck targets ES2022, where
+ // the latter does not exist, and the array being sorted is the one `map` just
+ // made — so there is nothing of anyone else's to mutate.
+ expect(inChildren.map((entry) => entry.coroutineId).sort()).toEqual(["root.0", "root.1"]);
+ // Both children number their own first block the same way and collide with
+ // nothing, because the child coroutine namespaces it.
+ expect(new Set(inChildren.map((entry) => entry.name))).toEqual(new Set(["eval:eval:root:0"]));
+
+ // Two spawns, two stable and distinct expansion identities.
+ const p1 = shared.identities.get("p1");
+ const p2 = shared.identities.get("p2");
+ expect(typeof p1).toBe("string");
+ expect(typeof p2).toBe("string");
+ expect(p1).not.toBe(p2);
+
+ // A second run of the same document derives all three again.
+ const again = harness();
+ const rerun = yield* run(COUNTER_DOC, { shared: again });
+ expect(rerun.ok).toBe(true);
+ expect(again.identities.get("p1")).toBe(p1);
+ expect(again.identities.get("p2")).toBe(p2);
+ // The same identities on the same coroutines. Compared as a set, because
+ // which child appends first is exactly what scheduling is allowed to
+ // decide — the contract fixes what a block is called and where, never the
+ // order two independent children reach the journal.
+ // `sort()` for the same reason, on the array `map` just made.
+ const identify = (found: EvalEntry[]): string[] =>
+ found.map((entry) => `${entry.coroutineId}/${entry.name}`).sort();
+ expect(identify(evalEntries(rerun.events))).toEqual(identify(entries));
+
+ // And a replay reproduces the rendering without running any of it.
+ const idle = harness();
+ const replayed = yield* run(COUNTER_DOC, {
+ shared: idle,
+ stream: new InMemoryStream(result.events),
+ });
+ expect(replayed.output).toBe(result.output);
+ expect(idle.ran).toEqual([]);
+ });
+});
+
+const ISOLATION_DOC = [
+ "",
+ "",
+ 'chosen',
+ '',
+ "spawn1({picked}/{handle})",
+ "",
+ "",
+ "spawn2({picked}/{handle})",
+ "",
+ "",
+ "",
+ "after({picked}/{handle})",
+ "",
+ '',
+].join("\n");
+
+describe("Tier ALL — PA4: a child's bindings and resources are its own", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ it("ALL7: a binding and a retained resource live on in their child and nowhere else", function* () {
+ const shared = harness();
+ const result = yield* run(ISOLATION_DOC, { shared });
+
+ expect(result.ok).toBe(true);
+ // Later work in the same child reads both.
+ expect(result.output).toContain("spawn1(chosen/held:kept)");
+ // The sibling and the work after `` read neither: the names are not
+ // bound there, so they render as the text that was written.
+ expect(result.output).toContain("spawn2({picked}/{handle})");
+ expect(result.output).toContain("after({picked}/{handle})");
+ // The resource lived while the child did, and was released when it ended.
+ expect(shared.timeline).toEqual(["start:kept", "stop:kept"]);
+ expect(shared.observed).toEqual(["after:released"]);
+ });
+});
+
+describe("Tier ALL — PA5: a partial replay restores one child and resumes the other", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ it("ALL8: the completed child is restored and only the unrecorded child runs", function* () {
+ const stream = new InMemoryStream();
+ const live = harness();
+ const golden = yield* run(TWO_GATES, {
+ shared: live,
+ stream,
+ *drive(shared, journal) {
+ const closedOne = signal();
+ journal.onAppend = (event) => {
+ if (event.type === "close" && event.coroutineId === "root.0") {
+ closedOne.publish();
+ }
+ };
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ // The first child is released and allowed to close before the second
+ // records anything, so the truncation below has exactly one complete
+ // child and one that has not started its work.
+ shared.release("one");
+ yield* awaiting("the first child closing", closedOne.published);
+ shared.release("two");
+ },
+ });
+ expect(golden.ok).toBe(true);
+ expect(golden.output).toContain("[one][two]");
+
+ const events = golden.events;
+ const closedAt = events.findIndex(
+ (event) => event.type === "close" && event.coroutineId === "root.0",
+ );
+ expect(closedAt).toBeGreaterThan(0);
+ const partial = events.slice(0, closedAt + 1);
+ expect(partial.some((event) => event.type === "close" && event.coroutineId === "root.1")).toBe(
+ false,
+ );
+ expect(gateOrder(partial)).toEqual(["one"]);
+
+ const resumed = harness();
+ const replayed = yield* run(TWO_GATES, {
+ shared: resumed,
+ stream: new InMemoryStream(partial),
+ *drive(shared) {
+ yield* shared.arrival("two");
+ shared.release("two");
+ },
+ });
+
+ expect(replayed.ok).toBe(true);
+ // The completed child's rendering came back from its recorded close, and
+ // only the child with no close ran.
+ expect(replayed.output).toBe(golden.output);
+ expect(resumed.ran).toEqual(["gate:two"]);
+ expect(gateCoroutines(replayed.events).get("two")).toBe("root.1");
+ });
+});
+
+describe("Tier ALL — PA6: a failure cancels its siblings and publishes nothing", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ it("ALL9: a held sibling is cancelled and joined, and renders nothing", function* () {
+ const shared = harness();
+ const result = yield* run(
+ [
+ "",
+ '',
+ '',
+ "",
+ "",
+ "tail",
+ ].join("\n"),
+ {
+ shared,
+ *drive(inner) {
+ yield* inner.arrival("bad");
+ yield* inner.arrival("held");
+ // The sibling is still holding at its barrier when the first child
+ // fails, and is never released by this driver.
+ inner.release("bad");
+ },
+ },
+ );
+
+ expect(result.ok).toBe(false);
+ expect(result.failure).toContain("FAILED:bad");
+ // Neither child's private buffer reached the document, and nothing after
+ // `` ran.
+ expect(result.output).not.toContain("[held]");
+ expect(result.output).not.toContain("tail");
+ // The held sibling's scope was torn down as part of the join.
+ expect(shared.timeline).toEqual(["start:kept", "stop:kept"]);
+ // The journal holds only what was acknowledged: the failing child closed
+ // with its error, the cancelled one as cancelled, and the held gate never
+ // recorded work it did not do.
+ expect(gateOrder(result.events)).toEqual([]);
+ const closed = new Map(closes(result.events).map((entry) => [entry.id, entry.status]));
+ expect(closed.get("root.0")).toBe("err");
+ expect(closed.get("root.1")).toBe("cancelled");
+ });
+
+ it("ALL9b: a child that already succeeded publishes nothing when a sibling fails", function* () {
+ const shared = harness();
+ const result = yield* run(
+ [
+ "",
+ '',
+ '',
+ "",
+ "",
+ "tail",
+ ].join("\n"),
+ {
+ shared,
+ *drive(inner) {
+ yield* inner.arrival("done");
+ yield* inner.arrival("bad");
+ // The first child runs to completion, and only then does its sibling
+ // fail: its rendering exists, and the join is what decides whether
+ // the document ever sees it.
+ inner.release("done");
+ yield* inner.append("done");
+ inner.release("bad");
+ },
+ },
+ );
+
+ expect(result.ok).toBe(false);
+ expect(result.failure).toContain("FAILED:bad");
+ // The successful child's own markdown was never published: the join failed,
+ // so `` emitted none of it.
+ expect(result.output).not.toContain("[done]");
+ expect(result.output).not.toContain("tail");
+ // Its durable record stands, because the journal only ever held work that
+ // was acknowledged.
+ expect(gateOrder(result.events)).toEqual(["done"]);
+ expect(shared.timeline).toEqual(["start:kept", "stop:kept"]);
+ const closed = new Map(closes(result.events).map((entry) => [entry.id, entry.status]));
+ expect(closed.get("root.0")).toBe("ok");
+ expect(closed.get("root.1")).toBe("err");
+ });
+
+ it("ALL10: cancelling the document leaves no spawned work alive", function* () {
+ const shared = harness();
+ const stream = new InMemoryStream();
+ const outcome = yield* scoped(function* () {
+ yield* useHostFiles();
+ yield* useStubFs({
+ "test.md": [
+ "",
+ '',
+ '',
+ "",
+ ].join("\n"),
+ });
+ yield* useEchoExec();
+ yield* useComponents(shared);
+ return yield* race([
+ (function* (): Operation {
+ const execution = yield* execute({ path: "test.md", stream });
+ yield* collect(execution);
+ return "finished";
+ })(),
+ (function* (): Operation {
+ yield* shared.arrival("one");
+ yield* shared.arrival("two");
+ return "cancelled";
+ })(),
+ ]);
+ });
+
+ expect(outcome).toBe("cancelled");
+ // The scope exited while both children were held, and both were joined:
+ // the retained resource is released and no gate recorded work.
+ expect(shared.timeline).toEqual(["start:kept", "stop:kept"]);
+ expect(gateOrder(stream.snapshot())).toEqual([]);
+ });
+});
+
+describe("Tier ALL — PA7: malformed structure refuses before any child starts", () => {
+ beforeAll(() => useTempFileCompiler());
+
+ const cases: Array<[string, string, string]> = [
+ [
+ "ALL11: fewer than two spawns",
+ ["", '', ""].join("\n"),
+ "at least two ",
+ ],
+ [
+ "ALL12: a prop on ",
+ [
+ "",
+ '',
+ '',
+ "",
+ ].join("\n"),
+ " accepts no props",
+ ],
+ ["ALL13: a self-closing ", "", "written paired"],
+ [
+ "ALL14: a self-closing ",
+ ["", "", '', ""].join("\n"),
+ " holds the markdown",
+ ],
+ [
+ "ALL15: a prop on ",
+ [
+ "",
+ '