feat(explore): on-device natural-language search, phase 1 (core plus dives)

lib/core/accessibility/app_shortcuts.dart

@@ -1,10 +1,12 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter/widgets.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 
 import 'package:submersion/core/accessibility/shortcut_registry.dart';
 import 'package:submersion/core/accessibility/shortcuts_help_dialog.dart';
+import 'package:submersion/features/explore/presentation/providers/explore_gate_providers.dart';
 import 'package:submersion/features/divers/presentation/widgets/diver_switcher_sheet.dart';
 
 /// Creates a platform-appropriate shortcut activator.
@@ -97,6 +99,12 @@ class AppShortcuts {
         activator: platformShortcut(LogicalKeyboardKey.keyF),
         isGlobal: true,
       ),
+      ShortcutEntry(
+        label: 'Explore with a sentence',
+        category: 'Search',
+        activator: platformShortcut(LogicalKeyboardKey.keyE),
+        isGlobal: true,
+      ),
 
       // General
       const ShortcutEntry(
@@ -174,6 +182,13 @@ class AppShortcuts {
       platformShortcut(LogicalKeyboardKey.keyF): () {
         context.push('/dives/search');
       },
+      platformShortcut(LogicalKeyboardKey.keyE): () {
+        // The page is useless without a model, so the shortcut honours the
+        // same gate as the app bar action.
+        if (ProviderScope.containerOf(context).read(exploreEnabledProvider)) {
+          context.push('/dives/explore');
+        }
+      },
 
       // Settings
       platformShortcut(LogicalKeyboardKey.comma): () {

lib/core/accessibility/shortcut_display.dart

@@ -34,6 +34,8 @@ final Map<String, String Function(AppLocalizations)> _shortcutEntryLabels = {
   'Go to Settings': (l10n) => l10n.accessibility_shortcut_goToSettings,
   'Go back': (l10n) => l10n.accessibility_shortcut_goBack,
   'Search dives': (l10n) => l10n.accessibility_shortcut_searchDives,
+  'Explore with a sentence': (l10n) =>
+      l10n.accessibility_shortcut_exploreWithSentence,
   'Close / Cancel': (l10n) => l10n.accessibility_shortcut_closeCancel,
   'Open settings': (l10n) => l10n.accessibility_shortcut_openSettings,
   'Switch diver': (l10n) => l10n.accessibility_shortcut_switchDiver,

lib/core/database/local_cache_database.dart

@@ -271,6 +271,24 @@ class DecoClassificationCache extends Table {
   Set<Column> get primaryKey => {diveId};
 }
 
+/// The diver's last Explore sentences with the model's parse, so the field
+/// can offer them and a re-run skips the model. Local-only by construction:
+/// no HLC, never synced, never backed up; rows with an older schema version
+/// are dropped on read.
+class RecentQueries extends Table {
+  /// Normalized sentence plus locale, so a retyped sentence bumps its row.
+  TextColumn get key => text()();
+  TextColumn get sentence => text()();
+  TextColumn get locale => text()();
+  TextColumn get parsedJson => text()();
+  IntColumn get schemaVersion => integer()();
+  TextColumn get subject => text()();
+  IntColumn get lastUsedAt => integer()();
+
+  @override
+  Set<Column> get primaryKey => {key};
+}
+
 @DriftDatabase(
   tables: [
     LocalAssetCache,
@@ -284,13 +302,14 @@ class DecoClassificationCache extends Table {
     WatchedRoots,
     WatchedFolderIndex,
     DecoClassificationCache,
+    RecentQueries,
   ],
 )
 class LocalCacheDatabase extends _$LocalCacheDatabase {
   LocalCacheDatabase(super.e);
 
   @override
-  int get schemaVersion => 17;
+  int get schemaVersion => 18;
 
   @override
   MigrationStrategy get migration => MigrationStrategy(
@@ -454,6 +473,10 @@ class LocalCacheDatabase extends _$LocalCacheDatabase {
           );
         }
       }
+      // v18: Explore recent queries. Table-only rung, no backfill.
+      if (from < 18) {
+        await m.createTable(recentQueries);
+      }
     },
     beforeOpen: (details) async {
       // Ladder-collision self-heal: a parallel branch that also claimed v7
@@ -535,6 +558,19 @@ class LocalCacheDatabase extends _$LocalCacheDatabase {
           PRIMARY KEY (dive_id)
         )
       ''');
+      // v18 mirror, same collision self-heal as above.
+      await customStatement('''
+        CREATE TABLE IF NOT EXISTS recent_queries (
+          key TEXT NOT NULL,
+          sentence TEXT NOT NULL,
+          locale TEXT NOT NULL,
+          parsed_json TEXT NOT NULL,
+          schema_version INTEGER NOT NULL,
+          subject TEXT NOT NULL,
+          last_used_at INTEGER NOT NULL,
+          PRIMARY KEY (key)
+        )
+      ''');
       await customStatement('''
         CREATE TABLE IF NOT EXISTS swiss_bathy_tile_cache (
           tile_key TEXT NOT NULL,

lib/core/router/app_router.dart

@@ -50,6 +50,7 @@ import 'package:submersion/features/dive_3d/presentation/pages/compare_dives_3d_
 import 'package:submersion/features/dive_log/presentation/pages/bulk_dive_edit_page.dart';
 import 'package:submersion/features/dive_log/presentation/pages/dive_edit_page.dart';
 import 'package:submersion/features/dive_log/presentation/pages/dive_search_page.dart';
+import 'package:submersion/features/explore/presentation/pages/explore_page.dart';
 import 'package:submersion/features/dive_log/presentation/pages/profile_editor_page.dart';
 import 'package:submersion/features/dive_log/presentation/providers/profile_editor_provider.dart';
 import 'package:submersion/features/maps/presentation/pages/dive_activity_map_page.dart';
@@ -442,6 +443,11 @@ final appRouterProvider = Provider<GoRouter>((ref) {
                   filterDiveId: state.uri.queryParameters['dive'],
                 ),
               ),
+              GoRoute(
+                path: 'explore',
+                name: 'explore',
+                builder: (context, state) => const ExplorePage(),
+              ),
               GoRoute(
                 path: ':diveId',
                 name: 'diveDetail',

lib/features/dive_log/data/repositories/dive_repository_impl.dart

@@ -229,6 +229,18 @@ class DiveRepository {
       )
       .debounce(changeTickDebounce);
 
+  /// Change tick for a list filtered by species ([DiveFilterState.speciesIds]):
+  /// a sighting is written without a `dives` write, so the dives tick alone
+  /// would leave the list stale.
+  Stream<void> watchSightingsFilterChanges() => _db
+      .tableUpdates(
+        TableUpdateQuery.allOf([
+          TableUpdateQuery.onTable(_db.dives),
+          TableUpdateQuery.onTable(_db.sightings),
+        ]),
+      )
+      .debounce(changeTickDebounce);
+
   /// [watchDiveListChanges] plus the tables the buddy filters read
   /// ([DiveFilterState.readsBuddyLinks]), for a list filtered by buddy.
   /// See [_buddyLinkTables].
@@ -2551,6 +2563,13 @@ class DiveRepository {
       clauses.add('d.site_id = ?');
       args.add(Variable(filter.siteId!));
     }
+    if (filter.siteIds.isNotEmpty) {
+      final placeholders = List.filled(filter.siteIds.length, '?').join(', ');
+      clauses.add('d.site_id IN ($placeholders)');
+      for (final siteId in filter.siteIds) {
+        args.add(Variable(siteId));
+      }
+    }
     if (filter.tripId != null) {
       clauses.add('d.trip_id = ?');
       args.add(Variable(filter.tripId!));
@@ -2567,6 +2586,50 @@ class DiveRepository {
       clauses.add('d.max_depth <= ?');
       args.add(Variable(filter.maxDepth!));
     }
+    // Null excluded when a bound is set, in step with Statistics and apply().
+    if (filter.minWaterTemp != null) {
+      clauses.add('d.water_temp IS NOT NULL AND d.water_temp >= ?');
+      args.add(Variable(filter.minWaterTemp!));
+    }
+    if (filter.maxWaterTemp != null) {
+      clauses.add('d.water_temp IS NOT NULL AND d.water_temp <= ?');
+      args.add(Variable(filter.maxWaterTemp!));
+    }
+    if (filter.minVisibility != null) {
+      clauses.add(
+        'd.visibility_meters IS NOT NULL AND d.visibility_meters >= ?',
+      );
+      args.add(Variable(filter.minVisibility!));
+    }
+    if (filter.maxVisibility != null) {
+      clauses.add(
+        'd.visibility_meters IS NOT NULL AND d.visibility_meters <= ?',
+      );
+      args.add(Variable(filter.maxVisibility!));
+    }
+    if (filter.waterTypes.isNotEmpty) {
+      final placeholders = List.filled(
+        filter.waterTypes.length,
+        '?',
+      ).join(', ');
+      clauses.add('d.water_type IN ($placeholders)');
+      for (final w in filter.waterTypes) {
+        args.add(Variable(w.name));
+      }
+    }
+    if (filter.speciesIds.isNotEmpty) {
+      final placeholders = List.filled(
+        filter.speciesIds.length,
+        '?',
+      ).join(', ');
+      clauses.add(
+        'EXISTS (SELECT 1 FROM sightings sg '
+        'WHERE sg.dive_id = d.id AND sg.species_id IN ($placeholders))',
+      );
+      for (final speciesId in filter.speciesIds) {
+        args.add(Variable(speciesId));
+      }
+    }
     if (filter.favoritesOnly == true) {
       clauses.add('d.is_favorite = 1');
     }
@@ -2720,6 +2783,23 @@ class DiveRepository {
     }
   }
 
+  /// Distinct legacy free-text buddy names (`dives.buddy`), for name
+  /// matching. Names only, never a count.
+  // stats-scope-exempt: a name list, not an aggregate; an excluded dive's
+  // buddy is still a name the diver may type.
+  Future<List<String>> getDistinctLegacyBuddyNames({String? diverId}) async {
+    final diverFilter = diverId != null ? 'AND diver_id = ?' : '';
+    final rows = await _db
+        .customSelect(
+          'SELECT DISTINCT buddy FROM dives '
+          "WHERE buddy IS NOT NULL AND buddy <> '' $diverFilter "
+          'ORDER BY buddy',
+          variables: [if (diverId != null) Variable(diverId)],
+        )
+        .get();
+    return rows.map((r) => r.read<String>('buddy')).toList();
+  }
+
   // ============================================================================
   // Query Operations
   // ============================================================================