Expand description
The GRAPH ROOT: what a struct whose fields are an application’s nodes expands into.
#[ingraph::graph]
pub struct Media {
videos: Video,
scenes: Scene,
}§The root IS the registry, and that is the whole of the inversion
The reference implementation pairs its walk with a per-entity back-pointer: an entity names the graph it belongs to, and a visitor written for one graph cannot be handed another’s entity. That wall is bought with a bounded slot on every entity’s binding, and it is what a REGISTRY needs — a type has to say which list it is on.
Here the list is written once, by hand, in the field order somebody chose. No node registers itself anywhere, nothing on the entity binding points back, and there is no second list a type could be borrowed from. What this half emits is that list, turned into a walk.
§Three items, and each is INHERENT
type_iter cannot be a trait method, and the reason is the mechanism the walk’s own bound rests
on: an impl may not ADD a where clause to a trait method (E0276), and this walk’s body has one
predicate per field to discharge. So the emission is an inherent impl, which is also what the
ruling asks for — Media::init(db), on the root, with the handle as a parameter.
init and validate ride the SQL family’s gate. Their signatures name the schema lane’s own
types and sqlx’s, so they exist per family rather than per declaration; type_iter names
neither and is emitted unconditionally, which is what keeps the walk the single authority whether
or not a build carries a database.
§The RESOURCES are on the same list, and that is one namespace
A field marked #[ingraph(resource)] is not a node: it is a shared citizen the launch builds
once and hands to whoever demanded it. It rides the SAME field list because the root is the
deployment’s whole catalog — so the two kinds are told apart by the attribute and never by a
second declaration. What that buys is Rust’s own refusal for a collision between them, and one
place to read a deployment’s members off. crate::catalog holds their half: the document block
they are grouped under, and the walk that declares them.
§And the INTERFACES, which are the THIRD tier of that one list
A field marked #[ingraph(interface)] names an interface — a contract over members rather than a
member. It is not a node and it is not a resource: it owns no table for the storage walk to
describe, nothing for the create pass to build, and no options section for a document to fill. So
it is a list of its own (InterfaceMount), read off the same fields, and the three walks a node
joins never see it.
What it DOES join is the root query, under the same #[ingraph(query)] word a node’s membership
is written with — see query for the projection, which is one hop shorter than a
node’s because an interface implements no Transformer.
§And the ORIGINS, which are the FIFTH tier and the only one that is a HEAD
A field marked #[ingraph(origin)] names an #[ingraph::source] declaration — a body that is
STARTED ONCE and runs until it is spent, told to stop or dead, rather than one called per item.
It is not a node: it declares no upstream, owns no table, mints no id and answers no query, so it
joins neither the storage walk nor the root query nor the create pass’s own predicate set.
What it DOES have is one out-edge, and that edge IS its feed — the consumer names the origin by
type in its own subscribe(…), the join finds it among these very fields, and the launch hands
the origin the consumer’s inbox rather than pumping items into it. So the tier’s whole emission
is the options section (presence is enablement, as everywhere) and five lines of the launch. See
OriginMount and crate::launch.
§The OPTIONS SPINE rides along, and it is not an entry
Beside those three the root gets <Root>Options — one section per declared node and one
resources block beside them, which is how a deployment says which of the catalog it launches
and what it builds its shared citizens with. It is a TYPE rather than an entry and it is
written in crate::options, where its own note carries the whole of why: presence is
enablement, the mount name is the document’s key, and the framework reads no file.
§And the TWO WORDS that put a DURABLE thing on the root
retired(<engine>) names where this deployment’s retirees are written down — see
RetiredLedger. It is on the root rather than on a member because a retirement is a fact about
a ROOT KEY: no member’s declaration could carry it, and the ledger is one per deployment. What it
grows is a [retired] section and a RETIRED_ENGINE const on the spine, both in
crate::options.
generations(<engine>) is its sibling and names where this deployment’s current pointers are
written down — see GenerationsSeat. It is on the root for the same reason and a second one: a
run closes over a ROOT KEY, and the pointer table is one per deployment. What it grows is a
[generations] section and a GENERATIONS_ENGINE const, in the same place.
They are the only two entries on a root that name a store, and they are two entries rather than one because a deployment may write either without the other: retirement is a fact about which keys are OUT, and a generation is a fact about which run a key’s closure is READ at.
§And the ENTRY that spends it
<Root>::launch is the fourth item, written in crate::launch: the ruled start-up sequence
walked once — validate, create, wire, ignite — with the node pass emitted in full and the steps
that name types this derive cannot see arriving as parameters. <Root>Nodes rides with it, the
create walk’s product read off the same list of mounts.
§Handles are PARAMETERS
The root owns no context. init and validate take the connection they run on, so a graph is
a description of what exists and never a holder of what it is stored in — the injection seam, and
the reason neither emitted entry has a receiver.
§The ROOT QUERY, folded from the members that have one
<Root>Query is the fifth item, written in query: a MergedObject over the
query UNIT each marked member emits, reached by projection rather than by name. It is the one
emitted item here that is CONDITIONAL on a word — see that module for why membership is read off
this declaration and nowhere else.
§What it does NOT emit, and what that is not a gap
No subscribe audit: what a member subscribes to is written in the member’s own declaration, which this derive cannot see — the three-author wall — so subscribe-completeness is an assembly check and is named as one rather than half-attempted here.
Structs§
- Fused
Member - ONE RETRIEVING MEMBER of a graph root: the field that names it, and its type.
- Generations
Seat - The
generations(<engine>)word a root wrote — which engine its current pointers live on. - Graph
Model - A validated ingraph root, ready to emit.
- Interface
Mount - ONE interface on a graph root: the field that names it, and whether this deployment publishes its root fields.
- Origin
Mount - ONE ORIGIN on a graph root: the field that names it, and its type.
- Retired
Ledger - The
retired(<engine>)word a root wrote — which engine its retirement rows live on.