[Feature]: Out-of-band auto-scorer model updates without a full Play release

[mathrb]

Problem / use case

The auto-scorer (camera assist, beta) ships its detection model bundled as an
app asset (assets/models/dart_auto_scorer.tflite, pinned via
kAutoScorerModelVersion). Today, improving only the model — no code change —
still requires a full app release and Google Play review. The review cycle is
slow and disproportionate for a payload that is data, not behaviour.

We want a way to ship an improved detection model to users out-of-band,
without going through a new Play release and its review, the way games stream
updated assets at launch.

Proposed solution

Scope a mechanism that lets the app fetch a newer auto-scorer model at runtime
and use it in place of the bundled one, while remaining safe and Play-compliant.

Goals / constraints to design around:

• A model swap must only take effect when it is compatible with the code the
  installed app already runs (input size, class map, preprocessing, threshold
  semantics). The currently-bundled model stays the fallback.
• Must degrade gracefully: offline, failed download, or any integrity failure →
  keep using the bundled model, never break scoring.
• No change to what user data leaves the device (the download is an outbound
  fetch of a data file; frame capture stays local and gated).

Alternatives considered

• Google "Play for On-device AI" (AI packs) — Google-hosted, free, with
  differential patching, BUT AI packs are still versioned together with the app
  binary, so they do not avoid a release/review for a model-only change.
  Reduces download size, not the review cycle. Rejected for the stated goal.
• Status quo (bundle + full release per model) — what we do now; the cost
  this ticket exists to remove.

Scope notes

• No persistence / game-events / statistics impact.
• Touches the auto-scorer detector loading path and app startup; needs network
  (INTERNET) — verify it's already in the merged manifest.
• Compliance angle is already researched (see context): a .tflite is data,
  not executable code, so a runtime model download is permitted under Google
  Play's Device and Network Abuse policy; no Data safety / privacy-policy change
  as long as no user data is uploaded.

Before implementation

Do not treat any architecture as decided. Re-derive the design from current
code via /plan first, answering at least:

• Where/how the model is loaded today and where a remote source would slot in.
• How to express and enforce the compatibility contract between a remote model
  and the installed app version (so an incompatible model is ignored, not run).
• Integrity / authenticity of the downloaded file, and the fallback chain.
• Hosting choice and its operational cost (versioning, bandwidth, availability).
• When this canal is not enough and a real release is still required (contract
  changes: classes, input resolution, preprocessing).

Additional context

Compliance research (2026-06-27):

• Device and Network Abuse — Play Console Help
• Dynamic Code Loading — Android Developers (Security)
• Play for On-device AI — Android Developers

Feature is and stays beta (model still experimental).

[mathrb]

Design — Out-of-band auto-scorer model updates

Scoped design for #715. Lets the app fetch an improved detection model at
runtime and use it in place of the bundled one, without a Play release/review,
while staying safe and Play-compliant. Feature stays beta.

Current state (derived from code)

• The model is loaded via YOLOView(modelPath: kAutoScorerModelAsset, …) (two
  call sites in auto_scorer_yolo_view_io.dart) and YOLO(modelPath:) in
  yolo_detector_io.dart, all pinned to the const asset
  assets/models/dart_auto_scorer.tflite.
• ultralytics_yolo 0.6.5 accepts an absolute file path as modelPath (its
  doc cites /data/user/0/…/files/custom.tflite). A runtime swap needs no native
  change — only resolving the effective path at detector-mount time.
• path_provider is available. No dio/http, no crypto, no
  connectivity_plus today.
• INTERNET is already merged into the release manifest via
  sentry_flutter / share_plus / package_info_plus. No post-create-android.sh
  change needed.
• The model "contract" (input 800×800, class map {0:dart, 1:cal1..4},
  preprocessing, threshold semantics) lives as code-side constants.

1. Hosting — mathrb/dartlodge (public app repo)

deep-darts-probe stays private. The .tflite already ships inside the
public app, so exposing it as a release asset leaks nothing new.

• Binaries → GitHub Releases of mathrb/dartlodge, under a dedicated
  tag prefix (e.g. model-round26) distinct from app-version tags (v1.x).
  ⚠️ Operational guard to verify at implementation: the existing tag-driven
  release.yml (APK/AAB build) must not trigger on model-* tags.
• Manifest (tiny) → committed on main at model_manifest.json, read via
  raw.githubusercontent.com/mathrb/dartlodge/main/model_manifest.json, updated
  per model publication. The binary is never committed (10 MB × versions would
  bloat git history) — that is what releases are for.
