defmodule AshPaperPlane do
  @moduledoc """
  Extension to AshPaperTrail that augments the version resource it generates. It
  does two independent things, and a resource asks for either or both.

  - It lifts named keys off the action's `source_context.shared` onto the
    version's metadata attribute, so a version records where a change came from
    rather than only what changed (`AshPaperPlane.SetVersionMetadata`).
  - It enqueues an Oban job when a version is created, riding the data layer's
    transaction where the data layer opens one on Oban's repo
    (`AshPaperPlane.EnqueueObanJob`).

  Both arrive through the `paper_trail` block's `mixin` option, and
  `AshPaperPlane.VersionMixin` documents the options that shape them:

      paper_trail do
        mixin {AshPaperPlane.VersionMixin, :extend,
               [[metadata: true, worker: MyApp.VersionCreatedWorker]]}
      end

  What goes into `shared`, and what the worker does when it runs, are the
  application's.
  """
end