railsdrip-engine 0.0.1

data/db/migrate/20260829123000_create_rails_drips_tables.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+class CreateRailsDripsTables < ActiveRecord::Migration[7.0]
+  def change
+    metadata_type = postgresql? ? :jsonb : :json
+
+    create_table :rails_drips_campaigns do |t|
+      t.string :key, null: false
+      t.string :name, null: false
+      t.text :description
+      t.integer :status, null: false, default: 0
+      t.boolean :allow_reenrollment, null: false, default: false
+      t.bigint :current_version_id
+      t.string :default_email_category
+      t.public_send(metadata_type, :data, null: false, default: {})
+      t.timestamps
+    end
+    add_index :rails_drips_campaigns, :key, unique: true
+    add_index :rails_drips_campaigns, :status
+    add_index :rails_drips_campaigns, :current_version_id
+
+    create_table :rails_drips_campaign_versions do |t|
+      t.references :campaign, null: false, foreign_key: { to_table: :rails_drips_campaigns }
+      t.integer :version_number, null: false
+      t.integer :status, null: false, default: 0
+      t.datetime :activated_at
+      t.references :created_by, polymorphic: true
+      t.timestamps
+    end
+    add_index :rails_drips_campaign_versions,
+      [:campaign_id, :version_number],
+      unique: true,
+      name: "idx_rails_drips_versions_campaign_number"
+    add_index :rails_drips_campaign_versions,
+      :campaign_id,
+      unique: true,
+      where: "status = 1",
+      name: "idx_rails_drips_versions_active_campaign"
+
+    add_foreign_key :rails_drips_campaigns,
+      :rails_drips_campaign_versions,
+      column: :current_version_id
+
+    create_table :rails_drips_steps do |t|
+      t.references :campaign_version, null: false, foreign_key: { to_table: :rails_drips_campaign_versions }
+      t.integer :position, null: false
+      t.string :name, null: false
+      t.integer :kind, null: false, default: 0
+      t.integer :delay_amount, null: false, default: 0
+      t.string :delay_unit, null: false, default: "days"
+      t.string :email_key, null: false
+      t.string :email_category
+      t.public_send(metadata_type, :data, null: false, default: {})
+      t.timestamps
+    end
+    add_index :rails_drips_steps,
+      [:campaign_version_id, :position],
+      unique: true,
+      name: "idx_rails_drips_steps_version_position"
+    add_index :rails_drips_steps, :email_key
+
+    create_table :rails_drips_enrollments do |t|
+      t.references :campaign, null: false, foreign_key: { to_table: :rails_drips_campaigns }
+      t.references :campaign_version, null: false, foreign_key: { to_table: :rails_drips_campaign_versions }
+      t.references :recipient, polymorphic: true, null: false
+      t.integer :status, null: false, default: 0
+      t.string :entry_source
+      t.string :exit_reason
+      t.references :added_by, polymorphic: true
+      t.references :removed_by, polymorphic: true
+      t.datetime :enrolled_at
+      t.datetime :paused_at
+      t.datetime :removed_at
+      t.datetime :completed_at
+      t.datetime :failed_at
+      t.public_send(metadata_type, :data, null: false, default: {})
+      t.timestamps
+    end
+    add_index :rails_drips_enrollments, [:campaign_id, :status]
+    add_index :rails_drips_enrollments, [:campaign_version_id, :status], name: "idx_rails_drips_enrollments_version_status"
+    add_index :rails_drips_enrollments,
+      [:campaign_id, :recipient_type, :recipient_id],
+      unique: true,
+      where: "status IN (0, 1)",
+      name: "idx_rails_drips_enrollments_open_recipient"
+
+    create_table :rails_drips_enrollment_events do |t|
+      t.references :enrollment, null: false, foreign_key: { to_table: :rails_drips_enrollments }
+      t.string :event_type, null: false
+      t.references :actor, polymorphic: true
+      t.datetime :occurred_at, null: false
+      t.public_send(metadata_type, :data, null: false, default: {})
+      t.timestamps
+    end
+    add_index :rails_drips_enrollment_events,
+      [:enrollment_id, :occurred_at],
+      name: "idx_rails_drips_events_enrollment_occurred"
+    add_index :rails_drips_enrollment_events, :event_type
+
+    create_table :rails_drips_deliveries do |t|
+      t.references :enrollment, null: false, foreign_key: { to_table: :rails_drips_enrollments }
+      t.references :step, null: false, foreign_key: { to_table: :rails_drips_steps }
+      t.references :recipient, polymorphic: true
+      t.string :recipient_email, null: false
+      t.integer :status, null: false, default: 0
+      t.datetime :scheduled_for, null: false
+      t.datetime :sent_at
+      t.datetime :failed_at
+      t.datetime :cancelled_at
+      t.string :campaign_key, null: false
+      t.string :email_key, null: false
+      t.string :email_category
+      t.string :subject_snapshot
+      t.text :html_body_snapshot
+      t.text :text_body_snapshot
+      t.string :provider
+      t.string :provider_message_id
+      t.integer :attempts, null: false, default: 0
+      t.text :last_error
+      t.public_send(metadata_type, :data, null: false, default: {})
+      t.timestamps
+    end
+    add_index :rails_drips_deliveries,
+      [:enrollment_id, :step_id],
+      unique: true,
+      name: "idx_rails_drips_deliveries_enrollment_step"
+    add_index :rails_drips_deliveries,
+      [:status, :scheduled_for],
+      name: "idx_rails_drips_deliveries_due"
+    add_index :rails_drips_deliveries, :recipient_email
+    add_index :rails_drips_deliveries, :campaign_key
+    add_index :rails_drips_deliveries, :email_key
+    add_index :rails_drips_deliveries, :provider_message_id
+  end
+
+  private
+
+  def postgresql?
+    connection.adapter_name.casecmp("PostgreSQL").zero?
+  end
+end
+

