@ariestools/actor-system

Environment-neutral, config-driven launcher for provider-backed actor systems.

The launcher parses one system configuration, resolves one provider graph, provisions one locator, constructs every actor with its own actor config and the same resolved provider system, and returns one idempotently stoppable session. Runtime packages such as browser-kit and cli-kit supply lifecycle adapters and, when needed, a different supervision policy.

import {
  ActorSystemCatalog,
  createActorSystemProviderRegistry,
  launchActorSystem,
} from '@ariestools/actor-system'

const actorRegistry = new ActorSystemCatalog()
const providerRegistry = createActorSystemProviderRegistry()

const session = await launchActorSystem({
  actorRegistry,
  config,
  providerRegistry,
})

await session.stop()

Hosts that need to inspect, validate, or reuse the resolved plan within one runtime can keep compilation separate from runtime acquisition:

import {
  compileActorSystem,
  launchCompiledActorSystem,
  sequentialActorSystemSupervision,
} from '@ariestools/actor-system'

const compiled = compileActorSystem({
  actorRegistry,
  config,
  providerRegistry,
})

// No provider has been created and no actor has been constructed or started.
console.log(compiled.providerSystem.resolution)

const session = await launchCompiledActorSystem({
  actorRegistry,
  compiled,
  supervision: sequentialActorSystemSupervision,
})

parallelActorSystemSupervision is the default and supports dynamic orchestration. sequentialActorSystemSupervision starts actors and joins their readiness in registration order, then rolls back or stops them in reverse order. Actors without the structural readiness surface are treated as ready by both policies.

The compiled object retains installed declarations and provider descriptors, so it is a runtime artifact rather than a structured-clone wire format. Browser realms exchange the serializable resolved config and plan identity through their host adapter, then bind those values to their local registries.

Resident runtime hosts can set requireResidentFailureSignals: true so every resident actor must expose whenFailed(). session.whenTerminal() races those actors with named provider and host/transport failure sources and rejects with an ActorSystemTerminalFailureError that preserves the resource kind, resource ID, stable code, and original cause. The older whenFailed() method remains as a raw-error compatibility signal.