42 lines
1.6 KiB
Markdown
42 lines
1.6 KiB
Markdown
# 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.
|