# ADR-0006: Undo snapshots and replay log

## Status

Accepted

## Context

Two related features address the same underlying need — making the
application safe and reproducible for learners:

1. **Accidental destruction.** A student typing `DROP TABLE
   Customers` and then realising what they did is a near-certain
   event in this audience. Without a recovery path, the experience
   is hostile and the learning moment is lost to panic.
2. **Replay and scripting.** A persistent record of every
   executed command is useful for tutorials, debugging, sharing
   reproducible problem reports, and rebuilding a project from a
   blank slate.

Both features are cheap to implement and high-leverage.

## Decision

### Undo snapshots

Before any destructive operation — `DROP`, `DELETE`, `TRUNCATE`,
schema-rebuild migrations, restore, etc. — the application takes a
snapshot of the database using SQLite's online backup API into a
ring buffer of recent snapshots (size to be tuned; initial target
N = 10).

An `undo` command (available in both modes as an app-level
command per ADR-0003 — no sigil) restores the most recent
snapshot. Each undo step is itself snapshotted to keep `redo`
possible.

**Undo requires confirmation.** Snapshots are taken only before
destructive operations, so the "current" state may include
non-destructive work (inserts, updates, schema additions) done
since the last snapshot. Restoring a snapshot therefore *can*
discard data the user has not been explicitly warned about.

Before restoring, the application displays a confirmation prompt
that includes:

- The snapshot's timestamp (local time, with a relative form such
  as "12 minutes ago").
- A short summary of the operation that triggered the snapshot
  (the command text, e.g. `DROP TABLE Customers`).
- A summary of changes that will be discarded if the undo
  proceeds — at minimum, counts of rows added/modified/deleted
  per table and any schema changes since the snapshot.

The user must explicitly confirm. A keyboard shortcut for
"confirm" is provided so power users are not slowed down, but
there is no flag to suppress the prompt — undo is rare enough,
and consequential enough, that the prompt is always shown.

### Replay log (`history.log`)

Every successfully executed command — DSL or SQL — is appended to
`history.log` in the project directory, one command per record,
with a timestamp and the resulting status. The format is
deliberately simple and human-readable so it can be hand-edited
and replayed.

The same format serves three purposes:

- A persistent input history surfaced via the TUI history feature.
- A scripting format: `.commands` files (or `history.log` itself)
  can be replayed via a `replay` command.
- A reproducible bug-report artifact when a project is shared.

The log is append-only during a session. It is **not** the
authoritative state of the project (that lives in `project.yaml`
+ `data/`, ADR-0004) — it is an audit and replay trail.

## Consequences

- Snapshots add modest overhead per destructive operation. The
  cost is bounded; learners care about safety far more than
  microseconds.
- The ring buffer size must be tuned later based on realistic
  database sizes; an initial value is fine for now.
- The replay log enables a future `replay` / scripting feature
  with no additional storage commitment.
- Tutorial authors gain a natural "starter script" format for
  exercises.