eventhub/docs/runtime-event-processing.md

# Runtime event processing

Runtime processing is now centered on **processing executions**. An execution loads canonical EventHub runtime events from selected sources, optionally partitions the event set, then runs a configured processing plan made of common EPL and/or Java modules.

The preferred endpoint is:

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

List available plans:

```http
GET /api/eventhub/runtime-processing/executions/plans
```

The older endpoint is still available for compatibility:

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

but it should be treated as a legacy profile adapter. New clients should use `processingPlanKey`, not `profileKey`.

## First predefined plan

The first predefined plan is:

```text
driver-working-time-v1
```

Legacy alias:

```text
tachograph-driver-esper-v1
```

This plan runs the source-neutral driver working-time chain over canonical runtime events. Tachograph file/database data is only one possible source of those canonical events. Its modules include:

```text
event-to-activity-intervals
event-to-vehicle-usage-intervals
vehicle-evidence-attachment
support-evidence-normalization
driving-derived-projections
```

The important design point is that runtime processing is not tachograph-specific. Tachograph is now treated as a source/compatibility layer; the working-time plan consumes canonical driver activity, vehicle usage, and support-evidence events from any supported source.

## Example execution

```json
{
  "processingPlanKey": "driver-working-time-v1",
  "sourceSelection": {
    "sessionIds": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"
    ],
    "sourceFamilies": ["TACHOGRAPH_FILE_SESSION", "YELLOWFOX_DB"],
    "occurredFrom": "2026-05-01T00:00:00Z",
    "occurredTo": "2026-05-31T23:59:59Z",
    "expandVehicleEvents": true
  },
  "partitioning": {
    "strategy": "DRIVER",
    "includeAllPartitions": true,
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "significantDrivingMinutes": 3,
    "minimumRestPeriodMinutes": 720,
    "includePartitionDebug": true
  }
}
```

## Conceptual flow

```text
source selection
 -> runtime event loaders
 -> canonical EventHub events
 -> partitioning
 -> vehicle evidence attachment
 -> support evidence normalization
 -> event-to-interval EPL modules
 -> driver working-time derived projection EPL/Java modules
 -> partition result map
```

## Why processing plans instead of profiles

A plan describes **which modules should run over a runtime event set**. This matches the EventHub goal better than domain-oriented profiles.

Future plans can reuse the same event-loading infrastructure:

```text
vehicle-trip-detection-v1
vehicle-stop-detection-v1
driver-settlement-v1
mixed-driver-vehicle-correlation-v1
telematics-poi-clustering-v1
```

Each plan may use different partitioning and modules, but the source loading and canonical event model remain common.

## Compatibility

Legacy profile endpoint:

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

with:

```json
{
  "profileKey": "tachograph-driver-esper-v1",
  "scope": {},
  "partitioning": {},
  "parameters": {}
}
```

internally delegates to:

```text
processingPlanKey = driver-working-time-v1
```

## Source-neutral driver working-time modules

The former tachograph-named processing artifacts are now represented by source-neutral driver working-time names:

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

Legacy tachograph names are kept as compatibility adapters for existing file-session endpoints and Postman requests. New runtime code should use the `driver-working-time-*` classes/resources and the `driver-working-time-v1` processing plan.

## Module execution results

`/api/eventhub/runtime-processing/executions` now exposes module execution metadata explicitly.

Top-level execution response includes:

```text
moduleResults
```

This map contains one entry per executed module. The top-level entries are intentionally sanitized: they expose status, warnings, and metadata without duplicating the full partition output payload.

Each partition result also includes:

```text
partitionResults[*].moduleResults
```

For `driver-working-time-v1`, the partition-level module results currently expose:

```text
vehicle-evidence-attachment
support-evidence-normalization
driving-derived-projections
```

The first implementation uses wrapper modules around the existing validated driver-working-time scope service. Logical phase modules such as `event-to-activity-intervals`, `event-to-vehicle-usage-intervals`, and `vehicle-usage-merge` are registered and executed as delegated modules so they can later be split into true standalone EPL/Java modules without changing the external processing-plan contract.

## First-class EPL modules

Runtime processing now supports modules implemented directly with Esper EPL through the common `RuntimeEplModuleExecutor`.

The first source-neutral EPL modules are:

| Module key | Engine | EPL resource | Output statement |
|---|---|---|---|
| `event-to-activity-intervals` | `EPL` | `esper/runtime-driver-activity-intervals.epl` | `driverActivityIntervals` |
| `event-to-vehicle-usage-intervals` | `EPL` | `esper/runtime-driver-vehicle-usage-intervals.epl` | `driverVehicleUsageIntervals` |

These modules operate on canonical EventHub runtime events, not on tachograph-specific source rows. They are currently used as first-class phase modules in `driver-working-time-v1`; the final `driving-derived-projections` module remains a compatibility adapter over the validated working-time projection service until the remaining projection stages are split into direct EPL modules.