open-loam 0.1.0

data/lib/generators/loam/install/templates/admin/sessions_mfa_challenge.html.erb

@@ -0,0 +1,18 @@
+<%% if @error %>
+  <p style="color:#b00"><%%= @error %></p>
+<%% end %>
+
+<h1>Two-factor authentication</h1>
+
+<p>Signed in as <strong><%%= @user.name %></strong>. Enter the 6-digit code from
+your authenticator app, or one of your recovery codes.</p>
+
+<%%= form_with url: mfa_verify_admin_session_path, method: :post do |f| %>
+  <p>
+    <%%= label_tag :code, "Code" %><br>
+    <%%= text_field_tag :code, nil, autofocus: true, autocomplete: "one-time-code", inputmode: "numeric" %>
+  </p>
+  <%%= f.submit "Verify" %>
+<%% end %>
+
+<%%= button_to "Cancel and sign out", admin_session_path, method: :delete %>

data/lib/generators/loam/install/templates/admin/sessions_new.html.erb

@@ -0,0 +1,45 @@
+<%% if flash[:alert] %>
+  <p style="color:#b00"><%%= flash[:alert] %></p>
+<%% end %>
+<%% if @error %>
+  <p style="color:#b00"><%%= @error %></p>
+<%% end %>
+
+<%% if @user %>
+  <h1>Choose a tenant</h1>
+
+  <p>Signed in as <strong><%%= @user.name %></strong>. You are a member of more than one tenant.</p>
+
+  <%%= form_with url: select_tenant_admin_session_path, method: :post do |f| %>
+    <p>
+      <%%= select_tag :tenant_id, options_from_collection_for_select(@tenants, :id, :name) %>
+    </p>
+    <%%= f.submit "Enter" %>
+  <%% end %>
+
+  <%%= button_to "Sign out", admin_session_path, method: :delete %>
+<%% else %>
+  <h1>Sign in</h1>
+
+  <%%= form_with url: admin_session_path, method: :post do |f| %>
+    <p>
+      <%%= label_tag :email %><br>
+      <%%= email_field_tag :email, params[:email], autofocus: true %>
+    </p>
+    <p>
+      <%%= label_tag :password %><br>
+      <%%= password_field_tag :password %>
+    </p>
+    <%%= f.submit "Sign in" %>
+  <%% end %>
+
+  <h2>Or sign in with SSO</h2>
+  <p>Enter your work email; if your organization has single sign-on, we'll send you to it.</p>
+  <%%= form_with url: sso_start_admin_session_path, method: :post do |f| %>
+    <p>
+      <%%= label_tag :sso_email, "Work email" %><br>
+      <%%= email_field_tag :email, params[:email] %>
+    </p>
+    <%%= f.submit "Continue with SSO" %>
+  <%% end %>
+<%% end %>

data/lib/generators/loam/install/templates/admin/sso_providers_controller.rb

@@ -0,0 +1,65 @@
+module Admin
+  # Configure this tenant's SSO (OIDC) provider — manager-only, since it governs
+  # who can sign in and at what role. Tenant-scoped by Loam::SsoProvider's default
+  # scope, so a manager only ever sees and edits their own tenant's connection.
+  # The client_secret is WRITE-ONLY: it is encrypted at rest and never rendered
+  # back, so editing without retyping it leaves the stored secret untouched.
+  class SsoProvidersController < BaseController
+    before_action { require_role!(:manager) }
+    before_action :set_provider, only: %i[edit update destroy]
+
+    rescue_from JSON::ParserError do |error|
+      flash.now[:alert] = "The group→role map must be valid JSON: #{error.message}"
+      @provider ||= Loam::SsoProvider.new
+      render(@provider.persisted? ? :edit : :new, status: :unprocessable_entity)
+    end
+
+    def index
+      @providers = Loam::SsoProvider.order(:domain)
+    end
+
+    def new
+      @provider = Loam::SsoProvider.new(protocol: "oidc", active: true, jit_role: "employee")
+    end
+
+    def create
+      @provider = Loam::SsoProvider.new(provider_params)
+      if @provider.save
+        redirect_to admin_sso_providers_path, notice: "SSO provider created."
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def edit; end
+
+    def update
+      if @provider.update(provider_params)
+        redirect_to admin_sso_providers_path, notice: "SSO provider updated."
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @provider.destroy!
+      redirect_to admin_sso_providers_path, notice: "SSO provider deleted."
+    end
+
+    private
+
+    def set_provider
+      @provider = Loam::SsoProvider.find(params[:id])
+    end
+
+    def provider_params
+      permitted = params.require(:sso_provider).permit(:name, :protocol, :issuer, :client_id, :domain, :jit_role, :active)
+      # Write-only: only assign the secret when a new value was typed, so a blank
+      # field on edit keeps the encrypted one already stored.
+      secret = params[:sso_provider][:client_secret]
+      permitted[:client_secret] = secret if secret.present?
+      permitted[:group_role_map] = JSON.parse(params[:sso_provider][:group_role_map].presence || "{}")
+      permitted
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/sso_providers_edit.html.erb

@@ -0,0 +1,3 @@
+<h1>Edit SSO provider</h1>
+
+<%%= render "form" %>

data/lib/generators/loam/install/templates/admin/sso_providers_form.html.erb

@@ -0,0 +1,32 @@
+<%% if @error || flash[:alert] %>
+  <p style="color:#b00"><%%= @error || flash[:alert] %></p>
+<%% end %>
+
+<%# The model is namespaced (Loam::SsoProvider), so an inferred URL/param-scope
+    would be admin_loam_sso_provider_path / loam_sso_provider[...]. Pin both to
+    the un-namespaced route and the "sso_provider" key the controller permits. %>
+<%%= form_with model: @provider, scope: :sso_provider,
+      url: (@provider.persisted? ? admin_sso_provider_path(@provider) : admin_sso_providers_path) do |f| %>
+  <%% if @provider.errors.any? %>
+    <ul><%% @provider.errors.full_messages.each do |m| %><li><%%= m %></li><%% end %></ul>
+  <%% end %>
+
+  <p><%%= f.label :name %><br><%%= f.text_field :name %></p>
+  <p><%%= f.label :domain, "Email domain (for home-realm discovery, e.g. acme.example)" %><br><%%= f.text_field :domain %></p>
+  <p><%%= f.label :issuer, "OIDC issuer URL (its .well-known is discovered)" %><br><%%= f.text_field :issuer %></p>
+  <p><%%= f.label :client_id %><br><%%= f.text_field :client_id %></p>
+  <p>
+    <%%= f.label :client_secret, "Client secret (encrypted; leave blank to keep the current one)" %><br>
+    <%%= f.password_field :client_secret, value: "", autocomplete: "off" %>
+  </p>
+  <p><%%= f.label :jit_role, "Default role for new (JIT) users" %><br><%%= f.text_field :jit_role %></p>
+  <p>
+    <%%= f.label :group_role_map, "IdP group → role map (JSON, optional)" %><br>
+    <%%= f.text_area :group_role_map, value: JSON.pretty_generate(@provider.group_roles), rows: 4, cols: 40 %>
+  </p>
+  <p><%%= f.label :active %> <%%= f.check_box :active %></p>
+
+  <%%= f.submit %>
+<%% end %>
+
+<p><%%= link_to "Back", admin_sso_providers_path %></p>

data/lib/generators/loam/install/templates/admin/sso_providers_index.html.erb

@@ -0,0 +1,26 @@
+<h1>SSO providers</h1>
+
+<p>Single sign-on for this tenant. A user whose email domain matches a provider
+below is sent to that identity provider to sign in (OIDC), and provisioned on
+first login. <%%= link_to "New provider", new_admin_sso_provider_path %></p>
+
+<table>
+  <thead>
+    <tr><th>Name</th><th>Protocol</th><th>Domain</th><th>JIT role</th><th>Active</th><th></th></tr>
+  </thead>
+  <tbody>
+    <%% @providers.each do |provider| %>
+      <tr>
+        <td><%%= provider.name %></td>
+        <td><%%= provider.protocol %></td>
+        <td><code><%%= provider.domain %></code></td>
+        <td><%%= provider.jit_role %></td>
+        <td><%%= provider.active? ? "yes" : "no" %></td>
+        <td>
+          <%%= link_to "Edit", edit_admin_sso_provider_path(provider) %>
+          <%%= button_to "Delete", admin_sso_provider_path(provider), method: :delete, form: { style: "display:inline" } %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/loam/install/templates/admin/sso_providers_new.html.erb

