# No Ampere-Hours (Ah) in UI or Model

## Decision

The application does not display, expose, or compute user-visible measurements in ampere-hours (Ah or mAh). This is a deliberate policy, not an omission.

## Rationale

### The physics

Ampere-hours measure **electric charge** — the integral of current over time (∫ I·dt). They express how many coulombs of charge flowed through a circuit, independent of voltage.

Watt-hours measure **energy** — the integral of power over time (∫ V·I·dt). Energy is what actually matters for a battery: it tells you how much work the battery can do, accounting for the voltage at which charge is delivered.

For a battery with a flat discharge curve these two metrics are proportional, but real batteries have voltage that drops as they discharge. A 3.5 V lithium cell and a 5.0 V USB output delivering the "same" mAh are not delivering the same energy. The difference can be 30% or more.

### The marketing abuse

Consumer electronics marketing adopted mAh as a proxy for battery capacity because the number is conveniently large:
- "10,000 mAh power bank" sounds more impressive than "37 Wh power bank"
- But 10,000 mAh at 3.7 V (lithium cell voltage) ≈ 37 Wh, while 10,000 mAh at 5 V (USB output voltage) ≈ 50 Wh
- Manufacturers measure at cell voltage; the useful output is at USB voltage — the same number means different things depending on context

This ambiguity has been widely documented and is a known source of consumer confusion. Rating bodies and careful reviewers use Wh.

### For this app specifically

USB Meter measures charge delivered over USB, where voltage is never constant. Reporting in Ah would require specifying *which voltage* to use, and any fixed reference (3.7 V, 5 V, nominal) would be arbitrary and misleading. Wh is unambiguous: it is always the integral of V·I·dt as measured at the USB port.

## What this means in practice

### UI
- No measurement expressed in Ah or mAh should appear in any view
- Battery capacity is expressed exclusively in Wh (`capacityEstimateWh`)
- Session energy is expressed exclusively in Wh (`measuredEnergyWh`, `effectiveBatteryEnergyWh`)

### Model layer (Swift)
- `ChargeSessionSummary`, `ChargeCheckpointSummary`, and `ChargeSessionSampleSummary` do not expose Ah fields
- `TypicalChargeCurvePoint` carries only `averageEnergyWh`
- `ChargedDeviceSummary` capacity estimates are always in Wh

### Internal / hardware layer
- The USB meters (UM25C, UM34C, TC66C) report both a Wh counter (`recordedWH`) and an Ah counter (`recordedAH`) over Bluetooth
- `Meter.recordedAH` and `Meter.chargeRecordAH` exist as raw hardware counters and are used only internally — they are never surfaced in summaries or shown to users
- The CoreData schema retains `measuredChargeAh`, `meterChargeBaselineAh`, and `meterLastChargeAh` as legacy attributes (data already stored in existing records is preserved), but these attributes are no longer read into Swift model summaries

## Enforcement

When adding new features involving energy or capacity:
- Always use Wh as the unit
- Do not introduce new Ah-denominated properties in any public summary struct
- Do not display Ah or mAh strings in any view, label, or tooltip
- If a hardware counter comes in Ah (e.g., from a new meter protocol), store it as a private implementation detail and convert to energy only if an average voltage is reliably known