open-loam 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c2e0e075f887239d67b9dfdcefeeba0c825cc7c8faf1fe1f32c813e7916c687
+  data.tar.gz: 51b1ee994cfc4f118369463bc999c302e699232bd122e20cf19511e213a9fd91
+SHA512:
+  metadata.gz: be8e513778bc4d402e6365304054a865a64f96441868e079b6ccffe41a26046d5d8f8d40c7f2870e6fe33eb26dcace0f708e49a5df83d069a301977c0ad9329a
+  data.tar.gz: 3fd4050284ae72d54324b0b69a5aee6f9bd86939cf92dc4299a253e4c4d861c616ad8321def46b673816fd3afda85e245745d165115973deb1f8f86a19a83785

data/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+Notable changes to Loam. This project follows [semantic versioning](https://semver.org),
+with the caveat that 0.x releases may break the public surface; the
+[backward-compatibility contract](BACKWARD_COMPATIBILITY.md) names what is
+frozen and what is not.
+
+## 0.1.0 — 2026-09-04
+
+First public release. Loam is a working, tested prototype: the foundation and
+the agent workflow are complete end to end, but no production deployment has
+used it yet. Evaluate it as a prototype, not as proven infrastructure.
+
+### The foundation
+
+- **Multi-tenancy** — `Loam::TenantRecord` scopes every query, job and event to
+  the current tenant. A missing tenant context raises `Loam::MissingTenantError`
+  rather than silently widening a query.
+- **Authorization** — roles, policies, field-level write access, and
+  deny-by-default wildcard feature permissions (`equipment.*`).
+- **Authentication** — password auth, MFA with step-up, rate-limiting and
+  lockout, and per-tenant OIDC single sign-on with JIT provisioning.
+- **Audit and history** — audit trails, record history, undo, soft deletion,
+  and optimistic-locking protection against concurrent edits.
+- **Encryption** — per-tenant AES-256-GCM field encryption with AAD binding,
+  and blind indexes for exact-match lookup on encrypted values.
+- **Business modelling** — runtime custom fields with a read-model index,
+  managed dictionaries, declared workflows with role-gated approvals, saved
+  views, configurable dashboards, content translations, comments and
+  attachments.
+- **Integration** — token-authenticated JSON APIs with generated OpenAPI 3.1
+  docs, signed outbound webhooks, replay-resistant inbound webhooks, and a
+  two-tier event bus (in-process subscribers plus durable, retryable delivery
+  with dead-lettering).
+- **Operations** — notifications, live browser updates, an atomic-claim
+  scheduler, long-running task progress, and policy-aware bulk CSV
+  import/export.
+
+### For AI coding agents
+
+- **`AGENTS.md`** — the contract, generated into the host app, telling an agent
+  where code belongs and which boundaries it must preserve.
+- **Generators as the interface** — `loam:install` and `loam:entity` are the
+  supported way to add a feature, for humans and agents alike.
+- **Structural guardrails** — tests that fail the build on a missing tenant
+  scope, a stray `.unscoped`, or an oversized `AGENTS.md`.
+- **A human-approval gate** — `Loam::PendingActions` stages an agent-proposed
+  mutation for review before it touches business data.
+- **The golden-tasks benchmark** and `Loam::Eval` scorer. Results, methodology
+  and caveats are published at
+  <https://deliveristsio.github.io/open-loam/agents/golden-tasks/>; they come
+  from a single internal run and are not independently reproduced.
+
+### Database keys
+
+- Generators follow the host app's primary key type — `bigint`, `uuid` or
+  `string` — resolved from `--primary-key-type`, then the app's own
+  `config.generators` setting, then `bigint`. This covers `create_table`,
+  `t.references`, and the polymorphic `*_id` columns that cannot use
+  `t.references`.
+- `Loam::GeneratedKey` assigns a UUID before create when the key is not an
+  integer, since a string primary key has no database default. Integer keys are
+  still generated by the database.
+
+### Known limitations
+
+- No production validation. The next milestone is one measured real build, not
+  more modules.
+- The benchmark is internal and has been run once.
+- Requires Rails 7.1 or newer and Ruby 3.2 or newer. The demo and CI run on
+  SQLite; other adapters are untested.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Smajdor and Loam contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,177 @@
+# Loam 🌱
+
+**In short:** Loam is a Rails starter kit for business apps — multi-tenancy,
+permissions, audit trails, workflows, and an event bus already built in, so you
+skip months of plumbing and start on real features. It's also AI-native:
+convention-driven code that AI coding agents (Claude Code, Codex, etc.) can
+safely extend, with human-approval gates before any agent write takes effect.
+
+**The fertile Rails foundation where AI agents grow business software.**
+
+📖 **Documentation: [deliveristsio.github.io/open-loam/](https://deliveristsio.github.io/open-loam/)**
+
+---
+
+## Why Loam exists
+
+Every serious back-office app — CRM, ERP, ops console, internal tool — re-derives
+the same ~80%: who's the tenant, who's allowed, what changed and when, how do
+modules talk, where's the admin. Teams burn months on this before shipping a
+single thing a customer cares about.
+
+And now a second shift: **AI coding agents** (Claude Code, Codex, opencode) can
+write real features — *if* the codebase is legible to them. Sprawling, snowflake
+architectures confuse agents as much as they confuse new hires. Convention is
+what makes a codebase safe for an agent to extend.
+
+Loam fuses the two: **a pre-built business foundation that is deliberately
+agent-legible.** Rails already leans convention-over-configuration — arguably the
+most agent-friendly framework there is. Loam extends that philosophy from "how to
+structure a controller" up to "how a multi-tenant, permissioned, audited business
+domain is built" — and ships the agent conventions to match.
+
+## Where Loam sits
+
+The pieces exist in Rails, but scattered — foundation shape in Bullet Train and
+the commerce products, an event backbone in Rails Event Store, custom-entity
+modeling only inside commerce. No Rails project unifies them into a single,
+agent-legible business foundation. The closest structural analogs live in other
+stacks: Frappe/ERPNext in Python, and
+**[Open Mercato](https://github.com/open-mercato/open-mercato)** in TypeScript —
+whose module system and convention-first, agent-legible approach directly
+inspired Loam. Loam brings that idea to Rails, the substrate it always suited.
+
+---
+
+## What's already decided
+
+Each pillar ships as a convention with sane defaults, overridable when you truly
+need to — never a blank page.
+
+| Pillar | What you get, out of the box |
+|--------|------------------------------|
+| 🏢 **Multi-tenancy** | Tenant isolation baked into every query, background job, and event. New models are tenant-scoped by default; a missing tenant context raises, never silently widens a query. |
+| 🔐 **Permissions & auth** | Password login, roles, policies, and field-level write access — declared, not hand-rolled per controller. Tenant selection limited to a user's memberships. Plus **feature-string permissions** (`Loam::Permissions`): grant a role wildcard capability strings (`equipment.*`) and check `Loam.can?("equipment.edit")` / `require_permission!` — deny-by-default, a finer layer under the coarse role. |
+| 🌾 **Custom fields** | Define fields at runtime (a `custom_fields` JSON column + a `Loam::FieldDefinition` row), so agents and admins extend a model without a migration for every idea. Filtering and sorting on a custom field is **index-backed** at scale via a typed read-model projection (`Loam::CustomFieldIndex`), not a per-row JSON scan — with **coverage accounting** (is the index complete or drifting?), a read-time gap that **falls back to the authoritative source for correctness** and **self-heals** in the background (deduped), and an honest "results may be incomplete" signal while it does. A field can declare `readable_roles`: filtering or sorting on a field a role **may not read** is refused, so a filter can't become an **inference oracle** on a restricted value. |
+| 🔀 **Workflow** | Declared states, transitions, and role-gated approvals on any entity; each transition emits an event and is audited. |
+| 📡 **Event backbone** | A first-class domain event bus (`domain.thing.happened`, publish/subscribe) so modules stay decoupled and workflows are legible. Two subscriber tiers with a **formal contract**: *ephemeral* (`Loam::Events.subscribe`, in-process, synchronous, best-effort) for cheap fan-out, and *durable* (`Loam::DurableEvents.register`) which **persists each delivery as a row** in the event's tenant and hands it to a background job — **at-least-once with retry + backoff**, a **dead-letter** view with manual requeue, and a periodic **sweep** that redelivers a lost job (row state, not the queue, is the source of truth). A handler is resolved from a boot-time registry, never constantized from the stored row. |
+| 🔔 **Notifications** | Tenant-scoped in-app notifications, created from events, surfaced in the admin. |
+| 🔌 **API & webhooks** | Token-authenticated JSON API per entity (policy-aware) and per-tenant signed **outbound** webhooks on domain events. **Inbound** webhooks too: a public `/webhooks/:token` receiver that HMAC-verifies each call over the raw body, resists replays (a `(source, delivery-id)` idempotency ledger), answers every auth failure with a uniform `401`, and publishes the verified event onto the bus so durable subscribers react. |
+| 🧾 **Audit** | Every change — who, what, when, in which tenant — recorded by default. |
+| ↩️ **Undo / history** | The audit trail is an **undo stack**: each record's History screen reverts a change with one click, and the undo is itself recorded — so undoing an `undo` is redo. Walks back one step at a time (never clobbers a newer edit); **encrypted fields and workflow state are never reverted** here (state changes undo via the reverse transition). |
+| 🗑️ **Soft-delete** | Deleting a record hides it instead of erasing it — excluded from every query by default, still tenant-scoped in the recycle bin, restorable, and recorded in the audit trail. |
+| ⚙️ **Settings** | A key-value settings store with a global default and a per-tenant override — typed values, resolved override → global → default, cached per request, and never leaking between tenants. |
+| 🚩 **Feature flags** | Runtime on/off capabilities per tenant for rollout or kill-switch — a global default plus per-tenant override, a `Loam::Features.on?` guard, and an admin screen. Gates a **capability**, not a person — distinct from roles and policies. |
+| 🔒 **Encryption at rest** | Mark a field `encrypts` and it is transparently AES-256-GCM encrypted with a **per-tenant** key (HKDF, KMS-pluggable) and decrypted on read — a DB dump leaks nothing and tenant A's key never opens tenant B's data. A keyed blind index keeps an encrypted email/phone findable by exact match; the audit trail records the change, never the value. |
+| 🔑 **MFA & step-up auth** | TOTP second factor for admin login (RFC 6238, no dependency), with single-use recovery codes; the secret is encrypted per-user so it verifies in any tenant. `require_sudo!` re-challenges for sensitive actions within a short window — orthogonal to role. MFA can be required per role. Failed password / TOTP / sudo attempts are **rate-limited and locked out** (per-identifier, configurable), so an online brute-force of a 6-digit code is throttled — and a lockout is enumeration-safe (a locked known and unknown identifier respond identically). |
+| 🚦 **AI approval gate** | An agent running under confirm-mode **stages** a write as a `PendingAction` with a before/after preview instead of committing it; a manager approves (a role-gated workflow transition) and only then does it execute — audited to the approver. The human-in-the-loop primitive for agent writes; encrypted fields never appear in the preview or audit. |
+| 🤖 **MCP server** | An [MCP](https://modelcontextprotocol.io) server (`bin/rails loam:mcp:serve`, stdio) exposes Loam to an AI agent: discover entities/schema/policy, **read** tenant-scoped records (only fields the role may see), and **propose** writes that are *staged for human approval* — never committed. Every gate is a Loam gate reused (tenancy, read-ACL, the approval gate); the agent acts as its API token's user, no more. |
+| 👓 **Saved views** | A user names a view of an entity's admin index — filters, sort, columns — and keeps it private, shares it to a role, or makes it the tenant default. Filters only ever touch whitelisted data columns; a stored view is optimistic-locked so shared edits don't clobber. |
+| 🔏 **Concurrent-edit safety** | Optimistic locking (`lock_version`) turns a stale save into a clean "this changed since you opened it" conflict — with a diff and a retry, never a silent clobber — and an advisory `RecordLock` shows "Anna is editing this" with a manager take-over. The version check is the guarantee; the lock is the courtesy. |
+| 📡 **Real-time updates** | A per-tenant Server-Sent-Events stream pushes selected events to the browser — the notification bell increments live, no polling. Opt-in per event pattern (default off, tenant- and audience-filtered), behind a broadcaster seam so Redis/SolidCable drops in for multi-process. |
+| 🧩 **Response enrichers** | One module attaches a computed block onto another's entity at read time — no foreign-key coupling (billing annotates an Equipment without Equipment knowing billing exists). A batch path resolves N records in one query; a failing enricher is isolated, and each runs tenant-scoped. |
+| ⚡ **Business rules** | A manager declares, per tenant, WHEN a condition holds THEN run actions — evaluated on domain events, no deploy. The condition is **data, never code**: a whitelisted `{field, op, value}` tree over real columns and custom fields (no `eval`, no `send`, tenant/encrypted columns refused), and the actions are a fixed safe vocabulary (notify, emit an event, set a whitelisted field, veto a transition). Rules fire tenant-scoped in priority order, each isolated, with an execution log that shows why it acted. |
+| 🔎 **Pluggable search** | `searchable_by` and `Model.search(q)` stay put; the strategy behind them is a swappable **driver**. Ships two: a portable substring **LIKE** (default, zero-setup) and a **word-level token index** (order-independent, AND-semantics, still plain SQL — no external service), with the seam ready for Meilisearch/Elasticsearch. Swapping is a one-line initializer change, no call-site edits. Tenant-scoped, and an encrypted field's plaintext is never tokenized. |
+| 🪪 **SSO (OIDC)** | Per-tenant single sign-on: each tenant connects its own identity provider. **Home-realm discovery** routes a user to their IdP by email domain; a verified identity is **just-in-time provisioned** (or linked to an existing account), with IdP group → role mapping. The client secret is encrypted at rest (per-tenant key). An unverified email is refused — no silent account takeover. OIDC ships end-to-end; SAML and SCIM are documented seams behind a protocol interface. |
+| 📚 **Dictionaries** | Per-tenant managed lookup lists — named sets of entries (value/label/color/icon/position/default) an admin curates without a deploy. Usable as a **custom-field type**: a `dictionary` field renders a select of the list's active entries and stores the chosen value, showing its label on read. Tenant-scoped and cached per request. |
+| ⏳ **Task progress** | A long-running job (import, reindex, report) reports percent / counts / ETA to the admin, pushed **live over SSE** — no polling. `Loam::Progress.start`/`advance`/`complete!`; the browser bar moves as the job runs. The broadcast is throttled to once per whole percent, the job supports a cooperative cancel, and a stalled job (dead heartbeat) is flagged. Tenant-scoped; the frame carries only id/percent/status. |
+| 🕰️ **Scheduler** | Per-tenant recurring jobs — cron (`0 7 * * *`) or interval — that enqueue an ActiveJob on schedule. A runner (`loam:scheduler:tick`, wired to system cron) claims due jobs **atomically** (Postgres `SKIP LOCKED`; SQLite a transactional claim), so multiple workers **never double-fire** one. `job_class` is whitelisted to a real ActiveJob (no arbitrary code). Tenant-scope jobs run per tenant; system-scope once. A stdlib cron-next calculator (no gem), timezone-aware. |
+| 📥 **Bulk import / export** | CSV **export** of any entity's current filtered view — policy- and encryption-aware (an encrypted field is redacted, never a plaintext dump). CSV **import** with a column-mapping engine: dedupe by a key (update-or-create), per-row validation with a skipped-row error log and a **downloadable error file**, a **dry-run** that commits nothing, and live progress (backgrounded, reported via the task bar). The mapping only targets policy-permitted fields — no crafted column reaches `tenant_id` or a field a role can't write. Plus **datatable bulk actions** (select rows → soft-delete / set-field / export), policy-checked per record and tenant-scoped. |
+| 📊 **Configurable dashboard** | The admin home is a grid of module-provided **widgets** on a registry — a metric or short list each. A manager picks which widgets appear and in what order, per tenant; a widget's `roles:` filter is enforced server-side (a hidden widget's data is never even computed). Widgets query tenant-scoped models (no cross-tenant leak), and a raising widget is isolated into an error tile — the dashboard never breaks. Ships built-ins (recent activity, unread notifications, pending approvals, running tasks). |
+| 📜 **Auto OpenAPI** | The JSON API documents itself. `Loam::OpenApi` introspects the generated per-entity API controllers — columns/types, exposed fields, custom fields, the bearer-token security scheme, and the tenancy guarantee — into an **OpenAPI 3.1** document, with **no hand-written annotations and no external gem**. A server-rendered explorer at `/admin/api_docs` (no Swagger-UI/external JS), a `.json` endpoint for tooling, and `loam:openapi:export` for CI. Request schemas expose only writable fields (never `tenant_id`); encrypted fields are typed as plain strings — the doc describes shape, never data. |
+| 🌐 **Content translations** | Translate the DATA in a record's fields per locale — a product name, a category label — distinct from Rails i18n (developer UI strings, still Rails-native). `translates :name` adds a read-time **overlay**: `record.name` returns the current locale's translation when one exists, else the record's own column (the base value, never lost). Locale is request state (a `/admin` switcher); translations are tenant-scoped, audited, additive rows. An **encrypted field can't be translated** — that would store plaintext, so it's refused at load. |
+| 🧬 **Override registry** | Disable or replace an entry in one of Loam's keyed registries — a built-in dashboard widget, a default broadcast pattern — from an initializer, **without forking or monkeypatching**: `Loam::Overrides.disable(:widgets, "open_progress")` / `.replace(:widgets, "audit_recent") { … }`. The value over a raw monkeypatch: a **stale override** (a key that no longer exists) is warned about at boot, so a typo isn't a silent no-op. Deliberately small — structural pieces (views, controllers, routes) still use standard Rails path-shadowing; this fills the gap for the in-gem registries. |
+| 🖥️ **Admin surface** | An internal console generated from your models — comments, attachments, global search, filtering, pagination — not a second app to maintain. |
+| 🤖 **Agent conventions** | An `AGENTS.md` (byte-budgeted), generators as the one interface, and structural guardrails so an AI agent can add a domain feature **safely** — and a human can read what it did. |
+
+You write the **20% that is your business**. Loam is the 80% that every business
+app shares.
+
+---
+
+## Agent-native by design
+
+Loam treats "an AI agent will extend this" as a first-class constraint:
+
+- **One obvious way** to add an entity, a permission, an event, a screen — so an
+  agent's output is predictable and reviewable.
+- **A contract they read** — an `AGENTS.md` map plus generators as the only
+  interface, so an agent extends the app the same way every time. (Live schema
+  access over MCP is on the roadmap.)
+- **Boundaries agents can't accidentally cross** — tenancy and permissions are
+  structural, not conventions an agent might forget.
+
+The result: a codebase where "add a `Subscription` entity with an admin screen,
+tenant-scoped, audited, emitting `subscription.created`" is a *small, safe* task —
+for an agent or a human.
+
+---
+
+## Status
+
+**Working prototype — every pillar in the table above is built, tested, and
+exercised end to end** by a demo app, a generator harness, and an agent
+benchmark. Some two dozen `Loam::` modules, from tenancy through SSO, each
+added the same way: a small in-gem implementation behind a convention, wired to
+agree with the rest.
+
+**What's in the repo**
+
+| Path | What it is |
+|------|-----------|
+| `lib/` | The `loam` gem — every pillar as a small `Loam::` module, plus the `loam:install` and `loam:entity` generators that are the whole interface. |
+| `demo/` | An equipment-rental app built with those generators (454 tests / 1,534 assertions as of 2026-08-22), carrying the generated guardrail tests: tenant isolation, no-context-raises, a lint against `.unscoped` in `app/`, and a 32 KB `AGENTS.md` budget. |
+| `ai/` | The agent benchmark — `golden_tasks.md` and recorded runs. First run: **10/10 tasks, zero isolation or authorization violations**; a vanilla-Rails control under the same prompts enforced isolation in **1/10**. |
+| `docs/_agents/` | Deep-dive conventions (encryption, SSO, scheduler, …) linked from `AGENTS.md`, so the agent contract stays inside its byte budget. |
+| `.github/` | CI runs the generator harness and the demo suite on every push. |
+
+**Security-hardened by adversarial review.** Each batch of features went through
+an independent adversarial security review; the reviews found and closed real
+cross-tenant account-takeover chains, privilege escalations, and PII-leak
+vectors — every fix landing with a regression test that reproduces the exploit.
+That the *power* features (a business-rules engine, bulk import, SSO) are where
+the holes appeared, and that the guardrails and reviews caught them, is the
+whole thesis in miniature.
+
+**How honest the "prototype" label is** — deliberately, each pillar is a
+*minimal in-gem implementation* rather than a wrapper around
+`acts_as_tenant`/`pundit`/`paper_trail`/Rails Event Store: the smallest surface
+that proves the conventions and the agent flow. Swapping the proven gems back in
+*behind the same `Loam::` conventions* is the roadmap, not a reversal. Custom
+fields use the portable Rails `json` column (not Postgres `jsonb`/GIN) because
+the demo runs on SQLite. See [How Loam works](docs/_foundation/overview.md) for
+the pillar-by-pillar breakdown and the decisions behind them.
+
+**Try it**
+
+```bash
+cd demo && bundle install && bin/rails db:migrate db:seed
+bin/rails test            # guardrail + entity tests
+bin/rails server          # → http://localhost:3000/admin
+```
+
+Sign in as `anna@example.com` (manager in both branches, so she gets the tenant
+picker) or `tomek@example.com` (Warsaw only) — password `password123` for both.
+
+**New here? Start with the [Getting Started walkthrough](https://deliveristsio.github.io/open-loam/getting-started/)** —
+it builds a multi-tenant feature from `rails new` to a working approval flow,
+showing the real commands and exactly what you *didn't* have to write.
+
+- [**Architecture map**](https://claude.ai/code/artifact/949311d3-5e14-4f07-a8ad-7b1bb5bd87ad) — a visual tour: the module graph, a request lifecycle, the event flow
+- [Getting started](https://deliveristsio.github.io/open-loam/getting-started/) — hands-on, install to first feature
+- [Overview](OVERVIEW.md) — plain-language product, use cases, evidence, and risks
+- [Concept & positioning](https://deliveristsio.github.io/open-loam/concept/)
+- [How Loam works](https://deliveristsio.github.io/open-loam/foundation/overview/) — the diagrams above + how every pillar is built
+- [Tenant isolation](https://deliveristsio.github.io/open-loam/foundation/tenant-isolation/) & [Authorization](https://deliveristsio.github.io/open-loam/foundation/authorization/) — the two flagship guarantees, in depth
+- [Agents](https://deliveristsio.github.io/open-loam/agents/) — the agent contract, guardrails, the golden-tasks benchmark, and subsystem deep-dives (encryption, SSO, scheduler, events, inbound webhooks, bulk, confirm-mode)
+- Reference — [configuration](https://deliveristsio.github.io/open-loam/reference/configuration/), [generators](https://deliveristsio.github.io/open-loam/reference/generators/), [backward compatibility](https://deliveristsio.github.io/open-loam/reference/compatibility/)
+- [Roadmap](ROADMAP.md) — ordered backlog, Mercato-informed
+- [Backward-compatibility contract](BACKWARD_COMPATIBILITY.md) — the frozen public surfaces
+- [Architecture decisions](https://deliveristsio.github.io/open-loam/adr/) & [lessons](ai/lessons.md) — why things are the way they are, and the gotchas
+- [Agent pack](.loam/agents/) — everything an AI agent should load to extend a Loam app correctly
+- [Manifesto](https://deliveristsio.github.io/open-loam/manifesto/)
+- [Contributing](CONTRIBUTING.md)
+
+---
+
+*MIT licensed — open-core, like the foundations it stands on.*

data/app/jobs/loam/custom_field_reindex_job.rb

@@ -0,0 +1,22 @@
+module Loam
+  # Heals a custom-field index gap in the background: rebuilds one model's
+  # read-model index (Loam::CustomFieldIndex) for one tenant. Enqueued (deduped)
+  # by CustomFieldIndex when a filter/order runs over an incomplete index, so a
+  # gap self-heals without an operator running a rake task. Inherits
+  # ActiveJob::Base, not the app's ApplicationRecord-owned base (the gem must not
+  # depend on a class the app configures), and carries the tenant explicitly.
+  class CustomFieldReindexJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(tenant_id, model_name)
+      tenant = Loam::Tenant.find_by(id: tenant_id)
+      model = model_name.to_s.safe_constantize
+      return unless tenant && model.is_a?(Class) && model < Loam::TenantRecord
+
+      Loam.as_tenant(tenant) { Loam::CustomFieldIndex.reindex(model) }
+    ensure
+      # Release the dedup marker so a later real gap can enqueue again.
+      Loam::CustomFieldIndex.clear_pending(tenant_id, model_name.to_s)
+    end
+  end
+end

data/app/jobs/loam/event_delivery_job.rb

@@ -0,0 +1,26 @@
+module Loam
+  # Runs one durable event delivery (Loam::DurableEvents). Inherits
+  # ActiveJob::Base rather than the host app's ApplicationJob — the gem must not
+  # depend on a class the app owns and may have configured for its own retries —
+  # and carries the tenant explicitly (ActiveJob doesn't serialize Loam::Current).
+  #
+  # A missing row is an ANSWER, not an error: with an async queue adapter the job
+  # can start before the creating transaction commits, so the row isn't visible
+  # yet. The job no-ops; the redelivery sweep picks the row up once it commits.
+  # Retry state lives in the ROW (Loam::DurableEvents.deliver), never here.
+  class EventDeliveryJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(tenant_id, delivery_id)
+      tenant = Loam::Tenant.find_by(id: tenant_id)
+      return if tenant.nil?
+
+      Loam.as_tenant(tenant) do
+        delivery = Loam::EventDelivery.find_by(id: delivery_id)
+        return if delivery.nil? # not visible yet (txn race) or gone — the sweep covers it
+
+        Loam::DurableEvents.deliver(delivery)
+      end
+    end
+  end
+end

data/app/jobs/loam/event_redelivery_sweep_job.rb

@@ -0,0 +1,21 @@
+module Loam
+  # Periodic durability sweep: re-enqueues due-but-undelivered event deliveries
+  # whose accelerator job was lost (worker crash, dropped message, an async
+  # adapter racing the creating transaction). This — not perform_later at publish
+  # — is what makes persistent delivery durable.
+  #
+  # Registered per-tenant via Loam::Scheduler (see Loam::Engine), so `sync_tenant`
+  # materializes a schedule row per tenant and the scheduler allowlist already
+  # covers the class. Tenant-scoped: the scheduler enqueues it with tenant_id and
+  # the sweep runs inside that tenant, so there is no cross-tenant scan.
+  class EventRedeliverySweepJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(tenant_id: nil)
+      tenant = Loam::Tenant.find_by(id: tenant_id)
+      return if tenant.nil?
+
+      Loam.as_tenant(tenant) { Loam::DurableEvents.redeliver_stuck }
+    end
+  end
+end

data/app/jobs/loam/webhook_delivery_job.rb

@@ -0,0 +1,59 @@
+require "net/http"
+require "openssl"
+
+module Loam
+  # Delivers one event to one endpoint. Inherits ActiveJob::Base rather than
+  # the host app's ApplicationJob: the gem must not depend on a class the app
+  # owns and may have configured for its own retries.
+  #
+  # Signing: the receiver recomputes HMAC-SHA256 of the exact body with the
+  # endpoint's secret and compares it to X-Loam-Signature. Body building and
+  # signing are class methods so both sides — and the tests — can call them
+  # without a network.
+  class WebhookDeliveryJob < ActiveJob::Base
+    queue_as :default
+
+    TIMEOUT_SECONDS = 5
+
+    def self.body_for(event_name, payload, tenant_id)
+      JSON.generate(event: event_name, payload: payload, tenant_id: tenant_id)
+    end
+
+    def self.signature(secret, body)
+      "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret.to_s, body)}"
+    end
+
+    def perform(tenant_id, endpoint_id, event_name, payload)
+      tenant = Loam::Tenant.find_by(id: tenant_id)
+      return if tenant.nil?
+
+      Loam.as_tenant(tenant) do
+        endpoint = Loam::WebhookEndpoint.find_by(id: endpoint_id)
+        # The endpoint may have been deleted or switched off between enqueue
+        # and delivery — that is an answer, not an error.
+        next if endpoint.nil? || !endpoint.active?
+
+        deliver(endpoint, self.class.body_for(event_name, payload, tenant_id), event_name)
+      end
+    end
+
+    private
+
+    def deliver(endpoint, body, event_name)
+      uri = URI.parse(endpoint.url)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = TIMEOUT_SECONDS
+      http.read_timeout = TIMEOUT_SECONDS
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["X-Loam-Event"] = event_name
+      request["X-Loam-Signature"] = self.class.signature(endpoint.secret, body)
+      request.body = body
+
+      http.request(request)
+    end
+  end
+end

data/app/models/loam/api_token.rb

@@ -0,0 +1,40 @@
+module Loam
+  # A bearer token that lets a machine act as one user in one tenant. Same
+  # rules as a human session: whatever the token's user may do in that tenant,
+  # no more. Plumbing, so not audited and not evented.
+  class ApiToken < Loam::TenantRecord
+    self.table_name = "loam_api_tokens"
+
+    belongs_to :user
+
+    validates :token, presence: true, uniqueness: true
+
+    before_validation on: :create do
+      self.token ||= SecureRandom.hex(24)
+    end
+
+    # THE blessed cross-tenant lookup, and the reason it lives in the gem.
+    #
+    # A bearer token arrives with no tenant context — the token IS how the
+    # request discovers which tenant it belongs to, so this one query must
+    # bypass the tenant scope. That is exactly what host apps are forbidden to
+    # do (`test/loam_guardrails_test.rb` fails the build on it), so the escape
+    # hatch is vetted framework code here, used once, at the edge: find the
+    # token, establish Loam::Current, and everything downstream is ordinary
+    # tenant-scoped code again.
+    #
+    # Returns the token, or nil for an unknown/blank one — callers render 401.
+    def self.authenticate(raw_token)
+      return nil if raw_token.blank?
+
+      api_token = unscoped.find_by(token: raw_token)
+      return nil unless api_token
+
+      Loam::Current.tenant = api_token.tenant
+      Loam::Current.actor = api_token.user
+      api_token.update_column(:last_used_at, Time.current)
+
+      api_token
+    end
+  end
+end

data/app/models/loam/audit_record.rb

@@ -0,0 +1,18 @@
+module Loam
+  # One row per change: who (actor), what (auditable + action + changeset),
+  # when (created_at), in which tenant (tenant_id, via TenantRecord).
+  # Append-only by convention; not itself audited or evented.
+  class AuditRecord < Loam::TenantRecord
+    self.table_name = "loam_audit_records"
+
+    belongs_to :actor, class_name: "User", optional: true
+
+    validates :auditable_type, :auditable_id, :action, presence: true
+
+    serialize :changeset, coder: JSON
+
+    def auditable
+      auditable_type.constantize.unscoped.find_by(id: auditable_id)
+    end
+  end
+end

data/app/models/loam/auth_attempt.rb

@@ -0,0 +1,13 @@
+module Loam
+  # A single failed authentication attempt, for rate-limiting/lockout
+  # (Loam::AuthThrottle). Deliberately NOT tenant-scoped — authentication happens
+  # BEFORE a tenant is chosen (login), so this is a global auth-layer table keyed
+  # by the submitted identifier (the same reason Loam::MfaCredential is global).
+  # Allowlisted in the guardrails tenancy lint.
+  class AuthAttempt < ApplicationRecord
+    include Loam::GeneratedKey
+    self.table_name = "loam_auth_attempts"
+
+    validates :identifier, :kind, presence: true
+  end
+end

data/app/models/loam/business_rule.rb

@@ -0,0 +1,49 @@
+module Loam
+  # A per-tenant, admin-configurable rule: WHEN a condition holds THEN run
+  # actions. Declared as DATA (a trigger event pattern + a safe condition tree +
+  # a typed action list), never as code — see Loam::BusinessRules for the engine
+  # that evaluates it. Audited like any business record.
+  class BusinessRule < Loam::TenantRecord
+    self.table_name = "loam_business_rules"
+
+    include Loam::Auditable
+
+    has_many :runs, class_name: "Loam::BusinessRuleRun", dependent: :delete_all
+
+    validates :name, :trigger, presence: true
+    # A rule may only target a tenant-scoped model (or none, for an event-only
+    # rule). Refusing a global class like `User` at SAVE time means a poisoned
+    # rule can't even be persisted — kept in lockstep with
+    # Loam::BusinessRules.subject_for, which refuses the same at run time.
+    validate :entity_type_targets_a_tenant_record
+
+    scope :active, -> { where(active: true) }
+    scope :by_priority, -> { order(priority: :desc, id: :asc) }
+    scope :for_entity, ->(entity_type) { where(entity_type: entity_type.to_s) }
+
+    def matches_trigger?(event_name)
+      Loam::Events.pattern_matches?(trigger, event_name)
+    end
+
+    # The stored json, defensively — a hand-created row could hold a non-hash /
+    # non-array.
+    def condition_tree
+      condition.is_a?(Hash) ? condition : {}
+    end
+
+    def action_list
+      actions.is_a?(Array) ? actions : []
+    end
+
+    private
+
+    def entity_type_targets_a_tenant_record
+      return if entity_type.blank?  # event-only rule, no subject to load
+
+      klass = entity_type.safe_constantize
+      unless klass.is_a?(Class) && klass < Loam::TenantRecord
+        errors.add(:entity_type, "must name a Loam tenant-scoped model (not #{entity_type.inspect})")
+      end
+    end
+  end
+end

data/app/models/loam/business_rule_run.rb

@@ -0,0 +1,27 @@
+module Loam
+  # The log of why a business rule did (or did not) act — so the admin can see
+  # WHY something happened. Plumbing, like Loam::RecordLock: NOT audited (a log
+  # of a log is noise). Capped per rule so the table stays lean.
+  class BusinessRuleRun < Loam::TenantRecord
+    self.table_name = "loam_business_rule_runs"
+
+    KEEP_PER_RULE = 50
+
+    belongs_to :business_rule, class_name: "Loam::BusinessRule"
+
+    scope :recent, -> { order(created_at: :desc) }
+
+    after_create_commit :prune_old_runs
+
+    private
+
+    # Keep the last KEEP_PER_RULE runs per rule; drop the rest. Cheap and bounded.
+    def prune_old_runs
+      stale = self.class.where(business_rule_id: business_rule_id)
+                        .order(created_at: :desc)
+                        .offset(KEEP_PER_RULE)
+                        .ids
+      self.class.where(id: stale).delete_all if stale.any?
+    end
+  end
+end

data/app/models/loam/comment.rb

@@ -0,0 +1,28 @@
+module Loam
+  # A note by one person, on one record, in one tenant. Polymorphic, so any
+  # entity that `include Loam::Commentable` gets a discussion for free.
+  #
+  # Not audited on purpose: the comment IS the activity record. A
+  # Loam::AuditRecord saying "someone created a comment" beside a comment
+  # saying what they wrote is the same fact stored twice.
+  #
+  # Evented on purpose, in Loam's own domain ("loam.comment.created"), because
+  # a new comment is exactly the kind of thing an app wants to react to —
+  # notify the watchers, ping a webhook — without every app inventing its own
+  # event name for it.
+  class Comment < Loam::TenantRecord
+    include Loam::Eventful
+
+    self.table_name = "loam_comments"
+
+    event_domain :loam
+    event_entity :comment # not "loam_comment", which the namespace would give
+
+    belongs_to :commentable, polymorphic: true
+    belongs_to :author, class_name: "User"
+
+    validates :body, presence: true
+
+    scope :oldest_first, -> { order(:created_at) }
+  end
+end

data/app/models/loam/config.rb

@@ -0,0 +1,27 @@
+module Loam
+  # A single configuration setting: one namespaced key, one JSON-able value.
+  #
+  # Deliberately NOT a Loam::TenantRecord. A setting exists at two levels — a
+  # GLOBAL default (tenant_id NULL) that every tenant sees, and a per-tenant
+  # OVERRIDE (tenant_id set) that wins for that one tenant — so tenancy is a
+  # nullable column here, not a default_scope. Resolving a key means reading
+  # across both levels at once, which is why the lookup lives in vetted gem code
+  # (Loam::Configs), never in app code (see the tenancy allowlist in
+  # test/loam_guardrails_test.rb).
+  #
+  # The value goes in a json column, so a bool, number, string, array, or hash
+  # all round-trip under the same key. Row existence — not the value — is what
+  # marks a key as set, so the value may legitimately be JSON null.
+  class Config < ApplicationRecord
+    include Loam::GeneratedKey
+    self.table_name = "loam_configs"
+
+    belongs_to :tenant, class_name: "Loam::Tenant", optional: true
+
+    validates :key, presence: true
+    # One global per key, one override per key per tenant. AR renders the nil
+    # scope as `tenant_id IS NULL`, so this covers both cases; the two partial
+    # indexes in the migration are the race-proof guarantee behind it.
+    validates :key, uniqueness: { scope: :tenant_id }
+  end
+end