open-loam 0.1.0

data/lib/generators/loam/install/templates/inbound_webhooks_controller.rb

@@ -0,0 +1,17 @@
+# Public endpoint that receives webhooks FROM external systems at
+# /webhooks/:token. No session, no bearer token: the HMAC signature is the auth
+# (ActionController::API, so there is no CSRF to skip). All the verified,
+# replay-resistant work lives in Loam::InboundWebhooks.ingest; this controller
+# only maps its Result to an HTTP status and never leaks tenant context to the
+# next request on this thread.
+class InboundWebhooksController < ActionController::API
+  def receive
+    result = Loam::InboundWebhooks.ingest(
+      token: params[:token], raw_body: request.raw_post, headers: request.headers
+    )
+    Rails.logger.info("[loam inbound] #{result.status} #{result.reason}") if result.status >= 400
+    head result.status
+  ensure
+    Loam::Current.reset
+  end
+end

data/lib/generators/loam/install/templates/initializer.rb

@@ -0,0 +1,218 @@
+# Loam configuration, tenant lifecycle hooks, and domain event subscriptions.
+
+# Master key for field encryption at rest (Loam::Encryptable). Per-tenant keys
+# are derived from it via HKDF, so it must be STABLE and SECRET — never commit it.
+# Set LOAM_MASTER_KEY in the environment (or wire Rails.application.credentials)
+# to a high-entropy value, e.g. `SecureRandom.hex(32)`. Only apps that actually
+# `encrypts` a field need it; encryption raises a clear error if it is missing.
+#
+#   Loam::Encryption.master_key = ENV.fetch("LOAM_MASTER_KEY")
+#
+# Rotating the key without re-encrypting orphans existing ciphertext — see
+# `bin/rails loam:encryption:rotate[Model,tenant_id]`.
+
+# Roles every tenant of this app is expected to have. A registry read by your
+# own seeding/admin code — Loam does not create memberships for you, because
+# who gets which role is business logic.
+Loam.default_roles = %w[manager employee]
+
+# Locales that CONTENT translations (Loam::Translatable) may be authored in — the
+# admin's language switcher and the per-record Translations screen offer these.
+# The first is the base/default; the rest overlay onto it. This is for user data
+# (a product name), NOT developer UI strings — those stay Rails i18n. Loam ships
+# a `loam.*` base locale (English) for its own chrome; the admin switcher sets
+# I18n.locale too, so add `config/locales/loam.pl.yml` (etc.) to translate the UI
+# for each locale you list here.
+Loam.locales = %w[en]
+
+# Observability (Loam::Telemetry). By default Loam wraps its async hot paths
+# (scheduler tick, durable event delivery, inbound webhook ingest) in spans that
+# emit ActiveSupport::Notifications events ("loam.span.*") — subscribe to those,
+# or plug a real tracer in here:
+#
+#   Loam::Telemetry.backend = ->(name, attributes, work) do
+#     OpenTelemetry.tracer_provider.tracer("loam").in_span(name, attributes: attributes.transform_keys(&:to_s)) { work.call }
+#   end
+
+# Feature-string permissions (Loam::Permissions) — a finer capability layer under
+# the coarse role. Deny-by-default; `*` grants everything, a trailing `.*` is a
+# prefix ("equipment.*"). Check with `Loam.can?("equipment.edit")`,
+# `require_permission!("...")` in a controller, or the `can?` view helper.
+# Orthogonal to roles (Loam::Membership) and field-level policies (Loam::Policy).
+#
+#   Loam::Permissions.configure do
+#     role :admin,   allow: "*"
+#     role :manager, allow: %w[equipment.* billing.read]
+#     role :clerk,   allow: %w[equipment.read]
+#   end
+
+# Customization WITHOUT forking (Loam::Overrides): disable or replace an entry in
+# one of Loam's keyed registries (:widgets, :broadcast_events). A stale override
+# (a key that no longer exists) is warned about at boot by `check!`, so a
+# typo'd override is visible instead of silently doing nothing.
+#
+#   Loam::Overrides.disable(:widgets, "open_progress")   # drop a built-in widget
+#   Loam::Overrides.replace(:widgets, "audit_recent") { |actor| { kind: "count", value: 0 } }
+#   Loam::Overrides.disable(:broadcast_events, "loam.progress.")  # stop pushing it over SSE
+#
+# BOUNDARY: this is only for Loam's in-gem registries. Override a VIEW, CONTROLLER,
+# or ROUTE the standard Rails way (create a file at the same path to shadow the
+# engine's, or `prepend` a module) — not here.
+
+# Events pushed live to the browser over SSE (Loam::EventStream). Default off; the
+# notification pattern is enabled here so the admin bell increments without a
+# reload. Add patterns (e.g. "billing.") to stream domain events to live widgets —
+# nothing reaches the browser unless it matches a pattern here (security posture).
+Loam.broadcast_events = [ "loam.notification.", "loam.progress." ]
+
+# Response enrichers (Loam::Enrichers): attach a computed block onto ANOTHER
+# module's entity in admin/API responses, with no foreign-key coupling — billing
+# can annotate an Equipment without Equipment knowing billing exists. Pass a
+# `batch:` resolver (array -> { id => value }) so an index stays one query, not N.
+#
+#   Loam::Enrichers.register("Equipment", key: "outstanding_balance", batch: ->(equipments) do
+#     totals = Invoice.where(equipment_id: equipments.map(&:id)).group(:equipment_id).sum(:balance)
+#     equipments.map(&:id).index_with { |id| totals.fetch(id, 0) }
+#   end)
+
+# Search backend (Loam::Search). The default is a substring LIKE — portable and
+# zero-setup. Opt into the word-level TokenDriver (also portable, no external
+# service: it keeps a normalized-token index in loam_search_tokens) for
+# order-independent, whole-word matching. `searchable_by` and every
+# `Model.search(q)` call site are UNCHANGED — only this line differs; an external
+# engine (Meilisearch/Elasticsearch) is a third driver behind the same seam.
+# After switching, backfill existing rows once with `bin/rails loam:search:reindex`
+# (new and updated records index themselves on save).
+#
+#   Loam::Search.driver = Loam::Search::TokenDriver
+
+# Custom-field read-model index (Loam::CustomFieldIndex). Filtering/sorting on a
+# custom field is index-backed (a typed projection in loam_custom_field_values)
+# instead of a per-row JSON scan. Records project themselves on save; backfill
+# existing data once with `bin/rails loam:index:reindex` (or
+# `Loam::CustomFieldIndex.reindex(Model)`). Query with
+# `Loam::CustomFieldIndex.filter(Model, field_key, op, value)` — the generated
+# entity index routes a `cf_field`/`cf_op`/`cf_value` filter through it.
+
+# Single sign-on (Loam::Sso). OIDC is shipped end-to-end: configure a per-tenant
+# provider under /admin/sso_providers (issuer, client_id, client_secret, email
+# domain, default JIT role). Home-realm discovery routes a user to their tenant's
+# IdP by email domain; a verified identity is JIT-provisioned or linked to an
+# existing User. The client_secret is encrypted at rest, so LOAM_MASTER_KEY must
+# be set (same key as the rest of Loam::Encryptable). SAML and SCIM are documented
+# seams (see docs/_foundation/overview.md). Nothing to register here for real OIDC.
+#
+# In tests, inject the offline fake so the flow never hits the network:
+#
+#   Loam::Sso.builder = ->(record, redirect_uri) { Loam::Sso::FakeProvider.new(record, redirect_uri: redirect_uri) }
+
+# Roles that MUST use two-factor auth (Loam::MfaCredential). At login, a user
+# whose role in the chosen tenant is on this list and who has not enrolled is
+# sent to set MFA up before they can work. Resolved via Loam::Configs, so it can
+# be a global default or a per-tenant override; empty means MFA is optional.
+#
+#   Loam::Configs.set("security.mfa_required_roles", ["manager"], scope: :global)
+#
+# Auth rate-limiting / lockout (Loam::AuthThrottle) guards failed password/TOTP/
+# sudo attempts. Defaults: lock after 10 failures within a 15-minute window.
+# Tune via Loam::Configs (global or per-tenant):
+#
+#   Loam::Configs.set("security.max_auth_attempts",   5,  scope: :global)
+#   Loam::Configs.set("security.auth_window_minutes", 10, scope: :global)
+#
+# Rack::Attack (with a cache store) is the production-scale path across multiple
+# processes; the built-in DB counter is the portable single-process default.
+
+# App-wide setting defaults (Loam::Configs). A key resolves override → global
+# row → this declared default, so declaring one here needs no migration and no
+# row — a tenant reads the default until someone overrides it in the admin
+# Settings screen (/admin/configs). Values keep their type (bool/number/string/
+# hash), and a per-tenant override never leaks to another tenant.
+#
+#   Loam.config_defaults = { "billing.currency" => "USD", "billing.net_terms" => 30 }
+#
+# To change the company-wide baseline at runtime (not per tenant), write a
+# global row: `Loam::Configs.set("billing.currency", "EUR", scope: :global)`.
+
+# Feature flags (Loam::Features). Declare known capabilities and their default
+# state; a flag with no row resolves to its declared default, and managers flip
+# a tenant's override at /admin/features. A flag gates a CAPABILITY (is this on
+# for the tenant), orthogonal to roles/policies, which gate a PERSON.
+#
+#   Loam.feature_defaults = {
+#     "beta_dashboard" => { default: false, description: "New dashboard, rolled out per tenant." }
+#   }
+#
+# In a controller: `require_feature!(:beta_dashboard)` (404s when off); in a
+# view: `<%% if feature_on?(:beta_dashboard) %>`. Flip app-wide with
+# `Loam::Features.enable(:beta_dashboard, scope: :global)`.
+
+# What a brand-new tenant gets for free. Registered at file scope on purpose:
+# inside `to_prepare` this would re-register on every code reload.
+Loam.on_tenant_created do |tenant|
+  # Seed roles/defaults for a new tenant here. MUST be idempotent —
+  # `bin/rails loam:sync` re-runs these for every existing tenant, which is how
+  # a default added in a later release reaches tenants that already exist.
+  # Use find_or_create_by!, never create!. The block runs inside
+  # Loam.as_tenant(tenant), so tenant-scoped writes need no extra ceremony.
+  #
+  # Baseline managed lookup lists (Loam::Dictionary) — a FieldDefinition of type
+  # "dictionary" can then point a custom field at the key, rendering a select:
+  #
+  #   severity = Loam::Dictionary.find_or_create_by!(key: "damage_severity") { |d| d.name = "Damage severity" }
+  #   [%w[minor Minor], %w[major Major], %w[critical Critical]].each_with_index do |(value, label), i|
+  #     severity.entries.find_or_create_by!(value: value) { |e| e.label = label; e.position = i }
+  #   end
+
+  # Materialize the registered tenant-scope schedules (see Loam::Scheduler.register
+  # below) as rows for this tenant. A no-op until you register one.
+  Loam::Scheduler.sync_tenant(tenant)
+end
+
+# Recurring jobs (Loam::Scheduler). Register default schedules here at file scope;
+# on_tenant_created materializes the tenant-scope ones per tenant. A "tenant" job
+# is enqueued with `tenant_id:` (establish it with Loam.as_tenant); a "system" job
+# runs once with no tenant. job_class MUST be a real ActiveJob (validated — never
+# arbitrary code). Wire the runner to system cron, every minute:
+#
+#   * * * * * cd /path/to/app && bin/rails loam:scheduler:tick
+#
+# The claim is atomic, so running it from several hosts never double-fires a job.
+#
+#   Loam::Scheduler.register(key: "nightly_digest", name: "Nightly digest",
+#                            job_class: "DigestJob", schedule: "0 7 * * *", scope: "tenant")
+#
+# Only ALLOWLISTED job classes are schedulable (a registered one, or one listed
+# here) — so a tenant admin can't schedule ActiveStorage::PurgeJob or a mailer:
+#
+#   Loam.schedulable_jobs = %w[DigestJob ReindexJob]
+
+# Domain event subscriptions. Subscribe to a single event or a whole domain
+# (trailing dot = prefix). Register them here at file scope, not inside
+# `to_prepare`: subscriptions are global, so a reload would add a second copy
+# of each one and every event would be handled twice.
+#
+#   Loam::Events.subscribe("billing.subscription.renewed") do |name, payload|
+#     BillingMailer.renewal_receipt(payload[:id]).deliver_later
+#   end
+#
+#   Loam::Events.subscribe("rental.") do |name, payload|
+#     Rails.logger.info("[loam event] #{name} #{payload.inspect}")
+#   end
+#
+# Event -> in-app notification is the intended pattern for telling someone
+# something. The subscriber runs in the publisher's tenant context, so the
+# notification lands in the right tenant with no extra ceremony:
+#
+#   Loam::Events.subscribe("rental.damage_report.approve") do |_name, payload|
+#     Loam::Notifications.notify_role(:manager, title: "Damage report approved")
+#   end
+
+# Business rules (Loam::BusinessRule) are the admin-editable cousin of the
+# subscriptions above: a manager declares, per tenant, WHEN a condition holds on
+# a triggering record THEN run a fixed vocabulary of safe actions (notify,
+# emit_event, set_field, block_transition). The condition is DATA — a
+# whitelisted {field, op, value} tree, never evaluated as code — so a tenant
+# admin can wire up automation without a deploy and without a code-injection
+# surface. The engine subscribes itself at boot; nothing to register here.
+# Manage rules under /admin/business_rules and see why they fired in the run log.

