TenantAtlas/specs/056-remove-legacy-bulkops/research.md

Phase 0 — Research: Remove Legacy BulkOperationRun & Canonicalize Operations (v1.0)

Branch: 056-remove-legacy-bulkops
Date: 2026-01-18

Goals for Research

• Resolve spec clarifications and translate them into concrete implementation constraints.
• Identify existing repo patterns for:
  • run identity / dedupe
  • summary_counts normalization
  • locks / concurrency limiting
  • idempotent selection hashing
• Enumerate known legacy usage locations to inform the discovery report.

Findings & Decisions

Decision 1 — Per-target scope concurrency

• Decision: Concurrency limits are configuration-driven with default = 1 per target scope.
• Rationale: Default=1 is the safest choice against Graph throttling and reduces blast radius when many tenants/scope targets are active.
• Alternatives considered:
  • Default=2: more throughput but higher throttling risk.
  • Default=5: increases throttling/incident risk.
  • Hardcoded values: hard to tune per environment.
• Implementation constraint: Limit is enforced per entra_tenant_id or directory_context_id.

Decision 2 — Selection Identity (idempotency fingerprint)

• Decision: Hybrid selection identity.
  • If the user explicitly selects IDs: fingerprint includes an IDs-hash.
  • If the user selects via filter/query (“select all”): fingerprint includes a query/filter hash.
• Rationale: Supports both UX patterns and avoids duplicate runs while remaining deterministic.
• Alternatives considered:
  • IDs-hash only: cannot represent “select all by filter”.
  • Query-hash only: cannot safely represent explicit selections.
  • Always store both: increases complexity without clear value.

Decision 3 — Legacy history handling

• Decision: Do not import legacy bulk-run history into OperationRun.
• Rationale: Minimizes migration risk and avoids polluting the canonical run surface with “synthetic” imported data.
• Alternatives considered:
  • One-time import: adds complexity, new semantics, and additional testing burden.

Decision 4 — Canonical summary metrics

• Decision: Summary metrics are derived and rendered from operation_runs.summary_counts using the canonical key registry.
• Rationale: Ensures consistent Monitoring UX and prevents ad-hoc keys.
• Alternatives considered:
  • Per-operation bespoke metrics: causes UX drift and breaks shared widgets.

Decision 5 — Reuse existing repo patterns

• Decision: Reuse existing run, lock, and selection hashing patterns already present in the repository.
• Rationale: Aligns with constitution and avoids divergent implementations.
• Evidence in repo:
  • OperationRunService provides tenant-wide active-run dedupe and safe dispatch failure handling.
  • OperationCatalog centralizes labels/durations and allowed summary keys.
  • InventoryConcurrencyLimiter shows slot-based lock acquisition with config-driven maxima.
  • InventorySyncService shows deterministic selection hashing and selection-level locks.

Legacy Usage Inventory (initial)

This is a starting list derived from a repo search; the Phase 2 Discovery Report must expand/confirm.

• Legacy bulk-run model: app/Models/BulkOperationRun.php
• Legacy bulk-run service: app/Services/BulkOperationService.php
• Legacy jobs using BulkOperationRun/Service:
  • app/Jobs/BulkPolicySyncJob.php
  • app/Jobs/BulkPolicyDeleteJob.php
  • app/Jobs/BulkBackupSetDeleteJob.php
  • app/Jobs/BulkPolicyVersionPruneJob.php
  • app/Jobs/BulkPolicyVersionForceDeleteJob.php
  • app/Jobs/BulkRestoreRunDeleteJob.php
  • app/Jobs/BulkTenantSyncJob.php
  • app/Jobs/CapturePolicySnapshotJob.php
  • app/Jobs/GenerateDriftFindingsJob.php (mixed usage)
• Legacy DB artifacts:
  • database/migrations/2025_12_23_215901_create_bulk_operation_runs_table.php
  • database/migrations/2026_01_11_120001_add_idempotency_key_to_bulk_operation_runs_table.php
  • database/migrations/2025_12_24_005055_increase_bulk_operation_runs_status_length.php
• Legacy test data:
  • database/factories/BulkOperationRunFactory.php
  • database/seeders/BulkOperationsTestSeeder.php

Open Questions

None remaining for Phase 0 (spec clarifications resolved). Any additional unknowns found during discovery are to be added to the Phase 2 discovery report and/or tasks.