wave 3.5: Effect-native internals

[ScriptedAlchemy]

Child of #107. Inserted between Wave 3 (complete: #139-#151) and Wave 4 by owner decision on 2026-09-01.

Why

The internals keep hand-rolling what Effect provides: typed error unions (AgentRequestError, typed Observed reasons, AB fail-closed contracts), resource lifecycles (request leases, EpochStore staging/leases/recovery, session teardown), backpressure (#145's pull-gated decode), and manual AbortSignal threading. Waves 4-6 build the biggest concurrency surfaces yet (hook thin-clients under host deadlines, the MCP progress projector, the notices ledger, warm-runtime lifecycle) — building those Effect-native now is cheaper than migrating them later.

Version and surface

Exact pin effect@4.0.0-rc.113 (unified ecosystem version). Full surface available including effect/unstable/* — latest and greatest by default; the exact pin controls exposure, RC bumps are a named re-pin chore (same treadmill pattern as React, #107 R4), and each unstable-module adoption gets a one-line note in docs/effect-conventions.md so re-pins know what to re-verify.

Hard boundary rules

• The public authoring surface stays Promise + zod: await agent(), route modules, defineState, every subpath export, generated artifact signatures. The four-concept newcomer ledger is untouched; Effect never appears in user-facing types, docs, or examples' user code.
• Effect lives in internals of @agent-bundle/runtime and packages/agent-bundle/src/dev + the state kernel; each package gets exactly one boundary module (src/effect/boundary.ts) owning runPromise edges, AbortSignal ↔ interruption bridges, and error-channel mapping to the existing typed contracts. Ad-hoc runPromise outside boundary modules is mechanically enforced.
• zod stays at all schema boundaries (MCP SDK interop; recorded G-decisions).

Stages

• Stage 0 — foundation + agentic feedback loop: exact pin; vendored Effect source at repos/effect via git subtree (squash) with AGENTS.md read-only-reference rules and editor excludes; agent-patterns/effect-{stream,scope,concurrency,errors}.md generated from the vendored source; boundary module + bridges; docs/effect-conventions.md; tsgo language service with v4-aware diagnostics; boundary lint enforcement; stdio-hook cold-start baseline (the stage-2 budget gate).
• Stage 1 — state kernel internals (the exemplar): Provide an optional durable Agent state kernel #98's kernel + both drivers on Effect (Scope for txn/connection lifecycles, typed error channel) behind the unchanged API. Parity: the 18-case conformance suite, cross-process + SIGKILL proofs, packaging boundary, eval:spot.
• Stage 2 — runtime dispatcher internals: feat(runtime): stream Suspense replacements through Flight #145's pipeline on Effect Stream/fibers (native backpressure, interruption), dispatch()/stream() byte-compatible; parity: event-contract tests + example + eval:spot + the cold-start budget.
• Stage 3 — dev seam, one subsystem per PR (highest value, highest risk, last): EpochStore → Scope/acquireRelease; coalescing rebuilds → fiber + Semaphore/Latch; SSE hub → PubSub-backed with the identical wire contract; MCP session lifecycles (the fix(dev): fail MCP tool calls closed when the pinned epoch vanishes #134 fail-closed contract) as scoped resources. Parity: unchanged DTO/SSE wire contracts + dev/workbench e2e suites.
• Stage 4 — policy flip: all NEW internal mechanics in waves 4-6 (hook thin clients Compile semantic Agent event routes into native host hooks #97, MCP progress projector Build a real RSC Agent Document renderer with streaming semantics #96-s4, notices ledger Add recipient-aware notices and capability-gated delivery #99, read-only doctor Add safe managed lifecycle for generated host bundles #101-s1) are built Effect-native from day one behind Promise edges. Sequencing: stage 2 lands before Build a real RSC Agent Document renderer with streaming semantics #96 stage 4 so the progress projector is born on Effect streams.

Out of scope

Compiler pipeline migration, Effect Schema at the public zod boundaries, any public API change.

Landing bar

Scoped tests + typecheck + lint per PR, merge on green (owner policy); parity means existing tests unchanged and green. Fragile-seam discipline: stage 3 PRs land only with full parity; per-test rstest retries cover known flakes.

[ScriptedAlchemy]

Stage 2 (Effect-native dispatcher and stream pipeline) merged in d691cdb (#156).

Root cause of the final event-count hang, verified by bisect + instrumentation: teardown called cancel() on the Flight ReadableStream from an acquireRelease finalizer while the Flight client held its reader; the locked-stream rejection became an Effect.promise defect during scope close and wedged the event stream's exit. Fixed with scopedAbortSignal + Stream.interruptWhen on the Flight source (no interaction with the locked stream). Details and stage-3 helped/hurt notes in the PR body.

Parity: runtime 144 pass / 1 skip; example 168 pass / 6 skip; typecheck / lint (boundary-lint green) / eval:spot green; cold start 41.82ms vs 39.74ms baseline (+5.2%, under the 15% gate); event-count test 30/30 stress runs.

[ScriptedAlchemy]

Wave 3.5 is complete. Stage 3 (dev seam) landed one subsystem per PR, strictly parity-gated — every existing dev/workbench suite passed unchanged, zero pin flips across the stage.

PR	Subsystem	Merge SHA
#158	Dev-seam boundary module (packages/agent-bundle/src/effect/boundary.ts, exact effect@4.0.0-rc.112 pin, boundary-lint coverage)	70deb9987a0e81f7471764e317c0b963ff6e5116
#159	MCP session lifecycles as scoped resources; #134 fail-closed contract on the typed error channel (McpSessionStaleEpochError)	0343e04a59740015c6e3cd187c31de22e2674838
#160	Coalescing rebuild scheduler on fiber + Semaphore(1) + shared Deferred	87711c4f81b2c85bfccf51dd1fc9e41439a93775
#161	EpochStore staging/leases/recovery: process-wide lease mutexes as Semaphores, publication as an Exit-aware compensation saga, retention via forEach + per-element Exit	f596377618a634b7c0ba76d106886a8da76bd80e
#162	Conventions doc: stage-3 outcomes, helped/hurt addendum, unstable-adoption record (none)	44e31b56c0ea7debfff0b5fd9bf8764934e80f41

One honest exception, recorded in docs/effect-conventions.md: ProjectEventHub (the SSE hub) stays imperative. Its public contract is synchronous re-entrant fan-out — foreground shutdown depends on same-tick tombstone delivery (documented in foreground-server.ts) and ~15 tests pin sync replay/removal/ordering — which Effect PubSub (an async fan-out structure) does not model. The SSE wire contract (sequence numbers, replay-gap frames) is untouched either way.

Parity evidence per PR is in each PR body; the stage-3 tail runs were full unit pool 1999/0 plus the epoch-heavy integration suites 35/0, lint and typecheck green. Stage 4 (policy flip: new wave 4–6 internals born Effect-native behind Promise edges) is now in force.

[ScriptedAlchemy]

Wave 4 Lane A / #97 proof dependency is landed.

• Thin event-route clients + Effect-native local transport: feat(events): render native hooks through warm runtime #180 (363890b69d475d7a79ef50c4067fb49a9158ca87)
• examples/rsc-agent-runtime/src/events/tool/after.tsx migration + Claude/Codex schema-conformance replays: feat(examples): adopt semantic event route #182 (9004850090061bab8bacce1ab8635819399b39e8)
• pnpm eval:spot is green against the compiler-generated Claude event-route wrapper.

Lane C can proceed from current main.