02 — Storage Model

From the Burrow™ specification set.

02 — Storage Model

Purpose

Separate where a file exists, what role that location serves, cloud synchronization state, and backup protection. These concepts must never be collapsed into one status.

Location Types

  • INTERNAL_VOLUME
  • EXTERNAL_VOLUME
  • ICLOUD_DRIVE
  • ONEDRIVE
  • OTHER_LOCAL
  • FUTURE_NETWORK
  • FUTURE_CLOUD

A OneDrive or iCloud item may also physically consume internal disk space. Provider classification and physical consumption are separate attributes.

Storage Roles

ACTIVE

Working data expected to remain readily accessible.

ARCHIVE

Preserved historical data that does not need to remain in active storage.

BACKUP

A secondary copy maintained for recovery.

A volume may support multiple roles, but each configured root should have an explicit intended role.

Cloud State

Where detectable:

  • NOT_CLOUD
  • CLOUD_UNKNOWN
  • CLOUD_ONLY
  • DOWNLOADED
  • PINNED_LOCAL
  • SYNCED_LOCAL
  • ERROR_OR_CONFLICT

Provider-specific details should be retained separately from normalized state.

Protection State

Derived, not manually asserted:

  • UNPROTECTED
  • LOCAL_ONLY
  • SYNCED_ONLY
  • BACKED_UP
  • VERIFIED_BACKUP
  • ARCHIVED
  • MULTI_LOCATION_PROTECTED
  • UNKNOWN

The derivation algorithm must be documented and testable.

Release 0.1 may only emit states Burrow™ can prove without backup functionality: LOCAL_ONLY, SYNCED_ONLY, and UNKNOWN. Do not describe synchronized cloud files as backed up or protected. BACKED_UP, VERIFIED_BACKUP, ARCHIVED, MULTI_LOCATION_PROTECTED, and UNPROTECTED remain later-release states.

Collection

A Collection is a logical group of data for backup/health purposes, e.g.:

  • Personal Documents
  • Development
  • Photos
  • Financial
  • Archive

Collections reference one or more roots and later one or more protection policies.

Stable Identity

Paths are mutable. Track:

  • volume stable identifier;
  • filesystem identity where available;
  • current path;
  • content hash where calculated.

Do not assume path alone permanently identifies a file.

Logical vs Physical Size

Capture both when possible:

  • logical file size;
  • allocated/physical size.

Cloud placeholders may have a large logical size and minimal local allocation. The UI must not misleadingly count the logical size as immediately reclaimable local disk space.

Reclaimable Space

"Potential recovery" must be conservative.

For exact duplicates, do not sum all copies. A duplicate group with N copies can at most reclaim the size of the copies that are genuinely removable.

Cloud eviction ("free up local space") is different from deletion and should be presented as a separate future action.

Source of Truth

Filesystem/provider state observed during the latest scan is evidence. The SQLite catalog is historical state and analysis.

The UI should display scan age so users know when a conclusion may be stale.