onepipeline 0.27.0

//! The failure modes the contract names, and the process exit codes it assigns.

// llmlint: ignore-file[invalid_states_unrepresentable] the run and node a failure names
// are `String`s because `RunId`/`NodeId` newtypes are public items `docs/contract.md`
// does not name. The engine validates a node reference against the live graph before it
// reaches a failure, so a newtype here would restate that check rather than add one.

use std::path::PathBuf;

/// What can go wrong driving a run.
///
/// The variants are the failures `docs/contract.md` distinguishes, and they
/// carry the exit codes it assigns: [`EXIT_QUEUED`], [`EXIT_REFUSED`], and
/// [`EXIT_NOTHING_DRIVING`].
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// A reply was malformed, or an edit in it was refused at submission, or the
    /// reconciler rejected it. Exits [`EXIT_REFUSED`].
    #[error("refused: {0}")]
    Refused(String),
    /// A reply's edits are accepted and durable but were not reconciled within
    /// the timeout; they remain queued. Exits [`EXIT_QUEUED`].
    ///
    /// **Nothing returns it.** A queued envelope is accepted, so `reply` answers
    /// it with a receipt at [`EXIT_SUCCESS`] rather than with an error — see
    /// divergence 67 — and this variant stays because it is published API.
    #[error("queued: {0}")]
    Queued(String),
    /// Nothing is driving the run: no orchestrator process, no surface, no
    /// ledger write. Exits [`EXIT_NOTHING_DRIVING`].
    #[error("nothing is driving run '{run}'")]
    NothingDriving {
        /// The run id.
        run: String,
    },
    /// External input the schema does not accept — a project, a rules file, a
    /// reply envelope, or a command line naming something that does not exist.
    /// Exits [`EXIT_REFUSED`].
    #[error("invalid: {0}")]
    Invalid(String),
    /// The run does not exist under the runs root. Exits [`EXIT_REFUSED`].
    #[error("no such run '{run}' under {root}")]
    NoSuchRun {
        /// The run id as it was named.
        run: String,
        /// The runs root that was searched.
        root: PathBuf,
    },
    /// The command needs the run's ownership, and this session does not have it.
    /// Exits [`EXIT_REFUSED`].
    #[error("run '{run}' belongs to {owner}, not to this session")]
    NotOwned {
        /// The run id.
        run: String,
        /// How the owner is named to a caller that is not it.
        owner: String,
    },
    /// Another writer holds the run's single-writer lock.
    /// Exits [`EXIT_REFUSED`].
    #[error("run '{run}' is being written by pid {pid} on {host} ({verb})")]
    Locked {
        /// The run id.
        run: String,
        /// The holding process.
        pid: u32,
        /// The host that pid is meaningful on.
        host: String,
        /// What the holder is doing.
        verb: String,
    },
    /// A sibling refused: `onevcs` answering a library call with an error, or
    /// `oneagentgraph`'s CLI refusing or failing to run.
    /// Exits [`EXIT_REFUSED`].
    #[error("{tool}: {message}")]
    Sibling {
        /// Which sibling — `oneagentgraph` or `onevcs`.
        tool: &'static str,
        /// What it said.
        message: String,
    },
    /// The ledger could not be read or written. Exits [`EXIT_REFUSED`].
    #[error("{path}: {source}")]
    Ledger {
        /// The file involved.
        path: PathBuf,
        /// What the filesystem said.
        #[source]
        source: std::io::Error,
    },
}

impl Error {
    /// The process exit code this failure carries.
    pub fn exit_code(&self) -> i32 {
        match self {
            Self::Queued(_) => EXIT_QUEUED,
            Self::NothingDriving { .. } => EXIT_NOTHING_DRIVING,
            _ => EXIT_REFUSED,
        }
    }
}

/// The result of anything in this crate that can fail.
pub type Result<T> = std::result::Result<T, Error>;

// llmlint: ignore-block[cli_output_contract] the two outcomes are told apart on stdout, by
// the receipt's `state`; this status answers acceptance. Divergence 67.
/// The run settled, or the reply's every edit was **accepted** — applied, or
/// durable on the run's command queue and waiting for a driver.
///
/// One status for both, because both are acceptances and the receipt is where
/// which one it was is read. See divergence 67.
pub const EXIT_SUCCESS: i32 = 0;
// llmlint: ignore-end[cli_output_contract]

/// A run's own "unfinished": a graph that is waiting or has a failed node has
/// not settled.
///
/// Neither an error nor completion. It is **not** what `reply` answers for
/// accepted-but-unreconciled edits any more: a queued envelope is accepted, and
/// a caller reading a status has to be able to tell one from a refusal to
/// correct. See divergence 67.
pub const EXIT_QUEUED: i32 = 1;

