Skip to main content

Module tower

Module tower 

Source
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 head

A 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.

writtenwhat 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 wordnothing 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 stepsthe walk
every one blockingfn walk(…)
at least one awaitedasync 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§

StepModel
ONE STEP of a tower — the field that holds the server, what it answers, and which face it wears.
TowerModel
A validated tower declaration, ready to emit.

Enums§

Fan
ONE FAN SEGMENT — which kind of fan a step opens, and the types the segment is wired with.
Router
WHO CHOOSES THE LANES — the router a route(…) mounted, shipped or the declaring crate’s.
Stage
WHERE A FAN SEGMENT SITS IN THE PIPELINE’S OWN ORDER — the ②-before-④ opinion, as data.