lernie 0.1.39

lernie: the operator seat — the window and wire client for a yog server
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! **The rendering**: what a reply looks like to a person (DESIGN §4.36).
//!
//! The boundary is JSON and stays JSON — that is REMOTE §3's whole shape, and
//! `--json` prints it byte for byte. What this module adds is the other half of
//! being a seat: **the part you look at**. A day of CLI use was a day of piping
//! into a JSON formatter, because the machine form was the only form (bl-6ae7);
//! the seat's own siblings set the standard the other way round, `bl list`
//! rendering and `bl list --json` being the machine form.
//!
//! # It is one rendering per reply KIND, never per verb
//!
//! That is the ruling (round-1 triage, ruling 4) and it is also the only shape
//! that stays one implementation. A verb is a serialization of a gesture
//! ([`crate::verbs`], DESIGN §4.10); its ANSWER is a kind of
//! [`crate::reply::Reply`], and several verbs answer with one kind — `attention`
//! and `seen` both answer a queue, `fleet`, `arm`, `disarm` and `disband` all
//! answer whether something stands. A render per verb would be a second table
//! keyed on the wrong fact and it would disagree with itself within a week.
//!
//! # It is a reading, and the frame is always one act away
//!
//! A rendering paints the facts a person scans a listing for, and elides the
//! rest: an entry's `raw` bytes, a preview's third paragraph, a step's whole
//! captured document. That is a deliberate loss and it is safe precisely
//! because it is not the only form — every one of these lines has a `--json`
//! beside it that is the frame exactly as it crossed. What must never happen is
//! the other direction: a rendering that states something the frame does not.
//!
//! # Where it hangs
//!
//! [`said`] is the one place this seat's product is written, so the rendering
//! reaches every surface that prints a reply stream at once — one gesture
//! ([`crate::seat::ask`]), a fan across channels ([`crate::seat::fanned`]) and
//! the composite start's two streams ([`crate::seat::start`]).

use serde_json::Value;

use crate::reply::{Read, read};

/// The receipts and the runs — what an ACT answers with.
mod acts;
/// The per-kind renderings, in the one match that dispatches them.
mod answer;
/// The conversation, as prose: its transcript and its own whole row.
mod chat;
/// The vocabulary every rendering is built from.
mod parts;
/// What a wall's policy is written in: roles, lineages, config, clients.
mod policy;
/// The three reads whose subject is an engine: its words, a search, the trail.
mod reads;
/// The conversation's own records, and the files a wall's policy is in.
mod records;
/// One step, drilled into — its records, its tool calls and its logs.
mod step;
/// The balls, the board, the fleet and what a wall's agents changed.
mod tasks;
/// The roster, the conversation list, the queue, the transcript and the tail.
mod walls;
/// What a wall's agents changed, as a diff rather than a row of counters.
mod work;

/// **Which form a reply stream is printed in.**
///
/// Two, and there will never be a third: one for a person and one for a
/// machine. It is decided by argv alone — nothing about the channel, the
/// gesture or the answer can change it — which is why it is a value
/// [`crate::cli::run`] hands over rather than a field on anything.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Form {
    /// What a person reads. The default, because the default reader is a
    /// person.
    #[default]
    Rendered,
    /// The frames exactly as they crossed, one per line.
    Json,
}

/// **The reply stream as this seat's product** — the one place that shape is
/// written, whichever form it takes.
pub fn said(stream: &[Value], form: Form) -> String {
    stream
        .iter()
        .map(|frame| match form {
            Form::Json => frame.to_string(),
            Form::Rendered => rendered(frame),
        })
        .collect::<Vec<String>>()
        .join("\n")
}

/// One frame, read and rendered. **Read here rather than by the caller**: a
/// rendering is a statement about what a frame turned out to be, and
/// [`crate::reply::read`] is the one thing that can say.
fn rendered(frame: &Value) -> String {
    match read(frame) {
        Read::Answer(reply) => answer::answer(&reply),
        // The engine's own sentence, unadorned. It is the answer to what was
        // asked, so it is printed rather than interpreted — this seat has
        // nothing to add to a wall saying no.
        Read::Refusal(why) => format!("refused: {why}"),
        // A statement about THIS SEAT, and the upgrade prompt (DESIGN §4.9's
        // rung 2). The frame is still on the wire and `--json` still prints it,
        // which is what makes the sentence actionable rather than a dead end.
        Read::Unreadable(why) => {
            format!("this seat cannot read that answer: {why} (`--json` prints the frame)")
        }
    }
}

#[cfg(test)]
mod tests;