• Publishing flow (only link to the private probe): train/export in
  deep-darts-probe → create a model-* release on dartlodge with the
  .tflite + its SHA-256 → update model_manifest.json. Publishing script lives
  in the probe repo (out of scope here, same boundary as Auto-scorer: reach the recall gate + close the data-collection loop #393).

2. Manifest format (stable URL → points at the latest release asset)

{
  "schema": 1,
  "contract": 1,
  "modelVersion": "dart_round26_withcal",
  "url": "https://github.com/mathrb/dartlodge/releases/download/model-round26/dart_auto_scorer.tflite",
  "sha256": "<hex>",
  "sizeBytes": 10727799,
  "inputSize": 800,
  "classCount": 5
}

The app reads the stable manifest URL (updated each publication); the binary
URL is a versioned release asset. This decouples "where is the latest" from
the versioned assets.

3. Compatibility contract

• New const kAutoScorerModelContract = 1 in dart_detector.dart (next to the
  version).
• Primary gate: manifest.contract == kAutoScorerModelContract (strict
  equality).
• Secondary sanity gate (defense-in-depth): manifest.inputSize == 800 && manifest.classCount == 5; reject + log on mismatch.
• Release boundary: bump kAutoScorerModelContract whenever classes /
  input-size / preprocessing / threshold semantics change → old apps ignore the
  new-contract model → a real Play release becomes necessary for those users.
  Documented in assets/models/README.md.

4. Integrity & authenticity

• SHA-256 of downloaded bytes == manifest.sha256, plus a sizeBytes check.
• Manifest and binary served over HTTPS from the pinned GitHub host.
• No binary signature: proportionate for beta data — a .tflite is data
  interpreted by the plugin, not executable code; worst case of a hash-matching
  malicious file is bad detections, not RCE (compliance already settled in the
  ticket).

5. Runtime resolution & fallback chain

Effective model resolved at YOLOView / YOLO mount time:

staged download valid (contract OK + integrity OK + file present)
   → else → bundled asset   (never deleted — ultimate fallback)

• Any failure at any step (offline, download error, hash mismatch, contract
  mismatch, corrupt file) → keep the bundled model. Scoring never breaks.
• If a staged model fails to load natively (YOLOView.onModelError, exposed
  by the plugin) → quarantine it (delete) and fall back to bundled, so a
  bad-but-hash-valid model cannot brick scoring permanently.
• The resolved modelVersion (bundled or downloaded) is threaded into captures /
  the session (auto_scorer_board_overlay.dart:179) so downloaded-model captures
  attribute correctly.

6. Update lifecycle

• Trigger: automatic background check at launch when the auto-scorer is
  enabled; download + staging are silent.
• Network policy: download only on an unmetered connection
  (connectivity_plus).
• Apply timing: the new model takes effect at the next detector mount /
  next session — never a hot swap mid-game.
• State persisted in shared_preferences: staged model version, contract,
  sha. Re-check is a no-op when manifest.modelVersion equals the staged (or
  bundled) version.

7. Architecture (feature auto_scorer, mobile-io only; web = no-op stub)

• domain/: AutoScorerModelManifest (freezed) + ResolvedModel (path +
  version + origin bundled/downloaded) + pure gate/selection logic.
• data/ (io): ModelUpdateService — fetch manifest → gate → connectivity →
  download to temp → verify hash/size → atomic move into
  getApplicationSupportDirectory()/models/. HTTP via dart:io HttpClient
  (no HTTP dep; follows GitHub→CDN redirects; feature is io-only). Web stub
  no-op returning bundled. Downloader / connectivity / fs injected behind
  abstractions for testability.
• presentation/: a provider resolves effective modelPath + modelVersion;
  the two YOLOView call sites, yolo_detector_io.dart, and the capture
  modelVersion read the resolved value. A startup hook kicks off the background
  check.

8. New dependencies (minimal)

• crypto — SHA-256 (official Dart package, tiny).
• connectivity_plus — unmetered/wifi detection.
• HTTP: none (dart:io HttpClient).

9. Settings & i18n

Status row in auto-scorer settings: active model version + state ("up to date" /
"downloading…" / "update ready on next launch") + a "Check now" button. i18n keys
across the 7 locales.

10. Testing

Pure and complete on: manifest parsing, compatibility gate (contract
match/mismatch, inputSize/classCount sanity, schema version), integrity
verification (known bytes/hash), resolver selection (staged valid → path;
contract mismatch → bundled; absent/missing file → bundled). The io service
injects downloader + connectivity + fs behind abstractions → tested with fakes;
only the thin dart:io edge stays untested (as with other native paths, which
are not widget-testable).

11. Out of scope

• Model publishing script (create release, compute SHA-256, update
  model_manifest.json) → lives in deep-darts-probe (private), same boundary
  as Auto-scorer: reach the recall gate + close the data-collection loop #393.

12. Operational items to verify at implementation

• release.yml does not trigger on model-* tags.
• connectivity_plus unmetered semantics on the target Android versions
  (minSdk 23).