gradatum-vault 0.4.3

//! Lifecycle CRUD des notes — création, persistance, mise à jour de statut.
//!
//! ## Opérations
//!
//! - `write_note` : calcule le `ContentHash`, persiste le `.md` sur disque, upsert l'index SQLite.
//! - `write_note_with_id` : idem en honorant un ULID préalloué (wikilinks stables).
//! - `read_note` : lit depuis l'index SQLite + disque, avec validation cache (B22).
//! - `update_status` : valide la transition via `NoteStatus::can_transition_to`, met à jour
//!   l'index SQLite, puis persiste le frontmatter sur disque via `write_note_with_id`
//!   (CoW tracé — snapshot `.history/` si le hash diffère).
//! - `delete_note` : supprime le `.md` du storage + purge `.history/<id>/`.
//!
//! ## Invariants
//!
//! - `vault_id` dans le frontmatter est toujours égal à `self.tenant_id` (forcé si absent).
//! - `updated` est mis à jour à `Utc::now()` à chaque écriture.
//! - Chemin on-disk : `<root>/<tenant>/<locus>/<id>.md` ou `<root>/<tenant>/<id>.md`.

use std::sync::atomic::Ordering;
use std::sync::Arc;

use chrono::Utc;
use gradatum_cache::CacheKey;
use gradatum_core::config::HistoryConfig;
use gradatum_core::error::GradatumError;
use gradatum_core::frontmatter::Frontmatter;
use gradatum_core::history::sha256_for_history;
use gradatum_core::identity::{ContentHash, NoteId, NoteVersion};
// DocumentStore : write_note, get_content_hash, get_note, list_by_status (Étape 0.1).
use gradatum_core::note::{EffectiveNote, Note, NoteBody};
use gradatum_core::status::NoteStatus;
use gradatum_core::DocumentStore as _;
use gradatum_storage::Storage as _;

use crate::error::VaultError;
use crate::registry::Vault;

/// Préfixe des répertoires d'historique CoW — exclus de l'index, FTS et drift detector.
///
/// Tout chemin commençant par ce préfixe (relatif à la racine tenant) est considéré
/// comme un artefact d'historique et ne doit pas être indexé, searchable ni scanné
/// pour le drift. La convention est `<tenant_id>/.history/<note_id>/<timestamp>.md`.
///
/// Exposé publiquement pour permettre aux consommateurs (scan Phase B untracked T12+,
/// filtrage dans drift detector) de filtrer les chemins history sans dupliquer la constante.
pub const HISTORY_DIR_PREFIX: &str = ".history/";

impl Vault {
    /// Écrit une note dans le vault en générant un nouvel ULID (comportement historique).
    ///
    /// Délègue à `write_note_inner` avec un `NoteId::new()`.
    ///
    /// ## Opérations
    ///
    /// 1. Force `vault_id = self.tenant_id` si absent du frontmatter.
    /// 2. Met à jour `frontmatter.updated` à `Utc::now()`.
    /// 3. Calcule `ContentHash::compute(&frontmatter, &body)`.
    /// 4. Génère un nouveau `NoteId` (ULID) via `NoteId::new()`.
    /// 5. Sérialise la note en Markdown via `gradatum-markdown::write`.
    /// 6. Persiste le `.md` à `<root>/<tenant>/<locus?>/<id>.md` via `FileStorage`.
    /// 7. Upsert l'index SQLite via `Index::upsert_note`.
    ///
    /// ## Erreurs
    ///
    /// - `VaultError::Core(GradatumError::Markdown(...))` si la sérialisation échoue.
    /// - `VaultError::Storage(...)` si l'écriture disque échoue.
    /// - `VaultError::Core(GradatumError::Storage(...))` si l'upsert SQLite échoue.
    pub async fn write_note(
        &self,
        frontmatter: Frontmatter,
        body: String,
    ) -> Result<Note, VaultError> {
        self.write_note_inner(frontmatter, body, NoteId::new())
            .await
    }

    /// Écrit une note en honorant un ULID fourni par l'appelant (item C —
    /// le worker passe le `note_id` préalloué à l'enqueue pour que
    /// write-time id == stored id, garantissant des wikilinks valides).
    ///
    /// Délègue à `write_note_inner` avec l'`id` fourni.
    pub async fn write_note_with_id(
        &self,
        frontmatter: Frontmatter,
        body: String,
        id: NoteId,
    ) -> Result<Note, VaultError> {
        self.write_note_inner(frontmatter, body, id).await
    }

