first commit

docs/persistence/database/migration/src/planner/migration-planner/migration-planner.md

@@ -0,0 +1,56 @@
+# migration-planner
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The migration planner produces `MigrationPlan` objects that describe which migrations should be applied or rolled back, without executing them. Separating planning from execution makes dry-run reporting straightforward, enables validation before any database writes, and simplifies unit testing by removing I/O dependencies from the planning step.
+
+## Features
+
+- `sortMigrations(migrations)` — lexicographic sort by `id`, putting numeric prefixes in ascending order.
+- `planUp(all, applied)` — returns all pending (not-yet-applied) migrations sorted ascending.
+- `planDown(all, applied, steps?)` — returns the last N applied migrations in reverse (rollback) order.
+- `checksumForMigration(migration)` — returns the stored checksum or computes one from the up function body.
+
+## Usage: Basic Example
+
+```ts
+import { planUp, sortMigrations } from "@suaveplan/migration";
+
+const plan = planUp(allMigrations, []);
+// plan.toApply contains all migrations in ascending id order
+```
+
+## Usage: Advanced Example
+
+```ts
+import { planDown } from "@suaveplan/migration";
+
+// Rollback only the last 2 applied migrations
+const plan = planDown(allMigrations, appliedRecords, 2);
+// plan.toRollback[0] is the most recently applied migration
+```
+
+## API Reference
+
+### `sortMigrations(migrations: Migration[]): Migration[]`
+
+Returns a new array sorted by `id` ascending. Does not mutate the input.
+
+### `planUp(all: Migration[], applied: MigrationRecord[]): MigrationPlan`
+
+Returns `{ toApply: Migration[], toRollback: [] }`. `toApply` contains migrations whose `id` is not in `applied`.
+
+### `planDown(all: Migration[], applied: MigrationRecord[], steps?: number): MigrationPlan`
+
+Returns `{ toApply: [], toRollback: Migration[] }`. `toRollback` is at most `steps` migrations (all if omitted), most-recent first.
+
+### `checksumForMigration(migration: Migration): string`
+
+Returns `migration.checksum` if set, otherwise computes SHA-256 of `migration.up.toString()`.
+
+## Implementation Notes
+
+`planDown` reverses the sorted applied list before slicing, ensuring rollbacks proceed in most-recent-first order (LIFO). `sortMigrations` uses `localeCompare` for reliable multi-character prefix handling.