@typespec/compiler 1.18.0-dev.4 → 1.18.0-dev.6

package/dist/src/core/types.d.ts

@@ -3,23 +3,34 @@ import type { ModuleResolutionResult } from "../module-resolver/index.js";
 import type { FileRef } from "./file-ref.js";
 import type { Numeric } from "./numeric.js";
 import type { Program } from "./program.js";
-export type MarshalledValue<Value> = Value extends StringValue ? string : Value extends NumericValue ? number | Numeric : Value extends BooleanValue ? boolean : Value extends ObjectValue ? Record<string, unknown> : Value extends ArrayValue ? unknown[] : Value extends EnumValue ? EnumMember : Value extends NullValue ? null : Value extends ScalarValue ? Value : Value;
 /**
- * Type System types
+ * JavaScript-facing type mapping for compiler values.
+ * Numeric values may use {@link Numeric} to preserve precision, while scalar constructor values
+ * retain their compiler representation.
  */
+export type MarshalledValue<Value> = Value extends StringValue ? string : Value extends NumericValue ? number | Numeric : Value extends BooleanValue ? boolean : Value extends ObjectValue ? Record<string, unknown> : Value extends ArrayValue ? unknown[] : Value extends EnumValue ? EnumMember : Value extends NullValue ? null : Value extends ScalarValue ? Value : Value;
+/** Type or primitive argument accepted by legacy decorator implementations. */
 export type DecoratorArgumentValue = Type | number | string | boolean;
+/** A checked decorator argument, retaining both its compiler entity and JavaScript representation. */
 export interface DecoratorArgument {
+    /** Type or value before marshalling for the decorator implementation. */
     value: Type | Value;
     /**
      * Marshalled value for use in Javascript.
      */
     jsValue: Type | Value | Record<string, unknown> | unknown[] | string | number | boolean | Numeric | null;
+    /** Argument expression, when the application originates in TypeSpec source. */
     node?: Node;
 }
+/** A decorator application attached to a type, including its checked arguments. */
 export interface DecoratorApplication {
+    /** TypeSpec declaration, if the decorator has a corresponding declaration. */
     definition?: Decorator;
+    /** JavaScript implementation invoked when the decorated type is finished. */
     decorator: DecoratorFunction;
+    /** Custom arguments in call order, excluding the decorator context and target. */
     args: DecoratorArgument[];
+    /** Source application, or absent for a programmatically constructed application. */
     node?: DecoratorExpressionNode | AugmentDecoratorStatementNode;
 }
 /**
@@ -27,10 +38,14 @@ export interface DecoratorApplication {
  * Use `@typespec/tspd` to generate an accurate signature from the `extern dec`
  */
 export interface DecoratorFunction {
+    /** Apply the decorator to its target and optionally register deferred validation. */
     (context: DecoratorContext, target: any, ...customArgs: any[]): DecoratorValidatorCallbacks | void;
+    /** Namespace associated with a JavaScript decorator export. */
     namespace?: string;
 }
+/** Deferred decorator validation that returns diagnostics without mutating the type graph. */
 export type ValidatorFn = () => readonly Diagnostic[];
+/** Validation hooks returned by a decorator to run after target or graph construction. */
 export interface DecoratorValidatorCallbacks {
     /**
      * Run validation after all decorators are run on the same type. Useful if trying to validate this decorator is compatible with other decorators without relying on the order they are applied.
@@ -43,11 +58,18 @@ export interface DecoratorValidatorCallbacks {
      */
     readonly onGraphFinish?: ValidatorFn;
 }
+/** Common identity and construction state shared by semantic types in the compiler graph. */
 export interface BaseType {
+    /** Distinguishes semantic types from values and parameter constraints. */
     readonly entityKind: "Type";
+    /** Discriminant identifying the concrete semantic type. */
     kind: string;
     /** Node used to construct this type. If the node is undefined it means the type was dynamically built. With typekit for example. */
     node?: Node;
+    /**
+     * Legacy instantiation metadata. The compiler's type checker does not populate this field,
+     * so its absence does not indicate whether this type is a template instance.
+     */
     instantiationParameters?: Type[];
     /**
      * If the type is currently being created.
@@ -62,20 +84,29 @@ export interface BaseType {
      */
     isFinished: boolean;
 }
+/** A semantic type that can carry decorator applications. */
 export interface DecoratedType {
+    /** Applications used when finishing this type, including copied or synthesized applications. */
     decorators: DecoratorApplication[];
 }
 /**
  * Union of all the types that implement TemplatedTypeBase
  */
 export type TemplatedType = Model | Operation | Interface | Union | Scalar;
+/** Substitutes template parameters with arguments while constructing a template instance. */
 export interface TypeMapper {
+    /** Whether enclosing arguments have been applied but this template is not fully instantiated. */
     partial: boolean;
+    /** Return the mapped argument, or the original parameter when no substitution is available. */
     getMappedType(type: TemplateParameter): Type | Value | IndeterminateEntity;
+    /** Arguments for this instantiation, with enclosing template arguments first. */
     args: readonly (Type | Value | IndeterminateEntity)[];
 }
+/** Instantiation metadata carried by types that support template parameters. */
 export interface TemplatedTypeBase {
+    /** Argument substitutions for an instantiation; absent on an uninstantiated declaration. */
     templateMapper?: TypeMapper;
+    /** Originating template node, when retained separately from the type's source node. */
     templateNode?: Node;
 }
 /**
@@ -85,18 +116,29 @@ export interface TemplatedTypeBase {
  * - Value Constraints
  */
 export type Entity = Type | Value | MixedParameterConstraint | IndeterminateEntity;
+/** Semantic type graph nodes, including declarations, members, literals, and template placeholders. */
 export type Type = BooleanLiteral | Decorator | FunctionType | Enum | EnumMember | FunctionParameter | Interface | IntrinsicType | Model | ModelProperty | Namespace | NumericLiteral | Operation | Scalar | ScalarConstructor | StringLiteral | StringTemplate | StringTemplateSpan | TemplateParameter | TemplateParameterAccess | Tuple | Union | UnionVariant;
+/** Standard-library types available by name through {@link Checker.getStdType}. */
 export type StdTypes = {
+    /** Generic standard model for integer-indexed collections. */
     Array: Model;
+    /** Generic standard model for string-indexed collections. */
     Record: Model;
 } & Record<IntrinsicScalarName, Scalar>;
+/** Names accepted when looking up a standard-library type. */
 export type StdTypeName = keyof StdTypes;
 export interface ObjectType extends BaseType {
     kind: "Object";
     properties: Record<string, Type>;
 }