data/docs/README.md

@@ -0,0 +1,13 @@
+# RailsDrips documentation
+
+Start with [Getting started](getting-started.md) if you are adding RailsDrips to an application.
+
+| Guide | Use it when |
+| --- | --- |
+| [Getting started](getting-started.md) | Installing the engine and sending the first campaign |
+| [Host integration](host-integration.md) | Wiring mailers, product rules, lifecycle triggers, jobs, or admin access |
+| [Architecture](architecture.md) | Understanding ownership, persistence, transactions, and delivery flow |
+| [Campaign definitions](campaign-definitions.md) | Authoring or changing YAML campaigns |
+| [Operations](operations.md) | Running the admin, audits, retries, and incident recovery |
+
+The files under `research/extracting-drip-engine/` explain the extraction decisions. They are maintainer references rather than required setup reading.

data/docs/architecture.md

@@ -0,0 +1,95 @@
+# Architecture
+
+RailsDrips is an isolated Rails engine with a headless workflow core and an optional operational UI.
+
+## Runtime ownership
+
+```mermaid
+flowchart LR
+  Event[Host product event] --> API[RailsDrips public API]
+  Definition[YAML campaign definition] --> Import[Definition importer]
+  Import --> DB[(RailsDrips tables)]
+  API --> DB
+  DB --> Commit[After database commit]
+  Commit --> AJ[Host Active Job adapter]
+  AJ --> Job[RailsDrips delivery job]
+  Job --> Policy[Host eligibility and preferences]
+  Policy --> Registry[Host mail registry]
+  Registry --> Mailer[Host Action Mailer]
+  Mailer --> Hook[Host transport hook]
+  Hook --> Transport[Host mail transport]
+  Job --> Evidence[Snapshots and enrollment events]
+  Evidence --> DB
+```
+
+The engine can schedule and audit email without knowing the host's `User` model, subscription system, mail provider, queue adapter, or product lifecycle.
+
+## Persistence model
+
+| Record | Purpose |
+| --- | --- |
+| `RailsDrips::Campaign` | Stable campaign identity and lifecycle state |
+| `RailsDrips::CampaignVersion` | Frozen executable definition used by a set of enrollments |
+| `RailsDrips::Step` | Ordered email key, category, and delay within one version |
+| `RailsDrips::Enrollment` | One recipient's journey through one frozen campaign version |
+| `RailsDrips::Delivery` | Scheduled attempt plus recipient, content snapshot, provider receipt, and failure state |
+| `RailsDrips::EnrollmentEvent` | Append-only evidence for enrollment and delivery transitions |
+
+Recipients and actors are polymorphic associations. Host records stay in host tables.
+
+## Definition and version flow
+
+1. YAML imports into a draft campaign version.
+2. Activation makes that version current for new enrollments.
+3. Existing enrollments remain attached to their original version.
+4. Metadata-only imports update the campaign without versioning.
+5. A step, delay, key, kind, position, or category change creates a new draft.
+6. Activating the draft retires the previous active version.
+
+The importer never edits active or retired versions, so a definition import cannot silently change messages already scheduled for recipients in flight. Direct model mutation is an internal, unsupported integration path.
+
+## Enrollment transaction
+
+`RailsDrips.enroll` resolves the campaign and recipient email, checks policy and idempotency, then creates the enrollment, initial event, and all step deliveries in one transaction. Delays are cumulative from `enrolled_at`.
+
+Each delivery enqueues through `after_create_commit`, so jobs appear only after the surrounding transaction commits—even when the host calls enrollment inside a larger transaction.
+
+A database partial unique index permits only one open enrollment for a campaign/recipient pair. The service converts concurrency collisions into `already_open`.
+
+## Delivery state machine
+
+```mermaid
+stateDiagram-v2
+  [*] --> scheduled
+  scheduled --> sending: guards pass and message is snapshotted
+  scheduled --> cancelled: campaign, enrollment, or preference rejects
+  sending --> sent: transport returns
+  sending --> failed: render, hook, or transport raises
+  failed --> scheduled: explicit retry
+  scheduled --> cancelled: operator or lifecycle cancellation
+```
+
+The job locks rows for state transitions but does not hold a database lock across transport I/O. A duplicate job sees a non-scheduled row and exits.
+
+There is an unavoidable ambiguity if the provider accepts a message and the process crashes before RailsDrips records `sent`. Delivery and provider message IDs provide correlation evidence; operators should investigate before retrying a `sending` row.
+
+## Campaign lifecycle
+
+- **Draft:** definition exists but cannot enroll recipients.
+- **Active:** accepts enrollments and permits delivery.
+- **Paused:** does not send; scheduled rows remain available for resume.
+- **Archived:** does not send or enroll and cancels future scheduled work.
+
+Resume re-enqueues only deliveries already due. A due-repair operation is also exposed independently.
+
+## Public and internal surfaces
+
+The stable host entry points are module methods on `RailsDrips`, configuration callables, definition tasks, and model data exposed to registered mailers.
+
+Services under `RailsDrips::*` support engine controllers and testing but should not be the first integration choice when a module-level operation exists. Change engine states through lifecycle services rather than direct status updates.
+
+## Optional admin
+
+The admin is a view over engine records and operations, not the source of host templates or product rules. It must remain usable without Tailwind, Turbo, Devise, GoodJob, or a particular `User` class.
+
+The current interface is deliberately minimal. The next UI iteration adds a coherent design system, draft authoring, sample data, and a runnable dummy app; see the [admin UI TODO](todo/admin-ui-and-dummy-app.md).

