Skip to main content

Module emit

Module emit 

Source
Expand description

Model in, tokens out.

Twenty-three AUTHORISED framework trait implementations, and no other. The rule was none of any kind, because the framework’s trait layer was moving and an expansion that named a half-settled trait would owe every consumer a revision the day it settled. That layer has settled for ToDatabaseComparison, the type-level map from a filter to the comparison it crosses into, so the rule lifted for that item; and the map’s own ITEM BOUND — Comparison: ComplexComparison<Db> — then made the lowering the second, because an expansion that names the map has to keep the promise the map makes. INHERENT impls were never covered by the rule: they bind nothing in the framework and are stable whatever that layer becomes, so new and the accessors are emitted.

Transformer is the third, and it settled differently from the other two: what it binds is entirely the emitter’s OWN output. Its faces are the *Key written here, the *Lineage beside it and the record itself — no consumer type, no backend type, nothing this emission does not also declare or sit on. An expansion naming it therefore owes a revision to nobody the emission was not already going to move.

Record is the fourth and stands on the third’s ground: it is the settled VOCABULARY the entity binding’s row-form member answers, and what an impl of it binds is the <Row>Comparison this emission also declares. It differs in one way that matters — its argument is a CONCRETE backend, the only one the emission names — and that is what makes it the storability audit and what makes it ride a gate. See DatabaseBackend::vocabulary.

Related<Target> and Reference are the fifth and sixth, admitted on the third’s ground and on one more of their own: a relation is declared in TWO derives that cannot see each other, so the pairing is the only way a reverse declaration’s audit can reach the forward one’s fields. What they bind is the emission’s own artifacts and the paths the declaration itself wrote. See [relate].

Identifiable is the seventh and the eighth — the SAME trait twice, because it is admitted on two self types and the allowlist is a (trait, self type) pair rather than a trait. It is Transformer’s supertrait, so an expansion naming the entity binding has to name it or the binding is not well formed, and what it binds is the declared type of the key’s last column: the third’s ground, one member of it. One impl is on the RECORD and one on the *Key — the two types the emission gives that column to. See RecordModel::binding.

KeySegments is the ninth, and it is on the *Key — the second impl that type carries. What it binds is the third’s ground again: the key written here, walked into a sink the framework owns, with nothing named that this emission did not also declare. It is the filesystem blob store’s own key requirement, and it is emitted because the store’s seam says so — that seam KEEPS the full key, since a directory tree nested by lineage is browsable where a flat one is not. The sentence in ingraph’s store::fs promising the derive emits it is what this makes true. See RecordModel::address_segments.

The ORDER is not a tenth impl. It was one — Orderable on the RECORD, with a condition of its own where the nine before it ride whatever condition already emitted the type they bind — and it is retired: the order is a MEMBER of the Record<Db> vocabulary now, so it rides that impl’s condition and a record stored nowhere has neither the row, the comparison nor the order. See DatabaseBackend::vocabulary, which is where all three are bound.

Implements<Interface> is the fourteenth, on the RECORD, admitted on the fifth and sixth’s ground alone: a membership is declared in two derives that cannot see each other, so the record’s implements(…) is the only way an interface’s expansion can know its member agreed. It carries nothing — a relation needs the referring fields crossing that boundary, and a membership needs only the fact — and what it binds is a path the declaration itself wrote. See [relate].

Graphql, GraphqlInput and GraphqlOutput are the eleventh, twelfth and thirteenth, admitted on the third’s ground and on the fifth and sixth’s: the two halves’ impls are on CARRIERS this emission mints, exactly as the pairing’s are on artifacts it mints, and an expansion that writes the face has to write them or the face names types answering nothing. What they bind is the filter, the key output and the order-by this emission also declares. Conditional like the tenth, on the block’s presence. See RecordModel::wire_binding.

