permittable 0.14.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a884eb52cc555157fddf46346de7995e12c1da2920e8488cfae7d7f383123824
-  data.tar.gz: dae0d105fb44f1a0dac9cc07b33fd583e3e5fc5952f5511bb46126a56ae229ad
+  metadata.gz: 2284fdea0043c6364608ab68b43de16bbea66462f12a4f2e6ee5bdf47087fbb6
+  data.tar.gz: 8dd729f396cee1ba015179bd3ee8522754bc6312f4816810ed060134da8456d7
 SHA512:
-  metadata.gz: 63a2d785b2067d7d581d13775da06c180db170597acaad22a9c3de0622a7592f79a7ccf8febcb6199a53954ac03bfa606e781110927e02834145c313dcb6b366
-  data.tar.gz: baca9f1599f2637e68ab407bb81861d342fc79b43c6a836aa6e165e47acf539c6f3625fcdc07cfe4c5dd9c9e1b1e69de75df481dffc7d95126e0ae3f52ac383d
+  metadata.gz: 239926696fff412e35a4ef9bf0f392f92006c90a9ff8d69779a575eb71420ff441a433123a23c7d9e459d8eaf62d74bc9371aa1649bb739b4d89db60831d41ad
+  data.tar.gz: 04b5b1fe3b2993056a650f2f293a9a95e8c46f5c8bc5eb609929a0e93ae9e81591cc6434822fce5dcbfd06eb9ae4b17081165fdc817c91495abc59badba12339

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 <!-- CHANGELOG.md -->
 
+## 0.15.1 (2026-11-12)
+<!-- title: a date String's hour and glued offset read or refused, and the exported body and descriptors list the routing keys, a renamed CSRF token and a route's format default -->
+
+**Patch rather than minor.** Every string this release newly refuses was already misread by 0.15.0: each dropped an hour or an offset, or read midnight UTC by accident. The refused strings are `"2026-09-05 10 A.D."`, `"2026-09-05 10 a"`, `"2026-09-05 10 AD GMT+5"`, offsets that are not read whole or not honoured (`"EST+5"`, `"UTC+99"`, `"GMT+0560"`), and, for a `:date`, `"2026-09-05 GMT+5"`. The export changes are these: `rails_routes` descriptors now name a `format:` default; a contract field `format` leaves the body for such routes; a rootless multipart `unknown: :error` body gains a redundant `"format": {}`; and a rootless JSON `unknown: :error` body lists the routing keys and a renamed CSRF token as free properties.
+
+### Fixed
+- **An hour before an era or a lone letter is refused on a date String.** `"2026-09-05 10 A.D."` and `"2026-09-05 10 a"` lost the hour on 0.15.0 and read as midnight; they are now refused as `invalid_type`, as `"2026-09-05 10 EST"` already was. (#179)
+- **An offset glued to a zone name is read.** `"2026-09-05 GMT+5"` and `"2026-09-05 UTC+0530"` were dropped to midnight UTC on 0.15.0. A `:datetime` now reads them as midnight at that offset (`2026-09-04T19:00Z`, `2026-09-04T18:30Z`); a `:date` refuses them, since the instant is not midnight UTC. (#179)
+- **The rootless `unknown: :error` JSON body lists the routing keys and a renamed CSRF token.** `controller`, `action`, `format` and the controller's `request_forgery_protection_token` are accepted by the runtime but failed the exported schema. They are now free, optional properties. (#180)
+- **A route's `format:` default fills a contract field of that name.** The export left a field called `format` in the body and its `required` list, though the router fills it. `rails_routes` now names `format` in the descriptor's `defaults:`. (#180)
+
+## 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
 
@@ -605,7 +605,7 @@ optional :avatar, :file, validate: ->(file) { file.size <= 2.megabytes && file.c
 array    :attachments, of: :file, length: 0..5
 ```
 
-`:file` takes `required:`, `nullable:`, `validate:`, `transform:`, `desc:`, `sensitive:`, `virtual:` and `message:`. `in:`, `length:`, `format:`, `normalize:`, `default:` and `example:` are refused at class load. A form's empty file input sends `""`, which is absent as everywhere else. The [drift guard](#the-schema-drift-guard) does not look for a column behind a `:file` field (an attachment is not a column), and the OpenAPI export documents an operation with a file as `multipart/form-data`, its properties named the way Rails reads the parts (`user[avatar]`, `docs[]`, `user[address][scan]`). An array of hashes is sent with an index (`items[0][photo]`, `items[0][name]`, `items[1][photo]`, …), as Rails' `fields_for` renders it, and the document describes those leaves with anchored `patternProperties`. What a flat body cannot carry, a container's own `required`, `minItems`/`maxItems`, `nullable`, `description` and custom-validation marker, is kept in the body's `x-permittable-form-groups`, keyed by the container's bracket name (`user[items]`), with `[]` standing for the index of a container inside an element (`user[items][][info]`). Send a nullable container's null as an empty part named by that bracket name, without `[]` (`user[docs]=""`; `user[docs][]=""` is an empty array). Under `unknown: :error` the multipart body sets `additionalProperties: false`, which refuses an undeclared part at any depth (`user[address][bogus]`, `user[items][0][bogus]`), and it lists the parts the server still takes: a nullable container's null as `{"const": ""}`, a `:json` field's keys (`user[extra][any]`) and, for a `root:` rule, any part outside the root, or for a rootless one, the form keys the runtime exempts (`authenticity_token`, `_method`, `utf8`, `commit`, `button`). A renamed CSRF token (`request_forgery_protection_token`) and an image submit's `x`/`y` cannot be known when the document is built, so they are not listed. The children of an optional hash are required only when the hash is sent (the group entry says the hash is optional), and `patternProperties` cannot mark a leaf of an array element required.
+`:file` takes `required:`, `nullable:`, `validate:`, `transform:`, `desc:`, `sensitive:`, `virtual:` and `message:`. `in:`, `length:`, `format:`, `normalize:`, `default:` and `example:` are refused at class load. A form's empty file input sends `""`, which is absent as everywhere else. The [drift guard](#the-schema-drift-guard) does not look for a column behind a `:file` field (an attachment is not a column), and the OpenAPI export documents an operation with a file as `multipart/form-data`, its properties named the way Rails reads the parts (`user[avatar]`, `docs[]`, `user[address][scan]`). An array of hashes is sent with an index (`items[0][photo]`, `items[0][name]`, `items[1][photo]`, …), as Rails' `fields_for` renders it, and the document describes those leaves with anchored `patternProperties`. What a flat body cannot carry, a container's own `required`, `minItems`/`maxItems`, `nullable`, `description` and custom-validation marker, is kept in the body's `x-permittable-form-groups`, keyed by the container's bracket name (`user[items]`), with `[]` standing for the index of a container inside an element (`user[items][][info]`). Send a nullable container's null as an empty part named by that bracket name, without `[]` (`user[docs]=""`; `user[docs][]=""` is an empty array). Under `unknown: :error` the multipart body sets `additionalProperties: false`, which refuses an undeclared part at any depth (`user[address][bogus]`, `user[items][0][bogus]`), and it lists the parts the server still takes: a nullable container's null as `{"const": ""}`, a `:json` field's keys (`user[extra][any]`) and, for a `root:` rule, any part outside the root, or for a rootless one, the keys the runtime exempts: Rails' routing keys (`controller`, `action`, `format`), the form keys (`authenticity_token`, `_method`, `utf8`, `commit`, `button`) and the CSRF token name the controller renamed with `request_forgery_protection_token`. An image submit's `x`/`y` and a per-instance override of the token cannot be known when the document is built, so they are not listed. The children of an optional hash are required only when the hash is sent (the group entry says the hash is optional), and `patternProperties` cannot mark a leaf of an array element required.
 
 An ActiveStorage direct upload (`form.file_field :avatar, direct_upload: true`) sends the file from the browser straight to the storage service, and the form then submits only the blob's signed id, a String, which a `:file` field refuses as `invalid_type`. Declare such a field `:string` and attach the signed id (`record.avatar.attach(signed_id)`):
 
@@ -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 glued to a zone name with no time is midnight at that offset where Ruby honours it (`"2026-09-05 GMT+5"` is `2026-09-04T19:00:00Z`) and refused where it does not (`"2026-09-05 UTC+99"`, `"2026-09-05 EST+5"`). An offset after the year of git's and ctime's format is read (`"Sat Sep  5 10:00:00 2026 -0500"` is `15:00:00Z`). An hour or offset the parser would drop or misread (`"2026-09-05T10"`, `"2026-09-05 10 -05:00"`, `"2026-09-05 10 A.D."`, `"2026-09-05 10 a"`, `"12:00 2026-09-05 -05:00"`) is refused rather than read as some other instant.
 
 **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 keys the runtime exempts (`controller`, `action`, `format`, `authenticity_token`, `_method`, `utf8`, `commit`, `button`, and the controller's renamed CSRF token, if any) 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` and `action`; a `format:` default (`defaults: { format: "json" }`) is named like any other, so a contract field called `format` leaves the body and its `required` list for such a route. **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) }