# Implementation Plan: Unified Operations Runs Suitewide

**Branch**: `feat/054-unify-operations-runs-suitewide` | **Date**: 2026-01-16 | **Spec**: [Spec Link](spec.md)
**Input**: Feature specification from `specs/054-unify-runs-suitewide/spec.md`

## Summary

This feature unifies long-running tenant operations (e.g., Inventory Sync, Drift Generation) into a single canonical `operation_runs` table. This enables a consistent "Monitoring -> Operations" view for all tenant activities. Legacy run tables will be maintained in parallel for now (Parallel Write Transition). `RestoreRun` remains a domain-specific record but will be mirrored into `operation_runs` via an adapter pattern.

## Technical Context

**Language/Version**: PHP 8.4
**Primary Dependencies**: Filament v4, Laravel v12, Livewire v3
**Storage**: PostgreSQL (`operation_runs` table + JSONB)
**Testing**: Pest v4 (Feature tests for Service, Livewire tests for UI)
**Target Platform**: Linux server (Docker/Dokploy)
**Project Type**: Web Application (Laravel Monolith)
**Performance Goals**: Start operation < 2s. List runs < 200ms.
**Constraints**: Tenant isolation is paramount. No cross-tenant data leakage.
**Scale/Scope**: ~50-100 runs/day per tenant. Retention 90 days.

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- [x] Inventory-first: N/A (this is about tracking operations, not inventory state itself)
- [x] Read/write separation: Monitoring is read-only. Starts are explicit writes.
- [x] Graph contract path: N/A (this feature tracks runs, doesn't call Graph directly)
- [x] Deterministic capabilities: N/A
- [x] Tenant isolation: `operation_runs` has `tenant_id`. Policies ensure scope.
- [x] Automation: Idempotency enforced via DB index.
- [x] Data minimization: No secrets in `failure_summary`.

## Project Structure

### Documentation (this feature)

```text
specs/054-unify-runs-suitewide/
├── plan.md              # This file
├── research.md          # Research findings
├── data-model.md        # Database schema
├── quickstart.md        # Dev guide
├── contracts/           # Service interfaces & routes
└── tasks.md             # Task breakdown
```

### Source Code (repository root)

```text
app/
├── Models/
│   └── OperationRun.php
├── Services/
│   └── OperationRunService.php
├── Livewire/
│   └── Monitoring/
│       ├── OperationsList.php
│       └── OperationsDetail.php
├── Jobs/
│   └── Middleware/
│       └── TrackOperationRun.php
└── Listeners/
    └── SyncRestoreRunToOperation.php

database/migrations/
└── YYYY_MM_DD_create_operation_runs_table.php
```

**Structure Decision**: Standard Laravel Service/Model/Livewire pattern.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | | |