# Capability Spec: api-host **Package**: `@suaveplan/api-host` **Status**: SHIPPED (Chunks A + B + C + D, 2026-05-25) > Every requirement below carries a `**Verified by:**` line. (See `openspec/AGENTS.md` Section 13.) Requirements are grouped by surface cluster: lifecycle, hot reload, capability registry, plugin ledger, admin API, error boundary, request pipeline, host composition, OTel, `definePlugin` DX. ## Requirements ### Requirement: Lifecycle FSM drives every plugin through documented states The package SHALL implement a per-plugin lifecycle driver covering every state and transition from design doc §4: `uninstalled`, `installing`, `installed`, `starting`, `started`, `rolled_back`, `crashed`, `stopping`, `stopped`, `uninstalling`, `install_failed`, `start_failed`, `uninstall_failed`. Each plugin SHALL have a per-plugin mutex; concurrent transition triggers MUST queue (only one transition in flight at a time). The FSM MUST emit `plugin.lifecycle_transitions_total{plugin, from, to, outcome}` on every transition. A handler throw inside a route or job tick MUST NOT transition the FSM — that is the error boundary's job (see "Error boundary" requirement). #### Scenario: every documented transition is reachable - **WHEN** a freshly-installed plugin is driven `install → installed → starting → started → stopping → stopped → uninstalling → uninstalled` - **THEN** every transition fires AND `plugin.lifecycle_transitions_total` records each one #### Scenario: per-plugin mutex collapses concurrent triggers - **WHEN** two `start()` calls arrive in the same microtask - **THEN** the second awaits the first AND only one `starting → started` transition is recorded #### Scenario: handler throw does not transition the FSM - **WHEN** a route handler throws `SuaveplanError` - **THEN** the error boundary catches it AND the plugin's state remains `started` **Verified by:** `src/lifecycle/lifecycle.test.ts::"every documented transition fires"` AND `src/lifecycle/lifecycle.test.ts::"per-plugin mutex collapses concurrent start triggers"` AND `src/error-boundary/error-boundary.test.ts::"handler throw does not transition FSM"` --- ### Requirement: `crashed` state is reachable only from worker tiers The package SHALL transition a plugin to `crashed` ONLY when its `isolation` tier is `isolated` or `sandboxed` AND its worker dies, OOMs, or exceeds its wall-clock budget. Trusted-tier plugins cannot reach `crashed` — a handler throw stays in `started` via the error boundary. Auto-restart with exponential backoff MUST trigger up to `crashRestartMax` (default 3) within `crashRestartWindowMs`; after the budget is exhausted the plugin parks in `crashed` until an operator calls `POST /admin/plugins/{name}/restart`. #### Scenario: trusted plugin handler throw stays started - **WHEN** a `trusted`-tier plugin's handler throws an uncaught exception - **THEN** the plugin state remains `started` AND no `crashed` transition is recorded #### Scenario: isolated plugin worker death triggers `crashed` - **WHEN** an `isolated`-tier plugin's worker emits an `exit` event with non-zero code - **THEN** the plugin transitions to `crashed` AND auto-restart fires once after backoff **Verified by:** `src/lifecycle/lifecycle.spec-conformance.test.ts::"trusted tier handler throw does not crash"` AND `src/lifecycle/lifecycle.spec-conformance.test.ts::"isolated tier worker exit transitions to crashed"` --- ### Requirement: Hot reload uses blue-green primitive by default The package SHALL implement the §8.1 blue-green reload primitive. Steps 1–8 of §8.1 MUST execute in order: snapshot to `RollbackJournal`, re-resolve manifest, import new module under `?v=N+1`, run migrations if `manifest.database.schemaVersion` increased, mount shadow router slot, run new `start()` + health probe, atomically flip the live-version pointer, drain the old slot. `host.config.blueGreen: false` MUST opt into the 503-window mode (§8.5) for environments that cannot tolerate two concurrent module instances. Native bindings present in the dep graph MUST refuse reload with `RELOAD_NATIVE_BINDING_HELD`. #### Scenario: blue-green flip is atomic and serves both old and new - **WHEN** a reload is in progress AND the version pointer has been flipped from N to N+1 - **THEN** new requests hit module N+1 AND in-flight requests continue against N until they settle or `drainDeadlineMs` (default 30s) elapses #### Scenario: native binding refuses reload - **WHEN** the dep graph of the new module imports a `.node` file - **THEN** the loader throws `RELOAD_NATIVE_BINDING_HELD` AND the shadow slot is discarded AND the live module continues serving #### Scenario: 503-window mode is opt-in via host config - **WHEN** `host.config.blueGreen === false` - **THEN** reload runs in single-slot drain-then-replace mode AND new requests during the drain window receive 503 + `Retry-After: 1` **Verified by:** `src/hot-reload/blue-green.test.ts::"blue-green flip is atomic and drains old slot"` AND `src/hot-reload/blue-green.test.ts::"native binding refuses reload"` AND `src/hot-reload/blue-green.test.ts::"503-window mode opt-in"` --- ### Requirement: RollbackJournal pins last 3 known-good specifiers and auto-rolls-back The package SHALL maintain a per-plugin ring buffer of depth 3 (configurable). Each entry SHALL match the §8.1a shape: `specifier`, `manifestHash`, `moduleRef: WeakRef | null`, `migrationCursor`, `capturedAt`, `version`. Entries SHALL be persisted to the plugin ledger so that after a host restart the rollback path still works (with one extra module import; the in-memory `moduleRef` is lost on restart). A `start_failed` event during a reload MUST auto-transition the plugin to `rolled_back` by re-activating the most-recent journal entry's specifier — operator action is NOT required for the happy rollback path. #### Scenario: ring buffer truncates to last 3 entries - **WHEN** five successful reloads happen - **THEN** `journal.length === 3` AND only the last three entries remain #### Scenario: auto-rollback on `start_failed` during reload - **WHEN** the new module's `start()` throws during a hot reload - **THEN** the plugin transitions `start_failed → rolled_back` AND the previous specifier from the journal is re-activated AND `plugin.rolled_back` is emitted #### Scenario: persisted cursor survives host restart - **WHEN** the host restarts AND the in-memory `moduleRef` is gone - **THEN** the persisted `specifier` + `migrationCursor` + `manifestHash` from the ledger let the host re-import the previous version with one additional `import(...)` call **Verified by:** `src/hot-reload/rollback-journal.test.ts::"ring buffer truncates to last 3"` AND `src/hot-reload/auto-rollback.test.ts::"start_failed during reload auto-rolls-back"` AND `src/hot-reload/rollback-journal.test.ts::"persisted cursor survives restart"` --- ### Requirement: CapabilityRegistry validates version compat at install The package SHALL expose a `CapabilityRegistry` accepting `defineCapability({ id, version, scope, provider, disposer })` registrations. On `install()` of any plugin, the registry MUST check every entry in the plugin's `requiredCapabilities` against (a) presence in the registry AND (b) version compatibility against the plugin's `apiHost` semver range. Missing → `CAPABILITY_NOT_REGISTERED`. Mismatch → `CAPABILITY_VERSION_MISMATCH`. Duplicate registration of the same `id` → `CAPABILITY_DUPLICATE_REGISTRATION`. Disposers MUST run in reverse-registration order on `stop()`. #### Scenario: missing required capability blocks install - **WHEN** a plugin declares `requiredCapabilities: ["db"]` AND no `db` adapter is registered - **THEN** install throws `CAPABILITY_NOT_REGISTERED` AND the plugin remains `installing` → `install_failed` #### Scenario: disposer order is reverse-registration - **WHEN** capabilities are registered in order `[logger, events, db]` AND `stop()` runs - **THEN** `db.disposer` runs first AND `logger.disposer` runs last **Verified by:** `src/capability-registry/capability-registry.test.ts::"missing required capability throws"` AND `src/capability-registry/capability-registry.test.ts::"disposer order is reverse-registration"` --- ### Requirement: Plugin ledger metadata DB ships its own forward-only migrations The package SHALL own a metadata DB whose schema is created and migrated by this package's own migration runner. Tables `suaveplan_plugin_ledger`, `suaveplan_rollback_journal`, `suaveplan_saga_instances`, `suaveplan_saga_steps`, `suaveplan_2pc_transactions` MUST exist after the runner completes. Migrations MUST be forward-only AND idempotent — running the runner twice MUST be a no-op. The default DB SHALL be SQLite at `host.config.metadataDbPath` (default `./suaveplan-host.db`); operators MAY override to Postgres or Surreal via `@suaveplan/db`. The ledger DB connection MUST NOT be shared with any plugin's own DB connection. #### Scenario: every documented table exists after migration - **WHEN** the migration runner completes against a fresh SQLite file - **THEN** every documented table is present with the documented columns #### Scenario: migration runner is idempotent - **WHEN** the runner is invoked twice in sequence - **THEN** the second run is a no-op AND no error is thrown **Verified by:** `src/plugin-ledger/migrations.test.ts::"every table exists after migration"` AND `src/plugin-ledger/migrations.test.ts::"migration runner is idempotent"` --- ### Requirement: Admin API surface is gated by `host:admin` RBAC and rate-limited The package SHALL mount the §8.4 admin endpoints under `host.config.adminPrefix` (default `/admin`, `null` disables HTTP admin entirely). Every endpoint SHALL require auth (no `publicRoutes` bypass) AND the `host:admin` scope. Per-principal rate limit MUST be 60 ops/min on read endpoints AND 1 op/min on destructive endpoints (`uninstall`, `force-uninstall`, `disable`). Every state-changing call MUST emit a `host.admin_action` audit envelope per §12.5 AND a `host.admin_action_total{action, outcome}` counter. #### Scenario: every documented endpoint is mounted - **WHEN** the host boots with default config - **THEN** every endpoint from §8.4 (`POST /admin/plugins/{name}/reload`, `disable`, `enable`, `install`, `uninstall`, `retry-install`, `retry-start`, `force-uninstall`, `GET /admin/plugins`, `GET /admin/plugins/{name}`, `GET /admin/capabilities`) is mounted #### Scenario: `adminPrefix: null` disables HTTP admin - **WHEN** `host.config.adminPrefix === null` - **THEN** no admin routes are mounted AND `GET /admin/plugins` returns 404 #### Scenario: destructive endpoint rate-limit kicks in at 2 requests / min - **WHEN** a single principal calls `POST /admin/plugins/x/uninstall` twice within 60 seconds - **THEN** the second call returns 429 **Verified by:** `src/admin-api/admin.test.ts::"every documented endpoint is mounted"` AND `src/admin-api/disabled.test.ts::"adminPrefix null disables admin routes"` AND `src/admin-api/admin.test.ts::"destructive rate-limit is 1 per minute"` --- ### Requirement: Error boundary produces the standard envelope and never leaks internals The package SHALL wrap every pipeline step (§6 steps 1–11) in an error boundary. The boundary MUST map: (a) `SuaveplanError` → status from the plugin manifest's `errors[code].status` map; codes not in the map → 500 with the code preserved in the envelope's `code` field; (b) `AbortError` → 499 (client gone); (c) anything else → 500 + log of the cause chain. The response body SHALL be the `ErrorEnvelope` from `api-types/errors` — `{ error: { code, message, status, requestId, traceId, details } }`. The `X-Trace-Id` response header MUST mirror `traceId`. `details` SHALL be redacted per manifest's `errors.redact[code]` policy AND auto-redacted by `@suaveplan/data-masking` for emails / CC shapes / JWT shapes. #### Scenario: unmapped code becomes 500 with code preserved - **WHEN** a handler throws `SuaveplanError` with code `PLUGIN.X.NOT_IN_MAP` - **THEN** the response status is 500 AND `body.error.code === "PLUGIN.X.NOT_IN_MAP"` #### Scenario: AbortError becomes 499 - **WHEN** the client drops the connection mid-request - **THEN** the boundary returns 499 AND no `api.errors_total` counter is incremented #### Scenario: trace id mirrors response header - **WHEN** any error response is produced - **THEN** `res.headers["x-trace-id"] === body.error.traceId` **Verified by:** `src/error-boundary/error-boundary.test.ts::"unmapped code preserves code in envelope"` AND `src/error-boundary/error-boundary.test.ts::"AbortError maps to 499"` AND `src/error-boundary/error-boundary.test.ts::"x-trace-id mirrors envelope traceId"` --- ### Requirement: Per-request pipeline orders the documented 11 steps and exposes OTel spans The package SHALL execute the §6 pipeline in the documented order: HTTP intake → route match → auth resolver → tenant resolver chain → (optional) rate limit → (optional) RBAC → body/params/query parse+validate → (optional) idempotency → capability scoping → plugin handler → response validation → response composition → telemetry close. Plugins MAY insert middleware between steps 7 (capability scoping) and 8 (handler) and NOWHERE ELSE. Streaming routes (`streaming: true`) MUST bypass steps 6 (body buffering) and 10 (response composition's buffering). Cookie-based auth MUST trigger CSRF verification via `Bun.CSRF` on non-GET/HEAD methods unless the route opts out with `csrf: false`. Response-validation strictness SHALL default to `enforce` (production: 500 on violation) and `warn` (development: log + counter, body passes through). #### Scenario: steps execute in documented order - **WHEN** a request flows through an instrumented pipeline - **THEN** the observed span tree matches §12.3 exactly (`api.request > api.route_match > api.auth.resolve > api.tenant.resolve > api.rbac.check > api.body.parse > api.body.validate > plugin.handler > api.response.validate > api.response.compose`) #### Scenario: plugin middleware insertion is restricted - **WHEN** a plugin attempts to register middleware that runs BEFORE auth - **THEN** the host throws `PIPELINE_MIDDLEWARE_SLOT_INVALID` at register time #### Scenario: cookie auth triggers CSRF on POST - **WHEN** an `auth.session` adapter sets a cookie-source flag AND a request arrives as `POST /x` without a CSRF token - **THEN** the pipeline returns 403 before reaching the handler **Verified by:** `src/request-pipeline/pipeline.test.ts::"steps execute in documented order"` AND `src/request-pipeline/pipeline.test.ts::"middleware insertion only between steps 7 and 8"` AND `src/request-pipeline/pipeline.test.ts::"cookie auth triggers CSRF on non-GET"` --- ### Requirement: OTel surface emits every documented metric and span The package SHALL emit every metric listed in §12.3 from at least one production path: `api.requests_total`, `api.request_duration_ms`, `api.body.bytes`, `api.response.bytes`, `api.errors_total`, `api.auth.failures_total`, `api.rbac.denials_total`, `api.tenant.unresolved_total`, `api.validation.failures_total`, `api.idempotency.replays_total`, `api.rate_limit.exceeded_total`, `plugin.lifecycle_transitions_total`, `plugin.reload_total`, `plugin.reload_duration_ms`, `plugin.unsafe_query_total`, `host.admin_action_total`. Each metric SHALL carry the documented label set. Tenant label MUST be opt-in via `host.config.otel.tenantLabelOptIn` to bound cardinality. #### Scenario: every documented metric appears in the in-memory exporter - **WHEN** the test exercises one production path per metric AND collects from `InMemoryMetricExporter` - **THEN** every metric name from §12.3 is present in the collected output with non-empty data points **Verified by:** `src/otel/otel.test.ts::"every documented metric is emitted"` --- ### Requirement: `definePlugin` types the capability map from `requires` literals The package SHALL export `definePlugin(spec)`. The `ctx` parameter passed to user lifecycle / route handlers SHALL have exactly the fields named in `requires` projected onto `ctx.capabilities`, plus the always-present base fields (`plugin`, `logger`, `events`, `config`, `jobs`, `abortSignal`, `instruments`, `secrets`). The orchestration-level `secrets: SecretsLike` slot is always present (the host injects `EmptySecrets` when no adapter is configured — see foundation-fix-gap-3); the capability-projected `ctx.capabilities.secrets` shape is reachable only when `requires` includes `"secrets"`. Accessing an undeclared capability via the capability slice MUST be a compile-time TypeScript error. #### Scenario: declared capability is typed and reachable - **WHEN** a plugin declares `requires: ["db", "auth.session"] as const` - **THEN** `ctx.capabilities.db` is typed as `AdminDatabaseLike` in lifecycle hooks AND `ctx.principal` is typed as `Principal | null` in route handlers #### Scenario: undeclared capability is a compile error - **WHEN** a plugin declares `requires: ["db"] as const` AND references `ctx.capabilities.events.publish(...)` - **THEN** TypeScript reports an error AND `expectTypeOf().not.toHaveProperty("events")` passes **Verified by:** `src/define-plugin/define-plugin.spec-conformance.test.ts::"declared capability is typed in ctx"` AND `src/define-plugin/define-plugin.spec-conformance.test.ts::"undeclared capability is a TS error"` --- ### Requirement: Health and readiness endpoints reflect plugin states The package SHALL mount `GET /internal/livez` (200 if process is responding; no plugin checks) AND `GET /internal/readyz` (200 only if every plugin's state is `started` OR appears in an explicit allowlist; 409 + structured body otherwise). A periodic background health check (default every 10s) SHALL poll each plugin's optional `health` capability hook; a plugin reporting `unhealthy` for longer than `healthFailWindowMs` MUST emit a `plugin.unhealthy` event AND optionally auto-disable per host config (off by default). #### Scenario: livez is independent of plugin state - **WHEN** every plugin is `install_failed` AND `/internal/livez` is called - **THEN** the response is 200 #### Scenario: readyz returns 409 when any plugin is not started - **WHEN** one plugin is `crashed` AND `/internal/readyz` is called - **THEN** the response is 409 AND the body lists the unready plugins with their states **Verified by:** `src/host/health.test.ts::"livez is independent of plugin state"` AND `src/host/health.test.ts::"readyz returns 409 when a plugin is not started"` --- ### Requirement: `./testing` subpath populates the Stage-5 keystone The package SHALL declare `./testing` as a subpath export AND ship: 1. `createTestHost(config?: TestHostConfig): Promise` — Stage-5 keystone composing every in-memory adapter (`api-router-in-memory`, `api-auth-anonymous` / `api-auth-static-principal`, `api-db-sqlite-memory`, `api-events-in-memory`, `api-ws-broker-in-memory`, `api-tenant-provider-memory`, `api-secrets-env`) into a single line of consumer code. 2. `runPipelineRouterConformance(factory)` plus the `PipelineRouterConformanceFactory` + `PipelineRouteRegistration` types. The harness SHALL exercise the host's `PipelineRouter` contract against any adapter via a factory-supplied `(router, register, reload?)` triple, covering: register → match round-trip, `null` on miss, `statusMap` propagation, plugin ownership across reload, `:param` parsing, and collision detection. 3. The legacy `STAGE_2_RESERVED` sentinel, retained for back-compat with a value of `false` (Stage 2 shipped `true`); consumers that branched on `=== true` now branch on `=== false` to opt into the populated helpers. `createTestHost` SHALL resolve each adapter slot in override-beats-default order. Defaults: router from `@suaveplan/api-router-in-memory` (loaded via dynamic specifier to side-step the build-graph cycle the package's runtime dep on `api-host` introduces), auth as a `SessionResolverChain` over `createStaticPrincipalResolver` (when `seed.principal` is set) or `createAnonymousResolver`, tenant chain via `tenantResolverChainFromProvider(createMemoryTenantProvider(seed.tenants ?? []), { headerName: "X-Tenant-Id" })`, secrets via `createEnvSecrets(...)` when `seed.secrets` is set else `new EmptySecrets()`, admin db via `createSqliteMemoryAdapter()`, ledger db via a separate `bun:sqlite :memory:` handle. `capabilities`/`rateLimit`/`idempotency`/`csrf`/`audit`/`span`/`adminPrincipal` default to minimal in-process accept-all stubs. `TestHost` SHALL extend `Host` with `installFixturePlugin(fixture)`, `fetchAs(principal, request)`, `waitForEvent(topic, timeoutMs?)`, `dispose()`, and a `readonly adapters: TestHostAdapters` surface exposing the wired `HostAdapters` bag, the `InMemoryEventsBus`, the `LifecycleEventMap` event bus, and the materialised fixture-route registrations. `waitForEvent` SHALL first inspect the in-memory bus's recorded history then subscribe to future emissions; it SHALL reject the returned promise when `timeoutMs` elapses. `dispose` SHALL stop the wrapped host, dispose the event bus, dispose the ws-broker, close the admin db when `close` is available, and close the ledger-db handle. Calling `dispose` more than once is a no-op. The package's vite build SHALL emit `dist/testing/testing.js` AND `dist/testing/create-test-host/create-test-host.js` AND `dist/testing/pipeline-router-conformance/pipeline-router-conformance.js` so the subpath resolves at runtime. #### Scenario: zero-config boot yields a usable host with every default adapter - **WHEN** a test calls `await createTestHost()` with no arguments - **THEN** the returned `TestHost.plugins()` SHALL be empty AND `host.adapters.host.router` SHALL be defined AND `host.adapters.eventBus` SHALL be defined AND `host.fetch(new Request("http://t/internal/livez"))` SHALL resolve with status 200 #### Scenario: harness drives a reference PipelineRouter through every required case - **WHEN** a test calls `runPipelineRouterConformance({ label, build: () => ({ router, register, reload? }) })` - **THEN** `describe("PipelineRouter conformance — ${label}", ...)` registers six `it()` cases AND all of them pass against any adapter whose `register` populates a backing table consulted by `router.match` #### Scenario: harness asserts collision detection throws - **WHEN** the harness invokes `register({ plugin: "p", method: "GET", path: "/x" })` followed by `register({ plugin: "q", method: "GET", path: "/x" })` - **THEN** the second call SHALL throw — the harness uses `expect(...).toThrow()` without prescribing the error class so any adapter-specific typed error satisfies the contract #### Scenario: harness asserts plugin ownership survives reload - **WHEN** the factory exposes a `reload()` hook, the harness registers a route, calls `reload()`, then calls `router.match(...)` - **THEN** the matched route's `plugin` AND `params` survive the reload cycle #### Scenario: seed.principal reaches `ctx.principal` - **WHEN** a test calls `createTestHost({ seed: { principal } })` then installs a fixture plugin with a route reading `ctx.principal` - **THEN** the handler SHALL observe `ctx.principal.id === principal.id` on every request #### Scenario: seed.tenants + X-Tenant-Id reaches `ctx.tenant` - **WHEN** a test seeds `tenants: [{ id: "t-a", slug: "tenant-a", ... }]` AND issues `fetch(new Request(url, { headers: { "X-Tenant-Id": "t-a" } }))` - **THEN** the matched route handler SHALL observe `ctx.tenant.id === "t-a"` AND `ctx.tenant.slug === "tenant-a"` #### Scenario: seed.secrets exposes `ctx.secrets.require` - **WHEN** a test seeds `secrets: { FOO: "bar" }` AND a route handler calls `await ctx.secrets.require("FOO")` - **THEN** the handler SHALL receive the string `"bar"` #### Scenario: ctx.db round-trips a real bun:sqlite write/read - **WHEN** the smoke server provisions a tenant-aware table via the admin db AND the per-request handler INSERTs + SELECTs through `ctx.db` under an `X-Tenant-Id` header - **THEN** the SELECT SHALL return the inserted row #### Scenario: waitForEvent resolves on bus emission - **WHEN** a test calls `host.waitForEvent("topic.x", 2000)` AND a route handler (or test) calls `host.adapters.eventBus.publish("topic.x", payload)` - **THEN** the `waitForEvent` promise SHALL resolve with the payload #### Scenario: waitForEvent rejects on timeout - **WHEN** a test calls `host.waitForEvent("topic.never", 25)` AND no emission lands within 25ms - **THEN** the promise SHALL reject with an `Error` whose `message` contains `"timed out"` #### Scenario: dispose is idempotent - **WHEN** a test calls `host.dispose()` twice in succession - **THEN** the second call SHALL be a no-op (no thrown error, no double-close on the ledger handle) **Verified by:** `src/testing/create-test-host/create-test-host.test.ts` (13 unit tests against a hand-rolled router adapter), `src/testing/pipeline-router-conformance/pipeline-router-conformance.test.ts`, (downstream) `@suaveplan/api-router-hono`'s `src/pipeline/pipeline.conformance.test.ts`, AND `e2e/foundation-stack-test-host/tests/test-host.spec.ts` (8 Playwright smoke groups against a Bun.serve listener). --- ## ADDED Requirements — Chunk B (Lifecycle + Hot-Reload drivers) ### Requirement: `LifecycleDriver` executes the FSM side-effect descriptors The package SHALL ship `class LifecycleDriver` that orchestrates per-plugin lifecycle through `createPluginFsm` (from `@suaveplan/api-lifecycle`) and executes each `SideEffectOp` in the discriminated union against pluggable adapter surfaces. The driver SHALL expose verbs `install`, `start`, `stop`, `uninstall`, `crash`, `retryInstall`, `retryStart`, `clearRollback`, `forceUninstall`, `repair`, `startForReload`. The driver SHALL emit `plugin.lifecycle_transitions_total{plugin, from, to, trigger, outcome}` on every transition. Per-plugin mutex semantics are inherited from `createPluginFsm`; concurrent triggers queue FIFO. #### Scenario: every documented transition is reachable from operator verbs - **WHEN** a freshly-registered plugin is driven `install → installed → start → started → stop → stopped → uninstall → uninstalled` - **THEN** every transition fires AND every side-effect op (`mount-routes`, `register-jobs`, `subscribe-events`, `inject-capabilities`, `call-user-hook`, `mark-health`, `write-ledger`, `register-scopes`, `unmount-routes`, `pause-jobs`, `unsubscribe-events`, `dispose-capabilities`, `force-cancel-stragglers`, `apply-data-policy`, `drop-ledger`, `drop-scopes`) executes against the configured adapter. #### Scenario: typed events fire on the host bus - **WHEN** the driver completes a lifecycle transition that carries an `emit-event` side-effect - **THEN** the matching topic (`plugin.installed` / `plugin.started` / `plugin.stopped` / `plugin.uninstalled`) is published on the host `EventBus`. #### Scenario: install hook failure parks in `install_failed` - **WHEN** a plugin's `install` hook throws - **THEN** the FSM dispatches `installFailed` AND the plugin lands in `install_failed` AND `lastError` records the cause code + message. #### Scenario: start hook auto-retries before parking - **WHEN** a plugin's `start` hook throws on the first attempt but succeeds on retry - **THEN** the `start_failed` retry budget is consumed AND the FSM reaches `started` via the auto-retry loop. **Verified by:** `src/lifecycle/lifecycle.test.ts::"drives install → installed → starting → started → stopping → stopped → uninstalling → uninstalled"` AND `src/lifecycle/lifecycle.test.ts::"emits typed events on the host bus"` AND `src/lifecycle/lifecycle.test.ts::"install hook throw parks the plugin in install_failed"` AND `src/lifecycle/lifecycle-coverage.test.ts::"retryStart in runStartRetries can succeed before budget exhaustion"` --- ### Requirement: `LifecycleDriver.crash` honours the per-plugin budget The driver SHALL transition `started → crashed` on `crash(plugin, cause)` and auto-restart via `crashRestart` up to `crashRestartMax` (default 3) within the `CrashBudgetTracker` window. After the budget is exhausted, the plugin SHALL remain parked in `crashed` until an operator calls a recovery verb. `plugin.crashed` SHALL be emitted on the host bus. #### Scenario: single crash auto-restarts to started - **WHEN** `crash(plugin, new Error("worker died"))` is invoked on a `started` plugin - **THEN** the FSM transitions `started → crashed → starting → started` AND `plugin.crashed` is emitted. **Verified by:** `src/lifecycle/lifecycle.test.ts::"crash transitions to crashed then auto-restarts to started"` AND `src/lifecycle/lifecycle.test.ts::"crash budget exhaustion parks the plugin"` --- ### Requirement: `ReloadDriver` implements the §8.1 blue-green primitive The package SHALL ship `class ReloadDriver` that orchestrates the design §8.1 blue-green hot-reload. Each `reload(plugin, opts)` call SHALL: 1. Refuse a concurrent reload with `RELOAD.IN_PROGRESS`. 2. Snapshot the active activation into the rollback journal. 3. Apply `requiresReinstall(prev, next)` (from `api-lifecycle`). 4. Import the new module under `bustSpecifier(url, N+1)` via the injected `ModuleResolver`. 5. Walk native bindings and refuse the reload with `RELOAD.NATIVE_BINDING_HELD` when any are present. 6. Stage the new handle in the blue-green shadow slot. 7. Drive `lifecycle.startForReload(plugin, probe)` which fires the FSM `start` and the host-level health probe; failure dispatches `rollbackTriggered` so the FSM lands in `rolled_back`. 8. On success, atomically flip the blue-green slot and drain the prior slot. 9. Emit `plugin.reload_total{plugin, trigger, outcome}` + `plugin.reload_duration_ms` histogram. `blueGreen: false` SHALL opt into the §8.5 503-window mode for environments that cannot host two module instances concurrently. #### Scenario: happy reload flips blue-green and persists the journal - **WHEN** the new module imports cleanly AND `start()` AND `probe()` succeed - **THEN** the blue-green adapter receives `stageShadow → flip → releaseDraining` AND the journal gains an entry AND `lastReloadTrigger` matches the trigger argument. #### Scenario: concurrent reload is rejected - **WHEN** a second `reload()` is dispatched while the first is in-flight - **THEN** the second rejects with `HostError(RELOAD.IN_PROGRESS)`. #### Scenario: native binding refuses reload - **WHEN** the resolver's `walkNativeBindings()` returns a non-empty array - **THEN** the reload throws `HostError(RELOAD.NATIVE_BINDING_HELD)` AND the shadow slot is discarded. #### Scenario: 503-window opt-in skips blue-green slot manipulation - **WHEN** the driver is constructed with `blueGreen: false` - **THEN** the blue-green adapter records no `stage / flip / release` calls AND the reload still completes. **Verified by:** `src/hot-reload/hot-reload.test.ts::"imports, stages, flips, drains, and persists the journal"` AND `src/hot-reload/hot-reload.test.ts::"rejects a concurrent reload with RELOAD.IN_PROGRESS"` AND `src/hot-reload/hot-reload.test.ts::"throws NATIVE_BINDING_HELD when walk reports bindings"` AND `src/hot-reload/hot-reload.test.ts::"skips blue-green slot manipulation when blueGreen=false"` --- ### Requirement: `RollbackJournal` ring buffer + auto-rollback The package SHALL maintain a per-plugin `RollbackJournal` (default depth 3, configurable via `journalDepth`) via the in-memory `createRollbackJournal` from `@suaveplan/api-loader`. Each successful activation SHALL push a `RollbackJournalEntry` carrying `specifier`, `manifestHash`, `moduleRef: WeakRef