@@ -0,0 +1,3 @@
+<h1>New SSO provider</h1>
+
+<%%= render "form" %>

data/lib/generators/loam/install/templates/admin/sudo_controller.rb

@@ -0,0 +1,45 @@
+module Admin
+  # The step-up ("sudo") re-challenge. A sensitive action calls require_sudo!,
+  # which detours here when the last authentication is stale; a correct password
+  # (or TOTP code, if the user has MFA) stamps a fresh sudo timestamp and returns
+  # to wherever they were headed.
+  class SudoController < BaseController
+    def new
+    end
+
+    def create
+      identifier = "#{current_actor.email}:sudo"  # a distinct throttle bucket from login
+
+      if Loam::AuthThrottle.locked?(identifier)
+        @error = "Too many attempts. Try again later."
+        return render :new, status: :too_many_requests
+      end
+
+      if reauthenticated?
+        Loam::AuthThrottle.clear(identifier)
+        session[:sudo_at] = Time.now.to_i
+        redirect_to(session.delete(:sudo_return_to).presence || admin_root_path,
+                    notice: "Re-authenticated — you can complete the action now.")
+      else
+        Loam::AuthThrottle.record_failure(identifier, kind: "sudo", ip: request.remote_ip)
+        @error = "That did not verify. Try again."
+        render :new, status: :unauthorized
+      end
+    end
+
+    private
+
+    # If the user has MFA, step-up takes a TOTP code — NOT a recovery code:
+    # recovery codes are single-use and reserved for LOGIN, so a routine sudo
+    # must never silently burn one. Otherwise fall back to the password. Either
+    # way it is the SAME person in Loam::Current re-confirming.
+    def reauthenticated?
+      credential = Loam::MfaCredential.active_for(current_actor)
+      if credential
+        credential.verify_totp(params[:code])
+      else
+        User.authenticate_by(email: current_actor.email, password: params[:password].to_s).present?
+      end
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/sudo_new.html.erb

@@ -0,0 +1,24 @@
+<%% if @error %>
+  <p style="color:#b00"><%%= @error %></p>
+<%% end %>
+
+<h1>Confirm it's you</h1>
+
+<p>This action is sensitive, so please re-authenticate.</p>
+
+<%%= form_with url: admin_sudo_path, method: :post do |f| %>
+  <%% if Loam::MfaCredential.active_for(current_actor) %>
+    <p>
+      <%%= label_tag :code, "Authenticator code" %><br>
+      <%%= text_field_tag :code, nil, autofocus: true, autocomplete: "one-time-code", inputmode: "numeric" %>
+    </p>
+  <%% else %>
+    <p>
+      <%%= label_tag :password %><br>
+      <%%= password_field_tag :password, nil, autofocus: true %>
+    </p>
+  <%% end %>
+  <%%= f.submit "Confirm" %>
+<%% end %>
+
+<p><%%= link_to "Cancel", admin_root_path %></p>

data/lib/generators/loam/install/templates/admin/translations_controller.rb

