event_engine 0.1.0

data/lib/event_engine/event_schema_loader.rb

@@ -0,0 +1,37 @@
+module EventEngine
+  class EventSchemaLoader
+    def self.load(path)
+      registry = SchemaRegistry.new
+      return registry unless File.exist?(path)
+
+      contents = File.read(path.to_s)
+      return registry if contents.strip.empty?
+
+      sandbox = Module.new
+      sandbox.const_set(:EventEngine, EventEngine)
+
+      schema =
+        sandbox.module_eval(contents, path.to_s)
+
+      unless schema.is_a?(EventEngine::EventSchema)
+        raise <<~MSG
+          Invalid EventEngine schema file.
+
+          Expected #{path} to return an EventSchema from:
+            EventEngine::EventSchema.define { ... }
+
+          But got:
+            #{schema.inspect}
+        MSG
+      end
+
+      schema.schemas_by_event.each_value do |versions|
+        versions.each_value do |s|
+          registry.register(s)
+        end
+      end
+
+      registry
+    end
+  end
+end

data/lib/event_engine/event_schema_merger.rb

@@ -0,0 +1,62 @@
+module EventEngine
+  class EventSchemaMerger
+    def self.merge(compiled_registry, file_registry)
+      merged = EventSchema.new
+
+      file_loaded_schema = file_registry.event_schema
+
+      file_loaded_schema.events.each do |event|
+        file_loaded_schema.versions_for(event).each do |version|
+          merged.register(file_loaded_schema.schema_for(event, version))
+        end
+      end
+
+      # Merge compiled schemas
+      compiled_registry.events.each do |event|
+        compiled_schema = compiled_registry.latest_for(event)
+
+        existing_versions = merged.versions_for(event)
+        latest_version = existing_versions.max
+        latest_schema = latest_version && merged.schema_for(event, latest_version)
+
+        if no_schema_change?(latest_schema, compiled_schema)
+          next
+        end
+
+        new_version = version(latest_version)
+        new_schema = compiled_schema.dup
+        new_schema.event_version = new_version
+
+        merged.register(new_schema)
+      end
+
+      merged.finalize!
+
+      merged
+    end
+
+    def self.changed?(compiled_registry, file_registry)
+      compiled_registry.events.any? do |event|
+        compiled_schema = compiled_registry.latest_for(event)
+
+        existing_versions = file_registry.versions_for(event)
+        latest_version = existing_versions.max
+        latest_schema = latest_version && file_registry.schema(event, version: latest_version)
+
+        # New event entirely
+        return true unless latest_schema
+
+        # Fingerprint mismatch means a new version would be created
+        latest_schema.fingerprint != compiled_schema.fingerprint
+      end
+    end
+
+    def self.no_schema_change?(latest_schema, compiled_schema)
+      latest_schema && latest_schema.fingerprint == compiled_schema.fingerprint
+    end
+
+    def self.version(latest_version)
+      (latest_version || 0) + 1
+    end
+  end
+end

data/lib/event_engine/event_schema_writer.rb

@@ -0,0 +1,47 @@
+module EventEngine
+  class EventSchemaWriter
+    HEADER = <<~RUBY.freeze
+      # This file is authoritative in production.
+      # It is generated from EventDefinitions via:
+      #
+      #   bin/rails event_engine:schema:dump
+      #
+      # Do not edit manually.
+
+    RUBY
+
+    def self.write(path, event_schema)
+      schemas =
+        event_schema
+          .schemas_by_event
+          .flat_map { |_event, versions| versions.values }
+          .sort_by { |s| [s.event_name.to_s, s.event_version] }
+
+      File.open(path, "w") do |io|
+        io.write(HEADER)
+        io.write("EventEngine::EventSchema.define do |schema|\n")
+
+        schemas.each do |definition|
+          write_definition(io, definition)
+        end
+
+        io.write("end\n")
+      end
+    end
+
+    def self.write_definition(io, definition)
+      io.write("  schema.register(\n")
+      indent(io, 4) { definition.to_ruby }
+      io.write("  )\n")
+    end
+
+    def self.indent(io, spaces)
+      padding = " " * spaces
+      yield.each_line do |line|
+        io.write(padding)
+        io.write(line)
+        io.write("\n")
+      end
+    end
+  end
+end

data/lib/event_engine/handler_registry.rb

@@ -0,0 +1,23 @@
+module EventEngine
+  class HandlerRegistry
+    def initialize
+      @handlers = []
+    end
+
+    def register(handler, levels:)
+      @handlers << { handler: handler, levels: levels }
+    end
+
+    def dispatch(event)
+      @handlers.each do |registration|
+        levels = registration[:levels]
+        registration[:handler].call(event) if levels == :all || levels.include?(event.process_type)
+      end
+      event
+    end
+
+    def clear!
+      @handlers.clear
+    end
+  end
+end

data/lib/event_engine/lifecycle_definition.rb

@@ -0,0 +1,86 @@
+require "event_engine/event_definition"
+
+module EventEngine
+  class LifecycleDefinition
+    include EventDefinition::Inputs
+    include EventDefinition::Payloads
+
+    class << self
+      def subject(value)
+        @subject = value
+      end
+
+      def event_type(value)
+        @event_type = value
+      end
+
+      def process_type(value)
+        @process_type = value
+      end
+
+      def lifecycle(*verbs)
+        @verbs = verbs
+      end
+
+      def on(verb, &block)
+        verb_overrides[verb] = block
+      end
+
+      def verb_overrides
+        @verb_overrides ||= {}
+      end
+
+      def generated_events
+        @generated_events ||= Array(@verbs).map { |verb| build_event(verb) }
+      end
+
+      def materialize_all!
+        subclasses.flat_map(&:generated_events)
+      end
+
+      def declared_subject
+        @subject
+      end
+
+      def declared_event_type
+        @event_type
+      end
+
+      def declared_process_type
+        @process_type
+      end
+
+      private
+
+      def build_event(verb)
+        template = self
+        name = :"#{template.declared_subject}_#{verb}"
+
+        Class.new(EventDefinition) do
+          event_name name
+          event_type template.declared_event_type
+
+          define_singleton_method(:inspect) { "EventEngine::LifecycleDefinition(#{name})" }
+          define_singleton_method(:to_s) { inspect }
+          subject template.declared_subject
+          process_type template.declared_process_type if template.declared_process_type
+
+          template.inputs.each do |name, kind|
+            kind == :required ? input(name) : optional_input(name)
+          end
+
+          template.payload_fields.each do |field|
+            if field[:required]
+              required_payload field[:name], from: field[:from], attr: field[:attr]
+            else
+              optional_payload field[:name], from: field[:from], attr: field[:attr]
+            end
+          end
+
+          override = template.verb_overrides[verb]
+          class_eval(&override) if override
+        end
+      end
+    end
+  end
+end

data/lib/event_engine/process_type.rb

@@ -0,0 +1,26 @@
+module EventEngine
+  module ProcessType
+    ALL = %i[inline background durable broker telemetry sourced].freeze
+
+    PROCESSORS = {
+      inline: :subscribers,
+      background: :subscribers,
+      durable: :delivery,
+      broker: :delivery,
+      telemetry: :telemetry,
+      sourced: :sourcing
+    }.freeze
+
+    def self.all
+      ALL
+    end
+
+    def self.processor_for(type)
+      PROCESSORS[type]
+    end
+
+    def self.known?(type)
+      ALL.include?(type)
+    end
+  end
+end

data/lib/event_engine/railtie.rb

@@ -0,0 +1,9 @@
+module EventEngine
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "tasks/event_engine_tasks.rake"
+      load "tasks/event_engine_schema.rake"
+      load "tasks/event_engine_schema_check.rake"
+    end
+  end
+end

data/lib/event_engine/reference/guide.md

@@ -0,0 +1,129 @@
+## EventEngine
+
+> **DO NOT** explore the event_engine gem source code. This reference is the
+> complete user-facing API, embedded verbatim into every event_engine local so
+> their guidance never drifts. Keep it the single source of truth.
+
+EventEngine is a Rails engine for defining domain events as declarative classes,
+compiling them to a committed schema, emitting them through generated helpers, and
+dispatching them to registered handlers. Core builds and routes events; it ships no
+handlers of its own. Durable delivery, an event store, and ready-made subscriber
+classes are separate companion gems (`event_engine-delivery`, `event_engine-store`,
+`event_engine-subscribers`) — this reference covers core only.
+
+### What it offers
+
+**Define events** — subclass `EventEngine::EventDefinition` in `app/event_definitions/`:
+
+```ruby
+class CowFed < EventEngine::EventDefinition
+  event_name :cow_fed        # the event's identity (required)
+  event_type :domain         # classification, e.g. :domain (required)
+  process_type :durable      # routing type (optional; set it explicitly)
+
+  input :cow                 # a required input
+  optional_input :farmer     # an optional input
+
+  required_payload :weight,      from: :cow,    attr: :weight
+  optional_payload :farmer_name, from: :farmer, attr: :name
+end
+```
+
+| DSL method | Purpose |
+|---|---|
+| `event_name(:symbol)` | The event's identity; becomes `EventEngine.<name>`. Required. |
+| `event_type(:symbol)` | Classification, e.g. `:domain`. Required. |
+| `process_type(:symbol)` | Routing type (optional). One of the six values below. |
+| `input(:name)` / `optional_input(:name)` | Inputs the emit helper must / may receive. |
+| `required_payload(name, from:, attr: nil)` | Payload field; `from:` names an input, `attr:` is the method read on it (`nil` passes the input through). |
+| `optional_payload(name, from:, attr: nil)` | Same, but omitted when the source input is nil. |
+
+Duplicate input names raise `ArgumentError`; payload `from:` must reference a
+declared input.
+
+**process_type** — core stamps this symbol onto every emitted event but does not act
+on it. Which handlers receive an event is decided by each handler's `levels:`. The
+values:
+
+| value | intent |
+|---|---|
+| `:inline` | handled in-process, synchronously |
+| `:background` | handled in-process, via a background job |
+| `:durable` | handled when a durable outbox drains |
+| `:broker` | published to an external transport |
+| `:telemetry` | metrics / observability handlers |
+| `:sourced` | an append-only event store |
+
+The companion gems register the handlers that give `:durable`, `:broker`, `:sourced`,
+etc. their behavior; core just routes to whatever is registered. If `process_type`
+is omitted it is `nil` — set it explicitly so routing intent is clear.
+
+**Emit events** — booting installs an `EventEngine.<event_name>` helper per event:
+
+```ruby
+EventEngine.cow_fed(
+  cow: cow, farmer: farmer,           # declared inputs, by name
+  occurred_at: Time.current,          # optional, defaults to now
+  metadata: { request_id: "abc" },    # optional
+  idempotency_key: "…",               # optional, defaults to a UUID
+  aggregate_type: "Cow", aggregate_id: cow.id, aggregate_version: 1,
+  event_version: 1                    # optional, defaults to the latest schema version
+)
+```
+
+Missing a required input, or passing an unknown one, raises `ArgumentError`. The
+event's `payload` is symbol-keyed.
+
+**Register handlers** — a handler is any object responding to `call(event)`:
+
+```ruby
+EventEngine.register_handler(handler, levels: [:inline, :durable])  # or levels: :all
+EventEngine.dispatch(event)     # fan an event out (emit helpers call this)
+EventEngine.reset_handlers!     # clear all handlers
+```
+
+Handlers run synchronously in registration order; if one raises, the rest don't run.
+Keep handlers idempotent.
+
+**Configure** — `config/initializers/event_engine.rb`, logger only:
+
+```ruby
+EventEngine.configure { |config| config.logger = Rails.logger }
+```
+
+**Schema workflow** — definitions compile to a committed `db/event_schema.rb`, which
+is authoritative at boot:
+
+```bash
+bin/rails event_engine:schema:dump    # compile definitions → db/event_schema.rb
+bin/rails event_engine:schema_check   # CI: fail if definitions drift from the file
+```
+
+A new event is version 1; changing an event's identity or payload bumps its version.
+Changing only `process_type` does not bump the version.
+
+### Install
+
+1. Add the gem and install: `gem "event_engine"`, then `bundle install`.
+2. Run `bin/rails g event_engine:install` — creates `db/event_schema.rb` and
+   `config/initializers/event_engine.rb`.
+3. Define events as classes in `app/event_definitions/`.
+4. Run `bin/rails event_engine:schema:dump` and commit `db/event_schema.rb`.
+5. Set `config.logger` in the initializer if you want something other than the default.
+
+Durable delivery, an event store, and prebuilt subscriber classes are separate gems
+(`event_engine-delivery`, `event_engine-store`, `event_engine-subscribers`); add them
+when you need them and follow their own setup.
+
+### EventEngine conventions
+
+- Define one `EventDefinition` class per event in `app/event_definitions/`; never
+  hand-build event hashes.
+- Build payloads from inputs with `required_payload`/`optional_payload`; don't pass
+  raw payload hashes to the emit helper.
+- Always set `process_type` explicitly so routing intent is clear.
+- Emit only through the generated `EventEngine.<event_name>` helpers, passing the
+  declared inputs.
+- Re-run `event_engine:schema:dump` and commit `db/event_schema.rb` after any
+  definition change; keep `event_engine:schema_check` green in CI.
+- Keep handlers and subscribers idempotent.

data/lib/event_engine/reference.rb

@@ -0,0 +1,16 @@
+module EventEngine
+  # Single source of truth for the EventEngine API reference. The companion
+  # Claude Code subagents (and any future doc generator) read from here so they
+  # can never disagree about how the gem is used.
+  module Reference
+    DIR = File.expand_path("reference", __dir__)
+
+    def self.content
+      read("guide.md")
+    end
+
+    def self.read(name)
+      File.read(File.join(DIR, name)).chomp
+    end
+  end
+end

data/lib/event_engine/schema_catalog.rb

@@ -0,0 +1,50 @@
+module EventEngine
+  class SchemaCatalog
+    def initialize(schema_registry:, subject_registry:)
+      @schema_registry = schema_registry
+      @subject_registry = subject_registry
+    end
+
+    def to_markdown
+      (["# Event Catalog"] + event_sections).join("\n\n") + "\n"
+    end
+
+    private
+
+    def event_sections
+      @schema_registry.events.map do |event|
+        section(@schema_registry.latest_for(event))
+      end
+    end
+
+    def section(schema)
+      ([
+        "## #{schema.event_name} (v#{schema.event_version})",
+        "- Type: #{schema.event_type}",
+        subject_line(schema)
+      ] + payload_lines(schema)).compact.join("\n")
+    end
+
+    def payload_lines(schema)
+      return [] if schema.payload_fields.empty?
+
+      ["- Payload:"] + schema.payload_fields.map do |field|
+        "  - #{field[:name]} (#{field[:required] ? "required" : "optional"})"
+      end
+    end
+
+    def subject_line(schema)
+      return nil unless schema.subject
+
+      details = subject_details(schema.subject)
+      details.empty? ? "- Subject: #{schema.subject}" : "- Subject: #{schema.subject} (#{details})"
+    end
+
+    def subject_details(name)
+      registered = @subject_registry[name]
+      return "" unless registered
+
+      registered.metadata.map { |key, value| "#{key}: #{value}" }.join(", ")
+    end
+  end
+end

data/lib/event_engine/schema_compatibility.rb

@@ -0,0 +1,50 @@
+module EventEngine
+  class SchemaCompatibility
+    def self.violations(old_registry:, new_registry:)
+      new_registry.events.flat_map do |event|
+        previous = old_registry.latest_for(event)
+        next [] unless previous
+
+        current = new_registry.latest_for(event)
+        new(old: previous, new: current).breaking_changes.map do |change|
+          "#{event}: #{change}"
+        end
+      end
+    end
+
+    def initialize(old:, new:)
+      @old = old
+      @new = new
+    end
+
+    def breaking_changes
+      removed_required_fields + newly_required_fields
+    end
+
+    private
+
+    def removed_required_fields
+      (required_names(@old) - field_names(@new)).map do |name|
+        "required payload field removed: #{name}"
+      end
+    end
+
+    def newly_required_fields
+      (optional_names(@old) & required_names(@new)).map do |name|
+        "payload field became required: #{name}"
+      end
+    end
+
+    def field_names(schema)
+      schema.payload_fields.map { |field| field[:name] }
+    end
+
+    def required_names(schema)
+      schema.payload_fields.select { |field| field[:required] }.map { |field| field[:name] }
+    end
+
+    def optional_names(schema)
+      schema.payload_fields.reject { |field| field[:required] }.map { |field| field[:name] }
+    end
+  end
+end

data/lib/event_engine/schema_diff.rb

@@ -0,0 +1,35 @@
+module EventEngine
+  class SchemaDiff
+    def initialize(expected:, actual:)
+      @expected = expected
+      @actual = actual
+    end
+
+    def changed?
+      @expected != @actual
+    end
+
+    def to_s
+      expected_lines = @expected.lines
+      actual_lines = @actual.lines
+
+      Array.new([ expected_lines.size, actual_lines.size ].max) do |index|
+        line_diff(expected_lines[index], actual_lines[index])
+      end.compact.join
+    end
+
+    private
+
+    def line_diff(expected_line, actual_line)
+      return " #{expected_line}" if expected_line == actual_line
+
+      [ marked("-", expected_line), marked("+", actual_line) ].compact.join
+    end
+
+    def marked(sign, line)
+      return nil if line.nil?
+
+      "#{sign}#{line}"
+    end
+  end
+end

data/lib/event_engine/schema_drift_guard.rb

@@ -0,0 +1,38 @@
+require "event_engine/schema_diff"
+
+module EventEngine
+  class SchemaDriftGuard
+    class DriftError < StandardError; end
+
+    def self.check!(schema_path:, definitions:)
+      raise DriftError, "Schema file does not exist: #{schema_path}" unless File.exist?(schema_path)
+
+      committed = File.read(schema_path)
+      regenerated = dump_to_string(definitions)
+
+      return true if committed == regenerated
+
+      raise DriftError, <<~MSG
+        EventEngine schema drift detected.
+
+        The DSL definitions do not match #{schema_path}.
+
+        #{SchemaDiff.new(expected: committed, actual: regenerated)}
+        Run:
+          bin/rails event_engine:schema:dump
+
+        And commit the updated schema file.
+      MSG
+    end
+
+    def self.dump_to_string(definitions)
+      Tempfile.create("event_schema") do |file|
+        EventEngine::EventSchemaDumper.dump!(
+          definitions: definitions,
+          path: file.path
+        )
+        File.read(file.path)
+      end
+    end
+  end
+end