Add native events and distinct Resource versions to OPC UA binding working draft by marcschier · Pull Request #568 · xregistry/spec

marcschier · 2026-09-03T05:22:37Z

Summary

bind xRegistry change events to native OPC UA EventTypes and standard
Subscriptions/EventFilters
map logical Resources and exact Versions to distinct OPC UA Objects:
Registry -> Group -> Resource -> Versions -> Version
keep Resource identity, Resource Meta, delete semantics and event SourceNode
stable while the Resource FileType view delegates to the selected default
Version
define exact create/upload outputs, fixed-role Delete(ExpectedEpoch),
pinned logical file handles, and dirty-Close-only document commits
define Server -> Registry -> Group -> Resource -> Version notifier
propagation and surviving-notifier delivery for deletions

Authoritative dependencies

xRegistry event semantics: Week of Aug 24 #563, merged as
66ee31e47fbadff6ab982ae1516f7d9065e46b64
OPC UA companion model: OPCF-Members/spec-drafts#32 at
d3399fca025025a73e5a6b599f850a81d985c060
companion NodeSet SHA-256:
369f5f3f1814b333e4eeb52bfb4b6a730cdff372505a5f91a54c94f0016ac4cf
stack implementation: Add native xRegistry events and distinct Resource versions OPCFoundation/UA-.NETStandard#4396

Compatibility

The binding describes xRegistry OPC UA model 0.6.0. A 0.6 Server exposes only
the distinct-node hierarchy. Updated Clients may retain a model-metadata-gated
fallback for 0.5 flat Servers; Servers do not expose duplicate legacy aliases.

Validation

python tools/verify.py .
python -m pytest tools/ -q — 67 passed
tools/spellcheck workingdrafts/bindings/opcua.md
tools/tabcheck workingdrafts/bindings/opcua.md
git diff --check

The PR remains a draft while the companion and stack changes are reviewed.

Define the native OPC UA event type mapping, interaction semantics, notifier topology, subscriptions, filtering, and optional conformance units for the xRegistry Events working draft. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Document the normative errata applied to the xRegistry Events draft, define observable interaction boundaries for domain methods, Writes and FileTransfer, and constrain notifier delivery guarantees during deletion. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Require FileTransfer writes to stage document bytes and update Version Epoch and ModifiedAt only when a successful Close commits byte-different content. Keep clean, aborted, and byte-identical closes side-effect free. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

duglin · 2026-09-03T09:40:48Z

+`VersionId`, `Format`, `ContentType`, `ExternalReference`, `ResourceUrl`,
+`Epoch`, `CreatedAt`, `ModifiedAt`, `Labels` and other Version Properties. A
+Resource representation takes those values from the committed default Version
+and adds Resource Meta from `MetaEpoch`, `MetaCreatedAt`, `MetaModifiedAt`,


We should discuss this

marcschier · 2026-09-03T14:47:55Z

Stack implementation: OPCFoundation/UA-.NETStandard#4396.

Address review feedback by distinguishing domain resource names, the inseparable Resource/first-Version create, Version labels, and the first-class Resource Meta entity. Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

Signed-off-by: Marc Schier <marcschier@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5

## Summary - support the xRegistry 0.6.0 distinct Resource/Version hierarchy: `Registry -> Group -> Resource -> Versions -> Version` - instantiate stable logical Resource nodes separately from exact Version nodes while preserving existing Version NodeIds - delegate logical Resource FileType operations and Version-view metadata to the selected default Version with handle pinning and shared writer reservations - make Resource and Version delete behavior role-stable and use `MetaEpoch` / `Epoch` respectively - use stable Resource SourceNodes, exact Version SourceNodes and the `Server -> Registry -> Group -> Resource -> Version` notifier chain - keep a model-metadata-gated client fallback for 0.5 flat Servers; 0.6 Servers expose no legacy aliases - target `HasWoTProjection` at the real stable logical Resource node - use `AsyncCustomNodeManager` for the registration, fast-path, and federation managers, with awaited lifecycle, node mutations, event delivery, and cleanup - handle startup rollback, reentrant deletion callbacks, undisclosed file handles, and retryable cleanup without blocking unrelated file operations ## Authoritative dependencies - companion specification: OPCF-Members/spec-drafts#32 at `d3399fca025025a73e5a6b599f850a81d985c060` - OPC UA binding: xregistry/spec#568 - xRegistry event semantics: xregistry/spec#563, merged as `66ee31e47fbadff6ab982ae1516f7d9065e46b64` - companion NodeSet SHA-256: `369f5f3f1814b333e4eeb52bfb4b6a730cdff372505a5f91a54c94f0016ac4cf` ## Review feedback - keep the WoT Connectivity information-model designation at `1.1`; draft revisions update the publication date without changing the model version - eliminate all 198 unique CA1861 diagnostics across 54 files and remove seven obsolete project suppressions - fix the analyzer-clean touched-path CA1307 and the hierarchy follow-up CA1846/CA1851 diagnostics without dropping legacy-TFM compatibility - recover the reconcile queue after callback faults/cancellation and continue accepted pending changes - remove migration guidance for the xRegistry managers, which are new in 2.0 ## Compatibility - public WoT Connectivity model designation remains `1.1` - generated event-record ABI, constructors, options, NodeIds, and stored documents remain compatible - the generic xRegistry managers are new in 2.0 and implement `IAsyncNodeManager`; use `IAsyncNodeManagerFactory` and the async lifecycle hooks (see `docs\XRegistry.md`) - persistence schema and document blobs remain compatible unless noted below ## Validation - merge validation at `980422f76` with upstream `e8bec27d5`: 454 targeted WoT/materialization/model/registry cases and all 327 XRegistry cases passed on both net10.0 and net48; all 29 net10 aggregation sample cases passed - feedback regressions at `308e8ba74`: 55 targeted queue and live registry event/projection/lifecycle cases passed on each of net10.0 and net48 - prior CI: all 266 checks passed at `6489a0908`; the unchanged Ubuntu Core certificate-counter test and dependent jobs passed on the one-time retry ([run 34117304035, attempt 2](https://github.com/OPCFoundation/UA-.NETStandard/actions/runs/34117304035/attempts/2)) - `Opc.Ua.XRegistry.Tests` — 327 passed on net10.0 and net48 for migration commit `32c914aaf` - `Opc.Ua.WotCon.Tests` net10.0 — 1348 passed - `Opc.Ua.WotCon.Bindings.Tests` net10.0 — 683 passed - `Opc.Ua.SourceGeneration.Core.Tests` net10.0 — 3807 passed, 8 skipped - `Opc.Ua.SourceGeneration.Tests` net10.0 — 145 passed - `Opc.Ua.SourceGeneration.Stack.Tests` net10.0 — 94 passed - affected XRegistry and WoT client/server projects build successfully - xRegistry NodeSet is byte-identical to the companion artifact - repository-wide CA1861 inventory — 198 unique diagnostics across 54 files reduced to zero - targeted changed-fixture validation — 1,098 passed, 3 skipped, 0 failed - constrained full `UA.slnx` net10.0 Release build — CA1861 = 0 - `Opc.Ua.XRegistry.Client` net472 and netstandard2.1 builds — 0 warnings, 0 errors - independent shared-array safety review — no significant issues - `git diff --check` The final review regressions cover concurrent reconcile/open, synthetic logical handle collisions across default switches, cross-session Close isolation, shared writer reservations, logical FileType property/change propagation, logical Labels delegation, role-fixed deletion, event sources, model-version gating, and stable `HasWoTProjection` targets. The companion specification and protocol binding are reviewed in the linked PRs above. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5c79a1ed-6dab-4522-a9fc-6548caa78ad5 Copilot-Session: b605797f-a97a-4cd0-8f12-016d33c2fd88 Copilot-Session: 7ef369a5-2307-4f71-8a11-15af0e72f240 Copilot-Session: e716d455-8397-4d22-9c5a-398847ab7317

