persistence

name	persistence
description	Safely change browser-local persistence, Dexie schemas, store synchronization, backups, trash, restore, or checkpoints. Use when diagram data or IndexedDB behavior changes.

Persistence

Read First

• src/lib/db.ts for the current Dexie version and upgrade history.
• src/store/store.ts for debounced position/full saves and state initialization.
• src/lib/backup.ts for .thot export/import behavior.
• src/lib/types.ts for persisted shapes.

Change Rules

1. Treat src/lib/db.ts as an append-only schema history. Add a new version() for persisted schema/index changes; do not rewrite old migrations.
2. Add upgrade logic for old records when a new required field cannot be safely defaulted at read time.
3. Preserve existing debounce and transaction behavior. Account for the fact that an immediate IndexedDB read after a mutation can observe the previous value.
4. Check all lifecycle paths for changed fields: create, import, duplicate, trash, restore, permanent delete, checkpoint, backup export, and backup import.
5. Keep diagrams and diagramsMap synchronized in Zustand. Avoid direct partial state updates that leave the map stale.
6. If a change affects backups, update validation and date rehydration deliberately. Backups currently cover diagrams, selected diagram state, and AI chat sessions, not every local table.
7. Use Dexie transactions for multi-table replacement or clear-and-restore operations.

Verification

• Test a fresh database and representative existing records when adding a migration.
• Verify reload persistence after normal edits, position-only edits, imports, restores, and deletion.
• Check backup round trips and confirm invalid backup input does not partially replace local data.
• Run pnpm run type-check, pnpm run lint, and pnpm run build.