@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -2,18 +2,18 @@
 name: catalyst-nestjs-primitives
 description: >
   Catalog and guide for NestJS primitives in the Aurora Catalyst backend: custom decorators, guards,
-  interceptors, pipes, filters. Documents the three catalyst-authored primitives (`@Auth` composite
-  decorator, `AuthenticationJwtGuard`, `AuthorizationPermissionsGuard`), references upstream
-  primitives from `@aurorajs.dev/core-back` (`@Timezone`, `@Auditing`, `@CurrentAccount`,
-  `@ContentLanguage`, `@TenantPolicy`, `@TenantConstraint`, `Permissions`), the dual REST/GraphQL
+  interceptors, pipes, filters. Documents the five catalyst-authored primitives (`@Auth` composite
+  decorator, `AuthenticationJwtGuard`, `AuthorizationPermissionsGuard`, `@TenantConstraint`,
+  `@TenantPolicy`), references upstream primitives from `@aurorajs.dev/core-back` (`@Timezone`,
+  `@Auditing`, `@CurrentAccount`, `@ContentLanguage`, `Permissions`), the dual REST/GraphQL
   context pattern via `Api.getRequestFromExecutionContext()`, and the `dPermissions.all` convention
   on IamAccount. Trigger: writing or reasoning about a guard, interceptor, pipe, filter, or custom
   decorator; protecting an endpoint with auth and permission checks; composing a custom composite
-  decorator with `applyDecorators`; understanding why every catalyst guard overrides `getRequest`;
-  understanding how `user.dPermissions.all` is read at guard time; deciding between `@Auth` and a
-  custom guard. Fires even if the user says only "add auth to this endpoint" or "I need a guard for
-  X". Does NOT apply to field-level validation (use `catalyst-field-schema`) and does NOT replace
-  full-module audits (use `catalyst-review-module`).
+  decorator with `applyDecorators`; scoping a module by tenant; understanding why every catalyst
+  guard overrides `getRequest`; understanding how `user.dPermissions.all` is read at guard time;
+  deciding between `@Auth` and a custom guard. Fires even if the user says only "add auth to this
+  endpoint" or "I need a guard for X". Does NOT apply to field-level validation (use
+  `catalyst-field-schema`) and does NOT replace full-module audits (use `catalyst-review-module`).
 license: MIT
 metadata:
   author: aurora
