@trainstar/synchro-react-native 0.3.2 → 0.4.0-rc.2

package/android/src/main/kotlin/com/trainstar/synchro/rn/SynchroModule.kt

@@ -8,10 +8,14 @@ import android.util.Base64
 import android.os.Process
 import com.facebook.react.bridge.*
 import com.trainstar.synchro.*
+import com.trainstar.synchro.inspection.ClientStateCaptureInspection
 import com.trainstar.synchro.inspection.SynchroInspection
 import com.trainstar.synchro.inspection.TransportObservationCollector
 import com.trainstar.synchro.inspection.TransportObservationSnapshot
 import com.trainstar.synchro.inspection.TransportOperationClass
+import com.trainstar.synchro.inspection.MigrationCheckpoint
+import com.trainstar.synchro.inspection.MigrationJournalInspection
+import com.trainstar.synchro.inspection.PhysicalSchemaColumnInspection
 import com.trainstar.synchro.inspection.withTransportObservation
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.*
@@ -50,11 +54,12 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         val INT64_PATTERN = Regex("^(?:0|-?[1-9][0-9]*)$")
     }
 
-    private var client: SynchroClient? = null
+    internal var client: SynchroClient? = null
+        private set
     private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
     private val lifecycleMutex = Mutex()
     private val transactionLock = Any()
-    private val sessions = ConcurrentHashMap<String, TransactionSession>()
+    internal val sessions = ConcurrentHashMap<String, TransactionSession>()
     private var acceptingTransactions = false
     private val observers = ConcurrentHashMap<String, Cancellable>()
     private val pendingAuthContinuations = ConcurrentHashMap<String, CancellableContinuation<String>>()
@@ -136,6 +141,9 @@ class SynchroModule(reactContext: ReactApplicationContext) :
             )
             is SynchroError.AlreadyStarted -> "ALREADY_STARTED" to emptyMap()
             is SynchroError.NotStarted -> "NOT_STARTED" to emptyMap()
+            is SynchroError.AtomicGroupInvalid -> "atomic_group_invalid" to mapOf(
+                "reason" to atomicGroupInvalidReasonWireValue(error.reason)
+            )
         }
     }
 
@@ -404,13 +412,7 @@ class SynchroModule(reactContext: ReactApplicationContext) :
             return
         }
         try {
-            val nativeStatements = (0 until statements.size()).map { i ->
-                val item = statements.getMap(i) ?: throw IllegalArgumentException("Invalid SQL statement at index $i")
-                val sql = item.getString("sql") ?: throw IllegalArgumentException("Missing SQL at index $i")
-                val params = if (item.hasKey("params")) item.getArray("params") else null
-                SQLStatement(sql, params?.let { parseParams(it) } ?: emptyArray())
-            }
-            val total = c.executeBatch(nativeStatements)
+            val total = c.executeBatch(parseStatements(statements))
             val map = Arguments.createMap().apply {
                 putInt("totalRowsAffected", total)
             }
@@ -422,11 +424,19 @@ class SynchroModule(reactContext: ReactApplicationContext) :
 
     // MARK: - Transactions
 
-    private class TransactionSession(val isWrite: Boolean) {
+    internal class TransactionSession(
+        val isWrite: Boolean,
+        private var beginSettlement: ((Result<String>) -> Unit)?,
+    ) {
         val operations = Channel<TransactionOp>(Channel.RENDEZVOUS)
         lateinit var job: Job
         private var abortCause: Throwable? = null
         private var terminal = false
+        private var terminalCompletion: CompletableDeferred<Unit>? = null
+
+        // A cancelled receive can drop an operation that its sender already handed over.
+        // The session owns each submitted operation until its completion settles.
+        private val outstanding = mutableSetOf<TransactionOp>()
 
         @Synchronized
         fun abort(cause: Throwable) {
@@ -436,16 +446,106 @@ class SynchroModule(reactContext: ReactApplicationContext) :
             operations.close(cause)
         }
 
+        /**
+         * Ends the session after its transaction returns. Each operation that the loop did not
+         * complete, received or not, settles with the abort cause. A rollback settles successfully.
+         */
+        @Synchronized
+        fun end() {
+            if (!terminal) {
+                terminal = true
+                operations.close()
+            }
+            outstanding.toList().forEach(::settleUnrun)
+        }
+
+        /** Submits one operation. A session that already ended settles it at once. */
+        suspend fun <T> perform(op: TransactionOp, deferred: CompletableDeferred<T>): T {
+            if (submit(op)) {
+                try {
+                    operations.send(op)
+                } catch (_: Exception) {
+                    // The channel closed or dropped the operation. The session settles it when it ends.
+                }
+            }
+            return deferred.await()
+        }
+
+        @Synchronized
+        fun submit(op: TransactionOp): Boolean {
+            if (terminal) {
+                settleUnrun(op)
+                return false
+            }
+            outstanding += op
+            return true
+        }
+
+        private fun settleUnrun(op: TransactionOp) {
+            outstanding -= op
+            when (op) {
+                is TransactionOp.Rollback -> op.deferred.complete(Unit)
+                else -> op.deferred.completeExceptionally(abortCause ?: TransactionAbortedException())
+            }
+        }
+
+        private fun release(deferred: CompletableDeferred<*>) {
+            outstanding.removeAll { it.deferred === deferred }
+        }
+
+        /**
+         * Settles begin when the transaction callback starts.
+         * A close that aborted the session earlier rejects begin instead.
+         */
+        @Synchronized
+        fun acceptBegin(txID: String) {
+            val settle = beginSettlement
+            beginSettlement = null
+            val cause = abortCause
+            if (cause != null) {
+                settle?.invoke(Result.failure(cause))
+                throw cause
+            }
+            settle?.invoke(Result.success(txID))
+        }
+
+        /** Rejects begin when the transaction fails before its callback starts. */
+        @Synchronized
+        fun rejectBegin(error: Throwable) {
+            val settle = beginSettlement ?: return
+            beginSettlement = null
+            settle(Result.failure(error))
+        }
+
+        /**
+         * Takes ownership of a received commit or rollback completion before the terminal decision.
+         * The job settles the owned completion after the database transaction ends.
+         */
         @Synchronized
-        fun completeNormally(): Boolean {
+        fun acceptTerminal(completion: CompletableDeferred<Unit>): Boolean {
+            release(completion)
+            terminalCompletion = completion
             if (terminal) return false
             terminal = true
             operations.close()
             return true
         }
 
+        /** Settles the owned terminal completion after the database transaction ends. */
+        @Synchronized
+        fun finishTerminal(error: Throwable?) {
+            val completion = terminalCompletion ?: return
+            terminalCompletion = null
+            if (error == null) {
+                completion.complete(Unit)
+            } else {
+                completion.completeExceptionally(error)
+            }
+        }
+
         @Synchronized
         fun <T> complete(deferred: CompletableDeferred<T>, value: T) {
+            release(deferred)
             val cause = abortCause
             if (cause == null) {
                 deferred.complete(value)
@@ -456,21 +556,22 @@ class SynchroModule(reactContext: ReactApplicationContext) :
 
         @Synchronized
         fun <T> completeExceptionally(deferred: CompletableDeferred<T>, error: Throwable) {
+            release(deferred)
             deferred.completeExceptionally(abortCause ?: error)
         }
     }
 
-    private sealed class TransactionOp {
-        data class Query(val sql: String, val params: Array<Any?>, val deferred: CompletableDeferred<WritableArray>) : TransactionOp()
-        data class QueryOne(val sql: String, val params: Array<Any?>, val deferred: CompletableDeferred<WritableMap?>) : TransactionOp()
-        data class Execute(val sql: String, val params: Array<Any?>, val deferred: CompletableDeferred<WritableMap>) : TransactionOp()
-        class Commit(val deferred: CompletableDeferred<Unit>) : TransactionOp()
-        class Rollback(val deferred: CompletableDeferred<Unit>) : TransactionOp()
+    internal sealed class TransactionOp {
+        abstract val deferred: CompletableDeferred<*>
+
+        class Query(val sql: String, val params: Array<Any?>, override val deferred: CompletableDeferred<WritableArray>) : TransactionOp()
+        class QueryOne(val sql: String, val params: Array<Any?>, override val deferred: CompletableDeferred<WritableMap?>) : TransactionOp()
+        class Execute(val sql: String, val params: Array<Any?>, override val deferred: CompletableDeferred<WritableMap>) : TransactionOp()
+        class Commit(override val deferred: CompletableDeferred<Unit>) : TransactionOp()
+        class Rollback(override val deferred: CompletableDeferred<Unit>) : TransactionOp()
     }
 
-    private class TransactionRollbackException(
-        val completion: CompletableDeferred<Unit>,
-    ) : Exception("rollback")
+    internal class TransactionRollbackException : Exception("rollback")
 
     private class TransactionAbortedException : Exception("Client closed during transaction")
     private class TransactionExpiredException : Exception("Transaction timed out due to inactivity")
@@ -480,12 +581,17 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         beginTransaction(isWrite = true, promise = promise)
     }
 
+    @ReactMethod
+    override fun beginAtomicWriteTransaction(promise: Promise) {
+        beginTransaction(isWrite = true, isAtomic = true, promise = promise)
+    }
+
     @ReactMethod
     override fun beginReadTransaction(promise: Promise) {
         beginTransaction(isWrite = false, promise = promise)
     }
 
-    private fun beginTransaction(isWrite: Boolean, promise: Promise) {
+    private fun beginTransaction(isWrite: Boolean, promise: Promise, isAtomic: Boolean = false) {
         val c = synchronized(transactionLock) {
             client.takeIf { acceptingTransactions }
         } ?: run {
@@ -494,28 +600,31 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         }
 
         val txID = UUID.randomUUID().toString()
-        val session = TransactionSession(isWrite)
+        val session = TransactionSession(isWrite) { result ->
+            result.fold(
+                onSuccess = { promise.resolve(it) },
+                onFailure = { rejectWithError(promise, it) },
+            )
+        }
 
         val job = scope.launch(start = CoroutineStart.LAZY) {
-            var finalDeferred: CompletableDeferred<Unit>? = null
             try {
                 if (isWrite) {
-                    c.writeTransaction { transaction ->
-                        finalDeferred = runTransactionLoop(
+                    val body: (ApplicationTransaction) -> Unit = { transaction ->
+                        runTransactionLoop(
                             txID = txID,
                             session = session,
-                            promise = promise,
                             query = transaction::query,
                             queryOne = transaction::queryOne,
                             execute = transaction::execute,
                         )
                     }
+                    if (isAtomic) c.atomicWriteTransaction(body) else c.writeTransaction(body)
                 } else {
                     c.readTransaction { transaction ->
-                        finalDeferred = runTransactionLoop(
+                        runTransactionLoop(
                             txID = txID,
                             session = session,
-                            promise = promise,
                             query = transaction::query,
                             queryOne = transaction::queryOne,
                             execute = { _, _ ->
@@ -524,17 +633,19 @@ class SynchroModule(reactContext: ReactApplicationContext) :
                         )
                     }
                 }
-                finalDeferred?.complete(Unit)
+                session.finishTerminal(null)
             } catch (e: TimeoutCancellationException) {
                 val timeout = TransactionExpiredException()
                 session.abort(timeout)
-                finalDeferred?.completeExceptionally(timeout)
+                session.finishTerminal(timeout)
             } catch (e: TransactionRollbackException) {
-                e.completion.complete(Unit)
+                session.finishTerminal(null)
             } catch (e: Exception) {
-                finalDeferred?.completeExceptionally(e)
+                // Acquisition can fail before the callback settles begin.
+                session.rejectBegin(e)
+                session.finishTerminal(e)
             } finally {
-                session.completeNormally()
+                session.end()
                 sessions.remove(txID, session)
             }
         }
@@ -555,16 +666,14 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         job.start()
     }
 
-    private fun runTransactionLoop(
+    internal fun runTransactionLoop(
         txID: String,
         session: TransactionSession,
-        promise: Promise,
         query: (String, Array<out Any?>?) -> List<Row>,
         queryOne: (String, Array<out Any?>?) -> Row?,
         execute: (String, Array<out Any?>?) -> ExecResult,
-    ): CompletableDeferred<Unit>? {
-        promise.resolve(txID)
-        var finalDeferred: CompletableDeferred<Unit>? = null
+    ) {
+        session.acceptBegin(txID)
         runBlocking {
             transactionLoop@ while (true) {
                 val result = withTimeout(5000) { session.operations.receiveCatching() }
@@ -604,19 +713,16 @@ class SynchroModule(reactContext: ReactApplicationContext) :
                         }
                     }
                     is TransactionOp.Commit -> {
-                        finalDeferred = op.deferred
-                        if (!session.completeNormally()) throw TransactionAbortedException()
+                        if (!session.acceptTerminal(op.deferred)) throw TransactionAbortedException()
                         break@transactionLoop
                     }
                     is TransactionOp.Rollback -> {
-                        finalDeferred = op.deferred
-                        if (!session.completeNormally()) throw TransactionAbortedException()
-                        throw TransactionRollbackException(op.deferred)
+                        if (!session.acceptTerminal(op.deferred)) throw TransactionAbortedException()
+                        throw TransactionRollbackException()
                     }
                 }
             }
         }
-        return finalDeferred
     }
 
     @ReactMethod
@@ -628,8 +734,7 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         scope.launch {
             try {
                 val deferred = CompletableDeferred<WritableArray>()
-                session.operations.send(TransactionOp.Query(sql, parseParams(params), deferred))
-                promise.resolve(deferred.await())
+                promise.resolve(session.perform(TransactionOp.Query(sql, parseParams(params), deferred), deferred))
             } catch (e: Exception) {
                 rejectWithError(promise, e)
             }
@@ -645,8 +750,7 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         scope.launch {
             try {
                 val deferred = CompletableDeferred<WritableMap?>()
-                session.operations.send(TransactionOp.QueryOne(sql, parseParams(params), deferred))
-                promise.resolve(deferred.await())
+                promise.resolve(session.perform(TransactionOp.QueryOne(sql, parseParams(params), deferred), deferred))
             } catch (e: Exception) {
                 rejectWithError(promise, e)
             }
@@ -666,8 +770,7 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         scope.launch {
             try {
                 val deferred = CompletableDeferred<WritableMap>()
-                session.operations.send(TransactionOp.Execute(sql, parseParams(params), deferred))
-                promise.resolve(deferred.await())
+                promise.resolve(session.perform(TransactionOp.Execute(sql, parseParams(params), deferred), deferred))
             } catch (e: Exception) {
                 rejectWithError(promise, e)
             }
@@ -683,8 +786,7 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         scope.launch {
             try {
                 val deferred = CompletableDeferred<Unit>()
-                session.operations.send(TransactionOp.Commit(deferred))
-                deferred.await()
+                session.perform(TransactionOp.Commit(deferred), deferred)
                 promise.resolve(null)
             } catch (e: Exception) {
                 rejectWithError(promise, e)
@@ -700,12 +802,12 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         }
         scope.launch {
             try {
+                // A session that ends before it runs this rollback settles it successfully.
                 val deferred = CompletableDeferred<Unit>()
-                session.operations.send(TransactionOp.Rollback(deferred))
-                deferred.await()
+                session.perform(TransactionOp.Rollback(deferred), deferred)
                 promise.resolve(null)
             } catch (e: Exception) {
-                promise.resolve(null) // Best-effort
+                rejectWithError(promise, e)
             }
         }
     }
@@ -972,6 +1074,19 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    @ReactMethod
+    override fun inspectRetainedMutationRecords(promise: Promise) {
+        val c = client ?: run {
+            promise.reject("NOT_CONNECTED", "Client not initialized")
+            return
+        }
+        try {
+            promise.resolve(JSONArray(c.inspectRetainedMutationRecords().map(::retainedMutationJson)).toString())
+        } catch (e: Exception) {
+            rejectWithError(promise, e)
+        }
+    }
+
     @ReactMethod
     override fun inspectRejectedMutations(promise: Promise) {
         val c = client ?: run {
@@ -986,73 +1101,61 @@ class SynchroModule(reactContext: ReactApplicationContext) :
     }
 
     @ReactMethod
-    override fun inspectClientState(promise: Promise) {
+    override fun inspectRejectedMutationRecords(promise: Promise) {
         val c = client ?: run {
             promise.reject("NOT_CONNECTED", "Client not initialized")
             return
         }
         try {
-            val inspection = SynchroInspection(c)
-            val capture = inspection.captureState(maximumRecords = 512)
-            val schema: Any = capture.schema?.let {
-                JSONObject().put("version", it.version).put("hash", it.hash)
-            } ?: JSONObject.NULL
-            val scopeStates = JSONArray(capture.scopeStates.map { value ->
-                JSONObject().apply {
-                    put("scope_id", value.scopeID)
-                    put("cursor", value.cursor ?: JSONObject.NULL)
-                    put("checksum", value.checksum ?: JSONObject.NULL)
-                    put("local_checksum", value.localChecksum)
-                    put("generation", value.generation)
-                }
-            })
-            val scopeRows = JSONArray(capture.scopeRows.map { value ->
-                JSONObject().apply {
-                    put("scope_id", value.scopeID)
-                    put("table_name", value.tableName)
-                    put("record_id", value.recordID)
-                    put("checksum", value.checksum)
-                    put("generation", value.generation)
-                }
-            })
-            val attempts = JSONArray(capture.rebuildAttempts.map { value ->
-                JSONObject().apply {
-                    put("scope_id", value.scopeID)
-                    put("rebuild_id", value.rebuildID)
-                    put("client_generation", value.clientGeneration)
-                    put("schema_version", value.schemaVersion)
-                    put("schema_hash", value.schemaHash)
-                    put("generation", value.generation)
-                    put("cursor", value.cursor ?: JSONObject.NULL)
-                    put("page_limit", value.pageLimit)
+            promise.resolve(JSONArray(c.inspectRejectedMutationRecords().map(::retainedRejectionJson)).toString())
+        } catch (e: Exception) {
+            rejectWithError(promise, e)
+        }
+    }
+
+    /** Reads client state, retained details, and the requested application rows from one read-only snapshot. */
+    @ReactMethod
+    override fun inspectClientStateSnapshot(rowStatements: ReadableArray, promise: Promise) {
+        val c = client ?: run {
+            promise.reject("NOT_CONNECTED", "Client not initialized")
+            return
+        }
+        try {
+            val statements = parseStatements(rowStatements)
+            val rows = mutableListOf<Row>()
+            val snapshot = SynchroInspection(c).captureSnapshot(maximumRecords = 512) { _, transaction ->
+                for (statement in statements) {
+                    rows += transaction.query(statement.sql, statement.params)
                 }
+            }
+            val inspection = JSONObject().apply {
+                put("client_state", clientStateJson(snapshot.capture))
+                put("migration_journal", snapshot.capture.migrationJournal?.let {
+                    JSONObject(Json.encodeToString(MigrationJournalInspection.serializer(), it))
+                } ?: JSONObject.NULL)
+                put("migration_journal_truncated", snapshot.capture.migrationJournalTruncated)
+                put("physical_schema", JSONArray(snapshot.capture.physicalSchema.map {
+                    JSONObject(Json.encodeToString(PhysicalSchemaColumnInspection.serializer(), it))
+                }))
+                put("physical_schema_truncated", snapshot.capture.physicalSchemaTruncated)
+                put("accepted_mutation_outcomes", JSONObject(snapshot.capture.acceptedMutationOutcomes))
+                put("accepted_mutation_outcomes_truncated", snapshot.capture.acceptedMutationOutcomesTruncated)
+                put("retained_mutations", snapshot.retainedMutations?.let { JSONArray(it.map(::retainedMutationJson)) } ?: JSONObject.NULL)
+                put("rejected_mutations", snapshot.rejectedMutations?.let { JSONArray(it.map(::retainedRejectionJson)) } ?: JSONObject.NULL)
+            }
+            promise.resolve(Arguments.createMap().apply {
+                putString("inspection", inspection.toString())
+                putArray("applicationRows", rowsToWritableArray(rows))
             })
-            promise.resolve(JSONObject().apply {
-                put("schema", schema)
-                put("scope_states", scopeStates)
-                put("scope_rows", scopeRows)
-                put("rebuild_attempts", attempts)
-                put("application_row_count", capture.applicationRowCount)
-                put("mutation_ledger_count", capture.mutationLedgerCount)
-                put("mutation_outcome_count", capture.mutationOutcomeCount)
-                put("sealed_batch_count", capture.sealedBatchCount)
-                put("rejected_mutation_count", capture.rejectedMutationCount)
-                put("scope_state_count", capture.scopeStateCount)
-                put("scope_row_count", capture.scopeRowCount)
-                put("provenance_count", capture.provenanceCount)
-                put("row_metadata_count", capture.rowMetadataCount)
-                put("rebuild_attempt_count", capture.rebuildAttemptCount)
-                put("rebuild_receipt_count", capture.rebuildReceiptCount)
-                put(
-                    "provenance_maintenance_work_cursor",
-                    capture.provenanceMaintenanceWorkCursor.toString(),
-                )
-            }.toString())
         } catch (error: Exception) {
             rejectWithError(promise, error)
         }
     }
 
+    /**
+     * Reads one record's row metadata and every rebuild receipt. The inspection snapshot bounds
+     * row metadata, so a durable proof reads its identity directly.
+     */
     @ReactMethod
     override fun inspectDurableState(tableName: String, recordID: String, promise: Promise) {
         val c = client ?: run {
@@ -1112,7 +1215,8 @@ class SynchroModule(reactContext: ReactApplicationContext) :
     override fun armTransportPause(operationClass: String, promise: Promise) {
         try {
             val collector = transportObservationCollector ?: error("Transport observation is not configured")
-            collector.armPause(transportOperationClass(operationClass))
+            val checkpoint = MigrationCheckpoint.fromWire(operationClass)
+            if (checkpoint != null) collector.armPause(checkpoint) else collector.armPause(transportOperationClass(operationClass))
             promise.resolve(null)
         } catch (error: Exception) {
             rejectWithError(promise, error)
@@ -1130,7 +1234,12 @@ class SynchroModule(reactContext: ReactApplicationContext) :
                         timeoutMs % 1.0 == 0.0,
                 ) { "Transport pause timeout is invalid" }
                 val collector = transportObservationCollector ?: error("Transport observation is not configured")
-                collector.awaitPause(transportOperationClass(operationClass), timeoutMs.toLong())
+                val checkpoint = MigrationCheckpoint.fromWire(operationClass)
+                if (checkpoint != null) {
+                    collector.awaitPause(checkpoint, timeoutMs.toLong())
+                } else {
+                    collector.awaitPause(transportOperationClass(operationClass), timeoutMs.toLong())
+                }
                 promise.resolve(null)
             } catch (error: Exception) {
                 rejectWithError(promise, error)
@@ -1392,6 +1501,88 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         })
     }
 
+    private fun clientStateJson(capture: ClientStateCaptureInspection): JSONObject {
+        val schema: Any = capture.schema?.let {
+            JSONObject().put("version", it.version).put("hash", it.hash)
+        } ?: JSONObject.NULL
+        val scopeStates = JSONArray(capture.scopeStates.map { value ->
+            JSONObject().apply {
+                put("scope_id", value.scopeID)
+                put("cursor", value.cursor ?: JSONObject.NULL)
+                put("checksum", value.checksum ?: JSONObject.NULL)
+                put("local_checksum", value.localChecksum)
+                put("generation", value.generation)
+            }
+        })
+        val scopeRows = JSONArray(capture.scopeRows.map { value ->
+            JSONObject().apply {
+                put("scope_id", value.scopeID)
+                put("table_name", value.tableName)
+                put("record_id", value.recordID)
+                put("checksum", value.checksum)
+                put("generation", value.generation)
+            }
+        })
+        val attempts = JSONArray(capture.rebuildAttempts.map { value ->
+            JSONObject().apply {
+                put("scope_id", value.scopeID)
+                put("rebuild_id", value.rebuildID)
+                put("client_generation", value.clientGeneration)
+                put("schema_version", value.schemaVersion)
+                put("schema_hash", value.schemaHash)
+                put("generation", value.generation)
+                put("cursor", value.cursor ?: JSONObject.NULL)
+                put("page_limit", value.pageLimit)
+            }
+        })
+        return JSONObject().apply {
+            put("schema", schema)
+            put("scope_states", scopeStates)
+            put("scope_rows", scopeRows)
+            put("rebuild_attempts", attempts)
+            put("application_row_count", capture.applicationRowCount)
+            put("mutation_ledger_count", capture.mutationLedgerCount)
+            put("mutation_outcome_count", capture.mutationOutcomeCount)
+            put("sealed_batch_count", capture.sealedBatchCount)
+            put("rejected_mutation_count", capture.rejectedMutationCount)
+            put("scope_state_count", capture.scopeStateCount)
+            put("scope_row_count", capture.scopeRowCount)
+            put("provenance_count", capture.provenanceCount)
+            put("row_metadata_count", capture.rowMetadataCount)
+            put("rebuild_attempt_count", capture.rebuildAttemptCount)
+            put("rebuild_receipt_count", capture.rebuildReceiptCount)
+            put("capture_overflowed", capture.overflowed)
+            put(
+                "provenance_maintenance_work_cursor",
+                capture.provenanceMaintenanceWorkCursor.toString(),
+            )
+        }
+    }
+
+    private fun parseStatements(statements: ReadableArray): List<SQLStatement> =
+        (0 until statements.size()).map { i ->
+            val item = statements.getMap(i) ?: throw IllegalArgumentException("Invalid SQL statement at index $i")
+            val sql = item.getString("sql") ?: throw IllegalArgumentException("Missing SQL at index $i")
+            val params = if (item.hasKey("params")) item.getArray("params") else null
+            SQLStatement(sql, params?.let { parseParams(it) } ?: emptyArray())
+        }
+
+    private fun retainedMutationJson(value: RetainedMutationInspection): JSONObject = when (value) {
+        is RetainedMutationInspection.Current -> pendingMutationJson(value.mutation).put("representation", "current")
+        is RetainedMutationInspection.Legacy -> JSONObject().apply {
+            put("representation", "legacy")
+            put("mutationID", value.mutation.mutationID)
+            put("localOrder", value.mutation.localOrder)
+            put("tableName", value.mutation.tableName)
+            put("recordID", value.mutation.recordID)
+            put("operation", operationWireValue(value.mutation.operation))
+            put("baseVersion", value.mutation.baseVersion ?: JSONObject.NULL)
+            put("clientVersion", value.mutation.clientVersion)
+            put("status", localMutationStatusWireValue(value.mutation.status))
+            put("sourceKind", value.mutation.sourceKind)
+        }
+    }
+
     private fun pendingMutationJson(mutation: PendingMutationInspection): JSONObject = JSONObject().apply {
         put("mutationID", mutation.mutationID)
         put("localOrder", mutation.localOrder)
@@ -1422,6 +1613,23 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         }))
     }
 
+    private fun retainedRejectionJson(value: RetainedRejectionInspection): JSONObject = when (value) {
+        is RetainedRejectionInspection.Current -> rejectedMutationJson(value.rejection).put("representation", "current")
+        is RetainedRejectionInspection.Legacy -> JSONObject().apply {
+            put("representation", "legacy")
+            put("mutationID", value.rejection.mutationID)
+            put("tableName", value.rejection.tableName)
+            put("recordID", value.rejection.recordID)
+            put("status", mutationStatusWireValue(value.rejection.status))
+            put("code", mutationRejectionCodeWireValue(value.rejection.code))
+            put("message", value.rejection.message ?: JSONObject.NULL)
+            put("serverRowJSON", value.rejection.serverRowJSON ?: JSONObject.NULL)
+            put("serverVersion", value.rejection.serverVersion ?: JSONObject.NULL)
+            put("createdAt", value.rejection.createdAt)
+            put("updatedAt", value.rejection.updatedAt)
+        }
+    }
+
     private fun rejectedMutationJson(mutation: RejectedMutationInspection): JSONObject = JSONObject().apply {
         put("mutationID", mutation.mutationID)
         put("tableName", mutation.tableName)
@@ -1476,6 +1684,14 @@ class SynchroModule(reactContext: ReactApplicationContext) :
         MutationRejectionCode.POLICY_REJECTED -> "policy_rejected"
         MutationRejectionCode.VALIDATION_FAILED -> "validation_failed"
         MutationRejectionCode.TABLE_NOT_SYNCED -> "table_not_synced"
+        MutationRejectionCode.ATOMIC_BATCH_REJECTED -> "atomic_batch_rejected"
+    }
+
+    private fun atomicGroupInvalidReasonWireValue(reason: AtomicGroupInvalidReason): String = when (reason) {
+        AtomicGroupInvalidReason.DELETE_FOLLOWED_BY_WRITE -> "deleteFollowedByWrite"
+        AtomicGroupInvalidReason.TOO_MANY_MUTATIONS -> "tooManyMutations"
+        AtomicGroupInvalidReason.MUTATION_TOO_LARGE -> "mutationTooLarge"
+        AtomicGroupInvalidReason.REQUEST_TOO_LARGE -> "requestTooLarge"
     }
 
     private fun jsonObjectToJsonObject(value: JsonObject): JSONObject {