/// The reply was malformed, or an edit was refused.
pub const EXIT_REFUSED: i32 = 2;

/// Nothing is driving the run — the state to intervene in.
pub const EXIT_NOTHING_DRIVING: i32 = 3;

/// A blocking surface is waiting to be answered.
///
/// `watch`'s own, and the one of its four returns that has no code above it
/// already: `0` is the run settling, [`EXIT_NOTHING_DRIVING`] is the state
/// `adopt` is the way back from, and [`EXIT_QUEUED`] and [`EXIT_REFUSED`] are
/// each spoken for by a different question. A caller branches on this rather
/// than on prose — which is the failure the verb exists to end, a watch that
/// matched a word and called a healthy run dead.
pub const EXIT_SURFACE_WAITING: i32 = 4;

/// A bounded wait elapsed with the run still live.
///
/// Not a failure and not completion: the run is being driven and had not
/// finished when the wait ran out, so the caller resumes from the cursor the
/// watch printed.
pub const EXIT_WATCH_ELAPSED: i32 = 5;

/// At least one run this session owns has nothing watching it.
///
/// `unwatched`'s own answer, and a status rather than the refused
/// [`EXIT_REFUSED`] because a caller has to tell "runs are unwatched" from "this
/// verb could not answer": a hook that read a refusal as an answer would go quiet
/// on exactly the runs it was installed to find, and one that read the answer as a
/// refusal would report every turn as broken.
///
/// **The same number [`EXIT_NODE_SETTLED`] carries, on a different verb**, because
/// every code above [`EXIT_NOTHING_DRIVING`] belongs to one verb's protocol and a
/// caller always knows which verb it ran. Divergence entry 68 is where that is
/// argued and ruled on; it is named on both constants so a reader meets it at
/// whichever one they open.
// llmlint: ignore-block[cli_output_contract] the rule reads these as one global code space, in
// which two outcomes sharing `6` are indistinguishable. They are not one space: every code
// above `3` belongs to a single verb's protocol, `watch` alone spells `4`, `5` and `6`, and
// `watch` already *reuses* `3` from the shared set by the contract owner's own ruling in
// divergence entry 58. A caller runs one verb and branches on its returns, so no caller can
// meet both meanings; giving this verb a seventh number instead would be inventing surface
// the proposal in entry 68 does not carry. Raise it there, not here.
pub const EXIT_RUNS_UNWATCHED: i32 = 6;
// llmlint: ignore-end[cli_output_contract]

/// A node the wait was told to return on settled.
///
/// `watch`'s fifth return, and a status of its own for the same reason the two
/// above it are: a caller that asked to be woken when a node settles has to be
/// able to tell that from the run settling, from a surface waiting and from the
/// wait running out — and the record beside it names *which* node, so neither
/// answer is read out of prose.
///
/// **Shared with [`EXIT_RUNS_UNWATCHED`]**, which is `unwatched`'s answer that an
/// owned run has nothing watching it, on the reading above: a code above
/// [`EXIT_NOTHING_DRIVING`] belongs to one verb's protocol. Divergence entries 58
/// and 68 argue it.
pub const EXIT_NODE_SETTLED: i32 = 6;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn every_failure_carries_the_code_the_contract_assigns() {
        assert_eq!(Error::Queued("edits".into()).exit_code(), EXIT_QUEUED);
        assert_eq!(Error::Refused("bad op".into()).exit_code(), EXIT_REFUSED);
        assert_eq!(Error::Invalid("bad plan".into()).exit_code(), EXIT_REFUSED);
        assert_eq!(
            Error::NothingDriving { run: "r".into() }.exit_code(),
            EXIT_NOTHING_DRIVING
        );
        assert_eq!(
            Error::Sibling {
                tool: "onevcs",
                message: "refused".into()
            }
            .exit_code(),
            EXIT_REFUSED
        );
    }

    #[test]
    fn a_refusal_says_which_run_and_who_owns_it() {
        let error = Error::NotOwned {
            run: "demo".into(),
            owner: "[claude-code:3f9a1c2e]".into(),
        };
        let rendered = error.to_string();
        assert!(rendered.contains("demo"), "{rendered}");
        assert!(rendered.contains("claude-code"), "{rendered}");
    }

    #[test]
    fn a_locked_run_names_the_writer_that_holds_it() {
        let rendered = Error::Locked {
            run: "demo".into(),
            pid: 4321,
            host: "builder".into(),
            verb: "drive".into(),
        }
        .to_string();
        assert!(rendered.contains("4321"), "{rendered}");
        assert!(rendered.contains("builder"), "{rendered}");
        assert!(rendered.contains("drive"), "{rendered}");
    }
}