Core knows physical devices: the device union, its state machine, and every virtual-only path leaves them alone #436

Part of #428.

Scope

After this PR the core knows a device record may be physical. The registry loads and saves physical records in their own list in state.json, which an older Simlock never reads, and each type has its own state machine (ADR 0022 §1–2, without absent, which task 3 adds). Every path that boots, shuts down, destroys, counts or compares devices with a root now reads only virtual devices, so a physical record survives a daemon start, doctor --fix, doctor --purge-orphans, cleanup, the warm pool, nuke's shutdown and delete steps, the health monitor and the planner untouched. simlock status and simlock list --devices show physical records, with physical and class on each device entry and in a worker's view. A grant's device and the HTTP lease answer may have no mode for a physical device, so a gateway keeps a worker's physical device and answers for a lease on it. No user command creates a physical record yet: device add comes in the next task. This PR makes it safe for that record to exist.

In short

A physical record is a registry device with physical: true, e.g. an iPhone 15 Pro on iOS 18.4, class phone, with ID 00008110-001A2B3C4D5E. state.json keeps it in a new top-level list, physicalDevices; the devices list keeps only simulators and emulators. The virtual read is the registry's list of every device that is not physical. Paths that act on simulators and emulators use it. Paths shared by both types keep reading every device: the lease path, doctor's stalled-transition finding, status and list. In this PR the only way to get a physical record is to write it into physicalDevices by hand, which is what the tests do.

flowchart LR
  R["registry: every device"] -->|"virtual read (new)"| V["startup, health monitor, doctor drift,<br/>purge-orphans, cleanup, warm pool,<br/>nuke, capacity, planner boot/evict"]
  R -->|"every device"| S["lease grant (fits refuses physical *),<br/>release and expiry, stalled-transition,<br/>status and list (+physical, class *)"]

With a physical record written into state.json before the daemon starts (wording illustrative):

# before: the record loads as a simulator
$ simlock doctor --fix
registry-device-missing dev_p1 (ios)        -> dev_p1 marked deleted
$ simlock lease --platform ios --device "iPhone 15 Pro" --os 18.4
Lease lse_1: dev_p1 ...                     -> a real device handed to a simulator request

# after
$ simlock doctor --fix
(no finding names dev_p1)
$ simlock status
Device dev_p1: ready, physical phone
$ simlock lease --platform ios --device "iPhone 15 Pro" --os 18.4
Lease lse_1: dev_v1 ...                     -> a new simulator; dev_p1 stays ready

If this goes wrong, an operator would see, from the next task on, an enrolled device marked deleted after a restart, a doctor --fix, a cleanup or a nuke; a simulator request granted a real device; real devices counted against simulator limits; an older Simlock, started on the same state.json, treating an enrolled device as a simulator; or a worker shown incompatible by a gateway of the same release.

Technical spec

Modules touched

flowchart TD
  CLI[cli: status line *] --> DSP[daemon/dispatcher: status, list *]
  GW[gateway: warm-hit, worker-link *] --> CT[contract: schemas, protocol *]
  HTTP[http: lease answer *] --> CT
  DSP --> CT
  UI[ui: test fixtures *] --> CT
  DSP --> REG[core/registry + domain *]
  LS[leasing: planner, reconciler,<br/>health monitor, release, modes *] --> REG
  OPT[core optional: doctor, reaper,<br/>cleanup executor, warm pool, nuke *] --> REG
  REQ[core required: reclaim, quarantine,<br/>capacity, lifecycle, startup, components *] --> REG
  LS --> DRV[core/driver types *]
  OPT --> DRV
  REQ --> DRV
  DRV --> IMPL[ios, android, both fakes: types only *]

sequenceDiagram
  participant C as CLI or gateway
  participant D as Daemon (worker)
  participant R as Registry
  C->>D: status.get / list.get
  D->>R: snapshot.devices and snapshot.virtualDevices
  R-->>D: records
  D-->>C: devices with physical and class; capacity from virtual devices only
  Note over C,D: a peer one protocol version apart is refused at hello: incompatible

Domain and registry:

• src/core/domain.ts: the types of ADR 0022 §1. DeviceRecord becomes VirtualDevice | PhysicalDevice, told apart by physical. DeviceSpec becomes VirtualSpec | PhysicalSpec. In memory physical is always a boolean: false on every virtual record and spec, true on every physical one (ADR 0022 §1). PhysicalSpec is { physical: true; platform; model; osVersion; class: "phone" | "tablet" }, with no mode and no imageTag. PhysicalDevice adds enrolledApps: readonly string[], and has no mode and no leaseIdentity. Every place that builds a virtual record or spec sets physical: false, test fixtures included; the compiler finds them. (reclaimingSince comes with task 3, the first task that enters reclaiming other than through beginRelease.)
• DeviceState becomes VirtualState | PhysicalState. In this task PhysicalState is ready | leased | reclaiming | quarantined | deleted; task 3 adds absent. transition (:411) checks a second table for a physical record: ready -> leased | deleted, leased -> reclaiming, reclaiming -> ready | quarantined, quarantined -> ready | deleted, deleted -> none. Anything else throws IllegalTransition. The virtual table (legalTransitions, :380) is unchanged.
• sameSpec (:66) is false when one spec is physical and the other is not.
• fits (:131) is false for a physical spec. Every requirement in this task is virtual; task 2 adds physical requirements.
• transitionEnteredAt (:455) is unchanged. In this task a physical record enters reclaiming only through beginRelease, which stamps lastLeaseEndedAt, the field it already reads.
• mayBeGranted (:251) is true for a physical record: lease.identity does not apply.
• src/core/registry.ts:
  • state.json gains a top-level list, physicalDevices. Physical records are saved there and only there; devices holds only virtual records. An older Simlock keeps an unknown top-level key as it found it (:829), so it never loads a physical record. physicalDevices joins the known top-level keys (:829), so it is not kept twice. A file with no physicalDevices loads with none. A physicalDevices that is not a list fails the load, as devices does (:825).
  • Rollback: an older Simlock still loads a lease on a physical device and keeps it. Its startup reconciler skips a lease whose device it does not hold (src/leasing/lease-reconciler.ts:44). But it cannot end that lease. Its expiry, release, release --all and nuke all go through beginRelease, which throws UnknownDeviceError when the lease's device is not in devices (src/core/registry.ts:659-663). ADR 0022 §1 said the older daemon ends such a lease; docs(adr): ADR 0022 amendments from the #428 spec check #443 corrects it. So leases on physical devices must be released before a rollback. docs/internal/KNOWN-PITFALLS.md gains an entry that says this: an older Simlock cannot end a lease on a physical device, so release those leases before rolling back.
  • In memory the two lists are one. RegistrySnapshot.devices (:67) lists the records of devices, then those of physicalDevices. The snapshot gains virtualDevices: readonly VirtualDevice[]: every record that is not physical, in snapshot order. It is the virtual read. No caller writes the filter itself.
  • parseDevice (:1061), for a record in devices: it loads as virtual, with physical: false on the record and its spec when the file has none, as every record today. It fails the load when the record or its spec carries a physical other than false, or its spec carries a class.
  • parseDevice, for a record in physicalDevices: it needs physical: true on the record and the spec, a spec class of phone or tablet, no spec mode or imageTag, no record mode or leaseIdentity, a physical state, and enrolledApps as a list of strings.
  • A record that breaks any of these rules fails the load, like any corrupt record. deviceRecordKeys (:893) gains physical and enrolledApps, so they are not kept twice as unknown fields.
  • A virtual record saves into devices as today, with no physical key on the record or its spec. A physical record saves into physicalDevices with physical: true on both.
  • #commitMissing (:573), the one place a device is written as missing, throws for a physical record and writes nothing. So markDeviceMissing (:526) and endLeaseAndMarkDeviceMissing (:549) can never unenroll one.

Driver types:

• src/core/driver.ts gains VirtualDriverDevice = DriverDevice & { physical: false } (ADR 0022 §5). provision takes a VirtualSpec, and resolveSpec returns one. makeReady, reclaim, shutdown, destroy and destroyLegacy take a VirtualDriverDevice. So a driver device with physical: true does not compile there. estimate keeps taking any DeviceSpec: it prices a physical reclaim for the stall rule. reclaim widens to physical devices in task 2, which also declares PhysicalDriverDevice.
• The three private toDriverDevice copies (src/core/reclaim-coordinator.ts:285, src/core/managed-device-lifecycle.ts:385, src/core/quarantine-coordinator.ts:299) take a VirtualDevice and return a VirtualDriverDevice. Task 2 merges them into one.
• src/drivers/ios, src/drivers/android, src/core/fake-driver.ts, e2e/fake-driver/fake-driver.ts: type changes only. No behaviour changes.

Paths that switch to the virtual read:

• Startup: StartupConverger#actionableDevices (src/core/startup-converger.ts:99) is the one startup filter, so a physical record left reclaiming gets no shutdown. ReclaimCoordinator.recoverInterrupted (src/core/reclaim-coordinator.ts:117) is called only from the converger's reclaiming list (:82, through src/core/create-core.ts:329-330). It adds no filter of its own: its re-reads look the ID up in the virtual read only so the compiler knows the record is virtual. LeaseReconciler.run (src/leasing/lease-reconciler.ts:39) skips a lease whose device is physical: the lease and the device keep their state (ADR 0022 §7).
• Health monitor: #runTick (src/leasing/lease-health-monitor.ts:126).
• Doctor (src/core/doctor.ts): the drift loop (:253) compares only virtual devices with root reality. So a physical record never gets registry-device-missing, foreign-state-change, foreign-provenance-change or legacy-device. The stalled-transition finding (:271) still checks every device. The orphan comparison (:246) keeps every record's key: an ID a physical record holds is never purged as an orphan.
• Cleanup: the reaper's view (src/core/reaper.ts:191) and CleanupExecutor.execute (src/core/cleanup-executor.ts:35).
• Warm pool: every registry read in src/core/warm-pool/converger.ts (:205, :285, :364, :443, :559, :597, :628).
• Capacity: create-core.ts (:202, :215) and the status figures in src/daemon/dispatcher.ts:355 build from the virtual read. So limits, the RAM budget, capacity.changed, and status' used, running and warm never count a physical record.
• Planner (src/leasing/acquisition-planner.ts): the on-its-way check (:99), the shutdown boot (:105), every capacity input (:123, :143, :179) and eviction candidates (:190). The ready grant (:90) keeps every device; fits refuses a physical one.
• ManagedDeviceLifecycle (src/core/managed-device-lifecycle.ts): bootForLease, bootWarm, readyProvisionedForLease, shutdown, destroy and recoverLeased take a VirtualDevice, and their re-reads (:349, :371) use the virtual read.
• Nuke: NukeService (src/core/nuke-service.ts:80, :95, :118) shuts down and deletes only virtual devices. Its lease step, LeaseReleaseCoordinator.releaseAllDuringMaintenance (src/leasing/lease-release-coordinator.ts:209), is not changed here. Nuke ending a physical lease, and the reclaim that follows, are task 2's: they are tested there with the real physical reclaim.
• ComponentInstaller#simlockDevices (src/core/component-installer.ts:525): a physical record never counts as using a runtime.
• QuarantineCoordinator.restore (src/core/quarantine-coordinator.ts:142).

Shared paths, with the interim for this task:

