skills/docs/api-stack/api/api-manifest/README.md

# @suaveplan/api-manifest - Zod manifest schema, parser, cross-field validators, dep-graph resolver, capability resolver, and canonical hasher for Suaveplan API plugin system

Stage-1 contract package of the Suaveplan API plugin system: Zod schemas, parser, cross-field validators, dependency-graph resolver, capability resolver, and canonical hasher for the `plugin.json` manifest documented in
`docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md` §3.

This package is the single source of truth for the declarative half of every plugin contract. Every consumer (host loader, admin API, CLI scaffolder, OpenAPI emitter, `definePlugin` typings) imports from here — the schema does not live in any single host implementation.

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

- [capability-resolver](./src/capability-resolver/capability-resolver.md) — Decide whether a plugin can boot against the host's registered capability set. Missing required capabilities block reso…
  - [capability-resolver](./src/capability-resolver/capability-resolver.md) — Decide whether a plugin can boot against the host's registered capability set. Missing required capabilities block reso…
- [dep-graph](./src/dep-graph/dep-graph.md) — Topologically order a set of plugin manifests so each plugin's `dependsOn` entries precede it. Deterministic — lexicogr…
  - [dep-graph](./src/dep-graph/dep-graph.md) — Topologically order a set of plugin manifests so each plugin's `dependsOn` entries precede it. Deterministic — lexicogr…
  - [semver](./src/dep-graph/semver.md) — Small in-house semver-range matcher used by the dep-graph and capability resolvers. Covers a deliberately narrow subset…
- [error-codes](./src/error-codes/error-codes.md) — Frozen `MANIFEST.*` error-code registry plus the concrete `SuaveplanError` subclass thrown by every public path in this…
  - [error-codes](./src/error-codes/error-codes.md) — Frozen `MANIFEST.*` error-code registry plus the concrete `SuaveplanError` subclass thrown by every public path in this…
- [hash](./src/hash/hash.md) — Compute `sha256:<hex>` over the canonical-JSON encoding of a manifest. Used by `RollbackJournal` entries and the plugin…
  - [canonical-json](./src/hash/canonical-json.md) — Canonical JSON encoder used by `hashManifest`. Object keys are sorted lexicographically at every depth; array order is…
  - [hash](./src/hash/hash.md) — Compute `sha256:<hex>` over the canonical-JSON encoding of a manifest. Used by `RollbackJournal` entries and the plugin…
- [parse](./src/parse/parse.md) — Two top-level entry points for converting an unknown JSON value into a typed `PluginManifest`. `parseManifest` is the t…
  - [parse](./src/parse/parse.md) — Two top-level entry points for converting an unknown JSON value into a typed `PluginManifest`. `parseManifest` is the t…
