zapstore/spec/features/FEAT-004-asset-first-queries.md

# FEAT-004 — Asset-First Query Optimization

## Goal

Speed up app listing screens by querying SoftwareAsset (kind 3063) first,
resolving the App (32267) via its direct relationship, and skipping the
intermediate Release (30063) for card-level display.

## Non-Goals

- Removing Release from the data model or detail screen
- Changing the models package
- Migrating all screens at once (phased rollout starting with Latest Releases)

## User-Visible Behavior

- App cards on the home screen load faster (2 hops instead of 4)
- No change to what the user sees: same name, icon, version pill, description
- Legacy 1063-only apps still appear, loaded via a separate fallback query
- Offline: local-first behavior unchanged — cached assets and apps render immediately

## Edge Cases

- App has only legacy FileMetadata (1063), no SoftwareAsset (3063) → fallback query picks it up (when `includeLegacy: true`; Latest Releases skips these)
- App has both 3063 and 1063 → 3063 wins (already the existing preference)
- SoftwareAsset exists but its App relationship fails to resolve → card skipped, no crash
- Network failure → local cache used, graceful degradation unchanged

## Acceptance Criteria

- [ ] `latestFileMetadata` renamed to `latestAsset` across codebase, with 3063→1063 fallback
- [ ] Centralized query helper with `includeLegacy` flag, reusable across screens
- [ ] LatestReleasesNotifier uses centralized query (3063-only, no legacy fallback)
- [ ] VersionPillWidget reads locally instead of re-fetching the full chain from remote
- [ ] `flutter analyze` clean
- [ ] Legacy 1063-only apps still appear in listings

## Notes

- The detail screen continues using Release for release notes, commit info, etc.
  Release is loaded via `latestRelease` relationship when needed, not as part of the card query.
- When legacy 1063 is fully removed, the fallback query function is deleted — single removal point.