permittable 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2284fdea0043c6364608ab68b43de16bbea66462f12a4f2e6ee5bdf47087fbb6
-  data.tar.gz: 8dd729f396cee1ba015179bd3ee8522754bc6312f4816810ed060134da8456d7
+  metadata.gz: '008b53fb20bca2df208a1bb8a09f942207790d4471b3e7346745df1806858184'
+  data.tar.gz: 2a3e3b24d9339ec2336f31690916bc1c25ef8206de97d94243d11497525d709b
 SHA512:
-  metadata.gz: 239926696fff412e35a4ef9bf0f392f92006c90a9ff8d69779a575eb71420ff441a433123a23c7d9e459d8eaf62d74bc9371aa1649bb739b4d89db60831d41ad
-  data.tar.gz: 04b5b1fe3b2993056a650f2f293a9a95e8c46f5c8bc5eb609929a0e93ae9e81591cc6434822fce5dcbfd06eb9ae4b17081165fdc817c91495abc59badba12339
+  metadata.gz: 424948f6d0d1f8115985432a55b0d6e64b4955a4142d0f98b51407fe718bb642217ae3b89303e07d80dd56f475a404f3628bb62e5941a21601c7d6283d07d2da
+  data.tar.gz: 43aa1e3832649fc76fb382dfd0719ec9012ea4adf50e67224af9a939b6631ad7b2837e4c25c52a38b24d03973c40fa367f8dadf388ef5d7905b6f88da76e9ae4

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 <!-- CHANGELOG.md -->
 
+## 0.16.0 (2026-11-15)
+<!-- title: date and boolean strings held to what the parser read, an audit that stops counting skipped contracts, and 422 rendered as an Integer -->
+
+Four changes to what a request, an audit, an export or a spec is held to. A `:boolean` refuses a number that only equals 1 or 0, and a `:date` or `:datetime` String refuses any part the parser did not read (#181). `permittable:audit` reports an action whose `enforce_params_contract` callback was skipped as `no contract` (#184). The gem passes the Integer 422 or 400 to `render`, so Rails 7.1 with Rack 3.1 stops printing a deprecation warning (#183). `Permittable::OpenAPI.document` exports a literal `permit_params "*"` action, and `permittable:generate` drafts carry more TODO hints and can no longer break a comment across lines (#182).
+
+Minor rather than patch: each entry can make a request, a boot, an audit gate or a spec that passes today fail. Before upgrading, read the entries that match what you use. A request can now be refused: a `:boolean` sent `1.0`, `0.0`, `BigDecimal("1")`, `Rational(1, 1)` or `Complex(1, 0)`, a `:date` or `:datetime` String with unread text (`"2026-01-01xyz"`, `"2026-01-15\n2099-12-31"`), and the localised or invisible-character forms that 0.15.1 read correctly (`"5. September 2026 um 10:00:00 MESZ"`, `"sam. 05 sept. 2026 10:00:00 CEST"`, `"2026-09-05‎"` with a left-to-right mark), all as `invalid_type` (#181). A boot can now fail: a `default:`, `example:` or `in:` on a `:boolean` field that holds such a number, and a `:date` or `:datetime` `example:` with unread text (#181). An audit gate can now fail: `permittable:audit[strict]` counts an `enforce: true` or monitor-mode action whose callback was skipped (#184). A spec can now fail: one that stubs `render` and expects `status: :unprocessable_entity` from the gem's own envelope now sees `422` (#183). No string that is still accepted is read as a different instant than on 0.15.1.
+
+### Fixed
+- **A `:boolean` refuses a number that only equals 1 or 0.** `true`, `false`, `"true"`, `"false"`, `"1"`, `"0"`, `1` and `0` are accepted as before. `1.0`, `0.0`, `BigDecimal("1")`, `Rational(1, 1)` and `Complex(1, 0)` were accepted on 0.15.1, so a JSON `1.0` was read as `true`; they are now `invalid_type`. A `default:`, `example:` or `in:` on a `:boolean` field that holds one raises at class load (`:default for field :b violates its own contract (invalid_type)`); write it as `true`, `false`, `1` or `0`. (#181)
+- **A `:date` or `:datetime` String with text the parser did not read is refused.** 0.15.1 accepted `"2026-01-01xyz"`, `"2026-01-15\n2099-12-31"`, `"2026-01-01 <script>"`, a NUL or zero-width character after the date, two conflicting offsets and `"2026-09-05 10:00 EST xyz"`; each is now `invalid_type`, and an authored `example:` in such a form raises at class load (`default:` and `in:` already did). Still read, as the same instant as 0.15.1: a browser `Date#toString` remark in brackets in any language (`"Sat Sep 05 2026 11:00:00 GMT+0300 (Москва, стандартное время)"`), a numeric offset followed by a zone abbreviation as a label, as Go's `time.String()` prints it (`"2026-09-05 10:00:00 +0800 CST"` is `02:00Z`), an RFC 9557 suffix (`"2026-09-05T10:00+01:00[Europe/Paris]"`), ActiveSupport `TimeWithZone#inspect` when the abbreviation and the offset agree, and one leading byte-order mark. Some other trailing junk is still read as on 0.15.1 (`"2026-09-05 22:00 am"`, a trailing `,` or `.`). (#181)
+- **Known limit: strings 0.15.1 read correctly are now refused.** Localised joiner and weekday words (`"5. September 2026 um 10:00:00 MESZ"`, `"Sa 5. Sep 10:00:00 CEST 2026"`, `"sam. 05 sept. 2026 10:00:00 CEST"`), a left-to-right mark or other invisible character anywhere, and a byte-order mark anywhere but once at the start. Send ISO 8601. (#181)
+- **A date String that 0.15.1 read as the wrong instant is refused.** A zone abbreviation followed by a different numeric offset (`"Sat, 05 Sep 2026 18:00:00 CST +08:00"` was `00:00Z` the next day), a spelled-out zone name with no brackets (`"... 10:00:00 AM Central European Summer Time"` was `16:00Z`) and `"EST5EDT"`. (#181)
+- **Cost.** A plain ISO date or date-time costs the same as on 0.15.1. Other accepted shapes cost about 0.4 to 0.6 ms per value, three to four times 0.15.1, and a string with more than 16 parts is refused before any reparse. (#181)
+- **`permittable:audit` no longer reports a skipped contract as covered.** An action whose `before_action` was removed with `skip_before_action :enforce_params_contract` (bare, `only:`, `except:`, `if:` or `unless:`; `ActionController::Base` and Metal; a subclass of a skipping parent) was covered in the audit, while a real request with an undeclared key got 200. An `enforce: true` or monitor-mode rule on such an action is now `no contract`, per action for `only:` and `except:`, with the note "request not checked before the action: skip_before_action :enforce_params_contract took its before_action off this action (checked only if the action reads permitted_params)", and `permittable:audit[strict]` counts it when the verb takes a body. A skip with `if:` or `unless:` is reported for every action it could reach, as "request may not be checked before the action: skip_before_action :enforce_params_contract is conditional (if:/unless:) and the audit cannot evaluate the condition (checked only if the action reads permitted_params)". This holds even when the action reads `permitted_params` and the request is validated there; to have such an action counted as covered, declare its rule lazily (neither `enforce: true` nor monitor mode, own or app-wide). Lazy rules are unchanged, and a `before_action :enforce_params_contract` declared again after the skip is covered again. The audit still cannot see a conditional skip made with `skip_callback`, a host's own `before_action :enforce_params_contract, only:` after a skip, or a `raise: false` skip on an ancestor that never included Permittable; see the README audit section. The matchers (`accept_params`, `reject_params`) do not see a skipped callback. (#184)
+- **The status the gem renders is an Integer.** On Rails 7.1 with Rack 3.1 or later, every 422 the gem rendered printed `warning: Status code :unprocessable_entity is deprecated and will be removed in a future version of Rack. Please use :unprocessable_content instead.` The gem now hands `render`, and a bare Metal controller's `status=`, the Integer 422 or 400; the response status line is unchanged on every Rails. `InvalidParameters#status` and the `status:` a host's `render_error` receives stay Symbols, so a `render_error` that forwards that Symbol to `render` still gets the warning on Rails 7.1 and can pass the Integer itself. A status that is neither a Symbol, a String nor an Integer is passed through; in the problem+json format it raised `NoMethodError` and rendered a 500 on 0.15.1, and now renders. (#183)
+- **`Permittable::OpenAPI.document` exports a literal `permit_params "*"` action.** It raised `NoMethodError` for a controller that declared one. (#182)
+- **A generated `# TODO` comment can no longer carry Ruby.** A column name containing a line break ended the comment, and the rest of the note became a line of Ruby in the drafted contract; the json-array and binary-column TODOs of 0.15.1 had this. Every drafted line now has its line breaks collapsed to a space. (#182)
+
+### Added
+- **`permittable:generate` drafts carry new TODO hints** for a `:decimal` column's precision and scale (the contract does not bound precision), a column named like a Rails request key (`format`, `controller`, `action`, `authenticity_token`), and a json column that holds arrays. (#182)
+- **README notes:** `permitted_params` is a `HashWithIndifferentAccess` in every mode; the cost of very many unknown keys under `unknown: :error`; a standalone `Contract` is fed the raw payload; a literal `"*"` action. (#182)
+
+### Changed
+- **`skip_before_action` is overridden on controllers that register the gem's callback**, to record a skip of `enforce_params_contract`; other skips are passed through untouched. `Permittable::Audit.inert?(controller, rule)` (undocumented) is gone. `Audit::Entry#inert` holds the reason (`:no_callbacks`, `:skipped` or `:conditional`) where it held `true`; `Entry#inert?` still returns true or false. (#184)
+
 ## 0.15.1 (2026-11-12)
 <!-- title: a date String's hour and glued offset read or refused, and the exported body and descriptors list the routing keys, a renamed CSRF token and a route's format default -->
 

data/README.md

@@ -536,7 +536,7 @@ request params
 
 Validation is **lazy by default**: it runs on the first `permitted_params` call, so an action that never reads params never pays for it. Pass `enforce: true` to run it in a `before_action` instead, rejecting bad requests before the action body executes. Results are **memoized per action**.
 
-In [monitor mode](#monitor-mode-roll-out-without-rejecting) the same flow runs, but a violation is reported instead of raised and the request proceeds with the raw params passed through.
+In [monitor mode](#monitor-mode-roll-out-without-rejecting) the same flow runs, but a violation is reported instead of raised and the request proceeds with the raw params passed through. `permitted_params` is a `HashWithIndifferentAccess` in every mode, never an `ActionController::Parameters`, so `.permitted?` and `.require` are not available on it and `Model.create!(permitted_params)` does not raise `ForbiddenAttributesError`.
 
 A bare `ActionController::Metal` controller has no callbacks and no `rescue_from` until it includes them. `include AbstractController::Callbacks` and then `include ActionController::Rescue` (the order `ActionController::Base` uses, so a rejection also covers the `before_action`), before or after `include Permittable`. The rendering modules (`AbstractController::Rendering`, `ActionController::Rendering`, `ActionController::Renderers::All`) are optional: without `ActionController::Rendering` the gem writes the error response itself, with the same status, content type and JSON body. An `enforce: true` rule, or a rule declaring `mode: :monitor`, raises `ArgumentError` at class load when `AbstractController::Callbacks` is missing. The class-load check reads only the rule's own `mode:`, not the app-wide `Permittable.mode`, which an initializer usually sets after the controller loads. A rule with no `mode:` under an app-wide `Permittable.mode = :monitor` therefore loads, but its `before_action` is not there to run it: `permittable:audit` reports those actions as `no contract` (`contract cannot run`) instead of as monitored. An `enforce: true` rule that is not in monitor mode still raises at class load when `ActionController::Rescue` is missing or was included before `AbstractController::Callbacks`. Both modules have to be in by the time of `permit_params`. A check registered at that first `permit_params` runs after any callback declared between the include and it (see [Per-request locales](#custom-error-messages-message)), and with `include Permittable` first, a `skip_before_action :enforce_params_contract` goes after the first `permit_params`, since the callback does not exist before it. On a bare `ActionController::Metal` controller that includes `ActionController::Rescue` after `include Permittable`, the gem registers its handler at the first `permit_params` instead, so there it is a catch-all declared after that `permit_params` that answers first, and a re-declaration goes after it.
 
@@ -570,6 +570,8 @@ class ReportsController < ApiController
 end
 ```
 
+A literal `"*"` in `permit_params` is only an action name: it matches an action called `"*"` and nothing else, and a rule with no actions is the catch-all. The `"*"` key is the OpenAPI export's catch-all marker for plain-Ruby hosts only.
+
 Rules accumulate by **reassignment, never mutation**, so subclasses inherit copy-on-write and can never corrupt a parent's contract.
 
 ### The field DSL
@@ -694,13 +696,13 @@ Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`.
 | `:integer` | `Integer`; whole `Float`s (`4.0`); canonical base-10 numeric strings (`"-12"`, `"007"`) | `"4.5"`, `"abc"`, `"1_8"`, `" 99 "`, `4.5`, NaN/Infinity |
 | `:float` | a real `Numeric`; a canonical numeric string (`"1.5"`, `".5"`, `"-2e3"`) | `"abc"`, `"1_8.5"`, `" 1.5 "`, and any number outside a Float's range, as a `Numeric` or a string alike (`BigDecimal("1e-400")`, `"1e400"`), a `Complex` (even `Complex(1, 0)`), a `Numeric` that cannot be converted |
 | `:decimal` | a real `Numeric`, or a canonical numeric string → `BigDecimal`; a `Rational` whose decimal expansion is exact (`Rational(1, 2)`, `3r`) | Unparseable strings, `"1_000"`, `" 1.5 "`, a `Complex`, a `Rational` no decimal holds exactly (`Rational(1, 3)`), a `Numeric` that cannot be converted |
-| `:boolean` | `true`/`false`, `"true"`/`"false"`, `"1"`/`"0"`, `1`/`0` | `"yes"`, `"on"`, `2` |
+| `:boolean` | `true`/`false`, `"true"`/`"false"`, `"1"`/`"0"`, the Integers `1`/`0` | `"yes"`, `"on"`, `2`, and a number that merely equals 1 or 0 (`1.0`, which is how JSON can send it) |
 | `:date` | `Date`; a `Time`, `DateTime` or `ActiveSupport::TimeWithZone` that is exactly midnight UTC, as that `Date`; a string naming a **complete** date, in any format `Date.parse` understands (`"2026-09-05"`, `"2026/09/05"`, `"Sep 5, 2026"`); a string with a time or zone only if it is exactly midnight UTC (`"2026-09-05T00:00:00Z"`) | Unparseable strings, **incomplete** ones (`"09/2026"`, `"5th"`, `"Sept"`), and any other instant, as an object or a string — one with a time of day, or a midnight in another zone |
 | `:datetime` | `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, `Date`; a string naming a complete date, with or without a time (an ISO date with an offset or `Z` and no time, `"2026-09-05-05:00"`, is midnight at that offset) | Unparseable strings, any string without a complete date (`"10:30"`), any other date followed by a bare offset and no time of day (`"Sep 5 2026 -05:00"`), an offset or an hour the parser would drop (`"12:00 2026-09-05 -05:00"`, `"2026-09-05 10 -05:00"`, `"2026-09-05T10"`), any word after a date that is not a zone Ruby knows, a day name or an era (`"2026-09-05 XYZ"`, `"2026-09-05 noon"`), and an ISO date followed by `T` and no time (`"2026-09-05T"`) |
 | `:json` | Any `Hash` — passed through uncast, see [free-form hashes](#free-form-hashes-json) | Arrays, scalars |
 | `:file` | An upload object (`ActionDispatch::Http::UploadedFile`, `Rack::Test::UploadedFile`), passed through uncast | A `String` (including a form's file field sent as text), numbers, hashes, arrays |
 
-**Dates are parsed, never guessed.** `Date.parse` fills in what a string omits *from today* — `"09/2026"` becomes the 1st, `"5th"` becomes this month of this year — so the same request would mean different things on different days. A `:date` or `:datetime` string must therefore name all three of year, month and day; which **format** it names them in is `Date.parse`'s business, so every complete format it understands still works. A `:datetime` may omit the *time* part, which reads as midnight UTC. An ISO date with an offset or `Z` and no time is midnight at that offset (`"2026-09-05 -05:00"` is `2026-09-05T05:00:00Z`; a `:date` takes it only where that is midnight UTC, as in `"2026-09-05+00:00"`); any other date followed by a bare offset and no time of day is refused, since Ruby's parser reads the offset as a time of day or drops it, and so is an ISO date followed by `T` and no time. A zone *name* after a date is honoured where Ruby knows it, with or without a time (`"2026-09-05 EST"` is `2026-09-05T05:00:00Z`, so a `:date` refuses it, and `"Sat Sep  5 10:00:00 2026 EST"` is `15:00:00Z`), and refused where it does not. So is **any other word** after a complete date that is not a day name or an era (`"2026-09-05 XYZ"`, `"2026-09-05 noon"`, `"2026-09-05 foo"`): all it can be is a zone, and a zone Ruby cannot honour is never guessed at. An offset glued to a zone name with no time is midnight at that offset where Ruby honours it (`"2026-09-05 GMT+5"` is `2026-09-04T19:00:00Z`) and refused where it does not (`"2026-09-05 UTC+99"`, `"2026-09-05 EST+5"`). An offset after the year of git's and ctime's format is read (`"Sat Sep  5 10:00:00 2026 -0500"` is `15:00:00Z`). An hour or offset the parser would drop or misread (`"2026-09-05T10"`, `"2026-09-05 10 -05:00"`, `"2026-09-05 10 A.D."`, `"2026-09-05 10 a"`, `"12:00 2026-09-05 -05:00"`) is refused rather than read as some other instant.
+**Dates are parsed, never guessed.** `Date.parse` fills in what a string omits *from today* — `"09/2026"` becomes the 1st, `"5th"` becomes this month of this year — so the same request would mean different things on different days. A `:date` or `:datetime` string must therefore name all three of year, month and day; which **format** it names them in is `Date.parse`'s business, so every complete format it understands still works. A `:datetime` may omit the *time* part, which reads as midnight UTC. An ISO date with an offset or `Z` and no time is midnight at that offset (`"2026-09-05 -05:00"` is `2026-09-05T05:00:00Z`; a `:date` takes it only where that is midnight UTC, as in `"2026-09-05+00:00"`); any other date followed by a bare offset and no time of day is refused, since Ruby's parser reads the offset as a time of day or drops it, and so is an ISO date followed by `T` and no time. A zone *name* after a date is honoured where Ruby knows it, with or without a time (`"2026-09-05 EST"` is `2026-09-05T05:00:00Z`, so a `:date` refuses it, and `"Sat Sep  5 10:00:00 2026 EST"` is `15:00:00Z`), and refused where it does not. So is **any other word** after a complete date that is not a day name or an era (`"2026-09-05 XYZ"`, `"2026-09-05 noon"`, `"2026-09-05 foo"`): all it can be is a zone, and a zone Ruby cannot honour is never guessed at. An offset glued to a zone name with no time is midnight at that offset where Ruby honours it (`"2026-09-05 GMT+5"` is `2026-09-04T19:00:00Z`) and refused where it does not (`"2026-09-05 UTC+99"`, `"2026-09-05 EST+5"`). An offset after the year of git's and ctime's format is read (`"Sat Sep  5 10:00:00 2026 -0500"` is `15:00:00Z`). An hour or offset the parser would drop or misread (`"2026-09-05T10"`, `"2026-09-05 10 -05:00"`, `"2026-09-05 10 A.D."`, `"2026-09-05 10 a"`, `"12:00 2026-09-05 -05:00"`) is refused rather than read as some other instant. Likewise any part of the string the parser read nothing from is refused, not dropped: junk after, before or between dates (`"2026-01-01xyz"`, `"2026-01-15\n2099-12-31"`, `"2026-01-01 <script>"`), and control or zero-width characters (bar one leading byte-order mark, which a CSV or text file saved as UTF-8 starts with, and which is dropped). What is let through repeats something that was read: a remark in brackets (`"(Central Daylight Time)"`, `"(Москва, стандартное время)"`, in any language, with commas, `&` or a nested bracket but no digits), an RFC 9557 suffix (`"[Europe/London]"`, `"[GMT+01:00]"`, the offset governs), Go's `m=+0.1`, and an offset or zone name that agrees with the one read (`"EDT -04:00"`), and a zone abbreviation after a numeric offset, which only labels it (`"2026-09-05 10:00:00 +0800 CST"` is `02:00:00Z`, as Go and `date` print it). Two zones in the other order (`"EDT -0700"`, `"CST +08:00"`: the abbreviation is what is read) or two different offsets are refused.
 
 **Strings in other encodings are inspected, never converted.** A String whose bytes are not valid in its **own** encoding (`"caf\xC3"` in UTF-8, a lone UTF-16 surrogate) is `invalid_type` for every scalar type, before `normalize:` or `format:` sees it. Any other String keeps its encoding: a `:string` value is handed back exactly as it arrived, so a controller using Rails' `skip_parameter_encoding` or `param_encoding` gets its binary or Shift_JIS text unchanged. The number, boolean and date types parse a UTF-8 **copy** of the text, so UTF-16 `"12"` casts to `12` for an `:integer`; when the text has no UTF-8 reading (a byte Windows-1252 leaves undefined) that is `invalid_type`. `normalize:` and `format:` work on the String in its own encoding. Where a normalizer cannot handle that encoding (`:squish` on UTF-16), the value is left as it is; where a `format:` pattern cannot be applied to it (a non-ASCII pattern against UTF-16 or binary bytes), that is a `format` violation. `in:` compares Strings as Ruby does, encoding included. A `:json` field's contents are not examined.
 
@@ -810,7 +812,7 @@ rescue_from Permittable::InvalidParameters, with: :render_invalid_parameters
 
 Paths are fully qualified: `user.address.zip`, `line_items[1].sku`.
 
-**`details` is complete; `message` is prose.** The `details` array names **every** offender, however many there are — it is the machine-readable channel and nothing is dropped from it. The `message` string is a sentence for a person, and it also lands in your logs and in every exception tracker, so it is bounded: at most ten offenders, each truncated past 120 characters, then a count of the rest (`…, and 49990 more`). Before that bound, a request carrying 50,000 undeclared keys against `unknown: :error` produced a **1 MB** exception message and a 1 MB log line. The 422 body still carries the complete `details`, so it stays proportional to the number of violations; the field bounds are what keep that number down.
+**`details` is complete; `message` is prose.** The `details` array names **every** offender, however many there are — it is the machine-readable channel and nothing is dropped from it. The `message` string is a sentence for a person, and it also lands in your logs and in every exception tracker, so it is bounded: at most ten offenders, each truncated past 120 characters, then a count of the rest (`…, and 49990 more`). Before that bound, a request carrying 50,000 undeclared keys against `unknown: :error` produced a **1 MB** exception message and a 1 MB log line. The 422 body still carries the complete `details`, so it stays proportional to the number of violations; the field bounds are what keep that number down. The check itself lists one violation per undeclared key, so its cost grows with the key count (tens of seconds at a few hundred thousand keys, growing linearly); cap the request body size or key count in front of the app.
 
 **Status codes.** A bad root key renders **400** — the request is malformed; the envelope you asked for isn't there, or isn't an object. Field-level violations render **422** — well-formed, semantically wrong. The two root failures are told apart by their code: `missing` when the key really is absent (`{}`, `{"user": null}`, `{"user": ""}`), `invalid_type` when the client sent it with the wrong shape.
 
@@ -1303,6 +1305,8 @@ Three things it tells you that nothing else does:
 - **Which contracts aren't enforcing yet.** The audit runs inside the app, so unlike the exported OpenAPI it resolves the **effective** mode — a rule's own `mode:` first, then your app-wide `Permittable.mode`. This is the [monitor-mode](#monitor-mode-roll-out-without-rejecting) rollout dashboard.
 - **Which contracts have gone stale.** A contract declared for an action no route reaches, or for a routed action Rails would 404, is a renamed or deleted action that left its contract behind. A contract on a shared base controller is stale only when no controller that inherits it reaches the action, and it is listed once, under the class that declares it.
 
+A contract that validates from the `before_action` (an `enforce: true` rule, or one in monitor mode) but whose callback was removed with a plain `skip_before_action :enforce_params_contract` reads `no contract — request not checked before the action: ...`, and counts against `[strict]` if it takes a body. `enforce: true` promises the check runs before the action whatever the action does, and the skip took that away. The note says the request is checked only if the action reads `permitted_params`: one that does is still validated there (rejected, or a monitor event), so the row can be a gap that is not one in practice. The audit does not read the action's code. To have such an action count as covered, declare its rule as a lazy one, neither `enforce: true` nor monitor mode (its own `mode:` or an app-wide `Permittable.mode = :monitor`, which makes every rule a monitor one): it validates when the action reads `permitted_params`, skip or not, and the audit reads it as covered. A subclass that skips what its parent declared is reported the same way, and so is a child's own `permit_params` under a parent that skipped it, since the callback is registered once per class tree and is not put back. A skip with `only:` or `except:` is read per action, the way Rails compares them (Symbols or Strings, one name or an Array): the actions it names read as above, the ones it spares stay covered. Skips in a row add up, and a subclass's skip never reaches its parent. A skip with `if:` or `unless:` cannot be evaluated without running your code, so every action it could reach reads `no contract — request may not be checked before the action: ... is conditional`, whether or not the condition holds at request time; an `only:` skip that also has `if:` is reported as skipped for the actions it names. Declaring `before_action :enforce_params_contract` again after a skip puts the check back, and the audit reads it as covered. The audit learns of a skip from the `skip_before_action` call itself (the gem wraps it on the controller once it registers its callback), so three things stay invisible: a skip made with `raise: false` on an ancestor that never included `Permittable` (it has nothing to skip itself, Rails rewrites the callback of the subclass that registered it, and nothing is recorded), a conditional skip made with `skip_callback(:process_action, :before, :enforce_params_contract, if: ...)` directly, and a `before_action :enforce_params_contract, only: ...` the app declares itself. All leave the action reported as covered; a skip made with `skip_callback` and no condition removes the callback and is reported. Check those with a request spec.
+
 A route that lists several verbs is audited once per verb. A `match ... via: :all` route is expanded into exactly GET, POST, PUT, PATCH and DELETE, and listed once for each. Rails sends a request to the first route that matches its path and verb, and the audit lists what Rails dispatches. With `get "hooks", to: "webhooks#index"` before `match "hooks", to: "webhooks#receive", via: :all`, `GET /hooks` is listed under `index` only, and `receive` gets the other four verbs. Turn the two around and the `get` route is never reached, so it is not listed, and a contract on `index` shows as stale. The same rule removes a route declared twice, and the OpenAPI export applies it too. Only an unconstrained route hides the routes behind it, and only on the identical path. A route with a constraint can pass a request on: a segment requirement (`id: /\d+/`), a subdomain or host, or a constraint object or lambda. So the routes after it stay listed, even when the constraint happens to admit every request. With `constraints(AdminConstraint) { post "settings", ... }` ahead of `post "settings", to: "settings#update"`, every non-admin `POST` reaches `settings#update`, so its row stays and `[strict]` still counts it. The audit errs towards an extra row rather than a hidden route. Paths that differ at all, even only in a variable's name (`users/:id` and `users/:slug`), are both listed. `resources` routes all seven actions whether or not they exist. A route that Rails would 404 reads `action not found`: no method (inherited ones count), no `action_missing`, and no template to render implicitly. It is not counted against `[strict]` or as coverage. It stays in the table rather than disappearing. The template check uses the class-level view paths and the default lookup details. So a template that is only found at request time reads `action not found`, for example one behind a `prepend_view_path` in a `before_action`, or one that exists only as a variant.
 
 A catch-all 404 route (`match "*path", to: "application#not_found", via: :all`) shows its POST, PUT and PATCH rows as accepting a body. They do accept one: every stray body reaches the controller. Route only GET to the controller (Rails answers HEAD from it). Send the other verbs to a plain Rack endpoint, which never parses the body and which the audit does not list:
@@ -1430,7 +1434,7 @@ Both work on a controller class, a controller instance, or a [standalone `Contra
 
 The negated forms follow the same rules as `not_to permit_param`: `not_to accept_params(...)` passes only when the contract rejects the payload, and `not_to reject_params(...)` only when it accepts it. Neither takes a qualifier — `not_to accept_params(...).returning(x)` would pass both on a rejection and on an acceptance returning anything else, so it raises and names the positive form — and both fail, rather than passing, when no rule covers the action or the subject declares no contracts.
 
-The matchers run **without a request**, so they know the controller's settings but not its route. The CSRF parameter name set at class level with `request_forgery_protection_token` is exempt from `unknown: :error` as it is at runtime, but a per-instance override is not seen, and neither are a route's **path parameters**: a payload `id` on a member action under `unknown: :error` is reported `unknown`, although a real `PATCH /users/1` carries it in the URL and is accepted. Leave path parameters out of the payload you pass to `accept_params` / `reject_params`. On a controller the payload goes through the same normalization a request gets, so a `nil` array element is dropped as Rails drops it (unless the app turned `perform_deep_munge` off), and a Symbol value (`status: :active`) reads as the String a request carries; a standalone `Contract` gets the payload as given, so a Symbol value there is still `invalid_type`. A failure message that echoes params (the returned hash, a `returning` expectation) redacts them like a request log: the names of `sensitive:` fields, plus the app's `config.filter_parameters` when a Rails application is booted. Matching is by substring, like Rails, so `sensitive: true` on `pin` also redacts `shipping`; when a `returning` mismatch is hidden by that, the message adds `differs at: pin, shipping`, names only. Under a `root:` contract the hash is filtered as the request logs it, under its root, so a scoped filter such as `"payment.number"` applies; the note stops at a redacted key and never names anything below it.
+The matchers run **without a request**, so they know the controller's settings but not its route. The CSRF parameter name set at class level with `request_forgery_protection_token` is exempt from `unknown: :error` as it is at runtime, but a per-instance override is not seen, and neither are a route's **path parameters**: a payload `id` on a member action under `unknown: :error` is reported `unknown`, although a real `PATCH /users/1` carries it in the URL and is accepted. Leave path parameters out of the payload you pass to `accept_params` / `reject_params`. On a controller the payload goes through the same normalization a request gets, so a `nil` array element is dropped as Rails drops it (unless the app turned `perform_deep_munge` off), and a Symbol value (`status: :active`) reads as the String a request carries; a standalone `Contract` gets the raw payload as given, with no deep munge and no Symbol-to-String conversion of values (a Symbol value there is still `invalid_type`), because `Contract#call` is fed by app code, not by a request. A failure message that echoes params (the returned hash, a `returning` expectation) redacts them like a request log: the names of `sensitive:` fields, plus the app's `config.filter_parameters` when a Rails application is booted. Matching is by substring, like Rails, so `sensitive: true` on `pin` also redacts `shipping`; when a `returning` mismatch is hidden by that, the message adds `differs at: pin, shipping`, names only. Under a `root:` contract the hash is filtered as the request logs it, under its root, so a scoped filter such as `"payment.number"` applies; the note stops at a redacted key and never names anything below it. They do not see a skipped `enforce_params_contract` callback either: `reject_params` still passes for an action whose real request is not checked before the action runs, because its callback was removed with `skip_before_action`. `permittable:audit` is what reports that.
 
 ### Standalone contracts (no controller)
 
@@ -1487,7 +1491,7 @@ Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
 
 Every operation references shared components for the [error envelope](#violations-and-error-responses): a `422` response always, plus a `400` when the contract declares a `root:`. So consumers get typed *errors*, not just typed inputs.
 
-**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a construct with no faithful ECMA-262 spelling is exported as `x-permittable-pattern` rather than a mistranslated `pattern`: a Ruby-only escape or flag, one ECMA-262 reads differently or refuses to compile at all (`{,3}`, `&&` in a class, a backreference, the word boundary `\b`), or one that cannot be carried once folded into the rest of its own character class (`\S` beside a member other than `\s`) — but **not** a hyphen right after a completed range (`[a-c-e]`), which both dialects read the same way and export unchanged. This also covers a regexp anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` at runtime and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`, and a rule's `finalize` block `x-permittable-finalize` (on the rule's own object, inside the `root:` wrapper when there is one, and on the operation too, so the marker survives an operation that has no request body); actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route — or whose path-and-verb slot another controller already claimed, which one document cannot represent twice, or whose route an earlier one shadows (below) — land in `x-permittable-controllers` instead of being dropped. A templated path segment is declared as a path `parameter` of type `string` unless the contract says more, because the route set doesn't say what an `:id` is and the exporter won't invent it: a rootless contract's *scalar* field of the same name is that parameter's schema (see [Unknown parameters](#unknown-parameters) for what that does to the request body), minus any `default:` and `nullable:`, since the URL always supplies a non-null value. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a construct with no faithful ECMA-262 spelling is exported as `x-permittable-pattern` rather than a mistranslated `pattern`: a Ruby-only escape or flag, one ECMA-262 reads differently or refuses to compile at all (`{,3}`, `&&` in a class, a backreference, the word boundary `\b`), or one that cannot be carried once folded into the rest of its own character class (`\S` beside a member other than `\s`) — but **not** a hyphen right after a completed range (`[a-c-e]`), which both dialects read the same way and export unchanged. This also covers a regexp anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` and `"12345\n"` at runtime (the trailing newline too, not only in the export), and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`, and a rule's `finalize` block `x-permittable-finalize` (on the rule's own object, inside the `root:` wrapper when there is one, and on the operation too, so the marker survives an operation that has no request body); actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route — or whose path-and-verb slot another controller already claimed, which one document cannot represent twice, or whose route an earlier one shadows (below) — land in `x-permittable-controllers` instead of being dropped. A templated path segment is declared as a path `parameter` of type `string` unless the contract says more, because the route set doesn't say what an `:id` is and the exporter won't invent it: a rootless contract's *scalar* field of the same name is that parameter's schema (see [Unknown parameters](#unknown-parameters) for what that does to the request body), minus any `default:` and `nullable:`, since the URL always supplies a non-null value. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
 
 **Mounted engines are documented under their mount point.** The task follows each `mount Billing::Engine => "/billing"` into the engine's routes, so an engine's operations land in `paths` as `/billing/...` (a dynamic mount point becomes a `{tenant}` template). A Rack mount that is not an engine is skipped. See [Auditing coverage](#auditing-coverage-permittableaudit) for the details and the one limit on shared parameter names.
 
@@ -1521,6 +1525,11 @@ Where they legitimately differ, the spec names the reason and asserts the **dire
 - **`null` as absence.** The runtime reads `{"age": null}` as `{}` ([absence](#absence-defaults-and-partial-updates)); JSON Schema cannot express that, so `type: integer` rejects a null the server would accept and ignore. A [`nullable:`](#explicit-nulls-nullable) field is not this case — there the null is a value, the exported `type` widens to say so, and the two agree.
 - **Padding that normalizes away.** `normalize:` runs before the checks, so under `normalize: :squish` and `length: 3..10` the server accepts `"  abcdefghij  "` — ten characters once squished — while the docs reject its fourteen.
 
+Two more go the same way but sit outside that spec's JSON-only harness (it has no multipart or Rails-parsing step), so they are documented here and not asserted there:
+
+- **Rails' `rows[][name]` naming.** The server accepts Rails' unindexed form naming in a multipart body; the export describes only the indexed `rows[0][name]` form.
+- **A dropped array element.** Rails' parameter parsing removes a `null` element before the contract runs, and the contract drops a blank one from a non-string array (`""` in an `:integer` array), while the schema's `items` refuses both. A standalone `Contract` still refuses `["a", null]`.
+
 Seven cases go the other way, and are worth knowing before you hand the document to a client. Each rule stays visible on its own field, and the spec asserts that as well as the direction:
 
 - **Bounds JSON Schema has no keyword for.** A `:json` field's `max_depth:` is enforced by the server but cannot be written as a JSON Schema keyword, so the published document is **looser** there and an over-nested payload still earns a 422. The bound is not dropped — it is exported as `x-permittable-max-depth` — so a generator or linter that wants it can read it.

data/lib/permittable/audit.rb

@@ -43,14 +43,24 @@ module Permittable
       outside_root: "Ignored as outside the app root (set Permittable.audit_ignore_outside_root = false to audit them):"
     }.freeze
 
+    # What an entry's `inert` reason reads as in the table.
+    INERT_NOTES = {
+      no_callbacks: "contract cannot run: controller lacks AbstractController::Callbacks (no before_action)",
+      skipped: "request not checked before the action: skip_before_action :enforce_params_contract took its " \
+               "before_action off this action (checked only if the action reads permitted_params)",
+      conditional: "request may not be checked before the action: skip_before_action :enforce_params_contract is " \
+                   "conditional (if:/unless:) and the audit cannot evaluate the condition " \
+                   "(checked only if the action reads permitted_params)"
+    }.freeze
+
     # One routed action, paired with the rule a request for it would resolve
     # through (nil when nothing covers it — including when the controller
     # never included the concern, which is exactly the case worth finding).
     #
     # `missing_action` marks a route to an action the controller does not
     # define — see Audit.missing_action?. `inert` marks one whose rule exists
-    # but cannot run, so `rule` is nil and the action is uncovered — see
-    # Audit.inert?. `route` identifies the route the
+    # but cannot run, so `rule` is nil and the action is uncovered: the reason,
+    # :no_callbacks, :skipped or :conditional — see Audit.inert_reason. `route` identifies the route the
     # path came from (nil for a hand-built descriptor, which is then its own
     # route); see `summary`. `ignored` is why the entry is left out of the
     # counts — a key of IGNORE_REASONS — or nil when it is audited.
@@ -69,7 +79,7 @@ module Permittable
       end
 
       def inert?
-        inert == true
+        !inert.nil?
       end
 
       # The mode this action would actually run in, rule-level declaration
@@ -118,32 +128,74 @@ module Permittable
       routes.select { |route| route[:controller].to_s == key }.map do |route|
         action = route[:action].to_s
         rule = rule_for(controller, action)
-        inert = inert?(controller, rule)
+        inert = inert_reason(controller, rule, action)
         Entry.new(controller: key, action: action, verb: route[:verb], path: route[:path],
                   rule: (rule unless inert), missing_action: missing[action], route: route[:route],
                   ignored: configured_ignore(key, action, ignore) || outside, inert: inert)
       end
     end
 
-    # Whether `rule` is declared on `controller` but can never run there: the
-    # gem never registered its before_action on it — a bare ActionController::
-    # Metal controller without AbstractController::Callbacks at its
-    # `permit_params`, which asks the flag the gem sets when it registers the
-    # callback (a callbacks module included afterwards does not undo that) —
-    # while the rule validates from that callback: an `enforce: true` rule, or
-    # one in monitor mode by its own mode: or the app-wide Permittable.mode.
-    # permit_params raises for this at class load, but reads only the rule's own
-    # mode, since the app-wide one is often set after the class loads; the
-    # effective mode is judged here. Such an action is audited as uncovered
-    # rather than as the monitored one it claims to be.
-    def inert?(controller, rule)
-      return false unless rule && defined?(::ActionController::Metal) && controller.is_a?(Class) &&
-                          controller < ::ActionController::Metal
-
-      (rule[:enforce] || (rule[:mode] || Permittable.mode) == :monitor) &&
+    # Why `rule` is declared on `controller` but may not run for `action`, or
+    # nil when it does: the gem's before_action is not in the controller's
+    # callback chain, or is skipped for that action, while the rule validates
+    # from that callback (an `enforce: true` rule, or one in monitor mode by
+    # its own mode: or the app-wide Permittable.mode). One of
+    # - :no_callbacks: a bare ActionController::Metal controller without
+    #   AbstractController::Callbacks at its `permit_params`, where the gem
+    #   never registered it (a callbacks module included afterwards does not
+    #   undo that);
+    # - :skipped: `skip_before_action :enforce_params_contract` took it out of
+    #   this class's chain and its subclasses' (permit_params does not register
+    #   it a second time), or its only:/except: name this action;
+    # - :conditional: a skip with if:/unless: that could reach this action,
+    #   whose condition the audit does not evaluate, since that is host code.
+    # permit_params raises for the first at class load, but reads only the
+    # rule's own mode, since the app-wide one is often set after the class
+    # loads; the effective mode is judged here. Such an action is audited as
+    # uncovered rather than as the monitored or enforced one it claims to be.
+    #
+    # The conditions of a skip are read from the record Permittable::SkipRecorder
+    # keeps of the `skip_before_action` call, and apply only while the callback
+    # in the chain is the one that call left. A skip made with `skip_callback`
+    # directly, or a `before_action :enforce_params_contract` of the host's own
+    # with conditions, is not seen unless it removed the callback outright.
+    def inert_reason(controller, rule, action)
+      return unless rule && (rule[:enforce] || (rule[:mode] || Permittable.mode) == :monitor)
+      return :no_callbacks if never_registered?(controller)
+      return unless controller.respond_to?(:_process_action_callbacks)
+
+      callback = controller._process_action_callbacks.find { |c| c.kind == :before && c.filter == :enforce_params_contract }
+      callback ? skip_reason(controller, callback, action) : :skipped
+    end
+
+    def skip_reason(controller, callback, action)
+      held = controller.permittable_skips if controller.respond_to?(:permittable_skips)
+      return unless held && held[:callback].equal?(callback)
+
+      effects = held[:skips].map { |skip| skip_effect(skip, action) }
+      effects.include?(:skipped) ? :skipped : effects.compact.first
+    end
+
+    # What one skip does to `action`, as Rails composes it: each skip adds its
+    # only: and except: to the callback as conditions that must all hold, so
+    # the action is skipped when it is in only: or outside except:. An if: or
+    # unless: makes it :conditional wherever only:/except: do not skip it.
+    def skip_effect(skip, action)
+      named = skip[:only]&.include?(action) || (skip[:except] && !skip[:except].include?(action))
+      return :skipped if named || (skip[:only].nil? && skip[:except].nil? && !skip[:conditional])
+
+      :conditional if skip[:conditional]
+    end
+
+    def never_registered?(controller)
+      defined?(::ActionController::Metal) && controller.is_a?(Class) && controller < ::ActionController::Metal &&
         !(controller.respond_to?(:permittable_callback_registered) && controller.permittable_callback_registered)
     end
 
+    # module_function made public singleton copies of these; they are this
+    # module's own steps, not API.
+    private_class_method :inert_reason, :skip_reason, :skip_effect, :never_registered?
+
     # Why `controller` — or one of its actions — is left out of the audit and
     # of permittable:generate: :configured (Permittable.audit_ignore names the
     # controller, or "controller#action"), :outside_root, or nil. The
@@ -490,8 +542,7 @@ module Permittable
     def inert_note(entry)
       return unless entry.inert?
 
-      ["contract cannot run: controller lacks AbstractController::Callbacks (no before_action)",
-       ("ACCEPTS A BODY" if entry.body?)].compact.join(" — ")
+      [INERT_NOTES.fetch(entry.inert), ("ACCEPTS A BODY" if entry.body?)].compact.join(" — ")
     end
 
     # The one wording for a route Rails would 404, covered or not.

data/lib/permittable/error_envelope.rb

@@ -72,6 +72,9 @@ module Permittable
     # response_body=. `render json:` calls `to_json` on a Hash, so the bytes
     # are the same. A controller with `render` always takes the first path.
     def render_json(controller, payload, status:, content_type: nil)
+      # The number, not the symbol: Rack >= 3.1 deprecates :unprocessable_entity
+      # (:unprocessable_content there) and Rails 7.1 passes it to Rack as is.
+      status = status_code(status) || status
       if !controller.respond_to?(:render) && controller.respond_to?(:response_body=)
         controller.status = status
         controller.content_type = content_type if content_type
@@ -192,6 +195,8 @@ module Permittable
     def status_code(status)
       return status if status.is_a?(Integer)
 
+      return nil unless status.respond_to?(:to_sym)
+
       symbol = status.to_sym
       STATUS_CODES[symbol] ||
         (defined?(Rack::Utils) && Rack::Utils::SYMBOL_TO_STATUS_CODE[symbol])

data/lib/permittable/generator.rb

@@ -43,7 +43,8 @@ module Permittable
     # lists the column. They ride on the column, set by in_rule, so the scan
     # path hands them to column_line without its own methods changing.
     DraftColumn = Struct.new(:name, :type, :null, :default, :default_function, :enum, :enum_integers, :sensitive,
-                             :unread, :rule, :listed, :assigned, :array, :array_default, keyword_init: true) do
+                             :unread, :rule, :listed, :assigned, :array, :array_default, :precision, :scale,
+                             keyword_init: true) do
       def in_rule(rule, listed: false)
         self.class.new(**to_h, rule: rule, listed: listed)
       end
@@ -556,6 +557,8 @@ module Permittable
                       default_function: column.respond_to?(:default_function) && column.default_function,
                       array: column.respond_to?(:array?) && column.array? == true,
                       array_default: array_default?(column.default),
+                      precision: column.respond_to?(:precision) && column.precision,
+                      scale: column.respond_to?(:scale) && column.scale,
                       sensitive: sensitive_role(model, column.name), assigned: assigned?(model, column),
                       **model_facts(model, column))
     end
@@ -1159,9 +1162,30 @@ module Permittable
       todos << "TODO: #{column.name} #{SCANNED_SENSITIVE.fetch(column.sensitive)}" if column.sensitive
       todos << enum_todo(column) if column.enum_integers
       todos << unread_todo(column) if column.unread
+      todos.concat(hint_todos(column))
+    end
+
+    # Hints about what a contract cannot say for a column, so a reviewer
+    # sees them before the draft is enforced. Comments only.
+    def hint_todos(column)
+      todos = []
+      if column.type == :decimal && column.precision
+        todos << "TODO: decimal(#{column.precision},#{column.scale || 0}): the contract does not bound precision; " \
+                 "a Postgres app may 500 on overflow"
+      end
+      if RAILS_REQUEST_KEYS.include?(column.name.to_s)
+        todos << "TODO: #{column.name} is also a Rails request key — if this contract is rootless (root: false) " \
+                 "the router's value collides with it"
+      end
+      if JSON_TYPES.include?(column.type)
+        todos << "TODO: #{column.name} (#{column.type}): a :json field accepts an object only, not an array"
+      end
       todos
     end
 
+    RAILS_REQUEST_KEYS = %w[controller action format authenticity_token].freeze
+    JSON_TYPES = %i[json jsonb].freeze
+
     SCANNED_SENSITIVE = {
       locking: "is the optimistic-locking column — kept because the permit call lists it: an edit form that " \
                "round-trips it is how Rails detects a stale update; never give it a default:",
@@ -1320,9 +1344,22 @@ module Permittable
       return nil if rules.empty?
 
       bodies = rules.map do |actions, body|
-        "#{signature(root: root, model: model, actions: actions)}\n#{body.map { |line| "  #{line}\n" }.join}end\n"
+        "#{one_line(signature(root: root, model: model, actions: actions))}\n" \
+          "#{body.map { |line| "  #{one_line(line)}\n" }.join}end\n"
       end
       HEADER + bodies.join("\n#{UPDATE_NOTE}")
     end
+
+    # Every drafted line passes through here, the one place text from the
+    # database or the app (a column name in a TODO) meets a comment. A line
+    # break in it would end that comment and leave the rest as live Ruby for
+    # whoever pastes the draft. Ruby's lexer ends a comment at "\n" only (a
+    # lone "\r", "\v", "\f", U+0085, U+2028/9 and NUL stay inside it), but an
+    # editor or terminal shows "\r" as a break too, so it goes as well. A name
+    # inside a quoted literal is already escaped by `inspect`, with no raw
+    # break left.
+    def one_line(line)
+      line.gsub(/\r\n|[\r\n]/, " ")
+    end
   end
 end

data/lib/permittable/open_api.rb

@@ -402,11 +402,10 @@ module Permittable
     end
 
     def operation_for(controller, action)
-      rule = if action == "*"
-               controller.permittable_contracts.reverse_each.find { |r| r[:actions].empty? }
-             else
-               controller.permit_rule_for(action)
-             end
+      # "*" is the catch-all's marker on a plain host; a rule that names "*"
+      # literally is an ordinary action and is found through permit_rule_for.
+      rule = (action == "*" && controller.permittable_contracts.reverse_each.find { |r| r[:actions].empty? }) ||
+             controller.permit_rule_for(action)
       operation = {}
       key = controller_key(controller)
       operation["operationId"] = "#{key.tr('/', '_')}_#{action}" if key && action != "*"
@@ -419,7 +418,7 @@ module Permittable
       # the rule's own declaration is contract data — the app-wide
       # Permittable.mode is runtime configuration the export can't see.
       operation["x-permittable-mode"] = "monitor" if rule[:mode] == :monitor
-      operation["x-permittable-catch-all"] = true if action == "*"
+      operation["x-permittable-catch-all"] = true if action == "*" && rule[:actions].empty?
       # `finalize` is flagged on the rule's object schema too (see
       # JsonSchema.rule), but that sits inside the requestBody, and an
       # operation can end up with no body (every field a path variable) while

data/lib/permittable/rspec.rb

@@ -669,6 +669,10 @@ module Permittable
         "expected #{subject_name} not to #{verb} those params#{action_label}, but it did"
       end
 
+      # The root a scoped filter_parameters entry needs comes from the subject,
+      # which a matcher only learns in matches?. Before any run there is none to
+      # resolve, so a description read then prints through the shallow filter
+      # (RSpec builds a one-liner's name after the run, so it is not affected).
       def description
         label = @expect_accepted ? "accept those params" : "reject those params"
         label += action_label

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.15.1".freeze
+  VERSION = "0.16.0".freeze
 end

data/lib/permittable.rb

@@ -642,8 +642,56 @@ module Permittable
     end
   end
 
+  # Remembers what `skip_before_action :enforce_params_contract` took out of
+  # the callback chain, for Audit. A skip with only:/except:/if:/unless: leaves
+  # the callback in the chain behind conditions Rails keeps private, so the
+  # only public place to read them is the call itself. Prepended to the
+  # controller's singleton class when the gem registers its callback, so it
+  # wins whatever the include order of the callbacks module and this one.
+  # It calls super with the arguments it was given and returns what super
+  # returns; it only looks.
+  module SkipRecorder
+    ruby2_keywords def skip_before_action(*args, &)
+      # A copy: Rails deletes only:/except: from a positional Hash and adds :if to it.
+      options = args.last.is_a?(Hash) ? args.last.dup : {}
+      return super unless args.any? { |name| name.to_s == "enforce_params_contract" }
+
+      # Rails rebuilds the callback of every class already below this one too,
+      # each with its own new object, so each gets the record.
+      targets = [self] + descendants
+      before = targets.map(&:permittable_hook_callback)
+      result = super
+      targets.zip(before) { |target, was| target.permittable_record_skip(was, options) }
+      result
+    end
+
+    def permittable_hook_callback
+      _process_action_callbacks.find { |callback| callback.kind == :before && callback.filter == :enforce_params_contract }
+    end
+
+    # One state per class, replaced rather than changed, so a subclass's skip
+    # never reaches its parent. It holds the callback now in the chain and
+    # every skip that produced it: a skip is carried forward from the state
+    # only when it was made on that very callback, so a callback declared
+    # again afterwards (a new object) starts clean. only:/except: are kept as
+    # Rails compares them, action names as Strings.
+    def permittable_record_skip(before, options)
+      after = permittable_hook_callback
+      return if before.nil? || before.equal?(after)
+
+      held = permittable_skips
+      skips = held && held[:callback].equal?(before) ? held[:skips] : []
+      skip = { only: (Array(options[:only]).to_set(&:to_s) if options[:only]),
+               except: (Array(options[:except]).to_set(&:to_s) if options[:except]),
+               conditional: options.key?(:if) || options.key?(:unless) }.freeze
+      self.permittable_skips = { callback: after, skips: (skips + [skip]).freeze }.freeze
+    end
+  end
+
   included do
     class_attribute :permittable_contracts, instance_accessor: false, default: []
+    # The skips of enforce_params_contract SkipRecorder saw (see Audit).
+    class_attribute :permittable_skips, instance_accessor: false, default: nil
     # Whether the gem itself ever registered its rescue_from / before_action
     # for this class (a subclass inherits the answer). Asking the callback
     # chain instead would bring back a check the app took out with
@@ -1006,9 +1054,11 @@ module Permittable
       result.exponent.abs > [DECIMAL_DIGIT_ALLOWANCE, source.length].max
     end
 
+    # eql?, not ==: 1.0, BigDecimal("1"), Rational(1, 1) and Complex(1, 0) are
+    # == 1, and a JSON `1.0` arrives as a Float, but only the Integer is listed.
     def cast_boolean(value)
-      return [:ok, true] if TRUE_VALUES.include?(value)
-      return [:ok, false] if FALSE_VALUES.include?(value)
+      return [:ok, true] if TRUE_VALUES.any? { |true_value| true_value.eql?(value) }
+      return [:ok, false] if FALSE_VALUES.any? { |false_value| false_value.eql?(value) }
 
       [:error, "invalid_type"]
     end
@@ -1033,6 +1083,7 @@ module Permittable
         date ? [:ok, date] : [:error, "invalid_type"]
       when Date then [:ok, value]
       when String
+        value = value.delete_prefix(BOM) if value.start_with?(BOM)
         # A bare ISO date ("2026-09-05", the common case) carries no zone, T
         # or offset, so it skips every check for one.
         plain = PLAIN_ISO_DATE.match?(value)
@@ -1048,6 +1099,7 @@ module Permittable
         if !plain && (dropped = dropped_tail(value, found))
           return date_at_midnight(*dropped)
         end
+        return [:error, "invalid_type"] if !plain && unread_text?(value, found)
 
         # Built from the components rather than re-running Date.parse, which
         # would parse the same string a second time — and Date.parse is the
@@ -1143,6 +1195,7 @@ module Permittable
       when Time, DateTime then [:ok, value.to_time.getutc]
       when Date then [:ok, Time.utc(value.year, value.month, value.day)]
       when String
+        value = value.delete_prefix(BOM) if value.start_with?(BOM)
         # Same rule as :date — the DATE part must be named in full, or it is
         # taken from today ("10:30" meant today at 10:30). An absent TIME part
         # is fine and means midnight, which is the documented reading of a
@@ -1177,6 +1230,7 @@ module Permittable
 
       dropped = dropped_tail(value, found)
       return dropped if dropped
+      return [:error, "invalid_type"] if unread_text?(value, found)
 
       [:ok, DateTime.parse(value, true, Date::GREGORIAN).to_time.utc]
     rescue ArgumentError, RangeError
@@ -1286,6 +1340,8 @@ module Permittable
     # without it names the same date (and time). Only a String that ends in a
     # signed number or a word is parsed again, so a plain "2026-09-05" is not.
     def dropped_tail(value, found)
+      # "at" joins a date to its time, and Ruby reads it as a zone (or drops it) when none follows.
+      return [:error, "invalid_type"] if /\sat\s*\z/i.match?(value)
       return [:error, "invalid_type"] if !found.key?(:hour) && ISO_DATE_T_START.match?(value)
       return if found.key?(:zone)
 
@@ -1351,17 +1407,87 @@ module Permittable
     def instant_in_zone(date, text)
       zone = Date._parse("00:00 #{text}")
       return [:error, "invalid_type"] unless zone.key?(:zone) && honoured_zone?(zone)
+      # Ruby reads a zone name and drops what follows it ("EST xyz" is EST).
+      return [:error, "invalid_type"] unless zone[:zone].casecmp?(text.split.join(" "))
+      return [:error, "invalid_type"] if unread_text?(date, Date._parse(date))
 
       [:ok, DateTime.parse(date, true, Date::GREGORIAN).to_time.utc - zone[:offset]]
     end
 
+    # Text Date._parse read nothing from, which the parse then leaves out of
+    # the result without a word: "2026-01-01xyz", a second date after the
+    # first ("2026-01-15\n2099-12-31"), "<script>", and any control or
+    # zero-width character (the parser takes it for a space). Found by
+    # leaving each word and number out in turn: if the parse is unchanged,
+    # that part of the String meant nothing to it.
+    #
+    # A part may stay unread only when it says nothing new: the T of an ISO
+    # date-time, an ordinal or era word, "at", a lone letter after a date, an am
+    # or pm the hour already says, or an offset or zone name that repeats the
+    # one read ("EDT -04:00", "+0000 UTC"; "-0400 PST" disagrees, so is
+    # refused). Remarks are set aside: a bracketed name ("(Central Daylight
+    # Time)", "(heure d'été de l'Est)"), an RFC 9557 zone id
+    # ("[Europe/London]", "[u-ca=japanese]": the offset governs) and Go's "m=+0.1".
+    def unread_text?(value, found)
+      return false if ISO_DATE_TIME.match?(value) || PLAIN_ISO_DATE.match?(value) # all of it is read; skips the parses below
+      return true if value.match?(INVISIBLE)
+
+      text = value.gsub(REMARK, " ")
+      # A remark the parser read (a "(Sat)") is part of the parse: look at it too.
+      text = value if text != value && Date._parse(text) != found
+      # "(GMT+02:00)" after "GMT+0200": a remark that repeats the offset read.
+      text = text.gsub(OFFSET_REMARK) do
+        Date._parse("00:00 GMT#{Regexp.last_match(1)}")[:offset] == found[:offset] ? " " : Regexp.last_match(0)
+      end
+      text = text.gsub(%r{[^-+',./:@[:alnum:]\[\]]+}, " ")
+      return true if text.scan(PART).size > MAX_PARTS # each part below costs a parse
+
+      text.scan(PART) do
+        part = Regexp.last_match
+        next if part[0].match?(part.pre_match.match?(/\d\z/) ? GLUED_NOISE : LONE_WORD)
+        next if part[0].casecmp?("at") && found.key?(:hour) && part.post_match.match?(/\d/) # joins a date to its time
+        # "10:30 am", "12 pm" and "22:00 pm" are what the hour already says.
+        next if { "am" => found[:hour].to_i < 12, "pm" => found[:hour].to_i >= 12 }[part[0].downcase]
+        next unless Date._parse("#{part.pre_match} #{part.post_match}") == found # the parse needed this part
+
+        # What it left unread may still repeat the zone read, or label it.
+        zone = Date._parse("00:00 #{part[0]}")[:offset] if found[:offset]
+        next if zone && (zone == found[:offset] || offset_label?(found, part))
+
+        return true
+      end
+      false
+    end
+
+    # "+0800 CST": a zone abbreviation right after the numeric offset read is a
+    # label for it (Go and `date` print one), even where Ruby's table maps it to
+    # another offset. The other order ("CST +08:00") reads the abbreviation, so no.
+    def offset_label?(found, part)
+      found[:zone].match?(/\A[+-]/) && part[0].match?(/\A[[:alpha:]]+\z/) && part.pre_match.rstrip.end_with?(found[:zone])
+    end
+
     def same_time?(rest, found)
       TIME_PARTS.all? { |part| rest[part] == found[part] }
     end
 
     TIME_PARTS = %i[hour min sec sec_fraction].freeze
     GLUED_OFFSET = /\A[+-](?:\d{1,2}|\d{2}[0-5]\d)\z/
-    private_constant :TIME_PARTS, :GLUED_OFFSET
+    ISO_DATE_TIME = /\A\d{4}-?\d\d-?\d\d[Tt ]\d\d:?\d\d(?::?\d\d(?:[.,]\d+)?)?(?:[Zz]| ?[+-]\d\d(?::?\d\d)?)?\z/
+    # One leading U+FEFF is a UTF-8 signature (a CSV or text file saved with one), not text.
+    BOM = "\uFEFF".freeze
+    INVISIBLE = /[\p{Cc}\p{Cf}&&[^\s]]/
+    REMARK_TEXT = /[\p{L}\p{M} .'’,&-]/
+    REMARK = %r{\((?:#{REMARK_TEXT}|\(#{REMARK_TEXT}*\))*\)|(?:\[!?[\w/+=:-]+\])+\z|\sm=[+-]\d+(?:\.\d+)?\z}
+    # No date format in use has more parts than this: the longest read in the
+    # specs and corpora has 8, e.g. "September 5, 2026 at 10:00:00 AM GMT+2".
+    MAX_PARTS = 16
+    PART = /[[:alpha:]]+|[+-]?\d[^[:alpha:]\s]*/
+    GLUED_NOISE = /\A(?:t|st|nd|rd|th)\z/i
+    # No /i: Onigmo then lets [[:alpha:]] match a ligature's folding ("st", "ss", "ff") once it has met non-ASCII text.
+    LONE_WORD = /\A(?:[[:alpha:]]|[Aa][Dd]|[Cc][Ee])\z/
+    OFFSET_REMARK = /\((?:GMT|UTC)([+-]\d{1,2}(?::?\d{2})?)\)/
+    private_constant :TIME_PARTS, :GLUED_OFFSET, :ISO_DATE_TIME, :BOM, :INVISIBLE, :REMARK_TEXT, :REMARK, :MAX_PARTS, :PART,
+                     :GLUED_NOISE, :LONE_WORD, :OFFSET_REMARK
 
     def same_date?(rest, found)
       complete_date?(rest) && rest.values_at(:year, :mon, :mday) == found.values_at(:year, :mon, :mday)
@@ -2466,6 +2592,7 @@ module Permittable
       # order: this check runs before any callback declared after the include,
       # so a locale switch that must cover it is a `prepend_around_action`.
       before_action :enforce_params_contract
+      singleton_class.prepend(SkipRecorder) unless singleton_class < SkipRecorder
       self.permittable_callback_registered = true
     end
 
@@ -2476,7 +2603,7 @@ module Permittable
     # Only the rule's OWN declared mode is read, never Permittable.mode: that
     # is usually set by an initializer, and an app must not stop booting over
     # it. The effective mode can only add a requirement, so an action it makes
-    # monitored without a before_action is left to Audit.inert?, which reports
+    # monitored without a before_action is left to Audit.inert_reason, which reports
     # it as not covered.
     def permittable_ensure_runnable!(rule)
       return unless defined?(::ActionController::Metal) && self < ::ActionController::Metal

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-12 00:00:00.000000000 Z
+date: 2026-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport