refactor: slim DeviceSpec to required fields + sparse serialization

[steviec]

Stack: base main. Coordinated rollout: mobile-dev-inc/copilot#2398 (worker, deploy first) → this PR → mobile-dev-inc/copilot#2399 (backend, deploy last).

Problem

DeviceSpec required callers to provide values that have permanent, never-changing defaults (locale, cpuArchitecture, etc.) and persisted a handful of fields that are pure derivations (osVersion, deviceName, tag, emulatorImage). The result: verbose, noisy payloads, lots of unnecessary stored values in the DB, and confusion about which fields actually carry intent.

It also mixed two different concerns: provisioning identity (what device to boot) and driver-level runtime config (how to configure the driver after boot). Driver-level config already lives in WorkspaceConfig, where the CLI has always read it from; only the cloud worker was pulling it from DeviceSpec.

Separately, DeviceSpecRequest was a parallel nullable-everything hierarchy that existed only so fromRequest() could magically fill in defaults — indirection without a clear reason to exist now that Kotlin constructor defaults do the same thing.

Approach

• DeviceSpec becomes provisioning identity only: platform, model, os, locale, plus cpuArchitecture on Android.
• Driver-level fields (disableAnimations, snapshotKeyHonorModalViews, orientation) are removed — consumers read them from WorkspaceConfig.platform instead.
• Require only platform + model + os from callers. Everything else has a sensible default in the primary constructor.
• Derived values (osVersion, deviceName, tag, emulatorImage) become computed get() properties — not stored, not serialized.
• Sparse JSON serialization: the wire format contains only the platform discriminator, the required fields, and any optional field whose runtime value differs from the constructor default. Single source of truth for defaults = the constructor signature, read via Kotlin reflection.
• Named DEFAULT constant per subtype (DeviceSpec.Android.DEFAULT, etc.) for call sites that just want a reasonable device.

Final shape

data class Android(
    override val model: String,
    override val os: String,
    val locale: AndroidLocale = AndroidLocale.fromString("en_US"),
    val cpuArchitecture: CPU_ARCHITECTURE = CPU_ARCHITECTURE.ARM64,
) : DeviceSpec()

data class Ios(
    override val model: String,
    override val os: String,
    val locale: IosLocale = IosLocale.EN_US,
) : DeviceSpec()

data class Web(
    override val model: String,
    override val os: String,
    val locale: WebLocale = WebLocale.EN_US,
) : DeviceSpec()

Key changes

• DeviceSpec.kt: Reshaped to provisioning-only. DeviceSpecRequest and DeviceSpec.fromRequest() deleted. Driver fields removed.
• DeviceSpecSparseSerializer.kt (new): custom JsonSerializer<DeviceSpec> that reads primary constructor defaults via reflection (cached per subtype) and omits fields matching defaults.
• CLI call sites updated to use DeviceSpec.X.DEFAULT instead of scattered hardcoded model/os strings.

Wire format

Android with only required fields:

{"platform":"ANDROID","model":"pixel_6","os":"android-33"}

With a non-default cpuArchitecture:

{"platform":"ANDROID","model":"pixel_6","os":"android-33","cpuArchitecture":"X86_64"}

Coordination with copilot

This PR deliberately removes driver fields that the copilot worker currently reads. The rollout is phased:

1. copilot#2398 (worker) — worker reads disableAnimations/snapshotKeyHonorModalViews from WorkspaceConfig. Deploy first.
2. This PR — merge after worker deploys so no running worker still reads the removed fields.
3. copilot# (backend) — bump submodule to this PR's head, simplify backend ingestion. Deploy last.

Jackson FAIL_ON_UNKNOWN_PROPERTIES = false on the backend and worker mappers ensures existing DB rows with the now-removed fields continue to deserialize cleanly.

Test plan

• Full compile clean across all modules
• Full test suite passes
• Sparse serializer tests cover locale + cpuArchitecture default-omission
• Legacy-verbose-JSON deserialization tests cover the full set of now-removed fields
• Manual smoke: `maestro start-device --platform android` launches a default emulator
• Manual smoke: `maestro start-device --platform ios --device-model iPhone-14 --device-os iOS-17-5` launches a simulator

[proksh]

Nice Simplication @steviec 🙌

[pedro18x]

Does the CLI still populate deviceLocale/deviceModel/deviceOs alongside deviceSpec in the upload payload? Diff only shows the import change, so I can't tell from here. If it does, every post-PR3 CLI run 400s on MixedDeviceSpecRequestException. Worth a test pinning "deviceSpec set, flat fields null."

[pedro18x]

The sparse serializer approach is awesome. One coordination question above that I'd want nailed down before this and 2399 ship together.

[steviec]

Does the CLI still populate deviceLocale/deviceModel/deviceOs alongside deviceSpec in the upload payload? Diff only shows the import change, so I can't tell from here. If it does, every post-PR3 CLI run 400s on MixedDeviceSpecRequestException. Worth a test pinning "deviceSpec set, flat fields null."

@pedro18x no, the CLI doesn't use the deviceSpec payload to the API yet.

[pedro18x]

Does the CLI still populate deviceLocale/deviceModel/deviceOs alongside deviceSpec in the upload payload? Diff only shows the import change, so I can't tell from here. If it does, every post-PR3 CLI run 400s on MixedDeviceSpecRequestException. Worth a test pinning "deviceSpec set, flat fields null."

@pedro18x no, the CLI doesn't use the deviceSpec payload to the API yet.

I see. Approved!