Skip to content

Commit 2e5f0f9

Browse files
authored
✨ Let a value body select its <Return> wherever its own flow reaches (#646)
* ✨ Let a value body select its <Return> wherever its own flow reaches A value root and a Markdown value component could only produce a value from a direct top-level `<Return>`, so "return this only if a condition holds" was inexpressible: the structural preflight rejected a nested return before any body effect ran, and the runtime diagnostic for a body that produced none was unreachable for a plain value root. A value body now owns an ephemeral return state for one execution of itself, with `<Break>`'s ownership rules exactly. `<If>`, `<Loop>`, `<Each>` and `<Let>` keep it, because a return written under them is written in the body the author could see. A component invocation hides it from the invoked body, so a component's own `<Return>` satisfies its own declaration; a nested value body installs a separate one; and content the caller projected restores the caller's, every projection of one authored element restoring the same state. Dynamically scanned Markdown and a foreign body receive none, so a `<Return>` there stays reserved and never resolves a component named `Return`. The first executed return claims the body synchronously, before evaluating its expression, so two returns racing through one body cannot both believe they were first. A second execution fails the body, evaluates nothing, and the first value is not published — there is no first-wins or last-wins fallback. A body that executes none reports the existing missing-return diagnostic, which is now reachable and is how a bounded search that found nothing reports itself. Preflight still runs before any body effect and still refuses a value body with no authored return, a return in a text body, `<Output>` in a value body, every malformed return, a missing `as`, and caller content offered to satisfy a callee's declaration. It no longer refuses one for being nested or for being one of several: two authored declarations are valid structure, so a second executed return is a runtime failure and effects preceding it may already have run. That timing change is the accepted consequence. `<Return>` still does not end the body. A return inside a loop needs its own `<Break />`. Architecture gains `definition-owned return state`; spec §5.4 and §6.10 state the same contract; Tier RV10/RV11 are rewritten and RV14 restated. Refs #640 * ✅ Prove the return frame's timing, ownership, precedence and replay The mechanics were implemented; six criteria of the frozen matrix had no discriminating test. They do now, and one of them found a stale contract. - RV10c starts two projections of one authored `<Return>` before awaiting either, and holds the body to one claim and one evaluation. Moving the claim after evaluation makes it report two. - RV10d's second expression names a binding that does not exist, so evaluating it at all would report something louder than the duplicate diagnostic. A CLI value root proves exit 1, empty stdout, the exact root diagnostic, and no trace of that second expression. - RV11b projects a caller's `<Return>` through a function component's `content()`, beside the Markdown `<Content />` case. - RV11c runs `render()` inside a value component, so the generated `<Return>` sits beneath an active frame and is still reserved — refused on its own terms rather than for want of an owner. - RV12 adds a teardown failure after selection, and a halt taken after selection while a later component is suspended: teardown completes and no value is published. - RV17a interrupts after a completed effect and a selection, resumes the same journal, and proves the effect is not performed again, the selection is reconstructed, the value matches, and no return event was added. The journal is asserted non-empty so that absence is a real absence. The misplaced-return diagnostic said a `<Return>` "must be a direct top-level child", which this change made untrue. It now says the element is not written in the flow of a body that declares `returns`, and names the two things that can never declare one. Tier RV had two rows numbered RV14. Every identifier is now unique: RV10c and RV17a are added, RV11b and RV11c are broadened, RV12 records the precedence cases, and nested value bodies fold into RV14. Refs #640 * 🔐 Take selection out of the document's reach `ActiveReturn` is a named context, and a named context is reachable by name from a document's own eval block: `createContext("expand.return")` names the slot the engine publishes on. The frame it carried was a plain mutable object, so a document could write a value onto it and publish something the engine never validated: --- returns: { type: number } --- ```js eval import { createContext } from "effection"; const frame = yield* createContext("expand.return").get(); frame.selected = { value: "schema-bypassed" }; ``` <If condition={false}><Return value={1} /></If> That printed "schema-bypassed" and exited 0 — a string through a number schema, from a document whose only authored return was unselected. What travels contextually is now a frozen carrier holding no facts, only an accessor that answers nothing without a `Symbol()` this module never exports. The owner, schema, claim and selected value live in that carrier's closure, so the state's lifetime is one execution of one body rather than a table's, and a document that reads, enumerates, calls, copies or replaces the carrier reaches none of it. A carrier the engine did not mint cannot supply the token, and state it fabricates lacks the mark the engine puts on its own — so a `<Return>` that finds one is reserved instead of selecting through it. Both settlement sites read the carrier their own body minted and has held since, never one read back from the context. RV10e covers both consumers: the value-root exploit exits 1 with empty stdout and the existing missing-return diagnostic, and the same attack inside a Markdown value component with an unselected authored return reports that component's own missing-return diagnostic and binds nothing. Restoring state to the carrier makes both fail and the exploit publish again. No suppression: the first attempt kept the state in a module-scoped WeakMap, which `local/no-module-scoped-registry` reports. The closure carries the same guarantee with the lifetime the rule asks for. Refs #640 * 🔐 Hand a value body down the call stack, where a document cannot reach it The named-context attack was fixed by sealing the carrier, but the capability was still exported: an eval block's imports are hoisted and resolved like any module's, so a document could import `claimReturn` and `selectReturnValue` from this package's own source by file URL, read the real carrier out of `createContext("expand.return")`, and call the engine's helpers with the engine's carrier. A value root declaring `returns: { type: number }` published "schema-bypassed" at exit 0 without executing its authored <Return>. Sealing the carrier harder cannot fix that, because the two capabilities compose: anything published contextually is readable, and any exported function acting on what was published is callable. So selection now uses neither. A `ReturnBody` is a plain object whose claim, selection and settlement are closures over state nothing else holds, and it reaches the `<Return>` that claims it as an ordinary parameter of expansion — down the call stack, which document code cannot read or replace. Ownership is unchanged and now explicit at every site rather than ambient: a component invocation passes none, caller projection passes the caller's, dynamically scanned markdown and generated fragments pass none, and the two owners settle from the object their own expansion created and held as a local. `ActiveReturn` is gone; nothing exported takes another body's. RV10e gains the direct-import case: a document imports this module by file URL, uses every export it still has, and reaches for the old context. The run fails with the existing missing-return diagnostic, publishes nothing, and the schema-invalid string never reaches the caller. Refs #640 * 📄 Say that ownership travels down the call stack, not through a context The §6.10 paragraph and the Tier RV10e row still described the sealed-carrier design the previous commit replaced. * 📄 Describe the return boundary the engine actually has The glossary row and the "Definition-owned return state" section still described the frozen carrier in a named context — the design the direct-import attack retired two commits ago. Both now say what the code does: ownership travels down the expansion call stack as a local, no exported function accepts another body's, and importing the module that defines one gets a document a body of its own, connected to no execution. The rejected shape stays in the text as the reason: a sealed carrier in a context plus an exported `claim(carrier)` is forgeable however carefully the carrier is sealed, because the document calls the engine's own helper with the engine's own carrier. Without that sentence this reads like an odd way to pass a parameter, and the simplification back to a context is an easy one to make twice. Documentation only. No runtime behavior changed. Refs #640 --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent ad1c8d3 commit 2e5f0f9

9 files changed

Lines changed: 1099 additions & 94 deletions

File tree

‎architecture.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ Existing documents and code get aligned to this section retroactively.
108108
| syntax catalog | 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 |
109109
| 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 catalog reports cannot drift |
110110
| origin-only | the inspectability of a component whose contract could only be learned by loading it: a repository TypeScript module, whose schemas live on its exports and whose top level would run. Such an entry carries name, category, origin and source kind, and no contract field at all — an absent contract is stated, never rendered as an empty one |
111+
| definition-owned return state | which value body a `<Return>` selects for: one ephemeral state per execution of one value root or Markdown value component. Structural directives keep the ambient one, a component invocation hides it from the invoked body, a nested value body installs its own, and caller-projected content restores the caller's. It travels down the expansion call stack as a local rather than through a context, and no exported function accepts another body's, so nothing a document can read, replace, or import acts on a live one. The first claim on it is atomic, so a second executed return fails the body rather than replacing its value, and it appends no durable event |
111112

112113
## Three axes
113114

@@ -2352,6 +2353,59 @@ hidden inside library objects that accumulate. One exception: metadata an
23522353
author declares at module evaluation, about a value the author owns, may live
23532354
on that value.
23542355

2356+
### Definition-owned return state
2357+
2358+
A value body — a value root, or a Markdown component that declares `returns` —
2359+
selects its value with a `<Return>` its own flow reaches, rather than with a
2360+
direct top-level child. What decides whose declaration an element satisfies is
2361+
the body it was written in, which is the ownership `<Break>` already establishes
2362+
for the loop it exits.
2363+
2364+
One state exists per execution of one value body. `<If>`, `<Loop>`, `<Each>` and
2365+
`<Let>` keep the ambient one; a component invocation hides the caller's from the
2366+
invoked body, so a component's own `<Return>` satisfies its own declaration; a
2367+
nested value body installs a separate one, and both executions stand; and
2368+
content the caller projected restores the caller's, through a Markdown
2369+
`<Content />` and a function component's `content()` alike, with every
2370+
projection of one authored element restoring the same state. Dynamically scanned
2371+
Markdown and a foreign body receive none, so a `<Return>` there stays reserved
2372+
and never resolves a component named `Return`.
2373+
2374+
The first executed `<Return>` claims the state before evaluating its expression,
2375+
so two returns racing through one body cannot both believe they were first. The
2376+
second fails the body, evaluates nothing, and the first value is not published —
2377+
there is no first-wins or last-wins fallback. A body that executes none reports
2378+
that instead, which is how a bounded search that found nothing reports itself.
2379+
2380+
**Selection is not a decision a document makes about itself.** A document's own
2381+
eval block reaches further than it looks: a named context by name, because
2382+
`createContext(name)` names the slot the engine would publish on, and an internal
2383+
module by file URL, because an eval block's imports are hoisted and resolved like
2384+
any other module's. Anything published contextually is therefore readable, and
2385+
any exported function acting on what was published is callable — a sealed carrier
2386+
in a context plus an exported `claim(carrier)` is forgeable however carefully the
2387+
carrier itself is sealed, because the document calls the engine's own helper with
2388+
the engine's own carrier.
2389+
2390+
So selection uses neither. The body that owns a value is a plain object whose
2391+
claim, selection and settlement are closures over state nothing else holds, and
2392+
it reaches the `<Return>` that claims it as an ordinary parameter of expansion —
2393+
down the call stack, which document code cannot read or replace. Ownership is
2394+
explicit at every site rather than ambient: a component invocation passes none,
2395+
so an invoked body is isolated; caller projection passes the caller's, so
2396+
projected content still satisfies the declaration its author could see; and
2397+
dynamically scanned markdown and generated fragments pass none. Both settlement
2398+
sites read the body their own expansion created and held as a local. Importing
2399+
the module that defines one gains a document nothing — it gets a body of its own,
2400+
connected to no execution — so a value still crosses its declared schema on the
2401+
way out.
2402+
2403+
Selection is not authority and not durable state: it appends no journal event, a
2404+
partial replay reconstructs it while completed effects replay, and a completed
2405+
document replay reuses the retained result without expanding the body. `<Return>`
2406+
does not end the body, so later documentation runs and a later failure,
2407+
cancellation or teardown failure keeps its existing precedence.
2408+
23552409
## Foreground commands
23562410

23572411
An executable block is a foreground child process. Its output reaches the reader

‎packages/cli/tests/value-root.test.ts‎

Lines changed: 127 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,84 @@ const INVALID_STRUCTURE_ROOT = [
7777
"",
7878
].join("\n");
7979

80+
/** A conditional return the run selects — the shape #640 exists for. */
81+
const SELECTED_CONDITIONAL_ROOT = [
82+
"---",
83+
"returns:",
84+
" type: string",
85+
"---",
86+
"",
87+
"<If condition={true}>",
88+
'<Return value="chosen" />',
89+
"</If>",
90+
"",
91+
].join("\n");
92+
93+
/** The same shape, unselected: statically valid, and it executes no return. */
94+
const UNSELECTED_CONDITIONAL_ROOT = [
95+
"---",
96+
"returns:",
97+
" type: string",
98+
"---",
99+
"",
100+
"<If condition={false}>",
101+
'<Return value="chosen" />',
102+
"</If>",
103+
"",
104+
].join("\n");
105+
106+
/**
107+
* Two executed returns. The second expression names a binding that does not
108+
* exist, so evaluating it at all would report `SECOND_MARKER` instead — which
109+
* makes its absence proof that it was never evaluated.
110+
*/
111+
const DUPLICATE_RETURN_ROOT = [
112+
"---",
113+
"returns:",
114+
" type: string",
115+
"---",
116+
"",
117+
'<Return value="first" />',
118+
"",
119+
"<Return value={SECOND_MARKER.reached} />",
120+
"",
121+
].join("\n");
122+
123+
/**
124+
* A document attacking its own return state through the named context.
125+
*
126+
* `expand.return` is reachable by name from an eval block, so the document
127+
* reads the carrier the engine published, tries to write a selected value onto
128+
* it, tries to clear its claim, and finally replaces the context with a
129+
* fully-formed forgery. Its one authored `<Return>` is unselected, so anything
130+
* it manages to select would be a value the engine never validated.
131+
*/
132+
const CARRIER_ATTACK_ROOT = [
133+
"---",
134+
"returns:",
135+
" type: number",
136+
"---",
137+
"",
138+
"```js eval",
139+
'import { createContext } from "effection";',
140+
'const ctx = createContext("expand.return");',
141+
"const carrier = yield* ctx.get();",
142+
'try { carrier.selected = { value: "schema-bypassed" }; } catch (error) {}',
143+
"try { carrier.claimed = false; } catch (error) {}",
144+
"yield* ctx.set({",
145+
' owner: "__root__",',
146+
' returns: { type: "string" },',
147+
" claimed: true,",
148+
' selected: { value: "schema-bypassed" },',
149+
"});",
150+
"```",
151+
"",
152+
"<If condition={false}>",
153+
"<Return value={1} />",
154+
"</If>",
155+
"",
156+
].join("\n");
157+
80158
const FAILS_AFTER_RETURN_ROOT = [
81159
"---",
82160
"returns:",
@@ -164,7 +242,54 @@ describe("Tier VR — xmd run value roots", { sanitizeOps: false, sanitizeResour
164242
});
165243
expect(result.code).toBe(1);
166244
expect(result.stdout).toBe("");
167-
expect(result.stderr).toContain("no direct top-level <Return>");
245+
expect(result.stderr).toContain("no <Return>");
246+
});
247+
248+
it("VR4a: a selected conditional <Return> writes its result", function* () {
249+
const result = yield* useFixture({ "doc.md": SELECTED_CONDITIONAL_ROOT }, function* (dir) {
250+
return yield* runCli(["run", "doc.md"], { cwd: dir }).expect();
251+
});
252+
expect(result.code).toBe(0);
253+
expect(JSON.parse(result.stdout)).toBe("chosen");
254+
});
255+
256+
it("VR4b: an unselected conditional <Return> reaches the missing-return failure", function* () {
257+
// Statically valid, so the body runs; nothing executes the return, which is
258+
// how a bounded exhaustion reaches this diagnostic at all.
259+
const result = yield* useFixture({ "doc.md": UNSELECTED_CONDITIONAL_ROOT }, function* (dir) {
260+
return yield* runCli(["run", "doc.md"], { cwd: dir }).join();
261+
});
262+
expect(result.code).toBe(1);
263+
expect(result.stdout).toBe("");
264+
expect(result.stderr).toContain(
265+
"The root document declares `returns` but produced no <Return> value.",
266+
);
267+
});
268+
269+
it("VR4c: two executed <Return>s exit nonzero with the duplicate diagnostic", function* () {
270+
const result = yield* useFixture({ "doc.md": DUPLICATE_RETURN_ROOT }, function* (dir) {
271+
return yield* runCli(["run", "doc.md"], { cwd: dir }).join();
272+
});
273+
expect(result.code).toBe(1);
274+
// The first selected value is discarded rather than published.
275+
expect(result.stdout).toBe("");
276+
expect(result.stderr).toContain(
277+
"The root document declares `returns` but executed more than one <Return>.",
278+
);
279+
expect(result.stderr).not.toContain("SECOND_MARKER");
280+
});
281+
282+
it("RV10e: a document cannot select a value through the named return context", function* () {
283+
const result = yield* useFixture({ "doc.md": CARRIER_ATTACK_ROOT }, function* (dir) {
284+
return yield* runCli(["run", "doc.md"], { cwd: dir }).join();
285+
});
286+
expect(result.code).toBe(1);
287+
// Nothing was published: not the forged value, and not a partial result.
288+
expect(result.stdout).toBe("");
289+
expect(result.stderr).toContain(
290+
"The root document declares `returns` but produced no <Return> value.",
291+
);
292+
expect(result.stderr).not.toContain("schema-bypassed");
168293
});
169294

