permittable 0.12.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 737a1777a6da7e8bcce3e969b82796279f0b5f1f51f3497abad696c4622f6951
-  data.tar.gz: 8c01787cc7081db7bbf6f4f0ce5a1f337b32e4d801d96bd6bd1f82678092c42e
+  metadata.gz: bbb9461a44e4918ca7a982fc42ad55e7c2c6a36b231ea9560eb298c85fea259c
+  data.tar.gz: 324137849cfc36dde9a3ff2764aeef2ba02beec9e6487bd70b4990b0ee3b95e9
 SHA512:
-  metadata.gz: 19320e84873a06b21eec376ddb236275ac7beaf217d29eed91e3dfab1e26c644c35538c6549ef57a73c6dd95b8bc9c5305aef8ed40075c3823f5d8a53dfd5404
-  data.tar.gz: 99cf9b0eee28ab54f31388fe647280b4f372022dc1bfc02ff01a09ef70032d68e0fde76816a51699fc9127b85f5230cd6938c2f4899981f954ec58d3e87a8de2
+  metadata.gz: f612dc7e5b04cf543c34b4b9ff4810e0620f80a8dfcc6cbed92d2969eab40a4396b3472d9ac2f8b4a37bc1b1a8d92ddc166312edba7de78508de2c4435dcba31
+  data.tar.gz: 7dd8145f4968a76cd10332a17f74a30531a4c4d549becd967b80c5f2a7f4ad41b54751209abf94b9386aa6a0aaa939d3be8f1eb1a3dd1b309f05bd39c5d212d6

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 <!-- CHANGELOG.md -->
 
+## 0.13.1 (2026-11-04)
+<!-- title: contracts that cannot be exported are refused at class load, a Metal catch-all and a date-parts example export correctly, and a pre-1582 date reads as the day it names -->
+
+Six fixes, one documentation change and a development dependency bump, no new API. A `:datetime` `default:` or `example:` finer than a nanosecond and a `:json` `default:` or `example:` holding NaN or Infinity are now refused at class load, instead of loading and then breaking the export. The OpenAPI export of a catch-all contract on an `ActionController::Metal` controller no longer documents the framework's own methods as operations, and an array `example:` written with date parts is exported as the date it spells. A midnight-UTC `Time` or `DateTime` sent to a `:date` before 1582 is read as the day it names. A missing-column error for an ignored column no longer suggests a migration, and the README now says that a catch-all `rescue_from` declared after the include wins.
+
+Patch rather than minor: nothing that works today stops working. Every entry is a crash or a wrong value on input that was already mishandled, an export correction that makes the document agree with what the server does, a clearer error message, documentation, or development tooling. Four things are visible from outside and worth knowing before you upgrade. A contract now fails at class load, naming the field, in three cases: its `:datetime` `default:` or `example:` is finer than a nanosecond (#159), which the export published as a different instant; its `:json` `default:` or `example:` holds NaN or Infinity (#163), which made the export raise; or its `:date` `in:` member is a `Time` on one of the days 1582-10-05 to 1582-10-14 (#164), which was read silently as 1582-09-30. The OpenAPI export of a Metal catch-all loses its bogus framework operations (#161). An array `example:` written with date parts is now exported correctly (#162).
+
+### Fixed
+- **An ignored column that is in the table was reported as missing, with a migration hint that would add it twice.** `ColumnGuard` checked a field against `column_names`, which leaves out `ignored_columns`, so `optional :legacy, :integer` on a model with `self.ignored_columns = %w[legacy]` raised "does not exist in the database" and suggested `bin/rails generate migration`. The guard still refuses the field, since assigning an ignored column raises `ActiveModel::UnknownAttributeError`, but the message now says the model ignores the column and suggests removing it from `ignored_columns` or declaring the field `virtual: true`. When the column was dropped and its name was left in `ignored_columns`, the message says the table has no such column and gives no migration. (#157)
+- **A `:datetime` `default:` or `example:` finer than a nanosecond loaded, and the export published a different instant.** 0.12.0 refused such an `in:` member (#106), but `Time.at(Rational(1, 3)).utc` as a `default:` was exported as `.333333333Z`, so a client that sent the published default sent a different instant. A `default:` or `example:` finer than a nanosecond now raises `ArgumentError` at class load, naming the field, at any depth: a scalar, an `of: :datetime` array, an array of hashes and a sub-field. A String with ten or more fractional digits is refused too, unlike an `in:` String member, which is published as written. A nanosecond-exact value is still accepted. (#159)
+- **The OpenAPI export documented about 36 framework methods of a Metal controller as operations.** A catch-all `permit_params` on an `ActionController::Metal` controller expanded from `action_methods`, which for a Metal subclass counts every public method of an included module, so `render`, `head`, `_prefixes`, `view_paths` and the rest were exported with operationIds such as `pings_render`. The catch-all now lists only the controller's own actions, as it does on an `ActionController::Base` controller. (#161)
+- **An array `example:` written with date parts was exported as `[{}]`.** `array :items, example: [{ "on(1i)" => "2026", "on(2i)" => "10", "on(3i)" => "17" }]` was published as `[[{}]]`, though a request with the same parts reads as `2026-10-17`, and the server would fill in the sub-field's default for the published payload. The example is now judged on the hash with the date parts assembled, and is exported as `[{"on" => "2026-10-17"}]`. This covers `:date` and `:datetime` parts, in arrays and in a nested block inside an array. Requests are unchanged. (#162)
+- **A `:json` `default:` or `example:` holding NaN or Infinity loaded, and the export raised.** `optional :meta, :json, default: { "score" => Float::NAN }` loaded, and `JSON.generate(json_schema)` then raised `JSON::GeneratorError`. No JSON request can carry NaN, so the value is one no client can send. A non-finite Float at any depth of a `:json` default or example, including a `:json` sub-field and a `:json` value inside an array, now raises `ArgumentError` at class load, naming the field and the path, such as `x[1].y`. Requests are unchanged. (#163)
+- **A midnight-UTC `Time` sent to a `:date` before 1582 was read as the wrong day.** `Time.utc(1500, 1, 1)` became 1499-12-23, because `Time#to_date` labels days before the reform in the Julian calendar, while the String `"1500-01-01"` is proleptic Gregorian. The same applied to a `DateTime` and a `TimeWithZone`, and to `in:` members and `default:` values, which never matched or were exported as a different day. The day is now built from the instant's own year, month and day, so a Time, a DateTime and the String `"1500-01-01T00:00:00Z"` all give 1500-01-01. (#164)
+- **A pre-1582 `DateTime` was read wrongly without ActiveSupport.** With a plain `require "permittable"`, `DateTime.new(1500, 1, 1)` sent to a `:date` landed on 1500-01-10. It now reads the DateTime's own calendar labels and gives 1500-01-01, with or without ActiveSupport. The days 1582-10-05 to 1582-10-14 do not exist in the calendar a `:date` reads, so a Time or DateTime on one of them is `invalid_type`, and an `in:` member on one raises the normal class-load error naming the field. A `:datetime` still accepts those days. (#164)
+
+### Documentation
+- **The README now says that a catch-all `rescue_from` declared after `include Permittable` wins.** `include Permittable` registers `rescue_from Permittable::InvalidParameters`, and Rails searches handlers from the last declared, so a `rescue_from StandardError` placed after the include answers an invalid request with its own response, often a 500, and the gem's 422 never runs. The README gives the two fixes: declare the catch-all before the include, or declare `rescue_from Permittable::InvalidParameters, with: :render_invalid_parameters` after it. (#158)
+
+### Development
+- **Bump `sqlite3` 2.10.0 to 2.10.1 and `rubocop` (bundler-minor-patch group).** Development dependencies only. (#167)
+
+## 0.13.0 (2026-10-24)
+<!-- title: the audit and the OpenAPI export follow mounted engines and Metal controllers, and a path variable is documented as one -->
+
+Two changes to what the audit and the OpenAPI export read, and one to how the export documents path variables. `permittable:audit`, `permittable:openapi` and `permittable:generate` now see controllers built directly on `ActionController::Metal`. The audit and the export follow routes mounted from a Rails engine, with the mount's path in front of the engine's. A rootless contract field that a route fills from the URL is documented as the path parameter it is.
+
+Minor rather than patch: there is no runtime change, `OpenAPI.rails_routes` callers now get more descriptors and a descriptor's `route:` may be an Array, but the audit and the OpenAPI document now see more, so `permittable:audit[strict]` can newly fail in an app that has an unguarded Metal controller or an unguarded route in a mounted engine, and an exported document changes for any app with a mounted engine, a Metal controller or a route-filled field.
+
+### Added
+- **`OpenAPI.rails_routes(app, engines: false)` reads the app's own route set alone.** `engines:` is a new keyword and defaults to `true`, which follows mounted engines (see the first entry under **Changed**). (#144)
+
+### Changed
+- **The audit and the OpenAPI export follow mounted Rails engines.** `OpenAPI.rails_routes` read only the app's own route set, so with `mount Billing::Engine => "/billing"` an unguarded `POST /billing/refunds` was never listed and `[strict]` exited 0, a covered `billing/invoices#create` was reported stale, and the export put billing operations under `x-permittable-controllers` instead of `paths`. `rails_routes(app, engines: true)` now follows each mounted engine, nested ones too, and puts the mount's path in front of the engine's, so a mount under `scope "(:locale)"`, at a dynamic `":tenant"`, or at `/` expands like any route. Routes reached through a mount carry `route: [mount, route]`, with one index per mount level (e.g. `[3, 0, 5]`), so `route:` may be an Array. Dispatch follows Rails: a mount ending in an optional segment lists no engine path Rails sends elsewhere, shadowing between app and engine routes follows Rails' single route order with each mount expanded in place, and a mount's `via:` drops the engine's other verbs. Rack mounts that are not engines are still skipped, a recursion guard stops cycles, and mounted gem engines appear in the audit's "outside the app root" section by default (while `Permittable.audit_ignore_outside_root` is on), without affecting `[strict]`. Callers that concatenate an app's and an engine's lists themselves should pass `engines: false`, which restores the old output. A parameter name used by both the mount and an engine route is not renamed: the path names it twice (`/t/{id}/{id}`) and the operation declares that one path parameter once. An engine route whose optional groups can all be absent (`post "(:locale(/:region))"`) is not documented as the mount's own path, which Rails answers with 404, and a lambda-constrained mount is still listed. (#144)
+- **`permittable:audit`, `permittable:openapi` and `permittable:generate` read `ActionController::Metal` controllers.** Each task collected controllers from `ActionController::Base.descendants` and `ActionController::API.descendants` only, so a lean webhook controller built on `Metal` was invisible: its unguarded `POST /hooks` had no audit row and did not fail `[strict]`, and one that included Permittable had its contracts enforced at runtime but missing from the export. All three tasks now read `Audit.rails_controllers`, which returns every named `ActionController::Metal` descendant less the framework's own abstract `ActionController::Base` and `ActionController::API`. (#108)
+
+### Fixed
+- **A rootless field a route fills from the URL is documented as the path parameter.** Rails merges the router's path parameters over the request's, so a rootless `required :id, :integer, in: 1..1000` on `resources :widgets, only: :update` is read from the URL, but the export gave the path parameter `{"type":"string"}` and put `id` in the request body's `required` list. The field now becomes the path parameter's schema, which stays required, and leaves the body's `properties` and `required`. Only a rootless contract does this, only for a scalar field, and only for a name the route's own path templates; an array, nested or `:json` field named like a variable stays in the body. With `unknown: :error`, every name the route templates stays in the body as an unconstrained, never-required property, so `{"id":7,"name":"x"}` is not documented as invalid. An action whose every field moved has no request body. A moved field loses `default:` and `nullable:`. A route that shares another's path pairs its variable names with the placed ones by position. (#136)
+
 ## 0.12.0 (2026-10-21)
 <!-- title: stricter numbers, dates and class-load checks, and matchers that stop passing for the wrong reason -->
 

data/README.md

@@ -716,7 +716,7 @@ What you give up is the shape. What you keep:
 | `max_depth:` | Caps **container nesting**, counting arrays as a level: `{"a": 1}` is 1, `{"a": {"b": 1}}` and `{"a": [1, 2]}` are 2, `{"a": [{"b": 1}]}` is 3. Violation code `depth` |
 | `validate:` / `transform:` | See the whole hash, so any check you can write in Ruby still applies |
 | `model:` | The field maps onto a column like a scalar does, so the [drift guard](#the-schema-drift-guard) still catches a dropped `metadata` column |
-| `sensitive:` / `nullable:` / `message:` / `desc:` / `default:` / `example:` | Behave as on any other field (`default:`/`example:` must be a hash, and are checked against the field's own bounds at class load) |
+| `sensitive:` / `nullable:` / `message:` / `desc:` / `default:` / `example:` | Behave as on any other field (`default:`/`example:` must be a hash holding no NaN or Infinity, and are checked against the field's own bounds at class load) |
 
 Bounding it matters more than it looks: an unbounded `jsonb` column is where clients put megabytes and 200-level-deep objects. `max_depth:` and `length:` are how a contract says "opaque, but not unlimited" — which is strictly more than `permit(metadata: {})` can say.
 
@@ -773,6 +773,12 @@ Exported [OpenAPI](#exporting-openapi-docs-that-cannot-drift) tells the truth ab
 
 Every failure raises `Permittable::InvalidParameters`, carrying `details` (an array of `{ param:, code: }`, plus a `message:` when the field [declares one](#custom-error-messages-message)) and a `status`. On a real controller it is auto-rescued into the error envelope shown at the [top of this README](#permittable).
 
+Rails searches `rescue_from` handlers from the last declared to the first, so a catch-all such as `rescue_from StandardError` declared *after* `include Permittable` answers an invalid request first, and the client gets that handler's response instead of the 422 or 400. Either declare the catch-all before the include, or re-declare the gem's handler after it:
+
+```ruby
+rescue_from Permittable::InvalidParameters, with: :render_invalid_parameters
+```
+
 | Code | Raised when |
 |---|---|
 | `missing` | A required field is absent, or the `root:` key is absent (that one is a **400**) |
@@ -904,7 +910,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. **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 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. **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.
 
@@ -1015,6 +1021,8 @@ If this parameter is not backed by a column, declare it with virtual: true.
 
 The error carries a ready-to-paste migration command, typed from your own field declaration.
 
+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.
+
 #### Checking types too (opt-in)
 
 A dropped column fails the deploy; a **retyped** one doesn't, unless you ask:
@@ -1241,7 +1249,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:
+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.
 
 ```sh
 bin/rails permittable:audit             # the table plus a summary
@@ -1288,7 +1296,7 @@ A `config.exceptions_app = routes` setup (`match "/404", to: "errors#not_found",
 
 Under `[strict]` the task aborts on these rows. Either route the catch-all GET-only, as above, or add `application#not_found` to the [ignore list](#ignoring-controllers-and-actions). Don't declare a contract on the catch-all to silence the gate. Under monitor mode it validates eagerly, so a malformed JSON POST answers 400 instead of 404. The OpenAPI export would also gain a fake `/{path}` endpoint.
 
-The table lists a row for every verb on every path; the summary counts routes. A route with an optional segment, such as anything under `scope "(:locale)"`, lists each path it expands to (`/users` and `/{locale}/users`), but it is one route, so one unguarded `POST` counts once and the summary line says `N routed actions in M rows`. Rows are collapsed by controller, action, route index and verb; the index is a position within one `rails_routes` call, so audit concatenated route lists (an app's and an engine's) separately, or give them distinct `route:` values. Two separate routes to the same action (`post "/users"` and `post "/admin/users"`) count as two, because each one is a way in.
+The table lists a row for every verb on every path; the summary counts routes. A route with an optional segment, such as anything under `scope "(:locale)"`, lists each path it expands to (`/users` and `/{locale}/users`), but it is one route, so one unguarded `POST` counts once and the summary line says `N routed actions in M rows`. Rows are collapsed by controller, action, route index and verb; the index is a position within one `rails_routes` call (a route reached through a mounted engine is `[mount, route]`; see below), so a caller that concatenates route lists itself should pass `engines: false` for each, and audit them separately or give them distinct `route:` values. Two separate routes to the same action (`post "/users"` and `post "/admin/users"`) count as two, because each one is a way in.
 
 Controllers that never included `Permittable` are audited too — those are the ones worth finding. Everything is plain Ruby over the frozen registry plus route descriptors, so `Permittable::Audit.entries(controllers:, routes:)` works without Rails. It takes `ignore:` and `root:` too, which default to `Permittable.audit_ignore` and `Rails.root` (see below).
 
@@ -1312,7 +1320,9 @@ An entry is a controller path the way Rails routes it (the controller half of `b
 
 Assign the whole list. It is frozen, so add to it with `Permittable.audit_ignore += ["webhooks#receive"]`, which is validated too.
 
-**Controllers outside `Rails.root` are ignored by default.** These are engines and gems: ActiveStorage, ActionMailbox, Devise, and Rails' own `rails/*` controllers. An app can't keep a contract in a gem's controller. The audit locates a controller by the file that defines its class (`Module#const_source_location`). A gem installed inside the app still counts as a gem; `bundle config path vendor/bundle` does this, and so do CI caches. A controller whose source can't be located is audited. To audit gem controllers like your own:
+**Mounted engines are part of the app.** `mount Billing::Engine => "/billing"` makes every route the engine draws a URL of the app, so `rails_routes` follows each mounted Rails engine (nested ones too) and puts the mount's path in front of the engine's: an unguarded `POST /billing/refunds` fails `[strict]`, and a covered action in the engine is not reported as stale. A mount at a dynamic `at: ":tenant"`, or under `scope "(:locale)"` at `/blog`, joins like any other path. A mount whose path ends in an optional segment (`scope "(:locale)"` over a mount at `/`, or `at: "/m(/:slug)"`) lists the engine's routes with the segment only, as Rails does: it matches the mount's own path first, the segment present before absent, so `/posts` is the locale `posts` asking for the engine's root, and the engine's `/posts` is reached as `/{locale}/posts`. A constrained segment (`locale: /en|fr/`) keeps both. A mount's `via:` limits the verbs: `mount Shop::Engine, at: "/g", via: :get` leaves out the engine's `POST` routes, which answer 404. An engine mounted twice is two routes to its actions. Routes are judged in Rails' order with the mount standing where it is drawn: an app route ahead of the mount answers before the engine is asked, an engine route that matches answers and hides an app route behind the mount, and a request the engine has no route for goes on to the next route. A constrained mount, like any constrained route, hides no route behind it. A Rack mount that is not an engine (Sidekiq::Web, a lambda) has no routes to read and is skipped. `Permittable::OpenAPI.rails_routes(app, engines: false)` reads the app's own route set alone. One limit: a parameter name used by both the mount and an engine route (`/{id}/.../{id}`) is not renamed, so the template names it twice (`/t/{id}/{id}`) and the operation declares that one path parameter once.
+
+**Controllers outside `Rails.root` are ignored by default.** These are gems and engines installed as gems (an engine kept inside your app counts as yours): ActiveStorage, ActionMailbox, Devise, and Rails' own `rails/*` controllers. An app can't keep a contract in a gem's controller. The audit locates a controller by the file that defines its class (`Module#const_source_location`). A gem installed inside the app still counts as a gem; `bundle config path vendor/bundle` does this, and so do CI caches. A controller whose source can't be located is audited. To audit gem controllers like your own:
 
 ```ruby
 Permittable.audit_ignore_outside_root = false
@@ -1457,7 +1467,9 @@ Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
 
 Every operation references shared components for the [error envelope](#violations-and-error-responses): a `422` response always, plus a `400` when the contract declares a `root:`. So consumers get typed *errors*, not just typed inputs.
 
-**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a construct with no faithful ECMA-262 spelling is exported as `x-permittable-pattern` rather than a mistranslated `pattern`: a Ruby-only escape or flag, one ECMA-262 reads differently or refuses to compile at all (`{,3}`, `&&` in a class, a backreference, the word boundary `\b`), or one that cannot be carried once folded into the rest of its own character class (`\S` beside a member other than `\s`) — but **not** a hyphen right after a completed range (`[a-c-e]`), which both dialects read the same way and export unchanged. This also covers a regexp anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` at runtime and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`, and a rule's `finalize` block `x-permittable-finalize` (on the rule's own object, inside the `root:` wrapper when there is one, and on the operation too, so the marker survives an operation that has no request body); actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route — or whose path-and-verb slot another controller already claimed, which one document cannot represent twice, or whose route an earlier one shadows (below) — land in `x-permittable-controllers` instead of being dropped. A templated path segment is declared as a path `parameter` of type `string`, because the route set doesn't say what an `:id` is and the exporter won't invent it. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a construct with no faithful ECMA-262 spelling is exported as `x-permittable-pattern` rather than a mistranslated `pattern`: a Ruby-only escape or flag, one ECMA-262 reads differently or refuses to compile at all (`{,3}`, `&&` in a class, a backreference, the word boundary `\b`), or one that cannot be carried once folded into the rest of its own character class (`\S` beside a member other than `\s`) — but **not** a hyphen right after a completed range (`[a-c-e]`), which both dialects read the same way and export unchanged. This also covers a regexp anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` at runtime and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`, and a rule's `finalize` block `x-permittable-finalize` (on the rule's own object, inside the `root:` wrapper when there is one, and on the operation too, so the marker survives an operation that has no request body); actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route — or whose path-and-verb slot another controller already claimed, which one document cannot represent twice, or whose route an earlier one shadows (below) — land in `x-permittable-controllers` instead of being dropped. A templated path segment is declared as a path `parameter` of type `string` unless the contract says more, because the route set doesn't say what an `:id` is and the exporter won't invent it: a rootless contract's *scalar* field of the same name is that parameter's schema (see [Unknown parameters](#unknown-parameters) for what that does to the request body), minus any `default:` and `nullable:`, since the URL always supplies a non-null value. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+
+**Mounted engines are documented under their mount point.** The task follows each `mount Billing::Engine => "/billing"` into the engine's routes, so an engine's operations land in `paths` as `/billing/...` (a dynamic mount point becomes a `{tenant}` template). A Rack mount that is not an engine is skipped. See [Auditing coverage](#auditing-coverage-permittableaudit) for the details and the one limit on shared parameter names.
 
 **Paths are the URLs Rails dispatches.** An optional segment expands into each path it stands for, read the way Rails matches it: present before absent, left to right, constraints included. So `get "x(/:a)(/new)"` documents no `/x/new`, because Rails reads that URL as `a = "new"`, unless a constraint on `:a` rejects `"new"`. Rails squeezes a run of slashes to one before it matches, so a variant an absent leading group leaves with two in a row is no URL: `get "(:locale)(/:theme)"` documents `/`, `/{locale}` and `/{locale}/{theme}`, never `//{theme}`, and `get "(:locale(/:region))"` documents no `/`, which Rails answers with a 404. OpenAPI forbids two paths that differ only in their variable names, and two routes can produce them: under `scope "(:locale)"` a root is `/{locale}` and a `get ":slug"` is `/{slug}`. Such paths are one path, spelled as the route Rails tries first spells it. A later route under another verb is placed there too, and carries its own spelling in `x-permittable-path`. One under the same verb is shadowed: Rails sends that URL to the earlier route, and reaches the later one only when the earlier route's constraints turn the request away. It is listed in the earlier operation's `x-permittable-shadows` instead of being emitted as a second path, and its operation lands in `x-permittable-controllers` if it has no other path. A variant of one route that a constraint keeps reachable is listed the same way: `x(/:a)(/:b)` with `a: /\d+/` sends `/x/foo` to `:b`, so `/x/{a}` lists `/x/{b}`.
 
@@ -1588,7 +1600,7 @@ A bad contract is a programmer error, so it fails when the class loads — never
 - `length:` that isn't a non-negative `Integer` or a `Range`, or a `Range` with a negative or fractional end (`..-1`, `-2..3`, `1.5..3.5`; a whole-number Float such as `1..10.0` is fine; leave an end off, or use `Float::INFINITY`, for no bound); an `in:` that is a `String` (`String#include?` would match any substring — `in: "free pro"` accepted `"e"`), or that is neither a `Range` nor answers `include?`
 - An `in:` member the field's own type can't cast (`in: %w[1 two]` on an `:integer`, `nil` on a field that isn't `nullable:`, or a `Time` on a `:date` field that isn't exactly midnight UTC), or an `in:` `Range` whose endpoints a value of the field's type can't be compared with (`in: "1".."5"` on an `:integer`) — either would reject every request as `inclusion`
 - A bound **no value could satisfy**: a reversed or empty `Range` (`in: 65..18`, `length: 5..2`, `length: 3...3`), an empty `in:` set, or a `length:` of 0 on a `required` field (where `""` already violates as `missing`)
-- A `Time` `in:` member on a `:datetime` field finer than a nanosecond (`Time.at(1.1)`, a third of a second): a request's fraction is a finite decimal and the export prints nine digits, so no request could equal it
+- A `Time` `in:` member, `default:` or `example:` on a `:datetime` field finer than a nanosecond (`Time.at(1.1)`, a third of a second): a request's fraction is a finite decimal and the export prints nine digits, so no request could equal the member, and a published default or example would be a different instant
 - `validate:` or `transform:` that isn't callable
 - A `default:` or `example:` that violates its own field's contract, or an array `default:`/`example:` whose elements violate `of:` — or, for an array declared with a **block**, an element that isn't a hash the block would accept
 - A `default: nil` or `example: nil` on a field that isn't `nullable:`

data/lib/permittable/audit.rb

@@ -142,6 +142,22 @@ module Permittable
       end
     end
 
+    # Every controller class a Rails route can reach, for the rake tasks:
+    # ActionController::Metal and everything below it. The tasks used to
+    # collect ActionController::Base and ::API descendants only, so a bare
+    # Metal controller — the usual shape of a lean webhook endpoint, and a
+    # host this gem supports — had no audit row, never counted against
+    # [strict], and its contracts were missing from the export. Base and API
+    # 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
+      return [] unless defined?(::ActionController::Metal)
+
+      frameworks = %w[ActionController::Base ActionController::API]
+      ::ActionController::Metal.descendants.uniq.select { |controller| controller.name && !frameworks.include?(controller.name) }
+    end
+
     # The root a controller's source must be inside to be audited:
     # Rails.root, unless Permittable.audit_ignore_outside_root is off — or nil
     # without Rails, where there is no app to be outside of.

data/lib/permittable/authored_values.rb

@@ -103,6 +103,16 @@ module Permittable
       found
     end
 
+    # An authored :datetime Time must survive the export's nine digits, at
+    # any depth, as a scalar `default:` or `example:` must (see Coercion).
+    def permittable_check_scalar(field, value)
+      Coercion.refuse_finer_than_nanosecond(field[:type], super)
+    end
+
+    def permittable_cast_element(field, element)
+      Coercion.refuse_finer_than_nanosecond(field[:of], super)
+    end
+
     # Nor does it run an array-level validate:, which expects the transformed
     # sub-fields a request hands it. The validating read has already run it
     # on exactly those, so the stored read, which would hand it the
@@ -114,11 +124,13 @@ module Permittable
     # What a client sends has no defaults filled in: an omitted sub-field
     # stays omitted, at any depth, so the published example does not show a
     # value (`cents: 0`) that no client sends. The walker fills them in; drop
-    # exactly what it filled, by the walker's own absence rule.
+    # exactly what it filled, by the walker's own absence rule, judged on the
+    # hash the walker walked: one with the date parts read into their field.
     def permittable_check_hash(fields, hash, **)
       result = super
       return result unless @as_sent
 
+      hash = permittable_read_date_parts(fields, hash)
       fields.each do |field|
         key = field[:name].to_s
         next unless field.key?(:default)
@@ -130,6 +142,30 @@ module Permittable
       result
     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.
+    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
+
+      [status, read]
+    end
+
+    # Where the first NaN or infinite Float sits, as `a.b[1].c`, or nil.
+    def non_finite_path(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
+      end
+    end
+
     def permittable_violation(_field, param, code)
       { param: param, code: code.to_s }
     end

data/lib/permittable/column_guard.rb

@@ -49,6 +49,8 @@ module Permittable
 
       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)
+
           raise ArgumentError,
                 "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
                 "#{column_migration_hint(klass, field, types)}"
@@ -204,6 +206,37 @@ module Permittable
       klass.name || "Model"
     end
 
+    # `klass.column_names` leaves out `self.ignored_columns`, so an ignored
+    # column that IS in the database reads as missing. Raising stays right
+    # (`Model.new(field: ...)` raises UnknownAttributeError), but the
+    # migration the missing-column message teaches would duplicate it.
+    def ignored_column?(klass, field)
+      klass.respond_to?(:ignored_columns) && klass.ignored_columns.map(&:to_s).include?(field.to_s)
+    end
+
+    # The column may have been dropped since it was ignored, with its name
+    # left in ignored_columns; the table itself says which. That case needs
+    # different advice: removing the name would only lead to a migration
+    # that re-adds a column the app no longer wants.
+    def ignored_column_message(label, klass, field)
+      subject = "#{label}: '#{field}' is in #{model_expr(klass)}'s ignored_columns"
+      if column_in_table?(klass, field)
+        "#{subject} (table: #{klass.table_name}), so the model ignores that column " \
+          "and assigning it raises ActiveModel::UnknownAttributeError. " \
+          "Remove it from ignored_columns, or declare the field virtual: true if the app handles it itself."
+      else
+        "#{subject} but the table has no such column (table: #{klass.table_name}). " \
+          "Remove it from ignored_columns and the field from the contract, " \
+          "or declare the field virtual: true if the app handles it itself."
+      end
+    end
+
+    # Unlike `column_names`, the connection's own column list includes the
+    # columns the model ignores.
+    def column_in_table?(klass, field)
+      klass.connection_pool.with_connection { |connection| connection.column_exists?(klass.table_name, field) }
+    end
+
     def column_migration_hint(klass, field, types)
       type = types.is_a?(Hash) ? types[field.to_sym] : types
       column = [field, type].compact.join(":")

data/lib/permittable/open_api.rb

@@ -91,6 +91,54 @@ module Permittable
       @concern_methods ||= Permittable.public_instance_methods(false).map(&:to_s).freeze
     end
 
+    # Gems whose public methods are the framework's own: the ones a controller
+    # gets from the modules Rails mixes in (Rendering, Head, Callbacks, ViewPaths,
+    # Rescuable, ...) and from the class attributes those define on it.
+    FRAMEWORK_GEMS = %w[actionpack actionview activesupport activemodel railties].freeze
+
+    # Rails reads a controller's internal methods off its nearest abstract
+    # class: ActionController::Base includes all of those modules, so they are
+    # internal on a Base or API controller, but ActionController::Metal includes
+    # none, so on one built directly on it every public method of an included
+    # module is an action_methods entry. A method is the framework's when it
+    # is defined in one of its gems, by whichever module or class_attribute
+    # put it on the controller; a method the app defines, in the class or in a
+    # concern of its own, stays an action. So does one a superclass declares in
+    # its own file, even a framework controller's (Rails::HealthController#show):
+    # a method defined elsewhere in a gem, such as the class_attribute readers
+    # an app's parent class gets from the modules it includes, is not one.
+    def framework_method?(controller, action)
+      return false unless controller.respond_to?(:instance_method)
+
+      method = controller.instance_method(action)
+      file = method.source_location&.first
+      return false if file.nil? || framework_roots.none? { |root| file.start_with?(root) }
+
+      !declared_by_superclass?(method, controller, file)
+    rescue NameError
+      false
+    end
+
+    # Whether `method` is written in the file that defines its owner, a class
+    # other than the controller itself. An anonymous owner has no such file.
+    def declared_by_superclass?(method, controller, file)
+      owner = method.owner
+      owner.is_a?(Class) && owner != controller && !owner.name.nil? &&
+        Object.const_source_location(owner.name)&.first == file
+    end
+
+    # Resolved lazily, like concern_methods: the gems load after this file.
+    # Real paths, which is what source_location reports: a gem's own path is
+    # only expanded, so one reached through a symlink would never match.
+    def framework_roots
+      @framework_roots ||= FRAMEWORK_GEMS.filter_map do |name|
+        path = Gem.loaded_specs[name]&.full_gem_path or next
+        File.join(File.realpath(path), "")
+      rescue SystemCallError
+        File.join(path, "")
+      end.freeze
+    end
+
     # Shared `components` for any document referencing Permittable responses.
     #
     # Unlike a rule's monitor mode — which the exporter reads only from the
@@ -176,7 +224,8 @@ module Permittable
       return explicit unless contracts.any? { |rule| rule[:actions].empty? }
       return explicit + ["*"] unless controller.respond_to?(:action_methods)
 
-      explicit + (controller.action_methods.map(&:to_s).sort - explicit - concern_methods)
+      actions = controller.action_methods.map(&:to_s).sort - explicit - concern_methods
+      explicit + actions.reject { |action| framework_method?(controller, action) }
     end
 
     def operation_for(controller, action)
@@ -373,7 +422,7 @@ module Permittable
         else
           free.each do |path, verb, template|
             holder = (paths[path] ||= {})
-            placed = with_path_parameters(operation, path)
+            placed = with_path_parameters(operation, path, controller.permit_rule_for(action), template || path)
             holder[verb] = template ? placed.merge("x-permittable-path" => template) : placed
             slots << OperationSlot.new(holder, verb, verb, operation["operationId"], owner, path)
           end
@@ -488,23 +537,93 @@ module Permittable
     # OpenAPI 3.1 requires every variable in a path template to be declared as
     # a path parameter — a document templating {id} without declaring it is
     # invalid, which every member route produced. The route set does not say
-    # what an :id is and the exporter does not guess: a path segment arrives as
-    # a string, so that is what it is documented as.
-    def with_path_parameters(operation, path)
-      variables = path.scan(/\{(\w+)\}/).flatten
+    # what an :id is, so a variable is a string unless the contract says
+    # otherwise: a rootless contract field named like one is that parameter's
+    # schema (path_fields), and leaves the body schema.
+    #
+    # `own` is the route's own spelling of the template, which differs
+    # from `path` when collapse_shapes placed the route under another
+    # route's spelling: the same shape, so the names pair up by position.
+    def with_path_parameters(operation, path, rule, own = path)
+      # A name the path templates twice (a mount and an engine route both
+      # name `:id`) is declared once: OpenAPI forbids two parameters with
+      # one name and location.
+      variables = path.scan(/\{(\w+)\}/).flatten.uniq
       return operation if variables.empty?
 
+      own_names = own.scan(/\{(\w+)\}/).flatten
+      fields = path_fields(rule, path.scan(/\{(\w+)\}/).flatten.zip(own_names).uniq(&:first))
       parameters = variables.map do |name|
-        { "name" => name, "in" => "path", "required" => true, "schema" => { "type" => "string" } }
+        schema = fields[name] ? path_schema(fields[name]) : { "type" => "string" }
+        { "name" => name, "in" => "path", "required" => true, "schema" => schema }
       end
       # Inserted ahead of requestBody, where a reader of the document expects
       # it; emission stays deterministic either way.
       operation.each_with_object({}) do |(key, value), out|
-        out["parameters"] = parameters if key == "requestBody"
-        out[key] = value
+        if key == "requestBody"
+          out["parameters"] = parameters
+          value = body_without(rule, fields.values, own_names)
+        end
+        out[key] = value unless value.nil?
       end
     end
 
+    # { path variable => the contract's field for it }. Rails merges the
+    # route's path parameters over the request's, so a field the route fills
+    # from the URL is read from the URL, never from the body: `id` in the
+    # body is overwritten, and a request that leaves it out is fine. A rooted
+    # contract reads its fields from inside the root, which a path parameter
+    # never reaches, so only a rootless one has such fields, and only at its
+    # top level. `names` pairs each variable of the placed path with the
+    # route's own name for it.
+    #
+    # Only a scalar field moves. A URL segment is one string, so an array or
+    # a hash can never be what it carries (`POST /defs/1,2` against
+    # `array :id` is a 422). Such a field stays in the body, where a client
+    # can at least say what it means.
+    def path_fields(rule, names)
+      return {} if rule[:root]
+
+      names.filter_map do |variable, own|
+        field = rule[:fields].find { |f| f[:name].to_s == own }
+        [variable, field] if field && field[:kind] == :scalar
+      end.to_h
+    end
+
+    # A moved field's schema as the path parameter documents it. The URL
+    # always supplies the segment, so a `default:` never applies and the
+    # value is never null: `nullable:` would only add "null" to the type.
+    def path_schema(field)
+      JsonSchema.field(field.except(:default, :nullable))
+    end
+
+    # The requestBody for `rule` without the fields a path parameter took
+    # over; nil, to leave it out, when that was every field. Such a body
+    # would be an empty object. An action declared with no fields at all
+    # keeps the empty body it always had.
+    #
+    # `unknown: :error` forbids every key the contract does not declare, but
+    # the runtime exempts the route's path parameters from that check and
+    # then overwrites them with the URL's values: `PATCH /widgets/7` with
+    # {"id":7,"name":"x"} is a 200 whether or not the contract declares `id`.
+    # That is the payload a Rails form, or a client sending a record back,
+    # produces, so the schema must not forbid it. Each name the route
+    # templates therefore stays in the body as an unconstrained property,
+    # any value and never required, since the value is read from the URL and
+    # nothing in the body can make the request wrong. A rooted contract
+    # needs none of this: its wrapper object is permissive already.
+    def body_without(rule, moved, templated)
+      rest = rule[:fields] - moved
+      return if rest.empty? && !moved.empty?
+
+      body = rule_request_body(moved.empty? ? rule : rule.merge(fields: rest))
+      return body unless rule[:unknown] == :error && !rule[:root]
+
+      properties = body["content"]["application/json"]["schema"]["properties"]
+      templated.each { |name| properties[name] ||= {} }
+      body
+    end
+
     # Drops every descriptor for a verb and concrete path that an earlier,
     # unconstrained route already answers (rails_routes calls it last).
     # Journey sorts the routes matching a request by precedence, their
@@ -533,10 +652,13 @@ module Permittable
     #
     # Descriptors arrive in route order (then verb, then optional variant),
     # so the first one seen is the first route. Precedence is a property of
-    # ONE route set, which is why this runs inside each rails_routes call and
-    # not in the readers: an engine's routes are relative to its mount point,
-    # and a list concatenated from an app's and an engine's must not let one
-    # shadow the other.
+    # ONE route table, which is why this runs once inside each rails_routes
+    # call and not in the readers: a list concatenated from an app's and an
+    # engine's must not let one shadow the other. An engine followed from its
+    # mount is part of that one table, expanded where the mount is drawn, so
+    # an app route ahead of the mount hides the engine's route for the same
+    # slot and an engine route hides a later app one (see rails_routes). An
+    # engine route is unconditional only when its mount is as well.
     #
     # Two more limits, both towards listing more. Only identical templates
     # are compared, so templates that differ at all, even only in a
@@ -616,9 +738,77 @@ module Permittable
     # A verb on a path that an earlier, unconstrained route already answers
     # is left out: Rails never dispatches it to the later route (see
     # drop_shadowed).
-    def rails_routes(app)
-      descriptors = app.routes.routes.each_with_index.flat_map do |route, index|
+    #
+    # A mounted Rails engine is part of the application: `mount Billing::Engine
+    # => "/billing"` makes every route the engine draws a URL of the app, so
+    # the audit's gate and the export must see them. With `engines: true`
+    # (the default) each such mount is followed into the engine's own route
+    # set, and the mount's path is put in front of every path found there,
+    # token by token, so a mount under `scope "(:locale)"`, one at a
+    # dynamic `at: ":tenant"` and one at "/" expand and join exactly as an
+    # app route would. A route reached through a mount carries its position
+    # as an Array, `[mount, route]` (`[3, 0, 5]` through an engine mounted in
+    # an engine), where an app route carries a bare Integer; so one engine
+    # mounted twice is two routes to its actions, as it is to a client. Only
+    # a Rails engine is followed: a Sidekiq::Web or a proc has no route set
+    # of ours to read and is skipped, as it always was. `engines: false`
+    # reads the one route set alone, for a caller that concatenates the lists
+    # of an app and its engines itself.
+    #
+    # Rails tries the routes in order with a mount standing where it is
+    # drawn, so the engine's routes are judged in that one order with the
+    # app's (see drop_shadowed): an app route ahead of the mount answers
+    # before the engine is asked, an engine route that matches answers and
+    # leaves an app route behind the mount unreached, and only a request the
+    # engine has no route for goes on (X-Cascade). A mount's `via:` limits
+    # the verbs it hands over: another verb is passed on, never answered by
+    # the engine.
+    #
+    # A parameter the mount and an engine route both name (`/{id}/.../{id}`)
+    # is not renamed: the template names it twice, the operation declares it
+    # once, and the README says so.
+    def rails_routes(app, engines: true)
+      drop_shadowed(collect_routes(app.routes, engines: engines, prefixes: [Prefix.new([], [])], parents: [],
+                                               visiting: [].freeze, reachable: true))
+    end
+
+    # What a route set mounted at one variant of its mount's path is led by.
+    # `tokens` are the mount's path from the root (see join_paths).
+    # `shadowed_by` are the paths of the variants Rails tries first, which
+    # leave this one nothing that they accept: a mount at "/" under
+    # `scope "(:locale)"` is matched as `/{locale}` before it is matched as
+    # "/", so /posts is the locale "posts" asking for the engine's root, and
+    # the engine's own /posts is not reached through the second variant. The
+    # mount's path is matched as a whole, unanchored and with no way back
+    # into it once the engine has been asked, so a variant that fits the
+    # leading segments of a path takes it whether or not the engine has a
+    # route for the rest.
+    Prefix = Struct.new(:tokens, :shadowed_by)
+
+    # The descriptors of one route set (`set`, anything with `routes`), each
+    # path led by every one of `prefixes` (a Prefix for each variant of the
+    # mounts above it, one empty one at the top) and each `route:` led by
+    # `parents`. `reachable` is whether every mount above answers every
+    # request for its path (see unconditional?); a route behind one that
+    # does not may be passed over, so it hides nothing. `visiting` is the
+    # route sets above this one, so an engine that mounts itself, or an app
+    # and engine that mount each other, ends the walk instead of recursing
+    # for good. Rails would loop on such a request too; the audit must not
+    # hang on it.
+    #
+    # The descriptors still carry `unconditional:`; the caller runs
+    # drop_shadowed over the whole list, mounts expanded in place.
+    def collect_routes(set, engines:, prefixes:, parents:, visiting:, reachable:)
+      visiting += [set]
+      set.routes.each_with_index.flat_map do |route, index|
+        id = parents.empty? ? index : parents + [index]
         requirements = route.requirements
+        if engines && (mounted = mounted_routes(route)) && visiting.none? { |above| above.equal?(mounted) }
+          found = collect_routes(mounted, engines: engines, prefixes: mount_prefixes(prefixes, route), parents: Array(id),
+                                          visiting: visiting, reachable: reachable && unconditional?(route))
+          verbs = route.verb.to_s.downcase.split("|")
+          next verbs.empty? ? found : found.select { |descriptor| verbs.include?(descriptor[:verb]) }
+        end
         verb = route.verb.to_s
         next [] if requirements[:controller].nil? || requirements[:action].nil?
 
@@ -627,9 +817,9 @@ module Permittable
         # audit entirely. Expand it into the verbs it actually answers.
         verb = ALL_VERBS if verb.empty?
 
-        variants = optional_variants(route.path.spec, requirements)
+        variants = optional_variants(route.path.spec, requirements, prefixes)
         # Read once per route; drop_shadowed reads it, then strips it.
-        unconditional = unconditional?(route)
+        unconditional = reachable && unconditional?(route)
         # One route can answer several verbs (`match via: [:patch, :put]`, and
         # the PATCH|PUT pair resources generates); documenting only the first
         # dropped the others from the export entirely. Verb by verb, then
@@ -638,12 +828,47 @@ module Permittable
         verb.split("|").flat_map do |single|
           variants.map do |path, shadows|
             descriptor = { controller: requirements[:controller], action: requirements[:action],
-                           verb: single.downcase, path: path, route: index, unconditional: unconditional }
+                           verb: single.downcase, path: path, route: id, unconditional: unconditional }
             shadows.empty? ? descriptor : descriptor.merge(shadows: shadows)
           end
         end
       end
-      drop_shadowed(descriptors)
+    end
+
+    # The Prefix of each variant of a mount's path under each of `prefixes`,
+    # outermost mount first, and within a mount present before absent, which
+    # is the order Rails' regexp tries them in. A variant is shadowed by every
+    # variant ahead of it: those of the same mount, and (through the
+    # `shadowed_by` it inherits) those of a mount above, judged where each
+    # was matched.
+    def mount_prefixes(prefixes, route)
+      own = variant_tokens(route.path.spec, route.requirements)
+      prefixes.flat_map do |above|
+        own.each_with_index.map do |tokens, index|
+          Prefix.new(join_paths(above.tokens, tokens),
+                     above.shadowed_by + own.take(index).map { |earlier| join_paths(above.tokens, earlier) })
+        end
+      end
+    end
+
+    # The route set a mount route hands requests to, or nil for any other
+    # route. Rails itself asks `route.app.engine?` (RoutesInspector does)
+    # and reads the set off `rack_app`. A route that cannot answer, such as a
+    # hand-built duck, is not a mount.
+    def mounted_routes(route)
+      return unless route.respond_to?(:app) && route.app.respond_to?(:engine?) && route.app.engine?
+
+      engine = route.app.rack_app
+      engine.routes if engine.respond_to?(:routes)
+    end
+
+    # `outer` then `inner`, as one path: the slash the mount ends in and the
+    # one the inner path starts with are one slash, and a route to the
+    # engine's root ("/") adds nothing to the mount's own path.
+    def join_paths(outer, inner)
+      inner = inner.drop(1) if outer.last == "/" && inner.first == "/"
+      inner = [] if inner == ["/"] && !outer.empty?
+      join_literals(outer + inner)
     end
 
     # A route parameter as optional_variants reads it: a `:name` segment or a
@@ -704,13 +929,23 @@ module Permittable
     # string: `to_s` prints an escaped parenthesis in a literal as a bare
     # one, which a string scan then read as a group. A Journey-shaped stand-in
     # may carry a String spec instead (string_variants).
-    def optional_variants(spec, requirements = {})
-      variants = if spec.respond_to?(:type)
-                   tree_variants(spec, requirements)
-                 else
-                   string_variants(spec.to_s.sub(FORMAT_GROUP, ""), requirements).first
-                 end
-      variants = variants.map { |tokens| join_literals(tokens) }
+    #
+    # `prefixes` are the Prefix of each variant of the mounts the route sits
+    # under (one empty one, none, by default). Each is put in front of every
+    # variant, the mount's variants outermost, which is the order Rails'
+    # regexp tries them in; a path a mount variant ahead of its own takes
+    # first is left out (see Prefix), and the shadowing above then judges the
+    # rest.
+    def optional_variants(spec, requirements = {}, prefixes = [Prefix.new([], [])])
+      # The route's own variants are judged before a mount's path is put in
+      # front of them: an empty one (`(:locale(/:region))` with nothing
+      # present) is no request path, but joined onto a mount it would read as
+      # the mount's own path, which Rails does not hand to that route.
+      own = variant_tokens(spec, requirements).select { |tokens| request_path?(tokens) }
+      variants = prefixes.flat_map do |prefix|
+        own.map { |tokens| join_paths(prefix.tokens, tokens) }
+           .reject { |joined| prefix.shadowed_by.any? { |earlier| shadowed?(earlier, joined.first(earlier.length)) } }
+      end
       # No group, no choice: nothing for one variant to shadow.
       return { render(variants.first) => [] } if variants.one?
 
@@ -732,6 +967,17 @@ module Permittable
       kept.to_a.reverse.to_h
     end
 
+    # The variants of a path spec, each a list of tokens with adjacent text
+    # joined (see join_literals), before any is dropped as shadowed.
+    def variant_tokens(spec, requirements)
+      variants = if spec.respond_to?(:type)
+                   tree_variants(spec, requirements)
+                 else
+                   string_variants(spec.to_s.sub(FORMAT_GROUP, ""), requirements).first
+                 end
+      variants.map { |tokens| join_literals(tokens) }
+    end
+
     # A Journey tree's variants, each a list of tokens: literal text and
     # Param. A group yields its contents' variants, then the empty one —
     # present before absent, as Rails' regexp tries them — except the

data/lib/permittable/tasks/audit.rake

@@ -11,12 +11,10 @@ namespace :permittable do
   task :audit, [:strict] => :environment do |_t, task_args|
     Rails.application.eager_load!
 
-    bases = []
-    bases << ActionController::Base if defined?(ActionController::Base)
-    bases << ActionController::API if defined?(ActionController::API)
     # Every controller, not just the ones including Permittable — a controller
-    # that never included it is unguarded, which is exactly the finding.
-    controllers = bases.flat_map(&:descendants).uniq.select(&:name)
+    # 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
     routes = Permittable::OpenAPI.rails_routes(Rails.application)
 
     entries = Permittable::Audit.entries(controllers: controllers, routes: routes)

data/lib/permittable/tasks/generate.rake

@@ -12,10 +12,7 @@ namespace :permittable do
   task :generate, [:controller] => :environment do |_t, task_args|
     Rails.application.eager_load!
 
-    bases = []
-    bases << ActionController::Base if defined?(ActionController::Base)
-    bases << ActionController::API if defined?(ActionController::API)
-    controllers = bases.flat_map(&:descendants).uniq.select(&:name)
+    controllers = Permittable::Audit.rails_controllers
 
     # { controller => actions to leave out of its draft }. A named controller
     # is drafted even if covered or ignored; the sweep skips both, and leaves

data/lib/permittable/tasks/openapi.rake

@@ -15,10 +15,7 @@ namespace :permittable do
   task :openapi, [:output] => :environment do |_t, task_args|
     Rails.application.eager_load!
 
-    bases = []
-    bases << ActionController::Base if defined?(ActionController::Base)
-    bases << ActionController::API if defined?(ActionController::API)
-    controllers = bases.flat_map(&:descendants).uniq.select do |controller|
+    controllers = Permittable::Audit.rails_controllers.select do |controller|
       controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any?
     end
 

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.12.0".freeze
+  VERSION = "0.13.1".freeze
 end

data/lib/permittable.rb

@@ -1046,9 +1046,31 @@ module Permittable
     # with a time of day always got. Shared by cast_date and
     # instant_as_date, so a value and an in: member cannot be read
     # differently; and always a plain Date, never the DateTime it came as.
+    #
+    # Built from the UTC components, as a String is (cast_date), not with
+    # Time#to_date: that keeps the instant's day NUMBER and labels it in the
+    # Julian calendar before the 1582 reform, so Time.utc(1500, 1, 1) came
+    # out as 1499-12-23 while "1500-01-01" was 1500-01-01.
+    #
+    # A day the 1582 reform skipped (1582-10-05..14) is no Date, as the String
+    # "1582-10-10" is none, so it is nil here and every caller gives its usual
+    # error. :datetime is proleptic Gregorian and does accept those days; the
+    # two differ there by design, :date being the String path's calendar.
+    #
+    # A DateTime is read by its own civil day, not through #to_time: stdlib's
+    # converts by day number, so outside Rails (ActiveSupport converts by
+    # component) a DateTime before 1582 landed 9 days late.
     def date_of_instant(instant)
-      utc = instant.to_time.getutc
-      utc.to_date if utc == utc.beginning_of_day
+      if instant.is_a?(DateTime)
+        utc = instant.new_offset(0)
+        return unless utc.hour.zero? && utc.minute.zero? && utc.second.zero? && utc.sec_fraction.zero?
+      else
+        utc = instant.to_time.getutc
+        return unless utc == utc.beginning_of_day
+      end
+      return unless Date.valid_date?(utc.year, utc.month, utc.day)
+
+      Date.new(utc.year, utc.month, utc.day)
     end
 
     # A zoneless String parses as UTC regardless of the host timezone
@@ -1241,11 +1263,34 @@ module Permittable
       return instant_as_date(member) if type == :date && (member.is_a?(Time) || member.is_a?(DateTime))
 
       status, value = cast(type, member)
-      return [status, value] unless status == :ok && type == :datetime && !member.is_a?(String) && !whole_nanoseconds?(value)
+      return [status, value] unless status == :ok && finer_than_nanosecond?(type, member, value)
 
       [:error, "finer than a nanosecond, so it never equals a request; round it, e.g. with .round(9)"]
     end
 
+    # Whether `raw`, authored as a Time-like `in:` member of a :datetime
+    # field and cast to `cast_value`, holds more than the nine digits the
+    # export prints. A String `in:` member is exempt: it is cast exactly as a
+    # request sending it is, and published as written (see
+    # published_in_member), so whatever precision it spells is reachable.
+    def finer_than_nanosecond?(type, raw, cast_value)
+      type == :datetime && !raw.is_a?(String) && !whole_nanoseconds?(cast_value)
+    end
+
+    # An authored `default:` or `example:` is held to the same rule as an
+    # `in:` member: the exported schema prints it to nine digits, so a value
+    # finer than that was published as a different instant than the action
+    # got for an omitted field, and a client sending the published default
+    # was not sending the default. Unlike an `in:` member, a String is NOT
+    # exempt here: a default or example is stored as the cast Time and
+    # exported from that, never as written, so "...00.1234567891Z" printed
+    # as .123456789Z. `outcome` is the cast's [status, value].
+    def refuse_finer_than_nanosecond(type, outcome)
+      return outcome unless outcome.first == :ok && type == :datetime && !whole_nanoseconds?(outcome.last)
+
+      [:error, "finer than a nanosecond, so the export publishes a different instant; round it, e.g. with .round(9)"]
+    end
+
     # A request's fraction of a second is a finite decimal, and the export
     # prints a member to at most nine digits, so a member that is not a whole
     # number of nanoseconds — Time.at(1.1) holds 1.10000000000000008881...,
@@ -1267,7 +1312,7 @@ module Permittable
     # class-load error a reason where a request gets `invalid_type`.
     def instant_as_date(member)
       date = date_of_instant(member)
-      date ? [:ok, date] : [:error, "not midnight UTC, so it never equals a date"]
+      date ? [:ok, date] : [:error, "not midnight UTC of an existing day, so it never equals a date"]
     end
 
     # What an exported enum lists for one member: the cast value, re-encoded
@@ -1885,7 +1930,9 @@ module Permittable
       # proc cannot rewrite the host's own literal.
       authored = field[opt].is_a?(String) ? field[opt].dup : field[opt]
       value = Coercion.apply_normalize(field[:normalize], authored)
-      status, result = Coercion.check_scalar(live_in?(field) ? field.except(:in) : field, value)
+      status, result = Coercion.refuse_finer_than_nanosecond(
+        field[:type], Coercion.check_scalar(live_in?(field) ? field.except(:in) : field, value)
+      )
       raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{result})" unless status == :ok
 
       field[opt] = freeze_authored(opt == :default && field[:transform] ? field[opt] : result)
@@ -2758,7 +2805,7 @@ module Permittable
     case field[:kind]
     when :scalar
       # Already normalized by permittable_normalized, before the absence rule.
-      permittable_check_whole(field, Coercion.check_scalar(field, value), full, result, violations: violations)
+      permittable_check_whole(field, permittable_check_scalar(field, value), full, result, violations: violations)
     when :json
       permittable_check_whole(field, permittable_check_json(field, value), full, result, violations: violations)
     when :nested
@@ -2883,7 +2930,18 @@ module Permittable
     field[:transform] ? field[:transform].call(value) : value
   end
 
-  # A second seam, for the same reader: the array-level `validate:` to run.
+  # More seams, for the same reader: how a scalar field's value, and an
+  # array element, are cast. A request's are cast as they come; an authored
+  # default: or example: is also held to the nine digits the export prints.
+  def permittable_check_scalar(field, value)
+    Coercion.check_scalar(field, value)
+  end
+
+  def permittable_cast_element(field, element)
+    Coercion.cast(field[:of], element)
+  end
+
+  # A third seam, for the same reader: the array-level `validate:` to run.
   def permittable_array_validator(field)
     field[:validate]
   end
@@ -2898,7 +2956,7 @@ module Permittable
                                     path: path, unknown: unknown, top_level: false, violations: violations)
     end
 
-    status, out = Coercion.cast(field[:of], permittable_own(element))
+    status, out = permittable_cast_element(field, permittable_own(element))
     return out if status == :ok
 
     violations << permittable_violation(field, path, out)

metadata

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