# Runtime driver working-time processing

Runtime driver working-time processing is a source-neutral processing plan over canonical EventHub events.

The preferred runtime execution endpoint is:

```http
POST /api/eventhub/runtime-processing/executions
```

Use:

```json
{
  "processingPlanKey": "driver-working-time-v1",
  "sourceSelection": {
    "tenantKey": "default",
    "driverKey": "12:12345678901234",
    "occurredFrom": "2026-05-01T00:00:00Z",
    "occurredTo": "2026-05-31T23:59:59Z",
    "sourceInputs": [
      {
        "sourceFamily": "TACHOGRAPH_FILE_SESSION",
        "eventBackend": "SOURCE_DB",
        "sessionIds": [
          "11111111-1111-1111-1111-111111111111",
          "22222222-2222-2222-2222-222222222222"
        ]
      },
      {
        "sourceFamily": "TACHOGRAPH_DB",
        "eventBackend": "EVENTHUB_DB"
      },
      {
        "sourceFamily": "YELLOWFOX_DB",
        "eventBackend": "SOURCE_DB"
      }
    ]
  }
}
```

Use `sourceInputs` when one runtime request must mix direct-source and EventHub-backed inputs. Keep `sourceFamilies + eventBackend` only for legacy same-backend scopes.

## Canonical input idea

The plan should work with events from any source once they are normalized into canonical EventHub event semantics:

```text
DRIVER_ACTIVITY START/END
DRIVER_CARD or DRIVER_VEHICLE_USAGE INSERT/WITHDRAW
POSITION / PLACE / BORDER_CROSSING / LOAD_UNLOAD / IGNITION / ODOMETER support evidence
```

Tachograph files and tachograph databases are only two possible sources. YellowFox and future telematics providers can contribute vehicle-only evidence that is attached to driver partitions by vehicle/time overlap.

## New source-neutral artifacts

```text
DriverWorkingTimeProcessingResultDto
DriverWorkingTimeProcessingCore
RuntimeDriverWorkingTimeScopeProcessingService
DriverWorkingTimeRuntimeProcessingPlan
runtime-driver-event-interval-preprocessor.epl
driver-working-time-derived-projections.epl
```

## Compatibility artifacts

The following names are kept only for backward compatibility with existing file-session APIs and older Postman calls:

```text
TachographEsperDriverProcessingResultDto
TachographEsperProcessingCore
UnifiedRuntimeTachographEsperScopeProcessingService
tachograph-driving-derived-projection-events-preprocessor.epl
tachograph-driving-derived-projection-bundle.epl
```

New runtime-processing code should use the driver-working-time names.

The common Esper contract is source-neutral as well:

```text
DriverWorkingTimeActivityPointInputEvent
DriverWorkingTimeVehicleUsagePointInputEvent
DriverWorkingTimeActivityIntervalInputEvent
DriverWorkingTimeVehicleUsageIntervalInputEvent
DriverWorkingTimeSupportEvidenceInputEvent
DriverWorkingTimeProjectionFinalizeEvent
DriverWorkingTimeVehicleUsageIntervalInputWindow
```

Tachograph-prefixed Esper types remain only inside the compatibility resources listed above.

## EPL-backed phase modules

The driver working-time plan now contains first-class EPL-backed phase modules for event-to-interval conversion:

```text
event-to-activity-intervals
  EventHub DRIVER_ACTIVITY START/END events
  -> DriverActivityIntervalEvent

 event-to-vehicle-usage-intervals
  EventHub DRIVER_CARD INSERT/WITHDRAW events
  -> DriverVehicleUsageIntervalEvent
```

The final derived projection module still delegates to the shared working-time projection service for parity with existing file-session processing. This lets us migrate the pipeline gradually: common event-to-interval conversion is now EPL-module based, while the larger rest/trip/overnight projection bundle remains compatibility-safe.