TenantAtlas/specs/086-retire-legacy-runs-into-operation-runs/plan.md

Implementation Plan: Retire Legacy Runs Into Operation Runs

Branch: 086-retire-legacy-runs-into-operation-runs | Date: 2026-02-10 | Spec: specs/086-retire-legacy-runs-into-operation-runs/spec.md Input: Feature specification from specs/086-retire-legacy-runs-into-operation-runs/spec.md

Summary

Retire legacy “run tracking” tables as the primary execution tracker for in-scope operations (inventory sync, directory groups sync, backup schedule runs, restore execution, and directory role definitions sync) and make operation_runs the canonical source of truth.

Key implementation approach:

• Use the existing tenantless canonical viewer /admin/operations/{run} (Filament page TenantlessOperationRunViewer) and ensure it remains DB-only at render time.
• Enforce the clarified 404/403 semantics for run viewing: non-members 404, members missing capability 403, where the view capability equals the start capability.
• Enforce dispatch-time OperationRun creation for every start surface; jobs never fallback-create.
• Apply explicit run identity rules per operation type (dedupe vs unique-per-click vs strict schedule dedupe), including strict scheduled backup idempotency: at most one canonical run ever per (schedule_id, intended fire-time).
• Remove Graph calls from UI render/search/label callbacks by using cached directory data (groups + role definitions) and “Sync now” operations.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4
Storage: PostgreSQL (via Sail)
Testing: Pest v4 (PHPUnit v12 runner)
Target Platform: Web application (Laravel + Filament admin panel) Project Type: web
Performance Goals: Operations viewer + Monitoring pages render from DB state only; canonical viewer loads in ~2s under normal conditions
Constraints: No outbound HTTP in Monitoring/Operations rendering/search/label callbacks (OPS-EX-AUTH-001); dispatch-time OperationRun creation; jobs must never fallback-create; strict 404/403 isolation semantics
Scale/Scope: TenantPilot admin workflows; multiple operation families; staged cutover with legacy history preserved

Constitution Check

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

• Inventory-first: No change to the meaning of inventory vs snapshots/backups; this spec only changes execution tracking.
• Read/write separation: Start surfaces remain enqueue-only; destructive-like actions are not added here; audit logging remains required for mutations.
• Graph contract path: UI render/search/label callbacks must become DB-only; any remaining Graph calls stay behind GraphClientInterface + config/graph_contracts.php.
• Deterministic capabilities: Run viewing must be capability-gated using the existing capability registry (no raw strings).
• RBAC-UX: Enforce clarified semantics for run viewing: non-members 404, members missing capability 403; authorization enforced server-side via Policy/Gate.
• Workspace isolation: Canonical tenantless /admin/operations/{run} continues to enforce workspace membership (deny-as-not-found).
• Global search: OperationRunResource stays non-globally-searchable; no new global-search surfaces introduced.
• Run observability: All in-scope long-running/scheduled/remote operations are tracked via OperationRun; Monitoring pages remain DB-only.
• Automation: Scheduled backup run creation uses strict idempotency per schedule + intended fire-time.
• Badge semantics (BADGE-001): Run status/outcome badges already use BadgeRenderer; do not introduce ad-hoc mappings.
• Filament UI Action Surface Contract: Legacy resources remain read-only; canonical operations pages already define inspection affordances.

Project Structure

Documentation (this feature)

specs/086-retire-legacy-runs-into-operation-runs/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── README.md
└── tasks.md  # To be created by /speckit.tasks

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   │   ├── Monitoring/
│   │   └── Operations/
│   └── Resources/
├── Http/
│   └── Middleware/
├── Jobs/
├── Models/
├── Policies/
├── Services/
└── Support/

config/
├── graph.php
└── graph_contracts.php

database/
└── migrations/

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

Structure Decision: Laravel web application (monolith) with Filament admin panel.

Complexity Tracking

No constitution violations are required for this feature.

Phase Plan

Phase 0/1 deliverables are already captured in:

• specs/086-retire-legacy-runs-into-operation-runs/research.md
• specs/086-retire-legacy-runs-into-operation-runs/data-model.md
• specs/086-retire-legacy-runs-into-operation-runs/contracts/README.md
• specs/086-retire-legacy-runs-into-operation-runs/quickstart.md

Phase 2 (tasks) will be produced via /speckit.tasks and should slice work by operation family:

1. Authorization: capability-gate canonical run viewing (404 vs 403 semantics).
2. Backup schedules: add backup_schedule.scheduled + strict idempotency; make manual runs unique-per-click.
3. Directory groups: stop writing legacy rows; keep legacy pages read-only; ensure dispatch-time OperationRun creation.
4. Inventory sync: stop writing legacy rows; ensure dispatch-time OperationRun creation and no UI Graph calls.
5. Tenant configuration: remove Graph calls from render/search/labels; add role definitions cache + “Sync now” operation.
6. Restore: ensure execution tracking uses OperationRun only; legacy restore domain records remain as domain entities.