fix: keep failed captures unpublished

Author: DevanMetz

.github/workflows/release.yml

@@ -41,6 +41,8 @@ jobs:
         run: python3 tools/test_ebook_pages.py --compiler cc
       - name: Test ebook library
         run: python3 tools/test_ebook_library.py --compiler cc
+      - name: Test capture writers
+        run: python3 tools/test_capture_write.py --compiler cc
       - name: Test Files text previews
         run: python3 tools/test_file_preview.py --compiler cc
       - name: Test Files directories
@@ -200,6 +202,21 @@ jobs:
           if-no-files-found: warn
           retention-days: 14
 
+      - name: Retain capture writer evidence
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: capture-write-logs
+          path: |
+            build/capture-write/compile.log
+            build/capture-write/result.log
+            build/capture-write/source.json
+            build/capture-write/capture_write.inc
+            build/capture-write/capture_write_config.inc
+            build/capture-write/storage_source.inc
+          if-no-files-found: warn
+          retention-days: 14
+
       - name: Retain Files text preview evidence
         uses: actions/upload-artifact@v4
         if: always()

ROADMAP.md

@@ -60,6 +60,7 @@ Phase 0 software work is implemented and builds cleanly:
 
 Phase 1 software progress is also underway:
 
+- [x] Scope and I2C capture cleanup no longer retries publication after a rejected write or failed I2C flush/sync. I2C releases recording ownership on known SD failure; both writers preserve the first cause through close and report once. All 35 native writer/storage cases pass; the previous callbacks fail 16 controls. Exact CSV/TMP bytes, Scope filename collision, pre-flush timing and 25 independent failure/success cycles per writer are checked with closed handles. UI, data, time, mount and fault boundaries are controlled; I2C start, ADC/drivers and physical SD/panel remain separate gates. Linux CI retains source hashes and logs.
 - [x] Ebook library listings confirm regular-file metadata before accepting `.txt` entries and report directory setup/open/read/stat/close errors, entry capacity and skipped long paths. Failed listings no longer claim an empty library; the first failure survives close. All 28 native existing-directory/file cases pass, including unchanged bytes, callback path ownership, first-error checks and 25 reopen cycles with closed handles. The previous callback fails 18 controls. UI, timer, mount, download and error boundaries are controlled; welcome creation and physical SD/panel checks remain separate. Linux CI retains source hashes and logs.
 - [x] System reports the firmware/commit, reset reason, uptime, panel, heap, storage capacity, current OTA state, and persistent last OTA result.
 - [x] Notes and ride summaries use recoverable backup replacement; rides publish only after durable sync, and health logs repair incomplete final rows.

docs/architecture.md

@@ -99,6 +99,8 @@ Files directory browsing resets errno before each directory read so per-entry `s
 
 The ebook library verifies regular-file metadata before offering a `.txt` entry, excluding matching directories and unconfirmed paths. Directory setup/open failures show their cause; read/stat/close failures keep confirmed rows visible with an incomplete-list warning. Fresh errno checks preserve the first failure, and failed or skipped listings cannot claim the library is empty. The existing 64-entry and 256-byte path bounds are disclosed. Native checks use an existing BOOKS directory with controlled UI, timer, SD, download and fault boundaries; welcome creation and physical storage remain separate checks.
 
+Scope captures the first rejected header/row write before cleanup and closes an invalid temporary stream without attempting publication. I2C uses a shared finish path for explicit Stop and error cleanup: known row/flush/sync/SD failures close and release recording ownership, preserve the first cause, and report once; only a healthy Stop attempts publication. This prevents a successful retry during cleanup from turning an earlier failure into a Saved result. Native bytes and closed handles are checked with controlled UI/data/time/fault boundaries; sampling, drivers and physical SD behavior remain separate gates.
+
 See [Storage and compatibility contract](compatibility.md) and [Data formats](data-formats.md).
 
 ## Network and radio

docs/data-formats.md

@@ -39,6 +39,8 @@ Choose a record from the current page and tap **COPY ROW** to put its original 1
 
 The ebook library accepts case-insensitive `.txt` names only after confirming regular-file metadata, and skips directories or entries with failed metadata. It stores at most 64 paths of 256 bytes, disclosing filled slots and overlong names. Setup/open errors show their cause; read/stat/close errors mark retained confirmed entries incomplete and reach the SD callback with the first failure. The copy-books hint appears only after an error-free listing with no accepted or overlong entries. Native existing-directory checks cover these transitions with controlled UI, timer, mount and error boundaries; welcome creation and physical SD/panel behavior remain separate checks.
 
+Scope and I2C capture failures never retry publication during cleanup. Rejected header/row writes and failed I2C periodic flush/sync stop recording into the current TMP, close it, preserve the first cause and report failure. Known SD unavailability also closes an active I2C capture before adding another row. Healthy explicit saves still use the existing flush/sync/close/rename helper and CSV formats. A failed TMP can contain partial or complete-looking bytes; check the named file before recovery. Native byte/fault checks do not establish physical durability or power-loss recovery.
+
 ## CSV conventions
 
 Before appending, HTTP, MQTT and Ring heart-rate logs remove an unfinished final row by retaining bytes through the last LF. Recovery scans backwards in 512-byte blocks, preserving preceding complete rows. Seek/read failures leave the file unchanged; truncation is synced before closing, and sync/close errors remain errors even if the tail has already been removed. Writers must be stopped during recovery. Native byte checks cover long tails and block boundaries; real SD timing and power-loss behavior remain hardware checks.

docs/testing.md

@@ -16,6 +16,7 @@ Python 3 and Node.js are needed for the quick checks. The configuration checks a
 | Ring heart-rate logging, saved timestamps or queue processing | [Ring history storage](#ring-history-storage) and a firmware build. |
 | Ebook page loading or navigation | [Ebook pages](#ebook-pages) and a firmware build. |
 | Ebook library enumeration | [Ebook library](#ebook-library) and a firmware build. |
+| Scope/I2C CSV writes or publication | [Capture writers](#capture-writers) and a firmware build. |
 | Scope/I2C capture or saved serial CSV viewers | [CSV viewer storage and UI](#csv-viewer-storage-and-ui), existing serial-copy checks and a firmware build. |
 | Files fallback text previews | [Files text previews](#files-text-previews) and a firmware build. |
 | Files directory browsing | [Files directories](#files-directories) and a firmware build. |
@@ -166,6 +167,18 @@ Windows Find APIs and POSIX directory APIs supply the entries; native dot entrie
 
 The library retains 64 stored paths of 256 bytes. The entry-limit message means those slots filled; no extra read proves that more entries exist. Generated callback/config source, full main/function/test hashes and compile/result logs stay under `build/ebook-library/`. Linux CI retains `ebook-library-logs`, including available failure diagnostics. These 28 checks are separate from the Windows native total.
 
+## Capture writers
+
+```powershell
+python tools/test_capture_write.py --compiler 'C:/path/to/clang.exe'
+```
+
+The portable runner compiles the actual Scope save callback and I2C log/finish/Stop callbacks together with complete `storage_io.c`. Its 35 cases verify exact native CSV/TMP bytes, the 300-row Scope format, I2C success/transaction-error rows, header/row failures with and without a stream error flag, missing errno, tick-clobbered errno, first-error preservation through close, one-shot flush/sync failures, failed publication, known SD unavailability during logging or Stop, pre-flush timing, a preexisting Scope filename and 25 independent failure/success cycles per writer. The previous callbacks fail 16 controls, including publishing rejected data during cleanup and replacing the first error. All current cases finish with closed native file/descriptor handles and one SD report per I/O failure.
+
+Rejected writes and I2C flush/sync failures close the stream without retrying publication. A complete-looking TMP can remain after a failed flush/sync/close; these checks do not establish physical durability or rollback. UI, clocks/ticks, channel/sample/calibration data, directory preparation, logical mount paths, SD error reporting and I/O faults are controlled. UTC supplies deterministic filenames. Windows descriptor creation adds binary mode so CSV bytes match the SDK's LF output. The I2C start constructor, drivers, ADC acquisition, real LVGL, SDK mount/error filtering, physical SD/panel and power cuts are not executed. The cycle fixture removes its owned prior files between independent sessions; it does not prove retained-TMP collision recovery in the I2C constructor.
+
+Full main/function/storage/header/test hashes, generated callback/config/storage source and compile/result logs stay under `build/capture-write/`. Linux CI retains `capture-write-logs`, including available failure diagnostics. These 35 cases are separate from the Windows native total.
+
 ## CSV viewer storage and UI
 
 ```powershell

