# @suaveplan/api-worker-host - Worker-side runtime that hosts exactly one Suaveplan API plugin inside an isolated Worker thread. Provides the bootstrap entry point that handshakes with the main host, wires capability proxies via @suaveplan/api-worker-rpc, dispatches lifecycle commands (install/start/stop/uninstall/reload) to plugin hooks, and surfaces uncaught exceptions as WORKER_HOST.CRASHED envelopes so the main host's LifecycleDriver can transition the plugin to the crashed state.

Worker-side runtime that hosts exactly one Suaveplan API plugin inside
an isolated `Worker` thread. The main-process counterpart is
`@suaveplan/api-host`; this package owns everything that runs *inside*
the worker: bootstrap handshake, capability proxy wiring, lifecycle
command dispatch, and uncaught-exception → `WORKER_HOST.CRASHED`
propagation.

This is API plugin system (design doc §2.2, §5.2a).
The transport layer (`@suaveplan/api-worker-rpc`) is consumed here for
every cross-boundary frame.

<!-- begin:auto-docs -->
## Documentation tree

- [bootstrap](./src/bootstrap/bootstrap.md) — `bootstrapWorkerPlugin` is the single entry point a worker thread invokes to host exactly one Suaveplan API plugin. It…
  - [bootstrap](./src/bootstrap/bootstrap.md) — `bootstrapWorkerPlugin` is the single entry point a worker thread invokes to host exactly one Suaveplan API plugin. It…
- [capability-proxies](./src/capability-proxies/capability-proxies.md) — This module turns the capability-handle descriptor table delivered by the main host into a live, frozen map of RPC-back…
  - [capability-proxies](./src/capability-proxies/capability-proxies.md) — This module turns the capability-handle descriptor table delivered by the main host into a live, frozen map of RPC-back…
- [crash-detection](./src/crash-detection/crash-detection.md) — This module installs the worker-side safety net that turns silent process death into observable crash telemetry. Withou…
  - [crash-detection](./src/crash-detection/crash-detection.md) — This module installs the worker-side safety net that turns silent process death into observable crash telemetry. Withou…
- [error-codes](./src/error-codes/error-codes.md) — This module owns the namespaced `WORKER_HOST.*` error registry consumed by the worker-side runtime that hosts exactly o…
  - [error-codes](./src/error-codes/error-codes.md) — This module owns the namespaced `WORKER_HOST.*` error registry consumed by the worker-side runtime that hosts exactly o…
- [lifecycle](./src/lifecycle/lifecycle.md) — This module hosts the worker-side counterpart to the main host's `LifecycleDriver`. It owns the worker's nine-state lif…
  - [lifecycle](./src/lifecycle/lifecycle.md) — This module hosts the worker-side counterpart to the main host's `LifecycleDriver`. It owns the worker's nine-state lif…
- [protocol-extension](./src/protocol-extension/protocol-extension.md) — This module defines the Zod schemas that the worker host layers on top of the transport-level frame protocol owned by `…
  - [protocol-extension](./src/protocol-extension/protocol-extension.md) — This module defines the Zod schemas that the worker host layers on top of the transport-level frame protocol owned by `…
- [testing](./src/testing/testing.md) — `runWorkerHostConformance` spins up an in-process worker-shaped peer using paired `MessageChannel` ports. It exists so…
  - [testing](./src/testing/testing.md) — `runWorkerHostConformance` spins up an in-process worker-shaped peer using paired `MessageChannel` ports. It exists so…
<!-- end:auto-docs -->

## Layout

- [bootstrap](./src/bootstrap/bootstrap.md) — `bootstrapWorkerPlugin`
  validates the manifest + capability handles, builds the proxy map,
  mounts the lifecycle RPC server, posts the `worker-ready` frame.
- [capability-proxies](./src/capability-proxies/capability-proxies.md) —
  `installCapabilityProxies` builds frozen RPC-backed capability slots;
  `getCapability` enforces declared capabilities.
- [lifecycle](./src/lifecycle/lifecycle.md) — `createLifecycleReceiver`
  owns the nine-state worker-side FSM and the `LifecycleAck` envelope.
- [crash-detection](./src/crash-detection/crash-detection.md) —
  `installCrashDetector` wires `uncaughtException` /
  `unhandledRejection` to a `WORKER_HOST.CRASHED` envelope before
  exiting.
- [protocol-extension](./src/protocol-extension/protocol-extension.md) —
  Zod schemas for every worker-host envelope.
- [error-codes](./src/error-codes/error-codes.md) — nine stable
  `WORKER_HOST.*` codes.
- [testing](./src/testing/testing.md) —
  `runWorkerHostConformance` in-process simulator.

## Stability

- **Version**: `0.1.0` (Original).
- **Tier**: server (requires Node `process` + `MessageChannel`; Node
  18+).
- **Dependencies**: `@suaveplan/api-types`,
  `@suaveplan/api-worker-rpc`, `@suaveplan/api-lifecycle`,
  `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`,
  `tslib`, `zod`.

## Verification

```bash
bunx turbo lint typecheck test build --filter=@suaveplan/api-worker-host
bunx turbo test:coverage --filter=@suaveplan/api-worker-host
```

All four coverage dimensions land at 100/100/100/100.