    /// Logique commune d'écriture de note — l'`id` est fourni par l'appelant.
    ///
    /// Appelé par `write_note` (avec `NoteId::new()`), `write_note_with_id`
    /// (avec un ULID préalloué) et `write_if_match` (F-41 optimistic-lock).
    /// La SEULE différence fonctionnelle entre les deux appelants directs est
    /// l'origine de l'`id`. `write_if_match` ajoute la vérification hash en amont.
    ///
    /// `pub(crate)` : accessible depuis `crate::write` (F-41) et futur `crate::history` (F-40).
    pub(crate) async fn write_note_inner(
        &self,
        mut frontmatter: Frontmatter,
        body: String,
        id: NoteId,
    ) -> Result<Note, VaultError> {
        // ── Phase 4 — Read-before-write ─────────────────────────────────────────
        // Tenter de lire la version existante AVANT d'écrire.
        // `existing` est `None` pour une création, `Some(note)` pour une mise à jour.
        // Réutilisé par :
        //   - F-41 `write_if_match` (check optimistic-lock via content_hash)
        //   - F-40 Copy-on-Write (snapshot .history/ si sha256_for_history diffère)
        // NoteNotFound n'est pas une erreur — la note est simplement nouvelle.
        let existing: Option<Note> = match self.read_note(id).await {
            Ok(note) => Some(note),
            Err(VaultError::Core(gradatum_core::error::GradatumError::NoteNotFound(_))) => None,
            Err(other) => return Err(other),
        };

        // Invariant : vault_id doit correspondre au tenant courant
        if frontmatter.vault_id.0.is_empty() {
            frontmatter.vault_id = self.tenant_id.clone();
        }

        // Mise à jour du timestamp de modification
        frontmatter.updated = Some(Utc::now());

        let body_obj = NoteBody { markdown: body };

        // Calcul du ContentHash JCS (§2.2) — déterministe cross-langage
        let content_hash = ContentHash::compute(&frontmatter, &body_obj.markdown);

        let note = Note {
            id,
            frontmatter,
            body: body_obj,
            version: NoteVersion::initial(),
            content_hash,
            integrity_signature: None,
        };

        // Chemin relatif on-disk : <tenant>/<locus?>/<id>.md
        let md_path = note_md_relative_path(&note);

        // ── F-40 Copy-on-Write ───────────────────────────────────────────────────
        // Si une version précédente existe ET que le contenu sémantique a changé
        // (sha256_for_history diffère), copier le .md courant dans .history/ AVANT
        // d'écraser. Le snapshot est lu depuis le storage (cohérence OpenDAL) et écrit
        // dans `<tenant>/.history/<id>/<timestamp_ms>.md`.
        //
        // Chemins .history/ JAMAIS passés à upsert_note → exclus de l'index SQLite,
        // FTS5 et drift scanner par construction. Le préfixe HISTORY_DIR_PREFIX est
        // documenté pour la Phase B (walk filesystem untracked, T12+) afin d'éviter
        // qu'elle indexe les snapshots.
        if let Some(ref prev) = existing {
            // Comparer les hashes sémantiques (excluant updated, processed, etc.).
            if sha256_for_history(prev) != sha256_for_history(&note) {
                // Timestamp de la version précédente — utilisé comme nom de fichier histoire.
                // Priorité : updated (timestamp de dernière écriture connue), sinon created,
                // sinon timestamp ULID de l'id (garanti non-nul, sortable).
                let ts_ms = prev
                    .frontmatter
                    .updated
                    .or(Some(prev.frontmatter.created))
                    .map(|dt| dt.timestamp_millis())
                    .unwrap_or_else(|| prev.id.timestamp_ms() as i64);

                // Chemin snapshot : <tenant>/.history/<id>/<ts_ms>.md
                // Le tenant dans le chemin provient du frontmatter existant (cohérent avec md_path).
                // Note : .history/ est sous le tenant, PAS sous un locus — toujours à la racine
                // tenant pour rester adressable même si le locus change lors d'un renommage.
                let tenant = prev.frontmatter.vault_id.as_str();
                let id_str = prev.id.to_string();
                let history_dir = format!("{}/.history/{}/", tenant, id_str);
                let snapshot_path = format!("{}{}.md", history_dir, ts_ms);

                // Lire le contenu actuel depuis le storage (source de vérité on-disk).
                // Le chemin courant est reconstruit depuis `prev` (avant la mise à jour
                // du frontmatter `updated` effectuée quelques lignes plus haut).
                let current_md_path = note_md_relative_path(prev);
                match self.storage.read(&current_md_path).await {
                    Ok(current_bytes) => {
                        // Créer le répertoire .history/<id>/ si nécessaire (idempotent).
                        if let Err(e) = self.storage.create_dir(&history_dir).await {
                            tracing::warn!(
                                id = %id_str,
                                history_dir = %history_dir,
                                err = %e,
                                "F-40 CoW : impossible de créer .history/ — snapshot ignoré"
                            );
                        } else {
                            // Écrire le snapshot — échec non fatal (on continue l'écriture principale).
                            if let Err(e) = self.storage.write(&snapshot_path, &current_bytes).await
                            {
                                tracing::warn!(
                                    id = %id_str,
                                    snapshot_path = %snapshot_path,
                                    err = %e,
                                    "F-40 CoW : écriture snapshot .history/ échouée — snapshot ignoré"
                                );
                            } else {
                                tracing::debug!(
                                    id = %id_str,
                                    snapshot_path = %snapshot_path,
                                    "F-40 CoW : snapshot .history/ créé"
                                );
                                // ── D1 — Rétention bornée (F-32A) ────────────────────────
                                // Après chaque écriture CoW réussie, appliquer la politique
                                // de rétention configurée (max_versions + ttl_days).
                                // Suppression non fatale : un échec est loggué sans bloquer.
                                // `.max(0)` sature à 0 avant le cast → ANSSI R11 safe.
                                let now_ms = Utc::now().timestamp_millis().max(0) as u64;
                                self.trim_history_to_max(id, &id_str, tenant, now_ms).await;
                            }
                        }
                    }
                    Err(gradatum_storage::StorageError::NotFound(_)) => {
                        // Fichier source absent — incohérence index/disque, on log mais on continue.
                        tracing::warn!(
                            id = %id_str,
                            current_md_path = %current_md_path,
                            "F-40 CoW : fichier source introuvable pour snapshot .history/ — skip"
                        );
                    }
                    Err(e) => {
                        // Erreur I/O inattendue — non fatale, on continue l'écriture principale.
                        tracing::warn!(
                            id = %id_str,
                            err = %e,
                            "F-40 CoW : erreur lecture fichier source — snapshot ignoré"
                        );
                    }
                }
            }
        }

        // Sérialisation Markdown (§5.1)
        let md_content = gradatum_markdown::write(&note)
            .map_err(|e| GradatumError::Markdown(format!("sérialisation md: {e}")))?;

        // Persistance sur disque via OpenDAL FileStorage
        self.storage
            .write(&md_path, md_content.as_bytes())
            .await
            .map_err(|e| VaultError::Storage(format!("write md {md_path}: {e}")))?;

        // Upsert dans l'index SQLite (FTS5 + note_overrides + file_checksums)
        // Étape 0.1 : upsert_note est devenu write_note via DocumentStore trait.
        self.index.write_note(&note).await?;

        Ok(note)
    }

    /// Lit une note par identifiant ULID.
    ///
    /// ## Algorithme (T4 P2.0c)
    ///
    /// 1. **Cache hit** : vérifie la présence dans `EffectiveNoteCache` + valide le checksum
    ///    via `index.get_content_hash` (protection B22 contre stale cache concurrent).
    ///    Si valide → retourne la note directement, incrémente `cache_hits`.
    ///    Si stale → invalide l'entrée, passe au cache miss.
    /// 2. **Cache miss** : `index.get_note(vault_id, id)` → `NoteRecord`.
    ///    Lit le `.md` sur disque via `storage.read(path)` pour obtenir le Markdown complet.
    ///    Parse via `gradatum_markdown::parse` → `ParsedNote` → `Note` complète.
    ///    Insère dans le cache pour les appels suivants.
    ///
    /// ## Chemin disque
    ///
    /// Tente d'abord `<vault_id>/<id>.md` (sans locus).
    /// Si absent, tente `<vault_id>/<section>/<id>.md` (locus = section).
    ///
    /// ## Erreurs
    ///
    /// - `VaultError::Core(GradatumError::NoteNotFound)` si absent de l'index.
    /// - `VaultError::Storage(...)` si le fichier .md est introuvable sur disque.
    /// - `VaultError::Markdown(...)` si le parse échoue.
    pub async fn read_note(&self, id: NoteId) -> Result<Note, VaultError> {
        let vault_id = self.tenant_id.as_str();
        let id_str = id.to_string();

        // ── 1. Cache hit path ─────────────────────────────────────────────────
        // Clé composite : (NoteId, scope_hash=0 pour read_note sans scope override).
        let cache_key: CacheKey = (id, 0u64);
        let index_for_validator = Arc::clone(&self.index);
        let id_for_validator = id;

        let cached = self
            .cache
            .get(cache_key, move |note_id| async move {
                // Validator : lit le hash courant depuis SQLite.
                // None = note absente de l'index → stale entry.
                index_for_validator
                    .get_content_hash(note_id)
                    .await?
                    .ok_or(GradatumError::NoteNotFound(id_for_validator))
            })
            .await
            .map_err(VaultError::Core)?;

        if let Some(effective) = cached {
            // Cache hit valide — reconstruire Note depuis EffectiveNote.
            self.cache_hits.fetch_add(1, Ordering::Relaxed);
            return Ok(effective_note_to_note(&effective, id));
        }

        // ── 2. Cache miss path ────────────────────────────────────────────────
        // Vérifier que la note existe dans l'index.
        let record = self
            .index
            .get_note(vault_id, &id_str)
            .await
            .map_err(VaultError::Core)?
            .ok_or(VaultError::Core(GradatumError::NoteNotFound(id)))?;

        // Construire le chemin disque : essayer sans locus puis avec section comme locus.
        let path_no_locus = format!("{}/{}.md", vault_id, id_str);
        let path_with_section = format!("{}/{}/{}.md", vault_id, record.section, id_str);

        let md_bytes = if self.storage.exists(&path_no_locus).await.unwrap_or(false) {
            self.storage
                .read(&path_no_locus)
                .await
                .map_err(|e| VaultError::Storage(format!("read .md {path_no_locus}: {e}")))?
        } else {
            self.storage
                .read(&path_with_section)
                .await
                .map_err(|e| VaultError::Storage(format!("read .md {path_with_section}: {e}")))?
        };

        let md_str = String::from_utf8(md_bytes)
            .map_err(|e| VaultError::Storage(format!("UTF-8 decode .md {id_str}: {e}")))?;

        // Parse le Markdown complet pour reconstruire la Note.
        let parsed =
            gradatum_markdown::parse(&md_str).map_err(|e| VaultError::Markdown(e.to_string()))?;

        // Reconstruire la version depuis `record.version` si disponible (défaut : 1).
        let note = Note {
            id,
            frontmatter: parsed.frontmatter,
            body: parsed.body,
            version: NoteVersion::initial(),
            content_hash: parsed.content_hash,
            integrity_signature: None,
        };

        // Insérer dans le cache pour les appels suivants.
        let effective = Arc::new(note_to_effective_note(&note));
        self.cache
            .insert(cache_key, effective, note.content_hash)
            .await;

        Ok(note)
    }

    /// Met à jour le statut d'une note avec validation de la state machine.
    ///
    /// ## State machine
    ///
    /// Seules les transitions définies dans `NoteStatus::can_transition_to` sont
    /// autorisées. Toute autre transition retourne
    /// `VaultError::Core(GradatumError::InvalidStatusTransition { from, to })`.
    ///
    /// Si `target == current` (même statut), retourne `Ok(())` sans écriture
    /// (idempotence — évite les 409 lors de rejeux curator).
    ///
    /// ## Legacy `downgraded`
    ///
    /// La valeur `status='downgraded'` est écrite **directement en SQLite** par
    /// `vault_downgrade` (mécanisme F-39/wikilinks stables). Elle est hors de
    /// l'enum `NoteStatus` et donc hors du graphe de cette state machine.
    /// La state machine ignore ce cas : si le frontmatter .md d'une note contient
    /// un statut `downgraded`, `read_note` échoue au parse TOML → `NoteNotFound`
    /// (le champ `status` du .md ne peut pas être `downgraded` car `vault_downgrade`
    /// n'écrit que SQLite, pas le .md). Ce mécanisme distinct est documenté dans
    /// CLAUDE-GRADATUM.md.
    ///
    /// ## CoW
    ///
    /// La mise à jour passe par `write_note_with_id` (chemin normal) — chaque
    /// transition est tracée dans `.history/` via le mécanisme F-40 Copy-on-Write.
    ///
    /// ## Erreurs
    ///
    /// - `VaultError::Core(GradatumError::NoteNotFound)` si la note est absente.
    /// - `VaultError::Core(GradatumError::InvalidStatusTransition { from, to })`
    ///   si la transition n'est pas autorisée par la state machine.
    /// - `VaultError::Storage` / `VaultError::Markdown` sur erreur I/O ou parse.
    pub async fn update_status(
        &self,
        id: NoteId,
        target: NoteStatus,
        reason: Option<String>,
    ) -> Result<(), VaultError> {
        // Lire la version courante pour obtenir le statut actuel.
        // Propage NoteNotFound si la note est absente.
        let note = self.read_note(id).await?;
        let current = note.frontmatter.status;

        // Idempotence : target == current → no-op silencieux.
        // Évite les 409 lors de rejeux ou retries du curator.
        if current == target {
            return Ok(());
        }

        // Valider la transition via la state machine.
        if !current.can_transition_to(target) {
            return Err(VaultError::Core(GradatumError::InvalidStatusTransition {
                from: current,
                to: target,
            }));
        }

        // Construire le frontmatter mis à jour avec le nouveau statut.
        let mut new_fm = note.frontmatter.clone();
        new_fm.status = target;
        new_fm.status_reason = reason;
        new_fm.status_changed = Some(Utc::now());

        // Écrire via write_note_with_id (chemin normal → CoW trace la transition).
        // L'id est préservé (wikilinks stables).
        self.write_note_with_id(new_fm, note.body.markdown, id)
            .await?;

        Ok(())
    }

    /// D1 — Supprime une note et purge son répertoire `.history/<id>/`.
    ///
    /// ## Opérations (dans l'ordre)
    ///
    /// 1. Tente de localiser le `.md` sur disque (sans locus, puis avec section comme locus).
    ///    Si la note est absente de l'index → retourne `VaultError::Core(NoteNotFound)`.
    /// 2. Supprime le fichier `.md` via `storage.delete(md_path)`.
    /// 3. Purge le répertoire `.history/<id>/` via `purge_history_dir` (non fatale).
    ///
    /// ## Comportement sur erreur
    ///
    /// - Absence de la note (index) : `Err(VaultError::Core(NoteNotFound))`.
    /// - Échec de la suppression du `.md` : `Err(VaultError::Storage(...))` — fatal.
    /// - Échec de la purge `.history/` : warn! loggué, **non fatal** — la note est déjà supprimée.
    ///
    /// ## Note
    ///
    /// Cette fonction ne dé-indexe pas la note (pas de `delete_note` dans `DocumentStore`
    /// en v0.4.1). La suppression de l'entrée SQLite est différée à la prochaine passe
    /// du drift detector (Phase B). Les consommateurs qui cherchent la note via
    /// `read_note` obtiendront une erreur I/O (`.md` absent) jusqu'à la purge SQLite.
    pub async fn delete_note(&self, id: NoteId) -> Result<(), VaultError> {
        let vault_id = self.tenant_id.as_str();
        let id_str = id.to_string();

        // Localiser le .md depuis l'index (nécessaire pour connaître la section/locus).
        let record = self
            .index
            .get_note(vault_id, &id_str)
            .await
            .map_err(VaultError::Core)?
            .ok_or(VaultError::Core(GradatumError::NoteNotFound(id)))?;

        // Déterminer le chemin disque effectif (sans locus en priorité, puis avec section).
        let path_no_locus = format!("{}/{}.md", vault_id, id_str);
        let path_with_section = format!("{}/{}/{}.md", vault_id, record.section, id_str);

        let md_path = if self.storage.exists(&path_no_locus).await.unwrap_or(false) {
            path_no_locus
        } else {
            path_with_section
        };

        // Supprimer le fichier .md — fatal si échoue.
        self.storage
            .delete(&md_path)
            .await
            .map_err(|e| VaultError::Storage(format!("delete md {md_path}: {e}")))?;

        // Purger .history/<id>/ — non fatal.
        self.purge_history_dir(id, &id_str, vault_id).await;

        Ok(())
    }

    /// F-40 — Liste les versions archivées d'une note dans `.history/`.
    ///
    /// Retourne les timestamps (millisecondes Unix) des snapshots disponibles,
    /// triés en ordre croissant (plus ancien en premier).
    ///
    /// Chaque snapshot est un fichier `<tenant>/.history/<id>/<ts_ms>.md`.
    /// La liste est construite depuis le storage filesystem (OpenDAL) — PAS depuis
    /// l'index SQLite (les snapshots ne sont pas indexés par construction).
    ///
    /// ## Retour
    ///
    /// `Vec<i64>` vide si aucun historique n'existe (note créée mais jamais modifiée,
    /// ou CoW pas encore déclenché).
    ///
    /// ## Erreurs
    ///
    /// - `VaultError::Storage` si le listing du répertoire `.history/` échoue pour une
    ///   raison autre que "répertoire absent" (NotFound = liste vide, pas une erreur).
    pub async fn history_versions(&self, id: NoteId) -> Result<Vec<i64>, VaultError> {
        let tenant = self.tenant_id.as_str();
        let id_str = id.to_string();
        let history_dir = format!("{}/.history/{}/", tenant, id_str);

        let entries = match self.storage.list(&history_dir).await {
            Ok(entries) => entries,
            Err(gradatum_storage::StorageError::NotFound(_)) => {
                // Répertoire absent = pas d'historique → liste vide, pas une erreur.
                return Ok(Vec::new());
            }
            Err(e) => {
                return Err(VaultError::Storage(format!(
                    "history_versions list {history_dir}: {e}"
                )));
            }
        };

        // Extraire les timestamps depuis les noms de fichiers `<ts_ms>.md`.
        let mut timestamps: Vec<i64> = entries
            .iter()
            .filter(|e| !e.is_dir && e.path.ends_with(".md"))
            .filter_map(|e| {
                // Extraire le basename (dernier segment du chemin).
                let basename = e.path.rsplit('/').next()?;
                // Retirer l'extension `.md` et parser comme i64.
                basename.strip_suffix(".md")?.parse::<i64>().ok()
            })
            .collect();

        // Trier du plus ancien au plus récent (timestamps croissants).
        timestamps.sort_unstable();
        Ok(timestamps)
    }

    /// F-40 — Lit le contenu d'un snapshot historique d'une note.
    ///
    /// ## Paramètres
    ///
    /// - `id` : identifiant de la note.
    /// - `ts_ms` : timestamp du snapshot en millisecondes Unix (depuis `history_versions`).
    ///
    /// ## Erreurs
    ///
    /// - `VaultError::Storage` si le fichier snapshot est introuvable ou illisible.
    /// - `VaultError::Markdown` si le parsing du snapshot échoue.
    pub async fn history_get(&self, id: NoteId, ts_ms: i64) -> Result<Note, VaultError> {
        let tenant = self.tenant_id.as_str();
        let id_str = id.to_string();
        let snapshot_path = format!("{}/.history/{}/{}.md", tenant, id_str, ts_ms);

        let bytes =
            self.storage.read(&snapshot_path).await.map_err(|e| {
                VaultError::Storage(format!("history_get read {snapshot_path}: {e}"))
            })?;

        let md_str = String::from_utf8(bytes).map_err(|e| {
            VaultError::Storage(format!("history_get UTF-8 decode {snapshot_path}: {e}"))
        })?;

        let parsed =
            gradatum_markdown::parse(&md_str).map_err(|e| VaultError::Markdown(e.to_string()))?;

        // Reconstituer la Note depuis le snapshot parsé.
        // L'id est celui de la note courante (le snapshot est une version ancienne).
        let note = Note {
            id,
            frontmatter: parsed.frontmatter,
            body: parsed.body,
            version: NoteVersion::initial(),
            content_hash: parsed.content_hash,
            integrity_signature: None,
        };

        Ok(note)
    }

    // ── Helpers rétention + purge ─────────────────────────────────────────────

    /// Applique la politique de rétention après un CoW réussi.
    ///
    /// Délègue à [`Self::apply_history_trim`] en passant `now_ms = Utc::now()`.
    /// Séparé en deux méthodes pour permettre l'injection du clock dans les tests.
    ///
    /// Opération non fatale : tout échec de listing ou de suppression individuelle
    /// est loggué en `warn!` sans interrompre l'écriture principale.
    async fn trim_history_to_max(&self, id: NoteId, id_str: &str, tenant: &str, now_ms: u64) {
        self.apply_history_trim(id, id_str, tenant, &self.config.history, now_ms)
            .await;
    }

    /// Applique la politique de rétention configurable sur les snapshots `.history/`.
    ///
    /// ## Algorithme (ordre déterministe)
    ///
    /// 1. **TTL d'abord** (si `cfg.ttl_days = Some(n)`) : supprimer les snapshots dont
    ///    le timestamp `ts_ms` est antérieur à `now_ms - n * 24 * 3600 * 1000`.
    /// 2. **Cap count ensuite** (toujours) : si le nombre de snapshots restants dépasse
    ///    `cfg.max_versions`, supprimer les plus anciens (timestamps les plus petits).
    ///
    /// L'ordre TTL-avant-count garantit que les snapshots retenus après TTL sont toujours
    /// les `max_versions` les plus récents. Le résultat est déterministe et idempotent.
    ///
    /// ## Paramètres
    ///
    /// - `id` / `id_str` / `tenant` : identifiant de la note et tenant pour construire
    ///   les chemins de snapshots OpenDAL.
    /// - `cfg` : configuration de rétention (max_versions + ttl_days).
    /// - `now_ms` : timestamp courant en millisecondes Unix. Passer `Utc::now().timestamp_millis() as u64`
    ///   en production, ou une valeur simulée dans les tests pour contrôler le TTL.
    ///
    /// ## Comportement sur erreur
    ///
    /// Non fatale — tout échec de listing ou de suppression individuelle est loggué en
    /// `warn!` sans propager d'erreur.
    pub async fn apply_history_trim(
        &self,
        id: NoteId,
        id_str: &str,
        tenant: &str,
        cfg: &HistoryConfig,
        now_ms: u64,
    ) {
        // Récupérer la liste actuelle des snapshots (triée croissant par timestamp).
        let mut versions = match self.history_versions(id).await {
            Ok(v) => v,
            Err(e) => {
                tracing::warn!(
                    id = %id_str,
                    err = %e,
                    "D1/F-32A rétention : impossible de lister .history/ pour bornage"
                );
                return;
            }
        };

        // ── Étape 1 : TTL — supprimer les snapshots expirés ────────────────────
        if let Some(ttl_days) = cfg.ttl_days {
            // Seuil d'expiration en millisecondes : now_ms - ttl_days * 86_400_000.
            // On sature à 0 pour éviter un overflow si ttl_days est grand.
            let ttl_ms = u64::from(ttl_days).saturating_mul(24 * 3600 * 1000);
            let cutoff_ms = now_ms.saturating_sub(ttl_ms);

            // Collecter les timestamps expirés avant de muter `versions`.
            let expired: Vec<i64> = versions
                .iter()
                .copied()
                .filter(|&ts| {
                    // Un snapshot est expiré si son timestamp est antérieur au cutoff.
                    // Timestamp négatif ou invalide (< 0) → u64::try_from échoue →
                    // traité comme expiré (valeur 0 < cutoff_ms sauf si cutoff=0).
                    // Sémantique ANSSI R11 : cast explicite avec comportement documenté.
                    u64::try_from(ts).unwrap_or(0) < cutoff_ms
                })
                .collect();

            if !expired.is_empty() {
                tracing::debug!(
                    id = %id_str,
                    expired = expired.len(),
                    ttl_days = ttl_days,
                    "D1/F-32A TTL : suppression snapshots expirés"
                );
                for ts_ms in &expired {
                    let snapshot_path = format!("{}/.history/{}/{}.md", tenant, id_str, ts_ms);
                    if let Err(e) = self.storage.delete(&snapshot_path).await {
                        tracing::warn!(
                            id = %id_str,
                            snapshot_path = %snapshot_path,
                            err = %e,
                            "D1/F-32A TTL : échec suppression snapshot expiré — non fatal"
                        );
                    }
                }
                // Retirer les timestamps supprimés de la liste pour l'étape 2.
                versions.retain(|ts| !expired.contains(ts));
            }
        }

        // ── Étape 2 : cap count — limiter au max_versions restant ──────────────
        // max_versions = 0 est interprété comme 1 (garder au moins 1 snapshot).
        let effective_max = cfg.max_versions.max(1);

        if versions.len() <= effective_max {
            return;
        }

        let to_delete_count = versions.len() - effective_max;
        let to_delete = &versions[..to_delete_count];

        tracing::debug!(
            id = %id_str,
            total = versions.len(),
            deleting = to_delete_count,
            max = effective_max,
            "D1/F-32A cap count : suppression snapshots excédentaires"
        );

        for &ts_ms in to_delete {
            let snapshot_path = format!("{}/.history/{}/{}.md", tenant, id_str, ts_ms);
            if let Err(e) = self.storage.delete(&snapshot_path).await {
                tracing::warn!(
                    id = %id_str,
                    snapshot_path = %snapshot_path,
                    err = %e,
                    "D1/F-32A cap count : échec suppression snapshot — non fatal"
                );
            }
        }
    }

    /// D1 — Supprime récursivement le répertoire `.history/<id>/`.
    ///
    /// Utilisé lors de la suppression d'une note (`delete_note`) pour éviter les
    /// orphelins disque. Opération non fatale — tout échec est loggué en `warn!`.
    ///
    /// ## Algorithme
    ///
    /// 1. Liste tous les fichiers sous `<tenant>/.history/<id>/`.
    /// 2. Supprime chaque fichier via `storage.delete()`.
    /// 3. Tente de supprimer le répertoire vide lui-même (peut échouer si non vide
    ///    ou si le backend ne supporte pas la suppression de répertoire — non fatal).
    async fn purge_history_dir(&self, _id: NoteId, id_str: &str, tenant: &str) {
        let history_dir = format!("{}/.history/{}/", tenant, id_str);

        // Lister tous les entrées sous .history/<id>/.
        let entries = match self.storage.list(&history_dir).await {
            Ok(e) => e,
            Err(gradatum_storage::StorageError::NotFound(_)) => {
                // Pas de .history/ — rien à purger.
                return;
            }
            Err(e) => {
                tracing::warn!(
                    id = %id_str,
                    history_dir = %history_dir,
                    err = %e,
                    "D1 purge : impossible de lister .history/ — non fatal"
                );
                return;
            }
        };

        // Supprimer chaque fichier (pas les répertoires — OpenDAL delete ne supporte
        // pas les répertoires non vides ; on supprime les feuilles d'abord).
        for entry in entries.iter().filter(|e| !e.is_dir) {
            if let Err(e) = self.storage.delete(&entry.path).await {
                tracing::warn!(
                    id = %id_str,
                    path = %entry.path,
                    err = %e,
                    "D1 purge : échec suppression fichier .history/ — non fatal"
                );
            }
        }

        // Tenter de supprimer le répertoire maintenant vide.
        // Certains backends (S3) ne nécessitent pas cette étape ; pour Fs, le répertoire
        // reste si non vide — on ignore l'erreur.
        if let Err(e) = self.storage.delete(&history_dir).await {
            tracing::debug!(
                id = %id_str,
                history_dir = %history_dir,
                err = %e,
                "D1 purge : suppression répertoire .history/ — ignorée (peut rester vide)"
            );
        }
    }
}

