# 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.