# DAW verification — bank-package transfer across machines

What a DAW pass must establish for `.rsbank` export and import, and the exact strings or
counts to read off. The unit corpus (`tests/fixtures/package_compat/`) already proves the
version ladder, the truncation verdicts and the hostile-name refusals against frozen
bytes. **Nothing below is covered by it**: every cell here depends on a real REAPER
session, a real file dialog, or a genuine second machine.

**Build to use.** Release, installed into `UserPlugins/`, REAPER restarted — extensions
load at startup only. Note the version the *About*/version action reports; §5 needs it.

**Machines to use.** Two: **A** (the source) and **B** (the destination). B must be a
different machine, or at minimum a different user account with its own REAPER resource
path and its own projects folder — the point is that no absolute path from A can resolve
on B. A USB stick, a network share, or a cloud folder are all acceptable transports.

**Projects to use.** On A: one **saved** project with a bank holding at least **three**
samples, at least one of them audibly distinct from the others, and at least one whose
display name carries a non-ASCII character (e.g. `Café hit`). On B: one **saved**,
otherwise empty project.

---

## 1. Export writes one file and touches nothing else

On A, right-click the bank's header in the docked panel → **Export as package...** (or
run *ReaSampler: export active bank as package*). Accept the suggested file name.

Read off:

- The console shows `ReaSampler export: wrote 3 entry/entries (N bytes) to <path>`, with
  the entry count matching the bank.
- A single `.rsbank` file exists at that path. **No `.rsbanktmp` sibling remains** — a
  leftover temp file means the atomic rename did not complete.
- The bank's card count, the bank folder's file count, and the project's dirty flag are
  all **unchanged**. An export writes no ext state and opens no undo point, so REAPER
  must not consider the project modified by it alone.
- Nothing was added to the arrange view.

## 2. The transfer itself — the claim no unit test can make

Copy the `.rsbank` to B by whatever transport you chose. Do **not** copy the project, the
bank folder, or anything else.

On B, open the empty saved project. Panel bank menu → **Import bank package...** (or run
*ReaSampler: import bank package (.rsbank)*), and choose the transferred file.

Read off:

- A message box: `Imported 3 sample(s) into a new bank: "<bank name>".`
- The console block repeats that line and ends with `One undo removes the imported bank
  and its entries. It does NOT delete the imported files ...`.
- The panel shows a **new** bank with the same display name and the same number of cards,
  **in the same order** as on A.
- B's bank folder holds three new files. The non-ASCII display name from A renders
  correctly on the card — a mangled name here means the UTF-8 path/name conversion broke
  in transit.
- **Audition each card.** They must sound like their counterparts on A. This is the whole
  claim: the audio survived a machine boundary with no shared path.
- Press **Ctrl-Z once**. The imported bank and its entries disappear in one step. The
  three files remain in B's bank folder (that is stated in the console block above, and is
  the designed behaviour — a prune reclaims them). Redo to continue.

## 3. Re-importing the same package never overwrites

Still on B, import the **same** file a second time.

Read off:

- A second new bank appears, named with a suffix (`<bank name> 2`), and the box's
  `(a bank named "<bank name>" already exists in this project)` clause appears in the
  console block.
- B's bank folder now holds **six** files, not three. The console reports
  `3 file(s) landed under a freshly minted name (the package's own name was already taken
  in the bank folder). An existing bank file is never overwritten.`
- The first imported bank's cards still audition correctly — nothing was replaced under it.

## 4. Round trip back to the source

On B, export the imported bank (§1) to a second `.rsbank`. Carry it back to A and import
it into A's original project.

Read off:

- The import succeeds and lands as a new bank beside the original.
- The original bank on A is untouched: same card count, same names, same audio.
- Compare the two `.rsbank` files' **sizes**. They will usually differ — entry names,
  sample ids and the export timestamp are all legitimately re-minted across a trip. The
  payload bytes are what must survive, and that half is closed by
  `tests/test_package_round_trip.cpp` against frozen bytes; do **not** treat a size
  difference here as a defect.

## 5. The too-new refusal, with the message read verbatim

This is the direction a user hits when a collaborator is ahead of them, and the message is
the only actionable output. Produce it by hand:

1. Copy the `.rsbank` from §1 to a scratch name.
2. Open the copy in a hex editor. Bytes 0–3 are `RSBK`; bytes 4–7 are `formatVersion`
   little-endian; bytes **8–11** are `minReaderVersion` little-endian.
3. Change byte **8** from `01` to `02`, and byte **4** from `01` to `02` (a writer cannot
   require a reader newer than the format it wrote — leaving `formatVersion` at 1 makes
   the file incoherent and it will be refused as malformed instead, which is a different
   cell). Save.
4. Import the edited copy.

Read off — the message box, all four lines:

```
Cannot import this bank package.
It was written by ReaSampler <the version noted at the top> and needs package format 2 or newer.
This build (<the same version>) reads package format 1.
Nothing was imported. Install ReaSampler <the same version> or newer and try again.
```

- The writer version named is the one **this** build stamped in §1 (the hex edit does not
  touch the semver), so the second and fourth lines will name your own version. That is
  expected — what is being verified is that all three facts are present and the box
  appears at all.
- **No** new bank, **no** new files in the bank folder, **no** undo point.

## 6. The truncated-download refusal is a different message

Copy the §1 package again and delete the last few hundred bytes (any hex editor, or
`head -c` / `fsutil` — the exact count does not matter as long as the file is shorter).
Import it.

Read off:

- The message box reads exactly: `This file is not a readable bank package (corrupt or
  truncated). Nothing was imported.`
- It is **not** the §5 message. Crossing these two is the failure this cell exists to
  catch — "install a newer build" does not fix a partial download.
- No new bank, no new files.

## 7. Corruption in the middle is caught before anything lands

Copy the §1 package again and flip a single byte **well past the halfway point** (inside a
payload, not the header). Import it.

Read off:

- The message box names the offending entry:
  `This bank package is damaged (entry "<name>" failed its integrity check). Nothing was
  imported.`
- The bank folder gained **no** files at all — not even the entries before the damaged
  one. Verification runs to completion before the first write, so a damaged package costs
  no rollback.

## 8. The unsaved-project refusals

- On B, File → New Project (do not save). Try to import. Read off:
  `Save the project before importing a bank package -- an unsaved project has no bank
  folder to import into.` The file picker must **not** have opened first.
- On A, in an unsaved project with no bank, try to export. Read off the console:
  `ReaSampler export: save the project first -- an unsaved project has no bank folder to
  read from.`

## 9. Drag-and-drop reaches the same verb

On B, drag a `.rsbank` from the file manager onto the docked ReaSampler panel.

Read off: the same import box as §2, and the same new bank. A `.rsbank` is a whole bank,
not audio — it must never land as an item in the arrange view.

---

## Recording the result

For each section, record **pass**, **fail with the string actually seen**, or **not
exercised**. §2 and §4 are the load-bearing ones: they are the only cells in this document
that involve a real machine boundary, and no unit test can stand in for them.
