open-loam 0.1.0

data/lib/loam/business_rules/condition.rb

@@ -0,0 +1,102 @@
+module Loam
+  module BusinessRules
+    # The SAFE condition evaluator — the critical security boundary of the rules
+    # engine. A rule is DATA an admin edits, so this must NEVER run arbitrary
+    # code: it supports only `and`/`or`/`not` and leaf comparisons
+    # `{ field, op, value }`, and a `field` may name ONLY a real, non-plumbing,
+    # non-encrypted column of the record OR a declared custom field. Anything
+    # else is refused — no `send` of arbitrary methods, no SQL, no eval.
+    module Condition
+      OPS = %w[eq neq gt gte lt lte in contains present blank].freeze
+      REFUSED = :__loam_field_refused__
+
+      def self.matches?(node, record)
+        node = node.is_a?(Hash) ? node : {}
+        return true if node.empty? # no condition = always fires
+
+        if node.key?("and")
+          Array(node["and"]).all? { |child| matches?(child, record) }
+        elsif node.key?("or")
+          Array(node["or"]).any? { |child| matches?(child, record) }
+        elsif node.key?("not")
+          !matches?(node["not"], record)
+        else
+          leaf(node, record)
+        end
+      end
+
+      def self.leaf(node, record)
+        op = node["op"].to_s
+        return false unless OPS.include?(op)
+
+        actual = read_field(node["field"].to_s, record)
+        return false if actual == REFUSED # an un-whitelisted field never matches
+
+        compare(op, actual, node["value"])
+      end
+
+      # A whitelisted read, or REFUSED. `tenant_id` is refused as an isolation
+      # footgun; ENCRYPTED columns are refused because a contains/eq rule over
+      # their decrypted value would be an oracle leaking the secret through the
+      # rule's behaviour. Everything unknown is refused, never sent.
+      def self.read_field(field, record)
+        klass = record.class
+        return REFUSED if refused_column?(klass, field)
+
+        if klass.column_names.include?(field)
+          record.public_send(field)
+        elsif custom_field?(record, field)
+          begin
+            record.custom_field(field)
+          rescue Loam::UnknownCustomFieldError
+            REFUSED
+          end
+        else
+          REFUSED
+        end
+      end
+
+      def self.refused_column?(klass, field)
+        return true if field == "tenant_id"
+
+        klass.respond_to?(:loam_encrypted_attributes) &&
+          klass.loam_encrypted_attributes.map(&:to_s).include?(field)
+      end
+
+      def self.custom_field?(record, field)
+        record.class.respond_to?(:custom_field_definitions) &&
+          record.class.custom_field_definitions.exists?(name: field)
+      end
+
+      def self.compare(op, actual, expected)
+        case op
+        when "eq"       then values_equal?(actual, expected)
+        when "neq"      then !values_equal?(actual, expected)
+        when "in"       then Array(expected).map(&:to_s).include?(actual.to_s)
+        when "contains" then actual.to_s.include?(expected.to_s)
+        when "present"  then actual.present?
+        when "blank"    then actual.blank?
+        else
+          cmp = numeric_compare(actual, expected)
+          return false if cmp.nil?
+
+          { "gt" => cmp.positive?, "gte" => cmp >= 0, "lt" => cmp.negative?, "lte" => cmp <= 0 }[op]
+        end
+      end
+
+      def self.values_equal?(actual, expected)
+        actual == expected || actual.to_s == expected.to_s || numeric_compare(actual, expected)&.zero? || false
+      end
+
+      # Compare as numbers when both coerce; else fall back to the natural
+      # comparison; incomparable types yield nil (so the op is simply false).
+      def self.numeric_compare(actual, expected)
+        Float(actual) <=> Float(expected)
+      rescue ArgumentError, TypeError
+        actual <=> expected
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/loam/business_rules.rb

@@ -0,0 +1,123 @@
+require "loam/business_rules/condition"
+require "loam/business_rules/actions"
+
+module Loam
+  # The engine that evaluates Loam::BusinessRule rows: WHEN a trigger fires and
+  # the condition holds, THEN run the actions — in the event's tenant context,
+  # in priority order, each rule isolated so one failure never breaks dispatch.
+  #
+  # It listens to every Loam event (like Loam::Webhooks), so a tenant can add a
+  # rule from the admin without a reboot. Evaluation runs INLINE in whatever
+  # published the event — cheap for the prototype; a job-based dispatcher is the
+  # scaling path.
+  module BusinessRules
+    MAX_DEPTH = 3 # bounds a rule chain: an emit_event action can trigger more
+                  # rules, but only so deep, so a self-triggering rule terminates.
+
+    class << self
+      # Wired once from Loam::Engine. Idempotent — subscribing twice would run
+      # every rule twice (see Loam::Webhooks.subscribe!).
+      def subscribe!
+        @subscription ||= Loam::Events.subscribe_all { |event_name, payload| on_event(event_name, payload) }
+      end
+
+      def on_event(event_name, payload)
+        tenant = Loam::Tenant.find_by(id: payload[:tenant_id])
+        return if tenant.nil?
+
+        Loam.as_tenant(tenant) do
+          within_depth_guard do
+            Loam::BusinessRule.active.by_priority.each do |rule|
+              next unless rule.matches_trigger?(event_name)
+
+              run_rule(rule, subject_for(rule, payload), event_name)
+            end
+          end
+        end
+      end
+
+      # Manual evaluation for a record — for programmatic/test use. Runs the
+      # active rules for the record's entity type (optionally filtered to a
+      # trigger) in priority order.
+      def evaluate(record, trigger: nil)
+        Loam::BusinessRule.active.for_entity(record.class.base_class.name).by_priority.each do |rule|
+          next if trigger && !rule.matches_trigger?(trigger)
+
+          run_rule(rule, record, trigger)
+        end
+      end
+
+      # Do the active rules with a block_transition action, whose condition
+      # holds, veto this transition? Consulted by a workflow BEFORE it moves (see
+      # the demo's DamageReport). Evaluate-only — no actions run, nothing logged.
+      def veto?(record, trigger)
+        Loam::BusinessRule.active.for_entity(record.class.base_class.name).by_priority.any? do |rule|
+          rule.matches_trigger?(trigger) &&
+            rule.action_list.any? { |action| action["type"].to_s == "block_transition" } &&
+            Condition.matches?(rule.condition_tree, record)
+        end
+      end
+
+      private
+
+      def run_rule(rule, record, event_name)
+        if record.nil? && rule.entity_type.present?
+          return log(rule, nil, event_name, matched: false, error: "subject not found")
+        end
+
+        matched = Condition.matches?(rule.condition_tree, record)
+        taken = []
+        # block_transition is a veto signal consumed elsewhere, not an action to
+        # perform here, so it is skipped in the THEN path.
+        rule.action_list.each { |action| taken << Actions.run(action, record) } if matched && record
+
+        log(rule, record, event_name, matched: matched, actions_taken: taken.compact) if matched || taken.any?
+      rescue StandardError => error
+        log(rule, record, event_name, matched: false, error: error.message)
+      end
+
+      def log(rule, record, event_name, matched:, actions_taken: [], error: nil)
+        # Lean: log the runs that ACTED, errored, or found no subject — not the
+        # deterministic "condition didn't match" ones (readable from the rule).
+        return if !matched && error.nil?
+
+        Loam::BusinessRuleRun.create!(
+          business_rule: rule,
+          subject_type: record&.class&.base_class&.name,
+          subject_id: record&.id,
+          event_name: event_name,
+          matched: matched,
+          actions_taken: actions_taken,
+          error: error
+        )
+      end
+
+      # A rule watches a specific entity; load THAT record from the rule's
+      # entity_type + the event's id (find_by, not find — a record deleted
+      # between publish and dispatch is a missing subject, not a crash).
+      def subject_for(rule, payload)
+        return nil if rule.entity_type.blank? || payload[:id].blank?
+
+        klass = rule.entity_type.safe_constantize
+        # A rule may ONLY target a tenant-scoped model. This is the security
+        # boundary: a global model like `User` has no tenant default scope, so a
+        # find_by(id:) would reach across tenants — refusing anything that is not
+        # a Loam::TenantRecord closes that, and a TenantRecord.find_by can only
+        # ever return a record in the CURRENT tenant even if an id is injected.
+        return nil unless klass.is_a?(Class) && klass < Loam::TenantRecord
+
+        klass.find_by(id: payload[:id])
+      end
+
+      def within_depth_guard
+        depth = Thread.current[:loam_rule_depth] ||= 0
+        return if depth >= MAX_DEPTH
+
+        Thread.current[:loam_rule_depth] = depth + 1
+        yield
+      ensure
+        Thread.current[:loam_rule_depth] = depth if depth
+      end
+    end
+  end
+end

data/lib/loam/commentable.rb

@@ -0,0 +1,22 @@
+module Loam
+  # Discussion on a record:
+  #
+  #   equipment.comment!("Hydraulics serviced")   # as Loam.actor
+  #   equipment.loam_comments.oldest_first
+  #
+  # Included by every generated entity. Comments are tenant-scoped like their
+  # subject, so a discussion can never be read from another tenant.
+  module Commentable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :loam_comments, as: :commentable, class_name: "Loam::Comment", dependent: :destroy
+    end
+
+    # Author defaults to whoever is acting — the same person the audit trail
+    # and the event payload would name.
+    def comment!(body, author: Loam::Current.actor)
+      loam_comments.create!(body: body, author: author)
+    end
+  end
+end

data/lib/loam/configs.rb

@@ -0,0 +1,115 @@
+module Loam
+  # The one way to read and write per-tenant settings.
+  #
+  #   Loam::Configs.get("rental.late_fee_per_day")          # resolved for the current tenant
+  #   Loam::Configs.set("rental.late_fee_per_day", 45)      # this tenant's override
+  #   Loam::Configs.set("rental.currency", "PLN", scope: :global)
+  #   Loam::Configs.reset("rental.late_fee_per_day")        # drop the override → fall back
+  #
+  # Resolution order, most specific first:
+  #   1. the current tenant's OVERRIDE row (tenant_id = current tenant)
+  #   2. the GLOBAL row (tenant_id NULL)
+  #   3. the declared default in Loam.config_defaults[key]
+  #   4. the `default:` argument (nil)
+  #
+  # Reads are memoized per request in Loam::Current.config_cache, keyed by
+  # [key, tenant_id], and the whole cache is dropped on any write. That is the
+  # deliberately-simple prototype cache; a Rails.cache-backed layer shared across
+  # requests is the scaling path, and it would slot in behind this same API.
+  module Configs
+    class << self
+      def get(key, default: nil)
+        key = key.to_s
+        store = cache
+        cache_key = [key, current_tenant_id]
+
+        return store[cache_key] if store.key?(cache_key)
+
+        # Only a value that actually RESOLVED (a row or a declared default) is
+        # cached — never the caller's `default:` fallback. The cache key omits
+        # `default:`, so caching it would make a later get with a different
+        # default wrongly return the first one when nothing is configured.
+        found, value = resolve(key)
+        return default unless found
+
+        store[cache_key] = value
+      end
+
+      # Write a setting. scope: :tenant writes the current tenant's override and
+      # requires a tenant in context (a missing one raises, like every Loam
+      # write); scope: :global writes the app-wide row (tenant_id NULL). Upsert.
+      def set(key, value, scope: :tenant)
+        key = key.to_s
+        record = row_for(key, scope).first_or_initialize
+        record.value_json = value
+        record.save!
+        clear_cache
+        value
+      end
+
+      # Drop the current tenant's override for a key so it falls back to the
+      # global row / declared default. Requires a tenant in context. No-op if
+      # there was no override. Returns true.
+      def reset(key)
+        row_for(key.to_s, :tenant).delete_all
+        clear_cache
+        true
+      end
+
+      # Whether the current tenant has an override for this key (vs. inheriting
+      # the global/declared value). Drives the admin "overridden?" column.
+      def overridden?(key)
+        row_for(key.to_s, :tenant).exists?
+      end
+
+      # Every key an admin might configure for the current tenant: declared
+      # defaults, plus any global or current-tenant rows already written. Sorted
+      # and de-duplicated, for the settings screen.
+      def defined_keys
+        rows = Loam::Config.where(tenant_id: [nil, Loam.tenant&.id]).distinct.pluck(:key)
+        (Loam.config_defaults.keys + rows).map(&:to_s).uniq.sort
+      end
+
+      private
+
+      # Returns [found?, value]. `found?` is false only when nothing resolved —
+      # the caller then applies its own `default:` without caching it.
+      def resolve(key)
+        if (tenant_id = current_tenant_id)
+          override = Loam::Config.find_by(key: key, tenant_id: tenant_id)
+          return [true, override.value_json] if override
+        end
+
+        global = Loam::Config.find_by(key: key, tenant_id: nil)
+        return [true, global.value_json] if global
+
+        return [true, Loam.config_defaults[key]] if Loam.config_defaults.key?(key)
+
+        [false, nil]
+      end
+
+      # The row(s) a write/read targets. :global is the tenant_id NULL row;
+      # :tenant is the current tenant's — which requires a tenant in context,
+      # so Loam.tenant! raises MissingTenantError when there is none.
+      def row_for(key, scope)
+        case scope
+        when :global then Loam::Config.where(key: key, tenant_id: nil)
+        when :tenant then Loam::Config.where(key: key, tenant_id: Loam.tenant!.id)
+        else raise ArgumentError, "unknown config scope #{scope.inspect} (use :tenant or :global)"
+        end
+      end
+
+      def current_tenant_id
+        Loam.tenant&.id
+      end
+
+      def cache
+        Loam::Current.config_cache ||= {}
+      end
+
+      def clear_cache
+        Loam::Current.config_cache = {}
+      end
+    end
+  end
+end

data/lib/loam/cron.rb

@@ -0,0 +1,98 @@
+require "set"
+
+module Loam
+  # A small, dependency-free "next run" calculator for a standard 5-field cron
+  # expression ("min hour dom month dow") plus an "interval:N" (every N seconds)
+  # form — same stdlib-only spirit as Loam::Totp / Loam::Base32. Timezone-aware;
+  # always returns UTC. Supports `*`, lists (`1,15`), ranges (`1-5`), and steps
+  # (`*/15`, `0-30/10`), and the classic cron day-of-month / day-of-week OR quirk
+  # (when BOTH are restricted, a match on either fires).
+  module Cron
+    RANGES = { min: 0..59, hour: 0..23, dom: 1..31, mon: 1..12, dow: 0..6 }.freeze
+    MAX_HORIZON = 4 # years to search before giving up (covers Feb-29 schedules)
+
+    module_function
+
+    # The next run strictly after `from`, evaluated in `zone`, returned in UTC.
+    def next_after(expr, from:, zone: "UTC")
+      expr = expr.to_s.strip
+
+      if expr.start_with?("interval:")
+        seconds = expr.split(":", 2).last.to_i
+        raise ArgumentError, "interval must be a positive number of seconds: #{expr.inspect}" unless seconds.positive?
+
+        return (from + seconds).utc
+      end
+
+      next_cron(expr, from, zone)
+    end
+
+    def next_cron(expr, from, zone)
+      fields = expr.split(/\s+/)
+      raise ArgumentError, "cron must have 5 fields (min hour dom month dow): #{expr.inspect}" unless fields.size == 5
+
+      min  = parse_field(fields[0], RANGES[:min])
+      hour = parse_field(fields[1], RANGES[:hour])
+      dom  = parse_field(fields[2], RANGES[:dom])
+      mon  = parse_field(fields[3], RANGES[:mon])
+      dow  = parse_field(fields[4], RANGES[:dow], dow: true)
+      dom_restricted = fields[2] != "*"
+      dow_restricted = fields[4] != "*"
+
+      time = from.in_time_zone(zone).change(sec: 0) + 60
+      limit = time + MAX_HORIZON.years
+
+      while time < limit
+        unless mon.include?(time.month) && day_matches?(time, dom, dow, dom_restricted, dow_restricted)
+          time = (time + 1.day).change(hour: 0, min: 0) # skip the whole non-matching day
+          next
+        end
+        return time.utc if hour.include?(time.hour) && min.include?(time.min)
+
+        time += 60
+      end
+
+      raise ArgumentError, "no cron match within #{MAX_HORIZON} years for #{expr.inspect}"
+    end
+
+    def day_matches?(time, dom, dow, dom_restricted, dow_restricted)
+      if dom_restricted && dow_restricted
+        dom.include?(time.day) || dow.include?(time.wday) # OR quirk
+      elsif dom_restricted
+        dom.include?(time.day)
+      elsif dow_restricted
+        dow.include?(time.wday)
+      else
+        true
+      end
+    end
+
+    # Parse one field into the set of matching integers.
+    def parse_field(field, range, dow: false)
+      values = Set.new
+
+      field.to_s.split(",").each do |part|
+        base, step = part.split("/", 2)
+        step = step ? Integer(step) : 1
+        raise ArgumentError, "bad step in #{part.inspect}" unless step.positive?
+
+        if base == "*"
+          lo, hi = range.min, range.max
+        elsif base.include?("-")
+          lo, hi = base.split("-", 2).map { |n| Integer(n) }
+        else
+          lo = hi = Integer(base)
+        end
+
+        (lo..hi).step(step) do |value|
+          value = 0 if dow && value == 7 # both 0 and 7 mean Sunday
+          raise ArgumentError, "value #{value} out of range for #{field.inspect}" unless range.include?(value)
+
+          values << value
+        end
+      end
+
+      values
+    end
+  end
+end

data/lib/loam/csv.rb

@@ -0,0 +1,18 @@
+module Loam
+  # CSV formula-injection defense. A cell whose value starts with =, +, -, @, or
+  # a tab/CR is treated as a FORMULA by Excel/Google Sheets when the file is
+  # opened — so `=cmd|...` or `=HYPERLINK(...)` in imported/exported data can run.
+  # Prefixing such a value with a single quote neutralizes it while leaving the
+  # visible text intact. Applied on every CSV cell Loam writes (export + the
+  # import error file).
+  module Csv
+    DANGEROUS = /\A[=+\-@\t\r]/
+
+    module_function
+
+    def safe(value)
+      string = value.to_s
+      string.match?(DANGEROUS) ? "'#{string}" : value
+    end
+  end
+end

data/lib/loam/current.rb

@@ -0,0 +1,21 @@
+require "active_support/current_attributes"
+
+module Loam
+  # Per-request (and per-job) execution context. Every tenant-scoped query,
+  # audit record, and published event reads from here.
+  class Current < ActiveSupport::CurrentAttributes
+    # config_cache memoizes resolved Loam::Configs values for the duration of
+    # one request/job, keyed by [key, tenant_id]. It resets with everything else
+    # here, so a value can never be read stale across requests.
+    #
+    # mutation_mode is the approval-gate seam (Loam::PendingActions): nil/:direct
+    # means writes commit normally; :confirm means a caller (an MCP tool acting
+    # for an AI agent) stages writes for human approval instead. It lives here so
+    # it is per-request and resets automatically.
+    # dictionary_cache memoizes resolved Loam::Dictionaries lookups for one
+    # request/job, keyed by [kind, key, tenant_id] — same posture as config_cache.
+    # locale is the current content-translation language (Loam::Translatable) —
+    # request state like tenant/actor, set in a before_action and reset here.
+    attribute :tenant, :actor, :config_cache, :mutation_mode, :dictionary_cache, :locale
+  end
+end