@@ -0,0 +1,37 @@
+module Admin
+  # Per-record content translations (Loam::Translatable) — manager-only, since
+  # translating content is a privileged edit. Scoped by translatable_type +
+  # translatable_id; edits each translatable field across Loam.locales. The base
+  # (default-locale) value stays on the record itself and is shown read-only for
+  # reference — translations are additive.
+  class TranslationsController < BaseController
+    before_action { require_role!(:manager) }
+    before_action :set_record
+
+    def index; end
+
+    def update
+      params.require(:translations).to_unsafe_h.each do |field, by_locale|
+        next unless @record.class.loam_translatable?(field)
+
+        by_locale.each { |locale, value| @record.set_translation(field, locale, value) if Loam.locales.include?(locale) }
+      end
+      redirect_to translate_path, notice: "Translations saved."
+    end
+
+    private
+
+    def set_record
+      model = Loam::Import.allowed_model(params[:translatable_type]) # whitelist: a Loam entity only
+      raise ActiveRecord::RecordNotFound unless model.include?(Loam::Translatable)
+
+      @record = model.find(params[:translatable_id])
+      @fields = model.loam_translatable_attributes
+    end
+
+    def translate_path
+      admin_translations_path(translatable_type: @record.class.name, translatable_id: @record.id)
+    end
+    helper_method :translate_path
+  end
+end

data/lib/generators/loam/install/templates/admin/translations_index.html.erb

@@ -0,0 +1,21 @@
+<h1>Translations — <%%= @record.class.model_name.human %> #<%%= @record.id %></h1>
+
+<p>Translate content per locale. The base (<%%= Loam.default_locale.upcase %>) value
+stays on the record; other locales overlay onto it, falling back to the base when
+empty.</p>
+
+<%%= form_with url: translate_path, method: :patch do %>
+  <%% @fields.each do |field| %>
+    <h3><%%= field.humanize %></h3>
+    <p><em>Base (<%%= Loam.default_locale.upcase %>):</em> <%%= @record.read_attribute(field) %></p>
+    <%% (Loam.locales - [Loam.default_locale]).each do |locale| %>
+      <p>
+        <%%= label_tag "translations[#{field}][#{locale}]", locale.upcase %><br>
+        <%%= text_field_tag "translations[#{field}][#{locale}]", @record.translations_for(field)[locale] %>
+      </p>
+    <%% end %>
+  <%% end %>
+  <%%= submit_tag "Save translations" %>
+<%% end %>
+
+<p><%%= link_to "Back", [:admin, @record] %></p>

data/lib/generators/loam/install/templates/admin/webhook_endpoints_controller.rb

@@ -0,0 +1,38 @@
+module Admin
+  # Where this tenant's events get delivered. Structural rather than
+  # per-record, like field definitions, so it is gated on the manager role
+  # instead of a generated entity policy.
+  class WebhookEndpointsController < BaseController
+    before_action { require_role!(:manager) }
+
+    def index
+      @records = Loam::WebhookEndpoint.order(:event_pattern)
+    end
+
+    def new
+      @record = Loam::WebhookEndpoint.new(active: true)
+    end
+
+    def create
+      @record = Loam::WebhookEndpoint.new(permitted_params)
+
+      if @record.save
+        redirect_to admin_webhook_endpoints_path
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      Loam::WebhookEndpoint.find(params[:id]).destroy!
+      redirect_to admin_webhook_endpoints_path
+    end
+
+    private
+
+    # The secret is generated, never submitted.
+    def permitted_params
+      params.require(:webhook_endpoint).permit(:url, :event_pattern, :active)
+    end
+  end
+end

data/lib/generators/loam/install/templates/admin/webhook_endpoints_index.html.erb

@@ -0,0 +1,32 @@
+<h1>Webhook endpoints</h1>
+
+<p>Domain events delivered over HTTP. A pattern ending in a dot matches a whole
+domain ("rental."); anything else is one exact event name.</p>
+
+<%%= link_to "New endpoint", new_admin_webhook_endpoint_path %>
+
+<table>
+  <thead>
+    <tr>
+      <th>Event pattern</th>
+      <th>URL</th>
+      <th>Active</th>
+      <th>Secret</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <%% @records.each do |record| %>
+      <tr>
+        <td><%%= record.event_pattern %></td>
+        <td><%%= record.url %></td>
+        <td><%%= record.active? ? "yes" : "no" %></td>
+        <td><code><%%= record.secret %></code></td>
+        <td><%%= button_to "Delete", admin_webhook_endpoint_path(record), method: :delete, form: { style: "display:inline" } %></td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>
+
+<p>Each delivery is signed: <code>X-Loam-Signature: sha256=HMAC-SHA256(secret, body)</code>.
+Recompute it on your side and reject anything that does not match.</p>

data/lib/generators/loam/install/templates/admin/webhook_endpoints_new.html.erb

@@ -0,0 +1,28 @@
+<h1>New webhook endpoint</h1>
+
+<%%= form_with model: @record, url: admin_webhook_endpoints_path do |f| %>
+  <%% if @record.errors.any? %>
+    <ul>
+      <%% @record.errors.full_messages.each do |message| %>
+        <li><%%= message %></li>
+      <%% end %>
+    </ul>
+  <%% end %>
+
+  <p>
+    <%%= f.label :event_pattern, "Event pattern (\"rental.\" for a whole domain, or one exact event name)" %><br>
+    <%%= f.text_field :event_pattern %>
+  </p>
+  <p>
+    <%%= f.label :url, "URL (http:// or https://)" %><br>
+    <%%= f.text_field :url %>
+  </p>
+  <p>
+    <%%= f.label :active %>
+    <%%= f.check_box :active %>
+  </p>
+
+  <%%= f.submit "Create endpoint" %>
+<%% end %>
+
+<p>A signing secret is generated for you and shown on the list.</p>

data/lib/generators/loam/install/templates/admin.css

@@ -0,0 +1,29 @@
+/* Loam admin console — shared styles (extracted from the layout, L-402). */
+body { font-family: system-ui, -apple-system, sans-serif; margin: 2rem; color: #1c1c1a; line-height: 1.5; }
+h1 { font-size: 1.55rem; margin: 0 0 0.75rem; }
+h2 { font-size: 1.2rem; margin: 1.25rem 0 0.5rem; }
+a { color: #1a5a9a; }
+
+table { border-collapse: collapse; margin: 0.5rem 0 1rem; }
+th, td { border: 1px solid #d5d5cf; padding: 0.4rem 0.8rem; text-align: left; vertical-align: top; }
+th { background: #f5f4f0; font-weight: 600; }
+
+nav { margin-bottom: 1.5rem; padding-bottom: 0.75rem; border-bottom: 1px solid #e4e2db; }
+nav a { margin-right: 1rem; }
+nav form { display: inline; }
+.context { color: #555; font-size: 0.9rem; margin-bottom: 1rem; }
+
+form p { margin: 0.5rem 0; }
+input, select, textarea { padding: 0.3rem 0.4rem; font: inherit; }
+button, input[type="submit"] { padding: 0.35rem 0.8rem; font: inherit; cursor: pointer; }
+
+/* Flash messages — controllers set notice:/alert:, the layout renders them. */
+.flash { padding: 0.6rem 0.9rem; border-radius: 6px; margin: 0 0 1rem; max-width: 60rem; }
+.flash-notice { background: #e6f4ea; border: 1px solid #b7dfc4; color: #1e5631; }
+.flash-alert  { background: #fdecec; border: 1px solid #f2b8b8; color: #8a1c1c; }
+
+.conflict { border: 2px solid #b00; padding: 0.75rem; margin-bottom: 1rem; }
+.lock-banner { background: #fffbe6; border: 1px solid #ece2a6; padding: 0.5rem; margin-bottom: 1rem; }
+
+code { background: #f3f0e9; padding: 0.05em 0.3em; border-radius: 3px; }
+small { color: #666; }

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

@@ -0,0 +1,90 @@
+module Api
+  # Base class for every JSON endpoint. Authentication is a bearer token:
+  #
+  #   curl -H "Authorization: Bearer <token>" http://localhost:3000/api/equipment
+  #
+  # A token identifies one user in one tenant, and `Loam::ApiToken.authenticate`
+  # establishes both in Loam::Current before any action runs. From that point
+  # on this is ordinary tenant-scoped Loam code: every query is filtered, every
+  # write is audited, every policy applies — the API is not a side door.
+  #
+  # Finding a token is the one lookup that cannot start from a tenant (the
+  # token is what reveals the tenant), which is why it lives in the gem rather
+  # than here: host app code must never reach across tenants.
+  class BaseController < ActionController::API
+    before_action :authenticate_api_token!
+
+    rescue_from Loam::NotAuthorizedError do
+      render json: { error: "forbidden" }, status: :forbidden
+    end
+
+    rescue_from ActiveRecord::RecordNotFound do
+      render json: { error: "not_found" }, status: :not_found
+    end
+
+    rescue_from Loam::UnknownCustomFieldError do |error|
+      render json: { error: error.message }, status: :unprocessable_entity
+    end
+
+    private
+
+    def authenticate_api_token!
+      @api_token = Loam::ApiToken.authenticate(bearer_token)
+
+      render json: { error: "unauthorized" }, status: :unauthorized unless @api_token
+    end
+
+    def bearer_token
+      request.headers["Authorization"].to_s[/\ABearer (.+)\z/, 1]
+    end
+
+    def current_tenant = Loam::Current.tenant
+    def current_actor = Loam::Current.actor
+
+    def policy_for(record)
+      Loam::Policy.for(record)
+    end
+
+    def authorize!(policy, action)
+      raise Loam::NotAuthorizedError unless policy.public_send(action)
+    end
+
+    # The JSON shape of an entity: its columns, custom fields included (they
+    # live in the `custom_fields` column that every generated entity carries).
+    #
+    # Encrypted fields (Loam::Encryptable) are returned DECRYPTED — the caller is
+    # authenticated, tenant-scoped and policy-gated, exactly like the admin show
+    # screen — and their blind-index `<field>_hash` column is dropped, so the
+    # equality-leaking hash never goes over the wire. `record.attributes` alone
+    # would emit the raw ciphertext plus the hash.
+    def entity_json(record, enrichments: nil)
+      json = record.attributes
+
+      if record.class.respond_to?(:loam_encrypted_attributes)
+        record.class.loam_encrypted_attributes.each do |name|
+          json[name] = record.public_send(name)
+          json.delete("#{name}_hash")
+        end
+      end
+
+      # Computed cross-module blocks (Loam::Enrichers), under a separate key so
+      # they're never confused with the record's own columns. An index passes the
+      # batched result (avoiding N+1); a single show computes it here.
+      enrichments = Loam::Enrichers.enrich(record) if enrichments.nil?
+      json["enrichments"] = enrichments if enrichments.present?
+      json
+    end
+
+    # Same field-level enforcement as the admin screens: only a definition the
+    # actor's role may write is assigned. Custom fields ride at the top level
+    # of the request body, beside the entity key.
+    def assign_custom_fields!(record, params, policy)
+      submitted = params[:custom_fields]
+      return unless submitted
+
+      submitted.each do |name, value|
+        record.set_custom_field(name, value) if policy.custom_field_writable?(name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+require "test_helper"
+
+# Structural guardrails. These are not feature tests — they enforce Loam's
+# invariants on the codebase itself. If one of these fails, an agent (or a
+# human) stepped outside the conventions.
+class LoamGuardrailsTest < ActiveSupport::TestCase
+  # Models that are legitimately not tenant-scoped. Loam::Config holds both
+  # global (tenant_id NULL) and per-tenant override rows, so tenancy is a
+  # nullable column and resolution lives in vetted gem code (Loam::Configs).
+  # Loam::MfaCredential belongs to the person, who spans tenants — MFA is
+  # verified at login before any tenant is chosen.
+  TENANCY_ALLOWLIST = %w[ApplicationRecord User Loam::Tenant Loam::Config Loam::MfaCredential Loam::AuthAttempt].freeze
+
+  # Rails' own engine models (storage, rich text, jobs) are framework
+  # plumbing, not business data — they are out of scope for tenant linting.
+  FRAMEWORK_NAMESPACES = %w[ActiveStorage:: ActionText:: ActionMailbox:: SolidQueue:: SolidCache:: SolidCable::].freeze
+
+  test "every app model is tenant-scoped (inherits Loam::TenantRecord)" do
+    Rails.application.eager_load!
+
+    offenders = ActiveRecord::Base.descendants.reject do |model|
+      model.abstract_class? ||
+        model.name.nil? ||
+        TENANCY_ALLOWLIST.include?(model.name) ||
+        FRAMEWORK_NAMESPACES.any? { |ns| model.name.start_with?(ns) } ||
+        model <= Loam::TenantRecord
+    end
+
+    assert_empty offenders,
+      "These models are NOT tenant-scoped: #{offenders.map(&:name).join(', ')}. " \
+      "Business models must inherit Loam::TenantRecord (use `rails g loam:entity`). " \
+      "If a model is intentionally global, add it to TENANCY_ALLOWLIST here — in review, on purpose."
+  end
+
+  test "touching a tenant-scoped model with no tenant context raises" do
+    Loam::Current.reset
+
+    assert_raises(Loam::MissingTenantError) { Loam::AuditRecord.count }
+    assert_raises(Loam::MissingTenantError) { Loam::Membership.first }
+  end
+
+  test "nobody uses .unscoped outside vetted framework code" do
+    offenders = Dir[Rails.root.join("app/**/*.rb")].select do |file|
+      File.read(file).match?(/\bunscoped\b/)
+    end
+
+    assert_empty offenders,
+      ".unscoped found in: #{offenders.join(', ')}. It bypasses tenant isolation — remove it."
+  end
+
+  # Agent harnesses read AGENTS.md into a context window and truncate what
+  # doesn't fit — silently. An overweight file doesn't warn, it just loses its
+  # tail, and the tail is where the invariants live.
+  AGENTS_MD_BUDGET_BYTES = 32_768
+
+  test "AGENTS.md stays inside its byte budget" do
+    path = Rails.root.join("AGENTS.md")
+
+    assert path.exist?, "AGENTS.md is missing from #{Rails.root} — it is the contract AI agents work against."
+    assert path.size <= AGENTS_MD_BUDGET_BYTES,
+      "AGENTS.md is #{path.size} bytes, over the #{AGENTS_MD_BUDGET_BYTES}-byte budget. " \
+      "Agent harnesses truncate instruction files without warning, so the tail — invariants, " \
+      "definition of done — would silently stop being read. Cut prose or move detail into " \
+      "docs/ and link it, rather than raising the budget."
+  end
+
+  test "every Loam::FieldDefinition entity_type resolves to a class that uses Loam::CustomFields" do
+    Rails.application.eager_load!
+
+    offenders = Loam::FieldDefinition.unscoped.distinct.pluck(:entity_type).reject do |entity_type|
+      klass = entity_type.safe_constantize
+      klass && klass.include?(Loam::CustomFields)
+    end
+
+    assert_empty offenders,
+      "These Loam::FieldDefinition entity_type values don't resolve to a class that " \
+      "`include Loam::CustomFields`: #{offenders.join(', ')}. Likely a typo when the field was created."
+  end
+end

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

@@ -0,0 +1,25 @@
+# Runs a CSV import in the background, advancing a Loam::ProgressJob so the admin
+# watches it live (L-915). Carries tenant + actor explicitly, like every Loam job.
+# The per-row summary (created/updated/failed + error rows) is stored on the
+# ProgressJob's `result` for the summary screen.
+class ImportJob < ApplicationJob
+  queue_as :default
+
+  def perform(entity_type:, csv:, mapping:, match_key:, tenant_id:, actor_id:)
+    tenant = Loam::Tenant.find(tenant_id)
+    actor = User.find_by(id: actor_id)
+    model = Loam::Import.allowed_model(entity_type)
+
+    Loam.as_tenant(tenant, actor: actor) do
+      total = [ CSV.parse(csv).size - 1, 0 ].max
+      progress = Loam::Progress.start(name: "Import #{entity_type}", total: total)
+      begin
+        result = Loam::Import.run(csv, model: model, mapping: mapping, actor: actor, match_key: match_key, progress: progress)
+        progress.update_columns(result: result.to_h)
+        progress.complete!
+      rescue StandardError => error
+        progress.fail!(error.message)
+      end
+    end
+  end
+end