Implementation Plan: Unified Operations Runs Suitewide

Branch: feat/054-unify-operations-runs-suitewide | Date: 2026-01-16 | Spec: Spec Link 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.

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

Project Structure

Documentation (this feature)

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)

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

2.9 KiB Raw Blame History