ahri_tre_app/

access_request.rs

//! Study access-request workflows.
//!
//! This module owns the application semantics of a browser visitor submitting
//! a governance request. Transport adapters supply the selected datastore and
//! requester identity, while persistence adapters implement the narrow port.

use thiserror::Error;

pub use ahri_tre_core::{
    ApproveCustodianStudyAccessRequest, CustodianStudyAccessRequest,
    CustodianStudyAccessRequestApprovalOutcome, CustodianStudyAccessRequestApprovalPreflight,
    CustodianStudyAccessRequestDecision, CustodianStudyAccessRequestPort,
    CustodianStudyAccessRequestPortError, CustodianStudyAccessRequestQueuePort,
    CustodianStudyAccessRequestRejectionOutcome, CustodianStudyAccessRequestStatusFilter,
    CustodianStudyAccessRequests, ProvisionStudyAccessRequestWorkflowEntry,
    ReadyAccessRequestDatastore, ReadyAccessRequestDatastoreResolver,
    RecordCustodianStudyAccessRequestApproval, RejectCustodianStudyAccessRequest,
    RequesterStudyAccessRequest, RequesterStudyAccessRequestPort,
    RequesterStudyAccessRequestPortError, RequesterStudyAccessRequestWithdrawalOutcome,
    RequesterStudyAccessRequests, StudyAccessRequestDecision, StudyAccessRequestLifecycle,
    StudyAccessRequestSubmissionOutcome, StudyAccessRequestSubmissionPort,
    StudyAccessRequestSubmissionPortError, StudyAccessRequestWorkflowEntryPort,
    StudyAccessRequestWorkflowEntryPortError, SubmitStudyAccessRequest,
    SubmittedStudyAccessRequest,
};

/// Application failures for submitting a Study access request.
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
pub enum SubmitStudyAccessRequestError {
    #[error("selected datastore identity is invalid")]
    InvalidDatastoreIdentity,
    #[error("access-request service authority is unavailable")]
    AuthorityUnavailable,
    #[error("selected datastore is unavailable")]
    DatastoreUnavailable,
    #[error("study was not found in the selected datastore")]
    StudyNotFound,
    #[error("intended use is required")]
    IntendedUseRequired,
    #[error("a pending request already exists for this study")]
    DuplicatePendingRequest,
}

/// Application failures for requester-owned access-request lifecycle actions.
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
pub enum RequesterStudyAccessRequestError {
    #[error("selected datastore identity is invalid")]
    InvalidDatastoreIdentity,
    #[error("access-request service authority is unavailable")]
    AuthorityUnavailable,
    #[error("selected datastore is unavailable")]
    DatastoreUnavailable,
    #[error("request was not found for the current visitor")]
    RequestNotFound,
    #[error("request is not pending and cannot be withdrawn")]
    RequestNotPending,
    #[error("request has an invalid lifecycle state")]
    InvalidLifecycleState,
}

/// Application failures for custodian-owned access-request lifecycle actions.
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
pub enum CustodianStudyAccessRequestError {
    #[error("selected datastore identity is invalid")]
    InvalidDatastoreIdentity,
    #[error("access-request authority is unavailable")]
    AuthorityUnavailable,
    #[error("an authenticated TRE user session is required")]
    AuthenticatedTreUserRequired,
    #[error("selected datastore is unavailable")]
    DatastoreUnavailable,
    #[error("request was not found")]
    RequestNotFound,
    #[error("the authenticated TRE user is not a custodian for this study")]
    CustodianshipRequired,
    #[error("request is not pending")]
    RequestNotPending,
    #[error("request has an invalid lifecycle state")]
    InvalidLifecycleState,
}

/// Submits a pending Study access request without granting Study access or
/// datastore workflow entry.
pub fn submit_study_access_request(
    port: &mut dyn StudyAccessRequestSubmissionPort,
    mut request: SubmitStudyAccessRequest,
) -> Result<SubmittedStudyAccessRequest, SubmitStudyAccessRequestError> {
    request.intended_use = required_text(&request.intended_use)
        .ok_or(SubmitStudyAccessRequestError::IntendedUseRequired)?;
    request.contact = optional_text(request.contact.as_deref());
    request.affiliation = optional_text(request.affiliation.as_deref());

    match port
        .submit_study_access_request(&request)
        .map_err(map_port_error)?
    {
        StudyAccessRequestSubmissionOutcome::Submitted(submission) => Ok(submission),
        StudyAccessRequestSubmissionOutcome::StudyNotFound => {
            Err(SubmitStudyAccessRequestError::StudyNotFound)
        }
        StudyAccessRequestSubmissionOutcome::DuplicatePendingRequest => {
            Err(SubmitStudyAccessRequestError::DuplicatePendingRequest)
        }
    }
}

fn map_port_error(error: StudyAccessRequestSubmissionPortError) -> SubmitStudyAccessRequestError {
    match error {
        StudyAccessRequestSubmissionPortError::InvalidDatastoreIdentity => {
            SubmitStudyAccessRequestError::InvalidDatastoreIdentity
        }
        StudyAccessRequestSubmissionPortError::AuthorityUnavailable => {
            SubmitStudyAccessRequestError::AuthorityUnavailable
        }
        StudyAccessRequestSubmissionPortError::DatastoreUnavailable => {
            SubmitStudyAccessRequestError::DatastoreUnavailable
        }
    }
}

