The stated key-column match spends its ambiguity silently; make it state its arity

The Backlog body left one question open: whether the key-columns constant’s spelling is catalog-canonical in the same sense the crawler’s own column reading is. If it were, the fix would be deleting four UPPER calls; if it were not, sql_node_key_column.column_name would earn a folded companion under the ordinary rule. The tree answers it, and the answer is the second branch.

JooqCatalog.reduceNodeMetadata fills an entry name with field.getName() on the entries of the Field<?>[] the constant holds, and does not resolve that field against the table it is standing on. JooqCatalog.columnFactsOf fills sql_column.column_name with col.getName() off the table’s own generated field constants and jooq_name with the reflective Java field name. So the two strings are byte-identical exactly when the constant references the table’s own field constants, which is what Sikt’s KjerneJooqGenerator emits, and are unrelated otherwise: an entry holding a DSL.field("id") or a field belonging to another table yields whatever spelling that field carries. The store records the entry as stated precisely so it can hold a name belonging to no column, which is the whole reason sql_node_key_column declines a foreign key to sql_column.

The argument form matters, because the common case points the other way. Almost always the constant does reference the table’s own field constants and the two strings are identical, and reasoning from that would settle the question wrongly. The case where the derivation fails is what decides it, and one example is enough. The schema reached the same answer before the question was asked: that foreign key is declined because "the constant spells a column by name and may spell one the table does not have", which puts the column on the spelled-reference side of the structural-versus-spelled split. A spelled reference is not a catalog reading.

An entry name is therefore a stated name, sql_node_key_column.column_name earns a column_name_upper companion under the ordinary rule, and no amendment to where folds are minted is needed.

The Backlog title, "the store folds two catalog-produced names as a hedge; make the comparison exact", is wrong in both halves as a result: the operands are not both catalog-produced, and exactness is what the match falls back to rather than what it becomes. A third word went with them in this revision. The fold is not a hedge at all. A hedge is a fold with no crossing under it, which is R702’s subject; this one bridges a spelled reference and a catalog reading and is the semantic the rule exists to serve. It stays, unconditionally. What is wrong is that the match spends an ambiguity without saying so, and the title and slug now name that instead.

One doc hazard this creates is handled in the Implementation below rather than discovered later. After the column lands, both operands of the match live in the sql_ family, and seven shipped _upper comments carry the same sentence: "Two values of one family are compared exactly, and a comparison that does want a fold on both sides reaches this column by joining …​ on its key rather than by having it forwarded through a derived view." They sit on sql_table (two), sql_column (two) and sql_constraint (three), which is every _upper column the sql_ family has. A reader arriving at the new column with that rule in hand deletes it.

The rule is wrong as stated rather than merely incomplete, and the word doing the damage is family. The discriminator was never the relation prefix: it is whether a value is a reading of the thing it names or a name spelled at it. Both operands here are sql_ and one of them is a spelled reference, which is the split the missing foreign key already stands on. The family holds facts about generated Java classes beside facts a database produced, sql_node_metadata sitting under sql_ because it shares a refresh unit with sql_table rather than because a database produced it. So the fix is to say catalog readings where those comments say values of one family: one phrase in seven places, after which the new column is obviously not an instance of the rule rather than an exception to be argued.

Two further facts the design leans on. FactSink.claim keys its dedupe set on a plain HashSet of the key values, so "Id" and "ID" are two distinct sql_column rows and the store can hold the collision at all. And the reading side this view mirrors, JooqCatalog.findColumn, matches the Java name case-insensitively and then the SQL name case-insensitively, each with findFirst, so on a colliding table it silently picks by reflective field order. That is the behaviour the store is meant to replace, not the behaviour it is meant to reproduce.

This is not a new axis for the fold rule, and framing it as one would be both wrong and a weaker argument. The fold stays entirely unconditional: every folded match becomes a row, exactly as intent_bound_table makes every candidate table a row. What is conditional is a verdict a consumer computes from arity, which is the discipline the schema already applies wherever ambiguity has a relation to sit on. Ambiguity is rows, never a decline, and the count says so; intent_bound_table.candidates and intent_name_matched_key_pair.unmatched_columns are that rule written down. This comparison never got the arity column because it was buried in a NOT EXISTS where arity had nowhere to surface, and that is the whole defect. No general statement about conditional folds is needed, and none should be added.

The schema has done this shape before at another site, which is the precedent to follow rather than invent against: intent_field_reference_step_hop already encodes SQL-name-wins precedence over the jOOQ name in SQL, through a NOT EXISTS, and carries key_matched_by as a closed-vocabulary column.

Three pieces:

The pairing relation. A new view intent_stated_key_column_match at grain one row per (key-column entry, sql_column row it could be). The grain is per column and not per (column, spelling) pairing: a column whose SQL name and Java name are both the sought name must be one row and not two. The join condition being a boolean rather than a row source gives that for free, so no DISTINCT is involved. Every exact match is also a folded match, so the folded predicate is the join and exactness is a projection over it, never a second arm.

