TenantAtlas/specs/087-legacy-runs-removal/research.md

Phase 0 — Research: Legacy Runs Removal (Spec 087)

Branch: 087-legacy-runs-removal
Date: 2026-02-12
Input Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/087-legacy-runs-removal/spec.md

What “Legacy Runs” Means In This Repo

Decision: “Legacy runs” for this spec are the tenant-scoped run tables + UI surfaces that duplicate operation_runs for:

• Inventory sync
• Entra group sync
• Backup schedule execution

Evidence (current repo state):

• Legacy tables exist:
  • inventory_sync_runs (database/migrations/2026_01_07_142719_create_inventory_sync_runs_table.php)
  • entra_group_sync_runs (database/migrations/2026_01_11_120004_create_entra_group_sync_runs_table.php)
  • backup_schedule_runs (database/migrations/2026_01_05_011034_create_backup_schedule_runs_table.php)
• These legacy tables already have bridging columns to canonical runs (operation_run_id was added later), indicating an ongoing migration to operation_runs:
  • database/migrations/2026_02_10_090213_add_operation_run_id_to_inventory_sync_runs_table.php
  • database/migrations/2026_02_10_090214_add_operation_run_id_to_entra_group_sync_runs_table.php
  • database/migrations/2026_02_10_090215_add_operation_run_id_to_backup_schedule_runs_table.php

Canonical Run Types: Spec vs Current Code

Problem

The spec mandates canonical run_type identifiers:

• inventory_sync
• drift_generate_findings
• entra_group_sync
• backup_schedule_run
• backup_schedule_retention
• backup_schedule_purge

But the current code uses dotted OperationRunType values such as:

• inventory.sync
• directory_groups.sync
• drift.generate
• backup_schedule.run_now / backup_schedule.retry / backup_schedule.scheduled

(app/Support/OperationRunType.php)

Decision

Adopt the spec’s underscore identifiers as the canonical stored values going forward.

Rationale

• The spec explicitly requires a standardized and enforced contract.
• Stored type values are used across UI and notifications; a single canonical scheme reduces “type sprawl.”

Backwards Compatibility Plan (for existing rows)

• Provide a one-time data migration that rewrites existing operation_runs.type values from the old dotted values to the new underscore values for the affected categories only.
• Keep a compatibility mapping in code (temporary) only if needed to avoid breaking filters/UI during rollout.

Alternatives Considered

• Keep dotted values and treat the spec’s list as “display labels.” Rejected because it violates FR-012’s explicit identifiers.
• Introduce a parallel “canonical_type” column. Rejected because it increases complexity and duplication.

Drift + Inventory References (FK Cutover)

Problem

Drift and inventory currently reference legacy run IDs:

• Findings: baseline_run_id / current_run_id are FKs to inventory_sync_runs (database/migrations/2026_01_13_223311_create_findings_table.php)
• Inventory items: last_seen_run_id references inventory_sync_runs (database/migrations/2026_01_07_142720_create_inventory_items_table.php)

But inventory items already have the new canonical field:

• last_seen_operation_run_id (database/migrations/2026_02_10_091433_add_last_seen_operation_run_id_to_inventory_items_table.php)

Decision

Migrate drift + inventory references to operation_runs and drop the legacy FK columns.

Migration Strategy

• Add new nullable columns:
  • findings.baseline_operation_run_id
  • findings.current_operation_run_id
• Backfill by joining through inventory_sync_runs.operation_run_id where available.
• Update app code to read/write the new fields.
• Drop old *_run_id FK columns.
• Only after that, drop the legacy tables.

Rationale

• Required to drop legacy tables without breaking referential integrity.
• Aligns with spec acceptance scenario: “historical drift findings where no safe mapping exists” remain functional (references can be null).

Legacy UI Surfaces Found (To Remove)

Inventory sync runs:

• app/Filament/Resources/InventorySyncRunResource.php

Entra group sync runs:

• app/Filament/Resources/EntraGroupSyncRunResource.php

Backup schedule run history (RelationManager + modal):

• app/Filament/Resources/BackupScheduleResource/RelationManagers/BackupScheduleRunsRelationManager.php

Architecture Guard (NoLegacyRuns)

Decision

Add a CI/architecture Pest test similar to existing “NoLegacy…” guards:

• tests/Feature/Guards/NoLegacyBulkOperationsTest.php

Guard Scope (per spec clarification)

Scan for forbidden tokens under:

• /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/
• /Users/ahmeddarrazi/Documents/projects/TenantAtlas/database/
• /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/
• /Users/ahmeddarrazi/Documents/projects/TenantAtlas/routes/

Exclude:

• vendor/, storage/, specs/, spechistory/, references/, bootstrap/cache/

Initial Forbidden Tokens (starting list)

• InventorySyncRun, inventory_sync_runs, InventorySyncRunResource
• EntraGroupSyncRun, entra_group_sync_runs, EntraGroupSyncRunResource
• BackupScheduleRun, backup_schedule_runs, BackupScheduleRunsRelationManager

Open Questions

None remaining for planning.

• “No backfill” is already clarified in the spec; the only data movement here is migrating references to existing operation_runs.
• Authorization semantics for canonical operations pages are clarified (404 vs 403) and must be preserved.