@antelopejs/interface-dms 0.10.3 → 0.12.0

package/docs/1.core/5.tenancy.md

@@ -1,17 +1,16 @@
 ---
 title: "Tenancy"
-description: "The DMS serves several tenants from one backend."
+description: "Schema constants, tenancy tables, request tenant resolution, access gates, membership writes, and the tenant lifecycle contract."
+mode: reference
 ---
 
-# Tenancy
-
 ## Overview
 
-The DMS serves several tenants from one backend. Tenant-owned tables live in a per-tenant schema, and a model handle is bound to one tenant when you obtain it: `GetModel(TenantMemberModel, tenantId)` reads and writes that tenant's rows only. No query filters rows by tenant, and no table carries a `tenantId` column — the isolation is in the handle.
+The DMS serves several tenants from one backend. Tenant-owned tables live in a per-tenant schema, and a model handle is bound to one tenant when you obtain it. `GetModel(TenantMemberModel, tenantId)` reads and writes the rows of that tenant only. No query filters rows by tenant, and no table carries a `tenantId` column. The handle carries the isolation.
 
-For a first implementation, follow [Multi-tenant data](/docs/auth-and-tenancy/multi-tenant): register the table in the tenant schema, protect the route, and inject a tenant-bound model. Use this reference for the schema constants and lifecycle contracts. **Resolving a tenant id is not an authorization check**; `getRequestTenantId` must run behind authentication.
+For a first implementation, follow [Multi-tenant data](/docs/auth-and-tenancy/multi-tenant). It registers the table in the tenant schema, protects the route, and injects a tenant-bound model. This page lists the schema constants and the lifecycle contracts. Resolving a tenant id is not an authorization check, so `getRequestTenantId` must run behind authentication.
 
-The tenancy surface spans several subpaths:
+The tenancy exports span several subpaths:
 
 | Subpath | Contains |
 | ------- | -------- |
@@ -21,6 +20,7 @@ The tenancy surface spans several subpaths:
 | `@antelopejs/interface-dms/tenant-scoped-model` | Injecting a tenant-bound model |
 | `@antelopejs/interface-dms/tenant-access` | Tenant access gates |
 | `@antelopejs/interface-dms/tenant-ownership` | Membership and ownership writes |
+| `@antelopejs/interface-dms/tenant-members` | `changeTenantMembers`, the one write path for memberships and invitations |
 | `@antelopejs/interface-dms/tenant-lifecycle` | Producer admission and permanent closure before deletion |
 | `@antelopejs/interface-dms/utils/saas-mode` | Declaring SaaS mode |
 | `@antelopejs/interface-dms/data-controllers` | The built-in members and roles data controllers |
@@ -65,36 +65,35 @@ export class Invoice extends Table {
 }
 ```
 
-## The Tenancy Tables
+## The tenancy tables
 
-All three tables and their models are exported from `@antelopejs/interface-dms/db`, along with their table-name constants `tenantsTableName`, `tenantMembersTableName` and `ROLES_TABLE_NAME`.
+`@antelopejs/interface-dms/db` exports the three tables, their models, and the table-name constants `tenantsTableName`, `tenantMembersTableName` and `ROLES_TABLE_NAME`.
 
 ### `Tenant`
 
-Table `tenants` in `dms-core` — one row per tenant, shared across the backend.
+Table `tenants` in `dms-core`. It holds one row per tenant, shared across the backend.
 
 | Field | Type | Notes |
 | ----- | ---- | ----- |
-| `_id` | `string` | Tenant id. This is the instance id every per-tenant model handle takes. |
+| `_id` | `string` | Tenant id. Every per-tenant model handle takes it as the instance id. |
 | `name` | `string` | Display name. |
 | `createdAt` | `Date` | Creation time, indexed. |
 | `updatedAt` | `Date` | Update time, indexed. |
 
-`TenantModel` extends `BasicDataModel(Tenant, tenantsTableName)` and adds `getMany(ids: string[]): Promise<Tenant[]>`, which returns `[]` for an empty id list.
-
-Being a core-schema table, `TenantModel` is obtained without an instance id: `GetModel(TenantModel)`.
+`TenantModel` extends `BasicDataModel(Tenant, tenantsTableName)` and adds `getMany(ids: string[]): Promise<Tenant[]>`, which returns `[]` for an empty id list. `tenants` is a core-schema table, so you obtain the model without an instance id: `GetModel(TenantModel)`.
 
 ### `TenantMember`
 
-Table `tenant_members` in `dms-tenant` — one row per member of the tenant the handle is bound to.
+Table `tenant_members` in `dms-tenant`. It holds one row per member of the tenant the handle is bound to.
 
 | Field | Type | Notes |
 | ----- | ---- | ----- |
 | `_id` | `string` | Membership id. |
-| `userId` | `string` | Indexed, related to the `User` table of the [Auth](/docs/interfaces/auth/introduction) domain. |
+| `userId` | `string` | Related to the `User` table of the [Auth](/docs/interfaces/auth/introduction) domain. Indexed across tenant instances. |
 | `roleIds` | `string[]` | Related to `Role`, many. The roles whose grants make up the member's base permission set. |
 | `isTenantOwner` | `boolean` | Whether the member owns the tenant. |
-| `joinedAt` | `Date` | Creation time, indexed. |
+| `inviteDeliveryId` | `string`, optional | Ties this membership to the durable invite acceptance that created it. |
+| `joinedAt` | `Date` | Creation time. Indexed across tenant instances. |
 | `invitedBy` | `string \| null` | Indexed, related to `User`. |
 
 `TenantMemberModel` extends `BasicDataModel(TenantMember, tenantMembersTableName)`:
@@ -104,16 +103,16 @@ Table `tenant_members` in `dms-tenant` — one row per member of the tenant the
 | `getByUser(userId)` | `Promise<TenantMember \| undefined>` |
 | `existsByUser(userId)` | `Promise<boolean>` |
 | `listAll()` | `Promise<TenantMember[]>` |
-| `listOwners()` | `Promise<TenantMember[]>` — members with `isTenantOwner` set |
+| `listOwners()` | `Promise<TenantMember[]>`, the members with `isTenantOwner` set |
 | `listByUserWithTenantIds(userId)` | `Promise<Array<{ tenantId: string; member: TenantMember }>>` |
-| `getOldestByUser(userId)` | `Promise<{ tenantId: string; member: TenantMember } \| undefined>` — earliest `joinedAt` |
+| `getOldestByUser(userId)` | `Promise<{ tenantId: string; member: TenantMember } \| undefined>`, the row with the earliest `joinedAt` |
 | `countOwnersExcluding(excludedUserIds)` | `Promise<number>` |
 
-The two methods that return a `tenantId` alongside the row report which tenant each row came from, which is what a lookup that spans instances needs.
+`listByUserWithTenantIds` and `getOldestByUser` return the tenant each row came from. A lookup that spans tenant instances needs that id.
 
 ### `Role`
 
-Table `roles` in `dms-tenant` — the tenant's roles.
+Table `roles` in `dms-tenant`. It holds the roles of the tenant.
 
 | Field | Type | Notes |
 | ----- | ---- | ----- |
@@ -121,13 +120,14 @@ Table `roles` in `dms-tenant` — the tenant's roles.
 | `createdAt` | `Date` | Creation time, indexed. |
 | `updatedAt` | `Date` | Update time, indexed. |
 | `name` | `string` | Indexed. |
+| `description` | `string \| null`, optional | What the role is for, shown in the roles editor. Absent on older rows. |
 | `permissions` | `string[]` | Granted permission ids ([Permissions](/docs/interfaces/core/permissions)). |
 
 `RoleModel` extends `BasicDataModel(Role, ROLES_TABLE_NAME)` and adds `getByName(name): Promise<Role | undefined>`.
 
-## Resolve the Request's Tenant
+## Resolve the request's tenant
 
-`getRequestTenantId(ctx)` returns the tenant of the request's **verified** credential, bound by the DMS auth decorators (`AuthUser`, `AuthRawUser`, `IfAuthUser` with a valid token, `AuthOwnerOnly`, `AuthUserWithPermission`, the auth a `PageController` installs), the tenant guards or `authenticateRequestUser`. Without a verified credential (anonymous request, invalid or forged token) it returns `DEFAULT_TENANT_ID`; a token is never read for its tenant before its signature, user and session are checked.
+`getRequestTenantId(ctx)` returns the tenant of the request's verified credential. The DMS binds that credential in the auth decorators (`AuthUser`, `AuthRawUser`, `IfAuthUser` with a valid token, `AuthOwnerOnly`, `AuthUserWithPermission`, and the auth a `PageController` installs), in the tenant guards (`AuthTenantMember`, `AuthTenantOwner` and `authenticateTenantRequest`), and in `authenticateRequestUser`. Without a verified credential, such as an anonymous request or an invalid or forged token, it returns `DEFAULT_TENANT_ID`. The DMS never reads a token's tenant before it checks the token's signature, user and session. When the request's authentication failed, or its `Authorization` header changed after authentication, `getRequestTenantId` throws `HTTPResult(401)`.
 
 ```typescript
 import {
@@ -148,11 +148,11 @@ export class WorkspaceController extends Controller("/api/workspace") {
 }
 ```
 
-Call it in the handler, after the route's auth decorator ran. A parameter or property provider that may run before it uses `resolveRequestTenantId(ctx)` (async), which verifies a bearer token itself and binds its tenant; `TenantScopedModel` does. Resolving a tenant is still not authorization: check membership and permissions for the operation.
+Call it in the handler, after the route's auth decorator ran. A parameter or property provider resolved alongside the auth decorator uses `resolveRequestTenantId(ctx)` instead. That async function waits for the tenant guards and credential checks the route's other providers start, and answers the tenant they verified. Without one, it verifies a bearer token itself and binds its tenant. A request without a verified credential reads as anonymous, and a credential verified on it later answers 401. `TenantScopedModel` uses it. A resolved tenant still authorizes nothing, so check membership and permissions for the operation.
 
-## Scope a Model to the Request's Tenant
+## Scope a model to the request's tenant
 
-`TenantScopedModel(ModelClass)` is a parameter and property decorator that injects `GetModel(ModelClass, await resolveRequestTenantId(ctx))`: the tenant of the verified credential, `DEFAULT_TENANT_ID` without one.
+`TenantScopedModel(ModelClass)` is a parameter and property decorator. It injects `GetModel(ModelClass, await resolveRequestTenantId(ctx))`, which is the tenant of the verified credential, or `DEFAULT_TENANT_ID` without one.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -172,9 +172,9 @@ export class RoleController extends Controller("/api/roles") {
 }
 ```
 
-As a property decorator it fills a data controller's `@ModelReference()` field:
+As a property decorator, it fills the `@ModelReference()` field of a data controller:
 
-```typescript
+```typescript fragment
 import { ModelReference } from "@antelopejs/interface-data-api/metadata";
 import { RoleModel } from "@antelopejs/interface-dms/db";
 import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
@@ -185,13 +185,13 @@ import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model
 declare model: RoleModel;
 ```
 
-Only use it for a model whose table lives in `TENANT_SCHEMA_NAME` or another schema with one instance per tenant. For a core-schema table, take the model without an instance id.
+Use it only for a model whose table lives in `TENANT_SCHEMA_NAME` or another schema with one instance per tenant. For a core-schema table, take the model without an instance id.
 
-## Tenant Access Gates
+## Tenant access gates
 
-A gate is a binary, tenant-level check, evaluated at every tenant authorization surface. It answers whether the tenant may use the product at all, independently of any permission set.
+A gate is a binary check at tenant level. It decides whether the tenant may use the product at all, independently of any permission set. The DMS evaluates the gates at every tenant authorization point: permission guards, the tenant member and owner guards, table view data routes, page and menu visibility, and realtime page access.
 
-```typescript
+```typescript fragment
 import { RegisterTenantAccessGate } from "@antelopejs/interface-dms/tenant-access";
 
 export async function construct(): Promise<void> {
@@ -217,26 +217,24 @@ type TenantAccessGateFn = (
 ) => Promise<TenantAccessResult> | TenantAccessResult;
 ```
 
-`TenantAccessGateInfo` carries `id`, `gate` and `order`.
-
-Semantics the interface guarantees:
+`TenantAccessGateInfo` carries `id`, `gate` and `order`. The interface guarantees these semantics:
 
-- Gates run in ascending `order`, ties in registration order; the first denial wins and its `code` is what reaches the client.
-- Registering an id twice replaces the earlier gate rather than adding a second one.
+- Gates run in ascending `order`, and ties run in registration order. The first denial wins, and its `code` reaches the client.
+- Registering an id a second time replaces the earlier gate. It does not add a second gate.
 - A gate that throws fails the request.
 - The registration is removed when the registering module unloads.
-- Register in `construct()` so the gate is active before the API serves requests.
+- Register in `construct()`, so the gate is active before the API serves requests.
 - `userId` is `undefined` for an unauthenticated request.
 
-Two functions evaluate the gates:
+Three functions evaluate the gates:
 
 | Function | Behavior |
 | -------- | -------- |
 | `CheckTenantAccess(userId, tenantId)` | Resolves to the first denial, or `{ allowed: true }`. |
-| `AssertTenantAccess(userId, tenantId)` | Calls `CheckTenantAccess` and throws a `403` whose body is the denying gate's `code`. |
-| `EvaluateTenantAccess(userId, tenantId)` | Server-side only. Resolves to every denial as `{ gateId, code }[]`, in gate order, `[]` when none; a gate that throws rejects the whole evaluation. |
+| `AssertTenantAccess(userId, tenantId)` | Calls `CheckTenantAccess` and throws a `403` whose body is the `code` of the denying gate. |
+| `EvaluateTenantAccess(userId, tenantId)` | Server-side only. Resolves to every denial as `TenantAccessDenial[]` (`{ gateId, code }`), in gate order, and to `[]` when no gate denies. A gate that throws rejects the whole evaluation. |
 
-```typescript
+```typescript fragment
 import {
   AssertTenantAccess,
   CheckTenantAccess,
@@ -250,17 +248,17 @@ if (!access.allowed) {
 await AssertTenantAccess(user._id, tenantId); // or let it throw
 ```
 
-`AuthTenantOwner` and `AuthTenantMember` call `AssertTenantAccess` unless the route opts out with `bypassTenantAccessGate` ([Permissions](/docs/interfaces/core/permissions)).
+`AuthTenantOwner` and `AuthTenantMember` call `AssertTenantAccess` unless the route opts out with `bypassTenantAccessGate` ([Permissions](/docs/interfaces/core/permissions)). A table view opts out with the option of the same name in `TableViewOptions`. Routes that must stay reachable for a denied tenant, such as billing or recovery, use these options.
 
-`EvaluateTenantAccess` exists for modules that must know whether a denial other than their own is in place, for example before lifting a hold: identify gates by `gateId`, never by `code`, which two gates may share. Its result is an observation, not an authorization receipt or an atomic snapshot of external state; revalidate before acting on it.
+`EvaluateTenantAccess` is for a module that must know whether another denial is in place, for example before it lifts its own hold. Identify gates by `gateId`, never by `code`, because two gates may share a code. The result is an observation. It is not an authorization receipt or an atomic snapshot of external state, so revalidate before you act on it.
 
-Use a gate to deny a tenant outright; use a permissions resolver to shape what its users may do.
+A gate denies a tenant outright. To shape what the users of a tenant may do, use a permissions resolver.
 
-## Memberships and Ownership
+## Memberships and ownership
 
-`applyTenantOwnership(userModel, userId, tenantId, patch)` upserts a membership row for the user in the tenant.
+`applyTenantOwnership(userModel, userId, tenantId, patch)` adds the user to the tenant, or sets the roles and ownership of an existing member.
 
-```typescript
+```typescript fragment
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import { applyTenantOwnership } from "@antelopejs/interface-dms/tenant-ownership";
 import { UserModel } from "@antelopejs/interface-dms/auth/db";
@@ -277,9 +275,10 @@ await applyTenantOwnership(GetModel(UserModel), userId, tenantId, {
 | ----- | ---- | ----------- |
 | `roleIds` | `string[]` | Roles the member holds after the write. Replaces the previous list. |
 | `isTenantOwner` | `boolean` | Ownership flag after the write. |
-| `invitedBy` | `string \| null` | Recorded on insert. Ignored when the membership row already exists. |
+| `invitedBy` | `string \| null`, optional | Recorded on insert. Ignored when the membership row already exists. |
+| `deliveryId` | `string`, optional | Durable invite delivery. It grants membership without replacing later edits. |
 
-`applyTenantOwnership` goes through [`changeTenantMembers`](#changetenantmembers), which fires `Hook.MEMBER_BEING_CHANGED` before any write, so a module can veto it. When the user is not yet a member, it also fires `Hook.MEMBER_BEING_ADDED` before the write and `Hook.MEMBER_ADDED` after it. For an existing member it updates `roleIds` and `isTenantOwner` and fires neither of those two ([Hooks](/docs/interfaces/core/hooks)).
+`applyTenantOwnership` goes through [`changeTenantMembers`](#changetenantmembers), which fires `Hook.MEMBER_BEING_CHANGED` before any write, so a module can veto it. When the user is not a member yet, it also fires `Hook.MEMBER_BEING_ADDED` before the write and `Hook.MEMBER_ADDED` after it. For an existing member, it updates `roleIds` and `isTenantOwner` and fires neither of those two hooks ([Hooks](/docs/interfaces/core/hooks)).
 
 Two helpers keep the legacy platform-owner flag on the user row aligned with tenant ownership:
 
@@ -288,11 +287,11 @@ Two helpers keep the legacy platform-owner flag on the user row aligned with ten
 | `syncPlatformOwnerOnTenantOwnerChange` | `(userModel, userId, tenantId, nextIsTenantOwner: boolean) => Promise<void>` |
 | `clearPlatformOwnerOnMemberRemoval` | `(userModel, userId, tenantId, removedMemberWasTenantOwner: boolean) => Promise<void>` |
 
-Both mirror the value onto `User.owner`, and both are no-ops outside the default tenant and when the backend runs in [SaaS mode](#saas-mode) — where `User.owner` means platform ownership rather than tenant ownership. `clearPlatformOwnerOnMemberRemoval` additionally does nothing when the removed member was not a tenant owner. Call them after a write that changes ownership by a path other than `applyTenantOwnership`, which already mirrors on its own.
+Both mirror the value onto `User.owner`. Both do nothing outside the default tenant, and nothing when the backend runs in [SaaS mode](#registersaasmode), where `User.owner` means platform ownership. `clearPlatformOwnerOnMemberRemoval` also does nothing when the removed member was not a tenant owner. Call them after a write that changes ownership without `applyTenantOwnership`, which mirrors the flag itself.
 
-### SaaS Mode
+### `RegisterSaasMode`
 
-By default, the owners of the default tenant are the platform owners. In SaaS mode the two are independent: tenant owners are customers, and platform ownership is managed on its own. The SaaS module declares that mode itself with `RegisterSaasMode`; the DMS never infers it from the modules it finds loaded.
+By default, the owners of the default tenant are the platform owners. In SaaS mode the two are independent. Tenant owners are customers, and platform ownership is managed separately. The SaaS module declares the mode itself with `RegisterSaasMode`. The DMS never infers it from the modules it finds loaded.
 
 ```typescript
 import { RegisterSaasMode } from "@antelopejs/interface-dms/utils/saas-mode";
@@ -304,82 +303,104 @@ export async function construct(): Promise<void> {
 
 While SaaS mode is on:
 
-- the default tenant's owner flag is no longer mirrored onto `User.owner`, by `applyTenantOwnership` or by the two helpers above;
-- removing members from the default tenant no longer refuses to remove the last platform owner.
+- `applyTenantOwnership` and the two helpers above no longer mirror the default tenant's owner flag onto `User.owner`.
+- Removing members from the default tenant no longer refuses to remove the last platform owner.
 
-The registration is removed when the registering module unloads, and the mode stays on while at least one registration is active. `isSaasMode()` resolves to the current state, `false` until a module registers. Both behaviours read it on every request, so it does not matter whether the SaaS module registers before or after the DMS starts.
+The registration is removed when the registering module unloads. The mode stays on while at least one registration is active. `isSaasMode()` resolves to the current state, and to `false` until a module registers. Both behaviors read the mode on every request, so the SaaS module may register before or after the DMS starts.
 
-## Tenant Lifecycle Admission
+## Tenant lifecycle admission
 
-Membership and invite producers coordinate with tenant deletion through `@antelopejs/interface-dms/tenant-lifecycle`. This is a write-lifecycle contract, not an authorization check or a transaction: authorize the caller separately.
+Membership and invite producers coordinate with tenant deletion through `@antelopejs/interface-dms/tenant-lifecycle`. This contract orders writes against deletion. It is not an authorization check or a transaction, so authorize the caller separately.
 
 ### `changeTenantMembers`
 
-Every insert, update or delete of a `TenantMemberModel` or `UserInviteModel` row goes through one entry point, `changeTenantMembers` from `@antelopejs/interface-dms/tenant-members`. The DMS uses it for every membership and invitation write it makes: adding a member, changing a member's roles or ownership (from the members table or the owner route), removing a member, moving the holders of a deleted role, leaving each tenant when an account is deleted, and creating, editing, resending, cancelling, expiring and accepting invitations. A module writing these rows itself must use it too; there is no other supported write path, and a raw `GetModel(...).insert/update/delete` on them skips both the barrier and the policy hook.
+Every insert, update or delete of a `TenantMemberModel` or `UserInviteModel` row goes through one entry point, `changeTenantMembers` from `@antelopejs/interface-dms/tenant-members`. The DMS uses it for every membership and invitation write it makes:
 
-```typescript
+- adding a member;
+- changing a member's roles or ownership, from the members table or the owner route;
+- removing a member, and moving the holders of a deleted role;
+- leaving each tenant when an account is deleted;
+- creating, editing, resending, cancelling, expiring and accepting invitations.
+
+A module that writes these rows itself must use it too. There is no other supported write path. A raw `GetModel(...).insert`, `update` or `delete` on these rows skips both the barrier and the policy hook.
+
+```typescript fragment
 changeTenantMembers<T>(
   tenantId: string,
-  plan: () => Promise<{ changes: MemberChange[]; write: () => Promise<T> }>,
+  plan: () => Promise<TenantMembersWrite<T>>,
 ): Promise<T>
+
+interface TenantMembersWrite<T> {
+  changes: MemberChange[];
+  write: () => Promise<T>;
+}
 ```
 
-It runs, in order:
+It runs these steps in order:
 
-1. `runTenantLifecycleOperation(tenantId, ...)`: refused at once, before anything is read, while a [barrier](#pausing-admission) is held or once admission is closed;
-2. `plan()`, inside the admission, which reads the current rows and describes the change;
-3. `Hook.MEMBER_BEING_CHANGED` once per `MemberChange`, with `{ tenantId, ...change }`. A throwing handler refuses the write, replays of an invitation acceptance included;
-4. `write()`, then the admission is released as `runTenantLifecycleOperation` describes.
+1. `runTenantLifecycleOperation(tenantId, ...)`. While a [barrier](#pausing-admission) is held, or once admission is closed, the call is refused at once, before anything is read.
+2. `plan()`, inside the admission. It reads the current rows and describes the change.
+3. `Hook.MEMBER_BEING_CHANGED`, once per `MemberChange`, with `{ tenantId, ...change }`. A throwing handler refuses the write, and that includes replays of an invitation acceptance.
+4. `write()`. The admission is then released as `runTenantLifecycleOperation` describes.
 
 A `MemberChange` has a `kind`:
 
 | `kind` | Fields | When |
 | ------ | ------ | ---- |
-| `added` | `userId`, `isTenantOwner`, `roleIds`, `deliveryId?` | A user joins: direct add, or an invitation accepted (`deliveryId` set) |
-| `removed` | `userId`, `isTenantOwner` | A member is removed, or leaves by deleting their account |
-| `roles` | `userId`, `roleIds`, `previousRoleIds` | A member's roles change, including when a deleted role is reassigned |
-| `ownership` | `userId`, `isTenantOwner`, `previousIsTenantOwner` | A member is given or loses the owner role |
+| `added` | `userId`, `isTenantOwner`, `roleIds`, `deliveryId?` | A user joins by direct add, or by an accepted invitation (`deliveryId` set). |
+| `removed` | `userId`, `isTenantOwner` | A member is removed, or leaves by deleting their account. |
+| `roles` | `userId`, `roleIds`, `previousRoleIds` | A member's roles change, including when a deleted role is reassigned. |
+| `ownership` | `userId`, `isTenantOwner`, `previousIsTenantOwner` | A member is given or loses the owner role. |
 
-One edit setting both roles and ownership announces two changes. A write that changes no membership (an invitation created, edited or retired) passes `changes: []`: it is still admitted, and invitation creation keeps its own `Hook.INVITE_BEING_CREATED`. Do not call `changeTenantMembers` from inside another `changeTenantMembers` or `runTenantLifecycleOperation` callback.
+One edit that sets both roles and ownership announces two changes. A write that changes no membership, such as an invitation created, edited or retired, passes `changes: []`. The write is still admitted, and invitation creation keeps its own `Hook.INVITE_BEING_CREATED`. Do not call `changeTenantMembers` from inside another `changeTenantMembers` or `runTenantLifecycleOperation` callback, because each call takes its own admission.
 
-Deleting an account makes one call per tenant the user belongs to, in turn. A tenant holding a barrier refuses its call, which stops the deletion there: the account and its remaining memberships stay, and the user can retry once the barrier is released.
+Deleting an account makes one call per tenant the user belongs to, one after the other. A tenant that holds a barrier refuses its call, and the deletion stops there. The account and its remaining memberships stay, and the user can retry once the barrier is released.
 
 ### `runTenantLifecycleOperation`
 
-`runTenantLifecycleOperation<T>(tenantId: string, work: () => Promise<T>): Promise<T>` admits one invocation before calling `work`, then returns its result after releasing that invocation's admission. Closed admission rejects without running `work`. Membership and invitation writes use it through `changeTenantMembers`; call it directly only for other work that must coordinate with tenant deletion, and await every effect, with no detached writer.
+`runTenantLifecycleOperation<T>(tenantId: string, work: () => Promise<T>): Promise<T>` admits one invocation, calls `work`, then releases that admission and returns the result. Closed admission rejects without running `work`. Membership and invitation writes use it through `changeTenantMembers`. Call it directly only for other work that must coordinate with tenant deletion. That work must await every effect and start no detached writer.
 
-A successful callback releases its admission. A deliberate HTTP 4xx refusal also attempts release and rethrows the original refusal; other failures retain admission because their effects may be indeterminate. Retrying is a new invocation and never retires the failed one's identity. There is no automatic expiry or reconciliation API.
+A successful callback releases its admission. A deliberate refusal, an `HTTPResult` with a 4xx status, also releases its admission and rethrows the original refusal. The release is tried three times. If every try fails, the admission stays and the call rejects. After a refusal it rejects with an `AggregateError` of the refusal and the release failure. After a success it rejects with the release failure. Any other failure retains the admission, because its effects may be indeterminate. A retry is a new invocation and never retires the identity of the failed one. There is no automatic expiry and no reconciliation API.
 
-### Pausing Admission
+### Pausing admission
 
 A module that must validate a tenant's inventory with no membership writer in flight, such as a plan downgrade, pauses admission instead of closing it:
 
 | Function | Behavior |
 | -------- | -------- |
-| `observeTenantLifecycle(tenantId)` | Resolves to `{ revision, barrierId, activeAttemptIds, closed }`. Never retires an attempt. |
-| `pauseTenantLifecycleAdmission(tenantId, barrierId, expectedRevision)` | Publishes the barrier with one compare-and-set on `expectedRevision`. Resolves `false` when the revision moved, a barrier is held or admission is closed. |
-| `resumeTenantLifecycleAdmission(tenantId, barrierId)` | Releases this barrier; with no barrier held, it invalidates the revision so a delayed `pause` fails. Resolves `false` for another owner's barrier or closed admission. |
+| `observeTenantLifecycle(tenantId)` | Resolves to a `TenantLifecycleObservation`: `{ revision, barrierId, activeAttemptIds, closed }`. Never retires an attempt. |
+| `pauseTenantLifecycleAdmission(tenantId, barrierId, expectedRevision)` | Publishes the barrier with one compare-and-set on `expectedRevision`. Resolves `false` when the revision moved, a barrier is held, or admission is closed. |
+| `resumeTenantLifecycleAdmission(tenantId, barrierId)` | Releases this barrier. With no barrier held, it invalidates the revision so that a delayed `pause` fails. Resolves `false` for the barrier of another owner or for closed admission. |
+
+While a barrier is held, `runTenantLifecycleOperation` rejects new work without running it, with an `HTTPResult` 409 (`Tenant lifecycle admission is paused`). The refusal writes nothing and retains no admission, and the caller may retry once the barrier is released. Admitted work keeps running.
 
-While a barrier is held, `runTenantLifecycleOperation` rejects new work without running it, with an `HTTPResult` 409 (`Tenant lifecycle admission is paused`): a deliberate refusal with nothing written and no admission retained, which the caller may retry once the barrier is released. Admitted work keeps running. Observe the revision before checking your own business intent, pause with that revision, recheck the intent, then wait for an observation with no active attempt before validating. A `false` from `pause` needs a new observation, not a blind retry. Use a unique `barrierId` per phase, and do not observe or pause from inside a `runTenantLifecycleOperation` callback: the caller would wait for itself.
+Follow this order:
+
+1. Observe the revision before you check your own business intent.
+2. Pause with that revision.
+3. Check the intent again. If you abandon it, resume.
+4. Wait for an observation with no active attempt, then validate.
+
+A `false` from `pause` needs a new observation, not a blind retry. Use a unique `barrierId` for each phase. Do not observe or pause from inside a `runTenantLifecycleOperation` callback, because the caller would wait for itself.
 
 ### `closeTenantLifecycleAdmission`
 
-`closeTenantLifecycleAdmission(tenantId: string): Promise<void>` permanently closes admission, then checks that no admitted operation remains. It rejects if work is active or indeterminate, or if the database cannot confirm the transition. Rejection can leave admission closed: it never authorizes deletion or reopening.
+`closeTenantLifecycleAdmission(tenantId: string): Promise<void>` closes admission permanently, then checks that no admitted operation remains. It rejects if work is active or indeterminate, or if the database cannot confirm the transition. A rejection can leave admission closed. It never authorizes deletion or reopening.
 
-Call it before any destructive tenant phase, including deletion hooks. Do not delete business data when closure rejects. Preserve the `tenant_lifecycle` and `invite_resolutions` safety rows after deletion; dropping the tenant schema or recreating those rows can reopen admission. Mixed-version writers and raw model writes bypassing admission prevent a safe rollout. These table names describe a preservation obligation, not supported raw-model APIs.
+Call it before any destructive tenant phase, including deletion hooks. Do not delete business data when closure rejects. Preserve the `tenant_lifecycle` and `invite_resolutions` safety rows after deletion, because dropping the tenant schema or recreating those rows can reopen admission. Writers on mixed versions, and raw model writes that bypass admission, prevent a safe rollout. These table names describe what to preserve. They are not supported raw-model APIs.
 
-The [backend-services guide](/docs/building/backend-services#tenant-deletion-closes-producer-admission-first) explains where this fits in a module's deletion flow.
+The [backend services guide](/docs/building/backend-services#tenant-deletion-closes-producer-admission-first) shows where closure fits in a module's deletion flow.
 
-## Built-in Data Controllers
+## Built-in data controllers
 
-The interface ships the two data controllers the built-in settings screens are built on. The DMS module registers both itself, so their routes exist as soon as it is loaded: reference them, do not register them again.
+The interface ships the two data controllers behind the built-in settings screens. The DMS module registers both itself, so their routes exist as soon as it is loaded. Reference them, and do not register them again.
 
 | Export | Import from | Table | Base path |
 | ------ | ----------- | ----- | --------- |
 | `memberSettingDataAPI` | `@antelopejs/interface-dms/data-controllers` | `TenantMember` | `/api/tables/members` |
 | `roleSettingDataAPI` | `@antelopejs/interface-dms/data-controllers/roles` | `Role` | `/api/tables/roles` |
 
-The `/data-controllers` barrel re-exports the members controller only; the roles controller is imported from its own path.
+The `/data-controllers` barrel re-exports the members controller only. Import the roles controller from its own path.
 
 ```typescript
 import { roleSettingDataAPI } from "@antelopejs/interface-dms/data-controllers/roles";
@@ -397,8 +418,13 @@ const reviewerRolesField = {
 };
 ```
 
-Both bind their model with `TenantScopedModel`, so they read and write the request's tenant. `memberSettingDataAPI` exposes the member's `name` and `email` joined from the `User` table, the member's roles as a plain relation onto `roleSettingDataAPI` (the DMS members page draws it with its own role picker, through the edit form's component slot), `isTenantOwner`, `joinedAt`, `isValidated` and a computed `connected` field; `roleSettingDataAPI` exposes `name`, `permissions`, `createdAt` and `updatedAt`. Reference either one as the relation target of your own columns when you need a member or role picker, or feed one to a `TableView` to render it.
+Both bind their model with `TenantScopedModel`, so they read and write the request's tenant.
+
+- `memberSettingDataAPI` exposes `_id`, `userId`, the member's `name`, `email`, `avatar`, `isValidated`, `lastActiveAt` and `twoFactorMethods` joined from the `User` table, the member's `roleIds` as a plain relation onto `roleSettingDataAPI`, `isTenantOwner`, and `joinedAt`. The DMS members page draws the roles with its own role picker, through the component slot of the edit form. The controller mounts every default table route except `new`, `archive` and `restore`.
+- `roleSettingDataAPI` exposes `_id`, `name`, `permissions`, `createdAt` and `updatedAt`, with every default table route.
+
+Reference either controller as the relation target of your own columns when you need a member or role picker, or pass one to a `TableView` to render it.
 
-## Next Steps
+## Next steps
 
 [Invites](/docs/interfaces/core/invites) covers bringing a user into a tenant that has no membership row for them yet.