permittable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: deed1778579c6d35f58ff18111114b00566ad0d6d2a92db5d4a9bfc3a730c6a6
+  data.tar.gz: 57c83b026226096fcc96552d2df3a51577da12e704b5883fb4ba8c1110704433
+SHA512:
+  metadata.gz: 1c89bc7b9ff00e4246f0ac9bcc2937b97fb5ba8cdcfda1cbb5308d7d9cff5b4a7410eb48c5a185acd2b8feb82f595f771319edc33badd64ad1155f3d5e691b51
+  data.tar.gz: a0087bd69e30d6739a9fc7af090b35cdbc268fbdad7cb57666d3fc71fc140a7b9e5304827e7d1789ff43ccc3f99789b576fbc8340d23595db38712e27abdb0db

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+<!-- CHANGELOG.md -->
+
+## 0.1.0 (2026-08-16)
+
+Initial extraction from [concerns_on_rails](https://github.com/VSN2015/concerns_on_rails) (developed there on `feature/permittable` as `ConcernsOnRails::Controllers::Permittable`; concerns_on_rails now depends on this gem and aliases that constant to `::Permittable`).
+
+### Added
+- **`Permittable`** — declarative, typed params contracts for Rails controllers. `permit_params *actions, root:, model:, unknown:, enforce:` declares a per-action contract (repeatable; no actions = catch-all; last matching rule wins; inherited copy-on-write) whose block DSL (`required`/`optional`/`array`, nested blocks) types every field (`:string :integer :float :decimal :boolean :date :datetime`) and validates it (`in:`, `format:`, `length:`, `normalize:` presets/Proc, `default:` — itself contract-checked at class load — and custom `validate:` with symbol violation codes). `permitted_params` returns the cast/validated/defaulted hash (lazy; `enforce: true` moves the check to a before_action); violations raise `Permittable::InvalidParameters`, auto-rescued into a JSON error envelope as 422 (400 for a missing `root:` key) with machine-readable `details:`, and instrument `invalid_parameters.permittable`.
+- **Schema-drift guard**: `model:` (a class, or `true` to infer from `controller_name`) checks every non-`virtual:` scalar field against the model's columns at controller class load — a column dropped by a migration fails the deploy with a copy-paste migration hint, not the request. Skips gracefully when the schema is unreachable.
+- **Strict coercion**: no ActiveModel::Type leniency — `"abc"` is never `0`, `?age[]=1` type confusion is a violation, not a 500. `nil`/`""` are ABSENT (absent optionals omitted, so partial updates never nil-out columns; `default:` fills absence).
+- **Output reshaping**: per-field `transform:` (a callable applied AFTER cast + validation; defaults and absent fields untouched, partially-invalid arrays never transformed) and a once-per-contract `finalize do |p| ... end` (runs only when every field validated, on a bare runner — controller state unreachable — must return the final Hash) with `violate!(param, code)` as the cross-field validation seam. The request's `params` is never mutated.
+- **`sensitive: true`** registers field names with `Permittable.filter_parameter_registry` (swappable, duck-typed), consulted at filter time by the proc `Permittable::Railtie` appends to `config.filter_parameters`.
+- Sole runtime dependency: activesupport (>= 5.0, < 9). actionpack/activerecord are optional integration points.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ethan Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# Permittable
+
+**Typed, validated params contracts for Rails controllers — plus a schema-drift guard.**
+
+`Permittable` is what strong parameters would be if it also knew types, bounds, defaults, and *why* a request was bad. `params.permit` (and Rails 8's `params.expect`) only answer "which keys may pass"; a Permittable contract additionally **casts** each field, **validates** it, applies **defaults**, reshapes the output, and turns every failure into a machine-readable 422. Because the contract is class-level data rather than code inside the action, it is introspectable — and can be checked against a model's schema at boot.
+
+```ruby
+class UsersController < ApplicationController
+  include Permittable
+
+  permit_params :create, :update, root: :user, model: User do
+    required :name,  :string,  length: 1..80, normalize: :squish
+    required :email, :string,  format: URI::MailTo::EMAIL_REGEXP, normalize: :email
+    optional :age,   :integer, in: 18..120
+    optional :ssn,   :string,  sensitive: true          # auto-redacted from logs
+    optional :plan,  :string,  in: %w[free pro], default: "free"
+    array    :tag_names, of: :string, length: 0..10, virtual: true
+    optional :address do
+      required :city, :string
+      optional :zip,  :string, format: /\A\d{5}\z/
+    end
+  end
+
+  def create
+    user = User.create!(permitted_params)   # cast, validated, defaulted
+  end
+end
+```
+
+A violating request renders:
+
+```json
+{ "success": false,
+  "error": { "message": "Invalid parameters: user.age (inclusion)",
+             "code": "invalid_parameters",
+             "details": [{ "param": "user.age", "code": "inclusion" }] } }
+```
+
+## Installation
+
+```ruby
+gem "permittable"
+```
+
+The only runtime dependency is `activesupport`. `actionpack` (rescue_from / before_action / `ActionController::Parameters`) and `activerecord` (the `model:` schema-drift guard) are optional — every touchpoint is guarded, so your app brings what it already has.
+
+## The schema-drift guard
+
+With `model:` (a class, or `true` to infer from the controller name), every non-`virtual:` scalar field is checked against the model's columns **at controller class load**. Production eager-loads controllers, so a column dropped by a migration fails the deploy, not the request:
+
+```
+Permittable: 'nickname' does not exist in the database (table: users).
+Add it with: bin/rails generate migration AddNicknameToUsers nickname:string
+If this parameter is not backed by a column, declare it with virtual: true.
+```
+
+Nested and array fields are implicitly virtual. The check skips gracefully when the schema is unreachable (`db:create`, `assets:precompile`). In CI, one spec running `Rails.application.eager_load!` exercises every contract in the app.
+
+## Configuration
+
+### `permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, &contract)`
+
+Repeatable; rules are inherited by subclasses copy-on-write. **No positional actions = catch-all**, and **the last matching rule wins** (contracts are configuration overrides).
+
+| Option | Default | Meaning |
+|---|---|---|
+| `*actions` | — | Actions the contract covers; **none = catch-all** |
+| `root:` | `false` | Key to unwrap first (`require(:user)` equivalent); missing/non-hash root → **400** |
+| `model:` | `nil` | Model class (or `true` to infer from `controller_name`) enabling the schema-drift guard |
+| `unknown:` | `:ignore` | `:ignore` / `:log` / `:error` — undeclared keys, at every nesting level (`controller`/`action`/`format` exempt at top level) |
+| `enforce:` | `false` | `false` = validate lazily on first `permitted_params` call; `true` = validate in a `before_action` |
+
+### Field DSL
+
+- `required :name, :type, **opts` / `optional :name, :type, **opts` — type defaults to `:string`; types: `:string`, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`.
+- A block instead of a type declares a **nested hash**; violation paths are dotted (`user.address.zip`).
+- `array :name, of: :type` (or a block for arrays of hashes) — `length:` constrains the element **count**, element failures carry the index (`items[1]`), `required: true` opts in.
+
+Per-field options: `in:` (Range/Array), `format:` / `length:` / `normalize:` (`:squish`, `:strip`, `:downcase`, `:upcase`, `:email`, or a Proc; string fields only), `default:` (validated against the field's own contract at class load), `validate:` (Proc — falsy fails as `"invalid"`, a returned Symbol becomes the violation code), `transform:` (below), `virtual:`, `sensitive:`.
+
+Every bad declaration raises a teaching `ArgumentError` at class load.
+
+## Output reshaping (`transform:` / `finalize`)
+
+The safe replacement for params-mutating before_actions — both layers operate on the validated **copy**; the request's `params` is never touched.
+
+- **`transform:`** (scalar and array fields) — a callable applied **after** cast and validation: `transform: ->(v) { v.split(",") }` turns a validated delimited String into an Array. Absent fields stay absent, `default:` values are authored in final shape, and a partially-invalid array is never transformed.
+- **`finalize do |p| … end`** (once per contract, top level only) — runs after every field validated cleanly, receives the result hash, and must return the final Hash. It executes on a bare runner, **not** the controller, so contracts stay pure; its one extra verb, `violate!(param, code)`, records a violation and halts the block immediately — the cross-field validation seam.
+
+```ruby
+permit_params :create, root: :lease_addendum_form do
+  required :resident_signatures, :string, transform: ->(v) { v.split("<<delimiter>>") }
+  required :signer_names,        :string, transform: ->(v) { v.split(",") }
+
+  finalize do |p|
+    violate!("lease_addendum_form.signer_names", :length_mismatch) unless p[:signer_names].length == p[:resident_signatures].length
+    p[:signatures] = p[:resident_signatures].zip(p[:signer_names]).map { |image, name| Signature.new(image:, full_name: name) }
+    p.except(:resident_signatures, :signer_names)
+  end
+end
+```
+
+## Methods
+
+- `permitted_params(action = action_name)` — the cast/validated/defaulted `HashWithIndifferentAccess`. Absent optional fields are **omitted** (partial updates never nil-out columns). Memoized per action. Raises `Permittable::InvalidParameters` on violation; `ArgumentError` when no contract covers the action (programmer error).
+- `enforce_params_contract` — the `before_action` entry point (skip with `skip_before_action`); only validates rules declared with `enforce: true`.
+- `render_invalid_parameters(error)` — the `rescue_from` target; renders via the host's `render_error` when defined, the identical inline envelope otherwise.
+- Class-side introspection: `permittable_contracts` and `permit_rule_for(action)`.
+- `Permittable.filter_parameter_registry` — duck-typed, swappable sink for `sensitive:` field names; `Permittable::Railtie` appends its live filter proc to `config.filter_parameters`.
+
+## Semantics worth knowing
+
+- **Coercion is strict** — deliberately not `ActiveModel::Type` (`"abc".to_i == 0` silently corrupts untrusted input). `"4.5"` is not an integer; booleans accept only `true/false/"true"/"false"/"1"/"0"/1/0`; unparseable dates are `invalid_type`; zoneless datetime strings parse as **UTC**.
+- **Type confusion is a violation, not a 500**: `?age[]=1` where a scalar is declared yields `invalid_type`.
+- `nil` and `""` are both **absent**; boolean `false` is present.
+- Every violation instruments `invalid_parameters.permittable` for dashboards.
+- Used inside [concerns_on_rails](https://github.com/VSN2015/concerns_on_rails)? `include ConcernsOnRails::Controllers::Permittable` is an alias for this module, and `sensitive:` registrations pool into that gem's shared filter registry.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT.

data/lib/permittable/column_guard.rb

@@ -0,0 +1,51 @@
+require "active_support/core_ext/string/inflections"
+
+module Permittable
+  # Schema validation behind the drift guard. When the schema is unreachable —
+  # no database yet (`db:create`, a fresh `db:migrate`, `assets:precompile`,
+  # CI bootstrap) or the table not yet migrated — the check is skipped and
+  # `false` is returned instead of raising, so controller classes stay
+  # loadable. A missing column with a *reachable* schema still raises: the
+  # rescue is scoped to ActiveRecord::ActiveRecordError precisely so real bugs
+  # (NameError from a typo etc.) keep surfacing. Skipping is self-healing:
+  # once the migration runs and classes reload, validation happens for real.
+  module ColumnGuard
+    module_function
+
+    # `types:` teaches the error message: a Symbol/String applies to every
+    # listed field, a Hash maps field => type. The raised ArgumentError then
+    # appends a ready-to-paste migration command.
+    def ensure_columns_on!(label, klass, *fields, types: nil)
+      return false unless schema_reachable?(klass)
+
+      fields.flatten.compact.each do |field|
+        next if klass.column_names.include?(field.to_s)
+
+        raise ArgumentError,
+              "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
+              "#{column_migration_hint(klass, field, types)}"
+      end
+      true
+    end
+
+    def column_migration_hint(klass, field, types)
+      type = types.is_a?(Hash) ? types[field.to_sym] : types
+      column = [field, type].compact.join(":")
+      " Add it with: bin/rails generate migration " \
+        "Add#{field.to_s.camelize}To#{klass.table_name.to_s.camelize} #{column}"
+    end
+
+    # True when the class's table can actually be inspected. Connection errors
+    # (ConnectionNotEstablished, NoDatabaseError, adapter errors) all inherit
+    # from ActiveRecord::ActiveRecordError; the defined? guard keeps this gem
+    # loadable without activerecord (a host without it cannot pass `model:`
+    # anyway).
+    def schema_reachable?(klass)
+      klass.table_exists?
+    rescue StandardError => e
+      raise unless defined?(ActiveRecord::ActiveRecordError) && e.is_a?(ActiveRecord::ActiveRecordError)
+
+      false
+    end
+  end
+end

data/lib/permittable/error_envelope.rb

@@ -0,0 +1,25 @@
+module Permittable
+  # One home for the error envelope: prefer the host's #render_error when the
+  # controller defines one (e.g. concerns_on_rails' Respondable), otherwise
+  # render the identical inline shape — and the single place to change when
+  # e.g. an RFC 9457 problem+json mode lands.
+  module ErrorEnvelope
+    module_function
+
+    def render(controller, message:, status:, code: nil, details: nil)
+      if controller.respond_to?(:render_error)
+        # errors: only when there are details — a host may document its
+        # render_error contract as `(message:, status:, code:)`, and an
+        # unconditional errors: kwarg would break those implementations.
+        kwargs = { message: message, code: code, status: status }
+        kwargs[:errors] = details if details
+        controller.render_error(**kwargs)
+      else
+        error = { message: message }
+        error[:code] = code if code
+        error[:details] = details if details
+        controller.render(json: { success: false, error: error }, status: status)
+      end
+    end
+  end
+end

data/lib/permittable/filter_parameter_registry.rb

@@ -0,0 +1,68 @@
+require "set"
+
+module Permittable
+  # Registry of sensitive parameter names (populated by `sensitive: true`
+  # contract fields) surfaced to Rails' log filtering. 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 proc appended once at
+  # boot by Permittable::Railtie consults this live registry at *filter time*,
+  # so fields registered when a controller class loads later (lazy loading in
+  # development) are still redacted.
+  #
+  # 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.
+  class FilterParameterRegistry
+    FILTERED = "[FILTERED]".freeze
+
+    def initialize
+      @fields = Set.new
+      @mutex = Mutex.new
+      @pattern = nil
+      # Stable object so the Railtie's idempotence check (`include?` before
+      # `<<`) holds across repeated initializer runs. ActiveSupport's
+      # ParameterFilter dups values before invoking proc filters, so in-place
+      # String#replace is the supported redaction mechanism.
+      @proc = lambda do |key, value|
+        value.replace(FILTERED) if value.is_a?(String) && include?(key)
+      end
+    end
+
+    def add(field)
+      name = field.to_s.downcase
+      return if name.empty?
+
+      @mutex.synchronize do
+        @pattern = nil if @fields.add?(name)
+      end
+      nil
+    end
+
+    def include?(key)
+      regexp = pattern
+      !regexp.nil? && regexp.match?(key.to_s)
+    end
+
+    def pattern
+      @mutex.synchronize do
+        next nil if @fields.empty?
+
+        @pattern ||= Regexp.new(@fields.map { |f| Regexp.escape(f) }.join("|"), Regexp::IGNORECASE)
+      end
+    end
+
+    def to_proc
+      @proc
+    end
+
+    # Spec hygiene — the registry is process-global.
+    def reset!
+      @mutex.synchronize do
+        @fields.clear
+        @pattern = nil
+      end
+    end
+  end
+end

data/lib/permittable/railtie.rb

@@ -0,0 +1,16 @@
+require "rails/railtie"
+
+module Permittable
+  # Boot-time integration, loaded only when Rails is present (see the
+  # conditional require at the bottom of lib/permittable.rb): appends the
+  # live-registry filter proc before ActiveRecord copies
+  # `config.filter_parameters` into `filter_attributes` (a `+=` snapshot), so
+  # `sensitive: true` params are redacted from both request logs and #inspect.
+  class Railtie < Rails::Railtie
+    initializer "permittable.filter_parameters",
+                before: "active_record.set_filter_attributes" do |app|
+      filter = ::Permittable.filter_parameter_registry.to_proc
+      app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
+    end
+  end
+end

data/lib/permittable/version.rb

@@ -0,0 +1,3 @@
+module Permittable
+  VERSION = "0.1.0".freeze
+end

data/lib/permittable.rb

@@ -0,0 +1,830 @@
+require "active_support"
+require "active_support/concern"
+require "active_support/notifications"
+require "active_support/hash_with_indifferent_access"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/string/filters"
+require "bigdecimal"
+require "date"
+require "time"
+
+require "permittable/version"
+require "permittable/error_envelope"
+require "permittable/column_guard"
+require "permittable/filter_parameter_registry"
+
+# Declarative, typed params contracts — what strong parameters would be if it
+# also knew types, bounds, defaults, and why a request was bad. Strong
+# parameters (and Rails 8's `params.expect`) only answer "which keys may
+# pass"; a Permittable contract additionally casts each field, validates it,
+# applies defaults, and turns every failure into a machine-readable 422 — and,
+# because the contract is class-level data rather than code inside the action,
+# it is introspectable (`permittable_contracts`) and can be checked against a
+# model's schema at class-load time.
+#
+#   class UsersController < ApplicationController
+#     include Permittable
+#
+#     permit_params :create, :update, root: :user, model: User do
+#       required :name,  :string,  length: 1..80, normalize: :squish
+#       required :email, :string,  format: URI::MailTo::EMAIL_REGEXP, normalize: :email
+#       optional :age,   :integer, in: 18..120
+#       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 :address do
+#         required :city, :string
+#         optional :zip,  :string, format: /\A\d{5}\z/
+#       end
+#     end
+#
+#     def create
+#       user = User.create!(permitted_params) # cast, validated, defaulted
+#     end
+#   end
+#
+# THE LAST MATCHING RULE WINS: contracts are configuration, so a base
+# controller's catch-all (a rule declared with no actions) is overridden by a
+# later action-specific declaration in a subclass. Rules accumulate via
+# reassignment, never mutation, so subclasses inherit copy-on-write.
+#
+# Schema-drift guard — the reason `model:` exists. Every non-virtual scalar
+# field is checked against the model's columns when the macro runs, i.e. at
+# controller class load. Production eager-loads controllers, so a column
+# dropped by a migration fails the deploy, not the request; the error carries
+# a copy-paste migration hint. Fields not backed by a column
+# (password_confirmation, terms flags) opt out with `virtual: true`; nested
+# and array fields are implicitly virtual. When the schema is unreachable
+# (db:create, assets:precompile) the check skips. In CI, one
+# `Rails.application.eager_load!` spec exercises every contract in the app.
+#
+# Validation is LAZY: it runs on the first `permitted_params` call, so an
+# action that never reads params never pays. `enforce: true` installs the
+# check as a before_action instead (reject before the action body runs).
+#
+# 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
+# do. A value the type cannot faithfully represent is a violation, not a
+# 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.
+#
+# Failures raise Permittable::InvalidParameters, rescued (on a real
+# controller) into the shared ErrorEnvelope shape with `details:` entries of
+# `{ param: "user.address.zip", code: "format" }`; a missing `root:` key
+# renders 400, field violations 422. Every violation also instruments
+# "invalid_parameters.permittable" so failures can be dashboarded.
+#
+# `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`.
+#
+# OUTPUT RESHAPING — the safe replacement for params-mutating before_actions.
+# Two layers, both operating on the validated COPY (the request's `params` is
+# never touched):
+#   * `transform:` (scalar and array fields) — a callable applied AFTER cast
+#     and validation to reshape that field's output, e.g.
+#     `transform: ->(v) { v.split(",") }` turns a validated delimited String
+#     into an Array. Runs only on request-supplied values: absent fields stay
+#     absent and `default:` values are authored in final shape.
+#   * `finalize do |p| ... end` (once per contract) — runs after every field
+#     validated cleanly, receives the result hash, and must return the
+#     (possibly restructured) Hash: combine parallel fields, build value
+#     objects, drop scaffolding keys. It executes on a bare runner — NOT the
+#     controller — so contracts stay pure data + pure functions; the only
+#     extra vocabulary is `violate!(param, code)`, which records one violation
+#     and halts the block immediately (the whole contract then fails as a
+#     normal 422), making finalize double as the cross-field validation seam
+#     ("ends_at after starts_at").
+#
+# Naming note: some legacy stacks (InheritedResources) define their own
+# `permitted_params`; don't include both on one controller.
+module Permittable
+  extend ActiveSupport::Concern
+
+  LABEL = "Permittable".freeze
+  SCALAR_TYPES = %i[string integer float decimal boolean date datetime].freeze
+  UNKNOWN_MODES = %i[ignore log error].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
+
+  NORMALIZERS = {
+    squish:   ->(v) { v.squish },
+    strip:    ->(v) { v.strip },
+    downcase: ->(v) { v.downcase },
+    upcase:   ->(v) { v.upcase },
+    email:    ->(v) { v.strip.downcase },
+  }.freeze
+
+  @registry_mutex = Mutex.new
+
+  class << self
+    # Duck-typed sink for `sensitive:` field names (#add / #include? /
+    # #to_proc / #reset!). Swappable so a host gem can pool registrations into
+    # its own registry (concerns_on_rails does exactly this).
+    def filter_parameter_registry
+      @filter_parameter_registry || @registry_mutex.synchronize do
+        @filter_parameter_registry ||= FilterParameterRegistry.new
+      end
+    end
+
+    attr_writer :filter_parameter_registry
+  end
+
+  # Raised when the request violates the matching contract. `details` is an
+  # array of { param:, code: } hashes; `status` is :bad_request for a missing
+  # root key, :unprocessable_entity for field violations.
+  class InvalidParameters < StandardError
+    attr_reader :details, :status
+
+    def initialize(message, details: [], status: :unprocessable_entity)
+      super(message)
+      @details = details
+      @status = status
+    end
+  end
+
+  included do
+    class_attribute :permittable_contracts, instance_accessor: false, default: []
+
+    rescue_from InvalidParameters, with: :render_invalid_parameters if respond_to?(:rescue_from)
+    before_action :enforce_params_contract if respond_to?(:before_action)
+  end
+
+  # Strict params-shaped coercion, shared by request-time validation and
+  # macro-time `default:` checking. Every entry point returns
+  # [:ok, cast_value] or [:error, code_string].
+  module Coercion
+    module_function
+
+    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.
+    def check_scalar(field, value)
+      value = apply_normalize(field[:normalize], value)
+      status, value = cast(field[:type], value)
+      return [status, value] unless status == :ok
+
+      check_scalar_rules(field, value)
+    end
+
+    def check_scalar_rules(field, value)
+      return [:error, "inclusion"] if field[:in] && !included_in?(field[:in], value)
+      return [:error, "format"] if field[:format] && !field[:format].match?(value)
+      return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
+
+      check_custom(field[:validate], value)
+    end
+
+    # A custom validator returning a Symbol fails with that symbol as the
+    # violation code; false/nil fails as "invalid"; any other truthy value
+    # passes.
+    def check_custom(validator, value)
+      return [:ok, value] unless validator
+
+      verdict = validator.call(value)
+      return [:error, verdict.to_s] if verdict.is_a?(Symbol)
+      return [:error, "invalid"] unless verdict
+
+      [:ok, value]
+    end
+
+    def cast(type, value)
+      return [:error, "invalid_type"] unless scalar_shaped?(value)
+
+      public_send("cast_#{type}", value)
+    end
+
+    # Arrays, hashes, and nested ActionController::Parameters
+    # (`?age[]=1`, `?age[x]=1`) can never satisfy a scalar type.
+    def scalar_shaped?(value)
+      return false if value.is_a?(Array) || value.is_a?(Hash)
+      return false if defined?(ActionController::Parameters) && value.is_a?(ActionController::Parameters)
+
+      true
+    end
+
+    def cast_string(value)
+      case value
+      when String then [:ok, value]
+      when Numeric, true, false then [:ok, value.to_s]
+      else [:error, "invalid_type"]
+      end
+    end
+
+    def cast_integer(value)
+      case value
+      when Integer then [:ok, value]
+      when Float then value == value.truncate ? [:ok, value.to_i] : [:error, "invalid_type"]
+      when String then [:ok, Integer(value, 10)]
+      else [:error, "invalid_type"]
+      end
+    rescue ArgumentError
+      [:error, "invalid_type"]
+    end
+
+    def cast_float(value)
+      case value
+      when Numeric then [:ok, value.to_f]
+      when String then [:ok, Float(value)]
+      else [:error, "invalid_type"]
+      end
+    rescue ArgumentError
+      [:error, "invalid_type"]
+    end
+
+    def cast_decimal(value)
+      case value
+      when Numeric, String then [:ok, BigDecimal(value.to_s)]
+      else [:error, "invalid_type"]
+      end
+    rescue ArgumentError
+      [:error, "invalid_type"]
+    end
+
+    def cast_boolean(value)
+      return [:ok, true] if TRUE_VALUES.include?(value)
+      return [:ok, false] if FALSE_VALUES.include?(value)
+
+      [:error, "invalid_type"]
+    end
+
+    def cast_date(value)
+      case value
+      when Date then [:ok, value]
+      when String then [:ok, Date.parse(value)]
+      else [:error, "invalid_type"]
+      end
+    rescue ArgumentError, RangeError
+      [:error, "invalid_type"]
+    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)
+      case value
+      when ActiveSupport::TimeWithZone, Time then [:ok, value.to_time.utc]
+      when 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]
+      else [:error, "invalid_type"]
+      end
+    rescue ArgumentError, RangeError
+      [:error, "invalid_type"]
+    end
+
+    # Presets only make sense on String input; a non-String value (JSON
+    # numbers, booleans) skips normalization and goes straight to the cast.
+    def apply_normalize(normalizer, value)
+      return value unless normalizer && value.is_a?(String)
+
+      normalizer.call(value)
+    end
+
+    # Range#include? walks discrete ranges; cover? is the O(1) bounds check
+    # and the right semantics for validation.
+    def included_in?(allowed, value)
+      allowed.is_a?(Range) ? allowed.cover?(value) : allowed.include?(value)
+    end
+
+    def length_ok?(spec, length)
+      spec.is_a?(Range) ? spec.cover?(length) : spec == length
+    end
+  end
+
+  # Builds the frozen field list from the permit_params block. Every
+  # 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].freeze
+    NESTED_OPTS = %i[virtual sensitive].freeze
+    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform].freeze
+
+    attr_reader :finalizer
+
+    def initialize
+      @fields = []
+      @finalizer = nil
+    end
+
+    def build(&block)
+      instance_eval(&block)
+      @fields.map(&:freeze).freeze
+    end
+
+    # Post-validation reshaping of the whole contract — see the module
+    # comment. Once per contract, top level only.
+    def finalize(&block)
+      raise ArgumentError, "#{LABEL}: finalize requires a block" unless block
+      raise ArgumentError, "#{LABEL}: finalize may only be declared once per contract" if @finalizer
+
+      @finalizer = block
+    end
+
+    # `required :name` defaults the type to :string. A block instead of a
+    # type declares a nested hash of sub-fields.
+    def required(name, type = nil, **opts, &block)
+      add_field(name, type, required: true, opts: opts, &block)
+    end
+
+    def optional(name, type = nil, **opts, &block)
+      add_field(name, type, required: false, opts: opts, &block)
+    end
+
+    # Array of scalars (`of:`, default :string) or, with a block, an array
+    # of nested hashes. Optional unless `required: true`; `length:`
+    # constrains the element COUNT.
+    def array(name, **opts, &block)
+      name = field_name!(name)
+      assert_opts!(name, opts, ARRAY_OPTS)
+      required = opts.delete(:required) ? true : false
+
+      field = { name: name, kind: :array, required: required, **opts }
+      if block
+        raise ArgumentError, "#{LABEL}: array :#{name} takes of: OR a block, not both" if opts.key?(:of)
+
+        field[:fields] = nested_fields!(name, &block)
+        field.delete(:of)
+      else
+        field[:of] = scalar_type!(name, opts[:of] || :string)
+      end
+      validate_length!(name, field[:length]) if field.key?(:length)
+      validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
+      validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
+      validate_array_default!(field) if field.key?(:default)
+      @fields << field
+    end
+
+    private
+
+    def add_field(name, type, required:, opts:, &block)
+      name = field_name!(name)
+      if block
+        raise ArgumentError, "#{LABEL}: :#{name} takes a type OR a nested block, not both" if type
+
+        assert_opts!(name, opts, NESTED_OPTS)
+        @fields << { name: name, kind: :nested, required: required,
+                     fields: nested_fields!(name, &block), **opts }
+      else
+        assert_opts!(name, opts, SCALAR_OPTS)
+        field = { name: name, kind: :scalar, required: required,
+                  type: scalar_type!(name, type || :string), **opts }
+        validate_scalar_opts!(field)
+        @fields << field
+      end
+    end
+
+    def field_name!(name)
+      name = name.to_sym
+      if @fields.any? { |f| f[:name] == name }
+        raise ArgumentError, "#{LABEL}: field :#{name} is declared twice in the same contract"
+      end
+
+      name
+    end
+
+    def assert_opts!(name, opts, allowed)
+      unknown = opts.keys - allowed
+      return if unknown.empty?
+
+      raise ArgumentError,
+            "#{LABEL}: unknown option(s) #{unknown.map(&:inspect).join(', ')} for field :#{name} " \
+            "(allowed: #{allowed.map(&:inspect).join(', ')})"
+    end
+
+    def scalar_type!(name, type)
+      type = type.to_sym
+      return type if SCALAR_TYPES.include?(type)
+
+      raise ArgumentError, "#{LABEL}: field :#{name} has unknown type :#{type} " \
+                           "(supported: #{SCALAR_TYPES.join(', ')})"
+    end
+
+    def nested_fields!(name, &block)
+      builder = ContractBuilder.new
+      fields = builder.build(&block)
+      raise ArgumentError, "#{LABEL}: nested field :#{name} declares no sub-fields" if fields.empty?
+      if builder.finalizer
+        raise ArgumentError, "#{LABEL}: finalize is only available at the top level of a contract (found inside :#{name})"
+      end
+
+      fields
+    end
+
+    def validate_scalar_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
+      if field.key?(:in) && !field[:in].respond_to?(:include?)
+        raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
+      end
+
+      validate_string_only_opts!(field)
+      validate_length!(name, field[:length]) if field.key?(:length)
+      validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
+      validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
+      resolve_normalizer!(field)
+      validate_default!(field)
+    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)
+      return if field[:type] == :string
+
+      %i[format length normalize].each do |opt|
+        next unless field.key?(opt)
+
+        raise ArgumentError, "#{LABEL}: :#{opt} is only supported on :string fields (field :#{field[:name]} is :#{field[:type]})"
+      end
+    end
+
+    def validate_length!(name, length)
+      return if length.is_a?(Range) || length.is_a?(Integer)
+
+      raise ArgumentError, "#{LABEL}: :length for :#{name} must be a Range or Integer"
+    end
+
+    def validate_callable!(name, opt, value)
+      return if value.respond_to?(:call)
+
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{name} must be callable"
+    end
+
+    def resolve_normalizer!(field)
+      normalizer = field[:normalize]
+      return if normalizer.nil?
+      return if normalizer.respond_to?(:call) && !normalizer.is_a?(Symbol)
+
+      field[:normalize] = NORMALIZERS.fetch(normalizer.to_sym) do
+        raise ArgumentError, "#{LABEL}: unknown :normalize preset :#{normalizer} for field :#{field[:name]} " \
+                             "(presets: #{NORMALIZERS.keys.join(', ')}, or pass a Proc)"
+      end
+    end
+
+    # A default must satisfy the field's own contract — catching a bad
+    # default at class load beats shipping it to every request.
+    def validate_default!(field)
+      return unless field.key?(:default)
+
+      status, code = Coercion.check_scalar(field, field[:default])
+      return if status == :ok
+
+      raise ArgumentError, "#{LABEL}: :default for field :#{field[:name]} violates its own contract (#{code})"
+    end
+
+    def validate_array_default!(field)
+      default = field[:default]
+      raise ArgumentError, "#{LABEL}: :default for array :#{field[:name]} must be an Array" unless default.is_a?(Array)
+      return unless field[:of]
+
+      default.each do |element|
+        status, code = Coercion.cast(field[:of], element)
+        next if status == :ok
+
+        raise ArgumentError, "#{LABEL}: :default for array :#{field[:name]} contains an element violating of: :#{field[:of]} (#{code})"
+      end
+    end
+  end
+
+  # The `self` a finalize block runs on. Deliberately bare — no controller
+  # delegation — so a contract cannot grow request-state dependencies; its
+  # whole vocabulary is the hash it receives plus `violate!`.
+  class FinalizeRunner
+    def initialize(violations)
+      @violations = violations
+    end
+
+    # Records ONE violation and halts the finalize block immediately (the
+    # code after a violate! call never runs, so it can assume the checked
+    # invariant). The contract then fails as a normal 422.
+    def violate!(param, code)
+      @violations << { param: param.to_s, code: code.to_s }
+      throw :permittable_finalize_halt
+    end
+  end
+
+  class_methods do
+    # Declare a params contract. No positional actions = catch-all for the
+    # whole controller. Repeatable; the LAST rule matching the request's
+    # action wins.
+    #
+    #   root:    key to unwrap first (`require(:user)` equivalent); false
+    #            (default) reads top-level params. Missing root renders 400.
+    #   model:   a model class (or `true` to infer from controller_name)
+    #            enabling the schema-drift check on every non-virtual scalar
+    #            field.
+    #   unknown: :ignore (default) / :log / :error — what to do with
+    #            undeclared keys, at every nesting level.
+    #   enforce: false (default) validates lazily on the first
+    #            permitted_params call; true validates in a before_action.
+    def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, &block)
+      raise ArgumentError, "#{LABEL}: permit_params requires a block declaring the contract fields" unless block
+
+      unknown = unknown.to_sym
+      raise ArgumentError, "#{LABEL}: :unknown must be one of #{UNKNOWN_MODES.join(', ')}" unless UNKNOWN_MODES.include?(unknown)
+
+      builder = ContractBuilder.new
+      fields = builder.build(&block)
+      raise ArgumentError, "#{LABEL}: a contract must declare at least one field" if fields.empty?
+
+      model_class = resolve_permit_model(model)
+      guard_contract_columns!(model_class, fields) if model_class
+      register_sensitive_params(fields)
+
+      rule = { actions: actions.flatten.map(&:to_s).freeze, root: root && root.to_sym,
+               model: model_class, unknown: unknown, enforce: !!enforce, fields: fields,
+               finalize: builder.finalizer }.freeze
+      self.permittable_contracts = permittable_contracts + [rule]
+    end
+
+    # The LAST declared rule matching `action`, or nil.
+    def permit_rule_for(action)
+      action = action.to_s
+      permittable_contracts.reverse_each.find do |rule|
+        rule[:actions].empty? || rule[:actions].include?(action)
+      end
+    end
+
+    private
+
+    def resolve_permit_model(model)
+      case model
+      when nil, false then nil
+      when true then infer_permit_model
+      else
+        unless model.is_a?(Class) && model.respond_to?(:column_names)
+          raise ArgumentError, "#{LABEL}: :model must be an ActiveRecord model class, true (infer from controller name), or nil"
+        end
+
+        model
+      end
+    end
+
+    def infer_permit_model
+      unless respond_to?(:controller_name)
+        raise ArgumentError, "#{LABEL}: model: true needs controller_name to infer from — pass the class explicitly (model: SomeModel)"
+      end
+
+      name = controller_name.classify
+      name.safe_constantize ||
+        raise(ArgumentError, "#{LABEL}: model: true inferred #{name} from '#{controller_name}' but no such class exists — " \
+                             "pass the class explicitly (model: SomeModel)")
+    end
+
+    # The drift guard. Nested/array fields are implicitly virtual — only
+    # scalar fields map one-to-one onto columns.
+    def guard_contract_columns!(model_class, fields)
+      checked = fields.select { |f| f[:kind] == :scalar && !f[:virtual] }
+      return if checked.empty?
+
+      types = checked.to_h { |f| [f[:name], f[:type]] }
+      begin
+        ColumnGuard.ensure_columns_on!(LABEL, model_class, *checked.map { |f| f[:name] }, types: types)
+      rescue ArgumentError => e
+        raise ArgumentError, "#{e.message} If this parameter is not backed by a column, declare it with virtual: true."
+      end
+    end
+
+    def register_sensitive_params(fields)
+      fields.each do |field|
+        Permittable.filter_parameter_registry.add(field[:name]) if field[:sensitive]
+        register_sensitive_params(field[:fields]) if field[:fields]
+      end
+    end
+  end
+
+  # The contract's output: a HashWithIndifferentAccess of cast, validated,
+  # defaulted values for the given action (default: the current action).
+  # Absent optional fields are omitted. Raises InvalidParameters on
+  # violation; raises ArgumentError when no contract covers the action
+  # (that is a programmer error, not a client error). Memoized per action.
+  def permitted_params(action = nil)
+    action = (action || permittable_action_name).to_s
+    raise ArgumentError, "#{LABEL}: no action given and action_name is not set" if action.empty?
+
+    @permittable_validated ||= {}
+    return @permittable_validated[action] if @permittable_validated.key?(action)
+
+    rule = self.class.permit_rule_for(action)
+    raise ArgumentError, "#{LABEL}: no params contract declared covering ##{action}" unless rule
+
+    @permittable_validated[action] = validate_params_contract!(rule)
+  end
+
+  # before_action entry point (public so hosts can `skip_before_action
+  # :enforce_params_contract`). Only rules that opted in with
+  # `enforce: true` validate here.
+  def enforce_params_contract
+    action = permittable_action_name
+    return nil unless action
+
+    rule = self.class.permit_rule_for(action)
+    permitted_params(action) if rule && rule[:enforce]
+    nil
+  end
+
+  # rescue_from target — renders through the shared envelope (the host's
+  # render_error when present, the identical inline shape otherwise).
+  def render_invalid_parameters(error)
+    ErrorEnvelope.render(
+      self, message: error.message, status: error.status,
+      code: "invalid_parameters", details: error.details
+    )
+  end
+
+  private
+
+  def validate_params_contract!(rule)
+    violations = []
+    source = permittable_root_hash(rule, violations)
+    result = ActiveSupport::HashWithIndifferentAccess.new
+    if source
+      result = permittable_check_hash(rule[:fields], source, path: rule[:root] ? rule[:root].to_s : nil,
+                                      unknown: rule[:unknown], top_level: !rule[:root], violations: violations)
+    end
+    # finalize only sees a hash every field vouched for — never garbage.
+    if violations.empty? && rule[:finalize]
+      result = permittable_run_finalize(rule[:finalize], result, violations)
+    end
+    return result if violations.empty?
+
+    raise_invalid_parameters!(violations, status: source ? :unprocessable_entity : :bad_request)
+  end
+
+  def raise_invalid_parameters!(violations, status:)
+    violations.each(&:freeze)
+    ActiveSupport::Notifications.instrument(
+      "invalid_parameters.permittable",
+      controller: permittable_controller_name, action: permittable_action_name, details: violations
+    )
+    summary = violations.map { |v| "#{v[:param]} (#{v[:code]})" }.join(", ")
+    raise InvalidParameters.new("Invalid parameters: #{summary}", details: violations, status: status)
+  end
+
+  def permittable_run_finalize(finalizer, result, violations)
+    runner = FinalizeRunner.new(violations)
+    finalized = catch(:permittable_finalize_halt) do
+      runner.instance_exec(result, &finalizer)
+    end
+    return result unless violations.empty?
+    unless finalized.is_a?(Hash)
+      raise ArgumentError,
+            "#{LABEL}: finalize must return the params Hash (got #{finalized.class}) — " \
+            "end the block with the hash, e.g. `p` or `p.except(:scaffolding)`"
+    end
+
+    finalized.is_a?(ActiveSupport::HashWithIndifferentAccess) ? finalized : ActiveSupport::HashWithIndifferentAccess.new(finalized)
+  end
+
+  def permittable_root_hash(rule, violations)
+    raw = permittable_plain_params
+    return raw unless rule[:root]
+
+    value = raw[rule[:root].to_s]
+    return value if value.is_a?(Hash)
+
+    violations << { param: rule[:root].to_s, code: "missing" }
+    nil
+  end
+
+  # One plain HashWithIndifferentAccess view of `params`, whatever the
+  # stack: ActionController::Parameters (to_unsafe_h — this concern does
+  # its own permitting, that is the point) or a plain hash in tests.
+  def permittable_plain_params
+    raw = params
+    raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
+    ActiveSupport::HashWithIndifferentAccess.new(raw)
+  end
+
+  def permittable_check_hash(fields, hash, path:, unknown:, top_level:, violations:)
+    result = ActiveSupport::HashWithIndifferentAccess.new
+    fields.each do |field|
+      key = field[:name].to_s
+      full = permittable_path(path, key)
+      value = hash[key]
+
+      if permittable_absent?(value, hash, key)
+        if field.key?(:default)
+          result[key] = field[:default]
+        elsif field[:required]
+          violations << { param: full, code: "missing" }
+        end
+        next
+      end
+
+      permittable_check_field(field, value, full, result, unknown: unknown, violations: violations)
+    end
+    permittable_check_unknown(fields, hash, path: path, unknown: unknown, top_level: top_level, violations: violations)
+    result
+  end
+
+  def permittable_check_field(field, value, full, result, unknown:, violations:)
+    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 << { param: full, code: out }
+      end
+    when :nested
+      if value.is_a?(Hash)
+        result[key] = permittable_check_hash(field[:fields], ActiveSupport::HashWithIndifferentAccess.new(value),
+                                             path: full, unknown: unknown, top_level: false, violations: violations)
+      else
+        violations << { param: full, code: "invalid_type" }
+      end
+    when :array
+      if value.is_a?(Array)
+        result[key] = permittable_check_array(field, value, path: full, unknown: unknown, violations: violations)
+      else
+        violations << { param: full, code: "invalid_type" }
+      end
+    end
+  end
+
+  def permittable_check_array(field, value, path:, unknown:, violations:)
+    before = violations.length
+    if field[:length] && !Coercion.length_ok?(field[:length], value.length)
+      violations << { param: path, code: "length" }
+    end
+    out = value.each_with_index.map do |element, index|
+      permittable_check_element(field, element, "#{path}[#{index}]", unknown: unknown, violations: violations)
+    end
+    if field[:validate]
+      status, code = Coercion.check_custom(field[:validate], out)
+      violations << { param: path, code: code } unless status == :ok
+    end
+    # Transform only a fully-valid array — a partially-nil one (element
+    # violations) would hand user code garbage it never agreed to see.
+    out = field[:transform].call(out) if field[:transform] && violations.length == before
+    out
+  end
+
+  def permittable_check_element(field, element, path, unknown:, violations:)
+    if field[:fields]
+      unless element.is_a?(Hash)
+        violations << { param: path, code: "invalid_type" }
+        return nil
+      end
+      return permittable_check_hash(field[:fields], ActiveSupport::HashWithIndifferentAccess.new(element),
+                                    path: path, unknown: unknown, top_level: false, violations: violations)
+    end
+
+    status, out = Coercion.cast(field[:of], element)
+    return out if status == :ok
+
+    violations << { param: path, code: out }
+    nil
+  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?)
+  end
+
+  def permittable_check_unknown(fields, hash, path:, unknown:, top_level:, violations:)
+    return if unknown == :ignore
+
+    declared = fields.map { |f| f[:name].to_s }
+    extra = hash.keys.map(&:to_s) - declared
+    extra -= ROUTING_KEYS if top_level
+    return if extra.empty?
+
+    if unknown == :error
+      extra.each { |key| violations << { param: permittable_path(path, key), code: "unknown" } }
+    elsif respond_to?(:logger) && logger
+      logger.warn("#{LABEL}: unknown parameter(s) ignored by the ##{permittable_action_name} contract: " \
+                  "#{extra.map { |key| permittable_path(path, key) }.join(', ')}")
+    end
+  end
+
+  def permittable_path(path, key)
+    path ? "#{path}.#{key}" : key
+  end
+
+  def permittable_action_name
+    respond_to?(:action_name) && action_name ? action_name.to_s : nil
+  end
+
+  def permittable_controller_name
+    return controller_path if respond_to?(:controller_path)
+
+    self.class.name
+  end
+end
+
+# Boot-time integration (filter_parameters registration), Rails apps only
+require "permittable/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: permittable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ethan Nguyen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'Declarative per-action params contracts: strict typing/coercion, validation,
+  defaults, machine-readable 422s, output reshaping (transform/finalize), and a boot-time
+  schema-drift guard that fails the deploy when a permitted field''s column was dropped.
+  Strong parameters with types, validation, and drift detection.'
+email:
+- doctorit@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/permittable.rb
+- lib/permittable/column_guard.rb
+- lib/permittable/error_envelope.rb
+- lib/permittable/filter_parameter_registry.rb
+- lib/permittable/railtie.rb
+- lib/permittable/version.rb
+homepage: https://github.com/VSN2015/permittable
+licenses:
+- MIT
+metadata:
+  license: MIT
+  homepage_uri: https://github.com/VSN2015/permittable
+  source_code_uri: https://github.com/VSN2015/permittable
+  changelog_uri: https://github.com/VSN2015/permittable/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Typed, validated params contracts for Rails controllers + schema-drift guard
+test_files: []