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 type | accessor | schema |
|---|---|---|
#[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 |
| unmarked | x_ref(&self) -> &T | video/facet.rs:121 |
#[ingraph(copy)] | x(&self) -> T, IN ADDITION to the borrow | video/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
Inenum gives the keyed group.