[Developer] #215 AI frame-suggest vertical slice (mock LlmService)

설계서대로 구현. flutter_gemma 실제 통합은 OQ-1 (모델 URL+SHA) 확정 후.
v1은 LlmService 추상 + ModelLifecycle (다운로드/SHA/purge) + Riverpod
providers + 다이얼로그 + Settings 화면까지. main.dart 가 MockLlmService 를
override 해 모든 경로가 graceful (suggest 결과는 빈 리스트).

추가:
- lib/data/ai/{llm_service,gemma_llm_service,model_lifecycle}.dart
- lib/domain/ai/{frame_candidate,few_shot_builder,parse_response,suggest_frame}.dart
- lib/state/ai_providers.dart (aiSettings + modelAvailability + frameSuggestions)
- lib/ui/screens/settings_screen.dart (opt-in 토글 + 모델 상태 표시)
- lib/ui/widgets/frame_suggestion_dialog.dart (후보 3개 카드 + 다시 시도)
- HabitCreateScreen: "AI 제안" 버튼 (opt-in + ready 일 때만 노출)
- MetaDao.remove(key) 추가 (purge 용)

테스트 31개 신규 추가 (총 62개 통과):
- test/domain/ai/{suggest_frame, few_shot_builder, parse_response}_test.dart
- test/data/ai/model_lifecycle_test.dart (download/SHA/purge/availability)

flutter analyze 0 issue, flutter build apk --debug 통과.

Refs #215

app/lib/data/ai/gemma_llm_service.dart

@@ -0,0 +1,45 @@
+import 'llm_service.dart';
+
+/// Stub for the real `flutter_gemma` integration.
+///
+/// Wired up only after OQ-1 (exact model URL + SHA + flutter_gemma API
+/// surface) is confirmed in Developer phase. Today this throws
+/// `UnimplementedError` from every method — the rest of the system
+/// (suggestFrame, ModelLifecycle, Riverpod providers) is built against the
+/// `LlmService` abstract above and runs end-to-end with `MockLlmService`.
+///
+/// When the package is added, replace the bodies with calls into
+/// FlutterGemma.init / generateWithFunctionCalling per the package docs.
+/// Existing tests + UI hooks remain unchanged.
+class GemmaLlmService implements LlmService {
+  final String modelPath;
+
+  GemmaLlmService({required this.modelPath});
+
+  bool _loaded = false;
+
+  @override
+  bool get isLoaded => _loaded;
+
+  @override
+  Future<void> load() async {
+    throw UnimplementedError(
+      'GemmaLlmService.load: pending OQ-1 (model URL + flutter_gemma).',
+    );
+  }
+
+  @override
+  Future<void> unload() async {
+    _loaded = false;
+  }
+
+  @override
+  Future<Map<String, dynamic>> generateStructured(
+    String prompt,
+    Map<String, dynamic> schema,
+  ) async {
+    throw UnimplementedError(
+      'GemmaLlmService.generateStructured: pending OQ-1.',
+    );
+  }
+}

app/lib/data/ai/llm_service.dart

@@ -0,0 +1,84 @@
+/// Abstract LLM backend.
+///
+/// Concrete impls: `GemmaLlmService` (flutter_gemma) and `MockLlmService` (tests).
+/// Contract:
+/// - After [load], [isLoaded] is true.
+/// - [generateStructured] throws [StateError] when not loaded.
+/// - [generateStructured] returns a parsed JSON map matching the schema.
+///   On schema/parse failure throws [FormatException].
+/// - [unload] is idempotent.
+abstract class LlmService {
+  bool get isLoaded;
+
+  Future<void> load();
+
+  Future<void> unload();
+
+  /// Calls the model with a function-calling [schema] and returns the parsed
+  /// JSON arguments map. Caller is responsible for applying `.timeout(...)`.
+  Future<Map<String, dynamic>> generateStructured(
+    String prompt,
+    Map<String, dynamic> schema,
+  );
+}
+
+/// Programmable stub for tests. Use [enqueueResponse] / [enqueueError].
+class MockLlmService implements LlmService {
+  final List<_Response> _queue = [];
+  bool _loaded = false;
+  int callCount = 0;
+  String? lastPrompt;
+  Map<String, dynamic>? lastSchema;
+  Duration responseDelay = Duration.zero;
+
+  @override
+  bool get isLoaded => _loaded;
+
+  @override
+  Future<void> load() async {
+    _loaded = true;
+  }
+
+  @override
+  Future<void> unload() async {
+    _loaded = false;
+  }
+
+  void enqueueResponse(Map<String, dynamic> response) {
+    _queue.add(_Response.value(response));
+  }
+
+  void enqueueError(Object error) {
+    _queue.add(_Response.error(error));
+  }
+
+  @override
+  Future<Map<String, dynamic>> generateStructured(
+    String prompt,
+    Map<String, dynamic> schema,
+  ) async {
+    callCount += 1;
+    lastPrompt = prompt;
+    lastSchema = schema;
+    if (!_loaded) {
+      throw StateError('LlmService not loaded');
+    }
+    if (responseDelay > Duration.zero) {
+      await Future<void>.delayed(responseDelay);
+    }
+    if (_queue.isEmpty) {
+      throw StateError('MockLlmService: no queued response');
+    }
+    final r = _queue.removeAt(0);
+    if (r.error != null) throw r.error!;
+    return r.value!;
+  }
+}
+
+class _Response {
+  final Map<String, dynamic>? value;
+  final Object? error;
+  const _Response._(this.value, this.error);
+  factory _Response.value(Map<String, dynamic> v) => _Response._(v, null);
+  factory _Response.error(Object e) => _Response._(null, e);
+}

app/lib/data/ai/model_lifecycle.dart

@@ -0,0 +1,262 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:crypto/crypto.dart';
+import 'package:http/http.dart' as http;
+import 'package:path/path.dart' as p;
+import 'package:path_provider/path_provider.dart';
+
+import '../db/daos/meta_dao.dart';
+
+/// meta_kv keys (#215 README §6).
+class AiMetaKeys {
+  static const optIn = 'ai_opt_in';
+  static const modelPath = 'ai_model_path';
+  static const modelSha = 'ai_model_sha256';
+  static const downloadState = 'ai_download_state';
+  static const downloadBytes = 'ai_download_bytes';
+
+  static const all = <String>[
+    optIn,
+    modelPath,
+    modelSha,
+    downloadState,
+    downloadBytes,
+  ];
+}
+
+enum ModelAvailability { ready, missing, corrupt, downloading }
+
+enum DownloadState { idle, downloading, paused, completed, failed }
+
+class DownloadProgress {
+  final int bytesReceived;
+  final int totalBytes; // -1 if unknown
+  final DownloadState state;
+  final String? errorMessage;
+  const DownloadProgress({
+    required this.bytesReceived,
+    required this.totalBytes,
+    required this.state,
+    this.errorMessage,
+  });
+}
+
+/// File-system / HTTP abstraction so tests can inject a fake.
+abstract class StorageAdapter {
+  Future<Directory> supportDir();
+  Future<http.StreamedResponse> rangeGet(Uri url, int from);
+}
+
+class _ProdStorage implements StorageAdapter {
+  final http.Client client;
+  _ProdStorage(this.client);
+  @override
+  Future<Directory> supportDir() => getApplicationSupportDirectory();
+  @override
+  Future<http.StreamedResponse> rangeGet(Uri url, int from) async {
+    final req = http.Request('GET', url);
+    if (from > 0) req.headers['Range'] = 'bytes=$from-';
+    return client.send(req);
+  }
+}
+
+/// Default config for the Gemma 4 E2B Q4_0 model. OQ-1: real URL + SHA
+/// to be pinned in Developer phase after `flutter_gemma` docs review.
+class ModelConfig {
+  final Uri url;
+  final String expectedSha256;
+  final String filename;
+  const ModelConfig({
+    required this.url,
+    required this.expectedSha256,
+    this.filename = 'gemma4_e2b_q4.bin',
+  });
+}
+
+/// Owns the model file: download (resumable) → SHA-256 verify → availability
+/// query → purge. All paths graceful: on failure surfaces as `corrupt` /
+/// `failed` rather than throwing through the call chain.
+class ModelLifecycle {
+  final MetaDao meta;
+  final ModelConfig config;
+  final StorageAdapter _storage;
+
+  ModelLifecycle({
+    required this.meta,
+    required this.config,
+    StorageAdapter? storage,
+    http.Client? httpClient,
+  }) : _storage = storage ?? _ProdStorage(httpClient ?? http.Client());
+
+  Future<String> _modelPath() async {
+    final dir = await _storage.supportDir();
+    return p.join(dir.path, config.filename);
+  }
+
+  Future<ModelAvailability> checkAvailability() async {
+    try {
+      final optIn = await meta.find(AiMetaKeys.optIn);
+      if (optIn != 'true') return ModelAvailability.missing;
+
+      final state = await meta.find(AiMetaKeys.downloadState);
+      if (state == 'downloading' || state == 'paused') {
+        return ModelAvailability.downloading;
+      }
+
+      final pathStr = await meta.find(AiMetaKeys.modelPath);
+      if (pathStr == null) return ModelAvailability.missing;
+
+      final file = File(pathStr);
+      if (!file.existsSync()) return ModelAvailability.missing;
+
+      final expected = await meta.find(AiMetaKeys.modelSha);
+      if (expected == null) return ModelAvailability.corrupt;
+
+      final actual = await _hashFile(file);
+      if (actual != expected) return ModelAvailability.corrupt;
+
+      return ModelAvailability.ready;
+    } catch (_) {
+      return ModelAvailability.corrupt;
+    }
+  }
+
+  Future<String> _hashFile(File file) async {
+    final digest = await sha256.bind(file.openRead()).first;
+    return digest.toString();
+  }
+
+  /// Streams resumable download progress. Mutates `meta_kv` as it goes.
+  /// Errors are emitted as `DownloadProgress(state: failed)` rather than
+  /// thrown — UI listens to the stream.
+  Stream<DownloadProgress> download() async* {
+    final path = await _modelPath();
+    final tempPath = '$path.tmp';
+    final tempFile = File(tempPath);
+    int existing =
+        tempFile.existsSync() ? await tempFile.length() : 0;
+
+    await meta.put(AiMetaKeys.downloadState, 'downloading');
+    await meta.put(AiMetaKeys.downloadBytes, existing.toString());
+    yield DownloadProgress(
+      bytesReceived: existing,
+      totalBytes: -1,
+      state: DownloadState.downloading,
+    );
+
+    http.StreamedResponse response;
+    try {
+      response = await _storage.rangeGet(config.url, existing);
+    } catch (e) {
+      await meta.put(AiMetaKeys.downloadState, 'paused');
+      yield DownloadProgress(
+        bytesReceived: existing,
+        totalBytes: -1,
+        state: DownloadState.failed,
+        errorMessage: 'network: $e',
+      );
+      return;
+    }
+
+    final status = response.statusCode;
+    if (status != 200 && status != 206) {
+      // 416 etc. — restart from 0.
+      if (tempFile.existsSync()) await tempFile.delete();
+      existing = 0;
+      await meta.put(AiMetaKeys.downloadBytes, '0');
+      yield DownloadProgress(
+        bytesReceived: 0,
+        totalBytes: -1,
+        state: DownloadState.failed,
+        errorMessage: 'http $status',
+      );
+      return;
+    }
+
+    final contentLength = response.contentLength ?? 0;
+    final total = status == 206 ? existing + contentLength : contentLength;
+    final sink = tempFile.openWrite(mode: FileMode.append);
+    int received = existing;
+
+    try {
+      await for (final chunk in response.stream) {
+        sink.add(chunk);
+        received += chunk.length;
+        await meta.put(AiMetaKeys.downloadBytes, received.toString());
+        yield DownloadProgress(
+          bytesReceived: received,
+          totalBytes: total,
+          state: DownloadState.downloading,
+        );
+      }
+      await sink.flush();
+      await sink.close();
+    } catch (e) {
+      await sink.close();
+      await meta.put(AiMetaKeys.downloadState, 'paused');
+      yield DownloadProgress(
+        bytesReceived: received,
+        totalBytes: total,
+        state: DownloadState.failed,
+        errorMessage: 'stream: $e',
+      );
+      return;
+    }
+
+    // Verify SHA-256.
+    final finalFile = File(path);
+    await tempFile.rename(path);
+    final sha = await _hashFile(finalFile);
+    if (sha != config.expectedSha256) {
+      await finalFile.delete();
+      await meta.put(AiMetaKeys.downloadState, 'failed');
+      yield DownloadProgress(
+        bytesReceived: received,
+        totalBytes: total,
+        state: DownloadState.failed,
+        errorMessage: 'sha mismatch',
+      );
+      return;
+    }
+
+    await meta.put(AiMetaKeys.modelPath, path);
+    await meta.put(AiMetaKeys.modelSha, sha);
+    await meta.put(AiMetaKeys.downloadState, 'completed');
+    yield DownloadProgress(
+      bytesReceived: received,
+      totalBytes: total,
+      state: DownloadState.completed,
+    );
+  }
+
+  /// opt-out: delete model file + clear all ai_* meta keys (except opt_in
+  /// which the caller toggles). Returns freed bytes (0 if nothing existed).
+  /// Idempotent.
+  Future<int> purge() async {
+    int freed = 0;
+    final pathStr = await meta.find(AiMetaKeys.modelPath);
+    if (pathStr != null) {
+      final f = File(pathStr);
+      if (f.existsSync()) {
+        freed += await f.length();
+        await f.delete();
+      }
+    }
+    final tempPath = '${await _modelPath()}.tmp';
+    final temp = File(tempPath);
+    if (temp.existsSync()) {
+      freed += await temp.length();
+      await temp.delete();
+    }
+    for (final k in [
+      AiMetaKeys.modelPath,
+      AiMetaKeys.modelSha,
+      AiMetaKeys.downloadState,
+      AiMetaKeys.downloadBytes,
+    ]) {
+      await meta.remove(k);
+    }
+    return freed;
+  }
+}