statecraft 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f62004e4153d3351bda79f2cf1f09db95e42b83302d016909cbe7d8d081ef3ba
-  data.tar.gz: e005456aca83c931019db903ff6a860efff9111da2de5bbe35fe7021192e1f28
+  metadata.gz: 4689cea0dee40236473975f52ea5ccd2ecd303783edebd7626ab1518a1f8c8bd
+  data.tar.gz: b3713ea5d55ea4881b55b10ceccb38847f2f85aa971d29326fd26e97412d0620
 SHA512:
-  metadata.gz: 8c8bd36f37d3c0392cfc4c17562f071f66e8e3252253e2237bc84283418dea222db32327e30aab4f3cd10b408e37852f6cddf3f93171a026194f1a6787f26c83
-  data.tar.gz: f1a14781c925c5bc72da7e7120fc8e1e0a4809b17f36f03f8e55b72e6a8a1163056b730804bb871d0961d1139428bd1084cffa5437f03847674e1dd49c989c9d
+  metadata.gz: 9690fff2fb62feaaea147a53c63113a77dc93103432ad3f5aa63b5593173d513d2abf83d5d53decf0d6eed7347d94509197f5bb0d03077cdbd5a98f1f20cefd4
+  data.tar.gz: cbd7e8d84af570a4c2cb1e51582262860b2d6d0cd7d87ed0304528413ca1d34720dbe6c9b4186fab5a68639c6814243ed2fed32f9774d4985a5f4f5408b45ede

data/README.md

@@ -260,6 +260,51 @@ belong to the application's presentation layer, not to the machine.
 A guard that reads metadata makes `may_*?` depend on the metadata you pass —
 pass the same metadata to `may_*?` that you will collect for `fire!`.
 
+## RSpec matchers
+
+One opt-in require gives your specs matchers over the whole introspection
+surface — RSpec never becomes a runtime dependency of the gem:
+
+<!-- illustrative -->
+```ruby
+# spec_helper.rb, after rspec itself is loaded
+require "statecraft/rspec"
+```
+
+<!-- illustrative -->
+```ruby
+# The record-level questions consult the guards, with the same metadata
+# your production call will carry:
+expect(order).to allow_event(:pay).with_metadata("amount" => 100)
+expect(order).to allow_transition_to(:cancelled).via(:cancel)
+expect(order).to allow_transition_to(:archived).directly
+expect(order).to have_transitioned_to(:paid)  # strictly log-based
+
+# The refusal with its reason — guard names come from refusals_for:
+expect(order).to refuse_event(:cancel).because_of(:customer_cancellable?)
+
+# The class-level pair answers the graph's shape; guards stay untouched:
+expect(OrderFlow).to have_edge(:pending, :cancelled).via(:cancel)
+expect(OrderFlow).to have_initial_state(:pending)
+
+# The transition itself: the state move AND the appended log row,
+# asserted in one expression around fire!/transition_to!:
+expect { order.fire!(:pay, metadata: { "amount" => 100 }) }
+  .to transition(order).from(:pending).to(:paid)
+      .via_event(:pay).with_metadata("amount" => 100)
+```
+
+A failing matcher explains itself with the same introspection the pipeline
+consults: the current state, the edges reachable from it, and the refusing
+guard with its layer. A non-bang call that returned `false` fails the
+`transition` matcher the same way; exceptions of the bang forms fly through
+like with `change` — assert refusals with `refuse_event` or `raise_error`,
+not with the block matcher.
+
+`because_of` carries the same honest limit as `refusals_for` underneath it:
+it names record-layer guards only. An input-reading `guard:` has no name
+there, and the failure message says so instead of guessing.
+
 ## Metadata
 
 Metadata is normalized on pipeline entry with a full JSON round-trip —
@@ -351,38 +396,48 @@ bin/rails generate statecraft:from_statesman Order
 The generator reads the live statesman machine through reflection (pass the
 class as a second argument when it is not `OrderStateMachine`; point at the
 class that declares the DSL — statesman graphs are not inherited) and writes
-three things: the conversion migration, a machine skeleton, and the
-`state_machine` mounting line. Two things it honestly cannot write: statesman
-has no events, so every edge arrives as a bare `transition` for you to name,
-and guard bodies are anonymous blocks — each becomes a TODO comment carrying
-the original `file:line`.
-
-The migration converts in this order:
-
-1. The model gains its `state` column, backfilled from the **last transition
-   by `sort_key`** — deliberately not `most_recent`, which drifts out of sync
-   often enough that statesman ships a repair task for it. Rows with no
-   transitions get the initial state; a CHECK constraint pins the value set.
-2. The transitions table gains `from_state` (a `LAG` window along the
-   `sort_key` chain, the first hop starting from the initial state) and a
-   nullable `event` — imported history reads as direct transitions, which is
-   the honest description of what statesman recorded.
-3. A text `metadata` column becomes native json(b) in one indivisible move
-   with removing `serialize` from the model: neither library works in the
-   half-converted state, so the type change and the code change ship
-   together.
-4. The foreign key is re-created with `ON DELETE CASCADE` (statesman's
-   default one carries no action), statesman's unique indexes go, and the
-   `[foreign_key, id]` index that serves statecraft's history reads arrives.
-5. `sort_key`, `most_recent` and `updated_at` are dropped last — the first
-   two would break the log INSERT outright, being NOT NULL without defaults.
-
-The migration's header names two pre-flight checks on live data — that the
-id order agrees with the `sort_key` order (statecraft reads history by id),
-and that a text `metadata` column holds valid JSON in every row (rows written
-by raw SQL may not survive the cast). Run both before migrating.
-
-After the migration, finish by hand (the generator prints this list): drop
+three conversion migrations, a machine skeleton, and the `state_machine`
+mounting line. Two things it honestly cannot write: statesman has no events,
+so every edge arrives as a bare `transition` for you to name, and guard
+bodies are anonymous blocks — each becomes a TODO comment carrying the
+original `file:line`.
+
+Three migrations, because the obvious single one is a production incident:
+`add_column` takes an ACCESS EXCLUSIVE lock that PostgreSQL holds until the
+**end of the transaction**, and a full-table backfill inside that same
+transaction keeps both tables unreadable — even for SELECTs — for its whole
+duration. The conversion splits along the lock boundaries instead, and the
+runbook is five steps:
+
+1. **Run `_ddl`** any time: nullable columns only — on PostgreSQL 11+ its
+   lock lasts milliseconds.
+2. **Run `_backfill`** any time, even mid-day: batches over parent-id
+   ranges outside any DDL transaction, touching only rows still NULL. The
+   model's state comes from the **last transition by `sort_key`** —
+   deliberately not `most_recent`, which drifts often enough that statesman
+   ships a repair task for it — `state_changed_at` from that transition's
+   `created_at`, and `from_state` from a `LAG` window along the chain.
+3. **Switch the code**: port the skeleton, deploy statecraft in place of
+   statesman.
+4. **Catch up**: the backfill is idempotent (`WHERE ... IS NULL`), so run
+   its class once more to pick up rows statesman wrote between steps 2
+   and 3 — `bin/rails runner` with a `load` of the migration file and
+   `.new.up` does it without touching `schema_migrations`.
+5. **Run `_finalize`**: NOT NULL lands through the `NOT VALID` →
+   `VALIDATE CONSTRAINT` pair (readers never blocked), the `state` and
+   `[foreign_key, id]` indexes build `CONCURRENTLY`, the cascade FK is
+   validated the same way, and the statesman columns are dropped last.
+   Honest limit: a text `metadata` column is rewritten under a lock here —
+   unavoidable within this recipe; for very large tables the shadow-column
+   dance is the escape.
+
+The `_ddl` migration's header names two pre-flight checks on live data —
+that the id order agrees with the `sort_key` order (statecraft reads history
+by id), and that a text `metadata` column holds valid JSON in every row
+(rows written by raw SQL may not survive the cast). Run both before
+starting.
+
+After finalize, finish by hand (the generator prints this list): drop
 `Statesman::Adapters::ActiveRecordTransition` and the
 `after_destroy :update_most_recent` callback from the transition model — they
 read dropped columns — plus `ActiveRecordQueries` from the model and the
@@ -391,7 +446,7 @@ events in the skeleton. One guarantee moves rather than disappears: the
 race safety statesman derived from its unique `(parent, sort_key)` index is
 statecraft's CAS on the state column.
 
-Outside Rails, the same steps work by hand — pair the migration order above
+Outside Rails, the same five steps work by hand — pair the runbook above
 with the reference schema in [Outside Rails](#outside-rails).
 
 ## PII and erasure

data/lib/generators/statecraft/from_statesman/from_statesman_generator.rb

@@ -50,13 +50,24 @@ module Statecraft
         inject_into_class model_file, class_name, mounting_line
       end
 
-      def create_conversion_migration
-        migration_template "convert_transitions_migration.rb.tt",
-                           "#{migration_directory}/convert_#{migration_slug}_transitions_to_statecraft.rb"
+      # Three migrations, strong-migrations style: instant DDL, a batched
+      # backfill outside any DDL transaction, and a short-lock finalize.
+      # migration_template numbers them monotonically, so they run in order.
+      def create_conversion_migrations
+        migration_template "convert_transitions_ddl.rb.tt",
+                           "#{migration_directory}/convert_#{migration_slug}_transitions_ddl.rb"
+        migration_template "convert_transitions_backfill.rb.tt",
+                           "#{migration_directory}/convert_#{migration_slug}_transitions_backfill.rb"
+        migration_template "convert_transitions_finalize.rb.tt",
+                           "#{migration_directory}/convert_#{migration_slug}_transitions_finalize.rb"
       end
 
       def print_cleanup_instructions
-        say "\nAfter running the migration, finish the move by hand:", :green
+        say "\nThe conversion is three migrations — run them per the README runbook:", :green
+        say "  1. _ddl now (instant); 2. _backfill any time (batched, no long locks;"
+        say "     rerun it to catch up rows statesman wrote in between);"
+        say "  3. _finalize after switching the code to statecraft."
+        say "\nAfter finalize, finish the move by hand:", :green
         say "  * #{log_class_name}: drop `include Statesman::Adapters::ActiveRecordTransition` and"
         say "    the `after_destroy :update_most_recent` callback (they read dropped columns);"
         say "    consider adding `def readonly? = persisted?` — the pipeline inserts around it."

data/lib/generators/statecraft/from_statesman/templates/convert_transitions_backfill.rb.tt

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Step 2 of 3: the batched backfill, outside any DDL transaction. Batches
+# walk ranges of PARENT ids — both updates are partitioned by the parent,
+# so the LAG window never tears at a batch boundary — and every statement
+# touches only rows still NULL, which makes the whole migration idempotent:
+# rerun it any time to catch up with rows statesman wrote in between (the
+# runbook's catch-up step after switching the code).
+class Convert<%= migration_slug.camelize %>TransitionsBackfill < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  disable_ddl_transaction!
+
+  BATCH_SIZE = 10_000
+
+  def up
+    bounds = select_rows("SELECT MIN(id), MAX(id) FROM <%= table_name %>").first
+    return if bounds.nil? || bounds.first.nil?
+
+    first_id, last_id = bounds.map(&:to_i)
+    first_id.step(last_id, BATCH_SIZE) do |batch_start|
+      batch_end = batch_start + BATCH_SIZE - 1
+      backfill_parent_rows(batch_start, batch_end)
+      backfill_transition_rows(batch_start, batch_end)
+    end
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+
+  private
+
+  # The current state is the to_state of the LAST transition by sort_key —
+  # deliberately not most_recent, which statesman itself ships a repair rake
+  # task for; rows without transitions are in the initial state. The moment
+  # of the last transition fills state_changed_at; never-transitioned rows
+  # stay NULL, exactly like a freshly created record.
+  def backfill_parent_rows(batch_start, batch_end)
+    execute <<~SQL
+      UPDATE <%= table_name %> SET
+        state = COALESCE(
+          (SELECT t.to_state FROM <%= log_table_name %> t
+           WHERE t.<%= foreign_key_column %> = <%= table_name %>.id
+           ORDER BY t.sort_key DESC LIMIT 1),
+          '<%= initial_state %>'
+        ),
+        state_changed_at =
+          (SELECT MAX(t.created_at) FROM <%= log_table_name %> t
+           WHERE t.<%= foreign_key_column %> = <%= table_name %>.id)
+      WHERE <%= table_name %>.id BETWEEN #{batch_start} AND #{batch_end}
+        AND <%= table_name %>.state IS NULL
+    SQL
+  end
+
+  # from_state is the previous to_state along the sort_key chain; the
+  # chain's first hop starts from the initial state. Runs while sort_key is
+  # still alive — the finalize migration drops it, so backfill comes first.
+  def backfill_transition_rows(batch_start, batch_end)
+    execute <<~SQL
+      UPDATE <%= log_table_name %> SET from_state = COALESCE(prev.prev_state, '<%= initial_state %>')
+      FROM (SELECT id, LAG(to_state) OVER (
+              PARTITION BY <%= foreign_key_column %> ORDER BY sort_key
+            ) AS prev_state
+            FROM <%= log_table_name %>
+            WHERE <%= foreign_key_column %> BETWEEN #{batch_start} AND #{batch_end}) prev
+      WHERE prev.id = <%= log_table_name %>.id
+        AND <%= log_table_name %>.from_state IS NULL
+    SQL
+  end
+end

data/lib/generators/statecraft/from_statesman/templates/convert_transitions_ddl.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Step 1 of 3: instant DDL. Adds the nullable columns and nothing else —
+# on PostgreSQL 11+ a nullable add_column without a default takes its
+# ACCESS EXCLUSIVE lock for milliseconds. The long work lives in the
+# batched backfill (step 2) and the finalize migration (step 3); run them
+# in that order, per the README's "Migrating from statesman" runbook.
+#
+# BEFORE STARTING THE CONVERSION — two checks on live data, both cheap:
+#
+# 1. statecraft reads history ordered by id, statesman ordered by sort_key.
+#    They almost always agree; prove it for your data (must return 0 rows):
+#
+#      SELECT t.<%= foreign_key_column %> FROM <%= log_table_name %> t
+#      JOIN <%= log_table_name %> later ON later.<%= foreign_key_column %> = t.<%= foreign_key_column %>
+#        AND later.sort_key > t.sort_key AND later.id < t.id LIMIT 1;
+#
+# 2. If your metadata column is text, every row must hold valid JSON (rows
+#    written by raw SQL may not) — the jsonb cast in step 3 dies on the
+#    first invalid one.
+class Convert<%= migration_slug.camelize %>TransitionsDdl < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= table_name %>, :state, :string
+    add_column :<%= table_name %>, :state_changed_at, :datetime
+    add_column :<%= log_table_name %>, :from_state, :string
+    add_column :<%= log_table_name %>, :event, :string
+  end
+end

data/lib/generators/statecraft/from_statesman/templates/convert_transitions_finalize.rb.tt

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Step 3 of 3: finalize with short locks, after the backfill has caught up
+# and the code has switched to statecraft (statesman columns are dropped
+# here, so run this last). Every long validation goes through the
+# PostgreSQL NOT VALID -> VALIDATE pair, which never blocks readers;
+# indexes build CONCURRENTLY.
+class Convert<%= migration_slug.camelize %>TransitionsFinalize < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  disable_ddl_transaction!
+
+  def up
+    enforce_not_null(:<%= table_name %>, :state)
+    enforce_not_null(:<%= log_table_name %>, :from_state)
+    add_state_default_and_check
+    build_indexes
+    rebuild_foreign_key
+    convert_metadata_column
+    drop_statesman_columns
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+
+  private
+
+  # NOT NULL without a full-table lock: a NOT VALID check validates while
+  # readers and writers keep working; SET NOT NULL then reuses the
+  # validated constraint and the helper check is dropped.
+  def enforce_not_null(table, column)
+    if postgresql?
+      helper_name = "#{table}_#{column}_null_check"
+      execute "ALTER TABLE #{table} ADD CONSTRAINT #{helper_name} CHECK (#{column} IS NOT NULL) NOT VALID"
+      execute "ALTER TABLE #{table} VALIDATE CONSTRAINT #{helper_name}"
+      change_column_null table, column, false
+      execute "ALTER TABLE #{table} DROP CONSTRAINT #{helper_name}"
+    else
+      change_column_null table, column, false
+    end
+  end
+
+  def add_state_default_and_check
+    change_column_default :<%= table_name %>, :state, "<%= initial_state %>"
+
+    return unless connection.supports_check_constraints?
+
+    # add new states here when the machine grows
+    if postgresql?
+      add_check_constraint :<%= table_name %>, state_check_expression,
+                           name: "<%= table_name %>_state_check", validate: false
+      validate_check_constraint :<%= table_name %>, name: "<%= table_name %>_state_check"
+    else
+      add_check_constraint :<%= table_name %>, state_check_expression,
+                           name: "<%= table_name %>_state_check"
+    end
+  end
+
+  # The state index is the reference schema's promise (scopes and
+  # where(state:) read it); [fk, id] serves the history reads.
+  def build_indexes
+    if postgresql?
+      add_index :<%= table_name %>, :state, algorithm: :concurrently, if_not_exists: true
+      add_index :<%= log_table_name %>, %i[<%= foreign_key_column %> id],
+                algorithm: :concurrently, if_not_exists: true
+    else
+      add_index :<%= table_name %>, :state, if_not_exists: true
+      add_index :<%= log_table_name %>, %i[<%= foreign_key_column %> id], if_not_exists: true
+    end
+
+    remove_index :<%= log_table_name %>, column: %i[<%= foreign_key_column %> sort_key], if_exists: true
+    remove_index :<%= log_table_name %>, column: %i[<%= foreign_key_column %> most_recent], if_exists: true
+  end
+
+  # An audit without its subject is not an audit: the statecraft contract is
+  # ON DELETE CASCADE (statesman's default foreign key, when present,
+  # carries no action). If your foreign key column is NOT named
+  # <%= foreign_key_column %> (check the has_many on your model), rename it
+  # first — statecraft derives the name from the model class:
+  #   rename_column :<%= log_table_name %>, :your_column, :<%= foreign_key_column %>
+  def rebuild_foreign_key
+    if foreign_key_exists?(:<%= log_table_name %>, :<%= table_name %>)
+      remove_foreign_key :<%= log_table_name %>, :<%= table_name %>
+    end
+
+    if postgresql?
+      add_foreign_key :<%= log_table_name %>, :<%= table_name %>,
+                      column: :<%= foreign_key_column %>, on_delete: :cascade, validate: false
+      validate_foreign_key :<%= log_table_name %>, :<%= table_name %>
+    else
+      add_foreign_key :<%= log_table_name %>, :<%= table_name %>,
+                      column: :<%= foreign_key_column %>, on_delete: :cascade
+    end
+  end
+
+  # Statesman's default schema serializes metadata into a text column; the
+  # statecraft pipeline wants native json(b). Converting the type and
+  # removing `serialize :metadata` from the transition model are ONE move —
+  # neither library works in the half-converted state. Honest limit: the
+  # type change rewrites the table under a lock; for very large tables the
+  # shadow-column dance is the escape, outside this recipe.
+  def convert_metadata_column
+    metadata_type = connection.columns(:<%= log_table_name %>).find { |column| column.name == "metadata" }&.sql_type.to_s
+    return unless metadata_type.match?(/text|char/i)
+
+    if postgresql?
+      change_column_default :<%= log_table_name %>, :metadata, nil
+      execute "ALTER TABLE <%= log_table_name %> ALTER COLUMN metadata TYPE jsonb USING metadata::jsonb"
+      execute "UPDATE <%= log_table_name %> SET metadata = '{}'::jsonb WHERE metadata IS NULL"
+      change_column_default :<%= log_table_name %>, :metadata, {}
+      change_column_null :<%= log_table_name %>, :metadata, false
+    else
+      change_column :<%= log_table_name %>, :metadata, :json, null: false, default: {}
+    end
+  end
+
+  # sort_key and most_recent are NOT NULL without defaults — the first
+  # statecraft insert would die on them; updated_at is merely absent from
+  # the statecraft schema. Dropped last: the backfill needs sort_key alive.
+  def drop_statesman_columns
+    remove_column :<%= log_table_name %>, :sort_key
+    remove_column :<%= log_table_name %>, :most_recent if column_exists?(:<%= log_table_name %>, :most_recent)
+    remove_column :<%= log_table_name %>, :updated_at if column_exists?(:<%= log_table_name %>, :updated_at)
+  end
+
+  def state_check_expression
+    "state IN ('<%= initial_state %>'<% (states - [initial_state]).each do |state_name| %>, '<%= state_name %>'<% end %>)"
+  end
+
+  def postgresql?
+    connection.adapter_name.match?(/postg/i)
+  end
+end

data/lib/statecraft/rspec/allow_event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to allow_event(:pay).with_metadata("amount" => 5)
+    #
+    # The can_fire? question, asked with the same metadata the production
+    # call will carry. The failure message walks the layers the pipeline
+    # walks: is the event declared from this state, and if so, which
+    # guards said no.
+    class AllowEvent
+      def initialize(event_name)
+        @event_name = event_name.to_sym
+        @metadata = {}
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        record.can_fire?(@event_name, metadata: @metadata)
+      end
+
+      def failure_message
+        lines = ["expected #{StateReport.standing(@record)} to allow event #{@event_name.inspect}, but it was refused"]
+        if StateReport.event_declared?(@record, @event_name)
+          lines << StateReport.refusal(@record, @event_name, @metadata)
+        else
+          lines << "event #{@event_name.inspect} is not declared from #{StateReport.current_state(@record).inspect}"
+          lines << StateReport.declared_shape_of(@record)
+        end
+        lines.join("\n  ")
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} not to allow event #{@event_name.inspect}, " \
+          "but the guards passed with metadata #{@metadata.inspect}"
+      end
+
+      def description
+        "allow event #{@event_name.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/allow_transition_to.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to allow_transition_to(:paid).via(:pay)
+    # expect(record).to allow_transition_to(:archived).directly
+    #
+    # The available_transitions prediction for one target: not only
+    # whether the record can go there, but HOW — via lists the events
+    # whose guards pass, directly asserts the guard-free direct way.
+    class AllowTransitionTo
+      def initialize(target_state)
+        @target_state = target_state.to_sym
+        @expected_via = []
+        @directly = false
+        @metadata = {}
+      end
+
+      def via(*event_names)
+        @expected_via = event_names.map(&:to_sym)
+        self
+      end
+
+      def directly
+        @directly = true
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        @availability = record.available_transitions(metadata: @metadata)
+                              .find { |availability| availability.to == @target_state }
+        return false unless @availability
+
+        missing_ways.empty?
+      end
+
+      def failure_message
+        unless @availability
+          return ["expected #{StateReport.standing(@record)} to reach #{@target_state.inspect}, but it cannot",
+                  StateReport.reachable(@record, @metadata),
+                  StateReport.declared_shape_of(@record)].join("\n  ")
+        end
+
+        "expected the way to #{@target_state.inspect} to include #{missing_ways.map(&:inspect).join(", ")}, " \
+          "but it is reachable via #{@availability.via.inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} not to reach #{@target_state.inspect}, " \
+          "but it is reachable via #{@availability.via.inspect}"
+      end
+
+      def description
+        "allow a transition to #{@target_state.inspect}"
+      end
+
+      private
+
+      def missing_ways
+        expected = @expected_via + (@directly ? [:direct] : [])
+        expected - @availability.via
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_edge.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(OrderFlow).to have_edge(:pending, :cancelled).via(:cancel)
+    #
+    # The class-level shape question of transitions_from: no guards are
+    # consulted, exactly like the method itself. via asserts that the
+    # named events ride the edge; a bare edge simply has none.
+    class HaveEdge
+      def initialize(from_state, to_state)
+        @from_state = from_state.to_sym
+        @to_state = to_state.to_sym
+        @expected_events = []
+      end
+
+      def via(*event_names)
+        @expected_events = event_names.map(&:to_sym)
+        self
+      end
+
+      def matches?(machine_class)
+        @machine_class = machine_class
+        @edge = machine_class.transitions_from(@from_state)
+                             .find { |descriptor| descriptor[:to] == @to_state }
+        @edge && (@expected_events - @edge[:events]).empty?
+      end
+
+      def failure_message
+        unless @edge
+          return ["expected #{@machine_class.name} to declare an edge #{@from_state.inspect} -> #{@to_state.inspect}",
+                  StateReport.declared_shape(@machine_class, @from_state)].join("\n  ")
+        end
+
+        missing = (@expected_events - @edge[:events]).map(&:inspect).join(", ")
+        "expected the edge #{@from_state.inspect} -> #{@to_state.inspect} to carry #{missing}, " \
+          "but its events are #{@edge[:events].inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected #{@machine_class.name} not to declare the edge #{@from_state.inspect} -> #{@to_state.inspect}, " \
+          "but it does (events: #{@edge[:events].inspect})"
+      end
+
+      def description
+        "have an edge #{@from_state.inspect} -> #{@to_state.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_initial_state.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(OrderFlow).to have_initial_state(:pending)
+    class HaveInitialState
+      def initialize(state_name)
+        @state_name = state_name.to_sym
+      end
+
+      def matches?(machine_class)
+        @machine_class = machine_class
+        machine_class.initial_state == @state_name
+      end
+
+      def failure_message
+        "expected the initial state of #{@machine_class.name} to be #{@state_name.inspect}, " \
+          "but it is #{@machine_class.initial_state.inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected the initial state of #{@machine_class.name} not to be #{@state_name.inspect}, but it is"
+      end
+
+      def description
+        "have the initial state #{@state_name.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_transitioned_to.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to have_transitioned_to(:paid)
+    #
+    # Strictly log-based, like transitioned_to? itself: the question is
+    # about history, never about the current state. The failure message
+    # shows what the log actually holds.
+    class HaveTransitionedTo
+      def initialize(state_name)
+        @state_name = state_name.to_sym
+      end
+
+      def matches?(record)
+        @record = record
+        record.transitioned_to?(@state_name)
+      end
+
+      def failure_message
+        "expected the log of #{StateReport.standing(@record)} to hold a transition to #{@state_name.inspect}, " \
+          "but #{log_contents}"
+      end
+
+      def failure_message_when_negated
+        "expected the log of #{StateReport.standing(@record)} to hold no transition to #{@state_name.inspect}, " \
+          "but it does"
+      end
+
+      def description
+        "have transitioned to #{@state_name.inspect}"
+      end
+
+      private
+
+      def log_contents
+        to_states = @record.history.map(&:to_state)
+        return "the log is empty" if to_states.empty?
+
+        "the log holds transitions to: #{to_states.join(", ")}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/matchers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # The example-facing surface: requiring statecraft/rspec includes this
+    # module into every example group, so specs call the factories bare.
+    # Record-level matchers consult guards (a prediction with the metadata
+    # you pass); class-level matchers answer the graph's shape only.
+    # rubocop:disable Naming/PredicatePrefix -- have_* is RSpec's matcher idiom, not a predicate
+    module Matchers
+      def allow_event(event_name)
+        AllowEvent.new(event_name)
+      end
+
+      def refuse_event(event_name)
+        RefuseEvent.new(event_name)
+      end
+
+      def allow_transition_to(target_state)
+        AllowTransitionTo.new(target_state)
+      end
+
+      def have_transitioned_to(state_name)
+        HaveTransitionedTo.new(state_name)
+      end
+
+      def have_edge(from_state, to_state)
+        HaveEdge.new(from_state, to_state)
+      end
+
+      def have_initial_state(state_name)
+        HaveInitialState.new(state_name)
+      end
+
+      def transition(record)
+        Transition.new(record)
+      end
+    end
+    # rubocop:enable Naming/PredicatePrefix
+  end
+end

data/lib/statecraft/rspec/refuse_event.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to refuse_event(:cancel).because_of(:customer_cancellable?)
+    #
+    # The named negation of allow_event: the refusal itself, and — through
+    # because_of — WHO refused. Guard names come from refusals_for, so
+    # because_of sees record-layer guards only; an input-reading guard:
+    # has no name there, and the failure message says so instead of
+    # pretending otherwise.
+    class RefuseEvent
+      def initialize(event_name)
+        @event_name = event_name.to_sym
+        @expected_guards = []
+        @metadata = {}
+      end
+
+      def because_of(*guard_names)
+        @expected_guards = guard_names.map(&:to_sym)
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        @allowed = record.can_fire?(@event_name, metadata: @metadata)
+        return false if @allowed
+
+        @refusing_guards = record.refusals_for(@event_name).map(&:guard)
+        (@expected_guards - @refusing_guards).empty?
+      end
+
+      def failure_message
+        if @allowed
+          return "expected #{StateReport.standing(@record)} to refuse event #{@event_name.inspect}, " \
+                 "but the guards passed with metadata #{@metadata.inspect}"
+        end
+
+        missing = (@expected_guards - @refusing_guards).map(&:inspect).join(", ")
+        "expected the refusal of #{@event_name.inspect} to come from #{missing}\n  #{actual_refusers}"
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} to allow event #{@event_name.inspect}, but it was refused\n  " +
+          StateReport.refusal(@record, @event_name, @metadata)
+      end
+
+      def description
+        "refuse event #{@event_name.inspect}"
+      end
+
+      private
+
+      def actual_refusers
+        if @refusing_guards.empty?
+          "but no record-layer guard refused: refusals_for names record-layer guards only, " \
+            "and this refusal came from an input-reading guard: or an undeclared branch"
+        else
+          "but the refusing record-layer guards were: #{@refusing_guards.map(&:inspect).join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/state_report.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # The shared sentences of every failure message: where the record
+    # stands, what the graph declares from there, what is reachable right
+    # now, and which guards refused. Built strictly on the public
+    # introspection surface — the matchers add words, never new answers.
+    module StateReport
+      module_function
+
+      def current_state(record)
+        record[record.class.statecraft_mounting.column]&.to_sym
+      end
+
+      def standing(record)
+        "#{record.class.name} in state #{current_state(record).inspect}"
+      end
+
+      def machine(record)
+        record.class.statecraft_mounting.machine_class
+      end
+
+      def event_declared?(record, event_name)
+        machine(record).transitions_from(current_state(record))
+                       .any? { |descriptor| descriptor[:events].include?(event_name) }
+      end
+
+      def declared_shape(machine_class, state)
+        descriptors = machine_class.transitions_from(state)
+        return "no edges are declared from #{state.inspect}" if descriptors.empty?
+
+        rendered = descriptors.map do |descriptor|
+          if descriptor[:events].empty?
+            "to #{descriptor[:to].inspect} (direct)"
+          else
+            "to #{descriptor[:to].inspect} via #{descriptor[:events].inspect}"
+          end
+        end
+        "declared from #{state.inspect}: #{rendered.join("; ")}"
+      end
+
+      def declared_shape_of(record)
+        declared_shape(machine(record), current_state(record))
+      end
+
+      def reachable(record, metadata)
+        transitions = record.available_transitions(metadata: metadata)
+        state = current_state(record).inspect
+        return "nothing is reachable from #{state} right now" if transitions.empty?
+
+        rendered = transitions.map { |availability| "to #{availability.to.inspect} via #{availability.via.inspect}" }
+        "reachable from #{state}: #{rendered.join("; ")}"
+      end
+
+      def refusal(record, event_name, metadata)
+        refusals = record.refusals_for(event_name)
+        if refusals.empty?
+          "no record-layer guard refused — an input-reading guard: said no to metadata #{metadata.inspect}"
+        else
+          named = refusals.map { |entry| "#{entry.guard.inspect} (#{entry.layer})" }
+          "refused by record-layer guards: #{named.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/transition.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect { order.fire!(:pay) }.to transition(order)
+    #   .from(:pending).to(:paid).via_event(:pay).with_metadata("k" => "v")
+    #
+    # The transition through the eyes of a test: the state column moved to
+    # the target AND exactly one log row was appended with the matching
+    # from/to/event/metadata. A non-bang call that returned false leaves
+    # both untouched — the matcher fails and explains why, from the same
+    # introspection the pipeline consulted. Exceptions of the bang forms
+    # fly through, like with the change matcher: refusals are asserted
+    # with refuse_event or raise_error, not here.
+    class Transition
+      def initialize(record)
+        @record = record
+        @failures = []
+      end
+
+      def from(state_name)
+        @from_state = state_name.to_sym
+        self
+      end
+
+      def to(state_name)
+        @to_state = state_name.to_sym
+        self
+      end
+
+      def via_event(event_name)
+        @event_name = event_name.to_sym
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        raise ArgumentError, "transition(record).to(:state) — the .to target is required" unless @to_state
+
+        @before_state = StateReport.current_state(@record)
+        appended_before = @record.history.count
+        block.call
+        @after_state = StateReport.current_state(@record)
+        @appended = @record.history.offset(appended_before).to_a
+        collect_failures
+        @failures.empty?
+      end
+
+      def failure_message
+        expected_event = " via event #{@event_name.inspect}" if @event_name
+        header = "expected the block to transition #{@record.class.name} " \
+                 "#{@before_state.inspect} -> #{@to_state.inspect}#{expected_event}"
+        ([header] + @failures).join("\n  ")
+      end
+
+      def failure_message_when_negated
+        row = @appended.last
+        written_by = " by event #{row.event.inspect}" if row.event
+        "expected the block not to transition #{@record.class.name} to #{@to_state.inspect}, " \
+          "but it did: #{row.from_state.inspect} -> #{row.to_state.inspect}#{written_by}"
+      end
+
+      def description
+        "transition #{@record.class.name} to #{@to_state.inspect}"
+      end
+
+      private
+
+      def collect_failures
+        return collect_missing_transition if @appended.empty?
+
+        if @appended.size > 1
+          @failures << "expected exactly one appended log row, but the block appended #{@appended.size}"
+        end
+        if @after_state != @to_state
+          @failures << "the record ended in #{@after_state.inspect}, not #{@to_state.inspect}"
+        end
+        collect_row_mismatches(@appended.last)
+      end
+
+      def collect_row_mismatches(row)
+        if row.to_state != @to_state.to_s
+          @failures << "the log row went to #{row.to_state.inspect}, not #{@to_state.inspect}"
+        end
+        if @from_state && row.from_state != @from_state.to_s
+          @failures << "the transition started from #{row.from_state.inspect}, not #{@from_state.inspect}"
+        end
+        if @event_name && row.event != @event_name.to_s
+          @failures << "the transition was written by event #{row.event.inspect}, not #{@event_name.inspect}"
+        end
+        collect_metadata_mismatch(row)
+      end
+
+      def collect_missing_transition
+        @failures << "no transition happened: the record stayed in #{@after_state.inspect}"
+        @failures << StateReport.reachable(@record, @metadata || {})
+        return unless @event_name && StateReport.event_declared?(@record, @event_name)
+
+        @failures << StateReport.refusal(@record, @event_name, @metadata || {})
+      end
+
+      def collect_metadata_mismatch(row)
+        return unless @metadata
+
+        expected = @metadata.deep_stringify_keys
+        return if row.metadata == expected
+
+        @failures << "the log row carries metadata #{row.metadata.inspect}, not #{expected.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "statecraft"
+
+# Deliberately not required by lib/statecraft.rb: the matchers exist only
+# where RSpec does, and the gem's runtime must not know about test
+# frameworks. This file is the one opt-in door.
+unless defined?(RSpec)
+  raise Statecraft::Error,
+        "statecraft/rspec builds RSpec matchers, so RSpec must be loaded first: " \
+        "require statecraft/rspec from your spec helper, after rspec itself"
+end
+
+require_relative "rspec/state_report"
+require_relative "rspec/allow_event"
+require_relative "rspec/refuse_event"
+require_relative "rspec/allow_transition_to"
+require_relative "rspec/have_transitioned_to"
+require_relative "rspec/have_edge"
+require_relative "rspec/have_initial_state"
+require_relative "rspec/transition"
+require_relative "rspec/matchers"
+
+RSpec.configure { |config| config.include Statecraft::RSpec::Matchers }

data/lib/statecraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statecraft
-  VERSION = "0.4.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Igor Pugachev
@@ -63,7 +63,9 @@ files:
 - lib/generators/statecraft/from_statesman/USAGE
 - lib/generators/statecraft/from_statesman/from_statesman_generator.rb
 - lib/generators/statecraft/from_statesman/templates/application_machine.rb.tt
-- lib/generators/statecraft/from_statesman/templates/convert_transitions_migration.rb.tt
+- lib/generators/statecraft/from_statesman/templates/convert_transitions_backfill.rb.tt
+- lib/generators/statecraft/from_statesman/templates/convert_transitions_ddl.rb.tt
+- lib/generators/statecraft/from_statesman/templates/convert_transitions_finalize.rb.tt
 - lib/generators/statecraft/from_statesman/templates/machine_from_statesman.rb.tt
 - lib/generators/statecraft/machine/USAGE
 - lib/generators/statecraft/machine/machine_generator.rb
@@ -85,6 +87,16 @@ files:
 - lib/statecraft/pipeline.rb
 - lib/statecraft/pipeline/edge_resolution.rb
 - lib/statecraft/pipeline/surface.rb
+- lib/statecraft/rspec.rb
+- lib/statecraft/rspec/allow_event.rb
+- lib/statecraft/rspec/allow_transition_to.rb
+- lib/statecraft/rspec/have_edge.rb
+- lib/statecraft/rspec/have_initial_state.rb
+- lib/statecraft/rspec/have_transitioned_to.rb
+- lib/statecraft/rspec/matchers.rb
+- lib/statecraft/rspec/refuse_event.rb
+- lib/statecraft/rspec/state_report.rb
+- lib/statecraft/rspec/transition.rb
 - lib/statecraft/version.rb
 - lib/statecraft/warnings.rb
 homepage: https://supostat.github.io/statecraft/

data/lib/generators/statecraft/from_statesman/templates/convert_transitions_migration.rb.tt

@@ -1,153 +0,0 @@
-# frozen_string_literal: true
-
-# Converts the statesman transitions table <%= log_table_name %> into the
-# statecraft log IN PLACE and gives <%= table_name %> its state column.
-#
-# BEFORE RUNNING — two checks on live data, both cheap:
-#
-# 1. statecraft reads history ordered by id, statesman ordered by sort_key.
-#    They almost always agree; prove it for your data (must return 0 rows):
-#
-#      SELECT t.<%= foreign_key_column %> FROM <%= log_table_name %> t
-#      JOIN <%= log_table_name %> later ON later.<%= foreign_key_column %> = t.<%= foreign_key_column %>
-#        AND later.sort_key > t.sort_key AND later.id < t.id LIMIT 1;
-#
-# 2. If your metadata column is text, every row must hold valid JSON (rows
-#    written by raw SQL may not) — the jsonb cast below dies on the first
-#    invalid one.
-class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def up
-    convert_parent_table
-    convert_transitions_table
-    convert_metadata_column
-    rebuild_indexes_and_foreign_key
-    drop_statesman_columns
-  end
-
-  def down
-    raise ActiveRecord::IrreversibleMigration
-  end
-
-  private
-
-  def convert_parent_table
-    add_column :<%= table_name %>, :state, :string
-    add_column :<%= table_name %>, :state_changed_at, :datetime
-
-    # The current state is the to_state of the LAST transition by sort_key —
-    # deliberately not most_recent, which statesman itself ships a repair
-    # rake task for; rows without transitions are in the initial state.
-    execute <<~SQL
-      UPDATE <%= table_name %> SET state = COALESCE(
-        (SELECT t.to_state FROM <%= log_table_name %> t
-         WHERE t.<%= foreign_key_column %> = <%= table_name %>.id
-         ORDER BY t.sort_key DESC LIMIT 1),
-        '<%= initial_state %>'
-      )
-    SQL
-
-    # The mounting says changed_at: true, so the column must exist — and the
-    # conversion knows the honest value: the moment of the last recorded
-    # transition. Rows that never transitioned stay NULL, exactly like a
-    # freshly created record.
-    execute <<~SQL
-      UPDATE <%= table_name %> SET state_changed_at =
-        (SELECT MAX(t.created_at) FROM <%= log_table_name %> t
-         WHERE t.<%= foreign_key_column %> = <%= table_name %>.id)
-    SQL
-
-    change_column_default :<%= table_name %>, :state, "<%= initial_state %>"
-    change_column_null :<%= table_name %>, :state, false
-
-    return unless connection.supports_check_constraints?
-
-    # add new states here when the machine grows
-    if postgresql?
-      add_check_constraint :<%= table_name %>, state_check_expression,
-                           name: "<%= table_name %>_state_check", validate: false
-      validate_check_constraint :<%= table_name %>, name: "<%= table_name %>_state_check"
-    else
-      add_check_constraint :<%= table_name %>, state_check_expression,
-                           name: "<%= table_name %>_state_check"
-    end
-  end
-
-  def convert_transitions_table
-    add_column :<%= log_table_name %>, :from_state, :string
-    add_column :<%= log_table_name %>, :event, :string
-
-    # from_state is the previous to_state along the sort_key chain; the
-    # chain's first hop starts from the initial state. Runs while sort_key
-    # is still alive — order matters.
-    execute <<~SQL
-      UPDATE <%= log_table_name %> SET from_state = COALESCE(prev.prev_state, '<%= initial_state %>')
-      FROM (SELECT id, LAG(to_state) OVER (
-              PARTITION BY <%= foreign_key_column %> ORDER BY sort_key
-            ) AS prev_state
-            FROM <%= log_table_name %>) prev
-      WHERE prev.id = <%= log_table_name %>.id
-    SQL
-
-    change_column_null :<%= log_table_name %>, :from_state, false
-    # event stays NULL for the imported history: statesman had no events, and
-    # statecraft reads NULL as a direct transition.
-  end
-
-  # Statesman's default schema serializes metadata into a text column; the
-  # statecraft pipeline wants native json(b). Converting the type and
-  # removing `serialize :metadata` from the transition model are ONE move —
-  # neither library works in the half-converted state.
-  def convert_metadata_column
-    metadata_type = connection.columns(:<%= log_table_name %>).find { |column| column.name == "metadata" }&.sql_type.to_s
-    return unless metadata_type.match?(/text|char/i)
-
-    if postgresql?
-      change_column_default :<%= log_table_name %>, :metadata, nil
-      execute "ALTER TABLE <%= log_table_name %> ALTER COLUMN metadata TYPE jsonb USING metadata::jsonb"
-      execute "UPDATE <%= log_table_name %> SET metadata = '{}'::jsonb WHERE metadata IS NULL"
-      change_column_default :<%= log_table_name %>, :metadata, {}
-      change_column_null :<%= log_table_name %>, :metadata, false
-    else
-      # SQLite types dynamically and serialize already stored JSON text —
-      # the change is declarative (a table rebuild under the hood).
-      change_column :<%= log_table_name %>, :metadata, :json, null: false, default: {}
-    end
-  end
-
-  def rebuild_indexes_and_foreign_key
-    # If your foreign key column is NOT named <%= foreign_key_column %>
-    # (check the has_many on your model), rename it first — statecraft
-    # derives the name from the model class and offers no override:
-    #   rename_column :<%= log_table_name %>, :your_column, :<%= foreign_key_column %>
-
-    remove_index :<%= log_table_name %>, column: %i[<%= foreign_key_column %> sort_key], if_exists: true
-    remove_index :<%= log_table_name %>, column: %i[<%= foreign_key_column %> most_recent], if_exists: true
-    add_index :<%= log_table_name %>, %i[<%= foreign_key_column %> id]
-
-    # An audit without its subject is not an audit: the statecraft contract
-    # is ON DELETE CASCADE (statesman's default foreign key, when present,
-    # carries no action).
-    if foreign_key_exists?(:<%= log_table_name %>, :<%= table_name %>)
-      remove_foreign_key :<%= log_table_name %>, :<%= table_name %>
-    end
-    add_foreign_key :<%= log_table_name %>, :<%= table_name %>,
-                    column: :<%= foreign_key_column %>, on_delete: :cascade
-  end
-
-  # sort_key and most_recent are NOT NULL without defaults — the first
-  # statecraft insert would die on them; updated_at is merely absent from
-  # the statecraft schema.
-  def drop_statesman_columns
-    remove_column :<%= log_table_name %>, :sort_key
-    remove_column :<%= log_table_name %>, :most_recent if column_exists?(:<%= log_table_name %>, :most_recent)
-    remove_column :<%= log_table_name %>, :updated_at if column_exists?(:<%= log_table_name %>, :updated_at)
-  end
-
-  def state_check_expression
-    "state IN ('<%= initial_state %>'<% (states - [initial_state]).each do |state_name| %>, '<%= state_name %>'<% end %>)"
-  end
-
-  def postgresql?
-    connection.adapter_name.match?(/postg/i)
-  end
-end