TenantAtlas/specs/053-unify-runs-monitoring/data-model.md

# Data Model: Unified Operations Runs + Monitoring Hub (053)

This feature primarily standardizes and surfaces existing run records for long-running operations, and links operators to the underlying business artifacts (e.g., drift findings).

## Entities

## 1) BulkOperationRun (`bulk_operation_runs`)

**Purpose:** Canonical tenant-scoped run record for long-running operations (Phase 1).

**Model:** `App\Models\BulkOperationRun`

**Key fields (existing):**
- `id` (PK)
- `tenant_id` (FK → tenants)
- `user_id` (FK → users)
- `resource` (string) — e.g. `drift`, `backup_set`
- `action` (string) — e.g. `generate`, `add_policies`
- `idempotency_key` (string|null)
- `status` (string) — `pending`, `running`, `completed`, `completed_with_errors`, `failed`, `aborted`
- counters: `total_items`, `processed_items`, `succeeded`, `failed`, `skipped`
- `item_ids` (jsonb) — stable identifiers for the items/scope of the run
  - Example (`drift.generate`): `{ scope_key, baseline_run_id, current_run_id }`
  - Example (`backup_set.add_policies`): `{ backup_set_id, policy_ids, options }`
- `failures` (jsonb|null) — sanitized failure details (including per-item failures for itemized operations)
- `audit_log_id` (FK → audit_logs|null)
- `created_at`, `updated_at`

**Relationships:**
- `BulkOperationRun belongsTo Tenant`
- `BulkOperationRun belongsTo User`
- `BulkOperationRun belongsTo AuditLog` (nullable)

**Uniqueness / idempotency:**
- Active-run uniqueness enforced via a partial unique index on `(tenant_id, idempotency_key)` for active statuses.
- Idempotency keys are deterministic and stable per tenant + operation type + scope.

**State transitions (storage):**
- `pending → running → completed | completed_with_errors | failed | aborted`

**Status mapping (operator UI semantics):**
- `pending` → `queued`
- `running` → `running`
- `completed` → `succeeded`
- `completed_with_errors` → `partially succeeded`
- `failed`/`aborted` → `failed`

**Failure entry shape (sanitized):**
- `reason_code` (string, stable) + `reason` (short sanitized message)
- for itemized runs: `item_id` per failure entry (and optional `type=skipped` for non-failure outcomes)

---

## 2) Finding (`findings`) — Drift results

**Purpose:** Persisted analytic findings; drift findings are the primary “related artifact” for Drift generation runs.

**Model:** `App\Models\Finding`

**Key fields (existing, drift-related):**
- `id` (PK)
- `tenant_id` (FK → tenants)
- `finding_type` (`drift`)
- `scope_key` (string)
- `baseline_run_id` (FK → inventory_sync_runs|null)
- `current_run_id` (FK → inventory_sync_runs|null)
- `fingerprint` (string; deterministic; unique per tenant)
- `subject_type`, `subject_external_id`
- `status` (`new|acknowledged`)
- `evidence_jsonb` (jsonb; sanitized allowlist)
- `created_at`, `updated_at`

**Relationships:**
- `Finding belongsTo Tenant`
- `Finding belongsTo InventorySyncRun` via `baseline_run_id` and `current_run_id` (nullable)

**Notes:**
- Phase 1 can link operators from the drift run to findings through scope/baseline/current identifiers without introducing a new DB foreign key.
- If later needed, introduce an explicit link (e.g., `findings.bulk_operation_run_id`) to make navigation and reporting easier.

---

## 3) InventorySyncRun (`inventory_sync_runs`) — Drift inputs

**Purpose:** “Last observed” inventory run records used as baseline/current inputs for drift comparisons.

**Model:** `App\Models\InventorySyncRun`

**Relevant fields (existing):**
- `tenant_id`
- `status`
- `selection_hash` (used as `scope_key`)
- `finished_at`

---

## 4) Notification Event (DB notifications)

**Purpose:** Persist run lifecycle notifications (queued/completed) linking operators to the run detail page.

**Storage:** Laravel Notifications (DB channel).

**Payload (target):**
- tenant identifier
- run identifier + type (`bulk_operation_run`)
- status bucket (queued/running/succeeded/partial/failed)
- summary counts and a safe error summary (when applicable)