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
10mod provider_selection;
11
12pub use provider_selection::{
13    ProviderAssignmentPayload, ProviderRequestPayload, ProviderSelectionSuggestor,
14};
15
16pub mod formation {
17    //! Grouped offering API for self-assembling formations.
18    //!
19    //! The stable pattern is:
20    //! - semantics in `converge-model`
21    //! - authoring in `converge-pack`
22    //! - runnable machinery in `converge-kernel`
23
24    pub use crate::{
25        ProviderAssignmentPayload, ProviderRequestPayload, ProviderSelectionSuggestor,
26    };
27    pub use converge_model::formation::{
28        DeliberatedFormationTemplate, FormationCatalog, FormationKind, FormationPlan,
29        FormationRequest, FormationTemplate, FormationTemplateMetadata, FormationTemplateQuery,
30        OpenClawFormationTemplate, ProfileSnapshot, RoleAssignment, ScoredFormationTemplate,
31        ScoringWeights, StaticFormationTemplate, SuggestorCapability, SuggestorProfile,
32        SuggestorRole,
33    };
34    pub use converge_optimization::suggestors::FormationAssemblySuggestor;
35    pub use converge_provider::{
36        Capability, CapabilityAssignment, CostClass, LatencyClass, ProviderAssignment,
37        ProviderRequest,
38    };
39}
40
41pub mod admission {
42    //! External observation admission API.
43    //!
44    //! Admission stages observations as proposals. It does not construct
45    //! authoritative facts; promotion remains engine-owned.
46
47    pub use converge_model::{
48        AdmissionActor, AdmissionActorKind, AdmissionContent, AdmissionError, AdmissionReceipt,
49        AdmissionRequest, AdmissionSource,
50    };
51
52    use crate::{ContextState, ConvergeError};
53
54    /// Stages an external observation for governed promotion.
55    pub fn admit_observation(
56        context: &mut ContextState,
57        request: AdmissionRequest,
58    ) -> Result<AdmissionReceipt, ConvergeError> {
59        context.submit_observation(request)
60    }
61}
62
63pub use converge_core::gates::hitl::{
64    ContextItem, GateDecision, GateEvent, GateEventKind, GateRequest, GateVerdict, HitlPolicy,
65    TimeoutAction, TimeoutPolicy,
66};
67pub use converge_core::gates::{
68    AuthorityLevel, FlowAction, FlowGateAuthorizer, FlowGateContext, FlowGateInput,
69    FlowGateOutcome, FlowGatePrincipal, FlowGateResource, FlowPhase, StopReason,
70};
71pub use converge_core::recall::{
72    CandidateProvenance, CandidateSourceType, RecallCandidate, RecallPolicy, RecallQuery,
73    RecallUse, RelevanceLevel, recall_from_store,
74};
75pub use converge_core::{
76    AdmissionActor, AdmissionActorKind, AdmissionContent, AdmissionError, AdmissionReceipt,
77    AdmissionRequest, AdmissionSource, ApprovalPointId, BackendId, BoundaryKind, BoundaryTarget,
78    Budget, BudgetResource, ChainId, ConstraintName, ConstraintValue, ContextSnapshot,
79    ContextState, ConvergeError, ConvergeResult, CorrectionTarget, CorrelationId, Criterion,
80    CriterionEvaluator, CriterionId, CriterionOutcome, CriterionResult, DecisionStep, Engine,
81    EngineHitlPolicy, EventId, EventQuery, ExperienceEvent, ExperienceEventEnvelope,
82    ExperienceEventKind, ExperienceEventObserver, ExperienceRecord, ExperienceStore,
83    ExperienceStoreError, ExperienceStoreResult, FactContent, FactContentKind, HitlPause,
84    IntegrityProof, Invariant, InvariantClass, InvariantResult, LamportClock, MerkleRoot,
85    OverrideTarget, PackId, RunResult, StreamingCallback, SuggestorId, TenantId, TraceLinkId,
86    TruthId, TypesBudgets, TypesIntentId, TypesIntentKind, TypesRootIntent, TypesRunHooks,
87    UnitInterval, UserExperienceEvent, UserExperienceEventEnvelope,
88};
89pub use converge_pack::{
90    AgentEffect, ArtifactId, Context, ContextFact, ContextKey, FactPayload, ProposedFact,
91    ProvenanceSource, Suggestor, TextPayload, ValidationError,
92};
93
94// Experience-side surface (artifact lifecycle, replay traces).
95// These let downstream consumers (Organism learning, Helms, etc.) reference
96// governed-artifact and replay vocabulary without importing converge_core.
97pub use converge_core::experience_store::ArtifactKind;
98pub use converge_core::governed_artifact::LifecycleEvent;
99pub use converge_core::kernel_boundary::{LocalReplayTrace, RemoteReplayTrace, ReplayTrace};
100
101#[cfg(test)]
102mod tests {
103    use super::{
104        BudgetResource, ContextKey, ContextState, StopReason,
105        admission::{
106            AdmissionActor, AdmissionActorKind, AdmissionContent, AdmissionRequest,
107            AdmissionSource, admit_observation,
108        },
109        formation::{
110            Capability, FormationCatalog, FormationRequest, FormationTemplate,
111            FormationTemplateMetadata, ProviderRequest, StaticFormationTemplate, SuggestorRole,
112        },
113    };
114
115    #[test]
116    fn kernel_reexports_runtime_stop_and_budget_types() {
117        let stop = StopReason::converged();
118        assert!(matches!(stop, StopReason::Converged));
119        assert!(matches!(BudgetResource::Tokens, BudgetResource::Tokens));
120    }
121
122    #[test]
123    fn kernel_groups_formation_offering_api() {
124        let formation = FormationRequest {
125            id: "req-1".to_string(),
126            required_roles: vec![SuggestorRole::Analysis],
127            required_capabilities: vec![],
128        };
129        let provider = ProviderRequest {
130            id: "provider-1".to_string(),
131            required_capabilities: vec![Capability::Reasoning],
132            backend_requirements: None,
133        };
134
135        assert_eq!(formation.required_roles, vec![SuggestorRole::Analysis]);
136        assert_eq!(provider.required_capabilities, vec![Capability::Reasoning]);
137    }
138
139    #[test]
140    fn kernel_reexports_template_catalog_surface() {
141        let catalog = FormationCatalog::new().with_template(FormationTemplate::static_template(
142            StaticFormationTemplate::new(FormationTemplateMetadata::new(
143                "analysis-only",
144                "Single-role analysis formation",
145                [SuggestorRole::Analysis],
146            )),
147        ));
148
149        assert_eq!(catalog.len(), 1);
150        assert_eq!(
151            catalog.get("analysis-only").map(FormationTemplate::id),
152            Some("analysis-only")
153        );
154    }
155
156    #[test]
157    fn kernel_admission_stages_observation() {
158        let mut context = ContextState::new();
159        let request = AdmissionRequest::new(
160            AdmissionActor::new("organism-runtime", AdmissionActorKind::System).unwrap(),
161            AdmissionSource::new("truth-document").unwrap(),
162            ContextKey::Seeds,
163            "truth-doc-1",
164            AdmissionContent::new(r#"{"claim":"approved source"}"#).unwrap(),
165        )
166        .unwrap();
167
168        let receipt = admit_observation(&mut context, request).unwrap();
169
170        assert!(receipt.staged());
171        assert_eq!(receipt.proposal_id().as_str(), "truth-doc-1");
172    }
173}
converge_kernel/lib.rs

converge_kernel/
lib.rs