@@ -33,9 +33,11 @@ Route every primitive task through one of these four branches.
 ```
 Need a NestJS primitive?
   │
-  ├── Does `@aurorajs.dev/core-back` already export it?   ───→ USE UPSTREAM
-  │   (@Timezone, @Auditing, @CurrentAccount,
-  │    @ContentLanguage, @TenantPolicy, @TenantConstraint, …)
+  ├── Does `@aurorajs.dev/core-back` already export it?   ───→ REUSE IT
+  │   (@Timezone, @Auditing, @CurrentAccount, @ContentLanguage — genuinely
+  │    upstream; @TenantConstraint, @TenantPolicy also resolve from this
+  │    specifier but are catalyst-authored, see the tables below — the
+  │    specifier is not proof of origin)
   │
   ├── Is the task "protect an endpoint with auth +       ───→ USE @Auth('<pkg>.<mod>.<op>')
   │   permission checks"?                                    (composite: Permissions +
@@ -73,13 +75,23 @@ reuse-first gate, and provides templates only as a last resort.
 | Primitive                       | Type                | Purpose                                                                                                                                                                                                                                                                                                 | Path                                                                            |
 | ------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | `@Auth(...permissions)`         | Composite decorator | Protects an endpoint via `Permissions(...)` metadata + `UseGuards(AuthenticationJwtGuard, AuthorizationPermissionsGuard)`. Canonical endpoint-protection decorator used on every resolver / controller.                                                                                                 | `backend/src/@aurora/decorators/auth.decorator.ts`                              |
-| `AuthenticationJwtGuard`        | Guard               | Extends passport's `AuthGuard('jwt')`. Overrides `getRequest()` via `Api.getRequestFromExecutionContext(context)` so it works in both REST (HTTP context) and GraphQL (execution context). Throws `UnauthorizedException` with `statusCode: 401` when the JWT is missing or invalid.                    | `backend/src/@app/authorization-code/guards/authentication-jwt.guard.ts`        |
-| `AuthorizationPermissionsGuard` | Guard               | Reads the `permissions` reflection metadata set by `Permissions(...)` (i.e., by `@Auth(...)`) and checks if the authenticated user's `dPermissions.all` intersects the required set via `Arr.intersects`. Same dual-context pattern. Throws `UnauthorizedException` with `statusCode: 403` on mismatch. | `backend/src/@app/authorization-code/guards/authorization-permissions.guard.ts` |
-
-That is the entire catalyst-authored primitive surface on disk today: one composite decorator and
-two guards. No custom pipes, interceptors, filters, or middleware exist in the repo. If a new
-pattern needs expressing, it is more likely a FieldSchema concern or belongs behind `@Auth` than a
-fresh primitive.
+| `AuthenticationJwtGuard`        | Guard               | Extends passport's `AuthGuard('jwt')`. Overrides `getRequest()` via `Api.getRequestFromExecutionContext(context)` so it works in both REST (HTTP context) and GraphQL (execution context). Throws `UnauthorizedException` with `statusCode: 401` when the JWT is missing or invalid.                    | `backend/src/@aurora/modules/authentication/infrastructure/guards/authentication-jwt.guard.ts`        |
+| `AuthorizationPermissionsGuard` | Guard               | Reads the `permissions` reflection metadata set by `Permissions(...)` (i.e., by `@Auth(...)`) and checks if the authenticated user's `dPermissions.all` intersects the required set via `Arr.intersects`. Same dual-context pattern. Throws `UnauthorizedException` with `statusCode: 403` on mismatch. | `backend/src/@aurora/modules/authentication/infrastructure/guards/authorization-permissions.guard.ts` |
+| `@TenantConstraint(...)`        | Method decorator    | Scopes a READ operation to the caller's tenant list: replaces the caller-supplied `constraint` argument with a server-composed one, AND-combined with whatever the caller sent. Fails closed. See "Tenant scoping" below.                                                                              | `packages/core-back/src/domain/decorators/tenant-constraint.decorator.ts`      |
+| `@TenantPolicy(...)`            | Method decorator    | Rejects a WRITE whose payload targets a tenant outside the caller's scope, before the wrapped method runs. Fails closed. See "Tenant scoping" below.                                                                                                                                                   | `packages/core-back/src/domain/decorators/tenant-policy.decorator.ts`         |
+
+That is the entire catalyst-authored primitive surface on disk today: one composite decorator, two
+guards, and two tenant-scoping decorators. No custom pipes, interceptors, filters, or middleware
+exist in the repo. If a new pattern needs expressing, it is more likely a FieldSchema concern or
+belongs behind `@Auth` than a fresh primitive.
+
+**`@TenantConstraint`/`@TenantPolicy` reach consumers through the `@aurorajs.dev/core-back`
+specifier, exactly like the upstream primitives below — but they are NOT upstream.** That specifier
+resolves to the workspace package `packages/core-back` (`backend/package.json`'s dependency is
+`workspace:*`), and these two decorators are catalyst's own addition to that package. Being
+reachable under an `@aurorajs.dev` import path does not make a primitive upstream; only the source
+directory does, which is why both rows above point at `packages/core-back/src/domain/decorators/`,
+never at an upstream release note.
 
 ## Inventory — Upstream primitives (`@aurorajs.dev/core-back`)
 
@@ -93,14 +105,124 @@ fresh primitive.
 | `@Auditing()`           | Param decorator — extracts auditing metadata (user id, timestamp, correlation id).                                                                                                   | `@aurorajs.dev/core-back` (`decorators`) |
 | `@CurrentAccount()`     | Param decorator — extracts the authenticated account object from the request.                                                                                                        | `@aurorajs.dev/core-back` (`decorators`) |
 | `@ContentLanguage()`    | Param decorator — extracts the content-language preference from the request.                                                                                                         | `@aurorajs.dev/core-back` (`decorators`) |
-| `@TenantPolicy()`       | Method / class decorator — enforces tenant write scope (use on mutations).                                                                                                           | `@aurorajs.dev/core-back` (`decorators`) |
-| `@TenantConstraint()`   | Method / class decorator — enforces tenant read scope (use on queries).                                                                                                              | `@aurorajs.dev/core-back` (`decorators`) |
 | `Permissions(...names)` | Metadata decorator — sets the `permissions` reflection key read by `AuthorizationPermissionsGuard`. Rarely used directly; prefer `@Auth(...)` composite which wires it consistently. | `@aurorajs.dev/core-back` (`decorators`) |
 
+`@TenantPolicy` and `@TenantConstraint` do NOT belong in this table: they do not exist in the
+upstream `@aurorajs.dev/core-back` release, only in this monorepo's own `packages/core-back` — see
+the catalyst-authored table above and the "Tenant scoping" section below.
+
 Everything not listed here that a catalyst resolver / controller uses (`@Args`, `@Body`,
 `@Mutation`, `@Query`, `@Resolver`, `@Controller`, `@Post`, `@Get`, `@Put`, `@Delete`, …) is
 standard NestJS and covered by the NestJS documentation. Do not duplicate NestJS docs here.
 
+## Tenant scoping — `@TenantConstraint` and `@TenantPolicy`
+
+Two method decorators in `packages/core-back/src/domain/decorators/` scope a generated module's
+reads and writes to the authenticated caller's tenant list. This section states the contract a
+consumer needs; the full behavioral contract (narrow-never-widen, the disjunction case, bulk-write
+rejection, both column shapes) is the `tenant-scope-decorators` capability spec — read it there, it
+is not restated here. That spec's path is state-dependent, so resolve it by which copy of this
+skill you are reading:
+
+- **This monorepo** — before the `add-tenant-scope-decorators` change archives, it lives at
+  `openspec/changes/add-tenant-scope-decorators/specs/tenant-scope-decorators/spec.md`; after
+  archive, the same capability moves to `openspec/specs/tenant-scope-decorators/spec.md`. If
+  neither resolves, search `openspec/` for the `tenant-scope-decorators` capability.
+- **A scaffolded project (`catalyst init`)** — this file is a packager-generated mirror
+  (`scripts/packager/`) and ships with NO `openspec/` directory at all, so neither path above will
+  EVER resolve there. **As of this writing, no PUBLISHED `@aurorajs.dev/core-back` release contains
+  these decorators** — the scaffold's `package.json` pins `^2.3.0`
+  (`packages/cli/src/templates/backend/application/package.json`), and the newest published version
+  that range resolves to (`2.4.0`, verified via `npm pack @aurorajs.dev/core-back@2.4.0` and
+  inspecting the tarball) ships no `tenant-policy.decorator.ts` / `tenant-constraint.decorator.ts`
+  at all. A scaffolded project's `node_modules/@aurorajs.dev/core-back` is therefore NOT an
+  authoritative source for this contract yet — pointing there leads nowhere. Until a future
+  core-back release publishes the decorators, treat `@TenantConstraint`/`@TenantPolicy` as
+  UNAVAILABLE in a scaffolded project and consult the monorepo source directly instead —
+  `packages/core-back/src/domain/decorators/tenant-policy.decorator.ts` and
+  `tenant-constraint.decorator.ts` — as the interim reference.
+
+**Arguments.** Both decorators take the tenant property name, the column shape, and the positional
+indices of the arguments they operate on. A generated module receives every one of these filled in
+explicitly by the generator — never relying on the defaults below, which exist only for a
+hand-written call site:
+
+| Decorator            | Options                                                                          | Defaults (hand-written call site only)          |
+| --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `@TenantConstraint()` | `accountIndex`, `constraintIndex`, `targetProperty`, `isArray`, `nullable`        | `accountIndex: 0`, `constraintIndex: 2`, `targetProperty: 'tenantId'`, `isArray: false`, `nullable: false` — matches `main(account, queryStatement, constraint, meta)` |
+| `@TenantPolicy()`     | `payloadIndex`, `accountIndex`, `targetProperty`, `isArray`, `requireProperty`    | `payloadIndex: 0`, `accountIndex: 1`, `targetProperty: 'tenantId'`, `isArray: false`, `requireProperty: true` — matches the payload-first `main(payload, account, meta?)`. `requireProperty: false` opts out of `TenantScopeMissingPropertyError` for a payload that omits the tenant property — the generator uses it on UPDATE (the row is already scoped by its existing tenant value), never on CREATE. |
+
+The generator emits different indices where the signature differs — `sum`/`max`/`min` put `field`
+at index 0, so their `@TenantConstraint(...)` carries `accountIndex: 1, constraintIndex: 3`.
+
+**The account is typed structurally.** Both decorators accept `{ dTenants: string[] }`
+(`TenantScopedAccount`, exported from `packages/core-back/src/domain/decorators/tenant-scope-account.ts`),
+never an IAM type. `packages/core-back` MUST NOT import IAM (HR-PORTS-001) — any object shaped like
+`{ dTenants: string[] }` satisfies the decorator, whatever the concrete account class the consuming
+backend actually passes (in this repo, `IamAccount` from `@api/graphql`).
+
+**Both fail closed.**
+
+- No principal at the declared `accountIndex` → an error naming the misconfiguration; the wrapped
+  method is NEVER invoked. This is a bug in the emitted code, not a caller mistake.
+- An account present with an EMPTY `dTenants` → NOT treated as "unrestricted". A read's predicate
+  matches no row (`in: []` / `overlap: []`); a write is rejected the same as any out-of-scope
+  payload.
+
+**The enforcement boundary is the transport layer, not the persistence layer.** Both decorators
+wrap a resolver/controller method — an internal caller that reaches the aggregate's application
+service or repository by another route (a cross-BC port, a hand-written flow that skips the
+generated endpoint) is **NOT** scoped by them. This is a deliberate design choice (design D6 of
+`add-tenant-scope-decorators`): tenant scoping is caller-DEPENDENT authorization, and the
+persistence layer has no caller to authorize. **Do not describe this mechanism as a persistence- or
+database-level guarantee** — it is not one, and documentation that implies otherwise misleads the
+next reader into trusting an internal call path these decorators never touch.
+
+### Inventory — every `hasTenant: true` module in this repository
+
+Measured directly against `cliter/*/*.aurora.yaml` and, where generated, the module's own
+`infrastructure/drizzle/*.schema.ts` — not recalled from memory.
+
+**No generated module runs with `hasTenant: true` today.** `business-partner-portal/partner-contact`
+was activated and measured in `add-tenant-scope-decorators`, then withdrawn: with `hasTenant: true`
+on that module, 0 of the 3 accounts holding `businessPartnerPortal.partnerContact.create` had the
+child tenant of either seeded business partner in their `dTenants` — every business partner creates
+a NEW child tenant, and `dTenants` is populated only when an account is created or updated, never by
+the token-issuance recompute path
+(`backend/src/@bridges/iam/account/adapters/iam-account-loader.adapter.ts`, the
+`refreshPermissions` option, which recomputes `dPermissions` only). So no existing account could
+ever see a business partner's own contacts. Activation is blocked on that `dTenants`-freshness gap,
+tracked as Backlog task **T-82**. `business-partner-portal/partner-contact.aurora.yaml` is back to
+`hasTenant: false`. The decorators, the generator's emission of them, and the generation-time
+validators are unaffected — they are the mechanism, ready for T-82 to flip the switch once
+`dTenants` is kept fresh.
+
+Two more modules declare the flag but are not generated into the backend at all, so the decorators
+never run for them either:
+
+| Bounded context          | Module          | Tenant property | YAML type                          | Drizzle column                                              | Generated into backend? |
+| ------------------------ | --------------- | ---------------- | ------------------------------------ | -------------------------------------------------------------- | -------------------------- |
+| `message`                | `inbox`          | `tenantIds`     | `array` (`arrayOptions.type: id`), `nullable: true` | — (not generated)                                              | No — `backend/src/@app/message` does not exist |
+| `message`                | `message`        | `tenantIds`     | `array` (`arrayOptions.type: id`), `nullable: true` | — (not generated)                                              | No — `backend/src/@app/message` does not exist |
+
+**A tenant COLUMN and the `hasTenant` SWITCH are independent — do not conflate them.** Several
+aggregates carry a tenant-shaped column while declaring `hasTenant: false`, so `@TenantConstraint`/
+`@TenantPolicy` are NOT applied to them even though the column exists:
+
+| Bounded context          | Module              | Tenant column                        | Generated into backend?                                                                                  |
+| ------------------------ | -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `reporting`              | `report`             | `tenantId`, nullable                   | Yes — `backend/src/@app/reporting/report/infrastructure/drizzle/reporting-drizzle-report.schema.ts:34` (`uuid('tenant_id')`, nullable) |
+| `business-partner-portal` | `business-partner`   | `tenantId`, NOT NULL                   | Yes — `backend/src/@app/business-partner-portal/business-partner/infrastructure/drizzle/business-partner-portal-drizzle-business-partner.schema.ts:20` (`uuid('tenant_id').notNull()`) |
+| `business-partner-portal` | `supplier-document`  | `tenantId`, NOT NULL                   | Yes — `backend/src/@app/business-partner-portal/supplier-document/infrastructure/drizzle/business-partner-portal-drizzle-supplier-document.schema.ts:26` (`uuid('tenant_id').notNull()`) |
+| `business-partner-portal` | `partner-contact`    | `tenantId`, NOT NULL                   | Yes — `backend/src/@app/business-partner-portal/partner-contact/infrastructure/drizzle/business-partner-portal-drizzle-partner-contact.schema.ts:22` (`uuid('tenant_id').notNull()`) |
+| `business-partner-portal` | `partner-address`    | `tenantId`, NOT NULL                   | No — `backend/src/@app/business-partner-portal/partner-address` does not exist                              |
+
+A schema in this second table is not scoped by these decorators at all — its column is plain data,
+filtered (if at all) by hand-written application logic, not by the generator's tenant mechanism.
+Flipping one of these to `hasTenant: true` requires its tenant property to resolve under the
+generator's exact-name predicate (`tenantId` then `tenantIds` — see D8 of
+`add-tenant-scope-decorators`), and regenerating the module.
+
 ## Dual REST/GraphQL Context Pattern (Catalyst-specific)
 
 Catalyst exposes every module over both REST and GraphQL. A guard, interceptor, or param decorator
@@ -116,7 +238,7 @@ Api.getRequestFromExecutionContext(context: ExecutionContext): Request
 
 It inspects the context type and returns the correct request object for either REST or GraphQL.
 Every catalyst guard overrides `getRequest()` to call it. The real shape, from
-`backend/src/@app/authorization-code/guards/authentication-jwt.guard.ts`:
+`backend/src/@aurora/modules/authentication/infrastructure/guards/authentication-jwt.guard.ts`:
 
 ```typescript
 import { Api } from '@aurorajs.dev/core-back';
@@ -177,7 +299,7 @@ it handles edge cases (empty arrays, non-array inputs) consistently.
 
 ## Anti-patterns
 
-1. **Writing a pipe for field-level validation.** → Use `@ApplySchema(FieldSchema)` from
+1. **Writing a pipe for field-level validation.** → Use `@ApplySchema({ schema, operation })` from
    `catalyst-field-schema`. The schema's `maxLength`, `nullable`, `enumOptions`, and `rules` already
    enforce what a pipe would re-implement. A pipe duplicates the check and drifts from the
    declarative contract.

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

@@ -89,6 +89,19 @@ freely.
 
 ---
 
+## `WrapperType<T>` on a decorated property typed with a class
+
+Use `WrapperType<T>` (imported from `@aurorajs.dev/core-back`) whenever a decorated property or
+constructor parameter is typed as another class that can sit on the other side of an import
+cycle — every relation-typed DTO property (`account?: WrapperType<IamAccountDto>`) is the
+recurring case, generated that way by the CLI templates. Reason: `emitDecoratorMetadata` reads a
+direct class reference eagerly into `design:type`, and native ESM's per-binding TDZ throws if the
+cycle has not finished evaluating; `WrapperType<T>` is an identity alias (`T` at compile time, `T`
+at runtime) that makes TypeScript emit `Object` instead. It changes nothing else — Swagger's own
+`@ApiProperty({ type: () => X })` factory is unaffected.
+
+---
+
 ## Where the `.module.ts` lives (composition root convention)
 
 NestJS `@Module()` declarations are **composition roots**, not domain code. They wire controllers
@@ -399,15 +412,45 @@ installed, list `cliter/`. To add a BC, create its `cliter/<bc>/` schemas and ru
 
 | Kind                     | Location                                                                            | Notes                                                                                                                                                                                                                                                                        |
 | ------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Unit `.spec.ts`          | Co-located next to the file under test (e.g. `handler.spec.ts` beside `handler.ts`) | Discovered by the default Jest config                                                                                                                                                                                                                                        |
+| Unit `.spec.ts`          | Co-located next to the file under test (e.g. `handler.spec.ts` beside `handler.ts`) | Discovered by `backend/vitest.config.ts`'s `include` glob                                                                                                                                                                                                                    |
 | App-level scaffold smoke | `backend/test/app.e2e-spec.ts`                                                      | Stays at `test/` root; not a BC acceptance test                                                                                                                                                                                                                              |
 | BC e2e / acceptance      | `backend/test/acceptance/<bounded-context>/`                                        | One folder per bounded context (or shared module) under test. Name it after the `cliter/<bc>` directory for Cliter-managed BCs (e.g. `o-auth`, `iam`, `hub`), or after the `@aurora`/`@app` module for hand-written features with no `cliter/` entry (e.g. `authentication`) |
 
 **Import style in acceptance tests**: use the `@`-aliases (`@api/`, `@app/`, `@aurora/`,
-`@bridges/`, `@config/`) for anything inside `src/@…/`. Both `test/jest-e2e.json` and
-`tsconfig.json` map these aliases to `src/@…/`, so the imports are location-independent — depth from
-`test/acceptance/<bc>/` does not matter. Only `src/app.module` and other top-level `src/` files that
-have no alias need a relative path (`../../../src/…`).
+`@bridges/`, `@config/`) for anything inside `src/@…/`. Both `backend/vitest.config.e2e.ts` (via
+the `vite-tsconfig-paths` plugin) and `tsconfig.json` map these aliases to `src/@…/`, so the
+imports are location-independent — depth from `test/acceptance/<bc>/` does not matter. Only
+`src/app.module` and other top-level `src/` files that have no alias need a relative path
+(`../../../src/…`).
+
+## Import specifiers — explicit, always
+
+Every relative or aliased specifier is explicit ESM: a FILE target ends in `.js`
+(`./tag.repository.js`), a BARREL directory target (one carrying an `index.ts`) ends in
+`/index.js` (`@app/iam/tag/index.js`, `./domain/index.js`). A bare package specifier
+(`@nestjs/common`, `rxjs`, `dayjs`) gains nothing — its own `exports` map resolves it. Node's ESM
+loader requires this form once a package declares `"type": "module"`; TypeScript under
+`module: nodenext` refuses to compile the extensionless form (`TS2307`) rather than silently
+resolving it.
+
+```typescript
+// Barrel target (directory carrying an index.ts)
+import { IamCreateTagService, IamFindTagByIdService } from '@app/iam/tag/index.js';
+
+// File target
+import { IamCreateTagHandler } from './iam-create-tag.handler.js';
+
+// Bare package — untouched
+import { EventEmitter2 } from '@nestjs/event-emitter';
+```
+
+This binds hand-written AND generated code identically: `catalyst generate` declares the full
+specifier at every template call site (golden rule 1 — the generator states what it wants, it
+never infers a barrel vs. a file from the bare path string), so a freshly generated module compiles
+under `nodenext` with no hand edit. `tsc` rejects a specifier missing its suffix in an
+`import`/`export` statement with `TS2307`/`TS2835`. A specifier written as a string argument
+(`vi.mock('…')`, `vi.importMock('…')`, `vi.importActual('…')`) is not checked by the compiler and
+takes the same explicit form by hand.
 
 ## Reference
 

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

@@ -159,21 +159,26 @@ longer wanted, that is a deliberate removal decision made by the team, not an au
 The BC's own `infrastructure/index.ts` / `shared/index.ts` barrels — AND the `@config` composition
 point — must **NEVER** import anything from a non-wired provider submodule. A barrel executes in FULL
 at import time — one re-export line, or one stray import in `@config`, silently reintroduces the SDK
-into every consumer. Guard this with a Jest test that makes the SDK module throw the instant it's
-required, then asserts importing the core barrels AND the composition point does not throw:
+into every consumer. Guard this with a Vitest test that makes the SDK module throw the instant it's
+imported, then asserts importing the core barrels AND the composition point does not throw:
 
 ```ts
 // storage-account-azure-sdk-isolation.spec.ts
-jest.mock('@azure/storage-blob', () => {
+vi.mock('@azure/storage-blob', () => {
   throw new Error('@azure/storage-blob must not be reachable through the storage-account BC core barrels');
 });
 
-it('does not pull @azure/storage-blob when importing the file-manager barrel', () => {
-  expect(() => require('@app/storage-account/file-manager')).not.toThrow();
-});
-
-it('does not pull @azure/storage-blob when importing the @config composition point', () => {
-  expect(() => require('@config/storage-account')).not.toThrow();
+describe('storage-account core barrels stay Azure-SDK-free', () => {
+  // Dynamic import, not require(): Vitest's require shim only resolves Node's own CJS
+  // extensions and does not know the `@app`/`@config` path aliases — both are
+  // vite-tsconfig-paths/esbuild concerns that only a real `import()` goes through.
+  it('does not pull @azure/storage-blob when importing the file-manager barrel', async () => {
+    await expect(import('@app/storage-account/file-manager/index.js')).resolves.toBeDefined();
+  });
+
+  it('does not pull @azure/storage-blob when importing the @config composition point', async () => {
+    await expect(import('@config/storage-account/index.js')).resolves.toBeDefined();
+  });
 });
 ```
 
@@ -190,7 +195,7 @@ observed to fail is not proof of anything.
 ## Testing the composition point
 
 Because the binding is hand-wired (fixed `useClass`, no env read), the spec is a plain import — no
-`jest.isolateModules` dance is needed (that machinery was for re-testing an env-frozen module value
+module-isolation dance is needed (that machinery was for re-testing an env-frozen module value
 per case; there is only one case now). Assert two things: (1) each token binds via `useClass` to the
 expected concrete class, and (2) constructing the bound classes never throws with no other-provider
 env/config present — proving the wired provider has no hidden dependency on the unwired one's
@@ -220,17 +225,15 @@ branch that could produce a mix).
 
 A full `app.listen()` boot needing Postgres/env is often unavailable in CI-less or sandboxed
 contexts. NestJS evaluates a `@Module()`'s `providers:` array (here, the spread of the binding array)
-at MODULE-DECORATION time — i.e. the instant the module FILE is `require`d, before any DI container
-starts. In principle that makes `require`-ing the composition root (with the SDK mocked to throw) an
-equivalent proof that boot never reaches an unwired provider's SDK. In practice, if the BC module
+at MODULE-DECORATION time — i.e. the instant the module FILE is imported, before any DI container
+starts. That makes dynamically `import()`-ing the composition root (with the SDK mocked to throw) an
+equivalent proof that boot never reaches an unwired provider's SDK, including when the BC module
 transitively imports `@aurora/shared.module` → `@aurora/modules/authentication` (any `@Auth`-guarded
-surface), this `require` fails in ts-jest for an UNRELATED reason: `jwks-rsa` ships ESM ts-jest cannot
-transform (see `catalyst-backend-testing` skill, "decorator-fires-in-TestingModule" family of
-gotchas, and memory `reference_jest_auth_esm_limitation`). When that happens, don't fight it — fall
-back to testing the composition point in isolation (previous section) plus the barrel-isolation test;
-together they cover the same property (the wired provider needs no other-provider config; the
-unwired provider's SDK is unreachable through the BC core or `@config`) without needing the full
-module graph to load under Jest.
+surface): Vitest resolves the real `jose`/`jwks-rsa` ESM chain natively, so that import needs no
+fallback. Prefer testing the composition point in isolation (previous section) plus the
+barrel-isolation test when the full module graph is not the property under test — together they
+cover the same property (the wired provider needs no other-provider config; the unwired provider's
+SDK is unreachable through the BC core or `@config`) with a narrower, faster suite.
 
 ## Checklist for adopting or adding a provider (e.g. switching to Azure, or adding AWS S3)