Skip to content

Android driver: catalog.ts owns device profiles, fit and the resolved-spec cache #1273

Closed

Description

@V3RON

Part of #1259.

Scope

After this PR, catalog.ts is a part of the Android driver (ADR 0063 §4). It owns the profile registry, the resolved-profile cache that resolveSpec writes, and the kept avdmanager list device answer, and does which profile a model name resolves to, the default avdmanager profile id, the API levels that fit a profile, listCatalog, default models, and resolveSpec's choice and refusal messages. 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. advisories and estimate stay in the root: they span parts. AndroidDriverOptions stays in index.ts; defaultDeviceProfileSources takes only the fields it reads.

In short

About 134 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["catalog.ts (new part)"]
  R --> O[parts moved earlier]
  P --> O
Loading

What a user would notice if this goes wrong: a model resolves to another profile, or a refusal message changes.

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) ANDROID_DEFAULT_MODELS at src/drivers/android/index.ts:314; #avdmanagerDevices at src/drivers/android/index.ts:614; #deviceProfiles at src/drivers/android/index.ts:616; #profileSources at src/drivers/android/index.ts:617; #resolvedProfiles at src/drivers/android/index.ts:631; resolveSpec at src/drivers/android/index.ts:1088; listCatalog at src/drivers/android/index.ts:2132; #profileFor at src/drivers/android/index.ts:2196; #defaultAvdmanagerDeviceId at src/drivers/android/index.ts:2202; #taggedApiLevel at src/drivers/android/index.ts:2586; fittingApiLevels at src/drivers/android/index.ts:3252; compareCatalogImages at src/drivers/android/index.ts:3260; userDevicesXmlPath at src/drivers/android/index.ts:3504; defaultDeviceProfileSources at src/drivers/android/index.ts:3511
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:1373 "seeds a library provision from the avdmanager list device read the catalog made"

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/catalog.ts (absent on 059a270).

flowchart LR
  R["index.ts (changed)"] --> P["catalog.ts (new)"]
  P --> E["earlier parts, data.ts"]
