permittable 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24ca6a6f3f19fec065cb3ac2edcc255131e0b3e6093b1a0f1b860b31a9798597
-  data.tar.gz: 639aa236702384c0762a5ee694835115fdbd9ed677bf16824bff4618f1aa6cb9
+  metadata.gz: 9f13494f2345ced22c261510fd65e89b855b263931a423e6abfb3acb9c3df605
+  data.tar.gz: b88b5cad51b572acabe91453a322869d3167671854f37f8ec27cd80b2454d361
 SHA512:
-  metadata.gz: 852e4234d867bda50477812978c1327132b87e76297fddf9f53d5a62b5e65545bf76bb2955dc2f0deb0fc3a4a547b88ca782a8a12fc03cb3ac7287f78f07c869
-  data.tar.gz: 7b850f5b1cc806cf3044c4fb27dcd59f270ff8d0a504ab5fd8e757d9d284df8c03e9182aafffd1e9c538524798e6620b76c621890832e5656dc29b9ae1c4b70a
+  metadata.gz: f3255855aee7d875af804e0984e3b1939b4018a3d4e51134e15ea61ad53fbcc549e6ec9464ffcc158d5b0a64a0e140a34806b7e37abd24f1b66fa5fbec88bec1
+  data.tar.gz: 658e22032c03f6413ad6343d20a8d493c07158975fea4223cac3fcda3a3db71c119d17f4744f79e1c53982560019b8690be6b03dad7a1f7e3cfe1ca68672d414

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 <!-- CHANGELOG.md -->
 
+## 0.7.0 (2026-09-16)
+<!-- title: sensitive: redaction, uncorruptible defaults, and stricter class load -->
+
+Two silent disclosures and three silent corruptions, all in code that was doing its job wrongly rather than not at all: `sensitive:` redacted nothing unless the value was a String, a swapped filter registry stopped being consulted, a mutable `default:` was shared by every request in the process, `normalize:` could manufacture an empty value that walked past `required`, and `unknown: :error` rejected the keys Rails itself adds to a form POST. Contract mistakes that could only ever fail at request time now fail at class load instead.
+
+### Fixed
+- **Swapping `Permittable.filter_parameter_registry` silently stopped `sensitive:` redaction.** `Permittable::Railtie` appended `filter_parameter_registry.to_proc` — a proc bound to whichever registry instance existed **at boot**. Rails runs railtie initializers *before* `config/initializers`, so a host gem or app that swaps the registry necessarily does so afterwards, leaving Rails filtering through the old instance: `sensitive:` fields registered themselves in the new registry, and the appended proc went on consulting an empty one. The parameter was logged in the clear, with nothing to indicate it. That swap is the reason the writer exists — the gem's own comment names `concerns_on_rails` as doing exactly this — so the broken ordering was the normal case rather than an exotic one. The Railtie now appends `Permittable.filter_parameter_proc`, which resolves the registry at **filter time**; it is one frozen object for the life of the process, so the Railtie's idempotence check still holds across repeated initializer runs.
+- **`sensitive:` redacted nothing unless the value was a String.** The mechanism was a proc filter, and ActiveSupport's `ParameterFilter` dups the value before invoking one and expects in-place mutation — so `optional :pin, :integer, sensitive: true` logged `1234` in the clear, and `sensitive: true` on a nested block logged the whole hash, since `ParameterFilter` checks `value.is_a?(Hash)` *before* the proc filters and recurses into it instead of ever calling them. Both are silent disclosures of exactly the fields a contract marked as the ones not to print. Each registered name is now **also added to `config.filter_parameters` by name**, which redacts a value of any type, while the proc stays for what only it can reach (consumers that snapshot the array at boot). A real Rails boot covers an `:integer` field, a sensitive nested block, and `#inspect`, with `precompile_filter_parameters` on — the modern default, and the reason the mechanism has to be a name rather than a live matcher object: precompilation joins filters by pattern source and discards anything whose matching is decided at filter time. `Permittable.on_sensitive_parameter` is the seam the Railtie installs, so the registry itself stays free of Rails.
+- **A mutable `default:` was shared by every request.** Field declarations are frozen data, but the *value* an author wrote for `default:` was not, and `HashWithIndifferentAccess` hands a non-frozen Array — and any String — to the result **by reference**. So `array :tags, of: :string, default: []` gave every request the same Array: one request appending to `permitted_params[:tags]` corrupted the default for every later request in the process, and `Model.new(tags: …)` assigns that same object, so `record.tags << x` was enough to trigger it. The corruption outlived the request and lasted for the life of the process. A `default:` (and a documentation `example:`) is now **deep-copied and frozen at class load**, so the contract cannot be corrupted, and each request is handed its own copy. The copy is the point: the object the host app passed in is never frozen, in case it is still using it.
+- **`normalize:` could manufacture an empty value that walked past `required`.** `""` is documented as absent, so a required field must violate — but normalization ran *after* absence had already been decided. `required :name, :string, normalize: :squish` therefore rejected `""` as `missing` and **accepted `"   "` as `""`**, writing an empty string into the column: exactly the silent corruption strict coercion exists to refuse, delivered by the gem's own preset. `normalize:` now runs **first**, before the absence rule, so a value that normalizes to empty is absent like any other empty value — it takes the `nullable:` / `default:` / `missing` branch. There is still exactly one reading of absence, and a `normalize:` Proc is still called exactly once per value. Relatedly, a `default:` is now **stored** in the form it was validated in: `default: "  free  "` with `normalize: :squish` was checked as `"free"` and used to be handed to requests as `"  free  "`.
+- **`unknown: :error` rejected ordinary form submissions.** Only the router's `controller`/`action`/`format` were exempt from the top-level unknown-key check, but Rails also merges `authenticity_token`, `_method`, `utf8` and `commit` into a form POST — so the strictest setting was unusable outside a JSON API, and every browser form failed on four of the framework's own keys rather than on anything the client got wrong. Those four are now exempt at the top level too. The exemption covers the *check* only, and only at the top level: a form key smuggled inside a `root:` or a nested hash is still `unknown`, a standalone `Permittable::Contract` still exempts nothing (it has neither a router nor a form), and monitor mode still passes the form keys through in its raw hash, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `_method` itself.
+- **An exported `pattern` could be stricter than the rule the server enforces.** Ruby's `^` and `$` anchor a **line**; ECMA-262's, without the `m` flag, anchor the whole string. So `format: /^\d{5}$/` accepts `"evil\n12345"` at runtime while the exported `"pattern": "^\\d{5}$"` rejects it — the documentation and the enforcement disagreeing, which is the one thing an export from contract data is meant to make impossible. Such a regexp now joins the constructs that stay visible as `x-permittable-pattern` instead of being mistranslated, alongside `\Z`, `\h` and the POSIX classes. Straight after `[` neither one is an anchor — `^` is class negation and `$` a literal — so `[^a]` and `[$]` still translate, as does an escaped `\$` or `\^`. `\A`/`\z` translate exactly and remain the anchors to reach for.
+
+- **A block array's `default:` was checked against a different reading of absence than the request it stands in for.** `""` is absent, so a client sending `items: [{ "sku" => "" }]` is refused with `items[0].sku missing` — but the class-load check for a block array's `default:` treated only `nil` as absent, so `default: [{ "sku" => "" }]` was accepted, and a `default:` is applied **without revalidation**: every request that omitted the key was handed the exact value the contract refuses from a client. The same held for a value that normalizes to empty, because the check normalized *after* deciding absence rather than before. That check now reads absence the way the walker does — normalize first, then `nil`/`""`, with `nullable:` splitting the rule for an explicitly-empty value exactly as it does at request time — and the value half of that rule is now one shared predicate rather than two spellings of it.
+
+Contracts that declare no `default:`, no `normalize:`, and no `unknown: :error` are unaffected.
+
+### Added
+- **Swapping the registry now carries the entries it already holds into the new one.** Late-binding the proc fixes redaction for contracts that load *after* a swap, but on its own it breaks the other half: nothing consults the outgoing registry again, so a `sensitive:` field registered by a contract that loaded *before* the swap would have stopped being redacted — the exact mirror image of the bug above, and the case a host gem pooling registrations is most likely to hit, since eager loading in production loads plenty of controllers before `config/initializers` runs. `Permittable.filter_parameter_registry=` now re-adds each name from the outgoing registry (read through a new duck-typed `#names`) to the incoming one, and a real Rails boot covers both halves.
+- **`Permittable.filter_parameter_registry=` validates what it is given.** A registry with no `#to_proc` used to be accepted silently and simply never consulted; with the proc late-bound it would instead have raised `NoMethodError` inside `process_action` on every request. It now raises `ArgumentError` at the point of the swap, naming the class. The registry's callable may take Rails' two-argument (`key, value`) or three-argument (`key, value, original_params`) proc-filter shape; both are dispatched by arity.
+
+### Changed
+- **A bound that no value could satisfy now fails at class load.** A reversed or empty `Range` excludes every value there is, so the field it bounds could never validate — and that surfaced as every request to the action failing on that field: a contract mistake reported to clients as their error, once per request, forever. `in: 65..18`, `length: 5..2`, `length: 3...3`, an empty `in: []`, a negative `length:`, and a `length:` of 0 on a `required` field (where `""` is absent and already violates as `missing`, so nothing is left to accept) are now `ArgumentError` at class load, naming the bound. Endless and beginless Ranges are legitimate and unaffected, as are endpoints that cannot be compared. **Breaking** for a contract that ships such a field, but only for one that was already failing 100% of the requests that reached it.
+- **An array declared with a block now checks its `default:` too.** `validate_array_authored_value!` only checked elements against `of:`, which is nil for a block array — so `array :items, default: [{ "nonsense" => true }] do required :sku, :string end` was accepted at class load and handed to every request that omitted the key, bypassing the contract the block declares. Elements are now checked against the block's own fields (required sub-fields present, scalar ones satisfying their own contract), the same shallow check `of:` gets. **Breaking** for a contract whose block-array default was already wrong, which previously returned that value rather than rejecting it.
+
+
+## 0.6.0 (2026-09-08)
+<!-- title: nullable fields, :json, and strict dates -->
+
+Two gaps in the field vocabulary closed and one guess removed. A contract can now say *clear this column* (`nullable:`) and *this hash has no shape, but it has bounds* (`:json`), and a date string must name the whole date instead of borrowing the missing parts from today. Contracts that use neither new option see only the date-parsing change, which is called out below.
+
+### Added
+- **`:json` field type — free-form hashes, the `jsonb` column case.** A `json`/`jsonb` column exists precisely so its contents need no schema, and every other field kind describes a shape. Until now a contract had only bad options for one: declare sub-keys you don't know, or leave the key undeclared — in which case the contract **silently dropped it** and the column never saw the data. Strong parameters has always had an answer (`params.permit(metadata: {})`); now so does a contract. `optional :metadata, :json` passes an arbitrary Hash through untouched — keys neither filtered nor cast, nested arrays and mixed scalars intact, `unknown:` deliberately not descending into it, `{}` a value rather than an absence, anything that is not a Hash an `invalid_type`. What it gives up is the shape; what it keeps is every bound worth having: **`length:`** caps the top-level key count, **`max_depth:`** caps container nesting with arrays counting as a level (violation code `depth`), `validate:`/`transform:` see the whole hash, and the field maps onto a column like a scalar does, so the schema-drift guard still catches a dropped `metadata` column. That matters more than it looks — an unbounded `jsonb` column is where clients put megabytes and 200-level-deep objects, and "opaque, but not unlimited" is strictly more than `permit(metadata: {})` can say. Values arrive as plain data, never `ActionController::Parameters`, so assigning straight to a `jsonb` attribute is safe. Exported as `{"type": "object"}` with `minProperties`/`maxProperties`, plus `x-permittable-max-depth` for the nesting bound JSON Schema has no keyword for.
+- **`permittable:generate` now drafts `json`, `jsonb` and `hstore` columns as `:json`** instead of leaving a TODO comment. Columns with no faithful representation at all (`binary`, geometry types) still become TODOs rather than guesses.
+
+- **`nullable:` field option — an explicit null is now part of a contract's vocabulary.** One absence rule (`nil` and `""` are both absent) is right for `PATCH` and wrong for the request that means *clear this*; `nullable: true` splits it in two for a single field. A key the client never sent stays **absent** — `default:` applies to it, a `required` field still violates `missing` — but a key sent **empty** (JSON `null`, or `""` from a form) is an explicit null and yields `nil` in the result, **ahead of the field's `default:`**, which is exactly what a `PATCH` clearing a column needs. Nothing is cast or checked for an explicit null: `in:`, `format:`, `length:`, `validate:`, and `transform:` never see a `nil` they didn't agree to handle. `required` + `nullable` reads as it does in SQL (the client must state the field; `null` is a legal statement), `default: nil` — legal only on a nullable field — gives the `PUT` reading where absence also means clear, and on arrays and nested blocks `nullable:` applies to the array or object itself, never its contents (a null *element* is still `invalid_type`). Exported JSON Schema / OpenAPI stays truthful: the field's `type` gains `"null"`, and a nullable `in:` set lists `null` in its `enum` (the one keyword that constrains the instance rather than a type). The RSpec matcher gains a `.nullable` chain, and `default: nil` / `example: nil` on a non-nullable field now fails at class load naming the fix, instead of the confusing `invalid_type`.
+
+Contracts that don't opt in are byte-for-byte unaffected: absence keeps its single meaning and nothing new appears in an exported schema.
+
+### Fixed
+- **`:date` and `:datetime` invented the parts a string left out, from today's date.** Coercion is documented as strict — "a value the type cannot faithfully represent is a violation, not a guess" — but it handed strings straight to `Date.parse`, which fills in what they omit from the current date: `"09/2026"` became the 1st of September, `"5th"` became the 5th of *this* month of *this* year, `"Sept"` became the 1st of September *this* year. The same request therefore meant different things on different days, which is a guess and a non-deterministic one. A `:date` or `:datetime` string must now name all three of year, month and day; which **format** it names them in is still `Date.parse`'s business, so every complete format it understands keeps working (`"2026-09-05"`, `"2026/09/05"`, `"Sep 5, 2026"`, `"5 September 2026"`). A `:datetime` may still omit the **time** part, which reads as midnight UTC as documented, but a string with only a time (`"10:30"`, previously *today* at 10:30) is now `invalid_type`. `Date`, `Time`, `DateTime` and `ActiveSupport::TimeWithZone` objects are unaffected.
+
+  This is a **behaviour change** for any endpoint that was relying on the fill-in, but the values it produced were not the ones the client meant, and an exported `"format": "date"` already promised RFC 3339 rather than `"5th"`.
+
 ## 0.5.2 (2026-09-06)
 <!-- title: Railtie coverage and a new README -->
 

data/README.md

@@ -179,7 +179,9 @@ Adopting on an existing API with live traffic? Skip ahead to [Adopting on a live
   - [The field DSL](#the-field-dsl)
   - [Field options](#field-options)
   - [Types and strict coercion](#types-and-strict-coercion)
+  - [Free-form hashes](#free-form-hashes-json)
   - [Absence, defaults, and partial updates](#absence-defaults-and-partial-updates)
+  - [Explicit nulls](#explicit-nulls-nullable)
   - [Violations and error responses](#violations-and-error-responses)
   - [Custom error messages](#custom-error-messages-message) · [Localizing with I18n](#localizing-default-messages-i18n)
   - [Unknown parameters](#unknown-parameters)
@@ -208,7 +210,7 @@ Adopting on an existing API with live traffic? Skip ahead to [Adopting on a live
 request params
    │
    ├─ 1  unwrap root:        params[:user]                missing or not a hash → 400
-   ├─ 2  each field          normalize → cast → validate → transform
+   ├─ 2  each field          normalize → absent? → cast → validate → transform
    ├─ 3  unknown-key check   at every nesting level       (unknown: :ignore | :log | :error)
    ├─ 4  finalize            only when nothing violated
    │
@@ -272,6 +274,9 @@ array :line_items, required: true do
   required :sku,      :string
   required :quantity, :integer, in: 1..99
 end
+
+# Free-form hashes — :json takes any hash, uncast and unfiltered, with bounds
+optional :metadata, :json, max_depth: 3, length: 0..32
 ```
 
 Arrays are **optional unless `required: true`**, and `length:` on an array constrains the element **count**.
@@ -285,17 +290,19 @@ Which options are legal depends on the field kind — anything else raises at cl
 | `in:` | ✅ | — | — | Allowed values: a `Range` (bounds-checked with `cover?`) or an `Array` |
 | `format:` | ✅¹ | — | — | Regexp the value must match |
 | `length:` | ✅¹ | ✅ | — | `Range` or `Integer`. Character count on strings, **element count** on arrays |
-| `normalize:` | ✅¹ | — | — | `:squish`, `:strip`, `:downcase`, `:upcase`, `:email`, or a Proc. Runs **before** the cast |
-| `default:` | ✅ | ✅ | — | Value used when the field is absent. Validated against the field's own contract at class load |
+| `normalize:` | ✅¹ | — | — | `:squish`, `:strip`, `:downcase`, `:upcase`, `:email`, or a Proc. Runs **first** — before the absence rule, so a value that normalizes to `""` is absent |
+| `default:` | ✅ | ✅ | — | Value used when the field is absent. Validated against the field's own contract at class load, then stored normalized and frozen (each request gets its own copy) |
 | `validate:` | ✅ | ✅ | — | Callable. Falsy fails as `"invalid"`; a returned `Symbol` becomes the violation code |
 | `transform:` | ✅ | ✅ | — | Callable applied **after** cast and validation — see [output reshaping](#output-reshaping-transform-and-finalize) |
 | `virtual:` | ✅ | ✅ | ✅ | Exempt this field from the schema-drift guard |
 | `sensitive:` | ✅ | ✅ | ✅ | Register the field name for [log redaction](#sensitive-parameters-and-log-redaction) |
 | `message:` | ✅ | ✅ | ✅ | Human-readable copy for violations on this field — a String, or a Hash of code → String. See [custom messages](#custom-error-messages-message) |
 | `of:` | — | ✅ | — | Element type for an array of scalars (default `:string`) |
+| `max_depth:` | — | — | — | `:json` fields only — maximum container nesting. See [free-form hashes](#free-form-hashes-json) |
 | `required:` | — | ✅ | — | Arrays are optional unless this is `true` |
 | `desc:` | ✅ | ✅ | ✅ | Documentation only — the field's `description` in [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) |
 | `example:` | ✅ | ✅ | — | Documentation only, but **validated against the field's own contract at class load**, like `default:` |
+| `nullable:` | ✅ | ✅ | ✅ | An explicitly-sent empty value yields `nil` instead of counting as absent — see [explicit nulls](#explicit-nulls-nullable) |
 
 ¹ `format:`, `length:`, and `normalize:` reason about characters and are **only valid on `:string` fields**. On any other type they would silently apply to an already-cast value, so declaring them raises at class load.
 
@@ -316,17 +323,49 @@ Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`.
 | `:float` | `Numeric`; any `Float()`-parseable string | `"abc"` |
 | `:decimal` | `Numeric` or `String` → `BigDecimal` | Unparseable strings |
 | `:boolean` | `true`/`false`, `"true"`/`"false"`, `"1"`/`"0"`, `1`/`0` | `"yes"`, `"on"`, `2` |
-| `:date` | `Date`; any `Date.parse`-able string | Unparseable strings |
-| `:datetime` | `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, `Date`, parseable strings | Unparseable strings |
+| `:date` | `Date`; a string naming a **complete** date, in any format `Date.parse` understands (`"2026-09-05"`, `"2026/09/05"`, `"Sep 5, 2026"`) | Unparseable strings, and **incomplete** ones (`"09/2026"`, `"5th"`, `"Sept"`) |
+| `:datetime` | `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, `Date`; a string naming a complete date, with or without a time | Unparseable strings, and any string without a complete date (`"10:30"`) |
+| `:json` | Any `Hash` — passed through uncast, see [free-form hashes](#free-form-hashes-json) | Arrays, scalars |
+
+**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.
 
-Two behaviours worth committing to memory:
+Two more behaviours worth committing to memory:
 
 - **Type confusion is a violation, not a 500.** A request of `?age[]=1` against a scalar `:integer` field yields `invalid_type`. Arrays, hashes, and nested `ActionController::Parameters` can never satisfy a scalar type, so the classic "`NoMethodError` on `[]`" crash is impossible.
 - **Datetimes are normalised to UTC.** A zoneless string parses as UTC regardless of the host timezone, which keeps behaviour deterministic across machines; explicit offsets are honoured and converted.
 
+### Free-form hashes (`:json`)
+
+A `json`/`jsonb` column exists precisely so its contents need no schema. Every other field kind describes a shape, so until `:json` a contract had only bad options for one: declare sub-keys you don't know, or leave the key undeclared — in which case the contract **silently dropped it**, and the column never saw the data. Strong parameters has always had an answer here (`params.permit(metadata: {})`); now so does a contract.
+
+```ruby
+permit_params :create, root: :user, model: User do
+  required :name,     :string
+  optional :metadata, :json, max_depth: 3, length: 0..32
+end
+```
+
+The hash passes through **untouched** — keys are neither filtered nor cast, nested arrays and mixed scalars survive, and `unknown:` does not descend into it. `{}` is a value, not an absence. Anything that is not a hash (an array, a string, a number) is `invalid_type`.
+
+What you give up is the shape. What you keep:
+
+| | |
+|---|---|
+| `length:` | Caps the **top-level key count** — same reading as an array's element count |
+| `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) |
+
+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.
+
+Values arrive as plain data (`HashWithIndifferentAccess`), never `ActionController::Parameters`, so assigning straight to a `jsonb` attribute is safe.
+
+In [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) the field is `{"type": "object"}` plus `minProperties`/`maxProperties`; JSON Schema has no nesting-depth keyword, so `max_depth:` stays visible as `x-permittable-max-depth` rather than being dropped or mistranslated.
+
 ### Absence, defaults, and partial updates
 
-`nil` and `""` are **both treated as absent** — the query-parameter convention, where an untouched form field arrives as an empty string. Boolean `false` is present.
+`nil` and `""` are **both treated as absent** — the query-parameter convention, where an untouched form field arrives as an empty string. Boolean `false` is present. `normalize:` runs *before* this rule, so a field declared `normalize: :squish` treats `"   "` as absent too: whitespace cannot satisfy a `required` field by becoming `""`.
 
 That single rule produces the behaviour you want from a `PATCH`:
 
@@ -336,10 +375,39 @@ That single rule produces the behaviour you want from a `PATCH`:
 | absent and **required** | a `missing` violation |
 | absent with a **`default:`** | the default — a defaulted field can never report `missing` |
 
-Declaring `required:` alongside `default:` is a class-load error, since a default implies optionality. And because absence and `nil` are the same thing here, **clearing a column to NULL is outside a contract's vocabulary** — do that explicitly in the action.
+Declaring `required:` alongside `default:` is a class-load error, since a default implies optionality. And because absence and `nil` are the same thing here, a plain field cannot clear a column to NULL — declare it [`nullable:`](#explicit-nulls-nullable) when it should.
 
 Defaults are checked against the field's own contract when the class loads, so `default: "gold"` on a field declared `in: %w[free pro]` fails at boot rather than on every request.
 
+### Explicit nulls (`nullable:`)
+
+One rule — `nil` and `""` are absent — is right for `PATCH` and wrong for the request that means *clear this*. `nullable: true` splits it in two for a single field:
+
+```ruby
+permit_params :update, root: :user, model: User do
+  optional :nickname, :string, nullable: true
+  optional :plan,     :string, in: %w[free pro], default: "free", nullable: true
+end
+```
+
+| Request | `nickname` in the result |
+|---|---|
+| `{ "user": {} }` | **omitted** — the column is untouched |
+| `{ "user": { "nickname": null } }` | `nil` — the column is cleared |
+| `{ "user": { "nickname": "" } }` | `nil` — the form-encoded spelling of the same intent |
+
+A key the client never sent is still **absent**: `default:` applies to it and a `required` field still violates with `missing`. Only *present-but-empty* changes meaning, and it changes it decisively — an explicit null wins over the field's `default:`, which is the behaviour a `PATCH` needs (`{ "plan": null }` clears the plan instead of silently resetting it to `"free"`).
+
+Nothing is cast or checked for an explicit null. `in:`, `format:`, `length:`, `validate:`, and `transform:` all see a value or nothing at all — never a `nil` they never agreed to handle.
+
+Three more readings worth knowing:
+
+- **`required` + `nullable`** is coherent, and means what it says in SQL: the client *must* state the field, and `null` is a legal statement. A missing key still violates.
+- **`default: nil`** — legal only on a nullable field — gives the `PUT` reading, where absence *also* means clear.
+- **On arrays and nested blocks**, `nullable:` applies to the array or object itself, never to its contents. `{ "tags": null }` yields `nil` (distinct from `[]`, which still gets length-checked); a null *element* inside `tags` is still `invalid_type`.
+
+Exported [OpenAPI](#exporting-openapi-docs-that-cannot-drift) tells the truth about all of this: a nullable field's `type` gains `"null"`, and a nullable `in:` set lists `null` in its `enum`.
+
 ### Violations and error responses
 
 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).
@@ -419,7 +487,9 @@ Resolution order per violation: the field's own `message:` (String, or the Hash
 | `:log` | Dropped, with a `logger.warn` naming the full paths |
 | `:error` | Each undeclared key becomes an `unknown` violation |
 
-Rails merges `controller`, `action`, and `format` into `params`; these are exempt at the top level so `unknown: :error` doesn't flag the router's own bookkeeping. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there.
+Rails merges its own keys into `params`: `controller`, `action`, and `format` from the router, plus `authenticity_token`, `_method`, `utf8`, and `commit` from an ordinary form POST. All seven are exempt at the top level, so `unknown: :error` flags what the *client* got wrong rather than what the framework added. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there — and a standalone `Contract` exempts nothing at all, having neither a router nor a form.
+
+The exemption covers the *check* only. Monitor mode still hands back the form keys in its raw pass-through, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `_method` itself; only the router's three are dropped there.
 
 ### Output reshaping (`transform:` and `finalize`)
 
@@ -485,9 +555,15 @@ Mark a field `sensitive: true` and its name is registered with `Permittable.filt
 optional :ssn, :string, sensitive: true
 ```
 
-The indirection is deliberate. Appending plain symbols to `config.filter_parameters` at class-load time misses every consumer that snapshots the list at boot — ActiveRecord's `filter_attributes` copy, lograge-style initializers, precompiled filters. A **single proc appended once at boot, consulting a live registry at filter time**, means fields registered when a controller loads later (lazy loading in development) are still redacted. The initializer runs before `active_record.set_filter_attributes`, so values are redacted from both request logs and `#inspect`.
+Two mechanisms, because neither covers the ground alone.
+
+A **single proc appended once at boot, consulting a live registry at filter time**, is what reaches consumers that snapshot `config.filter_parameters` at boot — ActiveRecord's `filter_attributes` copy, lograge-style initializers — so a field registered when a controller loads later (lazy loading in development) is still redacted there. The initializer runs before `active_record.set_filter_attributes`, so values are redacted from both request logs and `#inspect`.
+
+But a proc filter can only redact **String** values: ActiveSupport dups the value and expects in-place mutation, and for a `Hash` value it never calls the proc at all, recursing into it instead. So each name is **also registered as a name** in `config.filter_parameters`, which redacts a value of any type — an `:integer` field, or a whole sensitive nested block. Appending later still works: Rails' `precompile_filter_parameters` replaces that array *in place*, and `ActionDispatch` reads the same object on every request, so a name registered at class-load time is seen by the next request. (This is also why the mechanism is a name and not a live matcher object: precompilation joins patterns by source, which discards anything whose matching is decided at filter time.)
+
+Matching mirrors Rails' own symbol-filter semantics: case-insensitive substring match on the parameter key. The registry is fully duck-typed (`#add`, `#include?`, `#to_proc`, `#names`, `#reset!`) and swappable via `Permittable.filter_parameter_registry=`, so a host gem can pool registrations into its own. `#to_proc` must return a callable of arity 2 (`key, value`) or 3 (`key, value, original_params`), matching what Rails' own parameter filtering accepts; anything that does not respond to `#to_proc` is refused at the point of the swap rather than on the next request.
 
-Matching mirrors Rails' own symbol-filter semantics: case-insensitive substring match on the parameter key. The registry is fully duck-typed (`#add`, `#include?`, `#to_proc`, `#reset!`) and swappable via `Permittable.filter_parameter_registry=`, so a host gem can pool registrations into its own.
+**The swap works at any point**, including from `config/initializers` — which matters, because Rails runs railtie initializers *before* those, so a swap always happens after `Permittable::Railtie` has appended its filter. Two things make that safe. The appended proc (`Permittable.filter_parameter_proc`) resolves the registry at **filter time** rather than closing over whichever instance existed at boot, so whichever registry is current does the redacting. And the swap **carries the previous registry's names into the new one**, so a `sensitive:` field registered by a contract that loaded before the swap keeps being redacted afterwards. Without that, the two halves of an app would each redact only what the other did not.
 
 ### Instrumentation
 
@@ -660,7 +736,7 @@ Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
 
 Every operation references shared components for the [error envelope](#violations-and-error-responses): a `422` response always, plus a `400` when the contract declares a `root:`. So consumers get typed *errors*, not just typed inputs.
 
-**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern`; `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern` — including one anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` at runtime and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
 
 Output is deterministic (fixed key order, declaration-order properties), so the generated file can be committed and reviewed as a diff — a contract change shows up in the same PR as its documentation change.
 
@@ -714,7 +790,8 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 | Constant | Purpose |
 |---|---|
 | `Permittable.filter_parameter_registry` | The live registry of `sensitive:` field names |
-| `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry |
+| `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry; entries already registered are carried across |
+| `Permittable.filter_parameter_proc` | The single proc `Permittable::Railtie` appends to `config.filter_parameters`; consults the current registry at filter time |
 | `Permittable.mode` / `Permittable.mode=` | App-wide default (`:enforce`) for rules that don't declare their own `mode:` |
 | `Permittable::InvalidParameters` | Raised on violation; carries `#details` and `#status` |
 | `Permittable::JsonSchema` | Contract data → JSON Schema fragments (`.rule`, `.object`, `.field`) |
@@ -737,9 +814,13 @@ A bad contract is a programmer error, so it fails when the class loads — never
 - An unknown type, listing the supported ones
 - An unknown `normalize:` preset, listing the presets
 - `format:`, `length:`, or `normalize:` on a non-`:string` field
-- `length:` that isn't a `Range` or `Integer`; `in:` that doesn't respond to `include?`
+- `length:` that isn't a non-negative `Integer` or a `Range`; `in:` that doesn't respond to `include?`
+- 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`)
 - `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:`
+- 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:`
+- A `:json` field's `default:`/`example:` that isn't a Hash, or that its own `length:`/`max_depth:` would reject
+- A `max_depth:` that isn't a positive Integer
 - `required: true` combined with `default:`
 - A field given both a type and a nested block; an array given both `of:` and a block
 - An empty contract, or a nested block declaring no sub-fields

data/lib/permittable/filter_parameter_registry.rb

@@ -10,8 +10,9 @@ module Permittable
   #
   # Matching mirrors Rails symbol-filter semantics: case-insensitive substring
   # match on the parameter key. The whole object is duck-typed (#add,
-  # #include?, #to_proc, #reset!) so a host can swap in its own registry via
-  # `Permittable.filter_parameter_registry=` and pool registrations.
+  # #include?, #to_proc, #names, #reset!) so a host can swap in its own
+  # registry via `Permittable.filter_parameter_registry=` and pool
+  # registrations.
   class FilterParameterRegistry
     FILTERED = "[FILTERED]".freeze
 
@@ -55,6 +56,14 @@ module Permittable
       @proc
     end
 
+    # The names registered so far. Permittable.filter_parameter_registry=
+    # reads this off the outgoing registry and re-adds each name to the
+    # incoming one, so a swap never un-redacts a field that a contract
+    # loaded before it had already registered.
+    def names
+      @mutex.synchronize { @fields.to_a }
+    end
+
     # Spec hygiene — the registry is process-global.
     def reset!
       @mutex.synchronize do

data/lib/permittable/generator.rb

@@ -19,14 +19,17 @@ module Permittable
     DEFAULT_ACTIONS = %i[create update].freeze
     SKIPPED_COLUMNS = %w[created_at updated_at].freeze
 
-    # Column type => contract type. Anything absent here (json, jsonb, hstore,
-    # binary, ...) has no faithful scalar representation and becomes a TODO
-    # comment rather than a guess.
+    # Column type => contract type. Document-shaped columns map onto the
+    # opaque `:json` field — the shape stays undeclared, which is what a
+    # jsonb column is for, and `max_depth:`/`length:` can bound it later.
+    # Anything absent here (binary, geometry, ...) has no faithful
+    # representation and becomes a TODO comment rather than a guess.
     COLUMN_TYPES = {
       string: :string, text: :string, citext: :string, uuid: :string,
       integer: :integer, bigint: :integer, float: :float, decimal: :decimal,
       boolean: :boolean, date: :date, datetime: :datetime,
-      timestamp: :datetime, timestamptz: :datetime
+      timestamp: :datetime, timestamptz: :datetime,
+      json: :json, jsonb: :json, hstore: :json
     }.freeze
 
     # What a source scan recovered from existing permit calls. `scalars` are
@@ -168,7 +171,7 @@ module Permittable
 
     def column_line(column)
       type = COLUMN_TYPES[column.type]
-      return "# TODO: #{column.name} (#{column.type}) has no scalar contract type — declare it as a nested block or an array" unless type
+      return "# TODO: #{column.name} (#{column.type}) has no contract type — declare it as a nested block or an array" unless type
 
       line = "#{required_column?(column) ? 'required' : 'optional'} :#{column.name}, :#{type}"
       line += " # database default: #{column.default.inspect}" unless column.default.nil?

data/lib/permittable/json_schema.rb

@@ -33,16 +33,23 @@ module Permittable
 
     # Ruby regexp constructs with no ECMA-262 equivalent (\Z, \h, \K, \R, \G,
     # inline flag groups, absence operator, conditionals, POSIX classes,
-    # possessive quantifiers). A source matching this is left untranslated —
-    # the scan is deliberately over-eager on escaped lookalikes because a
-    # wrong pattern in published docs is worse than a missing one.
+    # possessive quantifiers) — and Ruby's ^ and $, which anchor a LINE where
+    # ECMA-262 without the m flag anchors the whole string. /^\d{5}$/ accepts
+    # "evil\n12345" at runtime, so emitting its source as `pattern` would
+    # publish a rule stricter than the server enforces, and an export from
+    # contract data is supposed to make that impossible. Straight after a [
+    # neither is an anchor — ^ is class negation and $ is a literal — so both
+    # stay translatable there. Otherwise the scan is deliberately over-eager
+    # on escaped lookalikes, because a wrong pattern in published docs is
+    # worse than a missing one.
     UNTRANSLATABLE = /
       \\[ZhHKRG]          |
       \(\?[a-z-]+[:)]     |
       \(\?~               |
       \(\?\(              |
       \[\[:               |
-      [*+?]\+
+      [*+?]\+             |
+      (?<![\\\[])[\^$]
     /x
 
     # Request-body schema for one rule from `permittable_contracts` /
@@ -75,12 +82,29 @@ module Permittable
     def field(field, unknown: :ignore)
       schema = case field[:kind]
                when :scalar then scalar_schema(field)
+               when :json then opaque_schema(field)
                when :nested then object(field[:fields], unknown: unknown)
                when :array then array_schema(field, unknown: unknown)
                end
+      nullify!(schema, field)
       annotate(schema, field)
     end
 
+    # `nullable: true` means an explicitly-sent empty value yields null, so
+    # the type gains "null". Assigning over the existing key keeps its
+    # position, preserving deterministic emission. `enum` is the one keyword
+    # that constrains the instance rather than one type (minLength, pattern,
+    # minimum and friends only apply to instances of their own type), so a
+    # nullable enum has to list null itself or it would reject the very null
+    # the type now permits.
+    def nullify!(schema, field)
+      return schema unless field[:nullable]
+
+      schema["type"] = Array(schema["type"]) + ["null"] if schema["type"]
+      schema["enum"] += [nil] if schema.key?("enum")
+      schema
+    end
+
     def scalar_schema(field)
       schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
       apply_in!(schema, field[:in])
@@ -89,6 +113,19 @@ module Permittable
       schema
     end
 
+    # A `:json` field's shape is deliberately undeclared, so the schema says
+    # "an object" and carries only the bounds the field does declare. JSON
+    # Schema has no nesting-depth keyword, so `max_depth:` stays visible as an
+    # extension rather than being dropped or mistranslated.
+    def opaque_schema(field)
+      schema = { "type" => "object" }
+      min, max = length_bounds(field[:length])
+      schema["minProperties"] = min if min
+      schema["maxProperties"] = max if max
+      schema["x-permittable-max-depth"] = field[:max_depth] if field[:max_depth]
+      schema
+    end
+
     def array_schema(field, unknown:)
       schema = { "type" => "array" }
       min, max = length_bounds(field[:length])
@@ -183,6 +220,9 @@ module Permittable
     def json_value(value)
       case value
       when Array then value.map { |v| json_value(v) }
+      # An authored `:json` default/example is a whole hash; its values get
+      # the same re-encoding as any other authored scalar.
+      when Hash then value.to_h { |k, v| [k.to_s, json_value(v)] }
       when BigDecimal then value.to_s("F")
       when Time then value.utc.iso8601
       # DateTime subclasses Date, so it must match first.

data/lib/permittable/railtie.rb

@@ -9,8 +9,24 @@ module Permittable
   class Railtie < Rails::Railtie
     initializer "permittable.filter_parameters",
                 before: "active_record.set_filter_attributes" do |app|
-      filter = ::Permittable.filter_parameter_registry.to_proc
+      # Late-bound on purpose — see Permittable.filter_parameter_proc. This
+      # initializer runs before config/initializers, so a registry swapped
+      # there must still be the one consulted at filter time.
+      filter = ::Permittable.filter_parameter_proc
       app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
+
+      # The proc above redacts Strings, live, and survives precompilation.
+      # What it cannot reach is a value that is not a String — ParameterFilter
+      # mutates values in place for proc filters, and skips them entirely for
+      # a Hash — so each registered name is ALSO added by name, which redacts
+      # any value type. Appending later still works: precompilation `replace`s
+      # this array in place and ActionDispatch reads the same object per
+      # request, so a name registered when a controller loads is seen by the
+      # next request. It is the array, not a snapshot, that has to be fed.
+      ::Permittable.on_sensitive_parameter do |name|
+        filters = app.config.filter_parameters
+        filters << name unless filters.include?(name)
+      end
     end
 
     rake_tasks do

data/lib/permittable/rspec.rb

@@ -91,6 +91,11 @@ module Permittable
         self
       end
 
+      def nullable
+        @expected[:nullable] = true
+        self
+      end
+
       # -- RSpec protocol ---------------------------------------------------
 
       def matches?(subject)
@@ -191,7 +196,7 @@ module Permittable
         when :array then "expected an array field, but it is declared with `#{field[:kind]}`" unless field[:kind] == :array
         when :of then "expected an array of :#{value}, but it is of: :#{field[:of]}" unless field[:of] == value
         when :required then required_mismatch(field, value)
-        when :virtual, :sensitive then "expected the field to be #{key}, but it is not" unless field[key]
+        when :virtual, :sensitive, :nullable then "expected the field to be #{key}, but it is not" unless field[key]
         else option_mismatch(field, key, value)
         end
       end
@@ -226,7 +231,7 @@ module Permittable
         when :array then "as an array"
         when :of then "of :#{value}"
         when :required then value ? "required" : "optional"
-        when :virtual, :sensitive then key.to_s
+        when :virtual, :sensitive, :nullable then key.to_s
         else "#{OPTION_LABELS.fetch(key)} #{value.inspect}"
         end
       end

data/lib/permittable/version.rb

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

data/lib/permittable.rb

@@ -4,6 +4,7 @@ require "active_support/notifications"
 require "active_support/hash_with_indifferent_access"
 require "active_support/core_ext/hash/indifferent_access" # nested plain Hashes inside HWIA.new
 require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/object/deep_dup" # authored default:/example: values are copied before freezing
 require "active_support/core_ext/string/inflections"
 require "active_support/core_ext/string/filters"
 require "bigdecimal"
@@ -34,6 +35,7 @@ require "permittable/filter_parameter_registry"
 #       optional :ssn,   :string,  sensitive: true
 #       optional :plan,  :string,  in: %w[free pro], default: "free"
 #       array    :tag_names, of: :string, length: 0..10, virtual: true
+#       optional :metadata,  :json,    max_depth: 3, length: 0..32
 #       optional :address do
 #         required :city, :string
 #         optional :zip,  :string, format: /\A\d{5}\z/
@@ -79,6 +81,17 @@ require "permittable/filter_parameter_registry"
 # request. `permittable_violations` reads the recorded details ([] when
 # the request was clean).
 #
+# THE :json FIELD — the deliberate hole. A json/jsonb column exists precisely
+# so its contents need no schema, and until it was declarable a contract could
+# only drop that key (strong parameters spells it `permit(metadata: {})`).
+# `optional :metadata, :json` passes an arbitrary Hash through untouched —
+# keys are neither filtered nor cast, and `unknown:` does not descend into it
+# — while still letting the contract bound the shape it refuses to describe:
+# `length:` caps the top-level key count, `max_depth:` caps container nesting
+# (arrays count as a level), and `validate:`/`transform:` see the whole hash.
+# Anything that is not a Hash is `invalid_type`, and the field still maps onto
+# a column for the drift guard.
+#
 # Coercion is deliberately STRICT — ActiveModel::Type is not used, because its
 # casts are lenient by design ("abc".to_i == 0, Boolean.cast("abc") == true)
 # and silently corrupting untrusted input is exactly what a contract must not
@@ -86,8 +99,21 @@ require "permittable/filter_parameter_registry"
 # guess. nil and "" are both treated as ABSENT (the query-param convention):
 # absent optional fields are OMITTED from the result (so partial updates never
 # nil-out columns), absent required fields violate, and `default:` fills
-# absence. Clearing a column to NULL is therefore outside a contract's
-# vocabulary — do that explicitly.
+# absence. `normalize:` runs BEFORE that rule rather than inside the cast, so
+# there is exactly one reading of absence and a value that normalizes to empty
+# ("   " under :squish) cannot satisfy a required field by becoming "". An
+# authored `default:`/`example:` is stored normalized — the form it was
+# validated in — and deep-frozen on a copy, so no request can corrupt it for
+# the next.
+#
+# `nullable: true` splits that rule in two for one field, which is how a PATCH
+# clears a column: a key the client never sent stays absent (defaults apply,
+# required violates), but a key sent EMPTY (JSON null, or "" from a form) is an
+# explicit null and yields nil in the result — ahead of any `default:`, and
+# without casting or checking a value that isn't there. It reads on arrays and
+# nested blocks too (the array/object itself may be null, never its elements),
+# and `default: nil` — legal only on a nullable field — gives the PUT reading
+# where absence also means clear.
 #
 # Failures raise Permittable::InvalidParameters, rescued (on a real
 # controller) into the shared ErrorEnvelope shape with `details:` entries of
@@ -107,7 +133,12 @@ require "permittable/filter_parameter_registry"
 # `sensitive: true` registers the field name with
 # Permittable.filter_parameter_registry (swappable — a host gem can point it
 # at its own registry), consulted at filter time by the proc
-# Permittable::Railtie appends to `config.filter_parameters`.
+# Permittable::Railtie appends to `config.filter_parameters`. The name is
+# ALSO published to that Railtie by name (see register_sensitive_parameter),
+# because a proc filter can only redact String values — ActiveSupport dups
+# the value and expects in-place mutation, and never calls the proc at all
+# for a Hash — so a name in config.filter_parameters is what covers an
+# :integer field or a sensitive nested block.
 #
 # OUTPUT RESHAPING — the safe replacement for params-mutating before_actions.
 # Two layers, both operating on the validated COPY (the request's `params` is
@@ -134,11 +165,39 @@ module Permittable
 
   LABEL = "Permittable".freeze
   SCALAR_TYPES = %i[string integer float decimal boolean date datetime].freeze
+  # Not a scalar: an opaque hash whose shape is deliberately undeclared, for
+  # the json/jsonb column a contract has to be able to carry.
+  JSON_TYPE = :json
   UNKNOWN_MODES = %i[ignore log error].freeze
   MODES = %i[enforce monitor].freeze
   # Rails merges routing bookkeeping into params; a top-level (root: false)
   # unknown-keys check must not flag them.
   ROUTING_KEYS = %w[controller action format].freeze
+  # Nor the keys an ordinary form POST carries — the CSRF token, the verb
+  # override, the encoding probe, and the submit button's name. Without this
+  # `unknown: :error` was unusable outside a JSON API: every browser form
+  # failed on the framework's own keys rather than on anything the client got
+  # wrong. Exempt from the CHECK only: unlike the routing keys these are NOT
+  # stripped from monitor mode's raw pass-through, where handing back an
+  # untouched params hash is the whole promise and a legacy action may well
+  # read `_method` itself.
+  FORM_KEYS = %w[authenticity_token _method utf8 commit].freeze
+  # ROUTING_KEYS/FORM_KEYS name where the keys come FROM; these two name what
+  # is DECIDED with them, which is what the call sites care about — and the
+  # asymmetry between them is the deliberate point, so spell it once here
+  # rather than leaving a bare ROUTING_KEYS to read like an oversight.
+  UNCHECKED_TOP_LEVEL_KEYS = (ROUTING_KEYS + FORM_KEYS).freeze
+  MONITOR_DROPPED_KEYS = ROUTING_KEYS
+
+  # The single proc Permittable::Railtie appends to config.filter_parameters.
+  # Declared with an optional third parameter so its own arity is -3 and Rails
+  # passes `original_params`; the registry's callable is then invoked by ITS
+  # arity, so both the 2- and 3-argument proc-filter shapes Rails accepts work
+  # as a swapped-in registry's #to_proc.
+  FILTER_PARAMETER_PROC = lambda do |key, value, original = nil|
+    inner = filter_parameter_registry.to_proc
+    inner.arity == 2 ? inner.call(key, value) : inner.call(key, value, original)
+  end.freeze
 
   NORMALIZERS = {
     squish: ->(v) { v.squish },
@@ -160,7 +219,84 @@ module Permittable
       end
     end
 
-    attr_writer :filter_parameter_registry
+    # Swapping registries must not un-redact anything. Contracts that loaded
+    # BEFORE the swap registered on the outgoing registry, and after the swap
+    # nothing consults it any more — so its entries are carried into the new
+    # one, which is the mirror image of the bug that made the proc late-bound
+    # in the first place. Validated here rather than at filter time: a
+    # registry with no #to_proc used to be silently never consulted, and
+    # late-binding it would instead raise NoMethodError on every request.
+    def filter_parameter_registry=(registry)
+      unless registry.nil? || registry.respond_to?(:to_proc)
+        raise ArgumentError,
+              "#{LABEL}: filter_parameter_registry must respond to #to_proc (got #{registry.class})"
+      end
+
+      @registry_mutex.synchronize do
+        previous = @filter_parameter_registry
+        @filter_parameter_registry = registry
+        next unless registry && previous.respond_to?(:names) && registry.respond_to?(:add)
+
+        previous.names.each { |name| registry.add(name) }
+      end
+      registry
+    end
+
+    # The proc Permittable::Railtie appends to config.filter_parameters.
+    #
+    # It resolves the registry at FILTER time rather than closing over
+    # whichever instance existed at boot. Rails runs railtie initializers
+    # BEFORE config/initializers, so an app or host gem that swaps the
+    # registry — the pooling the writer exists for — necessarily does so
+    # after the Railtie has already appended its proc. A proc bound to the old
+    # instance would go on consulting an empty registry and silently redact
+    # nothing, while `sensitive:` fields registered themselves in the new one.
+    #
+    # One frozen object for the life of the process, so the Railtie's
+    # idempotence check (include? before <<) holds across repeated initializer
+    # runs with no memo to synchronise.
+    def filter_parameter_proc
+      FILTER_PARAMETER_PROC
+    end
+
+    # Every `sensitive:` registration, published to whatever is listening.
+    #
+    # A proc filter cannot be the whole mechanism: ActiveSupport's
+    # ParameterFilter dups the value and expects in-place mutation, so a proc
+    # can only redact Strings — and it is never even CALLED for a Hash value,
+    # because ParameterFilter checks `value.is_a?(Hash)` first and recurses.
+    # So `optional :pin, :integer, sensitive: true` and `sensitive:` on a
+    # nested block both logged in the clear. What redacts any value type is a
+    # NAME in config.filter_parameters, which only Rails can be told about —
+    # hence a sink, installed by Permittable::Railtie, rather than Rails
+    # knowledge in this file or in the registry.
+    def register_sensitive_parameter(name)
+      filter_parameter_registry.add(name)
+      # Normalized the way the registry normalizes, so the name a sink sees is
+      # the same whether it arrives here or through on_sensitive_parameter's
+      # replay of #names — otherwise a sink deduplicating by value would hold
+      # both :ssn and "ssn".
+      name = name.to_s.downcase
+      sensitive_parameter_sinks.each { |sink| sink.call(name) } unless name.empty?
+      nil
+    end
+
+    # Install a sink. It is replayed over the names already registered, since
+    # a contract can be declared before the Railtie's initializer runs (a
+    # Permittable::Contract at require time, an eager-loaded controller) and
+    # would otherwise never reach it.
+    def on_sensitive_parameter(&sink)
+      @registry_mutex.synchronize { sensitive_parameter_sinks << sink }
+      registry = filter_parameter_registry
+      registry.names.each { |name| sink.call(name) } if registry.respond_to?(:names)
+      sink
+    end
+
+    # The installed sinks. Process-global, like the registry — specs that
+    # install one `.clear` this afterwards.
+    def sensitive_parameter_sinks
+      @sensitive_parameter_sinks ||= []
+    end
 
     # App-wide default for rules that don't declare their own mode:.
     # :enforce (the default) rejects violating requests; :monitor reports
@@ -227,10 +363,12 @@ module Permittable
     TRUE_VALUES = [true, "true", "1", 1].freeze
     FALSE_VALUES = [false, "false", "0", 0].freeze
 
-    # Full pipeline for one scalar field: normalize → cast → in / format /
-    # length / validate.
+    # Pipeline for one scalar field: cast → in / format / length / validate.
+    # `normalize:` is NOT applied here — it is its own stage, run by the
+    # caller before the absence rule (a value that normalizes to "" is absent
+    # like any other empty value), so normalizing again here would call a
+    # host's `normalize:` proc twice per value.
     def check_scalar(field, value)
-      value = apply_normalize(field[:normalize], value)
       status, value = cast(field[:type], value)
       return [status, value] unless status == :ok
 
@@ -245,6 +383,31 @@ module Permittable
       check_custom(field[:validate], value)
     end
 
+    # Free-form hash. The shape is deliberately undeclared, so the only
+    # checks are the bounds the field asked for: breadth (`length:`, the
+    # top-level key count, same reading as an array's element count) and
+    # nesting (`max_depth:`). Shared with macro-time `default:`/`example:`
+    # checking, like check_scalar.
+    def check_json(field, value)
+      return [:error, "invalid_type"] unless value.is_a?(Hash)
+      return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
+      return [:error, "depth"] if field[:max_depth] && depth_exceeds?(value, field[:max_depth])
+
+      check_custom(field[:validate], value)
+    end
+
+    # Container nesting, with the field's own hash as level 1. An Array counts
+    # as a level too — a deeply nested payload is a deeply nested payload
+    # whichever container carries it. Bails at the first breach instead of
+    # measuring the whole tree.
+    def depth_exceeds?(value, limit)
+      return false unless value.is_a?(Hash) || value.is_a?(Array)
+      return true if limit < 1
+
+      children = value.is_a?(Hash) ? value.each_value : value.each
+      children.any? { |child| depth_exceeds?(child, limit - 1) }
+    end
+
     # A custom validator returning a Symbol fails with that symbol as the
     # violation code; false/nil fails as "invalid"; any other truthy value
     # passes.
@@ -318,16 +481,37 @@ module Permittable
       [:error, "invalid_type"]
     end
 
+    # Date.parse fills in what a string omits FROM TODAY: "09/2026" becomes
+    # the 1st, "5th" becomes this month of this year. That is a guess, and a
+    # non-deterministic one — the same request means different things on
+    # different days — which is exactly what this coercion exists to refuse.
+    # So the string must name all three parts; which format it names them in
+    # is Date.parse's business, and every complete format it understands
+    # ("2026-09-05", "2026/09/05", "Sep 5, 2026") still works.
     def cast_date(value)
       case value
       when Date then [:ok, value]
-      when String then [:ok, Date.parse(value)]
+      when String
+        found = Date._parse(value)
+        return [:error, "invalid_type"] unless complete_date?(found)
+
+        # Built from the components rather than re-running Date.parse, which
+        # would parse the same string a second time — and Date.parse is the
+        # expensive half. Date.new applies the same calendar validation, so
+        # "2026-02-30" still fails.
+        [:ok, Date.new(found[:year], found[:mon], found[:mday])]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError, RangeError
       [:error, "invalid_type"]
     end
 
+    # Date._parse is the layer under Date.parse, and reports which components
+    # it actually FOUND rather than the filled-in result.
+    def complete_date?(found)
+      found.key?(:year) && found.key?(:mon) && found.key?(:mday)
+    end
+
     # A zoneless String parses as UTC regardless of the host timezone
     # (deterministic); explicit offsets are honoured and normalised to UTC.
     def cast_datetime(value)
@@ -335,7 +519,17 @@ module Permittable
       # DateTime is listed here, ahead of Date, because it subclasses Date.
       when ActiveSupport::TimeWithZone, Time, DateTime then [:ok, value.to_time.utc]
       when Date then [:ok, Time.utc(value.year, value.month, value.day)]
-      when String then [:ok, DateTime.parse(value).to_time.utc]
+      when String
+        # Same rule as :date — the DATE part must be named in full, or it is
+        # taken from today ("10:30" meant today at 10:30). An absent TIME part
+        # is fine and means midnight, which is the documented reading of a
+        # date given to a :datetime field.
+        #
+        # Unlike :date this still parses twice, deliberately: rebuilding a
+        # Time from components would have to reimplement DateTime.parse's
+        # handling of offsets, zone names and sub-second precision, and
+        # getting that subtly wrong costs more than the parse.
+        complete_date?(Date._parse(value)) ? [:ok, DateTime.parse(value).to_time.utc] : [:error, "invalid_type"]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError, RangeError
@@ -350,6 +544,14 @@ module Permittable
       normalizer.call(value)
     end
 
+    # nil and "" are both ABSENT — see the module comment. The VALUE half of
+    # that rule (the walker adds the key-presence half), shared with
+    # macro-time `default:`/`example:` checking so a default cannot be held
+    # to a different reading of absence than the request it stands in for.
+    def absent_value?(value)
+      value.nil? || (value.is_a?(String) && value.empty?)
+    end
+
     # Range#include? walks discrete ranges; cover? is the O(1) bounds check
     # and the right semantics for validation.
     def included_in?(allowed, value)
@@ -365,9 +567,13 @@ module Permittable
   # declaration is validated eagerly: a bad contract is a programmer error and
   # should fail at class load, not at request time.
   class ContractBuilder
-    SCALAR_OPTS = %i[in format length default normalize validate virtual sensitive transform message desc example].freeze
-    NESTED_OPTS = %i[virtual sensitive message desc].freeze
-    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message desc example].freeze
+    SCALAR_OPTS = %i[in format length default normalize validate virtual sensitive transform message desc example
+                     nullable].freeze
+    NESTED_OPTS = %i[virtual sensitive message desc nullable].freeze
+    JSON_OPTS   = %i[length max_depth default validate virtual sensitive transform message desc example
+                     nullable].freeze
+    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message desc example
+                     nullable].freeze
 
     attr_reader :finalizer
 
@@ -437,6 +643,12 @@ module Permittable
         field = { name: name, kind: :nested, required: required,
                   fields: nested_fields!(name, &block), **opts }
         validate_message!(field)
+      elsif type&.to_sym == JSON_TYPE
+        assert_opts!(name, opts, JSON_OPTS)
+        # `type:` is carried alongside `kind:` so the same `as(:json)` matcher
+        # chain and the same error wording work as for a scalar.
+        field = { name: name, kind: :json, required: required, type: JSON_TYPE, **opts }
+        validate_json_opts!(field)
       else
         assert_opts!(name, opts, SCALAR_OPTS)
         field = { name: name, kind: :scalar, required: required,
@@ -486,12 +698,18 @@ module Permittable
       if field[:required] && field.key?(:default)
         raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
       end
-      if field.key?(:in) && !field[:in].respond_to?(:include?)
-        raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
+
+      if field.key?(:in)
+        unless field[:in].respond_to?(:include?)
+          raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
+        end
+
+        assert_satisfiable!(name, :in, field[:in])
       end
 
       validate_string_only_opts!(field)
       validate_length!(name, field[:length]) if field.key?(:length)
+      validate_required_length!(field)
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
       resolve_normalizer!(field)
@@ -500,6 +718,40 @@ module Permittable
       validate_message!(field)
     end
 
+    def validate_json_opts!(field)
+      name = field[:name]
+      if field[:required] && field.key?(:default)
+        raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
+      end
+
+      validate_length!(name, field[:length]) if field.key?(:length)
+      validate_max_depth!(name, field[:max_depth]) if field.key?(:max_depth)
+      validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
+      validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
+      validate_json_authored_value!(field, :default)
+      validate_json_authored_value!(field, :example)
+      validate_message!(field)
+    end
+
+    def validate_max_depth!(name, depth)
+      return if depth.is_a?(Integer) && depth.positive?
+
+      raise ArgumentError, "#{LABEL}: :max_depth for :#{name} must be a positive Integer"
+    end
+
+    # Same rule as a scalar's authored value, over check_json: a `default:` or
+    # `example:` that its own bounds would reject fails at class load.
+    def validate_json_authored_value!(field, opt)
+      return unless field.key?(opt)
+      return if authored_nil!(field, opt)
+      raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
+
+      status, code = Coercion.check_json(field, field[opt])
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
+
+      field[opt] = freeze_authored(field[opt])
+    end
+
     # format / length / normalize reason about characters; on any other
     # type they would silently apply to a cast non-String and mislead.
     def validate_string_only_opts!(field)
@@ -513,9 +765,49 @@ module Permittable
     end
 
     def validate_length!(name, length)
-      return if length.is_a?(Range) || length.is_a?(Integer)
+      unless length.is_a?(Range) || (length.is_a?(Integer) && !length.negative?)
+        raise ArgumentError, "#{LABEL}: :length for :#{name} must be a non-negative Integer or a Range " \
+                             "(got #{length.inspect})"
+      end
 
-      raise ArgumentError, "#{LABEL}: :length for :#{name} must be a Range or Integer"
+      assert_satisfiable!(name, :length, length)
+    end
+
+    # A reversed Range (5..2), an exclusive Range with equal endpoints
+    # (3...3), or an empty set (in: []) excludes every value there is, so the
+    # field it bounds can never validate. That used to surface as every
+    # request to the action failing on that field — a contract mistake
+    # reported as a client error, once per request, forever. Endless and
+    # beginless Ranges are legitimate bounds, and endpoints that cannot be
+    # compared are left alone rather than guessed at.
+    def assert_satisfiable!(name, opt, bound)
+      return unless unsatisfiable?(bound)
+
+      raise ArgumentError, "#{LABEL}: :#{opt} for :#{name} is empty (#{bound.inspect}) — no value can satisfy it"
+    end
+
+    def unsatisfiable?(bound)
+      return bound.empty? if bound.respond_to?(:empty?)
+      return false unless bound.is_a?(Range) && bound.begin && bound.end
+
+      comparison = bound.begin <=> bound.end
+      return false if comparison.nil?
+
+      bound.exclude_end? ? !comparison.negative? : comparison.positive?
+    end
+
+    # "" is ABSENT and an absent required field violates as missing, so a
+    # required string can never validly be empty: a maximum length of 0
+    # leaves it nothing at all to accept. The exported schema already said
+    # so — minLength 1 alongside maxLength 0 — while nothing refused the
+    # declaration that produced it.
+    def validate_required_length!(field)
+      spec = field[:length]
+      return unless field[:required] && spec
+      return unless Coercion.length_ok?(spec, 0) && !Coercion.length_ok?(spec, 1)
+
+      raise ArgumentError, "#{LABEL}: :length for :#{field[:name]} is 0 on a required field — an absent or " \
+                           "empty value already violates as missing, so nothing could satisfy it"
     end
 
     def validate_callable!(name, opt, value)
@@ -538,20 +830,75 @@ module Permittable
     # An authored value (`default:`, or a documentation `example:`) must
     # satisfy the field's own contract — catching a lie at class load beats
     # shipping it to every request (or publishing it in generated docs).
+    # The authored value is STORED normalized, because that is the form it was
+    # validated in: `default: "  free  "` with `normalize: :squish` was
+    # checked as "free" and used to be handed to requests as "  free  ".
     def validate_authored_value!(field, opt)
       return unless field.key?(opt)
+      return if authored_nil!(field, opt)
 
-      status, code = Coercion.check_scalar(field, field[opt])
-      return if status == :ok
+      value = Coercion.apply_normalize(field[:normalize], field[opt])
+      status, code = Coercion.check_scalar(field, value)
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
 
-      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
+      field[opt] = freeze_authored(value)
     end
 
     def validate_array_authored_value!(field, opt)
       value = field[opt]
+      return if authored_nil!(field, opt)
       raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
-      return unless field[:of]
 
+      validate_array_elements!(field, opt, value) if field[:of]
+      validate_array_element_hashes!(field, opt, value) if field[:fields]
+      field[opt] = freeze_authored(value)
+    end
+
+    # The nested-block counterpart of the of: element check below. Without it
+    # `field[:of]` was nil for a block array, so its `default:` skipped
+    # validation entirely and whatever was authored went straight to every
+    # request that omitted the key. Shallow in the same way the of: check is:
+    # required sub-fields must be present and scalar ones must satisfy their
+    # own contract, which is what an authored value gets wrong.
+    def validate_array_element_hashes!(field, opt, value)
+      value.each do |element|
+        unless element.is_a?(Hash)
+          raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains #{element.class} " \
+                               "where the block declares a hash"
+        end
+
+        # Wrapped the way permittable_check_element wraps an element at
+        # request time, so class load reads keys exactly as a request does.
+        indifferent = ActiveSupport::HashWithIndifferentAccess.new(element)
+        field[:fields].each { |sub| validate_array_element_field!(field, opt, indifferent, sub) }
+      end
+    end
+
+    def validate_array_element_field!(field, opt, element, sub)
+      # Normalized before absence is read, and absence read with the runtime's
+      # own rule: a default: is applied WITHOUT revalidation, so anything this
+      # check waves through is handed to the app unexamined — and "" here used
+      # to mean a default could carry the very value a client is refused.
+      value = Coercion.apply_normalize(sub[:normalize], element[sub[:name]])
+      if Coercion.absent_value?(value)
+        # nullable: splits that rule exactly as permittable_explicit_null?
+        # does — a key present but empty is an explicit null, not an absence.
+        return if sub[:nullable] && element.key?(sub[:name])
+        return unless sub[:required]
+
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} is missing :#{sub[:name]}, " \
+                             "which the block declares as required"
+      end
+      return unless sub[:kind] == :scalar
+
+      status, code = Coercion.check_scalar(sub, value)
+      return if status == :ok
+
+      raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} has :#{sub[:name]} " \
+                           "violating its own contract (#{code})"
+    end
+
+    def validate_array_elements!(field, opt, value)
       value.each do |element|
         status, code = Coercion.cast(field[:of], element)
         next if status == :ok
@@ -560,6 +907,42 @@ module Permittable
       end
     end
 
+    # A contract is frozen data, but `@fields.map(&:freeze)` freezes only the
+    # field hashes — an authored `default:` or `example:` value stayed
+    # mutable, and HashWithIndifferentAccess hands a non-frozen Array (and
+    # any String) to the result BY REFERENCE. So one request appending to
+    # `permitted_params[:tags]` corrupted the default for every later request
+    # in the process. Freezing a COPY fixes that without freezing an object
+    # the host app passed in and may still be using.
+    def freeze_authored(value)
+      deep_freeze(value.deep_dup)
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each_pair do |key, element|
+          deep_freeze(key)
+          deep_freeze(element)
+        end
+      when Array then value.each { |element| deep_freeze(element) }
+      end
+      value.freeze
+    end
+
+    # An authored nil is only meaningful on a nullable field, where it says
+    # "absent means clear" (PUT semantics) rather than "no default". On any
+    # other field it is a value nil could never satisfy, so it fails at class
+    # load with the fix named.
+    def authored_nil!(field, opt)
+      return false unless field[opt].nil?
+      return true if field[:nullable]
+
+      raise ArgumentError,
+            "#{LABEL}: :#{opt} for field :#{field[:name]} is nil but the field is not nullable — " \
+            "declare nullable: true to make an explicit null part of the contract"
+    end
+
     # `message:` customizes what the client reads for a violation on this
     # field: one String covering every code, or a Hash of code => String
     # (codes without an entry keep the default rendering). Keys are
@@ -694,9 +1077,10 @@ module Permittable
     end
 
     # The drift guard. Nested/array fields are implicitly virtual — only
-    # scalar fields map one-to-one onto columns.
+    # scalar fields, and the opaque `:json` field standing in for a
+    # json/jsonb column, map one-to-one onto columns.
     def guard_contract_columns!(model_class, fields)
-      checked = fields.select { |f| f[:kind] == :scalar && !f[:virtual] }
+      checked = fields.select { |f| %i[scalar json].include?(f[:kind]) && !f[:virtual] }
       return if checked.empty?
 
       types = checked.to_h { |f| [f[:name], f[:type]] }
@@ -709,7 +1093,7 @@ module Permittable
 
     def register_sensitive_params(fields)
       fields.each do |field|
-        Permittable.filter_parameter_registry.add(field[:name]) if field[:sensitive]
+        Permittable.register_sensitive_parameter(field[:name]) if field[:sensitive]
         register_sensitive_params(field[:fields]) if field[:fields]
       end
     end
@@ -818,7 +1202,7 @@ module Permittable
     return ActiveSupport::HashWithIndifferentAccess.new unless source
 
     passed = ActiveSupport::HashWithIndifferentAccess.new(source)
-    rule[:root] ? passed : passed.except(*ROUTING_KEYS)
+    rule[:root] ? passed : passed.except(*MONITOR_DROPPED_KEYS)
   end
 
   def raise_invalid_parameters!(violations, status:)
@@ -900,11 +1284,13 @@ module Permittable
     fields.each do |field|
       key = field[:name].to_s
       full = permittable_path(path, key)
-      value = hash[key]
+      value = permittable_normalized(field, hash[key])
 
       if permittable_absent?(value, hash, key)
-        if field.key?(:default)
-          result[key] = field[:default]
+        if permittable_explicit_null?(field, hash, key)
+          result[key] = nil
+        elsif field.key?(:default)
+          result[key] = permittable_default(field)
         elsif field[:required]
           violations << permittable_violation(field, full, "missing")
         end
@@ -921,13 +1307,10 @@ module Permittable
     key = field[:name].to_s
     case field[:kind]
     when :scalar
-      status, out = Coercion.check_scalar(field, value)
-      if status == :ok
-        out = field[:transform].call(out) if field[:transform]
-        result[key] = out
-      else
-        violations << permittable_violation(field, full, out)
-      end
+      # Already normalized by permittable_normalized, before the absence rule.
+      permittable_check_whole(field, Coercion.check_scalar(field, value), full, result, violations: violations)
+    when :json
+      permittable_check_whole(field, Coercion.check_json(field, value), full, result, violations: violations)
     when :nested
       if value.is_a?(Hash)
         result[key] = permittable_check_hash(field[:fields], ActiveSupport::HashWithIndifferentAccess.new(value),
@@ -944,6 +1327,19 @@ module Permittable
     end
   end
 
+  # The shared tail of the two kinds whose entire value is checked in one
+  # call — a scalar, or an opaque hash. A clean value is transformed into the
+  # result; anything else records its code.
+  def permittable_check_whole(field, outcome, full, result, violations:)
+    status, out = outcome
+    if status == :ok
+      out = field[:transform].call(out) if field[:transform]
+      result[field[:name].to_s] = out
+    else
+      violations << permittable_violation(field, full, out)
+    end
+  end
+
   def permittable_check_array(field, value, path:, unknown:, violations:)
     before = violations.length
     violations << permittable_violation(field, path, "length") if field[:length] && !Coercion.length_ok?(field[:length], value.length)
@@ -977,9 +1373,39 @@ module Permittable
     nil
   end
 
+  # `normalize:` runs BEFORE the absence rule, not inside the cast, so there
+  # stays exactly ONE reading of absence. Otherwise a value that normalizes to
+  # empty walked straight past it: `required :name, :string, normalize:
+  # :squish` rejected "" as missing but accepted "   " as "" — the silent
+  # corruption strict coercion exists to refuse, delivered by the gem's own
+  # preset. Only scalars take normalize:, and apply_normalize is itself a
+  # no-op without one, so it owns that decision for every caller.
+  def permittable_normalized(field, value)
+    Coercion.apply_normalize(field[:normalize], value)
+  end
+
+  # An authored default belongs to the contract, which is frozen data (see
+  # ContractBuilder#freeze_authored). HashWithIndifferentAccess copies a
+  # frozen Array or Hash as it assigns it, but stores a String as-is — so
+  # that one is copied here, leaving every value in the result the app's own
+  # to mutate.
+  def permittable_default(field)
+    value = field[:default]
+    value.is_a?(String) ? value.dup : value
+  end
+
   # nil and "" are both ABSENT — see the module comment.
   def permittable_absent?(value, hash, key)
-    !hash.key?(key) || value.nil? || (value.is_a?(String) && value.empty?)
+    !hash.key?(key) || Coercion.absent_value?(value)
+  end
+
+  # `nullable: true` splits the one absence rule in two: a key the client
+  # never sent is still absent (defaults apply, required violates), but a key
+  # sent EMPTY is an explicit null — the field yields nil, so a PATCH can
+  # clear a column. Nothing is cast or checked: there is no value to check,
+  # and `transform:` never sees a nil it did not agree to.
+  def permittable_explicit_null?(field, hash, key)
+    field[:nullable] && hash.key?(key)
   end
 
   def permittable_check_unknown(fields, hash, path:, unknown:, top_level:, violations:)
@@ -987,7 +1413,7 @@ module Permittable
 
     declared = fields.map { |f| f[:name].to_s }
     extra = hash.keys.map(&:to_s) - declared
-    extra -= ROUTING_KEYS if top_level
+    extra -= UNCHECKED_TOP_LEVEL_KEYS if top_level
     return if extra.empty?
 
     if unknown == :error

metadata

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