Refactor @matrixai/async-init into a lifecycle kernel, keep adapters in-repo, keep js-container as the only companion repo

[CMCDragonkai]

@matrixai/async-init has grown beyond "async init decorators".

It is effectively a lifecycle kernel for long-running, resourceful, asynchronous service objects.

This issue is to do the v3 refactor intentionally, instead of continuing to extend the current decorator-first model.

The result should stay constrained to just 2 repos for now:

• @matrixai/async-init - js-async-init
• @matrixai/container - js-container

No extra package splitting yet. Any runtime-specific integrations should stay inside these repos as adapters/subpath exports.

Why

The current library is doing multiple jobs at once:

• lifecycle state management
• concurrent transition control
• runtime method admission (@ready)
• error policy
• events/tracing hooks

It also duplicates the same core machinery across:

• CreateDestroy
• StartStop
• CreateDestroyStartStop

Conceptually, this is no longer just "async init". It is a reusable lifecycle model for invisible service objects in JS runtimes.

That is useful not only in Node/CLI, but also in browser, worker, scene/runtime, transport, and WASM-adjacent code.

Goal

Refactor @matrixai/async-init into a clean lifecycle kernel that:

• preserves the original lifecycle motivations
• supports modern TS/ESM/runtime assumptions
• remains usable in backend and frontend environments
• stops treating decorators as the architectural center
• leaves graph wiring and lazy dependency planning to js-container

Non-goals

This issue is not about:

• turning @matrixai/async-init into a full IoC framework
• turning it into a full actor/process runtime
• adding many more repos/packages
• replacing React/component lifecycle
• rebuilding the world before landing v3

High-level direction

@matrixai/async-init

Owns:

• lifecycle state machine
• transition orchestration
• operation admission
• ownership/disposal semantics
• lifecycle events / tracing hooks
• compatibility decorators
• runtime adapters in the same repo

@matrixai/container

Owns:

• service tokens/providers
• scopes
• overrides
• lazy dependency edges
• boot/shutdown ordering

Core refactor principles

1. Replace the 3 duplicated lifecycle implementations with 1 internal lifecycle engine.
2. Treat CreateDestroy, StartStop, and CreateDestroyStartStop as profiles over that engine.
3. Replace error-instance APIs with error classes/factories/options.
4. Remove stack-reset magic as part of the breaking change.
5. Keep decorators as compatibility sugar, not the core abstraction.
6. Keep runtime adapters in the same repo via subpath exports.
7. Keep js-container as the only companion repo for graph wiring.

Expected outcome

After this work, @matrixai/async-init should feel like a small, dependable substrate for invisible async services in JS, rather than a strange decorator package that happens to encode runtime semantics.

[linear]

ENG-650

[CMCDragonkai]

I want the architecture boundary to be explicit:

@matrixai/async-init

This is the lifecycle kernel.

It should answer:

• what states a service can be in
• how transitions happen
• how concurrent transitions/operations are controlled
• how disposal/ownership works
• how lifecycle/tracing events are surfaced

@matrixai/container

This is the graph/wiring layer.

It should answer:

• how services are provided
• how dependencies are scoped
• how overrides work
• how lazy dependencies are represented
• how boot/shutdown ordering is planned

This means:

• @matrixai/async-init should not absorb container logic
• @matrixai/container should not reimplement lifecycle logic

The relationship should be:

• async-init defines what a service is
• js-container defines how services are wired together

[CMCDragonkai]

These are the breaking changes I think are worth taking together as v3:

1. Replace error instances with error classes/factories/options.

   • no more passing new Error(...) into decorators
   • construct errors at throw-site

2. Remove resetStackTrace.

   • this should disappear entirely once errors are created at throw-site

3. Replace positional decorator arguments with option dictionaries.

   • example: lifecycle decorators should take a single options object
   • this also makes future evolution much cleaner

4. Unify lifecycle internals under a single engine.

   • current separate implementations should become profiles

5. Demote decorators from "the architecture" to "compatibility sugar".

   • explicit runtime API first
   • decorators second

6. Keep runtime adapters in the repo instead of creating more repos.

   • e.g. subpath exports for node/react/web/auto if needed

This is the right point to do a large mechanical downstream update as well.

[CMCDragonkai]

On adapters: I want to keep them in-repo for now.

I do not want to explode this into many packages yet.

The likely shape is:

• @matrixai/async-init
• @matrixai/async-init/node
• @matrixai/async-init/web
• @matrixai/async-init/react
• maybe @matrixai/async-init/auto

Same idea can apply later to js-container if needed.

Important constraint:

• the core kernel should stay runtime-agnostic
• runtime-specific behavior should live in adapters
• dynamic runtime selection should be optional, not hidden in the core

This gives us:

• one repo
• one conceptual package
• explicit environment entrypoints
• room for browser/frontend use without turning the kernel into framework soup

[CMCDragonkai]

I do not want this refactor to imply that @matrixai/async-init is only for backend/CLI.

The model is useful anywhere there are invisible, resourceful, asynchronous subsystems.

That includes browser/frontend contexts such as:

• transport/session managers
• workers
• scene/runtime backends
• WebSocket/WebRTC/WebGPU-adjacent services
• WASM wrappers
• sync/caching/background engines

What it should not become is a replacement for ordinary UI/component lifecycle.

So the stance is:

• yes to frontend/browser usage
• yes to adapters
• no to making UI/component lifecycle the responsibility of the kernel

The kernel is for invisible service lifecycle, not view lifecycle.

[CMCDragonkai]

Suggested implementation order:

Phase 1

Refactor @matrixai/async-init internals first:

• single lifecycle engine
• unified state model
• error factory/class model
• remove stack-reset logic
• keep existing behavioral semantics where possible

Phase 2

Rebuild compatibility decorators on top of the engine:

• CreateDestroy
• StartStop
• CreateDestroyStartStop
• ready

Phase 3

Add adapter entrypoints in the same repo:

• node
• web
• react
• optional auto

Phase 4

Do downstream mechanical migration:

• error instance -> error class/factory
• positional decorator args -> options dict
• any import path adjustments

Phase 5

Then flesh out @matrixai/container against the new kernel:

• tokens/providers
• scopes
• lazy dependency edges
• boot/shutdown ordering

This keeps the work sequenced and stops js-container from being designed against old v2 assumptions.