Graphitron Development Principles

When different variants of a concept carry different data, use a sealed interface, not an enum with a shared field set: a sealed record hierarchy gives each variant exactly the fields it needs, and every switch that misses a new variant becomes a compile error. CallSiteExtraction is the exemplar ; some arms carry nothing, others exactly the references their extraction strategy needs ; read the type for the current arm set.

Enforced by: the compiler ; exhaustive switches over a sealed hierarchy break when a variant is added.

"Decide once" is also a statement about where raw external types may live at all. At capture the containment is structural: a relation stores values, so no live Table<?>, ForeignKey, Class<?> or graphql-java schema object crosses into the store. SdlFactCapture and its collaborators read each handle down to rows.

Off capture it is a convention: the rewrite and emit stages legitimately hold a registry or schema, so the rule is direction, not a holder roster. A consumer of a classification switches on captured values, and reaching back to a live object or a reflection Type tree for a fact the store could hold is the smell. An undecoded fact earns a column or a component, extracted at the boundary.

Enforced by: the store’s shape at capture (relations hold values, never live handles); off capture, review against the reads themselves (TypeDefinitionRegistry, GraphQLSchema, java.lang.reflect.Type, getGenericReturnType).

Give each fact the narrowest type the classifier can guarantee. A field record component declares the narrowest, not the broad sealed-interface root ; a return type that is always table-bound declares ReturnTypeRef.TableBoundReturnType directly, so consumers know it without a runtime check. A complex outcome gets its own sealed sub-taxonomy, not raw strings ; TableRef for the resolved table, ColumnRef for the resolved column. A new sub-taxonomy earns its place with a one-line note on what it carries that a sibling cannot ; otherwise it is a field on an existing record, and at milestone boundaries audit which could collapse.

Enforced by: the compiler where the narrowed component type is the contract; review for a new sub-taxonomy’s justification note and the milestone collapse audit.

"Carry the decision as a type" says what the model holds; this corollary says what it must not. Classification gathers facts and populates the model; the scaffolding it carries while gathering ; a builder-internal sealed hierarchy, a re-classification of the same argument in each output field’s context, a traversal carrier threading call context and collecting located violations as it walks the schema ; is an implementation detail, discarded before the model and invisible to every downstream view (generator, LSP). Validation is the same activity pointed the other way: it gathers facts too, reifying each missing or conflicting fact into a located violation the build acts on later (that violation’s typed shape lives under "Builder-step results are sealed" and "Rejections"). The smell either way: gathering scaffolding leaking into a model type, or a downstream view branching on a builder-internal type instead of the landed fact. A third form is inter-pass, not model-vs-scaffolding: several gathering passes coordinating implicitly through duplicated hardcoded skip-lists (buildFilters() skipping the pagination arguments buildPaginationSpec() claims, by the same hardcoded names) instead of each projecting exhaustively off one classification ; the lists must agree, nothing binds them, and a new argument type falls through both silently.

Enforced by: review only ; a downstream view referencing a builder-internal classification type, or two passes sharing a hardcoded skip-list, is the tell.

Every builder-step lift returns a sealed Resolved; rejection is a typed variant with a stable LSP code, never a string or out-param. The full narrative lives at Typed rejection. In fact-base terms, rejections are facts too: located violations asserted once and rendered into views ; the build log, the LSP ; never prose composed at the detection site.

Enforced by: the compiler on the sealed results; SealedHierarchyDocCoverageTest pins the permit-to-doc mapping for the Rejection taxonomy.

A fact true across a subset of variants is an orthogonal axis: reify it as a capability interface that exposes the fact uniformly (SqlGeneratingField.filters() over variants that carry filters in structurally different places), not as an instanceof chain re-enumerating the members. A view that forks on identity uses a sealed switch. Membership in a capability is itself a derived fact, so the axiom above governs it: safe when it is single-sourced ; mechanically assigned by the classifier or pinned by a test ; and a drift risk when it is a hand-declared marker nothing binds to the base facts it should track. Capabilities relocate exhaustiveness bookkeeping off the sealed switch rather than eliminating it.

Enforced by: the compiler for the accessor contract and the sealed-switch half; capability membership completeness is review only ; a variant that should implement a capability but omits it is a silent skip, so a membership meta-test is candidate roadmap material.

Where the ingress’s authoring-surface principle, state each fact once at its grain, is enforced at directive-design time. Directive arguments are flat scalars whenever the directive site already disambiguates the axis; an input-object wrapper is justified only for several genuinely-orthogonal pieces of information at once. @field(name: String!) is the worked example: the site (field, input field, argument, enum value) tells the classifier which axis is bound, so the directive carries only the name ; the axis is structural. The smell: an input wrapper most callsites fill in two-of-four slots on, whose failure surface widens from "the named thing didn’t resolve" to a cross-product of missing/inconsistent-slot errors (ExternalCodeReference is the existing case new directives should not lean on).

Enforced by: review only, at directive-design time.

When the model already carries typed information, runtime data formats derive from that metadata rather than inventing a parallel type system. The cursor format is the exemplar: each cursor column’s jOOQ DataType is already known, so encode/decode goes through field.getDataType().convert() instead of a hand-rolled type-tag system ; the column metadata is the type information. A parallel type system in a runtime format is the drift smell at the format boundary: redundant, and diverges.

Enforced by: review only.

Where the generator emits a method that crosses the wire-format boundary, it emits it in pair with a composer: the adapter decodes the wire shape into typed values, the composer does the work, and the composer’s signature is exactly the shape the adapter yields ; the boundary is the pair, not the adapter alone. The generated QueryConditions.<method>(Table, env) forwarding to the user-written <X>Conditions.<method>(Table, …​) is the worked example. The smell is asymmetric typing across the pair ; most often the adapter erasing type information the composer needs (an arity-erased RowN where the decoder produced Row<N><T1, …​, TN>; the fix has shipped), turning would-be compile failures into DSL-runtime surprises.

Enforced by: the graphitron-sakila-example compile where the pair’s signatures meet; review for the symmetry itself.

Every classifier decision that implies a generator branch must fail at validate time if that branch is unimplemented: the validator reads the same dispatch sets the generator does, so an unsupported classification is a build-time error, not a runtime UnsupportedOperationException. The dispatch state is a four-way disjoint partition over every GraphitronField sealed leaf: TypeFetcherGenerator’s `IMPLEMENTED_LEAVES, NOT_DISPATCHED_LEAVES and STUBBED_VARIANTS.keySet(), plus the projected bucket derived from the projection producer’s own membership declaration (ProjectionCommands.CONTRIBUTION_MINTING_LEAVES minus the dual-arm kinds; safe to derive because the test below pins the partition and the projection census test binds the declaration to observed minting), and ValidateMojo fails the build on stubbed variants. The rule extends to every new classifier invariant: no generator-side invariant goes unchecked at validate time.

Enforced by: GeneratorCoverageTest.everyGraphitronFieldLeafHasAKnownDispatchStatus (partition exhaustive and disjoint); ValidateMojo fails the build on stubbed variants.

The reverse direction: a classifier acceptance lets an emitter assume narrower shapes, so emitted code reads as tight as hand-written ; no defensive casts, no wildcard locals, no instanceof guards. The contract anchors on three layers: type-system narrowing at the producer (a record component, a return type, a sealed sub-variant ; once in the type, mechanically enforced), pipeline-tier tests pinning the end-to-end shape, and the graphitron-sakila-example compile as cross-module backstop. A defensive runtime cast or a var-typed local abandons the guarantee ; it fails on a real request, days after the build passed. Candidate type-system lifts that would carry current prose contracts structurally are method type-token threading and ColumnBackedField.parentTable. To record a producer-consumer linkage the type system can’t carry, use a javadoc {@link} from consumer to producer ; build-checked by the javadoc reference gate. Rule: if you relax a producer’s check body, audit every emitter site that consumes the corresponding shape, in the same commit.

Enforced by: the type system where the contract is lifted; the javadoc reference gate for the {@link} itself; the pipeline tier and the graphitron-sakila-example compile otherwise.

Behaviour is asserted at the SDL to classified model to generated TypeSpec pipeline layer; new features earn a pipeline test first. Above it, the graphitron-sakila-example compile pins type correctness and PostgreSQL execution pins behaviour. Code-string assertions on generated method bodies are banned at every tier: they test implementation, not behaviour, and break on every refactor ; the compile and execution tiers replace them. Tier names, locations, and the decision rubric: Test-tier guide.

Enforced by: the tiers themselves, on every -Plocal-db build; the code-string ban is review-enforced at test-review time.

An unguarded inventory in this document ; an arm list, a file census, an occurrence count, a compliance roster ; reads as authoritative and rots silently. A principle names the rule, one canonical exemplar, and the smell; an inventory appears only when a named live test pins it (the dispatch partition under "Rejections" is the pattern). Anything enumerable is first a materialized view, regenerated and --verify-gated on every build (supported-directives.adoc is the precedent); hand prose is the fallback for rationale only. Exemplars are chosen on stable surfaces: an exemplar that needs a forward note about its own demolition is the wrong exemplar.

Enforced by: review; the named-test requirement is the rule itself.

Every prose claim about code takes one of three honest forms: anchored on a checked reference (a {@link} the reference gate verifies), pinned by a named live test or type, or written at intent altitude ; the why and the shape ; so it survives mechanical refactors. Orientation javadoc is the blessed intent-altitude case: a class-level on-ramp (scope, entry points, model output, doc pointer; `GraphitronSchemaBuilder’s top comment is the exemplar) orients without narrating mechanics. The smell is narrow: line-by-line narration of a body, or prose paraphrasing a mechanism ; a hand-maintained caller census ; true when written, silently falsified as the code moves. Prefer deletion over rewrite.

Enforced by: the reviewer gates (Spec to Ready, In Review to Done); doc-coverage meta-tests where the surface is closed (SealedHierarchyDocCoverageTest and its siblings); RetiredVocabularyGuardTest for prose naming retired vocabulary.

A generated method that throws on a real request must produce a stack frame, a line, and locals that a developer who has never seen the generator can reason about. Concrete rules for any code a generator emits:

The smell: an emitter building a CodeBlock of nested ? : with Object casts and _x locals ; written for the emitter author’s convenience, not the consumer’s. (The NodeId-decode instance is cleaned up; the @condition arg-extraction instance is not.)

Enforced by: GeneratedSourcesLintTest.emittedSourcesDoNotUseVar and GeneratedSourcesLintTest.emittedSourcesHaveNoDunderIdentifiers (plus that class’s sibling lints); review for statement form and naming.

Three categories, three floors. Generator implementation may freely use Java 25 features. Generated source files must be valid Java 17: consumers compile Graphitron’s output with their own toolchain, so nothing emitted may require 21+ ; no switch patterns, no sequenced-collections API. Hand-written runtime artifacts consumers depend on (graphitron-jakarta-rest is the first instance) must also target Java 17 ; a runtime jar on the consumer’s classpath keeps the same floor as the generated sources. When adding code, ask which category it is in before reaching for syntax.

Enforced by: the parent pom’s requireJavaVersion enforcer (generator floor); graphitron-sakila-example compiling with <release>17</release> (emitted-syntax ceiling); graphitron-jakarta-rest’s own `<release>17</release> main compile (runtime category).

The emitter-conventions catalogue (return types, selection-aware queries, error quality, DSL.val column binding, DTO-parent batching, helper-locality) is reference material for emitter authors: Emitter conventions.