• ReclaimCoordinator.reclaim (src/core/reclaim-coordinator.ts:77) makes no driver call for a physical record. The device stays reclaiming, aged from lastLeaseEndedAt. Until task 2 adds the physical reclaim, doctor's stalled-transition rule is what moves it on.
• QuarantineCoordinator arms no retry for a physical record: not from enter (:89), enterFromStalledTransition (:122) or restore (:142). The record stays quarantined. Its device.quarantined event and its record still carry the backoff's nextRetryAt; no timer acts on it until task 2 adds the retry and the give-up. Neither interim can be reached by a user before task 2: a physical lease cannot be granted until then.
• LeaseAcquisitionCoordinator.servesDefaultMode (src/leasing/lease-acquisition-coordinator.ts:201) is false for a physical spec.
• #notifyReclaimWait (src/leasing/lease-acquisition-coordinator.ts:991) is unchanged: it uses sameSpec, which never matches a physical record for a virtual request. So a reclaiming physical record never gives a virtual waiter a reclaiming progress stage.

Status, list and the gateway:

• Dispatcher#decorateDevice (src/daemon/dispatcher.ts:843) sets physical on every device and class on a physical one. A physical device's entry has no mode.
• ui/: the test fixtures typed from the worker view (ui/src/views/workers-model.ts:13) gain physical: false, on the device and its spec: attention.test.tsx, workers.test.tsx, leases.test.tsx, worker-detail.test.tsx. The views that read a device's mode (worker-detail.tsx:151, leases.tsx:181) keep compiling with mode optional. So the console lane runs (toolchain.md). Marking physical devices in the console is task 1b's. Until then a physical record shows as any device does: a row in the worker page's Devices table with an empty Mode cell (worker-detail.tsx:151), a device in the Workers view's device total (ui/src/views/workers-model.ts:85), and, when quarantined or stalled, an attention item (ui/src/views/attention-model.ts:60). The lease page's Mode fact (leases.tsx:325) reads the HTTP lease answer's mode, so it is empty for a lease on a physical device; the Leases table's Mode cell (leases.tsx:181) shows "—".
• src/cli/index.ts formatStatus (:2381): a physical device's line reads Device <id>[ on <worker>]: <state>, physical <class> with today's markers. A virtual device's line is unchanged.
• src/gateway/routing/stages/warm-hit.ts: the spec it builds from a view device carries the entry's physical, so fits refuses a physical device and it is never a warm hit.

Contract and event changes

• statusDeviceSchema and deviceRecordSchema (src/contract/schemas.ts:145, :82) gain physical: boolean, always present, and class (phone or tablet), present only on a physical device. mode stays required when physical is false and is absent when it is true. The worker view's devices (src/contract/worker-view.ts:70) are statusDeviceSchema, so a gateway reads all three from its workers. enrolledApps stays off the wire, like deferredReclaimLeaseId: #decorateDevice spreads the whole record (src/daemon/dispatcher.ts:850), and no output schema declares the field.
• deviceSpecSchema (src/contract/schemas.ts:72) gains physical: boolean: responses pass the in-memory spec through, so a grant's, a status entry's and a list entry's spec carry it.
• grantedDeviceSchema (src/contract/schemas.ts:198) gains physical: boolean, always present, and class, present only on a physical device, as the status entry has them. Its mode (:212) may be absent only when physical is true. No physical grant exists before task 2, but the gateway parses a worker's list.get devices with this schema (src/gateway/worker-link.ts:114, :116) and leaves out a device that does not parse. Without this change it would leave out a physical device, and its GET /v1/leases/{id} for a lease on one would answer UNKNOWN_LEASE. Task 2 only references this shape.
• The HTTP lease answer: HttpLeaseDevice.mode (src/http/tracker.ts:405) and LeasePayload.mode (:47) become optional. buildLeasePayload (:86) leaves mode out when the device has none, which the contract allows only for a physical device. So a worker's registry record still serves as an HttpRegistryDevice (src/http/app.ts:50) when it is a PhysicalDevice, and GET /v1/leases/{id} (src/http/app.ts:406-415) answers for a lease on a physical device with no mode, on a worker and on a gateway.
• src/contract/protocol.ts: protocol +1 at merge. Its comment gains the reason: a gateway reads physical from every worker's devices, so a worker on the previous version is incompatible.
• Events: device.provisioned's spec gains physical: false (additive, events rule 6); both EVENTS.md files say so. Searched src/bus/index.ts: it is the only event with a spec (:137), and a physical record never emits it. Every event this task can emit for a physical record (lease.expired, lease.released, device.quarantined, doctor.reconciled) keeps its payload.

Other code on the same state

The state is the device records and leases in state.json, and the timers and claims that act on them. Found by searching src/ for snapshot.devices, .devices and the registry's device-writing methods.

• LeaseExpiryScheduler and LeaseReconciler: at startup the reconciler skips a physical lease, then the expiry timers are restored. A deadline that passed while the daemon was down expires the lease right after start. Expiry wins: it is the shared lease path.
• LeaseHealthMonitor and LeaseExpiryScheduler: the monitor never reads a physical record, so only expiry or a release ends a physical lease.
• Doctor --fix and a release in flight: both run under the serialized decision. #fixStalledTransition re-reads the state first. A release's background reclaim holds a claim, which isStalledTransition honours, but for a physical record that claim lasts only for the no-op reclaim. Whichever commits first wins; the other finds the state moved and does nothing.
• Doctor --fix and StartupConverger: the converger never reads a physical record, so only doctor moves a stuck physical reclaim.
• QuarantineCoordinator and Doctor: doctor's fix calls enterFromStalledTransition; the coordinator commits quarantined and arms nothing. No other path moves the record.
• NukeService and every lease release: nuke's shutdown and delete steps leave physical records alone. Its lease step, a release, release --all and expiry are the shared lease path, unchanged here; task 2 tests them on a physical lease.
• Warm pool converger and planner: neither boots, shuts down or evicts a physical record. The planner's ready grant reads every device, and fits refuses a physical one for every request in this task.
• CapacityCoordinator and CapacityObserver: both read only the virtual read, so a physical record's state change moves no figure. A registry commit still wakes the observer, which then finds nothing changed.
• DeviceOperationClaims: nothing in this task claims a physical record except a release's no-op reclaim.
• ComponentInstaller: reads the virtual read only.
• Dispatcher status and list, src/http/app.ts:820 (a lease's device), src/leasing/lease-lifecycle.ts:94 (the granted device): read every device, unchanged.
• Gateway: aggregate.ts:89 and dispatcher.ts:381 copy view devices with workerId, so physical and class pass through. worker-link.ts:114 parses a worker's devices with grantedDeviceSchema: it keeps a physical device, with physical and class and no mode (the grant shape above), and its spec's physical is always sent by a worker on this protocol. The gateway's HTTP lease answer is built from these devices, so it answers for a lease on a physical device. routing/view-state.ts:12 keys a refusal memo on the view's devices: a physical record's state change ends the memo early, which costs one more probe. warm-hit is changed above.
• The console (ui/) reads the worker view's devices and the HTTP lease answer. Its code does not change here, only its fixtures. It shows a physical record as it shows any device, as said above, until task 1b marks physical devices.
• Nuke.run (src/core/nuke.ts:21, :26): reads every device, to report which devices the nuke deleted. Nuke never deletes a physical record, so it never reports one.
• ReclaimCoordinator#unleasedDevice (src/core/reclaim-coordinator.ts:249): reads the virtual read. It looks for a shutdown device, a state a physical record never has, and its result goes to destroy, which takes a virtual device.
• QuarantineCoordinator#retry (src/core/quarantine-coordinator.ts:175): its re-read (:181) reads the virtual read. Only a retry timer calls it, and this task arms none for a physical record. Its result goes to the driver's reclaim, which takes a virtual device in this task.
• Doctor's fix re-reads, #fixMissingDevice (src/core/doctor.ts:701-706) and #fixForeignStateChange (:749-756): read every device, unchanged. They cannot reach a physical record: only a drift finding leads to them, and the drift loop raises none for a physical record.

Rules in play

• architecture.md rules 1–3: the core learns that a device may be physical (ADR 0022 §10). It still never learns what a UDID or serial means.
• architecture.md rule 6: one transition function, two tables, no platform-specific state.
• architecture.md rule 10: one virtual read, one fits, one #commitMissing guard.
• architecture.md rule 12: every interim exit above leaves the record in one named state.
• architecture.md rule 15: the optional components read the core's virtual read; nothing required reads them.
• safety.md rules 1, 7, 8 as amended by ADR 0022: a physical record is never shut down, destroyed, booted or marked missing.
• testing.md rules 1–4: each "left alone" test must fail when its path reads every device.
• toolchain.md "Contract shapes" and "Published surfaces": the schema change reruns MCP tools/list, HTTP and CLI help tests.

Tests

Main seam: withDaemon with the out-of-process fake driver, with state.json written into env.home before env.startDaemon(); the physical records go in its physicalDevices list. Model on e2e/startup-reconcile.test.ts (restart, driver log), e2e/doctor-drift.test.ts, e2e/capacity-cleanup-nuke.test.ts and, for the RAM budget, e2e/ram-budget-by-mode.test.ts. The seeded records: an iOS iPhone 15 Pro on 18.4, class phone, in ready, in leased (with a lease owned by the env's agent id) and in reclaiming (with lastLeaseEndedAt a day old). None is in the fake's scripted reality unless a line says so. "No driver call names it" means the fake driver's call log has no call whose argument carries that record's driverDeviceId. Unit seams: src/core/domain.test.ts, src/core/registry.test.ts, src/core/quarantine-coordinator.test.ts, src/core/reclaim-coordinator.test.ts, src/core/component-installer.test.ts, src/core/driver.test.ts, src/contract/schemas.test.ts, src/contract/worker-view.test.ts, src/gateway/routing/stages/warm-hit.test.ts, src/gateway/service.test.ts, src/http/app.test.ts, src/leasing/lease-acquisition-coordinator.test.ts, src/cli/index.test.ts, and the console's ui/src/views/worker-detail.test.tsx, workers.test.tsx, attention.test.tsx and leases.test.tsx.

• (e2e) a daemon started, then restarted, with a ready, a leased and a reclaiming physical record keeps each in its state; the lease renews for its owner; no driver call names any of them
• (e2e) a leased physical record whose lease deadline passed before the daemon started: right after start the lease ends with lease.expired, the record is reclaiming, and no lease.released with reason device-lost and no driver call names it
• (e2e) with health.probeIntervalMs 200 and stableObservations 2, a leased physical record is still leased after two seconds, its lease renews, and no lease.released or device.deleted names it
• (e2e) doctor --fix reports no finding naming the ready or the leased physical record and leaves both in their state
• (e2e) doctor --fix reports stalled-transition for the reclaiming physical record and moves it to quarantined with device.quarantined; after warmPool.quarantine.retryBackoffMs has passed, no driver call names it
• (e2e) with a scripted orphan simulator and a scripted root device whose ID is the ready physical record's driverDeviceId, doctor --purge-orphans --yes destroys the orphan, reports no orphan for that ID, and no destroy call names it
• (e2e) with idle thresholds of one second and the ready physical record's lastLeaseEndedAt an hour old, cleanup --dry-run proposes nothing for it, and cleanup leaves it ready with no shutdown call
• (e2e) with warmPool.enabled false, the ready physical record is still ready after the pool's pass, with no shutdown call
• (e2e) a warm target of one iPhone 15 Pro on 18.4 provisions a simulator; the target's report counts that simulator, not the physical record; its device.provisioned spec carries physical: false
• (e2e, model e2e/warm-targets.test.ts) with limits.ios.maxDevices 1 and a ready physical record, a warm target of one iPhone 15 Pro on 18.4 provisions a simulator; were the physical record counted, the device limit would refuse it
• (e2e, model e2e/warm-targets.test.ts) with limits.ios.maxRunning 1, a ready physical record and a shut-down iPhone 15 Pro simulator on 18.4, a warm target of one iPhone 15 Pro on 18.4 boots that simulator; were the physical record counted, the running limit would refuse the boot
• (e2e) with limits.ios.maxDevices 1 and maxRunning 1 and a ready physical record, lease --platform ios --no-wait is granted a new simulator, not NO_CAPACITY; the physical record stays ready, and status' iOS used, running and warm count only the simulator
• (e2e) with limits.ios.maxDevices 1, an idle ready iPhone 16 simulator and a ready physical record whose lastLeaseEndedAt is older than the simulator's, lease --platform ios --device "iPhone 15 Pro" evicts the simulator (a destroy call names it) and is granted a new simulator; the physical record stays ready, and no driver call names it
• (e2e) with a ready and a leased physical record, the capacity.changed emitted at start and after a simulator lease count only the simulator in iOS running and warm; under the resource capacity strategy its ramBudget.usedBytes and status' match the simulator's alone
• (e2e) lease --platform ios --device "iPhone 15 Pro" --os 18.4 and lease --platform ios --class phone are each granted a simulator while the physical record of that model and OS is ready
• (e2e) with a ready and a reclaiming physical record and no physical lease, nuke --delete-devices --yes destroys a simulator as today, keeps both physical records in their states, and no shutdown or destroy call names them
• (e2e) a physical lease whose deadline passes while the daemon runs ends with lease.expired; its record is reclaiming with lastLeaseEndedAt set, and no driver call names it
• (e2e) status --json and list --devices show a physical record with physical: true, class: "phone" and no mode, and a simulator with physical: false, its mode and no class
• (e2e) with a physical record seeded with two enrolled apps, the status --json and list --devices answers and a gateway's GET /v1/workers carry no enrolledApps on it
• (e2e, model e2e/gateway-fleet.test.ts) a gateway lists a worker's physical record with physical, class and workerId, and a gateway lease --platform ios --device "iPhone 15 Pro" --os 18.4 is granted a simulator on that worker
• (domain) every transition in the physical table is legal, and ready -> shutdown, reclaiming -> shutdown, shutdown -> ready and any move into provisioning throw IllegalTransition for a physical record; the virtual table is unchanged
• (domain) sameSpec is false for a physical and a virtual spec with the same platform, model and OS
• (domain) fits is false for a physical spec, for a model requirement and for a class requirement it would otherwise meet
• (domain) transitionEnteredAt of a reclaiming physical record is its lastLeaseEndedAt; mayBeGranted is true for a physical record
• (types, src/core/driver.test.ts) each of these fails to compile (@ts-expect-error): a value typed DriverDevice & { physical: true } passed to makeReady, reclaim, shutdown, destroy or destroyLegacy (src/core/driver.ts:403); a PhysicalSpec passed to provision (:319); resolveSpec's result (:274) assigned to a PhysicalSpec; a PhysicalDevice passed to ManagedDeviceLifecycle's bootForLease, bootWarm, readyProvisionedForLease, shutdown, destroy or recoverLeased. The same calls with a VirtualDriverDevice, a VirtualSpec and a VirtualDevice compile, and resolveSpec's result passes to provision as it is
• (registry) a record in devices with no physical loads with physical: false on the record and its spec, and is written back with no physical key on either
• (registry) a record in devices fails the load when the record or its spec has physical: true or a non-boolean physical, or its spec has a class
• (registry) a physical record with its class, enrolled apps and address survives a save and a load unchanged
• (registry) a record in physicalDevices fails the load when physical is missing or not true on the record or its spec, its class is missing or watch, its state is shutdown or provisioning, its spec has a mode or an imageTag, the record has a mode or a leaseIdentity, or its enrolledApps is not a list of strings
• (registry) a file with no physicalDevices loads with no physical record; one whose physicalDevices is a string fails the load
• (registry) after a virtual and a physical record are saved, the file's devices list holds only the virtual record and physicalDevices only the physical one; a reader of devices alone, as an older Simlock, finds no physical record
• (registry) snapshot.virtualDevices lists every virtual record in snapshot order and no physical one
• (registry) markDeviceMissing and endLeaseAndMarkDeviceMissing on a physical record throw and leave state.json unchanged
• (registry) beginRelease of a physical lease moves the record to reclaiming and stamps lastLeaseEndedAt with the clock's time
• (reclaim) ReclaimCoordinator.reclaim of a released physical lease calls no driver method and leaves the record reclaiming
• (quarantine) enterFromStalledTransition of a physical record commits quarantined and arms no timer; restore arms none for a quarantined physical record
• (components) a physical record on OS 18.4 does not count as a device using the 18.4 runtime, so its removal is not refused for it
• (leasing) servesDefaultMode is false for a physical spec on each platform
• (leasing) a waiter for iPhone 15 Pro on 18.4 that queues while the only reclaiming device of that model and OS is a physical record gets no reclaiming progress stage
• (contract) statusDeviceSchema and deviceRecordSchema accept a physical device with class and no mode, and a virtual one with mode; they refuse a device without physical, a spec without physical, a virtual device without mode, a physical device with a mode, a physical device without class, and a virtual device with a class; the worker view keeps physical and class, and refuses the same devices
• (contract) grantedDeviceSchema accepts a physical device with class and no mode, and keeps physical and class; it refuses a device without physical and a virtual device without mode
• (http) GET /v1/leases/{id} for a lease on a physical device answers the lease with no mode, on a worker and on a gateway; for a lease on a simulator it keeps the mode
• (gateway) a worker's physical device with no mode is kept in the grant shape beside its view, with physical and class, so the gateway's GET /v1/leases/{id} for a lease on it does not answer UNKNOWN_LEASE
• (gateway) warm-hit scores 0 for a worker whose only ready device that fits the request is physical
• (cli) the human status line of a physical device reads Device <id>: ready, physical phone; a simulator's line is unchanged
• (console) with a physical device in a worker's view, the worker page's Devices table lists it with an empty Mode cell, the Workers view's device total counts it, and a quarantined physical device is an attention item; a lease on it shows an empty Mode fact on its lease page and "—" in the Leases table's Mode cell

Done when

• With a ready, a leased and a reclaiming physical record seeded in state.json: a daemon start, a restart, doctor --fix, doctor --purge-orphans --yes, cleanup and a warm-pool pass leave the ready and leased records and the lease in place, and the fake driver's call log names none of them.
• nuke --delete-devices --yes leaves a ready physical record ready, and the fake driver's call log names it in no shutdown or destroy.
• An eviction for a simulator request destroys a simulator, never a physical record.
• doctor --fix moves the reclaiming physical record, past its threshold, to quarantined.
• simlock lease --platform ios --device "iPhone 15 Pro" --os 18.4 is granted a simulator while a ready physical record of that model and OS exists.
• simlock status --json and simlock list --devices show the physical record with physical: true and class, and status' capacity figures and capacity.changed do not count it.
• A gateway with that worker lists the record with physical and class.
• GET /v1/leases/{id} for a lease on a physical record answers the lease with no mode, on a worker and on a gateway, never UNKNOWN_LEASE.
• docs/internal/KNOWN-PITFALLS.md says an older Simlock cannot end a lease on a physical device, and that those leases must be released before a rollback.
• A state.json written before this PR loads, and every record in it stays virtual.
• A state.json written by this PR holds physical records only in physicalDevices, never in devices.
• PROTOCOL_VERSION_RANGE (src/contract/protocol.ts:47) is one above main's when this PR merges, and the comment above it names this change as the reason.

Out of scope

• Enrolling and removing physical devices, their events, and marking them in the console (1b).
• lease --physical, the physical reclaim (uninstall), its quarantine retries and the give-up that unenrolls (2).
• Nuke ending a physical lease and the reclaim after it (2). This task does not change nuke's lease step.
• reclaimingSince (3).
• The absent state and the physical-device watcher (3).
• The physical handlers in the iOS and Android drivers (4, 5), and the driver methods only they implement: inspectPhysical (declared with its first caller in 1b) and listPresentPhysical (declared with its first caller in 2). PhysicalDriverDevice is declared in 2, with reclaim's widening.
• Routing physical requests through a gateway (6).

Depends on

• docs(adr): a physical device is a second device type the core knows (ADR 0022) #435

Approval

• Approved for delivery

Written by an agent.