From 48ac1e8fcf58816f65586278523183c50a65549f Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 14:28:54 +0100 Subject: [PATCH 1/5] docs(adr): propose 0078, a worker may serve a platform's enrolled phones only (#1588) --- ...-serve-a-platforms-enrolled-phones-only.md | 98 +++++++++++++++++++ docs/internal/adr/README.md | 1 + 2 files changed, 99 insertions(+) create mode 100644 docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md diff --git a/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md b/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md new file mode 100644 index 000000000..17076d0b0 --- /dev/null +++ b/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md @@ -0,0 +1,98 @@ +# 0078. A worker may serve a platform's enrolled phones only + +- **Status:** Proposed +- **Date:** 2026-11-16 +- **Issue:** [#1588](https://github.com/callstackincubator/simlock/issues/1588) (request [#1181](https://github.com/callstackincubator/simlock/issues/1181)) +- **Narrows:** [ADR 0022](0022-a-physical-device-is-a-second-device-type-the-core-knows.md) + (the platform a worker has a driver for is no longer always one it + makes simulators or emulators for) and + [ADR 0009](0009-gateway-routing-is-a-list-of-stages.md) §4 (one more + reason a model is listed by no worker). + +## Context + +A worker with a platform's tools makes simulators or emulators for every +lease on that platform that does not pass `--physical`. An operator who +tests only on enrolled phones cannot stop that: + +- A lease without `--physical` never gets a phone (ADR 0022), so an agent + that forgets the flag gets an emulator, on a machine its operator meant + for phones. +- The capacity limits count only virtual devices, and are at least 1. +- The warm pool, a configured target and a learned kind boot devices of + their own. + +## Decision + +### 1. A per-platform key turns the platform's virtual devices off + +`ios.virtualDevices` and `android.virtualDevices` are booleans, default +`true`, set like any key and read at start. They are core keys beside +`defaultMode` and `defaultModels`, not driver keys: core, leasing and the +gateway act on them, and a driver does not. Every driver keeps starting +as today, so the phones of that platform are served as today. + +### 2. With it off, nothing makes, boots or keeps a virtual device of that platform + +- A request that does not pass `--physical` is refused at once, before + any catalog read or download: `UNKNOWN_MODEL`, with a message that + names the key and `--physical`. It never waits. +- Warm targets and learned kinds resolve through the same step, so they + are refused there too and boot nothing. +- At start, every idle virtual device of that platform is destroyed. A + leased one runs to its release and is destroyed then, as every virtual + device is. +- Saved baselines and installed components stay on disk. An operator may + still install and remove components. + +```mermaid +flowchart TD + R[lease, platform P] --> F{--physical?} + F -- yes --> P[Phone path, as today] + F -- no --> K{P.virtualDevices} + K -- true --> V[Virtual path, as today] + K -- false --> X[UNKNOWN_MODEL: phones only, pass --physical] +``` + +### 3. A worker says so in its catalog, and a gateway gives the same answer + +The worker's catalog entry for that platform lists no model, no runtime +and no image, and carries `virtualDevices: false`. The entry stays, so a +gateway still routes phone requests to that worker. A gateway refuses a +request without `--physical` with the phones-only message when every +known worker that has the platform reports `virtualDevices: false`. + +## Alternatives rejected + +- **Allow `0` for the capacity limits.** The limits would then mean two + things, and an agent that forgets `--physical` would wait or get + `NO_CAPACITY`, not a message that tells it what to pass. +- **Serve a request without `--physical` with a phone.** The same command + would mean different things on different workers. Emulator-only options + (`--mode`, `--image-tag`, model names from the catalog) would need new + rules, and a gateway would have to choose between phones and emulators + on behalf of the caller. +- **A driver key under `drivers.`.** That section holds where a + driver keeps its files, not what the worker serves, and a driver does + not act on this key. +- **A new error code.** `UNKNOWN_MODEL` already means "nothing here could + ever serve this request", and the gateway already gives it when no + worker lists a model. A new code would reach every client and error + table for no change in how a caller reacts. + +## Consequences + +- An agent behind a phones-only worker reads one message and passes + `--physical`. +- A phones-only Android worker still needs the whole Android SDK, because + the driver starts only when the emulator tools are there. Starting + Android with only `adb` is left to a later request. +- The catalog entry gains one field, so the protocol moves up by one. An + older gateway drops the field and gives its generic `UNKNOWN_MODEL` + message. +- Learned kinds of that platform are forgotten by the catalog check, + since the catalog lists none of their models. They are learned again + after the key is turned back on. + +The rows, messages and the order of the checks are in +[#1588](https://github.com/callstackincubator/simlock/issues/1588). diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 2694fb086..73678f581 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -111,3 +111,4 @@ the status is stale. | [0074](0074-an-admission-command-ranks-or-refuses-a-gateway-request-and-an-ended-chosen-lease-id-is-remembered.md) | An admission command ranks or refuses a gateway request, and an ended chosen lease id is remembered | Accepted; narrows 0005 items 10 and 11, decision 5 and requirements 14 and 30; supersedes 0020 §1 in part | | [0075](0075-a-foldable-simulator-streams-the-panel-in-use-and-a-stream-may-change-size.md) | A foldable simulator streams the panel in use, and a stream may change size while it runs | Accepted; narrows 0031's Consequences and 0052 §4 | | [0077](0077-the-repository-is-a-workspace-and-its-packages-release-together-under-one-version.md) | The repository is a workspace, and its packages release together under one version | Accepted | +| [0078](0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Proposed; narrows 0022 and 0009 §4 | From 8935334131416d48f0bda8016bb521fae8445ab6 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 14:45:10 +0100 Subject: [PATCH 2/5] docs(adr): 0078 names both ways to ask for a physical device --- ...-worker-may-serve-a-platforms-enrolled-phones-only.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md b/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md index 17076d0b0..30b37d42b 100644 --- a/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md +++ b/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md @@ -36,7 +36,8 @@ as today, so the phones of that platform are served as today. - A request that does not pass `--physical` is refused at once, before any catalog read or download: `UNKNOWN_MODEL`, with a message that - names the key and `--physical`. It never waits. + names the key and both ways to ask for a physical device (`--physical`, + or `physical: true`). It never waits. - Warm targets and learned kinds resolve through the same step, so they are refused there too and boot nothing. - At start, every idle virtual device of that platform is destroyed. A @@ -51,7 +52,7 @@ flowchart TD F -- yes --> P[Phone path, as today] F -- no --> K{P.virtualDevices} K -- true --> V[Virtual path, as today] - K -- false --> X[UNKNOWN_MODEL: phones only, pass --physical] + K -- false --> X[UNKNOWN_MODEL: phones only, ask for a physical one] ``` ### 3. A worker says so in its catalog, and a gateway gives the same answer @@ -82,8 +83,8 @@ known worker that has the platform reports `virtualDevices: false`. ## Consequences -- An agent behind a phones-only worker reads one message and passes - `--physical`. +- An agent behind a phones-only worker reads one message and asks for a + physical device. - A phones-only Android worker still needs the whole Android SDK, because the driver starts only when the emulator tools are there. Starting Android with only `adb` is left to a later request. From 43b1453ecb8f4cc8efe07d2fddb6fe7d6aaca450 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 14:48:52 +0100 Subject: [PATCH 3/5] docs(adr): accept 0078 (#1588) --- .../0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md | 2 +- docs/internal/adr/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md b/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md index 30b37d42b..bb72ae7b1 100644 --- a/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md +++ b/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md @@ -1,6 +1,6 @@ # 0078. A worker may serve a platform's enrolled phones only -- **Status:** Proposed +- **Status:** Accepted — not yet implemented - **Date:** 2026-11-16 - **Issue:** [#1588](https://github.com/callstackincubator/simlock/issues/1588) (request [#1181](https://github.com/callstackincubator/simlock/issues/1181)) - **Narrows:** [ADR 0022](0022-a-physical-device-is-a-second-device-type-the-core-knows.md) diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 73678f581..7d8d53457 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -111,4 +111,4 @@ the status is stale. | [0074](0074-an-admission-command-ranks-or-refuses-a-gateway-request-and-an-ended-chosen-lease-id-is-remembered.md) | An admission command ranks or refuses a gateway request, and an ended chosen lease id is remembered | Accepted; narrows 0005 items 10 and 11, decision 5 and requirements 14 and 30; supersedes 0020 §1 in part | | [0075](0075-a-foldable-simulator-streams-the-panel-in-use-and-a-stream-may-change-size.md) | A foldable simulator streams the panel in use, and a stream may change size while it runs | Accepted; narrows 0031's Consequences and 0052 §4 | | [0077](0077-the-repository-is-a-workspace-and-its-packages-release-together-under-one-version.md) | The repository is a workspace, and its packages release together under one version | Accepted | -| [0078](0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Proposed; narrows 0022 and 0009 §4 | +| [0078](0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted — not yet implemented; narrows 0022 and 0009 §4 | From d02be1570a241195cade02b10a7edc4f22b0c528 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 21:08:00 +0100 Subject: [PATCH 4/5] docs(adr): renumber the enrolled-phones ADR to 0080, 0078 and 0079 are taken (#1588) --- ...0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md} | 2 +- docs/internal/adr/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/internal/adr/{0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md => 0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md} (98%) diff --git a/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md b/docs/internal/adr/0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md similarity index 98% rename from docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md rename to docs/internal/adr/0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md index bb72ae7b1..94bb6bbce 100644 --- a/docs/internal/adr/0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md +++ b/docs/internal/adr/0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md @@ -1,4 +1,4 @@ -# 0078. A worker may serve a platform's enrolled phones only +# 0080. A worker may serve a platform's enrolled phones only - **Status:** Accepted — not yet implemented - **Date:** 2026-11-16 diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 712f73ceb..a46fa18cf 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -111,6 +111,6 @@ the status is stale. | [0074](0074-an-admission-command-ranks-or-refuses-a-gateway-request-and-an-ended-chosen-lease-id-is-remembered.md) | An admission command ranks or refuses a gateway request, and an ended chosen lease id is remembered | Accepted; narrows 0005 items 10 and 11, decision 5 and requirements 14 and 30; supersedes 0020 §1 in part | | [0075](0075-a-foldable-simulator-streams-the-panel-in-use-and-a-stream-may-change-size.md) | A foldable simulator streams the panel in use, and a stream may change size while it runs | Accepted; narrows 0031's Consequences and 0052 §4 | | [0077](0077-the-repository-is-a-workspace-and-its-packages-release-together-under-one-version.md) | The repository is a workspace, and its packages release together under one version | Accepted | -| [0078](0078-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted — not yet implemented; narrows 0022 and 0009 §4 | | [0078](0078-an-android-worker-tries-its-default-image-tag-first-and-falls-back-to-none.md) | An Android worker tries its default image tag first, and a lease falls back to none | Accepted | | [0079](0079-one-capture-per-device-is-shared-by-every-viewer-and-every-capture-sends-a-key-frame-every-5-s.md) | One capture per device is shared by every viewer, and every capture sends a key frame at least every 5 s | Accepted; narrows 0045 §5 | +| [0080](0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted — not yet implemented; narrows 0022 and 0009 §4 | From f597f486f37bfcdca01fcfa14ce613361efbdda9 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 12:10:32 +0100 Subject: [PATCH 5/5] docs(adr): renumber the enrolled-phones-only ADR to 0084 (#1588) --- ...0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md} | 2 +- docs/internal/adr/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/internal/adr/{0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md => 0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md} (98%) diff --git a/docs/internal/adr/0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md b/docs/internal/adr/0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md similarity index 98% rename from docs/internal/adr/0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md rename to docs/internal/adr/0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md index 94bb6bbce..ec3232299 100644 --- a/docs/internal/adr/0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md +++ b/docs/internal/adr/0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md @@ -1,4 +1,4 @@ -# 0080. A worker may serve a platform's enrolled phones only +# 0084. A worker may serve a platform's enrolled phones only - **Status:** Accepted — not yet implemented - **Date:** 2026-11-16 diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 2b8e85b49..62b056c8a 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -114,5 +114,5 @@ the status is stale. | [0077](0077-the-repository-is-a-workspace-and-its-packages-release-together-under-one-version.md) | The repository is a workspace, and its packages release together under one version | Accepted | | [0078](0078-an-android-worker-tries-its-default-image-tag-first-and-falls-back-to-none.md) | An Android worker tries its default image tag first, and a lease falls back to none | Accepted | | [0079](0079-one-capture-per-device-is-shared-by-every-viewer-and-every-capture-sends-a-key-frame-every-5-s.md) | One capture per device is shared by every viewer, and every capture sends a key frame at least every 5 s | Accepted; narrows 0045 §5 | -| [0080](0080-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted — not yet implemented; narrows 0022 and 0009 §4 | | [0080](0080-an-android-worker-may-enrol-phones-reached-over-the-network.md) | An Android worker may enrol phones reached over the network | Accepted; narrows 0022 §6 and §7, and 0073 §2 and §5 | +| [0084](0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted — not yet implemented; narrows 0022 and 0009 §4 |