Charge Session Integrity and Conflict Healing

Core Invariant

A meter can have at most one open charge session at any given time.

"Open" means statusRawValue is either active or paused. This invariant is used throughout the app to look up the active session for a meter without ambiguity.

How the Invariant Is Enforced at Creation

ChargeInsightsStore.startSession(...) checks for an existing open session on the same meterMACAddress before creating a new one:

guard fetchOpenSessionObject(forMeterMACAddress: snapshot.meterMACAddress) == nil else {
    return
}

This check is sufficient when all devices are online and share a consistent view of the CloudKit store. It is not sufficient when devices work offline independently.

Scenarios Where the Invariant Can Be Violated

Scenario A — Forgotten session + new session on another device (primary concern)

The user starts a session on Device A and forgets about it (walks away, doesn't close the app).
The user picks up Device B, which has not yet synced from Device A.
Device B finds no open session for the meter (it doesn't know about Device A's session yet).
Device B creates a new session successfully.
When both devices come back online and CloudKit syncs, both sessions are open for the same meter.

This is the most realistic scenario. Current meters (UM25C, UM34C, TC66C) only support one BT connection at a time, so both sessions cannot be live simultaneously — but the forgotten session remains open in the database.

Scenario B — Two devices simultaneously offline on meters that support multiple connections

If a future meter model supports multiple concurrent BT connections, two devices could legitimately start sessions for the same meter at the same time, both while offline. The healing mechanism covers this automatically, though the winner selection may be debatable in that case.

Scenario C — CloudKit conflict on `statusRawValue` itself

NSMergeByPropertyObjectTrumpMergePolicy is used throughout: in-memory values win over CloudKit-synced values at the Core Data level. This means a stopSession write on Device A while Device B has also written to the same session record could theoretically produce inconsistent statusRawValue after sync. This is distinct from the duplicate-session scenario and is considered unlikely in practice, but worth noting.

Healing Mechanism

ChargeInsightsStore.healDuplicateOpenSessions() is called from AppData.reloadChargedDevices() on every reload cycle, which is triggered by:

App startup (first device list load)
Every remote CloudKit change (NSPersistentStoreRemoteChange notification)
Every local Core Data write (via NSManagedObjectContextDidSave)

Algorithm

Fetch all open sessions (status active or paused).
Group by meterMACAddress.
For any group with more than one session:
- Winner = session with the latest startedAt. This represents the user's most recent explicit intent — they chose to start a new session, which means the older one was forgotten.
- Tie-break: higher measuredEnergyWh wins (the session that observed more charging is likely more useful).
- Loser(s): closed with status abandoned, endedAt set to winner's startedAt.
Save, then refresh derived metrics for affected devices.

Why `startedAt` instead of `updatedAt` for winner selection

updatedAt reflects the last write to the record, which could be CloudKit metadata or a background observation flush — not necessarily a user action. startedAt is set once at creation and directly represents the user's decision to begin a session. The session started later is the one the user intended to be active.

Overlap prevention

The loser's endedAt is set to the winner's startedAt (not Date() / "now"). This ensures the two sessions are contiguous with no gap and no overlap, which is important for:

Correct total energy accounting across a device's session history
Clean chart rendering (no two sessions claiming the same time range)
Capacity estimation (no double-counting of energy delivered in the same window)

Data Model

ChargeSession entity (Core Data model v16) includes:

Attribute	Type	Purpose
`wasConflictHealed`	`Boolean, optional`	`true` on sessions closed by the healing mechanism. `nil`/`false` on normal sessions.

This attribute is synced via CloudKit so all devices eventually see the flag, even if healing ran on only one of them.

UI Indicators

Sessions with wasConflictHealed == true are visually distinguished in ChargedDeviceSessionsView:

An orange icon (⟳) appears next to the status badge in the session card header, with a tooltip: "This session was automatically closed because a newer session was started on another device while offline."
The secondary info line includes "Auto-closed (sync conflict)" alongside other metadata (transport mode, trim, source mode).

The intent is to surface the event without alarming the user — the data is intact and the time range is correctly bounded.

What Is Not Covered

Detection at session-start time

When Device B starts a session while offline, it cannot know that Device A has an open session. There is no mechanism to warn the user before the conflict occurs. Healing is entirely reactive (post-sync).

A proactive approach would require a "soft lock" written to CloudKit before starting a session, which introduces latency and complexity. Not implemented.

Manual conflict resolution

Currently the loser is always automatically abandoned. There is no UI for the user to inspect the conflict and choose which session to keep, merge, or adjust. For the current meter lineup (single-connection BT), the automatic resolution is almost always correct.

Overlapping sessions on the same `chargedDeviceID` across different meters

The invariant is enforced per meterMACAddress, not per chargedDeviceID. If the same physical device is charged on two different meters simultaneously (unlikely but possible with future hardware), both sessions would have different MAC addresses and the invariant would not catch them. The healing mechanism would not fire because there is no duplicate per MAC.

Paused session + new session conflict

A paused session is still "open" and is treated the same as an active session for healing purposes. If healing runs on a paused + active pair, the paused session (earlier startedAt) becomes the loser. This is correct: the user started a new session, so the paused one was effectively abandoned.

Future Considerations

If future meters support multiple concurrent connections, the winner-selection strategy (latest startedAt) should be re-evaluated — in that case the session with more observed data might be preferable.
If session merging becomes desirable (combine energy from both conflicting sessions into one record), wasConflictHealed provides the signal to identify candidates.
A "conflict history" section in the device detail or a one-time notification could be added to inform users when healing has run, especially if conflicts become more frequent with new hardware.