From cf157f99942844190293f0412e22d3c4f8bd76a6 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 13:52:41 +0100 Subject: [PATCH 01/10] docs(adr): 0076 proposed, an iOS clone names only its own folders before its first boot --- ...y-its-own-folders-before-its-first-boot.md | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md new file mode 100644 index 000000000..dc2456e10 --- /dev/null +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -0,0 +1,60 @@ +# 0076. An iOS clone names only its own folders before its first boot + +- **Status:** Proposed +- **Date:** 2026-11-15 +- **Issue:** [#1561](https://github.com/callstackincubator/simlock/issues/1561), bug [#1548](https://github.com/callstackincubator/simlock/issues/1548) +- **Narrows:** [ADR 0061](0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md) + §2's iOS Copy row: one more step before a clone's first boot, beside + the LaunchServices database drop. §1 (sources in their own set) stands. + +Shapes, limits and messages live in the feature's design tables (#1561); +this record holds the decision and why. + +## Context + +A simulator that has booted stores absolute paths to its own device +folder (`/`) and its log folder +(`~/Library/Logs/CoreSimulator/`): in symbolic links, plists and +other files. `simctl clone` copies those bytes, and today a clone changes +only its LaunchServices database before its first boot. A booted copy +then follows its seed's paths and writes into the seed. + +Measured 2026-11-15 on Xcode 27.2, iPhone 17, in throwaway sets laid out +as Simlock's (`devices/`, `devices/sources/`): + +- A seed booted once names its own UDID in one link (`data/Library/Logs` + → the seed's log folder), in binary plists (ManagedSettings records, + Safari's preferences) and in two unified-log `.tracev3` files. The same + folder is spelled both `/private/tmp/…` and `/tmp/…`. +- Today's flow (iOS 27.2): within 90 s of its boot a copy wrote two files + into the seed (`data/Library/com.apple.ManagedSettings/Records/…/tokenized.plist`), + and its `Logs` link pointed at the seed's log folder. +- Rewriting the copy's links and plists from the seed's folders to its own + before its first boot took 1.0 s; in 120 s after the boot nothing in the + seed changed, and the copy used its own log folder. + +Sources live in their own set (ADR 0061 §1) so that no lease holder's +`simctl` lists them, so a seed's folder and its copy's differ by more than +the UDID: a same-length UDID swap cannot work. + +## Decision + +TODO after the measurements of 2026-11-15 (iOS 27.0, real use, a baseline +from a used copy, delete against rewrite, cost). + +## Consequences + +TODO + +## Alternatives considered + +- **Make seeds beside the copies, then swap UDIDs byte for byte.** Under + `deviceSet: "default"` the seed would sit in Xcode's own set, listed by + Xcode, DeviceHub and every `simctl list`, and hit by "Delete All + Simulators" (ADR 0048). It fixes no seed or baseline made before, whose + paths differ in length, so the rewrite is needed anyway. Rejected. +- **Make the seed read-only.** A copy that follows a path into the seed + then fails to write its own state. Rejected. +- **Rewrite one seed→copy pair.** A baseline saved from a copy names two + other simulators (the seed and the copy it was saved from). Rejected for + matching by pattern. From 699662587d267dc6f5b87b5c8448176fe47ff69f Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 14:56:29 +0100 Subject: [PATCH 02/10] docs(adr): 0076 decision, measurements and alternatives --- ...y-its-own-folders-before-its-first-boot.md | 114 ++++++++++++++++-- docs/internal/adr/README.md | 1 + 2 files changed, 104 insertions(+), 11 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index dc2456e10..8d0b23da8 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -4,8 +4,10 @@ - **Date:** 2026-11-15 - **Issue:** [#1561](https://github.com/callstackincubator/simlock/issues/1561), bug [#1548](https://github.com/callstackincubator/simlock/issues/1548) - **Narrows:** [ADR 0061](0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md) - §2's iOS Copy row: one more step before a clone's first boot, beside - the LaunchServices database drop. §1 (sources in their own set) stands. + §1's iOS sources locations (`/sources`, + `$SIMLOCK_HOME/devices/ios-sources`) and §2's iOS Copy row (one more + step before a clone's first boot, beside the LaunchServices database + drop). Sources still live in their own set, apart from the copies. Shapes, limits and messages live in the feature's design tables (#1561); this record holds the decision and why. @@ -29,9 +31,24 @@ as Simlock's (`devices/`, `devices/sources/`): - Today's flow (iOS 27.2): within 90 s of its boot a copy wrote two files into the seed (`data/Library/com.apple.ManagedSettings/Records/…/tokenized.plist`), and its `Logs` link pointed at the seed's log folder. -- Rewriting the copy's links and plists from the seed's folders to its own - before its first boot took 1.0 s; in 120 s after the boot nothing in the - seed changed, and the copy used its own log folder. +- Today's flow (iOS 27.0, a copy used: Safari, a reboot, 90 s idle): 5 + files written into the seed. A copy of a baseline saved from a used copy + wrote 204 files into that used copy's folder (home-screen snapshots, + the Photos library). +- A rewrite that parses each format (links, plists with their keys, JSON + with `\/` separators, text) left paths in SQLite rows, Spotlight + indexes, caches and widget timelines: a seed's copy still wrote 9 files + into the seed (a download path kept in `nsurlsessiond/tasks.sqlite`), and + one of two baseline copies wrote a home-screen snapshot into the used + copy. Deleting what it could not rewrite did not stop the snapshot. +- With the sources set at a path exactly as long as the device set's, a + byte-for-byte swap of every foreign folder's path, in every file and + link, after flushing every SQLite WAL in the source: four copies (two of + a seed, two of a baseline saved from a used copy), each used as above, + wrote nothing into any other simulator's folder. 216 swapped SQLite files + passed `integrity_check`. Only `.tracev3` log history still named other + simulators. Reading every byte took 1.6 s for a seed's copy and 13–17 s + for a 2.4 GB baseline's. Sources live in their own set (ADR 0061 §1) so that no lease holder's `simctl` lists them, so a seed's folder and its copy's differ by more than @@ -39,22 +56,97 @@ the UDID: a same-length UDID swap cannot work. ## Decision -TODO after the measurements of 2026-11-15 (iOS 27.0, real use, a baseline -from a used copy, delete against rewrite, cost). +```mermaid +flowchart LR + subgraph Before + S1[("seed in /sources")] -->|clone| C1["copy in "] -->|boots, follows
the seed's paths| S1 + end + subgraph After + S2[("seed in a folder as long
as the device set")] -->|clone| C2["copy"] --> F["same-length swap of
every foreign folder"] -->|boots| O["writes only its own folders"] + end +``` + +### 1. Sources live at a path as long as the device set's + +Under both settings the sources set is +`realpath($SIMLOCK_HOME)/devices/src`, followed by `_` until its real path +is exactly as long as the real path of the set the copies live in (the +owned root under `simlock`, Xcode's `Devices` under `default`). It is an +owned root under both. Both folders are under `/private`, or neither, +because iOS writes a folder under `/private` in two spellings (`/tmp/…` +and `/private/tmp/…`) and only one of them could match. When the name +would be shorter than `src`, or only one folder is under `/private`, iOS +does not start (`driver.root-rejected`, reason `sources-path-unfit`) and +the message says how to fix `SIMLOCK_HOME`. The copies do not move. + +### 2. A source is flushed and indexed when it is made + +When a seed is made, and when a baseline is saved, after the clean +shutdown and before the row turns `ready`: every SQLite WAL in it is +flushed into its database (`wal_checkpoint(TRUNCATE)`), because a WAL +frame carries a checksum a swap would break; then every file and link +that names a foreign folder is found once and recorded with the source. +A WAL that cannot be flushed is logged and never patched. + +### 3. Every lease's copy swaps foreign folders for its own before its first boot + +In each recorded link target and file of a new copy, every +`/` and `~/Library/Logs/CoreSimulator/` +whose UDID is not the copy's own becomes the copy's own, byte for byte, in +each spelling and with `/` or `\/` separators. A file's length never +changes, so the swap needs to understand no format. It runs beside the +LaunchServices drop of ADR 0061 §2, and a copy whose swap fails is +deleted, as one whose drop fails is. + +### 4. Sources made before this are not copied as they are + +A seed whose row names another set, or has no record of §2, is destroyed +and made again by the existing stale-seed path. A baseline whose row names +another set is stale (`saved in , which copies cannot be fixed from; +save it again`) and answers `BASELINE_STALE`; it is deleted in its own set +when removed. + +Shapes, messages and the table live in #1561's design tables. ## Consequences -TODO +- A lease's simulator writes only into its own folders; seeds and + baselines stop growing, and leases of one kind stop sharing state. +- The first lease of each kind after the upgrade makes its seed again + (about 40 s once). Every baseline saved before must be saved again. +- `deviceSet: "default"` needs a `SIMLOCK_HOME` outside `/tmp` and `/var` + and short enough for the padding; the slow lane's homes move out of + `/tmp`. +- Making a source reads it once in full; each copy patches only the + recorded files. +- A file format that compresses or checksums a path (the `.tracev3` log + history today) keeps the old path; such a file is never followed as a + path today. ## Alternatives considered - **Make seeds beside the copies, then swap UDIDs byte for byte.** Under `deviceSet: "default"` the seed would sit in Xcode's own set, listed by Xcode, DeviceHub and every `simctl list`, and hit by "Delete All - Simulators" (ADR 0048). It fixes no seed or baseline made before, whose - paths differ in length, so the rewrite is needed anyway. Rejected. + Simulators" (ADR 0048). Rejected for a separate folder of the same + length. - **Make the seed read-only.** A copy that follows a path into the seed then fails to write its own state. Rejected. +- **Rewrite each format in the copy, the sources staying where they are.** + Measured: paths remained in SQLite rows, indexes and caches, and copies + still wrote into the seed and into a baseline's used copy. Every format + needs its own parser, and each iOS release may add one. Rejected. - **Rewrite one seed→copy pair.** A baseline saved from a copy names two other simulators (the seed and the copy it was saved from). Rejected for - matching by pattern. + matching every foreign UDID. +- **Sources beside Xcode's set under `default`** + (`~/Library/Developer/CoreSimulator/`), always the right length and + never under `/private`. Rejected by the maintainer: everything Simlock + keeps stays in `SIMLOCK_HOME`, at the cost of refusing an unfit home. +- **Move the copies under `simlock` (`/d` beside `/s`).** Ends + leases running at the upgrade and needs `simctl` at startup to clear the + old set. Rejected for moving only the sources. +- **Migrate old baselines with a format rewrite.** Keeps the measured + leak for them. Rejected for "save it again". +- **Scan the whole copy each time.** 13–17 s for a 2.4 GB baseline. + Rejected for recording the files once per source. diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 298d3b37a..e0e835087 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -110,3 +110,4 @@ the status is stale. | [0073](0073-a-worker-may-enrol-the-phones-plugged-into-it.md) | A worker may enrol the phones plugged into it | Accepted; narrows 0022 §3, §5 and §6 | | [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 | +| [0076](0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md) | An iOS clone names only its own folders before its first boot | Proposed; narrows 0061 §1 and §2 | From eca09a8fdd9d2da0ad73fedfe9bb791f1c29f45e Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:10:03 +0100 Subject: [PATCH 03/10] docs(adr): 0076 records every folder a source names; stale check at startup --- ...names-only-its-own-folders-before-its-first-boot.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index 8d0b23da8..801f266d8 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -85,8 +85,9 @@ When a seed is made, and when a baseline is saved, after the clean shutdown and before the row turns `ready`: every SQLite WAL in it is flushed into its database (`wal_checkpoint(TRUNCATE)`), because a WAL frame carries a checksum a swap would break; then every file and link -that names a foreign folder is found once and recorded with the source. -A WAL that cannot be flushed is logged and never patched. +that names any device folder or log folder, the source's own included, is +found once and recorded with the source, and the source is marked as +indexed. A WAL that cannot be flushed is logged and never patched. ### 3. Every lease's copy swaps foreign folders for its own before its first boot @@ -103,8 +104,9 @@ deleted, as one whose drop fails is. A seed whose row names another set, or has no record of §2, is destroyed and made again by the existing stale-seed path. A baseline whose row names another set is stale (`saved in , which copies cannot be fixed from; -save it again`) and answers `BASELINE_STALE`; it is deleted in its own set -when removed. +save it again`) and answers `BASELINE_STALE` from the first request after +the worker starts, since core now checks baselines for staleness at +startup; it is deleted in its own set when removed. Shapes, messages and the table live in #1561's design tables. From 21525446544e6a8cfdf69245dd95e2cbe2532268 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:12:48 +0100 Subject: [PATCH 04/10] docs(adr): accept 0076 (not yet implemented) --- ...os-clone-names-only-its-own-folders-before-its-first-boot.md | 2 +- docs/internal/adr/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index 801f266d8..a53e665bc 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -1,6 +1,6 @@ # 0076. An iOS clone names only its own folders before its first boot -- **Status:** Proposed +- **Status:** Accepted — not yet implemented - **Date:** 2026-11-15 - **Issue:** [#1561](https://github.com/callstackincubator/simlock/issues/1561), bug [#1548](https://github.com/callstackincubator/simlock/issues/1548) - **Narrows:** [ADR 0061](0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md) diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index e0e835087..3e39a2526 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -110,4 +110,4 @@ the status is stale. | [0073](0073-a-worker-may-enrol-the-phones-plugged-into-it.md) | A worker may enrol the phones plugged into it | Accepted; narrows 0022 §3, §5 and §6 | | [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 | -| [0076](0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md) | An iOS clone names only its own folders before its first boot | Proposed; narrows 0061 §1 and §2 | +| [0076](0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md) | An iOS clone names only its own folders before its first boot | Accepted — not yet implemented; narrows 0061 §1 and §2 | From f7a696beb174090901c71e315c4dc66659fc11e9 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:47:47 +0100 Subject: [PATCH 05/10] =?UTF-8?q?docs(adr):=200076=20=C2=A74=20deletes=20a?= =?UTF-8?q?n=20old-set=20seed=20in=20the=20set=20its=20row=20names?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...one-names-only-its-own-folders-before-its-first-boot.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index a53e665bc..935105057 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -101,8 +101,11 @@ deleted, as one whose drop fails is. ### 4. Sources made before this are not copied as they are -A seed whose row names another set, or has no record of §2, is destroyed -and made again by the existing stale-seed path. A baseline whose row names +A seed whose row names another set (ready or `making`), or has no record +of §2, is deleted in the set its row names, as a baseline is, and its row is +dropped; the seed is then made again in the sources folder. The existing +stale-seed path alone would not do: it deletes in the current sources set, +where a seed of another set is not found. A baseline whose row names another set is stale (`saved in , which copies cannot be fixed from; save it again`) and answers `BASELINE_STALE` from the first request after the worker starts, since core now checks baselines for staleness at From c4963b247657e1fbaa0f89cef49a7bdfb0b747d8 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 19:44:56 +0100 Subject: [PATCH 06/10] docs(adr): 0076 a source never boots, and a copy swaps its lineage's UDIDs Revised after experiment 4 (N vs W, iOS 27.2) and a look at Xcode's parallel testing and Bluepill: copy then remove replaces the padded sources folder, and a same-length UDID swap with no size limit replaces the folder-path swap. --- ...y-its-own-folders-before-its-first-boot.md | 278 ++++++++++-------- docs/internal/adr/README.md | 2 +- 2 files changed, 157 insertions(+), 123 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index 935105057..7c4c66dd0 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -1,13 +1,15 @@ # 0076. An iOS clone names only its own folders before its first boot - **Status:** Accepted — not yet implemented -- **Date:** 2026-11-15 +- **Date:** 2026-11-15, revised 2026-11-16 - **Issue:** [#1561](https://github.com/callstackincubator/simlock/issues/1561), bug [#1548](https://github.com/callstackincubator/simlock/issues/1548) - **Narrows:** [ADR 0061](0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md) - §1's iOS sources locations (`/sources`, - `$SIMLOCK_HOME/devices/ios-sources`) and §2's iOS Copy row (one more - step before a clone's first boot, beside the LaunchServices database - drop). Sources still live in their own set, apart from the copies. + §1's seed ("create, one cold boot to ready, clean shutdown": the boot + now happens in a throwaway device, never in the source), §2's iOS Copy + row (one more step before a clone's first boot, beside the LaunchServices + database drop) and §4's iOS save (the leased device's log folder is + deleted with it). Sources still live in their own set, apart from the + copies. Shapes, limits and messages live in the feature's design tables (#1561); this record holds the decision and why. @@ -16,142 +18,174 @@ this record holds the decision and why. A simulator that has booted stores absolute paths to its own device folder (`/`) and its log folder -(`~/Library/Logs/CoreSimulator/`): in symbolic links, plists and -other files. `simctl clone` copies those bytes, and today a clone changes -only its LaunchServices database before its first boot. A booted copy -then follows its seed's paths and writes into the seed. +(`~/Library/Logs/CoreSimulator/`): in symbolic links, plists, SQLite +rows, Spotlight indexes, caches and widget timelines, sometimes in UTF-16. +`simctl clone` copies those bytes, and today a clone changes only its +LaunchServices database before its first boot. A booted copy then follows +its seed's paths and writes into the seed. Measured 2026-11-15 on Xcode 27.2, iPhone 17, in throwaway sets laid out as Simlock's (`devices/`, `devices/sources/`): -- A seed booted once names its own UDID in one link (`data/Library/Logs` - → the seed's log folder), in binary plists (ManagedSettings records, - Safari's preferences) and in two unified-log `.tracev3` files. The same - folder is spelled both `/private/tmp/…` and `/tmp/…`. -- Today's flow (iOS 27.2): within 90 s of its boot a copy wrote two files - into the seed (`data/Library/com.apple.ManagedSettings/Records/…/tokenized.plist`), - and its `Logs` link pointed at the seed's log folder. -- Today's flow (iOS 27.0, a copy used: Safari, a reboot, 90 s idle): 5 - files written into the seed. A copy of a baseline saved from a used copy - wrote 204 files into that used copy's folder (home-screen snapshots, - the Photos library). -- A rewrite that parses each format (links, plists with their keys, JSON - with `\/` separators, text) left paths in SQLite rows, Spotlight - indexes, caches and widget timelines: a seed's copy still wrote 9 files - into the seed (a download path kept in `nsurlsessiond/tasks.sqlite`), and - one of two baseline copies wrote a home-screen snapshot into the used - copy. Deleting what it could not rewrite did not stop the snapshot. -- With the sources set at a path exactly as long as the device set's, a - byte-for-byte swap of every foreign folder's path, in every file and - link, after flushing every SQLite WAL in the source: four copies (two of - a seed, two of a baseline saved from a used copy), each used as above, - wrote nothing into any other simulator's folder. 216 swapped SQLite files - passed `integrity_check`. Only `.tracev3` log history still named other - simulators. Reading every byte took 1.6 s for a seed's copy and 13–17 s - for a 2.4 GB baseline's. - -Sources live in their own set (ADR 0061 §1) so that no lease holder's -`simctl` lists them, so a seed's folder and its copy's differ by more than -the UDID: a same-length UDID swap cannot work. +- Today's flow: within 90 s of its boot a copy wrote files into the seed + (ManagedSettings records), and its `Logs` link pointed at the seed's log + folder. A copy of a baseline saved from a used copy wrote 204 files into + that used copy's folder (home-screen snapshots, the Photos library). +- A rewrite that parses each format left paths behind, and copies still + wrote into the seed. +- A byte-for-byte swap of foreign folder paths, with the sources set + padded to the device set's length, stopped the writes, but its search + for paths cannot be shown complete (UTF-16 and compressed paths were + missed at first; files over 64 MiB were skipped), and the padding + refuses some `SIMLOCK_HOME`s. + +Measured 2026-11-16 ("copy then remove", Xcode 27.2, throwaway sets; one +lineage on iOS 27.1 / iPhone Duo, then two per arm on iOS 27.2 / iPhone 17, +with and without the swap: a throwaway +S booted and used, cloned unbooted as the seed M; a lease L0 of M, used, +saved as the baseline B; two leases L1 and L2 of B booted together, each +changed, rebooted once and left idle 30 minutes; a control simulator +booted throughout): + +- A source that never boots is never named by any file. M and B were + byte-for-byte unchanged in every run, with or without a swap. +- Every foreign path a lease inherits is then `/` or + `~/Library/Logs/CoreSimulator/` of a simulator in its lineage (S, + L0): it differs from the lease's own path only by the UDID. +- With the LaunchServices drop alone, user-visible state survived, but + each L1 named S in 20–25 files and L0 in 32–34 (Spotlight, FrontBoard, + CloudKit, Biome, PosterBoard, assetsd, Screen Time, the app's own + defaults). Screen Time records recreated S's and L0's deleted folders, + and L1 and L2 wrote the same paths there. A defaults value holding an + absolute path pointed into deleted L0. During each L1's run, 101 and 222 + log lines named a foreign UDID, mostly failures (Photos analysis, + assetsd, Siri and Shortcuts databases, chronod, SpringBoard posters). + Only 11 small files reappeared against 50+ files naming a foreign UDID, + so a reappearing folder is a weak sign of a miss. +- With the WAL flush and the UDID swap of §2–3: no folder reappeared, the + defaults path named the lease's own container, an independent scan + (any UUID-shaped text, dashed or not, any case, UTF-16LE and BE, plus the + lineage's raw 16-byte, base64 and hex forms, inside plists, compressed + data, SQLite dumps and blobs, extended attributes and link targets) + found no foreign UDID, and no log line named one. Swapping took + 6.5–19.7 s over 1.8–2.2 GB, reading every byte. The flush covered + 329–368 databases with no failure and left every `-wal` file empty. + 1–2 locationd caches could not be read by the host user. +- In both arms crashes matched the control's kinds, and every SQLite + database passed `integrity_check` except two that use a tokenizer the + host's `sqlite3` lacks. + +Other tools clone the same way and live with it, because their clones last +one test run. Xcode's parallel testing (Xcode 27.2, two workers) cloned a +booted device into `XCTestDevices` and rewrote nothing; each clone named +the source in 44–45 files, and while the source was shut down its folder +gained 56 files and changed 19 (the Photos library and its WAL, widget +timelines, Screen Time records), written by both clones. Bluepill clones a +booted template with `cloneDeviceAsync` and changes nothing either. ## Decision ```mermaid flowchart LR - subgraph Before - S1[("seed in /sources")] -->|clone| C1["copy in "] -->|boots, follows
the seed's paths| S1 + subgraph Seed + S["throwaway S in the device set"] -->|boot, shut down| S + S -->|clone unbooted| M[("seed M in the sources set")] + S -.->|delete S and its log folder| X1(( )) end - subgraph After - S2[("seed in a folder as long
as the device set")] -->|clone| C2["copy"] --> F["same-length swap of
every foreign folder"] -->|boots| O["writes only its own folders"] + subgraph Baseline + L["held lease"] -->|shut down, clone| B[("baseline B")] + L -.->|delete it and its log folder| X2(( )) + end + subgraph Lease + M & B -->|clone| C["copy"] --> F["drop LaunchServices,
swap lineage UDIDs for its own"] -->|boots| O["writes only its own folders"] end ``` -### 1. Sources live at a path as long as the device set's - -Under both settings the sources set is -`realpath($SIMLOCK_HOME)/devices/src`, followed by `_` until its real path -is exactly as long as the real path of the set the copies live in (the -owned root under `simlock`, Xcode's `Devices` under `default`). It is an -owned root under both. Both folders are under `/private`, or neither, -because iOS writes a folder under `/private` in two spellings (`/tmp/…` -and `/private/tmp/…`) and only one of them could match. When the name -would be shorter than `src`, or only one folder is under `/private`, iOS -does not start (`driver.root-rejected`, reason `sources-path-unfit`) and -the message says how to fix `SIMLOCK_HOME`. The copies do not move. - -### 2. A source is flushed and indexed when it is made - -When a seed is made, and when a baseline is saved, after the clean -shutdown and before the row turns `ready`: every SQLite WAL in it is -flushed into its database (`wal_checkpoint(TRUNCATE)`), because a WAL -frame carries a checksum a swap would break; then every file and link -that names any device folder or log folder, the source's own included, is -found once and recorded with the source, and the source is marked as -indexed. A WAL that cannot be flushed is logged and never patched. - -### 3. Every lease's copy swaps foreign folders for its own before its first boot - -In each recorded link target and file of a new copy, every -`/` and `~/Library/Logs/CoreSimulator/` -whose UDID is not the copy's own becomes the copy's own, byte for byte, in -each spelling and with `/` or `\/` separators. A file's length never -changes, so the swap needs to understand no format. It runs beside the -LaunchServices drop of ADR 0061 §2, and a copy whose swap fails is -deleted, as one whose drop fails is. +### 1. A source never boots, and the simulator it was copied from is deleted + +A seed is made by creating a throwaway simulator in the device set the +copies live in, booting it to ready and shutting it down cleanly, then +cloning it, unbooted, into the sources set as the seed; the throwaway and +its log folder are deleted. A baseline is saved as ADR 0061 §4 says, and +the leased device's log folder (`simctl delete` leaves it) is deleted with +the device. A source therefore never names itself, and every path it +carries names a deleted simulator of the same device set. The sources set +may be at any path; its length does not matter. + +### 2. A source is flushed and records its lineage when it is made + +After the clean shutdown and before the row turns `ready`, every SQLite +WAL in the source is flushed into its database (`wal_checkpoint(TRUNCATE)`), +because a WAL frame carries a checksum a swap would break. The source +records its **lineage**: the UDIDs of the simulators it was copied from +that have booted (a seed: its throwaway; a baseline: its device's UDID and +its own source's lineage), the device set they ran in, and the files and +links that name any of them, found by reading every byte once with no size +limit. A file the host cannot read is recorded as unreadable. A WAL that +still holds frames after the flush is logged and never patched. + +### 3. Every lease's copy swaps its lineage's UDIDs for its own before its first boot + +In each recorded file and link target of a new copy, every lineage UDID +becomes the copy's own, byte for byte: upper and lower case ASCII, and +UTF-16LE and UTF-16BE. A UDID has one length, so the swap understands no +format, and the spellings of a folder (`/tmp/…` and `/private/tmp/…`) are +covered because only the UDID changes. A `-wal` file is never patched. An +unreadable file is left as it is and logged. The swap runs beside the +LaunchServices drop of ADR 0061 §2, and a copy whose swap fails is deleted, +as one whose drop fails is. ### 4. Sources made before this are not copied as they are -A seed whose row names another set (ready or `making`), or has no record -of §2, is deleted in the set its row names, as a baseline is, and its row is -dropped; the seed is then made again in the sources folder. The existing -stale-seed path alone would not do: it deletes in the current sources set, -where a seed of another set is not found. A baseline whose row names -another set is stale (`saved in , which copies cannot be fixed from; -save it again`) and answers `BASELINE_STALE` from the first request after -the worker starts, since core now checks baselines for staleness at -startup; it is deleted in its own set when removed. - -Shapes, messages and the table live in #1561's design tables. +A source with no lineage record, or whose lineage names another device set +than the copies' (the setting changed), is stale: a seed is deleted where +its row says and made again, and a baseline answers `BASELINE_STALE` +(`saved before simulators stopped sharing folders; save it again`) from +the first request after the worker starts. Each is deleted in its own set +when removed. ## Consequences -- A lease's simulator writes only into its own folders; seeds and - baselines stop growing, and leases of one kind stop sharing state. -- The first lease of each kind after the upgrade makes its seed again - (about 40 s once). Every baseline saved before must be saved again. -- `deviceSet: "default"` needs a `SIMLOCK_HOME` outside `/tmp` and `/var` - and short enough for the padding; the slow lane's homes move out of - `/tmp`. -- Making a source reads it once in full; each copy patches only the - recorded files. -- A file format that compresses or checksums a path (the `.tracev3` log - history today) keeps the old path; such a file is never followed as a - path today. +- A lease's simulator writes only into its own folders: seeds and + baselines stop growing, and leases of one kind stop sharing state, as + they do in Xcode's own parallel testing. +- Absolute paths an app stored before a baseline was saved resolve to the + lease's own container. +- No `SIMLOCK_HOME` is refused for its length or for being under `/tmp`; + the sources set needs no padding. +- Making a seed shows a throwaway `simlock-` simulator in the device set + for about 40 s, in Xcode's own set under `deviceSet: "default"`. +- Making a source reads it once in full (6.5–19.7 s for 2 GB measured as a + whole-copy swap); each copy patches only the recorded files. +- The first lease of each kind after the upgrade makes its seed again. + Every baseline saved before must be saved again. +- An unreadable file (1–2 locationd caches measured) and a format that + hides a UDID other than as ASCII or UTF-16 keep the old UDID. The + independent scan found none after the swap. +- In one of two lineages, a baseline's copy added a second Photos entry + for a photo the seed already had once its paths were its own (cause not + confirmed). ## Alternatives considered -- **Make seeds beside the copies, then swap UDIDs byte for byte.** Under - `deviceSet: "default"` the seed would sit in Xcode's own set, listed by - Xcode, DeviceHub and every `simctl list`, and hit by "Delete All - Simulators" (ADR 0048). Rejected for a separate folder of the same - length. -- **Make the seed read-only.** A copy that follows a path into the seed - then fails to write its own state. Rejected. -- **Rewrite each format in the copy, the sources staying where they are.** - Measured: paths remained in SQLite rows, indexes and caches, and copies - still wrote into the seed and into a baseline's used copy. Every format - needs its own parser, and each iOS release may add one. Rejected. -- **Rewrite one seed→copy pair.** A baseline saved from a copy names two - other simulators (the seed and the copy it was saved from). Rejected for - matching every foreign UDID. -- **Sources beside Xcode's set under `default`** - (`~/Library/Developer/CoreSimulator/`), always the right length and - never under `/private`. Rejected by the maintainer: everything Simlock - keeps stays in `SIMLOCK_HOME`, at the cost of refusing an unfit home. -- **Move the copies under `simlock` (`/d` beside `/s`).** Ends - leases running at the upgrade and needs `simctl` at startup to clear the - old set. Rejected for moving only the sources. -- **Migrate old baselines with a format rewrite.** Keeps the measured - leak for them. Rejected for "save it again". -- **Scan the whole copy each time.** 13–17 s for a 2.4 GB baseline. - Rejected for recording the files once per source. +- **No swap: copy then remove with the LaunchServices drop alone.** Seeds + and baselines stay clean, and Xcode's parallel testing works this way. + Measured: leases share Screen Time state through recreated folders, + stored absolute paths name deleted folders, and daemons keep failing + against them. Rejected for leases that last longer than a test run. +- **Keep the simulator a source was copied from, so its paths resolve.** + Measured: copies write into it (two leases into the same files), as + Xcode's clones write into their source. Rejected. +- **Pad the sources set to the device set's length and swap whole folder + paths** (this record's first version). The search for paths could not + be shown complete, files over 64 MiB were skipped, and an unfit + `SIMLOCK_HOME` was refused. Rejected for never booting a source, which + leaves only UDIDs to swap. +- **Rewrite each format in the copy.** Measured: paths remained in SQLite + rows, indexes and caches. Every format needs its own parser. Rejected. +- **Make the seed read-only.** A copy that follows a path into it fails + to write its own state. Rejected. +- **Detect misses by a deleted folder reappearing.** Measured: 11 files + reappeared against 50+ naming a foreign UDID. Rejected as a check. +- **Swap in the whole copy each time, with no record.** 6.5–19.7 s per + lease for 2 GB. Rejected for recording the files once per source. diff --git a/docs/internal/adr/README.md b/docs/internal/adr/README.md index 92503d7fb..63dbb308e 100644 --- a/docs/internal/adr/README.md +++ b/docs/internal/adr/README.md @@ -110,5 +110,5 @@ the status is stale. | [0073](0073-a-worker-may-enrol-the-phones-plugged-into-it.md) | A worker may enrol the phones plugged into it | Accepted; narrows 0022 §3, §5 and §6 | | [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 | -| [0076](0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md) | An iOS clone names only its own folders before its first boot | Accepted — not yet implemented; narrows 0061 §1 and §2 | +| [0076](0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md) | An iOS clone names only its own folders before its first boot | Accepted — not yet implemented; narrows 0061 §1, §2 and §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 | From ce51124b153f3d584b9f2bc1fa2bc507e883a6d5 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 19:58:41 +0100 Subject: [PATCH 07/10] docs(adr): 0076 a lineage records no device set, and a device keeps its source's lineage --- ...y-its-own-folders-before-its-first-boot.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index 7c4c66dd0..e00af0801 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -119,9 +119,11 @@ WAL in the source is flushed into its database (`wal_checkpoint(TRUNCATE)`), because a WAL frame carries a checksum a swap would break. The source records its **lineage**: the UDIDs of the simulators it was copied from that have booted (a seed: its throwaway; a baseline: its device's UDID and -its own source's lineage), the device set they ran in, and the files and -links that name any of them, found by reading every byte once with no size -limit. A file the host cannot read is recorded as unreadable. A WAL that +its own source's lineage) and the files and links that name any of them, +found by reading every byte once with no size limit. A lease's device +keeps its source's lineage, so a save knows it without reading the copy. +The device set is not recorded: switching `deviceSet` is refused while any +source is left (ADR 0048). A file the host cannot read is recorded as unreadable. A WAL that still holds frames after the flush is logged and never patched. ### 3. Every lease's copy swaps its lineage's UDIDs for its own before its first boot @@ -137,12 +139,11 @@ as one whose drop fails is. ### 4. Sources made before this are not copied as they are -A source with no lineage record, or whose lineage names another device set -than the copies' (the setting changed), is stale: a seed is deleted where -its row says and made again, and a baseline answers `BASELINE_STALE` -(`saved before simulators stopped sharing folders; save it again`) from -the first request after the worker starts. Each is deleted in its own set -when removed. +A source with no lineage record is stale: a seed is deleted and made +again, and a baseline answers `BASELINE_STALE` from the first request +after the worker starts, since core now checks baselines for staleness at +startup. A baseline saved from a device made before this has no lineage +either. The reason's wording lives in #1561's design tables. ## Consequences From 2f5ae89010f810b3f349d60a14dfb4bda87202be Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 20:43:01 +0100 Subject: [PATCH 08/10] docs(adr): 0076 deletes its throwaway through the making row and names the 0061 narrowings (#1561) --- ...es-only-its-own-folders-before-its-first-boot.md | 13 +++++++++++-- docs/internal/agent-rules/safety.md | 3 +++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index e00af0801..929034f90 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -8,7 +8,11 @@ now happens in a throwaway device, never in the source), §2's iOS Copy row (one more step before a clone's first boot, beside the LaunchServices database drop) and §4's iOS save (the leased device's log folder is - deleted with it). Sources still live in their own set, apart from the + deleted with it). It narrows §3 too: a source is also stale when it has + no lineage record (§4 below), beside the runtime or image gone or + changed. And §1's definition of a source ("has booted at least once") + no longer holds for an iOS source: it never boots, only its throwaway + does. Sources still live in their own set, apart from the copies. Shapes, limits and messages live in the feature's design tables (#1561); @@ -106,7 +110,12 @@ flowchart LR A seed is made by creating a throwaway simulator in the device set the copies live in, booting it to ready and shutting it down cleanly, then cloning it, unbooted, into the sources set as the seed; the throwaway and -its log folder are deleted. A baseline is saved as ADR 0061 §4 says, and +its log folder are deleted. The throwaway is in neither the registry nor +the sources set (under `deviceSet: "default"` it sits in Xcode's own set), +so the source's `making` row stores its UDID as soon as `simctl create` +returns it, the throwaway is deleted only through that row, and a restart +mid-make deletes it ([ADR 0001](0001-*.md) §6). This is one case beside +sources in [safety rule 1](../agent-rules/safety.md). A baseline is saved as ADR 0061 §4 says, and the leased device's log folder (`simctl delete` leaves it) is deleted with the device. A source therefore never names itself, and every path it carries names a deleted simulator of the same device set. The sources set diff --git a/docs/internal/agent-rules/safety.md b/docs/internal/agent-rules/safety.md index 1ac963978..95264e431 100644 --- a/docs/internal/agent-rules/safety.md +++ b/docs/internal/agent-rules/safety.md @@ -13,6 +13,9 @@ never enforce them only inside an individual rule or driver. baselines it keeps in its sources set, by an id its source table holds. `doctor --purge-orphans` may also delete a simulator in the sources set that no table row names. Nothing outside the sources set is reached this way. + An iOS seed's throwaway simulator, which sits in the device set the copies + live in, may be deleted too, only by the UDID its source's `making` row + stores ([ADR 0076](../adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md) §1). A physical device is the one kind of registry device Simlock did not create. It is Simlock's to act on only through its enrollment record, From ac1078613496ef1a690b6581bb8624aeac33bfb5 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 20:43:26 +0100 Subject: [PATCH 09/10] docs(adr): 0076 links ADR 0001 by its file name (#1561) --- ...os-clone-names-only-its-own-folders-before-its-first-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index 929034f90..b03cd58cd 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -114,7 +114,7 @@ its log folder are deleted. The throwaway is in neither the registry nor the sources set (under `deviceSet: "default"` it sits in Xcode's own set), so the source's `making` row stores its UDID as soon as `simctl create` returns it, the throwaway is deleted only through that row, and a restart -mid-make deletes it ([ADR 0001](0001-*.md) §6). This is one case beside +mid-make deletes it ([ADR 0001](0001-simlock-owned-device-roots.md) §6). This is one case beside sources in [safety rule 1](../agent-rules/safety.md). A baseline is saved as ADR 0061 §4 says, and the leased device's log folder (`simctl delete` leaves it) is deleted with the device. A source therefore never names itself, and every path it From db8e65591abe67a01a33404d2e32a1d69500341d Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Mon, 16 Nov 2026 20:46:01 +0100 Subject: [PATCH 10/10] =?UTF-8?q?docs(adr):=200076=20does=20not=20cite=20A?= =?UTF-8?q?DR=200001=20=C2=A76=20as=20authority=20for=20deleting=20the=20t?= =?UTF-8?q?hrowaway=20(#1561)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...lone-names-only-its-own-folders-before-its-first-boot.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md index b03cd58cd..2a632bfef 100644 --- a/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md +++ b/docs/internal/adr/0076-an-ios-clone-names-only-its-own-folders-before-its-first-boot.md @@ -113,8 +113,10 @@ cloning it, unbooted, into the sources set as the seed; the throwaway and its log folder are deleted. The throwaway is in neither the registry nor the sources set (under `deviceSet: "default"` it sits in Xcode's own set), so the source's `making` row stores its UDID as soon as `simctl create` -returns it, the throwaway is deleted only through that row, and a restart -mid-make deletes it ([ADR 0001](0001-simlock-owned-device-roots.md) §6). This is one case beside +returns it: without the row, [ADR 0001](0001-simlock-owned-device-roots.md) +§6's provision-then-register window would leave it an unrecorded orphan. The +throwaway is deleted only through that row, and a restart mid-make deletes it +by the recorded UDID, not as orphan reaping. This is one case beside sources in [safety rule 1](../agent-rules/safety.md). A baseline is saved as ADR 0061 §4 says, and the leased device's log folder (`simctl delete` leaves it) is deleted with the device. A source therefore never names itself, and every path it