gradatum_core/

job.rs

//! Types primitifs pour le système de jobs (v0.2.0+ — ARCH-D15).
//!
//! Ce module définit les types canoniques L0 utilisés par toute la couche
//! job infrastructure. Il appartient à `gradatum-core` pour permettre aux
//! crates de niveaux supérieurs (`gradatum-queue`, `gradatum-worker`,
//! `gradatum-db-sqlite`) d'en dépendre sans cycle.
//!
//! # Couches architecturales
//!
//! ```text
//! gradatum-core (L0) — Job, JobRecord, QueueStore, QueueEvent, DryRunAware
//!     ↑
//! gradatum-db-sqlite (L2) — SqliteQueueStore impl QueueStore
//!     ↑
//! gradatum-queue (L3)     — GradatumQueue facade (Apalis backend)
//!     ↑
//! gradatum-worker (L4)    — handlers Apalis + orchestration
//! ```
//!
//! # Ordre bincode — IMMUABLE
//!
//! Les variants de [`Job`] sont encodés par position par `bincode`.
//! **Ne jamais réordonner les variants existants.** Ajouter uniquement en fin
//! de liste. Violation = corruption silencieuse des jobs stockés en base.
//!
//! # Références
//!
//! - Decision ARCH-D15 : `docs/decisions/ARCH-D15-apalis-embedded.md`

#![allow(dead_code)] // types consommés progressivement selon le pipeline

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::time::Duration;
use tokio::sync::broadcast::Receiver;
use ulid::Ulid;

// ─────────────────────────────────────────────────────────────────────────────
// VaultScope — alias canonique
// ─────────────────────────────────────────────────────────────────────────────

/// Scope d'un job ou d'une requête vault.
///
/// `VaultScope` est l'alias de type pour [`JobScope`] — les deux noms coexistent
/// pour maintenir la cohérence avec le code vault existant (`VaultScope`) et le
/// nouveau système de jobs (`JobScope`).
pub type VaultScope = JobScope;

// ─────────────────────────────────────────────────────────────────────────────
// Job enum — ordre bincode figé (v55)
// ─────────────────────────────────────────────────────────────────────────────

/// Type de job soumis à la queue.
///
/// # Ordre bincode — IMMUABLE
///
/// Les variants sont encodés par position (0-20). Ne jamais réordonner.
/// Ajouter uniquement en fin de liste.
///
/// Les commentaires de position `(N)` sont informatifs — bincode encode par
/// ordre de déclaration Rust, pas par valeur numérique explicite.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", content = "data")]
pub enum Job {
    // System jobs (0-12) — automatiques
    /// ReAct loop F-04 — position bincode 0.
    Agent,
    /// Step `[[pipelines]]` F-52 — position bincode 1.
    Pipeline,
    /// Web crawler F-20 — position bincode 2.
    Collect,
    /// Semantic/Learn/Peer/Rationale F-22 — position bincode 3.
    Distill,
    /// Sauvegarde vault — position bincode 4.
    Backup,
    /// Lifecycle purge (suppression des notes Garbage) — position bincode 5.
    ///
    /// Variant unit→tuple : position 5 INCHANGÉE. Les jobs Purge existants en queue
    /// doivent être absents avant déploiement.
    Purge(PurgeSpec),
    /// FtsOnly/VectorsOnly/Full/MissingOnly F-15 — position bincode 6.
    ReIndex(ReIndexMode),
    /// Zone B compression F-30 — position bincode 7.
    Summarize,
    /// Memory Validation + healing F-43 — position bincode 8.
    Validate,
    /// Vault score + dédup F-51 — position bincode 9.
    Audit,
    /// Modèles mentaux F-49 — position bincode 10.
    Consolidate,
    /// Inbox/ classification F-42 — position bincode 11.
    Curate(CurateSpec),
    /// Oubli sémantique de notes (forget) — position bincode 12.
    ///
    /// Variant unit→tuple : position 12 INCHANGÉE. Les jobs Forget existants en queue
    /// doivent être absents avant déploiement.
    Forget(ForgetSpec),

    // Human jobs (13-16) — JobClass::Human requis
    /// Valide/rejette un lot de notes `needs-review` — position bincode 13.
    Review,
    /// Classifie manuellement une note `inbox/` non résolue — position bincode 14.
    Classify,
    /// Fusionne deux notes dupliquées (post `Job::Audit`) — position bincode 15.
    Merge,
    /// Enrichit les métadonnées d'un lot de notes — position bincode 16.
    Annotate,

    // Nouveaux variants v59 — ajoutés EN FIN (ordre bincode figé)
    /// Import predecessor v1.6.2 → Gradatum · `JobClass::Human` — position bincode 17.
    Migrate(MigrateSource),
    /// CSV/PDF/JSON depuis notes · `JobClass::Agent|Human` — position bincode 18.
    Export(ExportSource),
    /// Notification externe cascade · `JobClass::System` — position bincode 19.
    Notify(NotifySource),
    /// Ingestion document F-06 via queue · `JobClass::Agent|Human` — position bincode 20.
    Ingest(IngestSource),

    // Embed : ajouté EN FIN pour préserver l'ordre bincode des variants 0-20
    /// Génération d'embedding vectoriel — position bincode 21.
    Embed(EmbedSpec),
}

// ─────────────────────────────────────────────────────────────────────────────
// ReIndexMode
// ─────────────────────────────────────────────────────────────────────────────

/// Mode de réindexation pour [`Job::ReIndex`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ReIndexMode {
    /// Rebuild FTS5 + PageRank (défaut).
    FtsOnly,
    /// Recalcule tous les embeddings (après migration modèle).
    VectorsOnly,
    /// FtsOnly + VectorsOnly.
    Full,
    /// Embed uniquement les notes sans vecteur (nouvelles notes).
    ///
    /// Plus rapide que `VectorsOnly` sur grand vault actif.
    MissingOnly,
}

// ─────────────────────────────────────────────────────────────────────────────
// Source structs — variants actifs
// ─────────────────────────────────────────────────────────────────────────────

/// Spécification d'un job de curation (`Job::Curate`).
///
/// Classification `inbox/`, scoring, mise à jour des métadonnées.
///
/// ## Champs write optionnels
///
/// Les champs `title`, `body`, `author`, `tags`, `section_hint` sont portés
/// directement dans `CurateSpec` pour le path `vault_write → job_store`.
/// Ils sont optionnels (`#[serde(default)]`) — rétrocompatibles avec les
/// `JobRecord` existants (champ absent en JSON → `None`/`[]`).
///
/// Pour les jobs `Job::Curate` déclenchés par `vault_write` :
/// - `title` + `body` sont `Some` — portent le contenu à créer dans le vault.
///
/// Pour les jobs `Job::Curate` déclenchés par reclassification :
/// - `title` + `body` sont `None` — la note existe déjà dans le vault.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CurateSpec {
    /// Identifiant ULID de la note à curer.
    pub note_id: Ulid,
    /// Identifiant du tenant propriétaire (défaut : `"main"`).
    #[serde(default = "default_tenant_main")]
    pub tenant_id: String,
    /// Titre de la note (présent pour vault_write, absent pour reclassification).
    #[serde(default)]
    pub title: Option<String>,
    /// Corps Markdown de la note (présent pour vault_write).
    #[serde(default)]
    pub body: Option<String>,
    /// Auteur de la note (optionnel).
    #[serde(default)]
    pub author: Option<String>,
    /// Tags initiaux (optionnel — le curator peut en ajouter d'autres).
    #[serde(default)]
    pub tags: Vec<String>,
    /// Section suggérée (optionnel — le curator peut surclasser).
    #[serde(default)]
    pub section_hint: Option<String>,
    /// F-41 — Hash SHA-256 attendu pour l'optimistic-lock (optionnel).
    ///
    /// Si `Some`, le worker vérifie que le hash courant de la note correspond
    /// avant d'écrire. Sur mismatch : job marqué `Conflict`, note non écrasée.
    /// `None` = écriture inconditionnelle (rétrocompat — comportement actuel inchangé).
    ///
    /// Sérialisé en bincode comme `Option<[u8; 32]>` (32 octets fixes ou None).
    /// Taille payload : +33 octets (1 discriminant bincode + 32 octets hash) → négligeable.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expected_sha256: Option<[u8; 32]>,
}

