gate-54 rule (f) makes an ADR-066 cross-app relation unrepresentable — a sanctioned relation cannot be declared without failing the gate

[rubenvdlinde]

Summary

gate-54 rule (f) $REF TARGETS requires that a string $ref "resolve to a schema key in the same register file set (case-exact)".

ADR-066 explicitly sanctions cross-app relations — a property on one app's schema that references an object owned by another app. By construction, that target is not in the referencing app's register file set. So rule (f) and ADR-066 contradict each other: a correctly-declared cross-app relation is a permanent gate-54 failure, and there is no dialect to express it.

Rule (b) RELATION SHAPE closes the other exit: a format: uuid property with a relation-shaped description and no $ref is also a finding. So for a cross-app relation the author can fail (f) by naming the foreign schema, or fail (b) by not naming it.

Measured on pipelinq (12 findings, 6 of them this shape)

Property	Foreign owner	Rule hit
lead.decisions → $ref: 'Decision'	decidesk (ADR-066; decidesk owns making + eIDAS signing)	(f)
ticket.decisions → $ref: 'Decision'	decidesk	(f)
ticket.contract → $ref: 'Contract'	Shillinq (owns contract lifecycle)	(f)
ticket.caseReference	Procest (the case it converted into)	(b)
receiptTemplate.organizationId	organisation, an OpenRegister concept	(b)
posZReport.store	the store plane — ADR-080 D2/D3 says store discovery is OpenRegister's	(b)

Each description already names the owner explicitly, e.g.

"References decidesk Decision objects (ADR-066 cross-app relation); Decidesk owns the making and eIDAS signing."

So the intent is documented in-tree; there is simply no machine-readable way to say it.

Why "just drop the $ref" is the wrong fix

Deleting $ref: 'Decision' would silence rule (f) on ticket.contract/lead.decisions (they are not all format: uuid, so (b) would not always fire) — but it destroys the only structured statement of what the property points at, to satisfy a checker. That is the same trade as deleting an inconvenient @spec, and I have not done it in pipelinq#743.

⚠️ There is also a live trap for anyone tempted to "fix" it locally: pipelinq does have a local contract schema, so $ref: 'Contract' → $ref: 'contract' makes gate-54 green in one character. It would also silently repoint a Shillinq relation at a different, local object. A case-insensitive-looking near-miss is exactly where this gate can be satisfied by making the data model wrong.

Suggested fix

A first-class cross-app form, so the relation stays declared and machine-readable, e.g.

{ "type": "string", "format": "uuid",
  "$ref": "decidesk:decision" }

or a sibling key (x-openregister-external-ref) carrying { "app": "decidesk", "schema": "decision" }, with rule (f) resolving app:schema against the declared app dependency set rather than the local register, and rule (b) accepting its presence as "has a canonical ref".

Until then rule (f) cannot be satisfied by any correct cross-app schema, which makes gate-54 unclosable for every app that has one — i.e. every app ADR-066 applies to.

What was fixed locally

pipelinq#743 fixes the 6 findings with genuine local targets (5 ticket relations gained $ref, and task.requestId was repointed from the retired request schema to its ticket successor) and leaves these 6 red with this reason.

[rubenvdlinde]

Second measured instance: softwarecatalog contract.decisions

Confirming this on a second repo, with hydra-gates 651e5c5bb3ba8764903e5d6fc5bac5a208bd67fc (i.e. after the gate-45–55 and gate-56–64 correctness work, so this is not a stale-package artefact).

lib/Settings/softwarecatalogus_register.json:

"decisions": {
  "type": "array",
  "title": "Decisions",
  "description": "Approval/renewal decisions for this contract. References decidesk Decision objects (ADR-066); Decidesk owns the making and eIDAS signing.",
  "items": {
    "type": "string",
    "format": "uuid",
    "$ref": "Decision",
    "x-external-register": "decidesk"
  },
  "referenceType": "decision",
  "x-allow-create": true
}

Gate output:

[gate-54] relation-dialect: FAIL — 1 non-canonical relation dialect finding(s)
lib/Settings/softwarecatalogus_register.json: contract.decisions — $ref 'Decision' does not resolve to a schema key in the register set (case-exact)

Measured facts:

• There is no decision-like schema in softwarecatalog's register set — [k for k in schemas if 'decis' in k.lower()] returns []. The target genuinely lives in decidesk.
• The property already carries x-external-register: "decidesk", which states the intent machine-readably. grep -rn "external" scripts/lib/check_relation_dialect.py at 651e5c5 returns nothing — _resolve_ref() resolves only against the local keys set, so the annotation is invisible to the gate.

This is the whole of softwarecatalog's remaining gate-54 debt: the other four findings in this repo were genuine dangling refs ($ref: "#/components/schemas/property" on element/view/model/relation where the slug is property-definition) and are fixed in ConductionNL/softwarecatalog#467 — 5 → 1. So the remaining 1 is exactly the unrepresentable case this issue describes, with nothing else hiding behind it.

Left red deliberately. Renaming or deleting that $ref to green the gate would break the ADR-066 relation to satisfy a checker.

Since x-external-register is already present and already carries the target register's name, honouring it in _resolve_ref() (treat a $ref as satisfied when the property declares an external register, or resolve it against that register when its file set is available) would close this without inventing new vocabulary.

[rubenvdlinde]

Correction to my comment above — #286 closes this, and my instance is now fixable

My comment two hours ago argued that softwarecatalog's contract.decisions was unrepresentable and left it red on that basis. That is no longer true, and I want to correct it here rather than leave it as the last word.

I measured against package 651e5c5. #286 landed after that (365fa31, "fix(gate-54): a genuine cross-app reference could not be authored at all") and gives exactly the missing dialect: x-external-register: <app> on a property carrying the bare identifier, with no $ref.

Re-measured at 365fa31: the finding persisted, but for a different and correct reason. My property carried both x-external-register and $ref — and _is_external_ref() reads the annotation on the property, while this register had it on items only. So the exemption never applied and the old generic message fired instead of #286's new actionable one.

Authoring the sanctioned form — hoist x-external-register to the property, drop the $ref — takes gate-54 to PASS, and restoring the $ref puts it straight back to 1. Fixed in ConductionNL/softwarecatalog#473.

So: gate right, register wrong. My earlier "unclosable" framing was a stale-package artefact.

One residual, much smaller, worth deciding on

For an array-valued cross-app relation the natural home for x-external-register is items — that is where the $ref would have gone, and where the item's type/format live. Putting it only there is invisible to _is_external_ref(), and the resulting message is the generic "does not resolve to a schema key", which points an author at the wrong fix.

Either behaviour is defensible; the current one is just undiscoverable from the message. Cheapest fix would be for _is_external_ref() to also look in prop['items'], so an array of external references can be authored the same way as a scalar one.

[rubenvdlinde]

Resolved by the package itself — closing the loop with a measurement.

Re-cloning at 365fa31d09a26f980e6dc76cb0800575ef005a4e shows _is_external_ref now recognises x-external-register: <app> and suppresses both $ref rules, added after the same failure was measured on docudesk (correspondence.caseReference / generatedDocument.zaakId → a Procest Zaak). My filing described the same trap from pipelinq; the remedy is already in the tool.

Applied to all six pipelinq cross-app relations in ConductionNL/pipelinq#743 — gate-54 full-tree 12 → 0:

Property	Change
ticket.contract	drop $ref: Contract (kept x-external-register: shillinq)
lead.decisions.items, ticket.decisions.items	drop $ref: Decision (kept x-external-register: decidesk)
ticket.caseReference	+ x-external-register: procest
receiptTemplate.organizationId, posZReport.store	+ x-external-register: openregister

Three of the six already declared their owner and merely carried a $ref beside it — the exact shape the new message calls out.

Positive control: restoring $ref: Contract beside x-external-register: shillinq takes the count 0 → 1 with the "AND $ref" message; removing it returns 0.

Worth keeping as a general lesson: a finding I had documented as unclosable became closable purely because the package moved under me. Re-cloning .github@main before each measurement round — rather than trusting a sha from earlier in the session — is what surfaced it.