feat(docs): Add detailed reports for issues #511 and #531 addressing model validation and type duplication

2026-01-04 01:02:29 -05:00
parent 4d0a10c458
commit 542da8b7a1
2 changed files with 132 additions and 0 deletions
@@ -0,0 +1,70 @@
+# Issue #511: GeminiAgent Missing gemini-3-flash Model
+
+## Summary
+
+**Issue**: `gemini-3-flash` model missing from GeminiAgent validation
+**Type**: Bug - Configuration Mismatch
+**Status**: Open
+
+The `GeminiAgent` class is missing `gemini-3-flash` in its `validModels` array and `GeminiModel` type, while `SettingsRoutes` correctly validates it. This causes a silent fallback to `gemini-2.5-flash` when users configure `gemini-3-flash`.
+
+## Root Cause
+
+Synchronization gap between two configuration validation sources:
+
+| Component | Location | Status |
+|-----------|----------|--------|
+| SettingsRoutes.ts (line 244) | Settings validation | Includes `gemini-3-flash` |
+| GeminiAgent.ts (lines 34-39) | Type definition | **MISSING** |
+| GeminiAgent.ts (lines 42-48) | RPM limits | **MISSING** |
+| GeminiAgent.ts (lines 370-376) | validModels array | **MISSING** |
+
+## Failure Behavior
+
+1. User configures `gemini-3-flash` in settings
+2. Settings validation passes (SettingsRoutes.ts includes it)
+3. At runtime, `GeminiAgent.getGeminiConfig()`:
+   - Checks `validModels` - model not found
+   - Logs warning: "Invalid Gemini model 'gemini-3-flash', falling back to gemini-2.5-flash"
+   - Silently uses wrong model
+
+## Affected Files
+
+| File | Change Required |
+|------|-----------------|
+| `src/services/worker/GeminiAgent.ts` | Add to type, RPM limits, validModels |
+
+## Recommended Fix
+
+**3 additions to GeminiAgent.ts:**
+
+```typescript
+// 1. Type definition (lines 34-39)
+export type GeminiModel =
+  | 'gemini-2.5-flash-lite'
+  | 'gemini-2.5-flash'
+  | 'gemini-2.5-pro'
+  | 'gemini-2.0-flash'
+  | 'gemini-2.0-flash-lite'
+  | 'gemini-3-flash';  // ADD
+
+// 2. RPM limits (lines 42-48)
+const GEMINI_RPM_LIMITS: Record<GeminiModel, number> = {
+  // ... existing entries ...
+  'gemini-3-flash': 5,  // ADD
+};
+
+// 3. validModels (lines 370-376)
+const validModels: GeminiModel[] = [
+  // ... existing entries ...
+  'gemini-3-flash',  // ADD
+];
+```
+
+## Complexity
+
+**Trivial** - < 5 minutes
+
+- 3 lines to add in 1 file
+- No test changes required
+- Fully backward compatible
@@ -0,0 +1,62 @@
+# Issue #531: Export Script Type Duplication
+
+## Summary
+
+**Issue**: Reduce code duplication in export scripts with shared type definitions
+**Type**: Code Quality/Maintainability
+**Status**: Open
+**Author**: @rjmurillo
+
+The `export-memories.ts` script defines type interfaces inline that duplicate definitions already present in `src/types/database.ts`. This creates a maintenance burden and prevents DRY principles.
+
+## Root Cause
+
+Type duplication exists across two locations:
+
+**Location 1: `scripts/export-memories.ts` (lines 13-85)**
+- `ObservationRecord` (18 lines)
+- `SdkSessionRecord` (12 lines)
+- `SessionSummaryRecord` (17 lines)
+- `UserPromptRecord` (8 lines)
+- `ExportData` (14 lines)
+
+**Location 2: `src/types/database.ts` (lines 46-108)**
+- `SdkSessionRecord`, `ObservationRecord`, `SessionSummaryRecord`, `UserPromptRecord`
+
+**Total Duplication**: ~73 lines that mirror existing type definitions
+
+## Type Discrepancies
+
+| Type | Export Script | Database Type |
+|------|---------------|---------------|
+| ObservationRecord.title | `string` (required) | `string?` (optional) |
+| SdkSessionRecord.user_prompt | `string` (required) | `string \| null` |
+| SessionSummaryRecord | Includes `files_read`, `files_edited` | Missing these fields |
+| ExportData | Unique wrapper | No equivalent |
+
+## Affected Files
+
+1. `scripts/export-memories.ts` - Primary duplication source
+2. `src/types/database.ts` - Master type definitions
+3. `scripts/import-memories.ts` - Uses export data structure
+4. `src/services/worker-types.ts` - Related types with different naming
+
+## Recommended Fix
+
+1. Create `scripts/types/export.ts` with export-specific type extensions
+2. Use type composition to handle optionality differences:
+   ```typescript
+   export interface ExportObservationRecord extends Omit<DatabaseObservationRecord, 'title'> {
+     title: string; // Override: required for exports
+   }
+   ```
+3. Update import paths in export/import scripts
+
+## Complexity
+
+**Medium** - 2-3 hours
+
+- Type discrepancies require careful mapping
+- Only 4 files need updates
+- No breaking changes (internal scripts)
+- Existing tests should continue to pass