open-loam 0.1.0

data/lib/loam/widgets.rb

@@ -0,0 +1,77 @@
+module Loam
+  # 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|
+  #     { kind: "count", value: Rental.where(status: "open").count }   # tenant-scoped query
+  #   end
+  #
+  # The provider returns a small data hash (`{ kind: "count", value: }` or
+  # `{ kind: "list", items: [...] }`); the dashboard renders it generically.
+  # Widgets run tenant-scoped (query through tenant-scoped models), the `roles:`
+  # filter is enforced server-side (a hidden widget's data is NOT computed), and
+  # a raising provider is isolated into an error tile — the dashboard never breaks.
+  module Widgets
+    Widget = Struct.new(:key, :title, :roles, :provider, keyword_init: true) do
+      def visible_to?(role)
+        roles.nil? || Array(roles).map(&:to_s).include?(role.to_s)
+      end
+    end
+
+    class << self
+      def register(key:, title:, roles: nil, &block)
+        registry[key.to_s] = Widget.new(key: key.to_s, title: title, roles: roles, provider: block)
+        key.to_s
+      end
+
+      def registered = registry.values
+      def keys = registry.keys
+      def find(key) = registry[key.to_s]
+
+      def reset!
+        @registry = {}
+      end
+
+      # Resolve a widget for (actor, role): nil when it doesn't exist or the role
+      # 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
+
+        widget = find(key)
+        return nil unless widget&.visible_to?(role)
+
+        provider = Loam::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
+      # 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)
+                                   .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 }
+        end
+        register(key: "pending_approvals", title: "Pending approvals", roles: %w[manager]) do |_actor|
+          { kind: "count", value: Loam::PendingAction.pending.count }
+        end
+        register(key: "open_progress", title: "Running tasks") do |_actor|
+          { kind: "count", value: Loam::ProgressJob.where(status: "running").count }
+        end
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/loam/workflow.rb

