open-loam 0.1.0

data/lib/loam/lifecycle.rb

@@ -0,0 +1,180 @@
+module Loam
+  # Tenant lifecycle: what a brand-new tenant gets for free.
+  #
+  # An app declares seeding once, in config/initializers/loam.rb:
+  #
+  #   Loam.on_tenant_created do |tenant|
+  #     Loam::FieldDefinition.find_or_create_by!(entity_type: "Equipment", name: "asset_tag") { ... }
+  #   end
+  #
+  # The block runs inside `Loam.as_tenant(tenant)`, so tenant-scoped writes
+  # need no extra ceremony.
+  #
+  # THE CONTRACT: callbacks MUST be idempotent. They fire once when a tenant is
+  # created, and again for EVERY existing tenant whenever `bin/rails loam:sync`
+  # runs — which is how a role/field/default added by a later release reaches
+  # tenants that already exist. Write `find_or_create_by!`, never `create!`.
+  module Lifecycle
+    # Registered blocks, in declaration order. Registration returns the block
+    # itself so a caller (typically a test) can deregister it again.
+    def self.tenant_created_callbacks
+      @tenant_created_callbacks ||= []
+    end
+
+    def self.on_tenant_created(&block)
+      tenant_created_callbacks << block
+      block
+    end
+
+    # The single execution path for a tenant's callbacks — used both by
+    # Loam::Tenant's after_create_commit and by sync_tenants!, so "runs inside
+    # as_tenant, in declaration order" can never drift between the two.
+    #
+    # Exceptions propagate: a failing callback fails the tenant creation (Rails
+    # re-raises from after_commit) or the sync run, loudly, like every other
+    # Loam guardrail.
+    def self.run_tenant_created(tenant)
+      Loam.as_tenant(tenant) do
+        tenant_created_callbacks.each { |callback| callback.call(tenant) }
+      end
+    end
+
+    # Re-runs every on_tenant_created callback for every existing tenant.
+    # Idempotent by contract (see above) — safe to run on every deploy.
+    # Returns the number of tenants synced.
+    def self.sync_tenants!
+      count = 0
+      Loam::Tenant.find_each do |tenant|
+        run_tenant_created(tenant)
+        count += 1
+      end
+      count
+    end
+
+    # Role names this app expects every tenant to have — declared in the
+    # initializer (`Loam.default_roles = %w[manager employee]`) and read by
+    # whatever seeds memberships. A registry, not a mechanism: Loam does not
+    # create roles for you, because who gets which role is business logic.
+    def self.default_roles
+      @default_roles ||= []
+    end
+
+    def self.default_roles=(roles)
+      @default_roles = Array(roles).map(&:to_s)
+    end
+
+    # App-wide setting defaults: `{ "billing.currency" => "USD" }`, declared in
+    # the initializer and read by Loam::Configs as the baseline a key resolves
+    # to when no global row and no tenant override exist. A registry, like
+    # default_roles — declaring a default here needs no migration and no row.
+    def self.config_defaults
+      @config_defaults ||= {}
+    end
+
+    def self.config_defaults=(defaults)
+      @config_defaults = defaults.to_h.transform_keys(&:to_s)
+    end
+
+    # Event-name patterns (Loam::Events.pattern_matches?) whose events may be
+    # pushed to the browser over SSE (Loam::EventStream). DEFAULT OFF — an empty
+    # list means nothing reaches a browser; an app opts in explicitly, so a stray
+    # event never leaks by default.
+    def self.broadcast_events
+      @broadcast_events ||= []
+    end
+
+    def self.broadcast_events=(patterns)
+      @broadcast_events = Array(patterns).map(&:to_s)
+    end
+
+    # The locales content translations (Loam::Translatable) may be authored in —
+    # declared in the initializer (`Loam.locales = %w[en de pl]`), so the admin
+    # knows which languages to offer. A registry like the others; defaults to the
+    # single default locale.
+    def self.locales
+      @locales ||= [ default_locale ]
+    end
+
+    def self.locales=(codes)
+      @locales = Array(codes).map(&:to_s)
+    end
+
+    # Job classes an app EXPLICITLY allows the scheduler to run, beyond the ones
+    # it registers via Loam::Scheduler.register. An allowlist (not "any
+    # ActiveJob") so a tenant admin can't schedule ActiveStorage::PurgeJob or a
+    # mailer. Declared in the initializer: `Loam.schedulable_jobs = %w[DigestJob]`.
+    def self.schedulable_jobs
+      @schedulable_jobs ||= []
+    end
+
+    def self.schedulable_jobs=(names)
+      @schedulable_jobs = Array(names).map(&:to_s)
+    end
+
+    def self.default_locale
+      (defined?(I18n) ? I18n.default_locale : :en).to_s
+    end
+
+    # The current request/job locale — content reads overlay onto it. Request
+    # state like the tenant (set in a before_action, reset with Loam::Current).
+    def self.locale
+      (Loam::Current.locale || default_locale).to_s
+    end
+
+    def self.locale=(code)
+      Loam::Current.locale = code&.to_s
+    end
+
+    # Known feature flags: `{ "beta_dashboard" => { default: false, description:
+    # "..." } }`, declared in the initializer and read by Loam::Features. A
+    # registry like the others — a flag with no row resolves to its declared
+    # default, and the admin can list EVERY known flag, not just toggled ones.
+    def self.feature_defaults
+      @feature_defaults ||= {}
+    end
+
+    # Normalizes both levels: outer keys to strings, and each flag's own hash to
+    # symbol keys, so `{ "x" => { "default" => true } }` and
+    # `{ x: { default: true } }` behave identically.
+    def self.feature_defaults=(defaults)
+      @feature_defaults = defaults.to_h.each_with_object({}) do |(name, spec), out|
+        out[name.to_s] = spec.to_h.transform_keys(&:to_sym)
+      end
+    end
+  end
+
+  # The public surface is on Loam itself — apps and agents write
+  # `Loam.on_tenant_created`, never `Loam::Lifecycle.on_tenant_created`.
+  def self.on_tenant_created(&block) = Lifecycle.on_tenant_created(&block)
+  def self.tenant_created_callbacks = Lifecycle.tenant_created_callbacks
+  def self.sync_tenants! = Lifecycle.sync_tenants!
+  def self.default_roles = Lifecycle.default_roles
+  def self.default_roles=(roles)
+    Lifecycle.default_roles = roles
+  end
+  def self.config_defaults = Lifecycle.config_defaults
+  def self.config_defaults=(defaults)
+    Lifecycle.config_defaults = defaults
+  end
+  def self.feature_defaults = Lifecycle.feature_defaults
+  def self.feature_defaults=(defaults)
+    Lifecycle.feature_defaults = defaults
+  end
+  def self.broadcast_events = Lifecycle.broadcast_events
+  def self.broadcast_events=(patterns)
+    Lifecycle.broadcast_events = patterns
+  end
+  def self.locales = Lifecycle.locales
+  def self.locales=(codes)
+    Lifecycle.locales = codes
+  end
+  def self.schedulable_jobs = Lifecycle.schedulable_jobs
+  def self.schedulable_jobs=(names)
+    Lifecycle.schedulable_jobs = names
+  end
+  def self.default_locale = Lifecycle.default_locale
+  def self.locale = Lifecycle.locale
+  def self.locale=(code)
+    Lifecycle.locale = code
+  end
+end

data/lib/loam/locales/loam.en.yml

@@ -0,0 +1,80 @@
+# Loam's own UI strings (the framework chrome). Shipped inside lib/ so the gem
+# packages it, and added to the app's I18n load path by Loam::Engine. An app
+# localizes Loam by adding its own `config/locales/loam.<locale>.yml` overriding
+# these keys — distinct from Loam::Translatable, which localizes record DATA.
+# Entity and field names come from Rails' own activerecord.models /
+# activerecord.attributes (via model_name.human / human_attribute_name).
+en:
+  loam:
+    chrome:
+      tenant: "Tenant"
+      user: "User"
+      sign_out: "Sign out"
+      search: "Search"
+    nav:
+      dashboard: "Dashboard"
+      notifications: "Notifications"
+      api_tokens: "API tokens"
+      security: "Security"
+      approvals: "Approvals"
+      settings: "Settings"
+      features: "Features"
+      rules: "Rules"
+      sso: "SSO"
+      dictionaries: "Dictionaries"
+      tasks: "Tasks"
+      schedules: "Schedules"
+      deliveries: "Deliveries"
+      inbound: "Inbound"
+      api_docs: "API docs"
+      overrides: "Overrides"
+    actions:
+      new: "New %{name}"
+      new_title: "New %{name}"
+      edit_title: "Edit %{name} #%{id}"
+      show_title: "%{name} #%{id}"
+      deleted_title: "Deleted %{name}"
+      show: "Show"
+      edit: "Edit"
+      destroy: "Delete"
+      restore: "Restore"
+      back: "Back"
+      save: "Save"
+      translations: "Translations"
+      export_csv: "Export CSV"
+      import_csv: "Import CSV"
+      filter: "Filter"
+      deleted: "Deleted %{name}"
+    labels:
+      id: "ID"
+      actions: "Actions"
+      enrichments: "Enrichments"
+    bulk:
+      delete_selected: "Delete selected"
+      set_field: "Set field on selected"
+      export_selected: "Export selected"
+      apply: "Apply to selected"
+      confirm: "Apply to the selected rows?"
+      new_value: "new value (for Set field)"
+    views:
+      all: "All %{name} (no saved view)"
+      manage: "Manage views"
+      manage_saved: "Manage saved views"
+      save_current: "Save current view"
+      name_placeholder: "Name this view"
+      filter_placeholder: "Filter %{name}"
+    index:
+      incomplete: "Results may be incomplete — the custom-field index is rebuilding in the background."
+      empty: "No records yet."
+    pagination:
+      previous: "← Previous"
+      next: "Next →"
+      page: "Page %{page}"
+    flash:
+      created: "%{name} created."
+      updated: "%{name} updated."
+      destroyed: "%{name} deleted."
+      restored: "%{name} restored."
+    form:
+      read_only: "(read-only for your role)"
+      attach_files: "Attach files"

data/lib/loam/mcp/server.rb

@@ -0,0 +1,60 @@
+require "json"
+
+module Loam
+  module Mcp
+    # The stdio transport for the Loam MCP server (L-302): newline-delimited
+    # JSON-RPC over stdin/stdout, the MCP-spec stdio binding. Authenticates ONCE
+    # from LOAM_MCP_TOKEN (a Loam API token — never a tool argument, so it can't
+    # land in an agent transcript), then runs every message inside that token's
+    # tenant + actor. Nothing but JSON-RPC is written to stdout; logs go to stderr
+    # (wired in the rake task) — a stray stdout line corrupts the stream.
+    class Server
+      def initialize(input: $stdin, output: $stdout, token: ENV["LOAM_MCP_TOKEN"])
+        @input = input
+        @output = output
+        @token = token
+      end
+
+      def run
+        api_token = Loam::ApiToken.authenticate(@token)
+        return fail_auth unless api_token
+
+        tenant = api_token.tenant
+        actor = api_token.user
+
+        @input.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          request = parse(line)
+          next write(Loam::Mcp.err(nil, -32700, "parse error")) if request.nil?
+
+          begin
+            response = Loam.as_tenant(tenant, actor: actor) { Loam::Mcp.handle_jsonrpc(request) }
+            write(response) if response
+          ensure
+            Loam::Current.reset
+          end
+        end
+      end
+
+      private
+
+      def parse(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def write(message)
+        @output.puts(JSON.generate(message))
+        @output.flush
+      end
+
+      def fail_auth
+        write(Loam::Mcp.err(nil, -32001, "authentication failed: set LOAM_MCP_TOKEN to a valid Loam API token"))
+        exit(1)
+      end
+    end
+  end
+end

data/lib/loam/mcp.rb

@@ -0,0 +1,304 @@
+module Loam
+  # An MCP (Model Context Protocol) server surface exposing Loam to an AI agent —
+  # tools-only v1 (L-302). It lets an agent DISCOVER the domain (entities, schema,
+  # policy, workflow) and READ tenant-scoped records, and PROPOSE writes that are
+  # STAGED for human approval — never committed. Everything runs inside the
+  # tenant + actor of the API token the server authenticated with; whatever that
+  # user may do, no more. Approval authority stays with a human in the admin.
+  #
+  # Two layers: the tool methods (pure, assume Loam::Current is established) and
+  # `handle_jsonrpc` (a pure JSON-RPC dispatcher for initialize / tools/list /
+  # tools/call). The stdio transport (newline-delimited JSON-RPC) lives in
+  # Loam::Mcp::Server.
+  #
+  # SECURITY posture, reusing Loam's existing gates:
+  #   * entity names resolve against an allowlist (API-exposed TenantRecord
+  #     descendants), never a bare constantize;
+  #   * query filters/order are whitelisted to real columns (or a known custom
+  #     field, which carries the L-711 read-ACL); a filter on a field the role
+  #     can't read is refused (no inference oracle);
+  #   * query output emits only policy-readable fields per record (encrypted
+  #     values decrypted, blind-index columns dropped);
+  #   * a staged write accepts only policy-writable columns, refuses the workflow
+  #     column (that goes through a transition), and refuses id/tenant_id/
+  #     lock_version.
+  module Mcp
+    class ToolError < StandardError; end
+
+    PROTOCOL_VERSION = "2025-06-18".freeze
+    MAX_LIMIT = 100
+    FILTER_OPS = %w[eq neq contains gt gte lt lte present].freeze
+
+    TOOLS = [
+      {
+        name: "list_entities",
+        description: "List the business entities available in this Loam tenant.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false }
+      },
+      {
+        name: "describe_entity",
+        description: "Describe one entity: its columns and types, custom fields, workflow, and which fields the current role may read/write.",
+        inputSchema: {
+          type: "object",
+          properties: { entity: { type: "string", description: "Entity name, e.g. \"Equipment\"." } },
+          required: [ "entity" ], additionalProperties: false
+        }
+      },
+      {
+        name: "query_entity",
+        description: "Read tenant-scoped records of an entity. Returns only fields the current role may read. Filters and sort are whitelisted; limit is capped at 100.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string" },
+            filters: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  field: { type: "string" },
+                  op: { type: "string", enum: FILTER_OPS },
+                  value: {}
+                },
+                required: [ "field" ], additionalProperties: false
+              }
+            },
+            order: { type: "string", description: "A real column name to sort by." },
+            dir: { type: "string", enum: [ "asc", "desc" ] },
+            limit: { type: "integer", minimum: 1, maximum: MAX_LIMIT }
+          },
+          required: [ "entity" ], additionalProperties: false
+        }
+      },
+      {
+        name: "stage_write",
+        description: "PROPOSE an update to one record. It is staged as a Loam PendingAction for a human manager to approve — it does NOT take effect until approved. Only policy-writable columns are accepted; the workflow column is refused (use a transition).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            entity: { type: "string" },
+            id: { type: "integer" },
+            changes: { type: "object", description: "field => new value, real writable columns only." }
+          },
+          required: [ "entity", "id", "changes" ], additionalProperties: false
+        }
+      }
+    ].freeze
+
+    module_function
+
+    # --- entity allowlist ---
+
+    def entities
+      # Models are lazy-loaded (Zeitwerk), so `descendants` is only complete after
+      # an eager load — same as Loam::OpenApi's discovery.
+      Rails.application.eager_load! if defined?(Rails) && Rails.respond_to?(:application)
+      Loam::TenantRecord.descendants
+                        .reject { |model| model.name.blank? }
+                        .select { |model| api_exposed?(model) }
+                        .sort_by(&:name)
+    end
+
+    def api_exposed?(model)
+      "Api::#{model.model_name.plural.camelize}Controller".safe_constantize.present?
+    end
+
+    def resolve!(entity)
+      name = entity.to_s
+      entities.find { |m| m.name == name || m.model_name.plural == name } ||
+        raise(ToolError, "unknown entity #{entity.inspect}")
+    end
+
+    # --- tools ---
+
+    def list_entities
+      { entities: entities.map { |m| { name: m.name, plural: m.model_name.plural } } }
+    end
+
+    def describe_entity(entity:)
+      model = resolve!(entity)
+      policy = Loam::Policy.for(model.new)
+
+      columns = model.columns.reject { |c| c.name.end_with?("_hash") }.map do |col|
+        { name: col.name, type: col.sql_type_metadata.type.to_s,
+          readable: policy.readable?(col.name), writable: policy.writable?(col.name) }
+      end
+
+      custom = if model.respond_to?(:custom_field_definitions)
+        model.custom_field_definitions.map do |definition|
+          { name: definition.name, type: definition.field_type,
+            readable: policy.custom_field_readable?(definition.name),
+            writable: policy.custom_field_writable?(definition.name) }
+        end
+      else
+        []
+      end
+
+      workflow = if model.respond_to?(:loam_workflow) && model.loam_workflow
+        wf = model.loam_workflow
+        { column: wf.column, states: wf.states,
+          transitions: wf.transitions.values.map { |t| { name: t.name.to_s, from: t.from, to: t.to, roles: Array(t.roles).map(&:to_s) } } }
+      end
+
+      { name: model.name, columns: columns, custom_fields: custom, workflow: workflow }.compact
+    end
+
+    def query_entity(entity:, filters: [], order: nil, dir: "asc", limit: MAX_LIMIT)
+      model = resolve!(entity)
+      policy = Loam::Policy.for(model.new)
+      scope = apply_filters(model, model.all, filters, policy)
+      scope = apply_order(model, scope, order, dir)
+      capped = [ [ limit.to_i, 1 ].max, MAX_LIMIT ].min
+
+      records = scope.limit(capped).map { |record| serialize(record, policy) }
+      { entity: model.name, count: records.size, records: records }
+    end
+
+    def stage_write(entity:, id:, changes:)
+      model = resolve!(entity)
+      record = model.find(id) # tenant-scoped
+      policy = Loam::Policy.for(record)
+      workflow_column = model.respond_to?(:loam_workflow) ? model.loam_workflow&.column.to_s : nil
+
+      clean = {}
+      (changes || {}).each do |field, value|
+        field = field.to_s
+        raise ToolError, "#{field} cannot be set" if %w[id tenant_id lock_version].include?(field)
+        raise ToolError, "#{field} changes go through a workflow transition, not a direct write" if field == workflow_column
+
+        if model.column_names.include?(field)
+          raise ToolError, "#{field} is not writable for this role" unless policy.writable?(field)
+          clean[field] = value
+        elsif custom_field?(model, field)
+          raise ToolError, "custom-field writes over MCP are not supported in v1"
+        else
+          raise ToolError, "unknown field #{field.inspect}"
+        end
+      end
+      raise ToolError, "no writable changes" if clean.empty?
+
+      action = Loam::PendingActions.stage(
+        summary: "MCP proposal: update #{model.name}##{id}",
+        on: record, action: :update, changes: clean
+      )
+      { staged: true, pending_action_id: action.id, summary: action.summary, changes: clean,
+        note: "Staged for human approval — not applied until a manager approves it." }
+    end
+
+    # --- protocol ---
+
+    def call_tool(name, args)
+      kwargs = (args || {}).transform_keys(&:to_sym)
+      case name
+      when "list_entities"  then list_entities
+      when "describe_entity" then describe_entity(**kwargs.slice(:entity))
+      when "query_entity"   then query_entity(**kwargs.slice(:entity, :filters, :order, :dir, :limit))
+      when "stage_write"    then stage_write(**kwargs.slice(:entity, :id, :changes))
+      else raise ToolError, "unknown tool #{name.inspect}"
+      end
+    end
+
+    # Pure JSON-RPC dispatch. Returns a response Hash, or nil for a notification
+    # (no reply). Never raises for tool faults — those become an isError result.
+    def handle_jsonrpc(request)
+      id = request["id"]
+      case request["method"]
+      when "initialize"
+        ok(id, protocolVersion: request.dig("params", "protocolVersion") || PROTOCOL_VERSION,
+               capabilities: { tools: {} },
+               serverInfo: { name: "loam", version: Loam::VERSION })
+      when "tools/list"
+        ok(id, tools: TOOLS)
+      when "tools/call"
+        begin
+          data = call_tool(request.dig("params", "name"), request.dig("params", "arguments"))
+          ok(id, content: [ { type: "text", text: JSON.generate(data) } ])
+        rescue ToolError, Loam::Error, ActiveRecord::RecordNotFound => error
+          ok(id, isError: true, content: [ { type: "text", text: error.message } ])
+        end
+      when "notifications/initialized", "notifications/cancelled", nil
+        nil # notifications get no response
+      else
+        err(id, -32601, "method not found: #{request["method"]}")
+      end
+    end
+
+    # --- internals ---
+
+    def apply_filters(model, scope, filters, policy)
+      Array(filters).each do |raw|
+        field = raw["field"].to_s
+        op = (raw["op"] || "eq").to_s
+        raise ToolError, "unknown op #{op.inspect}" unless FILTER_OPS.include?(op)
+        value = raw["value"]
+
+        if model.column_names.include?(field)
+          raise ToolError, "#{field} is not readable for this role" unless policy.readable?(field)
+          scope = column_filter(model, scope, field, op, value)
+        elsif custom_field?(model, field)
+          # CustomFieldIndex.filter carries its own L-711 read-ACL for the current
+          # actor; surface its refusal as a clean tool error.
+          begin
+            scope = scope.merge(Loam::CustomFieldIndex.filter(model, field, op, value))
+          rescue Loam::FieldAccessError => error
+            raise ToolError, error.message
+          end
+        else
+          raise ToolError, "unknown field #{field.inspect}"
+        end
+      end
+      scope
+    end
+
+    def column_filter(model, scope, field, op, value)
+      column = model.connection.quote_column_name(field) # field is a real column name (whitelisted)
+      case op
+      when "eq"       then scope.where(field => value)
+      when "neq"      then scope.where.not(field => value)
+      when "contains" then scope.where("#{column} LIKE ?", "%#{value.to_s.gsub(/[\\%_]/) { |c| "\\#{c}" }}%")
+      when "present"  then scope.where.not(field => [ nil, "" ])
+      when "gt"       then scope.where("#{column} > ?", value)
+      when "gte"      then scope.where("#{column} >= ?", value)
+      when "lt"       then scope.where("#{column} < ?", value)
+      when "lte"      then scope.where("#{column} <= ?", value)
+      end
+    end
+
+    def apply_order(model, scope, order, dir)
+      return scope.order(id: :asc) if order.blank?
+      raise ToolError, "unknown sort column #{order.inspect}" unless model.column_names.include?(order.to_s)
+
+      direction = dir.to_s.casecmp("desc").zero? ? :desc : :asc
+      scope.reorder(order.to_s => direction)
+    end
+
+    def serialize(record, policy)
+      model = record.class
+      encrypted = model.respond_to?(:loam_encrypted_attributes) ? model.loam_encrypted_attributes.map(&:to_s) : []
+
+      json = {}
+      policy.readable_fields(model.column_names).each do |col|
+        next if col.end_with?("_hash")
+        json[col] = encrypted.include?(col) ? record.public_send(col) : record[col]
+      end
+      if model.respond_to?(:custom_field_definitions)
+        model.custom_field_definitions.each do |definition|
+          json["cf_#{definition.name}"] = record.custom_field(definition.name) if policy.custom_field_readable?(definition.name)
+        end
+      end
+      json
+    end
+
+    def custom_field?(model, field)
+      model.respond_to?(:custom_field_definitions) && model.custom_field_definitions.exists?(name: field)
+    end
+
+    def ok(id, **result)
+      { "jsonrpc" => "2.0", "id" => id, "result" => result }
+    end
+
+    def err(id, code, message)
+      { "jsonrpc" => "2.0", "id" => id, "error" => { "code" => code, "message" => message } }
+    end
+  end
+end

data/lib/loam/notifications.rb

@@ -0,0 +1,36 @@
+module Loam
+  # The one way to tell someone something inside the app.
+  #
+  #   Loam::Notifications.notify(user, title: "Order approved", source: order)
+  #   Loam::Notifications.notify_role(:manager, title: "New damage report")
+  #
+  # Records land in the CURRENT tenant (Loam::Notification is tenant-scoped),
+  # so a notification can never be delivered across a tenant boundary.
+  #
+  # The intended pattern is event -> notification: subscribe to a domain event
+  # in config/initializers/loam.rb and notify from there, instead of scattering
+  # delivery calls through models and controllers.
+  module Notifications
+    # Returns the created notifications. Accepts one user or many; `source` is
+    # any record the message is about, stored as type + id.
+    def self.notify(recipients, title:, body: nil, source: nil)
+      Array(recipients).map do |user|
+        Notification.create!(
+          user: user,
+          title: title,
+          body: body,
+          source_type: source&.class&.name,
+          source_id: source&.id
+        )
+      end
+    end
+
+    # Everyone holding `role` in the current tenant. Memberships are
+    # tenant-scoped, so this cannot reach into another tenant's staff.
+    def self.notify_role(role, title:, body: nil, source: nil)
+      recipients = Membership.where(role: role.to_s).includes(:user).map(&:user)
+
+      notify(recipients, title: title, body: body, source: source)
+    end
+  end
+end