permittable 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a884eb52cc555157fddf46346de7995e12c1da2920e8488cfae7d7f383123824
-  data.tar.gz: dae0d105fb44f1a0dac9cc07b33fd583e3e5fc5952f5511bb46126a56ae229ad
+  metadata.gz: 7e1419e11eb73f0b94274aa8f6a868e81913f64a754bfecde44885e83a825942
+  data.tar.gz: 74a084502a3328e692fd522c719d16e8242fb2a12a9602e3da76c3e6076be426
 SHA512:
-  metadata.gz: 63a2d785b2067d7d581d13775da06c180db170597acaad22a9c3de0622a7592f79a7ccf8febcb6199a53954ac03bfa606e781110927e02834145c313dcb6b366
-  data.tar.gz: baca9f1599f2637e68ab407bb81861d342fc79b43c6a836aa6e165e47acf539c6f3625fcdc07cfe4c5dd9c9e1b1e69de75df481dffc7d95126e0ae3f52ac383d
+  metadata.gz: de34efb031486908abdf6b26293108f83505dac300ce9a1977b88439c5677d058950a567bd79ead0aefe6f03605d7d312eede2215844393855beb098c99d2819
+  data.tar.gz: 95420ccea0d5842aaea3877ed3343ab444c7bc9a505efdad76b1b0b23fae1ab7bb636ba367cb9e4ad69151ae35e9a2491c05d6746d6cd31b87bb41cb5744c1be

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 <!-- CHANGELOG.md -->
 
