open-loam 0.1.0

data/lib/loam/encryptable.rb

@@ -0,0 +1,145 @@
+module Loam
+  # Field-level encryption at rest, keyed per tenant. Declare it on a model:
+  #
+  #   class Patient < Loam::TenantRecord
+  #     include Loam::Encryptable
+  #     encrypts :ssn                      # encrypted at rest, not searchable
+  #     encrypts :email, searchable: true  # + a blind index for exact-match lookup
+  #   end
+  #
+  #   Patient.create!(ssn: "078-05-1120")   # the ssn COLUMN now holds "v1:...."
+  #   patient.ssn                           # => "078-05-1120" (decrypted on read)
+  #   Patient.find_by_email("a@b.com")      # exact match via the blind index
+  #
+  # The value is sealed with the CURRENT tenant's key (Loam.tenant!), never the
+  # record's stored tenant_id — so a read in the wrong tenant's context fails the
+  # GCM auth tag instead of quietly decrypting another tenant's data. Reading or
+  # writing an encrypted field with no tenant in context raises
+  # MissingTenantError: you cannot encrypt without knowing whose key.
+  #
+  # Encryption happens eagerly on assignment, so re-submitting a form with the
+  # same value re-seals it under a fresh IV and records a "[encrypted]" audit
+  # update with no real change — accepted prototype noise.
+  module Encryptable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :loam_encrypted_attributes, default: [].freeze, instance_writer: false
+      class_attribute :loam_searchable_encrypted_attributes, default: [].freeze, instance_writer: false
+    end
+
+    class_methods do
+      # `scope:` chooses whose key seals the field. `:tenant` (default) keys off
+      # Loam.tenant! — right for entity data. A Proc `->(record) { "user/#{...}" }`
+      # keys off something else, for genuinely non-tenant data (an MFA secret
+      # belongs to the person and must decrypt in any tenant, and at login before
+      # a tenant is chosen). Non-tenant scopes cannot be `searchable`.
+      def encrypts(name, searchable: false, scope: :tenant)
+        name = name.to_s
+
+        if searchable && scope != :tenant
+          raise Loam::Error, "#{self.name}: `#{name}` cannot be both `searchable` and non-tenant-scoped."
+        end
+
+        # Encrypted ciphertext is meaningless to a LIKE scan, so the two are a
+        # contradiction. Caught whichever declaration comes second (Searchable
+        # runs the mirror check), so order in the model does not matter.
+        if respond_to?(:loam_searchable_columns) && loam_searchable_columns.include?(name)
+          raise Loam::Error,
+                "#{self.name}: `#{name}` is declared both `searchable_by` (LIKE) and `encrypts` — " \
+                "ciphertext cannot be LIKE-searched. Drop it from `searchable_by` and use " \
+                "`encrypts :#{name}, searchable: true` for exact-match lookup instead."
+        end
+
+        # A translation row would store the field's PLAINTEXT — recreating the
+        # leak encryption closes. Caught whichever declaration comes second
+        # (Translatable runs the mirror check), so model order does not matter.
+        if respond_to?(:loam_translatable_attributes) && loam_translatable_attributes.include?(name)
+          raise Loam::Error,
+                "#{self.name}: `#{name}` is declared both `translates` and `encrypts` — a translation " \
+                "would store plaintext. Encrypted data is not translatable."
+        end
+
+        self.loam_encrypted_attributes = (loam_encrypted_attributes + [name]).freeze
+        self.loam_searchable_encrypted_attributes = (loam_searchable_encrypted_attributes + [name]).freeze if searchable
+
+        include loam_encryption_reader_writer(name, searchable, scope)
+        define_loam_blind_index_finder(name) if searchable
+      end
+
+      # Reader/writer live in their own module (the Loam::Workflow precedent) so
+      # an app can override and still call `super`, and so they sit ABOVE Active
+      # Record's generated attribute methods in the ancestor chain and win.
+      def loam_encryption_reader_writer(name, searchable, scope)
+        hash_column = "#{name}_hash"
+
+        Module.new do
+          define_method(name) do
+            resolved = loam_encryption_scope(scope)
+            aad = Loam::Encryption.aad(resolved, self.class.table_name, name)
+            Loam::Encryption.decrypt_scoped(read_attribute(name), resolved, aad: aad)
+          end
+
+          define_method("#{name}=") do |value|
+            resolved = loam_encryption_scope(scope)
+            # Bind this ciphertext to its (scope, table, column) so it can't be
+            # transplanted to another column/table/tenant (v2 AAD).
+            aad = Loam::Encryption.aad(resolved, self.class.table_name, name)
+            write_attribute(name, Loam::Encryption.encrypt_scoped(value, resolved, aad: aad))
+            # The blind index tracks the ciphertext column: rewrite it in the
+            # same breath, so an exact-match lookup can never go stale.
+            write_attribute(hash_column, Loam::Encryption.blind_index_scoped(value, resolved)) if searchable
+          end
+        end
+      end
+
+      # `find_by_<name>` / `where_<name>` match the per-tenant blind index. They
+      # deliberately shadow Active Record's dynamic `find_by_<attr>`: the obvious
+      # call must hash-and-compare, never match a plaintext query against the
+      # ciphertext column (which would silently find nothing).
+      def define_loam_blind_index_finder(name)
+        hash_column = "#{name}_hash"
+
+        define_singleton_method("where_#{name}") do |value|
+          where(hash_column => Loam::Encryption.blind_index(value, Loam.tenant!.id))
+        end
+
+        define_singleton_method("find_by_#{name}") do |value|
+          public_send("where_#{name}", value).first
+        end
+      end
+    end
+
+    private
+
+    # Resolve a declared `scope:` to the namespaced owner string the key is
+    # derived from. `:tenant` keys off the current tenant (raises with none, the
+    # same safety property as an entity write); a Proc computes it from the
+    # record. A blank or `.../`-terminated result (e.g. a nil user_id) raises
+    # rather than deriving a degenerate shared key.
+    def loam_encryption_scope(scope)
+      resolved = scope == :tenant ? "tenant/#{Loam.tenant!.id}" : scope.call(self).to_s
+
+      if resolved.strip.empty? || resolved.end_with?("/")
+        raise Loam::Encryption::Error, "#{self.class}: cannot derive an encryption key from a blank scope (#{resolved.inspect})"
+      end
+      resolved
+    end
+
+    public
+
+    # Re-seal every encrypted field under the current key, with fresh IVs — the
+    # per-record step of a key rotation (read old, write new). With HKDF-from-
+    # master, a real rotation means a new master or a bumped Cipher::VERSION; the
+    # version tag lets old and new ciphertext coexist while this runs across a
+    # tenant's records, so rotation is a lazy re-encrypt, not a stop-the-world
+    # migration. Writes an ordinary audited "[encrypted]" update — see
+    # lib/tasks/loam.rake (loam:encryption:rotate).
+    def loam_reencrypt!
+      self.class.loam_encrypted_attributes.each do |name|
+        public_send("#{name}=", public_send(name))
+      end
+      save!
+    end
+  end
+end

data/lib/loam/encryption/cipher.rb

@@ -0,0 +1,75 @@
+module Loam
+  module Encryption
+    # AES-256-GCM sealing. GCM is *authenticated* encryption: the 16-byte auth
+    # tag turns tampering — or decrypting with the wrong key — into a loud
+    # failure on open, never silent garbage.
+    #
+    # Stored format, one string column:
+    #
+    #   "v1:" + base64( iv[12] ++ auth_tag[16] ++ ciphertext )              (no AAD)
+    #   "v2:" + base64( iv[12] ++ auth_tag[16] ++ ciphertext )   sealed WITH AAD
+    #
+    # The version tag lets the scheme evolve without a stop-the-world migration:
+    # v2 binds Additional Authenticated Data (the field's tenant+table+column) into
+    # the auth tag, so a ciphertext moved to a DIFFERENT column/table/tenant fails
+    # the tag on read — it can't be transplanted. Old "v1:" rows (no AAD) keep
+    # decrypting, so upgrading is a lazy re-encrypt (loam:encryption:rotate writes
+    # v2), never a data migration. The AAD is authenticated but NOT secret — it
+    # never conceals anything, it only pins WHERE the ciphertext is allowed to live.
+    module Cipher
+      VERSION = "v1".freeze  # legacy, no AAD — still readable
+      V2      = "v2".freeze  # current writes — AAD-bound
+      IV_BYTES  = 12   # GCM's standard nonce size
+      TAG_BYTES = 16   # full-length GCM tag; a shorter tag weakens authentication
+
+      # Encrypt with a fresh random IV. Reusing an IV under one key is
+      # catastrophic for GCM, so the IV is never derived or fixed — always
+      # OpenSSL's CSPRNG, once per value. With an `aad:` the ciphertext is bound
+      # to that context (v2); without one it stays v1 (a bare tenant-scoped blob).
+      def self.seal(plaintext, key, aad: nil)
+        cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
+        cipher.key = key
+        iv = cipher.random_iv
+        version = aad ? V2 : VERSION
+        cipher.auth_data = aad if aad # folded into the tag, not encrypted
+        ciphertext = cipher.update(plaintext) + cipher.final
+        tag = cipher.auth_tag(TAG_BYTES)
+        "#{version}:" + [iv + tag + ciphertext].pack("m0")
+      end
+
+      # Decrypt, or raise Loam::Encryption::DecryptionError. The wrong tenant's
+      # key, a tampered blob, a truncated tag, a v2 blob read with the WRONG (or
+      # missing) AAD, or plain garbage all fail the same loud way — never a
+      # partial or silently-wrong plaintext. A v1 blob carries no AAD, so the
+      # passed `aad:` is ignored for it (backward compatible).
+      def self.open(payload, key, aad: nil)
+        version, blob = payload.to_s.split(":", 2)
+        raise DecryptionError, "unrecognized ciphertext format" unless [ VERSION, V2 ].include?(version) && blob
+
+        raw = blob.unpack1("m0")
+        # Enforce the full IV+tag length BEFORE slicing: OpenSSL will verify a
+        # truncated tag against a truncated blob, so a short payload must be
+        # rejected here, not handed to the cipher.
+        raise DecryptionError, "ciphertext too short" if raw.nil? || raw.bytesize < IV_BYTES + TAG_BYTES
+
+        iv         = raw.byteslice(0, IV_BYTES)
+        tag        = raw.byteslice(IV_BYTES, TAG_BYTES)
+        ciphertext = raw.byteslice(IV_BYTES + TAG_BYTES..) || ""
+
+        cipher = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+        cipher.key = key
+        cipher.iv = iv
+        cipher.auth_tag = tag
+        cipher.auth_data = aad if version == V2 && aad # v2 rows require the matching AAD
+        plaintext = cipher.update(ciphertext) + cipher.final
+        # Decryption yields ASCII-8BIT bytes; our columns hold UTF-8 text.
+        plaintext.force_encoding(Encoding::UTF_8)
+      rescue OpenSSL::Cipher::CipherError, ArgumentError, TypeError
+        # $! is preserved as the DecryptionError's `cause`. The message stays
+        # deliberately vague — it must not distinguish "wrong key" from
+        # "corrupt data" to a caller.
+        raise DecryptionError, "could not decrypt (wrong key or corrupt data)"
+      end
+    end
+  end
+end

