Akka.Serialization.V2: closed generic messages + manifest-discriminated union fields (PoC for #8384)

[Aaronontheweb]

Proof of concept for #8384

Implements both parts of the design in #8384 for the source-generated MessagePack serializer:

Part 1 — [AkkaSerializable<T>] closed generic messages. A generic [AkkaSerializable] type is never serialized as an open definition (a source generator cannot reify open generics — same rule STJ enforces). Each closed construction is registered on the [AkkaSerializer] module using a generic form of the same [AkkaSerializable] attribute with its own manifest; generic fields are extracted from the constructed symbol, so Roslyn's member substitution delivers T-typed properties already concretely typed. One rule: everything on the wire is [AkkaSerializable] — a closed construction just has no declaration site of its own, so its marking lives on the serializer class.

Part 2 — [AkkaUnion] closed, manifest-discriminated unions. A field whose static type is an interface/abstract base with a declared closed member set encodes structurally inline as { 1: manifest, 2: member fields } — the typed alternative to [AkkaEnvelopePayload] for payload sets known at compile time. The union member set is declared once on the union base type (field-level [AkkaUnion] remains as a per-field override); the existing serializer-owned manifest is the discriminator, so no new identity scheme is introduced. Write dispatch is exact-runtime-type: an undeclared subtype fails serialization instead of silently truncating to its base (STJ FailSerialization semantics).

The combined scenario — a generic wrapper with a polymorphic payload, fully typed with no object boundary:

[AkkaUnion(typeof(OrderPlaced), typeof(OrderCancelled), typeof(OrderNote))]
public interface IOrderEvent { }

[AkkaSerializable]
public sealed record EventWrapper<T>(
    [property: AkkaField(1)] string Id,
    [property: AkkaField(2)] T Body) : IMyProtocol;

[AkkaSerializer<IMyProtocol>("my-protocol", 1234)]
[AkkaSerializable<EventWrapper<IOrderEvent>>(Manifest = "event-wrap-v1")]
public sealed partial class MyProtocolSerializer : AkkaSerializer { }

The protocol marker moved off the base type and into [AkkaSerializer<TProtocol>] — it was always pure generator input (the runtime never used TProtocol), so the base class is now non-generic. It is also renamed MessagePackSerializer → AkkaSerializer: the old name collided with MessagePack.MessagePackSerializer (CS0104) once de-generified, and leaked the wire format into the type users inherit; the new name echoes the [AkkaSerializer<TProtocol>] attribute and keeps MessagePack an implementation detail.

Changes

• Consolidated attribute surface (5 names): [AkkaSerializer<TProtocol>], [AkkaSerializable] (+ generic form for closed constructions), [AkkaField], [AkkaUnion], plus the [AkkaEnvelopePayload]/[AkkaSerializerFormatter] escape hatches; base class de-generified and renamed to AkkaSerializer
• Diagnostics and generator internals use "closed generic registration" terminology throughout (no "instantiation" vocabulary survives the attribute it named)
• AkkaUnionAttribute: type-level declaration on the union base (stated once, inherited by every field of that type) + field-level override
• FieldKind.Union with generated dispatch helpers deduplicated by (static type, member set) signature; exact SizeHint for all member kinds
• Arity-aware field-type resolution and STJ-style folded generated member names (WriteWrapperOrderRequest) with AKKASG024 collision detection
• New diagnostics: AKKASG015–019 (union validation), AKKASG020–022 (closed-generic registrations / generic definitions), AKKASG023 (unregistered closed generic field), AKKASG024 (generated-name collisions), AKKASG025 (advisory: unsealed union member)
• Unbound-generic registration is unrepresentable by construction ([AkkaSerializable<Wrapper<>>] is not legal C#) — compiler error instead of analyzer diagnostic
• Migrates the Artery control-message serializer to the new surface (name/id/binding unchanged — wire compatible)
• Fixes a latent codegen bug: properties whose camel-cased name is a C# keyword (e.g. Event) generated uncompilable locals; now @-escaped

Testing

134/134 (27 new): round-trips for class/struct/nested-only union members, nullable unions, type-level inheritance + field-level narrowing override, wire-format byte assertions, undeclared type/subtype rejection, unknown-manifest and payload-ordering failures, forward-compat key skipping, closed-construction round-trips + manifest dispatch + nesting, the combined scenario, and 8 diagnostics specs. API approval tests pass; Akka.Remote builds clean.

Out of scope (follow-ups tracked in #8384)

• Cross-assembly union members / instantiation payloads (extraction is compilation-local today)
• Wire-format docs page and BREAKING_CHANGES entry if/when this graduates from PoC

Closes nothing — PoC for discussion on #8384.

---

Update (2026-07-16): illegal-states-unrepresentable hardening pass

Three follow-up commits from an adversarial audit of the surface (plus a CI fix — e0c71bfbb repairs the repo-wide NU1605 from the Azure image SDK roll; unrelated to this PR's code):

• c507f0f73 — name-bound hybrid construction on deserialize. Read-side reconstruction previously bound ctor args positionally in [AkkaField]-index order with no validation — same-typed properties whose index order differed from ctor order silently swapped values on round-trip. Now emits named arguments (ordinal, then unique case-insensitive matching) plus object-initializer assignments for settable/init leftovers, so init-only POCO shapes serialize too. New: AKKASG026 (no matching ctor), AKKASG027 (defaulted ctor param covered by no field — silent reset), AKKASG028 ([AkkaField] on static/inaccessible property). Generator-owned read locals are __-prefixed so property names like FieldCount can't collide.
• 1b2ea0116 — serializer-level validation. AKKASG029 (concrete protocol implementor missing [AkkaSerializable] — previously vanished silently from dispatch), AKKASG031 (same protocol bound by two serializers), AKKASG032 (serializer class must be partial/non-generic/derive from AkkaSerializer), AKKASG033 (protocol type must be an interface), AKKASG034 (closed-generic registration that neither implements the protocol nor is reachable from any message — dead registration). No AKKASG030 needed: the compiler already rejects duplicate [AkkaSerializer<T>] attributes via CS0579 even with different type args (pinned by test).
• 5ea975e30 — attribute reshapes. [AkkaSerializer<TProtocol>(string name, int serializerId)] — identity is now required and always explicit (no auto-ids: sourcegen ordering is nondeterministic and config-defined collisions are invisible to the generator); AKKASG001/002 demote to constant-validity checks. [AkkaUnion(Type first, params Type[] rest)] — empty union sets no longer compile. [AkkaSerializerFormatter<TTarget, TFormatter>] where TFormatter : IAkkaMessagePackFormatter<TTarget> — interface conformance is compiler-enforced; the null-target and interface-mismatch diagnostics are deleted as unrepresentable. Artery serializer and benchmarks migrated with byte-identical name/id bindings (wire compatible).

Diagnostics now span AKKASG001–034 (022 has structural gaps closed; 030 intentionally absent). 161/161 tests. Wire format unchanged throughout — byte-assertion specs untouched. Known follow-ups: incremental-pipeline discipline pass (cached models retain symbols; AKKASG029 couples the terminal stage to CompilationProvider), benchmark coverage for union/closed-generic dispatch paths.