permittable 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f13494f2345ced22c261510fd65e89b855b263931a423e6abfb3acb9c3df605
-  data.tar.gz: b88b5cad51b572acabe91453a322869d3167671854f37f8ec27cd80b2454d361
+  metadata.gz: 9eb3f4de06deb2a19c6a24b870e6f4d718350b67d733feb6d3ba423f27b6cdc9
+  data.tar.gz: a1a231373f6d9bab90e1e14ff372c3ab22c163783f3beafb9c4e23e0e46b3d18
 SHA512:
-  metadata.gz: f3255855aee7d875af804e0984e3b1939b4018a3d4e51134e15ea61ad53fbcc549e6ec9464ffcc158d5b0a64a0e140a34806b7e37abd24f1b66fa5fbec88bec1
-  data.tar.gz: 658e22032c03f6413ad6343d20a8d493c07158975fea4223cac3fcda3a3db71c119d17f4744f79e1c53982560019b8690be6b03dad7a1f7e3cfe1ca68672d414
+  metadata.gz: f69d441339746c659b6dc64589f77671f22fc13c701116389bbd916ce533ea80a737387605314679b47363c0de784f805aed75c83d7b835b8857aeac305167d2
+  data.tar.gz: 9c64b6950b2149ce8aed60113c07bff435119c33090db0883a50464e31609fa52ceefe848ae52f0e1a3ea34a312669a7022e771f648f3e20ad12ef96fd4c9023

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 <!-- CHANGELOG.md -->
 
+## 0.8.0 (2026-09-19)
+<!-- title: a no-op sensitive: cascade, an invalid OpenAPI export, and megabyte-scale rejections -->
+
+Thirteen fixes, every one of them the gem doing its job wrongly rather than not at all. `sensitive: true` on a nested block or array was a complete no-op, printing in the clear the very values it promised to redact. Every exported OpenAPI document containing a member route was invalid — the committed golden fixture included — because a templated `{id}` was never declared as a parameter. `:datetime` raised `NameError` in any host that had not loaded ActiveSupport's time extensions, and normalising a `Time` to UTC rewrote the caller's own object. `:decimal` accepted the literal string `"NaN"` where `:float` rejected it. A rejected request instrumented itself once per read, double-counting in every dashboard. And one request could write a megabyte of log line, or spend nine seconds and 9.5 MB rejecting an array its own `length:` bound had already refused.
+
+Minor rather than patch: nothing changes shape and the API is untouched, but three fixes are visible from outside. `:float` and `:decimal` now reject values they used to accept, a malformed `root:` reports `invalid_type` where it reported `missing`, and the `sensitive:` cascade widens redaction app-wide. Read **Upgrading** before deploying.
+
+### Fixed
+- **A wildcard route exported an invalid OpenAPI path.** `OpenAPI.rails_routes` templated the `:id` form of a Rails path parameter but not the `*rest` wildcard, so `get "files/*path"` produced the path `/files/*path` — which is not a valid OpenAPI path template, and makes the whole exported document fail validation. Both forms are now templated: `/files/{path}`, including mixed routes like `/files/:bucket/*path` → `/files/{bucket}/{path}`.
+- **A templated path variable was never declared as a parameter.** OpenAPI 3.1 requires every `{variable}` in a path template to have a matching path parameter, and the exporter emitted none — so **every document containing a member route was invalid**, the committed golden fixture included. Each operation now carries one `{ in: "path", required: true }` parameter per variable in the path it was placed at, typed `string`: a route set does not say what an `:id` is, and the exporter documents what arrives rather than guessing. A new spec asserts the invariant over the whole document, so an operation added later cannot reintroduce it.
+- **A route answering several verbs was documented for only one of them.** `rails_routes` kept `verb.split("|").first`, so the `PATCH|PUT` pair `resources` generates — and any `match via: [:patch, :put]` — exported the PATCH operation and silently dropped PUT. Every verb a route answers now gets its own descriptor.
+- **The error-response schema had drifted from what the server renders.** `ERROR_SCHEMA` is the one hand-written part of the export, and it had fallen behind twice over: a violation on a field with `message:` (or with app I18n copy) carries a third key the schema didn't mention, so clients generating types from it dropped the human-readable copy; and the `code` enumeration never gained `depth`, which a `:json` field's `max_depth:` bound emits. `message` is now documented as an optional property — `required` stays `param` + `code`, since a violation without one keeps the bare shape — and `depth` is listed. A new spec renders a real violation and holds the schema to the envelope, so this half of the "docs cannot drift" claim is now guarded like the request-body half.
+- **Two controllers on one path and verb silently overwrote each other.** A document cannot carry two operations in one slot, and the second claim replaced the first with no indication anything had been lost. The loser now lands in `x-permittable-controllers`, which is where the exporter already puts an operation it cannot place.
+- **Every `:datetime` cast raised `NameError` in a host that had not loaded ActiveSupport's time extensions.** A standalone `Permittable::Contract` — validating a webhook payload or a job argument — got `uninitialized constant ActiveSupport::TimeWithZone` instead of a validated param, because activesupport does not load that class by default and the gem never asked for it. A Rails app gets it via `active_support/time` at boot, which is why the spec suite (`require "active_record"`) masked it, the same shape as the 0.5.1 nested-hash bug. Fixed by requiring `active_support/core_ext/time/calculations`, which loads `TimeWithZone` **and** the `Time` extensions it needs: the class alone is not self-sufficient, and converting a real zoned time calls `Time#sec_fraction`, so requiring only `time_with_zone` would have traded `NameError` for `NoMethodError` on activesupport 8.1. The bare-subprocess spec now casts every scalar type, including a real `TimeWithZone`, in a process with no Rails.
+- **`:float` and `:decimal` accepted numbers the type cannot faithfully hold, including ones a client controls.** `Float("1e400")` is `Infinity` and `Float("1e-400")` is `0.0` — the first overflows, the second loses the entire value — and both were accepted silently, leaving a value no numeric column can store. `Float::INFINITY` and `Float::NAN` objects passed straight through for both types. Worst of the set: **`BigDecimal("NaN")` and `BigDecimal("Infinity")` succeed where `Float()` raises**, so a client could send the literal string `"NaN"` for a `:decimal` price and have it stored — and `:float` rejected exactly those strings, so the two types disagreed, which is what marks the behaviour as accidental rather than designed. Non-finite results are now `invalid_type` for both types.
+  A genuine zero is unaffected however it is spelled — `"0"`, `"0.0"`, `"0.0000"` and `"0e10"` all still cast to `0.0`. Underflow is only visible against the source text (the result is an ordinary `0.0`), so a zero result is rejected only when the string named a nonzero **significand**; the exponent's digits say nothing about the value, which is why `"0e10"` is fine. `:decimal` keeps accepting the large exponents `BigDecimal` genuinely represents (`"1e400"` → `0.1e401`), since it has no exponent limit to overflow.
+- **A `root:` key sent with the wrong shape reported `missing`, which sent clients looking in the wrong place.** `{"user": "bob"}` against a `root: :user` contract answered `{ param: "user", code: "missing" }` — for a key the client had just sent. An absent root and a malformed one are different client mistakes, and now read differently: `missing` when the key really is absent (`{}`, `{"user": null}`, `{"user": ""}` — the gem's own definition of absence, so an empty string still counts), `invalid_type` when it was sent as something other than an object. Both remain **400**, since either way the envelope itself is malformed, so nothing changes at the HTTP level; only the diagnostic gets accurate.
+- **A rejected request instrumented `invalid_parameters.permittable` more than once, double-counting itself in every dashboard.** `permitted_params` is documented as memoized per action, but it only memoized *successes* — on a violation it raised without storing anything, so a second read revalidated from scratch and fired the event again. Any action that reads the params twice hit this, and `permittable_violations` followed by `permitted_params` — the pattern the monitor-mode docs suggest for "would this request fail?" — hit it every time. The memo now remembers the **outcome**: a rejection is stored and re-raised (the same exception object, not an equal-looking new one), so a contract runs, and instruments, exactly once per action per request. `ArgumentError` is deliberately still raised fresh every time and never memoized — a contract that doesn't cover the action is a bug to fix, not a verdict on the request.
+- **One request could write a megabyte of log line, or hand a megabyte of exception message to every error tracker.** The `unknown: :log` warn line joined **every** undeclared key, and the violation summary behind `InvalidParameters#message` (and the monitor-mode warn line) joined **every** violation. A request carrying 50,000 undeclared keys against `unknown: :log` produced a single **1 MB** `logger.warn`; the same request against `unknown: :error` produced a 1 MB exception message. `unknown: :log` is the natural mode for watching what a client really sends during a rollout, so this was on a normal path rather than an exotic corner.
+  Both are **prose, written for a person**: they now list at most ten names, each truncated past 120 characters, and count the rest (`…, and 49990 more`), taking that 1 MB line to 261 bytes. Truncating each name matters as much as capping the count — one 1 MB key name alone produced the same 1 MB line. The **machine-readable channels are untouched and complete** — `InvalidParameters#details` still names every offender, and so does the `invalid_parameters.permittable` instrumentation payload — because nothing should silently drop data a consumer might be reading. The only visible change is the `message` string when there are more than ten violations, or an offender's path is longer than 120 characters — neither of which an ordinary contract reaches.
+  One trade-off worth stating: under `unknown: :log` nothing else records an undeclared key, so beyond the tenth only the count survives. Where every name matters, `unknown: :error` in monitor mode records all of them in `details` and in the instrumentation payload without rejecting the request. The 422 body under `unknown: :error` is still proportional to the number of violations, because `details` is deliberately complete.
+- **An array outside its `length:` bound was still fully examined, so an oversized payload cost far more to reject than to accept.** `length:` recorded its violation and then cast, checked and reported on every element anyway. A payload of 200,000 non-string elements against `array :tags, of: :string, length: 0..10` produced **200,001 violations and a ~9.5 MB error body after ~9.2 seconds of CPU** — for a request already refused by its first check, and against the very bound a developer declares to prevent exactly that. `length:` is now a bound rather than a report: an array outside it returns immediately, so the same payload costs **one violation, ~40 bytes and ~57 ms** of contract work (the rest of the wall time is the `HashWithIndifferentAccess` conversion of the payload, which happens before any field is examined). A consequence worth knowing: `validate:` and `transform:` are no longer handed an array the contract has already rejected, matching the rule `transform:` already followed for element violations. Arrays within their bounds, and arrays with no `length:` declared, behave exactly as before — note in particular that there is still **no default cap**, so an array with no `length:` remains unbounded and every element of it is cast and checked. `benchmark/oversized_array.rb` re-runs the measurement.
+  An authored `default:`/`example:` on an array is now also checked against that array's own `length:` at class load, instead of loading and handing the action an out-of-bounds default.
+- **`sensitive: true` on a nested block or array was a complete no-op, and logged the values it promised to redact.** Rails' parameter filtering walks into hashes and arrays itself and asks a proc filter about the **leaf values only**, handing it the leaf's own key and never the path that led there — so registering only the container's name redacted nothing: the filter descended and asked about `"card_number"`, which the container's name does not match. A contract declaring `optional :payment, sensitive: true do required :card_number, :string end` printed the card number in the clear. `sensitive:` now **cascades** to every field inside a nested or array container, at any depth, and a spec proves it through `ActiveSupport::ParameterFilter` rather than only asserting on the registry. The cascade is resolved onto the field data at class load, so every reader of a contract agrees with the redaction: the exported JSON Schema marks a cascaded child `writeOnly`, and the RSpec matcher's `.sensitive` chain passes for it.
+- **`permittable:generate` read commented-out code as if it ran.** A controller keeping a `# params.require(:admin).permit(:superuser)` line for reference had `:admin` drafted as the contract's `root:` and `:superuser` drafted as a permitted field — a wrong suggestion, and a security-flavoured one, from a line that does not execute. The same applied to `=begin`/`=end` blocks and to trailing comments on live lines. Comments are now removed before scanning, using `Ripper` (stdlib, no new dependency) rather than a regexp, because `#` is only sometimes a comment: a permit call inside `#{'#{...}'}` interpolation **is** live code and is still read, and string **content** is deliberately kept because `permit("name")` is a supported spelling whose keys live in string tokens. A file `Ripper` cannot lex falls back to the raw source, so a syntactically odd controller scans exactly as it did before rather than not at all.
+
+### Added
+- **`sensitive: false` opts a sub-field out of an inherited cascade.** Matching is a case-insensitive **substring** match, so cascading a generic name like `:id` or `:name` would redact every parameter in the app that happens to contain it — occasionally a worse outcome than the leak it prevents. An explicit `sensitive: false` on a field (or on a container, for its whole subtree) keeps it readable. Only `false` opts out — `sensitive: nil` reads as "not stated" and still inherits.
+
+### Changed
+- **A `Time` passed to a `:datetime` field is no longer converted in place.** Normalising to UTC went through `value.to_time.utc`; `Time#to_time` returns `self` and `Time#utc` converts its **receiver**, so validating a request quietly rewrote the caller's own object — after `call!(at: t)`, `t` had become UTC. The cast now returns a new instance and leaves the argument alone. An `ActiveSupport::TimeWithZone` is likewise no longer handed back by way of the UTC instance it caches internally.
+- **`length:` is now checked before `in:` and `format:`, so a value the bound already excludes never pays for the expensive checks.** `length:` is an O(1) read of a String's size; `format:` runs a regexp over the whole value and `validate:` runs arbitrary app code. Checking the cheap bound *last* meant a 5 MB string against `length: 1..80` was scanned in full by the field's regexp before being rejected on its length — 121 ms where 38 ms would do, and a lever rather than mere waste when the app's regexp has poor worst-case behaviour. The documented order is now `normalize: → cast → length: → in: → format: → validate:`, with the first failure reported. The only observable change is which code a value violating **both** reports — `length` now, rather than `inclusion`/`format` — and that is the more useful answer anyway, since a client cannot act on "wrong format" for a value that is also far too long. A spec pins that the field's regexp is not consulted at all for an over-long value.
+
+### Upgrading
+- **A contract that already declares `sensitive: true` on a nested block or array will redact more than it did before.** That is the point of the fix, but the widening is app-wide and worth a look before deploying: every cascaded child's name is registered as a case-insensitive **substring** filter, so a child called `id`, `name`, `type`, `status` or `zip` starts redacting `user_id`, `company_name`, `content_type` and `gzip` in **every** controller's logs, not only in the contract that declared it. Run `grep -n "sensitive: true" app/controllers` and add `sensitive: false` to any child whose name is too generic to filter globally.
+
 ## 0.7.0 (2026-09-16)
 <!-- title: sensitive: redaction, uncorruptible defaults, and stricter class load -->
 

data/README.md

@@ -270,7 +270,7 @@ end
 
 # Arrays — of: for scalars, a block for hashes. Element failures carry their index: items[1].sku
 array :tag_names,  of: :string, length: 0..10
-array :line_items, required: true do
+array :line_items, required: true, length: 1..50 do
   required :sku,      :string
   required :quantity, :integer, in: 1..99
 end
@@ -281,6 +281,8 @@ optional :metadata, :json, max_depth: 3, length: 0..32
 
 Arrays are **optional unless `required: true`**, and `length:` on an array constrains the element **count**.
 
+`length:` is a **bound, not a report**: an array outside it is rejected without its elements being examined at all. A 200,000-element payload against `length: 0..10` is refused by its first check, so it costs one violation and a 40-byte body instead of 200,001 violations and several megabytes — milliseconds of contract work instead of seconds. There is **no default cap**: an array with no `length:` is unbounded, and every element of it is cast and checked however many arrive. Declare `length:` on every array you accept.
+
 ### Field options
 
 Which options are legal depends on the field kind — anything else raises at class load.
@@ -289,7 +291,7 @@ Which options are legal depends on the field kind — anything else raises at cl
 |---|:---:|:---:|:---:|---|
 | `in:` | ✅ | — | — | Allowed values: a `Range` (bounds-checked with `cover?`) or an `Array` |
 | `format:` | ✅¹ | — | — | Regexp the value must match |
-| `length:` | ✅¹ | ✅ | — | `Range` or `Integer`. Character count on strings, **element count** on arrays |
+| `length:` | ✅¹ | ✅ | — | `Range` or `Integer`. Character count on strings, **element count** on arrays, where it short-circuits — see [the field DSL](#the-field-dsl) |
 | `normalize:` | ✅¹ | — | — | `:squish`, `:strip`, `:downcase`, `:upcase`, `:email`, or a Proc. Runs **first** — before the absence rule, so a value that normalizes to `""` is absent |
 | `default:` | ✅ | ✅ | — | Value used when the field is absent. Validated against the field's own contract at class load, then stored normalized and frozen (each request gets its own copy) |
 | `validate:` | ✅ | ✅ | — | Callable. Falsy fails as `"invalid"`; a returned `Symbol` becomes the violation code |
@@ -306,6 +308,16 @@ Which options are legal depends on the field kind — anything else raises at cl
 
 ¹ `format:`, `length:`, and `normalize:` reason about characters and are **only valid on `:string` fields**. On any other type they would silently apply to an already-cast value, so declaring them raises at class load.
 
+**Checks run in a fixed order**, and the first failure is the one reported:
+
+```
+normalize:  →  cast  →  length:  →  in:  →  format:  →  validate:
+```
+
+`length:` comes before `in:` and `format:` on purpose. It is an O(1) read of a string's size, while `format:` runs a regexp over the whole value and `validate:` runs your own code — so a value the length bound already excludes never pays for the expensive checks. A 5 MB string against `length: 1..80` is rejected on its length without the regexp ever seeing it, which matters most when the regexp is one with poor worst-case behaviour.
+
+The visible consequence: a value that violates *both* its length and its format reports `length`. That is the more useful answer anyway — a client can't act on "wrong format" for a value that is also far too long.
+
 `validate:` is the escape hatch for anything the built-ins don't cover:
 
 ```ruby
@@ -329,6 +341,8 @@ Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`.
 
 **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.
 
+**Numbers must be finite.** `Float("1e400")` is `Infinity` and `Float("1e-400")` is `0.0` — neither represents what was sent, and neither is a value a numeric column can store, so both are `invalid_type`. A genuine zero is unaffected however it is spelled (`"0"`, `"0.0"`, `"0e10"`). `:decimal` has no exponent limit, so `"1e400"` is fine there — but `BigDecimal("NaN")` and `BigDecimal("Infinity")` *succeed* where `Float()` raises, so those literal strings are rejected explicitly.
+
 Two more behaviours worth committing to memory:
 
 - **Type confusion is a violation, not a 500.** A request of `?age[]=1` against a scalar `:integer` field yields `invalid_type`. Arrays, hashes, and nested `ActionController::Parameters` can never satisfy a scalar type, so the classic "`NoMethodError` on `[]`" crash is impossible.
@@ -414,8 +428,8 @@ Every failure raises `Permittable::InvalidParameters`, carrying `details` (an ar
 
 | Code | Raised when |
 |---|---|
-| `missing` | A required field is absent, or the `root:` key is missing (this one is a **400**) |
-| `invalid_type` | The value cannot be faithfully cast to the declared type |
+| `missing` | A required field is absent, or the `root:` key is absent (that one is a **400**) |
+| `invalid_type` | The value cannot be faithfully cast to the declared type — including a `root:` key the client *did* send with the wrong shape (`{"user": "bob"}`), which is also a **400** |
 | `inclusion` | The value is outside `in:` |
 | `format` | The value doesn't match `format:` |
 | `length` | A string's length, or an array's element count, is outside `length:` |
@@ -425,7 +439,9 @@ Every failure raises `Permittable::InvalidParameters`, carrying `details` (an ar
 
 Paths are fully qualified: `user.address.zip`, `line_items[1].sku`.
 
-**Status codes.** A missing root key renders **400** — the request is malformed; the envelope you asked for isn't there. Field-level violations render **422** — well-formed, semantically wrong.
+**`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.
+
+**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.
 
 **Custom rendering.** If your controller defines `render_error`, the envelope delegates to it as `render_error(message:, code:, status:, errors:)` — the `errors:` key is passed only when details exist, so hosts documenting a three-keyword contract keep working. Otherwise the inline JSON shape is rendered. Either way, `render_invalid_parameters` is a normal method you can override. For full control over the body (RFC 9457, a different envelope), `error.details` gives you the structured violations to build from.
 
@@ -484,9 +500,11 @@ Resolution order per violation: the field's own `message:` (String, or the Hash
 | Mode | Behaviour |
 |---|---|
 | `:ignore` (default) | Silently dropped, exactly like strong parameters |
-| `:log` | Dropped, with a `logger.warn` naming the full paths |
+| `:log` | Dropped, with a `logger.warn` naming the full paths — at most ten of them, then a count, so one request cannot write a megabyte of log |
 | `:error` | Each undeclared key becomes an `unknown` violation |
 
+Under `:log` that bound is the whole record: nothing else names an undeclared key, so beyond the tenth only the count survives. Where you need every name — auditing what a client really sends during a rollout — use `unknown: :error` in monitor mode, which records all of them in `details` and in the instrumentation payload without rejecting the request.
+
 Rails merges its own keys into `params`: `controller`, `action`, and `format` from the router, plus `authenticity_token`, `_method`, `utf8`, and `commit` from an ordinary form POST. All seven are exempt at the top level, so `unknown: :error` flags what the *client* got wrong rather than what the framework added. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there — and a standalone `Contract` exempts nothing at all, having neither a router nor a form.
 
 The exemption covers the *check* only. Monitor mode still hands back the form keys in its raw pass-through, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `_method` itself; only the router's three are dropped there.
@@ -555,6 +573,22 @@ Mark a field `sensitive: true` and its name is registered with `Permittable.filt
 optional :ssn, :string, sensitive: true
 ```
 
+**On a nested block or an array, `sensitive:` cascades to everything inside it:**
+
+```ruby
+optional :payment, sensitive: true do
+  required :card_number, :string        # redacted
+  optional :cvv,         :string        # redacted
+  optional :id,          :string, sensitive: false   # NOT redacted — see below
+end
+```
+
+It has to. Rails' parameter filtering walks into hashes and arrays itself and asks a proc filter about the **leaf values only**, handing it the leaf's own key and never the path that led there. So registering `payment` alone redacts nothing inside it: the filter descends and asks about `card_number`, which the container's name does not match.
+
+A sub-field opts out with an explicit `sensitive: false`. That exists because matching is a case-insensitive **substring** match, so cascading a generic name like `:id` or `:name` would redact every parameter in the app that happens to contain it — occasionally a worse outcome than the leak it prevents. Only `false` opts out; `sensitive: nil` reads as "not stated" and still inherits.
+
+The cascade is resolved onto the field when the contract loads, so everything that reads a contract agrees: the value is redacted from logs, the exported schema marks the child `writeOnly`, and `permit_param("payment.card_number").sensitive` passes.
+
 Two mechanisms, because neither covers the ground alone.
 
 A **single proc appended once at boot, consulting a live registry at filter time**, is what reaches consumers that snapshot `config.filter_parameters` at boot — ActiveRecord's `filter_attributes` copy, lograge-style initializers — so a field registered when a controller loads later (lazy loading in development) is still redacted there. The initializer runs before `active_record.set_filter_attributes`, so values are redacted from both request logs and `#inspect`.
@@ -567,7 +601,7 @@ Matching mirrors Rails' own symbol-filter semantics: case-insensitive substring
 
 ### Instrumentation
 
-Every violation emits an `ActiveSupport::Notifications` event, so rejected requests can be dashboarded and alerted on:
+Every violation emits an `ActiveSupport::Notifications` event, so rejected requests can be dashboarded and alerted on — **exactly once per action per request**, however many times the action reads the params (`permitted_params` memoizes the outcome, rejections included):
 
 ```ruby
 ActiveSupport::Notifications.subscribe("invalid_parameters.permittable") do |*, payload|
@@ -646,7 +680,7 @@ permit_params :create, :update, root: :user, model: User, mode: :monitor do
   optional :age, :integer
   optional :status, :string # database default: "active"
   optional :password_confirmation, :string, virtual: true # TODO: not a database column — confirm the type
-  array :tag_names, of: :string # TODO: confirm the element type
+  array :tag_names, of: :string # TODO: confirm the element type, and declare length: — an array without one is unbounded
 end
 ```
 
@@ -654,6 +688,7 @@ The generator's one rule is **draft, don't guess** — everything it cannot know
 
 - Drafts come out in **monitor mode**, so pasting one changes nothing until you flip it.
 - A permitted key that isn't a column becomes `virtual: true` with a TODO; a column type with no scalar equivalent (`json`, `binary`) becomes a TODO comment; a permit argument the conservative parser can't read (`*dynamic_keys`) is kept verbatim in a TODO instead of dropped.
+- **Comments are not code.** A commented-out `params.require(:admin).permit(:superuser)` kept for reference is skipped, so it can't contribute a root or a field to the draft. The source is tokenised with `Ripper` for this, because `#` is only sometimes a comment — a permit call inside `#{'#{...}'}` interpolation is live code and is still read, and quoted keys like `permit("name")` still work.
 - A database default is noted in a comment but **not** copied into `default:` — a contract default is injected on every request that omits the field, which would overwrite columns on partial updates. The database already handles creation.
 - `key: [:a, :b]` in a permit call drafts as a nested block, with a TODO noting it may be an array of hashes.
 
@@ -736,7 +771,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 Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern` — including one 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`; 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 land in `x-permittable-controllers` instead of being dropped. 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 Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern` — including one 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`; 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 — land in `x-permittable-controllers` instead of being dropped. A templated path segment is declared as a path `parameter` of type `string`, because the route set doesn't say what an `:id` is and the exporter won't invent it. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
 
 Output is deterministic (fixed key order, declaration-order properties), so the generated file can be committed and reviewed as a diff — a contract change shows up in the same PR as its documentation change.
 
@@ -772,7 +807,7 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 
 | Method | Purpose |
 |---|---|
-| `permitted_params(action = action_name)` | The cast, validated, defaulted `HashWithIndifferentAccess`. Memoized per action. Raises `InvalidParameters` on violation (in [monitor mode](#monitor-mode-roll-out-without-rejecting), returns the raw pass-through instead), or `ArgumentError` when no contract covers the action |
+| `permitted_params(action = action_name)` | The cast, validated, defaulted `HashWithIndifferentAccess`. Raises `InvalidParameters` on violation (in [monitor mode](#monitor-mode-roll-out-without-rejecting), returns the raw pass-through instead), or `ArgumentError` when no contract covers the action. **Memoized per action, outcome included** — a rejection is re-raised rather than revalidated, so a contract runs (and instruments) exactly once per action per request |
 | `permittable_violations(action = action_name)` | The violation details recorded by validating `action` — `[]` when clean. Triggers the same memoized validation; under enforce it swallows the raise, making "would this request fail?" a one-liner |
 | `enforce_params_contract` | The `before_action` entry point. Validates rules declared `enforce: true` and all [monitor-mode](#monitor-mode-roll-out-without-rejecting) rules. Public, so hosts can `skip_before_action` it |
 | `render_invalid_parameters(error)` | The `rescue_from` target. Renders via the host's `render_error` when defined, the inline envelope otherwise |

data/lib/permittable/generator.rb

@@ -1,3 +1,5 @@
+require "ripper"
+
 module Permittable
   # Drafts a permit_params contract from what the app already knows: the
   # model's columns (types, NOT NULL, database defaults) and, when the
@@ -54,14 +56,38 @@ module Permittable
     ARRAY_ARG  = /\A(\w+):\s*\[\s*\]\z/m
     NESTED_ARG = /\A(\w+):\s*\[([^\[\]]*)\]\z/m
 
+    # Comment tokens. Ripper (stdlib) is used rather than a regexp because `#`
+    # is only a comment sometimes — it also appears inside string literals and
+    # `#{}` interpolation, and a permit call inside interpolation IS live code.
+    # String CONTENT is deliberately kept: `permit("name")` is a supported
+    # spelling, and its keys live in string tokens.
+    COMMENT_TOKENS = %i[on_comment on_embdoc on_embdoc_beg on_embdoc_end].freeze
+
     module_function
 
+    # `source` with its comments removed. A controller keeping a commented-out
+    # `params.require(:admin).permit(:superuser)` for reference had :admin
+    # drafted as its root and :superuser as a permitted field — a wrong
+    # suggestion, and a security-flavoured one, from a line that does not run.
+    #
+    # Anything Ripper cannot lex falls back to the source unchanged, so a
+    # syntactically odd file scans exactly as it did before rather than not at
+    # all.
+    def executable_source(source)
+      tokens = Ripper.lex(source)
+      return source if tokens.nil? || tokens.empty?
+
+      tokens.reject { |token| COMMENT_TOKENS.include?(token[1]) }.map { |token| token[2] }.join
+    rescue StandardError
+      source
+    end
+
     # Merge every permit call found in `source` into one Scan. The first
     # `.require(:root)` seen wins, matching how a controller normally sticks
     # to one envelope across actions.
     def scan(source)
       result = Scan.new(root: nil, scalars: [], arrays: [], nested: {}, unparsed: [], calls: 0)
-      (source || "").scan(PERMIT_CALL) do |root, args|
+      executable_source(source.to_s).scan(PERMIT_CALL) do |root, args|
         result.calls += 1
         result.root ||= root&.to_sym
         split_args(args).each { |arg| classify_arg(result, arg) }
@@ -192,7 +218,9 @@ module Permittable
 
     def scanned_lines(scan, columns)
       lines = scan.scalars.map { |name| scanned_scalar_line(name, columns) }
-      lines += scan.arrays.map { |name| "array :#{name}, of: :string # TODO: confirm the element type" }
+      lines += scan.arrays.map do |name|
+        "array :#{name}, of: :string # TODO: confirm the element type, and declare length: — an array without one is unbounded"
+      end
       scan.nested.each { |name, keys| lines += nested_lines(name, keys) }
       lines + scan.unparsed.map { |arg| "# TODO: could not parse from the permit call: #{arg}" }
     end

data/lib/permittable/open_api.rb

@@ -11,8 +11,9 @@ module Permittable
   # Everything the exporter cannot know is left visible rather than guessed:
   # actions covered only by a catch-all rule on a host without
   # `action_methods` appear under the "*" key with `x-permittable-catch-all`,
-  # and operations with no matching route land in `x-permittable-controllers`
-  # instead of being dropped silently.
+  # and operations with no matching route — or whose path+verb slot another
+  # controller already claimed, which a document cannot represent twice —
+  # land in `x-permittable-controllers` instead of being dropped silently.
   module OpenAPI
     module_function
 
@@ -39,8 +40,15 @@ module Permittable
                   },
                   "code" => {
                     "type" => "string",
-                    "description" => "missing / invalid_type / inclusion / format / length / unknown / invalid, " \
-                                     "or a contract-specific symbol"
+                    "description" => "missing / invalid_type / inclusion / format / length / depth / unknown / " \
+                                     "invalid, or a contract-specific symbol"
+                  },
+                  # Present only when the field declares `message:` or the app
+                  # has I18n copy for the code; a violation without one keeps
+                  # the bare { param:, code: } shape, so this is not required.
+                  "message" => {
+                    "type" => "string",
+                    "description" => "Human-readable copy for this violation, when the contract or I18n supplies it"
                   }
                 },
                 "required" => %w[param code]
@@ -176,15 +184,43 @@ module Permittable
     def place_operations(controller, operations, routes, paths, unrouted)
       key = controller_key(controller) || controller.inspect
       operations.each do |action, operation|
-        matched = routes_for(routes, key, action)
-        if matched.empty?
+        # A path+verb pair carries exactly one operation, so a slot another
+        # controller already claimed is not written over: the loser stays
+        # visible under x-permittable-controllers, where an operation with no
+        # route at all lands, rather than disappearing from the document.
+        free = routes_for(routes, key, action).reject { |route| paths.dig(route[:path], verb_of(route)) }
+        if free.empty?
           (unrouted[key] ||= {})[action] = operation
         else
-          matched.each { |route| (paths[route[:path]] ||= {})[route[:verb].to_s.downcase] = operation }
+          free.each { |route| (paths[route[:path]] ||= {})[verb_of(route)] = with_path_parameters(operation, route[:path]) }
         end
       end
     end
 
+    def verb_of(route)
+      route[:verb].to_s.downcase
+    end
+
+    # OpenAPI 3.1 requires every variable in a path template to be declared as
+    # a path parameter — a document templating {id} without declaring it is
+    # invalid, which every member route produced. The route set does not say
+    # what an :id is and the exporter does not guess: a path segment arrives as
+    # a string, so that is what it is documented as.
+    def with_path_parameters(operation, path)
+      variables = path.scan(/\{(\w+)\}/).flatten
+      return operation if variables.empty?
+
+      parameters = variables.map do |name|
+        { "name" => name, "in" => "path", "required" => true, "schema" => { "type" => "string" } }
+      end
+      # Inserted ahead of requestBody, where a reader of the document expects
+      # it; emission stays deterministic either way.
+      operation.each_with_object({}) do |(key, value), out|
+        out["parameters"] = parameters if key == "requestBody"
+        out[key] = value
+      end
+    end
+
     def routes_for(routes, controller_key, action)
       return [] if routes.nil? || action == "*"
 
@@ -194,16 +230,23 @@ module Permittable
     # { controller:, action:, verb:, path: } descriptors from a Rails
     # application's route set. Duck-typed against Journey routes (each one
     # responds to requirements / verb / path.spec) so it stays unit-testable
-    # without Rails; Rails path params (:id) become OpenAPI templates ({id}).
+    # without Rails; Rails path params become OpenAPI templates — both the
+    # `:id` form and the `*rest` wildcard, which is a real route shape
+    # (`get "files/*path"`) and is not a valid OpenAPI template left as-is.
     def rails_routes(app)
-      app.routes.routes.filter_map do |route|
+      app.routes.routes.flat_map do |route|
         requirements = route.requirements
         verb = route.verb.to_s
-        next if requirements[:controller].nil? || requirements[:action].nil? || verb.empty?
+        next [] if requirements[:controller].nil? || requirements[:action].nil? || verb.empty?
 
-        path = route.path.spec.to_s.sub("(.:format)", "").gsub(/:(\w+)/) { "{#{Regexp.last_match(1)}}" }
-        { controller: requirements[:controller], action: requirements[:action],
-          verb: verb.split("|").first.downcase, path: path }
+        path = route.path.spec.to_s.sub("(.:format)", "").gsub(/[:*](\w+)/) { "{#{Regexp.last_match(1)}}" }
+        # One route can answer several verbs (`match via: [:patch, :put]`, and
+        # the PATCH|PUT pair resources generates); documenting only the first
+        # dropped the others from the export entirely.
+        verb.split("|").map do |single|
+          { controller: requirements[:controller], action: requirements[:action],
+            verb: single.downcase, path: path }
+        end
       end
     end
 

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.7.0".freeze
+  VERSION = "0.8.0".freeze
 end

data/lib/permittable.rb

@@ -7,6 +7,18 @@ require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/object/deep_dup" # authored default:/example: values are copied before freezing
 require "active_support/core_ext/string/inflections"
 require "active_support/core_ext/string/filters"
+# cast_datetime names ActiveSupport::TimeWithZone, which activesupport does not
+# load by default. A Rails app has it via active_support/time at boot; a
+# standalone host (a Contract validating a webhook payload or a job argument)
+# has nothing that loads it, and every :datetime cast raised NameError there.
+#
+# The Time core extensions come with it, and are not optional: TimeWithZone is
+# present but not self-sufficient. Converting one goes through
+# TimeZone#utc_to_local, which calls Time#sec_fraction — defined in
+# core_ext/time/calculations, which time_with_zone.rb does not itself require.
+# Without this line a real TimeWithZone raises NoMethodError in a bare host on
+# activesupport 8.1, having merely traded one crash for another.
+require "active_support/core_ext/time/calculations"
 require "bigdecimal"
 require "date"
 require "time"
@@ -139,6 +151,13 @@ require "permittable/filter_parameter_registry"
 # the value and expects in-place mutation, and never calls the proc at all
 # for a Hash — so a name in config.filter_parameters is what covers an
 # :integer field or a sensitive nested block.
+# Permittable::Railtie appends to `config.filter_parameters`. On a nested or
+# array field it CASCADES to every field inside, because Rails' filtering
+# asks about the leaf key it is looking at rather than the path to it; a
+# sub-field opts out with `sensitive: false`, since matching is a substring
+# match and a generic cascaded name would redact half the app's logs. The
+# cascade is resolved onto the field data at class load — see
+# ContractBuilder#cascade_sensitive.
 #
 # OUTPUT RESHAPING — the safe replacement for params-mutating before_actions.
 # Two layers, both operating on the validated COPY (the request's `params` is
@@ -188,6 +207,15 @@ module Permittable
   # rather than leaving a bare ROUTING_KEYS to read like an oversight.
   UNCHECKED_TOP_LEVEL_KEYS = (ROUTING_KEYS + FORM_KEYS).freeze
   MONITOR_DROPPED_KEYS = ROUTING_KEYS
+  # A log line and an exception message are PROSE, written for a person. They
+  # list at most this many names and count the rest, so one request cannot
+  # write a megabyte of them. The machine-readable channels — a violation's
+  # `details` and the instrumentation payload — stay complete; only the
+  # sentence is bounded.
+  PROSE_LIST_LIMIT = 10
+  # ...and each name it does list is truncated. Capping the COUNT alone still
+  # let ONE 1 MB key name write the 1 MB log line the cap exists to prevent.
+  PROSE_ITEM_LIMIT = 120
 
   # The single proc Permittable::Railtie appends to config.filter_parameters.
   # Declared with an optional third parameter so its own arity is -3 and Rails
@@ -375,10 +403,22 @@ module Permittable
       check_scalar_rules(field, value)
     end
 
+    # `length:` first, deliberately. It is an O(1) read of a String's size,
+    # while `format:` runs a regexp over the whole value and `validate:` runs
+    # arbitrary app code — so checking the cheap bound last meant a value the
+    # bound already excluded still paid for the expensive ones. A 5 MB string
+    # against `length: 1..80` scanned all 5 MB with the field's regexp before
+    # being rejected on its length, and an app regexp with poor worst-case
+    # behaviour turns that from waste into a lever.
+    #
+    # The only observable change is which code a value violating BOTH reports:
+    # `length` now, rather than `inclusion`/`format`. Reporting the structural
+    # failure first is the better answer anyway — a client cannot act on
+    # "wrong format" for a value that is also far too long.
     def check_scalar_rules(field, value)
+      return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
       return [:error, "inclusion"] if field[:in] && !included_in?(field[:in], value)
       return [:error, "format"] if field[:format] && !field[:format].match?(value)
-      return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
 
       check_custom(field[:validate], value)
     end
@@ -457,23 +497,54 @@ module Permittable
 
     def cast_float(value)
       case value
-      when Numeric then [:ok, value.to_f]
-      when String then [:ok, Float(value)]
+      when Numeric then finite_float(value.to_f)
+      when String then finite_float(Float(value), source: value)
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
       [:error, "invalid_type"]
     end
 
+    # A Float that is not finite does not represent what was sent. "1e400"
+    # overflows to Infinity and "1e-400" underflows to zero — both silently,
+    # and both leaving a value no column can faithfully store.
+    #
+    # Underflow is only visible against the source text, since the result is
+    # an ordinary 0.0: a zero result is rejected when the string it came from
+    # named a nonzero SIGNIFICAND. Only the significand, because "0e10" is a
+    # genuine zero whose exponent digits say nothing about the value — as are
+    # "0", "0.0" and "0.0000".
+    def finite_float(result, source: nil)
+      return [:error, "invalid_type"] unless result.finite?
+      return [:error, "invalid_type"] if result.zero? && nonzero_significand?(source)
+
+      [:ok, result]
+    end
+
+    def nonzero_significand?(source)
+      return false unless source
+
+      source.split(/[eE]/, 2).first.match?(/[1-9]/)
+    end
+
     def cast_decimal(value)
       case value
-      when Numeric, String then [:ok, BigDecimal(value.to_s)]
+      when Numeric, String then finite_decimal(BigDecimal(value.to_s))
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
       [:error, "invalid_type"]
     end
 
+    # BigDecimal has no exponent limit, so a :decimal cannot overflow — but
+    # BigDecimal("NaN") and BigDecimal("Infinity") SUCCEED where Float()
+    # raises, so a client could send the literal string "NaN" for a price and
+    # have it stored. Nothing else in the gem disagreed with itself this
+    # loudly: :float rejected those strings and :decimal did not.
+    def finite_decimal(result)
+      result.finite? ? [:ok, result] : [:error, "invalid_type"]
+    end
+
     def cast_boolean(value)
       return [:ok, true] if TRUE_VALUES.include?(value)
       return [:ok, false] if FALSE_VALUES.include?(value)
@@ -517,7 +588,12 @@ module Permittable
     def cast_datetime(value)
       case value
       # DateTime is listed here, ahead of Date, because it subclasses Date.
-      when ActiveSupport::TimeWithZone, Time, DateTime then [:ok, value.to_time.utc]
+      # `getutc` rather than `utc`: `Time#utc` converts the RECEIVER, and
+      # `Time#to_time` returns self, so `value.to_time.utc` silently rewrote
+      # the caller's own object. A TimeWithZone's `getutc` hands back the
+      # instance it caches internally, so that one is duped.
+      when ActiveSupport::TimeWithZone then [:ok, value.getutc.dup]
+      when Time, DateTime then [:ok, value.to_time.getutc]
       when Date then [:ok, Time.utc(value.year, value.month, value.day)]
       when String
         # Same rule as :date — the DATE part must be named in full, or it is
@@ -618,7 +694,7 @@ module Permittable
       if block
         raise ArgumentError, "#{LABEL}: array :#{name} takes of: OR a block, not both" if opts.key?(:of)
 
-        field[:fields] = nested_fields!(name, &block)
+        field[:fields] = cascade_sensitive(nested_fields!(name, &block), field[:sensitive])
         field.delete(:of)
       else
         field[:of] = scalar_type!(name, opts[:of] || :string)
@@ -642,6 +718,7 @@ module Permittable
         assert_opts!(name, opts, NESTED_OPTS)
         field = { name: name, kind: :nested, required: required,
                   fields: nested_fields!(name, &block), **opts }
+        field[:fields] = cascade_sensitive(field[:fields], field[:sensitive])
         validate_message!(field)
       elsif type&.to_sym == JSON_TYPE
         assert_opts!(name, opts, JSON_OPTS)
@@ -693,6 +770,43 @@ module Permittable
       fields
     end
 
+    # `sensitive: true` on a nested or array field CASCADES to every field
+    # inside it, and the cascade is resolved HERE, at class load, so that
+    # `field[:sensitive]` stays the single source of truth every reader
+    # consults: the filter registry, the exported schema's `writeOnly`, and
+    # the RSpec matcher's `.sensitive` chain. Resolving it privately inside
+    # the registry walk would have redacted a cascaded child at runtime
+    # while the schema and the matcher went on calling it public.
+    #
+    # It has to cascade: ActiveSupport::ParameterFilter recurses into Hash
+    # and Array values itself and consults proc filters only for the LEAVES,
+    # handing each one the leaf's own key and never the path that led there.
+    # So registering only `payment` is asked about `card_number`, which it
+    # does not match, and redacts nothing inside the container.
+    #
+    # A sub-field opts out with an explicit `sensitive: false`, because
+    # matching is a case-insensitive SUBSTRING match and cascading a generic
+    # name (:id, :name) would redact every parameter app-wide that contains
+    # it. Only `false` opts out; `sensitive: nil` reads as "not stated" and
+    # still inherits.
+    def cascade_sensitive(fields, inherited)
+      updated = fields.map { |field| cascade_field_sensitive(field, inherited) }
+      updated.zip(fields).all? { |new_field, old| new_field.equal?(old) } ? fields : updated.freeze
+    end
+
+    def cascade_field_sensitive(field, inherited)
+      declared = field[:sensitive]
+      effective = declared.nil? ? inherited : declared
+      children = field[:fields] ? cascade_sensitive(field[:fields], effective) : nil
+      unchanged = (effective ? declared == true : declared == false || !field.key?(:sensitive)) &&
+                  (children.nil? || children.equal?(field[:fields]))
+      return field if unchanged
+
+      updated = field.merge(sensitive: effective)
+      updated[:fields] = children if children
+      updated.freeze
+    end
+
     def validate_scalar_opts!(field)
       name = field[:name]
       if field[:required] && field.key?(:default)
@@ -848,6 +962,9 @@ module Permittable
       value = field[opt]
       return if authored_nil!(field, opt)
       raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
+      if field[:length] && !Coercion.length_ok?(field[:length], value.length)
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} violates its own contract (length)"
+      end
 
       validate_array_elements!(field, opt, value) if field[:of]
       validate_array_element_hashes!(field, opt, value) if field[:fields]
@@ -1091,6 +1208,21 @@ module Permittable
       end
     end
 
+    # `sensitive: true` on a nested or array field CASCADES to everything
+    # inside it, because Rails' parameter filtering matches the leaf key it is
+    # currently looking at — never the path that led there. Registering only
+    # the container's own name therefore redacted nothing it promised: the
+    # filter is handed ("payment", {...}), a Hash is not a String so nothing
+    # is replaced, and it then recurses and asks about "card_number", which
+    # was never registered.
+    #
+    # A sub-field opts out with an explicit `sensitive: false`. That escape
+    # hatch exists because matching is a case-insensitive SUBSTRING match, so
+    # cascading a generic name (:id, :name) would redact every parameter
+    # app-wide that happens to contain it — occasionally a worse outcome than
+    # the leak it prevents.
+    # The cascade is already resolved on the field data (see
+    # ContractBuilder#cascade_sensitive), so this only has to read it.
     def register_sensitive_params(fields)
       fields.each do |field|
         Permittable.register_sensitive_parameter(field[:name]) if field[:sensitive]
@@ -1103,18 +1235,31 @@ module Permittable
   # defaulted values for the given action (default: the current action).
   # Absent optional fields are omitted. Raises InvalidParameters on
   # violation; raises ArgumentError when no contract covers the action
-  # (that is a programmer error, not a client error). Memoized per action.
+  # (that is a programmer error, not a client error).
+  #
+  # Memoized per action, and the memo remembers the OUTCOME rather than only
+  # a success: a rejection is stored and re-raised. Validation is therefore
+  # observable exactly once per action per request, which the
+  # "invalid_parameters.permittable" event depends on — memoizing only
+  # successes meant a rejected request that was read twice (an action calling
+  # permittable_violations before permitted_params, say) instrumented twice
+  # and double-counted itself in every dashboard.
   def permitted_params(action = nil)
     action = (action || permittable_action_name).to_s
     raise ArgumentError, "#{LABEL}: no action given and action_name is not set" if action.empty?
 
     @permittable_validated ||= {}
-    return @permittable_validated[action] if @permittable_validated.key?(action)
-
-    rule = self.class.permit_rule_for(action)
-    raise ArgumentError, "#{LABEL}: no params contract declared covering ##{action}" unless rule
+    outcome = @permittable_validated.fetch(action) do
+      @permittable_validated[action] = permittable_outcome_for(action)
+    end
+    # `cause: nil` because a memoized rejection is raised from wherever the
+    # action happens to read the params next — possibly inside a `rescue` of
+    # something unrelated, whose exception Ruby would otherwise adopt as this
+    # error's cause for good. The object and its original backtrace (the
+    # first raise site, where the violation was found) are preserved.
+    raise outcome, cause: nil if outcome.is_a?(InvalidParameters)
 
-    @permittable_validated[action] = validate_params_contract!(rule, action)
+    outcome
   end
 
   # before_action entry point (public so hosts can `skip_before_action
@@ -1163,6 +1308,19 @@ module Permittable
 
   private
 
+  # The value permitted_params memoizes: the validated params, or the
+  # InvalidParameters that rejected them. ArgumentError is deliberately NOT
+  # memoized — a contract that does not cover the action is a bug to fix, not
+  # a verdict on this request, so it raises fresh on every call.
+  def permittable_outcome_for(action)
+    rule = self.class.permit_rule_for(action)
+    raise ArgumentError, "#{LABEL}: no params contract declared covering ##{action}" unless rule
+
+    validate_params_contract!(rule, action)
+  rescue InvalidParameters => e
+    e
+  end
+
   def validate_params_contract!(rule, action)
     violations = []
     source = permittable_root_hash(rule, violations)
@@ -1219,7 +1377,25 @@ module Permittable
   end
 
   def permittable_violation_summary(violations)
-    violations.map { |v| v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})" }.join(", ")
+    permittable_prose_list(violations) do |v|
+      v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})"
+    end
+  end
+
+  # See PROSE_LIST_LIMIT. `unknown: :error` on a request carrying 50,000
+  # undeclared keys used to produce a 50,000-item sentence — a megabyte of
+  # log line, or of exception message handed to every error tracker.
+  # The block formats one item, and is called only for the items actually
+  # shown — the rest are counted, never rendered.
+  def permittable_prose_list(items)
+    shown = items.first(PROSE_LIST_LIMIT).map { |item| permittable_prose_item(yield(item)) }.join(", ")
+    return shown if items.length <= PROSE_LIST_LIMIT
+
+    "#{shown}, and #{items.length - PROSE_LIST_LIMIT} more"
+  end
+
+  def permittable_prose_item(item)
+    item.length <= PROSE_ITEM_LIMIT ? item : "#{item[0, PROSE_ITEM_LIMIT - 3]}..."
   end
 
   # One violation detail entry. A field's `message:` (String, or Hash keyed
@@ -1261,12 +1437,21 @@ module Permittable
     raw = permittable_plain_params
     return raw unless rule[:root]
 
-    value = raw[rule[:root].to_s]
+    key = rule[:root].to_s
+    value = raw[key]
     return value if value.is_a?(Hash)
 
+    # A root that is absent and a root sent with the wrong shape
+    # ({"user": "bob"}) are different client mistakes, and telling a client
+    # that the key it just sent is "missing" sends it looking in the wrong
+    # place. Absence is the gem's own definition of it, so `{"user": ""}`
+    # still reads as missing. Either way the envelope is malformed, so both
+    # remain a 400.
+    #
     # No field declares the root, so message resolution can only come from
     # I18n ({} has no :message).
-    violations << permittable_violation({}, rule[:root].to_s, "missing")
+    code = permittable_absent?(value, raw, key) ? "missing" : "invalid_type"
+    violations << permittable_violation({}, key, code)
     nil
   end
 
@@ -1341,8 +1526,18 @@ module Permittable
   end
 
   def permittable_check_array(field, value, path:, unknown:, violations:)
+    # `length:` is a BOUND, not a report. An array outside it is rejected
+    # whatever its contents, so checking those contents can only add work and
+    # noise: a 200k-element payload against `length: 0..10` used to cast every
+    # element, collect 200k more violations, and answer with a multi-megabyte
+    # 422 — for a request already refused by its first check. Stopping here
+    # keeps the cost of an oversized array proportional to rejecting it.
+    if field[:length] && !Coercion.length_ok?(field[:length], value.length)
+      violations << permittable_violation(field, path, "length")
+      return nil
+    end
+
     before = violations.length
-    violations << permittable_violation(field, path, "length") if field[:length] && !Coercion.length_ok?(field[:length], value.length)
     out = value.each_with_index.map do |element, index|
       permittable_check_element(field, element, "#{path}[#{index}]", unknown: unknown, violations: violations)
     end
@@ -1419,8 +1614,8 @@ module Permittable
     if unknown == :error
       extra.each { |key| violations << permittable_violation({}, permittable_path(path, key), "unknown") }
     elsif respond_to?(:logger) && logger
-      logger.warn("#{LABEL}: unknown parameter(s) ignored by the ##{permittable_action_name} contract: " \
-                  "#{extra.map { |key| permittable_path(path, key) }.join(', ')}")
+      listed = permittable_prose_list(extra) { |key| permittable_path(path, key) }
+      logger.warn("#{LABEL}: unknown parameter(s) ignored by the ##{permittable_action_name} contract: #{listed}")
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport