Refuse a routine write’s first-hop condition instead of deferring it

The Backlog body asked three questions and answered none of them. All three are answerable by reading the tree, and the answers move the item.

Can the schema be written? Yes. A first path element {table: "rental", condition: {...}} resolves: BuildContext.parsePathElement’s `table: branch resolves the condition: to a JoinConditionRef, sees the departure node is a table-valued function, and hands the filter to synthesizeNameMatchedJoin, which builds an On.ColumnPairs hop carrying it. So hop 0 is a key-paired hop with a non-null filter(), which is precisely the shape the Backlog body suspected nothing looked at.

Does anything reject it? Yes, and it is the verdict the body assumed was blind to it. FieldBuilder.classifyMutationRoutineChain’s re-read-anchor verdict tests `!(hop0.on() instanceof On.ColumnPairs) || hop0.filter() != null, so the filtered arm and the condition-joined arm both land an UnclassifiedField. GraphitronSchemaValidator’s `validateUnclassifiedField turns that into a ValidationError through ValidationError.forField, which prefixes Field '<Type>.<field>': and carries the field’s SourceLocation, and GraphQLRewriteGenerator throws ValidationFailedException on a non-empty error list. The build fails, at the coordinate, before anything is emitted. Nothing is silently dropped.

Is the fix a located rejection? The location and the coordinate are already there. What is missing is everything else about the diagnostic, and one taxonomy claim behind it.

So the item is no longer an investigation. It is a diagnostic-quality and kind-correctness fix whose scope the read has pinned exactly.

RejectionKind’s own rule states the line: `DEFERRED is for a shape that is "legitimate; support is absent, not structurally impossible". The general mechanism that makes a hop-0 filter emittable is to join the departure table into the query as an alias, so the filter method has something to receive as its first argument. An ordinary single-table child field does exactly that: ParentCorrelation.OnParentJoin joins the parent’s own aliased table in and keys the batch by the parent’s primary key, so a hop-0 filter there is supported, not refused.

That mechanism is unavailable to a routine write, and the reason is the family’s defining rule rather than a missing feature: the routine appears in no statement after the one that ran it, because re-invoking it would re-execute the write. The departure table cannot be joined into the re-read at all, so the filter method’s first argument has nothing to bind against, at any level of generator effort. `RoutineWriteCommand.RereadAnchor’s javadoc already states this, and states it as structural.

The tree already refuses the same shape, for the same reason, at the two other sites where the departure side is not a joined alias, and both use Rejection.structural:

One rule, three sites, and the routine-write site is the only one filed as a deferral. Matching the other two is the whole design decision, and it extends a shape already in the tree rather than inventing a taxonomy.

A caveat worth stating so a reviewer can disagree with it deliberately. A filter could be evaluated inside the transaction, in the capture statement, by joining the arrival table there and filtering the captured keys before the commit. That is expressible. It is also a different feature wearing the same spelling: everywhere else condition: filters the rows of the enclosing query, and at this one position it would filter the keys of a pre-commit statement instead. Admitting the spelling later would mean it silently means something else here than it does everywhere else, so the deferral promise should not be kept open for it. If a reviewer wants that feature, it is a new Backlog item with its own spelling, not this one’s emission.

FieldBuilder.classifyMutationRoutineChain. Split the one conflated verdict into the two shapes an author can actually write, each Rejection.structural, keeping the check itself where it is (immediately after the Connection verdict, reading walk.steps().get(0)). Both messages state the mechanism in the author’s own vocabulary and give the fixes; neither repeats the coordinate, which ValidationError.forField prefixes.

For a first element that joins by condition: alone (On.Predicate): say the element joins by condition:, that the method’s first argument would be the routine’s own result, that the result cannot appear in the query that runs after the commit because re-invoking the routine would run the write a second time, and that a first element must name a key or a table so the write has key columns to capture and re-read by. Steer to moving the predicate onto a later element.

For a first element carrying a condition: alongside key: or table: (On.ColumnPairs with a non-null filter()): say the element carries a condition: filter, give the same reason, and add what it costs, which is that the filter would be dropped and the field would return rows the predicate should exclude. Steer to dropping the condition: or moving it onto a later element, where both of the method’s tables are joined into the re-read.

Keep the verdict total over On. The single condition it replaces is total by construction (!(hop0.on() instanceof On.ColumnPairs) catches everything that is not column pairs), and two hand-written arms are not, so write it as a switch over hop0.on() and give On.Lateral an arm of its own: a first element resolving to a second routine call, which the re-read cannot depart from for the same reason. That arm fires for nobody today, the one-routine-per-chain rule refusing a second @routine earlier and walkRoutineChain adding a lateral hop only where a running source exists, so it is there to keep every reachable shape on a located rejection rather than on the leaf’s IllegalArgumentException if either of those rules moves.

Per the javadoc conventions, neither message nor either comment cites a roadmap item; the prose names the live symbols and states the fact.

RoutineWriteCommands.anchorOf. The produce-time guard goes here, as the third assertion on a row that already carries two of the same family. The seat has a history worth stating, because the plan has been on both sides of it: the first draft put the guard here, the Spec review moved it to MutationField.MutationRoutineWriteField’s compact constructor for reasons that were correct against the tree at the time, and the tree has since moved out from under both. The re-read is now produced from `RoutineWriteFacts.Row, a store read, and TypeFetcherGenerator.renderRoutineWrite says of the leaf that this shell "reads the leaf for its name alone; everything the body says, the connection it acquires included, comes off the plan". The leaf’s hops reach no emitted statement, so a pin on its compact constructor would assert a shape nothing downstream consumes.

anchorOf is where the predicate would be lost. It reads hop 0’s table(), alias() and pairs and never looks at filter(), while tailOf carries filter() through for every hop after 0. It is also an assertion site now rather than a decode: it throws on an empty hop list and on a hop 0 whose basis is not JoinBasis.ColumnPairs, both as an IllegalStateException naming the coordinate and reading as a generator bug. Add the third in that voice, on a hop 0 with a non-null filter(), saying what the shape would cost: a re-read that drops the author’s predicate and returns rows it should exclude. The javadoc paragraph that used to disclaim this site as an assertion site is gone from the tree, so the argument that ruled the seat out is gone with it.

The producer-side narrowing that docs/architecture/principles/development-principles.adoc’s acceptance rule asks for is already in place on the path that matters, and it is the store’s. The seat relation gives this shape the `UNANCHORED_FIRST_HOP verdict, and RoutineWriteFacts.read admits ADMITTED rows and nothing else, so no filtered hop 0 reaches the plan tier at all. The new assertion covers the residual, a regression in that view’s CASE or in the hop resolution beneath it, which is exactly what the two assertions beside it cover.

No pin is added to MutationField.MutationRoutineWriteField, and its own account of this shape is corrected as prose instead. Three claims there are stale, two of them by this item and one already: its javadoc and the comment above its hop-0 pin say the re-read-anchor verdict "routes every other shape to a typed `Deferred`", which this item falsifies, and the same two sentences say the emitter’s key capture reads the pin’s pairs and narrows "on this pin’s authority", which the store read falsified before this item existed. Restate them as what the leaf actually guarantees: the classifier admits no other shape, and the pin is the leaf’s own account of its chain rather than the emitter’s authority for anything. `GraphitronSchemaValidator’s switch-arm comment needs no edit after all, since it enumerates the leaf’s pins and the leaf gains none.

`RoutineWriteCommand.RereadAnchor’s javadoc already calls the filter’s absence structural rather than an omission, and needs no edit. What changes is that the absence becomes asserted where the anchor is produced.

intent_mutation_routine_seat’s verdict comment (graphitron-model/src/main/resources/no/sikt/graphitron/model/graphitron-model.sql). Its closing sentence partitions the fourteen verdicts into the ones an author fixes and the ones the generator owes an emitter, and it lists `UNANCHORED_FIRST_HOP among the latter. Move it to the author-fixable list, so the store’s own account and the rejection kind agree. The verdict name and the view’s CASE logic do not change: the view keys off the first chain node’s step carrying a class_name, which covers both authored shapes and is correct as it stands.

docs/manual/reference/directives/routine.adoc. Delete the first-hop sentence from the Deferred write shapes section and state the rule as a constraint instead, in the == Constraints list where the other hard "no"s live, with the two fixes. The other three deferrals in that section (procedures, scalar and void routines, the hop-less Mutation @routine) are genuinely awaiting an emitter and stay.

GraphitronSchemaBuilderTest. The existing mutationRoutineChainWithConditionJoinedHopZeroDefers pins only the condition-joined arm and asserts Rejection.Deferred. Rename it to say it is refused rather than deferred, flip the assertion to Rejection.AuthorError.Structural, and anchor it on a fragment of the new prose. Add its sibling for the arm this item exists for: a first element {table: "rental", condition: {…​}} out of rent_film, asserting the structural arm and a fragment naming the filter. That sibling is the fixture the Backlog body said this item should own; today the shape is covered nowhere at the classifier tier, only through the derived view.

MutationRoutineSeatTest.anAuthoredConditionOnTheFirstHopLeavesTheReReadUnanchored already uses exactly this SDL and stays green untouched: the view’s verdict name and logic do not change. Worth naming here so a reviewer sees the two tiers are deliberately asserting different things, the classifier’s rejection and the store’s verdict.

The anchorOf assertion carries no test, and the reason is the seat rather than an exemption. Reaching it needs a store row the seat relation admits with a filtered hop 0, and the view refuses exactly that: the UNANCHORED_FIRST_HOP arm fires on the first chain node’s step carrying a class_name, which is where the filter comes from, so there is no fixture that reaches the throw without first breaking the view. Its two siblings on the same row are untested for the same reason, and no test asserts either today. That is what the generator-bug voice is for, and it is why the coverage that matters is at the classifier tier, where the two GraphitronSchemaBuilderTest cases above prove no such leaf and no such store row is produced in the first place.

RejectionKindProjectionTest needs no change (the projection is per-arm, not per-site), and neither does the diagnostics glossary, whose deferred entry describes the kind and enumerates no shapes.

The verification build is the full mvn install -Plocal-db: the SQL comment change touches the model module every downstream module reads, and the .adoc change renders in the docs module.

Nothing symbol-level is retired. What is retired is the claim that this shape awaits an emitter, and it survives as prose in four places rather than as code, so the sweep needs a query that reaches all four. Two of them carry no phrase from the author-facing surfaces and would be missed by a sweep built from those alone:

Alongside the two that the author-facing phrasing does reach:

The sweep query that reaches all four is the verdict’s own name rather than the deferral prose: grep re-read-anchor verdict, re-read anchor and derivable re-read across main and test sources plus the .adoc tree, and read every hit for whether it still claims an emitter is owed. The third term is what reaches the first surface above: that javadoc wraps the phrase as "no derivable re-read / anchor" across two lines, so a line-based grep for the second term alone misses it. Grepping "Deferred" near "routine" also works and is noisier, the sibling deferrals in that family (procedures, scalar and void routines, the hop-less Mutation @routine, the multi-routine chain) being genuine and staying.