Overview

Date: 2026-05-11

Time: 15:12

Overview

This page describes the automatic backup system designed for FTL2 modules, which creates timestamped copies of files before destructive operations (modify, delete). Backups are handled by the gate (not individual modules), use a two-phase discovery-then-execute protocol, and are especially valuable in AI-assisted workflows where operations may run without human review. Modules declare backup capability via docstring metadata; the gate's BackupManager orchestrates creation, storage, listing, and restoration.

Key Concepts

• Automatic backups are a safety net for destructive module operations — enabled by default, opt-out via --no-backup
• Module independence: modules *declare* backup capability in their docstring metadata; the gate *executes* the backup logic
• Two-phase execution protocol: Phase 1 discovers which paths need backup (ftl2discoverbackups), Phase 2 executes the operation with ftl2backupscreated metadata attached
• Three metadata fields: Backup-Capable (Yes/No), Backup-Paths (which args contain target paths), Backup-Trigger (modify, delete, or both — default is modify,delete)
• Backup naming convention: {original_path}.ftl2-backup-{YYYYMMDD}-{HHMMSS}
• Two storage strategies: adjacent (default, next to original) or central (--backup-dir / config backup.central_dir)
• Fail-safe behavior: if backup creation fails, the destructive operation does NOT proceed
• Modules with unpredictable effects (e.g., shell) declare Backup-Capable: No
• Backup info propagates into module results, state files, and workflow reports

Commands and Syntax

Module docstring metadata declaration:

Backup-Capable: Yes
Backup-Paths: dest
Backup-Trigger: modify

CLI options:

ftl2 run -m file -i hosts.yml -a "path=/etc/app.conf state=absent"           # backups enabled (default)
ftl2 run -m file -i hosts.yml -a "path=/tmp/test state=absent" --no-backup    # skip backups
ftl2 run -m file -i hosts.yml -a "path=/etc/app.conf state=absent" --backup-dir /var/ftl2/backups

Backup management commands:

ftl2 backup list [path]                                      # list all or path-specific backups
ftl2 backup show <backup-path>                               # show backup contents
ftl2 backup diff <backup-path>                               # diff backup vs current
ftl2 backup restore <backup-path> [--dry-run] [--force]      # restore from backup
ftl2 backup prune --older-than 7d                            # prune by age
ftl2 backup prune --keep 3                                   # prune keeping N most recent

Configuration (ftl2.yml):

backup:
  enabled: true
  location: adjacent  # or "central"
  central_dir: /var/ftl2/backups
  retention_days: 7
  max_backups_per_file: 5

Python module implementation pattern:

def main(args: dict) -> dict:
    if args.get("_ftl2_discover_backups"):
        return {"backup_paths": discover_backups(args)}
    backups_created = args.get("_ftl2_backups_created", [])
    # ... normal module logic ...

Relationships

• Gate (ftl_gate): owns the BackupManager that orchestrates the backup flow — modules don't create backups themselves
• Module metadata / docstrings: backup capability is declared alongside existing Arguments, Returns, Idempotent fields
• Dry-run mode: integrates to show "would back up" previews without executing
• State tracking: backup records are embedded in state files for crash recovery
• Workflow tracking: workflow reports include per-step backup summaries
• Privilege escalation: backup failures due to permissions suggest sudo or alternative --backup-dir
• Policy engine: could potentially enforce backup requirements per environment (not explicitly stated but implied by the module-independence design)

Exam-Relevant Points

• Backups are enabled by default for destructive operations; use --no-backup to disable
• The gate creates backups, not the module — this is the module-independence principle
• Backup naming format: {path}.ftl2-backup-{YYYYMMDD}-{HHMMSS}
• Three docstring metadata fields: Backup-Capable, Backup-Paths, Backup-Trigger
• Default trigger conditions are modify,delete
• Two-phase protocol: discovery (ftl2discoverbackups: true) then execution (ftl2backupscreated)
• If backup creation fails, the operation is aborted (fail-safe)
• Two storage modes: adjacent (default) and central (configured via backup.central_dir)
• Shell module is Backup-Capable: No because its effects are unpredictable
• Backup metadata appears in module results, state files, and workflow reports
• ftl2 backup restore and ftl2 backup prune are the key management commands
• Backups preserve original file permissions
• Retention is configurable via retentiondays and maxbackupsperfile