data/lib/generators/loam/install/templates/migrations/create_loam_api_tokens.rb

@@ -0,0 +1,15 @@
+class CreateLoamApiTokens < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_api_tokens<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.references :user, null: false, foreign_key: true<%= loam_type_option %>
+      t.string :token, null: false
+      t.string :label
+      t.datetime :last_used_at
+      t.timestamps
+    end
+    # Tokens are looked up before a tenant is known, so the uniqueness that
+    # matters is global.
+    add_index :loam_api_tokens, :token, unique: true
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_audit_records.rb

@@ -0,0 +1,14 @@
+class CreateLoamAuditRecords < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_audit_records<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :auditable_type, null: false
+      t.<%= loam_key_column_type %> :auditable_id<%= loam_key_limit_option %>, null: false
+      t.string :action, null: false
+      t.<%= loam_key_column_type %> :actor_id<%= loam_key_limit_option %>
+      t.text :changeset
+      t.timestamps
+    end
+    add_index :loam_audit_records, %i[tenant_id auditable_type auditable_id]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_auth_attempts.rb

@@ -0,0 +1,11 @@
+class CreateLoamAuthAttempts < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_auth_attempts<%= loam_id_option %> do |t|
+      t.string :identifier, null: false   # the submitted login (normalized), NOT tenant-scoped
+      t.string :kind, null: false         # password / totp / recovery / sudo
+      t.string :ip                        # nullable; for an optional per-ip throttle
+      t.timestamps
+    end
+    add_index :loam_auth_attempts, %i[identifier created_at]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_business_rules.rb

