permittable 0.11.0 → 0.12.0

data/lib/permittable.rb

@@ -132,11 +132,16 @@ require "permittable/filter_parameter_registry"
 # ("   " under :squish) cannot satisfy a required field by becoming "". An
 # authored `default:`/`example:` is stored as the contract reads it —
 # normalized and cast, so `default: "18"` on an :integer is 18, and an
-# array's read by the request walker itself. The one exception is a field
-# declaring `transform:`: its default is stored exactly AS AUTHORED, never
+# array's read by the request walker itself. The exceptions: a field
+# declaring `transform:` stores its default exactly AS AUTHORED, never
 # cast — `transform:` never runs on a default either (see OUTPUT RESHAPING),
-# so author such a default already in the shape the action should receive.
-# Either way it is deep-frozen on a copy, and each request gets its own deep
+# so author such a default already in the shape the action should receive —
+# and a `:json` field's is always stored as the walker reads a request's hash
+# (indifferent access, String keys; `transform:` or not), except that a
+# `:json` `example:` is stored as authored (in that same shape), whatever a
+# mutating `validate:` did to the copy it was checked on.
+# An `example:` is cast either way and never transformed: it documents what a
+# client sends. Either way it is deep-frozen on a copy, and each request gets its own deep
 # copy, so no request can corrupt it for the next.
 #
 # `nullable: true` splits that rule in two for one field, which is how a PATCH
@@ -189,8 +194,10 @@ require "permittable/filter_parameter_registry"
 #     into an Array. Runs only on request-supplied values: absent fields stay
 #     absent, and a `default:` is handed out exactly AS AUTHORED — validated
 #     against the field's own contract at class load (as any default is), but
-#     neither cast nor transformed — so a request sending a field's default
-#     gets the transformed value, a request omitting it the untransformed one.
+#     neither cast nor transformed (a `:json` field's is read as a request's
+#     hash is, indifferent with String keys, but no more than that) — so a
+#     request sending a field's default gets the transformed value, a
+#     request omitting it the untransformed one.
 #     Author a default already in the shape the action should receive:
 #     `transform: ->(v) { v.to_i }, default: 25` on a :string field hands both
 #     paths the Integer 25. A field with no `transform:` still gets its
@@ -226,20 +233,39 @@ module Permittable
   # unknown-keys check must not flag them.
   ROUTING_KEYS = %w[controller action format].freeze
   # Nor the keys an ordinary form POST carries — the CSRF token, the verb
-  # override, the encoding probe, and the submit button's name. Without this
-  # `unknown: :error` was unusable outside a JSON API: every browser form
-  # failed on the framework's own keys rather than on anything the client got
-  # wrong. Exempt from the CHECK only: unlike the routing keys these are NOT
-  # stripped from monitor mode's raw pass-through, where handing back an
-  # untouched params hash is the whole promise and a legacy action may well
-  # read `_method` itself.
-  FORM_KEYS = %w[authenticity_token _method utf8 commit].freeze
+  # override, the encoding probe, and the submit button's name: `commit` from
+  # f.submit/submit_tag, `button` from f.button/button_tag (which render
+  # <button name="button">, so a browser sends `button=` even with no
+  # value). Without this `unknown: :error` was unusable outside a JSON API:
+  # every browser form failed on the framework's own keys rather than on
+  # anything the client got wrong. Exempt from the CHECK only: unlike the
+  # routing keys these are NOT stripped from monitor mode's raw
+  # pass-through, where handing back an untouched params hash is the whole
+  # promise and a legacy action may well read `_method` itself.
+  #
+  # The click point of an image submit (image_submit_tag, which has no name
+  # of its own to exempt) is a form key too, but not a fixed one: `x` and `y`,
+  # or `<name>.x` and `<name>.y`, as a PAIR of digits. See
+  # permittable_image_submit_keys.
+  FORM_KEYS = %w[authenticity_token _method utf8 commit button].freeze
   # ROUTING_KEYS/FORM_KEYS name where the keys come FROM; these two name what
   # is DECIDED with them, which is what the call sites care about — and the
   # asymmetry between them is the deliberate point, so spell it once here
   # rather than leaving a bare ROUTING_KEYS to read like an oversight.
   UNCHECKED_TOP_LEVEL_KEYS = (ROUTING_KEYS + FORM_KEYS).freeze
   MONITOR_DROPPED_KEYS = ROUTING_KEYS
+  # Rails' date_select, datetime_select and time_select submit ONE value as
+  # several keys, each named for its position: `starts_on(1i)` the year,
+  # `(2i)` the month, `(3i)` the day, `(4i)` the hour, `(5i)` the minute and
+  # `(6i)` the second. Strong parameters passes them through for
+  # `permit(:starts_on)` and ActiveRecord assembles them. A contract read
+  # only `starts_on`, so such a form lost its date (silently, under the
+  # default `unknown: :ignore`) and a required one was always missing. A
+  # :date or :datetime field now reads its parts as its own value (see
+  # permittable_read_date_parts); this is how many parts each type has.
+  DATE_PARTS = { date: 3, datetime: 6 }.freeze
+  # One part, as a select sends it: an unsigned decimal integer.
+  DATE_PART_FORMAT = /\A\d+\z/
   # The field kinds that can hold ParamsWrapper's copy of a body — a hash. A
   # rootless contract declaring the wrapper key as one of these reads the
   # copy deliberately, so it is kept (see permittable_drops_wrapper_copy?).
@@ -616,6 +642,12 @@ module Permittable
     class_attribute :permittable_contracts, instance_accessor: false, default: []
 
     rescue_from InvalidParameters, with: :render_invalid_parameters if respond_to?(:rescue_from)
+    # Registered here, at the include, and not at the first `permit_params`:
+    # the README documents `skip_before_action :enforce_params_contract`, and
+    # Rails raises when it is asked to skip a callback that is not defined
+    # yet. The cost is the order: this check runs before any callback
+    # declared after the include (see the README's "Per-request locales"),
+    # so a locale switch that must cover it is a `prepend_around_action`.
     before_action :enforce_params_contract if respond_to?(:before_action)
   end
 
@@ -676,17 +708,10 @@ module Permittable
     # Free-form hash. The shape is deliberately undeclared, so the only
     # checks are the bounds the field asked for: breadth (`length:`, the
     # top-level key count, same reading as an array's element count) and
-    # nesting (`max_depth:`). Shared with macro-time `default:`/`example:`
-    # checking, like check_scalar.
-    def check_json(field, value)
-      status, code = check_json_bounds(field, value)
-      return [status, code] unless status == :ok
-
-      check_custom(field[:validate], value)
-    end
-
-    # The structural half of check_json, which the request walker runs on
-    # its own so that it can copy an accepted hash before app code sees it.
+    # nesting (`max_depth:`). The walker (permittable_check_json) runs them
+    # before `validate:`, so that it can copy an accepted hash before app
+    # code sees it, and an authored `default:`/`example:` goes through that
+    # walker too (see AuthoredValues).
     def check_json_bounds(field, value)
       return [:error, "invalid_type"] unless value.is_a?(Hash)
       return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
