standard_audit 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80719c54fd8a1d3859f52741cfc4a478ec670114ad5ab025b1b9b14a10a80625
-  data.tar.gz: d5baa91d4e29844e0e0c375e0ef6c9b3cd4f2d6eba0284696911891270f3befa
+  metadata.gz: c41a6212ecc33a1cdba995a12cc4c2205cf9bafe5b7eeb6cdd5c83288e1738d7
+  data.tar.gz: 41111fb868232c50a068a8e21ba2597ed4e60f4c15bc3018afc72199ecfc659e
 SHA512:
-  metadata.gz: 3fc6d5267408dd0858b0cecac9e449c00b6ef6e75b12cb9cb74167634769cd09f95fa51805a948f9a20e100b7bbd43237f473f4508d211a8c66293c0af2bbe3f
-  data.tar.gz: cdb5c7130f54d124da4e2b02586e510b5a75693c729d30d495403d4e948b7d6fcc81b640cb241a138292d452ebb5a52f0d84a6a0f178e8ecb982d7a209c179ea
+  metadata.gz: 710317dda7bf0b14fcf77f72365a2edcaaa33d6e77e8177e96bdad8dd86e1ef84bb57427a749c42b50b10e3f8a92aafc3efb2597eb0014fdba1b5639758c6223
+  data.tar.gz: 8e1e70aeed7098a52a413e37f971a0f433d535e36e880618aa6ddf2c000c6a664c2f29fc124653e14849a3389a2badbcdab0450aa9282fa80d077f219a77e082

data/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-24
+
+The Phase 4 release. It removes what 0.12 deprecated, the empty engine
+routing, and the gaps the five app adoptions of 0.12 ran into.
+
+### Removed (breaking)
+
+- **`standard_audit:add_checksums` generator** (deprecated in 0.12.0). It was the 0.2 → 0.3 upgrade path. Every install since 0.3 creates `checksum`; hosts older than 0.8 run `standard_audit:add_previous_checksum`.
+- **`isolate_namespace StandardAudit` and the empty `config/routes.rb`.** The engine has no routes, controllers or views, and no host mounts it. `AuditLog` sets its own `table_name`, so table naming is unchanged. Side effects: `StandardAudit::Engine.routes` no longer holds an (empty) isolated route set, and `StandardAudit.table_name_prefix` / `railtie_namespace` are no longer set by isolation. The gem uses neither.
+
+### Added
+
+- **`config.error_reporter = ->(error, context) { … }`**, the destination for every error the gem swallows: `record(raise: false)`, subscriber writes, raising `before_checksum` hooks, and `audit!` write failures under the default policy. nil (the default) keeps `Rails.error.report(error, handled: true, context:)`, so nothing changes unless you set it. Apps that don't forward `Rails.error` to their tracker (jumpdrive-web, nutripod-web) can report straight to Sentry instead of wrapping calls in their own rescue. A raising reporter is logged and ignored. `audit_write_error_handler` still takes precedence for `audit!`.
+- **`entry[:via]` in `before_write`**: `:direct` (`record` without a block, `record_audit`, `audit!`), `:notification` (the ActiveSupport::Notifications subscriber, including `record` with a block), or `:rails_event`. A hook can now tell a direct write from a subscriber write. Not persisted. `StandardAudit::VIA` lists the values.
+- **`hooks:` option on the `"a standard_audit baseline"` shared example**: an Integer (exact `before_checksum` hook count) or an Array of Symbol hook names. The mutation example clears the hooks before the reset, so it fails when a hook lives outside the baseline block.
+
+### Fixed
+
+- **Upgrade generators number the migration after the host's newest migration.** `add_anonymized_at`, `add_previous_checksum` and `install` stamped `Time.now`, which sorts before future-dated host migrations. They now use the later of now and one second after the newest migration in the target directory (a real timestamp, unlike ActiveRecord's `+1`, which can produce `…235960`).
+- **README `before_write` example.** It showed a PII guard in `before_write` next to a masking `metadata_builder`. `before_write` runs after the builder, so the guard only ever saw masked values. The README now documents the order (resolvers → `metadata_builder` → `before_write` → dereference → redact → persist) and shows guard-then-mask inside `before_write`.
+
+### Upgrade notes (0.12.x → 0.13.0)
+
+Grepped `origin/main` of sidekick-web, jumpdrive-web (control-plane), fundbright-web, luminality-web and nutripod-web on 2026-09-24.
+
+**Required host changes: none.** No app runs `add_checksums`, mounts `StandardAudit::Engine`, or uses its route helpers. Regenerate Sorbet RBIs (`bin/tapioca gem standard_audit`, `bin/tapioca dsl`) where the app uses Tapioca.
+
+**Optional cleanups this release enables:**
+- sidekick-web `spec/initializers/standard_audit_baseline_spec.rb:49-53` ("still carries the two classification hooks after a reset"): replace with `hooks: 2` on the `it_behaves_like` call.
+- jumpdrive-web `control-plane/app/services/mcp/server.rb:98-104` (`audit_tool` rescue → `ErrorReporting.notify`): replace with `StandardAudit.record(..., raise: false)` plus a `config.error_reporter` that calls `ErrorReporting.notify`. Or keep it, since it also adds `component:` context.
+- nutripod-web `app/controllers/concerns/audit_auth_failure.rb:92-96`: the rescue reports through `Rails.error` itself, so it can become `record(..., raise: false)` with `config.audit_error_context_key = :audit_event`, like the other apps. Add a `config.error_reporter` if nutripod-web does not forward `Rails.error` to Sentry.
+- fundbright-web `AuditWritePolicy` (`before_write`) can use `entry[:via]` if its PII guard should skip gem-published subscriber payloads.
+- Any `before_write` that iterates every `entry` key now also sees `:via`.
+
+## [0.12.1] - 2026-09-24
+
+### Upgrade steps
+
+1. **If you installed the 0.12.0 `add_anonymized_at` migration, check your copy.** The 0.12.0 template put `return if column_exists?(:audit_logs, :anonymized_at)` inside `change`. That early return also runs on rollback, so `db:rollback` deleted the `schema_migrations` row and silently left the column in place. Replace the body with `add_column :audit_logs, :anonymized_at, :datetime, if_not_exists: true` (in `change`), or copy the new up/down template. Nothing to do if your copy already uses `if_not_exists:` (sidekick-web, jumpdrive-web) or if you never ran the generator.
+2. If an error-tracker search or alert matches `before_checksum` hook failures on the `audit_event` context key, see Fixed.
+
+### Fixed
+
+- **The `add_anonymized_at` migration is reversible.** The template now uses explicit `up` / `down` with `add_column ..., if_not_exists: true` and `remove_column ..., if_exists: true`. It is still idempotent, and rollback now removes the column. A new generator spec runs the generated migration up, down and up.
+- **`before_checksum` hook failures use `config.audit_error_context_key`.** The hook's `Rails.error.report` hard-coded `audit_event:` as its context key. Every other audit-error report site uses the configured key (default `:audit_action`). Apps that set `audit_error_context_key = :audit_event` see no change. Apps on the default now get `audit_action:` for hook failures too, matching every other audit error.
+
+### Documentation
+
+- `current_scope_resolver` is for scope derived from `Current`. Scope derived from the row (e.g. the target's organisation) belongs in a `before_checksum` or `before_write` hook. The README no longer describes sidekick-web's target-derived hook as a `Current` back-fill.
+- New note: `before_write` / `before_checksum` run once per row, batched writes included. Memoize per-actor lookups (e.g. in a `CurrentAttributes` cache) to avoid an N+1 on a batch flush.
+- `record(raise: false)` reports through `Rails.error`, so failures reach Sentry only if a `Rails.error` subscriber is registered (`sentry-rails` registers one).
+
 ## [0.12.0] - 2026-09-24
 
 ### Upgrade steps

data/README.md

@@ -102,8 +102,8 @@ When `actor` is omitted, it falls back to the configured `current_actor_resolver
 
 Where a missing audit row must never break the request — logging an
 authentication failure, say — pass `raise: false`. A failed write is logged,
-reported to `Rails.error` as handled (context
-`{ <audit_error_context_key> => event_type, source: "StandardAudit.record" }`),
+reported through `config.error_reporter` (default: `Rails.error`, as handled;
+context `{ <audit_error_context_key> => event_type, source: "StandardAudit.record" }`),
 and `record` returns nil:
 
 ```ruby
@@ -116,6 +116,31 @@ StandardAudit.record("auth.token_invalid",
 The default is `raise: true` (unchanged). In block form the option only
 governs the audit write; errors from your block always propagate.
 
+#### Where swallowed failures go: `config.error_reporter`
+
+By default the gem reports every error it swallows with
+`Rails.error.report(error, handled: true, context:)`. That covers a failed
+`record(raise: false)`, a failed subscriber write, a raising `before_checksum`
+hook, and a failed `audit!` write under the default policy. It reaches your
+error tracker only if something subscribes to `Rails.error`. `sentry-rails`
+registers that subscriber for you. If your app never forwards `Rails.error`
+(a hand-rolled Sentry setup), point the gem straight at the tracker (0.13.0+):
+
+```ruby
+config.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
+```
+
+It receives the error and the context Hash (keyed by
+`audit_error_context_key`) and **replaces** the `Rails.error` call. If you want
+both, call `Rails.error.report` from it too. A reporter that raises is logged
+and ignored, so it can never turn a swallowed audit failure into a raised one.
+`audit_write_error_handler`, when set, still takes precedence for `audit!`
+write failures.
+
+**Replace your host code with** `config.error_reporter`. It supersedes any
+rescue-and-report wrapper kept around `record(raise: false)` or `audit!` only
+because the app does not forward `Rails.error` to its tracker.
+
 **Replace your host code with** `raise: false`. It supersedes the
 `AuditAuthFailure#record_auth_failure` rescue-and-report wrapper
 (sidekick-web, luminality-web, nutripod-web
@@ -166,18 +191,61 @@ never ran on direct `record` calls.)
 ```ruby
 config.before_write = ->(entry) {
   # entry: { event_type:, actor:, target:, scope:, metadata:,
-  #          request_id:, ip_address:, user_agent:, session_id: }
-  AuditMetadataPii.verify!(entry[:metadata]) if StandardAudit::Operation::Audit.verify?
-  if (surface = Current.audit_surface).present?
-    entry[:metadata] = entry[:metadata].merge(surface: surface)
-  end
+  #          request_id:, ip_address:, user_agent:, session_id:, via: }
+  metadata = entry[:metadata]
+  AuditMetadataPii.verify!(metadata) if StandardAudit::Operation::Audit.verify? && entry[:via] == :direct
+  metadata = AuditMetadataPii.mask(metadata)
+  metadata = metadata.merge(surface: Current.audit_surface) if Current.audit_surface.present?
+  entry[:metadata] = metadata
 }
 ```
 
-It runs after the `Current` resolvers and `metadata_builder`, and **before**
-dereferencing and `sensitive_keys` redaction, so anything it injects is still
-filtered. Mutate `entry` in place; the return value is ignored. Raising aborts
-the write: direct callers see the error, the subscribers rescue and report it.
+**Order, per write:** `Current` resolvers → `metadata_builder` → `before_write`
+→ record dereferencing → `sensitive_keys` redaction → persist (or buffer, or
+enqueue). So:
+
+- `before_write` **sees the builder's output, not the raw metadata.** If your
+  `metadata_builder` masks or rewrites values, a guard in `before_write` checks
+  the masked values and can never fire. Keep the builder to idempotent
+  injection (like `engine_scope`), and do guard-then-mask in `before_write`, in
+  that order, as above. Before 0.13 this README showed a guard in
+  `before_write` next to a masking builder, which does not work.
+- Anything `before_write` injects is still dereferenced and redacted.
+
+Mutate `entry` in place; the return value is ignored. Raising aborts the write:
+direct callers see the error, the subscribers rescue and report it.
+
+**`entry[:via]`** (0.13.0+) names the entry point, so a hook can treat direct
+writes differently from subscriber writes. For example, it can apply a guard
+only to rows your own code writes and not to payloads a gem publishes. It is
+not persisted.
+
+| `entry[:via]` | Written by |
+|---|---|
+| `:direct` | `StandardAudit.record` (no block), `Auditable#record_audit`, `Operation#audit!` |
+| `:notification` | the ActiveSupport::Notifications subscriber (`subscribe_to` patterns), including `StandardAudit.record` **with a block** |
+| `:rails_event` | the `Rails.event` subscriber (Rails 8.1+) |
+
+**Hooks run once per row, batched writes included.** `before_write` and
+`before_checksum` run for every row inside `StandardAudit.batch` too (at flush
+time for `before_checksum`). A hook that looks something up per actor (a role,
+a membership, a tenant) therefore runs one query per row and turns a batch into
+an N+1. Memoize those lookups for the unit of work, for example in a
+`CurrentAttributes` cache that resets with the request or job:
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  attribute :audit_actor_roles
+
+  def self.audit_role_for(actor)
+    self.audit_actor_roles ||= {}
+    audit_actor_roles[actor.to_global_id.to_s] ||= actor.audit_role
+  end
+end
+
+# actor_role: a column your app added to audit_logs
+config.before_checksum { |log| log.actor_role = Current.audit_role_for(log.actor) if log.actor }
+```
 
 **Replace your host code with** a `before_write`. It supersedes:
 
@@ -397,7 +465,8 @@ RSpec.describe "StandardAudit configuration baseline" do
     catalogue: -> { AuditCatalogue::ACTIONS },
     sensitive_keys: %i[source_payload],
     sensitive_key_patterns: [/secret/i],
-    present: %i[metadata_builder before_write current_scope_resolver]
+    present: %i[metadata_builder before_write current_scope_resolver],
+    hooks: 2 # before_checksum hooks: a count, or %i[backfill_scope] by name
 end
 ```
 
@@ -406,6 +475,13 @@ restored after a mutation plus `reset_configuration!`. Behaviour held in
 lambdas can only be checked for presence; keep an app-specific example for
 anything whose *result* matters.
 
+`hooks:` (0.13.0+) covers `before_checksum` hooks, which a reset drops unless
+the baseline re-adds them. Pass an Integer to require exactly that many, or an
+Array of Symbol hook names (`config.before_checksum :name`) to require each one.
+The mutation example clears the hooks before the reset, so a hook registered
+outside the baseline block fails it. This replaces hand-written "still carries
+the N hooks after a reset" examples.
+
 **Replace your host code with** the shared example. It supersedes the bulk of
 each app's `spec/initializers/standard_audit_baseline_spec.rb` (or
 `spec/config/…`). The `Current.account` / `Current.session&.id` resolver
@@ -500,9 +576,14 @@ StandardAudit.configure(baseline: true) do |config|
   config.current_scope_resolver = -> { Current.organisation }
 
   # -- before_write --
-  # Runs on every write path, before redaction. See "One write path".
+  # Runs on every write path, after metadata_builder and before redaction.
+  # entry[:via] is :direct, :notification or :rails_event. See "One write path".
   config.before_write = ->(entry) { entry[:metadata] = entry[:metadata].merge("surface" => Current.surface) }
 
+  # -- Error reporting --
+  # Where swallowed audit failures go. nil (default) = Rails.error.report.
+  # config.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
+
   # -- Async Processing --
   # Offload audit log creation to ActiveJob.
   config.async = false
@@ -641,14 +722,25 @@ It is a *fallback*: an explicit `scope:` and a scope found by `scope_extractor`
 always win. It applies on every write path (direct `record`, `audit!`,
 `record_audit`, both subscribers; sync, async and batched). Default `nil`.
 
-**Replace your host code with** the one line above. It supersedes:
+`current_scope_resolver` is for scope that comes from **ambient request
+state** (`Current`). It takes no arguments and never sees the row. Scope that
+derives from the **row itself**, such as the organisation that owns the
+target, belongs in a `before_checksum` hook (or `before_write`), which receives
+the record or entry:
 
-- a `scope_extractor` that falls back to `Current` (nutripod-web:
-  `->(payload) { payload[:scope] || Current.channel || Current.organisation }`),
-  which only ever covered the subscriber path — keep `scope_extractor` for
-  reading the payload, move the `Current` fallback here;
-- a `before_checksum` hook that back-fills `log.scope` from `Current`
-  (sidekick-web), which before 0.12.0 never ran on the batched path.
+```ruby
+config.before_checksum do |log|
+  log.scope ||= log.target.organisation if log.target.respond_to?(:organisation)
+end
+```
+
+**Replace your host code with** the one line above when your fallback reads
+`Current`. It supersedes a `scope_extractor` that falls back to `Current`
+(nutripod-web:
+`->(payload) { payload[:scope] || Current.channel || Current.organisation }`),
+which only ever covered the subscriber path. Keep `scope_extractor` for reading
+the payload and move the `Current` fallback here. Target-derived scope hooks
+stay as they are; since 0.12.0 they also run on the batched path.
 
 ## Async Processing
 
@@ -858,7 +950,12 @@ It is for rows that never had a checksum at all (pre-feature data).
 | `standard_audit:install` | `audit_logs` migration + initializer (new installs) |
 | `standard_audit:add_previous_checksum` | Adds `previous_checksum` (upgrading from < 0.8) |
 | `standard_audit:add_anonymized_at` | Adds `anonymized_at` (upgrading from < 0.12) |
-| `standard_audit:add_checksums` | **Deprecated** (0.12.0; to be removed). The 0.2 → 0.3 upgrade path; warns when run |
+
+The upgrade generators number their migration one second after the newest
+migration already in `db/migrate` when that is later than now (0.13.0+), so the
+new migration sorts after future-dated host migrations instead of before them.
+Before 0.13.0 they stamped the current time. (`standard_audit:add_checksums`,
+the 0.2 → 0.3 upgrade path, was removed in 0.13.0.)
 
 ## Rake Tasks
 

data/app/models/standard_audit/audit_log.rb

@@ -597,7 +597,7 @@ module StandardAudit
         # persist — so the hook would not actually be "skipped".
         restore_attributes_from(snapshot)
         Rails.logger.warn("[StandardAudit] before_checksum hook failed: #{e.class}: #{e.message}")
-        Rails.error.report(e, handled: true, context: { audit_event: event_type }) if Rails.respond_to?(:error)
+        StandardAudit.report_error(e, { StandardAudit.config.audit_error_context_key => event_type })
         nil
       end
     end

data/lib/generators/standard_audit/add_anonymized_at/add_anonymized_at_generator.rb

@@ -1,16 +1,15 @@
+require "rails/generators"
+require "generators/standard_audit/migration_number"
+
 module StandardAudit
   module Generators
     # Adds `audit_logs.anonymized_at` (0.12.0). With it, rows erased by
     # `AuditLog.anonymize_actor!` are reported by `verify_chain` as `redacted`
     # rather than as `digest_mismatch` failures.
     class AddAnonymizedAtGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include StandardAudit::Generators::MigrationNumber
       source_root File.expand_path("templates", __dir__)
 
-      def self.next_migration_number(dirname)
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
-      end
-
       def copy_migration
         migration_template "add_anonymized_at_to_audit_logs.rb.erb",
           "db/migrate/add_anonymized_at_to_audit_logs.rb"

data/lib/generators/standard_audit/add_anonymized_at/templates/add_anonymized_at_to_audit_logs.rb.erb

@@ -1,15 +1,25 @@
 class AddAnonymizedAtToAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def change
-    # A nullable column with no default: a metadata-only change on PostgreSQL,
-    # no table rewrite, nothing for StrongMigrations to object to. Idempotent,
-    # so it is safe on a host that already has the column (a 0.12+ install).
-    #
-    # Rows anonymized BEFORE this migration keep a NULL stamp and still fail
-    # `verify_chain` as `digest_mismatch`; there is no way to tell them apart
-    # from tampered rows after the fact. If your erasure records identify them,
-    # stamp them by hand (`update_columns(anonymized_at: ...)`).
-    return if column_exists?(:audit_logs, :anonymized_at)
+  # A nullable column with no default: a metadata-only change on PostgreSQL,
+  # no table rewrite, nothing for StrongMigrations to object to. Idempotent,
+  # so it is safe on a host that already has the column (a 0.12+ install).
+  #
+  # Rows anonymized BEFORE this migration keep a NULL stamp and still fail
+  # `verify_chain` as `digest_mismatch`; there is no way to tell them apart
+  # from tampered rows after the fact. If your erasure records identify them,
+  # stamp them by hand (`update_columns(anonymized_at: ...)`).
+  #
+  # Explicit up/down with `if_not_exists:` / `if_exists:` rather than an early
+  # `return if column_exists?` inside `change`: that return also runs on
+  # rollback, which then deletes the schema_migrations row and silently leaves
+  # the column behind.
+  #
+  # Rolling back drops the column even if it came from your create_audit_logs
+  # migration (0.12+ installs). Those installs do not need this migration.
+  def up
+    add_column :audit_logs, :anonymized_at, :datetime, if_not_exists: true
+  end
 
-    add_column :audit_logs, :anonymized_at, :datetime
+  def down
+    remove_column :audit_logs, :anonymized_at, if_exists: true
   end
 end

data/lib/generators/standard_audit/add_previous_checksum/add_previous_checksum_generator.rb

@@ -1,13 +1,12 @@
+require "rails/generators"
+require "generators/standard_audit/migration_number"
+
 module StandardAudit
   module Generators
     class AddPreviousChecksumGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include StandardAudit::Generators::MigrationNumber
       source_root File.expand_path("templates", __dir__)
 
-      def self.next_migration_number(dirname)
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
-      end
-
       def copy_migration
         migration_template "add_previous_checksum_to_audit_logs.rb.erb",
           "db/migrate/add_previous_checksum_to_audit_logs.rb"

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

@@ -1,4 +1,5 @@
 require "rails/generators"
+require "generators/standard_audit/migration_number"
 
 module StandardAudit
   module Generators
@@ -11,7 +12,7 @@ module StandardAudit
     # installed. Pass `--skip-*` flags to opt out of individual steps and
     # `--force` to overwrite an existing initializer.
     class InstallGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include StandardAudit::Generators::MigrationNumber
       source_root File.expand_path("templates", __dir__)
 
       desc <<~DESC
@@ -32,10 +33,6 @@ module StandardAudit
       class_option :force, type: :boolean, default: false,
         desc: "Overwrite config/initializers/standard_audit.rb if it already exists"
 
-      def self.next_migration_number(dirname)
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
-      end
-
       def copy_migration
         if options[:skip_migration]
           say_status("skip", "db/migrate/*_create_audit_logs.rb (--skip-migration)", :yellow)

data/lib/generators/standard_audit/migration_number.rb

@@ -0,0 +1,40 @@
+require "rails/generators/migration"
+require "time"
+
+module StandardAudit
+  module Generators
+    # Migration numbering shared by the gem's migration generators.
+    #
+    # A plain `Time.now` stamp sorts BEFORE a host's future-dated migrations
+    # (several consumers date theirs ahead of the clock), so the generated
+    # migration would run out of order and look already-applied to tools that
+    # compare against the latest version. This picks whichever is later: now,
+    # or one second after the newest migration already in the target
+    # directory. (ActiveRecord's own generators add 1 to the number, which
+    # can produce an invalid timestamp such as ...235960; this adds a second.)
+    module MigrationNumber
+      def self.included(base)
+        base.include Rails::Generators::Migration
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        FORMAT = "%Y%m%d%H%M%S".freeze
+
+        def next_migration_number(dirname)
+          [Time.now.utc.strftime(FORMAT), one_second_after(current_migration_number(dirname))].max
+        end
+
+        private
+
+        def one_second_after(number)
+          stamp = Kernel.format("%.14d", number)
+          (Time.strptime("#{stamp} +0000", "#{FORMAT} %z") + 1).utc.strftime(FORMAT)
+        rescue ArgumentError
+          # Not a timestamp (no migrations yet, or a sequential numbering).
+          Kernel.format("%.14d", number + 1)
+        end
+      end
+    end
+  end
+end

data/lib/standard_audit/configuration.rb

@@ -13,7 +13,7 @@ module StandardAudit
                   :anonymizable_metadata_keys, :retention_days,
                   :audit_catalogue, :verify_audit_declarations,
                   :raise_on_audit_write_error, :audit_write_error_handler,
-                  :audit_error_context_key
+                  :audit_error_context_key, :error_reporter
 
     def initialize
       @subscriptions = []
@@ -191,6 +191,27 @@ module StandardAudit
       # improvement to the built-in reporter. Default keeps existing behaviour.
       @audit_error_context_key = :audit_action
 
+      # Where the gem sends the errors it swallows: a failed subscriber write,
+      # a failed `record(raise: false)`, a raising `before_checksum` hook, and
+      # a failed `audit!` write under the default report-and-swallow policy.
+      # A callable taking `(error, context)`, where context is a Hash such as
+      # `{ audit_action: "orders.created", subscriber: "StandardAudit::Subscriber" }`
+      # (keyed by `audit_error_context_key`).
+      #
+      # nil (the default) means `Rails.error.report(error, handled: true,
+      # context: context)`. That reaches Sentry only when a `Rails.error`
+      # subscriber is registered (sentry-rails registers one); a host that
+      # never forwards `Rails.error` can point this straight at its tracker:
+      #
+      #   config.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
+      #
+      # It replaces the built-in `Rails.error` call; call `Rails.error.report`
+      # from it too if you want both. A reporter that raises is logged and
+      # ignored, so it can never turn a swallowed audit failure into a raised
+      # one. `audit_write_error_handler`, when set, still takes precedence for
+      # `audit!` write failures.
+      @error_reporter = nil
+
       # Retention defaults from ENV so it can be set per-environment without a
       # code change. Unset/blank/non-positive => nil (infinite retention, the
       # compliance-safe default that never auto-deletes). A host app can still

data/lib/standard_audit/engine.rb

@@ -1,7 +1,10 @@
 module StandardAudit
+  # A plain (non-isolated) engine: it contributes the AuditLog model, the two
+  # jobs and the subscriber wiring, and has no routes, controllers or views.
+  # 0.13.0 dropped `isolate_namespace` and the empty `config/routes.rb` it
+  # carried. Nothing depended on them: AuditLog sets its own `table_name`, and
+  # no host mounted the engine.
   class Engine < ::Rails::Engine
-    isolate_namespace StandardAudit
-
     initializer "standard_audit.subscriber" do
       ActiveSupport.on_load(:active_record) do
         StandardAudit.subscriber.setup!

data/lib/standard_audit/event_subscriber.rb

@@ -47,7 +47,8 @@ module StandardAudit
           ip_address: context[:ip_address] || payload[:ip_address],
           user_agent: context[:user_agent] || payload[:user_agent],
           session_id: context[:session_id] || payload[:session_id]
-        }
+        },
+        via: :rails_event
       )
     rescue => e
       StandardAudit.report_write_error(e, name, subscriber: self.class.name)

data/lib/standard_audit/operation/audit.rb

@@ -282,13 +282,9 @@ module StandardAudit
           message = "[StandardAudit] Failed to record #{action}: #{error.class} #{error.message}"
           Rails.logger&.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
 
-          return unless defined?(Rails) && Rails.respond_to?(:error) && Rails.error
-
-          Rails.error.report(
+          StandardAudit.report_error(
             error,
-            handled: true,
-            context: { StandardAudit.config.audit_error_context_key => action,
-                       operation: operation.class.name }
+            { StandardAudit.config.audit_error_context_key => action, operation: operation.class.name }
           )
         end
       end

data/lib/standard_audit/rspec/baseline.rb

@@ -18,12 +18,19 @@ require "standard_audit"
 #       catalogue: -> { AuditCatalogue::ACTIONS },
 #       sensitive_keys: %i[source_payload],
 #       sensitive_key_patterns: [/secret/i],
-#       present: %i[metadata_builder before_write current_scope_resolver]
+#       present: %i[metadata_builder before_write current_scope_resolver],
+#       hooks: 2   # or %i[backfill_scope classify_actor]
 #   end
 #
 # Every option is optional. Behaviour held in lambdas (resolvers, builders)
 # can't be compared by value, so list them under `present:` to assert they
 # survive a reset, and keep an app-specific example for what they return.
+#
+# `hooks:` covers `before_checksum` hooks, which live in a list rather than a
+# named setting. Pass an Integer to assert exactly that many are registered,
+# or an Array of the Symbol hook names (`config.before_checksum :name`) to
+# assert each is registered. The mutation example also clears the hooks
+# before the reset, so it fails if the baseline block doesn't re-add them.
 RSpec.shared_examples "a standard_audit baseline" do |options = {}|
   subscriptions          = Array(options[:subscriptions])
   settings               = options.fetch(:settings, {})
@@ -31,9 +38,14 @@ RSpec.shared_examples "a standard_audit baseline" do |options = {}|
   sensitive_keys         = Array(options[:sensitive_keys])
   sensitive_key_patterns = Array(options[:sensitive_key_patterns])
   present                = Array(options[:present])
+  hooks                  = options[:hooks]
+
+  unless hooks.nil? || hooks.is_a?(Integer) || (hooks.is_a?(Array) && hooks.all? { |h| h.is_a?(Symbol) || h.is_a?(String) })
+    raise ArgumentError, "hooks: must be an Integer (hook count) or an Array of Symbol hook names; got #{hooks.inspect}"
+  end
 
   def standard_audit_baseline_assertions(subscriptions:, settings:, catalogue:, sensitive_keys:,
-    sensitive_key_patterns:, present:)
+    sensitive_key_patterns:, present:, hooks:)
     config = StandardAudit.config
 
     expect(config.subscriptions).to include(*subscriptions) if subscriptions.any?
@@ -49,11 +61,22 @@ RSpec.shared_examples "a standard_audit baseline" do |options = {}|
     present.each do |name|
       expect(config.public_send(name)).not_to be_nil, "expected config.#{name} to survive a reset"
     end
+    case hooks
+    when Integer
+      expect(config.before_checksum_hooks.size).to eq(hooks),
+        "expected #{hooks} before_checksum hook(s) after a reset, found #{config.before_checksum_hooks.size}"
+    when Array
+      registered = config.before_checksum_hooks.select { |h| h.is_a?(Symbol) || h.is_a?(String) }.map(&:to_sym)
+      hooks.map(&:to_sym).each do |name|
+        expect(registered).to include(name), "expected before_checksum :#{name} to survive a reset"
+      end
+    end
   end
 
   let(:standard_audit_baseline_options) do
     { subscriptions: subscriptions, settings: settings, catalogue: catalogue,
-      sensitive_keys: sensitive_keys, sensitive_key_patterns: sensitive_key_patterns, present: present }
+      sensitive_keys: sensitive_keys, sensitive_key_patterns: sensitive_key_patterns, present: present,
+      hooks: hooks }
   end
 
   it "is registered with configure(baseline: true)" do
@@ -71,6 +94,7 @@ RSpec.shared_examples "a standard_audit baseline" do |options = {}|
     StandardAudit.config.subscribe_to "standard_audit.isolation_canary"
     settings.each_key { |name| StandardAudit.config.public_send(:"#{name}=", nil) }
     present.each { |name| StandardAudit.config.public_send(:"#{name}=", nil) }
+    StandardAudit.config.before_checksum_hooks = [] unless hooks.nil?
 
     StandardAudit.reset_configuration!
 

data/lib/standard_audit/subscriber.rb

@@ -46,7 +46,8 @@ module StandardAudit
         target: config.target_extractor.call(payload),
         scope: config.scope_extractor.call(payload),
         metadata: payload.except(*EXCLUDED_PAYLOAD_KEYS),
-        context: payload.slice(:request_id, :ip_address, :user_agent, :session_id)
+        context: payload.slice(:request_id, :ip_address, :user_agent, :session_id),
+        via: :notification
       )
     rescue => e
       StandardAudit.report_write_error(e, event.name, subscriber: self.class.name)

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/standard_audit.rb

@@ -17,6 +17,16 @@ module StandardAudit
   # `sensitive_keys` even if a user adds them there.
   RESERVED_METADATA_KEYS = %w[_tags _source].freeze
 
+  # Values of `entry[:via]` as `before_write` sees it:
+  #
+  # * `:direct` — `StandardAudit.record` without a block, and therefore
+  #   `Auditable#record_audit` and `Operation#audit!`.
+  # * `:notification` — the ActiveSupport::Notifications subscriber
+  #   (`subscribe_to` patterns, and `StandardAudit.record` WITH a block, which
+  #   instruments the event and lets this subscriber write it).
+  # * `:rails_event` — the `Rails.event` subscriber (Rails 8.1+).
+  VIA = %i[direct notification rails_event].freeze
+
   class << self
     # Applies configuration to the single mutable Configuration instance.
     #
@@ -58,7 +68,8 @@ module StandardAudit
     # here), so it records only when the event is subscribed to.
     #
     # `raise: false` makes a failed write non-fatal: the error is logged and
-    # reported to `Rails.error` as handled, and nil is returned. For call
+    # reported through `config.error_reporter` (default: `Rails.error`, as
+    # handled), and nil is returned. For call
     # sites where a missing audit row must never break the request (auth
     # failure logging, say). It governs only the audit write — in block form
     # the subscriber already rescues, and the block's own errors always
@@ -80,7 +91,7 @@ module StandardAudit
 
       begin
         write_entry(event_type, actor: actor, target: target, scope: scope,
-          metadata: metadata, context: options)
+          metadata: metadata, context: options, via: :direct)
       rescue => e
         raise if raise_errors
 
@@ -96,7 +107,11 @@ module StandardAudit
     # values; nil entries fall back to the Current resolvers. `reserved` is
     # merged into metadata AFTER `metadata_builder` (the Rails.event subscriber
     # uses it for `_tags` / `_source`, which a builder never saw before 0.12).
-    def write_entry(event_type, actor:, target:, scope:, metadata:, context: {}, reserved: {})
+    # `via` names the entry point (see VIA) and is handed to `before_write`
+    # as `entry[:via]`; it is not persisted.
+    def write_entry(event_type, actor:, target:, scope:, metadata:, context: {}, reserved: {}, via: :direct)
+      raise ArgumentError, "via must be one of #{VIA.inspect}; got #{via.inspect}" unless VIA.include?(via)
+
       actor ||= config.current_actor_resolver.call
       scope ||= config.current_scope_resolver&.call
 
@@ -113,14 +128,16 @@ module StandardAudit
         request_id: context[:request_id] || config.current_request_id_resolver.call,
         ip_address: context[:ip_address] || config.current_ip_address_resolver.call,
         user_agent: context[:user_agent] || config.current_user_agent_resolver.call,
-        session_id: context[:session_id] || config.current_session_id_resolver.call
+        session_id: context[:session_id] || config.current_session_id_resolver.call,
+        via: via
       }
 
-      # Runs on EVERY path, before redaction, so anything it injects into
-      # metadata is still subject to `sensitive_keys` and dereferencing. It may
-      # mutate `entry` in place; its return value is ignored. It may raise —
-      # that is how a host guard rejects a write — and the error propagates
-      # exactly as a failed save would.
+      # Runs on EVERY path, AFTER `metadata_builder` and before redaction, so
+      # it sees the builder's output and anything it injects into metadata is
+      # still subject to `sensitive_keys` and dereferencing. It may mutate
+      # `entry` in place; its return value is ignored. It may raise — that is
+      # how a host guard rejects a write — and the error propagates exactly as
+      # a failed save would. `entry[:via]` says which entry point wrote it.
       config.before_write&.call(entry)
 
       persist(entry)
@@ -147,20 +164,29 @@ module StandardAudit
       Thread.current[:standard_audit_batch] = previous
     end
 
-    # @api private — logs a failed audit write and reports it to Rails.error
-    # as handled. Used by the subscribers, which must never let an audit
-    # failure break the instrumented code path.
+    # @api private — logs a failed audit write and reports it through
+    # `report_error`. Used by the subscribers, which must never let an audit
+    # failure break the instrumented code path, and by `record(raise: false)`.
     def report_write_error(error, event_type, **context)
       Rails.logger.error("[StandardAudit] Error creating audit log for #{event_type}: #{error.class}: #{error.message}")
-      return unless Rails.respond_to?(:error) && Rails.error
+      report_error(error, { config.audit_error_context_key => event_type, **context })
+    end
 
-      Rails.error.report(
-        error,
-        handled: true,
-        context: { config.audit_error_context_key => event_type, **context }
-      )
+    # @api private — the one place the gem reports an error it swallows.
+    # Calls `config.error_reporter` when set, otherwise
+    # `Rails.error.report(error, handled: true, context:)`. A reporter that
+    # raises is logged and ignored.
+    def report_error(error, context)
+      if config.error_reporter
+        config.error_reporter.call(error, context)
+      elsif defined?(Rails) && Rails.respond_to?(:error) && Rails.error
+        Rails.error.report(error, handled: true, context: context)
+      end
+      nil
     rescue => report_failure
-      Rails.logger.error("[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}")
+      message = "[StandardAudit] Error reporting audit failure: #{report_failure.class}: #{report_failure.message}"
+      Rails.logger&.error(message) if defined?(Rails) && Rails.respond_to?(:logger)
+      nil
     end
 
     def subscriber

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -96,16 +96,14 @@ files:
 - app/jobs/standard_audit/create_audit_log_job.rb
 - app/models/standard_audit/application_record.rb
 - app/models/standard_audit/audit_log.rb
-- config/routes.rb
 - lib/generators/standard_audit/add_anonymized_at/add_anonymized_at_generator.rb
 - lib/generators/standard_audit/add_anonymized_at/templates/add_anonymized_at_to_audit_logs.rb.erb
-- lib/generators/standard_audit/add_checksums/add_checksums_generator.rb
-- lib/generators/standard_audit/add_checksums/templates/add_checksum_to_audit_logs.rb.erb
 - lib/generators/standard_audit/add_previous_checksum/add_previous_checksum_generator.rb
 - lib/generators/standard_audit/add_previous_checksum/templates/add_previous_checksum_to_audit_logs.rb.erb
 - lib/generators/standard_audit/install/install_generator.rb
 - lib/generators/standard_audit/install/templates/create_audit_logs.rb.erb
 - lib/generators/standard_audit/install/templates/initializer.rb.erb
+- lib/generators/standard_audit/migration_number.rb
 - lib/standard_audit.rb
 - lib/standard_audit/audit_scope.rb
 - lib/standard_audit/auditable.rb

data/config/routes.rb

@@ -1,2 +0,0 @@
-StandardAudit::Engine.routes.draw do
-end

data/lib/generators/standard_audit/add_checksums/add_checksums_generator.rb

@@ -1,30 +0,0 @@
-module StandardAudit
-  module Generators
-    # DEPRECATED (0.12.0); scheduled for removal. This is the 0.2 -> 0.3
-    # upgrade path that added the `checksum` column. Every install since 0.3
-    # creates the column via `standard_audit:install`, and no known host still
-    # needs it. Run `standard_audit:add_previous_checksum` on hosts that
-    # predate 0.8 instead.
-    class AddChecksumsGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
-      source_root File.expand_path("templates", __dir__)
-
-      DEPRECATION_MESSAGE = "standard_audit:add_checksums is deprecated and will be removed in a " \
-                            "future release. It only upgrades pre-0.3 installs; the install " \
-                            "generator has created the checksum column since 0.3.".freeze
-
-      def self.next_migration_number(dirname)
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
-      end
-
-      def warn_deprecated
-        say_status :deprecated, DEPRECATION_MESSAGE, :yellow
-        warn "[StandardAudit] DEPRECATION: #{DEPRECATION_MESSAGE}"
-      end
-
-      def copy_migration
-        migration_template "add_checksum_to_audit_logs.rb.erb", "db/migrate/add_checksum_to_audit_logs.rb"
-      end
-    end
-  end
-end

data/lib/generators/standard_audit/add_checksums/templates/add_checksum_to_audit_logs.rb.erb

@@ -1,6 +0,0 @@
-class AddChecksumToAuditLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def change
-    add_column :audit_logs, :checksum, :string, limit: 64
-    add_index :audit_logs, :created_at
-  end
-end