@tileflow/react-native 0.0.0-bootstrap.0 → 0.1.0-alpha.1

package/ios/TFAdmissionEngine.mm

@@ -0,0 +1,371 @@
+#import "TFAdmissionEngine.h"
+#import "TFAdmissionCatalog.h"
+#import <atomic>
+#import <cmath>
+
+static void TFInvalidAdmission(void) {
+	@throw [NSException exceptionWithName:@"TFNativeAdmissionInvalid" reason:@"Invalid native admission" userInfo:nil];
+}
+static BOOL TFString(id value, NSUInteger limit) { return [value isKindOfClass:NSString.class] && [(NSString *)value length] <= limit; }
+static BOOL TFExactNumber(id value, double minimum, double maximum) {
+	return [value isKindOfClass:NSNumber.class] && CFGetTypeID((__bridge CFTypeRef)value) != CFBooleanGetTypeID() &&
+		std::isfinite([value doubleValue]) && std::floor([value doubleValue]) == [value doubleValue] && [value doubleValue] >= minimum && [value doubleValue] <= maximum;
+}
+static BOOL TFGrantShape(NSString *value) {
+	if (!TFString(value, 24576)) return NO;
+	NSRegularExpression *expression = [NSRegularExpression regularExpressionWithPattern:@"^tf_native_v1\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" options:0 error:nil];
+	return [expression numberOfMatchesInString:value options:0 range:NSMakeRange(0, value.length)] == 1;
+}
+
+@interface TFAdmissionFlag : NSObject { @public std::atomic_bool value; }
+@end
+@implementation TFAdmissionFlag
+- (instancetype)init { if ((self = [super init])) value.store(true); return self; }
+@end
+
+@interface TFAdmissionCancellation : NSObject <TFAdmissionCancel> {
+	std::atomic_bool _cancelled;
+}
+@property (nonatomic, copy) dispatch_block_t action;
+- (instancetype)initWithAction:(dispatch_block_t)action;
+@end
+@implementation TFAdmissionCancellation
+- (instancetype)initWithAction:(dispatch_block_t)action { if ((self = [super init])) { _cancelled.store(false); _action = [action copy]; } return self; }
+- (void)cancel { if (!_cancelled.exchange(true)) self.action(); }
+- (NSString *)description { return @"TFAdmissionCancellation(redacted)"; }
+@end
+
+@class TFAdmissionWork;
+@interface TFAdmissionContext : NSObject
+@property (nonatomic, copy) NSString *identifier;
+@property (nonatomic, copy, nullable) NSString *mapId;
+@property (nonatomic) TFAdmissionCatalog *catalog;
+@property (nonatomic) NSMutableDictionary<NSString *, TFAdmissionWork *> *work;
+@property (nonatomic) NSMutableArray<NSString *> *order;
+@property (nonatomic) TFAdmissionFlag *alive;
+@property (nonatomic, copy, nullable) NSString *batch;
+@property (nonatomic, nullable) NSArray<NSString *> *batchTickets;
+@property (nonatomic, nullable) id<TFAdmissionCancel> batchTimer;
+@property (nonatomic) NSUInteger sequence;
+@end
+@implementation TFAdmissionContext
+- (instancetype)init {
+	if ((self = [super init])) { _work = [NSMutableDictionary dictionary]; _order = [NSMutableArray array]; _alive = [TFAdmissionFlag new]; }
+	return self;
+}
+- (NSString *)description { return @"TFAdmissionContext(redacted)"; }
+@end
+
+@interface TFAdmissionWork : NSObject
+@property (nonatomic, copy) NSString *identifier;
+@property (nonatomic) TFAdmissionContext *context;
+@property (nonatomic) NSURLRequest *request;
+@property (nonatomic) TFAdmissionFlag *alive;
+@property (nonatomic) NSTimeInterval entered;
+@property (atomic) NSTimeInterval deadline;
+@property (nonatomic, copy) NSString *phase;
+@property (nonatomic, copy) void (^response)(NSHTTPURLResponse *, NSData *);
+@property (nonatomic, copy) dispatch_block_t failure;
+@property (nonatomic, copy) TFAdmissionDelegate delegate;
+@property (nonatomic, copy, nullable) dispatch_block_t releaseReservation;
+@property (nonatomic, nullable) id<TFAdmissionCancel> cancellation;
+@property (nonatomic, nullable) id<TFAdmissionCancel> timer;
+@property (nonatomic, nullable) NSDictionary *authority;
+@property (nonatomic) NSUInteger redirects;
+@end
+@implementation TFAdmissionWork
+- (NSString *)description { return @"TFAdmissionWork(redacted)"; }
+@end
+
+@interface TFAdmissionEngine () {
+	std::atomic_bool _active;
+	std::atomic_bool _foreground;
+	std::atomic_bool _lossQueued;
+	std::atomic_uint _reservations;
+}
+@property (nonatomic, copy) NSString *installation;
+@property (nonatomic) id<TFAdmissionScheduler> scheduler;
+@property (nonatomic) id<TFAdmissionNetwork> network;
+@property (nonatomic, copy) TFAdmissionStartGuard owns;
+@property (nonatomic, copy) void (^emit)(NSDictionary *);
+@property (nonatomic) NSMutableDictionary<NSString *, TFAdmissionContext *> *contexts;
+@property (nonatomic) NSUInteger contextSequence;
+@property (nonatomic) NSUInteger ticketSequence;
+@end
+
+@implementation TFAdmissionEngine
+- (instancetype)initWithInstallation:(NSString *)installation scheduler:(id<TFAdmissionScheduler>)scheduler network:(id<TFAdmissionNetwork>)network owns:(TFAdmissionStartGuard)owns emit:(void (^)(NSDictionary *))emit {
+	if ((self = [super init])) {
+		_installation = [installation copy]; _scheduler = scheduler; _network = network; _owns = [owns copy]; _emit = [emit copy];
+		_contexts = [NSMutableDictionary dictionary]; _active.store(true); _foreground.store(true); _lossQueued.store(false); _reservations.store(0);
+	}
+	return self;
+}
+- (NSString *)description { return @"TFAdmissionEngine(redacted)"; }
+- (NSString *)registerMap:(NSString *)mapId resources:(NSArray<NSDictionary *> *)resources {
+	if (![self isOwner] || self.contexts.count >= 16 || ![resources isKindOfClass:NSArray.class] || resources.count > 128 || self.contextSequence >= 9007199254740991ULL) TFInvalidAdmission();
+	if (mapId) {
+		NSRegularExpression *pattern = [NSRegularExpression regularExpressionWithPattern:@"^map_[A-Za-z0-9_-]{16}$" options:0 error:nil];
+		if (!TFString(mapId, 64) || [pattern numberOfMatchesInString:mapId options:0 range:NSMakeRange(0, mapId.length)] != 1) TFInvalidAdmission();
+	}
+	TFAdmissionCatalog *catalog = [[TFAdmissionCatalog alloc] initWithResources:resources];
+	TFAdmissionContext *context = [TFAdmissionContext new];
+	context.identifier = [NSString stringWithFormat:@"%@.%lu", self.installation, (unsigned long)++self.contextSequence];
+	context.mapId = mapId; context.catalog = catalog;
+	self.contexts[context.identifier] = context;
+	return context.identifier;
+}
+- (NSUInteger)extendContext:(NSString *)identifier resources:(NSArray<NSDictionary *> *)resources {
+	TFAdmissionContext *context = self.contexts[identifier];
+	if (!context || !context.alive->value.load() || ![self isOwner]) TFInvalidAdmission();
+	// Append-only identity permits replay of an acknowledgement and theme rollback.
+	TFAdmissionCatalog *next = [context.catalog extending:resources];
+	context.catalog = next;
+	return next.resources.count;
+}
+- (TFAdmissionStartGuard)contextGuard:(NSString *)identifier {
+	TFAdmissionContext *context = self.contexts[identifier];
+	if (!context || !context.alive->value.load() || ![self isOwner]) TFInvalidAdmission();
+	TFAdmissionFlag *alive = context.alive;
+	// Capture only the original atomic lifetime, never a mutable registry lookup off-thread.
+	return [^BOOL {
+		@try { return alive->value.load() && self->_foreground.load() && [self isOwner]; }
+		@catch (NSException *exception) { return NO; }
+	} copy];
+}
+- (NSDictionary *)resource:(NSString *)url context:(TFAdmissionContext *)context {
+	@try { return [context.catalog find:url]; }
+	@catch (NSException *exception) { return nil; }
+}
+
+- (id<TFAdmissionCancel>)request:(NSURLRequest *)request response:(void (^)(NSHTTPURLResponse *, NSData *))response failure:(dispatch_block_t)failure delegate:(TFAdmissionDelegate)delegate {
+	// Reserve before posting to the main scheduler, not after it drains.
+	// This bounds ingress as well as the per-context admitted work queues.
+	if (self->_reservations.fetch_add(1) >= 2048) {
+		self->_reservations.fetch_sub(1); failure();
+		return [[TFAdmissionCancellation alloc] initWithAction:^{}];
+	}
+	TFAdmissionFlag *reserved = [TFAdmissionFlag new];
+	dispatch_block_t release = ^{ if (reserved->value.exchange(false)) self->_reservations.fetch_sub(1); };
+	TFAdmissionFlag *alive = [TFAdmissionFlag new];
+	__block TFAdmissionWork *work = nil;
+	[self.scheduler enqueue:^{
+		if (!alive->value.load()) { release(); return; }
+		NSDictionary *tagged;
+		@try { tagged = TFAdmissionStripContext(request.URL.absoluteString); }
+		@catch (NSException *exception) { alive->value.store(false); release(); failure(); return; }
+		TFAdmissionContext *context = self.contexts[tagged[@"context"]];
+		if (!self->_foreground.load() || ![self isOwner] || !context || !context.alive->value.load() || ![self resource:tagged[@"url"] context:context] || context.work.count >= 128 ||
+			![request.HTTPMethod isEqual:@"GET"] || request.HTTPBody || request.HTTPBodyStream ||
+			[request valueForHTTPHeaderField:TFAdmissionGrantHeader] != nil || self.ticketSequence >= 9007199254740991ULL) {
+			alive->value.store(false); release(); failure(); return;
+		}
+		NSMutableURLRequest *clean = [request mutableCopy];
+		clean.URL = [NSURL URLWithString:tagged[@"url"]];
+		work = [TFAdmissionWork new];
+		work.identifier = [NSString stringWithFormat:@"%lu", (unsigned long)++self.ticketSequence];
+		work.context = context; work.request = clean; work.alive = alive; work.entered = [self.scheduler nowMs]; work.phase = @"queue";
+		work.response = response; work.failure = failure; work.delegate = delegate; work.releaseReservation = release;
+		context.work[work.identifier] = work; [context.order addObject:work.identifier];
+		work.timer = [self.scheduler after:30000 perform:^{
+			if ([context.batchTickets containsObject:work.identifier]) [self retire:context.identifier];
+			else [self fail:work];
+		}];
+		[self.scheduler enqueue:^{ [self drain:context]; }];
+	}];
+	return [[TFAdmissionCancellation alloc] initWithAction:^{
+		if (!alive->value.exchange(false)) return;
+		[self.scheduler enqueue:^{
+			if (!work) return;
+			if ([work.context.batchTickets containsObject:work.identifier]) [self event:work.context kind:@"cancel" fields:@{@"tickets": @[work.identifier]}];
+			[self finish:work];
+		}];
+	}];
+}
+
+- (void)drain:(TFAdmissionContext *)context {
+	if (!context.alive->value.load() || !self->_foreground.load() || ![self isOwner] || context.batch) return;
+	NSMutableArray<TFAdmissionWork *> *selected = [NSMutableArray array];
+	for (NSString *identifier in context.order) {
+		TFAdmissionWork *work = context.work[identifier];
+		if (work.alive->value.load() && [work.phase isEqual:@"queue"]) [selected addObject:work];
+		if (selected.count == 8) break;
+	}
+	if (!selected.count) return;
+	if (context.sequence >= 9007199254740991ULL) { [self retire:context.identifier]; return; }
+	NSString *batch = [NSString stringWithFormat:@"%lu", (unsigned long)++context.sequence];
+	context.batch = batch;
+	NSMutableArray *tickets = [NSMutableArray array], *identifiers = [NSMutableArray array];
+	for (TFAdmissionWork *work in selected) {
+		work.phase = @"javascript";
+		[tickets addObject:@{@"ticket": work.identifier, @"url": work.request.URL.absoluteString}];
+		[identifiers addObject:work.identifier];
+	}
+	context.batchTickets = [identifiers copy];
+	context.batchTimer = [self.scheduler after:30000 perform:^{ if ([context.batch isEqual:batch]) [self retire:context.identifier]; }];
+	[self event:context kind:@"batch" fields:@{@"batch": batch, @"tickets": tickets}];
+}
+
+- (BOOL)authority:(NSDictionary *)authority allows:(NSDictionary *)resource context:(TFAdmissionContext *)context {
+	return resource && [authority[@"mapId"] isEqual:context.mapId] && [authority[@"resourceOrigins"] containsObject:TFAdmissionOrigin(resource[@"url"])] &&
+		[authority[@"resourceScopes"] containsObject:resource[@"scope"]] &&
+		(![resource[@"scope"] isEqual:@"style"] || TFAdmissionStyleMatchesMap(resource[@"url"], context.mapId)) &&
+		(!resource[@"tilesetId"] || [authority[@"tilesetIds"] containsObject:resource[@"tilesetId"]]);
+}
+- (BOOL)validAuthority:(NSDictionary *)authority {
+	if (![authority isKindOfClass:NSDictionary.class] || !TFGrantShape(authority[@"grant"]) || !TFString(authority[@"mapId"], 64)) return NO;
+	for (NSString *key in @[@"resourceOrigins", @"resourceScopes", @"tilesetIds"]) {
+		NSArray *array = authority[key];
+		NSUInteger maximum = [key isEqual:@"resourceOrigins"] ? 2 : [key isEqual:@"resourceScopes"] ? 6 : 18;
+		if (![array isKindOfClass:NSArray.class] || array.count > maximum) return NO;
+		for (id value in array) if (!TFString(value, 2048)) return NO;
+	}
+	return YES;
+}
+
+- (NSUInteger)completeContext:(NSString *)identifier generation:(NSUInteger)generation batch:(NSString *)batch results:(NSArray<NSDictionary *> *)results {
+	TFAdmissionContext *context = self.contexts[identifier];
+	if (!context || !context.alive->value.load() || !context.batch || generation != 1 || ![context.batch isEqual:batch] || ![self isOwner]) return 0;
+	if (![results isKindOfClass:NSArray.class] || results.count > 8 || results.count != context.batchTickets.count) { [self retire:identifier]; return 0; }
+	for (NSUInteger index = 0; index < results.count; index++) {
+		if (![results[index] isKindOfClass:NSDictionary.class] || ![results[index][@"ticket"] isEqual:context.batchTickets[index]]) { [self retire:identifier]; return 0; }
+	}
+	[context.batchTimer cancel]; context.batchTimer = nil; context.batch = nil; context.batchTickets = nil;
+	NSUInteger accepted = 0;
+	for (NSDictionary *result in results) {
+		TFAdmissionWork *work = context.work[result[@"ticket"]];
+		if (!work) continue;
+		if (!work.alive->value.load()) { [self finish:work]; continue; }
+		if (!self->_foreground.load() || [self.scheduler nowMs] - work.entered >= 30000) { [self fail:work]; continue; }
+		if ([result[@"kind"] isEqual:@"delegate"] && !context.mapId) {
+			work.phase = @"network"; work.deadline = work.entered + 30000;
+			if (![self canStart:work]) { [self fail:work]; continue; }
+			@try {
+				work.cancellation = work.delegate(work.request, ^(NSHTTPURLResponse *response, NSData *body) {
+					[self.scheduler enqueue:^{ [self received:work url:work.request.URL response:response body:body]; }];
+				});
+				if (!work.alive->value.load()) [work.cancellation cancel];
+				accepted++;
+			} @catch (NSException *exception) { [self fail:work]; }
+			continue;
+		}
+		NSDictionary *authority = result[@"authority"];
+		NSDictionary *resource = [self resource:work.request.URL.absoluteString context:context];
+		if (![result[@"kind"] isEqual:@"grant"] || !context.mapId || !TFExactNumber(result[@"validForMs"], 1, 900000) ||
+			![self validAuthority:authority] || ![self authority:authority allows:resource context:context]) { [self fail:work]; continue; }
+		work.authority = [authority copy];
+		// The budget is already based on the controller's original local
+		// deadline. Anchor it earlier, at enqueue, not at bridge receipt.
+		work.deadline = MIN(work.entered + 30000, work.entered + [result[@"validForMs"] doubleValue] - 1000);
+		if ([self start:work url:work.request.URL]) accepted++;
+	}
+	[self.scheduler enqueue:^{ [self drain:context]; }];
+	return accepted;
+}
+
+- (BOOL)canStart:(TFAdmissionWork *)work {
+	if (!work.alive->value.load() || !work.context.alive->value.load() || !self->_active.load() || !self->_foreground.load() || [self.scheduler nowMs] >= work.deadline) return NO;
+	if (!self.owns()) { [self loseOwnership]; return NO; }
+	return YES;
+}
+- (BOOL)start:(TFAdmissionWork *)work url:(NSURL *)url {
+	NSDictionary *resource = [self resource:url.absoluteString context:work.context];
+	if (!resource || !work.authority || ![self authority:work.authority allows:resource context:work.context] || ![self canStart:work]) { [self fail:work]; return NO; }
+	NSMutableURLRequest *request = [work.request mutableCopy];
+	request.URL = url;
+	request.timeoutInterval = MAX(0.001, (work.deadline - [self.scheduler nowMs]) / 1000.0);
+	[request setValue:work.authority[@"grant"] forHTTPHeaderField:TFAdmissionGrantHeader];
+	work.phase = @"network";
+	@try {
+		work.cancellation = [self.network start:request mayStart:^BOOL { return [self canStart:work]; }
+			completion:^(NSHTTPURLResponse *response, NSData *body) {
+				[self.scheduler enqueue:^{ [self received:work url:url response:response body:body]; }];
+			}];
+		if (!work.alive->value.load()) [work.cancellation cancel];
+		return YES;
+	} @catch (NSException *exception) { [self fail:work]; return NO; }
+}
+
+- (void)received:(TFAdmissionWork *)work url:(NSURL *)url response:(NSHTTPURLResponse *)response body:(NSData *)body {
+	if (!work.alive->value.load() || !work.context.alive->value.load()) return;
+	if (![self isOwner]) return;
+	if (!response || !body || body.length > 8388608 || !self->_foreground.load() || [self.scheduler nowMs] >= work.deadline) { [self fail:work]; return; }
+	[self event:work.context kind:@"response" fields:@{@"status": @(response.statusCode)}];
+	if (work.authority && [@[@301, @302, @303, @307, @308] containsObject:@(response.statusCode)]) {
+		if (++work.redirects > 3) { [self fail:work]; return; }
+		NSString *location = [response valueForHTTPHeaderField:@"Location"];
+		@try {
+			if (!TFString(location, 2048) || !location.length || [location containsString:@"\\"]) TFInvalidAdmission();
+			NSString *target = [NSURL URLWithString:location relativeToURL:url].absoluteURL.absoluteString;
+			if (TFAdmissionHasReservedContext(target)) {
+				NSDictionary *tagged = TFAdmissionStripContext(target);
+				if (![tagged[@"context"] isEqual:work.context.identifier]) TFInvalidAdmission();
+				target = tagged[@"url"];
+			} else TFAdmissionCleanURL(target);
+			if (![TFAdmissionOrigin(target) isEqual:TFAdmissionOrigin(work.request.URL.absoluteString)]) TFInvalidAdmission();
+			[self start:work url:[NSURL URLWithString:target]];
+		} @catch (NSException *exception) { [self fail:work]; }
+		return;
+	}
+	if (!work.alive->value.exchange(false)) return;
+	[self finish:work];
+	work.response(response, body);
+}
+- (void)finish:(TFAdmissionWork *)work {
+	work.alive->value.store(false);
+	[work.cancellation cancel]; work.cancellation = nil;
+	[work.timer cancel]; work.timer = nil; work.authority = nil;
+	[work.context.work removeObjectForKey:work.identifier]; [work.context.order removeObject:work.identifier];
+	if (work.releaseReservation) work.releaseReservation();
+	work.releaseReservation = nil;
+	[self.scheduler enqueue:^{ [self drain:work.context]; }];
+}
+- (void)fail:(TFAdmissionWork *)work {
+	BOOL notify = work.alive->value.exchange(false);
+	[self finish:work];
+	if (notify) work.failure();
+}
+- (void)retire:(NSString *)identifier {
+	TFAdmissionContext *context = self.contexts[identifier];
+	if (!context) return;
+	[self.contexts removeObjectForKey:identifier]; context.alive->value.store(false);
+	[context.batchTimer cancel]; context.batchTimer = nil; context.batch = nil; context.batchTickets = nil;
+	for (TFAdmissionWork *work in context.work.allValues) [self fail:work];
+	[self event:context kind:@"retired" fields:@{@"code": @"NATIVE_ADMISSION_CANCELLED"}];
+}
+- (void)lifecycle:(BOOL)foreground {
+	self->_foreground.store(foreground);
+	if (!foreground) for (TFAdmissionContext *context in self.contexts.allValues) {
+		if (context.batchTickets.count) [self event:context kind:@"cancel" fields:@{@"tickets": context.batchTickets}];
+		for (TFAdmissionWork *work in context.work.allValues) [self fail:work];
+	}
+	[self safeEmit:@{@"kind": @"lifecycle", @"installation": self.installation, @"foreground": @(foreground)}];
+	if (foreground) for (TFAdmissionContext *context in self.contexts.allValues) [self.scheduler enqueue:^{ [self drain:context]; }];
+}
+- (void)close {
+	self->_active.store(false);
+	for (NSString *identifier in self.contexts.allKeys) [self retire:identifier];
+}
+- (BOOL)isOwner {
+	if (!self->_active.load()) return NO;
+	if (!self.owns()) { [self loseOwnership]; return NO; }
+	return YES;
+}
+- (void)loseOwnership {
+	self->_active.store(false);
+	if (self->_lossQueued.exchange(true)) return;
+	[self.scheduler enqueue:^{
+		[self close];
+		[self safeEmit:@{@"kind": @"ownershipLost", @"installation": self.installation}];
+	}];
+}
+- (void)event:(TFAdmissionContext *)context kind:(NSString *)kind fields:(NSDictionary *)fields {
+	NSMutableDictionary *event = [@{@"kind": kind, @"installation": self.installation, @"context": context.identifier, @"generation": @1} mutableCopy];
+	[event addEntriesFromDictionary:fields];
+	[self safeEmit:event];
+}
+- (void)safeEmit:(NSDictionary *)event {
+	@try { self.emit(event); }
+	@catch (NSException *exception) { [self close]; }
+}
+@end

package/ios/TFAdmissionInstallation.h

@@ -0,0 +1,27 @@
+#import "TFAdmissionEngine.h"
+
+NS_ASSUME_NONNULL_BEGIN
+@class MLNNetworkConfiguration;
+@interface TFAdmissionInstallation : NSObject
+@property (nonatomic, readonly) NSString *identifier;
+@property (nonatomic, readonly) TFAdmissionEngine *engine;
+- (instancetype)initWithEmitter:(void (^)(NSDictionary *event))emit;
+// Private deterministic native harness seams; not exposed over React Native.
+- (instancetype)initWithScheduler:(id<TFAdmissionScheduler>)scheduler
+	network:(nullable id<TFAdmissionNetwork>)network
+	emit:(void (^)(NSDictionary *event))emit;
+- (instancetype)initWithConfiguration:(MLNNetworkConfiguration *)configuration
+	scheduler:(id<TFAdmissionScheduler>)scheduler
+	network:(nullable id<TFAdmissionNetwork>)network
+	emit:(void (^)(NSDictionary *event))emit;
+- (BOOL)ownsConfiguration;
+- (NSDictionary *)remove;
+- (id<TFAdmissionCancel>)delegateRequest:(NSURLRequest *)request
+	mayStart:(TFAdmissionStartGuard)guard completion:(TFAdmissionNetworkCompletion)completion;
+@end
+
+@interface TFNativeAdmissionURLProtocol : NSURLProtocol
++ (nullable TFAdmissionInstallation *)activeInstallation;
++ (void)setActiveInstallation:(nullable TFAdmissionInstallation *)installation;
+@end
+NS_ASSUME_NONNULL_END

package/ios/TFAdmissionInstallation.mm

@@ -0,0 +1,117 @@
+#import "TFAdmissionInstallation.h"
+#import "TFAdmissionNetwork.h"
+#import <MapLibre/MLNNetworkConfiguration.h>
+
+@interface TFAdmissionInstallation ()
+@property (nonatomic, readwrite) NSString *identifier;
+@property (nonatomic, readwrite) TFAdmissionEngine *engine;
+@property (nonatomic) MLNNetworkConfiguration *manager;
+@property (nonatomic) NSURLSessionConfiguration *previous;
+@property (nonatomic) NSURLSessionConfiguration *installed;
+@property (nonatomic) NSArray<Class> *protocols;
+@property (nonatomic) NSDictionary *additionalHeaders;
+@property (nonatomic, nullable) id<MLNNetworkConfigurationDelegate> previousDelegate;
+@property (nonatomic, nullable) TFAdmissionURLSessionNetwork *protectedNetwork;
+@property (nonatomic) TFAdmissionURLSessionNetwork *previousNetwork;
+@property (atomic) BOOL active;
+@property (nonatomic, nullable) NSDictionary *removal;
+@end
+
+@implementation TFAdmissionInstallation
+- (instancetype)initWithEmitter:(void (^)(NSDictionary *))emit {
+	return [self initWithScheduler:[TFContinuousAdmissionScheduler new] network:nil emit:emit];
+}
+- (instancetype)initWithScheduler:(id<TFAdmissionScheduler>)scheduler network:(id<TFAdmissionNetwork>)network emit:(void (^)(NSDictionary *))emit {
+	return [self initWithConfiguration:MLNNetworkConfiguration.sharedManager scheduler:scheduler network:network emit:emit];
+}
+- (instancetype)initWithConfiguration:(MLNNetworkConfiguration *)configuration scheduler:(id<TFAdmissionScheduler>)scheduler network:(id<TFAdmissionNetwork>)network emit:(void (^)(NSDictionary *))emit {
+	if ((self = [super init])) {
+		if ([TFNativeAdmissionURLProtocol activeInstallation]) [self invalid];
+		_manager = configuration;
+		_previous = _manager.sessionConfiguration;
+		_previousDelegate = _manager.delegate;
+		// A custom session factory bypasses sessionConfiguration.
+		if (!_manager || !_previous || _previous.identifier || [_previousDelegate respondsToSelector:@selector(sessionForNetworkConfiguration:)] ||
+			[_previous.protocolClasses containsObject:TFNativeAdmissionURLProtocol.class]) [self invalid];
+		for (NSString *name in _previous.HTTPAdditionalHeaders) {
+			if ([name caseInsensitiveCompare:TFAdmissionGrantHeader] == NSOrderedSame) [self invalid];
+		}
+		@try {
+			_identifier = NSUUID.UUID.UUIDString;
+			_installed = [_previous copy];
+			_protocols = [@[TFNativeAdmissionURLProtocol.class] arrayByAddingObjectsFromArray:_previous.protocolClasses ?: @[]];
+			_installed.protocolClasses = _protocols;
+			_additionalHeaders = [_installed.HTTPAdditionalHeaders copy] ?: @{};
+			_previousNetwork = [[TFAdmissionURLSessionNetwork alloc] initWithConfiguration:_previous followsRedirects:YES];
+			if (!network) {
+				NSURLSessionConfiguration *privateConfiguration = NSURLSessionConfiguration.ephemeralSessionConfiguration;
+				privateConfiguration.protocolClasses = @[];
+				privateConfiguration.URLCache = nil;
+				privateConfiguration.HTTPCookieStorage = nil;
+				privateConfiguration.URLCredentialStorage = nil;
+				privateConfiguration.HTTPShouldSetCookies = NO;
+				privateConfiguration.HTTPAdditionalHeaders = nil;
+				privateConfiguration.requestCachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
+				privateConfiguration.HTTPMaximumConnectionsPerHost = 1;
+				_protectedNetwork = [[TFAdmissionURLSessionNetwork alloc] initWithConfiguration:privateConfiguration followsRedirects:NO];
+				network = _protectedNetwork;
+			}
+			if (!network || !_previousNetwork) [self invalid];
+			_active = YES;
+			__weak TFAdmissionInstallation *weakSelf = self;
+			_engine = [[TFAdmissionEngine alloc] initWithInstallation:_identifier scheduler:scheduler network:network
+				owns:^BOOL { return [weakSelf ownsConfiguration]; } emit:emit];
+			[TFNativeAdmissionURLProtocol setActiveInstallation:self];
+			_manager.sessionConfiguration = _installed;
+			if (![self ownsConfiguration]) [self invalid];
+		} @catch (NSException *exception) {
+			// A setter can mutate before throwing. Restore by identity, not
+			// by whether its call returned, and never overwrite a later owner.
+			@try { [self remove]; } @catch (NSException *cleanupError) {
+				[self.engine close]; [self.protectedNetwork close]; [self.previousNetwork close];
+			}
+			self.active = NO;
+			if ([TFNativeAdmissionURLProtocol activeInstallation] == self) [TFNativeAdmissionURLProtocol setActiveInstallation:nil];
+			[self invalid];
+		}
+	}
+	return self;
+}
+- (NSString *)description { return @"TFAdmissionInstallation(redacted)"; }
+- (BOOL)matchesConfiguration {
+	NSURLSessionConfiguration *current = self.manager.sessionConfiguration;
+	return self.installed && current == self.installed && self.manager.delegate == self.previousDelegate &&
+		[current.protocolClasses isEqual:self.protocols] && [(current.HTTPAdditionalHeaders ?: @{}) isEqual:self.additionalHeaders] &&
+		[TFNativeAdmissionURLProtocol activeInstallation] == self;
+}
+- (BOOL)ownsConfiguration {
+	@try { return self.active && [self matchesConfiguration]; }
+	@catch (NSException *exception) { return NO; }
+}
+- (NSDictionary *)remove {
+	if (self.removal) return self.removal;
+	BOOL owned = [self matchesConfiguration];
+	self.active = NO;
+	[self.engine close];
+	[self.protectedNetwork close]; [self.previousNetwork close];
+	BOOL restored = NO;
+	if (owned) {
+		@try { self.manager.sessionConfiguration = self.previous; }
+		@catch (NSException *exception) {
+			if (self.manager.sessionConfiguration == self.installed) [self invalid];
+		}
+		NSURLSessionConfiguration *after = self.manager.sessionConfiguration;
+		if (after == self.installed) [self invalid];
+		restored = after == self.previous;
+	}
+	if ([TFNativeAdmissionURLProtocol activeInstallation] == self) [TFNativeAdmissionURLProtocol setActiveInstallation:nil];
+	self.removal = @{@"removed": @(restored), @"ownershipLost": @(!restored)};
+	return self.removal;
+}
+- (id<TFAdmissionCancel>)delegateRequest:(NSURLRequest *)request mayStart:(TFAdmissionStartGuard)guard completion:(TFAdmissionNetworkCompletion)completion {
+	return [self.previousNetwork start:request mayStart:guard completion:completion];
+}
+- (void)invalid {
+	@throw [NSException exceptionWithName:@"TFNativeAdmissionOwnership" reason:@"Native network ownership is unavailable" userInfo:nil];
+}
+@end

package/ios/TFAdmissionNetwork.h

@@ -0,0 +1,16 @@
+#import "TFAdmissionEngine.h"
+
+NS_ASSUME_NONNULL_BEGIN
+@interface TFContinuousAdmissionScheduler : NSObject <TFAdmissionScheduler>
+@end
+
+@interface TFAdmissionURLSessionNetwork : NSObject <TFAdmissionNetwork>
+- (instancetype)initWithConfiguration:(NSURLSessionConfiguration *)configuration followsRedirects:(BOOL)followsRedirects;
+- (instancetype)initWithConfiguration:(NSURLSessionConfiguration *)configuration followsRedirects:(BOOL)followsRedirects
+	responseByteLimit:(NSUInteger)responseByteLimit queueDepth:(NSUInteger)queueDepth concurrency:(NSUInteger)concurrency;
+// Internal deterministic harness seam; callers must provide a serial queue.
+- (instancetype)initWithConfiguration:(NSURLSessionConfiguration *)configuration followsRedirects:(BOOL)followsRedirects
+	responseByteLimit:(NSUInteger)responseByteLimit queueDepth:(NSUInteger)queueDepth concurrency:(NSUInteger)concurrency workQueue:(dispatch_queue_t)workQueue;
+- (void)close;
+@end
+NS_ASSUME_NONNULL_END