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.
  6. If an existing active run is returned (dedupe), the initiator (user_id, initiator_name) MUST NOT be replaced.

• Dispatch failure:

  • If queue dispatch fails after a run was created, the system MUST NOT leave misleading queued runs; instead complete the run immediately as failed (e.g., failure code queue.dispatch_failed) and show a clear UI message.

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\SyncRestoreRunToOperationRun

Listener for RestoreRun events to update the shadow OperationRun. The adapter row is created/visible only once a restore run reaches previewed (or later).