Module snapshot 

Pre-migration snapshots — Increment B.2 lean cut from docs/specs/SPEC_DATA_CHANNELS_2026_05_24.md §3.4.

When a launch detects an existing objects.db whose user_version is behind the binary’s OBJECT_SCHEMA_VERSION, copy the SQLite DBs into ~/.agentmux/snapshots/<channel>-pre-v<code-version>-<ISO8601>.bak/ BEFORE any migration mutates them, then prune to the newest MAX_SNAPSHOTS_PER_CHANNEL per channel.

Lean-cut scope decisions (vs. the full spec):

• SQLite files only — no copy of agents/, config/, logs/, or cef-cache/. Most state worth recovering lives in the DBs; agent workspaces are typically git-managed; logs and cache are regenerable. Cuts snapshot size by ~10× vs. a full data-dir copy.
• VACUUM INTO instead of file copy — produces an atomic, WAL-consistent single-file snapshot regardless of journal state. No need to coordinate .db-wal and .db-shm files separately.
• No restore CLI — manual restore is cp snapshot/*.db <db_dir>/. Documented in the spec for now; a CLI can come later if used.
• Snapshot failure is logged + non-fatal — the safety lock already prevents downgrade corruption, so a failed snapshot is a missing rollback aid, not a data-loss event. Refusing to boot would be worse.

Enums

SnapshotError

Constants

MAX_SNAPSHOTS_PER_CHANNEL

Maximum number of snapshots retained per channel. Older ones are pruned after each new snapshot. Spec §3.4 budgets ~2 GB per channel at this retention level; the lean SQLite-only cut runs well under that.

NAME_PRE_TOKEN 🔒

Token that separates <channel> from the version segment in snapshot dir names: <channel>-pre-v<code_version>-<ts>.bak. Used by the prune step to extract the timestamp from the filename (more robust than mtime, which can be rewritten by backup tools).

NAME_SUFFIX 🔒

SNAPSHOT_DB_NAMES 🔒

DBs included in a snapshot. Lean-cut: SQLite files only.

Functions

create_snapshot

Snapshot the SQLite DBs in db_dir to a new directory under snapshots_dir. The snapshot dir is named <channel>-pre-v<code_version>-<ISO8601>.bak. Uses VACUUM INTO for atomic, WAL-consistent copies. Returns the new snapshot dir.

maybe_snapshot_pre_migration

High-level entry: check, snapshot, prune. Returns the snapshot dir on success, or None if no snapshot was needed. Errors are surfaced to the caller; production call sites should log-and-continue rather than abort boot (see module docs).

needs_snapshot

Inspect objects.db to decide whether a pre-migration snapshot is warranted. Returns Some(found_version) if an existing DB is behind current; None for fresh installs (no file) or same-version opens. A newer-than-current DB is left alone — the safety lock in wstore.rs will refuse to open it before any migration runs.

parse_ts_from_name 🔒

Extract the timestamp segment from a snapshot dir name. Format: <channel>-pre-v<code_version>-<ISO8601>.bak. We already know the name starts with <channel>-pre-v (the caller checked); find the last - before .bak to split off the timestamp from <code_version>.

prune_snapshots

Delete oldest snapshots for channel until at most MAX_SNAPSHOTS_PER_CHANNEL remain. Returns the number pruned. Pruning errors on a specific entry are logged and skipped rather than aborting the whole sweep (one bad dir shouldn’t keep storage growing).

quote_sql_literal 🔒

snapshot_dir_name 🔒

validate_channel 🔒

Reject channel names that would break the filename layout or escape the snapshots dir. Mirrors the reserved-name set in agentmux-common’s sanitize_channel_name, but operates on the already-resolved channel string this module receives via env.