open-loam 0.1.1 → 0.3.0

data/lib/{loam → open_loam}/encryptable.rb

@@ -1,8 +1,8 @@
-module Loam
+module OpenLoam
   # Field-level encryption at rest, keyed per tenant. Declare it on a model:
   #
-  #   class Patient < Loam::TenantRecord
-  #     include Loam::Encryptable
+  #   class Patient < OpenLoam::TenantRecord
+  #     include OpenLoam::Encryptable
   #     encrypts :ssn                      # encrypted at rest, not searchable
   #     encrypts :email, searchable: true  # + a blind index for exact-match lookup
   #   end
@@ -11,7 +11,7 @@ module Loam
   #   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
+  # The value is sealed with the CURRENT tenant's key (OpenLoam.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
@@ -24,13 +24,13 @@ module Loam
     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
+      class_attribute :open_loam_encrypted_attributes, default: [].freeze, instance_writer: false
+      class_attribute :open_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/#{...}" }`
+      # OpenLoam.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`.
@@ -38,14 +38,14 @@ module Loam
         name = name.to_s
 
         if searchable && scope != :tenant
-          raise Loam::Error, "#{self.name}: `#{name}` cannot be both `searchable` and non-tenant-scoped."
+          raise OpenLoam::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,
+        if respond_to?(:open_loam_searchable_columns) && open_loam_searchable_columns.include?(name)
+          raise OpenLoam::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."
@@ -54,41 +54,45 @@ module Loam
         # 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,
+        if respond_to?(:open_loam_translatable_attributes) && open_loam_translatable_attributes.include?(name)
+          raise OpenLoam::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
+        self.open_loam_encrypted_attributes = (open_loam_encrypted_attributes + [name]).freeze
+        self.open_loam_searchable_encrypted_attributes = (open_loam_searchable_encrypted_attributes + [name]).freeze if searchable
 
-        include loam_encryption_reader_writer(name, searchable, scope)
-        define_loam_blind_index_finder(name) if searchable
+        include open_loam_encryption_reader_writer(name, searchable, scope)
+        define_open_loam_blind_index_finder(name) if searchable
       end
 
-      # Reader/writer live in their own module (the Loam::Workflow precedent) so
+      # Reader/writer live in their own module (the OpenLoam::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)
+      def open_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)
+            resolved = open_loam_encryption_scope(scope)
+            aad = OpenLoam::Encryption.aad(resolved, self.class.table_name, name)
+            OpenLoam::Encryption.decrypt_scoped(read_attribute(name), resolved, aad: aad)
           end
 
           define_method("#{name}=") do |value|
-            resolved = loam_encryption_scope(scope)
+            resolved = open_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))
+            aad = OpenLoam::Encryption.aad(resolved, self.class.table_name, name)
+            write_attribute(name, OpenLoam::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
+            if searchable
+              write_attribute(hash_column,
+                              OpenLoam::Encryption.blind_index_scoped(value, resolved,
+                                                                      table: self.class.table_name, column: name))
+            end
           end
         end
       end
@@ -97,11 +101,12 @@ module Loam
       # 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"
+      def define_open_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))
+          where(hash_column => OpenLoam::Encryption.blind_index(value, OpenLoam.tenant!.id,
+                                                                table: table_name, column: name))
         end
 
         define_singleton_method("find_by_#{name}") do |value|
@@ -117,11 +122,11 @@ module Loam
     # 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
+    def open_loam_encryption_scope(scope)
+      resolved = scope == :tenant ? "tenant/#{OpenLoam.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})"
+        raise OpenLoam::Encryption::Error, "#{self.class}: cannot derive an encryption key from a blank scope (#{resolved.inspect})"
       end
       resolved
     end
@@ -134,9 +139,9 @@ module Loam
     # 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|
+    # lib/tasks/open_loam.rake (open_loam:encryption:rotate).
+    def open_loam_reencrypt!
+      self.class.open_loam_encrypted_attributes.each do |name|
         public_send("#{name}=", public_send(name))
       end
       save!

data/lib/{loam → open_loam}/encryption/cipher.rb

@@ -1,4 +1,4 @@
-module Loam
+module OpenLoam
   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
@@ -13,7 +13,7 @@ module Loam
     # 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
+    # decrypting, so upgrading is a lazy re-encrypt (open_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
@@ -37,7 +37,7 @@ module Loam
         "#{version}:" + [iv + tag + ciphertext].pack("m0")
       end
 
-      # Decrypt, or raise Loam::Encryption::DecryptionError. The wrong tenant's
+      # Decrypt, or raise OpenLoam::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

data/lib/{loam → open_loam}/encryption/key_provider.rb

@@ -1,8 +1,8 @@
-module Loam
+module OpenLoam
   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
+    # `OpenLoam::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,
@@ -26,10 +26,26 @@ module Loam
       KEY_BYTES = 32   # AES-256 and HMAC-SHA256 both take a 32-byte key
 
       def data_key(scope:, purpose:)
+        derive(scope, purpose, OpenLoam::Encryption.master_key)
+      end
+
+      # The same derivation under the key being rotated away from, so decryption
+      # can fall back to it while open_loam:encryption:rotate rewrites rows under
+      # the new one. nil when no previous key is configured.
+      def previous_data_key(scope:, purpose:)
+        previous = OpenLoam::Encryption.previous_master_key
+        return nil if previous.nil?
+
+        derive(scope, purpose, previous)
+      end
+
+      private
+
+      def derive(scope, purpose, master)
         raise ArgumentError, "scope is required to derive a key" if scope.nil? || scope.to_s.empty?
 
         OpenSSL::KDF.hkdf(
-          Loam::Encryption.master_key,
+          master,
           salt: SALT,
           # info binds the key to owner AND purpose. "tenant/5" here reproduces
           # the pre-scope format exactly, so existing ciphertext still decrypts.

data/lib/{loam → open_loam}/encryption.rb

@@ -1,22 +1,22 @@
 require "openssl"
-require "loam/encryption/key_provider"
-require "loam/encryption/cipher"
+require "open_loam/encryption/key_provider"
+require "open_loam/encryption/cipher"
 
-module Loam
+module OpenLoam
   # Field-level encryption at rest, keyed per tenant.
   #
-  # The facade the rest of Loam calls: `encrypt`/`decrypt` seal and open a value
+  # The facade the rest of OpenLoam 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
+    class Error < OpenLoam::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. " \
+      def initialize(msg = "OpenLoam::Encryption has no master key. Set OPEN_LOAM_MASTER_KEY (or " \
+                           "`OpenLoam::Encryption.master_key = ...`) to a high-entropy secret, e.g. " \
                            "`SecureRandom.hex(32)`. NEVER commit it; use ENV or Rails credentials.")
         super
       end
@@ -41,19 +41,32 @@ module Loam
         @master_key = value
       end
 
+      attr_writer :previous_master_key
+
+      # The key being rotated AWAY from. Set it alongside the new master and
+      # decryption falls back to it, which is what makes rotation possible at
+      # all: open_loam:encryption:rotate has to READ every row under the old key
+      # before it can rewrite it under the new one. Unset it once the rotation
+      # has run everywhere.
+      def previous_master_key
+        key = defined?(@previous_master_key) ? @previous_master_key : nil
+        key ||= ENV["OPEN_LOAM_PREVIOUS_MASTER_KEY"]
+        key.presence
+      end
+
       def master_key
-        key = @master_key || ENV["LOAM_MASTER_KEY"]
+        key = @master_key || ENV["OPEN_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 " \
+                "OPEN_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
+      # OpenLoam::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))
@@ -68,8 +81,8 @@ module Loam
       # 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))
+      def blind_index(value, tenant_id, table: nil, column: nil)
+        blind_index_scoped(value, tenant_scope(tenant_id), table: table, column: column)
       end
 
       # Explicit-scope variants, for data owned by something OTHER than a tenant
@@ -82,23 +95,44 @@ module Loam
 
       def decrypt_scoped(payload, scope, aad: nil)
         return nil if payload.nil?
+
         Cipher.open(payload, data_key(scope, :encryption), aad: aad)
+      rescue DecryptionError
+        # GCM's auth tag makes "wrong key" a loud, unambiguous failure, so
+        # falling back is safe: a blob that opens under the previous key really
+        # was sealed with it. Writes always use the CURRENT key, so a row is
+        # rotated the moment anything saves it.
+        previous = previous_data_key(scope, :encryption)
+        raise if previous.nil?
+
+        Cipher.open(payload, previous, 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
+      # OpenLoam::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)
+      # The key is bound to (scope, table, column) for the same reason the
+      # ciphertext AAD is. A key scoped only to the tenant makes one value hash
+      # identically in every searchable column in that tenant: a dump correlates
+      # rows across tables, and anyone who can write one such field gets an
+      # equality oracle against columns they cannot read.
+      #
+      # table/column default to nil so an unbound caller still works — the
+      # per-tenant key, which is what OpenLoam::PendingActions wants for an
+      # idempotency digest that is not a column at all.
+      def blind_index_scoped(value, scope, table: nil, column: nil)
         return nil if value.nil?
-        OpenSSL::HMAC.hexdigest("SHA256", data_key(scope, :blind_index), value.to_s)
+
+        purpose = table && column ? "blind_index/#{table}/#{column}" : :blind_index
+        OpenSSL::HMAC.hexdigest("SHA256", data_key(scope, purpose), value.to_s)
       end
 
       private
@@ -120,6 +154,15 @@ module Loam
 
         key_provider.data_key(scope: scope, purpose: purpose)
       end
+
+      # nil unless a previous master is configured AND the provider supports the
+      # fallback — a KMS-backed provider manages its own key versions, so the
+      # base KeyProvider answers nil and nothing changes for it.
+      def previous_data_key(scope, purpose)
+        return nil unless key_provider.respond_to?(:previous_data_key)
+
+        key_provider.previous_data_key(scope: scope, purpose: purpose)
+      end
     end
   end
 end

data/lib/open_loam/engine.rb

@@ -0,0 +1,65 @@
+module OpenLoam
+  class Engine < ::Rails::Engine
+    # Not isolated on purpose: OpenLoam models live under the OpenLoam:: namespace but
+    # share the host app's routes/helpers, keeping the prototype surface small.
+
+    # Webhook dispatch listens to every OpenLoam event. Wired after initialization
+    # so the models it queries are loadable, and guarded against subscribing
+    # twice (see OpenLoam::Webhooks.subscribe!).
+    config.after_initialize do
+      OpenLoam::Webhooks.subscribe!
+      OpenLoam::DurableEvents.subscribe!    # persist + retry durable subscribers (L-706)
+      OpenLoam::EventLog.subscribe!         # capture every event as queryable history (L-204)
+      OpenLoam::BusinessRules.subscribe!
+      OpenLoam::Widgets.register_builtins!  # the default dashboard widgets
+      OpenLoam::Overrides.check!            # warn about any stale disable/replace overrides
+
+      # The durability sweep runs per-tenant on a schedule (materialized into
+      # each tenant by OpenLoam::Scheduler.sync_tenant). interval:300 = every 5 min.
+      OpenLoam::Scheduler.register(
+        key: OpenLoam::DurableEvents::SWEEP_KEY, name: "Event redelivery sweep",
+        job_class: "OpenLoam::EventRedeliverySweepJob", schedule: "interval:300", scope: "tenant"
+      )
+
+      # Event-log retention, also per-tenant. interval:86400 = daily; the window
+      # itself is OpenLoam.event_log_retention.
+      OpenLoam::Scheduler.register(
+        key: OpenLoam::EventLog::PRUNE_KEY, name: "Event log prune",
+        job_class: "OpenLoam::EventLogPruneJob", schedule: "interval:86400", scope: "tenant"
+      )
+    end
+
+    # OpenLoam's Active Record layer — TenantRecord, Auditable, Eventful and the
+    # rest — is defined inside ActiveSupport.on_load(:active_record) in
+    # lib/open_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 OpenLoam::TenantRecord and sorts ahead of application_record.rb reaches
+    # the constant before anything has touched Base, and eager load dies with
+    # "uninitialized constant OpenLoam::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 "open_loam.active_record_layer", before: :eager_load! do
+      ActiveRecord::Base
+    end
+
+    # OpenLoam'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/open_loam.<locale>.yml.
+    initializer "open_loam.i18n" do |app|
+      app.config.i18n.load_path += Dir[File.expand_path("locales/*.yml", __dir__)]
+    end
+
+    # lib/tasks/open_loam.rake (bin/rails open_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 → open_loam}/enrichers.rb

@@ -1,14 +1,14 @@
-module Loam
+module OpenLoam
   # 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|
+  #   OpenLoam::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 }, ... }
+  #   OpenLoam::Enrichers.enrich(equipment)        # => { "outstanding_balance" => 1200 }
+  #   OpenLoam::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.
@@ -97,7 +97,7 @@ module Loam
 
       def warn_failure(enricher, error)
         Rails.logger&.warn(
-          "[Loam::Enrichers] #{enricher.entity_type}/#{enricher.key} raised #{error.class}: #{error.message} — key omitted"
+          "[OpenLoam::Enrichers] #{enricher.entity_type}/#{enricher.key} raised #{error.class}: #{error.message} — key omitted"
         )
       end
     end

data/lib/{loam → open_loam}/errors.rb

@@ -1,31 +1,31 @@
-module Loam
+module OpenLoam
   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
+  # OpenLoam::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) { ... }")
+    def initialize(msg = "No tenant set in OpenLoam::Current — wrap this call in OpenLoam.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.
+  # OpenLoam::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
+  # Raised when a OpenLoam::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
+  # OpenLoam 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
+  # Raised by OpenLoam::CustomFields#custom_field/#set_custom_field when the name
+  # has no matching OpenLoam::FieldDefinition for this tenant + entity. Fails
   # loudly at the access site rather than silently reading/writing nil.
   class UnknownCustomFieldError < Error; end
 
@@ -36,12 +36,22 @@ module Loam
   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
+  # not read (OpenLoam::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
+  # Raised when a controller action finishes without having authorized anything
+  # (see the `verify_authorized!` guard in the generated base controllers).
+  #
+  # Deliberately NOT a NotAuthorizedError: that one means "this person may not",
+  # and the base controllers render it as a tidy 403. This means "this code
+  # forgot to ask", which is a developer bug that must not be dressed up as a
+  # refusal — nothing rescues it, so it surfaces as a 500 in dev and a failure
+  # in tests.
+  class AuthorizationNotPerformedError < Error; end
+
+  # Raised when a OpenLoam::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".

data/lib/{loam → open_loam}/eval.rb

@@ -1,6 +1,6 @@
-module Loam
+module OpenLoam
   # 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
+  # human) implements a task against a fresh OpenLoam 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

data/lib/open_loam/event_log.rb

@@ -0,0 +1,77 @@
+module OpenLoam
+  # Captures every published event as a queryable OpenLoam::EventRecord row —
+  # the capture half of the event system, where OpenLoam::DurableEvents is the
+  # delivery half ("durability is of DELIVERY, not CAPTURE").
+  #
+  # Capture is ON by default and captures everything but OpenLoam.uncaptured_events.
+  # That inverts OpenLoam.broadcast_events on purpose; see ADR 0007 for why, and
+  # for why this stayed in-gem rather than adopting Rails Event Store.
+  #
+  # Capture runs INLINE in the publisher's thread, so a failed insert propagates
+  # into whatever published the event. Deliberate — do not rescue it. Swallowing
+  # the error re-opens the silent gap this module exists to close.
+  module EventLog
+    PRUNE_KEY = "open_loam_event_log_prune".freeze
+
+    class << self
+      # Idempotent: subscribing twice would capture every event twice.
+      def subscribe!
+        @subscription ||= OpenLoam::Events.subscribe_all { |event_name, payload| capture(event_name, payload) }
+      end
+
+      # Exclusion is the only knob, because pattern_matches? has no match-all
+      # spelling ("" is an exact match on the empty name). Do not add an
+      # allow-list: capture-all has to stay the absence of configuration.
+      def capturable?(event_name)
+        OpenLoam.uncaptured_events.none? do |pattern|
+          next false if OpenLoam::Overrides.disabled?(:uncaptured_events, pattern) # an app can re-enable a default exclusion
+
+          OpenLoam::Events.pattern_matches?(pattern, event_name)
+        end
+      end
+
+      def capture(event_name, payload)
+        return unless capturable?(event_name)
+
+        tenant = OpenLoam::Tenant.find_by(id: payload[:tenant_id])
+        return if tenant.nil? # nil-tenant events are not captured (as Webhooks.dispatch / DurableEvents.capture)
+
+        OpenLoam.as_tenant(tenant) do
+          OpenLoam::EventRecord.create!(
+            name: event_name.to_s,
+            payload: payload.transform_keys(&:to_s),
+            occurred_at: Time.current
+          )
+        end
+      end
+
+      # name_or_prefix takes an exact event name or a trailing-dot domain
+      # prefix, the same rule as Events.subscribe. Oldest first.
+      def read(name_or_prefix = nil, since: nil, limit: nil)
+        scope = OpenLoam::EventRecord.chronological
+        scope = scope.matching(name_or_prefix) if name_or_prefix.present?
+        scope = scope.where(occurred_at: since..) if since
+        scope = scope.limit(limit) if limit
+        scope
+      end
+
+      # A re-read of history, NOT a second publish: nothing else on the bus fires
+      # and a replayed event is not re-captured. Handlers must be idempotent, and
+      # get string payload keys (from the row) where a live subscriber got symbols.
+      def replay(name_or_prefix = nil, since: nil, limit: nil, &handler)
+        read(name_or_prefix, since: since, limit: limit).each do |record|
+          handler.call(record.name, record.payload_hash)
+        end
+      end
+
+      # delete_all, NOT destroy_all: rows are readonly once persisted, and
+      # destroy on a readonly record raises ActiveRecord::ReadOnlyRecord.
+      def prune(now: Time.current)
+        retention = OpenLoam.event_log_retention
+        return 0 if retention.nil?
+
+        OpenLoam::EventRecord.where(occurred_at: ...(now - retention)).delete_all
+      end
+    end
+  end
+end