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)
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)

/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)

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