suaveplan/openspec/archive/2026-05-18-add-api-plugin-database/tasks.md

Tasks — Add @suaveplan/api-plugin-database

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/api-plugin-database.md
• 1.2 Read openspec/AGENTS.md §§ 0a, 2a, 6a, 7, 12, 13, 14
• 1.3 Draft proposal.md with ## Source mapping (in-scope) AND ### Excluded from this migration
• 1.4 Draft specs/api-plugin-database/spec.md with ## ADDED Requirements + **Verified by:**

2. Implementation

• 2.1 src/error-codes/error-codes.ts — DATABASE_CODES via defineCodes, DatabaseError extending SuaveplanError
• 2.2 src/types/types.ts — internal types (pool entry, waiter, plugin config)
• 2.3 src/config/config-schema.ts — Zod boundary (DatabasePluginOptionsSchema, DatabasePluginConfigSchema)
• 2.4 src/otel/instruments.ts — counters + histogram bundle
• 2.5 src/retry/retry.ts — exponential backoff with optional jitter + abort
• 2.6 src/pool/pool.ts — bounded pool of SurrealAdapter instances
• 2.7 src/migrations/lock.ts — advisory lock with lease expiry + takeover
• 2.8 src/migrations/runner.ts — wraps @suaveplan/api-migrations runner under the advisory lock
• 2.9 src/tenancy/tenancy.ts — provisionTenant / decommissionTenant callables, all 3 strategies
• 2.10 src/routes/problem-json.ts — RFC 7807 renderer
• 2.11 src/services/registry-augmentation.ts — ServiceRegistry.db slot
• 2.12 src/plugin/plugin.ts — createDatabasePlugin factory
• 2.13 src/index.ts — explicit named re-exports + side-effect imports

3. Tests

• 3.1 Unit tests for each module (*.test.ts)
• 3.2 src/api-plugin-database.spec-conformance.test.ts — every error code thrown from a production path
• 3.3 Real SurrealDB testcontainer integration test under tests/integration/
• 3.4 OTel emission asserted against real in-memory MeterProvider

4. Documentation

• 4.1 Sibling .md for every .ts implementation file (≥200 words, basic + advanced)
• 4.2 README.md with ## Modules linking every co-located .md

5. Pre-archive verification (the 5 gates)

• 5.1 bun run check — Biome 0 errors
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-database green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/api-plugin-database — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-database — 0 errors
• 5.5 bunx turbo build --filter=@suaveplan/api-plugin-database green

6. Archive

• 6.1 Fold specs/api-plugin-database/spec.md into openspec/specs/api-plugin-database/spec.md
• 6.2 Move openspec/changes/add-api-plugin-database/ to openspec/archive/2026-05-18-add-api-plugin-database/