suaveplan/openspec/archive/2026-05-25-api-host/tasks.md

Tasks — @suaveplan/api-host

Every checkbox MUST reflect work actually done in this change.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work
• 0.2 Worktrees under .claude/worktrees/ accounted for (agent-A/B/C all merged; agent-D = this change)
• 0.3 MANIFEST.md matches package count

1. Spec authoring

• 1.1 Read design doc docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md (§2.2, §4, §5, §6, §8, §12)
• 1.2 Read umbrella openspec/changes/api-plugin-foundation/proposal.md
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Draft specs/api-host/spec.md from openspec/templates/spec-delta.md
• 1.6 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Scaffold packages/api-stack/api/api-host/ (Chunk A)
• 2.2 src/define-plugin/ — definePlugin<Caps>(spec) (Chunk A)
• 2.3 src/capability-registry/ (Chunk A)
• 2.4 src/lifecycle/ — LifecycleDriver (Chunk B)
• 2.5 src/hot-reload/ — ReloadDriver (Chunk B)
• 2.6 src/hot-reload/rollback-journal via @suaveplan/api-loader (Chunk B)
• 2.7 src/plugin-ledger/ — PluginLedger + HostMigrationRunner (Chunk C)
• 2.8 src/admin-api/ — Hono sub-router; every §8.4 endpoint (Chunk C)
• 2.9 src/error-boundary/ — wraps every pipeline step; SuaveplanError → statusMap; AbortError → 499; default → 500 + log cause; envelope per api-types/errors (Chunk D)
• 2.10 src/request-pipeline/ — steps 1–11 from §6 in order; CSRF on cookie auth (non-GET/HEAD); streaming bypass; response-validation enforce/warn (Chunk D)
• 2.11 src/otel/ — HostInstruments (Chunk A); request-pipeline emits §12.3 metrics (Chunk D)
• 2.12 src/host/ — createHost(config); start() / stop() / fetch(); /internal/livez + /internal/readyz (Chunk D)
• 2.13 src/error-codes/ — every HOST_* / PLUGIN_* / RELOAD_* / CAPABILITY_* / ADMIN_* / LEDGER_* code, plus Chunk D additions (TENANT_NOT_RESOLVED, SESSION_REQUIRED, CSRF_TOKEN_INVALID, RBAC_DENIED, RATE_LIMIT_EXCEEDED, REQUEST_VALIDATION_FAILED, RESPONSE_VALIDATION_FAILED, IDEMPOTENCY_REPLAY, ROUTE_NOT_FOUND, HANDLER_THREW, CLIENT_ABORTED)
• 2.14 src/testing/ — RESERVED placeholder (Chunk A)
• 2.15 src/index.ts — explicit named re-exports per rule 10
• 2.16 package.json exports — every subpath including ./error-boundary, ./request-pipeline, ./host

3. Tests

• 3.1 lifecycle (Chunk B)
• 3.2 lifecycle-coverage (Chunk B)
• 3.3 hot-reload (Chunk B)
• 3.4 hot-reload-coverage (Chunk B)
• 3.5 file-watcher (Chunk B)
• 3.6 capability-registry (Chunk A)
• 3.7 plugin-ledger (Chunk C)
• 3.8 admin-api (Chunk C)
• 3.9 admin-api disabled — covered in src/host/host.test.ts::"adminPrefix: null disables admin surface"
• 3.10 src/error-boundary/error-boundary.test.ts — 18 tests covering manifest statusMap, default fallback, AbortError, ABORT_ERR variant, unknown throw, span recording, log cause chain, depth truncation (Chunk D)
• 3.11 src/request-pipeline/request-pipeline.test.ts — 36 tests covering every §6 step in order, CSRF gating cookie auth, streaming bypass, idempotency replay, request/response Zod, handler throw, audit (Chunk D)
• 3.12 response-validation enforce/warn covered in request-pipeline.test.ts::"response Zod mismatch in enforce mode → 500" and "response Zod mismatch in warn mode → success"
• 3.13 otel (Chunk A) — every §12.3 counter exercised through the request-pipeline tests
• 3.14 define-plugin generics (Chunk A)
• 3.15 src/host/host.test.ts — empty host boots; /internal/livez → 200; /internal/readyz → 200 (Chunk D)
• 3.16 Every it(...) carries { timeout: 5000 }

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 4.2 README.md updates in Chunks A/B/C; Chunk D adds error-boundary, request-pipeline, host modules
• 4.3 CLAUDE.md package listing updated when shipped

5. Pre-archive verification (the 5-gate triple)

• 5.1 bunx biome check src/ — clean
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-host — green (245 pass / 0 fail / 583 expect)
• 5.3 bun test --coverage — 100% line coverage on every Chunk D module + every other src/ module
• 5.4 bunx turbo build --filter=@suaveplan/api-host — green
• 5.5 No // biome-ignore / // @ts-ignore introduced

6. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 6.1 Generics threaded — definePlugin<Caps>, RequestContext<Caps> flow into the pipeline
• 6.2 Zod boundaries — admin-API bodies (Chunk C), host config + request body/params/query + response (Chunk D), ledger row shape (Chunk C)
• 6.3 Every error code thrown — Chunk D error codes verified via request-pipeline + host tests
• 6.4 Strict-mode behaviours both on and off — response validation enforce/warn, blueGreen/503-window
• 6.5 OTel instruments exercised on real production code paths (counter + histogram emit on every pipeline success/failure)
• 6.6 FSM dedup mutex tested (Chunk B)
• 6.7 No retroactive tick — every box above reflects work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/api-host/spec.md
• 7.2 Move openspec/changes/api-host/ → openspec/archive/2026-05-25-api-host/
• 7.3 Tick Stage-2 row in umbrella openspec/changes/api-plugin-foundation/
• 7.4 Refresh STATUS.md