fn default_tenant_main() -> String {
    "main".to_string()
}

/// Spécification d'un job d'embedding (`Job::Embed`).
///
/// Génération ou régénération du vecteur via `gradatum-embed::FallbackEmbedder`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmbedSpec {
    /// Identifiant ULID de la note à embedder.
    pub note_id: Ulid,
    /// Identifiant du tenant propriétaire (défaut : `"main"`).
    pub tenant_id: String,
    /// Forcer la régénération même si un vecteur existe déjà.
    pub force_regenerate: bool,
}

// ─────────────────────────────────────────────────────────────────────────────
// Source structs — nouveaux variants v59
// ─────────────────────────────────────────────────────────────────────────────

/// Source pour [`Job::Migrate`] — import predecessor vault → Gradatum.
///
/// `JobClass::Human` uniquement — action irréversible.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MigrateSource {
    /// Chemin du vault source.
    pub from_path: String,
    /// Mode de migration.
    pub mode: MigrateMode,
    /// Stratégie de résolution des conflits.
    pub conflict: ConflictStrategy,
    /// Simuler sans écrire — obligatoire en premier passage.
    pub dry_run: bool,
    /// Vault de destination.
    pub target: VaultScope,
}

/// Mode de migration pour [`MigrateSource`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum MigrateMode {
    /// Mapping 10 sections → `CognitiveCategory` + `ContentSection` §16.
    PredecessorV1,
    /// Import depuis un autre vault Gradatum.
    GradatumVault,
    /// Import Markdown brut sans mapping.
    RawMarkdown,
}

/// Stratégie de résolution des conflits pour [`MigrateSource`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ConflictStrategy {
    /// Écraser les notes existantes.
    Overwrite,
    /// Garder les existantes, ignorer les nouvelles.
    Skip,
    /// Suffixe `-imported` sur les conflits.
    Rename,
}

/// Source pour [`Job::Export`] — générer un fichier depuis des notes vault.
///
/// `JobClass::Agent | Human`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExportSource {
    /// Scope des notes à exporter.
    pub scope: VaultScope,
    /// Filtre FTS optionnel (ex : `"sections:decisions"`).
    pub filter: Option<String>,
    /// Format d'export.
    pub format: ExportFormat,
    /// Chemin OpenDAL destination (ex : `"exports/decisions-2026-05.pdf"`).
    pub target: String,
    /// Template Markdown pour le rendu.
    pub template: Option<String>,
}

/// Format d'export pour [`ExportSource`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum ExportFormat {
    /// Une ligne par note — titre, locus, trust, date, sections.
    Csv,
    /// Rendu Markdown → PDF (pandoc ou similaire).
    Pdf,
    /// Sérialisation complète des `Document` + frontmatter.
    Json,
    /// Concaténation des notes en un seul `.md`.
    Markdown,
    /// Archive des fichiers `.md` bruts.
    Zip,
}

/// Source pour [`Job::Notify`] — notification externe en cascade.
///
/// `JobClass::System` — déclenché via `await_jobs` `OnDone`/`OnFailed`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NotifySource {
    /// Canal de notification.
    pub channel: NotifyChannel,
    /// Template du message avec variables (ex : `"Job {{job_kind}} terminé : {{notes_created}} notes"`).
    pub template: String,
    /// Job dont on notifie la complétion.
    pub job_ref: Option<Ulid>,
}

/// Canal de notification pour [`NotifySource`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum NotifyChannel {
    /// Notification Telegram.
    Telegram {
        /// Identifiant du chat Telegram.
        chat_id: String,
    },
    /// Notification Slack via webhook.
    Slack {
        /// URL du webhook Slack.
        webhook_url: String,
    },
    /// Notification HTTP webhook générique.
    Webhook {
        /// URL du webhook.
        url: String,
        /// Méthode HTTP (`POST` recommandé).
        method: String,
    },
    /// Publication NATS.
    Nats {
        /// Subject NATS cible.
        subject: String,
    },
    /// Notification email.
    Email {
        /// Adresse email destinataire.
        to: String,
    },
}

/// Source pour [`Job::Ingest`] — ingestion document F-06 via queue.
///
/// `JobClass::Agent | Human`. Remplace `gradatum-admin vault import --file`
/// pour les corpus larges (progress + retry).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IngestSource {
    /// Source d'entrée à ingérer.
    pub source: IngestInputSource,
    /// Vault destination.
    pub vault: String,
    /// Locus destination (ex : `"rag/"`).
    pub locus: String,
    /// Stratégie d'ingestion.
    pub strategy: IngestStrategy,
    /// Simuler sans écrire — exceptions légitimes (opération potentiellement
    /// volumineuse, validation humaine recommandée).
    pub dry_run: bool,
}

/// Source d'entrée pour [`IngestSource`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum IngestInputSource {
    /// Chemin OpenDAL.
    File {
        /// Chemin du fichier.
        path: String,
    },
    /// URL à fetcher.
    Url {
        /// URL à ingérer.
        url: String,
    },
    /// Batch d'URLs.
    Urls {
        /// Liste des URLs à ingérer.
        urls: Vec<String>,
    },
    /// Dossier de fichiers déjà sur disque.
    Locus {
        /// Chemin du dossier.
        path: String,
    },
}

/// Stratégie d'ingestion pour [`IngestSource`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum IngestStrategy {
    /// Détecte automatiquement : `StructureGuided` ou `SlidingWindow`.
    Auto,
    /// Skeleton tree + structure-guided chunking.
    ForceStructured,
    /// Sliding window même si des headings sont présents.
    ForceSlidingWindow,
}

// ─────────────────────────────────────────────────────────────────────────────
// PurgeSpec + PurgeMode — Job::Purge (F-32C)
// ─────────────────────────────────────────────────────────────────────────────

/// Mode de purge pour [`PurgeSpec`].
///
/// Seul `Lifecycle` est implémenté en v0.4.3 : suppression des notes `Garbage`
/// dont l'ancienneté en Garbage (`status_changed`) dépasse `grace_days`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum PurgeMode {
    /// Supprime les notes `status=Garbage` ayant atteint la période de grâce.
    ///
    /// Ancienneté mesurée via la colonne `status_changed` de l'index (mise à jour par `update_status`).
    Lifecycle,
}

/// Spécification d'un job de purge (`Job::Purge`).
///
/// ## Dry-run obligatoire
///
/// `dry_run = true` est le défaut prudent. En mode dry-run, le handler liste les
/// notes éligibles et retourne [`JobOutput::dry_run`] **sans rien supprimer**.
///
/// La purge réelle (`dry_run = false`) doit être déclenchée explicitement.
///
/// ## Ancienneté
///
/// `grace_days` : durée minimale en état `Garbage` avant suppression.
/// Mesurée via la colonne `status_changed` de l'index SQLite. Défaut : `Some(30)` (prudent).
/// `None` = supprime toutes les notes Garbage sans délai (dangereux — CLI expert uniquement).
///
/// ## Cron
///
/// Le schedule cron purge nightly est INTENTIONNELLEMENT désactivé (voir config-full.toml).
/// Activation = décision opérateur séparée (prérequis : stratégie backup nocturne configurée).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PurgeSpec {
    /// Mode de purge — seul `Lifecycle` est implémenté en v0.4.3.
    pub mode: PurgeMode,
    /// Simulation sans écriture — défaut `true` (prudent).
    ///
    /// Exception à la règle v62 (`JobMode::DryRun` dans `JobSpec`) : le purge est une
    /// opération irréversible à fort impact (suppression permanente). Le double mécanisme
    /// (`spec.dry_run` + `JobMode::DryRun`) garantit qu'aucune écriture ne se produit
    /// si l'un des deux est actif.
    #[serde(default = "PurgeSpec::default_dry_run")]
    pub dry_run: bool,
    /// Ancienneté minimale en état Garbage avant suppression (jours).
    ///
    /// Défaut : `Some(30)`. `None` = pas de délai de grâce (CLI expert uniquement).
    #[serde(default = "PurgeSpec::default_grace_days")]
    pub grace_days: Option<u32>,
}

impl PurgeSpec {
    fn default_dry_run() -> bool {
        true
    }

    fn default_grace_days() -> Option<u32> {
        Some(30)
    }
}

impl Default for PurgeSpec {
    fn default() -> Self {
        Self {
            mode: PurgeMode::Lifecycle,
            dry_run: true,
            grace_days: Some(30),
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// ForgetSpec + ForgetScope — Job::Forget (F-44)
// ─────────────────────────────────────────────────────────────────────────────

/// Scope de résolution d'un job de forget (`Job::Forget`).
///
/// Trois modes de ciblage :
/// - `Topic` : résolution via FTS (recherche plein-texte) sur un vault optionnel.
/// - `Locus` : préfixe de locus (répertoire vault) — échappement LIKE appliqué côté worker.
/// - `Agent` : toutes les notes d'un agent donné dans les vaults spécifiés.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub enum ForgetScope {
    /// Résolution via recherche FTS — les notes correspondant à `query` sont ciblées.
    ///
    /// `vault` : tenant optionnel (`None` → vault principal `"main"`).
    /// `limit` : cap prudent sur le nombre de notes ciblées (défaut 50, max 200).
    Topic {
        /// Requête FTS (ex. `"secrets api-key"`).
        query: String,
        /// Tenant cible (optionnel — `None` = `"main"`).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        vault: Option<String>,
        /// Cap sur le nombre de résultats ciblés (défaut 50).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        limit: Option<usize>,
    },
    /// Résolution par préfixe de locus.
    ///
    /// `locus` est échappé LIKE côté worker. Exemples : `"inbox/"`, `"rag/corpus-x/"`.
    Locus {
        /// Tenant cible.
        vault: String,
        /// Préfixe locus (ex. `"inbox/old/"`) — matchera toutes les notes dont
        /// le locus commence par cette valeur.
        locus: String,
    },
    /// Résolution par agent — toutes les notes d'un `agent_id` dans les vaults spécifiés.
    ///
    /// `vaults` vide → vault `"main"` uniquement.
    Agent {
        /// Identifiant de l'agent (colonne `author_id`).
        agent_id: String,
        /// Liste de vaults cibles (`[]` → `["main"]`).
        #[serde(default)]
        vaults: Vec<String>,
    },
}

/// Spécification d'un job de forget (`Job::Forget`).
///
/// ## Dry-run obligatoire
///
/// `dry_run = true` est le défaut. En dry-run : le handler liste les ULIDs cibles +
/// exclusions (sections protégées) et retourne [`JobOutput::dry_run`] **sans aucune mutation**.
///
/// La mutation réelle (`dry_run = false`) nécessite en outre un `confirm_ulids`
/// correspondant exactement aux ULIDs de la preview (double confirmation).
///
/// ## Sections protégées
///
/// Les notes des sections `AgentIssues` et `Council` sont **toujours exclues** du lot,
/// quel que soit le scope. Elles sont signalées dans la preview sans bloquer le job.
///
/// ## Non-destructif
///
/// Le forget modifie le frontmatter YAML (`forgotten=true`, `forgotten_at`, `forgotten_by`)
/// via le chemin d'écriture normal (CoW tracé). Aucune suppression physique.
/// La purge physique est réservée à `Job::Purge`.
///
/// ## Idempotence
///
/// Un double forget est idempotent : `mark_forgotten` met à jour le timestamp si
/// la note est déjà forgotten — pas d'erreur.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ForgetSpec {
    /// Scope de résolution — détermine les notes cibles.
    pub scope: ForgetScope,
    /// Dry-run (simulation sans mutation) — défaut `true` (prudent).
    ///
    /// Exception à la règle v62 : opération à effet persistant sur le scoring.
    /// Double mécanisme (`spec.dry_run` + `JobMode::DryRun`) garantit l'absence
    /// de mutation si l'un des deux est actif.
    #[serde(default = "ForgetSpec::default_dry_run")]
    pub dry_run: bool,
    /// Acteur ayant déclenché le forget (pour auditabilité — `forgotten_by`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub forgotten_by: Option<String>,
    /// ULIDs confirmés depuis une preview préalable (double confirmation).
    ///
    /// En mode réel (`dry_run = false`) : doit correspondre exactement aux ULIDs
    /// retournés par la preview. Mismatch → job en erreur (Business), aucune mutation.
    /// `None` autorisé uniquement en dry_run.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub confirm_ulids: Vec<String>,
}

impl ForgetSpec {
    fn default_dry_run() -> bool {
        true
    }
}

impl Default for ForgetSpec {
    fn default() -> Self {
        Self {
            scope: ForgetScope::Topic {
                query: String::new(),
                vault: None,
                limit: Some(50),
            },
            dry_run: true,
            forgotten_by: None,
            confirm_ulids: vec![],
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// job_kind_str — helper de routing
// ─────────────────────────────────────────────────────────────────────────────

/// Retourne le nom du variant [`Job`] sous forme de chaîne statique.
///
/// Utilisé pour dénormaliser la colonne `kind` dans `gradatum_jobs` à l'enqueue,
/// et pour filtrer par `kind` dans [`QueueStore::dequeue_by_kind`].
///
/// # Exhaustivité
///
/// Ce match est exhaustif sans `_ =>` pour garantir qu'un nouveau variant de [`Job`]
/// provoque une erreur de compilation plutôt qu'un routage silencieusement incorrect.
///
/// # Correspondance JSON
///
/// La valeur retournée correspond à la clé `"type"` du payload sérialisé via
/// `#[serde(tag = "type", content = "data")]` (ex. `{"spec":{"kind":{"type":"Curate",...}}}`).
#[must_use]
pub fn job_kind_str(job: &Job) -> &'static str {
    match job {
        Job::Agent => "Agent",
        Job::Pipeline => "Pipeline",
        Job::Collect => "Collect",
        Job::Distill => "Distill",
        Job::Backup => "Backup",
        Job::Purge(_) => "Purge",
        Job::ReIndex(_) => "ReIndex",
        Job::Summarize => "Summarize",
        Job::Validate => "Validate",
        Job::Audit => "Audit",
        Job::Consolidate => "Consolidate",
        Job::Curate(_) => "Curate",
        Job::Forget(_) => "Forget",
        Job::Review => "Review",
        Job::Classify => "Classify",
        Job::Merge => "Merge",
        Job::Annotate => "Annotate",
        Job::Migrate(_) => "Migrate",
        Job::Export(_) => "Export",
        Job::Notify(_) => "Notify",
        Job::Ingest(_) => "Ingest",
        Job::Embed(_) => "Embed",
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// JobSpec — ce que fait le job
// ─────────────────────────────────────────────────────────────────────────────

/// Spécification fonctionnelle d'un job.
///
/// Contient le type de travail, la classe de déclencheur, le mode d'exécution,
/// le scope et la priorité.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobSpec {
    /// Type fonctionnel + payload.
    pub kind: Job,
    /// Qui déclenche le job.
    pub class: JobClass,
    /// Comment s'exécute le job.
    pub mode: JobMode,
    /// Sur quoi s'applique le job.
    pub scope: JobScope,
    /// Priorité dans la queue.
    pub priority: JobPriority,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobClass
// ─────────────────────────────────────────────────────────────────────────────

/// Classe de déclencheur d'un job.
///
/// Détermine la priorité par défaut et le routage dans la queue.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum JobClass {
    /// Cron autonome — pas d'acteur humain.
    System,
    /// Déclenché/exécuté par un agent LLM.
    Agent,
    /// Action explicite CLI/studio.
    Human,
    /// Appel machine externe (MCP, tiers).
    Api,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobMode
// ─────────────────────────────────────────────────────────────────────────────

/// Mode d'exécution d'un job.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum JobMode {
    /// Traite N éléments, s'arrête (défaut).
    #[default]
    Batch,
    /// Traite en continu jusqu'à queue vide.
    Streaming,
    /// Requiert allers-retours avec un acteur.
    Interactive,
    /// Simule sans écrire.
    DryRun,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobScope
// ─────────────────────────────────────────────────────────────────────────────

/// Scope d'un job — sur quoi s'applique le travail.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum JobScope {
    /// Tout le vault.
    VaultWide,
    /// Un locus spécifique (répertoire vault).
    Locus(String),
    /// Un ensemble de notes ciblées.
    Notes(Vec<Ulid>),
    /// Une session agent (contexte isolé).
    Session(Ulid),
}

// ─────────────────────────────────────────────────────────────────────────────
// JobPriority
// ─────────────────────────────────────────────────────────────────────────────

/// Priorité d'un job dans la queue (v65).
///
/// Mapping par défaut :
/// - `Agent`  → `High`    (agent actif en conversation → réponse attendue)
/// - `Human`  → `High`    (action humaine explicite → réponse attendue)
/// - `Api`    → `Normal`  (appel machine → latence acceptable)
/// - `System` → `Low`     (tâche de fond cron → ne bloque pas les agents)
///
/// Câblé dans `GradatumQueue.dequeue()` via `ORDER BY priority DESC`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum JobPriority {
    /// Agent actif + Human — réponse attendue.
    High,
    /// Api — latence acceptable (défaut).
    #[default]
    Normal,
    /// System cron — tâche de fond, ne bloque pas les agents.
    Low,
    /// Schedulé dans le futur (Consolidate trimestriel).
    Deferred,
}

impl JobPriority {
    /// Valeur SQL pour `ORDER BY priority DESC` (High=3 passe avant Low=0).
    #[must_use]
    pub fn as_u8(&self) -> u8 {
        match self {
            Self::High => 3,
            Self::Normal => 2,
            Self::Low => 1,
            Self::Deferred => 0,
        }
    }

    /// Priorité par défaut selon la classe du job.
    #[must_use]
    pub fn default_for(class: &JobClass) -> Self {
        match class {
            JobClass::Agent => Self::High,
            JobClass::Human => Self::High,
            JobClass::Api => Self::Normal,
            JobClass::System => Self::Low,
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// JobScheduling — quand s'exécute le job
// ─────────────────────────────────────────────────────────────────────────────

/// Contraintes de scheduling d'un job.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobScheduling {
    /// Source de déclenchement.
    pub trigger: TriggerSource,
    /// Date/heure de scheduling (UTC).
    pub scheduled_at: DateTime<Utc>,
    /// Chaînage déclaratif — `[]` = immédiat · `[x]` = chaîne · `[x,y]` = DAG.
    ///
    /// Sémantique : "déclenche-moi quand ces jobs sont terminés".
    /// Plus robuste que `not_before: DateTime` (fragile, dépend des durées).
    pub await_jobs: Vec<JobTrigger>,
    /// Deadline pour les jobs `Interactive` — timeout.
    pub deadline: Option<DateTime<Utc>>,
    /// Expression cron (ex : `"0 2 * * *"`).
    pub cron_expr: Option<String>,
}

/// Condition de déclenchement en cascade.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobTrigger {
    /// Identifiant du job attendu.
    pub job_id: Ulid,
    /// Condition de déclenchement.
    pub condition: TriggerCondition,
}

/// Condition sur l'état terminal d'un job attendu.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum TriggerCondition {
    /// Uniquement si `Done` (succès).
    OnDone,
    /// `Done | Failed | DLQ` — quoi qu'il arrive.
    OnAnyTerminal,
    /// Uniquement si `Failed` (alerting).
    OnFailed,
}

/// Source de déclenchement d'un job.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum TriggerSource {
    /// `[[worker.schedules]]` — tokio-cron-scheduler.
    Cron,
    /// `[[pipelines]]` step — pipeline_executor.
    Pipeline,
    /// `await_jobs` → `on_job_complete()` → `set_pending()`.
    Cascade,
    /// `WriteHook` ou `QaEvent` interceptor.
    OnEvent,
    /// `POST /api/v1/jobs/trigger` · admin CLI · `invoke_agent()`.
    Demand,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobLifecycle — où en est le job
// ─────────────────────────────────────────────────────────────────────────────

/// État courant du cycle de vie d'un job.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobLifecycle {
    /// Statut courant.
    pub status: JobStatus,
    /// Timestamp de création (UTC).
    pub created_at: DateTime<Utc>,
    /// Timestamp de démarrage (UTC) — `None` si pas encore démarré.
    pub started_at: Option<DateTime<Utc>>,
    /// Timestamp de fin (UTC) — `None` si pas encore terminé.
    pub completed_at: Option<DateTime<Utc>>,
    /// Expiration du lease SQLite — anti-doublon.
    pub lease_until: Option<DateTime<Utc>>,
    /// Résultat du job — `None` si pas encore terminé.
    pub result: Option<JobResult>,
}

/// Statut d'un job dans son cycle de vie.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum JobStatus {
    /// Dans la queue, prêt à démarrer.
    Pending,
    /// Lease active — en cours d'exécution.
    Running,
    /// `await_jobs` non satisfaits.
    Waiting,
    /// Succès.
    Done,
    /// Erreur, retry possible.
    Failed,
    /// Dead-letter — `max_retries` atteint.
    DLQ,
    /// Deadline dépassée ou orphelin.
    Cancelled,
    /// F-41 — Conflit optimistic-lock : l'écriture a été refusée parce que le
    /// `expected_sha256` fourni ne correspond pas au hash courant de la note.
    /// État terminal sans retry (la note n'a PAS été modifiée).
    /// Lire `lifecycle.result.result_note_md` pour obtenir le `current_sha256`
    /// encodé en JSON (`{ "current_sha256": "hex...", "attempted_sha256": "hex..." }`).
    Conflict,
}

/// Résultat d'un job terminé.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobResult {
    /// `true` si le job s'est terminé avec succès.
    pub success: bool,
    /// Durée d'exécution en millisecondes.
    pub duration_ms: u32,
    /// Coût LLM en USD — `None` si pas de LLM impliqué.
    pub cost_usd: Option<f32>,
    /// Note Gradatum résultat — point d'entrée unique pour l'agent (v57).
    ///
    /// `vault_read(result_note)` → frontmatter + chemins + wikilinks vers notes produites.
    /// Présent si `success=true`. Note d'erreur si `DLQ`.
    pub result_note: Option<Ulid>,
    /// F-41 — Payload JSON du conflit optimistic-lock (présent si `JobStatus::Conflict`).
    ///
    /// Contient les champs `current_sha256` (hash courant) et `attempted_sha256` (hash tenté).
    /// Permet au client poll de récupérer le hash courant pour résoudre le conflit.
    ///
    /// Exemple de payload :
    /// ```json
    /// { "current_sha256": "a3f1...", "attempted_sha256": "b2e0...", "timestamp_ms": 1234567890 }
    /// ```
    ///
    /// `None` pour tous les autres statuts.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub conflict_payload: Option<serde_json::Value>,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobWorkspace — workspace physique OpenDAL
// ─────────────────────────────────────────────────────────────────────────────

/// Workspace physique d'un job — structure OpenDAL (v57).
///
/// Tout passe par OpenDAL — même API quel que soit le backend (fs/s3/gcs).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobWorkspace {
    /// Chemin d'entrée — ex : `"worker/2026-05-20/01J-XYZ/input/"`.
    pub input: String,
    /// Chemin de sortie — ex : `"worker/2026-05-20/01J-XYZ/output/"`.
    pub output: String,
    /// Chemin de métadonnées — ex : `"worker/2026-05-20/01J-XYZ/meta/"`.
    pub meta: String,
}

