Skip to content

ADR-MOB-006 — Models are downloaded, verified and user-owned; never bundled, never silent

Status: Accepted (2026-08-07) · design only, no code yet Deciders: Mohsen Seyedkazemi Ardebili Context links: [[adr-mob-005]] (engines), [[adr-mob-007]] (privacy/permissions), [[adr-mob-009]] (distribution), [[adr-011]] (offline default, open weights)

Context

A dictation app is useless without weights and the weights are 40–500 MB. Four facts fix the design:

  • Play imposes a base APK/AAB size limit far below a bundled small.en, and F-Droid's main repo does not want large opaque binary blobs in-tree.
  • The user must be able to choose a model — tiny.en on an old phone, small.en on a flagship, a multilingual model for a non-English user — so a single bundled model is wrong even when it fits.
  • The download is the only time the app touches the network, and that single fact is the most important thing to be honest about, because the whole product claim is "offline".
  • Users who never want the app to touch the network at all (air-gapped, high-threat, or simply not trusting the claim) must have a supported path.

Decision

  1. No model weights ship inside the APK. The APK contains code and a signed catalogue of models (id, display name, engine, size, SHA-256, licence, source URL).
  2. First-run model chooser. Onboarding shows the catalogue with size, expected device-class suitability and licence, and asks the user to pick. Nothing is downloaded before an explicit tap. The screen states, verbatim in spirit: this is the only network request YazSes ever makes; after it completes you can disable network access for this app entirely and dictation will keep working.
  3. Download is a WorkManager job in :model, the single module with the INTERNET permission ([[adr-mob-007]]). Requirements: resumable, cancellable, Wi-Fi-only by default, HTTPS only (cleartextTrafficPermitted=false), SHA-256 verified against the in-APK catalogue before the file is made visible, atomic rename into place, and a readable failure state. A checksum mismatch deletes the file and reports it loudly — a corrupted or substituted model is a security event, not a retry.
  4. Sideload path, first-class and documented: the user may import a model file from local storage (SAF) or adb push it, and the app verifies it against the catalogue checksum when the model is known, or accepts it with an explicit "unverified, you supplied this" marker when it is not. The app is fully functional with network access permanently denied, and this is covered by an automated test, not just a claim.
  5. Models are stored in app-private storage (filesDir/noBackupFilesDir), excluded from cloud backup (android:allowBackup handling and backup rules), and listed in a Storage screen that shows size and offers deletion. Removing YazSes removes the weights.
  6. Open weights only, licence shown before download ([[adr-011]] §5). Each catalogue entry carries its licence and its upstream URL, and the download screen shows both.
  7. The catalogue is versioned in-repo (android/app/src/main/assets/models.json), so a model addition is a reviewable PR with a checksum in the diff — not a server-side change. There is no remote catalogue endpoint: the app never asks a YazSes-operated server anything, because there is no YazSes-operated server ([[adr-011]] §1).
  8. A quantisation/size matrix per engine is maintained from :bench device reports rather than asserted; the chooser's "recommended for your device" hint is derived from RAM and SoC class and is presented as a hint, with all options selectable.

Consequences

  • The APK stays small (single-digit MB plus native libs), which helps Play, F-Droid and users on metered connections.
  • First run has a real cost (a several-hundred-MB download) that must be communicated before it starts, including on mobile data.
  • Model files are user-visible and deletable, so "how much space is this taking" has an in-app answer — a common uninstall trigger removed.
  • Hosting is upstream (e.g. the model publisher's repository) rather than a YazSes CDN. Upstream URLs rot; the catalogue therefore needs a maintenance obligation and a mirror policy, and a broken URL must produce a clear error with a sideload suggestion, never a hang. This is a named risk with an owner.
  • Because the checksum is in the APK and the APK is signed, a compromised mirror cannot substitute weights — a genuinely meaningful supply-chain property for an app whose whole point is trust.

Rejected

  • Bundling tiny.en "so it works immediately". Tempting for onboarding, but it sets the accuracy expectation at the worst model the project can ship, adds ~75 MB to every install including for users who will immediately download something better, and starts an argument with F-Droid about in-tree blobs. Revisit only if onboarding drop-off data (from user reports, not telemetry — [[adr-011]] §1) shows it is the deciding factor.
  • A play-asset-delivery / dynamic-feature module for weights. Ties the mechanism to Play; F-Droid and GitHub APKs would need the download path anyway, so this would mean two mechanisms instead of one.
  • A YazSes-operated model server or catalogue endpoint. Creates the exact telemetry surface [[adr-011]] forbids (download logs are usage data), plus an operating cost and a single point of failure.
  • Downloading silently in the background on first launch. Violates the spirit of the offline claim, surprises metered-connection users, and would make the network permission feel like a lie.