Modules: contract, daemon, leasing, core, drivers (Android, iOS).
How one lease request becomes one concrete device, virtual or physical.
| Source | Where | Read when |
|---|---|---|
Request: model or class, osVersion (exact or range), mode, imageTag, physical, allowDownload, noWait |
contract/operations.ts → DeviceRequest |
Per request |
| Download permission | downloads.policy (on-request), daemon/dispatcher-leases.ts |
Per request, before leasing |
| Default mode | ios.defaultMode (full); Android always full |
Per request with no mode |
| Operator preference lists | ios.defaultModels, android.defaultModels |
Merged once at start |
| Built-in preference lists | Driver.defaultModels of each driver |
Merged once at start, after the operator's |
| Catalog | DriverCatalog.listCatalog → Driver.listCatalog |
Per class or range request; built on every read (Android keeps only its avdmanager list device answer, below) |
| Android profile library (16) | drivers/android/profiles/ |
Static |
| Android SDK profiles | avdmanager list device, kept in AvdmanagerDeviceList |
Asked by each catalog, each resolve of a model the library lacks, each library provision (seed); run again only when the sdklib jar, the tools' source.properties, the user's devices.xml, an image's or add-on's devices.xml, or an extras/<vendor>/<item> extra's devices.xml or source.properties changed size or modified time, appeared or went, or an image was installed or removed; 30 s limit |
| Android devices.xml | $ANDROID_USER_HOME/devices.xml, else .android/devices.xml |
Each catalog; a resolve no earlier source answered |
| Android system images | <sdk>/system-images/android-*/<tag>/<abi> + source.properties |
Each resolve, catalog, provision |
| Android fit rule | drivers/android/image-fit.ts fits |
With every image read |
| iOS device types and runtimes | simctl list -j devicetypes runtimes |
Each resolve, catalog |
| Existing devices | registry snapshot | Each plan |
| Enrolled physical devices | registry snapshot; presence from Driver.listPresentPhysical |
Each physical plan; presence before each grant |
| Warm targets | warmPool.targets (core/warm-pool/config.ts), and the kinds the pool learned from leases (core/warm-pool/learned.ts, state.db) |
Every warm-pool pass, downloads off |
Never read: the sdkmanager catalog. A preference list is merged in daemon/worker-composition.ts
modelPreferenceWiring; nothing else builds it.
In AcquisitionSpecResolver (leasing/acquisition-spec-resolver.ts), a part of LeaseAcquisitionCoordinator, no lock held. A virtualDevices: false platform is refused first (VirtualDevicesOffError), before any catalog read or download:
physical: true→ skip to the physical branch. A virtual Android request with noimageTagon a worker withandroid.defaultImageTagis tried first as if it named that tag, with downloads off anddefaultTagset so only host-CPU images count; aRuntimeMissingErrorruns steps 2 to 9 again on the request as it came (ADR 0078).- Mode = request's, else the platform default.
- Shape of the request:
- exact model, no range → used as is; no catalog read.
- no model, no range → class (none named =
phone). - range → with a model, the model must be listed in the catalog; without, class.
- Class →
classCandidates(core/catalog-match.ts): each preference name the catalog lists (names and aliases, ignoring case) and classes as that class, in list order. First one with a paired runtime the request accepts wins. None listed →UnknownModelError; none paired →RuntimeMissingError. - Range → newest paired runtime in range, passed on as an exact version. A range never installs.
- Image tag → only runtimes whose catalog
imagescarry the tag count. driver.resolveSpec(exact).RuntimeMissingErrorwithdownloadableandcomponent, andallowDownload→ComponentInstallerinstalls, then resolve once more.checkedSpec: tag must equal the request's; a non-slim request getsfullSpec.- Requirement: class or model target, OS (
range,exact, orinstalledfor a class with no OS), image tag. An exact model getsexactRequirement(spec).
Warm targets go through the same steps (resolve) with allowDownload: false; a target names no class. A learned kind is already a resolved spec and is kept ready like a target.
DeviceProfileRegistry.resolve(model): library → SDK → devices.xml; first name match, ignoring case, wins. No match →UnknownModelError.- Scan installed images.
- With
imageTag: images of that tag (at the requested level); none →RuntimeMissingError, never downloadable. Level = requested, else newest that fits. - Without: fitting API levels; level = requested, else newest. No fit →
RuntimeMissingError; downloadable only for an exact level with no image at all and agoogle_apisimage that would fit. - The profile is cached for
provision.modeis ignored: the spec is full.
imageTag→UnsupportedRequestOptionError.- Device type by name, ignoring case. No match →
UnknownModelError. - No OS → newest installed runtime that lists the type and sits inside its min/max range.
- Exact OS → out of range refused; installed and paired → spec; installed, unpaired refused; not installed → downloadable
(
component= the version; below iOS 16 not downloadable). - Slim spec only for a slim request on iOS 18.5+. Device type and runtime cached for
provision.
AcquisitionPlanner.plan (leasing/acquisition-planner.ts), under the lock. A device serves
when mayBeGranted, same pool mode, and fits(requirement, spec, classOf) (core/domain.ts):
same platform, same image tag, model equal or classOf(model) equal to the class, OS satisfied.
classOf reads the catalog entry read during resolution; a device record stores no class.
- A
ready, unclaimed device that serves → grant, unlessexceptor the driver requires a reboot before grant. That reboot waits under memory pressure, or returnsNO_CAPACITYif the request cannot wait. - Unless
noWait: one the warm pool is booting or creating under an ownerless claim (for a target or learned kind, a released device or a request queued behind) → wait. - A
shutdowndevice that serves → boot it. - Else provision the spec, evict an idle device, wait, or
NO_CAPACITY.
Existing devices are never re-checked against the Android fit rule: an older device serves a class or range request whenever its OS satisfies it.
Android provision:
- Profile from the
resolveSpeccache, else resolved again. - Image: installed, fitting, at the spec's level. Order host-ABI
google_apis→ host ABI →google_apis→ any. With a tag: that tag only, host ABI first. avdmanager create avd -d <seed>: an SDK profile's own id, else the firstavdmanager list deviceentry. Then devices.xmlhw.*keys, or the library profile's keys andboot.prop, are written over it.
iOS provision: simctl create with the cached device type and runtime.
- The coordinator: no enrolled, non-deleted device fits (
fitsPhysical: platform, model ignoring case or class, OS exact or range) →unresolvable-spec. planPhysical: firstready, present, unclaimed fitting device no older physical waiter fits.- Presence is read outside the lock and checked again inside it before the grant.
Enrolled facts come from inspectPhysical at simlock device add:
Android model ro.product.model, OS = API level, class phone;
iOS model marketingName (else productType), OS osVersionNumber, iPad tablet else phone.