suaveplan/openspec/changes/enterprise-api-plugin-database/tasks.md

Tasks: enterprise-api-plugin-database

Change ID: enterprise-api-plugin-database Package: @suaveplan/api-plugin-database Target path: api/data/api-plugin-database Prerequisite packages on Verdaccio: @suaveplan/api, @suaveplan/api-shared, @suaveplan/db, @suaveplan/error, @suaveplan/events, @suaveplan/logger, @suaveplan/types

---

0. Pre-flight (non-negotiable)

• 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)
• 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.
• 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.

1. Scaffold + types + errors + events

• Create api/data/api-plugin-database/; package.json v0.0.0, "sideEffects": ["src/events.ts"]; standard tooling.
• Types: DatabasePluginConfig (Zod), DatabaseStats, MigrationResult.
• Errors: 4-code union + metadata + registration. Test + doc.
• Events: DatabaseEventMap (database:connected, database:error, database:migration:complete).

---

2. DatabaseService (.test.ts + .md)

• getDb() — returns DatabaseAdapter; throws DatabasePluginError(DB_NOT_INITIALIZED) if called before onInit.
• runMigrations(path) — reads .surql files from path ordered by filename; executes each idempotently; returns MigrationResult.
• healthCheck() — executes a lightweight query; measures latency; emits database:error on failure.
• getStats() — returns connection count, query count from adapter internals.
• OTel span on each method.

---

3. Health route

• GET /health/db — calls healthCheck(); returns 200 {status: "ok"} or 503 {status: "degraded"}.
• health.test.ts + health.md.

---

4. Plugin factory

• createDatabasePlugin(config): definePlugin with name "database", no dependencies.
• onInit: open DB connection; run migrations at config.migrationsBasePath; register DatabaseService; emit database:connected.
• onClose: close DB connection; emit database:disconnected.

---

5. Integration tests + publish

• Connect to real SurrealDB; run sample migrations; health-check returns ok; stats non-zero.
• bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-database — green; 100% coverage.
• bun scripts/publish.ts --package @suaveplan/api-plugin-database.
• Archive → openspec/archive/2026-04-24-enterprise-api-plugin-database/.