Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
50 commits
Select commit Hold shift + click to select a range
175c0ba
test: a lease's copy swaps every recorded foreign folder for its own …
V3RON Nov 15, 2026
6024065
feat(ios): a lease's copy has its links' foreign folders swapped for …
V3RON Nov 15, 2026
d25612c
test: the same-length swap keeps every spelling and separator it foun…
V3RON Nov 15, 2026
f53683c
feat(ios): the swap keeps the /private spelling and escaped separator…
V3RON Nov 15, 2026
d3c5344
test: the filesystem reads links and bytes and writes them back at th…
V3RON Nov 15, 2026
4313667
feat(ports): the filesystem reads a file's bytes and overwrites them …
V3RON Nov 15, 2026
177eca1
test: a copy's recorded files are swapped too, and a swap that change…
V3RON Nov 15, 2026
ea16665
feat(ios): a copy's recorded files are swapped before its first boot …
V3RON Nov 15, 2026
e2c386e
test: making a source flushes its WALs and records the files and link…
V3RON Nov 15, 2026
14a9f5d
feat(ios): a made source has its WALs flushed and its files and links…
V3RON Nov 15, 2026
058196c
test: a copy whose swap fails is deleted and the provision fails (#1570)
V3RON Nov 15, 2026
85d30e0
test: a seed not indexed is made again and a baseline not indexed is …
V3RON Nov 15, 2026
c20da61
feat(ios): a seed not indexed is made again and a baseline not indexe…
V3RON Nov 15, 2026
aae54f0
feat(e2e): the lane keeps a seed's file rows with its row (#1570)
V3RON Nov 15, 2026
f27ce71
test(e2e): the slow lane proves a lease writes only into its own fold…
V3RON Nov 15, 2026
5cfade0
docs(ios): the manual says a source is flushed and indexed and a copy…
V3RON Nov 15, 2026
ed86d6a
refactor(ios): the copy steps live in source-copy.ts so index.ts stay…
V3RON Nov 15, 2026
36822e6
test(ios): a copy's unchanged recorded file is not counted, and a mad…
V3RON Nov 15, 2026
4deefd7
fix(ios): a WAL's flush is listed again, the swap names the real devi…
V3RON Nov 15, 2026
bce83b1
chore(ios): sourcesFolderOf is private to sources-folder.ts (#1570)
V3RON Nov 15, 2026
bfb9b90
fix(ios): a source's index skips unreadable and huge files and the cl…
V3RON Nov 15, 2026
3bdeb46
refactor(ios): the index's skips live in one reader, and the lane tes…
V3RON Nov 15, 2026
252cba6
test(ios): the memory filesystem's faults are planted in one call (#1…
V3RON Nov 15, 2026
2c01e72
docs(ios): the iOS manual fits its 8000 characters again (#1570)
V3RON Nov 16, 2026
9d9573b
chore: supersede the closed #1585 design on this branch (#1570)
V3RON Nov 16, 2026
06829b2
test: a copy swaps its lineage's UDIDs for its own before its first b…
V3RON Nov 16, 2026
ed4ea70
feat(ios): a copy swaps a recorded file's lineage UDIDs for its own b…
V3RON Nov 16, 2026
9447c02
test: a source made is flushed, its lineage stored and its files nami…
V3RON Nov 16, 2026
bdc70a3
feat(ios): a source made is flushed, its lineage stored and its files…
V3RON Nov 16, 2026
249b697
test: a copy whose swap fails is deleted and the provision fails (#1570)
V3RON Nov 16, 2026
3e1c913
feat(ios): a copy whose swap fails is deleted and the provision fails…
V3RON Nov 16, 2026
114bd4b
test: a copy swaps every form of the lineage's UDIDs in its recorded …
V3RON Nov 16, 2026
9d4c807
feat(ios): a copy swaps every form of the lineage's UDIDs in its reco…
V3RON Nov 16, 2026
16f41c7
test: a baseline the driver calls stale is checked at startup and aft…
V3RON Nov 16, 2026
93395fc
feat(baselines): a baseline with no lineage is stale, checked at star…
V3RON Nov 16, 2026
8b221bf
test: the lane keeps an iOS seed's lineage and file rows between flow…
V3RON Nov 16, 2026
2150745
feat(ios): the daemon gives the iOS driver the Node SQLite opener, an…
V3RON Nov 16, 2026
990f10b
docs: the lineage, the file record, the swap and when a baseline turn…
V3RON Nov 16, 2026
549d422
test: the filesystem port reads a link, repoints it and writes at an …
V3RON Nov 16, 2026
ed609c6
refactor(ios): the source record, the throwaway boot and the file wal…
V3RON Nov 16, 2026
c25fc5f
test: the edge of a swap window, a baseline copy's swap and a file's …
V3RON Nov 16, 2026
1ea76ed
docs: the iOS and core manuals fit their size limits and say what the…
V3RON Nov 16, 2026
3c09207
test: lineage round-trips and a non-UDID is refused; deleting a sourc…
V3RON Nov 16, 2026
767222e
fix: every WAL is flushed before its database is read; section cites,…
V3RON Nov 16, 2026
36a7353
fix: every WAL in a folder is flushed before it is listed again, sinc…
V3RON Nov 16, 2026
0714148
docs: the iOS manual drops the lineage's contents so the manuals fit …
V3RON Nov 16, 2026
ba0e075
fix: a copy's swap skips the LaunchServices database it just dropped …
V3RON Nov 16, 2026
17f358d
test: the isolation fingerprint takes an unreadable system cache file…
V3RON Nov 16, 2026
0eb1ea2
Merge remote-tracking branch 'origin/task/1569' into HEAD
V3RON Nov 16, 2026
7fef0f8
docs(adr): accept 0076 (#1570)
V3RON Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/internal/EVENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ consumer, just operator diagnostics, so it's a `warn` log line (`daemon.driver-d
|---|---|---|---|---|
| `baseline.saved` | name, version, platform, model, OS version, mode, image tag (when the device has one), size in bytes (when it could be counted), lease id (the lease the save ended), requester id (the admin principal that ran `baseline save`) | once per save, after the `baselines` row is committed and before the saved device is deleted | BaselineService | implemented |
| `baseline.removed` | name, version, reason (`operator` for `baseline remove`, `nuke` for `nuke --delete-devices`, `replaced` when a newer save of the name dropped it), requester id (the principal that ran the command; absent for a removal nobody asked for) | once per version deleted, after its row is deleted | BaselineService | implemented |
| `baseline.stale` | name, version, reason (the driver's words: the runtime, image or emulator that changed) | when a check finds a baseline stale that had no stale reason before (again after it was fresh in between). The check runs at start, after `component.removed`, and before `baseline list` and `doctor` answer | BaselineService | implemented |
| `baseline.stale` | name, version, reason (the driver's words: the runtime, image or emulator that changed, or an iOS baseline saved without a lineage record) | when a check finds a baseline stale that had no stale reason before (again after it was fresh in between). The check runs at start, after `component.removed`, after a save, and before `baseline list` and `doctor` answer | BaselineService | implemented |

`BaselineService` (`src/core/baselines.ts`) is the only emitter; drivers keep and destroy the sources but never emit (architecture rule 5).

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 0076. An iOS clone names only its own folders before its first boot

- **Status:** Accepted — not yet implemented
- **Status:** Accepted
- **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)
Expand Down
2 changes: 1 addition & 1 deletion docs/internal/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ 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, §2 and §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; 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 |
| [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 |
3 changes: 2 additions & 1 deletion docs/internal/flows/startup.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,8 @@ Before step 16, a driver with `deviceTcp` sweeps the reverse rules into 47000-47
`device.shutdown` (initiator `startup-interrupted-reclaim`).
3. Spent deletes: `shutdown` devices that may not be granted again are deleted
inline. A failed delete is logged; the device stays `shutdown`.
4. Warm pool and capacity observer start. The pool closes the lease rows of its learned-kind
4. Baselines `checkStale` (a failure is logged), so a baseline the driver calls stale is known before the first lease.
5. Warm pool and capacity observer start. The pool closes the lease rows of its learned-kind
record whose lease the registry no longer holds, and its first pass boots the recorded kinds.
22. `queue.changed` with the first depth. Converge done → health `running`.

Expand Down
66 changes: 66 additions & 0 deletions e2e/helpers/env.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -212,3 +212,69 @@ describe("withSharedDaemon with keepSeeds", () => {
}
});
});

describe("withSharedDaemon with keepSeeds and an iOS seed", () => {
it("gives the next env the iOS seed's lineage and its file rows, even when its simulator set is outside the home", async () => {
const laneHome = join(tmpdir(), `simlock-lane-${randomBytes(3).toString("hex")}`);
const sources = `${laneHome}-sources`;
process.env.SIMLOCK_E2E_LANE_HOME = laneHome;
const udid = "11111111-2222-3333-4444-555555555555";
const lineage = JSON.stringify(["AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB"]);
const files = [
{ kind: "file", relative_path: "data/Library/a.plist" },
{ kind: "link", relative_path: "data/Library/b" },
{ kind: "unreadable", relative_path: "data/Library/c" },
];
try {
await mkdir(join(sources, udid), { recursive: true });
const first = await laneEnv();
try {
const database = new DatabaseSync(join(first.home, "state.db"));
try {
database.exec("PRAGMA busy_timeout=5000");
database
.prepare(
`INSERT INTO ios_source_data (source_id, kind, state, spec_key, udid, set_path,
device_type_id, runtime_id, model, os_version, maker, lineage, created_at)
VALUES ('seed_ios', 'seed', 'ready', ?, ?, ?, 'type', 'runtime', 'iPhone 16', '26.5', 'maker', ?, 1)`,
)
.run("iPhone 16\u0000runtime", udid, sources, lineage);
for (const file of files) {
database
.prepare(
"INSERT INTO ios_source_files (source_id, relative_path, kind) VALUES ('seed_ios', ?, ?)",
)
.run(file.relative_path, file.kind);
}
} finally {
database.close();
}
} finally {
await first.teardown();
}

const second = await laneEnv();
try {
const database = new DatabaseSync(join(second.home, "state.db"));
try {
expect(database.prepare("SELECT source_id, lineage FROM ios_source_data").all()).toEqual([
{ lineage, source_id: "seed_ios" },
]);
expect(
database
.prepare("SELECT kind, relative_path FROM ios_source_files ORDER BY relative_path")
.all(),
).toEqual(files);
} finally {
database.close();
}
} finally {
await second.teardown();
}
} finally {
delete process.env.SIMLOCK_E2E_LANE_HOME;
await rm(laneHome, { force: true, recursive: true });
await rm(sources, { force: true, recursive: true });
}
});
});
36 changes: 32 additions & 4 deletions e2e/helpers/lane-home.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ type Row = Record<string, string | number | null>;
interface KeptSeed {
readonly table: string;
readonly row: Row;
/** why: ADR 0076: an iOS seed's file record is its lineage's other half, so it is kept with the row. */
readonly files?: readonly Row[];
}

interface SeedTable {
Expand Down Expand Up @@ -77,13 +79,21 @@ export async function restoreKeptSeeds(home: string): Promise<void> {
const seeds = JSON.parse(await readFile(join(home, KEPT_SEEDS_FILE), "utf8")) as KeptSeed[];
const database = new DatabaseSync(join(home, "state.db"));
try {
for (const { table, row } of seeds) {
for (const { table, row, files } of seeds) {
const columns = Object.keys(row);
database
.prepare(
`INSERT INTO ${table} (${columns.join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`,
)
.run(...columns.map((column) => row[column] ?? null));
for (const file of files ?? []) {
const fileColumns = Object.keys(file);
database
.prepare(
`INSERT INTO ios_source_files (${fileColumns.join(", ")}) VALUES (${fileColumns.map(() => "?").join(", ")})`,
)
.run(...fileColumns.map((column) => file[column] ?? null));
}
}
} finally {
database.close();
Expand Down Expand Up @@ -138,7 +148,13 @@ async function readySeeds(home: string): Promise<KeptSeed[]> {
const database = new DatabaseSync(path, { readOnly: true });
try {
return SEED_TABLES.flatMap(({ table }) =>
readyRows(database, table).map((row) => ({ row, table })),
readyRows(database, table).map((row) => ({
row,
table,
...(table === "ios_source_data"
? { files: textRows(database, "ios_source_files", "source_id", String(row["source_id"])) }
: {}),
})),
).filter((seed) => existsSync(folderOf(seed)));
} finally {
database.close();
Expand All @@ -151,6 +167,17 @@ async function readySeeds(home: string): Promise<KeptSeed[]> {
* is read as bytes and decoded here.
*/
function readyRows(database: DatabaseSync, table: string): Row[] {
return textRows(database, table, undefined, undefined, "kind = 'seed' AND state = 'ready'");
}

/** why: the rows of a table with every text column read as bytes (see `readyRows`); a table the driver never made has none. */
function textRows(
database: DatabaseSync,
table: string,
column?: string,
value?: string,
where = "1 = 1",
): Row[] {
const columns = database.prepare(`PRAGMA table_info(${table})`).all() as {
name: string;
type: string;
Expand All @@ -159,9 +186,10 @@ function readyRows(database: DatabaseSync, table: string): Row[] {
const selected = columns.map(({ name, type }) =>
type === "TEXT" ? `CAST(${name} AS BLOB) AS ${name}` : name,
);
const filter = column === undefined ? where : `${column} = ?`;
return database
.prepare(`SELECT ${selected.join(", ")} FROM ${table} WHERE kind = 'seed' AND state = 'ready'`)
.all()
.prepare(`SELECT ${selected.join(", ")} FROM ${table} WHERE ${filter}`)
.all(...(value === undefined ? [] : [value]))
.map((row) =>
Object.fromEntries(
Object.entries(row).map(([name, value]) => [
Expand Down
198 changes: 198 additions & 0 deletions e2e/slow-ios-source-isolation.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
import { createHash } from "node:crypto";
import { existsSync } from "node:fs";
import { mkdir, readdir, readFile, readlink, stat, writeFile } from "node:fs/promises";
import { homedir } from "node:os";
import { join } from "node:path";
import { DatabaseSync } from "node:sqlite";
import { describe, expect, it } from "vitest";

import { withDaemon } from "./helpers/index.js";
import type { TestEnv } from "./helpers/env.js";
import { sweepStaleDeviceSets } from "./helpers/ios-device-set.js";
import { DEVICE_READY_MS } from "./helpers/wait.js";

interface Grant {
readonly deviceSet: string;
readonly leaseId: string;
readonly udid: string;
}

const LOG_ROOT = join(homedir(), "Library", "Logs", "CoreSimulator");
const BASELINE = "isolation";

async function lease(env: TestEnv, extra: readonly string[] = []): Promise<Grant> {
const granted = await env.cli(
["lease", "--platform", "ios", "--agent-id", "isolation", "--detach", ...extra],
{ timeout: DEVICE_READY_MS },
);
expect(granted.code, `lease failed: ${granted.stderr}`).toBe(0);
const grant = granted.json as {
device: { driverDeviceId: string };
environment: Record<string, string>;
lease: { id: string };
};
return {
deviceSet: grant.environment.SIMLOCK_IOS_DEVICE_SET as string,
leaseId: grant.lease.id,
udid: grant.device.driverDeviceId,
};
}

async function release(env: TestEnv, grant: Grant): Promise<void> {
const released = await env.cli(["release", grant.leaseId]);
expect(released.code, `release failed: ${released.stderr}`).toBe(0);
}

/** why: a file's size, modification time and hash are what "unchanged after the row turned ready" compares (ADR 0076). */
async function fingerprint(folder: string): Promise<Record<string, string>> {
const result: Record<string, string> = {};
for (const entry of await readdir(folder, { recursive: true, withFileTypes: true })) {
const path = join(entry.parentPath, entry.name);
if (entry.isSymbolicLink()) result[path] = `link ${await readlink(path)}`;
else if (entry.isFile()) {
const { mtimeMs, size } = await stat(path);
// why: a system service's cache file inside a source can be unreadable to the test (EPERM); the product records it as unreadable too, so its size and time stand for it.
const hash = await readFile(path).then(
(bytes) => createHash("sha256").update(bytes).digest("hex"),
(error: NodeJS.ErrnoException) => {
if (error.code === "EPERM" || error.code === "EACCES") return "unreadable";
throw error;
},
);
result[path] = `${size} ${mtimeMs} ${hash}`;
}
}
return result;
}

function sourceFolder(home: string, kind: "seed" | "baseline"): string {
const database = new DatabaseSync(join(home, "state.db"), { readOnly: true });
try {
database.exec("PRAGMA busy_timeout=5000");
const row = database
.prepare(
"SELECT set_path, udid FROM ios_source_data WHERE kind = ? AND state = 'ready' ORDER BY created_at DESC",
)
.get(kind) as { set_path: string; udid: string } | undefined;
if (row === undefined) throw new Error(`no ready ${kind} source in state.db`);
return join(row.set_path, row.udid);
} finally {
database.close();
}
}

function seedThrowaway(home: string): string {
const database = new DatabaseSync(join(home, "state.db"), { readOnly: true });
try {
const row = database
.prepare("SELECT lineage FROM ios_source_data WHERE kind = 'seed' AND state = 'ready'")
.get() as { lineage: string } | undefined;
const [throwaway] = JSON.parse(row?.lineage ?? "[]") as string[];
if (throwaway === undefined) throw new Error("the ready seed has no lineage");
return throwaway;
} finally {
database.close();
}
}

/** why: ADR 0076: a copy's `Logs` link names the copy's own folder, never the throwaway's or the saved-from lease's. */
async function expectOwnLogs(grant: Grant, strangers: readonly string[]): Promise<void> {
const target = await readlink(join(grant.deviceSet, grant.udid, "data", "Library", "Logs"));
expect(target.toUpperCase()).toContain(grant.udid.toUpperCase());
for (const stranger of strangers) expect(target.toUpperCase()).not.toContain(stranger);
}

async function expectNoFolderNamedAfter(
names: readonly string[],
deviceSet: string,
): Promise<void> {
for (const root of [deviceSet, LOG_ROOT]) {
const entries = existsSync(root) ? await readdir(root) : [];
for (const name of names) {
expect(
entries.filter((entry) => entry.toUpperCase() === name),
`${root} holds a folder named after ${name}`,
).toEqual([]);
}
}
}

async function swapMilliseconds(env: TestEnv, udid: string): Promise<number> {
const log = await readFile(env.logPath, "utf8");
for (const line of log.split("\n")) {
const match = new RegExp(
`swapped \\d+ files and \\d+ links in (\\d+) ms for ${udid}`,
"i",
).exec(line);
if (match !== null) return Number(match[1]);
}
throw new Error(`the daemon log has no swap line for ${udid}`);
}

// why: this lane needs the real simctl toolchain on Xcode 27, hence darwin-only; it never installs a runtime.
describe.skipIf(process.platform !== "darwin")(
"iOS source isolation (real simctl)",
{ tags: ["slow", "ios"] },
() => {
it(
"leaves the seed unchanged after three leases and a saved baseline's source unchanged after two, gives every copy a Logs link to its own folder, brings back no folder named after the throwaway or the saved-from lease, and swaps a baseline's copy in under 1 s",
{ timeout: 2_400_000 },
async () => {
await sweepStaleDeviceSets();
const env = await withDaemon({
configOverrides: { log: { level: "debug" } },
driver: "real",
});

// why: case 1, the seed, after three leases of one kind.
const first = await lease(env);
const seedFolder = sourceFolder(env.home, "seed");
const throwaway = seedThrowaway(env.home).toUpperCase();
const seedBefore = await fingerprint(seedFolder);
await expectOwnLogs(first, [throwaway]);
await release(env, first);
for (let more = 0; more < 2; more += 1) {
const next = await lease(env);
await expectOwnLogs(next, [throwaway]);
await release(env, next);
}
expect(await fingerprint(seedFolder), "the seed changed after its row was ready").toEqual(
seedBefore,
);

// why: case 2, a baseline saved from a used lease, after two leases of it.
const saved = await lease(env);
const marker = join(saved.deviceSet, saved.udid, "data", "Documents", "isolation.txt");
await mkdir(join(saved.deviceSet, saved.udid, "data", "Documents"), { recursive: true });
await writeFile(marker, "used");
const baseline = await env.cli(["baseline", "save", BASELINE, "--lease", saved.leaseId], {
timeout: 600_000,
});
expect(baseline.code, `baseline save failed: ${baseline.stderr}`).toBe(0);
const baselineFolder = sourceFolder(env.home, "baseline");
const baselineBefore = await fingerprint(baselineFolder);
const strangers = [throwaway, saved.udid.toUpperCase()];
const copies: Grant[] = [];
for (let n = 0; n < 2; n += 1) {
const copy = await lease(env, ["--baseline", BASELINE]);
copies.push(copy);
// why: case 3, each copy's Logs link names its own folder.
await expectOwnLogs(copy, strangers);
await release(env, copy);
}
expect(
await fingerprint(baselineFolder),
"the baseline's source changed after its row was ready",
).toEqual(baselineBefore);

// why: case 4, no folder named after the throwaway or the saved-from lease comes back.
await expectNoFolderNamedAfter(strangers, first.deviceSet);

// why: case 5, a baseline's copy swaps in under 1 s, so a fall back to a full read is caught.
for (const copy of copies) {
expect(await swapMilliseconds(env, copy.udid)).toBeLessThan(1000);
}
},
);
},
);
Loading
Loading