0102. The device effects ask for no more than they use, and the build says what a phone would refuse
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-15
- Decided by: wave 5 implementer, domain B (internal only)
- Planning item: WP11 (platform effects), review of pull request #31
Context
The review of the eighteen device effects (decision 0101) found that some asked for more than they used, some could crash or hang iOS, and some mistakes that are plain in the page's text reached the phone:
- Contacts took Android's
READ_CONTACTS, the whole address book, to read the one contact the user picked, while its usage text said "nothing else". - The calendar took
READ_CALENDARandWRITE_CALENDARon Android, and write access on iOS 17, to add one event. permissions.request("microphone")in an app that imports onlypermissionsstops the app on iOS (no usage description), and a location request without one is never answered.- Android let a page read the clipboard at any moment, with no press.
- A mock, such as
mockBiometrics, could ship in a store build and pass every check. - What the recorder recorded and the picker copied stayed in the app's cache for ever.
The owner's rule is that anything statically knowable fails the build loudly, and that on a phone every feature works or is refused with an error code.
Decision
Contacts are picked for a phone number or an email address. The contract's pick takes { wants: "phone" | "email" }, default "phone". Android opens its picker for that content type, which hands over the one row the user taps with a grant for that row only, so no permission is declared or asked. iOS's picker shows the person's numbers or addresses and hands over the one tapped. The web's Contact Picker hands over all of the person's. The list not asked for is always empty, on every target. The contacts declaration stays, for an app that asks for the permission itself, with a usage text that says what that access is.
The calendar uses the calendar's own editor. Android opens it with ACTION_INSERT, which needs no permission: the outcome is "handed-off", as on the web. iOS 17 and later show EventKitUI's editor, which runs outside the app: "added" when the user saves, and a new outcome, "cancelled", when they close it. Before iOS 17 that editor needs full access, so there the event is still saved directly after the "calendar" permission. The effect declares only NSCalendarsUsageDescription (iOS 13 to 16); a new calendar_access declaration carries the Android permissions and the iOS 17 key for an app that asks for the permission itself.
A reason declares a permission, and an undeclared request fails the build (E0431). A reason in permissions.yaml now also writes its declaration, so an app can ask for a permission no effect it imports uses. The catalogue lists, for each permission name, the declarations that let a phone ask for it. A permissions.request whose name the page's text gives (as text, or in a const) must be declared by an imported effect or a reason, or the build fails. On the phone, a request whose usage description is missing anyway answers "unavailable" before anything is asked, on iOS as on Android.
The build reads addresses and names as far as the text goes. E0420 now also covers a const holding the address, a template or + whose start is written (only http:// and https:// can start a web address), and browser.open under another name (const { open } = browser). A name bound twice in the script is not read, so the check never guesses.
Android reads the clipboard only right after the user acts. The shell's activity notes each press and key; reading within five seconds of one works, as a browser allows, and otherwise fails with E0422.
A native build refuses a mock (E0432). Each mock is marked mock: true in the catalogue. A web build keeps them, for trying an app in a desktop browser; a native build, which is what reaches the stores, fails at the import. The device-effects example no longer swaps its effects for mocks in the app itself.
Recordings and picked files last while the app runs. The folders they are made in are emptied, of an earlier run's files only, when the app next starts.
Consequences
contacts.pick()with no options now gives the phone numbers only. An app that wanted the email addresses passes{ wants: "email" }.CalendarOutcomegains"cancelled", which aswitchover it must handle.- An app that asked for a permission no effect declares, without a reason, no longer builds. The fix the error gives is one line of
permissions.yaml. - An app that used a mock in its pages builds for the web but not for native.
- Recordings and picked files must be uploaded or copied elsewhere during the run in which they were made.
Alternatives considered
- **Keep
READ_CONTACTSand say so in the usage text.** Honest, but Play's policy and the user both ask why a picker needs the address book. - Refuse mocks in every build. The web build is how an app is tried on a desktop with no sensors; only a store build must not pretend.
- Ask for the permission's usage description at run time only. It would stop the crash, but the build already knows, and the owner's rule is that it says so.