# Runtime-derived tachograph projections

Runtime Processing now exposes the tachograph driving-derived Esper bundle through the unified runtime event assembly layer.

## Endpoint

```http
POST /api/eventhub/runtime-processing/driver-derived-projections
```

The request body uses the same selector fields as the existing runtime endpoints:

- `sessionId` for one uploaded tachograph file session
- `sessionIds` for multiple uploaded tachograph file sessions
- `compositeSessionId` for an existing tachograph composite session
- `tenantKey` + driver selector for tachograph DB / YellowFox DB runtime sources
- `eventBackend` with `SOURCE_DB` or `EVENTHUB_DB` where supported
- `sourceFamilies`, for example `TACHOGRAPH_FILE_SESSION`, `TACHOGRAPH_DB`, `YELLOWFOX_DB`
- `driverKey`, `driverSourceEntityId`, `driverCardNation`, `driverCardNumber`
- `occurredFrom`, `occurredTo`
- `expandVehicleEvents`
- `vehicleExpansionPaddingMinutes`

Additional Esper thresholds are optional:

- `significantDrivingMinutes`
- `minimumRestPeriodMinutes`

When omitted, the defaults are read from:

```yaml
eventhub:
  tachograph-file-session:
    processing:
      significant-driving-minutes: 3
      minimum-rest-period-minutes: 720
```

## Flow

```text
runtime request
  -> UnifiedRuntimeEventAssemblyService
  -> driver seed events
  -> discovered vehicles
  -> optional vehicle-expanded events
  -> merged runtime event stream
  -> UnifiedEventTimelineReconstructor
  -> DriverTimelineReusableProjectionBuilder.buildEsperDrivingDerivedProjectionBundleFromEvents(...)
  -> TachographEsperDriverProcessingResultDto
```

The derived part always uses the event-input Esper path. This means the runtime stream is passed as point events to Esper, where activity and card-vehicle-usage intervals are paired and vehicle-usage intervals are merged before the existing driving-derived rules run.

## Example: composite tachograph file session

```json
{
  "compositeSessionId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "sourceFamilies": ["TACHOGRAPH_FILE_SESSION"],
  "driverKey": "12:12345678901234",
  "occurredFrom": "2026-05-01T00:00:00Z",
  "occurredTo": "2026-05-31T23:59:59Z",
  "expandVehicleEvents": true,
  "vehicleExpansionPaddingMinutes": 15,
  "significantDrivingMinutes": 3,
  "minimumRestPeriodMinutes": 720
}
```

## Response

The response contains runtime assembly metadata and the tachograph Esper result:

```text
request
driverSeedEventCount
discoveredVehicleCount
expandedVehicleEventCount
mergedEventCount
discoveredVehicles
projection
notes
```

`projection` is the same high-level structure returned by the tachograph file-session Esper endpoint, including:

- activity interval count/list
- driving interval count/list
- driving interruption intervals
- daily/weekly rest candidate intervals
- daily/weekly rest candidate coverage intervals
- unclassified rest candidate coverage intervals
- potential home overnight stays
- potential in-vehicle overnight stays
- potential in-vehicle trips
- vehicle usage intervals
- VU card absent intervals
- support geo events

## Boundary note

Runtime processing works with point events. If `occurredFrom`/`occurredTo` cuts through a source interval, the matching START/END or INSERT/WITHDRAW point may be outside the selected window. For evaluations near boundaries, request a wider event window or use vehicle expansion padding so Esper receives enough point events to reconstruct the interval.