✨ feat: give every component invocation its own resource scope

[taras]

Why

Component invocations had no resource lifetime of their own. Each created its eval scope with parentEvalScope.eval(() => useEvalScope()), which parents the child to the parent's loop task, and EvalScope exposes no way to destroy one — so nothing was ever halted. Daemons and persist eval resources lived until the document ended.

The spec rows that said otherwise — L3, Q5, S7 — were unimplemented and untested: every lifetime test asserted only "execute completed without hanging", which document-lifetime teardown satisfies equally well.

This is the lifecycle #189 (<TempDir>) is blocked on: a watcher projected into a component must stop before that component's cleanup runs.

What changes

Before:

• A daemon started inside a component was still alive after that component finished.
• A resource a TypeScript component acquired was released with no relationship to when its projected content stopped.
• FunctionComponent was declared Workflow<string>, so a .ts component's only bridge to Effection was ephemeral().

After:

• Every Markdown and TypeScript component invocation is a resource scope, torn down when the invocation completes.
• Content the component projects stops before the component releases anything of its own.
• A component acquires resources with ordinary operations and needs no wrapper.

How it works

withInvocation() → scoped invocation frame → evalHost → body task → content scope

An invocation creates its eval scope on its own expansion frame and runs its body inside a task that scope owns. That collapses the engine's two parallel context chains into one, which is what makes middleware installed by a component visible to its projected content — including persistent work created there — while ancestor persistent middleware stays visible to nested invocations.

Leaving the invocation runs one destructor with three ordered stages:

1. halt the content scope — everything projected content created;
2. halt the body — the resources the component itself acquired;
3. halt the invocation scope — whatever persist and daemon retained.

Each stage finishes before the next begins, so the ordering never depends on the order a component happened to acquire things in. Every stage is attempted even when an earlier one fails, and failures are reported together.

Review guide

Start with: packages/core/src/invocation.ts

Then review:

1. specs/executable-mdx-spec.md §4.4 — the three nested eval scopes, the boundary, and teardown.
2. packages/core/src/invocation.ts — the two-phase handshake, single-flight content scope, ordered teardown.
3. packages/core/src/types.ts — the ComponentExecution contract.
4. packages/core/src/errors.ts + component-api.ts — reporting vs settling.
5. packages/core/src/expand.ts — both component paths through withInvocation.

Look carefully at:

• Providers are installed on the invocation's body task, not a nested scoped(). A nested scope releases author resources before teardown runs — that inversion is what O5 caught.
• Function-component projections leave the ambient environment in place. Capturing the caller's env broke AgentHarness, which publishes {harness.*} by installing an env for its own content.

What must stay true

• Workflow<T> stays assignable to Operation<T> — enforced by deno task check across every existing ephemeral-using component.
• A <Test>'s bindings stay invisible to the next test — checked by testing-mode.test.ts:178.
• Durable effects a component yields are still journaled and replayed — checked by O22.

How to verify it

• Q5 places a kill -0 probe in a block after the component while the document is still running, and gets STOPPED. Fails if a daemon keeps document lifetime.
• L3 does the same for a persist eval resource.
• O5/O6 assert the exact teardown timeline for a TypeScript component with no ephemeral(), scoped() or wrapper, with the resource acquired both before and after the first projection.
• O9/O10 make a teardown stage throw and prove the later stages still run.
• O22 runs a component that combines a durable effect with a directly acquired resource, then replays a stream with the root Close removed: the executor ran once, output is identical, the resource was re-established per execution.
• O23/O24 prove a persist eval block's projection settles under its own block's policy — throwing in documentation, collecting inside <Output>.

Scope

Included

• The invocation boundary, the projection foundation, and the error-policy split.
• ComponentExecution as the public component contract.
• <Test> composing the shared boundary instead of a private lease.
• useContent as an injected binding rather than a standard import, so a persistent evaluation can bind it to its source policy.

Intentionally unchanged

• Markdown <Content /> is still substitution-based; §4.4 states in the present tense where each projection path anchors.
• No Workflow or ephemeral() contract in durable-streams, document execution, modifiers or output handling.
• provider-integration.test.ts S7 still asserts rendered text rather than teardown order. Making it real needs two nested providers' daemons to log on SIGTERM; L3 and Q5 now prove the same ordering deterministically, and the subprocess timing was not worth the flake risk.

Risks and limitations

• Running the body inside its eval scope's task is the largest structural change: every provider previously read from the expansion frame now arrives through one longer chain. provider-integration.test.ts S1–S15, sample-component.test.ts and the Sampling smoke chapter are the regression net.
• Every invocation now waits for its projected content and its own daemons before returning, so daemon-heavy documents serialize more.

Scope confirmation

• Every changed file supports the purpose described above.
• Unrelated cleanup and formatting changes are excluded.
• Generated or mechanical changes are clearly identified.
• The description matches the final diff and test results.

[github-actions]

PR #210: ✨ feat: give every component invocation its own resource scope

23 files, +1819 / -235

Scope

🔴 PR has 2054 lines changed. Split into focused PRs.

🟡 2054 lines changed. PRs under 400 receive more thorough review.

🟡 23 files changed. Are all changes related?

Structural

✅ No structural bloat detected.

Slop

✅ Slop indicators look low.

Static Analysis

✅ Oxlint found no issues.

Correctness

No extraneous code patterns detected.