@ariestools/actor-engine

The host-agnostic actor and provider engine.

The engine parses one system configuration, resolves one provider graph, provisions one locator, constructs every actor with its own actor config and the same provider instances, config and resolution through restricted per-actor views, and returns one idempotently stoppable session. It does not know which surface drives it: host kits such as browser-kit and cli-kit supply lifecycle adapters and, when needed, a different supervision policy.

Renamed from @ariestools/actor-system, which remains as a deprecated alias for one release. See that package for the migration table.

startActorEngine(options) returns a handle before compilation. Subscribe to safe coarse boot events, read immutable bounded snapshot() records, await whenReady(), and call the handle's idempotent stop() to join cleanup even while launch is acquiring resources. A stop requested during acquisition waits for that acquisition, then rolls back acquired resources at the next cooperative checkpoint without starting later Providers or Actors. It does not forcibly abort arbitrary factory code or interrupt an already-running supervision call. Custom provisioners should call their supplied checkActive between acquisitions; the launcher also checks before constructing Actors. Failed compilation remains inspectable through the handle. Events carry fixed stage/outcome codes, sequence and nondecreasing elapsed milliseconds, never configuration or raw error messages. Both throwing and rejecting observers are isolated. The default provisioner records actual Provider acquisition/disposal; the launcher records Actor construction and one-shot execution. Completion events point to their start sequence, including failed acquisition and rollback. Resource IDs are public graph labels (never secrets); unsupported characters or labels over 128 characters are redacted. Custom provisioners receive the same optional diagnostics reporter and can use traceActorEngineResource around owned operations. Host diagnostic sinks compose with retained records and cannot replace operation results/errors. Built-in supervision records resident start, readiness-handler and stop spans; custom supervision policies report through the same optional observer seam. After compilation, snapshot().plan retains a safe graph before acquisition. describeActorEnginePlan(compiled) exposes that same projection independently: nodes, required/optional edges, bindings and absent optional capabilities, with separate omission counts and a configurable bound per collection. It never includes authored/resolved configuration or factories. Compilation failure retains events without pretending a resolved graph exists. renderActorEngineBoot(snapshot, 'text' | 'tree' | 'json') renders those same safe local records, preserving missing-graph and truncation indicators. It does not query a locator, collect errors or transmit telemetry.

The default memory provisioner gives each provider factory a frozen locator facade limited to that provider's declared dependency monikers. Undeclared getInstance and tryGetInstance calls reject with ActorEngineDependencyAccessError; aliases do not grant additional access. The facade has no registration or destruction methods and carries only the standard instrumentation context. Lookup remains available during that provider's disposal and is revoked afterward, including failed creation and rollback. Already returned provider objects are not revoked. Custom provisioners can use createActorEngineDependencyScope for the same boundary. Every actor factory also receives its own facade limited to that actor's dependencies, including when the host uses a custom provisioner. Actor access survives stop hooks, is revoked before provider release, and closes on failed factory construction or one-shot completion. A resident's whenStopped() settlement also revokes its scope while sibling actors and Providers remain live. requireResidentTerminationSignals: true rejects residents without that structural signal; compatibility launches retain system-drain revocation for actors without it. The session retains the trusted owner locator. Host-specific locator extensions must be supplied as declared providers instead of reaching through the actor context.

Declare optional edges in optionalDependencies. Compilation selects eligible implementations once and records missing, unconfigured optional capabilities in resolution.absentOptionalDependencies. Ambiguity, cycles, invalid explicit bindings and required transitive dependencies still fail. An absent declared optional lookup returns undefined through tryGetInstance; no runtime lookup selects a new provider. Compiled dependency declarations are immutable snapshots.

import {
  ActorEngineCatalog,
  createActorEngineProviderRegistry,
  launchActorEngine,
} from '@ariestools/actor-engine'

const actorRegistry = new ActorEngineCatalog()
const providerRegistry = createActorEngineProviderRegistry()

const session = await launchActorEngine({
  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 {
  compileActorEngine,
  launchCompiledActorEngine,
  sequentialActorEngineSupervision,
} from '@ariestools/actor-engine'

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

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

const session = await launchCompiledActorEngine({
  actorRegistry,
  compiled,
  supervision: sequentialActorEngineSupervision,
})

parallelActorEngineSupervision is the default and supports dynamic orchestration. sequentialActorEngineSupervision 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 ActorEngineTerminalFailureError that preserves the resource kind, resource ID, stable code, and original cause. The older whenFailed() method remains as a raw-error compatibility signal.

Supervising actors you constructed yourself

Hosts that build their own actors — rather than launching them from a config and catalog — supervise them through the same policies:

import { launchActors, sequentialActorEngineSupervision } from '@ariestools/actor-engine'

const session = await launchActors(actors, {
  supervision: sequentialActorEngineSupervision,
})

await session.whenTerminal().catch(handleFailure)
await session.stop()

createParallelActorEngineSupervision({ orchestrator }) supervises on an orchestrator the caller already owns. That policy then stops only the actors it registered, leaving the orchestrator's lifecycle to its owner.