placet 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40264b6092cdd9603f06a99d7a319bc53bfc3e309ff1457dce7f943f22ea3b70
-  data.tar.gz: e35bb7aa9e234acb23f57dbac7a0c01457746f772f548d62d84c90471b1ef279
+  metadata.gz: 2d415c5785fb1644baaf3c3ab610b931b059fb41794e03436556cb660953cf86
+  data.tar.gz: 806a4ad95bf60a3d38da95035a26eeffc99e76cd6fd3efb193058862c7319045
 SHA512:
-  metadata.gz: 2a842d373a4144dff69a586e1424774e7af86196f393f015bb6388013565f2557ce938d8d26452d192f634bf16297adf46d3ef3cd259de8a3e7a465fbc839d28
-  data.tar.gz: 0cfa85a2a33f3de96cd5366940a93f183f655e8ee58263bff0a920b4b5e386b2511c2a57a78785f818045e9826072cc4819188894285afe7deaef07554a36072
+  metadata.gz: 99c24faf6e6ea23af66494a24166f1866d1364eb79c7eb62959d7dca9b675a0fb297e574cb90a1e6e2eafda09d73297bb0e5f28784df39b5f9d47a73e4c7ed9a
+  data.tar.gz: dd10b1484a2b0377668760c424aef678f8781e041feafe199b75766f183d8f58bc2db2dbc6abcb62da8fb6bd1ca952002307ca3be555a8846f570c4c7bf0b92e

data/README.md

@@ -1,52 +1,32 @@
-# placet
+# placet (Ruby)
 
 > 宣言的な権限管理ライブラリ — simplified IAM-style authorization（コンセプト策定中）
 
-placet は、AWS IAM の権限モデル（principal への policy アタッチ、explicit deny の優先、implicit deny）を簡略化し、一般のアプリケーションに導入できるようにすることを目指す権限管理ライブラリです。評価器の内部構造は XACML のアーキテクチャ（PEP / PDP / PIP / PAP の役割分離）を参考にしています。
+placet の Ruby ランタイム（リファレンス実装）です。コア評価エンジン（PDP）・Ruby DSL・principal 導出（resolver / derive / relation）・scope 合成を実装し、[spec/conformance](../../spec/conformance) の適合性テストをすべてパスします。
 
-現在は**コンセプト策定フェーズ**であり、実装はまだありません。設計の全体と各判断の経緯は [docs/concept.md](docs/concept.md) にまとまっています。
+## インストール
 
-## モデルの概要
-
-- アクセスユーザーは、`user:42` / `role:editor` / `tenant:acme` のような複数の **principal**（主体の「面」）を持ち、アプリケーション DB の情報から導出される
-- 操作は `post:view` のような **action** で表され、action に対する allow / deny の集合が **policy** として principal にアタッチされる
-- 決定は **deny-overrides**（1 つでも deny があれば拒否）と **implicit deny**（どこにもマッチしなければ拒否）に固定され、常に「どの policy のどの statement が決め手か」という根拠つきで返される
-
-```yaml
-policies:
-  - name: post-editor
-    statements:
-      - effect: allow
-        actions: [post:create, post:update, post:delete]
-
-  - name: suspended
-    statements:
-      - effect: deny
-        actions: ["*"]
-
-attachments:
-  - principal: role:editor
-    policies: [post-editor]
-  - principal: flag:suspended
-    policies: [suspended]
+```ruby
+# Gemfile
+gem "placet"
 ```
 
-`role:editor` を持つユーザーの `post:update` は許可され、凍結されたユーザー（`flag:suspended` の面を持つユーザー）は allow の有無にかかわらず全操作が拒否されます。
+Rails 統合（宣言 DSL・ActiveRecord への scope 合成）には [placet-rails](../rails) を併用してください。動く例は [examples/sinatra](../../examples/sinatra) を参照。
 
-## 設計上の特徴
+テストの実行:
 
-- **結合則は deny-overrides のみ** — 設定による差し替えを提供しない。Policy を読めば結果が一意に予測できる
-- **動的な状態は principal 導出で吸収する** — Policy と attachment は静的でデプロイ時に固定。実行時に変わるのはユーザーの principal 集合だけ
-- **リソース個体認可は関係 principal（簡易 ReBAC）** — 「作成者本人のみ編集可」を `rel:owner` のような関係の面として表現し、評価器の仕様は変えない
-- **一覧フィルタリングを仕様に含む** — 「閲覧できるものだけを返す」を、関係ごとの scope の和・差として DB クエリに合成する
-- **言語非依存の 3 層構造** — コア仕様（フォーマット + 評価セマンティクス + 適合性テスト）/ 言語ランタイム / ORM・フレームワークアダプタ
+```sh
+cd packages/ruby
+for f in test/*_test.rb; do ruby -Ilib -Itest "$f"; done
+```
 
-## ステータス
+- プロジェクト全体: https://github.com/aspick/placet
+- 設計ドキュメント: https://github.com/aspick/placet/blob/main/docs/concept.md
 
-- [x] コンセプトと設計判断の整理（[docs/concept.md](docs/concept.md)）
-- [ ] 正規形の JSON Schema
-- [ ] リファレンス実装（Ruby ランタイム + 適合性 fixture）
+## モデルの概要
 
-## 名前について
+- アクセスユーザーは `user:42` / `role:editor` / `tenant:acme` のような複数の **principal**（主体の「面」）を持つ
+- 操作は `post:view` のような **action** で表され、allow / deny の集合が **policy** として principal にアタッチされる
+- 決定は **deny-overrides** と **implicit deny** に固定され、常に根拠つきで返される
 
-placet はラテン語で「可とする」。大学や教会の採決で用いられる placet / non placet（可 / 否）に由来します。読みは「プラケット」です。
+将来的には、このランタイムの上に ActiveRecord アダプタ・Rails PEP ヘルパー（一覧フィルタリングの scope 合成、呼び忘れ検知フック）が別 gem として提供される予定です。

data/lib/placet/action_registry.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Placet
+  # 既知の action を宣言して typo を検出するレジストリ（docs/rails-usage.md 2.5）。
+  # 評価セマンティクスに影響しない lint であり、正規形（version 1）には含まれない
+  # ランタイム機能なので、Definition（正規形と 1:1）ではなくランタイムが所有する
+  class ActionRegistry
+    def initialize
+      @by_resource = {}
+    end
+
+    def add(resource, operations)
+      (@by_resource[resource] ||= Set.new).merge(operations)
+    end
+
+    # 宣言が 1 つもない場合、レジストリは未使用（lint 無効）として扱う
+    def empty? = @by_resource.empty?
+
+    # 具体的な action の照合
+    def known_action?(action)
+      return true if empty?
+
+      resource, operation = action.split(":", 2)
+      @by_resource.key?(resource) && @by_resource[resource].include?(operation)
+    end
+
+    # パターン（ワイルドカード可）の照合
+    def known_pattern?(pattern)
+      return true if empty? || pattern == "*"
+
+      resource, operation = pattern.split(":", 2)
+      return false if resource != "*" && !@by_resource.key?(resource)
+      return true if operation == "*"
+
+      if resource == "*"
+        @by_resource.values.any? { |ops| ops.include?(operation) }
+      else
+        @by_resource[resource].include?(operation)
+      end
+    end
+  end
+end

data/lib/placet/decision.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Placet
+  # 決め手になった statement。via は derive による導出の連鎖（concept.md 3.6）
+  Determinant = Struct.new(:principal, :policy, :statement, :effect, :via, keyword_init: true) do
+    def to_h = super.compact
+  end
+
+  # 根拠つきの決定。basis は :explicit_allow / :explicit_deny / :implicit_deny
+  Decision = Struct.new(:decision, :basis, :determinants, keyword_init: true) do
+    def permit? = decision == :permit
+    def to_h = { decision: decision, basis: basis, determinants: determinants.map(&:to_h) }
+  end
+end

data/lib/placet/document.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Placet
+  ACTION_PATTERN_RE  = /\A(\*|(\*|[a-z][a-z0-9_]*):(\*|[a-z][a-z0-9_]*))\z/
+  CONCRETE_ACTION_RE = /\A[a-z][a-z0-9_]*:[a-z][a-z0-9_]*\z/
+  PRINCIPAL_RE       = /\A[a-z][a-z0-9_-]*:[^\s*]+\z/
+  POLICY_NAME_RE     = /\A[a-z][a-z0-9_-]*\z/
+
+  Statement = Struct.new(:effect, :actions, keyword_init: true)
+
+  # Policy 定義の保持と検証。正規形（spec/schema/policy-document.schema.json）と 1:1
+  class Definition
+    attr_reader :policies, :attachments
+
+    def initialize
+      @policies = {}     # name => [Statement]
+      @attachments = {}  # principal => [policy names]
+    end
+
+    # 正規形（JSON 互換 Hash・文字列キー）からの読み込み
+    def self.from_canonical(doc)
+      raise DefinitionError, "ドキュメントが Hash ではない" unless doc.is_a?(Hash)
+
+      version = doc["version"]
+      raise DefinitionError, "未対応の version: #{version.inspect}" unless version == 1
+
+      definition = new
+      Array(doc["policies"]).each do |policy|
+        statements = Array(policy["statements"]).map do |st|
+          effect = st["effect"]
+          raise DefinitionError, "effect が不正: #{effect.inspect}" unless %w[allow deny].include?(effect)
+
+          Statement.new(effect: effect, actions: Array(st["actions"]))
+        end
+        definition.add_policy(policy["name"], statements)
+      end
+      Array(doc["attachments"]).each do |attachment|
+        definition.add_attachment(attachment["principal"], Array(attachment["policies"]))
+      end
+      definition.validate!
+      definition
+    end
+
+    def add_policy(name, statements)
+      raise DefinitionError, "policy 名が不正: #{name.inspect}" unless name.is_a?(String) && name =~ POLICY_NAME_RE
+      raise DefinitionError, "policy 名が重複: #{name}" if @policies.key?(name)
+      raise DefinitionError, "statements が空: #{name}" if statements.empty?
+
+      @policies[name] = statements
+    end
+
+    def add_attachment(principal, names)
+      unless principal.is_a?(String) && principal =~ PRINCIPAL_RE
+        raise DefinitionError, "principal が不正（type:id 形式・* 不可）: #{principal.inspect}"
+      end
+
+      @attachments[principal] = (@attachments[principal] || []) | names
+    end
+
+    # registry を渡すと、action パターンのレジストリ照合（lint）もあわせて行う
+    def validate!(registry = nil)
+      @attachments.each do |principal, names|
+        names.each do |name|
+          unless @policies.key?(name)
+            raise DefinitionError, "attachment が未定義の policy を参照: #{name} (principal: #{principal})"
+          end
+        end
+      end
+      @policies.each do |name, statements|
+        statements.each { |st| st.actions.each { |pattern| validate_pattern!(pattern, name, registry) } }
+      end
+      self
+    end
+
+    def to_canonical
+      {
+        "version" => 1,
+        "policies" => @policies.map do |name, statements|
+          { "name" => name,
+            "statements" => statements.map { |s| { "effect" => s.effect, "actions" => s.actions } } }
+        end,
+        "attachments" => @attachments.map do |principal, names|
+          { "principal" => principal, "policies" => names }
+        end
+      }
+    end
+
+    private
+
+    def validate_pattern!(pattern, policy_name, registry)
+      unless pattern.is_a?(String) && pattern =~ ACTION_PATTERN_RE
+        raise DefinitionError, "action パターンが不正: #{pattern.inspect} (policy: #{policy_name})"
+      end
+      return if registry.nil? || registry.known_pattern?(pattern)
+
+      raise DefinitionError, "未知の action: #{pattern} (policy: #{policy_name})"
+    end
+  end
+end

data/lib/placet/dsl.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Placet
+  # Ruby DSL（docs/rails-usage.md 2.2）。評価結果は正規形と等価な Definition になる
+  class PolicyBuilder
+    attr_reader :statements
+
+    def initialize = @statements = []
+    def allow(*actions) = @statements << Statement.new(effect: "allow", actions: actions.flatten)
+    def deny(*actions)  = @statements << Statement.new(effect: "deny",  actions: actions.flatten)
+  end
+
+  class DefinitionBuilder
+    def initialize(definition, registry)
+      @definition = definition
+      @registry = registry
+    end
+
+    def actions(resource, operations) = @registry.add(resource, operations)
+
+    def policy(name, attach_to: nil, &block)
+      builder = PolicyBuilder.new
+      builder.instance_eval(&block)
+      @definition.add_policy(name, builder.statements)
+      Array(attach_to).each { |principal| @definition.add_attachment(principal, [name]) }
+    end
+
+    def attach(principal, *names) = @definition.add_attachment(principal, names.flatten)
+  end
+
+  # relation は check（個体判定）と scope（一覧用の逆写像）を必ずペアで宣言する
+  Relation = Struct.new(:name, :check, :scope, keyword_init: true)
+
+  class RelationBuilder
+    attr_reader :check_block, :scope_block
+
+    def check(&block) = @check_block = block
+    def scope(&block) = @scope_block = block
+  end
+end

data/lib/placet/engine.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Placet
+  # action パターンのマッチング（concept.md 3.3: セグメント単位で literal か *）
+  module ActionMatch
+    def self.match?(pattern, action)
+      return true if pattern == "*"
+
+      p_res, p_op = pattern.split(":", 2)
+      a_res, a_op = action.split(":", 2)
+      (p_res == "*" || p_res == a_res) && (p_op == "*" || p_op == a_op)
+    end
+  end
+
+  # 一覧フィルタリングの集合演算の計画（concept.md 8.4 / spec/conformance/README.md）。
+  # ORM アダプタはこの plan を WHERE 句へ写像する
+  ScopePlan = Struct.new(:kind, :include_relations, :exclude_relations, keyword_init: true)
+
+  # コア評価エンジン（PDP）。純粋関数として動作し、適合性テストの対象となる。
+  # 入力は principal 文字列の配列のみで、derive の由来（via）などランタイム層の
+  # 拡張は関知しない
+  class Engine
+    def initialize(definition, registry: nil)
+      @definition = definition
+      @registry = registry
+      @grant_cache = {}
+      @match_cache = {}
+      @valid_actions = Set.new
+    end
+
+    def decide(principals, action)
+      validate_action!(action)
+      matches = matches_for(action)
+
+      matched = []
+      principals.each do |principal|
+        @definition.attachments.fetch(principal, []).each do |policy_name|
+          matches.fetch(policy_name, []).each do |index, effect|
+            matched << Determinant.new(principal: principal, policy: policy_name,
+                                       statement: index, effect: effect)
+          end
+        end
+      end
+
+      denies, allows = matched.partition { |m| m.effect == "deny" }
+      return Decision.new(decision: :deny, basis: :explicit_deny, determinants: denies) if denies.any?
+      return Decision.new(decision: :permit, basis: :explicit_allow, determinants: allows) if allows.any?
+
+      Decision.new(decision: :deny, basis: :implicit_deny, determinants: [])
+    end
+
+    # 一覧フィルタリングの計画を返す。
+    # static_principals: 静的 principal（rel: を含まない導出結果）
+    # relations: 対象モデルに定義された relation 名のリスト
+    def scope_plan(static_principals, action, relations:)
+      validate_action!(action)
+      allow_ps, deny_ps = grants(action)
+      static = static_principals.to_a
+
+      if static.any? { |p| deny_ps.include?(p) }
+        return ScopePlan.new(kind: "empty", include_relations: [], exclude_relations: [])
+      end
+
+      exclude = relations.select { |name| deny_ps.include?("rel:#{name}") }
+
+      if static.any? { |p| allow_ps.include?(p) }
+        return ScopePlan.new(kind: "all", include_relations: [], exclude_relations: exclude)
+      end
+
+      include_ = relations.select { |name| allow_ps.include?("rel:#{name}") }
+      if include_.empty?
+        ScopePlan.new(kind: "empty", include_relations: [], exclude_relations: [])
+      else
+        ScopePlan.new(kind: "union", include_relations: include_, exclude_relations: exclude)
+      end
+    end
+
+    # action 検証の一元的な入口。決定要求・scope 合成の action は具体的
+    # （ワイルドカード不可）かつレジストリ宣言済み（使用時）でなければならない。
+    # typo は静かな全拒否 / 空 scope になるため即エラーにする。
+    # 宣言時 fail-fast には error_class に DefinitionError を渡して使う
+    def validate_action!(action, error_class: Error)
+      return if @valid_actions.include?(action)
+
+      unless action.is_a?(String) && action =~ CONCRETE_ACTION_RE
+        raise error_class, "action は具体的でなければならない: #{action.inspect}"
+      end
+      unless @registry.nil? || @registry.known_action?(action)
+        raise error_class, "未知の action: #{action}（レジストリに未宣言）"
+      end
+
+      @valid_actions << action
+    end
+
+    private
+
+    # action ごとの「マッチ済み statement 索引」（policy 名 => [[index, effect]]）。
+    # 定義は Engine 生成後に不変なのでキャッシュできる。decide の毎回の
+    # 全 statement 走査と action 文字列の split 繰り返しを避ける
+    def matches_for(action)
+      @match_cache[action] ||= @definition.policies.each_with_object({}) do |(name, statements), out|
+        hits = statements.each_with_index.filter_map do |st, index|
+          [index, st.effect] if statement_matches?(st, action)
+        end
+        out[name] = hits unless hits.empty?
+      end
+    end
+
+    def statement_matches?(statement, action)
+      statement.actions.any? { |pattern| ActionMatch.match?(pattern, action) }
+    end
+
+    # action → allow / deny を与える principal 集合の逆引き（起動時コンパイル相当）
+    def grants(action)
+      @grant_cache[action] ||= begin
+        allow = Set.new
+        deny = Set.new
+        @definition.attachments.each do |principal, names|
+          names.each do |name|
+            @definition.policies[name].each do |st|
+              (st.effect == "deny" ? deny : allow) << principal if statement_matches?(st, action)
+            end
+          end
+        end
+        [allow, deny]
+      end
+    end
+  end
+end

data/lib/placet/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Placet
+  class Error < StandardError; end
+
+  # 定義（Policy / attachment / relation）の不備。起動時に検出される
+  class DefinitionError < Error; end
+
+  # authorize! が拒否されたときに送出される。decision に根拠が入る
+  class Denied < Error
+    attr_reader :action, :decision
+
+    def initialize(action, decision)
+      @action = action
+      @decision = decision
+      super("denied: #{action} (#{decision.basis})")
+    end
+  end
+end

data/lib/placet/explain.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Placet
+  # 実効権限と決定根拠の説明表示（rails placet:explain 等が利用する）。
+  # Rails には依存しない。resolver はアプリの user オブジェクトを必要とするため、
+  # explain は principal 集合を直接受け取り、derive の 1 段展開だけを適用する
+  module Explain
+    module_function
+
+    # principal に直接・derive 経由でアタッチされる policy を一覧する
+    def principal_report(principal)
+      lines = [principal]
+      Placet.expand_principals([principal]).each do |expanded, via|
+        if expanded == principal
+          append_policies(lines, expanded, indent: "  ")
+        else
+          lines << "  └─ #{expanded}（#{via.join(' ← ')} から導出）"
+          append_policies(lines, expanded, indent: "       ")
+        end
+      end
+      lines.join("\n")
+    end
+
+    # principal 集合（derive 展開込み）で action を判定し、根拠を表示する
+    def decision_report(principals, action)
+      decision = Placet.decide_with_provenance(Placet.expand_principals(principals), action)
+      lines = ["#{decision.decision} (#{decision.basis})"]
+      decision.determinants.each do |d|
+        line = "└─ #{d.effect}: policy \"#{d.policy}\" statement #{d.statement} via #{d.principal}"
+        line += " ← #{d.via.join(' ← ')}" if d.via
+        lines << line
+      end
+      lines << "└─ マッチする statement なし（implicit deny）" if decision.determinants.empty?
+      lines.join("\n")
+    end
+
+    def append_policies(lines, principal, indent:)
+      names = Placet.definition.attachments.fetch(principal, [])
+      return lines << "#{indent}（アタッチされた policy なし）" if names.empty?
+
+      names.each do |name|
+        lines << "#{indent}policy: #{name}"
+        Placet.definition.policies[name].each do |st|
+          lines << "#{indent}  #{st.effect} #{st.actions.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/placet/runtime.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Placet
+  # モジュールレベルのランタイム API（docs/rails-usage.md）。
+  # 定義（静的）と principal 導出（動的）をつなぎ、Engine に決定を委譲する
+  class << self
+    def definition = (@definition ||= Definition.new)
+    def registry = (@registry ||= ActionRegistry.new)
+    def engine = (@engine ||= Engine.new(definition, registry: registry))
+
+    def define(&block)
+      DefinitionBuilder.new(definition, registry).instance_eval(&block)
+      definition.validate!(registry)
+      @engine = nil
+    end
+
+    def resolver(&block) = @resolver = block
+
+    def derive(type_pattern, &block)
+      type = type_pattern.delete_suffix(":*").delete_suffix(":")
+      ((@derives ||= {})[type] ||= []) << block
+    end
+
+    def relation(name, resource:, &block)
+      builder = RelationBuilder.new
+      builder.instance_eval(&block)
+      unless builder.check_block && builder.scope_block
+        raise DefinitionError, "relation は check と scope をペアで宣言する: #{name}"
+      end
+
+      ((@relations ||= {})[resource] ||= []) <<
+        Relation.new(name: name.to_s, check: builder.check_block, scope: builder.scope_block)
+    end
+
+    # 与えられた principal 集合に derive の 1 段展開を適用する。
+    # 戻り値は { principal => 由来の連鎖 (Array) }
+    def expand_principals(base)
+      out = {}
+      base.each { |p| out[p] = [] }
+      base.each do |p|
+        type, id = p.split(":", 2)
+        derive_hooks(type).each do |hook|
+          Array(hook.call(id)).each { |derived| out[derived] ||= [p] }
+        end
+      end
+      out
+    end
+
+    # principal 集合の導出。戻り値は { principal => 由来の連鎖 (Array) }
+    def principals_for(user, resource = nil)
+      with_relation_principals(expand_principals(Array(@resolver&.call(user))), user, resource)
+    end
+
+    # 複数 action は AND（fail-fast）。docs/rails-usage.md 4.2
+    def decide(user, actions, resource = nil)
+      last = nil
+      decide_each(user, actions, resource) do |_action, decision|
+        last = decision
+        return decision unless decision.permit?
+      end
+      last
+    end
+
+    def authorize!(user, actions, resource = nil)
+      count_enforcement!
+      decide_each(user, actions, resource) do |action, decision|
+        raise Denied.new(action, decision) unless decision.permit?
+      end
+      true
+    end
+
+    def permit?(user, actions, resource = nil) = decide(user, actions, resource).permit?
+
+    # 由来つきの principal 集合（Hash）で判定し、determinants に由来（via）を付与する。
+    # Engine は仕様どおり principal の配列のみを受けるため、via の装飾はこの層で行う
+    def decide_with_provenance(principals, action)
+      decision = engine.decide(principals.keys, action)
+      decision.determinants.each do |determinant|
+        via = principals[determinant.principal]
+        determinant.via = via unless via.nil? || via.empty?
+      end
+      decision
+    end
+
+    # action 検証の公開入口（Engine に委譲）。アダプタの宣言時 fail-fast にも使う
+    def validate_action!(action, error_class: Error)
+      engine.validate_action!(action, error_class: error_class)
+    end
+
+    # 一覧の scope 合成。Engine の plan を、登録された materializer（ORM アダプタ）
+    # またはインメモリの既定実装でコレクションへ写像する
+    def scoped(user, action, model:)
+      count_enforcement!
+      rels = relations_for(model)
+      plan = engine.scope_plan(principals_for(user).keys, action, relations: rels.map(&:name))
+      materializer_for(model).call(plan, rels, user, model)
+    end
+
+    # ORM アダプタが ScopePlan の実体化を登録する。matcher が true を返した
+    # model に materializer が適用される（後着優先。どれにもマッチしなければ
+    # インメモリの既定実装）。定義状態とは独立した登録なので reset! では消えない
+    def register_scope_materializer(matcher, materializer)
+      (@scope_materializers ||= []).unshift([matcher, materializer])
+    end
+
+    # relation 名の集合を scope 呼び出し結果へ写像する共通ヘルパー
+    # （インメモリ実装と ORM アダプタで共有）
+    def relation_scopes(relations, names, user)
+      relations.select { |r| names.include?(r.name) }.map { |r| r.scope.call(user) }
+    end
+
+    # このスレッドで enforcement（authorize! / scoped）が行われた回数。
+    # PEP ヘルパーの呼び忘れ検知（docs/rails-usage.md 4.4）が参照する
+    def enforcements = Thread.current[:placet_enforcements] || 0
+
+    # scope 合成の結果（通常は 1 ページ分）へ個体判定を再適用する二段構え。
+    # check / scope に乖離バグがあっても「見えてはいけないものが見える」方向には
+    # 倒れない（concept.md 11.5）。乖離レコードは on_recheck_divergence に通知して除外する。
+    # 静的 principal の導出（resolver + derive）はレコードに依存しないため 1 回だけ行う
+    def recheck(user, action, records)
+      base = expand_principals(Array(@resolver&.call(user)))
+      records.select do |record|
+        principals = with_relation_principals(base, user, record)
+        next true if engine.decide(principals.keys, action).permit?
+
+        if (handler = @on_recheck_divergence)
+          handler.call(user, action, record)
+        else
+          warn "placet: scope と check の乖離を検出: action=#{action} record=#{record.inspect}"
+        end
+        false
+      end
+    end
+
+    # 乖離検出時のハンドラ（user, action, record を受け取る）。既定は警告出力
+    attr_accessor :on_recheck_divergence
+
+    def export = definition.to_canonical
+
+    # テスト・再読み込み用: 定義と登録を破棄する（materializer は定義状態ではないため対象外）
+    def reset!
+      @definition = nil
+      @registry = nil
+      @engine = nil
+      @resolver = nil
+      @derives = nil
+      @relations = nil
+      @on_recheck_divergence = nil
+    end
+
+    # モデルに登録された relation の一覧（テストヘルパー・アダプタが参照する）
+    def relations_for(klass) = @relations ? @relations.fetch(klass, []) : []
+
+    private
+
+    def derive_hooks(type) = @derives ? @derives.fetch(type, []) : []
+    def count_enforcement! = Thread.current[:placet_enforcements] = enforcements + 1
+
+    # principals_for / decide / authorize! で共有する評価ループ。
+    # principal 導出は action に依存しないため、複数 action の AND でも 1 回で済ませる
+    def decide_each(user, actions, resource)
+      principals = principals_for(user, resource)
+      Array(actions).each do |action|
+        yield action, decide_with_provenance(principals, action)
+      end
+    end
+
+    # 由来つき principal 集合（base）に、resource との関係の面を追加する
+    def with_relation_principals(base, user, resource)
+      return base unless resource
+
+      out = base.dup
+      relations_for(resource.class).each do |rel|
+        out["rel:#{rel.name}"] ||= [] if rel.check.call(user, resource)
+      end
+      out
+    end
+
+    def materializer_for(model)
+      (@scope_materializers || []).each do |matcher, materializer|
+        return materializer if matcher.call(model)
+      end
+      method(:materialize_in_memory)
+    end
+
+    # 既定の実体化: インメモリコレクション（Array）に対する集合演算
+    def materialize_in_memory(plan, rels, user, model)
+      excluded = relation_scopes(rels, plan.exclude_relations, user).flatten(1)
+      case plan.kind
+      when "empty" then []
+      when "all"   then model.all.to_a - excluded
+      else
+        relation_scopes(rels, plan.include_relations, user).flatten(1).uniq - excluded
+      end
+    end
+  end
+end

data/lib/placet/test_helpers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "placet"
+
+module Placet
+  # テストスイートに include して使う検証ヘルパー（require "placet/test_helpers"）。
+  # minitest / RSpec のどちらからでも使える
+  module TestHelpers
+    # relation の check と scope の整合性を property test として検証する:
+    #   record ∈ scope(user) ⟺ check(user, record)
+    # 乖離（個体判定では見えるのに一覧に出ない / その逆）は「見えてはいけないものが
+    # 見える」事故の源泉なので、乖離を見つけた時点で詳細つきの例外を投げる
+    def verify_relation_consistency(name, resource:, users:, records:)
+      relation = Placet.relations_for(resource).find { |r| r.name == name.to_s }
+      raise Placet::Error, "relation が未定義: #{name} (resource: #{resource})" unless relation
+
+      users.each do |user|
+        scoped_records = relation.scope.call(user).to_a
+        records.each do |record|
+          in_scope = scoped_records.include?(record)
+          checked  = !!relation.check.call(user, record)
+          next if in_scope == checked
+
+          raise Placet::Error,
+                "relation #{name} の check と scope が乖離: " \
+                "user=#{user.inspect} record=#{record.inspect} scope=#{in_scope} check=#{checked}"
+        end
+      end
+      true
+    end
+  end
+end

data/lib/placet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Placet
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/placet.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "placet/version"
-
-raise NotImplementedError,
-      "placet is not implemented yet — this version is a placeholder to reserve the gem name. " \
-      "See https://github.com/aspick/placet for the concept and roadmap."
+require_relative "placet/errors"
+require_relative "placet/decision"
+require_relative "placet/document"
+require_relative "placet/action_registry"
+require_relative "placet/engine"
+require_relative "placet/dsl"
+require_relative "placet/runtime"
+require_relative "placet/explain"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: placet
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Yugo TERADA
@@ -22,6 +22,15 @@ files:
 - LICENSE
 - README.md
 - lib/placet.rb
+- lib/placet/action_registry.rb
+- lib/placet/decision.rb
+- lib/placet/document.rb
+- lib/placet/dsl.rb
+- lib/placet/engine.rb
+- lib/placet/errors.rb
+- lib/placet/explain.rb
+- lib/placet/runtime.rb
+- lib/placet/test_helpers.rb
 - lib/placet/version.rb
 homepage: https://github.com/aspick/placet
 licenses: