Initial Commit

openspec/changes/api-plugin-foundation/tasks.md

@@ -0,0 +1,137 @@
+# Tasks — API Plugin Foundation (umbrella)
+
+> Umbrella change. Tasks here track stage acceptance — per-package work is checked off in each package's own change. Do not retroactively tick boxes for work done before this change opened.
+
+## 0. Pre-flight (non-negotiable)
+
+- [x] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [x] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [x] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 0. Pre-work
+
+- [x] 0.1 Brainstorm + design doc at `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`
+- [x] 0.2 Design reviewed by `spec-document-reviewer` subagent (twice — once on initial draft, once on enterprise-scope rewrite)
+- [x] 0.3 User-approved scope: all 8 items previously deferred folded in as v1 design surface
+
+## 1. Per-package OpenSpec proposals authored
+
+### Stage 1 — Contracts
+
+- [x] 1.1 `api-types`
+- [x] 1.2 `api-manifest`
+- [x] 1.3 `api-router`
+- [x] 1.4 `api-graphql` (abstract contract)
+- [x] 1.5 `api-ws` (abstract contract)
+- [x] 1.6 `api-sse` (abstract contract)
+- [x] 1.7 `api-auth` (abstract session-resolver)
+- [x] 1.8 `api-auth-provider` (abstract provider)
+- [x] 1.9 `api-secrets` (abstract contract)
+- [x] 1.10 `api-tenant-provider` (abstract contract)
+- [x] 1.11 `api-loader`
+- [x] 1.12 `api-lifecycle`
+
+### Stage 2 — Host orchestration
+
+- [x] 2.1 `api-host`
+
+### Stage 3 — Worker isolation
+
+- [x] 3.1 `api-worker-rpc`
+- [x] 3.2 `api-worker-host`
+- [x] 3.3 `api-router-worker-bridge`
+- [x] 3.4 `api-db-worker-proxy`
+- [x] 3.5 `api-events-worker-proxy`
+- [x] 3.6 `api-secrets-worker-proxy`
+- [x] 3.7 `api-jobs-worker-proxy`
+- [x] 3.8 `api-logger-worker-proxy`
+
+### Stage 4 — Base adapters
+
+- [x] 4.1 `api-router-hono`
+- [x] 4.2 `api-auth-jwt`
+- [x] 4.3 `api-auth-anonymous`
+- [x] 4.4 `api-auth-bearer-static`
+- [x] 4.5 `api-tenant-resolver-jwt`
+- [x] 4.6 `api-secrets-env`
+- [x] 4.7 `api-db-adapter`
+- [x] 4.8 `api-tenant-provider-memory`
+
+### Stage 5 — Testing kit + conformance suites
+
+- [x] 5.1 `api-router-in-memory`
+- [x] 5.2 `api-auth-static-principal`
+- [x] 5.3 `api-db-sqlite-memory`
+- [x] 5.4 `api-events-in-memory`
+- [x] 5.5 `api-ws-broker-in-memory`
+- [x] 5.6 `api-host` testing-kit subpath (`./testing` export populated)
+- [x] 5.7 Conformance suites authored on every abstract package (`./testing` subpaths) — `runXxxConformance` shipped from api-manifest, api-router (+ api-host's `runPipelineRouterConformance`), api-graphql, api-ws, api-sse, api-auth, api-auth-provider, api-secrets, api-tenant-provider, api-loader, api-lifecycle, api-worker-rpc. api-types is types-only, no runtime conformance.
+
+### Stage 6 — Distributed transactions + Better-Auth
+
+- [x] 6.1 `api-saga`
+- [x] 6.2 `api-2pc`
+- [x] 6.3 `api-auth-better-auth`
+
+### Stage 7 — GraphQL + WebSocket / SSE
+
+- [x] 7.1 `api-graphql-yoga`
+- [x] 7.2 `api-graphql-apollo`
+- [x] 7.3 `api-graphql-ui-graphiql`
+- [x] 7.4 `api-graphql-ui-altair`
+- [x] 7.5 `api-ws-bun`
+- [x] 7.6 `api-ws-broker-redis`
+- [x] 7.7 `api-sse-bun`
+
+### Stage 8 — Sandboxing + middleware + helpers
+
+- [x] 8.1 `api-sandbox-permissions`
+- [x] 8.2 `api-sandbox-vm`
+- [x] 8.3 `api-sandbox-wasm`
+- [x] 8.4 `api-rbac`
+- [x] 8.5 `api-rate-limit`
+- [x] 8.6 `api-openapi`
+- [x] 8.7 `api-openapi-ui-scalar`
+- [x] 8.8 `api-openapi-ui-swagger`
+- [x] 8.9 `api-openapi-ui-redoc`
+- [x] 8.10 `api-audit-stdout`
+- [x] 8.11 `api-audit-file`
+- [x] 8.12 `api-auth-rolled` (session-resolver half; provider half deferred to `api-auth-rolled-provider`)
+- [x] 8.13 `api-secrets-bun`
+- [x] 8.14 `api-secrets-vault`
+- [x] 8.15 `api-tenant-resolver-header`
+- [x] 8.16 `api-tenant-resolver-subdomain`
+- [x] 8.17 `api-plugin-example`
+- [x] 8.18 `create-suaveplan-plugin`
+
+## 2. Stage acceptance gates
+
+Per `openspec/AGENTS.md §17`, every stage closes ONLY when its **integration smoke** is green — a real-composition test booting every shipped package in the stage and exercising the cross-package seams. Per-package conformance passing is necessary but not sufficient.
+
+- [x] 2.1 Stage 1 ✓ — every Stage-1 child change archived; `bun openspec validate` passes for every spec delta
+- [x] 2.2 Stage 2 ✓ — `api-host` archived; `bun examples/api-host-empty.ts` returns 200 on `/internal/livez`
+- [x] 2.3 Stage 3 ✓ — `api-worker-rpc` conformance suite passes against trivial proxy under both direct and worker surfaces
+- [x] 2.4 Stage 4 ✓ — every Stage-4 adapter passes its conformance suite under both surfaces **AND** `e2e/foundation-stack/` smoke (`bunx playwright test`) is green with NO hand-wired shims (router-pipeline, tenant-chain, secrets-injection, ledger-db). Coherence-fix changes `foundation-fix-gap-{1,2,3,4,5}` are the closure artifacts.
+- [x] 2.5 Stage 5 ✓ — `createTestHost` boots `api-plugin-example` skeleton with 100% conformance pass **AND** `e2e/foundation-stack-test-host/` smoke proves `createTestHost(config)` returns a host that drives every Stage-1..4 conformance surface without external services. (8/8 smoke groups green; foundation packages all pass §15 + §16 lint.)
+- [x] 2.6 Stage 6 ✓ — multi-step saga runs end-to-end (incl. compensation); `api-2pc` commits + aborts against real Postgres **AND** `e2e/foundation-stack-saga/` runs a 3-step compensable workflow end-to-end across two plugins. (7/7 specs green: 3 saga + 4 2PC against Postgres 16 testcontainer with `max_prepared_transactions=8`.)
+- [x] 2.7 Stage 7 ✓ — `api-plugin-example` federates GraphQL across two plugins; tenant-scoped WebSocket broadcast works **AND** `e2e/foundation-stack-engines/` smoke proves Yoga/Apollo + Bun WS + SSE coexist on one host. (5/5 specs green: 2 GraphQL federation across plugin-a+plugin-b through both Yoga and Apollo engines; 1 tenant-scoped WS broadcast with cross-tenant isolation; 1 SSE stream + publish; 1 four-engines-on-one-host route-collision check.)
+- [ ] 2.8 Stage 8 ✓ — `api-plugin-example` deploys under every isolation tier (incl. sandboxed WASM); `create-suaveplan-plugin <name>` scaffold tests pass first time **AND** `e2e/foundation-stack-full/` smoke boots every Stage 1-8 package together and exercises the full §6 11-step pipeline end-to-end.
+
+### Smoke-fail = stage incomplete
+
+If a smoke needs hand-wired shims to boot (today's E2E pre-Wave-1 caught 5 such gaps in Stage 4), the stage is NOT complete. Open coherence-fix changes against the gap-bearing packages — do NOT paper over with shims in the smoke. The smoke must consume canonical adapter surfaces a real downstream consumer would. See `openspec/archive/2026-05-26-foundation-fix-gap-{1,2,3,4,5}` for the precedent.
+
+## 3. Foundation acceptance
+
+- [ ] 3.1 Reference plugin's full integration test (design doc §13.5) green in CI
+- [ ] 3.2 Better-Auth adapter passes end-to-end OAuth flow with at least one provider (GitHub)
+- [ ] 3.3 Hot-reload cycle exercised: blue-green swap with in-flight completion + new-slot health probe + traffic flip
+- [ ] 3.4 Bad-module path: failed `start` triggers auto-rollback; plugin enters `rolled_back`; prior version keeps serving
+- [ ] 3.5 Admin API exercised end-to-end: install/uninstall/disable/enable/reload/rollback/force-uninstall with audit log entries
+- [ ] 3.6 Conformance suites pass for every adapter under both direct and worker-proxy surfaces
+
+## 4. Archive
+
+- [ ] 4.1 Refresh `MANIFEST.md` to include every foundation package
+- [ ] 4.2 Update `CLAUDE.md` `packages/api/` section with the foundation listing
+- [ ] 4.3 Move `openspec/changes/api-plugin-foundation/` → `openspec/archive/<yyyy-mm-dd>-api-plugin-foundation/` only after every child change is archived