// Register an augmentation function in this handler
public void registerAugmentationFunction(AugmentationFunction augmentationFunction)
    throws AugmentationFunctionException

// Unregister a registered function by its id
public void unRegisterAugmentationFunction(String augmentationFunctionId)
    throws AugmentationFunctionException

// Retrieve a single registered function by its id
public Optional<AugmentationFunction> getAugmentationFunction(String augmentationFunctionId)

// Retrieve all registered functions
public List<AugmentationFunction> getAllAugmentationFunctions()

// Called after a function is added to the handler's internal map
protected abstract void handleAugmentationFunctionRegistration(AugmentationFunction function)
    throws AugmentationFunctionException;

// Called after a function is removed from the handler's internal map
protected abstract void handleAugmentationFunctionUnRegistration(String augmentationFunctionId)
    throws AugmentationFunctionException;

// Called to start a stateful function — should invoke function.start(request)
protected abstract void handleAugmentationFunctionStart(StatefulAugmentationFunction function,
                                                        AugmentationFunctionRequest request)
    throws AugmentationFunctionException;

// Called to stop a running stateful function — should invoke function.stop(request)
protected abstract void handleAugmentationFunctionStop(StatefulAugmentationFunction function,
                                                       AugmentationFunctionRequest request)
    throws AugmentationFunctionException;

// Called to execute a stateless function — should invoke function.run(request) and return results
protected abstract List<AugmentationFunctionResult<?>> handleAugmentationFunctionExecution(
    StatelessAugmentationFunction function, AugmentationFunctionRequest request)
    throws AugmentationFunctionException;

// Called to deliver a refreshed query result to a running stateful function
protected abstract void handleAugmentationFunctionQueryResultRefresh(
    StatefulAugmentationFunction function, QueryRequest queryRequest, QueryResult<?> queryResult)
    throws AugmentationFunctionException;

// Create a handler with a unique ID
DefaultAugmentationFunctionHandler handler = new DefaultAugmentationFunctionHandler("my-handler-id");

// Register one or more augmentation functions
handler.registerAugmentationFunction(new MyStatelessFunction());
handler.registerAugmentationFunction(new MyStatefulFunction());

// Add the handler to the AugmentationManager
augmentationManager.addAugmentationFunctionHandler(handler);

public interface AugmentationLifeCycleListener {
    void onCreate();
    void onStart();
    void onDigitalTwinBound();
    void onDigitalTwinUnBound();
    void onSync(DigitalTwinState digitalTwinState);
    void onUnSync(DigitalTwinState digitalTwinState);
    void onStop();
    void onDestroy();
}

public interface StatelessAugmentationListener {

    void onStatelessAugmentationFunctionError(String augmentationFunctionId,
                                              AugmentationFunctionError augmentationFunctionError);
}

public interface StatefulAugmentationListener {

    // Called when the stateful function produces new results
    void onStatefulAugmentationFunctionResult(String augmentationFunctionId,
                                              List<AugmentationFunctionResult<?>> resultList);

    // Called when the stateful function encounters an error
    void onStatefulAugmentationFunctionError(String augmentationFunctionId,
                                             AugmentationFunctionError augmentationFunctionError);

    // Called when the stateful function requests a query result refresh from DT storage
    void onStatefulAugmentationFunctionQueryResultRefresh(String augmentationFunctionId,
                                                         QueryRequest queryRequest);
}

// Add a handler (before or after the DT is started)
public void addAugmentationFunctionHandler(AugmentationFunctionHandler handler)
    throws AugmentationFunctionException, WldtWorkerException

// Remove a handler by its id
public void removeAugmentationFunctionHandler(String handlerId)
    throws AugmentationFunctionException

// Retrieve the map of all registered handlers (id → handler)
public Map<String, AugmentationFunctionHandler> getAugmentationFunctionHandlerMap()

DigitalTwin digitalTwin = new DigitalTwin("my-dt-id", new MyDigitalTwinModel());

AugmentationManager augmentationManager = digitalTwin.getAugmentationManager();

// Remove a specific function from its handler
handler.unRegisterAugmentationFunction(MyStatelessFunction.FUNCTION_ID);

// Remove a handler and all its functions
augmentationManager.removeAugmentationFunctionHandler("sensor-handler");

// Retrieve a specific handler by id
Optional<AugmentationFunctionHandler> h =
    augmentationManager.getAugmentationFunctionHandler("sensor-handler");

// Retrieve all registered handlers
List<AugmentationFunctionHandler> allHandlers =
    augmentationManager.getAllAugmentationFunctionHandlers();

// Find a function by id across all handlers (returns a map handlerId → function)
Map<String, AugmentationFunction> found =
    augmentationManager.getAugmentationFunctionWithId(MyStatelessFunction.FUNCTION_ID);

// Retrieve a function from a specific handler
Optional<AugmentationFunction> fn =
    handler.getAugmentationFunction(MyStatelessFunction.FUNCTION_ID);

// Retrieve all functions registered on a handler
List<AugmentationFunction> allFunctions = handler.getAllAugmentationFunctions();

