Skip to content

gate-54 rule (b): a relation to a FOREIGN register has no expressible $ref, so a correct property is unfixable #289

Closed

Description

@rubenvdlinde

Measured on openconnector with gate package 48c88ba1e0d049f8f38538c33e790d3e603c55d0, scope --scope-to-diff --base origin/beta.

[gate-54] relation-dialect: FAIL — 1 non-canonical relation dialect finding(s)
lib/Settings/openconnector_register.json: source.configuration.authentication.credentialRef.credentialId
  — relation-shaped property (format:uuid + relation description) lacks canonical $ref (ADR-062 rule 7)

The finding is correct about the shape and wrong about the remedy

credentialId genuinely is a reference: it holds the UUID of a credential. Rule (b) fires because it has format: uuid plus a description matching _RELATION_DESC_RE ("UUID of the broker credential to use").

But the thing it references is not in this register's file set. It is an OpenRegister credential-broker credential, owned by OpenRegister/Doriath. And check (f) requires a string $ref to resolve case-exactly to a schema key or slug collected by _global_schema_keys(), which only globs lib/Settings/*register*.json and lib/Settings/register.d/*.json within the same app.

So the three available moves are all wrong:

  1. Add a $ref to a name that does not exist in openconnector's register set → immediately fails check (f) as a dangling $ref. Rule (b) and rule (f) are mutually unsatisfiable for a foreign-register relation.
  2. Invent a local credential schema to point at → fabricates a schema this app does not own and must not own; credentials deliberately live behind the broker so the secret never lands here.
  3. Reword the description so _RELATION_DESC_RE stops matching → pure comment-satisfaction. The property is still a relation; only the gate's view of it changed. This is the move the rule accidentally incentivises, and it is the one that makes the schema less accurate.

I did none of them. The finding is being left red on openconnector with this issue as the reason.

What the rule seems to be missing

There is no way to express "this is a relation, and its target is owned by another app's register". Everything else in ADR-062's dialect assumes a single register file set.

Possible shapes, in rough order of preference:

  • a qualified $ref the resolver understands as cross-app (e.g. openregister:credential), checked for app-plus-schema plausibility rather than resolved locally;
  • an explicit x-relation-external marker (naming the owning app/schema) that satisfies rule (b) and is skipped by rule (f);
  • failing both, rule (b) not firing when a property sits under a block the dialect already recognises as broker-owned.

Why this matters beyond one property

_RELATION_DESC_RE matches on prose — reference to, uuid of the, fk to. Any app that documents a cross-app UUID accurately will trip rule (b) and find rule (f) blocks the only fix. The incentive gradient points at deleting the accurate description, which is the opposite of what the dialect is for. openconnector's credentialRef block is likely not the only instance — every app consuming the credential broker has the same shape.

/cc the ADR-062 owner.

Activity

  1. rubenvdlinde commented on Aug 9, 2026

    @rubenvdlinde
    ContributorAuthor

    Measured: #286 fixes openconnector's shape too. This issue is a duplicate of #286 — but the gate is still red, because #286 has not merged.

    I tested the same working tree against two package refs, changing nothing but the checker. openconnector's source.configuration.authentication.credentialRef.credentialId annotated with x-external-register: openregister and no $ref:

    package ref gate-54
    c51a225 (main, at test time) FAIL — credentialId — relation-shaped property (format:uuid + relation description) lacks canonical $ref (ADR-062 rule 7)
    7f5f9e7 (#286 head) PASS
    651e5c5 (main, now) FAIL — byte-identical finding

    grep -c x-external-register hydra-gates/scripts/lib/check_relation_dialect.py returns 0 on 651e5c5. The notion still does not exist on main, so the annotation is inert there and the gate reports the original finding unchanged.

    This confirms #286 generalises beyond docudesk's shape

    docudesk's cases (correspondence.caseReference, generatedDocument.zaakId) point at a Zaak in Procest. Mine points at a credential in OpenRegister's broker — a different owning app, a different reason for the boundary (the secret must never land in openconnector), and it sits nested three levels deep inside configuration.authentication.credentialRef rather than at the schema root. _is_external_ref() handles it without modification, and check (b)'s and not _is_external_ref(prop) is the line that does it.

    So this is not "docudesk's fix happened to also work"; the exemption is keyed on the property, not on the shape of the register, which is the right axis.

    I have also confirmed the narrowness holds in the direction that matters: #286 still reports a property carrying both x-external-register and a $ref, which is correct — that $ref is one OpenRegister can never resolve.

    What I am doing

    Landing the annotation on openconnector now, with the reason written into the property description. It does not turn the gate green today — I have measured that it does not — but the property is genuinely a foreign-register reference and saying so is correct independent of any checker. When #286 merges, openconnector's gate-54 goes green with no further change.

    Leaving this issue open until #286 lands, then it should be closed as a duplicate. Closing it now would drop the tracking while the gate is still failing in two repos.

  2. rubenvdlinde commented on Aug 9, 2026

    @rubenvdlinde
    ContributorAuthor

    Closing on a measurement, not on a report. Fixed by #286, which is now on main.

    I verified the package state myself rather than taking it second-hand — a claim that #286 had merged reached me once while it was still open:

    $ git rev-parse origin/main
    365fa31d09a26f980e6dc76cb0800575ef005a4e
    $ git show origin/main:hydra-gates/scripts/lib/check_relation_dialect.py | grep -c '_is_external_ref'
    4
    

    Then re-ran the full suite on openconnector development (10605ab1, which already carries the x-external-register: openregister annotation), at CI scope, NODE_PATH proven by require.resolve('ajv') resolving to an absolute path under the server's node_modules:

    [hydra-gates] gate package: 365fa31d09a26f980e6dc76cb0800575ef005a4e
    [hydra-gates] Scope: diff vs origin/beta — 1475 changed file(s)
    [gate-54] relation-dialect: PASS
    

    No findings log was written, and all 30 .err files were 0-byte — so the gate reported PASS having actually run, not having crashed into one.

    The full sequence, for the record

    Same working tree, same property, four package refs:

    package ref gate-54
    c51a225 FAIL — lacks canonical $ref (ADR-062 rule 7)
    7f5f9e7 (#286 head) PASS
    651e5c5 (main, then) FAIL — byte-identical
    365fa31 (main, now) PASS

    The two FAILs were correct measurements of a package that did not yet contain the fix — grep -c x-external-register returned 0 on both — not a defect in #286.

    What this confirms about #286's generality

    openconnector's case differs from docudesk's in every dimension except the underlying one: a different owning app (OpenRegister's credential broker rather than a Zaak in Procest), a different reason for the boundary (the secret must never enter the openconnector process at all), and a property nested three levels deep inside configuration.authentication.credentialRef rather than sitting at a schema root. _is_external_ref() handled it unmodified.

    That is because the exemption is keyed on the property, not on the shape of the register — the right axis, and the reason this generalised without needing a second fix.

    Landed on openconnector in ConductionNL/integriq#1202.

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