# Loose-files mode

## Overview

Per-vault opt-in mode where audiofiles references samples at their original disk location instead of copying them into the vault's `samples/` directory. Trades safety for disk space savings.

In normal mode, every import copies the file into `vault/samples/<hash>.<ext>`. In loose-files mode, the database records the original path and no copy is made. The file stays where the user put it.

## Enabling

Loose-files mode is a vault-level setting, toggled in vault settings. Changing it only affects future imports — samples already in the vault are not moved or copied retroactively.

A vault stores its mode as a preference row:

| Key | Value | Default |
|-----|-------|---------|
| `loose_files` | `0` or `1` | `0` |

When loose-files mode is on, the vault settings UI shows a persistent warning:
> **Loose-files mode is on.** Samples are not copied into this vault. Moving, renaming, or deleting originals will break references.

## Import Behavior

### Normal Mode (unchanged)

1. Hash file → copy to `samples/<hash>.<ext>` → insert `samples` row
2. File is self-contained in the vault forever

### Loose-files mode

1. Hash file → record original absolute path → insert `samples` row
2. No copy is made
3. The `samples` row gets an additional `source_path TEXT` populated with the original absolute path

If a sample with the same hash already exists (duplicate detection still works), skip it as usual regardless of mode.

## Schema Change

Add one column to `samples`:

```sql
ALTER TABLE samples ADD COLUMN source_path TEXT;
```

- `NULL` → normal mode sample (blob lives in `samples/`)
- Non-`NULL` → loose-files mode sample (blob lives at this path)

This is the only way to tell which mode a sample was imported under. A vault in loose-files mode can contain a mix of both kinds if the mode was toggled between imports.

## Playback and Access

When resolving a sample's file path:

1. If `source_path` is `NULL`, use `vault/samples/<hash>.<ext>` (current behavior)
2. If `source_path` is non-`NULL`, use `source_path`

## Graceful Recovery

Loose-files mode makes a best-effort attempt to handle files that have gone missing. It does not try to be clever.

### On Access (Playback, Preview, Export, Analysis)

If `source_path` points to a file that no longer exists:

1. Check `vault/samples/<hash>.<ext>` as a fallback — the user may have re-imported in normal mode or manually placed the file there
2. If the fallback also misses, mark the sample as **unavailable** in the UI (grayed out, struck-through name, tooltip: "Original file not found at `<path>`")
3. Do not delete the metadata row — the sample keeps its tags, VFS position, and analysis data

### Relocate

Provide a **Relocate** action on unavailable samples:

- User picks a new file
- App verifies the SHA-256 hash matches the sample's `hash`
- If it matches, update `source_path` to the new location
- If it doesn't match, reject with: "Hash mismatch — this is a different file"

No batch relocate, no folder scanning, no automatic search. Keep it manual and simple.

### Vault Integrity Check

Add a "Check vault" action (in vault settings, next to the loose-files mode toggle) that scans all `source_path` entries and reports how many are valid vs. missing. Informational only — it does not fix anything, just gives the user a count.

## What This Does NOT Do

- Does not watch the filesystem for changes
- Does not auto-relocate or search for moved files
- Does not create symlinks or hardlinks
- Does not support relative paths — `source_path` is always absolute
- Does not convert existing samples between modes (no retroactive copy-in or copy-out)
- Does not sync `source_path` values via SyncKit — paths are device-local and meaningless on other machines