event_engine-event_definition 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4fd0fd21eecd6b764d2c91c230bff8733c055148918fdcc3dc027b80cecddb3
-  data.tar.gz: 39a989288b99eb7fbe86777f787c357bfedee66e36f1800ce9432915ec92ea93
+  metadata.gz: 0a8a55e00106d9d21d704bc1efff1e19e08e7ffde3f294b54b373a92e6725db7
+  data.tar.gz: 66cdbbc7a48f66eba5be87ac226a6de151133e9b6efdfa0e147315845d5bba64
 SHA512:
-  metadata.gz: 0b245cffa43807384cc64d41ae50cca49a967636dd08156766ba5af768dc2c456191bc9eadf886cac8db40c1d57ede617275124fa4da4f906998b01d988b2755
-  data.tar.gz: e1c634fe59d2e0afe642c65057939c3123513586ad1402e273bcb1352e38e630148d51a148f9404b537240c5fd55443548d7bd485c755c57d2964857387e420e
+  metadata.gz: 734d64cce2925dafa21b91d90998fd9b94113a620a526b89d682c90c617715d9bf1f6159cd7a525d10676333ff86570990837324d8a7af2b6a3d32ac5134b15a
+  data.tar.gz: 8e0a63cc27fd94b3bd6aeec2230e59b3d44d9e9c57b2e9e4880e9145817530332cd41293a3258c55eb8c9f2784e565074f15449e4467d1e8d599da267e93e440

data/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this gem are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-07-29
+
+### Added
+
+- Pack self-registration. A generated pack calls
+  `EventEngine::Definition.register_pack(self)` when required, so consumers can
+  discover every pack's `schema.json` instead of being handed each path by
+  configuration. Exposed as `Definition.packs` and `Definition.pack_schema_paths`.
+- The generate task reports the files it wrote.
+
+### Changed
+
+- **Breaking.** `event_engine:definition:dump` is now `event_definition:generate`,
+  and `tasks/event_engine_definition.rake` is now `tasks/event_definition.rake`.
+  Packs must update the `load` line in their Rakefile. "dump" did not say what the
+  task produces, and the `event_engine:` prefix implied a dependency on the runtime
+  that this gem does not have.
+- **Breaking.** `EventEngine::SchemaRegistry` and `EventEngine::EventSchema` are now
+  `EventEngine::Definition::SchemaRegistry` and `EventEngine::Definition::EventSchema`.
+  Both previously sat at the top level and shadowed the `event_engine` runtime's own
+  classes of the same name on the same require path, so in any app installing both
+  gems the runtime silently operated on this gem's classes instead of its own.
+
+### Fixed
+
+- Generating a pack into a path whose directory did not exist raised
+  `Errno::ENOENT`. The directory is now created.
+- The README recommended generating into `lib/generated/`, which Rails 7.1+
+  autoloads. Zeitwerk expects that file to define `Generated::MarketingEvents`, so an
+  app following the README booted in development and raised on eager load in
+  production. Documented how to keep the helper out of the autoload paths.
+
 ## [0.2.0] - 2026-07-20
 
 First published release of `event_engine-event_definition`, the plain-Ruby

data/README.md

@@ -70,7 +70,7 @@ The helper doesn't exist until you generate it. `event_engine-event_definition`
 ```ruby
 # Rakefile (in your domain pack)
 require "event_engine/definition"
-load "tasks/event_engine_definition.rake"
+load "tasks/event_definition.rake"
 
 EventEngine::Definition.configure do |config|
   config.definitions_path = "app/event_definitions"             # where your EventDefinitions live
@@ -80,7 +80,7 @@ end
 ```
 
 ```sh
-$ rake event_engine:definition:dump
+$ rake event_definition:generate
 ```
 
 The task loads every definition under `definitions_path` — **no Rails required** — and writes two files you commit:
@@ -90,6 +90,69 @@ The task loads every definition under `definitions_path` — **no Rails required
 
 This is a build-time step; your app never runs it while serving requests. If your events declare a `subject`, register them too: `config.subject_registry = EventEngine::SubjectRegistry.define { subject :lead }`.
 
+#### Generating inside a Rails app
+
+The path above is right for a **pack gem**, whose `lib/` a host never autoloads. If
+you generate into a **Rails app** instead, keep the helper out of the autoload paths.
+Rails 7.1+ autoloads `lib` by default, so Zeitwerk would expect
+`lib/generated/marketing_events.rb` to define `Generated::MarketingEvents` and raise
+on eager load — which means the app boots in development and fails in production:
+
+```
+Zeitwerk::NameError: expected file lib/generated/marketing_events.rb
+to define constant Generated::MarketingEvents
+```
+
+Add the directory to the ignore list:
+
+```ruby
+# config/application.rb
+config.autoload_lib(ignore: %w[assets tasks generated])
+```
+
+The helper is meant to be required explicitly, not autoloaded — it registers the pack
+on load, so it needs to be required once at boot:
+
+```ruby
+# config/initializers/event_engine.rb
+require Rails.root.join("lib/generated/marketing_events")
+```
+
+The generated helper looks like this — note that it registers itself:
+
+```ruby
+require "event_engine/definition"
+
+module MarketingEvents
+  def self.schema_path
+    File.expand_path("schema.json", __dir__)
+  end
+
+  def self.lead_created(lead:, event_version: nil, occurred_at: nil, ...)
+    EventEngine::Definition.publisher.publish(
+      :lead_created, domain: :marketing, inputs: { lead: lead }, ...
+    )
+  end
+
+  EventEngine::Definition.register_pack(self)
+end
+```
+
+### Pack self-registration
+
+Requiring a generated pack registers it, so consumers can discover every pack's
+schema without being told about each one:
+
+```ruby
+EventEngine::Definition.packs             # => [MarketingEvents, SalesEvents]
+EventEngine::Definition.pack_schema_paths # => ["/…/marketing/schema.json", "/…/sales/schema.json"]
+```
+
+This is what lets `event_engine`'s catalog task find your events with no
+per-pack configuration. `register_pack` is idempotent, so requiring a pack more
+than once is safe. `EventEngine::Definition.reset_packs!` clears the registry
+(useful in tests).
+
 ### Emit the event (at runtime)
 
 With the helper generated, producing the event anywhere in your app is one call. You hand it the whole `lead`; the contract decides what is captured off it:
@@ -110,10 +173,14 @@ Every `lead_created` event, from anywhere in the app, carries exactly the shape
 }
 ```
 
-> **Where the work happens:** this gem *records* the `from:`/`attr:` mapping and forwards the raw `lead` under `inputs:`. Reading `lead.id`, `lead.email`, … to build that payload is done by the publisher the `event_engine` runtime supplies — see [How it fits](#how-it-fits-with-event_engine). Until one is configured the default publisher raises, so wire it once at boot:
+> **Where the work happens:** this gem *records* the `from:`/`attr:` mapping and forwards the raw `lead` under `inputs:`. Reading `lead.id`, `lead.email`, … to build that payload is done by the publisher the `event_engine` runtime supplies — see [How it fits](#how-it-fits-with-event_engine).
+>
+> **With `event_engine` installed you wire nothing** — it registers `EventEngine::DefinitionPublisher` at boot and the helper just works.
+>
+> Without it, the default publisher raises `PublisherNotConfigured`. Assign your own — any object with `#publish(event_name, domain:, inputs:, **envelope)`:
 >
 > ```ruby
-> EventEngine::Definition.publisher = my_publisher   # any object with #publish(event_name, **envelope)
+> EventEngine::Definition.publisher = MyPublisher.new
 > ```
 
 ### More examples
@@ -161,7 +228,7 @@ A payload field must also have a `from:` that references a declared input, and e
 
 ### Inspecting the compiled schema
 
-Every definition compiles to a `Schema` value object:
+Every definition compiles to an `EventEngine::EventDefinition::Schemas::Schema` value object:
 
 ```ruby
 schema = LeadCreated.schema
@@ -186,10 +253,18 @@ EventDefinition DSL                          registers as the publisher
         │ compile                            ────────────────────►
         ▼                                    reads the raw inputs via the
 generated helper  ──publish(event)──►        schema's from:/attr: mapping,
-+ committed schema.json                       then dispatches, persists, brokers…
++ committed schema.json                       then routes it to a processor
 ```
 
-A domain pack depends only on `event_engine-event_definition` to declare its events and build its helper file. In an app that also has `event_engine` installed, `event_engine` provides a real publisher adapter and assigns it to `EventEngine::Definition.publisher`, so calling a generated helper hands the event to the full runtime. Nothing in this gem knows how events are dispatched — that decision lives entirely in `event_engine`.
+A domain pack depends only on `event_engine-event_definition` to declare its events and build its helper file. In an app that also has `event_engine` installed, `event_engine` assigns `EventEngine::DefinitionPublisher` to `EventEngine::Definition.publisher` **at boot**, so calling a generated helper hands the event to the full runtime with no wiring in the host.
+
+Nothing in this gem knows how events are processed — that decision lives entirely in `event_engine`, declared in its rules file. A definition describes *what an event carries*, never *what happens to it*.
+
+### Namespacing
+
+Public API sits at `EventEngine::EventDefinition` (the DSL you subclass) and `EventEngine::Definition` (configuration, the publisher port, the pack registry).
+
+This gem's internals live under `EventEngine::Definition::*` — `Definition::SchemaRegistry`, `Definition::EventSchema` — deliberately, so they do not collide with `event_engine`'s own classes of the same name. Both gems are loaded into one `EventEngine` namespace in a host, and a shared require path means whichever gem wins `$LOAD_PATH` silently shadows the other.
 
 ## Development
 

data/docs/examples.md

@@ -2,7 +2,7 @@
 
 Each example follows the same three beats: the **data** you already have, the **event** you define, and the **call** you make. For the full DSL reference and how this plugs into `event_engine`, see the [README](../README.md).
 
-The `SalesEvents` / `ProductEvents` modules below are the helpers produced by generating the pack — the `rake event_engine:definition:dump` build step in the README. These examples assume that step has already run, so they focus on defining the event and calling it.
+The `SalesEvents` / `ProductEvents` modules below are the helpers produced by generating the pack — the `rake event_definition:generate` build step in the README. These examples assume that step has already run, so they focus on defining the event and calling it.
 
 ## An event built from multiple inputs
 

data/lib/event_engine/definition/event_schema.rb

@@ -0,0 +1,82 @@
+module EventEngine
+  module Definition
+    class EventSchema
+      class DuplicateEventNameError < StandardError; end
+
+      def self.define(&block)
+        schema = new
+        block.call(schema)
+        schema
+      end
+
+      def initialize
+        @schemas_by_event = {}
+        @finalized = false
+      end
+
+      def register(schema)
+        raise FrozenError, "EventSchema is finalized" if @finalized
+        key = key_for(schema.domain, schema.event_name)
+        version = schema.event_version
+
+        @schemas_by_event[key] ||= {}
+        guard_duplicate_event_name!(@schemas_by_event[key][version], schema)
+        @schemas_by_event[key][version] = schema
+      end
+
+      def guard_duplicate_event_name!(existing, incoming)
+        return unless existing
+
+        raise DuplicateEventNameError,
+              "duplicate (domain, event_name) " \
+              "(#{incoming.domain.inspect}, #{incoming.event_name.inspect}): " \
+              "already registered at version #{existing.event_version.inspect}"
+      end
+
+      def events(domain: nil)
+        @schemas_by_event.keys
+          .select { |(schema_domain, _name)| domain.nil? || schema_domain == domain }
+          .map { |(_domain, event_name)| event_name }
+          .uniq
+      end
+
+      def versions_for(event_name, domain: nil)
+        version_sets_for(event_name, domain).flat_map(&:keys).uniq.sort
+      end
+
+      def schema_for(event_name, version, domain: nil)
+        set = version_sets_for(event_name, domain).find { |versions| versions.key?(version) }
+        set && set[version]
+      end
+
+      def latest_for(event_name, domain: nil)
+        merged = version_sets_for(event_name, domain).reduce({}, :merge)
+        return nil if merged.empty?
+        merged[merged.keys.max]
+      end
+
+      def finalize!
+        @finalized = true
+        @schemas_by_event.each_value(&:freeze)
+        @schemas_by_event.freeze
+        freeze
+      end
+
+      def schemas_by_event
+        @schemas_by_event
+      end
+
+      private
+
+      def key_for(domain, event_name)
+        [domain, event_name]
+      end
+
+      def version_sets_for(event_name, domain = nil)
+        @schemas_by_event.select do |(schema_domain, name), _versions|
+          name == event_name && (domain.nil? || schema_domain == domain)
+        end.values
+      end
+    end
+  end
+end

data/lib/event_engine/definition/schema_registry.rb

@@ -0,0 +1,73 @@
+module EventEngine
+  module Definition
+    class SchemaRegistry
+      class UnknownEventError < StandardError; end
+
+      class RegistryFrozenError < StandardError; end
+
+      def initialize(event_schema = EventSchema.new)
+        @event_schema = event_schema
+        @loaded = false
+      end
+
+      def register(schema)
+        @event_schema.register(schema)
+      end
+
+      def events
+        @event_schema.events
+      end
+
+      def versions_for(event_name, domain: nil)
+        @event_schema.versions_for(event_name, domain: domain)
+      end
+
+      def load_from_schema!(schema)
+        raise RegistryFrozenError, "EventRegistry already loaded" if loaded?
+        @event_schema = schema
+
+        @loaded = true
+        self
+      end
+
+      def reset!
+        @event_schema = {}
+        @loaded = false
+      end
+
+      def schema(event_name, version: nil, domain: nil)
+        raise RegistryFrozenError, "EventRegistry not loaded" unless loaded?
+
+        schema =
+          if version
+            @event_schema.schema_for(event_name, version, domain: domain)
+          else
+            @event_schema.latest_for(event_name, domain: domain)
+          end
+
+        unless schema
+          raise UnknownEventError,
+                "Unknown #{version ? "version #{version} for " : ""}event: #{event_name}"
+        end
+
+        schema
+      end
+
+      def latest_for(event_name, domain: nil)
+        @event_schema.latest_for(event_name, domain: domain)
+      end
+
+      def event_schema
+        @event_schema
+      end
+
+      def finalize!
+        @event_schema.finalize!
+      end
+
+      def loaded?
+        @loaded == true
+      end
+    end
+  end
+end

data/lib/event_engine/definition/version.rb

@@ -2,6 +2,6 @@
 
 module EventEngine
   module Definition
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/event_engine/definition.rb

@@ -5,8 +5,8 @@ require_relative "definition/version"
 require "event_engine/subject_registry"
 require "event_engine/event_definition"
 require "event_engine/definition_loader"
-require "event_engine/event_schema"
-require "event_engine/schema_registry"
+require "event_engine/definition/event_schema"
+require "event_engine/definition/schema_registry"
 require "event_engine/lifecycle_definition"
 require "event_engine/dsl_compiler"
 require "event_engine/definition/configuration"
@@ -26,6 +26,23 @@ module EventEngine
         @publisher = nil
       end
 
+      def packs
+        @packs ||= []
+      end
+
+      def register_pack(pack)
+        packs << pack unless packs.include?(pack)
+        pack
+      end
+
+      def pack_schema_paths
+        packs.map(&:schema_path)
+      end
+
+      def reset_packs!
+        @packs = nil
+      end
+
       def configuration
         @configuration ||= Configuration.new
       end

data/lib/event_engine/domain_pack_build.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "fileutils"
 require "event_engine/dsl_compiler"
 require "event_engine/subject_registry"
 require "event_engine/event_engine_helpers_writer"
@@ -39,6 +40,7 @@ module EventEngine
 
     def run
       event_schema = compile
+      FileUtils.mkdir_p(File.dirname(@helper_path))
       write_helper(event_schema)
       write_schema_json(event_schema)
       self

data/lib/event_engine/dsl_compiler.rb

@@ -16,7 +16,7 @@ module EventEngine
     ].freeze
 
     def self.compile(definitions, subject_registry: SubjectRegistry.new)
-      registry = SchemaRegistry.new
+      registry = Definition::SchemaRegistry.new
       subject_violations = []
       name_violations = []
       reserved_violations = []

data/lib/event_engine/event_engine_helpers_writer.rb

@@ -24,9 +24,17 @@ module EventEngine
     def self.generate(event_schema, root_module: "EventEngine", emit: "EventEngine.emit",
                       header: HEADER, group_by_domain: true, schema_filename: nil)
       body = group_by_domain ? grouped_body(event_schema, emit) : flat_body(event_schema, emit)
-      body = "#{schema_path_accessor(schema_filename)}#{body}" if schema_filename
+      body = "#{schema_path_accessor(schema_filename)}#{body}#{pack_registration}" if schema_filename
 
-      "#{header}module #{root_module}\n#{body}end\n"
+      "#{header}#{pack_require if schema_filename}module #{root_module}\n#{body}end\n"
+    end
+
+    def self.pack_require
+      %(require "event_engine/definition"\n\n)
+    end
+
+    def self.pack_registration
+      "\n  EventEngine::Definition.register_pack(self)\n"
     end
 
     def self.schema_path_accessor(filename)

data/lib/tasks/event_definition.rake

@@ -0,0 +1,20 @@
+require "event_engine/definition"
+
+namespace :event_definition do
+  desc "Generate the pack's helper and schema.json from its EventDefinitions"
+  task :generate do
+    config = EventEngine::Definition.configuration
+
+    definitions = EventEngine::DefinitionLoader.load!(config.definitions_path)
+
+    build = EventEngine::DomainPackBuild.run(
+      definitions,
+      helper_path: config.helper_path,
+      root_module: config.root_module,
+      subject_registry: config.subject_registry
+    )
+
+    puts "Wrote #{config.root_module} helper to #{config.helper_path}"
+    puts "Wrote #{config.root_module} schema to #{build.schema_path}"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_engine-event_definition
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - tylercschneider
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies: []
 description: 'The plain-Ruby foundation of the EventEngine pipeline: the EventDefinition
   DSL and the shared schema-contract value objects, with no Rails dependency. Lightweight
@@ -27,7 +27,9 @@ files:
 - docs/examples.md
 - lib/event_engine/definition.rb
 - lib/event_engine/definition/configuration.rb
+- lib/event_engine/definition/event_schema.rb
 - lib/event_engine/definition/null_publisher.rb
+- lib/event_engine/definition/schema_registry.rb
 - lib/event_engine/definition/version.rb
 - lib/event_engine/definition_loader.rb
 - lib/event_engine/domain_pack_build.rb
@@ -38,11 +40,9 @@ files:
 - lib/event_engine/event_definition/schemas.rb
 - lib/event_engine/event_definition/validation.rb
 - lib/event_engine/event_engine_helpers_writer.rb
-- lib/event_engine/event_schema.rb
 - lib/event_engine/lifecycle_definition.rb
-- lib/event_engine/schema_registry.rb
 - lib/event_engine/subject_registry.rb
-- lib/tasks/event_engine_definition.rake
+- lib/tasks/event_definition.rake
 - sig/event_engine/definition.rbs
 homepage: https://eventengine.co
 licenses:

data/lib/event_engine/event_schema.rb

@@ -1,80 +0,0 @@
-module EventEngine
-  class EventSchema
-    class DuplicateEventNameError < StandardError; end
-
-    def self.define(&block)
-      schema = new
-      block.call(schema)
-      schema
-    end
-
-    def initialize
-      @schemas_by_event = {}
-      @finalized = false
-    end
-
-    def register(schema)
-      raise FrozenError, "EventSchema is finalized" if @finalized
-      key = key_for(schema.domain, schema.event_name)
-      version = schema.event_version
-
-      @schemas_by_event[key] ||= {}
-      guard_duplicate_event_name!(@schemas_by_event[key][version], schema)
-      @schemas_by_event[key][version] = schema
-    end
-
-    def guard_duplicate_event_name!(existing, incoming)
-      return unless existing
-
-      raise DuplicateEventNameError,
-            "duplicate (domain, event_name) " \
-            "(#{incoming.domain.inspect}, #{incoming.event_name.inspect}): " \
-            "already registered at version #{existing.event_version.inspect}"
-    end
-
-    def events(domain: nil)
-      @schemas_by_event.keys
-        .select { |(schema_domain, _name)| domain.nil? || schema_domain == domain }
-        .map { |(_domain, event_name)| event_name }
-        .uniq
-    end
-
-    def versions_for(event_name, domain: nil)
-      version_sets_for(event_name, domain).flat_map(&:keys).uniq.sort
-    end
-
-    def schema_for(event_name, version, domain: nil)
-      set = version_sets_for(event_name, domain).find { |versions| versions.key?(version) }
-      set && set[version]
-    end
-
-    def latest_for(event_name, domain: nil)
-      merged = version_sets_for(event_name, domain).reduce({}, :merge)
-      return nil if merged.empty?
-      merged[merged.keys.max]
-    end
-
-    def finalize!
-      @finalized = true
-      @schemas_by_event.each_value(&:freeze)
-      @schemas_by_event.freeze
-      freeze
-    end
-
-    def schemas_by_event
-      @schemas_by_event
-    end
-
-    private
-
-    def key_for(domain, event_name)
-      [domain, event_name]
-    end
-
-    def version_sets_for(event_name, domain = nil)
-      @schemas_by_event.select do |(schema_domain, name), _versions|
-        name == event_name && (domain.nil? || schema_domain == domain)
-      end.values
-    end
-  end
-end

data/lib/event_engine/schema_registry.rb

@@ -1,71 +0,0 @@
-module EventEngine
-  class SchemaRegistry
-    class UnknownEventError < StandardError; end
-
-    class RegistryFrozenError < StandardError; end
-
-    def initialize(event_schema = EventSchema.new)
-      @event_schema = event_schema
-      @loaded = false
-    end
-
-    def register(schema)
-      @event_schema.register(schema)
-    end
-
-    def events
-      @event_schema.events
-    end
-
-    def versions_for(event_name, domain: nil)
-      @event_schema.versions_for(event_name, domain: domain)
-    end
-
-    def load_from_schema!(schema)
-      raise RegistryFrozenError, "EventRegistry already loaded" if loaded?
-      @event_schema = schema
-
-      @loaded = true
-      self
-    end
-
-    def reset!
-      @event_schema = {}
-      @loaded = false
-    end
-
-    def schema(event_name, version: nil, domain: nil)
-      raise RegistryFrozenError, "EventRegistry not loaded" unless loaded?
-
-      schema =
-        if version
-          @event_schema.schema_for(event_name, version, domain: domain)
-        else
-          @event_schema.latest_for(event_name, domain: domain)
-        end
-
-      unless schema
-        raise UnknownEventError,
-              "Unknown #{version ? "version #{version} for " : ""}event: #{event_name}"
-      end
-
-      schema
-    end
-
-    def latest_for(event_name, domain: nil)
-      @event_schema.latest_for(event_name, domain: domain)
-    end
-
-    def event_schema
-      @event_schema
-    end
-
-    def finalize!
-      @event_schema.finalize!
-    end
-
-    def loaded?
-      @loaded == true
-    end
-  end
-end

data/lib/tasks/event_engine_definition.rake

@@ -1,19 +0,0 @@
-require "event_engine/definition"
-
-namespace :event_engine do
-  namespace :definition do
-    desc "Generate the pack's helper and schema.json from its EventDefinitions"
-    task :dump do
-      config = EventEngine::Definition.configuration
-
-      definitions = EventEngine::DefinitionLoader.load!(config.definitions_path)
-
-      EventEngine::DomainPackBuild.run(
-        definitions,
-        helper_path: config.helper_path,
-        root_module: config.root_module,
-        subject_registry: config.subject_registry
-      )
-    end
-  end
-end