reasampler/docs/verify-package-transfer.md

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.