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 was executed by the R549 (facts-and-commands) programme (Done 2026-08-01; see roadmap/changelog.md), which consumed this model slice by slice after R314 (Done) shipped its reentry beachhead; the front half (the operation relation materialized as walked facts, dissolving the classifier’s operation-encoding leaves) was delivered by the R563 (operation-relation) programme (Done), as the OperationMember per-coordinate member multiset. The model now also has a second, executable home: the fact schema DDL in the graphitron-model module (R595) is this document’s normalised data model reified as a SQL schema, and the classification-stage derivations over it are R589’s subject. The stabilized why is migrating out section by section to docs/architecture/explanation/fact-model.adoc (a migrated section keeps its heading with a pointer body); suggested reading order is that page and this orientation, then The model (the ER diagram and the fact catalog), 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, OperationMember, 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 has an executable home, and the division of labour is explicit. The fact schema DDL in the graphitron-model module (R595) is this normalised model reified as SQL: the shipped families (graphql_ total transcription, graphitron_ decoded directive semantics, sql_ catalog, jvm_ classpath, store_ bookkeeping, javac_ compile diagnostics per R603, with graph_name leading the SDL-family keys per R610) carry the base relations, and the derived stratum (the claim views, resolution, reachability, demand, the diagnostics relations) lands consumer by consumer per R589’s strangler frame. The stage vocabulary over that home is three verbs, each stage only ever adding rows: classification gathers* (capture loads the base relations and the claim views read them), validation derives (a violated constraint becomes a located violation fact; the claims stay), and *planning joins facts directly into command records, which are the parse targets. This document keeps the why not yet migrated: the stabilized why moves section by section into docs/architecture/explanation/fact-model.adoc (a migrated section below keeps its heading with a one-line pointer as its body). The what migrates into the DDL relation by relation, and where prose and DDL disagree the DDL wins; which relations exist at any given moment is the DDL header’s record, not this document’s, so a reader should not expect a relation per deep-dive yet.

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 shipped half of this key system (Name-column natural keys per relation, the rendered coordinate, the definition-keyed / use-keyed split) migrated to docs/architecture/explanation/fact-model.adoc, section "The key discipline"; the five-kind sealed coordinate carrier and the mechanical never-a-stored-surrogate rule below are target-state and stay here until a carrier and a gate exist.

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. One reconciliation with the DDL: the capture schema stores output fields and input-object fields in a single graphql_field relation keyed (type_name, field_name), with the owning type’s kind distinguishing them by join. That is not the single-table inheritance this section argues against, because every key column is non-null and no column is populated-by-kind; the five-variant discipline governs the Java-side coordinate, while the capture relations key on the spec grammar directly and let the kind fall out of the type row.

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. The definition-keyed / use-keyed discipline this paragraph carried (authored facts at the definition member coordinate, use-site resolution a derived join over definition and consumer) migrated: see "The key discipline" in docs/architecture/explanation/fact-model.adoc.

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.

Migrated: the one-base-many-views layering, code generation as the narrowest view, and the re-sourcing invariant live in docs/architecture/explanation/fact-model.adoc, section "One base, many views". What stays here is the test-side obligation not yet discharged: the @classified corpus (ClassifiedHarness, CorpusDocuments.coveredLeaves(), VariantCoverageTest) still builds its verdict from the leaf zoo, so the harness is in scope for the re-sourcing and its coverage net needs restating once leaves are not the unit; widening the corpus directive to the fact set is filed separately.

Three facts test the relational instinct that a fact’s origin is not automatically a column on the fact. The instinct and its shipped exemplars migrated (the Provenance and Description stubs below); Capability stays, because its directives are reserved, not shipped.

The three recurring derivations this section named migrated; the stubs below point at their new home.

Migrated: the model statement (a schema coordinate is the input key to a lowering whose output is a referentially-closed graph of emitted Java methods; the leaf zoo, the per-field "graphitron field", and the two library types are denormalized or partial views of that one graph) lives in docs/architecture/explanation/fact-model.adoc, section "The back half: complete commands, a closed graph". The derivation chain, and the narrower superseded headline this section replaced, are recorded in Discovery below.

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.

Migrated: the discipline’s executable form (typed jOOQ access generated from the store’s own DDL, the declared-FK versus detection-query split of referential integrity, the no-migrations lifecycle with compile time as the only compatibility surface) lives in docs/architecture/explanation/fact-model.adoc, section "The discipline has an executable form". The argument-by-argument reversal record of this section’s original "no engine" answer is preserved in the git history; the spike measurement stays citable at roadmap/audits/2026-08-05-fact-base-h2-spike.md.

What stays: the back half remains outside the store’s ambitions. The emit side is imperative JavaPoet rendering that no engine makes easier, so the store carries the classification (front) half and the command relations, and determinism is owned at the emission boundary (whatever crosses into emission or diagnostics output is sorted at the crossing). The salsa-style incremental-memoization architecture this section once reserved is the road not taken: capture reads the type-definition registry (the linear half of graphql-java, never the superlinear assembly), and the warm-start cache is the surviving concession to LSP startup latency.

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; both landed in the R549 window). Rows 12 to 16 were the open surface: rows 12 to 14 closed as command data, rows 15 to 16 remain the fragments whose promotion-or-inline verdict is still open. 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):

(The naming-regime column was refreshed 2026-08-01 against the landed R549 state; every operation seam is now regime 1.) The mapping debt this crosswalk once owed is paid: R563 (Done) delivered the member vocabulary as code, the OperationMember per-coordinate member multiset, with the MEMBER_ARMS / MEMBER_KNOWN_GAPS obligation pinning arm coverage; this table stays the seam vocabulary those members map onto.

Two things the crosswalk makes visible. First, select lands on two seams (the projected column list in $project, 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. The line numbers were measured 2026-06-18/19 and drift with trunk; the class and member names are the stable citations (all re-verified live 2026-07-13). Since then the R549/R552/R563 programmes retired several of the walked emitters and carriers, so the threads and the baseline tables below are lineage, read with this mapping rather than re-anchored line by line: TypeClassGenerator and collectRequiredProjection became render/ProjectionUnitRenderer over plan/ProjectionCommands, and the emitted projection method was renamed $fields(sel, table, env) to $project(grouped, table, env) in the same re-platforming; the per-arm Inline* projection emitters (InlineColumnReferenceFieldEmitter, InlineTableFieldEmitter, InlineLookupTableFieldEmitter) dissolved into ProjectionUnitRenderer’s command-driven arms; `TypeConditionsGenerator became render/ConditionGlueRenderer, and FkTargetConditionEmitter became the model record FkTargetConditionFilter rendered via ConditionCommands; LookupValuesJoinEmitter became the render values-join family (LookupRows); the main-source methodgraph package was deleted (the recompile graph is a typed projection over the plan; the test-side oracles survive); ParentProjectionContainmentCheck was deleted with it; SplitTableField / RecordTableField merged to BatchedTableField (R432) and the ColumnField family to ColumnBackedField (R508); the Operation seal became the OperationMember member multiset (R563). The claims the threads ground stand; the pinned coordinates are of their date.

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 (collectRequiredProjection). 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 (TypeFetcherGenerator’s root builders; a 2026-07-26 code walk corrected the earlier `SelectMethodBody attribution, that class being the already-named entity-dispatch unit), 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, are parser-only stubs the classifier rejects; they own nothing by design. @enum is still honored today: its retirement is decided by this model (Enum facts) but filed as R360, Backlog, so until that ships its effect is owned by the enum facts as the authored backing they supersede.)

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 input-coordinate fact family (definition-keyed authored facts, use-site resolution over the derived occurrence path) 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 retirement decided, filed as R360), the DataFetcher and QueryPart-methods as views over them), the target seam topology and its placement rule, and the materialization decision as re-resolved: the relations live in the graphitron-model store, reified from this model’s DDL, with integrity split between declared FKs and detection queries). Out of scope: the emit re-platforming that consumes it (the R549 programme; R314 shipped its reentry slice), any rewrite of R316 slices 1-4 (they are the valid denormalized projection), the substrate itself (R595) and the classification-stage derivations over it (R589), and any incremental-query engine for the LSP (the road not taken; R595’s warm start is the concession). 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 the same walking pattern at file granularity). 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) needed committed names in main source. R314 (Done) first landed them as a dedicated command/name registry (the main-source methodgraph package); the R549 programme then re-sourced the closure onto the command relations themselves and retired that registry (2026-07-30): the relations' minted unit addresses (GeneratedUnits) are the committed names, and the closure joins bidirectionally through the re-sourced tests (LauncherRelationClosureTest and the level-1 MethodClosureOracleTest, both still in the test-side methodgraph package).

Landed (2026-07-14): EmittedMethodClosure (the walk: node relation = declared methods keyed by unit + nested-type path; edge relation = statically-qualified generated-to-generated callee references, resolved through the rendered import list / same-package / FQCN the way javac binds them, with comments and string literals blanked) plus MethodClosureOracleTest (pipeline tier, no.sikt.graphitron.rewrite.methodgraph), generating over a schema that spans the seam-worklist families (root select, child reference, @splitQuery, connection + @orderBy, @lookupKey, @nodeId filter conditions, nesting, table-bound @service and DML reentry, jOOQ-record service input) and asserting closure plus per-family non-vacuity floors on both relations. EmittedMethodClosureTest (unit tier) pins the scanner’s falsifiability: a dangling callee turns the oracle red; javadoc prose, string literals, constructors, enum-constant reads, and non-generated qualifiers do not. Documented level-1 blind spots, both closed by javac in the compilation tier and by the level-2 registry later: unqualified same-class calls (the rows-methods, scatter, order-by, record-instantiation helpers ; pinned as nodes instead) and instance calls through variables.

Reviewed (2026-07-14, In Review pass): the level-1 oracle is approved as shipped at 446ad39 (full reactor green under -Plocal-db; both test classes executed, closure and non-vacuity floors hold; the fresh scanner is the right call since R410’s TypeSpecReferenceWalk is type-granular, not method-granular). The item returns to Ready rather than Done-and-delete because the code deliverable was one phase of a still-live artifact: this document remains the governing model (R222 Relationships: "this document governs the model") consumed by R431 / R432 / R314 / R222, whose specs cite its sections by name and whose depends-on names its slug; the seam worklist is a living table iterated as those slices land; and the body names its own remaining pass (folding the pre-sharpening "QueryPart" wording through the sections from Normalization to What dissolves). Done-and-delete follows when the emit re-platforming no longer consumes the document or the stabilized model migrates out: to docs/architecture/, or into the graphitron-model DDL, the door R595 opened. The what is already migrating relation by relation; the why recorded here is the last content standing, and its eventual home is the architecture docs.

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.