data/docs/campaign-definitions.md

@@ -0,0 +1,100 @@
+# Campaign definitions
+
+Campaign definitions are reviewable YAML files describing a campaign and its ordered email steps. They are safe-loaded: aliases and Ruby object construction are rejected.
+
+## Complete example
+
+```yaml
+schema_version: 1
+campaign:
+  key: onboarding
+  name: Customer onboarding
+  description: Helps a new customer reach their first success.
+  allow_reenrollment: false
+  default_email_category: product_education
+  data:
+    owner: lifecycle_team
+  steps:
+    - position: 1
+      name: Welcome
+      kind: email
+      delay_amount: 0
+      delay_unit: minutes
+      email_key: welcome
+      data:
+        purpose: activation
+    - position: 2
+      name: First project reminder
+      kind: email
+      delay_amount: 2
+      delay_unit: days
+      email_key: first_project_reminder
+      email_category: product_reminders
+```
+
+## Campaign fields
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `key` | Yes | Stable machine identifier used by enrollment calls |
+| `name` | Yes | Operator-facing name |
+| `description` | No | Operator-facing purpose and audience |
+| `allow_reenrollment` | No | Whether a recipient with a closed enrollment may enter again; defaults to false |
+| `default_email_category` | No | Default preference category for steps |
+| `data` | No | Non-executable campaign metadata |
+| `steps` | Yes | Non-empty ordered list of executable steps |
+
+## Step fields
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `position` | Yes | Unique positive integer within the version |
+| `name` | Yes | Operator-facing step name |
+| `kind` | No | Currently only `email`; defaults to `email` |
+| `delay_amount` | Yes | Non-negative integer added after the previous step |
+| `delay_unit` | Yes | `minutes`, `hours`, or `days` |
+| `email_key` | Yes | Key registered by the host initializer |
+| `email_category` | No | Step-specific category overriding the campaign default |
+| `data` | No | Step metadata copied into the version |
+
+Delays are cumulative. In the example, welcome is immediate and the reminder is two days later.
+
+## Validation and import
+
+```bash
+# Validate syntax, schema, and registered mailer keys.
+bin/rails rails_drips:validate DEFINITION=config/rails_drips/onboarding.yml
+
+# Preview without writing.
+bin/rails rails_drips:import DEFINITION=config/rails_drips/onboarding.yml
+
+# Apply.
+bin/rails rails_drips:import DEFINITION=config/rails_drips/onboarding.yml APPLY=true
+```
+
+The importer returns outcomes such as `created`, `unchanged`, `metadata_updated`, or `version_created`. Each campaign imports transactionally.
+
+## What creates a version?
+
+Changing executable step fields creates a complete new draft. Active and retired versions are never edited. Executable fields include position, name, kind, delay, email key, category, and step data.
+
+Changing safe campaign metadata—name, description, reenrollment setting, default category, or campaign data—updates the campaign without creating a version.
+
+Activate a newly imported version explicitly:
+
+```bash
+bin/rails rails_drips:activate CAMPAIGN=onboarding VERSION=2
+```
+
+New enrollments use version 2. Existing enrollments continue using the version they entered with.
+
+## Recommended workflow
+
+1. Register and test every new mailer key in the host.
+2. Change YAML in a reviewed pull request.
+3. Validate in CI.
+4. Dry-run in the target environment.
+5. Apply the import.
+6. Inspect the draft version and steps.
+7. Activate deliberately.
+8. Monitor scheduled delivery counts and failures.

data/docs/getting-started.md

@@ -0,0 +1,170 @@
+# Getting started
+
+This guide takes a host application from installation to its first scheduled drip.
+
+## 1. Install the engine
+
+Add RailsDrips to the host application's Gemfile and run:
+
+```bash
+bundle install
+bin/rails generate rails_drips:install
+bin/rails db:migrate
+```
+
+The generator creates:
+
+- `config/initializers/rails_drips.rb`
+- `config/rails_drips/onboarding.yml`
+- a timestamped RailsDrips migration
+
+It does not run the migration. Re-running the generator uses normal Rails generator collision handling.
+
+RailsDrips uses the host application's database, Active Job adapter, Action Mailer configuration, logger, and time zone.
+
+## 2. Create the email in the host application
+
+RailsDrips never owns product email copy or templates. Create a regular Action Mailer class:
+
+```ruby
+# app/mailers/onboarding_mailer.rb
+class OnboardingMailer < ApplicationMailer
+  def welcome(delivery)
+    @delivery = delivery
+    @enrollment = delivery.enrollment
+    @recipient = @enrollment.recipient
+
+    mail(to: delivery.recipient_email, subject: "Welcome to Example")
+  end
+end
+```
+
+Add its normal templates:
+
+```erb
+<%# app/views/onboarding_mailer/welcome.html.erb %>
+<h1>Welcome, <%= @recipient.name %></h1>
+```
+
+The mailer receives a persisted `RailsDrips::Delivery`. Useful values include:
+
+- `delivery.recipient_email`
+- `delivery.email_key` and `delivery.email_category`
+- `delivery.enrollment.recipient`
+- `delivery.enrollment.data_value`
+- `delivery.enrollment.campaign`
+- `delivery.step`
+
+## 3. Register the mailer key
+
+Connect the YAML `email_key` to the host mailer in the generated initializer:
+
+```ruby
+RailsDrips.configure do |config|
+  config.delivery_queue_name = :mailers
+
+  config.mailers.register "welcome", label: "Welcome email" do |delivery|
+    OnboardingMailer.welcome(delivery)
+  end
+end
+```
+
+The block must return an `ActionMailer::MessageDelivery`. Registration happens at application boot, so every key referenced by a definition must be registered before validating or importing that definition.
+
+## 4. Define and activate a campaign
+
+Edit `config/rails_drips/onboarding.yml`:
+
+```yaml
+schema_version: 1
+campaign:
+  key: onboarding
+  name: Customer onboarding
+  description: Helps a new customer reach their first success.
+  allow_reenrollment: false
+  steps:
+    - position: 1
+      name: Welcome
+      kind: email
+      delay_amount: 0
+      delay_unit: minutes
+      email_key: welcome
+```
+
+Validate and preview the database operation:
+
+```bash
+bin/rails rails_drips:validate DEFINITION=config/rails_drips/onboarding.yml
+bin/rails rails_drips:import DEFINITION=config/rails_drips/onboarding.yml
+```
+
+Import writes only when `APPLY=true`:
+
+```bash
+bin/rails rails_drips:import DEFINITION=config/rails_drips/onboarding.yml APPLY=true
+bin/rails rails_drips:activate CAMPAIGN=onboarding VERSION=1
+```
+
+Importing creates a draft. Activation is deliberately separate so a definition can be reviewed before it accepts enrollments.
+
+## 5. Enroll from a product event
+
+Call RailsDrips from the host service, job, controller, or model callback that owns the product event:
+
+```ruby
+result = RailsDrips.enroll(
+  campaign: "onboarding",
+  recipient: account,
+  source: "account_created",
+  data: { plan: account.plan }
+)
+
+case result.status
+when :enrolled
+  Rails.logger.info("Enrolled ##{result.enrollment.id}")
+when :already_open, :reenrollment_disallowed
+  # Expected idempotent outcomes.
+when :campaign_inactive, :ineligible
+  # Expected business outcomes; result.reason may explain policy rejection.
+end
+```
+
+The recipient may be any persisted Active Record model. By default it must respond to `email_address` or `email`; configure a resolver if it does not.
+
+Remove a recipient from future steps when the owning product event occurs:
+
+```ruby
+RailsDrips.remove(
+  campaign: "onboarding",
+  recipient: account,
+  reason: "account_closed",
+  actor: Current.user
+)
+```
+
+Removal retains sent and failed evidence and cancels future scheduled deliveries.
+
+## 6. Run workers
+
+RailsDrips uses only Active Job APIs. Configure and run the host application's chosen adapter—Solid Queue, GoodJob, Sidekiq, or another Active Job backend. RailsDrips does not start workers itself.
+
+In development, verify the configured adapter actually processes the queue named by `delivery_queue_name`.
+
+## 7. Optional admin mount
+
+Mount the engine in the host router:
+
+```ruby
+# config/routes.rb
+mount RailsDrips::Engine => "/drips"
+```
+
+The current campaign index is then `/drips/campaigns`, but it returns `404` until the host explicitly enables and secures admin access. See [Operations](operations.md).
+
+The current pages are an operational prototype. They are useful for inspecting engine data, but the finished admin design and demonstration app are tracked separately.
+
+## Next steps
+
+- Add [host policies and transport integration](host-integration.md) if the product has eligibility or unsubscribe rules.
+- Read [campaign definitions](campaign-definitions.md) before changing an active campaign.
+- Set up [operational access and auditing](operations.md) before production use.

