fix(runtime): make Copy to RAM switch live backing

2026-09-03 10:47:15 +03:00
parent 347bc8310a
commit b1ab866f58
7 changed files with 150 additions and 111 deletions
@@ -138,7 +138,7 @@ All SAT run endpoints enqueue an async task. Response: `{"task_id": "..."}`.
 | Method | Path                         | Description                                       |
 |--------|------------------------------|---------------------------------------------------|
 | GET    | `/api/system/ram-status`     | toram boot state and ISO copy status              |
-| POST   | `/api/system/install-to-ram` | Copy ISO to RAM (background task)                 |
+| POST   | `/api/system/install-to-ram` | Copy ISO to RAM and verify active loop backing    |
 | GET    | `/api/system/time`           | Current host epoch, local wall-clock text, and timezone |
 | POST   | `/api/system/time-sync`      | Set host time and timezone from the browser       |
 | POST   | `/api/system/reboot`         | Reboot the host                                   |
@@ -0,0 +1,50 @@
+# Runtime Copy to RAM must switch the active loop backing file
+
+**Date:** 2026-09-03
+**Status:** active
+
+## Evidence
+
+On `bee@172.16.41.97`, the runtime `Copy to RAM` task showed two contradictory
+results:
+
+- with the BMC virtual CD connected, the 2.7 GB squashfs copy reached 100%,
+  loop reassociation logged `invalid argument`, and the worker failed;
+- without the ISO connected, a later task found the stale file in
+  `/dev/shm/bee-live`, logged the same reassociation error, but returned
+  success.
+
+After the reported success, `/sys/block/loop0/loop/backing_file` still named
+`/run/live/medium/live/filesystem-*.squashfs`, `/run/live/medium` was backed by
+`/dev/sr0`, and disconnecting virtual media produced repeated `Medium not
+present` and I/O errors. The system was not running independently from RAM.
+
+The Linux ABI defines `LOOP_CHANGE_FD` as `0x4C06` and
+`LOOP_SET_DIRECT_IO` as `0x4C08`. The application had named `0x4C08` as
+`ioctlLoopChangeFD`, so every fallback reassociation called the wrong ioctl
+and received `EINVAL`.
+
+## Decision
+
+- Use the correct `LOOP_CHANGE_FD` request number, `0x4C06`, and protect it
+  with a Linux-specific regression test.
+- Copy all source data before changing active loop devices.
+- Treat a missing loop device, failed reassociation, or failed post-change
+  backing-file lookup as a fatal task error. A copied file alone is never
+  proof that the running system uses it.
+- After all squashfs loops point at their files in `/dev/shm/bee-live`,
+  unmount the original live-medium mount and bind the RAM directory at
+  `/run/live/medium`.
+- Success requires both at least one switched loop and a tmpfs-backed
+  `/run/live/medium`.
+- Eject the original device without unmounting the new RAM bind mount.
+- Preserve a complete RAM copy after any failure that occurs after loop
+  reassociation begins, so retry never deletes a file backing a live loop.
+
+## Consequences
+
+The button can resume a complete copy left by an interrupted worker even if
+the virtual CD has since disappeared, but it reports success only if the
+kernel actually accepts that file as the live loop backing. Partial or stale
+copies can no longer produce a false `done` result. Boot-time `toram` remains
+a separate initramfs path and is not evidence that the runtime button worked.
@@ -17,3 +17,4 @@ One file per decision, named `YYYY-MM-DD-short-topic.md`.
 | 2026-08-31 | "Run All" SAT planning happens on the backend, not the browser | active |
 | 2026-08-31 | Support bundle uses private staging and unique atomic output | active |
 | 2026-09-03 | PCIe link verdict comes only from the existing real-traffic GPU bandwidth SAT | active |
+| 2026-09-03 | Runtime Copy to RAM succeeds only after active loop devices move to tmpfs | active |