/// Lists access requests owned by the current requester in the selected
/// datastore.
pub fn list_requester_study_access_requests(
    port: &mut dyn RequesterStudyAccessRequestPort,
    scope: &RequesterStudyAccessRequests,
) -> Result<Vec<RequesterStudyAccessRequest>, RequesterStudyAccessRequestError> {
    port.list_requester_study_access_requests(scope)
        .map_err(map_requester_port_error)
}

/// Finds an access request only when it is owned by the current requester in
/// the selected datastore.
pub fn get_requester_study_access_request(
    port: &mut dyn RequesterStudyAccessRequestPort,
    scope: &RequesterStudyAccessRequests,
    request_id: uuid::Uuid,
) -> Result<RequesterStudyAccessRequest, RequesterStudyAccessRequestError> {
    port.get_requester_study_access_request(scope, request_id)
        .map_err(map_requester_port_error)?
        .ok_or(RequesterStudyAccessRequestError::RequestNotFound)
}

/// Withdraws a pending access request only when it is owned by the current
/// requester in the selected datastore. This workflow cannot grant access or
/// provision datastore workflow entry.
pub fn withdraw_requester_study_access_request(
    port: &mut dyn RequesterStudyAccessRequestPort,
    scope: &RequesterStudyAccessRequests,
    request_id: uuid::Uuid,
) -> Result<RequesterStudyAccessRequest, RequesterStudyAccessRequestError> {
    match port
        .withdraw_requester_study_access_request(scope, request_id)
        .map_err(map_requester_port_error)?
    {
        RequesterStudyAccessRequestWithdrawalOutcome::Withdrawn(request) => Ok(request),
        RequesterStudyAccessRequestWithdrawalOutcome::NotFound => {
            Err(RequesterStudyAccessRequestError::RequestNotFound)
        }
        RequesterStudyAccessRequestWithdrawalOutcome::NotPending => {
            Err(RequesterStudyAccessRequestError::RequestNotPending)
        }
    }
}

fn map_requester_port_error(
    error: RequesterStudyAccessRequestPortError,
) -> RequesterStudyAccessRequestError {
    match error {
        RequesterStudyAccessRequestPortError::InvalidDatastoreIdentity => {
            RequesterStudyAccessRequestError::InvalidDatastoreIdentity
        }
        RequesterStudyAccessRequestPortError::AuthorityUnavailable => {
            RequesterStudyAccessRequestError::AuthorityUnavailable
        }
        RequesterStudyAccessRequestPortError::DatastoreUnavailable => {
            RequesterStudyAccessRequestError::DatastoreUnavailable
        }
        RequesterStudyAccessRequestPortError::InvalidLifecycleState => {
            RequesterStudyAccessRequestError::InvalidLifecycleState
        }
    }
}

/// Lists Study access requests in one supported status that the authenticated
/// database actor is authorized to steward in the selected datastore.
pub fn list_custodian_study_access_requests(
    port: &mut dyn CustodianStudyAccessRequestQueuePort,
    scope: &CustodianStudyAccessRequests,
) -> Result<Vec<CustodianStudyAccessRequest>, CustodianStudyAccessRequestError> {
    port.list_custodian_study_access_requests(scope)
        .map_err(map_custodian_port_error)
}

/// Rejects a pending Study access request when the authenticated database
/// actor custodians its Study. Empty rejection reasons are normalized to none.
pub fn reject_custodian_study_access_request(
    port: &mut dyn CustodianStudyAccessRequestPort,
    mut rejection: RejectCustodianStudyAccessRequest,
) -> Result<CustodianStudyAccessRequest, CustodianStudyAccessRequestError> {
    rejection.reason = optional_text(rejection.reason.as_deref());
    match port
        .reject_custodian_study_access_request(&rejection)
        .map_err(map_custodian_port_error)?
    {
        CustodianStudyAccessRequestRejectionOutcome::Rejected(request) => Ok(*request),
        CustodianStudyAccessRequestRejectionOutcome::NotFound => {
            Err(CustodianStudyAccessRequestError::RequestNotFound)
        }
        CustodianStudyAccessRequestRejectionOutcome::NotCustodian => {
            Err(CustodianStudyAccessRequestError::CustodianshipRequired)
        }
        CustodianStudyAccessRequestRejectionOutcome::NotPending => {
            Err(CustodianStudyAccessRequestError::RequestNotPending)
        }
    }
}

/// Approves a pending Study access request in three ordered steps: verify the
/// authenticated custodian's scoped request, provision or reuse requester
/// workflow entry in that request's datastore, then record the governed
/// Study-access grant and decision. If the final step fails, workflow entry is
/// deliberately retained; a retry safely provisions it again and re-runs only
/// the governed decision without attempting compensation.
pub fn approve_custodian_study_access_request(
    custodian_port: &mut dyn CustodianStudyAccessRequestPort,
    workflow_entry_port: &mut dyn StudyAccessRequestWorkflowEntryPort,
    approval: ApproveCustodianStudyAccessRequest,
) -> Result<CustodianStudyAccessRequest, CustodianStudyAccessRequestError> {
    let requester_orcid = match custodian_port
        .preflight_custodian_study_access_request_approval(&approval)
        .map_err(map_custodian_port_error)?
    {
        CustodianStudyAccessRequestApprovalPreflight::Pending { requester_orcid } => {
            requester_orcid
        }
        CustodianStudyAccessRequestApprovalPreflight::NotFound => {
            return Err(CustodianStudyAccessRequestError::RequestNotFound);
        }
        CustodianStudyAccessRequestApprovalPreflight::NotCustodian => {
            return Err(CustodianStudyAccessRequestError::CustodianshipRequired);
        }
        CustodianStudyAccessRequestApprovalPreflight::NotPending => {
            return Err(CustodianStudyAccessRequestError::RequestNotPending);
        }
    };
    let requester_role = workflow_entry_port
        .provision_study_access_request_workflow_entry(&ProvisionStudyAccessRequestWorkflowEntry {
            datastore_id: approval.datastore_id,
            requester_orcid,
        })
        .map_err(map_workflow_entry_port_error)?;
    match custodian_port
        .record_custodian_study_access_request_approval(
            &RecordCustodianStudyAccessRequestApproval {
                datastore_id: approval.datastore_id,
                request_id: approval.request_id,
                requester_role,
            },
        )
        .map_err(map_custodian_port_error)?
    {
        CustodianStudyAccessRequestApprovalOutcome::Approved(request) => Ok(*request),
        CustodianStudyAccessRequestApprovalOutcome::NotPending => {
            Err(CustodianStudyAccessRequestError::RequestNotPending)
        }
    }
}

fn map_custodian_port_error(
    error: CustodianStudyAccessRequestPortError,
) -> CustodianStudyAccessRequestError {
    match error {
        CustodianStudyAccessRequestPortError::InvalidDatastoreIdentity => {
            CustodianStudyAccessRequestError::InvalidDatastoreIdentity
        }
        CustodianStudyAccessRequestPortError::AuthorityUnavailable => {
            CustodianStudyAccessRequestError::AuthorityUnavailable
        }
        CustodianStudyAccessRequestPortError::AuthenticatedTreUserRequired => {
            CustodianStudyAccessRequestError::AuthenticatedTreUserRequired
        }
        CustodianStudyAccessRequestPortError::CustodianshipRequired => {
            CustodianStudyAccessRequestError::CustodianshipRequired
        }
        CustodianStudyAccessRequestPortError::DatastoreUnavailable => {
            CustodianStudyAccessRequestError::DatastoreUnavailable
        }
        CustodianStudyAccessRequestPortError::InvalidLifecycleState => {
            CustodianStudyAccessRequestError::InvalidLifecycleState
        }
    }
}

fn map_workflow_entry_port_error(
    error: StudyAccessRequestWorkflowEntryPortError,
) -> CustodianStudyAccessRequestError {
    match error {
        StudyAccessRequestWorkflowEntryPortError::AuthorityUnavailable => {
            CustodianStudyAccessRequestError::AuthorityUnavailable
        }
        StudyAccessRequestWorkflowEntryPortError::DatastoreUnavailable => {
            CustodianStudyAccessRequestError::DatastoreUnavailable
        }
    }
}

fn required_text(value: &str) -> Option<String> {
    let value = value.trim();
    (!value.is_empty()).then(|| value.to_string())
}

fn optional_text(value: Option<&str>) -> Option<String> {
    value.and_then(required_text)
}

#[cfg(test)]
mod tests {
    use super::*;
    use ahri_tre_types::StudyId;
    use chrono::Utc;
    use std::collections::VecDeque;
    use uuid::Uuid;

    #[derive(Debug)]
    struct FakeSubmissionPort {
        result: Result<StudyAccessRequestSubmissionOutcome, StudyAccessRequestSubmissionPortError>,
        received: Vec<SubmitStudyAccessRequest>,
    }

    impl FakeSubmissionPort {
        fn returning(
            result: Result<
                StudyAccessRequestSubmissionOutcome,
                StudyAccessRequestSubmissionPortError,
            >,
        ) -> Self {
            Self {
                result,
                received: Vec::new(),
            }
        }
    }

    impl StudyAccessRequestSubmissionPort for FakeSubmissionPort {
        fn submit_study_access_request(
            &mut self,
            request: &SubmitStudyAccessRequest,
        ) -> Result<StudyAccessRequestSubmissionOutcome, StudyAccessRequestSubmissionPortError>
        {
            self.received.push(request.clone());
            self.result.clone()
        }
    }

    #[derive(Debug)]
    struct FakeRequesterPort {
        listed: Result<Vec<RequesterStudyAccessRequest>, RequesterStudyAccessRequestPortError>,
        fetched: Result<Option<RequesterStudyAccessRequest>, RequesterStudyAccessRequestPortError>,
        withdrawn: Result<
            RequesterStudyAccessRequestWithdrawalOutcome,
            RequesterStudyAccessRequestPortError,
        >,
        received_scopes: Vec<RequesterStudyAccessRequests>,
        received_request_ids: Vec<Uuid>,
    }

    impl RequesterStudyAccessRequestPort for FakeRequesterPort {
        fn list_requester_study_access_requests(
            &mut self,
            scope: &RequesterStudyAccessRequests,
        ) -> Result<Vec<RequesterStudyAccessRequest>, RequesterStudyAccessRequestPortError>
        {
            self.received_scopes.push(scope.clone());
            self.listed.clone()
        }

