# Anatomy of a session

Beyond identity (`id`, `policyId`) and lifecycle (`state`, `pluggedInAt`, `pluggedOutAt`), a session is composed of five subsections: blocks, statistics, target, outcome, and error.

## Blocks

Discrete windows of active charging within a session. Use blocks to render a visual timeline of when the vehicle was (or will be) charging and when it was idle.

While `UPCOMING`, blocks are empty. While `ACTIVE`, blocks represent a mix of past charging and planned future charging — past blocks are final, future blocks are tentative and may shift as the schedule re-optimizes. While `SETTLED`, blocks are final and represent what actually happened.

Each block has a `type` (`BATTERY_RESERVE`, `REGULAR`, or `IMMEDIATE_START`), a `kwhSum` tracking the total energy delivered during that block, and time boundaries (`startAt`, `endAt`).

## Statistics

Charging data for the session. Use statistics to show how much energy was delivered, the battery level progression, and a charge rate chart.

`aggregated` provides session-level totals (total kWh, battery start/end percentages). It is `null` while `UPCOMING` and populated once `ACTIVE`.

`timeseries` is an array of 15-minute interval measurements spanning from plug-in to plug-out. During gaps between blocks, `kwh` is `0`. Use this to render a charge rate graph — the zeros make idle periods and block boundaries visible.

## Target

What the system is charging towards. Use the target to display the user's charging goal — the battery level they want and when they need it by.

`target.latest` is a discriminated union on `type`:

- A **`REGULAR`** target has a deadline (`readyBy`), a charge target (`minimumChargeTarget`), a battery reserve floor, and a `source` indicating whether it comes from the policy or a user override.
- An **`IMMEDIATE_START`** target has only a `minimumChargeTarget` — no deadline, no flexibility.

The target can change mid-session (e.g. the user triggers an immediate start override). `latest` always reflects the current state. When an override completes, the system reverts to the regular schedule target.

## Outcome

The system's assessment of whether the target will be (or was) met. Use the outcome to show the user whether they're on track — and if not, what the system expects will happen.

`outcome.latest` is `null` before the first estimate is available (always `null` while `UPCOMING`). Once `ACTIVE`, it matches the target type — use `type` to distinguish `REGULAR` from `IMMEDIATE_START` outcomes:

- A **`REGULAR`** outcome is a discriminated union on `state`: an `ON_TARGET` outcome has `batteryLevelAtReadyBy` and `minimumChargeTargetReachedAt` set to `null` (the target will be met, so projections are unnecessary); an `OFF_TARGET` outcome populates `batteryLevelAtReadyBy` with the estimated battery level at the deadline, and `minimumChargeTargetReachedAt` with the projected time the target will eventually be reached (or `null` if a projection is unavailable, for example if charging has failed to start).
- An **`IMMEDIATE_START`** outcome tracks when the target will be reached via `minimumChargeTargetReachedAt` (`null` when a projection is unavailable).

`outcome.latest.targetId` links back to the specific target being evaluated, so you can correlate the two.

## Error

Whether something has gone wrong with charge control. Use the error to surface actionable alerts to the user.

`error.latest` is `null` when there is no active error. Use `type` to identify the error kind: `START_FAIL` (charging failed to start), `STOP_FAIL` (charging failed to stop), or `MISSING_CAPABILITIES` (the vehicle is missing capabilities required for session management, such as charge state reporting or charge control — the `missingCapabilities` array lists exactly which ones). Errors resolve automatically — when the issue clears, `error.latest` returns to `null`.