@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/backend/application/.claude/skills/catalyst-backend-testing/SKILL.md

@@ -13,84 +13,71 @@ description: >
   understanding why `expect(result.password).toBeDefined()` fails on a read handler. Fires even when
   the user says only "write a test for this handler". Does NOT apply to testing upstream
   `@aurorajs.dev/core-back` decorators themselves (upstream concern) or to testing
-  `catalyst-cli`-generated scaffolds (generator concern). At the time of authoring, catalyst has
-  ZERO production tests for its modules — this skill establishes the first conventions via
-  synthesized templates anchored on real handler shapes.
+  `catalyst-cli`-generated scaffolds (generator concern).
 license: MIT
 metadata:
   author: aurora
-  version: '1.0'
+  version: '2.0'
 ---
 
-## ⚠ Starting Point — Read This First
+## Runner
 
-**Catalyst has no production test code for its modules today.** An inventory at authoring time
-(2026-04-23) found exactly two `.spec.ts` files in the backend, and both are NestJS CLI starters not
-specific to catalyst:
+Vitest — `pnpm --filter aurora-back test` (`backend/vitest.config.ts`). Mock with `vi.mock` /
+`vi.fn` / `vi.spyOn`; read the real module behind a mock with `vi.importActual` /
+`vi.importMock`, both **async** (`await vi.importActual(...)`). `isolate: true` and
+`restoreMocks: true` are set project-wide:
+mocks reset automatically between tests, and a `vi.mock` in one file never leaks into another —
+but that also means **never declare two `vi.mock` calls for the same specifier in one file**; the
+second silently wins and the ordering is not obvious from the file.
 
-- `backend/src/app.controller.spec.ts` — asserts `"Hello World!"`.
-- `backend/test/app.e2e-spec.ts` — same starter shape.
+The `TZ=Europe/Madrid` pin lives in `backend/test/vitest-setup.ts` (a `setupFiles` entry,
+evaluated before any test file's top-level code runs), never inside a test body — a
+`process.env.TZ = ...` assignment inside an `it()` never reaches V8's date cache in time and is
+silently inert.
 
-The CLI has a `--tests` flag on `catalyst load back module`, but the flag is a silent no-op today:
-`generateTestingFiles()` in `aurora-catalyst-cli/src/generator/handlers/back.handler.ts` checks for
-a templates directory that does not exist and returns without emitting anything.
+Every code example below is a real, passing suite in this repository, cited by path — copy its
+shape rather than the archetype's name.
 
-**This skill therefore establishes — not documents — catalyst's first testing conventions.** Every
-code example below is **synthesized** against real handler shapes (`IamCreateTagHandler`,
-`IamFindTagByIdHandler`, the same anchors `catalyst-handler-composer` uses). Every synthesized
-snippet opens with `// SYNTHESIZED — reconcile when the first real test lands` to remind the reader
-that it is a starting shape, not a canonical pattern extracted from production code. When real tests
-land, this skill's examples should be reconciled against them.
-
-The single catalyst-specific insight that justifies shipping this skill now — before real tests
-exist — is the **decorator-fires-in-TestingModule gotcha** documented below. Nothing else in the
-ecosystem teaches it.
-
-## Step 0 — Testing Conventions Gate
-
-Unlike the CLI-first gate in `catalyst-handler-composer` / `catalyst-field-schema` or the
-reuse-first gate in `catalyst-nestjs-primitives`, this gate is an **establishing** gate: testing
-conventions for catalyst are being set here, not described from prior practice. Most tasks today
-fall in branch 3 or 4.
+## Step 0 — Which archetype am I writing?
 
 ```
 About to write a test?
   │
-  ├── Does a similar `*.spec.ts` already exist on disk?  ───→ COPY its shape
-  │   (Today: only AppController + app.e2e-spec starters
-  │    exist. This branch activates once real tests land.)
-  │
-  ├── Does the CLI `--tests` flag scaffold one?          ───→ Use the scaffold
-  │   (Today: the flag is a no-op. This branch activates
-  │    when test templates land in the CLI.)
+  ├── Does a similar `*.spec.ts` already exist next to a sibling handler/service/guard?
+  │     → COPY its shape. This is the common case today (244 spec files under backend/src).
   │
-  ├── Is this a pattern covered by this skill's         ───→ Follow the template
-  │   templates below?                                       (write handler / read handler /
-  │                                                           guard / e2e / seed pattern)
+  ├── Is this a pattern covered by one of this skill's anchors below?
+  │     → Follow that anchor (write handler / read handler / guard / e2e / seed pattern).
   │
-  └── None of the above?                                 ───→ STOP and coordinate.
-       (You're establishing a new convention.              You are in "establishing a
-        Reach out before committing.)                        new convention" territory.
+  └── Neither?
+        → STOP and coordinate — you are about to establish a new convention, not follow one.
 ```
 
 ## Decorators Fire in TestingModule (Catalyst-specific)
 
-This is the single most important section of this skill. It is the insight that makes the skill
-worth shipping before real tests exist.
+This is the single most important section of this skill.
 
 `@ApplySchema`, `@Format`, `@Sanitize`, and `@EmitEvent` from `@aurorajs.dev/core-back` are
-`MethodDecorator`s that wrap `descriptor.value`. Verified in
+`MethodDecorator`s that wrap `descriptor.value`. The shipped source is
+`packages/core-back/src/modules/type-handlers/decorators/apply-schema.decorator.ts`, published as
 `@aurorajs.dev/core-back/dist/modules/type-handlers/decorators/apply-schema.decorator.js`:
 
 ```typescript
-function ApplySchema(schemaOrOptions) {
-  const { schema, payloadIndex } = Array.isArray(schemaOrOptions)
-    ? { schema: schemaOrOptions, payloadIndex: 0 }
-    : { schema: schemaOrOptions.schema, payloadIndex: schemaOrOptions.payloadIndex ?? 0 };
-  return applyDecorators(Format(schema), Sanitize({ schema, payloadIndex }));
+export function ApplySchema(options: ApplySchemaOptions): MethodDecorator {
+  const { schema, payloadIndex = 0, operation } = options;
+
+  return applyDecorators(Format(schema), Sanitize({ schema, payloadIndex, operation }));
 }
 ```
 
+`ApplySchemaOptions` takes only this object shape, and `operation: 'create' | 'update'` is a
+REQUIRED property — a spec file that hand-decorates a fake handler has to declare it too, or it
+does not compile. `payloadIndex` stays optional and defaults to `0`.
+
+The wrapping itself happens one level down, in `@Sanitize` (and symmetrically in `@Format`): it
+replaces `descriptor.value` with a function that sanitizes `args[payloadIndex]` and then calls the
+original method through `originalMethod.apply(this, args)`.
+
 `applyDecorators` composes `@Format` + `@Sanitize`. Both wrap the method descriptor — they run on
 **every** `handler.main(...)` invocation, including inside `TestingModule`. This has three concrete
 consequences for tests:
@@ -110,281 +97,324 @@ consequences for tests:
    normalized). A test asserting `expect(result.password).toBeDefined()` on a read-handler return
    will **fail** — the format decorator already masked it.
 
-Every template below accounts for these behaviors. If you stray from the templates, re-read this
-section before writing the assertions.
+Every anchor below accounts for these behaviors. If you stray from them, re-read this section
+before writing the assertions.
 
