react-native-update 10.59.2 → 10.61.0

package/ios/RCTPushy/RCTPushyDownloader.mm

@@ -1,7 +1,7 @@
 #import "RCTPushyDownloader.h"
+#import "RCTPushyCommon.h"
 #include "../../cpp/patch_core/archive_limits.h"
-
-static NSString *const RCTPushyDownloaderErrorDomain = @"cn.reactnative.pushy";
+#include "../../cpp/patch_core/resume_plan.h"
 
 // Cross-launch resumable download (NATIVE_CHECKUPDATE_DESIGN §11.4): a data
 // task streams the archive straight into savePath (a download task's
@@ -15,20 +15,31 @@ NSString *RCTPushyResumeSidecarPath(NSString *savePath) {
     return [savePath stringByAppendingString:@".resume"];
 }
 
-static NSDictionary *RCTPushyReadResumeMeta(NSString *savePath, NSString *url) {
-    NSData *data = [NSData dataWithContentsOfFile:RCTPushyResumeSidecarPath(savePath)];
-    if (data == nil) {
-        return nil;
-    }
-    id meta = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
-    if (![meta isKindOfClass:[NSDictionary class]]) {
-        return nil;
-    }
-    // An archive whose sidecar names another URL is untrusted.
-    if (![url isEqualToString:meta[@"url"]]) {
-        return nil;
-    }
-    return meta;
+// The sidecar's text, "" when there is none or it cannot be one (larger than
+// a sidecar ever is): pushy::resume treats both as "no trusted partial".
+static NSString *RCTPushyReadSidecarText(NSString *savePath) {
+    NSString *path = RCTPushyResumeSidecarPath(savePath);
+    NSNumber *size = [[NSFileManager defaultManager] attributesOfItemAtPath:path
+                                                                      error:nil][NSFileSize];
+    if (size == nil || size.longLongValue > pushy::resume::kMaxSidecarBytes) {
+        return @"";
+    }
+    NSString *text = [NSString stringWithContentsOfFile:path
+                                               encoding:NSUTF8StringEncoding
+                                                  error:nil];
+    return text ?: @"";
+}
+
+static std::string RCTPushyStd(NSString *value) {
+    const char *utf8 = value.UTF8String;
+    return utf8 == nullptr ? std::string() : std::string(utf8);
+}
+
+// A pushy::resume result as a dictionary; nil only if it did not parse.
+static NSDictionary *RCTPushyResumeDecision(const std::string &json) {
+    NSData *data = [NSData dataWithBytes:json.data() length:json.size()];
+    id value = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
+    return [value isKindOfClass:[NSDictionary class]] ? value : nil;
 }
 
 static void RCTPushyDeleteResumeSidecar(NSString *savePath) {
@@ -36,6 +47,16 @@ static void RCTPushyDeleteResumeSidecar(NSString *savePath) {
                                                error:nil];
 }
 
+void RCTPushyDiscardArchive(NSString *path) {
+    [[NSFileManager defaultManager] removeItemAtPath:path error:nil];
+    RCTPushyDeleteResumeSidecar(path);
+}
+
+BOOL RCTPushyIsHttpsDowngrade(NSURL *from, NSURL *to) {
+    return [[from.scheme lowercaseString] isEqualToString:@"https"]
+        && [[to.scheme lowercaseString] isEqualToString:@"http"];
+}
+
 long long RCTPushyFileSize(NSString *path) {
     NSDictionary *attributes =
         [[NSFileManager defaultManager] attributesOfItemAtPath:path error:nil];
@@ -69,54 +90,6 @@ NSString *RCTPushyFreeSpaceShortfall(NSString *path, long long bytesToWrite) {
     return nil;
 }
 
-// "bytes <start>-<end>/<total>". Returns the total (0 when "*"), or -1 when
-// missing/malformed, the start does not match the local partial, or the
-// range and total contradict each other (end before start, or a numeric
-// total not beyond the end — RFC 9110 §14.4). A total of 0 would otherwise
-// pass as "unknown" and skip the final size check.
-static long long RCTPushyParseContentRange(NSString *header, long long expectedStart) {
-    if (![header hasPrefix:@"bytes "]) {
-        return -1;
-    }
-    NSString *range = [[header substringFromIndex:6]
-        stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceCharacterSet]];
-    NSRange slash = [range rangeOfString:@"/"];
-    NSRange dash = [range rangeOfString:@"-"];
-    if (slash.location == NSNotFound || dash.location == NSNotFound
-        || dash.location > slash.location) {
-        return -1;
-    }
-    NSCharacterSet *whitespace = [NSCharacterSet whitespaceCharacterSet];
-    NSString *startPart = [[range substringToIndex:dash.location]
-        stringByTrimmingCharactersInSet:whitespace];
-    NSString *endPart = [[range substringWithRange:
-        NSMakeRange(dash.location + 1, slash.location - dash.location - 1)]
-        stringByTrimmingCharactersInSet:whitespace];
-    NSString *totalPart = [[range substringFromIndex:slash.location + 1]
-        stringByTrimmingCharactersInSet:whitespace];
-    // longLongValue reads 0 for non-numeric text; require real digits.
-    NSCharacterSet *digits = [NSCharacterSet decimalDigitCharacterSet];
-    if (startPart.length == 0 || endPart.length == 0
-        || [startPart rangeOfCharacterFromSet:digits.invertedSet].location != NSNotFound
-        || [endPart rangeOfCharacterFromSet:digits.invertedSet].location != NSNotFound) {
-        return -1;
-    }
-    long long start = startPart.longLongValue;
-    long long end = endPart.longLongValue;
-    if (start != expectedStart || end < start) {
-        return -1;
-    }
-    if ([totalPart isEqualToString:@"*"]) {
-        return 0;
-    }
-    if (totalPart.length == 0
-        || [totalPart rangeOfCharacterFromSet:digits.invertedSet].location != NSNotFound) {
-        return -1;
-    }
-    long long total = totalPart.longLongValue;
-    return total > end ? total : -1;
-}
-
 @interface RCTPushyDownloader()<NSURLSessionDataDelegate>
 
 @property (nonatomic, strong) NSURLSession *session;
@@ -126,7 +99,11 @@ static long long RCTPushyParseContentRange(NSString *header, long long expectedS
 @property (copy) NSString *urlString;
 @property (nonatomic, assign) NSTimeInterval timeoutInterval;
 @property (nonatomic, strong) NSFileHandle *fileHandle;
-@property (nonatomic, strong) NSDictionary *resumeMeta;
+// The sidecar the planned request was based on ("" for a fresh request),
+// and this response's validators: pushy::resume builds the next sidecar.
+@property (nonatomic, copy) NSString *sidecarText;
+@property (nonatomic, copy) NSString *responseEtag;
+@property (nonatomic, copy) NSString *responseLastModified;
 @property (nonatomic, assign) long long resumeOffset;   // requested Range start
 @property (nonatomic, assign) long long baseOffset;     // granted by the response
 @property (nonatomic, assign) long long receivedBytes;  // streamed this session
@@ -174,7 +151,7 @@ completionHandler:(void (^)(NSString *path, NSError *error))completionHandler
 {
     NSURL *url = [NSURL URLWithString:self.urlString];
     if (url == nil) {
-        [self completeWithError:[NSError errorWithDomain:RCTPushyDownloaderErrorDomain
+        [self completeWithError:[NSError errorWithDomain:RCTPushyErrorDomain
                                                     code:-1
                                                 userInfo:@{
                                                     NSLocalizedDescriptionKey: @"invalid download url",
@@ -182,45 +159,36 @@ completionHandler:(void (^)(NSString *path, NSError *error))completionHandler
         return;
     }
 
-    NSFileManager *fileManager = [NSFileManager defaultManager];
-    self.resumeMeta = RCTPushyReadResumeMeta(self.savePath, self.urlString);
+    // What to request is the shared core's decision (pushy::resume).
+    NSString *sidecarText = self.retriedFromZero ? @"" : RCTPushyReadSidecarText(self.savePath);
+    long long partialSize = RCTPushyFileSize(self.savePath);
+    NSDictionary *plan = RCTPushyResumeDecision(pushy::resume::PlanRequestJson(
+        RCTPushyStd(sidecarText), RCTPushyStd(self.urlString), MAX(0LL, partialSize)));
+    NSString *action = plan[@"action"];
     self.resumeOffset = 0;
-    if (self.resumeMeta != nil) {
-        long long size = RCTPushyFileSize(self.savePath);
-        long long knownTotal = [self.resumeMeta[@"total"] longLongValue];
-        if (size > 0 && knownTotal > 0 && size == knownTotal) {
-            // Fully received in a previous attempt (the process died between
-            // download end and unzip): nothing left to transfer.
-            if (self.progressHandler) {
-                self.progressHandler(knownTotal, knownTotal);
-            }
-            [self completeWithError:nil];
-            return;
+    if ([action isEqualToString:@"complete"]) {
+        // Fully received in a previous attempt (the process died between
+        // download end and unzip): nothing left to transfer.
+        long long knownTotal = [plan[@"total"] longLongValue];
+        if (self.progressHandler) {
+            self.progressHandler(knownTotal, knownTotal);
         }
-        if (size > 0 && (knownTotal <= 0 || size < knownTotal)) {
-            self.resumeOffset = size;
-        }
-    }
-    if (self.resumeOffset == 0) {
-        [fileManager removeItemAtPath:self.savePath error:nil];
-        RCTPushyDeleteResumeSidecar(self.savePath);
+        [self completeWithError:nil];
+        return;
     }
-
     NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
-    if (self.resumeOffset > 0) {
-        // Only resume requests pin the encoding: Range offsets must address
-        // the same bytes that are on disk. Fresh downloads keep the system's
-        // transparent gzip handling, matching the pre-resume behaviour for
-        // servers that compress regardless.
-        [request setValue:@"identity" forHTTPHeaderField:@"Accept-Encoding"];
-        [request setValue:[NSString stringWithFormat:@"bytes=%lld-", self.resumeOffset]
-       forHTTPHeaderField:@"Range"];
-        NSString *validator = self.resumeMeta[@"etag"] ?: self.resumeMeta[@"lastModified"];
-        if (validator != nil) {
-            // With a validator the server falls back to a full 200 when the
-            // file changed instead of appending mismatched bytes.
-            [request setValue:validator forHTTPHeaderField:@"If-Range"];
+    if ([action isEqualToString:@"resume"]) {
+        self.resumeOffset = [plan[@"offset"] longLongValue];
+        self.sidecarText = sidecarText;
+        // Range, Accept-Encoding: identity and If-Range. Fresh downloads send
+        // none of them and keep the system's transparent gzip handling.
+        NSDictionary *headers = plan[@"headers"];
+        for (NSString *name in headers) {
+            [request setValue:headers[name] forHTTPHeaderField:name];
         }
+    } else {
+        self.sidecarText = @"";
+        RCTPushyDiscardArchive(self.savePath);
     }
 
     NSURLSessionConfiguration *sessionConfig = [NSURLSessionConfiguration defaultSessionConfiguration];
@@ -239,37 +207,19 @@ completionHandler:(void (^)(NSString *path, NSError *error))completionHandler
     [task resume];
 }
 
-- (void)writeResumeMetaWithResponse:(NSHTTPURLResponse *)response total:(long long)total
+- (void)writeSidecarWithTotal:(long long)total
 {
-    NSMutableDictionary *meta = [NSMutableDictionary dictionary];
-    meta[@"url"] = self.urlString;
-    NSString *etag = response.allHeaderFields[@"ETag"] ?: self.resumeMeta[@"etag"];
-    NSString *lastModified =
-        response.allHeaderFields[@"Last-Modified"] ?: self.resumeMeta[@"lastModified"];
-    if (etag != nil) {
-        meta[@"etag"] = etag;
-    }
-    if (lastModified != nil) {
-        meta[@"lastModified"] = lastModified;
-    }
-    if (total > 0) {
-        meta[@"total"] = @(total);
-    }
-    NSData *data = [NSJSONSerialization dataWithJSONObject:meta options:0 error:nil];
-    if (data != nil) {
-        // Non-fatal on failure: without a sidecar the next attempt starts
-        // from zero.
-        [data writeToFile:RCTPushyResumeSidecarPath(self.savePath) atomically:YES];
-    }
+    std::string json = pushy::resume::SidecarJson(
+        RCTPushyStd(self.urlString), RCTPushyStd(self.responseEtag),
+        RCTPushyStd(self.responseLastModified), RCTPushyStd(self.sidecarText), total);
+    NSData *data = [NSData dataWithBytes:json.data() length:json.size()];
+    // Non-fatal on failure: without a sidecar the next attempt starts from
+    // zero.
+    [data writeToFile:RCTPushyResumeSidecarPath(self.savePath) atomically:YES];
 }
 
-- (void)completeWithError:(NSError *)error
+- (void)closeFileHandle
 {
-    if (self.finished) {
-        return;
-    }
-    self.finished = YES;
-
     if (self.fileHandle != nil) {
         @try {
             [self.fileHandle closeFile];
@@ -277,9 +227,18 @@ completionHandler:(void (^)(NSString *path, NSError *error))completionHandler
         }
         self.fileHandle = nil;
     }
+}
+
+- (void)completeWithError:(NSError *)error
+{
+    if (self.finished) {
+        return;
+    }
+    self.finished = YES;
+
+    [self closeFileHandle];
     if (self.discardPartial) {
-        [[NSFileManager defaultManager] removeItemAtPath:self.savePath error:nil];
-        RCTPushyDeleteResumeSidecar(self.savePath);
+        RCTPushyDiscardArchive(self.savePath);
     }
 
     void (^completionHandler)(NSString *, NSError *) = self.completionHandler;
@@ -297,7 +256,7 @@ completionHandler:(void (^)(NSString *path, NSError *error))completionHandler
 
 - (void)failWithDescription:(NSString *)description code:(NSInteger)code
 {
-    self.fileError = [NSError errorWithDomain:RCTPushyDownloaderErrorDomain
+    self.fileError = [NSError errorWithDomain:RCTPushyErrorDomain
                                          code:code
                                      userInfo:@{NSLocalizedDescriptionKey: description}];
 }
@@ -308,7 +267,7 @@ completionHandler:(void (^)(NSString *path, NSError *error))completionHandler
 - (void)restartFromZero
 {
     self.retriedFromZero = YES;
-    self.resumeMeta = nil;
+    self.sidecarText = @"";
     self.resumeOffset = 0;
     self.baseOffset = 0;
     self.receivedBytes = 0;
@@ -317,15 +276,8 @@ completionHandler:(void (^)(NSString *path, NSError *error))completionHandler
     self.encodedBody = NO;
     self.lastReportedPercentage = 0;
     self.lastReportedBytes = 0;
-    if (self.fileHandle != nil) {
-        @try {
-            [self.fileHandle closeFile];
-        } @catch (NSException *exception) {
-        }
-        self.fileHandle = nil;
-    }
-    [[NSFileManager defaultManager] removeItemAtPath:self.savePath error:nil];
-    RCTPushyDeleteResumeSidecar(self.savePath);
+    [self closeFileHandle];
+    RCTPushyDiscardArchive(self.savePath);
     [self.session finishTasksAndInvalidate];
     self.session = nil;
     [self startTransfer];
@@ -346,9 +298,7 @@ willPerformHTTPRedirection:(NSHTTPURLResponse *)response
         completionHandler(nil);
         return;
     }
-    NSString *originalScheme = [[NSURL URLWithString:self.urlString].scheme lowercaseString];
-    NSString *nextScheme = [request.URL.scheme lowercaseString];
-    if ([originalScheme isEqualToString:@"https"] && [nextScheme isEqualToString:@"http"]) {
+    if (RCTPushyIsHttpsDowngrade([NSURL URLWithString:self.urlString], request.URL)) {
         [self failWithDescription:[NSString stringWithFormat:
             @"https download redirected to plaintext http: %@", request.URL.absoluteString]
                              code:-1];
@@ -378,13 +328,33 @@ didReceiveResponse:(NSURLResponse *)response
         [self completeWithError:self.fileError];
         return;
     }
-    if (statusCode == 416) {
-        long long knownTotal = [self.resumeMeta[@"total"] longLongValue];
+    // What to do with this response is the shared core's decision
+    // (pushy::resume). A non-HTTP response cannot happen for an http(s) URL;
+    // it would carry no status, so it is classified like a plain 200.
+    NSDictionary *headers = httpResponse.allHeaderFields;
+    NSDictionary *decision = RCTPushyResumeDecision(pushy::resume::ClassifyResponseJson(
+        httpResponse != nil ? (int)statusCode : 200, self.resumeOffset,
+        RCTPushyStd(headers[@"Content-Range"]), RCTPushyStd(headers[@"Content-Encoding"]),
+        response.expectedContentLength, RCTPushyStd(self.sidecarText),
+        RCTPushyStd(self.urlString), MAX(0LL, RCTPushyFileSize(self.savePath))));
+    NSString *action = decision[@"action"];
+    if ([action isEqualToString:@"complete"]) {
+        // 416 and the partial is actually the complete file.
+        long long knownTotal = [decision[@"total"] longLongValue];
         completionHandler(NSURLSessionResponseCancel);
-        if (knownTotal > 0 && RCTPushyFileSize(self.savePath) == knownTotal) {
-            // The partial is actually the complete file.
-            [self completeWithError:nil];
-        } else if (!self.retriedFromZero) {
+        if (self.progressHandler) {
+            self.progressHandler(knownTotal, knownTotal);
+        }
+        [self completeWithError:nil];
+        return;
+    }
+    if ([action isEqualToString:@"restart"]) {
+        // A stale 416, encoded range bytes or a malformed/mismatched
+        // Content-Range: the partial cannot be trusted. One clean retry from
+        // zero instead of failing terminally, which would keep the partial
+        // and hit the same wall on every attempt.
+        completionHandler(NSURLSessionResponseCancel);
+        if (!self.retriedFromZero) {
             [self restartFromZero];
         } else {
             [self failWithDescription:@"server rejected the download range" code:statusCode];
@@ -392,7 +362,8 @@ didReceiveResponse:(NSURLResponse *)response
         }
         return;
     }
-    if (httpResponse != nil && (statusCode < 200 || statusCode >= 300)) {
+    if (![action isEqualToString:@"write"]) {
+        // The partial and its sidecar stay: that is the resume state.
         [self failWithDescription:[NSString stringWithFormat:@"unexpected http status code %ld",
                                    (long)statusCode]
                              code:statusCode];
@@ -401,39 +372,17 @@ didReceiveResponse:(NSURLResponse *)response
         return;
     }
 
-    NSString *contentEncoding =
-        [httpResponse.allHeaderFields[@"Content-Encoding"] lowercaseString];
-    self.encodedBody =
-        contentEncoding.length > 0 && ![contentEncoding isEqualToString:@"identity"];
-
-    BOOL append = statusCode == 206 && self.resumeOffset > 0;
-    if (append && (self.encodedBody
-        || RCTPushyParseContentRange(httpResponse.allHeaderFields[@"Content-Range"],
-                                     self.resumeOffset) < 0)) {
-        // Encoded range bytes or a malformed/mismatched Content-Range: the
-        // appended bytes could not be trusted. Treat like a stale partial —
-        // one clean retry from zero — instead of failing terminally, which
-        // would keep the partial and hit the same wall on every attempt.
-        completionHandler(NSURLSessionResponseCancel);
-        if (!self.retriedFromZero) {
-            [self restartFromZero];
-        } else {
-            [self failWithDescription:@"untrusted resume response" code:-1];
-            [self completeWithError:self.fileError];
-        }
-        return;
-    }
-    self.baseOffset = append ? self.resumeOffset : 0;
+    BOOL append = [decision[@"append"] boolValue];
+    // NSURLSession delivers decoded bytes for an encoded body: the core then
+    // reports total 0 (the encoded lengths say nothing about the file).
+    self.encodedBody = [decision[@"encoded"] boolValue];
+    self.baseOffset = [decision[@"base"] longLongValue];
     self.contentLength = response.expectedContentLength;
-    if (append) {
-        self.expectedTotal = RCTPushyParseContentRange(
-            httpResponse.allHeaderFields[@"Content-Range"], self.resumeOffset);
-    } else if (self.encodedBody) {
-        // Decoded bytes are being written; the encoded lengths say nothing.
-        self.expectedTotal = 0;
-    } else {
-        self.expectedTotal = self.contentLength > 0 ? self.contentLength : 0;
-    }
+    self.expectedTotal = [decision[@"total"] longLongValue];
+    id etag = headers[@"ETag"];
+    id lastModified = headers[@"Last-Modified"];
+    self.responseEtag = [etag isKindOfClass:[NSString class]] ? etag : nil;
+    self.responseLastModified = [lastModified isKindOfClass:[NSString class]] ? lastModified : nil;
 
     // Caps from archive_limits.h, applied before the first body byte lands
     // (Android does the same): the announced size up front here, streamed
@@ -490,13 +439,13 @@ didReceiveResponse:(NSURLResponse *)response
             return;
         }
     }
-    if (self.encodedBody) {
+    if (![decision[@"persistSidecar"] boolValue]) {
         // No resume across an encoded transfer: on-disk bytes are decoded,
         // Range offsets would address the encoded representation.
         RCTPushyDeleteResumeSidecar(self.savePath);
-    } else if (httpResponse != nil) {
+    } else {
         // Persist before streaming so a mid-stream crash can resume.
-        [self writeResumeMetaWithResponse:httpResponse total:self.expectedTotal];
+        [self writeSidecarWithTotal:self.expectedTotal];
     }
     completionHandler(NSURLSessionResponseAllow);
 }
@@ -523,19 +472,18 @@ didReceiveResponse:(NSURLResponse *)response
         [dataTask cancel];
         return;
     }
-    if (self.expectedTotal <= 0
-        && self.receivedBytes + (long long)data.length > self.freeSpaceReservedUntil) {
-        // Unknown/encoded length: the response-time check could only
-        // reserve the margin, so probe before any write that would run past
-        // the bytes reserved so far, each probe reserving at least the next
-        // PROBE bytes (more when one callback carries a larger buffer) — no
-        // write can ever eat into the margin. The archive cap alone (512
-        // MiB) is far more than the margin protects. The partial stays: a
-        // later attempt may find the space.
-        long long reserve = MAX(pushy::archive_limits::kUnknownLengthFreeSpaceProbeBytes,
-                                (long long)data.length);
-        self.freeSpaceReservedUntil = self.receivedBytes + reserve;
-        NSString *shortfall = RCTPushyFreeSpaceShortfall(self.savePath, reserve);
+    // Unknown/encoded length: the response-time check could only reserve the
+    // margin, so the disk is probed before any write that would run past the
+    // bytes reserved so far (archive_limits::PlanUnknownLengthFreeSpaceProbe)
+    // — no write can ever eat into the margin. The partial stays: a later
+    // attempt may find the space.
+    pushy::archive_limits::FreeSpaceProbe plan =
+        pushy::archive_limits::PlanUnknownLengthFreeSpaceProbe(
+            self.expectedTotal, self.receivedBytes, (long long)data.length,
+            self.freeSpaceReservedUntil);
+    self.freeSpaceReservedUntil = plan.reserved_until;
+    if (plan.probe) {
+        NSString *shortfall = RCTPushyFreeSpaceShortfall(self.savePath, plan.reserve);
         if (shortfall != nil) {
             [self failWithDescription:shortfall code:-1];
             [dataTask cancel];
@@ -611,6 +559,12 @@ didCompleteWithError:(NSError *)error
             finalError = self.fileError;
         }
     }
+    if (finalError == nil && !self.encodedBody) {
+        // Refresh with the final size: a length unknown up front (chunked)
+        // left the sidecar without a total, so a process dying between
+        // download end and unzip would otherwise download it all again.
+        [self writeSidecarWithTotal:RCTPushyFileSize(self.savePath)];
+    }
     // On failure the partial + sidecar stay on disk — that is the resume
     // state a later launch (or crash-rescue window) picks up — unless the
     // archive was rejected outright (discardPartial).

package/ios/RCTPushy/RCTPushyInstallRecord.mm

@@ -0,0 +1,101 @@
+// Version directories and the completion record: where an install lands and
+// how it is recorded as complete. The record itself (format, atomic write,
+// presence and activation checks) is the shared core's
+// (cpp/patch_core/install_record.h); every activation goes through its
+// activation check (PushyVerifyActivation below).
+#import "RCTPushyInternal.h"
+#include "../../cpp/patch_core/error_codes.h"
+#include "../../cpp/patch_core/install_record.h"
+
+PUSHY_HIDDEN NSString *const BUNDLE_FILE_NAME = @"index.bundlejs";
+
+PUSHY_HIDDEN NSString *PushyVersionDir(NSString *hash) {
+    return [[RCTPushy downloadDir] stringByAppendingPathComponent:hash];
+}
+
+// Two-phase install: everything lands in <hash>.staging first.
+PUSHY_HIDDEN NSString *PushyStagingDir(NSString *hash) {
+    return [PushyVersionDir(hash) stringByAppendingString:@(pushy::install_record::kStagingSuffix)];
+}
+
+// Presence check (launch / dedup paths, no digest work): bundle present and
+// the record is the legacy marker or names this version.
+PUSHY_HIDDEN BOOL PushyHasCompletedVersionAtPath(NSString *versionDir, NSString *hash) {
+    return pushy::install_record::IsComplete(PushyToStdString(versionDir), PushyToStdString(hash),
+                                             PushyToStdString(BUNDLE_FILE_NAME));
+}
+
+// The record's bundleSha256 (crash attribution); @"" when there is none.
+PUSHY_HIDDEN NSString *PushyRecordedBundleSha256(NSString *versionDir) {
+    return PushyFromStdString(
+        pushy::install_record::RecordedBundleSha256(PushyToStdString(versionDir))) ?: @"";
+}
+
+// Second phase of an install: seals <hash>.staging with the completion
+// record (the final bundle's digest is mandatory: a version whose bundle
+// could not be hashed is never recorded as installed) and renames it over
+// <hash> in one atomic step. nil on success. Runs on the file queue. The
+// caller drops the staging directory on failure.
+PUSHY_HIDDEN NSError *PushyPromoteStagingDir(NSString *hash, NSString *artifactSha256) {
+    std::string staging = PushyToStdString(PushyStagingDir(hash));
+    pushy::install_record::SealResult sealed = pushy::install_record::Seal(
+        staging, PushyToStdString(hash), PushyToStdString(BUNDLE_FILE_NAME),
+        PushyToStdString(artifactSha256), std::string());
+    if (!sealed.status.ok) {
+        return PushyErrorWithCode(sealed.file_failure ? pushy::error_codes::kFileOperationFailed
+                                                      : pushy::error_codes::kDeltaFailed,
+                                  PushyFromStdString(sealed.status.message));
+    }
+    NSString *versionDir = PushyVersionDir(hash);
+    NSFileManager *fileManager = [NSFileManager defaultManager];
+    if ([fileManager fileExistsAtPath:versionDir]) {
+        [fileManager removeItemAtPath:versionDir error:nil];
+    }
+    pushy::install_record::Status promoted =
+        pushy::install_record::Promote(staging, PushyToStdString(versionDir));
+    if (!promoted.ok) {
+        return PushyErrorWithCode(pushy::error_codes::kFileOperationFailed,
+                                  PushyFromStdString(promoted.message));
+    }
+    return nil;
+}
+
+// Versions activated before records existed are grandfathered through the
+// persisted current/last state, but only while their directory has no record
+// file (install_record::CheckActivation). Call under the state lock.
+static BOOL PushyIsCurrentOrLastLocked(const std::string &hash) {
+    pushy::state::State state = PushyStateFromDefaults(PushyDefaults());
+    return state.current_version == hash || state.last_version == hash;
+}
+
+PUSHY_HIDDEN NSError *PushyVerifyActivation(NSString *hash, PushyVerifiedActivation *out) {
+    if (!PushyIsSafePathComponent(hash)) {
+        return PushyErrorWithCode(pushy::error_codes::kInvalidOptions, ERROR_OPTIONS);
+    }
+    PushyVerifiedActivation verified;
+    verified.versionDir = PushyToStdString(PushyVersionDir(hash));
+    verified.hash = PushyToStdString(hash);
+    __block BOOL grandfathered = NO;
+    const std::string hashStd = verified.hash;
+    PushyWithStateLock(^{
+        grandfathered = PushyIsCurrentOrLastLocked(hashStd);
+    });
+    pushy::install_record::Status status = pushy::install_record::CheckActivation(
+        verified.versionDir, verified.hash, PushyToStdString(BUNDLE_FILE_NAME), grandfathered,
+        &verified.activation);
+    if (!status.ok) {
+        return PushyErrorWithCode(pushy::error_codes::kSwitchVersionFailed,
+                                  PushyFromStdString(status.message));
+    }
+    if (out != NULL) {
+        *out = verified;
+    }
+    return nil;
+}
+
+PUSHY_HIDDEN BOOL PushyVerifiedActivationUnchangedLocked(const PushyVerifiedActivation &verified) {
+    return pushy::install_record::Unchanged(verified.versionDir,
+                                            PushyToStdString(BUNDLE_FILE_NAME),
+                                            PushyIsCurrentOrLastLocked(verified.hash),
+                                            verified.activation);
+}