fix union with tokens

packages/emitter/src/emitter.ts

···
       return;
     }
 
-    // Only string enums can be added as defs
+    // Only string enums (including token refs) can be added as defs
     // Union refs (type: "union") must be inlined at usage sites
     if (unionDef.type === "string" && (unionDef.knownValues || unionDef.enum)) {
       const defName = name.charAt(0).toLowerCase() + name.slice(1);
···
         code: "union-refs-not-allowed-as-def",
         severity: "error",
         message:
-          `Named unions of model references cannot be defined as standalone defs. ` +
-          `Use @inline to inline them at usage sites, or use string enums instead.`,
+          `Named unions of non-token model references cannot be defined as standalone defs. ` +
+          `Use @inline to inline them at usage sites, use @token models for known values, or use string literals.`,
         target: union,
       });
     }
···
   private unionToLexiconProperty(
     unionType: Union,
     prop?: ModelProperty,
+    isDefining?: boolean,
   ): LexObjectProperty | null {
     const variants = this.parseUnionVariants(unionType);
 
···
       (variants.stringLiterals.length > 0 &&
         !variants.hasStringType &&
         variants.unionRefs.length === 0 &&
+        variants.knownValueRefs.length === 0 &&
         isClosed(this.program, unionType))
     ) {
       const isClosedUnion = isClosed(this.program, unionType);
···
       const minLength = getMinLength(this.program, unionType);
       const maxGraphemes = getMaxGraphemes(this.program, unionType);
       const minGraphemes = getMinGraphemes(this.program, unionType);
+
+      // Combine string literals and token refs for known values
+      const allKnownValues = [
+        ...variants.stringLiterals,
+        ...variants.knownValueRefs,
+      ];
+
       return {
         type: "string",
-        [isClosedUnion ? "enum" : "knownValues"]: variants.stringLiterals,
+        [isClosedUnion ? "enum" : "knownValues"]: allKnownValues,
         ...(propDesc && { description: propDesc }),
         ...(defaultValue !== undefined &&
           typeof defaultValue === "string" && { default: defaultValue }),
···
 
     // Model reference union (including empty union with unknown)
     if (variants.unionRefs.length > 0 || variants.hasUnknown) {
-      if (variants.stringLiterals.length > 0) {
+      if (variants.stringLiterals.length > 0 || variants.knownValueRefs.length > 0) {
         this.program.reportDiagnostic({
           code: "union-mixed-refs-literals",
           severity: "error",
           message:
-            `Union contains both model references and string literals. Lexicon unions must be either: ` +
-            `(1) model references only (type: "union"), ` +
-            `(2) string literals + string type (type: "string" with knownValues), or ` +
+            `Union contains both non-token model references and string literals/token refs. Lexicon unions must be either: ` +
+            `(1) non-token model references only (type: "union"), ` +
+            `(2) token refs + string literals + string type (type: "string" with knownValues), or ` +
             `(3) integer literals + integer type (type: "integer" with knownValues). ` +
             `Separate these into distinct fields or nested unions.`,
           target: unionType,
···
     const stringLiterals: string[] = [];
     const numericLiterals: number[] = [];
     const booleanLiterals: boolean[] = [];
+    const tokenModels: Model[] = [];
     let hasStringType = false;
     let hasUnknown = false;
 
     for (const variant of unionType.variants.values()) {
       switch (variant.type.kind) {
         case "Model":
-          const ref = this.getModelReference(variant.type as Model);
-          if (ref) unionRefs.push(ref);
+          const model = variant.type as Model;
+          // Collect token models separately - they're treated differently based on hasStringType
+          if (isToken(this.program, model)) {
+            tokenModels.push(model);
+          } else {
+            const ref = this.getModelReference(model);
+            if (ref) unionRefs.push(ref);
+          }
           break;
         case "String":
           stringLiterals.push((variant.type as StringLiteral).value);
···
       }
     }
 
+    // Validate: tokens must appear with | string
+    // Per Lexicon spec line 240: "unions can not reference token"
+    if (tokenModels.length > 0 && !hasStringType) {
+      this.program.reportDiagnostic({
+        code: "tokens-require-string",
+        severity: "error",
+        message:
+          "Tokens must be used with | string. Per Lexicon spec, tokens encode as string values and cannot appear in union refs.",
+        target: unionType,
+      });
+    }
+
+    // Token models become "known values" (always fully qualified refs)
+    const knownValueRefs = tokenModels
+      .map((m) => this.getModelReference(m, true))
+      .filter((ref): ref is string => ref !== null);
+
     const isStringEnum =
-      stringLiterals.length > 0 && hasStringType && unionRefs.length === 0;
+      (stringLiterals.length > 0 || knownValueRefs.length > 0) &&
+      hasStringType &&
+      unionRefs.length === 0;
 
     return {
       unionRefs,
       stringLiterals,
       numericLiterals,
       booleanLiterals,
+      knownValueRefs,
       hasStringType,
       hasUnknown,
       isStringEnum,
···
       }
     }
 
-    const unionDef = this.unionToLexiconProperty(unionType, prop);
+    const unionDef = this.unionToLexiconProperty(unionType, prop, isDefining);
     if (!unionDef) return null;
 
     // Inherit description from union if no prop description and union is @inline
···
     entity: Model | Union,
     name: string | undefined,
     namespace: Namespace | undefined,
+    fullyQualified = false,
   ): string | null {
     if (!name || !namespace || namespace.name === "TypeSpec") return null;
 
···
       });
     }
 
-    // Local reference (same namespace)
+    // For knownValues (fullyQualified=true), always use fully qualified refs
+    if (fullyQualified) {
+      return `${namespaceName}#${defName}`;
+    }
+
+    // Local reference (same namespace) - use short ref
     if (
       this.currentLexiconId === namespaceName ||
       this.currentLexiconId === `${namespaceName}.defs`
···
       return namespaceName;
     }
 
+    // All other refs use fully qualified format
     return `${namespaceName}#${defName}`;
   }
 
-  private getModelReference(model: Model): string | null {
-    return this.getReference(model, model.name, model.namespace);
+  private getModelReference(
+    model: Model,
+    fullyQualified = false,
+  ): string | null {
+    return this.getReference(model, model.name, model.namespace, fullyQualified);
   }
 
   private getUnionReference(union: Union): string | null {

packages/emitter/test/spec/basic/input/com/example/unionWithTokens.tsp

···
-import "@typelex/emitter";
-
-namespace com.example.unionWithTokens {
-  /** Tests union with token references */
-  model Main {
-    /** Reason can be a known token or unknown type */
-    @required
-    reason: (ReasonSpam | ReasonViolation | ReasonMisleading | unknown);
-  }
-
-  /** Spam: frequent unwanted promotion */
-  @token
-  model ReasonSpam {}
-
-  /** Direct violation of rules */
-  @token
-  model ReasonViolation {}
-
-  /** Misleading or deceptive content */
-  @token
-  model ReasonMisleading {}
-}

packages/emitter/test/spec/basic/output/com/example/unionWithTokens.json

···
-{
-  "lexicon": 1,
-  "id": "com.example.unionWithTokens",
-  "defs": {
-    "main": {
-      "type": "object",
-      "description": "Tests union with token references",
-      "required": ["reason"],
-      "properties": {
-        "reason": {
-          "type": "union",
-          "description": "Reason can be a known token or unknown type",
-          "refs": [
-            "#reasonSpam",
-            "#reasonViolation",
-            "#reasonMisleading"
-          ]
-        }
-      }
-    },
-    "reasonSpam": {
-      "type": "token",
-      "description": "Spam: frequent unwanted promotion"
-    },
-    "reasonViolation": {
-      "type": "token",
-      "description": "Direct violation of rules"
-    },
-    "reasonMisleading": {
-      "type": "token",
-      "description": "Misleading or deceptive content"
-    }
-  }
-}