@@ -9,25 +9,41 @@ import {
 import type { Typekit } from "@typespec/compiler/typekit";
 import { isHeader } from "@typespec/http";
 
+/** The codec selected for a source type and the two type-graph projections it produces. */
 export interface EncodingInfo {
+  /** First codec in the registry that accepted the source and its reference context. */
   codec: Codec;
+  /** Type exposed to generated language code; may be the unmodified source type. */
   languageType: Type;
+  /** Type describing the serialized representation, not an encoded runtime value. */
   wireType: Type;
 }
 
+/**
+ * Selects a codec by registration order. A registry starts empty; register an
+ * {@link IdentityCodec} last when unrecognized types should pass through.
+ */
 export class CodecRegistry {
+  /** Typekit supplied to every codec when selecting a representation. */
   $: Typekit;
   #codecs: Codec[];
 
+  /** Creates an empty registry bound to the typekit's program. */
   constructor($: Typekit) {
     this.$ = $;
     this.#codecs = [];
   }
 
+  /** Appends a codec; previously registered codecs retain priority. */
   addCodec(codec: Codec) {
     this.#codecs.push(codec);
   }
 
+  /**
+   * Returns the first non-null codec result, together with the selected codec.
+   * Reference members let codecs honor use-site metadata before type metadata.
+   * @throws Error when every registered codec declines the source type.
+   */
   encode(sourceType: Type, referenceTypes: MemberType[]): EncodingInfo {
     for (const codec of this.#codecs) {
       const result = codec.encode(this.$, sourceType, referenceTypes);
@@ -40,15 +56,34 @@ export class CodecRegistry {
   }
 }
 
+/**
+ * Chooses language and wire types for a source type in its use-site context.
+ * Codecs describe representations; they do not serialize or deserialize values.
+ */
 export abstract class Codec {
+  /** Stable selection identifier, also used in scalar canonicalization cache keys. */
   abstract id: string;
 
+  /**
+   * Selects type representations, or returns `null` to let the next codec try.
+   * @param referenceTypes Members referencing the source, in metadata lookup order.
+   */
   abstract encode(
     $: Typekit,
     sourceType: Type,
     referenceTypes: MemberType[],
-  ): { languageType: Type; wireType: Type } | null;
-
+  ): {
+    /** Type to use in the generated language's type graph. */
+    languageType: Type;
+    /** Type to use in the serialized payload's type graph. */
+    wireType: Type;
+  } | null;
+
+  /**
+   * Finds the first truthy metadata value on applicable reference members, then
+   * falls back to the source type. The source getter's result is returned as-is;
+   * without a source or a matching member value, returns `undefined`.
+   */
   static getMetadata<
     TTypeSource extends Type,
     TMemberSource extends MemberType,
@@ -84,9 +119,12 @@ export abstract class Codec {
   }
 }
 
+/** Fallback codec that accepts every type and preserves both representations. */
 export class IdentityCodec extends Codec {
+  /** Marks the result as unchanged for identity-codec predicates. */
   readonly id = "identity";
 
+  /** Returns the source object itself for both language and wire types. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     return {
       wireType: sourceType,
@@ -95,9 +133,15 @@ export class IdentityCodec extends Codec {
   }
 }
 
+/**
+ * Recognizes UTC date-time scalars encoded as `"unix-timestamp"` with `int64`.
+ * Use-site encoding metadata takes precedence over scalar metadata.
+ */
 export class UnixTimestamp64Codec extends Codec {
+  /** Distinguishes this timestamp selection in scalar cache keys. */
   readonly id = "unix-timestamp-64";
 
+  /** Uses builtin `utcDateTime` and `float64`, or declines nonmatching encodings. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (!$.scalar.is(sourceType) || !$.type.isAssignableTo(sourceType, $.builtin.utcDateTime)) {
       return null;
@@ -126,9 +170,15 @@ export class UnixTimestamp64Codec extends Codec {
   }
 }
 
+/**
+ * Recognizes UTC date-time scalars encoded as `"unixTimestamp"` with `int32`.
+ * Use-site encoding metadata takes precedence over scalar metadata.
+ */
 export class UnixTimestamp32Codec extends Codec {
+  /** Distinguishes this timestamp selection in scalar cache keys. */
   readonly id = "unix-timestamp-32";
 
+  /** Uses builtin `utcDateTime` and `float64`, or declines nonmatching encodings. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (!$.scalar.is(sourceType) || !$.type.isAssignableTo(sourceType, $.builtin.utcDateTime)) {
       return null;
@@ -157,9 +207,15 @@ export class UnixTimestamp32Codec extends Codec {
   }
 }
 
+/**
+ * Fallback string representation for scalars assignable to `utcDateTime`.
+ * Does not inspect encoding metadata; register more specific date codecs first.
+ */
 export class Rfc3339Codec extends Codec {
+  /** Distinguishes the RFC 3339 selection in scalar cache keys. */
   readonly id = "rfc3339";
 
+  /** Preserves the date-time language type and uses `string` on the wire, or declines. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (!$.scalar.is(sourceType) || !$.type.isAssignableTo(sourceType, $.builtin.utcDateTime)) {
       return null;
@@ -172,9 +228,15 @@ export class Rfc3339Codec extends Codec {
   }
 }
 
+/**
+ * Selects the HTTP-date string representation for UTC date-time scalars.
+ * Accepts explicit `rfc7231` encoding, or a header use site with no encoding.
+ */
 export class Rfc7231Codec extends Codec {
+  /** Distinguishes the HTTP-date selection in scalar cache keys. */
   readonly id = "rfc7231";
 
+  /** Preserves the source date-time type and uses `string` on the wire, or declines. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (!$.scalar.is(sourceType) || !$.type.isAssignableTo(sourceType, $.builtin.utcDateTime)) {
       return null;
@@ -209,9 +271,15 @@ export class Rfc7231Codec extends Codec {
   }
 }
 
+/**
+ * Selects a string wire representation for types assignable to `bytes`.
+ * This selection does not inspect an explicit encoding decorator.
+ */
 export class Base64Codec extends Codec {
+  /** Identifies the byte-to-string representation. */
   readonly id = "base64";
 
+  /** Preserves the byte language type and uses `string` on the wire, or declines. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (!$.type.isAssignableTo(sourceType, $.builtin.bytes)) {
       return null;
@@ -224,19 +292,30 @@ export class Base64Codec extends Codec {
   }
 }
 
+/**
+ * Optional category filters for numeric codec selection. Neither flag bypasses
+ * the final requirement to extend `float`, `int32`, or `uint32`.
+ */
 export interface CoerceToFloat64CodecOptions {
+  /** When true, additionally requires an integer or float scalar; defaults to false. */
   lossyInteger?: boolean;
+  /** When true, additionally requires a decimal or float scalar; defaults to false. */
   lossyDecimal?: boolean;
 }
 
+/** Uses `float64` on the wire for scalars extending `float`, `int32`, or `uint32`. */
 export class CoerceToFloat64Codec extends Codec {
+  /** Identifies numeric wire coercion without a language-type replacement. */
   readonly id = "coerce-to-float64";
+  /** Category filters consulted on each call; the supplied object is retained. */
   options: CoerceToFloat64CodecOptions;
+  /** Creates a numeric codec with no additional category filters by default. */
   constructor(options: CoerceToFloat64CodecOptions = {}) {
     super();
     this.options = options;
   }
 
+  /** Preserves an accepted numeric language type and uses `float64`, or returns `null`. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (
       this.options.lossyInteger &&
@@ -271,9 +350,15 @@ export class CoerceToFloat64Codec extends Codec {
   }
 }
 
+/**
+ * Selects a string wire representation for any array type, regardless of HTTP
+ * location. The codec does not choose a delimiter or perform the join itself.
+ */
 export class ArrayJoinCodec extends Codec {
+  /** Identifies an array represented as a string on the wire. */
   readonly id = "array-join";
 
+  /** Preserves the array language type and uses `string` on the wire, or declines. */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (!$.array.is(sourceType)) {
       return null;
@@ -288,22 +373,32 @@ export class ArrayJoinCodec extends Codec {
   }
 }
 
+/** Naming hook used after checking a property's `@friendlyName`. */
 interface RenameCodecOptions {
+  /** Returns a language-side property name, or `undefined` to leave it unchanged. */
   namer?(type: Type): string | undefined;
 }
 /**
  * Renames the language type according to the language's name policy and
  * friendly name decorator.
  */
 export class RenameCodec extends Codec {
+  /** Identifies a language-only model property rename. */
   readonly id = "model-property-rename";
+  /** Naming configuration retained by reference and consulted for each property. */
   options: RenameCodecOptions;
 
+  /** Creates a codec that only uses `@friendlyName` unless a naming hook is supplied. */
   constructor(options: RenameCodecOptions = {}) {
     super();
     this.options = options;
   }
 
+  /**
+   * Clones a model property with a changed language name and preserves its wire
+   * type. A different, nonempty friendly name wins over the naming hook.
+   * Returns `null` for other types or when neither source supplies a changed name.
+   */
   encode($: Typekit, sourceType: Type, referenceTypes: MemberType[]) {
     if (!$.modelProperty.is(sourceType)) {
       return null;
@@ -341,6 +436,12 @@ export class RenameCodec extends Codec {
 }
 
 const jsonCodecRegistryCache = new WeakMap<Program, CodecRegistry>();
+/**
+ * Gets the mutable default registry cached per program. Specific numeric and
+ * date-time codecs precede byte, array, and rename codecs, with identity last.
+ * Appending a codec to this registry cannot override its identity fallback;
+ * supply a separate registry to customize selection priority.
+ */
 export const getJsonCodecRegistry = ($: Typekit) => {
   if (jsonCodecRegistryCache.has($.program)) {
     return jsonCodecRegistryCache.get($.program)!;
 
@@ -64,6 +64,7 @@ export class EnumMemberHttpCanonicalization
     return this.engine.subgraphMatchesPredicate(this, predicate);
   }
 
+  /** Supplies an option-based cache key for an enum member, which needs no encoding codec. */
   static mutationInfo(
     engine: HttpCanonicalizer,
     sourceType: EnumMember,
@@ -79,6 +80,10 @@ export class EnumMemberHttpCanonicalization
     };
   }
 
+  /**
+   * Creates language and wire nodes that preserve the member's name and value.
+   * Enum members are leaves; no child canonicalizations are required.
+   */
   constructor(
     engine: HttpCanonicalizer,
     sourceType: EnumMember,
 
@@ -64,6 +64,7 @@ export class EnumHttpCanonicalization
     return this.engine.subgraphMatchesPredicate(this, predicate);
   }
 
+  /** Supplies the enum's option-based cache key and synthetic trait without selecting a codec. */
   static mutationInfo(
     engine: HttpCanonicalizer,
     sourceType: Enum,
@@ -79,6 +80,10 @@ export class EnumHttpCanonicalization
     };
   }
 
+  /**
+   * Initializes declaration status and projection nodes for the enum.
+   * Use the engine's `canonicalize` method to also traverse and connect its members.
+   */
   constructor(
     engine: HttpCanonicalizer,
     sourceType: Enum,
 
@@ -10,6 +10,10 @@ import { ScalarHttpCanonicalization } from "./scalar.js";
 import { UnionVariantHttpCanonicalization } from "./union-variant.js";
 import { UnionHttpCanonicalization } from "./union.js";
 
+/**
+ * Source-kind dispatch table used by {@link HttpCanonicalizer}. Several source
+ * kinds share the literal canonicalization; node `kind` need not equal source `kind`.
+ */
 export const CANONICALIZATION_CLASSES = {
   Operation: OperationHttpCanonicalization,
   Model: ModelHttpCanonicalization,
@@ -27,8 +31,10 @@ export const CANONICALIZATION_CLASSES = {
   Tuple: LiteralHttpCanonicalization,
 } as const;
 
+/** Instance types keyed by source kind, for the HTTP mutation engine's typed dispatch. */
 export type HttpCanonicalizationMutations = InstancesFor<typeof CANONICALIZATION_CLASSES>;
 
+/** Union of registered HTTP canonicalization nodes; narrow by `kind` to navigate shape-specific data. */
 export type HttpCanonicalization = InstanceType<
   (typeof CANONICALIZATION_CLASSES)[keyof typeof CANONICALIZATION_CLASSES]
 >;