Repository navigation
Description
Part of #1589.
Scope
After this PR, a physical device record can carry the phone's hardware serial. It survives a restart and reaches every presence read and every reclaim. device add refuses a phone whose hardware serial another live record already holds, with the new reason enrolled-under-other-id, whatever the transport. No driver sets a hardware serial yet (#1605 does), so on a real worker nothing a user sees changes except the new reason in the contract and the docs.
If this goes wrong, an operator would see a USB phone refused that has no other record, an enrolled phone lose its record across a restart, or presence reads stop answering for an enrolled phone.
Technical spec
Commit 5e639b4.
Rows
- Behaviours: B6, B7, B8, B9
- Stored state: S1
- Interfaces: I2, I3, I4, I7
- Existing code: X9, X10, X11, X12, X13, X14, X16, X24 (both fakes), X25 (the
toDriverDevicepart), X18 (reference/errors.mdx, and the reasons table inworker/enrolling-physical-devices.mdx:169-176)
Facts
| # | Fact | Source |
|---|---|---|
| F1 | Auto-enrolment's end-to-end tests drive the tick through the out-of-process fake driver | e2e/physical-enrollment-auto-enroll.test.ts |
| F2 | A registry migration test opens a database at an older version and reopens it with registryOwner |
src/core/registry.test.ts:77-85 |
| F3 | #inspect builds PhysicalEnrollmentInput from named fields only |
src/core/physical-enrollment.ts:193-199 |
Modules touched
Searches: listPresentPhysical, readPhysicalPresence, readPhysicalPresenceDetail, toDriverDevice, PhysicalEnrollmentInput, PhysicalInspection, DEVICE_NOT_ENROLLABLE_REASONS, registryOwner.
flowchart LR
C["contract/errors.ts (reason)"] --> CORE
CORE["core: driver.ts, physical-presence.ts, physical-enrollment.ts,<br/>registry*.ts, reclaim/quarantine coordinators, fake-driver.ts"] --> L["leasing: physical-device-watcher.ts, acquisition-workflow.ts"]
CORE --> D["drivers: ios/index.ts, android/index.ts + physical-handler.ts (signature only)"]
CORE --> E["e2e/fake-driver, e2e/helpers/physical-presence.ts"]
C --> W["website: errors.mdx, enrolling-physical-devices.mdx"]
Rules in play
- Safety rule 1 and ADR 0022 §6 step 3: one device, one record; the duplicate check runs under the lock at each commit, never on a stale read.
- Core manual "Lock, claims and commits": the check and the write are in the same
SerializedDecision.run; no driver I/O inside it. - Contract manual "Protocol version": the new reason changes a contract shape, so
PROTOCOL_VERSION_RANGEmoves by one in this PR. - ADR 0036 (state.db owners): the registry owner adds its seventh migration and nothing else.
- Testing rule 3:
physical-enrollment.ts,registry.tsand the reclaim and quarantine coordinators are strict areas; every new path has a test. - ADR 0080 §2.
Tests
The seam is PhysicalEnrollment.add with the in-process fake driver, modelled on src/core/physical-enrollment.test.ts; the registry on a real state.db, modelled on src/core/registry-physical.test.ts and src/core/registry.test.ts:77.
- B6: the worker auto-enrols a listed network ID through
device add's path: no record → enrolledinitiator: "auto"; hardware serial already enrolled → refusedenrolled-under-other-id, logged once, no event (extende2e/physical-enrollment-auto-enroll.test.ts) - B7:
device addof a phone whose hardware serial is already enrolled under another ID: equals a live record's ID; equals a live record'shardwareSerial; a USB ID equal to a live record'shardwareSerial; adeletedrecord → enrolled; same ID → re-enrolled; re-enrol taking a newhardwareSerial; clash between inspection and commit; clash at the second commit of a re-enrol;#inspectand the fake carryhardwareSerial - B8: the hardware serial survives a reopen; absent stays absent; a v6 database migrates; the watcher, a grant, a reclaim's failure read and a quarantine retry pass
driverDeviceIdandhardwareSerial;toDriverDevicecarries it todriver.reclaim - B9:
DEVICE_NOT_ENROLLABLEwith reasonenrolled-under-other-id, its message andcanonicalId, over the dispatcher, the CLI's JSON error line and the HTTP error body
Done when
pnpm test:changedpasses, with a test per B6–B9 case above.pnpm test:e2e e2e/physical-enrollment-auto-enroll.test.ts e2e/physical-enrollment.test.tspasses.website/src/content/docs/docs/reference/errors.mdxand the reasons table ofworker/enrolling-physical-devices.mdxlistenrolled-under-other-idwith what to do.- The website build and its HTTP API check pass (
src/contract/changes).
Out of scope
- Any driver setting
hardwareSerial, readingro.serialno, or accepting a network transport: An Android worker enrols, checks and reconnects phones reached over the network under android.networkDevices #1605. - Showing the hardware serial in status, the worker view or events (feature Decisions).
Depends on
- Android leases that name no image tag get the worker's android.defaultImageTag where it fits #1595
- A worker's catalog names its default image tag, and a gateway ranks and shows it #1596
Written by an agent.
Activity
test: a physical record's hardware serial survives a reload (#1604)
feat(registry): a physical record keeps its hardware serial across a …
test: a v6 state.db migrates and then stores a hardware serial (#1604)
test: every presence read passes each record's driverDeviceId and har…
feat(core): every presence read passes each record's driverDeviceId a…
test: presence-read helpers read the IDs of the entries a driver was …
feat(core): a physical reclaim hands the driver the record's hardware…
test: device add refuses a phone another live record's hardware seria…
feat(core): device add refuses a phone another live record's hardware…
test: re-enrol takes the new read's hardware serial and a late clash …
feat(core): re-enrol takes the new hardware serial and checks it at i…
test: the worker auto-enrols a listed network ID and refuses one whos…
docs(website): the error and reasons tables list enrolled-under-other…
test: re-enrolling a phone with its own hardware serial is not a clas…
V3RON commentedon Nov 16, 2026
Delivery run
Merged: none (#1622 is ready in feature #1589's stack, above ADR PR #1594; the stack merges once #1605 joins it)
Parked: none
Waiting: #1605 — runnable now; it stacks on #1622
Decided: #1594 — ADR number 0079 was taken by the merged stream ADR → renumbered to 0080, and #1589, #1604, #1605 now cite 0080
Written by an agent.