converge_pack/
agent.rs

1// Copyright 2024-2026 Reflective Labs
2
3// SPDX-License-Identifier: MIT
4
5//! The Suggestor trait — the contract all suggestor implementations satisfy.
6//!
7//! # Why this shape?
8//!
9//! Suggestors in Converge are not actors, not services, not workflow steps.
10//! They are pure functions over context: given the current state of shared
11//! context, a suggestor decides whether to act (`accepts`) and what to
12//! contribute (`execute`).
13//!
14//! This design makes suggestors:
15//! - **Deterministic**: same context → same decision.
16//! - **Composable**: suggestors don't know about each other, only about context.
17//! - **Testable**: mock the context, assert the effect.
18//!
19//! # Critical rules
20//!
21//! - `accepts()` must be **pure** — no side effects, no I/O, no mutations.
22//! - `execute()` is **read-only** — it reads context and returns an effect.
23//! - Suggestors **never call other suggestors** — all communication via shared context.
24//! - **Idempotency is context-based** — check for existing contributions in
25//!   context, not internal state. Internal `has_run` flags violate the
26//!   "context is the only shared state" axiom.
27
28use crate::context::{Context, ContextKey};
29use crate::effect::AgentEffect;
30
31/// The core suggestor contract.
32///
33/// Every suggestor in the Converge ecosystem implements this trait — whether
34/// it wraps an LLM, a policy engine, an optimizer, or a simple rule.
35///
36/// The engine calls `accepts()` to determine eligibility, then `execute()`
37/// to collect effects. Effects are merged by the engine in deterministic
38/// order (sorted by suggestor name).
39///
40/// # Thread Safety
41///
42/// Suggestors must be `Send + Sync` because the engine executes eligible
43/// suggestors in parallel (via Rayon). Suggestor state, if any, must be
44/// internally synchronized.
45pub trait Suggestor: Send + Sync {
46    /// Human-readable name, used for ordering, logging, and provenance.
47    ///
48    /// Must be unique within a convergence run. The engine sorts suggestors
49    /// by name to ensure deterministic merge order.
50    fn name(&self) -> &str;
51
52    /// Context keys this suggestor reads from.
53    ///
54    /// The engine uses this to determine when a suggestor becomes eligible:
55    /// a suggestor is a candidate when at least one of its dependency keys
56    /// has been modified since the last cycle.
57    fn dependencies(&self) -> &[ContextKey];
58
59    /// Pure predicate: should this suggestor execute given the current context?
60    ///
61    /// # Contract
62    ///
63    /// - Must be **pure**: no side effects, no I/O, no state mutation.
64    /// - Must be **deterministic**: same context → same answer.
65    /// - Must check **idempotency via context**: look for your own
66    ///   contributions in context (both `Proposals` and target key),
67    ///   not internal flags.
68    fn accepts(&self, ctx: &dyn Context) -> bool;
69
70    /// Produce effects given the current context.
71    ///
72    /// # Contract
73    ///
74    /// - **Read-only**: do not mutate context. Return effects instead.
75    /// - Effects are collected by the engine and merged after all
76    ///   eligible suggestors have executed.
77    /// - For LLM suggestors: emit `ProposedFact` to `ContextKey::Proposals`,
78    ///   not directly to the target key.
79    fn execute(&self, ctx: &dyn Context) -> AgentEffect;
80}
converge_pack/agent.rs

converge_pack/
agent.rs
