standard_audit 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55028cd60be7b29a81c8bd0eccb5cbccadfba4f7691f0d6576214de4367e53c9
-  data.tar.gz: efcf7f59f891570b8076e870f64d632de6d707ed9a4aa1f4b6e35aa7116199d1
+  metadata.gz: a1d506a4bb5ad3811dd4a70b6be817374ec9a88ced8d1ffd9415bfddd28cc50b
+  data.tar.gz: 52c8aaa70f86810c6b308c86fa81e10c368ab5ddb011d16f422745e7681c88da
 SHA512:
-  metadata.gz: d1d0c3c3807faf64dc9e21c897da2e3317a6fee1ea202aae6b07a948f416bbb8d35c03f8977a3def8bdf5a2bca9944941e3fe1b3c860d7b2b3aa942a8f048e16
-  data.tar.gz: 16278c66d30fe401947d8748e6b675a9dd5bc49dac1d0183635faf27df8e1b9e5a5f2d933aa8a606c1b66a01894dc030088a3813b7ca8eb2aee68ed7bd811e0d
+  metadata.gz: 2db9ee0ef4983ce2bd9a94d195bbbf973016f32a3e9e2a53b45476df6c9cc6d30f7edd2bfb7e9442d6839e05cc491263b91bb644462946510740c187eb861e29
+  data.tar.gz: cce577cbc3f1b5829429ab30765c451f4a0fdca18b9f6283f075e1b3487b3fb763ceaeca846e39768c53707361bfc87024da65e0f8e662885a47766f814dd5c1

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,9 @@ 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
 
     def initialize
       @subscriptions = []
@@ -78,6 +80,50 @@ 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
+
       # 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,253 @@
+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. A commented-out or
+      # documented `audit!` in the same file also counts as a write site; the
+      # predicates deliberately err towards a false pass rather than a false
+      # failure, since the runtime guard is 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:)
+          handler = StandardAudit.config.audit_write_error_handler
+
+          if handler
+            handler.call(error, action: action, operation: operation)
+          else
+            report_write_error(error, action: action, operation: operation)
+          end
+
+          raise error if StandardAudit.config.raise_on_audit_write_error
+
+          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)
+
+          File.read(path)
+        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: { audit_action: 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.9.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.9.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