@@ -0,0 +1,29 @@
+class CreateLoamBusinessRules < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_business_rules<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :name, null: false
+      t.string :entity_type              # the entity this rule watches (nil = event-only)
+      t.string :trigger, null: false     # an event pattern (Loam::Events.pattern_matches?)
+      t.json :condition, null: false, default: {}   # a safe condition tree (data, never code)
+      t.json :actions, null: false, default: []     # an ordered list of typed action descriptors
+      t.boolean :active, null: false, default: true
+      t.integer :priority, null: false, default: 0
+      t.timestamps
+    end
+    add_index :loam_business_rules, %i[tenant_id active]
+
+    create_table :loam_business_rule_runs<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.references :business_rule, null: false, foreign_key: { to_table: :loam_business_rules }<%= loam_type_option %>
+      t.string :subject_type
+      t.<%= loam_key_column_type %> :subject_id<%= loam_key_limit_option %>
+      t.string :event_name
+      t.boolean :matched, null: false, default: false
+      t.json :actions_taken, null: false, default: []
+      t.text :error
+      t.timestamps
+    end
+    add_index :loam_business_rule_runs, %i[tenant_id business_rule_id created_at]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_comments.rb

@@ -0,0 +1,13 @@
+class CreateLoamComments < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_comments<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :commentable_type, null: false
+      t.<%= loam_key_column_type %> :commentable_id<%= loam_key_limit_option %>, null: false
+      t.references :author, null: false, foreign_key: { to_table: :users }<%= loam_type_option %>
+      t.text :body, null: false
+      t.timestamps
+    end
+    add_index :loam_comments, %i[tenant_id commentable_type commentable_id]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_configs.rb

