@antelopejs/interface-dms 0.7.3 → 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-access.d.ts

@@ -50,6 +50,21 @@ export declare function RegisterTenantAccessGate(info: TenantAccessGateInfo): vo
  * undefined for unauthenticated requests.
  */
 export declare const CheckTenantAccess: (userId: string | undefined, tenantId: string) => Promise<TenantAccessResult>;
+/** One denying gate, identified independently of its user-facing error code. */
+export interface TenantAccessDenial {
+    gateId: string;
+    code: string;
+}
+/**
+ * Server-side evaluation of every registered gate, in gate order. Returns all
+ * denials (empty when allowed); any exception rejects the whole evaluation.
+ * Unlike CheckTenantAccess, an early denial does not hide later blockers.
+ * This is an observation, not an authorization receipt or an atomic snapshot
+ * of external state. Callers must preserve other holds and revalidate their
+ * operation's authorization before effects. Never infer ownership from code.
+ * Does not change the first-denial response of user-facing access checks.
+ */
+export declare const EvaluateTenantAccess: (userId: string | undefined, tenantId: string) => Promise<TenantAccessDenial[]>;
 /**
  * Assert that the tenant is accessible; throws a 403 whose body is the
  * denying gate's `code` (a machine-readable i18n key) otherwise.

package/dist/tenant-access.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CheckTenantAccess = exports.internal = void 0;
+exports.EvaluateTenantAccess = exports.CheckTenantAccess = exports.internal = void 0;
 exports.RegisterTenantAccessGate = RegisterTenantAccessGate;
 exports.AssertTenantAccess = AssertTenantAccess;
 const interface_api_1 = require("@antelopejs/interface-api");
@@ -48,6 +48,16 @@ function RegisterTenantAccessGate(info) {
  * undefined for unauthenticated requests.
  */
 exports.CheckTenantAccess = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Server-side evaluation of every registered gate, in gate order. Returns all
+ * denials (empty when allowed); any exception rejects the whole evaluation.
+ * Unlike CheckTenantAccess, an early denial does not hide later blockers.
+ * This is an observation, not an authorization receipt or an atomic snapshot
+ * of external state. Callers must preserve other holds and revalidate their
+ * operation's authorization before effects. Never infer ownership from code.
+ * Does not change the first-denial response of user-facing access checks.
+ */
+exports.EvaluateTenantAccess = (0, interface_core_1.InterfaceFunction)();
 /**
  * Assert that the tenant is accessible; throws a 403 whose body is the
  * denying gate's `code` (a machine-readable i18n key) otherwise.

package/dist/tenant-access.js.map

@@ -1 +1 @@
-{"version":3,"file":"tenant-access.js","sourceRoot":"","sources":["../src/tenant-access.ts"],"names":[],"mappings":";;;AA0DA,4DAEC;AAmBD,gDAQC;AAvFD,6DAAuD;AACvD,+DAGoC;AAEpC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAiBlC;;GAEG;AACH,IAAiB,QAAQ,CAIxB;AAJD,WAAiB,QAAQ;IACV,iCAAwB,GAAG,IAAI,iCAAgB,EAEzD,CAAC;AACN,CAAC,EAJgB,QAAQ,wBAAR,QAAQ,QAIxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,wBAAwB,CAAC,IAA0B;IACjE,QAAQ,CAAC,wBAAwB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACU,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AAEN;;;GAGG;AACI,KAAK,UAAU,kBAAkB,CACtC,MAA0B,EAC1B,QAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,0BAAU,CAAC,qBAAqB,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}
+{"version":3,"file":"tenant-access.js","sourceRoot":"","sources":["../src/tenant-access.ts"],"names":[],"mappings":";;;AA0DA,4DAEC;AA0CD,gDAQC;AA9GD,6DAAuD;AACvD,+DAGoC;AAEpC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAiBlC;;GAEG;AACH,IAAiB,QAAQ,CAIxB;AAJD,WAAiB,QAAQ;IACV,iCAAwB,GAAG,IAAI,iCAAgB,EAEzD,CAAC;AACN,CAAC,EAJgB,QAAQ,wBAAR,QAAQ,QAIxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,wBAAwB,CAAC,IAA0B;IACjE,QAAQ,CAAC,wBAAwB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACU,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AAQN;;;;;;;;GAQG;AACU,QAAA,oBAAoB,GAC/B,IAAA,kCAAiB,GAKd,CAAC;AAEN;;;GAGG;AACI,KAAK,UAAU,kBAAkB,CACtC,MAA0B,EAC1B,QAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,0BAAU,CAAC,qBAAqB,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}

package/dist/tenant-lifecycle.d.ts

@@ -13,3 +13,30 @@ export declare function runTenantLifecycleOperation<T>(tenantId: string, work: (
  * rejection requires preserving data, never timeout-based takeover or reopening.
  */
 export declare function closeTenantLifecycleAdmission(tenantId: string): Promise<void>;
+/** A non-destructive snapshot; no attempt expires or is retired by observation. */
+export interface TenantLifecycleObservation {
+    revision: string;
+    barrierId: string | null;
+    activeAttemptIds: string[];
+    closed: boolean;
+}
+/** Observe outside a producer callback: an initiator must not drain itself. */
+export declare function observeTenantLifecycle(tenantId: string): Promise<TenantLifecycleObservation>;
+/**
+ * Publish a temporary barrier on the same CAS revision as producer admission.
+ * Use a unique identity per phase, never reuse it. Observe the revision BEFORE
+ * checking the durable business intent, then attempt this single CAS. After
+ * acquisition recheck that intent; release if abandoned. False requires a new
+ * observation and intent check, not a blind retry. Unknown outcomes throw.
+ * Existing attempts keep running; only an empty observation while this barrier
+ * remains owned permits inventory validation. No Stripe calls under a barrier.
+ */
+export declare function pauseTenantLifecycleAdmission(tenantId: string, barrierId: string, expectedRevision: string): Promise<boolean>;
+/**
+ * Release this owner's barrier, or invalidate the revision when none is held.
+ * The latter revokes a delayed acquisition after its business intent is aborted.
+ * Never reopens permanent deletion closure or another owner's barrier (false).
+ * Retains every active/uncertain attempt; timeout is not evidence of completion.
+ * Publish pending policy before release so newly admitted producers read it.
+ */
+export declare function resumeTenantLifecycleAdmission(tenantId: string, barrierId: string): Promise<boolean>;

package/dist/tenant-lifecycle.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runTenantLifecycleOperation = runTenantLifecycleOperation;
 exports.closeTenantLifecycleAdmission = closeTenantLifecycleAdmission;
+exports.observeTenantLifecycle = observeTenantLifecycle;
+exports.pauseTenantLifecycleAdmission = pauseTenantLifecycleAdmission;
+exports.resumeTenantLifecycleAdmission = resumeTenantLifecycleAdmission;
 const node_crypto_1 = require("node:crypto");
 const interface_database_decorators_1 = require("@antelopejs/interface-database-decorators");
 const tenantLifecycle_model_1 = require("./db/internal/tenantLifecycle.model");
@@ -55,4 +58,36 @@ async function runTenantLifecycleOperation(tenantId, work) {
 async function closeTenantLifecycleAdmission(tenantId) {
     await (0, interface_database_decorators_1.GetModel)(tenantLifecycle_model_1.TenantLifecycleModel, tenantId).close(tenantId);
 }
+/** Observe outside a producer callback: an initiator must not drain itself. */
+async function observeTenantLifecycle(tenantId) {
+    const state = await (0, interface_database_decorators_1.GetModel)(tenantLifecycle_model_1.TenantLifecycleModel, tenantId).state(tenantId);
+    return {
+        revision: state.revision,
+        barrierId: state.barrierId ?? null,
+        activeAttemptIds: [...state.activeAttemptIds],
+        closed: state.closed,
+    };
+}
+/**
+ * Publish a temporary barrier on the same CAS revision as producer admission.
+ * Use a unique identity per phase, never reuse it. Observe the revision BEFORE
+ * checking the durable business intent, then attempt this single CAS. After
+ * acquisition recheck that intent; release if abandoned. False requires a new
+ * observation and intent check, not a blind retry. Unknown outcomes throw.
+ * Existing attempts keep running; only an empty observation while this barrier
+ * remains owned permits inventory validation. No Stripe calls under a barrier.
+ */
+async function pauseTenantLifecycleAdmission(tenantId, barrierId, expectedRevision) {
+    return (0, interface_database_decorators_1.GetModel)(tenantLifecycle_model_1.TenantLifecycleModel, tenantId).pause(tenantId, barrierId, expectedRevision);
+}
+/**
+ * Release this owner's barrier, or invalidate the revision when none is held.
+ * The latter revokes a delayed acquisition after its business intent is aborted.
+ * Never reopens permanent deletion closure or another owner's barrier (false).
+ * Retains every active/uncertain attempt; timeout is not evidence of completion.
+ * Publish pending policy before release so newly admitted producers read it.
+ */
+async function resumeTenantLifecycleAdmission(tenantId, barrierId) {
+    return (0, interface_database_decorators_1.GetModel)(tenantLifecycle_model_1.TenantLifecycleModel, tenantId).resume(tenantId, barrierId);
+}
 //# sourceMappingURL=tenant-lifecycle.js.map

package/dist/tenant-lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"tenant-lifecycle.js","sourceRoot":"","sources":["../src/tenant-lifecycle.ts"],"names":[],"mappings":";;AAkCA,kEAoBC;AAMD,sEAIC;AAhED,6CAAyC;AACzC,6FAAqE;AACrE,+EAA2E;AAE3E,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAOlC;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,MAAM,SAAS,GAAI,KAAuC,EAAE,SAAS,CAAC;IACtE,IAAI,OAAO,SAAS,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,OAAO,MAAM,IAAI,qBAAqB,IAAI,MAAM,GAAG,qBAAqB,CAAC;AAC3E,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,2BAA2B,CAC/C,QAAgB,EAChB,IAAsB;IAEtB,MAAM,KAAK,GAAG,IAAA,wCAAQ,EAAC,4CAAoB,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,IAAA,wBAAU,GAAE,CAAC;IAC/B,MAAM,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvC,IAAI,MAAS,CAAC;IACd,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,wEAAwE;YACxE,mDAAmD;YACnD,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,6BAA6B,CACjD,QAAgB;IAEhB,MAAM,IAAA,wCAAQ,EAAC,4CAAoB,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"tenant-lifecycle.js","sourceRoot":"","sources":["../src/tenant-lifecycle.ts"],"names":[],"mappings":";;AAkCA,kEAoBC;AAMD,sEAIC;AAWD,wDAUC;AAWD,sEAUC;AASD,wEAKC;AAxHD,6CAAyC;AACzC,6FAAqE;AACrE,+EAA2E;AAE3E,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAOlC;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,MAAM,SAAS,GAAI,KAAuC,EAAE,SAAS,CAAC;IACtE,IAAI,OAAO,SAAS,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,OAAO,MAAM,IAAI,qBAAqB,IAAI,MAAM,GAAG,qBAAqB,CAAC;AAC3E,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,2BAA2B,CAC/C,QAAgB,EAChB,IAAsB;IAEtB,MAAM,KAAK,GAAG,IAAA,wCAAQ,EAAC,4CAAoB,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,IAAA,wBAAU,GAAE,CAAC;IAC/B,MAAM,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACvC,IAAI,MAAS,CAAC;IACd,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,wEAAwE;YACxE,mDAAmD;YACnD,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,6BAA6B,CACjD,QAAgB;IAEhB,MAAM,IAAA,wCAAQ,EAAC,4CAAoB,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AACjE,CAAC;AAUD,+EAA+E;AACxE,KAAK,UAAU,sBAAsB,CAC1C,QAAgB;IAEhB,MAAM,KAAK,GAAG,MAAM,IAAA,wCAAQ,EAAC,4CAAoB,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7E,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,gBAAgB,EAAE,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC;QAC7C,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,6BAA6B,CACjD,QAAgB,EAChB,SAAiB,EACjB,gBAAwB;IAExB,OAAO,IAAA,wCAAQ,EAAC,4CAAoB,EAAE,QAAQ,CAAC,CAAC,KAAK,CACnD,QAAQ,EACR,SAAS,EACT,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,8BAA8B,CAClD,QAAgB,EAChB,SAAiB;IAEjB,OAAO,IAAA,wCAAQ,EAAC,4CAAoB,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC9E,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

@@ -3,11 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyTenantOwnership = applyTenantOwnership;
 exports.syncPlatformOwnerOnTenantOwnerChange = syncPlatformOwnerOnTenantOwnerChange;
 exports.clearPlatformOwnerOnMemberRemoval = clearPlatformOwnerOnMemberRemoval;
-const tenant_lifecycle_1 = require("./tenant-lifecycle");
+const interface_database_decorators_1 = require("@antelopejs/interface-database-decorators");
+const tenantMembers_model_1 = require("./db/models/tenantMembers.model");
+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, () => (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) {
     await (0, tenant_ownership_1.mirrorPlatformOwner)(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":";;AAgBA,oDASC;AAED,oFAOC;AAED,8EAQC;AA3CD,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,GAAG,EAAE,CAC/C,IAAA,+CAA4B,EAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CACjE,CAAC;AACJ,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,
-  );
+  });
 }
 ```