# External Contributions

This document tracks contributions made by collaborators outside the core project.

Its purpose is to support ongoing evaluation of each contributor's work quality,

patterns, and reliability over time.

---

## Contributor A — anonim, prieten al autorului

Toate intervențiile cunoscute sunt în `AppData.swift`, `ChargeInsightsStore.swift`, și `Meter.swift`.

---

### Intervenție 1 — Fix lag UI la formulare (aprilie 2026)

**Context:** La conectarea unui contor live, formularele din UI (typing, picker)

deveneau iresponsive. `reloadChargedDevices()` rula sincron pe main thread la fiecare

snapshot BLE (~1/s), blocând UIKit.

**Commit:** `4f79218` *(înglobat cu Intervenția 2)*

**Modificări introduse:**

- `chargeInsightsReadStore` — context separat de citire (`privateQueueConcurrencyType`)

- `chargedDevicesReloadQueue` — fetch mutat pe background queue

- `chargedDevicesReloadGeneration` — counter de invalidare pentru fetch-uri async depășite

**Bug introdus (descoperit ulterior):**

Pattern-ul generation+invalidare era prea agresiv. Contorul era incrementat la fiecare

apel `reloadChargedDevices()`, inclusiv cele declanșate în burst de

`NSManagedObjectContextObjectsDidChange`. Orice fetch async dura >0ms → generația era

deja depășită la finalizare → rezultatul era aruncat. Lista rămânea goală permanent

atât timp cât un contor live era conectat, indiferent că SQLite conținea date reale.

**Evaluare:** Problema identificată era reală. Soluția era funcțională în absența unui

contor conectat (test static), dar s-a rupt sub load real. Eroare clasică de

async invalidation, probabil netestat cu dispozitiv real.

---

### Intervenție 2 — Fix starvation reload (după aprilie 2026)

**Context:** Lista de charged devices rămânea goală permanent când un contor era activ.

Cauzat de bug-ul din Intervenția 1. Autorul a identificat și corectat singur problema.

**Commit:** `4f79218`

**Modificări introduse:**

- Înlocuire generation counter cu pattern `inFlight`/`pending`

  - `chargedDevicesReloadInFlight: Bool` — un singur fetch în zbor la un moment dat

  - `chargedDevicesReloadPending: Bool` — cerere nouă marcată pentru după finalizare

- `scheduleChargedDevicesReload(delay: 0.15)` — debounce pentru burst-uri de notificări

**Evaluare:** Corect și complet. Soluția standard pentru problema dată. Nu introduce

regresii. Diagnosticul era precis (cita dimensiunile exacte din SQLite: 10 devices,

15 sesiuni, 49 checkpoints, 24.279 samples).

---

### Intervenție 3 — Optimizare CPU pe Catalyst (aprilie 2026)

**Context:** Procesul Catalyst consuma CPU ridicat și constant. Identificat prin profiling.

**Commits:** `406be0e` (împreună cu ajustări ulterioare ale intervalelor)

**Cauze identificate de contributor:**

1. BLE polling continuu — `dataDumpRequest()` recursiv imediat după fiecare răspuns

2. Fiecare pachet BLE atingea CoreData/iCloud direct, cu reload UI frecvent

3. `noteMeterSeen` scria în `MeterNameStore` la fiecare observație

**Modificări introduse:**

- `Meter.swift` — `minimumLivePollingInterval = 0.4s`; înlocuit recursie imediată cu

  `scheduleNextLiveDataDumpRequest()` care respectă intervalul minim

- `AppData.swift` — coalescere snapshot-uri BLE în memorie (`pendingChargeObservationSnapshots`);

  flush periodic la 30s cu flush explicit la pause/stop/checkpoint/terminate;

  throttle `noteMeterSeen` la 15s; observer schimbat din `ObjectsDidChange` → `DidSave`

- `AppData.swift` — `writeContext` privat pentru `ChargeInsightsStore`

  (anterior store-ul scria direct pe `viewContext`, i.e. main thread)

- `ChargeInsightsStore.swift` — `maximumLiveIntegrationGap` 20s → 90s

  (aliniat cu fereastra de coalescere de 30s)

**Probleme rămase după livrare (rezolvate în același commit):**

- Work item-ul de flush era dispatchat pe `DispatchQueue.main`; apela

  `context.performAndWait` → bloca main thread la fiecare 30s (spike vizibil în profiler)

- `flushPendingChargeObservation` chema explicit `reloadChargedDevices()`, iar observer-ul

  DidSave chema și el `scheduleChargedDevicesReload()` — double reload per flush

Aceste două probleme au fost remediate separat (fix în `406be0e`):

flush-ul periodic mută scrierea CoreData pe `DispatchQueue.global(qos: .utility)`;

reload-ul explicit eliminat din flush, lăsat exclusiv pe seama observer-ului DidSave.

**Note privind originea problemelor rezolvate:**

`NSManagedObjectContextObjectsDidChange` ca observer și `viewContext` pentru scrieri

existau în codul proiectului **înainte** de orice intervenție a acestui contributor.

Intervenția 3 rezolvă probleme de design preexistente, nu regresii proprii.

Singura auto-corecție este `maximumLiveIntegrationGap`, ajustat pentru coalescing-ul

introdus tot în această intervenție.

**Evaluare:** Diagnostic corect pentru toate cele trei cauze. Modificările sunt

coerente între ele. Livrarea conținea două bug-uri minore (main thread + double reload)

care au necesitat remediere imediată, detectabile printr-un review atent al codului

fără a fi nevoie de runtime. Efectul net: CPU redus de la consum constant la 0–4%

cu spike-uri reziduale la ~30s (CloudKit sync inerent).

---

## Session Trim Feature — Buffer Restore Bug (pentru externalizare)

### Contextul feature-ului

S-a implementat un feature de "Session Trim": detectare automată a ferestrei reale de încărcare (ex: Apple Watch se încarcă 3h dar sesiunea rulează 16h overnight) + editor manual pentru trim. Feature-ul este complet implementat și compilează fără erori.

**Există un bug pre-existent** care blochează funcționarea feature-ului și trebuie rezolvat separat.

---

### Bug: istoricul sesiunii se pierde la fiecare restart de aplicație

**Simptom:** La restart cu sesiune activă, graficul afișează intervalul complet al sesiunii (ex: 16h) dar cu date doar din momentul reconectării BLE. Istoricul din Core Data nu este restaurat.

**Consecință pentru trim:** Banner-ul de trim nu apare (se bazează pe `aggregatedSamples` gol), editorul de trim are graficul gol.

---

### Unde este problema

**`Meter.restoreChargeRecordIfNeeded(from:)`** — `USB Meter/Model/Meter.swift`

```swift

func restoreChargeRecordIfNeeded(from activeSession: ChargeSessionSummary) {

    guard chargeRecordState == .waitingForStart else { return }  // ← problema

    guard chargeRecordStartTimestamp == nil else { return }

    guard chargeRecordAH == 0, chargeRecordWH == 0, chargeRecordDuration == 0 else { return }

    measurements.restorePersistedChargeSessionSamplesIfNeeded(from: activeSession)

    ...

}

```

**Race condition:** Datele BLE ajung înaintea completării `reloadChargedDevices` (async). La primul pachet BLE, `chargeRecordState` trece `waitingForStart → active`. Când `reloadChargedDevices` finalizează și încearcă restore, primul guard blochează — permanent pentru sesiunea curentă.

**`Measurements.restorePersistedChargeSessionSamplesIfNeeded`** are propriul guard: returnează dacă vreun series este non-gol. Dacă se rezolvă problema de mai sus și datele BLE au umplut deja buffer-ul, acesta trebuie resetat înainte de restore — dar **numai dacă `aggregatedSamples` nu este gol**, altfel graficul rămâne gol definitiv.

---

### Lanțul de apel la pornire

```text

SceneDelegate.activateCloudDeviceSync

  → AppData.activateChargeInsights        // setup writeContext + readContext

  → AppData.scheduleChargedDevicesReload  // async, ~100–500ms

[BLE se conectează, date ajung — pe main queue]

  → Meter.processData → Meter.updateChargeRecord

    → chargeRecordState = .active  // ← guard-ul din restore va bloca

[reloadChargedDevices completează]

  → AppData.restoreChargeMonitoringStateIfNeeded(for: meter)

    → Meter.restoreChargeRecordIfNeeded(from: session)  // ← guard blochează

```

---

### Fișiere modificate de feature (necommitted, diff disponibil)

| Fișier | Modificare |

| ------ | ---------- |

| `USB Meter/Model/CKModel.xcdatamodeld/USB_Meter 15.xcdatamodel/` | Nou — adaugă `trimStart`/`trimEnd` opționale pe `ChargeSession` |

| `USB Meter/Model/CKModel.xcdatamodeld/.xccurrentversion` | → v15 |

| `USB Meter/Model/ChargingWindowDetector.swift` | Nou — detectează fereastra activă de încărcare |

| `USB Meter/Views/Meter/Tabs/ChargeRecord/SessionTrimEditorView.swift` | Nou — editor trim cu drag handles |

| `USB Meter/Model/ChargeInsightsModel.swift` | `trimStart`, `trimEnd`, `isTrimmed` pe `ChargeSessionSummary` |

| `USB Meter/Model/ChargeInsightsStore.swift` | `setSessionTrim(sessionID:start:end:)` — recalculează energie, șterge checkpoints |

| `USB Meter/Model/AppData.swift` | Wrapper `setSessionTrim` |

| `USB Meter/Views/Meter/Tabs/ChargeRecord/MeterChargeRecordTabView.swift` | Banner detecție + sheet editor |

| `USB Meter.xcodeproj/project.pbxproj` | Referințe fișiere noi |

---

## Tipare observate

| | Interv. 1 | Interv. 2 | Interv. 3 |

|---|---|---|---|

| Diagnostic corect | Da | Da | Da |

| Funcționează fără load real | Da | Da | Da |

| Funcționează sub load real | Nu | Da | Parțial |

| Auto-corecție necesară | — | Da (proprie) | Parțial (externă) |

| Regresii introduse | Da (starvation) | Nu | Nu |

**Observație recurentă:** Contribuțiile funcționează corect în condiții statice dar

au tendința să rateze edge case-uri sub load real (contor live conectat). Testele

înainte de livrare par să nu includă scenariul cu dispozitiv activ.