@formspec/build 0.1.0-alpha.27 → 0.1.0-alpha.29

package/dist/index.js

@@ -1,5 +1,314 @@
 // src/canonicalize/chain-dsl-canonicalizer.ts
-import { IR_VERSION } from "@formspec/core/internals";
+import { IR_VERSION, _getFormSpecMetadataPolicy } from "@formspec/core/internals";
+
+// src/metadata/policy.ts
+var NOOP_INFLECT = () => "";
+function normalizePluralization(input) {
+  if (input?.mode === "infer-if-missing") {
+    return {
+      mode: "infer-if-missing",
+      infer: () => "",
+      inflect: input.inflect
+    };
+  }
+  if (input?.mode === "require-explicit") {
+    return {
+      mode: "require-explicit",
+      infer: () => "",
+      inflect: NOOP_INFLECT
+    };
+  }
+  return {
+    mode: "disabled",
+    infer: () => "",
+    inflect: NOOP_INFLECT
+  };
+}
+function normalizeScalarPolicy(input) {
+  if (input?.mode === "infer-if-missing") {
+    return {
+      mode: "infer-if-missing",
+      infer: input.infer,
+      pluralization: normalizePluralization(input.pluralization)
+    };
+  }
+  if (input?.mode === "require-explicit") {
+    return {
+      mode: "require-explicit",
+      infer: () => "",
+      pluralization: normalizePluralization(input.pluralization)
+    };
+  }
+  return {
+    mode: "disabled",
+    infer: () => "",
+    pluralization: normalizePluralization(input?.pluralization)
+  };
+}
+function normalizeDeclarationPolicy(input) {
+  return {
+    apiName: normalizeScalarPolicy(input?.apiName),
+    displayName: normalizeScalarPolicy(input?.displayName)
+  };
+}
+function normalizeMetadataPolicy(input) {
+  return {
+    type: normalizeDeclarationPolicy(input?.type),
+    field: normalizeDeclarationPolicy(input?.field),
+    method: normalizeDeclarationPolicy(input?.method)
+  };
+}
+function getDeclarationMetadataPolicy(policy, declarationKind) {
+  return policy[declarationKind];
+}
+function makeMetadataContext(surface, declarationKind, logicalName, buildContext) {
+  return {
+    surface,
+    declarationKind,
+    logicalName,
+    ...buildContext !== void 0 && { buildContext }
+  };
+}
+
+// src/metadata/resolve.ts
+function toExplicitScalar(value) {
+  return value !== void 0 && value.trim() !== "" ? { value, source: "explicit" } : void 0;
+}
+function toExplicitResolvedMetadata(explicit) {
+  if (explicit === void 0) {
+    return void 0;
+  }
+  const apiName = toExplicitScalar(explicit.apiName);
+  const displayName = toExplicitScalar(explicit.displayName);
+  const apiNamePlural = toExplicitScalar(explicit.apiNamePlural);
+  const displayNamePlural = toExplicitScalar(explicit.displayNamePlural);
+  const metadata = {
+    ...apiName !== void 0 && { apiName },
+    ...displayName !== void 0 && { displayName },
+    ...apiNamePlural !== void 0 && { apiNamePlural },
+    ...displayNamePlural !== void 0 && { displayNamePlural }
+  };
+  return Object.keys(metadata).length > 0 ? metadata : void 0;
+}
+function resolveScalar(current, policy, context, metadataLabel) {
+  if (current !== void 0) {
+    return current;
+  }
+  if (policy.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit ${metadataLabel} for ${context.declarationKind} "${context.logicalName}" on the ${context.surface} surface.`
+    );
+  }
+  if (policy.mode !== "infer-if-missing") {
+    return void 0;
+  }
+  const inferredValue = policy.infer(context);
+  return inferredValue.trim() !== "" ? { value: inferredValue, source: "inferred" } : void 0;
+}
+function resolvePlural(current, singular, policy, context, metadataLabel) {
+  if (current !== void 0) {
+    return current;
+  }
+  if (policy.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit ${metadataLabel} for ${context.declarationKind} "${context.logicalName}" on the ${context.surface} surface.`
+    );
+  }
+  if (singular === void 0 || policy.mode !== "infer-if-missing") {
+    return void 0;
+  }
+  const pluralValue = policy.inflect({ ...context, singular: singular.value });
+  return pluralValue.trim() !== "" ? { value: pluralValue, source: "inferred" } : void 0;
+}
+function resolveResolvedMetadata(current, policy, context) {
+  const apiName = resolveScalar(current?.apiName, policy.apiName, context, "apiName");
+  const displayName = resolveScalar(
+    current?.displayName,
+    policy.displayName,
+    context,
+    "displayName"
+  );
+  const apiNamePlural = resolvePlural(
+    current?.apiNamePlural,
+    apiName,
+    policy.apiName.pluralization,
+    context,
+    "apiNamePlural"
+  );
+  const displayNamePlural = resolvePlural(
+    current?.displayNamePlural,
+    displayName,
+    policy.displayName.pluralization,
+    context,
+    "displayNamePlural"
+  );
+  if (apiName === void 0 && displayName === void 0 && apiNamePlural === void 0 && displayNamePlural === void 0) {
+    return void 0;
+  }
+  return {
+    ...apiName !== void 0 && { apiName },
+    ...displayName !== void 0 && { displayName },
+    ...apiNamePlural !== void 0 && { apiNamePlural },
+    ...displayNamePlural !== void 0 && { displayNamePlural }
+  };
+}
+function pickResolvedMetadataValue(baseValue, overlayValue) {
+  if (overlayValue?.source === "explicit") {
+    return overlayValue;
+  }
+  if (baseValue?.source === "explicit") {
+    return baseValue;
+  }
+  return baseValue ?? overlayValue;
+}
+function resolveTypeNodeMetadata(type, options) {
+  switch (type.kind) {
+    case "array":
+      return {
+        ...type,
+        items: resolveTypeNodeMetadata(type.items, options)
+      };
+    case "object":
+      return {
+        ...type,
+        properties: type.properties.map((property) => resolveObjectPropertyMetadata(property, options))
+      };
+    case "record":
+      return {
+        ...type,
+        valueType: resolveTypeNodeMetadata(type.valueType, options)
+      };
+    case "union":
+      return {
+        ...type,
+        members: type.members.map((member) => resolveTypeNodeMetadata(member, options))
+      };
+    case "reference":
+    case "primitive":
+    case "enum":
+    case "dynamic":
+    case "custom":
+      return type;
+    default: {
+      const _exhaustive = type;
+      return _exhaustive;
+    }
+  }
+}
+function resolveObjectPropertyMetadata(property, options) {
+  const metadata = resolveResolvedMetadata(property.metadata, options.policy.field, {
+    surface: options.surface,
+    declarationKind: "field",
+    logicalName: property.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...property,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(property.type, options)
+  };
+}
+function resolveFieldMetadataNode(field, options) {
+  const metadata = resolveResolvedMetadata(field.metadata, options.policy.field, {
+    surface: options.surface,
+    declarationKind: "field",
+    logicalName: field.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...field,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(field.type, options)
+  };
+}
+function resolveFormElementMetadata(element, options) {
+  switch (element.kind) {
+    case "field":
+      return resolveFieldMetadataNode(element, options);
+    case "group":
+      return {
+        ...element,
+        elements: element.elements.map((child) => resolveFormElementMetadata(child, options))
+      };
+    case "conditional":
+      return {
+        ...element,
+        elements: element.elements.map((child) => resolveFormElementMetadata(child, options))
+      };
+    default: {
+      const _exhaustive = element;
+      return _exhaustive;
+    }
+  }
+}
+function resolveTypeDefinitionMetadata(typeDefinition, options) {
+  const metadata = resolveResolvedMetadata(typeDefinition.metadata, options.policy.type, {
+    surface: options.surface,
+    declarationKind: "type",
+    logicalName: typeDefinition.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...typeDefinition,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(typeDefinition.type, options)
+  };
+}
+function resolveMetadata(explicit, policy, context) {
+  return resolveResolvedMetadata(toExplicitResolvedMetadata(explicit), policy, context);
+}
+function mergeResolvedMetadata(baseMetadata, overlayMetadata) {
+  const apiName = pickResolvedMetadataValue(baseMetadata?.apiName, overlayMetadata?.apiName);
+  const displayName = pickResolvedMetadataValue(
+    baseMetadata?.displayName,
+    overlayMetadata?.displayName
+  );
+  const apiNamePlural = pickResolvedMetadataValue(
+    baseMetadata?.apiNamePlural,
+    overlayMetadata?.apiNamePlural
+  );
+  const displayNamePlural = pickResolvedMetadataValue(
+    baseMetadata?.displayNamePlural,
+    overlayMetadata?.displayNamePlural
+  );
+  if (apiName === void 0 && displayName === void 0 && apiNamePlural === void 0 && displayNamePlural === void 0) {
+    return void 0;
+  }
+  return {
+    ...apiName !== void 0 && { apiName },
+    ...displayName !== void 0 && { displayName },
+    ...apiNamePlural !== void 0 && { apiNamePlural },
+    ...displayNamePlural !== void 0 && { displayNamePlural }
+  };
+}
+function getSerializedName(logicalName, metadata) {
+  return metadata?.apiName?.value ?? logicalName;
+}
+function getDisplayName(metadata) {
+  return metadata?.displayName?.value;
+}
+function resolveFormIRMetadata(ir, options) {
+  const rootLogicalName = options.rootLogicalName ?? ir.name ?? "FormSpec";
+  const metadata = resolveResolvedMetadata(ir.metadata, options.policy.type, {
+    surface: options.surface,
+    declarationKind: "type",
+    logicalName: rootLogicalName,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...ir,
+    ...metadata !== void 0 && { metadata },
+    elements: ir.elements.map((element) => resolveFormElementMetadata(element, options)),
+    typeRegistry: Object.fromEntries(
+      Object.entries(ir.typeRegistry).map(([name, definition]) => [
+        name,
+        resolveTypeDefinitionMetadata(definition, options)
+      ])
+    )
+  };
+}
+
+// src/canonicalize/chain-dsl-canonicalizer.ts
 var CHAIN_DSL_PROVENANCE = {
   surface: "chain-dsl",
   file: "",
@@ -15,57 +324,60 @@ function isConditional(el) {
 function isField(el) {
   return el._type === "field";
 }
-function canonicalizeChainDSL(form) {
+function canonicalizeChainDSL(form, options) {
+  const metadataPolicy = normalizeMetadataPolicy(
+    options?.metadata ?? _getFormSpecMetadataPolicy(form)
+  );
   return {
     kind: "form-ir",
     irVersion: IR_VERSION,
-    elements: canonicalizeElements(form.elements),
+    elements: canonicalizeElements(form.elements, metadataPolicy),
     rootAnnotations: [],
     typeRegistry: {},
     provenance: CHAIN_DSL_PROVENANCE
   };
 }
-function canonicalizeElements(elements) {
-  return elements.map(canonicalizeElement);
+function canonicalizeElements(elements, metadataPolicy) {
+  return elements.map((element) => canonicalizeElement(element, metadataPolicy));
 }
-function canonicalizeElement(element) {
+function canonicalizeElement(element, metadataPolicy) {
   if (isField(element)) {
-    return canonicalizeField(element);
+    return canonicalizeField(element, metadataPolicy);
   }
   if (isGroup(element)) {
-    return canonicalizeGroup(element);
+    return canonicalizeGroup(element, metadataPolicy);
   }
   if (isConditional(element)) {
-    return canonicalizeConditional(element);
+    return canonicalizeConditional(element, metadataPolicy);
   }
   const _exhaustive = element;
   throw new Error(`Unknown element type: ${JSON.stringify(_exhaustive)}`);
 }
-function canonicalizeField(field) {
+function canonicalizeField(field, metadataPolicy) {
   switch (field._field) {
     case "text":
-      return canonicalizeTextField(field);
+      return canonicalizeTextField(field, metadataPolicy);
     case "number":
-      return canonicalizeNumberField(field);
+      return canonicalizeNumberField(field, metadataPolicy);
     case "boolean":
-      return canonicalizeBooleanField(field);
+      return canonicalizeBooleanField(field, metadataPolicy);
     case "enum":
-      return canonicalizeStaticEnumField(field);
+      return canonicalizeStaticEnumField(field, metadataPolicy);
     case "dynamic_enum":
-      return canonicalizeDynamicEnumField(field);
+      return canonicalizeDynamicEnumField(field, metadataPolicy);
     case "dynamic_schema":
-      return canonicalizeDynamicSchemaField(field);
+      return canonicalizeDynamicSchemaField(field, metadataPolicy);
     case "array":
-      return canonicalizeArrayField(field);
+      return canonicalizeArrayField(field, metadataPolicy);
     case "object":
-      return canonicalizeObjectField(field);
+      return canonicalizeObjectField(field, metadataPolicy);
     default: {
       const _exhaustive = field;
       throw new Error(`Unknown field type: ${JSON.stringify(_exhaustive)}`);
     }
   }
 }
-function canonicalizeTextField(field) {
+function canonicalizeTextField(field, metadataPolicy) {
   const type = { kind: "primitive", primitiveKind: "string" };
   const constraints = [];
   if (field.minLength !== void 0) {
@@ -97,13 +409,14 @@ function canonicalizeTextField(field) {
   }
   return buildFieldNode(
     field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
     type,
     field.required,
-    buildAnnotations(field.label, field.placeholder),
+    buildAnnotations(getExplicitDisplayName(field), field.placeholder),
     constraints
   );
 }
-function canonicalizeNumberField(field) {
+function canonicalizeNumberField(field, metadataPolicy) {
   const type = { kind: "primitive", primitiveKind: "number" };
   const constraints = [];
   if (field.min !== void 0) {
@@ -135,17 +448,24 @@ function canonicalizeNumberField(field) {
   }
   return buildFieldNode(
     field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
     type,
     field.required,
-    buildAnnotations(field.label),
+    buildAnnotations(getExplicitDisplayName(field)),
     constraints
   );
 }
-function canonicalizeBooleanField(field) {
+function canonicalizeBooleanField(field, metadataPolicy) {
   const type = { kind: "primitive", primitiveKind: "boolean" };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeStaticEnumField(field) {
+function canonicalizeStaticEnumField(field, metadataPolicy) {
   const members = field.options.map((opt) => {
     if (typeof opt === "string") {
       return { value: opt };
@@ -153,28 +473,46 @@ function canonicalizeStaticEnumField(field) {
     return { value: opt.id, displayName: opt.label };
   });
   const type = { kind: "enum", members };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeDynamicEnumField(field) {
+function canonicalizeDynamicEnumField(field, metadataPolicy) {
   const type = {
     kind: "dynamic",
     dynamicKind: "enum",
     sourceKey: field.source,
     parameterFields: field.params ? [...field.params] : []
   };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeDynamicSchemaField(field) {
+function canonicalizeDynamicSchemaField(field, metadataPolicy) {
   const type = {
     kind: "dynamic",
     dynamicKind: "schema",
     sourceKey: field.schemaSource,
     parameterFields: []
   };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeArrayField(field) {
-  const itemProperties = buildObjectProperties(field.items);
+function canonicalizeArrayField(field, metadataPolicy) {
+  const itemProperties = buildObjectProperties(field.items, metadataPolicy);
   const itemsType = {
     kind: "object",
     properties: itemProperties,
@@ -202,37 +540,44 @@ function canonicalizeArrayField(field) {
   }
   return buildFieldNode(
     field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
     type,
     field.required,
-    buildAnnotations(field.label),
+    buildAnnotations(getExplicitDisplayName(field)),
     constraints
   );
 }
-function canonicalizeObjectField(field) {
-  const properties = buildObjectProperties(field.properties);
+function canonicalizeObjectField(field, metadataPolicy) {
+  const properties = buildObjectProperties(field.properties, metadataPolicy);
   const type = {
     kind: "object",
     properties,
     additionalProperties: true
   };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeGroup(g) {
+function canonicalizeGroup(g, metadataPolicy) {
   return {
     kind: "group",
     label: g.label,
-    elements: canonicalizeElements(g.elements),
+    elements: canonicalizeElements(g.elements, metadataPolicy),
     provenance: CHAIN_DSL_PROVENANCE
   };
 }
-function canonicalizeConditional(c) {
+function canonicalizeConditional(c, metadataPolicy) {
   return {
     kind: "conditional",
     fieldName: c.field,
     // Conditional values from the chain DSL are JSON-serializable primitives
     // (strings, numbers, booleans) produced by the `is()` predicate helper.
     value: assertJsonValue(c.value),
-    elements: canonicalizeElements(c.elements),
+    elements: canonicalizeElements(c.elements, metadataPolicy),
     provenance: CHAIN_DSL_PROVENANCE
   };
 }
@@ -252,10 +597,11 @@ function assertJsonValue(v) {
   }
   throw new TypeError(`Conditional value is not a valid JsonValue: ${typeof v}`);
 }
-function buildFieldNode(name, type, required, annotations, constraints = []) {
+function buildFieldNode(name, metadata, type, required, annotations, constraints = []) {
   return {
     kind: "field",
     name,
+    ...metadata !== void 0 && { metadata },
     type,
     required: required === true,
     constraints,
@@ -285,13 +631,14 @@ function buildAnnotations(label, placeholder) {
   }
   return annotations;
 }
-function buildObjectProperties(elements, insideConditional = false) {
+function buildObjectProperties(elements, metadataPolicy, insideConditional = false) {
   const properties = [];
   for (const el of elements) {
     if (isField(el)) {
-      const fieldNode = canonicalizeField(el);
+      const fieldNode = canonicalizeField(el, metadataPolicy);
       properties.push({
         name: fieldNode.name,
+        ...fieldNode.metadata !== void 0 && { metadata: fieldNode.metadata },
         type: fieldNode.type,
         // Fields inside a conditional branch are always optional in the
         // data schema, regardless of their `required` flag — the condition
@@ -302,17 +649,34 @@ function buildObjectProperties(elements, insideConditional = false) {
         provenance: CHAIN_DSL_PROVENANCE
       });
     } else if (isGroup(el)) {
-      properties.push(...buildObjectProperties(el.elements, insideConditional));
+      properties.push(...buildObjectProperties(el.elements, metadataPolicy, insideConditional));
     } else if (isConditional(el)) {
-      properties.push(...buildObjectProperties(el.elements, true));
+      properties.push(...buildObjectProperties(el.elements, metadataPolicy, true));
     }
   }
   return properties;
 }
+function getExplicitDisplayName(field) {
+  if (field.label !== void 0 && field.displayName !== void 0) {
+    throw new Error('Chain DSL fields cannot specify both "label" and "displayName".');
+  }
+  return field.displayName ?? field.label;
+}
+function resolveFieldMetadata(logicalName, field, metadataPolicy) {
+  const displayName = getExplicitDisplayName(field);
+  return resolveMetadata(
+    {
+      ...field.apiName !== void 0 && { apiName: field.apiName },
+      ...displayName !== void 0 && { displayName }
+    },
+    getDeclarationMetadataPolicy(metadataPolicy, "field"),
+    makeMetadataContext("chain-dsl", "field", logicalName)
+  );
+}
 
 // src/canonicalize/tsdoc-canonicalizer.ts
 import { IR_VERSION as IR_VERSION2 } from "@formspec/core/internals";
-function canonicalizeTSDoc(analysis, source) {
+function canonicalizeTSDoc(analysis, source, options) {
   const file = source?.file ?? "";
   const provenance = {
     surface: "tsdoc",
@@ -321,15 +685,21 @@ function canonicalizeTSDoc(analysis, source) {
     column: 0
   };
   const elements = assembleElements(analysis.fields, analysis.fieldLayouts, provenance);
-  return {
+  const ir = {
     kind: "form-ir",
+    name: analysis.name,
     irVersion: IR_VERSION2,
     elements,
+    ...analysis.metadata !== void 0 && { metadata: analysis.metadata },
     typeRegistry: analysis.typeRegistry,
     ...analysis.annotations !== void 0 && analysis.annotations.length > 0 && { rootAnnotations: analysis.annotations },
     ...analysis.annotations !== void 0 && analysis.annotations.length > 0 && { annotations: analysis.annotations },
     provenance
   };
+  return resolveFormIRMetadata(ir, {
+    policy: normalizeMetadataPolicy(options?.metadata),
+    surface: "tsdoc"
+  });
 }
 function assembleElements(fields, layouts, provenance) {
   const elements = [];
@@ -386,6 +756,120 @@ function wrapInConditional(field, layout, provenance) {
   return conditional;
 }
 
+// src/metadata/collision-guards.ts
+function assertUniqueSerializedNames(entries, scope) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const previous = seen.get(entry.serializedName);
+    if (previous !== void 0) {
+      if (previous.logicalName === entry.logicalName && previous.category === entry.category) {
+        continue;
+      }
+      throw new Error(
+        `Serialized name collision in ${scope}: ${previous.category} "${previous.logicalName}" and ${entry.category} "${entry.logicalName}" both resolve to "${entry.serializedName}".`
+      );
+    }
+    seen.set(entry.serializedName, entry);
+  }
+}
+function collectFlattenedFields(elements) {
+  const fields = [];
+  for (const element of elements) {
+    switch (element.kind) {
+      case "field":
+        fields.push(element);
+        break;
+      case "group":
+      case "conditional":
+        fields.push(...collectFlattenedFields(element.elements));
+        break;
+      default: {
+        const exhaustive = element;
+        void exhaustive;
+      }
+    }
+  }
+  return fields;
+}
+function validateObjectProperties(properties, scope) {
+  assertUniqueSerializedNames(
+    properties.map((property) => ({
+      logicalName: property.name,
+      serializedName: getSerializedName(property.name, property.metadata),
+      category: "object property"
+    })),
+    scope
+  );
+  for (const property of properties) {
+    validateTypeNode(
+      property.type,
+      `${scope}.${getSerializedName(property.name, property.metadata)}`
+    );
+  }
+}
+function validateTypeNode(type, scope) {
+  switch (type.kind) {
+    case "array":
+      validateTypeNode(type.items, `${scope}[]`);
+      break;
+    case "object":
+      validateObjectProperties(type.properties, scope);
+      break;
+    case "record":
+      validateTypeNode(type.valueType, `${scope}.*`);
+      break;
+    case "union":
+      type.members.forEach((member, index) => {
+        validateTypeNode(member, `${scope}|${String(index)}`);
+      });
+      break;
+    case "reference":
+    case "primitive":
+    case "enum":
+    case "dynamic":
+    case "custom":
+      break;
+    default: {
+      const exhaustive = type;
+      void exhaustive;
+    }
+  }
+}
+function validateTypeDefinitions(typeRegistry) {
+  const definitions = Object.values(typeRegistry);
+  assertUniqueSerializedNames(
+    definitions.map((definition) => ({
+      logicalName: definition.name,
+      serializedName: getSerializedName(definition.name, definition.metadata),
+      category: "type definition"
+    })),
+    "$defs"
+  );
+  for (const definition of definitions) {
+    validateTypeDefinition(definition);
+  }
+}
+function validateTypeDefinition(definition) {
+  validateTypeNode(
+    definition.type,
+    `type "${getSerializedName(definition.name, definition.metadata)}"`
+  );
+}
+function assertNoSerializedNameCollisions(ir) {
+  assertUniqueSerializedNames(
+    collectFlattenedFields(ir.elements).map((field) => ({
+      logicalName: field.name,
+      serializedName: getSerializedName(field.name, field.metadata),
+      category: "field"
+    })),
+    "form root"
+  );
+  for (const field of collectFlattenedFields(ir.elements)) {
+    validateTypeNode(field.type, `field "${getSerializedName(field.name, field.metadata)}"`);
+  }
+  validateTypeDefinitions(ir.typeRegistry);
+}
+
 // src/json-schema/ir-generator.ts
 function makeContext(options) {
   const vendorPrefix = options?.vendorPrefix ?? "x-formspec";
@@ -396,19 +880,33 @@ function makeContext(options) {
   }
   return {
     defs: {},
+    typeNameMap: {},
+    typeRegistry: {},
     extensionRegistry: options?.extensionRegistry,
     vendorPrefix
   };
 }
 function generateJsonSchemaFromIR(ir, options) {
-  const ctx = makeContext(options);
+  assertNoSerializedNameCollisions(ir);
+  const ctx = {
+    ...makeContext(options),
+    typeRegistry: ir.typeRegistry,
+    typeNameMap: Object.fromEntries(
+      Object.entries(ir.typeRegistry).map(([name, typeDef]) => [
+        name,
+        getSerializedName(name, typeDef.metadata)
+      ])
+    )
+  };
   for (const [name, typeDef] of Object.entries(ir.typeRegistry)) {
-    ctx.defs[name] = generateTypeNode(typeDef.type, ctx);
+    const schemaName = ctx.typeNameMap[name] ?? name;
+    ctx.defs[schemaName] = generateTypeNode(typeDef.type, ctx);
+    applyResolvedMetadata(ctx.defs[schemaName], typeDef.metadata);
     if (typeDef.constraints && typeDef.constraints.length > 0) {
-      applyConstraints(ctx.defs[name], typeDef.constraints, ctx);
+      applyConstraints(ctx.defs[schemaName], typeDef.constraints, ctx);
     }
     if (typeDef.annotations && typeDef.annotations.length > 0) {
-      applyAnnotations(ctx.defs[name], typeDef.annotations, ctx);
+      applyAnnotations(ctx.defs[schemaName], typeDef.annotations, ctx);
     }
   }
   const properties = {};
@@ -421,6 +919,7 @@ function generateJsonSchemaFromIR(ir, options) {
     properties,
     ...uniqueRequired.length > 0 && { required: uniqueRequired }
   };
+  applyResolvedMetadata(result, ir.metadata);
   if (ir.annotations && ir.annotations.length > 0) {
     applyAnnotations(result, ir.annotations, ctx);
   }
@@ -433,9 +932,9 @@ function collectFields(elements, properties, required, ctx) {
   for (const element of elements) {
     switch (element.kind) {
       case "field":
-        properties[element.name] = generateFieldSchema(element, ctx);
+        properties[getSerializedName(element.name, element.metadata)] = generateFieldSchema(element, ctx);
         if (element.required) {
-          required.push(element.name);
+          required.push(getSerializedName(element.name, element.metadata));
         }
         break;
       case "group":
@@ -479,6 +978,7 @@ function generateFieldSchema(field, ctx) {
       rootAnnotations.push(annotation);
     }
   }
+  applyResolvedMetadata(schema, field.metadata);
   applyAnnotations(schema, rootAnnotations, ctx);
   if (itemStringSchema !== void 0) {
     applyAnnotations(itemStringSchema, itemAnnotations, ctx);
@@ -486,7 +986,7 @@ function generateFieldSchema(field, ctx) {
   if (pathConstraints.length === 0) {
     return schema;
   }
-  return applyPathTargetedConstraints(schema, pathConstraints, ctx);
+  return applyPathTargetedConstraints(schema, pathConstraints, ctx, field.type);
 }
 function isStringItemConstraint(constraint) {
   switch (constraint.constraintKind) {
@@ -498,9 +998,11 @@ function isStringItemConstraint(constraint) {
       return false;
   }
 }
-function applyPathTargetedConstraints(schema, pathConstraints, ctx) {
+function applyPathTargetedConstraints(schema, pathConstraints, ctx, typeNode) {
   if (schema.type === "array" && schema.items) {
-    schema.items = applyPathTargetedConstraints(schema.items, pathConstraints, ctx);
+    const referencedType = typeNode?.kind === "reference" ? resolveReferencedType(typeNode, ctx) : void 0;
+    const nestedType = typeNode?.kind === "array" ? typeNode.items : referencedType?.kind === "array" ? referencedType.items : void 0;
+    schema.items = applyPathTargetedConstraints(schema.items, pathConstraints, ctx, nestedType);
     return schema;
   }
   const byTarget = /* @__PURE__ */ new Map();
@@ -515,7 +1017,7 @@ function applyPathTargetedConstraints(schema, pathConstraints, ctx) {
   for (const [target, constraints] of byTarget) {
     const subSchema = {};
     applyConstraints(subSchema, constraints, ctx);
-    propertyOverrides[target] = subSchema;
+    propertyOverrides[resolveSerializedPropertyName(target, typeNode, ctx)] = subSchema;
   }
   if (schema.$ref) {
     const { $ref, ...rest } = schema;
@@ -563,7 +1065,7 @@ function generateTypeNode(type, ctx) {
     case "union":
       return generateUnionType(type, ctx);
     case "reference":
-      return generateReferenceType(type);
+      return generateReferenceType(type, ctx);
     case "dynamic":
       return generateDynamicType(type);
     case "custom":
@@ -604,9 +1106,10 @@ function generateObjectType(type, ctx) {
   const properties = {};
   const required = [];
   for (const prop of type.properties) {
-    properties[prop.name] = generatePropertySchema(prop, ctx);
+    const propertyName = getSerializedName(prop.name, prop.metadata);
+    properties[propertyName] = generatePropertySchema(prop, ctx);
     if (!prop.optional) {
-      required.push(prop.name);
+      required.push(propertyName);
     }
   }
   const schema = { type: "object", properties };
@@ -627,6 +1130,7 @@ function generateRecordType(type, ctx) {
 function generatePropertySchema(prop, ctx) {
   const schema = generateTypeNode(prop.type, ctx);
   applyConstraints(schema, prop.constraints, ctx);
+  applyResolvedMetadata(schema, prop.metadata);
   applyAnnotations(schema, prop.annotations, ctx);
   return schema;
 }
@@ -655,8 +1159,28 @@ function isNullableUnion(type) {
   ).length;
   return nullCount === 1;
 }
-function generateReferenceType(type) {
-  return { $ref: `#/$defs/${type.name}` };
+function generateReferenceType(type, ctx) {
+  return { $ref: `#/$defs/${ctx.typeNameMap[type.name] ?? type.name}` };
+}
+function applyResolvedMetadata(schema, metadata) {
+  const displayName = getDisplayName(metadata);
+  if (displayName !== void 0) {
+    schema.title = displayName;
+  }
+}
+function resolveReferencedType(type, ctx) {
+  return ctx.typeRegistry[type.name]?.type;
+}
+function resolveSerializedPropertyName(logicalName, typeNode, ctx) {
+  if (typeNode?.kind === "object") {
+    const property = typeNode.properties.find((candidate) => candidate.name === logicalName);
+    return property === void 0 ? logicalName : getSerializedName(property.name, property.metadata);
+  }
+  if (typeNode?.kind === "reference") {
+    const referencedType = resolveReferencedType(typeNode, ctx);
+    return referencedType === void 0 ? logicalName : resolveSerializedPropertyName(logicalName, referencedType, ctx);
+  }
+  return logicalName;
 }
 function generateDynamicType(type) {
   if (type.dynamicKind === "enum") {
@@ -736,7 +1260,7 @@ function applyAnnotations(schema, annotations, ctx) {
   for (const annotation of annotations) {
     switch (annotation.annotationKind) {
       case "displayName":
-        schema.title = annotation.value;
+        schema.title ??= annotation.value;
         break;
       case "description":
         schema.description = annotation.value;
@@ -823,7 +1347,10 @@ function assignVendorPrefixedExtensionKeywords(schema, extensionSchema, vendorPr
 
 // src/json-schema/generator.ts
 function generateJsonSchema(form, options) {
-  const ir = canonicalizeChainDSL(form);
+  const ir = canonicalizeChainDSL(
+    form,
+    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+  );
   const internalOptions = options?.vendorPrefix === void 0 ? void 0 : { vendorPrefix: options.vendorPrefix };
   return generateJsonSchemaFromIR(ir, internalOptions);
 }
@@ -993,13 +1520,21 @@ function combineRules(parentRule, childRule) {
     }
   };
 }
-function fieldNodeToControl(field, parentRule) {
-  const displayNameAnnotation = field.annotations.find((a) => a.annotationKind === "displayName");
+function getFieldDisplayName(field) {
+  const resolvedDisplayName = getDisplayName(field.metadata);
+  if (resolvedDisplayName !== void 0) {
+    return resolvedDisplayName;
+  }
+  return field.annotations.find((annotation) => annotation.annotationKind === "displayName")?.value;
+}
+function fieldNodeToControl(field, fieldNameMap, parentRule) {
   const placeholderAnnotation = field.annotations.find((a) => a.annotationKind === "placeholder");
+  const serializedName = fieldNameMap.get(field.name) ?? getSerializedName(field.name, field.metadata);
+  const displayName = getFieldDisplayName(field);
   const control = {
     type: "Control",
-    scope: fieldToScope(field.name),
-    ...displayNameAnnotation !== void 0 && { label: displayNameAnnotation.value },
+    scope: fieldToScope(serializedName),
+    ...displayName !== void 0 && { label: displayName },
     ...placeholderAnnotation !== void 0 && {
       options: { placeholder: placeholderAnnotation.value }
     },
@@ -1007,30 +1542,30 @@ function fieldNodeToControl(field, parentRule) {
   };
   return control;
 }
-function groupNodeToLayout(group, parentRule) {
+function groupNodeToLayout(group, fieldNameMap, parentRule) {
   return {
     type: "Group",
     label: group.label,
-    elements: irElementsToUiSchema(group.elements, parentRule),
+    elements: irElementsToUiSchema(group.elements, fieldNameMap, parentRule),
     ...parentRule !== void 0 && { rule: parentRule }
   };
 }
-function irElementsToUiSchema(elements, parentRule) {
+function irElementsToUiSchema(elements, fieldNameMap, parentRule) {
   const result = [];
   for (const element of elements) {
     switch (element.kind) {
       case "field": {
-        result.push(fieldNodeToControl(element, parentRule));
+        result.push(fieldNodeToControl(element, fieldNameMap, parentRule));
         break;
       }
       case "group": {
-        result.push(groupNodeToLayout(element, parentRule));
+        result.push(groupNodeToLayout(element, fieldNameMap, parentRule));
         break;
       }
       case "conditional": {
-        const newRule = createShowRule(element.fieldName, element.value);
+        const newRule = createShowRule(fieldNameMap.get(element.fieldName) ?? element.fieldName, element.value);
         const combinedRule = parentRule !== void 0 ? combineRules(parentRule, newRule) : newRule;
-        const childElements = irElementsToUiSchema(element.elements, combinedRule);
+        const childElements = irElementsToUiSchema(element.elements, fieldNameMap, combinedRule);
         result.push(...childElements);
         break;
       }
@@ -1044,16 +1579,42 @@ function irElementsToUiSchema(elements, parentRule) {
   return result;
 }
 function generateUiSchemaFromIR(ir) {
+  assertNoSerializedNameCollisions(ir);
+  const fieldNameMap = collectFieldNameMap(ir.elements);
   const result = {
     type: "VerticalLayout",
-    elements: irElementsToUiSchema(ir.elements)
+    elements: irElementsToUiSchema(ir.elements, fieldNameMap)
   };
   return parseOrThrow(uiSchema, result, "UI Schema");
 }
+function collectFieldNameMap(elements) {
+  const map = /* @__PURE__ */ new Map();
+  for (const element of elements) {
+    switch (element.kind) {
+      case "field":
+        map.set(element.name, getSerializedName(element.name, element.metadata));
+        break;
+      case "group":
+      case "conditional":
+        for (const [key, value] of collectFieldNameMap(element.elements)) {
+          map.set(key, value);
+        }
+        break;
+      default: {
+        const _exhaustive = element;
+        void _exhaustive;
+      }
+    }
+  }
+  return map;
+}
 
 // src/ui-schema/generator.ts
-function generateUiSchema(form) {
-  const ir = canonicalizeChainDSL(form);
+function generateUiSchema(form, options) {
+  const ir = canonicalizeChainDSL(
+    form,
+    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+  );
   return generateUiSchemaFromIR(ir);
 }
 
@@ -1212,6 +1773,9 @@ import * as path from "path";
 
 // src/analyzer/class-analyzer.ts
 import * as ts3 from "typescript";
+import {
+  parseCommentBlock as parseCommentBlock2
+} from "@formspec/analysis/internal";
 
 // src/analyzer/jsdoc-constraints.ts
 import * as ts2 from "typescript";
@@ -2114,7 +2678,76 @@ function makeParseOptions(extensionRegistry, fieldType, checker, subjectType, ho
     ...hostType !== void 0 && { hostType }
   };
 }
-function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
+function makeExplicitScalarMetadata(value) {
+  return value === void 0 || value === "" ? void 0 : { value, source: "explicit" };
+}
+function extractExplicitMetadata(node) {
+  let apiName;
+  let displayName;
+  let apiNamePlural;
+  let displayNamePlural;
+  for (const tag of getLeadingParsedTags(node)) {
+    const value = tag.argumentText.trim();
+    if (value === "") {
+      continue;
+    }
+    if (tag.normalizedTagName === "apiName") {
+      if (tag.target === null) {
+        apiName ??= value;
+      } else if (tag.target.kind === "variant") {
+        if (tag.target.rawText === "singular") {
+          apiName ??= value;
+        } else if (tag.target.rawText === "plural") {
+          apiNamePlural ??= value;
+        }
+      }
+      continue;
+    }
+    if (tag.normalizedTagName === "displayName") {
+      if (tag.target === null) {
+        displayName ??= value;
+      } else if (tag.target.kind === "variant") {
+        if (tag.target.rawText === "singular") {
+          displayName ??= value;
+        } else if (tag.target.rawText === "plural") {
+          displayNamePlural ??= value;
+        }
+      }
+    }
+  }
+  const resolvedApiName = makeExplicitScalarMetadata(apiName);
+  const resolvedDisplayName = makeExplicitScalarMetadata(displayName);
+  const resolvedApiNamePlural = makeExplicitScalarMetadata(apiNamePlural);
+  const resolvedDisplayNamePlural = makeExplicitScalarMetadata(displayNamePlural);
+  const metadata = {
+    ...resolvedApiName !== void 0 && { apiName: resolvedApiName },
+    ...resolvedDisplayName !== void 0 && { displayName: resolvedDisplayName },
+    ...resolvedApiNamePlural !== void 0 && { apiNamePlural: resolvedApiNamePlural },
+    ...resolvedDisplayNamePlural !== void 0 && {
+      displayNamePlural: resolvedDisplayNamePlural
+    }
+  };
+  return Object.keys(metadata).length === 0 ? void 0 : metadata;
+}
+function resolveNodeMetadata(metadataPolicy, declarationKind, logicalName, node, buildContext) {
+  const explicit = extractExplicitMetadata(node);
+  return resolveMetadata(
+    {
+      ...explicit?.apiName !== void 0 && { apiName: explicit.apiName.value },
+      ...explicit?.displayName !== void 0 && { displayName: explicit.displayName.value },
+      ...explicit?.apiNamePlural !== void 0 && {
+        apiNamePlural: explicit.apiNamePlural.value
+      },
+      ...explicit?.displayNamePlural !== void 0 && {
+        displayNamePlural: explicit.displayNamePlural.value
+      }
+    },
+    getDeclarationMetadataPolicy(metadataPolicy, declarationKind),
+    makeMetadataContext("tsdoc", declarationKind, logicalName, buildContext)
+  );
+}
+function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry, metadataPolicy) {
+  const normalizedMetadataPolicy = normalizeMetadataPolicy(metadataPolicy);
   const name = classDecl.name?.text ?? "AnonymousClass";
   const fields = [];
   const fieldLayouts = [];
@@ -2141,6 +2774,7 @@ function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
         visiting,
         diagnostics,
         classType,
+        normalizedMetadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
@@ -2159,9 +2793,25 @@ function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
       }
     }
   }
+  const specializedFields = applyDeclarationDiscriminatorToFields(
+    fields,
+    classDecl,
+    classType,
+    checker,
+    file,
+    diagnostics,
+    normalizedMetadataPolicy
+  );
+  const metadata = resolveNodeMetadata(normalizedMetadataPolicy, "type", name, classDecl, {
+    checker,
+    declaration: classDecl,
+    subjectType: classType,
+    hostType: classType
+  });
   return {
     name,
-    fields,
+    ...metadata !== void 0 && { metadata },
+    fields: specializedFields,
     fieldLayouts,
     typeRegistry,
     ...annotations.length > 0 && { annotations },
@@ -2170,7 +2820,8 @@ function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
     staticMethods
   };
 }
-function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegistry) {
+function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegistry, metadataPolicy) {
+  const normalizedMetadataPolicy = normalizeMetadataPolicy(metadataPolicy);
   const name = interfaceDecl.name.text;
   const fields = [];
   const typeRegistry = {};
@@ -2194,6 +2845,7 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegist
         visiting,
         diagnostics,
         interfaceType,
+        normalizedMetadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
@@ -2201,10 +2853,26 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegist
       }
     }
   }
-  const fieldLayouts = fields.map(() => ({}));
+  const specializedFields = applyDeclarationDiscriminatorToFields(
+    fields,
+    interfaceDecl,
+    interfaceType,
+    checker,
+    file,
+    diagnostics,
+    normalizedMetadataPolicy
+  );
+  const fieldLayouts = specializedFields.map(() => ({}));
+  const metadata = resolveNodeMetadata(normalizedMetadataPolicy, "type", name, interfaceDecl, {
+    checker,
+    declaration: interfaceDecl,
+    subjectType: interfaceType,
+    hostType: interfaceType
+  });
   return {
     name,
-    fields,
+    ...metadata !== void 0 && { metadata },
+    fields: specializedFields,
     fieldLayouts,
     typeRegistry,
     ...annotations.length > 0 && { annotations },
@@ -2213,7 +2881,7 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegist
     staticMethods: []
   };
 }
-function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry) {
+function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry, metadataPolicy) {
   if (!ts3.isTypeLiteralNode(typeAlias.type)) {
     const sourceFile = typeAlias.getSourceFile();
     const { line } = sourceFile.getLineAndCharacterOfPosition(typeAlias.getStart());
@@ -2223,6 +2891,8 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
       error: `Type alias "${typeAlias.name.text}" at line ${String(line + 1)} is not an object type literal (found ${kindDesc})`
     };
   }
+  const typeLiteral = typeAlias.type;
+  const normalizedMetadataPolicy = normalizeMetadataPolicy(metadataPolicy);
   const name = typeAlias.name.text;
   const fields = [];
   const typeRegistry = {};
@@ -2236,7 +2906,7 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
   const annotations = [...typeAliasDoc.annotations];
   diagnostics.push(...typeAliasDoc.diagnostics);
   const visiting = /* @__PURE__ */ new Set();
-  for (const member of typeAlias.type.members) {
+  for (const member of typeLiteral.members) {
     if (ts3.isPropertySignature(member)) {
       const fieldNode = analyzeInterfacePropertyToIR(
         member,
@@ -2246,6 +2916,7 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
         visiting,
         diagnostics,
         aliasType,
+        normalizedMetadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
@@ -2253,12 +2924,28 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
       }
     }
   }
+  const specializedFields = applyDeclarationDiscriminatorToFields(
+    fields,
+    typeAlias,
+    aliasType,
+    checker,
+    file,
+    diagnostics,
+    normalizedMetadataPolicy
+  );
+  const metadata = resolveNodeMetadata(normalizedMetadataPolicy, "type", name, typeAlias, {
+    checker,
+    declaration: typeAlias,
+    subjectType: aliasType,
+    hostType: aliasType
+  });
   return {
     ok: true,
     analysis: {
       name,
-      fields,
-      fieldLayouts: fields.map(() => ({})),
+      ...metadata !== void 0 && { metadata },
+      fields: specializedFields,
+      fieldLayouts: specializedFields.map(() => ({})),
       typeRegistry,
       ...annotations.length > 0 && { annotations },
       ...diagnostics.length > 0 && { diagnostics },
@@ -2267,7 +2954,444 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
     }
   };
 }
-function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, extensionRegistry) {
+function makeAnalysisDiagnostic(code, message, primaryLocation, relatedLocations = []) {
+  return {
+    code,
+    message,
+    severity: "error",
+    primaryLocation,
+    relatedLocations
+  };
+}
+function getLeadingParsedTags(node) {
+  const sourceFile = node.getSourceFile();
+  const sourceText = sourceFile.getFullText();
+  const commentRanges = ts3.getLeadingCommentRanges(sourceText, node.getFullStart());
+  if (commentRanges === void 0) {
+    return [];
+  }
+  const parsedTags = [];
+  for (const range of commentRanges) {
+    if (range.kind !== ts3.SyntaxKind.MultiLineCommentTrivia) {
+      continue;
+    }
+    const commentText = sourceText.slice(range.pos, range.end);
+    if (!commentText.startsWith("/**")) {
+      continue;
+    }
+    parsedTags.push(...parseCommentBlock2(commentText, { offset: range.pos }).tags);
+  }
+  return parsedTags;
+}
+function resolveDiscriminatorProperty(node, checker, fieldName) {
+  const subjectType = checker.getTypeAtLocation(node);
+  const propertySymbol = subjectType.getProperty(fieldName);
+  if (propertySymbol === void 0) {
+    return null;
+  }
+  const declaration = propertySymbol.valueDeclaration ?? propertySymbol.declarations?.find(
+    (candidate) => ts3.isPropertyDeclaration(candidate) || ts3.isPropertySignature(candidate)
+  ) ?? propertySymbol.declarations?.[0];
+  return {
+    declaration,
+    type: checker.getTypeOfSymbolAtLocation(propertySymbol, declaration ?? node),
+    optional: !!(propertySymbol.flags & ts3.SymbolFlags.Optional) || declaration !== void 0 && "questionToken" in declaration && declaration.questionToken !== void 0
+  };
+}
+function isLocalTypeParameterName(node, typeParameterName) {
+  return node.typeParameters?.some((typeParameter) => typeParameter.name.text === typeParameterName) ?? false;
+}
+function isNullishSemanticType(type) {
+  if (type.flags & (ts3.TypeFlags.Null | ts3.TypeFlags.Undefined | ts3.TypeFlags.Void | ts3.TypeFlags.Unknown | ts3.TypeFlags.Any)) {
+    return true;
+  }
+  return type.isUnion() && type.types.some((member) => isNullishSemanticType(member));
+}
+function isStringLikeSemanticType(type) {
+  if (type.flags & ts3.TypeFlags.StringLike) {
+    return true;
+  }
+  if (type.isUnion()) {
+    return type.types.length > 0 && type.types.every((member) => isStringLikeSemanticType(member));
+  }
+  return false;
+}
+function extractDiscriminatorDirective(node, file, diagnostics) {
+  const discriminatorTags = getLeadingParsedTags(node).filter(
+    (tag) => tag.normalizedTagName === "discriminator"
+  );
+  if (discriminatorTags.length === 0) {
+    return null;
+  }
+  const [firstTag, ...duplicateTags] = discriminatorTags;
+  for (const _duplicateTag of duplicateTags) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "DUPLICATE_TAG",
+        'Duplicate "@discriminator" tag. Only one discriminator declaration is allowed per declaration.',
+        provenanceForNode(node, file)
+      )
+    );
+  }
+  if (firstTag === void 0) {
+    return null;
+  }
+  const firstTarget = firstTag.target;
+  if (firstTarget?.path === null || firstTarget?.valid !== true) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        'Tag "@discriminator" requires a direct path target like ":kind".',
+        provenanceForNode(node, file)
+      )
+    );
+    return null;
+  }
+  if (firstTarget.path.segments.length !== 1) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        'Tag "@discriminator" only supports direct property targets in v1; nested paths are out of scope.',
+        provenanceForNode(node, file)
+      )
+    );
+    return null;
+  }
+  const typeParameterName = firstTag.argumentText.trim();
+  if (!/^[A-Za-z_$][\w$]*$/u.test(typeParameterName)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        'Tag "@discriminator" requires a local type parameter name as its source operand.',
+        provenanceForNode(node, file)
+      )
+    );
+    return null;
+  }
+  return {
+    fieldName: firstTarget.path.segments[0] ?? firstTarget.rawText,
+    typeParameterName,
+    provenance: provenanceForNode(node, file)
+  };
+}
+function validateDiscriminatorDirective(node, checker, file, diagnostics) {
+  const directive = extractDiscriminatorDirective(node, file, diagnostics);
+  if (directive === null) {
+    return null;
+  }
+  if (!isLocalTypeParameterName(node, directive.typeParameterName)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        `Tag "@discriminator" references "${directive.typeParameterName}", but the source operand must be a type parameter declared on the same declaration.`,
+        directive.provenance
+      )
+    );
+    return null;
+  }
+  const property = resolveDiscriminatorProperty(node, checker, directive.fieldName);
+  if (property === null) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "UNKNOWN_PATH_TARGET",
+        `Tag "@discriminator" targets "${directive.fieldName}", but no direct property with that name exists on this declaration.`,
+        directive.provenance
+      )
+    );
+    return null;
+  }
+  if (property.optional) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "TYPE_MISMATCH",
+        `Discriminator field "${directive.fieldName}" must be required; optional discriminator fields are not supported.`,
+        directive.provenance,
+        property.declaration !== void 0 ? [provenanceForNode(property.declaration, file)] : []
+      )
+    );
+    return null;
+  }
+  if (isNullishSemanticType(property.type)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "TYPE_MISMATCH",
+        `Discriminator field "${directive.fieldName}" must not be nullable.`,
+        directive.provenance,
+        property.declaration !== void 0 ? [provenanceForNode(property.declaration, file)] : []
+      )
+    );
+    return null;
+  }
+  if (!isStringLikeSemanticType(property.type)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "TYPE_MISMATCH",
+        `Discriminator field "${directive.fieldName}" must be string-like.`,
+        directive.provenance,
+        property.declaration !== void 0 ? [provenanceForNode(property.declaration, file)] : []
+      )
+    );
+    return null;
+  }
+  return directive;
+}
+function getConcreteTypeArgumentForDiscriminator(node, subjectType, checker, typeParameterName) {
+  const typeParameterIndex = node.typeParameters?.findIndex(
+    (typeParameter) => typeParameter.name.text === typeParameterName
+  ) ?? -1;
+  if (typeParameterIndex < 0) {
+    return null;
+  }
+  const referenceTypeArguments = (isTypeReference(subjectType) ? subjectType.typeArguments : void 0) ?? subjectType.aliasTypeArguments;
+  if (referenceTypeArguments?.[typeParameterIndex] !== void 0) {
+    return referenceTypeArguments[typeParameterIndex] ?? null;
+  }
+  const localTypeParameter = node.typeParameters?.[typeParameterIndex];
+  return localTypeParameter === void 0 ? null : checker.getTypeAtLocation(localTypeParameter);
+}
+function resolveLiteralDiscriminatorPropertyValue(boundType, fieldName, checker, provenance, diagnostics) {
+  const propertySymbol = boundType.getProperty(fieldName);
+  if (propertySymbol === void 0) {
+    return void 0;
+  }
+  const declaration = propertySymbol.valueDeclaration ?? propertySymbol.declarations?.[0];
+  const anchorNode = declaration ?? boundType.symbol.declarations?.[0] ?? null;
+  const resolvedAnchorNode = anchorNode ?? resolveNamedDiscriminatorDeclaration(boundType, checker);
+  if (resolvedAnchorNode === null) {
+    return void 0;
+  }
+  const propertyType = checker.getTypeOfSymbolAtLocation(
+    propertySymbol,
+    resolvedAnchorNode
+  );
+  if (propertyType.isStringLiteral()) {
+    return propertyType.value;
+  }
+  if (propertyType.isUnion()) {
+    const nonNullMembers = propertyType.types.filter(
+      (member) => !(member.flags & (ts3.TypeFlags.Null | ts3.TypeFlags.Undefined))
+    );
+    if (nonNullMembers.length > 0 && nonNullMembers.every((member) => member.isStringLiteral())) {
+      diagnostics.push(
+        makeAnalysisDiagnostic(
+          "INVALID_TAG_ARGUMENT",
+          "Discriminator resolution for union-valued identity properties is out of scope for v1.",
+          provenance
+        )
+      );
+      return null;
+    }
+  }
+  return void 0;
+}
+function resolveDiscriminatorApiName(boundType, checker, metadataPolicy) {
+  const declaration = resolveNamedDiscriminatorDeclaration(boundType, checker);
+  if (declaration === null) {
+    return void 0;
+  }
+  const metadata = resolveNodeMetadata(
+    metadataPolicy,
+    "type",
+    getDiscriminatorLogicalName(boundType, declaration, checker),
+    declaration,
+    {
+      checker,
+      declaration,
+      subjectType: boundType
+    }
+  );
+  return metadata?.apiName;
+}
+function resolveNamedDiscriminatorDeclaration(type, checker, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(type)) {
+    return null;
+  }
+  seen.add(type);
+  const symbol = type.aliasSymbol ?? type.getSymbol();
+  if (symbol !== void 0) {
+    const aliased = symbol.flags & ts3.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : void 0;
+    const targetSymbol = aliased ?? symbol;
+    const declaration = targetSymbol.declarations?.find(
+      (candidate) => ts3.isClassDeclaration(candidate) || ts3.isInterfaceDeclaration(candidate) || ts3.isTypeAliasDeclaration(candidate) || ts3.isEnumDeclaration(candidate)
+    );
+    if (declaration !== void 0) {
+      if (ts3.isTypeAliasDeclaration(declaration) && ts3.isTypeReferenceNode(declaration.type) && checker.getTypeFromTypeNode(declaration.type) !== type) {
+        return resolveNamedDiscriminatorDeclaration(
+          checker.getTypeFromTypeNode(declaration.type),
+          checker,
+          seen
+        );
+      }
+      return declaration;
+    }
+  }
+  return null;
+}
+function resolveDiscriminatorValue(boundType, fieldName, checker, provenance, diagnostics, metadataPolicy) {
+  if (boundType === null) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        "Discriminator resolution failed because no concrete type argument is available for the referenced type parameter.",
+        provenance
+      )
+    );
+    return null;
+  }
+  if (boundType.isStringLiteral()) {
+    return boundType.value;
+  }
+  if (boundType.isUnion()) {
+    const nonNullMembers = boundType.types.filter(
+      (member) => !(member.flags & (ts3.TypeFlags.Null | ts3.TypeFlags.Undefined))
+    );
+    if (nonNullMembers.every((member) => member.isStringLiteral())) {
+      diagnostics.push(
+        makeAnalysisDiagnostic(
+          "INVALID_TAG_ARGUMENT",
+          "Discriminator resolution for unions of string literals is out of scope for v1.",
+          provenance
+        )
+      );
+      return null;
+    }
+  }
+  const literalIdentityValue = resolveLiteralDiscriminatorPropertyValue(
+    boundType,
+    fieldName,
+    checker,
+    provenance,
+    diagnostics
+  );
+  if (literalIdentityValue !== void 0) {
+    return literalIdentityValue;
+  }
+  const apiName = resolveDiscriminatorApiName(boundType, checker, metadataPolicy);
+  if (apiName?.source === "explicit") {
+    return apiName.value;
+  }
+  if (apiName?.source === "inferred") {
+    return apiName.value;
+  }
+  diagnostics.push(
+    makeAnalysisDiagnostic(
+      "INVALID_TAG_ARGUMENT",
+      "Discriminator resolution could not derive a JSON-facing discriminator value from the referenced type argument.",
+      provenance
+    )
+  );
+  return null;
+}
+function getDeclarationName(node) {
+  if (ts3.isClassDeclaration(node) || ts3.isInterfaceDeclaration(node) || ts3.isTypeAliasDeclaration(node) || ts3.isEnumDeclaration(node)) {
+    return node.name?.text ?? "anonymous";
+  }
+  return "anonymous";
+}
+function getResolvedTypeArguments(type) {
+  return (isTypeReference(type) ? type.typeArguments : void 0) ?? type.aliasTypeArguments ?? [];
+}
+function getDiscriminatorLogicalName(type, declaration, checker) {
+  const baseName = getDeclarationName(declaration);
+  const typeArguments = getResolvedTypeArguments(type);
+  return typeArguments.length === 0 ? baseName : buildInstantiatedReferenceName(baseName, typeArguments, checker);
+}
+function applyDeclarationDiscriminatorToFields(fields, node, subjectType, checker, file, diagnostics, metadataPolicy) {
+  const directive = validateDiscriminatorDirective(node, checker, file, diagnostics);
+  if (directive === null) {
+    return [...fields];
+  }
+  const discriminatorValue = resolveDiscriminatorValue(
+    getConcreteTypeArgumentForDiscriminator(
+      node,
+      subjectType,
+      checker,
+      directive.typeParameterName
+    ),
+    directive.fieldName,
+    checker,
+    directive.provenance,
+    diagnostics,
+    metadataPolicy
+  );
+  if (discriminatorValue === null) {
+    return [...fields];
+  }
+  return fields.map(
+    (field) => field.name === directive.fieldName ? {
+      ...field,
+      type: {
+        kind: "enum",
+        members: [{ value: discriminatorValue }]
+      }
+    } : field
+  );
+}
+function buildInstantiatedReferenceName(baseName, typeArguments, checker) {
+  const renderedArguments = typeArguments.map(
+    (typeArgument) => checker.typeToString(typeArgument).replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "")
+  ).filter((value) => value !== "");
+  return renderedArguments.length === 0 ? baseName : `${baseName}__${renderedArguments.join("__")}`;
+}
+function extractReferenceTypeArguments(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy, extensionRegistry, diagnostics) {
+  const typeNode = sourceNode === void 0 ? void 0 : extractTypeNodeFromSource(sourceNode);
+  if (typeNode === void 0) {
+    return [];
+  }
+  const resolvedTypeNode = resolveAliasedTypeNode(typeNode, checker);
+  if (!ts3.isTypeReferenceNode(resolvedTypeNode) || resolvedTypeNode.typeArguments === void 0) {
+    return [];
+  }
+  return resolvedTypeNode.typeArguments.map((argumentNode) => {
+    const argumentType = checker.getTypeFromTypeNode(argumentNode);
+    return {
+      tsType: argumentType,
+      typeNode: resolveTypeNode(
+        argumentType,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        argumentNode,
+        metadataPolicy,
+        extensionRegistry,
+        diagnostics
+      )
+    };
+  });
+}
+function applyDiscriminatorToObjectProperties(properties, node, subjectType, checker, file, diagnostics, metadataPolicy) {
+  const directive = validateDiscriminatorDirective(node, checker, file, diagnostics);
+  if (directive === null) {
+    return properties;
+  }
+  const discriminatorValue = resolveDiscriminatorValue(
+    getConcreteTypeArgumentForDiscriminator(
+      node,
+      subjectType,
+      checker,
+      directive.typeParameterName
+    ),
+    directive.fieldName,
+    checker,
+    directive.provenance,
+    diagnostics,
+    metadataPolicy
+  );
+  if (discriminatorValue === null) {
+    return properties;
+  }
+  return properties.map(
+    (property) => property.name === directive.fieldName ? {
+      ...property,
+      type: {
+        kind: "enum",
+        members: [{ value: discriminatorValue }]
+      }
+    } : property
+  );
+}
+function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, metadataPolicy, extensionRegistry) {
   if (!ts3.isIdentifier(prop.name)) {
     return null;
   }
@@ -2282,6 +3406,7 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnosti
     typeRegistry,
     visiting,
     prop,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -2305,9 +3430,16 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnosti
     annotations.push(defaultAnnotation);
   }
   ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
+  const metadata = resolveNodeMetadata(metadataPolicy, "field", name, prop, {
+    checker,
+    declaration: prop,
+    subjectType: tsType,
+    hostType
+  });
   return {
     kind: "field",
     name,
+    ...metadata !== void 0 && { metadata },
     type,
     required: !optional,
     constraints,
@@ -2315,7 +3447,7 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnosti
     provenance
   };
 }
-function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, extensionRegistry) {
+function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, metadataPolicy, extensionRegistry) {
   if (!ts3.isIdentifier(prop.name)) {
     return null;
   }
@@ -2330,6 +3462,7 @@ function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visitin
     typeRegistry,
     visiting,
     prop,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -2349,9 +3482,16 @@ function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visitin
   let annotations = [];
   annotations.push(...docResult.annotations);
   ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
+  const metadata = resolveNodeMetadata(metadataPolicy, "field", name, prop, {
+    checker,
+    declaration: prop,
+    subjectType: tsType,
+    hostType
+  });
   return {
     kind: "field",
     name,
+    ...metadata !== void 0 && { metadata },
     type,
     required: !optional,
     constraints,
@@ -2476,7 +3616,7 @@ function getTypeNodeRegistrationName(typeNode) {
   }
   return null;
 }
-function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const customType = resolveRegisteredCustomType(sourceNode, extensionRegistry, checker);
   if (customType) {
     return customType;
@@ -2488,6 +3628,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
     typeRegistry,
     visiting,
     sourceNode,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -2532,6 +3673,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
       typeRegistry,
       visiting,
       sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -2544,6 +3686,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
       typeRegistry,
       visiting,
       sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -2555,13 +3698,15 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
       file,
       typeRegistry,
       visiting,
+      sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
   }
   return { kind: "primitive", primitiveKind: "string" };
 }
-function tryResolveNamedPrimitiveAlias(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function tryResolveNamedPrimitiveAlias(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   if (!(type.flags & (ts3.TypeFlags.String | ts3.TypeFlags.Number | ts3.TypeFlags.BigInt | ts3.TypeFlags.BigIntLiteral | ts3.TypeFlags.Boolean | ts3.TypeFlags.Null))) {
     return null;
   }
@@ -2581,14 +3726,21 @@ function tryResolveNamedPrimitiveAlias(type, checker, file, typeRegistry, visiti
       file,
       makeParseOptions(extensionRegistry)
     );
+    const metadata = resolveNodeMetadata(metadataPolicy, "type", aliasName, aliasDecl, {
+      checker,
+      declaration: aliasDecl,
+      subjectType: aliasType
+    });
     typeRegistry[aliasName] = {
       name: aliasName,
+      ...metadata !== void 0 && { metadata },
       type: resolveAliasedPrimitiveTarget(
         aliasType,
         checker,
         file,
         typeRegistry,
         visiting,
+        metadataPolicy,
         extensionRegistry,
         diagnostics
       ),
@@ -2617,7 +3769,7 @@ function shouldEmitPrimitiveAliasDefinition(typeNode, checker) {
   const resolved = checker.getTypeFromTypeNode(aliasDecl.type);
   return !!(resolved.flags & (ts3.TypeFlags.String | ts3.TypeFlags.Number | ts3.TypeFlags.BigInt | ts3.TypeFlags.BigIntLiteral | ts3.TypeFlags.Boolean | ts3.TypeFlags.Null));
 }
-function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiting, extensionRegistry, diagnostics) {
+function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiting, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const nestedAliasDecl = type.aliasSymbol?.declarations?.find(ts3.isTypeAliasDeclaration);
   if (nestedAliasDecl !== void 0) {
     return resolveAliasedPrimitiveTarget(
@@ -2626,6 +3778,7 @@ function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiti
       file,
       typeRegistry,
       visiting,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -2637,11 +3790,12 @@ function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiti
     typeRegistry,
     visiting,
     void 0,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
 }
-function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const typeName = getNamedTypeName(type);
   const namedDecl = getNamedTypeDeclaration(type);
   if (typeName && typeName in typeRegistry) {
@@ -2676,8 +3830,14 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
       return result;
     }
     const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
+    const metadata = namedDecl !== void 0 ? resolveNodeMetadata(metadataPolicy, "type", typeName, namedDecl, {
+      checker,
+      declaration: namedDecl,
+      subjectType: type
+    }) : void 0;
     typeRegistry[typeName] = {
       name: typeName,
+      ...metadata !== void 0 && { metadata },
       type: result,
       ...annotations !== void 0 && annotations.length > 0 && { annotations },
       provenance: provenanceForDeclaration(namedDecl ?? sourceNode, file)
@@ -2731,6 +3891,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
       typeRegistry,
       visiting,
       nonNullMembers[0].sourceNode ?? sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -2748,6 +3909,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
       typeRegistry,
       visiting,
       memberSourceNode ?? sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     )
@@ -2757,7 +3919,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
   }
   return registerNamed({ kind: "union", members });
 }
-function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const typeArgs = isTypeReference(type) ? type.typeArguments : void 0;
   const elementType = typeArgs?.[0];
   const elementSourceNode = extractArrayElementTypeNode(sourceNode, checker);
@@ -2768,12 +3930,13 @@ function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNod
     typeRegistry,
     visiting,
     elementSourceNode,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   ) : { kind: "primitive", primitiveKind: "string" };
   return { kind: "array", items };
 }
-function tryResolveRecordType(type, checker, file, typeRegistry, visiting, extensionRegistry, diagnostics) {
+function tryResolveRecordType(type, checker, file, typeRegistry, visiting, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   if (type.getProperties().length > 0) {
     return null;
   }
@@ -2788,6 +3951,7 @@ function tryResolveRecordType(type, checker, file, typeRegistry, visiting, exten
     typeRegistry,
     visiting,
     void 0,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -2818,35 +3982,76 @@ function typeNodeContainsReference(type, targetName) {
     }
   }
 }
-function resolveObjectType(type, checker, file, typeRegistry, visiting, extensionRegistry, diagnostics) {
+function shouldEmitResolvedObjectProperty(property, declaration) {
+  if (property.name.startsWith("__@")) {
+    return false;
+  }
+  if (declaration !== void 0 && "name" in declaration && declaration.name !== void 0) {
+    const name = declaration.name;
+    if (ts3.isComputedPropertyName(name) || ts3.isPrivateIdentifier(name)) {
+      return false;
+    }
+    if (!ts3.isIdentifier(name) && !ts3.isStringLiteral(name) && !ts3.isNumericLiteral(name)) {
+      return false;
+    }
+  }
+  return true;
+}
+function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
+  const collectedDiagnostics = diagnostics ?? [];
   const typeName = getNamedTypeName(type);
   const namedTypeName = typeName ?? void 0;
   const namedDecl = getNamedTypeDeclaration(type);
-  const shouldRegisterNamedType = namedTypeName !== void 0 && !(namedTypeName === "Record" && namedDecl?.getSourceFile().fileName !== file);
+  const referenceTypeArguments = extractReferenceTypeArguments(
+    type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    sourceNode,
+    metadataPolicy,
+    extensionRegistry,
+    collectedDiagnostics
+  );
+  const instantiatedTypeName = namedTypeName !== void 0 && referenceTypeArguments.length > 0 ? buildInstantiatedReferenceName(
+    namedTypeName,
+    referenceTypeArguments.map((argument) => argument.tsType),
+    checker
+  ) : void 0;
+  const registryTypeName = instantiatedTypeName ?? namedTypeName;
+  const shouldRegisterNamedType = registryTypeName !== void 0 && !(registryTypeName === "Record" && namedDecl?.getSourceFile().fileName !== file);
   const clearNamedTypeRegistration = () => {
-    if (namedTypeName === void 0 || !shouldRegisterNamedType) {
+    if (registryTypeName === void 0 || !shouldRegisterNamedType) {
       return;
     }
-    Reflect.deleteProperty(typeRegistry, namedTypeName);
+    Reflect.deleteProperty(typeRegistry, registryTypeName);
   };
   if (visiting.has(type)) {
-    if (namedTypeName !== void 0 && shouldRegisterNamedType) {
-      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+    if (registryTypeName !== void 0 && shouldRegisterNamedType) {
+      return {
+        kind: "reference",
+        name: registryTypeName,
+        typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+      };
     }
     return { kind: "object", properties: [], additionalProperties: false };
   }
-  if (namedTypeName !== void 0 && shouldRegisterNamedType && !typeRegistry[namedTypeName]) {
-    typeRegistry[namedTypeName] = {
-      name: namedTypeName,
+  if (registryTypeName !== void 0 && shouldRegisterNamedType && !typeRegistry[registryTypeName]) {
+    typeRegistry[registryTypeName] = {
+      name: registryTypeName,
       type: RESOLVING_TYPE_PLACEHOLDER,
       provenance: provenanceForDeclaration(namedDecl, file)
     };
   }
   visiting.add(type);
-  if (namedTypeName !== void 0 && shouldRegisterNamedType && typeRegistry[namedTypeName]?.type !== void 0) {
-    if (typeRegistry[namedTypeName].type !== RESOLVING_TYPE_PLACEHOLDER) {
+  if (registryTypeName !== void 0 && shouldRegisterNamedType && typeRegistry[registryTypeName]?.type !== void 0) {
+    if (typeRegistry[registryTypeName].type !== RESOLVING_TYPE_PLACEHOLDER) {
       visiting.delete(type);
-      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+      return {
+        kind: "reference",
+        name: registryTypeName,
+        typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+      };
     }
   }
   const recordNode = tryResolveRecordType(
@@ -2855,25 +4060,36 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
     file,
     typeRegistry,
     visiting,
+    metadataPolicy,
     extensionRegistry,
-    diagnostics
+    collectedDiagnostics
   );
   if (recordNode) {
     visiting.delete(type);
-    if (namedTypeName !== void 0 && shouldRegisterNamedType) {
-      const isRecursiveRecord = typeNodeContainsReference(recordNode.valueType, namedTypeName);
+    if (registryTypeName !== void 0 && shouldRegisterNamedType) {
+      const isRecursiveRecord = typeNodeContainsReference(recordNode.valueType, registryTypeName);
       if (!isRecursiveRecord) {
         clearNamedTypeRegistration();
         return recordNode;
       }
       const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
-      typeRegistry[namedTypeName] = {
-        name: namedTypeName,
+      const metadata = namedDecl !== void 0 ? resolveNodeMetadata(metadataPolicy, "type", registryTypeName, namedDecl, {
+        checker,
+        declaration: namedDecl,
+        subjectType: type
+      }) : void 0;
+      typeRegistry[registryTypeName] = {
+        name: registryTypeName,
+        ...metadata !== void 0 && { metadata },
         type: recordNode,
         ...annotations !== void 0 && annotations.length > 0 && { annotations },
         provenance: provenanceForDeclaration(namedDecl, file)
       };
-      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+      return {
+        kind: "reference",
+        name: registryTypeName,
+        typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+      };
     }
     return recordNode;
   }
@@ -2884,12 +4100,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
     file,
     typeRegistry,
     visiting,
-    diagnostics ?? [],
+    metadataPolicy,
+    collectedDiagnostics,
     extensionRegistry
   );
   for (const prop of type.getProperties()) {
     const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
     if (!declaration) continue;
+    if (!shouldEmitResolvedObjectProperty(prop, declaration)) continue;
     const propType = checker.getTypeOfSymbolAtLocation(prop, declaration);
     const optional = !!(prop.flags & ts3.SymbolFlags.Optional);
     const propTypeNode = resolveTypeNode(
@@ -2899,12 +4117,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
       typeRegistry,
       visiting,
       declaration,
+      metadataPolicy,
       extensionRegistry,
-      diagnostics
+      collectedDiagnostics
     );
     const fieldNodeInfo = fieldInfoMap?.get(prop.name);
     properties.push({
       name: prop.name,
+      ...fieldNodeInfo?.metadata !== void 0 && { metadata: fieldNodeInfo.metadata },
       type: propTypeNode,
       optional,
       constraints: fieldNodeInfo?.constraints ?? [],
@@ -2915,22 +4135,40 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
   visiting.delete(type);
   const objectNode = {
     kind: "object",
-    properties,
+    properties: namedDecl !== void 0 && (ts3.isClassDeclaration(namedDecl) || ts3.isInterfaceDeclaration(namedDecl) || ts3.isTypeAliasDeclaration(namedDecl)) ? applyDiscriminatorToObjectProperties(
+      properties,
+      namedDecl,
+      type,
+      checker,
+      file,
+      collectedDiagnostics,
+      metadataPolicy
+    ) : properties,
     additionalProperties: true
   };
-  if (namedTypeName !== void 0 && shouldRegisterNamedType) {
+  if (registryTypeName !== void 0 && shouldRegisterNamedType) {
     const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
-    typeRegistry[namedTypeName] = {
-      name: namedTypeName,
+    const metadata = namedDecl !== void 0 ? resolveNodeMetadata(metadataPolicy, "type", registryTypeName, namedDecl, {
+      checker,
+      declaration: namedDecl,
+      subjectType: type
+    }) : void 0;
+    typeRegistry[registryTypeName] = {
+      name: registryTypeName,
+      ...metadata !== void 0 && { metadata },
       type: objectNode,
       ...annotations !== void 0 && annotations.length > 0 && { annotations },
       provenance: provenanceForDeclaration(namedDecl, file)
     };
-    return { kind: "reference", name: namedTypeName, typeArguments: [] };
+    return {
+      kind: "reference",
+      name: registryTypeName,
+      typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+    };
   }
   return objectNode;
 }
-function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting, diagnostics, extensionRegistry) {
+function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting, metadataPolicy, diagnostics, extensionRegistry) {
   const symbols = [type.getSymbol(), type.aliasSymbol].filter(
     (s) => s?.declarations != null && s.declarations.length > 0
   );
@@ -2951,10 +4189,12 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
             visiting,
             diagnostics,
             hostType,
+            metadataPolicy,
             extensionRegistry
           );
           if (fieldNode) {
             map.set(fieldNode.name, {
+              ...fieldNode.metadata !== void 0 && { metadata: fieldNode.metadata },
               constraints: [...fieldNode.constraints],
               annotations: [...fieldNode.annotations],
               provenance: fieldNode.provenance
@@ -2972,6 +4212,7 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
         file,
         typeRegistry,
         visiting,
+        metadataPolicy,
         checker.getTypeAtLocation(interfaceDecl),
         diagnostics,
         extensionRegistry
@@ -2985,6 +4226,7 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
         file,
         typeRegistry,
         visiting,
+        metadataPolicy,
         checker.getTypeAtLocation(typeAliasDecl),
         diagnostics,
         extensionRegistry
@@ -3036,7 +4278,7 @@ function isNullishTypeNode(typeNode) {
   }
   return ts3.isLiteralTypeNode(typeNode) && (typeNode.literal.kind === ts3.SyntaxKind.NullKeyword || typeNode.literal.kind === ts3.SyntaxKind.UndefinedKeyword);
 }
-function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, hostType, diagnostics, extensionRegistry) {
+function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, metadataPolicy, hostType, diagnostics, extensionRegistry) {
   const map = /* @__PURE__ */ new Map();
   for (const member of members) {
     if (ts3.isPropertySignature(member)) {
@@ -3048,10 +4290,12 @@ function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, h
         visiting,
         diagnostics,
         hostType,
+        metadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
         map.set(fieldNode.name, {
+          ...fieldNode.metadata !== void 0 && { metadata: fieldNode.metadata },
           constraints: [...fieldNode.constraints],
           annotations: [...fieldNode.annotations],
           provenance: fieldNode.provenance
@@ -3082,6 +4326,7 @@ function extractTypeAliasConstraintNodes(typeNode, checker, file, extensionRegis
     {},
     /* @__PURE__ */ new Set(),
     aliasDecl.type,
+    void 0,
     extensionRegistry
   );
   const constraints = extractJSDocConstraintNodes(
@@ -3267,19 +4512,37 @@ function findInterfaceByName(sourceFile, interfaceName) {
 function findTypeAliasByName(sourceFile, aliasName) {
   return findNodeByName(sourceFile, aliasName, ts4.isTypeAliasDeclaration, (n) => n.name.text);
 }
-function analyzeNamedTypeToIR(filePath, typeName, extensionRegistry) {
+function analyzeNamedTypeToIR(filePath, typeName, extensionRegistry, metadataPolicy) {
   const ctx = createProgramContext(filePath);
-  return analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry);
+  return analyzeNamedTypeToIRFromProgramContext(
+    ctx,
+    filePath,
+    typeName,
+    extensionRegistry,
+    metadataPolicy
+  );
 }
-function analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry) {
+function analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry, metadataPolicy) {
   const analysisFilePath = path.resolve(filePath);
   const classDecl = findClassByName(ctx.sourceFile, typeName);
   if (classDecl !== null) {
-    return analyzeClassToIR(classDecl, ctx.checker, analysisFilePath, extensionRegistry);
+    return analyzeClassToIR(
+      classDecl,
+      ctx.checker,
+      analysisFilePath,
+      extensionRegistry,
+      metadataPolicy
+    );
   }
   const interfaceDecl = findInterfaceByName(ctx.sourceFile, typeName);
   if (interfaceDecl !== null) {
-    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, analysisFilePath, extensionRegistry);
+    return analyzeInterfaceToIR(
+      interfaceDecl,
+      ctx.checker,
+      analysisFilePath,
+      extensionRegistry,
+      metadataPolicy
+    );
   }
   const typeAlias = findTypeAliasByName(ctx.sourceFile, typeName);
   if (typeAlias !== null) {
@@ -3287,7 +4550,8 @@ function analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensi
       typeAlias,
       ctx.checker,
       analysisFilePath,
-      extensionRegistry
+      extensionRegistry,
+      metadataPolicy
     );
     if (result.ok) {
       return result.analysis;
@@ -3382,7 +4646,11 @@ function generateClassSchemas(analysis, source, options) {
   if (errorDiagnostics !== void 0 && errorDiagnostics.length > 0) {
     throw new Error(formatValidationError(errorDiagnostics));
   }
-  const ir = canonicalizeTSDoc(analysis, source);
+  const ir = canonicalizeTSDoc(
+    analysis,
+    source,
+    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+  );
   const validationResult = validateIR(ir, {
     ...options?.extensionRegistry !== void 0 && {
       extensionRegistry: options.extensionRegistry
@@ -3419,13 +4687,15 @@ function generateSchemasFromClass(options) {
     classDecl,
     ctx.checker,
     options.filePath,
-    options.extensionRegistry
+    options.extensionRegistry,
+    options.metadata
   );
   return generateClassSchemas(
     analysis,
     { file: options.filePath },
     {
       extensionRegistry: options.extensionRegistry,
+      metadata: options.metadata,
       vendorPrefix: options.vendorPrefix
     }
   );
@@ -3443,13 +4713,15 @@ function generateSchemasFromProgram(options) {
     ctx,
     options.filePath,
     options.typeName,
-    options.extensionRegistry
+    options.extensionRegistry,
+    options.metadata
   );
   return generateClassSchemas(
     analysis,
     { file: options.filePath },
     {
       extensionRegistry: options.extensionRegistry,
+      metadata: options.metadata,
       vendorPrefix: options.vendorPrefix
     }
   );
@@ -3458,16 +4730,28 @@ function generateSchemasFromProgram(options) {
 // src/generators/mixed-authoring.ts
 function buildMixedAuthoringSchemas(options) {
   const { filePath, typeName, overlays, ...schemaOptions } = options;
-  const analysis = analyzeNamedTypeToIR(filePath, typeName, schemaOptions.extensionRegistry);
-  const composedAnalysis = composeAnalysisWithOverlays(analysis, overlays);
-  const ir = canonicalizeTSDoc(composedAnalysis, { file: filePath });
+  const analysis = analyzeNamedTypeToIR(
+    filePath,
+    typeName,
+    schemaOptions.extensionRegistry,
+    schemaOptions.metadata
+  );
+  const composedAnalysis = composeAnalysisWithOverlays(analysis, overlays, schemaOptions.metadata);
+  const ir = canonicalizeTSDoc(
+    composedAnalysis,
+    { file: filePath },
+    schemaOptions.metadata !== void 0 ? { metadata: schemaOptions.metadata } : void 0
+  );
   return {
     jsonSchema: generateJsonSchemaFromIR(ir, schemaOptions),
     uiSchema: generateUiSchemaFromIR(ir)
   };
 }
-function composeAnalysisWithOverlays(analysis, overlays) {
-  const overlayIR = canonicalizeChainDSL(overlays);
+function composeAnalysisWithOverlays(analysis, overlays, metadata) {
+  const overlayIR = canonicalizeChainDSL(
+    overlays,
+    metadata !== void 0 ? { metadata } : void 0
+  );
   const overlayFields = collectOverlayFields(overlayIR.elements);
   if (overlayFields.length === 0) {
     return analysis;
@@ -3523,8 +4807,10 @@ function collectOverlayFields(elements) {
 }
 function mergeFieldOverlay(baseField, overlayField, typeRegistry) {
   assertSupportedOverlayField(baseField, overlayField);
+  const metadata = mergeResolvedMetadata(baseField.metadata, overlayField.metadata);
   return {
     ...baseField,
+    ...metadata !== void 0 && { metadata },
     type: mergeFieldType(baseField, overlayField, typeRegistry),
     annotations: mergeAnnotations(baseField.annotations, overlayField.annotations)
   };
@@ -3635,12 +4921,12 @@ function annotationKey(annotation) {
 function buildFormSchemas(form, options) {
   return {
     jsonSchema: generateJsonSchema(form, options),
-    uiSchema: generateUiSchema(form)
+    uiSchema: generateUiSchema(form, options)
   };
 }
 function writeSchemas(form, options) {
-  const { outDir, name = "schema", indent = 2, vendorPrefix } = options;
-  const buildOptions = vendorPrefix === void 0 ? void 0 : { vendorPrefix };
+  const { outDir, name = "schema", indent = 2, vendorPrefix, metadata } = options;
+  const buildOptions = vendorPrefix === void 0 && metadata === void 0 ? void 0 : { vendorPrefix, metadata };
   const { jsonSchema, uiSchema: uiSchema2 } = buildFormSchemas(form, buildOptions);
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });