spec(leaf): resolve IReferenceProvider convergence question from ADR-066

[rubenvdlinde]

What

Resolves the open question ADR-041 deferred and ADR-066 re-narrowed (decision #6): how the OpenRegister cross-app leaf mechanism (RegisterLeafProvidersEvent, LeafDescriptor, the app-local IntegrationProvider strategy) relates to Nextcloud's native OCP\Collaboration\Reference\IReferenceProvider.

Decision-only OpenSpec change — ships no code. Deliverable is the decision, the capability comparison, and a small normative boundary rule.

Decision: COEXIST with a documented boundary

• CONVERGE rejected — structural dealbreakers. Even a pure read-only app-local leaf returns a collection keyed on an OR object; IReferenceProvider matches one string and resolves one IReference, with no object-collection model. And a leaf's create() append has no home in the read-only reference contract. Convergence would fork the read path and split the write path across two mechanisms.
• COEXIST recommended — the two answer different questions and are not redundant; the only overlap (single read-only linked entity by URL) resolves deterministically by context. Draw the line, keep both.
• BRIDGE named but not built — an adapter surfacing an existing IReferenceProvider as a leaf's single-entity render is the only sensible future convergence, scoped to single-entity read-only render. No driver today, so not adopted.

Author boundary rule

• Data-provider leaf — object-scoped collection of your app's items on an OR object (list + optional append) and/or a tab/widget on the object.
• IReferenceProvider — single URL/text token to a read-only inline rich preview in free text (Talk, Text), no object, no write.

Contents

• proposal.md, design.md (comparison table + argued options + recommendation + boundary rule + recommended ADR-066 amendment), specs/leaf-reference-boundary/spec.md (4 normative requirements), tasks.md (unchecked).
• openspec validate leaf-reference-provider-convergence --strict passes.

Follow-up (not in this change)

Amend ADR-066 decision #6 from deferred to decided: coexist (hydra governance change) — status note drafted in design.md.

Do not merge — decision proposal for human review.

[github-actions]

Quality Report — ConductionNL/openregister @ 15d6839

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 174/174
npm			✅	✅ 555/555
PHPUnit					❌
Newman					❌
Playwright					⏭️

---

Quality workflow — 2026-07-25 11:51 UTC

Download the full PDF report from the workflow artifacts.

[github-actions]

Quality Report — ConductionNL/openregister @ 73a8d91

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
composer			✅	✅ 173/173
npm			✅	✅ 713/713
PHPUnit					✅
Newman					✅
Playwright					✅

---

Quality workflow — 2026-08-04 11:52 UTC

Download the full PDF report from the workflow artifacts.