# `@suaveplan/api-plugin-example` — reference plugin exercising every capability under every isolation tier

**Package**: `@suaveplan/api-plugin-example`
**Status**: PROPOSED
**Type**: new-package
**Stage**: 8 — see umbrella `openspec/changes/api-plugin-foundation/`

## Why

Per design doc §13.5, the reference plugin is a load-bearing integration test, not a tutorial. It exercises every contract surface in the foundation — every capability, every lifecycle hook, every route variant, every distributed-transaction surface, every error code mapping, every migration class. The host's CI runs the example's full integration suite on every host change so any host-side change that breaks the plugin contract fails loudly, in one place, against real Postgres + real Hono router.

The example also doubles as the canonical onboarding doc: when a plugin author asks "how do I use capability X?", the answer is "look at how `api-plugin-example` uses it."

## What changes

- ADDED: A complete `plugin.json` exercising every top-level key (`requiredCapabilities`, `optionalCapabilities`, `isolation`, `trustLevel`, `permissions`, `dependsOn`, `routes`, `graphql`, `websockets`, `sse`, `sagas`, `twoPhaseCommit`, `database`, `jobs`, `events`, `secrets`, `config`, `scopes`, `telemetry`, `openapi`, `errors`, `uninstall`).
- ADDED: `src/index.ts` exporting `definePlugin({ ... })` with:
  - REST routes covering every Section 6 step: public, private, validated, streaming, idempotent, rate-limited, RBAC-gated.
  - GraphQL types + resolvers + subscriptions (federated alongside a second tiny plugin in the integration test).
  - WebSocket endpoint with subscription fan-out (single-host bus AND multi-host bus exercised).
  - SSE endpoint with `Last-Event-Id` resume.
  - Owned saga (3-step) with compensations + 2PC participation flag.
  - Scheduled cron jobs (`reconcile-invoices`, `send-monthly-statements` per-tenant) + queued jobs (`send-receipt`).
  - Event publish + subscribe (`example.invoice.created`, subscribes to `users.user.deleted`).
  - Custom error codes (`PLUGIN.EXAMPLE.*`) with manifest-mapped statuses + redaction rules.
  - Custom metrics declared in manifest (`example.invoices_finalised_total`, `example.stripe.call_duration_ms`, `example.outstanding_invoice_count`).
  - Multiple secrets declared.
- ADDED: Migrations across two `schemaVersion` bumps in `migrations/postgres/` (and surrealdb / sqlite mirrors) to exercise upgrade-on-reload AND auto-rollback when the second migration is forced to fail (`tests/integration/migration-rollback.integration.test.ts`).
- ADDED: Integration test (`tests/integration/full-flow.integration.test.ts`) that boots the example against:
  1. `isolation: "trusted"`
  2. `isolation: "isolated"` (worker thread + worker-rpc)
  3. `isolation: "sandboxed"` with vm (`api-sandbox-vm`)
  4. `isolation: "sandboxed"` with WASM (`api-sandbox-wasm`)
  and exercises the full surface in each tier. Real Postgres via `testing-integration-postgres`, real Hono router.
- ADDED: Intentional schema-violation route (`/_/test/fail-response?failResponse=1`) to integration-test response validation in `enforce` and `warn` modes.

## Out of scope

- Production-grade business logic — the example's routes do the minimum to exercise the surfaces. They are NOT a billing engine.
- Cross-plugin federation specifics beyond the second-plugin pair used for federation tests.
- A web UI for the example — covered by separate frontend work.

## Source mapping

Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.

| Requirement | Design doc section |
|---|---|
| Reference plugin exercises every capability | §13.5 |
| Routes covering every Section 6 step | §13.5 |
| Migrations across two schema versions | §13.5 |
| Integration test against real Postgres + real Hono | §13.5 |
| Deploys against all three isolation tiers | §15 "What done looks like" |

## Verification approach

The example IS the integration test target. The spec is structured so every documented capability is a separate Requirement whose `Verified by:` cites a concrete integration-test `it(...)`. The integration tests live in this package's `tests/integration/` directory and run as part of host CI.

- `tests/integration/full-flow.integration.test.ts` — runs the full surface against all four isolation modes (parameterised over `["trusted", "isolated", "sandboxed-vm", "sandboxed-wasm"]`).
- `tests/integration/migration-rollback.integration.test.ts` — schema-bump upgrade + forced-failure rollback.
- `tests/integration/response-validation.integration.test.ts` — `?failResponse=1` in `enforce` vs `warn` modes.
- `tests/integration/graphql-federation.integration.test.ts` — federated query across this plugin and a sibling test plugin.
- `tests/integration/ws-broadcast.integration.test.ts` — single-host and multi-host fan-out.
- `tests/integration/saga-2pc.integration.test.ts` — owned saga full happy + compensated paths; 2PC vote/commit/abort cycle.

## Migration impact

None — additive only. The example serves as the canonical integration target for host CI.