Skip to main content

Module graph

Module graph 

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

FusedMember
ONE RETRIEVING MEMBER of a graph root: the field that names it, and its type.
GenerationsSeat
The generations(<engine>) word a root wrote — which engine its current pointers live on.
GraphModel
A validated ingraph root, ready to emit.
InterfaceMount
ONE interface on a graph root: the field that names it, and whether this deployment publishes its root fields.
OriginMount
ONE ORIGIN on a graph root: the field that names it, and its type.
RetiredLedger
The retired(<engine>) word a root wrote — which engine its retirement rows live on.