public class AugmentationFunctionContext {
    private DigitalTwinState digitalTwinState;
    private QueryResult<?> queryResult;
}

// Default constructor
public AugmentationFunctionContext()

// Constructor with state only
public AugmentationFunctionContext(DigitalTwinState digitalTwinState)

// Constructor with state and query results
public AugmentationFunctionContext(DigitalTwinState digitalTwinState, QueryResult<?> queryResult)

public class AugmentationFunctionContextRequest {
    private boolean observeState;
    private boolean observeEventNotifications;
    private List<String> propertyNameFilter;
    private List<String> eventNameFilter;
    private List<String> relationshipNameFilter;
    private QueryRequest queryRequest;
}

// Default constructor: observes state and events, no query
public AugmentationFunctionContextRequest()

// Constructor with query only
public AugmentationFunctionContextRequest(QueryRequest queryRequest)

// Constructor with observation flags and query
public AugmentationFunctionContextRequest(boolean observeState,
                                         boolean observeEventNotifications,
                                         QueryRequest queryRequest)

// Stateless function that needs the last 10 minutes of DT state history
public class HistoryAwareStatelessFunction extends StatelessAugmentationFunction {

    public HistoryAwareStatelessFunction() {
        // ⚠️ Warning: timestamps are computed once at construction time and stay fixed.
        // For a truly sliding "last 10 minutes" window, build the QueryRequest inside run()
        // and pass it to refreshQueryResult(QueryRequest) at each invocation instead.
        super("history-fn", "History Function", "Uses DT state history", "1.0.0",
              new AugmentationFunctionContextRequest(
                  new QueryRequest()
                      .setResourceType(QueryResourceType.DIGITAL_TWIN_STATE)
                      .setRequestType(QueryRequestType.TIME_RANGE)
                      .setStartTimestampMs(System.currentTimeMillis() - 600_000)
                      .setEndTimestampMs(System.currentTimeMillis())
              ));
    }

    @Override
    protected List<AugmentationFunctionResult<?>> run(AugmentationFunctionRequest request)
            throws AugmentationFunctionException {
        QueryResult<?> history = request.getContext().getQueryResult();
        // use history ...
        return Collections.emptyList();
    }
}

// Stateful function that only observes state changes (no event notifications needed)
public class StateOnlyStatefulFunction extends StatefulAugmentationFunction {

    public StateOnlyStatefulFunction() {
        super("state-only-fn", "State Only Function", "Observes state only", "1.0.0",
              new AugmentationFunctionContextRequest(true, false, null));
    }
    // ...
}

public class AugmentationFunctionRequest {
    private final String requestId;
    private final AugmentationFunctionContext context;
    private final AugmentationFunctionRequestType type;
    private final Long timestamp;
}

// Full constructor with explicit timestamp
public AugmentationFunctionRequest(String requestId,
                                   AugmentationFunctionContext context,
                                   AugmentationFunctionRequestType requestType,
                                   Long timestamp)

// Constructor with automatic timestamp (timestamp = now)
public AugmentationFunctionRequest(String requestId,
                                   AugmentationFunctionContext context,
                                   AugmentationFunctionRequestType requestType)

@Override
public List<AugmentationFunctionResult<?>> run(AugmentationFunctionRequest request)
        throws AugmentationFunctionException {

    // Retrieve the request type
    AugmentationFunctionRequestType type = request.getType(); // EXECUTE

    // Retrieve the context from the request
    AugmentationFunctionContext context = request.getContext();

    // Access the current DT state
    DigitalTwinState state = context.getDigitalTwinState();

    // Access optional query results from DT storage
    QueryResult<?> queryResult = context.getQueryResult();

    // ...
}

public enum AugmentationFunctionRequestType {
    EXECUTE,   // Stateless function execution request
    START,     // Stateful function start request
    STOP       // Stateful function stop request
}

public class StatelessPredictionFunction extends StatelessAugmentationFunction {
    
    @Override
    public List<AugmentationFunctionResult<?>> run(AugmentationFunctionRequest request) 
            throws AugmentationFunctionException {
        // Context used once per execution
        DigitalTwinState currentState = request.getContext().getDigitalTwinState();
        QueryResult<?> history = request.getContext().getQueryResult();
        
        // Perform prediction using current state and history
        // Return results
    }
}

public class StatefulAnomalyDetector extends StatefulAugmentationFunction {
    
    private List<Double> temperatureHistory = new ArrayList<>();
    
    @Override
    public void start(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        // Receive initial context at startup
        DigitalTwinState initialState = request.getContext().getDigitalTwinState();
        
        // Initialize with current temperature
        initialState.getProperty("temperature")
            .ifPresent(p -> temperatureHistory.add((Double) p.getValue()));
        
        logger.info("Started with initial temperature: {}", temperatureHistory.get(0));
    }
    
    @Override
    public void onStateUpdate(DigitalTwinState newState) {
        // Automatically receive state updates (no explicit context request needed)
        newState.getProperty("temperature")
            .ifPresent(p -> {
                double temp = (Double) p.getValue();
                temperatureHistory.add(temp);
                
                // Detect anomaly
                if (isAnomaly(temp)) {
                    notifyResult(createAnomalyResult(temp));
                }
            });
    }
    
