permittable 0.8.0 → 0.10.0

data/lib/permittable/json_schema/ecma_pattern.rb

@@ -0,0 +1,248 @@
+require "strscan"
+
+module Permittable
+  module JsonSchema
+    # Ruby Regexp source → an ECMA-262 `pattern` that compiles under the `u`
+    # flag, which is how Ajv — the validator most clients reach for — builds
+    # every pattern (`new RegExp(pattern, "u")`). Unicode mode is strict where
+    # Ruby is forgiving: `\#`, `\-` and `\ ` are identity escapes Ruby
+    # accepts and Unicode mode rejects, as are a bare `{`, a quantified
+    # lookahead, and `\x7`. Other constructs compile but MEAN something else
+    # there — `{,3}` is a literal without the flag, `&&` two ampersands — so
+    # a source that merely compiles is not yet a translation.
+    #
+    # Hence one tokenizer pass rather than a scan and a few gsubs: it reads
+    # escape pairs and character classes as units (so `\\A` stays a literal
+    # backslash and A, and `*+` inside a class is two literals rather than a
+    # possessive quantifier), and it is a whitelist — every token is either
+    # rewritten into something both engines read identically or the whole
+    # source is refused, and a refusal exports the regexp as
+    # x-permittable-pattern. A construct nobody anticipated is therefore
+    # refused rather than published, because a wrong pattern in published
+    # docs is worse than a missing one.
+    #
+    # Refused on purpose, each for a reason ECMA-262 cannot carry:
+    #   * Ruby's ^ and $, which anchor a LINE where ECMA-262 without the m
+    #     flag anchors the whole string: /^\d{5}$/ accepts "evil\n12345" at
+    #     runtime. \A and \z translate exactly.
+    #   * \Z \h \K \R \G \e \g and the other Ruby-only escapes, and octal
+    #     escapes, which Unicode mode rejects.
+    #   * \b and \B outside a class. Ruby's word boundary counts a non-ASCII
+    #     letter as a word character (its \w does not) and Unicode mode's is
+    #     ASCII-only, so /\Aa\b/ rejects "a\u00e9" at runtime while ^a\b
+    #     accepts it, and \B diverges the other way.
+    #   * Backreferences. One to a group that took no part FAILS in Ruby and
+    #     matches "" in ECMA-262 — /(a)?\1b/ rejects "b" at runtime and its
+    #     translation would accept it — and \12 is a backreference or an
+    #     octal escape depending on how many groups precede it.
+    #   * Atomic, comment, quoted-name, flag, absence and conditional groups.
+    #   * Possessive and stacked quantifiers, `{,n}`, and `{n}?`, which is
+    #     "{n}, optionally" in Ruby and a lazy — so still exact — {n} in
+    #     ECMA-262.
+    #   * `\p{...}`, whose property names differ between the two.
+    #   * Nested classes, POSIX brackets and `&&`; \S in a class beside
+    #     anything but \s.
+    #   * A repeated group name, a SyntaxError in Unicode mode before ES2025.
+    module EcmaPattern
+      module_function
+
+      # Ruby's \s, as ECMA-262 escapes. Ruby's \s is ASCII-only; ECMA-262's
+      # also matches NBSP, U+2028, U+FEFF and every other Unicode space, so
+      # publishing \s verbatim would document a field accepting what the
+      # server rejects. Spelled as escapes so a class can splice it in.
+      SPACE = ' \t\n\v\f\r'.freeze
+
+      # Escapes that name the same single character in both dialects, inside
+      # a class or out. `\0` only on its own: followed by a digit it is octal
+      # in Ruby and a SyntaxError in Unicode mode. `\x` only with two digits,
+      # where Ruby also accepts one.
+      CHARACTER_ESCAPE = /[tnrfv]|0(?!\d)|x\h{2}|u\h{4}|u\{\h{1,6}\}/
+
+      # ECMA-262's syntax characters (and `/`): the only identity escapes
+      # Unicode mode allows, and the way a literal one has to be spelled.
+      SYNTAX_ESCAPE = %r{[\^$\\.*+?()\[\]{}|/]}
+
+      # A group name both dialects accept. ASCII only; a non-ASCII name makes
+      # the regexp encoding-fixed, which ecma_pattern refuses before this.
+      GROUP_NAME = /[A-Za-z_]\w*/
+
+      # nil when the source uses anything that cannot be carried faithfully.
+      def translate(source)
+        scanner = StringScanner.new(source)
+        out = +""
+        quantifiable = false # can the token just emitted take a quantifier?
+        lookaround = [] # per open group: is it a lookaround?
+        names = []
+        until scanner.eos?
+          if scanner.skip(/\\/)
+            text, quantifiable = escape(scanner)
+          elsif scanner.skip(/\[/)
+            text = char_class(scanner)
+            quantifiable = true
+          elsif scanner.scan(/\(\?<(#{GROUP_NAME})>/o)
+            # Unicode mode (before ES2025) rejects a repeated name; Ruby allows it.
+            return nil if names.include?(scanner[1])
+
+            names << scanner[1]
+            lookaround << false
+            text = scanner.matched
+            quantifiable = false
+          elsif scanner.scan(/\((?!\?)|\(\?(?:[:=!]|<[=!])/)
+            lookaround << scanner.matched.end_with?("=", "!")
+            text = scanner.matched
+            quantifiable = false
+          elsif scanner.skip(/\)/)
+            return nil if lookaround.empty?
+
+            text = ")"
+            # A quantified lookaround is a SyntaxError in Unicode mode.
+            quantifiable = !lookaround.pop
+          elsif scanner.scan(/[*+?]|\{\d+(?:,\d*)?\}/)
+            # A quantifier on a quantifier is possessive (`*+`) or nested
+            # (`a{2}{3}`) in Ruby and a SyntaxError in ECMA-262; one on an
+            # assertion or a group opening is a SyntaxError there too.
+            return nil unless quantifiable
+
+            text = scanner.matched
+            if scanner.skip(/\?/)
+              return nil if text.start_with?("{") && !text.include?(",")
+
+              text += "?"
+            end
+            quantifiable = false
+          elsif scanner.check(/\(\?|\{,\d+\}|[\^$]/)
+            return nil
+          elsif scanner.skip(/\./)
+            # Ruby's dot stops only at \n; ECMA-262's (without the s flag)
+            # also at \r, U+2028 and U+2029.
+            text = '[^\n]'
+            quantifiable = true
+          elsif scanner.skip(/\|/)
+            text = "|"
+            quantifiable = false
+          elsif scanner.scan(/[{}\]]/)
+            # Literal in Ruby when they form no quantifier or class; bare,
+            # each is a SyntaxError in Unicode mode.
+            text = "\\#{scanner.matched}"
+            quantifiable = true
+          else
+            text = scanner.getch
+            quantifiable = true
+          end
+          return nil unless text
+
+          out << text
+        end
+        out
+      end
+
+      # An escape outside a class, the backslash already consumed: the
+      # translated text and whether a quantifier may follow it.
+      def escape(scanner)
+        if scanner.skip(/A/) then ["^", false]
+        elsif scanner.skip(/z/) then ["$", false]
+        elsif scanner.skip(/s/) then ["[#{SPACE}]", true]
+        elsif scanner.skip(/S/) then ["[^#{SPACE}]", true]
+        elsif scanner.scan(/[dDwW]/) then ["\\#{scanner.matched}", true]
+        else [literal_escape(scanner), true]
+        end
+      end
+
+      # The rest of a class, `[` already consumed. Ranges are only carried
+      # between two single characters: `[\w-z]` is a RegexpError in Ruby on
+      # either side of the hyphen (a class escape cannot end or start a
+      # range), so that source can never reach this method as a real Regexp;
+      # the refusal for it below is a defensive backstop, not something a
+      # live disagreement between the two engines depends on. A hyphen right
+      # after a just-closed range, `[a-c-e]`, is NOT a different range in
+      # Unicode mode — both engines read it as the set {a, b, c, -, e},
+      # rejecting "d" — so it is carried as a literal member, which may
+      # itself reopen a range (`[a-z--x]`, Ruby's own reading of a second
+      # hyphen after the first).
+      def char_class(scanner)
+        negated = scanner.skip(/\^/)
+        # A leading ] is a literal in Ruby and ends an empty class in ECMA-262.
+        return nil if scanner.check(/\]/)
+
+        members = +""
+        count = 0
+        space = complement = false
+        previous = nil # :char, :set (a class escape like \d) or :range
+        until scanner.skip(/\]/)
+          # A nested class or POSIX bracket, or an intersection.
+          return nil if scanner.eos? || scanner.check(/\[|&&/)
+
+          if previous == :range && scanner.check(/-(?!\])/)
+            # A range cannot start from another range's own end: both
+            # engines read this hyphen as an ordinary member, not a new
+            # range operator. It may itself reopen a range on the next
+            # iteration, exactly as Ruby reads a repeated hyphen.
+            scanner.skip(/-/)
+            members << "-"
+            previous = :char
+          elsif previous && scanner.check(/-(?!\])/)
+            return nil unless previous == :char
+
+            scanner.skip(/-/)
+            # Checked again past the hyphen: `[$-&&%]` is an (empty)
+            # intersection in Ruby and a class accepting "%" in ECMA-262.
+            return nil if scanner.check(/\[|&&/)
+
+            text, kind = class_atom(scanner)
+            return nil unless kind == :char
+
+            members << "-" << text
+            previous = :range
+          elsif scanner.skip(/\\S/)
+            complement = true
+            previous = :set
+          else
+            text, previous = class_atom(scanner)
+            return nil unless text
+
+            space ||= text == SPACE
+            members << text
+          end
+          count += 1
+        end
+        return "[#{'^' if negated}#{members}]" unless complement
+
+        # \S cannot be spliced in as members, but two classes containing it
+        # can be written exactly. With \s beside it the class covers every
+        # character whatever either escape means, so ECMA-262's wider \s is
+        # harmless there — the `[\s\S]` any-character idiom. On its own it is
+        # the complement of Ruby's \s. Beside anything else it is refused.
+        return negated ? '[^\s\S]' : '[\s\S]' if space
+        return nil unless count == 1
+
+        negated ? "[#{SPACE}]" : "[^#{SPACE}]"
+      end
+
+      # One member of a class: its text and :char or :set.
+      def class_atom(scanner)
+        return [scanner.getch, :char] unless scanner.skip(/\\/)
+
+        if scanner.skip(/s/) then [SPACE, :set]
+        elsif scanner.scan(/[dDwW]/) then ["\\#{scanner.matched}", :set]
+        # Both an escaped - and a backspace \b are valid in a Unicode-mode
+        # class, and mean what they mean in Ruby.
+        elsif scanner.scan(/[-b]/) then ["\\#{scanner.matched}", :char]
+        else
+          text = literal_escape(scanner)
+          [text, :char] if text
+        end
+      end
+
+      # An escape that names one character. A letter or digit not listed is
+      # a Ruby-only escape (or octal) and refuses the translation; any other
+      # character is an identity escape, which Unicode mode accepts only for
+      # syntax characters — so those stay escaped and the rest (`\#`, `\-`
+      # outside a class, `\ `, `\_`) are written bare, meaning the same thing.
+      def literal_escape(scanner)
+        if scanner.scan(CHARACTER_ESCAPE) || scanner.scan(SYNTAX_ESCAPE) then "\\#{scanner.matched}"
+        elsif scanner.scan(/[^A-Za-z0-9]/m) then scanner.matched
+        end
+      end
+    end
+  end
+end

data/lib/permittable/json_schema.rb

@@ -1,3 +1,5 @@
+require "permittable/json_schema/ecma_pattern"
+
 module Permittable
   # Converts frozen contract data — the rule and field hashes built by
   # ContractBuilder — into JSON Schema (draft 2020-12, the dialect OpenAPI 3.1
@@ -7,13 +9,41 @@ module Permittable
   # actually enforces.
   #
   # The exported schema describes the DECLARED INPUT SHAPE in its canonical
-  # JSON encoding. Two deliberate consequences:
+  # JSON encoding. Three deliberate consequences:
   #   * Coercion additionally accepts string-encoded scalars ("42", "true")
   #     for form/query payloads; the schema documents the JSON types only.
+  #   * Coercion reads an explicit `null` as ABSENCE, so `{"age": null}` means
+  #     the same as `{}`. JSON Schema cannot say that — `type: integer` reads
+  #     null as a present value of the wrong type — so the schema rejects a
+  #     null the server would accept and ignore.
   #   * `validate:`/`transform:`/`finalize` are opaque callables — they never
   #     change what a client may SEND, so fields carrying them are flagged
   #     with `x-permittable-*` extensions rather than mistranslated.
   #
+  # All three leave the schema STRICTER than the server, never looser: a
+  # client that validates against the published document is conservative,
+  # never surprised by a 422. spec/schema_conformance_spec.rb holds that line,
+  # asserting the direction of every divergence it permits.
+  #
+  # Where a rule has no JSON Schema keyword, the schema is LOOSER instead,
+  # and a client following it can still earn a 422. Each such rule stays
+  # visible on its own field, and the conformance spec labels each one
+  # rather than letting it pass as agreement:
+  #   * a `:json` field's `max_depth:` — `x-permittable-max-depth`;
+  #   * a Range of non-numbers (`in: "a".."m"`) — `x-permittable-range`;
+  #   * a `validate:` proc — `x-permittable-custom-validation`;
+  #   * a `normalize:` step, which the server runs BEFORE it checks, so
+  #     "   " passes a minLength of 3 and is then absent —
+  #     `x-permittable-normalize`;
+  #   * the string encoding of :decimal, :date and :datetime, whose validity
+  #     rests on `format`, an annotation in draft 2020-12 — so "abc", "NaN"
+  #     and "2026-02-30" pass the schema and fail the cast;
+  #   * the string encoding of a BOUNDED :decimal, which minimum/maximum
+  #     (number-only keywords) never see — the numeric bound is published
+  #     for a client that parses first.
+  # (A `normalize:` step also runs the safe way: "  abcdefghij  " is too
+  # long for a maxLength of 10 and fine once squished.)
+  #
   # Emission is deterministic (fixed key insertion order, declaration-order
   # properties) so generated documents are committable and diff-stable.
   module JsonSchema
@@ -31,27 +61,6 @@ module Permittable
       datetime: { "type" => "string", "format" => "date-time" }
     }.freeze
 
-    # Ruby regexp constructs with no ECMA-262 equivalent (\Z, \h, \K, \R, \G,
-    # inline flag groups, absence operator, conditionals, POSIX classes,
-    # possessive quantifiers) — and Ruby's ^ and $, which anchor a LINE where
-    # ECMA-262 without the m flag anchors the whole string. /^\d{5}$/ accepts
-    # "evil\n12345" at runtime, so emitting its source as `pattern` would
-    # publish a rule stricter than the server enforces, and an export from
-    # contract data is supposed to make that impossible. Straight after a [
-    # neither is an anchor — ^ is class negation and $ is a literal — so both
-    # stay translatable there. Otherwise the scan is deliberately over-eager
-    # on escaped lookalikes, because a wrong pattern in published docs is
-    # worse than a missing one.
-    UNTRANSLATABLE = /
-      \\[ZhHKRG]          |
-      \(\?[a-z-]+[:)]     |
-      \(\?~               |
-      \(\?\(              |
-      \[\[:               |
-      [*+?]\+             |
-      (?<![\\\[])[\^$]
-    /x
-
     # Request-body schema for one rule from `permittable_contracts` /
     # `permit_rule_for`: the object schema of its fields, wrapped in the
     # `root:` envelope when the rule declares one. The wrapper itself stays
@@ -105,9 +114,18 @@ module Permittable
       schema
     end
 
+    # deep_dup, not dup: .freeze is shallow, so the Array nested in an entry
+    # like :decimal ("type" => %w[string number]) stays live inside the frozen
+    # top-level Hash, and a shallow .dup would hand every :decimal field's
+    # exported schema that SAME Array. Nothing in this file mutates it in
+    # place (nullify! rebinds "type" to a new Array), but the exported
+    # document is caller-owned data, and a caller appending to it would
+    # otherwise silently rewrite the constant for every schema exported
+    # afterward in the process.
     def scalar_schema(field)
-      schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
-      apply_in!(schema, field[:in])
+      schema = SCALAR_SCHEMAS.fetch(field[:type]).deep_dup
+      apply_format_name!(schema, field)
+      apply_in!(schema, field)
       apply_string_bounds!(schema, field)
       apply_pattern!(schema, field[:format])
       schema
@@ -126,20 +144,48 @@ module Permittable
       schema
     end
 
+    # A `format:` preset also names the JSON Schema `format` keyword the
+    # ecosystem understands, which a hand-written Regexp cannot. `pattern` is
+    # still emitted next to it: in draft 2020-12 `format` is an annotation
+    # unless a validator opts into asserting it, so the pattern is what
+    # actually enforces.
+    def apply_format_name!(schema, field)
+      json = FORMATS.dig(field[:format_name], :json)
+      schema["format"] = json if json
+    end
+
     def array_schema(field, unknown:)
       schema = { "type" => "array" }
       min, max = length_bounds(field[:length])
       schema["minItems"] = min if min
       schema["maxItems"] = max if max
-      schema["items"] = field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).dup
+      # deep_dup here for the same reason as scalar_schema: a scalar `of:`
+      # otherwise hands every array field the SAME nested Array/Hash from
+      # SCALAR_SCHEMAS.
+      schema["items"] =
+        field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).deep_dup
       schema
     end
 
-    def apply_in!(schema, allowed)
+    # A list is stored cast by the field's type, so its enum is what the
+    # runtime compares against; `in_published` overrides the members an
+    # exact re-encoding would get wrong (see Coercion.published_in_member).
+    # An object that only answers include? says nothing a schema can list —
+    # annotate flags it as custom validation instead.
+    def apply_in!(schema, field)
+      allowed = field[:in]
       return unless allowed
+      return if opaque_in?(allowed)
 
       unless allowed.is_a?(Range)
-        schema["enum"] = allowed.map { |v| json_value(v) }
+        # The same numeric-vs-string rule default:/example: use (decimal_json)
+        # applies here too — a :decimal in: member is otherwise always
+        # exported as a string, so a numerically-exported default: is no
+        # longer a member of its own enum's exported list. in_published (a
+        # :date/:datetime member kept in its authored String form, see
+        # Coercion.published_in_member) takes precedence over the cast
+        # members when both apply.
+        schema["enum"] = (field[:in_published] || allowed).map { |v| json_value(v, decimal: :number) }
         return
       end
       # Runtime bounds-checks Ranges with cover?; numeric endpoints map onto
@@ -149,8 +195,102 @@ module Permittable
         schema["x-permittable-range"] = allowed.inspect
         return
       end
-      schema["minimum"] = json_value(allowed.begin) if allowed.begin
-      schema[allowed.exclude_end? ? "exclusiveMaximum" : "maximum"] = json_value(allowed.end) if allowed.end
+      type = field[:type]
+      min = json_bound(allowed, "minimum", type) if allowed.begin
+      schema["minimum"] = min if min
+      keyword = allowed.exclude_end? ? "exclusiveMaximum" : "maximum"
+      max = json_bound(allowed, keyword, type) if allowed.end
+      schema[keyword] = max if max
+    end
+
+    # The types whose cast turns a JSON number into the value `in:` compares,
+    # so a published bound can be checked against the server's own verdict.
+    NUMERIC_TYPES = %i[integer float decimal].freeze
+
+    # minimum/maximum must be JSON numbers — the metaschema says so — so a
+    # bound is NOT an authored value for json_value, which renders a
+    # BigDecimal as its precision-safe string and made `in:
+    # BigDecimal("0.01")..BigDecimal("999.99")` publish an invalid document.
+    # Integer and Float pass through; any other Numeric (BigDecimal,
+    # Rational) becomes an Integer when it is one, else a Float.
+    #
+    # An infinite endpoint (Float::INFINITY, BigDecimal("Infinity")) means
+    # "no bound", and neither it nor NaN — which compares to nothing — is a
+    # JSON number, so both are omitted: nil. (to_i on either raises, which
+    # used to take the whole export down with it.)
+    #
+    # A Float cannot hold every decimal. to_f rounds to the NEAREST double,
+    # which can land on the wrong side of the bound: 0.1000000000000000001
+    # becomes 0.1, and a client sending 0.1 passes `minimum: 0.1` and is then
+    # refused. How far is "wrong" depends on the field's TYPE, not on the
+    # bound: a :decimal reads the number back as BigDecimal("0.1") and
+    # compares exactly, while a :float compares the Float through
+    # BigDecimal#<=>, which reads it at limited precision and so needs a few
+    # doubles more. Rather than model either, the bound asks the server:
+    # while the most extreme value the published keyword admits would be
+    # refused by the field's own cast and comparison, the bound moves one
+    # double INWARD. The published range can then only be narrower than the
+    # enforced one — the safe direction — and stops at the first double the
+    # server accepts. (It never moves outward: where a lossy comparison
+    # would also accept a few doubles beyond the nearest one, those stay
+    # unpublished.) A decimal of up to 15 significant digits — every price —
+    # round-trips through a double, so it is emitted as written.
+    #
+    # An INTEGRAL bound past Float::MAX (`10**400`) needs none of this: a
+    # JSON number literal has no size limit, so it is exact as published,
+    # with no Float rounding to guard against in the first place. Asking the
+    # server would instead break it — the field's own cast runs the bound
+    # through `to_f`, which overflows a value this large to Infinity — so
+    # the loop below walked the bound to Infinity and dropped it, though
+    # master published it as `minimum: 10**400` outright. It is returned
+    # here before the loop runs. A FRACTIONAL bound past Float::MAX has no
+    # such escape (there is no arbitrary-precision JSON number this exporter
+    # emits without going through Float) and stays omitted, same as a
+    # genuinely infinite bound — see CHANGELOG.
+    def json_bound(range, keyword, type)
+      value = keyword == "minimum" ? range.begin : range.end
+      return nil unless value.finite?
+
+      bound = value.is_a?(Float) || value != value.to_i ? value.to_f : value.to_i
+      return bound if bound.is_a?(Integer) && !bound.to_f.finite?
+
+      step = keyword == "minimum" ? :next_float : :prev_float
+      # A fractional bound past Float::MAX converts to Infinity, which no
+      # step moves; it is then as unrepresentable as an infinite one.
+      bound = bound.to_f.public_send(step) until !bound.finite? || honoured?(range, keyword, type, bound)
+      bound if bound.finite?
+    end
+
+    # Would the server accept the most extreme value `keyword: bound`
+    # admits? Only the one side is asked — a range narrower than a double
+    # can span admits no double at all, and checking both ends would never
+    # settle. A non-numeric field type has no cast to ask, so its bound is
+    # published as converted.
+    def honoured?(range, keyword, type, bound)
+      return true unless NUMERIC_TYPES.include?(type)
+
+      side = keyword == "minimum" ? (range.begin..) : Range.new(nil, range.end, range.exclude_end?)
+      status, value = Coercion.cast(type, admitted_extreme(keyword, type, bound))
+      status == :ok && side.cover?(value)
+    end
+
+    # The value nearest the bound that the published keyword still lets
+    # through: the bound itself for minimum/maximum, the double (or, on an
+    # :integer field, the integer) just below it for exclusiveMaximum.
+    def admitted_extreme(keyword, type, bound)
+      if type == :integer
+        return bound.ceil if keyword == "minimum"
+        return bound.floor if keyword == "maximum"
+
+        return bound.ceil - 1
+      end
+      keyword == "exclusiveMaximum" ? bound.to_f.prev_float : bound
+    end
+
+    # A host's own include?-answering object, kept by the contract as given —
+    # the same predicate the contract used to decide it was not a list.
+    def opaque_in?(allowed)
+      !allowed.nil? && !allowed.is_a?(Range) && Coercion.in_list(allowed).nil?
     end
 
     def apply_string_bounds!(schema, field)
@@ -175,17 +315,19 @@ module Permittable
       end
     end
 
-    # Conservative Ruby → ECMA-262 translation: \A/\z anchors become ^/$.
-    # Flagged regexps bail entirely (JSON Schema's `pattern` has no flag
-    # slot, and /x//m/i all change semantics), as does any source containing
-    # an untranslatable construct.
+    # Ruby → ECMA-262 translation, conservative by construction — see
+    # EcmaPattern. Flagged regexps bail entirely (JSON Schema's `pattern` has
+    # no flag slot, and /x//m/i all change semantics).
+    #
+    # A `format:` preset goes through the same translation as an app's own
+    # regexp and needs no exemption: the tokenizer reads a class as a unit,
+    # so the `*+` inside :email's class is two literals rather than a
+    # possessive quantifier, and :email's `\#` is written as the bare `#`
+    # Unicode mode requires.
     def ecma_pattern(regexp)
       return nil unless regexp.options.zero?
 
-      source = regexp.source
-      return nil if source.match?(UNTRANSLATABLE)
-
-      source.gsub('\A', "^").gsub('\z', "$")
+      EcmaPattern.translate(regexp.source)
     end
 
     # length: reasons about characters on strings and element count on
@@ -202,35 +344,98 @@ module Permittable
     end
 
     # Documentation keys shared by every field kind. `default:`/`example:`
-    # are authored values (possibly Date/Time/BigDecimal literals), so they
+    # are stored as the contract casts them (Date, Time, BigDecimal), so they
     # are re-encoded as JSON scalars.
+    #
+    # The :decimal numeric-export rule (decimal_json) is scoped to a
+    # :decimal field's OWN value and never recurses into a :json field's
+    # contents: those are opaque and pass through uncast, so a BigDecimal
+    # found inside one is documented the same way it always was — a string,
+    # via BigDecimal#to_s("F") — rather than reinterpreted as a JSON number
+    # (silently changing a value outside any :decimal schema's justification)
+    # or coerced through Float, where a non-finite BigDecimal (Infinity, NaN)
+    # would crash JSON.generate.
+    #
+    # A `sensitive:` field's `default:`/`example:` are OMITTED rather than
+    # published: this exported document is the one channel meant to leave
+    # the app (client-generator tooling, a public docs endpoint), unlike the
+    # request log a `sensitive:` value is otherwise only redacted from, so
+    # shipping the real value here would defeat the redaction entirely.
+    # Omitting — rather than a placeholder string — matches how every other
+    # untranslatable or opaque fact in this file is handled: left out, with
+    # the `x-permittable-*` extension (here, `writeOnly`/`x-permittable-
+    # sensitive`) as the only signal that something is missing.
     def annotate(schema, field)
-      schema["default"] = json_value(field[:default]) if field.key?(:default)
-      schema["examples"] = [json_value(field[:example])] if field.key?(:example)
+      decimal_mode = field[:kind] == JSON_TYPE ? :string : :number
+      unless field[:sensitive]
+        schema["default"] = json_value(field[:default], decimal: decimal_mode) if field.key?(:default)
+        schema["examples"] = [json_value(field[:example], decimal: decimal_mode)] if field.key?(:example)
+      end
       schema["description"] = field[:desc] if field[:desc]
       if field[:sensitive]
         schema["writeOnly"] = true
         schema["x-permittable-sensitive"] = true
       end
-      schema["x-permittable-custom-validation"] = true if field[:validate]
+      schema["x-permittable-custom-validation"] = true if field[:validate] || opaque_in?(field[:in])
       schema["x-permittable-transformed"] = true if field[:transform]
+      apply_normalize!(schema, field)
       schema
     end
 
-    def json_value(value)
+    # The server checks the NORMALIZED string, so minLength/maxLength/pattern
+    # describe a value the client never sends: under `normalize: :squish`,
+    # "   " satisfies a minLength of 3 and then squishes to "" (absent), and
+    # " a  " satisfies it and squishes to "a". JSON Schema has no keyword for
+    # "transform, then check", so the step is flagged rather than dropped —
+    # by the preset's name, which a client can apply itself, or `true` for a
+    # host proc, which is as opaque as `transform:`. The preset is recovered
+    # by identity from the resolved callable, because the contract stores the
+    # lambda it runs rather than the name it was declared by.
+    def apply_normalize!(schema, field)
+      normalizer = field[:normalize]
+      return unless normalizer
+
+      preset = NORMALIZERS.key(normalizer)
+      schema["x-permittable-normalize"] = preset ? preset.to_s : true
+    end
+
+    def json_value(value, decimal: :string)
       case value
-      when Array then value.map { |v| json_value(v) }
+      when Array then value.map { |v| json_value(v, decimal: decimal) }
       # An authored `:json` default/example is a whole hash; its values get
       # the same re-encoding as any other authored scalar.
-      when Hash then value.to_h { |k, v| [k.to_s, json_value(v)] }
-      when BigDecimal then value.to_s("F")
-      when Time then value.utc.iso8601
+      when Hash then value.to_h { |k, v| [k.to_s, json_value(v, decimal: decimal)] }
+      when BigDecimal then decimal == :number ? decimal_json(value) : value.to_s("F")
+      when Time then exact_iso8601(value.getutc)
       # DateTime subclasses Date, so it must match first.
-      when DateTime then value.to_time.utc.iso8601
+      when DateTime then exact_iso8601(value.to_time.getutc)
       when Date then value.iso8601
       when Symbol then value.to_s
       else value
       end
     end
+
+    # A :decimal default/example is stored cast — a BigDecimal, even when it
+    # was authored as `1.5` — and exporting every BigDecimal as a string
+    # turned the number such a default had always been published as into
+    # "1.5". So it is a JSON number whenever a Float carries it exactly (the
+    # Float's shortest text reads back as the same BigDecimal), which is what
+    # a JSON number is to most consumers anyway, and a string only when the
+    # precision would otherwise be lost. Both spellings are within the
+    # :decimal schema's own `["string", "number"]`.
+    def decimal_json(value)
+      float = value.to_f
+      BigDecimal(float.to_s) == value ? float : value.to_s("F")
+    end
+
+    # iso8601 prints whole seconds unless told otherwise, and a sub-second
+    # instant re-encoded that way names a DIFFERENT instant — one an `in:`
+    # listing the original refuses. So as many fractional digits as the
+    # value has, up to the nanoseconds Time#nsec can report.
+    def exact_iso8601(time)
+      nsec = time.nsec
+      digits = nsec.zero? ? 0 : 9 - nsec.to_s.rjust(9, "0")[/0*\z/].length
+      time.iso8601(digits)
+    end
   end
 end