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

package/README.md

@@ -1,7 +1,219 @@
 # @tileflow/react-native
 
-This bootstrap package registers the npm name for Trusted Publishing. It contains no runtime or
-dependencies and is not an application SDK. Do not use it in an application.
+`@tileflow/react-native` provides a Tileflow `Map` backed by MapLibre Native on iOS and Android. It is pre-release. The first alpha release requires the bootstrap and Trusted Publisher checks in the [publishing guide](https://github.com/tileflow/tileflow-sdk/blob/main/PUBLISHING.md).
 
-Once the first runtime alpha is available, install `@tileflow/react-native@alpha` and follow its
-packaged README. This version is reserved for package registration, not the alpha channel.
+The package targets exactly React 19.2.0, React Native 0.83.10 and `@maplibre/maplibre-react-native` 11.3.10, with MapLibre Native Android 13.2.0 and iOS 6.26.0 through the pinned integration below. Expo consumers use Expo 55.0.31 with a native development build; Expo Go does not contain the required native modules.
+
+> Related packages and guides: [documentation index](https://raw.githubusercontent.com/tileflow/tileflow-sdk/main/llms.txt).
+
+## Install
+
+Start with an Expo development build or a bare React Native application matching those peers. Once the first alpha is available, install the package and its direct dependencies:
+
+```sh
+npm install --save-exact @tileflow/react-native@alpha @tileflow/core@alpha @tileflow/interactions@alpha @maplibre/maplibre-react-native@11.3.10
+```
+
+Keep the lockfile. Complete the [native integration](#native-integration) before building the application. Source on `main` can precede npm; installation or local checks do not establish Hosted availability or physical-device acceptance.
+
+The package exports a mounted `Map` and its public types from the ordinary package root. Importing the package does not install native networking, read application configuration, create a Map, start a session, acquire admission, schedule timers or perform network I/O. Those effects begin only inside a mounted component lifecycle.
+
+Tileflow `Map` is **Tileflow-only**. Its `source` is the existing Tileflow descriptor object:
+
+<!-- docs:check -->
+
+```tsx
+import {Map} from '@tileflow/react-native';
+
+export function StoreMap() {
+  return (
+    <Map
+      source={{
+        map: 'stores',
+        manifestUrl: 'https://maps.example.com/tileflow/manifest.json',
+      }}
+      theme="light"
+      style={{flex: 1}}
+      testID="store-map"
+    />
+  );
+}
+```
+
+There is no public renderer discriminator, arbitrary `mapStyle`, credential prop, Hosted client, Provider, admission API, native handle or MapLibre ref. An application that needs a wholly unmanaged MapLibre map should use `@maplibre/maplibre-react-native` directly.
+
+## Mounted ownership
+
+One mounted Tileflow `Map` owns one current source generation, one private Hosted binding/session/controller when required, one native admission context and one upstream MapLibre Map. Multiple mounted Maps may share only the acknowledged process-level networking installation; they never share contexts, sessions, grants, generations, abort state, callbacks or renderer ownership.
+
+The upstream native Map is not created until the source is resolved and its private admission context has been acknowledged. Hosted session delivery also requires the application configuration and bootstrap path to be ready. Non-session sources do not read mobile application configuration or acquire Hosted authority.
+
+Changing a theme keeps the same native Map, context and session. Replacing the logical source retires the previous owner before the replacement can open another context. Ordinary changes to callback identity, `children`, `style`, `testID` or unchanged semantic props do not recreate the source/session/native owner.
+
+Application-owned MapLibre children that are valid children of the upstream Map remain composable. Tileflow still owns the Map style, networking, camera lifecycle callbacks and readiness callbacks.
+
+## Source and theme
+
+Native sources keep the explicit shape:
+
+```ts
+{
+  map: 'stores',
+  manifestUrl: 'https://maps.example.com/tileflow/manifest.json',
+}
+```
+
+There is no implicit native manifest discovery. `theme` accepts one concrete published theme or `system`. A `system` selection subscribes to React Native Appearance only while that selection is mounted. Theme application is transactional: a new concrete style is prepared and applied on the same Map, becomes current only after native readiness, and attempts to restore the previous accepted style if the replacement fails.
+
+For the CLI's Native preview, explicitly permit its HTTP origin in the source:
+
+```tsx
+<Map
+  source={{
+    map: 'stores',
+    manifestUrl: 'http://127.0.0.1:3333/native/manifest.json',
+    developmentOrigin: 'http://127.0.0.1:3333',
+  }}
+/>
+```
+
+Use an address reachable from the target device. The exception covers only that exact scheme,
+host and port, including relative styles and resources; other origins still require HTTPS.
+Keep it in development configuration. The application owns any iOS ATS or Android cleartext
+exception. Changing or removing the origin retires the previous source owner. Hosted credentials
+and protected delivery still require HTTPS.
+
+`onThemeChange` reports only the safe public selection shape. It does not expose style URLs, style JSON, configuration, session authority or native error messages.
+
+## Camera
+
+The existing mount-stable camera contract is preserved. Use either an initial camera seed or complete controlled camera ownership for the lifetime of one mounted Map:
+
+```tsx
+<Map source={source} initialView={{center: [-9.14, 38.72], zoom: 11}} />
+```
+
+or:
+
+```tsx
+<Map
+  source={source}
+  view={{center, zoom, bearing, pitch}}
+  onViewChange={(event) => setView(event.view)}
+/>
+```
+
+Controlled mode requires a complete view and `onViewChange`. Programmatic camera operations are private. Native command receipts are correlated internally and are not inferred from delayed region callbacks. Gesture changes are the only camera changes emitted publicly; their controlled settlement occurs after the subsequent React commit. Theme/style restoration preserves the current camera owner.
+
+No public imperative camera API or raw upstream Map ref is exported.
+
+## Readiness
+
+`onLoad` means that the current native style was accepted for the mounted generation. It is not a rendered-frame receipt.
+
+`onReadinessChange({status: 'ready'})` requires all of the following for the current generation:
+
+- current native style acceptance;
+- a committed positive native layout/view barrier;
+- a fully rendered native map/frame after that barrier;
+- foreground lifecycle state.
+
+Readiness is invalidated by source/style transactions, layout changes, camera gesture/command epochs and backgrounding. Resume requires fresh native evidence; JavaScript animation frames, sleeps and arbitrary timers are not readiness proof.
+
+## Bounded resource preparation
+
+Before native rendering, the mounted owner prepares a bounded closure for the current style. It covers the owned style document, one TileJSON edge per tile source, tile templates, sprite leaves, glyph templates, native-v1 managed font faces and supported base-asset URLs represented by the accepted contracts.
+
+Relative URLs are resolved with Core's native URL policy. Protected resources are appended to the per-Map admission catalog only after native acknowledgement. Resource scope and tileset identity are preserved. Foreign/unowned resources are left unchanged and never receive Tileflow authority. Recursive, ambiguous, oversized or dynamically unbounded protected graphs fail closed.
+
+Glyph templates use a finite set of exact font-stack expansions. A later theme may extend that same template only through an acknowledged append-only finite union; it cannot change the resource scope, origin or identity.
+
+See [Private native resource admission](./docs/native-admission.md) for the transport and security boundaries.
+
+## Hosted mobile application configuration
+
+Hosted native session delivery uses a scoped, revocable, publishable **mobile application credential** configured once in the native application. It authenticates the distributed application, not its end user. The manifest supplies `mapId`, `apiUrl` and `usageMode`; Tileflow requires the manifest API origin to exactly match the configured canonical HTTPS origin before bootstrap.
+
+There is intentionally no credential prop, JS setter, Provider, client object, package-name/bundle-ID authentication or attestation path in this version.
+
+See [Native application configuration](./docs/native-configuration.md) for the exact Android resource and iOS Info.plist keys, credential grammar, origin normalization, rotation/revocation guidance and threat model.
+
+## Map options and presentation
+
+The public `mapOptions` object remains a positive allowlist. It includes the currently supported gesture/control options only. Style inputs, request transformation, headers and upstream lifecycle callbacks remain owned by Tileflow. Runtime validation rejects forged extra keys without reflecting their values.
+
+React Native `style`, `testID` and React children are preserved as presentation/composition inputs and do not become semantic source identity.
+
+## Safe events and ref
+
+The public lifecycle surface remains:
+
+- `onLoad`;
+- `onError`;
+- `onReadinessChange`;
+- `onThemeChange`;
+- controlled `onViewChange`;
+- `ref.getSourceState()`.
+
+`getSourceState()` returns only the last safe projected source snapshot. Errors use existing bounded codes/fields/kinds. No URL, response body, native event, credential, grant, session object, native handle or raw cause enters public callbacks, refs or serializable state.
+
+## Native integration
+
+Autolinking registers the private Android/iOS modules used by the mounted lifecycle. Android depends on the exact MapLibre React Native project and MapLibre Native 13.2.0. iOS uses the existing MapLibre React Native CocoaPod plus the exact MapLibre Native 6.26.0 Swift Package Manager product.
+
+For the iOS post-install integration, retain the host's normal React Native/MapLibre setup and then call:
+
+```ruby
+$MLRN.post_install(installer)
+tileflow_native_admission_post_install(installer)
+```
+
+Do not add a second MapLibre Native CocoaPod. See [Private native resource admission](./docs/native-admission.md) for installation-order and teardown details.
+
+## Source-checkout harness
+
+`harness/AdmissionHarness.tsx` mounts the real public Tileflow `Map` in an existing development host, including two simultaneous Maps under React `StrictMode`. It provides deterministic source-checkout controls for source replacement, theme transactions, controlled camera updates and teardown. The harness is excluded from exports and packed files and creates no service or runner. See [the harness guide](./harness/README.md).
+
+## Interactions and markers
+
+`Map` accepts portable `annotations`, semantic `interactions`, activation and diagnostic callbacks,
+and an optional marker renderer. Annotation data stays typed through a generic `Map`:
+
+```tsx
+<Map
+  source={source}
+  annotations={places}
+  interactions={bindings}
+  onInteractionEvent={(event) => {
+    selectPlace(event.target);
+  }}
+  renderMarker={({annotation}) => <PlaceMarker place={annotation.data} />}
+/>
+```
+
+Tileflow owns each stable native marker host, its coordinate, touch activation and accessibility
+wrapper. A bounded accessible marker is rendered when `renderMarker` is omitted. Large feature sets
+remain in native vector or GeoJSON layers and are selected through semantic rendered-feature
+queries rather than thousands of React marker views.
+
+The application owns persistent selection and its presentation. The SDK emits normalized
+annotation or POI targets but no popup, callout, tooltip, sheet, panel or modal renderer. See
+[Native interaction contract](./docs/native-interactions.md).
+
+## Current boundary
+
+The mounted component does not add location, selection-presentation UI, offline product APIs, an
+Expo config plugin, CLI behavior, deployment or publication. The package remains pre-release.
+
+Source and tests describe contracts; they do not establish that a native build, simulator/device run, Hosted service, app-store submission or package publication succeeded. Qualify the exact source revision in the intended host before relying on it.
+
+## Foreground location is application-owned
+
+`Map` does not request location permission, start a provider, track the device or recenter when a
+fix arrives. Applications can compose a validated foreground fix through the existing accessible
+annotation and controlled-camera contracts while keeping permission, provider lifetime, privacy
+policy, status UI and recenter controls outside Tileflow.
+
+See [Application-owned foreground location](./docs/native-location.md) for the package-owned
+source-checkout recipe. The recipe is excluded from package exports and packed runtime files and
+imports no concrete location provider.

package/TileflowNativeAdmission.podspec

@@ -0,0 +1,34 @@
+require 'json'
+require_relative 'ios/tileflow_native_admission'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+	s.name = 'TileflowNativeAdmission'
+	s.version = package['version'].delete_suffix('-development')
+	s.summary = 'Private mounted Map transport and lifecycle adapters for Tileflow.'
+	s.homepage = package['homepage']
+	s.authors = 'Tileflow'
+	s.license = { :type => 'Apache-2.0', :file => File.exist?(File.join(__dir__, 'LICENSE')) ? 'LICENSE' : '../../LICENSE' }
+	# This private development pod is consumed by local path/autolinking.
+	s.source = { :git => 'https://github.com/tileflow/tileflow-sdk.git' }
+	s.platforms = { :ios => '15.1' }
+	s.source_files = 'ios/*.{h,mm}'
+	s.private_header_files = 'ios/*.h'
+	s.frameworks = 'Foundation', 'UIKit'
+	s.libraries = 'c++'
+	s.dependency 'React-Core', '0.83.10'
+	s.dependency 'MapLibreReactNative', '11.3.10'
+	# Surface integration consumes only the pinned peer's private native view/camera headers.
+	# No Tileflow native header is promoted to a public CocoaPods header.
+	s.pod_target_xcconfig = {
+		'HEADER_SEARCH_PATHS' => '$(inherited) "${PODS_ROOT}/Headers/Private" "${PODS_ROOT}/Headers/Private/MapLibreReactNative"'
+	}
+	# MapLibre itself is an exact SPM product, not a second CocoaPods SDK.
+	install_modules_dependencies(s)
+
+	s.test_spec 'Admission' do |tests|
+		tests.source_files = 'ios/Tests/*.mm'
+		tests.requires_app_host = true
+	end
+end

package/android/build.gradle

@@ -0,0 +1,43 @@
+apply plugin: 'com.android.library'
+
+// The host React Native project owns AGP and Kotlin plugin versions.
+def agpMajor = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')[0].toInteger()
+if (agpMajor < 9 || (agpMajor == 9 && !providers.gradleProperty('android.builtInKotlin').getOrElse('true').toBoolean())) {
+	apply plugin: 'org.jetbrains.kotlin.android'
+}
+
+def nativeVersion = rootProject.ext.has('org.maplibre.reactnative.nativeVersion') ? rootProject.ext.get('org.maplibre.reactnative.nativeVersion').toString() : '13.2.0'
+def nativeVariant = rootProject.ext.has('org.maplibre.reactnative.nativeVariant') ? rootProject.ext.get('org.maplibre.reactnative.nativeVariant').toString() : 'opengl'
+if (nativeVersion != '13.2.0') throw new GradleException('Tileflow native admission requires MapLibre Native 13.2.0')
+
+android {
+	namespace 'dev.tileflow.reactnative'
+	compileSdkVersion rootProject.ext.has('compileSdkVersion') ? rootProject.ext.get('compileSdkVersion') : 36
+	defaultConfig {
+		minSdkVersion rootProject.ext.has('minSdkVersion') ? rootProject.ext.get('minSdkVersion') : 24
+		targetSdkVersion rootProject.ext.has('targetSdkVersion') ? rootProject.ext.get('targetSdkVersion') : 36
+	}
+	compileOptions {
+		sourceCompatibility JavaVersion.VERSION_17
+		targetCompatibility JavaVersion.VERSION_17
+	}
+	if (project.plugins.hasPlugin('org.jetbrains.kotlin.android')) {
+		kotlinOptions { jvmTarget = '17' }
+	}
+	testOptions { unitTests.includeAndroidResources = true }
+}
+
+repositories {
+	google()
+	mavenCentral()
+}
+
+dependencies {
+	implementation project(':maplibre_maplibre-react-native')
+	implementation('com.facebook.react:react-android:0.83.10') { version { strictly '0.83.10' } }
+	implementation("org.maplibre.gl:android-sdk-${nativeVariant}:13.2.0") { version { strictly '13.2.0' } }
+	implementation('com.squareup.okhttp3:okhttp:4.12.0') { version { strictly '4.12.0' } }
+	testImplementation 'junit:junit:4.13.2'
+	testImplementation 'org.robolectric:robolectric:4.14.1'
+	testImplementation 'com.squareup.okhttp3:mockwebserver:4.12.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+	<uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/dev/tileflow/reactnative/AdmissionBootstrap.kt

@@ -0,0 +1,144 @@
+package dev.tileflow.reactnative
+
+import java.util.concurrent.atomic.AtomicBoolean
+
+internal object AdmissionBootstrapLimits {
+	const val QUEUE = 32
+	const val REQUEST_BYTES = 2048
+	const val RESPONSE_BYTES = 65536
+	const val TIMEOUT_MS = 30000L
+}
+
+internal class AdmissionBootstrapRequest(
+	val url: String,
+	val credential: String,
+	val body: String,
+	val mayStart: () -> Boolean,
+) {
+	override fun toString() = "AdmissionBootstrapRequest(redacted)"
+}
+
+internal class AdmissionBootstrapReply(val status: Int, val cacheControl: String, val body: ByteArray) {
+	override fun toString() = "AdmissionBootstrapReply(redacted)"
+}
+
+internal interface AdmissionBootstrapNetwork {
+	fun start(request: AdmissionBootstrapRequest, completion: (AdmissionBootstrapReply?) -> Unit): AdmissionCancellation
+}
+
+// The serial owner only bounds transport work. It never parses a grant,
+// admits resources, counts commercial requests, or creates session IDs.
+internal class AdmissionBootstrap(
+	private val installation: String,
+	private val scheduler: AdmissionScheduler,
+	private val network: AdmissionBootstrapNetwork,
+	private val owns: () -> Boolean,
+) {
+	private class Context(val mapId: String?) {
+		val live = AtomicBoolean(true)
+		var endpoint: String? = null
+		var credential: String? = null
+		var lastRequest = 0L
+		val pending = linkedMapOf<String, Work>()
+	}
+	private class Work(
+		val id: String,
+		val context: Context,
+		val deadline: Long,
+		val completion: (AdmissionBootstrapReply?) -> Unit,
+	) {
+		val live = AtomicBoolean(true)
+		var network: AdmissionCancellation? = null
+		var timer: AdmissionCancellation? = null
+	}
+	private val contexts = linkedMapOf<String, Context>()
+	private val active = AtomicBoolean(true)
+	@Volatile private var foreground = true
+	private var pendingCount = 0
+	private val mobileCredential = Regex("tf_public_[0-9a-f]{48}")
+	private val bodyPattern = Regex("\\{\"mapId\":\"(map_[A-Za-z0-9_-]{16})\",\"sessionId\":\"([A-Za-z0-9._:-]{1,255})\",\"surfaceId\":\"([a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?)\"\\}")
+
+	override fun toString() = "AdmissionBootstrap(redacted)"
+
+	fun register(context: String, mapId: String?) {
+		if (!active.get() || !owned() || !validContext(context) || contexts.containsKey(context) || contexts.size >= AdmissionLimits.CONTEXTS ||
+			(mapId != null && !Regex("map_[A-Za-z0-9_-]{16}").matches(mapId))) invalid()
+		contexts[context] = Context(mapId)
+	}
+
+	fun start(contextId: String, requestId: String, url: String, credential: String, body: String, completion: (AdmissionBootstrapReply?) -> Unit) {
+		val context = contexts[contextId] ?: invalid()
+		if (!active.get() || !foreground || !owned() || !context.live.get() || context.mapId == null || pendingCount >= AdmissionBootstrapLimits.QUEUE) invalid()
+		val sequence = sequence(requestId)
+		if (sequence <= context.lastRequest || !mobileCredential.matches(credential) || body.length > AdmissionBootstrapLimits.REQUEST_BYTES) invalid()
+		val match = bodyPattern.matchEntire(body) ?: invalid()
+		if (match.groupValues[1] != context.mapId || match.groupValues.drop(2).any { it.startsWith("tf_native_") || mobileCredential.matches(it) }) invalid()
+		AdmissionUrl.clean(url)
+		if (url != AdmissionUrl.origin(url) + "/v1/sessions/start" ||
+			(context.endpoint != null && (context.endpoint != url || context.credential != credential))) invalid()
+		// The validated controller is the source of the first endpoint/credential.
+		// Bind subsequent bootstrap calls to that exact pair for this context.
+		context.endpoint = url; context.credential = credential; context.lastRequest = sequence
+		val work = Work(requestId, context, scheduler.nowMs() + AdmissionBootstrapLimits.TIMEOUT_MS, completion)
+		context.pending[requestId] = work; pendingCount++
+		work.timer = scheduler.after(AdmissionBootstrapLimits.TIMEOUT_MS) { finish(work, null) }
+		try {
+			work.network = network.start(AdmissionBootstrapRequest(url, credential, body) { mayStart(work) }) { reply ->
+				scheduler.dispatch {
+					val valid = mayStart(work) && reply != null && reply.status in 100..599 &&
+						reply.cacheControl.length <= 1024 && reply.body.size <= AdmissionBootstrapLimits.RESPONSE_BYTES
+					finish(work, if (valid) reply else null)
+				}
+			}
+			if (!work.live.get()) work.network?.cancel()
+		} catch (_: Exception) { finish(work, null) }
+	}
+
+	fun cancel(contextId: String, requestId: String) {
+		if (!validContext(contextId)) invalid()
+		val sequence = sequence(requestId)
+		val context = contexts[contextId] ?: return
+		// A cancellation can overtake dispatch. A per-context high-water mark
+		// prevents replay without retaining an unbounded tombstone collection.
+		context.lastRequest = maxOf(context.lastRequest, sequence)
+		context.pending[requestId]?.let { finish(it, null) }
+	}
+
+	fun retire(contextId: String) {
+		val context = contexts.remove(contextId) ?: return
+		context.live.set(false)
+		context.credential = null; context.endpoint = null
+		for (work in context.pending.values.toList()) finish(work, null)
+	}
+
+	fun lifecycle(resumed: Boolean) {
+		foreground = resumed
+		if (!resumed) for (context in contexts.values.toList()) for (work in context.pending.values.toList()) finish(work, null)
+	}
+
+	fun close() {
+		active.set(false)
+		for (context in contexts.keys.toList()) retire(context)
+	}
+
+	private fun mayStart(work: Work): Boolean = active.get() && foreground && work.live.get() && work.context.live.get() &&
+		scheduler.nowMs() < work.deadline && owned()
+
+	private fun finish(work: Work, reply: AdmissionBootstrapReply?) {
+		if (!work.live.compareAndSet(true, false)) return
+		work.context.pending.remove(work.id); pendingCount--
+		work.timer?.cancel(); work.timer = null
+		work.network?.cancel(); work.network = null
+		try { work.completion(reply) } catch (_: Exception) { /* A consumer cannot reopen retired transport work. */ }
+	}
+
+	private fun validContext(value: String) = AdmissionUrl.validToken(value) && value.startsWith("$installation.")
+	private fun sequence(value: String): Long {
+		if (!value.startsWith("$installation.")) invalid()
+		val suffix = value.substring(installation.length + 1)
+		if (!Regex("[1-9][0-9]{0,15}").matches(suffix)) invalid()
+		return suffix.toLongOrNull()?.takeIf { it <= 9007199254740991L } ?: invalid()
+	}
+	private fun owned() = try { owns() } catch (_: Exception) { false }
+	private fun invalid(): Nothing = throw IllegalArgumentException("Invalid native bootstrap")
+}

package/android/src/main/java/dev/tileflow/reactnative/AdmissionBootstrapOkHttpNetwork.kt

@@ -0,0 +1,89 @@
+package dev.tileflow.reactnative
+
+import java.io.ByteArrayOutputStream
+import java.io.IOException
+import java.util.concurrent.TimeUnit
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.Dispatcher
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.Response
+
+internal class AdmissionBootstrapOkHttpNetwork : AdmissionBootstrapNetwork {
+	private class Guard(val mayStart: () -> Boolean) {
+		override fun toString() = "NativeBootstrapGuard(redacted)"
+	}
+	private val lock = Any()
+	private val calls = mutableSetOf<Call>()
+	private var closed = false
+	private val dispatcher = Dispatcher().apply { maxRequests = 4; maxRequestsPerHost = 4 }
+	// Deliberately independent of both MapLibre and protected-resource HTTP.
+	// Defaults use no cookie jar, cache, authenticator, or application logger.
+	private val client = OkHttpClient.Builder()
+		.dispatcher(dispatcher)
+		.followRedirects(false).followSslRedirects(false)
+		.retryOnConnectionFailure(false).cache(null)
+		.connectTimeout(10, TimeUnit.SECONDS)
+		.callTimeout(AdmissionBootstrapLimits.TIMEOUT_MS, TimeUnit.MILLISECONDS)
+		.addNetworkInterceptor { chain ->
+			if (chain.request().tag(Guard::class.java)?.mayStart?.invoke() != true) throw IOException("Native bootstrap is cancelled")
+			chain.proceed(chain.request())
+		}.build()
+
+	override fun start(request: AdmissionBootstrapRequest, completion: (AdmissionBootstrapReply?) -> Unit): AdmissionCancellation {
+		if (!request.mayStart()) { completion(null); return AdmissionCancellation {} }
+		val call = client.newCall(Request.Builder().url(request.url)
+			.post(request.body.toRequestBody("application/json".toMediaType()))
+			.header("X-Tileflow-Mobile-Client", request.credential)
+			.header("Cache-Control", "no-store")
+			.tag(Guard::class.java, Guard(request.mayStart)).build())
+		val accepted = synchronized(lock) {
+			if (closed || calls.size >= AdmissionBootstrapLimits.QUEUE) false else { calls.add(call); true }
+		}
+		if (!accepted) { completion(null); return AdmissionCancellation {} }
+		fun complete(reply: AdmissionBootstrapReply?) {
+			synchronized(lock) { calls.remove(call) }
+			completion(reply)
+		}
+		try {
+			call.enqueue(object : Callback {
+				override fun onFailure(call: Call, error: IOException) { complete(null) }
+				override fun onResponse(call: Call, response: Response) {
+					val reply = try {
+						response.use {
+							val cacheControl = it.header("cache-control") ?: ""
+							val body = it.body
+							if (cacheControl.length > 1024 || body == null || body.contentLength() > AdmissionBootstrapLimits.RESPONSE_BYTES) throw IOException("Invalid bootstrap response")
+							val bytes = ByteArrayOutputStream()
+							body.byteStream().use { stream ->
+								val buffer = ByteArray(4096)
+								while (true) {
+									val count = stream.read(buffer)
+									if (count < 0) break
+									if (!request.mayStart() || count > AdmissionBootstrapLimits.RESPONSE_BYTES - bytes.size()) throw IOException("Invalid bootstrap response")
+									bytes.write(buffer, 0, count)
+								}
+							}
+							AdmissionBootstrapReply(it.code, cacheControl, bytes.toByteArray())
+						}
+					} catch (_: Exception) { null }
+					complete(reply)
+				}
+			})
+		} catch (_: Exception) { call.cancel(); complete(null) }
+		// Retain the capacity reservation until OkHttp's terminal callback.
+		// Repeated cancellation cannot grow its dispatcher queue without bound.
+		return AdmissionCancellation { call.cancel() }
+	}
+
+	fun close() {
+		val pending = synchronized(lock) { closed = true; calls.toList() }
+		for (call in pending) call.cancel()
+		client.connectionPool.evictAll()
+		dispatcher.executorService.shutdown()
+	}
+	override fun toString() = "AdmissionBootstrapOkHttpNetwork(redacted)"
+}