Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
# @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).
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Defines `LIFECYCLE_CODES` — the frozen, namespaced registry of the four error codes raised by the `@suaveplan/api-lifec…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Defines `LIFECYCLE_CODES` — the frozen, namespaced registry of the four error codes raised by the `@suaveplan/api-lifec…
|
||||
- [fsm-factory](./src/fsm-factory/fsm-factory.md) — Binds the `@suaveplan/api-lifecycle` definitions together — states, transitions, side-effects, and the per-plugin mutex…
|
||||
- [fsm-factory](./src/fsm-factory/fsm-factory.md) — Binds the `@suaveplan/api-lifecycle` definitions together — states, transitions, side-effects, and the per-plugin mutex…
|
||||
- [mutex-contract](./src/mutex-contract/mutex-contract.md) — Defines `PluginMutex` — the contract guaranteeing at most one lifecycle transition per plugin in flight at any time — t…
|
||||
- [mutex-contract](./src/mutex-contract/mutex-contract.md) — Defines `PluginMutex` — the contract guaranteeing at most one lifecycle transition per plugin in flight at any time — t…
|
||||
- [reinstall-criteria](./src/reinstall-criteria/reinstall-criteria.md) — Decides whether a manifest update from `prev` to `next` requires a full reinstall path (`uninstalled → installing → ins…
|
||||
- [reinstall-criteria](./src/reinstall-criteria/reinstall-criteria.md) — Decides whether a manifest update from `prev` to `next` requires a full reinstall path (`uninstalled → installing → ins…
|
||||
- [retry-policies](./src/retry-policies/retry-policies.md) — Owns the retry-budget contract for the two automatic-recovery paths in the lifecycle FSM: `start_failed` (3 attempts wi…
|
||||
- [retry-policies](./src/retry-policies/retry-policies.md) — Owns the retry-budget contract for the two automatic-recovery paths in the lifecycle FSM: `start_failed` (3 attempts wi…
|
||||
- [side-effects](./src/side-effects/side-effects.md) — Encodes every side-effect the host runtime SHALL execute on each documented transition — `mount-routes`, `unmount-route…
|
||||
- [side-effects](./src/side-effects/side-effects.md) — Encodes every side-effect the host runtime SHALL execute on each documented transition — `mount-routes`, `unmount-route…
|
||||
- [states](./src/states/states.md) — Owns the runtime view of the plugin lifecycle's 13-state union. The `PluginState` type itself is re-exported from `@sua…
|
||||
- [states](./src/states/states.md) — Owns the runtime view of the plugin lifecycle's 13-state union. The `PluginState` type itself is re-exported from `@sua…
|
||||
- [testing](./src/testing/conformance.md) — Exposes `runLifecycleConformance({ factory, label })` — the reusable test harness `api-host` lifecycle driver…
|
||||
- [conformance](./src/testing/conformance.md) — Exposes `runLifecycleConformance({ factory, label })` — the reusable test harness `api-host` lifecycle driver…
|
||||
- [transitions](./src/transitions/transitions.md) — Encodes the complete legal-transition graph of the plugin lifecycle FSM — every `(from, to, trigger)` edge documented i…
|
||||
- [transitions](./src/transitions/transitions.md) — Encodes the complete legal-transition graph of the plugin lifecycle FSM — every `(from, to, trigger)` edge documented i…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Modules
|
||||
|
||||
- [`states`](./src/states/states.md) — `PluginState` 13-state union,
|
||||
`PLUGIN_STATES` tuple, `isLive` / `isParked` predicates.
|
||||
- [`transitions`](./src/transitions/transitions.md) — `PLUGIN_TRANSITIONS`
|
||||
edge table, `PluginTransitions` query class.
|
||||
- [`fsm-factory`](./src/fsm-factory/fsm-factory.md) — `createPluginFsm`
|
||||
binding to `@suaveplan/fsm`.
|
||||
- [`side-effects`](./src/side-effects/side-effects.md) — `SIDE_EFFECTS`
|
||||
descriptor map keyed `<from>|<to>`.
|
||||
- [`retry-policies`](./src/retry-policies/retry-policies.md) —
|
||||
`RETRY_POLICIES.startFailed`, `RETRY_POLICIES.crashed`, plus
|
||||
`StartFailedTracker` and `CrashBudgetTracker`.
|
||||
- [`mutex-contract`](./src/mutex-contract/mutex-contract.md) —
|
||||
`PluginMutex` interface and `InMemoryPluginMutex` reference impl.
|
||||
- [`reinstall-criteria`](./src/reinstall-criteria/reinstall-criteria.md) —
|
||||
`requiresReinstall(prev, next)` and `compareSemver`.
|
||||
- [`error-codes`](./src/error-codes/error-codes.md) — `LIFECYCLE_CODES`
|
||||
registry plus `LifecycleError`.
|
||||
- [`testing/conformance`](./src/testing/conformance.md) —
|
||||
`runLifecycleConformance({ factory, label })` harness must
|
||||
pass.
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
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` |
|
||||
|
||||
Reference in New Issue
Block a user