TenantAtlas/specs/086-retire-legacy-runs-into-operation-runs/contracts

Contracts (Spec 086)

This spec does not introduce a new public HTTP API surface.

Canonical OperationRun contract (internal)

Spec 086 tightens and standardizes the internal contract for how operations are created, identified, and displayed.

Run creation contract

• Start surfaces must create the operation_runs row before dispatching asynchronous work.
• Jobs must receive the OperationRun (or its id) and must not attempt a fallback-create.

Identity / idempotency contract

Operation run identity is enforced by a partial unique index for active states.

Planned identity rules by type:

• inventory.sync and directory_groups.sync: deterministic identity (while-active dedupe)
• backup_schedule.run_now and backup_schedule.retry: unique-per-click identity (nonce)
• backup_schedule.scheduled: deterministic identity by (backup_schedule_id, scheduled_for) (strict)

Context contract (selected keys)

The operation_runs.context JSON is used for:

• “Target” display (via target_scope)
• “Related” deep links (via OperationRunLinks::related)
• provenance (trigger source, schedule id, initiating user)

Keys referenced in existing UI code:

• provider_connection_id
• backup_schedule_id
• backup_schedule_run_id
• restore_run_id
• target_scope

Graph Contract Registry

All Microsoft Graph calls remain required to go through GraphClientInterface and be modeled in config/graph_contracts.php.

Spec 086 removes Graph calls from Filament render/search/label callbacks (DB-only rendering), and moves those lookups behind cached tables + asynchronous sync operations.