supercode_interchange/orchestration/
workflow.rs

1//! How a board is worked (docs/architecture/orchestrator.md §2.9): the whole dispatch behaviour as data, a
2//! statechart in the manner of Amazon States Language and XState. A card is always in one of the workflow's
3//! statuses; a status may run an actor for as long as the card is in it (XState's `invoke`, ASL's `Task`); events
4//! move cards between statuses through transitions that say who may send them, what must hold, and what happens
5//! (Jira's conditions, validators and post functions); the dispatcher's scheduling is data too.
6//!
7//! Nothing here is a mode or a switch: a behaviour exists because a transition, an action or an expression says
8//! so. Names (statuses, events, roles, slots, actions) are open strings; conditions, targets, limits and
9//! durations are expressions over the card and the workflow's `params`, evaluated by the board engine. Hermes's
10//! dispatcher is one instance of this model, [`hermes_instance`], used by a home that declares none.
11
12use std::collections::BTreeMap;
13
14use schemars::JsonSchema;
15use serde::de::Error as _;
16use serde::{Deserialize, Deserializer, Serialize, Serializer};
17use serde_json::{Map, Value};
18
19/// An expression over the card, its relations, the event and `params` (a small CEL-like language: literals,
20/// `card.*`, `event.*`, `params.*`, comparisons, `&&`/`||`/`!`, `in`, and the engine's functions such as
21/// `parents.all(p, …)`). Written as a string; a bare number, boolean or null is the literal it spells.
22#[derive(Debug, Clone, PartialEq, Eq, JsonSchema)]
23#[schemars(transparent)]
24pub struct Expr(pub String);
25
26impl Serialize for Expr {
27    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
28        self.0.serialize(s)
29    }
30}
31
32impl<'de> Deserialize<'de> for Expr {
33    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
34        match Value::deserialize(d)? {
35            Value::String(s) => Ok(Self(s)),
36            v @ (Value::Number(_) | Value::Bool(_) | Value::Null) => Ok(Self(v.to_string())),
37            other => Err(D::Error::custom(format!(
38                "an expression is a string or a literal, not {other}"
39            ))),
40        }
41    }
42}
43
44/// One step a transition, an entry or an exit takes: a primitive the engine provides, named, with its arguments
45/// (`notify: {roles: [creator], template: …}`). Written as a one-key map.
46#[derive(Debug, Clone, PartialEq, Eq, JsonSchema)]
47pub struct Action {
48    /// The primitive (`assign`, `count`, `reset`, `notify`, `comment`, `send_to_actor`, `close_session`, …).
49    pub name: String,
50    /// Its arguments, as written.
51    pub args: Value,
52}
53
54impl Serialize for Action {
55    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
56        let mut m = Map::new();
57        m.insert(self.name.clone(), self.args.clone());
58        Value::Object(m).serialize(s)
59    }
60}
61
62impl<'de> Deserialize<'de> for Action {
63    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
64        match Value::deserialize(d)? {
65            Value::String(name) => Ok(Self {
66                name,
67                args: Value::Null,
68            }),
69            Value::Object(m) if m.len() == 1 => {
70                let (name, args) = m.into_iter().next().unwrap();
71                Ok(Self { name, args })
72            }
73            other => Err(D::Error::custom(format!(
74                "an action is a name or a one-key map, not {other}"
75            ))),
76        }
77    }
78}
79
80/// A move from the card's status on an event (or on none: `always`, `after`).
81#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
82pub struct Transition {
83    /// Source statuses; empty applies from every status.
84    #[serde(default, skip_serializing_if = "Vec::is_empty")]
85    pub from: Vec<String>,
86    /// Who may send the event: role names (the workflow's `roles`, and the engine's `platform` and `manager`).
87    /// Empty: anyone who may write the card.
88    #[serde(default, skip_serializing_if = "Vec::is_empty")]
89    pub by: Vec<String>,
90    /// The transition is taken only when this holds (Jira's condition); the first one that holds is taken.
91    #[serde(default, skip_serializing_if = "Option::is_none")]
92    pub guard: Option<Expr>,
93    /// Must hold, else the event is refused with the message (Jira's validator).
94    #[serde(default, skip_serializing_if = "Vec::is_empty")]
95    pub validate: Vec<Validation>,
96    /// The status the card moves to: a status name, or `{{expr}}`; none stays where it is (runs the actions only).
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub target: Option<String>,
99    /// What happens, in order, after the move (Jira's post functions).
100    #[serde(default, skip_serializing_if = "Vec::is_empty")]
101    pub actions: Vec<Action>,
102    /// What a person reads about it (the event's door text, the log).
103    #[serde(default, skip_serializing_if = "Option::is_none")]
104    pub description: Option<String>,
105}
106
107/// A validator: the expression must hold, else the event is refused with the message.
108#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
109pub struct Validation {
110    /// What must hold.
111    pub expr: Expr,
112    /// The refusal.
113    pub message: String,
114}
115
116/// A transition taken once a duration has passed in the status (XState's `after`, ASL's `Wait`).
117#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
118pub struct Delayed {
119    /// How long, in seconds (an expression).
120    pub after: Expr,
121    /// The move.
122    #[serde(flatten)]
123    pub transition: Transition,
124}
125
126/// What runs while a card is in a status: an actor of a role's lane in a named session slot of the card.
127#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
128pub struct Run {
129    /// The role whose lane (the profile it names) runs it.
130    pub role: String,
131    /// The card's session slot it runs in: a live session in the slot is kept, a lost one resumed, an empty slot
132    /// started fresh. Different slots are different sessions (a reviewer never works in the implementer's).
133    pub session: String,
134    /// What the actor is told when it starts: a template over the card (`{{card.id}}`, `{{context}}`) and
135    /// `{{doors}}`, the events the actor may send in this status, generated from its transitions.
136    #[serde(default)]
137    pub prompt: String,
138    /// Prompt file relative to the orchestration home.
139    #[serde(default, skip_serializing_if = "Option::is_none")]
140    pub prompt_file: Option<String>,
141    /// Skills the actor's session is given.
142    #[serde(default, skip_serializing_if = "Vec::is_empty")]
143    pub skills: Vec<String>,
144    /// Limits on the run, each an expression in seconds or a count (`runtime`, `heartbeat`, …); the engine emits
145    /// an event when one passes (`timed_out`, `stale`, …).
146    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
147    pub limits: BTreeMap<String, Expr>,
148}
149
150/// One status a card can be in.
151#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
152pub struct Status {
153    /// What `kanban.db`'s `tasks.status` holds for a card here, so Hermes reads the board (Hermes's own nine
154    /// statuses store as themselves); the exact name rides beside it where it differs.
155    #[serde(default, skip_serializing_if = "Option::is_none")]
156    pub stored_as: Option<String>,
157    /// What a person reads about it.
158    #[serde(default, skip_serializing_if = "Option::is_none")]
159    pub description: Option<String>,
160    /// What runs while a card is here.
161    #[serde(default, skip_serializing_if = "Option::is_none")]
162    pub run: Option<Run>,
163    /// A specification in the run machine's roles, without repeating supervision.
164    #[serde(default, skip_serializing_if = "Option::is_none")]
165    pub run_role: Option<String>,
166    /// Status used when a failed or blocked run is later resumed.
167    #[serde(default, skip_serializing_if = "Option::is_none")]
168    pub resume_as: Option<String>,
169    /// Done on entering (after the move's own actions).
170    #[serde(default, skip_serializing_if = "Vec::is_empty")]
171    pub entry: Vec<Action>,
172    /// Done on leaving (before the move's own actions): e.g. `close_session: reviewer`.
173    #[serde(default, skip_serializing_if = "Vec::is_empty")]
174    pub exit: Vec<Action>,
175    /// Events and their transitions, the first whose guard holds taken.
176    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
177    pub on: BTreeMap<String, Vec<Transition>>,
178    /// Transitions taken as soon as their guard holds (XState's `always`).
179    #[serde(default, skip_serializing_if = "Vec::is_empty")]
180    pub always: Vec<Transition>,
181    /// Transitions taken after a time in the status.
182    #[serde(default, skip_serializing_if = "Vec::is_empty")]
183    pub after: Vec<Delayed>,
184}
185
186/// A cap on what the dispatcher starts, in the board's one capacity language (docs/adr/0009-board-capacity.md):
187/// what it counts, in which scope, among which cards and sessions, at most how many. Every cap applies; a card starts
188/// only when each cap that matches it has room.
189#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
190#[serde(deny_unknown_fields)]
191pub struct Cap {
192    /// What the cap is called where a card waits on it and in the capacity view.
193    pub name: String,
194    /// Where one count is kept: one for the whole home, or one per board, machine or profile.
195    pub scope: CapScope,
196    /// What is counted.
197    pub counts: CapCount,
198    /// Only what matches counts, and only a card that matches is held (every key that is given must match).
199    #[serde(default, rename = "where", skip_serializing_if = "CapFilter::is_empty")]
200    pub filter: CapFilter,
201    /// What matches this is neither counted nor held, whatever `where` says (a standing service that holds no slot).
202    #[serde(default, skip_serializing_if = "CapFilter::is_empty")]
203    pub unless: CapFilter,
204    /// The most there may be in each count; a max that evaluates to nothing caps nothing.
205    pub max: Expr,
206    /// Slots of each count held back for the cards this matches while any waits (Hermes's review reservation).
207    #[serde(default, skip_serializing_if = "Option::is_none")]
208    pub reserve: Option<Reserve>,
209}
210
211/// Where a cap keeps one count.
212#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
213#[serde(rename_all = "snake_case")]
214pub enum CapScope {
215    /// One count across every board of the home and every machine its cards run on.
216    Global,
217    /// One count per board.
218    Board,
219    /// One count per machine a card names.
220    Machine,
221    /// One count per profile (the lane a card's run is started in).
222    Profile,
223}
224
225/// What a cap counts.
226#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
227#[serde(rename_all = "snake_case")]
228pub enum CapCount {
229    /// Cards with a live run.
230    Runs,
231    /// Cards, each once whatever its runs and sessions (a cap's `where` names the statuses that hold a slot).
232    Cards,
233    /// Live sessions the home's cards hold, in every slot (implementer and reviewer), idle or working.
234    Sessions,
235    /// Those of the sessions that are in a turn now.
236    Turns,
237    /// Cards started in this tick.
238    Starts,
239}
240
241/// Which cards and sessions a cap is about: each key given narrows it; a key's names are alternatives.
242#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
243#[serde(deny_unknown_fields)]
244pub struct CapFilter {
245    /// The card itself, by id.
246    #[serde(default, skip_serializing_if = "Names::is_empty")]
247    pub card: Names,
248    /// The model a session runs (the card's model, else its profile's).
249    #[serde(default, skip_serializing_if = "Names::is_empty")]
250    pub model: Names,
251    /// The harness a session runs (`claude-code`, `codex`, …).
252    #[serde(default, skip_serializing_if = "Names::is_empty")]
253    pub harness: Names,
254    /// The card's assignee (its profile).
255    #[serde(default, skip_serializing_if = "Names::is_empty")]
256    pub assignee: Names,
257    /// The card's status (for a card being started, the status its start moves it to).
258    #[serde(default, skip_serializing_if = "Names::is_empty")]
259    pub status: Names,
260    /// The status the board stores for the card (`blocked` for a paused card or one blocked on a message).
261    #[serde(default, skip_serializing_if = "Names::is_empty")]
262    pub stored: Names,
263    /// The machine the card names.
264    #[serde(default, skip_serializing_if = "Names::is_empty")]
265    pub machine: Names,
266    /// The card's board.
267    #[serde(default, skip_serializing_if = "Names::is_empty")]
268    pub board: Names,
269}
270
271impl CapFilter {
272    /// Whether it narrows nothing.
273    pub fn is_empty(&self) -> bool {
274        [
275            &self.card,
276            &self.model,
277            &self.harness,
278            &self.assignee,
279            &self.status,
280            &self.stored,
281            &self.machine,
282            &self.board,
283        ]
284        .iter()
285        .all(|n| n.is_empty())
286    }
287}
288
289/// Names written as one name or a list of them.
290#[derive(Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
291#[schemars(transparent)]
292pub struct Names(pub Vec<String>);
293
294impl Names {
295    /// Whether there are none.
296    pub fn is_empty(&self) -> bool {
297        self.0.is_empty()
298    }
299}
300
301impl Serialize for Names {
302    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
303        match self.0.as_slice() {
304            [one] => one.serialize(s),
305            many => many.serialize(s),
306        }
307    }
308}
309
310impl<'de> Deserialize<'de> for Names {
311    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
312        match Value::deserialize(d)? {
313            Value::String(s) => Ok(Self(vec![s])),
314            Value::Array(items) => items
315                .into_iter()
316                .map(|v| match v {
317                    Value::String(s) => Ok(s),
318                    other => Err(D::Error::custom(format!("a name is a string, not {other}"))),
319                })
320                .collect::<Result<_, _>>()
321                .map(Self),
322            other => Err(D::Error::custom(format!(
323                "names are a string or a list of strings, not {other}"
324            ))),
325        }
326    }
327}
328
329/// Slots of a cap held for some cards.
330#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
331#[serde(deny_unknown_fields)]
332pub struct Reserve {
333    /// The cards the slots are held for.
334    #[serde(rename = "for")]
335    pub for_cards: CapFilter,
336    /// How many.
337    pub slots: Expr,
338}
339
340/// The dispatcher: when it runs, what it may start, in what order, under which caps.
341#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
342#[serde(deny_unknown_fields)]
343pub struct Dispatch {
344    /// Seconds between ticks.
345    pub tick: Expr,
346    /// The event the dispatcher sends a card it starts (to cards whose status has a transition for it).
347    pub start: String,
348    /// Which cards it may start this tick.
349    #[serde(default, skip_serializing_if = "Option::is_none")]
350    pub eligible: Option<Expr>,
351    /// The order it starts them in: sort keys, `-` before one for descending.
352    #[serde(default, skip_serializing_if = "Vec::is_empty")]
353    pub order: Vec<Expr>,
354    /// The caps, in the capacity language.
355    #[serde(default, skip_serializing_if = "Vec::is_empty")]
356    pub capacity: Vec<Cap>,
357}
358
359/// The independently supervised run machine. Its events never become card notices.
360#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
361pub struct RunMachine {
362    /// Run specification selected for a card with an Every interval.
363    #[serde(default, skip_serializing_if = "Option::is_none")]
364    pub recurring_role: Option<String>,
365    /// Shared supervision limits, overridden by individual role specifications.
366    #[serde(default)]
367    pub limits: BTreeMap<String, Expr>,
368    /// Named run specifications, selected by a card status or a recurring role.
369    #[serde(default)]
370    pub roles: BTreeMap<String, Run>,
371    /// Run states and their entry, exit and event rules.
372    #[serde(default)]
373    pub states: BTreeMap<String, Status>,
374    /// Initial run state.
375    #[serde(default)]
376    pub initial: String,
377    /// Supervision shared by all run states.
378    #[serde(default)]
379    pub on: BTreeMap<String, Vec<Transition>>,
380    /// A run outcome emits this card verb (the sole link between machines).
381    #[serde(default)]
382    pub outcomes: BTreeMap<String, Vec<Transition>>,
383}
384
385/// Ordered lowering rule for Hermes's fixed dispatcher.
386#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
387pub struct StorageRule {
388    pub guard: Expr,
389    pub status: String,
390}
391
392/// A board's workflow.
393#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
394pub struct Workflow {
395    /// The run machine; absent for legacy homes during migration.
396    #[serde(default, skip_serializing_if = "Option::is_none")]
397    pub run: Option<RunMachine>,
398    /// Card verbs declared once, with source statuses on each transition.
399    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
400    pub verbs: BTreeMap<String, Vec<Transition>>,
401    /// Derived card conditions, such as ready.
402    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
403    pub derived: BTreeMap<String, Expr>,
404    /// Relation policies, interpreted by the engine's relation primitives.
405    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
406    pub relations: BTreeMap<String, Value>,
407    /// Flag policies, interpreted by the engine's flag primitives.
408    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
409    pub flags: BTreeMap<String, Value>,
410    /// Ordered Hermes projection and its explicitly accepted losses.
411    #[serde(default, skip_serializing_if = "Vec::is_empty")]
412    pub stored_as: Vec<StorageRule>,
413    #[serde(default, skip_serializing_if = "Vec::is_empty")]
414    pub losses: Vec<String>,
415    /// What a person reads about it.
416    #[serde(default, skip_serializing_if = "Option::is_none")]
417    pub description: Option<String>,
418    /// Named values the expressions read (`params.failure_limit`); a home's config.yaml `kanban:` keys override
419    /// them by name, so Hermes's settings are this workflow's parameters.
420    #[serde(default, skip_serializing_if = "Map::is_empty")]
421    pub params: Map<String, Value>,
422    /// Who acts on a card, each an expression naming a profile (`implementer: card.assignee`) or a person.
423    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
424    pub roles: BTreeMap<String, Expr>,
425    /// Where a new card starts: the first transition whose guard holds.
426    pub initial: Vec<Transition>,
427    /// Every status, by name.
428    pub statuses: BTreeMap<String, Status>,
429    /// Events that apply in every status (a status's own `on` for the same event is tried first).
430    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
431    pub on: BTreeMap<String, Vec<Transition>>,
432    /// The dispatcher.
433    pub dispatch: Dispatch,
434    /// Who is told what: for each audience (`creator`, `worker`, `dependency`, `chat`: who a card's subscriptions
435    /// are), the event kinds it hears and the template each is told in. A kind not named is not sent.
436    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
437    pub notify: BTreeMap<String, BTreeMap<String, String>>,
438}
439
440/// Hermes's dispatcher, transcribed as data (`hermes_cli/kanban_db.py`): the workflow a home runs when it
441/// declares none.
442pub fn hermes_instance() -> Workflow {
443    let mut workflow: Workflow =
444        serde_yaml::from_str(HERMES_WORKFLOW).expect("the built-in Hermes workflow parses");
445    if let Some(run) = &mut workflow.run {
446        for (role, prompt) in [
447            ("triager", include_str!("prompts/triager.md")),
448            ("implementer", include_str!("prompts/implementer.md")),
449            ("reviewer", include_str!("prompts/reviewer.md")),
450        ] {
451            if let Some(spec) = run.roles.get_mut(role) {
452                spec.prompt = prompt.to_owned();
453            }
454        }
455    }
456    workflow
457}
458
459/// The built-in Hermes workflow's source.
460pub const HERMES_WORKFLOW: &str = include_str!("hermes.workflow.yaml");
461
462impl Workflow {
463    /// Every name a transition targets or a run names must be declared; answers what is not.
464    pub fn check(&self) -> Result<(), String> {
465        let known = |t: &Option<String>| match t {
466            Some(name) if !name.starts_with("{{") && !self.statuses.contains_key(name) => {
467                Err(format!("no status {name}"))
468            }
469            _ => Ok(()),
470        };
471        let all = |ts: &[Transition]| ts.iter().try_for_each(|t| known(&t.target));
472        all(&self.initial)?;
473        for ts in self.verbs.values() {
474            all(ts)?;
475            for t in ts {
476                for source in &t.from {
477                    if !self.statuses.contains_key(source) {
478                        return Err(format!("no source status {source}"));
479                    }
480                }
481            }
482        }
483        if let Some(run) = &self.run {
484            if !run.states.contains_key(&run.initial) {
485                return Err(format!("no initial run state {}", run.initial));
486            }
487            for ts in run.outcomes.values() {
488                all(ts)?;
489            }
490            for ts in run
491                .on
492                .values()
493                .chain(run.states.values().flat_map(|s| s.on.values()))
494            {
495                for t in ts {
496                    if let Some(target) = &t.target {
497                        if !target.starts_with("{{") && !run.states.contains_key(target) {
498                            return Err(format!("no run state {target}"));
499                        }
500                    }
501                }
502            }
503            for (name, spec) in &run.roles {
504                if !self.roles.contains_key(&spec.role) {
505                    return Err(format!("run {name}: no role {}", spec.role));
506                }
507            }
508        }
509        for ts in self.on.values() {
510            all(ts)?;
511        }
512        for (name, s) in &self.statuses {
513            if let Some(role) = &s.run_role {
514                if !self
515                    .run
516                    .as_ref()
517                    .is_some_and(|r| r.roles.contains_key(role))
518                {
519                    return Err(format!("{name}: no run specification {role}"));
520                }
521            }
522            for ts in s.on.values() {
523                all(ts).map_err(|e| format!("{name}: {e}"))?;
524            }
525            all(&s.always).map_err(|e| format!("{name}: {e}"))?;
526            s.after
527                .iter()
528                .try_for_each(|d| known(&d.transition.target))
529                .map_err(|e| format!("{name}: {e}"))?;
530            if let Some(run) = &s.run {
531                if !self.roles.contains_key(&run.role) {
532                    return Err(format!("{name}: its run names no role {}", run.role));
533                }
534            }
535        }
536        Ok(())
537    }
538}
supercode_interchange/orchestration/workflow.rs

supercode_interchange/orchestration/
workflow.rs
