Skip to content

A phone's hardware serial is kept on its record, and one phone keeps one record #1604

Closed

Description

@V3RON

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 toDriverDevice part), X18 (reference/errors.mdx, and the reasons table in worker/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"]
Loading

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_RANGE moves 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.ts and 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 → enrolled initiator: "auto"; hardware serial already enrolled → refused enrolled-under-other-id, logged once, no event (extend e2e/physical-enrollment-auto-enroll.test.ts)
  • B7: device add of a phone whose hardware serial is already enrolled under another ID: equals a live record's ID; equals a live record's hardwareSerial; a USB ID equal to a live record's hardwareSerial; a deleted record → enrolled; same ID → re-enrolled; re-enrol taking a new hardwareSerial; clash between inspection and commit; clash at the second commit of a re-enrol; #inspect and the fake carry hardwareSerial
  • 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 driverDeviceId and hardwareSerial; toDriverDevice carries it to driver.reclaim
  • B9: DEVICE_NOT_ENROLLABLE with reason enrolled-under-other-id, its message and canonicalId, over the dispatcher, the CLI's JSON error line and the HTTP error body

Done when

  • pnpm test:changed passes, with a test per B6–B9 case above.
  • pnpm test:e2e e2e/physical-enrollment-auto-enroll.test.ts e2e/physical-enrollment.test.ts passes.
  • website/src/content/docs/docs/reference/errors.mdx and the reasons table of worker/enrolling-physical-devices.mdx list enrolled-under-other-id with what to do.
  • The website build and its HTTP API check pass (src/contract/ changes).

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 16, 2026
  2. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:draftScope written; technical spec or its spec check missing.
    on Nov 16, 2026
  3. self-assigned this
    on Nov 16, 2026
  4. V3RON commented on Nov 16, 2026

    @V3RON
    ContributorAuthor

    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.

  5. added a commit that references this issue on Nov 17, 2026
    959b632
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

platform:androidAndroid emulators or devicestask:readySpec checked. An agent may implement it once its Depends on allow.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions