@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/backend/packages/iam/src/@bridges/iam/account/adapters/iam-account-loader.adapter.spec.ts

@@ -1,7 +1,13 @@
-import { IamFindAccountService, IamUpdateAccountByIdService } from '@app/iam/account';
-import { IamGetRolesService } from '@app/iam/role';
+import type { Mock } from 'vitest';
+import { IamFindAccountService, IamUpdateAccountByIdService } from '@app/iam/account/index.js';
+import { IamGetRolesService } from '@app/iam/role/index.js';
+import { IamGetTenantsService } from '@app/iam/tenant/index.js';
+// Sub-barrel import, not the '@aurora/modules' root barrel: the root barrel evaluates
+// AuthenticationModule, which HR-MODGRAPH-001 requires stay a leaf. `domain/ports` is
+// contracts-only (interfaces + Symbol tokens, zero side-effects).
+import { ACCOUNT_CACHE_INVALIDATOR } from '@aurora/modules/authentication/domain/ports/index.js';
 import { Test, TestingModule } from '@nestjs/testing';
-import { IamAccountLoaderAdapter } from './iam-account-loader.adapter';
+import { IamAccountLoaderAdapter } from './iam-account-loader.adapter.js';
 
 // ─── Fixtures ────────────────────────────────────────────────────────────────
 
@@ -10,6 +16,9 @@ const ACCOUNT_ID = 'acc-0000-0000-0000-000000000001';
 const ROLE_ID_A = 'role-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
 const ROLE_ID_B = 'role-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
 
+const TENANT_ROOT_ID = 'tenant-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+const TENANT_CHILD_ID = 'tenant-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+
 /** Helper to build a fake IamAccount plain object (no Sequelize, no toJSON needed). */
 const buildFakeAccount = (overrides: Record<string, unknown> = {}) => ({
   id: ACCOUNT_ID,
@@ -23,6 +32,7 @@ const buildFakeAccount = (overrides: Record<string, unknown> = {}) => ({
   dApplicationCodes: [],
   dPermissions: { all: [], [ROLE_ID_A]: [] } as Record<string, string[]>,
   dTenants: [],
+  hasAddChildTenants: false,
   meta: null,
   // Shallow roles (no permissions) — as the main query now returns them.
   roles: [
@@ -72,14 +82,18 @@ const STORED_D_PERMISSIONS_STALE: Record<string, string[]> = {
 
 describe('IamAccountLoaderAdapter', () => {
   let adapter: IamAccountLoaderAdapter;
-  let findAccount: { main: jest.Mock };
-  let updateAccountById: { main: jest.Mock };
-  let getRoles: { main: jest.Mock };
+  let findAccount: { main: Mock };
+  let updateAccountById: { main: Mock };
+  let getRoles: { main: Mock };
+  let getTenants: { main: Mock };
+  let accountCacheInvalidator: { invalidate: Mock };
 
   beforeEach(async () => {
-    findAccount = { main: jest.fn() };
-    updateAccountById = { main: jest.fn().mockResolvedValue(undefined) };
-    getRoles = { main: jest.fn().mockResolvedValue([]) };
+    findAccount = { main: vi.fn() };
+    updateAccountById = { main: vi.fn().mockResolvedValue(undefined) };
+    getRoles = { main: vi.fn().mockResolvedValue([]) };
+    getTenants = { main: vi.fn().mockResolvedValue([]) };
+    accountCacheInvalidator = { invalidate: vi.fn().mockResolvedValue(undefined) };
 
     const module: TestingModule = await Test.createTestingModule({
       providers: [
@@ -87,6 +101,8 @@ describe('IamAccountLoaderAdapter', () => {
         { provide: IamFindAccountService, useValue: findAccount },
         { provide: IamUpdateAccountByIdService, useValue: updateAccountById },
         { provide: IamGetRolesService, useValue: getRoles },
+        { provide: IamGetTenantsService, useValue: getTenants },
+        { provide: ACCOUNT_CACHE_INVALIDATOR, useValue: accountCacheInvalidator },
       ],
     }).compile();
 
@@ -188,6 +204,35 @@ describe('IamAccountLoaderAdapter', () => {
       expect(result!.dPermissions.all).toEqual(
         expect.arrayContaining(['iam.account.get', 'iam.role.get']),
       );
+
+      // This write bypasses IamUpdateAccountByIdHandler (no @EmitEvent fires), so the
+      // authentication cache must be evicted directly here — otherwise an already-cached
+      // session for this account would keep serving the stale permissions for up to the TTL.
+      expect(accountCacheInvalidator.invalidate).toHaveBeenCalledTimes(1);
+      expect(accountCacheInvalidator.invalidate).toHaveBeenCalledWith(ACCOUNT_ID);
+    });
+  });
+
+  // ─── (b2) refreshPermissions: true + persisted write + cache invalidation fails (fail-soft) ──
+
+  describe('refreshPermissions: true — cache invalidation fails after a persisted write', () => {
+    it('returns the freshened account without rethrowing when accountCacheInvalidator.invalidate rejects', async () => {
+      const account = buildFakeAccount({ dPermissions: STORED_D_PERMISSIONS_STALE });
+      findAccount.main.mockResolvedValue(account);
+      getRoles.main.mockResolvedValue(buildRolesWithPermissions());
+      accountCacheInvalidator.invalidate.mockRejectedValue(new Error('cache down'));
+
+      const result = await adapter.loadById(ACCOUNT_ID, { refreshPermissions: true });
+
+      // The eviction was attempted (and failed) — pins that this test actually exercises the
+      // invalidation call, not just the pre-existing fail-soft return around the persist itself.
+      expect(accountCacheInvalidator.invalidate).toHaveBeenCalledWith(ACCOUNT_ID);
+
+      // Token issuance must not fail because the (best-effort) cache eviction failed.
+      expect(result).not.toBeNull();
+      expect(result!.dPermissions.all).toEqual(
+        expect.arrayContaining(['iam.account.get', 'iam.role.get']),
+      );
     });
   });
 
@@ -207,6 +252,8 @@ describe('IamAccountLoaderAdapter', () => {
       // No write — snapshot is already correct
       expect(updateAccountById.main).not.toHaveBeenCalled();
       expect(result).not.toBeNull();
+      // No persistence write means no drift was corrected — nothing to invalidate.
+      expect(accountCacheInvalidator.invalidate).not.toHaveBeenCalled();
     });
   });
 
@@ -251,12 +298,6 @@ describe('IamAccountLoaderAdapter', () => {
       // iam.role.get is absent (stale value)
       expect(result!.dPermissions.all).not.toContain('iam.role.get');
     });
-
-    it('confirms the test is non-tautological: without a catch, the error WOULD bubble', async () => {
-      // Direct verification: a rejected mock DOES throw if uncaught.
-      const throwingService = { main: jest.fn().mockRejectedValue(new Error('raw throw')) };
-      await expect(throwingService.main()).rejects.toThrow('raw throw');
-    });
   });
 
   // ─── (f) refreshPermissions: 'strict' — fail CLOSED (F3 fix) ──────────────
@@ -364,6 +405,17 @@ describe('IamAccountLoaderAdapter', () => {
         dPermissions: { all: expect.any(Array) },
       });
     });
+
+    // The create/update account handlers gate widening `hasAddChildTenants` on ANOTHER account
+    // by reading it off the caller's principal — if this mapping is dropped, every non-SUDO
+    // caller silently fails that guard because the field is always undefined.
+    it('carries hasAddChildTenants onto the mapped principal', async () => {
+      findAccount.main.mockResolvedValue(buildFakeAccount({ hasAddChildTenants: true }));
+
+      const result = await adapter.loadById(ACCOUNT_ID);
+
+      expect(result!.hasAddChildTenants).toBe(true);
+    });
   });
 
   // ─── Finding 1: Revocation (shrink) — permissions removed from live role ──
@@ -519,4 +571,257 @@ describe('IamAccountLoaderAdapter', () => {
       );
     });
   });
+
+  // ─── refreshTenants (a) — option absent: no tenant query, stored snapshot returned ──
+
+  describe('refreshTenants absent — no extra query, stored dTenants snapshot returned', () => {
+    it('does not call IamGetTenantsService and returns the stored snapshot', async () => {
+      const account = buildFakeAccount({ dTenants: [TENANT_ROOT_ID] });
+      findAccount.main.mockResolvedValue(account);
+
+      const result = await adapter.loadById(ACCOUNT_ID);
+
+      expect(getTenants.main).not.toHaveBeenCalled();
+      expect(updateAccountById.main).not.toHaveBeenCalled();
+      expect(result!.dTenants).toEqual([TENANT_ROOT_ID]);
+    });
+  });
+
+  // ─── refreshTenants (b) — a child created after the last save is discovered ─────────
+
+  describe('refreshTenants: true — hasAddChildTenants account, a child tenant was created since', () => {
+    it('returns dTenants containing the newly discovered descendant', async () => {
+      const account = buildFakeAccount({
+        hasAddChildTenants: true,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+      getTenants.main.mockResolvedValue([
+        { id: TENANT_ROOT_ID, parentId: null },
+        { id: TENANT_CHILD_ID, parentId: TENANT_ROOT_ID },
+      ]);
+
+      const result = await adapter.loadById(ACCOUNT_ID, { refreshTenants: true });
+
+      expect(result).not.toBeNull();
+      expect(result!.dTenants).toEqual(expect.arrayContaining([TENANT_ROOT_ID, TENANT_CHILD_ID]));
+    });
+  });
+
+  // ─── refreshTenants (c) — same fixture, WITHOUT the flag: child absent ──────────────
+
+  describe('refreshTenants: true — same fixture but the account cannot widen its scope', () => {
+    it('does not include the descendant when hasAddChildTenants is false', async () => {
+      const account = buildFakeAccount({
+        hasAddChildTenants: false,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+
+      const result = await adapter.loadById(ACCOUNT_ID, { refreshTenants: true });
+
+      expect(getTenants.main).not.toHaveBeenCalled();
+      expect(result).not.toBeNull();
+      expect(result!.dTenants).toEqual([TENANT_ROOT_ID]);
+      expect(result!.dTenants).not.toContain(TENANT_CHILD_ID);
+    });
+  });
+
+  // ─── refreshTenants (d) — recompute equal to stored: NO write ───────────────────────
+
+  describe('refreshTenants: true — recompute matches the stored snapshot (write-only-if-changed)', () => {
+    it('does not call updateAccountById when nothing changed', async () => {
+      const account = buildFakeAccount({
+        hasAddChildTenants: false,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+
+      await adapter.loadById(ACCOUNT_ID, { refreshTenants: true });
+
+      expect(updateAccountById.main).not.toHaveBeenCalled();
+      expect(accountCacheInvalidator.invalidate).not.toHaveBeenCalled();
+    });
+
+    it('does not call updateAccountById when the SAME set comes back in a DIFFERENT order — neither side has a stable order', async () => {
+      // The pivot read (`account.tenants`) and the stored `dTenants` snapshot are each produced
+      // by an independent, unordered path (a relation load vs. whatever order a previous save
+      // persisted) — an index-by-index array comparison would see this as a change and write on
+      // every token issuance even though the SET is identical.
+      const account = buildFakeAccount({
+        hasAddChildTenants: false,
+        tenants: [
+          { id: TENANT_CHILD_ID, name: 'Child' },
+          { id: TENANT_ROOT_ID, name: 'Root' },
+        ],
+        dTenants: [TENANT_ROOT_ID, TENANT_CHILD_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+
+      await adapter.loadById(ACCOUNT_ID, { refreshTenants: true });
+
+      expect(updateAccountById.main).not.toHaveBeenCalled();
+    });
+  });
+
+  // ─── refreshTenants (e) — recompute differs: updated exactly once ───────────────────
+
+  describe('refreshTenants: true — recompute differs from the stored snapshot', () => {
+    it('updates the account row exactly once and the returned account carries the new value', async () => {
+      const account = buildFakeAccount({
+        hasAddChildTenants: true,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+      getTenants.main.mockResolvedValue([
+        { id: TENANT_ROOT_ID, parentId: null },
+        { id: TENANT_CHILD_ID, parentId: TENANT_ROOT_ID },
+      ]);
+
+      const result = await adapter.loadById(ACCOUNT_ID, { refreshTenants: true });
+
+      expect(updateAccountById.main).toHaveBeenCalledTimes(1);
+      expect(updateAccountById.main).toHaveBeenCalledWith(
+        expect.objectContaining({
+          id: ACCOUNT_ID,
+          dTenants: expect.arrayContaining([TENANT_ROOT_ID, TENANT_CHILD_ID]),
+        }),
+        undefined,
+        undefined,
+      );
+      expect(result).not.toBeNull();
+      expect(result!.dTenants).toEqual(expect.arrayContaining([TENANT_ROOT_ID, TENANT_CHILD_ID]));
+
+      // Same reasoning as the dPermissions branch: this write never emits
+      // `iam.account.updated`, so the authentication cache must be evicted here directly.
+      expect(accountCacheInvalidator.invalidate).toHaveBeenCalledTimes(1);
+      expect(accountCacheInvalidator.invalidate).toHaveBeenCalledWith(ACCOUNT_ID);
+    });
+  });
+
+  // ─── refreshTenants (e2) — same-size membership swap: length alone cannot detect this ──
+
+  describe('refreshTenants: true — recomputed set has the SAME length as stored but DIFFERENT content', () => {
+    it('updates the account row and the returned account carries the new membership, not the stale one', async () => {
+      // Direct membership moved from TENANT_ROOT_ID to TENANT_CHILD_ID (revoked one, granted the
+      // other) — the stored snapshot still says TENANT_ROOT_ID. Both sets have length 1, so a
+      // length-only comparison would see "no change" and keep serving the revoked tenant.
+      const account = buildFakeAccount({
+        hasAddChildTenants: false,
+        tenants: [{ id: TENANT_CHILD_ID, name: 'Child' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+
+      const result = await adapter.loadById(ACCOUNT_ID, { refreshTenants: true });
+
+      expect(updateAccountById.main).toHaveBeenCalledTimes(1);
+      expect(updateAccountById.main).toHaveBeenCalledWith(
+        { id: ACCOUNT_ID, dTenants: [TENANT_CHILD_ID] },
+        undefined,
+        undefined,
+      );
+      expect(result).not.toBeNull();
+      expect(result!.dTenants).toEqual([TENANT_CHILD_ID]);
+      expect(result!.dTenants).not.toContain(TENANT_ROOT_ID);
+    });
+  });
+
+  // ─── refreshTenants (f) — throws with `true`: fail-soft ─────────────────────────────
+
+  describe('refreshTenants: true — fail-soft on tenant query error', () => {
+    it('returns the stored snapshot without rethrowing when IamGetTenantsService throws', async () => {
+      const account = buildFakeAccount({
+        hasAddChildTenants: true,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+      getTenants.main.mockRejectedValue(new Error('Tenants DB error — simulated failure'));
+
+      const result = await adapter.loadById(ACCOUNT_ID, { refreshTenants: true });
+
+      expect(result).not.toBeNull();
+      expect(result!.dTenants).toEqual([TENANT_ROOT_ID]);
+      expect(updateAccountById.main).not.toHaveBeenCalled();
+    });
+  });
+
+  // ─── refreshTenants (g) — throws with 'strict': rethrown ────────────────────────────
+
+  describe("refreshTenants: 'strict' — rethrows on tenant query error instead of falling back", () => {
+    it('rejects with the original error', async () => {
+      const account = buildFakeAccount({
+        hasAddChildTenants: true,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+      getTenants.main.mockRejectedValue(new Error('Tenants DB error — simulated failure'));
+
+      await expect(adapter.loadById(ACCOUNT_ID, { refreshTenants: 'strict' })).rejects.toThrow(
+        'Tenants DB error — simulated failure',
+      );
+      expect(updateAccountById.main).not.toHaveBeenCalled();
+    });
+  });
+
+  // ─── refreshTenants (h) — the two refreshes are independent in failure ──────────────
+
+  describe('refreshPermissions and refreshTenants are independent on failure', () => {
+    it('a failing tenant refresh does not suppress a successful permission refresh', async () => {
+      const account = buildFakeAccount({
+        dPermissions: STORED_D_PERMISSIONS_STALE,
+        hasAddChildTenants: true,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+      getRoles.main.mockResolvedValue(buildRolesWithPermissions());
+      getTenants.main.mockRejectedValue(new Error('Tenants DB error — simulated failure'));
+
+      const result = await adapter.loadById(ACCOUNT_ID, {
+        refreshPermissions: true,
+        refreshTenants: true,
+      });
+
+      expect(result).not.toBeNull();
+      // Permission refresh succeeded despite the tenant refresh failing.
+      expect(result!.dPermissions.all).toEqual(
+        expect.arrayContaining(['iam.account.get', 'iam.role.get']),
+      );
+      // Tenant refresh fell back to the stored snapshot.
+      expect(result!.dTenants).toEqual([TENANT_ROOT_ID]);
+    });
+
+    it('a failing permission refresh does not suppress a successful tenant refresh', async () => {
+      const account = buildFakeAccount({
+        dPermissions: STORED_D_PERMISSIONS_STALE,
+        hasAddChildTenants: true,
+        tenants: [{ id: TENANT_ROOT_ID, name: 'Root' }],
+        dTenants: [TENANT_ROOT_ID],
+      });
+      findAccount.main.mockResolvedValue(account);
+      getRoles.main.mockRejectedValue(new Error('Roles DB error — simulated failure'));
+      getTenants.main.mockResolvedValue([
+        { id: TENANT_ROOT_ID, parentId: null },
+        { id: TENANT_CHILD_ID, parentId: TENANT_ROOT_ID },
+      ]);
+
+      const result = await adapter.loadById(ACCOUNT_ID, {
+        refreshPermissions: true,
+        refreshTenants: true,
+      });
+
+      expect(result).not.toBeNull();
+      // Permission refresh fell back to the stored (stale) snapshot.
+      expect(result!.dPermissions.all).toEqual(STORED_D_PERMISSIONS_STALE.all);
+      // Tenant refresh succeeded despite the permission refresh failing.
+      expect(result!.dTenants).toEqual(expect.arrayContaining([TENANT_ROOT_ID, TENANT_CHILD_ID]));
+    });
+  });
 });

package/dist/templates/backend/packages/iam/src/@bridges/iam/account/adapters/iam-account-loader.adapter.ts

@@ -1,10 +1,18 @@
-import { IamAccount, IamRole } from '@api/graphql';
-import { IamFindAccountService, IamUpdateAccountByIdService } from '@app/iam/account';
-import { IamGetRolesService } from '@app/iam/role';
-import { iamCreatePermissionsFromRoles } from '@app/iam/shared';
-import type { AuthenticatedAccount, IAccountLoader, IAccountLoaderOptions } from '@aurora/modules';
+import { IamAccount, IamRole, IamTenant } from '@api/graphql.js';
+import { IamFindAccountService, IamUpdateAccountByIdService } from '@app/iam/account/index.js';
+import { IamGetRolesService } from '@app/iam/role/index.js';
+import { iamCreatePermissionsFromRoles, iamResolveAccountTenants } from '@app/iam/shared/index.js';
+import { IamGetTenantsService } from '@app/iam/tenant/index.js';
+import type { AuthenticatedAccount, IAccountLoader, IAccountLoaderOptions } from '@aurora/modules/index.js';
+// Sub-barrel import, not the '@aurora/modules' root barrel: the root barrel evaluates
+// AuthenticationModule, which HR-MODGRAPH-001 requires stay a leaf. `domain/ports` is
+// contracts-only (interfaces + Symbol tokens, zero side-effects).
+import {
+  ACCOUNT_CACHE_INVALIDATOR,
+  type IAccountCacheInvalidator,
+} from '@aurora/modules/authentication/domain/ports/index.js';
 import { Obj, QueryStatement } from '@aurorajs.dev/core-back';
-import { Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable, Logger } from '@nestjs/common';
 
 @Injectable()
 export class IamAccountLoaderAdapter implements IAccountLoader {
@@ -14,6 +22,11 @@ export class IamAccountLoaderAdapter implements IAccountLoader {
     private readonly findAccount: IamFindAccountService,
     private readonly updateAccountById: IamUpdateAccountByIdService,
     private readonly getRoles: IamGetRolesService,
+    private readonly getTenants: IamGetTenantsService,
+    // Cross-BC port (authentication is the supplier; this loader is the consumer). Provided
+    // app-wide by the @Global() BridgesModule — no module import needed here.
+    @Inject(ACCOUNT_CACHE_INVALIDATOR)
+    private readonly accountCacheInvalidator: IAccountCacheInvalidator,
   ) {}
 
   async loadById(
@@ -23,6 +36,8 @@ export class IamAccountLoaderAdapter implements IAccountLoader {
     const refreshPermissions =
       options?.refreshPermissions === true || options?.refreshPermissions === 'strict';
     const strict = options?.refreshPermissions === 'strict';
+    const refreshTenants = options?.refreshTenants === true || options?.refreshTenants === 'strict';
+    const strictTenants = options?.refreshTenants === 'strict';
 
     // Main query: always shallow roles (no nested permissions include).
     // Sibling collection includes (roles × tenants) produce a cartesian product;
@@ -36,6 +51,12 @@ export class IamAccountLoaderAdapter implements IAccountLoader {
 
     if (!account) return null;
 
+    // Both refresh blocks below accumulate their result here instead of returning early,
+    // so a failure in one NEVER short-circuits the other — the two denormalizations are
+    // independent by design (dPermissions costs a roles query, dTenants costs a full
+    // tenant-table read; a caller may want either without paying for both).
+    const overrides: Partial<IamAccount> = {};
+
     // Opt-in recompute path (D1): load roles WITH permissions in a separate decoupled
     // query, recompute dPermissions, persist only if changed (D2), fail-soft on any
     // error (D3).
@@ -81,15 +102,12 @@ export class IamAccountLoaderAdapter implements IAccountLoader {
             undefined,
             undefined,
           );
-          // Return the freshened snapshot.
-          // `account` is a Sequelize model instance at runtime whose column values
-          // are backed by `dataValues` getters, NOT own enumerable properties.
-          // Spreading `{ ...account }` loses those getter values (e.g. `id` becomes
-          // undefined). Re-serialising through JSON.parse(JSON.stringify()) forces
-          // all getter-backed values into own properties of a plain object before we
-          // override `dPermissions` with the freshly recomputed value.
-          const plain = JSON.parse(JSON.stringify(account)) as IamAccount;
-          return mapToAuthenticatedAccount({ ...plain, dPermissions: recomputed });
+          overrides.dPermissions = recomputed;
+          // This write bypasses IamUpdateAccountByIdHandler (it goes straight through the
+          // service), so `@EmitEvent('iam.account.updated')` never fires for it — evict the
+          // authentication cache directly, or a role-permission drift corrected here would stay
+          // masked in an already-cached session for up to CACHE_TTL_MS.
+          await this.invalidateAuthenticationCache(accountId);
         }
       } catch (error) {
         this.logger.error(
@@ -108,11 +126,101 @@ export class IamAccountLoaderAdapter implements IAccountLoader {
       }
     }
 
-    return mapToAuthenticatedAccount(account);
+    // Opt-in recompute path for dTenants — same shape as the permission block above, kept
+    // as its own try/catch (not nested inside it) so the two refreshes are independent in
+    // failure (design D2): one throwing must never suppress the other.
+    if (refreshTenants) {
+      try {
+        // `account.tenants` is the account's DIRECT tenant assignment (the m2m pivot), not
+        // the denormalized `dTenants` snapshot being refreshed here — the same distinction
+        // the create/update handlers make between `payload.tenantIds` and the derived value.
+        const directTenantIds = (account.tenants ?? [])
+          .filter((tenant): tenant is IamTenant => tenant !== null && tenant !== undefined)
+          .map((tenant) => tenant.id);
+
+        // The whole tenant table is only needed to walk descendants, so skip the read
+        // entirely when the account cannot widen its scope or has nothing to widen from.
+        let tenantRows: IamTenant[] = [];
+        if (account.hasAddChildTenants && directTenantIds.length > 0) {
+          tenantRows = await this.getTenants.main();
+        }
+
+        const recomputed = iamResolveAccountTenants(
+          directTenantIds,
+          tenantRows,
+          Boolean(account.hasAddChildTenants),
+        );
+
+        // Same reasoning as the permission block: this is change DETECTION, its result is
+        // never written, so HR-PERSISTENCE-001 does not apply — Obj.diff stays correct here.
+        // Unlike dPermissions above, NEITHER side here has a stable order: `directTenantIds`
+        // comes from a relation load and `stored` from whatever order a previous save
+        // persisted. Obj.diff compares arrays index by index, so it must run against SORTED
+        // copies — comparing the raw arrays would report a change (and write) on every token
+        // issuance for a same-membership reorder.
+        const stored = (account.dTenants ?? []) as string[];
+        const sortedRecomputed = [...recomputed].sort();
+        const sortedStored = [...stored].sort();
+        const valueDiff = Obj.diff(sortedRecomputed, sortedStored);
+        const hasChanges = recomputed.length !== stored.length || Object.keys(valueDiff).length > 0;
+
+        if (hasChanges) {
+          await this.updateAccountById.main(
+            { id: accountId, dTenants: recomputed },
+            undefined,
+            undefined,
+          );
+          overrides.dTenants = recomputed;
+          // Same reasoning as the dPermissions branch above: this write never emits
+          // `iam.account.updated`, so the authentication cache needs an explicit evict here.
+          await this.invalidateAuthenticationCache(accountId);
+        }
+      } catch (error) {
+        this.logger.error(
+          strictTenants
+            ? `[IamAccountLoaderAdapter] dTenants refresh failed for account ${accountId} — 'strict' mode: rejecting instead of serving a possibly-stale snapshot`
+            : `[IamAccountLoaderAdapter] dTenants refresh failed for account ${accountId} — falling back to stored snapshot`,
+          error instanceof Error ? error.stack : String(error),
+        );
+
+        if (strictTenants) throw error;
+      }
+    }
+
+    if (Object.keys(overrides).length === 0) {
+      return mapToAuthenticatedAccount(account);
+    }
+
+    // `account` is a Sequelize model instance at runtime whose column values are backed by
+    // `dataValues` getters, NOT own enumerable properties. Spreading `{ ...account }` loses
+    // those getter values (e.g. `id` becomes undefined). Re-serialising through
+    // JSON.parse(JSON.stringify()) forces all getter-backed values into own properties of a
+    // plain object before applying whichever refresh(es) actually changed something.
+    const plain = JSON.parse(JSON.stringify(account)) as IamAccount;
+    return mapToAuthenticatedAccount({ ...plain, ...overrides });
+  }
+
+  /** Best-effort: a cache eviction failure must never fail token issuance. */
+  private async invalidateAuthenticationCache(accountId: string): Promise<void> {
+    try {
+      await this.accountCacheInvalidator.invalidate(accountId);
+    } catch (error) {
+      this.logger.warn(
+        `Failed to invalidate cached account ${accountId} after a dPermissions/dTenants refresh: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
   }
 }
 
-function mapToAuthenticatedAccount(account: IamAccount): AuthenticatedAccount {
+/**
+ * Exported (not adapter-private) so caller-fixture builders in handler specs can derive an
+ * `AuthenticatedAccount` from a fake `IamAccount` instead of fabricating the principal shape on
+ * a cast literal — a field the mapper forgets to carry then fails the test that consumes it,
+ * instead of silently defaulting to `undefined` at runtime.
+ */
+export function mapToAuthenticatedAccount(account: IamAccount): AuthenticatedAccount {
   const permissions = (account.dPermissions ?? {}) as Record<string, string[]>;
   const allPermissions = Array.isArray(permissions.all) ? permissions.all : [];
 
@@ -126,6 +234,7 @@ function mapToAuthenticatedAccount(account: IamAccount): AuthenticatedAccount {
     dApplicationCodes: (account.dApplicationCodes ?? []) as string[],
     dPermissions: { ...permissions, all: allPermissions },
     dTenants: account.dTenants ?? [],
+    hasAddChildTenants: Boolean(account.hasAddChildTenants),
     meta: (account.meta ?? null) as Record<string, unknown> | null,
     roles: (account.roles ?? []).map((role) => ({
       id: role!.id,