Skip to content

Commit 4bc7454

Browse files
committed
✅ 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
1 parent 84b2793 commit 4bc7454

4 files changed

Lines changed: 336 additions & 11 deletions

File tree

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,23 @@ const UNSELECTED_CONDITIONAL_ROOT = [
103103
"",
104104
].join("\n");
105105

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+
106123
const FAILS_AFTER_RETURN_ROOT = [
107124
"---",
108125
"returns:",
@@ -214,6 +231,19 @@ describe("Tier VR — xmd run value roots", { sanitizeOps: false, sanitizeResour
214231
);
215232
});
216233

234+
it("VR4c: two executed <Return>s exit nonzero with the duplicate diagnostic", function* () {
235+
const result = yield* useFixture({ "doc.md": DUPLICATE_RETURN_ROOT }, function* (dir) {
236+
return yield* runCli(["run", "doc.md"], { cwd: dir }).join();
237+
});
238+
expect(result.code).toBe(1);
239+
// The first selected value is discarded rather than published.
240+
expect(result.stdout).toBe("");
241+
expect(result.stderr).toContain(
242+
"The root document declares `returns` but executed more than one <Return>.",
243+
);
244+
expect(result.stderr).not.toContain("SECOND_MARKER");
245+
});
246+
217247
it("VR5: a failure after <Return> exits nonzero with empty stdout", function* () {
218248
const result = yield* useFixture({ "doc.md": FAILS_AFTER_RETURN_ROOT }, function* (dir) {
219249
return yield* runCli(["run", "doc.md"], { cwd: dir }).join();

‎packages/core/src/expand.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3765,9 +3765,10 @@ function misplacedReturnError(segment: ComponentElement): ErrorSegment {
37653765
return {
37663766
type: "error",
37673767
message:
3768-
`${previewReturn(segment)} must be a direct top-level child of the document or ` +
3769-
"component whose `returns` declaration it satisfies. <Return> is reserved: it " +
3770-
"never resolves a component, and content a caller projects cannot declare one.",
3768+
`${previewReturn(segment)} is not written in the flow of a body that declares ` +
3769+
"`returns`, so there is no declaration for it to satisfy. <Return> is reserved: " +
3770+
"it never resolves a component, and neither markdown produced at runtime nor " +
3771+
"another component's body can declare one.",
37713772
source: "Return",
37723773
};
37733774
}

‎packages/core/tests/component-returns.test.ts‎

Lines changed: 295 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
import { beforeAll, describe, it } from "@executablemd/test-support/bdd";
1010
import { expect } from "@executablemd/test-support/expect";
11-
import { ensure, scoped, until } from "effection";
11+
import { ensure, scoped, spawn, until, withResolvers } from "effection";
1212
import type { Operation } from "effection";
1313
import { forEach } from "@effectionx/stream-helpers";
1414
import { InMemoryStream } from "@executablemd/durable-streams";
@@ -486,6 +486,295 @@ describe("Tier RV — component return values", () => {
486486
expect(said(result)).toContain("not the caller");
487487
});
488488

489+
it("RV11b: a caller's <Return> selects through a function component's content()", function* () {
490+
const result = yield* runFixture({
491+
"doc.md": [
492+
"---",
493+
"returns:",
494+
" type: string",
495+
"---",
496+
"",
497+
"<Wrap>",
498+
'<Return value="through content()" />',
499+
"</Wrap>",
500+
"",
501+
].join("\n"),
502+
"Wrap.ts": [
503+
'import { content } from "@executablemd/core";',
504+
"export default function*() {",
505+
" const rendered = yield* content();",
506+
" return `wrapped ${rendered}`;",
507+
"}",
508+
"",
509+
].join("\n"),
510+
});
511+
expect(result.value).toBe("through content()");
512+
});
513+
514+
it("RV11c: a <Return> render() generates stays reserved beneath a value body", function* () {
515+
// `render()` runs inside <Dynamic />, whose own value frame is active —
516+
// so this proves dynamic markdown is refused on its own terms rather than
517+
// for want of an owner to claim.
518+
const result = yield* run({
519+
"doc.md": '<Dynamic as="d" />\n',
520+
"Dynamic.md": [
521+
"---",
522+
"returns:",
523+
" type: string",
524+
"---",
525+
"",
526+
"```js eval",
527+
"const generated = yield* render(\'<Return value=\"dynamic\" />\');",
528+
"```",
529+
"",
530+
"{generated}",
531+
"",
532+
'<Return value="the component\'s own" />',
533+
"",
534+
].join("\n"),
535+
});
536+
// Diagnosed where it was generated, and no component named Return was
537+
// resolved to answer it.
538+
expect(said(result)).toContain("<Return> is reserved");
539+
expect(said(result)).toContain("neither markdown produced at runtime");
540+
// The generated element selected nothing: the run has no value at all.
541+
expect(result.value).toBeUndefined();
542+
});
543+
544+
it("RV10c: two concurrent projections claim once and evaluate once", function* () {
545+
// Both projections of one authored <Return> are started before either is
546+
// awaited, so the second reaches the body while the first is in flight.
547+
// The claim is taken synchronously, before the claiming return evaluates
548+
// anything, so exactly one expression is ever evaluated.
549+
const result = yield* runFixture({
550+
"doc.md": [
551+
"---",
552+
"returns:",
553+
" type: string",
554+
"---",
555+
"",
556+
"```js eval",
557+
"globalThis.__rv10c = 0;",
558+
"const mark = () => {",
559+
" globalThis.__rv10c += 1;",
560+
' return "evaluated";',
561+
"};",
562+
"```",
563+
"",
564+
"<Both>",
565+
"<Return value={mark()} />",
566+
"</Both>",
567+
"",
568+
].join("\n"),
569+
"Both.ts": [
570+
'import { content } from "@executablemd/core";',
571+
'import { all, spawn } from "effection";',
572+
"export default function*() {",
573+
" const first = yield* spawn(() => content());",
574+
" const second = yield* spawn(() => content());",
575+
" yield* all([first, second]);",
576+
' return "both";',
577+
"}",
578+
"",
579+
].join("\n"),
580+
});
581+
582+
expect(said(result)).toContain(
583+
"The root document declares `returns` but executed more than one <Return>.",
584+
);
585+
// The second execution evaluated nothing of its own, and the first
586+
// selected value was discarded rather than published.
587+
expect((globalThis as Record<string, unknown>).__rv10c).toBe(1);
588+
expect(result.value).toBeUndefined();
589+
});
590+
591+
it("RV12: a teardown failure after selection wins over the selected value", function* () {
592+
const result = yield* runFixture({
593+
"doc.md": [
594+
"---",
595+
"returns:",
596+
" type: string",
597+
"---",
598+
"",
599+
'<Return value="selected" />',
600+
"",
601+
'<Failing as="ignored" />',
602+
"",
603+
].join("\n"),
604+
// The body completes; teardown is what fails, after the value was
605+
// already selected.
606+
"Failing.ts": [
607+
'import { ensure } from "effection";',
608+
"export const returns = { type: 'string' };",
609+
"export default function*() {",
610+
' yield* ensure(function* () { throw new Error("TEARDOWN_FAILED"); });',
611+
' return "body finished";',
612+
"}",
613+
"",
614+
].join("\n"),
615+
});
616+
617+
expect(said(result)).toContain("TEARDOWN_FAILED");
618+
expect(result.value).toBeUndefined();
619+
});
620+
621+
it("RV12: halting after selection publishes no value and completes teardown", function* () {
622+
const reached = withResolvers<void>();
623+
const torn: string[] = [];
624+
const globals = globalThis as Record<string, unknown>;
625+
globals.__rv12reached = () => reached.resolve();
626+
globals.__rv12torn = () => torn.push("torn down");
627+
yield* ensure(() => {
628+
delete globals.__rv12reached;
629+
delete globals.__rv12torn;
630+
});
631+
632+
yield* scoped(function* () {
633+
const dir = path.join(os.tmpdir(), `returns-halt-${randomUUID()}`);
634+
yield* ensureDir(dir);
635+
yield* ensure(() => rm(dir, { recursive: true, force: true }));
636+
yield* writeTextFile(path.join(dir, "package.json"), JSON.stringify({ type: "module" }));
637+
yield* until(
638+
symlink(path.join(ROOT, "node_modules"), path.join(dir, "node_modules"), "dir"),
639+
);
640+
yield* writeTextFile(
641+
path.join(dir, "doc.md"),
642+
[
643+
"---",
644+
"returns:",
645+
" type: string",
646+
"---",
647+
"",
648+
'<Return value="selected" />',
649+
"",
650+
// Suspends after the value was selected, so the halt below lands
651+
// between selection and completion.
652+
'<Suspends as="never" />',
653+
"",
654+
].join("\n"),
655+
);
656+
yield* writeTextFile(
657+
path.join(dir, "Suspends.ts"),
658+
[
659+
'import { ensure, suspend } from "effection";',
660+
"export const returns = { type: 'string' };",
661+
"export default function*() {",
662+
" yield* ensure(() => { globalThis.__rv12torn(); });",
663+
" globalThis.__rv12reached();",
664+
" yield* suspend();",
665+
' return "unreachable";',
666+
"}",
667+
"",
668+
].join("\n"),
669+
);
670+
671+
const outcome: string[] = [];
672+
const task = yield* spawn(function* () {
673+
const execution = yield* execute({
674+
path: path.join(dir, "doc.md"),
675+
stream: new InMemoryStream(),
676+
includes: [dir],
677+
});
678+
const result = yield* execution;
679+
outcome.push(result.ok ? "ok" : "err");
680+
});
681+
682+
yield* reached.operation;
683+
yield* task.halt();
684+
685+
// Halted rather than completed: the selected value was never published
686+
// as a result, and the suspended component's teardown still ran.
687+
expect(outcome).toEqual([]);
688+
expect(torn).toEqual(["torn down"]);
689+
});
690+
});
691+
692+
it("RV17a: a partial replay reconstructs selection without repeating an effect", function* () {
693+
const stream = new InMemoryStream();
694+
const reached = withResolvers<void>();
695+
const globals = globalThis as Record<string, unknown>;
696+
globals.__rv17reached = () => reached.resolve();
697+
globals.__rv17suspend = true;
698+
yield* ensure(() => {
699+
delete globals.__rv17reached;
700+
delete globals.__rv17suspend;
701+
});
702+
703+
const dir = path.join(os.tmpdir(), `returns-replay-${randomUUID()}`);
704+
yield* ensureDir(dir);
705+
yield* ensure(() => rm(dir, { recursive: true, force: true }));
706+
yield* writeTextFile(path.join(dir, "package.json"), JSON.stringify({ type: "module" }));
707+
yield* until(symlink(path.join(ROOT, "node_modules"), path.join(dir, "node_modules"), "dir"));
708+
yield* writeTextFile(
709+
path.join(dir, "doc.md"),
710+
[
711+
"---",
712+
"returns:",
713+
" type: string",
714+
"---",
715+
"",
716+
"```bash exec",
717+
"echo work",
718+
"```",
719+
"",
720+
'<Return value="selected" />',
721+
"",
722+
'<Gate as="gate" />',
723+
"",
724+
].join("\n"),
725+
);
726+
// Suspends on the first pass only, so the resume can finish.
727+
yield* writeTextFile(
728+
path.join(dir, "Gate.ts"),
729+
[
730+
'import { suspend } from "effection";',
731+
"export const returns = { type: 'string' };",
732+
"export default function*() {",
733+
" if (globalThis.__rv17suspend) {",
734+
" globalThis.__rv17reached();",
735+
" yield* suspend();",
736+
" }",
737+
' return "gate";',
738+
"}",
739+
"",
740+
].join("\n"),
741+
);
742+
743+
const first: string[] = [];
744+
yield* scoped(function* () {
745+
const task = yield* spawn(() =>
746+
runExecution({
747+
path: path.join(dir, "doc.md"),
748+
stream,
749+
includes: [dir],
750+
commands: first,
751+
}),
752+
);
753+
yield* reached.operation;
754+
yield* task.halt();
755+
});
756+
expect(first).toEqual(["echo work"]);
757+
758+
globals.__rv17suspend = false;
759+
const second: string[] = [];
760+
const resumed = yield* scoped(() =>
761+
runExecution({ path: path.join(dir, "doc.md"), stream, includes: [dir], commands: second }),
762+
);
763+
764+
// The completed effect replayed from the journal rather than running.
765+
expect(second).toEqual([]);
766+
// Selection was reconstructed by ephemeral expansion, not recovered from
767+
// a record: the resumed run produces the same value.
768+
expect(resumed.value).toBe("selected");
769+
// Nothing about the selection was journaled.
770+
const descriptions = stream
771+
.snapshot()
772+
.flatMap((event) => (event.type === "yield" ? [event.description.type] : []));
773+
// The journal is not empty, so the absence above is a real absence.
774+
expect(descriptions).toContain("exec");
775+
expect(descriptions).not.toContain("return");
776+
});
777+
489778
it("RV14: a nested value body owns a separate declaration", function* () {
490779
const result = yield* run({
491780
"doc.md": '<Outer as="o" />\n\nGot {o}\n',
@@ -614,11 +903,15 @@ describe("Tier RV — component return values", () => {
614903
"",
615904
'<Return value="one" />',
616905
"",
617-
'<Return value="two" />',
906+
// Evaluating this expression at all would throw a different, louder
907+
// error, so the duplicate diagnostic below is proof it was never
908+
// evaluated.
909+
"<Return value={missingBinding.evaluated} />",
618910
"",
619911
].join("\n"),
620912
});
621913
expect(said(result)).toContain("<Verdict /> declares `returns` but executed more than one");
914+
expect(said(result)).not.toContain("missingBinding");
622915
// The first selected value is discarded rather than bound: the caller's
623916
// `as` never resolves, so nothing renders it.
624917
expect(said(result)).not.toContain("Got one");

0 commit comments

Comments
 (0)