Initial Commit

packages/persistence/database/migration/src/status/migration-status/migration-status.md

@@ -0,0 +1,56 @@
+# migration-status
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`MigrationStatusDashboard` provides a read-only view over the migration store. It computes per-migration status, aggregate counts, and a health check that can be wired into application readiness probes. Separating status reporting from the runner ensures that status queries never trigger migrations and can be called at any time without locking concerns.
+
+## Features
+
+- `getAll()` — returns every registered migration with its current status (`pending`, `applied`, `rolled-back`).
+- `getSummary()` — returns aggregate counts for total, applied, pending, and failed migrations.
+- `healthCheck()` — returns `{ healthy, pendingCount, failedCount }` suitable for a `/healthz` endpoint.
+- `getHistory(id)` — returns all ledger entries for a specific migration id (supports audit queries).
+
+## Usage: Basic Example
+
+```ts
+import { MigrationStatusDashboard, MemoryMigrationStore } from "@suaveplan/migration";
+
+const dashboard = new MigrationStatusDashboard({ store, migrations });
+const summary = await dashboard.getSummary();
+// { total: 5, applied: 4, pending: 1, failed: 0 }
+```
+
+## Usage: Advanced Example
+
+```ts
+import { MigrationStatusDashboard } from "@suaveplan/migration";
+
+const dashboard = new MigrationStatusDashboard({ store, migrations });
+const health = await dashboard.healthCheck();
+if (!health.healthy) {
+  console.warn(`${health.pendingCount} pending migrations, ${health.failedCount} failed`);
+}
+```
+
+## API Reference
+
+### `class MigrationStatusDashboard`
+
+**Constructor**: `(config: StatusConfig)`
+
+- `config.store` — `MigrationStoreAdapter`.
+- `config.migrations` — registered `Migration[]`.
+- `config.clock?` — injectable clock.
+
+- `getAll(): Promise<ExtendedMigrationStatus[]>` — sorted by id.
+- `getSummary(): Promise<MigrationSummary>` — `{ total, applied, pending, failed }`.
+- `healthCheck(): Promise<MigrationHealthCheck>` — `{ healthy, pendingCount, failedCount }`.
+- `getHistory(id: string): Promise<MigrationHistoryEntry[]>` — ledger entries for one migration.
+
+## Implementation Notes
+
+`healthy` is `true` only when both `pending === 0` and `failed === 0`. This is intentionally strict: unnapplied migrations in production are a deployment concern that should always be visible. The `getHistory` method supports audit use cases where the same migration may have been applied and rolled back multiple times.