Does: device management on a worker — registry, state machine, device verbs, reclaim, quarantine, warm pool, capacity, cleanup, components, baselines, doctor. Flows: startup, device selection, leasing (lease flow, when reclaim runs), warm pool, capacity.
Wiring:
core.connect(ports)runs once, before any request; a port used before it throws.physicalDeviceReadyis optional and a no-op beforeconnect.- Core never imports daemon or gateway, and only
usage/imports history. Leasing and drivers are kept out by the dependency rulescore-not-leasingandcore-not-drivers. - A part takes the config sections it reads, never the whole
Config:CoreConfig(createCore),DoctorConfig,CleanupConfig. A test builds only that slice, ortestConfigwhen it needs a whole config; it never writes a wholeConfigby hand. - The role comes from the daemon, never from a config key; a
modekey is refused.
Lock, claims and commits:
- One
SerializedDecision, shared by core, leasing and the installer. No driver I/O inside it. - One claim per device, in memory only.
- Every verb: claim and revalidate (lock) → driver (no lock) → revalidate and commit (lock) → release.
- Only
Registrywrites theregistrytables, insideSerializedDecision.run. A commit is onestate.dbtransaction, then memory, thenonCommit, then the event. A throw rolls back and leaves memory as it was. - A transition without the one event its edge calls for throws
RegistryEventError. - A lease with a requester-chosen id that leaves the registry writes its
ended_lease_idsrow in the same commit, and each commit prunes rows older thanlease.endedIdRetentionMs. - A virtual device record is created only by
DeviceProvisioner. Every driver verb on a registered device goes throughManagedDeviceLifecycle. - A driver keeps its own
DeviceDataTable(driver.ts) for a virtual device'sdriverData; a physical device has none. - A granted request's
grant.deviceis read as the device is now.
Devices:
- The state machine is
transitionindomain.ts.markDeviceMissingwritesdeletedfrom any state of a device with no lease. Adeletedrecord stays instate.dbandstatus.getfordevices.deletedRetentionMs, counted fromdeletedAt, thensnapshotstops listing it and the next commit drops it, with no event; a row alreadydeletedat the first start after the upgrade gets that start's time. - Destroy only what the registry holds. One exception:
doctor --purge-orphans, opt-in. - Nothing in core acts on a leased device, except
recoverLeased, under the lease: it reboots with no commit and no event. - Grant paths select by exact state.
mayBeGrantedrefuses every virtual device that has ended a lease, whatever itsleaseIdentity(ADR 0061 §2). - A physical device is never destroyed and never counted against capacity.
bootForLeaseandreadyProvisionedForLeasekeep thebootclaim for the grant;bootWarmdrops it atready.rebootForLeaseshuts areadydevice down and prepares it again with a lease'sexceptlist under that claim. The record staysready(onerecordRebootedDevicewrite, no event); on a failure it commitsready → shutdownfirst.devices.except_categoriesholds the list a lease kept running, written in the grant commit (createLease).shutdown,destroyanddisposeanswerundefinedfor a leased, gone or moved device. That is not an error.- Unreadable is not gone: startup skips a platform it could not list; doctor reports no drift there.
- Warm pool and startup never install. Instance id is never regenerated.
sweepWriteLeftoverslogs a pid-less legacy leftover and never deletes it.- Doctor's
service-brokencomes from an injectedserviceCheck, never from drift.
Reclaim and quarantine:
- Reclaim runs after leasing's lease-end commit. A virtual device: shutdown → destroy →
deleted. A physical device: commit whatdriver.reclaimreturns. - A failed reclaim quarantines. A physical device that is not present goes
absentinstead, and its reclaim runs again when it is back. - Quarantine retries run under the
reclaimclaim: a virtual device is destroyed, a physical one reclaimed. A physical device not present waitshealth.probeIntervalMs, and that try is not counted. - Out of retries, a virtual device is destroyed and a physical one unenrolled (
device.quarantine-abandoned). A destroy that fails leaves the device quarantined, with its capacity slot and no further retry (device.quarantine-stranded). quarantineCauseis written at entry; retries keep it and every exit drops it.
Components:
ComponentInstalleris the only caller ofinstallComponentandremoveComponent. One queue per platform, first come; a call for the same component joins. OneDiskSpaceGuardserves both platforms.- A removal marks the component under the lock, so
claimProvisionthrowsComponentBeingRemovedErroruntil it ends.
Baselines (ADR 0061 §4):
- One save or remove at a time. A save: leasing's
releaseToSaveends the lease, thenReclaimCoordinator.retireSavedcallsdriver.saveSourceunder thereclaimclaim. A driver failure quarantines the device and answersBASELINE_SAVE_FAILED. - A replace keeps the leased devices of older versions. An older version is dropped only when no device record and no provision (
hold) has it; that is checked after a save, on everydevice.deletedand at startup. removerefuses a baseline a lease uses, and destroys each source before its row.removeAll(nuke) deletes rows first.checkStaleruns beforelistanddoctor, aftercomponent.removed, after a save, and at startup. A failure is logged and goes on, except beforelist, which fails with it.
- A rollback keeps a stale quarantine cause. An older daemon keeps
quarantineCauseunknown; re-entry under it shows the old one. - One download at a time per platform. A second missing runtime waits, spending its own
downloads.timeoutMs. A bounded model with no--osasks Xcode for a bare major; pass--os. component removesees only this instance. One worker per user, so this matters for test roots and a second OS user. Another instance's devices, never-used default-set simulators and foreign devices made after the driver's count are not counted.- An older Simlock cannot end a physical lease. It skips
physicalDevices;beginReleasethrowsUnknownDeviceError. Release physical leases before a rollback. - Two instances can enrol one device. Only test roots and a second OS user can run a second instance. Each release uninstalls apps not on its own list. Enrol a device in one instance only.