feat(osgen)!: decode unions by the spec's discriminator, and name them after their schema

osgen never read the OpenAPI `discriminator`. Eight schemas in the spec declare
one, and every branch of all eight resolves to a distinct value, so 146 subtypes
that the payload names outright were instead decoded by guesswork: a JSON
token-class heuristic, or for the ambiguous ones no decoding at all until a
caller picked a branch by hand.

The discriminator is how OpenAPI expresses polymorphism, and the spec encodes
the hierarchy through allOf: a subtype is `allOf[Base, {type: enum[keyword]}]`,
so resolving a discriminant means walking allOf transitively -- the constant
sits on the narrowing member while the inherited fields come from the base.
discriminatorValues does that, and refuses the whole union unless every branch
resolves distinctly, so a partially-understood schema falls back rather than
emitting a decoder with an unreachable case.

Six emitted unions gain a real Type(), discriminant consts, and an UnmarshalJSON
that reads one property and decodes exactly that branch: CommonMappingProperty
(on `type`, with the spec's x-default naming the implicit object mapping),
CommonAnalysis{Analyzer,CharFilterDefinition,TokenFilterDefinition,
TokenizerDefinition,Normalizer}, plus ClusterRemoteInfoCluster on `mode`. A
value naming no branch is an error rather than a silent mis-decode.
MovingAverageAggregation also declares one but is request-body-only and never
emitted.

A $ref'd union was keyed by the caller's field path, so a shared schema was
re-emitted once per referencing field and its identity -- along with its
discriminator -- was discarded: _common.analysis___Analyzer became
IndicesIndexSettingsAnalysisAnalyzerValue, named after the single field that
happened to reach it. A $ref'd schema now keeps its own name and is emitted
once. That collapses 212 unions to 122, and the removals are consolidations
rather than losses: 138 redundant copies of 87 distinct shapes become 35 copies
of 91 shapes, with more distinct shapes surviving than before. Spec $ref counts
show the fan-in -- Script 33, StringOrStringArray 19, FieldValue 17, Sort 17.

ClusterRemoteInfoResp drops out of the json.RawMessage allowlist: it was an
untyped map and is now the typed, discriminated union.

Accessors on a request-selected union no longer lie. AsSum() against histogram
bytes returned a zero Sum with a nil error, indistinguishable from a real zero,
because encoding/json ignores unknown keys and a decode-error check cannot see
the mismatch; a required-property probe now rejects it. Constructors for a
discriminated branch also left the discriminant field empty, so a
marshal-unmarshal round trip failed on an empty discriminator.

Branch names come from the schema key's local segment rather than the qualified
Go type, so a const does not restate the group prefix its union name already
carries. Where a `<Union><Branch>Type` const would collide with a `<Union>Type`
enum type -- three analysis unions with a `Definition` branch beside a
`<Thing>Definition` union -- the branch is renamed, scoped to $ref branches so
inline branches keep their construction.

Vocabulary follows the spec instead of the decode mechanism. IsLazy and
LazyAccessors named a strategy while conflating two unrelated situations, "the
spec provides no discriminator" with "we never read the discriminator", and
become RequestSelected: the aggregation and suggest unions carry
x-supports-typed-keys and genuinely cannot be discriminated, since the branch is
chosen by the request and echoed only in the response map key. TypeLazyUnion
becomes TypeAmbiguousWire, unionNeedsTryEach becomes
branchesCollideOnTokenClass, resolveParentScopedUnion becomes resolveRefUnion.
TokenClass stays, documented as the fallback it is rather than the primary
strategy.

BREAKING CHANGE: 135 union types are removed and 45 added as $ref'd schemas
consolidate onto their spec names. MGetRespBodyDocsItem becomes MGetRespItem,
MSearchMultiSearchResultResponsesItem becomes MSearchRespItem, SortResultsItem
and CommonAggregationsCompositeAggregateKeyValue become FieldValue,
ErrorCauseHeaderValue becomes StringOrStringArray,
SearchResultAggregationsValue becomes CommonAggregationsAggregate, and
CatRecoveryRecord{Start,Stop}TimeMillis with
Replication{,Index}FollowerStatusTotalWriteTimeMillis become
StringifiedEpochTimeUnitMillis. SearchHitsMetadataTotal.SearchTotalHits becomes
TotalHits. Branch accessors lose the group prefix the union name already
carries, so MGetMultiGetError becomes MultiGetError. The six discriminated
unions gain a Type() and consts they did not have. UnionBranchError gains Err
and Unwrap, and Got may be "incompatible payload" when the payload cannot be
the requested branch.

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

cmd/osgen/api_render_union.go

@@ -8,9 +8,21 @@ package main
 
 import "github.com/opensearch-project/opensearch-go/v5/cmd/osgen/ir"
 
-// unionNeedsTryEach returns true if any two branches share the same token class,
-// meaning byte-prefix discrimination is insufficient for at least one pair.
-func unionNeedsTryEach(branches []unionBranch) bool {
+// branchesCollideOnTokenClass reports whether any two branches decode from the
+// same JSON token, which makes the first byte insufficient to pick one.
+//
+// This is the FALLBACK test, consulted only for unions the spec leaves
+// undiscriminated. A union that declares an OpenAPI `discriminator` reads its
+// branch from a named property (see discriminatorValues) and never consults the
+// token class at all -- most of the OpenSearch DSL unions are all-object and so
+// collide here trivially, which is exactly why the spec bothers to declare a
+// discriminator for them.
+//
+// When branches DO collide and no discriminator resolves, the union is
+// ir.TypeAmbiguousWire and classifyUnions picks the payload-inspection strategy:
+// a key-presence merge, request selection, or the try-each decoder of last
+// resort.
+func branchesCollideOnTokenClass(branches []unionBranch) bool {
 	if len(branches) < 2 {
 		return false
 	}

cmd/osgen/emit/build.go

@@ -202,8 +202,8 @@ func Build(spec *ir.Spec, cfg BuildConfig) []Target {
 }
 
 // splitUnionsFromSiblings partitions a sibling-types list into struct-shape
-// types and discriminated unions. Unions need the UnionFragment template
-// (which renders Type/branch accessors and try-each unmarshal); structs go
+// types and unions. Unions need the UnionFragment template
+// (which renders Type/branch accessors and the decode strategy); structs go
 // through SiblingTypesFragment. Without this split, a union sibling
 // rendered as a struct emits as `type Foo struct {}` because its Branches
 // aren't Fields.
@@ -212,7 +212,7 @@ func Build(spec *ir.Spec, cfg BuildConfig) []Target {
 func splitUnionsFromSiblings(types []*ir.Type) ([]*ir.Type, []*ir.Type) {
 	var structs, unions []*ir.Type
 	for _, st := range types {
-		if st.Kind == ir.TypeUnion || st.Kind == ir.TypeLazyUnion {
+		if st.Kind == ir.TypeUnion || st.Kind == ir.TypeAmbiguousWire {
 			unions = append(unions, st)
 		} else {
 			structs = append(structs, st)

cmd/osgen/emit/build_test.go

@@ -54,15 +54,15 @@ func TestSplitUnionsFromSiblings(t *testing.T) {
 		},
 		{
 			name:        "all unions (lazy)",
-			input:       []*ir.Type{{Name: "A", Kind: ir.TypeLazyUnion}, {Name: "B", Kind: ir.TypeLazyUnion}},
+			input:       []*ir.Type{{Name: "A", Kind: ir.TypeAmbiguousWire}, {Name: "B", Kind: ir.TypeAmbiguousWire}},
 			wantStructs: 0,
 			wantUnions:  2,
 		},
 		{
 			name: "mixed -- the ReindexSourceSort case",
 			input: []*ir.Type{
 				{Name: "ReindexSource", Kind: ir.TypeStruct},
-				{Name: "ReindexSourceSort", Kind: ir.TypeLazyUnion},
+				{Name: "ReindexSourceSort", Kind: ir.TypeAmbiguousWire},
 				{Name: "ReindexRemoteSource", Kind: ir.TypeStruct},
 				{Name: "ReindexSourceSlice", Kind: ir.TypeStruct},
 			},
@@ -72,7 +72,7 @@ func TestSplitUnionsFromSiblings(t *testing.T) {
 		{
 			name: "mixed strict + lazy unions",
 			input: []*ir.Type{
-				{Name: "Lazy", Kind: ir.TypeLazyUnion},
+				{Name: "RequestSel", Kind: ir.TypeAmbiguousWire},
 				{Name: "Struct", Kind: ir.TypeStruct},
 				{Name: "Strict", Kind: ir.TypeUnion},
 			},
@@ -95,10 +95,10 @@ func TestSplitUnionsFromSiblings(t *testing.T) {
 			// Verify no struct ended up in unions and vice versa.
 			for _, s := range structs {
 				require.NotEqual(t, ir.TypeUnion, s.Kind, "struct slice contains union %q", s.Name)
-				require.NotEqual(t, ir.TypeLazyUnion, s.Kind, "struct slice contains lazy union %q", s.Name)
+				require.NotEqual(t, ir.TypeAmbiguousWire, s.Kind, "struct slice contains lazy union %q", s.Name)
 			}
 			for _, u := range unions {
-				require.Contains(t, []ir.TypeKind{ir.TypeUnion, ir.TypeLazyUnion}, u.Kind, "union slice contains non-union %q", u.Name)
+				require.Contains(t, []ir.TypeKind{ir.TypeUnion, ir.TypeAmbiguousWire}, u.Kind, "union slice contains non-union %q", u.Name)
 			}
 		})
 	}

cmd/osgen/emit/export_test.go

@@ -44,7 +44,7 @@ func UnionFromResponses(resp *ir.Type, reg *ir.TypeRegistry) (string, string, st
 }
 
 // ResolveUnionShape mirrors UnionFromResponses for direct calls
-// against a TypeUnion / TypeLazyUnion (skipping the Responses-field
+// against a TypeUnion / TypeAmbiguousWire (skipping the Responses-field
 // indirection). Returns (unionName, success, errorBranch).
 func ResolveUnionShape(t *ir.Type, reg *ir.TypeRegistry) (string, string, string) {
 	u := resolveUnionShape(t, reg)

cmd/osgen/emit/frag_dispatch.go

@@ -233,7 +233,7 @@ func elementTypeHasShards(goType string, reg *ir.TypeRegistry) bool {
 	}
 	// Element is a discriminated union -- delegate to union resolution
 	// to see whether any branch carries Shards.
-	if resolved.Kind == ir.TypeLazyUnion || resolved.Kind == ir.TypeUnion {
+	if resolved.Kind == ir.TypeAmbiguousWire || resolved.Kind == ir.TypeUnion {
 		return resolveUnionShape(resolved, reg).success != ""
 	}
 	return false
@@ -288,13 +288,13 @@ type unionShape struct {
 	errorBranch string // error branch accessor Name (Status + Error), or ""
 }
 
-// resolveUnionShape walks a TypeLazyUnion/TypeUnion's branches and
+// resolveUnionShape walks a TypeAmbiguousWire/TypeUnion's branches and
 // classifies them. Branches whose resolved type has a Shards field
 // become the success branch; branches with both Status and Error
 // fields become the error branch. Returns zero-value if the type isn't
 // a union or no branches matched.
 func resolveUnionShape(t *ir.Type, reg *ir.TypeRegistry) unionShape {
-	if t == nil || (t.Kind != ir.TypeLazyUnion && t.Kind != ir.TypeUnion) {
+	if t == nil || (t.Kind != ir.TypeAmbiguousWire && t.Kind != ir.TypeUnion) {
 		return unionShape{}
 	}
 	out := unionShape{unionName: t.Name}
@@ -654,7 +654,7 @@ func unionFromResponses(resp *ir.Type, reg *ir.TypeRegistry) unionShape {
 	if !ok {
 		return unionShape{}
 	}
-	if resolved.Kind != ir.TypeLazyUnion && resolved.Kind != ir.TypeUnion {
+	if resolved.Kind != ir.TypeAmbiguousWire && resolved.Kind != ir.TypeUnion {
 		return unionShape{}
 	}
 	return resolveUnionShape(resolved, reg)

cmd/osgen/emit/frag_dispatch_helpers_test.go

@@ -275,7 +275,7 @@ func TestElementTypeHasShards(t *testing.T) {
 	regType(reg, &ir.Type{
 		Name:  "ItemUnion",
 		Scope: ir.ScopeLocal,
-		Kind:  ir.TypeLazyUnion,
+		Kind:  ir.TypeAmbiguousWire,
 		Branches: []ir.UnionBranch{
 			{Name: "ShardBranch", GoType: "ShardBranch"},
 			{Name: "ErrBranch", GoType: "ErrBranch"},
@@ -446,7 +446,7 @@ func TestResolveUnionShape(t *testing.T) {
 			name: "union with Shards + Status/Error branches",
 			input: &ir.Type{
 				Name: "ItemUnion",
-				Kind: ir.TypeLazyUnion,
+				Kind: ir.TypeAmbiguousWire,
 				Branches: []ir.UnionBranch{
 					{Name: "ShardBranch", GoType: "ShardBranch"},
 					{Name: "ErrBranch", GoType: "ErrBranch"},
@@ -460,7 +460,7 @@ func TestResolveUnionShape(t *testing.T) {
 			name: "union with only success branch",
 			input: &ir.Type{
 				Name: "OnlyShard",
-				Kind: ir.TypeLazyUnion,
+				Kind: ir.TypeAmbiguousWire,
 				Branches: []ir.UnionBranch{
 					{Name: "ShardBranch", GoType: "ShardBranch"},
 					{Name: "PlainBranch", GoType: "PlainBranch"},
@@ -473,7 +473,7 @@ func TestResolveUnionShape(t *testing.T) {
 			name: "branch type not in registry is skipped",
 			input: &ir.Type{
 				Name: "Mixed",
-				Kind: ir.TypeLazyUnion,
+				Kind: ir.TypeAmbiguousWire,
 				Branches: []ir.UnionBranch{
 					{Name: "Missing", GoType: "Missing"},
 					{Name: "ShardBranch", GoType: "ShardBranch"},
@@ -507,7 +507,7 @@ func TestUnionFromResponses(t *testing.T) {
 	regType(reg, &ir.Type{
 		Name:  "MsearchItemUnion",
 		Scope: ir.ScopeLocal,
-		Kind:  ir.TypeLazyUnion,
+		Kind:  ir.TypeAmbiguousWire,
 		Branches: []ir.UnionBranch{
 			{Name: "Item", GoType: "Item"},
 		},

cmd/osgen/emit/frag_shared_types.go

@@ -100,7 +100,7 @@ func NewSharedTypesFile(outDir, pkg string, types []*ir.Type) Target {
 func NewUnionTypesFile(outDir, pkg string, types []*ir.Type) Target {
 	var unionTypes []*ir.Type
 	for _, t := range types {
-		if (t.Kind == ir.TypeUnion || t.Kind == ir.TypeLazyUnion) && t.Scope == ir.ScopeShared {
+		if (t.Kind == ir.TypeUnion || t.Kind == ir.TypeAmbiguousWire) && t.Scope == ir.ScopeShared {
 			unionTypes = append(unionTypes, t)
 		}
 	}
@@ -127,7 +127,7 @@ func NewEnumTypesFile(outDir, pkg string, types []*ir.Type) Target {
 			enumTypes = append(enumTypes, t)
 		case ir.TypeStringEnum:
 			stringEnumTypes = append(stringEnumTypes, t)
-		case ir.TypeStruct, ir.TypeUnion, ir.TypeLazyUnion:
+		case ir.TypeStruct, ir.TypeUnion, ir.TypeAmbiguousWire:
 			// Emitted by other fragments (SharedTypesFragment / UnionFragment).
 		}
 	}