react-native-update 10.60.0 → 10.61.0

package/ios/RCTPushy/RCTPushyInstaller.mm

@@ -7,6 +7,7 @@
 #include "../../cpp/patch_core/archive_limits.h"
 #include "../../cpp/patch_core/archive_patch_core.h"
 #include "../../cpp/patch_core/digest.h"
+#include "../../cpp/patch_core/native_texts.h"
 #include "../../cpp/patch_core/error_codes.h"
 #include "../../cpp/patch_core/install_record.h"
 #include "../../cpp/patch_core/patch_core.h"
@@ -17,22 +18,22 @@
 static NSString *const SOURCE_PATCH_NAME = @"__diff.json";
 static NSString *const ERROR_FILE_OPERATION = @"file operation error";
 
-// Protocol strings stored encoded (RCTPushyRevealText) so they do not appear
-// as plain binary strings; decoded on first use.
+// Protocol strings stored encoded (cpp/patch_core/native_texts.h) so they do
+// not appear as plain binary strings; decoded on first use.
 static NSString *BUNDLE_PATCH_NAME(void) {
-    static NSString *value = RCTPushyRevealText("3319f0d4b6c56a502c3b10fcdca0de7d4b3307e9");
+    static NSString *value = PushyFromStdString(pushy::texts::BundleDeltaEntry());
     return value;
 }
 PUSHY_HIDDEN NSString *PushyOptionUrlKey(void) {
-    static NSString *value = RCTPushyRevealText("2f07f0d0ba8e5d572e");
+    static NSString *value = PushyFromStdString(pushy::texts::OptionUrlKey());
     return value;
 }
 static NSString *PushyIpaDeltaSuffix(void) {
-    static NSString *value = RCTPushyRevealText("741ee4d0e09b69512137");
+    static NSString *value = PushyFromStdString(pushy::texts::PackageDeltaSuffix());
     return value;
 }
 static NSString *PushyPpkDeltaSuffix(void) {
-    static NSString *value = RCTPushyRevealText("7407e4dae09b69512137");
+    static NSString *value = PushyFromStdString(pushy::texts::PpkDeltaSuffix());
     return value;
 }
 
@@ -109,8 +110,23 @@ static NSError *PushyEnsureFreeSpace(NSString *path, long long bytesToWrite) {
     }
 }
 
+// The delegate runs inside SSZipArchive's C extraction loop, which an
+// exception must not unwind through (CODE_AUDIT 4.4): a check that throws is
+// a violation like any other.
+- (void)check:(void (NS_NOESCAPE ^)(void))block {
+    @try {
+        block();
+    } @catch (...) {
+        if (self.violation == nil) {
+            self.violation = PushyCaughtReason(@"archive check failed");
+        }
+    }
+}
+
 - (void)zipArchiveWillUnzipArchiveAtPath:(NSString *)path zipInfo:(unz_global_info)zipInfo {
-    [self recordStatus:pushy::archive_limits::CheckEntryCount((long long)zipInfo.number_entry)];
+    [self check:^{
+        [self recordStatus:pushy::archive_limits::CheckEntryCount((long long)zipInfo.number_entry)];
+    }];
 }
 
 - (BOOL)zipArchiveShouldUnzipFileAtIndex:(NSInteger)fileIndex
@@ -123,9 +139,11 @@ static NSError *PushyEnsureFreeSpace(NSString *path, long long bytesToWrite) {
     // Unix mode bits travel in the high 16 bits of the external attributes
     // (the same field SSZipArchive keys its own symlink branch on).
     BOOL symlink = ((fileInfo.external_fa >> 16) & S_IFMT) == S_IFLNK;
-    [self recordStatus:_accumulator->Accept((long long)fileInfo.uncompressed_size,
-                                            (long long)fileInfo.compressed_size,
-                                            symlink, std::string())];
+    [self check:^{
+        [self recordStatus:self->_accumulator->Accept((long long)fileInfo.uncompressed_size,
+                                                      (long long)fileInfo.compressed_size,
+                                                      symlink, std::string())];
+    }];
     return self.violation == nil;
 }
 
@@ -152,9 +170,11 @@ static NSError *PushyEnsureFreeSpace(NSString *path, long long bytesToWrite) {
     }
     NSString *name = [[components subarrayWithRange:NSMakeRange(base, components.count - base)]
                       componentsJoinedByString:@"/"];
-    if (pushy::archive_limits::IsReservedEntryName(PushyToStdString(name))) {
-        self.violation = [NSString stringWithFormat:@"archive contains reserved entry %@", name];
-    }
+    [self check:^{
+        if (pushy::archive_limits::IsReservedEntryName(PushyToStdString(name))) {
+            self.violation = [NSString stringWithFormat:@"archive contains reserved entry %@", name];
+        }
+    }];
 }
 
 @end
@@ -326,6 +346,23 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
       options:(NSDictionary *)options
      progress:(void (^)(long long, long long))progress
      callback:(void (^)(NSError *error))callback
+{
+    // The caller is an RN method or the native round; neither survives an
+    // exception (CODE_AUDIT 4.4). This catch only covers the checks before
+    // the download registers; after that, failures settle every waiter
+    // through its completion instead.
+    @try {
+        [self fetchUnguarded:type options:options progress:progress callback:callback];
+    } @catch (...) {
+        callback(PushyErrorWithCode(pushy::error_codes::kFileOperationFailed,
+                                    PushyCaughtReason(ERROR_FILE_OPERATION)));
+    }
+}
+
++ (void)fetchUnguarded:(PushyType)type
+               options:(NSDictionary *)options
+              progress:(void (^)(long long, long long))progress
+              callback:(void (^)(NSError *error))callback
 {
     NSString *updateUrl = PushyOptionString(options, PushyOptionUrlKey());
     NSString *hash = PushyOptionString(options, @"hash");
@@ -368,15 +405,6 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
     void (^deferredStart)(void) = ^{
         [self fetch:type options:options progress:progress callback:callback];
     };
-    PushyDownloadRegistration registration = PushyRegisterDownload(
-        hash, type, deadlineUptime, callback, progress, deferredStart);
-    if (registration != PushyDownloadRegistrationOwner) {
-        RCTLogInfo(
-            @"RCTPushy -- %@ in-flight download for %@",
-            registration == PushyDownloadRegistrationJoined ? @"join" : @"defer",
-            hash);
-        return;
-    }
 
     NSString *zipFilePath = [dir stringByAppendingPathComponent:
         [hash stringByAppendingString:PushyArchiveExtension(type)]];
@@ -394,7 +422,13 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
     // to the download root itself.
     void (^completion)(NSError *) = ^(NSError *error) {
         dispatch_async(PushyFileQueue(), ^{
-            NSError *finalError = error ?: PushyPromoteStagingDir(hash, artifactSha256);
+            __block NSError *finalError = error;
+            if (finalError == nil && !PushyGuard(@"promote", ^{
+                    finalError = PushyPromoteStagingDir(hash, artifactSha256);
+                })) {
+                finalError = PushyErrorWithCode(pushy::error_codes::kFileOperationFailed,
+                                                ERROR_FILE_OPERATION);
+            }
             if (finalError != nil) {
                 [[NSFileManager defaultManager] removeItemAtPath:PushyStagingDir(hash) error:nil];
             }
@@ -402,32 +436,52 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
         });
     };
 
-    RCTLogInfo(@"RCTPushy -- download file %@", updateUrl);
-    NSTimeInterval timeoutSeconds = deadlineUptime - PushyMonotonicNow();
-    if (timeoutSeconds <= 0) {
-        completion(deadlineExpired());
+    PushyDownloadRegistration registration = PushyRegisterDownload(
+        hash, type, deadlineUptime, callback, progress, deferredStart);
+    if (registration != PushyDownloadRegistrationOwner) {
+        RCTLogInfo(
+            @"RCTPushy -- %@ in-flight download for %@",
+            registration == PushyDownloadRegistrationJoined ? @"join" : @"defer",
+            hash);
         return;
     }
-    [RCTPushyDownloader download:updateUrl
-                        savePath:zipFilePath
-                 timeoutInterval:timeoutSeconds
-                 progressHandler:^(long long receivedBytes, long long totalBytes) {
-        PushyReportDownloadProgress(hash, receivedBytes, totalBytes);
-    } completionHandler:^(NSString *path, NSError *error) {
-        if (error != nil) {
-            completion(error);
+
+    // Registered: every waiter now settles through `completion`.
+    @try {
+        RCTLogInfo(@"RCTPushy -- download file %@", updateUrl);
+        NSTimeInterval timeoutSeconds = deadlineUptime - PushyMonotonicNow();
+        if (timeoutSeconds <= 0) {
+            completion(deadlineExpired());
             return;
         }
-        dispatch_async(PushyFileQueue(), ^{
-            artifactSha256 = PushyFromStdString(
-                pushy::digest::Sha256File(PushyToStdString(zipFilePath)));
-        });
-        [self unzipDownloadedPackage:zipFilePath
-                                hash:hash
-                                type:type
-                          originHash:originHash
-                            callback:completion];
-    }];
+        [RCTPushyDownloader download:updateUrl
+                            savePath:zipFilePath
+                     timeoutInterval:timeoutSeconds
+                     progressHandler:^(long long receivedBytes, long long totalBytes) {
+            PushyReportDownloadProgress(hash, receivedBytes, totalBytes);
+        } completionHandler:^(NSString *path, NSError *error) {
+            if (error != nil) {
+                completion(error);
+                return;
+            }
+            dispatch_async(PushyFileQueue(), ^{
+                // A digest that throws is recorded as none, like an unreadable
+                // archive.
+                PushyGuard(@"archive digest", ^{
+                    artifactSha256 = PushyFromStdString(
+                        pushy::digest::Sha256File(PushyToStdString(zipFilePath)));
+                });
+            });
+            [self unzipDownloadedPackage:zipFilePath
+                                    hash:hash
+                                    type:type
+                              originHash:originHash
+                                callback:completion];
+        }];
+    } @catch (...) {
+        completion(PushyErrorWithCode(pushy::error_codes::kFileOperationFailed,
+                                      PushyCaughtReason(ERROR_FILE_OPERATION)));
+    }
 }
 
 + (void)unzipDownloadedPackage:(NSString *)zipFilePath
@@ -448,11 +502,11 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
             }
             @try {
                 [self finishDownloadedPackage:hash type:type originHash:originHash callback:callback];
-            } @catch (NSException *exception) {
+            } @catch (...) {
                 // An uncaught exception in a GCD block is fatal (and would
                 // trip the crash rescue); a bad package is a PATCH_FAILED.
                 callback(PushyErrorWithCode(pushy::error_codes::kDeltaFailed,
-                                            exception.reason ?: @"delta failed"));
+                                            PushyCaughtReason(@"delta failed")));
             }
         });
     }];
