vpr_core/repositories/

clinical.rs

//! Patient clinical records management.
//!
//! This module handles the creation, linking, and maintenance of per-patient
//! clinical record repositories within the Versioned Patient Repository (VPR).
//! Clinical data is stored in lines with OpenEHR Reference Model (RM) structures.
//! The module initialises new records from validated clinical templates, enforces
//! directory sharding for scalable storage, and ensures all operations are
//! version-controlled through Git with optional cryptographic signing.

use crate::author::Author;
use crate::config::CoreConfig;
use crate::constants::{CLINICAL_DIR_NAME, DEFAULT_GITIGNORE};
use crate::error::{PatientError, PatientResult};
use crate::paths::{
    clinical::{ehr_status::EhrStatusFile, letter::LetterPaths},
    common::GitIgnoreFile,
};
use crate::repositories::shared::create_uuid_and_shard_dir;
use crate::NonEmptyText;

// TODO: need to check if this is really needed
#[cfg(test)]
use crate::repositories::shared::create_uuid_and_shard_dir_with_source;
use crate::versioned_files::{
    ClinicalDomain::Record, FileToWrite, VersionedFileService, VprCommitAction, VprCommitDomain,
    VprCommitMessage,
};
use crate::ShardableUuid;
use openehr::{
    extract_rm_version, validate_namespace_uri_safe, ClinicalList, EhrId, EhrStatus,
    ExternalReference, Letter, LetterData,
};
use std::{
    fs,
    path::{Path, PathBuf},
    sync::Arc,
};
use vpr_uuid::{Sha256Hash, TimestampId, TimestampIdGenerator};

#[cfg(test)]
use std::io::ErrorKind;
use uuid::Uuid;

/// Marker type: clinical record does not yet exist.
///
/// This is a zero-sized type used in the type-state pattern to indicate that
/// a [`ClinicalService`] has not yet been initialised. Services in this state
/// can only call [`ClinicalService::initialise()`] to create a new clinical record.
///
/// # Type Safety
///
/// The type system prevents you from calling operations that require an existing
/// clinical record (like [`link_to_demographics`](ClinicalService::link_to_demographics))
/// when the service is in the `Uninitialised` state.
#[derive(Clone, Copy, Debug)]
pub struct Uninitialised;

/// Marker type: clinical record exists.
///
/// This type is used in the type-state pattern to indicate that a [`ClinicalService`]
/// has been initialised and has a valid clinical record with a known ID.
///
/// Services in this state can call operations that require an existing clinical record,
/// such as [`link_to_demographics`](ClinicalService::link_to_demographics).
///
/// # Fields
///
/// The clinical ID is stored privately and accessed via the
/// [`clinical_id()`](ClinicalService::clinical_id) method.
#[derive(Clone, Copy, Debug)]
pub struct Initialised {
    clinical_id: Uuid,
}

/// Result of reading an existing letter.
///
/// Contains the body content and parsed composition metadata.
#[derive(Debug, Clone)]
pub struct ReadLetterResult {
    /// The Markdown content from body.md
    pub body_content: NonEmptyText,
    /// Parsed composition metadata from composition.yaml
    pub letter_data: LetterData,
}

/// Metadata for a file attachment in a clinical letter.
///
/// This structure contains the information needed to reference an attached file
/// from a letter composition, including both the file storage details and
/// attachment-specific metadata.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct AttachmentMetadata {
    /// Name of the attachment metadata file (e.g., "attachment_1.yaml")
    pub metadata_filename: NonEmptyText,
    /// SHA-256 hash of the file content
    pub hash: Sha256Hash,
    /// Path to the file in the files storage (relative to repository root)
    pub file_storage_path: NonEmptyText,
    /// Size of the file in bytes
    pub size_bytes: u64,
    /// Detected media type (MIME type)
    pub media_type: Option<NonEmptyText>,
    /// Original filename from the source
    pub original_filename: NonEmptyText,
}

/// Result of reading letter attachments.
///
/// Contains the attachment metadata and the actual file content.
#[derive(Debug, Clone)]
pub struct LetterAttachment {
    /// Metadata about the attachment
    pub metadata: AttachmentMetadata,
    /// The binary content of the file
    pub content: Vec<u8>,
}

/// Service for managing clinical record operations.
///
/// This service uses the type-state pattern to enforce correct usage at compile time.
/// The generic parameter `S` can be either [`Uninitialised`] or [`Initialised`],
/// determining which operations are available.
///
/// # Type States
///
/// - `ClinicalService<Uninitialised>` - Created via [`new()`](ClinicalService::new).
///   Can only call [`initialise()`](ClinicalService::initialise).
///
/// - `ClinicalService<Initialised>` - Created via [`with_id()`](ClinicalService::with_id)
///   or returned from [`initialise()`](ClinicalService::initialise). Can call operations
///   like [`link_to_demographics()`](ClinicalService::link_to_demographics).
#[derive(Clone, Debug)]
pub struct ClinicalService<S> {
    cfg: Arc<CoreConfig>,
    state: S,
}

impl ClinicalService<Uninitialised> {
    /// Creates a new `ClinicalService` in the uninitialised state.
    ///
    /// This is the starting point for creating a new clinical record. The returned
    /// service can only call [`initialise()`](Self::initialise) to create the record.
    ///
    /// # Arguments
    ///
    /// * `cfg` - The core configuration containing paths, templates, and system settings.
    ///
    /// # Returns
    ///
    /// A `ClinicalService<Uninitialised>` ready to initialise a new clinical record.
    pub fn new(cfg: Arc<CoreConfig>) -> Self {
        Self {
            cfg,
            state: Uninitialised,
        }
    }
}

impl ClinicalService<Initialised> {
    /// Creates a `ClinicalService` in the initialised state with an existing clinical ID.
    ///
    /// Use this when you already have a clinical record and want to perform operations on it,
    /// such as linking to demographics or updating the EHR status.
    ///
    /// # Arguments
    ///
    /// * `cfg` - The core configuration containing paths, templates, and system settings.
    /// * `clinical_id` - The UUID of an existing clinical record.
    ///
    /// # Returns
    ///
    /// A `ClinicalService<Initialised>` ready to operate on the specified clinical record.
    ///
    /// # Note
    ///
    /// This constructor does not validate that the clinical record actually exists.
    /// Operations on a non-existent record will fail at runtime.
    pub fn with_id(cfg: Arc<CoreConfig>, clinical_id: Uuid) -> Self {
        Self {
            cfg,
            state: Initialised { clinical_id },
        }
    }

    /// Returns the clinical ID for this initialised service.
    ///
    /// # Returns
    ///
    /// The UUID of the clinical record associated with this service.
    pub fn clinical_id(&self) -> Uuid {
        self.state.clinical_id
    }
}

