The schema describing itself

No crossing is declared for this family and no foreign key crosses its boundary; its rows meet the other families' only where a reader joins them.

The schema’s own description: the family roster, each family’s headline relations and its sanctioned normalization crossings, the placement of relations no prefix covers, the census that closes both rosters against the observed schema, the declared key edges resolved out of the engine’s catalog, the register of which derived views are materialized into which tables, and the register’s derived refresh edges. Rows that are a function of this file alone, versioned with the DDL they describe and never refreshable apart from it, which is the property that matters and which every form in the family keeps: a roster stated as a VALUES view has rows that are part of the definition, and the register stated as a table has rows an INSERT in this same file supplies before any run opens the store. The register takes the table form because it is the one resident whose rows a constraint should defend, a key on the source view and NOT NULL on all three columns, and a view can carry neither; the two older rosters keep the view form until an item converts them. meta_materialize_dependency is the family’s one machine-written resident: unlike its authored siblings its rows come from one boot-time routine that derives them from the stored view definitions, so a hand edit is a bug, the same standing meta_relation_family’s comment claims for its derivation, here as a table because transitive reach through unregistered intermediate views is not a plain SQL view’s to express. Not store_, because these rows are a statement of what this file declares, never a record of what a run read.

The family roster: one row per relation-name prefix, keyed by the prefix under the schema’s naming discipline (a family is named for whose vocabulary its rows are written in, never for its reader or its role). The introduction column presents each family to a first-time reader and the definition column carries its charter, the latter migrated out of this file’s header so the roster has one home; the generated schema reference renders one page per row, ordered by ordinal, and the schema gates close the roster against the observed relations in both directions.

The sanctioned normalization crossings: one row says that this relation owns the rule by which a name written in one family’s vocabulary is matched against another family’s census. How two families meet is a fact about the schema rather than prose an author writes about it, so the crossings are declared here in the DDL the way the family roster and the materialization register are, and the reference renders the declarations. What the roster defends against is a fork: a new view can re-derive a normalization with its own function calls in a join predicate, produce plausible rows, and quietly leave two rules where the schema states one. Membership is two tests together. A relation is on the roster when it owns a normalization rule of its own, spelled in its own body, not when it reads a relation that states one; and when that rule mediates a meeting between two families' vocabularies, not a normalization inside one. Where the DDL assigns a rule’s ownership in its own comments, the roster follows that assignment, so a coordinate-shaped sibling whose comment says the rule is argued at the other site restates a body rather than a rule and earns no second row. Crossings by plain column equality on a shared natural key are deliberately absent: a foreign key is already a declared, engine-checked join path, and an identity comparison has no rule to re-derive differently, so there is nothing a new view could silently fork. The declarations are resolve-gated only. Whether they cover every crossing the views actually perform is a derivation over the view-read census, which no declaration can answer on its own, and until that closure exists the reference presents these rows as declarations and claims no exhaustiveness.

The headline roster: the relations a reader should meet first in each family, typically its central grain plus the derivations that make the grain useful. Curation is judgment, which is why membership is authored here and nothing else about a row is: the family comes from the meta_relation_family census by join rather than being stored beside the name, and what each headline means comes from the relation’s own comment, so there is no second blurb to drift from the first. The generated schema reference renders the roster as the family page’s starting point, each entry the relation name linked to its own entry further down the page plus the first sentence of that comment. Not named for the store glossary’s word grain, which this roster does not mean: a reader of the reference must never have to disambiguate a load-bearing word.

The register of materialized derivations: which derived views are refilled into which tables, and why. One row is one registration, read by the materializer on the capture cadence, which empties the target and refills it from the source view inside the capture transaction, per graph where the relation is graph-keyed and whole where it is not. The pair is directional and the direction is the whole point, which is why both columns say which end they are. A registration is invisible to consumers by construction: the canonical name every existing reader already spells is the name the target table takes, and the view stating the rule is what gets renamed, so no reader is edited and the rule is still written exactly once. The register itself carries no ordering; where one registered view reads another registration’s target, that fact is derived from the stored view definitions into meta_materialize_dependency at boot, and the materializer refreshes in an order respecting every row of it.

Primary key: (source_view_name).

The registry’s derived refresh edges: one row per registration whose source view reads, directly or through unregistered intermediate views, the target table of another registration, which must therefore refresh first. The family’s one machine-written resident: the rows are a function of this file alone, computed once per booted store by the population routine beside the materializer (no.sikt.graphitron.model.derive.MaterializeDependencies), which parses the stored view definitions and rewrites this relation before the first refresh, so a hand edit is a bug the next boot undoes, the same standing meta_relation_family’s comment claims for its derivation. A table rather than a view because transitive reach through unregistered intermediate views is not a plain SQL view’s to express. The materializer refreshes in a topological order over these rows with an alphabetical tie-break, so a row-free relation orders exactly as the registry’s own key does; a cycle among registrations is a registration error the build-time gate refuses, no refresh order making every target equal its view on a settled store.

Primary key: (source_view_name, depends_on). Foreign key: (source_view_name) references meta_materialize (source_view_name). Foreign key: (depends_on) references meta_materialize (source_view_name). Check: "SOURCE_VIEW_NAME" <> "DEPENDS_ON".

The placement exemptions: one row per relation deliberately outside every family, in the exemption polarity the schema gates use throughout, so a new prefix-less relation fails the roster gate until an authored row argues it in. The page column places the relation in the generated reference; the reason column carries the no-family argument beside the relation’s own comment.

The census that closes the roster: every relation in the schema, its kind, the family whose prefix covers it, and whether an exemption row places it. The one relational answer to which family a relation belongs to: the schema gates, the generated reference and the docs drift guard all read this view rather than re-deriving the match, so two mechanisms of different fidelity can never answer the question differently.

The declared key edges: one row per FOREIGN KEY the schema declares, naming the relation that references and the relation referenced, each with the family the census places it in. At constraint grain deliberately, and not filtered to the edges that leave a family: cross-family is a predicate a reader applies to these rows, not a population baked into the relation, and the name says what a row is rather than where it happens to render. Resolved out of the engine’s own catalog, a referential constraint through the key columns on both ends, so the edges are exactly what the DDL declares and no second list can fall behind them. A store view rather than something a renderer aggregates for itself, because family assignment is never re-derived outside the census, and because the generated reference is only the first reader: a gate closing the declared normalization crossings and the schema surface the editor tooling reads both ask this same question. Derivation seeded by declaration is the shape the whole family relationship rests on, here the declared foreign keys.

← Schema index