Repository navigation
Description
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
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_filesandios_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;checkStalefailing at startup or after a save; a baseline with a lineage. - B9: the lane keeps an iOS seed with its lineage and
ios_source_filesrows between flows: the next env finds both; files rows dropped (fails);set_pathoutside<home>/devices/ios/sources. - B10: the slow-lane isolation test, its five cases.
- B11:
ios_device_data.lineageround-trips throughdescribeDeviceDataTable, andisIosDriverDatarefuses a lineage entry that is not a UDID (insrc/drivers/ios/device-data.test.ts); a source deleted through the driver also deletes itsios_source_filesrows (extend the driver test that deletes a source). Assumption: these two behaviours get tests; the startup order ofcheckStalebefore the warm pool stays unclaimed in the manuals (decided in delivery, pending the maintainer).
Done when
pnpm test:changedpasses,pnpm test:e2e e2e/helpers/env.test.tspasses, and CI'spnpm checkpasses.- On a Mac with an iOS runtime:
scripts/slow-e2e.sh e2e/slow-ios-source-isolation.test.ts e2e/slow-baseline.test.tspasses. src/drivers/ios/AGENTS.md(Seeds) describes the lineage, the file record and the swap;src/core/AGENTS.mdanddocs/internal/flows/startup.mdsaycheckStalealso 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
- How a seed is made from a throwaway: A seed is copied from a throwaway simulator that is then deleted #1569.
- Undashed, raw-byte or compressed UDIDs (iOS: a leased simulator reads and writes only its own folders, never its seed's #1561 Non-goals).
Depends on
Written by an agent.
Activity
test: the same-length swap keeps every spelling and separator it found (
feat(ios): the swap keeps the /private spelling and escaped separator…
test: the filesystem reads links and bytes and writes them back at th…
feat(ports): the filesystem reads a file's bytes and overwrites them …
test: a copy's recorded files are swapped too, and a swap that change…
feat(ios): a copy's recorded files are swapped before its first boot …
test: making a source flushes its WALs and records the files and link…
feat(ios): a made source has its WALs flushed and its files and links…
test: a copy whose swap fails is deleted and the provision fails (#1570)
test: a seed not indexed is made again and a baseline not indexed is …
35 remaining items
feat(ios): the daemon gives the iOS driver the Node SQLite opener, an…
docs: the lineage, the file record, the swap and when a baseline turn…
test: the filesystem port reads a link, repoints it and writes at an …
refactor(ios): the source record, the throwaway boot and the file wal…
test: the edge of a swap window, a baseline copy's swap and a file's …
docs: the iOS and core manuals fit their size limits and say what the…
test: lineage round-trips and a non-UDID is refused; deleting a sourc…
fix: every WAL is flushed before its database is read; section cites,…
fix: every WAL in a folder is flushed before it is listed again, sinc…
docs: the iOS manual drops the lineage's contents so the manuals fit …
fix: a copy's swap skips the LaunchServices database it just dropped (#…
test: the isolation fingerprint takes an unreadable system cache file…
docs(adr): accept 0076 (#1570)
feat(ios): a leased simulator swaps its lineage's UDIDs for its own b…