Module union

Union shape and factories.

Defines UnionShape and the union factory used to declare a polymorphic property that accepts more than one value type, as an exclusive disjunction (sh:xone) of value-shape variants. The variants are mutually exclusive alternatives, matched in two regimes: a state value on persistence singles out exactly one variant (sh:xone) by value, while a model placeholder on retrieval matches at least one by kind (sh:or), requesting each it fits; extends-time narrowing pairs each child variant with a single parent variant. Variant order is preserved for deterministic error reporting and drives the indexed Union form through which union-typed slots are addressed in retrieval templates.

Inheritance

When a ResourceShape extends a parent via extends, a union-typed property may drop variants and tighten the variants it keeps, but never add new ones. Narrowing is the construction-time counterpart of the union's exclusive discrimination: each child variant must narrow exactly one parent variant, where narrowing is the value-shape override relation that governs non-union shapes — matching kind (and datatype for string / number, plus pattern for string and integral for number), only-tightening constraints, and, for reference / resource, a matching target shape or a subtype class. The pairing is order-independent and injective; either form is rejected when a child variant narrows no parent variant (unsatisfiable), several (ambiguous), or a parent already taken by another child variant (split). The child's form fixes the outcome:

1. Single-variant narrowing (Form 1) — the child is a non-union value shape; it narrows its one parent variant and the result collapses to that merged shape, so the enclosing SetShape.shape is no longer a union.

2. Union subsetting (Form 2) — the child is a union; its variants each narrow a distinct parent variant, the paired variants are merged, unpaired parent variants are dropped, and the result stays a union.

The merged union's model re-indexes contiguously from 0, following parent order. Dropping a parent variant renumbers every later variant — consumers must key off the shape's own model, not assume positional alignment with an ancestor. Union-form templates ({"0": ..., "1": ...}) are interpreted against the current shape's variants; well-typed templates derived from Schema carry the correct indices automatically.