        fn get_requester_study_access_request(
            &mut self,
            scope: &RequesterStudyAccessRequests,
            request_id: Uuid,
        ) -> Result<Option<RequesterStudyAccessRequest>, RequesterStudyAccessRequestPortError>
        {
            self.received_scopes.push(scope.clone());
            self.received_request_ids.push(request_id);
            self.fetched.clone()
        }

        fn withdraw_requester_study_access_request(
            &mut self,
            scope: &RequesterStudyAccessRequests,
            request_id: Uuid,
        ) -> Result<
            RequesterStudyAccessRequestWithdrawalOutcome,
            RequesterStudyAccessRequestPortError,
        > {
            self.received_scopes.push(scope.clone());
            self.received_request_ids.push(request_id);
            self.withdrawn.clone()
        }
    }

    #[derive(Debug)]
    struct FakeCustodianPort {
        listed: Result<Vec<CustodianStudyAccessRequest>, CustodianStudyAccessRequestPortError>,
        rejected: Result<
            CustodianStudyAccessRequestRejectionOutcome,
            CustodianStudyAccessRequestPortError,
        >,
        preflight: VecDeque<
            Result<
                CustodianStudyAccessRequestApprovalPreflight,
                CustodianStudyAccessRequestPortError,
            >,
        >,
        recorded: VecDeque<
            Result<
                CustodianStudyAccessRequestApprovalOutcome,
                CustodianStudyAccessRequestPortError,
            >,
        >,
        received_scopes: Vec<CustodianStudyAccessRequests>,
        received_rejections: Vec<RejectCustodianStudyAccessRequest>,
        received_approval_preflights: Vec<ApproveCustodianStudyAccessRequest>,
        received_recorded_approvals: Vec<RecordCustodianStudyAccessRequestApproval>,
    }

    impl CustodianStudyAccessRequestQueuePort for FakeCustodianPort {
        fn list_custodian_study_access_requests(
            &mut self,
            scope: &CustodianStudyAccessRequests,
        ) -> Result<Vec<CustodianStudyAccessRequest>, CustodianStudyAccessRequestPortError>
        {
            self.received_scopes.push(*scope);
            self.listed.clone()
        }
    }

    impl CustodianStudyAccessRequestPort for FakeCustodianPort {
        fn reject_custodian_study_access_request(
            &mut self,
            rejection: &RejectCustodianStudyAccessRequest,
        ) -> Result<CustodianStudyAccessRequestRejectionOutcome, CustodianStudyAccessRequestPortError>
        {
            self.received_rejections.push(rejection.clone());
            self.rejected.clone()
        }

        fn preflight_custodian_study_access_request_approval(
            &mut self,
            approval: &ApproveCustodianStudyAccessRequest,
        ) -> Result<
            CustodianStudyAccessRequestApprovalPreflight,
            CustodianStudyAccessRequestPortError,
        > {
            self.received_approval_preflights.push(*approval);
            self.preflight
                .pop_front()
                .expect("fake preflight result is configured")
        }

        fn record_custodian_study_access_request_approval(
            &mut self,
            approval: &RecordCustodianStudyAccessRequestApproval,
        ) -> Result<CustodianStudyAccessRequestApprovalOutcome, CustodianStudyAccessRequestPortError>
        {
            self.received_recorded_approvals.push(approval.clone());
            self.recorded
                .pop_front()
                .expect("fake governed approval result is configured")
        }
    }

    #[derive(Debug)]
    struct FakeWorkflowEntryPort {
        results: VecDeque<Result<String, StudyAccessRequestWorkflowEntryPortError>>,
        received: Vec<ProvisionStudyAccessRequestWorkflowEntry>,
    }

    impl StudyAccessRequestWorkflowEntryPort for FakeWorkflowEntryPort {
        fn provision_study_access_request_workflow_entry(
            &mut self,
            provisioning: &ProvisionStudyAccessRequestWorkflowEntry,
        ) -> Result<String, StudyAccessRequestWorkflowEntryPortError> {
            self.received.push(provisioning.clone());
            self.results
                .pop_front()
                .expect("fake workflow-entry result is configured")
        }
    }

    fn requester_scope() -> RequesterStudyAccessRequests {
        RequesterStudyAccessRequests {
            datastore_id: Uuid::from_u128(1),
            requester_orcid: "0000-0001-2345-6789".to_string(),
        }
    }

    fn requester_record(lifecycle: StudyAccessRequestLifecycle) -> RequesterStudyAccessRequest {
        RequesterStudyAccessRequest {
            request_id: Uuid::from_u128(3),
            datastore_id: Uuid::from_u128(1),
            study_id: StudyId(Uuid::from_u128(2)),
            intended_use: "research".to_string(),
            contact: Some("researcher@example.test".to_string()),
            affiliation: None,
            lifecycle,
            submitted_at: Utc::now(),
            decision: StudyAccessRequestDecision {
                decided_at: None,
                reason: None,
            },
        }
    }

    fn custodian_scope() -> CustodianStudyAccessRequests {
        CustodianStudyAccessRequests {
            datastore_id: Uuid::from_u128(1),
            status: CustodianStudyAccessRequestStatusFilter::Rejected,
        }
    }

    fn custodian_record(lifecycle: StudyAccessRequestLifecycle) -> CustodianStudyAccessRequest {
        CustodianStudyAccessRequest {
            request_id: Uuid::from_u128(3),
            datastore_id: Uuid::from_u128(1),
            study_id: StudyId(Uuid::from_u128(2)),
            requester_orcid: "0000-0001-2345-6789".to_string(),
            intended_use: "research".to_string(),
            contact: Some("researcher@example.test".to_string()),
            affiliation: None,
            lifecycle,
            submitted_at: Utc::now(),
            decision: CustodianStudyAccessRequestDecision {
                decided_at: None,
                decided_by: None,
                reason: None,
            },
        }
    }

    fn custodian_port(
        listed: Result<Vec<CustodianStudyAccessRequest>, CustodianStudyAccessRequestPortError>,
        rejected: Result<
            CustodianStudyAccessRequestRejectionOutcome,
            CustodianStudyAccessRequestPortError,
        >,
    ) -> FakeCustodianPort {
        FakeCustodianPort {
            listed,
            rejected,
            preflight: VecDeque::from([Ok(
                CustodianStudyAccessRequestApprovalPreflight::NotPending,
            )]),
            recorded: VecDeque::from([Ok(CustodianStudyAccessRequestApprovalOutcome::NotPending)]),
            received_scopes: Vec::new(),
            received_rejections: Vec::new(),
            received_approval_preflights: Vec::new(),
            received_recorded_approvals: Vec::new(),
        }
    }

    fn requester_port(
        listed: Result<Vec<RequesterStudyAccessRequest>, RequesterStudyAccessRequestPortError>,
        fetched: Result<Option<RequesterStudyAccessRequest>, RequesterStudyAccessRequestPortError>,
        withdrawn: Result<
            RequesterStudyAccessRequestWithdrawalOutcome,
            RequesterStudyAccessRequestPortError,
        >,
    ) -> FakeRequesterPort {
        FakeRequesterPort {
            listed,
            fetched,
            withdrawn,
            received_scopes: Vec::new(),
            received_request_ids: Vec::new(),
        }
    }

    fn request() -> SubmitStudyAccessRequest {
        SubmitStudyAccessRequest {
            datastore_id: Uuid::from_u128(1),
            study_id: StudyId(Uuid::from_u128(2)),
            requester_orcid: "0000-0001-2345-6789".to_string(),
            requester_subject: "orcid-subject".to_string(),
            intended_use: "  controlled research  ".to_string(),
            contact: Some(" researcher@example.test ".to_string()),
            affiliation: Some("   ".to_string()),
        }
    }

    #[test]
    fn submission_passes_normalized_request_to_port_and_returns_submission() {
        let submitted_at = Utc::now();
        let mut port = FakeSubmissionPort::returning(Ok(
            StudyAccessRequestSubmissionOutcome::Submitted(SubmittedStudyAccessRequest {
                request_id: Uuid::from_u128(3),
                submitted_at,
            }),
        ));

        let result = submit_study_access_request(&mut port, request()).unwrap();

        assert_eq!(result.request_id, Uuid::from_u128(3));
        assert_eq!(result.submitted_at, submitted_at);
        assert_eq!(port.received.len(), 1);
        assert_eq!(port.received[0].intended_use, "controlled research");
        assert_eq!(
            port.received[0].contact.as_deref(),
            Some("researcher@example.test")
        );
        assert_eq!(port.received[0].affiliation, None);
    }

    #[test]
    fn submission_rejects_missing_intended_use_before_calling_port() {
        let mut port =
            FakeSubmissionPort::returning(Ok(StudyAccessRequestSubmissionOutcome::StudyNotFound));
        let mut submission = request();
        submission.intended_use = " \t ".to_string();

        let error = submit_study_access_request(&mut port, submission).unwrap_err();

        assert_eq!(error, SubmitStudyAccessRequestError::IntendedUseRequired);
        assert!(port.received.is_empty());
    }

    #[test]
    fn submission_preserves_semantic_and_infrastructure_failures() {
        let cases = [
            (
                Ok(StudyAccessRequestSubmissionOutcome::StudyNotFound),
                SubmitStudyAccessRequestError::StudyNotFound,
            ),
            (
                Ok(StudyAccessRequestSubmissionOutcome::DuplicatePendingRequest),
                SubmitStudyAccessRequestError::DuplicatePendingRequest,
            ),
            (
                Err(StudyAccessRequestSubmissionPortError::InvalidDatastoreIdentity),
                SubmitStudyAccessRequestError::InvalidDatastoreIdentity,
            ),
            (
                Err(StudyAccessRequestSubmissionPortError::AuthorityUnavailable),
                SubmitStudyAccessRequestError::AuthorityUnavailable,
            ),
            (
                Err(StudyAccessRequestSubmissionPortError::DatastoreUnavailable),
                SubmitStudyAccessRequestError::DatastoreUnavailable,
            ),
        ];

        for (result, expected) in cases {
            let mut port = FakeSubmissionPort::returning(result);
            assert_eq!(
                submit_study_access_request(&mut port, request()).unwrap_err(),
                expected
            );
            assert_eq!(port.received.len(), 1);
        }
    }

    #[test]
    fn requester_lifecycle_use_cases_preserve_requester_scope_and_records() {
        let pending = requester_record(StudyAccessRequestLifecycle::Pending);
        let withdrawn = requester_record(StudyAccessRequestLifecycle::Withdrawn);
        let mut port = requester_port(
            Ok(vec![pending.clone()]),
            Ok(Some(pending.clone())),
            Ok(RequesterStudyAccessRequestWithdrawalOutcome::Withdrawn(
                withdrawn.clone(),
            )),
        );
        let scope = requester_scope();

        assert_eq!(
            list_requester_study_access_requests(&mut port, &scope).unwrap(),
            vec![pending.clone()]
        );
        assert_eq!(
            get_requester_study_access_request(&mut port, &scope, pending.request_id).unwrap(),
            pending
        );
        assert_eq!(
            withdraw_requester_study_access_request(&mut port, &scope, withdrawn.request_id)
                .unwrap(),
            withdrawn
        );
        assert_eq!(
            port.received_scopes,
            vec![scope.clone(), scope.clone(), scope]
        );
        assert_eq!(
            port.received_request_ids,
            vec![Uuid::from_u128(3), Uuid::from_u128(3)]
        );
    }

    #[test]
    fn requester_lifecycle_use_cases_preserve_semantic_and_port_failures() {
        let cases = [
            (
                RequesterStudyAccessRequestPortError::InvalidDatastoreIdentity,
                RequesterStudyAccessRequestError::InvalidDatastoreIdentity,
            ),
            (
                RequesterStudyAccessRequestPortError::AuthorityUnavailable,
                RequesterStudyAccessRequestError::AuthorityUnavailable,
            ),
            (
                RequesterStudyAccessRequestPortError::DatastoreUnavailable,
                RequesterStudyAccessRequestError::DatastoreUnavailable,
            ),
            (
                RequesterStudyAccessRequestPortError::InvalidLifecycleState,
                RequesterStudyAccessRequestError::InvalidLifecycleState,
            ),
        ];
        for (port_error, expected) in cases {
            let mut port = requester_port(Err(port_error), Err(port_error), Err(port_error));
            let scope = requester_scope();
            assert_eq!(
                list_requester_study_access_requests(&mut port, &scope).unwrap_err(),
                expected
            );
            assert_eq!(
                get_requester_study_access_request(&mut port, &scope, Uuid::from_u128(3))
                    .unwrap_err(),
                expected
            );
            assert_eq!(
                withdraw_requester_study_access_request(&mut port, &scope, Uuid::from_u128(3))
                    .unwrap_err(),
                expected
            );
        }

        for (outcome, expected) in [
            (
                RequesterStudyAccessRequestWithdrawalOutcome::NotFound,
                RequesterStudyAccessRequestError::RequestNotFound,
            ),
            (
                RequesterStudyAccessRequestWithdrawalOutcome::NotPending,
                RequesterStudyAccessRequestError::RequestNotPending,
            ),
        ] {
            let mut port = requester_port(Ok(Vec::new()), Ok(None), Ok(outcome));
            assert_eq!(
                withdraw_requester_study_access_request(
                    &mut port,
                    &requester_scope(),
                    Uuid::from_u128(3)
                )
                .unwrap_err(),
                expected
            );
        }

        let mut port = requester_port(
            Ok(Vec::new()),
            Ok(None),
            Ok(RequesterStudyAccessRequestWithdrawalOutcome::NotFound),
        );
        assert_eq!(
            get_requester_study_access_request(&mut port, &requester_scope(), Uuid::from_u128(3))
                .unwrap_err(),
            RequesterStudyAccessRequestError::RequestNotFound
        );
    }

    #[test]
    fn custodian_use_cases_preserve_scope_and_normalize_rejection_reason() {
        let pending = custodian_record(StudyAccessRequestLifecycle::Pending);
        let rejected = CustodianStudyAccessRequest {
            lifecycle: StudyAccessRequestLifecycle::Rejected,
            decision: CustodianStudyAccessRequestDecision {
                decided_at: Some(Utc::now()),
                decided_by: Some("custodian".to_string()),
                reason: Some("outside approved purpose".to_string()),
            },
            ..pending.clone()
        };
        let mut port = custodian_port(
            Ok(vec![pending.clone()]),
            Ok(CustodianStudyAccessRequestRejectionOutcome::Rejected(
                Box::new(rejected.clone()),
            )),
        );
        let scope = custodian_scope();

        assert_eq!(
            list_custodian_study_access_requests(&mut port, &scope).unwrap(),
            vec![pending]
        );
        assert_eq!(
            reject_custodian_study_access_request(
                &mut port,
                RejectCustodianStudyAccessRequest {
                    datastore_id: scope.datastore_id,
                    request_id: rejected.request_id,
                    reason: Some("  outside approved purpose  ".to_string()),
                },
            )
            .unwrap(),
            rejected
        );
        assert_eq!(port.received_scopes, vec![scope]);
        assert_eq!(
            port.received_rejections[0].reason.as_deref(),
            Some("outside approved purpose")
        );
    }