The TOPOLOGY family is the fifteenth through nineteenth, and it stands on the third’s ground with one addition of its own: Emits<N> and SoleProduct on the RECORD are how a node states what it puts on an edge, which is the ONE fact a downstream declaration cannot read for itself — the fifth and sixth’s argument seen from the other end of the edge. Products and ProductKind are on the product sum and its vocabulary, and Sink<Out> is on the DOWNSTREAM: all three are types this emission declares, so what they bind is its own output. Conditional on emits naming several, exactly as the tenth is conditional on its block. See [topology].

Describe<Db> is the TWENTY-THIRD, on the RECORD, and it stands on the fourth’s ground with the fourth’s own argument: the SCHEMA a migration creates this record’s storage from, built out of what the row’s SqlQuery binding already publishes — its address and its column shapes — with each field’s StoredAs<Db> word and its nullability beside them. It names the backend CONCRETELY and rides that dialect’s gate for Record<Db>’s reason, and it carries one condition of its own on top of the query face’s: a collection this database keeps in a COLUMN has no word to be declared at, so that database gets no blueprint. See [query], where the roster is.

Declared is the TWENTIETH, on the RECORD, and it is the only one on this list whose reason is a party OUTSIDE the declaration that emits it. What it binds is nothing at all — an effect, a lane, a table of upstreams, an options path and a shelf — but a graph root sees a field’s TYPE and no more, so a node’s own facts have to reach it as an impl or the root’s entry can name none of them. It is the other side of the same wall the fifth and sixth cross, one organ up: those carry a fact between two node declarations, and this carries one from a node to the root that mounts it. See [declared].

The line is not left to memory. tests::the_emission_declares_only_the_authorised_trait_impl reads the emission back and fails on any framework trait impl that is not ToDatabaseComparison<Row, Db> on the record’s own filter, keyed on a row a declared database really stores, ComplexComparison<Db> on a comparison that same model names, Transformer on the record itself, Record<Db> on it keyed on a backend a declared database really is, Related<Target> on the record at a target the model’s own ref names, Reference on an artifact the emitter mints for one of those fields, Identifiable on the record or on the *Key the model names, KeySegments on that same *Key, Graphql on the record, or GraphqlInput/GraphqlOutput on the carrier the emitter mints for each half — self type and argument both checked against the MODEL, so an authorised trait on the wrong type is refused exactly as a fourteenth would be. The walk OPENS the gates first, so wrapping an impl in one is not a way past the rule.

TryFromFilter is the one that stays absent HERE, and the reason is the DIALECT. A record’s comparison is generic in its database and stays that way, so the crossing would need a bound on <F as ToDatabaseComparison<V, Db>>::Comparison that no item bound carries — see DatabaseBackend::comparison_traits for what was measured, and why the LOWERING is reachable where the crossing is not.

An INTERFACE’s expansion writes it, and nothing about the wall moved: an interface’s engine face is per database already — the row equations, SqlInterface and the hydration all name a concrete backend and ride its gate — so its crossing is stated at that backend, where every projection normalises and the bound is not owed. See crate::interface::cross. Whether a RECORD could be given the same treatment is a real question this does not answer: its comparison is generic on purpose, so the crossing would have to be per dialect where the type is not.

§What is emitted

Three inherent impls at most: the *Key’s, the *Lineage’s, and the RECORD’s own. The first two come with a struct each; the record already exists — the derive only adds methods to it.

The record also gets its ENTITY BINDING — impl Transformer for Record — naming those two emitted types, the row form the declaration asked for and the wire face it declared, with impl Identifiable beside it on the record and on the *Key, each binding the id column’s declared type. Every record has all three, a root included: a root has no *Lineage to name, so it binds (); a record that persists nowhere binds () for its row form; and a record with no graphql(…) block binds () for its wire face. The *Lineage is identified by nothing — a chain of ancestors has no one id.

ONE CONDITIONAL binding rides beside that total one, and it is conditional because what it names is. An EXPOSED record gets impl Graphql for Record with a carrier per half — <E>GraphqlInput naming the filter and the order-by, <E>GraphqlOutput naming the key output — minted in the const on the relation artifacts’ terms. The STORED half of the pair this used to describe is no longer a binding of its own: a stored record’s order rides its Record<Db> impl. A record meeting neither condition implements neither, which is what a projection through the missing impl refuses on.

