The Graphitron data model

Every GraphQL field has a coordinate, its (parentType, fieldName), and Graphitron’s job is to turn each coordinate into the Java that resolves it. Today it does so by mapping each coordinate to one large "leaf" object that welds together everything the field needs at once, and those leaves multiply into a cross-product (Split x Lookup x Composite x …​) that this spec exists to dissolve. The dissolution has two halves.

The two halves meet at the operation relation: a coordinate’s facts decide which seams its query composes. A worked example is film.language: one coordinate, whose facts are a source (a Film row arrives), a target (it returns one Language), and a reference (the value lives on another table, reached by a foreign key); together those trigger a join and a select. No leaf type encodes "single table field reached by a reference"; the facts do, and they add rather than multiply.

This item is the model: the facts, the method graph, and the integrity check that ties them together. Re-platforming the generator’s emit onto the model is a separate item, R314. Suggested reading order is this orientation, then The model (the ER diagram and the fact catalog) and What the model enables, then the detail: the front half (The normalized schema: the coordinate and its facts) and the back half (Operations are realized by seams). The lettered Discovery threads (A-K) at the end record how the model was derived by walking the current emitters; they are the evidence, referenced throughout, not prerequisites to read first.

The entity is the schema coordinate, the GraphQL spec’s SchemaCoordinate stored decomposed into its grammar columns (the key system is The natural keys below; Foo.bar is the output-field case). The model is that coordinate together with a small set of facts, each an independent functional dependency found by its own walk. The leaf zoo, the per-field "graphitron field", and the two library types (DataFetcher, QueryPart) are denormalized views over these facts; a capability is added by adding a fact, not a new leaf type. The whole model at a glance:

The diagram is itself a denormalized view, the same move as the leaf zoo is a denormalized view below. A discriminator marked (sealed) is a tagged union, not one relation with nullable-by-arm columns: each variant carries only its own non-null columns (concrete-table inheritance, exactly like the coordinate key in The natural keys), and the per-variant columns are normalized in that fact’s deep-dive below. Flattening a union into one box with a kind / arm / domain enum is the diagram’s convenience, not the model’s shape; in the type system each is a sealed interface (Source, Operation, JoinStep, TargetShape, ErrorChannel, the discrimination signal). The unmarked entities are genuine single relations.

The catalog, each row a fact with its own deep-dive below:

The model is closed. Every active directive’s effect has an owning fact in this catalog; the completeness audit, directive by directive, is Directive coverage near the end. The two halves of the lowering, these facts (front) and the method graph that consumes them (back), meet at the operation relation, detailed throughout the rest of this document.

The model’s spine is its natural keys, and the entity key is not ad-hoc: it is the GraphQL specification’s SchemaCoordinate, the same coordinate this document is named for. The spec already standardizes the grammar for addressing every element of a schema, so the model adopts it rather than inventing a key. (Later sections still sketch the coordinate as (parentType, fieldName) for readability; that is shorthand for the MemberCoordinate output-field case. The ER diagram in The model draws the full key.)

The coordinate is a SchemaCoordinate, stored decomposed into its grammar columns. The spec’s five productions are five coordinate kinds, each carrying exactly the Name positions of its production, and the coordinate kind is just which production matched:

The columns are what the model keys, joins, and indexes on: every member of a type is a prefix scan on typeName, every argument of a field a prefix scan on (typeName, memberName). The canonical string is a derived render over the columns, never the stored key. Spec fidelity earns three things from one render function: the string is the spec’s own serialization, it is the stable id the model-context surface hands an agent to traverse between answers, and it is the per-coordinate key the language server files its classification under. One coordinate system, one render, three readers, no second id grammar to maintain.

This is a sealed union, not one table with nullable columns. Reading the five kinds as columns of a single coordinate relation would make typeName / memberName / argumentName / directiveName nullable and push "which columns are populated" onto an unenforced convention keyed off kind: single-table inheritance, the denormalized shape this whole document argues against. The model is instead a sealed SchemaCoordinate with five variants, each a relation carrying exactly its own Name positions, all non-null. That is concrete-table inheritance, the relational name for the sealed hierarchies the project already builds in the type system, so the key obeys the same compile-time discipline as the facts that hang off it. The shared leading columns are real, typeName heads Type / Member / Argument and directiveName heads Directive / DirectiveArgument, and that shared prefix is exactly what the prefix scans key on; it is shared structure across variants, not one flat row with holes. The ER diagram in The model draws the coordinate as a single keyed box because its subject is the facts that hang off the coordinate, not the key taxonomy; the decomposition lives here.

MemberCoordinate is a single key covering what earlier drafts split into three: an output field (Film.language), an input-object field (FilmWhereInput.title), and an enum value (Color.RED, the EnumValue key the enum facts carry). All three are Name.Name; they were never distinct key spaces. The directive productions make directives first-class addressable elements, not merely things that annotate other coordinates: a directive definition is @foo, its argument @foo(bar:).

Input fields are member coordinates of their own input type, not a path under the consuming field. The spec is definition-keyed and has no dotted-path coordinate, so a nested input field is addressed as a MemberCoordinate of its input type (FilmWhereInput.actor, then ActorWhereInput.lastName), and the use-site "path" earlier drafts wrote as (typeName, fieldName, inputPath) is not a coordinate at all: it is a derived traversal through the coordinate graph, an ArgumentCoordinate followed by a chain of input-type member coordinates. This is where the authored / derived split lands precisely. The authored facts (@field, @reference, @nodeId on an input field) live at the definition member coordinate, which is where the editor edits them: the cursor sits inside the input type’s definition, consumed by many fields, so the definition coordinate is the only key available. The use-site resolution (which table the input binds against, the inferred FK, the generated condition’s column) depends on the consuming field, so it is a derived join over (input member coordinate, consuming coordinate). Definition-keyed authored fact, use-keyed derived binding: the provenance axis, stated in the spec’s own grammar.

Everything beyond the spec’s coordinate set is a relation over coordinates, never a new coordinate kind or an extra column. A directive application (a @reference written at Film.language) is an edge joining the host coordinate to the directive coordinate and carrying the applied argument values; the Directive coverage audit is exactly that edge set, and "this @reference lowers to a join fact" is one edge resolving to facts. The use-site binding above is a derived relation. Neither becomes a sixth coordinate kind. The coordinate stays a faithful, column-decomposed SchemaCoordinate; the model’s extensions sit outside the key.

One base, three consumers, and the consumers do not all read it at the same depth. The facts are the base relations; everything a consumer reads is a view computed over them. The model already ships this layering, so R333’s job here is to name it and to keep it from fracturing into separate models as the leaf zoo dissolves.

The layering, as it ships today. Between the facts and the consumers sit two layers of view:

So "one model, three readers" is not aspirational, it is implemented, with a compile-enforced seam tying the projections to the classifier. What it is not is three co-equal readers of one flat fact set: there is a base, there are views, the views stack two deep, and the consumers enter at different depths.

Code generation is the narrowest view, not the model. It reads the resolved values (the resolvedTable coalesce, the inferred FK, the rolled-up enum backing) and demands a total, integrity-clean snapshot before it runs. It does not select the columns the other two live on: the authored form behind each resolved value, the description text, the source position. Those columns are in the base regardless; code generation simply does not project them. Calling code generation "the model" was the original error; it is the projection that selects the fewest columns and imposes the strictest precondition, no more privileged than the others. Re-platforming the emit onto the facts is R314.

The invariant that keeps it one model: the projection seam re-sources from the facts. Today CatalogBuilder.projectFieldClassification switches over the classifier’s leaf permits to build FieldClassification. When the leaf zoo dissolves into facts, that switch must re-source, from the leaf permits to the facts, and its compile-time coverage guarantee must move with it. This is the single load-bearing requirement of widening the model to three consumers. Miss it and the dissolution proceeds on the code-generation side while the projections still need the old leaf permits, so the leaves are kept alive as a shim purely to feed the editor and the agent, and the leaf zoo we set out to dissolve returns as a second model whose only job is the projection layer. Facts, revived leaves, and projections is three models. The fix is to point the projection seam at the facts and let its coverage switch fail to compile until every projection re-sources, the same falsifiable-closure discipline thread I applies to the emit.

The shared discipline is We are data modeling: the facts are typed, keyed relations in the type system, materialized as in-memory collections guarded by a referential-integrity check, not sat on a query-engine runtime. The three consumers read views over one base; the base carries every column some view needs, and no consumer owns a private model.

The section above promised the base carries columns code generation does not select. Three are due here, and they are a test of a relational instinct: do not assume a fact’s origin is a column on the fact. Authored data and inferred data often come from different walks, the directive walk versus the catalog or producer walk, and when they do the natural form is separate relations coalesced by a view, not one relation with a provenance tag. Pick per fact: a column when there is one value in one slot, separate relations when the origins are independent walks or the values are multi-valued. The three facts below pick three different shapes, which is the point.

The base carries facts; most of what a consumer reads is derived from them. Three derivations recur often enough to name, because each is easy to mistake for a stored thing and model wrong. The first is the catalog of views the six reads compute; the second is freshness, a property of the whole materialization; the third is location, the fact that flushed out the SourceLocation question. The thread tying them together: name the derivation, do not store its result where the base belongs.

The shipped field model (R290/R299/R305/R316) carries a hidden 1:1 assumption: one schema coordinate == one graphitron field (one OutputField leaf). That assumption is the root cause of the leaf cross-product (Split x Lookup x Record x Composite x …​): whenever a single SDL field has to contribute more than one thing to the emit, the multiplicity gets welded into a monolithic leaf as a repeating group or an extra duty. The pivot drops the 1:1, but the unit it drops to is the heart of this spec, and it is neither the field nor either library type. It is the emitted Java method:

This spec is the model; consuming it (re-platforming the generator onto the lowering) is R314’s emit re-platforming. The graph framing was reached by walking the actual emitters; the Discovery section below records that chain, each step pinned to a current emitter with line numbers. It superseded an earlier, narrower headline ("a coordinate lowers to one DataFetcher plus one or more `org.jooq.QueryPart`s") that named the SQL-side unit a level too fine. That earlier framing is kept in Discovery as the path in, not as the model.

The reason the field is the wrong unit is granularity: the methods we emit do not all sit at field granularity, so no single per-field model can source them. The method graph is the model precisely because it lets each node sit at its own granularity. Reading the current output bottom-up:

Granularity is heterogeneous on purpose; that heterogeneity is the content of the model. The leaf zoo is what you get from forcing one field-granular model to source all of these kinds at once. (Full table with code coordinates: Discovery thread E.)

Graphitron bridges GraphQL-Java and jOOQ, and the two libraries' own types still name the two sides of the graph, but as node-kind attributes, not as the top-level structure:

So the model is one graph; the resolve/SQL split and the two library types are how its nodes are typed, not two parallel emit targets. (Why the QueryPart is runtime-only, with the emitter evidence: Discovery thread D.)

(The sections from here through "What dissolves" predate the method-graph sharpening and still say "QueryPart" for the SQL-side unit. Read it as shorthand for the method that emits that QueryPart at runtime, per the node-kinds section above; the normalization, natural-key, and anchor arguments are unchanged by the sharpening. Folding the wording through is part of the systematic pass.)

The leaf model is denormalized in textbook ways, and the pivot is its normalization:

R316’s (source, operation, target) is common vocabulary that carries well, but it is a per-coordinate summary row: a denormalized join over several independent facts, with operation crammed into a single slot. The entity is the schema coordinate (parentType, fieldName); the model is the coordinate together with its facts, each its own functional dependency:

source and target are two different facts, derived by two different walks (parent/edge versus the field’s type), and they vary independently: the same target List(Table) sits under a Root source or a Child source. Earlier drafts bundled them into one (coordinate, source, target) row and named it "the DataFetcher relation"; that let the DataFetcher, which is a view (a node kind, per the two library types are node kinds, not the top level), masquerade as the top-level relation. The honest form keeps the coordinate as the entity and source / target / operation as its facts. The DataFetcher is the view that joins source and target (and dispatches the operation set); the QueryPart-emitting methods are views over operations.

The three splits do not all have the same forcing function, and the spec should not pretend they do. operation had to split out: it is multi-valued, so one slot was a genuine 1NF / repeating-group fault. source and target are each single-valued and 1:1, so co-storing them was never a normalization violation; separating them is fact-independence (two FDs, two walks) and refusing to let a view name a relation, not a normal-form fix. Both separations are right; only `operation’s is forced by a normal form.

The corpus directive sits on the coordinate (the natural key), so it already annotates the right thing; its verdict generalizes from one triple to a source fact, a target fact, and a set of operation rows, each independently assertable.

operation is a set because its members are triggered by separate, walkable facts. Most are input-triggered, fired by an independent SDL or argument fact: a table-bound return type mints select, pagination args / a Connection mint paginate, @condition or filter inputs mint condition, @orderBy mints orderBy, @service mints serviceCall. One is relational: join is minted by the reference fact, that is, by the relationship between source and the value’s table rather than by an independent input (see The reference fact). The operation set is the union of these triggers. This is the schema-walk reading of the whole thesis: the leaf cross-product (Split x Lookup x Composite x …​) is what you get from collapsing independent operations into one slot, so they multiply into leaf variants; as a set they merely co-occur, and the cross-product dissolves additively. Composite falls out the same way: N columns are N (or one N-ary) select operations, arity gone as a coordinate dimension.

Normalization assigns each R316 axis to the fact that owns it (nothing in R316 is wrong, it just gets distributed); the read-by column names the view that consumes the fact:

Two refinements the flat triple hid. First, target is consumed by two views: its wrapper (Single / List, the output cardinality) is read by the DataFetcher, its shape by the select operation. The fact itself stays whole on coordinate → target (it is just the field’s type); the two views read the parts they need rather than the shape being duplicated onto the operation. Watch the embeddable-Column-as- Record case: a target shape becoming a child’s source shape is a coordinate-to-coordinate edge (the wrapper algebra), not an operation. Second, operation multiplicity is 0..N, not 1..N: a field that reads off an in-memory record (target shape Record / Field), and Nest, have a source and a target fact and an empty operation set; the DataFetcher’s existence is the fact, and a no-op operation row would buy nothing.

R316 slices 1-4 are the denormalized, singleton-row view (one coordinate, its source and target facts, at most one operation’s worth of facts) and stay valid as that projection. They are the empty-or-one case of the 0..N operation set.

Everything above is data modeling, and it has quietly adopted the whole vocabulary of a relational database: keyed relations, a foreign key (the coordinate), normalization (1NF on both repeating groups, the composite columns and the operation slot; 3NF on the split key-projection), and referential integrity (thread I’s closure-under-reference is exactly that constraint on the edge relation). Taken to its end this looks like rebuilding a database, which raises the question honestly: should the generator just use one? The answer is a deliberate split. Adopt the relational model as design discipline; do not adopt a relational runtime. The decision and its reasoning:

Reserved, and explicitly not "a database": if a pull toward a real engine ever becomes acute it will be an incremental, demand-driven memoized query architecture (the salsa / rust-analyzer model: edit the schema, recompute only the affected classifications), not a relational store. Its one concrete future trigger is LSP performance: the LSP already does incremental parsing and marshals a CatalogBuilder snapshot to the editor, and incremental reclassification is the natural next want. That is a separate, later question tied to LSP perf, deliberately not conflated with "sit the generator on a database," and out of scope here.

This is the working surface for the spec’s central open decision: which seams (named method-call edges) exist in the target lowering. Each row is one candidate node; the table is iterated as decisions land, and it is the denormalized roll-up of three things defined downstream in this doc, so read the columns against them: the naming regime is thread J (R1 = name minted once and read on both ends, R2 = formula reconstructed at each end), the seam verdict applies the seam-placement rule of thread K (a seam belongs where a unit is (a) chosen by a runtime strategy/dispatch, (b) reused across more than one caller, or (c) something we want to assert independently in the corpus or tests; inline only a linear, single-use, non-varying construction), and "folds into X" means the row is an arm-renderer that is part of node X, not a node of its own (thread K’s pair partition). The acceptance test for the finished table is thread I’s bidirectional closure invariant.

Rows 1 to 9 are the seams the generator already cuts (the migration baseline; full detail in Current seam topology below). Rows 10 to 11 are the decided new seams (the 2026-06-19 target topology of thread K). Rows 12 to 16 are the open surface: fragments inlined today whose promotion-or-inline verdict is what we iterate. This table is the back-half view of the coordinate’s operation relation; Operations are realized by seams below draws the member-to-seam crosswalk that wires the two together.

The two relational pictures in this spec are one model seen from its two ends, joined by the operation relation. The front half (the normalized schema above) keys facts on the coordinate and reads each operation off a trigger fact. The back half (the seam worklist just above, and the method-call graph of threads E to K) is the emitted side: named methods and the calls between them. A coordinate’s operation set is the set of QueryPart-emitting seams its query unit composes; the seam worklist is the back-half view of the operation relation, the same way the DataFetcher is the view that joins source and target.

The back-half seams sort into three layers, and only the middle one is the operation relation:

The member-to-seam crosswalk (the column the worklist deferred to here):

Two things the crosswalk makes visible. First, select lands on two seams (the projected column list in $fields, and the FROM/launch in the Query unit), the back-half echo of target being read by two views in the front half (wrapper by the DataFetcher, shape by the select operation). Second, the additive dissolution is now end-to-end: a coordinate’s operation set is a union of rows, each row is one seam, and "more facts trigger more operations" is "more seams composed into the one Query unit," never a new leaf variant. Composite’s N columns are N select contributions into the same Projection seam; arity is gone from both halves at once.

The bridge also closes thread I over both halves: the front half commits the operation set (which seams must exist), the back half commits the names (regime 1), and referential integrity is that every operation resolves to a committed seam and every seam traces back to an operation or a view. Thread I’s falsifiable test asserts that round-trip.

A query anchor is a coordinate whose DataFetcher launches a SELECT: a root field, or a split/new-query field. A query scope’s content is "the QueryParts addressed to it." Every QueryPart carries an address: the anchor whose SELECT it lands in. With that, the two cross-field flows from R316’s wrapper algebra become statements about QueryParts and anchors:

The address unifies composite and split: composite’s column QueryParts are addressed to the coordinate’s own anchor (same scope), split’s key projection is addressed to an ancestor anchor. address in {self, enclosing anchor} covers both.

This section is the derivation of the lead model above, not a refinement bolted onto a different one. The chain began from the narrower "one DataFetcher + one or more QueryParts" instinct, which is right about the resolve side but names the SQL unit one level too fine. A 2026-06-18 session walking the actual emitters sharpened it to the model this spec now leads with: the codegen command is the emitted Java method, and the full emit target is a referentially-closed graph of those methods. The threads below record the chain; each is a claim grounded in a current emitter, with the code coordinate that pins it.

A. SplitTableField and RecordTableField are component-identical (measured). Both records carry the same eleven components (parentTypeName, name, location, returnType, joinPath, filters, orderBy, pagination, sourceKey, loaderRegistration, parentCorrelation) and both implements TableTargetField, BatchKeyField (ChildField.java:446 and :798). The only divergence is two derived methods: emitsSingleRecordPerKey() (Record adds the || dispatch == LOAD_MANY disjunct) and sourceShape() (Split to Table, Record to Record, the switch at ChildField.java:66 vs :79). Nothing in the data distinguishes them; the distinction is which methods consume the leaf and what extra it owes.

B. Functional core / imperative shell; "commands" are the addressed output, not a third concept. R333 already gives every QueryPart an address (the anchor it lands in). That address is the imperative-shell instruction. Naming the lowered units "commands" adds nothing new to the model; it fixes the boundary: the core decides the entire emit, the shell renders and never assembles. The law is commands must be complete: the shell makes no decision the core could have made.

C. The two targets sit at different granularities; the field is right for only one. The DataFetcher is field-granular: one coordinate, one resolver, 1:1, total. FetcherEmitter binds exactly that. The field model’s 1:1 is correct here and stays. The SQL side is not field-granular, and (thread D) is not a query either.

D. There is no complete query at codegen. TypeClassGenerator emits one $fields(sel, table, env) method per table-bound type that assembles the SELECT list from a DataFetchingFieldSelectionSet at runtime. The projected columns are a per-request value gated by the client’s selection set. So the SQL-side command is not a static SELECT, and it is not an org.jooq.QueryPart: a QueryPart is the per-request runtime value those methods produce. This corrects "The two emit targets" above: the SQL-side codegen target is the method that emits QueryParts, not the QueryPart.

E. The command granularity is the emitted method. Reading the output bottom-up, the natural command unit is the Java method we emit, because a $fields arm is not independently renderable (it needs the method scaffold, the switch, the recursion). The minimal renderable unit is the method. The method-command kinds and their granularities:

$fields is type-granular and a fold: it absorbs its own scalar and inline fields, recurses through every NestingField into the nested type’s fields in the same method (TypeClassGenerator NestingField arm at :301-303; nested types get no own class, :146), and opts in the SourceKey columns that Split children need projected into this parent SELECT (collectRequiredProjectionColumns, :341). Granularity is heterogeneous across command kinds, and that is the point: each command sits at the granularity of the method it renders. The leaf zoo is what you get from forcing a single field-granular model to source all of these kinds at once.

F. Completeness is a graph property, because methods call each other by name. $fields is not compile-complete in isolation: an inline table-field arm inside X.$fields emits Y.$fields(…​) in its multiset projection (InlineTableFieldEmitter:123); the split rows-methods, the polymorphic path, and the lookup path all call <Type>.$fields(…​); and self-referential types make the graph cyclic (depth-2 self-reference, per `InlineTableFieldEmitter’s javadoc). So completeness splits in two:

