converge_kernel/
lib.rs

1// Copyright 2024-2026 Reflective Labs
2// SPDX-License-Identifier: MIT
3
4//! # Converge Kernel
5//!
6//! This crate is the curated in-process execution API for Converge.
7//! Consumers embed the kernel here; they author packs in `converge-pack`
8//! and use `converge-model` for shared semantic types.
9
10pub mod formation {
11    //! Grouped offering API for self-assembling formations.
12    //!
13    //! The stable pattern is:
14    //! - semantics in `converge-model`
15    //! - authoring in `converge-pack`
16    //! - runnable machinery in `converge-kernel`
17
18    pub use converge_model::formation::{
19        DeliberatedFormationTemplate, FormationCatalog, FormationKind, FormationPlan,
20        FormationRequest, FormationTemplate, FormationTemplateMetadata, FormationTemplateQuery,
21        OpenClawFormationTemplate, ProfileSnapshot, RoleAssignment, ScoredFormationTemplate,
22        ScoringWeights, StaticFormationTemplate, SuggestorCapability, SuggestorProfile,
23        SuggestorRole,
24    };
25    pub use converge_optimization::suggestors::FormationAssemblySuggestor;
26    pub use converge_provider::ProviderSelectionSuggestor;
27    pub use converge_provider_api::{
28        Capability, CapabilityAssignment, CostClass, LatencyClass, ProviderAssignment,
29        ProviderRequest,
30    };
31}
32
33pub use converge_core::gates::hitl::{
34    ContextItem, GateDecision, GateEvent, GateEventKind, GateRequest, GateVerdict, HitlPolicy,
35    TimeoutAction, TimeoutPolicy,
36};
37pub use converge_core::gates::{
38    AuthorityLevel, FlowAction, FlowGateAuthorizer, FlowGateContext, FlowGateInput,
39    FlowGateOutcome, FlowGatePrincipal, FlowGateResource, FlowPhase, StopReason,
40};
41pub use converge_core::recall::{
42    CandidateProvenance, CandidateSourceType, RecallCandidate, RecallPolicy, RecallQuery,
43    RecallUse, RelevanceLevel, recall_from_store,
44};
45pub use converge_core::{
46    ApprovalPointId, BackendId, Budget, BudgetResource, ChainId, ConstraintName, ConstraintValue,
47    ContextState, ConvergeError, ConvergeResult, CorrelationId, Criterion, CriterionEvaluator,
48    CriterionId, CriterionOutcome, CriterionResult, DecisionStep, Engine, EngineHitlPolicy,
49    EventId, EventQuery, ExperienceEvent, ExperienceEventEnvelope, ExperienceEventKind,
50    ExperienceEventObserver, ExperienceRecord, ExperienceStore, ExperienceStoreError,
51    ExperienceStoreResult, HitlPause, IntegrityProof, Invariant, InvariantClass, InvariantResult,
52    LamportClock, MerkleRoot, OverrideTarget, PackId, RunResult, StreamingCallback, SuggestorId,
53    TenantId, TraceLinkId, TruthId, TypesBudgets, TypesIntentId, TypesIntentKind, TypesRootIntent,
54    TypesRunHooks, UserExperienceEvent, UserExperienceEventEnvelope,
55};
56pub use converge_pack::{
57    AgentEffect, Context, ContextKey, Fact, ProposedFact, Suggestor, ValidationError,
58};
59
60#[cfg(test)]
61mod tests {
62    use super::{
63        BudgetResource, StopReason,
64        formation::{
65            Capability, FormationCatalog, FormationRequest, FormationTemplate,
66            FormationTemplateMetadata, ProviderRequest, StaticFormationTemplate, SuggestorRole,
67        },
68    };
69
70    #[test]
71    fn kernel_reexports_runtime_stop_and_budget_types() {
72        let stop = StopReason::converged();
73        assert!(matches!(stop, StopReason::Converged));
74        assert!(matches!(BudgetResource::Tokens, BudgetResource::Tokens));
75    }
76
77    #[test]
78    fn kernel_groups_formation_offering_api() {
79        let formation = FormationRequest {
80            id: "req-1".to_string(),
81            required_roles: vec![SuggestorRole::Analysis],
82            required_capabilities: vec![],
83        };
84        let provider = ProviderRequest {
85            id: "provider-1".to_string(),
86            required_capabilities: vec![Capability::Reasoning],
87            backend_requirements: None,
88        };
89
90        assert_eq!(formation.required_roles, vec![SuggestorRole::Analysis]);
91        assert_eq!(provider.required_capabilities, vec![Capability::Reasoning]);
92    }
93
94    #[test]
95    fn kernel_reexports_template_catalog_surface() {
96        let catalog = FormationCatalog::new().with_template(FormationTemplate::static_template(
97            StaticFormationTemplate::new(FormationTemplateMetadata::new(
98                "analysis-only",
99                "Single-role analysis formation",
100                [SuggestorRole::Analysis],
101            )),
102        ));
103
104        assert_eq!(catalog.len(), 1);
105        assert_eq!(
106            catalog.get("analysis-only").map(FormationTemplate::id),
107            Some("analysis-only")
108        );
109    }
110}
converge_kernel/lib.rs

converge_kernel/
lib.rs
