# LLM-Friendly Migration System - Automatic Snapshot Protection

## Problem Statement
LLMs struggle with partial migration failures because:
- MySQL DDL operations auto-commit and cannot be rolled back
- Partial migrations leave the database in an inconsistent state
- LLMs get confused about what has/hasn't been applied
- Recovery requires manual intervention or database reset

## Implemented Solution: Automatic Docker Snapshot System

### Core Design
The `php artisan migrate` command automatically handles database snapshots in development mode. No separate commands needed.

### How It Works

1. **Development Mode** (`RSX_MODE=development`)
   - Automatically creates MySQL snapshot before migrations
   - Runs all pending migrations with validation
   - On success: commits changes, regenerates constants, recompiles bundles
   - On failure: automatically rolls back to snapshot

2. **Debug/Production Mode** (`RSX_MODE=debug` or `production`)
   - No snapshot protection (source code is read-only)
   - Migrations run directly
   - Schema normalization still runs
   - Constants and bundles NOT regenerated

### Migration Flow

```bash
# Development - just one command does everything
$ php artisan migrate
 Development mode: Using automatic snapshot protection

[1/4] Creating database snapshot...
[OK] Snapshot created successfully.

[2/4] Running migrations...
[OK] All 3 migrations completed successfully

[3/4] Running schema quality check...
[OK] Schema quality check passed.

[4/4] Committing changes...
[OK] Snapshot committed - backup removed.

Running post-migration tasks...
[OK] Migration completed successfully!
```

### Automatic Recovery on Failure

```bash
$ php artisan migrate
 Development mode: Using automatic snapshot protection

[1/4] Creating database snapshot...
[OK] Snapshot created successfully.

[2/4] Running migrations...

[ERROR] Migration failed!
 Automatically rolling back to snapshot...

[OK] Database restored to pre-migration state.

Fix your migration files and run "php artisan migrate" again.
```

### Implementation Details

The unified `migrate` command in development mode:
1. Stops MySQL via supervisord
2. Creates backup of `/var/lib/mysql` to `/var/lib/mysql_backup`
3. Restarts MySQL and runs migrations
4. On success: removes backup, regenerates constants, recompiles bundles
5. On failure: restores backup, removes flag file

### Environment Detection

The system automatically detects the environment:

1. **Development Mode** (snapshots enabled):
   - `RSX_MODE=development` in `.env`
   - Docker environment detected (`/.dockerenv` exists)

2. **Debug/Production Mode** (no snapshots):
   - `RSX_MODE=debug` or `RSX_MODE=production`
   - OR not running in Docker

### Benefits for LLMs

1. **Zero-Step Recovery**
   - Failed migrations automatically restore database
   - No commands to remember
   - Just fix migration files and run `migrate` again

2. **Safe Experimentation**
   - LLMs can try migrations without fear
   - Complete rollback always available
   - Learn from failures without consequences

3. **Simple Mental Model**
   - One command: `php artisan migrate`
   - System handles all the complexity
   - Clear success/failure messaging

4. **Production Safety**
   - System automatically adapts to environment
   - Source code treated as read-only in debug/production
   - Clear separation of dev/prod behaviors

### Limitations

1. **Docker Only**: Snapshots require Docker environment with supervisord
2. **Development Only**: Not available in debug/production modes
3. **Disk Space**: Requires space for MySQL data directory copy

### Implementation Files

- `/app/RSpade/Commands/Migrate/Maint_Migrate.php` - Unified migrate command
- `/app/Http/Middleware/CheckMigrationMode.php` - Web UI protection during migration

## Why This Approach

This implementation was chosen because:

1. **Complete Safety**: Filesystem snapshots guarantee perfect rollback
2. **Zero Friction**: Single command handles everything
3. **LLM-Friendly**: No multi-step workflow to remember
4. **Production Compatible**: Gracefully adapts to environment
5. **Laravel Integration**: Works with existing migration system