statecraft 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0c939e1b5d335a23df4ee4bdd3fc9f5ac5a1d42e53c1bec2d8b5b8c3bc8dde8
-  data.tar.gz: 2dc1c3391139562722cd1b6cfed0e7827582b06254fec0b9b8e24680b2d16e37
+  metadata.gz: 55f4ecb6760d01b042ad158351ec8735c3962c70c3a674d3af9d6ba2ecf26fd9
+  data.tar.gz: ecc0c3ac410d67431226ccc8b361ac5d2708c276425153561b0f732ef3aefa53
 SHA512:
-  metadata.gz: 40f3727eb9fc1acddcff7c95c9dce6783633175b0ee2bc7b78013ed5d5f45556b8cb9cff1cecbd54916449d38a2071796b28fbfc4f2dea40d7af4fb51019c743
-  data.tar.gz: ad2778897f1c4609f6c01b3c3e8129fa329da6dcbc131641ccc153f21bfc94a261754c142b086941d3a9a57aca68eafa03f4039ca1a2ad1fe23f1e06706b8649
+  metadata.gz: caf25d1b5349c441aa79573e1994b2298ef64fcc4b4b9f6e6b5958827ca03a9bf8275366cf1b128a4cf39f690e6ba9bcad0327b040a51effcf42f5fff9853098
+  data.tar.gz: 7acc79611c73b980a2a932c53d87723068adb1da7ddc61b590477cf84540a904750e9fa7d550d126aa9626f9edcc34538f6aed4aacb611894907148d80e07b63

data/README.md

@@ -351,38 +351,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 +401,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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.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

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

@@ -1,142 +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
-
-    # 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
-
-    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