The *Key gets one more of its own: impl KeySegments, walking its columns into a path, root first and the id last. That is the address the local filesystem blob store nests directories by, and it is emitted for every declaration rather than for the ones that store bytes — see RecordModel::address_segments for why, and for the vocabulary bound it lands under.

A declaration stating RELATIONS gets more, all of it inside the same const: one id equation per ref field, one pairing per target it names, an artifact per referring field, and one audit per derived(…) position. [relate] carries the whole of that story.

Each emitted type also gets a PAIR of conversions from the record: From<Record>, which moves its columns out, and From<&Record>, which clones them. Two rather than one because the choice is the caller’s and should be visible at the call site — TrackAddress::from(track) gives the record up, TrackAddress::from(&track) pays for a clone and keeps it. Neither can be const; a trait method cannot be. They need no bound of their own: the emitted struct derives Clone, so its column types are Clone by construction.

No constructor on the record. A real aggregate has twenty-odd fields, so a positional new would be unusable and transposition-prone; and the product schema hand-writes VALIDATING constructors (try_new rejecting nil ids) that a macro cannot replicate from a declaration. The application keeps its own constructor; this emits accessors and mutators only.

A declaration that WRAPS a foreign type gets one family more, and two of the above change their bodies rather than their shape: the reference family and the two conversions over the wrapped type, and readers and a raise that go through that type’s own accessors and constructor. All of it is crate::remote’s, including why none of it lands on this list — the family is core’s traits over a type the declaration names, and the allowlist above is about the FRAMEWORK’s.

§The shape of an emitted type, and why

Private fields, with accessors. A key is a value type with a construction path, not a transparent carrier whose representation is the API.

One new, positional, in key order — lineage root-first, then the id. A key has exactly one unsurprising way to be built, so there are no named constructors and no builder: a builder guards invariants, and a key has none — every combination of ids is a valid address, whether or not a row lives at it. No Default either; a default key is a nil address. new is const for every column shape, because moving a value into a struct drops nothing.

The mutators are the repository’s pair: set_x(&mut self, T) -> &mut Self to change one in place and chain, with_x(mut self, T) -> Self to derive a neighbouring key from this one. with_* carries #[must_use] — it returns the change rather than applying it, so dropping the result is always a mistake. There is no clear_* and no *_mut: a key’s columns are all required, and handing out &mut to one would let a caller mutate a live map key in place.

Both take T rather than impl Into<T>. A const fn cannot call Into::into, so an Into-taking setter could not be const for a marked column — and splitting the signature by markedness would make the two forms differ in more than constness, which is the one axis the marker is meant to control. This is a deliberate divergence from the hand-written style in the product schema.

§How a field is handed out

The projections are the product schema’s, reproduced rather than invented (mediaschema video/facet.rs, media.rs):

field typeaccessorschema
#[ingraph(repeated)]x_slice(&self) -> &[<T as Repeated>::Item]video/facet.rs:115
#[ingraph(optional)]x_ref(&self) -> Option<&<T as Optional>::Item>media.rs:197
unmarkedx_ref(&self) -> &Tvideo/facet.rs:121
#[ingraph(copy)]x(&self) -> T, IN ADDITION to the borrowvideo/facet.rs:110

A many-valued or optional field gets the PROJECTED shape — &[T] and Option<&T> — rather than &Vec<T> and &Option<T>, because those are what a caller can use without a second step.

The projection is chosen by the declaration’s MARKER, and the field’s declared type is written verbatim into a trait qualification: &[<Ids as Repeated>::Item]. Nothing pattern-matches the type’s spelling, so a type ALIAS projects exactly as the type it names would.

That is a bug fix, not a preference. The emitter used to match Vec<…>/Option<…> on the written type, and a field declared files: Ids was silently handed back as &Ids with nothing to catch it. A macro sees tokens, not resolved types — so the resolution is left to the compiler, which has the type.

Nothing is INFERRED either: an unmarked field takes the plain borrow. Removing a marker changes an accessor’s shape, and that should be a visible source change rather than a silent one.

A marked accessor is NOT const: it calls a trait method, and const trait methods are unstable. The plain and copy accessors, which touch no trait, stay const.

§copy, and what the marker changes

Every column gets x_ref(&self) -> &T. A column marked copy gets x(&self) -> T as well, and its mutators become const.

The marker is ADDITIVE, which is the point: adding it adds x(), removing it removes x(), and neither renames anything — so toggling copy on a column never breaks a caller that was borrowing it through x_ref(). A shape where the bare name switched between a copy and a borrow would rename the accessor at every call site instead.

It also makes the NAME state the return shape uniformly: x() is always a copy and x_ref() always a borrow, whatever the column’s type. The accessor convention’s default is not to demand _ref for every borrow, and this departs from it deliberately — a reader of generated code cannot see the emission to check, so predictability outranks terseness here, and additivity is what it buys.

The CONSTNESS asymmetry is the marker’s whole reason. set_x assigns over the column’s previous value and therefore drops it; a const destructor is unstable, so an unmarked column’s mutators cannot be const. A Copy value drops nothing, so a marked column’s can. The product schema already draws exactly this line by hand — a u32 setter is const fn, a Vec<Id> setter is not — and the marker automates it.

Whether a type really is Copy is NOT checkable here: a model carries names and types, not trait implementations. A wrongly marked column produces an emission that does not compile, reported at the generated accessor as “cannot move out of self.x”, which names the column.

§Every std name an expansion writes is QUALIFIED

An expansion lands in a module the framework does not control, and a bare path resolves THERE. A user with their own trait Debug in scope would capture #[derive(Debug)] on every emitted type at once, and a struct Option would break every projected accessor — with an error inside generated code the author cannot edit.

The anonymous const does not help. It scopes use statements; it does not change how a bare path in the enclosing module resolves. So every std item an expansion writes is spelled at its real path — ::core::fmt::Debug, ::core::option::Option, ::core::convert::From — derive macros included, which accept a path exactly as a trait bound does.

Not left to habit: fixtures::shadowed declares its own Debug, Clone, Option, Result and the rest, and derives the whole shape inside that module. If any bare path survived, that module would not compile.

§Where the impls sit

Every emitted impl goes inside ONE anonymous const _: () = { … }; per record — serde’s hygiene shape. The block is a scope, so the use statements the impl era will need (the framework traits, reached through the model’s krate path) can sit beside the impls without leaking a single name into the caller’s namespace. Today it holds only the inherent impls; the imports arrive with the traits.

The STRUCTS stay at top level — they are the API. Inherent impls inside the block remain fully reachable from another crate, const contexts included (verified cross-crate), so nothing about Key::new(7), .id() or .id_ref() changes for a caller.

Note for whoever reads the emission back: an impl-walking check that looks only at syn::File::items finds NOTHING now and passes vacuously. tests::impls descends into the block, and tests::the_impl_walk_descends_into_the_const_wrapper pins that it does.

No #[automatically_derived]. It is valid on TRAIT impls only — on an inherent impl this toolchain warns “can only be applied to trait impl blocks … will become a hard error in a future release”. The current emission has no trait impl, so the attribute has no valid subject and nothing is emitted. It belongs on each emitted trait impl, and lands with impl-era emission.

§#[inline], not #[inline(always)]

Every emitted method carries #[inline]. These are one-line cross-crate wrappers, which is the case the repository’s rust-type-conventions reference names for plain #[inline], and it records that #[inline(always)] is NOT a house default. The product schema writes #[inline(always)] by hand throughout (mediaschema video/facet.rs:109, :114, :120).

The divergence is deliberate, with both citations here so that neither side is “fixed” into the other by someone who has only read one of them.

Not #[non_exhaustive] — a decision, not an oversight. Nothing outside would be able to call new.

Not Ord, not Copy. Ord waits for a consumer; sorted output and BTreeMap keys are the case that will want it, and neither exists yet. Copy cannot be decided here at all — the field types come from the declaration, a macro cannot know whether they are Copy, and a derive cannot be conditional.

Constants§

PAIRED
The variant an In enum gives the keyed group.