TenantAtlas/specs/054-unify-runs-suitewide/contracts/service_interface.md

Service Interface: Operation Runs

App\Services\OperationRunService

ensureRun

Idempotently creates or retrieves an active run.

public function ensureRun(
    Tenant $tenant,
    string $type,
    array $inputs,
    ?User $initiator = null
): OperationRun

• Logic:
  1. Compute hash = sha256(tenant_id + type + sorted_json(inputs)).
  2. Try finding active run (queued or running) with this hash.
  3. If found, return it.
  4. If not found, create new queued run.
  5. Return run.

updateRun

Updates the status/outcome of a run.

public function updateRun(
    OperationRun $run,
    string $status,
    ?string $outcome = null,
    array $summaryCounts = [],
    array $failures = []
): OperationRun

failRun

Helper to fail a run immediately.

public function failRun(OperationRun $run, Throwable $e): OperationRun

App\Jobs\Middleware\TrackOperationRun

Middleware for Jobs to automatically handle running -> completed/failed transitions if bound to a run.

App\Listeners\SyncRestoreRunToOperation

Listener for RestoreRun events to update the shadow OperationRun.