@antelopejs/interface-dms 0.7.4 → 0.8.0

package/dist/request-tenant.js

@@ -1,58 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRequestTenantId = getRequestTenantId;
-const jsonwebtoken_1 = require("jsonwebtoken");
+exports.resolveRequestTenantId = resolveRequestTenantId;
+const auth_1 = require("./auth");
 const request_authenticators_1 = require("./auth/internal/request-authenticators");
 const constants_1 = require("./constants");
-const BEARER_PREFIX = "Bearer ";
-function extractBearerToken(authHeader) {
-    if (typeof authHeader !== "string")
-        return undefined;
-    if (!authHeader.startsWith(BEARER_PREFIX))
-        return undefined;
-    return authHeader.slice(BEARER_PREFIX.length);
+const BEARER_SCHEME = /^Bearer\s+(\S+)$/i;
+const pendingResolutions = new WeakMap();
+/**
+ * The tenant of the request's verified credential: the one bound by the DMS
+ * auth decorators (`AuthUser`, `AuthUserWithPermission`, `IfAuthUser` with a
+ * valid token…), the tenant guards or `authenticateRequestPrincipal`.
+ * Without a verified credential, `DEFAULT_TENANT_ID`: a token is never read
+ * for its tenant before its signature, user and session are checked.
+ *
+ * Call it once the route's auth decorator has run (in the handler). A
+ * parameter or property provider resolved alongside the auth decorator uses
+ * {@link resolveRequestTenantId} instead.
+ *
+ * @throws HTTPResult 401 when the request's authentication failed or its
+ * credential changed since
+ */
+function getRequestTenantId(ctx) {
+    return (0, request_authenticators_1.getAuthenticatedRequestTenantId)(ctx) ?? constants_1.DEFAULT_TENANT_ID;
 }
-function readTenantIdFromToken(token) {
+async function verifyRequestTenantId(ctx, token) {
     try {
-        const payload = (0, jsonwebtoken_1.decode)(token);
-        if (payload &&
-            typeof payload.tenantId === "string" &&
-            payload.tenantId.length > 0) {
-            return payload.tenantId;
-        }
+        const data = await auth_1.internal.IfAuthUserAuthenticator(token);
+        if (!data)
+            return constants_1.DEFAULT_TENANT_ID;
+        const user = await auth_1.internal.AuthRawUserValidator(data);
+        if (!user || typeof user === "boolean")
+            return constants_1.DEFAULT_TENANT_ID;
+        const tenantId = data.tenantId || constants_1.DEFAULT_TENANT_ID;
+        (0, request_authenticators_1.bindVerifiedRequestPrincipal)(ctx, { userId: user._id, tenantId });
+        return tenantId;
     }
     catch {
-        return undefined;
+        return constants_1.DEFAULT_TENANT_ID;
     }
-    return undefined;
 }
 /**
- * Prefer the tenant bound by authenticateRequestPrincipal or the tenant guards.
- * An authentication failure or changed credential makes this accessor throw.
- * Without a bound principal, preserve legacy JWT decoding / DEFAULT_TENANT_ID.
- *
- * The legacy value is only *decoded*: this function does NOT verify the
- * JWT signature. It is safe when the request has already been authenticated
- * upstream (auth decorators such as `@AuthUser`, `@AuthTenantMember`, or the
- * gating performed by `PageController`) — those validators verify the signature
- * before this function runs, so the decoded `tenantId` is authentic.
- *
- * For routes that legitimately accept anonymous traffic (e.g. `@IfAuthUser`),
- * the fallback resolves to `DEFAULT_TENANT_ID` so public layouts can be served.
- *
- * Do NOT introduce new routes that rely on `tenantId` for authorization without
- * upstream auth verification — without signature checks, the claim is forgeable.
+ * {@link getRequestTenantId} for a provider that may run before the route's
+ * auth decorator (`TenantScopedModel`, a tenant-scoped `Model`): a bearer
+ * token not yet verified is verified here, and its tenant bound to the
+ * request. An invalid token reads as anonymous: `DEFAULT_TENANT_ID`.
  */
-function getRequestTenantId(ctx) {
-    const authenticatedTenantId = (0, request_authenticators_1.getAuthenticatedRequestTenantId)(ctx);
-    if (authenticatedTenantId)
-        return authenticatedTenantId;
-    const token = extractBearerToken(ctx.rawRequest?.headers?.authorization);
-    if (token) {
-        const tenantIdFromJwt = readTenantIdFromToken(token);
-        if (tenantIdFromJwt)
-            return tenantIdFromJwt;
+async function resolveRequestTenantId(ctx) {
+    const bound = (0, request_authenticators_1.getAuthenticatedRequestTenantId)(ctx);
+    if (bound)
+        return bound;
+    const header = ctx.rawRequest?.headers?.authorization;
+    const token = typeof header === "string" ? header.match(BEARER_SCHEME)?.[1] : undefined;
+    if (!token)
+        return constants_1.DEFAULT_TENANT_ID;
+    const request = ctx.rawRequest;
+    const pending = pendingResolutions.get(request);
+    if (pending)
+        return pending;
+    const resolution = verifyRequestTenantId(ctx, token);
+    pendingResolutions.set(request, resolution);
+    try {
+        return await resolution;
+    }
+    finally {
+        pendingResolutions.delete(request);
     }
-    return constants_1.DEFAULT_TENANT_ID;
 }
 //# sourceMappingURL=request-tenant.js.map

package/dist/request-tenant.js.map

@@ -1 +1 @@
-{"version":3,"file":"request-tenant.js","sourceRoot":"","sources":["../src/request-tenant.ts"],"names":[],"mappings":";;AAkDA,gDASC;AA1DD,+CAAsC;AACtC,mFAAyF;AACzF,2CAAgD;AAEhD,MAAM,aAAa,GAAG,SAAS,CAAC;AAMhC,SAAS,kBAAkB,CAAC,UAAmB;IAC7C,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACrD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,UAAU,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa;IAC1C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAA,qBAAM,EAAC,KAAK,CAAgC,CAAC;QAC7D,IACE,OAAO;YACP,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;YACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAC3B,CAAC;YACD,OAAO,OAAO,CAAC,QAAQ,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,kBAAkB,CAAC,GAAmB;IACpD,MAAM,qBAAqB,GAAG,IAAA,wDAA+B,EAAC,GAAG,CAAC,CAAC;IACnE,IAAI,qBAAqB;QAAE,OAAO,qBAAqB,CAAC;IACxD,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;IACzE,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,eAAe,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,eAAe;YAAE,OAAO,eAAe,CAAC;IAC9C,CAAC;IACD,OAAO,6BAAiB,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"request-tenant.js","sourceRoot":"","sources":["../src/request-tenant.ts"],"names":[],"mappings":";;AA2BA,gDAEC;AAyBD,wDAmBC;AAvED,iCAAkC;AAClC,mFAGgD;AAChD,2CAAgD;AAEhD,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAAoC,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AACH,SAAgB,kBAAkB,CAAC,GAAmB;IACpD,OAAO,IAAA,wDAA+B,EAAC,GAAG,CAAC,IAAI,6BAAiB,CAAC;AACnE,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,GAAmB,EACnB,KAAa;IAEb,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,eAAQ,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI;YAAE,OAAO,6BAAiB,CAAC;QACpC,MAAM,IAAI,GAAG,MAAM,eAAQ,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,SAAS;YAAE,OAAO,6BAAiB,CAAC;QACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,6BAAiB,CAAC;QACpD,IAAA,qDAA4B,EAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,6BAAiB,CAAC;IAC3B,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,sBAAsB,CAC1C,GAAmB;IAEnB,MAAM,KAAK,GAAG,IAAA,wDAA+B,EAAC,GAAG,CAAC,CAAC;IACnD,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,aAAa,CAAC;IACtD,MAAM,KAAK,GACT,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,IAAI,CAAC,KAAK;QAAE,OAAO,6BAAiB,CAAC;IACrC,MAAM,OAAO,GAAG,GAAG,CAAC,UAAU,CAAC;IAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,UAAU,GAAG,qBAAqB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrD,kBAAkB,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC5C,IAAI,CAAC;QACH,OAAO,MAAM,UAAU,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;AACH,CAAC"}

package/dist/tenant-members.d.ts

@@ -0,0 +1,26 @@
+import { type MemberChange } from "./hooks";
+/** What one membership or invitation write changes, and the write itself. */
+export interface TenantMembersWrite<T> {
+    /**
+     * Announced through `Hook.MEMBER_BEING_CHANGED`, in order, before `write`
+     * runs. Empty for a write that changes no membership, such as an invitation
+     * created, edited or retired.
+     */
+    changes: MemberChange[];
+    write: () => Promise<T>;
+}
+/**
+ * The one entry point for writing tenant members and invitations: every
+ * insert, update or delete of a `TenantMemberModel` or `UserInviteModel` row
+ * goes through it. It admits the write under the tenant's lifecycle (refused
+ * while a barrier is held or once the tenant is closed), calls `plan` to read
+ * the current state and describe the change, fires `Hook.MEMBER_BEING_CHANGED`
+ * for each change (a throwing handler refuses the write, replays included),
+ * then runs the write and releases the admission.
+ *
+ * `plan` runs inside the admission so the change it describes is read from
+ * state no paused initiator is validating. Never call this from inside
+ * another `changeTenantMembers` or `runTenantLifecycleOperation` callback:
+ * each call takes its own admission.
+ */
+export declare function changeTenantMembers<T>(tenantId: string, plan: () => Promise<TenantMembersWrite<T>>): Promise<T>;

package/dist/tenant-members.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.changeTenantMembers = changeTenantMembers;
+const hooks_1 = require("./hooks");
+const tenant_lifecycle_1 = require("./tenant-lifecycle");
+/**
+ * The one entry point for writing tenant members and invitations: every
+ * insert, update or delete of a `TenantMemberModel` or `UserInviteModel` row
+ * goes through it. It admits the write under the tenant's lifecycle (refused
+ * while a barrier is held or once the tenant is closed), calls `plan` to read
+ * the current state and describe the change, fires `Hook.MEMBER_BEING_CHANGED`
+ * for each change (a throwing handler refuses the write, replays included),
+ * then runs the write and releases the admission.
+ *
+ * `plan` runs inside the admission so the change it describes is read from
+ * state no paused initiator is validating. Never call this from inside
+ * another `changeTenantMembers` or `runTenantLifecycleOperation` callback:
+ * each call takes its own admission.
+ */
+async function changeTenantMembers(tenantId, plan) {
+    return (0, tenant_lifecycle_1.runTenantLifecycleOperation)(tenantId, async () => {
+        const { changes, write } = await plan();
+        for (const change of changes) {
+            await (0, hooks_1.ExecuteHooks)(hooks_1.Hook.MEMBER_BEING_CHANGED, { tenantId, ...change });
+        }
+        return write();
+    });
+}
+//# sourceMappingURL=tenant-members.js.map

package/dist/tenant-members.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-members.js","sourceRoot":"","sources":["../src/tenant-members.ts"],"names":[],"mappings":";;AA4BA,kDAWC;AAvCD,mCAAgE;AAChE,yDAAiE;AAajE;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,mBAAmB,CACvC,QAAgB,EAChB,IAA0C;IAE1C,OAAO,IAAA,8CAA2B,EAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QACtD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,EAAE,CAAC;QACxC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,IAAA,oBAAY,EAAC,YAAI,CAAC,oBAAoB,EAAE,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tenant-ownership.d.ts

@@ -6,7 +6,10 @@ export interface TenantMembershipPatch {
     /** Durable invite delivery; grants membership without replacing later edits. */
     deliveryId?: string;
 }
-/** Admits membership writes before a tenant can begin destructive deletion. */
+/**
+ * Adds the user to the tenant, or sets the roles and ownership of an existing
+ * member, through `changeTenantMembers`.
+ */
 export declare function applyTenantOwnership(userModel: UserModel, userId: string, tenantId: string, patch: TenantMembershipPatch): Promise<void>;
 export declare function syncPlatformOwnerOnTenantOwnerChange(userModel: UserModel, userId: string, tenantId: string, nextIsTenantOwner: boolean): Promise<void>;
 export declare function clearPlatformOwnerOnMemberRemoval(userModel: UserModel, userId: string, tenantId: string, removedMemberWasTenantOwner: boolean): Promise<void>;

package/dist/tenant-ownership.js

@@ -5,25 +5,20 @@ exports.syncPlatformOwnerOnTenantOwnerChange = syncPlatformOwnerOnTenantOwnerCha
 exports.clearPlatformOwnerOnMemberRemoval = clearPlatformOwnerOnMemberRemoval;
 const interface_database_decorators_1 = require("@antelopejs/interface-database-decorators");
 const tenantMembers_model_1 = require("./db/models/tenantMembers.model");
-const hooks_1 = require("./hooks");
-const tenant_lifecycle_1 = require("./tenant-lifecycle");
+const tenant_members_1 = require("./tenant-members");
+const member_changes_1 = require("./internal/member-changes");
 const tenant_ownership_1 = require("./internal/tenant-ownership");
-/** Admits membership writes before a tenant can begin destructive deletion. */
+/**
+ * Adds the user to the tenant, or sets the roles and ownership of an existing
+ * member, through `changeTenantMembers`.
+ */
 async function applyTenantOwnership(userModel, userId, tenantId, patch) {
-    await (0, tenant_lifecycle_1.runTenantLifecycleOperation)(tenantId, async () => {
-        // Public callers supplying a delivery identity still need the policy veto.
-        // Internal resolution checks it before persisting its applying phase.
-        if (patch.deliveryId &&
-            !(await (0, interface_database_decorators_1.GetModel)(tenantMembers_model_1.TenantMemberModel, tenantId).getByUser(userId))) {
-            await (0, hooks_1.ExecuteHooks)(hooks_1.Hook.MEMBER_BEING_CHANGED, {
-                tenantId,
-                userId,
-                isTenantOwner: patch.isTenantOwner,
-                previousIsTenantOwner: null,
-                deliveryId: patch.deliveryId,
-            });
-        }
-        await (0, tenant_ownership_1.applyAdmittedTenantOwnership)(userModel, userId, tenantId, patch);
+    await (0, tenant_members_1.changeTenantMembers)(tenantId, async () => {
+        const existing = await (0, interface_database_decorators_1.GetModel)(tenantMembers_model_1.TenantMemberModel, tenantId).getByUser(userId);
+        return {
+            changes: (0, member_changes_1.describeMembershipPatch)(existing, userId, patch),
+            write: () => (0, tenant_ownership_1.applyAdmittedTenantOwnership)(userModel, userId, tenantId, patch),
+        };
     });
 }
 async function syncPlatformOwnerOnTenantOwnerChange(userModel, userId, tenantId, nextIsTenantOwner) {

package/dist/tenant-ownership.js.map

@@ -1 +1 @@
-{"version":3,"file":"tenant-ownership.js","sourceRoot":"","sources":["../src/tenant-ownership.ts"],"names":[],"mappings":";;AAmBA,oDAuBC;AAED,oFAOC;AAED,8EAQC;AA5DD,6FAAqE;AACrE,yEAAoE;AACpE,mCAA6C;AAC7C,yDAAiE;AACjE,kEAGqC;AAUrC,+EAA+E;AACxE,KAAK,UAAU,oBAAoB,CACxC,SAAoB,EACpB,MAAc,EACd,QAAgB,EAChB,KAA4B;IAE5B,MAAM,IAAA,8CAA2B,EAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QACrD,2EAA2E;QAC3E,sEAAsE;QACtE,IACE,KAAK,CAAC,UAAU;YAChB,CAAC,CAAC,MAAM,IAAA,wCAAQ,EAAC,uCAAiB,EAAE,QAAQ,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAChE,CAAC;YACD,MAAM,IAAA,oBAAY,EAAC,YAAI,CAAC,oBAAoB,EAAE;gBAC5C,QAAQ;gBACR,MAAM;gBACN,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,qBAAqB,EAAE,IAAI;gBAC3B,UAAU,EAAE,KAAK,CAAC,UAAU;aAC7B,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAA,+CAA4B,EAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;AACL,CAAC;AAEM,KAAK,UAAU,oCAAoC,CACxD,SAAoB,EACpB,MAAc,EACd,QAAgB,EAChB,iBAA0B;IAE1B,MAAM,IAAA,sCAAmB,EAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;AAC5E,CAAC;AAEM,KAAK,UAAU,iCAAiC,CACrD,SAAoB,EACpB,MAAc,EACd,QAAgB,EAChB,2BAAoC;IAEpC,IAAI,CAAC,2BAA2B;QAAE,OAAO;IACzC,MAAM,IAAA,sCAAmB,EAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"tenant-ownership.js","sourceRoot":"","sources":["../src/tenant-ownership.ts"],"names":[],"mappings":";;AAsBA,oDAgBC;AAED,oFAOC;AAED,8EAQC;AAxDD,6FAAqE;AACrE,yEAAoE;AACpE,qDAAuD;AACvD,8DAAoE;AACpE,kEAGqC;AAUrC;;;GAGG;AACI,KAAK,UAAU,oBAAoB,CACxC,SAAoB,EACpB,MAAc,EACd,QAAgB,EAChB,KAA4B;IAE5B,MAAM,IAAA,oCAAmB,EAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,QAAQ,GAAG,MAAM,IAAA,wCAAQ,EAAC,uCAAiB,EAAE,QAAQ,CAAC,CAAC,SAAS,CACpE,MAAM,CACP,CAAC;QACF,OAAO;YACL,OAAO,EAAE,IAAA,wCAAuB,EAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;YACzD,KAAK,EAAE,GAAG,EAAE,CACV,IAAA,+CAA4B,EAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;SACnE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAEM,KAAK,UAAU,oCAAoC,CACxD,SAAoB,EACpB,MAAc,EACd,QAAgB,EAChB,iBAA0B;IAE1B,MAAM,IAAA,sCAAmB,EAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;AAC5E,CAAC;AAEM,KAAK,UAAU,iCAAiC,CACrD,SAAoB,EACpB,MAAc,EACd,QAAgB,EAChB,2BAAoC;IAEpC,IAAI,CAAC,2BAA2B;QAAE,OAAO;IACzC,MAAM,IAAA,sCAAmB,EAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/tenant-scoped-model.d.ts

@@ -2,7 +2,8 @@ import { type Class } from "@antelopejs/interface-core/decorators";
 import { type DataModel } from "@antelopejs/interface-database-decorators";
 /**
  * Parameter/property decorator that injects `GetModel(cl, currentTenantId)`,
- * where `currentTenantId` is resolved per-request via {@link getRequestTenantId}.
+ * where `currentTenantId` is the tenant of the request's verified credential
+ * ({@link resolveRequestTenantId}), `DEFAULT_TENANT_ID` without one.
  *
  * Use on a `Model`-typed parameter of a route handler or DataAPI field. Only
  * applicable when the target table is registered in the `dms-tenant` schema

package/dist/tenant-scoped-model.js

@@ -7,15 +7,16 @@ const interface_database_decorators_1 = require("@antelopejs/interface-database-
 const request_tenant_1 = require("./request-tenant");
 /**
  * Parameter/property decorator that injects `GetModel(cl, currentTenantId)`,
- * where `currentTenantId` is resolved per-request via {@link getRequestTenantId}.
+ * where `currentTenantId` is the tenant of the request's verified credential
+ * ({@link resolveRequestTenantId}), `DEFAULT_TENANT_ID` without one.
  *
  * Use on a `Model`-typed parameter of a route handler or DataAPI field. Only
  * applicable when the target table is registered in the `dms-tenant` schema
  * (or any schema with one instance per tenant).
  */
 exports.TenantScopedModel = (0, decorators_1.MakeParameterAndPropertyDecorator)((target, key, index, cl) => {
-    (0, interface_api_1.SetParameterProvider)(target, key, index, (ctx) => {
-        return (0, interface_database_decorators_1.GetModel)(cl, (0, request_tenant_1.getRequestTenantId)(ctx));
+    (0, interface_api_1.SetParameterProvider)(target, key, index, async (ctx) => {
+        return (0, interface_database_decorators_1.GetModel)(cl, await (0, request_tenant_1.resolveRequestTenantId)(ctx));
     });
 });
 //# sourceMappingURL=tenant-scoped-model.js.map

package/dist/tenant-scoped-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"tenant-scoped-model.js","sourceRoot":"","sources":["../src/tenant-scoped-model.ts"],"names":[],"mappings":";;;AAAA,6DAGmC;AACnC,sEAG+C;AAC/C,6FAGmD;AACnD,qDAAsD;AAEtD;;;;;;;GAOG;AACU,QAAA,iBAAiB,GAAG,IAAA,8CAAiC,EAChE,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAA8C,EAAE,EAAE;IACrE,IAAA,oCAAoB,EAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,GAAmB,EAAE,EAAE;QAC/D,OAAO,IAAA,wCAAQ,EAAC,EAAE,EAAE,IAAA,mCAAkB,EAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC,CACF,CAAC"}
+{"version":3,"file":"tenant-scoped-model.js","sourceRoot":"","sources":["../src/tenant-scoped-model.ts"],"names":[],"mappings":";;;AAAA,6DAGmC;AACnC,sEAG+C;AAC/C,6FAGmD;AACnD,qDAA0D;AAE1D;;;;;;;;GAQG;AACU,QAAA,iBAAiB,GAAG,IAAA,8CAAiC,EAChE,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAA8C,EAAE,EAAE;IACrE,IAAA,oCAAoB,EAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE;QACrE,OAAO,IAAA,wCAAQ,EAAC,EAAE,EAAE,MAAM,IAAA,uCAAsB,EAAC,GAAG,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;AACL,CAAC,CACF,CAAC"}

package/docs/1.core/10.layout-banners.md

@@ -7,7 +7,7 @@ description: "A layout banner is a global message the backend adds under the das
 
 ## Overview
 
-A layout banner is a global message the backend adds under the dashboard header: a colored strip carrying a line of text and its link buttons, or a component of your frontend layer. It renders on every page of the dashboard layout — tenant pages and the module back-office pages under `/modules` alike — and banners stack by `order`.
+A layout banner is a global message the backend adds under the dashboard header: a colored strip carrying a line of text and its link buttons, or a component of your frontend layer. It renders on the pages its [`scope`](#scope) selects — by default the application's pages, leaving the module area under `/modules` out — and banners stack by `order`.
 
 Whether a banner shows is decided per request, on the server, while the site layout is built. The answer is part of the server-rendered page, so a banner never flashes in or out after hydration.
 
@@ -92,6 +92,60 @@ RegisterLayoutBanner({
 
 Re-registering a `key` replaces the banner.
 
+## Scope
+
+A banner is about the application being built — eighteen overdue invoices, a stock alert — so by default it shows on the application's pages only, and stays out of the **module area**: every page under `MODULE_URL_PREFIX` (`/modules`), that is the modules page, the module store and each module's own back-office pages. A banner about the workspace itself, which must follow the user into a module — billing past due, a suspended workspace, a maintenance window — sets `scope: LayoutBannerScope.EVERYWHERE`.
+
+`scope` is a plain option of the banner declaration, the same on the three kinds of banner — a text banner, a resolved banner and a component banner — with the same values and the same `"app"` default:
+
+```typescript
+import {
+  LayoutBannerScope,
+  LayoutBannerVariant,
+  RegisterLayoutBanner,
+} from "@antelopejs/interface-dms/layout-banners";
+
+// A text banner about the application: the default scope, written out.
+RegisterLayoutBanner({
+  key: "my-app:overdue-invoices",
+  variant: LayoutBannerVariant.WARNING,
+  scope: LayoutBannerScope.APP,
+  text: "$my_app.banners.overdue_invoices",
+  actions: [{ label: "$my_app.banners.review", to: "/finance/invoices" }],
+  visible: async ({ tenantId }) => hasOverdueInvoices(tenantId),
+});
+
+// A resolved banner about the workspace: it follows the user into /modules.
+RegisterLayoutBanner({
+  key: "saas:past-due",
+  variant: LayoutBannerVariant.ERROR,
+  scope: LayoutBannerScope.EVERYWHERE,
+  resolve: pastDueContent,
+});
+
+// A component banner about the workspace, also shown inside /modules.
+RegisterLayoutBanner({
+  key: "my-app:maintenance",
+  variant: LayoutBannerVariant.INFO,
+  scope: LayoutBannerScope.EVERYWHERE,
+  component: "MyAppMaintenanceBanner",
+  props: { statusUrl: "https://status.example.com" },
+  visible: async () => isMaintenanceScheduled(),
+});
+```
+
+| `scope` | Shows on |
+| ------- | -------- |
+| `"app"` (default) | Every page outside the module area. |
+| `"everywhere"` | Every page of the dashboard layout, module area included. |
+| `"modules"` | The module area only. |
+
+The scope is decided by the page, not by the request: the site layout is fetched once and shared by every page, so each banner carries its scope and the dashboard applies it against the current route — in the server-rendered page, so a banner never flashes in or out after hydration, and again on each client-side navigation, so moving in or out of `/modules` adds or removes it without re-fetching anything. A banner's `visible` or `resolve` therefore does not see the route; the scope is the only per-page filter. A dismissal is per key, whatever page the banner was closed on.
+
+::warning
+**Behaviour change.** Before `scope` existed every banner showed on every page, module area included. A banner registered without `scope` now stays out of `/modules`: give `scope: LayoutBannerScope.EVERYWHERE` to the ones reporting a workspace-wide state.
+::
+
 ## `LayoutBannerInfo`
 
 | Field | Type | Description |
@@ -105,6 +159,7 @@ Re-registering a `key` replaces the banner.
 | `order` | `number` | Stack order, ascending from the top. Defaults to `0`; ties keep the registration order. |
 | `icon` | `string` | Leading icon. Defaults to one matching the variant. |
 | `dismissible` | `boolean` | Whether the user can close the banner. Defaults to `false`. |
+| `scope` | `LayoutBannerScope` | `"app"`, `"everywhere"` or `"modules"`: the pages the banner shows on. Defaults to `"app"`, every page outside `/modules`. See [Scope](#scope). |
 | `visible` | `LayoutBannerVisibility` | Decides per request whether a `text` or `component` banner shows. Absent means always. |
 | `resolve` | `LayoutBannerResolver` | Builds `{ text, actions? }` per request, or `undefined` to hide the banner. Exclusive with `text`, `component` and `visible`. |
 
@@ -128,6 +183,6 @@ The resolvers run whenever a client fetches its site layout — on a full page l
 
 ## Rendering
 
-Banners render under the header of the dashboard layout, full width, in `order`, a text banner's `actions` on its right. Each one is its own live region: `error` banners carry `role="alert"`, `info` and `warning` banners `role="status"`.
+Banners render under the header of the dashboard layout, on the pages their scope covers, full width, in `order`, a text banner's `actions` on its right. Each one is its own live region: `error` banners carry `role="alert"`, `info` and `warning` banners `role="status"`.
 
 A dismissible banner shows a close button. The dismissal lasts for the browser session and is kept in the `dms-dismissed-banners` cookie, which the server reads too, so a dismissed banner is already absent from the server-rendered page. A banner that is not dismissible ignores any dismissal recorded under its key.

package/docs/1.core/2.pages-and-modules.md

@@ -62,6 +62,7 @@ The third argument is the page layout, a `ComponentInfo` produced by a layout bu
 | `order` | `number` | Sort order among siblings. |
 | `icon` | `string` | Icon name. |
 | `hidden` | `boolean` | Keep the entry out of the menu. Inherited from the resolved category when that category is hidden. |
+| `parent` | `ControllerClass` | The page this one is a detail of: the breadcrumb shows it before this page ("Operations / Projects / <record>"), its route parameters filled from this page's own. Resolved at registration, served as `parentSlug`. Pages only. |
 | `permission` | `Partial<Permission> \| Action` | Override the auto-derived page permission, or bind the page to an existing component `Action`. See [Permissions](/docs/interfaces/core/permissions). |
 | `publicAccess` | `boolean` | Serve the page without authentication. Inherited from the resolved category. |
 | `authOnly` | `boolean` | Require a logged-in user but no permission check. Inherited from the resolved category. |
@@ -212,7 +213,7 @@ Call `RegisterModule` before any page that references the module id: a page reso
 | `description` | `string` | Description carried on the module root. |
 | `icon` | `string` | Icon name. |
 | `landingPage` | `string` | Id of the page the module opens on; `/modules/<id>` redirects to it, query and hash kept. Defaults to the first page by `order`. |
-| `catalogCategory` | `string` | Category the module is filed under in the module catalog (`"Content"`, `"Developer"`…), may be a `$` i18n key; without one it goes under "Other". Unrelated to menu categories (`MenuOptions.category`, `defaultCategory`). Formerly `category`. |
+| `catalogCategory` | `string` | Category the module is filed under in the module catalog (`"Content"`, `"Developer"`…), may be a `$` i18n key. The Modules page and the store both file the module under it; without one, a store module takes the category of the store catalog, and any other goes under "Other". Unrelated to menu categories (`MenuOptions.category`, `defaultCategory`). Formerly `category`. |
 | `defaultCategory` | `{ displayName?, icon?, order?, urlSlug? }` | Groups the module's pages that declare `module` without an explicit `category`. Without it, those pages attach directly to the module root. |
 
 The generated default category uses `urlSlug` `"pages"` unless you override it, and falls back to the label `"$menu.section.pages"` when `displayName` is empty or omitted.
@@ -388,12 +389,20 @@ interface PageLayout<T = unknown> {
 Registering a page installs a `PageLayoutHandler` for its `fullSlug`:
 
 ```typescript
-type PageLayoutHandler = (
-  user: User | undefined,
-  memberModel: TenantMemberModel,
-  roleModel: RoleModel,
-  tenantId: string,
-) => Promise<PageLayout>;
+interface PageLayoutRequest {
+  user: User | undefined;
+  memberModel: TenantMemberModel;
+  roleModel: RoleModel;
+  tenantId: string;
+  /** The page URL's query, for header-button availability. */
+  query?: Readonly<Record<string, string>>;
+  /** The page URL's route parameters (`:id`), likewise. */
+  params?: Readonly<Record<string, string>>;
+  /** Passed to the permissions resolvers: `{ preview }` when a role preview reads the layout. */
+  resolverContext?: PermissionsResolverContext;
+}
+
+type PageLayoutHandler = (request: PageLayoutRequest) => Promise<PageLayout>;
 ```
 
 The handler drops the components the caller has no permission for and applies each component's own filter. Native upload tokens are bound to the exact page/component mount during page registration, not stamped by this handler; upload and metadata requests still check live authorization ([File storage](/docs/components/file-storage)). A page with `publicAccess`, `authOnly` or `noComponentPermissions` skips the filtering step and returns every component. Look a handler up with `GetPageLayoutBySlug(slug)`, which returns `undefined` for an unknown slug:
@@ -416,12 +425,12 @@ async function renderLayout(
   tenantId: string,
 ): Promise<PageLayout | undefined> {
   const handler = GetPageLayoutBySlug(slug);
-  return handler?.(
+  return handler?.({
     user,
-    GetModel(TenantMemberModel, tenantId),
-    GetModel(RoleModel, tenantId),
+    memberModel: GetModel(TenantMemberModel, tenantId),
+    roleModel: GetModel(RoleModel, tenantId),
     tenantId,
-  );
+  });
 }
 ```
 

package/docs/1.core/4.permissions.md

@@ -45,6 +45,8 @@ RegisterPermission("reports.export", {
 | `dependencies` | `string[]` | Permission ids this one needs to be of any use. The roles editor grants them with it (and takes it away with them), and a role is saved with them and the ids they sit under. `HasPermission` requires them, like the ids above: a registered dependency the set lacks makes the permission count for nothing. An unregistered one counts as held. |
 | `defaultGranted` | `boolean` | Treat the permission as held by every caller, without a role grant. |
 
+A table view's actions declare their `dependencies` themselves: `edit` and `export` need `view`, and every action only reached from the rows — `delete`, `archive`, `viewArchived`, `export`, and `add`/`edit`/`view` when their form opens over the table — needs `list`; `restore` needs `viewArchived`. A form opening as its own page and `select` need no `list`.
+
 `RegisterPermission(id, permission)` takes the id twice — once as the registry key, once inside the record — so keep them equal.
 
 `UnregisterPermission(id)` drops a permission from the grantable tree again. It exists for registrations undone while the process keeps running — a page extension whose module stopped, for instance. A permission left behind after its surface is gone stays offered in the roles editor and stays grantable, so anything that registers a permission conditionally should unregister it on the same condition.
@@ -174,11 +176,42 @@ type PermissionsResolverFn = (
   userId: string,
   tenantId: string,
   currentPermissions: Set<string>,
+  context: PermissionsResolverContext,
 ) => Promise<Set<string>> | Set<string>;
+
+interface PermissionsResolverContext {
+  /** Set when the call previews a role rather than computing a member's set. */
+  preview?: PermissionsResolverPreview;
+}
+
+interface PermissionsResolverPreview {
+  /** The previewed role's permissions, before any resolver reshaped them. */
+  rolePermissions: ReadonlySet<string>;
+}
 ```
 
 `PermissionsResolverInfo` carries `id`, `resolver` and `order`.
 
+### Role previews
+
+The roles editor's **Preview as role** runs the resolvers too, over the previewed role's set, and tells them so with `context.preview`. The `userId` of such a call is the person previewing. A resolver that grants or withholds by the user's standing (an owner handed every permission of the plan, a screen kept for owners) must check the flag, and shape the set as for a member holding only that role:
+
+```typescript
+RegisterPermissionsResolver({
+  id: "my_app.plan-limits",
+  order: 100,
+  resolver: async (userId, tenantId, currentPermissions, context) => {
+    const allowed = await loadPlanPermissions(tenantId);
+    if (!context.preview && (await isWorkspaceOwner(userId, tenantId))) {
+      return allowed;
+    }
+    return new Set([...currentPermissions].filter((p) => allowed.has(p)));
+  },
+});
+```
+
+The DMS always passes `context`: `{}` outside a preview.
+
 Semantics the interface guarantees:
 
 - Resolvers run in ascending `order`, each seeing the previous one's result; equal `order` runs in registration order, which is module load order.
@@ -187,7 +220,7 @@ Semantics the interface guarantees:
 - The registration is removed when the registering module unloads; there is no unregister call.
 - Register in `construct()` so the resolver is active before the API serves requests.
 
-`ApplyPermissionsResolvers(userId, tenantId, basePermissions)` runs the pipeline and resolves to the effective set. Prefer `GetEffectiveUserPermissions`, which computes the base set for you and calls it.
+`ApplyPermissionsResolvers(userId, tenantId, basePermissions, context?)` runs the pipeline, handing `context` (`{}` when omitted) to every resolver, and resolves to the effective set. Prefer `GetEffectiveUserPermissions`, which computes the base set for you and calls it.
 
 A resolver shapes a permission set. It cannot deny a surface that consults no permission set, and it cannot revoke a `defaultGranted` permission, which `HasPermission` grants after the resolvers ran. To cut a tenant off from the product entirely, register a tenant access gate instead ([Tenancy](/docs/interfaces/core/tenancy)).
 

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

@@ -127,7 +127,7 @@ Table `roles` in `dms-tenant` — the tenant's roles.
 
 ## Resolve the Request's Tenant
 
-`getRequestTenantId(ctx)` reads the `tenantId` claim of the request's bearer token and returns `DEFAULT_TENANT_ID` when there is no token or no claim.
+`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.
 
 ```typescript
 import {
@@ -148,11 +148,11 @@ export class WorkspaceController extends Controller("/api/workspace") {
 }
 ```
 
-The returned id is **decoded, not verified**: the function does not check the token's signature. It is safe behind a decorator that already authenticated the request — the guards from [Permissions](/docs/interfaces/core/permissions), `AuthUser` from `@antelopejs/interface-dms/auth`, or the auth a `PageController` installs. Do not authorize on the id in a route that no such decorator gates.
+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.
 
 ## Scope a Model to the Request's Tenant
 
-`TenantScopedModel(ModelClass)` is a parameter and property decorator that injects `GetModel(ModelClass, getRequestTenantId(ctx))`.
+`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.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -279,7 +279,7 @@ await applyTenantOwnership(GetModel(UserModel), userId, tenantId, {
 | `isTenantOwner` | `boolean` | Ownership flag after the write. |
 | `invitedBy` | `string \| null` | Recorded on insert. Ignored when the membership row already exists. |
 
-`applyTenantOwnership` 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 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)).
 
 Two helpers keep the legacy platform-owner flag on the user row aligned with tenant ownership:
 
@@ -313,9 +313,40 @@ The registration is removed when the registering module unloads, and the mode st
 
 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.
 
+### `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.
+
+```typescript
+changeTenantMembers<T>(
+  tenantId: string,
+  plan: () => Promise<{ changes: MemberChange[]; write: () => Promise<T> }>,
+): Promise<T>
+```
+
+It runs, 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.
+
+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 |
+
+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.
+
+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.
+
 ### `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`. Built-in membership and invite entry points already participate; custom producers must use this entry point and await every effect, with no detached writer.
+`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.
 
 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.
 
@@ -329,7 +360,7 @@ A module that must validate a tenant's inventory with no membership writer in fl
 | `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. |
 
-While a barrier is held, `runTenantLifecycleOperation` rejects new work without running it; 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.
+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.
 
 ### `closeTenantLifecycleAdmission`
 

package/docs/1.core/7.hooks.md

@@ -76,7 +76,7 @@ UnregisterHook(Hook.MEMBER_ADDED, onMemberAdded);
 | `Hook.INVITE_CREATED` | `"invite:created"` | `InviteCreatedHookPayload` | `undefined` |
 | `Hook.INVITE_DELETED` | `"invite:deleted"` | `InviteDeletedHookPayload` | `undefined` |
 | `Hook.MEMBER_BEING_ADDED` | `"member:being-added"` | `MemberHookPayload` | `undefined` |
-| `Hook.MEMBER_BEING_CHANGED` | `"member:being-changed"` | `MemberChangeHookPayload` | `undefined` — fires under tenant lifecycle admission before a membership is created or its ownership changes; throwing vetoes the write |
+| `Hook.MEMBER_BEING_CHANGED` | `"member:being-changed"` | `MemberChangeHookPayload` | `undefined` — fired by `changeTenantMembers` under tenant lifecycle admission before every membership write (`kind`: `added`, `removed`, `roles`, `ownership`); throwing vetoes the write |
 | `Hook.MEMBER_ADDED` | `"member:added"` | `MemberHookPayload` | `undefined` |
 | `Hook.MEMBER_REMOVED` | `"member:removed"` | `MemberRemovedHookPayload` | `undefined` |
 | `Hook.USER_REGISTERED` | `"user:registered"` | `UserRegisteredHookPayload` | `undefined` |
@@ -141,7 +141,17 @@ interface UserDeletedHookPayload {
 
 The shapes are not uniform, and the difference between the addition and removal payloads is deliberate: `MEMBER_BEING_ADDED` and `MEMBER_ADDED` describe one member with `userId`, while `MEMBER_REMOVED` carries `userIds`, because a removal can cover several members at once. Let the handler's inferred parameter type guide you.
 
-`MemberChangeHookPayload` extends `MemberHookPayload` with `previousIsTenantOwner`, `null` for a new membership. An invitation acceptance carries its `deliveryId` and is vetoed before the acceptance is persisted, including on replay: a `deliveryId` is not a policy exemption.
+`MemberChangeHookPayload` is `{ tenantId } & MemberChange`, a union discriminated by `kind`:
+
+```typescript
+type MemberChange =
+  | { kind: "added"; userId: string; isTenantOwner: boolean; roleIds: string[]; deliveryId?: string }
+  | { kind: "removed"; userId: string; isTenantOwner: boolean }
+  | { kind: "roles"; userId: string; roleIds: string[]; previousRoleIds: string[] }
+  | { kind: "ownership"; userId: string; isTenantOwner: boolean; previousIsTenantOwner: boolean };
+```
+
+Read `kind` first and return early for the kinds your policy does not limit. An invitation acceptance is an `added` change carrying its `deliveryId`, vetoed before the acceptance is persisted, including on replay: a `deliveryId` is not a policy exemption. See [`changeTenantMembers`](/docs/interfaces/core/tenancy#changetenantmembers) for which writes announce which kind.
 
 `UserDeletedHookPayload.tenantIds` lists the workspaces the user was a member of, all left before the deletion; delete the per-user rows your module keeps in them. `reason` is `"self"` today, the user deleting their own account.