migrate

type CLIOptions struct {
	DryRun          bool
	ID              string // run only this migration, skip others
	List            bool   // list registered migrations and exit
	ResetCheckpoint bool   // delete the replay checkpoint before running
	AuditLogPath    string
	CheckpointPath  string
	BackupDir       string
}

type Env struct {
	// AuditLogPath is the path to the live audit.jsonl file.
	AuditLogPath string

	// CheckpointPath is the path to the .replay-checkpoint file.
	CheckpointPath string

	// BackupDir is the directory under which rollback artifacts
	// (e.g. audit.jsonl.v040-backup) are written. Empty => same dir as
	// AuditLogPath.
	BackupDir string

	// Logger is where migrations emit progress. nil => stdlib log package.
	Logger *log.Logger

	// Stdout is where CLI output is written. nil => os.Stdout. Primarily
	// used by RunCLI; migrations themselves should log via Logger.
	Stdout io.Writer
}

type Migration interface {
	// ID is a stable identifier used in logs, metrics, and the CLI flag.
	// Convention: "vNNN_to_vMMM", e.g. "v040_to_v041".
	ID() string

	// FromVersion is the schema version this migration accepts as input.
	// Detect() must fail if observed input is anything else.
	FromVersion() string

	// ToVersion is the schema version this migration produces.
	ToVersion() string

	// Description is a one-line human-readable summary for CLI help and log
	// output. No trailing period, no newlines.
	Description() string

	// Detect reports whether the migration should run against the current
	// on-disk state. Returns (true, nil) if Migrate() should execute,
	// (false, nil) if state is already at ToVersion (or otherwise not this
	// migration's concern), and (_, err) on read/parse failure. Read-only —
	// must not modify disk.
	Detect(ctx context.Context, env Env) (bool, error)

	// Migrate performs the transition. When dryRun is true it must log the
	// intended actions without touching disk. On error the on-disk state
	// must be left unchanged — implementations typically stage output in a
	// temp file and atomically rename on success.
	Migrate(ctx context.Context, env Env, dryRun bool) (Result, error)

	// Verify checks post-migration invariants. Called after a successful
	// Migrate() and again on startup when resuming after a crash, to ensure
	// previous output is still intact. Must be idempotent.
	Verify(ctx context.Context, env Env) error
}

type Result struct {
	MigrationID string
	From        string
	To          string
	DryRun      bool
	Stats       map[string]int64
	Notes       []string
}