@formspec/build 0.1.0-alpha.58 → 0.1.0-alpha.61

package/dist/build-internal.d.ts

@@ -162,6 +162,21 @@ declare interface BuiltinConstraintBroadeningRegistration_2 {
     readonly parseValue: (raw: string) => ExtensionPayloadValue;
 }
 
+/**
+ * Registration for mapping a built-in TSDoc tag onto a custom constraint when
+ * it is used on a particular custom type.
+ *
+ * @public
+ */
+declare interface BuiltinConstraintBroadeningRegistration_3 {
+    /** The built-in tag being broadened, without the `@` prefix. */
+    readonly tagName: BuiltinConstraintName_2;
+    /** The custom constraint to emit for this built-in tag. */
+    readonly constraintName: string;
+    /** Parser from raw TSDoc text to extension payload. */
+    readonly parseValue: (raw: string) => ExtensionPayloadValue_2;
+}
+
 /**
  * Type of a built-in constraint name.
  *
@@ -169,6 +184,13 @@ declare interface BuiltinConstraintBroadeningRegistration_2 {
  */
 declare type BuiltinConstraintName = "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "minItems" | "maxItems" | "uniqueItems" | "pattern" | "const" | "enumOptions";
 
+/**
+ * Type of a built-in constraint name.
+ *
+ * @public
+ */
+declare type BuiltinConstraintName_2 = "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "minItems" | "maxItems" | "uniqueItems" | "pattern" | "const" | "enumOptions";
+
 /**
  * A Categorization element (tab-based layout).
  *
@@ -247,6 +269,24 @@ declare interface ConstraintSemanticRole {
     readonly inclusive: boolean;
 }
 
+/**
+ * Semantic metadata for ordered custom constraints that should participate in
+ * the generic contradiction/broadening logic.
+ *
+ * @public
+ */
+declare interface ConstraintSemanticRole_2 {
+    /**
+     * Logical family identifier shared by related constraints, for example
+     * `"decimal-bound"` or `"date-bound"`.
+     */
+    readonly family: string;
+    /** Whether this constraint acts as a lower or upper bound. */
+    readonly bound: "lower" | "upper" | "exact";
+    /** Whether equality is allowed when comparing against the bound. */
+    readonly inclusive: boolean;
+}
+
 export { ConstraintTagRegistration }
 
 /**
@@ -269,6 +309,26 @@ declare interface ConstraintTagRegistration_2 {
     readonly isApplicableToType?: (type: ExtensionApplicableType) => boolean;
 }
 
+/**
+ * Declarative authoring-side registration for a custom TSDoc constraint tag.
+ *
+ * @public
+ */
+declare interface ConstraintTagRegistration_3 {
+    /** Tag name without the `@` prefix, e.g. `"maxSigFig"`. */
+    readonly tagName: string;
+    /** The custom constraint that this tag should produce. */
+    readonly constraintName: string;
+    /** Parser from raw TSDoc text to JSON-serializable payload. */
+    readonly parseValue: (raw: string) => ExtensionPayloadValue_2;
+    /**
+     * Optional precise applicability predicate for the field type being parsed.
+     * When omitted, the target custom constraint registration controls type
+     * applicability during validation.
+     */
+    readonly isApplicableToType?: (type: ExtensionApplicableType_2) => boolean;
+}
+
 /**
  * A Control element that binds to a JSON Schema property.
  *
@@ -323,7 +383,7 @@ declare interface ControlOptionConstraints {
  *
  * @public
  */
-export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): MutableExtensionRegistry;
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition_2[]): MutableExtensionRegistry;
 
 /**
  * Creates a supported static build context for a source file.
@@ -366,6 +426,24 @@ declare interface CustomAnnotationRegistration_2 {
     readonly toJsonSchema?: (value: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
 }
 
+/**
+ * Registration for a custom annotation that may produce JSON Schema keywords.
+ *
+ * Custom annotations are referenced by FormSpec's internal custom-annotation nodes.
+ * They describe or present a field but do not affect which values are valid.
+ *
+ * @public
+ */
+declare interface CustomAnnotationRegistration_3 {
+    /** The annotation name, unique within the extension. */
+    readonly annotationName: string;
+    /**
+     * Optionally converts the annotation value into JSON Schema keywords.
+     * If omitted, the annotation has no JSON Schema representation (UI-only).
+     */
+    readonly toJsonSchema?: (value: ExtensionPayloadValue_2, vendorPrefix: string) => Record<string, unknown>;
+}
+
 export { CustomConstraintRegistration }
 
 /**
@@ -426,6 +504,64 @@ declare interface CustomConstraintRegistration_2 {
     readonly emitsVocabularyKeywords?: boolean;
 }
 
+/**
+ * Registration for a custom constraint that maps to JSON Schema keywords.
+ *
+ * Custom constraints are referenced by FormSpec's internal custom-constraint nodes.
+ *
+ * @public
+ */
+declare interface CustomConstraintRegistration_3 {
+    /** The constraint name, unique within the extension. */
+    readonly constraintName: string;
+    /**
+     * How this constraint composes with other constraints of the same kind.
+     * - "intersect": combine with logical AND (both must hold)
+     * - "override": last writer wins
+     */
+    readonly compositionRule: "intersect" | "override";
+    /**
+     * TypeNode kinds this constraint is applicable to, or `null` for any type.
+     * Used by the validator to emit TYPE_MISMATCH diagnostics.
+     */
+    readonly applicableTypes: readonly ExtensionApplicableType_2["kind"][] | null;
+    /**
+     * Optional precise type predicate used when kind-level applicability is too
+     * broad (for example, constraints that apply to integer-like primitives but
+     * not strings).
+     */
+    readonly isApplicableToType?: (type: ExtensionApplicableType_2) => boolean;
+    /**
+     * Optional comparator for payloads belonging to the same custom constraint.
+     * Return values follow the `Array.prototype.sort()` contract.
+     */
+    readonly comparePayloads?: (left: ExtensionPayloadValue_2, right: ExtensionPayloadValue_2) => number;
+    /**
+     * Optional semantic family metadata for generic contradiction/broadening
+     * handling across ordered constraints.
+     */
+    readonly semanticRole?: ConstraintSemanticRole_2;
+    /**
+     * Converts the custom constraint's payload into JSON Schema keywords.
+     *
+     * @param payload - The opaque JSON payload stored on the custom constraint node.
+     * @param vendorPrefix - The vendor prefix for extension keywords.
+     * @returns A JSON Schema fragment with the constraint keywords.
+     */
+    readonly toJsonSchema: (payload: ExtensionPayloadValue_2, vendorPrefix: string) => Record<string, unknown>;
+    /**
+     * When true, `toJsonSchema` may emit vocabulary keywords that do not carry
+     * the vendor prefix. By default, all keys returned from `toJsonSchema` must
+     * start with `${vendorPrefix}-`; setting this flag relaxes that check so
+     * the constraint can produce standard or custom vocabulary keywords such as
+     * `decimalMinimum`.
+     *
+     * Use this for constraints that define their own JSON Schema vocabulary
+     * rather than namespacing under the vendor prefix.
+     */
+    readonly emitsVocabularyKeywords?: boolean;
+}
+
 export { CustomTypeRegistration }
 
 /**
@@ -477,6 +613,39 @@ declare interface CustomTypeRegistration_2 {
      * @returns A JSON Schema fragment representing this type.
      */
     readonly toJsonSchema: (payload: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
+    /**
+     * Optional hook that coerces a `@defaultValue` literal into the serialized
+     * form that validates against the schema produced by `toJsonSchema`.
+     *
+     * `@defaultValue` arguments are parsed as JavaScript literals (numbers,
+     * booleans, strings, etc.) and injected into the emitted JSON Schema as-is.
+     * For custom types whose JSON Schema representation has a different runtime
+     * shape than the parsed literal (for example, `Decimal` emits
+     * `{ type: "string" }` but authors write `@defaultValue 9.99`), the literal
+     * must be coerced so that the emitted `default` keyword conforms to the
+     * schema.
+     *
+     * When this hook is omitted, the build pipeline falls back to a best-effort
+     * inference that only inspects a top-level `type` keyword on the schema
+     * returned by `toJsonSchema` (e.g., `"string"` output causes non-string
+     * literals to be stringified). The fallback does NOT handle `oneOf`,
+     * `anyOf`, or array-form `type` keywords — extensions that emit composite
+     * schemas must provide this hook explicitly. Likewise, extensions that need
+     * bespoke serialization (e.g., Date → ISO-8601 string) should provide the
+     * hook.
+     *
+     * Errors thrown from this hook propagate as build errors; the pipeline does
+     * not catch them.
+     *
+     * @param parsed - The JS literal extracted from `@defaultValue` (already
+     *   parsed from TSDoc text; typically `number | string | boolean | null`).
+     * @param payload - The custom-type payload attached to the IR node.
+     * @returns The coerced value to emit as the JSON Schema `default`. Return
+     *   `parsed` unchanged to opt out of coercion for a specific value.
+     *
+     * @alpha
+     */
+    readonly serializeDefault?: (parsed: unknown, payload: ExtensionPayloadValue) => unknown;
     /**
      * Optional broadening of built-in constraint tags so they can apply to this
      * custom type without modifying the core built-in constraint tables.
@@ -484,6 +653,63 @@ declare interface CustomTypeRegistration_2 {
     readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration_2[];
 }
 
+/**
+ * Registration for a custom type that maps to a JSON Schema representation.
+ *
+ * Custom types are referenced by FormSpec's internal custom-type IR nodes and
+ * resolved to JSON Schema via `toJsonSchema` during generation.
+ *
+ * @public
+ */
+declare interface CustomTypeRegistration_3 {
+    /** The type name, unique within the extension. */
+    readonly typeName: string;
+    /**
+     * Optional TypeScript surface names that should resolve to this custom type
+     * during TSDoc/class analysis. Defaults to `typeName` when omitted.
+     * @deprecated Prefer `brand` for structural detection or type parameters
+     * on `defineCustomType<T>()` for symbol-based detection. String name
+     * matching will be removed in a future major version.
+     */
+    readonly tsTypeNames?: readonly string[];
+    /**
+     * Optional brand identifier for structural type detection.
+     *
+     * When provided, the type resolver checks `type.getProperties()` for a
+     * computed property whose name matches this identifier. This is more
+     * reliable than `tsTypeNames` for aliased branded types because it does not
+     * depend on the local type name.
+     *
+     * Brand detection is attempted after name-based resolution (`tsTypeNames`)
+     * as a structural fallback. If both match, name-based resolution wins.
+     *
+     * The value should match the identifier text of a `unique symbol` declaration
+     * used as a computed property key on the branded type. For example, if the
+     * type is `string & { readonly [__decimalBrand]: true }`, the brand is
+     * `"__decimalBrand"`.
+     *
+     * Brand identifiers are stored as plain strings in the extension registry, so
+     * they must be unique across the extensions loaded into the same build.
+     *
+     * Note: `"__integerBrand"` is reserved for the builtin Integer type.
+     */
+    readonly brand?: string;
+    /**
+     * Converts the custom type's payload into a JSON Schema fragment.
+     *
+     * @param payload - The opaque JSON payload stored on the custom type node.
+     * @param vendorPrefix - The vendor prefix for extension keywords (e.g., "x-stripe").
+     * @returns A JSON Schema fragment representing this type.
+     */
+    readonly toJsonSchema: (payload: ExtensionPayloadValue_2, vendorPrefix: string) => Record<string, unknown>;
+    /* Excluded from this release type: serializeDefault */
+    /**
+     * Optional broadening of built-in constraint tags so they can apply to this
+     * custom type without modifying the core built-in constraint tables.
+     */
+    readonly builtinConstraintBroadenings?: readonly BuiltinConstraintBroadeningRegistration_3[];
+}
+
 /**
  * Per-declaration metadata policy input.
  *
@@ -616,7 +842,7 @@ declare interface EnumMemberDisplayNameRequireExplicitPolicyInput {
  */
 declare interface EnumMemberMetadataInferenceContext {
     /** Authoring surface the enum originated from. */
-    readonly surface: MetadataAuthoringSurface;
+    readonly surface: MetadataAuthoringSurface_2;
     /** Logical member identifier used for policy inference. */
     readonly logicalName: string;
     /** Underlying enum value before stringification. */
@@ -672,6 +898,25 @@ declare type ExtensionApplicableType = {
     readonly kind: Exclude<ExtensionTypeKind, "primitive" | "custom">;
 };
 
+/**
+ * A curated type shape exposed to extension applicability hooks.
+ *
+ * This intentionally exposes only the fields needed to determine tag/type
+ * applicability without committing the entire canonical IR as public API.
+ *
+ * @public
+ */
+declare type ExtensionApplicableType_2 = {
+    readonly kind: "primitive";
+    readonly primitiveKind: "string" | "number" | "integer" | "bigint" | "boolean" | "null";
+} | {
+    readonly kind: "custom";
+    readonly typeId: string;
+    readonly payload: ExtensionPayloadValue_2;
+} | {
+    readonly kind: Exclude<ExtensionTypeKind_2, "primitive" | "custom">;
+};
+
 export { ExtensionDefinition }
 
 /**
@@ -713,6 +958,45 @@ declare interface ExtensionDefinition_2 {
     readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration[];
 }
 
+/**
+ * A complete extension definition bundling types, constraints, annotations,
+ * and vocabulary keywords.
+ *
+ * @example
+ * ```typescript
+ * const monetaryExtension = defineExtension({
+ *   extensionId: "x-stripe/monetary",
+ *   types: [
+ *     defineCustomType({
+ *       typeName: "Decimal",
+ *       toJsonSchema: (_payload, prefix) => ({
+ *         type: "string",
+ *         [`${prefix}-decimal`]: true,
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare interface ExtensionDefinition_3 {
+    /** Globally unique extension identifier, e.g., "x-stripe/monetary". */
+    readonly extensionId: string;
+    /** Custom type registrations provided by this extension. */
+    readonly types?: readonly CustomTypeRegistration_3[];
+    /** Custom constraint registrations provided by this extension. */
+    readonly constraints?: readonly CustomConstraintRegistration_3[];
+    /** Authoring-side TSDoc tag registrations provided by this extension. */
+    readonly constraintTags?: readonly ConstraintTagRegistration_3[];
+    /** Metadata-slot registrations shared by build- and lint-time analysis. */
+    readonly metadataSlots?: readonly MetadataSlotRegistration_2[];
+    /** Custom annotation registrations provided by this extension. */
+    readonly annotations?: readonly CustomAnnotationRegistration_3[];
+    /** Vocabulary keyword registrations provided by this extension. */
+    readonly vocabularyKeywords?: readonly VocabularyKeywordRegistration_2[];
+}
+
 /**
  * A JSON-serializable payload value used by extension registration hooks.
  *
@@ -722,6 +1006,15 @@ declare type ExtensionPayloadValue = null | boolean | number | string | readonly
     readonly [key: string]: ExtensionPayloadValue;
 };
 
+/**
+ * A JSON-serializable payload value used by extension registration hooks.
+ *
+ * @public
+ */
+declare type ExtensionPayloadValue_2 = null | boolean | number | string | readonly ExtensionPayloadValue_2[] | {
+    readonly [key: string]: ExtensionPayloadValue_2;
+};
+
 /**
  * A registry of extensions that provides lookup by fully-qualified ID.
  *
@@ -733,14 +1026,31 @@ declare type ExtensionPayloadValue = null | boolean | number | string | readonly
  */
 export declare interface ExtensionRegistry {
     /** The extensions registered in this registry (in registration order). */
-    readonly extensions: readonly ExtensionDefinition[];
+    readonly extensions: readonly ExtensionDefinition_2[];
+    /**
+     * Setup diagnostics detected during registry construction.
+     *
+     * These diagnostics represent configuration errors in the extension
+     * registrations — e.g. unsupported TypeScript built-in type overrides,
+     * invalid type-name identifiers, or duplicate registrations. They are
+     * computed ONCE at `createExtensionRegistry` call time (§4 Phase 4 Slice C)
+     * and carried on the registry so consumers can emit them without re-running
+     * the validation on every analysis call.
+     *
+     * Consumers should check this array at the start of each analysis pass and
+     * short-circuit if it is non-empty — the registry is unusable for
+     * constraint-type validation when setup diagnostics are present.
+     *
+     * @internal
+     */
+    readonly setupDiagnostics: readonly SetupDiagnostic[];
     /**
      * Look up a custom type registration by its fully-qualified type ID.
      *
      * @param typeId - The fully-qualified type ID (e.g., "x-stripe/monetary/Decimal").
      * @returns The registration if found, otherwise `undefined`.
      */
-    findType(typeId: string): CustomTypeRegistration | undefined;
+    findType(typeId: string): CustomTypeRegistration_2 | undefined;
     /**
      * Look up a custom type registration by a TypeScript-facing type name.
      *
@@ -779,20 +1089,20 @@ export declare interface ExtensionRegistry {
      * @param constraintId - The fully-qualified constraint ID.
      * @returns The registration if found, otherwise `undefined`.
      */
-    findConstraint(constraintId: string): CustomConstraintRegistration | undefined;
+    findConstraint(constraintId: string): CustomConstraintRegistration_2 | undefined;
     /**
      * Look up a TSDoc custom constraint-tag registration by tag name.
      */
     findConstraintTag(tagName: string): {
         readonly extensionId: string;
-        readonly registration: ConstraintTagRegistration;
+        readonly registration: ConstraintTagRegistration_2;
     } | undefined;
     /**
      * Look up built-in tag broadening for a given custom type ID.
      */
     findBuiltinConstraintBroadening(typeId: string, tagName: string): {
         readonly extensionId: string;
-        readonly registration: BuiltinConstraintBroadeningRegistration;
+        readonly registration: BuiltinConstraintBroadeningRegistration_2;
     } | undefined;
     /**
      * Look up a custom annotation registration by its fully-qualified annotation ID.
@@ -800,7 +1110,7 @@ export declare interface ExtensionRegistry {
      * @param annotationId - The fully-qualified annotation ID.
      * @returns The registration if found, otherwise `undefined`.
      */
-    findAnnotation(annotationId: string): CustomAnnotationRegistration | undefined;
+    findAnnotation(annotationId: string): CustomAnnotationRegistration_2 | undefined;
 }
 
 /**
@@ -810,6 +1120,13 @@ export declare interface ExtensionRegistry {
  */
 declare type ExtensionTypeKind = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
 
+/**
+ * Top-level type kinds that extension applicability hooks may inspect.
+ *
+ * @public
+ */
+declare type ExtensionTypeKind_2 = "primitive" | "enum" | "array" | "object" | "record" | "union" | "reference" | "dynamic" | "custom";
+
 /**
  * The result of a successful extension type lookup.
  *
@@ -823,7 +1140,7 @@ export declare interface ExtensionTypeLookupResult {
     /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
     readonly extensionId: string;
     /** The custom type registration matched by this lookup. */
-    readonly registration: CustomTypeRegistration;
+    readonly registration: CustomTypeRegistration_2;
 }
 
 /**
@@ -888,7 +1205,7 @@ export declare interface FormSpecConfig {
      * Extension definitions providing custom types, constraints,
      * annotations, and vocabulary keywords.
      */
