statecraft 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70f23cb88e677af1d36d2acf31fc39a1688f90a46c99d6eebef3e76c49ca4f8e
-  data.tar.gz: f38e777eed1a3fa3109da01a9f56eeb09f8c181c9d13e899ab33e3334c372d8b
+  metadata.gz: 8e51b28a602d49b1cf5f71183e5c8b2080bd3e9f4e3a857147a65a7f5529373c
+  data.tar.gz: 2068032e1f963037d4521fbca8a02e53d5594bb5ce9902b9c809d1448ba7d9bd
 SHA512:
-  metadata.gz: 636c11b89dabc3d977f13d503ea7cc311c59dd4c677bfea917b333de36f37c045b1b1ddfec2a1f4643131c0f160dad33651ebf4371c32a365783b8e4c7f1df5f
-  data.tar.gz: e09b76e0ca7552f014259429ee4f16ce5ee64b75f4cd829dbffa391ec0604901ba2d9b5a23dd3375bc79f95dc3abe4ca4a77c483634de0343ed2601694bde538
+  metadata.gz: 4588eac402af35b053ce88660b39efb3a26694fdb9a5f3935844dedfff102f8d687f52af1c3b5da422cd7be99052bc55ef83e3f318d918746ef761bfba49a187
+  data.tar.gz: a995c7b056c6a2dd0beae23de1a06ced70f6ba3fbccce223375ea974f0fad506defd0bbf96426f10a3d2c95106be02c37c4075d569d1d8d342199bab8f8a6306

data/README.md

@@ -145,12 +145,52 @@ A good `record_guard:` is a one-line delegation to a domain predicate on the
 model (`def customer_cancellable?(record) = record.customer_cancellable?`):
 the machine keeps the registry "event → predicate", the model keeps the fact.
 
+The third nature is `input_guard:` — a guard declaring that its answer
+*without* the input would be a false "no". Its handler must take exactly
+`(record, metadata)` (the compiler refuses any other arity), execution runs
+it after the record and plain layers, and the question surface honors the
+declaration: a `can_fire?` / `may_*?` / `available_*` asked with metadata
+omitted entirely raises `Statecraft::MetadataRequired` naming the guard,
+instead of feeding it an empty hash and predicting a refusal that the real
+call would not hit. An explicit `metadata: {}` states "my input is empty"
+and is always a legal question.
+
 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.
 
+## Which rules belong in a guard
+
+Not every rule about a transition is a guard, and the three slots above are
+not an invitation to move form validation into the machine. One question
+draws the line: **would the rule still have to hold if the transition came
+from a job, a console or an ETL run instead of a form?**
+
+A rule about the record — this order is on credit, so it is not cancellable
+— always answers yes: it is a fact of the domain, it must hold for every
+caller, and it is checked inside the transaction where nothing can change
+under it. That is a `record_guard:`, and it is the case guards were built
+for.
+
+A rule that reads the input earns its place in two situations. The first is
+a rule that compares the input *against the record* — a refund amount that
+must not exceed the order total. One side of that comparison can change
+between a caller's check and the write, so the check belongs inside the
+transaction. The second is a rule protecting the log: metadata is write-once
+and the log is append-only, so a cancellation recorded without its reason
+stays useless forever. The last gate before something becomes permanent is
+worth having in the pipeline, whoever opened it.
+
+Everything else is the caller's job. A rule that reads only the input,
+never touches the record, and does not decide whether the log row makes
+sense — a minimum length, a format, a spelling — gains nothing from the
+machine but centralization, and it pays for that with a poorer contract: a
+guard answers with one boolean and a symbol, while a form object answers
+with several errors, attributed to fields, in the user's language. Validate
+the form in the form; hand the machine input it has already accepted.
+
 ## Callbacks and chains
 
 `before_transition`, `after_transition` and `after_commit` accept `from:`,
@@ -326,7 +366,36 @@ or a missing branch. It carries names, never words: human-readable reasons
 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!`.
+pass the same metadata to `may_*?` that you will collect for `fire!`. Mark
+such a guard `input_guard:` and the machine holds you to it: a question
+asked without any `metadata:` raises `Statecraft::MetadataRequired` with
+the guard's name instead of answering a false "no" (an explicit
+`metadata: {}` stays legal — it states the input is genuinely empty). A
+plain `guard:` keeps the old behavior: a bare question consults it with an
+empty hash.
+
+## Strict mode
+
+By default an unreachable state compiles silently — the column is written
+by more than the gem (legacy rows, the console, external systems), so a
+state without inbound edges is not necessarily a mistake. A machine that
+claims its graph is closed opts in:
+
+<!-- illustrative -->
+```ruby
+class OrderFlow < ApplicationMachine
+  strict!
+
+  state :pending, initial: true
+  # every state below must now be reachable from :pending through edges
+end
+```
+
+With `strict!` compilation additionally requires every declared state to be
+reachable from the initial one, walking edges only — guards are not
+consulted, exactly like `transitions_from`. Dead ends stay legal in strict
+mode too: terminal states are the norm, and an accidental one is surfaced
+by the first test as `InvalidTransition` with the list of allowed targets.
 
 ## RSpec matchers
 
@@ -405,9 +474,18 @@ and parse them in the guard.
 
 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.
+There is no metadata schema mechanism, and the shape evolves by convention:
+carry a `v:` key when you need versioned readers.
+
+A guard can require a key, but that is a narrow licence rather than the
+schema mechanism in disguise: the reason to enforce a field here is that
+the row is about to become permanent — metadata is write-once and the log
+is append-only, so a field missing at insert time is missing for good. Note
+what such a guard does *not* buy: metadata is frozen at the pipeline
+entrance, before the transaction opens, so checking it inside a guard is no
+more atomic than checking it in the caller. Shape and format belong to
+whoever assembled the hash — see
+[which rules belong in a guard](#which-rules-belong-in-a-guard).
 
 ## Initial state is not a transition
 
@@ -536,6 +614,52 @@ statesman never had: see [Stale transitions](#stale-transitions-versioning-again
 — the version column is a constant default, so adding it costs a
 metadata-only migration on PostgreSQL 11+.
 
+## Migrating from aasm
+
+aasm already keeps the current state in a column, so this move is the
+opposite shape of the statesman one: nothing is backfilled, and the
+conversion adds the history aasm never had.
+
+```sh
+bin/rails generate statecraft:from_aasm Order
+```
+
+The generator reads the live aasm machine off the model (pass a second
+argument to name one machine of a model that declares several) and writes
+the machine skeleton, the log-table migration and the mounting line. More
+survives the trip than from statesman: aasm has real event names, and its
+state column arrives as the mounting's `column:`.
+
+Guards come over by nature. An aasm guard judges the record and never sees
+what the caller submitted, which is exactly statecraft's `record_guard:` —
+so a symbol `guard:`/`if:` becomes a `record_guard:` plus a generated
+one-line delegate (`def payable?(record) = record.payable?`, because a
+guard symbol resolves on the machine here, not on the record), and
+`unless: :locked?` becomes a negating delegate. A lambda guard carries its
+own closure and cannot be moved: it arrives as a TODO with its `file:line`.
+
+One graph shape is refused rather than guessed. aasm lets one event branch
+from a single state and picks the first transition whose guard passes;
+statecraft makes an event a partial function, so `from` is unique within an
+event. The generator stops, names the branching events, and asks you to
+split them in aasm first — the `pay` / `fail_payment` pattern. Naming the
+halves is a domain decision, and a bad name would outlive the migration.
+
+The migration creates the log table and adds an index on the existing state
+column. It deliberately does **not** tighten that column: `NOT NULL`, a
+default and a `CHECK` on a live table mean long locks and an explosion on
+any legacy row outside the state list. The recipe for doing it later, in
+the `NOT VALID` → `VALIDATE CONSTRAINT` style, sits in the migration's own
+header.
+
+Then finish by hand (the generator prints the list): drop `include AASM`
+and the `aasm do ... end` block. Event calls keep their names under
+`helpers: true`, but their semantics sharpen — a lost race now raises
+`TransitionConflict` where aasm quietly answered `false` or, without an
+explicit lock, silently overwrote the column. aasm's state predicates
+(`order.paid?`) are not generated: use `in_state?(:paid)` or the `paid`
+scope.
+
 ## PII and erasure
 
 Metadata is the only place personal data can live — `from_state`, `to_state`
@@ -635,9 +759,10 @@ class OrderFlow
   # event and the bypass path all share pending -> cancelled — the log
   # records HOW, not only WHAT. The cancel guards split by nature: the
   # record layer judges the order (and the offering may ask it), the input
-  # layer judges what the operator typed (only fire! and the panel see it).
+  # layer judges what the operator typed — and is marked input_guard:, so a
+  # question asked without metadata raises instead of predicting a false no.
   event :cancel, from: :pending, to: :cancelled,
-        record_guard: :customer_cancellable?, guard: :reason_present?
+        record_guard: :customer_cancellable?, input_guard: :reason_present?
   event :admin_override, from: :pending, to: :cancelled
 
   private

data/lib/generators/statecraft/from_aasm/USAGE

@@ -0,0 +1,34 @@
+Description:
+    Migrates a model off aasm. aasm already keeps the current state in a
+    column, so nothing is backfilled: the conversion adds the append-only
+    history aasm never had, indexes the existing column and generates a
+    machine skeleton from the live aasm reflection.
+
+    Copied over: the states, the initial state, the real event names (unlike
+    statesman, aasm has them) and the state column, which becomes the
+    mounting's `column:`. Symbol guards (guard:/if:/unless:) come over as
+    record_guard: with a generated one-line delegate — aasm calls a guard on
+    the record, and statecraft resolves a guard symbol on the machine.
+    Lambda guards carry their own closure and cannot be moved: each becomes
+    a TODO comment with its source location.
+
+    The second argument names an aasm machine when the model declares
+    several (`aasm(:shipment)`); without it the unnamed machine is read.
+    An event that branches from one state (aasm picks the first transition
+    whose guard passes) is refused: statecraft makes an event a partial
+    function, so split it into two named events in aasm first.
+
+Example:
+    bin/rails generate statecraft:from_aasm Order
+
+    Creates (when missing) and edits:
+        app/state_machines/application_machine.rb
+        app/state_machines/order_flow.rb    (skeleton: states, events, guards)
+        app/models/order.rb                 (state_machine mounting line)
+        db/migrate/XXX_create_order_transitions.rb
+
+    The migration creates the log table and indexes the state column; the
+    column is otherwise left alone, with the NOT NULL / default / CHECK
+    recipe in its header. After running it, follow the printed cleanup list:
+    drop `include AASM` and the aasm block, and replace aasm's state
+    predicates (`order.paid?`) with `in_state?(:paid)` or the scope.

data/lib/generators/statecraft/from_aasm/from_aasm_generator.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Statecraft
+  module Generators
+    # `rails generate statecraft:from_aasm Order [machine_name]` — the door
+    # off aasm. Reads the live aasm machine through reflection (states, the
+    # initial state, real event names, the state column and the symbol
+    # guards), generates the machine skeleton, the log table migration and
+    # the mounting line. aasm keeps state in a column already, so nothing is
+    # backfilled: the conversion adds the history aasm never had.
+    class FromAasmGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :aasm_machine_name, type: :string, required: false,
+                                   desc: "The named aasm machine (default: the unnamed one)"
+
+      def load_aasm_machine
+        @aasm_machine = resolve_aasm_machine
+        assert_graph_present
+        assert_no_branching_events
+      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_skeleton
+        template "machine_from_aasm.rb.tt", "app/state_machines/#{file_path}_flow.rb"
+      end
+
+      def mount_model
+        unless File.exist?(File.join(destination_root, model_file))
+          say_status :skip, "#{model_file} not found — mount the machine yourself: #{mounting_line.strip}", :yellow
+          return
+        end
+
+        inject_into_class model_file, class_name, mounting_line
+      end
+
+      def create_log_migration
+        migration_template "create_log_table.rb.tt",
+                           "#{migration_directory}/create_#{migration_slug}_transitions.rb"
+      end
+
+      def print_cleanup_instructions
+        say "\nOne migration: it creates the log table aasm never had and indexes " \
+            "the existing #{state_column} column.", :green
+        say "The column itself is left alone — NOT NULL, a default and a CHECK on a live"
+        say "table are locks and legacy-row explosions; the migration header carries the recipe."
+        say "\nAfter it runs, finish the move by hand:", :green
+        say "  * #{class_name}: drop `include AASM` and the whole `aasm do ... end` block."
+        say "  * Event calls keep their names with helpers: true (`order.pay!`), but a losing"
+        say "    race now raises TransitionConflict instead of quietly answering false."
+        say "  * aasm state predicates (`order.paid?`) are not generated: use `in_state?(:paid)`"
+        say "    or the `#{class_name}.paid` scope."
+        say "  * Guards that were lambdas are TODO comments in the skeleton — port them by hand."
+      end
+
+      private
+
+      def resolve_aasm_machine
+        unless model_class.respond_to?(:aasm)
+          raise Thor::Error, "#{class_name} does not respond to .aasm — " \
+                             "point the generator at the model that includes AASM"
+        end
+
+        machine = aasm_machine_name ? model_class.aasm(aasm_machine_name.to_sym) : model_class.aasm
+        unless machine.respond_to?(:states) && machine.respond_to?(:events)
+          raise Thor::Error, "#{class_name}.aasm does not look like an aasm machine (no .states/.events)"
+        end
+
+        machine
+      end
+
+      def model_class
+        @model_class ||= class_name.safe_constantize ||
+                         raise(Thor::Error, "model class #{class_name} not found — " \
+                                            "the generator reads the live aasm machine off it")
+      end
+
+      # A model with named machines answers the unnamed `.aasm` with the
+      # :default machine, which holds no states at all — a silently empty
+      # graph. Name the machines instead of generating a skeleton of nothing.
+      def assert_graph_present
+        return unless states.empty?
+
+        raise Thor::Error, "#{class_name}'s #{machine_label} declares no states#{named_machines_hint}"
+      end
+
+      def named_machines_hint
+        names = declared_machine_names - ["default"]
+        return "" if names.empty?
+
+        " — it declares named machines: #{names.join(", ")}; " \
+          "pass one: rails g statecraft:from_aasm #{name} #{names.first}"
+      end
+
+      def declared_machine_names
+        store = defined?(AASM::StateMachineStore) && AASM::StateMachineStore.fetch(model_class)
+        store.respond_to?(:machine_names) ? store.machine_names.map(&:to_s) : []
+      rescue StandardError
+        []
+      end
+
+      # aasm picks the first transition of an event whose guard passes, so one
+      # event may branch from a single state; statecraft compiles an event as a
+      # partial function (from is unique within an event) and refuses such a
+      # graph. The split is a domain decision, so the door stops here.
+      def assert_no_branching_events
+        branching = event_descriptors.filter_map do |event|
+          froms = event[:transitions].map { |transition| transition[:from] }
+          duplicated = froms.tally.select { |_from, count| count > 1 }.keys
+          "#{event[:name]} (from #{duplicated.join(", ")})" unless duplicated.empty?
+        end
+        return if branching.empty?
+
+        raise Thor::Error,
+              "these aasm events branch from one state: #{branching.join("; ")}. " \
+              "statecraft makes an event a partial function — within one event, from is unique. " \
+              "Split each into two named events (the pay / fail_payment pattern) in aasm first, " \
+              "then rerun this generator."
+      end
+
+      def event_descriptors
+        @event_descriptors ||= @aasm_machine.events.map do |event|
+          {
+            name: event.name,
+            transitions: event.transitions.map { |transition| describe_transition(event, transition) }
+          }
+        end
+      end
+
+      def describe_transition(event, transition)
+        options = transition.respond_to?(:opts) ? transition.opts : {}
+        { from: transition.from, to: transition.to, guard: guard_descriptor(event, transition, options) }
+      end
+
+      # aasm spells the record-level guard three ways and calls it on the
+      # record; statecraft's record_guard: is the same nature (arity 1) but
+      # resolves on the machine, so every symbol becomes a one-line delegate.
+      # A lambda carries its own closure and cannot be moved — it is reported.
+      def guard_descriptor(event, transition, options)
+        positive = options[:guard] || options[:if]
+        negative = options[:unless]
+        return symbol_guard(positive, negated: false) if positive.is_a?(Symbol)
+        return symbol_guard(negative, negated: true) if negative.is_a?(Symbol)
+
+        lambda_note(event, transition, positive || negative)
+      end
+
+      def symbol_guard(name, negated:)
+        { kind: :delegate, source: name, method_name: negated ? "not_#{name.to_s.delete_suffix("?")}?" : name.to_s,
+          negated: negated }
+      end
+
+      def lambda_note(event, transition, callable)
+        return nil if callable.nil?
+
+        location = callable.respond_to?(:source_location) ? callable.source_location&.join(":") : nil
+        origin = location ? " — defined at #{location}" : ""
+        { kind: :todo, note: "#{event.name} (#{transition.from} -> #{transition.to})#{origin}" }
+      end
+
+      def states
+        @states ||= @aasm_machine.states.map { |state| state.name.to_s }
+      end
+
+      def initial_state
+        @aasm_machine.initial_state.to_s
+      end
+
+      def events
+        event_descriptors.flat_map do |event|
+          event[:transitions].map do |transition|
+            { name: event[:name], from: transition[:from], to: transition[:to],
+              guard: delegate_guard(transition) }
+          end
+        end
+      end
+
+      def guard_delegates
+        events.filter_map { |event| event[:guard] }.uniq { |guard| guard[:method_name] }
+      end
+
+      def guard_todos
+        all_guards.filter_map { |guard| guard[:note] if guard[:kind] == :todo }
+      end
+
+      def delegate_guard(transition)
+        guard = transition[:guard]
+        guard if guard && guard[:kind] == :delegate
+      end
+
+      def all_guards
+        event_descriptors.flat_map { |event| event[:transitions].filter_map { |t| t[:guard] } }
+      end
+
+      def state_column
+        @aasm_machine.respond_to?(:attribute_name) ? @aasm_machine.attribute_name.to_s : "state"
+      end
+
+      def machine_label
+        aasm_machine_name ? "aasm machine #{aasm_machine_name}" : "unnamed aasm machine"
+      end
+
+      def mounting_line
+        column = state_column == "state" ? "" : "column: :#{state_column}, "
+        "  state_machine #{class_name}Flow, #{column}changed_at: true, helpers: true, scopes: true\n"
+      end
+
+      def model_file
+        "app/models/#{file_path}.rb"
+      end
+
+      def table_name
+        @table_name ||= model_class.respond_to?(:table_name) ? model_class.table_name : super
+      end
+
+      def log_table_name
+        "#{table_name.singularize}_transitions"
+      end
+
+      def foreign_key_column
+        "#{file_name}_id"
+      end
+
+      def migration_directory
+        db_config = model_class.respond_to?(:connection_db_config) && model_class.connection_db_config
+        configured = db_config && Array(db_config.migrations_paths).first
+        configured || "db/migrate"
+      end
+
+      def migration_slug
+        file_path.tr("/", "_")
+      end
+
+      def migration_class_name
+        "Create#{migration_slug.camelize}Transitions"
+      end
+    end
+  end
+end

