@trainstar/synchro-react-native 0.4.0-rc.1 → 0.4.0-rc.3

package/README.md

@@ -4,28 +4,78 @@ React Native TurboModule bridge for Synchro. The package wraps the native Swift
 
 ## Requirements
 
-- React Native `0.83.x`. Use `0.83.5` or later with Xcode `26.4` or later.
-- iOS `16.0+`
+- React Native `>=0.82.1 <0.89.0` and React `>=19.1.1 <20.0.0`.
+- React Native `0.88.0` requires React `19.3.0` and Node `^22.13.0 || ^24.3.0 || >=26.0.0`.
+- React Native `0.82.1` needs the [fmt 12.1.0 backport](https://trainstar.github.io/synchro/reference/support-policy/#react-native-0821-fmt-backport) with Xcode 27.
+- Applications built with Xcode 27 must adopt the [UIKit scene lifecycle](https://developer.apple.com/documentation/uikit/transitioning-to-the-uikit-scene-based-life-cycle).
+- iOS `17.0+`
 - Android `minSdk 24`
-- Node `20.19.4+`
 - Android development and CI should use JDK `17`
 
 ## Installation
 
-Install the published package only after Synchro `0.4.0-rc.1` is available. Before that,
+Install the published package only after Synchro `0.4.0-rc.3` is available. Before that,
 use the local artifact flow in
 [Client Consumption](https://trainstar.github.io/synchro/clients/consumption/).
 
 ```sh
-npm install @trainstar/synchro-react-native@0.4.0-rc.1
+npm install @trainstar/synchro-react-native@0.4.0-rc.3
 ```
 
-Before you run `pod install`, add these published Synchro `0.4.0-rc.1` dependencies to the
+Apply the delivered React Native CLI correction after each fresh npm install and
+before you run Codegen, bundle, or native build commands:
+
+```sh
+npm install --save-dev --save-exact \
+  @react-native-community/cli@20.2.0 \
+  @react-native-community/cli-platform-android@20.2.0 \
+  @react-native-community/cli-platform-ios@20.2.0
+```
+
+Pin these CLI packages before the patch command. Default React Native templates
+can install an older CLI.
+
+```sh
+node node_modules/@trainstar/synchro-react-native/tooling-patches/apply.cjs cli
+```
+
+The command resolves the CLI from the application that calls it. It verifies
+the expected `20.2.0` source and post-patch SHA-256 values. It rejects another
+version, a missing target, or a target outside the application installation.
+The correction escapes the documented `jsSrcsDir` directory before the CLI
+adds its fixed source-extension glob. It also preserves the CLI's authored
+temporary-cache suffix patterns while treating the host temporary directory as
+a literal prefix. It does not change the upstream version.
+
+Applications that use `bunyamin` 1.6.3 with `stream-json` 1.9.1 must also apply
+the delivered correction before they run that tooling:
+
+```sh
+node node_modules/@trainstar/synchro-react-native/tooling-patches/apply.cjs stream-json
+```
+
+This correction backports upstream commit
+`2f2d35bbb547306991ded6487a279154d865a358` for both Assembler writes. It
+preserves the installed `stream-json` version and its 1.9.1 reviver behavior.
+
+Library projects that run `bob build` must apply the delivered Bob correction
+after each fresh npm installation and before they build:
+
+```sh
+node node_modules/@trainstar/synchro-react-native/tooling-patches/apply.cjs bob
+```
+
+The correction replaces Bob's glob-based removal of its resolved output and
+TypeScript build-info paths with its installed `fs-extra` literal operation.
+It rejects the current project directory and paths outside it before removal.
+It does not change compilation or TypeScript generation.
+
+Before you run `pod install`, add these published Synchro `0.4.0-rc.3` dependencies to the
 application `ios/Podfile`:
 
 ```ruby
-pod 'Synchro', :git => 'https://github.com/trainstar/synchro.git', :tag => 'v0.4.0-rc.1'
-pod 'GRDB.swift', :git => 'https://github.com/groue/GRDB.swift.git', :tag => 'v7.0.0'
+pod 'Synchro', :git => 'https://github.com/trainstar/synchro.git', :tag => 'v0.4.0-rc.3'
+pod 'GRDB.swift', :git => 'https://github.com/groue/GRDB.swift.git', :tag => 'v7.8.0'
 ```
 
 Then install the pods:
@@ -214,7 +264,7 @@ When one mutation in a group does not apply, the server applies no mutation of t
 
 After a failed group with a conflict, local state holds the server row for the conflicting member. It holds local values for every other member. The SDK does not revert those local values. Use `inspectRejectedMutations()` to find them and write new intent.
 
-The atomic API requires the Synchro `0.4.0-rc.1` extension and adapter. Use this deployment order:
+The atomic API requires the Synchro `0.4.0-rc.3` extension and adapter. Use this deployment order:
 
 1. Install the `0.4.0` extension and adapter on the server.
 2. Release the client code that calls `atomicWriteTransaction()`.
@@ -244,8 +294,9 @@ The iOS schema bridge rejects malformed JSON with the existing `UNKNOWN` error c
 
 ## Development
 
-The published package accepts Node `20.19.4` or later. Repository development
-uses the Node `22.20.0` pin in `.nvmrc`.
+The published package requires Node `20.19.4` or later.
+React Native `0.88.0` adds the higher Node requirement listed above.
+Repository development uses the Node `22.20.0` pin in `.nvmrc`.
 
 ```sh
 make lint-rn

package/SynchroReactNative.podspec

@@ -10,20 +10,32 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
-  s.platforms    = { :ios => "16.0" }
+  s.platforms    = { :ios => "17.0" }
   s.source       = { :git => "https://github.com/trainstar/synchro.git", :tag => "v#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   s.private_header_files = "ios/**/*.h"
   s.compiler_flags = "-Werror=protocol"
+  s.libraries = "c++"
 
   s.dependency "Synchro", "= #{s.version}"
 
   install_modules_dependencies(s)
 
+  s.app_spec "TestHost" do |app_spec|
+    app_spec.source_files = "ios-test-host/main.m"
+    app_spec.info_plist = {
+      "UIApplicationSceneManifest" => {
+        "UIApplicationSupportsMultipleScenes" => false
+      }
+    }
+  end
+
   # Test sources stay outside source_files, so production targets never compile them.
   s.test_spec "Tests" do |test_spec|
     test_spec.source_files = "ios-tests/**/*.swift"
     test_spec.requires_app_host = true
+    test_spec.app_host_name = "SynchroReactNative/TestHost"
+    test_spec.dependency "SynchroReactNative/TestHost"
   end
 end

package/android/build.gradle

@@ -32,7 +32,7 @@ apply plugin: "kotlin-android"
 
 apply plugin: "com.facebook.react"
 
-def defaultSynchroVersion = "0.4.0-rc.1"
+def defaultSynchroVersion = "0.4.0-rc.3"
 def resolvedSynchroVersion = findProperty("synchroVersion")?.toString() ?: defaultSynchroVersion
 
 android {

package/android/src/androidTest/kotlin/com/trainstar/synchro/rn/SynchroModuleTransactionTest.kt

@@ -268,7 +268,9 @@ class SynchroModuleTransactionTest {
         assertEquals("first", rows.getMap(0)!!.getString("name"))
         val inspection = JSONObject(result.getString("inspection")!!)
         assertEquals(
-            setOf("client_state", "retained_mutations", "rejected_mutations"),
+            setOf("client_state", "retained_mutations", "rejected_mutations", "migration_journal",
+                "migration_journal_truncated", "physical_schema", "physical_schema_truncated",
+                "accepted_mutation_outcomes", "accepted_mutation_outcomes_truncated"),
             inspection.keys().asSequence().toSet(),
         )
         // bridge_items is a local table, so the mutation ledger stays empty.
@@ -405,10 +407,7 @@ class SynchroModuleTransactionTest {
 }
 
 /**
- * RN 0.83 makes ReactApplicationContext abstract. BridgeReactContext is its concrete
- * @VisibleForTesting subclass. Its legacy-architecture assertion is inert only because the pinned
- * react-android 0.83.0 debug artifact sets UNSTABLE_ENABLE_MINIFY_LEGACY_ARCHITECTURE to false.
- * This context runs no JavaScript, so these tests do not cover the bridgeless JavaScript host.
+ * This context exercises native SQLite calls. The application tests verify JavaScript dispatch.
  */
 @Suppress("DEPRECATION")
 internal fun bridgeTestContext(context: android.content.Context): BridgeReactContext = BridgeReactContext(context)
@@ -440,14 +439,14 @@ private class RecordingPromise(val name: String) : Promise {
     }
 
     override fun resolve(value: Any?) = record { resolved.add(value) }
-    override fun reject(code: String, message: String?) = rejectWith(code, null)
-    override fun reject(code: String, throwable: Throwable?) = rejectWith(code, throwable)
-    override fun reject(code: String, message: String?, throwable: Throwable?) = rejectWith(code, throwable)
+    override fun reject(code: String?, message: String?) = rejectWith(code, null)
+    override fun reject(code: String?, throwable: Throwable?) = rejectWith(code, throwable)
+    override fun reject(code: String?, message: String?, throwable: Throwable?) = rejectWith(code, throwable)
     override fun reject(throwable: Throwable) = rejectWith(null, throwable)
     override fun reject(throwable: Throwable, userInfo: WritableMap) = rejectWith(null, throwable)
-    override fun reject(code: String, userInfo: WritableMap) = rejectWith(code, null)
-    override fun reject(code: String, throwable: Throwable?, userInfo: WritableMap) = rejectWith(code, throwable)
-    override fun reject(code: String, message: String?, userInfo: WritableMap) = rejectWith(code, null)
+    override fun reject(code: String?, userInfo: WritableMap) = rejectWith(code, null)
+    override fun reject(code: String?, throwable: Throwable?, userInfo: WritableMap) = rejectWith(code, throwable)
+    override fun reject(code: String?, message: String?, userInfo: WritableMap) = rejectWith(code, null)
     override fun reject(code: String?, message: String?, throwable: Throwable?, userInfo: WritableMap?) =
         rejectWith(code, throwable)
 

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

@@ -13,6 +13,9 @@ 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.*
@@ -1127,6 +1130,16 @@ class SynchroModule(reactContext: ReactApplicationContext) :
             }
             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)
             }
@@ -1202,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)
@@ -1220,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)
@@ -1532,6 +1551,7 @@ class SynchroModule(reactContext: ReactApplicationContext) :
             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(),