-    readonly extensions?: readonly ExtensionDefinition_2[];
+    readonly extensions?: readonly ExtensionDefinition_3[];
     /** Constraint surface configuration — controls which field types,
      * layouts, UI features, and field/control options are allowed. */
     readonly constraints?: ConstraintConfig;
@@ -1681,6 +1998,13 @@ declare interface LayoutTypeConstraints {
  */
 declare type MetadataAuthoringSurface = "tsdoc" | "chain-dsl";
 
+/**
+ * Authoring surfaces that can contribute metadata.
+ *
+ * @public
+ */
+declare type MetadataAuthoringSurface_2 = "tsdoc" | "chain-dsl";
+
 /**
  * Declaration categories that metadata policy can target.
  *
@@ -1688,6 +2012,13 @@ declare type MetadataAuthoringSurface = "tsdoc" | "chain-dsl";
  */
 declare type MetadataDeclarationKind = "type" | "field" | "method";
 
+/**
+ * Declaration categories that metadata policy can target.
+ *
+ * @public
+ */
+declare type MetadataDeclarationKind_2 = "type" | "field" | "method";
+
 /**
  * Build-facing context passed to metadata inference callbacks.
  *
@@ -1707,19 +2038,38 @@ declare interface MetadataInferenceContext {
     readonly buildContext?: unknown;
 }
 
+/**
+ * Build-facing context passed to metadata inference callbacks.
+ *
+ * `buildContext` is intentionally opaque so browser/runtime packages do not
+ * need to depend on TypeScript compiler types.
+ *
+ * @public
+ */
+declare interface MetadataInferenceContext_2 {
+    /** Authoring surface the metadata is being resolved for. */
+    readonly surface: MetadataAuthoringSurface_2;
+    /** Declaration kind currently being resolved. */
+    readonly declarationKind: MetadataDeclarationKind_2;
+    /** Logical identifier before any metadata policy is applied. */
+    readonly logicalName: string;
+    /** Optional build-only context supplied by the resolver. */
+    readonly buildContext?: unknown;
+}
+
 /**
  * Callback used to infer a scalar metadata value.
  *
  * @public
  */
-declare type MetadataInferenceFn = (context: MetadataInferenceContext) => string;
+declare type MetadataInferenceFn = (context: MetadataInferenceContext_2) => string;
 
 /**
  * Context passed to pluralization callbacks.
  *
  * @public
  */
-declare interface MetadataPluralizationContext extends MetadataInferenceContext {
+declare interface MetadataPluralizationContext extends MetadataInferenceContext_2 {
     /** Singular value that pluralization should derive from. */
     readonly singular: string;
 }
@@ -1803,6 +2153,23 @@ declare interface MetadataQualifierRegistration {
     readonly inferValue?: MetadataSlotInferenceFn | undefined;
 }
 
+/**
+ * Supported qualifier registration for an extensible metadata slot.
+ *
+ * @public
+ */
+declare interface MetadataQualifierRegistration_2 {
+    /** Qualifier text without the leading colon. */
+    readonly qualifier: string;
+    /**
+     * Optional source qualifier to use as the base input for this qualifier's
+     * inference hook. Defaults to the slot's bare/default value when omitted.
+     */
+    readonly sourceQualifier?: string | undefined;
+    /** Optional inference hook for this qualified value. */
+    readonly inferValue?: MetadataSlotInferenceFn_2 | undefined;
+}
+
 /**
  * Stable slot identifier for extensible metadata analysis.
  *
@@ -1810,6 +2177,13 @@ declare interface MetadataQualifierRegistration {
  */
 declare type MetadataSlotId = string;
 
+/**
+ * Stable slot identifier for extensible metadata analysis.
+ *
+ * @public
+ */
+declare type MetadataSlotId_2 = string;
+
 /**
  * Context passed to extensible metadata inference hooks.
  *
@@ -1826,6 +2200,22 @@ declare interface MetadataSlotInferenceContext extends MetadataInferenceContext
     readonly baseValue?: string | undefined;
 }
 
+/**
+ * Context passed to extensible metadata inference hooks.
+ *
+ * @public
+ */
+declare interface MetadataSlotInferenceContext_2 extends MetadataInferenceContext_2 {
+    /** Stable logical slot identifier. */
+    readonly slotId: MetadataSlotId_2;
+    /** Tag name associated with the slot, without the `@` prefix. */
+    readonly tagName: string;
+    /** Optional qualifier being inferred (for example `plural`). */
+    readonly qualifier?: string | undefined;
+    /** Resolved bare/default value used as the base input for derived qualifiers. */
+    readonly baseValue?: string | undefined;
+}
+
 /**
  * Callback used to infer an extensible metadata slot value.
  *
@@ -1833,6 +2223,13 @@ declare interface MetadataSlotInferenceContext extends MetadataInferenceContext
  */
 declare type MetadataSlotInferenceFn = (context: MetadataSlotInferenceContext) => string;
 
+/**
+ * Callback used to infer an extensible metadata slot value.
+ *
+ * @public
+ */
+declare type MetadataSlotInferenceFn_2 = (context: MetadataSlotInferenceContext_2) => string;
+
 /**
  * Extensible metadata slot definition shared across build- and lint-time analysis.
  *
@@ -1858,6 +2255,31 @@ declare interface MetadataSlotRegistration {
     readonly isApplicable?: ((context: MetadataInferenceContext) => boolean) | undefined;
 }
 
+/**
+ * Extensible metadata slot definition shared across build- and lint-time analysis.
+ *
+ * @public
+ */
+declare interface MetadataSlotRegistration_2 {
+    /** Stable logical slot identifier. */
+    readonly slotId: MetadataSlotId_2;
+    /** Tag name associated with this slot, without the `@` prefix. */
+    readonly tagName: string;
+    /** Declaration kinds where the slot is meaningful. */
+    readonly declarationKinds: readonly MetadataDeclarationKind_2[];
+    /** Whether a bare tag without a qualifier is supported. Defaults to true. */
+    readonly allowBare?: boolean | undefined;
+    /** Supported qualifiers for this slot. */
+    readonly qualifiers?: readonly MetadataQualifierRegistration_2[] | undefined;
+    /** Optional inference hook for the bare/default slot value. */
+    readonly inferValue?: MetadataSlotInferenceFn_2 | undefined;
+    /**
+     * Optional applicability hook for declaration-specific rules beyond
+     * declaration kind. `buildContext` may carry compiler objects.
+     */
+    readonly isApplicable?: ((context: MetadataInferenceContext_2) => boolean) | undefined;
+}
+
 /**
  * Supported declaration kinds for standalone metadata resolution.
  *
@@ -2116,6 +2538,23 @@ export declare interface SchemaGenerationTarget {
  */
 export declare type SchemaSourceDeclaration = ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
 
+/**
+ * Setup-time diagnostic produced by the `_validateExtensionSetup` helper.
+ *
+ * The `kind` field distinguishes between a "setup" failure (invalid type
+ * name, duplicate registration) and an unsupported built-in override.
+ *
+ * @internal
+ */
+export declare interface SetupDiagnostic {
+    /** The category of diagnostic. */
+    readonly kind: "unsupported-custom-type-override" | "synthetic-setup";
+    /** TypeScript diagnostic code, or -1 for non-TypeScript diagnostics. */
+    readonly code: number;
+    /** Human-readable description of the diagnostic. */
+    readonly message: string;
+}
+
 /**
  * Severity level for constraint violations.
  * - "error": Violation fails validation
@@ -2363,6 +2802,18 @@ declare interface VocabularyKeywordRegistration {
     readonly schema: ExtensionPayloadValue;
 }
 
+/**
+ * Registration for a vocabulary keyword to include in a JSON Schema `$vocabulary` declaration.
+ *
+ * @public
+ */
+declare interface VocabularyKeywordRegistration_2 {
+    /** The keyword name (without vendor prefix). */
+    readonly keyword: string;
+    /** JSON Schema that describes the valid values for this keyword. */
+    readonly schema: ExtensionPayloadValue_2;
+}
+
 /**
  * Builds and writes both JSON Schema and UI Schema files to disk.
  *