provenance 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f14ec0ba7dff7626fb82cb169c9f76423f72e0dc059f571f84bbadf07282455c
+  data.tar.gz: 8643b14cb28e42d5c2c62e0365ddfa39e3b0030237bc363b1bcbcc77be4ceb38
+SHA512:
+  metadata.gz: c299ddc878e226b43c8c14ed12e4f258d4882ce4bc0b65ccac5e235263fa068d9480d7185f9a03c31433f0fd3115a7c4d0cdab61cd5ece58c43e0ca9c866e318
+  data.tar.gz: 9b7bb4fa07e2d5c07ebedbbcd608894270c332a6b7837bc4fd0a5c8371500d0ee902ca4a408159ee95cae7edea0ce4020fcfa122c1c584c90569fd2925d3d564

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 2.0.0
+
+- One action-level event per HTTP request, ActiveJob job, rake task or explicit
+  `Provenance.action` block, with actor, request context, outcome and entity changes.
+- Opt-in model tracking with `has_provenance` (`only`, `except`, `redact`,
+  `associations`, `ignore_if`), link/unlink changes and bulk `update_all`,
+  `delete_all`, `insert_all`/`upsert_all` changes.
+- Emission after all touched transactions commit; rolled-back changes are dropped.
+- Native event format with a shipped JSON Schema (`schema/event-2.json`), plus OCSF
+  1.x and CloudEvents 1.0 serializers.
+- Sinks: logger, IO, HTTP (retries with backoff and jitter), proc, memory and
+  optional Kafka.
+- Outbox table with `Provenance::RelayJob`, `FOR UPDATE SKIP LOCKED` on PostgreSQL,
+  retries and retention pruning; `rails g provenance:install`.
+- HMAC-SHA256 integrity chain with `Provenance::Integrity.verify` and
+  `rake provenance:verify`.
+- RSpec support: `Provenance::Testing.capture` and the `emit_provenance_event` matcher.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Nikolaev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,358 @@
+# Provenance
+
+Provenance answers **who did what, through which entry point, with what outcome, and
+which records changed**. It emits one *action-level* event per HTTP request,
+background job, rake task or explicit block, and delivers it reliably to security and
+observability tooling: SIEM, log pipelines, webhooks, Kafka.
+
+Provenance is **not** a versioning or undo library. [paper_trail], [audited] and
+[logidze] keep per-record history inside your application database so you can show or
+restore previous versions. Provenance emits tamper-evident, standards-shaped events
+*out of* the application, one per user intent, with the record changes attached.
+
+Requirements: Ruby >= 3.2, Rails >= 7.2. MIT license.
+
+## Quick start
+
+```ruby
+# Gemfile
+gem "provenance", "~> 2.0"
+```
+
+```sh
+bin/rails g provenance:install   # outbox migration + config/initializers/provenance.rb
+bin/rails db:migrate
+```
+
+```ruby
+# config/initializers/provenance.rb
+Provenance.configure do |c|
+  c.enabled = !Rails.env.test?
+  c.actor { |ctx| ctx.controller.try(:current_user) }
+  c.sink :logger
+end
+
+# app/models/invoice.rb
+class Invoice < ApplicationRecord
+  has_provenance only: %i[status amount], redact: %i[notes], associations: %i[tags]
+end
+```
+
+A `PATCH /invoices/7` that changes the status now emits:
+
+```json
+{
+  "schema": "provenance/event@2",
+  "id": "0192f5c6-7b1e-7cc2-9a51-0d4f6a8e2b10",
+  "occurred_at": "2026-10-05T12:00:00.123Z",
+  "app": "billing",
+  "action": { "kind": "http", "name": "invoices#update", "caused_by": null },
+  "actor": { "id": "42", "type": "User", "display": "a@b.c", "roles": ["admin"], "impersonator": null },
+  "request": { "id": "3f1c…", "method": "PATCH", "path": "/invoices/7", "status": 200, "ip": "10.0.0.1", "user_agent": "…" },
+  "outcome": { "result": "success", "error": null },
+  "changes": [
+    { "entity": "Invoice", "entity_id": "7", "operation": "update", "diff": { "status": ["draft", "sent"] } }
+  ],
+  "metadata": {}
+}
+```
+
+The JSON Schema ships in [`schema/event-2.json`](schema/event-2.json).
+
+## Concepts
+
+- **Action** — a unit of user intent with a kind (`http`, `job`, `task`, `custom`),
+  a name, an actor, request context, an outcome and the entity changes made while it
+  was open. At most one event is emitted per action.
+- **Actor** — `id`, `type`, `display`, `roles` and an optional `impersonator` of the
+  same shape for "login as".
+- **Entity change** — `entity`, `entity_id`, `operation` (`create`, `update`,
+  `destroy`, `link`, `unlink`, `bulk_update`, `bulk_delete`, `bulk_insert`) and `diff`
+  (`{attr => [before, after]}` for updates, `{attr => after}` for creates,
+  `{attr => before}` for destroys).
+
+### What gets captured
+
+| Entry point | How | Action name |
+|---|---|---|
+| HTTP | Rack middleware inserted after `ActionDispatch::RequestId` | `"#{controller_path}##{action_name}"` |
+| ActiveJob | `around_perform` | job class name |
+| Rake | `Provenance::Rake.install!` (opt-in, e.g. in `Rakefile`) | task name |
+| Explicit | `Provenance.action("users.import") { ... }` | given name |
+| Model change outside any action | implicit `custom` action | `"Invoice.update"` |
+
+An action is emitted when it closes **and** every transaction it touched has
+committed. It is emitted if it has changes, has a non-success outcome, is a non-read
+HTTP request (anything but GET/HEAD), was opened explicitly, or `audit_reads` is on.
+
+Outcomes: `success`; `failure` for an unhandled exception (`error.class` and
+`error.message`, truncated to 500 characters) or a 5xx response; `denied` for an
+exception listed in `denied_exceptions` or a 401/403 response. Exceptions are always
+re-raised.
+
+Jobs enqueued inside an action carry the action id and actor in the job payload under
+the `provenance` key, so the job event has `action.caused_by` set to the parent id.
+
+## API
+
+```ruby
+Provenance.action("users.import", actor: admin, metadata: { file: "x.csv" }) do
+  # nested Provenance.action blocks attach to the outermost action
+end
+
+Provenance.current&.annotate(reason: "GDPR request #42")
+Provenance.current&.actor = some_user
+
+Provenance.without { Invoice.update_all(viewed: true) }   # suppress tracking
+
+class Admin::ReportsController < ApplicationController
+  provenance_action_name ->(controller) { "admin.reports.#{controller.action_name}" }
+  skip_provenance only: :preview
+end
+
+class CleanupJob < ApplicationJob
+  skip_provenance
+end
+```
+
+### Models
+
+```ruby
+class Invoice < ApplicationRecord
+  has_many :tags
+  has_provenance only: %i[status amount],        # or except: [...]
+    redact: %i[notes],                            # recorded as "[REDACTED]"
+    associations: %i[tags],                       # link/unlink changes
+    ignore_if: ->(invoice) { invoice.draft? }
+end
+```
+
+`has_provenance` must come after the association declarations it references. Changes
+are held per transaction and dropped if it rolls back. Bulk operations on tracked
+models — `update_all`, `delete_all`, `insert_all`, `upsert_all` (and the methods built
+on them) — produce one `bulk_*` change with `count`, a `where` fingerprint (SHA-256 of
+the WHERE clause with bind values replaced by placeholders) and up to `bulk_ids_limit`
+affected `ids` (`truncated: true` when cut). Ids come from a single `pluck` before the
+write, or from the records when the relation is already loaded. `created_at` and
+`updated_at` are ignored by default (`c.ignored_attributes`), as are primary keys.
+
+### Actor resolution
+
+`c.actor { |ctx| ... }` receives a context with `#controller`, `#job`, `#request` and
+`#env` and returns a user-like object, a Hash or a `Provenance::Actor`. Objects are
+read through `provenance_actor` (returning a Hash) if defined, otherwise `id`,
+`provenance_display`/`email`/`name` and `provenance_roles`. Resolver errors are
+reported to `on_error`; the event is emitted without an actor.
+
+## Configuration
+
+```ruby
+Provenance.configure do |c|
+  c.app_name = "billing"                       # default: Rails app module name, underscored
+  c.enabled = !Rails.env.test?                 # default: true
+  c.actor { |ctx| ctx.controller.try(:current_user) }
+  c.redact_attributes += %i[iban]              # merged with Rails filter_parameters
+  c.ignored_attributes = %w[created_at updated_at]
+  c.format = :native                           # :native | :ocsf | :cloudevents
+  c.sink :logger                               # repeatable
+  c.sink :http, url: ENV["AUDIT_URL"], headers: { "Authorization" => "Bearer …" }
+  c.outbox = true
+  c.outbox_retention = 7.days
+  c.outbox_batch_size = 100
+  c.outbox_enqueue_relay = true                # enqueue RelayJob after each write
+  c.integrity.key = ENV["PROVENANCE_HMAC_KEY"]  # nil disables
+  c.audit_reads = false                        # GET/HEAD actions without changes are skipped
+  c.denied_exceptions = ["CanCan::AccessDenied", "Pundit::NotAuthorizedError"]
+  c.bulk_ids_limit = 500
+  c.on_error { |exception, event| Rails.error.report(exception) }  # default: Rails.logger.error
+end
+```
+
+Redaction uses `ActiveSupport::ParameterFilter`, so `filter_parameters` entries such
+as `:passw` match partially. Redacted values become `"[REDACTED]"`; a `nil` side of an
+update stays `nil`. Encrypted attributes are always redacted. Event metadata is
+filtered the same way. Diff values are JSON-safe: times become ISO 8601, `BigDecimal`
+a string, binary strings `"[BINARY n bytes]"`.
+
+## Delivery
+
+### Sinks
+
+A sink is any object with `#deliver(batch)`, where `batch` is an Array of serialized
+events (Hashes). A failing sink never breaks the request: errors go to `on_error`
+and the other sinks still receive the batch.
+
+| Sink | Options |
+|---|---|
+| `:logger` | `logger:` (default `Rails.logger`), `level:` (default `:info`); one JSON line per event |
+| `:io` | any IO, e.g. `c.sink :io, $stdout`; one JSON line per event |
+| `:http` | `url:`, `headers:`, `open_timeout:`, `read_timeout:`, `retries:`, `backoff:`, `max_backoff:`; POSTs a JSON array, 2xx is success, exponential backoff with jitter |
+| `:proc` | a callable or block: `c.sink(:proc) { |batch| ... }` |
+| `:memory` | keeps events in memory, for tests |
+| `:kafka` | `require "provenance/sinks/kafka"` (needs `rdkafka`); `topic:`, `config:` or `producer:`; one message per event keyed by event id |
+| custom | `c.sink MySink.new` |
+
+### Outbox
+
+Inline delivery runs in the request thread after commit. For reliable delivery set
+`c.outbox = true`: events are written to the `provenance_outbox` table and
+`Provenance::RelayJob` delivers them.
+
+The relay drains pending rows in id order (`FOR UPDATE SKIP LOCKED` on PostgreSQL,
+plain ordering elsewhere), delivers each batch to every sink, marks rows delivered and
+retries failed batches with exponential backoff (capped at one hour), stopping at the
+first row that is not due so delivery order is kept. Delivered rows older than
+`outbox_retention` are pruned; the newest row per app is kept as the anchor of the
+integrity chain. Delivery is at-least-once: a batch that fails on one sink is retried
+on all of them.
+
+`RelayJob` is enqueued after each write by default. You can also schedule it (for
+example with Solid Queue recurring tasks) and turn `outbox_enqueue_relay` off, or run
+`bin/rails provenance:relay`.
+
+## Formats
+
+The format applies at delivery time; the outbox always stores native events.
+
+### Native
+
+`provenance/event@2`, described above and in `schema/event-2.json`.
+
+### CloudEvents
+
+CloudEvents 1.0 structured JSON:
+
+| CloudEvents | Value |
+|---|---|
+| `specversion` | `"1.0"` |
+| `id` | event `id` |
+| `source` | `app` |
+| `type` | `"provenance.action.<kind>"` |
+| `subject` | action name |
+| `time` | `occurred_at` |
+| `datacontenttype` | `"application/json"` |
+| `dataschema` | `"urn:provenance:event:2"` |
+| `data` | the native event |
+
+### OCSF
+
+OCSF 1.3: every action becomes one **API Activity** event (`class_uid` 6003,
+`category_uid` 6) and every entity change one **Entity Management** event
+(`class_uid` 3004, `category_uid` 3), so a single native event may produce several
+OCSF events. All of them share `metadata.correlation_uid` = native event id.
+
+Common fields:
+
+| OCSF | Source |
+|---|---|
+| `time` | `occurred_at` as epoch milliseconds |
+| `metadata.version` | `"1.3.0"` |
+| `metadata.uid` | event id (API Activity), `"<event id>/<change index>"` (Entity Management) |
+| `metadata.correlation_uid` | event id |
+| `metadata.log_name` | `app` |
+| `metadata.product` | `{name: "Provenance", vendor_name: "Provenance", version}` |
+| `actor.app_name` | `app` |
+| `actor.user.uid` / `.name` / `.type` | `actor.id` / `actor.display` / `actor.type` |
+| `actor.user.groups[].name` | `actor.roles` |
+| `status_id` / `status` | `success` → 1 Success; `failure`, `denied` → 2 Failure |
+| `status_detail` | `outcome.result` |
+| `severity_id` | `success` 1 Informational, `failure` 2 Low, `denied` 3 Medium |
+| `type_uid` | `class_uid * 100 + activity_id` |
+| `unmapped.action` | native `action` |
+| `unmapped.metadata` | native `metadata` |
+| `unmapped.impersonator` | `actor.impersonator` |
+| `unmapped.integrity` | native `integrity` |
+
+API Activity (6003):
+
+| OCSF | Source |
+|---|---|
+| `activity_id` | POST 1 Create, GET/HEAD 2 Read, PUT/PATCH 3 Update, DELETE 4 Delete; non-HTTP actions use the change operations when they agree, else 99 Other |
+| `api.operation` | action name |
+| `api.request.uid` | request id (event id for non-HTTP actions) |
+| `api.response.code` | HTTP status |
+| `api.response.error` / `.error_message` | `outcome.error.class` / `.message` |
+| `src_endpoint.ip` | `request.ip` |
+| `http_request.http_method` / `.url.path` / `.user_agent` / `.uid` | `request.method` / `.path` / `.user_agent` / `.id` |
+| `http_response.code` | `request.status` |
+| `resources[]` | `{type: entity, uid: entity_id}` per change |
+
+Entity Management (3004):
+
+| OCSF | Source |
+|---|---|
+| `activity_id` | `create`, `bulk_insert` 1 Create; `update`, `bulk_update` 3 Update; `destroy`, `bulk_delete` 4 Delete; `link`, `unlink` 99 Other (`activity_name` "Link"/"Unlink") |
+| `entity.name`, `entity.type` | `entity` |
+| `entity.uid` | `entity_id` |
+| `entity.data` | `diff` |
+| `unmapped.change` | `operation`, `association`, `target`, `count`, `where`, `ids`, `truncated` |
+
+## Integrity
+
+With `c.integrity.key` set (requires the outbox; configuration raises otherwise), each
+event gets
+
+```json
+"integrity": { "seq": 118, "prev": "<mac of seq 117>", "mac": "<hex>" }
+```
+
+where `seq` increases monotonically per app, and
+`mac = HMAC-SHA256(key, prev + canonical_json(event without "integrity"))`. Canonical
+JSON has sorted object keys and no whitespace; `prev` is `null` for the first event and
+counts as an empty string in the MAC input. Sequence numbers are allocated from the outbox table (an advisory transaction
+lock on PostgreSQL, a unique index plus retry elsewhere).
+
+```ruby
+Provenance::Integrity.verify(events, key: ENV["PROVENANCE_HMAC_KEY"])  # => nil or first broken seq
+```
+
+`bin/rails provenance:verify` checks the chain stored in the outbox and exits non-zero
+on a broken chain. Forward events to an append-only store to keep evidence beyond the
+outbox retention window.
+
+## Testing
+
+```ruby
+# spec/rails_helper.rb
+require "provenance/rspec"
+```
+
+```ruby
+events = Provenance::Testing.capture { post "/invoices", params: { ... } }
+
+expect { patch invoice_path(invoice), params: { invoice: { status: "sent" } } }
+  .to emit_provenance_event(action: "invoices#update", outcome: "success")
+  .with_change(entity: "Invoice", operation: "update", diff: including(status: ["draft", "sent"]))
+
+expect { get invoices_path }.not_to emit_provenance_event
+```
+
+While capturing, tracking is enabled even if `c.enabled` is false, and events go to the
+capture instead of the outbox or sinks. The matcher accepts `action`, `kind`,
+`caused_by`, `outcome`, `error`, `actor`, `actor_id`, `request`, `status`, `metadata`
+and `app`, any RSpec composable matcher as a value, `.with_change(...)` (repeatable)
+and `.exactly(n)` / `.once`.
+
+## Comparison
+
+| | Provenance | paper_trail | audited | logidze |
+|---|---|---|---|---|
+| Unit of record | one event per action (request, job, task, block) | one version per record change | one audit per record change | record history in a JSONB column |
+| Stored in | external sinks (via outbox) | app database | app database | app database (triggers) |
+| Undo / reify | no | yes | yes (revisions) | yes |
+| Request context and outcome (failure/denied) | yes | via whodunnit/metadata | via request uuid/comment | via meta |
+| Bulk operations | summarized per call | no | no | yes (triggers) |
+| Tamper evidence | HMAC chain | no | no | no |
+| Wire formats | native, OCSF, CloudEvents | — | — | — |
+
+Use paper_trail, audited or logidze when the application itself needs record history.
+Use Provenance when security or compliance tooling needs to know who did what. They
+can be combined.
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+[paper_trail]: https://github.com/paper-trail-gem/paper_trail
+[audited]: https://github.com/collectiveidea/audited
+[logidze]: https://github.com/palkan/logidze

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Provenance
+  # Rails generators shipped with Provenance.
+  module Generators
+    # +rails g provenance:install+: creates the outbox migration and an initializer.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the provenance_outbox migration and config/initializers/provenance.rb"
+
+      # @return [void]
+      def create_migration_file
+        migration_template "create_provenance_outbox.rb.tt", "db/migrate/create_provenance_outbox.rb"
+      end
+
+      # @return [void]
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/provenance.rb"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/provenance/install/templates/create_provenance_outbox.rb.tt

@@ -0,0 +1,21 @@
+class CreateProvenanceOutbox < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :provenance_outbox do |t|
+      t.string :app, null: false
+      t.string :event_id, null: false
+      t.bigint :seq
+      t.string :mac
+      t.text :payload, null: false
+      t.string :status, null: false, default: "pending"
+      t.integer :attempts, null: false, default: 0
+      t.datetime :next_attempt_at
+      t.datetime :delivered_at
+      t.text :last_error
+      t.timestamps
+    end
+
+    add_index :provenance_outbox, [:status, :id]
+    add_index :provenance_outbox, [:app, :seq], unique: true
+    add_index :provenance_outbox, :delivered_at
+  end
+end

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

@@ -0,0 +1,12 @@
+Provenance.configure do |c|
+  c.enabled = !Rails.env.test?
+  c.actor { |ctx| ctx.controller.try(:current_user) }
+  c.format = :native
+  c.sink :logger
+
+  # Reliable delivery through the provenance_outbox table (run the generated migration).
+  c.outbox = true
+
+  # Tamper evidence; requires the outbox.
+  # c.integrity.key = ENV["PROVENANCE_HMAC_KEY"]
+end

data/lib/provenance/action.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Provenance
+  # A unit of user intent: one HTTP request, job, rake task or explicit block.
+  class Action
+    # Accepted kinds.
+    KINDS = %w[http job task custom].freeze
+    # HTTP methods treated as reads.
+    READ_METHODS = %w[GET HEAD].freeze
+    # Maximum length of a recorded exception message.
+    MESSAGE_LIMIT = 500
+
+    # @return [String] UUIDv7
+    attr_reader :id
+    # @return [String]
+    attr_reader :kind
+    # @return [String, nil]
+    attr_accessor :name
+    # @return [String, nil] id of the action that caused this one
+    attr_accessor :caused_by
+    # @return [Context]
+    attr_reader :context
+    # @return [Hash] request attributes for HTTP actions
+    attr_reader :request
+    # @return [Hash{String => Object}]
+    attr_reader :metadata
+    # @return [Array<EntityChange>]
+    attr_reader :changes
+    # @return [Time]
+    attr_reader :started_at
+    # @return [Exception, nil]
+    attr_reader :exception
+    # @return [Actor, nil] actor set explicitly, without running the resolver
+    attr_reader :explicit_actor
+
+    # @param kind [Symbol, String]
+    # @param name [String, nil]
+    # @param actor [Object, nil]
+    # @param metadata [Hash]
+    # @param explicit [Boolean] explicit actions are always auditable
+    # @param caused_by [String, nil]
+    # @param context [Context, nil]
+    def initialize(kind:, name:, actor: nil, metadata: {}, explicit: false, caused_by: nil, context: nil)
+      @kind = kind.to_s
+      raise ArgumentError, "unknown action kind #{kind.inspect}" unless KINDS.include?(@kind)
+
+      @started_at = Time.now.utc
+      @id = UUID.v7(@started_at)
+      @name = name
+      @explicit_actor = Actor.wrap(actor)
+      @metadata = {}
+      annotate(**metadata)
+      @explicit = explicit
+      @caused_by = caused_by
+      @context = context || Context.new
+      @request = {}
+      @changes = []
+      @lock = Mutex.new
+      @skipped = false
+    end
+
+    # Merges data into the action metadata.
+    #
+    # @param data [Hash]
+    # @return [self]
+    def annotate(**data)
+      @metadata.merge!(data.deep_stringify_keys)
+      self
+    end
+
+    # @param value [Object, Hash, Actor, nil] anything {Actor.wrap} accepts
+    def actor=(value)
+      @explicit_actor = Actor.wrap(value)
+    end
+
+    # The actor, resolved through the configured resolver when not set explicitly.
+    # Resolver failures are reported to +on_error+ and yield +nil+.
+    #
+    # @return [Actor, nil]
+    def actor
+      return @explicit_actor if @explicit_actor
+
+      resolver = Provenance.config.actor_resolver
+      return nil unless resolver
+
+      resolved = Actor.wrap(resolver.call(context))
+      @explicit_actor = resolved if resolved
+      resolved
+    rescue => e
+      Provenance.config.report_error(e)
+      nil
+    end
+
+    # @param change [EntityChange]
+    # @return [void]
+    def add_change(change)
+      @lock.synchronize { @changes << change }
+    end
+
+    # Records an exception as the outcome. Only the first exception is kept.
+    #
+    # @param exception [Exception]
+    # @return [void]
+    def fail!(exception)
+      @exception ||= exception
+    end
+
+    # Excludes this action from emission.
+    #
+    # @return [void]
+    def skip!
+      @skipped = true
+    end
+
+    # @return [Boolean]
+    def skipped?
+      @skipped
+    end
+
+    # @return [Boolean]
+    def explicit?
+      @explicit
+    end
+
+    # @return [String] "success", "failure" or "denied"
+    def result
+      if exception
+        Provenance.config.denied?(exception) ? "denied" : "failure"
+      else
+        case request["status"].to_i
+        when 401, 403 then "denied"
+        when 500..599 then "failure"
+        else "success"
+        end
+      end
+    end
+
+    # @return [Hash, nil] {"class", "message"} of the recorded exception
+    def error
+      return nil unless exception
+
+      {"class" => exception.class.name, "message" => exception.message.to_s.truncate(MESSAGE_LIMIT)}
+    end
+
+    # @return [Boolean] whether an HTTP action used GET or HEAD
+    def read?
+      kind == "http" && READ_METHODS.include?(request["method"].to_s.upcase)
+    end
+
+    # Whether the action produces an event (section 4.4).
+    #
+    # @return [Boolean]
+    def auditable?
+      return false if skipped?
+
+      changes.any? || result != "success" || (kind == "http" && !read?) ||
+        Provenance.config.audit_reads || explicit?
+    end
+  end
+end