permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/configuration/strategy_values.rb

@@ -15,9 +15,10 @@ module PermissionForge
     module StrategyValues
       ALLOWED = {
         nil_user_strategy: %i[bypass raise deny],
+        no_read_access_strategy: %i[rules_only deny],
         response_filter_nil_user_strategy: %i[bypass block],
         masked_write_protection: %i[skip raise off],
-        masked_attributes_nil_user_strategy: %i[bypass hide],
+        masked_attributes_nil_user_strategy: %i[bypass hide_in_requests hide],
         action_guard_nil_user_strategy: %i[bypass deny raise],
         admin_tenantless_access: %i[deny allow],
         unconfigured_action_strategy: %i[allow block],

data/lib/permission_forge/configuration.rb

@@ -27,8 +27,8 @@ module PermissionForge
     # virtual attribute or a Ruby method (e.g., `"#{first_name} #{last_name}"`)
     # rather than a real column, so a SQL ORDER BY would fail.
     #
-    # The User class must respond to `:name` and `:email` (as method or column)
-    # for display labels. Override to scope or sort however you like:
+    # The User class must respond to `:name` and/or `:email` (or Rails 8's
+    # `:email_address`), as method or column, for display labels. Override to scope or sort however you like:
     #   config.user_list_resolver = -> { User.active.order(:last_name, :first_name) }
     attr_accessor :user_list_resolver
 
@@ -45,8 +45,8 @@ module PermissionForge
     # Receives the user, returns a String (the human-readable part).
     # The combobox automatically appends ` #<id>` so the JS can extract the id.
     #
-    # Default: tries name, full_name, display_name (in that order), then email,
-    # then a localized fallback. Override for full control:
+    # Default: tries name, full_name, display_name (in that order), then email
+    # (or email_address), then a localized fallback. Override for full control:
     #   config.user_label_formatter = ->(u) { "#{u.last_name}, #{u.first_name} <#{u.email}>" }
     attr_accessor :user_label_formatter
 
@@ -160,7 +160,8 @@ module PermissionForge
 
     # Lambda that receives the controller instance and returns true/false for auth.
     # When nil and API enabled, all requests return 401 (safe default).
-    # Example: ->(controller) { controller.current_user&.has_role?(:admin) }
+    # Example (PermissionForge.current_user is current_user_resolver's user, set when
+    # api_base_controller_class signs the caller in): ->(_controller) { PermissionForge.current_user&.admin? }
     attr_accessor :api_auth
 
     # Base controller class for API controllers (default: "::ActionController::Base").
@@ -179,10 +180,18 @@ module PermissionForge
     # Default records per page when per_page param is not provided.
     attr_accessor :api_default_per_page
 
-    # When true, the /api/stats endpoint requires admin access.
-    # The api_auth lambda must set @admin = true on the controller.
+    # When true (default), GET /api/stats answers only callers
+    # api_stats_authorization allows (403 for everyone else). false: every
+    # caller api_auth admits.
     attr_accessor :api_stats_require_admin
 
+    # Lambda that receives the controller and decides who may read GET
+    # /api/stats while api_stats_require_admin is on; a truthy answer allows.
+    # When nil, stats are refused (until 0.16 an api_auth that sets @admin =
+    # true on the controller still allows, with a deprecation warning).
+    # Example: ->(controller) { PermissionForge.current_user&.admin? }
+    attr_accessor :api_stats_authorization
+
     # Record identifier field for API lookups (default: :uuid).
     # Change to :id if your app uses integer IDs in URLs.
     attr_accessor :api_record_identifier
@@ -208,8 +217,8 @@ module PermissionForge
 
     # Lambda for action-level authorization on API mutation endpoints (clone, etc.).
     # Receives (controller, action_name, record) and should return true/false.
-    # When nil, no extra authorization is performed (backward-compatible).
-    # Example: ->(controller, action, record) { controller.current_user&.admin? }
+    # When nil, every mutation is refused while api_require_authorization is true (the default).
+    # Example: ->(controller, action, record) { PermissionForge.current_user&.admin? }
     attr_accessor :api_action_authorization
 
     # Lambda for authorization checks on user-to-permission-set assignments
@@ -299,8 +308,12 @@ module PermissionForge
     # Hash of regex => strategy string for GDPR field pattern matching
     attr_reader :gdpr_field_patterns
 
+    # Not created_at / updated_at (before 0.15 they were here): generated
+    # fields give them a row, at most read-only on a granting set
+    # (TimestampFields), so the default unconfigured_field_strategy (:block)
+    # no longer hides them from a reader who is granted them.
     DEFAULT_IGNORED_FIELDS = %w[
-      id created_at updated_at token_digest token_last_digits
+      id token_digest token_last_digits
       created_by updated_by token password encrypted_password
       deleted_at uuid deactivated
     ].freeze
@@ -312,7 +325,7 @@ module PermissionForge
 
     # Column names that are personal data, with the mask for each. One
     # definition for masking detection (ResourceFieldGenerator,
-    # GdprFieldAuditor, Admin::SensitiveColumns, the security audit) and for
+    # GdprFieldAuditor, SensitiveColumns, the security audit) and for
     # Rails' filter_parameters (PermissionForge.gdpr_filter_parameters), which
     # Rails also applies to ActiveRecord::Base.filter_attributes — so a match
     # prints as [FILTERED] in #inspect. A word matches anywhere in the name,
@@ -323,9 +336,11 @@ module PermissionForge
     # `home_tel`, `tel2`, `telNumber`, `cityName`, `zipcode` yes — `hotel_id`,
     # `capacity`, `telemetry_enabled`, `automobile_id`, `gzip_enabled` no.
     # Every alternative stands alone (no group with an inner `|`):
-    # Admin::SensitiveColumns names the one that matched.
+    # SensitiveColumns names the one that matched. The first pattern
+    # that matches decides the strategy: Rails 8's `email_address` is an
+    # email (it also matches `address`, below).
     DEFAULT_GDPR_FIELD_PATTERNS = {
-      /\Aemail\z|_email\z/ => 'email',
+      /\Aemail\z|_email\z|\Aemail_address\z|_email_address\z/ => 'email',
       /phone|telefon|\Amobile|_mobile|\Afax|_fax|\Atel\z|\Atel_|\Atel[A-Z0-9]|_tel\z|_tel_|_tel[A-Z0-9]/ => 'last4',
       /\Assn\z|social_security|national_id/ => 'last4',
       /iban|bank_account|credit_card|card_number/ => 'last4',
@@ -390,9 +405,10 @@ module PermissionForge
     end
 
     # Field-name variants produced by the configured mappings (e.g. `user_id`
-    # -> `user_uuid`, `price_cents` -> `price`). Shared by the granting and
-    # muting phases of PermissionHashBuilder so they always cover the same
-    # names.
+    # -> `user_uuid`, `price_cents` -> `price`), whatever the model. What a
+    # field row applies to is PermissionForge::FieldVariants: these, kept to
+    # the names the Resource's model has (shared by the granting and muting
+    # phases of PermissionHashBuilder and the admin).
     #
     # @param field_name [String, Symbol]
     # @return [Array<String>]
@@ -572,6 +588,7 @@ module PermissionForge
       @api_auth = nil
       @api_base_controller_class = '::ActionController::Base'
       @api_stats_require_admin = true
+      @api_stats_authorization = nil
       @api_pagination_handler = nil
       @api_max_per_page = 100
       @api_default_per_page = 15
@@ -591,13 +608,19 @@ module PermissionForge
       ->(user) { user.respond_to?(:active_for_authentication?) ? user.active_for_authentication? : true }
     end
 
+    # The profile is cached with the permission hash (the cache store:
+    # Redis, Solid Cache, ...), so an attribute the user model encrypts is
+    # left out (nil): neither its ciphertext nor its plaintext goes there.
     def default_profile_builder
       lambda { |user|
+        label = Admin::PersonLabel.new(user, decrypt: false)
         {
           id: user.id,
           uuid: user.try(:uuid),
-          name: user.try(:name),
-          email: user.try(:email)
+          # Raw-column-first (Admin::PersonLabel#raw_value): a masked User model never garbles the profile
+          name: label.raw_value(:name),
+          # The first present of `email`, Rails 8's `email_address` (Admin::PersonLabel::EMAIL_ATTRIBUTES)
+          email: label.email
         }
       }
     end

data/lib/permission_forge/controller_actions/managed_index.rb

@@ -16,9 +16,10 @@ module PermissionForge
     # in PermissionForge.cache, so every process sees an invalidation
     # (InvalidatesManagedActions drops it when a defining record changes).
     #
-    # A stale "not managed" lets a request through under the default
-    # strategy, so the index is invalidated and rebuilt the way a user's
-    # permission hash is — the same code, one definition:
+    # A stale "not managed" lets a request through under the :allow strategy
+    # (under :block, the default, both answers refuse), so the index is
+    # invalidated and rebuilt the way a user's permission hash is — the same
+    # code, one definition:
     #   - every invalidation leaves a fresh stamp (STAMP_KEY) before it removes
     #     the keys, and a build only leaves the index in the store when the
     #     stamp it read before reading the rows is still there after storing it
@@ -197,11 +198,11 @@ module PermissionForge
                                                 PermissionForge::ResourceAction.arel_table[:name])
         end
 
-        # Mirrors PermissionCacheAccessor#permission_cache_key.
+        # Mirrors PermissionCacheAccessor#permission_cache_key: the ambient
+        # tenant's key (PermissionForge.ambient_tenant_id, the one reader).
         def cache_key
-          config = PermissionForge.configuration
-          tenant = ActsAsTenant.current_tenant if config.tenant_enabled? && defined?(ActsAsTenant)
-          tenant ? tenant_key(tenant.id) : CACHE_KEY
+          tenant_id = PermissionForge.ambient_tenant_id
+          tenant_id ? tenant_key(tenant_id) : CACHE_KEY
         end
 
         def tenant_key(tenant_id)

data/lib/permission_forge/database_reach.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # Whether this process can use its database, asked where the answer may be
+  # "no" without anything being wrong with the app: at boot (BootChecks),
+  # when auto-applied masking reads the Resource table (MaskedModels,
+  # MaskingSync), and wherever the audit table is looked for.
+  #
+  # A process may have no database to use: a Docker build precompiles assets
+  # before any database exists, a fresh `rails new --skip-kamal` app comments
+  # its production database paths out (the deploy supplies DATABASE_URL at
+  # runtime), a worker starts while the database fails over. The same app
+  # without the gem boots in each case, so nothing the gem does at boot may
+  # abort it then.
+  #
+  # Connecting can fail in Rails' own code in more ways than
+  # ActiveRecord::ActiveRecordError: the sqlite3 adapter refuses a
+  # configuration without a database file with an ArgumentError. It is
+  # rescued only around a call that runs Rails' connection code alone (a
+  # ping, `table_exists?`), never around the gem's own code: an
+  # ArgumentError there is a bug and still raises. (An adapter whose driver
+  # gem is missing fails while Active Record loads, before any of this runs,
+  # with or without the gem.)
+  #
+  # Every place that asks whether a table is there and may answer "no"
+  # quietly asks table_exists? here. Its "no" is never kept: Active Record's
+  # schema cache remembers a missing table until the process restarts, so a
+  # process that booted before the migration (run from another process)
+  # would never see the table; each caller decides how often it asks again
+  # (MaskingSync: each run until it syncs; Audit: MISSING_TABLE_RECHECK).
+  # The audit table check of the record path passes the narrower
+  # UNREACHABLE_ERRORS: a configuration error there still raises out of
+  # Audit.record, so the change it records rolls back, as it always did.
+  # Services::HostKeyGuard lets a failed read propagate to its own rescue
+  # (READ_ERRORS), so that a pass is never remembered from a check that
+  # could not look.
+  #
+  # @api private
+  module DatabaseReach
+    # A configured database that does not answer (refused, timed out, lost)
+    # or does not exist. Never a configuration error: where a quiet "no"
+    # lets a change commit unrecorded (the audit table check of
+    # Audit.record), only these count as "cannot be asked".
+    UNREACHABLE_ERRORS = [ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError].freeze
+
+    # What a ping or a table check that may answer "no" quietly rescues: the
+    # database cannot be used at all — not reachable, not created, not
+    # configured (no adapter, an adapter that refuses its configuration:
+    # sqlite3's "No database file specified") — or Active Record raised for
+    # the query.
+    CONNECT_ERRORS = [ActiveRecord::ActiveRecordError, ArgumentError].freeze
+
+    # What a read raises when the database went away after it answered, or
+    # the table is not there yet (not migrated): the errors a boot step or a
+    # read of the Resource rows is skipped on.
+    READ_ERRORS = [ActiveRecord::ConnectionNotEstablished, ActiveRecord::StatementInvalid].freeze
+
+    class << self
+      # Connects and pings. `connection_pool.with_connection` alone is not
+      # enough: since Rails 7.2 it hands back a connection that has not
+      # connected yet, so an unreachable database looked available.
+      #
+      # @param model [Class, nil] an ActiveRecord model whose database is
+      #   asked; nil for the gem's tables (referenced inside the rescue: the
+      #   first reference loads the model, and Active Record with it)
+      # @return [Exception, nil] what connecting raised (CONNECT_ERRORS), nil
+      #   when the database answered
+      def problem(model = nil)
+        (model || PermissionForge::PermissionSet).connection_pool.with_connection(&:verify!)
+        nil
+      rescue *CONNECT_ERRORS => e
+        e
+      end
+
+      # @param model [Class] an ActiveRecord model
+      # @param errors [Array<Class>] what counts as "cannot be asked"
+      #   (CONNECT_ERRORS, or the narrower UNREACHABLE_ERRORS)
+      # @yieldparam error [Exception] what the check raised, when it did
+      # @return [Boolean] whether the model's table is there; false when the
+      #   check raised one of `errors`. A "no" is dropped from the schema
+      #   cache (`reset_column_information`): the next call asks the database.
+      def table_exists?(model, errors: CONNECT_ERRORS)
+        return true if model.table_exists?
+
+        model.reset_column_information
+        false
+      rescue *errors => e
+        yield e if block_given?
+        false
+      end
+    end
+  end
+end

data/lib/permission_forge/deprecation.rb

@@ -30,7 +30,7 @@ module PermissionForge
   module Deprecation
     # The version that removes what is deprecated now. A test fails once
     # VERSION reaches it: remove the deprecated code, then move the horizon.
-    HORIZON = '0.15'
+    HORIZON = '0.16'
     GEM_NAME = 'PermissionForge'
 
     DEPRECATOR = ActiveSupport::Deprecation.new(HORIZON, GEM_NAME)

data/lib/permission_forge/docs/api_samples.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'i18n'
+require 'active_support/json'
+require 'active_support/core_ext/object/json'
+require 'active_support/core_ext/string/inflections'
+
+module PermissionForge
+  module Docs
+    # The ```json sample=<name> blocks of docs/admin-api.md, rendered from
+    # Api::Schema and the serializers (`bundle exec rake docs:api`;
+    # docs/api_samples_test.rb fails while the document is stale). A success
+    # sample is a serializer's own output for an example record (EXAMPLES,
+    # else a value of the key's type), encoded as the API encodes it, inside
+    # the envelope the schema declares; an error sample is the schema's error
+    # body with the gem's en message. Only the body of a marked block is
+    # rewritten: the prose around it is kept as it stands.
+    #
+    # @api private
+    class ApiSamples
+      LOCALE_FILE = File.expand_path('../../../config/locales/permission_forge.en.yml', __dir__)
+      CREATED = Time.utc(2026, 3, 10, 12, 0, 0)
+      UPDATED = Time.utc(2026, 3, 12, 9, 30, 0)
+
+      # A value for a key no EXAMPLES entry gives, by its type.
+      TYPE_EXAMPLES = {
+        integer: 1, string: 'text', boolean: true, uuid: '00000000-0000-4000-8000-000000000001', time: CREATED,
+        foreign_identifier: 1, foreign_uuid: '00000000-0000-4000-8000-000000000002', host_key: 42, host_key_list: [],
+        string_list: [], object: {}
+      }.freeze
+
+      # The example record of each payload a sample shows.
+      EXAMPLES = {
+        permission_set: {
+          id: 12, uuid: 'd2b4c7e1-5a3f-4b8e-9c6d-1f2a3b4c5d6e', name: 'Sales Team', description: 'Read and edit customers',
+          is_active: true, is_editable: true, is_muting: false, requires_session_flag: nil,
+          allowed_ips: '203.0.113.0/24', allowed_ip_list: ['203.0.113.0/24'], allowed_hours_start: nil, allowed_hours_end: nil,
+          permission_set_group_id: 3, permission_set_group_uuid: '8a6f2c1d-3e4b-4f5a-8b7c-9d0e1f2a3b4c',
+          created_at: CREATED, updated_at: UPDATED
+        },
+        permission_set_group: {
+          id: 3, uuid: '8a6f2c1d-3e4b-4f5a-8b7c-9d0e1f2a3b4c', name: 'Sales', description: nil,
+          is_active: true, is_editable: true, created_at: CREATED, updated_at: CREATED
+        },
+        audit_event: {
+          id: 481, uuid: '5c1e9a7b-2d4f-4e6a-9b8c-0d1e2f3a4b5c', occurred_at: Time.utc(2026, 9, 14, 8, 12, 44.120391r),
+          event: 'assignment.revoked', category: 'change', actor_type: 'user', actor_id: '7', actor_label: 'Ada Admin',
+          source: 'admin_ui', record_type: 'PermissionForge::PermissionSetUser', record_id: '93',
+          record_uuid: 'a77f3b2c-1d4e-4f5a-8b6c-7d8e9f0a1b2c', record_label: 'Bo Brandt',
+          permission_set_id: 12, permission_set_uuid: 'd2b4c7e1-5a3f-4b8e-9c6d-1f2a3b4c5d6e', subject_user_id: '31',
+          data: { 'snapshot' => { 'user_id' => 31, 'expires_at' => nil } }, reason: 'left the team',
+          request_id: '6f1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d', ip: '203.0.113.9',
+          correlation_id: '0b8c7d6e-5f4a-4b3c-9d2e-1f0a9b8c7d6e', created_at: Time.utc(2026, 9, 14, 8, 12, 44.121002r)
+        }
+      }.freeze
+
+      # The 422s an input error answers, one per line of `input_errors`:
+      # [field, en key].
+      INPUT_ERRORS = [
+        %w[expires_at api.errors.not_iso8601_time], %w[permission_set api.errors.section_missing],
+        %w[bulk_action api.errors.bulk_action_invalid], %w[user_ids api.errors.user_ids_missing],
+        %w[user_id api.errors.user_not_found], %w[grant_all api.errors.boolean_invalid],
+        %w[is_active api.errors.boolean_invalid], %w[name api.errors.text_shape],
+        %w[field_value api.errors.field_value_shape],
+        %w[base api.errors.field_generation_failed]
+      ].freeze
+
+      # One sample: how it is laid out (`:pretty`, `:inline` on one line,
+      # `:lines` one inline body per line), the schema it follows
+      # ([:single | :collection | :list, payload] or [:error, status]) and how
+      # it is built (called with the ApiSamples).
+      Sample = Data.define(:style, :schema, :build) do
+        def error? = schema.first == :error
+      end
+
+      SAMPLES = {
+        'permission_set' => Sample.new(:pretty, %i[single permission_set], ->(_) { Example.envelope(:single, :permission_set) }),
+        'permission_set_group_collection' => Sample.new(:pretty, %i[collection permission_set_group],
+                                                        ->(_) { Example.envelope(:collection, :permission_set_group) }),
+        'audit_event_collection' => Sample.new(:pretty, %i[collection audit_event],
+                                               ->(_) { Example.envelope(:collection, :audit_event, per_page: 100) }),
+        'validation_error' => Sample.new(:pretty, [:error, 422], ->(_) { Text.error(422, 'name' => ['validations.name_blank']) }),
+        'not_found' => Sample.new(:pretty, [:error, 404], ->(_) { Text.error(404, 'api.errors.not_found') }),
+        'route_not_found' => Sample.new(:inline, [:error, 404], ->(_) { Text.error(404, 'api.errors.route_not_found') }),
+        'input_errors' => Sample.new(:lines, [:error, 422],
+                                     ->(_) { INPUT_ERRORS.map { |field, key| Text.error(422, field => [key]) } }),
+        'body_unreadable' => Sample.new(:inline, [:error, 400], ->(_) { Text.error(400, 'api.errors.body_unreadable') }),
+        'action_name_invalid' => Sample.new(:inline, [:error, 422], ->(_) { Text.error(422, 'name' => ['errors.admin.action_format']) })
+      }.freeze
+
+      # The gem's en messages, in the error body the schema declares.
+      module Text
+        module_function
+
+        # An error body whose messages are the en texts of `messages`: a
+        # key, or a field mapped to keys.
+        def error(status, messages)
+          texts = messages.is_a?(Hash) ? messages.transform_values { |keys| keys.map { |key| t(key) } } : t(messages)
+          Api::Schema.error_body(status, texts)
+        end
+
+        # The gem's en text of `permission_forge.<key>`.
+        def t(key)
+          I18n.load_path |= [LOCALE_FILE] unless I18n.load_path.any? { |path| path.to_s == LOCALE_FILE }
+          I18n.t("permission_forge.#{key}", locale: :en, raise: true)
+        end
+      end
+
+      # A serializer's own output for an example record, in its envelope.
+      module Example
+        module_function
+
+        # A success envelope around the example record of `payload`, as the
+        # API encodes it (`render json:`: times in ISO 8601).
+        def envelope(kind, payload, per_page: Configuration.new.api_default_per_page)
+          data = JSON.parse(ActiveSupport::JSON.encode(serialized(payload)))
+          case kind
+          when :single then { 'data' => data }
+          when :list then { 'data' => [data] }
+          when :collection then { 'data' => [data], 'meta' => { 'pagination' => { 'page' => 1, 'per_page' => per_page, 'total_count' => 1 } } }
+          end
+        end
+
+        # @raise [ArgumentError] for a serializer key Api::Schema does not declare
+        def serialized(payload)
+          serializer = Api::Serializers.const_get("#{payload.to_s.camelize}Serializer")
+          fields = Api::Schema.payload(payload)
+          declared!(serializer, fields.keys)
+          example = record(payload, fields)
+          serializer.new(example).with_reference_uuids(reference_uuids(serializer, example)).as_json
+        end
+
+        # The example's own uuid for each reference (it has no database to
+        # look them up in): association => { id => uuid }.
+        def reference_uuids(serializer, example)
+          serializer.references.to_h do |association|
+            id_key, uuid_key = Api::Serializers::BaseSerializer.reference_keys(association)
+            [association, { example[id_key] => example[uuid_key] }]
+          end
+        end
+
+        def declared!(serializer, keys)
+          undeclared = serializer.attribute_names - keys
+          return if undeclared.empty?
+
+          raise ArgumentError, "#{serializer.name.demodulize} answers #{undeclared.join(', ')}, which Api::Schema does not declare"
+        end
+
+        # EXAMPLES' values for `payload`, else a value of each key's type.
+        def record(payload, fields)
+          examples = EXAMPLES.fetch(payload, {})
+          values = fields.to_h { |key, type| [key, examples.fetch(key) { TYPE_EXAMPLES.fetch(type.to_s.delete_suffix('?').to_sym) }] }
+          Struct.new(*values.keys, keyword_init: true).new(**values)
+        end
+      end
+
+      # How a block lays out its JSON.
+      module Layout
+        module_function
+
+        # Indented two spaces; a list of scalars on one line.
+        def pretty(value, indent = 0)
+          case value
+          when Hash
+            entries = value.map { |key, inner| "#{JSON.generate(key.to_s)}: #{pretty(inner, indent + 2)}" }
+            value.empty? ? '{}' : nested('{}', entries, indent)
+          when Array then scalars?(value) ? inline(value) : nested('[]', value.map { |item| pretty(item, indent + 2) }, indent)
+          else JSON.generate(value)
+          end
+        end
+
+        # `brackets` is the pair ("{}" or "[]") around the entries, one per line.
+        def nested(brackets, entries, indent)
+          pad = ' ' * indent
+          "#{brackets[0]}\n#{entries.map { |entry| "#{pad}  #{entry}" }.join(",\n")}\n#{pad}#{brackets[1]}"
+        end
+
+        def scalars?(list) = list.none? { |item| item.is_a?(Hash) || item.is_a?(Array) }
+
+        # One line: `{ "key": value }`, `[a, b]`.
+        def inline(value)
+          case value
+          when Hash then value.empty? ? '{}' : "{ #{value.map { |key, inner| "#{JSON.generate(key.to_s)}: #{inline(inner)}" }.join(', ')} }"
+          when Array then "[#{value.map { |item| inline(item) }.join(', ')}]"
+          else JSON.generate(value)
+          end
+        end
+      end
+
+      # @param document [String] docs/admin-api.md as it stands
+      # @param blocks [Array] its fenced blocks, as test/support/doc_blocks.rb parses them
+      #   (each with #file, #line, #body and #sample)
+      def initialize(document:, blocks:)
+        @document = document
+        @blocks = blocks.select(&:sample)
+      end
+
+      # The document with the body of every sample block regenerated.
+      #
+      # @raise [ArgumentError] for a sample= naming no sample, or a serializer
+      #   key Api::Schema does not declare
+      def render
+        lines = @document.lines
+        @blocks.sort_by(&:line).reverse_each do |block|
+          lines[block.line, block.body.lines.size] = text(sample_name(block)).lines
+        end
+        lines.join
+      end
+
+      def stale? = render != @document
+
+      # The JSON value of a sample (an Array of bodies for a `:lines` sample).
+      def value(name)
+        SAMPLES.fetch(name).build.call(self)
+      end
+
+      # The sample laid out as the block holds it, ending in a newline.
+      def text(name)
+        built = value(name)
+        body = case SAMPLES.fetch(name).style
+               when :pretty then Layout.pretty(built)
+               when :inline then Layout.inline(built)
+               when :lines then built.map { |item| Layout.inline(item) }.join("\n")
+               end
+        "#{body}\n"
+      end
+
+      # What is wrong with a sample against Api::Schema.
+      #
+      # @return [Array<String>]
+      def problems(name)
+        sample = SAMPLES.fetch(name)
+        kind, detail = sample.schema
+        spec = kind == :error ? Api::Schema.error_envelope(detail) : Api::Schema.envelope(kind, detail)
+        items = sample.style == :lines ? value(name) : [value(name)]
+        items.flat_map { |item| Api::Schema.problems(item, spec) }
+      end
+
+      private
+
+      def sample_name(block)
+        name = block.sample
+        return name if SAMPLES.key?(name)
+
+        raise ArgumentError, "#{block.file}:#{block.line}: sample=#{name} names no sample (#{self.class}::SAMPLES)"
+      end
+    end
+  end
+end