# `LifecycleDriver`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`LifecycleDriver` is the runtime executor for the per-plugin lifecycle FSM
defined in `@suaveplan/api-lifecycle`. It owns one record per registered
plugin (manifest hash, plugin module from `definePlugin`, schemaVersion,
current FSM state, retry trackers, hook log) and translates the
author-facing verbs `install` / `start` / `stop` / `uninstall` / `crash` /
`retryInstall` / `retryStart` / `clearRollback` / `forceUninstall` /
`repair` into the trigger sequences that the `createPluginFsm` interpreter
applies against the legal-transition table.

Each high-level operation dispatches the entry trigger, executes the
side-effect descriptors captured on the FSM (the discriminated-union
`SideEffectOp` from `@suaveplan/api-lifecycle/side-effects`), then
dispatches the completion trigger. Failures along the way auto-dispatch
the matching `*Failed` trigger and the FSM ends in the documented parked
state (`install_failed`, `start_failed`, `uninstall_failed`). Auto-retry of
`start_failed` follows the `@suaveplan/retry` exponential-backoff policy
defined in `RETRY_POLICIES.startFailed`; crashed plugins auto-restart up
to `RETRY_POLICIES.crashed.crashRestartMax` (default 3) with cooldown
reset through `CrashBudgetTracker`.

## Features

- Full coverage of every `(state, trigger)` edge in
  `@suaveplan/api-lifecycle`'s `PLUGIN_TRANSITIONS` table.
- Per-plugin mutex enforcement inherited from `createPluginFsm` — concurrent
  triggers queue FIFO; tests assert this dedup.
- `SideEffectOp` execution against pluggable adapter surfaces
  (`RouterAdapter`, `JobSchedulerAdapter`, `TopicSubscriberAdapter`,
  `HealthMarkerAdapter`, `LedgerAdapter`, `MigrationRunner`, `RbacAdapter`,
  `CapabilityInjector`, `InflightTracker`).
- Emits `plugin.lifecycle_transitions_total{plugin, from, to, trigger,
  outcome}` on every transition via Chunk-A's `HostInstruments`.
- Emits typed events onto the host `EventBus<LifecycleEventMap>` —
  `plugin.installed`, `plugin.started`, `plugin.stopped`, `plugin.uninstalled`,
  `plugin.rolled_back`, `plugin.crashed`.
- `snapshot(plugin)` renders an admin-friendly view with the FSM state, the
  most recent hook outcomes, and any captured `lastError`.
- `rollback(plugin, cause)` is invoked by the `ReloadDriver` (see
  `../hot-reload/`) on a failed reload — drives `starting → rolled_back`
  without operator intervention.

## Usage: Basic

```ts
import { EventBus } from "@suaveplan/events";
import {
    createHostInstruments,
    LifecycleDriver,
} from "@suaveplan/api-host";

const events = new EventBus();
const instruments = createHostInstruments({
    hostId: "h1",
    hostVersion: "0.1.0",
});

const driver = new LifecycleDriver({
    adapters: {
        router: { mount() {}, unmount() {} },
        jobs: { register() {}, pause() {}, unpause() {} },
        topics: { subscribe() {}, unsubscribe() {} },
        health: { mark() {} },
        ledger: {
            async write() {},
            async drop() {},
            async read() { return null; },
        },
        migrations: { async runUpTo() {} },
        rbac: { registerScopes() {}, dropScopes() {} },
        capabilities: {
            inject: () => ({}) as never,
            dispose: async () => {},
        },
        inflight: {
            async drain() { return 0; },
            forceCancel: () => 0,
        },
    },
    events,
    instruments,
});

driver.register({
    module: pluginModule,
    manifest,
    manifestHash: "sha256:...",
    specifier: "file:///opt/plugin/dist/index.js?v=1",
    schemaVersion: 1,
});

await driver.install(pluginModule.name);
await driver.start(pluginModule.name);
```

## Usage: Advanced

Customise the per-plugin mutex (e.g. backed by a distributed lock) and the
crash-restart cap:

