TenantAtlas/specs/172-deferred-operator-surfaces-retrofit/research.md

Research: Deferred Operator Surfaces Retrofit

Decision 1: Treat the tenant detail view, not /admin/t/{tenant}, as the primary tenant-plane retrofit surface

• Decision: Scope the tenant-plane retrofit to the embedded widgets on ViewTenant and keep the table-based recent-operations widget on /admin/t/{tenant} out of scope.
• Rationale: Repo inspection shows the deferred embedded operation surfaces live on app/Filament/Resources/TenantResource/Pages/ViewTenant.php, while app/Filament/Pages/TenantDashboard.php already uses a declaration-backed table widget with row-click inspection. Mixing both into one slice would blur two different action-surface models.
• Alternatives considered: Retrofit the tenant dashboard table widget in the same spec. Rejected because it is already governed as a table surface and would expand the slice beyond the deferred embedded-surface problem.

Decision 2: Keep /admin/operations and /admin/operations/{run} as the canonical inspect destinations

• Decision: Reuse the existing admin-plane operations collection and detail routes for embedded drill-ins rather than creating tenant-scoped operations routes or a parallel tenant viewer.
• Rationale: OperationRunLinks already centralizes these destinations, and the spec explicitly forbids route or lifecycle changes. The missing behavior is scope-truth before navigation, not a missing destination.
• Alternatives considered: Add tenant-scoped operations routes or query-prefiltered viewers. Rejected because that would introduce new routing, new navigation semantics, and more RBAC surface area than this retrofit requires.

Decision 3: Use a state-driven CTA hierarchy instead of adding new embedded controls

• Decision: Model each embedded surface around a small CTA matrix: no run means one workflow-start action, an existing run means one primary inspect action, and any broader collection or monitoring links become explicitly secondary.
• Rationale: The current drift comes from equal-weight CTAs such as View all operations alongside per-row Open operation or inline Start verification beside an existing Open operation. A state matrix solves that with minimal code churn.
• Alternatives considered: Keep all current links and only rename them. Rejected because naming alone would not remove the competing-action problem described by Spec 172.

Decision 4: Let the owning page or wizard keep rerun controls while embedded surfaces focus on inspection

• Decision: On tenant detail, the existing page-level Verify configuration header action remains the rerun/start path when a verification run already exists, while the embedded widget focuses on inspecting the current run. On onboarding, the step-level workflow controls (Start verification or Refresh) remain the next-step controls, while report/technical-details links stay inspection-oriented.
• Rationale: The rerun affordance already exists on the owning surfaces. Reusing it avoids adding a second equal-weight CTA inside the embedded report widgets.
• Alternatives considered: Keep rerun/start controls inline inside every embedded surface state. Rejected because it produces the same CTA competition the feature is meant to eliminate.

Decision 5: Keep advanced monitoring links in diagnostics-only slots and gate them by existing access

• Decision: Retain any broader monitoring/admin operation link only in low-emphasis technical-details or diagnostics areas, and only when the operator can access that destination.
• Rationale: The technical-details modal already has an explicit advanced-monitoring affordance. Keeping it secondary preserves operator clarity without removing legitimate escalation paths for power users.
• Alternatives considered: Show advanced monitoring links beside every primary inspect CTA. Rejected because it weakens the single-primary-action rule and increases scope ambiguity.

Decision 6: Narrow governance through focused tests and baseline-exemption notes, not through a new widget framework

• Decision: Reuse the existing ActionSurfaceExemptions and ActionSurfaceContractTest model, tighten the relevant exemption wording if needed, and add focused widget/onboarding coverage instead of introducing widget-specific actionSurfaceDeclaration() plumbing.
• Rationale: Embedded widgets and report partials do not fit the existing table/page declaration model cleanly, and the codebase already recognizes that ManagedTenantOnboardingWizard is covered through dedicated conformance tests.
• Alternatives considered: Add a new generic embedded-surface declaration framework. Rejected because one concrete retrofit does not justify a new abstraction under ABSTR-001 and BLOAT-001.

Decision 7: Verify behavior with focused Pest and Livewire tests instead of broad string guards

• Decision: Extend the existing widget and onboarding feature tests to assert CTA count, scope cues, and advanced-link visibility directly on rendered surfaces.
• Rationale: The business truth here is UI hierarchy and scope behavior, not just string presence. Focused rendered-surface tests are more precise than grep-style bans and align with TEST-TRUTH-001.
• Alternatives considered: Add a repo-wide architecture or grep-style rule forbidding specific link combinations. Rejected because valid out-of-scope surfaces and diagnostics would require an exception list that encodes the same complexity this slice is avoiding.

Decision 8: Make scope explicit through placement and nearby copy rather than scope-first labels

• Decision: Any remaining collection drill-in from a tenant-detail surface should communicate broader admin scope through placement or helper text, not by inventing scope-first primary labels.
• Rationale: UI-NAMING-001 forbids making scope the primary verb-object label. The operator still needs to understand when a link leaves the tenant-local shell, but that should come from context and secondary explanation.
• Alternatives considered: Rename the main CTA to Open admin operations. Rejected because it over-rotates toward implementation language and conflicts with the repo's operator-facing naming rules.