viewable-one 0.0.0-stage → 0.12.1

package/lib/atomic.mjs

@@ -0,0 +1,96 @@
+// WRITE-THEN-RENAME, for every file the bridge writes that somebody else
+// polls.
+//
+// `writeFile` is not atomic: it truncates (or creates) the destination and
+// then streams bytes into it, so there is a real window in which a reader
+// sees an empty or half-written file. Nothing in this repo has a lock, and
+// every reader here is a POLLER - the app on its 10s ingestion tick, the
+// runner on its poll loop, a session's own `check_answer` - so that window
+// is not theoretical, it is the thing polling is guaranteed to find
+// eventually.
+//
+// It has already cost twice, on the OTHER side of the same contract:
+//
+//   - `lib/ops.mjs` readReceipt returns null rather than `{ok: false}` while
+//     the app's own non-atomic `writeFolderFile` is still in flight, because
+//     a poll landing in that window read "the app refused startSession",
+//     killed the request, and spawned nothing (2026-08-26). That guard reads
+//     around the app's window; this file removes the bridge's own.
+//   - a spawn request read mid-write parsed as invalid JSON and was CLAIMED
+//     with an ERROR receipt, and a claim is terminal - so a human click
+//     never ran.
+//
+// The temp file is a sibling (same directory, so the rename cannot cross a
+// filesystem) and carries the pid plus a counter, so two processes writing
+// the same destination never share a scratch name.
+
+import { link, rename, writeFile, rm } from "node:fs/promises";
+import { dirname, join, basename } from "node:path";
+
+let seq = 0;
+
+/** The rename failures that are worth waiting out rather than reporting.
+ *
+ * On Windows file locking is MANDATORY, not advisory: a rename over a
+ * destination another process has open fails EPERM or EBUSY, and every reader
+ * on the other side of this contract is a poller that opens these files
+ * constantly - plus the antivirus scanner and the search indexer, which open
+ * a file the instant it is created. The same rename a moment later succeeds.
+ * On a Mac neither code is ever produced here, so the loop below is dead code
+ * there and every existing test sees exactly what it saw before. Brief 21,
+ * session 3. */
+const RETRYABLE_RENAME = new Set(["EPERM", "EBUSY", "EACCES"]);
+
+/** How many times the rename is retried, and how long it waits between tries:
+ * 20ms, 40, 80, 120, 160 - about 420ms of patience in total, bounded so a
+ * genuinely locked file still fails rather than hanging a poll loop. */
+export const RENAME_RETRIES = 5;
+const backoffMs = (attempt) => Math.min(20 * (attempt + 1), 160);
+
+/** Write `data` to `path` so a concurrent reader sees either the old file or
+ * the new one, never a partial. Returns nothing; throws what writeFile throws.
+ *
+ * The temp file is removed on failure, so a failed write never leaves a
+ * `.tmp-` sibling behind for the next reader to wonder about.
+ *
+ * `rename` and `sleep` are injected for the retry test, which needs a rename
+ * that fails EBUSY twice and no real half-second of waiting. */
+export async function writeFileAtomic(
+  path,
+  data,
+  encoding = "utf8",
+  { rename: renameImpl = rename, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), retries = RENAME_RETRIES, mode } = {},
+) {
+  seq += 1;
+  const tmp = join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${seq}`);
+  try {
+    await writeFile(tmp, data, mode === undefined ? encoding : { encoding, mode });
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        await renameImpl(tmp, path);
+        break;
+      } catch (error) {
+        if (attempt >= retries || !RETRYABLE_RENAME.has(error?.code)) throw error;
+        await sleep(backoffMs(attempt));
+      }
+    }
+  } catch (error) {
+    await rm(tmp, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+/** Publish a complete file only if the destination does not exist. The link
+ * reserves the destination atomically across processes; a crash before it
+ * leaves only an ignored temp file, and a crash after it leaves the full file.
+ * EEXIST means another publisher already committed this identity. */
+export async function writeFileAtomicExclusive(path, data, encoding = "utf8") {
+  seq += 1;
+  const tmp = join(dirname(path), `.${basename(path)}.tmp-${process.pid}-${seq}`);
+  try {
+    await writeFile(tmp, data, encoding);
+    await link(tmp, path);
+  } finally {
+    await rm(tmp, { force: true }).catch(() => {});
+  }
+}