Backup, Restore, and Retention

WOML's state database contains the event history and immutable definitions needed to understand and recover durable runs. Treat it as production data. Backups protect that authority; retention controls how much completed history it keeps.

Create a coherent online backup

woml backup ./backups/2026-08-22

The command creates a coherent SQLite snapshot while the runtime may still be active, then writes a versioned manifest and checksums. The destination is a backup directory, not merely a copied database filename.

The WOML backup covers the selected runtime state boundary. It does not automatically copy:

• application databases accessed through services.db();
• remote systems called over HTTP;
• arbitrary files written by user scripts;
• WOML object storage kept outside the state database.

Back up those systems with their native tools. If you use services.storage, include its object directory in the same recovery plan.

Restore offline

woml restore ./backups/2026-08-22 --replace

Restore verifies checksums, refuses a live target, and retains the replaced database as a reported rollback copy.

Stop the runtime first. Restore is intentionally offline so an active process cannot append events while the authority is being replaced. The --replace flag is required when the target already exists; WOML retains the old database as a reported rollback copy instead of silently deleting it.

A sensible recovery drill is:

1. Restore into a temporary state path.
2. Run read-only inspection against the restored data.
3. Confirm expected workflows and recent runs.
4. Stop the production runtime.
5. Restore the reviewed backup into the production path.
6. Start the deployment and watch recovery diagnostics.

Prune old terminal runs

woml prune --before 90d --dry-run
woml prune --before 90d --compact

Pruning protects active/recoverable runs, referenced definitions, and durable user state. Start with dry-run. Compact reclaims SQLite space afterward.

--before 90d means terminal run history older than 90 days is eligible. WOML does not treat every old row as disposable: active or recoverable runs, immutable definitions still referenced by protected history, and services.state data remain protected.

Deletion does not necessarily shrink a SQLite file. Add --compact after a reviewed prune when reclaiming disk space matters. Compaction can be more I/O intensive, so schedule it deliberately.

Automate retention carefully

Production runtime configuration can apply separate retention periods for succeeded, failed, and cancelled runs. Failed history is often useful longer than successful history. Before enabling automatic retention, decide what your incident, legal, and audit needs actually require.

Use --state consistently and test backups by restoring them. An untested backup is only a hopeful file.