Freeze the package compatibility corpus: real .rsbank bytes proving both ladder directions, every truncation site, and the round trip
This commit is contained in:
@@ -0,0 +1,172 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user