# 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": {
    "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"
      }
    ],
    "expandVehicleEvents": true
  },
  "partitioning": {
    "strategy": "DRIVER",
    "includeAllPartitions": true,
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "significantDrivingMinutes": 3,
    "minimumRestPeriodMinutes": 720,
    "includePartitionDebug": true,
    "includePartitionMetadata": true,
    "includePartitionModuleResults": true,
    "includeExecutionModuleResults": true,
    "includeSupportEvidenceNormalization": true
  }
}
```

`sourceFamilies + eventBackend` is still accepted as a legacy shorthand when every selected family uses the same backend. Use `sourceInputs` when one runtime request must mix direct-source and EventHub-backed inputs.

## 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.

The active common EPL contracts use `DriverWorkingTime*InputEvent` and
`DriverWorkingTimeVehicleUsageIntervalInputWindow` names. Tachograph-prefixed Esper input
contracts are limited to legacy compatibility resources.

## 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.

## Response shaping

`driver-working-time-v1` supports a small set of optional request parameters to trim diagnostic payloads from `/api/eventhub/runtime-processing/executions` and the legacy `/api/eventhub/runtime-processing/event-processing` adapter.

All of these default to `true` to preserve current behavior:

```text
includeExecutionModuleResults
includePartitionMetadata
includePartitionModuleResults
includeSupportEvidenceNormalization
includePartitionDebug
```

Meaning:

- `includeExecutionModuleResults`: include top-level `moduleResults` on `/executions`
- `includePartitionMetadata`: include `partitionResults[*].metadata`
- `includePartitionModuleResults`: include `partitionResults[*].moduleResults`
- `includeSupportEvidenceNormalization`: include `supportEvidenceNormalization` in each partition result payload
- `includePartitionDebug`: include `partitionDebug` in each partition result payload

Example slim response request:

```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"
        ]
      }
    ]
  },
  "partitioning": {
    "strategy": "DRIVER"
  },
  "parameters": {
    "includeExecutionModuleResults": false,
    "includePartitionMetadata": false,
    "includePartitionModuleResults": false,
    "includeSupportEvidenceNormalization": false,
    "includePartitionDebug": false
  }
}
```