Groom the Fusion roles module feature and user stories

[odinr]

Type: Task
Target: Q4 2026
Parent: #5272
Ordering: Blocks implementation stories

Warning

The RolesV2 API surface, legacy compatibility, framework package boundary, and browser-side authorization semantics are intentionally unresolved. This task must settle those contracts before implementation stories are marked ready.

Objective

Turn the roles module placeholder into an implementation-ready feature with an agreed minimum viable scope, architecture, security guidance, dependency order, and testable user stories for Q4 2026.

Research inputs

• RolesV2 account endpoints for access-role assignments, active access-role assignments, claimable-role assignments, activation, and deactivation.
• RolesV2 concepts: systems, access roles, scopes, role assignments, claimable roles, and assignment validity.
• Existing Fusion module conventions: configurator, provider, module registration, app module integration, and React hooks.
• Existing role activation work in Add role activation to the dev portal PersonSideSheet #5230.
• Fusion Roles documentation for client integration and the requirement to enforce authorization on trusted backends.

Scope

• Confirm the app-developer and end-user workflows that belong in the first delivery.
• Define the framework-agnostic module contract and the app/React consumption surface.
• Decide RolesV2 endpoint, service discovery, authentication, identity, paging, caching, and refresh behavior.
• Decide whether claimable-role activation is part of the first delivery or a later story.
• Define the compatibility position for the legacy Roles service and People API role data.
• Produce estimated, dependency-ordered user stories with testable scenarios and Q4 sequencing.

Implementation is out of scope for this task.

Grooming checklist

• Validate the primary personas and workflows with app developers and RolesV2 owners.
• Confirm RolesV2 as the source of truth and document the required service discovery key, scopes, endpoint stability, and environment availability.
• Select the minimum consumer operations: current-user assignments, active assignments, scoped checks, claimable assignments, activation/deactivation, and refresh.
• Define typed domain models and identify which RolesV2 details remain visible to consumers.
• Define module configuration, provider responsibilities, initialization, disposal, and host/app registration.
• Define React hook responsibilities, query keys, loading/error/empty state, refresh, mutation state, and cache invalidation.
• Decide how the current account is resolved and how account changes or authentication changes invalidate state.
• Define paging and OData behavior so hooks cannot silently return incomplete authorization-related data.
• Document that frontend checks are advisory UI behavior and that protected operations require backend authorization.
• Decide legacy Roles/People API compatibility, migration guidance, and explicit non-goals.
• Identify reusable requirements or code boundaries from Add role activation to the dev portal PersonSideSheet #5230.
• Agree package names, ownership, test strategy, documentation, and cookbook coverage.
• Split the approved scope into dependency-ordered User Story issues and link them to the feature.
• Size the stories and agree the Q4 2026 delivery sequence, dependencies, and release criteria.

Candidate story split to validate

1. Consume current-user active access roles: expose typed assignment data with complete loading, error, empty, paging, and refresh behavior.
2. Evaluate global and resource-scoped roles: provide a consistent role-check API with explicit scope and validity semantics.
3. Consume roles from React applications: provide app-level hooks that compose the module contract and react to account or assignment changes.
4. Consume and activate claimable roles: expose eligible assignments and safe activation/deactivation mutation state if included in the minimum viable scope.
5. Configure and adopt the roles module: wire service discovery/authentication, document security boundaries, and provide a runnable cookbook migration path.

Acceptance criteria

• The feature has an approved in-scope/out-of-scope boundary and measurable completion criteria.
• The RolesV2 owners have confirmed the selected contracts and service configuration assumptions.
• The module and React package boundaries, public responsibilities, and state lifecycle are recorded.
• Security guidance explicitly separates role-aware UI from authoritative server-side access control.
• Legacy compatibility and migration expectations are explicit.
• Each approved user story has a role-centered statement, Given/When/Then scenarios, validation approach, dependencies, and an estimate.
• User stories are ordered and linked under the feature, with this grooming task preceding implementation.
• A Q4 2026 delivery sequence and release verification plan are agreed.

Dependencies and risks

• Requires participation from a RolesV2 owner and a Fusion Framework module maintainer.
• Backend and frontend work share an API and state contract; implementation must not split before that contract is approved.
• Claimable-role activation may introduce mutation, expiry, and refresh complexity that warrants a separate delivery slice.
• Milestone assignment is pending confirmation that the repository has a matching Q4 2026 milestone.