Skip to content

gate-54: no dialect for a cross-register $ref — a relation owned by another app can never resolve #300

Closed

Description

@rubenvdlinde

Summary

gate-54 resolves every $ref against the schemas of the app's own settings directory, so a relation that legitimately points at a schema owned by another app's register can never resolve. There is no dialect to express it, so the finding is permanently red and no correct change in the repo can clear it.

Measured on ConductionNL/procest@development, gate package 651e5c5bb3ba8764903e5d6fc5bac5a208bd67fc:

lib/Settings/procest_register.json: caseType.productsOrServices — $ref 'product' does not resolve to a schema key in the register set (case-exact)
lib/Settings/procest_register.json: case.vergunningaanvraagRef  — $ref 'vergunningaanvraag' does not resolve to a schema key in the register set (case-exact)

Why these are correct as authored

Both name schemas owned by a different app, exactly as their descriptions say:

  • caseType.productsOrServices → Pipelinq's product register (ADR-003: the charge on a concrete case is a Pipelinq financial transaction).
  • case.vergunningaanvraagRef → the DSO vergunningaanvraag object.

Neither is in procest's own 85-schema register set, and neither should be — adding a foreign schema to procest's register would misstate ownership and duplicate the source of truth.

Both properties are live: productsOrServices has 6 references across lib/ and src/, vergunningaanvraagRef has 7. Deleting them to clear the gate would break working relations.

Root cause

check_relation_dialect.py::_global_schema_keys() builds the candidate set from *register*.json and register.d/*.json in the same settings dir (_settings_dir(p)), collecting each schema's JSON key and its declared slug. There is no branch for a cross-register reference — the union is app-local by construction.

A note on what does NOT work

procest briefly carried "x-external-register": "<app>" next to three such $refs, added in good faith as a gate-54 fix (PR #776). It is inert in both directions and has since been removed (PR #775):

  • OpenRegister does not read it — no occurrence of x-external-register anywhere under openregister/lib/.
  • gate-54 does not read it either — there is no external-register branch in the checker.
  • Proof it changed nothing: gate-54 reports the same 2 findings with and without the key.

Worth flagging because an unread x-* key next to a flagged $ref looks exactly like a mechanism, and a later reader would reasonably assume the relation is declared and handled.

Suggested fix

Give the dialect a way to say "this target lives in another register", and teach the checker to recognise it — e.g. a qualified ref ($ref: "pipelinq:product") or an explicit sibling key the checker actually consults. Then:

  • resolve the local part against the named app's register when that app is present in the workspace;
  • when it is not present, report NOT VERIFIABLE HERE rather than FAIL — the same posture gate-30 already takes for monitoring endpoints whose controller lives in another package ("Their posture lives in the openregister package; NOT a pass for them").

The distinction matters: today a correct cross-app relation and a genuine typo produce byte-identical output.

Related

Same class in all three: the rule's evidence corpus is narrower than the construct it judges, so a correct design is indistinguishable from a defect.

Activity

  1. rubenvdlinde commented on Aug 9, 2026

    @rubenvdlinde
    ContributorAuthor

    Closing — this is already solved by #286, which I had not seen when I filed.

    _is_external_ref() exists at lib/check_relation_dialect.py:341 on main as of 365fa31d09a26f980e6dc76cb0800575ef005a4e. It did not exist at 651e5c5bb3ba8764903e5d6fc5bac5a208bd67fc, which is the package I measured against, so the finding I described was real at that SHA and is now obsolete.

    Both procest findings are closed by expressing them in the dialect #286 added — x-external-register: <app> on the property, bare identifier, no $ref:

    property owning register
    caseType.productsOrServices pipelinq
    case.vergunningaanvraagRef dso

    gate-54 on lib/Settings/procest_register.json: 2 → 0, proven both directions with the same checker and invocation — putting the $ref back reproduces $ref 'vergunningaanvraag' does not resolve to a schema key in the register set (case-exact), restoring returns it to 0.

    Two notes that may still be worth keeping from this issue:

    1. The "declares both" message is doing real work. procest had $ref and x-external-register on three properties, added before fix(gate-54): a genuine cross-app reference could not be authored at all #286 landed. The new branch reports them with an actionable message ("drop the $ref and keep the bare identifier") rather than the generic unresolved-target one. That distinction is what let me fix them correctly rather than guess.

    2. case.decisions is a counter-example worth remembering. It also carried x-external-register: "decidesk", but decision is one of procest's own 85 schemas and resolves locally — so the key there was wrong, and adding it would now create a finding. "Names another app" is not the same as "not resolvable here"; the register set is the test, not the app name in the description.

    Retracting my "no dialect exists" framing — the dialect exists, I measured a package that predated it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions