Family surface: version-agnostic dispatch members on welded family bases

[skarndev]

What

Welded families — two or more welded classes deriving one welded base (the shape a versioned class template welded per range makes) — can gain a synthesized version-agnostic surface on the base: the member intersection the concretes bind identically, each member a type-switch dispatch to the concrete class. Pure managed text over the concretes' own accessors: no new thunks, no new P/Invokes, the shim is byte-identical.

Strictly opt-in, via the rod's own mark: the surface is synthesized only for a base carrying [[=welder::rods::csharp::family_surface]] (<welder/rods/csharp/marks.hpp>). An unmarked base is never touched, however hoistable its family's intersection is — synthesizing members onto a base is too intrusive to infer from structure alone. The mark deliberately lives in the rod, not welder core: no other backend honors it, so core vocabulary stays untouched (the welder pin remains main). A consumer whose welded headers must also parse without this rod (a Python-only build) spells the mark behind a build-driven macro that expands to nothing when the rod is absent — the pattern is documented in marks.hpp.

Hoist rules (for a marked base)

• Identical C# spellings hoist with the exact type (scalars, strings, the shared scalar-sequence wrappers), settable when every concrete's is.
• Welded-class members hoist as the member types' common welded base — the getter upcasts, the setter downcasts (InvalidCastException names a wrong-era assignment).
• Sequences of welded elements (vectors and fixed arrays) hoist as a read-only FamilyVector<ElementBase> live view: Count, indexer, duck-typed foreach over the concrete wrapper.
• Methods spelled identically on every concrete hoist as forwarding dispatch; a bare base instance throws InvalidOperationException from the default arm.
• Era-gated / shape-changing members stay on the concretes, reached by pattern matching.

Why

Downstream (wowlib), ForVersion(...) returned a family base that carried verbs but no data — every property access needed a downcast, and the dynamic wrappers consumers built around it were slow (DLR). This gives base-typed code the same intersection semantics Python gets from its union aliases, at type-switch cost in front of the same P/Invoke the concrete path makes.

Mechanics

The field/method emitters record each class's member manifest (names + resolved C# spellings, placeholders included) beside their emissions; the class writer flushes it into document::family_records along with the base's mark state; the render pass groups records by resolved first-welded-base and appends one partial class <Base> block per marked family after its namespace's declarations.

Tests

• Existing goldens are unchanged.
• family.hpp / gen_family.cpp + FamilyTests.cs lock the whole matrix: exact-type read/write, base-typed welded members incl. live-view write-through, FamilyVector iteration, wrong-era InvalidCastException, method dispatch, era-gated exclusion, bare-base throw — and the opt-in negative: an unmarked family whose perfectly hoistable intersection must synthesize nothing. 42 managed tests, full ctest suite 7/7, against stock welder main.

🤖 Generated with Claude Code