field_struct 0.15.0

data/sig/field_struct.rbs

@@ -0,0 +1,2845 @@
+# Typed PORO foundation: declare fields with enforced types, presence checks,
+# and per-field validation. Subclass {FieldStruct::Base} to get a value object
+# whose attributes coerce, validate on assignment, and introspect cleanly.
+module FieldStruct
+  FILTERED: String
+  VERSION: String
+
+  # The library's root directory — the parent of +lib/+. Computed from this
+  # file's location, so it resolves to the repo root in development and to the
+  # installed gem directory when packaged.
+  # 
+  #   FieldStruct.root.join('lib', 'field_struct.rb') # => #<Pathname …>
+  # 
+  # _@return_ — absolute path to the gem root
+  def self.root: () -> Pathname
+
+  # Build a new {Registry}, parented to +parent+ (defaults to
+  # {FieldStruct.types}), and optionally configure it with a block
+  # evaluated in the new registry's instance scope.
+  # 
+  #   module Acme
+  #     def self.field_types
+  #       @field_types ||= FieldStruct.new_registry do
+  #         register :money, Acme::Types::Money
+  #       end
+  #     end
+  #   end
+  # 
+  # Equivalent to the longhand:
+  # 
+  #   FieldStruct::Registry.new(FieldStruct.types).tap do |r|
+  #     r.register :money, Acme::Types::Money
+  #   end
+  # 
+  # Pass +parent: nil+ for an unparented registry (no fallback chain).
+  # 
+  # _@param_ `parent` — the parent registry; defaults to {FieldStruct.types}. Pass +nil+ explicitly for no parent.
+  def self.new_registry: (?Registry? parent) -> Registry
+
+  # The base type registry, seeded with every v1 scalar type and the
+  # +:decimal+ alias for +:big_decimal+. Namespace registries should be
+  # built with this as their parent (see {Registry}).
+  def self.types: () -> Registry
+
+  # Opt-in short alias for the +FieldStruct+ module.
+  # 
+  # Defines a top-level constant (default: +FS+) that points back to
+  # +FieldStruct+, *and* swaps the prefix used by every +#inspect+
+  # method in the library so IRB output reads with the short name too:
+  # 
+  #   FieldStruct.use_alias!
+  #   FS::Base                 # => FieldStruct::Base
+  #   User.metadata.inspect    # => "#<FS::Metadata fields=[...]>"
+  # 
+  # Off by default — the user has to ask for it. Idempotent. If the
+  # chosen constant is already defined to something other than
+  # FieldStruct, raises +NameError+ rather than clobbering.
+  # 
+  # _@param_ `name` — the top-level constant to define (default +:FS+)
+  # 
+  # _@return_ — for chaining
+  def self.use_alias!: (?Symbol name) -> self
+
+  # The current prefix that library +#inspect+ methods should render.
+  # Defaults to +"FieldStruct"+; flipped to the alias string (e.g.
+  # +"FS"+) by {.use_alias!}.
+  def self.inspect_namespace: () -> String
+
+  # Generates RBS type signatures for the *generated* instance surface of
+  # user-defined {FieldStruct::Base} subclasses — the per-field accessors the
+  # +field+ DSL defines dynamically.
+  # 
+  # Sord generates +sig/field_struct.rbs+ from the library's static source, so
+  # it covers {Base}, {Types}, {Registry}, … but it can never see +User#name+
+  # or +User#age=+: those methods don't exist until a consumer declares the
+  # fields. This is the deferred "track 2" of the plan's RBS strategy (D13) —
+  # walk a subclass's {Metadata} and emit signatures for its accessors so
+  # downstream Steep / Solargraph can type-check code that touches them.
+  # 
+  #   class User < FieldStruct::Base
+  #     required :name, :string
+  #     optional :age,  :integer
+  #   end
+  # 
+  #   puts FieldStruct::RBS.generate(User)
+  #   # # Generated by FieldStruct::RBS. ...
+  #   # class User < ::FieldStruct::Base
+  #   #   attr_reader name: ::String
+  #   #   def name=: (::String? value) -> ::String?
+  #   #
+  #   #   attr_reader age: ::Integer?
+  #   #   def age=: (::Integer? value) -> ::Integer?
+  #   # end
+  # 
+  # Design choices:
+  # 
+  # * **Types describe a valid instance.** The reader type is the field's
+  #   {Types::Base#ruby_type} (or an override, below). Nullability follows
+  #   {Field#required?}: required → +T+, optional → +T?+. An invalid
+  #   instance — a required field left unset, or a +:keep_raw+ coercion
+  #   failure holding the raw input — can hold other values; check +valid?+
+  #   before trusting the signature. The generated header says so.
+  # * **Writer** is +(T? value) -> T?+: the runtime setter accepts +nil+ and
+  #   returns the coerced value. Loose input the type would coerce
+  #   (+user.age = "30"+) is valid Ruby but a type error to Steep — cast or
+  #   coerce at the boundary.
+  # * **Generic arguments** are filled in: arrays as +::Array[Element]+
+  #   (a scalar element as +Element?+, since a valid instance can hold nil
+  #   elements; a nested element stays non-nil, since nil makes it invalid),
+  #   unions as +(A | B)+ (a boolean member as +bool+, a member's own
+  #   {Types::Base#rbs_type} first), nested structs by qualified name; an
+  #   anonymous nested class raises +ArgumentError+. A custom type whose +ruby_type+ is a bare generic
+  #   class (+::Hash+) gets +untyped+ arguments unless it declares
+  #   {Types::Base#rbs_type}.
+  # * **Anything-valued fields** (+:value+, or a union with a +:value+
+  #   member) are +untyped+ — reader and writer, never +untyped?+.
+  # * **Overrides:** a field's +rbs_type:+ option, then the type's
+  #   {Types::Base#rbs_type}, replace the derived type +T+ verbatim;
+  #   nullability is still added for optional fields and writers.
+  # * **+new+ / +initialize+** are inherited from {Base}, which already
+  #   accepts +User.new(name: ...)+.
+  # 
+  # Each call emits one class. Referenced types (nested structs, array
+  # elements) appear as qualified names (+::Address+) — generate RBS for those
+  # classes too so the references resolve. {.type_for} exposes the per-field
+  # mapping for other generators.
+  module RBS
+    BOOL_CLASSES: ::Array[Class]
+    HEADER: String
+    GENERIC_ARITY: ::Hash[Class, Integer]
+
+    # Generate RBS source for a single FieldStruct subclass.
+    # 
+    # _@param_ `klass`
+    # 
+    # _@return_ — RBS declaring the class (wrapped in its module nesting)
+    # and a typed reader and writer for every field it declares, after a
+    # comment header stating that the types describe a valid instance
+    def self.generate: (singleton(FieldStruct::Base) klass) -> String
+
+    # The RBS type of one field's value, as {.generate} emits it — for other
+    # generators (e.g. one typing a method that takes or returns the field)
+    # that need the same mapping:
+    # 
+    #   FieldStruct::RBS.type_for(Order.metadata[:items])
+    #   # => "::Array[::LineItem]?"
+    #   FieldStruct::RBS.type_for(Order.metadata[:items], nullable: false)
+    #   # => "::Array[::LineItem]"
+    # 
+    # The type comes from the field's +rbs_type:+ option, else its type's
+    # {Types::Base#rbs_type}, else its {Types::Base#ruby_type} with generic
+    # arguments filled in. Qualified names (+::LineItem+) assume the
+    # referenced classes get RBS too.
+    # 
+    # _@param_ `field` — a declared field, e.g. +Order.metadata[:items]+
+    # 
+    # _@param_ `nullable` — append +?+ (the reader type of an optional field, and every writer's); +nil+, the default, means +!field.required?+. Never applied to +untyped+, which already admits +nil+.
+    # 
+    # _@return_ — an RBS type expression
+    def self.type_for: (Field field, ?nullable: bool?) -> String
+
+    # Build the +class ... end+ block (unindented, no surrounding modules).
+    # 
+    # _@param_ `klass`
+    def self.class_block: (singleton(FieldStruct::Base) klass) -> String
+
+    # Fields declared on +klass+ itself — inherited fields (the same {Field}
+    # objects merged in at inheritance time) belong to the parent's RBS.
+    # 
+    # _@param_ `klass`
+    def self.own_fields: (singleton(FieldStruct::Base) klass) -> ::Array[Field]
+
+    # An override, parenthesized when it is a union, intersection or proc
+    # type, so a trailing +?+ applies to the whole of it.
+    # 
+    # _@param_ `rbs` — a field's +rbs_type:+ or a type's +rbs_type+
+    # 
+    # _@return_ — +nil+ when there is no override
+    def self.override_expression: (String? rbs) -> String?
+
+    # _@param_ `rbs` — a stripped RBS type expression
+    # 
+    # _@return_ — whether one parenthesized group spans all of +rbs+
+    # (optionally followed by +?+), so wrapping it again adds nothing
+    def self.wrapped?: (String rbs) -> bool
+
+    # _@param_ `base` — an RBS type expression
+    # 
+    # _@return_ — +base+ made nullable, unless it already admits +nil+
+    def self.optional: (String base) -> String
+
+    # Map a type instance (plus its field options, needed for arrays) to an
+    # RBS type expression.
+    # 
+    # _@param_ `type_instance`
+    # 
+    # _@param_ `options`
+    def self.expression_for: (Types::Base type_instance, ::Hash[Symbol, Object?] options) -> String
+
+    # A union as its members' types, each member's own +rbs_type+ first.
+    # 
+    # _@param_ `union`
+    # 
+    # _@return_ — +untyped+ when any member is
+    def self.union_expression: (Types::Union union) -> String
+
+    # _@param_ `classes` — a {Types::Base#ruby_type}, as a list
+    # 
+    # _@return_ — one RBS type per class, with +TrueClass+ /
+    # +FalseClass+ together collapsed to +bool+ where the pair appears
+    def self.classes_to_rbs: (::Array[Class] classes) -> ::Array[String]
+
+    # The element type of an array field, derived from its +:of_type+ (a
+    # +Types::Base+ subclass for stock types, or a built instance for
+    # parameterized ones like {Types::Nested}).
+    # 
+    # _@param_ `of_type`
+    def self.element_type: ((Class | Types::Base)? of_type) -> String
+
+    # _@param_ `klass` — a Ruby class from a {Types::Base#ruby_type}
+    # 
+    # _@return_ — qualified RBS name (with +untyped+ type arguments for
+    # a generic class), or +untyped+ for the value type's +::Object+
+    def self.class_to_rbs: (Class klass) -> String
+
+    # Wrap an inner block in the +module ... end+ nesting implied by a
+    # qualified class name, indenting two spaces per level.
+    # 
+    # _@param_ `full_name` — e.g. +"Acme::Order"+
+    # 
+    # _@param_ `inner` — the class block
+    # 
+    # _@return_ — RBS source ending in a trailing newline
+    def self.wrap_namespace: (String full_name, String inner) -> String
+
+    # _@param_ `text`
+    # 
+    # _@return_ — +text+ with every non-blank line indented two spaces
+    def self.indent: (String text) -> String
+  end
+
+  # Superclass for FieldStruct value classes.
+  # 
+  #   class User < FieldStruct::Base
+  #     field :name, :string
+  #     field :age,  :integer
+  #   end
+  # 
+  #   u = User.new(name: 'Alice', age: '30')
+  #   u.name        # => 'Alice'
+  #   u.age         # => 30   (coerced from the string)
+  #   u.attributes  # => { name: 'Alice', age: 30 }
+  # 
+  # Phase 1 wires up the +field+ macro, getter/setter accessors with
+  # coercion via the resolved type, +initialize+ from a hash, +attributes+
+  # / +attribute_names+, and metadata inheritance via the +inherited+
+  # hook. Macros and validation layer on in later slices.
+  class Base
+    VALID_COERCION_POLICIES: ::Array[Symbol]
+    VALID_UNKNOWN_POLICIES: ::Array[Symbol]
+    RESERVED_FIELD_NAMES: ::Array[Symbol]
+    UNSET: Object
+    JSON_LOAD_OPTIONS: ::Hash[Symbol, Object]
+    JSON_DUMP_OPTIONS: ::Hash[Symbol, Object]
+    UNIVERSAL_FIELD_OPTIONS: ::Array[Symbol]
+
+    # _@return_ — the per-class field collection (memoized)
+    def self.metadata: () -> Metadata
+
+    # Mark this class (and its descendants) immutable. Setters called
+    # after {#initialize} completes raise {ImmutableError}. One-way
+    # switch: there is no companion +mutable!+ macro in Phase 1.
+    def self.immutable!: () -> bool
+
+    # _@return_ — whether this class is marked immutable
+    # (locally or via an ancestor)
+    def self.immutable?: () -> bool
+
+    # Mark this class (and its descendants) frozen-on-construct.
+    # Instances will be Ruby-frozen at the end of {#initialize} —
+    # any subsequent attempt to mutate ivars raises +FrozenError+.
+    # 
+    # Independent of {.immutable!}. +immutable!+ blocks our setters
+    # with a custom error; +frozen!+ engages Ruby's frozen-state
+    # mechanism, which also locks the instance against any other
+    # ivar mutation. Pick the one that matches the level of
+    # strictness you need (or stack both).
+    def self.frozen!: () -> bool
+
+    # _@return_ — whether instances of this class are frozen at
+    # the end of {#initialize} (locally or via an ancestor)
+    def self.frozen_on_construct?: () -> bool
+
+    # Class macro: get or set the policy used by the setter pipeline
+    # when a value can't be coerced into a field's declared type.
+    # 
+    #   coercion_policy :keep_raw   # default — store raw, add error
+    #   coercion_policy :replace    # store nil,  add error
+    #   coercion_policy :raise      # raise CoercionError
+    # 
+    # Inherited by subclasses; descendants can override. Default on
+    # Base itself is +:keep_raw+.
+    # 
+    # _@param_ `value` — policy to set; omit to read
+    # 
+    # _@return_ — the resolved policy
+    def self.coercion_policy: (?Symbol value) -> Symbol
+
+    # Class macro: get or set how {Base#initialize} responds to input
+    # keys that do not match any declared field.
+    # 
+    #   unknown_attributes :ignore   # default — silently drop them
+    #   unknown_attributes :raise    # raise UnknownAttributeError
+    # 
+    # Inherited by subclasses; descendants can override.
+    # 
+    # _@param_ `value` — policy to set; omit to read
+    # 
+    # _@return_ — the resolved policy
+    def self.unknown_attributes: (?Symbol value) -> Symbol
+
+    # _@return_ — declared field names in insertion order
+    def self.attribute_names: () -> ::Array[Symbol]
+
+    # Declare a field. Resolves +type_arg+ — a registered symbol or a
+    # {FieldStruct::Base} subclass — into a type class (and, for
+    # parameterized types like {Types::Nested}, a pre-built instance),
+    # builds a {Field}, adds it to the class's {Metadata}, and defines
+    # the getter/setter pair.
+    # 
+    # _@param_ `name` — canonical field name
+    # 
+    # _@param_ `type_arg` — a registered name in the resolving registry, OR a +Types::Base+ subclass, OR a +FieldStruct::Base+ subclass (auto-wrapped in {Types::Nested})
+    # 
+    # _@param_ `options` — each keyword option's value: +required:+ (Boolean), +default:+ (literal or callable), +coercion_policy:+ (Symbol), +description:+ / +desc:+ (String), +rbs_type:+ (String — an RBS type expression {RBS.generate} emits for this field instead of the derived one), +sensitive:+ (Boolean — mask the value in +inspect+; see {Field#sensitive?}), plus type-specific options (e.g. +format:+, +round:+, +of:+, +values:+, +enum:+, +in:+) — see each type's +coerce+ for the options it consumes
+    # 
+    # _@return_ — the class-level metadata, so the DSL reads
+    # cleanly in IRB (each line prints the running set of declared
+    # fields rather than just the most recently added one). The
+    # added Field is still available as +metadata[name]+.
+    def self.field: ((Symbol | String) name, (Symbol | singleton(Types::Base) | singleton(FieldStruct::Base)) type_arg, **Object? options) -> Metadata
+
+    # Sugar for {.field} with +required: true+.
+    # 
+    # _@param_ `name`
+    # 
+    # _@param_ `type_name`
+    # 
+    # _@param_ `options` — keyword options, as for {.field}
+    def self.required: ((Symbol | String) name, (Symbol | singleton(Types::Base) | singleton(FieldStruct::Base)) type_name, **Object? options) -> Metadata
+
+    # Sugar for {.field} with +required: false+ (the default).
+    # 
+    # _@param_ `name`
+    # 
+    # _@param_ `type_name`
+    # 
+    # _@param_ `options` — keyword options, as for {.field}
+    def self.optional: ((Symbol | String) name, (Symbol | singleton(Types::Base) | singleton(FieldStruct::Base)) type_name, **Object? options) -> Metadata
+
+    # Declare an external-name mapping for a serialization format.
+    # The mapping reads internal-field-name (Symbol) on the left, the
+    # external name (String) on the right; it applies to both
+    # directions (import reverse-maps, export forward-maps).
+    # 
+    #   serialize :json,
+    #             first_name: 'firstName',
+    #             last_name:  'lastName'
+    # 
+    # Fields not listed in the mapping serialize under their canonical
+    # name (identity). Repeating +serialize :json, ...+ on the same
+    # class replaces the prior mapping (last-write-wins).
+    # 
+    # All mapping keys must be declared fields at the moment +serialize+
+    # is called — declare fields first, then declare serializations.
+    # Mapping values are normalized to Strings.
+    # 
+    # The +:json+ format ships in-gem (Phase B wires it into +to_json+ /
+    # +from_json+). Future formats (CSV, XML, etc.) will be supported
+    # by downstream gems reading the same metadata.
+    # 
+    # _@param_ `name` — the format name (e.g. +:json+)
+    # 
+    # _@param_ `mapping` — each external key, passed as a keyword named for the internal field. Symbol values are normalized to Strings.
+    def self.serialize: ((Symbol | String) name, **(String | Symbol) mapping) -> self
+
+    # Resolve a type name through the registry chain visible to this
+    # class. Walks the containing modules of the class's name in
+    # outermost-first order, looking for the nearest one that responds
+    # to +field_types+. Falls back to {FieldStruct.types}.
+    # 
+    # _@param_ `type_name`
+    # 
+    # _@return_ — a Types::Base subclass
+    def self.resolve_type: (Symbol type_name) -> Class
+
+    # Resolve the second positional argument of {.field}.
+    # 
+    # _@param_ `type_arg`
+    # 
+    # _@return_ — +[type_class, type_instance]+ —
+    # +type_instance+ is +nil+ for stock symbolic types (Field will
+    # call +type_class.new+ itself); for nested-class args (and for
+    # symbol args that resolve to a FieldStruct::Base subclass) it's
+    # a pre-built {Types::Nested} instance.
+    def self.resolve_type_arg: ((Symbol | Class) type_arg) -> [Class, Types::Base]
+
+    # _@return_ — an ActiveModel::Name-shaped value for this class
+    def self.model_name: () -> ModelName
+
+    # A human/agent-readable summary of this class's schema: the class name
+    # followed by one line per field (type, required-ness, and the native
+    # options that field's type accepts). A single call that answers "what
+    # does this model look like, and what can I put where" without reading
+    # source. See {Metadata#describe} for the field-line format.
+    def self.describe: () -> String
+
+    # Parse a JSON string and build an instance.
+    # 
+    #   Person.from_json('{"name":"Alice","address":{"street":"1","city":"NYC"}}')
+    #   # => #<Person name: "Alice", address: #<Address ...>>
+    # 
+    # The parsed hash is fed through {#initialize} like any other input,
+    # so the full setter pipeline runs: coercion (strings re-coerce to
+    # Date/Time/BigDecimal), nested Hash → Types::Nested instantiation,
+    # +unknown_attributes+ policy, +coercion_policy+. Invalid JSON
+    # raises the underlying Oj parse error's class (+EncodingError+ or a
+    # subclass) with its position but not the input, which Oj's own
+    # message quotes; a non-object root (+[...]+, +"hi"+, +42+) raises
+    # +ArgumentError+ naming its class.
+    # 
+    # JSON numbers with a fraction or exponent parse as +BigDecimal+, never
+    # through a Float, so a +:decimal+ field gets the exact digits sent.
+    # +:float+ fields still convert to Float; +:value+ fields (and numbers
+    # inside their Hashes and Arrays) receive the +BigDecimal+.
+    # 
+    # _@param_ `json_string`
+    def self.from_json: (String json_string) -> Base
+
+    # Oj quotes the whole input in its parse-error message, and that input
+    # may be payments data. Re-raise the same class with Oj's description
+    # and position only, and without the original as +cause+ (which error
+    # reporters print).
+    # 
+    # _@param_ `json_string`
+    # 
+    # _@return_ — the parsed JSON value
+    def self.parse_json: (String json_string) -> Object?
+
+    # Walk a parsed JSON hash (string-keyed, possibly with external
+    # names) and reverse-map every key to its canonical Symbol via
+    # +metadata.serialization(:json)+. Recurses into nested
+    # FieldStruct values and arrays of nested. Unmapped keys are
+    # converted to Symbols and passed through — they'll be handled
+    # by +new+'s +unknown_attributes+ check.
+    # 
+    # _@param_ `hash` — parsed JSON object
+    # 
+    # _@return_ — canonical-keyed input ready for +.new+
+    def self.canonicalize_serialized_hash: (::Hash[(String | Symbol), Object?] hash) -> ::Hash[Symbol, Object?]
+
+    # Reverse-map a single serialized value for its field, recursing into
+    # nested FieldStructs and arrays of nested. Companion to
+    # {.canonicalize_serialized_hash}.
+    # 
+    # _@param_ `value` — the parsed JSON value
+    # 
+    # _@param_ `field` — the field it is for; +nil+ for an unknown key
+    # 
+    # _@return_ — +value+, with nested Hashes reverse-mapped
+    def self.canonicalize_serialized_value: (Object? value, Field? field) -> Object?
+
+    # Which external names apply depends on which member the Hash is for,
+    # so try the members in declared order, as {Types::Union#coerce} does:
+    # a struct member gets the Hash reverse-mapped through its own
+    # +serialize :json+ mapping, and the first member that accepts wins. A
+    # winning struct is returned built (the union's coerce passes it
+    # through to that member); a winning non-struct member gets the Hash
+    # unchanged. When nothing accepts it, the Hash goes on as-is and the
+    # setter's +coercion_policy+ handles the failure.
+    # 
+    # _@param_ `hash` — parsed JSON object for a union field
+    # 
+    # _@param_ `union`
+    def self.canonicalize_serialized_union_hash: (::Hash[(String | Symbol), Object?] hash, Types::Union union) -> (Base | ::Hash[(String | Symbol), Object?])
+
+    # _@return_ — the +field_types+ of the nearest enclosing
+    # module that defines one, or +nil+ to fall back to {FieldStruct.types}
+    def self.namespace_field_types: () -> Registry?
+
+    # _@param_ `type_class`
+    # 
+    # _@param_ `options` — the field's declared options
+    # 
+    # _@return_ — for an +:array+ field, +of:+ resolved
+    # into +of_type:+; otherwise +options+ unchanged
+    def self.resolve_array_options: (singleton(Types::Base) type_class, ::Hash[Symbol, Object?] options) -> ::Hash[Symbol, Object?]
+
+    # Check an array field's +element:+ options against the element type's
+    # own schema, exactly as a scalar field of that type is checked, and
+    # store them resolved and frozen. An empty or absent +element:+ leaves
+    # no +:element+ key, so an array without one is unchanged.
+    # 
+    # _@param_ `name` — the field name, for error messages
+    # 
+    # _@param_ `options` — the array field's resolved options
+    # 
+    # _@return_ — +options+ with +:element+ resolved
+    def self.resolve_element_options: ((Symbol | String) name, ::Hash[Symbol, Object?] options) -> ::Hash[Symbol, Object?]
+
+    # _@param_ `element_class` — the array's element type
+    # 
+    # _@param_ `element` — the declared +element:+ options
+    # 
+    # _@return_ — +element+, every key native to +element_class+
+    def self.element_options_checked: (singleton(Types::Base) element_class, ::Hash[Symbol, Object?] element) -> ::Hash[Symbol, Object?]
+
+    # _@param_ `word`
+    # 
+    # _@return_ — +"an"+ before a vowel, otherwise +"a"+
+    def self.article: (String word) -> String
+
+    # _@param_ `type_class`
+    # 
+    # _@param_ `options` — the field's declared options
+    # 
+    # _@return_ — the built union
+    # and the options without +of:+
+    def self.build_union_instance: (singleton(Types::Union) type_class, ::Hash[Symbol, Object?] options) -> [Types::Union, ::Hash[Symbol, Object?]]
+
+    # _@param_ `type_class`
+    # 
+    # _@param_ `options` — the field's declared options
+    # 
+    # _@return_ — +options+ with the type's default
+    # +format:+ added when it has one and none was declared
+    def self.apply_default_format: (singleton(Types::Base) type_class, ::Hash[Symbol, Object?] options) -> ::Hash[Symbol, Object?]
+
+    # Pull +description:+ (canonical) or +desc:+ (alias) out of the
+    # field-declaration options. Raises if both are given — pick one.
+    # 
+    # _@param_ `options` — mutated in place (keys deleted)
+    def self.extract_description!: (::Hash[Symbol, Object?] options) -> String?
+
+    # Three-way option check (design invariant 7): validate native, pass
+    # through foreign. For each declared option:
+    # 
+    # 1. **Native to this type** (in its +option_schema+) → validate the
+    #    value's shape against the descriptor.
+    # 2. **Native to *another* registered type but not this one** → raise,
+    #    naming the types it does apply to (the old "wrong family" errors,
+    #    now schema-driven).
+    # 3. **Not a FieldStruct option at all** → leave it untouched. Foreign
+    #    options persist on the Field for downstream tooling (e.g. an Avro
+    #    schema exporter).
+    # 
+    # _@param_ `type_class`
+    # 
+    # _@param_ `options` — the resolved per-field options
+    def self.validate_options!: (singleton(Types::Base) type_class, ::Hash[Symbol, Object?] options) -> void
+
+    # Every option name FieldStruct treats as its own: the union of every
+    # registered type's native options plus the universal field options.
+    # Anything outside this set is foreign and passes through.
+    # 
+    # _@param_ `registry`
+    def self.reserved_option_names: (Registry registry) -> ::Array[Symbol]
+
+    # _@param_ `type_class` — the field's type
+    # 
+    # _@param_ `key` — the option name
+    # 
+    # _@param_ `value` — the declared option value
+    # 
+    # _@param_ `descriptor` — the option's schema entry
+    def self.validate_option_value!: (
+                                       singleton(Types::Base) type_class,
+                                       Symbol key,
+                                       Object? value,
+                                       ::Hash[Symbol, Object] descriptor
+                                     ) -> void
+
+    # _@param_ `key` — the misapplied option name
+    # 
+    # _@param_ `type_class` — the field's type
+    # 
+    # _@param_ `registry` — the registry the field resolves through
+    # 
+    # _@return_ — the message for a native-elsewhere option, naming
+    # the registered types that do accept it
+    def self.wrong_family_message: (Symbol key, singleton(Types::Base) type_class, Registry registry) -> String
+
+    # _@param_ `type_class` — a type class or an option-value class
+    # 
+    # _@return_ — the unqualified class name (+"Integer"+, not
+    # +"FieldStruct::Types::Integer"+) for readable messages
+    def self.short_type_name: (Module type_class) -> String
+
+    # _@param_ `name` — the field name being declared
+    def self.refuse_reserved_name!: ((Symbol | String) name) -> void
+
+    # _@param_ `name` — the format name
+    # 
+    # _@param_ `mapping` — internal → external names
+    def self.validate_serialize_mapping!: ((Symbol | String) name, ::Hash[Symbol, (String | Symbol)] mapping) -> void
+
+    # _@param_ `value` — the declared field-level +coercion_policy:+
+    def self.validate_coercion_policy_override!: (Object value) -> void
+
+    # _@param_ `value` — the declared +rbs_type:+
+    def self.validate_rbs_type!: (Object value) -> void
+
+    # _@param_ `value` — the declared +sensitive:+
+    def self.validate_sensitive!: (Object value) -> void
+
+    # _@param_ `field`
+    def self.define_field_accessors: (Field field) -> void
+
+    # _@return_ — the registered cross-field validators
+    # for this class. Each entry is a proc that takes the
+    # record. Subclasses start with a +dup+ of the parent's list at
+    # inheritance time and accumulate their own.
+    def self.validators: () -> ::Array[Proc]
+
+    # Declare a cross-field validator.
+    # 
+    #   class Schedule < FieldStruct::Base
+    #     required :start_date, :date
+    #     required :end_date,   :date
+    # 
+    #     validate :ensure_chronological
+    #     validate do |record|
+    #       record.errors.add(:base, '...') if record.something_else?
+    #     end
+    # 
+    #     def ensure_chronological
+    #       return unless start_date && end_date
+    # 
+    #       errors.add(:base, 'end_date must not precede start_date') if start_date > end_date
+    #     end
+    #   end
+    # 
+    # Multiple symbols can be passed in a single call. Method-symbol
+    # and block forms are interchangeable — the symbol form is sugar
+    # for +validate { |r| r.send(:name) }+. Validators run on every
+    # call to {#valid?}, in declaration order, after per-field
+    # validation.
+    # 
+    # Per convention, validators add errors via
+    # +record.errors.add(:base, '...')+ — +errors[:base]+ is cleared
+    # at the start of each {#valid?} run, so prior cross-field errors
+    # don't pile up. Adding to a field-specific key bypasses that
+    # auto-clearing; the user is then responsible for clearing those
+    # entries.
+    # 
+    # _@param_ `method_names` — zero or more instance method names to invoke on each record at +valid?+ time
+    def self.validate: (*Symbol method_names) ?{ (Base record) -> void } -> self
+
+    # Ruby hook: give each subclass its own metadata seeded from the
+    # parent's (merged copy) plus inherited macro settings, so field
+    # declarations and config flow down the class chain.
+    # 
+    # _@param_ `subclass`
+    def self.inherited: (singleton(Base) subclass) -> void
+
+    # _@param_ `attrs` — input values, by symbol or string key. Anything responding to +to_hash+ (e.g. a permitted +ActionController::Parameters+) is converted first; +nil+ is treated as no input.
+    def initialize: (?(::Hash[(Symbol | String), Object?] | _ToHash[untyped, untyped])? attrs) -> void
+
+    # Bulk-update declared attributes from a hash. Routes each value
+    # through the same setter pipeline used everywhere else — so coercion,
+    # presence checks, and the +coercion_policy+ all run as normal.
+    # 
+    # Respects {.unknown_attributes} on input and {.immutable?} on the
+    # setter side. Keys must match declared field names. For data arriving
+    # in an external naming convention, see {Base.serialize} and
+    # {Base.from_json}.
+    # 
+    # _@param_ `attrs` — anything responding to +to_hash+ is converted first
+    def assign_attributes: ((::Hash[(Symbol | String), Object?] | _ToHash[untyped, untyped]) attrs) -> self
+
+    # A new instance with the given attributes changed; the receiver is left
+    # untouched. Like +Data#with+.
+    # 
+    #   moved = person.with(city: 'Provo', zip: '84601')
+    # 
+    # Changed fields run through the normal setter pipeline (coercion, the
+    # field's +coercion_policy+, its errors rewritten), then cross-field
+    # validators rerun. Unchanged fields are carried over exactly as they
+    # are, errors included, and callable defaults are not called again.
+    # The copy is shallow, as with +dup+: an unchanged nested struct or
+    # array is the same object in both. Unknown keys follow
+    # {.unknown_attributes}. Works on +immutable!+ and frozen instances;
+    # the copy is an instance of the receiver's class, immutable when the
+    # class is, and frozen when the receiver is.
+    # 
+    # _@param_ `positional` — refused — changes are keywords only
+    # 
+    # _@param_ `changes` — new values, by field name
+    # 
+    # _@return_ — a new instance of the receiver's class
+    def with: (*Object positional, **Object? changes) -> Base
+
+    # _@return_ — a fresh hash of current attribute values
+    # keyed by canonical field name. For format-aware export (with the
+    # declared +:json+ mapping applied), see {#as_json} / {#to_json}.
+    def attributes: () -> ::Hash[Symbol, Object?]
+
+    def attribute_names: () -> ::Array[Symbol]
+
+    # _@return_ — the per-instance error collection
+    def errors: () -> Errors
+
+    # Run the class's cross-field validators (if any), then report
+    # whether the record has any errors.
+    # 
+    # Each call clears +errors[:base]+ before running validators, so
+    # cross-field errors don't accumulate across calls. Field-level
+    # errors written by setters are NOT cleared by +valid?+ — Phase 1's
+    # "setter owns its field's errors" contract is preserved.
+    # 
+    # For classes that declare no +validate+ blocks, +valid?+ stays a
+    # cheap +errors.empty?+ read.
+    def valid?: () -> bool
+
+    # _@return_ — true when {#valid?} is false
+    def invalid?: () -> bool
+
+    # Structural equality: same class AND same {#attributes}. Errors are
+    # ignored — equality is about value, not validity.
+    # 
+    # _@param_ `other`
+    def ==: (Object other) -> bool
+
+    # _@return_ — consistent with {#==} so instances work as Hash
+    # keys and Set members
+    def hash: () -> Integer
+
+    # _@return_ — alias of {#attributes}
+    def to_h: () -> ::Hash[Symbol, Object?]
+
+    # _@param_ `_options` — unused — accepted for ActiveSupport-style symmetry
+    # 
+    # _@return_ — a JSON-ready hash with the
+    # +:json+ serialize mapping applied. Date/Time/DateTime convert
+    # to ISO-8601 strings, BigDecimal to its plain-form string,
+    # Symbol to String. Arrays recurse. Nested FieldStructs walk
+    # through their own +as_json+, applying their own mapping.
+    # Covers exactly the declared fields, each read through its reader
+    # (as {#attributes} reads them) in one pass; an override of
+    # {#attributes} does not change it.
+    def as_json: (?Object? _options) -> ::Hash[Symbol, Object?]
+
+    # _@param_ `_options` — unused — accepted for ActiveSupport-style symmetry
+    # 
+    # _@return_ — JSON representation, via Oj
+    def to_json: (?Object? _options) -> String
+
+    # Readable representation. Valid instances render as
+    # +#<ClassName field: value, ...>+. An *invalid* instance additionally
+    # surfaces its errors — +#<ClassName name: "" errors: {name: ["is
+    # required"]}>+ — so the most-read debug output never hides invalidity
+    # (design invariant 7). This reads the current {#errors}; it does not
+    # re-run validation, so printing an instance never mutates it.
+    # 
+    # A +sensitive: true+ field renders {FieldStruct::FILTERED} in place of
+    # a non-nil value (+nil+ still shows, so a missing value stays visible).
+    # +pp+ goes through here too.
+    def inspect: () -> String
+
+    def model_name: () -> ModelName
+
+    # _@return_ — for ActiveModel-shaped helpers that call .to_model
+    def to_model: () -> self
+
+    # Ruby pattern-matching hash protocol. Returns the declared field
+    # values keyed by canonical name, sliced down to +keys+ if the
+    # pattern asked for specific ones.
+    # 
+    #   case user
+    #   in { name: 'Alice', age: }
+    #     ...
+    #   in { name: String => name }
+    #     ...
+    #   end
+    # 
+    # Nested FieldStruct values respond to the same protocol, so deep
+    # patterns (+{ address: { city: 'NYC' } }+) work without extra code.
+    # Aliases (per the field-name aliases feature) do *not* participate;
+    # pattern matching uses canonical names, the same as Ruby-side
+    # accessors.
+    # 
+    # _@param_ `keys` — keys the pattern requested, or +nil+ for the +**rest+ pattern (every declared field)
+    def deconstruct_keys: (::Array[Symbol]? keys) -> ::Hash[Symbol, Object?]
+
+    # Ruby pattern-matching array protocol. Returns the declared field
+    # values in declaration order — useful for positional unpacking of
+    # small POROs whose field order is meaningful.
+    # 
+    #   class Point < FieldStruct::Base
+    #     required :x, :integer
+    #     required :y, :integer
+    #   end
+    # 
+    #   case point
+    #   in [x, y]
+    #     Math.hypot(x, y)
+    #   end
+    def deconstruct: () -> ::Array[Object?]
+
+    # Ruby hook behind +dup+ / +clone+: give the copy its own {Errors},
+    # seeded with the original's messages, so validating or reassigning
+    # one instance never changes the other's validity.
+    # 
+    # _@param_ `source` — the instance being copied
+    def initialize_copy: (self source) -> void
+
+    # Return +attrs+ as a Hash, converting via +to_hash+ when it isn't one.
+    # The message names the input's class, never its value.
+    # 
+    # _@param_ `attrs` — the caller's input
+    # 
+    # _@param_ `method_label` — the public method, for the message
+    def hash_input!: (Object? attrs, String method_label) -> ::Hash[(Symbol | String), Object?]
+
+    # _@param_ `value` — a field value, or an element inside one
+    # 
+    # _@param_ `field` — the field it belongs to, for its +format:+
+    # 
+    # _@return_ — a JSON-ready value for Oj
+    def json_value: (Object? value, ?Field? field) -> Object?
+
+    # A declared +format:+ is now stored as written, so a preset name has to be
+    # expanded before strftime sees it — and only the field's own type knows
+    # its preset table. An :array field's elements use the +format:+ in its
+    # +element:+ options, read through the element type, so +from_json+ reads
+    # back what +to_json+ wrote. With no declared format (an :array without
+    # one, a :value field holding a date) the answer is ISO-8601, as it has
+    # always been.
+    # 
+    # _@param_ `value`
+    # 
+    # _@param_ `field`
+    def temporal_json_value: ((::Date | ::Time | ::DateTime) value, Field? field) -> String
+
+    # _@param_ `field`
+    # 
+    # _@return_ — the
+    # options holding the +format:+ for this field's temporal values and
+    # the type class that resolves it — an array's +element:+ options and
+    # element type, or the field's own
+    def temporal_format_source: (Field? field) -> ([::Hash[Symbol, Object?], Class] | [NilClass, Class] | [NilClass, NilClass])
+
+    # Give every field its default, through the setter. A field with no
+    # default whose key +attrs+ carries only gets its ivar (so the ivar order
+    # stays the declaration order): the assignment that follows runs its
+    # setter, so a nil pass first would only be undone.
+    # 
+    # _@param_ `attrs` — the input about to be assigned
+    def apply_defaults: (::Hash[(Symbol | String), Object?] attrs) -> void
+
+    def run_cross_field_validators: () -> void
+
+    # _@param_ `attrs`
+    def reject_unknown_attributes!: (::Hash[(Symbol | String), Object?] attrs) -> void
+
+    # _@param_ `field`
+    # 
+    # _@param_ `value` — the coerced value just stored
+    def validate_field: (Field field, Object? value) -> void
+
+    # _@param_ `field`
+    # 
+    # _@param_ `value` — a present (non-missing) coerced value
+    def field_value_invalid?: (Field field, Object? value) -> bool
+
+    # Whether +value+ breaks a +format:+ Regexp, +enum:+ or +in:+ in +options+.
+    # 
+    # _@param_ `options` — a field's options, or an array field's +element:+ options
+    # 
+    # _@param_ `value` — a present coerced value
+    def outside_options?: (::Hash[Symbol, Object?] options, Object? value) -> bool
+
+    # _@param_ `field`
+    # 
+    # _@param_ `value` — a present coerced value
+    # 
+    # _@return_ — the indexes of every non-nil element
+    # that breaks the array field's +element:+ +format:+ / +enum:+ / +in:+,
+    # or +nil+ when there is none (or the field declares no +element:+)
+    def invalid_element_indexes: (Field field, Object? value) -> ::Array[Integer]?
+
+    # `in:` with a Range means a BOUNDS check, so ask the Range for its bounds.
+    # 
+    # Range#include? ENUMERATES a non-numeric range rather than comparing
+    # endpoints. For a Date range that is merely wasteful — 365 successor steps
+    # to answer one comparison. For a DateTime range it is wrong: the range
+    # steps by whole days, so a value that isn't exactly midnight is reported
+    # outside a range that plainly contains it.
+    # 
+    #   (DateTime.new(2026, 1, 1)..DateTime.new(2026, 12, 31))
+    #     .include?(DateTime.new(2026, 7, 3, 10, 30))  # => false
+    #     .cover?(DateTime.new(2026, 7, 3, 10, 30))    # => true
+    # 
+    # An Array stays a membership test. There is no string-range case to worry
+    # about: the DSL refuses `in:` on String fields outright.
+    # 
+    # _@param_ `allowed` — the field's +in:+ option (an Array for the stock types; a custom type may declare another)
+    # 
+    # _@param_ `value`
+    def within_allowed?: ((::Range[Object] | ::Enumerable[Object]) allowed, Object? value) -> bool
+
+    # _@param_ `value`
+    # 
+    # _@return_ — whether +value+ is, or is an Array holding, an
+    # invalid FieldStruct
+    def nested_invalid?: (Object? value) -> bool
+
+    # _@param_ `field`
+    # 
+    # _@param_ `raw_value` — the value that failed to coerce
+    # 
+    # _@param_ `error` — what the type raised
+    # 
+    # _@return_ — what the setter stored: +raw_value+ under
+    # +:keep_raw+, +nil+ under +:replace+
+    def apply_coercion_policy: (Field field, Object? raw_value, StandardError error) -> Object?
+
+    # _@param_ `field`
+    # 
+    # _@param_ `stored_value` — what to store in the field
+    # 
+    # _@param_ `error` — what the type raised
+    def record_coercion_failure: (Field field, Object? stored_value, StandardError error) -> void
+  end
+
+  # Base class for every error FieldStruct raises. Catch this to handle
+  # any library error generically.
+  class Error < StandardError
+  end
+
+  # Raised by the setter pipeline when a value cannot be coerced into a
+  # field's declared type and the class's +coercion_policy+ is +:raise+.
+  # 
+  # Carries the field name and the original underlying error for callers
+  # that want to inspect what happened.
+  class CoercionError < FieldStruct::Error
+    # _@param_ `message`
+    # 
+    # _@param_ `field_name`
+    # 
+    # _@param_ `original`
+    def initialize: (String message, ?field_name: Symbol?, ?original: StandardError?) -> void
+
+    # _@return_ — the field whose setter triggered the failure
+    attr_reader field_name: Symbol?
+
+    # _@return_ — the underlying error from the type's coerce
+    attr_reader original: StandardError?
+  end
+
+  # Raised when a field setter on a class marked +immutable!+ is called
+  # after construction.
+  class ImmutableError < FieldStruct::Error
+  end
+
+  # Raised by {Base#initialize} / {Base#assign_attributes} when the input
+  # hash includes a key that is not a declared field on the class and
+  # the +unknown_attributes+ policy is +:raise+.
+  class UnknownAttributeError < FieldStruct::Error
+    # _@param_ `message`
+    # 
+    # _@param_ `keys`
+    def initialize: (String message, ?keys: ::Array[Symbol]) -> void
+
+    # _@return_ — the offending keys
+    attr_reader keys: ::Array[Symbol]
+  end
+
+  # A single declared attribute on a FieldStruct class.
+  # 
+  # Holds the field's name, the resolved type class, whether it's
+  # required, an optional default, and any remaining keyword options
+  # (e.g. +format:+). Frozen after construction — the DSL is expected
+  # to build a fresh Field rather than mutate one.
+  class Field
+    # _@param_ `name` — canonical field name
+    # 
+    # _@param_ `type` — the resolved type class
+    # 
+    # _@param_ `type_instance` — optional pre-built instance — used by the DSL for parameterized types (e.g. {Types::Nested}) where +type.new+ wouldn't be enough to capture the parameterization. When nil, +type.new+ is called.
+    # 
+    # _@param_ `required`
+    # 
+    # _@param_ `default` — literal default value, or a parameterless callable (Proc/Lambda/Method) that returns one. Callables are invoked once per instance during apply_defaults.
+    # 
+    # _@param_ `coercion_policy` — override the class-level coercion policy for this one field; +nil+ means "use whatever the class says"
+    # 
+    # _@param_ `description` — human-readable description of the field; for documentation purposes only
+    # 
+    # _@param_ `rbs_type` — RBS type expression overriding the derived one in generated signatures (see {#rbs_type})
+    # 
+    # _@param_ `sensitive` — mask the value in {Base#inspect} (see {#sensitive?})
+    # 
+    # _@param_ `options` — extra keyword type/field options forwarded to coerce (e.g. +format:+, +of_type:+, +round:+, +values:+, +enum:+, +in:+)
+    def initialize: (
+                      name: (Symbol | String),
+                      _type: singleton(Types::Base),
+                      ?type_instance: Types::Base?,
+                      ?required: bool,
+                      ?default: Object?,
+                      ?coercion_policy: Symbol?,
+                      ?description: String?,
+                      ?rbs_type: String?,
+                      ?sensitive: bool,
+                      **Object? options
+                    ) -> void
+
+    def required?: () -> bool
+
+    # Whether the field holds data that must not reach a log — a card
+    # number, a CVV, a token. {Base#inspect} (and so +pp+) renders
+    # {FieldStruct::FILTERED} in place of a non-nil value. Data paths —
+    # the reader, +attributes+, +to_h+, +as_json+, +to_json+, pattern
+    # matching — return the real value, so round-trips stay exact.
+    # Declared with the +sensitive:+ field option.
+    def sensitive?: () -> bool
+
+    # Concise one-line representation. Designed to be readable in IRB
+    # without dumping every ivar (the default Object#inspect is the
+    # reason +optional :x, :string+ in a console looks like a wall of
+    # text).
+    def inspect: () -> String
+
+    # Delegates pretty-print to {#inspect} so IRB / pp don't fall back
+    # to the default reflection-based output.
+    # 
+    # _@param_ `pp` — a PP-shaped sink (responds to +#text+)
+    def pretty_print: (Object pp) -> void
+
+    # _@return_ — the type's short name, or +Nested(...)+ / +Union(...)+
+    def type_repr: () -> String
+
+    # Render an option's value in inspect output. Type-class values
+    # (e.g. +:of_type+ on an Array field) get their basename instead
+    # of the full +FieldStruct::Types::String+ class.inspect.
+    # 
+    # _@param_ `value` — an option value
+    def option_repr: (Object? value) -> String
+
+    # _@return_ — canonical field name
+    attr_reader name: Symbol
+
+    # _@return_ — the resolved type class
+    attr_reader type: singleton(Types::Base)
+
+    # _@return_ — the configured default value, or a
+    # parameterless callable returning one, or +nil+ if no default
+    attr_reader default: (Object | untyped)?
+
+    # _@return_ — frozen, holds the remaining keyword
+    # options forwarded to {Types::Base#coerce} (e.g. +:format+,
+    # +:round+, +:values+, +:of_type+, +:enum+, +:in+)
+    attr_reader options: ::Hash[Symbol, Object?]
+
+    # _@return_ — an eagerly-built instance of {#type}, reused by
+    # the setter pipeline so we don't allocate a fresh type per coercion
+    attr_reader type_instance: Types::Base
+
+    # _@return_ — this field's coercion-
+    # failure policy override, or +nil+ to defer to the class-level
+    # setting on {Base.coercion_policy}.
+    attr_reader coercion_policy: Symbol?
+
+    # _@return_ — human-readable description of the field;
+    # intended for downstream documentation generators. Not part of
+    # the data surface — does not appear in +attributes+ / +as_json+ /
+    # pattern matches.
+    attr_reader description: String?
+
+    # _@return_ — an RBS type expression that {RBS.generate} and
+    # {RBS.type_for} emit for this field instead of deriving one from the
+    # type (e.g. +"::ActiveRecord::Relation"+ on a +:value+ field), or
+    # +nil+ to derive it. Declared with the +rbs_type:+ field option;
+    # signatures only — it never affects coercion or validation.
+    attr_reader rbs_type: String?
+
+    # _@return_ — the setter's method name (+:name=+), built once here
+    # so the setter pipeline doesn't intern a dynamic Symbol per call
+    attr_reader setter_name: Symbol
+
+    # _@return_ — the instance variable holding the value (+:@name+),
+    # built once for the same reason as {#setter_name}
+    attr_reader ivar_name: Symbol
+  end
+
+  # Per-instance collection of validation messages, keyed by field name.
+  # 
+  # Shaped after ActiveModel::Errors but reuses none of its code. Each
+  # FieldStruct instance gets its own Errors object; the setter pipeline
+  # clears and rewrites a field's entry on every assignment.
+  class Errors
+    def initialize: () -> void
+
+    # Ruby hook behind +dup+ / +clone+: copy the message lists too, so
+    # adding to the copy never changes the original.
+    # 
+    # _@param_ `source` — the collection being copied
+    def initialize_copy: (self source) -> void
+
+    # _@param_ `field_name`
+    # 
+    # _@return_ — messages for the field, or an empty array
+    def []: ((Symbol | String) field_name) -> ::Array[String]
+
+    # _@param_ `field_name`
+    # 
+    # _@param_ `message`
+    # 
+    # _@return_ — the field's updated message list
+    def add: ((Symbol | String) field_name, String message) -> ::Array[String]
+
+    # Drop every message for a field.
+    # 
+    # _@param_ `field_name`
+    def clear: ((Symbol | String) field_name) -> void
+
+    # _@return_ — true when no field has any messages
+    def empty?: () -> bool
+
+    # _@return_ — snapshot of field → messages,
+    # skipping fields with empty message lists
+    def to_h: () -> ::Hash[Symbol, ::Array[String]]
+
+    # Every message rendered as a full, human-readable sentence: the
+    # humanized field name prepended to each message. Messages on +:base+
+    # (the cross-field convention) pass through unprefixed — they are
+    # already complete sentences. Order follows field insertion order, then
+    # message order within a field.
+    # 
+    #   errors.add(:first_name, 'is required')
+    #   errors.full_messages   # => ["First name is required"]
+    def full_messages: () -> ::Array[String]
+
+    def inspect: () -> String
+
+    # Turn a field name into a display label for {#full_messages}:
+    # underscores become spaces and the first character is upcased.
+    # Deliberately minimal — no inflection, no +_id+ stripping, no i18n.
+    # 
+    # _@param_ `field`
+    def humanize: (Symbol field) -> String
+  end
+
+  # The per-class collection of {Field} declarations.
+  # 
+  # Mutable while a class is being defined — the DSL adds fields as it
+  # encounters them — and queried thereafter by name or via iteration.
+  # Subclass inheritance is handled by {#merge}: a fresh child Metadata
+  # is seeded with the parent's fields, then accumulates its own; child
+  # declarations win on conflict.
+  class Metadata
+    include ::Enumerable[Field]
+    EMPTY_SERIALIZATION: ::Hash[Symbol, String]
+
+    def initialize: () -> void
+
+    # _@param_ `field`
+    def add: (Field field) -> self
+
+    # _@param_ `name`
+    def []: ((Symbol | String) name) -> Field?
+
+    # _@return_ — field names in insertion order
+    def names: () -> ::Array[Symbol]
+
+    # Yields each {Field} in insertion order.
+    # 
+    # _@return_ — when no block is given
+    def each: () ?{ (Field field) -> void } -> ::Enumerator[Field]
+
+    # A copy-pasteable schema view of the declared fields, keyed by field
+    # name. Each value is a plain Hash of primitives/strings (no live type
+    # objects), so the result reads cleanly in a console and is safe to
+    # `pp` or dump — handy for seeing a model's shape without reading its
+    # source. Option values that are classes or type instances are rendered
+    # as short names; a callable default shows as +"<callable>"+.
+    # 
+    #   User.metadata.to_h
+    #   # => { name: { type: "String", ruby_type: "String", required: true,
+    #   #              default: nil, options: {}, description: nil }, ... }
+    # 
+    # When a block is given this falls back to +Enumerable#to_h+ (mapping
+    # each {Field} to a pair), preserving existing callers.
+    # 
+    # _@return_ — field name → schema, or
+    # the block-mapped pairs when a block is supplied
+    def to_h: () -> ::Hash[Symbol, ::Hash[Symbol, Object?]]
+
+    # Record a serialization mapping for the named format. Repeats on
+    # the same format name replace the prior mapping (last-write-wins).
+    # The mapping is frozen on its way in.
+    # 
+    # _@param_ `name`
+    # 
+    # _@param_ `mapping`
+    def add_serialization: ((Symbol | String) name, ::Hash[Symbol, String] mapping) -> self
+
+    # Look up the mapping for a format. Returns an empty hash when the
+    # format hasn't been declared — the implicit identity mapping that
+    # serializers fall back to.
+    # 
+    # _@param_ `name`
+    # 
+    # _@return_ — frozen mapping (empty hash when undeclared)
+    def serialization: ((Symbol | String) name) -> ::Hash[Symbol, String]
+
+    # The reverse of {#serialization}: external name → field name, which
+    # {Base.from_json} needs on every call. Built once per mapping and reused
+    # while {#serialization} still returns that same frozen mapping, so any
+    # writer that installs a new one ({#add_serialization}, {#merge}, or a
+    # direct write to {#serializations}) is picked up on the next call.
+    # 
+    # _@param_ `name`
+    # 
+    # _@return_ — frozen; empty when the format is undeclared
+    def reverse_serialization: ((Symbol | String) name) -> ::Hash[String, Symbol]
+
+    # Copy fields and serializations from +parent+ into self, leaving
+    # already-declared entries untouched (child wins). Order: existing
+    # self fields stay where they are; parent fields are appended in
+    # iteration order if not present.
+    # 
+    # _@param_ `parent`
+    def merge: (Metadata parent) -> self
+
+    # Concise one-line representation. Lists the declared field names
+    # and, when present, the declared serialization formats — without
+    # dumping the underlying ivar hashes.
+    def inspect: () -> String
+
+    # Multi-line representation suitable for IRB / pp. Renders each
+    # field on its own indented line using {Field#inspect}, with the
+    # closing +>+ on its own line.
+    # 
+    # _@param_ `pp` — a PP-shaped sink (responds to +#text+)
+    def pretty_print: (Object pp) -> void
+
+    # Human/agent-readable summary of the declared fields: one line each
+    # with the field's type, required-ness, and the native options its type
+    # accepts (with value shapes, required options starred, and any presets).
+    # Answers "what can I put here?" without reading source. For the
+    # structured form use {#to_h}; for a class-titled version use
+    # {Base.describe}.
+    # 
+    #   name (String, required) — accepts format (Regexp | Symbol), enum (Array)
+    def describe: () -> String
+
+    # _@param_ `field`
+    # 
+    # _@return_ — one +describe+ line for a field
+    def describe_field: (Field field) -> String
+
+    # What this field actually declares, as written.
+    # 
+    # Without this, +describe+ answered only "what COULD go in this field" —
+    # the type's option vocabulary — and a field declaring
+    # +format: :iso8601, enum: %w[USD EUR]+ rendered identically to one
+    # declaring nothing at all. The option schema belongs to the type; this
+    # belongs to the field.
+    # 
+    # _@param_ `field`
+    # 
+    # _@return_ — +nil+ when the field declares no options
+    def declared_options_summary: (Field field) -> String?
+
+    # _@param_ `value` — a declared option value
+    # 
+    # _@return_ — a declared option value, rendered for a human. Type
+    # values (an Array field's +of_type:+) show their bare type name rather
+    # than a quoted string, so the line reads like the declaration it
+    # describes.
+    def declared_option_repr: (Object? value) -> String
+
+    # What an array field's +element:+ may hold — the names of its element
+    # type's native options — so the line answers "what can I pass to each
+    # element" too.
+    # 
+    # _@param_ `field`
+    # 
+    # _@return_ — +nil+ for a non-array field, or an element type
+    # with no options (a nested struct)
+    def element_accepts_summary: (Field field) -> String?
+
+    # _@param_ `type_class`
+    # 
+    # _@return_ — the type's native option vocabulary, or +nil+ when
+    # the type declares none
+    def accepts_summary: (singleton(Types::Base) type_class) -> String?
+
+    # _@param_ `type_class`
+    # 
+    # _@return_ — the type's native options as +name(shapes)+, required
+    # ones starred, presets appended — empty when the type has none
+    def native_options_summary: (singleton(Types::Base) type_class) -> String
+
+    # Render one field as a primitive-only schema Hash for {#to_h}.
+    # 
+    # _@param_ `field`
+    def field_schema: (Field field) -> ::Hash[Symbol, Object?]
+
+    # A single class, or +A | B+ for a multi-class ruby_type (boolean, union).
+    # 
+    # _@param_ `ruby_type` — a type's {Types::Base#ruby_type}
+    def ruby_type_repr: ((Class | ::Array[Class]) ruby_type) -> String
+
+    # Reduce an option/default value to something printable: short class
+    # names for type references, +"<callable>"+ for procs, recursion into
+    # Array/Hash, everything else as-is.
+    # 
+    # _@param_ `value` — an option or default value
+    def schema_value: (Object? value) -> Object?
+
+    # _@param_ `klass`
+    # 
+    # _@return_ — the last segment of the class name
+    def short_name: (Module klass) -> String
+
+    # _@return_ — declared
+    # external-name mappings keyed by format name. Each inner hash
+    # maps an internal field name (Symbol) to its external name
+    # (String). Fields not listed in an inner hash serialize under
+    # their canonical name.
+    attr_reader serializations: ::Hash[Symbol, ::Hash[Symbol, String]]
+  end
+
+  # Name → type-class map with optional parent fallback.
+  # 
+  # Holds the resolution table that maps symbolic type names (`:string`,
+  # `:integer`, …) to the {Types} classes that implement them. A namespace
+  # can build its own registry parented to the base ({FieldStruct.types})
+  # to extend or override the default set without mutating it.
+  class Registry
+    # _@param_ `parent` — the registry to fall back to when a name isn't found locally
+    def initialize: (?Registry? parent) -> void
+
+    # Register a type class — or an alias to an already-registered name.
+    # 
+    #   registry.register(:integer, MyInteger)        # type class
+    #   registry.register(:decimal, :big_decimal)     # alias (resolved now)
+    # 
+    # Aliases are eagerly resolved through {#lookup}, so the alias target
+    # must already be registered (locally or in a parent). A later
+    # registration of the same name overwrites silently — this is the
+    # mechanism that lets a namespace registry shadow a parent's type.
+    # 
+    # _@param_ `name` — the name to register
+    # 
+    # _@param_ `target` — a type class, or an existing registered name
+    def register: ((Symbol | String) name, (Class | Symbol) target) -> self
+
+    # Resolve a name to its type class, walking the parent chain.
+    # 
+    # _@param_ `name`
+    # 
+    # _@return_ — the type class
+    def lookup: ((Symbol | String) name) -> Class
+
+    # Whether the name resolves to anything (locally or via the parent chain).
+    # 
+    # _@param_ `name`
+    def key?: ((Symbol | String) name) -> bool
+
+    # Every distinct type class resolvable through this registry, including
+    # those inherited from the parent chain. Local entries come first;
+    # duplicates (e.g. an alias pointing at an already-listed class, or a
+    # parent class also registered locally) are removed.
+    # 
+    # _@return_ — deduplicated, local-first
+    def type_classes: () -> ::Array[Class]
+
+    # _@return_ — one-line summary of the locally-registered names
+    # (does not enumerate the parent chain), with a +parent+ marker
+    # when the registry has one
+    def inspect: () -> String
+
+    # _@return_ — the parent registry, or +nil+ for an unparented one
+    attr_reader parent: Registry?
+  end
+
+  # Scaffolds FieldStruct class source from one or more JSON example objects.
+  # 
+  # The goal is a *working prototype* you then refine by hand — the generator
+  # is deliberately conservative about types and never guesses past the
+  # evidence. Pass a single object to seed the shape, or an array of
+  # same-shape objects to gather more signal (empty fields get resolved from
+  # other samples, presence drives required/optional, and small repeated
+  # vocabularies surface as enum candidates). A single object is just the
+  # one-sample case of the same engine.
+  # 
+  #   FieldStruct::Scaffold.from_json(<<~JSON, class_name: 'User')
+  #     {"name": "Al", "age": 30, "active": true}
+  #   JSON
+  #   # class User < FieldStruct::Base
+  #   #   required :name, :string
+  #   #   required :age, :integer
+  #   #   required :active, :boolean
+  #   # end
+  # 
+  # Inference rules (conservative on purpose):
+  # 
+  # * JSON object → a nested FieldStruct class (emitted before its parent).
+  # * JSON array → +:array, of: <element type>+ (element class for arrays of objects).
+  # * JSON +true+/+false+ → +:boolean+; integer → +:integer+; real → +:float+.
+  # * JSON string → +:string+ — *including numeric-looking strings* (an
+  #   +authorization_code+ must not become an Integer). Hints like "maybe
+  #   :big_decimal" are emitted as trailing comments, not committed types.
+  # * required when present and non-blank across *every* sample; else optional.
+  # 
+  # The developer adds enums, descriptions, formats, and final scalar types;
+  # the comments point at where.
+  module Scaffold
+    NUMERIC_STRING: Regexp
+    ENUM_MAX_DISTINCT: Integer
+    RESERVED: ::Array[String]
+
+    # Generate FieldStruct class source from JSON example(s).
+    # 
+    # _@param_ `input` — a JSON string (object or array root), a parsed Hash, or an Array of same-shape Hashes
+    # 
+    # _@param_ `class_name` — the root class name
+    # 
+    # _@return_ — Ruby source defining the class and any nested classes
+    def self.from_json: ((String | ::Hash[Object, Object?] | ::Array[::Hash[Object, Object?]]) input, ?class_name: String) -> String
+
+    # _@param_ `input`
+    # 
+    # _@return_ — the sample set (a lone object becomes a set of
+    # one); {.from_json} checks every element is a Hash
+    def self.normalize: ((String | ::Hash[Object, Object?] | ::Array[::Hash[Object, Object?]]) input) -> ::Array[Object]
+
+    # Build the class for +samples+ as +class_name+, appending nested classes
+    # to +classes+ first (post-order, so references resolve), and return the
+    # (deduplicated) class name used.
+    # 
+    # _@param_ `class_name` — the name wanted
+    # 
+    # _@param_ `samples`
+    # 
+    # _@param_ `classes` — class sources emitted so far (appended to)
+    # 
+    # _@param_ `used` — class names taken so far (appended to)
+    def self.emit_object: (
+                            String class_name,
+                            ::Array[::Hash[Object, Object?]] samples,
+                            ::Array[String] classes,
+                            ::Array[String] used
+                          ) -> String
+
+    # _@param_ `samples`
+    # 
+    # _@param_ `key` — a sample key
+    # 
+    # _@return_ — +{ present: Integer, values: Array }+
+    # for +key+ across samples
+    def self.observe: (::Array[::Hash[Object, Object?]] samples, Object key) -> ::Hash[Symbol, (Integer | ::Array[Object?])]
+
+    # _@param_ `attr` — the attribute name
+    # 
+    # _@param_ `obs` — from {.observe}
+    # 
+    # _@param_ `total` — the sample count
+    # 
+    # _@param_ `classes` — class sources emitted so far
+    # 
+    # _@param_ `used` — class names taken so far
+    # 
+    # _@return_ — the indented DSL line
+    def self.field_line: (
+                           String attr,
+                           ::Hash[Symbol, (Integer | ::Array[Object?])] obs,
+                           Integer total,
+                           ::Array[String] classes,
+                           ::Array[String] used
+                         ) -> String
+
+    # _@param_ `attr` — the attribute name
+    # 
+    # _@param_ `non_nil` — the attribute's non-nil sample values
+    # 
+    # _@param_ `classes` — class sources emitted so far
+    # 
+    # _@param_ `used` — class names taken so far
+    # 
+    # _@return_ — +[type_part, comment_hint]+
+    def self.type_for: (
+                         String attr,
+                         ::Array[Object] non_nil,
+                         ::Array[String] classes,
+                         ::Array[String] used
+                       ) -> [String, String]
+
+    # _@param_ `attr` — the attribute name
+    # 
+    # _@param_ `elements` — every element of the attribute's arrays
+    # 
+    # _@param_ `classes` — class sources emitted so far
+    # 
+    # _@param_ `used` — class names taken so far
+    # 
+    # _@return_ — +of:+ value and a comment hint
+    def self.array_element: (
+                              String attr,
+                              ::Array[Object?] elements,
+                              ::Array[String] classes,
+                              ::Array[String] used
+                            ) -> [String, String]
+
+    # _@param_ `values` — non-nil scalar sample values
+    # 
+    # _@return_ — inferred scalar type and a comment hint
+    def self.infer_scalar: (::Array[Object] values) -> [Symbol, String]
+
+    # _@param_ `values`
+    # 
+    # _@return_ — +:string+ and a comment hint
+    def self.string_inference: (::Array[String] values) -> [Symbol, String]
+
+    # _@param_ `value`
+    # 
+    # _@return_ — +:boolean+, +:integer+, +:float+, +:string+ or +:other+
+    def self.scalar_kind: (Object value) -> Symbol
+
+    # +serialize+ refuses undeclared fields, so the mapping goes after them.
+    # 
+    # _@param_ `name` — the class name
+    # 
+    # _@param_ `mappings` — attribute name → original sample key
+    # 
+    # _@param_ `lines` — the field lines
+    # 
+    # _@return_ — the class source
+    def self.build_class: (String name, ::Hash[String, Object] mappings, ::Array[String] lines) -> String
+
+    # _@param_ `declaration` — the DSL call, without indentation
+    # 
+    # _@param_ `comment_parts` — trailing-comment fragments; nil and empty ones are dropped
+    # 
+    # _@return_ — the indented line, with a +#+ comment when any part remains
+    def self.decorate: (String declaration, *String? comment_parts) -> String
+
+    # _@param_ `present` — samples holding the key
+    # 
+    # _@param_ `total` — the sample count
+    # 
+    # _@param_ `missing` — nil or blank values among them
+    def self.availability_comment: (Integer present, Integer total, Integer missing) -> String?
+
+    # First-seen union of keys across all samples.
+    # 
+    # _@param_ `samples`
+    def self.ordered_keys: (::Array[::Hash[Object, Object?]] samples) -> ::Array[Object]
+
+    # _@param_ `base` — the name wanted
+    # 
+    # _@param_ `used` — names taken so far (appended to)
+    # 
+    # _@return_ — +base+, or +base+ with a numeric suffix
+    def self.unique_name: (String base, ::Array[String] used) -> String
+
+    # _@param_ `key` — an attribute name
+    # 
+    # _@return_ — a constant-safe class name
+    def self.class_name_for: (String key) -> String
+
+    # _@param_ `str`
+    def self.camelize: (String str) -> String
+
+    # Naive: strip one trailing "s". Good enough for a prototype name; the
+    # developer renames as needed.
+    # 
+    # _@param_ `str`
+    def self.singularize: (String str) -> String
+
+    # _@param_ `key` — a sample key
+    # 
+    # _@return_ — a snake_case attribute name that +field+ accepts
+    def self.safe_attr: (Object key) -> String
+
+    # _@param_ `value`
+    def self.blank_string?: (Object? value) -> bool
+  end
+
+  # Namespace for the built-in coercion types ({Types::String}, {Types::Integer},
+  # …) and the {Types::Base} contract that custom types implement.
+  module Types
+    # URL type — a {Types::String} that pre-fills the field's +format:+
+    # option with a practical http(s) URL pattern. Same shape as
+    # {Types::UUID}: bad-format input is a Phase 1 validation error,
+    # not a coercion failure.
+    # 
+    # The default pattern matches +http://+ and +https://+ URLs with a
+    # non-empty host. It is intentionally pragmatic, not RFC 3986
+    # exhaustive — users can override via +format: /.../+ if they need
+    # different schemes or stricter host rules.
+    class URL < FieldStruct::Types::String
+      # Inherits +format:+ / +enum:+ from {Types::String}, advertising the
+      # +:format+ presets this subtype resolves (see {.presets}).
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@return_ — practical http(s) pattern; override per-field via +format:+
+      def self.default_format: () -> Regexp
+
+      # _@return_ — named presets for +format:+
+      def self.presets: () -> ::Hash[::Symbol, Regexp]
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its Regexp at
+      # field-declaration time; a user-supplied Regexp passes through.
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+    end
+
+    # Abstract base for all FieldStruct type classes.
+    # 
+    # Subclasses must implement {#coerce} and {#ruby_type}. They may override
+    # {#missing?} when their notion of "missing" is broader than nil-only
+    # (e.g. strings consider empty/whitespace missing, arrays consider empty
+    # missing).
+    class Base
+      # Native per-field options this type understands, as a frozen Hash of
+      # option-name (Symbol) → descriptor. Each descriptor is built by
+      # {.option} and carries the accepted value classes, whether the option
+      # is required at declaration time, and any Symbol presets it accepts.
+      # 
+      # This merges {.own_option_schema} down the class chain so a subtype
+      # inherits its parent's options for free (e.g. {Types::UUID} picks up
+      # {Types::String}'s +format:+ / +enum:+). The merged result is frozen and
+      # memoized per type class — a type's option vocabulary is fixed at load,
+      # so this is computed once rather than on every field declaration.
+      # 
+      # This is the single source of truth for both *validation* (the DSL
+      # checks declared values against these descriptors) and *discoverability*
+      # (an agent or human can ask a type what it accepts without reading
+      # source). Options *not* listed here are treated as foreign and pass
+      # through onto the Field untouched, available to downstream tooling.
+      def self.option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # The options this type adds on top of its superclass's. Subclasses
+      # override *this* (not {.option_schema}) to declare their native options;
+      # the empty default means "adds nothing." {.option_schema} handles the
+      # inheritance merge.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # Build a normalized descriptor for {.option_schema}.
+      # 
+      # _@param_ `type` — the Ruby class(es) a declared value may be an instance of
+      # 
+      # _@param_ `required` — whether the option must be present at field-declaration time
+      # 
+      # _@param_ `presets` — Symbol preset names the option also accepts
+      # 
+      # _@return_ — a frozen descriptor: +{ type:, required:, presets: }+
+      def self.option: (_type: (::Class | ::Array[::Class]), ?required: bool, ?presets: ::Array[::Symbol]) -> ::Hash[::Symbol, Object]
+
+      # Resolve symbolic preset references on the per-field options hash
+      # at field-declaration time. Default implementation passes options
+      # through unchanged; concrete types override to interpret their
+      # own options (e.g. +format: :iso8601+ → strftime string).
+      # 
+      # _@param_ `options` — the per-field options hash, as written by the user
+      # 
+      # _@return_ — possibly-modified options to store on the Field
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+
+      # Resolve a declared +format:+ into the form coercion and rendering use.
+      # 
+      # Declared options are kept exactly as the user wrote them — see
+      # {TimeFormatResolver} for why — so a Symbol preset name has to be
+      # expanded somewhere, and the type owning the preset table is the only
+      # thing that can do it. This default serves types with no preset table:
+      # a String passes through, a Symbol is refused.
+      # 
+      # _@param_ `format` — the format as declared
+      def self.resolve_format: ((::String | ::Symbol)? format) -> ::String?
+
+      # Coerce an input value into the type's domain.
+      # 
+      # The contract here is intentionally loose — subclasses override with
+      # explicit kwargs for the options they consume (e.g. +format:+ for
+      # Date, +round:+ for Float, +of_type:+ for Array), plus a trailing
+      # +**+ catch-all so a call site that splats +field.options+ can pass
+      # keys that some types ignore. See each subclass's +coerce+ for the
+      # exact accepted options.
+      # 
+      # _@param_ `value` — raw input — each subclass narrows this to the inputs it actually accepts
+      # 
+      # _@return_ — the coerced value
+      def coerce: (Object value) -> Object
+
+      # Whether the given value should be treated as "missing" for the purpose
+      # of presence checks. The default is nil-only; subclasses override for
+      # emptier notions.
+      # 
+      # _@param_ `value`
+      def missing?: (Object value) -> bool
+
+      # The native Ruby class a coerced value will be an instance of.
+      # Used by the (deferred) RBS generator and for introspection.
+      def ruby_type: () -> Class
+
+      # The RBS type expression {FieldStruct::RBS} emits for fields of this
+      # type, or +nil+ (the default) to derive one from {#ruby_type}. Override
+      # in a custom type whose values {#ruby_type} can't describe on its own —
+      # typically a generic class, which RBS needs type arguments for:
+      # 
+      #   def ruby_type = ::Hash
+      #   def rbs_type  = '::Hash[::Symbol, ::String]'
+      # 
+      # Without it a bare generic +ruby_type+ is emitted with +untyped+
+      # arguments (+::Hash[untyped, untyped]+). A field's own +rbs_type:+
+      # option wins over this. Fully qualify constants (+::Hash+, not
+      # +Hash+): the RBS is emitted inside the struct's module nesting.
+      def rbs_type: () -> ::String?
+
+      # Concise type-instance representation. The default shows just the
+      # type-class name (e.g. +#<FieldStruct::Types::String>+). Subclasses
+      # that carry parameter state (Nested, Union, …) override to surface
+      # what they wrap.
+      def inspect: () -> ::String
+
+      # _@param_ `pp` — a PP-shaped sink (responds to +#text+)
+      def pretty_print: (Object pp) -> void
+    end
+
+    # Date type. Returns a +Date+ as-is, narrows a +DateTime+ or +Time+ down
+    # to a plain Date, reads a String via +Date.parse+ (or +strptime+ when the
+    # field declares a +format:+), and refuses everything else.
+    # 
+    # Per-field +format:+ option (String or Symbol-preset) controls both
+    # parsing (strptime when input is a String) and serialization
+    # (strftime when emitting via +as_json+ / +to_json+). When no format
+    # is set, the type uses +Date.parse+ for input and ISO-8601 for output.
+    class Date < FieldStruct::Types::Base
+      # Native options: a +format:+ strftime/strptime String (or Symbol
+      # preset; see {.presets}) and an +in:+ Array or Range of allowed values.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@return_ — field-level strftime/strptime format; +nil+
+      # leaves the type using ISO-8601 in/out
+      def self.default_format: () -> ::String?
+
+      # Named presets for the +format:+ option.
+      # 
+      # +:iso8601+ is an {Rfc3339Format} rather than a strftime String: the
+      # contract cannot be written as one (see that class). The display presets
+      # stay strftime-based — they are for humans, not wire formats.
+      def self.presets: () -> ::Hash[::Symbol, Object]
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its strftime
+      # string at field-declaration time; other forms pass through.
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+
+      # Resolve a declared +format:+ (a Symbol preset name or a strftime
+      # String) into the String that {#coerce} and JSON rendering actually
+      # use. Declarations are stored exactly as written, so this is where a
+      # preset name becomes usable. See {TimeFormatResolver}.
+      # 
+      # _@param_ `format` — the format as declared
+      # 
+      # _@return_ — +nil+ when the field declares no format
+      def self.resolve_format: ((::String | ::Symbol)? format) -> ::String?
+
+      # Dispatch is on explicit stdlib classes, never on a +respond_to?+ probe
+      # against the value. ActiveSupport defines +String#to_date+, so a probe
+      # that is false on plain Ruby is TRUE under Rails, and the type would take
+      # a different branch there than it does in its own suite — which is
+      # exactly how a declared +format:+ came to be ignored under Rails while
+      # every spec here passed. +Date.parse+ and +Date.strptime+ are not
+      # redefined by ActiveSupport, so dispatching on them gives one behaviour
+      # in both worlds.
+      # 
+      # _@param_ `value` — +nil+ → +nil+; a String is read through +strptime+ when a +format:+ is set and +Date.parse+ otherwise; a +Date+ passes through; a +DateTime+ or +Time+ (including ActiveSupport's TimeWithZone) is narrowed to a plain +Date+. Anything else is refused.
+      # 
+      # _@param_ `format` — strptime/strftime format; +nil+ uses {.default_format} (which itself defaults to +nil+ = ISO-8601 path)
+      def coerce: ((::String | ::Date | ::DateTime | ::Time)? value, ?format: ::String?) -> ::Date?
+
+      # _@return_ — the top-level +::Date+ class
+      def ruby_type: () -> Class
+
+      # _@param_ `value` — the raw string
+      # 
+      # _@param_ `format` — strptime format, when the field declares one
+      def parse_string: (::String value, ::String? format) -> ::Date
+
+      # +Date.parse+ and +Date.strptime+ build the Date straight from year,
+      # month and day whenever the parts carry all three and neither a Julian
+      # day (+:jd+) nor a day of the year (+:yday+) — date_core.c's fast path
+      # in +d_new_by_frags+ — so this returns the same Date. Any other shape is
+      # left to the stdlib (+nil+).
+      # 
+      # _@param_ `parts` — already checked by {TemporalParser}
+      def date_from_parts: (::Hash[::Symbol, Object] parts) -> ::Date?
+    end
+
+    # Time type. Returns a +Time+ as-is, builds one from a +Date+ or
+    # +DateTime+'s components, reads a String via +Time.parse+ (or +strptime+
+    # when the field declares a +format:+), and refuses everything else.
+    # 
+    # Per-field +format:+ option (String or Symbol-preset) controls both
+    # parsing (strptime when input is a String) and serialization
+    # (strftime via +as_json+).
+    class Time < FieldStruct::Types::Base
+      # Native options: a +format:+ strftime/strptime String (or Symbol
+      # preset; see {.presets}), an +in:+ Array or Range of allowed values,
+      # and a +zone:+ String (+"UTC"+, +"±HH:MM"+ or an IANA name; see {ZoneOption}).
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      def self.default_format: () -> ::String?
+
+      # Named presets for the +format:+ option.
+      # 
+      # +:iso8601+ is an {Rfc3339Format} rather than a strftime String: +%z+
+      # renders +\+0000+, which RFC 3339 rejects, and no strftime string can
+      # express optional fractional seconds. The interchange and display
+      # presets stay strftime-based.
+      def self.presets: () -> ::Hash[::Symbol, Object]
+
+      # Validate a Symbol +format:+ preset (see {.presets}) and a +zone:+
+      # (see {ZoneOption}) at field-declaration time.
+      # 
+      # _@param_ `options` — the per-field options
+      # 
+      # _@return_ — the options, unchanged
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+
+      # Resolve a declared +format:+ (a Symbol preset name or a strftime
+      # String) into the String that {#coerce} and JSON rendering actually
+      # use. Declarations are stored exactly as written, so this is where a
+      # preset name becomes usable. See {TimeFormatResolver}.
+      # 
+      # _@param_ `format` — the format as declared
+      # 
+      # _@return_ — +nil+ when the field declares no format
+      def self.resolve_format: ((::String | ::Symbol)? format) -> ::String?
+
+      # Dispatch is on explicit stdlib classes, never on a +respond_to?+ probe
+      # against the value. ActiveSupport defines +String#to_time+, and it
+      # returns +nil+ for a string with no time in it rather than raising — so
+      # under Rails "not-a-time" was coerced to nil and reported VALID. The
+      # probe is gone; +Time.parse+ and +Time.strptime+ behave the same with or
+      # without ActiveSupport loaded.
+      # 
+      # Cross-class conversion builds a Time from components rather than
+      # calling +to_time+, which ActiveSupport redefines: under AS 7.2
+      # +DateTime#to_time+ converts to the system-local zone and emits a
+      # deprecation warning, while 8.x preserves the offset. Constructing from
+      # parts gives the same instant and the same offset in all three
+      # environments, which is what makes the behaviour host-independent rather
+      # than merely documented.
+      # 
+      # _@param_ `value` — +nil+ → +nil+; a String is read through +strptime+ when a +format:+ is set and +Time.parse+ otherwise; a +Time+ passes through; a +DateTime+, +Date+ or Time-like value (ActiveSupport's TimeWithZone) is converted. Anything else is refused.
+      # 
+      # _@param_ `format` — strptime/strftime format; +nil+ uses {.default_format} (which itself defaults to +nil+ = ISO-8601 path)
+      # 
+      # _@param_ `zone` — +"UTC"+, +"±HH:MM"+ or an IANA name: the offset for a String that names none, and for a +Date+'s midnight. Input carrying its own offset keeps it. +nil+ means the process zone. See {ZoneOption}.
+      def coerce: ((::String | ::Time | ::Date | ::DateTime)? value, ?format: ::String?, ?zone: ::String?) -> ::Time?
+
+      # _@return_ — the top-level +::Time+ class
+      def ruby_type: () -> Class
+
+      # _@param_ `value` — the raw string
+      # 
+      # _@param_ `format` — strptime format, when the field declares one
+      # 
+      # _@param_ `zone` — the field's +zone:+, if declared
+      def parse_string: (::String value, ::String? format, ::String? zone) -> ::Time
+
+      # _@param_ `value` — the value to convert
+      # 
+      # _@return_ — the same instant, at the same offset, sub-second
+      # precision preserved
+      def time_from_datetime: (::DateTime value) -> ::Time
+    end
+
+    # UUID type — a {Types::String} that pre-fills the field's +format:+
+    # option with a canonical RFC-4122 pattern. Bad-format input becomes
+    # a Phase 1-style validation error (+"is invalid"+); coercion itself
+    # still just hands back the string.
+    # 
+    # Users can override the pattern by passing +format: /.../+ on the
+    # field declaration.
+    class UUID < FieldStruct::Types::String
+      # Inherits +format:+ / +enum:+ from {Types::String}, advertising the
+      # +:format+ presets this subtype resolves (see {.presets}).
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # Hex-digit-only canonical RFC-4122 form. Permits any version.
+      # 
+      # _@return_ — applied at the field level when no +format:+ is given
+      def self.default_format: () -> Regexp
+
+      # _@return_ — named presets for +format:+
+      def self.presets: () -> ::Hash[::Symbol, Regexp]
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its Regexp at
+      # field-declaration time; a user-supplied Regexp passes through.
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+    end
+
+    # Array type. Coerces each element through the registered element
+    # type named by the +:of+ DSL option (resolved at field-declaration
+    # time and stashed as +options[:of_type]+ — a class, not a symbol).
+    # 
+    # An optional +:element+ Hash carries the element type's own options
+    # (+strict:+, +base:+, +format:+, …), passed to every element's coerce:
+    # 
+    #   optional :ids, :array, of: :integer, element: {strict: true, base: 16}
+    # 
+    # A refused element is reported with its index — +element at index 2: …+ —
+    # and several with all of theirs (see {.elements_at}).
+    # 
+    # Missing: +nil+ or empty array. ruby_type: +::Array+.
+    class Array < FieldStruct::Types::Base
+      INDEXES_LISTED: ::Integer
+
+      # Native options: a required +of:+ naming the element type — a
+      # registered Symbol or a Class (a +Types::Base+ or +FieldStruct::Base+
+      # subclass) — and an +element:+ Hash of that element type's options.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # The element type class behind an +of_type+ option, whether it holds
+      # a class (+:integer+ → {Types::Integer}) or a built instance (a
+      # {Types::Nested}). Its +option_schema+ is what +element:+ accepts.
+      # 
+      # _@param_ `of_type` — an array field's +:of_type+ option
+      # 
+      # _@return_ — a {Types::Base} subclass
+      def self.element_class: ((Class | Types::Base) of_type) -> singleton(Types::Base)
+
+      # _@param_ `value` — anything else raises TypeError
+      # 
+      # _@param_ `of_type` — the element type — a Types::Base subclass for stock types, or an already-built instance for parameterized types like {Types::Nested}. The DSL stashes this when the user writes +of: :string+ / +of: SomeStruct+. Required at the type level; nil here means the type was called directly without DSL help.
+      # 
+      # _@param_ `element` — the element type's options, passed to every element's coerce (the DSL's +element:+, already validated against the element type's schema)
+      # 
+      # _@return_ — each element coerced by +of_type+
+      def coerce: (::Array[Object?]? value, ?of_type: (Class | Types::Base)?, ?element: ::Hash[::Symbol, Object?]?) -> ::Array[Object?]?
+
+      # Name a set of element indexes for an error message: one reads
+      # +element at index 2+, several +elements at index 2, 5+, and past
+      # {INDEXES_LISTED} the rest are counted (+… and 7 more+). Indexes only,
+      # never elements, so a message carries no value.
+      # 
+      # _@param_ `indexes` — ascending, at least one
+      def self.elements_at: (::Array[::Integer] indexes) -> ::String
+
+      # _@param_ `value`
+      # 
+      # _@return_ — +true+ when +nil+ or empty
+      def missing?: (Object value) -> bool
+
+      # _@return_ — the top-level +::Array+ class
+      def ruby_type: () -> Class
+
+      # Coerce the elements after the first refused one, so the error names
+      # every refused index, then raise the first element's error with them.
+      # The same message reaches every coercion_policy, :raise included —
+      # finishing the scan costs a refused array no more than an accepted one.
+      # 
+      # _@param_ `value` — the input array
+      # 
+      # _@param_ `first` — the index of the first refused element
+      # 
+      # _@param_ `error` — what the element type raised for it
+      # 
+      # _@param_ `element_type` — the element type instance
+      # 
+      # _@param_ `element` — element options
+      def raise_refused!: (
+                            ::Array[Object?] value,
+                            ::Integer first,
+                            StandardError error,
+                            Types::Base element_type,
+                            ::Hash[::Symbol, Object?]? element
+                          ) -> void
+
+      # +of_type+ may be either a Types::Base subclass (the DSL form for
+      # stock types like +:string+) or an already-built Types::Base
+      # instance (the DSL form for parameterized types like
+      # {Types::Nested}). Both produce a single cached instance per
+      # configured element type.
+      # 
+      # _@param_ `type_or_instance`
+      def element_type_for: ((singleton(Types::Base) | Types::Base) type_or_instance) -> Types::Base
+    end
+
+    # Email type — a {Types::String} that pre-fills the field's +format:+
+    # option with a pragmatic email pattern. Same shape as
+    # {Types::UUID} / {Types::URL}: bad-format input is a validation
+    # error, not a coercion failure.
+    # 
+    # The default pattern is deliberately not RFC 5322 strict — those
+    # regexes are unwieldy and reject real-world addresses. It checks
+    # +local@domain.tld+ shape with no internal whitespace or extra +@+
+    # characters; users can override via +format: /.../+ for stricter
+    # rules.
+    class Email < FieldStruct::Types::String
+      # Inherits +format:+ / +enum:+ from {Types::String}, advertising the
+      # +:format+ presets this subtype resolves (see {.presets}).
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@return_ — pragmatic +local@domain.tld+ shape, no internal
+      # whitespace or extra +@+; deliberately not RFC 5322 strict.
+      # Override per-field via +format:+ (Regexp or Symbol preset).
+      def self.default_format: () -> Regexp
+
+      # _@return_ — named presets for +format:+
+      def self.presets: () -> ::Hash[::Symbol, Regexp]
+
+      # Resolve a Symbol +format:+ preset (see {.presets}) to its Regexp at
+      # field-declaration time; a user-supplied Regexp passes through.
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+    end
+
+    # Float type. Coerces via +Kernel#Float+, which parses numeric strings
+    # strictly and rejects anything non-numeric. Strings are base 10, as for
+    # {Types::Integer}: a hex string like "0x1A", which +Kernel#Float+ would
+    # read as 26.0, is refused.
+    class Float < FieldStruct::Types::Base
+      HEX_PREFIX: ::Regexp
+
+      # Native options: a +round:+ Integer precision and an +in:+ Array or
+      # Range of allowed values.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@return_ — field-level rounding precision; +nil+ disables.
+      def self.default_round: () -> ::Integer?
+
+      # _@param_ `value` — +nil+ → +nil+; everything else flows through +Kernel#Float+ — strict on string parsing, rejects non-numeric strings, Symbols, Booleans, Arrays, and hex strings ("0x1A").
+      # 
+      # _@param_ `round` — decimal places, rounding half up (ties away from zero); +nil+ leaves the value unrounded. The result is a Float even at +round: 0+.
+      # 
+      # _@return_ — +nil+ for +nil+ input, otherwise the parsed float
+      def coerce: ((Numeric | ::String)? value, ?round: ::Integer?) -> ::Float?
+
+      # _@return_ — the top-level +::Float+ class
+      def ruby_type: () -> Class
+
+      # _@param_ `value` — a non-Float value
+      def parse: (Object value) -> ::Float
+    end
+
+    # Union type — a value that may be any of several types. Each
+    # member is tried in declared order; the first one whose +coerce+
+    # doesn't raise wins. Member-coercion errors are caught broadly
+    # (ArgumentError, TypeError, FieldStruct::Error) so a member's
+    # rejection lets the next member have a try; unrelated bugs (e.g.
+    # +NoMethodError+) still propagate.
+    # 
+    #   optional :payload, :union, of: [Payload, :boolean]
+    # 
+    # If every member rejects the value, the union raises a +TypeError+
+    # which the parent's +coercion_policy+ handles like any
+    # shape-level coercion failure.
+    # 
+    # Order matters: +of: [String, Integer]+ coerces "42" to "42"
+    # (String wins first); +of: [Integer, String]+ coerces "42" to 42.
+    class Union < FieldStruct::Types::Base
+      RESCUABLE: ::Array[singleton(::StandardError)]
+
+      # Native options: a required +of:+ Array of member types (the DSL
+      # additionally requires at least two members).
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@param_ `member_types` — member instances, in priority order
+      def initialize: (::Array[Types::Base] member_types) -> void
+
+      # _@param_ `value` — anything — each member type's coerce is tried in declared order; the first that doesn't raise wins
+      # 
+      # _@return_ — whatever the first successful member returns
+      def coerce: (Object? value) -> Object?
+
+      # _@param_ `value`
+      # 
+      # _@return_ — true only for nil — union doesn't try to
+      # collectively reason about "missing" across its members
+      def missing?: (Object value) -> bool
+
+      # Flat list of member +ruby_type+ values. Members whose
+      # ruby_type is already an Array (like Boolean's
+      # +[TrueClass, FalseClass]+) get spliced in; duplicates are
+      # removed.
+      def ruby_type: () -> ::Array[Class]
+
+      def inspect: () -> ::String
+
+      # _@return_ — the configured member type instances
+      attr_reader member_types: ::Array[Types::Base]
+    end
+
+    # Value type. A no-coercion passthrough — whatever you give it comes
+    # back unchanged. Useful as an escape hatch when you want a field
+    # declaration to participate in metadata without committing to a
+    # specific shape.
+    class Value < FieldStruct::Types::Base
+      # _@param_ `value` — anything — passthrough, no coercion
+      # 
+      # _@return_ — the value, unchanged
+      def coerce: (Object value) -> Object
+
+      # _@return_ — +Object+ — the broadest sensible class
+      def ruby_type: () -> Class
+    end
+
+    # Binary type — coerces input to a String and forces +ASCII-8BIT+
+    # encoding. Intended for raw bytes (file contents, BLOBs, etc.)
+    # where whitespace bytes (+\x20+, +\n+, etc.) are meaningful data,
+    # not "missing" content.
+    # 
+    # +missing?+ is therefore +nil+-or-empty only — unlike
+    # {Types::String} which treats whitespace-only as missing.
+    class Binary < FieldStruct::Types::String
+      # _@param_ `value` — anything stringable; +nil+ stays +nil+
+      # 
+      # _@return_ — +nil+ when input is +nil+, otherwise a
+      # fresh ASCII-8BIT-encoded copy of +value.to_s+
+      def coerce: (_ToS? value) -> ::String?
+
+      # Missing if nil or empty. Whitespace bytes are meaningful in
+      # binary data, so they don't count as missing.
+      # 
+      # _@param_ `value`
+      def missing?: (Object value) -> bool
+    end
+
+    # Type wrapper for nested FieldStruct fields.
+    # 
+    #   class Address < FieldStruct::Base
+    #     required :street, :string
+    #     required :city,   :string
+    #   end
+    # 
+    #   class Person < FieldStruct::Base
+    #     required :address, Address
+    #   end
+    # 
+    # Built and held per-Field by the DSL when it sees a class argument
+    # that descends from {FieldStruct::Base}. Each instance is
+    # parameterized by its target +struct_class+; instances are not
+    # interchangeable across different nested classes.
+    class Nested < FieldStruct::Types::Base
+      # _@param_ `struct_class` — a FieldStruct::Base subclass
+      def initialize: (Class struct_class) -> void
+
+      # Coerce input into a {#struct_class} instance.
+      # 
+      # - +nil+ → +nil+
+      # - already a {#struct_class} (or subclass) instance → passthrough
+      # - +Hash+ → +struct_class.new(hash)+
+      # - anything else → +TypeError+ (which the parent's coercion_policy
+      #   handles like any shape-level coercion failure)
+      # 
+      # Errors raised inside +struct_class.new+ (e.g.
+      # {UnknownAttributeError}, {CoercionError}) propagate to the caller
+      # rather than being caught by the parent's policy — those are
+      # structural rejections of the nested record's input, not parent-
+      # shape coercion failures.
+      # 
+      # _@param_ `value` — +nil+ → +nil+; an instance of {#struct_class} (or subclass) → passthrough; a +Hash+ → constructs via +struct_class.new(hash)+. Anything else raises TypeError.
+      def coerce: ((FieldStruct::Base | ::Hash[(::Symbol | ::String), Object?])? value) -> FieldStruct::Base?
+
+      # _@param_ `value`
+      # 
+      # _@return_ — true only when value is nil — an instance with
+      # all required fields missing is not "missing" here, it is just
+      # invalid. Invalidity is surfaced by the parent's validate_field.
+      def missing?: (Object value) -> bool
+
+      # _@return_ — the +struct_class+ itself, so introspection sees
+      # the actual nested type rather than a generic FieldStruct::Base
+      def ruby_type: () -> Class
+
+      def inspect: () -> ::String
+
+      # _@return_ — the FieldStruct::Base subclass this type wraps
+      attr_reader struct_class: Class
+    end
+
+    # String type. Coerces any non-nil value via +to_s+; treats nil, empty,
+    # and whitespace-only strings as missing. A field declared +strict: true+
+    # accepts only scalars (String, Symbol, Integer) and objects
+    # responding to +to_str+, so a Hash or Array is refused rather than stored
+    # as its +inspect+ text.
+    class String < FieldStruct::Types::Base
+      # Native options: a +format:+ Regexp (or Symbol preset, used by the
+      # +:uuid+ / +:url+ / +:email+ subtypes), an +enum:+ Array of
+      # allowed values, and a +strict:+ Boolean.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@param_ `value` — anything stringable (everything in Ruby responds to +to_s+); +nil+ stays +nil+
+      # 
+      # _@param_ `strict` — when true, refuse anything but a String, Symbol, Integer or +to_str+ object (a Float, BigDecimal or Rational is refused: its +to_s+ is +"0.12e2"+ / +"1/2"+, not the caller's text). Strict never changes what an accepted value becomes — it is still +value.to_s+.
+      # 
+      # _@return_ — +nil+ when input is +nil+, otherwise +value.to_s+
+      def coerce: (_ToS? value, ?strict: bool?) -> ::String?
+
+      # Missing if nil, empty, or whitespace-only.
+      # 
+      # _@param_ `value`
+      def missing?: (Object value) -> bool
+
+      # _@return_ — the top-level +::String+ class
+      def ruby_type: () -> Class
+
+      # _@param_ `value` — a non-nil value
+      def refuse_non_scalar!: (Object value) -> void
+    end
+
+    # Symbol type. Accepts an existing +Symbol+ or a +String+. Anything else
+    # raises +TypeError+, which the parent's +coercion_policy+ handles.
+    # 
+    # Empty symbols (+:""+) are unusual; like other scalar non-string types,
+    # +missing?+ is nil-only — an empty symbol counts as present.
+    class Symbol < FieldStruct::Types::Base
+      # Native options: an +enum:+ Array of allowed values (symbols are
+      # string-like, so they share +enum:+ with {Types::String}).
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@param_ `value` — anything else raises TypeError
+      def coerce: ((::Symbol | ::String)? value) -> ::Symbol?
+
+      # _@return_ — the top-level +::Symbol+ class
+      def ruby_type: () -> Class
+    end
+
+    # Boolean type. Accepts the literal +true+/+false+, the strings
+    # "true"/"false" (case-insensitive), and the integers/strings 1/0.
+    # Anything else raises +ArgumentError+.
+    # 
+    # Per-field +values:+ option customizes the truthy/falsy vocabulary:
+    # 
+    #   required :active, :boolean, values: {truthy: %w[on yes y],
+    #                                        falsy:  %w[off no n]}
+    #   required :flag,   :boolean, values: :english_yes_no
+    # 
+    # Hash form takes +:truthy+ and +:falsy+ Arrays of strings (matched
+    # case-insensitively). Symbol form names a built-in preset; see
+    # {.presets} for the available names.
+    # 
+    # Ruby has no Boolean class, so {#ruby_type} returns the pair
+    # +[TrueClass, FalseClass]+.
+    class Boolean < FieldStruct::Types::Base
+      # Native options: a +values:+ Hash with +:truthy+ / +:falsy+ keys, or a
+      # Symbol naming one of {.presets}.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@return_ — case-insensitive strings that coerce to true
+      def self.default_truthy: () -> ::Array[::String]
+
+      # _@return_ — case-insensitive strings that coerce to false
+      def self.default_falsy: () -> ::Array[::String]
+
+      # _@return_ — named presets for the +values:+ option
+      def self.presets: () -> ::Hash[::Symbol, ::Hash[::Symbol, ::Array[::String]]]
+
+      # Resolve a Symbol +values:+ to its preset Hash at field-declaration
+      # time. Pass-through for Hash form; raises for unknown preset names.
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+
+      # _@param_ `value` — accepts literal +true+/+false+; the integers +1+/+0+; or a String matched case-insensitively against the truthy/falsy vocabularies. Anything else raises ArgumentError.
+      # 
+      # _@param_ `values` — +{truthy: [...], falsy: [...]}+ custom vocabulary; +nil+ uses {.default_truthy} / {.default_falsy}
+      def coerce: ((bool | ::Integer | ::String)? value, ?values: ::Hash[::Symbol, ::Array[::String]]?) -> bool?
+
+      # _@return_ — +[TrueClass, FalseClass]+
+      def ruby_type: () -> [Class, Class]
+
+      # The accepted vocabulary is declared schema, so it is listed; the
+      # refused value is named by class only — it may be payments data.
+      # 
+      # _@param_ `value` — the refused input
+      # 
+      # _@param_ `accepted` — the truthy then falsy strings
+      def refusal_message: (Object value, ::Array[::String] accepted) -> ::String
+
+      # _@param_ `values` — the field's +values:+
+      # 
+      # _@return_ — +[truthy, falsy]+, downcased
+      def truthy_and_falsy_for: (::Hash[::Symbol, ::Array[::String]]? values) -> [::Array[::String], ::Array[::String]]
+    end
+
+    # Integer type. Strings parse in base 10 unless the field declares a
+    # +base:+, so "010" is ten (not octal eight) and "0x1A" is refused rather
+    # than read as hex. Float-shaped strings like "3.14" raise rather than
+    # silently truncate. Float numerics, by contrast, are truncated — that
+    # matches +Kernel#Integer+'s own behavior on numeric input — unless the
+    # field declares +strict: true+, which refuses any non-integral value.
+    class Integer < FieldStruct::Types::Base
+      BASES: ::Range[::Integer]
+      MAX_DECIMAL_DIGITS: ::Integer
+
+      # Native options: an +in:+ Array or Range of allowed values, a
+      # +base:+ Integer radix (2..36) for string input, and a +strict:+
+      # Boolean.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # Refuse a +base:+ outside 2..36 at field-declaration time. A
+      # non-Integer +base:+ is left for the option-shape check to report.
+      # 
+      # _@param_ `options` — the per-field options hash
+      # 
+      # _@return_ — the options, unchanged
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+
+      # _@param_ `value` — +nil+ → +nil+; +Integer+ passes through; a String parses in +base+ (surrounding whitespace and digit underscores allowed; float-shaped or out-of-base strings raise ArgumentError); other numerics flow through +Kernel#Integer+ — Floats are truncated; Symbols/Booleans/Arrays raise TypeError.
+      # 
+      # _@param_ `base` — radix (2..36) for String input; +nil+ means 10
+      # 
+      # _@param_ `strict` — when true, refuse a value that is not a whole number (+12.7+, a +Time+) instead of truncating it; an integral one (+12.0+) still becomes its Integer
+      # 
+      # _@return_ — +nil+ for +nil+ input, otherwise the parsed integer
+      def coerce: ((::Integer | Numeric | ::String)? value, ?base: ::Integer?, ?strict: bool?) -> ::Integer?
+
+      # _@return_ — the top-level +::Integer+ class
+      def ruby_type: () -> Class
+
+      # _@param_ `value`
+      def refuse_huge_decimal!: (Object value) -> void
+
+      # _@param_ `value` — the input, already read by +Kernel#Integer+
+      # 
+      # _@param_ `whole` — what +Kernel#Integer+ made of it
+      def refuse_inexact!: (Object value, ::Integer whole) -> void
+
+      # _@param_ `value`
+      # 
+      # _@param_ `base`
+      def parse_string: (::String value, ::Integer base) -> ::Integer
+    end
+
+    # DateTime type. Returns a +DateTime+ as-is, builds one from a +Date+ or
+    # +Time+'s components, reads a String via +DateTime.parse+ (or +strptime+
+    # when the field declares a +format:+), and refuses everything else.
+    # 
+    # Per-field +format:+ option (String or Symbol-preset) controls both
+    # parsing (strptime when input is a String) and serialization
+    # (strftime via +as_json+).
+    class DateTime < FieldStruct::Types::Base
+      # Native options: a +format:+ strftime/strptime String (or Symbol
+      # preset; see {.presets}), an +in:+ Array or Range of allowed values,
+      # and a +zone:+ String (+"UTC"+, +"±HH:MM"+ or an IANA name; see {ZoneOption}).
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@return_ — field-level strftime/strptime format; +nil+
+      # leaves the type using ISO-8601 in/out
+      def self.default_format: () -> ::String?
+
+      # Named presets for the +format:+ option.
+      # 
+      # +:iso8601+ is an {Rfc3339Format} rather than a strftime String: +%z+
+      # renders +\+0000+, which RFC 3339 rejects, and no strftime string can
+      # express optional fractional seconds. The interchange and display
+      # presets stay strftime-based.
+      def self.presets: () -> ::Hash[::Symbol, Object]
+
+      # Validate a Symbol +format:+ preset (see {.presets}) and a +zone:+
+      # (see {ZoneOption}) at field-declaration time.
+      # 
+      # _@param_ `options` — the per-field options
+      # 
+      # _@return_ — the options, unchanged
+      def self.resolve_options: (::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+
+      # Resolve a declared +format:+ (a Symbol preset name or a strftime
+      # String) into the String that {#coerce} and JSON rendering actually
+      # use. Declarations are stored exactly as written, so this is where a
+      # preset name becomes usable. See {TimeFormatResolver}.
+      # 
+      # _@param_ `format` — the format as declared
+      # 
+      # _@return_ — +nil+ when the field declares no format
+      def self.resolve_format: ((::String | ::Symbol)? format) -> ::String?
+
+      # Dispatch is on explicit stdlib classes, never on a +respond_to?+ probe
+      # against the value: ActiveSupport defines +String#to_datetime+, so a
+      # probe that is false on plain Ruby is TRUE under Rails.
+      # +DateTime.parse+ and +DateTime.strptime+ are not redefined by
+      # ActiveSupport. See {Types::Time#coerce} for why cross-class conversion
+      # is built from components rather than +to_datetime+.
+      # 
+      # _@param_ `value` — +nil+ → +nil+; a String is read through +strptime+ when a +format:+ is set and +DateTime.parse+ otherwise; a +DateTime+ passes through; a +Date+ becomes midnight and a +Time+ (including ActiveSupport's TimeWithZone) keeps its instant and offset. Anything else is refused.
+      # 
+      # _@param_ `format` — strptime/strftime format; +nil+ uses {.default_format} (which itself defaults to +nil+ = ISO-8601 path)
+      # 
+      # _@param_ `zone` — +"UTC"+, +"±HH:MM"+ or an IANA name: the offset for a String that names none, and for a +Date+'s midnight. Input carrying its own offset keeps it. +nil+ means UTC. See {ZoneOption}.
+      def coerce: ((::String | ::DateTime | ::Date | ::Time)? value, ?format: ::String?, ?zone: ::String?) -> ::DateTime?
+
+      # _@return_ — the top-level +::DateTime+ class
+      def ruby_type: () -> Class
+
+      # _@param_ `value` — the raw string
+      # 
+      # _@param_ `format` — strptime format, when the field declares one
+      # 
+      # _@param_ `zone` — the field's +zone:+, if declared
+      def parse_string: (::String value, ::String? format, ::String? zone) -> ::DateTime
+
+      # _@param_ `value` — the value to convert
+      # 
+      # _@return_ — the same instant, at the same offset, sub-second
+      # precision preserved
+      def datetime_from_time: (::Time value) -> ::DateTime
+    end
+
+    # BigDecimal type. Accepts a {::BigDecimal}, +Integer+, +Float+, or a
+    # numeric string. Float input is converted with +Float::DIG+ precision
+    # to avoid the bare +BigDecimal(Float)+ "can't omit precision" error.
+    class BigDecimal < FieldStruct::Types::Base
+      # Native options: a +round:+ Integer precision and an +in:+ Array or
+      # Range of allowed values.
+      def self.own_option_schema: () -> ::Hash[::Symbol, ::Hash[::Symbol, Object]]
+
+      # _@return_ — the field-level rounding precision, or +nil+
+      # for no rounding. Subclasses override.
+      def self.default_round: () -> ::Integer?
+
+      # _@param_ `value` — +nil+ → +nil+; a +BigDecimal+ passes through; +Float+ uses +Float::DIG+ precision; everything else goes through +Kernel.BigDecimal(value.to_s)+ — non-numeric strings raise ArgumentError.
+      # 
+      # _@param_ `round` — decimal places, rounding half up (ties away from zero) whatever the global +BigDecimal.mode+; +nil+ leaves the value unrounded. The result is a BigDecimal even at +round: 0+.
+      def coerce: ((::BigDecimal | Numeric | ::String)? value, ?round: ::Integer?) -> ::BigDecimal?
+
+      # _@return_ — the top-level +::BigDecimal+ class
+      def ruby_type: () -> Class
+
+      # _@param_ `value` — a value that is neither a BigDecimal nor a Float
+      def parse: (Object value) -> ::BigDecimal
+    end
+
+    # The +zone:+ option shared by {Time} and {DateTime}.
+    # 
+    # A zone-less string (+"2026-10-22 10:00"+) names a wall-clock time, not an
+    # instant: by default +:time+ reads it in the *process* zone and +:datetime+
+    # in UTC, so the same input meant different instants on different servers.
+    # +zone:+ supplies the missing offset, so it means one instant everywhere.
+    # 
+    # It only fills in an offset that is MISSING. A string with an offset, a
+    # +Time+, a +DateTime+ (and ActiveSupport's TimeWithZone) keep theirs; a
+    # +Date+, which has none, becomes midnight in the zone.
+    # 
+    # Accepted values are +"UTC"+, fixed offsets +"±HH:MM"+ and IANA
+    # Area/Location names (+"America/Denver"+). A fixed offset is the same all
+    # year. A name is read through tzinfo's zone database, so a wall-clock time
+    # gets the offset in force at that date and an instant (an epoch) the
+    # offset in force at that instant. tzinfo is required only when a field
+    # declares a name.
+    # 
+    # Daylight-saving edges, for a name:
+    # 
+    # - A wall-clock time the zone skips (02:30 on a spring-forward day) is
+    #   refused, as a 30 February is: it names no instant. ActiveSupport moves
+    #   it an hour forward instead; FieldStruct does not guess.
+    # - A wall-clock time the zone repeats (01:30 on a fall-back day) is read
+    #   at its daylight-time offset — the earlier instant — which is what
+    #   ActiveSupport's TimeWithZone picks, so a Rails app sees the same answer.
+    # - A +Date+ whose midnight the zone skips becomes the first moment of that
+    #   day (01:00 in Santiago on its spring-forward day), as
+    #   +Date#in_time_zone+ does.
+    # 
+    # The value returned is a plain +::Time+ (or +::DateTime+) carrying the
+    # offset, never a +TZInfo::TimeWithOffset+; it does not carry the zone
+    # itself, so arithmetic on it keeps that offset rather than following DST.
+    # 
+    # Refused: abbreviations and legacy aliases with no +/+ (+"MST"+ is a fixed
+    # -07:00 in the database, not Mountain time with DST) and Rails' friendly
+    # names (+"Mountain Time (US & Canada)"+), which only exist when
+    # ActiveSupport is loaded and so would make a declaration valid in one
+    # process and invalid in another (invariant 7).
+    module ZoneOption
+      OFFSET: ::Regexp
+
+      # Refuse a +zone:+ value FieldStruct cannot read, at declaration. A
+      # non-String is left for the option-shape check to report.
+      # 
+      # _@param_ `type_name` — the type's short name, for the message
+      # 
+      # _@param_ `options` — the per-field options
+      # 
+      # _@return_ — the options, unchanged
+      def self.validate!: (::String type_name, ::Hash[::Symbol, Object?] options) -> ::Hash[::Symbol, Object?]
+
+      # _@param_ `type_name` — the type's short name
+      # 
+      # _@param_ `zone` — the refused +zone:+
+      # 
+      # _@return_ — the declaration error, with a hint for the
+      # shape of +zone+
+      def self.refusal: (::String type_name, ::String zone) -> ::String
+
+      # Look up (and cache) a zone by name, requiring tzinfo on first use.
+      # 
+      # _@param_ `type_name` — the type's short name, for the message
+      # 
+      # _@param_ `zone` — an IANA name
+      # 
+      # _@return_ — the +TZInfo::Timezone+
+      def self.load_timezone: (::String type_name, ::String zone) -> Object
+
+      # _@param_ `zone` — an IANA name {.validate!} accepted
+      # 
+      # _@return_ — the cached +TZInfo::Timezone+
+      def self.timezone: (::String zone) -> Object
+
+      # _@param_ `zone` — a declared +zone:+
+      # 
+      # _@return_ — seconds east of UTC, or +nil+ when +zone+ is
+      # not a value {.validate!} accepts
+      def self.offset_seconds: (::String zone) -> ::Integer?
+
+      # Whether parsed fragments leave the offset to +zone:+.
+      # 
+      # _@param_ `parts` — fragments from +Date._parse+ or +Date._strptime+
+      # 
+      # _@return_ — +true+ when the string named no offset at all
+      def self.zoneless?: (::Hash[::Symbol, Object] parts) -> bool
+
+      # Read a zone-less String as a wall-clock time in +zone+.
+      # 
+      # _@param_ `value` — a string {.zoneless?} accepted
+      # 
+      # _@param_ `format` — a resolved strptime format, or +nil+ for the no-format path (which has already required a whole day)
+      # 
+      # _@param_ `zone` — a declared +zone:+
+      # 
+      # _@param_ `parts` — the fragments the string parsed to; an epoch (+%s+ / +%Q+) shows up as +:seconds+
+      # 
+      # _@return_ — at +zone+'s offset (+utc?+ for +"UTC"+)
+      def self.time_at: (
+                          ::String value,
+                          ::String? format,
+                          ::String zone,
+                          ::Hash[::Symbol, Object] parts
+                        ) -> ::Time
+
+      # {.time_at} for an IANA name: the offset depends on the date.
+      # 
+      # _@param_ `value` — the zone-less string
+      # 
+      # _@param_ `format` — a resolved strptime format, or +nil+
+      # 
+      # _@param_ `timezone` — a +TZInfo::Timezone+
+      # 
+      # _@param_ `parts` — the parsed fragments
+      def self.named_time_at: (
+                                ::String value,
+                                ::String? format,
+                                Object timezone,
+                                ::Hash[::Symbol, Object] parts
+                              ) -> ::Time
+
+      # A wall-clock time in a named zone.
+      # 
+      # _@param_ `timezone` — a +TZInfo::Timezone+
+      # 
+      # _@param_ `civil` — year, month, day, hour, minute and seconds (with any fraction)
+      # 
+      # _@return_ — at the offset in force at that wall-clock time
+      def self.local: (Object timezone, ::Array[::Numeric] civil) -> ::Time
+
+      # _@param_ `time` — an instant
+      # 
+      # _@param_ `timezone` — a +TZInfo::Timezone+
+      # 
+      # _@return_ — the same instant at the zone's offset at that instant
+      def self.in_zone: (::Time time, Object timezone) -> ::Time
+
+      # _@param_ `value` — a plain Date
+      # 
+      # _@param_ `zone` — a declared +zone:+
+      # 
+      # _@return_ — midnight at +zone+'s offset — for a name, the first
+      # moment of that day
+      def self.midnight: (::Date value, ::String zone) -> ::Time
+
+      # _@param_ `value` — a plain Date
+      # 
+      # _@param_ `timezone` — a +TZInfo::Timezone+
+      # 
+      # _@return_ — the first moment of that day in the zone
+      def self.named_midnight: (::Date value, Object timezone) -> ::Time
+
+      # _@param_ `seconds` — seconds east of UTC
+      # 
+      # _@return_ — +"+HH:MM"+ / +"-HH:MM"+
+      def self.offset_text: (::Integer seconds) -> ::String
+    end
+
+    # RFC 3339 — the profile of ISO 8601 that "ISO-8601" means in an API
+    # contract, and what JSON Schema's +date-time+ refers to. This is what the
+    # +:iso8601+ preset resolves to for {Date}, {Time} and {DateTime}.
+    # 
+    # FieldStruct parses and renders it itself, for two reasons.
+    # 
+    # **It cannot be written as a strftime string.** +%z+ renders +\+0000+,
+    # which RFC 3339 rejects — so the preset named +iso8601+ used to emit a
+    # value its own documented format would refuse. And no strftime string can
+    # express "optional fractional seconds", which most JSON APIs emit.
+    # 
+    # **The stdlib helpers disagree with each other.** Routing +Time+ through
+    # +Time.iso8601+ and +DateTime+ through +DateTime.iso8601+ would give the
+    # same declared preset two different contracts:
+    # 
+    #     Time.iso8601('2026-02-30T10:30:00Z')      # => 2026-03-02 10:30 UTC
+    #     DateTime.iso8601('2026-02-30T10:30:00Z')  # => refused
+    #     Time.iso8601('2026-07-03T10:30Z')         # => refused
+    #     DateTime.iso8601('2026-07-03T10:30Z')     # => accepted
+    #     DateTime.iso8601('10:30:00Z')             # => TODAY at 10:30
+    # 
+    # +Time.iso8601+ reading 30 February as 2 March is the exact
+    # silently-wrong-day defect this release exists to remove, so it cannot be
+    # the thing that implements the strict preset.
+    # 
+    # The pattern is deliberately narrow: fixed-width fields, a mandatory
+    # offset, and no week dates, ordinal dates or basic (unseparated) forms.
+    # That narrowness is the point — it is what lets a caller replace a
+    # hand-rolled +/\A\d{4}-\d{2}-\d{2}\z/+ with a declared format.
+    class Rfc3339Format
+      DATE: ::Regexp
+      TIMESTAMP: ::Regexp
+
+      # _@return_ — the date-only form, for {Types::Date}
+      def self.date: () -> Rfc3339Format
+
+      # _@return_ — the timestamp form, for {Types::Time} and {Types::DateTime}
+      def self.timestamp: () -> Rfc3339Format
+
+      # _@param_ `kind` — +:date+ or +:timestamp+
+      def initialize: (::Symbol kind) -> void
+
+      # _@return_ — the preset name this format implements
+      def name: () -> ::Symbol
+
+      # The accepted shape, as a regular expression whose source is also valid
+      # as an ECMA pattern — so a schema or documentation generator can publish
+      # the enforced contract rather than a prose approximation of it.
+      def pattern: () -> ::Regexp
+
+      # _@return_ — the format's name, for error messages and inspection
+      def to_s: () -> ::String
+
+      # Parse a String into date/time fragments.
+      # 
+      # _@param_ `value` — the raw string
+      # 
+      # _@return_ — +:year+, +:mon+, +:mday+ and, for a
+      # timestamp, +:hour+, +:min+, +:sec+, +:sec_fraction+, +:offset+
+      def parse: (::String value) -> ::Hash[::Symbol, Object]
+
+      # Render a coerced value back to RFC 3339.
+      # 
+      # _@param_ `value` — the coerced value
+      def render: ((::Date | ::Time | ::DateTime) value) -> ::String
+
+      # _@param_ `match` — a {DATE} match
+      def date_parts: (::MatchData match) -> ::Hash[::Symbol, ::Integer]
+
+      # _@param_ `match` — a {TIMESTAMP} match
+      def timestamp_parts: (::MatchData match) -> ::Hash[::Symbol, Object]
+
+      # _@param_ `text` — the +.digits+ capture, if any
+      # 
+      # _@return_ — seconds after the whole second, exact
+      def fraction_from: (::String? text) -> ::Rational
+
+      # _@param_ `text` — the offset capture: +Z+ or +±hh:mm+ / +±hhmm+
+      # 
+      # _@return_ — seconds east of UTC
+      def offset_from: (::String text) -> ::Integer
+
+      # _@param_ `value`
+      # 
+      # _@return_ — +".123"+, or empty when the value is on a whole second
+      def fraction_of: ((::Time | ::DateTime) value) -> ::String
+
+      # _@param_ `value`
+      # 
+      # _@return_ — +"Z"+ for UTC, otherwise +"+HH:MM"+
+      def offset_of: ((::Time | ::DateTime) value) -> ::String
+
+      # _@return_ — +:date+ or +:timestamp+
+      attr_reader kind: ::Symbol
+    end
+
+    # Generic preset resolution for a single named option on a single
+    # type. Symbol values are looked up in the supplied presets hash;
+    # anything else passes through. Unknown preset names raise
+    # +ArgumentError+ at field-declaration time.
+    # 
+    # Used by string-shaped types (Email/UUID/URL) for +format:+ and by
+    # time-shaped types (Date/Time/DateTime) via {TimeFormatResolver}
+    # (which adds a stricter set of allowed value types).
+    module PresetResolver
+      # Resolve +options[key]+ when it's a Symbol preset name, leaving other
+      # values untouched.
+      # 
+      # _@param_ `options` — the per-field options
+      # 
+      # _@param_ `key` — the option to resolve (e.g. +:format+)
+      # 
+      # _@param_ `presets` — preset name → concrete value
+      # 
+      # _@param_ `label` — used in the unknown-preset error message
+      # 
+      # _@return_ — options with +key+ resolved (a copy when changed)
+      def self.call: (
+                       ::Hash[::Symbol, Object?] options,
+                       ::Symbol key,
+                       ::Hash[::Symbol, Object] presets,
+                       label: ::String
+                     ) -> ::Hash[::Symbol, Object?]
+    end
+
+    # Shared String-parsing rules for {Date}, {Time} and {DateTime}.
+    # 
+    # Three rules the stdlib parsers leave to their caller. Each of them is a
+    # case where the stdlib answers a question it was not asked, confidently.
+    # 
+    # **Anchoring.** +strptime+ matches a PREFIX and discards the rest.
+    # +Date.strptime('2026-07-031', '%Y-%m-%d')+ returns the 3rd and throws the
+    # trailing +1+ away; +'2026-07-03T10:30:00+0000-NONSENSE'+ parses clean
+    # under the +iso8601+ preset. A declared +format:+ is a contract about the
+    # whole string, so anything left over is refused. (Leading whitespace needs
+    # no rule — +Date._strptime+ already returns +nil+ for it.)
+    # 
+    # **Civil validity.** +Date.strptime+ and +DateTime.strptime+ refuse the
+    # 30th of February. +Time+ does not: +Time.parse+, +Time.strptime+ and
+    # +Time.new+ all roll it forward to 2 March and say nothing. All three
+    # types refuse it here.
+    # 
+    # **Completeness.** With no declared format the stdlib parsers fill in
+    # whatever the string omits, from *today*: +Time.parse('10:30')+ is today
+    # at 10:30, +'July'+ is the 1st of July this year, +'12'+ is the 12th of
+    # this month. A value whose meaning depends on when it was parsed is not a
+    # value, so a string with no declared format must name a whole day.
+    # 
+    # Anchoring is trailing-junk rejection and nothing more. Widths, sign and
+    # case stay strptime-lenient for a hand-written format: +%m+ and +%d+
+    # accept one or two digits, which is strptime's contract rather than a
+    # defect. Strictness for the built-in presets is a separate concern.
+    module TemporalParser
+      # Validate a String against a declared format.
+      # 
+      # _@param_ `value` — the raw string
+      # 
+      # _@param_ `format` — a resolved strftime/strptime format
+      # 
+      # _@return_ — the parsed fragments
+      def self.strptime_parts: (::String value, ::String format) -> ::Hash[::Symbol, Object]
+
+      # Validate a String with no declared format.
+      # 
+      # _@param_ `value` — the raw string
+      # 
+      # _@return_ — the parsed fragments
+      def self.parse_parts: (::String value) -> ::Hash[::Symbol, Object]
+
+      # _@param_ `parts` — fragments from +Date._parse+
+      def self.ensure_whole_day!: (::Hash[::Symbol, Object] parts) -> void
+
+      # _@param_ `parts` — fragments from +Date._parse+ or +Date._strptime+
+      def self.ensure_real_day!: (::Hash[::Symbol, Object] parts) -> void
+    end
+
+    # Like {Types::String}, but the coerced value is frozen. Useful when
+    # downstream code must not mutate a stored string.
+    class ImmutableString < FieldStruct::Types::String
+      # _@param_ `value` — anything stringable; +nil+ stays +nil+
+      # 
+      # _@return_ — frozen string, or +nil+ if input is +nil+
+      def coerce: (_ToS? value) -> ::String?
+    end
+
+    # Shared +format:+ option resolution for {Date}/{Time}/{DateTime}.
+    # Each of those types calls +TimeFormatResolver.call(options, presets)+
+    # from its +resolve_options+ class method.
+    # 
+    # A declared +format:+ is VALIDATED at declaration time and kept exactly as
+    # the user wrote it; it is resolved to a strftime string later, at coerce
+    # and render time, by {.resolve}.
+    # 
+    # Keeping the declaration is the point. The Symbol used to be overwritten
+    # with the strftime String it expands to, which destroyed the only fact a
+    # documentation generator actually wants — that the field is +:iso8601+,
+    # not some anonymous String of percent-escapes. Recovering the name by
+    # reverse-mapping the String worked only while no two presets shared a
+    # value, which is luck rather than a contract.
+    module TimeFormatResolver
+      # Validate a declared +format:+ and return the options unchanged.
+      # 
+      # _@param_ `options` — the per-field options as written
+      # 
+      # _@param_ `presets` — the type's preset table
+      # 
+      # _@return_ — +options+, unmodified
+      def self.call: (::Hash[::Symbol, Object?] options, ::Hash[::Symbol, ::String] presets) -> ::Hash[::Symbol, Object?]
+
+      # Resolve a declared +format:+ to a strftime/strptime String.
+      # 
+      # _@param_ `format` — as declared
+      # 
+      # _@param_ `presets` — the type's preset table
+      # 
+      # _@return_ — +nil+ when no format is declared
+      def self.resolve: ((::String | ::Symbol)? format, ::Hash[::Symbol, ::String] presets) -> ::String?
+    end
+  end
+
+  # Minimal ActiveModel::Name-shaped value for {Base.model_name}.
+  # 
+  # We mirror only what Rails-adjacent callers commonly reach for:
+  # +name+, +singular+, +plural+, +element+, and string coercion.
+  # No ActiveModel code is reused; pluralization is naive +s+-suffix
+  # English. If a richer Name is needed, a downstream gem can build on
+  # this without changing the surface.
+  class ModelName
+    # _@param_ `class_name`
+    def initialize: (String? class_name) -> void
+
+    def to_s: () -> String
+
+    # _@param_ `str` — a bare class name
+    # 
+    # _@return_ — its snake_case form
+    def camel_to_snake: (String str) -> String
+
+    # _@return_ — the fully-qualified class name (or "" for anonymous classes)
+    attr_reader name: String
+
+    # _@return_ — last segment, snake_case (e.g. "user_account")
+    attr_reader singular: String
+
+    # _@return_ — naive +s+-suffixed plural of {#singular}
+    attr_reader plural: String
+
+    # _@return_ — same as {#singular} (the AM convention for last segment)
+    attr_reader element: String
+  end
+end