Skip to content

A leased iOS simulator swaps its lineage's UDIDs for its own before its first boot #1570

Closed

Description

@V3RON

Part of #1561.

Scope

After this PR, a leased iOS simulator writes only into its own folders: every source flushes its WALs and records its lineage and the files naming it, and before its first boot each copy swaps its lineage's UDIDs for its own. Seeds made before are made again, and baselines saved before (or saved from a lease made before) answer BASELINE_STALE with a "save it again" reason from the first request.

If it goes wrong: a lease fails to provision, an app in a baseline's copy loses data, or an old baseline fails as PROVISION_FAILED instead of BASELINE_STALE.

Technical spec

Commit 0ca6059.

Rows

Behaviours: B5, B6, B7, B8, B9, B10
Stored state: S2, S3, S4, S6
Interfaces: I2, I3, I4, I5, I6, I7
Existing code: X1 (the flush and record half), X2 (the flush and record half), X3, X7 (version 4), X8, X9, X10, X11, X12 (SqliteOpener), X13, X14, X15, X16, X18

Facts

# Fact Source
F1 openFile(path).read({start, end}) streams a byte range, so a file of any size is read in chunks src/ports/filesystem.ts:58-62, :70
F2 The driver's listSources copies sourceStaleReason into each source's staleReason, which core's #checkStale writes to baselines.stale_reason src/drivers/ios/seeds.ts:100-107, src/core/baselines.ts:302-313
F3 A stale baselines row answers BASELINE_STALE at lease time src/leasing/acquisition-spec-resolver.ts:108
F4 PR #1585 (closed) holds a WAL flush, filesystem port additions and a file record for the dropped design; they may be copied into today's split files PR #1585 files src/drivers/ios/source-index.ts, src/ports/filesystem.ts

Modules touched

src/drivers/ios/ (seeds.ts, source-data.ts, device-data.ts, simulator-data.ts, driver-options.ts (the SqliteOpener option), index.ts (builds Seeds, :210-226), a new swap module, AGENTS.md), src/ports/filesystem.ts (and src/auth/admin-secret.test.ts:59, :146, which build whole Filesystem objects), src/ports/sqlite.ts, src/core/create-core.ts, src/core/baselines.ts, src/core/AGENTS.md:61 (when checkStale runs), docs/internal/flows/startup.md:63-72 (the converge steps; #1598 edits the same lines, a merge conflict at most), src/daemon/driver-discovery.ts, e2e/helpers/lane-home.ts, e2e/helpers/env.test.ts, a new e2e/slow-ios-source-isolation.test.ts; website pages that describe staleness: website/src/content/docs/docs/worker/baselines.mdx:75, :98, using-devices/errors.mdx:48, reference/errors.mdx:72, reference/cli.mdx:456. Searches: markReady, iosDriverData, isIosDriverData, sourceStaleReason, seedIsStale, checkStale, converge, SqliteOpener, openFile, ios_source_data in e2e/.

flowchart LR
  P[ports: filesystem, sqlite] --> D[drivers/ios]
  D --> C[core: converge, baselines]
  X[daemon: driver-discovery] --> D
  E[e2e: lane-home, isolation test] --> D
Loading

Rules in play

  • ADR 0076 §2–4 (on PR docs(adr): 0076 an iOS clone names only its own folders before its first boot #1564, branch feature/1561-adr, the bottom of this feature's stack): flush and record when a source is made; swap before each copy's first boot; a source with no lineage is stale.
  • ADR 0061 §2: the swap runs beside the LaunchServices drop, and a copy whose swap fails is deleted.
  • Documentation rule 9: the website pages listed under Modules touched say a baseline also turns stale when it was saved before this change, or from a lease made before it.
  • ADR 0036 §2: only the iOS driver reads or writes ios_source_data, ios_source_files and ios_device_data.
  • The ports manual: new filesystem and SQLite calls get a Node adapter and a fake in the same file, with bounded waits.

Retired words

  • changes only its LaunchServices database: a copy also has its lineage's UDIDs swapped before its first boot.

Tests

Seam: IosSimctlDriver with the fake filesystem, fake simctl and the fake SQLite opener (I5), modelled on src/drivers/ios/index-seed-provision.test.ts; core's startup and save with the generic FakeDriver and its setSources (src/core/fake-driver.ts:739), through the dispatcher as in src/daemon/dispatcher-baseline-lease.test.ts:187-190; B9 in the fast e2e lane in e2e/helpers/env.test.ts.

  • B5: a source is made: two WALs; a WAL that cannot be flushed; a WAL left with frames; a file over 64 MiB; UTF-16BE only; a link to the throwaway's log folder; an unreadable file; the walk fails; no lineage UDID; a baseline from a device with a lineage; a baseline from a device with none.
  • B6: a copy swaps before its first boot: a link; ASCII upper; lower case; UTF-16LE; UTF-16BE; a UDID across two chunks; a file over 64 MiB; the copy's own UDID; an unreadable file; the I6 line.
  • B7: a copy whose swap fails is deleted: a recorded file gone; a write that fails; a result of another length.
  • B8: a source with no lineage is never copied: seed lineage null; seed lineage []; baseline made before A leased iOS simulator swaps its lineage's UDIDs for its own before its first boot #1570, after start; baseline saved from an old device after the save; a warm target; checkStale failing at startup or after a save; a baseline with a lineage.
  • B9: the lane keeps an iOS seed with its lineage and ios_source_files rows between flows: the next env finds both; files rows dropped (fails); set_path outside <home>/devices/ios/sources.
  • B10: the slow-lane isolation test, its five cases.
  • B11: ios_device_data.lineage round-trips through describeDeviceDataTable, and isIosDriverData refuses a lineage entry that is not a UDID (in src/drivers/ios/device-data.test.ts); a source deleted through the driver also deletes its ios_source_files rows (extend the driver test that deletes a source). Assumption: these two behaviours get tests; the startup order of checkStale before the warm pool stays unclaimed in the manuals (decided in delivery, pending the maintainer).

Done when

  • pnpm test:changed passes, pnpm test:e2e e2e/helpers/env.test.ts passes, and CI's pnpm check passes.
  • On a Mac with an iOS runtime: scripts/slow-e2e.sh e2e/slow-ios-source-isolation.test.ts e2e/slow-baseline.test.ts passes.
  • src/drivers/ios/AGENTS.md (Seeds) describes the lineage, the file record and the swap; src/core/AGENTS.md and docs/internal/flows/startup.md say checkStale also runs at startup and after a save; the website pages listed say when a baseline turns stale for this reason; the Rows' messages (I3, I7) appear verbatim in the code.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 15, 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 15, 2026
  3. self-assigned this
    on Nov 15, 2026
  4. 35 remaining items

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

Metadata

Metadata

Assignees

Labels

task: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