@@ -0,0 +1,21 @@
+class CreateLoamConfigs < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_configs<%= loam_id_option %> do |t|
+      t.string :key, null: false
+      # Nullable: a NULL tenant_id is the GLOBAL row; a set one is a per-tenant
+      # override. So this is NOT a tenant-scoped table.
+      t.references :tenant, null: true, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      # Any JSON-able value under one key. Nullable on purpose: row existence is
+      # the "is it set" signal, and JSON null is itself a storable value.
+      t.json :value_json
+      t.timestamps
+    end
+
+    # One global row per key (partial: only where there is no tenant).
+    add_index :loam_configs, :key, unique: true, where: "tenant_id IS NULL",
+              name: "index_loam_configs_global_key"
+    # One override row per key per tenant.
+    add_index :loam_configs, %i[key tenant_id], unique: true,
+              name: "index_loam_configs_on_key_and_tenant"
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_custom_field_values.rb

@@ -0,0 +1,19 @@
+class CreateLoamCustomFieldValues < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_custom_field_values<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :indexable_type, null: false
+      t.<%= loam_key_column_type %> :indexable_id<%= loam_key_limit_option %>, null: false
+      t.string :field_key, null: false
+      t.text :value_text                # canonical string form (contains/present/eq)
+      t.decimal :value_number           # integer/decimal fields (range queries)
+      t.boolean :value_boolean          # boolean fields
+      t.datetime :value_datetime        # date/datetime fields
+      t.timestamps
+    end
+    add_index :loam_custom_field_values, %i[indexable_type indexable_id field_key],
+              unique: true, name: "index_loam_cfv_unique"
+    add_index :loam_custom_field_values, %i[tenant_id indexable_type field_key value_text], name: "index_loam_cfv_text"
+    add_index :loam_custom_field_values, %i[tenant_id indexable_type field_key value_number], name: "index_loam_cfv_number"
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_dashboard_widgets.rb

@@ -0,0 +1,12 @@
+class CreateLoamDashboardWidgets < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_dashboard_widgets<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :widget_key, null: false   # a registered Loam::Widgets key
+      t.integer :position, null: false, default: 0
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    add_index :loam_dashboard_widgets, %i[tenant_id widget_key], unique: true
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_dictionaries.rb

@@ -0,0 +1,11 @@
+class CreateLoamDictionaries < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_dictionaries<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :key, null: false   # the code the field def / API references (e.g. "damage_severity")
+      t.string :name, null: false  # human label for the list
+      t.timestamps
+    end
+    add_index :loam_dictionaries, %i[tenant_id key], unique: true
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_dictionary_entries.rb

@@ -0,0 +1,18 @@
+class CreateLoamDictionaryEntries < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_dictionary_entries<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.references :dictionary, null: false, foreign_key: { to_table: :loam_dictionaries }<%= loam_type_option %>
+      t.string :value, null: false                    # the stored code
+      t.string :label, null: false                    # display text
+      t.string :color                                 # optional hex
+      t.string :icon                                  # optional icon name
+      t.integer :position, null: false, default: 0    # ordering
+      t.boolean :is_default, null: false, default: false
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    add_index :loam_dictionary_entries, %i[dictionary_id value], unique: true
+    add_index :loam_dictionary_entries, %i[tenant_id dictionary_id position]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_event_deliveries.rb

@@ -0,0 +1,17 @@
+class CreateLoamEventDeliveries < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_event_deliveries<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :subscriber_key, null: false            # a registered Loam::DurableEvents subscriber
+      t.string :event_name, null: false
+      t.json :payload, null: false                     # JSON-scalar event payload
+      t.string :status, null: false, default: "pending" # pending | delivered | dead
+      t.integer :attempts, null: false, default: 0
+      t.text :last_error
+      t.datetime :next_attempt_at                      # backoff gate for the next retry
+      t.datetime :delivered_at
+      t.timestamps
+    end
+    add_index :loam_event_deliveries, %i[tenant_id status next_attempt_at]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_field_definitions.rb

@@ -0,0 +1,15 @@
+class CreateLoamFieldDefinitions < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_field_definitions<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :entity_type, null: false
+      t.string :name, null: false
+      t.string :field_type, null: false
+      t.json :writable_roles, default: [], null: false
+      t.json :readable_roles, default: [], null: false  # empty = any member may read (used by the index oracle guard)
+      t.json :config, null: false, default: {}  # type-specific settings (e.g. a dictionary field's key)
+      t.timestamps
+    end
+    add_index :loam_field_definitions, %i[tenant_id entity_type name], unique: true, name: "index_loam_field_definitions_on_tenant_entity_name"
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_inbound_webhooks.rb

@@ -0,0 +1,31 @@
+class CreateLoamInboundWebhooks < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_inbound_webhook_sources<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :name, null: false
+      t.string :token, null: false                 # unguessable URL id: /webhooks/:token
+      t.string :secret, null: false                # HMAC key (authenticates the call)
+      t.string :signature_header, null: false, default: "X-Loam-Signature"
+      t.string :delivery_id_header                 # optional: external delivery-id for dedupe
+      t.string :timestamp_header                   # optional: enables the freshness window
+      t.integer :timestamp_tolerance               # seconds; nil = default 300
+      t.string :event_name, null: false            # what to publish on the bus
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    add_index :loam_inbound_webhook_sources, :token, unique: true
+
+    create_table :loam_inbound_webhook_deliveries<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.references :source, null: false, foreign_key: { to_table: :loam_inbound_webhook_sources }<%= loam_type_option %>
+      t.string :external_id, null: false           # delivery-id header, or a body hash
+      t.string :event_name, null: false
+      t.string :status, null: false, default: "received"
+      t.datetime :received_at
+      t.json :payload, null: false
+      t.timestamps
+    end
+    # The idempotency ledger: a replayed (source, external_id) can't be inserted twice.
+    add_index :loam_inbound_webhook_deliveries, %i[source_id external_id], unique: true
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_memberships.rb

@@ -0,0 +1,11 @@
+class CreateLoamMemberships < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_memberships<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.references :user, null: false, foreign_key: true<%= loam_type_option %>
+      t.string :role, null: false
+      t.timestamps
+    end
+    add_index :loam_memberships, %i[tenant_id user_id], unique: true
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_mfa_credentials.rb

@@ -0,0 +1,13 @@
+class CreateLoamMfaCredentials < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_mfa_credentials<%= loam_id_option %> do |t|
+      # Per USER, not per tenant — MFA belongs to the person (no tenant_id).
+      t.references :user, null: false, foreign_key: { to_table: :users }, index: { unique: true }<%= loam_type_option %>
+      t.text :totp_secret            # encrypted at rest, user-scoped (Loam::Encryptable)
+      t.text :recovery_codes         # JSON: [{ digest, used_at }], codes stored hashed
+      t.datetime :activated_at       # nil until the user confirms a live code
+      t.bigint :last_totp_step       # last accepted TOTP timestep — rejects replays
+      t.timestamps
+    end
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_notifications.rb

@@ -0,0 +1,15 @@
+class CreateLoamNotifications < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_notifications<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.references :user, null: false, foreign_key: true<%= loam_type_option %>
+      t.string :title, null: false
+      t.text :body
+      t.datetime :read_at
+      t.string :source_type
+      t.<%= loam_key_column_type %> :source_id<%= loam_key_limit_option %>
+      t.timestamps
+    end
+    add_index :loam_notifications, %i[tenant_id user_id read_at]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_pending_actions.rb

