open-loam 0.1.1 → 0.3.0

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

@@ -1,6 +1,6 @@
-module Loam
+module OpenLoam
   # Undo/redo built ON the audit trail (L-704). Every change already records a
-  # Loam::AuditRecord with its changeset; undoing one applies the inverse and
+  # OpenLoam::AuditRecord with its changeset; undoing one applies the inverse and
   # writes a NEW audit record — so the inverse is itself undoable, and "redo" is
   # just undoing that undo entry. No separate command log to keep in sync.
   #
@@ -12,11 +12,11 @@ module Loam
   #   * encrypted fields — the audit stores "[encrypted]", never the old value,
   #     so there is nothing to revert to;
   #   * the workflow column — a direct write is blocked by the transition gate
-  #     (Loam::Workflow), so state is undone by performing the reverse TRANSITION,
+  #     (OpenLoam::Workflow), so state is undone by performing the reverse TRANSITION,
   #     not here;
   #   * fields the actor's role may not write (when a policy is supplied).
   module Undo
-    class NotUndoableError < Loam::Error; end
+    class NotUndoableError < OpenLoam::Error; end
 
     IGNORE = %w[id lock_version created_at updated_at].freeze
 
@@ -53,7 +53,7 @@ module Loam
 
     def revert_fields(record, audit, policy)
       ensure_latest!(audit)
-      workflow_column = record.class.respond_to?(:loam_workflow) ? record.class.loam_workflow&.column.to_s : nil
+      workflow_column = record.class.respond_to?(:open_loam_workflow) ? record.class.open_loam_workflow&.column.to_s : nil
 
       updates = {}
       (audit.changeset || {}).each do |field, values|
@@ -69,10 +69,10 @@ module Loam
       raise NotUndoableError, "nothing revertable in this change" if updates.empty?
 
       # Relabel this save's audit as "undo" so the history reads legibly (and the
-      # entry is itself undoable = redo). loam_audit_as is the same hook
+      # entry is itself undoable = redo). open_loam_audit_as is the same hook
       # SoftDeletable uses for soft_delete/restore.
-      if record.respond_to?(:loam_audit_as, true)
-        record.send(:loam_audit_as, "undo") { record.update!(updates) }
+      if record.respond_to?(:open_loam_audit_as, true)
+        record.send(:open_loam_audit_as, "undo") { record.update!(updates) }
       else
         record.update!(updates)
       end
@@ -92,7 +92,7 @@ module Loam
     # The audit must be the record's most recent update/undo — else undoing it
     # would overwrite newer edits. Tenant-scoped via AuditRecord's default scope.
     def ensure_latest!(audit)
-      latest = Loam::AuditRecord
+      latest = OpenLoam::AuditRecord
                .where(auditable_type: audit.auditable_type, auditable_id: audit.auditable_id, action: %w[update undo])
                .order(:id).last
       return if latest.nil? || latest.id == audit.id
@@ -105,7 +105,7 @@ module Loam
     # restore. Never AuditRecord#auditable, which is unscoped.
     def load_record(audit)
       klass = audit.auditable_type.safe_constantize
-      raise NotUndoableError, "unknown type #{audit.auditable_type.inspect}" unless klass.is_a?(Class) && klass < Loam::TenantRecord
+      raise NotUndoableError, "unknown type #{audit.auditable_type.inspect}" unless klass.is_a?(Class) && klass < OpenLoam::TenantRecord
 
       scope = klass.respond_to?(:with_deleted) ? klass.with_deleted : klass.all
       record = scope.find_by(id: audit.auditable_id)
@@ -120,7 +120,7 @@ module Loam
     end
 
     def ensure_current_tenant!(audit)
-      raise NotUndoableError, "not in this tenant" unless audit.tenant_id == Loam.tenant!.id
+      raise NotUndoableError, "not in this tenant" unless audit.tenant_id == OpenLoam.tenant!.id
     end
   end
 end

data/lib/open_loam/version.rb

@@ -0,0 +1,3 @@
+module OpenLoam
+  VERSION = "0.3.0"
+end

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

@@ -1,12 +1,12 @@
-module Loam
+module OpenLoam
   # Domain events, delivered over HTTP to whoever asked for them.
   #
-  # One global subscriber listens to every Loam event and, in the tenant the
+  # One global subscriber listens to every OpenLoam event and, in the tenant the
   # event was published in, enqueues a delivery per matching active endpoint.
   # Matching happens at dispatch time rather than at subscribe time because
   # endpoints are data: a tenant can add one from the admin without a reboot.
   module Webhooks
-    # Wired once from Loam::Engine. Idempotent: subscribing twice would deliver
+    # Wired once from OpenLoam::Engine. Idempotent: subscribing twice would deliver
     # every event twice.
     def self.subscribe!
       @subscription ||= Events.subscribe_all { |event_name, payload| dispatch(event_name, payload) }
@@ -22,7 +22,7 @@ module Loam
       # and scalars by convention, never records.
       deliverable = payload.transform_keys(&:to_s)
 
-      Loam.as_tenant(tenant) do
+      OpenLoam.as_tenant(tenant) do
         WebhookEndpoint.active.each do |endpoint|
           next unless endpoint.matches?(event_name)
 

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

@@ -1,9 +1,9 @@
-module Loam
+module OpenLoam
   # A registry of dashboard widgets — small, module-provided tiles (a metric, a
   # short list) shown on the admin home. A widget is a DATA PROVIDER plus a
   # title and an optional role filter; it never renders arbitrary code:
   #
-  #   Loam::Widgets.register(key: "open_rentals", title: "Open rentals", roles: %w[manager]) do |actor|
+  #   OpenLoam::Widgets.register(key: "open_rentals", title: "Open rentals", roles: %w[manager]) do |actor|
   #     { kind: "count", value: Rental.where(status: "open").count }   # tenant-scoped query
   #   end
   #
@@ -37,33 +37,33 @@ module Loam
       # can't see it (so its data is never computed), otherwise
       # { key, title, data } — or { key, title, error: } when the provider raises.
       def resolve(key, actor:, role:)
-        return nil if Loam::Overrides.disabled?(:widgets, key) # customization without forking
+        return nil if OpenLoam::Overrides.disabled?(:widgets, key) # customization without forking
 
         widget = find(key)
         return nil unless widget&.visible_to?(role)
 
-        provider = Loam::Overrides.replacement(:widgets, key) || widget.provider
+        provider = OpenLoam::Overrides.replacement(:widgets, key) || widget.provider
         { key: widget.key, title: widget.title, data: provider.call(actor) }
       rescue StandardError => error
         { key: widget&.key, title: widget&.title, error: error.message }
       end
 
-      # The widgets every Loam app starts with — registered at boot from the
+      # The widgets every OpenLoam app starts with — registered at boot from the
       # engine, so a fresh install has a useful default dashboard.
       def register_builtins!
         register(key: "audit_recent", title: "Recent activity") do |_actor|
-          items = Loam::AuditRecord.order(created_at: :desc).limit(8)
+          items = OpenLoam::AuditRecord.order(created_at: :desc).limit(8)
                                    .map { |a| "#{a.action} #{a.auditable_type} ##{a.auditable_id}" }
           { kind: "list", items: items }
         end
         register(key: "notifications_unread", title: "Unread notifications") do |actor|
-          { kind: "count", value: Loam::Notification.unread.where(user_id: actor&.id).count }
+          { kind: "count", value: OpenLoam::Notification.unread.where(user_id: actor&.id).count }
         end
         register(key: "pending_approvals", title: "Pending approvals", roles: %w[manager]) do |_actor|
-          { kind: "count", value: Loam::PendingAction.pending.count }
+          { kind: "count", value: OpenLoam::PendingAction.pending.count }
         end
         register(key: "open_progress", title: "Running tasks") do |_actor|
-          { kind: "count", value: Loam::ProgressJob.where(status: "running").count }
+          { kind: "count", value: OpenLoam::ProgressJob.where(status: "running").count }
         end
       end
 

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

@@ -1,9 +1,9 @@
-module Loam
+module OpenLoam
   # Declarative state machine for a tenant-scoped entity: the states a record
   # can be in, the legal moves between them, and who may make each move.
   #
-  #   class PurchaseOrder < Loam::TenantRecord
-  #     include Loam::Workflow
+  #   class PurchaseOrder < OpenLoam::TenantRecord
+  #     include OpenLoam::Workflow
   #
   #     workflow :status, initial: "draft" do
   #       state "draft"
@@ -18,14 +18,14 @@ module Loam
   #   order.submit!                         # draft -> pending_approval, publishes
   #                                         # "<domain>.purchase_order.submit"
   #   order.workflow_transitions_available  # => [:approve] for a manager, [] for anyone else
-  #   PurchaseOrder.loam_workflow           # the frozen definition, for agents and admin UI
+  #   PurchaseOrder.open_loam_workflow           # the frozen definition, for agents and admin UI
   #
   # What this buys over hand-rolled `if status == "draft"`: an illegal move
   # raises instead of silently writing a bad value, the roles that may move a
   # record are declared in one readable place instead of scattered across
   # controllers, and the whole machine is introspectable.
   #
-  # The state change itself is an ordinary attribute write, so Loam::Auditable
+  # The state change itself is an ordinary attribute write, so OpenLoam::Auditable
   # records it like any other change — a workflow adds no second audit trail.
   module Workflow
     extend ActiveSupport::Concern
@@ -99,22 +99,22 @@ module Loam
 
     included do
       # nil until `workflow` is called; inherited by subclasses.
-      class_attribute :loam_workflow, instance_writer: false, default: nil
+      class_attribute :open_loam_workflow, instance_writer: false, default: nil
 
       # THE gate: the workflow column may only change through a transition
-      # (loam_perform_transition!), which enforces from-state and role. A direct
+      # (open_loam_perform_transition!), which enforces from-state and role. A direct
       # write — the edit form, Bulk.set_field, an import, a business-rule
       # set_field — would otherwise let a member self-"approve", skipping the
       # transition's roles:. Closing it here closes ALL paths at once. Creation
       # (the initial state) is exempt (`on: :update`).
-      validate :loam_workflow_column_only_via_transition, on: :update
+      validate :open_loam_workflow_column_only_via_transition, on: :update
     end
 
     class_methods do
       # The DSL. `initial:` defaults to the first declared state.
       def workflow(column, initial: nil, &block)
         definition = Builder.new(column, initial).build(&block)
-        self.loam_workflow = definition
+        self.open_loam_workflow = definition
 
         before_validation on: :create do
           self[definition.column] = definition.initial if self[definition.column].blank?
@@ -125,29 +125,29 @@ module Loam
         validates definition.column,
                   inclusion: { in: definition.states, message: "is not one of: #{definition.states.join(', ')}" }
 
-        include loam_workflow_module(definition)
+        include open_loam_workflow_module(definition)
       end
 
       # Transition and predicate methods live in their own module rather than
       # on the class, so an app can override `submit!` and still call `super`.
-      def loam_workflow_module(definition)
+      def open_loam_workflow_module(definition)
         model = self
 
         Module.new do
           definition.transitions.each_value do |transition|
-            define_method("#{transition.name}!") { loam_perform_transition!(transition) }
+            define_method("#{transition.name}!") { open_loam_perform_transition!(transition) }
           end
 
           definition.states.each do |state|
             predicate = "#{state}?"
-            next unless model.loam_workflow_predicate_free?(predicate)
+            next unless model.open_loam_workflow_predicate_free?(predicate)
 
             # A state predicate must never shadow a real column: DamageReport
             # has both a workflow state "approved" and an `approved` boolean
             # column, and `record.approved?` has to stay the column's. The
             # column check happens at CALL time, not class-load time — at load
             # the schema may not be readable yet (fresh CI database, db:create),
-            # and a load-time decision made Loam behave differently on CI than
+            # and a load-time decision made OpenLoam behave differently on CI than
             # on a warmed-up dev machine.
             define_method(predicate) do
               if self.class.columns_hash.key?(state)
@@ -162,41 +162,41 @@ module Loam
 
       # Explicitly defined methods still win — only truly free names get a
       # workflow predicate. Column collisions are handled inside the predicate
-      # itself (see loam_workflow_module), where the schema is reliably known.
-      def loam_workflow_predicate_free?(predicate)
+      # itself (see open_loam_workflow_module), where the schema is reliably known.
+      def open_loam_workflow_predicate_free?(predicate)
         !method_defined?(predicate) && !private_method_defined?(predicate)
       end
     end
 
     # Transition names that are legal right now: from this record's state, for
-    # the actor in Loam::Current. Never raises — an admin screen asks this to
+    # the actor in OpenLoam::Current. Never raises — an admin screen asks this to
     # decide which buttons to render.
     def workflow_transitions_available
-      role = loam_workflow_role
+      role = open_loam_workflow_role
 
-      self.class.loam_workflow.transitions_from(loam_workflow_state)
+      self.class.open_loam_workflow.transitions_from(open_loam_workflow_state)
           .select { |transition| transition.roles.empty? || transition.roles.include?(role) }
           .map(&:name)
     end
 
-    def loam_workflow_state
-      self[self.class.loam_workflow.column].to_s
+    def open_loam_workflow_state
+      self[self.class.open_loam_workflow.column].to_s
     end
 
     private
 
-    def loam_workflow_column_only_via_transition
-      return unless self.class.loam_workflow
+    def open_loam_workflow_column_only_via_transition
+      return unless self.class.open_loam_workflow
 
-      column = self.class.loam_workflow.column
+      column = self.class.open_loam_workflow.column
       return unless attribute_changed?(column)
-      return if @loam_in_transition
+      return if @open_loam_in_transition
 
       errors.add(column, "can only change through a workflow transition, not a direct write")
     end
 
-    def loam_perform_transition!(transition)
-      from = loam_workflow_state
+    def open_loam_perform_transition!(transition)
+      from = open_loam_workflow_state
 
       unless transition.from.include?(from)
         raise InvalidTransitionError,
@@ -204,53 +204,53 @@ module Loam
               "but this record is #{from.inspect}"
       end
 
-      loam_authorize_transition!(transition)
+      open_loam_authorize_transition!(transition)
 
-      self[self.class.loam_workflow.column] = transition.to
+      self[self.class.open_loam_workflow.column] = transition.to
       begin
-        @loam_in_transition = true # tells the guard THIS column change is blessed
+        @open_loam_in_transition = true # tells the guard THIS column change is blessed
         save!
       ensure
-        @loam_in_transition = false
+        @open_loam_in_transition = false
       end
 
-      Loam::Events.publish(
-        "#{loam_workflow_event_domain}.#{model_name.param_key}.#{transition.name}",
+      OpenLoam::Events.publish(
+        "#{open_loam_workflow_event_domain}.#{model_name.param_key}.#{transition.name}",
         id: id, from: from, to: transition.to
       )
 
       self
     end
 
-    def loam_authorize_transition!(transition)
+    def open_loam_authorize_transition!(transition)
       return if transition.roles.empty?
 
       allowed = transition.roles.join(", ")
-      unless Loam::Current.actor
+      unless OpenLoam::Current.actor
         raise NotAuthorizedError,
               "#{self.class.name}##{transition.name}! is restricted to #{allowed}, but there is no actor in " \
-              "Loam::Current — wrap the call in Loam.as_tenant(tenant, actor: user) { ... }"
+              "OpenLoam::Current — wrap the call in OpenLoam.as_tenant(tenant, actor: user) { ... }"
       end
 
-      return if transition.roles.include?(loam_workflow_role)
+      return if transition.roles.include?(open_loam_workflow_role)
 
       raise NotAuthorizedError,
             "#{self.class.name}##{transition.name}! is restricted to #{allowed}; " \
-            "this actor's role is #{loam_workflow_role.inspect}"
+            "this actor's role is #{open_loam_workflow_role.inspect}"
     end
 
-    # Role resolution deliberately goes through Loam::Policy: "your role" means
+    # Role resolution deliberately goes through OpenLoam::Policy: "your role" means
     # exactly one thing — your membership role in the current tenant — here, in
     # policies, and in the admin.
-    def loam_workflow_role
-      actor = Loam::Current.actor
-      actor && Loam::Policy.new(actor, self).role
+    def open_loam_workflow_role
+      actor = OpenLoam::Current.actor
+      actor && OpenLoam::Policy.new(actor, self).role
     end
 
     # Transitions publish into the model's own event domain when it has one
-    # (Loam::Eventful), so workflow events sit beside the lifecycle events.
-    def loam_workflow_event_domain
-      self.class.respond_to?(:loam_event_domain) ? self.class.loam_event_domain : "app"
+    # (OpenLoam::Eventful), so workflow events sit beside the lifecycle events.
+    def open_loam_workflow_event_domain
+      self.class.respond_to?(:open_loam_event_domain) ? self.class.open_loam_event_domain : "app"
     end
   end
 end

data/lib/open_loam.rb

@@ -0,0 +1,124 @@
+require "open_loam/version"
+require "open_loam/errors"
+require "open_loam/current"
+require "open_loam/events"
+require "open_loam/policy"
+require "open_loam/lifecycle"
+require "open_loam/configs"
+require "open_loam/features"
+require "open_loam/auth_throttle"
+require "open_loam/outbound_url"
+require "open_loam/dictionaries"
+require "open_loam/custom_field_index"
+require "open_loam/undo"
+require "open_loam/permissions"
+require "open_loam/telemetry"
+require "open_loam/eval"
+require "open_loam/mcp"
+require "open_loam/mcp/server"
+require "open_loam/progress"
+require "open_loam/cron"
+require "open_loam/scheduler"
+require "open_loam/csv"
+require "open_loam/export"
+require "open_loam/import"
+require "open_loam/bulk"
+require "open_loam/widgets"
+require "open_loam/dashboard"
+require "open_loam/overrides"
+require "open_loam/open_api"
+require "open_loam/encryption"
+require "open_loam/base32"
+require "open_loam/totp"
+require "open_loam/pending_actions"
+require "open_loam/perspectives"
+require "open_loam/record_locks"
+require "open_loam/event_stream"
+require "open_loam/enrichers"
+require "open_loam/search"
+require "open_loam/search/driver"
+require "open_loam/search/like_driver"
+require "open_loam/search/token_driver"
+require "open_loam/notifications"
+require "open_loam/sso"
+require "open_loam/business_rules"
+require "open_loam/webhooks"
+require "open_loam/inbound_webhooks"
+require "open_loam/durable_events"
+require "open_loam/event_log"
+require "open_loam/engine" if defined?(Rails::Engine)
+
+module OpenLoam
+  # The current tenant, or a loud failure. This is THE guardrail: tenant-scoped
+  # code paths call this, so a missing tenant context can never silently widen
+  # a query to all tenants.
+  def self.tenant!
+    Current.tenant or raise MissingTenantError
+  end
+
+  def self.tenant
+    Current.tenant
+  end
+
+  def self.actor
+    Current.actor
+  end
+
+  # Feature-string permission check for the current actor's role (see
+  # OpenLoam::Permissions) — deny-by-default, wildcard-aware. `role:` overrides the
+  # actor's role. Returns false with no actor/role.
+  def self.can?(permission, role: nil)
+    role ||= Current.actor && OpenLoam::Membership.find_by(user_id: Current.actor.id)&.role
+    OpenLoam::Permissions.allow?(role, permission)
+  end
+
+  # The approval-gate seam. When a caller runs under :confirm (an MCP tool acting
+  # for an AI agent), a write should be STAGED for human approval via
+  # OpenLoam::PendingActions.stage instead of committed. OpenLoam does not intercept
+  # Active Record globally — this is the documented hook a write path checks.
+  def self.mutation_mode
+    Current.mutation_mode || :direct
+  end
+
+  def self.require_confirmation?
+    mutation_mode == :confirm
+  end
+
+  # Run a block with writes gated for approval. The one blessed way to enter
+  # confirm-mode; restores the previous mode afterwards.
+  def self.with_confirmation
+    previous = Current.mutation_mode
+    Current.mutation_mode = :confirm
+    yield
+  ensure
+    Current.mutation_mode = previous
+  end
+
+  # Run a block inside a tenant (and optional actor) context, restoring the
+  # previous context afterwards. The one blessed way to switch tenants.
+  def self.as_tenant(tenant, actor: nil)
+    previous_tenant = Current.tenant
+    previous_actor = Current.actor
+    Current.tenant = tenant
+    Current.actor = actor if actor
+    yield
+  ensure
+    Current.tenant = previous_tenant
+    Current.actor = previous_actor
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  require "open_loam/generated_key"
+  require "open_loam/tenant_record"
+  require "open_loam/auditable"
+  require "open_loam/soft_deletable"
+  require "open_loam/eventful"
+  require "open_loam/custom_fields"
+  require "open_loam/workflow"
+  require "open_loam/searchable"
+  require "open_loam/encryptable"
+  require "open_loam/translatable"
+  require "open_loam/commentable"
+  require "open_loam/attachable"
+end