event_engine 0.1.0

data/config/routes.rb

@@ -0,0 +1,2 @@
+EventEngine::Engine.routes.draw do
+end

data/lib/event_engine/configuration.rb

@@ -0,0 +1,20 @@
+module EventEngine
+  # Holds configuration options for EventEngine core.
+  #
+  # @example
+  #   EventEngine.configure do |config|
+  #     config.logger = Rails.logger
+  #   end
+  class Configuration
+    # @!attribute [rw] logger
+    #   Logger instance for EventEngine messages.
+    #   @return [Logger] defaults to +Rails.logger+
+    attr_accessor :logger
+
+    attr_accessor :metadata_defaults
+
+    def initialize
+      @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    end
+  end
+end

data/lib/event_engine/definition_loader.rb

@@ -0,0 +1,26 @@
+module EventEngine
+  module DefinitionLoader
+    class << self
+      def ensure_loaded!
+        eager_load_definitions!
+        LifecycleDefinition.materialize_all!
+      end
+
+      def eager_load_definitions!
+        return if loaded?
+
+        unless defined?(Rails) && Rails.application
+          raise "EventEngine requires a Rails application to load definitions"
+        end
+
+        Rails.application.eager_load!
+
+        @loaded = true
+      end
+
+      def loaded?
+        @loaded ||= false
+      end
+    end
+  end
+end

data/lib/event_engine/dsl_compiler.rb

@@ -0,0 +1,50 @@
+module EventEngine
+  class DslCompiler
+    class InvalidEventNameError < StandardError; end
+
+    SNAKE_CASE = /\A[a-z][a-z0-9_]*\z/
+
+    def self.compile(definitions)
+      registry = SchemaRegistry.new
+      subject_violations = []
+      name_violations = []
+
+      Array(definitions).each do |definition|
+        schema = definition.schema
+        record_subject_violation(schema, subject_violations)
+        record_name_violation(schema, name_violations)
+        registry.register(schema)
+      end
+
+      raise_invalid_event_names(name_violations)
+      raise_unknown_subjects(subject_violations)
+
+      registry
+    end
+
+    def self.record_name_violation(schema, violations)
+      return if schema.event_name.to_s.match?(SNAKE_CASE)
+
+      violations << schema.event_name.inspect
+    end
+
+    def self.raise_invalid_event_names(violations)
+      return if violations.empty?
+
+      raise InvalidEventNameError, "event names must be snake_case: #{violations.join(", ")}"
+    end
+
+    def self.record_subject_violation(schema, violations)
+      return if schema.subject.nil?
+      return if EventEngine.subject_registry.registered?(schema.subject)
+
+      violations << "#{schema.event_name}: unknown subject #{schema.subject.inspect}"
+    end
+
+    def self.raise_unknown_subjects(violations)
+      return if violations.empty?
+
+      raise SubjectRegistry::UnknownSubjectError, violations.join(", ")
+    end
+  end
+end

data/lib/event_engine/engine.rb

@@ -0,0 +1,56 @@
+module EventEngine
+  class Engine < ::Rails::Engine
+    isolate_namespace EventEngine
+
+    initializer "event_engine.load_schema_and_install_helpers" do |app|
+      app.config.after_initialize do
+        schema_path = Rails.root.join("db", "event_schema.rb")
+
+        if File.exist?(schema_path)
+          Engine.send(
+            :load_schema_and_install_helpers,
+            schema_path: schema_path
+          )
+        else
+          Engine.send(
+            :handle_missing_schema!,
+            schema_path
+          )
+        end
+      end
+    end
+
+    class << self
+      private
+
+      def load_schema_and_install_helpers(schema_path:)
+        EventEngine.boot_from_schema!(
+          schema_path: schema_path,
+          registry: EventEngine::SchemaRegistry.new
+        )
+      end
+
+      def handle_missing_schema!(schema_path)
+        if Rails.env.development? || Rails.env.test?
+          Rails.logger.warn(
+            "[EventEngine] Schema file not found at #{schema_path}. " \
+            "Run: bin/rails event_engine:schema:dump"
+          )
+          return
+        end
+
+        raise <<~MSG
+          EventEngine schema file missing.
+
+          Expected to find:
+            #{schema_path}
+
+          Run:
+            bin/rails event_engine:schema:dump
+
+          And commit the generated file.
+        MSG
+      end
+    end
+  end
+end

data/lib/event_engine/event.rb

@@ -0,0 +1,32 @@
+module EventEngine
+  # A non-persisted, in-memory representation of an emitted event with a
+  # symbol-keyed payload. Passed to subscribers' +#handle(event)+ at every
+  # in-process level (1-3), and returned by the emitter for levels 1 and 2.
+  Event = Struct.new(
+    :event_name,
+    :event_type,
+    :event_version,
+    :process_type,
+    :subject,
+    :domain,
+    :payload,
+    :metadata,
+    :occurred_at,
+    :idempotency_key,
+    :aggregate_type,
+    :aggregate_id,
+    :aggregate_version,
+    keyword_init: true
+  ) do
+    # Builds an Event from a record responding to the same members (e.g. an
+    # OutboxEvent), normalizing the payload to symbol keys.
+    #
+    # @param record [#payload]
+    # @return [Event]
+    def self.from(record)
+      attrs = members.to_h { |member| [member, record.public_send(member)] }
+      attrs[:payload] = attrs[:payload].to_h.transform_keys(&:to_sym)
+      new(**attrs)
+    end
+  end
+end

data/lib/event_engine/event_builder.rb

@@ -0,0 +1,45 @@
+module EventEngine
+  # Constructs an event payload hash from a schema and input data.
+  # Validates that required inputs are present and no unknown inputs are passed.
+  class EventBuilder
+    # Builds an event attributes hash from schema and input data.
+    #
+    # @param schema [EventDefinition::Schema] the event schema
+    # @param data [Hash] input data keyed by input name
+    # @return [Hash] event attributes including :event_name, :event_type, :event_version, :payload
+    # @raise [ArgumentError] if required inputs are missing or unknown inputs are provided
+    def self.build(schema:, data:)
+      validate_inputs!(schema, data)
+
+      payload = {}
+
+      schema.payload_fields.each do |field|
+        input = data[field[:from]]
+        next if input.nil? && !field[:required]
+
+        value = field[:attr] ? input.public_send(field[:attr]) : input
+        payload[field[:name]] = value
+      end
+
+      {
+        event_name: schema.event_name,
+        event_type: schema.event_type,
+        event_version: schema.event_version,
+        payload: payload
+      }
+    end
+
+    private
+
+    def self.validate_inputs!(schema, data)
+      data_keys = data.keys.map(&:to_sym)
+
+      missing = schema.required_inputs - data_keys
+      raise ArgumentError, "missing required input: #{missing.join(', ')}" if missing.any?
+
+      allowed = schema.required_inputs + schema.optional_inputs
+      unknown = data_keys - allowed
+      raise ArgumentError, "unknown input: #{unknown.join(', ')}" if unknown.any?
+    end
+  end
+end

data/lib/event_engine/event_definition/inputs.rb

@@ -0,0 +1,43 @@
+module EventEngine
+  class EventDefinition
+    # DSL methods for declaring required and optional inputs on an event definition.
+    module Inputs
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Declares a required input for this event.
+        #
+        # @param name [Symbol] the input name
+        # @raise [ArgumentError] if the input is already declared
+        def input(name)
+          name = name.to_sym
+          if inputs.key?(name)
+            raise ArgumentError, "duplicate input: #{name}"
+          end
+          inputs[name] = :required
+        end
+
+        # Declares an optional input for this event.
+        #
+        # @param name [Symbol] the input name
+        # @raise [ArgumentError] if the input is already declared
+        def optional_input(name)
+          name = name.to_sym
+          if inputs.key?(name)
+            raise ArgumentError, "duplicate input: #{name}"
+          end
+          inputs[name] = :optional
+        end
+
+        # Returns all declared inputs as a hash of name => :required/:optional.
+        #
+        # @return [Hash{Symbol => Symbol}]
+        def inputs
+          @inputs ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/event_definition/payloads.rb

@@ -0,0 +1,47 @@
+module EventEngine
+  class EventDefinition
+    # DSL methods for declaring payload fields on an event definition.
+    module Payloads
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Declares an optional payload field.
+        #
+        # @param name [Symbol] the field name in the event payload
+        # @param from [Symbol] the input to extract the value from
+        # @param attr [Symbol, nil] method to call on the input (nil for passthrough)
+        def optional_payload(name, from: nil, attr: nil)
+          payload_fields << {
+            name: name.to_sym,
+            required: false,
+            from: from,
+            attr: attr
+          }
+        end
+
+        # Declares a required payload field.
+        #
+        # @param name [Symbol] the field name in the event payload
+        # @param from [Symbol] the input to extract the value from
+        # @param attr [Symbol, nil] method to call on the input (nil for passthrough)
+        def required_payload(name, from: nil, attr: nil)
+          payload_fields << {
+            name: name.to_sym,
+            required: true,
+            from: from,
+            attr: attr
+          }
+        end
+
+        # Returns all declared payload field definitions.
+        #
+        # @return [Array<Hash>]
+        def payload_fields
+          @payload_fields ||= []
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/event_definition/schemas.rb

@@ -0,0 +1,158 @@
+module EventEngine
+  class EventDefinition
+    # Provides schema generation and fingerprinting for event definitions.
+    module Schemas
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # Immutable representation of a compiled event schema.
+      # Holds the event identity, inputs, and payload field definitions.
+      # Used both at development time (compilation) and runtime (registry).
+      class Schema < Struct.new(
+        :event_name,
+        :event_version,
+        :event_type,
+        :process_type,
+        :subject,
+        :domain,
+        :required_inputs,
+        :optional_inputs,
+        :payload_fields,
+        keyword_init: true
+      )
+
+        # Returns a SHA256 fingerprint of the schema's canonical representation.
+        # Used to detect schema changes and trigger version bumps.
+        #
+        # @return [String] hex-encoded SHA256 digest
+        def fingerprint
+          Digest::SHA256.hexdigest(
+            canonical_representation
+          )
+        end
+
+        # Serializes the schema to a Ruby source string for the schema file.
+        #
+        # @return [String]
+        def to_ruby
+          <<~RUBY.strip
+            EventEngine::EventDefinition::Schema.new(
+              event_name: #{event_name.inspect},
+              event_version: #{event_version.inspect},
+              event_type: #{event_type.inspect},
+              process_type: #{process_type.inspect},
+              subject: #{subject.inspect},
+              domain: #{domain.inspect},
+              required_inputs: #{required_inputs.inspect},
+              optional_inputs: #{optional_inputs.inspect},
+              payload_fields: [#{payload_fields.map { |h| ruby_hash(h) }.join(", ")}]
+            )
+          RUBY
+        end
+
+        private
+
+        def canonical_representation
+          {
+            event_name: event_name.to_s,
+            event_type: event_type.to_s,
+            required_inputs: required_inputs.map(&:to_s).sort,
+            optional_inputs: optional_inputs.map(&:to_s).sort,
+            payload_fields: payload_fields
+              .map { |h| h.transform_values { |v| v.to_s } }
+              .sort_by { |h| h[:name].to_s }
+          }.to_json
+        end
+
+        def ruby_hash(hash)
+          inner = hash.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+          "{#{inner}}"
+        end
+      end
+
+      module ClassMethods
+        # Builds and returns a {Schema} from this definition's DSL declarations.
+        #
+        # @return [Schema]
+        # @raise [ArgumentError] if the definition has validation errors
+        def schema
+          errors = schema_errors
+          raise ArgumentError, errors.join(", ") if errors.any?
+
+          required = inputs.select { |_, v| v== :required }.keys
+          optional = inputs.select { |_, v| v== :optional }.keys
+
+          Schema.new(
+            event_name: @event_name,
+            event_type: @event_type,
+            process_type: @process_type,
+            subject: @subject,
+            domain: @domain,
+            required_inputs: required,
+            optional_inputs: optional,
+            payload_fields: payload_fields
+          )
+        end
+
+        # Returns validation errors for this definition, if any.
+        #
+        # @return [Array<String>]
+        def schema_errors
+          errors = []
+          validate_identity(errors)
+          validate_process_type(errors)
+          validate_payload_fields(errors)
+          errors
+        end
+
+        # Whether this definition has a valid schema (no errors).
+        #
+        # @return [Boolean]
+        def valid_schema?
+          schema_errors.empty?
+        end
+
+        private
+
+        def validate_identity(errors)
+          errors << "event_name is required" unless @event_name
+          errors << "event_type is required" unless @event_type
+        end
+
+        def validate_process_type(errors)
+          return if @process_type.nil? || ProcessType.known?(@process_type)
+          errors << "process_type is unknown: #{@process_type.inspect}"
+        end
+
+        def validate_payload_fields(errors)
+          seen = {}
+
+          payload_fields.each do |field|
+            name = field[:name]
+
+            if seen[name]
+              errors << "duplicate payload field: #{name}"
+            end
+
+            if RESERVED_PAYLOAD_FIELDS.include?(name)
+              errors << "payload field uses reserved name: #{name}"
+            end
+
+            if field[:from].nil?
+              errors << "payload field #{name} must have a from:"
+            end
+
+            unless inputs.key?(field[:from])
+              errors << "payload field #{name} references unknown input: #{field[:from]}"
+            end
+
+            # attr: is optional - when omitted, input value is used directly (passthrough)
+
+            seen[name] = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/event_definition/validation.rb

@@ -0,0 +1,18 @@
+module EventEngine
+  class EventDefinition
+    module Validation
+      def validate_inputs!(inputs)
+        declared = self.class.inputs
+        provided = inputs.keys.map(&:to_sym)
+
+        return if declared.empty?
+
+        missing = declared - provided
+        raise ArgumentError, "missing input: #{missing.join(', ')}" if missing.any?
+
+        extra = provided - declared
+        raise ArgumentError, "undeclared input: #{extra.join(', ')}" if extra.any?
+      end
+    end
+  end
+end

data/lib/event_engine/event_definition.rb

@@ -0,0 +1,76 @@
+require "event_engine/event_definition/inputs"
+require "event_engine/event_definition/payloads"
+require "event_engine/event_definition/validation"
+require "event_engine/event_definition/schemas"
+
+module EventEngine
+  # Base class for defining events using the EventEngine DSL.
+  #
+  # Subclass this to declare an event's name, type, inputs, and payload fields.
+  # Definitions are compiled into a schema file at development time and are
+  # not used at runtime.
+  #
+  # @example Define an event
+  #   class CowFed < EventEngine::EventDefinition
+  #     input :cow
+  #     optional_input :farmer
+  #
+  #     event_name :cow_fed
+  #     event_type :domain
+  #
+  #     required_payload :weight, from: :cow, attr: :weight
+  #     optional_payload :farmer_name, from: :farmer, attr: :name
+  #   end
+  class EventDefinition
+    # Payload field names reserved by the outbox schema.
+    RESERVED_PAYLOAD_FIELDS = %i[
+      event_name
+      event_type
+      event_version
+      occurred_at
+      created_at
+      updated_at
+      published_at
+      metadata
+      idempotency_key
+      attempts
+      dead_lettered_at
+      aggregate_type
+      aggregate_id
+      aggregate_version
+    ].freeze
+
+    include Inputs
+    include Payloads
+    include Validation
+    include Schemas
+
+    class << self
+      # Sets the event name for this definition.
+      #
+      # @param value [Symbol] the event name (e.g. +:cow_fed+)
+      def event_name(value)
+        @event_name = value
+      end
+
+      # Sets the event type for this definition.
+      #
+      # @param value [Symbol] the event type (e.g. +:domain+, +:integration+)
+      def event_type(value)
+        @event_type = value
+      end
+
+      def process_type(value)
+        @process_type = value
+      end
+
+      def subject(value)
+        @subject = value
+      end
+
+      def domain(value)
+        @domain = value
+      end
+    end
+  end
+end

data/lib/event_engine/event_schema.rb

@@ -0,0 +1,99 @@
+module EventEngine
+  # Container for all event schemas, organized by event name and version.
+  # This is the data structure loaded from the compiled +db/event_schema.rb+ file
+  # and used by {SchemaRegistry} at runtime.
+  class EventSchema
+    class DuplicateEventNameError < StandardError; end
+
+    # Creates an EventSchema using a block DSL (used by the schema file).
+    #
+    # @yieldparam schema [EventSchema]
+    # @return [EventSchema]
+    def self.define(&block)
+      schema = new
+      block.call(schema)
+      schema
+    end
+
+    def initialize
+      @schemas_by_event = {}
+      @finalized = false
+    end
+
+    # Registers a schema for a specific event name and version.
+    #
+    # @param schema [EventDefinition::Schema]
+    # @raise [FrozenError] if the schema has been finalized
+    def register(schema)
+      raise FrozenError, "EventSchema is finalized" if @finalized
+      event_name = schema.event_name
+      version = schema.event_version
+
+      @schemas_by_event[event_name] ||= {}
+      guard_duplicate_event_name!(@schemas_by_event[event_name][version], schema)
+      @schemas_by_event[event_name][version] = schema
+    end
+
+    def guard_duplicate_event_name!(existing, incoming)
+      return unless existing
+
+      raise DuplicateEventNameError,
+            "duplicate event_name #{incoming.event_name.inspect}: " \
+            "already registered with domain #{existing.domain.inspect}, " \
+            "cannot register again with domain #{incoming.domain.inspect}"
+    end
+
+    # Returns all registered event names.
+    #
+    # @return [Array<Symbol>]
+    def events
+      @schemas_by_event.keys
+    end
+
+    # Returns sorted version numbers for a given event.
+    #
+    # @param event_name [Symbol]
+    # @return [Array<Integer>]
+    def versions_for(event_name)
+      versions = @schemas_by_event[event_name]
+      return [] unless versions
+      versions.keys.sort
+    end
+
+    # Returns the schema for a specific event name and version.
+    #
+    # @param event_name [Symbol]
+    # @param version [Integer]
+    # @return [EventDefinition::Schema, nil]
+    def schema_for(event_name, version)
+      @schemas_by_event.dig(event_name, version)
+    end
+
+    # Returns the latest (highest version) schema for an event.
+    #
+    # @param event_name [Symbol]
+    # @return [EventDefinition::Schema, nil]
+    def latest_for(event_name)
+      versions = @schemas_by_event[event_name]
+      return nil unless versions && !versions.empty?
+      versions[versions.keys.max]
+    end
+
+    # Freezes the schema, preventing further registrations.
+    #
+    # @return [void]
+    def finalize!
+      @finalized = true
+      @schemas_by_event.each_value(&:freeze)
+      @schemas_by_event.freeze
+      freeze
+    end
+
+    # Returns the internal hash of schemas keyed by event name and version.
+    #
+    # @return [Hash{Symbol => Hash{Integer => EventDefinition::Schema}}]
+    def schemas_by_event
+      @schemas_by_event
+    end
+  end
+end

data/lib/event_engine/event_schema_dumper.rb

@@ -0,0 +1,13 @@
+module EventEngine
+  class EventSchemaDumper
+    def self.dump!(definitions:, path:)
+      compiled_schema = DslCompiler.compile(definitions)
+      compiled_schema.finalize!
+
+      loaded_schema = EventSchemaLoader.load(path)
+      merged_schema = EventSchemaMerger.merge(compiled_schema, loaded_schema)
+
+      EventSchemaWriter.write(path, merged_schema)
+    end
+  end
+end