    @Override
    public void stop(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        logger.info("Stopped after processing {} temperature readings", 
                    temperatureHistory.size());
    }
}

public class StatefulPollingAugmentationFunction extends StatefulAugmentationFunction {

    public static final String FUNCTION_ID = "polling-augmentation-function";
    private static final long POLLING_INTERVAL_MS = 5000;

    private Timer pollingTimer;

    public StatefulPollingAugmentationFunction() {
        super(FUNCTION_ID,
              "Polling Augmentation Function",
              "Periodically queries DT storage for the last 60 seconds of state history",
              "1.0.0",
              // ⚠️ Warning: timestamps below are fixed at construction time.
              // This sets the initial query range. To slide the window at each polling cycle,
              // call refreshQueryResult(new QueryRequest()...) with fresh timestamps inside the TimerTask.
              new AugmentationFunctionContextRequest(
                  new QueryRequest()
                      .setResourceType(QueryResourceType.DIGITAL_TWIN_STATE)
                      .setRequestType(QueryRequestType.TIME_RANGE)
                      .setStartTimestampMs(System.currentTimeMillis() - 60_000)
                      .setEndTimestampMs(System.currentTimeMillis())
              ));
    }

    @Override
    public void start(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        logger.info("Starting polling function, interval: {} ms", POLLING_INTERVAL_MS);

        pollingTimer = new Timer(true);
        pollingTimer.scheduleAtFixedRate(new TimerTask() {
            @Override
            public void run() {
                // Request a fresh query result from DT storage using the context request's QueryRequest
                refreshQueryResult();
            }
        }, 0, POLLING_INTERVAL_MS);
    }

    @Override
    public void onQueryResultRefresh(QueryRequest queryRequest, QueryResult<?> queryResult)
            throws AugmentationFunctionException {
        if (queryResult == null || queryResult.isEmpty()) {
            return;
        }

        // Process the refreshed historical data
        logger.debug("Received query refresh with {} records", queryResult.size());

        // Compute result from the historical snapshot
        AugmentationFunctionResult<Integer> result = new AugmentationFunctionResult<>(
                AugmentationFunctionResultType.GENERIC_RESULT,
                "history_record_count",
                queryResult.size(),
                null,
                Map.of("query_timestamp", System.currentTimeMillis())
        );

        notifyResult(Collections.singletonList(result));
    }

    @Override
    public void stop(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        if (pollingTimer != null) {
            pollingTimer.cancel();
            pollingTimer = null;
        }
        logger.info("Polling function stopped");
    }

    @Override
    public void onStateUpdate(DigitalTwinState digitalTwinState) {
        // Not used in pure polling mode — data is retrieved via scheduled refreshQueryResult()
    }

    @Override
    public void onEventNotificationReceived(DigitalTwinStateEventNotification<?> notification) {
        // Not used in pure polling mode
    }
}

protected void onAugmentationNewFunctionAvailable(String handlerId, 
                                                  AugmentationFunction augmentationFunction)

protected void onAugmentationFunctionUnAvailable(String handlerId, 
                                                 AugmentationFunction augmentationFunction)

protected void onAugmentationFunctionListAvailable(String handlerId, 
                                                   List<AugmentationFunction> augmentationFunctionList)

@Override
protected void onAugmentationNewFunctionAvailable(String handlerId,
                                                  AugmentationFunction augmentationFunction) {
    logger.info("New augmentation function available: {} from handler: {}",
                augmentationFunction.getId(),
                handlerId);

    // Custom logic: auto-start stateful functions
    if (augmentationFunction.getType() == AugmentationFunctionType.STATEFUL) {
        try {
            this.startAugmentationFunction(augmentationFunction.getId());
        } catch (Exception e) {
            logger.error("Failed to start stateful function", e);
        }
    }
}

// Search across all handlers for the function with the given id
protected void executeAugmentationFunction(String augmentationFunctionId)
    throws EventBusException, AugmentationFunctionException

// Same, but with a custom request id for traceability
protected void executeAugmentationFunction(String augmentationFunctionId,
                                           String augmentationFunctionRequestId)
    throws EventBusException, AugmentationFunctionException

// Target a specific handler explicitly
protected void executeAugmentationFunction(String augmentationFunctionHandlerId,
                                           String augmentationFunctionId,
                                           String augmentationFunctionRequestId)
    throws EventBusException, AugmentationFunctionException

// Search across all handlers
protected void startAugmentationFunction(String augmentationFunctionId)
    throws EventBusException, AugmentationFunctionException

// Same, but with a custom request id
protected void startAugmentationFunction(String augmentationFunctionId,
                                         String augmentationFunctionRequestId)
    throws EventBusException, AugmentationFunctionException

// Target a specific handler explicitly
protected void startAugmentationFunction(String augmentationFunctionHandlerId,
                                         String augmentationFunctionId,
                                         String augmentationFunctionRequestId)
    throws EventBusException, AugmentationFunctionException

// Search across all handlers
protected void stopAugmentationFunction(String augmentationFunctionId)
    throws EventBusException, AugmentationFunctionException

// Same, but with a custom request id
protected void stopAugmentationFunction(String augmentationFunctionId,
                                        String augmentationFunctionRequestId)
    throws EventBusException, AugmentationFunctionException

// Target a specific handler explicitly
protected void stopAugmentationFunction(String augmentationFunctionHandlerId,
                                        String augmentationFunctionId,
                                        String augmentationFunctionRequestId)
    throws EventBusException, AugmentationFunctionException

@Override
protected void onPhysicalAssetPropertyVariation(PhysicalAssetPropertyWldtEvent<?> physicalPropertyEventMessage) {
    try {

        // Implementation of the management of a new Physical Event in the Digital Twin Model
        //[...]
        
        // Execute augmentation function for each received physical event notification
        this.executeAugmentationFunction(RandomNumberAugmentationFunction.FUNCTION_ID);
        
    } catch (Exception e) {
        e.printStackTrace();
    }
}

@Override
protected void onDigitalTwinBound(Map<String, PhysicalAssetDescription> adaptersPhysicalAssetDescriptionMap) {
    try {
        
        // Implementation of the binding phase in the Model
        //[...]
        
        // Start stateful augmentation function after DT initialization
        this.startAugmentationFunction(
            StatefulPeriodicRandomNumberAugmentationFunction.FUNCTION_ID
        );
        
    } catch (Exception e) {
        e.printStackTrace();
    }
}

@Override
protected void onDigitalTwinUnBound(Map<String, PhysicalAssetDescription> adaptersPhysicalAssetDescriptionMap,
                                    String errorMessage) {
    try {
        this.stopAugmentationFunction(StatefulPeriodicRandomNumberAugmentationFunction.FUNCTION_ID);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

public class AugmentationFunctionResult<T> {
    private AugmentationFunctionResultType type;
    private String key;
    private T value;
    private AugmentationFunctionResultMetrics augmentationFunctionResultMetrics;
    private Map<String, Object> metadata;
    private AugmentationFunctionRequest request;
    private final Long timestamp;
}

public enum AugmentationFunctionResultType {
    PROPERTY_RESULT,
    EVENT_RESULT,
    RELATIONSHIP_RESULT,
    RELATIONSHIP_INSTANCE_RESULT,
    GENERIC_RESULT
}

public class AugmentationFunctionResultMetrics {
    private Long totalExecutionTimeMs;
    private Long startTimestamp;
    private Long endTimestamp;
    private Integer recordsProcessed;
    private Integer recordsGenerated;
    private String executionId;
    private String nodeId;
}

// Provide total execution time directly (throws AugmentationFunctionException if null or negative)
public AugmentationFunctionResultMetrics(Long totalExecutionTimeMs)
    throws AugmentationFunctionException

// Provide start and end timestamps; total time is auto-calculated
// (throws AugmentationFunctionException if timestamps are null or end < start)
public AugmentationFunctionResultMetrics(Long startTimestamp, Long endTimestamp)
    throws AugmentationFunctionException

long start = System.currentTimeMillis();

// ... perform computation ...

long end = System.currentTimeMillis();

AugmentationFunctionResultMetrics metrics = new AugmentationFunctionResultMetrics(start, end);
metrics.setRecordsProcessed(1440);
metrics.setRecordsGenerated(1);
metrics.setExecutionId(UUID.randomUUID().toString());

AugmentationFunctionResult<Double> result = new AugmentationFunctionResult<>(
    AugmentationFunctionResultType.PROPERTY_RESULT,
    "predicted_value",
    85.5,
    metrics,   // ← attach metrics
    null
);

public AugmentationFunctionResult(AugmentationFunctionResultType type,
                                  String key,
                                  T value,
                                  AugmentationFunctionResultMetrics augmentationFunctionResultMetrics,
                                  Map<String, Object> metadata)

  List<AugmentationFunctionResult<?>> results = new ArrayList<>();
  
  // Result 1: Predicted failure probability as property
  results.add(new AugmentationFunctionResult<>(
      AugmentationFunctionResultType.PROPERTY_RESULT,
      "predicted_failure_probability",
      0.78,
      null,
      Map.of("confidence", 0.92, "horizon_hours", 48)
  ));
  
  // Result 2: Maintenance recommendation as event
  results.add(new AugmentationFunctionResult<>(
      AugmentationFunctionResultType.EVENT_RESULT,
      "maintenance_required",
      Map.of("urgency", "HIGH", "estimated_hours", 48),
      null,
      Map.of("timestamp", System.currentTimeMillis())
  ));
  
  // Result 3: Generic analytics
  results.add(new AugmentationFunctionResult<>(
      AugmentationFunctionResultType.GENERIC_RESULT,
      "degradation_analysis",
      Map.of("trend", "increasing", "rate", 0.05),
      null,
      Map.of("samples_analyzed", 1000)
  ));

protected void onAugmentationFunctionResultEvent(String augmentationFunctionHandlerId,
                                                 String augmentationFunctionId,
                                                 List<AugmentationFunctionResult<?>> augmentationFunctionResult)

@Override
protected void onAugmentationFunctionResultEvent(String augmentationFunctionHandlerId,
                                                 String augmentationFunctionId,
                                                 List<AugmentationFunctionResult<?>> augmentationFunctionResult) {
    
    logger.info("Received {} results from function: {} (handler: {})",
                augmentationFunctionResult.size(),
                augmentationFunctionId,
                augmentationFunctionHandlerId);
    
    // Iterate over the augmentation function results
    for(AugmentationFunctionResult<?> result : augmentationFunctionResult) {
        logger.info("Processing result: {}", result);
        
        // Process based on result type
        switch (result.getType()) {
            case PROPERTY_RESULT:
                handlePropertyResult(result);
                break;
            case EVENT_RESULT:
                handleEventResult(result);
                break;
            case RELATIONSHIP_RESULT:
                handleRelationshipResult(result);
                break;
            case RELATIONSHIP_INSTANCE_RESULT:
                handleRelationshipInstanceResult(result);
                break;
            case GENERIC_RESULT:
                handleGenericResult(result);
                break;
        }
    }
}

AugmentationFunctionResult<Double> result = new AugmentationFunctionResult<>(
    AugmentationFunctionResultType.PROPERTY_RESULT,
    "predicted_temperature",
    85.5,
    null,
    Map.of(
        "confidence", 0.92,
        "horizon_minutes", 10,
        "timestamp", System.currentTimeMillis()
    )
);

AugmentationFunctionResult<Map<String, Object>> result = new AugmentationFunctionResult<>(
    AugmentationFunctionResultType.EVENT_RESULT,
    "temperature_anomaly_detected",
    Map.of(
        "anomaly", true,
        "severity", "HIGH",
        "temperature", 95.0,
        "threshold", 50.0
    ),
    null,
    Map.of(
        "detector_version", "1.2.3",
        "detection_time", System.currentTimeMillis()
    )
);

AugmentationFunctionResult<Map<String, Object>> result = new AugmentationFunctionResult<>(
    AugmentationFunctionResultType.RELATIONSHIP_RESULT,
    "energySuppliedBy",
    Map.of(
        "description", "Indicates energy supply relationship",
        "bidirectional", false
    ),
    null,
    Map.of(
        "discovered_at", System.currentTimeMillis(),
        "discovery_method", "network_topology_analysis"
    )
);

AugmentationFunctionResult<String> result = new AugmentationFunctionResult<>(
    AugmentationFunctionResultType.RELATIONSHIP_INSTANCE_RESULT,
    "connectedTo",
    "machine-002-dt-id",
    null,
    Map.of(
        "discovered_at", System.currentTimeMillis(),
        "confidence", 0.95,
        "connection_type", "physical"
    )
);

AugmentationFunctionResult<Map<String, Object>> result = new AugmentationFunctionResult<>(
    AugmentationFunctionResultType.GENERIC_RESULT,
    "performance_analysis",
    Map.of(
        "efficiency", 0.78,
        "uptime_percentage", 99.2,
        "energy_consumption_kwh", 150.5,
        "recommendation", "Schedule maintenance within 48 hours"
    ),
    null,
    Map.of(
        "analysis_period_hours", 24,
        "samples_analyzed", 1440
    )
);

public enum AugmentationFunctionErrorType {
    INFO,       // Informational messages, not necessarily problems
    WARNING,    // Non-blocking conditions that may require attention
    ERROR,      // Recoverable errors during function execution
    CRITICAL    // Critical failures that may compromise function operation
}

public class AugmentationFunctionError {
    private final String errorId;
    private final Long timestamp;
    private String augmentationFunctionRequestId;
    private final AugmentationFunctionErrorType errorType;
    private final String message;
    private HashMap<String, Object> metadata;
}

// Constructor with error type and message (timestamp = now, empty metadata)
public AugmentationFunctionError(AugmentationFunctionErrorType errorType, String message)

// Constructor with error type, message and explicit timestamp
public AugmentationFunctionError(AugmentationFunctionErrorType errorType, String message, Long timestamp)

// Full constructor with error type, message, timestamp and metadata
public AugmentationFunctionError(AugmentationFunctionErrorType errorType,
                                 String message,
                                 Long timestamp,
                                 HashMap<String, Object> metadata)

public class MyStatelessFunction extends StatelessAugmentationFunction {

    @Override
    protected List<AugmentationFunctionResult<?>> run(AugmentationFunctionRequest request)
            throws AugmentationFunctionException {

        try {
            // ... computation ...
        } catch (Exception e) {
            // Report a non-fatal warning — execution continues
            notifyError(new AugmentationFunctionError(
                AugmentationFunctionErrorType.WARNING,
                "Failed to retrieve sensor data: " + e.getMessage()
            ));
        }

        return Collections.emptyList();
    }
}

public class MyStatefulFunction extends StatefulAugmentationFunction {

    @Override
    public void onStateUpdate(DigitalTwinState digitalTwinState)
            throws AugmentationFunctionException {

        try {
            // ... stateful computation ...
        } catch (Exception e) {
            // Report a critical error with additional metadata
            HashMap<String, Object> meta = new HashMap<>();
            meta.put("state_snapshot", digitalTwinState.toString());

            notifyError(new AugmentationFunctionError(
                AugmentationFunctionErrorType.CRITICAL,
                "State processing failed: " + e.getMessage(),
                System.currentTimeMillis(),
                meta
            ));
        }
    }

    // ...
}

public abstract class AugmentationFunction {
    private String id;
    private String name;
    private String description;
    private String version;
    private AugmentationFunctionType type;
    private AugmentationFunctionContextRequest contextRequest;
}

// Full constructor — used internally by subclass constructors
public AugmentationFunction(String id, String name, String description, String version,
                            AugmentationFunctionType type,
                            AugmentationFunctionContextRequest contextRequest)

// Minimal constructor — description and version default to null
public AugmentationFunction(String id, String name, AugmentationFunctionType type)

public enum AugmentationFunctionType {
    STATELESS,  // Single-shot execution, no persistent internal state
    STATEFUL    // Continuous lifecycle, maintains internal state
}

public abstract class StatelessAugmentationFunction extends AugmentationFunction {

    // Default constructor — uses a default context request (observes state and events, no query)
    protected StatelessAugmentationFunction(String id,
                                            String name,
                                            String description,
                                            String version) {
        super(id, name, description, version, AugmentationFunctionType.STATELESS, new AugmentationFunctionContextRequest());
    }

    // Constructor with custom context request — use when the function needs a specific
    // AugmentationFunctionContextRequest (e.g. to include a storage QueryRequest or to
    // disable state/event observation)
    protected StatelessAugmentationFunction(String id,
                                            String name,
                                            String description,
                                            String version,
                                            AugmentationFunctionContextRequest contextRequest) {
        super(id, name, description, version, AugmentationFunctionType.STATELESS, contextRequest);
    }
    
    /**
     * Main execution method that must be implemented by concrete functions.
     * Called each time the function is invoked.
     * 
     * @param request The augmentation function request containing context (DT state, query results) and metadata
     * @return List of augmentation function results
     * @throws AugmentationFunctionException if execution fails
     */
    protected abstract List<AugmentationFunctionResult<?>> run(AugmentationFunctionRequest request) 
        throws AugmentationFunctionException;
}

public abstract class StatefulAugmentationFunction extends AugmentationFunction {

    // Default constructor — uses a default context request (observes state and events, no query)
    protected StatefulAugmentationFunction(String id,
                                           String name,
                                           String description,
                                           String version) {
        super(id, name, description, version, AugmentationFunctionType.STATEFUL, new AugmentationFunctionContextRequest());
    }

    // Constructor with custom context request — use when the function needs a specific
    // AugmentationFunctionContextRequest (e.g. to include a storage QueryRequest or to
    // disable state/event observation)
    protected StatefulAugmentationFunction(String id,
                                           String name,
                                           String description,
                                           String version,
                                           AugmentationFunctionContextRequest contextRequest) {
        super(id, name, description, version, AugmentationFunctionType.STATEFUL, contextRequest);
    }

    /**
     * Called when the function is started. Initialize internal state and resources here.
     *
     * @param request The augmentation function request containing the initial context
     * @throws AugmentationFunctionException if initialization fails
     */
    protected abstract void start(AugmentationFunctionRequest request)
        throws AugmentationFunctionException;

    /**
     * Called when the function is stopped. Clean up resources here.
     *
     * @param request The augmentation function request containing the final context
     * @throws AugmentationFunctionException if cleanup fails
     */
    protected abstract void stop(AugmentationFunctionRequest request)
        throws AugmentationFunctionException;

    /**
     * Called automatically when the Digital Twin state is updated.
     *
     * @param digitalTwinState The new Digital Twin state
     * @throws AugmentationFunctionException if processing fails
     */
    public abstract void onStateUpdate(DigitalTwinState digitalTwinState)
        throws AugmentationFunctionException;

    /**
     * Called automatically when a Digital Twin event is notified.
     *
     * @param digitalTwinStateEventNotification The event notification
     * @throws AugmentationFunctionException if processing fails
     */
    public abstract void onEventNotificationReceived(DigitalTwinStateEventNotification<?> digitalTwinStateEventNotification)
        throws AugmentationFunctionException;

    /**
     * Called when a refreshed query result becomes available from the DT storage.
     * Invoked only after the function has explicitly requested a refresh via refreshQueryResult().
     * Override this method only when using the polling pattern; the default implementation is a no-op.
     *
     * @param queryRequest The query request whose result was refreshed
     * @param queryResult  The new query result
     * @throws AugmentationFunctionException if processing fails
     */
    public void onQueryResultRefresh(QueryRequest queryRequest, QueryResult<?> queryResult)
        throws AugmentationFunctionException {
        // default no-op — override when using the polling pattern
    }

    /**
     * Request a refresh of the query result from the DT storage.
     * Uses the QueryRequest defined in AugmentationFunctionContextRequest.
     * The refreshed result is delivered asynchronously via onQueryResultRefresh().
     * Provided by the framework — call this method from your implementation, do not override it.
     */
    protected final void refreshQueryResult() { /* provided by the framework */ }

    /**
     * Request a refresh of the query result using a custom QueryRequest.
     * The refreshed result is delivered asynchronously via onQueryResultRefresh().
     * Provided by the framework — call this method from your implementation, do not override it.
     *
     * @param queryRequest The custom query request to execute
     */
    protected final void refreshQueryResult(QueryRequest queryRequest) { /* provided by the framework */ }

    /**
     * Notify results asynchronously to the Augmentation Manager.
     * Call this method whenever the function produces results.
     * Provided by the framework — call this method from your implementation, do not override it.
     *
     * @param results List of augmentation function results to publish
     */
    protected final void notifyResult(List<AugmentationFunctionResult<?>> results) { /* provided by the framework */ }

    /**
     * Notify an error to the Augmentation Manager.
     * The current request ID is attached automatically.
     * Provided by the framework — call this method from your implementation, do not override it.
     *
     * @param augmentationFunctionError The error to report
     */
    protected final void notifyError(AugmentationFunctionError augmentationFunctionError) { /* provided by the framework */ }
}

public class RandomNumberAugmentationFunction extends StatelessAugmentationFunction {

    public static final String FUNCTION_ID = "random-number-augmentation-function";

    public RandomNumberAugmentationFunction() {
        super(FUNCTION_ID,
                "Random Number Augmentation Function",
                "This augmentation function generates a random number between 0 and 100.",
                "1.0.0");
    }

    @Override
    public List<AugmentationFunctionResult<?>> run(AugmentationFunctionRequest request) 
            throws AugmentationFunctionException {
        
        // Generate a random number between 0 and 1
        double randomNumber = Math.random();

        // Create a generic result with the random number
        AugmentationFunctionResult<Double> result = new AugmentationFunctionResult<>(
                AugmentationFunctionResultType.GENERIC_RESULT,
                "randomNumber",
                randomNumber,
                null,
                null
        );

        return Collections.singletonList(result);
    }
}

public class RandomStateResultAugmentationFunction extends StatelessAugmentationFunction {

    public static final String FUNCTION_ID = "random-state-result-function";
    public static final int RANDOM_STRING_LENGTH = 10;

    public RandomStateResultAugmentationFunction() {
        super(FUNCTION_ID,
                "Random State Result Augmentation Function",
                "Generates multiple state components with random values",
                "1.0.0");
    }

    @Override
    public List<AugmentationFunctionResult<?>> run(AugmentationFunctionRequest request) 
            throws AugmentationFunctionException {

        List<AugmentationFunctionResult<?>> results = new ArrayList<>();

        // Property Result: Random string property
        results.add(new AugmentationFunctionResult<>(
                AugmentationFunctionResultType.PROPERTY_RESULT,
                "randomStringProperty",
                generateRandomString(RANDOM_STRING_LENGTH),
                null,
                null
        ));

        // Event Result: Random number event
        results.add(new AugmentationFunctionResult<>(
                AugmentationFunctionResultType.EVENT_RESULT,
                "randomNumberEvent",
                Math.random(),
                null,
                null
        ));

        // Relationship Result: New relationship type
        results.add(new AugmentationFunctionResult<>(
                AugmentationFunctionResultType.RELATIONSHIP_RESULT,
                "randomStringRelationship",
                generateRandomString(RANDOM_STRING_LENGTH),
                null,
                null
        ));

        // Relationship Instance Result: Concrete relationship
        results.add(new AugmentationFunctionResult<>(
                AugmentationFunctionResultType.RELATIONSHIP_INSTANCE_RESULT,
                "randomStringRelationshipInstance",
                generateRandomString(RANDOM_STRING_LENGTH),
                null,
                null
        ));

        return results;
    }

    private static String generateRandomString(int length) {
        String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
        StringBuilder randomString = new StringBuilder();
        for (int i = 0; i < length; i++) {
            int index = (int) (Math.random() * characters.length());
            randomString.append(characters.charAt(index));
        }
        return randomString.toString();
    }
}

public class StatefulPeriodicRandomNumberAugmentationFunction extends StatefulAugmentationFunction {

    private static final long AUGMENTATION_FUNCTION_TIME_MS = 1000;
    public static final String FUNCTION_ID = "periodic-random-number-augmentation-function";
    
    private Timer timer;
    private TimerTask timerTask;

    public StatefulPeriodicRandomNumberAugmentationFunction() {
        super(FUNCTION_ID,
                "Periodic Random Number Augmentation Function",
                "Generates random numbers periodically",
                "1.0.0");
    }

    @Override
    public void start(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        try {
            logger.info("Starting periodic function with period {} ms", AUGMENTATION_FUNCTION_TIME_MS);
            createTimerTask(0, AUGMENTATION_FUNCTION_TIME_MS);
        } catch (Exception e) {
            throw new AugmentationFunctionException("Error starting function: " + e.getMessage());
        }
    }

    @Override
    public void stop(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        try {
            logger.info("Stopping periodic function");
            stopTimerTask();
        } catch (Exception e) {
            throw new AugmentationFunctionException("Error stopping function: " + e.getMessage());
        }
    }

    private void createTimerTask(long initialDelayMs, long periodMs) {
        stopTimerTask(); // Ensure no existing timer
        
        this.timerTask = new TimerTask() {
            @Override
            public void run() {
                // Generate random number
                double randomNumber = Math.random();
                
                AugmentationFunctionResult<Double> result = new AugmentationFunctionResult<>(
                        AugmentationFunctionResultType.GENERIC_RESULT,
                        "randomNumber",
                        randomNumber,
                        null,
                        null
                );
                
                // Notify result asynchronously
                notifyResult(Collections.singletonList(result));
            }
        };

        this.timer = new Timer(true);
        this.timer.scheduleAtFixedRate(this.timerTask, initialDelayMs, periodMs);
    }

    private void stopTimerTask() {
        if (this.timerTask != null) {
            this.timerTask.cancel();
            this.timerTask = null;
        }
        if (this.timer != null) {
            this.timer.cancel();
            this.timer.purge();
            this.timer = null;
        }
    }

    @Override
    public void onStateUpdate(DigitalTwinState digitalTwinState) {
        logger.debug("Received state update: {}", digitalTwinState);
        // No action needed - timer handles result generation
    }

    @Override
    public void onEventNotificationReceived(DigitalTwinStateEventNotification<?> notification) {
        logger.debug("Received event notification: {}", notification);
        // No action needed - timer handles result generation
    }

    // onQueryResultRefresh is not needed in pure timer mode;
    // the default no-op implementation from StatefulAugmentationFunction is inherited.
}

public class StatefulStateDrivenRandomNumberAugmentationFunction extends StatefulAugmentationFunction {

    public static final String FUNCTION_ID = "state-driven-random-number-augmentation-function";
    
    private List<AugmentationFunctionResult<?>> lastResultList;

    public StatefulStateDrivenRandomNumberAugmentationFunction() {
        super(FUNCTION_ID,
                "State-Driven Random Number Augmentation Function",
                "Generates random numbers on state changes and computes running average",
                "1.0.0");
        
        this.lastResultList = new ArrayList<>();
    }

    @Override
    public void start(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        try {
            logger.info("Starting state-driven augmentation function");
            // Initialize internal state if needed
        } catch (Exception e) {
            throw new AugmentationFunctionException("Error starting function: " + e.getMessage());
        }
    }

    @Override
    public void stop(AugmentationFunctionRequest request) throws AugmentationFunctionException {
        try {
            logger.info("Stopping state-driven augmentation function");
            // Cleanup resources
        } catch (Exception e) {
            throw new AugmentationFunctionException("Error stopping function: " + e.getMessage());
        }
    }

    @Override
    public void onStateUpdate(DigitalTwinState digitalTwinState) throws AugmentationFunctionException {
        try {
            logger.debug("Received state update: {}", digitalTwinState);

            // Generate new random number in response to state change
            double randomNumber = Math.random();
            AugmentationFunctionResult<Double> result = new AugmentationFunctionResult<>(
                    AugmentationFunctionResultType.GENERIC_RESULT,
                    "randomNumber",
                    randomNumber,
                    null,
                    null
            );

            // Add to internal history (stateful behavior)
            this.lastResultList.add(result);

            // Compute average from history
            double averageRandomNumber = this.lastResultList.stream()
                    .filter(r -> r.getType() == AugmentationFunctionResultType.GENERIC_RESULT)
                    .mapToDouble(r -> (Double) r.getValue())
                    .average()
                    .orElse(0.0);

            // Create aggregated result
            AugmentationFunctionResult<Double> averageResult = new AugmentationFunctionResult<>(
                    AugmentationFunctionResultType.GENERIC_RESULT,
                    "averageRandomNumber",
                    averageRandomNumber,
                    null,
                    null
            );

            // Notify both results asynchronously
            this.notifyResult(Arrays.asList(result, averageResult));

        } catch (Exception e) {
            throw new AugmentationFunctionException("Error processing state update: " + e.getMessage());
        }
    }

    @Override
    public void onEventNotificationReceived(DigitalTwinStateEventNotification<?> notification) {
        logger.debug("Received event notification: {}", notification);
        // Could react to specific events if needed
    }

    // onQueryResultRefresh is not needed in pure push mode;
    // the default no-op implementation from StatefulAugmentationFunction is inherited.
}

public class AugmentationFunctionRegistrationWldtEvent extends WldtEvent<AugmentationFunction> {
    private String augmentationHandlerId;
}

public class AugmentationFunctionUnRegistrationWldtEvent extends WldtEvent<AugmentationFunction> {
    private String augmentationHandlerId;
}

public class AugmentationFunctionExecuteWldtEvent extends WldtEvent<AugmentationFunctionRequest> {
    private String augmentationFunctionId;
    private String augmentationHandlerId;
}