"Making the code hang together" is exactly the edge-and-name computation, today scattered across the emitters as naming convention (rowsMethodName(), the hardcoded <NestedType>.$fields, scatterByIdx emitted once per class). The cut lifts the whole call graph (nodes, edges, and the naming scheme) into the core; the shell stops knowing any naming convention.

G. Two seams, do not conflate. The static call graph must be closed: that is compile-time completeness, the superset of every edge that could fire. The selection set prunes which edges actually fire per request: that is the runtime subgraph, client data, legitimately dynamic. The core owns the first entirely; the second stays where it is.

H. Normalization, restated for the graph. The emit target is two relations: a node relation (method commands keyed by method name) and an edge relation (calls, as name references). Closure under reference is referential integrity on the edge relation. Two keys bracket the function the core is: the input key is the schema coordinate (parentType, fieldName) (the model key, unchanged from above); the output key is the method name in the emitted graph. The core is the map from input key to a referentially-closed (nodes, edges) relation. The leaf zoo, the per-field QueryParts, and the emitter-computed edges are all denormalized or smeared views of that one relation.

I. Falsifiable invariant (the test this earns). Bidirectional, in the spirit of GeneratorCoverageTest: every method graphitron emits is the render output of exactly one command, and every method-name reference in every emitted body resolves to a command the core committed to, with no emitter minting a callee name. If an emitter ever computes a callee name the core did not hand it, the cut has leaked. This is the test that proves "the shell assembles nothing" rather than asserting it.

