feat: add unsupported asset handling for mixed-version clusters (Gap 2.11)

Add Version property to StreamAssignment and ConsumerAssignment so future-version
entries from newer cluster peers are gracefully skipped rather than applied incorrectly.
ProcessStreamAssignment and ProcessConsumerAssignment now reject entries with
Version > CurrentVersion (1), incrementing SkippedUnsupportedEntries for operator
visibility. Add MetaEntryType.Unknown with a no-op ApplyEntry handler so unrecognised
RAFT entry types never crash the cluster. Version 0 is treated as current for
backward compatibility with pre-versioned assignments.

src/NATS.Server/JetStream/Cluster/ClusterAssignmentTypes.cs

@@ -119,6 +119,16 @@ public sealed class StreamAssignment
     public bool Recovering { get; set; }
     public bool Reassigning { get; set; }
 
+    /// <summary>
+    /// Schema version for forward-compatibility. Assignments with a version greater than
+    /// <see cref="JetStreamMetaGroup.CurrentVersion"/> are skipped so that an older node
+    /// does not crash when replaying a RAFT log produced by a newer cluster peer.
+    /// Version 0 is treated as equivalent to version 1 (backward compatibility with
+    /// pre-versioned assignments).
+    /// Go reference: jetstream_cluster.go — versioned assignment processing.
+    /// </summary>
+    public int Version { get; set; } = 1;
+
     /// <summary>
     /// Consumer assignments keyed by consumer name.
     /// Uses <see cref="JsonObjectCreationHandling.Populate"/> so the deserializer populates
@@ -141,4 +151,14 @@ public sealed class ConsumerAssignment
     public string ConfigJson { get; set; } = "{}";
     public bool Responded { get; set; }
     public bool Recovering { get; set; }
+
+    /// <summary>
+    /// Schema version for forward-compatibility. Assignments with a version greater than
+    /// <see cref="JetStreamMetaGroup.CurrentVersion"/> are skipped so that an older node
+    /// does not crash when replaying a RAFT log produced by a newer cluster peer.
+    /// Version 0 is treated as equivalent to version 1 (backward compatibility with
+    /// pre-versioned assignments).
+    /// Go reference: jetstream_cluster.go — versioned assignment processing.
+    /// </summary>
+    public int Version { get; set; } = 1;
 }

src/NATS.Server/JetStream/Cluster/JetStreamMetaGroup.cs

@@ -39,6 +39,10 @@ public sealed class JetStreamMetaGroup
     private int _leaderIndex = 1;
     private long _leadershipVersion = 1;
 
+    // Count of entries skipped due to unsupported version or unknown type.
+    // Go reference: jetstream_cluster.go — forward-compatibility skip counter.
+    private int _skippedUnsupportedEntries;
+
     public JetStreamMetaGroup(int nodes)
         : this(nodes, selfIndex: 1)
     {
@@ -50,6 +54,13 @@ public sealed class JetStreamMetaGroup
         _selfIndex = selfIndex;
     }
 
+    /// <summary>
+    /// The highest assignment schema version this node supports.
+    /// Assignments with a higher version are skipped rather than crashing the cluster.
+    /// Go reference: jetstream_cluster.go — versioned assignment handling for forward compatibility.
+    /// </summary>
+    public const int CurrentVersion = 1;
+
     /// <summary>
     /// Returns true when this node is the current meta-group leader.
     /// Go reference: jetstream_api.go:200-300 -- leader check before mutating operations.
@@ -79,6 +90,13 @@ public sealed class JetStreamMetaGroup
     /// </summary>
     public int ConsumerCount => _totalConsumerCount;
 
+    /// <summary>
+    /// Number of entries skipped because their version exceeds <see cref="CurrentVersion"/>
+    /// or their entry type is unknown. Allows operators to detect version skew in a mixed cluster.
+    /// Go reference: jetstream_cluster.go — forward-compatibility skip tracking.
+    /// </summary>
+    public int SkippedUnsupportedEntries => _skippedUnsupportedEntries;
+
     /// <summary>
     /// Total number of inflight stream proposals across all accounts.
     /// </summary>
@@ -417,7 +435,9 @@ public sealed class JetStreamMetaGroup
 
     /// <summary>
     /// Validates and processes a stream assignment.
-    /// Returns false if the assignment is invalid (empty name, null group).
+    /// Returns false if the assignment is invalid (empty name, null group) or if
+    /// the assignment's version exceeds <see cref="CurrentVersion"/> (forward-compatibility skip).
+    /// Version 0 is treated as version 1 for backward compatibility with pre-versioned entries.
     /// Idempotent: duplicate assignments for the same stream name are accepted.
     /// Go reference: jetstream_cluster.go:4541 processStreamAssignment.
     /// </summary>
@@ -426,6 +446,15 @@ public sealed class JetStreamMetaGroup
         if (string.IsNullOrEmpty(sa.StreamName) || sa.Group == null)
             return false;
 
+        // Version 0 means pre-versioned (treat as current). Versions above CurrentVersion
+        // are from a newer node and must be skipped to avoid corrupting cluster state.
+        var effectiveVersion = sa.Version == 0 ? CurrentVersion : sa.Version;
+        if (effectiveVersion > CurrentVersion)
+        {
+            Interlocked.Increment(ref _skippedUnsupportedEntries);
+            return false;
+        }
+
         AddStreamAssignment(sa);
         return true;
     }
@@ -473,7 +502,9 @@ public sealed class JetStreamMetaGroup
 
     /// <summary>
     /// Validates and processes a consumer assignment.
-    /// Returns false if the parent stream does not exist or consumer name is empty.
+    /// Returns false if the parent stream does not exist, consumer name is empty, or if
+    /// the assignment's version exceeds <see cref="CurrentVersion"/> (forward-compatibility skip).
+    /// Version 0 is treated as version 1 for backward compatibility with pre-versioned entries.
     /// Go reference: jetstream_cluster.go:5300 processConsumerAssignment.
     /// </summary>
     public bool ProcessConsumerAssignment(ConsumerAssignment ca)
@@ -481,6 +512,15 @@ public sealed class JetStreamMetaGroup
         if (string.IsNullOrEmpty(ca.ConsumerName) || string.IsNullOrEmpty(ca.StreamName))
             return false;
 
+        // Version 0 means pre-versioned (treat as current). Versions above CurrentVersion
+        // are from a newer node and must be skipped to avoid corrupting cluster state.
+        var effectiveVersion = ca.Version == 0 ? CurrentVersion : ca.Version;
+        if (effectiveVersion > CurrentVersion)
+        {
+            Interlocked.Increment(ref _skippedUnsupportedEntries);
+            return false;
+        }
+
         if (!_assignments.ContainsKey(ca.StreamName))
             return false;
 
@@ -606,6 +646,14 @@ public sealed class JetStreamMetaGroup
             case MetaEntryType.PeerRemove:
                 ProcessRemovePeer(name);
                 break;
+            case MetaEntryType.Unknown:
+            default:
+                // Unknown or future entry types are counted and skipped.
+                // This prevents an older node from crashing when it encounters a RAFT entry
+                // produced by a newer cluster peer.
+                // Go reference: jetstream_cluster.go — forward-compatibility fallback.
+                Interlocked.Increment(ref _skippedUnsupportedEntries);
+                break;
         }
     }
 
@@ -932,6 +980,13 @@ public enum MetaEntryType
     /// Go reference: jetstream_cluster.go processRemovePeer.
     /// </summary>
     PeerRemove,
+    /// <summary>
+    /// Sentinel value for an unrecognised entry type received from a newer cluster peer.
+    /// Applying an Unknown entry increments <see cref="JetStreamMetaGroup.SkippedUnsupportedEntries"/>
+    /// and is otherwise a no-op, ensuring forward compatibility without crashing.
+    /// Go reference: jetstream_cluster.go — unknown entry type graceful handling.
+    /// </summary>
+    Unknown,
 }
 
 public sealed class MetaGroupState