yog 0.0.98

yog: the standalone server for litany loops — the world, the balls and the conversations, behind one wire
//! **What the server says when it cannot know whether the box ran it**
//! (REMOTE §5.6, §5.7): the sentences this leg writes into a refusal or into a
//! capture, and the one clause the doubts share.
//!
//! Split out of [`super`] at §12's per-file budget, on the seam the file
//! already had: everything else there is a *shape* — what an invocation is,
//! what a capture is, how each is spelled on the wire — and these are the
//! server's own prose, the only text on this leg a model or an operator reads
//! that no tool produced.
//!
//! **They say one fact and they say it once.** Delivery on the routed leg is
//! at-least-once, so a hand-off that went out and never came back may still
//! have run on the box; the count is the whole of what the server knows, and
//! [`handed_to`] is the clause that states it. What differs between the three
//! is only what happened *around* the count — nothing came back, something
//! came back late, or the handle is gone — so the count has one home and the
//! endings are three.

use super::stream::Offsets;

/// The clause every sentence here opens with: who it went to and how many
/// times. `{client:?}` quotes the identity, which is a certificate CN and can
/// carry anything.
fn handed_to(client: &str, handed: u32) -> String {
    format!("this invocation was handed to {client:?} {handed} times")
}

/// What the count *means*, and what to do about it — the gesture lane's own
/// instruction, said the same way here: the server cannot know what the box
/// did, so the recovery is a read and never a re-send.
const MAY_HAVE_RUN: &str = "each hand-off may have run it";
const READ_FIRST: &str = "read the world before acting again";

/// The one sentence an unheld handle earns, said the same way at both readers.
///
/// **It names three causes and the third is the restart**
/// (REMOTE §5.6, ruling 3). The mailbox is RAM and stays RAM: the durable home
/// of a tool result is litany's step record, reached only through the driver's
/// collect, so a capture nobody had collected when this process died is gone.
/// A driver that outlives the server then polls a handle the new one never
/// minted, and until bl-8016 was told two of the three reasons that could be
/// true. The third carries the gesture lane's own instruction, because the
/// server cannot know whether the box ran it.
pub(super) fn unknown(invocation: &str) -> String {
    format!(
        "no invocation {invocation:?} is in flight; it was answered already, it expired, or \
         this server restarted since it was posted — the box may have run it; read the world \
         before acting again"
    )
}

/// **What an exhausted lease is answered with** (REMOTE §5.6, ruling 2): the
/// sentence of the server's own capture, written at the read that would hand
/// a slot out for a fourth time — non-zero, because it is a failed tool
/// result and the model reads it as one; nothing on stdout, because nothing
/// ran *here*. It names the client, the count and the instruction the gesture
/// lane already gives — a box that dropped three hand-offs of one tool, with
/// its own redial series in between, is a box that tool is killing, and the
/// recovery is a read rather than a re-send.
pub(super) fn in_doubt(client: &str, handed: u32) -> String {
    format!(
        "{} and never answered; {MAY_HAVE_RUN}; {READ_FIRST}",
        handed_to(client, handed)
    )
}

/// What ended a run that had begun to arrive — the three ways the server
/// learns one will not finish (REMOTE §5.7).
pub(super) const ASKED_AGAIN: &str = "the box asked for work again without finishing it";
pub(super) const WENT_QUIET: &str = "the box posted nothing for thirty seconds";
pub(super) const UNHEARD: &str =
    "it was refused a post because nobody had asked for its capture in thirty seconds";

/// **What an acknowledged run is answered with when it will not finish**
/// (REMOTE §5.7): the same doubt, said at once rather than after a second
/// hand-off, and naming how much had arrived — because a reader has already
/// consumed part of this run, and a second spliced behind it would be a
/// capture no run produced.
pub(super) fn unfinished(client: &str, handed: u32, why: &str, arrived: Offsets) -> String {
    format!(
        "{}; {why}, after {} bytes of stdout and {} of stderr had arrived; \
         {MAY_HAVE_RUN}; {READ_FIRST}",
        handed_to(client, handed),
        arrived.stdout,
        arrived.stderr
    )
}

/// **The refusal that is the stop** (REMOTE §5.7): a post for a slot nobody
/// is listening to. The foot ends the child on it and reads on.
pub(super) fn unheard(invocation: &str) -> String {
    format!(
        "nobody has asked for invocation {invocation:?}'s capture in thirty seconds, so \
         nothing is waiting for this run — stop it"
    )
}

/// The refusal an asker's `since` earns when no stream can answer from it.
pub(super) fn outside(invocation: &str) -> String {
    format!(
        "invocation {invocation:?}: `since` names bytes this server cannot answer from — \
         before what an earlier ask acknowledged, past what has arrived, or inside a \
         character; ask from the count of bytes you were answered"
    )
}

/// **The mark a redelivered invocation's capture carries** (REMOTE §5.6 as
/// amended by bl-0655): below the cap, the server says the count *earlier* and
/// without giving up. `None` at one hand-off, which is not a redelivery.
///
/// A foot restarted mid-flight ran one command twice on the box, and the
/// capture the model was handed — `Exit code: 0`, and the command's own output
/// — was indistinguishable from one clean run. The server already held the
/// hand-off count and spent it only on the give-up case; at hand-off two,
/// which is the common case (one restart, one deploy, one blip), it said
/// nothing, so a doubled `apt install` or a doubled migration reported itself
/// as a single one.
///
/// **The mark rides stderr, not a field of its own.** The three facts a
/// capture carries are the whole of what reaches the model — litany renders
/// exit code, stdout and stderr into the `tool_result` envelope and nothing
/// else (its ARCH §3.3) — so a field would be a fact only a decoder could
/// read, on the one lane whose reader is a language model. It goes *first*
/// ([`Run::absorb`](super::slots)), because the bounded projection cuts what
/// a long capture ends with.
///
/// **One hand-off is not a redelivery, and a re-post is not a second run.**
/// The count is the slot's, so this is silent at `handed == 1`; and Ruling 1's
/// held capture is posted on the next dial *before* that channel's first
/// follow-class read, so the slot is still at one when it lands — the case
/// where the box ran it once is the case that says nothing.
pub(super) fn redelivered(client: &str, handed: u32) -> Option<String> {
    (handed >= 2).then(|| {
        format!(
            "{}; {MAY_HAVE_RUN}, so what this capture reports may be the effect of \
             more than one run; {READ_FIRST}",
            handed_to(client, handed)
        )
    })
}