Docs: add verify-unsaved-bank.md, the five REAPER experiments gating the temp-bank design

docs/verify-unsaved-bank.md

@@ -0,0 +1,103 @@
+# DAW verification — REAPER behaviour behind a bank for never-saved projects
+
+What a hand-run REAPER pass must establish before the temporary bank for never-saved
+projects is designed. The plan is that the extension keeps a never-saved project's bank
+index in project ext state, then moves the bank's files into the project folder on the
+project's first save. That only works if REAPER keeps ext state on a project that has no
+`.rpp` yet and carries it into the first save. **No ReaSampler code exists for this yet** —
+every experiment below tests REAPER itself. **If E1 fails, the design needs rework**;
+E2–E5 only refine it.
+
+**Build to use.** None needed. The snippets run in REAPER's ReaScript console: *Actions →
+ReaScript: run ReaScript (EEL2 or lua)...*, or save the snippet as a `.lua` file and load
+it through *Actions → New action → Load ReaScript...*. Every API name cited below is in
+`vendor/reaper-sdk/sdk/reaper_plugin_functions.h`. The Lua return shapes are
+`[verify — DAW]`: ReaScript returns out-buffers as extra return values rather than taking
+a buffer argument, so adjust a snippet if it errors.
+
+**Projects to use.** Fresh never-saved tabs (*File → New project tab*). Close any saved
+project first so a stray `0` (current project) cannot resolve to it.
+
+---
+
+## E1. Ext state on a never-saved project survives tab switches and the first save (gates the design)
+
+1. In a new, never-saved tab, run:
+
+   ```lua
+   reaper.SetProjExtState(0, "rs_test", "k", "v")
+   ```
+
+2. Switch to another project tab, then back.
+3. Run:
+
+   ```lua
+   local n, v = reaper.GetProjExtState(0, "rs_test", "k")  -- [verify — DAW] return shape
+   reaper.ShowConsoleMsg(("n=%s v=%s\n"):format(tostring(n), tostring(v)))
+   ```
+
+4. Save the project for the first time. Close the tab, reopen the `.rpp`, and run step 3
+   again. Optionally open the `.rpp` in a text editor and look for `rs_test`.
+
+Read off: is `v` still `v` after the tab switch? After save and reopen? Is `rs_test` in
+the `.rpp`? The SDK header says `GetProjExtState` returns the value "the last time the
+project was saved", so a blank read at step 3 would matter even if step 4 passes.
+
+Result:
+
+## E2. Does `SetProjExtState` alone mark a never-saved project dirty?
+
+In a fresh never-saved tab with no other edits, run the `SetProjExtState` line from E1,
+then:
+
+```lua
+reaper.ShowConsoleMsg("dirty=" .. reaper.IsProjectDirty(0) .. "\n")
+```
+
+Read off: the `dirty` value, whether the title bar shows an asterisk, and whether closing
+the tab prompts to save.
+
+Result:
+
+## E3. What project path does a never-saved tab report?
+
+In two different never-saved tabs, run in each:
+
+```lua
+local p = reaper.GetProjectPathEx(0, "")  -- [verify — DAW] return shape
+reaper.ShowConsoleMsg("ex=" .. tostring(p) .. "  plain=" .. tostring(reaper.GetProjectPath("")) .. "\n")
+```
+
+Then change one tab's recording path (*File → Project settings → Media → Path to save
+media files*) and run it again in that tab.
+
+Read off: is it the default recording path? Is it the same in both tabs? Does the per-tab
+setting change it?
+
+Result:
+
+## E4. Save As with and without "Copy all media into project directory"
+
+In a never-saved tab, insert a media item whose file lives outside any project folder
+(e.g. a `.wav` on the desktop).
+
+1. *File → Save project as...* with **Copy all media into project directory** ticked.
+   Check where the item's source now points (item *Source properties*, or the take's
+   source via `GetMediaSourceFileName`).
+2. Repeat in a new never-saved tab with the option **unticked**.
+
+Read off: ticked — does the item now point at a copy in the project directory? Unticked —
+does it still point at the original path?
+
+Result:
+
+## E5. Save from the "save changes?" prompt on close and on quit
+
+Observation only. In a never-saved tab, make any change, then close the tab and choose
+**Save** in REAPER's "save changes?" prompt. Repeat by quitting REAPER with a never-saved,
+changed tab open.
+
+Read off: did REAPER save and then close in one step, with nothing in between? This
+confirms that an extension timer never gets to run between the save and the close.
+
+Result: