feat(persistence): couche conversationnelle — cadrage §18/§19 + briques P1→P4

Resync ARCHITECTURE.md (état livré + cadrage persistance/handoff) et premières briques de la couche de persistance conversationnelle (log canonique par paire + handoff incrémental), indépendante du provider — prépare reprise fiable et handoff cross-profile Claude↔Codex. ARCHITECTURE.md - §14.3.2/§17 : M5 marqué livré, verrou « ouvert » périmé, §17 réconcilié (vue = terminal de sortie, pas d'UI chat) ; §18 état livré 2026-06-12 ; §19 cadrage persistance/handoff (log par paire + handoff, 10 lots P1→P10) Domaine (conversation_log.rs, pur) - P1 : ConversationTurn / TurnId / TurnRole + port ConversationLog - P3 : Handoff + port HandoffStore - P4 : port HandoffSummarizer (async, seam OCP pour adapter LLM futur) Infrastructure (conversation_log/) - P2 : FsConversationLog — JSONL append-only par paire, sync_all (durabilité crash), skip ligne corrompue, fichier absent ⇒ vide - P3 : FsHandoffStore — handoff.md front-matter, write atomique tmp+rename - P4 : HeuristicHandoffSummarizer — incrémental, zéro modèle/I/O, fenêtre WINDOW Tests : domaine 12 + infra 24 (conversation_log) verts, suites complètes sans régression. Cycle dev/test : le binôme a débusqué et corrigé un bug de durabilité (append sans flush) au passage. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 13:09:35 +02:00
parent eca2ba95c4
commit 75e4f57a71
8 changed files with 2032 additions and 1 deletions
--- a/crates/infrastructure/src/conversation_log/handoff.rs
+++ b/crates/infrastructure/src/conversation_log/handoff.rs
@ -0,0 +1,217 @@
+//! [`FsHandoffStore`] — l'adapter `tokio::fs` du port [`HandoffStore`]
+//! (cadrage « persistance conversationnelle », lot P3).
+//!
+//! Le **point de reprise** d'une conversation (ARCHITECTURE §19.2/§19.3) est un
+//! [`Handoff`] : un résumé cumulatif Markdown borné par un curseur [`TurnId`]. On en
+//! garde **un seul** par conversation (le dernier), dans un fichier lisible à l'œil :
+//!
+//! ```text
+//! <project_root>/.ideai/conversations/
+//! └── <conversationId>/
+//!     ├── log.jsonl     # le log append-only (lot P2)
+//!     └── handoff.md    # le dernier point de reprise (ce module)
+//! ```
+//!
+//! ## Format `handoff.md`
+//!
+//! Un **front-matter** YAML délimité par `---`, suivi du corps `summary_md` tel quel :
+//!
+//! ```text
+//! ---
+//! upTo: 00000000-0000-0000-0000-00000000002a
+//! objective: livrer le lot P3
+//! ---
+//! # Résumé
+//! …le summary_md, octet pour octet…
+//! ```
+//!
+//! Le front-matter porte le curseur `upTo` (toujours) et `objective` (seulement s'il
+//! est `Some`). Le corps après le second `---\n` est le `summary_md` **exact** : le
+//! round-trip (`save` puis `load`) redonne le même [`Handoff`]. `objective` étant
+//! sérialisé sur une seule ligne, un objectif est interdit de retour-chariot ici ; en
+//! pratique c'est une phrase courte (un titre de but), jamais du multi-ligne.
+//!
+//! ## Robustesse
+//!
+//! - **Écriture atomique** : on écrit dans `handoff.md.tmp` puis on `rename` — jamais
+//!   de fichier à moitié écrit visible.
+//! - **Fichier absent** ⇒ `Ok(None)` (jamais une erreur) : une conversation sans
+//!   reprise est l'état normal au premier tour.
+//! - **Fichier présent mais illisible** (front-matter absent/incomplet, `upTo`
+//!   manquant ou non-UUID) ⇒ [`StoreError::Serialization`]. Contrairement au log
+//!   JSONL (où une ligne corrompue est sautée), un handoff corrompu est une vraie
+//!   erreur : il n'y a qu'un enregistrement, on ne peut pas « sauter ».
+
+use std::path::PathBuf;
+
+use async_trait::async_trait;
+
+use domain::conversation::ConversationId;
+use domain::conversation_log::{Handoff, HandoffStore, TurnId};
+use domain::ports::StoreError;
+use domain::project::ProjectPath;
+
+use super::{CONVERSATIONS_DIR, IDEAI_DIR};
+
+/// Nom du fichier de handoff, par conversation.
+const HANDOFF_FILE: &str = "handoff.md";
+
+/// Nom du fichier temporaire d'écriture atomique (renommé sur `handoff.md`).
+const HANDOFF_TMP_FILE: &str = "handoff.md.tmp";
+
+/// Délimiteur de front-matter (en tête et fin de l'entête).
+const FRONT_MATTER_FENCE: &str = "---";
+
+/// Adapter `tokio::fs` du store de handoff, un `handoff.md` par conversation.
+///
+/// Même convention de construction que [`super::FsConversationLog`] : le **project
+/// root** est fourni au constructeur, la base `<root>/.ideai/conversations` en dérive,
+/// et chaque conversation a son sous-dossier `<conversationId>/`.
+pub struct FsHandoffStore {
+    /// Racine `<project_root>/.ideai/conversations`.
+    base: PathBuf,
+}
+
+impl FsHandoffStore {
+    /// Construit l'adapter à partir du **project root**.
+    ///
+    /// La base `<root>/.ideai/conversations` en est dérivée ; le dossier de
+    /// conversation est créé paresseusement au premier `save`.
+    #[must_use]
+    pub fn new(root: &ProjectPath) -> Self {
+        let base = PathBuf::from(root.as_str())
+            .join(IDEAI_DIR)
+            .join(CONVERSATIONS_DIR);
+        Self { base }
+    }
+
+    /// `<base>/<conversationId>` — le dossier d'une conversation.
+    fn conversation_dir(&self, conversation: ConversationId) -> PathBuf {
+        self.base.join(conversation.to_string())
+    }
+
+    /// `<base>/<conversationId>/handoff.md` — le fichier de handoff d'une conversation.
+    fn handoff_path(&self, conversation: ConversationId) -> PathBuf {
+        self.conversation_dir(conversation).join(HANDOFF_FILE)
+    }
+
+    /// `<base>/<conversationId>/handoff.md.tmp` — le fichier temporaire d'écriture.
+    fn handoff_tmp_path(&self, conversation: ConversationId) -> PathBuf {
+        self.conversation_dir(conversation).join(HANDOFF_TMP_FILE)
+    }
+}
+
+/// Sérialise un [`Handoff`] au format `handoff.md` (front-matter + corps exact).
+fn serialize(handoff: &Handoff) -> String {
+    let mut out = String::new();
+    out.push_str(FRONT_MATTER_FENCE);
+    out.push('\n');
+    out.push_str(&format!("upTo: {}\n", handoff.up_to));
+    if let Some(objective) = &handoff.objective {
+        out.push_str(&format!("objective: {objective}\n"));
+    }
+    out.push_str(FRONT_MATTER_FENCE);
+    out.push('\n');
+    // Corps : le summary_md tel quel, octet pour octet.
+    out.push_str(&handoff.summary_md);
+    out
+}
+
+/// Parse le contenu d'un `handoff.md` en [`Handoff`].
+///
+/// Format attendu : `---\n<clé: valeur>*\n---\n<summary_md>`. Le corps après le second
+/// `---\n` est rendu **exact**. Toute déviation (front-matter absent/incomplet, `upTo`
+/// manquant ou non-UUID) ⇒ `Err(StoreError::Serialization)`.
+fn deserialize(content: &str) -> Result<Handoff, StoreError> {
+    let bad = |msg: &str| StoreError::Serialization(format!("handoff.md: {msg}"));
+
+    // Entête : `---\n` exactement en tête.
+    let after_open = content
+        .strip_prefix(FRONT_MATTER_FENCE)
+        .and_then(|rest| rest.strip_prefix('\n'))
+        .ok_or_else(|| bad("front-matter ouvrant `---` absent"))?;
+
+    // Fin de l'entête : la première ligne `---\n` (ou `---` en toute fin).
+    // On sépare les lignes du front-matter du corps.
+    let mut up_to: Option<TurnId> = None;
+    let mut objective: Option<String> = None;
+
+    // Trouver le `---` de fermeture, ligne par ligne.
+    let mut rest = after_open;
+    loop {
+        // Découpe la prochaine ligne (jusqu'au `\n` inclus si présent).
+        let (line, tail) = match rest.find('\n') {
+            Some(idx) => (&rest[..idx], &rest[idx + 1..]),
+            None => (rest, ""),
+        };
+
+        if line == FRONT_MATTER_FENCE {
+            // Fermeture trouvée : `tail` est le corps exact.
+            let up_to = up_to.ok_or_else(|| bad("clé `upTo` absente du front-matter"))?;
+            return Ok(Handoff {
+                summary_md: tail.to_string(),
+                up_to,
+                objective,
+            });
+        }
+
+        // Une ligne de clé: valeur dans le front-matter.
+        let (key, value) = line
+            .split_once(':')
+            .ok_or_else(|| bad("ligne de front-matter sans `:`"))?;
+        let value = value.trim();
+        match key.trim() {
+            "upTo" => {
+                let uuid = uuid::Uuid::parse_str(value)
+                    .map_err(|_| bad("`upTo` n'est pas un UUID valide"))?;
+                up_to = Some(TurnId::from_uuid(uuid));
+            }
+            "objective" => objective = Some(value.to_string()),
+            // Clé inconnue : tolérée (extensible), ignorée.
+            _ => {}
+        }
+
+        if tail.is_empty() {
+            // Plus de lignes et toujours pas de `---` fermant.
+            return Err(bad("front-matter fermant `---` absent"));
+        }
+        rest = tail;
+    }
+}
+
+#[async_trait]
+impl HandoffStore for FsHandoffStore {
+    async fn load(&self, conversation: ConversationId) -> Result<Option<Handoff>, StoreError> {
+        let content = match tokio::fs::read_to_string(self.handoff_path(conversation)).await {
+            Ok(content) => content,
+            // Absent ⇒ pas de reprise (jamais une erreur).
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+            Err(e) => return Err(StoreError::Io(e.to_string())),
+        };
+        deserialize(&content).map(Some)
+    }
+
+    async fn save(
+        &self,
+        conversation: ConversationId,
+        handoff: Handoff,
+    ) -> Result<(), StoreError> {
+        let body = serialize(&handoff);
+
+        let dir = self.conversation_dir(conversation);
+        tokio::fs::create_dir_all(&dir)
+            .await
+            .map_err(|e| StoreError::Io(e.to_string()))?;
+
+        // Écriture atomique : écrire le tmp puis `rename` sur la cible. Un lecteur ne
+        // voit jamais de fichier à moitié écrit (le rename est atomique sur le FS).
+        let tmp = self.handoff_tmp_path(conversation);
+        tokio::fs::write(&tmp, body.as_bytes())
+            .await
+            .map_err(|e| StoreError::Io(e.to_string()))?;
+        tokio::fs::rename(&tmp, self.handoff_path(conversation))
+            .await
+            .map_err(|e| StoreError::Io(e.to_string()))?;
+        Ok(())
+    }
+}