feat(cli): add vfs pack for atomic session transfer artifacts - #5
Merged
Conversation
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>
This was referenced Jul 27, 2026
…behind ProcRegistration
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
What
Adds
vfs pack <session-id>: prepares an inactive run session'sdelta.dbas a single-file transfer artifact. Also addsvfs version --jsonfor 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:
.session.lock; live mounts or owner/joiner procs are rejected with exit code 3.VACUUM INTO, since Turso lacks in-placeVACUUM) happen only on the copy.--outputartifacts 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):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:
crates/vfs-core/src/schema/mod.rs— v0.6 migration; confirm it is additive and preserves overlay configcrates/vfs-core/src/session.rs— metadata read/write API and its invariantscrates/vfs-cli/src/cmd/session_lock.rs— shared-for-lifetime vs exclusive-for-pack lock protocolcrates/vfs-cli/src/cmd/pack.rs— staging copy, prune, publish, backup recoverydocs/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;
--outputrefuses to overwrite a concurrently created target (verified @5ac5526).Regression coverage. Schema migration tests in
vfs-corepin row preservation across v0.5 → v0.6; CLI suites cover the exit-code contract.1d99611(post-review) updatestest-migrate-consolidation.sh's stale schema-version anduser_versionexpectations 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.