test(cli): deterministic torn-write regression coverage; document module

Address the openchamber-ai review's non-blocking notes: - Concurrency evidence: the torn-write test now injects a slow, chunked writeFile (one open handle, file grows prefix->full) so a torn read is deterministically observable in the 30ms window. A companion test runs the naive direct writer under the same load and asserts torn reads ARE produced, proving the atomicity test can actually fail on the pre-fix writer. - Windows fallback comment: no longer claims the copyFile fallback is atomic; it is called out as a last resort confined to Windows. - Module map: document cli-settings-accessors.js in bin/lib/DOCUMENTATION.md.
2026-08-09 11:39:42 +08:00
parent 7a165fd0bb
commit 95338dbbb1
3 changed files with 101 additions and 34 deletions
@@ -78,8 +78,10 @@ export const createSettingsAccessors = ({ fsPromises, path, dataDir, settingsFil
    }

    // Windows can transiently reject the atomic replace while another process
-    // briefly holds the target open. Copy the COMPLETE tmp file into place so
-    // persistence never wedges; a reader can still never see partial content.
+    // briefly holds the target open. Fall back to copying the COMPLETE tmp file
+    // so persistence never wedges. Note: copyFile is NOT atomic — this is a
+    // last-resort path confined to Windows, matching the settings runtime's
+    // fallback, not a substitute for the atomic rename used everywhere else.
    await fsPromises.copyFile(tmp, target);
    await fsPromises.rm(tmp, { force: true });
  };