@@ -0,0 +1,256 @@
+module Loam
+  # 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
+  #
+  #     workflow :status, initial: "draft" do
+  #       state "draft"
+  #       state "pending_approval"
+  #       state "approved"
+  #
+  #       transition :submit,  from: "draft",            to: "pending_approval"
+  #       transition :approve, from: "pending_approval", to: "approved", roles: [:manager]
+  #     end
+  #   end
+  #
+  #   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
+  #
+  # 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
+  # records it like any other change — a workflow adds no second audit trail.
+  module Workflow
+    extend ActiveSupport::Concern
+
+    # One declared move. `from` is a list because several states may share a
+    # move (e.g. cancel from draft OR pending_approval); `roles` empty means
+    # "not role-gated here" — the policy layer still gates the controller.
+    Transition = Struct.new(:name, :from, :to, :roles, keyword_init: true)
+
+    # The whole machine, frozen at class-definition time.
+    Definition = Struct.new(:column, :initial, :states, :transitions, keyword_init: true) do
+      def transitions_from(state)
+        transitions.each_value.select { |transition| transition.from.include?(state.to_s) }
+      end
+    end
+
+    # Collects the DSL block and validates the machine as a whole before
+    # freezing it. Validation runs at the end, so `state` and `transition` may
+    # appear in any order inside the block.
+    class Builder
+      def initialize(column, initial)
+        @column = column.to_s
+        @initial = initial&.to_s
+        @states = []
+        @transitions = {}
+      end
+
+      def state(name)
+        @states << name.to_s
+      end
+
+      def transition(name, from:, to:, roles: [])
+        @transitions[name.to_sym] = Transition.new(
+          name: name.to_sym,
+          from: Array(from).map(&:to_s).freeze,
+          to: to.to_s,
+          roles: Array(roles).map(&:to_sym).freeze
+        ).freeze
+      end
+
+      def build(&block)
+        instance_eval(&block)
+        validate!
+
+        Definition.new(
+          column: @column,
+          initial: @initial || @states.first,
+          states: @states.freeze,
+          transitions: @transitions.freeze
+        ).freeze
+      end
+
+      private
+
+      # A typo in a state name is a bug that would otherwise surface much
+      # later, as a transition that can never fire. Fail at class load.
+      def validate!
+        raise Error, "workflow #{@column} declares no states" if @states.empty?
+
+        undeclared = @transitions.each_value.flat_map { |t| t.from + [t.to] }.uniq - @states
+        if undeclared.any?
+          raise Error, "workflow #{@column} moves to/from undeclared states: #{undeclared.join(', ')} " \
+                       "(declare each one with `state \"name\"`)"
+        end
+
+        return if @initial.nil? || @states.include?(@initial)
+
+        raise Error, "workflow #{@column} initial state #{@initial.inspect} is not a declared state"
+      end
+    end
+
+    included do
+      # nil until `workflow` is called; inherited by subclasses.
+      class_attribute :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
+      # 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
+    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
+
+        before_validation on: :create do
+          self[definition.column] = definition.initial if self[definition.column].blank?
+        end
+
+        # A workflow column may only ever hold a declared state, whoever writes
+        # it — a transition, a form, a console.
+        validates definition.column,
+                  inclusion: { in: definition.states, message: "is not one of: #{definition.states.join(', ')}" }
+
+        include 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)
+        model = self
+
+        Module.new do
+          definition.transitions.each_value do |transition|
+            define_method("#{transition.name}!") { loam_perform_transition!(transition) }
+          end
+
+          definition.states.each do |state|
+            predicate = "#{state}?"
+            next unless model.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
+            # on a warmed-up dev machine.
+            define_method(predicate) do
+              if self.class.columns_hash.key?(state)
+                query_attribute(state)
+              else
+                self[definition.column].to_s == state
+              end
+            end
+          end
+        end
+      end
+
+      # 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)
+        !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
+    # decide which buttons to render.
+    def workflow_transitions_available
+      role = loam_workflow_role
+
+      self.class.loam_workflow.transitions_from(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
+    end
+
+    private
+
+    def loam_workflow_column_only_via_transition
+      return unless self.class.loam_workflow
+
+      column = self.class.loam_workflow.column
+      return unless attribute_changed?(column)
+      return if @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
+
+      unless transition.from.include?(from)
+        raise InvalidTransitionError,
+              "#{self.class.name}##{transition.name}! moves #{transition.from.join('/')} -> #{transition.to}, " \
+              "but this record is #{from.inspect}"
+      end
+
+      loam_authorize_transition!(transition)
+
+      self[self.class.loam_workflow.column] = transition.to
+      begin
+        @loam_in_transition = true # tells the guard THIS column change is blessed
+        save!
+      ensure
+        @loam_in_transition = false
+      end
+
+      Loam::Events.publish(
+        "#{loam_workflow_event_domain}.#{model_name.param_key}.#{transition.name}",
+        id: id, from: from, to: transition.to
+      )
+
+      self
+    end
+
+    def loam_authorize_transition!(transition)
+      return if transition.roles.empty?
+
+      allowed = transition.roles.join(", ")
+      unless Loam::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) { ... }"
+      end
+
+      return if transition.roles.include?(loam_workflow_role)
+
+      raise NotAuthorizedError,
+            "#{self.class.name}##{transition.name}! is restricted to #{allowed}; " \
+            "this actor's role is #{loam_workflow_role.inspect}"
+    end
+
+    # Role resolution deliberately goes through Loam::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
+    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"
+    end
+  end
+end

data/lib/loam.rb

@@ -0,0 +1,122 @@
+require "loam/version"
+require "loam/errors"
+require "loam/current"
+require "loam/events"
+require "loam/policy"
+require "loam/lifecycle"
+require "loam/configs"
+require "loam/features"
+require "loam/auth_throttle"
+require "loam/dictionaries"
+require "loam/custom_field_index"
+require "loam/undo"
+require "loam/permissions"
+require "loam/telemetry"
+require "loam/eval"
+require "loam/mcp"
+require "loam/mcp/server"
+require "loam/progress"
+require "loam/cron"
+require "loam/scheduler"
+require "loam/csv"
+require "loam/export"
+require "loam/import"
+require "loam/bulk"
+require "loam/widgets"
+require "loam/dashboard"
+require "loam/overrides"
+require "loam/open_api"
+require "loam/encryption"
+require "loam/base32"
+require "loam/totp"
+require "loam/pending_actions"
+require "loam/perspectives"
+require "loam/record_locks"
+require "loam/event_stream"
+require "loam/enrichers"
+require "loam/search"
+require "loam/search/driver"
+require "loam/search/like_driver"
+require "loam/search/token_driver"
+require "loam/notifications"
+require "loam/sso"
+require "loam/business_rules"
+require "loam/webhooks"
+require "loam/inbound_webhooks"
+require "loam/durable_events"
+require "loam/engine" if defined?(Rails::Engine)
+
+module Loam
+  # 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
+  # Loam::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 && Loam::Membership.find_by(user_id: Current.actor.id)&.role
+    Loam::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
+  # Loam::PendingActions.stage instead of committed. Loam 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 "loam/generated_key"
+  require "loam/tenant_record"
+  require "loam/auditable"
+  require "loam/soft_deletable"
+  require "loam/eventful"
+  require "loam/custom_fields"
+  require "loam/workflow"
+  require "loam/searchable"
+  require "loam/encryptable"
+  require "loam/translatable"
+  require "loam/commentable"
+  require "loam/attachable"
+end

data/lib/open-loam.rb

@@ -0,0 +1,5 @@
+# Bundler auto-requires the gem's name ("open-loam") on load. The library's
+# entry point and whole namespace are `loam` / `Loam::` — the gem is only
+# *distributed* as open-loam (the plain `loam` name is taken on RubyGems). This
+# shim bridges the two so `gem "open-loam"` works with the default require.
+require_relative "loam"

data/lib/tasks/loam.rake

@@ -0,0 +1,171 @@
+namespace :loam do
+  desc "Re-run every Loam.on_tenant_created callback for every existing tenant (idempotent)"
+  task sync: :environment do
+    synced = Loam.sync_tenants!
+    puts "loam:sync — ran #{Loam.tenant_created_callbacks.size} tenant callback(s) across #{synced} tenant(s)."
+  end
+
+  namespace :openapi do
+    # Write the OpenAPI 3.1 document + a Markdown rendering to disk, for CI or
+    # publishing. Introspection only — no server, no network.
+    #
+    #   bin/rails loam:openapi:export
+    desc "Export the API's OpenAPI JSON + Markdown to doc/"
+    task export: :environment do
+      require "json"
+      dir = ENV["DIR"].presence || "doc"
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "openapi.json"), JSON.pretty_generate(Loam::OpenApi.document))
+      File.write(File.join(dir, "openapi.md"), Loam::OpenApi.markdown)
+      puts "loam:openapi:export — wrote #{dir}/openapi.json and #{dir}/openapi.md."
+    end
+  end
+
+  namespace :scheduler do
+    # Fire every due recurring job once. Wire to system cron, every minute:
+    #   * * * * * cd /app && bin/rails loam:scheduler:tick
+    # The claim is atomic, so running this from several hosts never double-fires
+    # a job (Postgres SKIP LOCKED; SQLite serializes the single-process claim).
+    desc "Enqueue every due Loam::ScheduledJob (run from cron)"
+    task tick: :environment do
+      fired = Loam::Scheduler.tick
+      puts "loam:scheduler:tick — fired #{fired} scheduled job(s)."
+    end
+  end
+
+  namespace :index do
+    # Rebuild the custom-field read-model index (Loam::CustomFieldIndex) for every
+    # entity with custom fields, in every tenant. Run once after enabling it so
+    # existing rows are projected; new/updated records index themselves on save.
+    #
+    #   bin/rails loam:index:reindex
+    desc "Rebuild the custom-field read-model index for every model in every tenant"
+    task reindex: :environment do
+      Rails.application.eager_load!
+      models = Loam::TenantRecord.descendants.select do |model|
+        model.name.present? && model.respond_to?(:custom_field_definitions)
+      end
+
+      tenants = 0
+      Loam::Tenant.find_each do |tenant|
+        Loam.as_tenant(tenant) { models.each { |model| Loam::CustomFieldIndex.reindex(model) } }
+        tenants += 1
+      end
+      puts "loam:index:reindex — rebuilt #{models.size} model(s) across #{tenants} tenant(s)."
+    end
+
+    # Report custom-field index coverage (indexed vs expected) per model/field
+    # per tenant — the trust signal for whether the index is complete or drifting.
+    #
+    #   bin/rails loam:index:coverage
+    desc "Report custom-field index coverage per model/field per tenant"
+    task coverage: :environment do
+      Rails.application.eager_load!
+      models = Loam::TenantRecord.descendants.select do |model|
+        model.name.present? && model.respond_to?(:custom_field_definitions)
+      end
+
+      Loam::Tenant.find_each do |tenant|
+        Loam.as_tenant(tenant) do
+          models.each do |model|
+            model.custom_field_definitions.find_each do |definition|
+              c = Loam::CustomFieldIndex.coverage(model, definition.name)
+              flag = c[:complete] ? "ok" : "GAP"
+              puts "  [#{flag}] #{tenant.slug} #{model.name}.#{definition.name}: #{c[:indexed]}/#{c[:expected]} indexed"
+            end
+          end
+        end
+      end
+    end
+  end
+
+  namespace :search do
+    # Rebuild the active driver's search index for every searchable model in
+    # every tenant. Needed once after switching to a driver that keeps an index
+    # (Loam::Search::TokenDriver): existing rows have no tokens until reindexed,
+    # while new and updated records index themselves on save. A no-op under the
+    # default LikeDriver (its reindex does nothing), so it is always safe to run.
+    #
+    #   bin/rails loam:search:reindex
+    desc "Rebuild the search index for every searchable model in every tenant"
+    task reindex: :environment do
+      Rails.application.eager_load!
+      models = Loam::TenantRecord.descendants.select do |model|
+        model.name.present? && model.respond_to?(:loam_searchable?) && model.loam_searchable?
+      end
+
+      tenants = 0
+      Loam::Tenant.find_each do |tenant|
+        Loam.as_tenant(tenant) { models.each { |model| Loam::Search.reindex(model) } }
+        tenants += 1
+      end
+      puts "loam:search:reindex — rebuilt #{models.size} model(s) across #{tenants} tenant(s) using #{Loam::Search.driver}."
+    end
+  end
+
+  namespace :encryption do
+    # Rotate a tenant's encrypted data under the current key: read each record's
+    # encrypted fields (old key) and re-seal them (new key), one record at a
+    # time. The version tag in the stored format means old and new ciphertext
+    # coexist, so this can run incrementally without downtime. Each record is an
+    # ordinary audited "[encrypted]" update.
+    #
+    #   bin/rails loam:encryption:rotate[Customer,42]
+    desc "Re-encrypt a model's encrypted fields for one tenant (rotation step)"
+    task :rotate, %i[model tenant_id] => :environment do |_task, args|
+      model = fetch_encryptable_model(args[:model])
+      tenant = Loam::Tenant.find(args[:tenant_id])
+
+      count = 0
+      Loam.as_tenant(tenant) do
+        each_record(model) do |record|
+          record.loam_reencrypt!
+          count += 1
+        end
+      end
+      puts "loam:encryption:rotate — re-encrypted #{count} #{model.name} record(s) in tenant #{tenant.slug}."
+    end
+
+    # Decrypt and print one tenant's encrypted fields, e.g. for a GDPR data
+    # export or a migration. OPERATIONAL CAUTION: this prints plaintext PII to
+    # stdout — run it only where that output is safe (never into shared logs or
+    # a shell history that syncs), and only for a tenant you are authorized to
+    # export.
+    #
+    #   bin/rails loam:encryption:decrypt_dump[Customer,42]
+    desc "Print decrypted encrypted-field values for one tenant (GDPR export; handle with care)"
+    task :decrypt_dump, %i[model tenant_id] => :environment do |_task, args|
+      require "json"
+      model = fetch_encryptable_model(args[:model])
+      tenant = Loam::Tenant.find(args[:tenant_id])
+      fields = model.loam_encrypted_attributes
+
+      Loam.as_tenant(tenant) do
+        each_record(model) do |record|
+          row = { id: record.id }.merge(fields.index_with { |field| record.public_send(field) })
+          puts row.to_json
+        end
+      end
+    end
+  end
+end
+
+# Resolve a model name to a class that actually uses Loam::Encryptable — a typo
+# or a plain model should fail loudly, not silently dump/rotate nothing.
+def fetch_encryptable_model(name)
+  # Force the app's classes (and Loam::TenantRecord, required lazily via the
+  # active_record on_load hook) to load before we constantize a model name.
+  Rails.application.eager_load!
+  model = name.to_s.constantize
+  unless model.respond_to?(:loam_encrypted_attributes) && model.loam_encrypted_attributes.any?
+    abort "#{name} does not `include Loam::Encryptable` with any `encrypts` fields."
+  end
+  model
+end
+
+# Iterate every record, soft-deleted ones included (a GDPR export must not miss
+# data hidden in the recycle bin), staying inside the current tenant scope.
+def each_record(model, &block)
+  scope = model.respond_to?(:with_deleted) ? model.with_deleted : model.all
+  scope.find_each(&block)
+end

data/lib/tasks/loam_eval.rake

@@ -0,0 +1,32 @@
+require "json"
+require "fileutils"
+
+namespace :loam do
+  # Score the app's current test suite as a golden-task eval result and record it
+  # under ai/benchmark_runs/ (L-303). Run this in a Loam app AFTER an agent (or
+  # you) has implemented a golden task:
+  #
+  #   bin/rails "loam:eval[2]"                       # task 2, tests only
+  #   bin/rails "loam:eval[2,tenancy_leak:unscoped]" # note an invariant breach
+  #
+  # Exits non-zero if the task did not pass, so it drops straight into CI.
+  desc "Score the current test suite as a golden-task eval result (loam:eval[task,violation,violation,...])"
+  task :eval, [ :task ] => :environment do |_task, args|
+    task_id = args[:task] || "unspecified"
+    violations = args.extras # any positional args after the task id are violations
+
+    output = `bin/rails test 2>&1`
+    summary = Loam::Eval.parse_summary(output)
+    card = Loam::Eval.scorecard(task: task_id, summary: summary, violations: violations)
+
+    dir = Rails.root.join("ai", "benchmark_runs")
+    FileUtils.mkdir_p(dir)
+    stamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+    file = dir.join("eval-#{task_id}-#{stamp}.json")
+    File.write(file, JSON.pretty_generate(card))
+
+    puts JSON.pretty_generate(card)
+    puts "Recorded #{file}"
+    abort("Eval FAILED for task #{task_id}") unless card[:passed]
+  end
+end

data/lib/tasks/loam_mcp.rake

@@ -0,0 +1,20 @@
+require "logger"
+
+namespace :loam do
+  namespace :mcp do
+    # Serve the Loam MCP server over stdio. Point an MCP client (Claude Code,
+    # Cursor, Codex) at `bin/rails loam:mcp:serve` with LOAM_MCP_TOKEN set to a
+    # Loam API token — the agent then acts as that token's user, in that tenant.
+    #
+    # stdout carries JSON-RPC only; every log is sent to stderr so it can't
+    # corrupt the stream.
+    desc "Serve the Loam MCP server over stdio (auth via LOAM_MCP_TOKEN)"
+    task serve: :environment do
+      Rails.logger = Logger.new($stderr)
+      ActiveRecord::Base.logger = Rails.logger
+      $stdout.sync = true
+
+      Loam::Mcp::Server.new.run
+    end
+  end
+end