impl ClinicalService<Uninitialised> {
    /// Initialises a new clinical record for a patient.
    ///
    /// This function creates a new clinical entry with a unique UUID, stores it in a sharded
    /// directory structure, copies the clinical template into the patient's directory, writes an
    /// initial `ehr_status.yaml`, and initialises a Git repository for version control.
    ///
    /// **This method consumes `self`** and returns a new `ClinicalService<Initialised>` on success,
    /// enforcing at compile time that you cannot call `initialise()` twice on the same service.
    ///
    /// # Arguments
    ///
    /// * `author` - The author information for the initial Git commit. Must have a non-empty name.
    /// * `care_location` - High-level organisational location for the commit (e.g. hospital name).
    ///   Must be a non-empty string.
    ///
    /// # Returns
    ///
    /// Returns `ClinicalService<Initialised>` containing the newly created clinical record.
    /// Use [`clinical_id()`](ClinicalService::clinical_id) to get the UUID.
    ///
    /// # Errors
    ///
    /// Returns a `PatientError` if:
    /// - The author's name is empty or whitespace-only ([`PatientError::MissingAuthorName`])
    /// - The care location is empty or whitespace-only ([`PatientError::MissingCareLocation`])
    /// - Required inputs or configuration are invalid ([`PatientError::InvalidInput`])
    /// - The clinical template cannot be located or is invalid
    /// - A unique patient directory cannot be allocated after 5 attempts
    /// - File or directory operations fail while creating the record or copying templates ([`PatientError::FileWrite`])
    /// - Writing `ehr_status.yaml` fails
    /// - Git repository initialisation fails (e.g., [`PatientError::GitInit`])
    /// - The initial commit fails (e.g., certificate/signature mismatch)
    /// - Cleanup of a partially-created record directory fails ([`PatientError::CleanupAfterInitialiseFailed`])
    pub fn initialise(
        self,
        author: Author,
        care_location: NonEmptyText,
    ) -> PatientResult<ClinicalService<Initialised>> {
        author.validate_commit_author()?;

        let clinical_dir = self.clinical_dir();
        let (clinical_uuid, patient_dir) = create_uuid_and_shard_dir(&clinical_dir)?;

        let commit_message = VprCommitMessage::new(
            VprCommitDomain::Clinical(Record),
            VprCommitAction::Create,
            "Initialised the clinical record",
            care_location,
        )?;

        let rm_version = self.cfg.rm_system_version();

        // Prepare ehr_status.yaml content
        let ehr_status_yaml = EhrStatus::render(
            rm_version,
            None,
            Some(&EhrId::from_uuid(clinical_uuid.uuid())),
            None,
        )?;

        let files = [
            FileToWrite {
                relative_path: Path::new(GitIgnoreFile::NAME),
                content: DEFAULT_GITIGNORE,
                old_content: None,
            },
            FileToWrite {
                relative_path: Path::new(EhrStatusFile::NAME),
                content: &ehr_status_yaml,
                old_content: None,
            },
        ];

        VersionedFileService::init_and_commit(&patient_dir, &author, &commit_message, &files)?;

        Ok(ClinicalService {
            cfg: self.cfg,
            state: Initialised {
                clinical_id: clinical_uuid.uuid(),
            },
        })
    }
}

impl ClinicalService<Initialised> {
    /// Links the clinical record to the patient's demographics.
    ///
    /// This function updates the clinical record's `ehr_status.yaml` file to include an
    /// external reference to the patient's demographics record.
    ///
    /// The clinical UUID is obtained from the service's internal state (via [`clinical_id()`](Self::clinical_id)),
    /// ensuring type safety and preventing mismatched UUIDs.
    ///
    /// # Arguments
    ///
    /// * `author` - The author information for the Git commit recording this change.
    ///   Must have a non-empty name.
    /// * `care_location` - High-level organisational location for the commit (e.g. hospital name).
    ///   Must be a non-empty string.
    /// * `demographics_uuid` - The UUID of the associated patient demographics record.
    ///   Must be a canonical 32-character lowercase hex string.
    /// * `namespace` - Optional namespace for the external reference URI. If `None`, uses the
    ///   value configured in [`CoreConfig`]. The namespace must be URI-safe (no special characters
    ///   like `<`, `>`, `/`, `\`).
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on success. The `ehr_status.yaml` file is updated and committed to Git.
    ///
    /// # Errors
    ///
    /// Returns a `PatientError` if:
    /// - The author's name is empty or whitespace-only ([`PatientError::MissingAuthorName`])
    /// - The care location is empty or whitespace-only ([`PatientError::MissingCareLocation`])
    /// - The demographics UUID cannot be parsed ([`PatientError::Uuid`])
    /// - The namespace is invalid/unsafe for embedding into a `ehr://{namespace}/mpi` URI ([`PatientError::InvalidInput`])
    /// - The `ehr_status.yaml` file does not exist ([`PatientError::InvalidInput`])
    /// - Reading or writing `ehr_status.yaml` fails ([`PatientError::FileRead`] or [`PatientError::FileWrite`])
    /// - The existing `ehr_status.yaml` cannot be parsed ([`PatientError::Openehr`])
    /// - Git commit fails (various Git-related error variants)
    ///
    /// # Safety & Rollback
    ///
    /// If the file write or Git commit fails, this method attempts to restore the previous
    /// content of `ehr_status.yaml`.
    pub fn link_to_demographics(
        &self,
        author: &Author,
        care_location: NonEmptyText,
        demographics_uuid: &str,
        namespace: Option<NonEmptyText>,
    ) -> PatientResult<()> {
        author.validate_commit_author()?;

        let msg = VprCommitMessage::new(
            VprCommitDomain::Clinical(Record),
            VprCommitAction::Update,
            "EHR status linked to demographics",
            care_location,
        )?;

        let clinical_uuid = ShardableUuid::parse(&self.clinical_id().simple().to_string())?;
        let demographics_uuid = ShardableUuid::parse(demographics_uuid)?;

        let namespace = namespace
            .as_ref()
            .map(|n| n.as_str())
            .unwrap_or(self.cfg.vpr_namespace())
            .trim();

        validate_namespace_uri_safe(namespace)?;

        let patient_dir = self.clinical_patient_dir(&clinical_uuid);
        let filename = patient_dir.join("ehr_status.yaml");

        if !filename.exists() {
            return Err(PatientError::InvalidInput(format!(
                "{} does not exist for clinical record {}",
                "ehr_status.yaml", clinical_uuid
            )));
        }

        let external_reference = Some(vec![ExternalReference {
            namespace: format!("ehr://{}/mpi", namespace),
            id: demographics_uuid.uuid(),
        }]);

        let previous_data = fs::read_to_string(&filename).map_err(PatientError::FileRead)?;

        let rm_version = extract_rm_version(&previous_data)?;

        let yaml_content =
            EhrStatus::render(rm_version, Some(&previous_data), None, external_reference)?;

        VersionedFileService::write_and_commit_files(
            &patient_dir,
            author,
            &msg,
            &[FileToWrite {
                relative_path: Path::new("ehr_status.yaml"),
                content: &yaml_content,
                old_content: Some(&previous_data),
            }],
        )
    }

    /// Creates a new clinical letter with optional body and/or attachments.
    ///
    /// This is the unified function for creating letters with any combination of:
    /// - Body content only (markdown text saved as body.md)
    /// - Attachments only (files stored via FilesService)
    /// - Both body content AND attachments
    ///
    /// At least one of `body_content` or `attachment_files` must be provided.
    ///
    /// # Arguments
    ///
    /// * `author` - The author information for the Git commit. Must have a non-empty name.
    /// * `care_location` - High-level organisational location for the commit (e.g. hospital name).
    ///   Must be a non-empty string.
    /// * `body_content` - Optional Markdown content for the letter body (body.md).
    /// * `attachment_files` - Paths to files to attach (e.g., PDFs, images). Can be empty.
    /// * `clinical_lists` - Optional clinical lists to include in the composition.
    ///
    /// # Returns
    ///
    /// Returns the generated timestamp ID for the letter on success.
    ///
    /// # Errors
    ///
    /// Returns a `PatientError` if:
    /// - Both `body_content` and `attachment_files` are empty/None
    /// - The author's name is empty or whitespace-only
    /// - The care location is empty or whitespace-only
    /// - The clinical UUID cannot be parsed
    /// - Any attachment file cannot be read or stored
    /// - Creating the composition.yaml content fails
    /// - Writing files or committing to Git fails
    pub fn create_letter(
        &self,
        author: &Author,
        care_location: NonEmptyText,
        body_content: Option<NonEmptyText>,
        attachment_files: &[PathBuf],
        clinical_lists: Option<&[ClinicalList]>,
    ) -> PatientResult<TimestampId> {
        // Validate: at least one of body or attachments must be present
        if body_content.is_none() && attachment_files.is_empty() {
            return Err(PatientError::InvalidInput(
                "Letter must have either body content or attachments (or both)".to_string(),
            ));
        }

        author.validate_commit_author()?;

        let commit_message = VprCommitMessage::new(
            VprCommitDomain::Clinical(Record),
            VprCommitAction::Create,
            "Created new letter",
            care_location,
        )?;

        let timestamp_id = TimestampIdGenerator::generate(None)?;
        let letter_paths = LetterPaths::new(&timestamp_id);

        let clinical_uuid = ShardableUuid::parse(&self.clinical_id().simple().to_string())?;
        let patient_dir = self.clinical_patient_dir(&clinical_uuid);

        // Process attachments if provided
        let mut attachment_metadata_list = Vec::new();
        let mut attachment_files_to_write = Vec::new();

        if !attachment_files.is_empty() {
            let clinical_dir = self.clinical_dir();
            let files_service = vpr_files::FilesService::new(&clinical_dir, clinical_uuid.clone())
                .map_err(|e| {
                    PatientError::InvalidInput(format!("Failed to initialize files service: {}", e))
                })?;

            for (index, file_path) in attachment_files.iter().enumerate() {
                // Add file to storage
                let file_metadata = files_service.add(file_path).map_err(|e| {
                    PatientError::InvalidInput(format!("Failed to add attachment file: {}", e))
                })?;

                // Create attachment metadata
                let attachment_filename = format!("attachment_{}.yaml", index + 1);
                let attachment_metadata = AttachmentMetadata {
                    metadata_filename: NonEmptyText::new(&attachment_filename).map_err(|e| {
                        PatientError::InvalidInput(format!("Invalid attachment filename: {}", e))
                    })?,
                    hash: Sha256Hash::parse(file_metadata.hash.as_str()).map_err(|e| {
                        PatientError::InvalidInput(format!("Invalid SHA-256 hash: {}", e))
                    })?,
                    file_storage_path: NonEmptyText::new(file_metadata.relative_path.as_str())
                        .map_err(|e| {
                            PatientError::InvalidInput(format!("Invalid file storage path: {}", e))
                        })?,
                    size_bytes: file_metadata.size_bytes,
                    media_type: file_metadata
                        .media_type
                        .as_ref()
                        .map(|mt| NonEmptyText::new(mt.as_str()))
                        .transpose()
                        .map_err(|e| {
                            PatientError::InvalidInput(format!("Invalid media type: {}", e))
                        })?,
                    original_filename: NonEmptyText::new(&file_metadata.original_filename)
                        .map_err(|e| {
                            PatientError::InvalidInput(format!("Invalid original filename: {}", e))
                        })?,
                };

                // Serialize attachment metadata to YAML
                let attachment_yaml = serde_yaml::to_string(&attachment_metadata).map_err(|e| {
                    PatientError::InvalidInput(format!(
                        "Failed to serialize attachment metadata: {}",
                        e
                    ))
                })?;

                // Add to files to write
                let attachment_path = letter_paths.attachment(&attachment_filename);
                attachment_files_to_write.push((attachment_path, attachment_yaml));
                attachment_metadata_list.push(attachment_metadata);
            }
        }

        // Generate composition.yaml content
        let rm_version = self.cfg.rm_system_version();
        let start_time = timestamp_id.timestamp();

        // Build attachment references for the composition
        let attachment_refs: Vec<openehr::AttachmentReference> = attachment_metadata_list
            .iter()
            .map(|meta| openehr::AttachmentReference {
                path: format!("./attachments/{}", meta.metadata_filename),
            })
            .collect();

        // Construct LetterData
        let letter_data = openehr::LetterData {
            rm_version,
            uid: timestamp_id.clone(),
            composer_name: author.name.to_string(),
            composer_role: "Clinical Practitioner".to_string(),
            start_time,
            clinical_lists: clinical_lists
                .map(|lists| lists.to_vec())
                .unwrap_or_default(),
            has_body: body_content.is_some(),
            attachments: attachment_refs,
        };

        let composition_content =
            Letter::composition_render(rm_version, &letter_data).map_err(|e| {
                PatientError::InvalidInput(format!("Failed to create letter composition: {}", e))
            })?;

        let composition_yaml_relative_path = letter_paths.composition_yaml();

        // Build list of all files to write
        let mut files_to_write_vec = vec![FileToWrite {
            relative_path: &composition_yaml_relative_path,
            content: &composition_content,
            old_content: None,
        }];

        // Add body.md if provided
        let body_md_relative_path;
        if let Some(ref body) = body_content {
            body_md_relative_path = letter_paths.body_md();
            files_to_write_vec.push(FileToWrite {
                relative_path: &body_md_relative_path,
                content: body.as_str(),
                old_content: None,
            });
        }

        // Add attachment metadata files
        let attachment_paths: Vec<PathBuf> = attachment_files_to_write
            .iter()
            .map(|(path, _)| path.clone())
            .collect();

        for (path, content) in attachment_paths
            .iter()
            .zip(attachment_files_to_write.iter())
        {
            files_to_write_vec.push(FileToWrite {
                relative_path: path,
                content: content.1.as_str(),
                old_content: None,
            });
        }

        VersionedFileService::write_and_commit_files(
            &patient_dir,
            author,
            &commit_message,
            &files_to_write_vec,
        )?;

        Ok(timestamp_id)
    }

    /// Creates a new clinical letter with body content.
    ///
    /// This is a convenience wrapper around [`create_letter`](Self::create_letter)
    /// for the common case of creating a letter with only body content.
    ///
    /// # Arguments
    ///
    /// * `author` - The author information for the Git commit.
    /// * `care_location` - High-level organisational location for the commit.
    /// * `letter_content` - The Markdown content for the letter body.
    /// * `clinical_lists` - Optional clinical lists to include.
    ///
    /// # Returns
    ///
    /// Returns the generated timestamp ID for the letter on success.
    ///
    /// This function creates a new letter with the specified content, generates a unique
    /// timestamp-based ID, and commits both the composition.yaml and body.md files to Git.
    ///
    /// # Arguments
    ///
    /// * `author` - The author information for the Git commit. Must have a non-empty name.
    /// * `care_location` - High-level organisational location for the commit (e.g. hospital name).
    ///   Must be a non-empty string.
    /// * `letter_content` - The Markdown content for the letter body (body.md).
    ///
    /// # Returns
    ///
    /// Returns the generated timestamp ID for the letter on success.
    ///
    /// # Errors
    ///
    /// Returns a `PatientError` if:
    /// - The author's name is empty or whitespace-only
    /// - The care location is empty or whitespace-only
    /// - The clinical UUID cannot be parsed
    /// - Creating the composition.yaml content fails
    /// - Writing files or committing to Git fails
    pub fn new_letter(
        &self,
        author: &Author,
        care_location: NonEmptyText,
        letter_content: NonEmptyText,
        clinical_lists: Option<&[ClinicalList]>,
    ) -> PatientResult<TimestampId> {
        author.validate_commit_author()?;

        let msg = VprCommitMessage::new(
            VprCommitDomain::Clinical(Record),
            VprCommitAction::Create,
            "Created new letter",
            care_location,
        )?;

        let timestamp_id = TimestampIdGenerator::generate(None)?;
        let letter_paths = LetterPaths::new(&timestamp_id);

        let clinical_uuid = ShardableUuid::parse(&self.clinical_id().simple().to_string())?;
        let patient_dir = self.clinical_patient_dir(&clinical_uuid);

        let body_md_relative_path = letter_paths.body_md();
        let composition_yaml_relative_path = letter_paths.composition_yaml();

        // Generate composition.yaml content using Letter::composition_render
        let rm_version = self.cfg.rm_system_version();
        let start_time = timestamp_id.timestamp();

        // Construct LetterData for the new letter
        let letter_data = openehr::LetterData {
            rm_version,
            uid: timestamp_id.clone(),
            composer_name: author.name.to_string(),
            composer_role: "Clinical Practitioner".to_string(),
            start_time,
            clinical_lists: clinical_lists
                .map(|lists| lists.to_vec())
                .unwrap_or_default(),
            has_body: true,
            attachments: vec![],
        };

        let composition_content =
            Letter::composition_render(rm_version, &letter_data).map_err(|e| {
                PatientError::InvalidInput(format!("Failed to create letter composition: {}", e))
            })?;

        let files_to_write = [
            FileToWrite {
                relative_path: &composition_yaml_relative_path,
                content: &composition_content,
                old_content: None,
            },
            FileToWrite {
                relative_path: &body_md_relative_path,
                content: letter_content.as_str(),
                old_content: None,
            },
        ];

        VersionedFileService::write_and_commit_files(&patient_dir, author, &msg, &files_to_write)?;

        Ok(timestamp_id)
    }

    /// Reads an existing clinical letter.
    ///
    /// This function reads both the body.md and composition.yaml files for a letter,
    /// parses the composition metadata, and returns them together.
    ///
    /// # Arguments
    ///
    /// * `timestamp_id` - The timestamp ID of the letter to read.
    ///
    /// # Returns
    ///
    /// Returns a `ReadLetterResult` containing both the body content and parsed letter data.
    ///
    /// # Errors
    ///
    /// Returns a `PatientError` if:
    /// - The timestamp ID cannot be parsed
    /// - The clinical UUID cannot be parsed
    /// - The body.md or composition.yaml file does not exist
    /// - Reading either file fails
    /// - Parsing the composition.yaml fails
    pub fn read_letter(&self, timestamp_id: &str) -> PatientResult<ReadLetterResult> {
        let timestamp_id: vpr_uuid::TimestampId = timestamp_id
            .parse()
            .map_err(|e| PatientError::InvalidInput(format!("Invalid timestamp ID: {}", e)))?;
        let letter_paths = LetterPaths::new(&timestamp_id);

        let clinical_uuid = ShardableUuid::parse(&self.clinical_id().simple().to_string())?;
        let patient_dir = self.clinical_patient_dir(&clinical_uuid);

        let body_md_path = patient_dir.join(letter_paths.body_md());
        let composition_yaml_path = patient_dir.join(letter_paths.composition_yaml());

        // Check that both files exist
        if !body_md_path.exists() {
            return Err(PatientError::InvalidInput(format!(
                "Letter body file not found: {}",
                body_md_path.display()
            )));
        }

        if !composition_yaml_path.exists() {
            return Err(PatientError::InvalidInput(format!(
                "Letter composition file not found: {}",
                composition_yaml_path.display()
            )));
        }

        // Read the body content
        let body_content_str = fs::read_to_string(&body_md_path).map_err(PatientError::FileRead)?;
        let body_content = NonEmptyText::new(&body_content_str).map_err(|_| {
            PatientError::InvalidInput(format!(
                "Letter body is empty for timestamp ID: {}",
                timestamp_id
            ))
        })?;

        // Read and parse the composition
        let composition_yaml =
            fs::read_to_string(&composition_yaml_path).map_err(PatientError::FileRead)?;

        let rm_version = extract_rm_version(&composition_yaml)?;

        let letter_data = Letter::composition_parse(rm_version, &composition_yaml)
            .map_err(PatientError::Openehr)?;

        Ok(ReadLetterResult {
            body_content,
            letter_data,
        })
    }

    /// Retrieves all attachments for a clinical letter.
    ///
    /// This function reads all attachment metadata files from the letter's attachments directory
    /// and retrieves the actual file content from storage.
    ///
    /// # Arguments
    ///
    /// * `timestamp_id` - The timestamp ID of the letter.
    ///
    /// # Returns
    ///
    /// Returns a vector of `LetterAttachment` containing metadata and file content for each attachment.
    ///
    /// # Errors
    ///
    /// Returns a `PatientError` if:
    /// - The timestamp ID cannot be parsed
    /// - The clinical UUID cannot be parsed
    /// - The attachments directory does not exist or cannot be read
    /// - Any attachment metadata file cannot be read or parsed
    /// - Any file cannot be retrieved from storage
    pub fn get_letter_attachments(
        &self,
        timestamp_id: &str,
    ) -> PatientResult<Vec<LetterAttachment>> {
        let timestamp_id: vpr_uuid::TimestampId = timestamp_id
            .parse()
            .map_err(|e| PatientError::InvalidInput(format!("Invalid timestamp ID: {}", e)))?;
        let letter_paths = LetterPaths::new(&timestamp_id);

        let clinical_uuid = ShardableUuid::parse(&self.clinical_id().simple().to_string())?;
        let patient_dir = self.clinical_patient_dir(&clinical_uuid);

        let attachments_dir = patient_dir.join(letter_paths.attachments_dir());

        // Check if attachments directory exists
        if !attachments_dir.exists() {
            // No attachments - return empty vector
            return Ok(Vec::new());
        }

        // Initialize FilesService for reading files
        let clinical_dir = self.clinical_dir();
        let files_service =
            vpr_files::FilesService::new(&clinical_dir, clinical_uuid).map_err(|e| {
                PatientError::InvalidInput(format!("Failed to initialize files service: {}", e))
            })?;

        let mut attachments = Vec::new();

        // Read all attachment metadata files
        let entries = fs::read_dir(&attachments_dir).map_err(|e| {
            PatientError::FileRead(std::io::Error::new(
                e.kind(),
                format!("Failed to read attachments directory: {}", e),
            ))
        })?;

        for entry in entries {
            let entry = entry.map_err(PatientError::FileRead)?;
            let path = entry.path();

            // Only process .yaml files
            if path.extension().and_then(|s| s.to_str()) != Some("yaml") {
                continue;
            }

            // Read and parse attachment metadata
            let metadata_content = fs::read_to_string(&path).map_err(PatientError::FileRead)?;
            let metadata: AttachmentMetadata =
                serde_yaml::from_str(&metadata_content).map_err(|e| {
                    PatientError::InvalidInput(format!(
                        "Failed to parse attachment metadata: {}",
                        e
                    ))
                })?;

            // Retrieve file content from storage using the hash
            let content = files_service.read(metadata.hash.as_str()).map_err(|e| {
                PatientError::InvalidInput(format!("Failed to read attachment file: {}", e))
            })?;

            attachments.push(LetterAttachment { metadata, content });
        }

        Ok(attachments)
    }

    /// Creates a new clinical letter with file attachments.
    ///
    /// This is a convenience wrapper around [`create_letter`](Self::create_letter)
    /// for creating a letter with only attachments (no body content).
    ///
    /// # Arguments
    ///
    /// * `author` - The author information for the Git commit.
    /// * `care_location` - High-level organisational location for the commit.
    /// * `attachment_files` - Paths to files to attach (e.g., PDFs, images).
    /// * `clinical_lists` - Optional clinical lists to include.
    ///
    /// # Returns
    ///
    /// Returns the generated timestamp ID for the letter on success.
    pub fn new_letter_with_attachments(
        &self,
        author: &Author,
        care_location: NonEmptyText,
        attachment_files: &[PathBuf],
        clinical_lists: Option<&[ClinicalList]>,
    ) -> PatientResult<TimestampId> {
        self.create_letter(
            author,
            care_location,
            None,
            attachment_files,
            clinical_lists,
        )
    }
}

impl<S> ClinicalService<S> {
    /// Returns the path to the clinical records directory.
    ///
    /// This constructs the base directory for clinical records by joining
    /// the configured patient data directory with the clinical directory name.
    ///
    /// # Returns
    ///
    /// A `PathBuf` pointing to the clinical records directory (e.g., `{patient_data_dir}/clinical`).
    fn clinical_dir(&self) -> PathBuf {
        let data_dir = self.cfg.patient_data_dir().to_path_buf();
        data_dir.join(CLINICAL_DIR_NAME)
    }

    /// Returns the path to a specific patient's clinical record directory.
    ///
    /// This constructs the full path to a patient's clinical directory by
    /// determining the sharded subdirectory based on the UUID and joining
    /// it with the clinical base directory.
    ///
    /// # Arguments
    ///
    /// * `clinical_uuid` - The UUID identifying the clinical record.
    ///
    /// # Returns
    ///
    /// A `PathBuf` pointing to the patient's clinical record directory
    /// (e.g., `{clinical_dir}/{shard1}/{shard2}/{uuid}`).
    fn clinical_patient_dir(&self, clinical_uuid: &ShardableUuid) -> PathBuf {
        let clinical_dir = self.clinical_dir();
        clinical_uuid.sharded_dir(&clinical_dir)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::rm_system_version_from_env_value;
    use crate::{EmailAddress, NonEmptyText};

    use crate::CoreConfig;
    use p256::ecdsa::SigningKey;
    use p256::pkcs8::{EncodePrivateKey, EncodePublicKey};
    use rcgen::{CertificateParams, KeyPair};
    use std::path::Path;
    use std::sync::Arc;
    use tempfile::TempDir;

    fn test_cfg(patient_data_dir: &Path) -> Arc<CoreConfig> {
        let rm_system_version = rm_system_version_from_env_value(None)
            .expect("rm_system_version_from_env_value should succeed");

        Arc::new(
            CoreConfig::new(
                patient_data_dir.to_path_buf(),
                rm_system_version,
                crate::NonEmptyText::new("vpr.dev.1").unwrap(),
            )
            .expect("CoreConfig::new should succeed"),
        )
    }

    #[test]
    fn create_uuid_and_shard_dir_creates_first_available_candidate() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);

        let uuids = vec![ShardableUuid::parse("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
            .expect("uuid should be canonical")];
        let mut iter = uuids.into_iter();

        let (uuid, patient_dir) =
            create_uuid_and_shard_dir_with_source(&clinical_dir, || iter.next().unwrap())
                .expect("allocation should succeed");

        assert_eq!(uuid.to_string(), "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
        assert_eq!(
            patient_dir,
            clinical_dir
                .join("aa")
                .join("aa")
                .join("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
        );
        assert!(patient_dir.exists(), "patient directory should exist");
    }

    #[test]
    fn create_uuid_and_shard_dir_skips_existing_candidate() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);

        let first = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
        let second = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
        let first_dir = clinical_dir
            .join("aa")
            .join("aa")
            .join("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
        fs::create_dir_all(&first_dir).expect("Failed to pre-create first candidate dir");

        let uuids = vec![
            ShardableUuid::parse(first).expect("uuid should be canonical"),
            ShardableUuid::parse(second).expect("uuid should be canonical"),
        ];
        let mut iter = uuids.into_iter();

        let (uuid, patient_dir) =
            create_uuid_and_shard_dir_with_source(&clinical_dir, || iter.next().unwrap())
                .expect("allocation should succeed");

        assert_eq!(uuid.to_string(), second);
        assert_eq!(
            patient_dir,
            clinical_dir
                .join("bb")
                .join("bb")
                .join("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb")
        );
        assert!(patient_dir.exists(), "patient directory should exist");
    }

    #[test]
    fn create_uuid_and_shard_dir_fails_after_five_attempts() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);

        let ids = [
            "11111111111111111111111111111111",
            "22222222222222222222222222222222",
            "33333333333333333333333333333333",
            "44444444444444444444444444444444",
            "55555555555555555555555555555555",
        ];

        for id in ids {
            let dir = clinical_dir.join(&id[0..2]).join(&id[2..4]).join(id);
            fs::create_dir_all(&dir).expect("Failed to pre-create candidate dir");
        }

        let uuids = ids
            .into_iter()
            .map(|s| ShardableUuid::parse(s).expect("uuid should be canonical"))
            .collect::<Vec<_>>();
        let mut iter = uuids.into_iter();

        let err = create_uuid_and_shard_dir_with_source(&clinical_dir, || iter.next().unwrap())
            .expect_err("allocation should fail");

