permittable 0.11.1 → 0.12.0

data/lib/permittable.rb

@@ -132,10 +132,14 @@ 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.
+# 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.
@@ -190,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
@@ -248,6 +254,18 @@ module Permittable
   # 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?).
@@ -690,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)
@@ -831,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
@@ -863,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
@@ -871,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.
@@ -879,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)
@@ -898,8 +935,8 @@ module Permittable
     def cast_decimal(value)
       case value
       when Rational then rational_to_decimal(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 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
@@ -920,13 +957,38 @@ module Permittable
       finite_decimal(BigDecimal("#{value.numerator * (10**scale) / denominator}e-#{scale}"))
     end
 
-    # BigDecimal has no exponent limit, so a :decimal cannot overflow — but
     # 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)
@@ -945,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)
@@ -967,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)
@@ -989,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.
     #
@@ -1073,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
@@ -1116,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
@@ -1246,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
@@ -1258,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
@@ -1268,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 " \
@@ -1542,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
@@ -1572,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
@@ -2423,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)
@@ -2445,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]
@@ -2484,8 +2792,8 @@ module Permittable
       value.all? { |key, record| key.to_s.match?(/\A-?\d+\z/) && record.is_a?(Hash) }
   end
 
-  # Coercion.check_json, with the copy the result needs made in the middle.
-  # The opaque hash is handed over whole, and HashWithIndifferentAccess
+  # 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
@@ -2511,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