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

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

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

File layout

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.

2.6 KiB Raw Permalink Blame History