```ts
import { LifecycleDriver } from "@suaveplan/api-host/lifecycle";
import type { PluginMutex } from "@suaveplan/api-lifecycle";

class RedisPluginMutex implements PluginMutex {
    async acquire(plugin: string) { /* … */ }
    tryAcquire(plugin: string) { /* … */ }
}

const driver = new LifecycleDriver({
    adapters,
    events,
    instruments,
    mutex: new RedisPluginMutex(),
    crashRestartMax: 5,
    sleep: () => Promise.resolve(),
});

driver.events.on("plugin.rolled_back", ({ plugin, from, to }) => {
    operator.notify(`${plugin} rolled back ${from} → ${to}`);
});

await driver.crash(plugin.name, new Error("worker exit code 137"));
const snap = driver.snapshot(plugin.name);
if (snap.lastError !== null) operator.escalate(snap);
```

## API Reference

- `class LifecycleDriver`
  - `constructor(options: LifecycleDriverOptions)`
  - `register(record: RegisteredPlugin): void`
  - `update(record: RegisteredPlugin): void`
  - `install(plugin: string): Promise<PluginState>`
  - `start(plugin: string): Promise<PluginState>`
  - `stop(plugin: string): Promise<PluginState>`
  - `uninstall(plugin: string): Promise<PluginState>`
  - `crash(plugin: string, cause: unknown): Promise<PluginState>`
  - `retryInstall(plugin: string): Promise<PluginState>`
  - `retryStart(plugin: string): Promise<PluginState>`
  - `clearRollback(plugin: string): Promise<PluginState>`
  - `forceUninstall(plugin: string): Promise<PluginState>`
  - `repair(plugin: string): Promise<PluginState>`
  - `rollback(plugin: string, cause: unknown): Promise<PluginState>`
  - `snapshot(plugin: string): LifecycleSnapshot`
  - `names(): readonly string[]`
- `interface LifecycleDriverOptions` — `adapters`, `events`, `instruments`,
  `mutex?`, `crashRestartMax?`, `sleep?`
- `interface LifecycleEventMap` — `plugin.installed`, `plugin.started`,
  `plugin.stopped`, `plugin.uninstalled`, `plugin.rolled_back`,
  `plugin.crashed`.
- Adapter surfaces from `lifecycle.types.ts` — `RouterAdapter`,
  `JobSchedulerAdapter`, `TopicSubscriberAdapter`, `HealthMarkerAdapter`,
  `LedgerAdapter`, `MigrationRunner`, `RbacAdapter`, `CapabilityInjector`,
  `InflightTracker`, `LifecycleAdapters`.

## Implementation Notes

The driver intentionally delegates illegal-transition detection to the
underlying `PluginFsm` — every operator verb maps to one entry trigger;
attempting `start()` from `crashed` therefore raises a
`LifecycleError(ILLEGAL_TRANSITION)` from the FSM rather than a duplicate
guard in the driver. This keeps the source-of-truth for legal transitions
in The contract package.

Side-effect ops `validate-manifest`, `resolve-deps`, `acquire-db-connection`,
`complete-otel-span`, `apply-data-policy`, and `rollback-to-prior-module`
are documented but execute as no-ops inside the driver: manifest validation
ran at registration time, dep-graph resolution is computed by
`api-manifest/dep-graph` before registration, the ledger adapter holds
the DB connection, OTel span completion is captured via the lifecycle
counter, the data policy is applied by the next `drop-ledger` op, and the
rollback module switch is performed by the `ReloadDriver` before the
`rolled_back` transition fires. Keeping the no-op branches lets Stage-3
wire concrete behaviour without revising the FSM definition.

Auto-retry of `start_failed` uses `backoffDelay(base, factor, attempt, max)`
locally rather than `@suaveplan/retry`'s `retry()` engine because the
driver needs to inter-leave the FSM transitions between attempts —
`@suaveplan/retry`'s engine is single-call-with-retries semantics. The
underlying delay strategy is identical to `RETRY_POLICIES.startFailed.delay`.