event_engine 0.1.0

data/lib/event_engine.rb

@@ -0,0 +1,197 @@
+require_relative "event_engine/version"
+
+require "event_engine/engine"
+require "event_engine/configuration"
+require "event_engine/process_type"
+require "event_engine/event_definition"
+require "event_engine/lifecycle_definition"
+require "event_engine/event_builder"
+require "event_engine/handler_registry"
+require "event_engine/event_schema"
+require "event_engine/schema_registry"
+require "event_engine/subject_registry"
+require "event_engine/event"
+require "event_engine/dsl_compiler"
+require "event_engine/event_schema_loader"
+require "event_engine/event_schema_writer"
+require "event_engine/event_schema_merger"
+require "event_engine/event_schema_dumper"
+require "event_engine/schema_drift_guard"
+require "event_engine/schema_compatibility"
+require "event_engine/schema_catalog"
+require "event_engine/railtie"
+require "event_engine/definition_loader"
+require "event_engine/the_local"
+
+# EventEngine is the schema-first core of the event pipeline.
+#
+# Events are defined via a Ruby DSL and compiled into a canonical schema file.
+# At boot, a helper method is installed on this module for each registered event
+# (e.g. +EventEngine.cow_fed(cow: cow)+); the helper validates inputs, builds an
+# +Event+, and dispatches it to registered handlers by level. Companion gems
+# (e.g. event_engine-delivery) register handlers to process the events.
+#
+# @example Define, build, and dispatch an event
+#   EventEngine.register_handler(MyHandler, levels: :all)
+#   EventEngine.cow_fed(cow: cow, occurred_at: Time.current)
+module EventEngine
+  mattr_accessor :_installed_event_helpers, default: Set.new
+  class << self
+    # Returns the current configuration instance.
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for modification.
+    #
+    # @yieldparam config [Configuration] the configuration instance
+    # @example
+    #   EventEngine.configure do |config|
+    #     config.logger = Rails.logger
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    def handler_registry
+      @handler_registry ||= HandlerRegistry.new
+    end
+
+    def subject_registry
+      @subject_registry ||= SubjectRegistry.new
+    end
+
+    def define_subjects(&block)
+      subject_registry.instance_eval(&block)
+    end
+
+    def reset_subjects!
+      @subject_registry = nil
+    end
+
+    def enriched_metadata(call_site_metadata)
+      defaults = evaluated_metadata_defaults
+      return call_site_metadata if defaults.nil?
+
+      defaults.merge(call_site_metadata || {})
+    end
+
+    def evaluated_metadata_defaults
+      callable = configuration.metadata_defaults
+      return nil unless callable
+
+      callable.call
+    rescue => error
+      configuration.logger&.error("EventEngine metadata_defaults raised: #{error.message}")
+      nil
+    end
+
+    def register_handler(handler, levels:)
+      handler_registry.register(handler, levels: levels)
+    end
+
+    def dispatch(event)
+      handler_registry.dispatch(event)
+    end
+
+    def reset_handlers!
+      handler_registry.clear!
+    end
+
+    # Loads a schema file, populates the registry, and installs helper methods.
+    # Called automatically by the engine at Rails boot.
+    #
+    # @param schema_path [String, Pathname] path to the compiled schema file
+    # @param registry [SchemaRegistry] the registry to populate
+    # @return [EventSchema] the loaded schema
+    def boot_from_schema!(schema_path:, registry:)
+      event_schema = EventSchemaLoader.load(schema_path)
+
+      registry.reset!
+      registry.load_from_schema!(event_schema)
+
+      install_helpers(registry: registry)
+
+      event_schema
+    end
+
+    # Installs singleton helper methods on the EventEngine module for each
+    # event in the registry. Previous helpers are removed first.
+    #
+    # @param registry [SchemaRegistry] the loaded registry
+    def install_helpers(registry:)
+      _installed_event_helpers.each do |method_name|
+        singleton_class.remove_method(method_name) if singleton_class.method_defined?(method_name)
+      end
+      _installed_event_helpers.clear
+
+      registry.events.each do |event_name|
+        schema = registry.schema(event_name)
+
+        required = schema.required_inputs
+        optional = schema.optional_inputs
+
+        define_singleton_method(event_name) do |**args|
+          event_version = args.delete(:event_version)
+          occurred_at = args.delete(:occurred_at)
+          metadata = args.delete(:metadata)
+          idempotency_key = args.delete(:idempotency_key)
+          aggregate_type = args.delete(:aggregate_type)
+          aggregate_id = args.delete(:aggregate_id)
+          aggregate_version = args.delete(:aggregate_version)
+
+          input_keys = required + optional
+          inputs = args.slice(*input_keys)
+
+          missing = required - inputs.keys
+          raise ArgumentError, "Missing required inputs: #{missing.join(', ')}" if missing.any?
+
+          unknown = args.keys - input_keys
+          raise ArgumentError, "Unknown inputs: #{unknown.join(', ')}" if unknown.any?
+
+          schema = registry.schema(event_name, version: event_version)
+          attrs = EventBuilder.build(schema: schema, data: inputs)
+          attrs[:occurred_at] = occurred_at || Time.current
+          attrs[:metadata] = EventEngine.enriched_metadata(metadata)
+          attrs[:idempotency_key] = idempotency_key || SecureRandom.uuid
+          attrs[:aggregate_type] = aggregate_type
+          attrs[:aggregate_id] = aggregate_id
+          attrs[:aggregate_version] = aggregate_version
+          attrs[:process_type] = schema.process_type
+          attrs[:subject] = schema.subject
+          attrs[:domain] = schema.domain
+
+          EventEngine.dispatch(Event.new(**attrs))
+        end
+
+        _installed_event_helpers << event_name
+      end
+    end
+
+    # Compiles event definitions from source into a registry.
+    # Used by rake tasks for schema drift detection.
+    #
+    # @return [SchemaRegistry]
+    def compiled_schema_registry
+      DefinitionLoader.ensure_loaded!
+      definitions = EventDefinition.descendants
+      compiled = DslCompiler.compile(definitions)
+      registry = SchemaRegistry.new
+      registry.load_from_schema!(compiled)
+      registry
+    end
+
+    # Loads the committed schema file into a registry.
+    # Used by rake tasks for schema drift detection.
+    #
+    # @return [SchemaRegistry]
+    def file_schema_registry
+      loaded = EventSchemaLoader.load(Rails.root.join("db/event_schema.rb"))
+      registry = SchemaRegistry.new
+      registry.load_from_schema!(loaded)
+      registry
+    end
+  end
+end

data/lib/generators/event_engine/install_generator.rb

@@ -0,0 +1,31 @@
+module EventEngine
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install EventEngine (schema file, initializer, migrations)"
+
+      def create_event_schema
+        template "event_schema.rb", "db/event_schema.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/event_engine.rb"
+      end
+
+      def print_next_steps
+        say <<~MSG
+
+          EventEngine installed.
+
+          Next steps:
+            1. Define events in app/event_definitions/
+            2. Run: bin/rails event_engine:schema:dump
+            3. Commit db/event_schema.rb
+            4. Configure transport in config/initializers/event_engine.rb
+
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/event_engine/templates/event_schema.rb

@@ -0,0 +1,10 @@
+# This file is authoritative in production.
+# It is generated from EventDefinitions via:
+#
+#   bin/rails event_engine:schema:dump
+#
+# Do not edit manually.
+
+EventEngine::EventSchema.define do |schema|
+  # schema.register(...)
+end

data/lib/generators/event_engine/templates/initializer.rb

@@ -0,0 +1,4 @@
+EventEngine.configure do |c|
+  # Logger for EventEngine messages (defaults to Rails.logger)
+  # c.logger = Rails.logger
+end

data/lib/tasks/event_engine_catalog.rake

@@ -0,0 +1,13 @@
+namespace :event_engine do
+  desc "Render the event schema and subjects as a markdown catalog"
+  task catalog: :environment do
+    EventEngine::DefinitionLoader.ensure_loaded!
+
+    catalog = EventEngine::SchemaCatalog.new(
+      schema_registry: EventEngine.file_schema_registry,
+      subject_registry: EventEngine.subject_registry
+    )
+
+    puts catalog.to_markdown
+  end
+end

data/lib/tasks/event_engine_schema.rake

@@ -0,0 +1,82 @@
+namespace :event_engine do
+  desc "Fail if event schema DSL has drifted from db/event_schema.rb"
+  task schema: :environment do
+    EventEngine::DefinitionLoader.ensure_loaded!
+
+    descendants = EventEngine::EventDefinition.descendants
+
+    if descendants.empty?
+      raise <<~MSG
+        EventEngine found no EventDefinitions.
+
+        Expected definitions to be loaded during eager load.
+        Ensure they live in an eager-load path (e.g. app/event_definitions).
+      MSG
+    end
+
+    EventEngine::SchemaDriftGuard.check!(
+      schema_path: Rails.root.join("db/event_schema.rb"),
+      definitions: descendants
+    )
+  end
+
+  namespace :schema do
+    desc "Regenerate event_schema.rb from EventDefinitions"
+    task dump: :environment do
+      EventEngine::DefinitionLoader.ensure_loaded!
+
+      descendants = EventEngine::EventDefinition.descendants
+
+      if descendants.empty?
+        raise <<~MSG
+          EventEngine found no EventDefinitions.
+
+          Expected definitions to be loaded during eager load.
+          Ensure they live in an eager-load path (e.g. app/event_definitions).
+        MSG
+      end
+      
+      path = Rails.root.join("db/event_schema.rb")
+
+      EventEngine::EventSchemaDumper.dump!(
+        definitions: descendants,
+        path: path
+      )
+
+      puts "Dumping EventEngine schema to #{path}"
+    end
+
+    desc "Fail with a readable diff if definitions have drifted from db/event_schema.rb"
+    task verify: :environment do
+      EventEngine::DefinitionLoader.ensure_loaded!
+
+      descendants = EventEngine::EventDefinition.descendants
+
+      if descendants.empty?
+        raise <<~MSG
+          EventEngine found no EventDefinitions.
+
+          Expected definitions to be loaded during eager load.
+          Ensure they live in an eager-load path (e.g. app/event_definitions).
+        MSG
+      end
+
+      EventEngine::SchemaDriftGuard.check!(
+        schema_path: Rails.root.join("db/event_schema.rb"),
+        definitions: descendants
+      )
+    end
+
+    desc "Fail if new definitions break compatibility with the committed schema"
+    task compatibility: :environment do
+      EventEngine::DefinitionLoader.ensure_loaded!
+
+      violations = EventEngine::SchemaCompatibility.violations(
+        old_registry: EventEngine.file_schema_registry,
+        new_registry: EventEngine.compiled_schema_registry
+      )
+
+      raise "Breaking schema changes:\n#{violations.join("\n")}" if violations.any?
+    end
+  end
+end

data/lib/tasks/event_engine_schema_check.rake

@@ -0,0 +1,20 @@
+namespace :event_engine do
+  desc "Fail if event schema DSL has drifted from db/event_schema.rb"
+  task schema_check: :environment do
+    compiled = EventEngine.compiled_schema_registry
+    file = EventEngine.file_schema_registry
+
+    if EventEngine::EventSchemaMerger.changed?(compiled, file)
+      raise <<~MSG
+        Schema drift detected.
+
+        The compiled EventDefinitions differ from db/event_schema.rb.
+
+        Run:
+          bin/rails event_engine:schema:dump
+
+        Then commit the updated schema file.
+      MSG
+    end
+  end
+end

data/lib/tasks/event_engine_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :event_engine do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: event_engine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'The core of the EventEngine pipeline: define events with a Ruby DSL,
+  compile to a canonical schema, and dispatch built events to registered handlers
+  by level. Durable delivery, transports, the outbox, and the observability dashboard
+  live in the companion gem event_engine-delivery.'
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/event_engine_manifest.js
+- app/assets/stylesheets/event_engine/application.css
+- app/controllers/event_engine/application_controller.rb
+- app/helpers/event_engine/application_helper.rb
+- app/jobs/event_engine/application_job.rb
+- app/mailers/event_engine/application_mailer.rb
+- app/models/event_engine/application_record.rb
+- app/views/layouts/event_engine/application.html.erb
+- config/routes.rb
+- lib/event_engine.rb
+- lib/event_engine/configuration.rb
+- lib/event_engine/definition_loader.rb
+- lib/event_engine/dsl_compiler.rb
+- lib/event_engine/engine.rb
+- lib/event_engine/event.rb
+- lib/event_engine/event_builder.rb
+- lib/event_engine/event_definition.rb
+- lib/event_engine/event_definition/inputs.rb
+- lib/event_engine/event_definition/payloads.rb
+- lib/event_engine/event_definition/schemas.rb
+- lib/event_engine/event_definition/validation.rb
+- lib/event_engine/event_schema.rb
+- lib/event_engine/event_schema_dumper.rb
+- lib/event_engine/event_schema_loader.rb
+- lib/event_engine/event_schema_merger.rb
+- lib/event_engine/event_schema_writer.rb
+- lib/event_engine/handler_registry.rb
+- lib/event_engine/lifecycle_definition.rb
+- lib/event_engine/process_type.rb
+- lib/event_engine/railtie.rb
+- lib/event_engine/reference.rb
+- lib/event_engine/reference/guide.md
+- lib/event_engine/schema_catalog.rb
+- lib/event_engine/schema_compatibility.rb
+- lib/event_engine/schema_diff.rb
+- lib/event_engine/schema_drift_guard.rb
+- lib/event_engine/schema_registry.rb
+- lib/event_engine/subject_registry.rb
+- lib/event_engine/the_local.rb
+- lib/event_engine/the_local/agents/event_engine-develop.md
+- lib/event_engine/the_local/agents/event_engine-info.md
+- lib/event_engine/the_local/agents/event_engine-install.md
+- lib/event_engine/version.rb
+- lib/generators/event_engine/install_generator.rb
+- lib/generators/event_engine/templates/event_schema.rb
+- lib/generators/event_engine/templates/initializer.rb
+- lib/tasks/event_engine_catalog.rake
+- lib/tasks/event_engine_schema.rake
+- lib/tasks/event_engine_schema_check.rake
+- lib/tasks/event_engine_tasks.rake
+homepage: https://eventengine.co
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://eventengine.co
+  source_code_uri: https://github.com/DYB-Development/event_engine
+  changelog_uri: https://github.com/DYB-Development/event_engine/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/event_engine/issues
+  documentation_uri: https://github.com/DYB-Development/event_engine#readme
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Schema-first event definitions and dispatch for Rails
+test_files: []