statecraft 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1694416ac7a88eff03c4f73c1fab5c0b2d8bd182f7c8d88d72c4eb1da2574ecc
+  data.tar.gz: 4fa98301ac81c1d5b2cee6007048fe05f2ea6db36400cb2d6844d8f19fef9011
+SHA512:
+  metadata.gz: 6cc41535452dc33140e39f342c07488491b595c945538fc71f661e2233d03f2e922a52a3182e6d2022f57c2eed5cc494810126189f280fc532aae973d5eb2f4b
+  data.tar.gz: bc485f03bcee46d53f027d955def314aa7f2836211811dba751c93b2a29eaa8887a944479d2fb62ab62f540aa0e43aca0813c95f115212488e9495f80a8b8f90

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,354 @@
+# statecraft
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+A state machine for ActiveRecord where the current state lives in a column as
+the single source of truth, history is an append-only per-model log with
+write-once metadata, and every transition is guarded by a compare-and-swap
+update inside a savepoint. Event-aware guards, an explicit bypass policy, and
+telemetry for both successes and refusals.
+
+statecraft is an **ActiveRecord gem**, not a Rails gem: its runtime depends on
+`activerecord` and `activesupport` only. Anything that can call
+`ActiveRecord::Base.establish_connection` gets the full pipeline; Rails adds
+the generator as a progressive enhancement.
+
+## Why
+
+- `in_state?` and state scopes are a plain `WHERE` on a column — zero joins,
+  unlike log-derived current state (`most_recent`-style schemas).
+- Concurrency safety comes from a CAS `UPDATE ... WHERE state = :expected`:
+  of N concurrent writers exactly one wins, the rest get a deterministic
+  `Statecraft::TransitionConflict`, and the log records exactly one row.
+- The log carries first-class, write-once `jsonb` metadata: what the guards
+  checked is byte-for-byte what the log stored.
+
+## Installation
+
+```ruby
+gem "statecraft"
+```
+
+Requires Ruby >= 3.3 and ActiveRecord/ActiveSupport >= 7.2, < 9.
+PostgreSQL is the first-class database; SQLite works for development and
+tests (see [SQLite limits](#sqlite-limits)); MySQL is out of scope for v0.
+
+## Quick start
+
+```sh
+bin/rails generate statecraft:machine Order
+```
+
+The generator creates the migration (state column, `state_changed_at`, the
+log table with a cascade FK — and a CHECK constraint when the table is
+freshly created), the machine class, the readonly log model, and mounts the
+machine into the model. By hand it looks like this:
+
+```ruby
+class OrderFlow < ApplicationMachine
+  state :pending, initial: true
+  state :paid
+  state :cancelled
+
+  event :pay, from: :pending, to: :paid, guard: :payable?
+  transition from: :pending, to: :cancelled
+
+  after_commit :enqueue_receipt, event: [:pay]
+
+  private
+
+  def payable?(order, metadata)
+    metadata["amount"].to_i.positive?
+  end
+
+  def enqueue_receipt(order, transition)
+    ReceiptJob.perform_later(order.id, transition.log_record.id)
+  end
+end
+
+class Order < ApplicationRecord
+  state_machine OrderFlow, changed_at: true, helpers: true, scopes: true
+end
+
+order = Order.create!                                # born :pending via the column default
+order.pay!(metadata: { amount: 100, reason: :web }) # => the created OrderTransition row
+order.in_state?(:paid)                               # => true
+Order.paid.count                                     # plain WHERE, zero joins
+```
+
+Mounting options: `log:` (defaults to the `<Model>Transition` convention),
+`column:` (default `:state`), `changed_at:` (off by default; `true` derives
+`<column>_changed_at`), `touch:` (default `true` — `updated_at` is written in
+the same CAS update), `helpers:` and `scopes:` (both off by default; the
+generator turns them on for new code).
+
+## The transition pipeline
+
+`transition_to!` / `fire!` run one strict order:
+
+1. `persisted?` check — transitioning an unsaved record raises
+   `Statecraft::UnsavedRecordError`: initial state comes from the column
+   default, so there is nothing to transition.
+2. Metadata normalization and deep-freeze (see [Metadata](#metadata)).
+3. Edge resolution and the bypass policy check.
+4. Dirty check on `lock: true` edges — unsaved changes raise
+   `Statecraft::DirtyRecordError` instead of being silently destroyed by the
+   reload.
+5. `transaction(requires_new: true)` — a savepoint inside your transaction,
+   a real transaction otherwise: optional `SELECT ... FOR UPDATE` + reload
+   (with edge re-resolution from the fresh state), guards, `before_transition`
+   callbacks, the CAS update (touching `updated_at` and the `changed_at`
+   column in the same statement), the log INSERT, `after_transition`.
+6. `after_commit` callbacks are registered on the outermost real
+   transaction's commit.
+
+A transition is **not** a record save: model validations and model callbacks
+do not run, and unsaved changes on other attributes are neither saved nor
+(without `lock:`) touched. Guards are the transition's validations; machine
+callbacks are the transition's callbacks.
+
+Bang variants return the created log record. Non-bang variants return it too,
+or `false` — and `false` means exactly "a guard said no or the edge is not
+declared" (`GuardFailed` / `InvalidTransition`). Everything else — including
+`TransitionConflict` — always raises, in both variants.
+
+## Guards, events and the bypass policy
+
+A guard is attached to `(from, to, event-or-nil)`: an edge guard always runs,
+an event guard runs only when the transition goes through that event. Within
+one event, `from` is unique — an event is a partial function from state to
+edge, so `fire!` is structurally deterministic. Branching by outcome means
+two events (`pay` and `fail_payment`), not one event with two branches.
+
+Calling `transition_to!` directly over an edge that carries event guards is
+refused — the guards would be silently skipped. The escape hatch is explicit:
+`transition_to!(:paid, bypass_events: true)` skips event guards (edge guards
+still run) and records `event: nil` in the log, so audited bypasses stay
+visible.
+
+## Callbacks and chains
+
+`before_transition`, `after_transition` and `after_commit` accept `from:`,
+`to:` and `event:` filters (arrays welcome). Handlers — symbols resolving to
+machine instance methods, or callables — receive `(record, transition)` where
+`transition` carries `from`, `to`, `event`, `metadata` and (after the INSERT)
+`log_record`.
+
+Launching the next transition from `after_transition` is a supported pattern:
+the chain writes one log row per hop and every `after_commit` waits for the
+outermost commit. Two facts to know:
+
+- **The after-commit order is inverted.** A nested transition registers its
+  `after_commit` before its parent does, so on commit the chain's callbacks
+  run innermost-first (`fulfill` before `pay`). This is documented, tested
+  semantics — do not "fix" it.
+- **The chain depth ceiling is 16.** Deeper nesting raises
+  `Statecraft::ChainDepthExceeded` with the printed chain, which makes an
+  accidental cycle visible at a glance.
+
+Transitioning the *same record* from a guard or from `before_transition`
+raises `Statecraft::NestedTransitionError` immediately — the CAS would
+otherwise reject itself and masquerade as a phantom race. Transitioning from
+`after_commit` is an independent pipeline and is always legal.
+
+## after_commit and transactional tests
+
+`after_commit` follows Active Record transaction-callback semantics
+everywhere, including transactional tests. **Inside your own transaction,
+"the transition succeeded" does not mean "after_commit ran"** — the callback
+waits for the outermost real commit and silently never runs if that
+transaction rolls back, exactly like a model's `after_commit`. In a
+transactional test, `order.pay!` behaves the way `record.save` with a model
+after_commit callback behaves in that same test — one invariant, no special
+cases to learn. Exceptions raised inside `after_commit` propagate as-is: the
+transition is already committed, so they are handler errors, not transition
+errors.
+
+## Concurrency and isolation
+
+The CAS update is the concurrency contract: on the default READ COMMITTED
+isolation a race deterministically produces `TransitionConflict` for every
+loser, with the expected `from` in the error. Rescuing the conflict inside
+your transaction is safe: the savepoint has already rolled back the
+pipeline's effects, your outer work stays intact, and you may retry from the
+fresh state or take another branch.
+
+`lock: true` on an edge or event adds `SELECT ... FOR UPDATE` plus a reload
+before the guards. The row lock lives until your outermost transaction
+commits — releasing the savepoint does not release it.
+
+On stricter isolation levels (SERIALIZABLE) the same race may surface as
+`ActiveRecord::SerializationFailure` before the CAS ever sees it — up to and
+including commit time. statecraft passes the whole
+`ActiveRecord::TransactionRollbackError` family (including `Deadlocked`)
+through untouched: those errors mean "restart the whole transaction", a
+different protocol than the conflict's "continue from clean state", and the
+retry policy belongs to whoever chose the isolation level.
+
+## Introspection
+
+```ruby
+order.can_fire?(:pay, metadata: { amount: 100 })  # would the guards pass right now?
+order.may_pay?(metadata: { amount: 100 })          # alias, with helpers: true
+order.available_events(metadata: { amount: 100 })  # => [:pay]
+order.available_transitions(metadata: {})          # => [#<to: :cancelled, via: [:direct]>]
+order.transitioned_to?(:paid)                      # strictly log-based
+```
+
+`available_transitions` tells you not only *where* you can go but *how*:
+`via` lists the events whose guards pass, plus `:direct` when the edge is
+free of event guards and its edge guards pass. Every answer is a snapshot —
+CAS may still reject the transition a moment later.
+
+A guard that reads metadata makes `may_*?` depend on the metadata you pass.
+For a UI "is this button available" question, either do not hang input
+validation on a guard, or pass the same metadata to `may_*?` that you will
+collect for `fire!`.
+
+## Metadata
+
+Metadata is normalized on pipeline entry with a full JSON round-trip —
+symbol keys and values become strings, times become ISO-8601 strings — and
+then deep-frozen: **the guards see exactly what the log will store**, and a
+guard that mutates metadata dies with `FrozenError` in a transition and in a
+check alike. Unserializable values (a `Proc`, a model instance) fail
+instantly at the entrance, not inside the transaction.
+
+Facts of the transition moment (a price snapshot, a rules version) are
+collected by the caller: `order.pay!(metadata: { price: order.total })`.
+There is no metadata schema mechanism — required fields are enforced by
+guards — and the shape evolves by convention: carry a `v:` key when you need
+versioned readers.
+
+## Initial state is not a transition
+
+Creating a record is not a transition: rows enter the initial state through
+the column default (which also covers `insert_all`, fixtures, seeds and ETL),
+and the log stays silent about births — a consistently silent audit beats an
+inconsistently chatty one.
+
+| Question | Answer |
+|---|---|
+| When did the record enter the initial state? | `created_at` |
+| Has it ever *transitioned to* `:pending`? | `transitioned_to?(:pending)` — `false` until a real transition (a loop or a return counts) |
+| Is it in `:pending` now? | `in_state?(:pending)` / `where(state: :pending)` |
+
+## The log model is a read-model
+
+Scopes, reading methods and serializers on the log class are yours. Writing
+is not: the pipeline inserts rows through the insert path, so validations and
+callbacks declared on the log model never run — guards and machine callbacks
+are the single channel of truth. The generated `readonly?` makes persisted
+rows reject `update!` and `destroy`; it protects against accidental edits,
+not malicious ones (`update_all` and raw SQL still work — the real guarantee
+would be database triggers, which are out of v0). Deleting `readonly?` in
+your generated class is a supported customization.
+
+Deleting the parent record cascades to its log rows at the database level
+(`ON DELETE CASCADE`): an audit without its subject is not an audit. If your
+requirement is "history survives deletion", the answer is soft-deleting the
+record, not an FK mode — and swapping `:cascade` for `:restrict` in your
+generated migration is supported if you disagree.
+
+## Configuration
+
+There is none — deliberately. Every knob lives with its subject: mounting
+options on `state_machine`, `lock:` on edges and events, schema choices in
+your generated migration, `readonly?` in your generated log class. No
+initializer, no `Statecraft.configure`. If a future feature genuinely needs
+process-level configuration it will arrive as a designed decision, not as a
+convenience knob.
+
+## Renaming a state
+
+The log is never migrated: history is written in the words of its time, and
+every reading API handles log rows whose state names are no longer in the
+graph. To rename `:pending` to `:awaiting_payment`, follow the three-phase
+rolling rename recipe on the column:
+
+1. Declare **both** states in the machine with duplicated edges; widen the
+   CHECK constraint to both names (adding a value is cheap).
+2. Batch-`UPDATE` the column. Races are loud by construction: a row
+   repainted under a live transition makes its CAS miss and raise
+   `TransitionConflict` — retry from the new name. For a large table, add
+   the widened constraint as `NOT VALID` first and `VALIDATE CONSTRAINT`
+   after the cleanup.
+3. Drop the old state and its edges; narrow the CHECK back.
+
+## PII and erasure
+
+Metadata is the only place personal data can live — `from_state`, `to_state`
+and `event` never carry it, and telemetry payloads exclude metadata entirely.
+Three layers, in order of preference:
+
+1. **References, not values.** Store `{ user_id: 42 }`, not an email. Erasure
+   then touches the referent, never the log.
+2. **Hard delete.** `destroy` cascades to the log rows for free.
+3. **Soft delete + scrubbing.** Administrative erasure works at the relation
+   level, past `readonly?`:
+   `order.history.where(...).update_all(metadata: { scrubbed_at: Time.current.iso8601 })`.
+   The tombstone convention keeps the audit honest: "there was data here,
+   erased on request" is a legally different statement than "there was
+   nothing".
+
+## STI
+
+Mounting a machine on an STI base class is promised behavior: subclasses
+inherit the machine, helpers and scopes (`CreditOrder.pending` scopes the
+subclass by `type` + `state`, exactly like an enum scope would), CAS and the
+log FK hit the base class's table, and guards receive the actual subclass
+instance. Two honest boundaries: name-conflict checks at mounting cover the
+mounting class only — a subclass method shadowing a generated verb is plain
+Ruby method overriding; and mounting a *different* machine in a subclass is
+the multi-machine feature, out of v0 — it raises `Statecraft::AlreadyMounted`
+at the threshold.
+
+## Multiple databases
+
+The log lives next to its model, always — a cascade FK cannot cross
+databases, so this is a definition, not a restriction. The generated log
+class inherits the model's connection-owning ancestor (base, roles and
+horizontal shards follow automatically), and the generator drops the
+migration into that connection's migration path. Mounting verifies connection
+identity — same pool, same per-thread connection, one real transaction — and
+raises `Statecraft::ConnectionMismatch` with a fix hint otherwise. Two
+`connects_to` blocks pointing at one physical database are still two pools:
+that also fails the check, correctly.
+
+## Outside Rails
+
+No railties at runtime — the hygiene is enforced by a test, not a promise.
+Without the generator, create the schema by hand; the reference shape:
+
+```ruby
+create_table :orders do |t|
+  t.string :state, null: false, default: "pending", index: true
+  t.datetime :state_changed_at
+  t.timestamps null: false
+end
+add_check_constraint :orders, "state IN ('pending')", name: "orders_state_check"
+
+create_table :order_transitions do |t|
+  t.references :order, null: false,
+                       foreign_key: { on_delete: :cascade }, index: false
+  t.string :from_state, null: false
+  t.string :to_state, null: false
+  t.string :event
+  t.jsonb :metadata, null: false, default: {}
+  t.datetime :created_at, null: false
+  t.index %i[order_id id]
+end
+```
+
+## SQLite limits
+
+SQLite is a development and test database: `metadata` falls back to
+`json`/text, concurrency specs skip (the concurrency proof runs on
+PostgreSQL in CI), and `lock: true` degrades the way ActiveRecord itself
+degrades — the locking clause is dropped, the reload still runs, and
+statecraft warns once per machine per process that row-locking guarantees
+require PostgreSQL.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/generators/statecraft/machine/machine_generator.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Statecraft
+  module Generators
+    # `rails generate statecraft:machine Order` — the single statecraft
+    # generator. Creates the migration (state column, optional changed_at,
+    # the per-model log table with a cascade FK and a CHECK constraint for a
+    # freshly created table), the machine class, the readonly log model, the
+    # model mounting with helpers and scopes on, and lazily the shared
+    # ApplicationMachine parent. The migration lands in the migration path of
+    # the model's connection owner, so multi-database apps get it next to
+    # their model.
+    class MachineGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def detect_model_presence
+        @existing_model = File.exist?(File.join(destination_root, "app/models/#{file_name}.rb"))
+      end
+
+      def create_application_machine
+        application_machine_path = "app/state_machines/application_machine.rb"
+        return if File.exist?(File.join(destination_root, application_machine_path))
+
+        template "application_machine.rb.tt", application_machine_path
+      end
+
+      def create_machine_class
+        template "machine.rb.tt", "app/state_machines/#{file_name}_flow.rb"
+      end
+
+      def create_log_model
+        template "log_model.rb.tt", "app/models/#{file_name}_transition.rb"
+      end
+
+      def create_or_mount_model
+        if existing_model?
+          inject_into_class "app/models/#{file_name}.rb", class_name, mounting_line
+        else
+          template "model.rb.tt", "app/models/#{file_name}.rb"
+        end
+      end
+
+      def create_migration_file
+        migration_source = existing_model? ? "add_migration.rb.tt" : "create_migration.rb.tt"
+        migration_template migration_source,
+                           "#{migration_directory}/create_#{file_name}_state_machine.rb"
+      end
+
+      private
+
+      def existing_model?
+        @existing_model
+      end
+
+      def mounting_line
+        "  state_machine #{class_name}Flow, changed_at: true, helpers: true, scopes: true\n"
+      end
+
+      def migration_directory
+        specification_name = model_connection_specification_name
+        return "db/migrate" if specification_name.nil? || specification_name == "ActiveRecord::Base"
+
+        "db/#{specification_name.underscore.tr("/", "_")}_migrate"
+      end
+
+      def model_connection_specification_name
+        model_class = class_name.safe_constantize
+        model_class&.connection_specification_name
+      rescue StandardError
+        nil
+      end
+
+      def log_table_name
+        "#{table_name.singularize}_transitions"
+      end
+
+      def parent_class_name
+        specification_name = model_connection_specification_name
+        return "ApplicationRecord" if specification_name.nil? || specification_name == "ActiveRecord::Base"
+
+        specification_name
+      end
+
+      def foreign_key_column
+        "#{file_name}_id"
+      end
+
+      def migration_class_name
+        "Create#{class_name}StateMachine"
+      end
+
+      def metadata_column_type
+        adapter = ActiveRecord::Base.connection.adapter_name
+        adapter.match?(/postg/i) ? "jsonb" : "json"
+      rescue ActiveRecord::ActiveRecordError
+        "jsonb"
+      end
+    end
+  end
+end

data/lib/statecraft/errors.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Statecraft
+  class Error < StandardError; end
+
+  class CompilationError < Error; end
+
+  class GuardFailed < Error
+    attr_reader :record, :guard, :from, :to, :event
+
+    def initialize(record:, guard:, from:, to:, event:)
+      @record = record
+      @guard = guard
+      @from = from
+      @to = to
+      @event = event
+      via = event ? " (event #{event})" : nil
+      super("guard #{guard.inspect} failed for #{record.class.name}##{record.id} " \
+            "on #{from} -> #{to}#{via}")
+    end
+  end
+
+  class InvalidTransition < Error
+    attr_reader :record, :from, :requested, :allowed
+
+    def initialize(record:, from:, requested:, allowed:, message: nil)
+      @record = record
+      @from = from
+      @requested = requested
+      @allowed = allowed
+      default_message = "transition #{from} -> #{requested} is not declared for " \
+                        "#{record.class.name}; allowed from #{from}: " \
+                        "#{allowed.empty? ? "none" : allowed.join(", ")}"
+      super(message || default_message)
+    end
+  end
+
+  class TransitionConflict < Error
+    attr_reader :record, :expected_from
+
+    def initialize(record:, expected_from:)
+      @record = record
+      @expected_from = expected_from
+      super("concurrent update detected for #{record.class.name}##{record.id}: " \
+            "expected state #{expected_from.inspect}, another writer got there first")
+    end
+  end
+
+  class UnsavedRecordError < Error
+    attr_reader :record
+
+    def initialize(record:)
+      @record = record
+      super("cannot transition an unsaved #{record.class.name}: save the record first; " \
+            "initial state comes from the column default")
+    end
+  end
+
+  class DirtyRecordError < Error
+    attr_reader :record, :changed_attributes
+
+    def initialize(record:, changed_attributes:)
+      @record = record
+      @changed_attributes = changed_attributes
+      super("cannot lock-transition #{record.class.name}##{record.id} with unsaved changes " \
+            "(#{changed_attributes.join(", ")}): save or reload before transitioning")
+    end
+  end
+
+  class NestedTransitionError < Error
+    attr_reader :record
+
+    def initialize(record:)
+      @record = record
+      super("transition initiated from before_transition or a guard of another transition " \
+            "on #{record.class.name}##{record.id}; move it to after_transition or outside")
+    end
+  end
+
+  class ChainDepthExceeded < Error
+    attr_reader :chain
+
+    def initialize(chain:)
+      @chain = chain
+      super("transition chain exceeded depth #{chain.length}: #{chain.join(" -> ")}")
+    end
+  end
+
+  class AlreadyMounted < Error
+    attr_reader :model
+
+    def initialize(model:)
+      @model = model
+      super("#{model.name} already carries a state machine; inheritance shares the base " \
+            "machine, and per-subclass machines are out of v0")
+    end
+  end
+
+  class CompositePrimaryKeyUnsupported < Error
+    attr_reader :model
+
+    def initialize(model:)
+      @model = model
+      super("#{model.name} uses a composite primary key; statecraft v0 supports " \
+            "single-column primary keys only")
+    end
+  end
+
+  class ConnectionMismatch < Error
+    attr_reader :model, :log_class
+
+    def initialize(model:, log_class:)
+      @model = model
+      @log_class = log_class
+      super("#{log_class.name} does not share #{model.name}'s connection " \
+            "(#{log_class.connection_specification_name} vs #{model.connection_specification_name}); " \
+            "make the log model inherit from the model's connection-owning ancestor")
+    end
+  end
+end

data/lib/statecraft/instrumentation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Statecraft
+  # Publishes the two ActiveSupport::Notifications events of the pipeline.
+  # Success and refusal need different event names, so timing is measured
+  # manually and published with explicit start/finish instead of a naive
+  # instrument block. Metadata never enters a payload: subscribers routinely
+  # log payloads whole, and metadata is the one place PII can live — whoever
+  # needs it reads the log record. Refusal events are published after the
+  # savepoint rollback, outside the transaction, so a subscriber writing to
+  # the database is never rolled back together with the pipeline.
+  module Instrumentation
+    TRANSITION_EVENT = "transition.statecraft"
+    FAILURE_EVENT = "transition_failed.statecraft"
+
+    def self.publish_transition(started_at:, record:, machine_class:, log_record:)
+      publish(
+        TRANSITION_EVENT, started_at,
+        record_class: record.class.base_class.name,
+        record_id: record.id,
+        machine: machine_class.name,
+        from: log_record.from_state.to_sym,
+        to: log_record.to_state.to_sym,
+        event: log_record.event&.to_sym
+      )
+    end
+
+    def self.publish_failure(started_at:, record:, machine_class:, reason:, details:)
+      publish(
+        FAILURE_EVENT, started_at,
+        {
+          record_class: record.class.base_class.name,
+          record_id: record.id,
+          machine: machine_class.name,
+          reason: reason
+        }.merge(details)
+      )
+    end
+
+    def self.publish(event_name, started_at, payload)
+      ActiveSupport::Notifications.publish(
+        event_name, started_at, Time.current, "statecraft", payload
+      )
+    end
+    private_class_method :publish
+  end
+end