fix(openapi3): missing discriminator mapping entry when first union variant causes circular emit (#10268)

## Problem

When a TypeSpec model uses `@discriminator` on a base type and all
subtypes are referenced through a named union, the first variant in the
union is silently dropped from the generated `discriminator.mapping` in
the OpenAPI output.

**Example:**

```typespec
@Discriminator("classification")
model Pokemon { classification: string; }

model NormalPokemon extends Pokemon { classification: "normal"; }
model LegendaryPokemon extends Pokemon { classification: "legendary"; }
model MythicalPokemon extends Pokemon { classification: "mythical"; }

union PokemonVariant {
  normal: NormalPokemon,
  legendary: LegendaryPokemon,
  mythical: MythicalPokemon,
}
```

**Generated (broken):**
```yaml
discriminator:
  propertyName: classification
  mapping:
    legendary: '#/components/schemas/LegendaryPokemon'
    mythical: '#/components/schemas/MythicalPokemon'
    # 'normal' is missing!
```

## Root Cause

`getDiscriminatorMapping` calls `emitTypeReference` for each derived
model. The first variant in the union (`NormalPokemon`) is already
mid-emission when `applyDiscriminator` runs — because emitting
`NormalPokemon` triggered the emission of its base `Pokemon`, which
immediately calls `applyDiscriminator`.

For a model that is currently being emitted, `emitTypeReference` returns
a `Placeholder` (to handle the circular reference). The existing code
does:

```ts
mapping[key] = (ref.value as any).$ref;
```

`Placeholder` has no `$ref` property, so this evaluates to `undefined`.
The `Placeholder` does resolve correctly later (via its `onValue`
callback mechanism), but nobody registered a listener to update the
mapping — so `mapping["normal"]` stays `undefined` and is silently
dropped during YAML serialisation.

The second and third variants (`LegendaryPokemon`, `MythicalPokemon`)
are not yet in the emit stack at this point, so their
`emitTypeReference` calls return proper declarations and their `$ref`
values are captured correctly.

## Fix

Check whether `ref.value` is a `Placeholder`. If so, register an
`onValue` listener that writes the resolved `$ref` into the mapping once
the circular reference unwinds. `Placeholder` is already imported in
this file.

```ts
getDiscriminatorMapping(variants: Map<string, Type>) {
  const mapping: Record<string, string> | undefined = {};
  for (const [key, model] of variants.entries()) {
    const ref = this.emitter.emitTypeReference(model);
    compilerAssert(ref.kind === "code", "Unexpected ref schema. Should be kind: code");
    if (ref.value instanceof Placeholder) {
      ref.value.onValue((resolvedValue) => {
        mapping[key] = (resolvedValue as any).$ref;
      });
    } else {
      mapping[key] = (ref.value as any).$ref;
    }
  }
  return mapping;
}
```

The `onValue` callback fires before YAML serialisation, so the mapping
object is complete by the time the output is written.

---------

Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>

Author: jensdev

.chronus/changes/fix-openapi3-discriminator-circular-emit-2026-4-13.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/openapi3"
+---
+
+Fix missing discriminator mapping entry when the first union variant causes a circular emit, affecting both the OpenAPI 3.0 and 3.2 emitters.

packages/openapi3/src/schema-emitter-3-2.ts

@@ -3,6 +3,7 @@ import {
   AssetEmitter,
   createAssetEmitter,
   ObjectBuilder,
+  Placeholder,
   TypeEmitter,
 } from "@typespec/asset-emitter";
 import { compilerAssert, DiscriminatedUnion, Type } from "@typespec/compiler";
@@ -98,7 +99,13 @@ export class OpenAPI32SchemaEmitter extends OpenAPI31SchemaEmitter {
     for (const [key, model] of variants.entries()) {
       const ref = this.emitter.emitTypeReference(model);
       compilerAssert(ref.kind === "code", "Unexpected ref schema. Should be kind: code");
-      mapping[key] = (ref.value as any).$ref;
+      if (ref.value instanceof Placeholder) {
+        ref.value.onValue((resolvedValue: any) => {
+          mapping[key] = (resolvedValue as any).$ref;
+        });
+      } else {
+        mapping[key] = (ref.value as any).$ref;
+      }
     }
     return mapping;
   }

packages/openapi3/src/schema-emitter.ts

@@ -720,7 +720,13 @@ export class OpenAPI3SchemaEmitterBase<
     for (const [key, model] of variants.entries()) {
       const ref = this.emitter.emitTypeReference(model);
       compilerAssert(ref.kind === "code", "Unexpected ref schema. Should be kind: code");
-      mapping[key] = (ref.value as any).$ref;
+      if (ref.value instanceof Placeholder) {
+        ref.value.onValue((resolvedValue) => {
+          mapping[key] = (resolvedValue as any).$ref;
+        });
+      } else {
+        mapping[key] = (ref.value as any).$ref;
+      }
     }
     return mapping;
   }

packages/openapi3/test/discriminator.test.ts

@@ -345,6 +345,33 @@ worksFor(supportedVersions, ({ checkFor, openApiFor }) => {
     ]);
   });
 
+  it("includes all variants in discriminator mapping when first union variant causes circular emit", async () => {
+    const openApi = await openApiFor(`
+      @discriminator("kind")
+      model Pet { kind: string; }
+
+      model Cat extends Pet { kind: "cat"; }
+      model Dog extends Pet { kind: "dog"; }
+      model Bird extends Pet { kind: "bird"; }
+
+      union PetVariant {
+        cat: Cat,
+        dog: Dog,
+        bird: Bird,
+      }
+
+      op read(): { @body body: PetVariant };
+      `);
+    deepStrictEqual(openApi.components.schemas.Pet.discriminator, {
+      propertyName: "kind",
+      mapping: {
+        cat: "#/components/schemas/Cat",
+        dog: "#/components/schemas/Dog",
+        bird: "#/components/schemas/Bird",
+      },
+    });
+  });
+
   it("discriminator always needs to be marked as required", async () => {
     const openApi = await openApiFor(`
      @discriminator("kind")