impl JobWorkspace {
    /// Construit le workspace depuis un [`JobRecord`].
    ///
    /// Format : `worker/{YYYY-MM-DD}/{job_id}/{input|output|meta}/`
    #[must_use]
    pub fn from_job(job: &JobRecord) -> Self {
        let date = job.lifecycle.created_at.format("%Y-%m-%d").to_string();
        let base = format!("worker/{}/{}", date, job.id);
        Self {
            input: format!("{}/input/", base),
            output: format!("{}/output/", base),
            meta: format!("{}/meta/", base),
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// JobProgress — progress d'un job en cours
// ─────────────────────────────────────────────────────────────────────────────

/// Progress d'un job en cours (v58).
///
/// Stocké dans SQLite périodiquement.
/// `GET /api/v1/jobs/:id/status` → `{ status: "running", progress: { current: 47, total: 200 } }`
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobProgress {
    /// Éléments traités.
    pub current: u32,
    /// Éléments total (si connu).
    pub total: u32,
    /// Description de l'étape courante.
    pub step: String,
    /// Estimation du temps restant en secondes.
    pub eta_secs: Option<u32>,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobOutputFile + JobOutput
// ─────────────────────────────────────────────────────────────────────────────

/// Fichier produit par un job — stocké via OpenDAL dans `output/`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobOutputFile {
    /// Nom du fichier (ex : `"export.csv"` | `"report.pdf"` | `"chart.png"`).
    pub name: String,
    /// MIME type (ex : `"text/csv"` | `"application/pdf"` | `"image/png"`).
    pub mime_type: String,
    /// Taille en bytes.
    pub size: u64,
    /// TTL en jours — `None` = défaut du locus (`worker/`=30j, `exports/`=90j).
    pub ttl_days: Option<u32>,
}

/// Sorties complètes produites par un job (v57).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobOutput {
    /// Notes Markdown créées dans le vault.
    pub notes_created: Vec<Ulid>,
    /// Notes modifiées (Validate/Heal).
    pub notes_modified: Vec<Ulid>,
    /// Binaires/CSV/images dans `output/`.
    pub files: Vec<JobOutputFile>,
    /// Contenu Markdown de la note résultat.
    ///
    /// Écrit dans `output/result.md`, copié dans `vault work/jobs/` pour `vault_read()`.
    pub result_note_md: String,
}

impl JobOutput {
    /// Retourner si `JobMode::DryRun` — aucune écriture effectuée.
    #[must_use]
    pub fn dry_run(would_affect: usize, description: &str) -> Self {
        Self {
            notes_created: vec![],
            notes_modified: vec![],
            files: vec![],
            result_note_md: format!(
                "## DRY-RUN — {description}\n\n\
                 **Simulation uniquement — aucune écriture effectuée.**\n\n\
                 Notes qui auraient été affectées : {would_affect}\n",
            ),
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// JobRetry — comment le job récupère
// ─────────────────────────────────────────────────────────────────────────────

/// Politique de retry d'un job.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobRetry {
    /// Tentatives effectuées.
    pub count: u32,
    /// Maximum de tentatives — `0` = pas de retry.
    pub max: u32,
    /// Stratégie de backoff.
    pub backoff: RetryBackoff,
    /// Dernière erreur enregistrée.
    pub last_error: Option<String>,
    /// Historique complet des erreurs.
    pub errors: Vec<JobError>,
}

impl Default for JobRetry {
    fn default() -> Self {
        Self {
            count: 0,
            max: 3,
            backoff: RetryBackoff::Exponential { base: 5, max: 120 },
            last_error: None,
            errors: vec![],
        }
    }
}

/// Erreur individuelle enregistrée lors d'une tentative.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobError {
    /// Timestamp de l'erreur (UTC).
    pub at: DateTime<Utc>,
    /// Message d'erreur.
    pub message: String,
    /// Numéro de la tentative.
    pub attempt: u32,
}

/// Stratégie de backoff entre les tentatives.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum RetryBackoff {
    /// N secondes fixes entre chaque tentative.
    Fixed(u64),
    /// Backoff exponentiel `base → 2×base → ... → max` secondes.
    Exponential {
        /// Délai de base en secondes.
        base: u64,
        /// Délai maximal en secondes.
        max: u64,
    },
}

impl RetryBackoff {
    /// Calcule la durée d'attente pour la tentative `attempt` (0-indexé).
    ///
    /// Pour `Fixed(n)` : toujours `n` secondes.
    /// Pour `Exponential { base, max }` : `min(base * 2^attempt, max)` secondes.
    #[must_use]
    pub fn duration_for(&self, attempt: u32) -> Duration {
        match self {
            Self::Fixed(secs) => Duration::from_secs(*secs),
            Self::Exponential { base, max } => {
                let secs = base.saturating_mul(1_u64 << attempt.min(62));
                Duration::from_secs(secs.min(*max))
            }
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// JobLineage — d'où vient le job
// ─────────────────────────────────────────────────────────────────────────────

/// Traçabilité de l'émetteur et du contexte déclencheur d'un job.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobLineage {
    /// `agent_id` | `user_id` | `cron_id` — `None` si non tracé.
    pub triggered_by: Option<String>,
    /// Job parent si job enfant (cascade, agent spawn).
    pub parent_job: Option<Ulid>,
    /// Pipeline si step d'un `[[pipelines]]`.
    pub pipeline_id: Option<Ulid>,
    /// Nom du step dans le pipeline.
    pub pipeline_step: Option<String>,
    /// Jobs créés par ce job (cascade sortante).
    pub children: Vec<Ulid>,
    /// Coût LLM cumulé en USD.
    pub cost_usd: Option<f32>,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobRecord — enveloppe complète 5 blocs
// ─────────────────────────────────────────────────────────────────────────────

/// Enveloppe complète d'un job structurée en 5 blocs orthogonaux.
///
/// `JobRecord` est le type canonique L0 circulant dans toute la couche job.
/// Sérialisé en JSON par le `QueueStore` pour persistance en SQLite.
///
/// # Les 5 blocs
///
/// 1. [`JobSpec`] — CE QUE fait le job
/// 2. [`JobScheduling`] — QUAND il s'exécute
/// 3. [`JobLifecycle`] — OÙ il en est
/// 4. [`JobRetry`] — COMMENT il récupère
/// 5. [`JobLineage`] — D'OÙ il vient / liens
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobRecord {
    /// Identifiant unique du job (ULID monotone, ordre FIFO implicite).
    pub id: Ulid,
    /// Bloc 1 — CE QUE fait le job.
    pub spec: JobSpec,
    /// Bloc 2 — QUAND il s'exécute.
    pub scheduling: JobScheduling,
    /// Bloc 3 — OÙ il en est.
    pub lifecycle: JobLifecycle,
    /// Bloc 4 — COMMENT il récupère.
    pub retry: JobRetry,
    /// Bloc 5 — D'OÙ il vient / liens.
    pub lineage: JobLineage,
}

// ─────────────────────────────────────────────────────────────────────────────
// JobFilter — introspection F-16
// ─────────────────────────────────────────────────────────────────────────────

/// Filtre pour [`QueueStore::list`].
///
/// Le champ `cursor` permet la pagination cursor-based (F-16).
/// `cursor` est le dernier `id` ULID retourné — la requête suivante retourne les jobs
/// avec `id > cursor` (ULID est monotone, donc équivaut à un ordre temporel).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobFilter {
    /// Filtrer par classe de job.
    pub class: Option<JobClass>,
    /// Filtrer par statut.
    pub status: Option<JobStatus>,
    /// Filtrer par kind (nom du variant `Job`).
    pub kind: Option<String>,
    /// Filtrer les jobs créés après cette date.
    pub created_after: Option<DateTime<Utc>>,
    /// Nombre maximum de résultats (défaut : 50, max : 500).
    pub limit: usize,
    /// Cursor de pagination — dernier `id` ULID retourné (exclusif).
    ///
    /// `None` = début de la liste. `Some(ulid)` = jobs après ce ULID.
    /// Utiliser `next_cursor` de la réponse API précédente.
    pub cursor: Option<Ulid>,
}

impl Default for JobFilter {
    fn default() -> Self {
        Self {
            class: None,
            status: None,
            kind: None,
            created_after: None,
            limit: 50,
            cursor: None,
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// QueueEvent — événements publiés par le backend
// ─────────────────────────────────────────────────────────────────────────────

/// Événements publiés par le `QueueStore` via broadcast.
///
/// Consommés par :
/// - SSE endpoint `GET /api/v1/jobs/events`
/// - Cascade engine (`find_awaiting` + `set_pending`)
/// - Dashboard monitoring temps réel
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum QueueEvent {
    /// Nouveau job inséré — `Pending` ou `Waiting`.
    JobInserted(Ulid),
    /// Job terminé — `Done` ou `DLQ`.
    JobCompleted(Ulid, JobStatus, JobResult),
    /// Job échoué — `Failed` + numéro de tentative.
    JobFailed(Ulid, u32),
    /// Job passé `Waiting → Pending` (cascade satisfaite).
    JobReady(Ulid),
    /// Job annulé — deadline ou orphelin.
    JobCancelled(Ulid),
}

// ─────────────────────────────────────────────────────────────────────────────
// GradatumJob — payload Apalis
// ─────────────────────────────────────────────────────────────────────────────

/// Payload Apalis wrappant un [`JobRecord`].
///
/// Sérialisé en JSON dans la colonne `job` de la table Apalis.
/// Le champ `priority` duplique `spec.priority.as_u8()` pour permettre
/// un `ORDER BY priority DESC` sans désérialisation du payload.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GradatumJob {
    /// Enveloppe complète du job.
    pub record: JobRecord,
    /// Valeur de priorité dénormalisée pour le tri SQL (0-3).
    pub priority: u8,
}

// ─────────────────────────────────────────────────────────────────────────────
// DryRunAware trait
// ─────────────────────────────────────────────────────────────────────────────

/// Trait pour les jobs et handlers supportant le mode `DryRun` (v58).
///
/// Règle v62 : UN SEUL mécanisme, [`JobMode::DryRun`] dans [`JobSpec`].
/// Les `Source` structs ne portent PAS de champ `dry_run` sauf exceptions
/// légitimes (`MigrateSource.dry_run`, `IngestSource.dry_run`) pour les
/// opérations irréversibles nécessitant une validation humaine en premier.
///
/// Dans TOUS les handlers, la vérification est la première instruction :
///
/// ```rust,ignore
/// if job.spec.mode == JobMode::DryRun {
///     let count = ctx.vault.count(&src.scopes).await?;
///     return Ok(JobOutput::dry_run(count, "description"));
/// }
/// ```
pub trait DryRunAware {
    /// Retourne `true` si ce job est en mode DryRun.
    fn is_dry_run(&self) -> bool;

    /// Nombre de notes qui seraient affectées (estimation).
    ///
    /// Retourne `0` par défaut — surchargé par les implémentations qui peuvent
    /// calculer cette valeur sans effets de bord.
    fn notes_would_affect(&self) -> usize {
        0
    }
}

impl DryRunAware for JobRecord {
    fn is_dry_run(&self) -> bool {
        self.spec.mode == JobMode::DryRun
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// JobSource trait — factorisation v63
// ─────────────────────────────────────────────────────────────────────────────

/// Trait commun aux Source structs des variants `Job`.
///
/// Factorisation v63 — champs communs à 11 Source structs.
/// Rust ne supporte pas l'héritage de struct — trait préféré à embed.
pub trait JobSource {
    /// Scopes vault sur lesquels s'applique le job.
    fn scopes(&self) -> &[VaultScope];

    /// `true` si le job est en mode simulation (sans écriture).
    fn dry_run(&self) -> bool;

    /// Fenêtre temporelle optionnelle (notes créées/modifiées dans cette durée).
    fn window(&self) -> Option<Duration> {
        None
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// QueueStore trait — L0
// ─────────────────────────────────────────────────────────────────────────────

/// Trait de stockage de la queue de jobs — L0 `gradatum-core`.
///
/// Implémentations :
/// - `SqliteQueueStore` dans `gradatum-db-sqlite` (défaut embedded)
/// - `LibsqlQueueStore` dans `gradatum-db-sqlite` (remote opt-in F-25)
///
/// # Erreurs
///
/// Toutes les méthodes retournent `Result<_, QueueError>`.
/// Les implémentations ne doivent pas paniquer — propager les erreurs via `?`.
#[async_trait::async_trait]
pub trait QueueStore: Send + Sync {
    // ── Opérations de base ────────────────────────────────────────────────

    /// Insère un nouveau job dans la queue — retourne son `Ulid`.
    async fn enqueue(&self, job: JobRecord) -> Result<Ulid, QueueError>;

    /// Extrait le prochain job prêt à exécuter (lease atomique).
    ///
    /// Retourne `None` si la queue est vide ou si aucun job n'est prêt.
    async fn dequeue(&self) -> Result<Option<JobRecord>, QueueError>;

    /// Extrait le prochain job prêt à exécuter, filtré par `kind` (lease atomique).
    ///
    /// Garantit qu'un worker `curate` ne reçoit jamais un job `Embed` ou `ReIndex`,
    /// éliminant la race condition de routing (bug DLQ `UnexpectedVariant`).
    ///
    /// # Implémentation par défaut
    ///
    /// Fallback non filtré — les implémentations qui supportent le filtrage natif SQL
    /// (ex. `SqliteQueueStore`) doivent surcharger cette méthode avec `WHERE kind = ?`
    /// pour exploiter l'index `idx_jobs_status_kind`.
    ///
    /// # Paramètre
    ///
    /// `kind` : nom du variant `Job` tel que retourné par [`job_kind_str`] —
    /// ex. `"Curate"`, `"Embed"`, `"ReIndex"`.
    async fn dequeue_by_kind(&self, _kind: &str) -> Result<Option<JobRecord>, QueueError> {
        self.dequeue().await
    }

    /// Récupère un job par identifiant — `None` si inexistant.
    async fn get(&self, id: Ulid) -> Result<Option<JobRecord>, QueueError>;

    /// Marque un job comme `Done` avec son résultat.
    async fn complete(&self, id: Ulid, result: JobResult) -> Result<(), QueueError>;

    /// Marque un job comme `Failed` (retry possible selon policy).
    async fn fail(&self, id: Ulid, err: &str, attempt: u32) -> Result<(), QueueError>;

    /// Annule un job (`Cancelled`).
    async fn cancel(&self, id: Ulid) -> Result<(), QueueError>;

    /// Envoie un job en dead-letter (`DLQ`) — max retries atteint.
    async fn fail_dlq(&self, id: Ulid, err: &str) -> Result<(), QueueError>;

    // ── Cascade — chaînage await_jobs ────────────────────────────────────

    /// Trouve les jobs en `Waiting` dont `await_jobs` contient `job_id`.
    async fn find_awaiting(&self, job_id: Ulid) -> Result<Vec<JobRecord>, QueueError>;

    /// Passe un job de `Waiting` à `Pending`.
    async fn set_pending(&self, id: Ulid) -> Result<(), QueueError>;

    // ── Sweep périodique (30s) ────────────────────────────────────────────

    /// Récupère les jobs dont le lease a expiré → remet en `Pending`.
    async fn recover_stale_leases(&self, ttl: Duration) -> Result<Vec<Ulid>, QueueError>;

    /// Annule les jobs dont la deadline est dépassée.
    async fn cancel_expired_deadlines(&self, now: DateTime<Utc>) -> Result<Vec<Ulid>, QueueError>;

    /// Promeut les jobs schedulés en retry dont `scheduled_at <= now` → `Pending`.
    ///
    /// Garde v67 : si `retry.count >= retry.max` → `fail_dlq` au lieu de re-Pending.
    /// Évite la boucle infinie (`Failed → schedule → Failed → ...`).
    async fn promote_retries(&self, now: DateTime<Utc>) -> Result<Vec<Ulid>, QueueError>;

    /// Schedule un job en retry à `at` (transition `Failed → Waiting`).
    async fn schedule_retry(&self, id: Ulid, at: DateTime<Utc>) -> Result<(), QueueError>;

    // ── Introspection F-16 ────────────────────────────────────────────────

    /// Liste les jobs selon un filtre.
    async fn list(&self, filter: JobFilter) -> Result<Vec<JobRecord>, QueueError>;

    // ── Événements ────────────────────────────────────────────────────────

    /// Souscrit au broadcast des [`QueueEvent`].
    ///
    /// Chaque appel retourne un nouveau `Receiver` indépendant.
    /// Les événements sont émis sans garantie de livraison si le consommateur
    /// est trop lent (channel broadcast avec capacité fixe).
    fn subscribe(&self) -> Receiver<QueueEvent>;

    /// F-41 — Marque un job en état terminal `Conflict` (optimistic-lock).
    ///
    /// La note n'a PAS été écrite. Le `result_note_md` contient le JSON du conflit
    /// (`WriteConflictDto`) pour permettre au client de récupérer le `current_sha256`.
    ///
    /// Distinct de `fail()` (qui peut déclencher des retries) et de `complete()`
    /// (qui indique un succès). `Conflict` est terminal sans retry.
    ///
    /// # Implémentation par défaut
    ///
    /// Délègue à `complete()` avec `success: false`, puis corrige le statut
    /// dans le payload JSON (contournement : `complete()` met `Done` en colonne status,
    /// mais le `lifecycle.status` dans le payload JSON est le champ lu par le client poll).
    ///
    /// Les implémentations qui ont accès à la DB peuvent surcharger pour écrire
    /// directement `status = 'Conflict'` dans la colonne SQL.
    async fn mark_conflict(
        &self,
        id: Ulid,
        result_note_md: String,
        duration_ms: u32,
    ) -> Result<(), QueueError> {
        // Implémentation par défaut : utilise complete() avec success=false,
        // puis corrige le lifecycle.status dans le payload via un get+patch+re-save.
        // Les implémentations concrètes (SqliteQueueStore) surchargent cette méthode
        // pour écrire directement le bon statut SQL.
        let result = JobResult {
            success: false,
            duration_ms,
            cost_usd: None,
            result_note: None,
            conflict_payload: serde_json::from_str(&result_note_md).ok(),
        };
        // Appel complet() avec le résultat — le lifecycle.status payload sera Done,
        // mais l'implémentation concrète le corrige dans sa surcharge.
        // L'implémentation par défaut ne peut pas corriger le status SQL sans accès à la DB.
        self.complete(id, result).await
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// QueueError — erreurs L0 (sans dépendances externes)
// ─────────────────────────────────────────────────────────────────────────────

/// Erreurs du `QueueStore` — sans dépendance vers `sqlx` ou autre driver.
///
/// Les implémentations (`SqliteQueueStore`, etc.) mappent leurs erreurs internes
/// vers ces variants via `map_err()`.
#[derive(Debug, thiserror::Error)]
pub enum QueueError {
    /// Erreur de stockage (driver SQLite, libsql, etc.).
    #[error("erreur de stockage : {0}")]
    Storage(String),

    /// Job introuvable par identifiant.
    #[error("job introuvable : {0}")]
    NotFound(Ulid),

    /// Erreur de sérialisation/désérialisation du payload JSON.
    #[error("erreur de sérialisation : {0}")]
    Serialization(String),

    /// Transition d'état invalide (ex : `Done → Running`).
    #[error("transition d'état invalide : {0}")]
    InvalidTransition(String),

    /// Opération annulée (timeout, shutdown).
    #[error("opération annulée : {0}")]
    Cancelled(String),

    /// Opération non implémentée dans cette version.
    ///
    /// Utilisée à la place de `todo!()` pour signaler proprement une méthode
    /// du trait public dont l'implémentation est différée (ex. DAG F-14).
    /// Ne doit jamais déclencher de panic en production.
    #[error("opération non implémentée : {method}")]
    NotImplemented {
        /// Nom de la méthode non implémentée.
        method: &'static str,
    },
}

// ─────────────────────────────────────────────────────────────────────────────
// Tests unitaires
// ─────────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    fn make_job_record(job: Job, class: JobClass) -> JobRecord {
        let now = Utc::now();
        JobRecord {
            id: Ulid::new(),
            spec: JobSpec {
                kind: job,
                class,
                mode: JobMode::Batch,
                scope: JobScope::VaultWide,
                priority: JobPriority::default_for(&class),
            },
            scheduling: JobScheduling {
                trigger: TriggerSource::Demand,
                scheduled_at: now,
                await_jobs: vec![],
                deadline: None,
                cron_expr: None,
            },
            lifecycle: JobLifecycle {
                status: JobStatus::Pending,
                created_at: now,
                started_at: None,
                completed_at: None,
                lease_until: None,
                result: None,
            },
            retry: JobRetry::default(),
            lineage: JobLineage {
                triggered_by: None,
                parent_job: None,
                pipeline_id: None,
                pipeline_step: None,
                children: vec![],
                cost_usd: None,
            },
        }
    }

    #[test]
    fn job_priority_as_u8_ordering() {
        assert!(JobPriority::High.as_u8() > JobPriority::Normal.as_u8());
        assert!(JobPriority::Normal.as_u8() > JobPriority::Low.as_u8());
        assert!(JobPriority::Low.as_u8() > JobPriority::Deferred.as_u8());
    }

    #[test]
    fn job_priority_default_for_class() {
        assert_eq!(
            JobPriority::default_for(&JobClass::Agent),
            JobPriority::High
        );
        assert_eq!(
            JobPriority::default_for(&JobClass::Human),
            JobPriority::High
        );
        assert_eq!(
            JobPriority::default_for(&JobClass::Api),
            JobPriority::Normal
        );
        assert_eq!(
            JobPriority::default_for(&JobClass::System),
            JobPriority::Low
        );
    }

    #[test]
    fn job_mode_default_is_batch() {
        assert_eq!(JobMode::default(), JobMode::Batch);
    }

    #[test]
    fn job_retry_default_values() {
        let r = JobRetry::default();
        assert_eq!(r.count, 0);
        assert_eq!(r.max, 3);
        assert!(r.errors.is_empty());
    }

    #[test]
    fn retry_backoff_fixed_is_constant() {
        let b = RetryBackoff::Fixed(10);
        assert_eq!(b.duration_for(0), Duration::from_secs(10));
        assert_eq!(b.duration_for(5), Duration::from_secs(10));
    }

    #[test]
    fn retry_backoff_exponential_caps_at_max() {
        let b = RetryBackoff::Exponential { base: 5, max: 120 };
        assert_eq!(b.duration_for(0), Duration::from_secs(5));
        assert_eq!(b.duration_for(1), Duration::from_secs(10));
        assert_eq!(b.duration_for(10), Duration::from_secs(120)); // plafonné
    }

    #[test]
    fn job_record_serialize_roundtrip() {
        let record = make_job_record(
            Job::Embed(EmbedSpec {
                note_id: Ulid::new(),
                tenant_id: "main".to_string(),
                force_regenerate: false,
            }),
            JobClass::Agent,
        );

        let json =
            serde_json::to_string(&record).expect("JobRecord doit être sérialisable en JSON");
        let back: JobRecord =
            serde_json::from_str(&json).expect("JobRecord doit être désérialisable depuis JSON");
        assert_eq!(record.id, back.id);
        assert_eq!(record.spec.priority.as_u8(), back.spec.priority.as_u8());
    }

    #[test]
    fn job_workspace_paths_format() {
        let record = make_job_record(Job::Consolidate, JobClass::System);
        let ws = JobWorkspace::from_job(&record);
        assert!(ws.input.ends_with("/input/"));
        assert!(ws.output.ends_with("/output/"));
        assert!(ws.meta.ends_with("/meta/"));
    }

    #[test]
    fn dry_run_job_record() {
        let record = {
            let now = Utc::now();
            JobRecord {
                id: Ulid::new(),
                spec: JobSpec {
                    kind: Job::Curate(CurateSpec {
                        note_id: Ulid::new(),
                        tenant_id: "main".to_string(),
                        ..Default::default()
                    }),
                    class: JobClass::Agent,
                    mode: JobMode::DryRun,
                    scope: JobScope::VaultWide,
                    priority: JobPriority::High,
                },
                scheduling: JobScheduling {
                    trigger: TriggerSource::Demand,
                    scheduled_at: now,
                    await_jobs: vec![],
                    deadline: None,
                    cron_expr: None,
                },
                lifecycle: JobLifecycle {
                    status: JobStatus::Pending,
                    created_at: now,
                    started_at: None,
                    completed_at: None,
                    lease_until: None,
                    result: None,
                },
                retry: JobRetry::default(),
                lineage: JobLineage {
                    triggered_by: None,
                    parent_job: None,
                    pipeline_id: None,
                    pipeline_step: None,
                    children: vec![],
                    cost_usd: None,
                },
            }
        };
        assert!(record.is_dry_run());
    }

    #[test]
    fn job_output_dry_run_format() {
        let out = JobOutput::dry_run(42, "test curate");
        assert!(out.notes_created.is_empty());
        assert!(out.result_note_md.contains("DRY-RUN"));
        assert!(out.result_note_md.contains("42"));
    }

    #[test]
    fn job_filter_default_limit() {
        let f = JobFilter::default();
        assert_eq!(f.limit, 50);
        assert!(f.class.is_none());
        assert!(f.status.is_none());
    }

    #[test]
    fn gradatum_job_priority_matches_spec() {
        let record = make_job_record(Job::Agent, JobClass::Human);
        let expected_priority = record.spec.priority.as_u8();
        let job = GradatumJob {
            priority: expected_priority,
            record,
        };
        assert_eq!(job.priority, 3); // Human → High → 3
    }

    #[test]
    fn vault_scope_is_alias_of_job_scope() {
        // VaultScope = JobScope — vérification que le type alias compile
        let vs: VaultScope = JobScope::VaultWide;
        let js: JobScope = vs;
        assert!(matches!(js, JobScope::VaultWide));
    }

    #[test]
    fn queue_event_variants_serialize() {
        let id = Ulid::new();
        let ev = QueueEvent::JobInserted(id);
        let json = serde_json::to_string(&ev).expect("QueueEvent doit être sérialisable");
        assert!(json.contains("JobInserted"));
    }

    // ── Tests PurgeSpec + stabilité serde position 5 ─────────────────────────

    /// PurgeSpec par défaut : dry_run=true, grace_days=Some(30), mode=Lifecycle.
    ///
    /// Vérifie les valeurs prudentes par défaut.
    #[test]
    fn purge_spec_default_values() {
        let spec = PurgeSpec::default();
        assert!(spec.dry_run, "dry_run doit être true par défaut");
        assert_eq!(spec.grace_days, Some(30));
        assert_eq!(spec.mode, PurgeMode::Lifecycle);
    }

    /// Job::Purge(PurgeSpec) est sérialisable en JSON et le type discriminant est "Purge".
    ///
    /// Stabilité serde : `#[serde(tag = "type", content = "data")]` encode le variant
    /// par son nom ("Purge") — invariant pour la colonne `kind` de la queue.
    #[test]
    fn purge_job_serializes_with_correct_type_tag() {
        let job = Job::Purge(PurgeSpec::default());
        let json = serde_json::to_string(&job).expect("Job::Purge doit être sérialisable");
        assert!(
            json.contains("\"type\":\"Purge\""),
            "le tag serde doit être 'Purge', obtenu : {json}"
        );
    }

    /// Roundtrip JSON de Job::Purge — désérialisation depuis JSON correcte.
    #[test]
    fn purge_job_json_roundtrip() {
        let original = Job::Purge(PurgeSpec {
            mode: PurgeMode::Lifecycle,
            dry_run: false,
            grace_days: Some(7),
        });
        let json = serde_json::to_string(&original).expect("sérialisation Job::Purge");
        let back: Job = serde_json::from_str(&json).expect("désérialisation Job::Purge");
        assert!(
            matches!(back, Job::Purge(ref s) if !s.dry_run && s.grace_days == Some(7)),
            "roundtrip JSON incorrect : {json}"
        );
    }

    /// job_kind_str retourne "Purge" pour Job::Purge(_).
    #[test]
    fn job_kind_str_purge() {
        let job = Job::Purge(PurgeSpec::default());
        assert_eq!(job_kind_str(&job), "Purge");
    }

    /// PurgeSpec grace_days=None : pas de délai de grâce, dry_run=true par défaut.
    #[test]
    fn purge_spec_no_grace_serializes() {
        let spec = PurgeSpec {
            mode: PurgeMode::Lifecycle,
            dry_run: true,
            grace_days: None,
        };
        let json = serde_json::to_string(&spec).expect("sérialisation PurgeSpec sans grace");
        let back: PurgeSpec = serde_json::from_str(&json).expect("désérialisation PurgeSpec");
        assert!(back.grace_days.is_none());
        assert!(back.dry_run);
    }

    // ── Tests ForgetSpec + stabilité serde position 12 ───────────────────────

    /// ForgetSpec par défaut : dry_run=true, confirm_ulids vide.
    #[test]
    fn forget_spec_default_values() {
        let spec = ForgetSpec::default();
        assert!(spec.dry_run, "dry_run doit être true par défaut");
        assert!(spec.confirm_ulids.is_empty());
        assert!(spec.forgotten_by.is_none());
    }

    /// Job::Forget(ForgetSpec) est sérialisable en JSON et le type discriminant est "Forget".
    ///
    /// Stabilité serde : `#[serde(tag = "type", content = "data")]` encode le variant
    /// par son nom ("Forget") — invariant pour la colonne `kind` de la queue.
    #[test]
    fn forget_job_serializes_with_correct_type_tag() {
        let job = Job::Forget(ForgetSpec::default());
        let json = serde_json::to_string(&job).expect("Job::Forget doit être sérialisable");
        assert!(
            json.contains("\"type\":\"Forget\""),
            "le tag serde doit être 'Forget', obtenu : {json}"
        );
    }

    /// Roundtrip JSON de Job::Forget — désérialisation correcte depuis JSON.
    #[test]
    fn forget_job_json_roundtrip() {
        let original = Job::Forget(ForgetSpec {
            scope: ForgetScope::Topic {
                query: "secret api-key".to_string(),
                vault: None,
                limit: Some(10),
            },
            dry_run: false,
            forgotten_by: Some("operator-1".to_string()),
            confirm_ulids: vec!["01HTEST00000000000000000AB".to_string()],
        });
        let json = serde_json::to_string(&original).expect("sérialisation Job::Forget");
        let back: Job = serde_json::from_str(&json).expect("désérialisation Job::Forget");
        assert!(
            matches!(back, Job::Forget(ref s) if !s.dry_run && s.forgotten_by.as_deref() == Some("operator-1")),
            "roundtrip JSON incorrect : {json}"
        );
    }

    /// job_kind_str retourne "Forget" pour Job::Forget(_).
    #[test]
    fn job_kind_str_forget() {
        let job = Job::Forget(ForgetSpec::default());
        assert_eq!(job_kind_str(&job), "Forget");
    }

    /// ForgetScope::Locus sérialisable roundtrip.
    #[test]
    fn forget_scope_locus_roundtrip() {
        let spec = ForgetSpec {
            scope: ForgetScope::Locus {
                vault: "main".to_string(),
                locus: "inbox/old/".to_string(),
            },
            dry_run: true,
            forgotten_by: None,
            confirm_ulids: vec![],
        };
        let json = serde_json::to_string(&spec).expect("sérialisation ForgetScope::Locus");
        let back: ForgetSpec =
            serde_json::from_str(&json).expect("désérialisation ForgetScope::Locus");
        assert!(
            matches!(back.scope, ForgetScope::Locus { ref locus, .. } if locus == "inbox/old/")
        );
    }

    /// ForgetScope::Agent sérialisable roundtrip avec vaults vide → défaut ["main"] côté handler.
    #[test]
    fn forget_scope_agent_empty_vaults() {
        let spec = ForgetSpec {
            scope: ForgetScope::Agent {
                agent_id: "claude-agent".to_string(),
                vaults: vec![],
            },
            dry_run: true,
            forgotten_by: None,
            confirm_ulids: vec![],
        };
        let json = serde_json::to_string(&spec).expect("sérialisation ForgetScope::Agent");
        let back: ForgetSpec =
            serde_json::from_str(&json).expect("désérialisation ForgetScope::Agent");
        assert!(matches!(back.scope, ForgetScope::Agent { ref vaults, .. } if vaults.is_empty()));
    }
}