reeve 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c59f8e6c82441798415dbe8c2a0f53820615dfe8fcce4d96294ccc46d355208
-  data.tar.gz: 670b19c4de2bc2fab5c16b4fbb7c958b3ea64cede00615f219032ef27161626f
+  metadata.gz: bea7ce4962daf51d8ac269ab8fa8d95198d3dd0ab22fe534c2ddd0a0f79a8981
+  data.tar.gz: 8000630e05686b6d1a29c81e5b007f7a1b46f586aca9688870465c1b8b8d1d3a
 SHA512:
-  metadata.gz: 148721a9d10024026ff713a59ddf0fdf6cb1c32691f4c78c79961337a654f08c8f08b3445ba8a4630c00ce563553352c59194cc7355f00eae50942cf0f61cae0
-  data.tar.gz: 6b2b69206f97d2ca3278a3ccb37ba63a4ab74447a39de01f6e0c5ebe1c53aff5958a4c2389fafa0d55ae192bdd4035ed1df9d224e8fa49c7c4e52064bcdbe887
+  metadata.gz: 40886bd0fa070325c4e52eb41a9aa87e4f8cda355d71d68993641b62201aadd37243ce8988f0b9831d2aa33ef80a219d663a2c8b78cd4bd317dca411bbc70c48
+  data.tar.gz: b12725979b28ffa95cbd6838c9e6f1faadc47675894bd1d824c99632f7b0c715441b8c690eabd8f9d8873139a8be97b9cfa75eba22e97b0fa0a254287003f65b

data/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+All notable changes are recorded here. This project follows [Semantic
+Versioning](https://semver.org), with one rule specific to what it does — see
+[Versioning policy](#versioning-policy).
+
+## [0.1.0] - 2026-08-11
+
+First working release. The published 0.0.1 was a placeholder holding the gem name.
+
+### Added
+
+**Authorization**
+
+- `guard_with SomePolicy` declares the policy governing a tool. A tool without one is
+  denied (`no_guard_declared`) unless the host opts into `unguarded_tools =
+  :allow_with_warning`, which runs the tool unscoped and records `guard: "none"`.
+- `redact :argument_name` keeps an argument's value out of the ledger while keeping its
+  name.
+- `scoped(Model)` returns the policy-scoped relation inside a tool body. It is how a
+  guarded tool returns anything that is not a record: a count or a summary computed from
+  `scoped(...)` is safe because the tool never held unscoped data. A derived value
+  returned without it is denied (`unscoped_derived_result`).
+- Policy adapters for plain objects and for Pundit, behind one two-method protocol
+  (`authorize`, `scope`). `:auto` picks one and reports which through
+  `Reeve.config.resolved_policy_adapter`. Neither Pundit nor any authorization library is
+  a runtime dependency.
+- Per-record scoping for relations, arrays, single records, mixed types and derived
+  values. A single record outside the principal's scope is refused without naming it.
+
+**Audit**
+
+- One append-only `reeve_audit_entries` row per invocation, allowed or denied, recording
+  the agent, the principal, the tool, post-redaction arguments, returned identifiers, the
+  outcome, the rule that decided, and why it decided (`detail`).
+- The write happens in its own transaction, so a tool that raises and rolls back its own
+  work still leaves a trace — the invocations most worth recording are the ones that
+  failed.
+- A failed ledger write fails the invocation. `audit_failure_mode = :warn` degrades that
+  deliberately and must be opted into.
+- `Reeve::Audit::Query` queries the ledger by principal, agent, tool, outcome and time
+  range.
+- Entries are read-only after insert and refuse to be destroyed; the generated migration
+  documents the `GRANT INSERT, SELECT` that enforces what a library cannot.
+
+**Testing kit**
+
+- Seven framework-neutral checks (`CrossPrincipalLeak`, `AuditCoverage`, `GuardDeclared`,
+  `RulePresent`, `RedactionHolds`, `PrincipalRequired`, `ContractVersion`) plus
+  `Checks.run_all`, all plain Ruby that loads no test framework.
+- RSpec front-end (`require "reeve/rspec"`): `deny_access_for`, `audit_every_call`,
+  `pass_reeve_check`, and the `"a reeve-compliant server"` shared example group.
+- Minitest front-end (`require "reeve/minitest"`): the same guarantees from a stock
+  `rails new` application, with no RSpec installed.
+- Failure messages are built by the checks, so all three front-ends emit identical text.
+
+**Adoption**
+
+- `rails generate reeve:install` writes the initializer and the ledger migration.
+  `principal_resolver` ships as a TODO, because it is the one thing only the host can
+  answer, and reeve denies every call until it is filled in.
+- fast-mcp adapter (`require "reeve/fast_mcp"`): the DSL on every tool and the envelope
+  around every call, with the principal resolved from the request's headers. Needs Ruby
+  3.1+, because fast-mcp does.
+- `Reeve.invoke` gives the same guarantees with no Rails, no ActiveRecord and no MCP
+  server library.
+
+### Known limitations
+
+Stated here because finding them yourself later is worse than reading them now.
+
+- **A transaction the host wraps around an invocation takes the ledger row with it.** The
+  recorder writes in a savepoint, which protects the trace from a transaction the *tool*
+  opens and rolls back, but not from one already open around the whole call — a controller
+  that wraps each request, or a test suite using transactional fixtures. Reeve detects this
+  and warns, naming the invocation. Real isolation needs a second connection and is not
+  portable: on SQLite the enclosing transaction holds the write lock and a second
+  connection times out. Hosts needing durability there supply their own `audit_recorder`.
+- **An unscoped fetch by id still discloses existence.** `Invoice.find_by(id:)` denies for
+  a record that exists but belongs to someone else, and returns `nil` for one that does not
+  exist. Fetching through `scoped(...)` makes both answers `nil`.
+- **A scope-less type must be tied to its policy.** A plain object with an `id` is a
+  record, but a type with no relation cannot be checked against a policy scope — only
+  against `authorize`, which is often permissive. Such a type is trusted when a policy is
+  named for it or a `scoped(...)` call establishes provenance, and denied otherwise.
+- **A call that cannot be recorded fails, even when it was already failing.** An
+  unrecordable denial raises `AuditWriteError` carrying the denial as `#during`, rather
+  than the denial itself. With no recorder configured at all, that is the first thing you
+  will see, and it names the missing ledger.
+- **`AuditCoverage` proves one invocation is recorded**, not every invocation.
+- **The fast-mcp adapter needs Ruby 3.1+**, because fast-mcp depends on dry-schema. The
+  core supports 3.0.
+- CI runs SQLite only; MySQL and PostgreSQL rest on ActiveRecord's portability.
+
+### Notes
+
+- Ruby 3.0+, Rails 7.0+, zero runtime dependencies.
+- Publishing requires MFA on the owner's account (`rubygems_mfa_required`).
+
 ## [0.0.1] - 2026-08-11
 
 - Placeholder release reserving the gem name. No functionality.
+
+## Versioning policy
+
+Semantic versioning, with one project-specific rule that follows from what this library
+is for:
+
+- **A change that narrows what a tool returns is a security fix and may ship in a patch.**
+  If reeve was letting a record through that a policy did not permit, closing that is not
+  a breaking change, however much it changes behaviour for someone relying on it.
+- **A change that widens access is breaking by definition** — major version, plus a
+  migration note saying exactly what became visible that was not visible before.
+- Adding a nullable ledger column is minor and leaves the audit-entry contract version
+  alone. Removing or renaming a column, or changing what a value means, is major and bumps
+  it.
+- The audit-entry contract version is `1`.

data/README.md

@@ -7,8 +7,9 @@ A Ruby gem that makes it safe for a Rails application to expose MCP tools to AI
 declarative per-record authorization, an append-only audit ledger, and a testing kit that
 proves both hold.
 
-> **Status: 0.0.1 is a placeholder release reserving the gem name. There is no working
-> code yet.** Development is in progress — don't install this expecting it to do anything.
+> **Status: 0.1.0, the first working release.** Read the known limitations in
+> [CHANGELOG.md](CHANGELOG.md) before adopting it — particularly the one about a
+> transaction wrapped around an invocation, if your application wraps requests in one.
 
 *A reeve is an official who acts with delegated authority on behalf of someone else — the
 root of "sheriff" (shire-reeve). That delegation is exactly what this gem governs: an agent
@@ -27,11 +28,38 @@ in CI.
 
 That's the gap Reeve fills. It's an extension layer, not a competitor — it rides all three.
 
-## The shape of it
+## Three steps
+
+```bash
+bundle add reeve
+bin/rails generate reeve:install
+bin/rails db:migrate
+```
+
+**1. Say who the agent is acting for.** This is the only thing Reeve cannot work out for
+itself, and the generated initializer leaves it as a TODO:
+
+```ruby
+# config/initializers/reeve.rb
+Reeve.configure do |config|
+  config.principal_resolver = lambda do |context|
+    ApiToken.find_by(token: context.metadata.dig(:headers, "Authorization"))&.user
+  end
+
+  config.unguarded_tools  = :deny        # :deny | :allow_with_warning
+  config.redact_arguments = %i[password token ssn]
+end
+```
+
+Until that resolver is set, every guarded call denies with `no_principal`. That is the
+intended behaviour: the library is safe before it is configured.
+
+**2. Guard a tool.**
 
 ```ruby
 class InvoiceSearchTool < FastMcp::Tool
   guard_with InvoicePolicy          # the only line you add
+  redact :customer_ssn
 
   def call(query:)
     Invoice.where("number LIKE ?", "%#{query}%")
@@ -39,24 +67,170 @@ class InvoiceSearchTool < FastMcp::Tool
 end
 ```
 
-Three things then hold:
+**3. Prove it in CI.**
+
+```ruby
+RSpec.describe InvoiceSearchTool do
+  it { is_expected.to deny_access_for(stranger).with(query: "AC") }
+  it { is_expected.to audit_every_call }
+end
+```
+
+Three things now hold, and each is a test you can run rather than a claim you have to
+trust.
+
+## Deny by default
+
+A tool returns only the records its principal may see. No principal, no `guard_with`, or a
+policy that raises means no records — never a silent pass. A single record outside the
+principal's scope is refused in a way that does not reveal whether it exists:
+
+```ruby
+Reeve.invoke(tool: InvoiceShowTool, arguments: { id: 41 }, principal: alice)
+# => Reeve::DeniedError: reeve denied invoice_show_tool for principal 1:
+#    out_of_scope_record (the requested record is not within this principal's scope)
+```
+
+The error names the rule and never names the record. One caveat worth knowing: fetching
+from the unscoped model still lets a caller tell "someone else's" (a denial) from "no such
+record" (`nil`). If that distinction matters, fetch through `scoped`, where both answers
+are `nil`:
+
+```ruby
+def call(id:)
+  scoped(Invoice).find_by(id: id)
+end
+```
+
+Anything that is not a record — a count, a sum, a summary — is safe only when it was
+computed from `scoped`, because then the tool never held unscoped data:
+
+```ruby
+class OverdueTotalTool
+  include Reeve::Guard
+  guard_with InvoicePolicy
+
+  def call
+    scoped(Invoice).where(overdue: true).sum(:cents)   # safe by construction
+  end
+end
+```
+
+Reaching for `Invoice.sum(:cents)` there is denied with `unscoped_derived_result`. The
+guarantee is structural, not a matter of remembering.
+
+## Every call leaves a trace
+
+One append-only row per invocation, allowed or denied, naming the agent, the principal, the
+arguments (post-redaction), what came back, and the rule that decided:
+
+```ruby
+Reeve::Audit::Query
+  .for_principal(user)
+  .for_agent("claude-desktop")
+  .between(1.week.ago, Time.current)
+  .pluck(:occurred_at, :tool_name, :outcome, :rule, :record_type, :record_ids)
+```
+
+A call whose tool raised is still recorded — that trace is the one most worth having. A
+call that cannot be recorded fails, unless the host has explicitly opted into
+`audit_failure_mode = :warn`.
+
+## Provable in CI, in whichever framework you already use
+
+All the logic lives in framework-neutral checks. RSpec and Minitest are thin front-ends
+over the same objects, emitting the same messages, so no guarantee is provable in one
+framework only.
+
+```ruby
+# RSpec — require "reeve/rspec"
+it { is_expected.to deny_access_for(stranger) }
+it_behaves_like "a reeve-compliant server"
+```
+
+```ruby
+# Minitest — require "reeve/minitest"
+class ComplianceTest < ActiveSupport::TestCase
+  include Reeve::Testing::Assertions
+  include Reeve::Testing::ComplianceAssertions
+
+  def test_search_denies_a_stranger
+    assert_denies_access_for InvoiceSearchTool, stranger, query: "AC"
+  end
+end
+```
+
+A stock `rails new` application — Minitest, no RSpec — proves every guarantee without
+adding a test framework. That is a spec in this repo, not an aspiration.
+
+### Without a test framework at all
+
+The checks are plain objects, so the same guarantees are assertable from a rake task, a CI
+script, or a boot-time assertion in staging:
+
+<!-- reeve:compliance-gate -->
+```ruby
+require "reeve/testing"
+
+report = Reeve::Checks.run_all(principals: [alice, bob])
+abort report.to_s unless report.passed?
+```
+
+`alice` and `bob` are two fixture principals with disjoint records — that disjointness is
+what makes a shared record identifier proof of a leak. As a Rails rake task:
+
+```ruby
+# lib/tasks/reeve.rake
+namespace :reeve do
+  desc "Fail the build if any guarded tool leaks or goes unaudited"
+  task compliance: :environment do
+    require "reeve/testing"
+
+    report = Reeve::Checks.run_all(principals: Reeve::Testing.compliance_principals)
+    abort report.to_s unless report.passed?
+    puts report
+  end
+end
+```
+
+A failing run names the check, the tool, and the records that leaked:
+
+```text
+reeve compliance: 13 checks, 12 passed, 1 failed
+
+FAIL CrossPrincipalLeak
+  expected InvoiceSearchTool to return no records belonging to another principal, but it
+  returned 3 records to User#1 that also belong to User#2: Invoice#7, Invoice#8,
+  Invoice#9 (guard: InvoicePolicy, decision: allow via InvoicePolicy#index)
+```
+
+## Without Rails, or without fast-mcp
+
+The core needs neither. `Reeve.invoke` is the same envelope with the same guarantees:
+
+```ruby
+require "reeve"
+
+Reeve.invoke(
+  tool: InvoiceSearchTool,
+  arguments: { query: "AC" },
+  principal: current_user,
+  agent: { id: "claude-desktop" }
+)
+```
 
-1. **Deny by default.** The tool returns only invoices the acting principal may see. No
-   principal, no guard, or a policy error means no records — never a silent pass.
-2. **Every call leaves a trace.** One append-only ledger row per invocation, allowed or
-   denied, naming the agent, the principal, the arguments, what came back, and the rule
-   that decided.
-3. **Provable in CI.** `expect(tool).to deny_access_for(stranger)` in RSpec,
-   `assert_denies_access_for` in Minitest, or the checks called directly from a rake task.
+Policies are plain objects unless you want Pundit (`authorize` and `scope`, two methods).
+The ledger is an ActiveRecord table unless you supply your own recorder. Records are
+ActiveRecord unless they are not — a plain object with an `id` works.
 
-## Planned for v1
+## What you have not gained
 
-- Per-record authorization bridging Pundit or plain policy objects
-- Append-only audit ledger with a query interface and an install generator
-- Testing kit: framework-neutral checks with RSpec, Minitest, and plain-Ruby front-ends
-- fast-mcp adapter, plus a plain interface for everyone else
+Rate limiting, prompt-injection defence, cost control, and connection authentication are
+out of scope. This library governs *what an authenticated agent may touch* and *what it
+touched*. Keep your existing auth.
 
-Ruby 3.0+, Rails 7.0+. No runtime dependencies.
+Ruby 3.0+, Rails 7.0+. No runtime dependencies. The fast-mcp adapter needs Ruby 3.1+,
+because fast-mcp does.
 
 ## License
 

data/lib/generators/reeve/install/install_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Reeve
+  module Generators
+    # `bin/rails generate reeve:install` — step two of the three-step adoption path
+    # (Constitution VI). Writes an initializer and the ledger migration, and nothing else.
+    #
+    # The initializer deliberately ships with `principal_resolver` unset: it is the one
+    # thing only the host can answer, and a plausible-looking guess would be worse than a
+    # TODO, because the library fails closed until it is filled in.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the reeve initializer and the audit ledger migration."
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/reeve.rb"
+      end
+
+      def create_migration_file
+        migration_template(
+          "create_audit_entries.rb.tt",
+          "db/migrate/create_reeve_audit_entries.rb"
+        )
+      end
+
+      def report_next_step
+        say <<~NEXT
+
+          reeve is installed. Two things left:
+
+            1. Fill in `principal_resolver` in config/initializers/reeve.rb.
+               Until you do, every guarded call denies with `no_principal`.
+            2. Run `bin/rails db:migrate` to create the audit ledger.
+
+          Then add `guard_with SomePolicy` to a tool.
+        NEXT
+      end
+    end
+  end
+end

data/lib/generators/reeve/install/templates/create_audit_entries.rb.tt

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# The reeve audit ledger: one row per guarded tool invocation, allowed or denied.
+#
+# The table is yours. Reeve writes to it and reads from it, and exposes no API that
+# updates or deletes a row (FR-010). What the library can enforce, it enforces:
+# Reeve::Audit::Entry is readonly once persisted and aborts destroy. What it cannot
+# enforce, it does not pretend to — a database superuser or a raw `UPDATE` can still
+# rewrite history. If the ledger is a compliance artifact for you, close that gap in the
+# database, not in Ruby:
+#
+#   -- PostgreSQL, for the role your application connects as
+#   REVOKE ALL   ON reeve_audit_entries FROM app_role;
+#   GRANT INSERT, SELECT ON reeve_audit_entries TO app_role;
+#   GRANT USAGE  ON SEQUENCE reeve_audit_entries_id_seq TO app_role;
+#
+# Also explicitly out of scope for v1, so you can plan around it:
+#   * no retention, rotation or archival — this table grows until you prune it, and
+#     pruning is your policy, run by a role that is allowed to delete;
+#   * no cryptographic chaining or tamper-evidence. If that lands later it arrives as a
+#     nullable column, which the audit-entry contract's versioning already permits.
+#
+# `invocation_id` is a UUID stored as a string rather than a native `uuid` column,
+# because reeve supports every database ActiveRecord does and only PostgreSQL has the
+# native type. The unique index on it is what makes "exactly one row per invocation"
+# a checkable property.
+class CreateReeveAuditEntries < ActiveRecord::Migration[7.0]
+  def change
+    create_table :reeve_audit_entries do |t|
+      t.string   :invocation_id,  null: false
+      t.datetime :occurred_at,    null: false
+
+      t.string   :agent_id,       null: false
+      t.string   :agent_name
+      t.string   :principal_type
+      t.string   :principal_id
+
+      t.string   :tool_name,      null: false
+      t.json     :arguments,      null: false
+
+      t.string   :outcome,        null: false
+      t.string   :rule,           null: false
+      # Diagnostic text explaining the rule ("policy raised ArgumentError: boom").
+      # Nullable and free-form: match on `rule`, read `detail`. Never names a record.
+      t.text     :detail
+
+      t.string   :record_type
+      t.json     :record_ids,     null: false
+      t.integer  :record_count,   null: false, default: 0
+      t.boolean  :truncated,      null: false, default: false
+      t.boolean  :derived,        null: false, default: false
+
+      t.string   :guard,          null: false
+      t.integer  :duration_ms
+      t.json     :metadata
+    end
+
+    add_index :reeve_audit_entries, :invocation_id, unique: true
+
+    # One index per query axis in FR-013: by principal, by tool, by agent, by outcome —
+    # each paired with occurred_at, since every one of those questions is asked over a
+    # time range.
+    add_index :reeve_audit_entries, %i[principal_type principal_id occurred_at],
+              name: "index_reeve_audit_entries_on_principal"
+    add_index :reeve_audit_entries, %i[tool_name occurred_at]
+    add_index :reeve_audit_entries, %i[agent_id occurred_at]
+    add_index :reeve_audit_entries, %i[outcome occurred_at]
+  end
+end

data/lib/generators/reeve/install/templates/initializer.rb.tt

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# reeve — per-record authorization and an append-only audit ledger for the MCP tools
+# this application exposes to AI agents.
+#
+# Everything below is a live setting; the only one you must fill in is the first.
+
+Reeve.configure do |config|
+  # ---------------------------------------------------------------------------
+  # REQUIRED. Who is the agent acting for?
+  #
+  # Receives a Reeve::Context and returns the principal — the human whose
+  # permissions govern this call — or nil to deny it. Raising is treated as nil:
+  # reeve fails closed rather than guessing.
+  #
+  # Where the identity comes from is yours to decide. With the fast-mcp adapter
+  # the request's headers arrive as context.metadata[:headers]:
+  #
+  #   config.principal_resolver = lambda do |context|
+  #     token = context.metadata.dig(:headers, "Authorization")
+  #     ApiToken.find_by(token: token)&.user
+  #   end
+  #
+  # TODO: replace this with your own lookup. Until you do, every guarded call
+  # denies with the rule `no_principal` — which is the intended behaviour, not a
+  # bug: the library is safe before it is configured.
+  config.principal_resolver = ->(context) { nil }
+
+  # ---------------------------------------------------------------------------
+  # What happens to a tool with no `guard_with` declaration?
+  #
+  #   :deny                — the call returns nothing and is recorded as denied.
+  #   :allow_with_warning  — the call runs UNSCOPED, is logged, and is recorded
+  #                          with guard: "none". For retrofitting an existing
+  #                          server; every such call is a hole until it is
+  #                          declared.
+  #
+  # Written out rather than defaulted, because it is a decision you should make
+  # knowingly.
+  config.unguarded_tools = :deny
+
+  # ---------------------------------------------------------------------------
+  # Argument names whose values never reach the ledger. Names survive, values do
+  # not, recursively through nested hashes. Add per-tool names with `redact` in
+  # the tool itself.
+  config.redact_arguments = %i[password token secret ssn]
+
+  # What happens if the ledger write fails?
+  #
+  #   :fail  — the invocation fails. A call that cannot be recorded is a call
+  #            that did not happen.
+  #   :warn  — log it and continue. Opt in knowingly: it trades the audit
+  #            guarantee for availability.
+  config.audit_failure_mode = :fail
+
+  # Cap on how many record identifiers one entry stores. The true count is
+  # always recorded, and the entry says when the list was truncated.
+  config.max_recorded_ids = 1000
+
+  # Where warnings go (unguarded tools, degraded audit mode).
+  config.logger = Rails.logger
+end
+
+# The ledger itself is opt-in, so the core stays loadable without ActiveRecord.
+require "reeve/audit"

data/lib/reeve/audit/entry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # One ledger row: which agent, acting for which principal, called which tool with
+    # which arguments, what came back, and which rule decided (FR-009).
+    #
+    # Append-only (FR-010). The model enforces that as far as a library can: a persisted
+    # row is readonly, so `update` and `save` raise, and `destroy` aborts. It cannot
+    # enforce it against raw SQL and does not pretend to — the generated migration
+    # documents the INSERT+SELECT grant that closes the rest of the gap.
+    class Entry < ActiveRecord::Base
+      self.table_name = TABLE_NAME
+
+      ALLOW = "allow"
+      DENY  = "deny"
+      OUTCOMES = [ALLOW, DENY].freeze
+
+      REQUIRED = %i[invocation_id occurred_at agent_id tool_name outcome rule guard].freeze
+
+      validates(*REQUIRED, presence: true)
+      validates :invocation_id, uniqueness: true
+      validates :outcome, inclusion: { in: OUTCOMES, message: "must be allow or deny" }
+
+      before_destroy { throw :abort }
+
+      # The contract version this table's shape implements (FR-015). Exposed on the model
+      # so an export can stamp the rows it carries.
+      def self.contract_version
+        CONTRACT_VERSION
+      end
+
+      # False while the row is being inserted, true forever after: the insert is the only
+      # write the ledger ever performs.
+      def readonly?
+        persisted?
+      end
+
+      def allowed?
+        outcome == ALLOW
+      end
+
+      def denied?
+        outcome == DENY
+      end
+    end
+  end
+end

data/lib/reeve/audit/query.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The documented way to read the ledger (FR-013): one scope per query axis —
+    # principal, agent, tool, outcome, time range — each backed by one of the composite
+    # indexes the generated migration creates.
+    #
+    #   Q = Reeve::Audit::Query
+    #   Q.for_principal(user)
+    #     .for_agent("claude-desktop")
+    #     .between(1.week.ago, Time.current)
+    #     .pluck(:tool_name, :record_type, :record_ids, :outcome, :rule)
+    #
+    # The scopes are also extended onto Entry, so a host that would rather work with the
+    # model directly gets the same chain. There is deliberately no scope that writes.
+    module Query
+      # Defined once and used from two places: on Query, +all+ opens on the whole ledger;
+      # on Entry (and on a relation being chained), +all+ is the current scope, which is
+      # what makes these compose in any order.
+      module Scopes
+        def for_principal(principal)
+          all.where(Query.principal_key(principal))
+        end
+
+        def for_agent(agent_id)
+          all.where(agent_id: agent_id.to_s)
+        end
+
+        def for_tool(tool_name)
+          all.where(tool_name: tool_name.to_s)
+        end
+
+        def allowed
+          all.where(outcome: Entry::ALLOW)
+        end
+
+        def denied
+          all.where(outcome: Entry::DENY)
+        end
+
+        # By occurred_at: the ledger is ordered by when the call happened, not by when the
+        # row landed.
+        def between(from, to)
+          all.where(occurred_at: from..to)
+        end
+      end
+
+      extend Scopes
+
+      class << self
+        def all
+          Entry.all
+        end
+
+        # How a principal becomes a pair of columns. Mirrors Reeve::Context#principal_type
+        # and #principal_id exactly — a query that derived the key differently would
+        # quietly fail to find the rows the envelope wrote.
+        #
+        # Accepts the principal itself, or `type:`/`id:` for when an incident report is
+        # all that survives of them.
+        def principal_key(principal)
+          return explicit_key(principal) if principal.is_a?(Hash)
+
+          {
+            principal_type: principal.class.name,
+            principal_id: principal.respond_to?(:id) ? principal.id.to_s : principal.to_s
+          }
+        end
+
+        private
+
+        def explicit_key(attributes)
+          {
+            principal_type: attributes[:type]&.to_s,
+            principal_id: attributes[:id]&.to_s
+          }
+        end
+      end
+    end
+  end
+end
+
+Reeve::Audit::Entry.extend(Reeve::Audit::Query::Scopes)