bible/rules/patterns/backup-management/contract.md

Contract: Backup Management

Version: 1.1

Purpose

Общие правила для создания, хранения, именования, ротации и восстановления бэкапов вне зависимости от того, что именно сохраняется: SQLite, централизованная БД, конфиг, файлы пользователя или смешанный bundle.

Backup Capability Must Be Shipped

Backup/restore must be built into the application runtime or into binaries/scripts shipped as part of the application itself. Do not assume the operator already has suitable software installed on their machine.

Rules:

• AI must not rely on random machine-local applications (DB GUI clients, IDE plugins, desktop backup tools, ad-hoc admin utilities) being present on the user's machine.
• Backup helpers must not depend on locally installed database clients such as mysql, mysqldump, psql, pg_dump, sqlite3, or similar tools being present on the user's machine.
• If the application persists non-ephemeral state and does not already have backup functionality, implement it.
• Preferred delivery is one of: built-in UI action, CLI subcommand, background scheduler, or another application-owned mechanism implemented in the project.
• The backup path must work through application mechanics: application code, bundled libraries, and application-owned configuration.
• Rollout instructions must reference only shipped or implemented backup/restore paths.

Backup Storage

Backups are operational artifacts, not source artifacts.

Rules:

• Never write backups into the git repository tree.
• Backup files must never be staged or committed to git.
• Every application must have an explicit backup root outside the repository.
• Default local-app location: store backups next to the user config, for example ~/.config/<appname>/backups/.
• Default server/centralized location: store backups in an application-owned path outside the repository, for example /appdata/<appname>/backups/ or /var/backups/<appname>/.
• Keep retention tiers in separate directories: daily/, weekly/, monthly/, yearly/.

Backup Naming and Format

Rules:

• Each snapshot must be a single archive or dump artifact when feasible.
• Backup filenames must include a timestamp and a version marker relevant to restore safety, for example schema version, migration number, app version, or backup format version.
• If multiple artifacts are backed up independently, include the artifact identity in the filename.
• Backups should be archived/compressed by default (.zip, .tar.gz, .sql.gz, .dump.zst, or equivalent) unless restore tooling requires a raw dump.
• Include all sidecar files required for a correct restore.
• Include the application config in the backup when it is required for a meaningful restore.

Retention and Rotation

Use bounded retention. Do not keep an unbounded pile of snapshots.

Default policy:

• Daily: keep 7
• Weekly: keep 4
• Monthly: keep 12
• Yearly: keep 10

Rules:

• Prevent duplicate backups within the same retention period.
• Rotation/pruning must be automatic when the application manages recurring backups.
• Pre-migration or pre-repair safety backups may be kept outside normal rotation until the change is verified.

Automated Backup Behavior

For applications that manage recurring local or operator-triggered backups:

Rules:

• On application startup, create a backup immediately if none exists yet for the current period.
• Support scheduled daily backups at a configured local time.
• Before migrations or other risky state-changing maintenance steps, trigger a fresh backup from the application-owned backup mechanism.
• If backup location, schedule, or retention is configurable, provide safe defaults and an explicit disable switch.

Restore Readiness

Rules:

• The operator must know how to restore from the backup before applying risky changes.
• Restore steps must be documented next to the backup workflow.
• A backup that has never been validated for restore is only partially trusted.