J. Naming authority is a measured spectrum, and both ends already exist in-tree. A 2026-06-19 trace of every emitted call edge sorts them by where the callee name is derived, which is what thread F’s closure turns on:

The R2 set is the worklist for thread F’s closure; the cut is "make every edge look like MethodRef / rowsMethodName, none like $fields." This makes thread I’s invariant grep-able: every $$fields, scatterByIdx, + "Condition", + "OrderBy", + "Fetchers" outside a single mint point is a current violation, so the test starts red and the migration drives it green edge by edge.

K. Seams, not the current emitters, define the target. The emitter inventory below, and any pair table read off it, describe the current seam topology, which inlines heavily and is therefore not the destination. A seam is a named method call: the one place an edge (and a regime-1 name) can exist. Inlining is the absence of a seam, producer and consumer welded into one body. So "add a seam," "promote an inlined fragment to a core-minted node + edge," and "make a new pair possible" are one statement; the seam topology is the node/edge relation of thread H, and designing it is the content of the lowering.

The current resolve side is asymmetric. The child path factors its query into a named unit (child fetcher to DataLoader to rows<X>, the rows-method being the select / from / where / orderBy / $fields assembly as a named method). The root path inlines that same assembly into the fetcher body (SelectMethodBody), with no rows<X>-equivalent to call. Root and child build the same query two ways; only child names it. The decided target (2026-06-19) closes that seam: both fetcher kinds become thin entry points delegating to one shared query unit, differing only in invocation strategy (root calls it directly; child calls it batched through a loader plus scatter). This generalizes the SplitTableField = RecordTableField shared-rows-method (the one existing instance of reuse-via-seam) into the organizing principle. Service-backed is the parallel arm: the fetcher delegates to a named service-call unit instead of inlining service.method(…​). The root path gains a level of indirection not required by runtime (no batching to justify it); paying it to buy uniformity, testability, and reuse is a deliberate, accepted trade.

