permittable 0.8.0 → 0.9.0

data/lib/permittable.rb

@@ -1,3 +1,10 @@
+# Before active_support: on activesupport <= 7.0.8.4, requiring it raises
+# NameError (ActiveSupport::LoggerThreadSafeLevel::Logger) unless `logger` is
+# already loaded, because concurrent-ruby 1.3.5 stopped requiring it for them.
+# One stdlib require makes `require "permittable"` work on every activesupport
+# version the gemspec claims, whatever the host's own boot order.
+require "logger"
+
 require "active_support"
 require "active_support/concern"
 require "active_support/notifications"
@@ -22,6 +29,7 @@ require "active_support/core_ext/time/calculations"
 require "bigdecimal"
 require "date"
 require "time"
+require "uri" # URI::MailTo::EMAIL_REGEXP backs the :email format preset
 
 require "permittable/version"
 require "permittable/error_envelope"
@@ -74,6 +82,14 @@ require "permittable/filter_parameter_registry"
 # (db:create, assets:precompile) the check skips. In CI, one
 # `Rails.application.eager_load!` spec exercises every contract in the app.
 #
+# REUSING FIELDS — `Permittable.fields { ... }` builds a FieldGroup, a frozen
+# reusable field list, and the builder's `use` verb splices one in wherever
+# fields are declared (a contract, a nested block, another group). `use G,
+# optional: true` relaxes every spliced field, which is how an update contract
+# reuses a create contract; `only:`/`except:` select a subset. Because a group
+# is built by the same builder, its declarations are validated once, at the
+# group. See FieldGroup.
+#
 # Validation is LAZY: it runs on the first `permitted_params` call, so an
 # action that never reads params never pays. `enforce: true` installs the
 # check as a before_action instead (reject before the action body runs).
@@ -114,9 +130,14 @@ require "permittable/filter_parameter_registry"
 # absence. `normalize:` runs BEFORE that rule rather than inside the cast, so
 # there is exactly one reading of absence and a value that normalizes to empty
 # ("   " under :squish) cannot satisfy a required field by becoming "". An
-# authored `default:`/`example:` is stored normalized — the form it was
-# validated in — and deep-frozen on a copy, so no request can corrupt it for
-# the next.
+# 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
+# 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
+# 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
 # clears a column: a key the client never sent stays absent (defaults apply,
@@ -166,7 +187,14 @@ require "permittable/filter_parameter_registry"
 #     and validation to reshape that field's output, e.g.
 #     `transform: ->(v) { v.split(",") }` turns a validated delimited String
 #     into an Array. Runs only on request-supplied values: absent fields stay
-#     absent and `default:` values are authored in final shape.
+#     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.
+#     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
+#     default cast (see the module-level default:/example: paragraph above).
 #   * `finalize do |p| ... end` (once per contract) — runs after every field
 #     validated cleanly, receives the result hash, and must return the
 #     (possibly restructured) Hash: combine parallel fields, build value
@@ -189,6 +217,7 @@ module Permittable
   JSON_TYPE = :json
   UNKNOWN_MODES = %i[ignore log error].freeze
   MODES = %i[enforce monitor].freeze
+  ERROR_FORMATS = %i[envelope problem].freeze
   # Rails merges routing bookkeeping into params; a top-level (root: false)
   # unknown-keys check must not flag them.
   ROUTING_KEYS = %w[controller action format].freeze
@@ -207,6 +236,10 @@ 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
+  # 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_without_wrapper_copy).
+  WRAPPER_CONTAINER_KINDS = [:nested, JSON_TYPE].freeze
   # A log line and an exception message are PROSE, written for a person. They
   # list at most this many names and count the rest, so one request cannot
   # write a megabyte of them. The machine-readable channels — a violation's
@@ -216,6 +249,49 @@ module Permittable
   # ...and each name it does list is truncated. Capping the COUNT alone still
   # let ONE 1 MB key name write the 1 MB log line the cap exists to prevent.
   PROSE_ITEM_LIMIT = 120
+  # ...and a name that could break the sentence out of its line is escaped.
+  # The names are client-sent, and bounding their length escaped nothing: a
+  # key of "x\nE, [...] ERROR -- : ..." wrote a second, forged log entry.
+  # The set is, by Unicode property:
+  # - every control character (Cc: C0, DEL and C1 — C1 because U+0085 is
+  #   NEL, a line break to many readers, and U+009B is the 8-bit CSI that
+  #   starts a terminal escape);
+  # - U+2028/U+2029 (Zl, Zp), the separators a JSON-lines or JavaScript
+  #   reader splits a line on;
+  # - every format character (Cf): the bidi embeddings, overrides and
+  #   isolates, which can visually reorder a line and so move text across
+  #   the closing quote of an escaped name, and the zero-width and marker
+  #   characters (U+200B, U+200E/U+200F, U+061C, U+FEFF, ...), which make
+  #   two different names print identically;
+  # - every space but U+0020 (Zs), so a no-break or ideographic space
+  #   cannot make "x,<NBSP>y" pass for the ", " between two names.
+  PROSE_UNSAFE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Zs}&&[^ ]]/
+  # A name is also quoted when it merely LOOKS like prose structure. These
+  # characters print as they are — only the quoting marks them:
+  # - Unicode's own Quotation_Mark property, rather than a hand-picked list:
+  #   it already covers the plain and fullwidth `"`, every curly quote and
+  #   guillemet (Pi/Pf), AND the CJK corner brackets U+300C/U+300D, which
+  #   are real quotation marks in Japanese and Chinese text but are punctuation
+  #   category Ps/Pe, not Pi/Pf, so a Pi/Pf-only check missed them;
+  # - the list separator, or a fullwidth, small, ideographic or small-form-
+  #   ideographic comma (the last, U+FE51, is U+3001's small-form sibling,
+  #   the way U+FE50 is the plain comma's), could pass for the ", " between
+  #   two names;
+  # - a name that begins "and N more" (matched case-insensitively — "And"/
+  #   "AND" reads identically once rendered) could pass for the overflow
+  #   count. This still only catches the literal word: a homoglyph
+  #   substitution such as Cyrillic "а" for Latin "a" is not detected, and
+  #   no Unicode confusable-detection is attempted here — see CHANGELOG.
+  PROSE_AMBIGUOUS = /\p{Quotation_Mark}|[\u{FF0C}\u{FE50}\u{3001}\u{FE51}]|, |\A(?i:and \p{Nd}+ more)/
+  # \n, \r and \t, which a person recognises, get their short escape; any
+  # other unsafe character is \uXXXX, which JSON, JavaScript and Ruby all
+  # read the same way. The quote and backslash are escaped too, but only
+  # inside an escaped (quoted) name, where they would otherwise be ambiguous.
+  PROSE_ESCAPES = { "\n" => '\n', "\r" => '\r', "\t" => '\t', '"' => '\"', "\\" => '\\\\' }.freeze
+  # How much of a name the prose ever reads. Every character the rendering
+  # could show lies inside it even when each one is a 4-byte sequence in a
+  # binary key, so a 1 MB name is converted and scanned no further than this.
+  PROSE_SCAN_LIMIT = PROSE_ITEM_LIMIT * 4
 
   # The single proc Permittable::Railtie appends to config.filter_parameters.
   # Declared with an optional third parameter so its own arity is -3 and Rails
@@ -227,6 +303,28 @@ module Permittable
     inner.arity == 2 ? inner.call(key, value) : inner.call(key, value, original)
   end.freeze
 
+  # Named `format:` presets — the regexps every app writes by hand, defined
+  # once. A preset carries something a hand-written Regexp cannot: the JSON
+  # Schema `format` keyword the ecosystem understands, so an exported schema
+  # says `"format": "uuid"` and not only a wall of pattern.
+  #
+  # :email is deliberately URI::MailTo::EMAIL_REGEXP itself, the regexp Rails
+  # apps already paste into their contracts, so adopting the preset cannot
+  # change which addresses an endpoint accepts. The rest avoid flags and
+  # Ruby-only constructs (no \h, no /i) so they translate to ECMA-262 and
+  # export as a real `pattern` rather than an x-permittable-pattern
+  # extension. :url and :hostname are shape checks, not reachability
+  # guarantees.
+  FORMATS = {
+    email: { pattern: URI::MailTo::EMAIL_REGEXP, json: "email" }.freeze,
+    uuid: { pattern: /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/,
+            json: "uuid" }.freeze,
+    url: { pattern: %r{\Ahttps?://[^\s/?\#]+[^\s]*\z}, json: "uri" }.freeze,
+    slug: { pattern: /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/ }.freeze,
+    hostname: { pattern: /\A[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z/,
+                json: "hostname" }.freeze
+  }.freeze
+
   NORMALIZERS = {
     squish: ->(v) { v.squish },
     strip: ->(v) { v.strip },
@@ -326,6 +424,19 @@ module Permittable
       @sensitive_parameter_sinks ||= []
     end
 
+    # A reusable field list, shareable by any number of contracts — see
+    # FieldGroup for the whole story.
+    #
+    #   AddressFields = Permittable.fields do
+    #     required :city, :string
+    #     optional :zip,  :string, format: /\A\d{5}\z/
+    #   end
+    #
+    # Splice it into a contract (or another group) with `use`.
+    def fields(&)
+      FieldGroup.new(&)
+    end
+
     # App-wide default for rules that don't declare their own mode:.
     # :enforce (the default) rejects violating requests; :monitor reports
     # them — same instrumentation event with payload mode: :monitor, plus a
@@ -346,6 +457,54 @@ module Permittable
       @mode = value
     end
 
+    # The shape of a rejection: :envelope (the default — the host's
+    # #render_error, or the gem's inline JSON) or :problem, which renders RFC
+    # 9457 Problem Details as application/problem+json. App-wide, because the
+    # error format of an API is a property of the API rather than of any one
+    # contract, and set from an initializer:
+    #
+    #   Permittable.error_format = :problem
+    #
+    # See ErrorEnvelope, including why :problem opts out of #render_error.
+    def error_format
+      @error_format || :envelope
+    end
+
+    def error_format=(value)
+      value = value.to_sym
+      raise ArgumentError, "#{LABEL}: error_format must be one of #{ERROR_FORMATS.join(', ')}" unless ERROR_FORMATS.include?(value)
+
+      @error_format = value
+    end
+
+    # Base URI for problem `type` members. Unset (the default) leaves the type
+    # as RFC 9457's "about:blank"; set it to where the app documents its
+    # problem types and each type gets its own URI under it.
+    attr_accessor :problem_base_uri
+
+    # Whether the schema-drift guard also checks that a field's declared type
+    # matches its column's, on top of checking the column exists.
+    #
+    # OFF by default, deliberately. Every cross-type declaration has some
+    # legitimate use — a :string contract on a date column that lets
+    # ActiveRecord do the casting, a :boolean contract on a legacy integer
+    # column — and breaking those apps on an upgrade would cost more than the
+    # drift it catches. Turn it on and fix what it finds:
+    #
+    #   Permittable.check_column_types = true
+    #
+    # It compares type GROUPS rather than exact types, and never fires on a
+    # column it has no faithful contract type for. See ColumnGuard.
+    def check_column_types
+      @check_column_types || false
+    end
+
+    def check_column_types=(value)
+      raise ArgumentError, "#{LABEL}: check_column_types must be true or false" unless [true, false].include?(value)
+
+      @check_column_types = value
+    end
+
     # App-wide fallback copy for a violation code, looked up through I18n
     # under permittable.errors.<code> ("missing", "inclusion", or any Symbol
     # a validate: returned). Consulted only when the field declares no
@@ -418,22 +577,44 @@ module Permittable
     def check_scalar_rules(field, value)
       return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
       return [:error, "inclusion"] if field[:in] && !included_in?(field[:in], value)
-      return [:error, "format"] if field[:format] && !field[:format].match?(value)
+      return [:error, "format"] if field[:format] && !format_match?(field[:format], value)
 
       check_custom(field[:validate], value)
     end
 
+    # A Regexp RAISES rather than answers when a String's encoding cannot meet
+    # it — a UTF-8 pattern with non-ASCII characters against UTF-16,
+    # Shift_JIS or binary bytes (Encoding::CompatibilityError). A value the
+    # pattern cannot even be applied to has not been shown to match, so it is
+    # a `format` violation, the answer the client can act on. An app that
+    # takes other encodings on purpose (`skip_parameter_encoding`) sees what
+    # it saw before this rule, except that the crash is now a 422.
+    def format_match?(pattern, value)
+      pattern.match?(value)
+    rescue EncodingError, ArgumentError
+      false
+    end
+
     # 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.
+    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)
       return [:error, "depth"] if field[:max_depth] && depth_exceeds?(value, field[:max_depth])
 
-      check_custom(field[:validate], value)
+      [:ok, value]
     end
 
     # Container nesting, with the field's own hash as level 1. An Array counts
@@ -463,8 +644,76 @@ module Permittable
 
     def cast(type, value)
       return [:error, "invalid_type"] unless scalar_shaped?(value)
+      return public_send("cast_#{type}", value) unless value.is_a?(String)
+      # Bytes that are not valid in the String's OWN encoding are not text in
+      # any encoding: every String operation after the cast raises on them
+      # (`format:`, the normalize presets, an app's `validate:`). Rails'
+      # params builder guards a controller; a standalone Contract#call on a
+      # webhook payload has nothing in front of it, so `"caf\xC3"` was a 500.
+      return [:error, "invalid_type"] unless value.valid_encoding?
+      # A :string is handed back exactly as it arrived, in its own encoding.
+      # `skip_parameter_encoding` / `param_encoding` send a controller binary
+      # or Shift_JIS text ON PURPOSE, and converting it would hand the app
+      # something other than what it asked Rails for.
+      return cast_string(value) if type == :string
+
+      # A UTF-8 String IS already its own inspection copy — the check just
+      # above already scanned it — so utf8_text would only scan the same
+      # object a second time for no new answer. Every other encoding still
+      # goes through it: a US-ASCII or binary String is a NEW object once
+      # force_encoding'd, and one only `encode` could produce is not yet
+      # known to be valid UTF-8 at all.
+      text = value.encoding == Encoding::UTF_8 ? value : utf8_text(value)
+      text ? public_send("cast_#{type}", text) : [:error, "invalid_type"]
+    end
+
+    # Encodings whose bytes are READ as UTF-8 rather than converted: UTF-8
+    # itself, US-ASCII (a subset of it), and binary — which names no
+    # encoding at all, and is how a raw socket read or an unlabelled file
+    # hands a payload over.
+    UTF8_READABLE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::BINARY].freeze
+
+    # A UTF-8 copy of a String, for INSPECTION only — the text a number, a
+    # boolean or a date is parsed from — or nil when there is no UTF-8
+    # reading of it. The value handed back to the app is never this copy.
+    #
+    # Parsing the String itself went wrong for any encoding but UTF-8:
+    # `Integer()` on UTF-16 "12" raised Encoding::CompatibilityError, and
+    # `BigDecimal` read the same String byte by byte and returned 1 — a wrong
+    # answer where the other at least crashed.
+    #
+    # Binary and US-ASCII are read as UTF-8 (on a copy — the caller's String
+    # keeps its encoding), anything else is converted with `encode`, and a
+    # result that is not valid UTF-8, or a conversion that raises, is nil.
+    def utf8_text(value)
+      text = if value.encoding == Encoding::UTF_8 then value
+             elsif UTF8_READABLE.include?(value.encoding) then value.dup.force_encoding(Encoding::UTF_8)
+             else value.encode(Encoding::UTF_8)
+             end
+      text.valid_encoding? ? text : nil
+    rescue EncodingError
+      nil
+    end
 
-      public_send("cast_#{type}", value)
+    # utf8_text for text the gem must REPORT rather than judge — a client's
+    # undeclared key, written into a violation's `param`, the exception
+    # message and the log line. Refusing is not an option there, so what
+    # cannot be read is replaced with U+FFFD. Otherwise the undeclared key
+    # "caf\xC3" was copied raw into the 422 and rendering it raised
+    # JSON::GeneratorError, and a UTF-16 key raised
+    # Encoding::CompatibilityError while its path was being interpolated.
+    # Only undeclared keys come here (see permittable_unknown_key_violation):
+    # a declared key is the contract's own UTF-8 name.
+    def reportable_text(value)
+      utf8_text(value) || scrubbed_text(value)
+    end
+
+    def scrubbed_text(value)
+      return value.dup.force_encoding(Encoding::UTF_8).scrub if UTF8_READABLE.include?(value.encoding)
+
+      value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    rescue EncodingError
+      value.dup.force_encoding(Encoding::UTF_8).scrub
     end
 
     # Arrays, hashes, and nested ActionController::Parameters
@@ -476,9 +725,20 @@ module Permittable
       true
     end
 
+    # A String is returned as given. The request walker has already copied
+    # it on the way in (Permittable#permittable_normalized), before
+    # `normalize:` could see it — copying here as well would allocate twice
+    # per value and still come too late for a mutating `normalize:` proc.
     def cast_string(value)
       case value
       when String then [:ok, value]
+      # BigDecimal#to_s defaults to engineering notation ("0.15e1" for 1.5) —
+      # stdlib's own rendering, only ever masked in a host that has loaded
+      # Rails' active_support/core_ext/big_decimal/conversions, which patches
+      # the default format to "F". A :decimal default:/example: cast through
+      # 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]
       else [:error, "invalid_type"]
       end
@@ -487,7 +747,10 @@ module Permittable
     def cast_integer(value)
       case value
       when Integer then [:ok, value]
-      when Float then value == value.truncate ? [:ok, value.to_i] : [:error, "invalid_type"]
+      # NaN and Infinity first: `truncate` raises FloatDomainError on them (a
+      # RangeError, which the ArgumentError rescue below does not catch), and
+      # no integer is what either one sent. Same rule as finite_float.
+      when Float then value.finite? && value == value.truncate ? [:ok, value.to_i] : [:error, "invalid_type"]
       when String then [:ok, Integer(value, 10)]
       else [:error, "invalid_type"]
       end
@@ -614,10 +877,37 @@ module Permittable
 
     # Presets only make sense on String input; a non-String value (JSON
     # numbers, booleans) skips normalization and goes straight to the cast.
+    #
+    # A String that is not valid in its own encoding is left as it came, for
+    # the cast to refuse: every preset raises on invalid bytes, and an app's
+    # own proc would be handed input it never agreed to see. It is not empty,
+    # so the absence rule in between cannot mistake it for a missing value.
+    #
+    # A VALID String in another encoding is normalized in that encoding —
+    # `:strip` works on binary and Shift_JIS alike — and when a BUILT-IN
+    # PRESET cannot handle the encoding (`:squish` on UTF-16 raises
+    # Encoding::CompatibilityError) the value is left as it is rather than
+    # raising.
+    #
+    # That leniency is only for the gem's own presets, identified by object
+    # identity against NORMALIZERS' values (resolve_normalizer! replaces
+    # field[:normalize] with the exact Proc from that Hash, so a preset and
+    # an app-supplied Proc are never the same object). An app's own Proc
+    # raising is never swallowed, on ANY encoding: `normalize: ->(v) { raise
+    # ArgumentError, "..." if ... }` is a business rule, not an encoding
+    # failure, and treating its raise as "this encoding defeated the
+    # normalizer" would have let exactly the input a UTF-8 request could not
+    # bypass the very check it names.
     def apply_normalize(normalizer, value)
       return value unless normalizer && value.is_a?(String)
+      return value unless value.valid_encoding?
+      return normalizer.call(value) unless NORMALIZERS.value?(normalizer)
 
-      normalizer.call(value)
+      begin
+        normalizer.call(value)
+      rescue EncodingError, ArgumentError
+        value
+      end
     end
 
     # nil and "" are both ABSENT — see the module comment. The VALUE half of
@@ -628,6 +918,109 @@ module Permittable
       value.nil? || (value.is_a?(String) && value.empty?)
     end
 
+    # An `in:` list as the runtime holds it: every member cast by the field's
+    # own type, because included_in? compares the CAST request value against
+    # it. Comparing against the members as authored meant `in: %i[draft
+    # published]` on a :string field (and `in: %w[1 2 3]` on an :integer one)
+    # held values no cast could ever produce, and rejected every request.
+    #
+    # `normalize:` is deliberately not applied — it rewrites what a client
+    # sent, not what the contract author wrote. Duplicates the cast collapses
+    # ("1" and 1 on an :integer) are dropped, and a Set stays a Set, so an
+    # author who chose one for its O(1) include? keeps it. A nil member is
+    # dropped on a nullable field, where an explicit null is accepted before
+    # in: is ever consulted; anywhere else it is a member no value can equal,
+    # and is an error like any other.
+    #
+    # `members` is what in_list returned. Returns [:ok, cast, published] —
+    # `published` being what an exported enum lists, see published_in_member
+    # — or [:error, offending_member, code]. Shared by ContractBuilder and the
+    # RSpec matcher's `within` chain so the two cannot read a list differently.
+    def cast_in_members(type, members, nullable: false)
+      pairs = []
+      members.each do |member|
+        next if member.nil? && nullable
+
+        status, value = cast_in_member(type, member)
+        return [:error, member, value] unless status == :ok
+
+        pairs << [value, published_in_member(type, member, value)]
+      end
+      pairs = pairs.uniq(&:first)
+      cast_members = pairs.map(&:first)
+      [:ok, members.is_a?(Set) ? cast_members.to_set : cast_members, pairs.map(&:last)]
+    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
+    # registry).
+    #
+    # 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.
+    # 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
+      end
+    end
+
+    def plain_hash?(allowed)
+      allowed.instance_of?(Hash) || allowed.instance_of?(ActiveSupport::HashWithIndifferentAccess)
+    end
+
+    # A Symbol is read as its String: it is how Ruby spells a constant
+    # string, and a request never carries one, so no cast accepts it as is.
+    def cast_in_member(type, member)
+      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)
+    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.)
+    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]
+    end
+
+    # What an exported enum lists for one member: the cast value, re-encoded
+    # as JSON — except a :date/:datetime member authored as a String, which
+    # is published AS WRITTEN. Re-encoding a cast Time prints whole seconds,
+    # so "2026-09-05T10:00:00.25Z" was published as "…10:00:00Z", a value
+    # the server refuses. The authored String went through the very cast a
+    # request does, so the server accepts it by construction.
+    def published_in_member(type, member, value)
+      member.is_a?(String) && %i[date datetime].include?(type) ? member : value
+    end
+
     # Range#include? walks discrete ranges; cover? is the O(1) bounds check
     # and the right semantics for validation.
     def included_in?(allowed, value)
@@ -651,6 +1044,13 @@ module Permittable
     ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message desc example
                      nullable].freeze
 
+    # One value of each scalar type as a cast produces it, for asking whether
+    # an `in:` Range's endpoints can be compared with that type at all.
+    RANGE_PROBES = {
+      string: "", integer: 0, float: 0.0, decimal: BigDecimal("0"), boolean: true,
+      date: Date.new(2000, 1, 1), datetime: Time.utc(2000)
+    }.freeze
+
     attr_reader :finalizer
 
     def initialize
@@ -691,6 +1091,10 @@ module Permittable
       required = opts.delete(:required) ? true : false
 
       field = { name: name, kind: :array, required: required, **opts }
+      if field[:required] && field.key?(:default)
+        raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
+      end
+
       if block
         raise ArgumentError, "#{LABEL}: array :#{name} takes of: OR a block, not both" if opts.key?(:of)
 
@@ -708,8 +1112,69 @@ module Permittable
       @fields << field
     end
 
+    # Splice a reusable field group in at this point — the same fields, in the
+    # same order, as if they had been typed here. Works at the top level of a
+    # contract, inside a nested or array block, and inside another group.
+    #
+    #   permit_params :create, root: :user do
+    #     required :name, :string
+    #     optional :address do
+    #       use AddressFields
+    #     end
+    #   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.
+    #
+    # `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
+    # silently drop a field. A field declared twice still raises, so
+    # overriding one field of a group is deliberate: `use G, except: [:city]`
+    # 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.each do |field|
+        field_name!(field[:name])
+        @fields << field
+      end
+      nil
+    end
+
     private
 
+    def group_fields!(group)
+      return group.fields if group.respond_to?(:fields)
+
+      raise ArgumentError, "#{LABEL}: use expects a field group (Permittable.fields { ... }) or anything " \
+                           "answering #fields, such as a Permittable::Contract — got #{group.class}"
+    end
+
+    def select_group_fields!(fields, only:, except:)
+      raise ArgumentError, "#{LABEL}: use takes only: OR except:, not both" if only && except
+
+      if only || except
+        wanted = assert_group_names!(fields, only || except, only ? "only" : "except")
+        fields = only ? fields.select { |f| wanted.include?(f[:name]) } : fields.reject { |f| wanted.include?(f[:name]) }
+      end
+      return fields unless fields.empty?
+
+      raise ArgumentError, "#{LABEL}: use selects no fields from the group"
+    end
+
+    def assert_group_names!(fields, names, label)
+      wanted = Array(names).map(&:to_sym)
+      declared = fields.map { |f| f[:name] }
+      missing = wanted - declared
+      return wanted if missing.empty?
+
+      raise ArgumentError, "#{LABEL}: use #{label}: names #{missing.map(&:inspect).join(', ')}, which the group " \
+                           "does not declare (it declares: #{declared.map(&:inspect).join(', ')})"
+    end
+
     def add_field(name, type, required:, opts:, &block)
       name = field_name!(name)
       if block
@@ -813,25 +1278,109 @@ module Permittable
         raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
       end
 
-      if field.key?(:in)
-        unless field[:in].respond_to?(:include?)
-          raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
-        end
-
-        assert_satisfiable!(name, :in, field[:in])
-      end
-
+      resolve_in!(field) if field.key?(:in)
       validate_string_only_opts!(field)
       validate_length!(name, field[:length]) if field.key?(:length)
       validate_required_length!(field)
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
+      resolve_format!(field)
       resolve_normalizer!(field)
       validate_authored_value!(field, :default)
       validate_authored_value!(field, :example)
       validate_message!(field)
     end
 
+    # `in:` is a Range (bounds-checked with cover?), a list of values, or an
+    # object of the host's own that answers include? — kept exactly as given,
+    # since nothing here can know what it accepts. It used to be anything
+    # answering include?, which let a String through, and String#include? is
+    # a SUBSTRING test: `in: "free pro"` accepted "e", "fr" and "ee p". A
+    # String is refused here, along with anything answering neither.
+    #
+    # A list (see Coercion.in_list — a Hash lists its keys) is stored cast by
+    # the field's type (see Coercion.cast_in_members), so request-time
+    # matching, the exported enum, the RSpec matcher and the column guard's
+    # 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.
+    def resolve_in!(field)
+      name = field[:name]
+      allowed = field[:in]
+      if allowed.is_a?(Range)
+        assert_comparable_range!(field, allowed)
+      elsif (members = Coercion.in_list(allowed))
+        cast_in_members!(field, members)
+      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
+
+    def string_in_hint(allowed)
+      return "" unless allowed.is_a?(String)
+
+      " — String#include? would accept any substring; list the values instead, e.g. in: %w[#{allowed}]"
+    end
+
+    # `published` is stored only where it differs from the cast members (a
+    # String-authored :date/:datetime member), so it is read as an override.
+    def cast_in_members!(field, members)
+      status, cast, published = Coercion.cast_in_members(field[:type], members, nullable: field[:nullable])
+      unless status == :ok
+        # cast is the offending member here, and published its error code.
+        # nil is the one member written on purpose, meaning "null is allowed"
+        # — but an absent value never reaches in:, so the fix is worth naming.
+        hint = cast.nil? ? " — an absent value never reaches in:; declare nullable: true to accept an explicit null" : ""
+        raise ArgumentError, "#{LABEL}: :in for field :#{field[:name]} contains #{cast.inspect}, " \
+                             "which is not a valid :#{field[:type]} (#{published})#{hint}"
+      end
+
+      field[:in] = freeze_in_members(cast)
+      field[:in_published] = freeze_authored(published) unless published == cast.to_a
+    end
+
+    def freeze_in_members(members)
+      members.is_a?(Set) ? members.to_set { |member| freeze_authored(member) }.freeze : freeze_authored(members)
+    end
+
+    # A Range is kept exactly as written, unlike a list: casting its
+    # endpoints would change what it means. `0..Float::INFINITY` on a :float
+    # and `1.5..3` on an :integer are real bounds whose endpoints no cast
+    # accepts, and a :decimal's `0..100` would become BigDecimal endpoints
+    # that export as the STRING "0.0" where `minimum` needs a number.
+    #
+    # What does fail every request is an endpoint the cast value cannot be
+    # compared with — `"1".."5"` on an :integer, `1..5` on a :string,
+    # `.."9.99"` on a :decimal. cover? then answers false for every value, so
+    # that is caught here. The probe asks exactly what cover? will — begin
+    # <=> value, then value <=> end — so whatever the host's own <=> allows
+    # (ActiveSupport lets a Date range bound a :datetime) is allowed here too.
+    def assert_comparable_range!(field, range)
+      probe = RANGE_PROBES.fetch(field[:type])
+      # A NaN endpoint compares to nothing, by design, whatever it stands
+      # beside — not evidence of a wrong-TYPED bound (a String range on an
+      # :integer), which is what this check exists to catch. It is left
+      # alone here exactly as an infinite endpoint already is (INFINITY
+      # compares fine); the exporter separately omits it, since it is
+      # never `finite?`.
+      # Wrapped in an Array so a `false` endpoint still reads as found.
+      stray = if !range.begin.nil? && !nan?(range.begin) && (range.begin <=> probe).nil? then [range.begin]
+              elsif !range.end.nil? && !nan?(range.end) && (probe <=> range.end).nil? then [range.end]
+              end
+      return unless stray
+
+      raise ArgumentError, "#{LABEL}: :in for field :#{field[:name]} is a Range of #{stray.first.class} " \
+                           "(#{range.inspect}), which a :#{field[:type]} value cannot be compared with — " \
+                           "no value could satisfy it; write the bounds as :#{field[:type]} values"
+    end
+
+    def nan?(value)
+      value.respond_to?(:nan?) && value.nan?
+    end
+
     def validate_json_opts!(field)
       name = field[:name]
       if field[:required] && field.key?(:default)
@@ -930,6 +1479,28 @@ module Permittable
       raise ArgumentError, "#{LABEL}: :#{opt} for field :#{name} must be callable"
     end
 
+    # A Symbol (or String) `format:` names a preset; a Regexp is used as
+    # given. Resolving here means request-time matching stays a plain
+    # Regexp#match?, and an authored `default:`/`example:` is checked against
+    # the resolved pattern like any other. The preset NAME is kept on the
+    # field so exporters and the RSpec matcher can speak in presets.
+    def resolve_format!(field)
+      preset = field[:format]
+      return if preset.nil? || preset.is_a?(Regexp)
+
+      unless preset.is_a?(Symbol) || preset.is_a?(String)
+        raise ArgumentError, "#{LABEL}: :format for field :#{field[:name]} must be a Regexp or a preset name " \
+                             "(presets: #{FORMATS.keys.join(', ')})"
+      end
+
+      spec = FORMATS.fetch(preset.to_sym) do
+        raise ArgumentError, "#{LABEL}: unknown :format preset :#{preset} for field :#{field[:name]} " \
+                             "(presets: #{FORMATS.keys.join(', ')}, or pass a Regexp)"
+      end
+      field[:format_name] = preset.to_sym
+      field[:format] = spec[:pattern]
+    end
+
     def resolve_normalizer!(field)
       normalizer = field[:normalize]
       return if normalizer.nil?
@@ -943,85 +1514,67 @@ module Permittable
 
     # An authored value (`default:`, or a documentation `example:`) must
     # satisfy the field's own contract — catching a lie at class load beats
-    # shipping it to every request (or publishing it in generated docs).
-    # The authored value is STORED normalized, because that is the form it was
-    # validated in: `default: "  free  "` with `normalize: :squish` was
-    # checked as "free" and used to be handed to requests as "  free  ".
+    # shipping it to every request (or publishing it in generated docs) —
+    # which is checked here by normalizing and casting it, same as a request's
+    # value. `default: "  free  "` with `normalize: :squish` is checked as
+    # "free"; `default: "18"` on an :integer is checked as 18.
+    #
+    # What is STORED from that differs by whether the field has `transform:`.
+    # With none, the cast result is stored — the form a request sending the
+    # 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 —
+    # `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
+    # receive: `default: 25` beside `transform: ->(v) { v.to_i }` on a
+    # :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).
     def validate_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
 
-      value = Coercion.apply_normalize(field[:normalize], field[opt])
-      status, code = Coercion.check_scalar(field, value)
-      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
-
-      field[opt] = freeze_authored(value)
-    end
-
+      # Copied first, like a request's String, so a mutating `normalize:`
+      # 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)
+      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)
+    end
+
+    # An array's authored value is validated by the REQUEST walker itself
+    # (see AuthoredValues) exactly as validate_authored_value! validates a
+    # scalar's: elements cast, nested hashes and arrays read at every depth, a
+    # sub-field's own default: filled in, `""` on a nullable sub-field made
+    # the explicit nil a request would get, keys the block does not declare
+    # dropped (as `unknown: :ignore` drops them), and the array's own
+    # `validate:` run over the result. A hand-rolled one-level check used to
+    # 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. `transform:` itself is deliberately
+    # never run on a default either way — see AuthoredValues.
     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)
-      if field[:length] && !Coercion.length_ok?(field[:length], value.length)
-        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} violates its own contract (length)"
-      end
-
-      validate_array_elements!(field, opt, value) if field[:of]
-      validate_array_element_hashes!(field, opt, value) if field[:fields]
-      field[opt] = freeze_authored(value)
-    end
-
-    # The nested-block counterpart of the of: element check below. Without it
-    # `field[:of]` was nil for a block array, so its `default:` skipped
-    # validation entirely and whatever was authored went straight to every
-    # request that omitted the key. Shallow in the same way the of: check is:
-    # required sub-fields must be present and scalar ones must satisfy their
-    # own contract, which is what an authored value gets wrong.
-    def validate_array_element_hashes!(field, opt, value)
-      value.each do |element|
-        unless element.is_a?(Hash)
-          raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains #{element.class} " \
-                               "where the block declares a hash"
-        end
-
-        # Wrapped the way permittable_check_element wraps an element at
-        # request time, so class load reads keys exactly as a request does.
-        indifferent = ActiveSupport::HashWithIndifferentAccess.new(element)
-        field[:fields].each { |sub| validate_array_element_field!(field, opt, indifferent, sub) }
-      end
-    end
 
-    def validate_array_element_field!(field, opt, element, sub)
-      # Normalized before absence is read, and absence read with the runtime's
-      # own rule: a default: is applied WITHOUT revalidation, so anything this
-      # check waves through is handed to the app unexamined — and "" here used
-      # to mean a default could carry the very value a client is refused.
-      value = Coercion.apply_normalize(sub[:normalize], element[sub[:name]])
-      if Coercion.absent_value?(value)
-        # nullable: splits that rule exactly as permittable_explicit_null?
-        # does — a key present but empty is an explicit null, not an absence.
-        return if sub[:nullable] && element.key?(sub[:name])
-        return unless sub[:required]
-
-        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} is missing :#{sub[:name]}, " \
-                             "which the block declares as required"
+      read, violations = AuthoredValues.read_array(field, value)
+      unless violations.empty?
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} violates its own contract: " \
+                             "#{AuthoredValues.summary(violations)}"
       end
-      return unless sub[:kind] == :scalar
 
-      status, code = Coercion.check_scalar(sub, value)
-      return if status == :ok
-
-      raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} has :#{sub[:name]} " \
-                           "violating its own contract (#{code})"
-    end
-
-    def validate_array_elements!(field, opt, value)
-      value.each do |element|
-        status, code = Coercion.cast(field[:of], element)
-        next if status == :ok
-
-        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains an element violating of: :#{field[:of]} (#{code})"
-      end
+      field[opt] = freeze_authored(field[:transform] ? value : read)
     end
 
     # A contract is frozen data, but `@fields.map(&:freeze)` freezes only the
@@ -1201,9 +1754,16 @@ module Permittable
       return if checked.empty?
 
       types = checked.to_h { |f| [f[:name], f[:type]] }
+      allowed = checked.select { |f| f.key?(:in) }.to_h { |f| [f[:name], f[:in]] }
       begin
-        ColumnGuard.ensure_columns_on!(LABEL, model_class, *checked.map { |f| f[:name] }, types: types)
+        ColumnGuard.ensure_columns_on!(LABEL, model_class, *checked.map { |f| f[:name] },
+                                       types: types, check_types: Permittable.check_column_types,
+                                       allowed: allowed)
       rescue ArgumentError => e
+        # The type error carries its own guidance; only the missing-column one
+        # needs the virtual: hint appended.
+        raise e unless e.message.include?("does not exist in the database")
+
         raise ArgumentError, "#{e.message} If this parameter is not backed by a column, declare it with virtual: true."
       end
     end
@@ -1308,6 +1868,39 @@ module Permittable
 
   private
 
+  # ParamsWrapper copies a JSON body under the controller's wrapper key
+  # (`user` for UsersController) — on by default in a Rails app — and a
+  # rootless contract then saw that copy as an unknown top-level key on every
+  # well-formed request. Whether the copy is Rails' own has to be read HERE,
+  # before ParamsWrapper#process_action (next in the chain) runs: once it has
+  # wrapped, `_wrapper_enabled?` answers false, because params now carry the
+  # key. Asking afterwards could not tell Rails' copy from a client that sent
+  # `user` itself, which is exactly the key the check must still flag.
+  # Private, like the method it wraps — a public one would become an action.
+  # A plain duck has no process_action and no ParamsWrapper, so this never
+  # runs there, and the guards keep an actionpack-free host inert.
+  # Assigned on every request, never only when true: a controller instance
+  # dispatched twice would otherwise carry one request's exemption into the
+  # next, where a `user` the client did send would pass as Rails' copy.
+  def process_action(*)
+    @permittable_wrapper_key = permittable_wrapper_copy_key
+    super
+  end
+
+  # The wrapper key, if ParamsWrapper is about to copy the body under it;
+  # nil otherwise. `_wrapper_enabled?` alone is not enough: it asks the
+  # string-keyed params for the key AS CONFIGURED, so `wrap_parameters :user`
+  # — the form the Rails docs use — answers "not sent" even when the client
+  # sent `user` itself, and Rails wraps anyway. Asking the same params for
+  # the String keeps that client's key the client's, whichever spelling the
+  # host chose.
+  def permittable_wrapper_copy_key
+    return unless respond_to?(:_wrapper_enabled?, true) && respond_to?(:_wrapper_key, true) && _wrapper_enabled?
+
+    key = _wrapper_key.to_s
+    key unless request.parameters.key?(key)
+  end
+
   # The value permitted_params memoizes: the validated params, or the
   # InvalidParameters that rejected them. ArgumentError is deliberately NOT
   # memoized — a contract that does not cover the action is a bug to fix, not
@@ -1326,8 +1919,9 @@ module Permittable
     source = permittable_root_hash(rule, violations)
     result = ActiveSupport::HashWithIndifferentAccess.new
     if source
-      result = permittable_check_hash(rule[:fields], source, path: rule[:root] ? rule[:root].to_s : nil,
-                                                             unknown: rule[:unknown], top_level: !rule[:root], violations: violations)
+      checked = rule[:root] ? source : permittable_without_wrapper_copy(rule[:fields], source)
+      result = permittable_check_hash(rule[:fields], checked, path: rule[:root] ? rule[:root].to_s : nil,
+                                                              unknown: rule[:unknown], top_level: !rule[:root], violations: violations)
     end
     # finalize only sees a hash every field vouched for — never garbage.
     result = permittable_run_finalize(rule[:finalize], result, violations) if violations.empty? && rule[:finalize]
@@ -1359,6 +1953,10 @@ module Permittable
     end
     return ActiveSupport::HashWithIndifferentAccess.new unless source
 
+    # Deliberately NOT deep-copied, unlike the enforce path's result: this is
+    # the pre-contract app's own params, and `params.permit` hands its Strings
+    # back by reference too — copying here would change behaviour in the one
+    # mode whose promise is that nothing changes.
     passed = ActiveSupport::HashWithIndifferentAccess.new(source)
     rule[:root] ? passed : passed.except(*MONITOR_DROPPED_KEYS)
   end
@@ -1377,25 +1975,121 @@ module Permittable
   end
 
   def permittable_violation_summary(violations)
+    # The param is the client-controlled part; the message (or code) is the
+    # developer's, so it is handed over separately and never escaped — a
+    # YAML `|` message ending in "\n" must not quote every name it follows.
+    #
+    # An unknown-key violation's `param:` is already reportable_text — valid
+    # UTF-8, but scrubbed to U+FFFD wherever the key wasn't. That is right
+    # for `details`/instrumentation (a machine reads it and only needs it not
+    # to crash `to_json`), but prose can do better: permittable_prose_utf8
+    # keeps a legacy byte transcodable and an invalid one visible as \xNN
+    # rather than replacing it, so prose reads the RAW key when one was
+    # saved (see permittable_unknown_key_violation), and falls back to the
+    # param for any other violation.
     permittable_prose_list(violations) do |v|
-      v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})"
+      name = @permittable_unknown_key_raw&.[](v) || v[:param].to_s
+      [name, v[:message] ? " #{v[:message]}" : " (#{v[:code]})"]
     end
   end
 
   # See PROSE_LIST_LIMIT. `unknown: :error` on a request carrying 50,000
   # undeclared keys used to produce a 50,000-item sentence — a megabyte of
   # log line, or of exception message handed to every error tracker.
-  # The block formats one item, and is called only for the items actually
-  # shown — the rest are counted, never rendered.
+  # The block returns one item's name, or [name, suffix], and is called
+  # only for the items actually shown — the rest are counted, never rendered.
   def permittable_prose_list(items)
-    shown = items.first(PROSE_LIST_LIMIT).map { |item| permittable_prose_item(yield(item)) }.join(", ")
+    shown = items.first(PROSE_LIST_LIMIT).map { |item| permittable_prose_item(*yield(item)) }.join(", ")
     return shown if items.length <= PROSE_LIST_LIMIT
 
     "#{shown}, and #{items.length - PROSE_LIST_LIMIT} more"
   end
 
-  def permittable_prose_item(item)
-    item.length <= PROSE_ITEM_LIMIT ? item : "#{item[0, PROSE_ITEM_LIMIT - 3]}..."
+  # See PROSE_ITEM_LIMIT, PROSE_UNSAFE and PROSE_AMBIGUOUS. The item is the
+  # name plus the suffix, truncated as one. Only a name that needs it is
+  # quoted and escaped, judged by the part of it the truncated item would
+  # SHOW — a control character past the cut is not printed, so it quotes
+  # nothing. Every ordinary name therefore prints exactly as before, just
+  # always as UTF-8: a Windows-1252 or binary key is converted rather than
+  # written raw, and names of mixed encodings can be joined.
+  def permittable_prose_item(name, suffix = "")
+    text = permittable_prose_utf8(name[0, PROSE_SCAN_LIMIT])
+    suffix = permittable_prose_utf8(suffix)
+    more = !name[PROSE_SCAN_LIMIT].nil?
+    fits = !more && text.length + suffix.length <= PROSE_ITEM_LIMIT
+    shown = fits ? text : text[0, PROSE_ITEM_LIMIT - 3]
+    if !shown.valid_encoding? || shown.match?(PROSE_UNSAFE) || shown.match?(PROSE_AMBIGUOUS)
+      return permittable_prose_quoted(text, more, suffix)
+    end
+
+    fits ? "#{text}#{suffix}" : "#{"#{text}#{suffix}"[0, PROSE_ITEM_LIMIT - 3]}..."
+  end
+
+  # The name is truncated by whole escapes, never through one: cutting the
+  # escaped text at a fixed width could print a dangling backslash, or half
+  # of an escape. When the name itself is cut, the "..." goes outside the
+  # closing quote, so the quotes still delimit exactly what is shown. A
+  # quoted name that fits the limit on its own is never cut: the suffix is
+  # cut instead, to whatever room is left — possibly none — and the "..."
+  # that marks it may then run up to three characters past the limit. A
+  # dropped developer suffix is better flagged than hidden, and the name is
+  # the part a reader is there for. Only as many characters are escaped as
+  # can be shown.
+  def permittable_prose_quoted(text, more, suffix)
+    budget = PROSE_ITEM_LIMIT - 2 # the two quotes
+    pieces = []
+    length = 0
+    text.each_char do |char|
+      pieces << permittable_prose_escape(char)
+      length += pieces.last.length
+      break if length > budget
+    end
+    if !more && length <= budget
+      quoted = "\"#{pieces.join}\""
+      return "#{quoted}#{suffix}" if quoted.length + suffix.length <= PROSE_ITEM_LIMIT
+
+      return "#{quoted}#{suffix[0, [PROSE_ITEM_LIMIT - 3 - quoted.length, 0].max]}..."
+    end
+
+    length -= pieces.pop.length while length > budget - 3
+    "\"#{pieces.join}\"..."
+  end
+
+  # A byte that is not valid UTF-8 is shown as \xNN rather than passed
+  # through: it is not a character a person can read, and a lone 0x85 or
+  # 0x9B is NEL or CSI to a Latin-1 terminal. A character beyond the BMP
+  # (the Cf tag characters) is \u{XXXXX}, since \uXXXX holds only four digits.
+  def permittable_prose_escape(char)
+    return char.bytes.map { |byte| format('\x%02X', byte) }.join unless char.valid_encoding?
+
+    PROSE_ESCAPES.fetch(char) do
+      next char unless char.match?(PROSE_UNSAFE)
+
+      char.ord > 0xFFFF ? format('\u{%X}', char.ord) : format('\u%04X', char.ord)
+    end
+  end
+
+  # PROSE_UNSAFE is a UTF-8 pattern, and matching it against a binary key
+  # with high bytes raises Encoding::CompatibilityError — a log line must
+  # never be what fails a request. A binary key has no charset to convert
+  # from, and Rack hands UTF-8 bytes over as binary, so it is read as UTF-8.
+  # A key in a real encoding is transcoded character by character: what
+  # maps is converted, and only a byte that does not (Windows-1252 leaves
+  # 0x81, 0x8D, 0x8F, 0x90 and 0x9D undefined) is kept as an invalid byte,
+  # which the escaper then shows as \xNN — rather than reading the whole
+  # key as UTF-8, which turned a mappable é into \xE9 and mojibake into
+  # characters the client never sent.
+  def permittable_prose_utf8(item)
+    return item if item.encoding == Encoding::UTF_8
+    return item.dup.force_encoding(Encoding::UTF_8) if item.encoding == Encoding::BINARY || item.ascii_only?
+
+    converter = Encoding::Converter.new(item.encoding, Encoding::UTF_8)
+    source = item.dup
+    out = String.new(encoding: Encoding::UTF_8)
+    out << converter.primitive_errinfo[3].force_encoding(Encoding::UTF_8) until converter.primitive_convert(source, out) == :finished
+    out
+  rescue EncodingError # no converter, as for a dummy encoding such as UTF-7
+    item.dup.force_encoding(Encoding::UTF_8)
   end
 
   # One violation detail entry. A field's `message:` (String, or Hash keyed
@@ -1495,7 +2189,7 @@ module Permittable
       # Already normalized by permittable_normalized, before the absence rule.
       permittable_check_whole(field, Coercion.check_scalar(field, value), full, result, violations: violations)
     when :json
-      permittable_check_whole(field, Coercion.check_json(field, value), full, result, violations: violations)
+      permittable_check_whole(field, permittable_check_json(field, value), full, result, violations: violations)
     when :nested
       if value.is_a?(Hash)
         result[key] = permittable_check_hash(field[:fields], ActiveSupport::HashWithIndifferentAccess.new(value),
@@ -1512,14 +2206,27 @@ 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
+  # 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
+  # payload refused on `length:` or `max_depth:` was copied in full just to
+  # be refused, undoing the early exit those bounds exist for.
+  def permittable_check_json(field, value)
+    status, code = Coercion.check_json_bounds(field, value)
+    return [status, code] unless status == :ok
+
+    Coercion.check_custom(field[:validate], value.deep_dup)
+  end
+
   # The shared tail of the two kinds whose entire value is checked in one
   # call — a scalar, or an opaque hash. A clean value is transformed into the
   # result; anything else records its code.
   def permittable_check_whole(field, outcome, full, result, violations:)
     status, out = outcome
     if status == :ok
-      out = field[:transform].call(out) if field[:transform]
-      result[field[:name].to_s] = out
+      result[field[:name].to_s] = permittable_transform(field, out)
     else
       violations << permittable_violation(field, full, out)
     end
@@ -1541,14 +2248,40 @@ module Permittable
     out = value.each_with_index.map do |element, index|
       permittable_check_element(field, element, "#{path}[#{index}]", unknown: unknown, violations: violations)
     end
-    if field[:validate]
+    # validate: and transform: see only a fully-valid array. A partially-nil
+    # one (element violations) would hand user code garbage it never agreed
+    # to see — and for validate: that was a crash, not just garbage:
+    # `validate: ->(a) { a.sum < 100 }` sent `["x", 2]` raised TypeError on
+    # the nil where "x" failed to cast, turning the element's 422 into a 500.
+    #
+    # The cost is real and accepted: the whole-array verdict is no longer
+    # reported ALONGSIDE element violations. `[1, "x", 1]` against a
+    # uniqueness validator reports only `ids[1]`; the client fixes it,
+    # resends, and only then learns of the duplicate. Running app code over
+    # nils it never agreed to handle is the worse failure.
+    #
+    # An undeclared key inside an element (`unknown: :error`) is not such a
+    # violation: it removes nothing from the element validate: sees, so it
+    # does not stop validate: from running.
+    #
+    # transform: is stricter, as on the scalar path: it runs only when
+    # 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)
       violations << permittable_violation(field, path, code) unless status == :ok
     end
     # Transform only a fully-valid array — a partially-nil one (element
     # violations) would hand user code garbage it never agreed to see.
-    out = field[:transform].call(out) if field[:transform] && violations.length == before
-    out
+    violations.length == before ? permittable_transform(field, out) : out
+  end
+
+  # The one place a field's `transform:` is applied — a seam, so that
+  # AuthoredValues can walk an authored default through this same walker
+  # without running app code over it at class load.
+  def permittable_transform(field, value)
+    field[:transform] ? field[:transform].call(value) : value
   end
 
   def permittable_check_element(field, element, path, unknown:, violations:)
@@ -1561,7 +2294,7 @@ module Permittable
                                     path: path, unknown: unknown, top_level: false, violations: violations)
     end
 
-    status, out = Coercion.cast(field[:of], element)
+    status, out = Coercion.cast(field[:of], permittable_own(element))
     return out if status == :ok
 
     violations << permittable_violation(field, path, out)
@@ -1575,18 +2308,34 @@ module Permittable
   # corruption strict coercion exists to refuse, delivered by the gem's own
   # preset. Only scalars take normalize:, and apply_normalize is itself a
   # no-op without one, so it owns that decision for every caller.
+  #
+  # It is also where a request's String stops being the request's. Nothing
+  # the walker hands to app code — `normalize:`, `validate:`, `transform:`,
+  # the result — may alias the caller's params, or `permitted_params[:name]
+  # << "x"` (or `normalize: ->(v) { v.strip! || v }`) rewrites the caller's
+  # Hash or ActionController::Parameters behind the app's back. Copying at
+  # the walker's input, ahead of normalize:, makes it one copy per String;
+  # String#dup shares a long String's buffer copy-on-write, so the copy is
+  # cheap until someone writes to it. `of:` elements get the same treatment
+  # in permittable_check_element, and a :json hash in permittable_check_json.
   def permittable_normalized(field, value)
-    Coercion.apply_normalize(field[:normalize], value)
+    Coercion.apply_normalize(field[:normalize], permittable_own(value))
+  end
+
+  def permittable_own(value)
+    value.is_a?(String) ? value.dup : value
   end
 
   # An authored default belongs to the contract, which is frozen data (see
-  # ContractBuilder#freeze_authored). HashWithIndifferentAccess copies a
-  # frozen Array or Hash as it assigns it, but stores a String as-is — so
-  # that one is copied here, leaving every value in the result the app's own
+  # ContractBuilder#freeze_authored), so every request gets a deep copy of it.
+  # Copying only a top-level String was not enough: HashWithIndifferentAccess
+  # copies a frozen Array or Hash as it assigns it, but not what is INSIDE
+  # one, so `permitted_params[:tags].first << "x"` on an `of: :string`
+  # default — or any edit to a String in a :json default — raised
+  # FrozenError. A deep copy leaves every value in the result the app's own
   # to mutate.
   def permittable_default(field)
-    value = field[:default]
-    value.is_a?(String) ? value.dup : value
+    field[:default].deep_dup
   end
 
   # nil and "" are both ABSENT — see the module comment.
@@ -1608,21 +2357,83 @@ module Permittable
 
     declared = fields.map { |f| f[:name].to_s }
     extra = hash.keys.map(&:to_s) - declared
-    extra -= UNCHECKED_TOP_LEVEL_KEYS if top_level
+    extra -= UNCHECKED_TOP_LEVEL_KEYS + permittable_request_supplied_keys if top_level
     return if extra.empty?
 
     if unknown == :error
-      extra.each { |key| violations << permittable_violation({}, permittable_path(path, key), "unknown") }
+      extra.each { |key| violations << permittable_unknown_key_violation(path, key) }
     elsif respond_to?(:logger) && logger
-      listed = permittable_prose_list(extra) { |key| permittable_path(path, key) }
+      listed = permittable_prose_list(extra) { |key| permittable_path(path, permittable_prose_utf8(key)) }
       logger.warn("#{LABEL}: unknown parameter(s) ignored by the ##{permittable_action_name} contract: #{listed}")
     end
   end
 
+  # The top-level keys THIS request's router put into params, beyond the
+  # fixed UNCHECKED_TOP_LEVEL_KEYS: whatever it matched out of the URL
+  # (`PATCH /users/1` merges `id`, which the exported OpenAPI documents as a
+  # path parameter, not a body field). A controller only — a plain params
+  # duck and a standalone Contract have no request, so they exempt nothing
+  # extra. Subtracted from the undeclared keys, so a contract that DECLARES
+  # `id` still has that field checked like any other: the value is real, the
+  # URL carried it.
+  def permittable_request_supplied_keys
+    return [] unless respond_to?(:request) && request.respond_to?(:path_parameters)
+
+    request.path_parameters.keys.map(&:to_s)
+  end
+
+  # A rootless contract's input without ParamsWrapper's copy of the body,
+  # when Rails made one (see process_action). Removed rather than merely
+  # exempted from the unknown-keys check, because the client never sent that
+  # key: a contract that happens to declare a scalar or array field of the
+  # wrapper's name (`optional :feedback, :string` on FeedbackController)
+  # would otherwise validate Rails' copy of the whole body as that field — a
+  # false 422 invalid_type for a well-formed request.
+  #
+  # Kept, though, when the contract declares that key as a hash container (a
+  # nested block or :json): that rootless contract is reading the copy ON
+  # PURPOSE, a root: spelled as a field, and it worked that way before the
+  # copy was ever dropped — dropping it would turn every such request into
+  # `user missing`. Top level only, where the copy lives; a rooted contract
+  # reads the copy as its root, which is exactly what ParamsWrapper is for.
+  # What is checked changes, not what monitor mode hands back: its raw
+  # pass-through still carries the copy, as the pre-contract app's params did.
+  def permittable_without_wrapper_copy(fields, source)
+    key = @permittable_wrapper_key
+    return source unless key
+    return source if fields.any? { |f| f[:name].to_s == key && WRAPPER_CONTAINER_KINDS.include?(f[:kind]) }
+
+    source.except(key)
+  end
+
   def permittable_path(path, key)
     path ? "#{path}.#{key}" : key
   end
 
+  # The one place a CLIENT's key enters a path, so the only one converted to
+  # reportable UTF-8 (see Coercion.reportable_text) — every declared key a
+  # request walks through is the contract's own name and is left alone.
+  #
+  # The entry is also remembered by identity, which is how
+  # permittable_check_array tells an undeclared key from a sub-field that
+  # failed. The code alone cannot: a sub-field's validate: may itself
+  # return :unknown.
+  def permittable_unknown_key_violation(path, key)
+    entry = permittable_violation({}, permittable_path(path, Coercion.reportable_text(key)), "unknown")
+    (@permittable_unknown_key_violations ||= {}.compare_by_identity)[entry] = true
+    # Prose (the exception message) gets the richer transcoding instead of
+    # `param:`'s scrubbed-to-U+FFFD text — see permittable_violation_summary.
+    # permittable_prose_utf8, not Coercion.reportable_text, is what keeps the
+    # concatenation with `path` (the contract's own UTF-8 field names) from
+    # raising Encoding::CompatibilityError, the same as the :log line below.
+    (@permittable_unknown_key_raw ||= {}.compare_by_identity)[entry] = permittable_path(path, permittable_prose_utf8(key))
+    entry
+  end
+
+  def permittable_unknown_key_violation?(entry)
+    @permittable_unknown_key_violations&.key?(entry) || false
+  end
+
   def permittable_action_name
     respond_to?(:action_name) && action_name ? action_name.to_s : nil
   end
@@ -1634,6 +2445,10 @@ module Permittable
   end
 end
 
+# Class-load reading of an authored array default:/example: — the request
+# walker itself, so it needs the concern's body loaded.
+require "permittable/authored_values"
+
 # Contract exporters — the other readers of the frozen contract registry.
 # Loaded after the module body so OpenAPI can see the concern's own methods.
 require "permittable/json_schema"
@@ -1646,6 +2461,13 @@ require "permittable/generator"
 # Standalone contracts — the same DSL callable on any Hash, no controller.
 require "permittable/contract"
 
+# Contract COVERAGE — the registry crossed with the route set, so a
+# half-covered controller is as visible as an uncovered one.
+require "permittable/audit"
+
+# Reusable field lists — `Permittable.fields` + the builder's `use` verb.
+require "permittable/field_group"
+
 # Boot-time integration (filter_parameters registration, the
 # permittable:openapi rake task), Rails apps only
 require "permittable/railtie" if defined?(Rails::Railtie)