seams 0.1.0

data/lib/generators/seams/billing/templates/app/views/checkout/success.html.erb.tt

@@ -0,0 +1,5 @@
+<h1>Thanks!</h1>
+
+<p>Your subscription is being activated. You'll receive a confirmation email shortly.</p>
+
+<p><%%= link_to "Back to plans", billing.plans_path %></p>

data/lib/generators/seams/billing/templates/app/views/invoices/index.html.erb.tt

@@ -0,0 +1,22 @@
+<%%# Read-only invoice history for the signed-in user. %>
+<h1>Billing history</h1>
+
+<%% if @invoices.empty? %>
+  <p>No invoices yet.</p>
+<%% else %>
+  <table>
+    <thead>
+      <tr><th>Date</th><th>Amount</th><th>Status</th><th></th></tr>
+    </thead>
+    <tbody>
+      <%% @invoices.each do |invoice| %>
+        <tr>
+          <td><%%= invoice.created_at.to_date %></td>
+          <td><%%= Billing::CurrencyHelper.format_money(invoice.amount_cents, invoice.currency) %></td>
+          <td><%%= invoice.status.titleize %></td>
+          <td><%%= link_to "View", invoice_path(invoice) %></td>
+        </tr>
+      <%% end %>
+    </tbody>
+  </table>
+<%% end %>

data/lib/generators/seams/billing/templates/app/views/invoices/show.html.erb.tt

@@ -0,0 +1,14 @@
+<%%# Single invoice view. The Stripe-hosted PDF lives off the gateway %>
+<%%# (we do not proxy it); add a `hosted_invoice_url` link in your host %>
+<%%# override if you want one. %>
+<h1>Invoice <%%= @invoice.gateway_ref %></h1>
+
+<dl>
+  <dt>Amount</dt>      <dd><%%= Billing::CurrencyHelper.format_money(@invoice.amount_cents, @invoice.currency) %></dd>
+  <dt>Status</dt>      <dd><%%= @invoice.status.titleize %></dd>
+  <dt>Customer</dt>    <dd><%%= @invoice.customer_ref %></dd>
+  <dt>Subscription</dt><dd><%%= @invoice.subscription_ref %></dd>
+  <dt>Paid at</dt>     <dd><%%= @invoice.paid_at %></dd>
+</dl>
+
+<%%= link_to "Back to billing history", invoices_path %>

data/lib/generators/seams/billing/templates/app/views/plans/index.html.erb.tt

@@ -0,0 +1,51 @@
+<h1>Plans</h1>
+
+<%% if @recurring_plans.any? %>
+  <section class="plans plans-recurring">
+    <h2>Subscriptions</h2>
+    <%% @recurring_plans.each do |plan| %>
+      <article class="plan">
+        <h3><%%= plan.name %></h3>
+        <p class="plan-price">
+          <%%= number_to_currency(plan.amount_cents / 100.0, unit: plan.currency.upcase + " ") %> /
+          <%%= plan.interval %>
+        </p>
+        <%% if plan.has_trial? %>
+          <p><%%= plan.trial_period_days %>-day free trial</p>
+        <%% end %>
+        <%%= button_to "Subscribe", billing.checkout_path(plan: plan.gateway_ref), method: :post %>
+      </article>
+    <%% end %>
+  </section>
+<%% end %>
+
+<%% if @lifetime_plans.any? %>
+  <section class="plans plans-lifetime">
+    <h2>Lifetime — buy once, own forever</h2>
+    <p class="plans-lifetime-disclaimer">
+      One payment, permanent access. No recurring billing.
+    </p>
+    <%% @lifetime_plans.each do |plan| %>
+      <article class="plan plan-lifetime">
+        <h3><%%= plan.name %></h3>
+        <p class="plan-price">
+          <%%= number_to_currency(plan.amount_cents / 100.0, unit: plan.currency.upcase + " ") %> ·
+          one-time
+        </p>
+        <%% remaining = plan.lifetime_inventory_remaining %>
+        <%% if remaining.nil? %>
+          <p class="plan-inventory">Unlimited</p>
+        <%% elsif remaining.zero? %>
+          <p class="plan-inventory plan-sold-out">Sold out</p>
+        <%% else %>
+          <p class="plan-inventory">Only <%%= remaining %> left at this price</p>
+        <%% end %>
+        <%% if plan.lifetime_sold_out? %>
+          <button disabled>Sold out</button>
+        <%% else %>
+          <%%= button_to "Buy lifetime", billing.lifetime_checkout_path(plan: plan.gateway_ref), method: :post %>
+        <%% end %>
+      </article>
+    <%% end %>
+  </section>
+<%% end %>

data/lib/generators/seams/billing/templates/app/views/subscriptions/index.html.erb.tt

@@ -0,0 +1,16 @@
+<%%# Lists the signed-in user's subscriptions. Override at %>
+<%%# app/views/billing/subscriptions/index.html.erb in your host. %>
+<h1>Your subscriptions</h1>
+
+<%% if @subscriptions.empty? %>
+  <p>You do not have any subscriptions yet. <%%= link_to "View plans", plans_path %>.</p>
+<%% else %>
+  <ul>
+    <%% @subscriptions.each do |subscription| %>
+      <li>
+        <%%= link_to subscription.plan_ref, subscription_path(subscription) %>
+        — <%%= subscription.status.titleize %>
+      </li>
+    <%% end %>
+  </ul>
+<%% end %>

data/lib/generators/seams/billing/templates/app/views/subscriptions/show.html.erb.tt

@@ -0,0 +1,25 @@
+<%%# Single subscription view with cancel / reactivate / change_plan %>
+<%%# controls. Override in your host to brand it. %>
+<h1>Subscription <%%= @subscription.gateway_ref %></h1>
+
+<dl>
+  <dt>Status</dt>       <dd><%%= @subscription.status.titleize %></dd>
+  <dt>Plan</dt>         <dd><%%= @subscription.plan_ref %></dd>
+  <dt>Customer</dt>     <dd><%%= @subscription.customer_ref %></dd>
+  <dt>Period ends</dt>  <dd><%%= @subscription.current_period_end %></dd>
+</dl>
+
+<%% if @subscription.active? %>
+  <%%= button_to "Cancel at period end", subscription_path(@subscription),
+                method: :delete,
+                data:   { confirm: "Cancel this subscription at the end of the billing period?" } %>
+
+  <h2>Change plan</h2>
+  <%%= form_with url: change_plan_subscription_path(@subscription), method: :post do |form| %>
+    <%%= form.label     :price_ref, "New plan id" %>
+    <%%= form.text_field :price_ref %>
+    <%%= form.submit "Change plan" %>
+  <%% end %>
+<%% else %>
+  <%%= button_to "Reactivate", reactivate_subscription_path(@subscription), method: :post %>
+<%% end %>

data/lib/generators/seams/billing/templates/config/routes.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+Billing::Engine.routes.draw do
+  resources :plans, only: %i[index]
+
+  # Self-service subscription management — Phase 3 (4/4). Backed by
+  # the Phase 3 (2/4) service objects; member actions map onto
+  # CancelService / ReactivateService / ChangePlanService.
+  resources :subscriptions, only: %i[index show] do
+    member do
+      delete :cancel
+      post   :reactivate
+      post   :change_plan
+    end
+  end
+
+  # Read-only billing history. Stripe hosts the PDF; the show view
+  # links to hosted_invoice_url if your host wires it up.
+  resources :invoices, only: %i[index show]
+
+  post "/checkout",          to: "checkout#create",   as: :checkout
+  get  "/checkout/success",  to: "checkout#success",  as: :checkout_success
+  # Lifetime Deal purchase — Stripe Checkout `mode: "payment"`.
+  # Namespaced under /checkout/ alongside the recurring-checkout flow
+  # so the surface stays grouped. See issue #2 section 3A.LTD.
+  post "/checkout/lifetime", to: "checkout#lifetime", as: :lifetime_checkout
+
+  post "/portal", to: "portal#create", as: :portal
+
+  # Admin-side LTD management. Mount behind your admin gate; see
+  # Billing::Admin::LifetimePassesController for the contract.
+  namespace :admin do
+    resources :lifetime_passes, only: %i[index new create destroy]
+  end
+
+  # Follow-up generators that add new gateway-flow routes (Adyen webhook, Paddle webhook, alternative checkout) splice their routes here, ahead of the existing Stripe webhook.
+  # seams:insertion-point billing.routes.before_webhook
+  post "/webhooks/stripe", to: "webhooks#stripe", as: :stripe_webhook
+end

data/lib/generators/seams/billing/templates/db/migrate/create_billing_invoices.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# What: creates the billing_invoices table.
+# Why:  per-invoice audit trail for support and finance — when a
+#       customer asks "did you charge me on the 3rd?" we don't have to
+#       round-trip the gateway every time. The invoice belongs to an
+#       Accounts::Account (the tenant the subscription was billed on),
+#       not to an individual Identity.
+# Risk: append-only writes from webhook handlers; no live-traffic SQL.
+class CreateBillingInvoices < ActiveRecord::Migration[7.1]
+  def change
+    create_table :billing_invoices do |t|
+      # Local tenant FK. UUID to match Accounts::Account#id; no DB-level
+      # FK across engines — see create_billing_subscriptions for why.
+      t.uuid       :account_id,       null: false
+      t.string     :gateway_ref,      null: false
+      t.string     :customer_ref,     null: false   # Stripe customer id (cus_*)
+      t.string     :subscription_ref                # Stripe subscription id (sub_*); nil for one-off invoices
+      t.integer    :amount_cents,     null: false
+      t.string     :currency,         null: false, default: "USD"
+      t.string     :status,           null: false, default: "open"
+      t.datetime   :paid_at
+      t.timestamps
+    end
+
+    add_index :billing_invoices, :account_id
+    add_index :billing_invoices, :gateway_ref,      unique: true
+    add_index :billing_invoices, :customer_ref
+    add_index :billing_invoices, :subscription_ref, where: "subscription_ref IS NOT NULL"
+    add_index :billing_invoices, %i[status created_at]
+  end
+end

data/lib/generators/seams/billing/templates/db/migrate/create_billing_lifetime_passes.rb.tt

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# What: creates billing_lifetime_passes — the one-time-paid OR privately
+#       granted permanent-access record. Lives in its own table because
+#       Subscription's renewal/period semantics don't apply.
+# Why:  Lifetime Deals (LTDs) are a real revenue + early-adopter feedback
+#       channel; the engine ships the mechanism so hosts can offer them
+#       without rolling their own model. See README LTD section for the
+#       trade-off (indefinite support, no recurring revenue). Bound to
+#       an Accounts::Account — the entitlement belongs to the tenant.
+#       `granted_by_identity_id` is the human (Auth::Identity) who
+#       pressed the "grant lifetime" button — Identity, not Account,
+#       because that column tracks human action rather than tenant data.
+# Risk: append-mostly (revoke is a soft delete via revoked_at, not a row
+#       delete, so audit history survives). Unique index on
+#       (account_id, plan_ref) prevents accidentally double-granting.
+class CreateBillingLifetimePasses < ActiveRecord::Migration[7.1]
+  def change
+    create_table :billing_lifetime_passes do |t|
+      # Local tenant FK. UUID to match Accounts::Account#id.
+      t.uuid     :account_id,          null: false
+      t.string   :customer_ref,        null: false   # gateway-side customer id (cus_*)
+      t.string   :plan_ref,            null: false   # billing_plans.gateway_ref
+      t.string   :gateway_ref                        # Stripe Checkout Session id; nil for private grants
+      # The Identity (auth_identities row) of the admin who granted
+      # the pass; nil for paid LTDs purchased through Stripe Checkout.
+      # bigint to match auth_identities' default integer PK.
+      t.bigint   :granted_by_identity_id
+      t.datetime :granted_at,          null: false
+      t.datetime :revoked_at                         # soft-revoke (refund / ToS violation)
+      t.bigint   :revoked_by_identity_id             # admin Identity who revoked
+      t.text     :notes
+      t.timestamps
+    end
+
+    add_index :billing_lifetime_passes, :account_id
+    add_index :billing_lifetime_passes, %i[account_id plan_ref], unique: true,
+                                                                 name: "index_billing_ltd_unique"
+    add_index :billing_lifetime_passes, :gateway_ref, unique: true,
+                                                      where: "gateway_ref IS NOT NULL"
+    add_index :billing_lifetime_passes, :revoked_at, where: "revoked_at IS NULL"
+  end
+end

data/lib/generators/seams/billing/templates/db/migrate/create_billing_plans.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# What: creates billing_plans, the local mirror of Stripe Prices.
+# Why:  the pricing page renders from this table without a per-request
+#       Stripe round-trip; webhooks keep it in sync if a plan changes
+#       upstream.
+# Risk: small table, append-mostly. Unique index on gateway_ref.
+class CreateBillingPlans < ActiveRecord::Migration[7.1]
+  def change
+    create_table :billing_plans do |t|
+      t.string  :gateway_ref,        null: false   # price_* from Stripe
+      t.string  :name,               null: false
+      t.text    :description
+      t.integer :amount_cents,       null: false, default: 0
+      t.string  :currency,           null: false, default: "usd"
+      t.string  :interval,           null: false, default: "month"
+      t.integer :trial_period_days
+      t.boolean :active,             null: false, default: true
+      t.jsonb   :features,           null: false, default: {}
+      # LTD inventory cap. nil = unlimited. Only meaningful when
+      # interval == "lifetime"; ignored otherwise. The pricing page +
+      # admin grant flow read Plan#lifetime_inventory_remaining to
+      # gate purchases / grants.
+      t.integer :max_lifetime_units
+      t.timestamps
+    end
+
+    add_index :billing_plans, :gateway_ref, unique: true
+    add_index :billing_plans, :active
+  end
+end

data/lib/generators/seams/billing/templates/db/migrate/create_billing_subscriptions.rb.tt

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# What: creates the billing_subscriptions table.
+# Why:  source of truth for "is this customer paying us right now?"
+#       Synced from gateway webhooks (status, current_period_end). Bound
+#       to an Accounts::Account (the tenant) — not to an Identity. The
+#       Stripe customer is the workspace, not the human; a single
+#       human (Identity) with memberships in two Accounts has two
+#       independent billing relationships.
+# Risk: empty on creation, append-mostly thereafter. Status updates
+#       happen in transactions of one row — no locking concerns.
+class CreateBillingSubscriptions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :billing_subscriptions do |t|
+      # Local tenant FK. UUID to match Accounts::Account#id; no DB-level
+      # foreign key because billing and accounts may live in different
+      # schemas / databases — cross-engine integrity is enforced at the
+      # application layer (the AccountScoped concern + service objects).
+      t.uuid     :account_id,          null: false
+      t.string   :customer_ref,        null: false   # Stripe customer id (cus_*) for the Account
+      t.string   :plan_ref,            null: false
+      t.string   :gateway_ref,         null: false
+      t.string   :status,              null: false, default: "incomplete"
+      t.datetime :current_period_end
+      t.timestamps
+    end
+
+    add_index :billing_subscriptions, :account_id
+    add_index :billing_subscriptions, :customer_ref
+    add_index :billing_subscriptions, :gateway_ref, unique: true
+    add_index :billing_subscriptions, :status
+  end
+end

data/lib/generators/seams/billing/templates/db/migrate/create_billing_webhook_events.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# What: creates billing_webhook_events for idempotent webhook handling.
+# Why:  Stripe explicitly recommends deduping by event id because they
+#       retry indefinitely until the endpoint returns 2xx
+#       (https://docs.stripe.com/webhooks#handle-duplicate-events).
+#       Without this table the welcome-email subscriber would re-send
+#       on every retry.
+# Risk: empty on creation, append-only thereafter. Unique index on
+#       gateway_event_id is the deduper.
+class CreateBillingWebhookEvents < ActiveRecord::Migration[7.1]
+  def change
+    create_table :billing_webhook_events do |t|
+      t.string   :gateway,            null: false   # "stripe" | "paddle" | ...
+      t.string   :gateway_event_id,   null: false   # provider's evt_* id
+      t.string   :event_type,         null: false
+      t.boolean  :livemode,           null: false, default: false
+      t.timestamps
+    end
+
+    add_index :billing_webhook_events, %i[gateway gateway_event_id], unique: true
+    add_index :billing_webhook_events, :event_type
+  end
+end

data/lib/generators/seams/billing/templates/lib/billing.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "billing/version"
+require "billing/configuration"
+require "billing/engine"
+require "billing/concerns/billable"
+require "billing/gateways/abstract"
+require "billing/gateways/stripe"
+# Follow-up generators that ship pre-wired gateway adapters (seams:billing:add_gateway paddle) splice their `require "billing/gateways/paddle"` line here.
+# seams:insertion-point billing.gateways.adapters
+
+module Billing
+  class Error           < StandardError; end
+  class GatewayError    < Error; end
+  class WebhookError    < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def gateway
+      configuration.gateway.constantize.new
+    rescue NameError => e
+      raise Billing::Error,
+            "Billing.configuration.gateway is set to #{configuration.gateway.inspect}, " \
+            "which could not be resolved: #{e.message}"
+    end
+  end
+end

data/lib/generators/seams/billing/templates/lib/concerns/billable.rb.tt

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Billing
+  # Mix into the host's Accounts::Account model — the tenant — to gain
+  # billing helpers. The Account is the Stripe customer; subscriptions,
+  # invoices, and lifetime passes all belong to the tenant, not to an
+  # individual human (Identity). A single Identity who is a member of
+  # two Accounts has TWO independent billing relationships.
+  #
+  # Wiring is config-driven (see Billing::Configuration#billable_class).
+  # The default `"Accounts::Account"` matches the canonical accounts
+  # engine; hosts on a different tenant model point the config at
+  # their own class.
+  #
+  # Hosts that want to wire it manually instead can do so:
+  #
+  #   class Accounts::Account < ApplicationRecord
+  #     include Billing::Billable
+  #   end
+  module Billable
+    extend ActiveSupport::Concern
+
+    included do
+      # Associations are bare `account_id` keyed — the cross-engine
+      # model-access cop forbids `belongs_to :account` from inside
+      # billing pointing at Accounts::Account, so we use foreign_key
+      # without a class_name on the back-edge: account.billing_*
+      # queries the billing tables by the account's id.
+      has_many :billing_subscriptions, class_name: "Billing::Subscription",
+                                       foreign_key: :account_id, primary_key: :id
+      has_many :billing_lifetime_passes, class_name: "Billing::LifetimePass",
+                                         foreign_key: :account_id, primary_key: :id
+      has_many :billing_invoices, class_name: "Billing::Invoice",
+                                  foreign_key: :account_id, primary_key: :id
+    end
+
+    # Enqueues a Stripe subscription. The `email:` arg is the contact
+    # address Stripe attaches to the customer record on first creation
+    # — typically the Account owner's Identity#email_address, but the
+    # host decides (it might be a billing-specific contact instead).
+    # Subsequent calls reuse the existing Stripe customer.
+    def start_subscription!(plan_ref:, email:)
+      Billing::StartSubscriptionJob.perform_later(
+        account_id:   id,
+        customer_ref: stripe_customer_ref!(email: email),
+        plan_ref:     plan_ref
+      )
+    end
+
+    def cancel_subscription!(subscription_ref:)
+      Billing::CancelSubscriptionJob.perform_later(subscription_ref: subscription_ref)
+    end
+
+    # Lifetime Deal helpers (issue #2 section 3A.LTD).
+    # `lifetime?` is true if this Account holds an active LifetimePass
+    # for ANY plan; `has_lifetime_for?(plan_ref:)` narrows to one.
+    def lifetime?
+      billing_lifetime_passes.where(revoked_at: nil).exists?
+    end
+
+    def has_lifetime_for?(plan_ref:)
+      billing_lifetime_passes.where(revoked_at: nil, plan_ref: plan_ref).exists?
+    end
+
+    # The "is this Account a paying / entitled customer right now?"
+    # check. True for active or trialing recurring subscriptions OR
+    # for any active lifetime pass. Use this in host code instead of
+    # querying subscriptions directly so LTD-only accounts are
+    # accounted for.
+    def has_active_billing?
+      billing_subscriptions.where(status: %w[active trialing]).exists? || lifetime?
+    end
+
+    # Lazily resolves (and caches) the Stripe customer id for this
+    # Account. First call creates a Stripe customer keyed on the
+    # Account#name + the supplied billing email; subsequent calls
+    # return the cached value.
+    #
+    # The `customer_ref` is stored on every billing_subscriptions /
+    # billing_invoices / billing_lifetime_passes row, so once an
+    # Account has any billing activity we can read the ref off any
+    # existing row and skip the Stripe API call.
+    def stripe_customer_ref!(email:)
+      existing = billing_subscriptions.first&.customer_ref ||
+                 billing_invoices.first&.customer_ref ||
+                 billing_lifetime_passes.first&.customer_ref
+      return existing if existing
+
+      result = Billing::Customers::FindOrCreateService.call(
+        email:    email,
+        metadata: { account_id: id, account_name: respond_to?(:name) ? name : nil }
+      )
+      raise Billing::Error, "Could not resolve Stripe customer: #{result.error}" unless result.ok?
+
+      result.value
+    end
+  end
+end

data/lib/generators/seams/billing/templates/lib/configuration.rb.tt

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Billing
+  # Engine-scoped configuration. Override in
+  # config/initializers/billing.rb of the host application:
+  #
+  #   Billing.configure do |c|
+  #     c.gateway        = "Billing::Gateways::Stripe"
+  #     c.api_key        = ENV.fetch("STRIPE_SECRET_KEY")
+  #     c.webhook_secret = ENV.fetch("STRIPE_WEBHOOK_SECRET")
+  #     # The host class that represents the billable tenant. The
+  #     # engine includes `Billing::Billable` into this class at boot
+  #     # so `account.start_subscription!(plan_ref:, email:)` etc are
+  #     # available wherever you handle Account rows. Default is the
+  #     # canonical `Accounts::Account` from the seams accounts engine;
+  #     # set to a different constant name if your tenant lives on a
+  #     # different model.
+  #     c.billable_class = "Accounts::Account"
+  #   end
+  class Configuration
+    attr_accessor :gateway, :api_key, :webhook_secret, :default_currency,
+                  :process_webhooks_async, :billable_class
+    # Follow-up generators that add knobs (proration mode, dunning retries, tax adapters) declare their attr_accessor here.
+    # seams:insertion-point billing.configuration.attributes
+
+    def initialize
+      @gateway                = "<%= gateway_class_name %>"
+      @api_key                = ENV.fetch("<%= gateway_env_prefix %>_SECRET_KEY",     nil)
+      @webhook_secret         = ENV.fetch("<%= gateway_env_prefix %>_WEBHOOK_SECRET", nil)
+      @default_currency       = "usd"
+      # Default to synchronous so failed handlers roll back the
+      # WebhookEvent insert and Stripe gets to retry. Hosts on Solid
+      # Queue (or similar) can flip to async + accept the trade-off.
+      @process_webhooks_async = false
+      # The Account-as-billable contract — see class comment.
+      @billable_class         = "Accounts::Account"
+      # Follow-up generators that add defaults for new attributes (matching billing.configuration.attributes) splice them here.
+      # seams:insertion-point billing.configuration.defaults
+    end
+
+    # Short identifier used as the `gateway:` field in canonical event
+    # payloads. Derived from `gateway` (e.g. "Billing::Gateways::Stripe"
+    # → "stripe"). Override directly if your class name doesn't follow
+    # the convention. NOT memoized — `gateway` is mutable, so
+    # gateway_name re-derives on every read.
+    def gateway_name
+      @gateway_name || gateway.to_s.split("::").last.to_s.downcase
+    end
+
+    attr_writer :gateway_name
+  end
+end

data/lib/generators/seams/billing/templates/lib/engine.rb.tt

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Billing
+  class Engine < ::Rails::Engine
+    isolate_namespace Billing
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer "billing.register_events" do
+      # Subscription lifecycle.
+      Seams::EventRegistry.register("subscription.created.billing",         emitted_by: "Billing")
+      Seams::EventRegistry.register("subscription.updated.billing",         emitted_by: "Billing")
+      Seams::EventRegistry.register("subscription.canceled.billing",        emitted_by: "Billing")
+      Seams::EventRegistry.register("subscription.trial_will_end.billing",  emitted_by: "Billing")
+      # Invoice lifecycle.
+      Seams::EventRegistry.register("invoice.created.billing",              emitted_by: "Billing")
+      Seams::EventRegistry.register("invoice.paid.billing",                 emitted_by: "Billing")
+      Seams::EventRegistry.register("invoice.failed.billing",               emitted_by: "Billing")
+      Seams::EventRegistry.register("invoice.finalized.billing",            emitted_by: "Billing")
+      Seams::EventRegistry.register("invoice.voided.billing",               emitted_by: "Billing")
+      # One-off payment + refund signals.
+      Seams::EventRegistry.register("payment.succeeded.billing",            emitted_by: "Billing")
+      Seams::EventRegistry.register("payment.failed.billing",               emitted_by: "Billing")
+      Seams::EventRegistry.register("charge.refunded.billing",              emitted_by: "Billing")
+      Seams::EventRegistry.register("checkout.session_completed.billing",   emitted_by: "Billing")
+      # Lifetime Deal events — see issue #2 section 3A.LTD.
+      Seams::EventRegistry.register("lifetime.granted.billing",             emitted_by: "Billing")
+      Seams::EventRegistry.register("lifetime.purchased.billing",           emitted_by: "Billing")
+      Seams::EventRegistry.register("lifetime.revoked.billing",             emitted_by: "Billing")
+      # Follow-up generators that ship new billing events (subscription.discount_applied.billing, dispute.created.billing) register them here.
+      # seams:insertion-point billing.engine.events
+    end
+
+    initializer "billing.append_migrations" do |app|
+      unless app.root == root
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+
+    # Follow-up generators that need their own initializer block (custom Billable include, gateway feature-flag wiring) declare it here.
+    # seams:insertion-point billing.engine.initializers
+
+    # Auto-include Billing::Billable into the configured tenant class
+    # (default: Accounts::Account). Wired via a to_prepare hook so the
+    # host's accounts engine has had a chance to autoload its model
+    # first; safe to re-run because Module#include is idempotent. The
+    # host can opt out by setting `billable_class = nil`.
+    config.to_prepare do
+      target = Billing.configuration.billable_class
+      next if target.nil? || (target.respond_to?(:empty?) && target.empty?)
+
+      begin
+        # Accept either a String ("Accounts::Account") or a Class
+        # (Accounts::Account). String is the documented shape — late
+        # constantize sidesteps autoload-order issues — but a host
+        # that hardwires the class object (e.g. via `c.billable_class
+        # = User`) shouldn't blow up at boot just because Class
+        # doesn't respond to `.constantize`.
+        klass = target.is_a?(String) ? target.constantize : target
+        klass.include(Billing::Billable)
+      rescue NameError
+        # Tenant class not yet loaded (e.g. accounts engine not
+        # installed). Hosts that wire Billable manually will still
+        # work; this is a best-effort auto-include.
+      end
+    end
+  end
+end