Target topology, uniform across root / child / service:

Seam-placement rule. A seam belongs wherever a unit is (a) chosen by a runtime strategy/dispatch, (b) reused across more than one caller, or (c) something we want to assert independently in the corpus or tests. Inline only a linear, single-use, non-varying construction. On the jOOQ side, where jOOQ’s own in-language composition means a QueryPart can be an inline expression or a named method, we take the looser reading of (c): seam wherever the corpus might want to assert, accepting the parameter-threading cost (env, dsl, table, selection set across each seam), rather than reserving assertion for the query-unit level. The brake against one-method-per-QueryPart is that (a)/(b)/(c) must each be a real, named reason; "it is an expression" is not one. Testability is the through-line: an inlined fragment is assertable only through the whole query that contains it, a named query-part unit is independently assertable and is a clean regime-1 edge by construction, so "more seams," "more testable," and "more decoupled pairs" are the same axis.

Every active directive declares a behavior the model must lower, so the model is complete exactly when every directive’s effect has an owning fact. This is the audit that drives the remaining work: walk the directives, map each to its owning fact, and the ones with no home are the gaps. (The retired directives, @record / @notGenerated / @multitableReference / @enum (R360), are parser-only stubs the classifier rejects; they own nothing by design.)

Owned by an existing fact:

Planned, not yet a directive: @capability / @exemplifies will own a capability_tag(coordinate, slug) relation plus the slug namespace (a third referenced namespace; see Provenance, description, and capability). They are read by the knowledge surface, not by code generation, and the audit will list them in the table above once they ship.

The gaps, in resolution order:

In scope: the model (the lowering to a referentially-closed method-call-graph, the normalization, the natural keys, the anchor/address primitive, the node and edge relations, the coordinate-and-its-facts normalized schema (source / target / operation as independent functional dependencies, plus the reference / referencedTable / derived resolvedTable / tableExpr facts and the (coordinate, path) input-coordinate fact family whose facts roll up into the output operation set, the read-side source object (type-level cast target) and accessor (field-level locator, no transform axis) facts, the node facts (NodeType / NodeKeyColumn plus the per-coordinate key projections, with the codec entailed and identity-carrying paths deciding whether the read stays projection-only or rides a join), the enum facts (authored value set plus a derived EnumBacking backing-type roll-up driving a synthesis-time lift, @enum retired), the DataFetcher and QueryPart-methods as views over them), the target seam topology and its placement rule, and the decision to materialize the relations as typed in-type collections with a referential-integrity check rather than on a query engine). Out of scope: the emit re-platforming that consumes it (R314), any rewrite of R316 slices 1-4 (they are the valid denormalized projection), and any incremental-query engine for the LSP (a separate, later perf question). No code in this item beyond what is needed to make the model executable as tests, and that split is now decided (2026-07-04): the Ready code deliverable is thread I’s closure oracle at level 1, a characterization harness over the current emit that walks the generated TypeSpecs, collects declared method names and intra-generated call references, and asserts every such callee resolves to an emitted method (R410’s TypeSpecReferenceWalk is most of the walking machinery). Level 1 is valid before any re-platforming and survives it as the harness. The bidirectional form (every emitted method is exactly one command’s output; every callee name resolves to a committed command) needs the command/name registry and lands with the emit slices, first populated for the reentry family by R314.

Surfaced 2026-06-18 while researching a claim that SplitTableField is a variant of RecordTableField that should dissolve. The emit trace refuted the literal "source is a record" reading (split reads a live catalog row) but confirmed the structural kinship (identical record components, shared batch-load machinery). Pressing on "what is the real difference" produced the double-duty observation (split also injects keys into the parent SELECT), then the parent-projection-as-up-flow relation, then the insight that reifying it as a separate node dissolves the relation, and finally the normalization framing: the node is a QueryPart, the SDL field is the natural key, and the leaf zoo is a denormalized view. The chain is preserved in the R316 design discussion of the same date.