-## Unit Test — Write Handler (anchored on `IamCreateTagHandler`)
+## Unit Test — Write Handler
+
+Real: `backend/src/@app/reporting/report-category/application/create/reporting-create-report-category.handler.spec.ts`.
 
 ```typescript
-// SYNTHESIZED — no real test exists for IamCreateTagHandler today.
-// Reconcile when the first real handler test lands in catalyst.
-import { NotFoundException } from '@nestjs/common';
+import { BadRequestException } from '@nestjs/common';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { Test } from '@nestjs/testing';
 
-import { IamCreateTagHandler, IamCreateTagService, IamFindTagByIdService } from '@app/iam/tag';
+import {
+  ReportingCreateReportCategoryService,
+  ReportingFindReportCategoryByIdService,
+} from '@app/reporting/report-category/index.js';
+
+import { ReportingCreateReportCategoryHandler } from './reporting-create-report-category.handler.js';
+
+describe('ReportingCreateReportCategoryHandler — color validation (BR-REPORT-CATEGORY-001)', () => {
+  let handler: ReportingCreateReportCategoryHandler;
 
-describe('IamCreateTagHandler', () => {
-  let handler: IamCreateTagHandler;
-  const createService = { main: jest.fn() };
-  const findByIdService = { main: jest.fn() };
-  const eventEmitter = { emit: jest.fn() }; // MANDATORY — @EmitEvent reads this.eventEmitter
+  const createService = { main: vi.fn() };
+  const findByIdService = { main: vi.fn() };
+  const eventEmitter = { emit: vi.fn() }; // MANDATORY — @EmitEvent reads this.eventEmitter
+
+  const handlerMeta = { timezone: 'UTC', repositoryOptions: { auditing: null } };
 
   beforeEach(async () => {
-    jest.clearAllMocks();
+    vi.clearAllMocks();
+
     const moduleRef = await Test.createTestingModule({
       providers: [
-        IamCreateTagHandler,
+        ReportingCreateReportCategoryHandler,
         { provide: EventEmitter2, useValue: eventEmitter },
-        { provide: IamCreateTagService, useValue: createService },
-        { provide: IamFindTagByIdService, useValue: findByIdService },
+        { provide: ReportingCreateReportCategoryService, useValue: createService },
+        { provide: ReportingFindReportCategoryByIdService, useValue: findByIdService },
       ],
     }).compile();
 
-    handler = moduleRef.get(IamCreateTagHandler);
+    handler = moduleRef.get(ReportingCreateReportCategoryHandler);
   });
 
-  it('persists, emits iam.tag.created, and returns the hydrated entity', async () => {
-    const payload = { id: 'uuid-1', name: 'feature' };
-    const handlerMeta = {
-      timezone: 'UTC',
-      repositoryOptions: { auditing: null },
-    };
-    const hydrated = {
-      id: 'uuid-1',
-      name: 'feature',
-      createdAt: '2026-04-23T00:00:00.000Z',
-      updatedAt: null,
-      deletedAt: null,
-    };
-    findByIdService.main.mockResolvedValue(hydrated);
-
-    const result = await handler.main(payload, handlerMeta);
+  it('accepts a valid hex color and delegates to createService', async () => {
+    const id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
+    const payload = { id, name: 'Finance', color: '#f97316' };
+    findByIdService.main.mockResolvedValue(payload);
+
+    const result = await handler.main(payload, handlerMeta as any);
 
     expect(createService.main).toHaveBeenCalledWith(payload, handlerMeta);
-    expect(findByIdService.main).toHaveBeenCalledWith('uuid-1', {}, handlerMeta);
-    expect(eventEmitter.emit).toHaveBeenCalledWith('iam.tag.created', expect.anything());
-    expect(result).toEqual(hydrated);
+    expect(result).toEqual(payload);
   });
 });
 ```
 
-**Note — password caveat.** `IamTag` has no `type: 'password'` field, so the assertion
-`expect(createService.main).toHaveBeenCalledWith(payload, handlerMeta)` works as written. If you
-port this template to a handler whose `FieldSchema` declares `type: 'password'` (for example an
-`IamCreateUserHandler`), `@Sanitize` runs `bcrypt.hashSync` on the payload before the service call.
-The service mock will receive a hash, not the plaintext — adjust the assertion to one of:
+**Note — password caveat.** If you port this shape to a handler whose `FieldSchema` declares
+`type: 'password'` (an `IamCreateUserHandler`, for instance), `@Sanitize` runs `bcrypt.hashSync`
+on the payload before the service call. The service mock will receive a hash, not the plaintext —
+assert the shape instead of the exact value:
 
 ```typescript
-// Option A — assert the shape + hash presence, not exact value:
 expect(createService.main).toHaveBeenCalledWith(
   expect.objectContaining({ id: payload.id, password: expect.any(String) }),
   handlerMeta,
 );
-
-// Option B — stub bcrypt.hashSync to return a deterministic value:
-jest.spyOn(bcrypt, 'hashSync').mockReturnValue('$2b$10$fixed-hash');
 ```
 
