The fact store schema

Every run of the generator leaves a record of itself here: which module it captured, which files it read, what configuration it held in hand, and where it wrote. The rows answer bookkeeping questions rather than schema questions: what was this store built from, and which graph do these facts belong to. When two runs disagree, this family is where you look up what each of them actually saw.

A complete transcription of the GraphQL schema documents, as any SDL reader would see them. Every type, field, argument and directive application lands here exactly as written, with no judgment about what any of it means. The two judgment rows it does hold are the SDL toolchain’s own verdicts on whether the documents parse and validate at all.

What the generator understands the author to have asked for. Each row is the decoded reading of one directive application: the same information that stands in the schema documents, restated in the generator’s own vocabulary so later questions can be asked with plain joins instead of re-parsing strings. Decoding is tolerant: a value that does not fit the declared shape is quarantined rather than lost.

What the consumer’s database declares, read through the generated jOOQ model: schemas, tables, columns, keys, constraints, indexes and callables. These rows are the ground that written table and column references are checked against. A few rows also transcribe what the generated model states about itself, because that model ships as one unit with the catalog it was generated from.

A census of the classes available on the declared compile classpath: the classes themselves, their public methods and parameters, their record components and supertypes. When the schema names Java code, this census is what the name is checked against. Presence says nothing about purpose; a class earns its row by being on the classpath, not by being used.

Where things are written in the consumer’s own Java sources: the position and documentation comment of each class, method and field declaration, from a plain parse of the source files. It exists so tools can point at a line in a file the author owns. It reads the sources rather than the compiled output deliberately, because the two answer different questions and may legitimately disagree.

What the JDK compiler reported when the emitted sources were last compiled: one row per diagnostic, in the compiler’s own words. Each compile round replaces the previous one wholesale, so the family always describes the latest round and nothing older.

What the legacy classification walk concluded, kept while that walk is being retired. The rows exist so new derivations can be checked against the old code’s answers during the migration; when the walk is gone, the family goes with it.

The derivation layer: what follows once the schema’s readings, the database catalog and the classpath census are put side by side. Rows here are computed, never captured; each view states one rule, and taller derivations are built by reading shorter ones. This is the family the generator and the editor tooling actually plan from.

The legacy walk’s error verdicts, in the sealed rejection hierarchy’s own vocabulary. Transitional by construction: each kind of verdict moves out as its detection is rebuilt store-native, and the family empties as that migration completes.

The linter’s findings: one row per finding, plus the corrections a rule can compute for its own findings. A correction here is a suggestion an editor may offer, never a rewrite the build performs. The family speaks the linter’s vocabulary, where severity follows from the rule.

The advisory arm of build feedback: warnings that point at nothing rule-shaped, just a message and a location worth a human’s attention. Small on purpose.

The schema describing itself: which families exist, where the exceptions live, and how the roster closes against the relations actually observed. These rows are versioned with the schema definition and never change at run time. The reference pages you are reading are rendered from this family’s rows and the comments beside them.