Skip to content

feat(cli): add vfs pack for atomic session transfer artifacts - #5

Merged
factory-ain3sh merged 6 commits into
mainfrom
pack-verb
Jul 28, 2026
Merged

feat(cli): add vfs pack for atomic session transfer artifacts#5
factory-ain3sh merged 6 commits into
mainfrom
pack-verb

Conversation

@factory-ain3sh

@factory-ain3sh factory-ain3sh commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

Description

What

Adds vfs pack <session-id>: prepares an inactive run session's delta.db as a single-file transfer artifact. Also adds vfs version --json for capability detection and schema v0.6 with persistent session-handoff metadata.

Why

Session handoff (AC-768) needs a transferable artifact with its own integrity story: a packed database must carry a double-resume guard (generation) and future seed provenance inside the file itself, not in session-directory sidecars that never travel.

How

Pack owns the operation end to end:

  1. Takes the exclusive .session.lock; live mounts or owner/joiner procs are rejected with exit code 3.
  2. Copies the SQLite family (main + WAL/SHM) to a private staging family; pruning, v0.6 migration, generation bump, checkpoint, and compaction (VACUUM INTO, since Turso lacks in-place VACUUM) happen only on the copy.
  3. Prunes generated-artifact globs through the core filesystem API, never via whiteouts, so a pruned base-shadowing path falls back to the base version.
  4. Publishes atomically: old family renamed to a deterministic backup, staging renamed into place, metadata verified, rollback on failure. A later pack recovers the backup if the process died between renames. --output artifacts publish via no-replace hard link.

Schema v0.6 adds fs_session_metadata(key, value) (generation, seeded_paths); the v0.5 → v0.6 migration is additive and runs in the same schema transaction.

Stack (merged bottom-up 2026-07-28, vfs main @ 3b2af42):

  1. refactor: rename agentfs to vfs across runtime, tooling, and docs #4 rename agentfs to vfs
  2. feat(cli): add vfs pack for atomic session transfer artifacts #5 vfs pack <- this PR
  3. feat(cli): add vfs seed for portable dirty-base capture #6 vfs seed
  4. feat(cli): harden resumable run sessions and add status preflight #7 run hardening + status

Related Issue

Part of AC-768

Reviewer Guide

Diff shape: ~50% cmd/pack.rs (staging + publication state machine), ~20% core (schema/mod.rs, session.rs), ~15% locking (session_lock.rs), ~15% CLI plumbing/docs.
Review depth: Deep on publication ordering; that rename dance is the crash-safety story.
Read order:

  1. crates/vfs-core/src/schema/mod.rs — v0.6 migration; confirm it is additive and preserves overlay config
  2. crates/vfs-core/src/session.rs — metadata read/write API and its invariants
  3. crates/vfs-cli/src/cmd/session_lock.rs — shared-for-lifetime vs exclusive-for-pack lock protocol
  4. crates/vfs-cli/src/cmd/pack.rs — staging copy, prune, publish, backup recovery
  5. docs/SPEC.md — the failure contract ("a failed pack MUST leave metadata and filesystem rows at pre-pack values")

Open for pushback: pack rejects live sessions outright (exit 3) instead of waiting; the daemon caller owns retry policy.

Risk & Impact

The v0.6 migration runs on every older database pack touches. It is additive (new table only), but a migration bug would be data-corrupting; the SPEC preservation clauses are the contract. Publication has two crash windows between renames; the deterministic-backup recovery path covers both. Prune misconfiguration silently drops delta paths, which is why default prunes are overridable (--no-default-prunes, --prune).

Verification

Behavior verified. Pack on a live session exits 3 with the documented message; interrupted publication recovers the backup on the next pack; --output refuses to overwrite a concurrently created target (verified @ 5ac5526).
Regression coverage. Schema migration tests in vfs-core pin row preservation across v0.5 → v0.6; CLI suites cover the exit-code contract. 1d99611 (post-review) updates test-migrate-consolidation.sh's stale schema-version and user_version expectations for v0.6, caught on the first macOS + ubuntu CI run against main.
Not tested. Concurrent pack from two processes beyond the lock-acquisition test; the exclusive flock makes the race unreachable by construction.
Standard validators. cargo build/test and CLI shell suites clean.

factory-ain3sh and others added 2 commits July 24, 2026 02:40
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Base automatically changed from rename-vfs to main July 28, 2026 01:20
factory-ain3sh and others added 2 commits July 27, 2026 18:55
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
@factory-ain3sh
factory-ain3sh merged commit ea15138 into main Jul 28, 2026
10 checks passed
@factory-ain3sh
factory-ain3sh deleted the pack-verb branch July 28, 2026 02:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant