TenantAtlas/specs/142-rbac-role-definition-diff-ux-upgrade/research.md

Research: RBAC Role Definition Diff UX Upgrade

Decision 1: Reuse the existing shared diff foundation instead of extending it broadly

• Decision: Build this feature as a thin RBAC consumer on top of the existing App\Support\Diff classes and resources/views/filament/partials/diff/* partials introduced by Spec 141.
• Rationale: The shared presenter, DTOs, centralized badge mapping, summary partial, row partials, and inline list partial already exist. The current gap is consumer adoption on the RBAC finding detail surface, not missing foundation primitives.
• Alternatives considered:
  • Extend the shared foundation first with additional generic abstractions. Rejected because it broadens scope without first validating the current foundation on a real surface.
  • Keep the RBAC Blade view custom and copy over only visual classes. Rejected because it would duplicate summary, row-state, and value-formatting logic again.

Decision 2: Add a thin RBAC-specific shaping adapter at the consumer boundary

• Decision: Introduce a small RBAC-specific builder that reads finding.evidence_jsonb.rbac_role_definition, applies label/order/list-field rules, and outputs DiffPresentation for the Blade consumer.
• Rationale: The spec explicitly allows consumer-local shaping while keeping the underlying comparison engine authoritative. This avoids pushing RBAC-specific label maps and ordering rules into generic shared classes.
• Alternatives considered:
  • Compute RBAC-specific view semantics directly in Blade. Rejected because the current one-off view already demonstrates why that becomes hard to maintain and test.
  • Change the baseline comparison job payload to emit a render-ready shared shape. Rejected because this spec is presentation-only and must not rewrite the authoritative diff producer.

Decision 3: Treat Allowed Actions as the primary explicit list-diff field

• Decision: Use explicit RBAC field designation to render Allowed Actions, and any other simple list-like RBAC fields that fit the same shape, through the shared inline list partial.
• Rationale: Allowed Actions is the clearest operator pain point and already appears as array data in the RBAC evidence payload. Explicit consumer-local designation is safer than inferring every array field automatically.
• Alternatives considered:
  • Rely only on automatic list detection. Rejected because RBAC presentation needs predictable behavior for operator-facing fields, not just shape-based guesses.
  • Keep side-by-side text blocks for permission fields. Rejected because that preserves the main usability problem this spec exists to fix.

Decision 4: Prefer deterministic logical row order over interactive sorting

• Decision: Render RBAC rows in a stable, review-friendly order using an explicit consumer ordering strategy with alphabetical fallback.
• Rationale: The spec prioritizes predictable review readability over advanced interactive sorting. Operators should see core role-definition metadata first and permission-block details after that.
• Alternatives considered:
  • Pure alphabetical ordering from the shared presenter only. Rejected because it is deterministic but not ideal for operator review.
  • User-driven sorting or grouping controls. Rejected because it adds UI complexity that is out of scope for this consumer hardening pass.

Decision 5: Do not ship the optional “show only changes” toggle in the first pass

• Decision: Plan the implementation without a local toggle unless it proves trivial during implementation.
• Rationale: The spec makes the toggle optional and explicitly says the default view must already be understandable. The shared changed/unchanged row styling already provides the core value with less interaction risk.
• Alternatives considered:
  • Make the toggle part of the required implementation. Rejected because it adds Livewire/Alpine behavior without being necessary to satisfy the primary goals.
  • Collapse unchanged rows by default. Rejected because the product decision for this spec favors quieter audit context rather than aggressive hiding.

Decision 6: Use existing feature and support tests as the regression backbone

• Decision: Extend tests/Feature/Filament/FindingViewRbacEvidenceTest.php for consumer behavior and only add focused unit/support coverage where the RBAC-specific builder or shared rendering needs it.
• Rationale: The repo already has strong shared diff tests for presenter logic, value stringification, badges, and shared partials. The missing confidence is at the RBAC consumer integration layer.
• Alternatives considered:
  • Add only feature tests. Rejected because any new RBAC builder would benefit from targeted unit coverage for ordering and field designation.
  • Add browser tests. Rejected because the surface can be validated well through existing Pest feature/view tests for this scope.

Decision 7: Keep deployment and asset implications unchanged

• Decision: Use existing Blade partials and Tailwind/Filament styling without adding new asset bundles or on-demand asset registration.
• Rationale: The feature is a server-rendered Blade composition change within an existing Filament page. No new JS or CSS distribution mechanism is necessary.
• Alternatives considered:
  • Add consumer-specific JS for list diffing or filters. Rejected because the spec explicitly avoids heavy client-side diffing and over-building advanced controls.
  • Add dedicated panel assets for the RBAC diff region. Rejected because the shared partials and existing Filament/Tailwind classes are sufficient.