- [compat](./src/schema/compat.md) — Validates the compatibility block of a plugin manifest: the `apiHost` semver range and the two capability arrays (`requ…
- [config](./src/schema/config.md) — Plugin-level config block. `schemaPath` points at a JSON Schema the host validates user-supplied config against at inst…
- [database](./src/schema/database.md) — Database-wiring block. Pins whether the plugin needs a database connection, which engines it supports, its current sche…
- [depends-on](./src/schema/depends-on.md) — Map of plugin-name → semver range used by the dep-graph resolver. Names follow the same npm-package convention as `iden…
- [errors](./src/schema/errors.md) — Plugin-error status-map block. Maps `PLUGIN.<DOMAIN>.<REASON>` codes to HTTP status numbers and optional redaction path…
- [events](./src/schema/events.md) — Event-bus topology declaration. Lists the subjects this plugin publishes and the subjects it subscribes to. Subjects fo…
- [graphql](./src/schema/graphql.md) — Optional GraphQL contribution block. When `contributes` is `true`, the host loads the SDL at `types` (path relative to…
- [identity](./src/schema/identity.md) — Zod schema for the identity fields of a plugin manifest — the keys that uniquely identify a plugin in the registry and…
- [isolation](./src/schema/isolation.md) — Two Zod enum schemas covering the orthogonal isolation and trust axes of the manifest. Isolation determines how the hos…
- [jobs](./src/schema/jobs.md) — Background-job block: cron schedules and queued workers. Handlers live in the code half of the manifest; this block is…
- [openapi](./src/schema/openapi.md) — OpenAPI contribution block. When `contributes: true` the host emits a per-plugin OpenAPI document by introspecting the…
- [permissions](./src/schema/permissions.md) — Zod schemas for the sandbox permissions block. `permissions.fs` and `permissions.fetch` are host-proxied allowlists hon…
- [plugin-manifest](./src/schema/plugin-manifest.md) — Composite Zod schema joining every per-key sub-schema into a single strict-mode object. The inferred `PluginManifest` t…
- [routes](./src/schema/routes.md) — Validates the declarative HTTP-routes block. Carries the route `prefix` plus an optional `publicRoutes` array — routes…
- [sagas](./src/schema/sagas.md) — Saga ownership + participation block. `owns` lists the sagas this plugin orchestrates (each with a non-empty step list)…
- [scopes](./src/schema/scopes.md) — AuthZ scope declarations. Each entry pins a `resource:action` name and an optional human-readable description. The host…
- [secrets](./src/schema/secrets.md) — Declares the named secrets the plugin needs at boot. Names use SCREAMING_SNAKE_CASE so they map cleanly onto environmen…
- [sse](./src/schema/sse.md) — Server-Sent-Events endpoint declarations. Mirrors the WebSocket block's shape minus the heartbeat/connection cap — SSE…
- [telemetry](./src/schema/telemetry.md) — Telemetry-instrument declarations. The host pre-registers every named counter, histogram, and gauge so plugin code can…
- [two-phase-commit](./src/schema/two-phase-commit.md) — Two-phase-commit participation declaration. A plugin sets `participates: true` to opt into the host's 2PC coordinator;…
- [uninstall](./src/schema/uninstall.md) — Uninstall data-handling policy. Three modes: `archive` (move rows to a prefixed shadow table so they survive removal),…
- [websockets](./src/schema/websockets.md) — Validates the WebSocket endpoint declarations. Each entry pins a path, an optional auth scope, the set of subjects the…
- [testing](./src/testing/conformance.md) — Reusable conformance harness for downstream tooling (admin CLI, IDE plugin) that ships its own `parseManifest` implemen…
  - [conformance](./src/testing/conformance.md) — Reusable conformance harness for downstream tooling (admin CLI, IDE plugin) that ships its own `parseManifest` implemen…
- [validate-error-status-map-shape](./src/validators/validate-error-status-map-shape.md) — Defence-in-depth re-check of the `errors.statusMap` shape. The Zod schema already rejects malformed entries; this valid…
- [validate-openapi-requires-graphql-or-routes](./src/validators/validate-openapi-requires-graphql-or-routes.md) — Rejects manifests that declare an OpenAPI contribution but expose neither HTTP routes nor a GraphQL contribution. The O…
- [validate-permissions-when-sandboxed](./src/validators/validate-permissions-when-sandboxed.md) — Enforces that a `sandboxed`-tier plugin declares `permissions.budgets`. Without budgets the host can't enforce CPU/memo…
- [validate-saga-ownership](./src/validators/validate-saga-ownership.md) — Cross-field validator that rejects sagas whose step list references a plugin neither owned by this manifest nor declare…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/api-manifest
```

## Subpath exports

Each concern is a separate subpath so consumers tree-shake to exactly what they use.

- [`./schema`](./src/schema/plugin-manifest.md) — `pluginManifestSchema`, the composite Zod schema, plus every per-key sub-schema.
- [`./parse`](./src/parse/parse.md) — `parseManifest` and `parseManifestSafe`.
- [`./validators`](./src/validators/validate-saga-ownership.md) — four cross-field validators that Zod alone can't express.
- [`./dep-graph`](./src/dep-graph/dep-graph.md) — `resolveInstallOrder` and the in-house `satisfies` semver matcher.
- [`./capability-resolver`](./src/capability-resolver/capability-resolver.md) — `resolveCapabilities`.
- [`./hash`](./src/hash/hash.md) — `hashManifest` and the underlying `canonicalJson` encoder.
- [`./error-codes`](./src/error-codes/error-codes.md) — `MANIFEST_CODES` registry and `ManifestError`.
- [`./testing`](./src/testing/conformance.md) — `runManifestConformance` harness and fixtures.

## Modules

### Schema

- [`identity`](./src/schema/identity.md), [`compat`](./src/schema/compat.md), [`isolation`](./src/schema/isolation.md), [`permissions`](./src/schema/permissions.md)
- [`depends-on`](./src/schema/depends-on.md), [`routes`](./src/schema/routes.md), [`graphql`](./src/schema/graphql.md)
- [`websockets`](./src/schema/websockets.md), [`sse`](./src/schema/sse.md), [`sagas`](./src/schema/sagas.md), [`two-phase-commit`](./src/schema/two-phase-commit.md)
- [`database`](./src/schema/database.md), [`jobs`](./src/schema/jobs.md), [`events`](./src/schema/events.md)
- [`secrets`](./src/schema/secrets.md), [`config`](./src/schema/config.md), [`scopes`](./src/schema/scopes.md)
- [`telemetry`](./src/schema/telemetry.md), [`openapi`](./src/schema/openapi.md), [`errors`](./src/schema/errors.md), [`uninstall`](./src/schema/uninstall.md)
- [`plugin-manifest`](./src/schema/plugin-manifest.md) — the composite schema.

### Parse, validators, graph, capability, hash, testing

- [`parse`](./src/parse/parse.md)
- [`validate-saga-ownership`](./src/validators/validate-saga-ownership.md)
- [`validate-permissions-when-sandboxed`](./src/validators/validate-permissions-when-sandboxed.md)
- [`validate-openapi-requires-graphql-or-routes`](./src/validators/validate-openapi-requires-graphql-or-routes.md)
- [`validate-error-status-map-shape`](./src/validators/validate-error-status-map-shape.md)
- [`dep-graph`](./src/dep-graph/dep-graph.md), [`semver`](./src/dep-graph/semver.md)
- [`capability-resolver`](./src/capability-resolver/capability-resolver.md)
- [`hash`](./src/hash/hash.md), [`canonical-json`](./src/hash/canonical-json.md)
- [`testing`](./src/testing/conformance.md)
- [`error-codes`](./src/error-codes/error-codes.md)

## Error codes

Every code is namespaced under `MANIFEST.*` and produced by `defineCodes`. The eleven codes — `PARSE_FAILED`, `DEPENDENCY_CYCLE`, `MISSING_DEPENDENCY`, `DEPENDENCY_VERSION_MISMATCH`, `CAPABILITY_REQUIRED_MISSING`, `CAPABILITY_VERSION_MISMATCH`, `OPTIONAL_CAPABILITY_MISSING`, `INVALID_SAGA_OWNERSHIP`, `SANDBOX_REQUIRES_BUDGETS`, `INVALID_ERROR_STATUS_MAP`, `OPENAPI_REQUIRES_GRAPHQL_OR_ROUTES` — are pinned by a spec-conformance test and each has at least one production-path reference.

## Dependencies

- `@suaveplan/api-types` — the type-level view of the manifest (zero runtime).
- `@suaveplan/error` — `SuaveplanError`, `defineCodes`.
- `@suaveplan/types` — shared logger/clock/id-generator contracts.
- `zod` — runtime schema engine.

## License

MIT