170295
it("VR5: a failure after <Return> exits nonzero with empty stdout", function* () {
@@ -201,7 +326,7 @@ describe("Tier VR — xmd run value roots", { sanitizeOps: false, sanitizeResour
201326
});
202327
expect(result.code).toBe(1);
203328
expect(result.stdout).toBe("");
204-
expect(result.stderr).toContain("no direct top-level <Return>");
329+
expect(result.stderr).toContain("no <Return>");
205330
});
206331

207332
/**

‎packages/core/src/execute.ts‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -79,11 +79,10 @@ import {
7979
expandSegmentsWithin,
8080
expandBody,
8181
bodyHasOutput,
82-
isTopLevelReturn,
83-
resolveReturnValue,
8482
validateBodyStructure,
8583
createBlockCounter,
8684
} from "./expand.ts";
85+
import { createReturnBody, missingReturnMessage } from "./return-flow.ts";
8786
import type { BlockCounter } from "./expand.ts";
8887
import {
8988
DocumentationError,
@@ -1594,7 +1593,11 @@ function* runValueRoot(
15941593
checkedFailures: CheckedFailures,
15951594
authority: ExpansionAuthority,
15961595
): Operation<DocumentResult> {
1597-
let produced: { value: Json } | undefined;
1596+
// Created outside the scope the body runs in, so the value it selected is
1597+
// still readable after that scope — and its teardown — has finished.
1598+
// The root's own, held as a local and handed to the segments it expands, so
1599+
// nothing a document can read or replace decides what this root returns.
1600+
const ownBody = createReturnBody("__root__", returns);
15981601

15991602
yield* scoped(function* () {
16001603
yield* Component.around(
@@ -1607,10 +1610,6 @@ function* runValueRoot(
16071610
);
16081611

16091612
for (const segment of root.bodySegments) {
1610-
if (isTopLevelReturn(segment)) {
1611-
produced = { value: yield* resolveReturnValue("__root__", returns, segment) };
1612-
continue;
1613-
}
16141613
const expanded = yield* expandSegmentsWithin(
16151614
[segment],
16161615
root.meta,
@@ -1622,6 +1621,7 @@ function* runValueRoot(
16221621
0,
16231622
checkedFailures,
16241623
authority,
1624+
ownBody,
16251625
);
16261626
for (const resolved of expanded) {
16271627
const text = renderSegment(resolved);
@@ -1634,10 +1634,12 @@ function* runValueRoot(
16341634
});
16351635

16361636
yield* refuseCheckedFailure(checkedFailures);
1637-
if (!produced) {
1638-
throw new Error("The root document declares `returns` but produced no <Return> value.");
1637+
// Read after the body finished, so a return anywhere in it has executed.
1638+
const selected = ownBody.settle();
1639+
if (!selected) {
1640+
throw new Error(missingReturnMessage("__root__"));
16391641
}
1640-
return { status: "ok", output: chunks.join(""), value: produced.value };
1642+
return { status: "ok", output: chunks.join(""), value: selected.value };
16411643
}
16421644

16431645
/**
@@ -1774,6 +1776,7 @@ function* documentWorkflow(
17741776
rootPath,
17751777
checkedFailures,
17761778
authority,
1779+
undefined,
17771780
);
17781781
const text = selected.map(renderSegment).join("");
17791782
// An empty buffered root emits no output event.
@@ -1800,6 +1803,7 @@ function* documentWorkflow(
18001803
0,
18011804
checkedFailures,
18021805
authority,
1806+
undefined,
18031807
);
18041808

18051809
while (emittedThrough < produced.length) {

0 commit comments

Comments
 (0)