stack/docs/fleet/operations/backup-restore.md

Fleet Configuration Backup and Restore Boundary

Issue: #758 · Card: FCM-M4-001

This page defines evidence that must exist before a roster v1-to-v2 cutover. FCM-M4-001 lists these prerequisites in non-executable recovery evidence but does not validate that backups exist and performs no backup, migration, canary, or restore. FCM-M4-002 owns the executable reversible canary and rollback gates.

Preserve before cutover

• The authoritative v1 roster, byte-for-byte, with a SHA-256 identity.
• Existing per-agent legacy .env, strict .env.local, and quarantine files under private permissions.
• Reviewed per-local-agent systemd and exact-socket tmux observations.
• The canonical v2 candidate and its SHA-256 identity.
• Inventory-only remote agents and connector configuration as evidence, not local control-plane input.

.env.generated is a rebuildable projection and is not restored as authority. It must be regenerated from the selected authoritative roster. .env.local is operator-owned strict data and must not be overwritten or absorbed into generated output. Quarantined source remains private evidence; public diagnostics expose only rule code, key name, and SHA-256.

Restore requirements

A later rollback implementation must restore the authoritative roster and operator-owned environment files, regenerate managed projections, and preserve each reviewed pre-cutover stopped/running state. It must never start an agent observed stopped and must never reconcile an inventory-only remote or connector entry.

The preview evidence deliberately records:

• executable: false;
• required backup artifacts;
• source and candidate identities;
• lifecycle observations and resulting desired states;
• environment relocation/quarantine dispositions;
• FCM-M4-002 as the executable rollback gate owner.

Do not interpret a ready preview as a completed backup, migration, canary, or rollback.