Expand description
THE TOWER’s model — a question pipeline’s two ends, its steps, and the chain the emission demands between them. The TOWER declaration’s emission: the CONNECTIVITY, which is what makes a question pipeline a compile-time theorem, and the WALK that spends it.
#[ingraph::tower(question(type = "String"))]
pub struct ClipText {
#[ingraph(answer = "Vec<String>")] tokenize: Tokenize,
#[ingraph(answer = "Vec<f32>", async)] encode: ClipTextTower,
}
impl SearchTower for ClipText
where
Tokenize: Serves<String, Vec<String>>, // spanned at `tokenize`
ClipTextTower: AsyncServes<Vec<String>, Vec<f32>>, // spanned at `encode`
{
type Question = String;
type Answer = Vec<f32>;
type Steps = ClipText;
}
pub enum ClipTextError {
Tokenize(<Tokenize as Serves<String, Vec<String>>>::Error),
Encode(<ClipTextTower as AsyncServes<Vec<String>, Vec<f32>>>::Error),
}§THE AMENDMENT: a tower MAY FAN, and every fan folds before the mouth
The tower law gained its amendment with the search pipeline’s design: a tower may contain
FANNING SEGMENTS — expansion × lane routing — and every fan must fold before the tower’s mouth,
so the OUTER contract stays 1 → 1. A segment is opened by a step word (Fan) and closed by
the walk, which is why no word names a fold: where it happens is the law’s, not an author’s.
TODAY’S TOWERS ARE THE DEGENERATE CASE, and that is a fact about this file rather than a
promise: a declaration that writes no fan word has StepModel::fan None at every step,
TowerModel::fanned answers false, and not one line of the emission below asks. The
expansion such a tower gets is the expansion it got before the amendment, token for token.
THE FAN WALK IS HERE — fanned_body below emits the nesting: the widening once, the
crossing per arm, the tail per (arm × lane) cell, and the fold that closes every segment before
the mouth.
AND SO IS THE ASSEMBLY ROW. assembly emits the third impl a declaration states: the GATE
(check, one reading per declared stage word, at that step’s own field) and the UNIFORM RUN
(run, the walk at an arity that does not move with the step count — which is what a search
recipe’s resolver can call and walk itself never was). The gate is EMITTED and not a roster
row, and that is the fan model’s own note read back: what a gate reads is a SEAT, and a seat is a
value no const could carry across the expansion wall. A tower that opened no segment emits NO
gate and inherits the row that refuses nothing.
§⟂ THE STAGE BEFORE THE FAN: a step that ANNOTATES rather than transforms
A third step word opens a third stage, and it is the one whose ends are the SAME TYPE.
annotate(type = "…") says this step hands back the question it was given, one fact richer —
and the fan words downstream READ that fact, which is the whole reason the stage exists and
cannot be an ordinary hop: a step’s answer travels downstream, so a datum a WIDENING needs
cannot arrive as the answer of a step that runs after it.
The seat is StepModel::annotation and the order is Stage::Annotate, which sorts before
both fan words. Three consequences, all emitted below: the chain’s type does NOT move across the
step (flows), the walk asks the QUESTION before it calls the operator (annotating), and the
step is an ordinary Serves/AsyncServes hop at both ends — so a Door onto a graph resident
mounts here with no bridge and no wrapper, which is what the resident-hop stage was named for.
§THE CHAIN IS DERIVED, so there is nothing for two words to disagree about
One question is written — the tower’s — and one answer per step. Every question after the first
IS the answer before it, so an author never states an adjacency and the emission never checks
one: what it does is DEMAND each hop, at the type the chain arrived at. A step that does not
serve the question it is handed is E0277 at the impl, and the predicate carries that step’s
own span, so the caret is on the field an author has to change.
A trivially-false where predicate on a concrete impl is a hard error on stable — that is what
puts the refusal AT THE IMPL rather than leaving an impl that silently never applies — and it is
why the connectivity is stated as a where clause rather than as a helper call beside it.
§THE WORD SELECTS THE FACE, one step at a time
A bare step field binds the blocking Serves; #[ingraph(async)] binds AsyncServes.
This is the fifth position in the framework where a word chooses a face — after
source(async), handler(async), operator(async) and resource(async) — and it is the first
that is PER FIELD rather than per declaration, which is the whole of what makes a MIXED tower
expressible: a blocking tokenizer and an awaited encoder are one chain.
Words CHOOSE; bounds PROVE. Nothing here checks that a step’s body really is awaited — a word
that lied names a face the type does not wear, and the same E0277 on the same step field says
so.
§THE WORDS ARE OMISSIBLE, and what fills their place is a PROJECTION
question(type = "…") and answer = "…" are OVERRIDE words. A step’s type may carry its own
canonical line — impl DefaultServe for Tokenize { type Question = …; type Answer = …; }, the
one-time what this server is usually asked — and a declaration that omits a word gets that
line’s projection wherever the written type would have gone:
#[ingraph::tower] // no question: step0's canonical one
pub struct ClipText {
tokenize: Tokenize, // no answer: `<Tokenize as DefaultServe>::Answer`
#[ingraph(async)] encode: ClipTextTower,
}SELECTION NEVER COMES FROM INFERENCE. DefaultServe takes no parameter, so
<Tokenize as DefaultServe>::Answer is one concrete type rather than a variable the compiler is
asked to solve for. A step with several Serves impls is therefore no more ambiguous omitted
than written — E0283 is not reachable by this road, and a chain still selects among a step’s
impls by the types the declaration arrived at.
THE CHAIN’S where CLAUSE STILL NAMES FACES AND NOTHING ELSE, which is what makes the
canonical line free of a mode. DefaultServe’s own supertrait is the BASE Serve — the seat a
server’s knobs sit in — and never a face, so an awaited-only server can declare its canonical
line and a blocking one can declare the same. Landing that supertrait on a face instead would
make the omissible word available only to steps wearing that face, and the shipped towers in
this tree wear the awaited one: a declaration word available in only one mode is a mode-coupled
authoring surface, which is the thing the word selects the face exists to prevent.
What proves the canonical line HONEST is therefore not the supertrait but this emission’s own
predicate: an omitted answer puts <Ty as DefaultServe>::Answer on both sides of the hop, so
a server whose canonical line names a Q → A it does not serve is E0277 at that step’s field,
exactly where a written word that lied would be.
§THE HEAD’S OWN answer — the one word here that DECIDES NOTHING
#[ingraph::tower(question(type = "String"), answer = "Vec<f32>")]
pub struct ClipText { … } // ← what this tower is FOR, said at its headA tower’s answer is DERIVED — it is the last step’s, and no word can make it anything else. So this word is not a third override beside the two above: what it writes down is an INTENT, and what the emission does with it is demand that the derivation agree. That is a DOUBLE ENTRY, the source layer’s own shape one axis over: the WORD is what a reader, a manifest front end and a search recipe’s author see, the DERIVATION is what the compiler resolves a binding through, and neither can mint the other — so the join is written as one bound, and the two are checked against each other AT THE DECLARATION.
| written | what happens |
|---|---|
answer = "Vec<f32>" over a chain arriving at Vec<f32> | it compiles, and costs nothing |
answer = "Vec<f32>" over a chain arriving at Vec<f64> | E0271 at the WORD |
| no word | nothing is emitted and nothing is checked |
WHAT IT BUYS is WHERE the drift is reported, and never whether it is. A tower whose last step
quietly moved is already caught — by the binding that named the coordinate type it expected —
but that refusal lands in the recipe, at a declaration whose author changed nothing. The pin puts
the same fact at the tower, beside the step that moved. So the two ends of the entry each name
it, which is what tests/tower_pin holds.
The word is OPTIONAL and a tower that omits it pays nothing: no bound, no obligation, and not one token in the expansion. Absence is a road here as it is above — a tower whose answer is whatever its steps arrive at has an intent nobody needed to write down.
It is spent through SearchTower’s own Answer seat rather than through a fresh one, which is
what keeps the pin honest for a chain written EITHER way: a written last answer and a projected
canonical line are the same associated type by the time this bound is resolved, so a wholly
canonical tower states its intent once here and has every step’s line checked against it.
§THE WALK’S FACE IS THE OR OF ITS STEPS’
The mutation node’s assembled face one layer over, verbatim: a tower whose every step is blocking walks in a blocking function, and one awaited step makes the whole walk awaited. The dividend is the same one — a deployment walking a wholly synchronous tower needs no runtime — and so is the reason it is an OR rather than always async: an awaited walk is the more general and the more expensive shape, and paying for it where nothing awaits would be the framework choosing a runtime on an application’s behalf.
| the tower’s steps | the walk |
|---|---|
| every one blocking | fn walk(…) |
| at least one awaited | async fn walk(…) |
§WHY THE STEPS ARE PARAMETERS AND NOT &mut self
type Steps = ClipText says the declaration holds its own servers, and a walk taking &mut self would still compile. The parameters are what make the walk callable by a deployment that
holds its steps ANYWHERE — one behind a door, one in a registry, one on the stack — and a caller
that does hold the struct passes &mut tower.tokenize, &mut tower.encode, which the borrow
checker takes as the disjoint borrows they are.
A step’s PARAMETER is positional and __-pinned, so a field called question or options
cannot shadow the two seats it sits between. walk itself is the declaration’s own name and is
the one thing this expansion adds to a declaring scope: a tower whose author already wrote an
inherent walk is E0592 naming both, which is the honest collision rather than a silent
shadow.
§THE WALK REFUSES IN THE TOWER’S OWN SUM, one arm per step
A chain of N hops has N error types and one Result has one. The answer is a SUM the
declaration mints: <Tower>Error, an arm per step named after the step’s field, each carrying
that step’s own Serves::Error / AsyncServes::Error PROJECTION. The assembled face’s revived
node sum one layer over, at the one grain a tower has.
A projection rather than an erasure is the whole of what this buys. The alternative — one named,
boxed refusal — costs a bound at every step (Error + Send + Sync + 'static) and hands a caller
a dyn it can only print; the sum costs nothing at the declaration and hands a caller back the
very type the step declared, so match on the arm reaches the error’s own data.
What the sum does demand is one thing, at one place: source reaches the cause, so a step’s
error has to BE an error. That demand lands at the step’s own field, per Serves::Error’s own
discipline — bound-free where it is DECLARED, demanded where it is SPENT.
<Tower>Error is minted in the declaring scope, so a tower beside an author’s own <Tower>Error
is E0428 naming both — the honest collision the walk’s own E0592 already takes.
It takes the DECLARATION’s visibility, which makes a step’s own visibility matter in a way the
walk’s parameters did not: an enum arm is exactly as public as its enum, so a pub tower over a
private step is E0446 rather than the private_interfaces lint. That is the projection’s price
and it is the honest one — a tower published across a crate boundary publishes what its steps
refuse with, because that is what its callers have to match on.
§THE TOWER’S OWN OPTIONS — one field per step, and the walk is what projects it
Serve::Options is per SERVER and the walk’s tail seat is per TOWER, so the declaration mints
the object that joins them: <Tower>StepOptions, ONE FIELD PER STEP, each field the projection
Option<<Step as Serve>::Options> of that step’s own seat. A caller names some, all or none of
them in one value, and the walk hands each hop the field belonging to it:
pub struct ClipTextStepOptions {
tokenize: Option<<Tokenize as Serve>::Options>, // named through `with_tokenize`
encode: Option<<ClipTextTower as Serve>::Options>, // and read back through `tokenize()`
}
ClipText::walk(question, &mut tokenize, &mut encode, Some(&options))§THE REQUEST’S OWN OPTIONS — one field per WORD, and the walk never learns it exists
The object above is keyed by STEP and named at INSTALL. Its twin is keyed by the declaration’s own
WORDS and named per REQUEST: <Tower>SearchOptions, whose rows are the FRAMEWORK’s knobs — a walk
budget always, an arm weight where expand was written, a lane emphasis where route(…) named
the shipped weighted fan.
pub struct ClipTextSearchOptions {
budget: Option<SearchBudget>, // ALWAYS — no word writes it and no word takes it away
arm_weight: Option<f64>, // `expand = "Synonyms"` minted this
}BOTH OBJECTS EXIST BECAUSE ONLY ONE OF THEM CAN CROSS. A step’s seat is the application’s own
type and whether it is () is a fact only the compiler holds, so the step-keyed object has no
wire face a macro could mint. Every row of the word-keyed one is a type this framework owns, so
all of it crosses — and the words that key it are HERE, which is why it is minted at the tower
grammar and not at the recipe that publishes it.
The WALK’s arity, parameters and hand-call road are untouched by any of it: the emitted run
composes tier three into a step-keyed package (ArmWeights::over) or into this read’s own minted
router (with_emphasis) and hands the walk exactly what it always took.
None IS A LEVEL, at both grains, and it means the same thing at each: this call named
nothing, under which a step runs at its own floor. A walk handed no options at all hands every
hop None; a walk handed options that named nothing FOR ONE STEP hands that hop None too. The
walk never invents a default on a step author’s behalf, which is why the fields are Option and
not the bare seat — a bare one would need Default, and a projected seat is bound-free by
Serve::Options’ own discipline.
A ()-SEATED STEP STILL HAS A FIELD, and that is the half-row law’s Rust half. Whether
<Step as Serve>::Options is () is a fact only the COMPILER holds — this emission sees a type
and never resolves it — so the struct carries a row for every step and the () ones are
zero-sized and unreadable. What a () seat publishes NOTHING of is the WIRE row, and that law is
already shipped one emitter over: fuse::Row carries a crosses flag, its
Rust struct keeps every field, and its InputObject face publishes only the rows that cross —
a row that does not is simply None on the way in. The division here is the same one, with a
harder half for whoever emits the wire face: fuse’s non-crossing row is a FRAMEWORK type it
recognises by name, and a step’s seat is a projection of somebody else’s, so the decision moves
to where the recipe wires the arm.
A caller who nonetheless names knobs for a ()-seated step is refused at that step’s own
with_…, whose parameter IS the seat: expected (), found Flow, with the caret on the knobs
and note: method defined here on the step’s own field. tests/tower_knobs pins it.
§THE RECORD — DeclaredTower, and why the tokens are restated
A search recipe binding crate::ClipText expands in a pass that has never seen these tokens, so
four facts it needs are STATED rather than guessed: ALL_SYNC (whether the walk it emits is
awaited), StepOptions and SearchOptions (the two objects above, which a recipe could otherwise
only reach by mangling a name), and STEPS (the roster, in declaration order). The two ENDS are
not restated — the record’s supertrait is SearchTower, which already carries them.
Structs§
- Step
Model - ONE STEP of a tower — the field that holds the server, what it answers, and which face it wears.
- Tower
Model - A validated tower declaration, ready to emit.