data/docs/host-integration.md

@@ -0,0 +1,160 @@
+# Host application integration
+
+RailsDrips is intentionally not a complete email product by itself. It provides the reusable state machine and delivery machinery while the host application keeps control of product behavior.
+
+## What the host must implement
+
+Only three integrations are required for a basic campaign:
+
+1. An Action Mailer method and templates for every registered `email_key`.
+2. A registration block connecting each key to its mailer method.
+3. A call to `RailsDrips.enroll` from the product event that begins the journey.
+
+The host must also run an Active Job worker where scheduled delivery should occur. Everything else in this guide is optional.
+
+## Integration map
+
+| Host concern | Required? | Code location | RailsDrips calls it when |
+| --- | --- | --- | --- |
+| Mailer and templates | Yes | `app/mailers`, `app/views` | A scheduled delivery is ready to render |
+| Mail registry | Yes | RailsDrips initializer | A delivery resolves its `email_key` |
+| Enrollment trigger | Yes | Host domain service/job/controller | The host decides a recipient should enter a campaign |
+| Active Job backend | Production | Host environment configuration | A delivery is scheduled or retried |
+| Recipient email resolver | For nonstandard models | RailsDrips initializer | Enrollment snapshots the destination address |
+| Eligibility evaluator | Optional | Initializer or host policy object | Enrollment and immediately before delivery |
+| Preference evaluator | Optional | Initializer or host policy object | Immediately before delivery |
+| Transport metadata hook | Optional | RailsDrips initializer | After rendering and before transport |
+| Admin security adapters | For admin only | RailsDrips initializer | Every engine admin request |
+| Queue inventory | Optional | Host operations adapter | An integrity audit requests queue evidence |
+
+## Mail registration
+
+```ruby
+config.mailers.register "trial_day_1", label: "Trial: getting started" do |delivery|
+  TrialMailer.getting_started(delivery)
+end
+```
+
+The registry block receives the engine delivery and must return an `ActionMailer::MessageDelivery`. Keep selection logic in the registry or host mailer; do not put host-specific mailer constants in the gem.
+
+Mailer keys are executable definition identifiers. Renaming a key creates a new campaign version.
+
+## Recipient integration
+
+Enrollments use a polymorphic `recipient`; the engine does not require a `User` class. The default email resolver tries `recipient.email_address`, then `recipient.email`.
+
+```ruby
+config.recipient_email_resolver = ->(recipient) do
+  recipient.primary_contact.email
+end
+
+config.recipient_label_resolver = ->(recipient) do
+  "#{recipient.company_name} (#{recipient.email})"
+end
+```
+
+The resolved email is copied to the delivery when the enrollment is scheduled. This preserves evidence even if the recipient changes its email later.
+
+## Eligibility
+
+The eligibility evaluator defaults to allowing delivery. It runs at enrollment and again immediately before delivery:
+
+```ruby
+config.eligibility_evaluator = lambda do |recipient:, campaign:, phase:, **context|
+  decision = CampaignEligibility.call(
+    recipient: recipient,
+    campaign_key: campaign.key,
+    phase: phase,
+    delivery: context[:delivery]
+  )
+
+  { eligible: decision.allowed?, reason: decision.reason }
+end
+```
+
+- `phase: :enrollment` runs before enrollment rows are written.
+- `phase: :delivery` runs before rendering and sending each message.
+
+Return `true`/`false`, or a hash with `eligible` or `allowed` plus an optional `reason`. Business rejection returns a result or cancellation state; policy exceptions remain real failures.
+
+`force: true` bypasses eligibility and preference checks. The choice is persisted for auditability; reserve it for explicit operator or migration workflows.
+
+## Email preferences
+
+The preference evaluator also defaults to allowing delivery:
+
+```ruby
+config.preference_evaluator = lambda do |recipient:, category:, delivery:|
+  category.blank? || recipient.subscribed_to_email_category?(category)
+end
+```
+
+Set `default_email_category` on a campaign or `email_category` on a step. The step wins. RailsDrips stores the resolved category but does not define categories or unsubscribe pages—the host owns those concepts.
+
+## Transport metadata
+
+Decorate the final `Mail::Message` before delivery:
+
+```ruby
+config.transport_metadata_hook = lambda do |message:, delivery:|
+  message.header["X-Campaign-Key"] = delivery.campaign_key
+  message.header["X-RailsDrips-Delivery-ID"] = delivery.id.to_s
+  message
+end
+```
+
+Use this for provider tags, correlation IDs, or custom headers. Return the message that should be snapshotted and delivered. Provider SDKs and credentials remain host concerns.
+
+## Product lifecycle calls
+
+RailsDrips does not guess when someone enters or leaves a campaign. Put calls at the host's domain boundary:
+
+```ruby
+class Accounts::Activate
+  def call(account)
+    # Host activation work...
+    RailsDrips.enroll(campaign: "onboarding", recipient: account, source: "activation")
+  end
+end
+```
+
+The public operations are:
+
+```ruby
+RailsDrips.enroll(...)
+RailsDrips.remove(...)
+RailsDrips.pause_campaign(campaign: campaign)
+RailsDrips.resume_campaign(campaign: campaign)
+RailsDrips.archive_campaign(campaign: campaign, reason: "retired")
+RailsDrips.unarchive_campaign(campaign: campaign)
+RailsDrips.enqueue_due_deliveries(campaign: campaign, dry_run: true)
+```
+
+Operations return a `RailsDrips::Result` with a stable `status` and relevant `campaign`, `enrollment`, `delivery`, `reason`, or `count` values.
+
+## Reloading registrations in development
+
+The registry rejects duplicate keys. If the host uses a Rails reloader hook, clear and rebuild it inside that hook:
+
+```ruby
+Rails.application.config.to_prepare do
+  RailsDrips.configuration.mailers.clear
+  RailsDrips.configuration.mailers.register("welcome", label: "Welcome") do |delivery|
+    OnboardingMailer.welcome(delivery)
+  end
+end
+```
+
+Use either a boot-time initializer or `to_prepare`; do not register the same key through both paths.
+
+## Host integration tests
+
+At minimum, cover:
+
+- every registered key returns a renderable `ActionMailer::MessageDelivery`;
+- lifecycle events enroll and remove the intended recipient;
+- enrollment and delivery eligibility decisions;
+- unsubscribe/category rejection;
+- metadata on the final message;
+- the chosen Active Job adapter executes scheduled jobs;
+- admin routes fail closed and authorized operators can access them, if mounted.