@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

package/dist/templates/frontend/application/src/@aurora/modules/graphql/apollo.factory.spec.ts

@@ -1,42 +1,38 @@
 /**
  * Integration spec for the Apollo link chain built by createAuroraGraphqlLinks.
  *
- * Focus: the retry-re-attaches-fresh-Bearer bug.
- *
- * Chain order under test: [errorLink, headersLink, terminatingLink]
- *
- * Scenario
- * --------
- * 1. The access token is EXPIRED (empty string) when the operation starts.
- * 2. The terminating link returns a CombinedGraphQLErrors-compatible 401
- *    (statusCode: 401, message starting "OAuthAccessToken not allowed") on the FIRST call.
- * 3. ErrorLink catches it, calls authHandler.tryRefresh(), which writes a fresh token into
- *    tokenStore and resolves true.
- * 4. ErrorLink calls forward(operation), which re-runs headersLink.  headersLink now reads the
- *    fresh tokenStore.accessToken() and sets Authorization: Bearer <fresh>.
- * 5. The terminating link receives the retried call with Authorization: Bearer <fresh> and
- *    returns a success result.
- * 6. The operation ultimately succeeds and handleUnauthorized was NOT called.
- *
- * RED / GREEN demonstration
- * -------------------------
- * Run the test with the OLD chain order [headersLink, errorLink, terminatingLink] to confirm it
- * FAILS (retried call has no Authorization header), then with the CORRECT order
- * [errorLink, headersLink, terminatingLink] to confirm it PASSES.
- *
- * The production code exported by apollo.factory.ts uses the CORRECT order, so all tests here
- * pass on the imported function.
+ * Since redesign-session-expiry-recovery, the error link no longer classifies or branches itself:
+ * it reports an access-expiry 401 to `SessionRecoveryCoordinatorService` (resolved LAZILY through a
+ * captured `Injector`) and either forwards the operation on 'retry' or lets it terminate on
+ * 'terminate'. `headersLink` stamps `tokenStore.identityGeneration()` (a monotonic counter) instead
+ * of the old boolean `IMPERSONATED_REQUEST_CONTEXT_KEY`.
  */
 
 import '@angular/compiler';
-import { signal } from '@angular/core';
+import { Injector } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { Router } from '@angular/router';
 import { ApolloLink } from '@apollo/client/core';
 import { CombinedGraphQLErrors } from '@apollo/client/errors';
 import { SetContextLink } from '@apollo/client/link/context';
 import { ErrorLink } from '@apollo/client/link/error';
-import { Observable } from 'rxjs';
+import {
+  provideTransloco,
+  TranslocoService,
+  type Translation,
+  type TranslocoLoader,
+} from '@jsverse/transloco';
+import { toast } from '@spartan-ng/brain/sonner';
+import { Apollo } from 'apollo-angular';
+import { forkJoin, lastValueFrom, Observable, of, throwError } from 'rxjs';
+import navigationEn from '../../../../public/i18n/navigation/en.json';
+import navigationEs from '../../../../public/i18n/navigation/es.json';
+import { CurrentAccountService } from '../authentication/shared/current-account.service';
+import { SessionRecoveryCoordinatorService } from '../authentication/shared/session-recovery-coordinator.service';
+import { TokenStore } from '../authentication/shared/token-store.service';
 import { createAuroraGraphqlLinks } from './apollo.factory';
 import type { GraphQLAuthHandler, GraphQLErrorHandler } from './graphql.types';
+import { auroraGraphqlErrorHandlerFactory } from './handlers/aurora-graphql-error.handler';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -56,23 +52,20 @@ const MOCK_APOLLO_CLIENT = {
   },
 } as unknown as import('@apollo/client/core').ApolloClient;
 
-/**
- * Builds a minimal but structurally valid JWT with an `exp` in the future.
- * `isTokenExpired` in the production code parses `atob(token.split('.')[1]).exp`,
- * so we need a real base64-encoded payload with a future `exp`.  The header and
- * signature segments are placeholders — they are never validated in tests.
- */
-function makeFutureJwt(payload: Record<string, unknown> = {}): string {
-  const exp = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
-  const fullPayload = { sub: 'test-user', iat: Math.floor(Date.now() / 1000), exp, ...payload };
-  const encodedPayload = btoa(JSON.stringify(fullPayload));
-  return `eyJhbGciOiJIUzI1NiJ9.${encodedPayload}.fake-signature`;
+/** Structurally valid JWT with a controllable `exp`, for identity-generation-aware tests. */
+function jwt(payload: Record<string, unknown>, expOffsetSeconds: number): string {
+  const exp = Math.floor(Date.now() / 1000) + expOffsetSeconds;
+  return `${btoa(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))}.${btoa(
+    JSON.stringify({ exp, ...payload }),
+  )}.fake-signature`;
 }
 
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
 /**
  * Drives the composed link chain and collects results / errors.
  * Resolves with the emitted result (if any), or resolves with null when the
- * observable completes without emitting (e.g. after handleUnauthorized + EMPTY).
+ * observable completes without emitting (e.g. after a terminated operation).
  */
 function executeLink(
   link: ApolloLink,
@@ -98,39 +91,13 @@ function executeLink(
   });
 }
 
-// ---------------------------------------------------------------------------
-// Shared mock factories
-// ---------------------------------------------------------------------------
-
-interface TokenStoreShape {
-  accessToken: ReturnType<typeof signal<string>>;
-  refreshToken: ReturnType<typeof signal<string>>;
-}
-
-function makeTokenStore(initial: { access: string; refresh: string }): TokenStoreShape {
-  return {
-    accessToken: signal(initial.access),
-    refreshToken: signal(initial.refresh),
-  };
-}
-
-interface MockAuthHandler extends GraphQLAuthHandler {
-  handleUnauthorizedSpy: ReturnType<typeof vi.fn>;
-}
-
-function makeAuthHandler(tokenStore: TokenStoreShape, freshToken: string): MockAuthHandler {
-  const handleUnauthorizedSpy = vi.fn();
+/** A GraphQLAuthHandler stub that never returns a Basic header — every operation falls through to
+ * the Bearer branch of headersLink. */
+function noopAuthHandler(): GraphQLAuthHandler {
   return {
     async getAuthorizationHeader(): Promise<string | null> {
-      // Returns null so headersLink falls back to tokenStore.accessToken().
       return null;
     },
-    async tryRefresh(): Promise<boolean> {
-      tokenStore.accessToken.set(freshToken);
-      return true;
-    },
-    handleUnauthorized: handleUnauthorizedSpy,
-    handleUnauthorizedSpy,
   };
 }
 
@@ -150,6 +117,33 @@ function makeErrorHandler(): MockErrorHandler {
   };
 }
 
+/** Wires a REAL `SessionRecoveryCoordinatorService` around the given (real) `TokenStore`, with a
+ * controllable Apollo `mutate` (the only network call the coordinator itself makes). */
+function wireCoordinatorInjector(options: {
+  store: TokenStore;
+  mutate?: ReturnType<typeof vi.fn>;
+}): {
+  injector: Injector;
+  mutate: ReturnType<typeof vi.fn>;
+  navigate: ReturnType<typeof vi.fn>;
+  load: ReturnType<typeof vi.fn>;
+} {
+  const mutate = options.mutate ?? vi.fn();
+  const navigate = vi.fn().mockResolvedValue(true);
+  const load = vi.fn();
+  const injector = Injector.create({
+    providers: [
+      { provide: TokenStore, useValue: options.store },
+      { provide: Apollo, useValue: { mutate } },
+      { provide: Router, useValue: { navigate } },
+      { provide: TranslocoService, useValue: { translate: (key: string) => key } },
+      { provide: CurrentAccountService, useValue: { load } },
+      SessionRecoveryCoordinatorService,
+    ],
+  });
+  return { injector, mutate, navigate, load };
+}
+
 /** Minimal GQL query document required by ApolloLink */
 const DUMMY_QUERY = {
   kind: 'Document',
@@ -174,6 +168,37 @@ const DUMMY_QUERY = {
 /** Success result returned by the terminating mock link on the second call. */
 const SUCCESS_RESULT = { data: { dummy: 'ok' } };
 
+/** Same shape as DUMMY_QUERY but named as one of BASIC_AUTH_OPERATIONS, so headersLink attaches
+ * client-Basic headers instead of a Bearer token. */
+const BASIC_QUERY = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'mutation',
+      name: { kind: 'Name', value: 'oAuthCreateToken' },
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [{ kind: 'Field', name: { kind: 'Name', value: 'oAuthCreateToken' } }],
+      },
+    },
+  ],
+} as unknown as import('graphql').DocumentNode;
+
+const ACCESS_EXPIRY_RESULT = {
+  errors: [
+    {
+      message: 'Unauthorized',
+      extensions: {
+        originalError: {
+          statusCode: 401,
+          message: 'OAuthAccessToken not allowed for this operation',
+        },
+      },
+    },
+  ],
+} as import('@apollo/client/core').ApolloLink.Result;
+
 /**
  * Builds a terminating ApolloLink that:
  *  - On the FIRST call: emits a GraphQL result with a 401 OAuthAccessToken error.
@@ -192,25 +217,9 @@ function makeTerminatingMockLink(recordedHeaders: Array<string | undefined>): Ap
 
     return new Observable((observer) => {
       if (call === 0) {
-        // First call — emit a result that ErrorLink will interpret as a 401.
-        const rawResult = {
-          errors: [
-            {
-              message: 'Unauthorized',
-              extensions: {
-                originalError: {
-                  statusCode: 401,
-                  message: 'OAuthAccessToken not allowed for this operation',
-                },
-              },
-            },
-          ],
-        };
-
-        observer.next(rawResult as import('@apollo/client/core').ApolloLink.Result);
+        observer.next(ACCESS_EXPIRY_RESULT);
         observer.complete();
       } else {
-        // Subsequent calls — success.
         observer.next(SUCCESS_RESULT);
         observer.complete();
       }
@@ -218,541 +227,1003 @@ function makeTerminatingMockLink(recordedHeaders: Array<string | undefined>): Ap
   });
 }
 
+let toastInfo: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  localStorage.clear();
+  toastInfo = vi.spyOn(toast, 'info').mockImplementation(() => undefined as never);
+});
+
+afterEach(() => {
+  toastInfo.mockRestore();
+  localStorage.clear();
+});
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('createAuroraGraphqlLinks — link chain order', () => {
-  // Must be a structurally valid JWT so isTokenExpired() returns false and headersLink
-  // attaches it as Bearer.  A plain string like 'abc123' would fail the JWT parse and
-  // be treated as expired, so the header would not be attached on the retry.
-  const FRESH_TOKEN = makeFutureJwt();
+describe('createAuroraGraphqlLinks — retry re-attaches fresh Bearer via the coordinator', () => {
+  it('sends Authorization: Bearer <fresh> on the retried operation after a successful refresh grant', async () => {
+    const EXPIRED = jwt({ aci: 'actor-1' }, -60);
+    const ROTATED = jwt({ aci: 'actor-1', jti: 'rotated' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: EXPIRED, refreshToken: 'refresh-token-123' });
+
+    const mutate = vi.fn().mockReturnValue(
+      of({
+        data: { oAuthCreateToken: { accessToken: ROTATED, refreshToken: 'refresh-token-456' } },
+      }),
+    );
+    const { injector } = wireCoordinatorInjector({ store, mutate });
+
+    const recordedHeaders: Array<string | undefined> = [];
+    const terminatingLink = makeTerminatingMockLink(recordedHeaders);
+
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: terminatingLink,
+    });
 
-  let tokenStore: TokenStoreShape;
-  let authHandler: ReturnType<typeof makeAuthHandler>;
-  let errorHandler: ReturnType<typeof makeErrorHandler>;
-  let translocoService: { translate: ReturnType<typeof vi.fn> };
+    const result = await executeLink(link, DUMMY_QUERY);
 
-  beforeEach(() => {
-    // Access token starts EXPIRED/empty so headersLink skips the Bearer header on the first pass.
-    tokenStore = makeTokenStore({ access: '', refresh: 'valid-refresh-token' });
-    authHandler = makeAuthHandler(tokenStore, FRESH_TOKEN);
-    errorHandler = makeErrorHandler();
-    translocoService = { translate: vi.fn().mockReturnValue('translated') };
+    expect(recordedHeaders).toHaveLength(2);
+    expect(recordedHeaders[0]).toBeUndefined();
+    expect(recordedHeaders[1]).toBe(`Bearer ${ROTATED}`);
+    expect(result).toEqual(SUCCESS_RESULT);
+    expect(mutate).toHaveBeenCalledTimes(1);
   });
 
-  describe('retry re-attaches fresh Bearer (the latent bug fix)', () => {
-    it('sends Authorization: Bearer <fresh> on the retried operation', async () => {
-      const recordedHeaders: Array<string | undefined> = [];
-      const terminatingLink = makeTerminatingMockLink(recordedHeaders);
-
-      const link = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: terminatingLink,
-      });
+  it('does NOT terminate the operation when the refresh grant succeeds', async () => {
+    const EXPIRED = jwt({ aci: 'actor-1' }, -60);
+    const ROTATED = jwt({ aci: 'actor-1', jti: 'rotated' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: EXPIRED, refreshToken: 'refresh-token-123' });
+    const mutate = vi
+      .fn()
+      .mockReturnValue(
+        of({ data: { oAuthCreateToken: { accessToken: ROTATED, refreshToken: 'r2' } } }),
+      );
+    const { injector, navigate } = wireCoordinatorInjector({ store, mutate });
+
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: makeTerminatingMockLink([]),
+    });
 
-      const result = await executeLink(link, DUMMY_QUERY);
+    await executeLink(link, DUMMY_QUERY);
 
-      // The terminating link was called TWICE (first 401, then success on retry).
-      expect(recordedHeaders).toHaveLength(2);
+    expect(navigate).not.toHaveBeenCalled();
+  });
+});
+
+describe('old chain order [headersLink, errorLink, http] demonstrates the retry-order bug', () => {
+  /**
+   * This test intentionally builds the WRONG chain order (headersLink before errorLink) to prove
+   * that the retry does NOT re-run headersLink, so the retried call has no Authorization header —
+   * the bug the production chain order fixes. It is self-contained (its own inline retry logic),
+   * independent of `createAuroraGraphqlLinks` and of the coordinator.
+   */
+  it('fails to attach Bearer on retry with old [headersLink, errorLink, http] order', async () => {
+    const recordedHeaders: Array<string | undefined> = [];
+    let callCount = 0;
+    const alwaysUnauthorizedLink = new ApolloLink((operation) => {
+      const headers =
+        (operation.getContext() as { headers?: Record<string, string> }).headers ?? {};
+      recordedHeaders.push(headers['Authorization']);
+      callCount++;
+      return new Observable((observer) => {
+        observer.next(ACCESS_EXPIRY_RESULT);
+        observer.complete();
+      });
+    });
 
-      // First call: token was expired, so no Authorization header.
-      expect(recordedHeaders[0]).toBeUndefined();
+    const tryRefresh = vi.fn().mockResolvedValue(true);
+    const handleUnauthorized = vi.fn();
 
-      // Second call (retry after refresh): should carry the fresh Bearer token.
-      expect(recordedHeaders[1]).toBe(`Bearer ${FRESH_TOKEN}`);
+    const headersLink = new SetContextLink(async (prevContext) => {
+      const headerMap: Record<string, string> = {};
+      const prevHeaders = (prevContext as { headers?: unknown }).headers;
+      if (prevHeaders && typeof prevHeaders === 'object') {
+        Object.assign(headerMap, prevHeaders as Record<string, string>);
+      }
+      return { headers: headerMap };
+    });
 
-      // The operation ultimately succeeded.
-      expect(result).toEqual(SUCCESS_RESULT);
+    const wrongOrderErrorLink = new ErrorLink(({ error, operation, forward }) => {
+      if (CombinedGraphQLErrors.is(error)) {
+        const isAccessExpiry = error.errors.some((e) => {
+          const ext = e.extensions as Record<string, unknown> | undefined;
+          const orig = ext?.['originalError'] as
+            { statusCode: number; message: string } | undefined;
+          return orig?.statusCode === 401 && orig.message.startsWith('OAuthAccessToken');
+        });
 
-      // handleUnauthorized must NOT have been called — the refresh path resolved.
-      expect(authHandler.handleUnauthorizedSpy).not.toHaveBeenCalled();
+        const context = operation.getContext() as Record<string, unknown>;
+        const alreadyRetried = context['__refreshRetried'] === true;
+
+        if (isAccessExpiry && !alreadyRetried) {
+          operation.setContext({ __refreshRetried: true });
+          return new Observable((observer) => {
+            tryRefresh().then((refreshed: boolean) => {
+              if (refreshed) {
+                forward(operation).subscribe(observer);
+              } else {
+                handleUnauthorized();
+                observer.complete();
+              }
+            });
+          });
+        }
+      }
+      handleUnauthorized();
+      return;
     });
 
-    it('does NOT call handleUnauthorized when refresh succeeds', async () => {
-      const terminatingLink = makeTerminatingMockLink([]);
+    const wrongOrderLink = ApolloLink.from([
+      headersLink,
+      wrongOrderErrorLink,
+      alwaysUnauthorizedLink,
+    ]);
 
-      const link = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: terminatingLink,
-      });
+    try {
+      await executeLink(wrongOrderLink, DUMMY_QUERY);
+    } catch {
+      // Ignore errors from the wrong-order chain.
+    }
 
-      await executeLink(link, DUMMY_QUERY);
+    const retryHeaderIsEmpty = recordedHeaders.length >= 2 && recordedHeaders[1] == null;
+    const unauthorizedWasCalled = handleUnauthorized.mock.calls.length > 0;
 
-      expect(authHandler.handleUnauthorizedSpy).not.toHaveBeenCalled();
-    });
+    expect(retryHeaderIsEmpty || unauthorizedWasCalled).toBe(true);
   });
+});
 
-  describe('old chain order [headersLink, errorLink, http] demonstrates the bug', () => {
-    /**
-     * This test intentionally uses the WRONG chain order (headersLink before errorLink)
-     * to prove that the retry does NOT re-run headersLink, so the retried call has no
-     * Authorization header — the bug that this fix resolves.
-     *
-     * With the wrong order the retry gets an empty Authorization header, which causes
-     * another 401, and then the retry-once guard routes to handleUnauthorized.
-     */
-    it('fails to attach Bearer on retry with old [headersLink, errorLink, http] order', async () => {
-      const recordedHeaders: Array<string | undefined> = [];
-
-      // A terminating link that always returns 401 (simulating no token ever attached).
-      // With the wrong order, the retry also has no token and gets another 401.
-      // The retry-once guard then calls handleUnauthorized.
-      let callCount = 0;
-      const alwaysUnauthorizedLink = new ApolloLink((operation) => {
-        const headers =
-          (operation.getContext() as { headers?: Record<string, string> }).headers ?? {};
-        recordedHeaders.push(headers['Authorization']);
-        callCount++;
-
-        return new Observable((observer) => {
-          observer.next({
-            errors: [
-              {
-                message: 'Unauthorized',
-                extensions: {
-                  originalError: {
-                    statusCode: 401,
-                    message: 'OAuthAccessToken not allowed for this operation',
-                  },
+describe('normal (non-retry) error paths are unchanged', () => {
+  function baseDeps(store: TokenStore, httpLink: ApolloLink) {
+    const { injector } = wireCoordinatorInjector({ store });
+    return {
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink,
+    };
+  }
+
+  it('calls handleGraphQLErrors for non-auth GraphQL errors', async () => {
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: jwt({ aci: 'actor-1' }, 3600), refreshToken: 'refresh' });
+    const nonAuthTerminating = new ApolloLink(() => {
+      return new Observable((observer) => {
+        observer.next({
+          errors: [
+            {
+              message: 'Something went wrong',
+              extensions: {
+                originalError: {
+                  statusCode: 500,
+                  message: 'Internal server error',
+                  translation: 'errors.internal',
                 },
               },
-            ],
-          } as import('@apollo/client/core').ApolloLink.Result);
-          observer.complete();
-        });
+            },
+          ],
+        } as import('@apollo/client/core').ApolloLink.Result);
+        observer.complete();
       });
+    });
 
-      // Build the WRONG chain: headersLink is upstream of errorLink, so forward(operation)
-      // in the error handler does NOT re-run headersLink.
-      const headersLink = new SetContextLink(async (prevContext, operation) => {
-        const headerMap: Record<string, string> = {};
-        const prevHeaders = (prevContext as { headers?: unknown }).headers;
-        if (prevHeaders && typeof prevHeaders === 'object') {
-          Object.assign(headerMap, prevHeaders as Record<string, string>);
-        }
-        const handlerHeader = await authHandler.getAuthorizationHeader(
-          operation.operationName ?? null,
-        );
-        if (handlerHeader) {
-          headerMap['Authorization'] = handlerHeader;
-        } else {
-          const token = tokenStore.accessToken();
-          // isTokenExpired equivalent: empty string means expired.
-          if (token && token.length > 0) {
-            headerMap['Authorization'] = `Bearer ${token}`;
-          }
-        }
-        return { headers: headerMap };
-      });
+    const deps = baseDeps(store, nonAuthTerminating);
+    const link = createAuroraGraphqlLinks(deps);
+    await executeLink(link, DUMMY_QUERY);
 
-      const wrongOrderErrorLink = new ErrorLink(({ error, operation, forward }) => {
-        if (CombinedGraphQLErrors.is(error)) {
-          const isAccessExpiry = error.errors.some((e) => {
-            const ext = e.extensions as Record<string, unknown> | undefined;
-            const orig = ext?.['originalError'] as
-              | { statusCode: number; message: string }
-              | undefined;
-            return orig?.statusCode === 401 && orig.message.startsWith('OAuthAccessToken');
-          });
+    expect(deps.errorHandler.handleGraphQLErrorsSpy).toHaveBeenCalledOnce();
+  });
 
-          const context = operation.getContext() as Record<string, unknown>;
-          const alreadyRetried = context['__refreshRetried'] === true;
-
-          if (isAccessExpiry && !alreadyRetried) {
-            operation.setContext({ __refreshRetried: true });
-            return new Observable((observer) => {
-              authHandler.tryRefresh().then((refreshed) => {
-                if (refreshed) {
-                  // With wrong chain order, forward(operation) does NOT re-run headersLink.
-                  forward(operation).subscribe(observer);
-                } else {
-                  authHandler.handleUnauthorized();
-                  observer.complete();
-                }
-              });
-            });
-          }
-        }
-        authHandler.handleUnauthorized();
-        return;
+  // Was: 'terminates and signs out for OAuthRefreshToken 404 errors'. Reversed deliberately — the
+  // shape only ever comes from the o-auth/refresh-token admin CRUD handlers (find / find-by-id /
+  // delete-by-id) reporting a missing row, never from an authentication path. The genuine
+  // refresh-grant failure is a 400 `invalid_grant`, already handled by
+  // SessionRecoveryCoordinatorService. This mirrors the sibling `OAuthAccessToken` admin CRUD 404,
+  // which already falls through to the generic toast path below.
+  it('does NOT sign out for an OAuthRefreshToken 404 — falls through to the generic toast path like its OAuthAccessToken sibling', async () => {
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: jwt({ aci: 'actor-1' }, 3600), refreshToken: 'refresh' });
+    const notFoundTerminating = new ApolloLink(() => {
+      return new Observable((observer) => {
+        observer.next({
+          errors: [
+            {
+              message: 'Not found',
+              extensions: {
+                originalError: {
+                  statusCode: 404,
+                  message: 'OAuthRefreshToken with id: abc, not found',
+                },
+              },
+            },
+          ],
+        } as import('@apollo/client/core').ApolloLink.Result);
+        observer.complete();
       });
+    });
 
-      const wrongOrderLink = ApolloLink.from([
-        headersLink,
-        wrongOrderErrorLink,
-        alwaysUnauthorizedLink,
-      ]);
-
-      // Drive the chain — the retried call (if headers re-ran) would carry the fresh token,
-      // but with the wrong order it will NOT.  We use firstValueFrom and catch to handle the
-      // case where the observable completes without emitting (empty result after handleUnauthorized).
-      try {
-        await executeLink(wrongOrderLink, DUMMY_QUERY);
-      } catch {
-        // Ignore errors from the wrong-order chain.
-      }
+    const { injector, navigate, mutate } = wireCoordinatorInjector({ store });
+    const errorHandler = makeErrorHandler();
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler,
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: notFoundTerminating,
+    });
 
-      // With wrong chain order the retry is attempted (callCount >= 2) but the
-      // retried call still has no Authorization header (undefined), proving the bug.
-      // OR handleUnauthorized is called on the fallthrough path.
-      const retryHeaderIsEmpty = recordedHeaders.length >= 2 && recordedHeaders[1] == null;
-      const unauthorizedWasCalled = authHandler.handleUnauthorizedSpy.mock.calls.length > 0;
+    const result = await executeLink(link, DUMMY_QUERY);
 
-      // At least one of these must be true to confirm the bug manifests.
-      expect(retryHeaderIsEmpty || unauthorizedWasCalled).toBe(true);
-    });
+    expect(navigate).not.toHaveBeenCalledWith(['/auth/sign-in']);
+    expect(mutate).not.toHaveBeenCalled();
+    expect(store.authenticated()).toBe(true);
+    // "surfaced to the caller through the generic path": handleGraphQLErrors fires the toast AND
+    // the original result (still carrying the error) is emitted downstream, not swallowed.
+    expect(errorHandler.handleGraphQLErrorsSpy).toHaveBeenCalledOnce();
+    expect(result).not.toBeNull();
   });
 
-  describe('normal (non-retry) error paths are unchanged', () => {
-    it('calls handleGraphQLErrors for non-auth GraphQL errors', async () => {
-      const nonAuthTerminating = new ApolloLink((_operation) => {
-        return new Observable((observer) => {
-          observer.next({
-            errors: [
-              {
-                message: 'Something went wrong',
-                extensions: {
-                  originalError: {
-                    statusCode: 500,
-                    message: 'Internal server error',
-                    translation: 'errors.internal',
-                  },
-                },
-              },
-            ],
-          } as import('@apollo/client/core').ApolloLink.Result);
-          observer.complete();
-        });
+  it('suppresses toast when error code is in skipGlobalErrors', async () => {
+    const store = new TokenStore();
+    const invalidGrantTerminating = new ApolloLink(() => {
+      return new Observable((observer) => {
+        observer.next({
+          errors: [
+            {
+              message: 'Bad Request',
+              extensions: { originalError: { statusCode: 400, error: 'invalid_grant' } },
+            },
+          ],
+        } as import('@apollo/client/core').ApolloLink.Result);
+        observer.complete();
       });
+    });
+
+    const deps = baseDeps(store, invalidGrantTerminating);
+    const linkWithSkip = createAuroraGraphqlLinks(deps);
 
-      const link = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: nonAuthTerminating,
+    await new Promise<void>((resolve, reject) => {
+      ApolloLink.execute(
+        linkWithSkip,
+        { query: DUMMY_QUERY, variables: {}, context: { skipGlobalErrors: ['invalid_grant'] } },
+        { client: MOCK_APOLLO_CLIENT },
+      ).subscribe({ next: () => {}, error: reject, complete: resolve });
+    });
+
+    expect(deps.errorHandler.handleGraphQLErrorsSpy).not.toHaveBeenCalled();
+  });
+
+  it('still fires toast when error code is not in skipGlobalErrors', async () => {
+    const store = new TokenStore();
+    const invalidGrantTerminating = new ApolloLink(() => {
+      return new Observable((observer) => {
+        observer.next({
+          errors: [
+            {
+              message: 'Bad Request',
+              extensions: { originalError: { statusCode: 400, error: 'invalid_grant' } },
+            },
+          ],
+        } as import('@apollo/client/core').ApolloLink.Result);
+        observer.complete();
       });
+    });
 
-      await executeLink(link, DUMMY_QUERY);
+    const deps = baseDeps(store, invalidGrantTerminating);
+    const linkWithoutSkip = createAuroraGraphqlLinks(deps);
 
-      expect(errorHandler.handleGraphQLErrorsSpy).toHaveBeenCalledOnce();
+    await new Promise<void>((resolve, reject) => {
+      ApolloLink.execute(
+        linkWithoutSkip,
+        { query: DUMMY_QUERY, variables: {}, context: {} },
+        { client: MOCK_APOLLO_CLIENT },
+      ).subscribe({ next: () => {}, error: reject, complete: resolve });
     });
 
-    it('calls handleUnauthorized for OAuthRefreshToken 404 errors', async () => {
-      const refreshInvalidTerminating = new ApolloLink((_operation) => {
-        return new Observable((observer) => {
-          observer.next({
-            errors: [
-              {
-                message: 'Not found',
-                extensions: {
-                  originalError: {
-                    statusCode: 404,
-                    message: 'OAuthRefreshToken not found',
-                  },
-                },
-              },
-            ],
-          } as import('@apollo/client/core').ApolloLink.Result);
-          observer.complete();
-        });
-      });
+    expect(deps.errorHandler.handleGraphQLErrorsSpy).toHaveBeenCalledOnce();
+  });
 
-      const link = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: refreshInvalidTerminating,
+  it('calls handleNetworkError for network-level errors', async () => {
+    const store = new TokenStore();
+    const networkErrorTerminating = new ApolloLink(() => {
+      return new Observable((observer) => {
+        observer.error(new Error('Network failure'));
       });
+    });
+
+    const deps = baseDeps(store, networkErrorTerminating);
+    const link = createAuroraGraphqlLinks(deps);
 
+    try {
       await executeLink(link, DUMMY_QUERY);
+    } catch {
+      // network errors bubble up — that is expected.
+    }
 
-      expect(authHandler.handleUnauthorizedSpy).toHaveBeenCalledOnce();
-    });
+    expect(deps.errorHandler.handleNetworkErrorSpy).toHaveBeenCalledOnce();
+  });
 
-    it('suppresses toast when error code is in skipGlobalErrors', async () => {
-      // Operation context carries skipGlobalErrors: ['invalid_grant'].
-      // The terminating link emits a 400 error whose originalError.error === 'invalid_grant'
-      // (post-#1 backend shape: statusCode + error at the top level of the body, no nested message).
-      // Expected: handleGraphQLErrors is NOT called because the error is suppressed for inline display.
-      const invalidGrantTerminating = new ApolloLink((_operation) => {
-        return new Observable((observer) => {
-          observer.next({
-            errors: [
-              {
-                message: 'Bad Request',
-                extensions: {
-                  originalError: {
-                    statusCode: 400,
-                    error: 'invalid_grant',
-                  },
-                },
-              },
-            ],
-          } as import('@apollo/client/core').ApolloLink.Result);
-          observer.complete();
-        });
+  it('attaches Bearer header on the first call when getAuthorizationHeader supplies it', async () => {
+    const validToken = 'valid-not-expired-token';
+    const recordedHeaders: Array<string | undefined> = [];
+    const successTerminating = new ApolloLink((operation) => {
+      const headers =
+        (operation.getContext() as { headers?: Record<string, string> }).headers ?? {};
+      recordedHeaders.push(headers['Authorization']);
+      return new Observable((observer) => {
+        observer.next(SUCCESS_RESULT);
+        observer.complete();
       });
+    });
 
-      const linkWithSkip = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: invalidGrantTerminating,
-      });
+    const store = new TokenStore();
+    const { injector } = wireCoordinatorInjector({ store });
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: {
+        async getAuthorizationHeader(): Promise<string | null> {
+          return `Bearer ${validToken}`;
+        },
+      },
+      tokenStore: store,
+      injector,
+      httpLink: successTerminating,
+    });
+
+    await executeLink(link, DUMMY_QUERY);
 
-      await new Promise<void>((resolve, reject) => {
-        ApolloLink.execute(
-          linkWithSkip,
-          { query: DUMMY_QUERY, variables: {}, context: { skipGlobalErrors: ['invalid_grant'] } },
-          { client: MOCK_APOLLO_CLIENT },
-        ).subscribe({ next: () => {}, error: reject, complete: resolve });
+    expect(recordedHeaders[0]).toBe(`Bearer ${validToken}`);
+  });
+});
+
+describe('retry-once guard (D5)', () => {
+  it('retries at most once: a retried op that 401s again does not trigger a second refresh grant', async () => {
+    let callCount = 0;
+    const alwaysUnauthorizedLink = new ApolloLink(() => {
+      callCount++;
+      return new Observable((observer) => {
+        observer.next(ACCESS_EXPIRY_RESULT);
+        observer.complete();
       });
+    });
 
-      expect(errorHandler.handleGraphQLErrorsSpy).not.toHaveBeenCalled();
+    const EXPIRED = jwt({ aci: 'actor-1' }, -60);
+    const ROTATED = jwt({ aci: 'actor-1', jti: 'rotated' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: EXPIRED, refreshToken: 'refresh' });
+    const mutate = vi
+      .fn()
+      .mockReturnValue(
+        of({ data: { oAuthCreateToken: { accessToken: ROTATED, refreshToken: 'r2' } } }),
+      );
+    const { injector, navigate } = wireCoordinatorInjector({ store, mutate });
+
+    const result = await executeLink(
+      createAuroraGraphqlLinks({
+        translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+        errorHandler: makeErrorHandler(),
+        authHandler: noopAuthHandler(),
+        tokenStore: store,
+        injector,
+        httpLink: alwaysUnauthorizedLink,
+      }),
+      DUMMY_QUERY,
+    );
+
+    // The terminating link was hit TWICE: initial call + one retry (no more).
+    expect(callCount).toBe(2);
+    // The refresh grant fired exactly once — the second 401 (from the retried op) flows straight
+    // out of forward()'s Observable to the subscriber, bypassing errorLink entirely (Apollo v4
+    // forward() semantics), so it never re-enters the coordinator.
+    expect(mutate).toHaveBeenCalledTimes(1);
+    expect(navigate).not.toHaveBeenCalledWith(['/auth/sign-in']);
+    expect(result).toMatchObject({
+      errors: [expect.objectContaining({ message: 'Unauthorized' })],
     });
+  });
 
-    it('still fires toast when error code is not in skipGlobalErrors', async () => {
-      // Same error shape as above, but no skipGlobalErrors context — the toast MUST fire.
-      const invalidGrantTerminating = new ApolloLink((_operation) => {
-        return new Observable((observer) => {
-          observer.next({
-            errors: [
-              {
-                message: 'Bad Request',
-                extensions: {
-                  originalError: {
-                    statusCode: 400,
-                    error: 'invalid_grant',
-                  },
-                },
-              },
-            ],
-          } as import('@apollo/client/core').ApolloLink.Result);
+  /**
+   * The ONLY test that exercises the `alreadyRetried` branch, and therefore the only thing
+   * standing between it and a future "unreachable code" cleanup. Read the guard's comment in
+   * `apollo.factory.ts` before touching this test.
+   *
+   * It deliberately does NOT go through the retry path: measurement showed the error link runs
+   * exactly once there, so the guard is unreachable that way. It reaches the guard the way
+   * production would if the transport ever emitted more than one errored payload for a single
+   * operation (`@defer` / `@stream` / multipart, subscriptions) — `ErrorLink` invokes its callback
+   * once PER emission, and the second run sees `__refreshRetried` already set by the first.
+   *
+   * Delete the `alreadyRetried` condition and this test goes red: the second payload would start a
+   * SECOND refresh grant (`recoverForOperation` twice) instead of terminating.
+   */
+  it('terminates instead of refreshing again when a second errored payload arrives for the same operation', async () => {
+    const twiceUnauthorizedLink = new ApolloLink(
+      () =>
+        new Observable((observer) => {
+          observer.next(ACCESS_EXPIRY_RESULT);
+          observer.next(ACCESS_EXPIRY_RESULT);
           observer.complete();
-        });
-      });
+        }),
+    );
+
+    const EXPIRED = jwt({ aci: 'actor-1' }, -60);
+    const ROTATED = jwt({ aci: 'actor-1', jti: 'rotated' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: EXPIRED, refreshToken: 'refresh' });
+    const stampedGeneration = store.identityGeneration();
+
+    const mutate = vi
+      .fn()
+      .mockReturnValue(
+        of({ data: { oAuthCreateToken: { accessToken: ROTATED, refreshToken: 'r2' } } }),
+      );
+    const { injector } = wireCoordinatorInjector({ store, mutate });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+    const recoverForOperation = vi.spyOn(coordinator, 'recoverForOperation');
+    const terminate = vi.spyOn(coordinator, 'terminate');
+
+    await executeLink(
+      createAuroraGraphqlLinks({
+        translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+        errorHandler: makeErrorHandler(),
+        authHandler: noopAuthHandler(),
+        tokenStore: store,
+        injector,
+        httpLink: twiceUnauthorizedLink,
+      }),
+      DUMMY_QUERY,
+    );
+    await flush();
+
+    // First payload took the recovery path; the second one hit the guard and terminated instead
+    // of asking for a second recovery.
+    expect(recoverForOperation).toHaveBeenCalledTimes(1);
+    expect(terminate).toHaveBeenCalledTimes(1);
+    // Terminated with the identity the operation was SENT under, never unconditionally — so a
+    // late failure from a dead identity cannot sign out a different, still-valid session.
+    expect(terminate).toHaveBeenCalledWith(stampedGeneration);
+  });
 
-      const linkWithoutSkip = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: invalidGrantTerminating,
-      });
+  it('signs out and redirects to sign-in when the refresh grant fails', async () => {
+    const EXPIRED = jwt({ aci: 'actor-1' }, -60);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: EXPIRED, refreshToken: 'refresh' });
+    const mutate = vi.fn().mockReturnValue(throwError(() => new Error('invalid_grant')));
+    const { injector, navigate } = wireCoordinatorInjector({ store, mutate });
+
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: makeTerminatingMockLink([]),
+    });
 
-      await new Promise<void>((resolve, reject) => {
-        ApolloLink.execute(
-          linkWithoutSkip,
-          { query: DUMMY_QUERY, variables: {}, context: {} },
-          { client: MOCK_APOLLO_CLIENT },
-        ).subscribe({ next: () => {}, error: reject, complete: resolve });
-      });
+    await executeLink(link, DUMMY_QUERY);
 
-      expect(errorHandler.handleGraphQLErrorsSpy).toHaveBeenCalledOnce();
+    expect(navigate).toHaveBeenCalledWith(['/auth/sign-in']);
+    expect(store.authenticated()).toBe(false);
+  });
+});
+
+describe('impersonation-issued operation is terminated (never retried) and rolls back the session', () => {
+  it('unwinds the impersonation and terminates the operation without retrying, on access expiry', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, 3600);
+    const IMPERSONATION_EXPIRED = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, -60);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+    store.beginImpersonation({ accessToken: IMPERSONATION_EXPIRED });
+
+    const { injector, navigate, load, mutate } = wireCoordinatorInjector({ store });
+    // Would succeed on a retry (so a bug that retries anyway is observable), but the operation
+    // must never reach it a second time.
+    const terminatingLink = makeTerminatingMockLink([]);
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: terminatingLink,
     });
 
-    it('calls handleNetworkError for network-level errors', async () => {
-      const networkErrorTerminating = new ApolloLink((_operation) => {
-        return new Observable((observer) => {
-          observer.error(new Error('Network failure'));
-        });
-      });
+    const result = await executeLink(link, DUMMY_QUERY);
 
-      const link = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: networkErrorTerminating,
+    expect(result).toBeNull(); // terminated, never retried
+    expect(mutate).not.toHaveBeenCalled(); // no refresh grant for a non-renewable credential
+    expect(store.isImpersonating()).toBe(false);
+    expect(store.accessToken()).toBe(OPERATOR_ACCESS);
+    expect(load).toHaveBeenCalled();
+    expect(navigate).not.toHaveBeenCalledWith(['/auth/sign-in']); // unwind, not sign-out
+    expect(toastInfo).toHaveBeenCalledOnce();
+  });
+});
+
+describe('task 3.1 — the re-send window', () => {
+  it('does not re-send an operation when an impersonation becomes active while its refresh grant is in flight', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, -60);
+    const OPERATOR_ROTATED = jwt({ aci: 'actor-1', jti: 'rotated' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+
+    let releaseGate: (() => void) | undefined;
+    const mutate = vi.fn().mockImplementation(
+      () =>
+        new Observable((observer) => {
+          releaseGate = () => {
+            observer.next({
+              data: { oAuthCreateToken: { accessToken: OPERATOR_ROTATED, refreshToken: 'r2' } },
+            });
+            observer.complete();
+          };
+        }),
+    );
+    const { injector } = wireCoordinatorInjector({ store, mutate });
+
+    const recordedHeaders: Array<string | undefined> = [];
+    const httpLink = new ApolloLink((operation) => {
+      const headers =
+        (operation.getContext() as { headers?: Record<string, string> }).headers ?? {};
+      recordedHeaders.push(headers['Authorization']);
+      return new Observable((observer) => {
+        observer.next(ACCESS_EXPIRY_RESULT);
+        observer.complete();
       });
+    });
 
-      try {
-        await executeLink(link, DUMMY_QUERY);
-      } catch {
-        // network errors bubble up — that is expected.
-      }
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink,
+    });
+
+    const resultPromise = executeLink(link, DUMMY_QUERY);
+    await flush();
+    expect(mutate).toHaveBeenCalledTimes(1);
+
+    // An impersonation becomes active WHILE the refresh grant is still in flight.
+    const IMPERSONATION_ACCESS = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600);
+    store.beginImpersonation({ accessToken: IMPERSONATION_ACCESS });
+
+    releaseGate?.();
+    const result = await resultPromise;
+
+    // Not re-sent: only the ORIGINAL call ever reached the terminating link.
+    expect(recordedHeaders).toHaveLength(1);
+    expect(result).toBeNull(); // terminated
+    // The (valid, brand-new) impersonation that started mid-flight is untouched — the stale
+    // refresh result must not clobber it, and the operation must not be sent under it either.
+    expect(store.isImpersonating()).toBe(true);
+    expect(store.accessToken()).toBe(IMPERSONATION_ACCESS);
+    expect(toastInfo).toHaveBeenCalledOnce();
+  });
+});
+
+describe('task 3.2 — a late failure does not unwind a different (later) impersonation', () => {
+  it('leaves a second, still-valid impersonation of the same target untouched when a stale operation from the first fails late', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+
+    const FIRST_IMPERSONATION = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600);
+    store.beginImpersonation({ accessToken: FIRST_IMPERSONATION });
+    const firstGeneration = store.identityGeneration();
+
+    // The first impersonation ends, and a SECOND impersonation of the SAME target begins.
+    store.endImpersonation();
+    const SECOND_IMPERSONATION = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600);
+    store.beginImpersonation({ accessToken: SECOND_IMPERSONATION });
+
+    const { injector, navigate, load } = wireCoordinatorInjector({ store });
+    const coordinator = injector.get(SessionRecoveryCoordinatorService);
+
+    // A late failure arrives for an operation that was SENT (and stamped) back when the FIRST
+    // impersonation was active.
+    const outcome = await new Promise<string>((resolve) =>
+      coordinator.recoverForOperation(firstGeneration).subscribe(resolve),
+    );
+
+    expect(outcome).toBe('terminate');
+    expect(store.isImpersonating()).toBe(true);
+    expect(store.accessToken()).toBe(SECOND_IMPERSONATION); // untouched
+    expect(load).not.toHaveBeenCalled();
+    expect(navigate).not.toHaveBeenCalledWith(['/auth/sign-in']);
+  });
+});
+
+describe('task 4.1 — a terminated operation still informs the operator', () => {
+  it('shows a notice instead of silently discarding an operation whose identity changed mid-flight', async () => {
+    const store = new TokenStore();
+    store.setCredentials({
+      accessToken: jwt({ aci: 'actor-1' }, -60),
+      refreshToken: 'operator-refresh',
+    });
 
-      expect(errorHandler.handleNetworkErrorSpy).toHaveBeenCalledOnce();
-    });
-
-    it('attaches Bearer header on the first call when the token is valid', async () => {
-      const validToken = 'valid-not-expired-token';
-      // Simulate a non-expired token — isTokenExpired returns false for non-empty strings
-      // that are not actually expired JWTs. We use a plausible-looking non-expired token
-      // by making tokenStore return it (the real isTokenExpired checks the JWT exp claim;
-      // we use a mock that only sets the signal so the check uses the real isTokenExpired).
-      // Since we cannot easily produce a real JWT here, we instead verify that when
-      // headersLink runs AFTER errorLink in the chain, the header IS set on the first call
-      // when the token is present by verifying the normal success path (no errors).
-      const recordedHeaders: Array<string | undefined> = [];
-      const successTerminating = new ApolloLink((operation) => {
-        const headers =
-          (operation.getContext() as { headers?: Record<string, string> }).headers ?? {};
-        recordedHeaders.push(headers['Authorization']);
-        return new Observable((observer) => {
-          observer.next(SUCCESS_RESULT);
+    let observerRef:
+      | { next: (v: import('@apollo/client/core').ApolloLink.Result) => void; complete: () => void }
+      | undefined;
+    const gatedHttpLink = new ApolloLink(
+      () =>
+        new Observable<import('@apollo/client/core').ApolloLink.Result>((observer) => {
+          observerRef = observer;
+        }),
+    );
+
+    const { injector } = wireCoordinatorInjector({ store });
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: gatedHttpLink,
+    });
+
+    const resultPromise = executeLink(link, DUMMY_QUERY);
+    await flush();
+
+    // Identity changes WHILE this operation is in flight, before its (stale) 401 arrives.
+    store.beginImpersonation({
+      accessToken: jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600),
+    });
+
+    observerRef?.next(ACCESS_EXPIRY_RESULT);
+    observerRef?.complete();
+    const result = await resultPromise;
+
+    expect(result).toBeNull(); // terminated, not silently retried under the wrong identity
+    // The regression this task reproduces: an earlier round's mirror guard returned before the
+    // toast path, and watchQuery's errorPolicy:'ignore' would then discard the error entirely —
+    // the operator would see an empty list with no indication anything failed.
+    expect(toastInfo).toHaveBeenCalledOnce();
+  });
+});
+
+describe('task 4.2 — one notice for N concurrent terminal failures; none for a successful refresh', () => {
+  it('produces exactly one notice when three concurrent operations fail against the same unusable (no-refresh-token) credential', async () => {
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: jwt({ aci: 'actor-1' }, -60) }); // no refresh token at all
+
+    const { injector, mutate } = wireCoordinatorInjector({ store });
+    const httpLink = new ApolloLink(
+      () =>
+        new Observable((observer) => {
+          observer.next(ACCESS_EXPIRY_RESULT);
           observer.complete();
-        });
-      });
+        }),
+    );
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink,
+    });
 
-      // Use a token store that has a non-expired token.
-      // isTokenExpired only passes for non-empty strings that are valid JWTs with
-      // a future exp. Since we cannot easily craft one here, we test the branch
-      // that headersLink DOES run in position (downstream of errorLink) by checking
-      // that the X-Timezone header is present (which headersLink always sets).
-      const linkWithTimezone = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler: {
-          ...authHandler,
-          async getAuthorizationHeader(): Promise<string | null> {
-            return `Bearer ${validToken}`;
-          },
-        },
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: successTerminating,
-      });
+    await Promise.all([
+      executeLink(link, DUMMY_QUERY),
+      executeLink(link, DUMMY_QUERY),
+      executeLink(link, DUMMY_QUERY),
+    ]);
 
-      await executeLink(linkWithTimezone, DUMMY_QUERY);
+    expect(mutate).not.toHaveBeenCalled();
+    expect(toastInfo).toHaveBeenCalledTimes(1);
+    expect(store.authenticated()).toBe(false);
+  });
 
-      // headersLink ran (proved by Authorization header being set via getAuthorizationHeader).
-      expect(recordedHeaders[0]).toBe(`Bearer ${validToken}`);
+  it('shows no notice when the transparent refresh succeeds', async () => {
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: jwt({ aci: 'actor-1' }, -60), refreshToken: 'refresh' });
+    const ROTATED = jwt({ aci: 'actor-1', jti: 'rotated' }, 3600);
+    const mutate = vi
+      .fn()
+      .mockReturnValue(
+        of({ data: { oAuthCreateToken: { accessToken: ROTATED, refreshToken: 'r2' } } }),
+      );
+    const { injector } = wireCoordinatorInjector({ store, mutate });
+
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: makeTerminatingMockLink([]),
     });
+
+    const result = await executeLink(link, DUMMY_QUERY);
+
+    expect(result).toEqual(SUCCESS_RESULT);
+    expect(toastInfo).not.toHaveBeenCalled();
   });
+});
+
+// ── Refused impersonation reaches the operator as translated copy ────────────
+//
+// A refusal (backend veto) travels as a GraphQL error → error link →
+// extractGraphqlErrorTranslations(translator) → GRAPHQL_ERROR_HANDLER → toast. Unrelated to the
+// access-expiry recovery path — untouched by the redesign.
+describe('refused impersonation → translated toast (navigation scope)', () => {
+  class ShippedCatalogLoader implements TranslocoLoader {
+    getTranslation(path: string): Observable<Translation> {
+      const catalogs: Record<string, Translation> = {
+        en: {},
+        es: {},
+        'navigation/en': navigationEn as unknown as Translation,
+        'navigation/es': navigationEs as unknown as Translation,
+      };
+      return of(catalogs[path] ?? {});
+    }
+  }
+
+  async function bootstrapTranslocoLikeTheApp(lang: 'en' | 'es'): Promise<TranslocoService> {
+    TestBed.configureTestingModule({
+      providers: [
+        provideTransloco({
+          config: {
+            availableLangs: ['en', 'es'],
+            defaultLang: lang,
+            fallbackLang: lang,
+            reRenderOnLangChange: true,
+            prodMode: false,
+            scopes: { keepCasing: true },
+          },
+          loader: ShippedCatalogLoader,
+        }),
+      ],
+    });
+
+    const transloco = TestBed.inject(TranslocoService);
+    await lastValueFrom(forkJoin([transloco.load(lang), transloco.load(`navigation/${lang}`)]));
+    return transloco;
+  }
 
-  describe('retry-once guard (D5)', () => {
-    it('retries at most once: a retried op that 401s again does not trigger a second refresh', async () => {
-      // Terminating link that returns a 401 on EVERY call — both the initial request and the
-      // retry triggered by the refresh.  This directly exercises the __refreshRetried guard.
-      //
-      // How Apollo v4 ErrorLink works:
-      // - The initial 401 fires the errorHandler, which returns a retry Observable (forward(op)).
-      // - ErrorLink subscribes to that retry Observable and pipes its results to the outer observer.
-      // - The retry Observable (forward(op)) re-runs [headersLink, httpLink] — NOT errorLink again.
-      // - When the retried op yields another 401, that result flows straight to the outer observer
-      //   as a raw GraphQL result, bypassing errorLink entirely.
-      //
-      // The __refreshRetried guard therefore prevents a SECOND independent operation from re-entering
-      // the refresh path (e.g. if a component dispatches another query after the retried op fails),
-      // not the current forward() result.  Apollo v4 DOES preserve operation.setContext(...)
-      // across forward(), which we verify by confirming tryRefresh fires only once (not twice).
-      let callCount = 0;
-      const alwaysUnauthorizedLink = new ApolloLink((_operation) => {
-        callCount++;
-        return new Observable((observer) => {
+  function refusalLink(translation: string, message: string): ApolloLink {
+    return new ApolloLink(
+      () =>
+        new Observable((observer) => {
           observer.next({
             errors: [
               {
-                message: 'Unauthorized',
-                extensions: {
-                  originalError: {
-                    statusCode: 401,
-                    message: 'OAuthAccessToken not allowed for this operation',
-                  },
-                },
+                message: 'Forbidden',
+                extensions: { originalError: { statusCode: 403, message, translation } },
               },
             ],
           } as import('@apollo/client/core').ApolloLink.Result);
           observer.complete();
-        });
-      });
+        }),
+    );
+  }
 
-      const tryRefreshSpy = vi.fn().mockResolvedValue(true);
-      const handleUnauthorizedSpy = vi.fn();
+  const REFUSAL_KEYS = Object.keys(navigationEn.Impersonation.Errors);
 
-      const guardAuthHandler: MockAuthHandler = {
-        async getAuthorizationHeader(): Promise<string | null> {
-          return null;
-        },
-        tryRefresh: tryRefreshSpy,
-        handleUnauthorized: handleUnauthorizedSpy,
-        handleUnauthorizedSpy,
-      };
+  let toastError: ReturnType<typeof vi.spyOn>;
 
-      const result = await executeLink(
-        createAuroraGraphqlLinks({
-          translocoService:
-            translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-          errorHandler,
-          authHandler: guardAuthHandler,
-          tokenStore:
-            tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-          httpLink: alwaysUnauthorizedLink,
+  beforeEach(() => {
+    TestBed.resetTestingModule();
+    toastError = vi.spyOn(toast, 'error').mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => {
+    toastError.mockRestore();
+  });
+
+  it('shows the TRANSLATED refusal — not the raw key, not "undefined" — for a payload the backend veto produces', async () => {
+    const transloco = await bootstrapTranslocoLikeTheApp('en');
+    const errorHandler = TestBed.runInInjectionContext(() => auroraGraphqlErrorHandlerFactory());
+    const store = new TokenStore();
+    const { injector } = wireCoordinatorInjector({ store });
+
+    const link = createAuroraGraphqlLinks({
+      translocoService: transloco,
+      errorHandler,
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: refusalLink(
+        'navigation.Impersonation.Errors.TargetPrivileged',
+        'The target account is privileged',
+      ),
+    });
+
+    await executeLink(link, DUMMY_QUERY);
+
+    const shown = toastError.mock.calls[0]?.[0];
+    expect(shown).toBe(navigationEn.Impersonation.Errors.TargetPrivileged);
+    expect(shown).not.toBe('navigation.Impersonation.Errors.TargetPrivileged');
+    expect(String(shown)).not.toContain('undefined');
+    expect(shown).not.toBe('The target account is privileged');
+  });
+
+  it.each(['en', 'es'] as const)(
+    'resolves every impersonation refusal key in %s through the eagerly loaded navigation scope',
+    async (lang) => {
+      const transloco = await bootstrapTranslocoLikeTheApp(lang);
+
+      expect(REFUSAL_KEYS.length).toBeGreaterThan(0);
+      for (const key of REFUSAL_KEYS) {
+        const fullKey = `navigation.Impersonation.Errors.${key}`;
+        const translated = transloco.translate(fullKey);
+
+        expect(translated).not.toBe(fullKey);
+        expect(typeof translated).toBe('string');
+        expect((translated as string).length).toBeGreaterThan(0);
+      }
+    },
+  );
+
+  it('depends on the eager scope load: the same key does NOT resolve before it', async () => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideTransloco({
+          config: {
+            availableLangs: ['en', 'es'],
+            defaultLang: 'en',
+            fallbackLang: 'en',
+            prodMode: false,
+            scopes: { keepCasing: true },
+          },
+          loader: ShippedCatalogLoader,
         }),
-        DUMMY_QUERY,
-      );
+      ],
+    });
+    const transloco = TestBed.inject(TranslocoService);
+    await lastValueFrom(transloco.load('en'));
 
-      // The terminating link was hit TWICE: initial call + one retry (no more).
-      expect(callCount).toBe(2);
+    const fullKey = 'navigation.Impersonation.Errors.TargetPrivileged';
+    expect(transloco.translate(fullKey)).toBe(fullKey);
 
-      // tryRefresh fires exactly once — Apollo v4 preserves __refreshRetried across forward(),
-      // so the second 401 on the retried op does NOT trigger another refresh cycle.
-      expect(tryRefreshSpy).toHaveBeenCalledExactlyOnceWith();
+    await lastValueFrom(transloco.load('navigation/en'));
+    expect(transloco.translate(fullKey)).toBe(navigationEn.Impersonation.Errors.TargetPrivileged);
+  });
+});
 
-      // handleUnauthorized is NOT called: the second 401 flows out of the retry Observable
-      // directly to the outer observer, bypassing errorLink.  The raw 401 result is the
-      // final observable emission.
-      expect(handleUnauthorizedSpy).not.toHaveBeenCalled();
+describe('finding 2: terminate() must not destroy a session a stale operation was never issued under', () => {
+  // Removed: 'leaves the operator session untouched when the identity changed before a late 404
+  // (isRefreshInvalid) arrives'. Its subject, the `isRefreshInvalid` branch, no longer exists — a
+  // 404 `OAuthRefreshToken` now falls through to the generic toast path, which never calls
+  // `coordinator.terminate()` and therefore never touches `TokenStore` at all. The hazard this test
+  // guarded against (a late failure from a stale identity generation destroying a DIFFERENT,
+  // currently valid session) cannot occur any more for this shape, by construction — there is
+  // nothing left to re-point the scenario at. The equivalent generation-aware protection for the
+  // access-expiry path (the branch that DOES still call `terminate()`) remains covered by "task
+  // 3.2" and "task 4.1" below, and by the sibling test right after this comment for the
+  // unconditional Basic-call-site case.
+  it('still terminates the Basic call site (oAuthCreateToken/oAuthRevokeToken) UNCONDITIONALLY, with no generation check, after an identity change', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, 3600);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+
+    let observerRef:
+      | { next: (v: import('@apollo/client/core').ApolloLink.Result) => void; complete: () => void }
+      | undefined;
+    const gatedHttpLink = new ApolloLink(
+      () =>
+        new Observable<import('@apollo/client/core').ApolloLink.Result>((observer) => {
+          observerRef = observer;
+        }),
+    );
+
+    const { injector, navigate } = wireCoordinatorInjector({ store });
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink: gatedHttpLink,
+    });
 
-      // The final result carries the 401 errors (the retried op's response).
-      expect(result).toMatchObject({
-        errors: [expect.objectContaining({ message: 'Unauthorized' })],
-      });
+    const resultPromise = executeLink(link, BASIC_QUERY);
+    await flush();
+
+    // Identity changes WHILE this client-Basic operation is in flight — a check here (mistakenly
+    // added by a future edit) would wrongly SKIP a sign-out that is genuinely needed.
+    store.beginImpersonation({
+      accessToken: jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, 3600),
     });
 
-    it('calls handleUnauthorized when refresh fails', async () => {
-      const terminatingLink = makeTerminatingMockLink([]);
-      const handleUnauthorized = vi.fn();
-      const failingAuthHandler: MockAuthHandler = {
-        async getAuthorizationHeader(): Promise<string | null> {
-          return null;
-        },
-        async tryRefresh(): Promise<boolean> {
-          return false; // refresh fails
-        },
-        handleUnauthorized,
-        handleUnauthorizedSpy: handleUnauthorized,
-      };
+    observerRef?.next(ACCESS_EXPIRY_RESULT);
+    observerRef?.complete();
+    const result = await resultPromise;
 
-      const link = createAuroraGraphqlLinks({
-        translocoService:
-          translocoService as unknown as import('@jsverse/transloco').TranslocoService,
-        errorHandler,
-        authHandler: failingAuthHandler,
-        tokenStore:
-          tokenStore as unknown as import('../authentication/shared/token-store.service').TokenStore,
-        httpLink: terminatingLink,
-      });
+    expect(result).toBeNull();
+    expect(navigate).toHaveBeenCalledWith(['/auth/sign-in']);
+    expect(store.authenticated()).toBe(false);
+  });
+});
 
-      await executeLink(link, DUMMY_QUERY);
+describe('task 5 — concurrent expiries against the same impersonation credential roll back once', () => {
+  /**
+   * Spec scenarios "Concurrent expiries roll back once" and "A failed operation is never re-sent
+   * under a different identity". Applies the same shape as "task 4.2 — one notice for N concurrent
+   * terminal failures" above, but to the UNWIND path instead of the no-refresh-token terminal path.
+   *
+   * Fixture: a real TokenStore, an operator credential WITH a refresh token, then a REAL
+   * `beginImpersonation` with an EXPIRED impersonation credential carrying NO refresh token
+   * (production never issues one for it — design D4). N operations are driven through the REAL
+   * link chain, all failing with the access-expiry 401, all stamped with the same generation
+   * (they are dispatched before the single-flight unwind has a chance to run — it is deferred onto
+   * a microtask specifically so the latch is installed before any of its body runs).
+   */
+  it('N operations failing with access expiry produce exactly one rollback, exactly one notice, no refresh grant, and are never re-sent', async () => {
+    const OPERATOR_ACCESS = jwt({ aci: 'actor-1' }, 3600);
+    const IMPERSONATION_EXPIRED = jwt({ aci: 'target-1', act: { aci: 'actor-1' } }, -60);
+    const store = new TokenStore();
+    store.setCredentials({ accessToken: OPERATOR_ACCESS, refreshToken: 'operator-refresh' });
+    store.beginImpersonation({ accessToken: IMPERSONATION_EXPIRED }); // no refreshToken
+
+    const { injector, navigate, load, mutate } = wireCoordinatorInjector({ store });
+    const endImpersonationSpy = vi.spyOn(store, 'endImpersonation');
+
+    const N = 3;
+    const recordedHeaders: Array<string | undefined> = [];
+    let transportCallCount = 0;
+    const httpLink = new ApolloLink((operation) => {
+      const headers =
+        (operation.getContext() as { headers?: Record<string, string> }).headers ?? {};
+      recordedHeaders.push(headers['Authorization']);
+      transportCallCount++;
+      return new Observable((observer) => {
+        observer.next(ACCESS_EXPIRY_RESULT);
+        observer.complete();
+      });
+    });
 
-      expect(handleUnauthorized).toHaveBeenCalledOnce();
+    const link = createAuroraGraphqlLinks({
+      translocoService: { translate: (key: string) => key } as unknown as TranslocoService,
+      errorHandler: makeErrorHandler(),
+      authHandler: noopAuthHandler(),
+      tokenStore: store,
+      injector,
+      httpLink,
     });
+
+    const results = await Promise.all(
+      Array.from({ length: N }, () => executeLink(link, DUMMY_QUERY)),
+    );
+
+    // Blocker 3: none of the N operations was re-sent — exactly N calls reached the transport, and
+    // every one of them terminated (null), never a retried success.
+    expect(transportCallCount).toBe(N);
+    expect(results).toEqual(Array.from({ length: N }, () => null));
+    // No request carried the operator's own Bearer token for an operation issued inside the
+    // target's session (the impersonation token is expired, so headersLink attaches no header at
+    // all — but the operator's credential specifically must never appear here).
+    expect(recordedHeaders).not.toContain(`Bearer ${OPERATOR_ACCESS}`);
+
+    // Blocker 2: exactly ONE rollback effect...
+    expect(endImpersonationSpy).toHaveBeenCalledTimes(1);
+    expect(store.isImpersonating()).toBe(false);
+    expect(store.accessToken()).toBe(OPERATOR_ACCESS);
+    expect(load).toHaveBeenCalledTimes(1); // exactly one CurrentAccountService.load()
+    // ...and exactly ONE expiry notice.
+    expect(toastInfo).toHaveBeenCalledTimes(1);
+    expect(toastInfo).toHaveBeenCalledWith('navigation.Impersonation.ExpiredNotice');
+    // No refresh grant at all — a grant against a credential with no refresh token would be a bug.
+    expect(mutate).not.toHaveBeenCalled();
   });
 });