reasampler/src/shell/package/CLAUDE.md

src/shell/package — package filesystem + dialog seam

Scope

The filesystem and dialog acts behind bank-package export/import: streaming package file I/O plus the file-status and exclusive-create acts (package_io), the UTF-8 path conversion every one of them goes through (package_path), the landed-file journal and its rollback delete (package_rollback), and the two file pickers (package_pickers). Those are bytes-only — the package format (magic, manifest, entry layout) is core/package's business. Beside them sit both promptless verbs: export_bank whole, and the import split so its decisions stay testable — import_landing (REAPER-free) decides and writes, while import_bank owns the only REAPER project state this directory touches (the ext-state persist, the undo block, the generation bump). The export direction touches none of it: an export writes no ext state, opens no undo point and never bumps the generation, and what prompting it needs belongs to its skin (shell/actions/package_export_action), not this seam.

Invariants

• Paths cross this seam as UTF-8 narrow strings and are converted through utf8Path() before ANY filesystem call. This is not decoration: on Windows std::filesystem decodes a narrow path through the runtime ANSI code page (measured GetACP() == 1252), so a bare fs::path(std::string) turns café.rsbank into café.rsbank or fails to open it. Every path a verb hands in or gets back — including listFolderFileNames' results, which go through pathToUtf8() and never string() — is UTF-8. core/util/file_bytes has the un-converted shape, which is why readFilePayload reads through this module's own PackageFileReader instead.
• Atomic package write, to the limit of a rename. A package accumulates in a .rsbanktmp sibling in the destination directory and reaches the destination only through commit()'s rename (the mono-collapse temp+rename precedent). A failed, aborted, or abandoned write leaves the destination absent or holding its prior contents. This is process-crash atomic, NOT power-loss atomic: commit() flushes and closes but does not fsync/FlushFileBuffers, so a power cut can still leave a renamed-but-unflushed file. Deliberate — an fsync over a whole sample bank is a real stall, and the failure this design targets is a refused or interrupted export.
• Streaming, both ways — at most ONE entry's payload in memory. Writes append one payload at a time; reads seek and materialize one range at a time. The claim is structural, not aspirational: every payload crosses this seam as a move-only PayloadBuffer, and PayloadBuffer::alive() is the seam counter the tests assert against. There is no read-whole-package or write-whole-package entry point; do not add one.
• An empty PayloadBuffer is a failure signal, never an entry. It is the seam's one "nothing to work with" branch, so both PackageFileWriter::appendPayload and writeFileExclusive refuse it — appending it would let a verb commit framing that claims bytes nobody wrote. appendRaw(ptr, 0) stays tolerated: framing has legitimate zero-length edges.
• No overwrite of a bank-folder file, ever — and the create is the check. writeLandedFile lands through writeFileExclusive (O_EXCL / _O_EXCL), so the refusal of an occupied path is one atomic act rather than an exists() a concurrent writer could win the race against. Collision handling (auto-rename) remains the import plan's job upstream. The package writer itself DOES replace an existing destination — the export save dialog's own overwrite confirm is the consent — and that asymmetry is deliberate. Closed, both halves. pickPackageSavePath's own .rsbank re-append (see its Gotcha below) can turn a confirmed path X into a write target X.rsbank that the dialog never asked about, so exportBank re-checks fileStatus() on the path actually handed to PackageFileWriter — after any extension append — and refuses RefusedDestinationExists until the caller sets allowOverwrite. The caller does not always re-prompt to get there: pickPackageSavePath reports whether it appended (outAppended), and package_export_action pre-grants allowOverwrite whenever it did NOT — an unappended path is exactly what the dialog's own confirm already covered, so asking again would be a second prompt for the same consent. Only an appended path, one the dialog never saw, still costs the verb's own confirm naming that exact path.
• The rollback delete is prune's ONE carve-out, and only HALF of it is structural. The citation and the full discriminator live at package_rollback.cpp's header. "Did this call create it" is structural: only exclusively-created paths are recorded, resolved absolute at record time so a later CWD change cannot re-aim the delete. "Did anything ever reference it" is a contract the import verb must honour: it MUST call markIndexCommitted() only AFTER the index write has returned success — calling it before, then having that write fail, strands the landed files with no index entry and a journal that now refuses to roll them back — after which rollback() refuses and writeLandedFile refuses. (Destroying an armed journal without calling either does NOT roll it back — see LandedFileJournal's own doc comment.) import_bank honours it: it calls markIndexCommitted() only after persistBankOp has returned.
• Integrity is proven before the first byte lands, not undone after. landPackage hashes every declared payload against the manifest and only then creates the bank folder, so a damaged package costs no rollback at all and cannot leave debris behind a rollback that itself failed. The second read of each payload is deliberate on a once-per-gesture path — do not fold it into one hash-and-write pass.
• Both pickers ride GetUserFileName — mode 1 for import, mode 0 for export. There is no platform split and no fallback: main.cpp defines REAPERAPI_IMPLEMENT without REAPERAPI_MINIMAL and aborts the extension load if any single name fails to resolve, so a build that can load us cannot lack it.

Modules

• package_path — header-only; the ONE UTF-8-narrow → fs::path conversion, so the encoding contract has a single enforcement point.
• package_io — every filesystem act the verbs need: PayloadBuffer (move-only payload + the alive() seam counter), PackageFileWriter (append-only temp+atomic-rename writer), PackageFileReader (seek-and-read one range per call, range-checked against the real file size), readFilePayload (one source file as one entry's payload), fileStatus (Present/Absent/Unreadable — export's refusal message must distinguish the last two, and an empty payload cannot), writeFileExclusive (exclusive create + write, self-cleaning on a partial write), and listFolderFileNames (bare UTF-8 names, sorted, non-recursive, non-throwing). REAPER-free; tested without a DAW.
• package_rollback — LandedFileJournal: writeLandedFile (exclusive-create land, path resolved absolute, recorded on success only), markIndexCommitted (disarms the journal), and rollback (deletes exactly the recorded set, hard unlink, tolerating a vanished file; refuses once disarmed). REAPER-free; tested without a DAW.
• package_pickers — pickPackageForImport and pickPackageSavePath, both GetUserFileName; pickPackageSavePath also reports whether it appended .rsbank (outAppended), the signal package_export_action uses to skip a redundant overwrite confirm. Neither picker can be exercised in a unit test.
• export_bank — the promptless export verb, in three composable public steps: surveyBankExport (the read-only plan, report-before-acting), digestSources (measures each entry's length + hashBytes digest, one payload at a time), and writePackageFile (prefix, then each payload re-read and re-verified against that digest before it is appended, then commit). exportBank composes the three and gates on the plan verdict, the incomplete confirm and the destination confirm. The session arrives const: saveToActiveProject, bumpBankGeneration and writeAssignmentRequest are the session's only non-const acts, so a const session cannot reach them and "an export writes no ext state, opens no undo point and never bumps the generation" holds by the type rather than by memory (pruneReclaim, the sole file-deletion path, is const too and sits outside this claim). Reads the session through inline accessors only, which is why its tests link and run without a DAW.
• import_landing — the import's two halves that decide anything: landPackage (decode, plan, verify EVERY payload's digest, then land through the journal) and applyImportedBank (the new bank's entries plus a birth record per landed file, in one straight-line block). REAPER-free deliberately — all-or-nothing, integrity and birth-record behaviour are assertable without a DAW.
• import_bank — the promptless import verb over a live ReaSamplerSession: the project directory, the minted bank id, the recordCreated writer, and the one undo-batched persist. REAPER-facing, so it compiles into the extension module rather than into a library with a test target.

package_round_trip_tests is declared here with no library of its own: it drives the same frozen corpus (tests/fixtures/package_compat/) through both verbs, which is where export → import → export payload identity is proven.

Gotchas

• A crash mid-export strands the .rsbanktmp sibling. It is not a .rsbank (no picker filter matches it), and a later export to the same destination truncates it. A crash mid-import strands a partial bank file under its real name instead — the land is a direct exclusive create, not temp+rename. Either way the debris was never recorded in the tracking ledger, so prune sees a foreign file (not owned, never an orphan) and will not touch it; removal is by hand. [verify — DAW] whether the import verb should pre-clean stale debris when it lands.
• The picker filter and mode arguments are spelled to GetUserFileName's documented pair format but are [verify — DAW] on all three platforms — neither picker is exercised outside a live REAPER session. GetUserFileName also takes no owner window, so dialog parenting is REAPER's to do; the superseded Win32 path passed GetMainHwnd() explicitly. Also [verify — DAW]: whether mode 0's picker appends an extension from extension_list when the user omits one — pickPackageSavePath re-appends .rsbank itself so the returned path is correct regardless of how that lands (the superseded Win32 path had ofn.lpstrDefExt for this; GetUserFileName has no equivalent parameter). The re-append is suffix-blind: it only skips when the path already ends in .rsbank, so a path carrying a DIFFERENT extension gets .rsbank appended after it (mybank.bak → mybank.bak.rsbank), unlike the superseded ofn.lpstrDefExt, which appended only when the path had no extension at all. Defensible for a format-locked export, but a real divergence from the old picker's behavior — whoever tests the picker under [verify — DAW] should expect the double-extension result on a path that already has one.
• pickPackageSavePath's suggestedPath doubles as the dialog's starting directory when it is a full path. The verbs should seed it from the project directory — passing a bare name leaves the dialog on REAPER's process working directory, which is its install or resource path.
• readRange(_, 0) returns an empty buffer — indistinguishable from failure, by design (the one "nothing to work with" branch). Cross-track contract, not a local rule: a genuinely zero-length entry cannot round-trip through this seam, so core/package's format layer must not emit one.