diff --git a/docs/internal/adr/0083-a-worker-may-turn-single-slim-services-on-or-off-beside-its-categories.md b/docs/internal/adr/0083-a-worker-may-turn-single-slim-services-on-or-off-beside-its-categories.md new file mode 100644 index 000000000..37f47c643 --- /dev/null +++ b/docs/internal/adr/0083-a-worker-may-turn-single-slim-services-on-or-off-beside-its-categories.md @@ -0,0 +1,109 @@ +# 0083. A worker may turn single slim services on or off beside its categories + +- **Status:** Accepted — not yet implemented +- **Date:** 2026-11-17 +- **Issue:** [#1644](https://github.com/callstackincubator/simlock/issues/1644) (requests [#1556](https://github.com/callstackincubator/simlock/issues/1556), [#1552](https://github.com/callstackincubator/simlock/issues/1552)) +- **Narrows:** [ADR 0060](0060-ios-slim-writes-launchd-overrides-while-the-simulator-is-shut-down.md) §1 (the managed labels gain the worker's named services and the ones it recorded, a never-disable label may be written `true`, and a record file sits beside the overrides) and §2 (a device is `slim` only when some label is written `true`); [ADR 0066](0066-a-slim-lease-may-keep-named-categories-running.md) §2 (a kept category also wins over a service the worker turns off by name). + +## Context + +A worker slims whole categories (`ios.slim.categories`). Two requests +need one service at a time: + +- #1556 keeps push, assets and StoreKit running while the rest of their + categories stay off. Today the only way is to drop the whole category. +- #1552 turns off `com.apple.diagnosticd`, which no category lists. On one + x86 VM with iOS 26.5 it cost 7–11% of a core per booted simulator. It + must stay opt-in: without it `log stream` inside the simulator breaks. + +The file of ADR 0060 handles it. Checked on 2026-11-17 on iOS 26.4 +(23E254a), a throwaway iPhone 17 in a private device set: with +`com.apple.diagnosticd` written `true` before the boot, the boot finished, +`print-disabled` listed it disabled and no `diagnosticd` ran under the +runtime root; with the file removed and a reboot, it ran. + +A lease's `--except` (ADR 0066) keeps whole categories, per lease. Both +requests are about the worker, not a lease. + +```mermaid +flowchart LR + subgraph Before["Today"] + A1[ios.slim.categories] --> A2["category labels off"] --> A3[disabled.plist] + end + subgraph After["This ADR"] + B1[ios.slim.categories] --> B2["category labels off"] + B3[ios.slim.exclude] --> B4["+ named services off"] + B5[ios.slim.include] --> B6["− named services on"] + B2 --> B4 --> B6 --> B7["− lease --except categories"] --> B8[disabled.plist] + end +``` + +## Decision + +### 1. Two worker lists of service names + +The worker config takes `ios.slim.include` (services that run anyway) and +`ios.slim.exclude` (services that do not run), beside +`ios.slim.categories`. Both hold launchd service names, never categories. +A name in both lists fails the config load. Neither reaches a lease +request, the catalog or a gateway. + +### 2. What a slim device turns off + +The services written off are those of the worker's categories that the +lease does not keep, plus `exclude`, minus `include`. The services of a +category the lease keeps are always written on. A kept category wins over +`exclude` for its own services, as it already wins over a slimmed +category that lists the same one: the lease asked for it running. + +`exclude` wins over simslim's never-disable list: the operator named the +service. Every name in either list becomes a managed label (ADR 0060 §1), +written `true` or `false` on every `prepare`. + +### 3. The readback keeps ADR 0060's rules for these names + +An `include` or `exclude` service not read back as written grants `full`, +and a readback that cannot run grants `slim`, as for any managed label. A +`full` device runs every service, so an `include` service runs there too. +Only a lease's `--except` keeps ADR 0066's stricter rule. + +### 4. Slim means some service is off + +A device is `slim` only when at least one label is written `true`. So +`categories: []` with an `exclude` is a slim worker, and a configuration +or an `--except` that leaves nothing off grants `full`, as today. + +### 5. Simlock records the names it wrote + +The file also holds lines the runtime wrote, so Simlock cannot tell its +own lines from them once a name leaves both lists. Beside each +simulator's `disabled.plist`, Simlock keeps a record of the `include` and +`exclude` names it last wrote. A recorded name in neither list stays a +managed label at the next `prepare`, written by §2 as any other name: `true` +when a slimmed category the lease does not keep lists it, `false` otherwise. +The record is then rewritten. It is copied +with the file and removed with its folder. Without it, an idle simulator +that survives a restart, or a baseline's copy, keeps a reverted `exclude` +off with no warning. The file's name and shape are in the feature. + +## Consequences + +- #1552's setup is `categories: []`, `exclude: ["com.apple.diagnosticd"]`, + with slim leases. +- Simlock cannot tell a misspelt name: launchd reads back whatever the + file says. +- One more file per simulator (§5). A baseline saved before this ADR has + no record, so a name dropped from `exclude` stays off in its copies; + putting it in `include` turns it back on. +- No protocol change; the catalog's `slimCategories` stays the categories. + +## Alternatives considered + +- **Fail the boot when an `include` service is off, as `--except` does.** + Every slim boot on such a worker would fail whenever the readback times + out under load, where it grants `slim` today; a plain slim boot that + fails is not retried. Rejected by the maintainer. +- **A `diagnostics` category for #1552.** Turns the service off for every + worker that leaves `categories` unset, which breaks `log stream`. +- **Names on a lease (`--except` of a service).** Out of scope for now; + `--except` stays categories-only. diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 4743b1dcd..471e8a90b 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -95,13 +95,13 @@ the status is stale. | [0054](0054-a-lease-holder-tunnels-device-ports-to-its-own-machine.md) | A lease holder tunnels device ports to its own machine | Accepted; narrows 0005 Non-goals (port forwarding); §2, §5 and §6 and the iOS Consequence narrowed by 0064 | | [0058](0058-through-a-gateway-simlock-adb-and-simctl-send-stdin-only-with-stdin.md) | Through a gateway, `simlock adb` and `simlock simctl` send stdin only with `--stdin` | Accepted; narrows 0005 §19c | | [0059](0059-a-worker-with-real-drivers-holds-a-per-user-lock.md) | A worker with real drivers holds a per-user lock | Accepted; narrows 0034 §1 | -| [0060](0060-ios-slim-writes-launchd-overrides-while-the-simulator-is-shut-down.md) | iOS slim writes launchd overrides while the simulator is shut down | Accepted; supersedes 0002 §2, §3, §5, §8, §9 | +| [0060](0060-ios-slim-writes-launchd-overrides-while-the-simulator-is-shut-down.md) | iOS slim writes launchd overrides while the simulator is shut down | Accepted; supersedes 0002 §2, §3, §5, §8, §9; §1 and §2 narrowed by 0083 | | [0061](0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md) | Every virtual device is a copy of a source, and a baseline is a named source | Accepted; narrows 0001 §1, §3, §4, §5, §6, 0007 §6, 0009 §2, §4, §6, 0015 §6–7, 0038 §5 and 0060 §4; §5 narrowed by 0062 | | [0062](0062-the-warm-pool-learns-a-baseline-after-repeated-leases-and-follows-its-newest-version.md) | The warm pool learns a baseline after repeated leases, and follows its newest version | Accepted; narrows 0038 §1, §4, §5, §8, 0050 and 0061 §5 | | [0063](0063-a-big-module-is-one-composition-root-over-parts-that-own-their-state.md) | A big module is one composition root over parts that own their state | Accepted | | [0064](0064-a-tunnel-reaches-an-ios-simulators-ports-and-an-emulators-adb-port.md) | A tunnel reaches an iOS simulator's ports and an emulator's adb port | Accepted; narrows 0054 §2, §5, §6, 0001 §4 and 0005 Non-goals | | [0065](0065-a-driver-owns-its-config-keys-and-a-module-takes-the-sections-it-reads.md) | A driver owns its config keys, and a module takes the config sections it reads | Accepted | -| [0066](0066-a-slim-lease-may-keep-named-categories-running.md) | A slim lease may keep named categories running | Accepted; narrows 0007 §8, §9, 0008 §4, §9, 0009 §2, §4 and 0060 §1, §2, §6 | +| [0066](0066-a-slim-lease-may-keep-named-categories-running.md) | A slim lease may keep named categories running | Accepted; narrows 0007 §8, §9, 0008 §4, §9, 0009 §2, §4 and 0060 §1, §2, §6; §2 narrowed by 0083 | | [0067](0067-a-lease-has-a-file-folder-on-its-worker-that-http-callers-fill-and-read.md) | A lease has a file folder on its worker that HTTP callers fill and read | Accepted; narrows 0005 Non-goals (file transfer) and §19b′, 0026 §1 (a core relay target) and 0028 §4 (a file PUT's deadline) | | [0068](0068-a-worker-pauses-warming-and-new-devices-under-host-memory-pressure.md) | A worker pauses warming and new devices under host memory pressure | Accepted; narrows 0029, adds a rank stage to 0009 | | [0069](0069-a-learned-kind-keeps-one-ready-copy-while-its-copies-are-leased.md) | A learned kind keeps one ready copy while its copies are leased | Accepted; narrows 0038 §2 and §3 | @@ -115,4 +115,5 @@ the status is stale. | [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-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 | +| [0083](0083-a-worker-may-turn-single-slim-services-on-or-off-beside-its-categories.md) | A worker may turn single slim services on or off beside its categories | Accepted — not yet implemented; narrows 0060 §1, §2 and 0066 §2 | | [0084](0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted; narrows 0022 and 0009 §4 |