ID

R235

Status

Backlog

Bucket

cleanup

Priority

6

Theme

structural-refactor

Created

2026-05-23

Updated

2026-05-23

Tidy @reference path-element surface: separate join-shape from WHERE-filter

The legacy ReferenceElement { table, key, condition } directive surface combines three roles in one input object: key: and table: and condition: (without companions) name the join shape; condition: combined with key: or table: names a WHERE-filter that folds onto the FkJoin’s whereFilter. The full combinations table at R232’s spec lines 44-52 documents seven valid shapes. The conflation invites cargo-culting (condition: sometimes means "ConditionJoin", sometimes "WHERE filter on FkJoin") and the seven-shape free combination invites authoring drift.

R232 deliberately preserved the legacy semantics so the lift could ship without forcing a migration; the regression-guard fixtures TABLE_WITH_CONDITION_PRESERVES_WHERE_FILTER / KEY_WITH_CONDITION_PRESERVES_WHERE_FILTER in GraphitronSchemaBuilderTest pin the existing meanings so a future cleanup pass can’t silently re-classify.

Likely design: @oneOf for the join-shape arm (mutually-exclusive key: | table: | condition:) + a separate whereFilter: field for the conditional, or an equivalent restructuring that makes the SDL author’s intent unambiguous at the directive site. Migration would either be cleanly automated (the resolver knows which condition: slot each schema uses) or surfaced via an actionable AUTHOR_ERROR per element.

Surfaced during R232’s design fork; filed as a separate item because R232’s scope was target-table resolution, not surface cleanup.