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.

1.6 KiB Raw Blame History