Loading
  • src/drivers/android/catalog.ts: new; the part. It imports only data.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/catalog.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, gains catalog.ts and 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.

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 profile registry, the resolved-profile cache that resolveSpec writes, and the kept avdmanager list device answer. 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 (#1271, #1272) 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 first describe naming "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 a why:, 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/catalog.test.ts, a new file modelled on src/drivers/android/adb-registrar.test.ts. These 64 tests move there, each keeping its claim and cases, because everything each asserts is made by this part: src/drivers/android/index.test.ts:191 "resolves the newest installed matching image"; src/drivers/android/index.test.ts:212 "rejects a missing image naming its API level as the component, and starts no sdkmanager"; src/drivers/android/index.test.ts:279 "fails a tag that is not installed for the API level as a runtime that cannot be downloaded, na…"; src/drivers/android/index.test.ts:303 "gives a tagged request with no API level the newest API level that has an image of that tag…"; src/drivers/android/index.test.ts:381 "fails a tag installed for no API level, with no API level named, naming the tag and no API lev…"; src/drivers/android/index.test.ts:912 "lists resolvable models and installed API levels, defaulting to the newest"; src/drivers/android/index.test.ts:947 "pairs a model with an installed API level whose only image has a foreign ABI, when the image f…"; src/drivers/android/index.test.ts:973 "reports no default runtime and no installed API levels without system images"; src/drivers/android/index.test.ts:991 "lists a built-in profile's avdmanager id as another name for its model"; src/drivers/android/index.test.ts:1002 "lists no other name when the id equals the display name ignoring case"; src/drivers/android/index.test.ts:1019 "resolves every listed name of every listed model, in upper and lower case, to that model"; src/drivers/android/index.test.ts:1056 "lists the same models as before other names were listed, for the same profiles"; src/drivers/android/index.test.ts:1078 "marks a model that comes only from devices.xml as custom, and no built-in model"; src/drivers/android/index.test.ts:1092 "lists the built-in models and no customModels field when devices.xml cannot be parsed"; src/drivers/android/index.test.ts:1107 "lists models with one avdmanager run"; src/drivers/android/index.test.ts:1173 "runs avdmanager list device once, with a 30 s limit, for two catalogs read while none of its…"; src/drivers/android/index.test.ts:1186 "runs avdmanager list device again after any file it reads device profiles from changed"; src/drivers/android/index.test.ts:1320 "runs avdmanager list device again after a read that failed"; src/drivers/android/index.test.ts:1338 "runs one avdmanager list device for two catalogs read at once"; src/drivers/android/index.test.ts:1386 "lists every installed system image with its API level, tag, and ABI, a foreign-ABI image inclu…"; src/drivers/android/index.test.ts:1409 "lists images by API level, then tag, then ABI, whatever order the disk returns them in"; src/drivers/android/index.test.ts:1438 "does not list a dot entry under system-images as a tag or an ABI"; src/drivers/android/index.test.ts:1452 "does not list an image that is not installed, even one sdkmanager offers"; src/drivers/android/index.test.ts:2060 "surfaces malformed devices.xml as a diagnostic and falls through to UnknownModelError, never t…"; src/drivers/android/index.test.ts:2143 "lists Pixel 9 first in the catalog, once, as phone, not custom, with pixel_9 as its other …"; src/drivers/android/index.test.ts:5446 "every library model resolves, and the catalog lists all 16 with their table classes, when avd…"; src/drivers/android/index.test.ts:5478"the catalog classes Medium Tablettabletwhenavdmanager list devicealso listsmedium_ta…"; src/drivers/android/index.test.ts:5720 "$name gives its After result"; src/drivers/android/index.test.ts:5745 "pairs My Tablet with 35 and 36 and not the TV image at 34, and the TV with 34 only"; src/drivers/android/index.test.ts:5770 "is not downloadable for an uninstalled level above the profile's API range"; src/drivers/android/index.test.ts:5785 "lists in modelRuntimes only levels with a fitting image, and every installed image elsewhere…"; src/drivers/android/index.test.ts:5803 "resolves every pair it lists, and refuses a level it leaves out"; src/drivers/android/index.test.ts:5832 "pairs a devices.xml profile avdmanager did not list with every installed phone level"; src/drivers/android/index.test.ts:5843 "counts android-Baklava with AndroidVersion.ApiLevel=35 as a level Pixel 9 pairs with"; src/drivers/android/index.test.ts:5855 "ranks a preview image by the API level it records, so a newer numeric level stays the newest…"; src/drivers/android/index.test.ts:5873 "ranks a preview image above the numeric levels when the level it records is higher"; src/drivers/android/index.test.ts:5882 "ranks a preview folder by the highest level any of its images records, so an image recording n…"; src/drivers/android/index.test.ts:5893 "ranks a preview folder by the highest level among its images, whichever is read first (%s)…"; src/drivers/android/index.test.ts:5909 "uses the folder name for --image-tag and the catalog's images[].tag when SystemImage.TagId dif…"; src/drivers/android/index.test.ts:5928 "gives a request with no version the newest level with a fitting image"; src/drivers/android/index.test.ts:5938 "fails a request with no version RUNTIME_MISSING, not downloadable, when no level has a fitting…"; src/drivers/android/index.test.ts:5948 "skips a newest level whose image of the tag misfits and takes the newest level where it fits…"; src/drivers/android/index.test.ts:5977 "names the API range for an API level below the profile's minimum"; src/drivers/android/index.test.ts:5985 "names the API range for a level above the profile's maximum"; src/drivers/android/index.test.ts:6001 "names the kind for %s with only phone images"; src/drivers/android/index.test.ts:6016 "names phone or tablet for a profile with no kind whose only image is a TV image"; src/drivers/android/index.test.ts:6024 "names the tag for any other kind"; src/drivers/android/index.test.ts:6032 "says the model does not take the kind of image it was given (%s)"; src/drivers/android/index.test.ts:6046 "says none of the installed images fit it when no single check rules out every image"; src/drivers/android/index.test.ts:6057 "gives the API range reason for an image that fails both API range and kind"; src/drivers/android/index.test.ts:6065 "drops the level from the message when no version was asked, reading every installed image"; src/drivers/android/index.test.ts:6073 "says an image tag's image does not fit it, and why"; src/drivers/android/index.test.ts:6084 "says the level is not installed for a level with nothing installed"; src/drivers/android/index.test.ts:6092 "says no system image is installed on a host with no image at all"; src/drivers/android/index.test.ts:6100 "keeps today's message for an image tag with no image of that tag installed"; src/drivers/android/index.test.ts:7293 "fails RUNTIME_MISSING, not downloadable, and starts no sdkmanager"; src/drivers/android/index.test.ts:8221 "a custom profile listed by avdmanager gets the API range of its devices.xml entry: api-level 3…"; src/drivers/android/index.test.ts:8246 "a custom profile with playstore-enabled false drops Play Store images"; src/drivers/android/index.test.ts:8264 "a custom Wear profile with playstore-enabled false keeps an image tagged android-wear,google_a…"; src/drivers/android/index.test.ts:8299 "a custom profile with no type and a 10.1-inch screen that does not fold fits tablet images; a …"; src/drivers/android/index.test.ts:8321 "a custom profile with nothing but a name pairs as after #489"; src/drivers/android/index.test.ts:8330 "a custom profile's class still comes from avdmanager's Tag line"; src/drivers/android/index.test.ts:8339 "a devices.xml profile avdmanager does not list fits by its own tag-id, range, Play Store flag …"; src/drivers/android/index.test.ts:8405 "reads devices.xml from ANDROID_USER_HOME, then ANDROID_PREFS_ROOT, then ANDROID_SDK_HOME, then…". Every other test stays where it is; F8's tests stay in src/drivers/android/index.test.ts and keep proving the root reaches the part.

  • The driver resolves specs and lists the catalog through catalog.ts, and gets the same profiles, fit verdicts and refusal messages as before; cases: "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.

Done when

  • pnpm exec vitest run --project unit src/drivers/android passes, and its number of tests is the base's plus the tests this task adds.
  • src/drivers/android/catalog.ts exists, and only files in src/drivers/android/ import it: dependency-cruiser's past-index rule (.dependency-cruiser.mjs:36-37), run by pnpm check, fails any import of it from outside the folder.
  • src/drivers/android/index.ts defines none of the F1 names, except each Driver method (and other AndroidDriver member 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.
  • pnpm check passes.

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.
  • New or stronger tests for code moved unchanged that no test pinned before: the apiLevel === requested filter in #taggedApiLevel, the resolved-profile cache write on the untagged path, the list device reported no built-in device profiles refusal, and the root's cannot resolve <platform> requests check. Two moved tests that SystemImages decides ("does not list a dot entry …", "does not list an image that is not installed …") stay in catalog.test.ts where this spec puts them. Tests: no new test for these; the root test that proves which options the root hands the part stays, since ADR 0063 §2 makes the root's wiring its own claim (decided in delivery, pending the maintainer)

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 4, 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 4, 2026
  3. self-assigned this
    on Nov 4, 2026
  4. added a commit that references this issue on Nov 4, 2026
    eadab6d
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