@@ -817,7 +842,8 @@ module Permittable
       # here (a plain :string field, not :decimal itself) must render the same
       # way regardless of whether that patch happens to be loaded.
       when BigDecimal then [:ok, value.to_s("F")]
-      when Numeric, true, false then [:ok, value.to_s]
+      when Numeric then foreign_numeric { [:ok, value.to_s] }
+      when true, false then [:ok, value.to_s]
       else [:error, "invalid_type"]
       end
     end
@@ -849,7 +875,19 @@ module Permittable
 
     def cast_float(value)
       case value
-      when Numeric then finite_float(value.to_f)
+      # A Complex is not real? (a real number), so never a Float — even Complex(1, 0),
+      # which :integer and :decimal refuse too ("1+0i" is no spelling of either).
+      # Taking the ones whose to_f happens to work would make the rule "the
+      # imaginary part is an exact zero": Complex(1, 0.0).to_f raises RangeError
+      # just as Complex(1, 1) does, and a contract must not raise on input.
+      #
+      # A zero Numeric is a genuine zero; one that only BECAME zero in to_f
+      # (BigDecimal("1e-400"), Rational(1, 10**400)) is underflow, exactly as
+      # for the String of it, so a nonzero one passes its text for the check.
+      when Numeric
+        foreign_numeric do
+          value.real? ? finite_float(value.to_f, source: (value.to_s unless value.zero?)) : [:error, "invalid_type"]
+        end
       when String then value.match?(NUMERIC_FORMAT) ? finite_float(Float(value), source: value) : [:error, "invalid_type"]
       else [:error, "invalid_type"]
       end
@@ -857,6 +895,18 @@ module Permittable
       [:error, "invalid_type"]
     end
 
+    # The Numeric branches call to_f, to_s and zero? on a value whose class
+    # the caller chose: Complex(1, 1).to_f raises RangeError, and a custom
+    # Numeric may raise anything. A value that cannot be converted is not a
+    # value of the type, so it is an invalid_type violation rather than an
+    # exception out of #call (a 500 where a 422 is due). Wrapped around the
+    # Numeric branches only; the other branches call nothing a caller wrote.
+    def foreign_numeric
+      yield
+    rescue StandardError
+      [:error, "invalid_type"]
+    end
+
     # A Float that is not finite does not represent what was sent. "1e400"
     # overflows to Infinity and "1e-400" underflows to zero — both silently,
     # and both leaving a value no column can faithfully store.
@@ -865,7 +915,8 @@ module Permittable
     # an ordinary 0.0: a zero result is rejected when the string it came from
     # named a nonzero SIGNIFICAND. Only the significand, because "0e10" is a
     # genuine zero whose exponent digits say nothing about the value — as are
-    # "0", "0.0" and "0.0000".
+    # "0", "0.0" and "0.0000". A Numeric is checked the same way, by its to_s
+    # (see cast_float).
     def finite_float(result, source: nil)
       return [:error, "invalid_type"] unless result.finite?
       return [:error, "invalid_type"] if result.zero? && nonzero_significand?(source)
@@ -879,23 +930,65 @@ module Permittable
       source.split(/[eE]/, 2).first.match?(/[1-9]/)
     end
 
+    # Rational#to_s is "1/2", which BigDecimal() cannot read, so the generic
+    # Numeric branch refused every Rational, even a whole one (3r).
     def cast_decimal(value)
       case value
-      when Numeric then finite_decimal(BigDecimal(value.to_s))
-      when String then value.match?(NUMERIC_FORMAT) ? finite_decimal(BigDecimal(value)) : [:error, "invalid_type"]
+      when Rational then rational_to_decimal(value)
+      when Numeric then foreign_numeric { finite_decimal(BigDecimal(value.to_s)) }
+      when String then value.match?(NUMERIC_FORMAT) ? finite_decimal(BigDecimal(value), source: value) : [:error, "invalid_type"]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
       [:error, "invalid_type"]
     end
 
-    # BigDecimal has no exponent limit, so a :decimal cannot overflow — but
+    # A Rational is exactly a decimal only when its reduced denominator has
+    # no prime factor but 2 and 5 (1/2, 3/40), and then it divides 10**k for
+    # k = its bit length, which is at least the exponent of either factor.
+    # Anything else (1/3) has no finite expansion, so a BigDecimal could hold
+    # it only rounded at a precision this gem would have to pick. That is the
+    # guess every other coercion here refuses, so it is invalid_type.
+    def rational_to_decimal(value)
+      denominator = value.denominator
+      scale = denominator.bit_length
+      return [:error, "invalid_type"] unless ((10**scale) % denominator).zero?
+
+      finite_decimal(BigDecimal("#{value.numerator * (10**scale) / denominator}e-#{scale}"))
+    end
+
     # BigDecimal("NaN") and BigDecimal("Infinity") SUCCEED where Float()
     # raises, so a client could send the literal string "NaN" for a price and
     # have it stored. Nothing else in the gem disagreed with itself this
     # loudly: :float rejected those strings and :decimal did not.
-    def finite_decimal(result)
-      result.finite? ? [:ok, result] : [:error, "invalid_type"]
+    #
+    # BigDecimal's exponent is far wider than a Float's, but it is bounded:
+    # "1e99999999999999999999" overflows to Infinity, refused above, and
+    # "1e-99999999999999999999" underflows to zero — silently, like a Float,
+    # so the same nonzero-significand rule as finite_float applies.
+    def finite_decimal(result, source: nil)
+      return [:error, "invalid_type"] unless result.finite?
+      return [:error, "invalid_type"] if result.zero? && nonzero_significand?(source)
+      return [:error, "invalid_type"] if source && amplified?(result, source)
+
+      [:ok, result]
+    end
+
+    # How many digits a :decimal's plain form may run to beyond what the
+    # client actually sent. See amplified?.
+    DECIMAL_DIGIT_ALLOWANCE = 1_000
+
+    # BigDecimal keeps a huge exponent exactly: "1e4000000000000000000" is 22
+    # bytes and a finite value. But a database adapter quoting it, JSON
+    # rendering, BigDecimal#to_s and a log line all build its plain form,
+    # which is NoMemoryError there — and with a smaller exponent
+    # ("1e1000000000"), a gigabyte string from a dozen bytes of request.
+    # So a String whose plain form would run past both a thousand digits and
+    # its own length is refused: "1e400" and "1e-999" still cast, and so
+    # does any number spelled out digit by digit, however long, since the
+    # request already paid for every digit.
+    def amplified?(result, source)
+      result.exponent.abs > [DECIMAL_DIGIT_ALLOWANCE, source.length].max
     end
 
     def cast_boolean(value)
@@ -914,6 +1007,15 @@ module Permittable
     # ("2026-09-05", "2026/09/05", "Sep 5, 2026") still works.
     def cast_date(value)
       case value
+      # Ahead of Date, which DateTime subclasses: `when Date` handed a
+      # DateTime back whole, time of day included, so `default:
+      # DateTime.new(2026, 1, 5, 12)` was stored as noon and exported as a
+      # date-time under `format: date` — while a Time was refused outright,
+      # and an in: member was read as an instant. Every instant is now read
+      # the way that member is (see date_of_instant).
+      when Time, DateTime
+        date = date_of_instant(value)
+        date ? [:ok, date] : [:error, "invalid_type"]
       when Date then [:ok, value]
       when String
         found = Date._parse(value)
@@ -936,6 +1038,19 @@ module Permittable
       found.key?(:year) && found.key?(:mon) && found.key?(:mday)
     end
 
+    # The date a Time or DateTime IS, or nil: its UTC date when it is
+    # exactly midnight UTC. That is the instant ActiveSupport compares a
+    # Date as, and the one :datetime reads a Date as, so the two types map
+    # onto each other and back. Any other instant has a time of day, which
+    # a Date cannot hold, so it is not a date at all — the answer a Time
+    # with a time of day always got. Shared by cast_date and
+    # instant_as_date, so a value and an in: member cannot be read
+    # differently; and always a plain Date, never the DateTime it came as.
+    def date_of_instant(instant)
+      utc = instant.to_time.getutc
+      utc.to_date if utc == utc.beginning_of_day
+    end
+
     # A zoneless String parses as UTC regardless of the host timezone
     # (deterministic); explicit offsets are honoured and normalised to UTC.
     def cast_datetime(value)
@@ -958,13 +1073,36 @@ module Permittable
         # Time from components would have to reimplement DateTime.parse's
         # handling of offsets, zone names and sub-second precision, and
         # getting that subtly wrong costs more than the parse.
-        complete_date?(Date._parse(value)) ? [:ok, DateTime.parse(value).to_time.utc] : [:error, "invalid_type"]
+        #
+        # Parsed in the proleptic Gregorian calendar, which is what ISO 8601
+        # and Time use. DateTime.parse defaults to the 1582 Italian reform
+        # and read an earlier date as Julian; stdlib's DateTime#to_time then
+        # converts by day number, so "1500-01-01" became 1500-01-10 — unless
+        # the host had loaded ActiveSupport's DateTime#to_time, which
+        # converts by component. Gregorian, both agree.
+        found = Date._parse(value)
+        return [:error, "invalid_type"] unless complete_date?(found) && honoured_zone?(found)
+
+        [:ok, DateTime.parse(value, true, Date::GREGORIAN).to_time.utc]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError, RangeError
       [:error, "invalid_type"]
     end
 
+    # A zone the parser could not turn into an offset — an offset of a day
+    # or more ("+24:00", "-99:00", "+99") or an abbreviation it does not
+    # know ("XYZ") — is reported as a zone with no offset, or with one
+    # beyond a day, and DateTime.parse then reads the wall clock as UTC: an
+    # instant hours away from the one the client named. The client stated a
+    # zone, so it is refused rather than guessed at.
+    def honoured_zone?(found)
+      return true unless found.key?(:zone)
+
+      offset = found[:offset]
+      !offset.nil? && offset.abs < 86_400
+    end
+
     # Presets only make sense on String input; a non-String value (JSON
     # numbers, booleans) skips normalization and goes straight to the cast.
     #
@@ -1042,41 +1180,58 @@ module Permittable
     end
 
     # The members of an `in:` that is a LIST, or nil when it is not one.
-    # Only Array, Set, Hash and Enumerator count, and only when the object's
-    # OWN class provides the collection's ordinary include? — not a Hash,
-    # Array or Set SUBCLASS overriding it (a case-insensitive allowlist, a
-    # fuzzy Set, a registry matching some other way entirely). `case allowed;
-    # when Hash ...` matches with ===, which for a Class is is_a?, so a
-    # subclass would otherwise match its ancestor's branch and have its
-    # override silently discarded — read for its raw keys/elements instead,
-    # which can invert which values it actually accepts. It is left opaque
-    # instead, exactly like any other object whose include? is the point
-    # (see resolve_in!) and enumerating it may be expensive (a DB-backed
+    # Only Array, Set, Hash and Enumerator count, and only when the object
+    # answers with the collection's ordinary include? — not one a Hash,
+    # Array or Set SUBCLASS overrides (a case-insensitive allowlist, a fuzzy
+    # Set, a registry matching some other way entirely). `case allowed; when
+    # Hash ...` matches with ===, which for a Class is is_a?, so a subclass
+    # would otherwise match its ancestor's branch and have its override
+    # silently discarded — read for its raw keys/elements instead, which can
+    # invert which values it actually accepts. It is left opaque instead,
+    # exactly like any other object whose include? is the point (see
+    # resolve_in!) and enumerating it may be expensive (a DB-backed
     # registry).
     #
+    # So the test is which module OWNS include?, not the object's exact
+    # class. A subclass that keeps its base's include? answers exactly what
+    # its keys or elements say, and is a list like its base. Rails'
+    # `config_for(:plans)` returns one, an ActiveSupport::OrderedOptions:
+    # an exact-class test left it opaque, so `include?("pro")` asked about
+    # its Symbol keys and every request was refused.
+    #
     # A Hash lists its KEYS, which is what Hash#include? asks about — the
     # Rails enum idiom, `in: Post.statuses` — and, like a Set, is stored as a
     # Set, so membership stays O(1) per request.
-    # ActiveSupport::HashWithIndifferentAccess is the one Hash subclass
-    # accepted anyway: its include? override only canonicalises the argument
-    # (String/Symbol) before the SAME key lookup, so its keys are still
-    # exactly its members — and it is what a Rails enum's own reader
-    # (`Post.statuses`) actually returns.
+    # ActiveSupport::HashWithIndifferentAccess is the one include? override
+    # accepted anyway: it only canonicalises the argument (String/Symbol)
+    # before the SAME key lookup, so its keys are still exactly its members
+    # — and it is what a Rails enum's own reader (`Post.statuses`) actually
+    # returns.
     # Enumerator::Lazy is the same story on the Enumerator side: Lazy
     # overrides chain methods like map and select, but not include?, so it
     # is still read as a list — and forced to an Array here, once, since
     # left lazy it would be cast on every request instead of at class load.
     def in_list(allowed)
       case allowed
-      when Hash then allowed.keys.to_set if plain_hash?(allowed)
-      when Set then allowed if allowed.instance_of?(Set)
-      when Array then allowed.to_a if allowed.instance_of?(Array)
-      when Enumerator then allowed.to_a if allowed.method(:include?).owner == Enumerable
+      when Hash then allowed.keys.to_set if include_from?(allowed, Hash, ActiveSupport::HashWithIndifferentAccess)
+      when Set then allowed if include_from?(allowed, Set)
+      when Array then allowed.to_a if include_from?(allowed, Array)
+      when Enumerator then allowed.to_a if include_from?(allowed, Enumerator)
       end
     end
 
-    def plain_hash?(allowed)
-      allowed.instance_of?(Hash) || allowed.instance_of?(ActiveSupport::HashWithIndifferentAccess)
+    # Whether `allowed` answers include? as one of `bases` itself does. What
+    # is compared is the owner the BASE class reports, not a literal class:
+    # a gem that prepends a module defining include? into Array, Hash or Set
+    # (an instrumenting one) makes that module the owner for every instance,
+    # and a test against the literal class then read every plain
+    # `in: %i[draft published]` as an object with an include? of its own,
+    # used it as given, and refused "draft". A prepended module is the
+    # base's own include?; a subclass, a singleton method or an `extend`
+    # still has a different owner.
+    def include_from?(allowed, *bases)
+      owner = allowed.method(:include?).owner
+      bases.any? { |base| base.instance_method(:include?).owner == owner }
     end
 
     # A Symbol is read as its String: it is how Ruby spells a constant
@@ -1085,20 +1240,34 @@ module Permittable
       member = member.to_s if member.is_a?(Symbol)
       return instant_as_date(member) if type == :date && (member.is_a?(Time) || member.is_a?(DateTime))
 
-      cast(type, member)
+      status, value = cast(type, member)
+      return [status, value] unless status == :ok && type == :datetime && !member.is_a?(String) && !whole_nanoseconds?(value)
+
+      [:error, "finer than a nanosecond, so it never equals a request; round it, e.g. with .round(9)"]
+    end
+
+    # A request's fraction of a second is a finite decimal, and the export
+    # prints a member to at most nine digits, so a member that is not a whole
+    # number of nanoseconds — Time.at(1.1) holds 1.10000000000000008881...,
+    # Time.utc(..., Rational(1, 3)) a third — was published as an enum value
+    # the server refuses and could never be matched. The :datetime analogue
+    # of instant_as_date. Only for a Time-like member: a String member is
+    # cast exactly as a request sending it is, and published as written, so
+    # whatever precision it spells is reachable.
+    def whole_nanoseconds?(time)
+      (time.subsec * 1_000_000_000).denominator == 1
     end
 
     # A Time or DateTime member of a :date field. ActiveSupport compares one
     # with a Date as INSTANTS, the Date standing for its midnight UTC, so
     # that instant is the only one that ever equalled a request's date. It
     # is read as that UTC date; any other instant never matched anything,
-    # and is refused like any member no request could equal. (cast_date
-    # would keep a DateTime whole — it IS a Date — and refuse a Time.)
+    # and is refused like any member no request could equal. cast_date
+    # reads it the same way (date_of_instant); this only gives the
+    # class-load error a reason where a request gets `invalid_type`.
     def instant_as_date(member)
-      utc = member.to_time.getutc
-      return [:error, "not midnight UTC, so it never equals a date"] unless utc == utc.beginning_of_day
-
-      [:ok, utc.to_date]
+      date = date_of_instant(member)
+      date ? [:ok, date] : [:error, "not midnight UTC, so it never equals a date"]
     end
 
     # What an exported enum lists for one member: the cast value, re-encoded
@@ -1199,6 +1368,7 @@ module Permittable
       validate_array_authored_value!(field, :default) if field.key?(:default)
       validate_array_authored_value!(field, :example) if field.key?(:example)
       validate_message!(field)
+      freeze_desc!(field)
       @fields << field
     end
 
@@ -1214,10 +1384,13 @@ module Permittable
     #   end
     #
     # `optional: true` relaxes every spliced field, which is how an update
-    # contract reuses a create contract: nothing is mandatory, but `default:`,
-    # types and bounds all still apply. It relaxes the TOP LEVEL only — if a
-    # client sends an address at all, the address's own required sub-fields
-    # still hold.
+    # contract reuses a create contract: nothing is mandatory, and types and
+    # bounds all still apply. It drops each relaxed field's `default:` too. A
+    # default is filled in for every request that omits the field, so on a
+    # PATCH it would overwrite the column the client left alone: `default:
+    # "free"` reset every "pro" user who only renamed themself. It relaxes
+    # the TOP LEVEL only — if a client sends an address at all, the
+    # address's own required sub-fields and defaults still hold.
     #
     # `only:`/`except:` select a subset, in the group's own order. Naming a
     # field the group doesn't declare is a class-load error, so a typo cannot
@@ -1226,7 +1399,7 @@ module Permittable
     # and then declare `:city` yourself.
     def use(group, only: nil, except: nil, optional: false)
       fields = select_group_fields!(group_fields!(group), only: only, except: except)
-      fields = fields.map { |field| field.merge(required: false).freeze } if optional
+      fields = fields.map { |field| field.except(:default).merge(required: false).freeze } if optional
       fields.each do |field|
         field_name!(field[:name])
         @fields << field
@@ -1236,7 +1409,22 @@ module Permittable
 
     private
 
+    # A Contract is usable as a group because it answers #fields — but its
+    # finalize is not a field, so splicing would drop the contract's
+    # cross-field rule: a standalone Booking contract rejecting an ends_on
+    # before its starts_on, used by a controller that then accepts it. That
+    # is the drift `use` exists to prevent, so it is refused here, loudly,
+    # the way a field group's own finalize is. Also under only:/except: — a
+    # finalize is opaque, so there is no part of it to keep — which the
+    # message says, since that is the first thing a user tries.
     def group_fields!(group)
+      if group.is_a?(Contract) && group.rule[:finalize]
+        raise ArgumentError, "#{LABEL}: use cannot carry a Permittable::Contract's finalize, so the contract's " \
+                             "cross-field rule would be silently dropped. Selecting fields with only:/except: " \
+                             "does not lift this: the finalize cannot be split, so it is refused for any part " \
+                             "of the contract. To share both, declare the fields in a Permittable.fields " \
+                             "group that the contract and this block each use, and declare finalize in each"
+      end
       return group.fields if group.respond_to?(:fields)
 
       raise ArgumentError, "#{LABEL}: use expects a field group (Permittable.fields { ... }) or anything " \
@@ -1275,6 +1463,7 @@ module Permittable
                   fields: nested_fields!(name, &block), **opts }
         field[:fields] = cascade_sensitive(field[:fields], field[:sensitive])
         validate_message!(field)
+        freeze_desc!(field)
       elsif type&.to_sym == JSON_TYPE
         assert_opts!(name, opts, JSON_OPTS)
         # `type:` is carried alongside `kind:` so the same `as(:json)` matcher
@@ -1379,6 +1568,7 @@ module Permittable
       validate_authored_value!(field, :default)
       validate_authored_value!(field, :example)
       validate_message!(field)
+      freeze_desc!(field)
     end
 
     # `in:` is a Range (bounds-checked with cover?), a list of values, or an
@@ -1394,19 +1584,34 @@ module Permittable
     # enum rule all read the members the runtime compares against. A member
     # no request value could ever equal is a contract mistake, and fails here
     # rather than as an `inclusion` on every request.
+    #
+    # An empty list or a reversed Range is refused for the same reason, but
+    # an object used as given is not asked: it is read on every request, so
+    # a live registry that is empty now (filled in an initializer or
+    # `after_initialize`, after `eager_load!` has run this) is the very use
+    # the README recommends it for.
     def resolve_in!(field)
       name = field[:name]
       allowed = field[:in]
       if allowed.is_a?(Range)
         assert_comparable_range!(field, allowed)
+        assert_satisfiable!(name, :in, allowed)
       elsif (members = Coercion.in_list(allowed))
         cast_in_members!(field, members)
+        assert_satisfiable!(name, :in, field[:in])
       elsif allowed.is_a?(String) || !allowed.respond_to?(:include?)
         raise ArgumentError, "#{LABEL}: :in for field :#{name} must be a Range, a list of values (an Array, Set, " \
                              "or a Hash read as its keys), or an object answering include? " \
                              "(got #{allowed.inspect})#{string_in_hint(allowed)}"
       end
-      assert_satisfiable!(name, :in, field[:in])
+    end
+
+    # An `in:` that is neither a Range nor a list the gem read and cast
+    # itself, so one resolve_in! kept exactly as given: its contents are the
+    # host's, and unknown at class load.
+    def live_in?(field)
+      allowed = field[:in]
+      !allowed.nil? && !allowed.is_a?(Range) && Coercion.in_list(allowed).nil?
     end
 
     def string_in_hint(allowed)
@@ -1484,6 +1689,7 @@ module Permittable
       validate_json_authored_value!(field, :default)
       validate_json_authored_value!(field, :example)
       validate_message!(field)
+      freeze_desc!(field)
     end
 
     def validate_max_depth!(name, depth)
@@ -1492,17 +1698,32 @@ module Permittable
       raise ArgumentError, "#{LABEL}: :max_depth for :#{name} must be a positive Integer"
     end
 
-    # Same rule as a scalar's authored value, over check_json: a `default:` or
-    # `example:` that its own bounds would reject fails at class load.
+    # Same rule as a scalar's authored value: a `default:` or `example:` that
+    # its own bounds would reject fails at class load. Like an array's, it is
+    # read by the request walker itself (see AuthoredValues), so it is checked
+    # as a request sending the same hash is. The raw Hash used to be checked
+    # instead: `validate: ->(p) { p[:theme] == "dark" }` passed a request's
+    # {"theme":"dark"}, which the walker reads indifferently, and refused the
+    # same Hash authored as `default:`. And a `validate:` that edits its
+    # argument edited the host's own Hash, which a request's deep copy spares.
+    #
+    # For a `default:` the walker's copy is what is stored, so the action, the
+    # export and the RSpec matcher all read what a request sending it would
+    # have produced. An `example:` is not: it documents what a client SENDS,
+    # so it is validated on that copy but stored as a fresh copy of the value
+    # AS AUTHORED (request-shaped, indifferent with String keys), which a
+    # `validate:` editing its argument cannot have added a key to or dropped
+    # one from. That matches every other example on a contract, which is never
+    # processed the way the action would see it.
     def validate_json_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
       raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
 
-      status, code = Coercion.check_json(field, field[opt])
-      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
+      status, read = AuthoredValues.read_json(field, field[opt])
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{read})" unless status == :ok
 
-      field[opt] = freeze_authored(field[opt])
+      field[opt] = freeze_authored(opt == :example ? ActiveSupport::HashWithIndifferentAccess.new(field[opt]) : read)
     end
 
     # format / length / normalize reason about characters; on any other
@@ -1522,10 +1743,33 @@ module Permittable
         raise ArgumentError, "#{LABEL}: :length for :#{name} must be a non-negative Integer or a Range " \
                              "(got #{length.inspect})"
       end
+      validate_length_ends!(name, length) if length.is_a?(Range)
 
       assert_satisfiable!(name, :length, length)
     end
 
+    # A length is a count, so each end of a Range is a non-negative whole
+    # number — an Integer, or a Float/Rational/BigDecimal with no fraction
+    # (`1..10.0` means ten) — or open: nil, or an infinite Float on its own
+    # side (`1..Float::INFINITY` predates endless Ranges). A negative end matched nothing (`..-1`
+    # rejected every value, forever, as the client's fault) or meant nothing
+    # (`-2..3` is `..3`), and a fractional one exported a minLength/maxLength
+    # the JSON Schema metaschema refuses — Ajv rejects the whole document.
+    def validate_length_ends!(name, length)
+      ok = length_end?(length.begin, -Float::INFINITY) && length_end?(length.end, Float::INFINITY)
+      return if ok
+
+      raise ArgumentError, "#{LABEL}: :length for :#{name} must have non-negative whole-number ends " \
+                           "(got #{length.inspect}); leave an end off for no bound, e.g. 1.. or ..80"
+    end
+
+    def length_end?(value, open)
+      return true if value.nil? || value == open
+      return false unless value.is_a?(Numeric) && value.real? && value.finite?
+
+      !value.negative? && value == value.to_i
+    end
+
     # A reversed Range (5..2), an exclusive Range with equal endpoints
     # (3...3), or an empty set (in: []) excludes every value there is, so the
     # field it bounds can never validate. That used to surface as every
@@ -1614,7 +1858,7 @@ module Permittable
     # same value gets, and what used to be thrown away: `default: "18"` used
     # to be handed to every request omitting it as the String "18", and
     # `:boolean, default: "false"` gave the app a truthy String.
-    # With a `transform:`, the value is stored exactly AS AUTHORED instead —
+    # With a `transform:`, a default is stored exactly AS AUTHORED instead —
     # `transform:` never runs on a default (see AuthoredValues), so casting it
     # here would silently change its type out from under an author who, per
     # the README, writes such a default in the shape the action should
@@ -1622,6 +1866,17 @@ module Permittable
     # :string field means the app gets the Integer 25 either way, whether the
     # request sent "25" (cast then transformed) or omitted the field
     # (authored as the already-final Integer).
+    #
+    # An `example:` is cast either way. It documents what a client SENDS and
+    # never reaches the action, so that reason does not apply to it: under
+    # `transform:` it used to be published uncast, `"type": "integer",
+    # "examples": ["18"]`, the very lie the cast exists to stop.
+    #
+    # The one rule not checked is `in:` when it is an object used as given
+    # (see resolve_in!): a live registry is empty at class load, so
+    # `in: LIVE, default: "order.paid"` would be refused for a member it will
+    # hold by the first request. What it will contain is unknown then, so its
+    # `include?` is not asked; every other rule is still checked.
     def validate_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
@@ -1630,10 +1885,10 @@ module Permittable
       # proc cannot rewrite the host's own literal.
       authored = field[opt].is_a?(String) ? field[opt].dup : field[opt]
       value = Coercion.apply_normalize(field[:normalize], authored)
-      status, result = Coercion.check_scalar(field, value)
+      status, result = Coercion.check_scalar(live_in?(field) ? field.except(:in) : field, value)
       raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{result})" unless status == :ok
 
-      field[opt] = freeze_authored(field[:transform] ? field[opt] : result)
+      field[opt] = freeze_authored(opt == :default && field[:transform] ? field[opt] : result)
     end
 
     # An array's authored value is validated by the REQUEST walker itself
@@ -1646,27 +1901,61 @@ module Permittable
     # cast only the top level of each element, and got every one of those
     # wrong.
     #
-    # What is STORED follows the same split as a scalar's: without
-    # `transform:`, the walker's read (exactly what a request sending it
-    # gets); with one, the array exactly AS AUTHORED — the walker still runs,
-    # so a declaration mistake (an element `validate:` refuses, a sub-field
-    # default out of bounds) still fails at class load, but its cast result
-    # is discarded rather than stored. The array's OWN `transform:` is
-    # deliberately never run on a default either way; a SUB-FIELD's
-    # `transform:` still runs during that walk, so "the walker's read" above
-    # really is what an equivalent request produces — see AuthoredValues.
+    # What is STORED for a default follows the same split as a scalar's:
+    # without `transform:`, the walker's read (exactly what a request sending
+    # it gets); with one, the array exactly AS AUTHORED — the walker still
+    # runs, so a declaration mistake (an element `validate:` refuses, a
+    # sub-field default out of bounds) still fails at class load, but its
+    # cast result is discarded rather than stored. The array's OWN
+    # `transform:` is deliberately never run on a default either way. A
+    # SUB-FIELD's `transform:` still runs during that walk, so "the walker's
+    # read" above really is what an equivalent request produces: all of them
+    # when the array has no `transform:` of its own, and, when it has one,
+    # those below an array declaring `validate:`, the only readers of their
+    # output (a request runs sub-field transforms, then that `validate:`,
+    # then the array's own transform) — see AuthoredValues.
+    #
+    # An `example:` is validated the same way, as a request would be, but what
+    # is STORED is a second read of it exactly as a client SENDS it: cast and
+    # normalized, with no `transform:` run at any depth and no sub-field
+    # `default:` filled in. Read through a sub-field's transform,
+    # `[{ price: "9.99" }]` under `transform: ->(d) { (d * 100).to_i }` was
+    # published as `[{ "price": 999 }]`: 100 times the price, and a `tags`
+    # split into an Array the server refuses. The two reads cannot be one: an
+    # array-level `validate:` must see the transformed sub-fields a request
+    # hands it (`i[:tags].is_a?(Array)`), so the validating read keeps them,
+    # and the stored read, which runs no `validate:`, discards them.
+    #
+    # The transforming read exists only for that `validate:`, so it runs only
+    # when one could consume it. Anywhere else its output is thrown away, yet
+    # it would still call app code at class load: `optional :id, :string,
+    # transform: ->(s) { Account.find(s) }` under an `example:` hit the
+    # database, or raised, at boot. Only an array carries a `validate:` that
+    # sees its transformed children: a scalar's or a :json field's runs on
+    # its own value before its own transform, and a nested hash takes none.
+    # Without one, the as-sent read both validates and is stored.
     def validate_array_authored_value!(field, opt)
       value = field[opt]
       return if authored_nil!(field, opt)
       raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
 
-      read, violations = AuthoredValues.read_array(field, value)
+      as_sent = opt == :example && !array_validate_in?(field)
+      read, violations = AuthoredValues.read_array(field, value, as_sent: as_sent)
       unless violations.empty?
         raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} violates its own contract: " \
                              "#{AuthoredValues.summary(violations)}"
       end
 
-      field[opt] = freeze_authored(field[:transform] ? value : read)
+      read, = AuthoredValues.read_array(field, value, as_sent: true) if opt == :example && !as_sent
+      field[opt] = freeze_authored(opt == :default && field[:transform] ? value : read)
+    end
+
+    # Whether `field`, or any array or nested hash below it, declares an
+    # array-level `validate:`.
+    def array_validate_in?(field)
+      return true if field[:kind] == :array && field[:validate]
+
+      Array(field[:fields]).any? { |sub| array_validate_in?(sub) }
     end
 
     # A contract is frozen data, but `@fields.map(&:freeze)` freezes only the
@@ -1705,6 +1994,18 @@ module Permittable
             "declare nullable: true to make an explicit null part of the contract"
     end
 
+    # `desc:` is exported as the schema's `description`, and was handed out
+    # by reference: a caller appending to a generated document's
+    # description (" (deprecated)", a gsub! for localisation) rewrote the
+    # contract inside the frozen rule, and every later export in the process
+    # carried the edit. Frozen as a copy, like message:, default: and
+    # example:, so the host's own String is left as it passed it. The
+    # exporters hand out an unfrozen `dup` of it, so editing a generated
+    # document in place works and still cannot reach the contract.
+    def freeze_desc!(field)
+      field[:desc] = freeze_authored(field[:desc]) unless field[:desc].nil?
+    end
+
     # `message:` customizes what the client reads for a violation on this
     # field: one String covering every code, or a Hash of code => String
     # (codes without an entry keep the default rendering). Keys are
@@ -1804,7 +2105,7 @@ module Permittable
 
       rule = { actions: actions.flatten.map(&:to_s).freeze, root: root && root.to_sym,
                model: model_class, unknown: unknown, enforce: !!enforce, mode: mode, fields: fields,
-               finalize: builder.finalizer, desc: desc }.freeze
+               finalize: builder.finalizer, desc: desc&.deep_dup&.freeze }.freeze
       self.permittable_contracts = permittable_contracts + [rule]
     end
 
@@ -1851,10 +2152,11 @@ module Permittable
 
       types = checked.to_h { |f| [f[:name], f[:type]] }
       allowed = checked.select { |f| f.key?(:in) }.to_h { |f| [f[:name], f[:in]] }
+      transformed = checked.select { |f| f[:transform] }.map { |f| f[:name].to_sym }
       begin
         ColumnGuard.ensure_columns_on!(LABEL, model_class, *checked.map { |f| f[:name] },
                                        types: types, check_types: Permittable.check_column_types,
-                                       allowed: allowed)
+                                       allowed: allowed, transformed: transformed)
       rescue ArgumentError => e
         # The type error carries its own guidance; only the missing-column one
         # needs the virtual: hint appended.
@@ -1929,10 +2231,33 @@ module Permittable
     return nil unless action
 
     rule = self.class.permit_rule_for(action)
-    permitted_params(action) if rule && (rule[:enforce] || permittable_mode(rule) == :monitor)
+    return nil unless rule
+
+    if permittable_mode(rule) == :monitor
+      permittable_monitor_eagerly(action)
+    elsif rule[:enforce]
+      permitted_params(action)
+    end
     nil
   end
 
+  # Monitor mode's promise is that the action runs, whatever the request
+  # holds — that is what makes it safe to turn on. Checking eagerly reads
+  # `params`, which raises ActionDispatch's ParseError on a body Rails
+  # cannot parse: a webhook action reading request.raw_post itself got a
+  # 400 instead of running. An exception from the contract's own code
+  # (validate:, transform:, finalize) became a 500 the same way. Either is
+  # now logged, by class only (a parse error's message can quote the body),
+  # and the action runs; one that reads permitted_params meets the same
+  # exception itself, as it would with no contract at all.
+  def permittable_monitor_eagerly(action)
+    permitted_params(action)
+  rescue StandardError => e
+    return unless respond_to?(:logger) && logger
+
+    logger.warn("#{LABEL}: [monitor] ##{action} could not be checked: #{e.class} — the action runs unchecked")
+  end
+
   # The violation details recorded by validating `action` (default: the
   # current action) — [] when the request satisfied the contract. Triggers
   # the same memoized validation as permitted_params, so under monitor mode
@@ -2292,6 +2617,7 @@ module Permittable
 
   def permittable_check_hash(fields, hash, path:, unknown:, top_level:, violations:)
     result = ActiveSupport::HashWithIndifferentAccess.new
+    hash = permittable_read_date_parts(fields, hash)
     fields.each do |field|
       key = field[:name].to_s
       full = permittable_path(path, key)
@@ -2314,6 +2640,119 @@ module Permittable
     result
   end
 
+  # See DATE_PARTS. A :date or :datetime field reads the parts sent for it
+  # as its own value. They are replaced, in a COPY of `hash`, by the one
+  # value they make, under the field's own key, so the walk sees exactly
+  # what it would have had the client sent that value: the cast, `in:`,
+  # `validate:`, `transform:`, the absence rule and `nullable:` all apply
+  # unchanged, the action gets the field's own key, and the unknown-keys
+  # check never sees the parts it read. `hash` itself is left as it is: it
+  # may be the request's own params, which monitor mode hands back as they
+  # arrived.
+  #
+  # Only when the field's own key is ABSENT. When both are sent, the key the
+  # contract declares wins the VALUE, and the parts are left in the copy,
+  # untouched, for the unknown-keys check to judge as it always has: flagged
+  # under `unknown: :error`, logged under `:log`, dropped under `:ignore`.
+  # They must not be consumed unread: strong parameters passes them through
+  # `permit(:starts_on)` (the legacy action of an `enforce: true` rollout) and
+  # ActiveRecord assigns multiparameter attributes AFTER the plain ones, so
+  # parts hidden from `unknown: :error` would overwrite the value the
+  # contract validated. And not when the contract declares one of the parts
+  # as a field of its own, which is how a contract could carry them through
+  # before this: that field keeps it.
+  def permittable_read_date_parts(fields, hash)
+    read = nil
+    fields.each do |field|
+      count = field[:kind] == :scalar && DATE_PARTS[field[:type]]
+      next unless count
+
+      key = field[:name].to_s
+      names = Array.new(count) { |index| "#{key}(#{index + 1}i)" }
+      next if hash.key?(key)
+      next unless names.any? { |name| hash.key?(name) }
+      next if fields.any? { |other| names.include?(other[:name].to_s) }
+
+      read ||= hash.dup
+      parts = {}
+      names.each.with_index(1) { |name, position| parts[position] = read.delete(name) if read.key?(name) }
+
+      # Parts that make no value are handed to the field as the several
+      # values they are, which a scalar refuses as invalid_type: on the
+      # field's own path, with its own message:, as for `?starts_on[]=x`.
+      read[key] = permittable_date_from_parts(parts, field[:type]) || parts.values
+    end
+    read || hash
+  end
+
+  # The ISO 8601 String that `parts` (keyed by Rails' positions, 1-3 the
+  # date and 4-6 the time) spell for a field of `type`, "" when they spell
+  # the field sent empty, or nil when they spell nothing at all. A String is
+  # what a :date or :datetime field already reads, so its cast and that
+  # cast's rules (a zoneless datetime is UTC) stay in one place.
+  #
+  # This follows ActiveRecord's own reading of the same parts
+  # (ActiveModel::Type::Date and DateTime cast them as a Hash): a value
+  # needs all of (1i)-(3i), and when any one of them is blank the attribute
+  # is nil, so the field reads as sent empty. That has to be ANY and not all
+  # of them: Rails fills a part it discards (discard_day, or the date of a
+  # time_select) through a hidden input, and the year and month selects of
+  # an untouched picker still sit on their prompts beside it, so the form
+  # arrives as {"(1i)" => "", "(2i)" => "", "(3i)" => "1"}. The time parts
+  # of a :datetime are the other way round: ActiveModel defaults a blank
+  # (4i), (5i) or (6i) to 00 once the date is there, and so does this. The
+  # blank part need only be among those SENT: ActiveModel reads a Hash with
+  # (2i) and (3i) but no (1i), or with (1i) and (2i) but no (3i), as nil when
+  # one of the ones it has is blank, and so does this. A part that is missing
+  # with no blank sibling is nil here, for a scalar to refuse as
+  # invalid_type, when it is one of (1i)-(3i): a time_select with
+  # `ignore_date:` sends only (4i) and (5i), and a :datetime needs a date.
+  # A MISSING (4i), (5i) or (6i) is 00 like a blank one, which is what
+  # ActiveModel does with {1 => 2026, 2 => 10, 3 => 17}: a date_select on a
+  # :datetime column, or a datetime_select with `discard_hour:`, sends the
+  # date alone, and (6i) comes with `include_seconds:` only.
+  # Whatever else is not an unsigned decimal integer is nil likewise.
+  def permittable_date_from_parts(parts, type)
+    return "" if (1..3).any? { |position| parts.key?(position) && Coercion.absent_value?(parts[position]) }
+
+    time = type == :datetime
+    digits = (1..3).map { |position| permittable_date_part(parts[position], year: position == 1) }
+    if time
+      # A time part that is blank or missing is 00, as ActiveModel reads it.
+      digits += (4..6).map do |position|
+        next "00" if !parts.key?(position) || Coercion.absent_value?(parts[position])
+
+        permittable_date_part(parts[position])
+      end
+    end
+    return nil if digits.include?(nil)
+
+    year, month, day, hour, minute, second = digits
+    time ? "#{year}-#{month}-#{day}T#{hour}:#{minute}:#{second}" : "#{year}-#{month}-#{day}"
+  end
+
+  # One part's digits, padded once its leading zeros are dropped: "7" and
+  # "007" are both "07". Joined as sent, Date._parse reads "2026-007-5" as
+  # May 7th. The year is padded to four digits, so "99" is the year 99 (as
+  # ActiveRecord reads it) rather than a two-digit year Date._parse places
+  # in 1999, and is otherwise left to the cast, as a year in a String is.
+  # Any other part has at most two digits: a month of "100" is no value a
+  # select offers, and Date._parse would read the string around it some
+  # other way. A non-negative Integer is the digits it prints: a JSON body or
+  # an `as: :json` request cannot send the String a form does, and
+  # ActiveRecord reads either. nil for anything that is not an unsigned
+  # decimal integer.
+  def permittable_date_part(part, year: false)
+    part = part.to_s if part.is_a?(Integer) && !part.negative?
+    text = Coercion.utf8_text(part) if part.is_a?(String)
+    return nil unless text&.match?(DATE_PART_FORMAT)
+
+    digits = text.sub(/\A0+(?=\d)/, "")
+    return digits.rjust(4, "0") if year
+
+    digits.rjust(2, "0") if digits.length <= 2
+  end
+
   def permittable_check_field(field, value, full, result, unknown:, violations:)
     key = field[:name].to_s
     case field[:kind]
@@ -2330,6 +2769,7 @@ module Permittable
         violations << permittable_violation(field, full, "invalid_type")
       end
     when :array
+      value = value.values if permittable_fields_for_records?(field, value)
       if value.is_a?(Array)
         result[key] = permittable_check_array(field, value, path: full, unknown: unknown, violations: violations)
       else
@@ -2338,8 +2778,22 @@ module Permittable
     end
   end
 
-  # Coercion.check_json, with the copy the result needs made in the middle.
-  # The opaque hash is handed over whole, and HashWithIndifferentAccess
+  # Whether `value` is an array of hashes sent the way Rails' fields_for
+  # sends one: `user[addresses_attributes][0][city]` reaches the params as a
+  # Hash keyed "0", "1", ... (or a timestamp, for a record added in the
+  # browser). Strong params permits exactly this shape (its
+  # fields_for_style?: every key an integer, every value a hash) and
+  # accepts_nested_attributes_for reads its values in order, so an
+  # `array ... do` field reads them as its elements. Paths then count the
+  # records in the order sent. An empty Hash, or one of scalars, is not this
+  # shape and stays invalid_type.
+  def permittable_fields_for_records?(field, value)
+    field[:fields] && value.is_a?(Hash) && !value.empty? &&
+      value.all? { |key, record| key.to_s.match?(/\A-?\d+\z/) && record.is_a?(Hash) }
+  end
+
+  # The bounds, then `validate:`, with the copy the result needs made in the
+  # middle. The opaque hash is handed over whole, and HashWithIndifferentAccess
   # rebuilt its containers but not the Strings inside them, so it is
   # deep-copied for the reason permittable_normalized copies a String — but
   # only once it is within its bounds. Copying first meant a megabyte
@@ -2365,19 +2819,31 @@ module Permittable
   end
 
   def permittable_check_array(field, value, path:, unknown:, violations:)
+    # A scalar array's "" elements are absent, as "" is for a field: the
+    # hidden `name="post[tag_ids][]" value=""` that collection_check_boxes
+    # and `select multiple: true` render, so that unchecking every box still
+    # sends the key, made every submit a 422 for `of: :integer`. Each kept
+    # element keeps the index the client sent it at, so violation paths
+    # still point into the request. A null element, which no form sends,
+    # is still refused.
+    blank = ->(element) { !field[:fields] && element.is_a?(String) && element.empty? }
+    count = field[:fields] ? value.length : value.length - value.count(&blank)
+
     # `length:` is a BOUND, not a report. An array outside it is rejected
     # whatever its contents, so checking those contents can only add work and
     # noise: a 200k-element payload against `length: 0..10` used to cast every
     # element, collect 200k more violations, and answer with a multi-megabyte
     # 422 — for a request already refused by its first check. Stopping here
-    # keeps the cost of an oversized array proportional to rejecting it.
-    if field[:length] && !Coercion.length_ok?(field[:length], value.length)
+    # keeps the cost of an oversized array proportional to rejecting it (the
+    # blank count above allocates nothing).
+    if field[:length] && !Coercion.length_ok?(field[:length], count)
       violations << permittable_violation(field, path, "length")
       return nil
     end
 
     before = violations.length
-    out = value.each_with_index.map do |element, index|
+    elements = value.each_with_index.reject { |element, _| blank.call(element) }
+    out = elements.map do |element, index|
       permittable_check_element(field, element, "#{path}[#{index}]", unknown: unknown, violations: violations)
     end
     # validate: and transform: see only a fully-valid array. A partially-nil
@@ -2400,8 +2866,9 @@ module Permittable
     # NOTHING violated, validate: included — a transform may rely on what
     # validate: checked (`Math.sqrt` after "all positive").
     elements_valid = violations.drop(before).all? { |v| permittable_unknown_key_violation?(v) }
-    if field[:validate] && elements_valid
-      status, code = Coercion.check_custom(field[:validate], out)
+    validator = permittable_array_validator(field)
+    if validator && elements_valid
+      status, code = Coercion.check_custom(validator, out)
       violations << permittable_violation(field, path, code) unless status == :ok
     end
     # Transform only a fully-valid array — a partially-nil one (element
@@ -2416,6 +2883,11 @@ module Permittable
     field[:transform] ? field[:transform].call(value) : value
   end
 
+  # A second seam, for the same reader: the array-level `validate:` to run.
+  def permittable_array_validator(field)
+    field[:validate]
+  end
+
   def permittable_check_element(field, element, path, unknown:, violations:)
     if field[:fields]
       unless element.is_a?(Hash)
@@ -2492,6 +2964,7 @@ module Permittable
     if top_level
       extra -= UNCHECKED_TOP_LEVEL_KEYS + permittable_request_supplied_keys
       extra -= [permittable_configured_csrf_key].compact
+      extra -= permittable_image_submit_keys(hash, extra)
     end
     return if extra.empty?
 
@@ -2517,6 +2990,33 @@ module Permittable
     request.path_parameters.keys.map(&:to_s)
   end
 
+  # The click point of an image submit among `keys` (the undeclared top-level
+  # keys). image_submit_tag renders <input type="image">, and a browser
+  # submitting through it posts where it was clicked: `x=12&y=7`, or
+  # `save.x=12&save.y=7` when the tag is named "save" (Rack keeps a dotted
+  # key as it is). Like the other FORM_KEYS these are the framework's own
+  # keys, so `unknown: :error` must not fail the form for them. Unlike them
+  # `x` and `y` are ordinary names a contract may really be sent, so a
+  # lone `x` is still flagged: a point is exempt only as a PAIR, both of
+  # them in `keys` (a declared `x` or `y` is not, and is checked as a field)
+  # and both digits, which is all a browser sends (coordinates are never
+  # negative or fractional). Read by bytes, since a client's key or value can
+  # be invalid UTF-8, which a regexp refuses to match, or another encoding
+  # altogether (a UTF-16 key makes `end_with?` raise).
+  def permittable_image_submit_keys(hash, keys)
+    by_bytes = keys.to_h { |key| [key.b, key] }
+    by_bytes.each_with_object([]) do |(bytes, key), point|
+      next unless bytes == "x" || bytes.end_with?(".x")
+
+      partner = by_bytes["#{bytes.delete_suffix('x')}y"]
+      point.push(key, partner) if partner && [key, partner].all? { |name| permittable_digits?(hash[name]) }
+    end
+  end
+
+  def permittable_digits?(value)
+    value.is_a?(String) && !value.empty? && value.each_byte.all? { |byte| byte.between?(48, 57) }
+  end
+
   # FORM_KEYS bakes in "authenticity_token" — Rails' DEFAULT CSRF parameter
   # name — but `config.action_controller.request_forgery_protection_token`
   # lets an app rename it, and an app that does trips `unknown: :error` on