event_engine 0.1.0 → 0.2.0

data/the_local/agents/event_engine-install.md

@@ -0,0 +1,99 @@
+---
+name: event_engine-install
+description: Use to hook event_engine into a Rails app — adding the gem, writing the `EventEngine.configure` initializer, and getting the boot-time schema catalog in place.
+tools: Bash, Read, Edit
+scope: events — registering processors and publishers, building the schema catalog, and directing emitted events to the right processor
+---
+
+This local follows the steps below exactly, in order, and invents none. Where a
+step names a decision, it asks the developer instead of choosing.
+
+## What event_engine is
+
+A Rails engine that loads a committed catalog of event schemas at boot so an app
+can emit checked, routed events — hook it in when an app needs its events to be a
+declared, reviewable contract.
+
+## Interface
+
+- `EventEngine.configure` — yields the configuration object. The one setup call a
+  host app makes; put it in an initializer so it runs at boot.
+
+## How to use it
+
+1. Add the gem to the host app's `Gemfile`:
+
+   ```ruby
+   gem "event_engine"
+   ```
+
+   Ask the developer whether to take the released gem, pin a version, or track
+   the source repository (`github: "DYB-Development/event_engine"`) — do not pick
+   for them. The host must be a Rails app; this gem is a Rails engine and does
+   nothing outside one.
+
+2. Install it:
+
+   ```bash
+   bundle install
+   ```
+
+3. Create `config/initializers/event_engine.rb` in the host app:
+
+   ```ruby
+   require "event_engine"
+
+   EventEngine.configure do |config|
+   end
+   ```
+
+   Every setting is optional — an empty block is a valid install. Steps 4 and 5
+   fill it in.
+
+4. Decide `metadata_defaults` with the developer. It takes a callable returning a
+   hash, invoked on every emit, and its keys are merged **under** any metadata
+   passed at the call site, so the call site wins on a collision. There is no safe
+   default: ask what belongs on every event this app emits (request id, actor,
+   deploy version, …), and leave it unset if the answer is nothing.
+
+   ```ruby
+   config.metadata_defaults = -> { { request_id: Current.request_id } }
+   ```
+
+   A callable that raises is swallowed and logged rather than breaking the emit.
+
+5. Set `logger` only if the engine's own output should go somewhere other than
+   `Rails.logger` — it defaults to `Rails.logger` inside a Rails app.
+
+   ```ruby
+   config.logger = Logger.new("log/event_engine.log")
+   ```
+
+6. Get the schema catalog to `db/event_schema.json` in the host app and commit it.
+   The engine reads that exact path at boot; the path is fixed and no setting
+   moves it. Without the file, the app logs a warning in `development` and `test`
+   and **refuses to boot in every other environment**. Building the catalog from
+   the app's event packs is the `event_engine-develop` local's job — hand off to
+   it, and confirm the file exists before treating this install as done.
+
+7. Verify the app boots with the catalog loaded:
+
+   ```bash
+   bin/rails runner 'puts EventEngine.schema_registry.loaded?'
+   ```
+
+   `true` means the initializer ran and the catalog was read. `false` means the
+   catalog file is missing — go back to step 6.
+
+## Conventions
+
+- The initializer is the only host file this local writes, plus one `Gemfile`
+  line. It creates no migrations and no tables.
+- Re-running any step is safe. Editing the initializer requires an app restart to
+  take effect; nothing re-reads it at runtime.
+- If `db/event_engine_helpers.rb` is present in the host app, the engine loads it
+  at boot. It never creates that file — an event pack commits it. Do not write one.
+- Out of scope for this local: everything an app does *with* the engine —
+  registering processors, publishers or handlers, choosing how events route,
+  pointing the engine at schema sources, emitting events, and the catalog tasks.
+  All of that belongs to `event_engine-develop`.

data/the_local/interface.yml

@@ -0,0 +1,27 @@
+scope: events — registering processors and publishers, building the schema catalog, and directing emitted events to the right processor
+
+install:
+  - EventEngine.configure
+
+develop:
+  - EventEngine.register_processor
+  - EventEngine.register_definition_publisher!
+  - EventEngine.register_handler
+  - publisher_schema_paths
+  - event_processors
+  - domain_processors
+  - default_processor
+  - bin/rails event_engine:schema:catalog
+  - bin/rails event_engine:catalog
+
+sources:
+  - lib/event_engine.rb
+  - lib/event_engine/engine.rb
+  - lib/event_engine/configuration.rb
+  - lib/event_engine/definition_publisher.rb
+  - lib/event_engine/processor_registry.rb
+  - lib/event_engine/processor_resolver.rb
+  - lib/event_engine/handler_registry.rb
+  - lib/event_engine/schema_catalog_builder.rb
+  - lib/tasks/event_engine_catalog.rake
+  - lib/tasks/event_engine_schema_catalog.rake

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: event_engine
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - tylercschneider
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-25 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -30,10 +30,30 @@ dependencies:
     - - "<"
       - !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.'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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 runtime of the EventEngine pipeline: load the committed schema catalog
+  aggregated from domain packs, build validated events, and dispatch them to registered
+  handlers by process_type. Events are declared with event_engine-event_definition;
+  durable delivery, transports, and the dashboard live in event_engine-delivery.'
 email:
 - tylercschneider@gmail.com
 executables: []
@@ -44,56 +64,33 @@ files:
 - 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/catalog_entry.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/definition_publisher.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/event_schema_json_loader.rb
 - lib/event_engine/handler_registry.rb
-- lib/event_engine/lifecycle_definition.rb
-- lib/event_engine/process_type.rb
+- lib/event_engine/invalid_rules_error.rb
+- lib/event_engine/processing_rules.rb
+- lib/event_engine/processor_registry.rb
+- lib/event_engine/processor_resolver.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/rules_file.rb
+- lib/event_engine/schema_catalog_builder.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/unregistered_processor_error.rb
+- lib/event_engine/unroutable_event_error.rb
+- lib/event_engine/unrouted_events_error.rb
 - 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
+- lib/tasks/event_engine_rules.rake
+- the_local/agents/event_engine-develop.md
+- the_local/agents/event_engine-info.md
+- the_local/agents/event_engine-install.md
+- the_local/interface.yml
 homepage: https://eventengine.co
 licenses:
 - MIT
@@ -123,5 +120,5 @@ requirements: []
 rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
-summary: Schema-first event definitions and dispatch for Rails
+summary: The Rails host runtime for the schema-first EventEngine pipeline
 test_files: []

data/app/assets/config/event_engine_manifest.js

@@ -1 +0,0 @@
-//= link_directory ../stylesheets/event_engine .css

data/app/assets/stylesheets/event_engine/application.css

@@ -1,15 +0,0 @@
-/*
- * This is a manifest file that'll be compiled into application.css, which will include all the files
- * listed below.
- *
- * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
- * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
- *
- * You're free to add application-wide styles to this file and they'll appear at the bottom of the
- * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
- * files in this directory. Styles in this file should be added after the last require_* statement.
- * It is generally better to create a new file per style scope.
- *
- *= require_tree .
- *= require_self
- */

data/app/controllers/event_engine/application_controller.rb

@@ -1,4 +0,0 @@
-module EventEngine
-  class ApplicationController < ActionController::Base
-  end
-end

data/app/helpers/event_engine/application_helper.rb

@@ -1,4 +0,0 @@
-module EventEngine
-  module ApplicationHelper
-  end
-end

data/app/jobs/event_engine/application_job.rb

@@ -1,4 +0,0 @@
-module EventEngine
-  class ApplicationJob < ActiveJob::Base
-  end
-end

data/app/mailers/event_engine/application_mailer.rb

@@ -1,6 +0,0 @@
-module EventEngine
-  class ApplicationMailer < ActionMailer::Base
-    default from: "from@example.com"
-    layout "mailer"
-  end
-end

data/app/models/event_engine/application_record.rb

@@ -1,5 +0,0 @@
-module EventEngine
-  class ApplicationRecord < ActiveRecord::Base
-    self.abstract_class = true
-  end
-end

data/app/views/layouts/event_engine/application.html.erb

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Event engine</title>
-  <%= csrf_meta_tags %>
-  <%= csp_meta_tag %>
-
-  <%= stylesheet_link_tag    "event_engine/application", media: "all" %>
-</head>
-<body>
-
-<%= yield %>
-
-</body>
-</html>

data/config/routes.rb

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

data/lib/event_engine/definition_loader.rb

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

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

@@ -1,56 +0,0 @@
-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_definition/inputs.rb

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

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