event_engine 0.1.0 → 0.2.0

data/lib/event_engine/event_definition/schemas.rb

@@ -1,158 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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_dumper.rb

@@ -1,13 +0,0 @@
-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

data/lib/event_engine/event_schema_loader.rb

@@ -1,37 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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

@@ -1,47 +0,0 @@
-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/lifecycle_definition.rb

@@ -1,86 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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/reference/guide.md

@@ -1,129 +0,0 @@
-## 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

@@ -1,16 +0,0 @@
-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