main/main.c

@@ -2273,26 +2273,33 @@ static void scope_capture_clicked(lv_event_t *event)
     gain_permille = scope_gains_permille[channel_index];
     portEXIT_CRITICAL(&scope_lock);
     uint32_t rate = scope_sample_rates[rate_index];
-    bool write_ok = fputs("unix_time,elapsed_us,gpio,millivolts,sample_rate_hz,offset_mv,scale_permille\n", file) >= 0;
-    for (size_t i = 0; write_ok && i < SCOPE_CHART_POINTS; i++) {
+    errno = 0;
+    int error = fputs("unix_time,elapsed_us,gpio,millivolts,sample_rate_hz,offset_mv,scale_permille\n", file) < 0
+                    ? (errno ? errno : EIO) : 0;
+    for (size_t i = 0; !error && i < SCOPE_CHART_POINTS; i++) {
         uint32_t elapsed_us = (uint32_t)((uint64_t)i * 1000000U / rate);
-        write_ok = fprintf(file, "%lld,%lu,%d,%ld,%lu,%d,%u\n",
-                           (long long)captured_at, (unsigned long)elapsed_us,
-                           (int)scope_channels[channel_index].pin, (long)scope_chart_points[i],
-                           (unsigned long)rate, (int)offset_mv, (unsigned)gain_permille) >= 0;
+        errno = 0;
+        if (fprintf(file, "%lld,%lu,%d,%ld,%lu,%d,%u\n",
+                    (long long)captured_at, (unsigned long)elapsed_us,
+                    (int)scope_channels[channel_index].pin, (long)scope_chart_points[i],
+                    (unsigned long)rate, (int)offset_mv, (unsigned)gain_permille) < 0)
+            error = errno ? errno : EIO;
     }
 
-    bool saved = write_ok && storage_commit_new_file(&file, temporary_path, final_path) == 0;
-    if (!saved && file) {
-        errno = errno ? errno : EIO;
-        storage_commit_new_file(&file, temporary_path, final_path);
+    bool saved = false;
+    if (!error) {
+        errno = 0;
+        saved = storage_commit_new_file(&file, temporary_path, final_path) == 0;
+        if (!saved) error = errno ? errno : EIO;
+    } else {
+        fclose(file);
+        file = NULL;
     }
     if (saved) {
         const char *name = strrchr(final_path, '/');
         snprintf(scope_capture_notice, sizeof(scope_capture_notice), "Saved %s",
                  name ? name + 1 : "Scope CSV");
     } else {
-        int error = errno ? errno : EIO;
         sd_record_error(error);
         struct stat info;
         bool retained = stat(temporary_path, &info) == 0;
@@ -5876,23 +5883,34 @@ static void i2c_result_action(void)
     i2c_update_controls();
 }
 
-static bool i2c_capture_stop(void)
+static bool i2c_capture_finish(int error)
 {
-    if (!i2c_capture_file) return true;
+    if (!i2c_capture_file) return error == 0;
+    if (!error && !sd_ready) {
+        error = sd_error_snapshot();
+        if (!error) error = ENODEV;
+    }
 
     const char *temporary_name = strrchr(i2c_capture_temporary_path, '/');
     const char *final_name = strrchr(i2c_capture_final_path, '/');
-    bool saved = storage_commit_new_file(&i2c_capture_file, i2c_capture_temporary_path,
-                                         i2c_capture_final_path) == 0;
+    bool saved = false;
+    if (!error) {
+        errno = 0;
+        saved = storage_commit_new_file(&i2c_capture_file, i2c_capture_temporary_path,
+                                       i2c_capture_final_path) == 0;
+        if (!saved) error = errno ? errno : EIO;
+    } else {
+        fclose(i2c_capture_file);
+        i2c_capture_file = NULL;
+    }
     if (saved) {
         snprintf(i2c_capture_notice, sizeof(i2c_capture_notice), "Saved %s",
                  final_name ? final_name + 1 : "I2C CSV");
     } else {
-        int save_error = errno ? errno : EIO;
-        sd_record_error(save_error);
+        sd_record_error(error);
         snprintf(i2c_capture_notice, sizeof(i2c_capture_notice),
-                 "Capture not published; %s retained (%s)",
-                 temporary_name ? temporary_name + 1 : "TMP", strerror(save_error));
+                 "Capture not published; check %s (%s)",
+                 temporary_name ? temporary_name + 1 : "TMP", strerror(error));
     }
     i2c_capture_temporary_path[0] = '\0';
     i2c_capture_final_path[0] = '\0';
@@ -5901,6 +5919,11 @@ static bool i2c_capture_stop(void)
     return saved;
 }
 
+static bool i2c_capture_stop(void)
+{
+    return i2c_capture_finish(0);
+}
+
 static bool i2c_capture_start(void)
 {
     i2c_capture_notice[0] = '\0';
@@ -6010,24 +6033,26 @@ static bool i2c_capture_start(void)
 static void i2c_capture_log(esp_err_t transaction_error, uint8_t value)
 {
     if (!i2c_capture_file) return;
+    if (!sd_ready) {
+        int error = sd_error_snapshot();
+        i2c_capture_finish(error ? error : ENODEV);
+        return;
+    }
 
     char value_text[5] = "";
     if (transaction_error == ESP_OK) snprintf(value_text, sizeof(value_text), "0x%02X", value);
-    bool failed = fprintf(i2c_capture_file, "%lld,0x%02X,0x%02X,%s,%s,%lu\n",
-                          (long long)time(NULL), i2c_selected_address, i2c_selected_register,
-                          value_text, esp_err_to_name(transaction_error),
-                          (unsigned long)(i2c_bus_speed_hz / 1000)) < 0;
+    errno = 0;
+    int error = fprintf(i2c_capture_file, "%lld,0x%02X,0x%02X,%s,%s,%lu\n",
+                        (long long)time(NULL), i2c_selected_address, i2c_selected_register,
+                        value_text, esp_err_to_name(transaction_error),
+                        (unsigned long)(i2c_bus_speed_hz / 1000)) < 0 ? (errno ? errno : EIO) : 0;
     TickType_t now = xTaskGetTickCount();
-    if (!failed && now - i2c_capture_last_flush_tick >= pdMS_TO_TICKS(I2C_CAPTURE_FLUSH_MS)) {
-        failed = storage_sync_file(i2c_capture_file) != 0;
-        if (!failed) i2c_capture_last_flush_tick = now;
-    }
-    if (failed) {
-        int error = errno ? errno : EIO;
-        sd_record_error(error);
-        errno = error;
-        i2c_capture_stop();
+    if (!error && now - i2c_capture_last_flush_tick >= pdMS_TO_TICKS(I2C_CAPTURE_FLUSH_MS)) {
+        errno = 0;
+        if (storage_sync_file(i2c_capture_file) != 0) error = errno ? errno : EIO;
+        else i2c_capture_last_flush_tick = now;
     }
+    if (error) i2c_capture_finish(error);
 }
 
 static void i2c_address_step_clicked(lv_event_t *event)