data/lib/loam/encryption/key_provider.rb

@@ -0,0 +1,43 @@
+module Loam
+  module Encryption
+    # The seam a real KMS plugs into. A provider turns (scope, purpose) into a
+    # 32-byte data key; swap the default for a Vault/AWS-KMS-backed provider via
+    # `Loam::Encryption.key_provider = MyKmsProvider.new` and NO call site
+    # changes — Cipher and Encryptable only ever ask for a key.
+    #
+    # `scope` is a namespaced owner string: "tenant/5" for an entity field,
+    # "user/12" for genuinely user-owned data (an MFA secret) that must decrypt
+    # regardless of which tenant the user is currently acting in.
+    class KeyProvider
+      def data_key(scope:, purpose:)
+        raise NotImplementedError, "#{self.class} must implement #data_key(scope:, purpose:)"
+      end
+    end
+
+    # Default provider: derive a per-scope, per-purpose key from one master key
+    # with HKDF-SHA256. Deterministic, so no key needs to be stored, and one
+    # scope's key can NEVER equal another's because the scope is bound into the
+    # HKDF `info`. Purpose separation means the encryption key and the
+    # blind-index (HMAC) key derived for one scope are independent.
+    class HkdfKeyProvider < KeyProvider
+      # A fixed, non-secret salt. HKDF's strength comes from the master key's
+      # entropy; the salt only has to be stable so derivation is reproducible.
+      SALT = "loam.encryption.hkdf.v1".freeze
+      KEY_BYTES = 32   # AES-256 and HMAC-SHA256 both take a 32-byte key
+
+      def data_key(scope:, purpose:)
+        raise ArgumentError, "scope is required to derive a key" if scope.nil? || scope.to_s.empty?
+
+        OpenSSL::KDF.hkdf(
+          Loam::Encryption.master_key,
+          salt: SALT,
+          # info binds the key to owner AND purpose. "tenant/5" here reproduces
+          # the pre-scope format exactly, so existing ciphertext still decrypts.
+          info: "loam/#{purpose}/#{scope}",
+          length: KEY_BYTES,
+          hash: "SHA256"
+        )
+      end
+    end
+  end
+end

data/lib/loam/encryption.rb

@@ -0,0 +1,125 @@
+require "openssl"
+require "loam/encryption/key_provider"
+require "loam/encryption/cipher"
+
+module Loam
+  # Field-level encryption at rest, keyed per tenant.
+  #
+  # The facade the rest of Loam calls: `encrypt`/`decrypt` seal and open a value
+  # with the tenant's derived AES-256-GCM key, and `blind_index` computes the
+  # per-tenant HMAC used to find an encrypted field by exact value. Key
+  # derivation is delegated to a pluggable `key_provider` (HKDF by default, a
+  # KMS in production), so this module holds the scheme, not the key material.
+  module Encryption
+    class Error < Loam::Error; end
+
+    # Raised when a crypto operation is attempted with no master key configured.
+    class MissingMasterKeyError < Error
+      def initialize(msg = "Loam::Encryption has no master key. Set LOAM_MASTER_KEY (or " \
+                           "`Loam::Encryption.master_key = ...`) to a high-entropy secret, e.g. " \
+                           "`SecureRandom.hex(32)`. NEVER commit it; use ENV or Rails credentials.")
+        super
+      end
+    end
+
+    # Raised by decrypt on the wrong key, tampering, truncation, or garbage —
+    # one loud, undifferentiated failure.
+    class DecryptionError < Error; end
+
+    # HKDF extracts entropy from whatever it is given, but a short master key is
+    # a short master key — refuse anything below 256 bits of material.
+    MASTER_KEY_MIN_BYTES = 32
+
+    class << self
+      attr_writer :key_provider
+
+      def key_provider
+        @key_provider ||= HkdfKeyProvider.new
+      end
+
+      def master_key=(value)
+        @master_key = value
+      end
+
+      def master_key
+        key = @master_key || ENV["LOAM_MASTER_KEY"]
+        raise MissingMasterKeyError if key.nil? || key.empty?
+        if key.bytesize < MASTER_KEY_MIN_BYTES
+          raise MissingMasterKeyError,
+                "LOAM_MASTER_KEY is too short (#{key.bytesize} bytes); use at least " \
+                "#{MASTER_KEY_MIN_BYTES}, e.g. `SecureRandom.hex(32)`."
+        end
+        key
+      end
+
+      # Tenant-scoped operations — the default for entity fields via
+      # Loam::Encryptable. nil stays nil (an unset field is not "the empty
+      # string encrypted"); any other value is stringified and sealed.
+      def encrypt(plaintext, tenant_id)
+        encrypt_scoped(plaintext, tenant_scope(tenant_id))
+      end
+
+      def decrypt(payload, tenant_id)
+        decrypt_scoped(payload, tenant_scope(tenant_id))
+      end
+
+      # A deterministic, per-tenant keyed hash for exact-match lookup of an
+      # encrypted field. It leaks equality WITHIN a tenant (same value → same
+      # hash) — the accepted trade-off for searchability — but the per-tenant
+      # HMAC key means the same value hashes differently across tenants, so
+      # equality never leaks between them. Only searchable fields get one.
+      def blind_index(value, tenant_id)
+        blind_index_scoped(value, tenant_scope(tenant_id))
+      end
+
+      # Explicit-scope variants, for data owned by something OTHER than a tenant
+      # — an MFA secret, say, keyed "user/42" so it decrypts in whatever tenant
+      # the user is currently in, or at login when no tenant is chosen yet.
+      def encrypt_scoped(plaintext, scope, aad: nil)
+        return nil if plaintext.nil?
+        Cipher.seal(plaintext.to_s, data_key(scope, :encryption), aad: aad)
+      end
+
+      def decrypt_scoped(payload, scope, aad: nil)
+        return nil if payload.nil?
+        Cipher.open(payload, data_key(scope, :encryption), aad: aad)
+      end
+
+      # The Additional Authenticated Data that BINDS a ciphertext to where it
+      # lives — the key scope (tenant/owner) + table + column. Reconstructed
+      # identically on read and write, so a blob moved to a different column,
+      # table, or tenant fails the auth tag. NOT the record id (see
+      # Loam::Encryptable): the id is unknown at INSERT time, and binding it would
+      # force an ugly post-insert double-write; record-swap within one
+      # tenant+table+column stays a documented residual.
+      def aad(scope, table, column)
+        "loam-aad:v2:#{scope}:#{table}:#{column}"
+      end
+
+      def blind_index_scoped(value, scope)
+        return nil if value.nil?
+        OpenSSL::HMAC.hexdigest("SHA256", data_key(scope, :blind_index), value.to_s)
+      end
+
+      private
+
+      # "tenant/5" reproduces the pre-scope HKDF info exactly (see HkdfKeyProvider).
+      def tenant_scope(tenant_id)
+        "tenant/#{tenant_id}"
+      end
+
+      # Central guard for every crypto path (tenant and explicit scope alike): a
+      # nil tenant makes the scope "tenant/", a nil owner id makes "user/" — a
+      # degenerate scope that would otherwise derive a real, SHARED key. Refuse
+      # it here so `encrypt(x, nil)` fails like the Encryptable-layer guard does,
+      # rather than silently keying unrelated records together.
+      def data_key(scope, purpose)
+        if scope.nil? || scope.to_s.strip.empty? || scope.to_s.end_with?("/")
+          raise ArgumentError, "refusing to derive an encryption key from a degenerate scope #{scope.inspect}"
+        end
+
+        key_provider.data_key(scope: scope, purpose: purpose)
+      end
+    end
+  end
+end

data/lib/loam/engine.rb

@@ -0,0 +1,57 @@
+module Loam
+  class Engine < ::Rails::Engine
+    # Not isolated on purpose: Loam models live under the Loam:: namespace but
+    # share the host app's routes/helpers, keeping the prototype surface small.
+
+    # Webhook dispatch listens to every Loam event. Wired after initialization
+    # so the models it queries are loadable, and guarded against subscribing
+    # twice (see Loam::Webhooks.subscribe!).
+    config.after_initialize do
+      Loam::Webhooks.subscribe!
+      Loam::DurableEvents.subscribe!    # persist + retry durable subscribers (L-706)
+      Loam::BusinessRules.subscribe!
+      Loam::Widgets.register_builtins!  # the default dashboard widgets
+      Loam::Overrides.check!            # warn about any stale disable/replace overrides
+
+      # The durability sweep runs per-tenant on a schedule (materialized into
+      # each tenant by Loam::Scheduler.sync_tenant). interval:300 = every 5 min.
+      Loam::Scheduler.register(
+        key: Loam::DurableEvents::SWEEP_KEY, name: "Event redelivery sweep",
+        job_class: "Loam::EventRedeliverySweepJob", schedule: "interval:300", scope: "tenant"
+      )
+    end
+
+    # Loam's Active Record layer — TenantRecord, Auditable, Eventful and the
+    # rest — is defined inside ActiveSupport.on_load(:active_record) in
+    # lib/loam.rb, so those constants exist only once something has referenced
+    # ActiveRecord::Base.
+    #
+    # Zeitwerk eager-loads app/models alphabetically. A host model that inherits
+    # from Loam::TenantRecord and sorts ahead of application_record.rb reaches
+    # the constant before anything has touched Base, and eager load dies with
+    # "uninitialized constant Loam::TenantRecord". Whether an app hits it
+    # depends on its model names, so it shows up on a rename rather than on the
+    # change that caused it.
+    #
+    # Referencing Base here fires the hook while load order is still the
+    # engine's to decide instead of each host app's. :eager_load! is late enough
+    # that every active_record.* initializer has applied its configuration, and
+    # it runs in every environment (in development it is a no-op that still
+    # executes), so lazily-loaded apps are settled by the same line.
+    initializer "loam.active_record_layer", before: :eager_load! do
+      ActiveRecord::Base
+    end
+
+    # Loam's own UI strings ship under lib/ (the gemspec packages lib/**/*), so
+    # register them on the app's I18n load path explicitly rather than relying on
+    # the default config/locales path (which the gem does not ship). An app
+    # overrides any key with its own config/locales/loam.<locale>.yml.
+    initializer "loam.i18n" do |app|
+      app.config.i18n.load_path += Dir[File.expand_path("locales/*.yml", __dir__)]
+    end
+
+    # lib/tasks/loam.rake (bin/rails loam:sync) is picked up by Rails::Engine's
+    # own lib/tasks loading. Loading it again from a `rake_tasks` block here
+    # would define the task twice and run its body twice.
+  end
+end

data/lib/loam/enrichers.rb

@@ -0,0 +1,105 @@
+module Loam
+  # Response enrichers: one module attaches a computed block onto ANOTHER
+  # module's entity in admin/API responses, with no foreign-key coupling.
+  #
+  #   # billing knows about equipment; equipment knows nothing about billing:
+  #   Loam::Enrichers.register("Equipment", key: "outstanding_balance") do |equipment|
+  #     Invoice.where(equipment_id: equipment.id).sum(:balance)
+  #   end
+  #
+  #   Loam::Enrichers.enrich(equipment)        # => { "outstanding_balance" => 1200 }
+  #   Loam::Enrichers.enrich_many(equipments)  # => { id => { key => value }, ... }
+  #
+  # Distinct from custom fields: a custom field is STORED on the record; an
+  # enricher is COMPUTED at read time by different (possibly cross-module) code.
+  #
+  # BATCH to avoid N+1: pass `batch:` (an array -> { record.id => value }) and
+  # `enrich_many` resolves N records in one query instead of N. `enrich` reuses
+  # the batch path for a single record, so batched enrichers are cheap either way.
+  #
+  # Enrichers run in the CURRENT tenant context (the record was loaded there), so
+  # a resolver querying tenant-scoped models can only ever see this tenant's data.
+  # A resolver that raises is ISOLATED — its key is omitted, the rest still
+  # resolve, and the response is never broken. (No timeout in the prototype — a
+  # pathologically slow enricher is a future concern.)
+  module Enrichers
+    Enricher = Struct.new(:entity_type, :key, :priority, :resolver, :batch_resolver, keyword_init: true)
+
+    class << self
+      # Register an enricher for records of `entity_type` (the model's base-class
+      # name, e.g. "Equipment"). Provide a per-record block OR a `batch:` proc.
+      def register(entity_type, key:, priority: 0, batch: nil, &resolver)
+        raise ArgumentError, "register needs a block or a batch: resolver" unless resolver || batch
+
+        registry[entity_type.to_s] << Enricher.new(
+          entity_type: entity_type.to_s, key: key.to_s, priority: priority,
+          resolver: resolver, batch_resolver: batch
+        )
+      end
+
+      def enrich(record)
+        enrich_many([record]).fetch(record.id, {})
+      end
+
+      # { record.id => { key => value } } for a homogeneous array of records.
+      def enrich_many(records)
+        records = Array(records)
+        return {} if records.empty?
+
+        types = records.map { |record| record.class.base_class }.uniq
+        raise ArgumentError, "enrich_many expects one entity type, got #{types.map(&:name).join(', ')}" if types.size > 1
+
+        by_id = records.each_with_object({}) { |record, hash| hash[record.id] = {} }
+
+        for_type(types.first).each do |enricher|
+          # Per-enricher isolation: a raise omits THIS key for all records; the
+          # others still resolve.
+          begin
+            if enricher.batch_resolver
+              values = enricher.batch_resolver.call(records)
+              records.each { |record| by_id[record.id][enricher.key] = values[record.id] }
+            else
+              records.each { |record| by_id[record.id][enricher.key] = enricher.resolver.call(record) }
+            end
+          rescue StandardError => error
+            warn_failure(enricher, error)
+          end
+        end
+
+        by_id
+      end
+
+      # --- test support: the registry is process-global, so a test snapshots it
+      # in setup and restores in teardown (keeping the app's boot-registered
+      # enrichers intact, which `clear!` would not).
+      def snapshot
+        registry.transform_values(&:dup)
+      end
+
+      def restore(snapshot)
+        @registry = Hash.new { |hash, key| hash[key] = [] }
+        snapshot.each { |type, enrichers| @registry[type] = enrichers.dup }
+      end
+
+      private
+
+      def registry
+        @registry ||= Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # The enrichers for a class. Distinct keys compose; if two register the
+      # SAME key, higher priority wins, ties go to the later registration.
+      def for_type(klass)
+        registry[klass.base_class.name]
+          .group_by(&:key)
+          .map { |_key, group| group.each_with_index.max_by { |enricher, index| [enricher.priority, index] }.first }
+      end
+
+      def warn_failure(enricher, error)
+        Rails.logger&.warn(
+          "[Loam::Enrichers] #{enricher.entity_type}/#{enricher.key} raised #{error.class}: #{error.message} — key omitted"
+        )
+      end
+    end
+  end
+end

data/lib/loam/errors.rb

@@ -0,0 +1,49 @@
+module Loam
+  class Error < StandardError; end
+
+  # Raised whenever a tenant-scoped model is touched with no tenant in
+  # Loam::Current. This is a structural guardrail, not a convention: forgetting
+  # the tenant context fails loudly (in tests, before it leaks) instead of
+  # silently returning or writing cross-tenant data.
+  class MissingTenantError < Error
+    def initialize(msg = "No tenant set in Loam::Current — wrap this call in Loam.as_tenant(tenant) { ... }")
+      super
+    end
+  end
+
+  # Raised by admin controllers / callers when a policy check fails, and by a
+  # Loam::Workflow transition the current actor's role may not perform.
+  class NotAuthorizedError < Error; end
+
+  # Raised when a Loam::Workflow transition is attempted from a state it does
+  # not move from ("approve a report that was never submitted"). Like every
+  # Loam guardrail it fails at the call site rather than writing a state the
+  # machine says is impossible.
+  class InvalidTransitionError < Error; end
+
+  # Raised when an event name does not follow the `domain.thing.happened` convention.
+  class InvalidEventNameError < Error; end
+
+  # Raised by Loam::CustomFields#custom_field/#set_custom_field when the name
+  # has no matching Loam::FieldDefinition for this tenant + entity. Fails
+  # loudly at the access site rather than silently reading/writing nil.
+  class UnknownCustomFieldError < Error; end
+
+  # Raised by require_feature! when a capability is turned OFF for the current
+  # tenant. Distinct from NotAuthorizedError on purpose: a disabled feature is
+  # "not here" (the capability does not exist for this tenant), not "you may
+  # not" — so admin controllers render it as 404, not 403.
+  class FeatureDisabledError < Error; end
+
+  # Raised when a filter/sort is attempted on a custom field the current role may
+  # not read (Loam::CustomFieldIndex) — otherwise a filter would be an inference
+  # oracle on a restricted field. A NotAuthorizedError so admin controllers render
+  # it as 403, like any other field-access denial.
+  class FieldAccessError < NotAuthorizedError; end
+
+  # Raised when a Loam::BusinessRule with a `block_transition` action vetoes a
+  # workflow transition. Distinct from NotAuthorizedError (a role gate) and
+  # InvalidTransitionError (an illegal move): the move is legal and permitted,
+  # but a rule says "not under these conditions".
+  class TransitionVetoedError < Error; end
+end

data/lib/loam/eval.rb

@@ -0,0 +1,47 @@
+module Loam
+  # Scripted evaluation scoring for the golden tasks (L-303). An agent (or a
+  # human) implements a task against a fresh Loam app; this scores the RESULT
+  # consistently — the test outcome plus the structural invariants — into a
+  # machine-readable scorecard, so runs are comparable over time
+  # (ai/benchmark_runs/). Driving the agent is out of scope; consistent scoring
+  # is the point, and it encodes the golden-tasks bar: green suite AND no
+  # invariant violated.
+  module Eval
+    # The minitest summary line, whatever the counts: "N runs, M assertions,
+    # F failures, E errors, S skips".
+    SUMMARY = /(\d+)\s+runs?,\s+(\d+)\s+assertions?,\s+(\d+)\s+failures?,\s+(\d+)\s+errors?/
+
+    module_function
+
+    def parse_summary(output)
+      match = output.to_s.match(SUMMARY)
+      return nil unless match
+
+      { runs: match[1].to_i, assertions: match[2].to_i, failures: match[3].to_i, errors: match[4].to_i }
+    end
+
+    # A task PASSES only when the suite is green AND no invariant was violated —
+    # the bar the golden-tasks doc sets. `violations` is a list of invariant
+    # breaches a reviewer (or a lint) found (tenancy leak, unauthorized write, …);
+    # `interventions` counts human corrections needed. Both feed the comparison,
+    # neither is inferred here.
+    def scorecard(task:, summary:, violations: [], interventions: 0, notes: nil)
+      counts = summary || { runs: 0, assertions: 0, failures: 0, errors: 0 }
+      green = counts[:failures].to_i.zero? && counts[:errors].to_i.zero? && counts[:runs].to_i.positive?
+      passed = green && Array(violations).empty?
+
+      {
+        task: task.to_s,
+        passed: passed,
+        tests_green: green,
+        runs: counts[:runs].to_i,
+        assertions: counts[:assertions].to_i,
+        failures: counts[:failures].to_i,
+        errors: counts[:errors].to_i,
+        violations: Array(violations),
+        interventions: interventions.to_i,
+        notes: notes
+      }
+    end
+  end
+end