@@ -0,0 +1,26 @@
+class CreateLoamPendingActions < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_pending_actions<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.<%= loam_key_column_type %> :actor_id<%= loam_key_limit_option %>                       # who staged it (the proposer)
+      t.string :status, null: false, default: "pending"
+      t.string :action_type, null: false       # create / update / destroy
+      t.string :target_type                     # the model being mutated
+      t.<%= loam_key_column_type %> :target_id<%= loam_key_limit_option %>                       # null for a staged create
+      t.text :changeset                         # encrypted JSON of the proposed changes
+      t.text :summary, null: false              # human-readable description
+      t.string :idempotency_key, null: false    # keyed HMAC; same proposal collapses to one row
+      t.<%= loam_key_column_type %> :reviewed_by_id<%= loam_key_limit_option %>                  # the approving/rejecting manager
+      t.datetime :reviewed_at
+      t.text :result                            # execution outcome, or "rejected: <reason>"
+      t.text :error                             # execution failure message
+      t.timestamps
+    end
+    # One row per distinct proposal per tenant.
+    # Only ONE PENDING row per proposal per tenant — a rejected/executed row with
+    # the same key may coexist, so a rejected proposal can be re-staged later.
+    add_index :loam_pending_actions, %i[tenant_id idempotency_key], unique: true,
+              where: "status = 'pending'", name: "index_loam_pending_actions_pending_key"
+    add_index :loam_pending_actions, %i[tenant_id status]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_perspectives.rb

@@ -0,0 +1,17 @@
+class CreateLoamPerspectives < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_perspectives<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :entity_type, null: false        # which entity this view is for
+      t.string :name, null: false               # human label
+      t.<%= loam_key_column_type %> :owner_id<%= loam_key_limit_option %>                         # the user who owns a private view
+      t.string :visibility, null: false, default: "private"  # private / role / tenant
+      t.string :role                             # set when visibility is "role"
+      t.boolean :is_default, null: false, default: false
+      t.json :config, null: false, default: {}   # { columns, filters, sort, page_size }
+      t.integer :lock_version, null: false, default: 0  # optimistic locking
+      t.timestamps
+    end
+    add_index :loam_perspectives, %i[tenant_id entity_type]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_progress_jobs.rb

@@ -0,0 +1,20 @@
+class CreateLoamProgressJobs < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_progress_jobs<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :key                                   # optional caller-chosen id (e.g. "reindex:Gadget")
+      t.string :name, null: false                     # human label
+      t.string :status, null: false, default: "running"  # running / completed / failed / cancelled
+      t.integer :total, null: false, default: 0
+      t.integer :completed, null: false, default: 0
+      t.text :message                                 # latest status line
+      t.text :error                                   # set when failed
+      t.<%= loam_key_column_type %> :actor_id<%= loam_key_limit_option %>                              # who started it
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.json :result                                  # structured result for a finished job (e.g. an import summary)
+      t.timestamps                                    # updated_at is the heartbeat
+    end
+    add_index :loam_progress_jobs, %i[tenant_id status]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_record_locks.rb

@@ -0,0 +1,16 @@
+class CreateLoamRecordLocks < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_record_locks<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :lockable_type, null: false
+      t.<%= loam_key_column_type %> :lockable_id<%= loam_key_limit_option %>, null: false
+      t.references :locked_by, null: false, foreign_key: { to_table: :users }<%= loam_type_option %>
+      t.string :token, null: false
+      t.datetime :expires_at, null: false   # TTL; an expired lock is treated as free
+      t.timestamps                          # updated_at is the heartbeat
+    end
+    # One advisory lock per record.
+    add_index :loam_record_locks, %i[tenant_id lockable_type lockable_id], unique: true,
+              name: "index_loam_record_locks_on_lockable"
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_scheduled_jobs.rb

@@ -0,0 +1,20 @@
+class CreateLoamScheduledJobs < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_scheduled_jobs<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :key, null: false                        # unique per tenant
+      t.string :name, null: false
+      t.string :job_class, null: false                  # a whitelisted ActiveJob class name
+      t.string :schedule, null: false                   # "0 7 * * *" or "interval:3600"
+      t.string :timezone                                # IANA zone; UTC when blank
+      t.string :scope, null: false, default: "tenant"   # "tenant" (per-tenant) or "system" (once)
+      t.datetime :next_run_at
+      t.datetime :last_run_at
+      t.datetime :locked_until                          # the atomic-claim lock (no double-fire)
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    add_index :loam_scheduled_jobs, %i[tenant_id key], unique: true
+    add_index :loam_scheduled_jobs, %i[active next_run_at locked_until]
+  end
+end