+/**
+ * A parameter constraint with independent type and value alternatives.
+ * A `valueof` alternative constrains a value's type rather than accepting the type itself.
+ */
 export interface MixedParameterConstraint {
+    /** Distinguishes this constraint from a type, value, or unresolved literal entity. */
     readonly entityKind: "MixedParameterConstraint";
+    /** Source expression defining the constraint, when available. */
     readonly node?: UnionExpressionNode | Expression;
     /** Type constraints */
     readonly type?: Type;
@@ -105,54 +147,84 @@ export interface MixedParameterConstraint {
 }
 /** When an entity that could be used as a type or value has not figured out if it is a value or type yet. */
 export interface IndeterminateEntity {
+    /** Identifies an entity whose type-versus-value interpretation is not yet selected. */
     readonly entityKind: "Indeterminate";
+    /** Literal-like type from which a type or value can be selected by the surrounding context. */
     readonly type: StringLiteral | StringTemplate | NumericLiteral | BooleanLiteral | EnumMember | UnionVariant | NullType;
 }
+/** Compiler-defined special type, rather than a declaration in the standard library. */
 export interface IntrinsicType extends BaseType {
+    /** Discriminant shared by the compiler's special types. */
     kind: "Intrinsic";
+    /** Identifies the special type and its assignability semantics. */
     name: "ErrorType" | "void" | "never" | "unknown" | "null";
 }
+/** Error-recovery type used when checking cannot produce a valid type. */
 export interface ErrorType extends IntrinsicType {
     name: "ErrorType";
 }
+/** An operation result with no return value. */
 export interface VoidType extends IntrinsicType {
     name: "void";
 }
+/** Bottom type with no possible values, assignable to every type. */
 export interface NeverType extends IntrinsicType {
     name: "never";
 }
+/** Top type accepting any type without imposing a more specific constraint. */
 export interface UnknownType extends IntrinsicType {
     name: "unknown";
 }
+/** Singleton type of the `null` value, distinct from an operation returning `void`. */
 export interface NullType extends IntrinsicType {
     name: "null";
 }
+/** Names of the built-in scalars exposed through the compiler's standard-type lookup. */
 export type IntrinsicScalarName = "bytes" | "numeric" | "integer" | "float" | "int64" | "int32" | "int16" | "int8" | "uint64" | "uint32" | "uint16" | "uint8" | "safeint" | "float32" | "float64" | "decimal" | "decimal128" | "string" | "plainDate" | "plainTime" | "utcDateTime" | "offsetDateTime" | "duration" | "boolean" | "url";
+/** An indexer shape that admits no keys and consequently has no value type. */
 export type NeverIndexer = {
+    /** Bottom type, allowing no indexed keys. */
     readonly key: NeverType;
+    /** No value type exists for an indexer without keys. */
     readonly value: undefined;
 };
+/** Key and element constraints for an indexed model such as an array or record. */
 export type ModelIndexer = {
+    /** Scalar constraining keys; standard arrays use `integer` and records use `string`. */
     readonly key: Scalar;
+    /** Type required for indexed values. */
     readonly value: Type;
 };
+/** Model narrowed by {@link isArrayModelType} to have an integer-keyed indexer. */
 export interface ArrayModelType extends Model {
+    /** Indexer describing the array's element type. */
     indexer: {
+        /** Integer key scalar used for array positions. */
         key: Scalar;
+        /** Type of each array element. */
         value: Type;
     };
 }
+/** Model narrowed by {@link isRecordModelType} to have a string-keyed indexer. */
 export interface RecordModelType extends Model {
+    /** Indexer describing values associated with record keys. */
     indexer: {
+        /** String key scalar used for record entries. */
         key: Scalar;
+        /** Type of each record entry. */
         value: Type;
     };
 }
+/** Structured type with ordered own properties, optional indexing, and model inheritance. */
 export interface Model extends BaseType, DecoratedType, TemplatedTypeBase {
+    /** Discriminant for structured model types. */
     kind: "Model";
+    /** Declared name, or an empty string for an anonymous model. */
     name: string;
     node?: ModelStatementNode | ModelDeclarationExpressionNode | ModelExpressionNode | IntersectionExpressionNode | ObjectLiteralNode;
+    /** Namespace containing a named declaration, when associated with one. */
     namespace?: Namespace;
+    /** Constraint on indexed entries, if this model supports indexing. */
     indexer?: ModelIndexer;
     /**
      * Whether this model was declared in expression position (e.g. an anonymous
@@ -189,6 +261,7 @@ export interface Model extends BaseType, DecoratedType, TemplatedTypeBase {
      */
     sourceModels: SourceModel[];
 }
+/** Records a model-composition input separately from the model's inheritance relationship. */
 export interface SourceModel {
     /**
      * How was this model used.
@@ -202,19 +275,34 @@ export interface SourceModel {
     /** Node where this source model was referenced. */
     readonly node?: Node;
 }
+/** A named model field, including copied fields introduced by composition. */
 export interface ModelProperty extends BaseType, DecoratedType {
+    /** Discriminant for model fields and operation parameters. */
     kind: "ModelProperty";
     node?: ModelPropertyNode | ModelSpreadPropertyNode | ObjectLiteralPropertyNode;
+    /** Key under which this property appears in its containing model. */
     name: string;
+    /** Type of values accepted by the property, independent of optionality. */
     type: Type;
+    /** Property copied to create this one through composition, when applicable. */
     sourceProperty?: ModelProperty;
+    /** Whether the property may be omitted; this does not add `null` to its type. */
     optional: boolean;
+    /** Checked default value, when a default was supplied. */
     defaultValue?: Value;
+    /** Containing model, when attached; copied properties belong to the receiving model. */
     model?: Model;
 }
+/**
+ * A checked TypeSpec value, distinct from the {@link Type} describing what values are allowed.
+ * Narrow with `valueKind` to inspect primitive payloads, collection contents, or constructor calls.
+ */
 export type Value = ScalarValue | NumericValue | StringValue | BooleanValue | ObjectValue | ArrayValue | EnumValue | NullValue | FunctionValue;
+/** Common identity and storage-type metadata inherited by checked values. */
 interface BaseValue {
+    /** Distinguishes a concrete value from a type or parameter constraint. */
     readonly entityKind: "Value";
+    /** Discriminant identifying how the value's contents are represented. */
     readonly valueKind: string;
     /**
      * Represent the storage type of a value.
@@ -227,54 +315,93 @@ interface BaseValue {
      */
     type: Type;
 }
+/** An object value with checked named entries, rather than a model type's property declarations. */
 export interface ObjectValue extends BaseValue {
+    /** Discriminant for object contents stored in a property map. */
     valueKind: "ObjectValue";
+    /** Object literal that produced the value, when available. */
     node?: ObjectLiteralNode;
+    /** Actual entries keyed by property name; each descriptor contains a value, not a property type. */
     properties: Map<string, ObjectValuePropertyDescriptor>;
 }
+/** One named entry in an {@link ObjectValue}, with its checked value and optional source. */
 export interface ObjectValuePropertyDescriptor {
+    /** Property syntax that supplied this entry, when available. */
     node?: ObjectLiteralPropertyNode;
+    /** Entry name matching its key in the containing object's property map. */
     name: string;
+    /** Checked contents of the entry. */
     value: Value;
 }
+/** An array value containing checked elements, distinct from an array model or tuple type. */
 export interface ArrayValue extends BaseValue {
+    /** Discriminant for array contents stored as an element list. */
     valueKind: "ArrayValue";
+    /** Array literal that produced the value, when available. */
     node?: ArrayLiteralNode;
+    /** Element values in array order. */
     values: Value[];
 }
+/** A scalar constructor call retained as a scalar, constructor name, and checked arguments. */
 export interface ScalarValue extends BaseValue {
+    /** Discriminant for a retained constructor call rather than a primitive payload. */
     valueKind: "ScalarValue";
+    /** Scalar instantiated by the constructor call. */
     scalar: Scalar;
+    /** Constructor invocation used to create the value. */
     value: {
+        /** Constructor name on the scalar. */
         name: string;
+        /** Checked arguments in call order. */
         args: Value[];
     };
 }
+/** A numeric value whose exact contents are preserved independently of JavaScript number precision. */
 export interface NumericValue extends BaseValue {
+    /** Discriminant for an exact numeric payload. */
     valueKind: "NumericValue";
+    /** Selected numeric scalar, or undefined for a literal without an inferred or explicit scalar. */
     scalar: Scalar | undefined;
+    /** Exact numeric contents; use Numeric conversion methods when a JavaScript number is needed. */
     value: Numeric;
 }
+/** A string value, optionally associated with a scalar selected by its context or construction. */
 export interface StringValue extends BaseValue {
+    /** Discriminant for a JavaScript string payload. */
     valueKind: "StringValue";
+    /** Selected string scalar, or undefined when the value has no scalar association. */
     scalar: Scalar | undefined;
+    /** String contents, independent of the value's storage type. */
     value: string;
 }
+/** A boolean value, optionally associated with a scalar selected by its context or construction. */
 export interface BooleanValue extends BaseValue {
+    /** Discriminant for a JavaScript boolean payload. */
     valueKind: "BooleanValue";
+    /** Selected boolean scalar, or undefined when the value has no scalar association. */
     scalar: Scalar | undefined;
+    /** Boolean contents, independent of the value's storage type. */
     value: boolean;
 }
+/** A value referring to an enum member, retaining member identity rather than only its assigned value. */
 export interface EnumValue extends BaseValue {
+    /** Discriminant for a value backed by an enum member. */
     valueKind: "EnumValue";
+    /** Referenced member, including its owning enum and any explicit string or numeric value. */
     value: EnumMember;
 }
+/** The concrete null value, distinct from the intrinsic type used to describe it. */
 export interface NullValue extends BaseValue {
+    /** Discriminant for the null payload. */
     valueKind: "NullValue";
+    /** Null contents; absence of a value is not represented by this field being undefined. */
     value: null;
 }
+/** A scalar declaration or expression, with optional scalar inheritance and named constructors. */
 export interface Scalar extends BaseType, DecoratedType, TemplatedTypeBase {
+    /** Discriminant for scalar types rather than scalar values. */
     kind: "Scalar";
+    /** Declared name, or an empty string for an anonymous scalar expression. */
     name: string;
     node?: ScalarStatementNode | ScalarDeclarationExpressionNode;
     /**
@@ -294,19 +421,29 @@ export interface Scalar extends BaseType, DecoratedType, TemplatedTypeBase {
      * Direct children. This is the reverse relation of @see baseScalar
      */
     derivedScalars: Scalar[];
+    /** Constructors keyed by name, including inherited constructors rebound to this scalar. */
     constructors: Map<string, ScalarConstructor>;
 }
+/** A named scalar initializer whose checked call produces a value of its associated scalar. */
 export interface ScalarConstructor extends BaseType {
+    /** Discriminant for scalar initializer signatures. */
     kind: "ScalarConstructor";
     node?: ScalarConstructorNode;
+    /** Initializer name used after the scalar name in a constructor call. */
     name: string;
+    /** Scalar constructed by this signature, including when the signature was inherited. */
     scalar: Scalar;
+    /** Parameter constraints in declaration order, including optional and rest parameters. */
     parameters: SignatureFunctionParameter[];
 }
+/** A named collection of operations, including operations copied from extended interfaces. */
 export interface Interface extends BaseType, DecoratedType, TemplatedTypeBase {
+    /** Discriminant for operation containers. */
     kind: "Interface";
+    /** Local declaration name, excluding its namespace path. */
     name: string;
     node?: InterfaceStatementNode;
+    /** Containing namespace, when associated with a namespace. */
     namespace?: Namespace;
     /**
      * The interfaces that provide additional operations via `interface extends`.
@@ -326,10 +463,14 @@ export interface Interface extends BaseType, DecoratedType, TemplatedTypeBase {
      */
     operations: RekeyableMap<string, Operation>;
 }
+/** An ordered set of named members with optional explicit string or numeric values. */
 export interface Enum extends BaseType, DecoratedType {
+    /** Discriminant for enum types rather than individual members. */
     kind: "Enum";
+    /** Declared name, or an empty string for an anonymous enum expression. */
     name: string;
     node?: EnumStatementNode | EnumDeclarationExpressionNode;
+    /** Containing namespace, when associated with a namespace. */
     namespace?: Namespace;
     /**
      * Whether this enum was declared in expression position (anonymous `enum { ... }`)
@@ -344,11 +485,16 @@ export interface Enum extends BaseType, DecoratedType {
      */
     members: RekeyableMap<string, EnumMember>;
 }
+/** A named enum entry retaining both its owning enum and any spread source. */
 export interface EnumMember extends BaseType, DecoratedType {
+    /** Discriminant for a member declaration rather than an enum value wrapper. */
     kind: "EnumMember";
+    /** Member name, distinct from any explicitly assigned value. */
     name: string;
+    /** Owning enum; spread copies belong to the receiving enum. */
     enum: Enum;
     node?: EnumMemberNode;
+    /** Explicitly assigned value, or undefined for a member declared with only a name. */
     value?: string | number;
     /**
      * when spread operators make new enum members,
@@ -356,22 +502,33 @@ export interface EnumMember extends BaseType, DecoratedType {
      */
     sourceMember?: EnumMember;
 }
+/** A callable API signature, declared in a namespace or owned by an interface. */
 export interface Operation extends BaseType, DecoratedType, TemplatedTypeBase {
+    /** Discriminant for API operation signatures rather than TypeSpec function values. */
     kind: "Operation";
     node?: OperationStatementNode;
+    /** Local operation name, excluding namespace and interface qualifiers. */
     name: string;
+    /** Containing namespace, including for operations declared inside an interface. */
     namespace?: Namespace;
+    /** Owning interface, or absent for a namespace-level operation. */
     interface?: Interface;
+    /** Model whose properties describe the operation's ordered parameters. */
     parameters: Model;
+    /** Result type, including the `void` intrinsic for an operation without a return value. */
     returnType: Type;
     /**
      * The operation that is referenced via `op is`.
      */
     sourceOperation?: Operation;
 }
+/** A declaration container; nested namespaces link to their parent and the global namespace is unnamed. */
 export interface Namespace extends BaseType, DecoratedType {
+    /** Discriminant for namespace containers rather than their declarations. */
     kind: "Namespace";
+    /** Local namespace segment, or an empty string for the global namespace. */
     name: string;
+    /** Parent namespace; absent on the global namespace. */
     namespace?: Namespace;
     node?: NamespaceStatementNode | JsNamespaceDeclarationNode;
     /**
@@ -429,53 +586,84 @@ export interface Namespace extends BaseType, DecoratedType {
      */
     functionDeclarations: Map<string, FunctionValue>;
 }
+/** Singleton primitive types, distinct from the corresponding checked value objects. */
 export type LiteralType = StringLiteral | NumericLiteral | BooleanLiteral;
+/** Singleton type accepting exactly one string. */
 export interface StringLiteral extends BaseType {
+    /** Discriminant for string literal types, not the `string` scalar. */
     kind: "String";
     node?: StringLiteralNode;
+    /** String accepted by this singleton type. */
     value: string;
 }
+/** Singleton numeric type retaining exact numeric contents alongside a JavaScript projection. */
 export interface NumericLiteral extends BaseType {
+    /** Discriminant for numeric literal types, not numeric scalar declarations. */
     kind: "Number";
     node?: NumericLiteralNode;
+    /** JavaScript numeric projection; use numericValue when precision or range matters. */
     value: number;
+    /** Exact numeric contents, without JavaScript number rounding. */
     numericValue: Numeric;
+    /** Source spelling, or synthesized numeric text for a programmatically created literal. */
     valueAsString: string;
 }
+/** Singleton type accepting exactly one boolean. */
 export interface BooleanLiteral extends BaseType {
+    /** Discriminant for boolean literal types, not the `boolean` scalar. */
     kind: "Boolean";
     node?: BooleanLiteralNode;
+    /** Boolean accepted by this singleton type. */
     value: boolean;
 }
+/** A string template type retaining its literal text and interpolated types as separate spans. */
 export interface StringTemplate extends BaseType {
+    /** Discriminant for a template type rather than a concrete string value. */
     kind: "StringTemplate";
     /** If the template can be render as as string this is the string value */
     stringValue?: string;
     node?: StringTemplateExpressionNode;
+    /** Text and interpolated types in source order, including any empty text spans. */
     spans: StringTemplateSpan[];
 }
+/** One part of a string template, narrowed by isInterpolated rather than by kind. */
 export type StringTemplateSpan = StringTemplateSpanLiteral | StringTemplateSpanValue;
+/** Literal text between interpolations in a string template. */
 export interface StringTemplateSpanLiteral extends BaseType {
+    /** Shared span discriminant; use isInterpolated to distinguish text from interpolation. */
     kind: "StringTemplateSpan";
     node?: StringTemplateHeadNode | StringTemplateMiddleNode | StringTemplateTailNode;
+    /** Marks source text rather than an interpolated expression, even when the text is empty. */
     isInterpolated: false;
+    /** Singleton string type holding this span's text. */
     type: StringLiteral;
 }
+/** An interpolated type in a string template, including interpolated string literal types. */
 export interface StringTemplateSpanValue extends BaseType {
+    /** Shared span discriminant; use isInterpolated to distinguish interpolation from text. */
     kind: "StringTemplateSpan";
     node?: Expression;
+    /** Marks an interpolation even when its type is a string literal. */
     isInterpolated: true;
+    /** Interpolated type, which may not be renderable as a concrete string. */
     type: Type;
 }
+/** A fixed sequence of element types, distinct from an array value or indexed model. */
 export interface Tuple extends BaseType {
+    /** Discriminant for tuple types rather than array values. */
     kind: "Tuple";
     node?: TupleExpressionNode | ArrayLiteralNode;
+    /** Element types in tuple position order. */
     values: Type[];
 }
+/** Alternatives described by ordered variants, from either a union declaration or an expression. */
 export interface Union extends BaseType, DecoratedType, TemplatedTypeBase {
+    /** Discriminant for a union of types rather than a single variant. */
     kind: "Union";
+    /** Declared name, when present; expression unions can also retain a declaration-expression name. */
     name?: string;
     node?: UnionExpressionNode | UnionStatementNode | UnionDeclarationExpressionNode;
+    /** Containing namespace, when associated with a namespace. */
     namespace?: Namespace;
     /**
      * The variants of the union.
@@ -483,6 +671,7 @@ export interface Union extends BaseType, DecoratedType, TemplatedTypeBase {
      * Variants are ordered in order that they appear in source.
      */
     variants: RekeyableMap<string | symbol, UnionVariant>;
+    /** Whether the union is used in expression position, including both `A | B` and `union { ... }`. */
     expression: boolean;
     /**
      * Type declared with the `extends` clause of a union statement. Union variants are
@@ -503,11 +692,16 @@ export interface Union extends BaseType, DecoratedType, TemplatedTypeBase {
      */
     baseType?: Model | Scalar | Enum | Union;
 }
+/** One alternative of a union, with either a declared name or an anonymous symbol key. */
 export interface UnionVariant extends BaseType, DecoratedType {
+    /** Discriminant for a union alternative rather than the alternative's value type. */
     kind: "UnionVariant";
+    /** Declared variant name, or a unique symbol for an unnamed alternative. */
     name: string | symbol;
     node?: UnionVariantNode | undefined;
+    /** Type accepted by this alternative. */
     type: Type;
+    /** Owning union; flattened union expressions can reuse variants owned by another union. */
     union: Union;
 }
 /**
@@ -518,6 +712,7 @@ export interface UnionVariant extends BaseType, DecoratedType {
  * @experimental
  */
 export interface TemplateParameter extends BaseType {
+    /** Discriminant for an unresolved template parameter rather than a substituted argument. */
     kind: "TemplateParameter";
 }
 /**
@@ -531,15 +726,23 @@ export interface TemplateParameter extends BaseType {
  * @experimental
  */
 export interface TemplateParameterAccess extends BaseType {
+    /** Discriminant for unresolved member access rooted in a template parameter. */
     kind: "TemplateParameterAccess";
 }
+/** A checked TypeSpec decorator declaration, distinct from an application of that decorator. */
 export interface Decorator extends BaseType {
+    /** Discriminant for decorator declarations rather than decorator applications. */
     kind: "Decorator";
     node?: DecoratorDeclarationStatementNode;
+    /** Local decorator name including its leading `@`, without namespace qualifiers. */
     name: `@${string}`;
+    /** Declaring namespace, including the global namespace for unqualified declarations. */
     namespace: Namespace;
+    /** Constraint on the decorated target, separate from custom arguments. */
     target: MixedFunctionParameter;
+    /** Custom parameter constraints in declaration order, excluding the target. */
     parameters: MixedFunctionParameter[];
+    /** JavaScript implementation receiving the context, target, and marshalled custom arguments. */
     implementation: (ctx: DecoratorContext, target: Type, ...args: unknown[]) => void;
     /** How this decorator was declared. */
     declarationKind: "extern" | "auto";
@@ -548,6 +751,7 @@ export interface Decorator extends BaseType {
  * The type of a Function in TypeSpec.
  */
 export interface FunctionType extends BaseType {
+    /** Discriminant for a function signature constraint rather than a callable function value. */
     kind: "FunctionType";
     /**
      * The parameter constraints of the function.
@@ -582,7 +786,9 @@ export interface FunctionType extends BaseType {
  * ```
  */
 export interface FunctionValue<Parameters extends unknown[] = never[], ReturnType = unknown> extends BaseValue {
+    /** Discriminant for callable function values rather than data values. */
     valueKind: "Function";
+    /** Source `fn` declaration, when the function originates in a declaration. */
     node?: FunctionDeclarationStatementNode;
     /**
      * The function's name as declared in the TypeSpec source, if any.
@@ -613,7 +819,9 @@ export interface FunctionValue<Parameters extends unknown[] = never[], ReturnTyp
      */
     implementation: (ctx: FunctionContext, ...args: Parameters) => ReturnType;
 }
+/** Signature entry shared by function, decorator, and scalar-constructor parameters. */
 export interface FunctionParameterBase extends BaseType {
+    /** Shared parameter discriminant; mixed selects the constraint representation. */
     kind: "FunctionParameter";
     node?: FunctionParameterNode;
     /**
@@ -633,21 +841,31 @@ export interface FunctionParameterBase extends BaseType {
  * A function parameter with a mixed parameter constraint that could accept a value.
  */
 export interface MixedFunctionParameter extends FunctionParameterBase {
+    /** Selects independent type and value alternatives instead of a simple type constraint. */
     mixed: true;
+    /** Constraint describing the types or values that may be supplied. */
     type: MixedParameterConstraint;
 }
 /**
  * A function parameter with a simple type constraint.
  */
 export interface SignatureFunctionParameter extends FunctionParameterBase {
+    /** Selects a single type constraint instead of mixed type and value alternatives. */
     mixed: false;
+    /** Type required for values supplied to this signature parameter. */
     type: Type;
 }
 /**
  * A function parameter.
  */
 export type FunctionParameter = MixedFunctionParameter | SignatureFunctionParameter;
+/**
+ * Binding identity used for name lookup before and during type checking.
+ * Declaration symbols collect contributing nodes in `declarations`; expression and
+ * late-bound symbols instead use `node` or `type`.
+ */
 export interface Sym {
+    /** Combined category, visibility, and binding-state bits for this symbol. */
     readonly flags: SymbolFlags;
     /**
      * Nodes which contribute to this declaration, present if SymbolFlags.Declaration is set.
@@ -683,7 +901,7 @@ export interface Sym {
      */
     readonly members?: SymbolTable;
     /**
-     * Symbol table
+     * Metatype members selected with `::`, such as an operation's `parameters`.
      */
     readonly metatypeMembers?: SymbolTable;
     /**
@@ -803,32 +1021,54 @@ export interface MutableSymbolTable extends SymbolTable {
      */
     include(source: SymbolTable, parentSym?: Sym): void;
 }
+/**
+ * Bit flags describing a symbol's category and how it is bound.
+ * Category bits may be combined with flags such as `Declaration`, `Member`, or `Internal`.
+ */
 export declare const enum SymbolFlags {
+    /** No category or binding-state bits are set. */
     None = 0,
+    /** A model declaration or structural model expression. */
     Model = 2,
+    /** A scalar declaration, including a scalar declaration expression. */
     Scalar = 4,
+    /** An operation, either namespace-level or an interface member. */
     Operation = 8,
+    /** An enum whose members can be looked up by name. */
     Enum = 16,
+    /** An interface containing operation members. */
     Interface = 32,
+    /** A keyword-form union containing variant members. */
     Union = 64,
+    /** An alias whose target must be resolved before accessing the underlying type. */
     Alias = 128,
+    /** A namespace that can merge declarations and export contained symbols. */
     Namespace = 256,
+    /** A decorator signature or JavaScript decorator implementation. */
     Decorator = 512,
+    /** A parameter declared in a template's `<...>` list. */
     TemplateParameter = 1024,
+    /** A function signature or JavaScript function implementation. */
     Function = 2048,
+    /** A named parameter in a function, decorator, or scalar constructor signature. */
     FunctionParameter = 4096,
+    /** A lookup binding introduced by `using`, forwarding to `symbolSource`. */
     Using = 8192,
+    /** A using binding made ambiguous by another using binding with the same name. */
     DuplicateUsing = 16384,
+    /** A file-level container for exported declarations. */
     SourceFile = 32768,
+    /** A symbol accessed as a member of its containing model, scalar, enum, union, or interface. */
     Member = 65536,
+    /** A constant declaration whose initializer produces a value. */
     Const = 131072,
     /**
      * A symbol which represents a declaration. Such symbols will have at least
-     * one entry in the `declarations[]` array referring to a node with an `id`.
-     *
-     * Symbols which do not represent declarations
+     * one entry in the `declarations` array. Non-declaration symbols instead store
+     * their originating node in `node`, when one exists.
      */
     Declaration = 1048576,
+    /** A JavaScript implementation to be merged with its TypeSpec decorator or function signature. */
     Implementation = 2097152,
     /**
      * A symbol which was late-bound, in which case, the type referred to
@@ -839,6 +1079,7 @@ export declare const enum SymbolFlags {
      * An internal symbol that can only be referenced from a source file in the same package.
      */
     Internal = 8388608,
+    /** Categories that store contained declarations in their `exports` table. */
     ExportContainer = 33024,
     /**
      * Symbols whose members will be late bound (and stored on the type)
@@ -849,7 +1090,9 @@ export declare const enum SymbolFlags {
  * Maps type arguments to instantiated type.
  */
 export interface TypeInstantiationMap {
+    /** Retrieve the cached instantiation for an ordered argument list, or `undefined` if absent. */
     get(args: readonly (Type | Value | IndeterminateEntity)[]): Type | undefined;
+    /** Cache an instantiated type under its ordered list of type or value arguments. */
     set(args: readonly (Type | Value | IndeterminateEntity)[], type: Type): void;
 }
 /**
@@ -867,88 +1110,168 @@ export interface RekeyableMap<K, V> extends Map<K, V> {
     rekey(existingKey: K, newKey: K): boolean;
 }
 /**
- * AST types
+ * Discriminants for syntax nodes, comment ranges, and documentation nodes.
+ * Use a node's `kind` to narrow to its corresponding AST interface.
  */
 export declare enum SyntaxKind {
+    /** Root of a parsed TypeSpec file, including statements and parse diagnostics. */
     TypeSpecScript = 0,
+    /** Loaded JavaScript module supplying decorator or function implementations. */
     JsSourceFile = 1,
+    /** File or package import such as `import "./models.tsp";`. */
     ImportStatement = 2,
+    /** Name token, with its decoded spelling available as `sv`. */
     Identifier = 3,
+    /** Out-of-line decorator application using `@@decorator(Target, ...)`. */
     AugmentDecoratorStatement = 4,
+    /** Decorator application attached to a declaration using `@decorator(...)`. */
     DecoratorExpression = 5,
+    /** Compiler directive introduced by `#`, such as `#suppress`. */
     DirectiveExpression = 6,
+    /** Qualified name segment selected with `.` or metatype selector `::`. */
     MemberExpression = 7,
+    /** Namespace declaration, including blockless and dotted forms. */
     NamespaceStatement = 8,
+    /** Namespace import into the current lookup scope using `using`. */
     UsingStatement = 9,
+    /** Named operation declaration, either with a signature or an `is` reference. */
     OperationStatement = 10,
+    /** Explicit operation parameter list and return type. */
     OperationSignatureDeclaration = 11,
+    /** Operation signature reused through an `is` reference. */
     OperationSignatureReference = 12,
+    /** Named model declaration registered in its enclosing namespace. */
     ModelStatement = 13,
+    /** Structural model type in braces, also used for operation parameter lists. */
     ModelExpression = 14,
+    /** Model property or operation parameter, including its type and optional default. */
     ModelProperty = 15,
+    /** Model properties copied into a body or parameter list using `...`. */
     ModelSpreadProperty = 16,
+    /** Named scalar declaration with optional base scalar and constructors. */
     ScalarStatement = 17,
+    /** Named interface declaration containing operations. */
     InterfaceStatement = 18,
+    /** Named union declaration containing variant nodes. */
     UnionStatement = 19,
+    /** Named or unnamed alternative in a keyword-form union. */
     UnionVariant = 20,
+    /** Named enum declaration containing members and member spreads. */
     EnumStatement = 21,
+    /** Enum member with an optional explicit string or numeric value. */
     EnumMember = 22,
+    /** Members copied from another enum using `...`. */
     EnumSpreadMember = 23,
+    /** Type alias declaration, optionally parameterized by template parameters. */
     AliasStatement = 24,
+    /** Decorator signature declaration with a separate target parameter. */
     DecoratorDeclarationStatement = 25,
+    /** Named function signature declaration, distinct from a function type expression. */
     FunctionDeclarationStatement = 26,
+    /** Parameter in a function, decorator, or scalar constructor signature. */
     FunctionParameter = 27,
+    /** Infix union type assembled with `|`, not a keyword-form union declaration. */
     UnionExpression = 28,
+    /** Intersection type assembled with `&`. */
     IntersectionExpression = 29,
+    /** Tuple type written `[A, B]`, not an array value literal. */
     TupleExpression = 30,
+    /** Array type formed by an element type followed by `[]`. */
     ArrayExpression = 31,
+    /** Quoted string without interpolation. */
     StringLiteral = 32,
+    /** Numeric token retaining both its spelling and JavaScript numeric value. */
     NumericLiteral = 33,
+    /** The `true` or `false` literal. */
     BooleanLiteral = 34,
+    /** Interpolated string with a head and ordered substitution spans. */
     StringTemplateExpression = 35,
+    /** Text before the first `${...}` substitution in an interpolated string. */
     StringTemplateHead = 36,
+    /** Text between consecutive substitutions in an interpolated string. */
     StringTemplateMiddle = 37,
+    /** Text after the final substitution in an interpolated string. */
     StringTemplateTail = 38,
+    /** A string substitution expression paired with the text that follows it. */
     StringTemplateSpan = 39,
+    /** The `extern` declaration modifier. */
     ExternKeyword = 40,
+    /** The `void` type keyword, typically used for an operation with no return value. */
     VoidKeyword = 41,
+    /** The `never` type keyword, denoting a type with no possible values. */
     NeverKeyword = 42,
+    /** The `unknown` type keyword, represented by {@link AnyKeywordNode}. */
     UnknownKeyword = 43,
+    /** Value constraint introduced by `valueof`. */
     ValueOfExpression = 44,
+    /** Reference to a name with an optional template argument list. */
     TypeReference = 45,
+    /** Template parameter declaration with optional constraint and default. */
     TemplateParameterDeclaration = 46,
+    /** Standalone semicolon without a declaration. */
     EmptyStatement = 47,
+    /** Recovery node for source that could not be parsed as a valid statement. */
     InvalidStatement = 48,
+    /** Single-line comment range collected when comment tracking is enabled. */
     LineComment = 49,
+    /** Block comment range, possibly also parsed as documentation. */
     BlockComment = 50,
+    /** Parsed documentation comment with body content and tags. */
     Doc = 51,
+    /** Text content within a documentation comment or tag. */
     DocText = 52,
+    /** Documentation tag describing a function or operation parameter. */
     DocParamTag = 53,
+    /** Documentation tag describing a model property. */
     DocPropTag = 54,
+    /** Documentation tag describing a return value. */
     DocReturnsTag = 55,
+    /** Documentation tag describing error responses. */
     DocErrorsTag = 56,
+    /** Documentation tag describing a template parameter. */
     DocTemplateTag = 57,
+    /** Documentation tag whose name has no dedicated syntax kind. */
     DocUnknownTag = 58,
+    /** Reserved kind; the parser does not currently produce return-statement nodes. */
     Return = 59,
+    /** Namespace node synthesized while binding JavaScript implementations. */
     JsNamespaceDeclaration = 60,
+    /** Positional or named argument inside a type reference's `<...>` list. */
     TemplateArgument = 61,
+    /** Expression introduced by `typeof` to obtain the type of a value. */
     TypeOfExpression = 62,
+    /** Object value written `#{ ... }`, distinct from a structural model type. */
     ObjectLiteral = 63,
+    /** Named value entry in an object literal. */
     ObjectLiteralProperty = 64,
+    /** Properties copied from an object value using `...`. */
     ObjectLiteralSpreadProperty = 65,
+    /** Array value written `#[ ... ]`, distinct from a tuple type. */
     ArrayLiteral = 66,
+    /** Named constant value with an optional type annotation. */
     ConstStatement = 67,
+    /** Function or scalar-constructor invocation with positional arguments. */
     CallExpression = 68,
+    /** Named `init` signature declared within a scalar. */
     ScalarConstructor = 69,
+    /** The `internal` declaration modifier restricting package visibility. */
     InternalKeyword = 70,
+    /** The `auto` modifier requesting a compiler-provided decorator implementation. */
     AutoKeyword = 71,
+    /** Anonymous function signature written `fn(...) => ...`. */
     FunctionTypeExpression = 72,
+    /** Keyword-form `model` used as an expression without namespace registration. */
     ModelDeclarationExpression = 73,
+    /** Keyword-form `scalar` used as an expression without namespace registration. */
     ScalarDeclarationExpression = 74,
+    /** Keyword-form `union` used as an expression without namespace registration. */
     UnionDeclarationExpression = 75,
+    /** Keyword-form `enum` used as an expression without namespace registration. */
     EnumDeclarationExpression = 76
 }
+/** Parser error-state and origin bits attached to syntax nodes. */
 export declare const enum NodeFlags {
+    /** No error-state or synthetic-origin bits have been set. */
     None = 0,
     /**
      * If this is set, the DescendantHasError bit can be trusted. If this not set,
@@ -976,29 +1299,48 @@ export declare const enum NodeFlags {
      */
     Synthetic = 8
 }
+/**
+ * Shared source range and metadata for syntax nodes.
+ * Parent and binding information need not be available on a freshly parsed or synthetic tree.
+ */
 export interface BaseNode extends TextRange {
+    /** Discriminant used to narrow the node to a specific syntax interface. */
     readonly kind: SyntaxKind;
+    /** Enclosing syntax node once parent links have been established; absent at roots. */
     readonly parent?: Node;
+    /** Compiler directives attached to this node, in source order when present. */
     readonly directives?: readonly DirectiveExpressionNode[];
+    /** Attached documentation comments when documentation parsing is enabled. */
     readonly docs?: readonly DocNode[];
+    /** Parse-error cache state and synthetic-origin markers; use `hasParseError` for errors. */
     readonly flags: NodeFlags;
     /** Unique id across the process used to look up NodeLinks */
     _id?: number;
 }
+/** Syntax shared by declarations that accept template parameter lists. */
 export interface TemplateDeclarationNode {
+    /** Parameters in declaration order; empty when no template list was written. */
     readonly templateParameters: readonly TemplateParameterDeclarationNode[];
+    /** Range including `<` and `>`; positions are `-1` when the list is absent. */
     readonly templateParametersRange: TextRange;
+    /** Local bindings, including template parameters, populated during binding when applicable. */
     readonly locals?: SymbolTable;
 }
 /**
  * owner node and other related information according to the position
  */
 export interface PositionDetail {
+    /** Most specific node accepted by the position query, or `undefined` when none matches. */
     readonly node: Node | undefined;
+    /** Queried zero-based UTF-16 offset in the source file. */
     readonly position: number;
+    /** UTF-16 code unit at `position`, or `NaN` outside the source text. */
     readonly char: number;
+    /** UTF-16 code unit immediately before `position`, or `NaN` outside the source text. */
     readonly preChar: number;
+    /** UTF-16 code unit immediately after `position`, or `NaN` outside the source text. */
     readonly nextChar: number;
+    /** Whether the position query identifies whitespace or comment trivia at this offset. */
     readonly inTrivia: boolean;
     /**
      * if the position is in a trivia, return the start position of the trivia containing the position
@@ -1023,6 +1365,10 @@ export interface PositionDetail {
     /** get the PositionDetail of positionAfterTrivia */
     readonly getPositionDetailAfterTrivia: () => PositionDetail;
 }
+/**
+ * Discriminated union of syntax nodes visited by the parser's AST utilities.
+ * Comment ranges are tracked separately as {@link Comment}, not as child nodes.
+ */
 export type Node = TypeSpecScriptNode | JsSourceFileNode | JsNamespaceDeclarationNode | TemplateArgumentNode | TemplateParameterDeclarationNode | ModelPropertyNode | UnionVariantNode | OperationStatementNode | OperationSignatureDeclarationNode | OperationSignatureReferenceNode | EnumMemberNode | EnumSpreadMemberNode | ModelSpreadPropertyNode | DecoratorExpressionNode | DirectiveExpressionNode | Statement | Expression | FunctionParameterNode | StringTemplateSpanNode | StringTemplateHeadNode | StringTemplateMiddleNode | StringTemplateTailNode | Modifier | DocNode | DocContent | DocTag | ReferenceExpression | ObjectLiteralNode | ObjectLiteralPropertyNode | ObjectLiteralSpreadPropertyNode | ScalarConstructorNode | ArrayLiteralNode;
 /**
  * Node that can be used as template
@@ -1032,42 +1378,75 @@ export type TemplateableNode = ModelStatementNode | ModelDeclarationExpressionNo
  * Node types that can have referencable members
  */
 export type MemberContainerNode = ModelStatementNode | ModelExpressionNode | ModelDeclarationExpressionNode | InterfaceStatementNode | EnumStatementNode | EnumDeclarationExpressionNode | UnionStatementNode | UnionDeclarationExpressionNode | IntersectionExpressionNode | ScalarStatementNode | ScalarDeclarationExpressionNode;
+/** Syntax declarations that introduce members of a model, enum, interface, union, or scalar. */
 export type MemberNode = ModelPropertyNode | EnumMemberNode | OperationStatementNode | UnionVariantNode | ScalarConstructorNode;
+/** Semantic types whose named members can be resolved through member access. */
 export type MemberContainerType = Model | Enum | Interface | Union | Scalar;
 /**
  * Type that can be used as members of a container type.
  */
 export type MemberType = ModelProperty | EnumMember | Operation | UnionVariant | ScalarConstructor;
+/** Source comment ranges collected separately from the syntax tree when requested by {@link ParseOptions}. */
 export type Comment = LineComment | BlockComment;
+/** Range of a `//` comment, excluding the terminating line break. */
 export interface LineComment extends TextRange {
+    /** Identifies a line-comment range rather than a block-comment range. */
     readonly kind: SyntaxKind.LineComment;
 }
+/** Range of a `/* ... *\/` comment, including its delimiters. */
 export interface BlockComment extends TextRange {
+    /** Identifies a block-comment range, including documentation comments. */
     readonly kind: SyntaxKind.BlockComment;
     /** If that comment was parsed as a doc comment. If parserOptions.docs=false this will always be false. */
     readonly parsedAsDocs?: boolean;
 }
+/** Controls optional comment collection and documentation parsing without changing the source text. */
 export interface ParseOptions {
     /** When true, collect comment ranges in {@link TypeSpecScriptNode.comments}. */
     readonly comments?: boolean;
     /** When true, parse doc comments into {@link Node.docs}. */
     readonly docs?: boolean;
 }
+/**
+ * Root syntax node for a TypeSpec source file.
+ * Parsing creates statements and diagnostics; binding later populates namespace,
+ * using, and local-symbol indexes without replacing the source-order statement tree.
+ */
 export interface TypeSpecScriptNode extends BaseNode {
+    /** Identifies a TypeSpec file root, rather than a loaded JavaScript module. */
     readonly kind: SyntaxKind.TypeSpecScript;
+    /** Synthetic identifier whose spelling is the source file path. */
     readonly id: IdentifierNode;
+    /** Top-level statements in source order, including recovery and empty statements. */
     readonly statements: readonly Statement[];
+    /** Source text and path from which this tree was parsed. */
     readonly file: SourceFile;
+    /** Blockless file namespace and its enclosing namespace segments, populated during binding. */
     readonly inScopeNamespaces: readonly NamespaceStatementNode[];
+    /** All namespace declaration nodes encountered during binding, including nested segments. */
     readonly namespaces: NamespaceStatementNode[];
+    /** Using statements from all scopes in this file, collected during binding. */
     readonly usings: readonly UsingStatementNode[];
+    /** Source-order comment ranges; empty unless comment collection was requested. */
     readonly comments: readonly Comment[];
+    /** Diagnostics produced while parsing, independent of later binding and checking diagnostics. */
     readonly parseDiagnostics: readonly Diagnostic[];
+    /** Whether parser recovery left a tree that the formatter can safely print. */
     readonly printable: boolean;
+    /** File-local lookup bindings; initialized by the binder, not by parsing alone. */
     readonly locals: SymbolTable;
+    /** Options supplied to the parser for this tree. */
     readonly parseOptions: ParseOptions;
 }
+/**
+ * AST node variants representable in a statement list, including declarations and recovery nodes.
+ * The union also includes call expressions, but the parser does not accept standalone call statements.
+ */
 export type Statement = ImportStatementNode | ModelStatementNode | ScalarStatementNode | NamespaceStatementNode | InterfaceStatementNode | UnionStatementNode | UsingStatementNode | EnumStatementNode | AliasStatementNode | OperationStatementNode | DecoratorDeclarationStatementNode | FunctionDeclarationStatementNode | AugmentDecoratorStatementNode | ConstStatementNode | CallExpressionNode | EmptyStatementNode | InvalidStatementNode;
+/**
+ * Shared shape for named statement declarations.
+ * Parsed modifiers preserve source order and may include combinations later rejected by the checker.
+ */
 export interface DeclarationNode {
     /**
      * Identifier that this node declares.
@@ -1094,64 +1473,117 @@ export interface OptionallyNamedDeclarationNode {
      */
     readonly id?: IdentifierNode;
     /**
-     * Modifier nodes applied to this declaration.
+     * Modifier nodes applied to this declaration. Empty for parsed declaration expressions.
      */
     readonly modifiers: Modifier[];
     /**
-     * Combined modifier flags for this declaration.
+     * Combined modifier flags for this declaration. `None` for parsed declaration expressions.
      */
     readonly modifierFlags: ModifierFlags;
 }
+/** Statement variants that introduce a named declaration and carry declaration modifiers. */
 export type Declaration = Extract<Statement, DeclarationNode>;
+/** Syntax nodes used as lexical scopes for declaration and reference lookup. */
 export type ScopeNode = NamespaceStatementNode | ModelStatementNode | InterfaceStatementNode | AliasStatementNode | TypeSpecScriptNode | JsSourceFileNode;
+/** File or package import written `import "path";` at the source-file level. */
 export interface ImportStatementNode extends BaseNode {
+    /** Distinguishes module loading from namespace lookup through a `using` statement. */
     readonly kind: SyntaxKind.ImportStatement;
+    /** Quoted module specifier; its decoded value may be a relative path or package name. */
     readonly path: StringLiteralNode;
+    /** Source file containing the import once parent links have been established. */
     readonly parent?: TypeSpecScriptNode;
 }
+/** Name token used for declarations, references, member selectors, and other named syntax. */
 export interface IdentifierNode extends BaseNode {
+    /** Identifies the name token itself, not a reference or declaration containing it. */
     readonly kind: SyntaxKind.Identifier;
+    /**
+     * Decoded name without quoting or escapes; identifier tokens are NFC-normalized.
+     * Read the source range instead when the original spelling is needed.
+     */
     readonly sv: string;
 }
+/** An `@decorator(...)` annotation attached to a declaration or member. */
 export interface DecoratorExpressionNode extends BaseNode {
+    /** Distinguishes an attached annotation from an out-of-line `@@` application. */
     readonly kind: SyntaxKind.DecoratorExpression;
+    /** Decorator name, without the leading `@`, optionally qualified by a namespace. */
     readonly target: IdentifierNode | MemberExpressionNode;
+    /** Explicit arguments in source order; the decorated entity is supplied separately by the checker. */
     readonly arguments: readonly Expression[];
 }
+/** An out-of-line decorator application, such as `@@doc(MyModel, "description");`. */
 export interface AugmentDecoratorStatementNode extends BaseNode {
+    /** Identifies the `@@` statement form rather than a declaration annotation. */
     readonly kind: SyntaxKind.AugmentDecoratorStatement;
+    /** Decorator name without the leading `@@`. */
     readonly target: IdentifierNode | MemberExpressionNode;
+    /** First source argument: the reference to the entity being decorated. */
     readonly targetType: TypeReferenceNode;
+    /** Remaining source arguments, excluding the decorated entity reference. */
     readonly arguments: readonly Expression[];
+    /** Containing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
+/** A line-oriented compiler directive, such as `#suppress "code" "reason"`. */
 export interface DirectiveExpressionNode extends BaseNode {
+    /** Identifies a `#` directive rather than an `@` decorator annotation. */
     readonly kind: SyntaxKind.DirectiveExpression;
+    /** Directive name without the leading `#`. */
     readonly target: IdentifierNode;
+    /** Identifier or quoted-string arguments before the terminating newline. */
     readonly arguments: readonly DirectiveArgument[];
 }
+/** Directive arguments are names or quoted strings, not arbitrary TypeSpec expressions. */
 export type DirectiveArgument = StringLiteralNode | IdentifierNode;
+/**
+ * Syntax accepted in expression positions, including type expressions and value-producing syntax.
+ * Whether an expression denotes a type, value, or constraint is determined during checking.
+ */
 export type Expression = ArrayExpressionNode | MemberExpressionNode | ModelExpressionNode | ModelDeclarationExpressionNode | EnumDeclarationExpressionNode | UnionDeclarationExpressionNode | ScalarDeclarationExpressionNode | ObjectLiteralNode | ArrayLiteralNode | TupleExpressionNode | UnionExpressionNode | IntersectionExpressionNode | TypeReferenceNode | ValueOfExpressionNode | TypeOfExpressionNode | CallExpressionNode | StringLiteralNode | NumericLiteralNode | BooleanLiteralNode | StringTemplateExpressionNode | VoidKeywordNode | NeverKeywordNode | AnyKeywordNode | FunctionTypeExpressionNode;
 export type ParenthesizedExpression = Expression & {
     readonly parenthesized: true;
 };
+/** Name-reference syntax accepted by resolution utilities, including the intrinsic `void` and `never` keywords. */
 export type ReferenceExpression = TypeReferenceNode | MemberExpressionNode | IdentifierNode | VoidKeywordNode | NeverKeywordNode;
+/** One step of a qualified reference, such as `Namespace.Type` or `Operation::parameters`. */
 export interface MemberExpressionNode extends BaseNode {
+    /** Identifies a selected name segment rather than a complete reference with template arguments. */
     readonly kind: SyntaxKind.MemberExpression;
+    /** Name immediately following this node's selector. */
     readonly id: IdentifierNode;
+    /** Reference prefix to the left of the selector; longer chains nest through this property. */
     readonly base: MemberExpressionNode | IdentifierNode;
+    /** `.` selects namespace or type members; `::` selects compiler-provided metatype members. */
     readonly selector: "." | "::";
 }
+/**
+ * One segment of a namespace declaration.
+ * Dotted namespaces are nested nodes, while a blockless namespace scopes subsequent file statements.
+ */
 export interface NamespaceStatementNode extends BaseNode, DeclarationNode {
+    /** Identifies a source namespace declaration, not a namespace synthesized for JavaScript. */
     readonly kind: SyntaxKind.NamespaceStatement;
+    /**
+     * Block statements, a nested segment of a dotted name, or `undefined` for the
+     * innermost segment of a blockless namespace.
+     */
     readonly statements?: readonly Statement[] | NamespaceStatementNode;
+    /** Annotations on this segment; outer segments synthesized for a dotted name have none. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Local lookup bindings initialized during binding, separate for each declaration of a merged namespace. */
     readonly locals?: SymbolTable;
+    /** Enclosing file or namespace segment after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
+/** Brings a namespace's exported names into the containing lookup scope without loading a module. */
 export interface UsingStatementNode extends BaseNode {
+    /** Identifies namespace lookup syntax rather than a file import. */
     readonly kind: SyntaxKind.UsingStatement;
+    /** Namespace reference to make available for unqualified name lookup. */
     readonly name: IdentifierNode | MemberExpressionNode;
+    /** Syntactic container after binding; effective blockless namespace scope is in `scopeNamespace`. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
     /**
      * Namespace this using statement is scoped to.
@@ -1163,82 +1595,141 @@ export interface UsingStatementNode extends BaseNode {
      */
     readonly scopeNamespace?: NamespaceStatementNode;
 }
+/** Explicit `(parameters): ReturnType` portion of an operation declaration. */
 export interface OperationSignatureDeclarationNode extends BaseNode {
+    /** Selects the explicit-signature branch of {@link OperationSignature}. */
     readonly kind: SyntaxKind.OperationSignatureDeclaration;
+    /** Parameter list represented as model properties and spreads, with parentheses as its body range. */
     readonly parameters: ModelExpressionNode;
+    /** Type expression following the signature's colon. */
     readonly returnType: Expression;
 }
+/** `is BaseOperation` portion of an operation that reuses another operation's signature. */
 export interface OperationSignatureReferenceNode extends BaseNode {
+    /** Selects signature reuse rather than an explicit parameter list and return type. */
     readonly kind: SyntaxKind.OperationSignatureReference;
+    /** Referenced operation, including any explicit template arguments. */
     readonly baseOperation: TypeReferenceNode;
 }
+/** An operation either declares its own signature or reuses one through `is`. */
 export type OperationSignature = OperationSignatureDeclarationNode | OperationSignatureReferenceNode;
+/**
+ * Named operation declared in a namespace or interface.
+ * The `op` keyword is optional for interface members, but both forms use this node shape.
+ */
 export interface OperationStatementNode extends BaseNode, DeclarationNode, TemplateDeclarationNode {
+    /** Identifies the named operation node rather than its signature child. */
     readonly kind: SyntaxKind.OperationStatement;
+    /** Explicit signature or reference to an operation whose signature is reused. */
     readonly signature: OperationSignature;
+    /** Decorator annotations in source order, not their execution order. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** File, namespace, or interface syntactically containing this operation after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode | InterfaceStatementNode;
 }
+/** Named model declaration whose checked type is registered in the enclosing namespace. */
 export interface ModelStatementNode extends BaseNode, DeclarationNode, TemplateDeclarationNode {
+    /** Distinguishes a namespace declaration from a keyword-form model in expression position. */
     readonly kind: SyntaxKind.ModelStatement;
+    /** Own property declarations and spreads in source order; inherited properties are not inserted here. */
     readonly properties: readonly (ModelPropertyNode | ModelSpreadPropertyNode)[];
+    /** Range including body braces, or `{-1, -1}` when an `is` declaration has no body. */
     readonly bodyRange: TextRange;
+    /** Base model expression following `extends`; mutually exclusive with `is` in parsed syntax. */
     readonly extends?: Expression;
+    /** Model expression following `is`, whose properties and decorators are copied by the checker. */
     readonly is?: Expression;
+    /** Decorator annotations as written, before semantic evaluation. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Syntactic containing file or namespace after binding, including for blockless namespaces. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
 /**
  * A `model` declaration used in expression position (e.g. `alias M = model { x: string }`
  * or a property type). May carry a name (kept on the resulting type but never registered)
- * and is always `expression: true`. Template parameters are syntactically accepted for
- * error recovery but rejected by the checker.
+ * and produces a model type with `expression: true`. Checking requires the
+ * `declaration-expressions` feature. Template parameters are syntactically accepted
+ * for error recovery but rejected by the checker.
  */
 export interface ModelDeclarationExpressionNode extends BaseNode, OptionallyNamedDeclarationNode, TemplateDeclarationNode {
+    /** Identifies keyword-form model syntax in expression position, not a bare `{ ... }` model type. */
     readonly kind: SyntaxKind.ModelDeclarationExpression;
+    /** Own property declarations and spreads in source order, before inheritance or copying is resolved. */
     readonly properties: readonly (ModelPropertyNode | ModelSpreadPropertyNode)[];
+    /** Range including body braces, or `{-1, -1}` when an `is` expression omits a body. */
     readonly bodyRange: TextRange;
+    /** Base model expression following `extends`, absent when `is` is used. */
     readonly extends?: Expression;
+    /** Source model expression following `is`, absent when `extends` is used. */
     readonly is?: Expression;
+    /** Annotations applied to the resulting model type, not to the enclosing expression's owner. */
     readonly decorators: readonly DecoratorExpressionNode[];
 }
+/** Named scalar declaration with an optional base scalar and named constructor signatures. */
 export interface ScalarStatementNode extends BaseNode, DeclarationNode, TemplateDeclarationNode {
+    /** Distinguishes a namespace scalar declaration from a scalar declaration expression. */
     readonly kind: SyntaxKind.ScalarStatement;
+    /** Base scalar reference following `extends`, including any template arguments. */
     readonly extends?: TypeReferenceNode;
+    /** Decorator annotations on this scalar in source order. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Constructor signatures written in this body, excluding inherited constructors. */
     readonly members: readonly ScalarConstructorNode[];
+    /** Range including constructor-body braces, or `{-1, -1}` for a bodyless declaration. */
     readonly bodyRange: TextRange;
+    /** Syntactic containing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
 /**
  * A `scalar` declaration used in expression position (e.g. `alias S = scalar extends int32`).
- * May carry a name (kept on the resulting type but never registered) and is always
- * `expression: true`. Template parameters are syntactically accepted for error recovery but
- * rejected by the checker.
+ * May carry a name (kept on the resulting type but never registered) and
+ * produces a scalar type with `expression: true`. Checking requires the
+ * `declaration-expressions` feature. Template parameters are syntactically accepted
+ * for error recovery but rejected by the checker.
  */
 export interface ScalarDeclarationExpressionNode extends BaseNode, OptionallyNamedDeclarationNode, TemplateDeclarationNode {
+    /** Identifies a scalar used as an expression without introducing a namespace binding. */
     readonly kind: SyntaxKind.ScalarDeclarationExpression;
+    /** Base scalar reference following `extends`, or `undefined` when omitted. */
     readonly extends?: TypeReferenceNode;
+    /** Annotations applied to the scalar type produced by this expression. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Constructor signatures written in the optional scalar body. */
     readonly members: readonly ScalarConstructorNode[];
+    /** Range including constructor-body braces, or `{-1, -1}` when no body was written. */
     readonly bodyRange: TextRange;
 }
+/** Named scalar constructor signature written `init name(parameters);`. */
 export interface ScalarConstructorNode extends BaseNode {
+    /** Distinguishes a constructor declaration from a call to that constructor. */
     readonly kind: SyntaxKind.ScalarConstructor;
+    /** Constructor name following `init`. */
     readonly id: IdentifierNode;
+    /** Constructor parameters in source order, using function-parameter syntax rather than model properties. */
     readonly parameters: FunctionParameterNode[];
+    /** Scalar declaration or scalar declaration expression containing this signature after binding. */
     readonly parent?: ScalarStatementNode | ScalarDeclarationExpressionNode;
 }
+/** Named interface declaration grouping operations and optionally extending other interfaces. */
 export interface InterfaceStatementNode extends BaseNode, DeclarationNode, TemplateDeclarationNode {
+    /** Identifies an interface declaration, not one of its operation members. */
     readonly kind: SyntaxKind.InterfaceStatement;
+    /** Operations explicitly written in this body; inherited operations exist only in the checked type. */
     readonly operations: readonly OperationStatementNode[];
+    /** Range including the braces surrounding the operation list. */
     readonly bodyRange: TextRange;
+    /** Base interface references in source order; empty when no `extends` clause was written. */
     readonly extends: readonly TypeReferenceNode[];
+    /** Annotations on the interface itself, separate from annotations on individual operations. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Syntactic containing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
+/** Named keyword-form union whose alternatives may have individually addressable names. */
 export interface UnionStatementNode extends BaseNode, DeclarationNode, TemplateDeclarationNode {
+    /** Distinguishes a named union declaration from an infix `|` expression. */
     readonly kind: SyntaxKind.UnionStatement;
+    /** Variant nodes in source order, including both named and unnamed alternatives. */
     readonly options: readonly UnionVariantNode[];
     /**
      * Type that every variant of this union must be assignable to.
@@ -1249,17 +1740,22 @@ export interface UnionStatementNode extends BaseNode, DeclarationNode, TemplateD
      * @experimental
      */
     readonly extends?: Expression;
+    /** Annotations on the union itself, separate from variant annotations. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Syntactic containing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
 /**
  * A keyword-form `union` declaration used in expression position
  * (e.g. `alias U = union { string, int32 }`). May carry a name (kept on the resulting type
- * but never registered) and is always `expression: true`. Template parameters are
- * syntactically accepted for error recovery but rejected by the checker.
+ * but never registered) and produces a union type with `expression: true`.
+ * Checking requires the `declaration-expressions` feature. Template parameters
+ * are syntactically accepted for error recovery but rejected by the checker.
  */
 export interface UnionDeclarationExpressionNode extends BaseNode, OptionallyNamedDeclarationNode, TemplateDeclarationNode {
+    /** Identifies keyword-form union syntax in expression position, not an infix `|` expression. */
     readonly kind: SyntaxKind.UnionDeclarationExpression;
+    /** Named or unnamed variants in source order; retained as members of this union when used in a larger `|`. */
     readonly options: readonly UnionVariantNode[];
     /**
      * Type that every variant of this union must be assignable to.
@@ -1270,206 +1766,367 @@ export interface UnionDeclarationExpressionNode extends BaseNode, OptionallyName
      * @experimental
      */
     readonly extends?: Expression;
+    /** Annotations applied to the union type produced by this expression. */
     readonly decorators: readonly DecoratorExpressionNode[];
 }
+/** One alternative in a keyword-form union, with an optional name before `:`. */
 export interface UnionVariantNode extends BaseNode {
+    /** Identifies a declaration-body alternative rather than an operand of an infix union. */
     readonly kind: SyntaxKind.UnionVariant;
+    /** Explicit variant name; absent for an unnamed alternative such as `string`. */
     readonly id?: IdentifierNode;
+    /** Type expression for this alternative, whether or not a name was provided. */
     readonly value: Expression;
+    /** Annotations on this variant, not on its containing union. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Containing union declaration or union declaration expression after binding. */
     readonly parent?: UnionStatementNode | UnionDeclarationExpressionNode;
 }
+/** Named enum declaration containing explicit members and enum spreads. */
 export interface EnumStatementNode extends BaseNode, DeclarationNode {
+    /** Distinguishes a namespace enum declaration from an enum declaration expression. */
     readonly kind: SyntaxKind.EnumStatement;
+    /** Members and spread references as written; spreads are not expanded in the syntax tree. */
     readonly members: readonly (EnumMemberNode | EnumSpreadMemberNode)[];
+    /** Annotations on this enum, separate from member annotations. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Syntactic containing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
 /**
  * An `enum` declaration used in expression position (e.g. `alias E = enum { a, b }`).
- * May carry a name (kept on the resulting type but never registered) and is always
- * `expression: true`.
+ * May carry a name (kept on the resulting type but never registered) and produces
+ * an enum type with `expression: true`. Checking requires the `declaration-expressions` feature.
  */
 export interface EnumDeclarationExpressionNode extends BaseNode, OptionallyNamedDeclarationNode {
+    /** Identifies enum syntax used as an expression without introducing a namespace binding. */
     readonly kind: SyntaxKind.EnumDeclarationExpression;
+    /** Members and spreads in source order, before enum spreads are resolved by the checker. */
     readonly members: readonly (EnumMemberNode | EnumSpreadMemberNode)[];
+    /** Annotations applied to the enum type produced by this expression. */
     readonly decorators: readonly DecoratorExpressionNode[];
 }
+/** Enum member declaration with an optional explicit string or numeric literal after `:`. */
 export interface EnumMemberNode extends BaseNode {
+    /** Identifies an explicit member rather than an enum spread. */
     readonly kind: SyntaxKind.EnumMember;
+    /** Member name, including decoded names accepted through quoted-identifier syntax. */
     readonly id: IdentifierNode;
+    /** Explicit literal value; absent when the member is declared by name alone. */
     readonly value?: StringLiteralNode | NumericLiteralNode;
+    /** Annotations on this member, not its containing enum. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Containing enum declaration or enum declaration expression after binding. */
     readonly parent?: EnumStatementNode | EnumDeclarationExpressionNode;
 }
+/** An enum-body `...OtherEnum` entry whose members are copied during type checking. */
 export interface EnumSpreadMemberNode extends BaseNode {
+    /** Distinguishes a spread reference from an explicitly named enum member. */
     readonly kind: SyntaxKind.EnumSpreadMember;
+    /** Reference to the enum supplying the copied members. */
     readonly target: TypeReferenceNode;
 }
+/** Named alias for a type expression, optionally parameterized by template parameters. */
 export interface AliasStatementNode extends BaseNode, DeclarationNode, TemplateDeclarationNode {
+    /** Identifies a named alias declaration rather than the expression it aliases. */
     readonly kind: SyntaxKind.AliasStatement;
+    /** Expression following `=`, resolved in the alias's template and namespace scope. */
     readonly value: Expression;
+    /** Enclosing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
+/** Named constant value, optionally checked against an explicit type annotation. */
 export interface ConstStatementNode extends BaseNode, DeclarationNode {
+    /** Identifies a value declaration rather than a type alias. */
     readonly kind: SyntaxKind.ConstStatement;
+    /** Initializer following `=`, evaluated as a value by the checker. */
     readonly value: Expression;
+    /** Type annotation following `:`, or `undefined` when the value's type is inferred. */
     readonly type?: Expression;
+    /** Enclosing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
+/**
+ * Invocation of a function or scalar constructor in an expression.
+ * Although included in {@link Statement}, the parser does not accept standalone call statements.
+ */
 export interface CallExpressionNode extends BaseNode {
+    /** Distinguishes invocation with `(...)` from a name reference with optional `<...>` arguments. */
     readonly kind: SyntaxKind.CallExpression;
+    /** Function name or qualified constructor reference, without the argument list. */
     readonly target: MemberExpressionNode | IdentifierNode;
+    /** Explicit argument expressions in source order; no implicit context argument is stored here. */
     readonly arguments: Expression[];
 }
+/** Recovery placeholder for source that could not form a recognized statement. */
 export interface InvalidStatementNode extends BaseNode {
+    /** Identifies a parser-recovery node, not a valid declaration. */
     readonly kind: SyntaxKind.InvalidStatement;
+    /** Leading decorators retained while recovering from the invalid statement. */
     readonly decorators: readonly DecoratorExpressionNode[];
 }
+/** Standalone semicolon with no associated declaration or expression. */
 export interface EmptyStatementNode extends BaseNode {
+    /** Identifies an intentionally empty statement rather than a recovery placeholder. */
     readonly kind: SyntaxKind.EmptyStatement;
 }
+/**
+ * Structural model type written `{ ... }`, also used for operation parameter lists.
+ * Unlike a model declaration expression, it has no declaration name, modifiers, or heritage clauses.
+ */
 export interface ModelExpressionNode extends BaseNode {
+    /** Identifies structural model syntax rather than an object value written `#{ ... }`. */
     readonly kind: SyntaxKind.ModelExpression;
+    /** Explicit property declarations and spreads in source order, before spreads are expanded. */
     readonly properties: (ModelPropertyNode | ModelSpreadPropertyNode)[];
+    /** Range including the surrounding braces, or parentheses when used as an operation parameter list. */
     readonly bodyRange: TextRange;
 }
+/** Array type formed by applying a postfix `[]` to an element type expression. */
 export interface ArrayExpressionNode extends BaseNode {
+    /** Identifies an array type rather than an array value literal. */
     readonly kind: SyntaxKind.ArrayExpression;
+    /** Expression before this `[]`; nested array types contain another array expression here. */
     readonly elementType: Expression;
 }
+/** Fixed-length tuple type written `[A, B]`, distinct from an array value `#[a, b]`. */
 export interface TupleExpressionNode extends BaseNode {
+    /** Identifies tuple type syntax rather than value-literal syntax. */
     readonly kind: SyntaxKind.TupleExpression;
+    /** Element type expressions in tuple index order. */
     readonly values: readonly Expression[];
 }
+/** Property type declaration in a model body, or parameter declaration in an operation signature. */
 export interface ModelPropertyNode extends BaseNode {
+    /** Identifies an explicitly declared property rather than a property spread. */
     readonly kind: SyntaxKind.ModelProperty;
+    /** Property name, decoded from identifier or legacy quoted-name syntax. */
     readonly id: IdentifierNode;
+    /** Declared type expression following `:`, not the property's default value. */
     readonly value: Expression;
+    /** Property or parameter annotations in source order. */
     readonly decorators: readonly DecoratorExpressionNode[];
+    /** Whether `?` was written after the property name. */
     readonly optional: boolean;
+    /** Default-value expression following `=`, absent when no default was written. */
     readonly default?: Expression;
+    /** Containing model syntax or operation-parameter model after parent links are established. */
     readonly parent?: ModelStatementNode | ModelExpressionNode | ModelDeclarationExpressionNode;
 }
+/** Model-body or operation-parameter spread written `...SourceModel`. */
 export interface ModelSpreadPropertyNode extends BaseNode {
+    /** Identifies a spread that contributes properties during checking, not an explicit property node. */
     readonly kind: SyntaxKind.ModelSpreadProperty;
+    /** Model reference, including any template arguments, supplying the copied properties. */
     readonly target: TypeReferenceNode;
+    /** Containing model syntax or operation-parameter model after binding. */
     readonly parent?: ModelStatementNode | ModelExpressionNode | ModelDeclarationExpressionNode;
 }
+/** Object value literal written `#{ ... }`, not a structural model type. */
 export interface ObjectLiteralNode extends BaseNode {
+    /** Distinguishes value-producing object syntax from a model expression. */
     readonly kind: SyntaxKind.ObjectLiteral;
+    /** Property initializers and object spreads in source order, before evaluation. */
     readonly properties: (ObjectLiteralPropertyNode | ObjectLiteralSpreadPropertyNode)[];
+    /** Range including the `#{` opening token and closing brace. */
     readonly bodyRange: TextRange;
 }
+/** Named object-value initializer written `name: expression` inside `#{ ... }`. */
 export interface ObjectLiteralPropertyNode extends BaseNode {
+    /** Identifies an explicit initializer rather than an object spread. */
     readonly kind: SyntaxKind.ObjectLiteralProperty;
+    /** Decoded object property name. */
     readonly id: IdentifierNode;
+    /** Initializer expression, evaluated as a value rather than a property type annotation. */
     readonly value: Expression;
+    /** Object literal containing this initializer after binding. */
     readonly parent?: ObjectLiteralNode;
 }
+/** Object-value spread written `...source` inside `#{ ... }`. */
 export interface ObjectLiteralSpreadPropertyNode extends BaseNode {
+    /** Identifies property copying from an object value rather than from a model type. */
     readonly kind: SyntaxKind.ObjectLiteralSpreadProperty;
+    /** Reference to the object value whose properties are copied during evaluation. */
     readonly target: TypeReferenceNode;
+    /** Object literal containing this spread after binding. */
     readonly parent?: ObjectLiteralNode;
 }
+/** Array value literal written `#[ ... ]`, not a tuple type expression. */
 export interface ArrayLiteralNode extends BaseNode {
+    /** Distinguishes value-producing array syntax from tuple and array type syntax. */
     readonly kind: SyntaxKind.ArrayLiteral;
+    /** Element expressions in array index order, evaluated as values. */
     readonly values: readonly Expression[];
 }
+/** Primitive literal nodes and string-template text fragments; excludes whole templates and structural literals. */
 export type LiteralNode = StringLiteralNode | NumericLiteralNode | BooleanLiteralNode | StringTemplateHeadNode | StringTemplateMiddleNode | StringTemplateTailNode;
+/** Quoted string without unescaped interpolation, including triple-quoted strings. */
 export interface StringLiteralNode extends BaseNode {
+    /** Identifies a complete string literal rather than a fragment of an interpolated string. */
     readonly kind: SyntaxKind.StringLiteral;
+    /** Decoded content without delimiters; triple-quoted strings also have indentation removed. */
     readonly value: string;
 }
+/** Numeric literal retaining its source spelling independently of JavaScript number precision. */
 export interface NumericLiteralNode extends BaseNode {
+    /** Identifies numeric literal syntax, including decimal, hexadecimal, and binary forms. */
     readonly kind: SyntaxKind.NumericLiteral;
+    /** JavaScript `Number` conversion of the token, which may lose precision or overflow. */
     readonly value: number;
+    /** Original numeric token spelling, preserving radix, exponent, and precision for exact numeric handling. */
     readonly valueAsString: string;
 }
+/** Boolean literal written `true` or `false`. */
 export interface BooleanLiteralNode extends BaseNode {
+    /** Identifies a boolean literal rather than a reference named by an identifier. */
     readonly kind: SyntaxKind.BooleanLiteral;
+    /** `true` for the `true` keyword and `false` for the `false` keyword. */
     readonly value: boolean;
 }
+/** Interpolated string split into initial text and ordered expression/text pairs. */
 export interface StringTemplateExpressionNode extends BaseNode {
+    /** Identifies a string containing substitutions rather than a plain string literal. */
     readonly kind: SyntaxKind.StringTemplateExpression;
+    /** Text before the first substitution, possibly empty. */
     readonly head: StringTemplateHeadNode;
+    /** One span per substitution in source order; the final span ends in a tail node. */
     readonly spans: readonly StringTemplateSpanNode[];
 }
+/** A `${expression}` substitution paired with the string text immediately following it. */
 export interface StringTemplateSpanNode extends BaseNode {
+    /** Identifies an expression/text pair, not a standalone string token. */
     readonly kind: SyntaxKind.StringTemplateSpan;
+    /** Expression inside the substitution's braces. */
     readonly expression: Expression;
+    /** Following text: a middle fragment if another substitution follows, otherwise the closing tail. */
     readonly literal: StringTemplateMiddleNode | StringTemplateTailNode;
 }
+/** Shared decoded-text contract for the head, middle, and tail fragments of an interpolated string. */
 export interface StringTemplateLiteralLikeNode extends BaseNode {
+    /** Text without string or substitution delimiters, with escapes and triple-quote indentation processed. */
     readonly value: string;
 }
+/** Opening text fragment before an interpolated string's first `${...}` substitution. */
 export interface StringTemplateHeadNode extends StringTemplateLiteralLikeNode {
+    /** Identifies the initial fragment stored in {@link StringTemplateExpressionNode.head}. */
     readonly kind: SyntaxKind.StringTemplateHead;
 }
+/** Text fragment after one substitution and before the next in an interpolated string. */
 export interface StringTemplateMiddleNode extends StringTemplateLiteralLikeNode {
+    /** Indicates that another substitution follows this fragment. */
     readonly kind: SyntaxKind.StringTemplateMiddle;
 }
+/** Closing text fragment after the last substitution in an interpolated string. */
 export interface StringTemplateTailNode extends StringTemplateLiteralLikeNode {
+    /** Indicates that this fragment ends the interpolated string. */
     readonly kind: SyntaxKind.StringTemplateTail;
 }
+/** `extern` modifier token for a declaration implemented in JavaScript. */
 export interface ExternKeywordNode extends BaseNode {
+    /** Selects the externally implemented declaration modifier in {@link Modifier}. */
     readonly kind: SyntaxKind.ExternKeyword;
 }
+/** `internal` modifier token restricting a declaration's visibility to its package. */
 export interface InternalKeywordNode extends BaseNode {
+    /** Selects the package-visibility modifier in {@link Modifier}. */
     readonly kind: SyntaxKind.InternalKeyword;
 }
+/** `auto` modifier token requesting a compiler-provided decorator implementation. */
 export interface AutoKeywordNode extends BaseNode {
+    /** Selects the automatic-implementation modifier, mutually exclusive with `extern` on decorators. */
     readonly kind: SyntaxKind.AutoKeyword;
 }
+/** Intrinsic `void` type syntax, used for operations with no return value. */
 export interface VoidKeywordNode extends BaseNode {
+    /** Identifies the intrinsic keyword rather than an identifier named `void`. */
     readonly kind: SyntaxKind.VoidKeyword;
 }
+/** Intrinsic `never` type syntax, denoting a type with no possible values. */
 export interface NeverKeywordNode extends BaseNode {
+    /** Identifies the intrinsic keyword rather than a name resolved through lookup. */
     readonly kind: SyntaxKind.NeverKeyword;
 }
+/** Intrinsic `unknown` type syntax; the historical interface name does not imply an `any` keyword. */
 export interface AnyKeywordNode extends BaseNode {
+    /** Uses `UnknownKeyword` because the source spelling is `unknown`. */
     readonly kind: SyntaxKind.UnknownKeyword;
 }
+/** Infix type union such as `A | B`, distinct from a keyword-form union with variant declarations. */
 export interface UnionExpressionNode extends BaseNode {
+    /** Identifies infix union syntax rather than a named or inline keyword-form declaration. */
     readonly kind: SyntaxKind.UnionExpression;
+    /** Operand expressions in source order; parenthesized unions remain nested rather than being flattened here. */
     readonly options: readonly Expression[];
 }
+/** Infix intersection such as `A & B`, resolved to a model type by the checker. */
 export interface IntersectionExpressionNode extends BaseNode {
+    /** Identifies intersection syntax rather than an explicit model body. */
     readonly kind: SyntaxKind.IntersectionExpression;
+    /** Operand expressions in source order, before their properties are combined during checking. */
     readonly options: readonly Expression[];
 }
+/** Value constraint `valueof T`, permitting values whose types are assignable to the target type. */
 export interface ValueOfExpressionNode extends BaseNode {
+    /** Identifies a value constraint, not the type-of-value query written `typeof`. */
     readonly kind: SyntaxKind.ValueOfExpression;
+    /** Type expression following `valueof`. */
     readonly target: Expression;
 }
+/** Type query `typeof value`, obtaining the type of a value-producing expression. */
 export interface TypeOfExpressionNode extends BaseNode {
+    /** Identifies a type query rather than a `valueof` constraint. */
     readonly kind: SyntaxKind.TypeOfExpression;
+    /** Value-producing expression whose type is requested. */
     readonly target: Expression;
 }
+/** Name reference with an optional template argument list, interpreted in its checking context. */
 export interface TypeReferenceNode extends BaseNode {
+    /** Identifies a complete reference rather than a bare identifier or member-selection segment. */
     readonly kind: SyntaxKind.TypeReference;
+    /** Unqualified name or nested qualified name, excluding template arguments. */
     readonly target: MemberExpressionNode | IdentifierNode;
+    /** Explicit template arguments in source order; does not include inferred or default arguments. */
     readonly arguments: readonly TemplateArgumentNode[];
 }
+/** One positional expression or `name = expression` argument in a reference's `<...>` list. */
 export interface TemplateArgumentNode extends BaseNode {
+    /** Identifies an argument at a reference site, not a parameter declaration. */
     readonly kind: SyntaxKind.TemplateArgument;
+    /** Parameter name for a named argument; absent for positional arguments. */
     readonly name?: IdentifierNode;
+    /** Supplied argument expression, which may be checked as a type or value according to the parameter. */
     readonly argument: Expression;
 }
+/** Template parameter syntax, optionally constrained with `extends` and defaulted with `=`. */
 export interface TemplateParameterDeclarationNode extends BaseNode {
+    /** Identifies a declared template parameter rather than an argument supplied at a reference. */
     readonly kind: SyntaxKind.TemplateParameterDeclaration;
+    /** Explicit type, value, or mixed constraint following `extends`, absent when omitted. */
     readonly constraint?: Expression;
+    /** Argument expression to use when this parameter is omitted, absent when no default was written. */
     readonly default?: Expression;
+    /** Owning declaration after binding; declaration-expression owners may retain invalid template syntax for recovery. */
     readonly parent?: TemplateableNode;
+    /** Name introduced into the owning declaration's template scope. */
     readonly id: IdentifierNode;
 }
+/**
+ * Bit mask derived from a declaration's modifier tokens.
+ * Presence records parsed syntax, not validity; the checker enforces allowed and required combinations.
+ */
 export declare const enum ModifierFlags {
+    /** No modifier tokens were written. */
     None = 0,
+    /** An `extern` token requests a JavaScript implementation. */
     Extern = 2,
+    /** An `internal` token requests package-local visibility. */
     Internal = 4,
+    /** An `auto` token requests a compiler-provided decorator implementation. */
     Auto = 8,
+    /** Mask of every recognized modifier bit, not a combination valid on every declaration. */
     All = 14
 }
+/** Individual declaration modifier tokens, preserved separately from their combined bit mask. */
 export type Modifier = ExternKeywordNode | InternalKeywordNode | AutoKeywordNode;
 /**
  * Represent a decorator declaration
@@ -1479,6 +2136,7 @@ export type Modifier = ExternKeywordNode | InternalKeywordNode | AutoKeywordNode
  * ```
  */
 export interface DecoratorDeclarationStatementNode extends BaseNode, DeclarationNode {
+    /** Identifies a decorator signature declaration, not an application of that decorator. */
     readonly kind: SyntaxKind.DecoratorDeclarationStatement;
     /**
      * Decorator target. First parameter.
@@ -1488,11 +2146,19 @@ export interface DecoratorDeclarationStatementNode extends BaseNode, Declaration
      * Additional parameters
      */
     readonly parameters: FunctionParameterNode[];
+    /** Syntactic containing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
+/**
+ * Parameter syntax shared by functions, decorators, and scalar constructors.
+ * Invalid optional/rest combinations remain in the AST and are reported as diagnostics.
+ */
 export interface FunctionParameterNode extends BaseNode {
+    /** Identifies signature-parameter syntax rather than an operation's model-property parameter. */
     readonly kind: SyntaxKind.FunctionParameter;
+    /** Parameter name without an optional marker or rest prefix. */
     readonly id: IdentifierNode;
+    /** Constraint following `:`; absent when omitted, in which case checking uses `unknown`. */
     readonly type?: Expression;
     /**
      * Parameter defined with `?`
@@ -1512,9 +2178,13 @@ export interface FunctionParameterNode extends BaseNode {
  * ```
  */
 export interface FunctionDeclarationStatementNode extends BaseNode, DeclarationNode {
+    /** Identifies a named function declaration, distinct from an anonymous function type expression. */
     readonly kind: SyntaxKind.FunctionDeclarationStatement;
+    /** Declared parameters in source order; the JavaScript context parameter is not part of this list. */
     readonly parameters: FunctionParameterNode[];
+    /** Constraint following `:`, absent when omitted; checking defaults the result constraint to `unknown`. */
     readonly returnType?: Expression;
+    /** Syntactic containing file or namespace after binding. */
     readonly parent?: TypeSpecScriptNode | NamespaceStatementNode;
 }
 /**
@@ -1526,60 +2196,107 @@ export interface FunctionDeclarationStatementNode extends BaseNode, DeclarationN
  * ```
  */
 export interface FunctionTypeExpressionNode extends BaseNode {
+    /** Identifies anonymous function type syntax, not a named function declaration. */
     readonly kind: SyntaxKind.FunctionTypeExpression;
+    /** Signature parameters in source order, including optional and rest markers. */
     readonly parameters: FunctionParameterNode[];
+    /** Constraint following `=>`, absent when omitted; checking defaults the result constraint to `unknown`. */
     readonly returnType?: Expression;
 }
+/** Syntactic role of an identifier, used to choose reference resolution and completion behavior. */
 export interface IdentifierContext {
+    /** Context category, not the semantic type or symbol category of the identifier. */
     kind: IdentifierKind;
+    /** First ancestor that is not a member-expression segment, retaining the construct that gives the name its role. */
     node: Node;
 }
+/** Identifier roles classified by `getIdentifierContext`, independently of whether lookup succeeds. */
 export declare enum IdentifierKind {
+    /** Name within a type reference, including segments of a qualified target. */
     TypeReference = 0,
+    /** Named template argument's parameter name, not the expression supplied as its argument. */
     TemplateArgument = 1,
+    /** Decorator name in an attached annotation or out-of-line augment statement. */
     Decorator = 2,
+    /** Invocation target in a call expression, not a function declaration's name. */
     Function = 3,
+    /** Namespace name targeted by a `using` statement. */
     Using = 4,
+    /** Declaration name not classified by one of the property-specific roles. */
     Declaration = 5,
+    /** Property name in a structural model expression, including operation parameters. */
     ModelExpressionProperty = 6,
+    /** Property name in a model statement or keyword-form model declaration expression. */
     ModelStatementProperty = 7,
+    /** Property name in a `#{ ... }` object value literal. */
     ObjectLiteralProperty = 8,
+    /** Name in syntax without a more specific resolution or declaration role. */
     Other = 9
 }
+/**
+ * Parsed documentation comment, with free-form text separated from its block tags.
+ * These nodes are available when documentation parsing is enabled.
+ */
 export interface DocNode extends BaseNode {
+    /** Identifies a complete documentation comment. */
     readonly kind: SyntaxKind.Doc;
+    /** Text outside block tags, in source order; inspect node text rather than array length for a description. */
     readonly content: readonly DocContent[];
+    /** Recognized and unrecognized block tags, in source order. */
     readonly tags: readonly DocTag[];
 }
+/** Common syntax retained for every documentation block tag. */
 export interface DocTagBaseNode extends BaseNode {
+    /** Written tag name without the leading `@`, including unrecognized names. */
     readonly tagName: IdentifierNode;
+    /** Descriptive text after the tag name and any parameter or property name. */
     readonly content: readonly DocContent[];
 }
+/** Supported documentation block tags, including a fallback for unrecognized tags. */
 export type DocTag = DocReturnsTagNode | DocErrorsTagNode | DocParamTagNode | DocPropTagNode | DocTemplateTagNode | DocUnknownTagNode;
+/** Content within a documentation comment or tag; currently stored as text rather than parsed Markdown. */
 export type DocContent = DocTextNode;
+/** A text segment from a documentation comment, retaining Markdown as text. */
 export interface DocTextNode extends BaseNode {
+    /** Identifies documentation text rather than a block tag. */
     readonly kind: SyntaxKind.DocText;
+    /** Text with comment-line prefixes removed, line endings normalized, and outer whitespace trimmed. */
     readonly text: string;
 }
+/** Return-value documentation introduced by either `@return` or `@returns`. */
 export interface DocReturnsTagNode extends DocTagBaseNode {
+    /** Identifies either spelling of the return-documentation tag. */
     readonly kind: SyntaxKind.DocReturnsTag;
 }
+/** Error-response documentation introduced by `@errors`. */
 export interface DocErrorsTagNode extends DocTagBaseNode {
+    /** Identifies an error-documentation tag. */
     readonly kind: SyntaxKind.DocErrorsTag;
 }
+/** Documentation associated with the named parameter of a declaration. */
 export interface DocParamTagNode extends DocTagBaseNode {
+    /** Identifies an `@param` tag. */
     readonly kind: SyntaxKind.DocParamTag;
+    /** Parameter name as written in the comment, not a resolved parameter declaration. */
     readonly paramName: IdentifierNode;
 }
+/** Documentation associated with the named property of a model. */
 export interface DocPropTagNode extends DocTagBaseNode {
+    /** Identifies an `@prop` tag. */
     readonly kind: SyntaxKind.DocPropTag;
+    /** Property name as written in the comment, not a resolved property declaration. */
     readonly propName: IdentifierNode;
 }
+/** Documentation associated with a named template parameter. */
 export interface DocTemplateTagNode extends DocTagBaseNode {
+    /** Identifies an `@template` tag. */
     readonly kind: SyntaxKind.DocTemplateTag;
+    /** Template parameter name as written in the comment. */
     readonly paramName: IdentifierNode;
 }
+/** Unrecognized block tag retained for tools without assigning built-in semantics. */
 export interface DocUnknownTagNode extends DocTagBaseNode {
+    /** Identifies a tag whose name has no specialized documentation node. */
     readonly kind: SyntaxKind.DocUnknownTag;
 }
 /**
@@ -1601,15 +2318,30 @@ export interface LineAndCharacter {
      */
     character: number;
 }
+/** Loaded JavaScript module represented in the syntax graph without parsing its JavaScript source. */
 export interface JsSourceFileNode extends DeclarationNode, BaseNode {
+    /** Distinguishes a loaded JavaScript module from a parsed TypeSpec script. */
     readonly kind: SyntaxKind.JsSourceFile;
+    /** Empty source file carrying the module's path for diagnostic locations. */
     readonly file: SourceFile;
+    /** Module namespace object returned by the host's JavaScript import operation. */
     readonly esmExports: any;
 }
+/** Namespace declaration synthesized while binding JavaScript implementations to TypeSpec namespaces. */
 export interface JsNamespaceDeclarationNode extends DeclarationNode, BaseNode {
+    /** Distinguishes a JavaScript-provided namespace from a namespace written in TypeSpec. */
     readonly kind: SyntaxKind.JsNamespaceDeclaration;
 }
+/**
+ * Implementation of a library's `$onEmit` hook, invoked during emission after checking,
+ * validation, and linting. The compiler awaits a returned promise before continuing.
+ * Report issues through the context's program rather than returning diagnostics.
+ */
 export type EmitterFunc = (context: EmitContext) => Promise<void> | void;
+/**
+ * Source text and diagnostic identity shared by syntax nodes and source locations.
+ * Positions and line mappings refer to this text snapshot, not a subsequently modified file.
+ */
 export interface SourceFile {
     /** The source code text. */
     readonly text: string;
@@ -1643,19 +2375,24 @@ export interface SourceFile {
 export type LocationContext = ProjectLocationContext | CompilerLocationContext | SyntheticLocationContext | LibraryLocationContext;
 /** Defined in the user project. */
 export interface ProjectLocationContext {
+    /** Identifies source belonging to the consuming project rather than a dependency. */
     readonly type: "project";
+    /** Package flags exported by the project's JavaScript code, when available. */
     readonly flags?: PackageFlags;
 }
 /** Built-in */
 export interface CompilerLocationContext {
+    /** Identifies the compiler's standard-library source. */
     readonly type: "compiler";
 }
 /** Refer to a type that was not declared in a file */
 export interface SyntheticLocationContext {
+    /** Identifies a target for which no source-file location exists. */
     readonly type: "synthetic";
 }
 /** Defined in a library. */
 export interface LibraryLocationContext {
+    /** Identifies source loaded from a library package. */
     readonly type: "library";
     /** Library metadata */
     readonly metadata: ModuleLibraryMetadata;
@@ -1668,38 +2405,51 @@ export interface LibraryLocationContext {
      */
     readonly features?: readonly string[];
 }
+/** Resolution and exported contracts of a JavaScript library loaded by the program. */
 export interface LibraryInstance {
+    /** Resolved package or standalone file from which the JavaScript entry point was loaded. */
     module: ModuleResolutionResult;
+    /** Loaded JavaScript entry point and its exports. */
     entrypoint: JsSourceFileNode;
+    /** Package metadata, or standalone-file metadata when no package was resolved. */
     metadata: LibraryMetadata;
+    /** The entry point's `$lib` export, if it declares a TypeSpec library. */
     definition?: TypeSpecLibrary<any>;
+    /** Resolved `$linter` export; populated when the entry point provides a linter. */
     linter: LinterResolvedDefinition;
 }
+/** Metadata discriminated by whether the library resolved to a package or a standalone file. */
 export type LibraryMetadata = FileLibraryMetadata | ModuleLibraryMetadata;
+/** Optional package information used to describe a library and direct consumers to support resources. */
 interface LibraryMetadataBase {
     /** Library homepage. */
     homepage?: string;
     /** Library version */
     version?: string;
+    /** Issue-tracker metadata, when supplied by the package. */
     bugs?: {
         /** Url where to file bugs for this library. */
         url?: string;
     };
 }
+/** Metadata for a standalone JavaScript file, whose name may come from its `$lib` export. */
 export interface FileLibraryMetadata extends LibraryMetadataBase {
+    /** Identifies a library resolved directly to a file rather than a package. */
     type: "file";
     /** Library name as specified in the package.json or in exported $lib. */
     name?: string;
 }
 /** Data for a library. Either loaded via a node_modules package or a standalone js file  */
 export interface ModuleLibraryMetadata extends LibraryMetadataBase {
+    /** Identifies a library resolved through a package manifest. */
     readonly type: "module";
     /** Library name as specified in the package.json or in exported $lib. */
     readonly name: string;
 }
+/** Half-open range of UTF-16 code-unit offsets in a source string. */
 export interface TextRange {
     /**
-     * The starting position of the ranger measured in UTF-16 code units from the
+     * The starting position of the range measured in UTF-16 code units from the
      * start of the full string. Inclusive.
      */
     readonly pos: number;
@@ -1709,8 +2459,11 @@ export interface TextRange {
      */
     readonly end: number;
 }
+/** A source range together with the text snapshot to which its offsets refer. */
 export interface SourceLocation extends TextRange {
+    /** Source text and path used to resolve the range into line and character coordinates. */
     file: SourceFile;
+    /** True when the location is a placeholder rather than a range in actual source text. */
     isSynthetic?: boolean;
 }
 /** Used to explicitly specify that a diagnostic has no target. */
@@ -1724,24 +2477,50 @@ export interface TemplateInstanceTarget {
     /** Template mapper used. */
     readonly templateMapper: TypeMapper;
 }
+/** Semantic or syntax target resolved to a location when reporting, or an explicit source range. */
 export type DiagnosticTarget = TypeSpecDiagnosticTarget | SourceLocation;
+/** Whether an issue prevents successful compilation or is a potentially suppressible warning. */
 export type DiagnosticSeverity = "error" | "warning";
+/**
+ * A fully formatted compiler or library issue. Creating a diagnostic does not report it;
+ * pass it to the program's reporting APIs or return it to the caller as appropriate.
+ */
 export interface Diagnostic {
+    /** Diagnostic identifier, qualified as `<library-name>/<code>` for library diagnostics. */
     code: string;
+    /**
+     * Factories use the definition's severity. Program reporting may promote warnings
+     * to errors in `program.diagnostics` when `warningAsError` is enabled.
+     */
     severity: DiagnosticSeverity;
+    /** Human-readable message with any diagnostic format arguments already substituted. */
     message: string;
+    /** Location-bearing target, or {@link NoTarget} for an issue without a source location. */
     target: DiagnosticTarget | typeof NoTarget;
+    /** Available fixes offered to consumers; attaching a fix does not execute it. */
     readonly codefixes?: readonly CodeFix[];
 }
+/** A suggested source change that is resolved only when a consumer requests the fix. */
 export interface CodeFix {
+    /** Stable identifier used to select this fix, including by command-line code-fix selection. */
     readonly id: string;
+    /** Human-readable action label shown to users choosing a fix. */
     readonly label: string;
+    /**
+     * Computes edits when the fix is resolved, not when its diagnostic is reported.
+     * Context helpers only construct edits: return them to have the caller apply them.
+     * Returning nothing, including from an asynchronous callback, contributes no edits.
+     */
     readonly fix: (fixContext: CodeFixContext) => CodeFixEdit | CodeFixEdit[] | Promise<void> | void;
 }
+/** A UTF-16 insertion offset associated with a particular source-text snapshot. */
 export interface FilePos {
+    /** Zero-based offset from the start of the file's text. */
     readonly pos: number;
+    /** Source snapshot whose text the offset indexes. */
     readonly file: SourceFile;
 }
+/** Factories for text edits; calling them does not modify the source file. */
 export interface CodeFixContext {
     /** Add the given text before the range or pos given. */
     readonly prependText: (location: SourceLocation | FilePos, text: string) => InsertTextCodeFixEdit;
@@ -1750,38 +2529,65 @@ export interface CodeFixContext {
     /** Replace the text at the given range. */
     readonly replaceText: (location: SourceLocation, newText: string) => ReplaceTextCodeFixEdit;
 }
+/**
+ * Text insertion or half-open range replacement against an original source snapshot.
+ * Fixes must provide compatible, non-overlapping edits; application orders edits by offset.
+ */
 export type CodeFixEdit = InsertTextCodeFixEdit | ReplaceTextCodeFixEdit;
+/** Inserts text at an offset without removing any existing characters. */
 export interface InsertTextCodeFixEdit {
+    /** Selects insertion rather than range replacement. */
     readonly kind: "insert-text";
+    /** Text to insert verbatim. */
     readonly text: string;
+    /** Zero-based UTF-16 offset in the original file text. */
     readonly pos: number;
+    /** Source snapshot to edit; its path identifies the output file. */
     readonly file: SourceFile;
 }
+/** Replaces the inherited half-open range; an empty replacement deletes the range. */
 export interface ReplaceTextCodeFixEdit extends TextRange {
+    /** Selects replacement of a source range. */
     readonly kind: "replace-text";
+    /** Replacement text, or an empty string to remove the range. */
     readonly text: string;
+    /** Source snapshot to edit; range offsets refer to its original text. */
     readonly file: SourceFile;
 }
 /**
  * Return type of accessor functions in TypeSpec.
  * Tuple composed of:
  * - 0: Actual result of an accessor function
- * - 1: List of diagnostics that were emitted while retrieving the data.
+ * - 1: Diagnostics produced while retrieving the data, in collection order.
+ *
+ * Callers own reporting or propagating the returned diagnostics; the tuple itself
+ * does not report them to a program. An empty list indicates no collected issues.
  */
 export type DiagnosticResult<T> = [T, readonly Diagnostic[]];
+/** Syntax origin shared by interpreted compiler directives. */
 export interface DirectiveBase {
+    /** Original directive expression used to locate diagnostics about the directive. */
     node: DirectiveExpressionNode;
 }
+/** Interpreted suppression or deprecation directive attached to a declaration. */
 export type Directive = SuppressDirective | DeprecatedDirective;
+/** A `#suppress` directive requesting suppression of a matching warning in its scope. */
 export interface SuppressDirective extends DirectiveBase {
+    /** Selects warning-suppression semantics. */
     name: "suppress";
+    /** Diagnostic or linter rule code to suppress; error diagnostics cannot be suppressed. */
     code: string;
+    /** Author-supplied explanation for suppressing the warning. */
     message: string;
 }
+/** A `#deprecated` directive marking a declaration as deprecated for its consumers. */
 export interface DeprecatedDirective extends DirectiveBase {
+    /** Selects deprecation rather than warning suppression. */
     name: "deprecated";
+    /** Explanation surfaced when the deprecated declaration is used. */
     message: string;
 }
+/** Controls whether a host removal operation descends into a directory's contents. */
 export interface RmOptions {
     /**
      * If `true`, perform a recursive directory removal. In
@@ -1791,6 +2597,10 @@ export interface RmOptions {
      */
     recursive?: boolean;
 }
+/**
+ * Asynchronous file-system and URL capabilities used by compiler infrastructure.
+ * Hosts can be backed by a real or virtual file system; I/O failures reject the returned promises.
+ */
 export interface SystemHost {
     /** read a file at the given url. */
     readUrl(url: string): Promise<SourceFile>;
@@ -1818,23 +2628,38 @@ export interface SystemHost {
      * @param path Path to the directory.
      */
     mkdirp(path: string): Promise<string | undefined>;
+    /** Inspects a path; the returned predicates identify directories and regular files respectively. */
     stat(path: string): Promise<{
         isDirectory(): boolean;
         isFile(): boolean;
     }>;
+    /** Resolves a possibly symlinked path to its real file-system path. */
     realpath(path: string): Promise<string>;
 }
+/**
+ * Host capabilities required to compile TypeSpec, extending file I/O with module loading,
+ * source-kind detection, standard-library discovery, and log delivery.
+ */
 export interface CompilerHost extends SystemHost {
     /**
      * Optional cache to reuse the results of parsing and binding across programs.
+     * Entries are keyed by source-file identity, not path; reuse a source snapshot only
+     * while its text is unchanged.
      */
     parseCache?: WeakMap<SourceFile, TypeSpecScriptNode>;
+    /** Returns the compiler's installation root, used to locate bundled compiler resources. */
     getExecutionRoot(): string;
+    /** Returns directories containing standard-library entry points to load for compilation. */
     getLibDirs(): string[];
+    /** Loads a JavaScript module and returns its module namespace object, including TypeSpec hook exports. */
     getJsImport(path: string): Promise<Record<string, any>>;
+    /** Classifies a source path for loading, or returns undefined when the host does not recognize it. */
     getSourceFileKind(path: string): SourceFileKind | undefined;
+    /** Converts a file URL into a path understood by this host's file-system operations. */
     fileURLToPath(url: string): string;
+    /** Converts a host file-system path into a file URL. */
     pathToFileURL(path: string): string;
+    /** Receives processed log messages produced by compiler logging. */
     logSink: LogSink;
 }
 /**
@@ -1842,9 +2667,11 @@ export interface CompilerHost extends SystemHost {
  */
 export type SourceFileKind = "typespec" | "js";
 type UnionToIntersection<T> = (T extends any ? (k: T) => void : never) extends (k: infer I) => void ? I : never;
+/** Traversal control returned by semantic listeners when the navigation API honors callback results. */
 export declare enum ListenerFlow {
     /**
-     * Do not navigate any containing or referenced type.
+     * Skip recursive traversal from the current type, and its exit callback when
+     * that navigation path checks this result. This does not stop the whole walk.
      */
     NoRecursion = 1
 }
@@ -1856,14 +2683,26 @@ type exitListener<T extends string | number | symbol> = T extends string ? `exit
 type ListenerForType<T extends Type> = T extends Type ? {
     [k in Uncapitalize<T["kind"]> | exitListener<T["kind"]>]?: TypeListener<T>;
 } : never;
+/**
+ * Optional synchronous callbacks keyed by uncapitalized type kind, such as `model`,
+ * and corresponding exit names, such as `exitModel`.
+ * Entry callbacks run before following the type's relationships; exit callbacks,
+ * where emitted by the walker, run afterward. This walks the semantic graph, not syntax.
+ */
 export type TypeListeners = UnionToIntersection<ListenerForType<Type>>;
 type ValueListener<V> = (context: V) => ListenerFlow | undefined | void;
 type exitValueListener<T extends string | number | symbol> = T extends string ? `exit${T}` : T;
 type ListenerForValue<V extends Value> = V extends Value ? {
     [k in Uncapitalize<V["valueKind"]> | exitValueListener<V["valueKind"]>]?: ValueListener<V>;
 } : never;
+/**
+ * Optional synchronous callbacks keyed by uncapitalized value kind and corresponding
+ * exit names. A callback is invoked only when the selected navigation API visits that value.
+ */
 export type ValueListeners = UnionToIntersection<ListenerForValue<Value>>;
+/** Callbacks for semantic navigation, with an optional program-level entry event. */
 export type SemanticNodeListener = {
+    /** Called once by program navigation before visiting the global namespace. */
     root?: (context: Program) => void | undefined;
 } & TypeListeners & ValueListeners;
 /**
@@ -1896,18 +2735,24 @@ export interface TypeInfoContext {
  * Providers are gated behind the experimental `type-info-provider` compiler feature.
  */
 export type TypeInfoProvider = (context: TypeInfoContext) => TypeInfo | undefined;
+/** Input to a diagnostic factory before a source target is attached. */
 export type DiagnosticReportWithoutTarget<T extends {
     [code: string]: DiagnosticMessages;
 }, C extends keyof T, M extends keyof T[C] = "default"> = {
+    /** Unqualified code declared in the diagnostic map. */
     code: C;
+    /** Message variant to format; omitted selects `"default"`. */
     messageId?: M;
+    /** Optional fixes to attach to the created diagnostic without executing them. */
     readonly codefixes?: readonly CodeFix[];
 } & DiagnosticFormat<T, C, M>;
+/** Complete diagnostic-factory input, including a source-location target or explicit {@link NoTarget}. */
 export type DiagnosticReport<T extends {
     [code: string]: DiagnosticMessages;
 }, C extends keyof T, M extends keyof T[C] = "default"> = DiagnosticReportWithoutTarget<T, C, M> & {
     target: DiagnosticTarget | typeof NoTarget;
 };
+/** Requires a `format` map of named string substitutions when the selected message is a callable message template. */
 export type DiagnosticFormat<T extends {
     [code: string]: DiagnosticMessages;
 }, C extends keyof T, M extends keyof T[C] = "default"> = T[C][M] extends CallableMessage<infer A> ? {
@@ -1949,38 +2794,62 @@ export interface DiagnosticDefinition<M extends DiagnosticMessages> {
      */
     readonly docs?: string | FileRef;
 }
+/** Named message variants for one diagnostic or linter rule; `"default"` is used when no variant is selected. */
 export interface DiagnosticMessages {
+    /** Literal text or a formatter keyed by the message variant name. */
     readonly [messageId: string]: string | CallableMessage<string[]>;
 }
+/** Message formatter produced by {@link paramMessage}, with its substitution names retained for typing. */
 export interface CallableMessage<T extends string[]> {
+    /** Substitution names in template order; names may repeat when referenced more than once. */
     keys: T;
+    /** Formats the message using the supplied string value for each substitution name. */
     (dict: Record<T[number], string>): string;
 }
+/** Diagnostic definitions keyed by unqualified diagnostic code, preserving each code's message variants. */
 export type DiagnosticMap<T extends {
     [code: string]: DiagnosticMessages;
 }> = {
+    /** Severity, message variants, and optional metadata for this diagnostic code. */
     readonly [code in keyof T]: DiagnosticDefinition<T[code]>;
 };
+/** Typed factory and reporting operations for a fixed set of diagnostic definitions. */
 export interface DiagnosticCreator<T extends {
     [code: string]: DiagnosticMessages;
 }> {
+    /** Type-only carrier for message inference; not populated by the diagnostic creator at runtime. */
     readonly type: T;
+    /** Definitions used to determine severity and format messages. */
     readonly diagnostics: DiagnosticMap<T>;
+    /**
+     * Formats a diagnostic without reporting it. Throws if the code or selected message
+     * is not defined; library-scoped creators qualify the resulting diagnostic code.
+     */
     createDiagnostic<C extends keyof T, M extends keyof T[C] = "default">(diag: DiagnosticReport<T, C, M>): Diagnostic;
+    /** Creates and reports the diagnostic through the program, which applies its reporting policies. */
     reportDiagnostic<C extends keyof T, M extends keyof T[C] = "default">(program: Program, diag: DiagnosticReport<T, C, M>): void;
 }
+/** Extracts the code-to-message type from a diagnostic definition map for reuse in generic APIs. */
 export type TypeOfDiagnostics<T extends DiagnosticMap<any>> = T extends DiagnosticMap<infer D> ? D : never;
+/** JSON Schema typed against an emitter's options, used to validate configured option values. */
 export type JSONSchemaType<T> = AjvJSONSchemaType<T>;
+/** Metadata for a library state key whose symbol is created with the library. */
 export interface StateDef {
     /**
      * Description for this state.
      */
     readonly description?: string;
 }
+/** Opt-in compiler behavior supported by a library or emitter. */
 export interface TypeSpecLibraryCapabilities {
-    /** Only applicable for emitters. Specify that this emitter will respect the dryRun flag and run, report diagnostic but not write any output.  */
+    /**
+     * Allows an emitter to run during dry-run compilation. The emitter must inspect
+     * the program's dry-run option and avoid writing output while still reporting diagnostics.
+     * Emitters without this capability are skipped in dry-run mode.
+     */
     readonly dryRun?: boolean;
 }
+/** Definition supplied to {@link createTypeSpecLibrary} and typically exported as `$lib`. */
 export interface TypeSpecLibraryDef<T extends {
     [code: string]: DiagnosticMessages;
 }, E extends Record<string, any> = Record<string, never>, State extends string = never> {
@@ -2007,11 +2876,13 @@ export interface TypeSpecLibraryDef<T extends {
      */
     readonly requireImports?: readonly string[];
     /**
-     * Emitter configuration if library is an emitter.
+     * Emitter configuration if library is an emitter. Its optional `options` JSON Schema
+     * validates custom configuration before the emitter runs; omit it when no schema is supplied.
      */
     readonly emitter?: {
         options?: JSONSchemaType<E>;
     };
+    /** Named state definitions used to create the corresponding symbols in the library's `stateKeys` map. */
     readonly state?: Record<State, StateDef>;
 }
 /**
@@ -2028,7 +2899,9 @@ export interface TypeSpecLibraryDef<T extends {
  * ```
  */
 export interface DecoratorImplementations {
+    /** Implementations grouped by fully qualified TypeSpec namespace, not JavaScript module path. */
     readonly [namespace: string]: {
+        /** Decorator implementations keyed by their TypeSpec names, without the JavaScript `$` prefix. */
         readonly [name: string]: DecoratorFunction;
     };
 }
@@ -2037,18 +2910,29 @@ export interface FunctionImplementations {
         readonly [name: string]: (ctx: FunctionContext, ...parameters: never[]) => unknown;
     };
 }
+/** Extension point for package-level flags exported as `$flags`; no flags are currently predefined. */
 export interface PackageFlags {
 }
+/** A library's `$linter` export: available rules and optional named rule-set configurations. */
 export interface LinterDefinition {
+    /** Rule definitions in registration order; listing a rule does not enable it. */
     rules: LinterRuleDefinition<string, DiagnosticMessages, any>[];
+    /** Named presets consumers can extend, with names local to this library. */
     ruleSets?: Record<string, LinterRuleSet>;
 }
+/** Loaded linter definition with library-qualified rule IDs and a materialized rule-set map. */
 export interface LinterResolvedDefinition {
+    /** Rules in definition order, each with its library-qualified ID. */
     readonly rules: LinterRule<string, DiagnosticMessages, any>[];
+    /**
+     * Named presets. A nonempty rule list gets an `"all"` preset enabling every rule
+     * unless the library explicitly defines one; otherwise this map may be empty.
+     */
     readonly ruleSets: {
         [name: string]: LinterRuleSet;
     };
 }
+/** Shared diagnostic metadata and option configuration for synchronous and asynchronous rules. */
 interface LinterRuleDefinitionBase<N extends string, DM extends DiagnosticMessages, Options extends Record<string, unknown> = Record<string, never>> {
     /** Rule name (without the library name) */
     name: N;
@@ -2071,32 +2955,46 @@ interface LinterRuleDefinitionBase<N extends string, DM extends DiagnosticMessag
      * When provided, options will be validated against this schema before the rule runs.
      */
     optionSchema?: Record<string, unknown>;
-    /** Default options for the rule, used when enabled with `true` and no options are specified. */
+    /** Defaults used with `true` and shallowly merged with explicitly configured option properties. */
     defaultOptions?: Options;
 }
+/** Rule whose navigation callbacks and post-navigation `exit` callback must all complete synchronously. */
 interface LinterRuleDefinitionSync<N extends string, DM extends DiagnosticMessages, Options extends Record<string, unknown> = Record<string, never>> extends LinterRuleDefinitionBase<N, DM, Options> {
     /** Whether this is an async rule. Default is false */
     async?: false;
-    /** Creator */
+    /**
+     * Creates a fresh listener before navigation. Its optional `exit` callback runs
+     * after the walk with the program. Linter dispatch ignores listener return values,
+     * including {@link ListenerFlow.NoRecursion}.
+     */
     create(context: LinterRuleContext<DM, Options>): SemanticNodeListener & {
         exit?: (context: Program) => void | undefined;
     };
 }
+/**
+ * Rule run in the asynchronous-rule pass after synchronous rules finish.
+ * Navigation callbacks remain synchronous; only the post-navigation `exit` callback may return a promise.
+ */
 interface LinterRuleDefinitionAsync<N extends string, DM extends DiagnosticMessages, Options extends Record<string, unknown> = Record<string, never>> extends LinterRuleDefinitionBase<N, DM, Options> {
-    /** Whether this is an async rule. Default is false */
+    /** Enables awaiting the promise returned by the post-navigation `exit` callback. */
     async: true;
-    /** Creator */
+    /**
+     * Creates a fresh listener before navigation. `exit` runs after the walk, and
+     * its promise is awaited before the asynchronous-rule pass completes.
+     * Linter dispatch ignores navigation callback return values.
+     */
     create(context: LinterRuleContext<DM, Options>): SemanticNodeListener & {
         exit?: (context: Program) => Promise<void | undefined>;
     };
 }
+/** Rule definition discriminated by whether its post-navigation callback can perform asynchronous work. */
 export type LinterRuleDefinition<N extends string, DM extends DiagnosticMessages, Options extends Record<string, unknown> = Record<string, never>> = LinterRuleDefinitionSync<N, DM, Options> | LinterRuleDefinitionAsync<N, DM, Options>;
 /** Resolved instance of a linter rule that will run. */
 export type LinterRule<N extends string, DM extends DiagnosticMessages, Options extends Record<string, unknown> = Record<string, never>> = LinterRuleDefinition<N, DM, Options> & {
-    /** Expanded rule id in format `<library-name>:<rule-name>` */
+    /** Expanded rule ID in the form `<library-name>/<rule-name>`, used as its diagnostic code. */
     id: string;
 };
-/** Reference to a rule. In this format `<library name>:<rule/ruleset name>` */
+/** Library-qualified reference in the form `<library-name>/<rule-or-ruleset-name>`. */
 export type RuleRef = `${string}/${string}`;
 /**
  * Reference to a ruleset defined in a yaml file. In this format `file:<path to the yaml file>`.
@@ -2109,39 +3007,59 @@ export type RuleSetRef = RuleRef | RuleSetFileRef;
 /**
  * Value for enabling a linter rule.
  * - `true` enables the rule with default options.
- * - An object enables the rule with the specified options.
+ * - `false` skips enabling the rule; it does not disable a rule enabled by an extended preset.
+ * - An object enables the rule with its properties shallowly merged over default options.
  */
 export type LinterRuleEnableValue = boolean | Record<string, unknown>;
+/** Preset applied by extending other rule sets, then applying local enable and disable entries. */
 export interface LinterRuleSet {
-    /** Other ruleset this ruleset extends */
+    /** Rule sets to apply first, in array order, before this preset's own entries. */
     extends?: RuleSetRef[];
-    /** Rules to enable/configure */
+    /** Rules to enable/configure, keyed by library-qualified reference. Entries set to `false` are ignored. */
     enable?: Record<RuleRef, LinterRuleEnableValue>;
-    /** Rules to disable. A rule CANNOT be in enable and disable map. */
+    /** Rules to disable, with explanatory strings as values. A rule cannot also be enabled in this preset. */
     disable?: Record<RuleRef, string>;
 }
+/** Per-run rule context providing resolved options and a rule-scoped diagnostic collector. */
 export interface LinterRuleContext<DM extends DiagnosticMessages, Options extends Record<string, unknown> = Record<string, never>> {
+    /** Program being linted; report rule findings through this context rather than directly to the program. */
     readonly program: Program;
-    /** Options configured for this rule. */
+    /** Configured properties merged over rule defaults, or an empty object when neither is provided. */
     readonly options: Options;
+    /**
+     * Formats a warning using this rule's ID and messages and adds it to the linter's results.
+     * Only targets belonging to the user project are collected: library, compiler,
+     * synthetic, and {@link NoTarget} findings are ignored. The program later reports collected findings.
+     */
     reportDiagnostic<M extends keyof DM>(diag: LinterRuleDiagnosticReport<DM, M>): void;
 }
+/** Requires a `format` substitution map when the selected rule message is callable. */
 export type LinterRuleDiagnosticFormat<T extends DiagnosticMessages, M extends keyof T = "default"> = T[M] extends CallableMessage<infer A> ? {
     format: Record<A[number], string>;
 } : Record<string, unknown>;
+/** Rule finding before its source target is attached; the context supplies the rule code and severity. */
 export type LinterRuleDiagnosticReportWithoutTarget<T extends DiagnosticMessages, M extends keyof T = "default"> = {
+    /** Message variant to use; omitted selects `"default"`. */
     messageId?: M;
+    /** Optional actions offered with the finding, without executing them during linting. */
     codefixes?: CodeFix[];
 } & LinterRuleDiagnosticFormat<T, M>;
+/**
+ * Rule finding with a source-location target. Although {@link NoTarget} is accepted
+ * by the shape, the linter only collects findings whose targets belong to the user project.
+ */
 export type LinterRuleDiagnosticReport<T extends DiagnosticMessages, M extends keyof T = "default"> = LinterRuleDiagnosticReportWithoutTarget<T, M> & {
     target: DiagnosticTarget | typeof NoTarget;
 };
+/** Library definition enriched with diagnostic, state-key, and tracing helpers by {@link createTypeSpecLibrary}. */
 export interface TypeSpecLibrary<T extends {
     [code: string]: DiagnosticMessages;
 }, E extends Record<string, any> = Record<string, never>, State extends string = never> extends TypeSpecLibraryDef<T, E, State> {
     /** Library name */
     readonly name: string;
+    /** Creates a library-qualified diagnostic and reports it through the program's reporting policies. */
     reportDiagnostic<C extends keyof T, M extends keyof T[C]>(program: Program, diag: DiagnosticReport<T, C, M>): void;
+    /** Creates a library-qualified diagnostic without reporting it; the caller owns reporting or returning it. */
     createDiagnostic<C extends keyof T, M extends keyof T[C]>(diag: DiagnosticReport<T, C, M>): Diagnostic;
     /**
      * Get or create a symbol with the given name unique for that library.
@@ -2153,10 +3071,11 @@ export interface TypeSpecLibrary<T extends {
      * All trace area logged via this tracer will be prefixed with the library name.
      */
     getTracer(program: Program): Tracer;
+    /** Symbols for declared state names, registered as `<library-name>/<state-name>` for program state maps and sets. */
     readonly stateKeys: Record<State, symbol>;
 }
 /**
- * Get the options for the onEmit of this library.
+ * Extracts the custom emitter-option type declared by a TypeSpec library for its `$onEmit` hook.
  */
 export type EmitOptionsFor<C> = C extends TypeSpecLibrary<infer _T, infer E> ? E : never;
 /**
@@ -2224,17 +3143,20 @@ export interface FunctionContext extends InvocationContext {
      */
     functionCallTarget: DiagnosticTarget;
 }
+/** Per-emitter compilation context supplied to `$onEmit`, including options and performance reporting. */
 export interface EmitContext<TOptions extends object = Record<string, never>> {
     /**
-     * TypeSpec Program.
+     * Checked program being emitted. Use its reporting APIs to report emitter diagnostics.
      */
     program: Program;
     /**
-     * Configured output dir for the emitter. Emitter should emit all output under that directory.
+     * Resolved output directory for this emitter, including its configured override if any.
+     * Emit all output beneath this directory rather than the program's shared output directory.
      */
     emitterOutputDir: string;
     /**
-     * Emitter custom options defined in createTypeSpecLibrary
+     * Custom options configured for this emitter, validated when the library declares an options schema.
+     * The compiler's `emitter-output-dir` option is removed and exposed as `emitterOutputDir` instead.
      */
     options: TOptions;
     /**
@@ -2244,12 +3166,21 @@ export interface EmitContext<TOptions extends object = Record<string, never>> {
      */
     readonly perf: PerfReporter;
 }
+/** Elapsed-time measurement handle returned by compiler performance utilities. */
 export interface Timer {
+    /**
+     * Returns milliseconds since the timer started. A reporting timer also records
+     * the measurement under its label; repeated calls measure again from the original start.
+     */
     end: () => number;
 }
+/**
+ * Records an emitter's named performance measurements for compiler statistics.
+ * Measurements use milliseconds; recording the same label replaces its previous value.
+ */
 export interface PerfReporter {
     /**
-     * Start timer for the given label.
+     * Starts a timer whose measurement is recorded under the label when `end()` is called.
      *
      * @example
      * ```ts
@@ -2259,9 +3190,9 @@ export interface PerfReporter {
      * ```
      */
     startTimer(label: string): Timer;
-    /** Report a sync function elapsed time.  */
+    /** Calls the callback immediately, records elapsed time on successful return, and returns its result. */
     time<T>(label: string, callback: () => T): T;
-    /** Report an async function elapsed time.  */
+    /** Calls and awaits the callback, records elapsed time on successful resolution, and returns its result. */
     timeAsync<T>(label: string, callback: () => Promise<T>): Promise<T>;
     /**
      * Report a custom elapsed time for the given label.
@@ -2280,43 +3211,70 @@ export interface PerfReporter {
      */
     report(label: string, milliseconds: number): void;
 }
+/** Log severity, ordered from verbose tracing through warnings to errors for logger filtering. */
 export type LogLevel = "trace" | "warning" | "error";
+/** Input to a logger before its optional target is resolved to a source location. */
 export interface LogInfo {
+    /** Severity used by the logger's configured minimum-level filter. */
     level: LogLevel;
+    /** Human-readable text delivered to the sink when the message passes filtering. */
     message: string;
+    /** Optional diagnostic identifier or trace-area name; absent for messages without a code. */
     code?: string;
+    /** Optional location-bearing target; absent or {@link NoTarget} produces no source location. */
     target?: DiagnosticTarget | typeof NoTarget;
 }
+/** Log entry ready for a sink, with any source target already resolved to a location. */
 export interface ProcessedLog {
+    /** Severity to display; filtering is normally performed before sink delivery. */
     level: LogLevel;
+    /** Human-readable message to display. */
     message: string;
+    /** Optional diagnostic identifier or trace-area name associated with the message. */
     code?: string;
     /** Documentation for the error code. */
     url?: string;
-    /** Log location */
+    /** Resolved location when a target was supplied; may be synthetic when no actual source is available. */
     sourceLocation?: SourceLocation;
 }
+/** Destination for processed compiler log entries, such as a console or editor integration. */
 export interface LogSink {
+    /** Consumes one processed log entry; delivery does not itself add a diagnostic to a program. */
     log(log: ProcessedLog): void;
 }
+/**
+ * Filters and forwards log messages to a sink. Logging warnings or errors does not
+ * report program diagnostics or change compilation success.
+ */
 export interface Logger {
+    /** Logs a trace message without a code, subject to the configured minimum log level. */
     trace(message: string): void;
+    /** Logs a warning without a code or a program diagnostic. */
     warn(message: string): void;
+    /** Logs an error without a code or a program diagnostic. */
     error(message: string): void;
+    /** Filters by severity, resolves the optional target, and forwards the entry to the sink. */
     log(log: LogInfo): void;
 }
+/** Selects which dot-separated trace areas a tracer forwards to its logger. */
 export interface TracerOptions {
+    /**
+     * Area prefixes to enable, such as `"http"` or `"http.route"`; `"*"` enables all areas.
+     * A prefix enables its descendants. Omitted or empty filters disable tracing.
+     */
     filter?: string[];
 }
+/** Hierarchical tracing whose enabled areas are controlled by {@link TracerOptions}. */
 export interface Tracer {
     /**
-     * Trace
-     * @param area
-     * @param message
+     * Logs a message under a dot-separated area when that area is enabled.
+     * The default compiler tracer uses the area as the log code and does not forward
+     * the optional target to its logger.
      */
     trace(area: string, message: string, target?: DiagnosticTarget): void;
     /**
-     * @param subarea
+     * Returns a child tracer that prefixes subsequent areas with this subarea,
+     * separated by a dot. Child tracers share the parent's filtering and log destination.
      */
     sub(subarea: string): Tracer;
 }