Replace session state encoder with IEncodable generation using source generators (#3673)

* Replace SessionStateEncoder with IEncodeable on session/subscription models

- Source-gen [DataType]/[DataTypeField] on: MonitoredItemOptions, MonitoredItemState,
  SubscriptionOptions, SubscriptionState (auto-generated Encode/Decode/IsEqual/Clone)
- Manual IEncodeable on: SessionOptions, SessionState, SessionConfiguration
  (ConfiguredEndpoint and IUserIdentity require manual encoding)
- Delete SessionStateEncoder.cs (488 lines removed)
- Remove [DataContract]/[DataMember]/[KnownType]/[CollectionDataContract] attributes
- Remove JsonSerializerContext classes
- Change init -> set, byte[] -> ByteString, DateTime -> DateTimeUtc
- MonitoredItems: ArrayOf<MonitoredItemState> with StructureHandling.Inline
- Subscriptions: ArrayOf<SubscriptionState>

* Source generator: support partial init properties with backing fields

Add IsInitOnly detection to the [DataType] source generator so that
partial properties with init-only setters can be used in IEncodeable types.

For each init-only partial property, the generator:
- Emits a private backing field (__PropertyName)
- Emits the partial property implementation (get => __field; init => __field = value)
- Uses the backing field in Decode() instead of the property
- Skips simple init-only fields in Clone() (record 'with' already copies them)
Detection uses both IPropertySymbol.SetMethod.IsInitOnly and syntax-tree
fallback (SyntaxKind.InitAccessorDeclaration) for partial definitions.
* docs: add partial init properties and session state migration sections

- SourceGeneratedDataTypes.md: new 'Partial Init Properties' section
  documenting backing field generation for init-only partial properties
- MigrationGuide.md: new 'Session State Persistence' section covering

Author: marcschier

Docs/MigrationGuide.md

@@ -43,6 +43,10 @@
       - [ExtensionObject array helpers changed](#extensionobject-array-helpers-changed)
     - [Complex Types](#complex-types)
       - [ComplexTypes moved to Opc.Ua.Client assembly](#complextypes-moved-to-opcuaclient-assembly)
+    - [Session and Browser State Persistence](#session-and-browser-state-persistence)
+      - [Property type changes](#property-type-changes)
+      - [`IUserIdentity` on `SessionOptions` is now computed](#iuseridentity-on-sessionoptions-is-now-computed)
+      - [Encoding format is not guaranteed backward compatible](#encoding-format-is-not-guaranteed-backward-compatible)
       - [OptionSet DataType support](#optionset-datatype-support)
     - [Other Breaking Changes](#other-breaking-changes)
   - [Migrating from 1.05.377 to 1.05.378](#migrating-from-105377-to-105378)
@@ -628,9 +632,55 @@ Impact on existing code:
 - No wire-format changes: encoders/decoders continue to route through `IEncodeableFactory` → `IEncodeableType.CreateInstance`, which now yields `Opc.Ua.Encoders.OptionSet` for registered sub-types.
 - UInteger-backed OptionSet DataTypes remain treated as their underlying unsigned integer in a `Variant` (unchanged).
 
-### Other Breaking Changes
+### Session and Browser State Persistence
 
-- **Session/Browser state format**: Persistence switched from `DataContractSerializer` XML to `BinaryEncoder`. Delete old persisted files and re-establish sessions.
+**Breaking Change**: Persistence switched from `DataContractSerializer` XML to `IEncoder` and `IDecoder`. `BrowserState`, `SessionState`, `SessionOptions`, `SubscriptionState`, and `MonitoredItemState` are annotated with `[DataType]` and use the standard `Encode`/`Decode` methods generated by the source generator.
+
+To register the state types with the encodeable factory:
+
+```csharp
+context.Factory.Builder.AddOpcUaClientDataTypes();
+```
+
+#### Property type changes
+
+The following property types have changed to use the new stack value types:
+
+| Class | Property | Old Type | New Type |
+|---|---|---|---|
+| `SessionState` | `ServerNonce` | `byte[]?` | `ByteString` |
+| `SessionState` | `ClientNonce` | `byte[]?` | `ByteString` |
+| `SessionState` | `ServerEccEphemeralKey` | `byte[]?` | `ByteString` |
+| `SessionState` | `Timestamp` | `DateTime` | `DateTimeUtc` |
+| `SessionState` | `Subscriptions` | `SubscriptionStateCollection?` | `ArrayOf<SubscriptionState>` |
+| `SubscriptionState` | `MonitoredItems` | `MonitoredItemStateCollection` | `ArrayOf<MonitoredItemState>` |
+| `SubscriptionState` | `Timestamp` | `DateTime` | `DateTimeUtc` |
+
+#### `IUserIdentity` on `SessionOptions` is now computed
+
+`SessionOptions.Identity` (`IUserIdentity?`) is no longer a serialized field. It is a computed property backed by `UserIdentityToken? IdentityToken`, which is the actual serialized field:
+
+```csharp
+public partial record class SessionOptions
+{
+    // Serialized field
+    [DataTypeField(Order = 2, StructureHandling = StructureHandling.ExtensionObject)]
+    public UserIdentityToken? IdentityToken { get; set; }
+
+    // Computed — not serialized
+    public IUserIdentity? Identity
+    {
+        get => IdentityToken != null ? new UserIdentity(IdentityToken) : null;
+        set => IdentityToken = value?.TokenHandler?.Token;
+    }
+}
+```
+
+When migrating code that previously set `Identity` directly, no code changes are required — the property still accepts `IUserIdentity`. However, if you were serializing session state manually, note that only `IdentityToken` round-trips through encode/decode.
+
+#### Encoding format is not guaranteed backward compatible
+
+The encoding format for session state has changed. Existing persisted session state files **cannot** be loaded by the new `SessionConfiguration.Create()` method. Handle restore failures and re-persist the new session state.
 
 ## Migrating from 1.05.377 to 1.05.378
 

Docs/SourceGeneratedDataTypes.md

@@ -477,6 +477,69 @@ public partial class SecuritySettings
 > `Exclude` would omit an explicit `false` on encode. `Include` ensures the
 > value always round-trips correctly.
 
+## Partial Init Properties
+
+The source generator supports `partial` properties with `init` accessors for
+immutable record types. This enables record classes with init-only properties
+to participate in OPC UA binary and XML encoding — the generator creates a
+private backing field for each such property and assigns to it directly during
+`Decode()`, bypassing the init-only constraint.
+
+### Example
+
+```csharp
+[DataType(Namespace = "urn:mycompany:myapp")]
+public partial record class DeviceConfig
+{
+    [DataTypeField(Order = 0)]
+    public partial string Name { get; init; } = "Default";
+
+    [DataTypeField(Order = 1)]
+    public partial int Port { get; init; }
+}
+```
+
+The generator produces:
+
+```csharp
+partial record class DeviceConfig : IEncodeable, IJsonEncodeable
+{
+    private string __Name = "Default";
+    public partial string Name { get => __Name; init => __Name = value; }
+
+    private int __Port;
+    public partial int Port { get => __Port; init => __Port = value; }
+
+    public virtual void Decode(IDecoder decoder)
+    {
+        // Assigns to backing field, bypassing init constraint
+        if (decoder.HasField("Name")) __Name = decoder.ReadString("Name");
+        if (decoder.HasField("Port")) __Port = decoder.ReadInt32("Port");
+    }
+    // ...
+}
+```
+
+### How It Works
+
+1. For each property declared as `partial` with an `init` accessor, the
+   generator emits a private backing field named `__<PropertyName>`.
+2. The partial property implementation delegates `get` and `init` to that
+   backing field.
+3. `Decode()` assigns to the backing field directly, which is legal because
+   the field is a regular mutable field — only the public `init` accessor is
+   restricted to object-initializer contexts.
+4. `Clone()` for record types uses `this with { }`, which copies init-only
+   properties automatically via the copy constructor.
+
+### When to Use
+
+- Use `partial` + `init` properties when you want an immutable public API
+  (callers can only set values at construction time) while still allowing
+  the decoder to populate the object from a binary or XML stream.
+- This is especially useful for configuration and options types modeled as
+  `record class`.
+
 ## Requirements and Constraints
 
 1. **Must be `partial`**: The class must be declared `partial` so the generator

Libraries/Opc.Ua.Client/Session/Session.cs

@@ -860,15 +860,15 @@ public virtual void Snapshot(out SessionState state)
             Snapshot(out SessionConfiguration configuration);
 
             // Snapshot subscription state
-            var subscriptionStateCollection = new SubscriptionStateCollection(SubscriptionCount);
+            var subscriptionStates = new List<SubscriptionState>(SubscriptionCount);
             foreach (Subscription subscription in Subscriptions)
             {
                 subscription.Snapshot(out SubscriptionState subscriptionState);
-                subscriptionStateCollection.Add(subscriptionState);
+                subscriptionStates.Add(subscriptionState);
             }
             state = new SessionState(configuration)
             {
-                Subscriptions = subscriptionStateCollection
+                Subscriptions = subscriptionStates
             };
         }
 
@@ -878,7 +878,7 @@ public virtual void Restore(SessionState state)
             using Activity? activity = m_telemetry.StartActivity();
             ThrowIfDisposed();
             Restore((SessionConfiguration)state);
-            if (state.Subscriptions == null)
+            if (state.Subscriptions.IsEmpty)
             {
                 return;
             }
@@ -894,11 +894,11 @@ public virtual void Restore(SessionState state)
         /// <inheritdoc/>
         public void Snapshot(out SessionConfiguration sessionConfiguration)
         {
-            byte[]? serverNonce = !m_serverNonce.IsEmpty ? m_serverNonce.ToArray() : null;
-            byte[]? clientNonce = m_clientNonce != null ? [.. m_clientNonce] : null;
-            byte[]? serverEccEphemeralKey = m_eccServerEphemeralKey?.Data != null
-                ? [.. m_eccServerEphemeralKey.Data]
-                : null;
+            ByteString serverNonce = !m_serverNonce.IsEmpty ? m_serverNonce : default;
+            ByteString clientNonce = m_clientNonce != null ? ByteString.From(m_clientNonce) : default;
+            ByteString serverEccEphemeralKey = m_eccServerEphemeralKey?.Data != null
+                ? ByteString.From([.. m_eccServerEphemeralKey.Data])
+                : default;
             sessionConfiguration = new SessionConfiguration
             {
                 SessionName = SessionName,
@@ -926,20 +926,20 @@ public void Restore(SessionConfiguration sessionConfiguration)
                     : null;
             m_identity = sessionConfiguration.Identity ?? new UserIdentity();
             m_checkDomain = sessionConfiguration.CheckDomain;
-            m_serverNonce = ByteString.From(sessionConfiguration.ServerNonce);
-            m_clientNonce = sessionConfiguration.ClientNonce != null
-                ? [.. sessionConfiguration.ClientNonce]
+            m_serverNonce = sessionConfiguration.ServerNonce;
+            m_clientNonce = !sessionConfiguration.ClientNonce.IsNull
+                ? sessionConfiguration.ClientNonce.ToArray()
                 : null;
             m_userTokenSecurityPolicyUri = sessionConfiguration.UserIdentityTokenPolicy;
-            if (sessionConfiguration.ServerEccEphemeralKey?.Length > 0)
+            if (sessionConfiguration.ServerEccEphemeralKey.Length > 0)
             {
                 string? ephemeralKeyPolicyUri = !string.IsNullOrEmpty(m_userTokenSecurityPolicyUri)
                     ? m_userTokenSecurityPolicyUri
                     : m_endpoint.Description?.SecurityPolicyUri ?? SecurityPolicies.None;
                 SecurityPolicyInfo ephemeralKeyPolicy = SecurityPolicies.GetInfo(ephemeralKeyPolicyUri);
                 m_eccServerEphemeralKey = Nonce.CreateNonce(
                     ephemeralKeyPolicy,
-                    sessionConfiguration.ServerEccEphemeralKey);
+                    sessionConfiguration.ServerEccEphemeralKey.ToArray());
             }
             else
             {
@@ -980,8 +980,7 @@ public SessionConfiguration SaveSessionConfiguration(Stream? stream = null)
                     null, context.NamespaceUris.ToArrayOf());
                 encoder.WriteStringArray(
                     null, context.ServerUris.ToArrayOf());
-                SessionStateEncoder.EncodeSessionConfiguration(
-                    encoder, sessionConfiguration);
+                sessionConfiguration.Encode(encoder);
             }
             return sessionConfiguration;
         }
@@ -994,11 +993,11 @@ public virtual void Save(
         {
             using Activity? activity = m_telemetry.StartActivity();
             // Snapshot subscription state
-            var subscriptionStateCollection = new SubscriptionStateCollection();
+            var subscriptionStates = new List<SubscriptionState>();
             foreach (Subscription subscription in subscriptions)
             {
                 subscription.Snapshot(out SubscriptionState state);
-                subscriptionStateCollection.Add(state);
+                subscriptionStates.Add(state);
             }
 
             IServiceMessageContext context = MessageContext
@@ -1009,10 +1008,10 @@ public virtual void Save(
                 null, context.NamespaceUris.ToArrayOf());
             encoder.WriteStringArray(
                 null, context.ServerUris.ToArrayOf());
-            encoder.WriteInt32(null, subscriptionStateCollection.Count);
-            foreach (SubscriptionState state in subscriptionStateCollection)
+            encoder.WriteInt32(null, subscriptionStates.Count);
+            foreach (SubscriptionState state in subscriptionStates)
             {
-                SessionStateEncoder.EncodeSubscriptionState(encoder, state);
+                state.Encode(encoder);
             }
         }
 
@@ -1043,8 +1042,8 @@ public virtual IEnumerable<Subscription> Load(
             var subscriptions = new SubscriptionCollection(count);
             for (int i = 0; i < count; i++)
             {
-                SubscriptionState state =
-                    SessionStateEncoder.DecodeSubscriptionState(decoder);
+                var state = new SubscriptionState();
+                state.Decode(decoder);
                 // Restore subscription from state
                 Subscription subscription = CreateSubscription(state);
                 subscription.Restore(state);