[CLD-302]: feat(operations): introduce ExecutionOperationN (#152)

There is a scenario discovered when an operation with same input has to
be run multiple times, eg when deploying the same MCMS contract multiple
times so it can be associated with different roles.

This commit introduces `ExecutionOperationN`, it will execute the
provided operation N times.

For idempotency behaviour, we went to ensure on reruns, the
`ExecutionOperationN` will return the successful prior results in the
same order in the slice. That is why we need to remember the order.

Usage
```go
// execute 3 times
linkDeployReports, err := operations.ExecuteOperationN(
			b, DeployLinkOp, deps, operations.EmptyInput{},
			"deploy-multiple-link-contract", 3,
			operations.WithRetry[operations.EmptyInput, EthereumDeps](),
		)
```

Report
```
  {
    "id": "15ac8420-0b59-4293-a188-948ad43643da",
    "definition": {
      "id": "deploy-link-token-op",
      "version": "1.0.0",
      "description": "Deploy LINK Contract Operation"
    },
    "output": "0x9dc98d0a1362d1aa83a10569c45ef4ee3ef97071",
    "input": {},
    "timestamp": "2025-06-04T15:36:02.066618+10:00",
    "error": null,
    "childOperationReports": null,
    "executionSeries": {
      "id": "deploy-multiple-times",
      "order": 1
    }
  }
```

JIRA: https://smartcontract-it.atlassian.net/browse/CLD-302

Author: graham-chainlink

.changeset/cute-pans-cheer.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat(operations): introduce ExecutionOperationN

operations/execute.go

@@ -105,7 +105,7 @@ func ExecuteOperation[IN, OUT, DEP any](
 		return Report[IN, OUT]{}, fmt.Errorf("operation %s input: %w", operation.def.ID, ErrNotSerializable)
 	}
 
-	if previousReport, found := loadPreviousSuccessfulReport[IN, OUT](b, operation.def, input); found {
+	if previousReport, ok := loadPreviousSuccessfulReport[IN, OUT](b, operation.def, input); ok {
 		b.Logger.Infow("Operation already executed. Returning previous result", "id", operation.def.ID,
 			"version", operation.def.Version, "description", operation.def.Description)
 
@@ -123,29 +123,7 @@ func ExecuteOperation[IN, OUT, DEP any](
 	var err error
 
 	if executeConfig.retryConfig.Enabled {
-		var inputTemp = input
-
-		// Generate the configurable options for the retry
-		retryOpts := executeConfig.retryConfig.Policy.options()
-		// Use the operation context in the retry
-		retryOpts = append(retryOpts, retry.Context(b.GetContext()))
-		// Append the retry logic which will log the retry and attempt to transform the input
-		// if the user provided a custom input hook.
-		retryOpts = append(retryOpts, retry.OnRetry(func(attempt uint, err error) {
-			b.Logger.Infow("Operation failed. Retrying...",
-				"operation", operation.def.ID, "attempt", attempt, "error", err)
-
-			if executeConfig.retryConfig.InputHook != nil {
-				inputTemp = executeConfig.retryConfig.InputHook(attempt, err, inputTemp, deps)
-			}
-		}))
-
-		output, err = retry.DoWithData(
-			func() (OUT, error) {
-				return operation.execute(b, deps, inputTemp)
-			},
-			retryOpts...,
-		)
+		output, err = executeWithRetry(b, operation, deps, input, executeConfig)
 	} else {
 		output, err = operation.execute(b, deps, input)
 	}
@@ -166,6 +144,113 @@ func ExecuteOperation[IN, OUT, DEP any](
 	return report, nil
 }
 
+// ExecuteOperationN executes the given operation multiple n times with the given input and dependencies.
+// Execution will return the previous successful execution results and skip execution if there were
+// previous successful runs found in the Reports.
+// executionSeriesID is used to identify the multiple executions as a single unit.
+// It is important to use a unique executionSeriesID for different sets of multiple executions.
+func ExecuteOperationN[IN, OUT, DEP any](
+	b Bundle, operation *Operation[IN, OUT, DEP], deps DEP, input IN, seriesID string, n uint,
+	opts ...ExecuteOption[IN, DEP],
+) ([]Report[IN, OUT], error) {
+	if !IsSerializable(b.Logger, input) {
+		return []Report[IN, OUT]{}, fmt.Errorf("operation %s input: %w", operation.def.ID, ErrNotSerializable)
+	}
+
+	results, ok := loadSuccessfulExecutionSeriesReports[IN, OUT](b, operation.def, input, seriesID)
+	resultsLen := uint(len(results))
+	if ok {
+		// if there are more reports than n, we return only the first n reports
+		if resultsLen >= n {
+			b.Logger.Infow("Operations already executed in an execution series. Returning previous results", "id", operation.def.ID,
+				"version", operation.def.Version, "description", operation.def.Description, "executionSeriesID", seriesID)
+
+			return results[:n], nil
+		}
+	}
+	remainingTimesToRun := n - resultsLen
+
+	b.Logger.Infow("Executing operation multiple times",
+		"executionSeriesID", seriesID,
+		"n", n,
+		"remainingTimesToRun", remainingTimesToRun)
+
+	executeConfig := &ExecuteConfig[IN, DEP]{
+		retryConfig: newDisabledRetryConfig[IN, DEP](),
+	}
+	for _, opt := range opts {
+		opt(executeConfig)
+	}
+
+	order := resultsLen
+	for range remainingTimesToRun {
+		var output OUT
+		var err error
+
+		if executeConfig.retryConfig.Enabled {
+			output, err = executeWithRetry(b, operation, deps, input, executeConfig)
+		} else {
+			output, err = operation.execute(b, deps, input)
+		}
+
+		if err == nil && !IsSerializable(b.Logger, output) {
+			return []Report[IN, OUT]{}, fmt.Errorf("operation %s output: %w", operation.def.ID, ErrNotSerializable)
+		}
+
+		report := NewReport(operation.def, input, output, err)
+		report.ExecutionSeries = &ExecutionSeries{
+			ID:    seriesID,
+			Order: order,
+		}
+		order++
+		if err = b.reporter.AddReport(genericReport(report)); err != nil {
+			return []Report[IN, OUT]{}, err
+		}
+
+		if report.Err != nil {
+			return []Report[IN, OUT]{}, report.Err
+		}
+
+		results = append(results, report)
+	}
+
+	return results, nil
+}
+
+func executeWithRetry[IN, OUT, DEP any](
+	b Bundle,
+	operation *Operation[IN, OUT, DEP],
+	deps DEP,
+	input IN,
+	executeConfig *ExecuteConfig[IN, DEP],
+) (OUT, error) {
+	var inputTemp = input
+
+	// Generate the configurable options for the retry
+	retryOpts := executeConfig.retryConfig.Policy.options()
+	// Use the operation context in the retry
+	retryOpts = append(retryOpts, retry.Context(b.GetContext()))
+	// Append the retry logic which will log the retry and attempt to transform the input
+	// if the user provided a custom input hook.
+	retryOpts = append(retryOpts, retry.OnRetry(func(attempt uint, err error) {
+		b.Logger.Infow("Operation failed. Retrying...",
+			"operation", operation.def.ID, "attempt", attempt, "error", err)
+
+		if executeConfig.retryConfig.InputHook != nil {
+			inputTemp = executeConfig.retryConfig.InputHook(attempt, err, inputTemp, deps)
+		}
+	}))
+
+	output, err := retry.DoWithData(
+		func() (OUT, error) {
+			return operation.execute(b, deps, inputTemp)
+		},
+		retryOpts...,
+	)
+
+	return output, err
+}
+
 // ExecuteSequence executes a Sequence and returns a SequenceReport.
 // The SequenceReport contains a report for the Sequence and also the execution reports which are all
 // the operations that were executed as part of this sequence.
@@ -189,7 +274,7 @@ func ExecuteSequence[IN, OUT, DEP any](
 		return SequenceReport[IN, OUT]{}, fmt.Errorf("sequence %s input: %w", sequence.def.ID, ErrNotSerializable)
 	}
 
-	if previousReport, found := loadPreviousSuccessfulReport[IN, OUT](b, sequence.def, input); found {
+	if previousReport, ok := loadPreviousSuccessfulReport[IN, OUT](b, sequence.def, input); ok {
 		executionReports, err := b.reporter.GetExecutionReports(previousReport.ID)
 		if err != nil {
 			return SequenceReport[IN, OUT]{}, err
@@ -291,3 +376,56 @@ func loadPreviousSuccessfulReport[IN, OUT any](
 	// No previous execution was found
 	return Report[IN, OUT]{}, false
 }
+
+// loadSuccessfulExecutionSeriesReports loads all successful reports for an operation in an execution series.
+func loadSuccessfulExecutionSeriesReports[IN, OUT any](
+	b Bundle, def Definition, input IN, seriesID string,
+) ([]Report[IN, OUT], bool) {
+	prevReports, err := b.reporter.GetReports()
+	if err != nil {
+		b.Logger.Errorw("Failed to get reports", "error", err)
+		return []Report[IN, OUT]{}, false
+	}
+	currentHash, err := constructUniqueHashFrom(b.reportHashCache, def, input)
+	if err != nil {
+		b.Logger.Errorw("Failed to construct unique hash", "error", err)
+		return []Report[IN, OUT]{}, false
+	}
+
+	var foundReports []Report[IN, OUT]
+	for _, report := range prevReports {
+		// if the report is not part of the same execution series, skip it
+		if report.ExecutionSeries == nil || report.ExecutionSeries.ID != seriesID {
+			continue
+		}
+		reportHash, err := constructUniqueHashFrom(b.reportHashCache, report.Def, report.Input)
+		if err != nil {
+			b.Logger.Errorw("Failed to construct unique hash for previous report", "error", err)
+			continue
+		}
+		if reportHash == currentHash && report.Err == nil {
+			typedReport, ok := typeReport[IN, OUT](report)
+			if !ok {
+				b.Logger.Debugw(fmt.Sprintf("Previous %s execution found but couldn't find its matching Report", def.ID), "report_id", report.ID)
+				continue
+			}
+
+			b.Logger.Debugw(fmt.Sprintf("Previous %s execution found", def.ID), "report_id", report.ID)
+
+			foundReports = append(foundReports, typedReport)
+		}
+	}
+
+	b.Logger.Infof("Found %d reports for ExecutionSeriesID %q", len(foundReports), seriesID)
+
+	if len(foundReports) == 0 {
+		return []Report[IN, OUT]{}, false
+	}
+
+	results := make([]Report[IN, OUT], len(foundReports))
+	for _, foundReport := range foundReports {
+		results[foundReport.ExecutionSeries.Order] = foundReport
+	}
+
+	return results, true
+}