permittable 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 577c3a6c767e85dd2b3fc0ad8049e1d0ec77d2b87bc1f6eedca351161f589ef9
-  data.tar.gz: bed2c92d56a70abf45f8f9cc4b779788886623b442054d63727893f891eb0c13
+  metadata.gz: e6009aed769f45203bb8053f4310d4ac986ec941815704e613f63bddf819bf92
+  data.tar.gz: 721cead2003e010c773e4bab9de20830d85f40182a049b8e4db6fa82d1f377d7
 SHA512:
-  metadata.gz: bd955e930e66036f2bffd9f006996ad0713e3582eda8386e51bc668d42432db7f941bef9724ba5c6589e85be4ce91827cc8536f49ca6c0d698562de0aee65520
-  data.tar.gz: a61f63950413801e405a6690e141a35616d974cc347bdae86e9a6f239a75e89225604b973acb4daf4b7daa25492e767175f674de6376df62eb0128e27f16fa62
+  metadata.gz: 5ff703088a1c1389cc49150521380c56f937d4ba0f99de0137e7390a91fa66a16bdad09092f0c65964b94e332bee170b17bdc6d7e9d03c11a7b2020f95953c78
+  data.tar.gz: 64b5097368d5df03d8dfacb4c9eb79cf6ecb08e2c0b933a80281201139e496f143f0336d886d4a4d33a15dfc0f2c7642f10ee5641e625874a80526717386d869

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 <!-- CHANGELOG.md -->
 
+## 0.4.0 (2026-08-24)
+<!-- title: monitor mode -->
+
+The rollout switch. Adopting contracts on a live API — or tightening an existing one — used to mean flipping unknown clients from "accepted" to "422" in a single deploy. A contract can now run in **monitor mode**: the full pipeline executes (unwrap, cast, validate, defaults), but a violation is **reported instead of rejected** and the request proceeds exactly as it did before the contract existed. Deploy monitoring, dashboard the would-be rejections, then enforce controller by controller — every 422 you finally return is one you already counted.
+
+### Added
+- **`mode: :monitor` on `permit_params`, and an app-wide `Permittable.mode` default** (`:enforce` unless set; a rule's own `mode:` always wins, in both directions). On a violating request in monitor mode nothing raises and nothing renders: the `invalid_parameters.permittable` event fires with `mode: :monitor`, the logger warns with the offending paths, and `permitted_params` returns the **raw pass-through** — exactly what the client sent, no casts, no defaults, no transforms (a missing `root:` passes an empty hash; a rootless contract drops only the router's bookkeeping keys). Monitor rules validate **eagerly in the `before_action` regardless of `enforce:`**, so telemetry never depends on the action calling `permitted_params` — legacy actions still reading `params` directly are exactly the ones being monitored.
+- **`permittable_violations(action = nil)`** — the recorded violation details for the (memoized) validation of `action`, `[]` when the request was clean. The monitor-mode observable; under enforce it swallows its own trigger's raise, making "would this request fail?" a one-liner in tests.
+- **`mode:` key on the `invalid_parameters.permittable` payload** (`:enforce` / `:monitor`), so one subscriber can dashboard enforced rejections and monitored would-be rejections side by side. Additive — existing subscribers are unaffected.
+- **`x-permittable-mode: "monitor"`** on exported OpenAPI operations whose rule declares monitor mode — the docs must not promise a 422 the server doesn't yet send. Only the per-rule declaration is exported; the app-wide `Permittable.mode` is runtime configuration, not contract data.
+
+Contracts that don't opt in are byte-for-byte unaffected: the default mode is `:enforce` and the enforce path behaves exactly as before.
+
+## 0.3.0 (2026-08-24)
+<!-- title: OpenAPI export -->
+
+Contracts gain a third reader. The registry that already drives the validator and the schema-drift guard now also generates **OpenAPI 3.1** — because the schema is emitted from the same frozen data the server enforces, the docs cannot drift from the validation. Fully additive; no behaviour of existing contracts changes.
+
+### Added
+- **`Permittable::JsonSchema`** — converts rules and fields into JSON Schema (draft 2020-12): types map onto their canonical JSON encodings (`:decimal` as `["string", "number"]` + `format: decimal`), `in:` → `enum`/`minimum`/`maximum`, `length:` → `minLength`/`maxLength` or `minItems`/`maxItems`, `format:` → `pattern` with `\A`/`\z` translated to `^`/`$`, `default:` → `default`, `unknown: :error` → `additionalProperties: false` at every level, `root:` → a required wrapper object, `sensitive:` → `writeOnly: true`. Required strings get `minLength: 1` (`""` is absent). What has no ECMA/JSON-Schema equivalent stays visible instead of guessed: Ruby-only or flagged regexps export as `x-permittable-pattern`, `validate:`/`transform:` as `x-permittable-custom-validation`/`x-permittable-transformed`, non-numeric Ranges as `x-permittable-range`. Emission is deterministic, so generated documents are committable and diff-stable.
+- **`Permittable::OpenAPI`** — assembles full OpenAPI 3.1 documents (`.document`) and fragments (`.request_body_for`, `.operations_for`, `.components`) from any set of controllers, plain Ruby, no Rails required. Operations resolve through `permit_rule_for`, so last-matching-rule-wins holds in the docs exactly as at request time; every operation references shared components typing the 422 (and, for rooted contracts, 400) error envelope. Catch-all rules expand through `action_methods` (the concern's own public methods excluded) or surface as `"*"` + `x-permittable-catch-all`; unrouted operations land in `x-permittable-controllers` rather than being dropped.
+- **`bin/rails permittable:openapi[output]`** — rake task (loaded by the Railtie) that eager-loads the app, collects every controller with contracts, maps actions onto `paths` via the route set (`:id` → `{id}`), and prints or writes the document. `OPENAPI_TITLE`/`OPENAPI_VERSION` override the `info` block.
+- **`desc:` and `example:` field options, `desc:` on `permit_params`** — documentation passthrough carried on the frozen contract data and ignored by the runtime. An `example:` is validated against its own field's contract at class load, exactly like `default:`, so published examples can't lie either.
+
 ## 0.2.0 (2026-08-18)
 <!-- title: custom error messages -->
 

data/README.md

@@ -54,6 +54,7 @@ A violating request never reaches your action:
 - [Violations and error responses](#violations-and-error-responses) · [Custom error messages](#custom-error-messages-message) · [Unknown parameters](#unknown-parameters)
 - [Output reshaping](#output-reshaping-transform-and-finalize) · [The schema-drift guard](#the-schema-drift-guard)
 - [Sensitive parameters](#sensitive-parameters-and-log-redaction) · [Instrumentation](#instrumentation)
+- [Monitor mode](#monitor-mode-roll-out-without-rejecting) · [Exporting OpenAPI](#exporting-openapi-docs-that-cannot-drift)
 - [API reference](#api-reference) · [Errors caught at class load](#errors-caught-at-class-load) · [Compatibility](#compatibility)
 
 ---
@@ -70,6 +71,8 @@ A violating request never reaches your action:
 | Machine-readable error details | ❌ | ❌ | ✅ |
 | Reshapes output | ❌ | ❌ | ✅ |
 | Checked against your schema at boot | ❌ | ❌ | ✅ |
+| Exports OpenAPI / JSON Schema | ❌ | ❌ | ✅ |
+| Report-only rollout mode | ❌ | ❌ | ✅ |
 
 The design rests on one idea: **a contract is data, not code.** It is declared once at the class level, frozen, inheritable, and introspectable. Everything else here follows from that — the drift guard can read it at boot, `finalize` can run on a bare object with no controller state, and the whole contract can be printed or tested without a request.
 
@@ -106,10 +109,12 @@ params
 
 Validation is **lazy by default**: it runs on the first `permitted_params` call, so an action that never reads params never pays for it. Pass `enforce: true` to run it in a `before_action` instead, rejecting bad requests before the action body executes. Results are **memoized per action**.
 
+In [monitor mode](#monitor-mode-roll-out-without-rejecting) the same flow runs, but a violation is reported instead of raised and the request proceeds with the raw params passed through.
+
 ## Declaring a contract
 
 ```ruby
-permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, &contract)
+permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, mode: nil, desc: nil, &contract)
 ```
 
 | Option | Default | Meaning |
@@ -119,6 +124,8 @@ permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: fals
 | `model:` | `nil` | Model class, or `true` to infer from `controller_name`, enabling the [drift guard](#the-schema-drift-guard) |
 | `unknown:` | `:ignore` | `:ignore` / `:log` / `:error` — how to treat undeclared keys |
 | `enforce:` | `false` | `false` validates lazily on first use; `true` validates in a `before_action` |
+| `mode:` | `nil` | `nil` follows `Permittable.mode`; `:monitor` reports violations instead of rejecting — see [monitor mode](#monitor-mode-roll-out-without-rejecting) |
+| `desc:` | `nil` | Documentation only — becomes the operation description in [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) |
 
 `permit_params` is **repeatable**, and **the last matching rule wins**. Contracts behave like configuration: a base controller declares a catch-all, and a subclass overrides it for specific actions.
 
@@ -186,6 +193,8 @@ Which options are legal depends on the field kind — anything else raises at cl
 | `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`) |
 | `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:` |
 
 ¹ `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.
 
@@ -378,14 +387,99 @@ ActiveSupport::Notifications.subscribe("invalid_parameters.permittable") do |*,
 end
 ```
 
+## Monitor mode (roll out without rejecting)
+
+Adopting contracts on a live API — or tightening one field on an existing contract — has a chicken-and-egg problem: you cannot know what the 422s would break until you enforce them, and you dare not enforce them until you know. Old mobile app versions, third-party integrations, and forgotten cron jobs all send what they send. `mode: :monitor` resolves it: the full pipeline runs (unwrap, cast, validate, defaults), but a violation is **reported instead of rejected** and the request proceeds exactly as it did before the contract existed.
+
+```ruby
+class OrdersController < ApplicationController
+  permit_params :create, root: :order, mode: :monitor do
+    required :sku,      :string
+    optional :quantity, :integer, in: 1..99
+  end
+
+  # The action doesn't have to change while monitoring — it can keep reading
+  # params the old way; the contract validates in the before_action.
+end
+```
+
+Or flip the whole app at once and pin controllers to their final mode one at a time — a rule's own `mode:` always beats the global, in both directions:
+
+```ruby
+# config/initializers/permittable.rb
+Permittable.mode = ENV.fetch("PERMITTABLE_MODE", "enforce").to_sym
+```
+
+On a violating request in monitor mode:
+
+- **Nothing raises and nothing renders** — the action runs.
+- The [`invalid_parameters.permittable` event](#instrumentation) fires with `mode: :monitor` in the payload (enforced violations carry `mode: :enforce`), and the logger warns with the offending paths. Point your existing subscriber at a dashboard and you have a per-controller rollout report.
+- `permitted_params` returns the **raw pass-through**: exactly what the client sent, untouched — no casts, no defaults, no transforms. A missing `root:` passes an empty hash (the envelope you asked for isn't there); a rootless contract drops only Rails' routing keys.
+- `permittable_violations` returns the recorded details (`[]` when the request was clean), if the action wants to branch on or tag the traffic.
+
+Monitor-mode rules validate **eagerly in the `before_action`, regardless of `enforce:`** — telemetry must not depend on the action calling `permitted_params`, since legacy actions still reading `params` directly are exactly the ones worth monitoring. (On a plain-Ruby host without `before_action`, validation stays lazy.)
+
+The rollout recipe:
+
+1. Write contracts for a legacy controller. The action code stays as-is.
+2. Deploy with `PERMITTABLE_MODE=monitor`. Behaviour is unchanged; telemetry starts.
+3. Watch the dashboard. Every entry is a real client that would have been rejected — fix the contract, or wait for that traffic to drain.
+4. Flip to enforce, controller by controller. Every 422 you now return is one you already counted.
+
+[Exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) marks operations whose rule declares `mode: :monitor` with `x-permittable-mode: "monitor"` — the docs shouldn't promise a 422 the server doesn't yet send. Only the per-rule declaration is exported: the global `Permittable.mode` is runtime configuration, not contract data.
+
+## Exporting OpenAPI (docs that cannot drift)
+
+Because a contract is data, it has a third reader beyond the validator and the drift guard: an exporter that emits **OpenAPI 3.1** (whose request bodies are plain JSON Schema). The schema is generated from the same frozen data the server enforces, so — like the drift guard, pointed outward — the docs cannot lie:
+
+```sh
+bin/rails permittable:openapi                       # JSON to stdout
+bin/rails "permittable:openapi[openapi/api.json]"   # write to a file
+```
+
+The task eager-loads the app (also exercising the drift guard), collects every controller with contracts, and maps documented actions onto `paths` via the route set. `OPENAPI_TITLE` / `OPENAPI_VERSION` override the `info` block. Pipe the output through Swagger UI, Redoc, Postman, or [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) and your frontend gets compile-time types for every request body.
+
+Or build fragments programmatically — no Rails required:
+
+```ruby
+Permittable::JsonSchema.rule(UsersController.permit_rule_for(:create))  # request-body schema
+Permittable::OpenAPI.request_body_for(UsersController, :create)         # OpenAPI requestBody object
+Permittable::OpenAPI.operations_for(UsersController)                    # { action => operation }
+Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
+```
+
+How contracts map:
+
+| Contract | Emitted schema |
+|---|---|
+| `required` / `optional` | the object's `required:` array; required strings also get `minLength: 1` (`""` is absent) |
+| `:string` `:integer` `:float` `:boolean` | `string` / `integer` / `number` / `boolean` |
+| `:date` / `:datetime` | `string` + `format: date` / `date-time` |
+| `:decimal` | `type: ["string", "number"]` + `format: decimal` (string is the precision-safe encoding) |
+| `in:` Array / numeric Range | `enum` / `minimum` + `maximum` (exclusive ends honoured) |
+| `length:` | `minLength`/`maxLength` on strings, `minItems`/`maxItems` on arrays |
+| `format:` | `pattern`, with `\A`/`\z` translated to `^`/`$` |
+| `default:` / `desc:` / `example:` | `default` / `description` / `examples` |
+| nested block / `array` | `object` + `properties` / `array` + `items` |
+| `unknown: :error` | `additionalProperties: false`, at every nesting level |
+| `root:` | the wrapping object, itself required |
+| `sensitive: true` | `writeOnly: true` (never echoed in responses) |
+
+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.
+
+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.
+
 ## API reference
 
 ### Instance methods
 
 | Method | Purpose |
 |---|---|
-| `permitted_params(action = action_name)` | The cast, validated, defaulted `HashWithIndifferentAccess`. Memoized per action. Raises `InvalidParameters` on violation, or `ArgumentError` when no contract covers the action |
-| `enforce_params_contract` | The `before_action` entry point. Only validates rules declared `enforce: true`. Public, so hosts can `skip_before_action` it |
+| `permitted_params(action = action_name)` | The cast, validated, defaulted `HashWithIndifferentAccess`. Memoized per action. Raises `InvalidParameters` on violation (in [monitor mode](#monitor-mode-roll-out-without-rejecting), returns the raw pass-through instead), or `ArgumentError` when no contract covers the action |
+| `permittable_violations(action = action_name)` | The violation details recorded by validating `action` — `[]` when clean. Triggers the same memoized validation; under enforce it swallows the raise, making "would this request fail?" a one-liner |
+| `enforce_params_contract` | The `before_action` entry point. Validates rules declared `enforce: true` and all [monitor-mode](#monitor-mode-roll-out-without-rejecting) rules. Public, so hosts can `skip_before_action` it |
 | `render_invalid_parameters(error)` | The `rescue_from` target. Renders via the host's `render_error` when defined, the inline envelope otherwise |
 
 ### Class methods
@@ -402,7 +496,10 @@ end
 |---|---|
 | `Permittable.filter_parameter_registry` | The live registry of `sensitive:` field names |
 | `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry |
+| `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`) |
+| `Permittable::OpenAPI` | OpenAPI 3.1 assembly (`.document`, `.operations_for`, `.request_body_for`, `.components`) |
 
 ## Errors caught at class load
 
@@ -415,12 +512,13 @@ A bad contract is a programmer error, so it fails when the class loads — never
 - `format:`, `length:`, or `normalize:` on a non-`:string` field
 - `length:` that isn't a `Range` or `Integer`; `in:` that doesn't respond to `include?`
 - `validate:` or `transform:` that isn't callable
-- A `default:` that violates its own field's contract, or an array `default:` whose elements violate `of:`
+- A `default:` or `example:` that violates its own field's contract, or an array `default:`/`example:` whose elements violate `of:`
 - `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
 - `finalize` declared twice, without a block, or inside a nested block
 - `permit_params` without a block, or an invalid `unknown:` mode
+- An invalid `mode:` (and `Permittable.mode =` rejects invalid values at assignment)
 - A `model:` that isn't an ActiveRecord class, or `model: true` that can't be inferred
 
 ## Compatibility
@@ -438,7 +536,7 @@ Using [concerns_on_rails](https://github.com/VSN2015/concerns_on_rails)? `Concer
 
 ```sh
 bundle install
-bundle exec rspec      # 76 examples
+bundle exec rspec      # 125 examples
 bundle exec rubocop
 ```
 

data/lib/permittable/json_schema.rb

@@ -0,0 +1,196 @@
+module Permittable
+  # Converts frozen contract data — the rule and field hashes built by
+  # ContractBuilder — into JSON Schema (draft 2020-12, the dialect OpenAPI 3.1
+  # request bodies use). This is the third reader of the contract registry,
+  # after the request validator and the column guard: because a contract is
+  # data, a schema exported from it cannot drift from what the server
+  # actually enforces.
+  #
+  # The exported schema describes the DECLARED INPUT SHAPE in its canonical
+  # JSON encoding. Two deliberate consequences:
+  #   * Coercion additionally accepts string-encoded scalars ("42", "true")
+  #     for form/query payloads; the schema documents the JSON types only.
+  #   * `validate:`/`transform:`/`finalize` are opaque callables — they never
+  #     change what a client may SEND, so fields carrying them are flagged
+  #     with `x-permittable-*` extensions rather than mistranslated.
+  #
+  # Emission is deterministic (fixed key insertion order, declaration-order
+  # properties) so generated documents are committable and diff-stable.
+  module JsonSchema
+    module_function
+
+    SCALAR_SCHEMAS = {
+      string: { "type" => "string" },
+      integer: { "type" => "integer" },
+      float: { "type" => "number" },
+      # Coercion accepts Numeric or String for :decimal; string is the
+      # precision-safe form, so both encodings are documented.
+      decimal: { "type" => %w[string number], "format" => "decimal" },
+      boolean: { "type" => "boolean" },
+      date: { "type" => "string", "format" => "date" },
+      datetime: { "type" => "string", "format" => "date-time" }
+    }.freeze
+
+    # 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.
+    UNTRANSLATABLE = /
+      \\[ZhHKRG]          |
+      \(\?[a-z-]+[:)]     |
+      \(\?~               |
+      \(\?\(              |
+      \[\[:               |
+      [*+?]\+
+    /x
+
+    # Request-body schema for one rule from `permittable_contracts` /
+    # `permit_rule_for`: the object schema of its fields, wrapped in the
+    # `root:` envelope when the rule declares one. The wrapper itself stays
+    # permissive even under `unknown: :error` — the runtime never inspects
+    # sibling keys outside the root.
+    def rule(permit_rule)
+      schema = object(permit_rule[:fields], unknown: permit_rule[:unknown])
+      return schema unless permit_rule[:root]
+
+      root = permit_rule[:root].to_s
+      { "type" => "object", "properties" => { root => schema }, "required" => [root] }
+    end
+
+    # Object schema for a field list; `unknown:` applies at every nesting
+    # level, exactly like the runtime check.
+    def object(fields, unknown: :ignore)
+      schema = {
+        "type" => "object",
+        "properties" => fields.to_h { |f| [f[:name].to_s, field(f, unknown: unknown)] }
+      }
+      required = fields.select { |f| f[:required] }.map { |f| f[:name].to_s }
+      schema["required"] = required unless required.empty?
+      schema["additionalProperties"] = false if unknown == :error
+      schema
+    end
+
+    # Schema fragment for one field hash of any kind.
+    def field(field, unknown: :ignore)
+      schema = case field[:kind]
+               when :scalar then scalar_schema(field)
+               when :nested then object(field[:fields], unknown: unknown)
+               when :array then array_schema(field, unknown: unknown)
+               end
+      annotate(schema, field)
+    end
+
+    def scalar_schema(field)
+      schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
+      apply_in!(schema, field[:in])
+      apply_string_bounds!(schema, field)
+      apply_pattern!(schema, field[:format])
+      schema
+    end
+
+    def array_schema(field, unknown:)
+      schema = { "type" => "array" }
+      min, max = length_bounds(field[:length])
+      schema["minItems"] = min if min
+      schema["maxItems"] = max if max
+      schema["items"] = field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).dup
+      schema
+    end
+
+    def apply_in!(schema, allowed)
+      return unless allowed
+
+      unless allowed.is_a?(Range)
+        schema["enum"] = allowed.map { |v| json_value(v) }
+        return
+      end
+      # Runtime bounds-checks Ranges with cover?; numeric endpoints map onto
+      # minimum/maximum, anything else (a Range of strings) has no JSON
+      # Schema equivalent and is carried as an extension.
+      unless allowed.begin.is_a?(Numeric) || allowed.end.is_a?(Numeric)
+        schema["x-permittable-range"] = allowed.inspect
+        return
+      end
+      schema["minimum"] = json_value(allowed.begin) if allowed.begin
+      schema[allowed.exclude_end? ? "exclusiveMaximum" : "maximum"] = json_value(allowed.end) if allowed.end
+    end
+
+    def apply_string_bounds!(schema, field)
+      return unless field[:type] == :string
+
+      min, max = length_bounds(field[:length])
+      # "" is ABSENT and an absent required field violates, so a required
+      # string can never validly be empty — the schema says so.
+      min = 1 if field[:required] && min.to_i < 1
+      schema["minLength"] = min if min
+      schema["maxLength"] = max if max
+    end
+
+    def apply_pattern!(schema, regexp)
+      return unless regexp
+
+      pattern = ecma_pattern(regexp)
+      if pattern
+        schema["pattern"] = pattern
+      else
+        schema["x-permittable-pattern"] = regexp.inspect
+      end
+    end
+
+    # Conservative Ruby → ECMA-262 translation: \A/\z anchors become ^/$.
+    # Flagged regexps bail entirely (JSON Schema's `pattern` has no flag
+    # slot, and /x//m/i all change semantics), as does any source containing
+    # an untranslatable construct.
+    def ecma_pattern(regexp)
+      return nil unless regexp.options.zero?
+
+      source = regexp.source
+      return nil if source.match?(UNTRANSLATABLE)
+
+      source.gsub('\A', "^").gsub('\z', "$")
+    end
+
+    # length: reasons about characters on strings and element count on
+    # arrays; either way it is an exact Integer or a Range (possibly endless
+    # / beginless, possibly exclusive).
+    def length_bounds(spec)
+      case spec
+      when Integer then [spec, spec]
+      when Range
+        max = spec.end && spec.exclude_end? ? spec.end - 1 : spec.end
+        [spec.begin, max]
+      else [nil, nil]
+      end
+    end
+
+    # Documentation keys shared by every field kind. `default:`/`example:`
+    # are authored values (possibly Date/Time/BigDecimal literals), so they
+    # are re-encoded as JSON scalars.
+    def annotate(schema, field)
+      schema["default"] = json_value(field[:default]) if field.key?(:default)
+      schema["examples"] = [json_value(field[:example])] if field.key?(:example)
+      schema["description"] = field[:desc] if field[:desc]
+      if field[:sensitive]
+        schema["writeOnly"] = true
+        schema["x-permittable-sensitive"] = true
+      end
+      schema["x-permittable-custom-validation"] = true if field[:validate]
+      schema["x-permittable-transformed"] = true if field[:transform]
+      schema
+    end
+
+    def json_value(value)
+      case value
+      when Array then value.map { |v| json_value(v) }
+      when BigDecimal then value.to_s("F")
+      when Time then value.utc.iso8601
+      # DateTime subclasses Date, so it must match first.
+      when DateTime then value.to_time.utc.iso8601
+      when Date then value.iso8601
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end

data/lib/permittable/open_api.rb

@@ -0,0 +1,216 @@
+require "permittable/version"
+require "permittable/json_schema"
+
+module Permittable
+  # Assembles OpenAPI 3.1 fragments and documents from Permittable contracts.
+  # Plain Ruby over the frozen contract registry — Rails is not required; the
+  # `permittable:openapi` rake task (loaded by the Railtie) supplies the
+  # Rails-only parts: eager loading, controller discovery, and the route
+  # descriptors that turn operations into real `paths` entries.
+  #
+  # Everything the exporter cannot know is left visible rather than guessed:
+  # actions covered only by a catch-all rule on a host without
+  # `action_methods` appear under the "*" key with `x-permittable-catch-all`,
+  # and operations with no matching route land in `x-permittable-controllers`
+  # instead of being dropped silently.
+  module OpenAPI
+    module_function
+
+    # The error envelope rendered by render_invalid_parameters (see
+    # ErrorEnvelope): code/details are present on every violation this gem
+    # raises, message always.
+    ERROR_SCHEMA = {
+      "type" => "object",
+      "properties" => {
+        "success" => { "type" => "boolean", "enum" => [false] },
+        "error" => {
+          "type" => "object",
+          "properties" => {
+            "message" => { "type" => "string" },
+            "code" => { "type" => "string", "enum" => ["invalid_parameters"] },
+            "details" => {
+              "type" => "array",
+              "items" => {
+                "type" => "object",
+                "properties" => {
+                  "param" => {
+                    "type" => "string",
+                    "description" => "Fully-qualified parameter path, e.g. user.address.zip or line_items[1].sku"
+                  },
+                  "code" => {
+                    "type" => "string",
+                    "description" => "missing / invalid_type / inclusion / format / length / unknown / invalid, " \
+                                     "or a contract-specific symbol"
+                  }
+                },
+                "required" => %w[param code]
+              }
+            }
+          },
+          "required" => %w[message]
+        }
+      },
+      "required" => %w[success error]
+    }.freeze
+
+    # Instance methods the concern itself adds to every including controller;
+    # action_methods reports them as actions (they are public by design), but
+    # they are never routed and must not be documented as endpoints. Resolved
+    # lazily — at file-load time the concern's module body may not have run.
+    def concern_methods
+      @concern_methods ||= Permittable.public_instance_methods(false).map(&:to_s).freeze
+    end
+
+    # Shared `components` for any document referencing Permittable responses.
+    def components
+      {
+        "schemas" => { "PermittableInvalidParameters" => ERROR_SCHEMA },
+        "responses" => {
+          "PermittableBadRequest" => error_response(
+            "The root: key is missing or not an object — the request envelope itself is malformed."
+          ),
+          "PermittableUnprocessableEntity" => error_response(
+            "One or more parameters violated the action's contract; details names each offender."
+          )
+        }
+      }
+    end
+
+    def error_response(description)
+      {
+        "description" => description,
+        "content" => {
+          "application/json" => {
+            "schema" => { "$ref" => "#/components/schemas/PermittableInvalidParameters" }
+          }
+        }
+      }
+    end
+
+    # OpenAPI requestBody object for the contract covering `action`, nil when
+    # no contract does. `required` mirrors the runtime: a rooted contract
+    # rejects a bodyless request outright (400), and so does any top-level
+    # required field (missing).
+    def request_body_for(controller, action)
+      rule = controller.permit_rule_for(action)
+      rule && rule_request_body(rule)
+    end
+
+    def rule_request_body(rule)
+      {
+        "required" => !!(rule[:root] || rule[:fields].any? { |f| f[:required] }),
+        "content" => { "application/json" => { "schema" => JsonSchema.rule(rule) } }
+      }
+    end
+
+    # { action => operation } for every action the controller's contracts
+    # cover, resolved through permit_rule_for so last-matching-rule-wins holds
+    # in the documentation exactly as it does at request time.
+    def operations_for(controller)
+      documented_actions(controller).to_h { |action| [action, operation_for(controller, action)] }
+    end
+
+    # Explicitly-declared actions in declaration order; when a catch-all rule
+    # exists, the controller's remaining action_methods (sorted) follow — or
+    # the literal "*" on hosts without action_methods (plain-Ruby params
+    # ducks), where the covered action set is unknowable.
+    def documented_actions(controller)
+      contracts = controller.permittable_contracts
+      explicit = contracts.flat_map { |rule| rule[:actions] }.uniq
+      return explicit unless contracts.any? { |rule| rule[:actions].empty? }
+      return explicit + ["*"] unless controller.respond_to?(:action_methods)
+
+      explicit + (controller.action_methods.map(&:to_s).sort - explicit - concern_methods)
+    end
+
+    def operation_for(controller, action)
+      rule = if action == "*"
+               controller.permittable_contracts.reverse_each.find { |r| r[:actions].empty? }
+             else
+               controller.permit_rule_for(action)
+             end
+      operation = {}
+      key = controller_key(controller)
+      operation["operationId"] = "#{key.tr('/', '_')}_#{action}" if key && action != "*"
+      operation["description"] = rule[:desc] if rule[:desc]
+      operation["requestBody"] = rule_request_body(rule)
+      operation["responses"] = responses_for(rule)
+      # The docs must not promise a 422 the server doesn't yet send. Only
+      # the rule's own declaration is contract data — the app-wide
+      # Permittable.mode is runtime configuration the export can't see.
+      operation["x-permittable-mode"] = "monitor" if rule[:mode] == :monitor
+      operation["x-permittable-catch-all"] = true if action == "*"
+      operation
+    end
+
+    def responses_for(rule)
+      responses = {}
+      responses["400"] = { "$ref" => "#/components/responses/PermittableBadRequest" } if rule[:root]
+      responses["422"] = { "$ref" => "#/components/responses/PermittableUnprocessableEntity" }
+      responses
+    end
+
+    # A complete OpenAPI 3.1 document. `routes:` is an optional array of
+    # { controller:, action:, verb:, path: } descriptors (see rails_routes);
+    # operations with a matching descriptor become `paths` entries, the rest
+    # are grouped by controller under `x-permittable-controllers`.
+    def document(controllers:, info: {}, routes: nil)
+      paths = {}
+      unrouted = {}
+      controllers.each do |controller|
+        operations = operations_for(controller)
+        next if operations.empty?
+
+        place_operations(controller, operations, routes, paths, unrouted)
+      end
+      doc = {
+        "openapi" => "3.1.0",
+        "info" => { "title" => "Permittable contracts", "version" => VERSION }.merge(info),
+        "paths" => paths,
+        "components" => components
+      }
+      doc["x-permittable-controllers"] = unrouted unless unrouted.empty?
+      doc
+    end
+
+    def place_operations(controller, operations, routes, paths, unrouted)
+      key = controller_key(controller) || controller.inspect
+      operations.each do |action, operation|
+        matched = routes_for(routes, key, action)
+        if matched.empty?
+          (unrouted[key] ||= {})[action] = operation
+        else
+          matched.each { |route| (paths[route[:path]] ||= {})[route[:verb].to_s.downcase] = operation }
+        end
+      end
+    end
+
+    def routes_for(routes, controller_key, action)
+      return [] if routes.nil? || action == "*"
+
+      routes.select { |r| r[:controller].to_s == controller_key && r[:action].to_s == action }
+    end
+
+    # { controller:, action:, verb:, path: } descriptors from a Rails
+    # application's route set. Duck-typed against Journey routes (each one
+    # responds to requirements / verb / path.spec) so it stays unit-testable
+    # without Rails; Rails path params (:id) become OpenAPI templates ({id}).
+    def rails_routes(app)
+      app.routes.routes.filter_map do |route|
+        requirements = route.requirements
+        verb = route.verb.to_s
+        next if requirements[:controller].nil? || requirements[:action].nil? || verb.empty?
+
+        path = route.path.spec.to_s.sub("(.:format)", "").gsub(/:(\w+)/) { "{#{Regexp.last_match(1)}}" }
+        { controller: requirements[:controller], action: requirements[:action],
+          verb: verb.split("|").first.downcase, path: path }
+      end
+    end
+
+    def controller_key(controller)
+      return controller.controller_path if controller.respond_to?(:controller_path)
+
+      controller.name
+    end
+  end
+end

data/lib/permittable/railtie.rb

@@ -12,5 +12,9 @@ module Permittable
       filter = ::Permittable.filter_parameter_registry.to_proc
       app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
     end
+
+    rake_tasks do
+      load File.expand_path("tasks/openapi.rake", __dir__)
+    end
   end
 end

data/lib/permittable/tasks/openapi.rake

@@ -0,0 +1,44 @@
+# Exports every Permittable contract in the app as an OpenAPI 3.1 document —
+# the docs-that-cannot-drift counterpart to the schema-drift guard. Eager
+# loading makes every controller's permit_params macro run (also exercising
+# the drift guard), then the route set maps documented actions onto paths.
+#
+#   bin/rails permittable:openapi                       # JSON to stdout
+#   bin/rails "permittable:openapi[openapi/api.json]"   # write to a file
+#
+# OPENAPI_TITLE / OPENAPI_VERSION override the document's info block.
+require "json"
+require "fileutils"
+
+namespace :permittable do
+  desc "Export an OpenAPI 3.1 document generated from every Permittable contract"
+  task :openapi, [:output] => :environment do |_t, task_args|
+    Rails.application.eager_load!
+
+    bases = []
+    bases << ActionController::Base if defined?(ActionController::Base)
+    bases << ActionController::API if defined?(ActionController::API)
+    controllers = bases.flat_map(&:descendants).uniq.select do |controller|
+      controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any?
+    end
+
+    document = Permittable::OpenAPI.document(
+      controllers: controllers,
+      routes: Permittable::OpenAPI.rails_routes(Rails.application),
+      info: {
+        "title" => ENV.fetch("OPENAPI_TITLE") { "#{Rails.application.class.module_parent_name} API" },
+        "version" => ENV.fetch("OPENAPI_VERSION", "1.0.0")
+      }
+    )
+
+    json = "#{JSON.pretty_generate(document)}\n"
+    if task_args[:output]
+      FileUtils.mkdir_p(File.dirname(task_args[:output]))
+      File.write(task_args[:output], json)
+      puts "Permittable: wrote #{task_args[:output]} " \
+           "(#{controllers.length} controller#{'s' unless controllers.length == 1})"
+    else
+      puts json
+    end
+  end
+end

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.2.0".freeze
+  VERSION = "0.4.0".freeze
 end

data/lib/permittable.rb

@@ -63,6 +63,21 @@ require "permittable/filter_parameter_registry"
 # action that never reads params never pays. `enforce: true` installs the
 # check as a before_action instead (reject before the action body runs).
 #
+# MONITOR MODE — the rollout switch. `mode: :monitor` on a rule (or
+# `Permittable.mode = :monitor` app-wide; a rule's own mode: wins) runs the
+# full pipeline but REPORTS violations instead of rejecting: the same
+# "invalid_parameters.permittable" event fires (payload mode: :monitor),
+# the logger warns, and permitted_params returns the raw params passed
+# through untouched — no casts, no defaults, no transforms — so behaviour
+# is identical to the pre-contract app (a missing root: passes an empty
+# hash; a rootless contract drops only the router's bookkeeping keys).
+# Monitor rules validate eagerly in the before_action regardless of
+# enforce:, because telemetry must not depend on the action calling
+# permitted_params — legacy actions still reading `params` directly are
+# exactly the ones being monitored — and monitoring can never halt the
+# request. `permittable_violations` reads the recorded details ([] when
+# the request was clean).
+#
 # 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
@@ -119,6 +134,7 @@ module Permittable
   LABEL = "Permittable".freeze
   SCALAR_TYPES = %i[string integer float decimal boolean date datetime].freeze
   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
@@ -144,6 +160,26 @@ module Permittable
     end
 
     attr_writer :filter_parameter_registry
+
+    # App-wide default for rules that don't declare their own mode:.
+    # :enforce (the default) rejects violating requests; :monitor reports
+    # them — same instrumentation event with payload mode: :monitor, plus a
+    # logger.warn — and lets the request proceed with the raw params passed
+    # through. This is the rollout switch for brownfield adoption: set it
+    # from an initializer (Permittable.mode =
+    # ENV.fetch("PERMITTABLE_MODE", "enforce").to_sym) and flip controllers
+    # to their final mode one at a time, since a rule's own mode: always
+    # wins over this default.
+    def mode
+      @mode || :enforce
+    end
+
+    def mode=(value)
+      value = value.to_sym
+      raise ArgumentError, "#{LABEL}: mode must be one of #{MODES.join(', ')}" unless MODES.include?(value)
+
+      @mode = value
+    end
   end
 
   # Raised when the request violates the matching contract. `details` is an
@@ -313,9 +349,9 @@ 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].freeze
-    NESTED_OPTS = %i[virtual sensitive message].freeze
-    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message].freeze
+    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
 
     attr_reader :finalizer
 
@@ -368,7 +404,8 @@ module Permittable
       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)
+      validate_array_authored_value!(field, :default) if field.key?(:default)
+      validate_array_authored_value!(field, :example) if field.key?(:example)
       validate_message!(field)
       @fields << field
     end
@@ -442,7 +479,8 @@ module Permittable
       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)
+      validate_authored_value!(field, :default)
+      validate_authored_value!(field, :example)
       validate_message!(field)
     end
 
@@ -481,27 +519,28 @@ module Permittable
       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)
+    # 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).
+    def validate_authored_value!(field, opt)
+      return unless field.key?(opt)
 
-      status, code = Coercion.check_scalar(field, field[:default])
+      status, code = Coercion.check_scalar(field, field[opt])
       return if status == :ok
 
-      raise ArgumentError, "#{LABEL}: :default for field :#{field[:name]} violates its own contract (#{code})"
+      raise ArgumentError, "#{LABEL}: :#{opt} 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)
+    def validate_array_authored_value!(field, opt)
+      value = field[opt]
+      raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
       return unless field[:of]
 
-      default.each do |element|
+      value.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})"
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains an element violating of: :#{field[:of]} (#{code})"
       end
     end
 
@@ -561,12 +600,23 @@ module Permittable
     #            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)
+    #   mode:    nil (default) follows Permittable.mode; :enforce rejects
+    #            violating requests; :monitor reports them and passes the
+    #            raw params through (see MONITOR MODE in the module
+    #            comment).
+    #   desc:    documentation only — carried on the rule for exporters
+    #            (Permittable::OpenAPI); the runtime never reads it.
+    def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, mode: nil, desc: nil, &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)
 
+      mode = mode&.to_sym
+      if mode && !MODES.include?(mode)
+        raise ArgumentError, "#{LABEL}: :mode must be one of #{MODES.join(', ')}, or nil to follow Permittable.mode"
+      end
+
       builder = ContractBuilder.new
       fields = builder.build(&block)
       raise ArgumentError, "#{LABEL}: a contract must declare at least one field" if fields.empty?
@@ -576,8 +626,8 @@ module Permittable
       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
+               model: model_class, unknown: unknown, enforce: !!enforce, mode: mode, fields: fields,
+               finalize: builder.finalizer, desc: desc }.freeze
       self.permittable_contracts = permittable_contracts + [rule]
     end
 
@@ -652,21 +702,44 @@ module Permittable
     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)
+    @permittable_validated[action] = validate_params_contract!(rule, action)
   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.
+  # :enforce_params_contract`). Two kinds of rule validate here: those that
+  # opted in with `enforce: true`, and monitor-mode rules — monitoring must
+  # not depend on the action calling permitted_params (legacy actions still
+  # reading `params` directly are exactly the ones being monitored), and it
+  # can never halt the request because monitor mode never raises.
   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]
+    permitted_params(action) if rule && (rule[:enforce] || permittable_mode(rule) == :monitor)
     nil
   end
 
+  # The violation details recorded by validating `action` (default: the
+  # current action) — [] when the request satisfied the contract. Triggers
+  # the same memoized validation as permitted_params, so under monitor mode
+  # this is the request-level observable ("what would have been
+  # rejected?"); under enforce mode it swallows the raise and hands back
+  # the details, which makes "would this request fail?" a one-liner in
+  # tests.
+  def permittable_violations(action = nil)
+    action = (action || permittable_action_name).to_s
+    @permittable_violations ||= {}
+    unless @permittable_violations.key?(action)
+      begin
+        permitted_params(action)
+      rescue InvalidParameters
+        # validation recorded the details before raising
+      end
+    end
+    @permittable_violations.fetch(action)
+  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)
@@ -678,7 +751,7 @@ module Permittable
 
   private
 
-  def validate_params_contract!(rule)
+  def validate_params_contract!(rule, action)
     violations = []
     source = permittable_root_hash(rule, violations)
     result = ActiveSupport::HashWithIndifferentAccess.new
@@ -688,19 +761,53 @@ module Permittable
     end
     # finalize only sees a hash every field vouched for — never garbage.
     result = permittable_run_finalize(rule[:finalize], result, violations) if violations.empty? && rule[:finalize]
+    violations.each(&:freeze)
+    (@permittable_violations ||= {})[action] = violations.freeze
     return result if violations.empty?
+    return permittable_monitor_pass_through(rule, source, violations) if permittable_mode(rule) == :monitor
 
     raise_invalid_parameters!(violations, status: source ? :unprocessable_entity : :bad_request)
   end
 
+  # A rule's own mode: wins; otherwise the app-wide Permittable.mode.
+  def permittable_mode(rule)
+    rule[:mode] || Permittable.mode
+  end
+
+  # Monitor mode's violation path: emit the same instrumentation event the
+  # enforce path does (payload mode: :monitor) plus a warn line, then hand
+  # back exactly what the client sent — no casts, no defaults, no
+  # transforms — so behaviour is identical to the pre-contract app. A
+  # missing root: passes an empty hash through (the envelope you asked for
+  # isn't there); a rootless contract drops only the router's bookkeeping
+  # keys, mirroring their exemption from the unknown-keys check.
+  def permittable_monitor_pass_through(rule, source, violations)
+    permittable_instrument_violations(violations, mode: :monitor)
+    if respond_to?(:logger) && logger
+      logger.warn("#{LABEL}: [monitor] ##{permittable_action_name} would have been rejected: " \
+                  "#{permittable_violation_summary(violations)}")
+    end
+    return ActiveSupport::HashWithIndifferentAccess.new unless source
+
+    passed = ActiveSupport::HashWithIndifferentAccess.new(source)
+    rule[:root] ? passed : passed.except(*ROUTING_KEYS)
+  end
+
   def raise_invalid_parameters!(violations, status:)
-    violations.each(&:freeze)
+    permittable_instrument_violations(violations, mode: :enforce)
+    raise InvalidParameters.new("Invalid parameters: #{permittable_violation_summary(violations)}",
+                                details: violations, status: status)
+  end
+
+  def permittable_instrument_violations(violations, mode:)
     ActiveSupport::Notifications.instrument(
       "invalid_parameters.permittable",
-      controller: permittable_controller_name, action: permittable_action_name, details: violations
+      controller: permittable_controller_name, action: permittable_action_name, details: violations, mode: mode
     )
-    summary = violations.map { |v| v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})" }.join(", ")
-    raise InvalidParameters.new("Invalid parameters: #{summary}", details: violations, status: status)
+  end
+
+  def permittable_violation_summary(violations)
+    violations.map { |v| v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})" }.join(", ")
   end
 
   # One violation detail entry. A field's `message:` (String, or Hash keyed
@@ -873,5 +980,11 @@ module Permittable
   end
 end
 
-# Boot-time integration (filter_parameters registration), Rails apps only
+# Contract exporters — the other readers of the frozen contract registry.
+# Loaded after the module body so OpenAPI can see the concern's own methods.
+require "permittable/json_schema"
+require "permittable/open_api"
+
+# Boot-time integration (filter_parameters registration, the
+# permittable:openapi rake task), Rails apps only
 require "permittable/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -50,7 +50,10 @@ files:
 - lib/permittable/column_guard.rb
 - lib/permittable/error_envelope.rb
 - lib/permittable/filter_parameter_registry.rb
+- lib/permittable/json_schema.rb
+- lib/permittable/open_api.rb
 - lib/permittable/railtie.rb
+- lib/permittable/tasks/openapi.rake
 - lib/permittable/version.rb
 homepage: https://github.com/VSN2015/permittable
 licenses: