@scalebun-release/react-native 2.5.0

package/android/src/main/java/com/scalebun/replaysdk/outbox/NativeOutbox.kt

@@ -0,0 +1,574 @@
+package com.scalebun.replaysdk.outbox
+
+import android.content.Context
+import com.scalebun.replaysdk.core.ReplayLogger
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+
+/**
+ * Native file-based replay outbox (durable; survives app restart / process kill).
+ *
+ * Layout (per the implementation spec):
+ *   <root>/sessions/<sessionId>/
+ *     manifest.json
+ *     frames/{pending,uploading,failed,dead}/<frameId>.{webp|jpg}  + <frameId>.json
+ *     events|logs|network|errors|performance/{pending,uploading,failed,dead}/
+ *       segment-NNNNNN.jsonl + segment-NNNNNN.meta.json
+ *
+ * Durability rules:
+ *  - Atomic writes only: write `<name>.tmp`, fsync, then rename to final. A partially
+ *    written file never becomes a valid queue item.
+ *  - For a frame the metadata `.json` is the COMMIT MARKER: the image is written and
+ *    renamed first, then the `.json`. An image without a sibling `.json` is an orphan
+ *    and is swept on recovery — it is never uploaded.
+ *  - Telemetry is appended to an OPEN segment (`segment-current.jsonl`). It is closed
+ *    (renamed to `segment-NNNNNN.jsonl` + a `.meta.json`) on count/byte threshold or
+ *    on flush/session-end. Only CLOSED segments are uploaded.
+ *  - On startup, stale `uploading/` items are moved back to `pending/` (an upload
+ *    that was interrupted mid-flight is retried, not lost).
+ *
+ * All disk mutation is serialized on this instance's monitor so the bridge thread,
+ * the capture thread and the uploader thread never race a rename.
+ */
+class NativeOutbox(context: Context, private val maxBytes: Long, private val maxAgeMs: Long) {
+
+    private val lock = Any()
+    private val root: File = resolveRoot(context)
+
+    companion object {
+        const val FRAMES = "frames"
+        val TELEMETRY_LANES = listOf("events", "logs", "network", "errors", "performance")
+        private const val OPEN_SEGMENT = "segment-current.jsonl"
+
+        /**
+         * Diagnostic counters (process-global, observable, never silent — section 3/§Privacy).
+         *  - maskFailureDropCount: frames discarded at CAPTURE time because masking could
+         *    not be applied/resolved (fail-closed). Incremented by the capture path.
+         *  - maskPolicyDropCount: committed frames deleted by recover() for masked=false
+         *    under a mask-required policy.
+         */
+        @JvmStatic val maskFailureDropCount = java.util.concurrent.atomic.AtomicInteger(0)
+        @JvmStatic val maskPolicyDropCount = java.util.concurrent.atomic.AtomicInteger(0)
+
+        /**
+         * noBackupFilesDir/scalebun/outbox when available (screenshots must NOT be in
+         * cloud backup), else filesDir/scalebun/outbox.
+         */
+        private fun resolveRoot(context: Context): File {
+            val base = try {
+                context.noBackupFilesDir ?: context.filesDir
+            } catch (_: Throwable) {
+                context.filesDir
+            }
+            return File(File(base, "scalebun"), "outbox").also { it.mkdirs() }
+        }
+    }
+
+    // ─── Session dirs ───────────────────────────────────────────────────
+
+    private fun sessionDir(sessionId: String): File = File(File(root, "sessions"), sessionId)
+
+    private fun laneDir(sessionId: String, lane: String, state: String): File =
+        File(File(sessionDir(sessionId), lane), state).also { it.mkdirs() }
+
+    fun initSession(sessionId: String, screenName: String): Unit = synchronized(lock) {
+        val dir = sessionDir(sessionId)
+        for (lane in listOf(FRAMES) + TELEMETRY_LANES) {
+            for (state in listOf("pending", "uploading", "failed", "dead")) {
+                File(File(dir, lane), state).mkdirs()
+            }
+        }
+        // Idempotent: preserve the original startedAt (LRU/age key) across re-inits.
+        val manifestFile = File(dir, "manifest.json")
+        if (!manifestFile.exists()) {
+            val manifest = JSONObject()
+                .put("sessionId", sessionId)
+                .put("screenName", screenName)
+                .put("startedAt", System.currentTimeMillis())
+                .put("schema", 1)
+            atomicWrite(manifestFile, manifest.toString().toByteArray())
+        }
+    }
+
+    // ─── Frames ─────────────────────────────────────────────────────────
+
+    /**
+     * Persist a captured frame. Writes the image bytes first (renamed into place),
+     * then the metadata json as the commit marker. Returns the metadata path on
+     * success, null on failure. NO base64 — raw encoded bytes only.
+     */
+    fun writeFrame(meta: JSONObject, bytes: ByteArray): String? = synchronized(lock) {
+        try {
+            val sessionId = meta.getString("sessionId")
+            val frameId = meta.getString("frameId")
+            val format = meta.optString("format", "webp")
+            val ext = if (format == "jpeg") "jpg" else "webp"
+            val pending = laneDir(sessionId, FRAMES, "pending")
+            val imageFile = File(pending, "$frameId.$ext")
+            atomicWrite(imageFile, bytes)
+            meta.put("localFile", imageFile.name)
+            meta.put("attemptCount", 0)
+            meta.put("nextRetryAt", 0L)
+            val metaFile = File(pending, "$frameId.json")
+            atomicWrite(metaFile, meta.toString().toByteArray())
+            metaFile.absolutePath
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.writeFrame failed: ${e.message}")
+            null
+        }
+    }
+
+    /**
+     * Staged frame write — IMAGE ONLY (no metadata json). The frame is invisible to
+     * the uploader (which lists `.json` metas) until `commitFrame` lands the meta.
+     * Lets the JS orchestrator (ReplayCaptureManager) make its keyframe/delta +
+     * change-detection decision BEFORE the frame becomes uploadable. A staged image
+     * with no sibling `.json` is swept as an orphan on the next `recover()`.
+     * Returns the image filename on success, null on failure.
+     */
+    fun writeFrameImage(sessionId: String, frameId: String, format: String, bytes: ByteArray): String? = synchronized(lock) {
+        try {
+            val ext = if (format == "jpeg") "jpg" else "webp"
+            val pending = laneDir(sessionId, FRAMES, "pending")
+            val imageFile = File(pending, "$frameId.$ext")
+            atomicWrite(imageFile, bytes)
+            imageFile.name
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.writeFrameImage failed: ${e.message}")
+            null
+        }
+    }
+
+    /**
+     * Commit a previously staged frame: write the metadata json (the upload marker)
+     * carrying the JS-authoritative `sequenceNumber`/`frameType`/`baseFrameId`. Returns
+     * the meta path, or null if the staged image is missing.
+     */
+    fun commitFrame(meta: JSONObject): String? = synchronized(lock) {
+        try {
+            val sessionId = meta.getString("sessionId")
+            val frameId = meta.getString("frameId")
+            val format = meta.optString("format", "webp")
+            val ext = if (format == "jpeg") "jpg" else "webp"
+            val pending = laneDir(sessionId, FRAMES, "pending")
+            val imageFile = File(pending, "$frameId.$ext")
+            if (!imageFile.exists()) {
+                ReplayLogger.warn("outbox.commitFrame: staged image missing for $frameId")
+                return null
+            }
+            meta.put("localFile", imageFile.name)
+            meta.put("attemptCount", 0)
+            meta.put("nextRetryAt", 0L)
+            val metaFile = File(pending, "$frameId.json")
+            atomicWrite(metaFile, meta.toString().toByteArray())
+            metaFile.absolutePath
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.commitFrame failed: ${e.message}")
+            null
+        }
+    }
+
+    /** Discard a staged frame (JS suppressed it): delete the image + any meta. */
+    fun discardFrame(sessionId: String, frameId: String): Unit = synchronized(lock) {
+        try {
+            val pending = laneDir(sessionId, FRAMES, "pending")
+            pending.listFiles { f -> f.name.substringBeforeLast('.') == frameId }?.forEach { it.delete() }
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.discardFrame failed: ${e.message}")
+        }
+    }
+
+    // ─── Quota (shared contract v1) ─────────────────────────────────────
+
+    /**
+     * Delete EVERYTHING stored for one lane, across every session and every state (pending incl.
+     * the open segment and staged frame images, uploading, failed, dead). Used when the server
+     * refuses the lane's feature for quota: the stored items would be refused too, and the contract
+     * forbids retrying them. Returns the number of files removed.
+     */
+    fun purgeLane(lane: String): Int = synchronized(lock) {
+        var removed = 0
+        try {
+            val sessions = File(root, "sessions").listFiles()?.filter { it.isDirectory } ?: emptyList()
+            for (dir in sessions) {
+                for (state in listOf("pending", "uploading", "failed", "dead")) {
+                    File(File(dir, lane), state).listFiles()?.forEach { if (it.delete()) removed++ }
+                }
+            }
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.purgeLane($lane) failed: ${e.message}")
+        }
+        removed
+    }
+
+    /**
+     * Delete ONE session's whole directory (every lane, every state). Used when the server refuses a
+     * child write with 402 quota_exceeded feature:"sessions": that session's start was refused, no
+     * row will ever exist, so nothing stored for it can ever be accepted. Other sessions are untouched.
+     */
+    fun purgeSession(sessionId: String): Boolean = synchronized(lock) {
+        if (sessionId.isEmpty()) return@synchronized false
+        try { sessionDir(sessionId).deleteRecursively() } catch (e: Exception) { false }
+    }
+
+    // ─── Telemetry (JSONL segments) ─────────────────────────────────────
+
+    /**
+     * Append telemetry records (one JSON object per line) to the lane's open segment,
+     * then close+rotate the segment when it reaches `flushCount` lines or `maxSegBytes`.
+     */
+    fun appendTelemetry(
+        sessionId: String,
+        lane: String,
+        records: List<JSONObject>,
+        flushCount: Int,
+        maxSegBytes: Long,
+    ): Unit = synchronized(lock) {
+        if (records.isEmpty()) return
+        try {
+            val pending = laneDir(sessionId, lane, "pending")
+            val open = File(pending, OPEN_SEGMENT)
+            val sb = StringBuilder()
+            for (r in records) sb.append(r.toString()).append('\n')
+            // Append is naturally crash-truncating at line granularity; a half-written
+            // trailing line is dropped by the line reader on upload, never mis-parsed.
+            open.appendBytes(sb.toString().toByteArray())
+            val lines = countLines(open)
+            if (lines >= flushCount || open.length() >= maxSegBytes) {
+                closeSegment(sessionId, lane)
+            }
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.appendTelemetry($lane) failed: ${e.message}")
+        }
+    }
+
+    /** Force-close every lane's open segment (call on flush / session end). */
+    fun closeAllOpenSegments(sessionId: String): Unit = synchronized(lock) {
+        for (lane in TELEMETRY_LANES) closeSegment(sessionId, lane)
+    }
+
+    private fun closeSegment(sessionId: String, lane: String) {
+        val pending = laneDir(sessionId, lane, "pending")
+        val open = File(pending, OPEN_SEGMENT)
+        if (!open.exists() || open.length() == 0L) return
+        val seq = nextSegmentSeq(pending)
+        val name = "segment-%06d".format(seq)
+        val finalFile = File(pending, "$name.jsonl")
+        if (open.renameTo(finalFile)) {
+            val meta = JSONObject()
+                .put("sessionId", sessionId)
+                .put("lane", lane)
+                .put("segment", name)
+                .put("lines", countLines(finalFile))
+                .put("bytes", finalFile.length())
+                .put("closedAt", System.currentTimeMillis())
+                .put("attemptCount", 0)
+                .put("nextRetryAt", 0L)
+            atomicWrite(File(pending, "$name.meta.json"), meta.toString().toByteArray())
+        }
+    }
+
+    private fun nextSegmentSeq(dir: File): Int {
+        val existing = dir.listFiles { f -> f.name.startsWith("segment-") && f.name.endsWith(".jsonl") }
+        var max = 0
+        existing?.forEach {
+            val n = it.name.removePrefix("segment-").removeSuffix(".jsonl").toIntOrNull() ?: 0
+            if (n > max) max = n
+        }
+        return max + 1
+    }
+
+    // ─── Queue listing (for the uploader) ───────────────────────────────
+
+    fun listSessionIds(): List<String> = synchronized(lock) {
+        File(root, "sessions").listFiles()?.filter { it.isDirectory }?.map { it.name } ?: emptyList()
+    }
+
+    /** Pending frame metadata files whose nextRetryAt has elapsed. */
+    fun dueFrameMetas(sessionId: String, now: Long): List<File> = synchronized(lock) {
+        laneDir(sessionId, FRAMES, "pending").listFiles { f -> f.name.endsWith(".json") }
+            ?.filter { isDue(it, now) } ?: emptyList()
+    }
+
+    /** Closed, due telemetry segment meta files for a lane. */
+    fun dueSegments(sessionId: String, lane: String, now: Long): List<File> = synchronized(lock) {
+        laneDir(sessionId, lane, "pending").listFiles { f -> f.name.endsWith(".meta.json") }
+            ?.filter { isDue(it, now) } ?: emptyList()
+    }
+
+    private fun isDue(metaFile: File, now: Long): Boolean = try {
+        val obj = JSONObject(metaFile.readText())
+        obj.optLong("nextRetryAt", 0L) <= now
+    } catch (_: Exception) {
+        true
+    }
+
+    // ─── State transitions (atomic via rename) ──────────────────────────
+
+    /** Move a frame (image + json) pending→uploading. Returns the uploading json file. */
+    fun moveFrameToUploading(meta: File): File? = synchronized(lock) {
+        moveFramePair(meta, "pending", "uploading")
+    }
+
+    fun frameImageFor(metaFile: File): File? = try {
+        val obj = JSONObject(metaFile.readText())
+        File(metaFile.parentFile, obj.getString("localFile"))
+    } catch (_: Exception) {
+        null
+    }
+
+    /** Success: delete image + json. */
+    fun deleteFrame(metaFile: File): Unit = synchronized(lock) {
+        frameImageFor(metaFile)?.delete()
+        metaFile.delete()
+    }
+
+    /** Failure: bump attempt, set nextRetryAt; move to failed/, or dead/ past maxAttempts. */
+    fun failFrame(metaFile: File, maxAttempts: Int, backoffMs: Long): Unit = synchronized(lock) {
+        // Back-compat shim → treat as a server-transient failure.
+        recordServerFailure(metaFile, isFrame = true, attemptCap = maxAttempts, backoffMs = backoffMs)
+    }
+
+    // ─── Network-aware failure recording (two-counter model, section 6) ──────
+    //
+    // `networkFailureCount` — incremented on NETWORK_UNAVAILABLE; NEVER reaches dead.
+    // `serverAttemptCount`  — incremented on SERVER_TRANSIENT/SERVER_PERMANENT; the
+    //                          only counter that can reach the dead cap.
+    // A claimed item lives in `uploading/`; on every outcome below it is moved back
+    // to `pending/` (retryable) or `dead/` (terminal). This also fixes a latent bug
+    // where a transient-failed item was left stranded in `uploading/`.
+
+    /** NETWORK_UNAVAILABLE: keep fully retryable forever, no progress toward dead. */
+    fun recordNetworkFailure(metaFile: File, isFrame: Boolean, retryIntervalMs: Long): Unit = synchronized(lock) {
+        try {
+            val obj = JSONObject(metaFile.readText())
+            obj.put("networkFailureCount", obj.optInt("networkFailureCount", 0) + 1)
+            obj.put("nextRetryAt", System.currentTimeMillis() + retryIntervalMs)
+            obj.put("lastOutcome", "NETWORK_UNAVAILABLE")
+            atomicWrite(metaFile, obj.toString().toByteArray())
+            requeueToPending(metaFile, isFrame)
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.recordNetworkFailure: ${e.message}")
+        }
+    }
+
+    /** SERVER_TRANSIENT / SERVER_PERMANENT: bump serverAttemptCount; dead at `attemptCap`. */
+    fun recordServerFailure(
+        metaFile: File,
+        isFrame: Boolean,
+        attemptCap: Int,
+        backoffMs: Long,
+        permanent: Boolean = false,
+        statusCode: Int = 0,
+        bodySnippet: String = "",
+    ): Unit = synchronized(lock) {
+        try {
+            val obj = JSONObject(metaFile.readText())
+            val attempts = obj.optInt("serverAttemptCount", obj.optInt("attemptCount", 0)) + 1
+            obj.put("serverAttemptCount", attempts)
+            obj.put("attemptCount", attempts) // keep legacy field in sync for observability
+            obj.put("nextRetryAt", System.currentTimeMillis() + backoffMs)
+            obj.put("lastOutcome", if (permanent) "SERVER_PERMANENT" else "SERVER_TRANSIENT")
+            if (statusCode != 0) obj.put("lastStatus", statusCode)
+            if (bodySnippet.isNotEmpty()) obj.put("lastError", bodySnippet.take(280))
+            atomicWrite(metaFile, obj.toString().toByteArray())
+            if (attempts >= attemptCap) {
+                if (permanent) ReplayLogger.warn("outbox: poison batch -> dead (status=$statusCode): ${bodySnippet.take(120)}")
+                moveToDead(metaFile, isFrame)
+            } else {
+                requeueToPending(metaFile, isFrame)
+            }
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.recordServerFailure: ${e.message}")
+        }
+    }
+
+    private fun requeueToPending(metaFile: File, isFrame: Boolean) {
+        if (currentStateOf(metaFile) == "uploading") {
+            if (isFrame) moveFramePair(metaFile, "uploading", "pending")
+            else moveSegmentTriple(metaFile, "uploading", "pending")
+        }
+    }
+
+    private fun moveToDead(metaFile: File, isFrame: Boolean) {
+        if (isFrame) moveFramePair(metaFile, currentStateOf(metaFile), "dead")
+        else moveSegmentTriple(metaFile, currentStateOf(metaFile), "dead")
+    }
+
+    fun moveSegmentToUploading(metaFile: File): File? = synchronized(lock) {
+        moveSegmentTriple(metaFile, "pending", "uploading")
+    }
+
+    fun segmentDataFor(metaFile: File): File? = try {
+        val obj = JSONObject(metaFile.readText())
+        File(metaFile.parentFile, obj.getString("segment") + ".jsonl")
+    } catch (_: Exception) {
+        null
+    }
+
+    fun deleteSegment(metaFile: File): Unit = synchronized(lock) {
+        segmentDataFor(metaFile)?.delete()
+        metaFile.delete()
+    }
+
+    fun failSegment(metaFile: File, maxAttempts: Int, backoffMs: Long): Unit = synchronized(lock) {
+        // Back-compat shim → treat as a server-transient failure.
+        recordServerFailure(metaFile, isFrame = false, attemptCap = maxAttempts, backoffMs = backoffMs)
+    }
+
+    // ─── Recovery / cleanup ─────────────────────────────────────────────
+
+    /**
+     * On startup: move every `uploading/` item back to `pending/` (interrupted
+     * upload), and delete orphan frame images that have no sibling `.json` (a write
+     * that crashed before the commit marker landed). Also enforces age/byte caps.
+     */
+    fun recover(maskRequired: Boolean = false): Unit = synchronized(lock) {
+        try {
+            for (sessionId in listSessionIds()) {
+                // Frames: uploading → pending
+                requeueDir(laneDir(sessionId, FRAMES, "uploading"), laneDir(sessionId, FRAMES, "pending"))
+                // Drop orphan images (no .json) in pending.
+                val pending = laneDir(sessionId, FRAMES, "pending")
+                pending.listFiles { f -> !f.name.endsWith(".json") && !f.name.endsWith(".tmp") }?.forEach { img ->
+                    val base = img.name.substringBeforeLast('.')
+                    if (!File(pending, "$base.json").exists()) img.delete()
+                }
+                // Mask-policy enforcement (section 3): a committed frame with masked=false
+                // under a mask-required policy is treated as an orphan and deleted —
+                // recover() never resurrects/uploads an unmasked frame.
+                if (maskRequired) {
+                    pending.listFiles { f -> f.name.endsWith(".json") }?.forEach { meta ->
+                        val isMasked = try { JSONObject(meta.readText()).optBoolean("masked", false) } catch (_: Exception) { false }
+                        if (!isMasked) { deleteFrame(meta); maskPolicyDropCount.incrementAndGet() }
+                    }
+                }
+                // Telemetry: uploading → pending; drop any leftover .tmp.
+                for (lane in TELEMETRY_LANES) {
+                    requeueDir(laneDir(sessionId, lane, "uploading"), laneDir(sessionId, lane, "pending"))
+                }
+                // Sweep stray .tmp everywhere.
+                sweepTmp(sessionDir(sessionId))
+            }
+            enforceLimits()
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox.recover: ${e.message}")
+        }
+    }
+
+    /** Delete sessions older than maxAgeMs, then LRU-evict until under maxBytes. */
+    fun enforceLimits(): Unit = synchronized(lock) {
+        val sessions = File(root, "sessions").listFiles()?.filter { it.isDirectory } ?: return
+        val now = System.currentTimeMillis()
+        // Age policy.
+        for (dir in sessions) {
+            val started = manifestStartedAt(dir)
+            if (now - started > maxAgeMs) dir.deleteRecursively()
+        }
+        // Byte policy (LRU by manifest startedAt).
+        var total = dirSize(root)
+        if (total <= maxBytes) return
+        val live = File(root, "sessions").listFiles()?.filter { it.isDirectory }
+            ?.sortedBy { manifestStartedAt(it) } ?: return
+        for (dir in live) {
+            if (total <= maxBytes) break
+            val sz = dirSize(dir)
+            dir.deleteRecursively()
+            total -= sz
+        }
+    }
+
+    fun totalBytes(): Long = synchronized(lock) { dirSize(root) }
+
+    // ─── helpers ────────────────────────────────────────────────────────
+
+    private fun moveFramePair(metaFile: File, from: String, to: String): File? {
+        val sessionId = sessionIdOf(metaFile)
+        val img = frameImageFor(metaFile)
+        val destDir = laneDir(sessionId, FRAMES, to)
+        val destMeta = File(destDir, metaFile.name)
+        if (img != null && img.exists()) img.renameTo(File(destDir, img.name))
+        return if (metaFile.renameTo(destMeta)) destMeta else null
+    }
+
+    private fun moveSegmentTriple(metaFile: File, from: String, to: String): File? {
+        val sessionId = sessionIdOf(metaFile)
+        val lane = laneOf(metaFile)
+        val data = segmentDataFor(metaFile)
+        val destDir = laneDir(sessionId, lane, to)
+        if (data != null && data.exists()) data.renameTo(File(destDir, data.name))
+        val destMeta = File(destDir, metaFile.name)
+        return if (metaFile.renameTo(destMeta)) destMeta else null
+    }
+
+    private fun requeueDir(fromDir: File, toDir: File) {
+        fromDir.listFiles()?.forEach { f ->
+            if (f.name.endsWith(".tmp")) { f.delete(); return@forEach }
+            f.renameTo(File(toDir, f.name))
+        }
+    }
+
+    private fun sweepTmp(dir: File) {
+        dir.walkTopDown().forEach { if (it.isFile && it.name.endsWith(".tmp")) it.delete() }
+    }
+
+    private fun currentStateOf(file: File): String = file.parentFile?.name ?: "pending"
+    private fun laneOf(file: File): String = file.parentFile?.parentFile?.name ?: "events"
+    private fun sessionIdOf(file: File): String =
+        file.parentFile?.parentFile?.parentFile?.name ?: ""
+
+    private fun manifestStartedAt(sessionDir: File): Long = try {
+        JSONObject(File(sessionDir, "manifest.json").readText()).optLong("startedAt", 0L)
+    } catch (_: Exception) {
+        0L
+    }
+
+    private fun countLines(f: File): Int = try {
+        var n = 0
+        f.forEachLine { if (it.isNotEmpty()) n++ }
+        n
+    } catch (_: Exception) { 0 }
+
+    private fun dirSize(dir: File): Long =
+        dir.walkTopDown().filter { it.isFile }.map { it.length() }.sum()
+
+    /**
+     * Write to `<file>.tmp`, fsync the file, atomically rename to the final path,
+     * then fsync the PARENT DIRECTORY. The rename is not durable across a power
+     * loss / hard kill until the directory entry itself is flushed (section 5).
+     */
+    private fun atomicWrite(file: File, bytes: ByteArray) {
+        val parent = file.parentFile
+        parent?.mkdirs()
+        val tmp = File(parent, file.name + ".tmp")
+        java.io.FileOutputStream(tmp).use { out ->
+            out.write(bytes)
+            out.flush()
+            try { out.fd.sync() } catch (_: Exception) { }
+        }
+        if (!tmp.renameTo(file)) {
+            // Fallback: overwrite-rename can fail if the target exists on some FS.
+            file.delete()
+            if (!tmp.renameTo(file)) { tmp.delete(); throw java.io.IOException("rename failed: ${file.name}") }
+        }
+        if (parent != null) fsyncDir(parent)
+    }
+
+    /**
+     * fsync a directory so a freshly-renamed entry survives a hard kill. Opening a
+     * directory FD for read and calling sync() on it is the documented POSIX way;
+     * best-effort (silently ignored on FS that disallow it).
+     */
+    private fun fsyncDir(dir: File) {
+        try {
+            android.os.ParcelFileDescriptor.open(
+                dir, android.os.ParcelFileDescriptor.MODE_READ_ONLY
+            ).use { pfd ->
+                android.system.Os.fsync(pfd.fileDescriptor)
+            }
+        } catch (_: Throwable) {
+            // FS may reject directory fsync; the file fsync above is still in force.
+        }
+    }
+}