    #[test]
    fn custodian_use_cases_preserve_authorization_lifecycle_and_port_failures() {
        for (outcome, expected) in [
            (
                CustodianStudyAccessRequestRejectionOutcome::NotFound,
                CustodianStudyAccessRequestError::RequestNotFound,
            ),
            (
                CustodianStudyAccessRequestRejectionOutcome::NotCustodian,
                CustodianStudyAccessRequestError::CustodianshipRequired,
            ),
            (
                CustodianStudyAccessRequestRejectionOutcome::NotPending,
                CustodianStudyAccessRequestError::RequestNotPending,
            ),
        ] {
            let mut port = custodian_port(Ok(Vec::new()), Ok(outcome));
            assert_eq!(
                reject_custodian_study_access_request(
                    &mut port,
                    RejectCustodianStudyAccessRequest {
                        datastore_id: Uuid::from_u128(1),
                        request_id: Uuid::from_u128(3),
                        reason: Some("   ".to_string()),
                    },
                )
                .unwrap_err(),
                expected
            );
            assert_eq!(port.received_rejections[0].reason, None);
        }

        for (port_error, expected) in [
            (
                CustodianStudyAccessRequestPortError::InvalidDatastoreIdentity,
                CustodianStudyAccessRequestError::InvalidDatastoreIdentity,
            ),
            (
                CustodianStudyAccessRequestPortError::AuthorityUnavailable,
                CustodianStudyAccessRequestError::AuthorityUnavailable,
            ),
            (
                CustodianStudyAccessRequestPortError::AuthenticatedTreUserRequired,
                CustodianStudyAccessRequestError::AuthenticatedTreUserRequired,
            ),
            (
                CustodianStudyAccessRequestPortError::CustodianshipRequired,
                CustodianStudyAccessRequestError::CustodianshipRequired,
            ),
            (
                CustodianStudyAccessRequestPortError::DatastoreUnavailable,
                CustodianStudyAccessRequestError::DatastoreUnavailable,
            ),
            (
                CustodianStudyAccessRequestPortError::InvalidLifecycleState,
                CustodianStudyAccessRequestError::InvalidLifecycleState,
            ),
        ] {
            let mut port = custodian_port(Err(port_error), Err(port_error));
            assert_eq!(
                list_custodian_study_access_requests(&mut port, &custodian_scope()).unwrap_err(),
                expected
            );
            assert_eq!(
                reject_custodian_study_access_request(
                    &mut port,
                    RejectCustodianStudyAccessRequest {
                        datastore_id: Uuid::from_u128(1),
                        request_id: Uuid::from_u128(3),
                        reason: None,
                    },
                )
                .unwrap_err(),
                expected
            );
        }
    }

    #[test]
    fn approval_provisions_only_the_preflighted_request_datastore_then_records_grant() {
        let approved = CustodianStudyAccessRequest {
            lifecycle: StudyAccessRequestLifecycle::Approved,
            decision: CustodianStudyAccessRequestDecision {
                decided_at: Some(Utc::now()),
                decided_by: Some("custodian".to_string()),
                reason: None,
            },
            ..custodian_record(StudyAccessRequestLifecycle::Pending)
        };
        let approval = ApproveCustodianStudyAccessRequest {
            datastore_id: Uuid::from_u128(1),
            request_id: Uuid::from_u128(3),
        };
        let mut custodian = FakeCustodianPort {
            listed: Ok(Vec::new()),
            rejected: Ok(CustodianStudyAccessRequestRejectionOutcome::NotPending),
            preflight: VecDeque::from([Ok(
                CustodianStudyAccessRequestApprovalPreflight::Pending {
                    requester_orcid: "0000-0001-2345-6789".to_string(),
                },
            )]),
            recorded: VecDeque::from([Ok(CustodianStudyAccessRequestApprovalOutcome::Approved(
                Box::new(approved.clone()),
            ))]),
            received_scopes: Vec::new(),
            received_rejections: Vec::new(),
            received_approval_preflights: Vec::new(),
            received_recorded_approvals: Vec::new(),
        };
        let mut workflow_entry = FakeWorkflowEntryPort {
            results: VecDeque::from([Ok("tre_orcid_0000_0001_2345_6789".to_string())]),
            received: Vec::new(),
        };

        assert_eq!(
            approve_custodian_study_access_request(&mut custodian, &mut workflow_entry, approval)
                .unwrap(),
            approved
        );
        assert_eq!(custodian.received_approval_preflights, vec![approval]);
        assert_eq!(
            workflow_entry.received,
            vec![ProvisionStudyAccessRequestWorkflowEntry {
                datastore_id: approval.datastore_id,
                requester_orcid: "0000-0001-2345-6789".to_string(),
            }]
        );
        assert_eq!(
            custodian.received_recorded_approvals,
            vec![RecordCustodianStudyAccessRequestApproval {
                datastore_id: approval.datastore_id,
                request_id: approval.request_id,
                requester_role: "tre_orcid_0000_0001_2345_6789".to_string(),
            }]
        );
    }

    #[test]
    fn approval_does_not_record_a_grant_when_workflow_entry_provisioning_fails() {
        let approval = ApproveCustodianStudyAccessRequest {
            datastore_id: Uuid::from_u128(1),
            request_id: Uuid::from_u128(3),
        };
        let mut custodian = FakeCustodianPort {
            listed: Ok(Vec::new()),
            rejected: Ok(CustodianStudyAccessRequestRejectionOutcome::NotPending),
            preflight: VecDeque::from([Ok(
                CustodianStudyAccessRequestApprovalPreflight::Pending {
                    requester_orcid: "0000-0001-2345-6789".to_string(),
                },
            )]),
            recorded: VecDeque::new(),
            received_scopes: Vec::new(),
            received_rejections: Vec::new(),
            received_approval_preflights: Vec::new(),
            received_recorded_approvals: Vec::new(),
        };
        let mut workflow_entry = FakeWorkflowEntryPort {
            results: VecDeque::from([Err(
                StudyAccessRequestWorkflowEntryPortError::DatastoreUnavailable,
            )]),
            received: Vec::new(),
        };

        assert_eq!(
            approve_custodian_study_access_request(&mut custodian, &mut workflow_entry, approval)
                .unwrap_err(),
            CustodianStudyAccessRequestError::DatastoreUnavailable
        );
        assert_eq!(custodian.received_approval_preflights, vec![approval]);
        assert_eq!(workflow_entry.received.len(), 1);
        assert!(custodian.received_recorded_approvals.is_empty());
    }

    #[test]
    fn approval_preserves_preflight_authorization_and_lifecycle_outcomes() {
        let approval = ApproveCustodianStudyAccessRequest {
            datastore_id: Uuid::from_u128(1),
            request_id: Uuid::from_u128(3),
        };
        for (preflight, expected) in [
            (
                CustodianStudyAccessRequestApprovalPreflight::NotFound,
                CustodianStudyAccessRequestError::RequestNotFound,
            ),
            (
                CustodianStudyAccessRequestApprovalPreflight::NotCustodian,
                CustodianStudyAccessRequestError::CustodianshipRequired,
            ),
            (
                CustodianStudyAccessRequestApprovalPreflight::NotPending,
                CustodianStudyAccessRequestError::RequestNotPending,
            ),
        ] {
            let mut custodian = custodian_port(
                Ok(Vec::new()),
                Ok(CustodianStudyAccessRequestRejectionOutcome::NotPending),
            );
            custodian.preflight = VecDeque::from([Ok(preflight)]);
            let mut workflow_entry = FakeWorkflowEntryPort {
                results: VecDeque::from([Ok("unexpected".to_string())]),
                received: Vec::new(),
            };

            assert_eq!(
                approve_custodian_study_access_request(
                    &mut custodian,
                    &mut workflow_entry,
                    approval,
                )
                .unwrap_err(),
                expected
            );
            assert!(workflow_entry.received.is_empty());
            assert!(custodian.received_recorded_approvals.is_empty());
        }

        let mut invalid_lifecycle = custodian_port(
            Ok(Vec::new()),
            Ok(CustodianStudyAccessRequestRejectionOutcome::NotPending),
        );
        invalid_lifecycle.preflight = VecDeque::from([Err(
            CustodianStudyAccessRequestPortError::InvalidLifecycleState,
        )]);
        let mut workflow_entry = FakeWorkflowEntryPort {
            results: VecDeque::from([Ok("unexpected".to_string())]),
            received: Vec::new(),
        };
        assert_eq!(
            approve_custodian_study_access_request(
                &mut invalid_lifecycle,
                &mut workflow_entry,
                approval,
            )
            .unwrap_err(),
            CustodianStudyAccessRequestError::InvalidLifecycleState
        );
        assert!(workflow_entry.received.is_empty());
        assert!(invalid_lifecycle.received_recorded_approvals.is_empty());
    }

    #[test]
    fn approval_retry_retains_workflow_entry_after_governed_decision_failure() {
        let approval = ApproveCustodianStudyAccessRequest {
            datastore_id: Uuid::from_u128(1),
            request_id: Uuid::from_u128(3),
        };
        let approved = CustodianStudyAccessRequest {
            lifecycle: StudyAccessRequestLifecycle::Approved,
            ..custodian_record(StudyAccessRequestLifecycle::Pending)
        };
        let mut custodian = FakeCustodianPort {
            listed: Ok(Vec::new()),
            rejected: Ok(CustodianStudyAccessRequestRejectionOutcome::NotPending),
            preflight: VecDeque::from([
                Ok(CustodianStudyAccessRequestApprovalPreflight::Pending {
                    requester_orcid: "0000-0001-2345-6789".to_string(),
                }),
                Ok(CustodianStudyAccessRequestApprovalPreflight::Pending {
                    requester_orcid: "0000-0001-2345-6789".to_string(),
                }),
            ]),
            recorded: VecDeque::from([
                Err(CustodianStudyAccessRequestPortError::DatastoreUnavailable),
                Ok(CustodianStudyAccessRequestApprovalOutcome::Approved(
                    Box::new(approved.clone()),
                )),
            ]),
            received_scopes: Vec::new(),
            received_rejections: Vec::new(),
            received_approval_preflights: Vec::new(),
            received_recorded_approvals: Vec::new(),
        };
        let mut workflow_entry = FakeWorkflowEntryPort {
            results: VecDeque::from([
                Ok("tre_orcid_0000_0001_2345_6789".to_string()),
                Ok("tre_orcid_0000_0001_2345_6789".to_string()),
            ]),
            received: Vec::new(),
        };

        assert_eq!(
            approve_custodian_study_access_request(&mut custodian, &mut workflow_entry, approval)
                .unwrap_err(),
            CustodianStudyAccessRequestError::DatastoreUnavailable
        );
        assert_eq!(
            approve_custodian_study_access_request(&mut custodian, &mut workflow_entry, approval)
                .unwrap(),
            approved
        );
        assert_eq!(workflow_entry.received.len(), 2);
        assert_eq!(custodian.received_recorded_approvals.len(), 2);
        assert!(workflow_entry.results.is_empty());
    }
}