thrall 0.0.15

thrall: the foot — a tool-execution 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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202

//! One channel: present, wait, hand off, answer — and every sentence that ends
//! it.

use super::super::hold::hold;
use super::{advertised, aside, echo, gesture, ops, receipt, refusal, row, said, set, wired, work};
use serde_json::json;

/// **The whole loop, once around**: present, wait, hand off, answer, present
/// again, wait again. Nothing in it is thrall speaking unprompted, and the
/// order is the evidence.
#[test]
fn the_loop_presents_waits_hands_off_and_answers() {
    let (_scratch, engine, channel) = wired(vec![
        advertised(),
        work(vec![row("i-1", "Bash")]),
        receipt("i-1"),
        advertised(),
        refusal("the engine is going down"),
    ]);
    assert_eq!(
        said(hold(&channel, &set(), echo, &aside(), None)),
        "the engine is going down",
        "the channel ends with the sentence that ended it"
    );
    assert_eq!(
        ops(&engine),
        [
            "advertise",
            "invocations",
            "complete",
            "advertise",
            "invocations"
        ]
    );
    // The presentation is the config's projection: three keys, no argv.
    assert_eq!(
        gesture(&engine, 0)["tools"],
        json!([{"name": "Bash", "description": "run a command in a shell",
                "input_schema": {"type": "object"}}])
    );
    // The completion quotes the handle, and carries what the hand-off was
    // given: the invocation's tool, and this box's whole set.
    assert_eq!(
        gesture(&engine, 2),
        json!({"op": "complete", "invocation": "i-1",
               "capture": {"stdout": "Bash", "stderr": "1 tools", "exit_code": 0}})
    );
}

/// **The advertisement goes first, and a refusal of it ends the channel there.**
/// A foot that could not say what it offers has nothing to wait for.
#[test]
fn a_refused_advertisement_ends_the_channel_before_any_read() {
    let (_scratch, engine, channel) = wired(vec![refusal("this leaf is not registered here")]);
    assert_eq!(
        said(hold(&channel, &set(), echo, &aside(), None)),
        "this leaf is not registered here"
    );
    assert_eq!(ops(&engine), ["advertise"]);
}

/// **An empty answer is ordinary.** The engine holds the read for its own bound
/// and then answers with what it has, which is usually nothing — so a foot
/// waiting for hours is a sequence of answered reads, not a hang.
///
/// It is also the proof that the re-assertion costs an idle foot **nothing**
/// (bl-2d78): no hand-off ends, so no set is presented again, and a foot that
/// is parked the whole time is the case the engine's own guard already covers.
#[test]
fn an_empty_answer_is_waited_through_and_not_an_ending() {
    let (_scratch, engine, channel) = wired(vec![
        advertised(),
        work(vec![]),
        work(vec![]),
        refusal("the engine is going down"),
    ]);
    assert_eq!(
        said(hold(&channel, &set(), echo, &aside(), None)),
        "the engine is going down"
    );
    assert_eq!(
        ops(&engine),
        ["advertise", "invocations", "invocations", "invocations"]
    );
}

/// Two invocations in one answer are run **serially**, in the order they came,
/// each answered before the next begins — which is what makes a busy foot
/// absent at the far end.
#[test]
fn work_in_one_answer_is_run_one_at_a_time_in_order() {
    let (_scratch, engine, channel) = wired(vec![
        advertised(),
        work(vec![row("i-1", "Bash"), row("i-2", "Bash")]),
        receipt("i-1"),
        advertised(),
        receipt("i-2"),
        advertised(),
        refusal("stop"),
    ]);
    assert_eq!(said(hold(&channel, &set(), echo, &aside(), None)), "stop");
    assert_eq!(
        ops(&engine),
        [
            "advertise",
            "invocations",
            "complete",
            "advertise",
            "complete",
            "advertise",
            "invocations"
        ]
    );
    assert_eq!(gesture(&engine, 2)["invocation"], json!("i-1"));
    assert_eq!(gesture(&engine, 4)["invocation"], json!("i-2"));
}

/// **The window a foot opens itself is closed at the end of every hand-off**
/// (bl-2d78, yog bl-1462). The stored set is keyed on this box's identity and
/// any connection bearing the certificate may replace it; the engine refuses a
/// replacement only while this machine holds a parked read, and a foot holds
/// none while it executes. So each hand-off ends by saying the set again — the
/// same set, in the same spelling as the first presentation.
#[test]
fn the_set_is_asserted_again_at_the_end_of_every_hand_off() {
    let (_scratch, engine, channel) = wired(vec![
        advertised(),
        work(vec![row("i-1", "Bash")]),
        receipt("i-1"),
        advertised(),
        refusal("stop"),
    ]);
    assert_eq!(said(hold(&channel, &set(), echo, &aside(), None)), "stop");
    assert_eq!(
        gesture(&engine, 3),
        gesture(&engine, 0),
        "the re-assertion is the presentation, not a second projection"
    );
}

/// **A refused re-assertion ends the channel**, and the engine's sentence is
/// what the supervisor's log carries. The engine declines a set that would
/// replace a *serving* machine's own, so a refusal here means another
/// connection is holding this machine's read under a different set — two
/// processes claiming one name, which is exactly what this foot must not keep
/// serving through. `ending` proves it is not collapsed into the retryable
/// refusal beside it.
#[test]
fn a_refused_re_assertion_ends_the_channel() {
    let refused = "another connection is holding this engine's follow-class read";
    let (_scratch, engine, channel) = wired(vec![
        advertised(),
        work(vec![row("i-1", "Bash")]),
        receipt("i-1"),
        refusal(refused),
    ]);
    assert_eq!(said(hold(&channel, &set(), echo, &aside(), None)), refused);
    assert_eq!(
        ops(&engine),
        ["advertise", "invocations", "complete", "advertise"],
        "it stops at the refusal rather than reading for more work"
    );
}

/// **A refused completion ends the channel.** The two ends disagree about what
/// is in flight, and a foot that kept answering into that would be posting
/// captures nobody is waiting for.
#[test]
fn a_refused_completion_ends_the_channel() {
    let (_scratch, _engine, channel) = wired(vec![
        advertised(),
        work(vec![row("i-1", "Bash")]),
        refusal("no invocation \"i-1\" is in flight"),
    ]);
    assert_eq!(
        said(hold(&channel, &set(), echo, &aside(), None)),
        "no invocation \"i-1\" is in flight"
    );
}

/// An engine that answers the read with something other than this machine's
/// work is a disagreement worth stopping on, and the sentence names what came
/// back.
#[test]
fn an_answer_that_is_not_this_machine_s_work_ends_the_channel() {
    let (_scratch, _engine, channel) = wired(vec![advertised(), advertised()]);
    let said = said(hold(&channel, &set(), echo, &aside(), None));
    assert!(said.contains("not this machine's work"), "{said}");
    assert!(said.contains("Advertised"), "{said}");
}

/// A kind no foot gesture can earn stops the channel rather than being ignored:
/// continuing on an answer to a question nobody asked would be guessing.
#[test]
fn an_answer_no_foot_gesture_can_earn_ends_the_channel() {
    let (_scratch, _engine, channel) =
        wired(vec![json!({"ok": true, "kind": "board", "rows": []})]);
    assert_eq!(
        said(hold(&channel, &set(), echo, &aside(), None)),
        "reply: unusable kind \"board\""
    );
}