04 — Inventory Specification

From the Burrow™ specification set.

04 — Inventory Specification

Goal

Create an accurate, resumable, explainable catalog of user-approved storage roots without changing user files.

Root Discovery

Discover:

  • internal data volume;
  • iCloud Drive root(s);
  • OneDrive root(s);
  • mounted external volumes.

Discovery does not imply scanning. The user chooses/approves scan roots.

Default Exclusions

Do not scan operating-system internals by default.

Potential default exclusions include:

  • system directories;
  • application bundles unless specifically requested;
  • node_modules and build/cache directories as configurable exclusions, not hardcoded deletion targets;
  • package internals unless "scan packages" is enabled.

Exclusion rules must be visible and editable.

File Metadata

Capture where available:

  • file record ID;
  • scan ID;
  • volume ID;
  • root ID;
  • full path;
  • parent path;
  • name;
  • extension;
  • content type/UTI;
  • logical size;
  • allocated size;
  • creation time;
  • modification time;
  • last access time where reliable;
  • directory flag;
  • symbolic link flag;
  • package/bundle flag;
  • hidden flag;
  • provider;
  • normalized cloud state;
  • provider-specific metadata;
  • filesystem identity;
  • permission/read error state;
  • first seen;
  • last seen.

Symbolic Links

Do not recursively follow symlinks by default. Record the link and target metadata where safe to avoid cycles and unintended traversal.

Packages

Treat macOS packages/bundles as atomic by default for UI purposes. Advanced scanning may inspect contents later.

Progress

A scan should report:

  • current root;
  • files/directories discovered;
  • logical bytes observed;
  • errors;
  • elapsed time;
  • status: queued/running/cancelling/completed/failed/partial.

Cancellation

Cancellation must be safe. Persist completed observations and mark the scan incomplete.

Incremental Behavior

Reuse existing full hashes when the file identity and relevant change indicators prove the content has not changed.

Do not rely only on filename.

Cloud Placeholders

Avoid intentionally downloading cloud-only files merely to inventory them.

If content is unavailable locally, metadata may be cataloged and hash status set to unavailable/deferred.

Errors

Permission-denied, unavailable-volume, inaccessible-placeholder, path-race, and I/O errors should be recorded per item/root rather than aborting the entire scan.

Scan Completeness

The UI must indicate partial coverage. "No duplicates found" is not valid if significant roots were inaccessible.

Read-Only Acceptance Test

During v0.1, compare filesystem metadata before and after representative scans and verify Burrow™ has not mutated test files.