-## Unit Test — Read Handler (anchored on `IamFindTagByIdHandler`)
+## Unit Test — Read Handler
+
+Real: `backend/src/@app/hub/app/application/find/hub-find-app-by-id.handler.spec.ts`.
 
 ```typescript
-// SYNTHESIZED — no real test exists for IamFindTagByIdHandler today.
-// Reconcile when the first real read-handler test lands.
+import { HubFindAppByIdService } from '@app/hub/app/application/find/hub-find-app-by-id.service.js';
 import { NotFoundException } from '@nestjs/common';
-import { Test } from '@nestjs/testing';
+import { Test, TestingModule } from '@nestjs/testing';
+import { HubFindAppByIdHandler } from './hub-find-app-by-id.handler.js';
 
-import { IamFindTagByIdHandler, IamFindTagByIdService } from '@app/iam/tag';
+const handlerMeta = { timezone: 'UTC', repositoryOptions: { auditing: null } };
 
-describe('IamFindTagByIdHandler', () => {
-  let handler: IamFindTagByIdHandler;
-  const findByIdService = { main: jest.fn() };
+describe('HubFindAppByIdHandler', () => {
+  let handler: HubFindAppByIdHandler;
+  const findByIdService = { main: vi.fn() };
 
   beforeEach(async () => {
-    jest.clearAllMocks();
-    const moduleRef = await Test.createTestingModule({
+    vi.clearAllMocks();
+    findByIdService.main.mockResolvedValue({ id: '1', code: 'myapp' });
+
+    const moduleRef: TestingModule = await Test.createTestingModule({
       providers: [
-        IamFindTagByIdHandler,
-        { provide: IamFindTagByIdService, useValue: findByIdService },
+        HubFindAppByIdHandler,
+        { provide: HubFindAppByIdService, useValue: findByIdService },
       ],
     }).compile();
 
-    handler = moduleRef.get(IamFindTagByIdHandler);
+    handler = moduleRef.get(HubFindAppByIdHandler);
   });
 
-  it('returns the tag when found', async () => {
-    const tag = { id: 'uuid-1', name: 'feature' };
-    findByIdService.main.mockResolvedValue(tag);
-
-    const result = await handler.main('uuid-1', undefined, undefined);
-
-    expect(result).toMatchObject({ id: 'uuid-1', name: 'feature' });
+  it('returns the found app', async () => {
+    const result = await handler.main('1', undefined, handlerMeta);
+    expect(result).toEqual({ id: '1', code: 'myapp' });
   });
 
-  it('throws NotFoundException when the tag is missing', async () => {
+  it('throws NotFoundException when no app is found', async () => {
     findByIdService.main.mockResolvedValue(null);
-
-    await expect(handler.main('missing', undefined, undefined)).rejects.toThrow(NotFoundException);
+    await expect(handler.main('missing', undefined, handlerMeta)).rejects.toThrow(
+      NotFoundException,
+    );
   });
 });
 ```
 
-**Note — format caveat.** If the read handler's `FieldSchema` masks a field (e.g., a User entity's
-`password`), the returned entity has `password === undefined`. A test asserting
-`expect(result.password).toBeDefined()` would fail. Assert only on fields the schema exposes.
+**Note — format caveat.** If the read handler's `FieldSchema` masks a field (e.g. a User entity's
+`password`), the returned entity has `password === undefined`. Assert only on fields the schema
+exposes; use `catalyst-field-schema`'s field catalog to know what is masked.
 
-## Unit Test — Guard (dual-context)
+## Mocking a module barrel — `vi.mock` with `importOriginal` / `importActual`
 
