# OpenSpec Change: enterprise-api-plugin-database

- **Change ID**: enterprise-api-plugin-database
- **Package**: `@suaveplan/api-plugin-database`
- **Category**: api/data
- **Target path**: `api/data/api-plugin-database`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-database.md`

---

## Summary

Deliver `@suaveplan/api-plugin-database` on the genesis branch from scratch at enterprise quality. Foundation database plugin for the API tier: wraps `@suaveplan/surrealdb` (or any `DatabaseAdapter`-compatible backend), provides `getDb()` helper for downstream plugins, runs SurrealQL migrations at boot, exposes a `/health/db` readiness probe, and registers a `DatabaseService` with connection-pool stats. This is the dependency declared by almost every other plugin; it must land first in the dependency wave. Events: `database:connected`, `database:error`.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
| `@suaveplan/db` (`workspace:^`) | `DatabaseAdapter` interface |
| `@suaveplan/error` (`workspace:^`) | `DatabasePluginError` hierarchy |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
| `@suaveplan/events` (`workspace:^`) | Event bus |
| `@suaveplan/logger` (`workspace:^`) | Structured logging |
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
| `@opentelemetry/api` | OTel |

---

## Public API surface

```ts
function createDatabasePlugin(config: DatabasePluginConfig): PluginDescriptor<DatabasePluginConfig>

// Registered service accessible by downstream plugins:
interface DatabaseService {
  getDb(): DatabaseAdapter
  runMigrations(path: string): Promise<MigrationResult>
  healthCheck(): Promise<{ status: 'ok' | 'degraded'; latencyMs: number }>
  getStats(): DatabaseStats
}

interface DatabasePluginConfig {
  adapter: DatabaseAdapter   // injected; typically @suaveplan/surrealdb
  migrationsBasePath?: string
}
```

### Error codes

```ts
type DatabasePluginErrorCode =
  | "DB_CONNECTION_FAILED"
  | "DB_MIGRATION_FAILED"
  | "DB_HEALTH_CHECK_FAILED"
  | "DB_NOT_INITIALIZED"
```

---

## File layout

```text
api/data/api-plugin-database/
  package.json  tsconfig.json  vitest.config.ts
  src/
    index.ts  events.ts  types/  errors/
    services/database/
    routes/health/
  tests/integration.test.ts
```

---

## Impact

This is the most critical dependency: every other plugin with `dependencies: ["database"]` requires this plugin. Must be published first. Prerequisites: `@suaveplan/api`, `@suaveplan/db`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`.