eventhub/docs/runtime-event-processing.md

# Runtime Event Processing

Runtime Processing is now source-neutral. The API receives a runtime scope, selects a processing profile, partitions the normalized EventHub-style events, and delegates execution to the selected profile.

The tachograph Esper processing is no longer the root concept. It is one profile:

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

## Profile discovery endpoint

```http
GET /api/eventhub/runtime-processing/event-processing/profiles
```

Example response:

```json
[
  {
    "profileKey": "tachograph-driver-esper-v1",
    "displayName": "Tachograph Driver Esper Processing",
    "description": "Runs the shared tachograph driver Esper processing pipeline over Runtime Processing event scopes.",
    "defaultPartitioningStrategy": "DRIVER",
    "supportedPartitioningStrategies": ["DRIVER"],
    "requiredParameters": [],
    "optionalParameters": [
      "significantDrivingMinutes",
      "minimumRestPeriodMinutes",
      "attachVehicleOnlyEvents",
      "vehicleEvidencePaddingMinutes",
      "includePartitionDebug"
    ]
  }
]
```

Clients should prefer this endpoint instead of hardcoding profile metadata.

## Generic execution endpoint

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

## Request shape

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

## Response shape

```json
{
  "profileKey": "tachograph-driver-esper-v1",
  "partitioningStrategy": "DRIVER",
  "inputEventCount": 1234,
  "selectedPartitionCount": 2,
  "discoveredVehicleCount": 3,
  "partitionResults": {
    "12:12345678901234": {
      "partitionType": "DRIVER",
      "partitionKey": "12:12345678901234",
      "resultType": "UnifiedRuntimeDerivedProjectionResultDto",
      "result": {
        "projection": {
          "activityIntervals": [],
          "drivingIntervals": [],
          "drivingInterruptionIntervals": [],
          "dailyWeeklyRestCandidateIntervals": [],
          "dailyWeeklyRestCandidateCoverageIntervals": [],
          "unclassifiedDailyWeeklyRestCandidateCoverageIntervals": [],
          "potentialHomeOvernightStayIntervals": [],
          "potentialInVehicleOvernightStayIntervals": [],
          "potentialInVehicleTripIntervals": [],
          "vehicleUsageIntervals": [],
          "vuCardAbsentIntervals": [],
          "supportGeoEvents": []
        }
      }
    }
  },
  "notes": [],
  "warnings": []
}
```

## Concepts

### Scope

`scope` is the existing runtime selection model. It can select events from:

```text
TACHOGRAPH_FILE_SESSION
TACHOGRAPH_DB
YELLOWFOX_DB
```

and can use:

```text
SOURCE_DB
EVENTHUB_DB
```

where supported.

For uploaded tachograph files, the scope can use:

```text
sessionId
sessionIds
compositeSessionId
```

### Profile

A profile owns domain-specific processing semantics. It defines:

```text
profile key
expected partitioning strategy
profile-specific parameters
result type
```

Current profile:

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

Future profiles can include:

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

### Partitioning

The common API supports generic partitioning options:

```text
NONE
DRIVER
VEHICLE
DRIVER_VEHICLE
SOURCE_FAMILY
CUSTOM_PROFILE
```

The first tachograph profile currently supports `DRIVER` partitioning. The service partitions mixed event scopes in Java before invoking Esper so that existing single-driver EPL windows cannot mix driver states.

## Partition debug / audit output

For mixed-source scopes, request debug output when validating why events were or were not attached to a driver partition:

```json
{
  "partitioning": {
    "strategy": "DRIVER",
    "includeAllPartitions": true,
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "includePartitionDebug": true
  }
}
```

When enabled, each generic `partitionResults[*].metadata.partitionDebug` contains:

```text
directDriverEventCount
vehicleUsageIntervalCount
candidateVehicleEvidenceEventCount
attachedVehicleEvidenceEventCount
ignoredVehicleEvidenceEventCount
mergedEventCount
vehicleUsageIntervals
vehicleEvidenceDecisions
notes
warnings
```

`vehicleEvidenceDecisions` explains every relevant decision, for example:

```text
DIRECT_DRIVER_EVENT
ATTACHED_VEHICLE_EVIDENCE
IGNORED_NO_OVERLAPPING_VEHICLE_USAGE
IGNORED_ATTACHMENT_DISABLED
```

The compatibility response type also has `partitionDebugByDriver`; use the generic endpoint when you need to enable debug output explicitly. Keep debug disabled for high-volume production requests unless you need attribution diagnostics, because the decision list can be large.

## Compatibility endpoint

The old tachograph endpoint remains available:

```http
POST /api/eventhub/runtime-processing/tachograph/esper-processing
```

It now acts as a compatibility adapter for:

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

with:

```text
profileKey = tachograph-driver-esper-v1
partitioning.strategy = DRIVER
```

## Tachograph profile processing flow

```text
runtime event scope
 -> broad event assembly
 -> driver partition discovery
 -> for each driver:
      direct driver events
      reconstruct driver vehicle-usage intervals
      attach only vehicle-scoped events whose vehicle matches and whose timestamp falls inside a usage interval plus configured padding
      shared event-input Esper projection pipeline
 -> generic partitionResults map
```

The tachograph profile reuses the same `TachographEsperProcessingCore` used by the file-session endpoint. This prevents the file-session API and runtime-processing API from drifting into separate rule chains.
## Vehicle-only evidence attachment

For driver-partitioned profiles, vehicle-only events are no longer attached only by vehicle identity. They are attached to a driver partition only when there is temporal evidence:

```text
vehicle-only event.vehicleKey/registrationKey matches a reconstructed driver vehicle-usage interval
and event.occurredAt is inside [usage.from - padding, usage.to + padding]
```

This prevents unrelated vehicle events from being copied into a driver result simply because the driver used the same vehicle on another day. The tachograph profile currently uses:

```json
{
  "partitioning": {
    "attachVehicleEvidence": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includeDebug": true
  },
  "parameters": {
    "attachVehicleOnlyEvents": true,
    "vehicleEvidencePaddingMinutes": 15,
    "includePartitionDebug": true
  }
}
```

`parameters` take precedence in the tachograph profile. The compatibility endpoint maps these values to `expandVehicleEvents` and `vehicleExpansionPaddingMinutes`.