// ── Helpers de conversion cache ───────────────────────────────────────────────

/// Convertit une `EffectiveNote` (depuis le cache) en `Note` complète.
///
/// `EffectiveNote` est structurellement identique à `Note` (pas d'overrides appliqués).
/// Reconstitue la `Note` depuis ses champs.
fn effective_note_to_note(effective: &EffectiveNote, id: NoteId) -> Note {
    Note {
        id,
        frontmatter: effective.frontmatter.clone(),
        body: effective.body.clone(),
        version: effective.version,
        content_hash: effective.content_hash,
        integrity_signature: None,
    }
}

/// Convertit une `Note` en `EffectiveNote` pour insertion dans le cache.
///
/// Projection directe — pas d'overrides appliqués.
fn note_to_effective_note(note: &Note) -> EffectiveNote {
    EffectiveNote {
        id: note.id,
        frontmatter: note.frontmatter.clone(),
        body: note.body.clone(),
        version: note.version,
        content_hash: note.content_hash,
    }
}

/// Construit le chemin relatif on-disk d'une note.
///
/// Format : `<tenant>/<locus>/<id>.md` ou `<tenant>/<id>.md` si pas de locus.
/// Le chemin est toujours relatif à la racine du vault (passé tel quel à `Storage::write`).
fn note_md_relative_path(note: &Note) -> String {
    let tenant = note.frontmatter.vault_id.as_str();
    let id_str = note.id.to_string();
    match note.frontmatter.locus.as_ref() {
        Some(locus) => format!("{}/{}/{}.md", tenant, locus.as_str(), id_str),
        None => format!("{}/{}.md", tenant, id_str),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use gradatum_core::scope::VaultId;
    use gradatum_core::section::Section;

    fn build_minimal_frontmatter() -> Frontmatter {
        Frontmatter {
            schema_version: 1,
            vault_id: VaultId::new("main"),
            locus: None,
            section: Section::Decisions,
            status: NoteStatus::Draft,
            status_reason: None,
            status_changed: None,
            tags: Default::default(),
            author: None,
            created: Utc::now(),
            updated: None,
            extra: Default::default(),
            provenance: None,
            forgotten: None,
            forgotten_at: None,
            forgotten_by: None,
        }
    }

    #[test]
    fn note_md_relative_path_no_locus() {
        let fm = build_minimal_frontmatter();
        let body = NoteBody {
            markdown: "test".into(),
        };
        let hash = ContentHash::compute(&fm, "test");
        let id = NoteId::new();
        let note = Note {
            id,
            frontmatter: fm,
            body,
            version: NoteVersion::initial(),
            content_hash: hash,
            integrity_signature: None,
        };
        let path = note_md_relative_path(&note);
        assert!(path.starts_with("main/"));
        assert!(path.ends_with(".md"));
    }

    #[test]
    fn note_md_relative_path_with_locus() {
        use gradatum_core::scope::LocusId;
        let mut fm = build_minimal_frontmatter();
        fm.locus = Some(LocusId::new("my-locus"));
        let body = NoteBody {
            markdown: "test".into(),
        };
        let hash = ContentHash::compute(&fm, "test");
        let id = NoteId::new();
        let note = Note {
            id,
            frontmatter: fm,
            body,
            version: NoteVersion::initial(),
            content_hash: hash,
            integrity_signature: None,
        };
        let path = note_md_relative_path(&note);
        assert!(path.starts_with("main/my-locus/"));
        assert!(path.ends_with(".md"));
    }
}