-Catalyst guards override `getRequest(context)` via `Api.getRequestFromExecutionContext(context)` so
-they work on both REST (HTTP) and GraphQL contexts. See `catalyst-nestjs-primitives` for the full
-pattern. Tests must fake both context types to exercise the override.
+Vitest's ESM-backed mocking is strict: accessing an export the factory did not return THROWS ("No X
+export is defined on the mock") instead of silently yielding `undefined`. When the code under test
+reads more than one export from a mocked module (a decorator plus a helper, for instance), spread
+the real module and override only the target.
+
+Real: `backend/src/@app/hub/app/application/get/hub-get-apps.handler.spec.ts`.
 
 ```typescript
-// SYNTHESIZED — pattern anchored on AuthorizationPermissionsGuard.
-// Reconcile when the first real guard test lands.
-import { ExecutionContext } from '@nestjs/common';
-
-const fakeHttpContext = {
-  getType: () => 'http',
-  switchToHttp: () => ({
-    getRequest: () => ({
-      user: { dPermissions: { all: ['iam.tag.create'] } },
-    }),
-  }),
-  getClass: () => ({ name: 'IamCreateTagResolver' }),
-} as unknown as ExecutionContext;
-
-// For the GraphQL branch, replace getType with () => 'graphql'
-// and stub GqlExecutionContext.create(context).getContext().req similarly.
+vi.mock('@app/hub/app/domain/index.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@app/hub/app/domain/index.js')>();
+  return {
+    ...actual,
+    hubAppAccessPermissionName: (code: string) => `hub.app.${code}.access`,
+  };
+});
+vi.mock('@aurorajs.dev/core-back', async () => {
+  const actual =
+    await vi.importActual<typeof import('@aurorajs.dev/core-back')>('@aurorajs.dev/core-back');
+  return {
+    Format: () => (_t: unknown, _k: unknown, d: unknown) => d,
+    HandlerMeta: class {},
+    QueryStatement: class QueryStatement {},
+    DEFAULT_MAX_DEPTH: actual.DEFAULT_MAX_DEPTH,
+    LOGICAL_OPERATOR: actual.LOGICAL_OPERATOR,
+  };
+});
 ```
 
-`Api.getRequestFromExecutionContext()` inspects `context.getType()`; your fake must return `'http'`
-or `'graphql'` to drive the branch you intend to test. A thorough guard test exercises both branches
-to confirm the override works for both API styles.
+`importOriginal` (passed to the factory) and `vi.importActual` (called standalone, given the
+specifier) do the same job — use whichever is already in scope.
 
-## E2E Tests — supertest (REST + GraphQL)
+## Mocking a Node built-in — `vi.hoisted`
 
-Both snippets assume an already-bootstrapped `INestApplication` set up in `beforeAll`. The
-authenticated account MUST hold the permission the endpoint's `@Auth(...)` decorator requires; see
-the seeds section below for how to prepare it.
+`vi.mock` factories run before the file's own imports, so a factory that closes over a variable
+declared in the same file throws a hoisting error. `vi.hoisted` lifts the variables it returns to
+the very top, before `vi.mock` itself runs.
 
-**REST variant:**
+Real: `backend/src/@app/tools/procedure/shared/services/tools-load-procedures.service.spec.ts`.
 
 ```typescript
-// SYNTHESIZED — pattern for a REST endpoint protected by @Auth('iam.tag.create').
-import * as request from 'supertest';
-
-it('POST /iam/tag — creates a tag when the account has iam.tag.create', async () => {
-  await request(app.getHttpServer())
-    .post('/iam/tag')
-    .set('Authorization', `Bearer ${authenticatedToken}`)
-    .send({ id: 'uuid-1', name: 'feature' })
-    .expect(201);
+// `vi.mock('node:fs', ...)`, not `vi.spyOn`: the production service imports `* as fs from
+// 'node:fs'`, and Vitest's ESM namespace object for that import is frozen — spying on it throws
+// "Module namespace is not configurable in ESM" (measured). `vi.mock` intercepts the specifier
+// itself, so every importer of `node:fs` in this file's module graph resolves to the mocked
+// module.
+const { mockReaddir, mockReadFile, mockExists } = vi.hoisted(() => ({
+  mockReaddir: vi.fn(),
+  mockReadFile: vi.fn(),
+  mockExists: vi.fn(),
+}));
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return {
+    ...actual,
+    readdirSync: mockReaddir,
+    readFileSync: mockReadFile,
+    existsSync: mockExists,
+  };
 });
 ```
 
-**GraphQL variant:**
+## Unit Test — Guard (dual-context)
+
+Catalyst guards override `getRequest(context)` via `Api.getRequestFromExecutionContext(context)` so
+they work on both REST (HTTP) and GraphQL contexts. See `catalyst-nestjs-primitives` for the full
+pattern. A test fakes both context shapes to exercise the override.
+
+Real: `backend/src/@aurora/modules/authentication/infrastructure/guards/authentication-jwt.guard.spec.ts`.
 
 ```typescript
