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
//! **The routing leg's server half** (REMOTE §3, §5, §9 step 7; bl-024b): the
//! four arms that put an invocation into a tool host's mailbox and bring its
//! capture back.
//!
//! One module for both chokepoints' arms, because they are one mechanism read
//! from four sides — two acts ([`dispatch`](super::dispatch::dispatch)'s) and
//! two reads ([`answer`](super::answer::answer)'s) over the one
//! [`Mailbox`](crate::registry::mailbox::Mailbox). Splitting them by
//! mutate/populate would put half of one hand-off in each of two files and
//! leave nowhere to state the invariant that binds them.
//!
//! **The ask never inverts** (REMOTE §3): the server speaks only when spoken
//! to, at both ends. A driver asks it to queue a call and asks again for the
//! capture; a tool host asks for its next work and posts what it got. Nothing
//! here writes down a connection, and nothing here waits on the intake that
//! runs it — [`invoke`] returns the instant the call is queued, because the
//! deposit consumer is one thread for the whole world and a tool takes as long
//! as a tool takes.
//!
//! **Adjudication is untouched and still runs first.** By the time a call
//! reaches [`invoke`] the tool control (§8.6) has already judged it in the
//! driver; this leg is transport, and REMOTE §5 is honest that what happens on
//! the far machine is beyond the adjudicator's reach.
use crate;
use crate;
use Deps;
use Reply;
/// The family's one door: whichever end of the hand-off was asked for.
pub
/// Queue one call for the machine that advertised it, and answer the handle.
///
/// The one thing checked here is REMOTE §5's own staleness correction — *"a
/// client refuses a tool it no longer carries"* — asked where it can still be
/// answered cheaply, against what that client advertises **now**. Presence is
/// deliberately not checked: a tool host holds a connection only while it is
/// waiting, so a presence test would refuse the second call of a busy host
/// (see [`crate::registry::mailbox`]). What makes a vanished client visible is
/// the asker's own deadline.
///
/// **And a connection reaches only a machine it shares a workspace with**
/// (REMOTE §4, §5.7; bl-e0c9). A call addresses a machine and names no
/// workspace, so before this a scoped client could queue work for a box in a
/// workspace it was never registered in. The registrations of the two are both
/// files, so the test is their intersection, and a machine outside it is
/// answered in the staleness sentence — absent-shaped, as §4 requires. An
/// in-world caller is unscoped (§3) and is held to its workspace where it
/// resolves the name: the loaded set, the worktree lane and the `bz` arm each
/// read the calling workspace's own roster.
/// A tool host posts for one invocation — a piece of its output, or the
/// capture that ends it (REMOTE §5.7). The identity that may is the intake's,
/// exactly as it is for an advertisement and for the read below — so an
/// in-world caller is refused in band with a sentence, and a handle addressed
/// to another machine is **absent** (REMOTE §4).
/// **The follow-class read** (REMOTE §3): this client's next work, waited for.
/// It blocks the calling intake for the mailbox's hold — which is a connection
/// thread and never the deposit consumer, because an in-world caller is refused
/// before the wait rather than parked in it.
///
/// **One reader per identity** (REMOTE §5.1, bl-1462): a second read under
/// the same certificate while one is parked here is refused in band — a read
/// never takes the queue from the read that holds it. **An advertisement does**
/// (bl-96e0): the read it ends is answered [`Taken::Superseded`](crate::registry::mailbox::Taken), so the
/// process behind it, if one is still alive, learns it is no longer this
/// machine's reader.
pub
/// The asker's poll: the capture if the far machine has answered, nothing yet
/// if it has not, and the absent sentence for a handle this caller did not
/// post. It never waits — the patience belongs to the caller, who is the only
/// one that knows how long its tool is worth waiting for — **and it is what
/// keeps the run alive** (REMOTE §5.7): every poll stamps the slot at `now`.
/// With `since`, the text from the asker's own offsets rides back as it
/// arrives.
pub
/// The intake's client identity, or the in-band refusal an intake that carries
/// none earns — the [`advertise`](super::dispatch) precedent, and its reason
/// exactly: a caller who typed this at a terminal made a category error worth
/// naming, not an authentication failure worth hiding.