open-loam 0.1.0

data/app/models/loam/custom_field_value.rb

@@ -0,0 +1,18 @@
+module Loam
+  # A read-model projection of ONE custom field of ONE record into typed,
+  # INDEXED columns — so filtering/sorting/searching on a custom field is
+  # index-backed instead of a per-row JSON extraction over the `custom_fields`
+  # column (which can't be indexed and full-scans at scale). One row per
+  # (record, custom field); maintained by Loam::CustomFieldIndex from the
+  # Loam::CustomFields save/destroy hooks. Tenant-scoped.
+  #
+  # The value is written into the column matching the field's declared type
+  # (value_number / value_boolean / value_datetime) AND always into value_text
+  # (its string form) for text ops (contains/present) and canonical equality.
+  class CustomFieldValue < Loam::TenantRecord
+    self.table_name = "loam_custom_field_values"
+
+    validates :indexable_type, :indexable_id, :field_key, presence: true
+    validates :field_key, uniqueness: { scope: %i[indexable_type indexable_id] }
+  end
+end

data/app/models/loam/dashboard_widget.rb

@@ -0,0 +1,16 @@
+module Loam
+  # A tenant's dashboard layout: which registered widgets appear, in what order.
+  # A manager arranges these on the Dashboard settings screen; the dashboard
+  # renders the active ones by position (see Loam::Dashboard). Tenant-scoped and
+  # audited.
+  class DashboardWidget < Loam::TenantRecord
+    self.table_name = "loam_dashboard_widgets"
+
+    include Loam::Auditable
+
+    validates :widget_key, presence: true, uniqueness: { scope: :tenant_id }
+
+    scope :active, -> { where(active: true) }
+    scope :ordered, -> { order(:position, :id) }
+  end
+end

data/app/models/loam/dictionary.rb

@@ -0,0 +1,20 @@
+module Loam
+  # A per-tenant managed lookup list — a named set of entries (e.g.
+  # "damage_severity" → minor/major/critical). Admins curate the values without a
+  # code deploy, and a Loam::FieldDefinition of type "dictionary" can point a
+  # custom field at one. Tenant-scoped and audited like every Loam entity; see
+  # Loam::Dictionaries for the read API.
+  class Dictionary < Loam::TenantRecord
+    self.table_name = "loam_dictionaries"
+
+    include Loam::Auditable
+
+    has_many :entries, class_name: "Loam::DictionaryEntry",
+             foreign_key: :dictionary_id, dependent: :delete_all
+
+    validates :key, presence: true, uniqueness: { scope: :tenant_id }
+    validates :name, presence: true
+
+    normalizes :key, with: ->(key) { key.to_s.strip.presence }
+  end
+end

data/app/models/loam/dictionary_entry.rb

@@ -0,0 +1,31 @@
+module Loam
+  # One option in a Loam::Dictionary: a stored `value` (the code that lands in a
+  # record) plus display metadata (label, color, icon), an ordering `position`,
+  # a `is_default` flag, and an `active` switch (a retired option stops being
+  # offered without deleting the historical values already stored). Tenant-scoped
+  # and audited.
+  class DictionaryEntry < Loam::TenantRecord
+    self.table_name = "loam_dictionary_entries"
+
+    include Loam::Auditable
+
+    belongs_to :dictionary, class_name: "Loam::Dictionary"
+
+    validates :value, presence: true, uniqueness: { scope: :dictionary_id }
+    validates :label, presence: true
+
+    scope :active, -> { where(active: true) }
+    scope :ordered, -> { order(:position, :id) }
+
+    after_commit :clear_dictionary_cache
+    after_destroy_commit :clear_dictionary_cache
+
+    private
+
+    # A within-request edit must not read a stale cached list (the cache also
+    # resets per request, so this only matters when a write and a read share one).
+    def clear_dictionary_cache
+      Loam::Dictionaries.clear_cache
+    end
+  end
+end

data/app/models/loam/event_delivery.rb

@@ -0,0 +1,38 @@
+module Loam
+  # One durable delivery of one event to one persistent subscriber
+  # (see Loam::DurableEvents). The ROW is the durable record of intent: it is
+  # committed in the event's tenant at publish time, and the background job is
+  # only an accelerator. If the job is lost, the sweep re-enqueues from this row.
+  #
+  # Lifecycle: pending -> delivered (handler ran) | dead (handler removed, or
+  # MAX_ATTEMPTS exhausted). A pending row with next_attempt_at in the future is
+  # simply waiting out its backoff.
+  class EventDelivery < Loam::TenantRecord
+    self.table_name = "loam_event_deliveries"
+
+    STATUSES = %w[pending delivered dead].freeze
+
+    validates :subscriber_key, :event_name, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :pending,   -> { where(status: "pending") }
+    scope :delivered, -> { where(status: "delivered") }
+    scope :dead,      -> { where(status: "dead") }
+
+    # Rows ready for a (re)delivery attempt: pending and past their backoff gate.
+    scope :due, ->(now = Time.current) {
+      pending.where("next_attempt_at IS NULL OR next_attempt_at <= ?", now)
+    }
+
+    # The stored payload as a Hash regardless of adapter (Postgres jsonb returns
+    # a Hash; a text/json column may hand back a String).
+    def payload_hash
+      value = self[:payload]
+      return value if value.is_a?(Hash)
+
+      JSON.parse(value.to_s.presence || "{}")
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/app/models/loam/field_definition.rb

@@ -0,0 +1,48 @@
+module Loam
+  # Runtime declaration of a migration-free field on a tenant-scoped entity —
+  # "entity_type Equipment gets a field called serial_number of type string,
+  # writable by managers only." Tenant-scoped like everything else: a field
+  # defined in one tenant is invisible to another's records of the same
+  # entity_type, and definitions are the ONLY way values in an entity's
+  # `custom_fields` json column get read/written (see Loam::CustomFields).
+  class FieldDefinition < Loam::TenantRecord
+    self.table_name = "loam_field_definitions"
+
+    FIELD_TYPES = %w[string text integer decimal boolean date datetime dictionary].freeze
+
+    validates :entity_type, presence: true
+    validates :name, presence: true, uniqueness: { scope: %i[tenant_id entity_type] }
+    validates :field_type, presence: true, inclusion: { in: FIELD_TYPES }
+    validate :dictionary_key_resolves, if: -> { field_type == "dictionary" }
+
+    # Field-level READ gate for the runtime field, mirroring writable_roles: an
+    # empty readable_roles means any member may read it; otherwise only the listed
+    # roles. Used by Loam::CustomFieldIndex (so a filter can't be an oracle on a
+    # restricted field) and Loam::Policy#custom_field_readable?.
+    def readable_by?(role)
+      roles = readable_roles
+      roles.blank? || (role.present? && roles.map(&:to_sym).include?(role.to_sym))
+    end
+
+    # The `config` json holds type-specific settings. For a "dictionary" field it
+    # carries the key of the Loam::Dictionary whose entries populate the select.
+    def dictionary_key
+      config.is_a?(Hash) ? config["dictionary"] : nil
+    end
+
+    def dictionary_key=(value)
+      base = config.is_a?(Hash) ? config : {}
+      self.config = base.merge("dictionary" => value.to_s.strip.presence)
+    end
+
+    private
+
+    def dictionary_key_resolves
+      if dictionary_key.blank?
+        errors.add(:dictionary_key, "is required for a dictionary field")
+      elsif Loam::Dictionaries.get(dictionary_key).nil?
+        errors.add(:dictionary_key, "must name an existing dictionary in this tenant")
+      end
+    end
+  end
+end

data/app/models/loam/inbound_webhook_delivery.rb

@@ -0,0 +1,24 @@
+module Loam
+  # One received inbound webhook. Two jobs: an idempotency ledger (a unique
+  # (source_id, external_id) index turns a replayed delivery into a no-op) and an
+  # audit/payload store — the raw body is kept here so an event subscriber reads
+  # it, keeping the published event payload scalar-clean (ids only).
+  class InboundWebhookDelivery < Loam::TenantRecord
+    self.table_name = "loam_inbound_webhook_deliveries"
+
+    belongs_to :source, class_name: "Loam::InboundWebhookSource", inverse_of: :deliveries
+
+    validates :external_id, presence: true
+    # (source_id, external_id) uniqueness is enforced by a DB index — the ledger
+    # must be race-safe, so we rely on the constraint, not a validation.
+
+    def payload_hash
+      value = self[:payload]
+      return value if value.is_a?(Hash)
+
+      JSON.parse(value.to_s.presence || "{}")
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/app/models/loam/inbound_webhook_source.rb

@@ -0,0 +1,55 @@
+module Loam
+  # A registered external system allowed to POST webhooks INTO this tenant — the
+  # inbound sibling of Loam::WebhookEndpoint (which delivers events OUT). The
+  # `token` is the unguessable URL id (`/webhooks/:token`) that identifies the
+  # source; the `secret` is the HMAC key that AUTHENTICATES each call. Identity is
+  # not authority: rotating either is supported from the admin.
+  #
+  # On a verified delivery, Loam publishes `event_name` onto the domain event bus
+  # with a reference to the stored Loam::InboundWebhookDelivery, so durable
+  # subscribers (Loam::DurableEvents) react — the payload itself lives on the row.
+  class InboundWebhookSource < Loam::TenantRecord
+    self.table_name = "loam_inbound_webhook_sources"
+
+    DEFAULT_SIGNATURE_HEADER = "X-Loam-Signature".freeze
+    DEFAULT_TOLERANCE = 300 # seconds
+
+    has_many :deliveries, class_name: "Loam::InboundWebhookDelivery",
+                          foreign_key: :source_id, dependent: :destroy, inverse_of: :source
+
+    validates :name, presence: true
+    validates :token, presence: true, uniqueness: true
+    validates :secret, presence: true
+    validates :event_name, presence: true,
+              format: { with: Loam::Events::NAME_FORMAT, message: "must follow domain.thing.happened" }
+
+    scope :active, -> { where(active: true) }
+
+    before_validation on: :create do
+      self.token ||= SecureRandom.hex(24)
+      self.secret ||= SecureRandom.hex(32)
+      self.signature_header = DEFAULT_SIGNATURE_HEADER if signature_header.blank?
+      self.active = true if active.nil?
+    end
+
+    # THE blessed cross-tenant lookup (see Loam::ApiToken.authenticate): a public
+    # inbound request arrives with no tenant context — the token in the URL is how
+    # it discovers its tenant. Establishes Loam::Current.tenant (never an actor:
+    # the sender is a machine, not a user) and returns the ACTIVE source, or nil.
+    def self.resolve(raw_token)
+      return nil if raw_token.blank?
+
+      source = unscoped.find_by(token: raw_token)
+      return nil unless source&.active?
+
+      Loam::Current.tenant = source.tenant
+      source
+    end
+
+    def signature_header_key = signature_header.presence || DEFAULT_SIGNATURE_HEADER
+    def tolerance = (timestamp_tolerance.presence || DEFAULT_TOLERANCE).to_i
+
+    def rotate_token!  = update!(token: SecureRandom.hex(24))
+    def rotate_secret! = update!(secret: SecureRandom.hex(32))
+  end
+end

data/app/models/loam/membership.rb

@@ -0,0 +1,27 @@
+module Loam
+  # Connects an actor (the host app's User) to a tenant with a role. Roles are
+  # plain strings ("manager", "employee", ...) — policies interpret them.
+  # Tenant-scoped like everything else: asking for someone's role always means
+  # "their role in the CURRENT tenant".
+  class Membership < Loam::TenantRecord
+    self.table_name = "loam_memberships"
+
+    belongs_to :user
+
+    validates :role, presence: true
+    validates :user_id, uniqueness: { scope: :tenant_id }
+
+    # The other blessed cross-tenant lookup (see Loam::ApiToken.authenticate).
+    # "Which tenants may this person enter?" is asked at login, before any
+    # tenant is chosen, so it cannot be answered from inside one — which is why
+    # it lives in the gem rather than in host app code, where reaching across
+    # tenants is a guardrail failure.
+    #
+    # Returns a Loam::Tenant relation, so callers can order/filter it further.
+    def self.tenants_for(user)
+      user_id = user.respond_to?(:id) ? user.id : user
+
+      Loam::Tenant.where(id: unscoped.where(user_id: user_id).select(:tenant_id)).order(:name)
+    end
+  end
+end

data/app/models/loam/mfa_credential.rb

@@ -0,0 +1,114 @@
+require "bcrypt"
+
+module Loam
+  # A user's multi-factor credential: a TOTP secret plus single-use recovery
+  # codes. Deliberately NOT tenant-scoped — MFA belongs to the PERSON, who spans
+  # tenants, and the second-factor challenge runs at login BEFORE any tenant is
+  # chosen. So the secret is encrypted under a USER-scoped key (Loam::Encryptable
+  # `scope:`), which decrypts in any tenant and with no tenant at all — the whole
+  # reason a per-tenant key would be a lockout bug here.
+  class MfaCredential < ApplicationRecord
+    include Loam::GeneratedKey
+    self.table_name = "loam_mfa_credentials"
+
+    RECOVERY_CODE_COUNT = 10
+
+    belongs_to :user
+
+    include Loam::Encryptable
+    encrypts :totp_secret, scope: ->(credential) { "user/#{credential.user_id}" }
+
+    # Recovery codes are stored HASHED (BCrypt), never in the clear: [{ "digest",
+    # "used_at" }]. The plaintext is shown once, at generation, and then only the
+    # user has it.
+    serialize :recovery_codes, coder: JSON, type: Array
+
+    validates :user_id, uniqueness: true
+
+    # The active credential for a user, or nil — nil while enrollment is pending
+    # (a secret exists but was never confirmed) so an un-activated credential
+    # never gates login.
+    def self.active_for(user)
+      return nil unless user
+
+      credential = find_by(user_id: user.id)
+      credential&.activated? ? credential : nil
+    end
+
+    def activated?
+      activated_at.present?
+    end
+
+    # Confirm enrollment against a CANDIDATE secret (held in the session, never
+    # written until proven) with a live code, then activate: adopt the secret,
+    # mint recovery codes, and record the confirming step so it cannot be
+    # replayed at the next login. Returns the plaintext codes (shown ONCE) or nil
+    # if the code is wrong. The old secret stays valid until this succeeds, so a
+    # half-finished re-enrollment never downgrades an active credential.
+    def activate_with!(candidate_secret, code)
+      step = Loam::Totp.matching_step(candidate_secret, code)
+      return nil unless step
+
+      self.totp_secret = candidate_secret
+      self.activated_at = Time.current
+      self.last_totp_step = step
+      plaintext = mint_recovery_codes!
+      save!
+      plaintext
+    end
+
+    # Verify a TOTP code AND consume its timestep, so a captured code cannot be
+    # replayed within its ~90s validity window (at login or at sudo). The lock +
+    # last_totp_step check closes the read-modify-write race of two concurrent
+    # submits. On SQLite `FOR UPDATE` is dropped (writer serialization + the
+    # re-check still hold); Postgres takes a real row lock.
+    def verify_totp(code)
+      return false unless activated?
+
+      with_lock do
+        step = Loam::Totp.matching_step(totp_secret, code)
+        if step && (last_totp_step.nil? || step > last_totp_step)
+          update!(last_totp_step: step)
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # Consume a recovery code: valid exactly once. with_lock reloads and
+    # re-checks inside the transaction, so two concurrent submits of the same
+    # code cannot both succeed. Constant-time per candidate via BCrypt.
+    def consume_recovery_code(code)
+      code = code.to_s.strip.downcase
+      return false if code.empty?
+
+      with_lock do
+        entry = recovery_codes.find { |e| e["used_at"].nil? && BCrypt::Password.new(e["digest"]) == code }
+        if entry
+          entry["used_at"] = Time.current.iso8601
+          save!
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def unused_recovery_code_count
+      recovery_codes.count { |e| e["used_at"].nil? }
+    end
+
+    def provisioning_uri(issuer:)
+      Loam::Totp.provisioning_uri(totp_secret, account: user.email, issuer: issuer)
+    end
+
+    private
+
+    def mint_recovery_codes!
+      plaintext = Array.new(RECOVERY_CODE_COUNT) { SecureRandom.alphanumeric(10).downcase }
+      self.recovery_codes = plaintext.map { |code| { "digest" => BCrypt::Password.create(code), "used_at" => nil } }
+      plaintext
+    end
+  end
+end

data/app/models/loam/notification.rb

@@ -0,0 +1,36 @@
+module Loam
+  # One in-app message for one recipient (`user`) in one tenant. The same
+  # person in two tenants has two separate inboxes — like everything else in
+  # Loam, "your notifications" always means "in the current tenant".
+  #
+  # Plumbing, not business data: not audited, the same way Loam::AuditRecord
+  # isn't. It IS evented, though — creating one publishes "loam.notification.created"
+  # (carrying the recipient's user_id) so Loam::EventStream can push it to that
+  # user's browser and the bell updates live. Created through
+  # Loam::Notifications.notify, read through the admin bell.
+  class Notification < Loam::TenantRecord
+    self.table_name = "loam_notifications"
+
+    belongs_to :user
+
+    validates :title, presence: true
+
+    scope :unread, -> { where(read_at: nil) }
+
+    # The one signal the real-time bell listens for. Only id + recipient ride the
+    # event (Loam::Events also stamps tenant_id); no message content is broadcast.
+    after_create_commit do
+      Loam::Events.publish("loam.notification.created", id: id, user_id: user_id)
+    end
+
+    # What the notification is about, if anything (source_type/source_id) —
+    # stored rather than associated, so a notification survives its subject.
+
+    def read? = read_at.present?
+
+    def mark_read!
+      update!(read_at: Time.current) unless read?
+      self
+    end
+  end
+end

data/app/models/loam/pending_action.rb

@@ -0,0 +1,208 @@
+module Loam
+  # A staged mutation awaiting human approval. When a caller runs under
+  # confirm-mode (an MCP tool acting for an AI agent — see Loam.mutation_mode), a
+  # write is staged HERE as a preview instead of committing; a manager approves
+  # or rejects, and only approval executes it. This is Loam's thesis made
+  # concrete: agent-triggered writes are gate-able.
+  #
+  # The approval gate IS a workflow (Loam::Workflow): pending → (manager) approve
+  # / reject → executed / failed. "Who may approve" lives in one declarative,
+  # role-gated place. The proposed changes are encrypted at rest (Loam::Encryptable),
+  # because a staged change to an encrypted target field would otherwise sit here
+  # — and in this row's own audit — as plaintext, reopening the leak L-901 closed.
+  class PendingAction < Loam::TenantRecord
+    self.table_name = "loam_pending_actions"
+
+    include Loam::Auditable
+    include Loam::Encryptable
+    include Loam::Workflow
+
+    belongs_to :actor, class_name: "User", optional: true
+    belongs_to :reviewer, class_name: "User", foreign_key: :reviewed_by_id, optional: true
+
+    # Encrypted JSON. Encryptable also makes Auditable redact `changeset` to
+    # "[encrypted]" automatically, so the proposal never lands in the audit trail.
+    encrypts :changeset
+
+    validates :action_type, :summary, :idempotency_key, presence: true
+    # Only ONE pending row per proposal per tenant — a rejected/executed row with
+    # the same key may coexist so the proposal can be re-staged later. `conditions`
+    # scopes the existence check to pending rows (so a rejected row does not block
+    # a re-stage); `if: :pending?` skips the check on a non-pending row's own saves.
+    # Both mirror the partial DB index (WHERE status = 'pending').
+    validates :idempotency_key,
+              uniqueness: { scope: :tenant_id, conditions: -> { where(status: "pending") } },
+              if: :pending?
+
+    # The review queue: still awaiting a decision.
+    scope :pending, -> { where(status: "pending") }
+
+    # status is a workflow column, but a plain column underneath — guard it so a
+    # direct `update!(status: "executed")` cannot skip the manager role gate and
+    # execute_change!. Only a `to_*` transition (which sets the flag below) may
+    # move it. `update_column` / raw SQL remain the deliberate low-level escape
+    # hatch, like `.unscoped`.
+    validate :status_changes_only_through_a_transition, on: :update
+    # ...and a new row must START pending — otherwise create!(status: "executed")
+    # would forge an already-approved/executed record without any transition.
+    validate :status_starts_at_the_initial_state, on: :create
+
+    # Transitions are prefixed `to_` so their generated bang methods do not
+    # collide with the public approve!/reject!(by:) API below.
+    workflow :status, initial: "pending" do
+      state "pending"
+      state "approved"
+      state "rejected"
+      state "executed"
+      state "failed"
+
+      transition :to_approved, from: "pending",  to: "approved", roles: [ :manager ]
+      transition :to_rejected, from: "pending",  to: "rejected", roles: [ :manager ]
+      transition :to_executed, from: "approved", to: "executed"
+      transition :to_failed,   from: "approved", to: "failed"
+    end
+
+    # `changeset` is a Hash in Ruby but an encrypted JSON string at rest. The
+    # class methods win over Encryptable's included module and reach it via super.
+    def changeset
+      raw = super
+      raw.present? ? JSON.parse(raw) : {}
+    end
+
+    def changeset=(value)
+      super(value.nil? ? nil : value.to_json)
+    end
+
+    # A structured before/after diff. An encrypted target field shows
+    # "[encrypted]" on BOTH sides — a reviewer sees THAT a secret changes, never
+    # its value.
+    def preview
+      target = load_target
+      encrypted = encrypted_target_fields
+
+      changeset.each_with_object({}) do |(field, proposed), diff|
+        field = field.to_s
+        diff[field] =
+          if encrypted.include?(field)
+            { "from" => (target ? "[encrypted]" : nil), "to" => "[encrypted]" }
+          else
+            { "from" => target&.read_attribute(field), "to" => proposed }
+          end
+      end
+    end
+
+    # Approve and execute, atomically enough: the transition is role-gated to a
+    # manager; execution runs in a transaction so a failure leaves NO partial
+    # write; the record ends "executed" or "failed". Executes as `by`, so the
+    # TARGET's audit names the approving human — the person owns the change.
+    def approve!(by:)
+      Loam.as_tenant(tenant, actor: by) do
+        reject_self_approval!(by)
+        self.reviewed_by_id = by.id
+        self.reviewed_at = Time.current
+        to_approved!   # NotAuthorizedError if not a manager; InvalidTransitionError if not pending
+        execute_and_record!
+      end
+      self
+    end
+
+    def reject!(by:, reason: nil)
+      Loam.as_tenant(tenant, actor: by) do
+        self.reviewed_by_id = by.id
+        self.reviewed_at = Time.current
+        self.result = [ "rejected", reason.presence ].compact.join(": ")
+        to_rejected!
+      end
+      self
+    end
+
+    private
+
+    # Segregation of duties: the person who staged a change must not be the one
+    # who approves it — normally the proposer is an AI agent and the approver a
+    # human. Opt out per tenant with the "approvals.allow_self_approve" flag. A
+    # proposal with no recorded actor (actor_id nil) bypasses the check.
+    # (reject! is deliberately NOT gated: rejecting your own proposal is a
+    # withdrawal, not a segregation-of-duties concern.)
+    def reject_self_approval!(by)
+      return unless by.id == actor_id
+      return if Loam::Configs.get("approvals.allow_self_approve", default: false)
+
+      raise Loam::NotAuthorizedError, "self-approval is not permitted; a different person must approve this change"
+    end
+
+    # Execution AND its status/result recording share ONE transaction with the
+    # target write: if recording the outcome fails after the target committed,
+    # the whole thing rolls back rather than leaving the change applied but the
+    # status stuck at "approved".
+    def execute_and_record!
+      ActiveRecord::Base.transaction do
+        outcome = execute_change!
+        to_executed!
+        update!(result: outcome)
+      end
+    rescue StandardError => error
+      # The transaction rolled back, but Active Record leaves the in-memory
+      # attributes as they were mid-transaction — reload to the real DB state
+      # ("approved") before transitioning to "failed".
+      reload
+      to_failed!
+      update!(error: error.message)
+    end
+
+    def execute_change!
+      case action_type
+      when "create"
+        record = target_class.create!(changeset)
+        "created #{target_type}##{record.id}"
+      when "update"
+        target_class.find(target_id).update!(changeset)
+        "updated #{target_type}##{target_id}"
+      when "destroy"
+        target = target_class.find(target_id)
+        target.respond_to?(:soft_delete!) ? target.soft_delete! : target.destroy!
+        "deleted #{target_type}##{target_id}"
+      else
+        raise Loam::Error, "unknown action_type #{action_type.inspect}"
+      end
+    end
+
+    def target_class
+      target_type.constantize
+    end
+
+    def load_target
+      return nil if target_id.nil?
+
+      target_class.find_by(id: target_id)
+    end
+
+    def encrypted_target_fields
+      return [] unless target_class.respond_to?(:loam_encrypted_attributes)
+
+      target_class.loam_encrypted_attributes.map(&:to_s)
+    end
+
+    # Set while a workflow transition is performing its save, so the validation
+    # below can tell a legitimate status move from a direct assignment.
+    def loam_perform_transition!(transition)
+      @loam_status_via_transition = true
+      super
+    ensure
+      @loam_status_via_transition = false
+    end
+
+    def status_changes_only_through_a_transition
+      return unless will_save_change_to_status?
+      return if @loam_status_via_transition
+
+      errors.add(:status, "may only change through an approval transition (approve!/reject!), not a direct write")
+    end
+
+    def status_starts_at_the_initial_state
+      return if status == self.class.loam_workflow.initial
+
+      errors.add(:status, "must start at #{self.class.loam_workflow.initial.inspect} — a staged action begins pending")
+    end
+  end
+end