        match err {
            PatientError::PatientDirCreation(e) => {
                assert_eq!(e.kind(), ErrorKind::AlreadyExists);
            }
            other => panic!("unexpected error: {other:?}"),
        }
    }

    #[test]
    fn create_uuid_and_shard_dir_returns_error_if_parent_dir_creation_fails() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);

        // For UUID "aa..", the shard prefix directories are "aa/aa".
        // Create a *file* at "clinical_dir/aa" so creating "clinical_dir/aa/aa" fails.
        fs::create_dir_all(&clinical_dir).expect("Failed to create clinical_dir");
        let blocking_path = clinical_dir.join("aa");
        fs::write(&blocking_path, b"not a directory").expect("Failed to create blocking file");

        let uuids = vec![ShardableUuid::parse("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
            .expect("uuid should be canonical")];
        let mut iter = uuids.into_iter();

        let err = create_uuid_and_shard_dir_with_source(&clinical_dir, || iter.next().unwrap())
            .expect_err("allocation should fail when parent dir creation fails");

        assert!(matches!(err, PatientError::PatientDirCreation(_)));
    }

    #[test]
    fn test_initialise_fails_fast_on_invalid_author_and_creates_no_files() {
        let patient_data_dir = TempDir::new().expect("Failed to create temp dir");

        let rm_system_version = rm_system_version_from_env_value(None)
            .expect("rm_system_version_from_env_value should succeed");

        let cfg = Arc::new(
            CoreConfig::new(
                patient_data_dir.path().to_path_buf(),
                rm_system_version,
                crate::NonEmptyText::new("vpr.dev.1").unwrap(),
            )
            .expect("CoreConfig::new should succeed"),
        );

        let _service = ClinicalService::new(cfg);

        // NonEmptyText validation prevents whitespace-only strings at the type level
        let err =
            NonEmptyText::new(" ").expect_err("creating NonEmptyText from whitespace should fail");
        assert!(matches!(err, crate::TextError::Empty));

        assert!(
            !patient_data_dir.path().join(CLINICAL_DIR_NAME).exists(),
            "initialise should not perform filesystem side-effects when validation fails"
        );
    }

    #[test]
    fn test_initialise_rejects_missing_care_location_and_creates_no_files() {
        let patient_data_dir = TempDir::new().expect("Failed to create temp dir");

        let rm_system_version = rm_system_version_from_env_value(None)
            .expect("rm_system_version_from_env_value should succeed");

        let cfg = Arc::new(
            CoreConfig::new(
                patient_data_dir.path().to_path_buf(),
                rm_system_version,
                crate::NonEmptyText::new("vpr.dev.1").unwrap(),
            )
            .expect("CoreConfig::new should succeed"),
        );

        let _service = ClinicalService::new(cfg);

        let _author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        // NonEmptyText validation prevents whitespace-only strings at the type level
        let err = NonEmptyText::new(" \t\n")
            .expect_err("creating NonEmptyText from whitespace should fail");
        assert!(matches!(err, crate::TextError::Empty));

        assert!(
            !patient_data_dir.path().join(CLINICAL_DIR_NAME).exists(),
            "initialise should not perform filesystem side-effects when validation fails"
        );
    }

    #[test]
    fn test_initialise_creates_clinical_record() {
        // Create a temporary directory for testing
        let temp_dir = TempDir::new().expect("Failed to create temp dir");

        // Create a test author
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg);

        // Call initialise
        let result = service.initialise(author, NonEmptyText::new("Test Hospital").unwrap());
        assert!(result.is_ok(), "initialise should succeed");

        let clinical_uuid = result.unwrap();
        let clinical_uuid_str = clinical_uuid.clinical_id().simple().to_string();
        assert_eq!(clinical_uuid_str.len(), 32, "UUID should be 32 characters");

        // Verify directory structure exists
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);
        assert!(clinical_dir.exists(), "clinical directory should exist");

        // Extract sharding directories from UUID
        let s1 = &clinical_uuid_str[0..2];
        let s2 = &clinical_uuid_str[2..4];
        let patient_dir = clinical_dir.join(s1).join(s2).join(&clinical_uuid_str);
        assert!(patient_dir.exists(), "patient directory should exist");

        // Verify core files were created (no longer copying templates)
        let ehr_status_file = patient_dir.join("ehr_status.yaml");
        assert!(ehr_status_file.exists(), "ehr_status.yaml should exist");

        let gitignore_file = patient_dir.join(".gitignore");
        assert!(gitignore_file.exists(), ".gitignore should exist");

        // Verify Git repository exists and has initial commit
        let repo = git2::Repository::open(&patient_dir).expect("Failed to open Git repo");
        let head = repo.head().expect("Failed to get HEAD");
        let commit = head.peel_to_commit().expect("Failed to get commit");
        assert_eq!(
            commit.message().unwrap(),
            "record:create: Initialised the clinical record\n\nAuthor-Name: Test Author\nAuthor-Role: Clinician\nCare-Location: Test Hospital"
        );
    }

    #[test]
    fn test_link_to_demographics_updates_ehr_status() {
        // Create a temporary directory for testing
        let temp_dir = TempDir::new().expect("Failed to create temp dir");

        // Create a test author
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        // Initialise clinical service
        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg.clone());

        // First, initialise a clinical record
        let care_location: NonEmptyText = NonEmptyText::new("Test Hospital").unwrap();
        let service = service
            .initialise(author.clone(), care_location.clone())
            .expect("initialise should succeed");
        let clinical_uuid = service.clinical_id();
        let clinical_uuid_str = clinical_uuid.simple().to_string();

        // Now link to demographics
        let demographics_uuid = "12345678123412341234123456789abc";
        let result = service.link_to_demographics(&author, care_location, demographics_uuid, None);
        assert!(result.is_ok(), "link_to_demographics should succeed");

        // Verify ehr_status.yaml was updated with linking information
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);
        let patient_dir = ShardableUuid::parse(&clinical_uuid_str)
            .expect("clinical_uuid should be canonical")
            .sharded_dir(&clinical_dir);
        let ehr_status_file = patient_dir.join("ehr_status.yaml");

        assert!(ehr_status_file.exists(), "ehr_status.yaml should exist");
    }

    #[test]
    fn test_link_to_demographics_rejects_invalid_clinical_uuid() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());
        // This test is no longer applicable with the type-state pattern
        // because you cannot call link_to_demographics on an Uninitialised service
        // The type system prevents this at compile time
        let _service = ClinicalService::new(cfg);

        // This would not compile:
        // service.link_to_demographics(&author, care_location, "...", None);
        // So we just verify the service was created successfully
    }

    #[test]
    fn test_link_to_demographics_rejects_invalid_demographics_uuid() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg);

        // Create a valid clinical record first
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Try to link with invalid demographics UUID
        let err = service
            .link_to_demographics(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                "invalid-demographics-uuid",
                None,
            )
            .expect_err("expected validation failure for invalid demographics UUID");
        assert!(matches!(err, PatientError::Uuid(_)));
    }

    #[test]
    fn test_link_to_demographics_rejects_invalid_namespace() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg);

        // Create a valid clinical record
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Try to link with unsafe namespace containing invalid characters
        let demographics_uuid = ShardableUuid::new();
        let demographics_uuid_str = demographics_uuid.to_string();

        let err = service
            .link_to_demographics(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                &demographics_uuid_str,
                Some(NonEmptyText::new("unsafe<namespace>with/special\\chars").unwrap()),
            )
            .expect_err("expected validation failure for unsafe namespace");
        assert!(matches!(err, PatientError::Openehr(_)));
    }

    #[test]
    fn test_link_to_demographics_fails_when_ehr_status_missing() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        // Manually create a clinical directory without ehr_status.yaml
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);
        let clinical_uuid = ShardableUuid::new();
        let patient_dir = clinical_uuid.sharded_dir(&clinical_dir);
        fs::create_dir_all(&patient_dir).expect("Failed to create patient dir");

        // Initialize Git repo but don't create ehr_status.yaml
        VersionedFileService::init(&patient_dir).expect("Failed to init git");

        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let demographics_uuid = ShardableUuid::new();
        let demographics_uuid_str = demographics_uuid.to_string();

        // Should fail because ehr_status.yaml doesn't exist
        let service = ClinicalService::with_id(cfg, clinical_uuid.uuid());
        let err = service
            .link_to_demographics(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                &demographics_uuid_str,
                None,
            )
            .expect_err("link_to_demographics should fail when ehr_status.yaml is missing");

        assert!(
            matches!(err, PatientError::InvalidInput(_)),
            "Should return InvalidInput error when ehr_status.yaml is missing"
        );
    }

    #[test]
    fn test_link_to_demographics_rejects_corrupted_ehr_status() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        // Create a clinical directory with corrupted ehr_status.yaml
        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);
        let clinical_uuid = ShardableUuid::new();
        let patient_dir = clinical_uuid.sharded_dir(&clinical_dir);
        fs::create_dir_all(&patient_dir).expect("Failed to create patient dir");

        // Initialize Git repo
        VersionedFileService::init(&patient_dir).expect("Failed to init git");

        // Write corrupted YAML (missing required rm_version field)
        let ehr_status_file = patient_dir.join("ehr_status.yaml");
        fs::write(&ehr_status_file, "archetype_node_id: some_id\nname: Test")
            .expect("Failed to write corrupted file");

        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let demographics_uuid = ShardableUuid::new();
        let demographics_uuid_str = demographics_uuid.to_string();

        let service = ClinicalService::with_id(cfg, clinical_uuid.uuid());
        let err = service
            .link_to_demographics(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                &demographics_uuid_str,
                None,
            )
            .expect_err("expected failure due to corrupted ehr_status");

        // Should fail when trying to extract RM version from corrupted file
        assert!(matches!(
            err,
            PatientError::InvalidInput(_)
                | PatientError::YamlDeserialization(_)
                | PatientError::Openehr(_)
        ));
    }

    #[test]
    fn test_verify_commit_signature() {
        // Create a temporary directory for testing
        let temp_dir = TempDir::new().expect("Failed to create temp dir");

        // Generate a key pair for signing
        let signing_key = SigningKey::random(&mut rand::thread_rng());
        let verifying_key = signing_key.verifying_key();

        // Encode private key to PEM
        let private_key_pem = signing_key
            .to_pkcs8_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode private key");

        // Encode public key to PEM
        let public_key_pem = verifying_key
            .to_public_key_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode public key");

        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg.clone());
        let clinical_dir = cfg
            .patient_data_dir()
            .join(crate::constants::CLINICAL_DIR_NAME);
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: Some(private_key_pem.to_string().into_bytes()),
            certificate: None,
        };

        // Initialise clinical record
        let result = service.initialise(author, NonEmptyText::new("Test Hospital").unwrap());
        assert!(result.is_ok(), "initialise should succeed");
        let clinical_uuid = result.unwrap();
        let clinical_uuid_str = clinical_uuid.clinical_id().simple().to_string();

        // Verify the signature
        let verify_result = VersionedFileService::verify_commit_signature(
            &clinical_dir,
            &clinical_uuid_str,
            &public_key_pem,
        );
        assert!(
            verify_result.is_ok(),
            "verify_commit_signature should succeed"
        );
        assert!(verify_result.unwrap(), "signature should be valid");

        // Verify fails with a wrong public key
        let wrong_signing_key = SigningKey::random(&mut rand::thread_rng());
        let wrong_pub_pem = wrong_signing_key
            .verifying_key()
            .to_public_key_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode wrong public key");
        let wrong_verify = VersionedFileService::verify_commit_signature(
            &clinical_dir,
            &clinical_uuid_str,
            &wrong_pub_pem,
        );
        assert!(wrong_verify.is_ok(), "verify with wrong key should succeed");
        assert!(
            !wrong_verify.unwrap(),
            "signature should be invalid with wrong key"
        );
    }

    #[test]
    fn test_verify_commit_signature_offline_with_embedded_public_key() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");

        let signing_key = SigningKey::random(&mut rand::thread_rng());
        let verifying_key = signing_key.verifying_key();

        let private_key_pem = signing_key
            .to_pkcs8_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode private key");
        let public_key_pem = verifying_key
            .to_public_key_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode public key");

        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg.clone());
        let clinical_dir = cfg
            .patient_data_dir()
            .join(crate::constants::CLINICAL_DIR_NAME);
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: Some(private_key_pem.to_string().into_bytes()),
            certificate: None,
        };

        let clinical_uuid = service
            .initialise(author, NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");
        let clinical_uuid_str = clinical_uuid.clinical_id().simple().to_string();

        // Offline verification: no external key material is provided.
        let ok =
            VersionedFileService::verify_commit_signature(&clinical_dir, &clinical_uuid_str, "")
                .expect("verify_commit_signature should succeed");
        assert!(ok, "embedded public key verification should succeed");

        // Compatibility: verification still works with an explicit public key.
        let ok = VersionedFileService::verify_commit_signature(
            &clinical_dir,
            &clinical_uuid_str,
            &public_key_pem,
        )
        .expect("verify_commit_signature should succeed");
        assert!(ok, "verification with explicit public key should succeed");
    }

    #[test]
    fn test_initialise_rejects_mismatched_author_certificate() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");

        // Signing key used for commit.
        let signing_key = SigningKey::random(&mut rand::thread_rng());
        let private_key_pem = signing_key
            .to_pkcs8_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode private key");

        // Different key used to create a certificate (mismatch).
        let other_key = SigningKey::random(&mut rand::thread_rng());
        let other_private_key_pem = other_key
            .to_pkcs8_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode other private key");
        let other_private_key_pem_str = other_private_key_pem.to_string();

        let other_keypair = KeyPair::from_pem(&other_private_key_pem_str)
            .expect("KeyPair::from_pem should succeed");
        let params = CertificateParams::default();
        let cert = params
            .self_signed(&other_keypair)
            .expect("self_signed should succeed");
        let cert_pem = cert.pem();

        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg);
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: Some(private_key_pem.to_string().into_bytes()),
            certificate: Some(cert_pem.into_bytes()),
        };

        let err = service
            .initialise(author, NonEmptyText::new("Test Hospital").unwrap())
            .expect_err("initialise should fail due to certificate mismatch");
        assert!(matches!(
            err,
            PatientError::AuthorCertificatePublicKeyMismatch
        ));
    }

    #[test]
    fn test_extract_embedded_commit_signature_from_head_commit() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");

        let signing_key = SigningKey::random(&mut rand::thread_rng());
        let private_key_pem = signing_key
            .to_pkcs8_pem(p256::pkcs8::LineEnding::LF)
            .expect("Failed to encode private key");

        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg);
        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: Some(private_key_pem.to_string().into_bytes()),
            certificate: None,
        };

        let clinical_uuid = service
            .initialise(author, NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");
        let clinical_uuid_str = clinical_uuid.clinical_id().simple().to_string();

        let clinical_dir = temp_dir.path().join(CLINICAL_DIR_NAME);
        let patient_dir = ShardableUuid::parse(&clinical_uuid_str)
            .expect("clinical_uuid should be canonical")
            .sharded_dir(&clinical_dir);

        let repo = git2::Repository::open(&patient_dir).expect("Failed to open Git repo");
        let head = repo.head().expect("Failed to get HEAD");
        let commit = head.peel_to_commit().expect("Failed to get commit");

        let embedded = crate::author::extract_embedded_commit_signature(&commit)
            .expect("extract_embedded_commit_signature should succeed");
        assert_eq!(embedded.signature.len(), 64);
        assert!(!embedded.public_key.is_empty());
        assert!(embedded.certificate.is_none());
    }

    #[test]
    fn test_initialise_without_signature_creates_commit_without_embedded_signature() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");

        let cfg = test_cfg(temp_dir.path());
        let service = ClinicalService::new(cfg.clone());
        let clinical_dir = cfg
            .patient_data_dir()
            .join(crate::constants::CLINICAL_DIR_NAME);

        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let clinical_uuid = service
            .initialise(author, NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");
        let clinical_uuid_str = clinical_uuid.clinical_id().simple().to_string();

        let patient_dir = ShardableUuid::parse(&clinical_uuid_str)
            .expect("clinical_uuid should be canonical")
            .sharded_dir(&clinical_dir);

        let repo = git2::Repository::open(&patient_dir).expect("Failed to open Git repo");
        let head = repo.head().expect("Failed to get HEAD");
        let commit = head.peel_to_commit().expect("Failed to get commit");

        assert!(
            crate::author::extract_embedded_commit_signature(&commit).is_err(),
            "unsigned commits should not contain an embedded signature payload"
        );

        let ok =
            VersionedFileService::verify_commit_signature(&clinical_dir, &clinical_uuid_str, "")
                .expect("verify_commit_signature should succeed");
        assert!(
            !ok,
            "verification should be false when no signature is embedded"
        );
    }

    #[test]
    fn test_new_letter() {
        let patient_data_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(patient_data_dir.path());

        let author = Author {
            name: NonEmptyText::new("Test Author").unwrap(),
            role: NonEmptyText::new("Clinician").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = ClinicalService::new(cfg.clone());
        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        let result = service.new_letter(
            &author,
            NonEmptyText::new("Test Hospital").unwrap(),
            NonEmptyText::new("Letter content").unwrap(),
            None,
        );

        assert!(result.is_ok(), "new_letter should return Ok");
        let timestamp_id = result.unwrap();
        println!("Timestamp ID: {}", timestamp_id);

        let timestamp_str = timestamp_id.to_string();
        assert!(!timestamp_str.is_empty());
        assert!(
            timestamp_str.contains("Z-"),
            "timestamp_id should contain 'Z-' separator"
        );
    }

    #[test]
    fn test_new_letter_with_attachments() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        // Initialize clinical record
        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Create a test PDF file
        let test_file = temp_dir.path().join("test_document.pdf");
        fs::write(&test_file, b"fake PDF content").expect("Failed to create test file");

        let attachment_files = vec![test_file.clone()];

        // Create letter with attachment
        let result = service.new_letter_with_attachments(
            &author,
            NonEmptyText::new("Test Hospital").unwrap(),
            &attachment_files,
            None,
        );

        assert!(result.is_ok(), "new_letter_with_attachments should succeed");
        let timestamp_id = result.unwrap();

        // Verify the files were created
        let clinical_uuid = ShardableUuid::parse(&service.clinical_id().simple().to_string())
            .expect("should parse clinical UUID");
        let patient_dir = service.clinical_patient_dir(&clinical_uuid);
        let letter_paths = LetterPaths::new(&timestamp_id);

        // Check composition.yaml exists
        let composition_path = patient_dir.join(letter_paths.composition_yaml());
        assert!(composition_path.exists(), "composition.yaml should exist");

        // Check attachment metadata file exists
        let attachment_path = patient_dir.join(letter_paths.attachment("attachment_1.yaml"));
        assert!(attachment_path.exists(), "attachment_1.yaml should exist");

        // Read and verify attachment metadata
        let attachment_content =
            fs::read_to_string(&attachment_path).expect("should read attachment metadata");
        let attachment_metadata: AttachmentMetadata =
            serde_yaml::from_str(&attachment_content).expect("should parse attachment metadata");

        assert_eq!(
            attachment_metadata.metadata_filename.as_str(),
            "attachment_1.yaml"
        );
        assert_eq!(
            attachment_metadata.original_filename.as_str(),
            "test_document.pdf"
        );
        assert_eq!(attachment_metadata.size_bytes, 16); // "fake PDF content".len()
        assert!(!attachment_metadata.hash.as_str().is_empty());
    }

    #[test]
    fn test_get_letter_attachments() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        // Initialize clinical record
        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Create test files
        let test_file1 = temp_dir.path().join("document1.pdf");
        let test_file2 = temp_dir.path().join("image.png");
        let content1 = b"PDF content here";
        let content2 = b"PNG content here";
        fs::write(&test_file1, content1).expect("Failed to create test file 1");
        fs::write(&test_file2, content2).expect("Failed to create test file 2");

        let attachment_files = vec![test_file1, test_file2];

        // Create letter with attachments
        let timestamp_id = service
            .new_letter_with_attachments(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                &attachment_files,
                None,
            )
            .expect("new_letter_with_attachments should succeed");

        // Retrieve attachments
        let attachments = service
            .get_letter_attachments(&timestamp_id.to_string())
            .expect("get_letter_attachments should succeed");

        // Verify we got 2 attachments
        assert_eq!(attachments.len(), 2, "should have 2 attachments");

        // Verify first attachment
        assert_eq!(
            attachments[0].metadata.original_filename.as_str(),
            "document1.pdf"
        );
        assert_eq!(attachments[0].metadata.size_bytes, content1.len() as u64);
        assert_eq!(attachments[0].content, content1);

        // Verify second attachment
        assert_eq!(
            attachments[1].metadata.original_filename.as_str(),
            "image.png"
        );
        assert_eq!(attachments[1].metadata.size_bytes, content2.len() as u64);
        assert_eq!(attachments[1].content, content2);
    }

    #[test]
    fn test_get_letter_attachments_empty() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        // Initialize clinical record
        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Create letter without attachments
        let timestamp_id = service
            .new_letter(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                NonEmptyText::new("Test content").unwrap(),
                None,
            )
            .expect("new_letter should succeed");

        // Try to retrieve attachments
        let attachments = service
            .get_letter_attachments(&timestamp_id.to_string())
            .expect("get_letter_attachments should succeed");

        // Should return empty vector
        assert_eq!(attachments.len(), 0, "should have no attachments");
    }

    #[test]
    fn test_read_letter() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        // Initialize clinical record
        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        let letter_content = "# Test Letter\n\nThis is a test letter.";

        // Create letter
        let timestamp_id = service
            .new_letter(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                NonEmptyText::new(letter_content).unwrap(),
                None,
            )
            .expect("new_letter should succeed");

        // Read letter back
        let result = service
            .read_letter(&timestamp_id.to_string())
            .expect("read_letter should succeed");

        // Verify content
        assert_eq!(result.body_content.as_str(), letter_content);
        assert_eq!(result.letter_data.composer_name, "Dr. Test");
        assert_eq!(result.letter_data.composer_role, "Clinical Practitioner");
    }

    #[test]
    fn test_read_letter_invalid_timestamp() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Try to read with invalid timestamp
        let result = service.read_letter("invalid-timestamp");

        assert!(result.is_err());
        assert!(matches!(result, Err(PatientError::InvalidInput(_))));
    }

    #[test]
    fn test_read_letter_nonexistent() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Try to read non-existent letter with valid timestamp format
        let fake_timestamp = "20260125T120000.000Z-550e8400-e29b-41d4-a716-446655440000";
        let result = service.read_letter(fake_timestamp);

        assert!(result.is_err());
        assert!(matches!(result, Err(PatientError::InvalidInput(_))));
    }

    #[test]
    fn test_new_letter_with_attachments_nonexistent_file() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Try to attach non-existent file
        let nonexistent_file = temp_dir.path().join("does_not_exist.pdf");
        let attachment_files = vec![nonexistent_file];

        let result = service.new_letter_with_attachments(
            &author,
            NonEmptyText::new("Test Hospital").unwrap(),
            &attachment_files,
            None,
        );

        assert!(result.is_err());
        assert!(matches!(result, Err(PatientError::InvalidInput(_))));
    }

    #[test]
    fn test_new_letter_with_attachments_multiple_files() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Create multiple test files
        let test_files = vec![
            (temp_dir.path().join("doc1.pdf"), b"content1" as &[u8]),
            (temp_dir.path().join("doc2.txt"), b"content2"),
            (temp_dir.path().join("image.png"), b"content3"),
        ];

        for (path, content) in &test_files {
            fs::write(path, content).expect("Failed to create test file");
        }

        let attachment_files: Vec<PathBuf> =
            test_files.iter().map(|(path, _)| path.clone()).collect();

        let timestamp_id = service
            .new_letter_with_attachments(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                &attachment_files,
                None,
            )
            .expect("new_letter_with_attachments should succeed");

        // Verify all attachments were created
        let clinical_uuid = ShardableUuid::parse(&service.clinical_id().simple().to_string())
            .expect("should parse clinical UUID");
        let patient_dir = service.clinical_patient_dir(&clinical_uuid);
        let letter_paths = LetterPaths::new(&timestamp_id);

        for i in 1..=3 {
            let attachment_path =
                patient_dir.join(letter_paths.attachment(&format!("attachment_{}.yaml", i)));
            assert!(
                attachment_path.exists(),
                "attachment_{}.yaml should exist",
                i
            );
        }
    }

    #[test]
    fn test_get_letter_attachments_invalid_timestamp() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        let result = service.get_letter_attachments("invalid-timestamp");

        assert!(result.is_err());
        assert!(matches!(result, Err(PatientError::InvalidInput(_))));
    }

    #[test]
    fn test_get_letter_attachments_with_clinical_lists() {
        let temp_dir = TempDir::new().expect("Failed to create temp dir");
        let cfg = test_cfg(temp_dir.path());

        let service = ClinicalService::new(cfg.clone());
        let author = Author {
            name: NonEmptyText::new("Dr. Test").unwrap(),
            role: NonEmptyText::new("Consultant").unwrap(),
            email: EmailAddress::parse("test@example.com").unwrap(),
            registrations: vec![],
            signature: None,
            certificate: None,
        };

        let service = service
            .initialise(author.clone(), NonEmptyText::new("Test Hospital").unwrap())
            .expect("initialise should succeed");

        // Create test file
        let test_file = temp_dir.path().join("report.pdf");
        fs::write(&test_file, b"test report content").expect("Failed to create test file");

        // Create clinical lists
        let clinical_lists = vec![openehr::ClinicalList {
            name: "Diagnoses".to_string(),
            kind: "diagnoses".to_string(),
            items: vec![openehr::ClinicalListItem {
                text: "Hypertension".to_string(),
                code: None,
            }],
        }];

        let timestamp_id = service
            .new_letter_with_attachments(
                &author,
                NonEmptyText::new("Test Hospital").unwrap(),
                &[test_file],
                Some(&clinical_lists),
            )
            .expect("new_letter_with_attachments should succeed");

        // Verify attachment is retrievable
        let attachments = service
            .get_letter_attachments(&timestamp_id.to_string())
            .expect("get_letter_attachments should succeed");

        assert_eq!(attachments.len(), 1);
        assert_eq!(
            attachments[0].metadata.original_filename.as_str(),
            "report.pdf"
        );
    }

    #[test]
    fn test_attachment_metadata_serialization() {
        let metadata = AttachmentMetadata {
            metadata_filename: NonEmptyText::new("attachment_1.yaml").unwrap(),
            hash: Sha256Hash::parse(
                "abc123def456789012345678901234567890123456789012345678901234abcd",
            )
            .unwrap(),
            file_storage_path: NonEmptyText::new("files/sha256/ab/c1/abc123").unwrap(),
            size_bytes: 1024,
            media_type: Some(NonEmptyText::new("application/pdf").unwrap()),
            original_filename: NonEmptyText::new("test.pdf").unwrap(),
        };

        // Serialize to YAML
        let yaml = serde_yaml::to_string(&metadata).expect("should serialize");
        assert!(yaml.contains("filename:"));
        assert!(yaml.contains("test.pdf"));

        // Deserialize back
        let deserialized: AttachmentMetadata =
            serde_yaml::from_str(&yaml).expect("should deserialize");
        assert_eq!(deserialized.metadata_filename, metadata.metadata_filename);
        assert_eq!(deserialized.original_filename, metadata.original_filename);
        assert_eq!(deserialized.hash, metadata.hash);
        assert_eq!(deserialized.size_bytes, metadata.size_bytes);
    }
}