Repository navigation
Description
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:
- Add a
$refto 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. - Invent a local
credentialschema 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. - Reword the description so
_RELATION_DESC_REstops 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
$refthe resolver understands as cross-app (e.g.openregister:credential), checked for app-plus-schema plausibility rather than resolved locally; - an explicit
x-relation-externalmarker (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
rubenvdlinde commentedon Aug 9, 2026
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.credentialIdannotated withx-external-register: openregisterand no$ref:c51a225(main, at test time)credentialId — relation-shaped property (format:uuid + relation description) lacks canonical $ref (ADR-062 rule 7)7f5f9e7(#286 head)651e5c5(main, now)grep -c x-external-register hydra-gates/scripts/lib/check_relation_dialect.pyreturns 0 on651e5c5. 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 insideconfiguration.authentication.credentialRefrather than at the schema root._is_external_ref()handles it without modification, and check (b)'sand 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-registerand a$ref, which is correct — that$refis 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.
rubenvdlinde commentedon Aug 9, 2026
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:
Then re-ran the full suite on openconnector
development(10605ab1, which already carries thex-external-register: openregisterannotation), at CI scope,NODE_PATHproven byrequire.resolve('ajv')resolving to an absolute path under the server'snode_modules:No findings log was written, and all 30
.errfiles 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:
c51a225lacks canonical $ref (ADR-062 rule 7)7f5f9e7(#286 head)651e5c5(main, then)365fa31(main, now)The two FAILs were correct measurements of a package that did not yet contain the fix —
grep -c x-external-registerreturned 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.credentialRefrather 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.