# 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.