open-loam 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c2e0e075f887239d67b9dfdcefeeba0c825cc7c8faf1fe1f32c813e7916c687
-  data.tar.gz: 51b1ee994cfc4f118369463bc999c302e699232bd122e20cf19511e213a9fd91
+  metadata.gz: 7fda058767d913097dee8faac85c9957d680233405c3d57004cf786a9ccc155d
+  data.tar.gz: 87763cfa7c0fa23c24111d8dceda31d73c491b6b8ead4cd1559aaeb742c7df2e
 SHA512:
-  metadata.gz: be8e513778bc4d402e6365304054a865a64f96441868e079b6ccffe41a26046d5d8f8d40c7f2870e6fe33eb26dcace0f708e49a5df83d069a301977c0ad9329a
-  data.tar.gz: 3fd4050284ae72d54324b0b69a5aee6f9bd86939cf92dc4299a253e4c4d861c616ad8321def46b673816fd3afda85e245745d165115973deb1f8f86a19a83785
+  metadata.gz: 1d40e81813088308a110726cea561b9a2fa4496658e95b7292e64af28473d2363a6b629546892989fae52abd05cd13bddc76578fdd08257fed60f8736ca37efc
+  data.tar.gz: 97caae5c7991ccadff19905a0224959aa9c40b1c446dfc39dcae4a51bb575ce685c579d24836e92069c7b8b4788c20002d519e3e613556967c4e43e63bd90f87

data/CHANGELOG.md

@@ -1,20 +1,60 @@
 # Changelog
 
-Notable changes to Loam. This project follows [semantic versioning](https://semver.org),
+Notable changes to OpenLoam. 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.2.0 — 2026-09-05
+
+### BREAKING
+
+- **Ruby namespace renamed `Loam` → `OpenLoam`**, and every dependent
+  surface with it: the CLI (`rails g open_loam:install`,
+  `rails g open_loam:entity`, `bin/rails open_loam:mcp:serve`, etc.), all
+  `loam_*`-prefixed database tables and columns, `LOAM_*` env vars (now
+  `OPEN_LOAM_*`), and the outbound webhook signature header
+  (`X-Loam-Signature` → `X-OpenLoam-Signature`, tracked in
+  [BACKWARD_COMPATIBILITY.md](BACKWARD_COMPATIBILITY.md)). The RubyGems
+  package name is unaffected — it stays `open-loam`, as it already was.
+- No back-compat shim is provided for any of this. Per 0.1.0/0.1.1 above, no
+  production deployment exists yet, so there is nothing running against the
+  old names to break in place — an app installed from an 0.1.x generator
+  would need its own table/env-var renames to upgrade, which is why this
+  ships as a breaking 0.x release rather than a deprecation cycle.
+- One literal is deliberately **not** renamed, ever: the encryption
+  key-derivation inputs in `lib/open_loam/encryption/key_provider.rb`
+  (the HKDF `SALT` and `info` strings) and the AAD prefix in
+  `lib/open_loam/encryption.rb#aad`. These are inputs to key/tag
+  derivation, not identifiers — changing any of them would silently
+  break decryption of already-encrypted data.
+
+## 0.1.1 — 2026-09-04
+
+No functional change. The packaged code is byte-identical to 0.1.0 — only CI
+configuration moved, and workflows are not part of the gem.
+
+This version exists to exercise the release pipeline end to end, so that the
+first keyless publish is a version nothing depends on rather than one that
+matters.
+
+### Changed
+
+- Releases are published from CI using RubyGems trusted publishing. GitHub's
+  OIDC token is exchanged for short-lived credentials, so no API key is held on
+  a maintainer's machine or in repository secrets, and publishing is gated on an
+  approval in the `release` environment.
+
 ## 0.1.0 — 2026-09-04
 
-First public release. Loam is a working, tested prototype: the foundation and
+First public release. OpenLoam 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`
+- **Multi-tenancy** — `OpenLoam::TenantRecord` scopes every query, job and event to
+  the current tenant. A missing tenant context raises `OpenLoam::MissingTenantError`
   rather than silently widening a query.
 - **Authorization** — roles, policies, field-level write access, and
   deny-by-default wildcard feature permissions (`equipment.*`).
@@ -40,13 +80,13 @@ used it yet. Evaluate it as a prototype, not as proven infrastructure.
 
 - **`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
+- **Generators as the interface** — `open_loam:install` and `open_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
+- **A human-approval gate** — `OpenLoam::PendingActions` stages an agent-proposed
   mutation for review before it touches business data.
-- **The golden-tasks benchmark** and `Loam::Eval` scorer. Results, methodology
+- **The golden-tasks benchmark** and `OpenLoam::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.
@@ -58,7 +98,7 @@ used it yet. Evaluate it as a prototype, not as proven infrastructure.
   `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
+- `OpenLoam::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.
 

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Grzegorz Smajdor and Loam contributors
+Copyright (c) 2026 Grzegorz Smajdor and OpenLoam 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

data/README.md

@@ -1,6 +1,6 @@
-# Loam 🌱
+# OpenLoam 🌱
 
-**In short:** Loam is a Rails starter kit for business apps — multi-tenancy,
+**In short:** OpenLoam 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
@@ -12,7 +12,7 @@ safely extend, with human-approval gates before any agent write takes effect.
 
 ---
 
-## Why Loam exists
+## Why OpenLoam 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
@@ -24,13 +24,13 @@ write real features — *if* the codebase is legible to them. Sprawling, snowfla
 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
+OpenLoam 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
+most agent-friendly framework there is. OpenLoam 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
+## Where OpenLoam 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
@@ -39,7 +39,7 @@ 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.
+inspired OpenLoam. OpenLoam brings that idea to Rails, the substrate it always suited.
 
 ---
 
@@ -51,21 +51,21 @@ 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. |
+| 🔐 **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** (`OpenLoam::Permissions`): grant a role wildcard capability strings (`equipment.*`) and check `OpenLoam.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 `OpenLoam::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 (`OpenLoam::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. |
+| 📡 **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* (`OpenLoam::Events.subscribe`, in-process, synchronous, best-effort) for cheap fan-out, and *durable* (`OpenLoam::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. |
+| 🚩 **Feature flags** | Runtime on/off capabilities per tenant for rollout or kill-switch — a global default plus per-tenant override, a `OpenLoam::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. |
+| 🤖 **MCP server** | An [MCP](https://modelcontextprotocol.io) server (`bin/rails open_loam:mcp:serve`, stdio) exposes OpenLoam 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 OpenLoam 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. |
@@ -74,24 +74,24 @@ need to — never a blank page.
 | 🔎 **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. |
+| ⏳ **Task progress** | A long-running job (import, reindex, report) reports percent / counts / ETA to the admin, pushed **live over SSE** — no polling. `OpenLoam::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 (`open_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. |
+| 📜 **Auto OpenAPI** | The JSON API documents itself. `OpenLoam::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 `open_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. |
+| 🧬 **Override registry** | Disable or replace an entry in one of OpenLoam's keyed registries — a built-in dashboard widget, a default broadcast pattern — from an initializer, **without forking or monkeypatching**: `OpenLoam::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
+You write the **20% that is your business**. OpenLoam 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:
+OpenLoam 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.
@@ -111,7 +111,7 @@ for an agent or a human.
 
 **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
+benchmark. Some two dozen `OpenLoam::` modules, from tenancy through SSO, each
 added the same way: a small in-gem implementation behind a convention, wired to
 agree with the rest.
 
@@ -119,7 +119,7 @@ agree with the rest.
 
 | 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. |
+| `lib/` | The `open_loam` gem — every pillar as a small `OpenLoam::` module, plus the `open_loam:install` and `open_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. |
@@ -137,9 +137,9 @@ whole thesis in miniature.
 *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
+*behind the same `OpenLoam::` 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 demo runs on SQLite. See [How OpenLoam works](docs/_foundation/overview.md) for
 the pillar-by-pillar breakdown and the decisions behind them.
 
 **Try it**
@@ -161,14 +161,14 @@ showing the real commands and exactly what you *didn't* have to write.
 - [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
+- [How OpenLoam 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
+- [Agent pack](.open_loam/agents/) — everything an AI agent should load to extend a OpenLoam app correctly
 - [Manifesto](https://deliveristsio.github.io/open-loam/manifesto/)
 - [Contributing](CONTRIBUTING.md)
 

data/app/jobs/{loam → open_loam}/custom_field_reindex_job.rb

@@ -1,6 +1,6 @@
-module Loam
+module OpenLoam
   # Heals a custom-field index gap in the background: rebuilds one model's
-  # read-model index (Loam::CustomFieldIndex) for one tenant. Enqueued (deduped)
+  # read-model index (OpenLoam::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
@@ -9,14 +9,14 @@ module Loam
     queue_as :default
 
     def perform(tenant_id, model_name)
-      tenant = Loam::Tenant.find_by(id: tenant_id)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       model = model_name.to_s.safe_constantize
-      return unless tenant && model.is_a?(Class) && model < Loam::TenantRecord
+      return unless tenant && model.is_a?(Class) && model < OpenLoam::TenantRecord
 
-      Loam.as_tenant(tenant) { Loam::CustomFieldIndex.reindex(model) }
+      OpenLoam.as_tenant(tenant) { OpenLoam::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)
+      OpenLoam::CustomFieldIndex.clear_pending(tenant_id, model_name.to_s)
     end
   end
 end

data/app/jobs/{loam → open_loam}/event_delivery_job.rb

@@ -1,25 +1,25 @@
-module Loam
-  # Runs one durable event delivery (Loam::DurableEvents). Inherits
+module OpenLoam
+  # Runs one durable event delivery (OpenLoam::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).
+  # and carries the tenant explicitly (ActiveJob doesn't serialize OpenLoam::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.
+  # Retry state lives in the ROW (OpenLoam::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)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       return if tenant.nil?
 
-      Loam.as_tenant(tenant) do
-        delivery = Loam::EventDelivery.find_by(id: delivery_id)
+      OpenLoam.as_tenant(tenant) do
+        delivery = OpenLoam::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)
+        OpenLoam::DurableEvents.deliver(delivery)
       end
     end
   end

data/app/jobs/{loam → open_loam}/event_redelivery_sweep_job.rb

@@ -1,10 +1,10 @@
-module Loam
+module OpenLoam
   # 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`
+  # Registered per-tenant via OpenLoam::Scheduler (see OpenLoam::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.
@@ -12,10 +12,10 @@ module Loam
     queue_as :default
 
     def perform(tenant_id: nil)
-      tenant = Loam::Tenant.find_by(id: tenant_id)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       return if tenant.nil?
 
-      Loam.as_tenant(tenant) { Loam::DurableEvents.redeliver_stuck }
+      OpenLoam.as_tenant(tenant) { OpenLoam::DurableEvents.redeliver_stuck }
     end
   end
 end

data/app/jobs/{loam → open_loam}/webhook_delivery_job.rb

@@ -1,13 +1,13 @@
 require "net/http"
 require "openssl"
 
-module Loam
+module OpenLoam
   # 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
+  # endpoint's secret and compares it to X-OpenLoam-Signature. Body building and
   # signing are class methods so both sides — and the tests — can call them
   # without a network.
   class WebhookDeliveryJob < ActiveJob::Base
@@ -24,11 +24,11 @@ module Loam
     end
 
     def perform(tenant_id, endpoint_id, event_name, payload)
-      tenant = Loam::Tenant.find_by(id: tenant_id)
+      tenant = OpenLoam::Tenant.find_by(id: tenant_id)
       return if tenant.nil?
 
-      Loam.as_tenant(tenant) do
-        endpoint = Loam::WebhookEndpoint.find_by(id: endpoint_id)
+      OpenLoam.as_tenant(tenant) do
+        endpoint = OpenLoam::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?
@@ -49,8 +49,8 @@ module Loam
 
       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["X-OpenLoam-Event"] = event_name
+      request["X-OpenLoam-Signature"] = self.class.signature(endpoint.secret, body)
       request.body = body
 
       http.request(request)

data/app/models/{loam → open_loam}/api_token.rb

@@ -1,9 +1,9 @@
-module Loam
+module OpenLoam
   # 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"
+  class ApiToken < OpenLoam::TenantRecord
+    self.table_name = "open_loam_api_tokens"
 
     belongs_to :user
 
@@ -18,9 +18,9 @@ module Loam
     # 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
+    # do (`test/open_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
+    # token, establish OpenLoam::Current, and everything downstream is ordinary
     # tenant-scoped code again.
     #
     # Returns the token, or nil for an unknown/blank one — callers render 401.
@@ -30,8 +30,8 @@ module Loam
       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
+      OpenLoam::Current.tenant = api_token.tenant
+      OpenLoam::Current.actor = api_token.user
       api_token.update_column(:last_used_at, Time.current)
 
       api_token

data/app/models/{loam → open_loam}/audit_record.rb

@@ -1,9 +1,9 @@
-module Loam
+module OpenLoam
   # 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"
+  class AuditRecord < OpenLoam::TenantRecord
+    self.table_name = "open_loam_audit_records"
 
     belongs_to :actor, class_name: "User", optional: true
 

data/app/models/{loam → open_loam}/auth_attempt.rb

@@ -1,12 +1,12 @@
-module Loam
+module OpenLoam
   # A single failed authentication attempt, for rate-limiting/lockout
-  # (Loam::AuthThrottle). Deliberately NOT tenant-scoped — authentication happens
+  # (OpenLoam::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).
+  # by the submitted identifier (the same reason OpenLoam::MfaCredential is global).
   # Allowlisted in the guardrails tenancy lint.
   class AuthAttempt < ApplicationRecord
-    include Loam::GeneratedKey
-    self.table_name = "loam_auth_attempts"
+    include OpenLoam::GeneratedKey
+    self.table_name = "open_loam_auth_attempts"
 
     validates :identifier, :kind, presence: true
   end

data/app/models/{loam → open_loam}/business_rule.rb

@@ -1,20 +1,20 @@
-module Loam
+module OpenLoam
   # 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
+  # a typed action list), never as code — see OpenLoam::BusinessRules for the engine
   # that evaluates it. Audited like any business record.
-  class BusinessRule < Loam::TenantRecord
-    self.table_name = "loam_business_rules"
+  class BusinessRule < OpenLoam::TenantRecord
+    self.table_name = "open_loam_business_rules"
 
-    include Loam::Auditable
+    include OpenLoam::Auditable
 
-    has_many :runs, class_name: "Loam::BusinessRuleRun", dependent: :delete_all
+    has_many :runs, class_name: "OpenLoam::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.
+    # OpenLoam::BusinessRules.subject_for, which refuses the same at run time.
     validate :entity_type_targets_a_tenant_record
 
     scope :active, -> { where(active: true) }
@@ -22,7 +22,7 @@ module Loam
     scope :for_entity, ->(entity_type) { where(entity_type: entity_type.to_s) }
 
     def matches_trigger?(event_name)
-      Loam::Events.pattern_matches?(trigger, event_name)
+      OpenLoam::Events.pattern_matches?(trigger, event_name)
     end
 
     # The stored json, defensively — a hand-created row could hold a non-hash /
@@ -41,8 +41,8 @@ module Loam
       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})")
+      unless klass.is_a?(Class) && klass < OpenLoam::TenantRecord
+        errors.add(:entity_type, "must name a OpenLoam tenant-scoped model (not #{entity_type.inspect})")
       end
     end
   end

data/app/models/{loam → open_loam}/business_rule_run.rb

@@ -1,13 +1,13 @@
-module Loam
+module OpenLoam
   # 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
+  # WHY something happened. Plumbing, like OpenLoam::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"
+  class BusinessRuleRun < OpenLoam::TenantRecord
+    self.table_name = "open_loam_business_rule_runs"
 
     KEEP_PER_RULE = 50
 
-    belongs_to :business_rule, class_name: "Loam::BusinessRule"
+    belongs_to :business_rule, class_name: "OpenLoam::BusinessRule"
 
     scope :recent, -> { order(created_at: :desc) }
 

data/app/models/{loam → open_loam}/comment.rb

@@ -1,22 +1,22 @@
-module Loam
+module OpenLoam
   # A note by one person, on one record, in one tenant. Polymorphic, so any
-  # entity that `include Loam::Commentable` gets a discussion for free.
+  # entity that `include OpenLoam::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
+  # OpenLoam::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
+  # Evented on purpose, in OpenLoam's own domain ("open_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
+  class Comment < OpenLoam::TenantRecord
+    include OpenLoam::Eventful
 
-    self.table_name = "loam_comments"
+    self.table_name = "open_loam_comments"
 
-    event_domain :loam
-    event_entity :comment # not "loam_comment", which the namespace would give
+    event_domain :open_loam
+    event_entity :comment # not "open_loam_comment", which the namespace would give
 
     belongs_to :commentable, polymorphic: true
     belongs_to :author, class_name: "User"

data/app/models/{loam → open_loam}/config.rb

@@ -1,22 +1,22 @@
-module Loam
+module OpenLoam
   # A single configuration setting: one namespaced key, one JSON-able value.
   #
-  # Deliberately NOT a Loam::TenantRecord. A setting exists at two levels — a
+  # Deliberately NOT a OpenLoam::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).
+  # (OpenLoam::Configs), never in app code (see the tenancy allowlist in
+  # test/open_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"
+    include OpenLoam::GeneratedKey
+    self.table_name = "open_loam_configs"
 
-    belongs_to :tenant, class_name: "Loam::Tenant", optional: true
+    belongs_to :tenant, class_name: "OpenLoam::Tenant", optional: true
 
     validates :key, presence: true
     # One global per key, one override per key per tenant. AR renders the nil