gaia-framework 1.57.0 → 1.57.2

package/_gaia/dev/knowledge/angular/rxjs-patterns.md

@@ -1,119 +0,0 @@
----
-name: RxJS Observable Patterns
-stack: angular
-version: "1.0"
-focus: [rxjs]
----
-
-# RxJS Observable Patterns
-
-## Principle
-
-Use RxJS observables as the primary mechanism for managing asynchronous data flows. Choose operators deliberately based on the concurrency semantics required (switch, merge, concat, exhaust). Always manage subscription lifecycle to prevent memory leaks.
-
-## Rationale
-
-RxJS provides a composable, declarative approach to async operations. Choosing the right flattening operator prevents subtle bugs: `switchMap` cancels prior requests (ideal for search), `concatMap` queues them (ideal for ordered writes), `mergeMap` runs concurrently, and `exhaustMap` ignores new emissions while one is active (ideal for form submissions). Proper subscription management is critical because Angular components are created and destroyed frequently.
-
-## Pattern Examples
-
-### Pattern 1: Type-Ahead Search with switchMap
-
-```typescript
-@Component({ /* ... */ })
-export class SearchComponent implements OnInit, OnDestroy {
-  searchControl = new FormControl('');
-  results$!: Observable<SearchResult[]>;
-  private destroy$ = new Subject<void>();
-
-  constructor(private searchService: SearchService) {}
-
-  ngOnInit(): void {
-    this.results$ = this.searchControl.valueChanges.pipe(
-      debounceTime(300),
-      distinctUntilChanged(),
-      filter((term): term is string => term !== null && term.length >= 2),
-      switchMap(term => this.searchService.search(term).pipe(
-        catchError(() => of([]))  // Recover per-request, not globally
-      )),
-      takeUntil(this.destroy$)
-    );
-  }
-
-  ngOnDestroy(): void {
-    this.destroy$.next();
-    this.destroy$.complete();
-  }
-}
-```
-
-### Pattern 2: Combining Multiple Streams
-
-```typescript
-export class DashboardComponent implements OnInit {
-  vm$!: Observable<DashboardViewModel>;
-
-  ngOnInit(): void {
-    this.vm$ = combineLatest([
-      this.store.select(selectUser),
-      this.store.select(selectNotifications),
-      this.store.select(selectMetrics),
-    ]).pipe(
-      map(([user, notifications, metrics]) => ({
-        user,
-        notifications,
-        metrics,
-        hasUnread: notifications.some(n => !n.read),
-      }))
-    );
-  }
-}
-
-// Template: single async pipe, one subscription
-// <ng-container *ngIf="vm$ | async as vm">
-//   <app-header [user]="vm.user" [unread]="vm.hasUnread" />
-//   <app-metrics [data]="vm.metrics" />
-// </ng-container>
-```
-
-### Pattern 3: Retry with Exponential Backoff
-
-```typescript
-export function retryWithBackoff<T>(
-  maxRetries = 3,
-  delayMs = 1000
-): MonoTypeOperatorFunction<T> {
-  return (source: Observable<T>) =>
-    source.pipe(
-      retry({
-        count: maxRetries,
-        delay: (error, retryCount) => {
-          const backoff = delayMs * Math.pow(2, retryCount - 1);
-          console.warn(`Retry #${retryCount} in ${backoff}ms`, error.message);
-          return timer(backoff);
-        },
-      })
-    );
-}
-
-// Usage
-this.http.get<Data[]>('/api/data').pipe(
-  retryWithBackoff(3, 500),
-  catchError(() => of([]))
-);
-```
-
-## Anti-Patterns
-
-- **Nested subscriptions**: Never subscribe inside a subscribe callback; use flattening operators (`switchMap`, `mergeMap`, etc.) instead.
-- **Forgetting to unsubscribe**: Every manual `.subscribe()` in a component must be cleaned up via `takeUntil`, `DestroyRef`, or the `async` pipe.
-- **Using `mergeMap` for search**: `mergeMap` does not cancel prior emissions; race conditions will show stale results. Use `switchMap`.
-- **Catching errors at the top level**: Placing `catchError` outside the inner observable kills the outer stream on first error.
-- **Subscribing multiple times to the same HTTP call**: HTTP observables are cold; each subscription triggers a new request. Use `shareReplay(1)` when sharing.
-
-## Integration Points
-
-- **Angular HttpClient**: Returns cold observables; combine with RxJS operators for caching, retry, and transformation.
-- **NgRx Effects**: Effects are observable streams that listen to actions and dispatch new actions; see `ngrx-state.md`.
-- **Angular Forms**: `valueChanges` and `statusChanges` are observables on reactive form controls.
-- **Component lifecycle**: Tie subscriptions to `OnDestroy` via the `destroy$` pattern or Angular 16+ `DestroyRef`.

package/_gaia/dev/knowledge/flutter/dart-conventions.md

@@ -1,143 +0,0 @@
----
-name: Dart Language Conventions
-stack: flutter
-version: "1.0"
-focus: [dart]
----
-
-# Dart Language Conventions
-
-## Principle
-
-Follow Effective Dart guidelines: embrace null safety, use strong typing with type inference where clear, prefer immutable data, and use `async`/`await` over raw `Future` chains. Write code that reads like well-structured prose, using Dart's expressive syntax features (cascades, collection literals, extension methods).
-
-## Rationale
-
-Dart's sound null safety eliminates entire categories of runtime errors at compile time. Type inference reduces verbosity without sacrificing safety. Extension methods add functionality to types without modifying them, keeping code modular. Consistent adherence to Effective Dart conventions ensures that code is idiomatic, readable, and maintainable across teams.
-
-## Pattern Examples
-
-### Pattern 1: Null Safety and Smart Typing
-
-```dart
-// Sound null safety — explicit nullable vs non-nullable
-class UserProfile {
-  final String name;           // required, never null
-  final String? bio;           // optional, may be null
-  final DateTime createdAt;
-
-  const UserProfile({
-    required this.name,
-    this.bio,
-    required this.createdAt,
-  });
-
-  // Null-aware operators
-  String get displayBio => bio ?? 'No bio provided';
-  int? get bioLength => bio?.length;  // null if bio is null
-
-  // Pattern matching with null checks (Dart 3)
-  String describe() => switch (bio) {
-    final b? when b.length > 100 => '${name} has a detailed bio',
-    final b? => '${name}: $b',
-    null => '${name} (no bio)',
-  };
-}
-```
-
-### Pattern 2: Extension Methods and Typedefs
-
-```dart
-// Extension on String for domain-specific logic
-extension StringValidation on String {
-  bool get isValidEmail =>
-      RegExp(r'^[\w-.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(this);
-
-  String get capitalized =>
-      isEmpty ? this : '${this[0].toUpperCase()}${substring(1)}';
-
-  String truncate(int maxLength, {String suffix = '...'}) =>
-      length <= maxLength ? this : '${substring(0, maxLength)}$suffix';
-}
-
-// Extension on DateTime
-extension DateTimeFormat on DateTime {
-  String get iso8601Date => toIso8601String().split('T').first;
-  bool get isToday {
-    final now = DateTime.now();
-    return year == now.year && month == now.month && day == now.day;
-  }
-}
-
-// Typedef for readability
-typedef JsonMap = Map<String, dynamic>;
-typedef FromJson<T> = T Function(JsonMap json);
-```
-
-### Pattern 3: Async/Await Patterns
-
-```dart
-// Structured async with error handling
-class ApiClient {
-  Future<Result<T>> safeRequest<T>(
-    Future<T> Function() request,
-  ) async {
-    try {
-      final data = await request();
-      return Result.success(data);
-    } on SocketException {
-      return Result.failure('No internet connection');
-    } on TimeoutException {
-      return Result.failure('Request timed out');
-    } on FormatException catch (e) {
-      return Result.failure('Invalid response: ${e.message}');
-    }
-  }
-}
-
-// Result type for explicit error handling
-sealed class Result<T> {
-  const Result();
-  const factory Result.success(T data) = Success;
-  const factory Result.failure(String message) = Failure;
-}
-
-class Success<T> extends Result<T> {
-  final T data;
-  const Success(this.data);
-}
-
-class Failure<T> extends Result<T> {
-  final String message;
-  const Failure(this.message);
-}
-
-// Parallel async operations
-Future<DashboardData> loadDashboard() async {
-  final results = await Future.wait([
-    fetchUserProfile(),
-    fetchNotifications(),
-    fetchMetrics(),
-  ]);
-  return DashboardData(
-    profile: results[0] as UserProfile,
-    notifications: results[1] as List<Notification>,
-    metrics: results[2] as Metrics,
-  );
-}
-```
-
-## Anti-Patterns
-
-- **Using `dynamic` to avoid typing**: Defeats null safety and type checking. Use generics or union types instead.
-- **Catching `Exception` generically**: Catch specific exception types for proper error handling.
-- **Mutable data classes**: Prefer `final` fields and `const` constructors for value objects. Use `copyWith` for modifications.
-- **Ignoring linter rules**: Configure `analysis_options.yaml` with recommended rules and fix all warnings.
-- **Nested `.then()` chains**: Use `async`/`await` for readability. Reserve `.then()` only for fire-and-forget scenarios.
-
-## Integration Points
-
-- **Flutter Widgets**: Dart conventions (const, null safety, sealed classes) directly impact widget code; see `widget-patterns.md`.
-- **State Management**: Sealed classes and pattern matching define state hierarchies; see `state-management.md`.
-- **Platform Channels**: Async/await wraps channel calls; see `platform-channels.md`.
-- **Linting**: Use `flutter_lints` or `very_good_analysis` for enforcement.

package/_gaia/dev/knowledge/flutter/platform-channels.md

@@ -1,144 +0,0 @@
----
-name: Flutter Platform Channels
-stack: flutter
-version: "1.0"
-focus: [flutter]
----
-
-# Flutter Platform Channels
-
-## Principle
-
-Use platform channels to bridge Dart and native code (iOS/Android) when Flutter APIs do not cover a native capability. Use `MethodChannel` for request/response calls, `EventChannel` for continuous native-to-Dart streams, and `BasicMessageChannel` for simple bidirectional messaging. Always handle platform exceptions and check platform availability before invoking.
-
-## Rationale
-
-Flutter provides a rich set of plugins, but some features (biometrics, Bluetooth LE, custom camera pipelines, native SDKs) require direct native integration. Platform channels provide a structured, type-safe mechanism for this communication. Proper error handling and platform detection ensure the app degrades gracefully on unsupported platforms.
-
-## Pattern Examples
-
-### Pattern 1: MethodChannel for Native Calls
-
-```dart
-// Dart side — request/response pattern
-class BatteryService {
-  static const _channel = MethodChannel('com.example.app/battery');
-
-  Future<int> getBatteryLevel() async {
-    try {
-      final int level = await _channel.invokeMethod('getBatteryLevel');
-      return level;
-    } on PlatformException catch (e) {
-      throw BatteryException('Failed to get battery level: ${e.message}');
-    }
-  }
-}
-
-// Android (Kotlin)
-class MainActivity : FlutterActivity() {
-    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
-        super.configureFlutterEngine(flutterEngine)
-        MethodChannel(flutterEngine.dartExecutor.binaryMessenger,
-            "com.example.app/battery"
-        ).setMethodCallHandler { call, result ->
-            when (call.method) {
-                "getBatteryLevel" -> {
-                    val level = getBatteryLevel()
-                    if (level != -1) result.success(level)
-                    else result.error("UNAVAILABLE", "Battery level unavailable", null)
-                }
-                else -> result.notImplemented()
-            }
-        }
-    }
-}
-
-// iOS (Swift)
-@UIApplicationMain
-class AppDelegate: FlutterAppDelegate {
-    override func application(
-        _ application: UIApplication,
-        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-    ) -> Bool {
-        let controller = window?.rootViewController as! FlutterViewController
-        let channel = FlutterMethodChannel(
-            name: "com.example.app/battery",
-            binaryMessenger: controller.binaryMessenger
-        )
-        channel.setMethodCallHandler { call, result in
-            guard call.method == "getBatteryLevel" else {
-                result(FlutterMethodNotImplemented)
-                return
-            }
-            result(UIDevice.current.batteryLevel * 100)
-        }
-        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-    }
-}
-```
-
-### Pattern 2: EventChannel for Streaming Data
-
-```dart
-// Dart — continuous stream from native
-class AccelerometerService {
-  static const _eventChannel = EventChannel('com.example.app/accelerometer');
-
-  Stream<AccelerometerData> get readings {
-    return _eventChannel.receiveBroadcastStream().map((event) {
-      final map = Map<String, double>.from(event as Map);
-      return AccelerometerData(x: map['x']!, y: map['y']!, z: map['z']!);
-    });
-  }
-}
-
-// Consumed in widget
-StreamBuilder<AccelerometerData>(
-  stream: accelerometerService.readings,
-  builder: (context, snapshot) {
-    if (!snapshot.hasData) return const Text('Waiting...');
-    final data = snapshot.data!;
-    return Text('X: ${data.x.toStringAsFixed(2)}');
-  },
-);
-```
-
-### Pattern 3: Platform Detection
-
-```dart
-import 'dart:io' show Platform;
-import 'package:flutter/foundation.dart' show kIsWeb;
-
-class PlatformService {
-  static bool get isIOS => !kIsWeb && Platform.isIOS;
-  static bool get isAndroid => !kIsWeb && Platform.isAndroid;
-  static bool get isMobile => isIOS || isAndroid;
-  static bool get isDesktop =>
-      !kIsWeb && (Platform.isMacOS || Platform.isWindows || Platform.isLinux);
-
-  static Future<T> platformSpecific<T>({
-    required Future<T> Function() ios,
-    required Future<T> Function() android,
-    Future<T> Function()? fallback,
-  }) async {
-    if (isIOS) return ios();
-    if (isAndroid) return android();
-    if (fallback != null) return fallback();
-    throw UnsupportedError('Platform not supported');
-  }
-}
-```
-
-## Anti-Patterns
-
-- **String-typed channel names without constants**: Typos in channel names cause silent failures. Define names as `static const`.
-- **No error handling on native side**: Unhandled native exceptions crash the app. Always wrap in try/catch and use `result.error()`.
-- **Heavy computation on the platform thread**: Blocking the main thread on native side causes UI jank. Use background threads for heavy work.
-- **Ignoring platform availability**: Calling iOS-only APIs on Android throws. Always check the platform first.
-
-## Integration Points
-
-- **State Management**: Native data streams feed into BLoC/Cubit state; see `state-management.md`.
-- **Widget Layer**: Platform-specific widgets use conditional rendering; see `widget-patterns.md`.
-- **Dart Conventions**: Follow async/await patterns for channel calls; see `dart-conventions.md`.
-- **Testing**: Mock the method channel in tests using `TestDefaultBinaryMessengerBinding`.

package/_gaia/dev/knowledge/flutter/state-management.md

@@ -1,144 +0,0 @@
----
-name: Flutter State Management
-stack: flutter
-version: "1.0"
-focus: [flutter]
----
-
-# Flutter State Management
-
-## Principle
-
-Choose the state management approach that matches the complexity of the state being managed. Use `setState` for local ephemeral state, `Provider`/`Riverpod` for simple shared state, and BLoC/Cubit for complex business logic with well-defined state transitions. Never mix approaches arbitrarily within the same feature.
-
-## Rationale
-
-Flutter has no single "right" state management solution. The key is matching the tool to the problem. `setState` is perfect for UI-only state (tab index, animation). Provider offers simple dependency injection and reactive rebuilds. Riverpod improves on Provider with compile-time safety and no `BuildContext` dependency. BLoC enforces a strict event-driven architecture ideal for complex flows with testable state transitions.
-
-## Pattern Examples
-
-### Pattern 1: BLoC/Cubit Pattern
-
-```dart
-// State definition — sealed class for exhaustive matching
-sealed class AuthState {}
-class AuthInitial extends AuthState {}
-class AuthLoading extends AuthState {}
-class AuthAuthenticated extends AuthState {
-  final User user;
-  AuthAuthenticated(this.user);
-}
-class AuthError extends AuthState {
-  final String message;
-  AuthError(this.message);
-}
-
-// Cubit — simpler than full BLoC when events aren't needed
-class AuthCubit extends Cubit<AuthState> {
-  AuthCubit(this._authRepo) : super(AuthInitial());
-  final AuthRepository _authRepo;
-
-  Future<void> signIn(String email, String password) async {
-    emit(AuthLoading());
-    try {
-      final user = await _authRepo.signIn(email, password);
-      emit(AuthAuthenticated(user));
-    } catch (e) {
-      emit(AuthError(e.toString()));
-    }
-  }
-
-  Future<void> signOut() async {
-    await _authRepo.signOut();
-    emit(AuthInitial());
-  }
-}
-
-// Widget consumption
-BlocBuilder<AuthCubit, AuthState>(
-  builder: (context, state) => switch (state) {
-    AuthInitial() => const LoginForm(),
-    AuthLoading() => const CircularProgressIndicator(),
-    AuthAuthenticated(:final user) => HomeScreen(user: user),
-    AuthError(:final message) => ErrorView(message: message),
-  },
-);
-```
-
-### Pattern 2: Riverpod with AsyncNotifier
-
-```dart
-// Provider definition — no BuildContext needed
-@riverpod
-class TodoList extends _$TodoList {
-  @override
-  Future<List<Todo>> build() async {
-    return ref.read(todoRepositoryProvider).fetchAll();
-  }
-
-  Future<void> addTodo(String title) async {
-    state = const AsyncLoading();
-    state = await AsyncValue.guard(() async {
-      await ref.read(todoRepositoryProvider).add(title);
-      return ref.read(todoRepositoryProvider).fetchAll();
-    });
-  }
-}
-
-// Widget consumption
-class TodoScreen extends ConsumerWidget {
-  const TodoScreen({super.key});
-
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final todosAsync = ref.watch(todoListProvider);
-    return todosAsync.when(
-      data: (todos) => TodoListView(todos: todos),
-      loading: () => const CircularProgressIndicator(),
-      error: (err, stack) => ErrorView(message: err.toString()),
-    );
-  }
-}
-```
-
-### Pattern 3: Provider for Simple DI
-
-```dart
-// Simple shared state with ChangeNotifier
-class CartModel extends ChangeNotifier {
-  final List<Product> _items = [];
-  List<Product> get items => List.unmodifiable(_items);
-  double get total => _items.fold(0, (sum, p) => sum + p.price);
-
-  void add(Product product) {
-    _items.add(product);
-    notifyListeners();
-  }
-
-  void remove(String productId) {
-    _items.removeWhere((p) => p.id == productId);
-    notifyListeners();
-  }
-}
-
-// Provided at app root
-ChangeNotifierProvider(create: (_) => CartModel(), child: const MyApp());
-
-// Consumed
-final cart = context.watch<CartModel>();
-Text('Total: \$${cart.total.toStringAsFixed(2)}');
-```
-
-## Anti-Patterns
-
-- **Global state for everything**: Using BLoC for toggle buttons or tab indices. Use `setState` for ephemeral UI state.
-- **Mixing approaches randomly**: Using Provider in one feature, BLoC in another, and Riverpod in a third within the same app.
-- **Fat BLoCs**: Putting UI formatting logic in BLoC. BLoC handles business logic; the widget formats display.
-- **Not sealing state classes**: Using abstract base class without sealed means the compiler cannot check exhaustiveness in switch statements.
-
-## Integration Points
-
-- **Widgets**: State is consumed in the widget layer via `BlocBuilder`, `Consumer`, or `context.watch`; see `widget-patterns.md`.
-- **Platform Channels**: Async platform calls feed into state management layer; see `platform-channels.md`.
-- **Testing**: Cubits and Notifiers are plain Dart classes, easily testable without Flutter test harness.
-- **Navigation**: State transitions (authenticated/unauthenticated) drive route guards.

package/_gaia/dev/knowledge/flutter/widget-patterns.md

@@ -1,134 +0,0 @@
----
-name: Flutter Widget Patterns
-stack: flutter
-version: "1.0"
-focus: [flutter]
----
-
-# Flutter Widget Patterns
-
-## Principle
-
-Build UIs through small, composable widgets. Use `const` constructors wherever possible to enable framework-level render optimization. Understand the widget-element-renderobject tree to make informed decisions about when to split widgets, use keys, and optimize rebuilds.
-
-## Rationale
-
-Flutter rebuilds widgets frequently. The framework diffs the widget tree and only updates elements whose configuration changed. `const` widgets are canonicalized at compile time, so the framework skips diffing them entirely. Splitting large build methods into smaller widgets gives Flutter finer granularity for selective rebuilds, and `Key` objects ensure correct element reuse when lists reorder.
-
-## Pattern Examples
-
-### Pattern 1: Const Constructors and Widget Extraction
-
-```dart
-// Good: const constructor enables compile-time canonicalization
-class StatusBadge extends StatelessWidget {
-  const StatusBadge({super.key, required this.label, required this.color});
-
-  final String label;
-  final Color color;
-
-  @override
-  Widget build(BuildContext context) {
-    return Container(
-      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 4),
-      decoration: BoxDecoration(
-        color: color.withOpacity(0.15),
-        borderRadius: const BorderRadius.all(Radius.circular(12)),
-      ),
-      child: Text(
-        label,
-        style: TextStyle(color: color, fontWeight: FontWeight.w600),
-      ),
-    );
-  }
-}
-
-// Usage with const — Flutter skips rebuild entirely
-const StatusBadge(label: 'Active', color: Colors.green);
-```
-
-### Pattern 2: Keys for List Reordering
-
-```dart
-class TodoList extends StatelessWidget {
-  const TodoList({super.key, required this.items});
-  final List<TodoItem> items;
-
-  @override
-  Widget build(BuildContext context) {
-    return ListView.builder(
-      itemCount: items.length,
-      itemBuilder: (context, index) {
-        final item = items[index];
-        // ValueKey ensures correct element reuse when items reorder
-        return Dismissible(
-          key: ValueKey(item.id),
-          onDismissed: (_) => context.read<TodoCubit>().remove(item.id),
-          child: TodoTile(item: item),
-        );
-      },
-    );
-  }
-}
-```
-
-### Pattern 3: Custom Widget with Composition
-
-```dart
-class UserCard extends StatelessWidget {
-  const UserCard({
-    super.key,
-    required this.user,
-    this.onTap,
-    this.trailing,
-  });
-
-  final User user;
-  final VoidCallback? onTap;
-  final Widget? trailing;
-
-  @override
-  Widget build(BuildContext context) {
-    final theme = Theme.of(context);
-    return Card(
-      child: InkWell(
-        onTap: onTap,
-        borderRadius: BorderRadius.circular(12),
-        child: Padding(
-          padding: const EdgeInsets.all(16),
-          child: Row(
-            children: [
-              CircleAvatar(backgroundImage: NetworkImage(user.avatarUrl)),
-              const SizedBox(width: 12),
-              Expanded(
-                child: Column(
-                  crossAxisAlignment: CrossAxisAlignment.start,
-                  children: [
-                    Text(user.name, style: theme.textTheme.titleMedium),
-                    Text(user.email, style: theme.textTheme.bodySmall),
-                  ],
-                ),
-              ),
-              if (trailing != null) trailing!,
-            ],
-          ),
-        ),
-      ),
-    );
-  }
-}
-```
-
-## Anti-Patterns
-
-- **Mega build methods**: A single `build()` with 200+ lines. Extract sub-widgets so Flutter can selectively rebuild.
-- **Missing const**: Omitting `const` on constructors and widget instantiations wastes the canonicalization optimization.
-- **Using `GlobalKey` for everything**: `GlobalKey` is expensive; prefer `ValueKey` or `ObjectKey` for list items.
-- **Rebuilding the entire tree on state change**: Not splitting stateful and stateless parts. Place `StatefulWidget` at the narrowest scope possible.
-
-## Integration Points
-
-- **State Management**: Widgets consume state from BLoC/Cubit/Provider; see `state-management.md`.
-- **Platform Channels**: Custom widgets may wrap platform-specific views; see `platform-channels.md`.
-- **Dart Conventions**: Follow `const` and null-safety patterns from `dart-conventions.md`.
-- **Theme**: Access `Theme.of(context)` for consistent styling; define tokens in `ThemeData`.