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
//! ANNOTATION — the stage BEFORE the widening, and the one seat a question opens to it.
//!
//! ```text
//! question ──▶ ⟂ annotate ──▶ the SAME question, enriched ──▶ ② expand ──▶ ④ route ──▶ the tail
//! │ │ │
//! └── writes the annotation ─────────────────────┴── read here ┘
//! ```
//!
//! [`expand`](super::expand) widens a question into several and [`LaneFan`](crate::LaneFan) crosses
//! one into probes. This module is what happens BEFORE either: a question may be ANNOTATED — asked at a
//! detector, a classifier or a resident holding a model, and handed back **as itself**, carrying one
//! more fact than it arrived with.
//!
//! # THE STAGE ANNOTATES; IT DOES NOT TRANSFORM
//!
//! Every other step of a tower turns one type into the next, and the chain is what those hops
//! derive. An annotation stage's ends are THE SAME TYPE, and that is not a special case of the chain
//! — it is the whole reason the stage exists. The stages after it READ what it wrote: a widening
//! picks the targets to widen INTO, a crossing picks the lanes to ask, and neither can read a datum
//! that arrives as its own step's ANSWER, because a step's answer goes downstream and never up. A
//! stage that annotates in place is the one shape that reaches both.
//!
//! # FILL-IF-ABSENT, and the operator is NOT CONSULTED for a value the caller supplied
//!
//! A question may arrive with the annotation already aboard — a client that knows its own language
//! says so, and a request is supreme over anything a deployment would have detected. So the walk
//! ASKS THE QUESTION FIRST, through [`AnnotatedQuestion::carried`], and calls the stage's operator
//! only where the answer is [`None`].
//!
//! **Not consulted, rather than consulted and discarded.** The two readings differ by exactly one
//! thing and it is the expensive one: what a resident-mounted stage holds is
//! *query-time compute over an exclusive model* — a detector, a tokenizer, a device context — and
//! spending a forward pass on a value that will be thrown away is a cost the framework would be
//! choosing on an application's behalf. The cheaper reading is also the honest one: *fill if absent*
//! says the stage fills a gap, and there is no gap.
//!
//! # THE ANNOTATION'S TYPE IS THE DECLARATION'S, and this module names none
//!
//! [`AnnotatedQuestion`] is generic over what is carried, so a language tag, a detected script, a
//! classified intent and a tenant identifier are one mechanism. **No language vocabulary enters
//! here**: what a lane is keyed on is [`LanguageTag`](crate::LanguageTag)'s and
//! [`lane_for`](crate::lane_for)'s business one module over, and what a QUESTION carries is the
//! declaring crate's own type — a tower's question is the application's, which is the ruling this
//! framework has kept at every position where a question's shape came up.
/// **A QUESTION THAT CARRIES AN ANNOTATION** — the ⟂ stage's one seat, written at the stage and
/// READ everywhere after it.
///
/// ```
/// use ingraph::AnnotatedQuestion;
///
/// pub struct Ask {
/// text: String,
/// lang: Option<String>,
/// }
///
/// impl AnnotatedQuestion<String> for Ask {
/// fn carried(&self) -> Option<&String> {
/// self.lang.as_ref()
/// }
/// }
///
/// let told = Ask { text: "sunset".to_owned(), lang: Some("ja".to_owned()) };
/// let silent = Ask { text: "sunset".to_owned(), lang: None };
///
/// // What the walk asks before it spends the stage's operator.
/// assert!(told.carried().is_some());
/// assert!(silent.carried().is_none());
/// ```
///
/// # ONE METHOD, because the framework only ever READS
///
/// What WRITES the annotation is the stage's own operator — a [`Serves`](crate::Serves) or
/// [`AsyncServes`](crate::AsyncServes) whose question and answer are both this type — so there is no
/// setter here and there is nothing for one to be. That division is what keeps *perfect adaptation
/// belongs to the arm author* true at this position too: how a question folds a detected tag into
/// itself, which of several seats it fills, and what it recomputes when it does are the question
/// author's, and a framework setter would be the framework guessing all three.
///
/// # A QUESTION MAY CARRY SEVERAL, and that is why the parameter is on the TRAIT
///
/// `impl AnnotatedQuestion<LanguageTag> for Ask` and `impl AnnotatedQuestion<Intent> for Ask` stand
/// side by side, each read by the stage that names its type. An associated type would have closed
/// that to one annotation per question and closed it in the direction this framework never closes:
/// what a product enriches a question with is the product's, and a seat with room for one is a
/// vocabulary with room for whatever the framework happened to imagine.
///
/// # It asks NOTHING of the annotation
///
/// No [`Eq`], no [`Clone`], no [`Debug`]. The framework's whole spend is *is it there* — the
/// borrowed value is for the stages downstream, and what THEY need of it is theirs to demand.