Backup Engine v2 Implementation Plan

For agentic workers: implement this plan task-by-task. Use checkbox (- [ ]) tracking. Do not collapse phases into one large change. The source design is docs/superpowers/specs/2026-04-30-backup-engine-v2-design.md.

Goal

Turn the Rust/SQLite backup engine into a fast, storage-efficient, safe backup system with a beginner-friendly BACKUPS dashboard.

The finished system must support:

CAS-backed file storage.
Incremental backups.
Streaming and deterministic snapshots.
Full restore and selected-file restore.
Restore preview and restore file suggestions.
Commit-triggered automatic backups.
Automatic cleanup policy for growing backup data.
Mac and Windows edge-case safety.
0 byte file correctness.
A full-screen BACKUPS dashboard that absorbs the old Checkpoints entry point.

Non-negotiable constraints

Do not put everything into one file.
Keep vibelign-core/src/backup/checkpoint.rs as a thin compatibility/wiring layer.
Keep vibelign-gui/src/pages/BackupDashboard.tsx as a page shell only.
Do not put all GUI logic into vibelign-gui/src/lib/vib.ts.
Do not put tests into one giant integration file.
Do not expose internal terms such as SHA, hash, trigger, checkpoint, diff, preview, or ledger in user-facing Korean copy.
Preserve existing vib checkpoint, vib history, and vib undo behavior. vib undo in v2 internally calls safe full restore against the latest v2 checkpoint; legacy-only DBs fall back to the v1 restore path.
Do not rewrite the whole engine to async/Tokio in this work.
Do not import legacy JSON backups in v2 MVP.
Every new Rust/Python source file must include === ANCHOR: <NAME>_START === / === ANCHOR: <NAME>_END === boundaries so vib guard --strict keeps passing.
Engine version discriminator is checkpoints.engine_version only; do not branch restore behavior on object_hash IS NULL.
Do not introduce a Rust commit_auto_backup.rs module. Pass trigger, git_commit_sha, git_commit_message through the existing CheckpointCreate request payload.
Design every new boundary for extension: local CAS is the only v2 MVP backend, but create.rs, restore/*, retention.rs, Python bridge helpers, and GUI panels must not assume cloud sync, encryption, or remote storage can never exist.

Release split:

Engine MVP = Phases 1–7. Ship to CLI/MCP first.
Dashboard MVP = Phases 8–9. Ship after Engine MVP is stable.

Target module structure

Rust:

vibelign-core/src/backup/
├─ mod.rs
├─ cas.rs
├─ snapshot.rs
├─ checkpoint.rs
├─ create.rs
├─ restore/
│  ├─ mod.rs
│  ├─ full.rs
│  ├─ files.rs
│  └─ preview.rs
├─ diff.rs
├─ stats.rs
├─ suggestions.rs
└─ retention.rs

Rust 쪽에 commit_auto_backup.rs는 두지 않는다. trigger / git metadata는 CheckpointCreate request payload로 받아 create.rs가 그대로 row에 기록한다. post-commit 자동 백업의 트리거/dedupe/no-changes 처리는 모두 Python auto_backup.py가 담당한다.

Extension seams to preserve:

cas.rs exposes object operations; other modules must not hard-code .vibelign/rust_objects/ layout except through CAS helpers.
create.rs accepts backup metadata through request payloads, not through separate code paths for manual, post-commit, scheduled, or future remote-triggered backups.
restore/* resolves object content through CAS APIs so future remote/encrypted objects can slot in behind the same contract.
retention.rs returns cleanup plans and calls CAS/object deletion APIs; it must not directly encode backend-specific delete behavior.
ipc/protocol.rs changes are additive only. New fields may be optional; existing field names and meanings must remain stable.
GUI additions use new components/backup-dashboard/* panels instead of expanding BackupDashboard.tsx or vib.ts.

Python bridge:

vibelign/core/checkpoint_engine/
├─ rust_engine.py
├─ requests.py
├─ responses.py
└─ auto_backup.py

GUI:

vibelign-gui/src/pages/
└─ BackupDashboard.tsx

vibelign-gui/src/components/backup-dashboard/
├─ SafetySummary.tsx
├─ StorageSavings.tsx
├─ DateGraph.tsx
├─ BackupFlow.tsx
├─ RestoreSuggestions.tsx
├─ FileHistoryTable.tsx
├─ RestorePreviewPanel.tsx
└─ CleanupInsight.tsx

Phase order

Schema and compatibility foundation.
CAS storage.
Snapshot and incremental backup creation.
Restore, diff, preview, and file suggestions.
Retention and cleanup policy.
Commit-triggered automatic backup.
Python bridge and CLI/MCP integration.
GUI BACKUPS dashboard.
Cross-platform and release verification.

Each phase must be independently reviewable and revertible.

Phase 1: Schema and compatibility foundation

Purpose: Add the database columns and protocol shapes needed by v2 without breaking v1 restore paths.

Files:

Verification:

cargo test --manifest-path vibelign-core/Cargo.toml
python -m pytest tests/test_checkpoint_cmd_wrapper.py tests/test_mcp_checkpoint_handlers.py -q

Exit criteria:

Old backup rows still restore.
New columns exist with safe defaults.
Existing Python/CLI checkpoint tests pass unchanged or with additive assertions only.

Phase 2: CAS storage

Purpose: Store identical file contents once and make object lifecycle safe.

Files:

Modify: vibelign-core/src/backup/cas.rs
Modify: vibelign-core/src/backup/mod.rs
Add focused Rust tests for CAS behavior
Implement object path layout: .vibelign/rust_objects/blake3/ab/cd/<full_hash>.
Keep object path layout private to cas.rs; callers receive resolved paths or object handles, not shard paths.
Implement store_object, resolve_object, increment_ref, decrement_ref, and prune_unreferenced.
Use atomic write flow: tempfile + rename. If rename fails because the destination exists, treat as success (concurrent storer won the race) and skip fs write.
On insert race, use INSERT INTO cas_objects ... ON CONFLICT(hash) DO UPDATE SET ref_count = ref_count + 1. Never decrement below zero (add CHECK(ref_count >= 0) if SQLite version supports it, otherwise a debug assertion).
Prevent path traversal and symlink escape.
Treat 0 byte files as real files:
- Store BLAKE3 empty input hash.
- Persist size = 0 row.
- Restore as an actual empty file.
Keep size == 0, empty content, empty path, and missing file as different states.
Cross-platform smoke (one test each): Windows-style \\ relative path stored as canonical / form; macOS NFC vs NFD filename input collapses to one CAS row.

Verification:

cargo test --manifest-path vibelign-core/Cargo.toml backup::cas

Exit criteria:

Identical content stores one object.
Ref counts increment and decrement correctly.
0 byte files store and restore correctly.
Unreferenced objects prune only when ref_count == 0.

Phase 3: Snapshot and incremental backup creation

Purpose: Build deterministic file snapshots and create backups that reuse unchanged CAS objects.

Files:

Modify: vibelign-core/src/backup/snapshot.rs
Add: vibelign-core/src/backup/create.rs
Modify: vibelign-core/src/backup/checkpoint.rs as a thin delegator
Modify: vibelign-core/Cargo.toml only if a small parallelism dependency is required
Add focused Rust tests for snapshot and create planner behavior
Replace whole-file memory reads for hashing with buffered streaming hash.
Add bounded parallel hashing using rayon or a small standard-thread approach.
Sort results by normalized relative_path before DB writes and IPC output.
Exclude .git, .vibelign/vibelign.db, .vibelign/rust_checkpoints/, and .vibelign/rust_objects/.
Implement incremental planner using relative_path + hash + size.
Store changed/new files in CAS and reuse unchanged objects.
Record original_size_bytes, stored_size_bytes, reused_file_count, and changed_file_count.
Preserve no_changes behavior without making it slower.
Handle race cases where a file is deleted or changed during snapshot by returning a clear internal warning/failure state.

Verification:

cargo test --manifest-path vibelign-core/Cargo.toml backup::snapshot
cargo test --manifest-path vibelign-core/Cargo.toml backup::create

Exit criteria:

Large files are not read fully into memory.
Parallel output is deterministic.
Unchanged files reuse object hashes.
0 byte unchanged files are reused, not skipped.
Performance target on the benchmark fixture (10k files / ≈500 MB):
- Cold create: at least 30% faster than the v1 whole-file-read baseline.
- Warm create (no_changes): within ±5% of v1 baseline.
- The benchmark harness lives next to existing tests/test_bench_* fixtures; record numbers in tests/benchmark/patch_accuracy_baseline.json-style snapshot.

Phase 4: Restore, diff, preview, and file suggestions

Purpose: Let users see what will change before restore and restore selected files safely.

Files:

Verification:

cargo test --manifest-path vibelign-core/Cargo.toml backup::restore
cargo test --manifest-path vibelign-core/Cargo.toml backup::diff
cargo test --manifest-path vibelign-core/Cargo.toml backup::suggestions

Exit criteria:

Preview changes no files.
Selected-file restore changes only selected files.
Restore suggestions include plain-language reason codes for the GUI/Python layer to translate.
Legacy rows still restore.

Phase 5: Retention and cleanup policy

Purpose: Prevent backup data from growing forever while preserving important restore points.

Files:

Verification:

cargo test --manifest-path vibelign-core/Cargo.toml backup::retention

Exit criteria:

Protected backups never prune.
min_keep is respected.
Auto backups prune before manual backups when all else is equal.
Ref counts remain consistent after cleanup and partial failure tests.

Phase 6: Commit-triggered automatic backup

Purpose: Create backups automatically after commit without blocking the user’s Git workflow.

Files:

Add: vibelign/core/checkpoint_engine/auto_backup.py
Modify: vibelign/core/git_hooks.py
Modify: vibelign/cli/cli_command_groups.py
Add: vibelign/commands/internal_post_commit_cmd.py as the single combined post-commit entrypoint
Modify: vibelign/commands/internal_record_commit_cmd.py only if shared helper extraction is needed for the combined entrypoint
Add/modify: tests/test_git_hooks_post_commit.py

No Rust commit_auto_backup.rs file. Phase 1 already added trigger / git_commit_sha / git_commit_message to the CheckpointCreate request, and Phase 3’s create.rs writes them to the new columns. Python is the only orchestrator.

Verification:

python -m pytest tests/test_git_hooks.py tests/test_git_hooks_post_commit.py -q
cargo test --manifest-path vibelign-core/Cargo.toml backup::create

Exit criteria:

Commit creates a non-fatal automatic backup.
Duplicate snapshot creates no duplicate backup.
Existing hook content is preserved.

Phase 7: Python bridge, CLI, and MCP integration

Purpose: Expose the Rust engine additions through Python, CLI, and MCP without bloating existing wrappers.

Files:

Verification:

python -m pytest tests/test_checkpoint_cmd_wrapper.py tests/test_mcp_checkpoint_handlers.py tests/test_gui_cli_contracts.py -q

Exit criteria:

Python can call every new Rust command.
Existing checkpoint commands still work.
MCP and GUI contracts use stable snake_case JSON.

Phase 8: GUI `BACKUPS` dashboard

Purpose: Replace the small checkpoint-only experience with a full-screen beginner-friendly backup dashboard.

Files:

Verification:

npm run build --prefix vibelign-gui
npm run lint --prefix vibelign-gui
python -m pytest tests/test_gui_cli_contracts.py -q

Exit criteria:

BACKUPS is the single user-facing backup entry point.
No narrow home-card-only backup UX.
Dashboard numbers match engine JSON fixtures.
Internal terms are not shown in Korean UI copy.

Phase 9: Cross-platform and release verification

Purpose: Prove the backup engine works on macOS and Windows before release.

Files:

Verification:

cargo test --manifest-path vibelign-core/Cargo.toml
python -m pytest tests/test_cross_platform_paths.py tests/test_checkpoint_cmd_wrapper.py tests/test_mcp_checkpoint_handlers.py -q
npm run build --prefix vibelign-gui

Exit criteria:

macOS and Windows test suites pass.
File path, Unicode, 0 byte, locked file, symlink, and cleanup policy cases are covered.
Release notes can truthfully say the backup engine handles Mac/Windows edge cases.

Final acceptance checklist

Review feedback applied (2026-04-30)

The plan was updated in-place to address the design review. Quick map:

#	Issue	Fix location
1	No schema migration runner — re-running ALTERs would error out	Phase 1 — `apply_migrations(conn, target=2)` gated by `db_meta.schema_version`
2	Dual v1/v2 discriminator (`engine_version` vs `object_hash IS NULL`)	Non-negotiable constraints + Phase 1 — `checkpoints.engine_version` only
3	`commit_auto_backup.rs` had no real responsibility	Module structure + Phase 6 — Rust file removed; trigger metadata flows through `CheckpointCreate` payload
4	Default mismatches (`min_keep` 10 vs 20, `max_total_size_bytes` 2 GiB vs 1 GiB)	Phase 1 — v2 migration updates `retention_policy` defaults
5	Phase 1 IPC types pre-defined → forced rework	Phase 1 — only `CheckpointCreate` field additions; later phases own their own IPC
6	Existing 6 Python bridge files unmapped	Phase 7 — explicit responsibility table
7	Cleanup transaction order could drift `ref_count` on crash	Phase 5 — single SQL tx (rows + ref_count), separate fs unlink stage
8	Selected-file safety scope ambiguous	Design §6 + (already implicit in Phase 4/5) — safety checkpoint is always full project
9	v2 `storage_path` could collide with legacy NULL/empty	Phase 1 — `cas:<full_hash>` sentinel
10	Suggestions algorithm missing cap / sort / legacy fallback	Phase 4 — design §5 spec referenced
11	Cross-platform validation only at the end	Phases 2/4/6 — one platform smoke each, Phase 9 stays the comprehensive matrix
12	`auto_backup_on_commit` storage location undefined	Phase 1 + Phase 6 — `db_meta` row

Additional reinforcements:

CAS concurrency rule (ON CONFLICT DO UPDATE, idempotent rename) — Phase 2.
Quantitative perf target (10k files, +30% cold, ±5% warm) — Phase 3.
Banned-word lint for Korean UI copy — Phase 8.
Anchor convention enforced for new source files — Non-negotiable constraints.
vib undo semantics in v2 documented — Non-negotiable constraints.
Engine MVP / Dashboard MVP release split — Non-negotiable constraints.

Review feedback round 2 — VibeLign command surface & platform edges

#	Issue	Fix location
B1	`.vibelign/rust_objects/` would leak BLAKE3 blobs into git	Phase 1 — extend `_ensure_gitignore_entry`
B2	Post-commit hook `python3` fallback unreachable on Windows	Phase 6 — fallback chain `python` → `py -3` → `python3`
B3	stdin pipe shared between two `vib _internal_*` commands	Phase 6 — single combined `_internal_post_commit` entrypoint
B4	The old settings-style auto-backup command does not exist	Phase 6 — reuse `vib config auto-backup on\|off`
B5	Free-disk-space crate missing	Phase 5 — add `fs2`/`sysinfo` dependency
C1	`work_memory.json` race between record and backup	Phase 6 — single entrypoint serialises writes
C2	Silent `vib undo` semantic change	Design §6 — safety checkpoint hidden from history/undo, advisory line on first use
C3	`_clean_msg` exposes raw `auto backup after commit ...`	Phase 7 — extend `CheckpointSummary` with `trigger`, update `_clean_msg`, hide `safe_restore` rows from CLI
C4	`RetentionPolicy` dataclass default not aligned with DB default	Phase 1 — also update dataclass defaults
C5	`shadow_runner.py` blowing up disk on every commit	Phase 7 — default off, opt-in via `VIBELIGN_SHADOW_COMPARE=1`
C6	SQLite busy_timeout 5s vs concurrent backup ops	Phase 5 — raise to 15s for backup operations
M1	iCloud / SMB / NFS host of `.vibelign/vibelign.db` corrupts WAL	Phase 1 — doctor warning, no auto-disable
M2	v1 NFD vs v2 NFC `relative_path` mismatch	Phase 1 — NFC backfill in migration, abort on collision
M3	macOS case-only rename precedence undefined	Phase 9 — “last `WalkDir` stat wins” rule documented in tests
M4	macOS SMB chmod silently fails	Existing `chmod-failed` status preserved; Phase 9 verifies no regression
W1	Windows NTFS 260-char path limit	Phase 9 — `\\?\` prefix on resolved restore paths > 240 chars
W2	Windows locked files silently skipped during snapshot	Design §1 — snapshot returns `skipped[]`; Phase 9 — propagation test
W3	Non-ASCII cwd encoding	Existing `encoding="utf-8"` on `subprocess.run`; Phase 7 — apply to all new bridge calls
W4	Windows AV scan exceeds 30s subprocess timeout	Phase 6 — backup-class timeout raised to 90s
W5	`.exe.sha256` manifest distribution	Release notes only — no design change
W6	Git Bash CRLF rewrites commit message bytes	Design §7 — message is metadata-only, not a dedupe key

Backup Engine v2 Implementation Plan

Goal

Non-negotiable constraints

Target module structure

Phase order

Phase 1: Schema and compatibility foundation

Phase 2: CAS storage

Phase 3: Snapshot and incremental backup creation

Phase 4: Restore, diff, preview, and file suggestions

Phase 5: Retention and cleanup policy

Phase 6: Commit-triggered automatic backup

Phase 7: Python bridge, CLI, and MCP integration

Phase 8: GUI BACKUPS dashboard

Phase 9: Cross-platform and release verification

Final acceptance checklist

Review feedback applied (2026-04-30)

Review feedback round 2 — VibeLign command surface & platform edges

Phase 8: GUI `BACKUPS` dashboard