Arity is stated as columns, not left to the reader: candidates (how many columns answer at all) and exact_candidates (how many answer on an exact spelling), both window counts over the entry’s partition, with the inherited-window caution the schema’s other arity comments carry. A boolean would not be enough, and the case that proves it is reachable: on a quoted-identifier catalog, column A can be exactly Id on its jooq_name while column B is exactly Id on its column_name. A some-row-matched-exactly test calls that resolved and hands the pick back to whoever reaches a column first, which is precisely the failure this item exists to stop. Two counts express it; one flag cannot.

The relation deliberately does not carry which spelling matched, and deliberately replaces findColumn’s Java-name-first precedence with exactness rather than reproducing it. What that costs has to be stated exactly, because the tempting claim is the wrong one. The two rules agree on every table whose column spellings, Java and SQL names taken together, are case-insensitively distinct: exactly one column can answer at all there, so both rules return it. They diverge only where two columns collide under the fold, which is the population this item exists for. They do not diverge only on the inputs the arity columns call malformed: a table where one column answers exactly and a second answers only folded has two candidates and one exact, resolves with no defect, and resolves to the exactly-spelled column where `findColumn would have taken the Java-name match. That is a deliberate behaviour change on a colliding catalog rather than a divergence to apologise for, and the statement of it belongs in the view comment; it is the load-bearing half of the relation’s justification. It exposes no _upper column either, so the rule that a derived view never forwards a fold holds.

What earns the relation, given that it will have one view reading it. An earlier revision argued two readers, R668’s tier being the second; R668 has since settled and does not read it, so that argument is dead and is replaced here rather than quietly left standing. One reader is the shape this schema otherwise answers with a CTE, so the question is real.

The load-bearing answer is that a CTE would state the arity where nobody can read it. This schema’s rule for an ambiguity is not that a count exists but that the witnesses are rows; intent_name_matched_key_pair.unmatched_columns says so outright, a consumer explaining a refusal reading the rows behind a number above it, and intent_bound_table offering every candidate to an editor is the same rule. A KEY_COLUMN_CASE_AMBIGUOUS row says a table is malformed and says nothing about which columns collided, which is the question anyone who hits it asks first. Shipping a verdict whose witnesses are sealed inside the view that reached it would reproduce, one level up, exactly the defect this item exists to remove: an answer with nowhere to put what it knows.

The resolution being spelled more than once is a second argument and no longer the main one. It stays spelled in Java by JooqCatalog.findColumn, which is R729’s, and intent_resolved_node_key_column.column_name forwards the stated spelling onward to intent_resolved_node_key_projection, which R668 has landed, and to an emitter that eventually needs a real column; that column’s comment explicitly declines to perform the match, "settled convention rather than this relation’s rule". Lifting the defect view’s own copy out takes the SQL count from two to one rather than to zero, which is worth stating plainly rather than claiming a sweep.

The gated arm. intent_node_metadata_defect’s entry arm stops reading columns and reads the counts: an entry resolves when `exact_candidates = 1, or when exact_candidates = 0 AND candidates = 1. KEY_COLUMN_UNRESOLVED keeps its meaning exactly, no column answers at all.

The new defect value. KEY_COLUMN_CASE_AMBIGUOUS, the complement: more than one exact candidate, or none exact and more than one folded. One arm covers both shapes because the arity columns make them one condition. It is a distinct value rather than a reading of KEY_COLUMN_UNRESOLVED because that value’s meaning is already fixed by the message the live probe composes from it, references column 'X' which does not belong to this table, and on a colliding table that sentence is false: case-variant columns do exist and the entry names none of them exactly.

That value changes what well-formed metadata means, and that has to be stated rather than treated as a message refinement, because well-formedness has consumers. intent_resolved_node_key_column’s `JOOQ_METADATA tier gates on a table having no defect row at all, so a case-ambiguous entry stops that tier resolving and falls through rather than resolving against a column picked by field order. That is the payoff, and it needs no edit to that view. intent_inferred_node_type shipped while this item was in Spec and stands on the same conjunction, so a case-ambiguous key column also stops the type being an inferred node. Both are the right answers and both are semantic changes this item owns.

Neither consumer needs editing, and the reason is worth stating so nobody goes looking. Both gate on a table having no defect row at all, with no filter on which value, so a new value reaches both by construction. The schema also deliberately accepts two spellings of that conjunction rather than extracting it, each view’s comment naming the other as its sibling spelling, so the count of value-agnostic gates is already two and would keep growing. That is what makes the propagation worth a pinned case rather than an observation: a gate that inherits a new value silently is exactly the kind that nobody notices has changed.

The Java enforcer. The store’s verdict needs one or it is a fact with no teeth. JooqCatalog.validateLookup resolves entries through findColumn, which folds and takes findFirst over the reflective field order, so without a Java-side change the store would report a table malformed while the shipped generator quietly picks a column and emits against it. A store verdict the build does not enforce is the drift this project treats as a smell.

The enforcer mirrors the relation rather than inventing a second rule, which is what stops the two sides drifting apart the way the folded predicate already did. validateLookup’s `columnLookup argument stops returning one column and starts returning every column that answers the name, and validateLookup computes the verdict from that list exactly as the defect arm computes it from the counts: one exact candidate wins, a single folded candidate wins where none is exact, anything else is Malformed. The list has the relation’s grain, one entry per column and not per spelling, which falls out of walking the table’s fields once. An Optional cannot carry this, and that is the real reason the signature moves rather than a convenience: the existing empty case already means no column answers and composes the sentence that says so, and telling an ambiguity apart from it is what stops that sentence being printed about a table whose columns do exist.

findColumn is not touched and neither are its other callers. They carry the same silent pick, and that is R729, filed off this item’s analysis. This item leaves one worked example of the rule rather than a sweep, and depends on nothing.

Nothing generated needs regenerating by hand. The schema reference under docs/architecture/reference/schema/ is rendered from the DDL and its comments by the docs module’s render-schema-reference execution, so the new relation documents itself.

graphitron-model/src/test/java/no/sikt/graphitron/model/intent/NodeMetadataDefectTest.java is the home; it seeds rows directly, which is what lets a colliding catalog be stated in two lines rather than shipped as a broken generated class.

All the store cases are seeded rows, not crawler fixtures. The class javadoc already argues why: reaching these states through a crawler would mean shipping a broken generated class into the fixture tree for each of them, where stating them takes a line. Said here so the implementer does not try to manufacture a quoted-identifier collision inside the sakila catalog.

WrittenStatementCoverageTest covers the write function without a new case: it enumerates the relations the catalog reports a computed column for and round-trips a distinct value per writable column.

If the exact-first decision turns out hard, what defers is that predicate plus the new defect value plus the Java enforcer, together, and what lands is the folded column, the pairing relation with both arity columns, and the entry arm rewritten to read it with today’s semantics: a defect exactly when candidates = 0. That intermediate is coherent on its own terms. There is one spelling of the resolution instead of two, no vocabulary change, no consumer impact on the metadata tier or on intent_inferred_node_type, the arity is already stated so a collision is visible to anyone who looks, and the remaining work is a one-line predicate change plus its tests.

What must not be the fallback is landing the relation while leaving the defect view’s own NOT EXISTS in place. That would leave the fold spelled twice with nothing binding the two, which is the drift this item exists to remove, arriving by the back door.

Deferring is a judgement about difficulty encountered, not a default. If it happens, the deferred half is filed as its own Backlog item with the design above carried across intact, and this item’s body records what made it hard so the next session does not rediscover it.

R668 has answered the question this section used to hold open, and the answer removes an obligation rather than adding one. Its earlier body stated the constraint that the JOOQ_METADATA tier of intent_resolved_node_key_column must resolve an entry through the same predicate as the arm deciding the entry is well-formed, "or the two can disagree about which entries resolved". Its landed stages hold that agreement the way it was always held: the tier reads nothing but the defect view’s verdict and never resolves an entry itself.

What R668 needed was a different match, a trailing argMapping segment against a resolved key column, and it closed that one without spelling a predicate twice either: the authored side is folded on its own base relation as graphitron_argument_path_segment.segment_name_upper, the key-column side is folded at the crossing in intent_resolved_node_key_projection, and the unknown-column defect is stated as the absence of a projection row rather than as a repeated predicate. R668’s body records that it shipped a column_name_upper on intent_resolved_node_key_column and then reverted it, on the rule that a derived view never forwards a fold, and `intent_resolved_node_key_column.column_name’s comment now carries the reason so nobody mints one again.

Two consequences for this item, one of them uncomfortable and stated rather than buried. R668 will not read intent_stated_key_column_match, so the two-readers argument this item first made for the relation is gone; what earns it now is argued above, on witnesses. And R668’s landed DDL left this item’s arm alone exactly as its body promises: the four UPPER calls are in place and sql_node_key_column.column_name_upper is unminted, both deliberately deferred here. The implementer still re-reads the arm as it then stands rather than trusting this paragraph, R668 not yet being Done.

The depends-on field stays empty deliberately: this item is not blocked by R668, it just must not be written against a stale copy of the arm.

Two neighbouring items must not settle a convention opposite to this one, and they are not the same item as each other. R729 is the Java-side sibling over this crossing, a spelled name meeting a catalog reading, where the fold stays and only the silent pick goes. R702 is over the other one, two catalog readings compared under a fold that bridges nothing, where the fold itself goes. Neither is a dependency. This item’s convention, stated so both can agree or argue with it: a fold is minted where a spelled reference meets a reading and nowhere else, exactness is what a fold falls back to when more than one thing answers, and an ambiguity a fold would have spent silently is a stated row.