@@ -536,120 +590,109 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
       completionHandler:(void (^)(NSError *error))completionHandler
 {
     dispatch_async(PushyFileQueue(), ^{
-        NSFileManager *fileManager = [NSFileManager defaultManager];
-        if ([fileManager fileExistsAtPath:destination]) {
-            [fileManager removeItemAtPath:destination error:nil];
-        }
-
-        // Resource caps before the first byte is extracted
-        // (cpp/patch_core/archive_limits.h). SSZipArchive only exposes the
-        // entry count up front (zipArchiveWillUnzipArchiveAtPath:zipInfo:),
-        // not the uncompressed total, so the disk check uses a 2x-archive
-        // heuristic; the guard enforces the exact caps entry by entry.
-        long long archiveBytes = RCTPushyFileSize(path);
-        NSError *preflight = nil;
-        if (archiveBytes > pushy::archive_limits::kMaxArchiveBytes) {
-            preflight = PushyErrorWithCode(pushy::error_codes::kDeltaFailed,
-                [NSString stringWithFormat:@"archive too large: %lld bytes", archiveBytes]);
-        } else {
-            preflight = PushyEnsureFreeSpace(destination, MAX(0LL, archiveBytes) * 2);
-        }
-        if (preflight != nil) {
+        @try {
+            [self unzipFileUnguardedAtPath:path
+                             toDestination:destination
+                         completionHandler:completionHandler];
+        } @catch (...) {
+            // The archive limits run inside the extraction (CODE_AUDIT 4.4).
             RCTPushyDiscardArchive(path);
-            completionHandler(preflight);
-            return;
+            completionHandler(PushyErrorWithCode(pushy::error_codes::kDeltaFailed,
+                                                 PushyCaughtReason(@"unzip failed")));
         }
-
-        PushyUnzipGuard *guard = [[PushyUnzipGuard alloc] initWithArchiveBytes:archiveBytes
-                                                                    destination:destination];
-        // preserveAttributes:NO — the archive's mode/mtime bits have no use
-        // here and are one less thing a hostile package controls.
-        [SSZipArchive unzipFileAtPath:path
-                        toDestination:destination
-                   preserveAttributes:NO
-                            overwrite:YES
-                       nestedZipLevel:0
-                             password:nil
-                                error:nil
-                             delegate:guard
-                      progressHandler:nil
-                    completionHandler:^(NSString *archivePath, BOOL succeeded, NSError *error) {
-            // The resume sidecar dies with its archive (§11.4): whether the
-            // unzip consumed it or classified it as poisoned, nothing must
-            // survive to vouch for bytes that are gone.
-            RCTPushyDiscardArchive(archivePath);
-
-            NSError *unzipError = error;
-            if (guard.violation != nil) {
-                unzipError = PushyErrorWithCode(pushy::error_codes::kDeltaFailed, guard.violation);
-            } else if (!succeeded && unzipError == nil) {
-                unzipError = PushyErrorWithCode(pushy::error_codes::kDeltaFailed, @"unzip failed");
-            } else if (unzipError != nil && unzipError.userInfo[RCTPushyErrorCodeKey] == nil) {
-                // SSZipArchive's own NSError (corrupt zip, bad magic, ...) has
-                // no stable code; without one, fetchPackage's fallback would
-                // classify it as DOWNLOAD_FAILED even though the download
-                // succeeded — keep the classification deterministic.
-                unzipError = PushyErrorWithCode(pushy::error_codes::kDeltaFailed,
-                                                unzipError.localizedDescription ?: @"unzip failed");
-            }
-            completionHandler(unzipError);
-        }];
     });
 }
 
-+ (BOOL)switchVersion:(NSString *)hash error:(NSError **)error
++ (void)unzipFileUnguardedAtPath:(NSString *)path
+                   toDestination:(NSString *)destination
+               completionHandler:(void (^)(NSError *error))completionHandler
 {
-    if (!PushyIsSafePathComponent(hash)) {
-        if (error != NULL) {
-            *error = PushyErrorWithCode(pushy::error_codes::kInvalidOptions, ERROR_OPTIONS);
-        }
-        return NO;
+    NSFileManager *fileManager = [NSFileManager defaultManager];
+    if ([fileManager fileExistsAtPath:destination]) {
+        [fileManager removeItemAtPath:destination error:nil];
+    }
+
+    // Resource caps before the first byte is extracted
+    // (cpp/patch_core/archive_limits.h). SSZipArchive only exposes the
+    // entry count up front (zipArchiveWillUnzipArchiveAtPath:zipInfo:),
+    // not the uncompressed total, so the disk check uses a 2x-archive
+    // heuristic; the guard enforces the exact caps entry by entry.
+    long long archiveBytes = RCTPushyFileSize(path);
+    NSError *preflight = nil;
+    if (archiveBytes > pushy::archive_limits::kMaxArchiveBytes) {
+        preflight = PushyErrorWithCode(pushy::error_codes::kDeltaFailed,
+            [NSString stringWithFormat:@"archive too large: %lld bytes", archiveBytes]);
+    } else {
+        preflight = PushyEnsureFreeSpace(destination, MAX(0LL, archiveBytes) * 2);
+    }
+    if (preflight != nil) {
+        RCTPushyDiscardArchive(path);
+        completionHandler(preflight);
+        return;
     }
 
-    // Same gate as Android and Harmony (install_record::CheckActivation):
-    // only a version this SDK recorded as completely installed, whose
-    // record's bundle digest matches the bytes on disk, may be activated.
-    // Versions activated before records existed are grandfathered through
-    // current/last state, but only while their directory has no record file.
-    std::string versionDir = PushyToStdString(PushyVersionDir(hash));
-    std::string hashStd = PushyToStdString(hash);
-    std::string bundleName = PushyToStdString(BUNDLE_FILE_NAME);
-    BOOL (^isCurrentOrLast)(void) = ^BOOL {
-        pushy::state::State state = PushyStateFromDefaults(PushyDefaults());
-        return state.current_version == hashStd || state.last_version == hashStd;
-    };
+    PushyUnzipGuard *guard = [[PushyUnzipGuard alloc] initWithArchiveBytes:archiveBytes
+                                                                destination:destination];
+    // preserveAttributes:NO — the archive's mode/mtime bits have no use
+    // here and are one less thing a hostile package controls.
+    [SSZipArchive unzipFileAtPath:path
+                    toDestination:destination
+               preserveAttributes:NO
+                        overwrite:YES
+                   nestedZipLevel:0
+                         password:nil
+                            error:nil
+                         delegate:guard
+                  progressHandler:nil
+                completionHandler:^(NSString *archivePath, BOOL succeeded, NSError *error) {
+        // The resume sidecar dies with its archive (§11.4): whether the
+        // unzip consumed it or classified it as poisoned, nothing must
+        // survive to vouch for bytes that are gone.
+        RCTPushyDiscardArchive(archivePath);
+
+        NSError *unzipError = error;
+        if (guard.violation != nil) {
+            unzipError = PushyErrorWithCode(pushy::error_codes::kDeltaFailed, guard.violation);
+        } else if (!succeeded && unzipError == nil) {
+            unzipError = PushyErrorWithCode(pushy::error_codes::kDeltaFailed, @"unzip failed");
+        } else if (unzipError != nil && unzipError.userInfo[RCTPushyErrorCodeKey] == nil) {
+            // SSZipArchive's own NSError (corrupt zip, bad magic, ...) has
+            // no stable code; without one, fetchPackage's fallback would
+            // classify it as DOWNLOAD_FAILED even though the download
+            // succeeded — keep the classification deterministic.
+            unzipError = PushyErrorWithCode(pushy::error_codes::kDeltaFailed,
+                                            unzipError.localizedDescription ?: @"unzip failed");
+        }
+        completionHandler(unzipError);
+    }];
+}
 
-    // The digest check reads the whole bundle, so it runs OUTSIDE the state
-    // lock: +bundleURL takes that lock on the main thread at launch.
-    __block BOOL grandfathered = NO;
-    PushyWithStateLock(^{
-        grandfathered = isCurrentOrLast();
-    });
-    pushy::install_record::Activation activation;
-    pushy::install_record::Status verified = pushy::install_record::CheckActivation(
-        versionDir, hashStd, bundleName, grandfathered, &activation);
-
-    __block NSError *lockedError = verified.ok
-        ? nil
-        : PushyErrorWithCode(pushy::error_codes::kSwitchVersionFailed,
-                             PushyFromStdString(verified.message));
-    if (lockedError == nil) {
-        PushyWithStateLock(^{
-            // Re-check cheaply that the directory is still the one that was
-            // verified: same grandfathering, same record, same bundle file.
-            if (!pushy::install_record::Unchanged(versionDir, bundleName, isCurrentOrLast(),
-                                                  activation)) {
-                lockedError = PushyErrorWithCode(
-                    pushy::error_codes::kSwitchVersionFailed,
-                    [NSString stringWithFormat:@"Bundle version %@ changed while switching.", hash]);
-                return;
-            }
-            PushySwitchVersionLocked(hash);
-        });
++ (BOOL)switchVersion:(NSString *)hash error:(NSError **)error
+{
+    // Same gate as Android and Harmony (install_record::CheckActivation); see
+    // PushyVerifyActivation.
+    PushyVerifiedActivation verified;
+    __block NSError *switchError = nil;
+    @try {
+        switchError = PushyVerifyActivation(hash, &verified);
+        if (switchError == nil) {
+            PushyWithStateLock(^{
+                if (!PushyVerifiedActivationUnchangedLocked(verified)) {
+                    switchError = PushyErrorWithCode(
+                        pushy::error_codes::kSwitchVersionFailed,
+                        [NSString stringWithFormat:@"Bundle version %@ changed while switching.", hash]);
+                    return;
+                }
+                PushySwitchVersionLocked(hash);
+            });
+        }
+    } @catch (...) {
+        switchError = PushyErrorWithCode(pushy::error_codes::kSwitchVersionFailed,
+                                         PushyCaughtReason(@"switch failed"));
     }
-    if (lockedError != nil) {
+    if (switchError != nil) {
         if (error != NULL) {
-            *error = lockedError;
+            *error = switchError;
         }
         return NO;
     }
@@ -658,7 +701,7 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
 
 + (void)clearInvalidFiles
 {
-    dispatch_async(PushyFileQueue(), ^{
+    dispatch_async(PushyFileQueue(), ^{ PushyGuard(@"cleanup", ^{
         // Snapshot the state under the lock, but run the (slow) filesystem
         // cleanup outside of it so state operations are not blocked.
         __block pushy::state::State state;
@@ -683,7 +726,7 @@ static BOOL PushyEnsureDirectoryExists(NSString *path) {
         if (!status.ok) {
             RCTLogWarn(@"Pushy cleanup error: %s", status.message.c_str());
         }
-    });
+    }); });
 }
 
 @end

package/ios/RCTPushy/RCTPushyInternal.h

@@ -21,6 +21,7 @@
 #include <atomic>
 #include <string>
 
+#include "../../cpp/patch_core/install_record.h"
 #include "../../cpp/patch_core/state_core.h"
 
 // RN's log macros pass __FILE__, which would embed this file's absolute build
@@ -31,9 +32,11 @@
 #endif
 
 typedef NS_ENUM(NSInteger, PushyType) {
+    // <generated:archive-patch-types> (scripts/contract.ts; bun scripts/generate-contract.ts)
     PushyTypeFullDownload = 1,
     PushyTypePatchFromPackage = 2,
     PushyTypePatchFromPpk = 3,
+    // </generated:archive-patch-types>
 };
 
 #pragma mark - RCTPushyState.mm
@@ -52,6 +55,15 @@ extern PUSHY_HIDDEN std::atomic<bool> ignoreRollback;
 extern PUSHY_HIDDEN std::atomic<uint64_t> pushyResetGeneration;
 
 PUSHY_HIDDEN NSString *KeyPackageUpdatedMarked(void);
+// What a reset / a binary upgrade deletes besides the state fields
+// (generated from scripts/contract.ts storedItems), and the removal itself:
+// every key in `keys` and every stored key starting with one of `prefixes`.
+PUSHY_HIDDEN NSArray<NSString *> *PushyKeysClearedOnReset(void);
+PUSHY_HIDDEN NSArray<NSString *> *PushyKeyPrefixesClearedOnReset(void);
+PUSHY_HIDDEN NSArray<NSString *> *PushyKeysClearedOnUpgrade(void);
+PUSHY_HIDDEN NSArray<NSString *> *PushyKeyPrefixesClearedOnUpgrade(void);
+PUSHY_HIDDEN void PushyRemoveKeys(NSUserDefaults *defaults, NSArray<NSString *> *keys,
+                                  NSArray<NSString *> *prefixes);
 PUSHY_HIDDEN NSString *PushyHashInfoKey(NSString *hash);
 // Immutable host-facing snapshot; activated always means NEXT launch.
 PUSHY_HIDDEN NSDictionary *PushyHostResult(NSString *status, NSString *reason,
@@ -59,6 +71,15 @@ PUSHY_HIDDEN NSDictionary *PushyHostResult(NSString *status, NSString *reason,
 PUSHY_HIDDEN NSTimeInterval PushyMonotonicNow(void);
 PUSHY_HIDDEN NSUserDefaults *PushyDefaults(void);
 PUSHY_HIDDEN void PushyWithStateLock(void (NS_NOESCAPE ^block)(void));
+// Inside `@catch (...)`: the reason of what was caught — an NSException's
+// reason or a C++ exception's what() — or `fallback` when it has none. The
+// shared cores can throw std::bad_alloc / std::length_error, which
+// `@catch (NSException *)` lets through; an entry point (RN method, host
+// API, GCD block, launch path) therefore catches `...` (CODE_AUDIT 4.4).
+PUSHY_HIDDEN NSString *PushyCaughtReason(NSString *fallback);
+// Runs `block` for an entry point that has nobody to report to: whatever it
+// throws is logged under `where` and swallowed. NO when it threw.
+PUSHY_HIDDEN BOOL PushyGuard(NSString *where, void (NS_NOESCAPE ^block)(void));
 PUSHY_HIDDEN std::string PushyToStdString(NSString *value);
 PUSHY_HIDDEN NSString *PushyFromStdString(const std::string &value);
 PUSHY_HIDDEN NSString *PushyOptionString(NSDictionary *options, NSString *key);
@@ -87,6 +108,26 @@ PUSHY_HIDDEN BOOL PushyHasCompletedVersionAtPath(NSString *versionDir, NSString
 PUSHY_HIDDEN NSString *PushyRecordedBundleSha256(NSString *versionDir);
 PUSHY_HIDDEN NSError *PushyPromoteStagingDir(NSString *hash, NSString *artifactSha256);
 
+// The activation gate every path that points the next launch at a version
+// goes through (switchVersion:error:, the native round's commit and the crash
+// hold's pending activation), as Android and Harmony do: only a version
+// recorded as completely installed, whose record's bundle digest matches the
+// bytes on disk, may be activated (install_record::CheckActivation). Split in
+// two because the digest reads the whole bundle and must not run under the
+// state lock (+bundleURL takes it on the main thread at launch).
+struct PushyVerifiedActivation {
+    std::string versionDir;
+    std::string hash;
+    pushy::install_record::Activation activation;
+};
+// Outside the state lock. nil when `hash` may be activated (and *out holds
+// what was verified), else a SWITCH_VERSION_FAILED error.
+PUSHY_HIDDEN NSError *PushyVerifyActivation(NSString *hash, PushyVerifiedActivation *out);
+// Under the state lock, right before PushySwitchVersionLocked: whether the
+// directory is still the one verified (same grandfathering, same record, same
+// bundle file). No hashing.
+PUSHY_HIDDEN BOOL PushyVerifiedActivationUnchangedLocked(const PushyVerifiedActivation &verified);
+
 #pragma mark - RCTPushyInstaller.mm
 
 // Protocol key of the artifact URL in download options.