Integrate the OPC UA event binding and the distinct Resource/Version node model from xregistry#568 into the federation binding work on main. xregistry#568 branched from 18eb428, 52 commits back, so both sides had rewritten the same file: xregistry#568 by +835/-352 and main by +753/-273. The merge produced 32 conflicts. Both sides had claimed section 9 for different features. xregistry#568 used it for Events and main used it for Federation. The integrated numbering follows xregistry#568: Events is 9, Federation is 10, Error handling is 11 and Conformance is 12. Main's six federation subsections moved to 10.1 through 10.6 and its resolver-outcome subsection to 11.1. Content kept from xregistry#568: - The whole Events family, 9.1 through 9.7, covering the canonical EventTypes, field mapping, EventSourceUrl, emission rules, notifier topology, subscription and filtering, and delivery lifetime. - The distinct Resource and Version model: a logical Resource owning a typed ResourceVersionsType component named Versions, with exact Version Objects below it, and Resource Meta carried by MetaEpoch, MetaLabels, MetaCreatedAt and MetaModifiedAt. - The pinned companion model, Version 0.6.0 at commit d3399fca with its NodeSet digest. - The export-capable, event-capable and client conformance clauses, including the XREG-Events conformance unit. - The federated proxy rule, which local proxy Objects must obey. Content kept from main, none of which xregistry#568 had seen: - Section 1.1 Motivation, 8.1 Native metadata and navigation and 8.2 Core document-view export. - The full federation section. xregistry#568 carried a 36-line version; main's is 206 lines with advertisement and Registry selection, structured reference resolution, the three distinct reference mechanisms, trust and live consistency, namespace export and the pinned companion gaps. - Section 11.1 Federation resolver outcomes and its outcome table. - The readability work from the Lingity sessions, including the bulleted operation model and the named obligation holders. Where the two sides described the same rule differently, the merged text keeps main's sentence structure and xregistry#568's model vocabulary. The scope paragraph, the resource deletion rule and the serialization section are resolved that way. Verified that nothing was dropped. Every xregistry#568 marker survives at its original count: ResourceVersionsType 8, MetaEpoch 46, MetaCreatedAt 12, AssignedVersionId 9, EventSourceUrl 7, incarnation 7. Every main marker survives as well. Obligation counts rise to MUST 190, SHOULD 13 and MAY 35, against 138/8/27 on main and 137/12/36 on xregistry#568, consistent with a union of two feature sets rather than a replacement of one by the other. Five Events cross-references had to be restored to section 9 after the federation renumbering moved them, and four rules from xregistry#568 that the conflict resolution had truncated were added back: the MetaLabels reads and label Methods in the operation model, the MetaLabels coverage in recursive delete, and the federated proxy rule. tools/verify.py succeeds, spellcheck, tabcheck and badhrefs pass, and the full suite passes with 1179 tests. Signed-off-by: Marc Schier <marcschier@hotmail.com>

marcschier · 2026-09-23T08:34:01Z

Merged into #571 as 501adf4 and closing here. Nothing from this PR was dropped.

This branch was created from 18eb428, 52 commits before the federation binding work landed on #571's branch, so both sides had rewritten workingdrafts/bindings/opcua.md: this PR by +835/-352, #571 by +753/-273. The three-way merge produced 32 conflicts, resolved individually rather than by preferring either side.

The structural collision

Both branches had claimed §9 for different features — Events here, Federation on #571. The integrated document uses this PR's numbering:

§	Section	Source
9	Events (9.1–9.7)	this PR
10	Federation (10.1–10.6)	#571, renumbered from §9
11	Error handling (11.1 Federation resolver outcomes)	#571, renumbered from §10
12	Conformance	both, merged

Kept from this PR

The whole Events family: canonical EventTypes, field mapping, EventSourceUrl, emission rules, notifier topology, subscription and filtering, delivery lifetime and replay.
The distinct Resource/Version model — a logical Resource owning a typed ResourceVersionsType component named Versions, with exact Version Objects below it, and Resource Meta carried by MetaEpoch, MetaLabels, MetaCreatedAt, MetaModifiedAt.
The pinned companion model, Version 0.6.0 at commit d3399fca with its NodeSet digest.
The export-capable, event-capable and client conformance clauses, including the XREG-Events conformance unit.
The federated proxy rule.

Kept from #571, which this branch predates

§1.1 Motivation, §8.1 Native metadata and navigation, §8.2 Core document-view export, §11.1 Federation resolver outcomes, and the full federation section — this branch carried a 36-line version, #571's is 206 lines.

Verification

Every marker from this PR survives at its original count: ResourceVersionsType 8, MetaEpoch 46, MetaCreatedAt 12, AssignedVersionId 9, EventSourceUrl 7, incarnation 7. Obligation counts rose to MUST 190 / SHOULD 13 / MAY 35, against 137/12/36 here and 138/8/27 on #571 — a union of both feature sets, not a replacement.

Two classes of problem were found and fixed during verification:

Five Events cross-references had been dragged to §10 by the federation renumbering and were restored to §9.
Four rules from this PR that the conflict resolution had truncated were added back: the MetaLabels reads and label Methods in the baseline operation model, MetaLabels coverage in recursive delete, and the federated proxy rule.

tools/verify.py succeeds, spellcheck/tabcheck/badhrefs pass, the full suite passes with 1179 tests, and #571 is green on verify and DCO.

marcschier and others added 3 commits September 3, 2026 07:22