data/lib/generators/statecraft/from_aasm/templates/application_machine.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Shared home for private guard helpers used by several machines. Keep it
+# free of DSL declarations (states, transitions, events): machine definitions
+# are NOT inherited — each machine declares its own graph.
+class ApplicationMachine
+  include Statecraft::Machine
+end

data/lib/generators/statecraft/from_aasm/templates/create_log_table.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# aasm kept the state in <%= table_name %>.<%= state_column %> and kept no history at
+# all, so this migration adds only what the gem needs: the append-only log and
+# an index on the column the scopes will read.
+#
+# The column itself is deliberately left as aasm made it. To tighten it later
+# without blocking writes on a live table:
+#   ALTER TABLE <%= table_name %> ALTER COLUMN <%= state_column %> SET DEFAULT '<%= initial_state %>';
+#   -- backfill NULLs, then --
+#   ALTER TABLE <%= table_name %> ALTER COLUMN <%= state_column %> SET NOT NULL;
+#   ALTER TABLE <%= table_name %> ADD CONSTRAINT <%= table_name %>_<%= state_column %>_check
+#     CHECK (<%= state_column %> IN (<%= states.map { |state| "'#{state}'" }.join(", ") %>)) NOT VALID;
+#   -- clean the data --
+#   ALTER TABLE <%= table_name %> VALIDATE CONSTRAINT <%= table_name %>_<%= state_column %>_check;
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= log_table_name.pluralize %> do |t|
+      t.references :<%= file_name %>,
+                   null: false, index: false,
+                   foreign_key: { to_table: :<%= table_name %>, on_delete: :cascade }
+      t.string :from_state, null: false
+      t.string :to_state, null: false
+      t.string :event
+      t.column :metadata, metadata_column_type, null: false, default: {}
+      t.datetime :created_at, null: false
+      t.index %i[<%= foreign_key_column %> id]
+    end
+
+    add_index :<%= table_name %>, :<%= state_column %> unless index_exists?(:<%= table_name %>, :<%= state_column %>)
+  end
+
+  private
+
+  # jsonb where the database has it, json elsewhere: the adapter is known
+  # only when the migration actually runs, never at generation time.
+  def metadata_column_type
+    connection.adapter_name.match?(/postg/i) ? :jsonb : :json
+  end
+end

data/lib/generators/statecraft/from_aasm/templates/machine_from_aasm.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Skeleton generated from <%= class_name %>'s <%= machine_label %>: the graph and
+# the event names are copied, the semantics are yours to port.
+#
+# - aasm guards judge the record and see no input, so every symbol guard came
+#   over as record_guard: with a one-line delegate below. A guard that reads
+#   what the caller submits belongs on guard: (arity 2) instead.
+# - lambda guards carry their own closure and cannot be moved; each is a TODO
+#   with its original location.
+class <%= class_name %>Flow < ApplicationMachine
+<% states.each do |state_name| -%>
+  state :<%= state_name %><%= state_name == initial_state ? ", initial: true" : "" %>
+<% end -%>
+
+<% events.each do |event| -%>
+  event :<%= event[:name] %>, from: :<%= event[:from] %>, to: :<%= event[:to] %><%= event[:guard] ? ", record_guard: :#{event[:guard][:method_name]}" : "" %>
+<% end -%>
+<% unless guard_todos.empty? -%>
+
+<% guard_todos.each do |note| -%>
+  # TODO(guard): <%= note %>
+<% end -%>
+<% end -%>
+<% unless guard_delegates.empty? -%>
+
+  private
+
+  # The machine keeps the registry "event -> predicate" and delegates the
+  # domain facts to the record, exactly where aasm called them.
+<% guard_delegates.each do |guard| -%>
+  def <%= guard[:method_name] %>(record) = <%= guard[:negated] ? "!record.#{guard[:source]}" : "record.#{guard[:source]}" %>
+<% end -%>
+<% end -%>
+end

data/lib/statecraft/errors.rb

@@ -139,4 +139,21 @@ module Statecraft
             "make the log model inherit from the model's connection-owning ancestor")
     end
   end
+
+  # A question (can_fire?, may_*?, available_*) was asked without metadata
+  # while an input_guard stands on the consulted path — its answer without
+  # the input would be a false "no", so the question refuses loudly instead.
+  # An explicit `metadata: {}` states "my input is empty" and is legal.
+  class MetadataRequired < Error
+    attr_reader :record, :question, :guards
+
+    def initialize(record:, question:, guards:)
+      @record = record
+      @question = question
+      @guards = guards
+      super("#{question} on #{record.class.name} consults input guards " \
+            "#{guards.map(&:inspect).join(", ")} — pass metadata: to answer with input " \
+            "(an explicit metadata: {} means the input is empty)")
+    end
+  end
 end

data/lib/statecraft/introspection.rb

@@ -11,7 +11,7 @@ module Statecraft
     Availability = Struct.new(:to, :via, keyword_init: true)
     Refusal = Struct.new(:event, :guard, :layer, keyword_init: true)
 
-    def can_fire?(event_name, metadata: {})
+    def can_fire?(event_name, metadata: Metadata::OMITTED)
       graph = statecraft_graph
       branches = graph.events[event_name.to_sym]
       return false unless branches
@@ -19,24 +19,32 @@ module Statecraft
       edge = branches[statecraft_current_state]
       return false unless edge
 
-      statecraft_guards_pass?(edge, event_name.to_sym, Metadata.normalize(metadata))
+      normalized = statecraft_question_metadata(metadata, [[edge, event_name.to_sym]],
+                                                question: "can_fire?(#{event_name.inspect})")
+      statecraft_guards_pass?(edge, event_name.to_sym, normalized)
     end
 
-    def available_events(metadata: {})
-      normalized = Metadata.normalize(metadata)
-      statecraft_graph.events.filter_map do |event_name, branches|
+    def available_events(metadata: Metadata::OMITTED)
+      consulted = statecraft_graph.events.filter_map do |event_name, branches|
         edge = branches[statecraft_current_state]
-        next unless edge
-
+        [edge, event_name] if edge
+      end
+      normalized = statecraft_question_metadata(metadata, consulted, question: "available_events")
+      consulted.filter_map do |edge, event_name|
         event_name if statecraft_guards_pass?(edge, event_name, normalized)
       end
     end
 
-    def available_transitions(metadata: {})
-      normalized = Metadata.normalize(metadata)
-      statecraft_graph.edges.filter_map do |(from, _to), edge|
-        next unless from == statecraft_current_state
-
+    def available_transitions(metadata: Metadata::OMITTED)
+      outgoing = statecraft_graph.edges.filter_map do |(from, _to), edge|
+        edge if from == statecraft_current_state
+      end
+      consulted = outgoing.flat_map do |edge|
+        pairs = edge.event_names.map { |event_name| [edge, event_name] }
+        statecraft_direct_legal?(edge) ? pairs + [[edge, nil]] : pairs
+      end
+      normalized = statecraft_question_metadata(metadata, consulted, question: "available_transitions")
+      outgoing.filter_map do |edge|
         via = statecraft_passable_via(edge, normalized)
         Availability.new(to: edge.to, via: via) unless via.empty?
       end
@@ -73,6 +81,23 @@ module Statecraft
 
     private
 
+    # The single funnel for a question's metadata. Omitted with no input
+    # guard on the consulted path degrades to an empty hash; omitted with
+    # one raises MetadataRequired — the guard declared that its answer
+    # without input would be a false "no". An explicit hash always passes.
+    def statecraft_question_metadata(metadata, consulted_pairs, question:)
+      return Metadata.normalize(metadata) unless metadata.equal?(Metadata::OMITTED)
+
+      input_guards = consulted_pairs.flat_map { |edge, event_name| statecraft_input_guards(edge, event_name) }
+      return Metadata.normalize({}) if input_guards.empty?
+
+      raise MetadataRequired.new(record: self, question: question, guards: input_guards.uniq)
+    end
+
+    def statecraft_input_guards(edge, event_name)
+      edge.edge_input_guards + (event_name ? edge.event_input_guards.fetch(event_name, []) : [])
+    end
+
     def statecraft_record_refusals(edge, event_name)
       machine_instance = self.class.statecraft_mounting.machine_class.new
       layers = {

data/lib/statecraft/machine.rb

@@ -7,12 +7,15 @@ module Statecraft
   # Guard and callback symbols resolve to instance methods of the machine
   # class; callables are honored with a plain `call` and arity dispatch.
   module Machine
-    # edge_guards / event_guards carry the FULL lists of both layers in
-    # record-then-input order — execution and the prediction run them as one
+    # edge_guards / event_guards carry the FULL lists of all layers in
+    # record-plain-input order — execution and the prediction run them as one
     # sequence. The parallel *_record_guards fields hold only the record
-    # layer; nothing but the offering introspection reads them.
-    Edge = Struct.new(:from, :to, :lock, :edge_guards, :edge_record_guards,
-                      :event_names, :event_guards, :event_record_guards, keyword_init: true)
+    # layer (read by the offering introspection); the *_input_guards fields
+    # hold only the marked input layer (read by the question surface to
+    # refuse a question asked without metadata).
+    Edge = Struct.new(:from, :to, :lock, :edge_guards, :edge_record_guards, :edge_input_guards,
+                      :event_names, :event_guards, :event_record_guards, :event_input_guards,
+                      keyword_init: true)
     Callback = Struct.new(:handler, :from, :to, :event, keyword_init: true)
     CompiledGraph = Struct.new(
       :states, :initial_state, :edges, :events, :callbacks,
@@ -59,16 +62,17 @@ module Statecraft
         declared_states << { name: name.to_sym, initial: initial }
       end
 
-      def transition(from:, to:, guard: nil, record_guard: nil, lock: false)
+      def transition(from:, to:, guard: nil, record_guard: nil, input_guard: nil, lock: false)
         declared_edges << {
           from: from.to_sym, to: to.to_sym,
           guards: Array(guard), record_guards: Array(record_guard),
+          input_guards: Array(input_guard),
           lock: lock || current_event_lock,
           event: current_event_name
         }
       end
 
-      def event(name, from: nil, to: nil, guard: nil, record_guard: nil, lock: false, &declarations)
+      def event(name, from: nil, to: nil, guard: nil, record_guard: nil, input_guard: nil, lock: false, &declarations)
         name = name.to_sym
         declared_event_names << name
         if declarations
@@ -87,7 +91,8 @@ module Statecraft
 
           @statecraft_current_event = { name: name, lock: false }
           begin
-            transition(from: from, to: to, guard: guard, record_guard: record_guard, lock: lock)
+            transition(from: from, to: to, guard: guard, record_guard: record_guard,
+                       input_guard: input_guard, lock: lock)
           ensure
             @statecraft_current_event = nil
           end
@@ -108,6 +113,16 @@ module Statecraft
         end
       end
 
+      # Opt-in shape strictness: with strict! the compiler additionally
+      # requires every declared state to be reachable from the initial one.
+      # Off by default — the column is written by more than the gem, so an
+      # unconnected state is legal unless the machine claims a closed graph.
+      def strict!
+        @statecraft_strict = true
+      end
+
+      def strict? = @statecraft_strict == true
+
       def states
         compiled_graph.states
       end
@@ -197,6 +212,8 @@ module Statecraft
         events = compile_events(edges)
         resolve_symbols(edges)
         assert_record_guards_unary(edges)
+        assert_input_guards_binary(edges)
+        assert_states_reachable(states, initial, edges) if machine_class.strict?
         CompiledGraph.new(
           states: states.freeze,
           initial_state: initial,
@@ -249,9 +266,10 @@ module Statecraft
       def build_edge(declaration)
         Edge.new(
           from: declaration[:from], to: declaration[:to], lock: declaration[:lock],
-          edge_guards: declaration[:record_guards] + declaration[:guards],
+          edge_guards: declaration[:record_guards] + declaration[:guards] + declaration[:input_guards],
           edge_record_guards: declaration[:record_guards],
-          event_names: [], event_guards: {}, event_record_guards: {}
+          edge_input_guards: declaration[:input_guards],
+          event_names: [], event_guards: {}, event_record_guards: {}, event_input_guards: {}
         )
       end
 
@@ -259,16 +277,18 @@ module Statecraft
         event_name = declaration[:event]
         edge ||= Edge.new(
           from: declaration[:from], to: declaration[:to], lock: false,
-          edge_guards: [], edge_record_guards: [],
-          event_names: [], event_guards: {}, event_record_guards: {}
+          edge_guards: [], edge_record_guards: [], edge_input_guards: [],
+          event_names: [], event_guards: {}, event_record_guards: {}, event_input_guards: {}
         )
         if edge.event_names.include?(event_name)
           raise CompilationError, "event #{event_name.inspect} declares edge #{pair_name(pair)} twice"
         end
 
         edge.event_names << event_name
-        edge.event_guards[event_name] = declaration[:record_guards] + declaration[:guards]
+        edge.event_guards[event_name] = declaration[:record_guards] + declaration[:guards] +
+                                        declaration[:input_guards]
         edge.event_record_guards[event_name] = declaration[:record_guards]
+        edge.event_input_guards[event_name] = declaration[:input_guards]
         edge.lock ||= declaration[:lock]
         edge
       end
@@ -334,15 +354,62 @@ module Statecraft
         guard.respond_to?(:arity) ? guard.arity : guard.method(:call).arity
       end
 
+      # An input guard promises that its answer is meaningless without the
+      # input, and the promise is held by shape: it must accept exactly the
+      # record and the metadata, so a question asked without metadata can be
+      # refused instead of answered falsely.
+      def assert_input_guards_binary(edges)
+        edges.each_value do |edge|
+          input_guards = edge.edge_input_guards + edge.event_input_guards.values.flatten
+          input_guards.each do |guard|
+            arity = record_guard_arity(guard)
+            next if arity == 2
+
+            label = guard.is_a?(Symbol) ? guard.inspect : "the callable"
+            raise CompilationError,
+                  "input_guard #{label} must take the record and the metadata (arity 2), got arity #{arity}"
+          end
+        end
+      end
+
+      # Strict reachability is a shape check, like transitions_from: edges
+      # only, no guards. Dead ends stay legal — terminal states are the norm.
+      def assert_states_reachable(states, initial, edges)
+        unreachable = states - reachable_states(initial, edges)
+        return if unreachable.empty?
+
+        raise CompilationError,
+              "strict!: unreachable from the initial #{initial.inspect}: " \
+              "#{unreachable.map(&:inspect).join(", ")} — connect with edges or drop strict!"
+      end
+
+      def reachable_states(initial, edges)
+        reached = [initial]
+        queue = [initial]
+        until queue.empty?
+          from = queue.shift
+          edges.each_key do |(edge_from, edge_to)|
+            next if edge_from != from || reached.include?(edge_to)
+
+            reached << edge_to
+            queue << edge_to
+          end
+        end
+        reached
+      end
+
       def deep_freeze_edges(edges)
         edges.each_value do |edge|
           edge.edge_guards.freeze
           edge.edge_record_guards.freeze
+          edge.edge_input_guards.freeze
           edge.event_names.freeze
           edge.event_guards.each_value(&:freeze)
           edge.event_guards.freeze
           edge.event_record_guards.each_value(&:freeze)
           edge.event_record_guards.freeze
+          edge.event_input_guards.each_value(&:freeze)
+          edge.event_input_guards.freeze
           edge.freeze
         end
         edges.freeze

data/lib/statecraft/metadata.rb

@@ -7,6 +7,11 @@ module Statecraft
   # strings, and anything that JSON cannot represent fails instantly at the
   # pipeline entrance instead of inside the transaction.
   module Metadata
+    # The question surface's default: distinguishes "asked without metadata"
+    # from an explicit empty hash, so a question that would consult an
+    # input_guard can refuse loudly instead of answering from a void.
+    OMITTED = Object.new.freeze
+
     def self.normalize(raw_metadata)
       deep_freeze(round_trip(raw_metadata))
     end

data/lib/statecraft/mounting.rb

@@ -183,7 +183,9 @@ module Statecraft
             define_method(event_name) do |metadata: {}, seen: nil|
               fire(event_name, metadata: metadata, seen: seen)
             end
-            define_method("may_#{event_name}?") { |metadata: {}| can_fire?(event_name, metadata: metadata) }
+            define_method("may_#{event_name}?") do |metadata: Metadata::OMITTED|
+              can_fire?(event_name, metadata: metadata)
+            end
           end
         end
         model.include(verbs)

data/lib/statecraft/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Igor Pugachev
@@ -60,6 +60,11 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/statecraft/from_aasm/USAGE
+- lib/generators/statecraft/from_aasm/from_aasm_generator.rb
+- lib/generators/statecraft/from_aasm/templates/application_machine.rb.tt
+- lib/generators/statecraft/from_aasm/templates/create_log_table.rb.tt
+- lib/generators/statecraft/from_aasm/templates/machine_from_aasm.rb.tt
 - 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