feat: add t.variant for union dispatch when members share a typename

[jimmy-phantom]

Problem

The typename does two jobs: entity identity (the [typename, id] cache key) and union dispatch. When two union members share a typename, dispatch silently collapses to the last member:

class ImagePost extends Entity {
  __typename = t.typename('Post');
  id = t.id;
  kind = t.const('image');
  url = t.string;
}

class GalleryPost extends Entity {
  __typename = t.typename('Post');
  id = t.id;
  kind = t.const('gallery');
  images = t.array(t.entity(ImagePost));
}

// every payload parses as GalleryPost; image posts fail validation and are
// silently dropped from arrays, live membership, and mutation events
t.union(t.entity(ImagePost), t.entity(GalleryPost));

Change

t.variant(value) marks the tag field. Identity stays on the typename; dispatch uses the variant:

class ImagePost extends Entity {
  __typename = t.typename('Post'); // identity: cache key stays [Post, id]
  id = t.id;
  kind = t.variant('image');       // dispatch: selects the shape
  url = t.string;
}

• unions and t.liveArray dispatch on (typename, variant)
• live collections route events to the def matching the entity's variant
• registry merge treats the variant field as an enum of the variants' values
• t.variant validates like t.const and is not part of the cache key

Behavior changes (hence minor)

• Duplicate typenames in a union without variants now throw at definition time, instead of silent last-wins. Same for a duplicate (typename, variant) pair, mixed variant and non-variant members, and conflicting variant fields.
• t.liveValue over same-typename defs without variants routes events to the first def the entity satisfies, instead of always the last def.

Verification

• 17 new tests in variant-unions.test.ts: definition guards, parse dispatch, single-variant entity arrays, live membership per variant, liveValue multi-def routing
• full suite: 1264 passed, 2 skipped; tsc --noEmit clean; production build smoke-tested (variant dispatch works, duplicate guard throws)
• docs: new "Unions with Shared Typenames" section in core/types

🤖 Generated with Claude Code

[jimmy-phantom]

🤖 Automated review (Claude Code)

The mechanism holds up well on the primary paths: I verified parse dispatch, the definition-time guards, the registry enum merge, and per-variant live routing all behave as the PR and changeset describe, and the full unit suite passes. The inline comments cover one real bug in union composition (shared VariantGroup mutation), one routing inconsistency on the delete path, and one unreconciled runtime case (variant flips), each reproduced with a focused test.

Two smaller gaps live in code the diff does not touch:

• packages/fetchium/src/testing/auto-generate.ts: generateUnion only picks shape entries that are instanceof ValidatorDef, so VariantGroup entries are skipped and a variant-union field generates {} (verified), which cannot parse when the field is required.
• buildConstraintFieldRefs in packages/fetchium/src/typeDefs.ts keys per-class constraints by typename, so constraints: [[TextPost, {...}], [ThreadPost, {...}]] silently keeps only the last entry when the classes share a typename. Variant members are the first supported way to put two classes with one typename in the same liveArray, which makes this reachable.

[jimmy-phantom]

From the review summary: generateUnion now handles variant groups (446333c, with a test). The per-class constraint collapse in buildConstraintFieldRefs predates this PR; constrained variant unions remain a known limitation for a follow-up.

[jimmy-phantom]

🤖 Automated review (Claude Code)

Re-review of the fix round: the centralized addVariantDefToUnion merge, parse dispatch, delete-path resolution, and generator changes all check out. One new verified defect in live collection event routing, detailed inline.

[jimmy-phantom]

🤖 Automated review (Claude Code)

Follow-up pass over the round-3 changes and their consumers. Two new issues, both verified with focused repros: delete events bypass the new variant gating (corrupts t.liveValue reducer state), and the dev-mode merged-def compatibility check rejects structurally identical variant union fields.