skills/plugins/document-navigator/docs/api-stack/api/api-lifecycle/README.md

@suaveplan/api-lifecycle - Plugin lifecycle FSM contract: 13-state discriminated union, legal-transition table, side-effect descriptors, retry policies for start_failed and crashed, per-plugin mutex contract, and reinstall criteria — the definition consumed by api-host's lifecycle driver. Pure definitions + factories; no host runtime.

Stage-1 contract package for the Suaveplan API plugin system: the plugin-lifecycle finite state machine definition, the legal-transition table, the side-effect descriptors per transition, the retry policies for start_failed and crashed, the per-plugin mutex contract, and the requiresReinstall criteria. api-host consumes this package to execute the actual lifecycle — ships only the data and the factory.

Backed by @suaveplan/fsm (state-machine runtime), @suaveplan/retry (exponential backoff), @suaveplan/error (typed errors), and @suaveplan/events (observers).

Documentation tree

• error-codes — Defines LIFECYCLE_CODES — the frozen, namespaced registry of the four error codes raised by the `@suaveplan/api-lifec…
  • error-codes — Defines LIFECYCLE_CODES — the frozen, namespaced registry of the four error codes raised by the `@suaveplan/api-lifec…
• fsm-factory — Binds the @suaveplan/api-lifecycle definitions together — states, transitions, side-effects, and the per-plugin mutex…
  • fsm-factory — Binds the @suaveplan/api-lifecycle definitions together — states, transitions, side-effects, and the per-plugin mutex…
• mutex-contract — Defines PluginMutex — the contract guaranteeing at most one lifecycle transition per plugin in flight at any time — t…
  • mutex-contract — Defines PluginMutex — the contract guaranteeing at most one lifecycle transition per plugin in flight at any time — t…
• reinstall-criteria — Decides whether a manifest update from prev to next requires a full reinstall path (`uninstalled → installing → ins…
  • reinstall-criteria — Decides whether a manifest update from prev to next requires a full reinstall path (`uninstalled → installing → ins…
• retry-policies — Owns the retry-budget contract for the two automatic-recovery paths in the lifecycle FSM: start_failed (3 attempts wi…
  • retry-policies — Owns the retry-budget contract for the two automatic-recovery paths in the lifecycle FSM: start_failed (3 attempts wi…
• side-effects — Encodes every side-effect the host runtime SHALL execute on each documented transition — mount-routes, `unmount-route…
  • side-effects — Encodes every side-effect the host runtime SHALL execute on each documented transition — mount-routes, `unmount-route…
• states — Owns the runtime view of the plugin lifecycle's 13-state union. The PluginState type itself is re-exported from `@sua…
  • states — Owns the runtime view of the plugin lifecycle's 13-state union. The PluginState type itself is re-exported from `@sua…
• testing — Exposes runLifecycleConformance({ factory, label }) — the reusable test harness api-host lifecycle driver…
  • conformance — Exposes runLifecycleConformance({ factory, label }) — the reusable test harness api-host lifecycle driver…
• transitions — Encodes the complete legal-transition graph of the plugin lifecycle FSM — every (from, to, trigger) edge documented i…
  • transitions — Encodes the complete legal-transition graph of the plugin lifecycle FSM — every (from, to, trigger) edge documented i…

Modules

• states — PluginState 13-state union, PLUGIN_STATES tuple, isLive / isParked predicates.
• transitions — PLUGIN_TRANSITIONS edge table, PluginTransitions query class.
• fsm-factory — createPluginFsm binding to @suaveplan/fsm.
• side-effects — SIDE_EFFECTS descriptor map keyed <from>|<to>.
• retry-policies — RETRY_POLICIES.startFailed, RETRY_POLICIES.crashed, plus StartFailedTracker and CrashBudgetTracker.
• mutex-contract — PluginMutex interface and InMemoryPluginMutex reference impl.
• reinstall-criteria — requiresReinstall(prev, next) and compareSemver.
• error-codes — LIFECYCLE_CODES registry plus LifecycleError.
• testing/conformance — runLifecycleConformance({ factory, label }) harness must pass.

Quick start

import { createPluginFsm } from "@suaveplan/api-lifecycle";

const fsm = createPluginFsm({ plugin: "billing" });
await fsm.transition("install");
await fsm.transition("installCompleted");
await fsm.transition("start");
await fsm.transition("startCompleted");
// fsm.state === "started"

Error codes

Code	Thrown when
LIFECYCLE.ILLEGAL_TRANSITION	(from, trigger) not in the legal table
LIFECYCLE.MUTEX_HELD	assertAcquired called on a null tryAcquire result
LIFECYCLE.RETRY_BUDGET_EXHAUSTED	start_failed × 3 OR crashed × 3 in window
LIFECYCLE.REINSTALL_REQUIRED_VERSION_DOWNGRADE	next.version < prev.version