petticoat 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 697674762c68bca9da5ca1d6a9a11d8293aa5b5b7acbee009d949d49180efea0
+  data.tar.gz: 6990ad9ceda48183c0f29476e6d01e31d3352ac09925f9f5c6ea03100dfd9021
+SHA512:
+  metadata.gz: a12b5b6a52860b015aa2bc4722b5d84156ef98bf413918154c71fb2e4ff31a3e8805e8307ba74f2223a3516a610dabc75b3b2427fc02588a1d7303a311c8eb4d
+  data.tar.gz: c901e51344bd319253ff4bd61e0b13b9c40ff00afe97b7481c01581aa00c083b3c61c2e48eb6f56bf77914be34a8871a1c0557034fc501a813406ba80e2b79ae

data/README.md

@@ -0,0 +1,274 @@
+# Petticoat
+
+Petticoat turns existing CanCanCan abilities into a small, deterministic catalogue
+for frontend controls and navigation. It does not authorize requests. The server
+must still check every operation.
+
+The core is application-independent. It does not load Rails, build users,
+discover abilities, query a database or run permission blocks.
+
+## Supported environment
+
+Version 0.2.0 is tested with Ruby 4.0.6 and this CanCanCan 3.6.0 fork:
+`olistik/cancancan` at `18ce8ad800658629d4c1c2cb1382cd4794c2a5a3`.
+The adapter checks the relevant source files as well as the version number.
+Upstream CanCanCan 3.6.0 and other builds are **not verified** and may be rejected.
+Do not bypass the check to make an incompatible build appear supported.
+
+The development Gemfile pins that fork. Applications must select it themselves;
+a gem dependency cannot select another gem's Git source.
+
+## One selected population per document
+
+Callers supply completed ability objects and meaningful subject identifiers.
+Keep users with different construction contexts separate. For example, compile
+privileged and ordinary users into separate documents when a flag changes rule
+construction. Petticoat does not know what your application's flags mean.
+
+Here is a complete, database-free example:
+
+```ruby
+require 'petticoat'
+
+Item = Struct.new(:owner)
+ability = Class.new { include CanCan::Ability }.new
+ability.can :read, Item, owner: 42
+
+document = Petticoat::Document.new(subjects: { 'items' => Item })
+document.add(context: 'editor', role: 'member', scenario: 'ordinary',
+             snapshot: Petticoat::Snapshot.new(ability))
+
+catalogue = document.to_h
+Petticoat::Schema.validate!(catalogue)
+puts Petticoat::Document.lookup(catalogue, context: 'editor',
+                               role: 'member', subject: 'items')
+# possible
+```
+
+The owner value is not exported. A conditional grant does not promise that an
+accessible persisted record exists.
+
+The resource context looks like:
+
+```json
+{
+  "scope": "individual",
+  "examined_roles": ["member"],
+  "resources": {
+    "items": {"possible": ["member"], "unknown": []}
+  }
+}
+```
+
+A document's `subjects` is an array of opaque identifiers, not JSON:API metadata.
+Do not infer identifiers by pluralizing model names. The application owns that
+mapping and any application-specific envelope.
+
+## Reading answers
+
+The default `view: resources` answers whether some interaction may be available:
+
+- `possible`: every observed setup has some potentially permitted action.
+- `denied`: all observed setups deny all actions in this scope.
+- `unknown`: a failed capture, unsupported behavior, disagreement or missing
+  coverage prevents a conclusion.
+
+Resource entries contain sorted, disjoint `possible` and `unknown` role lists.
+An examined role absent from both lists defaults to denied. A wholly denied
+resource is omitted. An unexamined role, missing context or unregistered subject
+is unknown, not denied. `examined_roles` includes failed attempts; examined does
+not mean successful.
+
+For action-specific controls:
+
+```ruby
+actions = document.to_h(view: 'actions')
+Petticoat::Document.lookup(actions, context: 'editor', role: 'member',
+                          subject: 'items', action: 'read')
+# conditional
+```
+
+The action view uses `contexts[context].roles[role][subject][action]` and returns
+`unconditional`, `conditional`, `denied` or `unknown`. Read an explicit action
+first, then its action `*`, then the scoped denied default. Explicit exceptions
+win. Aliases are already expanded directionally: index does not imply literal
+read. Custom actions keep their names. A registered subject `*` represents
+CanCanCan's `:all`; it is not a fallback for unknown subjects.
+
+Resource queries omit action; action queries require it. Unknown versions, missing
+dimensions and extra query dimensions (including admin or scenario) return unknown.
+Use separate documents to select a population; lookup does not guess or merge one.
+
+Within each setup, any supported unconditional or conditional action makes the
+resource possible. Otherwise an unknown action makes it unknown; otherwise denied.
+Only then are resource answers compared across setups with the same role/context.
+Two setups may allow different actions yet agree that some interaction is possible.
+This is not evidence that listing, reading, or any particular endpoint will work.
+
+## Capturing and validating
+
+`Document#add(context:, role:, scenario:, snapshot:, scope: 'individual')`
+records a captured setup. Use `scope: 'composed'` for an actual ordered ability
+composition built by the caller. Never manufacture a global union of abilities.
+Duplicate scenario identities within a context and conflicting scope raise errors.
+
+A caller that has established a failed or unsupported setup may add
+`snapshot: nil`; it remains unknown for every registered subject. Unexpected
+execution failures should abort the application's export, preserving valid output.
+
+`Document#evidence` returns sorted, redacted per-scenario action observations.
+`Snapshot#evidence(identifier_callable)` returns redacted rule evidence in its
+original order. Neither exports condition values, SQL or record inspect strings.
+Condition hashes, ordinary blocks and attribute restrictions remain conditional
+as justified by rule order. SQL, instance subjects and custom matching can be unknown.
+Stored blocks are never executed merely to export them.
+
+`Schema.validate!` checks the [generic schema](lib/petticoat/schema.json), related
+membership/subject coverage and the content digest. Invalid data raises an error.
+`Schema.validate_contexts!(contexts, subjects:, view:)` shares cross-field checks
+with applications that have already schema-validated their own envelope.
+
+`Petticoat.canonical_json(value)` sorts maps, not ordered rule arrays.
+Document digests exclude themselves. The caller owns source fingerprints, output
+paths, safe file replacement and freshness checks. Keep private diagnostics
+separate from frontend data.
+
+## Install the optional CLI
+
+The core above works without the CLI. `require 'petticoat'` does not load the
+installer or an application. Bundler exposes the gem's `exe/petticoat` as
+`bundle exec petticoat`.
+
+Add Petticoat to your development/test bundle with `require: false`. Select the
+[supported CanCanCan source](#supported-environment) and install the bundle first.
+From the application root, run:
+
+```sh
+BUNDLE_FROZEN=true bundle exec petticoat install --dry-run
+BUNDLE_FROZEN=true bundle exec petticoat install
+```
+
+This creates just two application-owned files:
+
+- `bin/petticoat`: a thin, executable Bundler wrapper that loads the gem executable.
+- `config/petticoat.rb`: a commented integration entry to connect your own runner.
+
+The starter is deliberately **not ready to export**. Until you configure the
+runner, `export`, `check` and `test` fail with an actionable error and create no
+catalogue. The installer does not infer roles, copy policies, configure databases,
+select a test framework, run factories or boot your app. It never edits Gemfile,
+the lockfile or existing application files.
+
+Missing files are created; identical bytes and modes are left alone. Any content
+or mode conflict, symlink or unsafe path aborts before writes. Dry-run writes
+nothing. There is no `--preset`, `--force` or upgrade mode. Caught publication
+failures roll back only unchanged files created by that attempt. Installation is
+exclusive, not crash-atomic; rerun to finish an identical partial installation.
+
+Freeze the bundle after dependency setup: otherwise Bundler itself can touch the
+lockfile before a dry run reaches the installer. The wrapper and executable also
+freeze their own setup.
+
+## Connect your application
+
+Edit `config/petticoat.rb`: require your application-owned runner and assign it
+to `Petticoat::CLI.integration`. The generated comments show the shape. This is
+trusted command configuration, not a framework initializer. Only operational
+commands load it; help, version and install do not.
+
+The runner can be a module, object or lambda that implements:
+
+```ruby
+def self.call(mode:, arguments:, options:, out:)
+  # Run your application's build, comparison or tests.
+  # Raise on failure, including a failed child test process.
+end
+```
+
+| Keyword | What the CLI supplies |
+| --- | --- |
+| `mode` | `"export"`, `"check"` or `"test"`. |
+| `arguments` | Unparsed application test arguments; empty for export/check. |
+| `options[:output]` | Absolute path from an explicit `--output PATH`, if supplied. |
+| `options[:coverage]` | Absolute path from an explicit `--diagnostics PATH`, if supplied. |
+| `options[:seed]` | Integer from `--seed N`, if supplied. |
+| `out` | The output IO for status messages. |
+
+No paths, seed or test framework defaults are invented by the gem. The runner
+must raise on failure; returning `false` or a nonzero number does not signal an
+exit status. Normal completion means CLI exit 0. Exceptions produce exit 1;
+unexpected exception messages are redacted. Use `Petticoat::Error` only for safe,
+non-sensitive user-facing messages.
+
+Your runner owns the parts that depend on your application:
+
+1. Establish isolated test resources and disable live calls/delivery **before**
+   booting a framework or constructing factory records. A test environment name
+   alone does not prove a database is safe.
+2. Build real, asserted scenarios and actual ordered ability compositions.
+   Supply subject identifiers and keep distinct construction populations separate.
+   Pass completed abilities to `Snapshot` and `Document`; do not copy permissions.
+3. Clean up scenario effects. Preserve known gaps as unknown; abort unexpected
+   failures. Validate the complete catalogue before safely replacing any output.
+4. Implement `check` as a non-writing comparison, and `test` using your own test
+   framework and chosen scope. Keep coverage diagnostics out of frontend assets.
+
+After implementing and testing that boundary:
+
+```sh
+bin/petticoat test
+bin/petticoat export
+bin/petticoat check
+```
+
+Export/check also accept `--output PATH`, `--diagnostics PATH` and `--seed N`.
+The CLI dispatches these operations; it does not implement database isolation,
+file publication or freshness for you.
+
+```text
+Gem: bin wrapper template + CLI + capture / reduction / lookup / schema
+                              |
+                    loads config/petticoat.rb
+                              |
+App: explicit runner + scenarios / composition / subjects / isolation / output
+                              |
+                    explicit build using the core
+                              |
+Frontend: generated JSON hints     Server: existing authorization checks
+```
+
+Commit the wrapper, completed config, application runner, its tests and any
+generated assets in the application repository. Keep application-specific
+onboarding and safety instructions there too. A fresh application needs its own
+integration; the gem cannot safely infer one.
+
+For upgrades, update the dependency and review your runner against this contract.
+Do not rerun install over a customized config. Application integrations are not
+bundled presets and are never overwritten by a gem update. Ordinary Ability
+changes need a fresh export, not parallel permission declarations. Add scenarios
+when new roles, construction-time branches or composition contexts require them.
+
+## Develop and build locally
+
+Use the Ruby version in `.ruby-version`:
+
+```sh
+bundle install --local
+bundle exec rspec
+bundle exec rubocop
+gem build petticoat.gemspec
+```
+
+If a locked dependency is not installed locally, dependency setup may need network
+access. Tests use real CanCanCan and synthetic subjects, not Rails or factories.
+They also execute the Ruby example above and test the optional CLI and installer
+against filesystem failures and an application-supplied callable in a fresh process.
+Application-level factory, isolation and publication tests belong to each application.
+
+This is a pre-release, Git-sourced gem, not a published RubyGems release.
+No open-source license or public release is provided; `Nonstandard`
+metadata does not grant redistribution rights. Publication is deliberately disabled
+through an invalid `allowed_push_host`. Choose licensing, verify the name, and
+authorize distribution separately before any release.
+
+Made with ❤️ by [olistik](https://olisti.co)

data/exe/petticoat

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+ENV['BUNDLE_FROZEN'] = 'true'
+require 'bundler/setup'
+require 'petticoat/cli'
+
+exit Petticoat::CLI.run(ARGV)

data/lib/petticoat/adapter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Petticoat
+  # All access to undocumented CanCanCan internals lives here. Only private
+  # copies receive the gem's relevance/alias-cache mutations.
+  class Adapter
+    ID = 'cancancan-3.6.0-18ce8ad80065'
+    FILES = {
+      'ability.rb' => '6864743679252c07b750630ca4ebbad94117d6367ef6c33d7132a0e1ce2d5bbc',
+      'ability/rules.rb' => '4a7f96dd94b606e904718642b1a0a97efa3000be6396fb5f1150be005b02032b',
+      'ability/actions.rb' => '97c79d145b0e694cb273c4b7f3915426ead55546295d1ba92d6bb0cdfe08c3f7',
+      'rule.rb' => '7a4b0ce56f001a29a66c1051928732a88c893060ed1e11510fa2e1d3c31e7d18',
+      'relevant.rb' => 'dbe8ea801fd50a2e6fbb87a65825febb6affdee367c6a52706340bf1a91e55a1',
+      'conditions_matcher.rb' => 'f324a2a78788241c6ea53aecd3b9f48b947d42551db3eba84e6f9226c33351b7',
+      'class_matcher.rb' => 'b26f464494c2ff1551c4fa004d28fc4c82cad4cacbb04088e55971d47af489e2'
+    }.freeze
+
+    Shell = Class.new { include CanCan::Ability }
+    COPIED_FIELDS = %i[actions subjects attributes].freeze
+    METHOD_OWNERS = {
+      can?: CanCan::Ability,
+      alternative_subjects: CanCan::Ability,
+      rules: CanCan::Ability::Rules,
+      relevant_rules: CanCan::Ability::Rules,
+      possible_relevant_rules: CanCan::Ability::Rules,
+      expand_actions: CanCan::Ability::Actions,
+      aliased_actions: CanCan::Ability::Actions
+    }.freeze
+
+    attr_reader :rules, :aliases, :issues
+
+    def self.verify!
+      raise Error, 'Unsupported CanCanCan version' unless CanCan::VERSION == '3.6.0'
+      return if @verified
+
+      root = File.join(Gem.loaded_specs.fetch('cancancan').full_gem_path, 'lib/cancan')
+      unless FILES.all? { |file, digest| Digest::SHA256.file(File.join(root, file)).hexdigest == digest }
+        raise Error, 'Unsupported CanCanCan source; review the manifest adapter before exporting'
+      end
+
+      @verified = true
+    end
+
+    def initialize(ability)
+      self.class.verify!
+      @shell = Shell.new
+      @issues = semantic_issues(ability)
+      @aliases = copy_aliases(ability)
+      validate_aliases!
+      @shell.instance_variable_set(:@aliased_actions, @aliases.transform_values(&:dup))
+      @rules = copy_rules(ability)
+      cache = ability.instance_variable_get(:@expanded_actions) || {}
+      @shell.instance_variable_set(:@expanded_actions, cache.to_h { |key, value| [key.dup, value.dup] })
+    end
+
+    def relevant(action, subject)
+      @shell.send(:relevant_rules, action, subject)
+    end
+
+    def actions
+      (rules.flat_map(&:actions) + aliases.keys + aliases.values.flatten).uniq
+    end
+
+    def unsupported_subjects?
+      rules.any? do |rule|
+        rule.subjects.empty? || rule.subjects.any? { |subject| !subject.is_a?(Module) && !subject.is_a?(Symbol) }
+      end
+    end
+
+    private
+
+    def copy_aliases(ability)
+      source = ability.instance_variable_get(:@aliased_actions) || @shell.aliased_actions
+      source.to_h { |key, values| [key, values.dup] }
+    end
+
+    def semantic_issues(ability)
+      METHOD_OWNERS.filter_map { |name, owner| "custom_#{name}" unless ability.method(name).owner == owner }
+    end
+
+    def copy_rules(ability)
+      (ability.instance_variable_get(:@rules) || []).map do |rule|
+        copy = rule.dup
+        COPIED_FIELDS.each do |field|
+          copy.instance_variable_set(:"@#{field}", rule.public_send(field).dup)
+        end
+        @shell.send(:add_rule, copy)
+        copy
+      end
+    end
+
+    def validate_aliases!
+      @aliases.each_key { |action| visit_alias(action, []) }
+    end
+
+    def visit_alias(action, path)
+      raise Error, 'Unsupported alias cycle' if path.include?(action)
+      raise Error, 'Unsupported action identifier' unless action.is_a?(Symbol)
+
+      @aliases.fetch(action, []).each { |child| visit_alias(child, path + [action]) }
+    end
+  end
+end

data/lib/petticoat/cli.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative '../petticoat'
+
+module Petticoat
+  # Optional command entry. Loading the core never loads an application's setup.
+  class CLI
+    HELP = <<~TEXT
+      Usage: petticoat install [--dry-run]
+             petticoat export|check [--output PATH] [--diagnostics PATH] [--seed N]
+             petticoat test [application test arguments]
+             petticoat --help|--version
+
+      Run from the application root. Installation creates missing files only.
+      Export, check and test use your runner in config/petticoat.rb.
+      See the Petticoat README for the integration contract.
+    TEXT
+
+    class << self
+      attr_accessor :integration
+
+      def run(arguments, root: Dir.pwd, out: $stdout, err: $stderr)
+        self.integration = nil
+        new(arguments.dup, root, out).run
+      rescue OptionParser::ParseError
+        err.puts 'Petticoat: invalid command options; run petticoat --help.'
+        1
+      rescue StandardError => e
+        # Only our own explicit messages may reach the terminal.
+        message = e.is_a?(Petticoat::Error) ||
+                  (e.instance_of?(RuntimeError) && e.message.start_with?('Petticoat'))
+        err.puts(message ? e.message : "Petticoat command failed (#{e.class}).")
+        1
+      ensure
+        self.integration = nil
+      end
+    end
+
+    def initialize(arguments, root, out)
+      @arguments = arguments
+      @root = File.expand_path(root)
+      @out = out
+    end
+
+    def run
+      mode = @arguments.shift
+      case mode
+      when nil, '--help', '-h' then display(HELP)
+      when '--version', '-v' then display(Petticoat::VERSION)
+      when 'install' then install
+      when 'export', 'check', 'test' then operate(mode)
+      else raise Error, 'Petticoat: unknown command; run petticoat --help.'
+      end
+      0
+    end
+
+    private
+
+    def display(message)
+      reject_arguments!
+      @out.puts message
+    end
+
+    def install
+      require_relative 'installer'
+      options = { dry_run: false }
+      parser = OptionParser.new do |item|
+        item.on('--dry-run') { options[:dry_run] = true }
+      end
+      parser.parse!(@arguments)
+      reject_arguments!
+      Installer.new(root: @root).call(dry_run: options[:dry_run], out: @out)
+    end
+
+    def operate(mode)
+      options = mode == 'test' ? {} : export_options
+      config = File.join(@root, 'config/petticoat.rb')
+      unless File.file?(config)
+        raise Error, 'Petticoat: missing config/petticoat.rb; run petticoat install, ' \
+                     'then configure your application runner.'
+      end
+
+      load config
+      unless self.class.integration.respond_to?(:call)
+        raise Error, 'Petticoat: config/petticoat.rb must select a callable CLI.integration.'
+      end
+
+      self.class.integration.call(mode: mode, arguments: @arguments, options: options, out: @out)
+    end
+
+    def export_options
+      options = {}
+      OptionParser.new do |parser|
+        parser.on('--output PATH') { |value| options[:output] = File.expand_path(value, @root) }
+        parser.on('--diagnostics PATH') { |value| options[:coverage] = File.expand_path(value, @root) }
+        parser.on('--seed N', Integer) { |value| options[:seed] = value }
+      end.parse!(@arguments)
+      reject_arguments!
+      options
+    end
+
+    def reject_arguments!
+      raise Error, 'Petticoat: unexpected command arguments; run petticoat --help.' unless @arguments.empty?
+    end
+  end
+end

data/lib/petticoat/document.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Petticoat
+  class Document
+    SCHEMA_VERSION = 1
+    VIEWS = %w[resources actions].freeze
+    DEFAULT_ACTIONS = %w[read index show create new update edit destroy manage].freeze
+    DEFAULTS = { 'state' => 'denied', 'scope' => 'registered_subjects_in_present_entries' }.freeze
+    private_constant :DEFAULTS
+
+    def initialize(subjects:, actions: DEFAULT_ACTIONS)
+      @subjects = subjects
+      @actions = actions
+      @observations = {}
+    end
+
+    # One document represents one caller-selected construction population.
+    def add(context:, role:, scenario:, snapshot:, scope: 'individual')
+      entry = (@observations[context] ||= { scope:, snapshots: {} })
+      raise Error, 'Conflicting context scope' unless entry[:scope] == scope
+      raise Error, 'Duplicate scenario in context' if entry[:snapshots].key?(scenario)
+
+      entry[:snapshots][scenario] = { role:, snapshot: }
+    end
+
+    def to_h(view: 'resources')
+      raise Error, 'Unsupported catalogue view' unless VIEWS.include?(view)
+
+      actions = all_actions
+      payload = {
+        'schema_version' => SCHEMA_VERSION,
+        'view' => view,
+        'adapter' => Adapter::ID,
+        'scope' => 'observed_ability_construction',
+        'basis' => 'observed_scenarios',
+        'defaults' => DEFAULTS,
+        'subjects' => @subjects.keys.sort,
+        'contexts' => @observations.transform_values do |entry|
+          context_payload(entry[:scope], entry[:snapshots], actions, view)
+        end
+      }
+      payload['digest'] = Digest::SHA256.hexdigest(Petticoat.canonical_json(payload))
+      Petticoat.canonical(payload)
+    end
+
+    # Developer evidence, not another frontend catalogue. Values stay redacted.
+    def evidence
+      actions = all_actions
+      observations =
+        @observations.flat_map do |context, entry|
+          entry[:snapshots].map do |scenario, observation|
+            payload = snapshot_payload(observation, actions)
+            payload.merge('context' => context,
+                          'scope' => entry[:scope],
+                          'scenario' => scenario,
+                          'states' => sparse_states(payload.fetch('states')))
+          end
+        end
+      Petticoat.canonical(observations.sort_by { |item| item.values_at('context', 'scenario') })
+    end
+
+    def self.lookup(payload, **query)
+      return 'unknown' unless payload.is_a?(Hash)
+      return 'unknown' unless compatible_query?(payload, query)
+      return 'unknown' unless registered_subject?(payload, query.fetch(:subject))
+
+      context = payload['contexts']&.dig(query.fetch(:context))
+      return 'unknown' unless context.is_a?(Hash)
+
+      payload.fetch('view') == 'resources' ? lookup_resource(context, query) : lookup_actions(context, query)
+    end
+
+    def self.lookup_actions(context, query)
+      entry = context.dig('roles', query.fetch(:role))
+      return 'unknown' unless entry.is_a?(Hash)
+
+      actions = entry.fetch(query.fetch(:subject), {})
+      actions.fetch(query.fetch(:action), actions.fetch('*', DEFAULTS.fetch('state')))
+    end
+    private_class_method :lookup_actions
+
+    def self.registered_subject?(payload, subject)
+      payload['subjects'].is_a?(Array) && payload['subjects'].include?(subject)
+    end
+    private_class_method :registered_subject?
+
+    def self.compatible_query?(payload, query)
+      payload.values_at('schema_version', 'basis', 'defaults') ==
+        [SCHEMA_VERSION, 'observed_scenarios', DEFAULTS] &&
+        (query.keys - %i[context role subject action]).empty? &&
+        %i[context role subject].all? { |key| query[key].is_a?(String) } && compatible_view_query?(payload, query)
+    end
+    private_class_method :compatible_query?
+
+    def self.compatible_view_query?(payload, query)
+      case payload['view']
+      when 'resources' then !query.key?(:action)
+      when 'actions' then query[:action].is_a?(String)
+      else false
+      end
+    end
+    private_class_method :compatible_view_query?
+
+    def self.lookup_resource(context, query)
+      role = query.fetch(:role)
+      examined = context['examined_roles']
+      resources = context['resources']
+      return 'unknown' unless examined.is_a?(Array) && examined.include?(role) && resources.is_a?(Hash)
+      return DEFAULTS.fetch('state') unless resources.key?(query.fetch(:subject))
+
+      resource_membership(resources.fetch(query.fetch(:subject)), role)
+    end
+    private_class_method :lookup_resource
+
+    def self.resource_membership(entry, role)
+      return 'unknown' unless entry.is_a?(Hash) && entry['possible'].is_a?(Array) && entry['unknown'].is_a?(Array)
+      return 'unknown' if entry.fetch('unknown').include?(role)
+      return 'possible' if entry.fetch('possible').include?(role)
+
+      DEFAULTS.fetch('state')
+    end
+    private_class_method :resource_membership
+
+    private
+
+    def all_actions
+      snapshots = @observations.values.flat_map { |context| context[:snapshots].values }
+      observed = snapshots.flat_map { |entry| entry[:snapshot]&.actions || [] }
+      (@actions + observed + ['*']).uniq.sort
+    end
+
+    def context_payload(scope, observations, actions, view)
+      snapshots = observations.values.map { |observation| snapshot_payload(observation, actions) }
+      roles =
+        snapshots.group_by { |snapshot| snapshot.fetch('role') }
+                 .transform_values do |group|
+          view == 'resources' ? resource_states(group) : sparse_states(aggregate(group, actions))
+        end
+      # Agreement uses complete tables. Only the exported representation is sparse.
+      view == 'resources' ? resource_context(scope, roles) : { 'scope' => scope, 'roles' => roles }
+    end
+
+    # Invert already-agreed states, without losing examined-but-denied roles.
+    def resource_context(scope, roles)
+      resources = {}
+      roles.sort.each do |role, states|
+        states.each do |subject, state|
+          entry = (resources[subject] ||= { 'possible' => [], 'unknown' => [] })
+          entry.fetch(state) << role
+        end
+      end
+      { 'scope' => scope, 'examined_roles' => roles.keys.sort, 'resources' => resources }
+    end
+
+    def snapshot_payload(observation, actions)
+      snapshot = observation[:snapshot]
+      {
+        'role' => observation[:role],
+        'coverage' => snapshot ? 'observed' : 'unknown',
+        'aliases' => snapshot&.aliases || {},
+        'states' => states(snapshot, actions)
+      }
+    end
+
+    # Ask whether any interaction is possible within EACH scenario first. Two
+    # scenarios may allow different actions while agreeing at resource level.
+    def resource_states(observations)
+      @subjects.filter_map do |identifier, _subject|
+        values = observations.map { |snapshot| interaction(snapshot.fetch('states').fetch(identifier)) }
+                             .uniq
+        value = values.size == 1 ? values.first : 'unknown'
+        [identifier, value] unless value == DEFAULTS.fetch('state')
+      end.to_h
+    end
+
+    def interaction(actions)
+      return 'possible' if actions.values.any? { |state| %w[unconditional conditional].include?(state) }
+      return 'unknown' if actions.value?('unknown')
+
+      'denied'
+    end
+
+    def states(snapshot, actions)
+      @subjects.to_h do |identifier, subject|
+        values = actions.to_h { |action| [action, snapshot ? snapshot.state(action, subject) : 'unknown'] }
+        [identifier, compact(values)]
+      end
+    end
+
+    def aggregate(observations, actions)
+      @subjects.to_h do |identifier, _subject|
+        values = actions.to_h { |action| [action, agreement(observations, identifier, action)] }
+        [identifier, compact(values)]
+      end
+    end
+
+    def agreement(observations, identifier, action)
+      values = observations.map do |snapshot|
+        table = snapshot.fetch('states').fetch(identifier)
+        table.fetch(action, table.fetch('*'))
+      end.uniq
+      values.size == 1 ? values.first : 'unknown'
+    end
+
+    def compact(values)
+      values.select { |action, value| action == '*' || value != values.fetch('*') }
+    end
+
+    def sparse_states(states)
+      states.filter_map do |subject, actions|
+        sparse = actions.reject { |action, value| action == '*' && value == DEFAULTS.fetch('state') }
+        [subject, sparse] unless sparse.empty?
+      end.to_h
+    end
+  end
+end

data/lib/petticoat/installation_path.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Petticoat
+  # Reject symlinks and non-directory parents inside the selected checkout.
+  class InstallationPath
+    def initialize(root, relative)
+      parts = relative.split('/')
+      if relative.empty? || relative.start_with?('/') || parts.any? { |part| ['', '.', '..'].include?(part) } ||
+         relative.include?("\0") || relative.include?('\\')
+        raise Error, 'Petticoat: unsafe installation path.'
+      end
+
+      @root = File.realpath(root)
+      @parts = parts
+      @relative = relative
+    end
+
+    def checked
+      path = @root
+      @parts.each_with_index do |part, index|
+        path = File.join(path, part)
+        invalid = File.symlink?(path) ||
+                  (File.exist?(path) && (index == @parts.size - 1 ? !File.file?(path) : !File.directory?(path)))
+        raise Error, "Petticoat: unsafe installation path: #{@relative}." if invalid
+      end
+      path
+    end
+  end
+end

data/lib/petticoat/installer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+require_relative '../petticoat'
+require_relative 'installation_path'
+
+module Petticoat
+  # Create-only publication: a preflight conflict never causes partial installation.
+  class Installer
+    FILES = { 'bin/petticoat' => 0o755, 'config/petticoat.rb' => 0o644 }.freeze
+
+    def initialize(root:)
+      @root = File.realpath(root)
+    end
+
+    def call(dry_run: false, out: $stdout)
+      entries = plan
+      entries.each { |entry| out.puts "#{entry.fetch(:state)} #{entry.fetch(:relative)}" }
+      additions = entries.select { |entry| entry.fetch(:state) == 'create' }
+      publish(additions) unless dry_run || additions.empty?
+      out.puts(dry_run ? 'Petticoat dry run: no files written.' : 'Petticoat starter installed.')
+      out.puts 'Next: edit config/petticoat.rb.' unless dry_run
+      out.puts 'See the Petticoat README. Install does not configure or start your app, or generate catalogues.'
+      entries
+    end
+
+    private
+
+    def files
+      directory = File.expand_path('../../templates', __dir__)
+      FILES.to_h do |path, mode|
+        source = InstallationPath.new(directory, path).checked
+        [path, { bytes: File.binread(source), mode: mode }]
+      end
+    end
+
+    def plan
+      entries = files.sort.map { |relative, file| entry(relative, file) }
+      conflicts = entries.select { |item| item.fetch(:state) == 'conflict' }
+      unless conflicts.empty?
+        names = conflicts.map { |item| item.fetch(:relative) }.join(', ')
+        raise Error, "Petticoat installation conflicts: #{names}. " \
+                     'No files written. Review existing integration files; there is no --force.'
+      end
+      entries
+    end
+
+    def entry(relative, file)
+      raise Error, 'Petticoat: target is outside the two-file starter.' unless FILES.key?(relative)
+
+      path = InstallationPath.new(@root, relative).checked
+      state = if !File.exist?(path)
+                'create'
+              elsif identical?(path, file)
+                'unchanged'
+              else
+                'conflict'
+              end
+      file.merge(relative: relative, path: path, state: state)
+    end
+
+    def identical?(path, file)
+      File.binread(path) == file.fetch(:bytes) && (File.stat(path).mode & 0o777) == file.fetch(:mode)
+    end
+
+    def publish(entries)
+      staged = []
+      installed = []
+      directories = []
+      begin
+        entries.each { |entry| staged << stage(entry) }
+        staged.each { |entry| install_file(entry, installed, directories) }
+      rescue StandardError
+        rollback(installed, directories)
+        raise
+      ensure
+        staged.each { |entry| entry.fetch(:temporary).close! }
+      end
+    end
+
+    def stage(entry)
+      file = Tempfile.new('.petticoat-install-', @root)
+      file.binmode
+      file.write(entry.fetch(:bytes))
+      file.flush
+      file.fsync
+      file.chmod(entry.fetch(:mode))
+      entry.merge(temporary: file)
+    rescue StandardError
+      file&.close!
+      raise
+    end
+
+    def install_file(entry, installed, directories)
+      InstallationPath.new(@root, entry.fetch(:relative)).checked
+      make_parents(File.dirname(entry.fetch(:path)), directories)
+      # Exclusive creation, including when another writer races the preflight.
+      File.link(entry.fetch(:temporary).path, entry.fetch(:path))
+      installed << entry.merge(identity: File.stat(entry.fetch(:path)).ino)
+    end
+
+    def make_parents(directory, created)
+      return if directory == @root || File.directory?(directory)
+
+      make_parents(File.dirname(directory), created)
+      Dir.mkdir(directory)
+      created << { path: directory, identity: File.stat(directory).ino }
+    end
+
+    def rollback(installed, directories)
+      installed.reverse_each { |entry| remove_owned_file(entry) }
+      directories.reverse_each do |entry|
+        path = entry.fetch(:path)
+        next unless File.directory?(path) && File.realpath(path) == path &&
+                    File.stat(path).ino == entry.fetch(:identity)
+
+        Dir.rmdir(path)
+      rescue SystemCallError
+        # Preserve nonempty or concurrently changed directories.
+        next
+      end
+    end
+
+    def remove_owned_file(entry)
+      path = InstallationPath.new(@root, entry.fetch(:relative)).checked
+      return unless File.file?(path) && File.stat(path).ino == entry.fetch(:identity) && identical?(path, entry)
+
+      File.unlink(path)
+    rescue StandardError
+      warn 'Petticoat: installation rollback could not remove an owned file; inspect the planned paths.'
+    end
+  end
+end

data/lib/petticoat/schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Petticoat observed capability catalogue",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "enum": [
+        1
+      ]
+    },
+    "adapter": {
+      "enum": [
+        "cancancan-3.6.0-18ce8ad80065"
+      ]
+    },
+    "scope": {
+      "enum": [
+        "observed_ability_construction"
+      ]
+    },
+    "digest": {
+      "$ref": "#/definitions/digest"
+    },
+    "subjects": {
+      "$ref": "#/definitions/strings"
+    },
+    "contexts": {
+      "type": "object"
+    },
+    "defaults": {
+      "enum": [
+        {
+          "state": "denied",
+          "scope": "registered_subjects_in_present_entries"
+        }
+      ]
+    },
+    "basis": {
+      "enum": [
+        "observed_scenarios"
+      ]
+    },
+    "view": {
+      "enum": [
+        "resources",
+        "actions"
+      ]
+    }
+  },
+  "required": [
+    "schema_version",
+    "adapter",
+    "scope",
+    "digest",
+    "subjects",
+    "contexts",
+    "defaults",
+    "basis",
+    "view"
+  ],
+  "additionalProperties": false,
+  "definitions": {
+    "digest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "strings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "actions": {
+      "type": "object",
+      "additionalProperties": {
+        "enum": [
+          "unconditional",
+          "conditional",
+          "denied",
+          "unknown"
+        ]
+      }
+    },
+    "states": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/actions"
+      }
+    },
+    "resources_contexts": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/resources_context"
+      }
+    },
+    "actions_contexts": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/actions_context"
+      }
+    },
+    "actions_context": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "enum": [
+            "individual",
+            "composed"
+          ]
+        },
+        "roles": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/states"
+          }
+        }
+      },
+      "required": [
+        "scope",
+        "roles"
+      ],
+      "additionalProperties": false
+    },
+    "resource_roles": {
+      "type": "object",
+      "properties": {
+        "possible": {
+          "$ref": "#/definitions/strings"
+        },
+        "unknown": {
+          "$ref": "#/definitions/strings"
+        }
+      },
+      "required": [
+        "possible",
+        "unknown"
+      ],
+      "additionalProperties": false
+    },
+    "resources_context": {
+      "type": "object",
+      "properties": {
+        "scope": {
+          "enum": [
+            "individual",
+            "composed"
+          ]
+        },
+        "examined_roles": {
+          "$ref": "#/definitions/strings"
+        },
+        "resources": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/resource_roles"
+          }
+        }
+      },
+      "required": [
+        "scope",
+        "examined_roles",
+        "resources"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "allOf": [
+    {
+      "oneOf": [
+        {
+          "properties": {
+            "view": {
+              "enum": [
+                "resources"
+              ]
+            },
+            "contexts": {
+              "$ref": "#/definitions/resources_contexts"
+            }
+          }
+        },
+        {
+          "properties": {
+            "view": {
+              "enum": [
+                "actions"
+              ]
+            },
+            "contexts": {
+              "$ref": "#/definitions/actions_contexts"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

data/lib/petticoat/schema.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module Petticoat
+  module Schema
+    PATH = File.expand_path('schema.json', __dir__).freeze
+
+    def self.validate!(payload)
+      JSON::Validator.validate!(PATH, payload, validate_schema: true)
+      validate_contexts!(payload.fetch('contexts'), subjects: payload.fetch('subjects'), view: payload.fetch('view'))
+      expected = Digest::SHA256.hexdigest(Petticoat.canonical_json(payload.except('digest')))
+      raise Error, 'Content digest mismatch' unless payload.fetch('digest') == expected
+
+      payload
+    end
+
+    # The shape is schema-validated first; these invariants relate sibling fields.
+    def self.validate_contexts!(contexts, subjects:, view:)
+      contexts.each_value do |context|
+        if view == 'resources'
+          validate_resource_roles!(context, subjects)
+        else
+          context.fetch('roles').each_value do |states|
+            raise Error, 'Unregistered action subject' unless (states.keys - subjects).empty?
+          end
+        end
+      end
+      contexts
+    end
+
+    def self.validate_resource_roles!(context, subjects)
+      examined = context.fetch('examined_roles')
+      context.fetch('resources').each do |subject, entry|
+        possible, unknown = entry.values_at('possible', 'unknown')
+        unless subjects.include?(subject) && !possible.intersect?(unknown) &&
+               ((possible + unknown) - examined).empty?
+          raise Error, 'Resource role lists conflict with examined scope'
+        end
+      end
+    end
+    private_class_method :validate_resource_roles!
+  end
+end

data/lib/petticoat/snapshot.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Petticoat
+  class Snapshot
+    attr_reader :adapter
+
+    def initialize(ability)
+      @adapter = Adapter.new(ability)
+    end
+
+    def state(action, subject)
+      return 'unknown' if unsupported?
+
+      # An object cannot equal an explicit Symbol action, so this queries only
+      # manage grants. No permission predicate is evaluated.
+      query = action == '*' ? Object.new : action.to_sym
+      relevant = adapter.relevant(query, subject)
+      return 'unknown' if raw_conditions?(relevant)
+
+      possibilities = outcomes(relevant)
+      return 'conditional' if possibilities.size > 1
+
+      possibilities.first ? 'unconditional' : 'denied'
+    end
+
+    def actions
+      adapter.actions.grep(Symbol).map(&:to_s).sort
+    end
+
+    def aliases
+      adapter.aliases.to_h { |key, values| [key.to_s, values.map(&:to_s).uniq.sort] }
+    end
+
+    def subjects
+      adapter.rules.flat_map(&:subjects).uniq
+    end
+
+    def evidence(subject_identifier)
+      adapter.rules.map do |rule|
+        {
+          'allow' => rule.base_behavior,
+          'actions' => rule.actions.filter_map { |action| action.to_s if action.is_a?(Symbol) },
+          'subjects' => rule.subjects.map { |subject| subject_identifier.call(subject) || 'unsupported' },
+          'predicate' => predicate_kind(rule),
+          'attributes_restricted' => !rule.attributes.empty?
+        }
+      end
+    end
+
+    private
+
+    def raw_conditions?(relevant)
+      relevant.any? { |rule| !rule.conditions.is_a?(Hash) && !rule.conditions.nil? }
+    end
+
+    def outcomes(relevant)
+      relevant.reverse_each.reduce([false]) do |values, rule|
+        conditional?(rule) ? values | [rule.base_behavior] : [rule.base_behavior]
+      end
+    end
+
+    def conditional?(rule)
+      rule.block || !rule.attributes.empty? || (rule.conditions && !rule.conditions.empty?)
+    end
+
+    def unsupported?
+      !adapter.issues.empty? || adapter.unsupported_subjects? ||
+        adapter.rules.any? { |rule| rule.actions.empty? || rule.actions.any? { |action| !action.is_a?(Symbol) } }
+    end
+
+    def predicate_kind(rule)
+      return 'block' if rule.block
+      return 'none' if rule.conditions.nil? || (rule.conditions.is_a?(Hash) && rule.conditions.empty?)
+
+      rule.conditions.is_a?(Hash) ? 'hash' : 'unsupported'
+    end
+  end
+end

data/lib/petticoat/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Petticoat
+  VERSION = '0.2.0'
+end

data/lib/petticoat.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+require 'cancan'
+require_relative 'petticoat/version'
+
+module Petticoat
+  class Error < StandardError; end
+
+  def self.canonical(value)
+    case value
+    when Hash then value.keys.sort.to_h { |key| [key, canonical(value.fetch(key))] }
+    when Array then value.map { |item| canonical(item) }
+    else value
+    end
+  end
+
+  def self.canonical_json(value)
+    "#{JSON.pretty_generate(canonical(value))}\n"
+  end
+end
+
+require_relative 'petticoat/adapter'
+require_relative 'petticoat/snapshot'
+require_relative 'petticoat/document'
+require_relative 'petticoat/schema'

data/templates/bin/petticoat

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Generated by Petticoat. The gem owns the executable; the app owns its integration.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+ENV['BUNDLE_FROZEN'] = 'true'
+require 'bundler/setup'
+load Gem.bin_path('petticoat', 'petticoat')

data/templates/config/petticoat.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Command configuration, not a framework initializer. Only export/check/test load it.
+# Require your application-owned runner here, then replace the error below with:
+# Petticoat::CLI.integration = YourApplication::CapabilityRunner
+#
+# The runner implements call(mode:, arguments:, options:, out:).
+# It owns safe test setup, scenario construction, output paths and publication.
+# It must raise on failure; returning false or an exit code is not sufficient.
+# See the Petticoat README, "Connect your application", for the complete contract.
+raise Petticoat::Error, 'Petticoat: integration is not configured. ' \
+                        'Edit config/petticoat.rb to select your application runner.'

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: petticoat
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Maurizio De Magnis <root@olisti.co>
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cancancan
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.21'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 6.2.0
+description: Captures completed abilities and conservatively exports deterministic
+  role/resource/action catalogues.
+executables:
+- petticoat
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/petticoat
+- lib/petticoat.rb
+- lib/petticoat/adapter.rb
+- lib/petticoat/cli.rb
+- lib/petticoat/document.rb
+- lib/petticoat/installation_path.rb
+- lib/petticoat/installer.rb
+- lib/petticoat/schema.json
+- lib/petticoat/schema.rb
+- lib/petticoat/snapshot.rb
+- lib/petticoat/version.rb
+- templates/bin/petticoat
+- templates/config/petticoat.rb
+homepage: https://source.olisti.co/olisti.co/petticoat
+licenses:
+- Nonstandard
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Observed UI capability catalogues from CanCanCan abilities
+test_files: []