Effect v4 compiler composition: implementation and qualification

[benpsnyder]

Decision to make

Should Analog adopt Effect as an internal compiler dependency to provide a shared model for resource ownership, concurrent work and replaceable services?

The proposed implementation is analogjs/analog#2521. This issue owns the adoption rationale, alternatives and maintainer decision. The PR owns the implementation contract, metrics, tradeoffs, validation status and reproduction commands. Performance tables and CI snapshots are maintained there so readers have one place to verify them.

Why this is worth revisiting

A development compiler is a long-lived coordinator of native workers, file watchers, mutable compiler state and overlapping server lifetimes. It must decide what an edit invalidates, when an SSR read can safely proceed, and which work must finish before resources are released. Correctness depends on those policies agreeing across compiler modes.

The proposal uses Effect's scoped resources, service composition and concurrency primitives to express that coordination. Analog still owns the compiler policies and native Angular/Vite adapters. The claimed long-term value is that maintainers can inspect and test a common lifetime model instead of reconstructing ownership across independent callbacks. Whether the actual abstractions make this easier to maintain is the central review question.

The implementation now provides concrete evidence for reconsideration: improved editing behavior, resource/read race qualification and restart/shutdown tests. The PR's benefits and evidence show the results. Those results establish properties of the tested fixtures; they do not isolate the dependency's contribution or establish correctness for every code path. The SSR query-variant/pending-transform correction and fast behavioral reload fixes are now integrated and validated in the published PR. Review its correctness disposition and remaining qualification alongside the benefits; new sustained-operation evidence and the final archive are published, while the recorded performance gate misses and final Vite 6 browser restart failure remain open acceptance concerns.

What would make the dependency worthwhile?

Maintainer question	Value being proposed	How to assess it
Why use an additional runtime library inside a build tool?	A shared ownership/concurrency model for native compiler resources, reads, cancellation and restart.	Can a maintainer explain which scope owns a worker/listener and which operations must finish before it closes? Review the compiler contract.
Do the bridge APIs earn their complexity?	Replaceable compiler, stylesheet and storage capabilities allow tests to control failures and lifecycle events without starting every native subsystem.	Do the service contracts expose useful boundaries, or simply add indirection? Inspect the tests linked in the PR; request simpler boundaries where the extra layer does not help.
Does this impose Effect on application authors?	Keep compiler coordination internal and preserve the native consumer-facing integration.	Review the public boundary evidence and migration impact, including internal declaration and Node dependency costs.
Does the user benefit justify the maintenance burden?	A better editing experience with explicit freshness and cleanup behavior.	Read the HMR measurements alongside dependency/production costs, not just the headline improvements.

Alternatives to evaluate

Option	Potential benefit	Work or uncertainty remaining
Adopt the proposed Effect implementation	Use the implemented and qualified shared lifecycle/service model.	Maintainers must accept the dependency, prerelease policy, conceptual overhead and the PR's recorded costs.
Implement equivalent ownership and scheduling with native primitives	Avoid a direct Effect dependency and keep the concurrency vocabulary closer to existing TypeScript.	An equivalent implementation has not been built and benchmarked in this comparison. It would need to preserve the same lifecycle, cancellation, freshness and testing guarantees.
Port selected HMR improvements independently	Evaluate deferred work, invalidation, emit reuse and Angular metadata updates separately from dependency adoption.	Porting effort and regression coverage remain to be established. The current measurements cannot be treated as a ready-made result for a different implementation.

The alternatives are valid review options, not completed competing prototypes. Faster HMR alone cannot decide between them: the optimization policies can in principle be expressed with or without Effect. Conversely, showing that native primitives could implement a policy does not establish that maintaining a separate implementation would be cheaper.

Implementation obligations

Published in analogjs/analog#2521, runtime ca75a6d499a29fb765fe049db374f26319566585, with current repair and handoff evidence:

• Integrate the qualified SSR owner/query/pending-transform correction and retain its regressions.
• Automatically reload fast-mode behavioral edits, with updated browser behavior and conservative handling of ambiguous edits.
• Implement lazy session runtimes, supported Effect subpath imports, empty include-cache reuse and scoped warming of previously used SSR environments, with lifecycle/failure tests and an on-demand escape hatch.
• Implement and exercise supported native CSS updates, including DOM identity, focus, selection, child state, shared/lazy owners and compatibility fallbacks. Native updates remain limited to qualified integration externalization; ordinary-style automatic externalization was withheld after missed performance gates.
• Complete correctness qualification after resolving the final Vite 6/ngtsc browser restart failure and disposing of the unreproduced Windows initial-render timeout. Split-save, source-gate and pending SSR fetch repairs have targeted proof; the PR retains failed attempts and revision-specific qualification.
• Complete the bounded sustained-operation qualification and publish its evidence archive and synchronized maintainer points. This does not close the separate packed restart failure.
• Publish comparative measurements and their acceptance disposition, retaining failed cells, unavailable comparisons and qualified fallbacks. The previous comparison remains separately attributed; the newest correctness-only control and candidate artifacts are prepared, but the next comparison has not run.
• Resolve the remaining performance acceptance concerns before adoption, as judged by the maintainers; the PR does not claim the strict gate has passed.

The PR's current validation and remaining cautions are the source of implementation status and measurements. These checkboxes record implementation obligations; they do not settle the dependency decision.

Outstanding maintainer decisions

• Decide whether the service/lifetime model improves maintainability enough to justify a direct runtime dependency.
• Accept or reject the prerelease dependency policy and establish who will maintain its integration as upstream APIs evolve.
• Review whether the bridge contracts are proportionate, and identify any that should be simplified before adoption.
• Review the recorded performance and footprint costs and migration/compatibility behavior; decide which remaining concerns require changes before acceptance.
• Review the integrated correctness fixes and their validation, and decide whether remaining qualification concerns require changes before adoption.
• Select adoption, a narrower port, or further comparative work, and record the rationale in this issue.

These are decision criteria, not a claim of maintainer approval. The issue should close when the maintainers have recorded a disposition and the associated implementation obligations are satisfied; completed benchmarks alone do not settle the dependency question.

Evidence navigation

• Implementation, benefits and current PR status — analogjs/analog#2521.
• Behavior changes, benefits and compatibility fallbacks.
• HMR benchmark protocol, comparative results and sustained operation.
• Dependency footprint and historical production costs.
• Current implementation report and evidence archive.
• Maintainer points.
• Validation, qualified revisions and CI.
• Migration requirements.
• Commands to reproduce the comparisons.

The earlier issue description's measurement tables remain available in the committed historical evidence record. They are linked rather than copied here; current and historical revisions are distinguished in the PR.