Add generic xRegistry libraries (abstract registry base model)

[marcschier]

Description

xRegistry is the abstract registry base model: a registry-agnostic, content-addressed
resource registry. It knows nothing about what a resource contains — a concrete registry supplies its
own companion namespace and a fingerprinting strategy and reuses everything else. The PubSub Schema
Registry in #4007 is the first specialization (its resources are schema documents),
and #4093 (WoT Binding) carries a byte-identical copy of the same base NodeSet, so a
shared canonical home is worth having.

Packages

Package	Depends on	Contains
OPCFoundation.NetStandard.Opc.Ua.XRegistry	Opc.Ua.Core	Abstract base companion model (compiled by the model source generator), XRegistryWellKnown, IResourceContentIdProvider
OPCFoundation.NetStandard.Opc.Ua.XRegistry.Client	+ Opc.Ua.Client	XRegistryClient (abstract) / GenericXRegistryClient (sealed), built on the generated ObjectType proxies
OPCFoundation.NetStandard.Opc.Ua.XRegistry.Server	+ Opc.Ua.Server	Fast-path / registration / federation node managers, XRegistryServerOptions, IXRegistryResourceStore

Opc.Ua.XRegistry deliberately depends on neither SDK, so a codec or a shared contracts assembly can
reference the identity abstraction without pulling in the client or the server.

The model is compiled, not loaded

The companion model is compiled into the assemblies by the OPC UA model source generator.
Opc.Ua.XRegistry.NodeSet2.xml is an AdditionalFiles generator input only — there is no
EmbeddedResource, no runtime NodeSet parsing and no hand-written NodeId tables for anything the
model declares. All three node managers load it the same way:

protected override NodeStateCollection LoadPredefinedNodes(ISystemContext context)
{
    return new NodeStateCollection().AddOpcUaXRegistry(context);
}

XRegistryWellKnown is reduced to the namespace URI plus the identifiers of the instances a
registry materializes at runtime, which live above the model's own 63000-63999 range so they can
never collide with it.

What it does

• Content-derived identity — IResourceContentIdProvider maps a document + format to a
  fingerprint and names the (canonicalization, hash) algorithm. Identity is derived from the bytes,
  not assigned by the server, so it is stable across registries — which is what makes de-duplication
  and federation work.
• Opaque-NodeId fast path — a registered resource is reachable at an Opaque NodeId whose
  Identifier is the raw content-id bytes, so a consumer that received the id on the wire resolves the
  document in a single Read: no Browse, no fingerprint recomputation. The client reads it through
  the ReadBytesAsync session extension, so a document larger than MaxByteStringLength is fetched
  with range-based reads rather than failing. Optionally pre-publishes a seed resource so a fresh
  server can resolve one resource before any registration.
• The model's own lifecycle — the registry root is a RegistryType instance serving
  CreateGroup / GetOrCreateGroup; each group serves CreateResource / GetOrCreateResource; and
  because ResourceType : FileType, the document is the file — content is streamed through the
  inherited Open / Read / Write / Close. Close fingerprints the accumulated bytes and
  publishes the Opaque fast-path node at runtime. Identical bytes reuse the existing node, whose
  lifetime is reference counted so it survives until the last resource resolving to those bytes is
  gone and is retired when a resource is re-written with different content.
• Optimistic concurrency — Delete(ExpectedEpoch) on both resources and groups, and the same
  epoch check on label mutations, so a caller working from a stale read is rejected rather than
  clobbering a concurrent change.
• Labels — RegistryType, GroupType and ResourceType each expose an AttributesType Object
  with AddAttribute / RemoveAttribute; labels are published as addressable String Properties.
• Federation — a resource hosted by another registry is published as a real ResourceType
  instance whose ExternalReference (ExpandedNodeId + ServerIndex into the local ServerArray)
  and ResourceUrl carry the link and whose Xid carries the content-id. Because it is an ordinary
  ResourceType, a generic client drives a federated resource through exactly the same proxy as a
  local one.

Extensibility

A domain registry subtypes the base model — the PubSub Schema Registry declares
SchemaFileType : ResourceType — and the generator mirrors that hierarchy across assemblies, so the
proxy chain follows automatically (SchemaFileTypeClient : ResourceTypeClient : FileTypeClient).

abstract XRegistryClient
   ├── sealed GenericXRegistryClient   // any registry namespace
   ├── SchemaRegistryClient  (domain)
   └── WotRegistryClient     (domain)

• A domain client derives from XRegistryClient and inherits the whole lifecycle. Helpers
  written as extension methods over a base proxy (such as WriteDocumentAsync on
  ResourceTypeClient) are callable on the domain proxy with no inheritance in the client layer.
• A generic client still drives a domain registry, because a domain instance is an instance of
  the base type. This is covered by a test that defines a domain subclass over the base.

State

Document bytes live behind an injectable IXRegistryResourceStore. Because a resource is a
ResourceType, which is a FileType, the store mirrors the file access model: reads and writes are
offset and length based, so a document never has to be materialized as a whole and a ranged read
touches only the bytes it needs.

The document is transferred with the inherited FileType Methods, whose mode bits are honoured: a
write that does not set EraseExisting starts from the stored bytes and replaces only the range it
writes rather than truncating the rest. A handle is valid only on the resource and the session that
opened it, and a session's handles are released when it closes.

Two implementations ship: InMemoryResourceStore (the default, in-process) and
FileSystemResourceStore, built on the IFileSystem abstraction so documents outlive the
process and a shared volume can back a cluster. XRegistryResourceStoreContractTests is a reusable
fixture that validates any implementation against the contract.

Transport security

Registry writes always require a SignAndEncrypt secure channel — a document and its
content-derived identity are integrity-critical, so every mutation is rejected with
BadSecurityModeInsufficient on a channel that is only signed or unprotected. This is not
configurable. Reads are allowed on any secure channel by default; RequireEncryptionForReads extends
the requirement to them when the documents themselves are confidential. An in-process call carries no
channel and is always allowed.

Hardening

The lifecycle Methods are remotely callable, so every unbounded dimension is bounded via
XRegistryServerOptions; exceeding a bound fails the call rather than the server:

Option	Default	Enforced on	Status code
MaxConcurrentUploads	64	CreateResource, Open	BadTooManyOperations
MaxResourceBytes	16 MiB	Write	BadRequestTooLarge
MaxRegisteredResources	4096	CreateResource	BadTooManyOperations

A source generator bug fixed along the way

Building on the compiled model surfaced a defect in shared generator infrastructure.
NodeSetToModelDesign.CreateDecoder decoded values with an empty EncodeableFactory, so a NodeSet2's
method InputArguments / OutputArguments — encoded as a list of Argument ExtensionObjects — never
decoded, while HasArguments was still set. Every NodeSet2-sourced model in the stack was
silently generating argument-less MethodStates and ObjectType proxies. ModelDesign-sourced models
(the core stack) were unaffected, which is why this went unnoticed. Fixed in b87726af with a
regression test that fails without it.

Two defects in the xRegistry NodeSet itself were fixed at the same time: BrowseName="1:InputArguments"
→ ns-0 InputArguments (published NodeSets never namespace-qualify these), and the CreateResource /
GetOrCreateResource output VersionId renamed to AssignedVersionId, which collided with the
input of the same name and produced a duplicate C# parameter.

Other fixes applied while extracting

• XRegistryRegistrationNodeManager uses System.Threading.Lock instead of an object-typed sync
  root, per the repository locking rules.
• Dropped the InternalsVisibleTo entries granting internals to Opc.Ua.PubSub.Server.Tests. That
  project only consumes public XRegistryWellKnown API.
