supercode-interchange 0.5.104

//! How a board is worked (docs/architecture/orchestrator.md §2.9): the whole dispatch behaviour as data, a
//! statechart in the manner of Amazon States Language and XState. A card is always in one of the workflow's
//! statuses; a status may run an actor for as long as the card is in it (XState's `invoke`, ASL's `Task`); events
//! move cards between statuses through transitions that say who may send them, what must hold, and what happens
//! (Jira's conditions, validators and post functions); the dispatcher's scheduling is data too.
//!
//! Nothing here is a mode or a switch: a behaviour exists because a transition, an action or an expression says
//! so. Names (statuses, events, roles, slots, actions) are open strings; conditions, targets, limits and
//! durations are expressions over the card and the workflow's `params`, evaluated by the board engine. Hermes's
//! dispatcher is one instance of this model, [`hermes_instance`], used by a home that declares none.

use std::collections::BTreeMap;

use schemars::JsonSchema;
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::{Map, Value};

/// An expression over the card, its relations, the event and `params` (a small CEL-like language: literals,
/// `card.*`, `event.*`, `params.*`, comparisons, `&&`/`||`/`!`, `in`, and the engine's functions such as
/// `parents.all(p, …)`). Written as a string; a bare number, boolean or null is the literal it spells.
#[derive(Debug, Clone, PartialEq, Eq, JsonSchema)]
#[schemars(transparent)]
pub struct Expr(pub String);

impl Serialize for Expr {
    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        self.0.serialize(s)
    }
}

impl<'de> Deserialize<'de> for Expr {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(s) => Ok(Self(s)),
            v @ (Value::Number(_) | Value::Bool(_) | Value::Null) => Ok(Self(v.to_string())),
            other => Err(D::Error::custom(format!(
                "an expression is a string or a literal, not {other}"
            ))),
        }
    }
}

/// One step a transition, an entry or an exit takes: a primitive the engine provides, named, with its arguments
/// (`notify: {roles: [creator], template: …}`). Written as a one-key map.
#[derive(Debug, Clone, PartialEq, Eq, JsonSchema)]
pub struct Action {
    /// The primitive (`assign`, `count`, `reset`, `notify`, `comment`, `send_to_actor`, `close_session`, …).
    pub name: String,
    /// Its arguments, as written.
    pub args: Value,
}

impl Serialize for Action {
    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        let mut m = Map::new();
        m.insert(self.name.clone(), self.args.clone());
        Value::Object(m).serialize(s)
    }
}

impl<'de> Deserialize<'de> for Action {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(name) => Ok(Self {
                name,
                args: Value::Null,
            }),
            Value::Object(m) if m.len() == 1 => {
                let (name, args) = m.into_iter().next().unwrap();
                Ok(Self { name, args })
            }
            other => Err(D::Error::custom(format!(
                "an action is a name or a one-key map, not {other}"
            ))),
        }
    }
}

/// A move from the card's status on an event (or on none: `always`, `after`).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Transition {
    /// Source statuses; empty applies from every status.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub from: Vec<String>,
    /// Who may send the event: role names (the workflow's `roles`, and the engine's `platform` and `manager`).
    /// Empty: anyone who may write the card.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub by: Vec<String>,
    /// The transition is taken only when this holds (Jira's condition); the first one that holds is taken.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub guard: Option<Expr>,
    /// Must hold, else the event is refused with the message (Jira's validator).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub validate: Vec<Validation>,
    /// The status the card moves to: a status name, or `{{expr}}`; none stays where it is (runs the actions only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub target: Option<String>,
    /// What happens, in order, after the move (Jira's post functions).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub actions: Vec<Action>,
    /// What a person reads about it (the event's door text, the log).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

/// A validator: the expression must hold, else the event is refused with the message.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Validation {
    /// What must hold.
    pub expr: Expr,
    /// The refusal.
    pub message: String,
}

/// A transition taken once a duration has passed in the status (XState's `after`, ASL's `Wait`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Delayed {
    /// How long, in seconds (an expression).
    pub after: Expr,
    /// The move.
    #[serde(flatten)]
    pub transition: Transition,
}

