Skip to main content

Module interface

Module interface 

Source
Expand description

The INTERFACE face: 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 crate::union equips — one variant per member, each carrying that member — and the promise is the fields(…) list: every member has these fields, at these types, and the ones the declaration marks COMPUTED are derived rather than stored.

§It is a PSEUDO-RECORD, and today it declares only the promise

An interface names no table and mints no id. What it has instead is the set of its members’ rows, which is why its query layer is a fan-out rather than a select — and that layer is not this round’s. What lands here is the DECLARATION and the TEETH: the contract as a Rust trait, the per-member implementations of it, and one type equation per (stored field, database, member) saying the member’s row really carries the column at the type the interface pinned.

§The three TIERS a field can be in, and the two FACES they land on

tierwrittenevery memberwhose face carries it
storednothing, or persist(<db>(type = "…"))carries the column<I>Fields, on the MEMBER
computedgraphql(computed)DERIVES the value<I>Derivations, on the member’s wire OUTPUT
try_computedgraphql(try_computed)derives it, falliblythe same, returning a Result

Stored and computed are MUTUALLY EXCLUSIVE, in both directions: a value a member derives is not a column its row holds, and a column its row holds is not a value it derives. The front end refuses either spelling of the pair rather than electing one.

The domain contract is STORED-ONLY, and the split is the ruling rather than a staging. 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 it on the domain trait would have made every member’s domain type owe a method its rows have no column for and its pipeline never asks. <I>Fields therefore carries the stored tier and nothing else, and the computed tier is <I>Derivations, whose implementors are the members’ GraphQL OUTPUT types.

<I>Derivations is DECLARED here and implemented nowhere: the emission writes the trait, and a member’s output type writes the impl by hand. There is no escape machinery under it for the same reason — a hand author writes their own glue, and a generated adapter would be a seam nobody asked for. The interface’s own output face is what consumes it, and that face is the find half’s.

§A member may call a stored field something else, and the INTERFACE is where it says so

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.

HERE rather than on the member, and the reason is what a macro can see. A member-side word would have to reach an 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 on the interface, every hop of the chain is backed by the SAME derive input: the block’s key is checked token-for-token against the enum’s own variants, the variant names the payload type it carries, that type projects to <M as Record<Db>>::Row, and the declared ident is what the access spells.

It extends the axis one step, and the step is INTERFACE-SPECIFIC: interface field block ▸ members(…) ▸ one block per variant ▸ entries. A record grows no member axis, having no members — so this is the one grammar in the framework where a block’s key is a variant rather than a database or a domain, and the container is what says where that holds. POSITION decides: outside it every key is a word the grammar owns, inside it every key is a variant.

§The names this expansion puts in the declaring scope

InterfaceModel::emitted_types is the list, and each name arrives with what it IS: the sealed refusal the union half writes, the CONTRACT trait, the DERIVATIONS trait a member writes its computed half through, the DISCRIMINANT, the two ADDRESSES over it — the id sum a row carries and the key sum a hit will — one PROJECTION ROW per SQL database the declaration is about, the page’s cursor and predicate, the order-by, and the two the wire query surface is: the FILTER a client sends and the ARGUMENT object that carries it.

The RESERVED list is empty, and this is where it ended. Every name on it had a function here and no emission — the point being that a name decided when its emission lands is a name decided twice — and each has since been taken by the emission that reserved it. The KEY was the last, and it is the one that left by RULING rather than by a consumer: it is the fusion seam’s premise, so it is minted before that seam rather than with it.

§crate = "…" exists here where the union has none

A union’s whole expansion is core, so there is nothing for the option to move. An interface’s is not: the membership evidence, the storability the equations read a row through, and the backend gates they ride are all framework names, so the declaration states its root once and every emitted path follows it.

Structs§

InterfaceDatabase
ONE database inside the interface’s own persist(…): which, and what its synthetic words are named in.
InterfaceError
ONE database’s refusal cell for the crossing an interface’s hydration performs.
InterfaceField
One field of the contract: what every member has, and how.
InterfaceModel
One interface’s declaration, validated.
MemberColumn
What ONE member calls one field of the contract.
Operand
ONE database’s operand crossing for one field: the function its values enter storage through.
Pin
ONE database’s pin for one stored field: the type that database keeps it at.

Enums§

Tier
Which TIER one field of the contract is in.

Functions§

default_derivations_name
What an interface’s DERIVATIONS trait is called: <Interface>Derivations.
default_fields_name
What an interface’s CONTRACT trait is called: <Interface>Fields.
default_filter_name
What an interface’s FILTER is called: <Interface>Filter.
default_id_name
What an interface’s ADDRESS is called: <Interface>Id.
default_input_name
What an interface’s wire ARGUMENT object is called: <Interface>GraphqlInput.
default_key_name
What an interface’s KEY is called: <Interface>Key.
default_kind_name
What an interface’s DISCRIMINANT is called: <Interface>Kind.
default_order_by_name
What an interface’s ORDER is called: <Interface>OrderBy. The RECORD’s convention — see default_key_name.
default_output_name
What an interface’s wire OUTPUT object is called: <Interface>GraphqlOutput. The RECORD’s convention — see default_key_name.
default_row_name
What an interface’s ROW is called in one database: <Interface><Db>Row.