TenantAtlas/specs/054-unify-runs-suitewide/plan.md

# Implementation Plan: Unified Operations Runs Suitewide (054)

**Branch**: `feat/054-unify-operations-runs-suitewide` | **Date**: 2026-01-17 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/054-unify-runs-suitewide/spec.md` ([spec.md](spec.md))  
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/054-unify-runs-suitewide/spec.md`

**Note**: This plan is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.

## Summary

Eliminate “run sprawl” by adopting a single tenant-scoped canonical run record (`operation_runs`) for long-running and
operationally relevant actions across the product, surfaced consistently in Monitoring → Operations (list + detail).

Key behaviors:
- Start surfaces are enqueue-only: authorize → create/reuse canonical run (dedupe) → dispatch → confirm + “View run”.
- Legacy per-module run tables remain in parallel where they exist; Monitoring/Operations uses canonical runs.
- Restore remains a domain workflow record, but is mirrored into canonical runs via an adapter row (`restore.execute`)
  created from `RestoreRunStatus=previewed` onward (`status=queued`, `outcome=pending` until execution begins).

## Technical Context

**Language/Version**: PHP 8.4.15 (Laravel 12)  
**Primary Dependencies**: Filament v4, Livewire v3  
**Storage**: PostgreSQL (`operation_runs` + JSONB for summary/failures/context; partial unique index for active-run dedupe)  
**Testing**: Pest v4 (PHPUnit v12)  
**Target Platform**: Web application (Sail-first locally, Dokploy-first deploy)  
**Project Type**: web  
**Performance Goals**: Start surfaces confirm within 2 seconds and provide a “View run” link; Monitoring/Operations list is usable with default last-30-days window and filters.  
**Constraints**: Tenant isolation is non-negotiable; Monitoring is DB-only at render time; no remote work inline; failures are stable codes + sanitized messages (no secrets/tokens/raw payload dumps).  
**Scale/Scope**: Tenant-scoped run history across modules; retention defaults to 90 days.

## Constitution Check

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

- Inventory-first: PASS (Monitoring uses persisted run records; does not redefine Inventory semantics).
- Read/write separation: PASS (Monitoring/Operations is view-only; writes remain in their owning UIs with explicit confirmation/audit where applicable).
- Graph contract path: PASS (Monitoring makes no Graph calls; start surfaces MUST NOT perform remote work inline).
- Deterministic capabilities: N/A (no new capability resolver introduced in this feature).
- Tenant isolation: PASS (all run access is tenant-scoped; cross-tenant access is forbidden).
- Run observability: PASS (queued/remote/scheduled work is tracked as canonical runs and links to a single Monitoring hub).
- Automation: PASS (active-run de-duplication via deterministic identity + partial unique index).
- Data minimization: PASS (failure summaries are sanitized and stable; no secrets/tokens/raw payload dumps in persisted failures/notifications).

**Gate status (pre-Phase 0)**: PASS (no violations).  
**Gate status (post-Phase 1)**: PASS (design artifacts present: `research.md`, `data-model.md`, `contracts/`, `quickstart.md`).

## Project Structure

### Documentation (this feature)

```text
/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/054-unify-runs-suitewide/
├── plan.md                     # This file (/speckit.plan command output)
├── spec.md                     # Feature specification (input)
├── checklists/
│   └── requirements.md         # Spec quality checklist
├── research.md                 # Phase 0 output
├── data-model.md               # Phase 1 output
├── quickstart.md               # Phase 1 output
├── contracts/                  # Phase 1 output
└── tasks.md                    # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```

### Source Code (repository root)

```text
app/
├── Filament/
│   ├── Pages/
│   └── Resources/
├── Jobs/
│   └── Middleware/
├── Listeners/
├── Models/
├── Notifications/
├── Observers/
├── Policies/
├── Services/
└── Support/

database/
└── migrations/

routes/
└── console.php

tests/
├── Feature/
└── Unit/
```

**Structure Decision**: Laravel web application. Implement canonical runs via Eloquent (`OperationRun`) + a small service layer for idempotent creation and lifecycle updates, instrument background jobs via middleware, and surface runs in Filament Monitoring/Operations (tenant-scoped, view-only).

## Complexity Tracking

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