/// What runs while a card is in a status: an actor of a role's lane in a named session slot of the card.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Run {
    /// The role whose lane (the profile it names) runs it.
    pub role: String,
    /// The card's session slot it runs in: a live session in the slot is kept, a lost one resumed, an empty slot
    /// started fresh. Different slots are different sessions (a reviewer never works in the implementer's).
    pub session: String,
    /// What the actor is told when it starts: a template over the card (`{{card.id}}`, `{{context}}`) and
    /// `{{doors}}`, the events the actor may send in this status, generated from its transitions.
    #[serde(default)]
    pub prompt: String,
    /// Prompt file relative to the orchestration home.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prompt_file: Option<String>,
    /// Skills the actor's session is given.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub skills: Vec<String>,
    /// Limits on the run, each an expression in seconds or a count (`runtime`, `heartbeat`, …); the engine emits
    /// an event when one passes (`timed_out`, `stale`, …).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub limits: BTreeMap<String, Expr>,
}

/// One status a card can be in.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Status {
    /// What `kanban.db`'s `tasks.status` holds for a card here, so Hermes reads the board (Hermes's own nine
    /// statuses store as themselves); the exact name rides beside it where it differs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stored_as: Option<String>,
    /// What a person reads about it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// What runs while a card is here.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run: Option<Run>,
    /// A specification in the run machine's roles, without repeating supervision.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_role: Option<String>,
    /// Status used when a failed or blocked run is later resumed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub resume_as: Option<String>,
    /// Done on entering (after the move's own actions).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub entry: Vec<Action>,
    /// Done on leaving (before the move's own actions): e.g. `close_session: reviewer`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub exit: Vec<Action>,
    /// Events and their transitions, the first whose guard holds taken.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub on: BTreeMap<String, Vec<Transition>>,
    /// Transitions taken as soon as their guard holds (XState's `always`).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub always: Vec<Transition>,
    /// Transitions taken after a time in the status.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub after: Vec<Delayed>,
}

/// A cap on what the dispatcher starts, in the board's one capacity language (docs/adr/0009-board-capacity.md):
/// what it counts, in which scope, among which cards and sessions, at most how many. Every cap applies; a card starts
/// only when each cap that matches it has room.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Cap {
    /// What the cap is called where a card waits on it and in the capacity view.
    pub name: String,
    /// Where one count is kept: one for the whole home, or one per board, machine or profile.
    pub scope: CapScope,
    /// What is counted.
    pub counts: CapCount,
    /// Only what matches counts, and only a card that matches is held (every key that is given must match).
    #[serde(default, rename = "where", skip_serializing_if = "CapFilter::is_empty")]
    pub filter: CapFilter,
    /// What matches this is neither counted nor held, whatever `where` says (a standing service that holds no slot).
    #[serde(default, skip_serializing_if = "CapFilter::is_empty")]
    pub unless: CapFilter,
    /// The most there may be in each count; a max that evaluates to nothing caps nothing.
    pub max: Expr,
    /// Slots of each count held back for the cards this matches while any waits (Hermes's review reservation).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reserve: Option<Reserve>,
}

/// Where a cap keeps one count.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum CapScope {
    /// One count across every board of the home and every machine its cards run on.
    Global,
    /// One count per board.
    Board,
    /// One count per machine a card names.
    Machine,
    /// One count per profile (the lane a card's run is started in).
    Profile,
}

/// What a cap counts.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum CapCount {
    /// Cards with a live run.
    Runs,
    /// Cards, each once whatever its runs and sessions (a cap's `where` names the statuses that hold a slot).
    Cards,
    /// Live sessions the home's cards hold, in every slot (implementer and reviewer), idle or working.
    Sessions,
    /// Those of the sessions that are in a turn now.
    Turns,
    /// Cards started in this tick.
    Starts,
}

/// Which cards and sessions a cap is about: each key given narrows it; a key's names are alternatives.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CapFilter {
    /// The card itself, by id.
    #[serde(default, skip_serializing_if = "Names::is_empty")]
    pub card: Names,
    /// The model a session runs (the card's model, else its profile's).
    #[serde(default, skip_serializing_if = "Names::is_empty")]
    pub model: Names,
    /// The harness a session runs (`claude-code`, `codex`, …).
    #[serde(default, skip_serializing_if = "Names::is_empty")]
    pub harness: Names,
    /// The card's assignee (its profile).
    #[serde(default, skip_serializing_if = "Names::is_empty")]
    pub assignee: Names,
    /// The card's status (for a card being started, the status its start moves it to).
    #[serde(default, skip_serializing_if = "Names::is_empty")]
    pub status: Names,
    /// The machine the card names.
    #[serde(default, skip_serializing_if = "Names::is_empty")]
    pub machine: Names,
    /// The card's board.
    #[serde(default, skip_serializing_if = "Names::is_empty")]
    pub board: Names,
}

impl CapFilter {
    /// Whether it narrows nothing.
    pub fn is_empty(&self) -> bool {
        [
            &self.card,
            &self.model,
            &self.harness,
            &self.assignee,
            &self.status,
            &self.machine,
            &self.board,
        ]
        .iter()
        .all(|n| n.is_empty())
    }
}

/// Names written as one name or a list of them.
#[derive(Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
#[schemars(transparent)]
pub struct Names(pub Vec<String>);

impl Names {
    /// Whether there are none.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }
}

impl Serialize for Names {
    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
        match self.0.as_slice() {
            [one] => one.serialize(s),
            many => many.serialize(s),
        }
    }
}

impl<'de> Deserialize<'de> for Names {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(s) => Ok(Self(vec![s])),
            Value::Array(items) => items
                .into_iter()
                .map(|v| match v {
                    Value::String(s) => Ok(s),
                    other => Err(D::Error::custom(format!("a name is a string, not {other}"))),
                })
                .collect::<Result<_, _>>()
                .map(Self),
            other => Err(D::Error::custom(format!(
                "names are a string or a list of strings, not {other}"
            ))),
        }
    }
}

/// Slots of a cap held for some cards.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Reserve {
    /// The cards the slots are held for.
    #[serde(rename = "for")]
    pub for_cards: CapFilter,
    /// How many.
    pub slots: Expr,
}

/// The dispatcher: when it runs, what it may start, in what order, under which caps.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Dispatch {
    /// Whether the served home dispatches its boards (an expression; Hermes's `dispatch_in_gateway`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub serve: Option<Expr>,
    /// Seconds between ticks.
    pub tick: Expr,
    /// The event the dispatcher sends a card it starts (to cards whose status has a transition for it).
    pub start: String,
    /// Which cards it may start this tick.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub eligible: Option<Expr>,
    /// The order it starts them in: sort keys, `-` before one for descending.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub order: Vec<Expr>,
    /// The caps, in the capacity language.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub capacity: Vec<Cap>,
}

/// The independently supervised run machine. Its events never become card notices.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunMachine {
    /// Run specification selected for a card with an Every interval.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub recurring_role: Option<String>,
    /// Shared supervision limits, overridden by individual role specifications.
    #[serde(default)]
    pub limits: BTreeMap<String, Expr>,
    /// Named run specifications, selected by a card status or a recurring role.
    #[serde(default)]
    pub roles: BTreeMap<String, Run>,
    /// Run states and their entry, exit and event rules.
    #[serde(default)]
    pub states: BTreeMap<String, Status>,
    /// Initial run state.
    #[serde(default)]
    pub initial: String,
    /// Supervision shared by all run states.
    #[serde(default)]
    pub on: BTreeMap<String, Vec<Transition>>,
    /// A run outcome emits this card verb (the sole link between machines).
    #[serde(default)]
    pub outcomes: BTreeMap<String, Vec<Transition>>,
}

/// Ordered lowering rule for Hermes's fixed dispatcher.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct StorageRule {
    pub guard: Expr,
    pub status: String,
}

/// A board's workflow.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Workflow {
    /// The run machine; absent for legacy homes during migration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run: Option<RunMachine>,
    /// Card verbs declared once, with source statuses on each transition.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub verbs: BTreeMap<String, Vec<Transition>>,
    /// Derived card conditions, such as ready.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub derived: BTreeMap<String, Expr>,
    /// Relation policies, interpreted by the engine's relation primitives.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub relations: BTreeMap<String, Value>,
    /// Flag policies, interpreted by the engine's flag primitives.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub flags: BTreeMap<String, Value>,
    /// Ordered Hermes projection and its explicitly accepted losses.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub stored_as: Vec<StorageRule>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub losses: Vec<String>,
    /// What a person reads about it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// Named values the expressions read (`params.failure_limit`); a home's config.yaml `kanban:` keys override
    /// them by name, so Hermes's settings are this workflow's parameters.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub params: Map<String, Value>,
    /// Who acts on a card, each an expression naming a profile (`implementer: card.assignee`) or a person.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub roles: BTreeMap<String, Expr>,
    /// Where a new card starts: the first transition whose guard holds.
    pub initial: Vec<Transition>,
    /// Every status, by name.
    pub statuses: BTreeMap<String, Status>,
    /// Events that apply in every status (a status's own `on` for the same event is tried first).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub on: BTreeMap<String, Vec<Transition>>,
    /// The dispatcher.
    pub dispatch: Dispatch,
    /// Who is told what: for each audience (`creator`, `worker`, `dependency`, `chat`: who a card's subscriptions
    /// are), the event kinds it hears and the template each is told in. A kind not named is not sent.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub notify: BTreeMap<String, BTreeMap<String, String>>,
}

/// Hermes's dispatcher, transcribed as data (`hermes_cli/kanban_db.py`): the workflow a home runs when it
/// declares none.
pub fn hermes_instance() -> Workflow {
    let mut workflow: Workflow =
        serde_yaml::from_str(HERMES_WORKFLOW).expect("the built-in Hermes workflow parses");
    if let Some(run) = &mut workflow.run {
        for (role, prompt) in [
            ("triager", include_str!("prompts/triager.md")),
            ("implementer", include_str!("prompts/implementer.md")),
            ("reviewer", include_str!("prompts/reviewer.md")),
        ] {
            if let Some(spec) = run.roles.get_mut(role) {
                spec.prompt = prompt.to_owned();
            }
        }
    }
    workflow
}

/// The built-in Hermes workflow's source.
pub const HERMES_WORKFLOW: &str = include_str!("hermes.workflow.yaml");

impl Workflow {
    /// Every name a transition targets or a run names must be declared; answers what is not.
    pub fn check(&self) -> Result<(), String> {
        let known = |t: &Option<String>| match t {
            Some(name) if !name.starts_with("{{") && !self.statuses.contains_key(name) => {
                Err(format!("no status {name}"))
            }
            _ => Ok(()),
        };
        let all = |ts: &[Transition]| ts.iter().try_for_each(|t| known(&t.target));
        all(&self.initial)?;
        for ts in self.verbs.values() {
            all(ts)?;
            for t in ts {
                for source in &t.from {
                    if !self.statuses.contains_key(source) {
                        return Err(format!("no source status {source}"));
                    }
                }
            }
        }
        if let Some(run) = &self.run {
            if !run.states.contains_key(&run.initial) {
                return Err(format!("no initial run state {}", run.initial));
            }
            for ts in run.outcomes.values() {
                all(ts)?;
            }
            for ts in run
                .on
                .values()
                .chain(run.states.values().flat_map(|s| s.on.values()))
            {
                for t in ts {
                    if let Some(target) = &t.target {
                        if !target.starts_with("{{") && !run.states.contains_key(target) {
                            return Err(format!("no run state {target}"));
                        }
                    }
                }
            }
            for (name, spec) in &run.roles {
                if !self.roles.contains_key(&spec.role) {
                    return Err(format!("run {name}: no role {}", spec.role));
                }
            }
        }
        for ts in self.on.values() {
            all(ts)?;
        }
        for (name, s) in &self.statuses {
            if let Some(role) = &s.run_role {
                if !self
                    .run
                    .as_ref()
                    .is_some_and(|r| r.roles.contains_key(role))
                {
                    return Err(format!("{name}: no run specification {role}"));
                }
            }
            for ts in s.on.values() {
                all(ts).map_err(|e| format!("{name}: {e}"))?;
            }
            all(&s.always).map_err(|e| format!("{name}: {e}"))?;
            s.after
                .iter()
                .try_for_each(|d| known(&d.transition.target))
                .map_err(|e| format!("{name}: {e}"))?;
            if let Some(run) = &s.run {
                if !self.roles.contains_key(&run.role) {
                    return Err(format!("{name}: its run names no role {}", run.role));
                }
            }
        }
        Ok(())
    }
}