#[interface]Expand description
Declare an INTERFACE — a member set with a contract over it.
An interface is a union plus a promise. The union half is the same payload-carrying enum
Union equips: one variant per member, each carrying that member and nothing else. The
promise is fields(…) — every member has these fields, at these types.
#[ingraph::interface(
persist(sqlite, postgres),
graphql(computed(error = "media::ComputeError")),
fields(
title: String,
mask(type = "Mask", copy, persist(sqlite(type = "u32"), postgres(type = "int4"))),
created_at(type = "Timestamp", members(Audio(field = "imported_at"))),
display_label(type = "String", graphql(computed)),
checksum(type = "u64", graphql(try_computed)),
),
)]
pub enum Media {
Video(Video),
Audio(Audio),
}§A field is in ONE of three tiers, and the tier decides whose face carries it
| tier | written | every member | the face |
|---|---|---|---|
| stored | nothing, or persist(<db>(type = "…")) | carries the column | <I>Fields, on the member |
| computed | graphql(computed) | DERIVES the value | <I>Derivations, on its wire output |
| try_computed | graphql(try_computed) | derives it, fallibly | the same, returning a Result |
The domain contract is STORED-ONLY. A computed field is a query-layer construct — it is derived
to be answered, and what answers a query is the wire output — so putting one on the domain trait
would make every member’s domain type owe a method its rows have no column for. <I>Derivations
is DECLARED and implemented nowhere: a member’s output type writes the impl by hand, and there
is no adapter under it, because a hand author writes their own glue.
Stored and computed are mutually exclusive in both directions, and each direction has its own refusal.
§Attributes
On the enum:
crate = "path::to::ingraph"— whereingraphlives, exactly asrecord’s. Present here where a union has none, because an interface’s expansion DOES name framework paths: the membership evidence, the storability its equations read a row through, and the backend gates they ride.unwrap_error(rename = "Name")— what the emitted REFUSAL type is called. Defaults to<Interface>UnwrapError, which is the union’s convention reached through the union’s own function.errornames the CONVERSION CELLS instead, and the old spelling is a named migration refusal — one word per thing typed.persist(sqlite, postgres, …)— which databases the contract’s pins are checked at. A SELECTION rather than a storage declaration: an interface owns no table. A database block may carryalias(prefix = "__mine"), which moves the words a union statement INVENTS in that database — the discriminant every arm projects and the derived table the outer query names.depthis refused here: it is the length of an alias table, and an interface has none.graphql(computed(error = "path::To"))— the type every fallible computed field answers with. ONE cell and DB-LESS, which is this grammar’s one ruled exception to database blocks: a computed value is derived from the member rather than read out of a row, so the crossing names no database.fields(…)— the contract. An interface with none is a union, and is refused by that reason.
A field is <name>: <Type> or <name>(type = "<Type>", …), and the long form takes copy,
persist(<db>(type = "…")), graphql(…) and a MEMBER block. The long form’s type is written in
a STRING, as every other type in this grammar is; the short form’s is the Rust type itself,
because there it is what the : already introduces.
§A member may call a stored field something else
created_at(type = "Timestamp", members(Audio(field = "imported_at"))) — the member Audio carries this
field as imported_at, in its own struct and in its own row.
Declared on the INTERFACE rather than on the member, and the reason is what a macro can see: a member-side word would have to reach the interface’s expansion across a derive boundary, and the only things that cross one are a type and a const — neither of which produces the IDENT a field access needs. Written here, every hop is backed by the same derive input, starting with the block’s key, which is checked token-for-token against the enum’s own variants in VERBATIM case.
What a block moves is the ACCESS and not the METHOD: a caller writes the interface’s name
whatever member it is holding. field = "…" is the only entry it takes; one members(…) per
field, never empty; and members(…) on a computed field is refused — a derived value is read
out of no column at all.
§The axis law
A DOMAIN block, then a DATABASE block, then that cell’s entries — at every level. So a database name written where a domain belongs is refused BY NAME rather than as an unknown entry, wherever it appears.
A field’s members(…) extends it one step — interface field block ▸ members(…) ▸ one block
per variant ▸ entries — and the step is this grammar’s alone: a record grows no member axis,
having no members.
POSITION decides what a key is. Outside members(…) every key is a word this grammar owns;
inside it every key is a VARIANT, matched token-for-token against the enum’s own. A variant
written outside the container is refused BY NAME rather than as an unknown word, and one whose
spelling collides with a grammar word — or one in lower case — is reachable inside it, where a
rule reading the first letter had a corner it could not address.
§What it emits
The union face — is_<member>, the unwrap_<member> family in all three receivers, and the
sealed refusal — through the same seam Union reaches, so an interface’s members are asked for
exactly as a union’s are.
§Refusals
The SHAPE refusals are the union’s family, stated in this declaration’s own terms: a non-enum, an enum with no variants, a variant carrying no member, one carrying several, one carrying its member in a named field, any generic parameter, two variants carrying one type, and two variants whose words derive one method.
Its own are the contract’s: a field declared twice, a field with no type, an entry neither form
admits, a database name at a domain position, an interface with no fields(…) at all, and the
tier collision in both of its directions. members(…) adds five more — a key naming no variant
(refused by listing the ones there are), one member named twice in one container, a container on
a computed field, a second container on one field, and one naming nobody. A member block written
OUTSIDE the container is refused by name, which is a migration rather than an unknown word.
A field’s graphql(output(<db>(…))) is ADMITTED AND REFUSED rather than unknown: it is a real
entry of the settled design whose consumer is the interface’s own output face, whose stored half
waits on an accessor a member’s wire object does not publish yet, so the refusal names the shape
and says what it arrives with. The four operand and hydration cells beside it are READ — see
[interface]’s own note for which level each sits at and why.