@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/organizations/organizations.shared.resources-config.schemas.js

@@ -12,13 +12,45 @@ import { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resourc
 import { ResourceOperationVariantType } from '../resources/resources.shared.schemas.js';
 import { CoreUserNotificationTarget, CoreUserNotificationChannel } from '../notifications/notifications.shared.schemas.js';
 import { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory.js';
+import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
 import { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
-// Custom operations enum for organizations
-export var Organization_AppAdmin_Operations;
-(function (Organization_AppAdmin_Operations) {
-    Organization_AppAdmin_Operations["ACTIVATE"] = "activate";
-    Organization_AppAdmin_Operations["SUSPEND"] = "suspend";
-})(Organization_AppAdmin_Operations || (Organization_AppAdmin_Operations = {}));
+/**
+ * Tenant LIFECYCLE transitions — the operations that own `Organization.status`.
+ *
+ * Renamed from `Organization_AppAdmin_Operations` on 2026-08-01. The old name described the
+ * AUDIENCE of the two members it happened to hold (`ACTIVATE`/`SUSPEND` are super-admin-only) and
+ * stopped being true the moment an ORG_ADMIN-facing member joined it. The members share a
+ * *concern*, not an audience: each is a guarded transition of the tenant state machine, declared
+ * `resourceOperationLike: UPDATE`, gated by an `enabledCondition` on the current status, and the
+ * sole authority for the `status` field that generic UPDATE may not write. The frontend already
+ * called this concept by its right name — `organizationLifecycleOpViews` in the presets.
+ *
+ * `status` is `.excludeFromUpdate()`, so every transition here declares `authoritativeFields`
+ * naming the fields its prefix owns; without that the repository's strict re-parse silently strips
+ * the write and the operation answers success having changed nothing.
+ */
+export var Organization_Lifecycle_Operations;
+(function (Organization_Lifecycle_Operations) {
+    Organization_Lifecycle_Operations["ACTIVATE"] = "activate";
+    Organization_Lifecycle_Operations["SUSPEND"] = "suspend";
+    /**
+     * Mark the tenant for deletion — the SOFT-DELETE half of tenant teardown.
+     *
+     * Replaces the tenant-facing `DELETE` door, which now belongs to the purge batch. Writes
+     * `status: DELETED` + `deletionRequestedAt` + `purgeScheduledAt`, reconciles every affected user's global
+     * `userTypes`, and invalidates their tokens — so the tenant is authorization-dead immediately
+     * while remaining fully data-alive and restorable until the window elapses.
+     */
+    Organization_Lifecycle_Operations["REQUEST_DELETION"] = "request_deletion";
+    /**
+     * Cancel a pending deletion inside the retention window.
+     *
+     * The inverse of {@link REQUEST_DELETION}. Nothing needs re-creating: authority is re-derived
+     * from the membership rows the window deliberately preserved, which is exactly why those rows
+     * are not touched at mark time.
+     */
+    Organization_Lifecycle_Operations["RESTORE"] = "restore";
+})(Organization_Lifecycle_Operations || (Organization_Lifecycle_Operations = {}));
 const ORGANIZATION_ADMIN_SORT_FIELDS = ['status'];
 const ORGANIZATION_ADMIN_FILTER_FIELDS = {
     status: z.enum(OrganizationStatus),
@@ -32,6 +64,11 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
     resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],
     resourceRelationships: resourcesRelationships,
     isSystemResource: true, // Organizations are a core system resource
+    // The invitation-accept auth flow reads the inviting org's display name via
+    // `readAsSystem` to render the invite email — the invitee is not yet a member
+    // and cannot satisfy the org READ ACL. READ-only; the request is authorized by
+    // the consumable invitation token, not org membership.
+    systemAccessPolicy: { read: ResourceSystemAccessMode.ALLOWED },
     coreOperations: [
         CoreResourceOperation.READ,
         CoreResourceOperation.LIST,
@@ -40,23 +77,76 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
         CoreResourceOperation.UPDATE,
         CoreResourceOperation.DELETE
     ],
-    customOperation: Organization_AppAdmin_Operations,
+    customOperation: Organization_Lifecycle_Operations,
+    /**
+     * ⚠️ WHAT `APP_ADMIN_SUPER_ADMIN` ACTUALLY BUYS ON THIS RESOURCE (measured 2026-08-05, not inferred)
+     *
+     * Every super-admin-gated variant below reads as cross-tenant ("any organization"). **It is not.**
+     * A probe against the real authorization service with real Mongo denied ALL 12 of them to a
+     * platform super-administrator who is not scoped to the target tenant; the same 12 allow once the
+     * caller's execution context carries `initiatorIds.organizationId` equal to that tenant.
+     *
+     * The reason is that tenant isolation is enforced at two gates the role table does not reach:
+     * `validateParentScopeAccess` (collection calls) and `authorizeOrganizations` (per-instance
+     * calls). Both compare the request against the CALLER'S OWN organization. A role key, however
+     * privileged, does not supply one.
+     *
+     * So these variants mean "a super-admin acting INSIDE an organization", not "a super-admin acting
+     * on any organization". Read every `// Super admins can … any organization` comment below with
+     * that correction applied — they were written from the role gate alone.
+     *
+     * Making one genuinely cross-tenant is a deliberate, per-variant act: declare
+     * `admitsCrossTenantPlatformAdministration` on it, which admits the crossing at BOTH gates.
+     *
+     * ## Which variants are crossed, and why the line falls there (decided 2026-08-05)
+     *
+     * | Variant | Crossed | Reason |
+     * |---|---|---|
+     * | `restore` | ✅ | A MARKED tenant is `DELETED`, which confers no authority, so NOBODY could restore one. Recuperative. |
+     * | `activate` | ✅ | `SUSPENDED` confers no authority and is the only state ACTIVATE runs from. Recuperative. |
+     * | `requestDeletion: admin` | ✅ | The operator takedown path — but the REVERSIBLE one: mark + notify + window, undone by `restore`. |
+     * | `delete: admin` | ❌ | Irreversible, whole-tenant, cascading, skips the window. See its own block for the full decision. |
+     * | everything else | ❌ | No demonstrated operator need. Absence of a use case is a reason to stay shut. |
+     *
+     * The organising principle: **cross the boundary for actions a later action can undo.** Every
+     * crossing above is recoverable, which is what lets the crossing be justified on operator need
+     * alone. `delete: admin` is the inverse and is therefore held to a higher bar it does not yet
+     * meet. `organizationMembers.grantOwnership` (the owner-floor repair door) follows the same rule
+     * on the membership resource.
+     *
+     * See `.claude/rules/administrative-continuity-floors.md` and
+     * `cross-tenant-super-admin-reach.mongo.integration.test.ts`.
+     */
     operationsConfiguration: {
         [CoreResourceOperation.CREATE]: {
             variants: [
+                {
+                    // Registration and registration-onboarding create organizations through
+                    // `ServicesRegistryHandlerBackendService.create()`. INTERNAL_CALL is the
+                    // service layer's native, route-less transport, so it gives that trusted
+                    // workflow a distinct operation identity instead of making it masquerade
+                    // as the public self-service endpoint. The organization CREATE prefix
+                    // allows creation-policy-managed types only on this path.
+                    variantType: ResourceOperationVariantType.INTERNAL_CALL,
+                    isDefault: true,
+                    roles: [],
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                },
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
-                    roles: ['USER_SELF'], // Users can create their organizations
+                    roles: [CORE_APP_ROLES.APP_USER], // Any authenticated user can create their own organization (ownership is established by the create flow, not a role)
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
                     // DTOs auto-derived from decorators (excludeFromCreate on _id, createdAt, updatedAt)
-                    // status manually excluded for this variant (auto-set to ACTIVE)
+                    // `status` IS accepted on CREATE (it carries `.default(ACTIVE)`, so an omitted value
+                    // lands ACTIVE). Only UPDATE excludes it — see the field's JSDoc for why a tenant must
+                    // not be able to re-set its own lifecycle state after the fact.
                 },
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: false,
                     variantKey: "admin",
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Super admins can create organizations for any customer
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Not crossed — see the banner table; creation has no existing tenant to cross into
                     riskLevel: ResourceOperationRiskLevel.LOW,
                     // DTOs auto-derived from decorators (excludeFromCreate on _id, createdAt, updatedAt)
                 }
@@ -84,17 +174,61 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: false,
                     variantKey: "admin",
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Super admins can view any organization
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Not crossed — see the banner table; a super-admin reads organizations they are scoped to
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }
             ]
         },
+        /**
+         * ⚠️ THE SCOPE-ROOT COLLECTION OPERATIONS — read this before changing LIST, SEARCH or the roles
+         * either declares.
+         *
+         * `organizations` is the ONLY resource that is both ORGANIZATIONS-scoped and its own scope ROOT,
+         * and that makes both of its collection reads special in a way no other resource's are.
+         *
+         * **Their roles resolve against the APPLICATION table, not the organization one.** There is no
+         * `:organizationId` segment on `/organizations`, so `validateParentScopeAccess` cannot ask "what
+         * are your roles inside THIS tenant" — it takes the scope-root branch and validates the declared
+         * roles against the caller's APPLICATION-scope entries. Declaring an ORGANIZATION role on either
+         * of these would therefore be unsatisfiable, not merely unusual.
+         *
+         * **Row confinement is NOT free here, and until 2026-08-11 it did not exist.** Every other
+         * org-scoped resource is confined on its `organizationId` COLUMN; the tenant row has no such
+         * column, so both persistence adapters lost the axis and a scope-root LIST compiled to the EMPTY
+         * filter. The comment that used to sit on this line asserted the opposite — "still filtered to
+         * the caller's own organization" — and was the reason the gate looked like the only thing
+         * broken. Confinement now comes from `assignScopeRootCollectionConfinementToFilter`, which
+         * restricts these reads to the tenants the caller holds an organization-WIDE role entry for.
+         *
+         * So a platform super-administrator sees THEIR OWN organizations here, not every tenant — which
+         * is the same correction the banner above records for the other eleven super-admin variants. A
+         * genuine cross-tenant directory is NOT available by declaring
+         * `admitsCrossTenantPlatformAdministration`: that admission requires a usable platform-access
+         * grant for a TARGET tenant, and a collection call has no target. See
+         * `.claude/plans/organizations-scope-root-collection-gate-analysis.md`.
+         *
+         * ## ⚠️ If you are here because an operator "cannot find the tenant id", STOP
+         *
+         * That is the known and DELIBERATE consequence of the confinement, not a bug in it. An operator
+         * needs an `organizationId` to request a platform-access grant, and no in-product surface yields
+         * the id of a tenant they are not a member of.
+         *
+         * Widening this operation is the obvious fix and the wrong one: it re-opens the cross-tenant
+         * disclosure the confinement closed, and hands the full customer list to every platform
+         * administrator as a standing privilege — exactly what the grant mechanism was built to remove.
+         *
+         * The intended flow is that the id arrives from OUTSIDE the product, with the customer's support
+         * ticket (Microsoft Customer Lockbox and Google Access Approval both work this way). The full
+         * reasoning, and what a legitimate directory operation would look like instead, is on
+         * `platformAccessGrants | requestAccess`'s `organizationId` field and in SEC-SCOPEROOT-5
+         * (`.claude/plans/DEFERRED.md`).
+         */
         [CoreResourceOperation.LIST]: {
             variants: [
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Only super admins can list all organizations
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Not crossed — resolved against the APPLICATION role table; rows confined to the caller's own organizations
                     riskLevel: ResourceOperationRiskLevel.LOW,
                     filterFields: ORGANIZATION_ADMIN_FILTER_FIELDS,
                     sortFields: ORGANIZATION_ADMIN_SORT_FIELDS,
@@ -105,7 +239,7 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
             variants: [{
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Same scope-root contract as LIST above
                     riskLevel: ResourceOperationRiskLevel.LOW,
                     isSearchable: true,
                     searchableFields: ['name', 'slug', 'email'],
@@ -122,16 +256,21 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
                     isDefault: true,
                     roles: [CORE_ORG_ROLES.ORG_ADMIN], // Org admins can update their organization
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
-                    // DTOs auto-derived from decorators (excludeFromUpdate on _id, slug, createdAt, updatedAt)
-                    // status manually excluded for this variant
+                    // DTOs auto-derived from decorators (excludeFromUpdate on _id, type,
+                    // slug, status, createdAt, updatedAt). Organization-type transitions require
+                    // a dedicated dependent-policy migration, not a generic patch, and `status`
+                    // belongs to the SUSPEND / ACTIVATE verbs — this variant is ORG_ADMIN-gated, so
+                    // accepting it here let a suspended tenant reinstate itself.
                 },
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: false,
                     variantKey: "admin",
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Super admins can update any organization
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Not crossed — see the banner table
                     riskLevel: ResourceOperationRiskLevel.LOW,
-                    // DTOs auto-derived from decorators (excludeFromUpdate on _id, slug, createdAt, updatedAt)
+                    // DTOs auto-derived from decorators (excludeFromUpdate on _id, type,
+                    // slug, createdAt, updatedAt). Super-admin scope does not make a raw
+                    // type rewrite semantically safe.
                 }
             ],
             userNotifications: [
@@ -141,43 +280,154 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
                 }
             ]
         },
+        /**
+         * DELETE is the PURGE — the irreversible half of tenant teardown, reached at the END of the
+         * retention window and no longer the tenant-facing door.
+         *
+         * ## Why the tenant-facing variant is gone
+         *
+         * Deleting a tenant used to be synchronous and immediate: one `DELETE /organizations/{id}` by
+         * an ORG_ADMIN destroyed the tenant and everything the cascade reached. Tenant offboarding is
+         * a job-shaped problem, not a request-shaped one, so it is now two phases —
+         * {@link Organization_Lifecycle_Operations.REQUEST_DELETION} marks the tenant (and kills its
+         * authority immediately), and this operation destroys it once
+         * `Organization.purgeScheduledAt` has elapsed. Leaving an ORG_ADMIN-reachable synchronous
+         * DELETE in place would have made the retention window optional for exactly the caller it
+         * protects, which is the same as not having one.
+         *
+         * ## The two remaining doors
+         *
+         * - **INTERNAL_CALL (default)** — the route-less service transport the `organization-purge`
+         *   batch dispatches through. Route-less is the point: a window that any client can skip is
+         *   decorative. This mirrors CREATE on this same resource, whose default is likewise an
+         *   INTERNAL_CALL owned by a trusted workflow.
+         * - **API_CALL `admin`** — the super-administrator's deliberate purge-now escape hatch, for a
+         *   legal-order or abuse takedown that cannot wait out the window. Kept because operators
+         *   genuinely need it and because forcing them to a database console would be strictly worse
+         *   for auditability: this door is role-gated, step-up-gated, and emits `ORGANIZATION_DELETED`
+         *   like any other purge. It SKIPS the retention window by design.
+         *
+         * ⚠️ Custom implementations resolve by an exact operation-path key that embeds `variantType`.
+         * The default door changing from API_CALL to INTERNAL_CALL therefore MOVES the key that
+         * `organization-deletion-audit.custom-impl.backend.service.ts` registers on — that file was
+         * updated in the same pass. A hook left on the old key silently never runs.
+         *
+         * Cascading delete is handled via `childOperations.lifecycle.onParentDelete` on relationships.
+         *
+         * ⚠️ NO `userNotifications` here any more. They moved to `REQUEST_DELETION`, which is where
+         * they can still reach anyone: telling an organization's users that it has been deleted, in
+         * the same transaction that deletes those users' memberships, is a notification with no
+         * audience — and the batch that triggers a purge has no initiating user context to render it
+         * from. The members are told when the tenant is MARKED, which is also the only moment the
+         * warning is actionable (it can still be restored).
+         */
         [CoreResourceOperation.DELETE]: {
             variants: [
                 {
-                    variantType: ResourceOperationVariantType.API_CALL,
+                    variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
-                    roles: [CORE_ORG_ROLES.ORG_ADMIN], // Org admins can delete their organization
+                    roles: [],
                     riskLevel: ResourceOperationRiskLevel.CRITICAL,
-                    // Cascading delete is now handled via childOperations.lifecycle.onParentDelete on relationships
                 },
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: false,
                     variantKey: "admin",
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Super admins can delete any organization
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
                     riskLevel: ResourceOperationRiskLevel.HIGH,
-                    // Cascading delete is now handled via childOperations.lifecycle.onParentDelete on relationships
+                    //
+                    // ⚠️ DELIBERATELY NOT CROSS-TENANT — the one super-admin door on this resource left shut,
+                    // decided 2026-08-05. Do not "finish the job" by adding
+                    // `admitsCrossTenantPlatformAdministration` here without re-opening the decision below.
+                    //
+                    // The tension is real and worth stating rather than hiding: the JSDoc above says this door
+                    // is kept because operators genuinely need it and because pushing them to a database
+                    // console would be strictly worse for auditability. Both halves argue for opening it. What
+                    // outweighs them is asymmetry of consequence.
+                    //
+                    // Every other crossing on this resource is recoverable. ACTIVATE un-halts, RESTORE
+                    // un-marks, REQUEST_DELETION marks-with-a-window. `grantOwnership` on the membership
+                    // resource is additive and idempotent. Their safety argument is "one narrow effect that a
+                    // later action can undo". This operation is the exact inverse: irreversible, whole-tenant,
+                    // cascading, and it SKIPS the window on purpose. There is no RESTORE after a purge.
+                    //
+                    // The security cost is a change of KIND, not degree. Today a compromised platform-admin
+                    // credential can destroy only tenants that principal is already scoped into — accidental
+                    // containment, but real containment. Crossing this one converts that same compromise into
+                    // "any tenant, immediately". `requiresStepUpAuthentication` answers a hijacked session; it
+                    // does not answer phished credentials with the second factor supplied.
+                    //
+                    // And the operational pressure that makes opening it feel urgent is mostly relieved by the
+                    // three doors that DID open: a legal-order or abuse takedown can now be executed
+                    // cross-tenant through REQUEST_DELETION (mark + notify + window), with RESTORE available
+                    // if the order is stayed or the abuse call was wrong. That covers the cited use cases with
+                    // a recovery path. What remains uncovered is only "destroy within hours, irreversibly,
+                    // against a tenant the operator is not in".
+                    //
+                    // If that residue must be covered, the answer is NOT this flag alone. Require, together:
+                    // a mandatory `justification` on the request DTO (as `organizationMembers.grantOwnership`
+                    // has), a distinct high-severity audit event separable from routine purges, and a
+                    // two-person rule. Instant irreversible cross-tenant destruction is the one capability in
+                    // this product that deserves a second SIGNATURE, not merely a second factor. Until those
+                    // exist, the honest operator answer is the window — or a database console with a change
+                    // ticket, which at least leaves a human trail outside the system it is destroying.
+                    //
+                    // assurance-control: WILDO.ACCESS.CROSS_TENANT_ADMINISTRATION — deliberate non-grant;
+                    // the blast radius of this verb is not admitted to platform tier.
+                    //
+                    //
+                    // Irreversible destruction of a whole tenant, and it cascades. A hijacked session must not
+                    // be able to do this on the strength of a login that happened at some earlier point:
+                    // `riskLevel` is UI-only, and the per-user-type `stepUpAuth` policy is opt-in, off by
+                    // default, and satisfied by any authentication newer than `maxAgeSeconds`.
+                    //
+                    // assurance-control: WILDO.IDENTITY.STEP_UP_AUTHENTICATION — re-authentication before a high-impact action.
+                    requiresStepUpAuthentication: true,
                 }
             ],
-            userNotifications: [
-                {
-                    target: CoreUserNotificationTarget.ORGANIZATION_USERS,
-                    channel: CoreUserNotificationChannel.EMAIL,
-                }
-            ]
         },
-        [Organization_AppAdmin_Operations.ACTIVATE]: {
+        [Organization_Lifecycle_Operations.ACTIVATE]: {
             variants: [
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
-                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // Only super admins can activate organizations
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
                     resourceOperationLike: CoreResourceOperation.UPDATE,
+                    // Cross-tenant, because otherwise this door cannot be opened by anyone. `SUSPENDED` is in
+                    // `ORGANIZATION_STATUSES_WITHOUT_AUTHORITY`, so a suspended tenant's own admins hold no
+                    // authority — and ACTIVATE is reachable only FROM `SUSPENDED` or `TRIAL_EXPIRED`. Without
+                    // the crossing, the only principal who could un-suspend a tenant is a super-administrator
+                    // who happens to already be a member of it, which is an accident of staffing rather than a
+                    // control. Purely recuperative: it moves a halted tenant back to operational and destroys
+                    // nothing, so admitting the crossing costs no reversibility.
+                    admitsCrossTenantPlatformAdministration: true,
                     requestDto: z.object({
                         reason: z.string().max(500).optional()
                     }),
-                    haveBulkOperation: true
+                    // Conditional availability by org status. ACTIVATE re-enables a halted
+                    // or inactive organization, so it is available only from SUSPENDED or
+                    // TRIAL_EXPIRED — never from ACTIVE (a no-op) nor the terminal
+                    // CANCELLED / DELETED states. Evaluated on BOTH the frontend (the
+                    // action renders disabled otherwise, via `useOperationsEnabled`) AND
+                    // the backend (`services-registry-handler` throws
+                    // `SERVICE_RESOURCE_OPERATION_DISABLED` → 403 when false), so the guard
+                    // holds even if the client is bypassed. Keep in sync with the resource
+                    // spec's ACTIVATE error scenarios.
+                    enabledCondition: ({ currentObject }) => {
+                        return (currentObject.status === OrganizationStatus.SUSPENDED ||
+                            currentObject.status === OrganizationStatus.TRIAL_EXPIRED);
+                    },
+                    // NO `haveBulkOperation`. The generated bulk variant was removed on 2026-08-01: it could
+                    // never do bulk work. `assertBulkHookObjectContextAvailability` fails a bulk UPDATE
+                    // closed whenever its `enabledCondition` needs object context and no single persisted
+                    // `currentObject` is available — and the condition above reads `currentObject.status` by
+                    // construction, because the whole point is that ACTIVATE is only legal from specific
+                    // states. So a multi-org selector was refused (403) BY DESIGN and the variant only ever
+                    // worked with a one-element `_ids` array: a more expensive spelling of this variant, at
+                    // the cost of a second route and a second custom-implementation registration
+                    // (`isBulkOperation` is part of the operation-path key). Bulk suspension would require
+                    // abandoning the per-row state gate, which is not a trade this operation should make.
                 }
             ],
             userNotifications: [
@@ -187,7 +437,7 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
                 }
             ]
         },
-        [Organization_AppAdmin_Operations.SUSPEND]: {
+        [Organization_Lifecycle_Operations.SUSPEND]: {
             variants: [
                 {
                     variantType: ResourceOperationVariantType.API_CALL,
@@ -199,7 +449,228 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
                         suspensionReason: z.string().min(1).max(500),
                         notifyMembers: z.boolean().default(true)
                     }),
-                    haveBulkOperation: true
+                    // Conditional availability by org status. SUSPEND halts an operational
+                    // organization, so it is available only from ACTIVE or TRIAL — never
+                    // from SUSPENDED (a no-op) nor the terminal CANCELLED / DELETED states.
+                    // Enforced on the frontend (the action renders disabled otherwise) AND
+                    // the backend (`services-registry-handler` throws
+                    // `SERVICE_RESOURCE_OPERATION_DISABLED` → 403), so re-suspending an
+                    // already-suspended org fails closed server-side. Keep in sync with the
+                    // resource spec's SUSPEND error scenarios.
+                    enabledCondition: ({ currentObject }) => {
+                        return (currentObject.status === OrganizationStatus.ACTIVE ||
+                            currentObject.status === OrganizationStatus.TRIAL);
+                    },
+                    // NO `haveBulkOperation` — same reasoning as ACTIVATE above. Suspending many tenants in
+                    // one request is exactly the operation whose per-row state gate must not be dropped.
+                }
+            ],
+            userNotifications: [
+                {
+                    target: CoreUserNotificationTarget.ORGANIZATION_USERS,
+                    channel: CoreUserNotificationChannel.EMAIL,
+                    // Honours the `notifyMembers` flag the request contract has always advertised.
+                    //
+                    // Until this operation was implemented the flag was inert in the worst way: the DTO
+                    // accepted it, the caller could set it to `false`, and the declarative notification fired
+                    // regardless — a silent contract lie on an operation that emails an entire tenant. A
+                    // suspension is sometimes deliberately quiet (a fraud hold the operator does not want to
+                    // tip off), so this is a real capability rather than a formality.
+                    //
+                    // `!== false` rather than a truthy test: the field carries `.default(true)`, so an
+                    // omitted value must still notify.
+                    condition: ({ inputDto }) => inputDto?.notifyMembers !== false,
+                }
+            ]
+        },
+        /**
+         * Mark the tenant for deletion — the SOFT-DELETE phase, and the door that replaced the
+         * tenant-facing `DELETE`.
+         *
+         * ## What fires here, and what deliberately does not
+         *
+         * Authorization consequences fire NOW; data removal waits for the purge. The split is the
+         * load-bearing part of the design:
+         *
+         * - **now** — `status: DELETED` + `deletionRequestedAt` + `purgeScheduledAt`; every affected user's
+         *   GLOBAL `user.userTypes` reconciled; their tokens invalidated. A global grant that exists
+         *   only because of this tenant must not outlive it by the length of the retention window —
+         *   that grant outliving its justification is the original defect this whole workstream
+         *   exists to fix, and deferring it to the purge would ship that defect with a longer fuse.
+         * - **later (purge)** — membership rows, unit assignments and every other org child.
+         *
+         * The rule that decides which side a concern lands on: remove at mark time only what is
+         * RE-DERIVABLE on restore. Org-scoped roles are re-derivable from the membership rows, so the
+         * rows stay and the authority is recomputed per request from `status` (see
+         * `isAuthorityConferringOrganizationStatus`). Global `userTypes` are NOT re-derivable that
+         * way — they are a denormalized grant on the user row — so they are reconciled here, and
+         * `restore` re-grants them.
+         *
+         * ## Audience limitation inherited from the DELETE door this replaces
+         *
+         * ⚠️ KNOWN, accepted deliberately. Re-authentication proves identity by PASSWORD only today,
+         * and the framework DESTROYS `passwordHash` + passkeys for directory-managed (SCIM) users as a
+         * compliance control (`_reconcileLocalCredentialsForDirectoryManaged`). So an ORG_ADMIN of a
+         * directory-managed organization cannot satisfy the step-up gate and is refused. That is
+         * fail-closed on the most destructive action available to a tenant, and the refusal is
+         * diagnosable — the step-up round-trip ends in an explicit "No password set for this account".
+         * Extending re-authentication to TOTP (which IS preserved for directory-managed users) removes
+         * the limitation; until then such a tenant is marked through the `admin` variant below.
+         *
+         * assurance-control: WILDO.IDENTITY.STEP_UP_AUTHENTICATION — re-authentication before a high-impact
+         * action; the tenant loses its access rights at the moment of the decision, not at the moment
+         * its data is destroyed.
+         */
+        [Organization_Lifecycle_Operations.REQUEST_DELETION]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_ADMIN], // Org admins can schedule their own organization's deletion
+                    riskLevel: ResourceOperationRiskLevel.CRITICAL,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    requestDto: z.object({
+                        reason: z.string().max(500).optional()
+                    }),
+                    requiresStepUpAuthentication: true,
+                    // Available only from a state the tenant can still be marked FROM. Never from DELETED
+                    // (already marked — restore or wait for the purge) nor from the terminal CANCELLED.
+                    // Enforced on the frontend (the action renders disabled) AND the backend
+                    // (`services-registry-handler` throws `SERVICE_RESOURCE_OPERATION_DISABLED` → 403), so a
+                    // double-mark fails closed server-side and cannot silently re-arm the window. Keep in
+                    // sync with the resource spec's REQUEST_DELETION error scenarios.
+                    //
+                    // The condition is shared with the `admin` variant below, and the ROLE gate is what
+                    // makes them differ in practice: `SUSPENDED` confers no authority
+                    // (`ORGANIZATION_STATUSES_WITHOUT_AUTHORITY`), so on THIS variant that arm is
+                    // unreachable — an org admin cannot mark a tenant the platform has halted. It is
+                    // reachable on the `admin` variant, which is the intended shape: a suspended tenant is
+                    // under platform control, and the platform can still schedule its deletion.
+                    enabledCondition: ({ currentObject }) => {
+                        return (currentObject.status === OrganizationStatus.ACTIVE ||
+                            currentObject.status === OrganizationStatus.TRIAL ||
+                            currentObject.status === OrganizationStatus.TRIAL_EXPIRED ||
+                            currentObject.status === OrganizationStatus.SUSPENDED);
+                    },
+                    // NO `haveBulkOperation` — same reasoning as SUSPEND/ACTIVATE: the per-row state gate
+                    // above reads `currentObject.status`, and a bulk UPDATE whose `enabledCondition` needs
+                    // object context is failed closed by `assertBulkHookObjectContextAvailability`.
+                },
+                {
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: false,
+                    variantKey: "admin",
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    // Cross-tenant: this is the operator's takedown path, and it is the REVERSIBLE one. It
+                    // MARKS the tenant, notifies its users, and starts the retention window — every effect can
+                    // be undone by RESTORE (also crossed, immediately above; crossing one without the other
+                    // would hand operators a one-way door and call it a window).
+                    //
+                    // The JSDoc on the sibling org-admin variant already asserts this shape — "a suspended
+                    // tenant is under platform control, and the platform can still schedule its deletion" —
+                    // which was true of the role gate and false of the runtime until this flag.
+                    //
+                    // Deliberately the FIRST destructive door opened, and deliberately not the last one: a
+                    // legal-order or abuse takedown routed through MARK + window keeps a recovery path open,
+                    // which is what makes leaving instant purge closed (see DELETE `admin`) affordable rather
+                    // than merely cautious.
+                    admitsCrossTenantPlatformAdministration: true,
+                    riskLevel: ResourceOperationRiskLevel.HIGH,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    requestDto: z.object({
+                        reason: z.string().max(500).optional()
+                    }),
+                    // The flag is per-VARIANT — nothing is inherited from the variant above. Marking someone
+                    // else's tenant for destruction is not a lesser act than marking your own.
+                    requiresStepUpAuthentication: true,
+                    enabledCondition: ({ currentObject }) => {
+                        return (currentObject.status === OrganizationStatus.ACTIVE ||
+                            currentObject.status === OrganizationStatus.TRIAL ||
+                            currentObject.status === OrganizationStatus.TRIAL_EXPIRED ||
+                            currentObject.status === OrganizationStatus.SUSPENDED);
+                    },
+                }
+            ],
+            userNotifications: [
+                {
+                    // The members ARE the audience here, and this is the only moment the warning is
+                    // actionable — the tenant can still be restored. This notification moved from DELETE,
+                    // where by the time it fired its recipients were being deleted in the same transaction.
+                    target: CoreUserNotificationTarget.ORGANIZATION_USERS,
+                    channel: CoreUserNotificationChannel.EMAIL,
+                }
+            ]
+        },
+        /**
+         * Cancel a pending deletion — the inverse of
+         * {@link Organization_Lifecycle_Operations.REQUEST_DELETION}, available for the whole
+         * retention window.
+         *
+         * Restoring needs no data re-creation, and that is a property of the phase split rather than a
+         * happy accident: the mark deliberately removed only what is re-derivable. Membership rows,
+         * unit assignments and every other child were never touched, so clearing `status` re-arms
+         * org-scoped authority on the next request for free. The one thing that WAS removed — each
+         * affected user's global `userTypes` — is re-granted here from the same configuration that
+         * granted it originally.
+         *
+         * ## Why the window is not re-checked here
+         *
+         * There is no "too late to restore" branch. If the purge has run, the row is gone and the
+         * operation 404s at addressing; if the row is present, it is restorable. Encoding a second
+         * time-based rule would create a state where a row exists but claims to be unrecoverable —
+         * an unrecoverable row that still holds every one of its members' data is the worst of both
+         * phases.
+         *
+         * Deliberately NOT step-up gated: restoring is the SAFE direction. Every other lifecycle verb
+         * here reduces access or destroys data; this one returns a tenant to the state it was already
+         * in. Gating recovery behind the same friction as destruction discourages the correct
+         * response to a mistaken deletion.
+         *
+         * ## ⚠️ Why this is SUPER-ADMIN ONLY — a tenant cannot un-mark itself
+         *
+         * Not a policy preference: an ORG-scoped variant here would be UNSATISFIABLE. A `DELETED`
+         * organization confers no authority at all
+         * (`ORGANIZATION_STATUSES_WITHOUT_AUTHORITY`), so its ORG_ADMIN no longer holds `ORG_ADMIN`
+         * anywhere and would be refused by the role gate before `enabledCondition` was ever consulted.
+         * Declaring the variant anyway would ship a door that renders in the UI, is documented in the
+         * spec, and answers 403 forever.
+         *
+         * That is also the correct product shape, and it is what every comparable system does —
+         * Microsoft 365, Google Workspace, Salesforce and AWS all recover a deleted tenant through the
+         * PROVIDER's administrator or support, never through the deleted tenant's own credentials.
+         * The tenant-facing safety net is the retention window itself; the recovery action is an
+         * operator's.
+         *
+         * assurance-control: WILDO.DATA.SECURE_LIFECYCLE — a reversible deletion decision, with the
+         * reversal itself audited and performed by a separately-privileged party.
+         */
+        [Organization_Lifecycle_Operations.RESTORE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], // See the JSDoc: an org-scoped variant would be unsatisfiable
+                    riskLevel: ResourceOperationRiskLevel.HIGH,
+                    // Cross-tenant, and this variant is WHY the gap was worth finding. The JSDoc above rejects
+                    // an org-scoped variant precisely because it "would ship a door that renders in the UI, is
+                    // documented in the spec, and answers 403 forever" — and then shipped exactly that one
+                    // tier up: a MARKED tenant is `DELETED`, which confers no authority, so its own admins
+                    // cannot restore it; and a platform administrator could not reach the row. Nobody could
+                    // restore a marked tenant, and the purge batch collected it when the window expired.
+                    //
+                    // That makes the retention window the load-bearing casualty: a window whose release nobody
+                    // can pull is not a safety net, it is a delay. Restoring it here is what lets the rest of
+                    // the teardown lifecycle keep claiming reversibility.
+                    admitsCrossTenantPlatformAdministration: true,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    requestDto: z.object({
+                        reason: z.string().max(500).optional()
+                    }),
+                    // Only a MARKED tenant can be restored. From any live state this is a no-op, and from
+                    // the terminal CANCELLED it is not a deletion being undone.
+                    enabledCondition: ({ currentObject }) => {
+                        return currentObject.status === OrganizationStatus.DELETED;
+                    },
                 }
             ],
             userNotifications: [
@@ -211,4 +682,4 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
         }
     },
 });
-//# sourceMappingURL=organizations.shared.resources-config.schemas.js.map
+//# sourceMappingURL=organizations.shared.resources-config.schemas.js.map