standard_audit 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55028cd60be7b29a81c8bd0eccb5cbccadfba4f7691f0d6576214de4367e53c9
-  data.tar.gz: efcf7f59f891570b8076e870f64d632de6d707ed9a4aa1f4b6e35aa7116199d1
+  metadata.gz: 7fca49bbca23bc24c89aa7249f0ea4718c2f4fa6bae03748ec93a45df17c4bd0
+  data.tar.gz: 7920932fea8af270498c7620d7cb4e18e0cfaab1c0deb7f299715ce578882dd2
 SHA512:
-  metadata.gz: d1d0c3c3807faf64dc9e21c897da2e3317a6fee1ea202aae6b07a948f416bbb8d35c03f8977a3def8bdf5a2bca9944941e3fe1b3c860d7b2b3aa942a8f048e16
-  data.tar.gz: 16278c66d30fe401947d8748e6b675a9dd5bc49dac1d0183635faf27df8e1b9e5a5f2d933aa8a606c1b66a01894dc030088a3813b7ca8eb2aee68ed7bd811e0d
+  metadata.gz: 7117529ed69a81588ea18b081e3b8a8047dc9441fe116bef9e594beacc692108a1c8d625e2d4c1a959ac01a1d03857d9d94e91a4dfe65c52c35ce894b980e797
+  data.tar.gz: bdb36b281136e0928c4bac601bbee408de0cf040d70222c8d3339153c53312e1bd1820f136488086184426f68ce9f930b75d521b75fd25950f4f7b3bb232c66d

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-31
+
+### Added
+
+- **`config.audit_error_context_key`** (default `:audit_action`) — renames the `Rails.error.report` context key naming the audit action, without needing a whole handler. Two apps had overridden `audit_write_error_handler` for nothing but this: both tag every OTHER audit-error report site with `audit_event:` (four sites in one, twelve across ten files in the other), so adopting the gem name left the operations layer as the only place forking the convention. A handler written to rename one key also silently opts out of every future improvement to the built-in reporter.
+
+### Changed
+
+- **The built-in reporter no longer fires when `raise_on_audit_write_error` re-raises.** The caller receives the error and owns it, so reporting as well produced two events for one failure in every host that both sets the flag and reports on what it catches — which is most hosts that set it at all, since the flag exists for hosts treating an unaudited write as a failure worth handling. Two of the five apps hit this independently and each wrote a log-only handler to work around it. A host that does NOT catch the error still gets a report, via its framework unhandled-error path. An explicitly configured `audit_write_error_handler` is unaffected and still runs under either policy — only the built-in reporter steps aside.
+
+### Fixed
+
+- **The write-site scan no longer reads comments as calls.** An operation declaring `audit_none!` that explained itself in prose naming `audit!` was flagged by `unexpected_write_sites` — a false failure, which hosts worked around by backticking the token in their own comments. Source is now lexed with `Ripper` and comment tokens dropped before scanning; a file that cannot be lexed falls back to raw source (the old behaviour). Lexing rather than stripping `#` to end-of-line, because the naive form eats `"#{interpolation}"` and `%w[#]` and would trade a false failure for a false pass.
+- **Corrected a docstring that was wrong for half its own surface.** It claimed the source-scanning predicates "err towards a false pass rather than a false failure". That held only for `missing_write_sites`; in the `unexpected_write_sites` direction the same match produced a false failure. Worse than the bug itself, since it told anyone hitting the failure not to suspect the scanner.
+
+## [0.9.0] - 2026-07-31
+
+### Added
+
+- **`StandardAudit::Operation` — the operation-audit DSL, extracted from five independent copies.** Every consumer app had written the same contract by hand: `audits "x.y"` / `audit_none!` class declarations, a private `audit!(action, **attrs)` as the single write path, and a `verify_audit_declared!` guard that raises on declaration↔write drift in local environments and writes silently in production. The surface is unchanged from those copies, so operation files do not move — adopting apps swap one `include` line and delete their concern. (`rarebit-one/rarebit-ops#279`)
+  - It is a **module, never a base class**. The five host `ApplicationOperation`s range 61–303 lines and diverge deliberately (one refuses a `Result`/`execute` lifecycle; one app has no shared base at all), so the module contributes the audit contract and nothing else.
+  - **Both adoption shapes work with no configuration**: a shared base that includes it once, whose subclasses are the real operations, and standalone leaves that each include it directly. The unifier is that a class declaring nothing *and* having subclasses is treated as a base and excluded — so a shared base auto-excludes, while every leaf is retained. A class that did declare is never excluded that way.
+  - `audit_abstract!` for an intermediate class the automatic rule can't see (typically one with no subclasses yet).
+- **`config.audit_catalogue`** — the host's action vocabulary, as a **callable** (`-> { AuditCatalogue::ACTIONS }`); referencing an autoloadable constant eagerly from an initializer breaks Zeitwerk reloading. A plain Array is accepted for a frozen literal. `nil` (the default) skips the membership check, so the DSL is adoptable before an app has a catalogue. **Membership is the only rule applied** — no dot-count, case, prefix, or namespace validation, because an action may legitimately carry a notification-bus namespace verbatim and normalising it would orphan historical rows.
+- **`config.raise_on_audit_write_error`** (default `false`) and **`config.audit_write_error_handler`**. Four of the five apps report-and-swallow a failed audit write; one deliberately does not rescue, because for it an unaudited state change is itself a compliance failure. A swallow-only module would have silently downgraded that posture. `StandardAudit::Operation::DeclarationError` is never governed by either — it always re-raises, ahead of any generic rescue.
+- **`config.verify_audit_declarations`** (callable or boolean, default: local environments only) — gates the dev/test guard.
+- **Meta-spec logic as plain Ruby predicates** on `StandardAudit::Operation::Audit`: `.operations(source:)`, `.undeclared`, `.unknown_actions`, `.orphan_actions(within:)`, `.missing_write_sites`, `.unexpected_write_sites`, `.duplicate_catalogue_entries`, `.declared_actions`. Each takes an explicit `operations:` list, so hosts can write bespoke assertions.
+- **`standard_audit/rspec/operation`** — a thin RSpec shared-example layer over those predicates, with no logic of its own. It carries a **`minimum:` registry floor**, the one example that catches "someone stopped including the module" or "eager loading stopped reaching the operations"; without it every other example passes vacuously against an empty set. Also `expected:`, `source:` scoping, and `orphans_within:` for hosts whose catalogue covers writers outside `app/operations/`.
+
+Everything is additive and nothing includes the module by default — existing hosts upgrade with no code change.
+
 ## [0.8.0] - 2026-07-30
 
 ### Added

data/README.md

@@ -162,6 +162,128 @@ This provides:
 organisation.scoped_audit_logs  # all logs scoped to this organisation
 ```
 
+## Operation Audit Contract
+
+`StandardAudit::Operation` makes an operation *declare* what it audits, so a new
+mutating operation cannot silently ship with no audit trail. It is a **module,
+not a base class** — it contributes the audit contract and nothing else (no
+`call`, no `Result`, no `execute`), so it drops into any operation style.
+
+```ruby
+class ApplicationOperation
+  include StandardAudit::Operation   # ← the whole adoption, for a shared base
+end
+
+class Orders::CreateOperation < ApplicationOperation
+  audits "order.created"
+
+  def execute
+    order = Order.create!(**attrs)
+    audit!("order.created", target: order, metadata: { total: order.total })
+  end
+end
+
+class Orders::ReindexOperation < ApplicationOperation
+  audit_none!   # projection of already-audited state
+end
+```
+
+- `audits "x.y"` — the action(s) this operation may write. Repeatable args; the
+  declaration is **not inherited**, so every leaf states its own intent.
+- `audit_none!` — mutates state but deliberately records nothing. Leave the
+  reason as a comment.
+- `audit_abstract!` — a base or intermediate class, not a real operation.
+- `audit!(action, **attrs)` — private; the single write path. Args forward
+  straight to `StandardAudit.record`. Call it inside the operation's own
+  transaction so the row commits with the state change.
+
+### Adoption shapes
+
+Both work with no configuration:
+
+1. **A shared base includes the module once**, and the real operations are its
+   subclasses (registered via `inherited`). The base declares nothing and has
+   subclasses, so it is excluded from the checks automatically. A class that
+   *did* declare is never excluded this way, so subclassing a real operation
+   cannot quietly drop it.
+2. **Every operation includes the module directly**, with no shared base
+   (registered via `included`).
+
+Both land in one registry, so a single meta-spec covers a codebase mixing them.
+
+### The catalogue
+
+The gem has no knowledge of your action vocabulary. Declare it as a **callable** —
+referencing an autoloadable constant eagerly from an initializer pins the
+first-loaded copy and breaks Zeitwerk reloading:
+
+```ruby
+StandardAudit.configure(baseline: true) do |config|
+  config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
+end
+```
+
+`nil` (the default) skips the membership check entirely, so the DSL is adoptable
+before you have a catalogue. **Membership is the only rule** — there is no
+dot-count, case, prefix, or namespace validation, because an action may
+legitimately carry a notification-bus namespace verbatim.
+
+### Error policy
+
+`StandardAudit::Operation::DeclarationError` — a declaration↔write mismatch —
+**always propagates**, ahead of any generic rescue. It is raised in local
+environments only (`config.verify_audit_declarations`); in production `audit!`
+just writes, because a developer's mistake must not 500 a user. The meta-spec is
+the real gate.
+
+A genuine **write** failure is governed by config:
+
+```ruby
+config.raise_on_audit_write_error = true   # default false: report and swallow
+config.audit_write_error_handler  = ->(error, action:, operation:) { ... }
+```
+
+Default `false` matches most apps, but set it `true` where an unaudited state
+change is itself a compliance failure — the audit write then aborts the
+operation.
+
+### The meta-spec
+
+The analysis is **plain Ruby**, so you can assert on it however you like:
+
+```ruby
+StandardAudit::Operation::Audit.operations(source: "/app/operations/")
+StandardAudit::Operation::Audit.undeclared            # => [Class, ...]
+StandardAudit::Operation::Audit.unknown_actions       # => { Class => ["x.y"] }
+StandardAudit::Operation::Audit.orphan_actions(within: ...)
+StandardAudit::Operation::Audit.missing_write_sites   # declares but never writes
+StandardAudit::Operation::Audit.unexpected_write_sites
+StandardAudit::Operation::Audit.duplicate_catalogue_entries
+```
+
+A thin RSpec layer over exactly those predicates:
+
+```ruby
+require "standard_audit/rspec/operation"
+
+RSpec.describe "Operation audit declarations" do
+  it_behaves_like "standard_audit operation declarations",
+    source:         "/app/operations/",
+    minimum:        100,
+    expected:       %w[Orders::CreateOperation],
+    orphans_within: -> { AuditCatalogue::OPERATION_ACTIONS }
+end
+```
+
+**Set `minimum:`.** It is the only example that fails when someone stops
+including the module or eager loading stops reaching your operations — every
+other example passes vacuously against an empty set. `orphans_within:` is the
+catalogue slice operations own; pass it when your catalogue also covers writers
+outside `app/operations/`, which would otherwise always look orphaned.
+
+The registry can only see loaded classes, so the shared example calls
+`Rails.application.eager_load!` by default (`eager_load: false` to opt out).
+
 ## Configuration Reference
 
 Use `configure(baseline: true)` in your initializer. It remembers the block so
@@ -218,6 +340,23 @@ StandardAudit.configure(baseline: true) do |config|
   config.before_checksum { |log| log.scope = MyApp.derive_scope(log) }
   config.before_checksum :backfill_scope   # an AuditLog instance method
 
+  # -- Operation audit contract (StandardAudit::Operation) --
+  # Your action vocabulary, as a CALLABLE so Zeitwerk can reload it. nil (the
+  # default) skips the membership check entirely.
+  config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
+
+  # Whether `audit!` verifies declarations before writing. Callable or boolean;
+  # defaults to local environments only.
+  config.verify_audit_declarations = -> { Rails.env.local? }
+
+  # Whether a failed audit WRITE aborts the operation. Default false (report and
+  # swallow). Set true where an unaudited state change is a compliance failure.
+  # DeclarationError always propagates regardless.
+  config.raise_on_audit_write_error = false
+  config.audit_write_error_handler = ->(error, action:, operation:) {
+    ErrorReporting.notify(error, component: "operation_audit", audit_action: action)
+  }
+
   # -- Metadata Builder --
   # Optional proc to transform metadata before storage.
   config.metadata_builder = ->(metadata) { metadata.slice(:relevant_key) }

data/lib/standard_audit/configuration.rb

@@ -8,7 +8,10 @@ module StandardAudit
                   :sensitive_keys, :sensitive_key_patterns,
                   :sensitive_key_exceptions, :filter_nested_metadata,
                   :metadata_builder, :before_checksum_hooks,
-                  :anonymizable_metadata_keys, :retention_days
+                  :anonymizable_metadata_keys, :retention_days,
+                  :audit_catalogue, :verify_audit_declarations,
+                  :raise_on_audit_write_error, :audit_write_error_handler,
+                  :audit_error_context_key
 
     def initialize
       @subscriptions = []
@@ -78,6 +81,67 @@ module StandardAudit
 
       @anonymizable_metadata_keys = %i[email name ip_address]
 
+      # ── StandardAudit::Operation (the operation-audit DSL) ────────────────
+
+      # The host's canonical action vocabulary, used by `audit!` to reject an
+      # action absent from it. Normally a CALLABLE, because referencing an
+      # autoloadable constant eagerly from an initializer pins the first-loaded
+      # copy and breaks Zeitwerk reloading:
+      #
+      #   config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
+      #
+      # A plain Array is accepted when the vocabulary really is a frozen
+      # literal. `nil` (the default) skips the membership check entirely, so
+      # the DSL is adoptable before an app has a catalogue.
+      #
+      # Membership is the ONLY rule applied — see StandardAudit::Operation.
+      @audit_catalogue = nil
+
+      # Whether `audit!` verifies the declaration before writing. A callable
+      # (or a plain boolean). Defaults to local environments only: in
+      # production `audit!` just writes, because a developer's declaration
+      # mistake must not 500 a user — the host's meta-spec is the real gate.
+      @verify_audit_declarations = -> {
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:local?) && Rails.env.local?
+      }
+
+      # Whether a failed audit *write* aborts the operation. `false` (report
+      # and swallow) matches four of the five apps this DSL was extracted from.
+      # Set `true` where an unaudited state change is itself a compliance
+      # failure — one app deliberately does not rescue, and defaulting to
+      # swallow would have silently downgraded that posture.
+      #
+      # StandardAudit::Operation::DeclarationError is NEVER governed by this;
+      # it always propagates.
+      @raise_on_audit_write_error = false
+
+      # Optional callable invoked instead of the built-in logger/Rails.error
+      # reporting when an audit write fails:
+      #
+      #   config.audit_write_error_handler =
+      #     ->(error, action:, operation:) { ErrorReporting.notify(error, ...) }
+      #
+      # Runs before `raise_on_audit_write_error` is applied, so it sees every
+      # write failure under either policy.
+      @audit_write_error_handler = nil
+
+      # The `Rails.error.report` context key naming the audit action, for the
+      # built-in reporter. Exists because two apps independently overrode
+      # `audit_write_error_handler` for nothing but this key: both tag every
+      # OTHER audit-error report site with `audit_event:` (four sites in one
+      # app, twelve across ten files in the other), so adopting the gem's name
+      # left the operations layer as the only place forking the convention.
+      #
+      # That divergence fails silently and asymmetrically — a saved error-tracker
+      # search grouped on the host's key keeps working and simply stops
+      # containing operation write failures. Nothing errors, nothing goes red,
+      # and the search still looks healthy.
+      #
+      # A whole handler to rename one key is a lot of ceremony, and a handler
+      # written for that reason also silently opts out of every future
+      # improvement to the built-in reporter. Default keeps existing behaviour.
+      @audit_error_context_key = :audit_action
+
       # 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/operation/audit.rb

@@ -0,0 +1,297 @@
+require "ripper"
+
+module StandardAudit
+  module Operation
+    # The registry, the catalogue resolver, the write-error policy, and the
+    # analysis predicates behind the operation-audit meta-spec.
+    #
+    # Everything here is PLAIN RUBY that returns data — no RSpec, no
+    # assertions. A host can call these from a bespoke spec, a rake task, or a
+    # CI script. `standard_audit/rspec/operation` is a thin shared-example
+    # layer over exactly these methods and adds no logic of its own.
+    #
+    #   StandardAudit::Operation::Audit.undeclared           # => [Class, ...]
+    #   StandardAudit::Operation::Audit.unknown_actions      # => { Class => ["x.y"] }
+    #   StandardAudit::Operation::Audit.orphan_actions       # => ["x.y"]
+    #   StandardAudit::Operation::Audit.missing_write_sites  # => [Class, ...]
+    module Audit
+      # Heuristic used by the source-scanning predicates: a call to the private
+      # `audit!` helper, with or without parentheses, not preceded by a receiver
+      # (so `foo.audit!` and `Something::audit!` don't count).
+      #
+      # The scan is FILE-scoped, not class-scoped — two operations defined in
+      # one file share a verdict. Zeitwerk requires one class per file in a
+      # real app, so this only matters for fixtures.
+      #
+      # Comments are stripped before scanning (see .strip_comments), so a
+      # documented or commented-out `audit!` is not a write site. Until 0.9.1
+      # it was, and the docstring here claimed the predicates "err towards a
+      # false pass rather than a false failure" — which was only ever true of
+      # {.missing_write_sites}. In the {.unexpected_write_sites} direction the
+      # same match produces a false FAILURE, so an `audit_none!` class that
+      # explained itself in prose failed the check. The claim was wrong for
+      # half its own surface, which is worse than the bug: it told anyone
+      # hitting the failure not to suspect the scanner.
+      #
+      # What remains genuinely heuristic: a string literal containing `audit!`
+      # still counts, and the runtime guard is still the authoritative check.
+      WRITE_SITE_PATTERN = /(?<![\w.:])audit!\s*(?:\(|["':@$\w])/
+
+      class << self
+        # ── Registry ────────────────────────────────────────────────────────
+
+        # Every class that has gained the contract, in registration order.
+        # Includes bases, intermediates, and anonymous classes — use
+        # {.operations} for the filtered view a meta-spec should assert on.
+        def registered
+          @registered ||= []
+        end
+
+        def register(klass)
+          registered << klass unless registered.include?(klass)
+          klass
+        end
+
+        # Empties the registry. For the gem's own specs and for hosts that
+        # rebuild the constant graph mid-suite; a normal suite never needs it.
+        def reset_registry!
+          @registered = []
+        end
+
+        # The real operations a meta-spec should hold to the contract.
+        #
+        # Excluded:
+        #   - anonymous classes (no name) — test doubles and `Class.new` fixtures
+        #   - classes that declared `audit_abstract!`
+        #   - classes that declare NOTHING and have subclasses — i.e. a shared
+        #     base such as `ApplicationOperation`. This is what lets an app
+        #     adopt the whole contract with one `include` on its base class and
+        #     no further configuration. A class that DID declare is never
+        #     excluded by this rule, even if it is subclassed, so subclassing a
+        #     real operation cannot quietly drop it from the check.
+        #
+        # @param source [String, nil] keep only classes whose defining file path
+        #   contains this fragment, e.g. `"/app/operations/"`. Recommended: it
+        #   scopes the check to the host's own operations and drops anything
+        #   defined in a spec file.
+        def operations(source: nil)
+          registered.select do |klass|
+            next false if klass.name.nil? || klass.name.empty?
+            next false if klass.audit_spec == :abstract
+            next false if klass.audit_spec.nil? && subclassed?(klass)
+            next true if source.nil?
+
+            source_path(klass)&.include?(source)
+          end
+        end
+
+        # Absolute path of the file that defines `klass`, or nil.
+        def source_path(klass)
+          return nil if klass.name.nil? || klass.name.empty?
+
+          Object.const_source_location(klass.name)&.first
+        rescue NameError
+          nil
+        end
+
+        # ── Catalogue ───────────────────────────────────────────────────────
+
+        # The host's action vocabulary as an Array of Strings, or nil when no
+        # catalogue is configured (in which case membership is not checked).
+        #
+        # `config.audit_catalogue` is normally a callable — see the note in
+        # StandardAudit::Operation on why an eagerly-referenced autoloadable
+        # constant breaks Zeitwerk reloading. A plain Array is accepted for the
+        # case where the vocabulary really is a frozen literal.
+        def catalogue
+          raw = StandardAudit.config.audit_catalogue
+          return nil if raw.nil?
+
+          resolved = raw.respond_to?(:call) ? raw.call : raw
+          return nil if resolved.nil?
+
+          Array(resolved).map(&:to_s)
+        end
+
+        # ── Policy ──────────────────────────────────────────────────────────
+
+        # Whether `audit!` verifies declarations before writing. Defaults to
+        # "local environments only" — production writes silently, because a
+        # developer's declaration mistake must not 500 a user.
+        def verify?
+          resolver = StandardAudit.config.verify_audit_declarations
+          resolver.respond_to?(:call) ? !!resolver.call : !!resolver
+        end
+
+        # Applies the configured policy to a failed audit *write* (never to a
+        # DeclarationError, which `audit!` re-raises first).
+        #
+        # @return [nil] when the error is swallowed
+        # @raise [StandardError] the original error when
+        #   `config.raise_on_audit_write_error` is true
+        def handle_write_error(error, action:, operation:)
+          raising = StandardAudit.config.raise_on_audit_write_error
+          handler = StandardAudit.config.audit_write_error_handler
+
+          if handler
+            handler.call(error, action: action, operation: operation)
+          elsif !raising
+            # Deliberately NOT reported when re-raising: the caller receives the
+            # error and owns it from here. Reporting as well produced two events
+            # for one failure in every host that both sets
+            # `raise_on_audit_write_error` and reports on the error it catches —
+            # which is most hosts that set the flag at all, since the flag exists
+            # for hosts that treat an unaudited write as a failure worth
+            # handling. And a host that does NOT catch it still gets the report,
+            # via its framework's own unhandled-error path.
+            report_write_error(error, action: action, operation: operation)
+          end
+
+          raise error if raising
+
+          nil
+        end
+
+        # ── Predicates ──────────────────────────────────────────────────────
+
+        # Operations that declare neither `audits` nor `audit_none!`. A new
+        # mutating operation shipping with no audit trail shows up here.
+        #
+        # @return [Array<Class>]
+        def undeclared(operations: self.operations)
+          operations.select { |klass| klass.audit_spec.nil? }
+        end
+
+        # Declared actions that are absent from the configured catalogue.
+        # Empty when no catalogue is configured.
+        #
+        # @return [Hash{Class => Array<String>}]
+        def unknown_actions(operations: self.operations, catalogue: self.catalogue)
+          return {} if catalogue.nil?
+
+          operations.each_with_object({}) do |klass, acc|
+            unknown = declared_for(klass) - catalogue
+            acc[klass] = unknown if unknown.any?
+          end
+        end
+
+        # Catalogue entries no operation declares — dead vocabulary, which makes
+        # the catalogue a wish rather than a record.
+        #
+        # @param within [Array<String>, nil] check only this slice. Hosts whose
+        #   catalogue also covers non-operation writers (a controller concern, a
+        #   tool server, a notification-bus name) pass the operation-only slice
+        #   here; the rest are written outside `app/operations/` and would
+        #   always look orphaned.
+        # @return [Array<String>]
+        def orphan_actions(operations: self.operations, catalogue: self.catalogue, within: nil)
+          pool = within ? Array(within).map(&:to_s) : catalogue
+          return [] if pool.nil?
+
+          pool - declared_actions(operations: operations)
+        end
+
+        # Every action declared across the given operations, de-duplicated.
+        #
+        # @return [Array<String>]
+        def declared_actions(operations: self.operations)
+          operations.flat_map { |klass| declared_for(klass) }.uniq
+        end
+
+        # Catalogue entries listed more than once.
+        #
+        # @return [Array<String>]
+        def duplicate_catalogue_entries(catalogue: self.catalogue)
+          return [] if catalogue.nil?
+
+          catalogue.tally.select { |_action, count| count > 1 }.keys
+        end
+
+        # Operations that declare `audits` but whose source contains no `audit!`
+        # call — the declaration is aspirational and nothing writes the row.
+        #
+        # Source-based, therefore a heuristic: a class whose defining file can't
+        # be read is skipped rather than reported.
+        #
+        # @return [Array<Class>]
+        def missing_write_sites(operations: self.operations)
+          operations.select do |klass|
+            spec = klass.audit_spec
+            next false unless spec.is_a?(Array)
+
+            src = source_for(klass)
+            src && !src.match?(WRITE_SITE_PATTERN)
+          end
+        end
+
+        # Operations that declare `audit_none!` but whose source calls `audit!`
+        # anyway. The runtime guard catches this too, but only if that code path
+        # is exercised; this catches it statically.
+        #
+        # @return [Array<Class>]
+        def unexpected_write_sites(operations: self.operations)
+          operations.select do |klass|
+            next false unless klass.audit_spec == :none
+
+            src = source_for(klass)
+            src&.match?(WRITE_SITE_PATTERN)
+          end
+        end
+
+        private
+
+        def declared_for(klass)
+          spec = klass.audit_spec
+          spec.is_a?(Array) ? spec : []
+        end
+
+        def source_for(klass)
+          path = source_path(klass)
+          return nil unless path && File.exist?(path)
+
+          strip_comments(File.read(path))
+        end
+
+        # Comments are not write sites. Scanning raw source made a class that
+        # declares `audit_none!` and *explains why* in prose ("No direct audit!
+        # here") fail `unexpected_write_sites` — the scanner matched the word in
+        # the comment. That is a false failure, and it forced hosts to backtick
+        # the token in their own comments to appease a static check.
+        #
+        # Lexing rather than regex-stripping `#` to end-of-line, because the
+        # naive form eats `"#{interpolation}"` and `%w[#]`, which would trade a
+        # false failure for a false pass. A file Ripper cannot lex (syntax the
+        # running Ruby doesn't accept) falls back to the raw source: the old
+        # behaviour, which is conservative in the `audits` direction.
+        def strip_comments(src)
+          tokens = Ripper.lex(src)
+          return src if tokens.nil?
+
+          tokens.reject { |(_pos, type, _tok, _state)| type == :on_comment }
+                .map { |(_pos, _type, tok, _state)| tok }
+                .join
+        rescue StandardError
+          src
+        end
+
+        def subclassed?(klass)
+          klass.respond_to?(:subclasses) && klass.subclasses.any?
+        end
+
+        def report_write_error(error, action:, operation:)
+          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(
+            error,
+            handled: true,
+            context: { StandardAudit.config.audit_error_context_key => action,
+                       operation: operation.class.name }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/standard_audit/operation.rb

@@ -0,0 +1,205 @@
+require "active_support/concern"
+require "standard_audit/operation/audit"
+
+module StandardAudit
+  # Operation-level audit contract, extracted from five independent copies of
+  # the same DSL (fundbright-web, jumpdrive-web, luminality-web, nutripod-web,
+  # sidekick-web).
+  #
+  # It is a MODULE, never a base class. The five host `ApplicationOperation`
+  # classes range from 61 to 303 lines and diverge deliberately — one of them
+  # explicitly refuses a `Result`/`execute` lifecycle, and one app has no shared
+  # operation base at all. This module contributes the audit contract and
+  # nothing else: no lifecycle, no `call`, no `Result`.
+  #
+  # It gives an including class:
+  #
+  #   - a class-level declaration of audit intent — `audits "x.y"` (it records
+  #     one or more audit events), `audit_none!` (it intentionally records
+  #     none), or `audit_abstract!` (it is a base/intermediate class, not a real
+  #     operation). The declaration is meant to be MANDATORY, enforced by the
+  #     host's meta-spec — see StandardAudit::Operation::Audit and
+  #     `standard_audit/rspec/operation`.
+  #
+  #   - a single private instance-level write path, `audit!(action, **attrs)`,
+  #     which verifies the declaration (dev/test only) and then writes through
+  #     StandardAudit.record.
+  #
+  # ── ADOPTION SHAPES ─────────────────────────────────────────────────────────
+  # Both shapes found in the estate work with no host configuration:
+  #
+  #   1. A shared base includes the module once, and the real operations are its
+  #      subclasses. `inherited` registers them. The base itself is excluded
+  #      from `Audit.operations` automatically because it declares nothing and
+  #      has subclasses.
+  #
+  #   2. Every operation is a leaf that includes the module directly (no shared
+  #      base). `included` registers each one.
+  #
+  # ── ERROR POLICY ────────────────────────────────────────────────────────────
+  # `DeclarationError` ALWAYS propagates — it is a developer mistake caught in
+  # dev/test, and letting it decay into a swallowed write or a failure Result
+  # would hide drift from CI.
+  #
+  # A genuine *write* failure is governed by `config.raise_on_audit_write_error`
+  # (default `false`, i.e. report and swallow). One of the five apps
+  # deliberately lets a failed audit write abort the operation, because for it
+  # an unaudited state change is a compliance failure; it sets the flag to
+  # `true`. A swallow-only module would have silently downgraded that posture,
+  # which is why this is configurable rather than fixed.
+  #
+  # ── CATALOGUE ───────────────────────────────────────────────────────────────
+  # The gem has no knowledge of any host's action vocabulary. The host declares
+  # it:
+  #
+  #   StandardAudit.configure(baseline: true) do |config|
+  #     config.audit_catalogue = -> { AuditCatalogue::ACTIONS }
+  #   end
+  #
+  # A CALLABLE, because referencing an autoloadable constant eagerly from an
+  # initializer pins the first-loaded copy and breaks Zeitwerk reloading. `nil`
+  # (the default) means the catalogue check is skipped entirely, so the DSL is
+  # adoptable before an app has a catalogue.
+  #
+  # Membership is the ONLY rule applied to an action string. There is
+  # deliberately no dot-count, case, prefix, or namespace validation: one app's
+  # catalogue carries notification-bus names verbatim
+  # (`jumpdrive-web.surface.audience_changed`) because the subscriber records
+  # the bus name as-is, and normalising them would orphan historical rows.
+  module Operation
+    extend ActiveSupport::Concern
+
+    # Raised when an operation writes an audit action it didn't declare, wrote
+    # despite `audit_none!`, or wrote an action absent from the configured
+    # catalogue. Raised in dev/test only (see `config.verify_audit_declarations`)
+    # and never rescued by this module.
+    class DeclarationError < StandardError; end
+
+    included do |base|
+      StandardAudit::Operation::Audit.register(base)
+    end
+
+    module ClassMethods
+      # Subclasses of an adopting base class are the real operations, so they
+      # register too — and they do NOT inherit `@audit_spec`, by design: each
+      # leaf states its own intent. A leaf reading `nil` through a declared
+      # parent would be the wrong (and silently passing) answer.
+      def inherited(subclass)
+        super
+        StandardAudit::Operation::Audit.register(subclass)
+      end
+
+      # The audit action(s) this operation is expected to emit.
+      #
+      # @return [nil, :none, :abstract, Array<String>]
+      #   `nil` — undeclared (the meta-spec forbids this)
+      #   `:none` — intentionally records no audit
+      #   `:abstract` — not a real operation; excluded from the meta-spec
+      #   Array — the catalogue action strings it may write
+      def audit_spec
+        @audit_spec
+      end
+
+      # Declare the audit action(s) this operation emits (primary first; an
+      # operation may emit several — conditional or per-item — and all must be
+      # listed). The matching write happens via #audit! inside the operation.
+      #
+      #   audits "order.created"
+      #   audits "order.created", "order.line_item_added"
+      #
+      # Values are coerced to Strings, so Symbols and frozen catalogue
+      # constants both work. Calling it twice REPLACES the declaration.
+      def audits(*actions)
+        actions = actions.flatten.map(&:to_s)
+        raise ArgumentError, "`audits` needs at least one action" if actions.empty?
+
+        @audit_spec = actions
+      end
+
+      # Declare that this operation mutates state but intentionally records no
+      # audit. The accepted reasons, all of which should be left as a comment
+      # on the call: delegators that audit downstream, projections/re-indexes
+      # derived from already-audited state, outcome-only writes on a record
+      # whose creation is already audited, and high-volume telemetry ingestion.
+      def audit_none!
+        @audit_spec = :none
+      end
+
+      # Declare that this class is a base or intermediate class rather than a
+      # real operation, so the meta-spec skips it.
+      #
+      # Usually unnecessary: a class that declares nothing and HAS subclasses is
+      # treated as a base automatically, which is what makes a one-line
+      # `include StandardAudit::Operation` on a shared `ApplicationOperation`
+      # work with no further configuration. Use this when the automatic rule is
+      # not enough — most often an intermediate class that has no subclasses
+      # *yet*, or one you want to state the intent of explicitly.
+      def audit_abstract!
+        @audit_spec = :abstract
+      end
+    end
+
+    private
+
+    # The single audit-write path for operations.
+    #
+    # Call it INSIDE the operation's own transaction where one is open, so the
+    # audit row commits atomically with the state change — this helper opens no
+    # transaction of its own. `action` is the StandardAudit `event_type`;
+    # keyword args are forwarded straight to StandardAudit.record, so `actor:` /
+    # `target:` / `scope:` must be model objects (the gem records their
+    # GlobalID), alongside `metadata:` and context overrides such as
+    # `ip_address:`.
+    #
+    # `actor:` defaults to whatever `config.current_actor_resolver` returns, so
+    # only operations acting on someone else's behalf need to pass it.
+    #
+    # In dev/test it raises DeclarationError on declaration↔write drift. In
+    # production it just writes: a developer mistake shouldn't 500 a user, and
+    # the meta-spec is the CI gate.
+    #
+    # @return [StandardAudit::AuditLog, nil]
+    def audit!(action, **attrs)
+      action = action.to_s
+      verify_audit_declared!(action) if StandardAudit::Operation::Audit.verify?
+
+      StandardAudit.record(action, **attrs)
+    rescue DeclarationError
+      # Always propagate a declaration mismatch, ahead of the generic rescue
+      # below and regardless of `raise_on_audit_write_error`. It can only be
+      # raised when verification is on (dev/test).
+      raise
+    rescue StandardError => e
+      StandardAudit::Operation::Audit.handle_write_error(e, action: action, operation: self)
+    end
+
+    # Raises DeclarationError when `action` contradicts the class's declaration
+    # or is absent from the configured catalogue. Public-ish by convention (it
+    # is private, like `audit!`) but documented because host meta-specs assert
+    # on its messages.
+    def verify_audit_declared!(action)
+      catalogue = StandardAudit::Operation::Audit.catalogue
+
+      case (spec = self.class.audit_spec)
+      when nil
+        raise DeclarationError,
+          "#{self.class} writes audit '#{action}' but declares neither `audits` nor `audit_none!`"
+      when :none
+        raise DeclarationError,
+          "#{self.class} declares `audit_none!` but writes audit '#{action}'"
+      when :abstract
+        raise DeclarationError,
+          "#{self.class} declares `audit_abstract!` but writes audit '#{action}'"
+      else
+        unless spec.include?(action)
+          raise DeclarationError,
+            "#{self.class} writes audit '#{action}' not in its declared actions #{spec.inspect}"
+        end
+        if catalogue && !catalogue.include?(action)
+          raise DeclarationError,
+            "audit action '#{action}' is not in the configured audit catalogue"
+        end
+      end
+    end
+  end
+end

data/lib/standard_audit/rspec/operation.rb

@@ -0,0 +1,136 @@
+require "standard_audit"
+
+# RSpec shared examples for the operation-audit contract.
+#
+# A THIN layer over StandardAudit::Operation::Audit — every example below is a
+# one-line call to a plain-Ruby predicate plus a failure message. If the shape
+# of these examples doesn't fit your app, call the predicates directly from a
+# bespoke spec and skip this file; nothing here is load-bearing.
+#
+#   require "standard_audit/rspec/operation"
+#
+#   RSpec.describe "Operation audit declarations" do
+#     it_behaves_like "standard_audit operation declarations",
+#       source:         "/app/operations/",
+#       minimum:        100,
+#       orphans_within: -> { AuditCatalogue::OPERATION_ACTIONS }
+#   end
+#
+# Options (all optional):
+#
+#   source:         path fragment scoping the check to your own operations.
+#                   Strongly recommended — without it, any class anywhere that
+#                   includes the module is held to the contract.
+#   minimum:        registry floor. THE MOST IMPORTANT OPTION. Without it, an
+#                   app where someone stopped including the module — or where
+#                   eager loading silently stopped reaching `app/operations/` —
+#                   passes every other example vacuously against an empty set.
+#                   Set it just below your real count.
+#   expected:       Array of class names that must be registered. A second,
+#                   sharper form of the same protection.
+#   orphans_within: the catalogue slice operations are responsible for, as an
+#                   Array or a callable. Use it when your catalogue also covers
+#                   writers outside `app/operations/` (a controller concern, a
+#                   tool server, a notification-bus name), which would otherwise
+#                   always look orphaned. Omit to skip the orphan check;
+#                   pass `:catalogue` to check the whole catalogue.
+#   eager_load:     force `Rails.application.eager_load!` first so the registry
+#                   is complete regardless of the test env's setting.
+#                   Defaults to true.
+RSpec.shared_examples "standard_audit operation declarations" do |options = {}|
+  source         = options[:source]
+  minimum        = options[:minimum]
+  expected       = Array(options[:expected])
+  orphans_within = options[:orphans_within]
+  eager_load     = options.fetch(:eager_load, true)
+
+  audit = StandardAudit::Operation::Audit
+
+  before(:all) do
+    Rails.application.eager_load! if eager_load && defined?(Rails) && Rails.application
+  end
+
+  let(:operations) { audit.operations(source: source) }
+
+  it "sees the operations it is supposed to check" do
+    if expected.any?
+      expect(operations.map(&:name)).to include(*expected)
+    end
+
+    if minimum
+      expect(operations.size).to be >= minimum,
+        "Expected at least #{minimum} registered operations#{source ? " under #{source}" : ""}, " \
+        "found #{operations.size}. Every other example in this group passes vacuously against " \
+        "an empty set, so this is almost certainly a wiring failure — an operation that stopped " \
+        "including StandardAudit::Operation, or eager loading no longer reaching them."
+    end
+
+    skip("no `minimum:` or `expected:` given — nothing to assert") if minimum.nil? && expected.empty?
+  end
+
+  it "requires every operation to declare `audits` or `audit_none!`" do
+    undeclared = audit.undeclared(operations: operations)
+
+    expect(undeclared).to be_empty,
+      "These operations declare neither `audits` nor `audit_none!`:\n  " \
+      "#{undeclared.map(&:name).sort.join("\n  ")}\n" \
+      "Add `audits \"some.action\"` if it records an audit, or `audit_none!` " \
+      "(with the reason in a comment) if it deliberately doesn't."
+  end
+
+  it "only declares actions present in the audit catalogue" do
+    unknown = audit.unknown_actions(operations: operations)
+
+    skip("no `config.audit_catalogue` configured") if audit.catalogue.nil?
+
+    expect(unknown).to be_empty,
+      "These operations declare audit actions missing from the catalogue " \
+      "(add them to it):\n  " \
+      "#{unknown.map { |klass, actions| "#{klass.name}: #{actions.inspect}" }.join("\n  ")}"
+  end
+
+  it "has no duplicate catalogue entries" do
+    skip("no `config.audit_catalogue` configured") if audit.catalogue.nil?
+
+    dupes = audit.duplicate_catalogue_entries
+
+    expect(dupes).to be_empty, "duplicate audit catalogue entries: #{dupes.inspect}"
+  end
+
+  it "operations that declare `audits` call `audit!`" do
+    missing = audit.missing_write_sites(operations: operations)
+
+    expect(missing).to be_empty,
+      "These operations declare `audits` but never call `audit!`:\n  " \
+      "#{missing.map(&:name).sort.join("\n  ")}"
+  end
+
+  it "operations that declare `audit_none!` do not call `audit!`" do
+    writing = audit.unexpected_write_sites(operations: operations)
+
+    expect(writing).to be_empty,
+      "These operations declare `audit_none!` but call `audit!`:\n  " \
+      "#{writing.map(&:name).sort.join("\n  ")}"
+  end
+
+  it "has no catalogued action that no operation writes" do
+    skip("no `orphans_within:` given") if orphans_within.nil?
+
+    within =
+      if orphans_within == :catalogue
+        nil
+      elsif orphans_within.respond_to?(:call)
+        orphans_within.call
+      else
+        orphans_within
+      end
+
+    skip("no `config.audit_catalogue` configured") if within.nil? && audit.catalogue.nil?
+
+    orphans = audit.orphan_actions(operations: operations, within: within)
+
+    expect(orphans).to be_empty,
+      "These catalogued actions are declared by no operation — wire them or " \
+      "drop them: #{orphans.inspect}"
+  end
+end

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.8.0"
+  VERSION = "0.10.0"
 end

data/lib/standard_audit.rb

@@ -6,6 +6,7 @@ require "standard_audit/sensitive_keys_dry_run"
 require "standard_audit/subscriber"
 require "standard_audit/event_subscriber"
 require "standard_audit/reference_preloading"
+require "standard_audit/operation"
 require "standard_audit/auditable"
 require "standard_audit/audit_scope"
 require "standard_audit/checks/retention"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -112,8 +112,11 @@ files:
 - lib/standard_audit/engine.rb
 - lib/standard_audit/event_subscriber.rb
 - lib/standard_audit/metadata_filter.rb
+- lib/standard_audit/operation.rb
+- lib/standard_audit/operation/audit.rb
 - lib/standard_audit/reference_preloading.rb
 - lib/standard_audit/rspec.rb
+- lib/standard_audit/rspec/operation.rb
 - lib/standard_audit/sensitive_keys_dry_run.rb
 - lib/standard_audit/subscriber.rb
 - lib/standard_audit/version.rb