• The UA.slnx edit in DRAFT Add experimental data encodings #4007 accidentally replaced the
  tests/Opc.Ua.Redundancy.Kubernetes.Tests entry instead of adding a line, silently dropping that
  project from the solution. The entry is preserved here and the change is purely additive.

Tests

tests/Opc.Ua.XRegistry.Tests (168) covers the group and resource lifecycles, the FileType
transfer, delete and epoch conflicts, labels, federation, both resource stores, the fast path,
transport security and the extensibility contract — positive and negative paths. Passing on net10.0
and net48. Patch line coverage is 98.5%.

Also adds tests/Directory.Build.props / .targets: the .NET 10 SDK prunes
Microsoft.Extensions.Logging.Abstractions out of the test output, and coverlet's Mono.Cecil
resolver only searches the output directory, so it silently fails to instrument every module that
references ILogger and reports 0% coverage for them. These force the package back into the restore
graph and copy its implementation next to the test binary.

Documentation

New docs/XRegistry.md, linked from the documentation index.

Follow-ups (deliberately not in this PR)

• The libraries currently emit no logging. Adding source-generated [LoggerMessage] logging is worth
  a follow-up.
• WoT Binding and WoT Connectivity 1.1 #4093 (WoT Binding) carries an identical copy of Opc.Ua.XRegistry.NodeSet2.xml under
  src/Opc.Ua.WotCon/Design/; de-duplicating it against this package is a natural follow-up.
• The NodeIds in XRegistryWellKnown are provisional — final identifiers are assigned by the OPC
  Foundation.

Related

• DRAFT Add experimental data encodings #4007 is rebased onto this branch and now contains only the experimental data encodings and the
  PubSub Schema Registry specialization.

[codecov]

Codecov Report

❌ Patch coverage is 94.18484% with 56 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.68%. Comparing base (a03bca9) to head (2a9182c).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
...egistry.Server/XRegistryRegistrationNodeManager.cs	92.12%	12 Missing and 37 partials ⚠️
src/Opc.Ua.XRegistry.Client/XRegistryClient.cs	97.56%	0 Missing and 2 partials ⚠️
...a.XRegistry.Server/XRegistryFastPathNodeManager.cs	94.28%	0 Missing and 2 partials ⚠️
...XRegistry.Server/XRegistryFederationNodeManager.cs	95.00%	0 Missing and 2 partials ⚠️
...Opc.Ua.XRegistry.Server/FileSystemResourceStore.cs	98.75%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4097      +/-   ##
==========================================
- Coverage   79.95%   79.68%   -0.27%     
==========================================
  Files        1472     1481       +9     
  Lines      199303   200265     +962     
  Branches    34534    34724     +190     
==========================================
+ Hits       159347   159584     +237     
- Misses      27833    28543     +710     
- Partials    12123    12138      +15     

Files with missing lines	Coverage Δ
.../Opc.Ua.XRegistry.Client/GenericXRegistryClient.cs	100.00% <100.00%> (ø)
...a.XRegistry.Client/ResourceTypeClientExtensions.cs	100.00% <100.00%> (ø)
...c/Opc.Ua.XRegistry.Server/InMemoryResourceStore.cs	100.00% <100.00%> (ø)
...try.Server/XRegistryServiceCollectionExtensions.cs	100.00% <100.00%> (ø)
...urceGeneration.Core/Schema/NodeSetToModelDesign.cs	71.25% <100.00%> (+2.48%)	⬆️
...Opc.Ua.XRegistry.Server/FileSystemResourceStore.cs	98.75% <98.75%> (ø)
src/Opc.Ua.XRegistry.Client/XRegistryClient.cs	97.56% <97.56%> (ø)
...a.XRegistry.Server/XRegistryFastPathNodeManager.cs	94.28% <94.28%> (ø)
...XRegistry.Server/XRegistryFederationNodeManager.cs	95.00% <95.00%> (ø)
...egistry.Server/XRegistryRegistrationNodeManager.cs	92.12% <92.12%> (ø)

... and 59 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.