-// SYNTHESIZED — pattern for the same operation exposed via GraphQL mutation.
-it('POST /graphql — mutates iamCreateTag when the account has iam.tag.create', async () => {
-  await request(app.getHttpServer())
-    .post('/graphql')
-    .set('Authorization', `Bearer ${authenticatedToken}`)
-    .send({
-      query: `mutation ($payload: IamCreateTagInput!) {
-        iamCreateTag(payload: $payload) { id name }
-      }`,
-      variables: { payload: { id: 'uuid-1', name: 'feature' } },
-    })
-    .expect(200)
-    .expect((res) => expect(res.body.data.iamCreateTag.id).toBe('uuid-1'));
-});
+function makeHttpContext(userContainer: { user?: unknown }): ExecutionContext {
+  return {
+    getType: () => 'http',
+    switchToHttp: () => ({ getRequest: () => userContainer }),
+    getClass: () => ({ name: 'TestController' }),
+    getHandler: () => ({ name: 'testHandler' }),
+    getArgs: () => [],
+    getArgByIndex: () => undefined,
+    switchToRpc: () => ({}),
+    switchToWs: () => ({}),
+  } as unknown as ExecutionContext;
+}
+
+function makeGraphqlContext(userContainer: { user?: unknown }): ExecutionContext {
+  return {
+    getType: () => 'graphql',
+    switchToHttp: () => ({ getRequest: () => ({}) }),
+    getClass: () => ({ name: 'TestResolver' }),
+    getHandler: () => ({ name: 'testQuery' }),
+    getArgs: () => [null, null, { req: userContainer }, null],
+    getArgByIndex: (index: number) => [null, null, { req: userContainer }, null][index],
+    switchToRpc: () => ({}),
+    switchToWs: () => ({}),
+  } as unknown as ExecutionContext;
+}
 ```
 
-Both variants rely on the same authenticated account + seeded permissions. The only real difference
-is the request shape.
+`Api.getRequestFromExecutionContext()` inspects `context.getType()`; the fake must return `'http'`
+or `'graphql'` to drive the branch under test. A thorough guard test exercises both branches. Spy
+on the guard's own superclass method with
+`vi.spyOn(Object.getPrototypeOf(Object.getPrototypeOf(guard)), 'canActivate')` when the guard
+delegates to Passport's base implementation — that pattern is in the same file.
 
-## Seeds as Testing Utilities
+## E2E Tests — supertest (REST + GraphQL)
 
-The ONLY concrete testing utility catalyst has today are the seed files:
+Both variants assume an already-bootstrapped `INestApplication` set up in `beforeAll`. The
+authenticated account MUST hold the permission the endpoint's `@Auth(...)` decorator requires.
 
-- `backend/src/@app/iam/iam.seed.ts` — exports `boundedContexts[]`, `permissions[]`, `roles[]`.
-- `backend/src/@app/library/library.seed.ts` — same pattern for the library bounded context.
-- `backend/src/@app/o-auth/o-auth.seed.ts` — same pattern for o-auth.
+Real: `backend/test/acceptance/o-auth/token-masking.e2e-spec.ts` seeds an account with
+`d_permissions` via a raw insert and signs a token for it directly through the real port:
 
-For any e2e test of an `@Auth('<permission>')`-protected endpoint, the authenticated account MUST
-hold that permission in its `dPermissions.all`. The `AuthorizationPermissionsGuard` reads
-`user.dPermissions.all` and compares via `Arr.intersects` — no permission match means the guard
-throws `UnauthorizedException` with `statusCode: 403`. See `catalyst-nestjs-primitives` for the
-convention.
+```typescript
+const insertAccount = async (id: string, permissions: string[]) => {
+  const dPermissions = JSON.stringify({ all: permissions });
+  await db.execute(sql`
+    INSERT INTO iam_account (id, type, email, username, is_active, client_id, d_application_codes, d_permissions, d_tenants, created_at)
+    VALUES (${id}, 'USER', ${`e2e-${id}@test.local`}, ${`e2e-${id}`},
+      true, ${BOOTSTRAP_OAUTH_CLIENT_ID}, ARRAY[]::varchar[], ${dPermissions}::jsonb,
+      ARRAY[]::uuid[], NOW())
+  `);
+};
+
+readerToken = (await jwtSigner.signAccess({ aci: READER_ID })).token;
+
+const res = await request(app.getHttpServer())
+  .post('/graphql')
+  .set('Authorization', `Bearer ${readerToken}`)
+  .set('Content-Type', 'application/json')
+  .send({ query: QUERY, variables: { query: { where: { id: { eq: ACCESS_TOKEN_ID } } } } })
+  .expect(200);
+```
 
-**Synthesized e2e setup snippet:**
+The REST shape is the same request builder against a REST path instead of `/graphql`:
 
 ```typescript
-// SYNTHESIZED — pattern for seeding permissions + an authenticated account.
-import { permissions as iamPermissions } from '@app/iam/iam.seed';
-
-beforeAll(async () => {
-  // Load permissions from the seed into the test database.
-  await permissionRepository.bulkInsert(iamPermissions);
-
-  // Create an account whose dPermissions.all includes the target permission(s).
-  const account = await accountRepository.create({
-    id: 'test-account-uuid',
-    username: 'tester',
-    dPermissions: { all: ['iam.tag.create', 'iam.tag.get'] },
-    // … other required fields per IamAccountFieldSchema
-  });
-
-  // Issue a JWT for that account and store it for requests.
-  authenticatedToken = jwtService.sign({ sub: account.id });
-});
+await request(app.getHttpServer())
+  .post('/iam/tag')
+  .set('Authorization', `Bearer ${authenticatedToken}`)
+  .send({ id: 'uuid-1', name: 'feature' })
+  .expect(201);
 ```
 
-The `dPermissions.all` array is the critical field. Hardcoding a subset in the test fixture drifts
-from the real seed as permissions evolve — prefer importing the seed's `permissions` array and
-pulling the ids you need, rather than hand-writing strings.
+## Seeds as Testing Utilities
+
+Two patterns coexist, both real:
+
+- **Import the seed's permission ids** — `backend/src/@app/iam/iam.seed.ts` (and the equivalent
+  `library.seed.ts` / `o-auth.seed.ts`) export `boundedContexts[]`, `permissions[]`, `roles[]`.
+  Preferred when the test wires a real repository/service and needs the exact permission id
+  strings, so it drifts with the seed instead of hardcoding a copy.
+- **Raw SQL insert with a literal `d_permissions` jsonb**, as in the token-masking e2e above.
+  Preferred for a standalone e2e that seeds its own fixture rows directly against the database.
+
+For any e2e test of an `@Auth('<permission>')`-protected endpoint, the authenticated account MUST
+hold that permission in its `dPermissions.all`. `AuthorizationPermissionsGuard` reads
+`user.dPermissions.all` and compares via `Arr.intersects` — no match throws `UnauthorizedException`
+(`statusCode: 403`). See `catalyst-nestjs-primitives` for the convention.
 
 ## Anti-patterns
 
-1. **`handler.execute(...)`.** → Catalyst handlers have `main()`, not `execute()`. Aurora-old CQRS
-   `ICommandHandler.execute(command)` is obsolete in catalyst. Call
-   `handler.main(payload, handlerMeta)` directly.
+1. **`handler.execute(...)`.** → Catalyst handlers have `main()`, not `execute()`.
 
 2. **Testing `@ApplySchema` / `@Format` / `@Sanitize` / `@EmitEvent` decorator internals.** → Those
    live in `@aurorajs.dev/core-back` and are maintained upstream. Your catalyst test consumes their
-   behavior; it does not test them. If you think you need to test the decorator itself, the bug
-   belongs upstream.
+   behavior; it does not test them.
 
 3. **Writing a handler test without `EventEmitter2` in `providers`.** → Every write handler with
    `@EmitEvent` fails silently or errors because `this.eventEmitter.emit(...)` has no target. Always
-   add `{ provide: EventEmitter2, useValue: { emit: jest.fn() } }` to the providers list.
+   add `{ provide: EventEmitter2, useValue: { emit: vi.fn() } }` to the providers list.
 
-4. **Asserting against plaintext passwords after `@ApplySchema`.** → `@Sanitize` bcrypt- hashed the
-   payload before `main()` ran. Either stub `bcrypt.hashSync` or assert on the hashed form (use
-   `expect.any(String)` or a deterministic stub value).
+4. **Asserting against plaintext passwords after `@ApplySchema`.** → `@Sanitize` bcrypt-hashed the
+   payload before `main()` ran. Assert on the shape (`expect.any(String)`), not the literal value.
 
 5. **Asserting `result.password` on a read handler.** → `@Format` returned `undefined` for fields
-   the schema masks. Assert only on fields the schema exposes; use `catalyst-field-schema`'s field
-   catalog to know what's masked.
+   the schema masks. Assert only on fields the schema exposes.
 
 6. **Hardcoding `dPermissions.all` in test fixtures instead of using the seeds.** → The real seed
-   evolves; hardcoded fixtures drift. Import the seed's `permissions` array and compute
-   `dPermissions.all` from it, so adding a new permission to `iam.seed.ts` automatically updates
-   every test that reads it.
+   evolves; hardcoded fixtures drift. Import the seed's `permissions` array (or the raw-SQL
+   fixture pattern above) instead of retyping permission strings.
+
+7. **Two `vi.mock()` calls for the same specifier in one file.** → Order-dependent and confusing;
+   the second silently wins. Merge them into one factory.
+
+8. **`vi.spyOn` on a namespace import (`import * as fs from 'node:fs'`).** → Vitest's ESM
+   namespace object is frozen; spying throws "Module namespace is not configurable in ESM". Use
+   `vi.mock` on the specifier instead (see the `vi.hoisted` anchor above).
 
 ## Cross-references
 
-- **`catalyst-handler-composer`** — handler shape under test. The templates here anchor on
-  `IamCreateTagHandler` and `IamFindTagByIdHandler`, the same examples composer uses. When writing a
-  test for a different handler archetype, read composer's archetype reference first.
-- **`catalyst-field-schema`** — what the decorators do. Understanding why a password is hashed or
-  why a field is masked on return requires the decorator + type-handler catalog from field-schema's
-  reference.
-- **`catalyst-nestjs-primitives`** — the dual-context pattern. Testing a catalyst guard means faking
-  an `ExecutionContext` for both REST and GraphQL; the primitive itself is documented in
-  nestjs-primitives, and this skill's guard section points back to it.
-- **`catalyst-project-structure`** — where test files live on disk (co-located `.spec.ts` next to
-  the handler they test, or under `test/` for e2e). The structure skill is the source of truth; this
-  skill assumes it.
+- **`catalyst-handler-composer`** — handler shape under test.
+- **`catalyst-field-schema`** — what the decorators do; the field catalog for masked/sanitized
+  properties.
+- **`catalyst-nestjs-primitives`** — the dual-context pattern the guard anchor exercises.
+- **`catalyst-project-structure`** — where test files live on disk: co-located `.spec.ts` next to
+  the handler they test; BC e2e/acceptance specs under `backend/test/acceptance/<bc>/` (one folder
+  per bounded context), while the `app.e2e-spec.ts` scaffold smoke stays at `test/` root. Also the
+  source of truth for the explicit-specifier import convention every spec's own imports follow.
+- **`scripts/contracts/README.md`** (not a skill — a monorepo-level suite) — when the assertion is
+  that a BACKEND artefact agrees with a FRONTEND one, a spec here cannot make it honestly: it would
+  compare the backend value against a literal the spec itself declares, staying green while the two
+  sides disagree. Read the four admission conditions in that README before writing a cross-side
+  contract test.