Skip to content
Spec{0}

Recovery from corruption

SQLite is durable, and Spec0’s data layout is conservative. Most of the time you’ll never see a corruption issue. When you do, Spec0 has a structured response — and you have a few buttons.

What Spec0 checks on startup

Every time Spec0 launches:

  1. WAL replay — the SQLite write-ahead log is replayed automatically.
  2. PRAGMA integrity_check runs against the app DB and each project DB.
  3. Migrations run (forward-only, pure functions, idempotent).
  4. Event log replay rebuilds in-memory read models.
  5. Orphan reconciliation — Doing cards whose MCP session vanished get released back to Todo (or your configured policy).
  6. Artifact spot-check — a sample of artifact references is verified against the bytes on disk.

If every step succeeds, Spec0 fires an app.startup.recovered summary event and the UI opens normally.

The recovery modal

If PRAGMA integrity_check fails on any DB — or a migration aborts — Spec0 opens a Recovery modal before showing the board.

The modal:

  • Names the affected DB (e.g. “Project: loomwright”).
  • Shows the error from SQLite verbatim.
  • Offers three actions:
    • Restore from latest auto-backup — pulls from ~/Library/Application Support/Spec0/backups/. Default action.
    • Restore from a specific backup — file picker, points at any tarball.
    • Continue with the healthy projects — quarantines the damaged DB so you can keep using the rest.

Pick one and Spec0 acts. Nothing else is mutated until you click.

Row-level errors

A single corrupted row in the event log (rather than a whole DB failure) surfaces a smaller notification: events.row_parse_failed. The event is quarantined; the rest of the project keeps loading.

You’ll see one such row in Diagnostics → Event log inspector with a quarantined flag. If it’s a card you cared about, restore that project from a backup.

Missing artifact bytes

If a card references an artifact whose bytes are gone (manually deleted, disk-corrupt, etc.), Spec0 surfaces artifact.not_found on the relevant card. The card otherwise still loads; only that one attachment is unavailable.

When to file a crash report

If recovery succeeds but Spec0 reports an internal error during the startup sequence, Settings → Crash reports can package the redacted log slice for you to share. Crash reports are opt-in; no remote endpoint is configured by default.

What’s safe to do if all else fails

Worst case, you can:

  1. Quit Spec0.
  2. Rename ~/Library/Application Support/Spec0/ to Spec0.broken.
  3. Relaunch Spec0 — it’ll initialize a fresh data dir.
  4. Use Restore from backup to pull in the most recent good tarball.

This is the nuclear option. The Recovery modal handles every realistic case below that.