converge-core 3.0.3

Converge Agent OS - correctness-first, context-driven multi-agent runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

// Copyright 2024-2026 Reflective Labs
// SPDX-License-Identifier: MIT

//! Truth catalog primitives.
//!
//! Truths describe jobs, policies, and invariants above domain packs.
//! Applications provide the catalog content; the runtime consumes a common
//! shape for intent construction, guardrails, and pack participation.

use serde::{Deserialize, Serialize};

use crate::{Context, Criterion, FactId, TypesIntentConstraint};

/// What class of truth is being described.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum TruthKind {
    /// A job-to-be-done spanning multiple packs.
    Job,
    /// A cross-cutting policy or guardrail.
    Policy,
    /// A module-local or pack-local invariant.
    Invariant,
}

/// Portable truth definition.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TruthDefinition {
    /// Stable truth identifier.
    pub key: String,
    /// Truth class.
    pub kind: TruthKind,
    /// Human-readable summary.
    pub summary: String,
    /// Required or optional success criteria.
    pub success_criteria: Vec<Criterion>,
    /// Hard and soft constraints derived from the truth.
    pub constraints: Vec<TypesIntentConstraint>,
    /// Human approval points that the runtime must respect.
    pub approval_points: Vec<String>,
    /// Which packs should participate when this truth is active.
    pub participating_packs: Vec<String>,
}

/// Machine-evaluable outcome for a single criterion.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum CriterionResult {
    /// The criterion was satisfied, with fact IDs that justify the result.
    Met { evidence: Vec<FactId> },
    /// The criterion is currently blocked on human intervention.
    Blocked {
        /// Why the criterion is blocked.
        reason: String,
        /// Optional approval or workflow reference the host can surface.
        approval_ref: Option<String>,
    },
    /// The criterion was evaluated and is not satisfied.
    Unmet { reason: String },
    /// The runtime could not determine whether the criterion was satisfied.
    Indeterminate,
}

/// Evaluated outcome for a specific criterion.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CriterionOutcome {
    /// The criterion that was evaluated.
    pub criterion: Criterion,
    /// The result of the evaluation.
    pub result: CriterionResult,
}

/// Application-provided boundary for evaluating success criteria.
pub trait CriterionEvaluator: Send + Sync {
    /// Evaluate a criterion against the converged context.
    fn evaluate(&self, criterion: &Criterion, context: &Context) -> CriterionResult;
}

/// Application-provided truth catalog boundary.
pub trait TruthCatalog: Send + Sync {
    /// List all truths known to the application.
    fn list_truths(&self) -> Vec<TruthDefinition>;

    /// Resolve a truth by key.
    fn find_truth(&self, key: &str) -> Option<TruthDefinition> {
        self.list_truths()
            .into_iter()
            .find(|truth| truth.key == key)
    }
}