event_engine 0.1.0 → 0.2.1

data/README.md

@@ -1,517 +1,337 @@
 # EventEngine
 
-EventEngine is the schema-first **core** of an event pipeline for Rails:
+The **Rails host runtime** of the [EventEngine](https://github.com/DYB-Development) pipeline.
 
-- **Define** events with a small Ruby DSL.
-- **Compile** them into a canonical, committed schema file (`db/event_schema.rb`).
-- **Emit** them through generated helpers (`EventEngine.cow_fed(...)`) that build a
-  validated `Event` and **dispatch** it to registered handlers by *level*.
+EventEngine is a schema-first event pipeline. Domain events are **declared** and
+**compiled** into a committed contract by domain-pack gems (built on
+[`event_engine-event_definition`](https://github.com/DYB-Development/event_engine-event_definition)).
+This gem is the **runtime** a Rails app installs: it holds the schema registry,
+**builds** a validated `EventEngine::Event` from the inputs a pack hands it, and
+hands it to the **processor** its rules name.
 
-The core gem does **not** deliver events anywhere on its own. It builds the event
-and hands it to whatever handlers are registered. Durable delivery and durable
-storage live in companion gems that register themselves as handlers:
+This gem does **not** author events (that is `event_engine-event_definition` + your
+domain packs) and does **not** deliver them (that is the processor gems below). It is
+the middle of the pipe: inputs in, built event out, routed to a processor.
 
-| Gem | Responsibility | Add it when |
-|---|---|---|
-| **`event_engine`** (this gem) | Define, compile, emit, dispatch | Always — it's the core |
-| [`event_engine-delivery`](https://github.com/DYB-Development/event_engine-delivery) | Transactional outbox, retries, dead-letters, transports (Kafka), dashboard, cloud reporter | You need to deliver events reliably (in-process or to a broker) |
-| [`event_engine-store`](https://github.com/DYB-Development/event_engine-store) | Durable, append-only event log + event-sourcing replay & projections | You need a permanent record of every event / event sourcing |
-
-You can run the core gem **by itself** with your own handlers — see
-[The handler extension point](#the-handler-extension-point).
-
-> This README documents the core gem **only**. Outbox, transports, dead-letters,
-> the dashboard, and the cloud reporter are documented in `event_engine-delivery`.
-> The event log, replay, and projections are documented in `event_engine-store`.
-
----
-
-## Table of contents
-
-- [Quick start](#quick-start)
-- [Mental model](#mental-model)
-- [Defining events](#defining-events)
-  - [The DSL reference](#the-dsl-reference)
-  - [How payload fields are extracted](#how-payload-fields-are-extracted)
-  - [There is no `type:` casting](#there-is-no-type-casting)
-  - [Lifecycle event families](#lifecycle-event-families)
-- [Generating the schema](#generating-the-schema)
-  - [How versioning works](#how-versioning-works)
-  - [Drift checking in CI](#drift-checking-in-ci)
-- [Emitting events](#emitting-events)
-- [Subscribers](#subscribers)
-- [Event levels](#event-levels)
-- [The handler extension point](#the-handler-extension-point)
-- [Configuration](#configuration)
-- [Rake tasks](#rake-tasks)
-- [Installation generator](#installation-generator)
-- [For AI assistants](#for-ai-assistants)
-- [Contributing](#contributing)
-- [License](#license)
+> **Status.** The authoring layer is fully extracted out of this gem, and the
+> passive wiring is in place: the publisher adapter registers itself at boot and
+> packs are discovered without per-pack host config. A host registers its
+> processors and declares its [rules file](#declaring-how-events-are-processed) —
+> nothing else.
 
 ---
 
-## Quick start
-
-```ruby
-# Gemfile
-gem "event_engine"
-```
+## Where this gem sits
 
-```bash
-bundle install
-```
+| Gem | Responsibility | Add it when |
+|---|---|---|
+| [`event_engine-event_definition`](https://github.com/DYB-Development/event_engine-event_definition) | The DSL, schema value objects, and the build step that turns definitions into a committed helper file + `schema.json`. No Rails. | A gem or app **declares** events |
+| **`event_engine`** (this gem) | Catalog, build a validated event, route it to the processor its rules name | Always — it's the host runtime |
+| `event_engine-delivery` | Transactional outbox, retries, dead-letters, transports (Kafka), dashboard | You need durable/broker delivery |
+| `event_engine-store` | Durable append-only event log + replay & projections | You need a permanent record / event sourcing |
+| `event_engine-subscribers`, `-telemetry`, `-sourced` | Processor gems for inline/background subscribers, telemetry, and event sourcing | You want that processing style |
 
-1. **Define an event** in `app/event_definitions/cow_fed.rb` (see [Defining events](#defining-events)).
-2. **Dump the schema**:
-   ```bash
-   bin/rails event_engine:schema:dump
-   ```
-3. **Commit `db/event_schema.rb`** — it is authoritative at runtime.
-4. **Register at least one handler** so emitted events do something. Either add a
-   companion gem (`event_engine-delivery` / `event_engine-store`) or write your own
-   (see [The handler extension point](#the-handler-extension-point)).
-5. **Emit** from your app code:
-   ```ruby
-   EventEngine.cow_fed(cow: cow)
-   ```
-
-> With **no** handler registered, the core gem builds and dispatches the event but
-> nothing observes it. That's expected — core is the dispatch layer; handlers are
-> what *do* something with events.
+Domain packs (e.g. `event_engine-marketing_events`, `-sales_events`, `-user_events`)
+declare events against `event_engine-event_definition` and each ships its own
+committed `schema.json` and helper module.
 
 ---
 
-## Mental model
+## How it fits together
+
+A pack's generated helper does **not** emit. It forwards the raw inputs through a
+**publisher port**; this gem is what turns those inputs into a real event and
+routes it.
 
 ```
-EventDefinition (Ruby DSL)
-        │  bin/rails event_engine:schema:dump
-        ▼
-db/event_schema.rb   ◄── authoritative at runtime; commit it
-        │  Rails boot (Engine initializer)
-        ▼
-SchemaRegistry  ──► installs EventEngine.<event_name> helpers
-        │  you call EventEngine.cow_fed(cow: cow)
-        ▼
-EventBuilder builds a validated EventEngine::Event
-        │  EventEngine.dispatch(event)
-        ▼
-HandlerRegistry ──► every registered handler whose `levels:` match event_level
-                     (event_engine-delivery, event_engine-store, or your own)
+pack helper  (event_engine-event_definition)
+    MarketingEvents.lead_created(lead: lead, …envelope)
+          │  calls the publisher PORT (not emit):
+          ▼
+    EventEngine::Definition.publisher.publish(:lead_created, domain: :marketing,
+                                               inputs: { lead: lead }, …envelope)
+          ▼
+    EventEngine::DefinitionPublisher           ◄── registered at boot, no host wiring
+          │  EventEngine.emit(:lead_created, inputs: { lead: lead }, domain: :marketing, …)
+          ▼
+    EventBuilder builds the payload from each field's from:/attr:  ◄── catalog entry
+          │  the rules file decides which processor handles it
+          ▼
+    the processor named by the rule
+          (event_engine-delivery / -store / -subscribers / your own)
 ```
 
-Two things are worth internalizing:
+**`EventEngine.emit` is the official emit, and it lives here** — not in the pack. The
+pack passes *inputs* (the whole objects you already have); this gem reads them via
+the catalog entry's `from:`/`attr:` mapping to build the flat `payload`, stamps the
+envelope, and routes it.
 
-1. **The committed schema file — not your definition classes — is the source of
-   truth at runtime.** Definition classes are read only at *dump* time. In
-   production a missing `db/event_schema.rb` raises at boot.
-2. **Emitting and handling are decoupled.** `EventEngine.dispatch` just fans the
-   event out to handlers by level. The core gem ships *no* handlers.
+### The passive wiring
 
----
+A host installs the gems and configures **nothing per pack**. Both halves self-wire:
 
-## Defining events
+1. **Emit routing** — at boot `event_engine` registers `DefinitionPublisher` as
+   `EventEngine::Definition.publisher`, so every pack helper routes into
+   `EventEngine.emit` automatically.
+2. **Schema discovery** — a generated pack registers itself when required, so
+   `event_engine:catalog` finds every pack's `schema.json` with no
+   configuration. See [Building the catalog](#1-build-the-catalog).
 
-Put definitions where Rails eager-loads them — conventionally
-`app/event_definitions/`. Subclass `EventEngine::EventDefinition`:
+What a host still decides for itself is **how** each event is processed, in the
+[rules file](#declaring-how-events-are-processed).
 
-```ruby
-# app/event_definitions/cow_fed.rb
-class CowFed < EventEngine::EventDefinition
-  input :cow                 # required input to the emit helper
-  optional_input :farmer     # optional input
-
-  event_name :cow_fed        # the event's identity → EventEngine.cow_fed
-  event_type :domain         # free-form classification (:domain, :integration, …)
-  event_level 3              # how it's dispatched (optional; see Event levels)
-
-  required_payload :weight,      from: :cow,    attr: :weight
-  optional_payload :farmer_name, from: :farmer, attr: :name
-end
-```
+---
 
-### The DSL reference
+## A working example
 
-All methods below are **class-level** macros on an `EventDefinition` subclass.
+[**DYB-Development/event_engine_example**](https://github.com/DYB-Development/event_engine_example)
+is a minimal Rails app wired to this pipeline end to end — declaring an event,
+compiling it, declaring how it is processed, and handling it. It installs all three
+gems from RubyGems, so it is what a real host looks like.
 
-| Macro | Signature | What it does |
-|---|---|---|
-| `event_name` | `event_name(:symbol)` | The event's identity. Becomes the `EventEngine.<name>` helper. **Required.** |
-| `event_type` | `event_type(:symbol)` | Free-form classification, e.g. `:domain`, `:integration`, `:system`. **Required.** |
-| `event_level` | `event_level(Integer)` | Dispatch level `1..4` (see [Event levels](#event-levels)). Optional. |
-| `input` | `input(:name)` | Declares a **required** input keyword the emit helper accepts. Duplicate names raise `ArgumentError`. |
-| `optional_input` | `optional_input(:name)` | Declares an **optional** input keyword. |
-| `required_payload` | `required_payload(name, from:, attr: nil)` | A payload field that must be present. `from:` names the input it reads; `attr:` is the method called on that input. |
-| `optional_payload` | `optional_payload(name, from:, attr: nil)` | Same, but **omitted from the payload** when the source input is `nil`. |
+---
 
-A handful of payload field names are **reserved** (they collide with event
-envelope/outbox columns) and rejected at dump time:
+## Getting started
 
+```ruby
+# Gemfile
+gem "event_engine"
 ```
-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
+
+```bash
+bundle install
 ```
 
-### How payload fields are extracted
+### 1. Build the catalog
 
-When you emit, `EventBuilder` walks each declared payload field and pulls a value
-out of the inputs you passed:
+At boot the engine loads a committed **`db/event_schema.json`** and reconstructs the
+registry from it (no Ruby is evaluated from a schema file; missing in production
+raises). Put the schema there by either:
 
-- `from:` selects **which input** to read.
-- `attr:` is the **method called on that input**. If `attr:` is `nil`, the input
-  itself is used (passthrough).
-- For an `optional_payload`, if the `from:` input is `nil` the field is simply left
-  out of the payload (no key, not a `nil` value).
+- committing `db/event_schema.json` directly, or
+- registering a pack's slice at boot (additive — each slice merges in):
 
-```ruby
-required_payload :weight, from: :cow, attr: :weight
-# → payload[:weight] = cow.weight
+  ```ruby
+  # in a pack's Rails engine
+  initializer "marketing_events.register_events" do
+    config.after_initialize do
+      EventEngine.register_slice!(schema_path: MarketingEvents.schema_path)
+    end
+  end
+  ```
 
-optional_payload :raw_cow, from: :cow
-# → payload[:raw_cow] = cow            (passthrough; attr omitted)
+To build `db/event_schema.json` from your packs, run the catalog task — it finds
+them without configuration:
 
-optional_payload :farmer_name, from: :farmer, attr: :name
-# → only present if `farmer:` was passed and non-nil
+```bash
+bin/rails event_engine:catalog
 ```
 
-The resulting `event.payload` is a **symbol-keyed Hash**.
+This writes **two** files: the catalog itself, and the
+[rules file](#declaring-how-events-are-processed) listing every event in it.
 
-### There is no `type:` casting
+### Where the catalog's sources come from
 
-The complete payload DSL is `required_payload` / `optional_payload` with `from:` and
-`attr:` only — there is no `type:` option and no type casting, and no
-`entity_class` / `entity_id` / `entity_version` macros.
+`EventEngine.schema_sources` resolves what the catalog aggregates:
 
-Whatever value `attr:` returns is stored as-is. If you need a value coerced to a
-specific type, do it on the source object's method (e.g. have `cow.weight` return a
-`Float`) or expose a purpose-built reader and point `attr:` at it.
+1. `config.publisher_schema_paths`, when you have set it — an explicit list always wins.
+2. Otherwise, **every pack that has registered itself**. Packs generated by
+   `event_engine-event_definition` call `EventEngine::Definition.register_pack(self)`
+   when required, so requiring a pack is enough to make its `schema.json` discoverable.
 
-### Lifecycle event families
+Discovery is optional and degrades quietly: `event_engine` does not depend on
+`event_engine-event_definition`, so with no packs loaded there is nothing to
+discover and `schema_sources` returns the configured list (empty by default).
 
-Related events that describe one capability — `export_csv_started`,
-`export_csv_completed`, `export_csv_failed` — share inputs and payload fields. Writing
-them as three independent `EventDefinition`s lets their names and shared fields drift.
-Subclass `EventEngine::LifecycleDefinition` to stamp the whole family from one template:
+A host with packs in its Gemfile therefore needs no per-pack configuration:
 
 ```ruby
-# app/event_definitions/export_csv_events.rb
-class ExportCsvEvents < EventEngine::LifecycleDefinition
-  subject :export_csv                      # validated against the SubjectRegistry
-  event_type :product
-
-  input :export
-  required_payload :format, from: :export, attr: :format
-
-  lifecycle :started, :completed, :failed  # → export_csv_started / _completed / _failed
-
-  on :failed do
-    input :error
-    required_payload :error_class, from: :error, attr: :class
-  end
-end
+EventEngine.configuration.publisher_schema_paths  # => []
+EventEngine.schema_sources                        # => ["/…/marketing/schema.json"]
 ```
 
-This generates three real `EventDefinition`s named `subject_verb` (flat snake_case, so
-each yields a working `EventEngine.export_csv_completed(...)` helper). Shared declarations
-apply to every verb; an `on :verb` block layers additional inputs/payloads onto that verb
-only. The generated events behave exactly like hand-written ones everywhere — schema dump,
-registry, helpers, metadata enricher, catalog, and compatibility checks all apply unchanged.
-
-| Macro | Signature | What it does |
-|---|---|---|
-| `subject` | `subject(:symbol)` | The family's subject, carried onto every generated event. Must be registered. |
-| `event_type` | `event_type(:symbol)` | Shared across every verb. |
-| `process_type` | `process_type(:symbol)` | Shared across every verb. Optional. |
-| `lifecycle` | `lifecycle(*verbs)` | Generates one event per verb, named `:"#{subject}_#{verb}"`. |
-| `on` | `on(:verb) { … }` | Layers verb-specific `input` / `required_payload` / `optional_payload` onto that verb only. Add-only. |
-
-Shared `input` / `optional_input` / `required_payload` / `optional_payload` are declared
-exactly as on a plain `EventDefinition` and apply to every verb.
-
----
-
-## Generating the schema
-
-After adding or changing definitions:
-
-```bash
-bin/rails event_engine:schema:dump   # compile definitions → db/event_schema.rb
-```
+### 2. Register your processors
 
-This compiles every `EventDefinition` subclass, merges with the existing committed
-file, and rewrites `db/event_schema.rb`. **Commit the result.** The generated file
-looks like:
+A processor is anything responding to `#call(event)`, registered under a name. Add a
+processor gem (`event_engine-delivery`, `-store`, `-subscribers`, …) **or** your own:
 
 ```ruby
-# 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(
-    EventEngine::EventDefinition::Schema.new(
-      event_name: :cow_fed,
-      event_version: 1,
-      event_type: :domain,
-      event_level: 3,
-      required_inputs: [:cow],
-      optional_inputs: [:farmer],
-      payload_fields: [
-        { name: :weight, required: true, from: :cow, attr: :weight }
-      ]
-    )
-  )
-end
+# config/initializers/event_engine.rb
+EventEngine.register_processor(:subscribers, SubscriberFanout.new)
+EventEngine.register_processor(:audit, ->(event) { AuditLog.record(event) })
 ```
 
-### How versioning works
+### 3. Declare how each event is processed
 
-The dumper is **append-only and additive** — it never edits an existing version in
-place:
+Name the processor for each event in `config/event_rules.yml` — see
+[the rules file](#declaring-how-events-are-processed).
 
-- A brand-new event is written as **version 1**.
-- When you change an existing event, the merger compares a **SHA256 fingerprint**
-  of its `event_name`, `event_type`, inputs, and payload fields against the latest
-  version in the file. If they differ, it writes a **new version** (`N + 1`); if
-  they match, nothing changes.
-- Version numbers are **monotonic** — reverting a change to a previous shape still
-  produces a *new* higher version, never reuses an old number.
+### 4. Emit
 
-> **`event_level` is intentionally excluded from the fingerprint.** Changing only an
-> event's level does **not** bump its version — level is treated as operational
-> routing metadata, not part of the event contract. This is what lets you "promote"
-> an event up the level ladder as a one-line change with no schema churn.
+```ruby
+EventEngine.emit(:cow_fed, inputs: { cow: cow }, domain: :sales)
+```
 
-### Drift checking in CI
+Or, more usually, call the pack's generated helper — it routes here for you:
 
-```bash
-bin/rails event_engine:schema:verify
+```ruby
+MarketingEvents.lead_created(lead: lead)
 ```
 
-This fails if your definitions have drifted from the committed `db/event_schema.rb`
-(i.e. someone changed a definition but forgot to dump), printing a readable diff of
-what changed. Add it to CI to keep the file honest. The older `event_engine:schema`
-and `event_engine:schema_check` tasks perform the same check without the diff.
-
 ---
 
 ## Emitting events
 
-At boot the engine loads `db/event_schema.rb` and installs a singleton helper on
-`EventEngine` for each event. Pass declared inputs by keyword, plus optional
-emit-time envelope fields:
+`EventEngine.emit` is the always-available entry point, and the target the publisher
+adapter forwards to. It looks the event up in the catalog, builds its payload from
+the inputs, stamps the envelope, routes it to its processor, and returns the built
+`EventEngine::Event`.
 
 ```ruby
-EventEngine.cow_fed(
-  cow: cow,                        # declared inputs, by name
-  farmer: farmer,
-
-  occurred_at: Time.current,       # optional; defaults to Time.current
-  metadata: { request_id: "abc" }, # optional contextual hash
-  idempotency_key: "cow-#{cow.id}-#{Date.current}", # optional; defaults to a UUID
-  aggregate_type: "Cow",           # optional aggregate tracking
+event = EventEngine.emit(
+  :cow_fed,
+  inputs: { cow: cow, farmer: farmer },  # the declared inputs, by name
+
+  domain: :sales,                        # scopes lookup when a name exists in >1 domain
+  event_version: 2,                      # optional; defaults to the latest version
+  occurred_at: Time.current,             # optional; defaults to Time.current
+  metadata: { source: "import" },        # optional; merged over metadata_defaults
+  idempotency_key: "cow-#{cow.id}",      # optional; defaults to a UUID
+  aggregate_type: "Cow",                 # optional aggregate envelope fields
   aggregate_id: cow.id,
-  aggregate_version: 1
+  aggregate_version: 3
 )
-```
-
-- Missing a required input, or passing an unknown input, raises `ArgumentError`.
-- `event_version:` may be passed to pin a specific schema version (defaults to latest).
-- The return value is **whatever the handlers return** — there's no canonical return
-  in core. (`event_engine-delivery`, for example, returns the persisted outbox record
-  for levels 3+.)
-
-The built `EventEngine::Event` exposes: `event_name`, `event_type`, `event_version`,
-`event_level`, `payload` (symbol-keyed), `metadata`, `occurred_at`,
-`idempotency_key`, `aggregate_type`, `aggregate_id`, `aggregate_version`.
-
----
 
-## Subscribers
-
-A **subscriber** reacts to an event in-process. Subclass `EventEngine::Subscriber`,
-declare what it handles, and implement `handle`:
-
-```ruby
-# app/subscribers/send_welcome_email.rb
-class SendWelcomeEmail < EventEngine::Subscriber
-  subscribes_to :user_registered
-
-  def handle(event)
-    # event.payload is symbol-keyed
-    UserMailer.welcome(event.payload[:user_id]).deliver_later
-  end
-end
+event.payload        # => { weight: 500 }   (symbol-keyed, built from inputs)
+event.process_type   # => :durable          (from the rules file)
 ```
 
-- `subscribes_to(:event_name)` registers the subscriber at load time.
-- `handle(event)` is required; the base raises `NotImplementedError` otherwise.
+Input validation (missing required input, unknown input) raises `ArgumentError` at
+build time.
 
-> **Who actually calls subscribers?** The core gem only *registers* subscribers in
-> `EventEngine::SubscriberRegistry` — it does not invoke them. Invocation is done by
-> a handler. `event_engine-delivery` invokes subscribers for levels 1–3 (see its
-> docs). If you run core standalone, your own handler decides when/whether to call
-> `EventEngine::SubscriberRegistry.subscribers_for(event.event_name)`.
+### Named helpers (`MarketingEvents.lead_created`)
 
-Keep subscribers **idempotent** — at levels 3+ they may be retried.
+The ergonomic per-event helpers live in the **domain packs**, generated by
+`event_engine-event_definition`. This runtime does not generate them; at boot it will
+`load db/event_engine_helpers.rb` **if a pack has committed one**, but it never
+creates that file. Once the [publisher adapter](#the-intended-passive-wiring-tbd)
+is wired, calling a pack helper routes through `EventEngine.emit` for you; until then,
+call `EventEngine.emit` directly.
 
 ---
 
-## Event levels
+## Declaring how events are processed
 
-`event_level` is a hint that tells the *delivery* layer how hard to work to get an
-event where it's going. **Your producer code never changes when you move an event up
-a level — it's a one-line edit to the definition.**
+Every event in the catalog gets its processing declared in one file,
+`config/event_rules.yml`. The catalog task writes it for you and keeps it in step
+with the catalog.
 
-| Level | Durable? | Where it goes | Adopt when | Watch out for |
-|---|---|---|---|---|
-| **1 sync** | no | in-app subscribers, synchronously in the caller's stack | a cheap in-process reaction that must happen now | a slow/failing subscriber blocks the caller; nothing persists, so it's lost on a crash |
-| **2 job** | no | in-app subscribers, via a background job | the reaction can be deferred | still not durable; needs an ActiveJob backend; failures don't surface to the caller |
-| **3 outbox** | **yes** | in-app subscribers, when the outbox drains | the reaction must survive a crash and be atomic with your DB write | more moving parts; delivery is eventual |
-| **4 outbox + broker** | **yes** | **outside the app**, to a transport (Kafka, …) | an independent service consumes it on its own cycle | it's a cross-service contract — schema/version discipline matters; needs a real transport |
+```yaml
+default: subscribers      # anything not named below
+packs:
+  marketing: subscribers  # every event in the marketing pack
+  billing: ledger
+events:
+  invoice_voided: audit   # this one event
+  lead_converted:         # catalogued but undecided
+```
 
-Guiding principle: **adopt the lowest level that solves your real problem; move up
-only when the problem demands it.** Signals to move up:
+A rule names a **registered processor**. Resolution is **event → pack → default**,
+and the resolved name is both the processor invoked and the value stamped on
+`event.process_type`, so the two cannot disagree.
 
-- A level-1 subscriber is slow / on the request hot path → **1 → 2**.
-- Work is lost across crashes/restarts/deploys → **2 → 3**.
-- An independent service must consume the event → **3 → 4**.
+### Keeping it in step with the catalog
 
-> **The level table describes behavior implemented by `event_engine-delivery`.** The
-> core gem only stamps `event_level` onto the event and dispatches it. Levels 1–4
-> *mean* something only once a handler that interprets them is registered. Level 5
-> (event sourcing) is reserved but unsupported by the delivery layer.
+`bin/rails event_engine:catalog` writes this file alongside the catalog:
 
-> **Caveat:** if you omit `event_level`, the event's level is `nil`. Handlers decide
-> how to treat `nil` — `event_engine-delivery`, for instance, routes `nil` through
-> its outbox path (the `else` branch). Set a level explicitly to be unambiguous.
+- every catalogued event appears, so a new event is visible rather than silently unrouted
+- rules you have already decided are preserved
+- `default` and `packs` are preserved
 
----
+A newly catalogued event appears with no value. It falls through to its pack rule or
+the default; if neither exists, emitting it raises rather than being dropped.
 
-## The handler extension point
+### When a rule is wrong
 
-This is the seam every companion gem (and you) plug into. A **handler** is any
-object that responds to `call(event)`. Register it with the levels it cares about:
+Both misconfigurations fail loudly and name the fix:
 
-```ruby
-EventEngine.register_handler(handler, levels: :all)   # every event
-EventEngine.register_handler(handler, levels: 1..4)   # a Range
-EventEngine.register_handler(handler, levels: [1, 3]) # an explicit list
 ```
+EventEngine::UnroutableEventError:
+  no processing rule for event :lead_converted (pack :marketing);
+  declare it in the rules file under events, packs, or default
 
-On `EventEngine.dispatch(event)`, every handler whose `levels:` include
-`event.event_level` (or `:all`) gets `call(event)`, in registration order.
-
-A minimal standalone handler — no companion gem required:
-
-```ruby
-# config/initializers/event_engine.rb
-class LogEverythingHandler
-  def call(event)
-    Rails.logger.info("[event] #{event.event_name} v#{event.event_version} #{event.payload.inspect}")
-    event
-  end
-end
-
-Rails.application.config.after_initialize do
-  EventEngine.register_handler(LogEverythingHandler.new, levels: :all)
-end
+EventEngine::UnregisteredProcessorError:
+  the rule for event :lead_created (pack :marketing) names processor :ghost,
+  but no processor is registered under that name
 ```
 
-This is exactly how the companion gems hook in:
+Declaring nothing at all is still valid: with an empty rules file no processor is
+invoked and events are built and returned as before.
 
-- **`event_engine-delivery`** registers a handler at `levels: :all` that routes by
-  level (sync subscribers / background job / outbox / broker).
-- **`event_engine-store`** registers two handlers at `levels: :all` (a recorder and a
-  projection dispatcher).
+---
+
+## Configuration
 
-Other primitives on the `EventEngine` module:
+Set via `EventEngine.configure { |config| … }`. All fields are optional.
 
-- `EventEngine.dispatch(event)` — fan an `Event` out to handlers (helpers call this).
-- `EventEngine.reset_handlers!` — clear all handlers (useful in tests, or to fully
-  take over routing).
+| Field | Default | Accepts | What it does |
+|---|---|---|---|
+| `schema_path` | `"db/event_schema.json"` | String / path | The committed catalog the engine loads at boot, and the file the catalog task writes. |
+| `rules_path` | `"config/event_rules.yml"` | String / path | The processing rules the runtime loads, and the file the catalog task keeps in step. |
+| `metadata_defaults` | `nil` | A callable (`-> { Hash }`) | Called on each emit; its hash is merged **under** any call-site `metadata:` (call-site wins). A raising callable is swallowed and logged, so emission never breaks. |
+| `logger` | `Rails.logger` | Any Logger | Where the engine logs (missing-schema warning, a raising `metadata_defaults`). |
+| `publisher_schema_paths` | `[]` | Array of paths | Pins the catalog task to an explicit list of `schema.json` files. Leave empty to discover registered packs. |
 
-> Handlers run **in-process, in order, synchronously** within `dispatch`. If a
-> handler raises, later handlers don't run and the exception propagates to the
-> caller. Order matters: register `event_engine-store` before/after `delivery`
-> deliberately if both are present.
+Processing is **not** configured here — it is declared in the
+[rules file](#declaring-how-events-are-processed).
 
 ---
 
-## Configuration
+## The `Event`
 
-The **core** gem's configuration is intentionally tiny — just a logger:
+`EventEngine::Event` is a keyword-init `Struct`:
 
-```ruby
-# config/initializers/event_engine.rb
-EventEngine.configure do |config|
-  config.logger = Rails.logger   # the only core option
-end
+```
+event_name  event_type  event_version  process_type  subject  domain
+payload  metadata  occurred_at  idempotency_key
+aggregate_type  aggregate_id  aggregate_version
 ```
 
-| Option | Default | Purpose |
-|---|---|---|
-| `logger` | `Rails.logger` (or `Logger.new($stdout)` outside Rails) | Where core logs |
-
-> Delivery options (`delivery_adapter`, `transport`, `batch_size`, …) belong to
-> `event_engine-delivery` and are set via `EventEngine::Delivery.configure` — see that
-> gem's README.
+`Event.from(record)` rebuilds one from any object exposing those readers (symbolizing
+the payload keys) — handy for processor gems reconstituting a persisted event.
 
 ---
 
 ## Rake tasks
 
-| Task | Purpose |
+| Task | What it does |
 |---|---|
-| `event_engine:schema:dump` | Compile definitions → `db/event_schema.rb` (commit it) |
-| `event_engine:schema:verify` | Fail with a readable diff if definitions have drifted (use in CI) |
-| `event_engine:schema` | Same drift check, no diff |
-| `event_engine:schema_check` | Same drift check, no diff (alternate name) |
+| `event_engine:catalog` | Builds the committed catalog at `schema_path` from every discovered pack (or from `publisher_schema_paths` when set), then keeps the rules file at `rules_path` in step with it. |
 
-(`event_engine-delivery` adds `dead_letters:*` and `outbox:cleanup` tasks.)
 
 ---
 
-## Installation generator
+## Known gaps
 
-```bash
-bin/rails g event_engine:install
-```
-
-It creates `config/initializers/event_engine.rb`, a stub `db/event_schema.rb`, and
-installs Claude Code subagent files under `.claude/agents/` (see
-[For AI assistants](#for-ai-assistants)).
-
-The core gem itself ships no migrations. If you need the outbox or the event log,
-install the companion gem you need and run its migrations directly (see
-`event_engine-delivery` / `event_engine-store`).
+- **Boot requires a committed `db/event_schema.json`.** The engine raises in
+  production if it is missing. Building it is one task (`event_engine:catalog`),
+  but it does have to be committed.
+- **`the_local` guides.** The AI-assistant reference under
+  `lib/event_engine/reference/` and the `the_local` subagents still describe the old
+  in-gem DSL. They are generated provider docs (owned by `the_local-develop`) and
+  will be regenerated to match this runtime.
 
 ---
 
-## For AI assistants
-
-A condensed, authoritative API reference ships inside the gem at
-`lib/event_engine/reference/guide.md` and is installed into consuming apps as Claude
-Code subagents (`.claude/agents/`). When working in a host app, prefer that
-reference and this README over reading gem internals.
+## Development
 
----
-
-## Contributing
-
-1. Fork and create a feature branch.
-2. Add tests for behavior changes (Minitest; see `test/`).
-3. Run the suite: `bundle exec rake test`.
-4. Open a PR.
+```bash
+bundle install
+bundle exec rake test        # Minitest, via the dummy app in test/dummy
+```
 
 ---
 
 ## License
 
-Available as open source under the terms of the
-[MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).