feat: portable drive identity (RFC 0005)

[rmanibus]

Summary

Implement portable drive identity foundations from RFC 0005 across local source handling and policy/grouping paths.

What Changes

• Local source identity detection improvements (UUID/label/mount context).
• Engine and policy updates to use stable source identity fields.
• E2E and source tests for portability behavior.
• RFC updates to align proposal and implementation.

Tracking

• Story / epic: RFC 0005: Epic / Tracking issue for portable drive identity #103
• RFC: rfcs/0005-portable-drive-identity.md
• Milestone: RFC 0005: Portable drive identity

[codecov]

Codecov Report

❌ Patch coverage is 78.19549% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/source/local_source_linux.go	68.83%	12 Missing and 12 partials ⚠️
cmd/cloudstic/format.go	25.00%	1 Missing and 2 partials ⚠️
cmd/cloudstic/cmd_backup.go	75.00%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Implements the foundation of RFC 0005 “portable drive identity” by adding stable volume identity fields to local sources, updating snapshot matching/grouping to prefer those identities, and exposing an override flag in the CLI so portable-drive incremental backups can work across machines/mount points.

Changes:

• Add VolumeUUID/VolumeLabel to core.SourceInfo, populate them from local sources, and make SourceInfo.Path volume-relative when UUID is present.
• Update backup lineage selection (findPreviousSnapshot) and retention grouping (makeGroupKey) to use VolumeUUID (+ path) when available.
• Add CLI/docs/tests/e2e coverage for the new portability behavior, including a -volume-uuid / CLOUDSTIC_VOLUME_UUID override.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
rfcs/0005-portable-drive-identity.md	Updates RFC to reflect the implemented UUID/label/mount-point behavior and matching rules.
internal/core/models.go	Extends SourceInfo with VolumeUUID and VolumeLabel.
pkg/source/local_source.go	Populates volume fields in Info() and normalizes local file IDs/paths to forward slashes.
pkg/source/local_source_darwin.go	macOS volume identity detection (partition UUID via diskutil + fallbacks).
pkg/source/local_source_linux.go	Linux volume identity detection (by-partuuid/by-uuid/by-label + mount resolution).
pkg/source/local_source_windows.go	Windows volume identity detection via GetVolumePathName + DeviceIoControl.
pkg/source/local_source_stub.go	Stub identity detection for unsupported platforms.
internal/engine/backup.go	Prefers VolumeUUID + Path matching for cross-machine incremental backups.
internal/engine/policy.go	Groups retention keys using VolumeUUID (and path) when present.
cmd/cloudstic/cmd_backup.go	Adds -volume-uuid flag + env default; wires it into local source initialization.
cmd/cloudstic/format.go	Displays VolumeLabel in the snapshot table “Account” column when present.
docs/user-guide.md	Documents portable drive behavior, the override flag/env var, and platform support.
pkg/source/local_source_test.go	Adjusts local source tests for volume-relative Path when UUID exists.
pkg/source/local_source_volume_test.go	Adds tests for UUID detection, casing normalization, override behavior, and slash normalization.
pkg/source/local_source_plist_test.go	Adds unit tests for macOS plist parsing helpers.
internal/engine/backup_test.go	Adds tests for UUID-preferred snapshot selection and subdir isolation.
internal/engine/policy_test.go	Adds tests for retention grouping by UUID+path and legacy mixing.
e2e/e2e_test.go	Extends e2e matrix to include portable-drive sources when available.
e2e/portable_test.go	Adds portable-drive source factory selection.
e2e/portable_linux.go	Linux e2e portable drive source using a GPT loopback device.
e2e/portable_darwin.go	macOS e2e portable drive source using a GPT RAM disk.
e2e/portable_stub.go	Stub e2e portable drive source for non-darwin/non-linux platforms.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.