Ψ-W1-T4 remediation: gate silent arrange drops, pin surface totality, hedge unverified SDK claims, close comment/exception-safety minors

src/shell/actions/arrange_drop_win.h

@@ -16,14 +16,18 @@ class MediaTrack;
 
 namespace reasampler {
 
-// The arrange time under a screen X, via REAPER's own pixel-column -> time mapping. Times left
-// of project start clamp to 0.
+// The arrange time under a screen X, via GetSet_ArrangeView2's one-pixel-column reading —
+// inferred behavior, not SDK-documented (see the .cpp's assumption D). Times left of project
+// start clamp to 0.
 double arrangeTimeAtScreenX(int screenX);
 
-// Places every path in `absolutePaths` on `track`, the first at `time` and each subsequent one
-// after the previous (REAPER's own multi-file drop shape), inside ONE undo block. The drop time
-// honors the project's snap setting. The caller's track selection and edit-cursor position are
-// restored before returning. Returns the number of files handed to REAPER.
+// Places every path in `absolutePaths` on `track`, inside ONE undo block. The first lands at
+// `time`; whether REAPER's own cursor advance lands the rest end-to-end, or stacks them at one
+// position instead, is assumption B in the .cpp (visible, one Ctrl-Z away, either way). The
+// drop time is assumed to honor the project's snap setting (assumption C). The caller's track
+// selection and edit-cursor position are restored before returning. Returns the number of files
+// InsertMedia reported inserting successfully — its return isn't SDK-documented; treated as
+// 0=failure (assumption E in the .cpp).
 int performArrangeDrop(MediaTrack* track, double time,
                        const std::vector<std::string>& absolutePaths);