Repository navigation
Description
Part of #1259.
Scope
After this PR, seeds.ts is a part of the Android driver (ADR 0063 §4). It owns the sources table and the set of seeds being made, and does listing sources, provision (the seed lock, finding, judging stale and making a seed, then copying it), copying a baseline source, saving a device as a source, destroying sources, sweeping leftovers, and whether a fresh seed exists. AndroidDriver builds it in its constructor, passes it the options it needs, and delegates to it. Behaviour, messages, timeouts and files on disk do not change. It takes the per-device lock and the device states from device-table.ts, never a lock of its own, so a save and a destroy of one device stay serialized. This is the last part: after it the root tests split into index.test.ts (the root's wiring) and index-lifecycle.test.ts (the verbs that span parts), each under 2,500 lines.
In short
About 566 lines of code move out of the 3,573-line driver into a file an agent reads whole. Nothing a user or a caller sees changes. A part is a file that owns its own state and takes its collaborators in an options object; it never imports index.ts.
flowchart LR
R["index.ts: AndroidDriver"] --> P["seeds.ts (new part)"]
R --> O[parts moved earlier]
P --> O
What a user would notice if this goes wrong: a seed is made twice or never, or a copy fails.
Technical spec
Facts
Commit 059a270. Line numbers are on that commit; earlier tasks of #1259 move code, so the implementer finds each name by search.
| # | Fact | Source |
|---|---|---|
| F1 | every name this task moves, at its line on 059a270 (the exact assignment of every name of the file, made from its syntax tree) | SNAPSHOT_SAVE_TIMEOUT_MS at src/drivers/android/index.ts:144; PROVISION_ESTIMATE_MS at src/drivers/android/index.ts:150; SEED_MAKE_ESTIMATE_MS at src/drivers/android/index.ts:152; BOOT_SNAPSHOT at src/drivers/android/index.ts:161; SOURCES_DIRECTORY at src/drivers/android/index.ts:162; SEED_COPY_TIMEOUT_MS at src/drivers/android/index.ts:163; STALE_REASON_MAX_LENGTH at src/drivers/android/index.ts:164; SEED_MAKE_CEILING_MS at src/drivers/android/index.ts:166; SEED_POWER_OFF_TIMEOUT_MS at src/drivers/android/index.ts:167; SAVE_EXIT_POLL_INTERVAL_MS at src/drivers/android/index.ts:169; SEED_SHELL_TIMEOUT_MS at src/drivers/android/index.ts:171; SeedRecord at src/drivers/android/index.ts:287; savedKindOf at src/drivers/android/index.ts:586; #sources at src/drivers/android/index.ts:636; #making at src/drivers/android/index.ts:638; listSources at src/drivers/android/index.ts:1150; #sweepLeftovers at src/drivers/android/index.ts:1181; #orphanSources at src/drivers/android/index.ts:1191; #sourceFolders at src/drivers/android/index.ts:1204; #removeSource at src/drivers/android/index.ts:1214; #staleReasonOf at src/drivers/android/index.ts:1231; #removeSeed at src/drivers/android/index.ts:1261; saveSource at src/drivers/android/index.ts:1271; #kindOfDevice at src/drivers/android/index.ts:1337; #powerOffForSave at src/drivers/android/index.ts:1359; #exitedWithin at src/drivers/android/index.ts:1396; destroySource at src/drivers/android/index.ts:1415; provision at src/drivers/android/index.ts:1432; #provisionFromSource at src/drivers/android/index.ts:1483; #makeSeed at src/drivers/android/index.ts:1523; #bootSeedTwice at src/drivers/android/index.ts:1590; #snapshotSource at src/drivers/android/index.ts:1610; #coldState at src/drivers/android/index.ts:1621; #bootToSnapshot at src/drivers/android/index.ts:1625; #awaitSeedPowerOff at src/drivers/android/index.ts:1635; #saveBootSnapshot at src/drivers/android/index.ts:1661; #copySeed at src/drivers/android/index.ts:1686; #copyAvd at src/drivers/android/index.ts:1694; #hasFreshSeed at src/drivers/android/index.ts:2183; #destroySeedsOf at src/drivers/android/index.ts:2302; #assertAndroidSpec at src/drivers/android/index.ts:3058 |
| F2 | a part in this folder takes an options object and is built by the driver | src/drivers/android/adb-registrar.ts:22-25, src/drivers/android/index.ts:675 |
| F3 | such a part has its own test file that builds it directly | src/drivers/android/adb-registrar.test.ts:9 |
| F4 | the folder's testing.ts is imported by index.test.ts, and the test file's shared helpers sit outside any describe |
src/drivers/android/index.test.ts:46, src/drivers/android/index.test.ts:5117-5410, src/drivers/android/index.test.ts:7306-8212 |
| F5 | Fallow fails CI on an import loop between files (circular-dependencies, default error) and on any dead-code finding |
node_modules/fallow/schema.json RulesConfig at pnpm-lock.yaml:2180; docs/internal/agent-rules/toolchain.md:51-53 |
| F6 | test-lint flags an added sibling import in a test unless a why: sits above the first describe |
.agents/scripts/test-lint.mjs:141-148 |
| F7 | the module manual is 141 lines, and manuals may have at most 150 | src/drivers/android/AGENTS.md:1-141, src/docs-manuals.test.ts:9 |
| F8 | the root tests that prove the root still reaches this part | src/drivers/android/index.test.ts:6437 "provisions a device named after a baseline source as a copy of that source's folder" |
| F9 | saveSource runs under the same per-device lock as makeReady and destroy |
src/drivers/android/index.ts:1275, src/drivers/android/index.ts:1727, src/drivers/android/index.ts:1820 |
Modules touched
Searches: grep -rn of each F1 name under src/ (hits only in src/drivers/android/index.ts, src/drivers/android/index.test.ts and, for the exports index.ts keeps, their importers); ls src/drivers/android/seeds.ts (absent on 059a270).
flowchart LR
R["index.ts (changed)"] --> P["seeds.ts (new)"]
P --> E["earlier parts, data.ts"]
src/drivers/android/seeds.ts: new; the part. It imports onlydata.ts, files that exist on 059a270 and the parts of earlier tasks; anything else reaches it as an option or a callback.src/drivers/android/index.ts: builds the part, delegates, and loses the F1 names.src/drivers/android/index.test.ts: loses the tests named under Tests.src/drivers/android/seeds.test.ts: new; its tests.src/drivers/android/data.ts: takes a type two parts share, when this task moves one.src/drivers/android/testing.ts: takes any helper two test files now use.src/drivers/android/AGENTS.md: the one Files row for the parts (ADR 0063), which Android driver: adb-tools.ts, the leaf part for env, commands and device folders #1264 adds, gainsseeds.tsand a few words; no new row (F7).src/source-hygiene.test.ts: the two Android entries of the shrink-only list take their new lengths; an entry whose file is now within its limit is removed.src/drivers/android/index.test.tssplits into itself (the root's wiring) andsrc/drivers/android/index-lifecycle.test.ts(the verbs that span parts).
Contract and event changes
none: the task moves code inside the Android driver; no file under src/contract/ and no event changes (search: git grep -n "drivers/android" src/contract gives 0 hits).
Other code on the same state
The state this part owns: the sources table and the set of seeds being made. Searches: grep -n of each owned name in src/drivers/android/index.ts and under src/ outside the Android folder (0 hits outside). After this task the root and later tasks (none) reach that state only through this part's interface; none keeps a copy.
Failure modes
none: the task crosses no new boundary and writes no new state. Every call to adb, emulator, avdmanager or sdkmanager it moves keeps its arguments, environment and time limit (F1).
Rules in play
- ADR 0063 §1, "A part never calls the root": the part takes collaborators and callbacks in its options and imports no
index.ts(F5 fails a loop). - ADR 0063 §2, tests sit with the part: a test moves only when everything it asserts is made by this part; a test across parts stays in the root's tests. A part test file has one
why:above its firstdescribenaming "a part of a decomposed module" (F6). - ADR 0063 §3: a listed file that is now within its limit leaves the shrink-only list in this PR.
- Architecture rule 14, "nothing outside the directory imports a file inside it": only files in
src/drivers/android/import the part. - Architecture rule 17, "A comment starts with
why:": a moved comment that is not awhy:, or that no longer holds, is deleted. - Documentation rule 7 and
src/docs-manuals.test.ts: the manual stays within 150 lines (F7).
Tests
The seam is src/drivers/android/seeds.test.ts, a new file modelled on src/drivers/android/adb-registrar.test.ts. These 32 tests move there, each keeping its claim and cases, because everything each asserts is made by this part: src/drivers/android/index.test.ts:338 "creates a tagged device from the host ABI's image when the tag is installed for two ABIs"; src/drivers/android/index.test.ts:362 "creates a tagged device from a foreign ABI's image when that is the only image of the tag"; src/drivers/android/index.test.ts:396 "fails provisioning a tagged spec whose image went missing after it resolved, offering no downl…"; src/drivers/android/index.test.ts:1717 "does not change the config hash when simlock.mark is present in config.ini"; src/drivers/android/index.test.ts:2008 "captures differing hardware properties in the config hash, proving they land before it is comp…"; src/drivers/android/index.test.ts:2018 "shadows a devices.xml profile with a built-in one of the same name and never applies propertie…"; src/drivers/android/index.test.ts:2029 "rejects a hardware-property value with an embedded line break, defense in depth beyond the dev…"; src/drivers/android/index.test.ts:2165 "provisions a library device with every hardware value of the profile in config.ini"; src/drivers/android/index.test.ts:2176 "provisions identical hw.* and vm.heapSize lines whether avdmanager list device lists pi…"; src/drivers/android/index.test.ts:2193"removes everyhw.(excepthw.cpu.arch), vm.heapSizeandskin.line the seed wrote th…";src/drivers/android/index.test.ts:2210"keepsimage.sysdir.1, tag.id, abi.type, target, hw.cpu.arch, disk.dataPartition.siz…"; src/drivers/android/index.test.ts:2237 "sets PlayStore.enabled=yes on a Play Store image when the profile allows Play Store, and no…"; src/drivers/android/index.test.ts:2251"reads an image's tags fromSystemImage.TagId, and from the folder name when it has none"; src/drivers/android/index.test.ts:2268"writes the profile's boot properties toboot.prop, and removes a seed's boot.propwhen the…";src/drivers/android/index.test.ts:2307"refuses %s with %j beforeavdmanager create avdruns";src/drivers/android/index.test.ts:2339"refuses NUL in adevices.xmlvalue, through the one shared check";src/drivers/android/index.test.ts:2380"rethrows and runs noavdmanager deletewhen a write afteravdmanager create avdfails";src/drivers/android/index.test.ts:2394"seedsavdmanager create avdwith the first profileavdmanager list deviceprints, also whe…";src/drivers/android/index.test.ts:5756"creates a phone from the Play Store image at the newest level, and the TV from the android-tv …";src/drivers/android/index.test.ts:6110"creates the device from a fitting image, never a misfit one that sorts first";src/drivers/android/index.test.ts:6125"follows today's order among fitting images: %s first";src/drivers/android/index.test.ts:6160"throws RUNTIME_MISSING when no fitting image is left, and creates nothing from a misfit one…";src/drivers/android/index.test.ts:6316"tells why a seed is stale, cut to 300 characters, and clears the reason when the image and emu…";src/drivers/android/index.test.ts:6379"destroys a stale seed and makes it again at the next provision";src/drivers/android/index.test.ts:6693"removes a seed's folder and row and throws when making it fails at any step";src/drivers/android/index.test.ts:6804"removes the device's folder and throws when copying the seed fails";src/drivers/android/index.test.ts:6817"makes one seed when two plain leases of one kind are provisioned at once";src/drivers/android/index.test.ts:6840"provisions a kind with a ready seed while another kind's seed is being made, and leaves that k…";src/drivers/android/index.test.ts:6945"lists each ready seed with its size, reports a sources folder no row names as an orphan, and d…";src/drivers/android/index.test.ts:6983"lists no size for a seed whose size cannot be counted";src/drivers/android/index.test.ts:7000"sweeps a making row an earlier process left, stopping its emulator by path, and one this proce…";src/drivers/android/index.test.ts:8365"writes the same config.ini keys for a rich devices.xml profile as for a plain one". Every other test stays where it is; F8's tests stay insrc/drivers/android/index.test.ts` and keep proving the root reaches the part.
- The driver makes seeds and copies through
seeds.ts, with the same staleness, locking and cleanup as before; cases: "creates a tagged device from the host ABI's image when the tag is installed for two ABIs"; "creates a tagged device from a foreign ABI's image when that is the only image of the tag"; "fails provisioning a tagged spec whose image went missing after it resolved, offering no downl…"; "does not change the config hash when simlock.mark is present in config.ini"; "captures differing hardware properties in the config hash, proving they land before it is comp…"; "shadows a devices.xml profile with a built-in one of the same name and never applies propertie…"; and the other tests named in its task. - A test of the whole driver still passes through
AndroidDriverafter every part is moved, split between the wiring and the lifecycle test files; cases: the 99 tests that stay on the root, wiring and lifecycle.
Done when
pnpm exec vitest run --project unit src/drivers/androidpasses, and its number of tests is the base's plus the tests this task adds.src/drivers/android/seeds.tsexists, and only files insrc/drivers/android/import it: dependency-cruiser'spast-indexrule (.dependency-cruiser.mjs:36-37), run bypnpm check, fails any import of it from outside the folder.src/drivers/android/index.tsdefines none of the F1 names, except eachDrivermethod (and otherAndroidDrivermember the core or the daemon calls), which stays and delegates; the root's field that holds the part takes a name that is not an F1 name; an F1 constant the root still uses is imported from the part.- In
src/source-hygiene.test.ts, each Android entry equals its file's new line count, or is gone when the file is within its limit. src/drivers/android/index.tsis at most 1,400 lines and every Android test file at most 2,500, and neither Android entry is on the shrink-only list.pnpm checkpasses.
Out of scope
- Any change of behaviour, message, timeout or file on disk.
- The parts of the other tasks of Split the source and test files too big for agents to read whole #1259.
Depends on
Written by an agent.
Activity
test(android): seeds.ts makes seeds and copies, applies profiles, jud…
test(android): the root tests split into index.test.ts and index-life…
refactor(android): seeds.ts takes the catalog itself; testing.ts expo…
test(android): the source destroy test asserts the emulator is stoppe…
docs(adr): ADR 0063 is Accepted (#1272)
test(core): the provisioner's only-creator scan allows the Android dr…
refactor(android): seeds.ts is a part of the Android driver (#1286)