feat: core enhancements - introspection, compensating transitions, and cross-machine support

[monotykamary]

feat: core enhancements - introspection, compensating transitions, cross-machine support, and state snapshots

Summary

This PR introduces core enhancements to FOSM-Rails focused on developer experience, introspection, cross-machine workflow support, and state snapshot capabilities. Following review, we simplified the DSL to be more Rails-like by removing force: and rescue: options in favor of cleaner patterns.

🚀 Features Added

1. Guard Error Messages

Guards can now return rich values: true, false, "failure reason", or [:fail, "reason"].

lifecycle do
  guard :has_items, on: :send do |inv|
    inv.items.any? || "At least one item required"
  end
  
  guard :valid_email, on: :send do |inv|
    inv.email =~ /@/ ? true : [ :fail, "Invalid email format" ]
  end
end

# Error messages flow through to exceptions and diagnostics
invoice.fire!(:send, actor: user) 
# => raises Fosm::GuardFailed with message: "Guard 'has_items' failed: At least one item required"

2. why_cannot_fire? Introspection

New method returns detailed diagnostics for any failed transition—perfect for debugging and UI error messages.

result = invoice.why_cannot_fire?(:send)
# => {
#   can_fire: false,
#   reason: "Guard 'has_items' failed: At least one item required",
#   current_state: "draft",
#   event: "send",
#   is_terminal: false,
#   passed_guards: [:valid_email],
#   failed_guards: [
#     { name: :has_items, reason: "At least one item required" }
#   ],
#   valid_from_states: [:draft]
# }

3. Terminal State Enforcement

Terminal states are now truly terminal—no bypass mechanisms. Compensating workflows should be modeled explicitly with non-terminal states.

lifecycle do
  state :paid, terminal: true
  state :refunded, terminal: true
  
  # Terminal states block ALL transitions
  event :refund, from: :paid, to: :refunded  # Also terminal, but valid from :paid
end

invoice.paid? # => true (terminal)
invoice.can_fire?(:refund)  # => false (terminal blocks all events)

# Raises Fosm::TerminalState
invoice.refund!(actor: :test)  # => raises TerminalState

4. Side Effects — Errors Propagate Naturally

Side effects run inside the transaction and errors propagate. Host apps can add their own rescue blocks if recovery is needed.

lifecycle do
  # Default behavior - fails the transition on error
  side_effect :critical_webhook, on: :pay do |inv|
    PaymentGateway.charge!(inv)
  end
  
  # Host app handles recovery in the block
  side_effect :notify_slack, on: :pay do |inv|
    Slack.notify("Invoice #{inv.id} paid")
  rescue => e
    Rails.logger.error("Slack notify failed: #{e.message}")
    # Transition continues because we rescued
  end
end

5. Deferred Side Effects (defer: true)

Run side effects via after_commit callbacks to solve SQLite/database locking with cross-machine triggers.

class Invoice < ApplicationRecord
  lifecycle do
    event :complete, from: :in_progress, to: :completed
    
    # Deferred side effect runs AFTER transaction commits
    # Perfect for triggering other state machines
    side_effect :activate_contract, on: :complete, defer: true do |invoice, transition|
      invoice.contract&.activate!(actor: :system)
    end
  end
end

class Contract < ApplicationRecord
  lifecycle do
    state :pending, initial: true
    state :active
    
    # This transition fires in its own transaction, no deadlock
    event :activate, from: :pending, to: :active
  end
end

6. Auto-captured Causal Chain Tracking

When fire! is called from within a side effect, the triggering context is automatically captured via thread-local storage and included in transition logs.

# Invoice completes and triggers contract activation via deferred side effect
invoice.complete!(actor: user)

# TransitionLog for contract activation automatically includes:
# triggered_by: {
#   record_type: "Fosm::Invoice",
#   record_id: 456,
#   event_name: "complete"
# }

# Query the causal chain
contract.transition_logs.last.metadata["triggered_by"]
# => { "record_type" => "Fosm::Invoice", "event_name" => "complete", ... }

7. Graph Generation (fosm:graph:generate)

Generate JSON graph representations for visual state machine exploration.

# Generate graph for single model
$ rake fosm:graph:generate MODEL=Invoice
Generated: app/assets/graphs/invoice_graph.json

# Generate system-wide dependency graph
$ rake fosm:graph:generate MODEL=Invoice SYSTEM=true
Generated: app/assets/graphs/fosm_system_graph.json

{
  "machine": "Fosm::Invoice",
  "states": [
    { "name": "draft", "initial": true, "terminal": false },
    { "name": "paid", "initial": false, "terminal": true }
  ],
  "events": [
    {
      "name": "send",
      "from": ["draft"],
      "to": "sent",
      "guards": ["has_items"],
      "side_effects": ["send_notification"]
    }
  ],
  "cross_machine_connections": [
    {
      "source": { "machine": "Fosm::Order", "event": "complete" },
      "via": "activate_contract",
      "target_machine": "Fosm::Contract"
    }
  ]
}

8. State Snapshots 🎯

Inspired by let-it-race's horizontal event-sourcing pattern, FOSM now supports flexible state snapshots on transitions. Capture both schema state (database attributes) and arbitrary observations (adhoc data that doesn't fit your schema).

Multiple Snapshot Strategies

lifecycle do
  snapshot :every                    # Every transition
  snapshot every: 10                 # Every 10 transitions
  snapshot time: 300                   # If > 5 min since last snapshot
  snapshot :terminal                  # Only on terminal states
  snapshot :manual                    # Only when explicitly requested (default)
  
  # What to capture from schema
  snapshot_attributes :amount, :line_items_count, :state
  # If not specified, defaults to all non-internal attributes
end

Schema + Arbitrary Observations

# Capture both database state AND messy observational data
invoice.pay!(
  actor: user,
  snapshot_data: {
    # Arbitrary observations that don't fit your schema
    external_ref: "pi_123456",
    risk_score: 0.85,
    ip_address: "192.168.1.1",
    geo_location: { country: "US", city: "NYC" },
    raw_webhook_payload: webhook_body,
    fraud_check_result: { status: "passed", provider: "maxmind" }
  }
)

The resulting state_snapshot JSON combines both:

{
  "amount": 100.00,
  "line_items_count": 5,
  "state": "paid",
  "_fosm_snapshot_meta": {
    "snapshot_at": "2024-03-22T08:45:00Z",
    "record_class": "Fosm::Invoice",
    "record_id": "123"
  },
  "_observations": {
    "external_ref": "pi_123456",
    "risk_score": 0.85,
    "ip_address": "192.168.1.1",
    "geo_location": { "country": "US", "city": "NYC" },
    "raw_webhook_payload": { "event": "payment_intent.created" }
  }
}

Manual Snapshot Override

# Force a snapshot even if strategy wouldn't trigger
invoice.pay!(actor: user, metadata: { snapshot: true })

# Opt out of automatic snapshot
invoice.pay!(actor: user, metadata: { snapshot: false })

Basic Query Methods

# Get most recent snapshot
invoice.last_snapshot  # => Fosm::TransitionLog entry
invoice.last_snapshot_data  # => the snapshot hash

# Get all snapshots
invoice.snapshots  # => ActiveRecord::Relation

# Simple replay from a specific transition
invoice.replay_from(transition_log_id) { |log| puts log.event_name }

# Check if a log entry has a snapshot
log.snapshot?  # => true/false

TransitionLog Scopes

Fosm::TransitionLog.with_snapshot           # Only entries with snapshots
Fosm::TransitionLog.without_snapshot        # Only entries without snapshots
Fosm::TransitionLog.by_snapshot_reason("terminal")  # Filter by reason

When to Use Observations vs Schema

Use case	Store in schema?	Store in observations?
Core business data (amount, status)	✅ Yes
External system refs (stripe_id)	Maybe	✅ Yes (if volatile)
Risk/fraud scores		✅ Yes (ephemeral)
Raw webhook payloads		✅ Yes (large/complex)
Geolocation data	Maybe	✅ Yes (if analytics only)
Calculated metrics	Maybe	✅ Yes (if expensive to recompute)

This captures let-it-race's "messy truth" pattern—you're not forced to decide upfront what data matters. Capture everything in observations, then later promote frequently-used observations to proper schema columns.

🧪 Model-Based Testing

Our comprehensive test suite demonstrates real-world usage patterns. See test/models/snapshot_test.rb for snapshot verification tests.

🔒 Race Condition Fix (SELECT FOR UPDATE)

This PR includes protection against race conditions in concurrent fire! calls using SELECT FOR UPDATE row locking.

📊 Test Coverage

All tests passing with Rubocop 0 offenses.

🔄 Simplifications Made

• Removed force: true - Terminal states are truly terminal
• Removed rescue: strategies - Side effects propagate errors naturally
• Enhanced triggered_by auto-capture - No manual passing needed

📝 Files Changed

• lib/fosm/lifecycle.rb - Core lifecycle with snapshot support
• lib/fosm/lifecycle/definition.rb - DSL for snapshot configuration
• lib/fosm/lifecycle/snapshot_configuration.rb - Snapshot strategies
• app/models/fosm/transition_log.rb - Snapshot scopes and helpers
• db/migrate/20240101000005_add_state_snapshot_to_fosm_transition_logs.rb - Migration
• Test infrastructure and comprehensive test suite

🔍 Code Quality

• Rubocop: All files, 0 offenses
• Tests: All passing
• CI: All checks passing (lint + test)

Ready for review and merge! 🚀