This package is the keystone of the API plugin system. Every downstream package either consumes api-host directly (worker proxies talk to it) or extends it (adapters register with its CapabilityRegistry).

Documentation tree

admin-api — createAdminApi builds the host-side Hono sub-router that exposes the design §8.4 admin surface — every operational en…
- admin-api — createAdminApi builds the host-side Hono sub-router that exposes the design §8.4 admin surface — every operational en…
- audit-sink — MemoryAdminAuditSink is the in-memory default audit sink for the host's admin API. Every admin endpoint emits a struc…
- idempotency-store — InMemoryIdempotencyStore is the process-local default for the admin API's Idempotency-Key enforcement. Mutating adm…
- rate-limiter — AdminRateLimiter enforces the design §8.4 per-principal rate limits on every admin endpoint. Read endpoints share a 6…
capability-registry — The CapabilityRegistry is the live, single-instance store of every capability adapter wired into a host process. Stag…
- capability-registry — The CapabilityRegistry is the live, single-instance store of every capability adapter wired into a host process. Stag…
define-plugin — definePlugin is the canonical entry point plugin authors call to declare their name / version / requires / `iso…
- define-plugin — definePlugin is the canonical entry point plugin authors call to declare their name / version / requires / `iso…
empty-secrets — EmptySecrets is the no-op default SecretsLike implementation the host injects into every PluginContext / `Request…
- empty-secrets — EmptySecrets is the no-op default SecretsLike implementation the host injects into every PluginContext / `Request…
error-boundary — The ErrorBoundary wraps every step of the per-request pipeline (design doc §6 steps 1–11) and projects every captured…
- error-boundary — The ErrorBoundary wraps every step of the per-request pipeline (design doc §6 steps 1–11) and projects every captured…
error-codes — This module owns every stable error code raised by @suaveplan/api-host and its sub-drivers (lifecycle, hot reload, ca…
- error-codes — This module owns every stable error code raised by @suaveplan/api-host and its sub-drivers (lifecycle, hot reload, ca…
host — createHost(config) composes every internal driver (LifecycleDriver, ReloadDriver, PluginLedger, `CapabilityRegi…
- host — createHost(config) composes every internal driver (LifecycleDriver, ReloadDriver, PluginLedger, `CapabilityRegi…
hot-reload — ReloadDriver implements the §8.1 blue-green hot-reload primitive plus the §8.1a RollbackJournal integration. Each `…
- file-watcher — FileWatcher is the dev-mode file-system watch primitive consumed by ReloadDriver's §8.3 trigger path. Each `registe…
- hot-reload — ReloadDriver implements the §8.1 blue-green hot-reload primitive plus the §8.1a RollbackJournal integration. Each `…
lifecycle — LifecycleDriver is the runtime executor for the per-plugin lifecycle FSM defined in @suaveplan/api-lifecycle. It ow…
- lifecycle — LifecycleDriver is the runtime executor for the per-plugin lifecycle FSM defined in @suaveplan/api-lifecycle. It ow…
otel — createHostInstruments builds the frozen bundle of every OpenTelemetry counter and histogram the host emits on a produ…
- otel — createHostInstruments builds the frozen bundle of every OpenTelemetry counter and histogram the host emits on a produ…
in-memory-bus — InMemoryPipelineEventsBus is the canonical fixture wired by createTestHost (test keystone) and consumed by every…
noop-bus — NoopPipelineEventsBus is the default value the host installs on HostAdapters.pipelineEvents when no operator-suppli…
pipeline-events-constants — @suaveplan/api-types is types-only — adding a runtime export there breaks the byte-size invariant CI enforces. The `P…
plugin-ledger — PluginLedger is the host-owned metadata store backing every plugin record the API host orchestrates. It persists the…
- migrations — HostMigrationRunner is the forward-only idempotent migration engine the API host runs against its plugin ledger DB. I…
- plugin-ledger — PluginLedger is the host-owned metadata store backing every plugin record the API host orchestrates. It persists the…
request-pipeline — RequestPipeline implements the design-doc §6 per-request data flow exactly: tenant resolve, CSRF check, session resol…
- request-pipeline-driver — This module exports the runPipeline function: the orchestrator that chains the §6 step gates (`request-pipeline-steps…
- request-pipeline-emitters — This module owns the three side-effecting closers the §6 pipeline calls once a request has reached its outcome: `emitAu…
- request-pipeline-helpers — This module concentrates the pure (no-this, no side-effecting) helpers the §6 request pipeline relies on: request-id…
- request-pipeline-outcomes — This module ties the bare emitters and validators together for the orchestrator. It exposes DriverConfig (the frozen…
- request-pipeline-stage-emit — This module wraps the PipelineEventsBus.emit calls the §6 11-step driver makes around every stage. The helper central…
- request-pipeline-stage-skip — The §6 11-step request pipeline has four stages (csrf, capability, idempotency, audit) that may be conditionall…
- request-pipeline-steps — This module hosts the six per-request gate functions the §6 pipeline runs after route match and before plugin handler i…
- request-pipeline-validation — This module owns the two Zod-validation functions the §6 pipeline runs: validateRequest (step 6) parses body / query…
- request-pipeline — RequestPipeline implements the design-doc §6 per-request data flow exactly: tenant resolve, CSRF check, session resol…
reserved-prefix — The reserved-prefix contract publishes the canonical list of URL path prefixes that @suaveplan/api-host (and every fi…
- reserved-prefix — The reserved-prefix contract publishes the canonical list of URL path prefixes that @suaveplan/api-host (and every fi…
testing — @suaveplan/api-host/testing is a reserved subpath in API plugin system. The intent is to popul…
- create-test-host — createTestHost is The keystone of the @suaveplan/api-host/testing subpath. It composes every in-memory adap…
  - create-test-host — createTestHost is The keystone of the @suaveplan/api-host/testing subpath. It composes every in-memory adap…
- pipeline-events-conformance — This harness drives a host factory's RequestPipeline through a known-shape happy-path request and a known-shape 404 r…
  - pipeline-events-conformance — This harness drives a host factory's RequestPipeline through a known-shape happy-path request and a known-shape 404 r…
- testing — @suaveplan/api-host/testing is a reserved subpath in API plugin system. The intent is to popul…

Chunk status

@suaveplan/api-host ships in chunks per the precedent set by the @suaveplan/pdf migration. Chunk A — this release — ships the pieces every later chunk depends on:

Subpath	Status	Description
`./error-codes`	✅ Chunk A	Full union of `HOST_` / `PLUGIN_` / `RELOAD_` / `CAPABILITY_` / `ADMIN_*` codes + default status map + `HostError` class. Every later chunk's codes are pre-declared so the union is stable.
`./define-plugin`	✅ Chunk A	`definePlugin<const Caps>(spec)` author DX + `PluginModule<Caps>` + derived context types.
`./capability-registry`	✅ Chunk A	Runtime `CapabilityRegistry` with semver-shape validation, duplicate detection, `assertSatisfies` compat check, reverse-order disposers. `defineCapability(...)` helper.
`./otel`	✅ Chunk A	`createHostInstruments` + `HOST_COUNTER_NAMES` (12) + `HOST_HISTOGRAM_NAMES` (4) covering the §12.3 surface; per-plugin meter cache.
`./testing`	✅ Test tier	Populated with `createTestHost(config?)` — composes every test in-memory adapter into a running `Host` in one line. The legacy `STAGE_2_RESERVED` sentinel flips to `false`. The `runPipelineRouterConformance` harness still ships from this subpath.
`./lifecycle`	⏳ Chunk B	`LifecycleDriver` — per-plugin FSM mutex, every §4 transition, auto-rollback hand-off, worker-tier `crashed` auto-restart.
`./hot-reload`	⏳ Chunk B	`ReloadDriver` — blue-green primitive, `RollbackJournal` ring buffer, drain timer, native-binding guard.
`./plugin-ledger`	⏳ Chunk C	Host-owned metadata DB + forward-only idempotent migrations.
`./admin-api`	⏳ Chunk C	Hono sub-router for §8.4 endpoints + RBAC + rate-limit + audit envelope.
`./error-boundary`	⏳ Chunk D	Per-step boundary mapping `SuaveplanError → manifest statusMap`, `AbortError → 499`.
`./request-pipeline`	⏳ Chunk D	Steps 1–11 from §6 in documented order + CSRF gating + streaming bypass.
`./host`	⏳ Chunk D	Top-level `createHost(config)` composing every driver.

Until the follow-up chunks ship, this package is not a runnable host — it is the contract surface every downstream package can compile and link against.

Modules

src/error-codes/error-codes.md — error-code registry.
src/define-plugin/define-plugin.md — author-facing plugin entry point.
src/capability-registry/capability-registry.md — runtime capability registry.
src/lifecycle/lifecycle.md — LifecycleDriver driving every §4 transition.
src/hot-reload/hot-reload.md — ReloadDriver blue-green primitive (§8.1).
src/hot-reload/file-watcher.md — debounced filesystem watcher.
src/plugin-ledger/plugin-ledger.md — SQLite-backed host metadata store.
src/plugin-ledger/migrations.md — forward-only migration runner.
src/admin-api/admin-api.md — Hono admin sub-router (§8.4).
src/admin-api/audit-sink.md — pluggable audit sink.
src/admin-api/idempotency-store.md — Idempotency-Key store.
src/admin-api/rate-limiter.md — admin token-bucket limiter.
src/error-boundary/error-boundary.md — §12.7 pipeline-step throw containment.
src/request-pipeline/request-pipeline.md — §6 11-step per-request driver.
src/host/host.md — top-level createHost(config) composing every internal driver.
src/otel/otel.md — host instrument registry.
src/testing/testing.md — RESERVED subpath for test utilities.

Conformance posture

api-host carries suaveplan.conformanceSkip for api-lifecycle, api-loader, api-manifest, and api-secrets. These four packages each export a run*Conformance(factory) harness expecting the consumer to PROVIDE a concrete implementation of the contract (LifecycleDriverFactory, ManifestSchemaSet, etc.). api-host is the orchestrator that DRIVES those contracts — it consumes the abstract types, composes them via LifecycleDriver / ReloadDriver / RequestPipeline, and threads SecretsLike through ctx.secrets. It does not implement the abstract types itself.

The ./testing createTestHost(...) factory is the canonical proof that api-host composes the four contracts correctly. The e2e/foundation-stack-test-host Playwright suite drives every contract through createTestHost end-to-end and asserts on the observable behaviour (lifecycle install → start → handler invocation → secret resolution → ledger persistence). When the §16 check-conformance-tests.ts lint reports api-host as a consumer without conformance tests, the skip plus the e2e smoke is the documented answer.

If a future change extracts the conformance harnesses into adapter-agnostic forms (i.e., the harness signature shifts from factory: () => Impl to factory: () => Driver), the skip can be removed and the harness invoked through createTestHost's adapter bag.

Install

bun add @suaveplan/api-host

License

MIT

README.md Unescape Escape