+## 0.15.0 (2026-11-12)
+<!-- title: zone names and hours that Date._parse drops honoured or refused, an export that matches what the server stores, an audit that stops reporting rules that cannot run, matchers that redact what they print, and a column guard that knows aliases and store accessors -->
+
+Five changes to what a string, an export, an audit, a matcher or a model is held to, and one to what a model may declare. A `:date` or `:datetime` string that carries a zone name, an hour or an offset that `Date._parse` reads only in some positions is read as the instant it names, or refused, where the part was dropped (#174). The export refuses a non-finite `BigDecimal` and a sub-nanosecond `Time` in an authored `:json` value, publishes a `:date` member as `YYYY-MM-DD` (#175), and lists Rails' form keys in a rootless `unknown: :error` JSON body (#178). `permittable:audit` reports a bare `ActionController::Metal` rule that cannot run as uncovered, and lists the controllers a route names that nothing has loaded (#176). The matchers read a Symbol value as the String a request carries and redact sensitive values from failure messages (#177). A model's `alias_attribute` and `store_accessor` fields are checked against the column that backs them, where 0.14.0 refused them at class load (#178).
+
+Minor rather than patch: each entry can make a request, a boot, a spec, an audit or an export that passes today fail, or read differently. Before upgrading, read the entries that match what you use. A request can now be refused: an ISO date followed by `T` and no hour (`"2026-09-05T10"`, `"2026-09-05T1030"`, `"2026-09-05T10Z"`), any unknown word after a complete date (`"2026-09-05 foo"`), an initial-led zone name Ruby does not know (`"W. Europe"`), an hour or offset the parser misplaces (`"2026-09-05 10 EST"`, `"2026-09-05 10 -05:00"`), an offset after the year in a form other than git's or `ctime`'s, and a zone name with an offset after the year (`"Sat Sep 5 10:00:00 2026 UTC+0000"`), all as `invalid_type`, and a `:date` string with a zone name that does not name midnight UTC (`"2026-09-05 EST"`) (#174). A boot can now fail: an authored `default:` or `example:` on a `:json` field that holds a non-finite `BigDecimal` or a `Time` or `DateTime` finer than a nanosecond, at any depth (#175), and an `in:`, `default:` or `example:` written as a time-carrying `:date` string that is not exactly midnight UTC (#174). Nothing that loaded on 0.14.0 newly fails because of #178: on 0.14.0 an alias or store accessor field was refused at class load as a missing column, so its checks reject nothing that loaded. An action can now receive something different: a `:datetime` such as `"2026-09-05 EST"` is `05:00Z` where it was `00:00Z`, and `"Sat Sep 5 10:00:00 2026 EST"` or `"... -0500"` is `15:00Z` where it was `10:00Z` (#174), and `nil` for an omitted nullable `:json` field with `default: ""` (#175). An export now reads differently: a `:date` `in:` member written as a String prints as `YYYY-MM-DD` (#175), and a rootless `unknown: :error` JSON body lists `authenticity_token`, `_method`, `utf8`, `commit` and `button` as free optional properties (#178). An audit can now fail: a gate on uncovered actions fails for a bare Metal controller rule that cannot run, which was covered, and for a routed controller that the audit now loads, whose file now runs and whose load error now raises (#176). And a spec can fail where it passed: a controller matcher given a Symbol value that asserted a rejection now sees an acceptance, a `:json` field's Symbol values come back as Strings in a matcher's returned hash (#177), and a `returning` message that showed a sensitive value now shows the placeholder (#177).
+
+### Added
+- **`permittable:audit` lists the controllers a route names that nothing has loaded.** The audit collected controllers from `ActionController::Metal.descendants`, which holds only loaded classes, so `Rails::HealthController` behind `GET /up` had no row. `Audit.rails_controllers(routes)` now adds every controller a route names, constantized; a missing constant, or one that is not an `ActionController::Metal` class, is skipped. A controller from a gem is still ignored by default, and its row shows the ignore reason. Running the audit loads those controllers, so a controller with an import-time side effect runs it, and an error raised inside a controller's file is now raised, not rescued as a `NameError`. (#176)
+- **The matchers print a hash with its sensitive values redacted, and say where it differs.** A `returning` mismatch printed the whole returned hash with `inspect`, and a `returning` expectation as written, so a CI log carried `sensitive:` values and the values in `config.filter_parameters`. Both now print the registry's placeholder, by the names from `sensitive:` (matched by substring, like Rails) and, under a booted Rails app, `config.filter_parameters`; under a `root:` contract a scoped filter such as `"payment.number"` applies, and an `ActionController::Parameters` is unwrapped first. When redaction hides a `returning` mismatch the message adds `differs at: <path>`, naming only paths. Matching still compares the real values, and a pass or fail is unchanged. (#177)
+
+### Changed
+- **A `:date` or `:datetime` string reads or refuses the zone, offset or hour `Date._parse` drops.** `Date._parse` reports a zone only beside a time of day, so a zone name after a bare date, an hour after an ISO `T` and an offset after the year (git and `ctime` format) were dropped or misplaced, and the value came from the date alone. A zone name Ruby knows is applied (`"2026-09-05 EST"` is `05:00Z` as a `:datetime`, not `00:00Z`; `"Sat Sep 5 10:00:00 2026 EST"` and `"... -0500"` are `15:00Z`, not `10:00Z`; `"20260905 10 EST"` is `15:00Z`), and an offset after the year of git's and `ctime`'s format is read the same way. These are refused as `invalid_type`: an ISO `T` with no hour, any unknown word after a complete date, an initial-led zone name Ruby does not know (`"W. Europe"`, `"S. Africa Standard Time"`), an hour or offset the parser misplaces, and an offset after the year in any other form. Dotted eras (`A.D.`, `B.C.`) are skipped like `AD` and `BC`, and a single letter is never a zone. A `:date` string that carries a time or zone is still accepted only at exactly midnight UTC, so a `:date` zone name that moves the instant, `EST` included, is now refused, and the same rule fails an `in:`, `default:` or `example:` member at class load. The value is a plain `Date` built from its year, month and day. Date-only strings, `Date`, `Time`, `DateTime`, `TimeWithZone` and a zone name that names midnight UTC are unchanged. Still read as before: `"2026-09-05 10 A.D."`, `"2026-09-05 10 A."` and `"2026-09-05 GMT+5"` drop the hour or offset. (#174)
+- **An authored `:json` value that the export cannot carry fails at class load, and a `:date` member is published as a date.** The check from #163 covered only `Float`. A `default:` or `example:` for a `:json` field that holds a non-finite `BigDecimal` (`NaN`, `Infinity`, `-Infinity`) or a `Time` or `DateTime` finer than a nanosecond, at any depth, raises `ArgumentError` naming the field and the path (`a.b[1].c`), with the hint to round a `Time` with `.round(9)`; 0.14.0 loaded the class and exported the `BigDecimal` as a String and the `Time` as a different instant. A `:date` `in:` member written as a String is exported as `YYYY-MM-DD`, so `in: ["Sep 5, 2026", Date.new(2026, 9, 6)]` is `["2026-09-05", "2026-09-06"]`, where the first value failed the field's own `format: date`; a member past year 9999 is published in a spelling the server reads back as the same `Date`. A `:datetime` String member is still published as written. The runtime cast of a request is unchanged. (#175)
+- **A blank default on a nullable `:json` field reads as `nil`.** `optional :prefs, :json, nullable: true, default: ""` failed at class load with "must be a Hash", while a request that sends `""` for the field reads as `nil`. It now loads with `nil` as its default, and `with_default("")` reads as `nil` in the matcher. A non-nullable `:json` field given `""` still raises. (#175)
+- **A Symbol value in a controller matcher payload is read as the String a request carries.** The matcher stringified Symbol keys but passed a Symbol value through, so `accept_params(status: :active)` against `in: %w[active]` failed with `invalid_type` for a request the app accepts. A `:json` field's Symbol values come back as Strings in the returned hash. A standalone `Contract` still gets the payload as given, and a Symbol there is still `invalid_type`. A bare `ActionDispatch` module, one defined without `ActionDispatch::Request`, no longer makes a matcher raise for a missing normalizer. (#177)
+- **A bare `ActionController::Metal` rule that cannot run is audited as uncovered.** `Audit.entries` marked an action covered whenever a rule was declared. An action whose `before_action` the gem never registered, because `AbstractController::Callbacks` was missing when `permit_params` ran, and whose effective mode (the rule's own `mode:` or `Permittable.mode`) is `enforce` or `monitor`, is now uncovered, with the note "contract cannot run: controller lacks AbstractController::Callbacks (no before_action)". Including the module after `permit_params` does not make it covered. The class-load check in `permit_params` is unchanged and still reads only the rule's own `mode:`, so such a controller still loads, and the README says so. (#176)
+- **The exported JSON body of a rootless `unknown: :error` contract lists Rails' form keys.** The runtime exempts `authenticity_token`, `_method`, `utf8`, `commit` and `button` at the top of a rootless contract, but the body schema set `additionalProperties: false` without them, so a body the server accepts failed validation against the export. They are now free, optional properties, and a name the contract declares keeps its own schema. A `root:` rule, a multipart body, `JsonSchema.rule` and `Contract#json_schema` are unchanged. A renamed CSRF token and `format` are not listed, as for #165. (#178)
+- **`alias_attribute` and `store_accessor` fields are checked against the column behind them.** The column guard looked a field up by its own name, so an alias or a store key failed at class load as a missing column although assignment accepts it. An alias resolves to its target through any chain, so an alias of an enum, or an enum declared on the alias name, goes through the enum contract, and under `Permittable.check_column_types` its type is compared with the target's. A `store_accessor` is accepted when its store column exists and has no type to compare; it is accepted only under the name its writer takes (`settings_theme` with `prefix: true`, not the bare key), and a subclass finds an accessor a parent declared. An error for a missing alias target or store column now names the target or the store, with its migration. (#178)
+
 ## 0.14.0 (2026-11-09)
 <!-- title: a :file field type with a multipart export, date strings read as the instant they name, Metal controllers that enforce whatever the include order, and matchers that see what a request sees -->
 

data/README.md

@@ -538,7 +538,7 @@ Validation is **lazy by default**: it runs on the first `permitted_params` call,
 
 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.
 
-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` or `mode: :monitor` rule raises `ArgumentError` at class load when `AbstractController::Callbacks` is missing. So does an `enforce: true` rule that is not in monitor mode 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.
+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.
 
 ### Declaring a contract
 
@@ -696,11 +696,11 @@ Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`.
 | `: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` |
 | `: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"`), and an ISO date followed by `T` and no time (`"2026-09-05T"`) |
+| `: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.
+**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 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"`, `"12:00 2026-09-05 -05:00"`) is refused rather than read as some other instant.
 
 **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.
 
@@ -928,7 +928,7 @@ The setting is app-wide, not per-contract, because the error format of an API is
 
 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` (or whatever `config.action_controller.request_forgery_protection_token` renames it to), `_method`, `utf8`, and the submit button's name from an ordinary form POST: `commit` from `f.submit` / `submit_tag`, `button` from `f.button` / `button_tag` (sent as `button=` when the `<button>` has no value). All eight are exempt at the top level. So is the click point of an image submit: `image_submit_tag("save.png")` renders an `<input type="image">` with no name, and a browser submitting through it posts where it was clicked as `x=12&y=7` (or `save.x=12&save.y=7` when the tag is named `"save"`, which Rack keeps as those literal keys). `x` and `y` are ordinary names a contract may really be sent, so they are exempt only as a pair, both present and both plain digits (never negative or fractional); a lone `x`, or a pair that is not digits, is flagged as usual, and a contract that *declares* `x` or `y` has it validated as usual and sees the other flagged unless it declares that too. A bracketed image-submit name is not covered (`name: "user[save]"` is parsed by Rack as `{"user"=>{"save"=>{".x"=>..}}}`, nested rather than top level), just as only the top-level `commit` and `button` are. So are the route's **path parameters** (`PATCH /users/1` merges `id`, which the exported OpenAPI documents as a path parameter rather than a body field); a contract that *declares* `id` has it validated as usual, since the URL really carried it, and the export then documents that field as the path parameter's schema (`required :id, :integer, in: 1..1000` becomes `{"type":"integer","minimum":1,"maximum":1000}`) and leaves it out of the request body, `required` list included, so a body without `id` is valid. Only a rootless contract does this, and only for a name the route templates; a `root:` contract's `id` is a body field and stays one, and so does an `array`, nested or `:json` field, since no URL segment can be one. Under `unknown: :error` the body schema forbids undeclared keys, but every name the route templates stays in it as a property that takes any value and is never required, declared or not: `PATCH /users/1` with `{"id":1,"name":"x"}` is accepted, because the path parameter is exempt and the URL's `id` overwrites the body's. A name the route fills from `defaults:` (`post "w", to: "widgets#create", defaults: { kind: "x" }`, on the route, its `scope` or the `mount` it is reached through) is no body field either, since the router overwrites the body's value: the export leaves it out of the body, `required` list included, and under `unknown: :error` keeps it as that same free property, but declares no path parameter for it, because no URL carries it. `rails_routes` names such keys in each descriptor's `defaults:`, apart from `controller`, `action` and `format`. **ParamsWrapper's copy of a JSON body** under the controller's wrapper key (`user` for `UsersController`) goes further: when Rails made that copy, a rootless contract does not see the key at all, because the client never sent it. So an undeclared wrapper key is not flagged, and a scalar or array field that happens to share the wrapper's name (`optional :feedback, :string` on `FeedbackController`) is simply absent, rather than failing as `invalid_type` against Rails' copy of the whole body. The one exception is a rootless contract that declares the wrapper key as a hash container — a nested block (`required :user do ... end`) or `:json`. That contract is reading the copy on purpose, like a `root:` spelled as a field, so the copy is kept and validated as that field. A client that sends `user` itself is checked like any other key: validated if declared, flagged if not. That holds whether the wrapper name is configured as a String or as a Symbol (`wrap_parameters :user`). Either way `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, a form, nor a request.
+Rails merges its own keys into `params`: `controller`, `action`, and `format` from the router, plus `authenticity_token` (or whatever `config.action_controller.request_forgery_protection_token` renames it to), `_method`, `utf8`, and the submit button's name from an ordinary form POST: `commit` from `f.submit` / `submit_tag`, `button` from `f.button` / `button_tag` (sent as `button=` when the `<button>` has no value). All eight are exempt at the top level. So is the click point of an image submit: `image_submit_tag("save.png")` renders an `<input type="image">` with no name, and a browser submitting through it posts where it was clicked as `x=12&y=7` (or `save.x=12&save.y=7` when the tag is named `"save"`, which Rack keeps as those literal keys). `x` and `y` are ordinary names a contract may really be sent, so they are exempt only as a pair, both present and both plain digits (never negative or fractional); a lone `x`, or a pair that is not digits, is flagged as usual, and a contract that *declares* `x` or `y` has it validated as usual and sees the other flagged unless it declares that too. A bracketed image-submit name is not covered (`name: "user[save]"` is parsed by Rack as `{"user"=>{"save"=>{".x"=>..}}}`, nested rather than top level), just as only the top-level `commit` and `button` are. So are the route's **path parameters** (`PATCH /users/1` merges `id`, which the exported OpenAPI documents as a path parameter rather than a body field); a contract that *declares* `id` has it validated as usual, since the URL really carried it, and the export then documents that field as the path parameter's schema (`required :id, :integer, in: 1..1000` becomes `{"type":"integer","minimum":1,"maximum":1000}`) and leaves it out of the request body, `required` list included, so a body without `id` is valid. Only a rootless contract does this, and only for a name the route templates; a `root:` contract's `id` is a body field and stays one, and so does an `array`, nested or `:json` field, since no URL segment can be one. Under `unknown: :error` the body schema forbids undeclared keys, but the form keys above (`authenticity_token`, `_method`, `utf8`, `commit`, `button`) stay in a rootless contract's JSON body as free, optional properties, as in its multipart body, because the runtime accepts them (a `root:` contract's body is unchanged: they sit outside the root; a name the contract declares keeps its own schema; `Contract#json_schema` describes the contract alone and lists none), and every name the route templates stays in it as a property that takes any value and is never required, declared or not: `PATCH /users/1` with `{"id":1,"name":"x"}` is accepted, because the path parameter is exempt and the URL's `id` overwrites the body's. A name the route fills from `defaults:` (`post "w", to: "widgets#create", defaults: { kind: "x" }`, on the route, its `scope` or the `mount` it is reached through) is no body field either, since the router overwrites the body's value: the export leaves it out of the body, `required` list included, and under `unknown: :error` keeps it as that same free property, but declares no path parameter for it, because no URL carries it. `rails_routes` names such keys in each descriptor's `defaults:`, apart from `controller`, `action` and `format`. **ParamsWrapper's copy of a JSON body** under the controller's wrapper key (`user` for `UsersController`) goes further: when Rails made that copy, a rootless contract does not see the key at all, because the client never sent it. So an undeclared wrapper key is not flagged, and a scalar or array field that happens to share the wrapper's name (`optional :feedback, :string` on `FeedbackController`) is simply absent, rather than failing as `invalid_type` against Rails' copy of the whole body. The one exception is a rootless contract that declares the wrapper key as a hash container — a nested block (`required :user do ... end`) or `:json`. That contract is reading the copy on purpose, like a `root:` spelled as a field, so the copy is kept and validated as that field. A client that sends `user` itself is checked like any other key: validated if declared, flagged if not. That holds whether the wrapper name is configured as a String or as a Symbol (`wrap_parameters :user`). Either way `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, a form, nor a request.
 
 All of this changes what is *checked* only. Monitor mode still hands back the form keys, the path parameters and the wrapper's copy in its raw pass-through, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `params[:id]` or `_method` itself; only the router's three are dropped there.
 
@@ -1041,6 +1041,8 @@ The error carries a ready-to-paste migration command, typed from your own field
 
 A field naming a column the model lists in `ignored_columns` raises too, but says so (remove it from `ignored_columns`, or declare it `virtual: true`) rather than suggesting a migration.
 
+An attribute assignment accepts without a column of its own is checked against the column behind it. A field named for an `alias_attribute` (`alias_attribute :title, :name`) is checked as its target `name`, type included. A field named for a `store_accessor` (`store_accessor :settings, :theme`) passes when the store's column (`settings`) exists, since the value lives inside that column; it has no type of its own to compare, and a missing store column is reported by the store's name rather than as a missing `theme` column. The name is the one assignment takes, so with `prefix: true` it is `settings_theme` and the bare `theme` is still reported missing. An accessor a parent model declared counts too. Rails does not record which prefix built which accessor, so two stores that share a key under different prefixes are ambiguous: the guard picks the store by the longest matching key, and may then check the other store's column. An alias whose target column is missing is reported as `'title' is an alias of 'name'`, with the migration for `name`. Only a name no column, alias or store accessor backs still needs `virtual: true`.
+
 #### Checking types too (opt-in)
 
 A dropped column fails the deploy; a **retyped** one doesn't, unless you ask:
@@ -1267,7 +1269,7 @@ No Rails required for the core: `Permittable::Generator.draft(model: User)`, `.f
 
 A controller declaring `permit_params :create` looks adopted. If it also answers `PATCH`, that action is validating **nothing** — and until now nothing in the gem said so. [`permittable:generate`](#generating-draft-contracts-permittablegenerate) only notices controllers with no contract at all, and the [OpenAPI export](#exporting-openapi-docs-that-cannot-drift) documents what exists rather than what is missing.
 
-The audit crosses the contract registry with the **route set**, so a half-covered controller is as visible as an uncovered one. It reads every controller a route can reach: `ActionController::Base` and `::API` subclasses, and bare `ActionController::Metal` ones such as a lean webhook endpoint. The export and the generator read the same list.
+The audit crosses the contract registry with the **route set**, so a half-covered controller is as visible as an uncovered one. It reads every controller a route can reach: `ActionController::Base` and `::API` subclasses, and bare `ActionController::Metal` ones such as a lean webhook endpoint. It also loads any autoloaded controller a route names (`Rails::HealthController` behind `/up`, which nothing has loaded yet), since the route's own controller is part of the app; a route whose controller constant does not exist is skipped, not raised on. A controller from a gem is still [ignored by default](#ignoring-controllers-and-actions). The export and the generator read the same list of loaded controllers; the audit also loads any autoloaded controller a route names.
 
 ```sh
 bin/rails permittable:audit             # the table plus a summary
@@ -1428,7 +1430,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); a standalone `Contract` gets the payload as given.
+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.
 
 ### Standalone contracts (no controller)
 
@@ -1545,7 +1547,7 @@ A `format:` regexp that does not translate to ECMA-262 is looser in the same way
 | `:date` / `:datetime` | `string` + `format: date` / `date-time` |
 | `:file` | `string` + `contentMediaType: application/octet-stream` (the 3.1 spelling; `format: binary` is 3.0's). An operation whose contract has a `:file` field gets a `multipart/form-data` request body instead of `application/json` |
 | `:decimal` | `type: ["string", "number"]` + `format: decimal` (string is the precision-safe encoding) |
-| `in:` list / numeric Range | `enum` of the cast members (a `:date`/`:datetime` member written as a String is published as written) / `minimum` + `maximum` (exclusive ends honoured). An `in:` object that only answers `include?` is flagged `x-permittable-custom-validation` |
+| `in:` list / numeric Range | `enum` of the cast members (a `:datetime` member written as a String is published as written; a `:date` member, however written, as `YYYY-MM-DD`) / `minimum` + `maximum` (exclusive ends honoured). An `in:` object that only answers `include?` is flagged `x-permittable-custom-validation` |
 | `length:` | `minLength`/`maxLength` on strings, `minItems`/`maxItems` on arrays |
 | `format:` | `pattern`, valid under the `u` flag Ajv compiles with: `\A`/`\z` become `^`/`$`, `\s` and `.` are spelled out as the classes they are in Ruby (ECMA-262's `\s` also matches NBSP and U+2028; its `.` also stops at `\r`), and redundant escapes like `\-` and `\#` are written bare |
 | `default:` / `desc:` / `example:` | `default` / `description` / `examples` |

data/lib/permittable/audit.rb

@@ -48,11 +48,13 @@ module Permittable
     # 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?. `route` identifies the route the
+    # 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
     # 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.
-    Entry = Struct.new(:controller, :action, :verb, :path, :rule, :missing_action, :route, :ignored,
+    Entry = Struct.new(:controller, :action, :verb, :path, :rule, :missing_action, :route, :ignored, :inert,
                        keyword_init: true) do
       def covered?
         !rule.nil?
@@ -66,6 +68,10 @@ module Permittable
         !ignored.nil?
       end
 
+      def inert?
+        inert == true
+      end
+
       # The mode this action would actually run in, rule-level declaration
       # first and the app-wide default behind it.
       def mode
@@ -111,12 +117,33 @@ module Permittable
       outside = :outside_root if outside_root?(controller, root)
       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)
         Entry.new(controller: key, action: action, verb: route[:verb], path: route[:path],
-                  rule: rule_for(controller, action), missing_action: missing[action],
-                  route: route[:route], ignored: configured_ignore(key, action, ignore) || outside)
+                  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) &&
+        !(controller.respond_to?(:permittable_callback_registered) && controller.permittable_callback_registered)
+    end
+
     # 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
@@ -151,11 +178,32 @@ module Permittable
     # themselves are Metal descendants too; they are the framework's abstract
     # bases, which no route names, and the old lists never held them.
     # Anonymous classes cannot be routed to, so only named ones are kept.
-    def rails_controllers
+    #
+    # `descendants` only holds classes that have been loaded, and a framework
+    # controller is autoloaded: Rails::HealthController behind `/up` is a
+    # registered constant until something touches it, so it had no row. Pass
+    # the route descriptors and every controller a route names is loaded and
+    # added — it is the route's own controller. A constant that does not exist,
+    # or is not a controller class, is left out rather than raised on.
+    def rails_controllers(routes = [])
       return [] unless defined?(::ActionController::Metal)
 
       frameworks = %w[ActionController::Base ActionController::API]
-      ::ActionController::Metal.descendants.uniq.select { |controller| controller.name && !frameworks.include?(controller.name) }
+      loaded = ::ActionController::Metal.descendants + routed_controllers(routes)
+      loaded.uniq.select { |controller| controller.name && !frameworks.include?(controller.name) }
+    end
+
+    # The controller classes the routes' `controller:` keys name, constantized
+    # (loading an autoloaded one). `safe_constantize` answers nil for a missing
+    # constant and raises on anything else — an error inside the controller's
+    # own file is the app's to see, so nothing more is rescued here. A key that
+    # names no constant, or one that is not an ActionController::Metal class,
+    # yields nothing.
+    def routed_controllers(routes)
+      routes.map { |route| route[:controller].to_s }.reject(&:empty?).uniq.filter_map do |key|
+        found = ActiveSupport::Inflector.safe_constantize("#{ActiveSupport::Inflector.camelize(key)}Controller")
+        found if found.is_a?(Class) && found < ::ActionController::Metal
+      end
     end
 
     # The root a controller's source must be inside to be audited:
@@ -434,7 +482,16 @@ module Permittable
     end
 
     def uncovered_note(entry)
-      not_found_note(entry) || ("ACCEPTS A BODY" if entry.body?)
+      not_found_note(entry) || inert_note(entry) || ("ACCEPTS A BODY" if entry.body?)
+    end
+
+    # Says why a declared contract is not counted, and keeps the body warning
+    # a gate reader needs.
+    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(" — ")
     end
 
     # The one wording for a route Rails would 404, covered or not.

data/lib/permittable/authored_values.rb

@@ -143,29 +143,41 @@ module Permittable
     end
 
     # An authored hash is exported as a schema `default`/`example`, and JSON
-    # has no NaN or Infinity: JSON.generate raises on them when the document
-    # is written, long after the class loaded. A request cannot carry one
-    # (JSON has none; a form sends Strings), so only the authored value is
-    # held to it, here, and not permittable_check_json for every request.
+    # has no NaN or Infinity: JSON.generate raises on a Float's when the
+    # document is written, long after the class loaded, and a BigDecimal's was
+    # exported as the String "NaN". Nor does the export keep a Time finer than
+    # a nanosecond: it prints nine digits, a different instant (a :datetime
+    # field's own default is refused for the same reason). A request cannot
+    # carry any of these (JSON has none; a form sends Strings), so only the
+    # authored value is held to it, here, and not permittable_check_json for
+    # every request.
     def permittable_check_json(field, value)
       status, read = super
       return [status, read] unless status == :ok
 
-      at = non_finite_path(value, "")
-      return [:error, "holds NaN or Infinity at #{at}, which JSON cannot carry"] if at
+      problem = unexportable_json(value, "")
+      return [:error, problem] if problem
 
       [status, read]
     end
 
-    # Where the first NaN or infinite Float sits, as `a.b[1].c`, or nil.
-    def non_finite_path(value, path)
+    # Why the first value that would not survive the export is refused, and
+    # where it sits (`a.b[1].c`), or nil.
+    def unexportable_json(value, path)
       case value
-      when Float then path unless value.finite?
-      when Hash then value.each_pair.lazy.filter_map { |k, v| non_finite_path(v, path.empty? ? k.to_s : "#{path}.#{k}") }.first
-      when Array then value.each_with_index.lazy.filter_map { |v, i| non_finite_path(v, "#{path}[#{i}]") }.first
+      when Float, BigDecimal then "holds NaN or Infinity at #{path}, which JSON cannot carry" unless value.finite?
+      when Time, DateTime then unexportable_time(value, path)
+      when Hash then value.each_pair.lazy.filter_map { |k, v| unexportable_json(v, path.empty? ? k.to_s : "#{path}.#{k}") }.first
+      when Array then value.each_with_index.lazy.filter_map { |v, i| unexportable_json(v, "#{path}[#{i}]") }.first
       end
     end
 
+    def unexportable_time(time, path)
+      return if Coercion.whole_nanoseconds?(time)
+
+      "holds a Time at #{path} finer than a nanosecond, so the export publishes a different instant; round it, e.g. with .round(9)"
+    end
+
     def permittable_violation(_field, param, code)
       { param: param, code: code.to_s }
     end

data/lib/permittable/column_guard.rb

@@ -48,12 +48,11 @@ module Permittable
       return false unless schema_reachable?(klass)
 
       fields.flatten.compact.each do |field|
-        unless klass.column_names.include?(field.to_s)
-          raise ArgumentError, ignored_column_message(label, klass, field) if ignored_column?(klass, field)
+        column = backing_column(klass, field)
+        unless klass.column_names.include?(column)
+          raise ArgumentError, ignored_column_message(label, klass, column) if ignored_column?(klass, column)
 
-          raise ArgumentError,
-                "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
-                "#{column_migration_hint(klass, field, types)}"
+          raise ArgumentError, missing_column_message(label, klass, field, column, types)
         end
 
         ensure_column_type!(label, klass, field, types, allowed, transformed: transformed) if check_types
@@ -61,6 +60,114 @@ module Permittable
       true
     end
 
+    # `alias_attribute :title, :name` makes `title` an attribute assignment
+    # accepts, backed by `name`'s column, so the existence check, the
+    # ignored_columns check and the type check all look at the target. Aliases
+    # may chain; the walk stops at a name it has seen, so a cycle cannot hang a
+    # class body. A duck-typed model without `attribute_aliases` (or whose
+    # reader returns nil) has none.
+    def resolve_alias(klass, field)
+      name = field.to_s
+      aliases = attribute_aliases_of(klass)
+      seen = [name]
+      while (target = aliases[name])
+        break if seen.include?(target.to_s)
+
+        name = target.to_s
+        seen << name
+      end
+      name
+    end
+
+    def attribute_aliases_of(klass)
+      klass.respond_to?(:attribute_aliases) ? Hash(klass.attribute_aliases) : {}
+    end
+
+    # The column a field is stored in: its alias target's, or for a store
+    # accessor (`store_accessor :settings, :theme`) the column of its store,
+    # `settings`, itself resolved when the store is an alias. The field is then
+    # a key inside that column, not a column of its own, so the column's type
+    # says nothing about it (see ensure_column_type!). The guard accepts it for
+    # the reason it accepts an alias or an enum: assignment takes it and the
+    # data lands in a column. `virtual: true` stays the opt-out for what no
+    # column holds. That is also why the store column itself must exist.
+    def backing_column(klass, field)
+      name = resolve_alias(klass, field)
+      store = stored_attribute_store(klass, name)
+      store ? resolve_alias(klass, store) : name
+    end
+
+    # The store (the column holding the hash) a `store_accessor` field lives
+    # in, nil when `name` is a plain attribute. A real column of the same name
+    # wins: it is the attribute Rails reads. A duck-typed model without
+    # `stored_attributes` has none.
+    #
+    # `stored_attributes` lists the raw keys (`{settings: [:theme]}`), but the
+    # accessor is named by `prefix:`/`suffix:` too (`settings_theme`), so the
+    # name is accepted only when the model really has a store accessor's writer
+    # under it, which is what assignment calls (see store_accessor_writer?). A
+    # writer from anywhere else is an ordinary attribute, not a
+    # store key. The store is then the one whose key the name is built from,
+    # the longest key first and one whose name the accessor mentions next.
+    # Rails does not record which prefix built which accessor, so two stores
+    # sharing a key are ambiguous, and the guess may check the other's column.
+    def stored_attribute_store(klass, name)
+      return unless klass.respond_to?(:stored_attributes)
+      return if klass.column_names.include?(name) || !store_accessor_writer?(klass, "#{name}=")
+
+      pairs = Hash(klass.stored_attributes).flat_map { |store, keys| keys.map { |key| [store, key.to_s] } }
+      pairs.select { |_store, key| name.include?(key) }
+           .min_by { |store, key| [-key.length, name.include?(store.to_s) ? 0 : 1] }&.first
+    end
+
+    # Whether `writer` is a store accessor's, whatever the model has layered on
+    # it. The accessor is defined by active_record/store.rb itself, so the
+    # method chain is walked through `super` (an override in the model, a
+    # subclass, a prepended or later-included module calls through to it) until
+    # a method defined in that file turns up. That holds across Rails versions:
+    # the module holding the accessors is `_store_accessors_module` on 6.1
+    # through 8.1 and a `GeneratedStoreMethods` constant on main, which a
+    # lookup of either would miss. An ordinary writer (`attr_accessor`, an
+    # attribute-API or column writer) is defined elsewhere.
+    STORE_SOURCE = %r{/active_record/store\.rb\z}
+
+    def store_accessor_writer?(klass, writer)
+      return false unless klass.method_defined?(writer)
+
+      method = klass.instance_method(writer)
+      while method
+        return true if method.source_location&.first.to_s.match?(STORE_SOURCE)
+
+        method = method.super_method
+      end
+      false
+    end
+
+    def missing_column_message(label, klass, field, column, types)
+      store = stored_attribute_store(klass, resolve_alias(klass, field))
+      return store_column_message(label, klass, field, store, column) if store
+
+      if column == field.to_s
+        return "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
+               "#{column_migration_hint(klass, field, types)}"
+      end
+
+      # An alias: the migration must add the column the alias points at,
+      # not one named for the alias, which would still leave this check failing.
+      "#{label}: '#{field}' is an alias of '#{column}', which does not exist in the database " \
+        "(table: #{klass.table_name})." \
+        "#{column_migration_hint(klass, column, types.is_a?(Hash) ? types[field.to_sym] : types)}"
+    end
+
+    # The store column is gone (dropped, or never migrated), so the accessor
+    # reads and writes nothing. That is the column the migration is for, not
+    # a column named after the accessor, which would shadow it.
+    def store_column_message(label, klass, field, store, column)
+      "#{label}: '#{field}' is a store_accessor of :#{store} on #{model_expr(klass)}, " \
+        "but the table has no '#{column}' column (table: #{klass.table_name}). " \
+        "Add the '#{column}' column that holds it, or declare the field virtual: true if the app handles it itself."
+    end
+
     # The type half of the drift guard, opt-in via Permittable
     # .check_column_types. It compares GROUPS rather than exact types (see
     # TYPE_GROUPS) and stays silent unless both sides are known, so it can
@@ -68,18 +175,23 @@ module Permittable
     # :datetime after the column became a string, say.
     def ensure_column_type!(label, klass, field, types, allowed = nil, transformed: nil)
       declared = types.is_a?(Hash) ? types[field.to_sym] : types
-      column = klass.columns_hash[field.to_s]
+      target = resolve_alias(klass, field)
+      column = klass.columns_hash[target]
       return unless declared && column
 
       ensure_not_array_column!(label, klass, field, declared, column)
 
       wanted = TYPE_GROUPS[declared.to_sym]
-      enum = enum_attribute?(klass, field)
+      # An enum is keyed by the name it was declared on, which may be the
+      # alias (`enum :phase` over `alias_attribute :phase, :status`) or the
+      # target it points at.
+      enum_name = [field.to_s, target].find { |name| enum_attribute?(klass, name) }
+      enum = !enum_name.nil?
       # Checked before the column's type, which an enum's contract does not
       # depend on: see ensure_enum_contract!.
       if enum && wanted == :text
-        return ensure_enum_contract!(label, klass, field, declared, allowed && allowed[field.to_sym],
-                                     transformed: Array(transformed).include?(field.to_sym))
+        return ensure_enum_contract!(label, klass, enum_name, declared, allowed && allowed[field.to_sym],
+                                     transformed: Array(transformed).include?(field.to_sym), shown: field.to_s)
       end
 
       # `column.type` is nil for a SQL type the adapter does not recognise
@@ -95,7 +207,8 @@ module Permittable
       # On an enum, `virtual: true` would be the wrong advice: it switches
       # off the existence check too, and the field IS backed by this column.
       fix = if enum
-              "'#{field}' is an enum on #{model_expr(klass)}: declare it :string, in: #{enum_keys_expr(klass, field)}."
+              "#{enum_subject(enum_name, field)} is an enum on #{model_expr(klass)}: " \
+                "declare it :string, in: #{enum_keys_expr(klass, enum_name)}."
             else
               "Change the contract to match the column, migrate the column to match the contract, " \
                 "or declare the field virtual: true if it is not backed by this column."
@@ -153,7 +266,7 @@ module Permittable
     # over a string column) is left compared against the column by choice:
     # an enum's mapping says exactly which strings are valid, an attribute
     # override says nothing a contract could be checked against.
-    def ensure_enum_contract!(label, klass, field, declared, listed, transformed: false)
+    def ensure_enum_contract!(label, klass, field, declared, listed, transformed: false, shown: field)
       problem =
         if listed.nil?
           "declared :#{declared} without an in:"
@@ -170,11 +283,19 @@ module Permittable
         end
 
       raise ArgumentError,
-            "#{label}: '#{field}' is an enum on #{model_expr(klass)}, #{problem} (table: #{klass.table_name}). " \
+            "#{label}: #{enum_subject(field, shown)} is an enum on #{model_expr(klass)}, #{problem} (table: #{klass.table_name}). " \
             "A value outside the enum would pass the contract and then raise on assignment. " \
             "Declare it with in: #{enum_keys_expr(klass, field)}."
     end
 
+    # The field as an enum error names it: `'phase'`, or `'state' (an alias of
+    # 'status')` when the enum is declared on the alias's target.
+    def enum_subject(enum_name, shown)
+      return "'#{shown}'" if enum_name.to_s == shown.to_s
+
+      "'#{shown}' (an alias of '#{enum_name}')"
+    end
+
     def enum_values(klass, field)
       mapping = klass.defined_enums[field.to_s]
       mapping.keys.map(&:to_s) + mapping.values.grep(String)

data/lib/permittable/contract.rb

@@ -140,7 +140,10 @@ module Permittable
     end
 
     # The request-body schema for this contract — JSON Schema draft 2020-12,
-    # identical to what the OpenAPI exporter emits for a controller rule.
+    # what the OpenAPI exporter emits for a controller rule, less what only an
+    # HTTP request carries (the form keys a rootless `unknown: :error` body
+    # lists, the route's path parameters, a multipart body's flat part names):
+    # a contract exempts none of those.
     def json_schema
       JsonSchema.rule(rule)
     end

data/lib/permittable/json_schema.rb

@@ -223,7 +223,7 @@ module Permittable
         # applies here too — a :decimal in: member is otherwise always
         # exported as a string, so a numerically-exported default: is no
         # longer a member of its own enum's exported list. in_published (a
-        # :date/:datetime member kept in its authored String form, see
+        # :datetime member kept in its authored String form, see
         # Coercion.published_in_member) takes precedence over the cast
         # members when both apply.
         schema["enum"] = (field[:in_published] || allowed).map { |v| json_value(v, decimal: :number) }

data/lib/permittable/open_api.rb

@@ -204,12 +204,27 @@ module Permittable
       media_type = body_media_type(rule)
       schema = JsonSchema.rule(rule)
       schema = form_schema(schema, rule) if media_type == "multipart/form-data"
+      allow_form_keys!(schema) if media_type != "multipart/form-data" && rule[:unknown] == :error && !rule[:root]
       {
         "required" => !!(rule[:root] || rule[:fields].any? { |f| f[:required] }),
         "content" => { media_type => { "schema" => schema } }
       }
     end
 
+    # Under `unknown: :error` the runtime still exempts Rails' form keys
+    # (FORM_KEYS) at the top of a rootless contract, so a JSON body carrying
+    # `authenticity_token` or `_method` (a form's fields sent as JSON, a record
+    # echoed back) is accepted, and the body schema must not forbid it. They
+    # stay in as free, never-required properties, as the multipart body lists
+    # them (see form_schema). A name the contract declares keeps its own
+    # schema. A `root:` rule needs none of this: the keys sit outside the root,
+    # in a wrapper that is permissive already. The plain JsonSchema.rule and
+    # Contract#json_schema describe the contract, not an HTTP body, and a
+    # standalone Contract exempts no form key, so they do not list them.
+    def allow_form_keys!(schema)
+      Permittable::FORM_KEYS.each { |key| schema["properties"][key] ||= {} }
+    end
+
     # A multipart body is not one JSON object: each part is a form field, and
     # Rails reads the part NAMES. `user[avatar]` is the avatar of the `user`
     # hash and a repeated `docs[]` is an array, so the schema's properties

data/lib/permittable/rspec.rb

@@ -469,6 +469,8 @@ module Permittable
       end
 
       def cast_json_default(field, expected)
+        # Absent on a nullable field is the nil a contract stores for it.
+        return nil if field[:nullable] && Coercion.absent_value?(expected)
         return expected unless expected.is_a?(Hash)
 
         status, value = AuthoredValues.read_json(field, expected)
@@ -634,7 +636,7 @@ module Permittable
       # `not_to ...returning(x)` would pass both on a rejection and on an
       # acceptance returning anything else.
       def does_not_match?(subject) # rubocop:disable Naming/PredicatePrefix -- the RSpec protocol name
-        raise ArgumentError, negated_qualifier_message if @returning || !@expected_violations.empty?
+        raise ArgumentError, negated_qualifier_message(subject) if @returning || !@expected_violations.empty?
 
         rule = locate(subject)
         return false unless rule
@@ -649,9 +651,12 @@ module Permittable
         if @expect_accepted
           return "expected #{subject_name} to #{description}, but it rejected them: #{summary(@violations)}" unless @violations.empty?
 
-          "expected #{subject_name} to #{description}, but it accepted them but returned #{@result.to_h.inspect}"
+          "expected #{subject_name} to #{description}, but it accepted them but returned " \
+            "#{printable(@result.to_h)}#{differs_note}"
         else
-          return "expected #{subject_name} to #{description}, but it accepted them, returning #{@result.to_h.inspect}" if @violations.empty?
+          if @violations.empty?
+            return "expected #{subject_name} to #{description}, but it accepted them, returning #{printable(@result.to_h)}"
+          end
 
           "expected #{subject_name} to #{description}, but the violations were: #{summary(@violations)}"
         end
@@ -668,7 +673,7 @@ module Permittable
         label = @expect_accepted ? "accept those params" : "reject those params"
         label += action_label
         label += " with #{summary(@expected_violations)}" unless @expected_violations.empty?
-        label += " returning #{@returning.inspect}" if @returning
+        label += " returning #{printable(@returning)}" if @returning
         label
       end
 
@@ -682,15 +687,27 @@ module Permittable
       # first so a matcher object reused across examples (or re-chained
       # with another for_action) never reports a previous run's problem.
       def locate(subject)
-        @problem = @violations = @result = nil
+        @problem = @violations = @result = @root = nil
         @subject = resolve_subject(subject)
-        resolve_rule
-      end
-
-      def negated_qualifier_message
+        rule = resolve_rule
+        @root = rule[:root] if rule
+        rule
+      end
+
+      def negated_qualifier_message(subject = nil)
+        # Raised before the rule is located, so the root a scoped filter
+        # needs is looked up here, best effort: a subject or an ambiguity
+        # that locate would refuse (a BasicObject answers no respond_to?) is not
+        # this message's to report, and leaves the filter unscoped (the
+        # shallow one) rather than masking the qualifier error.
+        begin
+          locate(subject) if subject
+        rescue StandardError
+          @root = nil
+        end
         call = @expect_accepted ? "accept_params" : "reject_params"
         qualifiers = []
-        qualifiers << "returning #{@returning.inspect}" if @returning
+        qualifiers << "returning #{printable(@returning)}" if @returning
         qualifiers << "with_violation #{summary(@expected_violations)}" unless @expected_violations.empty?
         "#{LABEL}: `not_to #{call}(...)` cannot take qualifiers (here: #{qualifiers.join(', ')}) — " \
           "negating one is ambiguous, since it would pass both when the params are " \
@@ -788,36 +805,40 @@ module Permittable
       # payload belongs to the spec. The copy stringifies Symbol keys, which
       # the normalizer's HashWithIndifferentAccess does anyway but only after
       # it has read a Symbol :tempfile key as an upload, a key a request
-      # (String keys only) never has. A Parameters payload is unwrapped first
-      # so it is normalized like the Hash it wraps.
+      # (String keys only) never has, and Symbol values (see copy_payload).
+      # A Parameters payload is unwrapped first so it is normalized like the
+      # Hash it wraps. Without actionpack's request code only the normalizer
+      # is skipped; the copy (and its Symbol stringifying) still happens.
       def request_params
+        payload = copy_payload(@params.respond_to?(:to_unsafe_h) ? @params.to_unsafe_h : @params)
         utils = request_utils
-        return @params unless utils
-
-        payload = @params.respond_to?(:to_unsafe_h) ? @params.to_unsafe_h : @params
-        utils.normalize_encode_params(copy_payload(payload))
+        utils ? utils.normalize_encode_params(payload) : payload
       end
 
       # Rails main moved the class from ActionDispatch::Request::Utils to
-      # ActionDispatch::Http::Utils. nil only when ActionDispatch is not
-      # loaded at all (a non-Rails stand-in controller); once it is, a rename
-      # this does not know raises instead of silently skipping the
-      # normalization, which would bring the false greens back.
+      # ActionDispatch::Http::Utils. nil when actionpack's request code is not
+      # loaded (a non-Rails stand-in controller, or a bare ActionDispatch module
+      # that something else namespaced): there is nothing to normalize with, and
+      # nothing was renamed. Once ActionDispatch::Request exists, a rename this
+      # does not know raises instead of silently skipping the normalization,
+      # which would bring the false greens back.
       def request_utils
-        return unless defined?(ActionDispatch)
-
         if defined?(ActionDispatch::Http::Utils) then ActionDispatch::Http::Utils
         elsif defined?(ActionDispatch::Request::Utils) then ActionDispatch::Request::Utils
-        else
+        elsif defined?(ActionDispatch::Request)
           raise "Permittable's matchers cannot find Rails' parameter normalizer: neither " \
                 "ActionDispatch::Http::Utils nor ActionDispatch::Request::Utils is defined"
         end
       end
 
+      # Symbol keys become Strings, and so do Symbol values: a request carries
+      # every scalar as a String (or a JSON number, boolean or null), never a
+      # Symbol, so `status: :active` is the "active" the contract would read.
       def copy_payload(value)
         case value
         when Hash then value.to_h { |key, item| [key.is_a?(Symbol) ? key.to_s : key, copy_payload(item)] }
         when Array then value.map { |item| copy_payload(item) }
+        when Symbol then value.to_s
         else value
         end
       end
@@ -874,6 +895,116 @@ module Permittable
         raise ArgumentError, "#{LABEL}: the subject of accept_params/reject_params must include Permittable (got #{subject.inspect})"
       end
 
+      # A hash echoed into a failure message, which lands in CI logs, goes out
+      # redacted the way a request log is: by the names `sensitive:` fields
+      # registered, and by the app's config.filter_parameters when a Rails
+      # application is booted. Only the printed copy is filtered; the matching
+      # itself reads the real values.
+      def printable(hash)
+        redacted(hash).inspect
+      end
+
+      # The redacted structure itself, which differs_note walks beside the
+      # real one. A rule with a root: has its hash put back under that root
+      # for the app's filter, as a request logs it, so a scoped filter
+      # ("payment.number", /\Apayment\.code\z/) matches; the registry pass
+      # runs on the hash alone, as it does at runtime.
+      def redacted(hash)
+        inner = redact_sensitive(hash)
+        filter = parameter_filter
+        return inner unless filter
+        return filter.filter(inner) unless @root
+
+        key = @root.to_s
+        filter.filter(key => inner)[key]
+      end
+
+      # The registry's names, by whatever it can answer: #include?, else its
+      # #names matched the way the registry matches (case-insensitive
+      # substring). One with neither is left to its #to_proc in
+      # parameter_filter. A masked value is replaced whole, a Hash included.
+      # An ActionController::Parameters is unwrapped, so its nested values
+      # are reached too.
+      def redact_sensitive(value)
+        value = value.to_unsafe_h if value.respond_to?(:to_unsafe_h)
+        return value.map { |item| redact_sensitive(item) } if value.is_a?(Array)
+        return value unless value.is_a?(Hash)
+
+        registry = Permittable.filter_parameter_registry
+        value.to_h do |key, item|
+          [key, sensitive_name?(registry, key) ? Permittable::FilterParameterRegistry::FILTERED : redact_sensitive(item)]
+        end
+      end
+
+      def sensitive_name?(registry, key)
+        if registry.respond_to?(:include?)
+          registry.include?(key)
+        elsif registry.respond_to?(:names)
+          name = key.to_s.downcase
+          registry.names.any? { |sensitive| name.include?(sensitive.to_s.downcase) }
+        else
+          false
+        end
+      end
+
+      # Rails' ParameterFilter over the app's config.filter_parameters, plus
+      # the registry's own #to_proc when it can answer neither #include? nor
+      # #names (a proc masks only Strings, but it is all such a registry
+      # offers). ActiveSupport::ParameterFilter is not loaded by
+      # `require "active_support"` before 7.0, and a Rails 6.1 app without
+      # ActionDispatch::Request has not loaded it either; it has been
+      # requirable since 6.0.
+      def parameter_filter
+        filters = []
+        app = defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        filters.concat(Array(app.config.filter_parameters)) if app
+        registry = Permittable.filter_parameter_registry
+        filters << registry.to_proc unless registry.respond_to?(:include?) || registry.respond_to?(:names)
+        return if filters.empty?
+
+        begin
+          require "active_support/parameter_filter"
+        rescue LoadError
+          return
+        end
+        ActiveSupport::ParameterFilter.new(filters)
+      end
+
+      # The registry matches by substring, like Rails (`pin` also redacts
+      # `shipping`), so an expected and an actual hash that differ only under
+      # redacted names print the same. Say where they differ, by name only.
+      def differs_note
+        return "" unless @returning
+
+        expected = ActiveSupport::HashWithIndifferentAccess.new(@returning).to_h
+        actual = @result.to_h
+        return "" if expected == actual || printable(expected) != printable(actual)
+
+        # A filter on the root itself masks the whole hash, leaving the root as the one path.
+        paths = differing_paths(expected, actual, redacted(expected), redacted(actual)).map { |path| path || @root.to_s }
+        paths.empty? ? "" : "; differs at: #{paths.join(', ')}"
+      end
+
+      # Walks the real hashes beside their redacted copies and stops at the
+      # redaction boundary: a node the copy shows as masked is named by its
+      # path alone when the real values differ, and not entered, since a key
+      # or an index below it is as secret as its value.
+      def differing_paths(expected, actual, expected_masked, actual_masked, prefix = nil)
+        filtered = Permittable::FilterParameterRegistry::FILTERED
+        masked = expected_masked == filtered || actual_masked == filtered
+        if !masked && expected.is_a?(Hash) && actual.is_a?(Hash)
+          (expected.keys | actual.keys).flat_map do |key|
+            differing_paths(expected[key], actual[key], expected_masked[key], actual_masked[key], [prefix, key].compact.join("."))
+          end
+        elsif !masked && expected.is_a?(Array) && actual.is_a?(Array) && expected.length == actual.length
+          expected.each_index.flat_map do |i|
+            differing_paths(expected[i], actual[i], expected_masked[i], actual_masked[i], "#{prefix}[#{i}]")
+          end
+        else
+          expected == actual ? [] : [prefix]
+        end
+      end
+
       def summary(violations)
         violations.map { |v| v[:code] ? "#{v[:param]} (#{v[:code]})" : v[:param] }.join(", ")
       end

data/lib/permittable/tasks/audit.rake

@@ -13,9 +13,10 @@ namespace :permittable do
 
     # Every controller, not just the ones including Permittable — a controller
     # that never included it is unguarded, which is exactly the finding. Bare
-    # ActionController::Metal ones included; see Audit.rails_controllers.
-    controllers = Permittable::Audit.rails_controllers
+    # ActionController::Metal ones included, and autoloaded framework ones
+    # (Rails::HealthController) the routes name; see Audit.rails_controllers.
     routes = Permittable::OpenAPI.rails_routes(Rails.application)
+    controllers = Permittable::Audit.rails_controllers(routes)
 
     entries = Permittable::Audit.entries(controllers: controllers, routes: routes)
     stale = Permittable::Audit.stale(controllers: controllers, routes: routes)

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.14.0".freeze
+  VERSION = "0.15.0".freeze
 end

data/lib/permittable.rb

@@ -1041,9 +1041,13 @@ module Permittable
         found = Date._parse(value)
         return [:error, "invalid_type"] unless complete_date?(found)
         return cast_date_instant(value, found) if names_an_instant?(found)
-        # No time found, but an offset may have been dropped ("5/9/2026
-        # -0500"), which :datetime refuses too.
-        return [:error, "invalid_type"] if !plain && offset_misread?(value, found)
+
+        # No time found, but a zone or offset may have been dropped
+        # ("5/9/2026 -0500", "2026-09-05 EST") or an hour with it
+        # ("2026-09-05T10"), which :datetime refuses or reads the same way.
+        if !plain && (dropped = dropped_tail(value, found))
+          return date_at_midnight(*dropped)
+        end
 
         # Built from the components rather than re-running Date.parse, which
         # would parse the same string a second time — and Date.parse is the
@@ -1082,7 +1086,11 @@ module Permittable
     # ruled out the ISO forms cast_datetime reads without one; :datetime's
     # reading of it is then the same, with one parse fewer.
     def cast_date_instant(value, found = nil)
-      status, instant = found ? cast_parsed_datetime(value, found) : cast_datetime(value)
+      date_at_midnight(*(found ? cast_parsed_datetime(value, found) : cast_datetime(value)))
+    end
+
+    # The Date of an instant read from a String when it is midnight UTC.
+    def date_at_midnight(status, instant)
       return [:error, "invalid_type"] unless status == :ok && instant == instant.beginning_of_day
 
       [:ok, Date.new(instant.year, instant.month, instant.day)]
@@ -1167,7 +1175,9 @@ module Permittable
     # parts, shared with cast_date_instant so a :date need not parse twice.
     def cast_parsed_datetime(value, found)
       return [:error, "invalid_type"] unless complete_date?(found) && honoured_zone?(found)
-      return [:error, "invalid_type"] if offset_misread?(value, found)
+
+      dropped = dropped_tail(value, found)
+      return dropped if dropped
 
       [:ok, DateTime.parse(value, true, Date::GREGORIAN).to_time.utc]
     rescue ArgumentError, RangeError
@@ -1236,23 +1246,102 @@ module Permittable
       (zone.start_with?("-") ? -1 : 1) * ((hours * 3600) + (minutes * 60))
     end
 
-    # Whether a date's trailing offset was taken for its time of day
-    # ("Sep 5 2026 -05:00" reports 05:00, "2026-09-05 UTC-05:00" too) or
-    # dropped without a trace ("5/9/2026 -0500", "2026-09-05 +5"), outside
-    # the ISO form midnight_at_offset reads. The tail is the culprit when the
-    # parser found no zone and the String without it names the same date and
-    # no time. Only a String that ends in a signed number and either got an
-    # hour or has a space before the number is parsed again, so a plain
-    # "2026-09-05" is not.
-    def offset_misread?(value, found)
-      return false if found.key?(:zone)
+    # An ISO date, then a "T": what follows is an ISO time, so a parse that
+    # found no hour ("2026-09-05T10", "T1030", "T10Z") dropped it.
+    ISO_DATE_T_START = /\A\s*\d{4}(-?)\d{2}\1\d{2}[Tt]/
+
+    # Trailing words, set apart by a space: a zone name ("EST", "Eastern
+    # Standard Time", "W. Europe Standard Time") or a day or era word. The
+    # first word has two letters or more, or one and a ".", as a lone letter
+    # is a military zone or the ISO "T".
+    ZONE_NAME_TAIL = /(?<=\s)[[:alpha:]](?:\.|[[:alpha:]]+)[[:alpha:].]*(?:\s+[[:alpha:].]+)*\z/
 
-      tail = SIGNED_TAIL.match(value) or return false
-      return false unless tail[1] || found.key?(:hour)
+    # An era word at the start of such a tail: the parser reads it with the
+    # date ("Sep 5 2026 BC" is the year -2025), so it is not what follows.
+    ERA_WORD = /\A(?:a\.?\s?d\.?|c\.?\s?e\.?|b\.?\s?c\.?(?:\s?e\.?)?)(?:\s+|\z)/i
 
-      rest = Date._parse(tail.pre_match)
-      complete_date?(rest) && !rest.key?(:hour) &&
-        rest.values_at(:year, :mon, :mday) == found.values_at(:year, :mon, :mday)
+    # What ends a date the way git, `date` and Time#to_s write it, with the
+    # offset after the year: "Sat Sep 5 10:00:00 2026", "Sep 5 10:00 2026".
+    TIME_THEN_YEAR = /\d:\d{2}(?::\d{2}(?:[.,]\d+)?)?\s+\d{4}\s*\z/
+    private_constant :ZONE_NAME_TAIL, :ERA_WORD, :TIME_THEN_YEAR
+
+    # What Date._parse did with the END of a date or date-time String when it
+    # dropped or misplaced it, as nil when it did neither, or the result
+    # ([:ok, instant] or [:error, "invalid_type"]) the String must be given:
+    #
+    # - an hour after an ISO "T" it did not find ("2026-09-05T10");
+    # - a trailing offset taken for a time of day ("Sep 5 2026 -05:00",
+    #   "2026-09-05 10 -05:00", "2026-09-05 UTC-05:00") or dropped without a
+    #   trace ("5/9/2026 -0500", "12:00 2026-09-05 -05:00"), outside the ISO
+    #   form midnight_at_offset reads. An offset after "10:00:00 2026" is the
+    #   exception: that is git's and ctime's format, which puts it after the
+    #   year, so it is read, like a zone name;
+    # - a trailing zone NAME, which it reads only next to a time of day:
+    #   "2026-09-05 EST" is midnight at -05:00 and "Sat Sep 5 10:00:00 2026
+    #   EST" 10:00 there. A name it does not know is refused like any other
+    #   zone (honoured_zone?), and so is ANY other word after a complete date
+    #   ("2026-09-05 noon"), since all it can be is a zone. A day name and an
+    #   era word are what the parser reads as part of the date, not a zone.
+    #
+    # The tail is the culprit when the parser found no zone and the String
+    # 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)
+      return [:error, "invalid_type"] if !found.key?(:hour) && ISO_DATE_T_START.match?(value)
+      return if found.key?(:zone)
+
+      if (tail = SIGNED_TAIL.match(value))
+        return unless tail[1] || found.key?(:hour)
+
+        rest = Date._parse(tail.pre_match)
+        return unless same_date?(rest, found)
+
+        git_style = tail[1] && found.key?(:hour) && TIME_THEN_YEAR.match?(tail.pre_match) && same_time?(rest, found)
+        git_style ? instant_in_zone(tail.pre_match, tail[0].strip) : [:error, "invalid_type"]
+      elsif (tail = ZONE_NAME_TAIL.match(value))
+        pre = tail.pre_match
+        text = tail[0]
+        if (era = ERA_WORD.match(text))
+          pre += era[0]
+          text = era.post_match
+        end
+        return if text.empty?
+
+        rest = Date._parse(pre)
+        return unless same_date?(rest, found)
+
+        zone = Date._parse("00:00 #{text}")
+        return unless zone.key?(:zone) # a day name
+        # A single letter is a military zone, which is no zone here: alone it
+        # is nothing ("2026-09-05 a", "A."), but the rest of an initial-led
+        # name Ruby did not know ("W. Europe") is dropped, so it is refused
+        # like any other word it does not know.
+        return text.match?(/\A[[:alpha:]]\.?\z/) ? nil : [:error, "invalid_type"] if zone[:zone].length == 1
+        # The hour the tail made the parser lose ("2026-09-05 10 EST").
+        return [:error, "invalid_type"] unless same_time?(rest, found)
+
+        instant_in_zone(pre, text)
+      end
+    end
+
+    # The wall clock `date` names, as it is read in the zone `text` names:
+    # [:ok, instant], or an error when Ruby cannot honour the zone.
+    def instant_in_zone(date, text)
+      zone = Date._parse("00:00 #{text}")
+      return [:error, "invalid_type"] unless zone.key?(:zone) && honoured_zone?(zone)
+
+      [:ok, DateTime.parse(date, true, Date::GREGORIAN).to_time.utc - zone[:offset]]
+    end
+
+    def same_time?(rest, found)
+      TIME_PARTS.all? { |part| rest[part] == found[part] }
+    end
+
+    TIME_PARTS = %i[hour min sec sec_fraction].freeze
+    private_constant :TIME_PARTS
+
+    def same_date?(rest, found)
+      complete_date?(rest) && rest.values_at(:year, :mon, :mday) == found.values_at(:year, :mon, :mday)
     end
 
     # Presets only make sense on String input; a non-String value (JSON
@@ -1446,13 +1535,17 @@ module Permittable
     end
 
     # What an exported enum lists for one member: the cast value, re-encoded
-    # as JSON — except a :date/:datetime member authored as a String, which
-    # is published AS WRITTEN. Re-encoding a cast Time prints whole seconds,
-    # so "2026-09-05T10:00:00.25Z" was published as "…10:00:00Z", a value
-    # the server refuses. The authored String went through the very cast a
-    # request does, so the server accepts it by construction.
+    # as JSON — except a :datetime member authored as a String, which is
+    # published AS WRITTEN. Re-encoding a cast Time prints whole seconds, so
+    # "2026-09-05T10:00:00.25Z" was published as "…10:00:00Z", a value the
+    # server refuses. The authored String went through the very cast a request
+    # does, so the server accepts it by construction. A :date member is
+    # re-encoded: a Date has no digits to lose, and the String as written
+    # ("Sep 6, 2026", "2026-09-05T00:00:00Z") is a date the server reads but
+    # not one `format: date` accepts, so it is published as the YYYY-MM-DD
+    # the server compares against.
     def published_in_member(type, member, value)
-      member.is_a?(String) && %i[date datetime].include?(type) ? member : value
+      member.is_a?(String) && type == :datetime ? member : value
     end
 
     # Range#include? walks discrete ranges; cover? is the O(1) bounds check
@@ -1799,7 +1892,7 @@ module Permittable
     end
 
     # `published` is stored only where it differs from the cast members (a
-    # String-authored :date/:datetime member), so it is read as an override.
+    # String-authored :datetime member), so it is read as an override.
     def cast_in_members!(field, members)
       status, cast, published = Coercion.cast_in_members(field[:type], members, nullable: field[:nullable])
       unless status == :ok
@@ -1896,6 +1989,12 @@ module Permittable
     def validate_json_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
+
+      # A request sending "" for a nullable :json field is the explicit null
+      # the walker reads it as, so a blank authored value is that nil, as a
+      # nullable scalar's is (see validate_authored_value!).
+      return field[opt] = nil if field[:nullable] && Coercion.absent_value?(field[opt])
+
       raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
 
       status, read = AuthoredValues.read_json(field, field[opt])
@@ -2351,6 +2450,11 @@ module Permittable
     # rescue_from until the app includes them, and a rule that needs one of
     # them would otherwise load and then not run: raise at class load, naming
     # the module. Other hosts (a plain class, a duck) are left as they are.
+    # 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
+    # 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.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-09 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport