Repository navigation
Description
Request: #1251
Problem
A few source and test files are too big for a coding agent to read whole. Agents read them in many small sed -n ranges, each after a grep -n to find the spot. That costs tokens and turns, and an agent that sees one range at a time misses what sits next to it. In the last 10 agent sessions the worst file, src/drivers/android/index.ts, was read in 198 separate ranges.
On 059a270 22 files are over 1,400 lines (code) or 2,500 lines (tests). The worst is the Android driver: 3,573 lines, one class with 29 private fields, and an 8,442-line test file. It grew 500 lines in the week before this spec.
Who it is for
Every coding agent that builds, reviews or fixes a change in these modules: the implementer, the reviewers and bug triage.
Outcome
- The Android driver is one composition root and ten parts that own their own state. An agent working on emulator boot reads
emulator.tsand its tests, not the whole driver. - No file can pass 1,400 lines (code) or 2,500 (tests) without
pnpm checkfailing. The 22 files already over may not grow, except by a visible edit to the size test's list, until their own feature splits them. - The Android driver behaves exactly as before.
How it works for the user
The user is an agent changing the Android driver.
flowchart LR
A[Agent must change emulator boot] --> B[Reads the module manual's Files table]
B --> C[Opens emulator.ts and emulator.test.ts whole]
C --> D[Edits, runs pnpm check]
D --> E{A file over its limit?}
E -- no --> F[Done]
E -- yes --> G[pnpm check fails naming the file, its lines and the limit]
G --> H[Agent splits the file in the same change]
Before, an agent asked to change boot ran:
$ grep -n "#startEmulator\|#waitForReadiness" src/drivers/android/index.ts
$ sed -n 2880,2960p src/drivers/android/index.ts
$ sed -n 2750,2800p src/drivers/android/index.ts
... (many more ranges)
After:
$ cat src/drivers/android/emulator.ts # about 280 lines
A file that grows past its limit fails the size test in pnpm check:
FAIL src/source-hygiene.test.ts > tracked files > stay within their size limit
src/drivers/android/seeds.ts: 1412 lines; a code file may have at most 1400. Split it (ADR 0063).
Examples
The size test's verdict on a file. A file on the shrink-only list is one that was over its limit when the test landed.
| File | Lines | Listed length | Today | After |
|---|---|---|---|---|
src/core/lifecycle.ts (code) |
1,400 | not listed | passes | passes |
| a new code file | 1,401 | not listed | passes | fails: over 1,400 |
a test file x.test.ts |
2,501 | not listed | passes | fails: over 2,500 |
a helper test-x.ts or testing.ts |
2,501 | not listed | passes | fails: over 2,500 (counted as a test file) |
src/daemon/main.ts |
1,902 | 1,902 | passes | passes |
src/daemon/main.ts grown |
1,903 | 1,902 | passes | fails: grew past its listed length |
src/daemon/main.ts grown, its listed length raised to 1,930 in the same PR |
1,930 | 1,930 | passes | passes |
src/daemon/main.ts shrunk |
1,850 | 1,902 | passes | passes |
| a listed file split | 1,200 | 1,902 | passes | fails: under the limit, remove it from the list |
| a listed file deleted | none | 1,902 | passes | fails: no such file, remove it from the list |
vendor/…, website/… |
any | not listed | passes | passes (not scanned) |
What could go wrong
- A part moves a behaviour subtly (a timeout, an order of checks), and an emulator fails to boot or a foreign emulator is stopped. Unlikely: every moved test keeps its claim, and the ownership check stays one function.
- Open PRs that touch the Android driver (feat(android): android.emulator.hardwareKeyboard gives emulators a hardware keyboard #1082, test(e2e): find the Android SDK on Windows in the slow Android tests #1128, fix(android): stop the emulator's qemu child too when killing it on Windows #1129, test(audit): 20 weak tests fixed, 9 tests deleted, 21 folded into tables, since cd1c463 #1253) hit hand-made merge conflicts.
- Feature work that grows a file past its limit has to split it first, which makes that PR bigger.
Words used
- composition root: the one file that builds a module's parts and connects them, e.g.
AndroidDriverinsrc/drivers/android/index.tsafter this feature. - part: a file inside a module that owns its own state and exposes a small interface, taking its collaborators in an options object, e.g.
console-ports.tsowning the port reservations. - leaf part: a part that calls no other part, e.g.
adb-tools.ts. - shrink-only list: the size test's list of files that were over their limit when it landed, each with its length; a listed file may not grow past its listed length unless the same PR raises that length in the list, and it leaves the list once under its limit.
- seed: a shut-down device Simlock keeps only to copy into new devices (ADR 0061).
Non-goals
- Changing any behaviour of the Android driver, its messages, timeouts or files on disk.
- Decomposing the iOS driver,
daemon/main.ts,daemon/server.ts, the fleet coordinator, the lease acquisition coordinator orcontract/schemas.ts. Each is a later feature from Split the source and test files too big for agents to read whole #1251, following ADR 0063. - Splitting the 9 test files over 2,500 lines whose code files are under 1,400 (e.g.
src/cli/index.test.ts), or the 5 tests of the other listed code files. They stay on the shrink-only list for later features. - A Fallow rule for file length: Fallow 3.36.0 has none.
Completion conditions
src/drivers/android/index.tsis at most 1,400 lines andsrc/drivers/android/index.test.tsat most 2,500, and neither is on the shrink-only list.- Each of the ten parts of ADR 0063 §4 is a file in
src/drivers/android/; a part whose behaviour its own tests can show has its own test file, and every test that crosses parts stays on the root. pnpm checkruns the size test, and its shrink-only list holds exactly the scanned files over their limit, and neither Android file.src/drivers/android/AGENTS.mdnames every part in its Files table.- The whole Android test suite passes, with every test of 059a270 still present (moved or not) plus the two new ones (a pinned config hash, the per-device lock).
Open questions
none
Decisions
- ADR 0063 — A big module is one composition root over parts that own their state (PR docs(adr): propose 0063, a big module is one composition root over parts that own their state (#1259) #1262): the pattern, tests with the part, the size limits and their shrink-only list, and the Android driver's ten parts.
Shared values
| Value or state | Rule | Written by | Read by | Source |
|---|---|---|---|---|
| Size limits | 1,400 lines for a code file, 2,500 for a test file; lines as wc -l counts them |
#1263 | every task | ADR 0063 §3 |
| Test file | a name matching .test. or .spec., or a basename test-* or testing.ts; every other .ts, .tsx, .mts, .mjs, .js, .cjs file is code |
#1263 | every task | ADR 0063 §3; .dependency-cruiser.mjs:14 |
| Scanned files | tracked files under src/, ui/, e2e/, scripts/, .agents/scripts/ |
#1263 | every task | #1251's measure |
| Shrink-only list | in src/source-hygiene.test.ts: path → length; every scanned file over its limit on the commit #1263 merges from, with its length there (22 files on 059a270); a PR raises a length only by editing that line |
#1263 writes; each part task lowers the Android lengths, and the task that brings a listed file within its limit removes its entry | every task | ADR 0063 §3 |
adb-tools.ts interface |
the scoped env, run-or-throw (DriverCrashError on a non-zero exit), a device's AVD folder and checked driver data, the adb devices scan, a bounded adb shell read, the emulator's version, the wait |
#1264 | #1265–#1273 | ADR 0063 §4; src/drivers/android/index.ts:1028, src/drivers/android/index.ts:3008 |
Shared types in data.ts |
DeviceState (moved by #1266) and SystemImage (moved by #1268) live in src/drivers/android/data.ts, beside AndroidDriverData |
#1266, #1268 | every later task | ADR 0063 §1 (a helper two parts need goes to a leaf) |
| The ownership answer | ownership.ts runs every emu avd path query and returns its raw result: failed (with its error text) or a path, possibly blank; plus the folder comparison. Each caller keeps today's handling of each result |
#1265 | #1266–#1273 | ADR 0063 §4; src/drivers/android/index.ts:1850-1858, src/drivers/android/index.ts:2855-2868, src/drivers/android/index.ts:2050 |
ConsolePorts interface |
reserve and free a console port; one allocator per process runner, built by the root | #1266 | #1269, #1271, #1272 | ADR 0063 §4 |
avd-config.ts interface |
config.ini merge, library profile, hardware properties, the config hash, marks write and read | #1268 | #1270, #1273, #1271, #1272 | ADR 0063 §4 |
Emulator interface |
start (returns the process handle), wait until ready, shut down, wait for exit, log tail, stop an unowned emulator | #1269 | #1271, #1272 | ADR 0063 §4 |
SystemImages interface |
installed images, matching image, install, find and list components, tool versions, the fit refusal message | #1270 | #1273, #1272 | ADR 0063 §4 |
Catalog interface |
resolve a profile, the default avdmanager profile id, fitting API levels, listCatalog, resolveSpec |
#1273 | #1272 | ADR 0063 §4 |
DeviceTable interface |
get, set and delete a device's state; the per-device lock (also seed:<spec key>); listManaged; pre-root devices; reattach |
#1271 | #1272 | ADR 0063 §4 |
| Verbs that span parts | makeReady, shutdown, destroy, reclaim, estimate, removeComponent, advisories stay in the root and call the parts |
every part task | every part task | ADR 0063 §4 |
| Android manual | one Files row, Parts of AndroidDriver (ADR 0063), names every part; #1264 adds it, and each later part task adds its file to that row, so the manual stays within 150 lines |
#1264 adds; every later part task | every part task | src/drivers/android/AGENTS.md:1-141; src/docs-manuals.test.ts:9 |
| Testing rule 6 text | adds "a part of a decomposed module" as a reason for an internal-file test, and allows moving a test to the part in a behaviour-keeping change | #1263 | every task | ADR 0063 §2 |
Behaviours
| Behaviour (invoker, action, what it sees) | Seam | Cases | Task |
|---|---|---|---|
| A contributor runs the size test with a file over its limit that is not listed, and it fails naming the file, its lines and the limit | src/source-hygiene.test.ts |
code 1,400 passes, 1,401 fails; test 2,500 passes, 2,501 fails; test-x.ts and testing.ts count as tests |
#1263 |
| A contributor runs the size test with a listed file, and it fails when the file grew past its listed length or no longer needs the entry | src/source-hygiene.test.ts |
same length passes; shrunk passes; grew by one fails; under its limit fails; deleted fails | #1263 |
The driver runs adb and emulator commands through adb-tools.ts, and the whole-driver tests see the same environment, failures and devices as before |
src/drivers/android/index.test.ts |
"boots concurrent devices on different even ports and skips ports adb shows taken"; "destroys a plain Android device after its ownership check" | #1264 |
The driver asks ownership.ts what emu avd path answers, and the whole-driver tests see the same stops, refusals and listings as before |
src/drivers/android/index.test.ts |
"destroys a plain Android device after its ownership check"; "gates running state, processes and erasable marks on path proof" | #1265 |
The driver reserves console ports through console-ports.ts, and the whole-driver tests see the same ports as before |
src/drivers/android/index.test.ts |
"boots concurrent devices on different even ports and skips ports adb shows taken"; "skips a console port when something listens on %s that its own adb server does not list" | #1266 |
A caller passes adb arguments through passthrough-rules.ts, and is refused or served exactly as before |
src/drivers/android/passthrough-rules.test.ts |
"fills an emulator's serial into an adb command that names no device"; "refuses an emulator adb command that names another device, or that runs on another platform…"; "rejects a refusal with PassthroughRefusedError naming adb, never throwing it synchronously…"; "refuses kill-server, which would detach every leased emulator at once"; "refuses kill-server behind a global flag, not only in first position"; "refuses adb disconnect with or without an address, on the local CLI and through device.exec…"; and the other tests named in its task | #1267 |
The driver writes config and marks through avd-config.ts, and gets the same files, marks and pinned config hash as before |
src/drivers/android/avd-config.test.ts, and src/drivers/android/index.test.ts |
"rewrites the mark on makeReady's early-return branch"; "captures the config hash after the library's keys are written"; a fixed config's hash equals its value on 059a270 (new) | #1268 |
The driver boots and stops emulators through emulator.ts, and the whole-driver tests see the same launches, readiness and shutdowns as before |
src/drivers/android/index.test.ts |
"launches with the same arguments as before these options existed under the default config"; "starts the seed's boots and the copy's boot with -crash-report-mode never" | #1269 |
The driver installs, lists and finds system images through system-images.ts, with the same results and messages as before |
src/drivers/android/system-images.test.ts |
"fails naming downloads.acceptAndroidLicenses when licenses are unaccepted and the flag is off…"; "recognizes the alternate 'licenses have not been accepted' sdkmanager phrasing, not just 'not …"; "still fails when the install is rejected again after accepting licenses"; "installs the google_apis image for the host ABI with no timeout of its own, and reports it ins…"; "reports already-installed when the image was there before sdkmanager ran"; "gives two installs of one package, with an uninstall between them, different receipts"; and the other tests named in its task | #1270 |
The driver resolves specs and lists the catalog through catalog.ts, and gets the same profiles, fit verdicts and refusal messages as before |
src/drivers/android/catalog.test.ts |
"resolves the newest installed matching image"; "rejects a missing image naming its API level as the component, and starts no sdkmanager"; "fails a tag that is not installed for the API level as a runtime that cannot be downloaded, na…"; "gives a tagged request with no API level the newest API level that has an image of that tag…"; "fails a tag installed for no API level, with no API level named, naming the tag and no API lev…"; "lists resolvable models and installed API levels, defaulting to the newest"; and the other tests named in its task | #1273 |
The driver lists devices and locks each one through device-table.ts, and sees the same devices, serials and order of calls as before |
src/drivers/android/device-table.test.ts |
"reports one running root AVD, one stopped root AVD and the running AVD's process"; "listManaged settles after the timeout when one serial's mark read never answers, reports that …"; "reads the erasable mark with head -c 4096, and a mark cut at that cap is read as no mark"; "listManaged passes a 30-second timeout to adb devices"; "treats an otherwise-stopped AVD as transitioning when an unattributable transitional serial is…"; "still resolves a stopped AVD as stopped when adb reports no serials at all"; and the other tests named in its task; a second call under one device's lock waits for the first, a call on another device does not (new) | #1271 |
The driver makes seeds and copies through seeds.ts, with the same staleness, locking and cleanup as before |
src/drivers/android/seeds.test.ts |
"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 | #1272 |
A test of the whole driver still passes through AndroidDriver after 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 |
src/drivers/android/index.test.ts, src/drivers/android/index-lifecycle.test.ts |
the 99 tests that stay on the root, wiring and lifecycle | #1272 |
Tasks
flowchart LR
T1[#1263 size test] --> T2[#1264 adb-tools] --> T3[#1265 ownership] --> T4[#1266 console-ports] --> T5[#1267 passthrough-rules] --> T6[#1268 avd-config] --> T7[#1269 emulator] --> T8[#1270 system-images] --> T11[#1273 catalog] --> T9[#1271 device-table] --> T10[#1272 seeds, root done]
Every part task changes src/drivers/android/index.ts and its test file, so they run one after the other.
- Size test: a code file stays at 1,400 lines and a test file at 2,500 #1263 Size test —
pnpm checkfails a file over its limit, and the 22 files over today may only shrink. Risk: a wrong file pattern fails a good PR or passes a big file. - Android driver: adb-tools.ts, the leaf part for env, commands and device folders #1264 adb-tools.ts — the commands, environments and device folders every part needs live in one leaf part. Risk: a command runs with the wrong
ANDROID_AVD_HOME. - Android driver: ownership.ts, the one check before a stop, load or destroy #1265 ownership.ts — the
emu avd pathcheck is one function every caller goes through. Risk: a foreign emulator is stopped, or an own one is left running. - Android driver: console-ports.ts owns the console port reservations #1266 console-ports.ts — console port reservations have one owner. Risk: two emulators get the same port.
- Android driver: passthrough-rules.ts holds the adb refusal rules #1267 passthrough-rules.ts — the adb refusal rules are a pure part with their own tests. Risk: a refused command passes, or an allowed one is refused.
- Android driver: avd-config.ts owns config.ini, the config hash and the marks #1268 avd-config.ts —
config.ini, the config hash and the marks have one owner. Risk: seeds are judged stale and made again for no reason. - Android driver: emulator.ts starts, readies and stops an emulator #1269 emulator.ts — starting, readying and stopping an emulator is one part. Risk: a boot fails or hangs.
- Android driver: system-images.ts owns system images and components #1270 system-images.ts — images and components have one owner. Risk: an install, a licence check or a removal changes.
- Android driver: catalog.ts owns device profiles, fit and the resolved-spec cache #1273 catalog.ts — device profiles, fit verdicts and the resolved-spec cache have one owner. Risk: a model resolves to another profile, or a refusal message changes.
- Android driver: device-table.ts owns device states, locks and listing #1271 device-table.ts — device states, per-device locks and listing have one owner. Risk: a device is missed after a restart.
- Android driver: seeds.ts owns seeds and copies, and the root is done #1272 seeds.ts — seeds and copies are one part, and
AndroidDriveris only the root. Risk: a seed is made twice, or a copy fails.
Completion conditions → tasks: Android files under their limits and off the list → #1272. Ten parts → #1264–#1273. Size test with 20 listed files → #1263 (22 listed) and #1272 (two removed). Manual names every part → #1264 adds the parts row, each later part task adds its file to it. Whole Android suite passes → every task.
Open work in the same area:
- feat(android): android.emulator.hardwareKeyboard gives emulators a hardware keyboard #1082 (open,
android.emulator.hardwareKeyboard): adds 30 lines tosrc/drivers/android/index.tsand 95 to its test. No Depends on: the maintainer chose to start now. If it merges after Size test: a code file stays at 1,400 lines and a test file at 2,500 #1263 it raises the two listed lengths in its own PR; whichever merges second rebases. - fix(agent-device): an allocate's device mode reaches the lease request (#1223) #1225 (open PR, +35 to
src/agent-device/edge.test.ts), ios.simulator.headless false shows each simulator in DeviceHub or Simulator.app #1239 and Warm pool: a baseline kind is learned on its Nth lease in 24 h and warms its newest version #1261 (ready tasks, iOS driver,main.ts, schemas,converger.test.ts): each raises the listed lengths it grows, in its own PR. No Depends on. - feat(ios): ios.simulator.audio keeps every simulator silent #1258 (draft, +35 to
src/core/config.test.ts, 2,485 lines on 059a270): it takes that file to 2,519. If it merges before Size test: a code file stays at 1,400 lines and a test file at 2,500 #1263, Size test: a code file stays at 1,400 lines and a test file at 2,500 #1263 lists the file; if after, feat(ios): ios.simulator.audio keeps every simulator silent #1258 splits the file or adds its line to the list. No Depends on. - test(e2e): find the Android SDK on Windows in the slow Android tests #1128, fix(android): stop the emulator's qemu child too when killing it on Windows #1129 (drafts, Android emulator fixes) and test(audit): 20 weak tests fixed, 9 tests deleted, 21 folded into tables, since cd1c463 #1253 (draft, test audit): touch the same files. No Depends on: they rebase onto the parts.
- feat(ios): lease --label names the leased simulator #1243: touches the iOS driver, schemas, fleet and lease coordinators. It raises the lengths it grows if it merges after Size test: a code file stays at 1,400 lines and a test file at 2,500 #1263. No Depends on.
Written by an agent.
Activity
docs(adr): 0063 narrows testing rule 6 for parts (#1259)
docs(adr): 0063 adds the catalog part, three-way ownership answer, vi…
V3RON commentedon Nov 4, 2026
Spec updated: all sections written; Android driver pilot (ADR 0063, PR #1262), size test #1263, ten part tasks #1264–#1273.
Written by an agent.
docs(adr): 0063 draws the parts from the code, raw ownership answers,…
docs(adr): accept 0063 (#1259)
docs(adr): 0063 defines the scanned set and test files, and states th…
github-actions commentedon Nov 4, 2026
Closing: all 11 sub-issues are closed. The PR that closed the last one walks the completion conditions (delivery rule 9); reopen this if one does not hold on
main. Flip its ADRs to Accepted if delivery has not.github-actions commentedon Nov 4, 2026
Closing: all 11 sub-issues are closed. The PR that closed the last one walks the completion conditions (delivery rule 9); reopen this if one does not hold on
main. Flip its ADRs to Accepted if delivery has not.docs(adr): propose 0063, a big module is one composition root over pa…
refactor(android): seeds.ts is a part of the Android driver (#1286)
V3RON commentedon Nov 4, 2026
Delivery run
Merged: #1262 (ADR 0063), #1274 (#1263), #1276 (#1264), #1277 (#1265), #1278 (#1266), #1279 (#1267), #1280 (#1268), #1281 (#1269), #1283 (#1270), #1284 (#1273), #1285 (#1271), #1286 (#1272)
Parked: none
Waiting: none
Decided: #1270, #1273, #1271, #1272 — new tests for code moved unchanged that no test pinned on the base? → no; the root wiring tests stay (decision comments on #1283, #1284, #1285)
Asleep: 7 min
Written by an agent.